portage-cli 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4a3c3b0ce94430985a4660b316c7fafb711d8814bc9497bba70d866bf927dc1
-  data.tar.gz: ac8bbf8f8f08ca0eda4962adfa8d240dae05e54b571a40b8aed68a8b3dd3ea03
+  metadata.gz: 86b0359cf6f3c98f45853a7407dd03e9688f91212ce1ee05e84727b34450e3ad
+  data.tar.gz: 94eeec1e819b534d38055bc55c61a74cc61730d0134e5f7bc5da7aef3a257485
 SHA512:
-  metadata.gz: 7484fb5d07dc6c4c9bcfbfb01f84909b6c0c551d3e117bb4854ca5e67049779657272ea3c5c904847d2381780b11ffd839efa0e689c9eb20d2db8bd903126737
-  data.tar.gz: 70e0a2624e6e20714c2898069e53440cb620044c513a2644f12576b3da96bd0b2be5cc6603a2774a4f229eb8e19d5724889b9353ef3fab628ec6c06587a03a00
+  metadata.gz: b8f1f2b0c0a9addba9154c3951c90ec4c3dcd1b8b765e03eca8c13ed17f80c23b7999efaa993c4173f045f12c7ad724705667e00164d5f3a87905caab216197a
+  data.tar.gz: 26e138751551e630c86de1ccd2e701f9cf287ef0cf6ed78e852bae7ed8c43922257d3f7a3840a3f8735de0306c4d39e01f40bf9348388041a9516c65bd3dbbd8

data/CHANGELOG.md

@@ -6,6 +6,36 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-09-15
+
+- No behavior change — widens the `portage-ucp` dependency pin to `~> 0.6`
+  so this gem can install alongside `portage-ucp` 0.6.0 (the pessimistic
+  `~> 0.5` pin published with 0.4.0 excludes it).
+
+## [0.4.0] - 2026-09-14
+
+- Added `portage payment list/enroll/set-default/remove/freeze/revoke` —
+  card-on-file storage so `buy`'s `--payment-token` dead-end can fall back to
+  a stored default (`@payment_token ||= PaymentMethods.default`) instead of
+  requiring a fresh token on every call (docs/plans/agentic-payments.md
+  Phase 1). Storage picks macOS Keychain / Linux Secret Service (`secret-tool`,
+  D-Bus session required) / a headless `PORTAGE_PAYMENT_TOKEN`-only tier, in
+  that order, with no homegrown fallback store. `enroll` is a browser handoff
+  to a gateway-hosted setup page (the new `app.portage-ucp.payment_enrollment`
+  capability in `portage-ucp`) — no raw card number ever reaches this
+  process.
+- Added `portage payment enroll --scope-merchant/--scope-max-amount/
+  --scope-currency` — binds a Phase 2 per-token policy scope at enrollment
+  time, written to `Portage::Ucp::Policy` keyed by the same `token_ref`
+  `PolicyGuard` derives from the token at charge time.
+- Added `portage policy show/set` — manages the Phase 2 policy file's
+  top-level caps/velocity/allowlist (`Portage::Ucp::Policy`), checked by
+  `PolicyGuard` on every `complete_checkout`.
+- Widened the `portage-ucp` dependency pin from `~> 0.4` to `~> 0.5` and the
+  `portage-ucp-client` pin from `~> 0.2` to `~> 0.3` — this release's
+  `Policy`/`PolicyGuard`/`TokenRef` and `Session#create_payment_enrollment`
+  calls only exist from those versions on.
+
 ## [0.3.0] - 2026-08-28
 
 - Fixed: `find` and `buy` were treating `search_catalog`'s wire envelope

data/README.md

@@ -73,6 +73,18 @@ portage compare <url> --product-id ID [--id VALUE ...] [--results N]
                        [--max-price N] [--json]
 portage history [list] [--purchases|--searches] [--limit N] [--json]
 portage history clear [--purchases|--searches]
