@authorizedretailers/spec 0.1.0

package/README.md

@@ -0,0 +1,130 @@
+# 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.
+
+> **Status: draft v0.1.** 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.
+
+- **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)
+
+## 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.
+- **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 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.
+- **Retailers can see and dispute their status.** A retailer can check how it is listed and dispute an entry it believes is wrong (spec section 11).
+
+## Who it's for
+
+| 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 |
+| An agent builder | Check a seller before recommending or buying, with an answer you can verify |
+
+## Publish a file (brands)
+
+A brand verifies control of its domain with a registry, which signs its list. The brand then serves a file at:
+
+```
+https://<brand-domain>/.well-known/authorized-retailers.json
+```
+
+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 |
+
+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:
+
+```json
+{
+  "spec": "authorized-retailers/0.1",
+  "form": "pointer",
+  "brand": { "name": "Example Brand", "domain": "brand.example" },
+  "list": "https://authorizedretailers.ai/v0/brands/brand.example/list"
+}
+```
+
+## Validate a file
+
+```bash
+npm install @authorizedretailers/spec
+```
+
+```ts
+import { validateFile, 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:
+
+```ts
+import { checkPublishedFile } from "@authorizedretailers/spec";
+
+const check = await checkPublishedFile("brand.example", file, jwks);
+// { counts: true, kid } or { counts: false, reason }
+```
+
+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:
+
+```ts
+import { verifyDocument } from "@authorizedretailers/spec";
+
+const answer = await fetch("https://authorizedretailers.ai/v0/verify", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    brand_domain: "brand.example",
+    channel: { type: "amazon", marketplace: "US", seller_id: "A1B2C3D4E5F6G7" },
+    territory: "US",
+  }),
+}).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);
+// { 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.
+
+## 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 |
+| `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.
+
+## 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).
+
+## License
+
+- The specification and documents in `spec/` and `docs/`: [CC BY 4.0](LICENSE-SPEC)
+- Schemas, code and fixtures: [Apache 2.0](LICENSE)
+
+"authorizedretailers.ai" and "Authorized Retailers" are trademarks. See [TRADEMARKS.md](TRADEMARKS.md).

package/dist/constants.d.ts

@@ -0,0 +1,6 @@
+/** 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;

package/dist/constants.js

@@ -0,0 +1,7 @@
+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;

package/dist/identity.d.ts

@@ -0,0 +1,27 @@
+import type { Authorization, Channel, FullFile } from "./types.js";
+export declare function normalizeDomain(domain: string): string;
+export declare function normalizeCountry(code: string): string;
+/**
+ * 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.
+ */
+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[];
+/**
+ * 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 declare function validAuthorizations(file: FullFile, now?: number): 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.
+ */
+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.
+ */
+export declare function normalizeChannel(input: unknown): unknown;

package/dist/identity.js

@@ -0,0 +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" };
+export function normalizeDomain(domain) {
+    return domain.trim().toLowerCase().replace(/\.$/, "").replace(/^www\./, "");
+}
+export function normalizeCountry(code) {
+    const upper = code.trim().toUpperCase();
+    return MARKETPLACE_ALIASES[upper] ?? upper;
+}
+/**
+ * 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.
+ */
+export function channelKey(channel) {
+    switch (channel.type) {
+        case "amazon":
+            return `amazon:${normalizeCountry(channel.marketplace)}:${channel.seller_id.trim().toUpperCase()}`;
+        case "walmart":
+            return `walmart:${normalizeCountry(channel.marketplace)}:${channel.seller_id.trim()}`;
+        case "ebay":
+            return `ebay:${normalizeCountry(channel.marketplace)}:${channel.seller_id.trim().toLowerCase()}`;
+        case "web":
+            return `web:${normalizeDomain(channel.domain)}`;
+        case "physical":
+            return 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.
+ */
+export function normalizeVerifyRequest(input) {
+    if (!isRecord(input))
+        return input;
+    const out = { ...input };
+    if (typeof out.brand_domain === "string")
+        out.brand_domain = normalizeDomain(out.brand_domain);
+    if (typeof out.territory === "string")
+        out.territory = normalizeCountry(out.territory);
+    if (typeof out.product_line === "string")
+        out.product_line = out.product_line.trim();
+    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.
+ */
+export function normalizeChannel(input) {
+    if (!isRecord(input))
+        return 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) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./constants.js";
+export * from "./timestamp.js";
+export * from "./validate.js";
+export * from "./identity.js";
+export * from "./jcs.js";
+export * from "./jws.js";
+export * from "./published.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./constants.js";
+export * from "./timestamp.js";
+export * from "./validate.js";
+export * from "./identity.js";
+export * from "./jcs.js";
+export * from "./jws.js";
+export * from "./published.js";

package/dist/jcs.d.ts

@@ -0,0 +1,5 @@
+export declare class CanonicalizationError extends Error {
+    constructor(message: string);
+}
+export declare function canonicalize(value: unknown): string;
+export declare function canonicalBytes(value: unknown): Uint8Array<ArrayBuffer>;

package/dist/jcs.js

@@ -0,0 +1,47 @@
+// JSON Canonicalization Scheme, RFC 8785.
+//
+// ECMAScript already defines the two hard parts the RFC relies on: JSON.stringify's string
+// escaping (RFC 8785 §3.2.2.2) and Number.prototype.toString's shortest round-trip form
+// (§3.2.2.3). What remains is recursive key sorting by UTF-16 code units (§3.2.3), which is
+// what Array.prototype.sort does by default on strings.
+export class CanonicalizationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CanonicalizationError";
+    }
+}
+export function canonicalize(value) {
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "boolean":
+            return value ? "true" : "false";
+        case "number":
+            if (!Number.isFinite(value))
+                throw new CanonicalizationError(`cannot canonicalize ${value}`);
+            return JSON.stringify(value); // -0 serializes as "0", as RFC 8785 requires
+        case "string":
+            if (/\p{Surrogate}/u.test(value.replace(/[\uD800-\uDBFF][\uDC00-\uDFFF]/g, ""))) {
+                throw new CanonicalizationError("string contains a lone surrogate");
+            }
+            return JSON.stringify(value);
+        case "object": {
+            if (Array.isArray(value))
+                return `[${value.map(canonicalize).join(",")}]`;
+            const obj = value;
+            const proto = Object.getPrototypeOf(obj);
+            if (proto !== Object.prototype && proto !== null) {
+                throw new CanonicalizationError("only plain objects can be canonicalized");
+            }
+            const keys = Object.keys(obj)
+                .filter((k) => obj[k] !== undefined)
+                .sort();
+            return `{${keys.map((k) => `${canonicalize(k)}:${canonicalize(obj[k])}`).join(",")}}`;
+        }
+        default:
+            throw new CanonicalizationError(`cannot canonicalize a ${typeof value}`);
+    }
+}
+export function canonicalBytes(value) {
+    return new TextEncoder().encode(canonicalize(value));
+}

package/dist/jws.d.ts

@@ -0,0 +1,42 @@
+export declare const JWS_ALG = "EdDSA";
+export interface PublicJwk {
+    kty: "OKP";
+    crv: "Ed25519";
+    x: string;
+    kid: string;
+    alg?: "EdDSA";
+    use?: "sig";
+}
+export interface Jwks {
+    keys: PublicJwk[];
+}
+export declare function base64url(bytes: Uint8Array): string;
+export declare function base64urlDecode(s: string): Uint8Array<ArrayBuffer>;
+/** The bytes a signature covers: the document minus "signature", canonicalized. */
+export declare function signingPayload(doc: object): Uint8Array<ArrayBuffer>;
+/**
+ * Produces a compact detached JWS over `payload`. Holders of the private key (the signer Worker,
+ * 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 SignatureCheck = {
+    valid: true;
+    kid: string;
+} | {
+    valid: false;
+    reason: VerifyFailure;
+};
+export interface VerifyOptions {
+    /** Epoch ms to check validity against. Defaults to Date.now(). */
+    now?: number;
+}
+/**
+ * Reference verifier for agents (§8, §9, §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 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).
+ */
+export declare function verifyDocument(doc: object, jwks: Jwks, opts?: VerifyOptions): Promise<SignatureCheck>;

package/dist/jws.js

@@ -0,0 +1,90 @@
+// Detached JWS (RFC 7515 Appendix F) with EdDSA / Ed25519 over RFC 8785 canonical JSON (§8).
+//
+// The signed payload is the canonical form of the document with its "signature" member removed.
+// The compact serialization is "<header>..<signature>": the payload segment is empty because the
+// reader recomputes it from the document it already has.
+import { canonicalBytes, canonicalize } from "./jcs.js";
+import { parseTimestamp } from "./timestamp.js";
+export const JWS_ALG = "EdDSA";
+const ED25519 = { name: "Ed25519" };
+export function base64url(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export function base64urlDecode(s) {
+    if (!/^[A-Za-z0-9_-]*$/.test(s))
+        throw new Error("not base64url");
+    const bin = atob(s.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (s.length % 4)) % 4));
+    return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+}
+/** The bytes a signature covers: the document minus "signature", canonicalized. */
+export function signingPayload(doc) {
+    const { signature: _omit, ...rest } = doc;
+    return canonicalBytes(rest);
+}
+function protectedHeader(kid) {
+    return base64url(new TextEncoder().encode(canonicalize({ alg: JWS_ALG, kid })));
+}
+function signingInput(headerB64, payload) {
+    return new TextEncoder().encode(`${headerB64}.${base64url(payload)}`);
+}
+/**
+ * Produces a compact detached JWS over `payload`. Holders of the private key (the signer Worker,
+ * or a future managed key service) call this; nothing else in the registry sees the key.
+ */
+export async function signDetached(privateKey, kid, payload) {
+    const header = protectedHeader(kid);
+    const sig = new Uint8Array(await crypto.subtle.sign(ED25519, privateKey, signingInput(header, payload)));
+    return `${header}..${base64url(sig)}`;
+}
+/**
+ * Reference verifier for agents (§8, §9, §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 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).
+ */
+export async function verifyDocument(doc, jwks, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const sig = doc.signature;
+    if (!sig || typeof sig.jws !== "string" || typeof sig.kid !== "string")
+        return { valid: false, reason: "missing_signature" };
+    const parts = sig.jws.split(".");
+    if (parts.length !== 3 || parts[1] !== "" || !parts[0] || !parts[2])
+        return { valid: false, reason: "malformed_jws" };
+    let header;
+    let signature;
+    try {
+        header = JSON.parse(new TextDecoder().decode(base64urlDecode(parts[0])));
+        signature = base64urlDecode(parts[2]);
+    }
+    catch {
+        return { valid: false, reason: "malformed_jws" };
+    }
+    if (header.alg !== JWS_ALG || header.crit !== undefined)
+        return { valid: false, reason: "alg_not_allowed" };
+    if (header.kid !== sig.kid)
+        return { valid: false, reason: "kid_mismatch" };
+    const jwk = jwks.keys.find((k) => k.kid === sig.kid);
+    if (!jwk || jwk.kty !== "OKP" || jwk.crv !== "Ed25519")
+        return { valid: false, reason: "unknown_kid" };
+    const key = await crypto.subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, ED25519, false, ["verify"]);
+    const ok = await crypto.subtle.verify(ED25519, key, signature, signingInput(parts[0], signingPayload(doc)));
+    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" };
+    }
+    return { valid: true, kid: sig.kid };
+}

package/dist/published.d.ts

@@ -0,0 +1,15 @@
+import { type Jwks, type VerifyFailure } from "./jws.js";
+import type { AuthorizedRetailersFile } from "./types.js";
+export type PublishedFileCheck = {
+    counts: true;
+    kid: string;
+} | {
+    counts: false;
+    reason: VerifyFailure | "domain_mismatch";
+};
+/**
+ * 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.
+ */
+export declare function checkPublishedFile(fetchedFrom: string, file: AuthorizedRetailersFile, jwks: Jwks, now?: number): Promise<PublishedFileCheck>;

package/dist/published.js

@@ -0,0 +1,15 @@
+// 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.
+import { normalizeDomain } from "./identity.js";
+import { verifyDocument } from "./jws.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.
+ */
+export async function checkPublishedFile(fetchedFrom, file, jwks, now = Date.now()) {
+    if (normalizeDomain(file.brand.domain) !== normalizeDomain(fetchedFrom))
+        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 };
+}