ORBCART DOCUMENTATION

Security

The trust model of OrbCart, what each key and token opens, what is not built yet, and what to check before you go live.

In OrbCart, access follows from what a caller presents, never from what it claims. A key decides the Environment and the Channel, a token opens exactly one Cart or one Order, and everything binding is decided on the server.

The trust model

  • Browsers and agents send intent, not facts. A request names references, quantities, addresses and choices. Prices, tax, shipping costs, discounts, totals, currency and Channel come from your systems and the server. The API has no field for them, and a request that sends one is refused.
  • The key decides the context. A publishable key belongs to one Channel of one Environment. A client cannot pick another Channel, and a live key on a test Worker is refused.
  • A token opens one thing. A Cart token opens one Cart, an Order token reads one Order. Keys and tokens are 256 random bits; OrbCart stores only their SHA-256 and compares it in constant time.
  • Credentials travel in a header. The API reads them only from Authorization, never from its URLs. Two links carry a secret on purpose: the Order link you send the buyer, which only reads its Order, and the hand-off code in an agent's continue link, which opens one Cart while its Quote lasts.
  • Only your sites call from a browser. Browsers may call only from a Channel's origins, plus localhost in test. This keeps other sites from embedding your checkout. Scripts outside a browser are not stopped, and need not be: the publishable key opens nothing binding.
  • The secret key never works in a browser. The Worker refuses a secret key sent from a web page, createAdmin throws where a document exists, and createCommerce refuses a secret key.
  • Card data never reaches you or OrbCart. Payment fields come from the provider and send card details straight to it. OrbCart sees only the provider's references, which keeps the most demanding PCI scope with the provider.
  • Provider webhooks are verified before they count. Stripe, Adyen and PAYONE messages need a valid signature, and PayPal's are confirmed through PayPal's API. Mollie's are unsigned, so OrbCart only reads the named payment back with your key. Every message is stored before the 200, so a redelivery repeats nothing.
  • What OrbCart sends is signed. Quotes, events and calls to your HTTP contracts carry an ES256 signature of the Environment, whose public keys are at /.well-known/jwks.json. Each Environment has its own key, so a test event fails verification against live. A Service Binding is not signed: only your own account can reach it.
  • Outgoing calls go only to public addresses. An HTTP contract or event receiver must be https on port 443, with a host name rather than an IP address and no private name.
  • Agents prove who they are. Every UCP checkout request needs an HTTP message signature, which OrbCart checks against the keys the agent platform publishes. Identity is a signal, not a permission: an agent follows the same rules as a browser.
  • Retries never charge twice. Every change carries an Idempotency-Key, and a repeat replays the first answer. Calls to the provider carry a key derived from the Payment's ID. An unclear answer is resolved, never guessed. How →
  • Each Environment is its own Worker. test and live have separate keys, provider accounts and data. Code of one Environment has no binding to the data of another.
  • The Explorer sits behind Cloudflare Access. The Worker verifies each Access sign-in and the member's role. Without Access, the Explorer opens only on localhost.

Keys and tokens

CredentialLooks likeKeep it inOpens
Publishable keypk_test_…The browser, an app or an agentCreating Carts in its Channel.
Cart tokencart_…_secret_…The buyer's session cookieOne Cart: read, change, quote and pay.
Order tokenord_…_secret_…The Order link you send the buyerOne Order, to read.
Buyer ID tokenYour identity's JWTThe OrbCart-Buyer headerThat buyer's own Carts and Orders, beside a key or token.
Secret keysk_test_…A secret of your serverEverything in the Environment, through the Admin API.
Root secret32 random bytesA Wrangler secret of the WorkerNothing over the API. It seals the signing keys, names the buyer indexes and signs agent hand-off codes, so never change it.

The demo keeps the Cart token in an HttpOnly, SameSite=Lax cookie and hands it to the page that needs it. Never put it in a URL, an analytics event or a log.

Personal data

  • Not in logs, IDs or events. The Worker logs one line per request: route, status, code and duration, never bodies, headers or addresses. Events name the Order, and your receiver loads the details with the secret key.
  • Not in the Order list. The D1 copy behind lists and the Explorer has no names, addresses or emails. Members with the developer role see Orders without contact details.
  • Kept in the EU. Durable Objects run in the EU jurisdiction unless you choose another.
  • Deleted when unused. A Cart without an Order is deleted with every personal detail after half a year without a change, the Channel's default expiresAfterDays.
  • ID tokens are checked, not kept. OrbCart keeps only a signed-in buyer's issuer and subject.

Not built yet

  • No rate limits. OrbCart does not limit requests per key or sender yet. Until it does, put a rate limiting rule of your Cloudflare zone in front of the Worker's route.
  • No revoking or rotating keys. Nothing revokes an API key or rotates the signing key yet, so a leaked secret key cannot be switched off. Keep it on one server.
  • test keys only from the CLI. orbcart keys issue refuses live. A guided live setup comes with orbcart deploy.

Before you go live

  • live runs in its own Worker with its own root secret and live provider keys. Test keys stay in test.
  • The root secret, provider keys and webhook secrets are set with wrangler secret put, never in code or wrangler.jsonc.
  • Each Channel's origins lists only your real storefront origins.
  • The secret key lives only on your server. The browser gets ORBCART_URL and the publishable key.
  • The Cart token sits in a session cookie, never in a URL, analytics or logs.
  • Your event receivers and HTTP contracts check every call with verifyEvent() or verifyRequest().
  • Provider webhooks point at the live Worker, with matching secrets.
  • The Explorer is behind Cloudflare Access, for the people who need it.
  • A rate limiting rule protects the Worker's route.

The rest of the go-live list, from tax to legal texts, is in Deployment.

On this page