feat(server): composeMethod — typed before/after hooks with {shortCircuit: T} discriminated wrapper

[bokelley]

Parent: #452

JS source

.changeset/compose-method-helper.md (6.7).

Pattern

Wrap individual DecisioningPlatform methods with hooks:

• before(params) -> ShortCircuit | None. Return None to fall through to inner method, or {"short_circuit": value} to skip the inner method and use value as the result.
• after(result, params, ctx) -> result runs on the result whether it came from the inner method OR a before short-circuit.
• Critically: after runs BEFORE response-schema validation, so adopters can tweak shape before the framework validates.

Proposed API

from adcp.decisioning import compose_method, require_account_match, require_advertiser_match, require_org_scope

platform.create_media_buy = compose_method(
    inner=platform.create_media_buy,
    before=require_account_match,           # raises PERMISSION_DENIED if mismatch
    after=lambda result, params, ctx: ...,  # echo back custom fields
)

Security composers (each is a valid before hook):

• require_account_match — fails if params.account_id doesn't match resolved auth principal's account.
• require_advertiser_match — fails if params.advertiser_id not in resolved principal's advertisers.
• require_org_scope — fails if resolved principal isn't operator-scoped.

All raise typed PermissionDeniedError (#3).

Acceptance criteria

• compose_method helper exported from adcp.decisioning.
• 3 security composers exported.
• Tests cover: before-only, after-only, both, short-circuit path, exception in before propagates, after runs on short-circuited result.

[bokelley]

Triage

Classification: Feature request
Bucket(s): handlers, middleware (no matching labels exist in this repo — see run summary note)
Status: ready-for-human
Milestone: omitted (no version signal in issue text)

What the experts said:

• security-reviewer: 3 blockers — (1) no framework enforcement that short_circuit return can't itself bypass auth; (2) if PermissionDeniedError isn't a subclass of AdcpError, dispatch wraps it as INTERNAL_ERROR and the buyer can't distinguish permission denial from a server bug; (3) after running before schema validation creates a window where after output bypasses the last firewall on PII-adjacent response fields
• ad-tech-protocol-expert: 3 blockers — (1) the {"short_circuit": value} dict sentinel passes all isinstance checks silently and lands on the wire as-is if it's not a valid response shape; (2) require_advertiser_match has no actual wire field to check — advertiser_id doesn't exist on request models (the field is a nested AccountReference.brand); (3) require_org_scope maps to no first-class AdCP concept — AuthInfo.operator is documented as "most adopters leave this None" and BuyerAgent.billing_capabilities membership is a different concept
• code-reviewer: 3 blockers — (1) before(params) is missing ctx, making all three security composers non-functional as specced; (2) the wrapper is always-async, which bypasses the executor branch in _invoke_platform_method for sync platform methods; (3) PermissionDeniedError has no schema backing and issue chore(main): release 0.1.2 #3 (the cited source) is a closed release PR, not a type definition
• dx-expert: 2 blockers — (1) dict discriminator {"short_circuit": value} is inconsistent with SDK conventions (exception-based error paths, typed return models everywhere else) and invisible to type checkers; should be a typed ShortCircuit class; (2) error model: PermissionDeniedError as a standalone exception creates a second dispatch seam alongside AdcpError

My take: The pattern has solid value and the JS parity motivation is clear, but four independent reviewers converge on the same three blockers before any implementation: the before hook needs ctx, the short-circuit signal needs to be a typed class (not a sentinel dict), and the security composers must use AdcpError(code="PERMISSION_DENIED", ...) directly (or a subclass). Additionally, require_advertiser_match and require_org_scope need their wire-field mappings clarified before they can be specified — advertiser_id doesn't exist on request models and "operator-scoped" has no agreed field mapping in this SDK.

Questions for @bokelley before implementation:

1. Should before receive (params, ctx) rather than (params) only? The security composers require ctx to read the auth principal.
2. For require_advertiser_match: which field does this check — params.account (an AccountReference), a brand reference, or a per-specialism field?
3. For require_org_scope: which Python field maps to "operator-scoped" — AuthInfo.operator is not None, a BuyerAgent.billing_capabilities membership check, or something else?
4. Should PermissionDeniedError be a thin subclass of AdcpError (safe: dispatch catches it) or is AdcpError(code="PERMISSION_DENIED", ...) sufficient for this batch?

---

Triaged by Claude Code. Session: https://claude.ai/code/session_011gfA41uCMgnxsBDxa3KAhZ

---

Generated by Claude Code