portage-ucp 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36c3a77e9f625761b827d1e925d54217b7bff302f4a7a60540d4a8c5d1794fb9
-  data.tar.gz: 05a86e2740a327c63bb0e06aa450e2aa5207aa60ce637575133483ed8df4698b
+  metadata.gz: f8228c4a5a32d4ed322103ebc5061bf3179700fae68cc414fd0e53a8cb7f900e
+  data.tar.gz: dfc1f273f7fc79a8af633d4341af409a1447550c56a2fb0e8c7d4301b85c65c4
 SHA512:
-  metadata.gz: d0d4746f829e60009463ee2748ba5c46ff6f3932b5a345f3f26d94e437a5132b39002945bf19abe1ee3d02c46e1760b52afa6910a15531df494c4e39dcca7787
-  data.tar.gz: 60898e67d72f545c24970415775506be4930336a4f325be61714cef0f810547f77b79951f7b48e3fb32b72cdd9adb9669b4f3af4f872be0a4bcb7ea60b325bf5
+  metadata.gz: 4b7bb63032f231ed97eee56d0ed1d5d85a0fed3fae9c5590a22b153285ce13cc9c362903971bbb9d0a1f9fd0ecb5372e6412f6c38c76ed4f1e17927491006803
+  data.tar.gz: 3046889323d2b87b8ec26523e93bd33ff4edad0345bb858e5f2a75f6c9e0d288e0918cb8b0ee0b3dee467fa47023d7469a254a3e0bfc0ada5aaa527907c1c6fc

data/CHANGELOG.md

@@ -6,6 +6,136 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+## [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
+
+- Added `Adapter#create_payment_enrollment(idempotency_key:)` /
+  `#get_payment_enrollment(enrollment_id:)`, advertised as a new
+  `app.portage-ucp.payment_enrollment` capability — a Portage extension, not
+  part of the UCP spec. Starts a card-on-file enrollment without the card
+  ever touching this process: `#create_payment_enrollment` returns a
+  gateway-hosted `setup_url`, and the caller polls `#get_payment_enrollment`
+  until `status` leaves `"pending"` and a `payment_token` appears.
+  Implemented in `ReferenceAdapter` as a worked example (docs/plans/agentic-payments.md
+  Phase 1).
+- Made the idempotency dedup store pluggable — `Support::Idempotency` now
+  takes a `store:` (defaulting to the existing in-memory behavior via the new
+  `MemoryStore`), with a `FileStore` alternative for dedup that survives a
+  process restart.
+- Added a durable `Support::TransactionLog`, wired into
+  `Dispatcher#complete_checkout` dispatch — a transaction is reserved before
+  dispatch and marked settled/failed after, so a crash mid-charge leaves a
+  diagnosable record instead of silence.
+- Extended `TransactionLog` to also record policy decisions and confirmation
+  outcomes on the same transaction record `PolicyGuard`/`Confirmer` gate.
+- Added `PolicyGuard`, wired into `Dispatcher` just before `complete_checkout`
+  dispatch — enforces `Policy`'s per-transaction/rolling caps, velocity, and
+  merchant allowlist (docs/plans/agentic-payments.md Phase 2). Configured via
+  `portage-cli`'s `portage policy show/set`.
+- Added per-token enrollment scopes to `Policy` — a merchant/max-amount/
+  currency scope can be bound to a token at enrollment time and is checked by
+  `PolicyGuard` keyed by the same `token_ref` derived from the token at
+  charge time.
+- Added a `Confirmer` interface, wired into `Dispatcher` right after
+  `PolicyGuard.check!` passes and before `complete_checkout` dispatch.
+  `Confirmer::Terminal` blocks the process on stdin and fails closed on
+  anything but an explicit `"y"` (no answer, `"n"`, or EOF all deny);
+  `Confirmer::AutoApprove` is for specs/conformance kits (docs/plans/agentic-payments.md
+  Phase 3).
+- Added a durable `Support::OrderLedger`, wired into the `complete_checkout`
+  settle path — written after the transaction record is already complete, so
+  a failed snapshot write surfaces without flipping an already-settled charge
+  to failed.
+- `Mcp::Server.call_tool` now extracts `ucp-agent.profile` from `_meta` the
+  same way it already does `correlation_id` from `traceparent`, logging/
+  forwarding it as `agent_profile` through every transport (http, stdio,
+  loopback) and `Client::Session`. Additive only — `Dispatcher` accepts and
+  threads it without yet acting on it.
+- Added `Adapter#lookup_catalog(ids:)`, advertised alongside `search_catalog`
+  — fetches several known product ids in one round trip instead of one
+  `get_product` call per id. Implemented in `Shopify::Adapter` via the Admin
+  API's `nodes(ids:)` field, reusing the same `Mapper.product` shape
+  `get_product`/`search_catalog` already use.
+
 ## [0.4.0] - 2026-08-28
 
 - Added `Adapter#reorder(order_id:, idempotency_key:)`, advertised as a new