+portage payment list [--json]
+portage payment enroll <url> [--label NAME] [--json]
+                              [--scope-merchant HOST ...] [--scope-max-amount N] [--scope-currency CUR]
+portage payment set-default <id>
+portage payment remove <id>
+portage payment freeze <id>
+portage payment revoke <id>
+portage policy show [--json]
+portage policy set [--per-transaction-cap N --currency CUR]
+                    [--rolling-cap N --rolling-window-seconds N --currency CUR]
+                    [--velocity-count N --velocity-window-seconds N]
+                    [--allow HOST ...] [--clear-allowlist]
 ```
 
 - `--query` — search term. Against the store's catalog when you name a store,
@@ -80,7 +92,9 @@ portage history clear [--purchases|--searches]
 - `--qty` — quantity, default `1`.
 - `--payment-token` — a tokenized payment credential (never a raw card number —
   `PaymentTokenGuard` in the core gem rejects those before they reach the wire).
-  Omit for `--dry-run` or to just browse.
+  Omit for `--dry-run` or to just browse, or to fall back to whatever
+  `portage payment` has on file as the default (see "Payment" below) — the
+  flag always wins when both are present.
 - `--product-id` — buy exactly this product rather than whatever the catalog
   search ranks first. If the id isn't in the results, nothing is bought.
 - `--store` — name the merchant without giving a full URL; skips the search.
@@ -162,6 +176,83 @@ portage history clear --purchases     # wipe just one
 This is a local convenience cache, not an audit log — `portage history clear`
 deletes it outright, and there's no server-side record.
 
+### Payment
+
+Card-on-file storage for `--payment-token`, so an autonomous agent can
+complete a checkout without a human handing over a fresh token every time
+(docs/plans/agentic-payments.md Phase 1). No raw card number ever touches
+this process — enrollment is a browser handoff to the gateway's own hosted
+setup page:
+
+```bash
+portage payment enroll https://your-shop.example --label "Ops card"
+# → prints a setup_url; visit it, enter the card there, this process polls
+#   until the gateway hands back a token, then stores it.
+
+portage payment list
+portage payment set-default <id>
+portage payment freeze <id>    # blocks spend, keeps the enrollment
+portage payment revoke <id>    # deletes the token and the enrollment
+portage payment remove <id>    # same as revoke — no processor-side
+                                # "invalidate this token" call to differ by
+```
+
+`--scope-merchant`/`--scope-max-amount`/`--scope-currency` bind a Phase 2
+policy scope to the token at enrollment time, rather than after the fact:
+
+```bash
+portage payment enroll https://your-shop.example --label "Ops card" \
+  --scope-merchant your-shop.example --scope-max-amount 5000 --scope-currency USD
+```
+
+Written to `Policy` keyed by the same `token_ref` `PolicyGuard` derives from
+the token at charge time — enrollment is the only place a scope gets
+attached to a specific token; `portage policy set` below only touches the
+global caps/velocity/allowlist, not per-token scopes.
+
+Storage picks the strongest tier your platform actually has, in order, with
+no homegrown fallback store of its own:
+
+1. **macOS Keychain**, via the `security` CLI.
+2. **Linux Secret Service** (GNOME Keyring/KWallet), via `secret-tool` — only
+   when a D-Bus session is actually live.
+3. **Headless** — no local storage at all. The token *is*
+   `PORTAGE_PAYMENT_TOKEN`; `list`/`enroll`/`freeze`/etc. don't apply, since
+   there's nothing local to manage.
+
+**Local policy guards agent mistakes, not a compromised agent.** Anyone
+running as the local user can read/edit `~/.portage/payment_methods.json` or
+the Keychain/Secret Service entry directly — this is a convenience store, not
+a security boundary. The real backstop against a rogue or compromised agent
+is an issuer-side limit (a virtual card via Stripe Issuing, Privacy.com,
+etc.), not anything in this gem.
+
+### Policy
+
+`portage policy show`/`set` manage the Phase 2 policy file
+(`Portage::Ucp::Policy`, checked by `PolicyGuard` on every `complete_checkout`)
+— top-level caps, velocity, and a merchant allowlist that apply regardless of
+which token is spending:
+
+```bash
+portage policy show
+portage policy show --json
+
+portage policy set --per-transaction-cap 10000 --currency USD
+portage policy set --rolling-cap 50000 --rolling-window-seconds 86400 --currency USD
+portage policy set --velocity-count 5 --velocity-window-seconds 3600
+portage policy set --allow shop.example.com --allow other-shop.example.com
+portage policy set --clear-allowlist
+```
+
+Each `--*` group is applied independently — `portage policy set --allow
+shop.example.com` touches only the allowlist, leaving caps/velocity as they
+were, so caps and the allowlist can be configured in separate invocations.
+An empty policy (nothing ever set) means every check passes; this is an
+opt-in guardrail, not a default-deny one. Per-token scopes (merchant/amount
+limits bound to one enrolled card) are set via `portage payment enroll
+--scope-*` above, not here.
+
 ### Shipping address (own-store checkouts only)
 
 When buying against your own store (`portage buy`'s step 2 adapter-credentials

data/lib/portage/cli/buy.rb

@@ -3,6 +3,7 @@ require "uri"
 require "json"
 require "portage/ucp"
 require "portage/ucp/client"
+require_relative "payment_methods"
 
 module Portage
   module Cli
@@ -262,9 +263,11 @@ module Portage
       end
 
       def complete(session, source, products, checkout)
+        @payment_token ||= PaymentMethods.default
         unless @payment_token
           return checkout_report(source, products, checkout,
-                                 message: "No --payment-token given — can't complete the purchase.")
+                                 message: "No --payment-token given, and no default payment method on file — " \
+                                          "run `portage payment enroll` or pass --payment-token.")
         end
 
         completed = session.complete_checkout(checkout_id: checkout["id"], payment_token: @payment_token)

data/lib/portage/cli/payment_methods/env_backend.rb

@@ -0,0 +1,28 @@
+module Portage
+  module Cli
+    class PaymentMethods
+      # Headless tier (no D-Bus session — the common case for a server-
+      # deployed agent): no local storage at all, consistent with how
+      # Resolver.env_for already resolves platform credentials. The token
+      # *is* PORTAGE_PAYMENT_TOKEN — there's no id/enrollment/freeze/revoke
+      # bookkeeping to do, since there's nowhere local to keep it.
+      class EnvBackend
+        VAR = "PORTAGE_PAYMENT_TOKEN".freeze
+
+        def self.available? = true
+
+        def read(_id) = ENV.fetch(VAR, nil)
+
+        def write(_id, _token)
+          raise NotSupportedError, "headless mode has no local storage — set #{VAR} instead"
+        end
+
+        def delete(_id)
+          raise NotSupportedError, "headless mode has no local storage — unset #{VAR} instead"
+        end
+      end
+
+      class NotSupportedError < StandardError; end
+    end
+  end
+end

data/lib/portage/cli/payment_methods/keychain_backend.rb

@@ -0,0 +1,42 @@
+require "open3"
+
+module Portage
+  module Cli
+    class PaymentMethods
+      # macOS Keychain, via the `security` CLI (Open3 — array args, never an
+      # interpolated shell string, so an id/token containing shell metachars
+      # can't inject). The token is the generic-password's own secret; `id`
+      # is the account name, always scoped to SERVICE so it never collides
+      # with an unrelated Keychain entry.
+      class KeychainBackend
+        SERVICE = "portage-cli-payment".freeze
+
+        def self.available?
+          RUBY_PLATFORM.include?("darwin") && Portage::Cli::PaymentMethods.executable?("security")
+        end
+
+        # `-U` upserts rather than erroring on a pre-existing account, so
+        # re-enrolling under the same id just replaces the secret.
+        def write(id, token)
+          run("add-generic-password", "-a", id, "-s", SERVICE, "-w", token, "-U")
+        end
+
+        def read(id)
+          out, status = Open3.capture2("security", "find-generic-password", "-a", id, "-s", SERVICE, "-w")
+          status.success? ? out.chomp : nil
+        end
+
+        def delete(id)
+          run("delete-generic-password", "-a", id, "-s", SERVICE)
+        end
+
+        private
+
+        def run(*)
+          Open3.capture2("security", *)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/payment_methods/secret_service_backend.rb

@@ -0,0 +1,39 @@
+require "open3"
+
+module Portage
+  module Cli
+    class PaymentMethods
+      # Linux Secret Service (GNOME Keyring/KWallet via D-Bus), through the
+      # `secret-tool` CLI. Only reachable with a live D-Bus session — the
+      # headless/no-session case falls through to EnvBackend instead (see
+      # PaymentMethods.detect_backend), never a homegrown fallback store.
+      class SecretServiceBackend
+        SERVICE = "portage-cli-payment".freeze
+
+        def self.available?
+          ENV["DBUS_SESSION_BUS_ADDRESS"].to_s != "" && Portage::Cli::PaymentMethods.executable?("secret-tool")
+        end
+
+        # `secret-tool store` reads the secret from stdin rather than argv,
+        # so it never shows up in `ps`/shell history.
+        def write(id, token)
+          Open3.capture2(
+            "secret-tool", "store", "--label=Portage payment method #{id}",
+            "service", SERVICE, "account", id, stdin_data: token
+          )
+          nil
+        end
+
+        def read(id)
+          out, status = Open3.capture2("secret-tool", "lookup", "service", SERVICE, "account", id)
+          status.success? ? out.chomp : nil
+        end
+
+        def delete(id)
+          Open3.capture2("secret-tool", "clear", "service", SERVICE, "account", id)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/payment_methods.rb

@@ -0,0 +1,265 @@
+require "json"
+require "fileutils"
+require "securerandom"
+require "uri"
+require "net/http"
+require "portage/ucp"
+require "portage/ucp/client"
+
+# Buy::PermissiveAuthenticator (adapter-loopback auth) is used by
+# #adapter_session below — not require_relative'd here to avoid a load
+# cycle (buy.rb will require this file too, for PaymentMethods.default);
+# cli.rb requires "cli/buy" before "cli/payment_methods", so it's already
+# loaded by the time #enroll actually runs.
+require_relative "payment_methods/keychain_backend"
+require_relative "payment_methods/secret_service_backend"
+require_relative "payment_methods/env_backend"
+
+module Portage
+  module Cli
+    # Card-on-file store for `portage buy`'s `--payment-token` dead-end
+    # (buy.rb) — three backend tiers, picked once per process by
+    # .detect_backend, no homegrown crypto or fallback file store of our
+    # own (docs/plans/agentic-payments.md Phase 1):
+    #
+    #   1. macOS Keychain (KeychainBackend, shells out to `security`)
+    #   2. Linux Secret Service (SecretServiceBackend, shells out to
+    #      `secret-tool`) — only when a D-Bus session is actually live
+    #   3. Headless (EnvBackend) — no local storage; the token comes
+    #      straight from PORTAGE_PAYMENT_TOKEN
+    #
+    # The secret itself lives in the backend; this class only keeps
+    # non-secret bookkeeping (label/default/frozen) in
+    # ~/.portage/payment_methods.json — irrelevant for the headless tier,
+    # which has no ids to track at all.
+    #
+    # Local policy guards agent mistakes, not a compromised agent: anyone
+    # running as the local user can edit payment_methods.json directly, so
+    # the real backstop against a rogue/compromised agent is an issuer-side
+    # limit (a virtual card via Stripe Issuing, Privacy.com, etc.), not this
+    # file.
+    class PaymentMethods
+      PATH = File.join(Dir.home, ".portage", "payment_methods.json").freeze
+
+      class UnknownMethodError < StandardError; end
+
+      def self.executable?(name)
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+          File.executable?(File.join(dir, name)) && !File.directory?(File.join(dir, name))
+        end
+      end
+
+      def self.detect_backend
+        return KeychainBackend.new if KeychainBackend.available?
+        return SecretServiceBackend.new if SecretServiceBackend.available?
+
+        EnvBackend.new
+      end
+
+      def self.default(path: PATH, backend: detect_backend) = new(path: path, backend: backend).default
+
+      def initialize(path: PATH, backend: self.class.detect_backend)
+        @path = path
+        @backend = backend
+      end
+
+      # @return [String, nil] the token `portage buy` should use when
+      #   `--payment-token` was omitted, or nil if there isn't one it can
+      #   safely use (nothing enrolled, or the only default is frozen).
+      def default
+        return @backend.read(nil) if headless?
+
+        entry = store["methods"].find { |m| m["default"] }
+        return nil if entry.nil? || entry["frozen"]
+
+        @backend.read(entry["id"])
+      end
+
+      # @return [Array<Hash>] non-secret metadata only — never the token.
+      def list
+        return [] if headless?
+
+        store["methods"]
+      end
+
+      def make_default(id)
+        entry = find!(id)
+        store["methods"].each { |m| m["default"] = (m["id"] == id) }
+        write
+        entry
+      end
+
+      # `remove` and `revoke` are the same hard delete (metadata entry +
+      # backend secret, both gone) — the plan names them separately, but
+      # with no processor-side "invalidate this token" capability to defer
+      # to, there's no real distinction to invent between "remove" and
+      # "delete the token" beyond the name. Both exist as CLI subcommands so
+      # either reads naturally in the moment ("get rid of this" vs. "this
+      # card's compromised, kill it").
+      def remove(id)
+        entry = find!(id)
+        store["methods"].reject! { |m| m["id"] == id }
+        write
+        @backend.delete(id)
+        entry
+      end
+      alias revoke remove
+
+      # Blocks spend without forgetting the enrollment — `default` returns
+      # nil for a frozen default, but the metadata entry (and backend
+      # secret) stay put. No "unfreeze" — the plan draws the line at v1
+      # only needing revoke to fully undo an enrollment.
+      def freeze_method(id)
+        entry = find!(id)
+        entry["frozen"] = true
+        write
+        entry
+      end
+
+      # Starts a browser-handoff enrollment against `url` (native UCP
+      # manifest, or the own-store adapter loopback — same discovery
+      # buy.rb#call uses) and blocks polling
+      # app.portage-ucp.payment_enrollment until the gateway-hosted setup
+      # page resolves to a token or `timeout` elapses. Prints nothing
+      # itself — callers (Cli.run_payment_enroll) own presentation.
+      #
+      # Yields the gateway-hosted `setup_url` to the given block as soon as
+      # it's known (before polling starts) — the caller's one chance to show
+      # it, since this method otherwise doesn't return until "complete" or
+      # `timeout` elapses.
+      #
+      # @return [Hash] {status:, setup_url:, id:, label:} — status is
+      #   "complete", "pending" (timed out — the CLI can re-poll later
+      #   against the same enrollment id), or "unsupported" (nothing at
+      #   `url` advertises payment enrollment).
+      # @param scope [Hash, nil] Phase 2 per-token policy scope, bound at
+      #   enrollment time (docs/plans/agentic-payments.md) — e.g.
+      #   `{merchants: ["shop.example.com"], max_amount: 5000, currency: "USD"}`.
+      #   Written to Portage::Ucp::Policy keyed by the same token_ref
+      #   PolicyGuard derives from the token at charge time, never to
+      #   payment_methods.json — policy config is portage-ucp's file, not
+      #   this gem's.
+      def enroll(url, label: nil, scope: nil, poll_interval: 3, timeout: 300, sleeper: ->(s) { sleep(s) })
+        raise NotSupportedError, "headless mode has no local storage — set PORTAGE_PAYMENT_TOKEN instead" if headless?
+
+        session = discover_session(url)
+        return { status: "unsupported" } unless session && payment_enrollment_advertised?(session)
+
+        enrollment = session.create_payment_enrollment
+        yield enrollment["setup_url"] if block_given?
+        poll_until_resolved(session, enrollment, label, scope, poll_interval, timeout, sleeper)
+      rescue Portage::Ucp::Client::Error
+        # Capability not actually there despite #advertises? being nil
+        # (own-store adapter loopback doesn't know capabilities upfront —
+        # see Session#advertises?) — the adapter simply never registered the
+        # tool, surfaced as a client-side error rather than a Ruby NoMethodError.
+        { status: "unsupported" }
+      end
+
+      private
+
+      def headless?
+        @backend.is_a?(EnvBackend)
+      end
+
+      def poll_until_resolved(session, enrollment, label, scope, poll_interval, timeout, sleeper)
+        deadline = Time.now + timeout
+        current = enrollment
+        until current["status"] == "complete" || Time.now >= deadline
+          sleeper.call(poll_interval)
+          current = session.get_payment_enrollment(enrollment_id: current["id"])
+          return { status: "unsupported" } unless current
+        end
+        return { status: "pending", setup_url: enrollment["setup_url"], id: enrollment["id"] } unless
+          current["status"] == "complete"
+
+        { status: "complete", **enroll_locally(current["payment_token"], label, scope) }
+      end
+
+      def enroll_locally(token, label, scope)
+        id = SecureRandom.uuid
+        @backend.write(id, token)
+        entry = { "id" => id, "label" => label || id, "frozen" => false,
+                  "default" => store["methods"].empty?, "created_at" => Time.now.utc.iso8601 }
+        store["methods"] << entry
+        write
+        set_token_scope(token, scope) if scope
+        { id: id, label: entry["label"] }
+      end
+
+      def set_token_scope(token, scope)
+        token_ref = Portage::Ucp::Support::TokenRef.for(token)
+        Portage::Ucp::Policy.load.set_token_scope(token_ref, stringify_keys(scope))
+      end
+
+      def stringify_keys(hash) = hash.transform_keys(&:to_s)
+
+      # Same native-manifest-first, own-store-adapter-fallback discovery as
+      # Buy#call — duplicated rather than extracted since Buy's version is
+      # entangled with cart/checkout-specific branching this only needs the
+      # session object from.
+      def discover_session(url)
+        native = Portage::Ucp::Client.discover(url)
+        native if native
+      rescue Portage::Ucp::Client::DiscoveryError
+        adapter_session(url)
+      end
+
+      def adapter_session(url)
+        uri = URI.parse(url.to_s =~ %r{\Ahttps?://}i ? url.to_s : "https://#{url}")
+        body, headers = fetch_homepage(uri)
+        platform = body && Portage::Ucp::Resolver.detect_platform(body, headers)
+        return nil unless platform
+
+        env = Portage::Ucp::Resolver.env_for(platform)
+        return nil if Portage::Ucp::Resolver.missing_env(platform, env).any?
+
+        adapter = Portage::Ucp::Resolver.build_adapter(platform, env)
+        Portage::Ucp::Client.for_adapter(adapter, authenticator: Buy::PermissiveAuthenticator.new)
+      rescue StandardError
+        nil
+      end
+
+      def fetch_homepage(uri)
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                                       open_timeout: 5, read_timeout: 5) do |http|
+          http.get(uri.request_uri, { "User-Agent" => "portage-payment-enroll" })
+        end
+        response.is_a?(Net::HTTPSuccess) ? [response.body, response.to_hash] : [nil, {}]
+      rescue StandardError
+        [nil, {}]
+      end
+
+      def payment_enrollment_advertised?(session)
+        session.advertises?("app.portage-ucp.payment_enrollment") != false
+      end
+
+      def find!(id)
+        store["methods"].find { |m| m["id"] == id } || raise(UnknownMethodError, id)
+      end
+
+      def store
+        @store ||= read
+      end
+
+      def read
+        parsed = File.readable?(@path) ? JSON.parse(File.read(@path)) : {}
+        parsed = {} unless parsed.is_a?(Hash)
+        { "methods" => Array(parsed["methods"]) }
+      rescue StandardError
+        { "methods" => [] }
+      end
+
+      # Unlike History#write, a failed write on the payment path is fatal
+      # (docs/plans/agentic-payments.md's "transaction log writes are fatal
+      # on the payment path" applies here too — a swallowed write here would
+      # silently un-set/re-set a default or forget a freeze) — raises
+      # rather than the `rescue StandardError; nil` pattern history.rb uses.
+      def write
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, JSON.generate(@store))
+        File.chmod(0o600, @path)
+      end
+    end
+  end
+end

data/lib/portage/cli/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Cli
-    VERSION = "0.3.0".freeze
+    VERSION = "0.4.1".freeze
   end
 end

data/lib/portage/cli.rb

@@ -8,6 +8,7 @@ require_relative "cli/buy"
 require_relative "cli/find"
 require_relative "cli/compare"
 require_relative "cli/history"
+require_relative "cli/payment_methods"
 
 module Portage
   # `portage` — the single command-line entrypoint for acting as a shopper's
@@ -24,6 +25,18 @@ module Portage
                                     [--max-price N] [--json]
              portage history [list] [--purchases|--searches] [--limit N] [--json]
              portage history clear [--purchases|--searches]
+             portage payment list [--json]
+             portage payment enroll <url> [--label NAME] [--json]
+                                    [--scope-merchant HOST ...] [--scope-max-amount N] [--scope-currency CUR]
+             portage payment set-default <id>
+             portage payment remove <id>
+             portage payment freeze <id>
+             portage payment revoke <id>
+             portage policy show [--json]
+             portage policy set [--per-transaction-cap N --currency CUR]
+                                 [--rolling-cap N --rolling-window-seconds N --currency CUR]
+                                 [--velocity-count N --velocity-window-seconds N]
+                                 [--allow HOST ...] [--clear-allowlist]
     USAGE
 
     # @param argv [Array<String>]
@@ -35,6 +48,8 @@ module Portage
       when "find" then run_find(rest)
       when "compare" then run_compare(rest)
       when "history" then run_history(rest)
+      when "payment" then run_payment(rest)
+      when "policy" then run_policy(rest)
       else
         warn USAGE
         1
@@ -298,6 +313,210 @@ module Portage
     end
     private_class_method :history_search_line
 
+    # --- payment ---
+
+    # Maps each single-id subcommand to the PaymentMethods method it calls —
+    # collapsing what would otherwise be four near-identical `when` branches
+    # (each just yielding a different method to #run_payment_mutate) into one
+    # table lookup.
+    PAYMENT_MUTATIONS = { "set-default" => :make_default, "remove" => :remove,
+                          "freeze" => :freeze_method, "revoke" => :revoke }.freeze
+
+    def self.run_payment(argv)
+      sub = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      return run_payment_list(argv) if sub == "list"
+      return run_payment_enroll(argv) if sub == "enroll"
+      return run_payment_mutate(argv, PAYMENT_MUTATIONS[sub]) if PAYMENT_MUTATIONS.key?(sub)
+
+      warn USAGE
+      1
+    end
+    private_class_method :run_payment
+
+    def self.run_payment_list(argv)
+      json = false
+      OptionParser.new { |parser| parser.on("--json") { json = true } }.parse!(argv)
+      methods = PaymentMethods.new.list
+      puts json ? JSON.pretty_generate(methods) : format_payment_list(methods)
+      0
+    end
+    private_class_method :run_payment_list
+
+    # Shared by set-default/remove/freeze/revoke — each takes exactly one
+    # `<id>` positional arg and reports the (now-updated) entry, or fails
+    # cleanly for an id that isn't enrolled.
+    def self.run_payment_mutate(argv, method_name)
+      id = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      unless id
+        warn USAGE
+        return 1
+      end
+
+      entry = PaymentMethods.new.public_send(method_name, id)
+      puts "#{entry['label']} (#{entry['id']}) — default: #{entry['default']}, frozen: #{entry['frozen']}"
+      0
+    rescue PaymentMethods::UnknownMethodError
+      warn "No payment method enrolled with id #{id}."
+      1
+    end
+    private_class_method :run_payment_mutate
+
+    def self.parse_payment_enroll_options(argv)
+      opts = { scope_merchants: [] }
+      OptionParser.new do |parser|
+        parser.on("--label NAME") { |v| opts[:label] = v }
+        parser.on("--json") { opts[:json] = true }
+        parser.on("--scope-merchant HOST") { |v| opts[:scope_merchants] << v }
+        parser.on("--scope-max-amount N", Integer) { |v| opts[:scope_max_amount] = v }
+        parser.on("--scope-currency CUR") { |v| opts[:scope_currency] = v }
+      end.parse!(argv)
+      opts[:url] = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      opts
+    end
+    private_class_method :parse_payment_enroll_options
+
+    # nil (not `{}`) when no --scope-* flag was given at all, so
+    # PaymentMethods#enroll's `scope:` default of no-scope-written stays the
+    # behavior for a plain `portage payment enroll` — Phase 2's per-token
+    # scope is opt-in.
+    def self.payment_enroll_scope(opts)
+      return nil if opts[:scope_merchants].empty? && !opts[:scope_max_amount]
+
+      { merchants: opts[:scope_merchants], max_amount: opts[:scope_max_amount], currency: opts[:scope_currency] }
+        .compact
+    end
+    private_class_method :payment_enroll_scope
+
+    def self.run_payment_enroll(argv)
+      opts = parse_payment_enroll_options(argv)
+      unless opts[:url]
+        warn USAGE
+        return 1
+      end
+
+      result = PaymentMethods.new.enroll(opts[:url], label: opts[:label],
+                                                     scope: payment_enroll_scope(opts)) do |setup_url|
+        puts "Visit this link to add a card, then wait — polling for completion:\n  #{setup_url}"
+      end
+      puts opts[:json] ? JSON.pretty_generate(result) : format_payment_enroll(result)
+      result[:status] == "complete" ? 0 : 1
+    rescue PaymentMethods::NotSupportedError => e
+      warn e.message
+      1
+    end
+    private_class_method :run_payment_enroll
+
+    # --- policy ---
+
+    def self.run_policy(argv)
+      sub = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      case sub
+      when "show" then run_policy_show(argv)
+      when "set" then run_policy_set(argv)
+      else
+        warn USAGE
+        1
+      end
+    end
+    private_class_method :run_policy
+
+    def self.run_policy_show(argv)
+      json = false
+      OptionParser.new { |parser| parser.on("--json") { json = true } }.parse!(argv)
+      policy = Portage::Ucp::Policy.load.to_h
+      puts json ? JSON.pretty_generate(policy) : format_policy(policy)
+      0
+    end
+    private_class_method :run_policy_show
+
+    def self.format_policy(policy)
+      return "(no policy configured — every check passes)" if policy.empty?
+
+      JSON.pretty_generate(policy)
+    end
+    private_class_method :format_policy
+
+    def self.parse_policy_set_options(argv)
+      opts = { allow: [] }
+      OptionParser.new do |parser|
+        parser.on("--per-transaction-cap N", Integer) { |v| opts[:per_transaction_cap] = v }
+        parser.on("--rolling-cap N", Integer) { |v| opts[:rolling_cap] = v }
+        parser.on("--rolling-window-seconds N", Integer) { |v| opts[:rolling_window_seconds] = v }
+        parser.on("--currency CUR") { |v| opts[:currency] = v }
+        parser.on("--velocity-count N", Integer) { |v| opts[:velocity_count] = v }
+        parser.on("--velocity-window-seconds N", Integer) { |v| opts[:velocity_window_seconds] = v }
+        parser.on("--allow HOST") { |v| opts[:allow] << v }
+        parser.on("--clear-allowlist") { opts[:clear_allowlist] = true }
+      end.parse!(argv)
+      opts
+    end
+    private_class_method :parse_policy_set_options
+
+    # Each `--*` group is applied independently and only when its required
+    # fields are present — `portage policy set --allow shop.example.com`
+    # touches only the allowlist, leaving caps/velocity untouched, so caps
+    # and the allowlist can be configured in separate invocations.
+    def self.run_policy_set(argv)
+      opts = parse_policy_set_options(argv)
+      policy = Portage::Ucp::Policy.load
+      set_policy_cap(policy, opts)
+      set_policy_velocity(policy, opts)
+      set_policy_allowlist(policy, opts)
+      puts format_policy(policy.to_h)
+      0
+    end
+    private_class_method :run_policy_set
+
+    def self.set_policy_cap(policy, opts)
+      if opts[:per_transaction_cap]
+        policy.set("per_transaction_cap",
+                   { "amount" => opts[:per_transaction_cap], "currency" => require_currency!(opts) })
+      end
+      return unless opts[:rolling_cap] && opts[:rolling_window_seconds]
+
+      policy.set("rolling_cap", { "amount" => opts[:rolling_cap], "currency" => require_currency!(opts),
+                                  "window_seconds" => opts[:rolling_window_seconds] })
+    end
+    private_class_method :set_policy_cap
+
+    def self.set_policy_velocity(policy, opts)
+      return unless opts[:velocity_count] && opts[:velocity_window_seconds]
+
+      policy.set("velocity", { "count" => opts[:velocity_count], "window_seconds" => opts[:velocity_window_seconds] })
+    end
+    private_class_method :set_policy_velocity
+
+    def self.set_policy_allowlist(policy, opts)
+      return policy.set("merchant_allowlist", []) if opts[:clear_allowlist]
+      return if opts[:allow].empty?
+
+      policy.set("merchant_allowlist", (policy.merchant_allowlist + opts[:allow]).uniq)
+    end
+    private_class_method :set_policy_allowlist
+
+    def self.require_currency!(opts)
+      opts[:currency] || raise(ArgumentError, "--currency is required alongside a cap")
+    end
+    private_class_method :require_currency!
+
+    def self.format_payment_list(methods)
+      return "(no payment methods enrolled)" if methods.empty?
+
+      methods.map { |m| "#{m['label']} (#{m['id']}) — default: #{m['default']}, frozen: #{m['frozen']}" }.join("\n")
+    end
+    private_class_method :format_payment_list
+
+    def self.format_payment_enroll(result)
+      case result[:status]
+      when "complete" then "Enrolled #{result[:label]} (#{result[:id]})."
+      when "pending"
+        "Timed out waiting for enrollment — finish it at #{result[:setup_url]}, then run " \
+        "`portage payment enroll` again."
+      else "This store doesn't support payment enrollment."
+      end
+    end
+    private_class_method :format_payment_enroll
+
     # --- output ---
 
     def self.format_report(report)

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-cli
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Tom Whitbread
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: portage-ucp
@@ -15,28 +16,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: portage-ucp-client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -103,6 +104,7 @@ description: 'Ships the `portage` executable. `portage buy <url>` tries native U
   ones answering /.well-known/ucp, and search their catalogs — documented APIs only,
   no SERP scraping. Depends on portage-ucp (for platform detection via Resolver) and
   portage-ucp-client (for the actual buy calls); no single adapter gem is a hard dependency.'
+email:
 executables:
 - portage
 extensions: []
@@ -118,6 +120,10 @@ files:
 - lib/portage/cli/compare.rb
 - lib/portage/cli/find.rb
 - lib/portage/cli/history.rb
+- lib/portage/cli/payment_methods.rb
+- lib/portage/cli/payment_methods/env_backend.rb
+- lib/portage/cli/payment_methods/keychain_backend.rb
+- lib/portage/cli/payment_methods/secret_service_backend.rb
 - lib/portage/cli/probe_cache.rb
 - lib/portage/cli/search_backends.rb
 - lib/portage/cli/shipping_profile.rb
@@ -129,6 +135,7 @@ metadata:
   source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-cli
   changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-cli/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -143,7 +150,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: portage — one CLI command to buy from any store, native UCP or not
 test_files: []