# 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](/docs/shop/order-page) you send the buyer, which only reads its Order, and the hand-off code in an [agent's continue link](/docs/shop/agents#build-the-continue-page), 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](/docs/integrate/order-events#verify-a-delivery) and calls to your [HTTP contracts](/docs/integrate/remote-contracts#verify-an-http-call) 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 →](/docs/cart/how-it-works#when-something-goes-wrong)
- **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 →](#the-admin-and-your-staff)

## 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.
- **`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`](/docs/run/deployment#set-the-root-secret), 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](/docs/run/deployment#protect-cart-creation-and-checkout) are in place.

The rest of the go-live list, from tax to legal texts, is in
[Deployment](/docs/run/deployment#checklist-before-real-money).