Backoffice

Operators sign in with Okta; the backoffice server calls the API as itself.

The backoffice reads shop data only through the /v1/ops/* procedures. Its adapter calls the typed client (client.ops.orders.search(input, { context: { token, headers: { operator, traceparent } } })); problemOf maps a failure to ShopDataError(error, status, detail), a timeout to shop_unavailable (503) and a credential failure to shop_credentials (503). The Okta persona checks (docs/okta-personas.md) need a real Okta org.

The backoffice keeps Okta sign-in, role checks, operator sessions and operator_audit_events in its own DB. ShopData has only an API adapter. Overview composes four concurrent reads; customer detail composes three. The token supplier coalesces issuance and caches tokens in memory and the Workers Cache API. API problems preserve their original codes in audit rows and page states.

The wire format is bounded to 2 KB:

Operator: v1.<unpadded base64url of UTF-8 JSON>
{ sub, email, name: string | null, roles: ["viewer", "auditor"], sid: "ops_…" }

roles may contain zero to two allowed roles; domain reads require viewer. The schema rejects extra keys, unknown versions, malformed encoding and invalid session identifiers. Only the dedicated backoffice client may send Operator; its token cannot carry guest or website session context headers. Storefront and MCP callers are refused on every ops route, even if their token claims ops:read.

The backoffice client secret is the authority; the header supplies attribution only. Possession of that secret permits all operator reads and can claim any staff identity. This does not provide per-person API authorization. The backoffice audit row remains the system of record. API logs add api_operator_call with operation, staff subject, email, session, status, request ID and valid trace context. They never include order or customer responses. Trace/request identifiers remain distinct from the non-secret owned action ID. Public claims alone cannot establish a trusted service hop; actual private sender facts and the API response request ID are paired at read time.

Customer identities come from the API’s read-only ops_management Management client, whose grant is exactly read:users. The backoffice itself has no shop database or Management binding; it binds only its own audit and session database.

Diagnostic investigation

Auditors read normalized ShopDatabase diagnostics through the API, without a direct ShopDatabase binding. The separate named BackofficeAudit private entrypoint accepts only backoffice-owned observations. Source/producer/simulation and actual executing service/runtime remain distinct from the collecting API. No historical ledger backfill is performed. The local ledger stays the source of truth and awaited access gate; its new successful entries project best effort.

Event, actor-chain, timeline and health reads require the live auditor session and local gate. Raw header/token release also requires an admitted API release event; neither gate can be bypassed if storage is unavailable. The six-tab right-hand sheet retains investigation context and offers Events/Flow. Its credential cache is ephemeral and raw responses are private/no-store. Reader auditing cannot prevent replay of intentionally retained non-cookie capabilities.

All three histories have30-day expiry: diagnostics, customer activity and local operator access. The backoffice’s hourly handler cleans its own ledger; API cleanup remains separate. See diagnostic investigations for bounded capture, cursor/Flow evidence, credential authority, stream setup and restore policy.