portage-ucp 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8228c4a5a32d4ed322103ebc5061bf3179700fae68cc414fd0e53a8cb7f900e
-  data.tar.gz: dfc1f273f7fc79a8af633d4341af409a1447550c56a2fb0e8c7d4301b85c65c4
+  metadata.gz: 826f590ea83ab80febf6e461f60d1eb580d7ebf460a419bafb81d0f713525e81
+  data.tar.gz: eb98a54978daf0904de0121101e98e597a67cd38dabd7440dd3813449b384635
 SHA512:
-  metadata.gz: 4b7bb63032f231ed97eee56d0ed1d5d85a0fed3fae9c5590a22b153285ce13cc9c362903971bbb9d0a1f9fd0ecb5372e6412f6c38c76ed4f1e17927491006803
-  data.tar.gz: 3046889323d2b87b8ec26523e93bd33ff4edad0345bb858e5f2a75f6c9e0d288e0918cb8b0ee0b3dee467fa47023d7469a254a3e0bfc0ada5aaa527907c1c6fc
+  metadata.gz: fcb26f95ac6d46b622f3495b945f76549d4c7525c25fbe0552c3485659395e35e1e0330fe212052f253ba79680d498e9de0b179d91c9bee17a4f2796ec33c50c
+  data.tar.gz: 4726bf3de6e45993612ea7a2c4bfd57ef418ad1a7c1d1a17efdffa90d20991df0fe9f623548f81065383b31aa99fd7210c2512d7994f6521a4bb6cfcfc494c1c

data/CHANGELOG.md

@@ -4,7 +4,69 @@ 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
 

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/ap2/mandate.rb

@@ -1,3 +1,5 @@
+require "json"
+
 module Portage
   module Ucp
     module Ap2
@@ -6,14 +8,39 @@ module Portage
       # 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
+      # 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 }
+            "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

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

@@ -3,30 +3,44 @@ 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.
+      # 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
 
-        def self.validate!(mandate)
+        # @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
 
-          return unless Time.now >= Time.parse(mandate.expires_at)
+          if Time.now >= Time.parse(mandate.expires_at)
+            raise Portage::Ucp::InvalidMandateError,
+                  "payment mandate expired at #{mandate.expires_at}"
+          end
 
-          raise Portage::Ucp::InvalidMandateError,
-                "payment mandate expired at #{mandate.expires_at}"
+          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

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/configuration.rb

@@ -9,7 +9,42 @@ module Portage
     # through every call site.
     class Configuration
       attr_accessor :registry, :authenticator, :rate_limiter, :logger,
-                    :business, :signer, :payment_handlers, :signing_keys, :services
+                    :business, :signer, :payment_handlers, :signing_keys, :services,
+                    :mandate_trusted_keys, :require_mandate_signature
+
+      # Unset by default — the gem has no OTel dependency of its own
+      # (Observability's JSON-to-Logger path needs nothing else). Set to
+      # anything responding to #in_span(name, attributes:) to also emit a
+      # span per Observability.log call, e.g.
+      # `Portage::Ucp.configuration.tracer = OpenTelemetry.tracer_provider.tracer("portage-ucp")`.
+      attr_accessor :tracer
+
+      # idempotency_provider has no default set here, unlike the other
+      # collaborators above — Support::Idempotency#idempotency_store falls
+      # back to a fresh per-instance MemoryStore when this is unset, so
+      # setting it is an opt-in to a shared/process-wide store rather than
+      # a default every adapter instance would otherwise get for free.
+      #
+      # WARNING: Support::Idempotency::FileStore#fetch_or_store holds one
+      # flock across the *entire* dedup'd call, including any network I/O
+      # the block does. That's fine for the single-host CLI it's documented
+      # for (one process at a time, effectively), but this attribute is
+      # process-wide Configuration — set FileStore here in a multi-request
+      # server and every checkout across every request/thread serializes
+      # behind that one lock. FileStore also has no TTL/eviction: the
+      # backing file grows forever, one entry per idempotency key ever
+      # seen. Don't set this to FileStore outside a short-lived CLI
+      # process; a long-lived server needs a store with per-key locking
+      # and eviction instead.
+      attr_accessor :idempotency_provider
+
+      # mandate_trusted_keys is likewise unset by default (see
+      # Dispatcher's mandate_trust_keys doc / Ap2::MandateGuard) — this gem
+      # has no AP2 issuer keys of its own. require_mandate_signature
+      # defaults to false so an unconfigured Dispatcher keeps today's
+      # shape-only posture; a caller flips it on to make MandateGuard
+      # raise instead of silently skipping crypto when trusted_keys
+      # resolves to nil (design-log §33 fail-closed option).
 
       def initialize
         @registry = CapabilityRegistry.default
