Skip to Content

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.
  • Your staff signs in once, at the admin. The OrbCommerce Admin sends a staff token with every call, and the Worker checks it against the key set of its STAFF_ISSUER and the person's areas on each request. How →

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.
Staff tokenA 15-minute JWTThe admin's memory, never keptWhat the person's areas allow in the Admin API, as the admin calls it.
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 lists. The copy in your Postgres behind lists and the admin has no names, addresses or emails. Staff with Connections but no Orders see Orders and Carts 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.

The admin and your staff

OrbCart's screens are the Orders area of the OrbCommerce Admin, with its channels under Settings, and have no sign-in of their own. Your staff signs in once at the admin (http://localhost:8789 on your machine), which forwards each call to the Worker through its service binding, and the Worker trusts the 15-minute EdDSA tokens the admin issues for the audience orbcommerce-staff, checked against ${STAFF_ISSUER}/api/auth/jwks. A token names the person by their name, never their email, and carries a level for each area they work in. The owner invites people with their areas and changes them; removing someone ends their sessions.

AreaViewEdit
OrdersOrders and Carts with the buyer, search by emailRefunds
ConnectionsEvents and receivers; Orders and Carts without buyerResend and replay events, pause receivers

Anyone on the staff reads the environment's setup. A call the person's areas do not allow answers 403 not_permitted, its area and level naming what to ask the owner for. The secret key keeps opening everything, as before.

Rate limits

The withdrawal function is open to anyone with the publishable key, so OrbCart limits it: 5 declarations per email and 20 per client network (an IPv4 address or an IPv6 /64) in any minute. A Durable Object of its own, ATTEMPT_BUDGET, keeps each count exactly, also across the turn of a minute; the Workers rate limit bindings WITHDRAWALS_PER_EMAIL and WITHDRAWALS_PER_ADDRESS in wrangler.jsonc turn floods away in front of it. Each counter is named by an HMAC from the root secret, so neither ever sees an email or an address. Past a limit, POST /v1/withdrawals answers 429 rate_limited with Retry-After; a declaration that arrived before stays received. The client address is CF-Connecting-IP: when your server calls the Worker through a service binding, forward the visitor's, or all your visitors share one counter.

A gift card code is a bearer secret, so one client network may try 10 codes in any minute, at checkout and at the desk alike, counted the same way: by ATTEMPT_BUDGET, behind the binding GIFT_CARD_LOOKUPS_PER_ADDRESS. Past the budget, a lookup answers 429 rate_limited and a cart gift_card_rate_limited.

Every discount code entry counts towards two limits: 10 attempts per Cart in any 10 minutes and 30 per client network in any minute. ATTEMPT_BUDGET enforces both behind CODE_ENTRIES_PER_ADDRESS. The network budget is checked before opening the Cart. Only a verified Cart credential can spend the Cart's budget. When either budget is spent, the API returns 429 code_rate_limited without changing the Cart. This check also applies to replays with an Idempotency-Key; a rate-limited request does not reserve the key.

The same declaration again within ten minutes, from a double click or a reload, is the one received before: it records and mails once, whatever Idempotency-Key the client sends.

Not built yet

  • No other rate limits. Apart from withdrawals, gift card lookups and discount code entries, 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.
  • STAFF_ISSUER names your staff sign-in, and only the people who need it have Orders or Connections.
  • The cart creation rate rule and checkout challenge are in place.

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

On this page