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

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

@@ -1,5 +1,9 @@
 import { createHash } from "crypto";
-import { registerWebBotAuthLegacyOriginGate } from "../signing/web-bot-auth.mjs";
+import {
+  registerWebBotAuthLegacyOriginGate,
+  registerWebBotAuthRevocationCheck,
+  WebBotAuthUnavailableError
+} from "../signing/web-bot-auth.mjs";
 import { RequestSignatureError } from "../signing/errors.mjs";
 import { TaskTypeValues } from "../types/enums.generated.mjs";
 import { AdcpError } from "../server/decisioning/async-outcome.mjs";
@@ -8,7 +12,9 @@ import { markVerifiedHttpSig } from "../server/decisioning/buyer-agent.mjs";
 import { isVerifiedWebBotSigner, WebBotAuthError } from "../signing/web-bot-auth.mjs";
 import {
   authorizeDemandGrant,
-  IdentityAuthorizationError
+  IdentityAuthorizationError,
+  TrustMembershipError,
+  TrustRecordUnavailableError
 } from "./trust.mjs";
 import { MUTATING_TASKS } from "../utils/idempotency.mjs";
 const IDENTITY_ADMIN_TOOLS = /* @__PURE__ */ new Set(["sync_principal", "sync_agent_notification_configs"]);
@@ -26,6 +32,9 @@ function claimFromContext(ctx) {
   const claim = ctx.authInfo?.extra?.identity33;
   return claim && isVerifiedWebBotSigner(claim.signer) ? claim : void 0;
 }
+function anonymousPrincipalFor(origin, prefix = "anonymous") {
+  return `${prefix}:${createHash("sha256").update(origin).digest("hex")}`;
+}
 function isIdentity33UnboundContext(ctx) {
   return claimFromContext(ctx)?.state === "identity-established";
 }
