@authorizedretailers/spec 0.1.0 → 0.2.0

package/dist/jws.js

@@ -40,12 +40,16 @@ export async function signDetached(privateKey, kid, payload) {
     return `${header}..${base64url(sig)}`;
 }
 /**
- * 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 async function verifyDocument(doc, jwks, opts = {}) {
     const now = opts.now ?? Date.now();
@@ -76,15 +80,45 @@ export async function verifyDocument(doc, jwks, opts = {}) {
     if (!ok)
         return { valid: false, reason: "bad_signature" };
     const d = doc;
-    if (typeof d.valid_until === "string") {
-        const until = parseTimestamp(d.valid_until);
-        if (until === null || now > until)
-            return { valid: false, reason: "answer_expired" };
-    }
-    else if (d.form === "full" && typeof d.expires === "string") {
-        const expires = parseTimestamp(d.expires);
-        if (expires === null || now >= expires)
-            return { valid: false, reason: "list_expired" };
+    const until = typeof d.valid_until === "string" ? parseTimestamp(d.valid_until) : null;
+    const staleUntil = typeof d.stale_until === "string" ? parseTimestamp(d.stale_until) : null;
+    const isFeed = d.feed === "revocations";
+    const expired = isFeed ? "feed_expired" : typeof d.public === "boolean" ? "list_expired" : "answer_expired";
+    if (until === null)
+        return { valid: false, reason: expired };
+    if (now <= until)
+        return { valid: true, kid: sig.kid };
+    // Past valid_until. A feed stays usable to its own stale_until: it is what makes stale answers safe.
+    if (staleUntil === null || now > staleUntil)
+        return { valid: false, reason: expired };
+    if (isFeed)
+        return { valid: true, kid: sig.kid, stale: true };
+    if (!opts.allowStale)
+        return { valid: false, reason: expired };
+    if (!opts.revocationFeed)
+        return { valid: false, reason: "revocation_feed_required" };
+    const feed = await verifyDocument(opts.revocationFeed, jwks, { now });
+    if (!feed.valid || opts.revocationFeed.feed !== "revocations")
+        return { valid: false, reason: "revocation_feed_invalid" };
+    if (typeof d.revocation_id === "string" && isRevoked(opts.revocationFeed, d.revocation_id))
+        return { valid: false, reason: "revoked" };
+    return { valid: true, kid: sig.kid, stale: true };
+}
+/** Whether a revocation feed lists this revocation_id (section 10.3). Doesn't check the feed's signature. */
+export function isRevoked(feed, revocationId) {
+    return feed.entries.some((e) => e.revocation_id === revocationId);
+}
+/**
+ * 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 async function checkRevocationFeed(feed, jwks, opts = {}) {
+    if (typeof feed !== "object" || feed === null || feed.feed !== "revocations" || !Array.isArray(feed.entries)) {
+        return { valid: false, reason: "not_a_feed" };
     }
-    return { valid: true, kid: sig.kid };
+    const check = await verifyDocument(feed, jwks, opts);
+    if (!check.valid)
+        return check;
+    const ids = new Set(feed.entries.map((e) => e.revocation_id));
+    return { valid: true, kid: check.kid, stale: check.stale === true, revoked: (id) => ids.has(id) };
 }

package/dist/match.d.ts

@@ -0,0 +1,21 @@
+import type { Authorization, ProductResult, PublicList, UnlistedReason, VerifyRequest } from "./types.js";
+export interface MatchResult {
+    status: "authorized" | "unlisted" | "expired";
+    reason?: UnlistedReason;
+    /** The authorization behind an authorized or expired answer. */
+    authorization?: Authorization;
+    /** Present when the request named a product (section 9). */
+    product?: ProductResult;
+    /** Signal types to attach to the answer, e.g. "product_not_in_catalog" (section 9.2 rule 5). */
+    signals: string[];
+}
+/** An as_of value (ISO date or UTC date-time) as epoch ms; a bare date means the start of that day, UTC. */
+export declare function parseAsOf(value: string): number | null;
+/**
+ * Matches a validated verify request against a brand's public list (sections 6.2, 9.1, 9.2).
+ * Seller first: channel, seller ID, territory and date. Then product line or product, only among the
+ * authorizations that cover the seller, so a product never makes an uncovered seller authorized.
+ * Does not know about registration, disputes or observation: the registry adds those.
+ * Throws if the territory can't be worked out (a generic-domain web store with no territory).
+ */
+export declare function matchRequest(list: PublicList, request: VerifyRequest, now?: number): MatchResult;