data/README.md

@@ -23,13 +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; `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.
 
@@ -71,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/portage/ucp/adapter.rb

@@ -10,6 +10,11 @@ module Portage
       # get_cart/get_checkout/get_order.
       # @return [Portage::Ucp::ProductDetail, nil]
       def get_product(product_id:) = not_implemented
+      # Batch fetch — same result shape as search_catalog, for a caller that
+      # already has a set of product ids (e.g. hydrating a cart/order) and
+      # wants one round trip instead of N #get_product calls.
+      # @return [Portage::Ucp::CatalogSearchResult]
+      def lookup_catalog(product_ids:) = not_implemented
 
       # --- Cart (dev.ucp.shopping.cart) ---
       # Full-replacement semantics, matching UCP's real cart methods: create/
@@ -66,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
 
@@ -123,6 +136,63 @@ module Portage
       # @return [Portage::Ucp::Identity] linked profile for an exchanged OAuth token
       def link_identity(oauth_token:) = not_implemented
 
+      # --- Payment Enrollment (app.portage-ucp.payment_enrollment — Portage
+      # extension, not part of the UCP spec) ---
+      # Starts a card-on-file enrollment. Card data never touches this
+      # process: #create_payment_enrollment returns a `setup_url` for a
+      # 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:, 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,21 @@
+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); `signature` is carried opaquely
+      # — MandateGuard checks the mandate's *shape*, never the signature
+      # itself, since verifying it needs a trust anchor this gem doesn't
+      # have (see MandateGuard's own comment).
+      PaymentMandate = Data.define(:amount, :currency, :merchant, :expires_at, :signature) do
+        def to_wire_h
+          { "amount" => amount, "currency" => currency, "merchant" => merchant,
+            "expires_at" => expires_at, "signature" => signature }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+require "time"
+
+module Portage
+  module Ucp
+    module Ap2
+      # Mandate-*shape* validation (design-log §33/Phase B) — required
+      # fields present and not expired. This is deliberately NOT
+      # cryptographic AP2 verification: `signature` is carried opaquely
+      # (see PaymentMandate) and this guard never inspects it. No key
+      # infrastructure or trust anchor exists in this repo to verify a
+      # signature against — that's a real external dependency and an
+      # explicit non-goal here, the same carve-out the existing plan draws
+      # around crypto-signing the confirmation payload. A real PSP adapter
+      # is expected to verify a mandate's signature against the issuing
+      # agent's trust anchor before ever handing it to this gem.
+      module MandateGuard
+        REQUIRED_FIELDS = %i[amount currency merchant expires_at signature].freeze
+
+        def self.validate!(mandate)
+          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
+
+          return unless Time.now >= Time.parse(mandate.expires_at)
+
+          raise Portage::Ucp::InvalidMandateError,
+                "payment mandate expired at #{mandate.expires_at}"
+        end
+      end
+    end
+  end
+end

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

@@ -4,7 +4,8 @@ module Portage
       CATALOG = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.catalog",
         version: "1",
-        actions: { "search_catalog" => :search_catalog, "get_product" => :get_product }
+        actions: { "search_catalog" => :search_catalog, "get_product" => :get_product,
+                   "lookup_catalog" => :lookup_catalog }
       )
     end
   end

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

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

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

@@ -0,0 +1,17 @@
+module Portage
+  module Ucp
+    module Capabilities
+      # Portage-only extension, not part of the UCP spec (no ucp.dev
+      # reverse-domain meaning to borrow), same posture as Capabilities::REORDER.
+      # Advertised only if the adapter overrides Adapter#create_payment_enrollment
+      # — an adapter with no real gateway support for it simply never shows it
+      # in the manifest (see docs/plans/agentic-payments.md Phase 1).
+      PAYMENT_ENROLLMENT = Portage::Ucp::Capability.new(
+        name: "app.portage-ucp.payment_enrollment",
+        version: "1",
+        actions: { "create_payment_enrollment" => :create_payment_enrollment,
+                   "get_payment_enrollment" => :get_payment_enrollment }
+      )
+    end
+  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

data/lib/portage/ucp/confirmer.rb

@@ -0,0 +1,176 @@
+require "timeout"
+require "net/http"
+
+module Portage
+  module Ucp
+    # Phase 3 (docs/plans/agentic-payments.md) — the last gate before a
+    # payment-completing dispatch, run by Dispatcher right after PolicyGuard
+    # passes. Transport-agnostic by design: Dispatcher only ever calls
+    # `#confirm!(amount:, currency:, merchant:, idempotency_key:)` on
+    # whatever object it's given, so a future WhatsApp/Slack confirmer is a
+    # separate gem implementing the same method, no core change required.
+    # `idempotency_key` rides along even though this phase's Terminal
+    # implementation ignores it — an async transport needs it to bind a
+    # reply back to the request that asked.
+    module Confirmer
+      # Blocks the CLI process on stdin: "Approve? [y/N]". Fail-closed — no
+      # answer within `timeout_seconds` denies, same as an explicit "n",
+      # never leaves a payment pending on an agent that's still waiting.
+      # Checkout staleness while the operator was thinking isn't handled
+      # here: the confirmed amount is re-validated by nothing in this class,
+      # but the adapter call `call_adapter` makes right after this passes
+      # hits the real backend, which is the thing that'd reject a checkout
+      # that expired mid-wait — no separate re-check needed.
+      class Terminal
+        DEFAULT_TIMEOUT_SECONDS = 120
+
+        def initialize(timeout_seconds: DEFAULT_TIMEOUT_SECONDS, input: $stdin, output: $stdout)
+          @timeout_seconds = timeout_seconds
+          @input = input
+          @output = output
+        end
+
+        # @raise [Portage::Ucp::ConfirmationDeniedError] on "n", timeout, or
+        #   EOF (stdin closed out from under a headless run) — anything that
+        #   isn't an explicit "y" denies.
+        # @return [Hash] `{approved: true}` on "y".
+        def confirm!(amount:, currency:, merchant:, idempotency_key:)
+          @output.print("Approve payment of #{amount} #{currency} to #{merchant.inspect}? [y/N] ")
+          @output.flush
+
+          answer = read_with_timeout
+          return { approved: true } if answer&.strip&.downcase == "y"
+
+          deny!(answer.nil? ? :timeout : :denied, idempotency_key)
+        end
+
+        private
+
+        def read_with_timeout
+          Timeout.timeout(@timeout_seconds) { @input.gets }
+        rescue Timeout::Error
+          nil
+        end
+
+        def deny!(reason, idempotency_key)
+          message = reason == :timeout ? "confirmation timed out after #{@timeout_seconds}s" : "confirmation denied"
+          raise Portage::Ucp::ConfirmationDeniedError.new(
+            message, reason: reason, decision: { approved: false, reason: reason, idempotency_key: idempotency_key }
+          )
+        end
+      end
+
+      # Always approves. For adapter conformance suites and Dispatcher specs
+      # that need a real `confirm!` call to return without blocking on
+      # stdin — never wire this into a real Dispatcher: confirmation
+      # defaulting to *on* is the thing that makes Phase 1's permanently-
+      # spendable stored token safe (see plan, "No arm step").
+      class AutoApprove
+        def confirm!(**)
+          { approved: true }
+        end
+      end
+
+      # Raised when the confirm or status HTTP call itself fails (non-2xx,
+      # not the 409 Support::HttpClient already normalizes to ConflictError)
+      # — a transport failure talking to the out-of-band approver, not a
+      # denial by it. Kept distinct from ConfirmationDeniedError: that one
+      # means "someone said no" or "no one answered in time," this one means
+      # "couldn't even ask."
+      class WebhookApiError < Portage::Ucp::Error
+        include Support::ApiError
+
+        private
+
+        def api_label
+          "Confirmer::Webhook"
+        end
+      end
+
+      # Out-of-band approval over plain HTTP: POST the request, then poll a
+      # status endpoint until the out-of-band channel (Slack, WhatsApp,
+      # whatever a caller wires up) records an answer. Core only ever speaks
+      # HTTP here — the actual notification transport is the caller's job,
+      # same "transport-agnostic by design" posture as this module's
+      # top-of-file comment.
+      #
+      # Deliberately its own timeout default, not Terminal::
+      # DEFAULT_TIMEOUT_SECONDS: 120s fits a human already at a keyboard, not
+      # someone who has to notice a Slack message and tap approve.
+      class Webhook
+        include Support::HttpClient
+
+        DEFAULT_TIMEOUT_SECONDS = 900
+        DEFAULT_POLL_INTERVAL_SECONDS = 5
+
+        # @param confirm_url [String] posted `{amount, currency, merchant,
+        #   idempotency_key}` once, to kick off the out-of-band approval.
+        # @param status_url [String] polled (GET, `?idempotency_key=...`)
+        #   for `{"status" => "approved" | "denied" | "pending"}` until it
+        #   stops answering "pending" or `timeout_seconds` elapses.
+        # @param wait [#call, nil] escape hatch for push-based transports —
+        #   when given, called with `idempotency_key` instead of polling,
+        #   and must itself return `"approved"` or `"denied"` (blocking as
+        #   long as it needs to; `timeout_seconds` isn't enforced around it,
+        #   since a push transport is expected to enforce its own).
+        def initialize(confirm_url:, status_url:, timeout_seconds: DEFAULT_TIMEOUT_SECONDS,
+                       poll_interval_seconds: DEFAULT_POLL_INTERVAL_SECONDS, headers: {}, wait: nil)
+          @confirm_url = confirm_url
+          @status_url = status_url
+          @timeout_seconds = timeout_seconds
+          @poll_interval_seconds = poll_interval_seconds
+          @headers = headers
+          @wait = wait
+        end
+
+        # @raise [Portage::Ucp::ConfirmationDeniedError] on an explicit
+        #   deny, or on timeout (fail-closed, same as Terminal).
+        # @raise [Portage::Ucp::Confirmer::WebhookApiError] if the confirm
+        #   or status HTTP call itself fails.
+        # @return [Hash] `{approved: true}` on approval.
+        def confirm!(amount:, currency:, merchant:, idempotency_key:)
+          json_request(Net::HTTP::Post, @confirm_url,
+                       body: { amount: amount, currency: currency, merchant: merchant,
+                               idempotency_key: idempotency_key },
+                       headers: @headers)
+
+          status = @wait ? @wait.call(idempotency_key) : poll(idempotency_key)
+          return { approved: true } if status == "approved"
+
+          deny!(status == "denied" ? :denied : :timeout, idempotency_key)
+        end
+
+        private
+
+        def poll(idempotency_key)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout_seconds
+
+          loop do
+            response = json_request(Net::HTTP::Get, status_url_for(idempotency_key), headers: @headers)
+            return response["status"] if %w[approved denied].include?(response["status"])
+            return "timeout" if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+            sleep(@poll_interval_seconds)
+          end
+        end
+
+        def status_url_for(idempotency_key)
+          uri = URI(@status_url)
+          uri.query = "idempotency_key=#{URI.encode_www_form_component(idempotency_key)}"
+          uri
+        end
+
+        def deny!(reason, idempotency_key)
+          message = reason == :timeout ? "confirmation timed out after #{@timeout_seconds}s" : "confirmation denied"
+          raise Portage::Ucp::ConfirmationDeniedError.new(
+            message, reason: reason, decision: { approved: false, reason: reason, idempotency_key: idempotency_key }
+          )
+        end
+
+        def api_error_class
+          WebhookApiError
+        end
+      end
+    end
+  end
+end