@@ -19,6 +54,7 @@ module Portage
         @payment_handlers = []
         @signing_keys = []
         @services = []
+        @require_mandate_signature = false
       end
     end
 

data/lib/portage/ucp/dispatcher.rb

@@ -35,9 +35,26 @@ module Portage
       #   duck-typed the same way. `nil` by default and never `require`d
       #   from core (§2: core stays dependency-light); a consumer wires
       #   one in from their own app after requiring that gem themselves.
+      # @param mandate_trust_keys [Array<Hash>, #call, nil] forwarded to
+      #   Ap2::MandateGuard.validate! as `trusted_keys:`. Defaults to
+      #   Configuration#mandate_trusted_keys, which itself has no default —
+      #   same reasoning as `journal`: this gem has no AP2 issuer keys of
+      #   its own to default to, so an unconfigured Dispatcher gets
+      #   shape-only mandate validation, not a silent skip of crypto a
+      #   caller thought was on. A caller with a real trust anchor (a PSP
+      #   adapter's own key store, or a resolver against the issuing
+      #   agent's manifest) passes it here to get Ap2::MandateSignature's
+      #   cryptographic check on every dispatch that carries a `mandate`.
+      # @param require_mandate_signature [Boolean] forwarded to
+      #   Ap2::MandateGuard.validate! as `require_signature:`. Defaults to
+      #   Configuration#require_mandate_signature (false) — set true to
+      #   make a dispatch with a `mandate` but no resolvable trust anchor
+      #   raise InvalidMandateError instead of downgrading to shape-only.
       def initialize(adapter:, registry: CapabilityRegistry.default, logger: Portage::Ucp.configuration.logger,
                      shop: nil, transaction_log: Support::TransactionLog.new, policy: Policy.load,
-                     confirmer: Confirmer::Terminal.new, order_ledger: Support::OrderLedger.new, journal: nil)
+                     confirmer: Confirmer::Terminal.new, order_ledger: Support::OrderLedger.new, journal: nil,
+                     mandate_trust_keys: Portage::Ucp.configuration.mandate_trusted_keys,
+                     require_mandate_signature: Portage::Ucp.configuration.require_mandate_signature)
         @adapter = adapter
         @registry = registry
         @logger = logger
@@ -47,6 +64,8 @@ module Portage
         @confirmer = confirmer
         @order_ledger = order_ledger
         @journal = journal
+        @mandate_trust_keys = mandate_trust_keys
+        @require_mandate_signature = require_mandate_signature
       end
 
       # @param correlation_id [String, nil] threaded through to the adapter
@@ -91,7 +110,10 @@ module Portage
       # every call already passes through.
       def validate_inbound_boundaries!(arguments)
         Portage::Ucp::PaymentTokenGuard.validate!(arguments[:payment_token]) if arguments.key?(:payment_token)
-        Portage::Ucp::Ap2::MandateGuard.validate!(arguments[:mandate]) if arguments[:mandate]
+        return unless arguments[:mandate]
+
+        Portage::Ucp::Ap2::MandateGuard.validate!(arguments[:mandate], trusted_keys: @mandate_trust_keys,
+                                                                       require_signature: @require_mandate_signature)
       end
 
       # Outbound counterpart to the above (design-log §33) — every adapter's

data/lib/portage/ucp/errors.rb

@@ -15,10 +15,11 @@ module Portage
     # guard's own error, not value_objects.rb's.
     class InvalidPaymentEnrollmentError < Error; end
     # Raised by Ap2::MandateGuard.validate! (design-log §33/Phase B) — a
-    # mandate that's expired or missing a required field. Mandate-shape
-    # validation only, not cryptographic AP2 verification: no key
-    # infrastructure or trust anchor exists in this repo to verify a
-    # mandate's signature against (see Ap2::MandateGuard's own comment).
+    # mandate that's expired, missing a required field, or (when the caller
+    # supplies a `trusted_keys:` trust anchor) fails cryptographic
+    # verification via Ap2::MandateSignature. Shape-only vs shape+crypto is
+    # the caller's choice, not this error's — see Ap2::MandateGuard's own
+    # comment.
     class InvalidMandateError < Error; end
     class RateLimitExceededError < Error; end
     # Raised by #complete_checkout when the platform rejects completion

