@adcp/sdk 16.0.0-beta.1 → 16.0.0-beta.3

package/dist/lib/identity-3.3/revocation.mjs

@@ -6,7 +6,7 @@ import { parseStrictJson } from "../signing/agent-resolver/strict-json.mjs";
 import {
   SignatureDirectoryResolver,
   WebBotAuthError,
-  verifySignatureDirectory,
+  WebBotAuthUnavailableError,
   jwkThumbprint
 } from "../signing/web-bot-auth.mjs";
 const REASONS = [
@@ -24,28 +24,51 @@ const REASONS = [
 import { mergeRevocationDetails } from "../signing/revocation.mjs";
 import { mergeRevocationDetails as mergeRevocationDetail } from "../signing/revocation.mjs";
 class InMemoryOriginRevocationStore {
-  constructor(limits = { perOrigin: 16384, total: 1e5 }) {
-    this.limits = limits;
-  }
-  limits;
   durability = "process-local";
   revoked = /* @__PURE__ */ new Map();
+  originKeys = /* @__PURE__ */ new Map();
+  operatorKeys = /* @__PURE__ */ new Map();
+  limits;
+  constructor(limits = {}) {
+    this.limits = {
+      perOrigin: limits.perOrigin ?? 16384,
+      perOperator: limits.perOperator ?? 16384,
+      total: limits.total ?? 1e5
+    };
+    if (Object.values(this.limits).some((value) => !Number.isSafeInteger(value) || value < 1))
+      throw new TypeError("Revocation limits must be positive safe integers");
+  }
   async merge(origin, snapshot) {
     origin = canonicalAgentOrigin(origin);
+    const operator = operatorOf(origin);
     const additions = new Set(snapshot.revoked_kids.filter((kid) => !this.revoked.has(JSON.stringify([origin, kid]))));
-    const count = [...this.revoked.keys()].filter((key) => JSON.parse(key)[0] === origin).length;
-    if (count + additions.size > this.limits.perOrigin || this.revoked.size + additions.size > this.limits.total)
+    const originCount = this.originKeys.get(origin) ?? 0, operatorCount = this.operatorKeys.get(operator) ?? 0;
+    if (originCount + additions.size > this.limits.perOrigin || operatorCount + additions.size > this.limits.perOperator || this.revoked.size + additions.size > this.limits.total)
       throw new WebBotAuthError(403, "revocation_storage_limit");
     for (const kid of snapshot.revoked_kids) {
       const key = JSON.stringify([origin, kid]), prior = this.revoked.get(key), detail = snapshot.revocation_details?.[kid] ?? {};
       this.revoked.set(key, mergeRevocationDetail(prior, detail));
     }
+    if (additions.size) {
+      this.originKeys.set(origin, originCount + additions.size);
+      this.operatorKeys.set(operator, operatorCount + additions.size);
+    }
   }
   async get(origin, keyid) {
     const entry = this.revoked.get(JSON.stringify([canonicalAgentOrigin(origin), keyid]));
     return entry && { ...entry };
   }
 }
+function operatorOf(origin) {
+  try {
+    return eTldPlusOne(origin);
+  } catch {
+    return new URL(origin).hostname;
+  }
+}
+const MAX_POLLING_SECONDS = 1800;
+class RevocationListAbsentError extends Error {
+}
 class OriginRevocationResolver {
   constructor(options) {
     this.options = options;
@@ -61,31 +84,73 @@ class OriginRevocationResolver {
   pending = /* @__PURE__ */ new Map();
   failures = /* @__PURE__ */ new Map();
   persistenceFailures = /* @__PURE__ */ new Set();
+  absentUntil = /* @__PURE__ */ new Map();
+  /**
+   * Compatibility wrapper over {@link status}: `true` when revoked, `false`
+   * when the list is current, and `revocation_unavailable` when the identity
+   * publishes no list (`absent`) or its status is not known (`unknown`).
+   */
   async isRevoked(originUrl, keyid) {
+    const state = await this.status(originUrl, keyid);
+    if (state === "revoked") return true;
+    if (state === "current") return false;
+    throw new WebBotAuthError(403, state === "absent" ? "revocation_absent" : "revocation_unavailable");
+  }
+  /**
+   * Revocation status of `keyid` at `origin`:
+   * - `revoked`: a stored (permanent) revocation covers the key.
+   * - `current`: a signed list is current, or within `next_update` + grace.
+   * - `absent`: the origin serves no list (404/410). The identity is still
+   *   established but cannot be bound for spend.
+   * - `unknown`: no list could be verified and grace has passed (or there was
+   *   never a list). The identity is not established.
+   * Throws {@link WebBotAuthUnavailableError} (`revocation_persistence_failed`)
+   * when the history store fails: an infrastructure outage, never a
+   * revocation outcome.
+   */
+  async status(originUrl, keyid) {
+    try {
+      return await this.currentStatus(originUrl, keyid);
+    } catch (error) {
+      if (error instanceof WebBotAuthError && error.reason === "revocation_persistence_failed")
+        throw new WebBotAuthUnavailableError("revocation_persistence_failed", error);
+      throw error;
+    }
+  }
+  async currentStatus(originUrl, keyid) {
     const origin = canonicalAgentOrigin(originUrl), now = this.now();
-    if (await this.readStored(origin, keyid)) return true;
+    if (await this.readStored(origin, keyid)) return "revoked";
+    const settled = async () => {
+      if (await this.readStored(origin, keyid)) return "revoked";
+      if ((this.absentUntil.get(origin) ?? 0) > now) return "absent";
+      return (this.freshness.get(origin) ?? 0) > now || (this.graceUntil.get(origin) ?? 0) > now ? "current" : "unknown";
+    };
     if ((this.freshness.get(origin) ?? 0) <= now) {
       if ((this.failures.get(origin) ?? 0) > now) {
         if (this.persistenceFailures.has(origin)) throw new WebBotAuthError(403, "revocation_persistence_failed");
-        if ((this.graceUntil.get(origin) ?? 0) > now) return false;
-        throw new WebBotAuthError(403, "revocation_unavailable");
+        return settled();
       }
       let promise = this.pending.get(origin);
       if (!promise) {
-        if (this.pending.size >= 16 || [...this.pending.keys()].filter((pendingOrigin) => eTldPlusOne(pendingOrigin) === eTldPlusOne(origin)).length >= 2) {
-          throw new WebBotAuthError(403, "revocation_unavailable");
+        if (this.pending.size >= 16 || [...this.pending.keys()].filter((pendingOrigin) => operatorOf(pendingOrigin) === operatorOf(origin)).length >= 2) {
+          return settled();
         }
         promise = this.refresh(origin).catch((error) => {
           if (this.failures.size >= (this.options.maxOrigins ?? 1e3)) {
             const oldest = this.failures.keys().next().value;
             this.failures.delete(oldest);
             this.persistenceFailures.delete(oldest);
+            this.absentUntil.delete(oldest);
           }
           this.failures.set(origin, now + 60);
           if (error instanceof WebBotAuthError && error.reason === "revocation_persistence_failed") {
             this.persistenceFailures.add(origin);
             this.graceUntil.delete(origin);
           }
+          if (error.cause instanceof RevocationListAbsentError) {
+            this.absentUntil.set(origin, now + 60);
+            this.graceUntil.delete(origin);
+          }
           throw error;
         });
         this.pending.set(origin, promise);
@@ -94,12 +159,11 @@ class OriginRevocationResolver {
         await promise;
       } catch (error) {
         if (error instanceof WebBotAuthError && error.reason === "revocation_persistence_failed") throw error;
-        if ((this.graceUntil.get(origin) ?? 0) <= now) throw error;
       } finally {
         if (this.pending.get(origin) === promise) this.pending.delete(origin);
       }
     }
-    return !!await this.readStored(origin, keyid);
+    return settled();
   }
   async readStored(origin, keyid) {
     try {
@@ -117,6 +181,7 @@ class OriginRevocationResolver {
         maxBodyBytes: 256 * 1024,
         timeoutMs: 1e4
       });
+      if (response.status === 404 || response.status === 410) throw new RevocationListAbsentError();
       if (response.status !== 200) throw new Error("Unavailable revocation list");
       const body = new TextDecoder("utf-8", { fatal: true }).decode(response.body);
       let tokens;
@@ -142,9 +207,9 @@ class OriginRevocationResolver {
           if (header.typ !== "adcp-gov-revocation+jws" || typeof header.kid !== "string" || typeof header.alg !== "string" || !["EdDSA", "ES256"].includes(header.alg))
             continue;
           await this.options.directory.resolve(header.kid, origin);
-          const proof = this.options.directory.getAuditProof(origin);
-          if (!proof || new URL(proof.request.url).origin !== origin) continue;
-          const checked = verifySignatureDirectory(proof, this.now(), this.options.directory.allowsTestKeys);
+          const checked = this.options.directory.getVerifiedDirectory(origin);
+          if (!checked || new URL(checked.proof.request.url).origin !== origin || checked.expires <= this.now())
+            continue;
           const jwk = checked.keys.find((key) => key.kid === header.kid);
           if (!jwk) continue;
           const result = await compactVerify(token, await importJWK(jwk, header.alg), {
@@ -161,7 +226,8 @@ class OriginRevocationResolver {
         32
       );
       const updated = Date.parse(snapshot.updated) / 1e3, next = Date.parse(snapshot.next_update) / 1e3, now = this.now();
-      if (snapshot.issuer !== origin || !Number.isFinite(updated) || !Number.isFinite(next) || updated > now || next <= now || next <= updated || next > now + 1800 || !Array.isArray(snapshot.revoked_kids) || snapshot.revoked_kids.length > 4096 || snapshot.revoked_kids.some((k) => typeof k !== "string" || k.length > 256) || updated < (this.updated.get(origin) ?? 0))
+      if (snapshot.issuer !== origin || !Number.isFinite(updated) || !Number.isFinite(next) || // Tolerate a publisher clock slightly ahead, as for request `created`.
+      updated > now + 60 || next <= now || next <= updated || !Array.isArray(snapshot.revoked_kids) || snapshot.revoked_kids.length > 4096 || snapshot.revoked_kids.some((k) => typeof k !== "string" || k.length > 256) || updated < (this.updated.get(origin) ?? 0))
         throw new Error("Invalid revocation snapshot");
       for (const [kid, detail] of Object.entries(snapshot.revocation_details ?? {}))
         if (!snapshot.revoked_kids.includes(kid) || !detail || detail.reason && !REASONS.includes(detail.reason) || detail.invalidity_date && !Number.isFinite(Date.parse(detail.invalidity_date)))
@@ -179,11 +245,15 @@ class OriginRevocationResolver {
         this.updated.delete(oldest);
         this.graceUntil.delete(oldest);
       }
-      this.graceUntil.set(origin, next + 4 * (this.options.pollingIntervalSeconds ?? 300));
+      this.graceUntil.set(
+        origin,
+        Math.min(next, now + MAX_POLLING_SECONDS) + 4 * (this.options.pollingIntervalSeconds ?? 300)
+      );
       this.updated.set(origin, updated);
       this.freshness.set(origin, Math.min(next, now + (this.options.pollingIntervalSeconds ?? 300)));
       this.failures.delete(origin);
       this.persistenceFailures.delete(origin);
+      this.absentUntil.delete(origin);
     } catch (cause) {
       if (cause instanceof WebBotAuthError && cause.reason === "revocation_persistence_failed") throw cause;
       const error = new WebBotAuthError(403, "revocation_unavailable");

package/dist/lib/identity-3.3/server.d.mts

@@ -1,3 +1,4 @@
+import type { OriginRevocationStatus } from './revocation.mjs';
 import type { AuthPrincipal } from '../server/auth.mjs';
 import type { HandlerContext, ProtocolHandlers } from '../server/create-adcp-server.mjs';
 import { type VerifiedWebBotSigner } from '../signing/web-bot-auth.mjs';
@@ -10,6 +11,17 @@ export declare function createIdentity33PrincipalResolver(options: {
     lifecycle: OriginIdentityLifecycle;
     anonymousPrincipal?: string;
     anonymousTools?: readonly string[];
+    /**
+     * Origin revocation, checked here (the identity layer), not during signature
+     * verification. A revoked key is refused without a challenge; unknown
+     * status leaves the identity unverified; an origin serving no list stays
+     * identity-established and cannot be bound or spend. Usually an
+     * `OriginRevocationResolver`. Without it, the server must supply the
+     * deprecated `webBotAuth.isRevoked`.
+     */
+    revocation?: {
+        status(origin: string, keyid: string): Promise<OriginRevocationStatus>;
+    };
 }): (signers: readonly VerifiedWebBotSigner[], operation: ResolvedOperation) => Promise<AuthPrincipal>;
 /** Pass to createAdcpServer.identity33.authorize; framework runs it before its replay cache. */
 export declare function createIdentity33Authorization<TAccount>(options: {

package/dist/lib/identity-3.3/server.d.ts

@@ -1,3 +1,4 @@
+import type { OriginRevocationStatus } from './revocation';
 import type { AuthPrincipal } from '../server/auth';
 import type { HandlerContext, ProtocolHandlers } from '../server/create-adcp-server';
 import { type VerifiedWebBotSigner } from '../signing/web-bot-auth';
@@ -10,6 +11,17 @@ export declare function createIdentity33PrincipalResolver(options: {
     lifecycle: OriginIdentityLifecycle;
     anonymousPrincipal?: string;
     anonymousTools?: readonly string[];
+    /**
+     * Origin revocation, checked here (the identity layer), not during signature
+     * verification. A revoked key is refused without a challenge; unknown
+     * status leaves the identity unverified; an origin serving no list stays
+     * identity-established and cannot be bound or spend. Usually an
+     * `OriginRevocationResolver`. Without it, the server must supply the
+     * deprecated `webBotAuth.isRevoked`.
+     */
+    revocation?: {
+        status(origin: string, keyid: string): Promise<OriginRevocationStatus>;
+    };
 }): (signers: readonly VerifiedWebBotSigner[], operation: ResolvedOperation) => Promise<AuthPrincipal>;
 /** Pass to createAdcpServer.identity33.authorize; framework runs it before its replay cache. */
 export declare function createIdentity33Authorization<TAccount>(options: {

package/dist/lib/identity-3.3/server.js

@@ -50,6 +50,9 @@ function claimFromContext(ctx) {
   const claim = ctx.authInfo?.extra?.identity33;
   return claim && (0, import_web_bot_auth3.isVerifiedWebBotSigner)(claim.signer) ? claim : void 0;
 }
+function anonymousPrincipalFor(origin, prefix = "anonymous") {
+  return `${prefix}:${(0, import_crypto.createHash)("sha256").update(origin).digest("hex")}`;
+}
 function isIdentity33UnboundContext(ctx) {
   return claimFromContext(ctx)?.state === "identity-established";
 }
@@ -67,17 +70,44 @@ function createIdentity33PrincipalResolver(options) {
     if (!signers.length || signers.some((s) => !(0, import_web_bot_auth3.isVerifiedWebBotSigner)(s)))
       throw new import_web_bot_auth3.WebBotAuthError(403, "unverified_identity");
     const signer = signers[signers.length - 1];
+    let revocation;
+    if (options.revocation) {
+      revocation = "current";
+      for (const each of signers) {
+        let status;
+        try {
+          status = await options.revocation.status(each.origin, each.keyid);
+        } catch (error) {
+          throw new import_web_bot_auth.WebBotAuthUnavailableError("revocation_persistence_failed", error);
+        }
+        if (status === "revoked") throw new import_web_bot_auth3.WebBotAuthError(403, "key_revoked");
+        if (status === "unknown") throw new import_web_bot_auth3.WebBotAuthError(403, "identity_unverified");
+        if (status === "absent") revocation = "absent";
+      }
+    }
     const revoked = signers.find((s) => s.authorizationFailure);
-    const { binding } = revoked ? { binding: void 0 } : await options.lifecycle.getPrincipal(signer.origin);
+    let { binding } = revoked || revocation === "absent" ? { binding: void 0 } : await options.lifecycle.getPrincipal(signer.origin);
+    if (binding) {
+      try {
+        await options.lifecycle.authorizeBound(signer.origin, { readOnly: true });
+      } catch (error) {
+        if (error instanceof import_trust.TrustMembershipError) binding = void 0;
+        else if (error instanceof import_trust.TrustRecordUnavailableError)
+          throw new import_web_bot_auth.WebBotAuthUnavailableError("trust_record_unavailable", error);
+        else throw error;
+      }
+    }
     if (!binding && operation !== void 0 && typeof operation !== "string")
       throw new import_web_bot_auth3.WebBotAuthError(400, "operation");
     const authorizationFailure = revoked?.authorizationFailure ?? (!binding && typeof operation === "string" && !anonymousTools.has(operation) ? (0, import_web_bot_auth2.createWebBotAuthAuthorizationFailure)("identity_not_bound") : void 0);
     return {
-      principal: binding?.principalId ?? `${options.anonymousPrincipal ?? "anonymous"}:${(0, import_crypto.createHash)("sha256").update(signer.origin).digest("hex")}`,
+      principal: binding?.principalId ?? anonymousPrincipalFor(signer.origin, options.anonymousPrincipal),
       extra: {
         identity33: {
           state: binding ? "bound" : "identity-established",
           signer: revoked ?? signer,
+          ...revocation && { revocation },
+          anonymousPrincipal: anonymousPrincipalFor(signer.origin, options.anonymousPrincipal),
           ...authorizationFailure && { authorizationFailure }
         }
       },
@@ -91,6 +121,7 @@ function createIdentity33PrincipalResolver(options) {
       } : {}
     };
   };
+  if (options.revocation) (0, import_web_bot_auth.registerWebBotAuthRevocationCheck)(resolver);
   (0, import_web_bot_auth.registerWebBotAuthLegacyOriginGate)(resolver, async (origin) => {
     if ((await options.lifecycle.getPrincipal(origin)).binding)
       throw new import_errors.RequestSignatureError(
@@ -102,6 +133,37 @@ function createIdentity33PrincipalResolver(options) {
   return resolver;
 }
 function createIdentity33Authorization(options) {
+  const anonymousTools = options.anonymousTools ?? [
+    "get_principal",
+    "get_adcp_capabilities",
+    "list_creative_formats",
+    "get_products"
+  ];
+  const authorizeUnbound = async (ctx, identity, tool, params) => {
+    if (tool === "sync_principal") {
+      if (identity.revocation === "absent")
+        throw new import_async_outcome.AdcpError("PERMISSION_DENIED", { message: "Agent identity cannot be onboarded" });
+      const dryRun = !!params && typeof params === "object" && params.dry_run === true;
+      const binding = await options.lifecycle.syncOpen(identity.signer.origin, { dryRun });
+      if (dryRun) return;
+      if (!ctx.authInfo) throw new import_trust.IdentityAuthorizationError();
+      ctx.authInfo.clientId = binding.principalId;
+      ctx.authInfo.credential = (0, import_buyer_agent.markVerifiedHttpSig)({
+        kind: "http_sig",
+        keyid: identity.signer.keyid,
+        agent_url: identity.signer.origin,
+        verified_at: identity.signer.verified_at
+      });
+      ctx.authInfo.extra = {
+        ...ctx.authInfo.extra,
+        credential: ctx.authInfo.credential,
+        identity33: { ...identity, state: "bound" }
+      };
+      return;
+    }
+    if (anonymousTools.includes(tool) && !needsSpendAuthorization(tool, params)) return;
+    throw new import_async_outcome.AdcpError("PERMISSION_DENIED", { message: "Agent identity is not onboarded for this operation" });
+  };
   return async (ctx, tool, params) => {
     const identity = claimFromContext(ctx);
     const failure = (0, import_web_bot_auth2.getWebBotAuthAuthorizationFailure)(ctx.authInfo?.extra);
@@ -114,48 +176,43 @@ function createIdentity33Authorization(options) {
         });
       return;
     }
-    if (identity.state === "identity-established") {
-      if (tool === "sync_principal") {
-        const dryRun = !!params && typeof params === "object" && params.dry_run === true;
-        const binding = await options.lifecycle.syncOpen(identity.signer.origin, { dryRun });
-        if (dryRun) return;
-        if (!ctx.authInfo) throw new import_trust.IdentityAuthorizationError();
-        ctx.authInfo.clientId = binding.principalId;
-        ctx.authInfo.credential = (0, import_buyer_agent.markVerifiedHttpSig)({
-          kind: "http_sig",
-          keyid: identity.signer.keyid,
-          agent_url: identity.signer.origin,
-          verified_at: identity.signer.verified_at
-        });
-        ctx.authInfo.extra = {
-          ...ctx.authInfo.extra,
-          credential: ctx.authInfo.credential,
-          identity33: { ...identity, state: "bound" }
-        };
+    if (identity.state === "identity-established") return authorizeUnbound(ctx, identity, tool, params);
+    const origin = identity.signer.origin;
+    const spend = !IDENTITY_ADMIN_TOOLS.has(tool) && needsSpendAuthorization(tool, params) && !(!KNOWN_TOOLS.has(tool) && options.readOnlyTools?.includes(tool));
+    try {
+      if (IDENTITY_ADMIN_TOOLS.has(tool)) {
+        await options.lifecycle.authorizeBound(origin, { identityConfiguration: true });
         return;
       }
-      if ((options.anonymousTools ?? ["get_principal", "get_adcp_capabilities", "list_creative_formats", "get_products"]).includes(tool) && !needsSpendAuthorization(tool, params))
+      if (!spend) {
+        await options.lifecycle.authorizeBound(origin, { readOnly: true });
         return;
-      throw new import_async_outcome.AdcpError("PERMISSION_DENIED", { message: "Agent identity is not onboarded for this operation" });
-    }
-    const origin = identity.signer.origin;
-    if (IDENTITY_ADMIN_TOOLS.has(tool)) {
-      await options.lifecycle.authorizeBound(origin, { identityConfiguration: true });
-      return;
-    }
-    if (!needsSpendAuthorization(tool, params) || !KNOWN_TOOLS.has(tool) && options.readOnlyTools?.includes(tool)) {
-      await options.lifecycle.authorizeBound(origin, { readOnly: true });
-      return;
-    }
-    const claims = await options.resolveClaims(ctx, tool, params);
-    if (!claims.length) throw new import_trust.IdentityAuthorizationError();
-    for (const claim of claims) {
-      await options.lifecycle.authorizeBound(origin, {
-        sandbox: claim.sandbox,
-        billing: claim.billing,
-        brandDomain: claim.brand.domain
-      });
-      await (0, import_trust.authorizeDemandGrant)({ ...claim, signerOrigin: origin }, options.grants);
+      }
+      const claims = await options.resolveClaims(ctx, tool, params);
+      if (!claims.length) throw new import_trust.IdentityAuthorizationError();
+      for (const claim of claims) {
+        await options.lifecycle.authorizeBound(origin, {
+          sandbox: claim.sandbox,
+          billing: claim.billing,
+          brandDomain: claim.brand.domain
+        });
+        await (0, import_trust.authorizeDemandGrant)({ ...claim, signerOrigin: origin }, options.grants);
+      }
+    } catch (error) {
+      if (error instanceof import_trust.TrustRecordUnavailableError)
+        throw new import_async_outcome.AdcpError("SERVICE_UNAVAILABLE", { message: error.message, recovery: "transient" });
+      if (error instanceof import_trust.TrustMembershipError && !spend) {
+        const demoted = { ...identity, state: "identity-established" };
+        if (ctx.authInfo) {
+          const { credential: _credential, ...extra } = ctx.authInfo.extra ?? {};
+          ctx.authInfo.clientId = identity.anonymousPrincipal ?? anonymousPrincipalFor(origin);
+          delete ctx.authInfo.credential;
+          ctx.authInfo.extra = { ...extra, identity33: demoted };
+        }
+        delete ctx.agent;
+        return authorizeUnbound(ctx, demoted, tool, params);
+      }
+      throw error;
     }
   };
 }
@@ -176,7 +233,10 @@ function withIdentity33PrincipalHandlers(base, lifecycle) {
         return base.getPrincipal(params, ctx);
       }
       const read = await lifecycle.getPrincipal(identity.signer.origin);
-      if (!read.binding) return { result: read.result };
+      if (!read.binding || identity.state === "identity-established")
+        return {
+          result: { kind: "unconfigured", ...read.result.relationship && { relationship: read.result.relationship } }
+        };
       if (!base.getPrincipal) return { result: read.result };
       const response = await base.getPrincipal(params, ctx);
       if (read.result.relationship && response && typeof response === "object") {
@@ -200,7 +260,7 @@ function createIdentity33PrincipalScopeResolver(options) {
       return options.legacy(ctx);
     }
     const { binding } = await options.lifecycle.getPrincipal(identity.signer.origin);
-    if (!binding) throw new import_trust.IdentityAuthorizationError();
+    if (!binding || identity.state !== "bound") throw new import_trust.IdentityAuthorizationError();
     return {
       tenant_id: options.tenantId,
       principal_id: binding.principalId,