portage-ucp 0.5.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11276545531e50962e8e16e8d1c966853adfa8ddb8c1aa3851f7fa89a494b33e
-  data.tar.gz: 7421a957575b40d55200ce54e70335bec9a7c7a735cd0941eb2e1bdec0bdd535
+  metadata.gz: 826f590ea83ab80febf6e461f60d1eb580d7ebf460a419bafb81d0f713525e81
+  data.tar.gz: eb98a54978daf0904de0121101e98e597a67cd38dabd7440dd3813449b384635
 SHA512:
-  metadata.gz: 52d85b70ca4e16311c318331bb0ca161c82ff9f833e4d08b5c3e262550ecaeccf334aaf35cf5e39f5a351e3a5aa58ed0a508615003c1da6d54d728a9dc34eda9
-  data.tar.gz: 05e158b1864ae760e08ddb3ab76080a1effd59bfa475ebd64e23f0f2e30f6ff87b4afe44eef0112ca5dda0a6e579e64532df396743cab582373f90e44805b089
+  metadata.gz: fcb26f95ac6d46b622f3495b945f76549d4c7525c25fbe0552c3485659395e35e1e0330fe212052f253ba79680d498e9de0b179d91c9bee17a4f2796ec33c50c
+  data.tar.gz: 4726bf3de6e45993612ea7a2c4bfd57ef418ad1a7c1d1a17efdffa90d20991df0fe9f623548f81065383b31aa99fd7210c2512d7994f6521a4bb6cfcfc494c1c

data/CHANGELOG.md

@@ -4,7 +4,149 @@ All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project is
 pre-1.0, so APIs may still shift between minor versions.
 
