@authorizedretailers/spec 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,116 @@
+export declare const SPEC_VERSION: "authorized-retailers/0.1";
+export type SpecVersion = typeof SPEC_VERSION;
+/** RFC 3339 UTC timestamp, e.g. "2026-09-23T00:00:00Z". */
+export type Timestamp = string;
+export interface Brand {
+    name: string;
+    domain: string;
+}
+export type MarketplaceChannelType = "amazon" | "walmart" | "ebay";
+export interface MarketplaceChannel {
+    type: MarketplaceChannelType;
+    marketplace: string;
+    seller_id: string;
+}
+export interface WebChannel {
+    type: "web";
+    domain: string;
+}
+export interface PhysicalChannel {
+    type: "physical";
+    address: string;
+    country: string;
+}
+/** A channel an agent can see and match on (section 6). */
+export type VerifiableChannel = MarketplaceChannel | WebChannel;
+export type Channel = VerifiableChannel | PhysicalChannel;
+export type ChannelType = Channel["type"];
+export interface Party {
+    name: string;
+    entity_id?: string;
+}
+export interface Scope {
+    /** ISO 3166-1 alpha-2 codes, or exactly ["*"]. */
+    territories: string[];
+    /** Named product lines, or exactly ["all"]. */
+    product_lines: string[];
+}
+export interface Authorization {
+    id: string;
+    retailer: Party;
+    channels: Channel[];
+    scope: Scope;
+    proposed_by?: Party | null;
+    expires: Timestamp;
+}
+export interface Signature {
+    kid: string;
+    /** Detached compact JWS: "<header>..<signature>". */
+    jws: string;
+}
+export interface FullFile {
+    spec: SpecVersion;
+    form: "full";
+    brand: Brand;
+    issued: Timestamp;
+    expires: Timestamp;
+    authorizations: Authorization[];
+    signature?: Signature;
+}
+export interface PointerFile {
+    spec: SpecVersion;
+    form: "pointer";
+    brand: Brand;
+    list: string;
+}
+export interface PrivateFile {
+    spec: SpecVersion;
+    form: "private";
+    brand: Brand;
+    verify: string;
+}
+export type AuthorizedRetailersFile = FullFile | PointerFile | PrivateFile;
+export type FileForm = AuthorizedRetailersFile["form"];
+export interface VerifyRequest {
+    brand_domain: string;
+    channel: VerifiableChannel;
+    territory: string;
+    /** Defaults to "all". */
+    product_line?: string;
+}
+export type VerifyStatus = "authorized" | "unlisted" | "expired" | "brand_unverified" | "disputed";
+export type UnverifiedReason = "not_registered" | "domain_unlinked" | "verification_lapsed";
+export interface Signal {
+    type: string;
+    observed: Timestamp;
+    detail?: string;
+}
+/** Section 7: the registry saw this seller selling on the channel within the last 30 days. */
+export interface Observation {
+    last_seen: Timestamp;
+}
+interface VerifyResponseBase {
+    checked: Timestamp;
+    /** At most 24 hours after `checked` (section 9). */
+    valid_until: Timestamp;
+    /** Non-null only on `authorized` answers (section 7). */
+    observed: Observation | null;
+    signals: Signal[];
+    signature: Signature;
+}
+export interface VerifyResponseWithAuthorization extends VerifyResponseBase {
+    status: "authorized" | "expired" | "disputed";
+    authorization_id: string;
+    expires: Timestamp;
+}
+export interface VerifyResponseUnlisted extends VerifyResponseBase {
+    status: "unlisted";
+}
+export interface VerifyResponseBrandUnverified extends VerifyResponseBase {
+    status: "brand_unverified";
+    reason?: UnverifiedReason;
+}
+export type VerifyResponse = VerifyResponseWithAuthorization | VerifyResponseUnlisted | VerifyResponseBrandUnverified;
+/** A verify response before the registry attaches its signature. */
+export type UnsignedVerifyResponse = VerifyResponse extends infer R ? R extends VerifyResponseBase ? Omit<R, "signature"> : never : never;
+export {};

package/dist/types.js

@@ -0,0 +1,2 @@
+// Types mirror schemas/*.json. The schemas are canonical; if the two disagree, the schema wins.
+export const SPEC_VERSION = "authorized-retailers/0.1";

package/dist/validate.d.ts

