feat(webhooks): support tenant-scoped signing senders in PgTaskWebhookOutbox

[bokelley]

Summary

PgTaskWebhookOutbox in 8.0.0-beta.8 accepts one fixed WebhookSender for the process. That is not sufficient for a multi-tenant seller whose request-scoped capabilities advertise tenant-specific RFC 9421 signing credentials.

This blocks adopting the SDK-managed durable outbox without either signing some tenant webhooks with the wrong key or collapsing all tenants onto one global signing identity.

Concrete adopter shape

Embedded Sales Agent serves multiple seller tenants through one PlatformRouter and one task registry. DecisioningPlatform.get_adcp_capabilities_for_request() resolves webhook_signing per tenant from that tenant active TenantSigningCredential. The existing delivery path loads the same tenant credential when producing the RFC 9421 signature.

The beta.8 outbox instead stores a single sender:

PgTaskWebhookOutbox(
    pool=pool,
    sender=WebhookSender.from_jwk(one_private_jwk),
    ...,
)

At worker time there is no request context from which the adopter can select the tenant credential. account_id is the buyer account identity and is not generically the seller tenant or signing scope. Buyer-supplied request_context is also not a trusted place for signing identity.

Using a subclass is intentionally unavailable: beta.8 correctly requires the exact PgTaskRegistry and PgTaskWebhookOutbox types so an override cannot invalidate the audited durability contract. The external-owner path would require duplicating the new atomic outbox just to vary key selection.

Required behavior

Please add an SDK-owned tenant-aware sender resolution path while retaining the exact audited registry/outbox types. For example:

• capture a trusted, adopter-resolved signing scope when the task is issued;
• store that scope in the encrypted/authenticated registration or outbox envelope;
• resolve a WebhookSender from that scope for each delivery attempt;
• validate every resolved sender as RFC 9421-capable, SDK-owned IP-pinned transport with private destinations disabled;
• preserve byte-identical body/idempotency retries while allowing a fresh signature from the currently valid tenant key.

The signing scope must come from trusted server-side account/platform metadata, not push_notification_config, buyer context, or an unqualified buyer account ID.

A possible public shape is a concrete SDK resolver interface accepted by PgTaskWebhookOutbox, plus a handler hook that derives an opaque signing-scope ID from the resolved RequestContext. The fixed sender= path should remain the simple single-tenant default.

Acceptance criteria

1. Two tenants handled by one registry/outbox can deliver with different kid values matching their request-scoped advertised credentials.
2. The trusted signing scope survives task issuance, process restart, terminal enqueue, and worker delivery.
3. A buyer cannot select or alter the signing scope through request fields.
4. Exact body and idempotency-key replay guarantees remain unchanged.
5. Missing/invalid tenant sender resolution fails closed and leaves a recoverable/quarantined delivery record.
6. Key rotation can select the currently valid tenant sender without rewriting the immutable webhook body.

Related context: #875 established the need for tenant-specific externally managed webhook signing capabilities. Beta.8 now provides the durable publisher, but only for a single fixed signing identity.

[bokelley]

Triage

Classification: Feature request
Bucket(s): signing (no matching repo label — noted in run summary), middleware
Status: ready-for-human
Milestone: omit

What the experts said:

• ad-tech-protocol-expert: Request is protocol-conformant and the issue/delivery time split is the correct approach for key rotation; three gaps must be closed: signing_scope_id must be bound into _envelope_aad AAD (otherwise a DB-level column substitution can redirect signing without breaking decryption), _owns_client/_allow_private_destinations invariants must be enforced at delivery time on every resolved sender (not just at construction), and the acceptance criteria must distinguish transient scope-missing (rotation in flight → retry) from permanent scope-missing (decommissioned scope → quarantine).
• security-reviewer: Threat model is sound only if signing_scope_id is populated exclusively from the server's internal tenant registry and never from buyer-supplied fields (e.g. push_notification_config, request context); otherwise a buyer can force cross-tenant key misuse. Typed exceptions distinguishing ScopePermanentlyUnknown (quarantine) from ScopeTransientlyUnavailable (retry) are required or dead rows will accumulate through the full retry horizon.

My take: The design is sound and the acceptance criteria are well-specified; the two experts converge on the implementation approach. This is flagged for human review because it is security-sensitive (signing identity selection), requires a DB schema migration (new nullable signing_scope_id column), and introduces a new public protocol class (WebhookSenderResolver) to the audited outbox contract — all three of which warrant a human decision before implementation begins.

Implementation scope when authorized:

• Add sender_resolver: WebhookSenderResolver | None = None to PgTaskWebhookOutbox.__init__, mutually exclusive with the existing sender= (which becomes the single-tenant default). Accept either one; reject neither or both.
• Define WebhookSenderResolver as a concrete SDK-owned interface with a typed resolve(signing_scope_id: str) -> WebhookSender async method and two exception subclasses: ScopePermanentlyUnknown (triggers quarantine in _quarantine_permanent_delivery_error) and ScopeTransientlyUnavailable (triggers the retry/release path).
• Add a nullable signing_scope_id TEXT COLLATE "C" column to the outbox table DDL in create_schema; include it in _envelope_aad (append to the AAD list after idempotency_key) to bind it cryptographically to the stored envelope.
• Add a new handler hook (on PgTaskRegistry or a platform method) that derives an opaque signing_scope_id from the server-side RequestContext at task-issue time; the framework must explicitly document that this hook must not derive the scope from buyer-supplied fields (push_notification_config, request context, account_id).
• In process_one, call resolver.resolve(signing_scope_id) and enforce _owns_client/not _allow_private_destinations on the returned sender before calling send_prepared; use protect_registration/open_registration (lines 299–363) as prior-art for the authenticated storage pattern.
• Relevant files: src/adcp/decisioning/pg/task_webhook_outbox.py, src/adcp/decisioning/pg/task_registry.py, src/adcp/webhook_sender.py (for the resolver interface export), src/adcp/decisioning/__init__.py (re-export).
• Required checks: pytest on affected pg tests, mypy src/, ruff check ., and a migration-safe schema test confirming signing_scope_id IS NULL rows still process correctly (backward compat for existing rows).

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code