data/lib/portage/ucp/mcp/server.rb

@@ -13,12 +13,20 @@ module Portage
         # doesn't need one keyword argument per collaborator.
         Context = Struct.new(:dispatcher, :authenticator, :rate_limiter, :logger, keyword_init: true)
 
+        # @param journal [#record_checkout, nil] forwarded straight to
+        #   `Dispatcher.new` (see its own doc comment) — `nil` by default and
+        #   never `require`d from core (§2), same as `Dispatcher` itself.
+        #   Named here explicitly, rather than left to fall through
+        #   `**server_opts`, so a consumer wiring a real journal through
+        #   `Client.for_adapter`/`Loopback` (both already forward
+        #   `**server_opts` here) has a documented seam to do it at (§37).
         def self.build(adapter:, registry: Portage::Ucp.configuration.registry,
                        authenticator: Portage::Ucp.configuration.authenticator,
                        rate_limiter: Portage::Ucp.configuration.rate_limiter,
-                       logger: Portage::Ucp.configuration.logger, **server_opts)
+                       logger: Portage::Ucp.configuration.logger, journal: nil, **server_opts)
           context = Context.new(
-            dispatcher: Portage::Ucp::Dispatcher.new(adapter: adapter, registry: registry, logger: logger),
+            dispatcher: Portage::Ucp::Dispatcher.new(adapter: adapter, registry: registry, logger: logger,
+                                                     journal: journal),
             authenticator: authenticator, rate_limiter: rate_limiter, logger: logger
           )
           tools = registry.advertised(adapter).flat_map do |capability|

data/lib/portage/ucp/observability.rb

@@ -23,7 +23,9 @@ module Portage
       REDACTED = "[REDACTED]".freeze
 
       def self.log(logger, event, **fields)
-        logger.info(JSON.generate({ event: event }.merge(redact(fields))))
+        redacted = redact(fields)
+        logger.info(JSON.generate({ event: event }.merge(redacted)))
+        emit_span(event, redacted)
       end
 
       def self.redact(value)
@@ -36,6 +38,44 @@ module Portage
           value
         end
       end
+
+      # Opt-in only — no OTel dependency in the gemspec, so this never fires
+      # unless a consumer sets Configuration#tracer to something responding
+      # to #in_span(name, attributes:), e.g.
+      # `OpenTelemetry.tracer_provider.tracer("portage-ucp")`. The JSON-to-
+      # Logger path above is unconditional and unaffected either way — this
+      # is an additional emitter over the same already-redacted event set,
+      # not a replacement for it.
+      def self.emit_span(event, fields)
+        tracer = Portage::Ucp.configuration.tracer
+        return unless tracer
+
+        # The span exists to record that this event happened, not to wrap
+        # any work of its own — #log is a fire-and-forget instrumentation
+        # call, so there's nothing to put in the block.
+        tracer.in_span(event, attributes: flatten_attributes(fields)) {} # rubocop:disable Lint/EmptyBlock
+      end
+      private_class_method :emit_span
+
+      # OTel span attributes must be a flat String => String/Numeric/Boolean
+      # (or homogeneous array thereof) map — nested hashes aren't valid, so
+      # this dot-joins nested keys instead of shipping them as-is.
+      def self.flatten_attributes(fields, prefix = nil)
+        fields.each_with_object({}) do |(key, value), attrs|
+          full_key = prefix ? "#{prefix}.#{key}" : key.to_s
+          case value
+          when Hash
+            attrs.merge!(flatten_attributes(value, full_key))
+          when Array
+            attrs[full_key] = value.map(&:to_s)
+          when nil
+            next
+          else
+            attrs[full_key] = value
+          end
+        end
+      end
+      private_class_method :flatten_attributes
     end
   end
 end

data/lib/portage/ucp/railtie.rb

@@ -0,0 +1,14 @@
+module Portage
+  module Ucp
+    # Registers `rails g portage:ucp:install` with a host Rails app. Only
+    # loaded when Rails is already present (see the guarded require at the
+    # bottom of ucp.rb) — this gem has no Rails dependency of its own (it's
+    # the protocol-only core, per the gemspec), so Rails integration is
+    # opt-in via whatever the host app already bundles.
+    class Railtie < ::Rails::Railtie
+      generators do
+        require "generators/portage/ucp/install/install_generator"
+      end
+    end
+  end
+end

