@adcp/sdk 6.6.0 → 6.8.0

package/dist/lib/server/decisioning/account.d.ts

@@ -11,8 +11,9 @@
  *
  * @public
  */
-import type { BrandReference, AccountReference, ReportUsageRequest, ReportUsageResponse, GetAccountFinancialsRequest, GetAccountFinancialsSuccess } from '../../types/tools.generated';
+import type { Account as WireAccount, AccountScope, BillingParty, BrandReference, AccountReference, BusinessEntity, ExtensionObject, PaymentTerms, ReportUsageRequest, ReportUsageResponse, SyncAccountsSuccess, SyncGovernanceRequest, SyncGovernanceSuccess, GetAccountFinancialsRequest, GetAccountFinancialsSuccess } from '../../types/tools.generated';
 import type { CursorPage, CursorRequest } from './pagination';
+import type { AdcpCredential, BuyerAgent } from './buyer-agent';
 /**
  * Account — framework's rich representation. A strict superset of the wire
  * `Account` shape (from `list_accounts` / response envelopes):
@@ -44,6 +45,13 @@ export interface Account<TCtxMeta = Record<string, unknown>> {
      * behalf of an advertiser whose rates differ from the operator's.
      */
     advertiser?: string;
+    /**
+     * Optional intermediary who receives invoices on behalf of the advertiser
+     * (e.g., agency holdco). Distinct from `advertiser` (whose rates apply)
+     * and from `billing.invoicedTo` (the legal billing party). Use when the
+     * invoice recipient differs from both — common in agency-handled flows.
+     */
+    billing_proxy?: string;
     /**
      * Settlement boundary for operator-billed retail-media platforms.
      * `'agent'` = pass-through (buyer's agent settles directly with the platform).
@@ -57,6 +65,70 @@ export interface Account<TCtxMeta = Record<string, unknown>> {
     billing?: {
         invoicedTo: 'agent' | 'operator' | BrandReference;
     };
+    /**
+     * Business entity invoiced on this account. Carries legal name, tax IDs,
+     * address, contacts, and (write-only) bank details for B2B invoicing.
+     *
+     * **`bank` is write-only.** The wire schema marks `BusinessEntity.bank` as
+     * MUST NOT be echoed in responses (sellers store and confirm receipt
+     * without returning the details). `toWireAccount` strips it on emit, so
+     * adopters who store the full entity here will not leak bank details to
+     * buyers — but DO NOT rely on the strip for anything beyond response
+     * projection. Adopters loading the entity from their own DB SHOULD apply
+     * the same rule at retrieval time, especially for non-list endpoints.
+     */
+    billing_entity?: BusinessEntity;
+    /**
+     * Identifier for the rate card applied to this account. Opaque seller-side
+     * string; emitted unchanged on the wire.
+     */
+    rate_card?: string;
+    /** Payment terms applied to this account. */
+    payment_terms?: PaymentTerms;
+    /** Maximum outstanding balance allowed on this account. */
+    credit_limit?: WireAccount['credit_limit'];
+    /**
+     * Setup payload for accounts in `pending_approval`. Carries the URL/message
+     * the buyer surfaces to a human to complete activation (credit-app, legal
+     * agreement, fund-add). Required-shape: `message` is mandatory; `url` and
+     * `expires_at` are optional.
+     *
+     * The framework does NOT validate that `setup` is populated when status is
+     * `pending_approval` — that's an adopter contract with the spec. It also
+     * does NOT clear `setup` when status leaves `pending_approval`; adopters
+     * who echo the same `Account` across status transitions should drop the
+     * field themselves.
+     */
+    setup?: WireAccount['setup'];
+    /** Account scope (operator / brand / operator_brand / agent). */
+    account_scope?: AccountScope;
+    /**
+     * Governance agent endpoints registered on this account. Auth credentials
+     * are write-only on the wire and not modeled here — adopters set/update
+     * via `sync_governance`, not by re-emitting the Account.
+     */
+    governance_agents?: WireAccount['governance_agents'];
+    /**
+     * Cloud storage bucket for offline reporting delivery. Only present when
+     * the seller's capabilities advertise `reporting_delivery_methods`
+     * including `'offline'`. Per-account access MUST be IAM-scoped — see the
+     * schema description for security constraints.
+     */
+    reporting_bucket?: WireAccount['reporting_bucket'];
+    /**
+     * Sandbox account marker. For implicit accounts the wire schema treats
+     * this as part of the natural key — the same brand/operator pair can have
+     * separate production and sandbox accounts. For explicit accounts, sandbox
+     * accounts are pre-existing test accounts the seller surfaces via
+     * `list_accounts`.
+     */
+    sandbox?: boolean;
+    /**
+     * Wire `ext` extension hatch. Carries forward-compatible additions the
+     * codegen'd type doesn't model yet. Adopters who don't need extensions
+     * leave this undefined.
+     */
+    ext?: ExtensionObject;
     /**
      * Adapter-internal opaque state. Framework doesn't read this; **stripped
      * before emitting on the wire**. GAM puts `{ networkId, advertiserId }`;
@@ -72,10 +144,33 @@ export interface Account<TCtxMeta = Record<string, unknown>> {
      * where the SDK bridges between `getProducts` and `createMediaBuy`).
      * Put adapter state in `ctx_metadata`; treat it as fresh from your
      * `accounts.resolve()` on every request.
+     *
+     * **DO NOT put credentials here.** The wire-strip protects buyer
+     * responses but does NOT protect server-side log lines, error
+     * envelopes (when `exposeErrorDetails: true`), heap dumps, or
+     * adopter-generated strings (`JSON.stringify(account)` in an error
+     * message). Bearer tokens, OAuth refresh tokens, API keys, and
+     * client secrets belong on `authInfo` (which the framework
+     * round-trips through `refreshToken`) or in your own per-principal
+     * token cache — NOT in `ctx_metadata`. See
+     * [`docs/guides/CTX-METADATA-SAFETY.md`](../../../../docs/guides/CTX-METADATA-SAFETY.md)
+     * for the full guidance and the recommended re-derive-per-request
+     * pattern.
      */
     ctx_metadata: TCtxMeta;