-## [Unreleased]
+## [0.7.1] - 2026-09-16
+
+- No behavior change — 0.7.0 was built and pushed with `gem build` run from
+  the workspace root instead of this gem's own directory, so
+  `spec.files = Dir["lib/**/*.rb", ...]` resolved against the wrong working
+  directory and packaged an empty gem (no `lib/`). 0.7.0 has been yanked;
+  0.7.1 repackages the exact same 0.7.0 code correctly.
+
+## [0.7.0] - 2026-09-16
+
+- Added `Ap2::MandateSignature` — real ECDSA (P-256/P-384) verification of a
+  `PaymentMandate#signature` against a JWK trust-anchor set (an array of JWKs,
+  or a `#call(kid)` resolver), reusing the same wire conventions as the
+  existing RFC 9421 `Security::Signature`. `MandateGuard.validate!` gains a
+  `require_signature:` (default `false`) fail-closed option — with it set,
+  a mandate that no trust key can verify raises `InvalidMandateError` instead
+  of silently falling back to shape-only validation. `Configuration` gains
+  `mandate_trusted_keys`/`require_mandate_signature` accessors, and
+  `Dispatcher.new` gains matching `mandate_trust_keys:`/
+  `require_mandate_signature:` kwargs. 0.6.0 shipped AP2 mandates shape-only
+  ("no cryptographic verification" — see that entry below); this closes the
+  gap. Also hardens the shape-only path itself: rejects non-EC JWKs before
+  trusting `crv`/`x`/`y`, rescues `ArgumentError` in `decode_base64url` so a
+  malformed base64url value raises `InvalidMandateError` rather than
+  crashing, and stops leaking the raw curve/digest hash into the
+  wrong-length error message.
+- Closed a cross-process idempotency race: `FileStore` gains
+  `#fetch_or_store`, an atomic check-then-set under one `LOCK_EX` (the
+  previous fetch-then-store used two separate lock acquisitions, leaving a
+  window for a duplicate charge). `Idempotency#dedup` now goes through it.
+  `FileStore` persistence now writes to a temp file and `File.rename`s it
+  into place instead of truncating in place, and locks a sidecar `.lock`
+  file rather than the data file itself, so a lock held across a rename
+  can't go stale. A poisoned or truncated data file is now rescued and
+  treated as empty on read instead of permanently breaking every subsequent
+  `portage` invocation. `Configuration` gains `idempotency_provider` so a
+  caller can share one store process-wide instead of every
+  `Idempotency`-including instance getting its own fresh `MemoryStore`.
+  Per-key idempotency locks and `SessionLock`'s per-session locks are now
+  refcounted and reaped after use instead of growing unbounded for the life
+  of a long-running process.
+- Added `Rails::Railtie` and a `rails g portage:ucp:install` generator,
+  guarded so they only load when Rails is already present (the gemspec adds
+  no Rails dependency of its own) — writes a `config/initializers/
+  portage_ucp.rb` stub and mounts the manifest/webhook Rack endpoints with
+  TODO placeholders for a Rails host to fill in.
+- Added opt-in OpenTelemetry span emission: `Configuration#tracer` (`nil` by
+  default, no OTel dependency added). When set to something responding to
+  `#in_span(name, attributes:)`, `Observability.log` also emits a span
+  alongside its existing JSON logging; a no-op otherwise.
+- `Mcp::Server.build` now names `journal:` explicitly rather than leaving it
+  to fall through `**server_opts`, forwarding it straight to
+  `Dispatcher.new` — `Client.for_adapter`/`Loopback` already splatted
+  `server_opts` through, but nothing constructed a `Dispatcher` with a
+  journal regardless of what a caller passed. Closes design-log §37's named
+  gap; see `portage-cli`'s own changelog for the loopback buy path this now
+  lets `portage-cli` wire up.
+- Added `#each_record`/`#all` to `TransactionLog`/`OrderLedger` (and to both
+  classes' `Store` abstraction) — read-only enumeration over every stored
+  record, additive alongside the existing keyed `#find`/`#completed_since`.
+  §22 item 6's console is the second real consumer the `Store` docs said
+  would trigger this; `FileStore` implements it under the same shared-file
+  lock as every other read.
+
+## [0.6.0] - 2026-09-15
+
+- **Breaking:** `PaymentEnrollment` results are now validated by the new
+  `PaymentEnrollmentGuard` (design-log §33/Phase B) — every
+  `create_payment_enrollment`/`get_payment_enrollment` response an adapter
+  returns is checked via `Dispatcher#call`: `status` must be `"pending"` or
+  `"complete"`; `"pending"` must carry a `setup_url` and no `payment_token`;
+  `"complete"` must carry a `payment_token` and no `setup_url`. Raises the
+  new `Portage::Ucp::InvalidPaymentEnrollmentError` on a violation. A value
+  that constructed fine before (e.g. `status: "banana"`, or `"complete"`
+  with no token) now raises the first time it crosses `Dispatcher#call` —
+  consumers of `PaymentEnrollment` (`portage-cli`, `portage-ucp-client`)
+  are unaffected since they only branch on the CLI's own wire-level status
+  string, never construct the object themselves.
+- Added `Portage::Ucp::Ap2` — an AP2 mandate shape (design-log §33/Phase B,
+  citing the AP2/UCP payment-handler gap already confirmed at design-log
+  §29/§30). `Ap2::PaymentMandate` (amount, currency, merchant, expires_at,
+  signature) and `Ap2::MandateGuard.validate!` (required fields + expiry —
+  mandate-*shape* validation, not cryptographic AP2 verification; no key
+  infrastructure or trust anchor exists in this repo to verify a signature
+  against). `create_payment_enrollment`/`complete_checkout` take an
+  optional `mandate:` kwarg, shape-checked by `Dispatcher#call` before any
+  adapter sees it; `ReferenceAdapter` accepts one and echoes it back on the
+  enrollment it returns. `PaymentEnrollment` gains an optional `mandate:`
+  field for that echo (safe to add — it's a Portage extension, not a
+  UCP-schema-validated type).
+- Adapter conformance kit (`lib/portage/ucp/rspec.rb`) gains an
+  `app.portage-ucp.payment_enrollment` example proving an adapter's
+  enrollment responses satisfy `PaymentEnrollmentGuard` — previously the
+  kit had zero enrollment coverage; the only existing assertions lived in
+  this gem's own `reference_adapter_conformance_spec.rb`, which ships to
+  nobody.
+- `Support::TransactionLog` and `Support::OrderLedger` are now backed by a
+  pluggable `Store` (design-log §33) — new `Store`/`FileStore` pair on
+  each, mirroring `portage-ucp-journal`. `Dispatcher.new(transaction_log:,
+  order_ledger:)` / `TransactionLog.new(store:)` / `OrderLedger.new(store:)`
+  are the injection points; `path:`/`clock:` still work unchanged as a
+  shorthand for the file-backed default. Pure extract-interface refactor —
+  no behavior change, no new construction-site requirements.
+- Added `app.portage-ucp.payment_method`, `app.portage-ucp.saved_address`, and
+  `app.portage-ucp.shopper_data` — Portage-owned extensions (design-log §22
+  item 7) for saved payment references, saved addresses, and shopper data
+  erasure, shipped together per §16. `oauth_token:` is the authorization
+  boundary on every method, including the two `list_*` reads, since
+  `Mcp::Server` only authorizes/rate-limits calls carrying an
+  `idempotency_key`. `save_payment_method`'s `payment_token:` runs through
+  the existing `PaymentTokenGuard` via `Dispatcher#call`, same as
+  `complete_checkout`. `ReferenceAdapter` implements all three; `Adapter`'s
+  stubs raise `NotImplementedError` until overridden.
+- `Dispatcher.new` gains an optional `journal:` argument (`nil` by default,
+  never `require`d from this gem) — after a successful `complete_checkout`
+  with a settled order, `@journal.record_checkout(shop:, source:, checkout:,
+  idempotency_key:)` runs alongside the existing `order_ledger` write, same
+  after-settle/outside-the-rescue posture. `source` is `"native_ucp"` or
+  `"adapter:<platform>"`, read off the adapter's class. Pairs with the new
+  `portage-ucp-journal` gem's `PurchaseJournal` (design-log §22,
+  docs/plans/storage-abstraction-journal.md) — core takes on no new runtime
+  dependency; a consumer wires the journal in from their own app.
+- Added `Portage::Ucp::Security::Signature` and
+  `Portage::Ucp::Rack::SignatureVerification` — verifies RFC 9421 HTTP
+  Message Signatures on inbound requests per UCP's signature spec
+  (`ucp.dev/2026-04-08/specification/signatures/`), the cryptographic
+  proof-of-consent piece design-log §22 named as the one genuine security
+  hole remaining before 1.0. Verify-before-parse, same posture as
+  `Rack::WebhookEndpoint`; trusted keys reuse `Manifest#signing_keys`'
+  current+next JWK-array shape rather than a second key config.
+- Added `Confirmer::Webhook` (design-log §22 slice, Phase C) — out-of-band
+  approval for the confirmation gate, alongside `Terminal`/`AutoApprove`.
+  POSTs `{amount, currency, merchant, idempotency_key}` to a configured
+  URL, then polls a configured status endpoint (or calls a caller-supplied
+  `wait:` callback, for push-based transports) until approve/deny/timeout.
+  Fails closed on timeout, same as `Terminal`, but with its own longer
+  default timeout (900s vs. `Terminal`'s 120s) — a human already at a
+  terminal isn't the same wait as noticing and acting on a Slack message.
+  Built on `Support::HttpClient`, no new runtime dependency. Non-2xx
+  responses from the confirm/status calls themselves raise the new
+  `Confirmer::WebhookApiError`, distinct from `ConfirmationDeniedError`:
+  one means the out-of-band approver couldn't be reached, the other means
+  it was reached and said no (or never answered).
 
 ## [0.5.0] - 2026-09-14
 

data/README.md

@@ -23,17 +23,22 @@ in this gem.
 | `Portage::Ucp::Manifest` | Builds the signed `/.well-known/ucp` discovery document. |
 | `Portage::Ucp::Rack::ManifestEndpoint` | Serves that manifest over Rack. |
 | `Portage::Ucp::Rack::WebhookEndpoint` | HMAC-verified inbound order-lifecycle webhooks. |
+| `Portage::Ucp::Security::Signature` / `Portage::Ucp::Rack::SignatureVerification` | Verifies RFC 9421 HTTP Message Signatures on inbound requests per UCP's signature spec — cryptographic proof the call carries a signed AP2/UCP authorization, not just an authenticated caller. Wrap your mounted MCP/UCP endpoint with the Rack middleware; verification runs before the body is parsed. |
 | `Portage::Ucp::SchemaValidator` | Validates data against UCP's own vendored JSON Schemas/OpenRPC docs, offline. |
 | `Portage::Ucp::Resolver` / `exe/portage-ucp-check` | Probes any store's homepage/`.well-known/ucp` and recommends the matching adapter gem. |
 | `Portage::Ucp::Support::TransactionLog` | Durable pre/post-dispatch record of every `complete_checkout` call — reserved before dispatch, marked settled/failed after, so a crash mid-charge is diagnosable rather than silently lost. |
 | `Portage::Ucp::Support::OrderLedger` | Durable snapshot written after settlement, alongside (not instead of) the transaction record — a failed snapshot write surfaces without flipping an already-settled charge to failed. |
-| `Portage::Ucp::Confirmer` | Gate run just before `complete_checkout` dispatch, after `PolicyGuard`. `Confirmer::Terminal` blocks on stdin and fails closed on anything but an explicit `"y"`; `Confirmer::AutoApprove` is for specs/conformance kits that need a real `confirm!` without blocking. |
+| `Portage::Ucp::Confirmer` | Gate run just before `complete_checkout` dispatch, after `PolicyGuard`. `Confirmer::Terminal` blocks on stdin and fails closed on anything but an explicit `"y"`; `Confirmer::AutoApprove` is for specs/conformance kits that need a real `confirm!` without blocking; `Confirmer::Webhook` is an out-of-band transport (POST + poll a status URL, or a caller-supplied `wait:` callback) for a Slack/WhatsApp/etc. approval flow — same fail-closed-on-timeout contract, its own longer default timeout. |
 | `Portage::Ucp::PolicyGuard` / `Portage::Ucp::Policy` | Per-transaction/rolling/velocity caps and a merchant allowlist, checked before `complete_checkout` dispatch; configured via `portage-cli`'s `portage policy show/set`. |
+| `Portage::Ucp::PaymentEnrollmentGuard` | Validates every `create_payment_enrollment`/`get_payment_enrollment` result an `Adapter` returns — `status` must be `"pending"` (with a `setup_url`, no `payment_token`) or `"complete"` (with a `payment_token`, no `setup_url`). Runs automatically in `Dispatcher#call`. |
+| `Portage::Ucp::Ap2::PaymentMandate` / `Portage::Ucp::Ap2::MandateGuard` | A typed shape for an AP2 payment mandate, and shape-only validation (required fields + expiry — not cryptographic verification) run automatically on any `mandate:` argument passed through `Dispatcher#call`. |
 
 Security defaults are all locked down, not permissive-by-omission —
 `UnconfiguredAuthenticator` rejects every mutating call until you configure a real
 one, `PaymentTokenGuard` rejects raw card numbers before they reach your `Adapter`,
-and manifest signing is opt-in. Full detail in the root README's
+`PaymentEnrollmentGuard`/`Ap2::MandateGuard` reject malformed enrollments/mandates
+before they cross the same boundary, and manifest signing is opt-in. Full detail in
+the root README's
 [Security hooks](https://github.com/tomtom87/Portage#security-hooks--nothing-is-permissive-by-default)
 section.
 
@@ -75,6 +80,18 @@ and the [detailed walkthrough](https://github.com/tomtom87/Portage/blob/main/doc
 for the full agent-side conversation, manifest/webhook Rack mounting, and a real
 adapter to model your own against.
 
+## Swapping the store
+
+`Support::TransactionLog` and `Support::OrderLedger` each accept a `store:`
+(`Dispatcher.new(transaction_log:, order_ledger:)` is the injection point).
+`FileStore` — whole-file `flock` + JSON, `chmod 0600` — is the shipped
+default for both; nothing else ships today. Write your own subclass of
+`Support::TransactionLog::Store` / `Support::OrderLedger::Store` for a real
+database, Redis, or an in-memory double for tests — same posture as
+`portage-ucp-journal`'s `Store`/`FileStore` seam, no bundled second backend
+(see that gem's README). `path:`/`clock:` still work as a shorthand that
+builds a `FileStore` under the hood, so existing callers are unaffected.
+
 ## Checking any store
 
 ```bash

data/lib/generators/portage/ucp/install/install_generator.rb

@@ -0,0 +1,28 @@
+require "rails/generators"
+
+module Portage
+  module Ucp
+    module Generators
+      # rails g portage:ucp:install — writes the initializer stub and mounts
+      # the discovery/webhook Rack endpoints. Leaves authenticator, rate
+      # limiter and business identity as TODOs: none of those have a safe
+      # default a generator could pick for the host app (see
+      # UnconfiguredAuthenticator/NullRateLimiter in configuration.rb).
+      class InstallGenerator < ::Rails::Generators::Base
+        source_root File.expand_path("templates", __dir__)
+
+        def copy_initializer
+          template "portage_ucp.rb", "config/initializers/portage_ucp.rb"
+        end
+
+        def add_routes
+          route <<~RUBY.strip
+            # TODO: replace YOUR_ADAPTER with your Portage::Ucp::Adapter instance.
+            mount Portage::Ucp::Rack::ManifestEndpoint.new(manifest: Portage::Ucp::Manifest.new(adapter: YOUR_ADAPTER)) => "/.well-known/ucp"
+            mount Portage::Ucp::Rack::WebhookEndpoint.new(secret: Rails.application.credentials.dig(:portage_ucp, :webhook_secret), on_order_event: ->(order) { }) => "/webhooks/portage_ucp"
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/generators/portage/ucp/install/templates/portage_ucp.rb

@@ -0,0 +1,21 @@
+Portage::Ucp.configure do |config|
+  # TODO: authenticator must return an auth context (any truthy value) or
+  # raise Portage::Ucp::AuthenticationError. Left unset, every mutating
+  # capability call is rejected (UnconfiguredAuthenticator).
+  # config.authenticator = ->(server_context) { ... }
+
+  # TODO: rate_limiter#check!(key, capability) raises
+  # Portage::Ucp::RateLimitExceededError to block a call. Left unset, no
+  # limiting is applied (NullRateLimiter).
+  # config.rate_limiter = MyRateLimiter.new
+
+  # TODO: business identity advertised in the /.well-known/ucp manifest.
+  # config.business = { name: "Your Business" }
+
+  # config.signer = MySigner.new
+  # config.signing_keys = []
+  # config.payment_handlers = []
+  # config.services = []
+  # config.mandate_trusted_keys = []
+  # config.require_mandate_signature = false
+end

data/lib/portage/ucp/adapter.rb

@@ -71,8 +71,16 @@ module Portage
       # than a generic/platform error, so callers can distinguish a stale-stock
       # failure from e.g. a declined payment.
       # @raise [Portage::Ucp::OutOfStockError] if a line item is no longer available
+      # @param mandate [Portage::Ucp::Ap2::PaymentMandate, nil] an AP2
+      #   mandate authorizing this charge, alongside or instead of relying
+      #   on `payment_token` alone (design-log §33/Phase B). Validated for
+      #   shape (not cryptographically) by Dispatcher#call via
+      #   Ap2::MandateGuard before an adapter ever sees it. Optional and
+      #   `nil` by default — no adapter in this repo has a real PSP to
+      #   verify a mandate's signature against, so this is a pass-through
+      #   slot, same posture as `payment_token` on this same method.
       # @return [Portage::Ucp::Checkout]
-      def complete_checkout(checkout_id:, payment_token:, idempotency_key:) = not_implemented
+      def complete_checkout(checkout_id:, payment_token:, idempotency_key:, mandate: nil) = not_implemented
       # @return [Portage::Ucp::Checkout]
       def cancel_checkout(checkout_id:, idempotency_key:) = not_implemented
 
@@ -135,11 +143,56 @@ module Portage
       # gateway-hosted page where the human enters their card, and the
       # caller polls #get_payment_enrollment until `status` leaves
       # "pending". See docs/plans/agentic-payments.md Phase 1.
+      # @param mandate [Portage::Ucp::Ap2::PaymentMandate, nil] an AP2
+      #   mandate presented at enrollment time (design-log §33/Phase B),
+      #   same optional/pass-through posture as `complete_checkout`'s
+      #   `mandate:` above — validated for shape by Dispatcher#call, never
+      #   cryptographically, before an adapter ever sees it.
       # @return [Portage::Ucp::PaymentEnrollment]
-      def create_payment_enrollment(idempotency_key:) = not_implemented
+      def create_payment_enrollment(idempotency_key:, mandate: nil) = not_implemented
       # @return [Portage::Ucp::PaymentEnrollment, nil] nil if the enrollment isn't found
       def get_payment_enrollment(enrollment_id:) = not_implemented
 
+      # --- Payment Method / Saved Address / Shopper Data (app.portage-ucp.*
+      # — Portage extensions, not part of the UCP spec) ---
+      # `oauth_token:` — not `subject:` — is the authorization boundary on
+      # every method below, including the two list_* reads. Mcp::Server
+      # treats a call as mutating only when it takes an idempotency_key
+      # (mcp/server.rb:38), and both the authorize and rate_limit guards
+      # skip non-mutating calls entirely. A bare `subject:` string would let
+      # any caller who knows (or guesses) a subject enumerate another
+      # shopper's saved payment references and addresses — the exact risk
+      # §16 (design-log.md:816-819) calls out lookups against this data for.
+      # Carrying the credential on every call closes that: possession of a
+      # subject grants nothing without a valid oauth_token to derive it from.
+      # Do not "simplify" this back to `subject:`.
+      #
+      # @return [Portage::Ucp::PaymentMethodRef] stores an already-tokenized
+      #   payment_token; PaymentTokenGuard runs on it via Dispatcher#call
+      #   before this method is ever reached (dispatcher.rb:75), so a raw PAN
+      #   never arrives here.
+      def save_payment_method(oauth_token:, payment_token:, idempotency_key:) = not_implemented
+      # @return [Array<Portage::Ucp::PaymentMethodRef>]
+      def list_payment_methods(oauth_token:) = not_implemented
+      # @return [Boolean]
+      def delete_payment_method(oauth_token:, payment_method_id:, idempotency_key:) = not_implemented
+
+      # @return [Portage::Ucp::SavedAddress]
+      def save_address(oauth_token:, address:, idempotency_key:) = not_implemented
+      # @return [Array<Portage::Ucp::SavedAddress>]
+      def list_addresses(oauth_token:) = not_implemented
+      # @return [Boolean]
+      def delete_address(oauth_token:, address_id:, idempotency_key:) = not_implemented
+
+      # Erases every payment method, address, and linked identity Portage
+      # holds for this shopper. Idempotent and safe to repeat: a second call
+      # on an already-erased subject returns zero counts, never raises. A
+      # real adapter must forward the deletion to the PSP/platform's own
+      # API — Portage core never holds the credential behind psp_reference,
+      # only the opaque reference itself.
+      # @return [Portage::Ucp::ShopperDataErasure]
+      def delete_shopper_data(oauth_token:, idempotency_key:) = not_implemented
+
       private
 
       def not_implemented

data/lib/portage/ucp/ap2/mandate.rb

@@ -0,0 +1,48 @@
+require "json"
+
+module Portage
+  module Ucp
+    module Ap2
+      # A typed shape for an AP2 payment mandate (design-log §33/Phase B,
+      # citing design-log.md:1984-2117's already-confirmed AP2 gap) — the
+      # cart/intent authorization a shopper's agent presents alongside (or
+      # instead of) a bare `payment_token`. `amount`/`currency` mirror the
+      # minor-unit-integer convention `Total#amount` already uses elsewhere
+      # in this gem (see value_objects.rb).
+      #
+      # `kid` identifies which of the issuing agent's keys `signature` was
+      # made with — optional (defaults nil) so existing callers that only
+      # ever exercised shape validation keep constructing a PaymentMandate
+      # without it; it's required the moment a caller actually wants
+      # Ap2::MandateSignature/MandateGuard's `trusted_keys:` to verify the
+      # signature cryptographically. `signature` itself is still carried
+      # opaquely here — this Data class doesn't verify anything, it's just
+      # the shape; see MandateGuard and Ap2::MandateSignature for the two
+      # tiers of validation (shape-only vs shape+crypto).
+      PaymentMandate = Data.define(:amount, :currency, :merchant, :expires_at, :signature, :kid) do
+        def initialize(kid: nil, **rest)
+          super
+        end
+
+        def to_wire_h
+          { "amount" => amount, "currency" => currency, "merchant" => merchant,
+            "expires_at" => expires_at, "signature" => signature, "kid" => kid }
+        end
+
+        # The exact bytes Ap2::MandateSignature verifies `signature`
+        # against — every field but `signature` itself, canonicalized the
+        # same way Manifest#sign canonicalizes its own payload (JSON.generate
+        # over a fixed-order hash, no key sorting beyond that fixed order,
+        # since both sides of a mandate are expected to agree on the field
+        # order out of band rather than this gem inventing a JCS-style
+        # canonicalization scheme it doesn't need elsewhere).
+        def signing_payload
+          JSON.generate(
+            { "amount" => amount, "currency" => currency, "merchant" => merchant,
+              "expires_at" => expires_at, "kid" => kid }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/ap2/mandate_guard.rb

@@ -0,0 +1,48 @@
+require "time"
+
+module Portage
+  module Ucp
+    module Ap2
+      # Mandate validation (design-log §33/Phase B): required fields present,
+      # not expired, and — when the caller supplies a trust anchor —
+      # cryptographic proof via Ap2::MandateSignature. `trusted_keys` has no
+      # default because this gem has no key infrastructure of its own to
+      # default it to (§9's convention: keys are always consumer-provided,
+      # never generated or assumed here); a caller that omits it gets
+      # shape-only validation, same posture this guard always had, not a
+      # silent downgrade. A real PSP adapter is expected to pass the issuing
+      # agent's trust anchor (its own store, or a resolver against the
+      # agent's own manifest) once it has one. A caller that wants that
+      # omission to be an error instead — fail closed rather than silently
+      # downgrade to shape-only — sets `require_signature: true`.
+      module MandateGuard
+        REQUIRED_FIELDS = %i[amount currency merchant expires_at signature].freeze
+
+        # @param trusted_keys [Array<Hash>, #call, nil] forwarded to
+        #   Ap2::MandateSignature.verify! when present — see module doc.
+        # @param require_signature [Boolean] when true, `trusted_keys`
+        #   resolving to nil raises InvalidMandateError instead of falling
+        #   back to shape-only validation.
+        def self.validate!(mandate, trusted_keys: nil, require_signature: false)
+          missing = REQUIRED_FIELDS.reject { |field| mandate.public_send(field) }
+          unless missing.empty?
+            raise Portage::Ucp::InvalidMandateError,
+                  "payment mandate is missing required field(s): #{missing.join(', ')}"
+          end
+
+          if Time.now >= Time.parse(mandate.expires_at)
+            raise Portage::Ucp::InvalidMandateError,
+                  "payment mandate expired at #{mandate.expires_at}"
+          end
+
+          if trusted_keys
+            Ap2::MandateSignature.verify!(mandate, trusted_keys: trusted_keys)
+          elsif require_signature
+            raise Portage::Ucp::InvalidMandateError,
+                  "payment mandate signature verification is required but no trusted_keys are configured"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/ap2/mandate_signature.rb

@@ -0,0 +1,148 @@
+require "openssl"
+require "base64"
+
+module Portage
+  module Ucp
+    module Ap2
+      # Cryptographic verification of a PaymentMandate's `signature` — the
+      # piece MandateGuard's own comment (and PaymentMandate's, before this
+      # file existed) flagged as deliberately missing: "no key infrastructure
+      # or trust anchor exists in this repo to verify a signature against."
+      # A caller that now has a trust anchor (a real PSP adapter, or a
+      # platform-provided key resolver) passes it as `trusted_keys:` to get
+      # actual proof instead of shape-only validation.
+      #
+      # Same ECDSA/JWK wire conventions as Security::Signature (P-256
+      # mandatory/P-384 optional, raw r||s signature bytes, JWK x/y
+      # coordinates) since that curve support is already proven against this
+      # gem's RFC 9421 verifier — but deliberately a separate class, not a
+      # shared one: a mandate isn't an HTTP request (no method/path/headers
+      # to canonicalize, just PaymentMandate#signing_payload), and
+      # Security::Signature's own class doc already frames every signing
+      # story in this gem as deliberately distinct rather than unified under
+      # one abstraction.
+      #
+      # Trust anchor: `trusted_keys` here is the mandate *issuer's* key set
+      # (the shopper's agent, or the agent platform vouching for it) — a
+      # different trust root than Security::Signature's `trusted_keys` (the
+      # calling platform's own request-signing key), even though both reuse
+      # the same flat-JWK-array-or-#call(kid)-resolver shape (§9's
+      # convention, reused again here rather than inventing a second
+      # differently-shaped key config for the same job).
+      module MandateSignature
+        CURVES = {
+          "P-256" => { oid: "1.2.840.10045.3.1.7", coord: 32, digest: "SHA256" },
+          "P-384" => { oid: "1.3.132.0.34", coord: 48, digest: "SHA384" }
+        }.freeze
+        EC_PUBLIC_KEY_OID = "1.2.840.10045.2.1".freeze
+
+        # @param mandate [PaymentMandate]
+        # @param trusted_keys [Array<Hash>, #call] JWK hash set (or
+        #   resolver #call(kid) => JWK hash or nil), keyed by `kid` — see
+        #   module doc.
+        # @return [true] never a falsy result; raises
+        #   Portage::Ucp::InvalidMandateError on any failure so a caller
+        #   can't accidentally treat "didn't check" as "checked and passed"
+        #   (same convention as Security::Signature.verify!).
+        def self.verify!(mandate, trusted_keys:)
+          jwk = trust_key!(mandate, trusted_keys)
+          curve = curve_for!(jwk)
+          raw_signature = sized_signature!(mandate, curve)
+
+          key = ec_public_key(jwk, curve)
+          der = raw_to_der(raw_signature, curve[:coord])
+          verified = key.verify(curve[:digest], der, mandate.signing_payload)
+          raise Portage::Ucp::InvalidMandateError, "mandate signature does not verify" unless verified
+
+          true
+        rescue OpenSSL::PKey::PKeyError, OpenSSL::PKey::EC::Point::Error, OpenSSL::ASN1::ASN1Error => e
+          raise Portage::Ucp::InvalidMandateError, "mandate signature verification failed: #{e.message}"
+        end
+
+        def self.trust_key!(mandate, trusted_keys)
+          kid = mandate.kid
+          raise Portage::Ucp::InvalidMandateError, "mandate has no kid to resolve a trust key by" unless kid
+
+          jwk = resolve_key(trusted_keys, kid)
+          raise Portage::Ucp::InvalidMandateError, "no trusted key for mandate kid #{kid.inspect}" unless jwk
+
+          jwk
+        end
+        private_class_method :trust_key!
+
+        def self.curve_for!(jwk)
+          kty = jwk["kty"] || jwk[:kty]
+          raise Portage::Ucp::InvalidMandateError, "unsupported key type #{kty.inspect}" unless kty == "EC"
+
+          crv = jwk["crv"] || jwk[:crv]
+          CURVES.fetch(crv) { raise Portage::Ucp::InvalidMandateError, "unsupported curve #{crv.inspect}" }
+        end
+        private_class_method :curve_for!
+
+        def self.sized_signature!(mandate, curve)
+          raw_signature = decode_signature(mandate.signature)
+          unless raw_signature.bytesize == curve[:coord] * 2
+            raise Portage::Ucp::InvalidMandateError, "mandate signature is the wrong length for #{curve[:digest]}"
+          end
+
+          raw_signature
+        end
+        private_class_method :sized_signature!
+
+        def self.resolve_key(trusted_keys, kid)
+          if trusted_keys.respond_to?(:call)
+            trusted_keys.call(kid)
+          else
+            Array(trusted_keys).find { |k| (k["kid"] || k[:kid]) == kid }
+          end
+        end
+        private_class_method :resolve_key
+
+        def self.decode_signature(value)
+          Base64.strict_decode64(value.to_s)
+        rescue ArgumentError
+          raise Portage::Ucp::InvalidMandateError, "mandate signature isn't valid base64"
+        end
+        private_class_method :decode_signature
+
+        # Same DER-from-raw-JWK-coordinates construction as
+        # Security::Signature#ec_public_key, for the same reason: the
+        # OpenSSL::PKey::EC#public_key= setter no longer works since EC keys
+        # became immutable in the openssl gem's OpenSSL 3.0 support.
+        def self.ec_public_key(jwk, curve)
+          x = decode_base64url(jwk["x"] || jwk[:x])
+          y = decode_base64url(jwk["y"] || jwk[:y])
+          raise Portage::Ucp::InvalidMandateError, "JWK missing x/y" if x.nil? || y.nil?
+
+          octet_string = "\x04".b + x + y
+          der = OpenSSL::ASN1::Sequence.new([
+                                              OpenSSL::ASN1::Sequence.new([
+                                                                            OpenSSL::ASN1::ObjectId.new(EC_PUBLIC_KEY_OID),
+                                                                            OpenSSL::ASN1::ObjectId.new(curve[:oid])
+                                                                          ]),
+                                              OpenSSL::ASN1::BitString.new(octet_string)
+                                            ]).to_der
+          OpenSSL::PKey::EC.new(der)
+        end
+        private_class_method :ec_public_key
+
+        def self.raw_to_der(raw_signature, coord)
+          r = OpenSSL::BN.new(raw_signature.byteslice(0, coord), 2)
+          s = OpenSSL::BN.new(raw_signature.byteslice(coord, coord), 2)
+          OpenSSL::ASN1::Sequence.new([OpenSSL::ASN1::Integer.new(r), OpenSSL::ASN1::Integer.new(s)]).to_der
+        end
+        private_class_method :raw_to_der
+
+        def self.decode_base64url(value)
+          return nil unless value
+
+          padded = value + ("=" * ((4 - (value.length % 4)) % 4))
+          Base64.urlsafe_decode64(padded)
+        rescue ArgumentError
+          raise Portage::Ucp::InvalidMandateError, "JWK coordinate isn't valid base64url"
+        end
+        private_class_method :decode_base64url
+      end
+    end
+  end
+end

data/lib/portage/ucp/capabilities/identity_linking.rb

@@ -8,7 +8,7 @@ module Portage
       )
 
       ALL = [CATALOG, CART, CHECKOUT, ORDER, IDENTITY_LINKING, DISCOUNT, FULFILLMENT, REORDER,
-             PAYMENT_ENROLLMENT].freeze
+             PAYMENT_ENROLLMENT, PAYMENT_METHOD, SAVED_ADDRESS, SHOPPER_DATA].freeze
     end
   end
 end

data/lib/portage/ucp/capabilities/payment_enrollment.rb

@@ -10,7 +10,7 @@ module Portage
         name: "app.portage-ucp.payment_enrollment",
         version: "1",
         actions: { "create_payment_enrollment" => :create_payment_enrollment,
-                  "get_payment_enrollment" => :get_payment_enrollment }
+                   "get_payment_enrollment" => :get_payment_enrollment }
       )
     end
   end

data/lib/portage/ucp/capabilities/payment_method.rb

@@ -0,0 +1,28 @@
+module Portage
+  module Ucp
+    module Capabilities
+      # Portage-only extensions, not part of the UCP spec (no ucp.dev
+      # reverse-domain meaning to borrow), same posture as
+      # Capabilities::PAYMENT_ENROLLMENT/REORDER. Advertised only if the
+      # adapter overrides at least one of its own action methods. Kept as
+      # two capabilities (payment methods vs. addresses) rather than one,
+      # per design-log §16/§22 item 7's "ship together, but they're
+      # separate concerns" — a consumer can still gate them independently.
+      PAYMENT_METHOD = Portage::Ucp::Capability.new(
+        name: "app.portage-ucp.payment_method",
+        version: "1",
+        actions: { "save_payment_method" => :save_payment_method,
+                   "list_payment_methods" => :list_payment_methods,
+                   "delete_payment_method" => :delete_payment_method }
+      )
+
+      SAVED_ADDRESS = Portage::Ucp::Capability.new(
+        name: "app.portage-ucp.saved_address",
+        version: "1",
+        actions: { "save_address" => :save_address,
+                   "list_addresses" => :list_addresses,
+                   "delete_address" => :delete_address }
+      )
+    end
+  end
+end

data/lib/portage/ucp/capabilities/shopper_data.rb

@@ -0,0 +1,15 @@
+module Portage
+  module Ucp
+    module Capabilities
+      # Portage-only extension, not part of the UCP spec. Kept separate from
+      # PAYMENT_METHOD/SAVED_ADDRESS: this is the erasure duty over *both*
+      # of those plus the linked identity, not a peer capability alongside
+      # them (design-log §22 item 7).
+      SHOPPER_DATA = Portage::Ucp::Capability.new(
+        name: "app.portage-ucp.shopper_data",
+        version: "1",
+        actions: { "delete_shopper_data" => :delete_shopper_data }
+      )
+    end
+  end
+end