Provenance & the verification seal

A provenance seal (the Polymer Partner seal) lets a shopper confirm that the store they are on is a genuine, currently-authorized partner of a supplier — and, optionally, that a specific lot was really supplied to that partner with approved documentation. The trust model lives in the data, not the badge: a retailer page can display any image it likes, but the only thing that decides “verified” is a server-side registry record that the retailer does not control.

This is a platform capability, exposed for RUO Pro stores that source from a participating supplier. The registry is owned by the provenance module.

What a partner seal actually asserts

The seal makes a narrow, checkable claim:

• A recorded business relationship between a supplier and a retailer, in a named status (active or not).
• A verified domain — the relationship is bound to specific hostnames the supplier (or the merchant, via self-serve verification) has proven control of. A copied badge on some other domain resolves to nothing.
• Optionally, a lot — that a specific lot id was supplied to that partner, with an approved documentation (COA) link.

It is deliberately not a blanket endorsement of the retailer, every product it sells, or the physical item in a buyer’s hands. The seal confirms the relationship and its recorded sourcing scope, and nothing more.

Fail-closed by construction

The registry is server-side truth, and every path that cannot produce a genuine positive shapes to a non-positive answer:

• An unknown host, an unverified domain row, a suspended partner, or a revoked lot all resolve to unknown / inactive / unavailable.
• An unknown domain learns nothing about who is a partner — the response carries an empty name, never a leak of the registry’s contents.
• A lot result never exceeds the partner result: without an active partner match, a lot query returns unavailable, not a decided no_match.
• A failed read (registry or DNS unreachable) is a real error status, never an “unknown partner” the widget would present as a decided negative. Unknown and absent stay different types, per the platform’s honest-absence rule.

Verification status is never accepted from an embed attribute, a query parameter, or any retailer-supplied data — the only way to produce partner.status: "active" is a verified domain row belonging to an active partner.

The public verification endpoint

One public, unauthenticated, tenant-scoped read backs the seal. CORS is open (access-control-allow-origin: *) on purpose: the response is public consumer-facing registry data, carries no credentials, and its trust binding is in the payload — partner.domain must equal the embedding page’s hostname, so the widget refuses a response served to any other site. An Origin header would prove nothing, so restricting it would add no integrity, only breakage.

GET https://api.ruo.pro/provenance/v1/{supplier}/partner-verification?domain={hostname}[&lot={lot-id}]

• {supplier} — the supplier’s registry (a tenant ref).
• domain — the hostname being checked (required). It is normalized the way registry rows are stored (trimmed, lowercased, port and trailing dot stripped); an invalid hostname is a 400, never a registry miss.
• lot — an optional lot id to confirm against the partner’s supply records.

Responses carry a short, honest freshness window: expiresAt is roughly five minutes out, and a cached positive must go stale quickly.

Example — a verified partner, with a confirmed lot

GET /provenance/v1/acme-labs/partner-verification?domain=shop.example.com&lot=LOT-2291 HTTP/1.1
Host: api.ruo.pro

{
  "partner": {
    "status": "active",
    "name": "Example Retail Co.",
    "domain": "shop.example.com",
    "scope": "Finished-goods reseller, North America"
  },
  "expiresAt": "2026-09-14T18:35:00.000Z",
  "canonicalUrl": "https://api.ruo.pro/provenance/v1/acme-labs/verify/example-retail",
  "lot": {
    "status": "confirmed",
    "id": "LOT-2291",
    "material": "Reference compound A",
    "suppliedTo": "Example Retail Co.",
    "documentationUrl": "https://…/coa/LOT-2291.pdf"
  }
}

An unknown or unverified domain returns the same shape with partner.status: "unknown", an empty name, and canonicalUrl: null — it reveals nothing about the registry. A queried lot with no active partner match comes back { "status": "unavailable", "id": "…" }.

The fields

How a storefront surfaces “verified” state

There are two supported ways to show the seal, and both talk to the same endpoint:

1. The embeddable seal script. A retailer page includes the supplier’s widget, which derives its API and canonical origin from its own src, so it only ever talks to the registry that served it:

   <script src="https://api.ruo.pro/provenance/v1/acme-labs/widget.js" defer></script>

   The widget calls partner-verification with its own page hostname as domain, validates the response hard (domain echo, status enums, a future expiresAt, suppliedTo === partner.name on confirmed lots), and renders the verified state only when all of that holds.

2. A “verify this site” checker, from the other direction — on the supplier’s own site, or anywhere trust matters. Take a user-entered URL, send new URL(input).hostname as domain=, render partner.status, and link canonicalUrl. No key needed; don’t cache positives beyond expiresAt.

Either way, the badge itself is inert. The canonical record is the independent artifact a copied badge cannot fake:

GET https://api.ruo.pro/provenance/v1/{supplier}/verify/{partnerRef}

It returns a plain HTML page with the partner’s current status, sourcing scope, approved domains, and the timestamp the record was checked — status, scope, domains, and nothing else (no prices, volumes, or private commercial terms).

Keeping “verified” honest over time

A verified domain is never verified-forever. A background re-verification sweep re-validates verified domains roughly every six hours:

• A DCV (TXT-challenge) domain must still publish its issued token.
• A platform domain (a verified storefront domain of the linked merchant) must still be a verified storefront domain of that merchant.

A single miss only bumps a streak — DNS blips are real. Three sustained misses lapse the row (an audited provenance.domain.lapsed), after which the seal stops resolving positive for that host. A check that cannot complete is recorded as “could not check” and fails the sweep honestly, rather than reading as a clean pass. A pending DCV claim whose token appears is verified automatically.

Reporting a discrepancy

The seal carries a public report flow for consumers who spot something wrong (a mismatched product, a lot that will not confirm, an identity concern):

POST https://api.ruo.pro/provenance/v1/{supplier}/reports
{ "domain": "…", "issue": "product_mismatch", "details": "…", "lot": "…" }

issue is a closed vocabulary (website_identity, product_mismatch, lot_not_found, documentation); details is capped at 1500 characters; the endpoint is per-IP rate-limited (5/hour, fail-closed) and solicits no PII. It returns a public reference (RPT-XXXXXXXX) for follow-up.

Related

• Tenancy — credential-carries-ownership, and the fail-closed host-resolution rule the platform-domain check reuses.
• Manifest & sections — how a store authors what renders, including a COA/provenance block.