-    /** Caller's authenticated principal. **Stripped before emitting on the wire.** */
-    authInfo: AuthPrincipal;
+    /**
+     * Caller's authenticated principal. **Stripped before emitting on the wire.**
+     *
+     * Optional from the adopter's perspective: when `accounts.resolve` returns
+     * an `Account` without `authInfo`, the framework auto-attaches the
+     * principal from `ctx.authInfo` (the auth shape extracted by
+     * `serve({ authenticate })`). Adopters that need to *transform* the
+     * principal — e.g. derive a tenant-scoped sub-principal from the OAuth
+     * client — set it explicitly; adopters that just want the
+     * `serve({ authenticate })` principal threaded through resource handlers
+     * can omit the field and rely on the framework default.
+     */
+    authInfo?: AuthPrincipal;
 }
 /**
  * The OAuth-style auth shape extracted by `serve({ authenticate })`. Threaded
@@ -90,9 +185,47 @@ export interface Account<TCtxMeta = Record<string, unknown>> {
  * @public
  */
 export interface ResolvedAuthInfo {
-    token: string;
-    clientId: string;
-    scopes: string[];
+    /**
+     * Kind-discriminated credential — Phase 1 Stage 3 of #1269. Populated by
+     * the framework's built-in authenticators (`verifyApiKey`, `verifyBearer`,
+     * `verifySignatureAsAuthenticator`); custom `authenticate` callbacks can
+     * stamp this directly on the returned `AuthPrincipal` to opt into the
+     * discriminated-credential surface. The framework propagates it from
+     * `req.auth.extra.credential` to this top-level field on every request.
+     *
+     * **Verified vs. claimed.** `credential.kind === 'http_sig'` carries an
+     * `agent_url` that is cryptographically verified by the framework's
+     * signature verifier (per adcontextprotocol/adcp#3831). The framework
+     * brands verified credentials with a module-private symbol that
+     * `BuyerAgentRegistry` factories check before treating the credential
+     * as authentic — a literal-shape `{ kind: 'http_sig', ... }` synthesized
+     * by a custom authenticator is rejected at the registry layer. Adopters
+     * making security-relevant decisions on `agent_url` MUST read it from
+     * the credential variant; framework-stamped registry-derived URLs are
+     * exposed via `ctx.agent.agent_url` only.
+     */
+    credential?: AdcpCredential;
+    /**
+     * Optional operator seat within the buyer agent. Stamped only when the
+     * authenticator's claims include a `sub` / `oid` / equivalent identifying
+     * a sub-principal within the agent. Reserved for future use; v1 of
+     * `BuyerAgentRegistry` doesn't consume it.
+     */
+    operator?: string;
+    /**
+     * @deprecated Use `credential.kind === 'oauth' ? credential.client_id : ...`
+     * for the discriminated shape. Optional in N+1 of the deprecation cycle
+     * per #1269; framework continues to populate it for adopter compatibility
+     * through the cycle. Removed in N+2.
+     */
+    token?: string;
+    /**
+     * @deprecated Use `credential.client_id` (oauth) or `credential.key_id`
+     * (api_key) instead.
+     */
+    clientId?: string;
+    /** @deprecated Use `credential.scopes` (oauth) instead. */
+    scopes?: string[];
     expiresAt?: number;
     extra?: Record<string, unknown>;
 }
