@authorizedretailers/spec 0.1.1 → 0.2.0

package/README.md

@@ -1,19 +1,20 @@
 # authorized-retailers.json
 
-An open standard for brands to publish which retailers they have authorized, and for software to check a seller against that list.
+An open format with a single registry, for brands to record which retailers they have authorized and for software to check a seller against that record.
 
-> **Status: draft v0.1.** Breaking changes are possible before v1.0. See [GOVERNANCE.md](GOVERNANCE.md) for how changes are made.
+> **Status: draft v0.2.** Breaking changes are possible before v1.0. See [GOVERNANCE.md](GOVERNANCE.md) for how changes are made.
 
-The standard answers one question: has this brand authorized this seller, on this channel, in this territory, for this product line, as of this date? The format is built for AI shopping agents to check before they recommend or buy, and is ready for them as they adopt it. It works just as well for marketplaces, brand protection teams and anyone else who needs the answer.
+The standard answers one question: has this brand authorized this seller, on this channel, in this territory, for this product, as of this date? Built for AI shopping agents to check before they recommend or buy. It works just as well for marketplaces, brand protection teams and anyone else who needs the answer.
 
-- **Read the spec:** [`spec/spec-v0.1.md`](spec/spec-v0.1.md), also at [authorizedretailers.ai/spec](https://authorizedretailers.ai/spec)
-- **Reference registry:** [authorizedretailers.ai](https://authorizedretailers.ai)
+- **Read the spec:** [`spec/spec-v0.2.md`](spec/spec-v0.2.md), also at [authorizedretailers.ai/spec](https://authorizedretailers.ai/spec)
+- **The registry:** [authorizedretailers.ai](https://authorizedretailers.ai). The registry currently lists US channels. Other countries are coming.
 
 ## Core principles
 
-- **Every authorization comes from the brand.** No one else can authorize a retailer: not a distributor, not a retailer and not the registry.
+- **Every authorization comes from the brand.** No one else can authorize a retailer: not a distributor, not a retailer and not the registry. The registry confirms the brand controls its domain, publishes the brand's list and signs it. It never changes a list on its own. The signature says who published the list, not who is authorized.
 - **Distributors can propose, only the brand approves.** A proposal changes nothing until the brand says yes.
-- **Authorization is scoped and expires.** Each one names its channels, territories and product lines, and lapses unless the brand reconfirms it.
+- **Authorization is scoped.** Each authorization names its channels and territories and the product lines or products it covers. It lasts until the brand revokes it, or until an end date if the brand sets one.
+- **One source of truth.** authorizedretailers.ai is the only registry. An answer counts only if it verifies against the registry's published keys. Anyone may cache or relay signed answers, but no one else can issue them.
 - **Authorization is not authenticity.** An answer says what the brand has approved. It does not say whether any item is genuine.
 - **The registry doesn't rule on pricing.** Pricing and commercial terms are between the brand and its retailers.
 - **Listing is free.** Brands publish and retailers are listed at no cost.
@@ -23,69 +24,70 @@ The standard answers one question: has this brand authorized this seller, on thi
 
 | You are | You use it to |
 | --- | --- |
-| A brand | Publish which retailers you've authorized, where and for what |
-| A retailer | Show that the brands you sell have authorized you, and see how you're listed |
+| A brand | Record which retailers you've authorized, where and for which products |
 | An agent builder | Check a seller before recommending or buying, with an answer you can verify |
 
-## Publish a file (brands)
+## Register a brand
 
-A brand verifies control of its domain with a registry, which signs its list. The brand then serves a file at:
+A brand keeps its catalog and authorizations on the registry, which signs its list. The list lives on the registry, so it is always current. The brand proves it controls its domain with a DNS TXT record, which works on every site platform:
 
 ```
-https://<brand-domain>/.well-known/authorized-retailers.json
+authorizedretailers-verify=<token from the registry>
 ```
 
-The file takes one of three forms:
-
-| Form | What it holds | Use when |
-| --- | --- | --- |
-| `full` | The complete signed list | You want your list public |
-| `pointer` | A URL to your signed list on a registry | You want the file to stay current without re-uploading |
-| `private` | Your identity and a verify endpoint, no retailers | You don't want your distribution network public |
+A brand that can serve files under `/.well-known/` may also serve a pointer, or use one in place of the DNS record:
 
-Only files signed by a registry count. An unsigned file is well formed but treated as no file (spec section 5). The simplest choice is the `pointer` form:
+```
+https://<brand-domain>/.well-known/authorized-retailers.json
+```
 
 ```json
 {
-  "spec": "authorized-retailers/0.1",
+  "spec": "authorized-retailers/0.2",
   "form": "pointer",
   "brand": { "name": "Example Brand", "domain": "brand.example" },
+  "verify_token": "<token from the registry>",
   "list": "https://authorizedretailers.ai/v0/brands/brand.example/list"
 }
 ```
 
-## Validate a file
+The pointer holds no authorization data, so it never goes out of date. The token is public: it proves control only of the domain it was issued for. The registry checks the DNS record or pointer regularly. If both are removed, the brand's list stops counting until one is restored. The pointer itself is not signed. The list it names is, and so is every answer from the verify endpoint.
+
+## Validate a pointer and a list
 
 ```bash
 npm install @authorizedretailers/spec
 ```
 
-```ts
-import { validateFile, validAuthorizations } from "@authorizedretailers/spec";
+```js
+import { validateFile, checkPublishedList, validAuthorizations } from "@authorizedretailers/spec";
 
-const result = validateFile(file);
-if (!result.valid) console.log(result.errors);
-else if (result.value.form === "full") {
-  const current = validAuthorizations(result.value); // an expired file yields none
-}
-```
-
-To accept a file you fetched, check its signature and that it vouches for the domain it came from:
+// The registry's public keys. Fetch once and cache.
+const jwks = await fetch("https://authorizedretailers.ai/.well-known/jwks.json").then((r) => r.json());
 
-```ts
-import { checkPublishedFile } from "@authorizedretailers/spec";
+const pointer = await fetch("https://brand.example/.well-known/authorized-retailers.json").then((r) => r.json());
+const file = validateFile(pointer, "brand.example");
+if (!file.valid) console.log(file.errors);
 
-const check = await checkPublishedFile("brand.example", file, jwks);
+// Fetch the signed list the pointer names, then check it.
+const list = await fetch(file.value.list).then((r) => r.json());
+const check = await checkPublishedList("brand.example", list, jwks);
 // { counts: true, kid } or { counts: false, reason }
+
+if (check.counts && list.public) {
+  const current = validAuthorizations(list); // leaves out authorizations past their end date
+}
 ```
 
+A brand with only a DNS record has no pointer. Its list is at the same registry URL: `https://authorizedretailers.ai/v0/brands/<domain>/list`.
+
 The package works in Node 20+, Cloudflare Workers, Deno and browsers. It uses only Web Crypto, makes no network calls and sends no telemetry.
 
 ## Verify a signed registry answer (agent builders)
 
-Ask a registry whether a seller is authorized, then verify the answer against the registry's published keys:
+Ask the registry whether a seller is authorized, then verify the answer against the registry's published keys (`jwks`, fetched above):
 
-```ts
+```js
 import { verifyDocument } from "@authorizedretailers/spec";
 
 const answer = await fetch("https://authorizedretailers.ai/v0/verify", {
@@ -93,35 +95,52 @@ const answer = await fetch("https://authorizedretailers.ai/v0/verify", {
   headers: { "Content-Type": "application/json" },
   body: JSON.stringify({
     brand_domain: "brand.example",
-    channel: { type: "amazon", marketplace: "US", seller_id: "A1B2C3D4E5F6G7" },
-    territory: "US",
+    channel: { type: "amazon", domain: "amazon.com", seller_id: "A1B2C3D4E5F6G7" },
+    // Optional:
+    territory: "US",                  // defaults to the domain's country
+    product: { asin: "B0EXAMPLE1" },  // or { gtin: "00012345678905" } for UPC or EAN
+    as_of: "2026-09-28",              // defaults to now
   }),
 }).then((r) => r.json());
 
-const jwks = await fetch("https://authorizedretailers.ai/.well-known/jwks.json").then((r) => r.json());
-const check = await verifyDocument(answer, jwks);
+const verified = await verifyDocument(answer, jwks);
 // { valid: true, kid } or { valid: false, reason }
 ```
 
-The verifier rejects keys no longer in the key set and answers past their `valid_until`. On `unknown_kid`, fetch the key set again once. Match sellers on the identifier you see, never on a retailer name: `channelKey()` normalizes identifiers so every reader agrees.
+Marketplace channels are identified by their domain and seller ID, and web stores by their domain. A marketplace domain sets the territory (amazon.com is US, amazon.ca is CA), and a request for a different territory is answered `unlisted`. Product is optional: ask with a GTIN or, on Amazon, an ASIN. Authorization is decided per seller first, then checked against the product lines or products the brand has authorized. Every answer that includes a product says whether it is in the brand's catalog. A product that isn't may be a duplicate listing.
+
+The verifier rejects keys no longer in the key set and answers past their `valid_until` (15 minutes). On `unknown_kid`, fetch the key set again once. Match sellers on the identifier you see, never on a retailer name: `channelKey()` normalizes identifiers so every reader agrees.
+
+If the registry is unreachable, never treat a seller as authorized without a current answer. Between `valid_until` and `stale_until` (24 hours) you may use an answer you already hold, marked as stale, after checking it against the revocation feed: `verifyDocument(answer, jwks, { allowStale: true, revocationFeed })`. Otherwise the seller is unconfirmed (spec section 10.2).
+
+## Upgrading from 0.1
+
+- `full` and `private` files are gone. Replace any `/.well-known/authorized-retailers.json` with a pointer, or remove it and rely on the DNS record.
+- The hosted `authorized-retailers-verify.txt` file is gone. Use the DNS record or the pointer's `verify_token`.
+- Marketplace channels use `domain` (`amazon.com`) instead of `marketplace` (`US`). The old field is rejected.
+- `brand_unverified` is now `brand_not_registered`.
+- Authorizations have no default expiry. `valid_until` is 15 minutes, with `stale_until` for outages.
+- `validateFullFile` is replaced by `validateList`, and `checkPublishedFile` by `checkPublishedList`. `validateFile` validates pointers only and takes the domain it was fetched from.
 
 ## What's in this repository
 
 | Path | What |
 | --- | --- |
-| `spec/` | The specification |
-| `schemas/` | JSON Schemas (draft 2020-12) for the three file forms and the verify request and response |
-| `fixtures/` | Valid and invalid examples, with `manifest.json` saying what each should produce. Usable as a conformance suite |
-| `src/` | Types, validator, identifier matching, RFC 8785 canonicalization (JCS) and detached EdDSA JWS signing and verification |
+| `spec/` | The specification, every version |
+| `schemas/` | JSON Schemas (draft 2020-12) for the pointer file, the signed list, the revocation feed and the verify request and response, one folder per version |
+| `fixtures/` | Valid and invalid examples and matching cases, with `manifest.json` saying what each should produce. Usable as a conformance suite |
+| `src/` | Types, validator, identifier, territory and product matching, RFC 8785 canonicalization (JCS) and detached EdDSA JWS signing and verification |
 | `test/` | Tests for all of the above |
 | `docs/MUST-coverage.md` | Every MUST in the spec and where it is tested |
 
-Anyone may run a registry that implements this standard. See [TRADEMARKS.md](TRADEMARKS.md) for how to describe it.
+authorizedretailers.ai is the only registry. Anyone may build on the standard and cache or relay signed answers, but only answers signed with the registry's published keys count. See [TRADEMARKS.md](TRADEMARKS.md).
 
 ## Feedback
 
 Send feedback on the spec at [authorizedretailers.ai/spec](https://authorizedretailers.ai/spec#feedback). This repository doesn't accept pull requests. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
+Use of the registry is subject to the terms at authorizedretailers.ai/terms.
+
 ## License
 
 - The specification and documents in `spec/` and `docs/`: [CC BY 4.0](LICENSE-SPEC)

package/dist/constants.d.ts

@@ -1,6 +1,25 @@
-/** Section 10: maximum expiry is 180 days from issue. */
-export declare const MAX_EXPIRY_MS: number;
-/** Section 10: recommended default expiry. */
-export declare const DEFAULT_EXPIRY_MS: number;
-/** Section 9: a verify answer's valid_until is at most 24 hours after checked. */
-export declare const MAX_ANSWER_VALIDITY_MS: number;
+import type { MarketplaceChannelType } from "./types.js";
+/** Section 10.1: a signed list's or answer's valid_until is at most 15 minutes after it was issued. */
+export declare const MAX_VALIDITY_MS: number;
+/** Section 10.2: stale_until is at most 24 hours after issue. */
+export declare const MAX_STALE_MS: number;
+/** Section 10: the verify API reflects a revocation within this long. */
+export declare const REVOCATION_MAX_DELAY_MS: number;
+/** Section 5.1: readers may follow this many HTTPS redirects when fetching a pointer. */
+export declare const MAX_POINTER_REDIRECTS = 3;
+/** Section 5.1: a pointer's list URL must be on this origin. */
+export declare const REGISTRY_ORIGIN = "https://authorizedretailers.ai";
+export declare const REGISTRY_JWKS_URL = "https://authorizedretailers.ai/.well-known/jwks.json";
+export declare const REGISTRY_REVOCATIONS_URL = "https://authorizedretailers.ai/v0/revocations";
+/** Section 10.2: mirror base URLs. None yet; listed here and in the spec when they launch. */
+export declare const MIRRORS: readonly string[];
+/** Section 4: the DNS TXT record value prefix. */
+export declare const DNS_VERIFY_PREFIX = "authorizedretailers-verify=";
+export declare const POINTER_PATH = "/.well-known/authorized-retailers.json";
+/** Section 6: marketplace domains, their channel type and country. */
+export declare const MARKETPLACE_DOMAINS: Readonly<Record<string, {
+    type: MarketplaceChannelType;
+    country: string;
+}>>;
+/** Section 6.2: two-letter domain endings widely used as generic domains, so they imply no territory. */
+export declare const GENERIC_CCTLDS: ReadonlySet<string>;

package/dist/constants.js

@@ -1,7 +1,41 @@
-const DAY_MS = 24 * 60 * 60 * 1000;
-/** Section 10: maximum expiry is 180 days from issue. */
-export const MAX_EXPIRY_MS = 180 * DAY_MS;
-/** Section 10: recommended default expiry. */
-export const DEFAULT_EXPIRY_MS = 90 * DAY_MS;
-/** Section 9: a verify answer's valid_until is at most 24 hours after checked. */
-export const MAX_ANSWER_VALIDITY_MS = DAY_MS;
+const MINUTE_MS = 60 * 1000;
+const HOUR_MS = 60 * MINUTE_MS;
+/** Section 10.1: a signed list's or answer's valid_until is at most 15 minutes after it was issued. */
+export const MAX_VALIDITY_MS = 15 * MINUTE_MS;
+/** Section 10.2: stale_until is at most 24 hours after issue. */
+export const MAX_STALE_MS = 24 * HOUR_MS;
+/** Section 10: the verify API reflects a revocation within this long. */
+export const REVOCATION_MAX_DELAY_MS = MINUTE_MS;
+/** Section 5.1: readers may follow this many HTTPS redirects when fetching a pointer. */
+export const MAX_POINTER_REDIRECTS = 3;
+/** Section 5.1: a pointer's list URL must be on this origin. */
+export const REGISTRY_ORIGIN = "https://authorizedretailers.ai";
+export const REGISTRY_JWKS_URL = `${REGISTRY_ORIGIN}/.well-known/jwks.json`;
+export const REGISTRY_REVOCATIONS_URL = `${REGISTRY_ORIGIN}/v0/revocations`;
+/** Section 10.2: mirror base URLs. None yet; listed here and in the spec when they launch. */
+export const MIRRORS = [];
+/** Section 4: the DNS TXT record value prefix. */
+export const DNS_VERIFY_PREFIX = "authorizedretailers-verify=";
+export const POINTER_PATH = "/.well-known/authorized-retailers.json";
+/** Section 6: marketplace domains, their channel type and country. */
+export const MARKETPLACE_DOMAINS = {
+    "amazon.com": { type: "amazon", country: "US" },
+    "amazon.ca": { type: "amazon", country: "CA" },
+    "amazon.co.uk": { type: "amazon", country: "GB" },
+    "amazon.de": { type: "amazon", country: "DE" },
+    "amazon.fr": { type: "amazon", country: "FR" },
+    "amazon.it": { type: "amazon", country: "IT" },
+    "amazon.es": { type: "amazon", country: "ES" },
+    "amazon.com.au": { type: "amazon", country: "AU" },
+    "walmart.com": { type: "walmart", country: "US" },
+    "walmart.ca": { type: "walmart", country: "CA" },
+    "ebay.com": { type: "ebay", country: "US" },
+    "ebay.co.uk": { type: "ebay", country: "GB" },
+    "ebay.ca": { type: "ebay", country: "CA" },
+    "ebay.de": { type: "ebay", country: "DE" },
+    "ebay.com.au": { type: "ebay", country: "AU" },
+};
+/** Section 6.2: two-letter domain endings widely used as generic domains, so they imply no territory. */
+export const GENERIC_CCTLDS = new Set([
+    "ac", "ai", "cc", "co", "fm", "gg", "io", "la", "ly", "me", "sh", "so", "to", "tv", "vc", "ws",
+]);

package/dist/identity.d.ts

@@ -1,27 +1,42 @@
-import type { Authorization, Channel, FullFile } from "./types.js";
+import type { Authorization, Channel, MarketplaceChannel } from "./types.js";
+/** Section 6: lowercase, no trailing dot, no leading "www.". */
 export declare function normalizeDomain(domain: string): string;
+/** Uppercases and maps common aliases (UK) to ISO 3166-1 alpha-2 (GB). */
 export declare function normalizeCountry(code: string): string;
+export declare function isCountryCode(code: string): boolean;
+export declare function isMarketplaceDomain(domain: string): boolean;
 /**
- * The identity an agent matches on (section 6: match on the channel identifier, never the
- * retailer name). Returns null for physical channels, which agents cannot verify.
+ * Section 6.2: the country a domain implies. A marketplace domain's country from the table, a
+ * country-code domain's country (".co.uk" is GB), or null for a generic domain (".com", ".io").
  */
-export declare function channelKey(channel: Channel): string | null;
-/** Authorizations naming this channel. Matching uses channelKey only; retailer names are ignored. */
-export declare function authorizationsForChannel(authorizations: Authorization[], channel: Channel): Authorization[];
+export declare function territoryForDomain(domain: string): string | null;
+/**
+ * Section 6.2: the territories one channel of an authorization covers. A marketplace channel covers
+ * only its domain's country, and only if the scope (when given) allows it. A web store covers
+ * scope.territories when given, otherwise its domain's country. An empty result means none: a
+ * marketplace country the scope leaves out, or a generic-domain web store with no territories.
+ */
+export declare function effectiveTerritories(authorization: Authorization, channel: Channel): string[];
+/** Whether a channel of an authorization covers a territory. */
+export declare function coversTerritory(authorization: Authorization, channel: Channel, territory: string): boolean;
 /**
- * The authorizations a reader may rely on at `now`. Section 5: an expired file contains no valid
- * authorizations. Individually expired authorizations are dropped too.
+ * Section 6.1: the identity an agent matches on (never the retailer name). Domains are normalized;
+ * Amazon seller IDs are uppercased, eBay user IDs lowercased and Walmart partner IDs kept as they are.
  */
-export declare function validAuthorizations(file: FullFile, now?: number): Authorization[];
+export declare function channelKey(channel: Channel): string;
+/** The marketplace channel's type as its domain implies, or null for a non-marketplace domain. */
+export declare function marketplaceTypeForDomain(domain: string): MarketplaceChannel["type"] | null;
+/** Authorizations naming this channel. Matching uses channelKey only; retailer names are ignored. */
+export declare function authorizationsForChannel(authorizations: Authorization[], channel: Channel): Authorization[];
 /**
  * Brings raw agent input into the canonical form validateVerifyRequest expects: trims strings,
- * lowercases domains (dropping "www."), uppercases country codes. Leaves unexpected shapes alone
- * so the validator reports them.
+ * lowercases domains (dropping "www."), uppercases country codes and ASINs, maps "UK" to "GB" and
+ * strips spaces and dashes from GTINs. Leaves unexpected shapes alone so the validator reports them.
  */
 export declare function normalizeVerifyRequest(input: unknown): unknown;
 /**
- * Canonical form of a channel as typed by a person or agent: trims, lowercases the type and
- * domains (dropping "www."), uppercases country codes. Unexpected shapes pass through untouched.
- * Identifier case is kept; channelKey decides how case compares.
+ * Canonical form of a channel as typed by a person or agent: trims, lowercases the type and domain
+ * (dropping "www."). Seller ID case is kept; channelKey decides how case compares.
  */
 export declare function normalizeChannel(input: unknown): unknown;
+export declare function isRecord(v: unknown): v is Record<string, unknown>;

package/dist/identity.js

@@ -1,55 +1,92 @@
-import { parseTimestamp } from "./timestamp.js";
-/** Marketplace codes some platforms use in place of ISO 3166-1 alpha-2. */
-const MARKETPLACE_ALIASES = { UK: "GB" };
+import { GENERIC_CCTLDS, MARKETPLACE_DOMAINS } from "./constants.js";
+import { common } from "./schemas.js";
+/** ISO 3166-1 alpha-2 codes, from the schema so the two can't disagree. */
+const ISO_COUNTRIES = new Set(common.$defs.countryCode.enum);
+/** Codes people commonly type in place of ISO 3166-1 alpha-2. Schemas accept only the ISO code. */
+const COUNTRY_ALIASES = { UK: "GB" };
+/** Section 6: lowercase, no trailing dot, no leading "www.". */
 export function normalizeDomain(domain) {
     return domain.trim().toLowerCase().replace(/\.$/, "").replace(/^www\./, "");
 }
+/** Uppercases and maps common aliases (UK) to ISO 3166-1 alpha-2 (GB). */
 export function normalizeCountry(code) {
     const upper = code.trim().toUpperCase();
-    return MARKETPLACE_ALIASES[upper] ?? upper;
+    return COUNTRY_ALIASES[upper] ?? upper;
+}
+export function isCountryCode(code) {
+    return ISO_COUNTRIES.has(code);
+}
+export function isMarketplaceDomain(domain) {
+    return Object.hasOwn(MARKETPLACE_DOMAINS, normalizeDomain(domain));
+}
+/**
+ * Section 6.2: the country a domain implies. A marketplace domain's country from the table, a
+ * country-code domain's country (".co.uk" is GB), or null for a generic domain (".com", ".io").
+ */
+export function territoryForDomain(domain) {
+    const d = normalizeDomain(domain);
+    const market = MARKETPLACE_DOMAINS[d];
+    if (market)
+        return market.country;
+    const tld = d.slice(d.lastIndexOf(".") + 1);
+    if (tld.length !== 2 || GENERIC_CCTLDS.has(tld))
+        return null;
+    const country = tld === "uk" ? "GB" : tld.toUpperCase();
+    return ISO_COUNTRIES.has(country) ? country : null;
 }
 /**
- * The identity an agent matches on (section 6: match on the channel identifier, never the
- * retailer name). Returns null for physical channels, which agents cannot verify.
+ * Section 6.2: the territories one channel of an authorization covers. A marketplace channel covers
+ * only its domain's country, and only if the scope (when given) allows it. A web store covers
+ * scope.territories when given, otherwise its domain's country. An empty result means none: a
+ * marketplace country the scope leaves out, or a generic-domain web store with no territories.
+ */
+export function effectiveTerritories(authorization, channel) {
+    const listed = authorization.scope.territories;
+    const own = territoryForDomain(channel.domain);
+    if (channel.type !== "web") {
+        if (own === null)
+            return [];
+        return !listed || listed[0] === "*" || listed.includes(own) ? [own] : [];
+    }
+    if (listed)
+        return listed;
+    return own === null ? [] : [own];
+}
+/** Whether a channel of an authorization covers a territory. */
+export function coversTerritory(authorization, channel, territory) {
+    const t = effectiveTerritories(authorization, channel);
+    return t[0] === "*" || t.includes(territory);
+}
+/**
+ * Section 6.1: the identity an agent matches on (never the retailer name). Domains are normalized;
+ * Amazon seller IDs are uppercased, eBay user IDs lowercased and Walmart partner IDs kept as they are.
  */
 export function channelKey(channel) {
+    const domain = normalizeDomain(channel.domain);
     switch (channel.type) {
         case "amazon":
-            return `amazon:${normalizeCountry(channel.marketplace)}:${channel.seller_id.trim().toUpperCase()}`;
+            return `amazon:${domain}:${channel.seller_id.trim().toUpperCase()}`;
         case "walmart":
-            return `walmart:${normalizeCountry(channel.marketplace)}:${channel.seller_id.trim()}`;
+            return `walmart:${domain}:${channel.seller_id.trim()}`;
         case "ebay":
-            return `ebay:${normalizeCountry(channel.marketplace)}:${channel.seller_id.trim().toLowerCase()}`;
+            return `ebay:${domain}:${channel.seller_id.trim().toLowerCase()}`;
         case "web":
-            return `web:${normalizeDomain(channel.domain)}`;
-        case "physical":
-            return null;
+            return `web:${domain}`;
     }
 }
+/** The marketplace channel's type as its domain implies, or null for a non-marketplace domain. */
+export function marketplaceTypeForDomain(domain) {
+    return MARKETPLACE_DOMAINS[normalizeDomain(domain)]?.type ?? null;
+}
 /** Authorizations naming this channel. Matching uses channelKey only; retailer names are ignored. */
 export function authorizationsForChannel(authorizations, channel) {
     const key = channelKey(channel);
-    if (key === null)
-        return [];
     return authorizations.filter((a) => a.channels.some((c) => channelKey(c) === key));
 }
-/**
- * The authorizations a reader may rely on at `now`. Section 5: an expired file contains no valid
- * authorizations. Individually expired authorizations are dropped too.
- */
-export function validAuthorizations(file, now = Date.now()) {
-    const fileExpires = parseTimestamp(file.expires);
-    if (fileExpires === null || now >= fileExpires)
-        return [];
-    return file.authorizations.filter((a) => {
-        const exp = parseTimestamp(a.expires);
-        return exp !== null && now < exp;
-    });
-}
 /**
  * Brings raw agent input into the canonical form validateVerifyRequest expects: trims strings,
- * lowercases domains (dropping "www."), uppercases country codes. Leaves unexpected shapes alone
- * so the validator reports them.
+ * lowercases domains (dropping "www."), uppercases country codes and ASINs, maps "UK" to "GB" and
+ * strips spaces and dashes from GTINs. Leaves unexpected shapes alone so the validator reports them.
  */
 export function normalizeVerifyRequest(input) {
     if (!isRecord(input))
@@ -61,13 +98,22 @@ export function normalizeVerifyRequest(input) {
         out.territory = normalizeCountry(out.territory);
     if (typeof out.product_line === "string")
         out.product_line = out.product_line.trim();
+    if (typeof out.as_of === "string")
+        out.as_of = out.as_of.trim();
+    if (isRecord(out.product)) {
+        const p = { ...out.product };
+        if (typeof p.gtin === "string")
+            p.gtin = p.gtin.replace(/[\s-]/g, "");
+        if (typeof p.asin === "string")
+            p.asin = p.asin.trim().toUpperCase();
+        out.product = p;
+    }
     out.channel = normalizeChannel(out.channel);
     return out;
 }
 /**
- * Canonical form of a channel as typed by a person or agent: trims, lowercases the type and
- * domains (dropping "www."), uppercases country codes. Unexpected shapes pass through untouched.
- * Identifier case is kept; channelKey decides how case compares.
+ * Canonical form of a channel as typed by a person or agent: trims, lowercases the type and domain
+ * (dropping "www."). Seller ID case is kept; channelKey decides how case compares.
  */
 export function normalizeChannel(input) {
     if (!isRecord(input))
@@ -75,18 +121,12 @@ export function normalizeChannel(input) {
     const ch = { ...input };
     if (typeof ch.type === "string")
         ch.type = ch.type.trim().toLowerCase();
-    if (typeof ch.marketplace === "string")
-        ch.marketplace = normalizeCountry(ch.marketplace);
     if (typeof ch.seller_id === "string")
         ch.seller_id = ch.seller_id.trim();
     if (typeof ch.domain === "string")
         ch.domain = normalizeDomain(ch.domain);
-    if (typeof ch.address === "string")
-        ch.address = ch.address.trim();
-    if (typeof ch.country === "string")
-        ch.country = ch.country.trim().toUpperCase();
     return ch;
 }
-function isRecord(v) {
+export function isRecord(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export * from "./constants.js";
 export * from "./timestamp.js";
 export * from "./validate.js";
 export * from "./identity.js";
+export * from "./product.js";
+export * from "./match.js";
 export * from "./jcs.js";
 export * from "./jws.js";
 export * from "./published.js";

package/dist/index.js

@@ -3,6 +3,8 @@ export * from "./constants.js";
 export * from "./timestamp.js";
 export * from "./validate.js";
 export * from "./identity.js";
+export * from "./product.js";
+export * from "./match.js";
 export * from "./jcs.js";
 export * from "./jws.js";
 export * from "./published.js";

package/dist/jws.d.ts

@@ -1,3 +1,4 @@
+import type { RevocationFeed } from "./types.js";
 export declare const JWS_ALG = "EdDSA";
 export interface PublicJwk {
     kty: "OKP";
@@ -19,10 +20,11 @@ export declare function signingPayload(doc: object): Uint8Array<ArrayBuffer>;
  * or a future managed key service) call this; nothing else in the registry sees the key.
  */
 export declare function signDetached(privateKey: CryptoKey, kid: string, payload: Uint8Array): Promise<string>;
-export type VerifyFailure = "missing_signature" | "malformed_jws" | "alg_not_allowed" | "kid_mismatch" | "unknown_kid" | "bad_signature" | "answer_expired" | "list_expired";
+export type VerifyFailure = "missing_signature" | "malformed_jws" | "alg_not_allowed" | "kid_mismatch" | "unknown_kid" | "bad_signature" | "answer_expired" | "list_expired" | "feed_expired" | "revocation_feed_required" | "revocation_feed_invalid" | "revoked";
 export type SignatureCheck = {
     valid: true;
     kid: string;
+    stale?: true;
 } | {
     valid: false;
     reason: VerifyFailure;
@@ -30,13 +32,42 @@ export type SignatureCheck = {
 export interface VerifyOptions {
     /** Epoch ms to check validity against. Defaults to Date.now(). */
     now?: number;
+    /**
+     * Section 10.2: accept a list or answer between its valid_until and stale_until. Only for when the
+     * registry and every mirror are unreachable, and only with a revocation feed to check against.
+     */
+    allowStale?: boolean;
+    /** The newest revocation feed the caller could get, unverified; verifyDocument checks it. */
+    revocationFeed?: RevocationFeed;
 }
 /**
- * Reference verifier for agents (§8, §9, §12). Checks, in order:
+ * Reference verifier for agents (sections 8, 9, 10, 12). Checks, in order:
  *  - the signature is a well-formed detached EdDSA JWS whose header kid matches signature.kid;
- *  - the kid is in the current key set: signatures from keys no longer in the set are rejected (§8 MUST);
+ *  - the kid is in the current key set: signatures from keys no longer in the set are rejected (section 8 MUST);
  *  - the signature verifies over the canonical document;
- *  - a verify answer is not past its valid_until (§9, §12 MUST), and a list is not past its expires (§5).
- * Callers SHOULD refetch the key set once on "unknown_kid" before giving up (§8).
+ *  - the document is not past its valid_until (section 10.1 MUST). With allowStale and a revocation
+ *    feed, a list or answer up to its stale_until is accepted as { valid: true, stale: true }, unless
+ *    the feed lists the answer's revocation_id (section 10.3). A stale list's revoked authorizations
+ *    are dropped by validAuthorizations(list, now, feed), not here.
+ *  - a revocation feed is usable up to its own stale_until, and is flagged stale after valid_until.
+ * Callers SHOULD refetch the key set once on "unknown_kid" before giving up (section 8).
  */
 export declare function verifyDocument(doc: object, jwks: Jwks, opts?: VerifyOptions): Promise<SignatureCheck>;
+/** Whether a revocation feed lists this revocation_id (section 10.3). Doesn't check the feed's signature. */
+export declare function isRevoked(feed: RevocationFeed, revocationId: string): boolean;
+export type RevocationFeedCheck = {
+    valid: true;
+    kid: string;
+    stale: boolean;
+    revoked: (revocationId: string) => boolean;
+} | {
+    valid: false;
+    reason: VerifyFailure | "not_a_feed";
+};
+/**
+ * Section 10.3: checks a revocation feed's signature and freshness (usable to its stale_until) and
+ * returns a lookup for revocation IDs. Makes no network calls: the caller fetches the feed.
+ */
+export declare function checkRevocationFeed(feed: unknown, jwks: Jwks, opts?: {
+    now?: number;
+}): Promise<RevocationFeedCheck>;