data/lib/portage/ucp/support/idempotency/file_store.rb

@@ -6,9 +6,16 @@ module Portage
       module Idempotency
         # Cross-process, cross-restart store for the common CLI case: one
         # host, potentially many `portage` invocations, no shared server to
-        # hold an in-memory table for them. A single file under `flock`
-        # stands in for that — every read/write acquires the lock so two
-        # processes racing on the same key don't both run the mutation.
+        # hold an in-memory table for them. A dedicated `.lock` file under
+        # `flock` stands in for that — see `with_lock` for why it's a
+        # separate file from the data file. `#fetch`/`#store` each acquire
+        # the lock for their own call only, so pairing them (the old
+        # `Idempotency#dedup` shape) leaves a window between the two
+        # acquisitions where a second process can also read NOT_FOUND and
+        # also run the mutation — dedup now goes through `#fetch_or_store`
+        # instead, which holds one lock across the whole check-then-set and
+        # is what actually gives two processes racing on the same key the
+        # guarantee that only one of them runs it.
         #
         # Marshal, not JSON: dedup'd return values are arbitrary adapter
         # domain objects (Data.define value objects, nested structures) that
@@ -24,37 +31,67 @@ module Portage
         class FileStore
           def initialize(path: File.join(Dir.home, ".portage", "idempotency.marshal"))
             @path = path
+            @lock_path = "#{path}.lock"
           end
 
           def fetch(key)
-            with_lock(File::LOCK_SH) { |data, _file| data.key?(key) ? data[key] : NOT_FOUND }
+            with_lock(File::LOCK_SH) { |data| data.key?(key) ? data[key] : NOT_FOUND }
           end
 
           def store(key, value)
-            with_lock(File::LOCK_EX) do |data, file|
+            with_lock(File::LOCK_EX) do |data|
               data[key] = value
-              persist(data, file)
+              persist(data)
             end
             value
           end
 
           def include?(key)
-            with_lock(File::LOCK_SH) { |data, _file| data.key?(key) }
+            with_lock(File::LOCK_SH) { |data| data.key?(key) }
+          end
+
+          # Atomic check-then-set, unlike calling `fetch` then `store`: those
+          # are two separate `with_lock` acquisitions, so the shared lock is
+          # released between them and a second process can read NOT_FOUND in
+          # the gap and run the same mutation — the exact double-charge §9a
+          # exists to prevent. Holding one `LOCK_EX` across the read, the
+          # block (the actual mutation), and the write closes that window.
+          # Coarser-grained than a per-key lock — this blocks *every* key on
+          # the file while one mutation is in flight, not just this one — but
+          # correctness beats throughput for a single-host CLI process, and
+          # that's the case this store is documented for.
+          def fetch_or_store(key)
+            with_lock(File::LOCK_EX) do |data|
+              next data[key] if data.key?(key)
+
+              value = yield
+              data[key] = value
+              persist(data)
+              value
+            end
           end
 
           private
 
+          # Locks a sidecar `.lock` file rather than `@path` itself, because
+          # `persist` below replaces `@path` via rename to avoid ever leaving
+          # a torn write on disk. A lock held on the data file's inode
+          # wouldn't survive that swap — a second process already blocked on
+          # `flock` for the old inode would wake up into a stale, pre-write
+          # view instead of being serialized after the write. The lock file
+          # is never renamed, so it stays a stable thing to serialize on.
           def with_lock(lock_mode)
             FileUtils.mkdir_p(File.dirname(@path))
-            File.open(@path, File::RDWR | File::CREAT, 0o600) do |file|
-              file.flock(lock_mode)
-              yield(read(file), file)
+            File.open(@lock_path, File::RDWR | File::CREAT, 0o600) do |lock_file|
+              lock_file.flock(lock_mode)
+              yield(read)
             end
           end
 
-          def read(file)
-            file.rewind
-            raw = file.read
+          def read
+            return {} unless File.exist?(@path)
+
+            raw = File.read(@path)
             return {} if raw.empty?
 
             # rubocop:disable Security/MarshalLoad -- this file is written only