@@ -101,6 +234,16 @@ export interface ResolveContext {
     authInfo?: ResolvedAuthInfo;
     /** Tool the buyer is calling — useful for tool-aware tenant routing. */
     toolName?: string;
+    /**
+     * Resolved buyer agent from `BuyerAgentRegistry.resolve()`, when an
+     * `agentRegistry` is configured (Phase 1 of #1269). The framework calls
+     * the registry once per request before `accounts.resolve` and threads the
+     * resolved record here so adopters can route tenant resolution against
+     * the durable buyer-agent identity rather than re-deriving it from
+     * `authInfo`. Undefined when no registry is configured OR when the
+     * registry returns null for the request's credential.
+     */
+    agent?: BuyerAgent;
 }
 /**
  * Context passed to AccountStore tool methods that operate on a single
@@ -125,6 +268,43 @@ export interface AccountToolContext<TCtxMeta = Record<string, unknown>> extends
     /** Resolved Account from `accounts.resolve()`. Populated by the framework before dispatch. */
     account: Account<TCtxMeta>;
 }
+/**
+ * Request context for tools whose wire request does not carry an `account`
+ * field — `preview_creative`, `list_creative_formats`, and
+ * `provide_performance_feedback`. The framework calls
+ * `accounts.resolve(undefined, ctx)` for these, accepting a `null` return; if
+ * `null`, `ctx.account` is undefined when the handler runs.
+ *
+ * Adopter handlers MUST handle the `undefined` case explicitly. Choose one of:
+ *
+ *   1. **Singleton fallback** — return a non-null synthetic `Account` from
+ *      `accounts.resolve(undefined, ctx)` for the publisher-wide tenant
+ *      (e.g., format catalog, performance feedback aggregation). Inside the
+ *      handler, narrow with `if (!ctx.account) throw ...` once and treat
+ *      `ctx.account` as defined for the rest.
+ *   2. **Auth-derived lookup** — in `accounts.resolve(undefined, ctx)`, look
+ *      up by `ctx.authInfo.clientId` (or whichever principal field your auth
+ *      wires) and return the matching account.
+ *   3. **Error out** — throw `AdcpError({ code: 'ACCOUNT_NOT_FOUND' })` from
+ *      within the handler when `ctx.account == null` and the operation
+ *      requires tenant scoping.
+ *
+ * The narrowed type catches the mismatch at authorship time — adopters who
+ * forget to handle `ctx.account === undefined` get a TS error, not a runtime
+ * `Cannot read properties of undefined` deep in their upstream call. Same
+ * shape as the `definePlatformWithCompliance` invariant: convert a runtime
+ * gate into a compile-time one.
+ *
+ * @public
+ */
+export type NoAccountCtx<TCtxMeta = Record<string, unknown>> = Omit<import('./context').RequestContext<Account<TCtxMeta>>, 'account'> & {
+    /**
+     * Resolved account, OR `undefined` when the wire request didn't carry an
+     * account ref AND `accounts.resolve(undefined, ctx)` returned null. Always
+     * narrow before reading `ctx_metadata` / `id`.
+     */
+    account: Account<TCtxMeta> | undefined;
+};
 export interface AuthPrincipal {
     /** Stable identifier for the calling agent (e.g., `https://buyer.example.com/mcp`). */
     agent_url?: string;
@@ -147,10 +327,18 @@ export interface AccountStore<TCtxMeta = Record<string, unknown>> {
      * - `'implicit'` — buyer must `sync_accounts` first; subsequent requests are
      *   resolved from the auth principal's pre-synced linkage (LinkedIn, some
      *   retail-media operators). Framework refuses inline `account_id` references
-     *   for these platforms.
+     *   for these platforms — emits `AdcpError('INVALID_REQUEST', { field:
+     *   'account.account_id' })` before reaching `accounts.resolve`. The
+     *   brand+operator union arm is permitted (used during the initial
+     *   `sync_accounts` flow); only `account_id`-shaped references are rejected.
      * - `'derived'` — single-tenant agents where there is no account_id on the
      *   wire at all and the auth principal alone identifies the tenant. Most
      *   self-hosted broadcasters and retail-media operators in proxy mode.
+     *   Framework refuses inline `account_id` references for these platforms —
+     *   same `AdcpError('INVALID_REQUEST', { field: 'account.account_id' })`
+     *   shape as `'implicit'`, but with a single-tenant message instead of the
+     *   `sync_accounts`-first guidance (no `sync_accounts` step exists in
+     *   derived mode). The brand+operator union arm is permitted.
      *
      * Defaults to `'explicit'` when omitted.
      */
@@ -176,7 +364,11 @@ export interface AccountStore<TCtxMeta = Record<string, unknown>> {
      * ```ts
      * resolve: async (ref, ctx) => {
      *   if (ref?.account_id) return await this.db.findById(ref.account_id);
-     *   const platformAcct = await myUpstream.findByOAuthClient(ctx?.authInfo?.clientId);
+     *   const cred = ctx?.authInfo?.credential;
+     *   const clientKey = cred?.kind === 'oauth' ? cred.client_id
+     *     : cred?.kind === 'api_key' ? cred.key_id
+     *     : undefined;
+     *   const platformAcct = clientKey ? await myUpstream.findByClientKey(clientKey) : null;
      *   return platformAcct ? this.toAccount(platformAcct) : null;
      * }
      * ```
@@ -200,14 +392,72 @@ export interface AccountStore<TCtxMeta = Record<string, unknown>> {
      * **Optional.** Stateless platforms (creative-template, signal-marketplace
      * proxies) that don't manage account lifecycle can omit this; framework
      * surfaces `UNSUPPORTED_FEATURE` to buyers calling `sync_accounts`.
+     *
+     * `ctx.authInfo` carries the caller's authenticated principal (when
+     * `serve({ authenticate })` is wired); `ctx.agent` carries the resolved
+     * `BuyerAgent` record (when an `agentRegistry` is configured). Adopters
+     * implementing principal-keyed gates (e.g., per-buyer-agent
+     * `BILLING_NOT_PERMITTED_FOR_AGENT` on the spec's billing surfaces) read
+     * the principal here — same threading as `accounts.resolve`.
+     *
+     * **Prefer `ctx.agent` over `ctx.authInfo.credential` for commercial-
+     * relationship decisions.** `ctx.agent` is the registry-resolved durable
+     * identity (status, billing capabilities, default account terms);
+     * `ctx.authInfo.credential` is the raw transport-level credential. For
+     * billing gates the registry-resolved identity is canonical. Use
+     * `credential` only for transport-level branching (e.g., reading the
+     * verified `agent_url` from `credential.kind === 'http_sig'` when
+     * `agentRegistry` is not configured).
+     */
+    upsert?(refs: AccountReference[], ctx?: ResolveContext): Promise<SyncAccountsResultRow[]>;
+    /**
+     * sync_governance API surface. Buyers register governance agent endpoints
+     * per-account; the seller persists the binding and consults the agents
+     * during media buy lifecycle events via `check_governance`.
+     *
+     * **Optional.** Adopters that don't model buyer-supplied governance agents
+     * (most direct sellers) leave this unimplemented and the framework returns
+     * `UNSUPPORTED_FEATURE`.
+     *
+     * `entries` is the wire request's `accounts[]` — each entry pairs an
+     * `AccountReference` with its `governance_agents[]`. The framework has
+     * already deduped on `idempotency_key` and stripped wire metadata
+     * (`adcp_major_version`, `context`, `ext`) before invoking this method.
+     *
+     * **Replace semantics, per spec.** Each call REPLACES the previously
+     * synced governance agents for the referenced account. An entry whose
+     * `governance_agents` is empty clears the binding for that account.
+     *
+     * **Write-only credentials.** Each `governance_agents[i].authentication.credentials`
+     * is the bearer the seller presents to that governance agent on outbound
+     * `check_governance` calls. Persist them — silently dropping ships
+     * unauthenticated requests once cross-agent calls are wired. The framework
+     * strips `authentication` from each `governance_agents[i]` of every row
+     * before serialization (`toWireSyncGovernanceRow`), so credentials never
+     * reach the response wire OR the idempotency replay cache, even if an
+     * adopter returns a loosely-typed row that spreads the input. Do not rely
+     * on TypeScript narrowing alone — the strip is enforced at the dispatcher.
+     *
+     * `ctx.authInfo` and `ctx.agent` carry the caller's principal — same
+     * threading as `upsert`. Adopters MUST gate per-entry persistence by the
+     * caller's tenant: each entry's `account.operator` (or `account_id`) must
+     * map to the same tenant the auth principal authorizes; otherwise return a
+     * `'failed'` row carrying `errors: [{code: 'PERMISSION_DENIED', ...}]` for
+     * that entry. (Operation-level rejection — `throw new AdcpError(...)` —
+     * fails the whole batch, which is the wrong shape when a single entry
+     * fails the gate.)
      */
-    upsert?(refs: AccountReference[]): Promise<SyncAccountsResultRow[]>;
+    syncGovernance?(entries: SyncGovernanceRequest['accounts'], ctx?: ResolveContext): Promise<SyncGovernanceSuccess['accounts']>;
     /**
      * list_accounts API surface. Framework wraps with cursor envelope.
      *
      * **Optional.** Same rationale as `upsert` — stateless platforms can omit.
+     *
+     * `ctx.authInfo` and `ctx.agent` carry the caller's principal — adopters
+     * scope the listing per-principal (e.g., return only accounts visible to
+     * the calling buyer agent) without re-deriving identity from the request.
      */
-    list?(filter: AccountFilter & CursorRequest): Promise<CursorPage<Account<TCtxMeta>>>;
+    list?(filter: AccountFilter & CursorRequest, ctx?: ResolveContext): Promise<CursorPage<Account<TCtxMeta>>>;
     /**
      * report_usage API surface. Operator-billed platforms accept usage rows
      * (often impressions / spend by media_buy + period) for billing
@@ -219,9 +469,12 @@ export interface AccountStore<TCtxMeta = Record<string, unknown>> {
      * platform must dedupe replays under the framework's idempotency key.
      *
      * `ctx.authInfo` carries the caller's OAuth principal (when
-     * `serve({ authenticate })` is wired). Platforms fronting an upstream
-     * billing API (Snap, Meta, retail-media) use it to authorize the usage
-     * post against the principal's tenant — same pattern as `accounts.resolve`.
+     * `serve({ authenticate })` is wired); `ctx.agent` carries the resolved
+     * `BuyerAgent` record (when an `agentRegistry` is configured). Platforms
+     * fronting an upstream billing API (Snap, Meta, retail-media) use them
+     * to authorize the usage post against the principal's tenant — same
+     * pattern as `accounts.resolve`. Prefer `ctx.agent` for principal-keyed
+     * commercial gates; see `upsert?` for the rationale.
      */
     reportUsage?(req: ReportUsageRequest, ctx?: ResolveContext): Promise<ReportUsageResponse>;
     /**
@@ -240,9 +493,11 @@ export interface AccountStore<TCtxMeta = Record<string, unknown>> {
      * `ctx.account.ctx_metadata` without re-resolving.
      *
      * `ctx.authInfo` carries the caller's OAuth principal (when
-     * `serve({ authenticate })` is wired). Platforms that guard financials
-     * per-principal use it to authorize the read — same pattern as
-     * `accounts.resolve`.
+     * `serve({ authenticate })` is wired); `ctx.agent` carries the resolved
+     * `BuyerAgent` record (when an `agentRegistry` is configured). Platforms
+     * that guard financials per-principal use them to authorize the read —
+     * same pattern as `accounts.resolve`. Prefer `ctx.agent` for principal-
+     * keyed commercial gates; see `upsert?` for the rationale.
      */
     getAccountFinancials?(req: GetAccountFinancialsRequest, ctx: AccountToolContext<TCtxMeta>): Promise<GetAccountFinancialsSuccess>;
     /**
@@ -330,25 +585,57 @@ export interface AccountFilter {
     /** Filter by status. */
     status?: AdcpAccountStatus[];
 }
+/**
+ * Per-account result row returned by an adopter's `accounts.upsert`
+ * implementation. Maps to one element of the wire `sync_accounts` response's
+ * `accounts[]` array.
+ *
+ * Carries the same optional commercial / lifecycle fields as the wire shape
+ * so adopters can echo `setup` (for `pending_approval` accounts), `billing`,
+ * `billing_entity`, `payment_terms`, etc. on creation. The framework
+ * projects these through `toWireSyncAccountRow` before emit, applying the
+ * same `billing_entity.bank` strip as `toWireAccount` (write-only contract).
+ *
+ * **MUST NOT carry `authInfo` or other auth-derived fields.** This shape is
+ * emitted on the `sync_accounts` response wire. The framework's projector
+ * does not read `authInfo`, but adopters MUST NOT add an `authInfo` key on
+ * returned rows — same MUST-NOT-LEAK rule the framework enforces on
+ * `Account.authInfo`.
+ */
 export interface SyncAccountsResultRow {
     account_id?: string;
     brand: BrandReference;
     operator: string;
+    /** Human-readable account name assigned by the seller. */
+    name?: string;
     action: 'created' | 'updated' | 'unchanged' | 'failed';
     status: AdcpAccountStatus;
+    /** Invoiced-to party. Echoes the request's `billing` after seller acceptance. */
+    billing?: BillingParty;
+    /** Business entity invoiced. `bank` is stripped on emit (write-only). */
+    billing_entity?: BusinessEntity;
+    account_scope?: AccountScope;
+    /** Setup payload for `pending_approval` accounts (URL/message/expiry). */
+    setup?: WireAccount['setup'];
+    rate_card?: string;
+    payment_terms?: PaymentTerms;
+    credit_limit?: WireAccount['credit_limit'];
     errors?: {
         code: string;
         message: string;
     }[];
+    warnings?: string[];
+    sandbox?: boolean;
 }
 export type AdcpAccountStatus = 'active' | 'pending_approval' | 'rejected' | 'payment_required' | 'suspended' | 'closed';
-import type { Account as WireAccount } from '../../types/tools.generated';
 /**
  * Project a framework `Account<TCtxMeta>` to the wire `Account` shape.
  *
- * Strips `metadata` and `authInfo` (framework-internal); renames `id` →
- * `account_id`; passes through `name`, `status`, `brand`, `operator`,
- * `advertiser`, and `billing.invoicedTo` mappings.
+ * Strips `ctx_metadata` and `authInfo` (framework-internal); renames `id` →
+ * `account_id`; passes through wire-shaped fields. Strips
+ * `billing_entity.bank` per the schema's write-only constraint — bank
+ * coordinates flow buyer→seller in `sync_accounts` requests but MUST NOT
+ * appear in any response payload.
  *
  * Used by the framework when emitting `list_accounts` and other wire
  * responses that include account data. Adopters never call this directly —
@@ -356,6 +643,40 @@ import type { Account as WireAccount } from '../../types/tools.generated';
  * and the framework projects.
  */
 export declare function toWireAccount<TCtxMeta>(account: Account<TCtxMeta>): WireAccount;
+type WireSyncAccountRow = SyncAccountsSuccess['accounts'][number];
+/**
+ * Project an adopter `SyncAccountsResultRow` to the wire shape returned by
+ * `sync_accounts`. Applies the same `billing_entity.bank` strip as
+ * `toWireAccount` — the wire schema marks bank coordinates write-only on
+ * EVERY response, not just `list_accounts`. Adopters returning a row that
+ * spreads a DB record carrying `bank` (e.g.,
+ * `{ ...db.findByBrand(r.brand), action: 'updated' }`) have it stripped
+ * before emit.
+ *
+ * Used by the framework when emitting `sync_accounts` responses. Adopters
+ * never call this directly — they return `SyncAccountsResultRow[]` from
+ * `accounts.upsert` and the framework projects.
+ */
+export declare function toWireSyncAccountRow(row: SyncAccountsResultRow): WireSyncAccountRow;
+type WireSyncGovernanceRow = SyncGovernanceSuccess['accounts'][number];
+/**
+ * Project a `sync_governance` response row to the wire shape, stripping
+ * any fields the buyer is NOT entitled to receive. Critically: each
+ * `governance_agents[i]` is reduced to `{url, categories?}` only — the
+ * spec marks `authentication.credentials` write-only (the buyer sends
+ * the bearer; the seller persists it for outbound `check_governance`
+ * calls but MUST NOT echo it back). The natural `{ ...entry.governance_agents[i] }`
+ * echo idiom would compile silently against the typed return shape and
+ * ship credentials over the wire AND into the idempotency replay cache,
+ * arming the buyer (and any subsequent caller hitting the same key) to
+ * impersonate the seller against the governance agent.
+ *
+ * Defense-in-depth: this dispatcher-level strip runs even if an adopter
+ * returns a loosely-typed row, and even if a future codegen change
+ * loosens the response Zod schema's `.passthrough()` for governance
+ * agents.
+ */
+export declare function toWireSyncGovernanceRow(row: WireSyncGovernanceRow): WireSyncGovernanceRow;
 /**
  * Extract `account_id` from an `AccountReference` discriminated union without
  * casting. Returns `undefined` when `ref` is absent or the union arm doesn't
@@ -367,11 +688,14 @@ export declare function toWireAccount<TCtxMeta>(account: Account<TCtxMeta>): Wir
  * resolve: async (ref, ctx) => {
  *   const id = refAccountId(ref);
  *   if (id) return this.db.findById(id);
- *   return this.db.findByOAuthClient(ctx?.authInfo?.clientId ?? '');
+ *   const cred = ctx?.authInfo?.credential;
+ *   const key = cred?.kind === 'oauth' ? cred.client_id : cred?.kind === 'api_key' ? cred.key_id : undefined;
+ *   return key ? this.db.findByClientKey(key) : null;
  * }
  * ```
  *
  * @public
  */
 export declare function refAccountId(ref?: AccountReference): string | undefined;
+export {};
 //# sourceMappingURL=account.d.ts.map

package/dist/lib/server/decisioning/account.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/account.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"account.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/account.ts"],"names":[],"mappings":"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"}