Security hooks¶
Security hooks — nothing is permissive by default¶
Read this before wiring a server up to anything real — every default here is deliberately locked down, not permissive-by-omission:
- Authentication:
Portage::Ucp::UnconfiguredAuthenticator(the default) rejects every mutating call until you configure a real one. Implement#call(server_context)to return a truthy auth context, or raisePortage::Ucp::AuthenticationError. - What counts as mutating:
Mcp::Server.buildsends a call to the authenticator and the rate limiter only when its adapter method takesidempotency_key:. Every other tool skips both, and no option changes that. That includeslist_payment_methodsandlist_addresses, by design: they takeoauth_token:, not a baresubject:, so a caller learns nothing without the shopper's own token (docs/design-log.md§32). An adapter must derive the shopper from that token on every call. - Rate limiting:
Portage::Ucp::NullRateLimiter(the default) never limits. Implement#check!(key, capability)and raisePortage::Ucp::RateLimitExceededErrorto block a call. - PAN guard:
Portage::Ucp::PaymentTokenGuardrejects anypayment_tokenthat looks like a raw card number (digits-only, Luhn-valid, 12–19 chars) before it ever reaches yourAdapter—complete_checkoutmust receive a tokenized credential. - Idempotency: every mutating capability action takes an
idempotency_key:— yourAdapteris responsible for deduping retries (seeportage-ucp-shopify's in-process dedup table for one approach). - Observability:
Portage::Ucp::Observability.logemits structured JSON log events through a consumer-injected logger, redactingpayment_token/oauth_token/authorizationautomatically. - Manifest signing:
Portage::Ucp::Manifestnever generates or stores keys — pass asigner(anything responding to#kidand#sign(canonical_json)) to produce a signed manifest; omit it to serve unsigned. - Policy caps:
Portage::Ucp::PolicyGuard, wired intoDispatcherjust beforecomplete_checkoutdispatch, enforcesPortage::Ucp::Policy's per-transaction/rolling caps, velocity limits, and merchant allowlist — plus per-token enrollment scopes (merchant/max-amount/currency) bound at enrollment time and checked by the sametoken_refat charge time. Configured viaportage-cli'sportage policy show/setandportage payment enroll --scope-*. - Confirmation:
Portage::Ucp::Confirmer, run right afterPolicyGuard.check!passes and beforecomplete_checkoutdispatch.Confirmer::Terminalblocks on stdin and fails closed on anything but an explicit"y";Confirmer::AutoApproveis for specs/conformance kits that need a realconfirm!without blocking;Confirmer::Webhookis for out-of-band approval — POSTs to a configured URL and polls (or calls a caller-suppliedwait:callback) until approve/deny/timeout, failing closed on timeout likeTerminalbut with a longer default (900s vs. 120s).Mcp::Server.buildalways usesConfirmer::Terminaland can't be given another one. Over a stdio MCP transport that confirmer shares$stdinand$stdoutwith the transport, so everycomplete_checkoutcall is denied and its response frame is corrupted. See Dispatcher for the details. - Payment enrollment:
Portage::Ucp::PaymentEnrollmentGuard, run viaDispatcher#call, validates everycreate_payment_enrollment/get_payment_enrollmentresponse an adapter returns —"pending"must carry asetup_urland nopayment_token,"complete"the reverse — raisingInvalidPaymentEnrollmentErroron a violation. An optionalmandate:kwarg on the same two methods is checked byPortage::Ucp::Ap2::MandateGuard: AP2 mandate shape and expiry always, plus the signature viaAp2::MandateSignaturewhen trusted keys are configured (mandate_trusted_keys;require_mandate_signaturerejects unsigned mandates). - Inbound request signatures:
Portage::Ucp::Security::Signature/Rack::SignatureVerificationverify RFC 9421 HTTP Message Signatures on inbound requests per UCP's signature spec — the same verify-before-parse posture asRack::WebhookEndpoint, trustingManifest#signing_keys' current+next JWK array. - Durable records:
Portage::Ucp::Support::TransactionLogreserves a transaction beforecomplete_checkoutdispatch and marks it settled/failed after, recordingPolicyGuard/Confirmeroutcomes on the same record.Portage::Ucp::Support::OrderLedgerwrites a durable snapshot alongside it once settlement succeeds — a failed snapshot write surfaces without flipping an already-settled charge to failed.
WebMCP-specific hardening¶
portage-ucp-webmcp's CallEndpoint (the Rack endpoint a page's document.modelContext
tool calls land on) adds two more limits on top of the above: a max_body_bytes cap
(1 MiB default, rejected with 413) and a call_timeout (30s default) on the underlying
tool dispatch. Both are configurable per endpoint instance — see
the WebMCP adapter page for the full README, including its
CSP/CSRF guidance.
Shared HTTP client timeouts¶
Every bundled adapter's HTTP calls go through Portage::Ucp::Support::HttpClient, which
sets a default open timeout of 5s and read timeout of 30s, and retries a timeout (and
429/5xx responses) with exponential backoff, up to 4 attempts total, through
Portage::Ucp::Support::Retry rather than propagating it straight to the caller.