@@ -62,13 +99,28 @@ module Portage
             # exposure); see the class comment on the trust boundary.
             Marshal.load(raw)
             # rubocop:enable Security/MarshalLoad
+          rescue StandardError
+            # A truncated write (crash mid-persist) or a renamed/removed class
+            # (Marshal replays the dumped class name) both poison this file
+            # forever without a rescue here — every future `portage`
+            # invocation would raise just from opening the store. Treat
+            # either as an empty store, same posture as OrderLedger::FileStore
+            # rescuing JSON::ParserError.
+            {}
           end
 
-          def persist(data, file)
-            file.rewind
-            file.truncate(0)
-            file.write(Marshal.dump(data))
-            file.flush
+          def persist(data)
+            tmp_path = "#{@path}.#{Process.pid}.#{object_id}.tmp"
+            File.open(tmp_path, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |tmp|
+              tmp.write(Marshal.dump(data))
+              tmp.flush
+            end
+            # Rename, not truncate+write in place: a crash between truncate
+            # and write used to leave a half-written file that `read` above
+            # would then have to poison-recover from. A rename is atomic, so
+            # readers only ever see the old complete file or the new complete
+            # one, never a torn one.
+            File.rename(tmp_path, @path)
             File.chmod(0o600, @path)
           end
         end

data/lib/portage/ucp/support/idempotency/memory_store.rb

@@ -21,6 +21,17 @@ module Portage
             @mutex.synchronize { @data[key] = value }
           end
 
+          # Atomic check-then-set: `Idempotency#dedup`'s own per-key `Mutex`
+          # already serializes same-process racers on this key, so a plain
+          # fetch-then-store pair is safe here — unlike `FileStore`, there's
+          # no second process able to interleave between the two steps.
+          def fetch_or_store(key)
+            cached = fetch(key)
+            return cached unless cached.equal?(NOT_FOUND)
+
+            store(key, yield)
+          end
+
           # Duck-types Hash#include? so this can stand in wherever a caller
           # (e.g. the conformance kit, `rspec.rb`) just wants to assert a key
           # was dedup'd, without reaching for the internal `fetch` sentinel.

data/lib/portage/ucp/support/idempotency.rb

@@ -9,12 +9,17 @@ module Portage
       # — this is that table, now backed by a pluggable store instead of a
       # bare Hash.
       #
-      # Defaults to `MemoryStore` (in-process, lost on restart — the same
-      # durability the old bare Hash had). A consumer that needs dedup to
-      # survive a process restart or be shared across processes (the actual
-      # complaint behind this: a single-host CLI invoked fresh per command,
-      # or a multi-worker server) injects a different store via
-      # `idempotency_store=` — `FileStore` ships for the single-host case;
+      # Defaults to a fresh `MemoryStore` per including instance (in-process,
+      # lost on restart — the same durability the old bare Hash had, and
+      # the same isolation: one adapter instance's dedup table never leaks
+      # into another's). A consumer that needs dedup to survive a process
+      # restart or be shared across processes (the actual complaint behind
+      # this: a single-host CLI invoked fresh per command, or a
+      # multi-worker server) sets `Portage::Ucp.configuration.idempotency_provider`
+      # once via `configure { |c| c.idempotency_provider = ... }` — every
+      # instance that doesn't set its own store via `idempotency_store=`
+      # then shares that one process-wide store instead of each getting its
+      # own in-memory table. `FileStore` ships for the single-host case;
       # Redis/SQLite-backed stores are a consumer's own implementation
       # against the same two-method interface (`#fetch(key)` /
       # `#store(key, value)`).
@@ -37,21 +42,27 @@ module Portage
 
         private
 
-        def dedup(idempotency_key)
+        def dedup(idempotency_key, &block)
           init_idempotency_locks!
 
-          key_lock = @idempotency_mutex.synchronize { @idempotency_locks[idempotency_key] ||= Mutex.new }
-
-          key_lock.synchronize do
-            cached = idempotency_store.fetch(idempotency_key)
-            next cached unless cached.equal?(NOT_FOUND)
-
-            idempotency_store.store(idempotency_key, yield)
+          key_lock = checkout_idempotency_lock(idempotency_key)
+          begin
+            # `key_lock` only serializes threads inside *this* process — it can't
+            # stop a second `portage` invocation (a second process, its own
+            # Mutex) from racing this one. That's the store's job: `fetch` then
+            # `store` as two separate calls (the old shape here) is two separate
+            # lock acquisitions on `FileStore`, so both processes can observe
+            # NOT_FOUND and both run `yield` — the double-charge §9a exists to
+            # prevent. `fetch_or_store` does the whole check-then-set under one
+            # lock acquisition instead.
+            key_lock.synchronize { idempotency_store.fetch_or_store(idempotency_key, &block) }
+          ensure
+            checkin_idempotency_lock(idempotency_key)
           end
         end
 
         def idempotency_store
-          @idempotency_store ||= MemoryStore.new
+          @idempotency_store ||= Portage::Ucp.configuration.idempotency_provider || MemoryStore.new
         end
 
         def init_idempotency_locks!
@@ -62,6 +73,33 @@ module Portage
             @idempotency_locks ||= {}
           end
         end
+
+        # `@idempotency_locks` is per-instance and never bounded otherwise —
+        # a long-lived process (server, not a CLI invoked fresh per command)
+        # would accumulate one Mutex per distinct idempotency key forever.
+        # Refcount each entry instead of leaving it in the table for the
+        # instance's lifetime: checkout bumps the count before handing out
+        # the Mutex, checkin drops it and reaps the entry once nothing still
+        # holds a reference. The refcount, not `Mutex#locked?`, is what makes
+        # this safe — a thread waiting on `key_lock.synchronize` still counts
+        # as holding a reference, so the entry can't be deleted (and a
+        # second, disconnected Mutex created for the same key) while it's
+        # still queued.
+        def checkout_idempotency_lock(idempotency_key)
+          @idempotency_mutex.synchronize do
+            entry = (@idempotency_locks[idempotency_key] ||= { mutex: Mutex.new, refcount: 0 })
+            entry[:refcount] += 1
+            entry[:mutex]
+          end
+        end
+
+        def checkin_idempotency_lock(idempotency_key)
+          @idempotency_mutex.synchronize do
+            entry = @idempotency_locks[idempotency_key]
+            entry[:refcount] -= 1
+            @idempotency_locks.delete(idempotency_key) if entry[:refcount].zero?
+          end
+        end
       end
     end
   end

data/lib/portage/ucp/support/order_ledger/file_store.rb

@@ -32,6 +32,12 @@ module Portage
             with_lock(File::LOCK_SH) { |data, _file| data[order_id] }
           end
 
+          def each_record(&block)
+            return enum_for(:each_record) unless block
+
+            with_lock(File::LOCK_SH) { |data, _file| data.values }.each(&block)
+          end
+
           private
 
           def with_lock(lock_mode)

data/lib/portage/ucp/support/order_ledger/store.rb

@@ -16,6 +16,13 @@ module Portage
           def find(order_id)
             raise NotImplementedError, "#{self.class} must implement #find"
           end
+
+          # Yields every snapshot, in no guaranteed order, without a block
+          # returns an Enumerator — same §22 item 6 console read surface
+          # added to `TransactionLog::Store`. Additive; `#find` is unchanged.
+          def each_record(&)
+            raise NotImplementedError, "#{self.class} must implement #each_record"
+          end
         end
       end
     end

data/lib/portage/ucp/support/order_ledger.rb

@@ -41,6 +41,14 @@ module Portage
         def find(order_id)
           @store.find(order_id)
         end
+
+        def each_record(&)
+          @store.each_record(&)
+        end
+
+        def all
+          enum_for(:each_record).to_a
+        end
       end
     end
   end

data/lib/portage/ucp/support/session_lock.rb

@@ -21,9 +21,12 @@ module Portage
         def synchronize(session_id, &)
           init_session_locks!
 
-          key_lock = @session_lock_mutex.synchronize { @session_locks[session_id] ||= Mutex.new }
-
-          key_lock.synchronize(&)
+          key_lock = checkout_session_lock(session_id)
+          begin
+            key_lock.synchronize(&)
+          ensure
+            checkin_session_lock(session_id)
+          end
         end
 
         def init_session_locks!
@@ -34,6 +37,29 @@ module Portage
             @session_locks ||= {}
           end
         end
+
+        # Same unbounded-growth problem as Idempotency's per-key locks: one
+        # Mutex per session/cart id, never removed, in a process that outlives
+        # any single session. Refcount instead of `Mutex#locked?` so an entry
+        # is only reaped once no thread — including one still queued on
+        # `key_lock.synchronize` — holds a reference to it; deleting on
+        # `locked?` alone would let a queued waiter end up serialized against
+        # a disconnected Mutex a new caller replaced it with.
+        def checkout_session_lock(session_id)
+          @session_lock_mutex.synchronize do
+            entry = (@session_locks[session_id] ||= { mutex: Mutex.new, refcount: 0 })
+            entry[:refcount] += 1
+            entry[:mutex]
+          end
+        end
+
+        def checkin_session_lock(session_id)
+          @session_lock_mutex.synchronize do
+            entry = @session_locks[session_id]
+            entry[:refcount] -= 1
+            @session_locks.delete(session_id) if entry[:refcount].zero?
+          end
+        end
       end
     end
   end

data/lib/portage/ucp/support/transaction_log/file_store.rb

@@ -75,6 +75,12 @@ module Portage
             end
           end
 
+          def each_record(&block)
+            return enum_for(:each_record) unless block
+
+            with_lock(File::LOCK_SH) { |data, _file| data.values }.each(&block)
+          end
+
           private
 
           def with_lock(lock_mode)

data/lib/portage/ucp/support/transaction_log/store.rb

@@ -44,6 +44,15 @@ module Portage
             raise NotImplementedError, "#{self.class} must implement #find"
           end
 
+          # Yields every record, in no guaranteed order, without a block
+          # returns an Enumerator — the read surface §22 item 6's console
+          # needed and this class's own comment flagged as the trigger to
+          # add it. `#find`/`#completed_since` stay as they were; this is
+          # additive, not a replacement for either.
+          def each_record(&)
+            raise NotImplementedError, "#{self.class} must implement #each_record"
+          end
+
           def completed_since(since, shop:)
             raise NotImplementedError, "#{self.class} must implement #completed_since"
           end

data/lib/portage/ucp/support/transaction_log.rb

@@ -102,6 +102,14 @@ module Portage
         def completed_since(since, shop:)
           @store.completed_since(since, shop: shop)
         end
+
+        def each_record(&)
+          @store.each_record(&)
+        end
+
+        def all
+          enum_for(:each_record).to_a
+        end
       end
     end
   end

data/lib/portage/ucp/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Ucp
-    VERSION = "0.6.0".freeze
+    VERSION = "0.7.1".freeze
   end
 end

data/lib/portage/ucp.rb

@@ -32,6 +32,7 @@ require_relative "ucp/support/token_ref"
 require_relative "ucp/payment_token_guard"
 require_relative "ucp/payment_enrollment_guard"
 require_relative "ucp/ap2/mandate"
+require_relative "ucp/ap2/mandate_signature"
 require_relative "ucp/ap2/mandate_guard"
 require_relative "ucp/policy"
 require_relative "ucp/policy_guard"
@@ -64,6 +65,10 @@ require_relative "ucp/security/signature"
 require_relative "ucp/rack/signature_verification"
 require_relative "ucp/resolver"
 require_relative "ucp/check"
+# Rails integration is opt-in and never a hard dependency (this stays the
+# protocol-only core gem, per the gemspec) — only loaded when a host app
+# already has Rails on the load path.
+require_relative "ucp/railtie" if defined?(Rails::Railtie)
 
 module Portage
   module Ucp

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Tom Whitbread
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-15 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -148,10 +148,13 @@ files:
 - LICENSE
 - README.md
 - exe/portage-ucp-check
+- lib/generators/portage/ucp/install/install_generator.rb
+- lib/generators/portage/ucp/install/templates/portage_ucp.rb
 - lib/portage/ucp.rb
 - lib/portage/ucp/adapter.rb
 - lib/portage/ucp/ap2/mandate.rb
 - lib/portage/ucp/ap2/mandate_guard.rb
+- lib/portage/ucp/ap2/mandate_signature.rb
 - lib/portage/ucp/authenticator.rb
 - lib/portage/ucp/capabilities/cart.rb
 - lib/portage/ucp/capabilities/catalog.rb
@@ -182,6 +185,7 @@ files:
 - lib/portage/ucp/rack/manifest_endpoint.rb
 - lib/portage/ucp/rack/signature_verification.rb
 - lib/portage/ucp/rack/webhook_endpoint.rb
+- lib/portage/ucp/railtie.rb
 - lib/portage/ucp/rate_limiter.rb
 - lib/portage/ucp/reference_adapter.rb
 - lib/portage/ucp/resolver.rb