package/dist/match.js

@@ -0,0 +1,89 @@
+// Section 9: answering a verify request from a public list. The registry and agents holding a
+// cached public list use the same function, so they reach the same answer.
+import { channelKey, coversTerritory, territoryForDomain } from "./identity.js";
+import { productCovered, productLineCovered } from "./product.js";
+import { parseTimestamp } from "./timestamp.js";
+/** An as_of value (ISO date or UTC date-time) as epoch ms; a bare date means the start of that day, UTC. */
+export function parseAsOf(value) {
+    return parseTimestamp(/^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}T00:00:00Z` : value);
+}
+function expiresBy(a, at) {
+    if (a.expires === undefined)
+        return false;
+    const exp = parseTimestamp(a.expires);
+    return exp === null || at >= exp;
+}
+/**
+ * Matches a validated verify request against a brand's public list (sections 6.2, 9.1, 9.2).
+ * Seller first: channel, seller ID, territory and date. Then product line or product, only among the
+ * authorizations that cover the seller, so a product never makes an uncovered seller authorized.
+ * Does not know about registration, disputes or observation: the registry adds those.
+ * Throws if the territory can't be worked out (a generic-domain web store with no territory).
+ */
+export function matchRequest(list, request, now = Date.now()) {
+    const at = request.as_of !== undefined ? parseAsOf(request.as_of) : now;
+    if (at === null)
+        throw new TypeError(`invalid as_of: ${request.as_of}`);
+    const territory = request.territory ?? territoryForDomain(request.channel.domain);
+    if (territory === null)
+        throw new TypeError("territory is required for a web store on a generic domain (section 6.2)");
+    const key = channelKey(request.channel);
+    const named = list.authorizations
+        .map((a) => ({ a, channel: a.channels.find((c) => channelKey(c) === key) }))
+        .filter((x) => x.channel !== undefined);
+    const inTerritory = named.filter(({ a, channel }) => coversTerritory(a, channel, territory));
+    const live = inTerritory.filter(({ a }) => !expiresBy(a, at)).map(({ a }) => a);
+    if (live.length === 0) {
+        const ended = inTerritory.filter(({ a }) => expiresBy(a, at)).map(({ a }) => a);
+        if (ended.length > 0) {
+            const latest = ended.reduce((x, y) => (parseTimestamp(y.expires) > parseTimestamp(x.expires) ? y : x));
+            return { status: "expired", authorization: latest, signals: [], ...productOnly(list, request) };
+        }
+        // Section 6.2: a marketplace domain fixes the territory. Say so when the seller is listed there.
+        const marketplaceElsewhere = named.some(({ a, channel }) => channel.type !== "web" && !expiresBy(a, at) && territoryForDomain(channel.domain) !== territory);
+        return {
+            status: "unlisted",
+            ...(marketplaceElsewhere ? { reason: "territory_mismatch" } : {}),
+            signals: [],
+            ...productOnly(list, request),
+        };
+    }
+    let candidates = live;
+    if (request.product_line !== undefined) {
+        candidates = candidates.filter((a) => productLineCovered(a, request.product_line, list.exclusions));
+        if (candidates.length === 0)
+            return { status: "unlisted", signals: [], ...productOnly(list, request) };
+    }
+    if (request.product === undefined)
+        return { status: "authorized", authorization: candidates[0], signals: [] };
+    const results = candidates.map((a) => ({ a, r: productCovered(list, a, request.product) }));
+    const hit = results.find(({ r }) => r.coverage === "covered");
+    const first = results[0].r;
+    const product = first.in_catalog
+        ? { in_catalog: true, id: first.product.id, ...(first.product.product_line ? { product_line: first.product.product_line } : {}) }
+        : { in_catalog: false };
+    if (hit) {
+        return {
+            status: "authorized",
+            authorization: hit.a,
+            product,
+            signals: hit.r.in_catalog ? [] : ["product_not_in_catalog"],
+        };
+    }
+    const reason = !first.in_catalog
+        ? "product_not_in_catalog"
+        : results.some(({ r }) => r.coverage === "excluded")
+            ? "product_excluded"
+            : "product_not_in_scope";
+    return { status: "unlisted", reason, product, signals: [] };
+}
+/** The product part of an answer that was decided before the product was considered. */
+function productOnly(list, request) {
+    if (request.product === undefined)
+        return {};
+    const probe = productCovered(list, { scope: {} }, request.product);
+    if (!probe.in_catalog)
+        return { product: { in_catalog: false } };
+    const p = probe.product;
+    return { product: { in_catalog: true, id: p.id, ...(p.product_line ? { product_line: p.product_line } : {}) } };
+}

package/dist/product.d.ts

@@ -0,0 +1,34 @@
+import type { Authorization, Exclusions, Product, ProductRef, PublicList } from "./types.js";
+/** Whether a GTIN (8, 12, 13 or 14 digits) has a valid GS1 check digit. */
+export declare function isValidGtin(gtin: string): boolean;
+/** GTIN-14 form used for matching: left-padded with zeros. Throws on an invalid GTIN. */
+export declare function toGtin14(gtin: string): string;
+/** An ASIN: 10 uppercase letters or digits. */
+export declare function isValidAsin(asin: string): boolean;
+/** The catalog product a GTIN or ASIN refers to, or undefined when it isn't in the catalog. */
+export declare function findProduct(catalog: Product[] | undefined, ref: ProductRef): Product | undefined;
+export type Coverage = "covered" | "excluded" | "not_in_scope";
+/**
+ * Section 3.1: whether an authorization covers a catalog product. Exclusions (the authorization's
+ * and the brand's) always win over inclusions.
+ */
+export declare function productCoverage(authorization: Authorization, product: Product, brandExclusions?: Exclusions): Coverage;
+/** Whether the authorization is scoped to every product (product_lines ["all"]). */
+export declare function coversAllProducts(authorization: Authorization): boolean;
+/**
+ * Section 9: whether an authorization covers a whole product line, for requests that ask with
+ * product_line. The line is covered when the scope is ["all"] or names it, and nobody excludes it.
+ */
+export declare function productLineCovered(authorization: Authorization, line: string, brandExclusions?: Exclusions): boolean;
+/**
+ * Section 9.2, for one authorization: covered, excluded, not in scope, or (for a product the catalog
+ * doesn't hold) whether the authorization's ["all"] scope still covers it.
+ */
+export declare function productCovered(list: Pick<PublicList, "catalog" | "exclusions">, authorization: Authorization, product: ProductRef): {
+    in_catalog: true;
+    product: Product;
+    coverage: Coverage;
+} | {
+    in_catalog: false;
+    coverage: "covered" | "not_in_catalog";
+};

package/dist/product.js

@@ -0,0 +1,75 @@
+// Section 3.1: product identifiers and catalog lookups.
+/** Whether a GTIN (8, 12, 13 or 14 digits) has a valid GS1 check digit. */
+export function isValidGtin(gtin) {
+    if (!/^(\d{8}|\d{12,14})$/.test(gtin))
+        return false;
+    const digits = [...gtin].map(Number);
+    const check = digits.pop();
+    // Weights alternate 3, 1, 3, ... from the digit next to the check digit.
+    const sum = digits.reverse().reduce((s, d, i) => s + d * (i % 2 === 0 ? 3 : 1), 0);
+    return (10 - (sum % 10)) % 10 === check;
+}
+/** GTIN-14 form used for matching: left-padded with zeros. Throws on an invalid GTIN. */
+export function toGtin14(gtin) {
+    if (!isValidGtin(gtin))
+        throw new Error(`invalid GTIN: ${gtin}`);
+    return gtin.padStart(14, "0");
+}
+/** An ASIN: 10 uppercase letters or digits. */
+export function isValidAsin(asin) {
+    return /^[A-Z0-9]{10}$/.test(asin);
+}
+/** The catalog product a GTIN or ASIN refers to, or undefined when it isn't in the catalog. */
+export function findProduct(catalog, ref) {
+    if (!catalog)
+        return undefined;
+    if ("gtin" in ref) {
+        if (!isValidGtin(ref.gtin))
+            return undefined;
+        const want = toGtin14(ref.gtin);
+        return catalog.find((p) => p.gtin !== undefined && isValidGtin(p.gtin) && toGtin14(p.gtin) === want);
+    }
+    const asin = ref.asin.toUpperCase();
+    return catalog.find((p) => p.asins?.includes(asin));
+}
+/**
+ * Section 3.1: whether an authorization covers a catalog product. Exclusions (the authorization's
+ * and the brand's) always win over inclusions.
+ */
+export function productCoverage(authorization, product, brandExclusions) {
+    const s = authorization.scope;
+    const line = product.product_line;
+    const excluded = (line !== undefined && (s.exclude_product_lines?.includes(line) || brandExclusions?.product_lines?.includes(line))) ||
+        s.exclude_products?.includes(product.id) ||
+        brandExclusions?.products?.includes(product.id);
+    if (excluded)
+        return "excluded";
+    const included = s.product_lines?.[0] === "all" ||
+        (line !== undefined && s.product_lines?.includes(line)) ||
+        s.products?.includes(product.id);
+    return included ? "covered" : "not_in_scope";
+}
+/** Whether the authorization is scoped to every product (product_lines ["all"]). */
+export function coversAllProducts(authorization) {
+    return authorization.scope.product_lines?.[0] === "all";
+}
+/**
+ * Section 9: whether an authorization covers a whole product line, for requests that ask with
+ * product_line. The line is covered when the scope is ["all"] or names it, and nobody excludes it.
+ */
+export function productLineCovered(authorization, line, brandExclusions) {
+    const s = authorization.scope;
+    if (s.exclude_product_lines?.includes(line) || brandExclusions?.product_lines?.includes(line))
+        return false;
+    return s.product_lines?.[0] === "all" || (s.product_lines?.includes(line) ?? false);
+}
+/**
+ * Section 9.2, for one authorization: covered, excluded, not in scope, or (for a product the catalog
+ * doesn't hold) whether the authorization's ["all"] scope still covers it.
+ */
+export function productCovered(list, authorization, product) {
+    const found = findProduct(list.catalog, product);
+    if (found)
+        return { in_catalog: true, product: found, coverage: productCoverage(authorization, found, list.exclusions) };
+    return { in_catalog: false, coverage: coversAllProducts(authorization) ? "covered" : "not_in_catalog" };
+}

package/dist/published.d.ts

@@ -1,15 +1,21 @@
-import { type Jwks, type VerifyFailure } from "./jws.js";
-import type { AuthorizedRetailersFile } from "./types.js";
-export type PublishedFileCheck = {
+import { type Jwks, type VerifyFailure, type VerifyOptions } from "./jws.js";
+import type { Authorization, PublicList, RevocationFeed } from "./types.js";
+export type PublishedListCheck = {
     counts: true;
     kid: string;
+    stale?: true;
 } | {
     counts: false;
-    reason: VerifyFailure | "domain_mismatch";
+    reason: VerifyFailure | "domain_mismatch" | "not_a_list";
 };
 /**
- * Whether a published file counts, given the domain it was fetched from and the registry's keys.
- * An unsigned file, a bad signature, an expired list, or a file naming another brand's domain
- * doesn't count: treat it as no file at all.
+ * Whether a fetched list counts for `brandDomain`, given the registry's keys. An unsigned list, a
+ * bad signature, a list past its valid_until (or stale_until, with allowStale) or a list that
+ * doesn't name the domain doesn't count: treat it as no list at all.
  */
-export declare function checkPublishedFile(fetchedFrom: string, file: AuthorizedRetailersFile, jwks: Jwks, now?: number): Promise<PublishedFileCheck>;
+export declare function checkPublishedList(brandDomain: string, list: unknown, jwks: Jwks, opts?: VerifyOptions): Promise<PublishedListCheck>;
+/**
+ * The authorizations a reader may rely on at `now`: those without an end date or not yet past it.
+ * With a revocation feed (for a stale list, section 10.3), revoked authorizations are dropped too.
+ */
+export declare function validAuthorizations(list: PublicList, now?: number, revocationFeed?: RevocationFeed): Authorization[];

package/dist/published.js

@@ -1,15 +1,37 @@
-// Section 5: which published files count. Only a file signed by a registry, and only for the domain
-// it was fetched from. Indexes and agents reading brands' files directly both apply this.
+// Section 5.2: which signed lists count. Only a list signed with the registry's keys, and only for a
+// brand domain the list names. Agents reading lists directly or from a mirror apply this.
 import { normalizeDomain } from "./identity.js";
-import { verifyDocument } from "./jws.js";
+import { isRevoked, verifyDocument } from "./jws.js";
+import { parseTimestamp } from "./timestamp.js";
 /**
- * Whether a published file counts, given the domain it was fetched from and the registry's keys.
- * An unsigned file, a bad signature, an expired list, or a file naming another brand's domain
- * doesn't count: treat it as no file at all.
+ * Whether a fetched list counts for `brandDomain`, given the registry's keys. An unsigned list, a
+ * bad signature, a list past its valid_until (or stale_until, with allowStale) or a list that
+ * doesn't name the domain doesn't count: treat it as no list at all.
  */
-export async function checkPublishedFile(fetchedFrom, file, jwks, now = Date.now()) {
-    if (normalizeDomain(file.brand.domain) !== normalizeDomain(fetchedFrom))
+export async function checkPublishedList(brandDomain, list, jwks, opts = {}) {
+    const domains = list?.brand?.domains;
+    if (typeof list !== "object" || list === null || !Array.isArray(domains) || typeof list.public !== "boolean") {
+        return { counts: false, reason: "not_a_list" };
+    }
+    const want = normalizeDomain(brandDomain);
+    if (!domains.some((d) => typeof d === "string" && normalizeDomain(d) === want))
         return { counts: false, reason: "domain_mismatch" };
-    const sig = await verifyDocument(file, jwks, { now });
-    return sig.valid ? { counts: true, kid: sig.kid } : { counts: false, reason: sig.reason };
+    const sig = await verifyDocument(list, jwks, opts);
+    if (!sig.valid)
+        return { counts: false, reason: sig.reason };
+    return sig.stale ? { counts: true, kid: sig.kid, stale: true } : { counts: true, kid: sig.kid };
+}
+/**
+ * The authorizations a reader may rely on at `now`: those without an end date or not yet past it.
+ * With a revocation feed (for a stale list, section 10.3), revoked authorizations are dropped too.
+ */
+export function validAuthorizations(list, now = Date.now(), revocationFeed) {
+    return list.authorizations.filter((a) => {
+        if (revocationFeed && isRevoked(revocationFeed, a.revocation_id))
+            return false;
+        if (a.expires === undefined)
+            return true;
+        const exp = parseTimestamp(a.expires);
+        return exp !== null && now < exp;
+    });
 }