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
livekey on atestWorker 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 intest. 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,
createAdminthrows where adocumentexists, andcreateCommercerefuses 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 atestevent fails verification againstlive. 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
httpson 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.
testandlivehave 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_ISSUERand the person's areas on each request. How →
Keys and tokens
| Credential | Looks like | Keep it in | Opens |
|---|---|---|---|
| Publishable key | pk_test_… | The browser, an app or an agent | Creating Carts in its Channel. |
| Cart token | cart_…_secret_… | The buyer's session cookie | One Cart: read, change, quote and pay. |
| Order token | ord_…_secret_… | The Order link you send the buyer | One Order, to read. |
| Buyer ID token | Your identity's JWT | The OrbCart-Buyer header | That buyer's own Carts and Orders, beside a key or token. |
| Secret key | sk_test_… | A secret of your server | Everything in the Environment, through the Admin API. |
| Staff token | A 15-minute JWT | The admin's memory, never kept | What the person's areas allow in the Admin API, as the admin calls it. |
| Root secret | 32 random bytes | A Wrangler secret of the Worker | Nothing 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.
| Area | View | Edit |
|---|---|---|
| Orders | Orders and Carts with the buyer, search by email | Refunds |
| Connections | Events and receivers; Orders and Carts without buyer | Resend 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.
testkeys only from the CLI.orbcart keys issuerefuseslive. A guidedlivesetup comes withorbcart deploy.
Before you go live
-
liveruns in its own Worker with its own root secret and live provider keys. Test keys stay intest. - The root secret, provider keys and webhook secrets are set with
wrangler secret put, never in code orwrangler.jsonc. - Each Channel's
originslists only your real storefront origins. - The secret key lives only on your server. The browser gets
ORBCART_URLand 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()orverifyRequest(). - Provider webhooks point at the live Worker, with matching secrets.
-
STAFF_ISSUERnames 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.