ucp-client

UCP Client

Use the resource URL as the primary identifier. Keep RDF as the authoritative offer description, UCP as the commerce/checkout protocol, MPP as the HTTP 402 payment protocol, and Stripe as a payment processor. Do not collapse these layers.

Two entry points

Everything below (steps 1-9) is the --resource-url-driven path: start from a protected resource, work backward through identity/402/RDF discovery to find its offer. When the merchant instead publishes a product feed (RSS 2.0 + Google Merchant g: namespace, e.g. https://<shop>/shop/feed?rss), skip all of that: --product-feed URL fetches the feed directly — it is already a complete, typically-public, pre-authenticated list of every purchasable offer with its own IRI (link/guid), price, and currency. With no --feed-item-id/--feed-search selector the client lists every item and stops so a human or calling agent can pick one; with a selector matching exactly one item, it goes straight to UCP discovery and checkout (steps 6-9 below), skipping the identity-probe/401/402/RDF/SPARQL steps (1-5) entirely — there is no resource ACL to probe and no offer to discover, the feed already answered both.

# List every offer in the shop's feed
python scripts/ucp_resource_client.py --product-feed "https://ods-qa.openlinksw.com/shop/feed?rss"

# Pick one by title search, preview the checkout without creating it
python scripts/ucp_resource_client.py \
  --product-feed "https://ods-qa.openlinksw.com/shop/feed?rss" \
  --feed-search "Hotpot" --bearer-token-env UCP_BEARER --dry-run

# Same, but actually create + complete the checkout via a Stripe test SPT
python scripts/ucp_resource_client.py \
  --product-feed "https://ods-qa.openlinksw.com/shop/feed?rss" \
  --feed-item-id "ODSQA-FA-PROPERLANCASHIREHOTPOTRECIPE-0001" \
  --bearer-token-env UCP_BEARER --complete-with-stripe-spt

Core workflow (--resource-url path)

1. Accept a protected resource_url and establish the request identity without putting secrets on the command line. scripts/ucp_resource_client.py accepts a WebID-TLS/NetID client certificate directly, either as PKCS#12 (--client-p12 PATH --client-p12-password-env ENV_VAR — the bundle is decrypted with cryptography and staged as temporary 0600 PEM files, cleaned up on exit; confirmed live against ODS-QA) or PEM (--client-cert/--client-key); for the selected ODS-QA direct-execution profile with curl itself rather than this script, the mtls-curl skill is the alternative. The client also accepts an OAuth access token (Bearer or DPoP), Digest credentials, environment-backed headers, or an already-established ambient identity session. Discover OAuth metadata from the resource origin's OAuth 2.0 Authorization Server Metadata endpoint when using OAuth; the server OAuth backend is assumed to already exist and is not implemented by this skill.
2. Probe the resource before commerce. Interpret the server response as an identity-first state machine: 401 means authentication is missing or failed and may advertise one or more authentication schemes; 200 means the authenticated identity passes the resource ACL; 402 means the authenticated identity failed the ACL and payment can grant access; 403 is a terminal policy denial without a payable challenge. A 401 may therefore trigger Digest, WebID-TLS/mTLS, or OAuth token acquisition; it is never itself a payment challenge.
3. Accept 402 only when identity was established and the response includes at least one WWW-Authenticate: Payment challenge. Parse repeated WWW-Authenticate and Link fields, preserving Payment challenge parameters, Payment-Receipt, Location, content type, and links such as rel=offer, describedby, alternate, or payment. A naked 402, or 402 before identity, is a protocol error.
4. Query the merchant RDF knowledge graph for a schema:Offer associated with the resource IRI. Accept both Schema.org namespace forms (http://schema.org/ and https://schema.org/). Match direct schema:itemOffered, schema:url, schema:contentUrl, or schema:identifier links and item-mediated links such as Offer → License/Product → resource. Use --resource-predicate IRI for additional explicit merchant relations. Use --sparql-endpoint when known; otherwise try <merchant-origin>/sparql; then use response-linked or explicit RDF metadata. Quad stores commonly keep offer data in a named graph outside the SPARQL protocol default graph: an unscoped query that returns no rows is automatically retried once, scanned across all named graphs (GRAPH ?g { ... }), before falling back to RDF dereference; pass --sparql-default-graph IRI (repeatable) to scope explicitly instead of relying on the automatic scan. If the resource's public/RDF-published IRI differs from the URL actually used to access it (see the ODS-QA case below), pass --match-url with the RDF-published IRI so offer matching succeeds independently of the access URL. If discovery still finds no offer at all (some MPP/x402-gated resources publish no RDF description whatsoever), fall back to decoding the offer identity directly out of the resource's own WWW-Authenticate: Payment request=<base64url JSON> challenge parameter, when present, rather than failing outright.
5. Extract offer identity, item identity, price, currency, availability, seller, and UCP item identifier. Read price/currency either directly or through schema:priceSpecification. Prefer schema:sku, then schema:productID, then literal schema:identifier; known explicit merchant identifiers such as oplofr:offerNumber may follow. For another merchant vocabulary use repeatable --item-id-predicate IRI, or supply a verified --item-id VALUE. Never infer an ID from a URL path. schema:potentialAction query parameters remain opt-in via --allow-action-item-id.
6. Discover the merchant UCP profile at /.well-known/ucp and read the advertised dev.ucp.shopping REST checkout capability/version.
7. Create a UCP checkout session using the mapped item ID and quantity. Treat the checkout response as authoritative for final price, totals, eligibility, and status. Before spending money, surface the checkout amount/currency and payment boundary unless the user explicitly authorized the purchase and any required spending limit is satisfied.
8. Pay for the checkout through whichever surface the merchant actually settles it on — these are two distinct targets, not interchangeable:
   • UCP checkout completion: when the merchant advertises a payment handler compatible with a Shared Payment Token (e.g. opl_shop_stripe_spt, following the Link Agent Wallet shape from Stripe's UCP payments handler), pass --complete-with-stripe-spt to fetch a Stripe test-mode SPT capped at the checkout's authoritative total and POST .../complete directly — this finishes the UCP checkout itself and returns the resulting order.
   • Resource-level MPP payment: fulfill one server-advertised Payment challenge on the protected resource using an MPP implementation such as mppx (--mpp-command). Preserve identity independently through WebID-TLS/mTLS, an authenticated session cookie, or a server-side challenge binding; Basic/Digest/Bearer/DPoP and Payment cannot both occupy the single Authorization field. After entitlement binding, retry the resource with the original identity context and capture Payment-Receipt plus the final status.
9. Reconcile an MPP receipt with the UCP checkout only through a merchant-supported binding — the two are not automatically the same transaction. Return the resource plus provenance: identity-gate state, resource URL, offer IRI, checkout ID/status, amount/currency, payment method/intent, receipt or order, and final HTTP status.