@@ -43,17 +52,44 @@ function createIdentity33PrincipalResolver(options) {
     if (!signers.length || signers.some((s) => !isVerifiedWebBotSigner(s)))
       throw new 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 WebBotAuthUnavailableError("revocation_persistence_failed", error);
+        }
+        if (status === "revoked") throw new WebBotAuthError(403, "key_revoked");
+        if (status === "unknown") throw new 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 TrustMembershipError) binding = void 0;
+        else if (error instanceof TrustRecordUnavailableError)
+          throw new WebBotAuthUnavailableError("trust_record_unavailable", error);
+        else throw error;
+      }
+    }
     if (!binding && operation !== void 0 && typeof operation !== "string")
       throw new WebBotAuthError(400, "operation");
     const authorizationFailure = revoked?.authorizationFailure ?? (!binding && typeof operation === "string" && !anonymousTools.has(operation) ? createWebBotAuthAuthorizationFailure("identity_not_bound") : void 0);
     return {
-      principal: binding?.principalId ?? `${options.anonymousPrincipal ?? "anonymous"}:${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 }
         }
       },
@@ -67,6 +103,7 @@ function createIdentity33PrincipalResolver(options) {
       } : {}
     };
   };
+  if (options.revocation) registerWebBotAuthRevocationCheck(resolver);
   registerWebBotAuthLegacyOriginGate(resolver, async (origin) => {
     if ((await options.lifecycle.getPrincipal(origin)).binding)
       throw new RequestSignatureError(
@@ -78,6 +115,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 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 IdentityAuthorizationError();
+      ctx.authInfo.clientId = binding.principalId;
+      ctx.authInfo.credential = 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 AdcpError("PERMISSION_DENIED", { message: "Agent identity is not onboarded for this operation" });
+  };
   return async (ctx, tool, params) => {
     const identity = claimFromContext(ctx);
     const failure = getWebBotAuthAuthorizationFailure(ctx.authInfo?.extra);
@@ -90,48 +158,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 IdentityAuthorizationError();
-        ctx.authInfo.clientId = binding.principalId;
-        ctx.authInfo.credential = 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 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 IdentityAuthorizationError();
-    for (const claim of claims) {
-      await options.lifecycle.authorizeBound(origin, {
-        sandbox: claim.sandbox,
-        billing: claim.billing,
-        brandDomain: claim.brand.domain
-      });
-      await authorizeDemandGrant({ ...claim, signerOrigin: origin }, options.grants);
+      }
+      const claims = await options.resolveClaims(ctx, tool, params);
+      if (!claims.length) throw new IdentityAuthorizationError();
+      for (const claim of claims) {
+        await options.lifecycle.authorizeBound(origin, {
+          sandbox: claim.sandbox,
+          billing: claim.billing,
+          brandDomain: claim.brand.domain
+        });
+        await authorizeDemandGrant({ ...claim, signerOrigin: origin }, options.grants);
+      }
+    } catch (error) {
+      if (error instanceof TrustRecordUnavailableError)
+        throw new AdcpError("SERVICE_UNAVAILABLE", { message: error.message, recovery: "transient" });
+      if (error instanceof 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;
     }
   };
 }
@@ -152,7 +215,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") {
@@ -176,7 +242,7 @@ function createIdentity33PrincipalScopeResolver(options) {
       return options.legacy(ctx);
     }
     const { binding } = await options.lifecycle.getPrincipal(identity.signer.origin);
-    if (!binding) throw new IdentityAuthorizationError();
+    if (!binding || identity.state !== "bound") throw new IdentityAuthorizationError();
     return {
       tenant_id: options.tenantId,
       principal_id: binding.principalId,

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

@@ -6,6 +6,32 @@ export declare class IdentityAuthorizationError extends Error {
     readonly details: AgentGrantDeniedDetails | undefined;
     constructor(reason?: 'authorization_failed' | 'grant_absent');
 }
+/**
+ * The trust record could not be read (transport error, outage, capacity,
+ * invalid content). A fetch failure is never absence or delisting: spend
+ * fails closed with a retryable SERVICE_UNAVAILABLE, other calls continue
+ * under an existing binding.
+ */
+export declare class TrustRecordUnavailableError extends IdentityAuthorizationError {
+    readonly transient: true;
+    /**
+     * Set by `match()`: the last record read for this operator listed the origin
+     * with the role and is still within the seller's outage bound
+     * (`maxOutageContinuationSeconds` past its freshness). Only then may non-spend
+     * calls continue under a binding.
+     */
+    lastKnownListed: boolean;
+    constructor();
+}
+/**
+ * The operator's last record read does not list the origin with the required
+ * role (`unlisted`; operators retire agents by publishing an empty `agents[]`),
+ * or the operator has never published one (`absent`).
+ */
+export declare class TrustMembershipError extends IdentityAuthorizationError {
+    readonly membership: 'unlisted' | 'absent';
+    constructor(membership?: 'unlisted' | 'absent');
+}
 /** Schema plus semantic checks; publication never includes identity keys. */
 export declare function validateTrustRecord(value: unknown): asserts value is TrustRecord;
 export declare function createTrustRecord(record: TrustRecord): TrustRecord;
@@ -24,9 +50,30 @@ export type TrustFetchResult = {
 export interface TrustEvaluatorOptions {
     /** Matches configured revocation polling: one minute through thirty minutes. */
     pollingIntervalSeconds?: number;
+    /**
+     * Seller policy: how long past the last listing record's freshness a bound
+     * origin's non-spend calls may continue while its operator's record cannot
+     * be read. Spend never continues on an outage. Default four polling
+     * intervals.
+     */
+    maxOutageContinuationSeconds?: number;
     now?: () => number;
     fetchOptions?: Pick<SsrfFetchOptions, 'lookup' | 'trustedFetchFn'>;
     maxEntries?: number;
+    /**
+     * Process-local authority history only: operators remembered per hosting
+     * provider, i.e. per ICANN registrable domain of a PSL PRIVATE-section name
+     * (every `*.vercel.app`, `*.s3.<region>.amazonaws.com` or
+     * `*.<project>.platformsh.site` operator shares one budget). ICANN
+     * registrable domains each count once. Default 32.
+     */
+    maxAuthoritativeOperatorsPerPrivateSuffix?: number;
+    /**
+     * Process-local authority history only: total slots all PRIVATE-section
+     * operators may hold together, so registrants of ICANN domains always keep
+     * headroom. Default half of `maxEntries`.
+     */
+    maxPrivateAuthoritativeOperators?: number;
     maxConcurrentFetches?: number;
     /** Share authoritative-history across restarts/replicas when legacy fallback is enabled. */
     authorityHistory?: {
@@ -41,10 +88,14 @@ export declare class TrustEvaluator {
     private readonly negative;
     private readonly pending;
     private readonly urlRequests;
+    /** Keyed by (operator, host): one operator's authoritative_location hops never spend another's budget. */
     private readonly hostRates;
     private readonly authoritativeOperators;
-    private authorityHistoryOverflowed;
+    /** Remembered authoritative operators per budget group (see authorityGroup). */
+    private readonly authorityGroups;
+    private privateAuthorityOperators;
     readonly pollingIntervalSeconds: number;
+    readonly maxOutageContinuationSeconds: number;
     constructor(options?: TrustEvaluatorOptions);
     get(domainOrOrigin: string, force?: boolean): Promise<TrustFetchResult>;
     match(origin: string, role: string, countries?: readonly string[]): Promise<{
@@ -54,6 +105,16 @@ export declare class TrustEvaluator {
         freshUntil: number;
     }>;
     invalidate(domain: string): void;
+    /**
+     * Record that `operator` served a trust record. With durable history the
+     * in-memory set is only a cache and may evict; without it, nothing is
+     * evicted and an operator over its group budget or the total is refused.
+     */
+    private rememberAuthority;
+    /**
+     * Process-local view only. With durable `authorityHistory` this set is a
+     * cache and may have evicted an operator that durable history still records.
+     */
     hasAuthoritativeRecord(domain: string): boolean;
     private now;
     private request;

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

@@ -6,6 +6,32 @@ export declare class IdentityAuthorizationError extends Error {
     readonly details: AgentGrantDeniedDetails | undefined;
     constructor(reason?: 'authorization_failed' | 'grant_absent');
 }
+/**
+ * The trust record could not be read (transport error, outage, capacity,
+ * invalid content). A fetch failure is never absence or delisting: spend
+ * fails closed with a retryable SERVICE_UNAVAILABLE, other calls continue
+ * under an existing binding.
+ */
+export declare class TrustRecordUnavailableError extends IdentityAuthorizationError {
+    readonly transient: true;
+    /**
+     * Set by `match()`: the last record read for this operator listed the origin
+     * with the role and is still within the seller's outage bound
+     * (`maxOutageContinuationSeconds` past its freshness). Only then may non-spend
+     * calls continue under a binding.
+     */
+    lastKnownListed: boolean;
+    constructor();
+}
+/**
+ * The operator's last record read does not list the origin with the required
+ * role (`unlisted`; operators retire agents by publishing an empty `agents[]`),
+ * or the operator has never published one (`absent`).
+ */
+export declare class TrustMembershipError extends IdentityAuthorizationError {
+    readonly membership: 'unlisted' | 'absent';
+    constructor(membership?: 'unlisted' | 'absent');
+}
 /** Schema plus semantic checks; publication never includes identity keys. */
 export declare function validateTrustRecord(value: unknown): asserts value is TrustRecord;
 export declare function createTrustRecord(record: TrustRecord): TrustRecord;
@@ -24,9 +50,30 @@ export type TrustFetchResult = {
 export interface TrustEvaluatorOptions {
     /** Matches configured revocation polling: one minute through thirty minutes. */
     pollingIntervalSeconds?: number;
+    /**
+     * Seller policy: how long past the last listing record's freshness a bound
+     * origin's non-spend calls may continue while its operator's record cannot
+     * be read. Spend never continues on an outage. Default four polling
+     * intervals.
+     */
+    maxOutageContinuationSeconds?: number;
     now?: () => number;
     fetchOptions?: Pick<SsrfFetchOptions, 'lookup' | 'trustedFetchFn'>;
     maxEntries?: number;
+    /**
+     * Process-local authority history only: operators remembered per hosting
+     * provider, i.e. per ICANN registrable domain of a PSL PRIVATE-section name
+     * (every `*.vercel.app`, `*.s3.<region>.amazonaws.com` or
+     * `*.<project>.platformsh.site` operator shares one budget). ICANN
+     * registrable domains each count once. Default 32.
+     */
+    maxAuthoritativeOperatorsPerPrivateSuffix?: number;
+    /**
+     * Process-local authority history only: total slots all PRIVATE-section
+     * operators may hold together, so registrants of ICANN domains always keep
+     * headroom. Default half of `maxEntries`.
+     */
+    maxPrivateAuthoritativeOperators?: number;
     maxConcurrentFetches?: number;
     /** Share authoritative-history across restarts/replicas when legacy fallback is enabled. */
     authorityHistory?: {
@@ -41,10 +88,14 @@ export declare class TrustEvaluator {
     private readonly negative;
     private readonly pending;
     private readonly urlRequests;
+    /** Keyed by (operator, host): one operator's authoritative_location hops never spend another's budget. */
     private readonly hostRates;
     private readonly authoritativeOperators;
-    private authorityHistoryOverflowed;
+    /** Remembered authoritative operators per budget group (see authorityGroup). */
+    private readonly authorityGroups;
+    private privateAuthorityOperators;
     readonly pollingIntervalSeconds: number;
+    readonly maxOutageContinuationSeconds: number;
     constructor(options?: TrustEvaluatorOptions);
     get(domainOrOrigin: string, force?: boolean): Promise<TrustFetchResult>;
     match(origin: string, role: string, countries?: readonly string[]): Promise<{
@@ -54,6 +105,16 @@ export declare class TrustEvaluator {
         freshUntil: number;
     }>;
     invalidate(domain: string): void;
+    /**
+     * Record that `operator` served a trust record. With durable history the
+     * in-memory set is only a cache and may evict; without it, nothing is
+     * evicted and an operator over its group budget or the total is refused.
+     */
+    private rememberAuthority;
+    /**
+     * Process-local view only. With durable `authorityHistory` this set is a
+     * cache and may have evicted an operator that durable history still records.
+     */
     hasAuthoritativeRecord(domain: string): boolean;
     private now;
     private request;