@@ -0,0 +1,28 @@
+import type { AuthorizedRetailersFile, Channel, Scope, FullFile, PointerFile, PrivateFile, VerifyRequest, VerifyResponse } from "./types.js";
+export type ErrorCode = "schema" | "invalid_timestamp" | "expires_not_after_issued" | "file_expiry_exceeds_max" | "authorization_expires_after_file" | "duplicate_authorization_id" | "valid_until_not_after_checked" | "valid_until_exceeds_max";
+export interface ValidationError {
+    code: ErrorCode;
+    /** JSON Pointer into the instance, e.g. "/authorizations/0/expires". */
+    path: string;
+    message: string;
+}
+export type ValidationResult<T> = {
+    valid: true;
+    value: T;
+    errors: [];
+} | {
+    valid: false;
+    errors: ValidationError[];
+};
+/** Validates an authorized-retailers.json file of any form. */
+export declare function validateFile(input: unknown): ValidationResult<AuthorizedRetailersFile>;
+export declare function validateFullFile(input: unknown): ValidationResult<FullFile>;
+export declare function validatePointerFile(input: unknown): ValidationResult<PointerFile>;
+export declare function validatePrivateFile(input: unknown): ValidationResult<PrivateFile>;
+/** Validates a canonical verify request. Call normalizeVerifyRequest on raw agent input first. */
+export declare function validateVerifyRequest(input: unknown): ValidationResult<VerifyRequest>;
+export declare function validateVerifyResponse(input: unknown): ValidationResult<VerifyResponse>;
+/** Validates one authorization scope (§3), e.g. before a registry stores it. */
+export declare function validateScope(input: unknown): ValidationResult<Scope>;
+/** Validates one channel identifier (§6), e.g. before a registry stores it. */
+export declare function validateChannel(input: unknown): ValidationResult<Channel>;

package/dist/validate.js

@@ -0,0 +1,147 @@
+import { Validator } from "@cfworker/json-schema";
+import { common, file, fileFull, filePointer, filePrivate, verifyRequest, verifyResponse } from "./schemas.js";
+import { MAX_ANSWER_VALIDITY_MS, MAX_EXPIRY_MS } from "./constants.js";
+import { parseTimestamp } from "./timestamp.js";
+const ALL_SCHEMAS = [common, fileFull, filePointer, filePrivate, file, verifyRequest, verifyResponse];
+const scopeSchema = { $id: "https://authorizedretailers.ai/schemas/0.1/scope.json", $ref: "common.json#/$defs/scope" };
+const channelSchema = { $id: "https://authorizedretailers.ai/schemas/0.1/channel.json", $ref: "common.json#/$defs/channel" };
+function makeValidator(root) {
+    const v = new Validator(root, "2020-12", false);
+    for (const s of ALL_SCHEMAS)
+        if (s !== root)
+            v.addSchema(s);
+    return v;
+}
+// Built lazily: compiling at module load would slow Worker cold starts for callers that never validate.
+const validators = new Map();
+function schemaErrors(root, instance) {
+    let v = validators.get(root);
+    if (!v) {
+        v = makeValidator(root);
+        validators.set(root, v);
+    }
+    const result = v.validate(instance);
+    if (result.valid)
+        return [];
+    return dedupe(result.errors.map(toError));
+}
+function toError(unit) {
+    const path = unit.instanceLocation.replace(/^#/, "");
+    return { code: "schema", path, message: `${unit.error} (${unit.keywordLocation})` };
+}
+function dedupe(errors) {
+    const seen = new Set();
+    return errors.filter((e) => {
+        const k = `${e.path}|${e.message}`;
+        if (seen.has(k))
+            return false;
+        seen.add(k);
+        return true;
+    });
+}
+function done(errors, value) {
+    return errors.length === 0 ? { valid: true, value: value, errors: [] } : { valid: false, errors };
+}
+function ts(errors, path, value) {
+    const ms = parseTimestamp(value);
+    if (ms === null)
+        errors.push({ code: "invalid_timestamp", path, message: `not a valid UTC timestamp: ${value}` });
+    return ms;
+}
+/** Rules the JSON Schema cannot express (sections 5 and 10). Assumes the file already passed the schema. */
+function fullFileRules(f) {
+    const errors = [];
+    const issued = ts(errors, "/issued", f.issued);
+    const expires = ts(errors, "/expires", f.expires);
+    if (issued !== null && expires !== null) {
+        if (expires <= issued) {
+            errors.push({ code: "expires_not_after_issued", path: "/expires", message: "file expires must be after issued" });
+        }
+        else if (expires - issued > MAX_EXPIRY_MS) {
+            errors.push({
+                code: "file_expiry_exceeds_max",
+                path: "/expires",
+                message: "file expires more than 180 days after issued (section 10)",
+            });
+        }
+    }
+    const ids = new Set();
+    f.authorizations.forEach((a, i) => {
+        const base = `/authorizations/${i}`;
+        if (ids.has(a.id)) {
+            errors.push({ code: "duplicate_authorization_id", path: `${base}/id`, message: `duplicate authorization id ${a.id}` });
+        }
+        ids.add(a.id);
+        const aExpires = ts(errors, `${base}/expires`, a.expires);
+        if (aExpires !== null && expires !== null && aExpires > expires) {
+            errors.push({
+                code: "authorization_expires_after_file",
+                path: `${base}/expires`,
+                message: "an authorization's expires MUST NOT be later than the file's expires (section 5)",
+            });
+        }
+    });
+    return errors;
+}
+function verifyResponseRules(r) {
+    const errors = [];
+    const checked = ts(errors, "/checked", r.checked);
+    const validUntil = ts(errors, "/valid_until", r.valid_until);
+    if ("expires" in r)
+        ts(errors, "/expires", r.expires);
+    for (const [i, s] of r.signals.entries())
+        ts(errors, `/signals/${i}/observed`, s.observed);
+    if (r.observed)
+        ts(errors, "/observed/last_seen", r.observed.last_seen);
+    if (checked !== null && validUntil !== null) {
+        if (validUntil <= checked) {
+            errors.push({ code: "valid_until_not_after_checked", path: "/valid_until", message: "valid_until must be after checked" });
+        }
+        else if (validUntil - checked > MAX_ANSWER_VALIDITY_MS) {
+            errors.push({
+                code: "valid_until_exceeds_max",
+                path: "/valid_until",
+                message: "valid_until MUST be no later than 24 hours after checked (section 9)",
+            });
+        }
+    }
+    return errors;
+}
+/** Validates an authorized-retailers.json file of any form. */
+export function validateFile(input) {
+    const errors = schemaErrors(file, input);
+    if (errors.length === 0 && input.form === "full") {
+        errors.push(...fullFileRules(input));
+    }
+    return done(errors, input);
+}
+export function validateFullFile(input) {
+    const errors = schemaErrors(fileFull, input);
+    if (errors.length === 0)
+        errors.push(...fullFileRules(input));
+    return done(errors, input);
+}
+export function validatePointerFile(input) {
+    return done(schemaErrors(filePointer, input), input);
+}
+export function validatePrivateFile(input) {
+    return done(schemaErrors(filePrivate, input), input);
+}
+/** Validates a canonical verify request. Call normalizeVerifyRequest on raw agent input first. */
+export function validateVerifyRequest(input) {
+    return done(schemaErrors(verifyRequest, input), input);
+}
+export function validateVerifyResponse(input) {
+    const errors = schemaErrors(verifyResponse, input);
+    if (errors.length === 0)
+        errors.push(...verifyResponseRules(input));
+    return done(errors, input);
+}
+/** Validates one authorization scope (§3), e.g. before a registry stores it. */
+export function validateScope(input) {
+    return done(schemaErrors(scopeSchema, input), input);
+}
+/** Validates one channel identifier (§6), e.g. before a registry stores it. */
+export function validateChannel(input) {
+    return done(schemaErrors(channelSchema, input), input);
+}

package/fixtures/file/invalid/full-all-mixed.json

@@ -0,0 +1,47 @@
+{
+  "spec": "authorized-retailers/0.1",
+  "form": "full",
+  "brand": {
+    "name": "Example Brand",
+    "domain": "brand.example"
+  },
+  "issued": "2026-09-23T00:00:00Z",
+  "expires": "2026-12-22T00:00:00Z",
+  "authorizations": [
+    {
+      "id": "auth_01J9X2",
+      "retailer": {
+        "name": "Example Retail LLC",
+        "entity_id": "ent_7Q4M"
+      },
+      "channels": [
+        {
+          "type": "amazon",
+          "marketplace": "US",
+          "seller_id": "A1B2C3D4E5F6G7"
+        },
+        {
+          "type": "walmart",
+          "marketplace": "US",
+          "seller_id": "101234567"
+        },
+        {
+          "type": "web",
+          "domain": "retailer.example"
+        }
+      ],
+      "scope": {
+        "territories": [
+          "US",
+          "CA"
+        ],
+        "product_lines": [
+          "all",
+          "running"
+        ]
+      },
+      "proposed_by": null,
+      "expires": "2026-12-22T00:00:00Z"
+    }
+  ]
+}

package/fixtures/file/invalid/full-amazon-missing-seller-id.json

@@ -0,0 +1,45 @@
+{
+  "spec": "authorized-retailers/0.1",
+  "form": "full",
+  "brand": {
+    "name": "Example Brand",
+    "domain": "brand.example"
+  },
+  "issued": "2026-09-23T00:00:00Z",
+  "expires": "2026-12-22T00:00:00Z",
+  "authorizations": [
+    {
+      "id": "auth_01J9X2",
+      "retailer": {
+        "name": "Example Retail LLC",
+        "entity_id": "ent_7Q4M"
+      },
+      "channels": [
+        {
+          "type": "amazon",
+          "marketplace": "US"
+        },
+        {
+          "type": "walmart",
+          "marketplace": "US",
+          "seller_id": "101234567"
+        },
+        {
+          "type": "web",
+          "domain": "retailer.example"
+        }
+      ],
+      "scope": {
+        "territories": [
+          "US",
+          "CA"
+        ],
+        "product_lines": [
+          "all"
+        ]
+      },
+      "proposed_by": null,
+      "expires": "2026-12-22T00:00:00Z"
+    }
+  ]
+}

package/fixtures/file/invalid/full-attached-jws.json

@@ -0,0 +1,50 @@
+{
+  "spec": "authorized-retailers/0.1",
+  "form": "full",
+  "brand": {
+    "name": "Example Brand",
+    "domain": "brand.example"
+  },
+  "issued": "2026-09-23T00:00:00Z",
+  "expires": "2026-12-22T00:00:00Z",
+  "authorizations": [
+    {
+      "id": "auth_01J9X2",
+      "retailer": {
+        "name": "Example Retail LLC",
+        "entity_id": "ent_7Q4M"
+      },
+      "channels": [
+        {
+          "type": "amazon",
+          "marketplace": "US",
+          "seller_id": "A1B2C3D4E5F6G7"
+        },
+        {
+          "type": "walmart",
+          "marketplace": "US",
+          "seller_id": "101234567"
+        },
+        {
+          "type": "web",
+          "domain": "retailer.example"
+        }
+      ],
+      "scope": {
+        "territories": [
+          "US",
+          "CA"
+        ],
+        "product_lines": [
+          "all"
+        ]
+      },
+      "proposed_by": null,
+      "expires": "2026-12-22T00:00:00Z"
+    }
+  ],
+  "signature": {
+    "kid": "ar-2026-09",
+    "jws": "aGVhZA.cGF5bG9hZA.c2ln"
+  }
+}

package/fixtures/file/invalid/full-authorization-expires-after-file.json

@@ -0,0 +1,46 @@
+{
+  "spec": "authorized-retailers/0.1",
+  "form": "full",
+  "brand": {
+    "name": "Example Brand",
+    "domain": "brand.example"
+  },
+  "issued": "2026-09-23T00:00:00Z",
+  "expires": "2026-12-22T00:00:00Z",
+  "authorizations": [
+    {
+      "id": "auth_01J9X2",
+      "retailer": {
+        "name": "Example Retail LLC",
+        "entity_id": "ent_7Q4M"
+      },
+      "channels": [
+        {
+          "type": "amazon",
+          "marketplace": "US",
+          "seller_id": "A1B2C3D4E5F6G7"
+        },
+        {
+          "type": "walmart",
+          "marketplace": "US",
+          "seller_id": "101234567"
+        },
+        {
+          "type": "web",
+          "domain": "retailer.example"
+        }
+      ],
+      "scope": {
+        "territories": [
+          "US",
+          "CA"
+        ],
+        "product_lines": [
+          "all"
+        ]
+      },
+      "proposed_by": null,
+      "expires": "2026-12-23T00:00:00Z"
+    }
+  ]
+}

package/fixtures/file/invalid/full-duplicate-authorization-id.json

@@ -0,0 +1,80 @@
+{
+  "spec": "authorized-retailers/0.1",
+  "form": "full",
+  "brand": {
+    "name": "Example Brand",
+    "domain": "brand.example"
+  },
+  "issued": "2026-09-23T00:00:00Z",
+  "expires": "2026-12-22T00:00:00Z",
+  "authorizations": [
+    {
+      "id": "auth_01J9X2",
+      "retailer": {
+        "name": "Example Retail LLC",
+        "entity_id": "ent_7Q4M"
+      },
+      "channels": [
+        {
+          "type": "amazon",
+          "marketplace": "US",
+          "seller_id": "A1B2C3D4E5F6G7"
+        },
+        {
+          "type": "walmart",
+          "marketplace": "US",
+          "seller_id": "101234567"
+        },
+        {
+          "type": "web",
+          "domain": "retailer.example"
+        }
+      ],
+      "scope": {
+        "territories": [
+          "US",
+          "CA"
+        ],
+        "product_lines": [
+          "all"
+        ]
+      },
+      "proposed_by": null,
+      "expires": "2026-12-22T00:00:00Z"
+    },
+    {
+      "id": "auth_01J9X2",
+      "retailer": {
+        "name": "Example Retail LLC",
+        "entity_id": "ent_7Q4M"
+      },
+      "channels": [
+        {
+          "type": "amazon",
+          "marketplace": "US",
+          "seller_id": "A1B2C3D4E5F6G7"
+        },
+        {
+          "type": "walmart",
+          "marketplace": "US",
+          "seller_id": "101234567"
+        },
+        {
+          "type": "web",
+          "domain": "retailer.example"
+        }
+      ],
+      "scope": {
+        "territories": [
+          "US",
+          "CA"
+        ],
+        "product_lines": [
+          "all"
+        ]
+      },
+      "proposed_by": null,
+      "expires": "2026-12-22T00:00:00Z"
+    }
+  ]
+}

package/fixtures/file/invalid/full-empty-territories.json

@@ -0,0 +1,43 @@
+{
+  "spec": "authorized-retailers/0.1",
+  "form": "full",
+  "brand": {
+    "name": "Example Brand",
+    "domain": "brand.example"
+  },
+  "issued": "2026-09-23T00:00:00Z",
+  "expires": "2026-12-22T00:00:00Z",
+  "authorizations": [
+    {
+      "id": "auth_01J9X2",
+      "retailer": {
+        "name": "Example Retail LLC",
+        "entity_id": "ent_7Q4M"
+      },
+      "channels": [
+        {
+          "type": "amazon",
+          "marketplace": "US",
+          "seller_id": "A1B2C3D4E5F6G7"
+        },
+        {
+          "type": "walmart",
+          "marketplace": "US",
+          "seller_id": "101234567"
+        },
+        {
+          "type": "web",
+          "domain": "retailer.example"
+        }
+      ],
+      "scope": {
+        "territories": [],
+        "product_lines": [
+          "all"
+        ]
+      },
+      "proposed_by": null,
+      "expires": "2026-12-22T00:00:00Z"
+    }
+  ]
+}

package/fixtures/file/invalid/full-expires-before-issued.json

@@ -0,0 +1,46 @@
+{
+  "spec": "authorized-retailers/0.1",
+  "form": "full",
+  "brand": {
+    "name": "Example Brand",
+    "domain": "brand.example"
+  },
+  "issued": "2026-09-23T00:00:00Z",
+  "expires": "2026-09-22T00:00:00Z",
+  "authorizations": [
+    {
+      "id": "auth_01J9X2",
+      "retailer": {
+        "name": "Example Retail LLC",
+        "entity_id": "ent_7Q4M"
+      },
+      "channels": [
+        {
+          "type": "amazon",
+          "marketplace": "US",
+          "seller_id": "A1B2C3D4E5F6G7"
+        },
+        {
+          "type": "walmart",
+          "marketplace": "US",
+          "seller_id": "101234567"
+        },
+        {
+          "type": "web",
+          "domain": "retailer.example"
+        }
+      ],
+      "scope": {
+        "territories": [
+          "US",
+          "CA"
+        ],
+        "product_lines": [
+          "all"
+        ]
+      },
+      "proposed_by": null,
+      "expires": "2026-09-22T00:00:00Z"
+    }
+  ]
+}