3.2 KiB
ADR-001: Verified tenant ownership for payment orders
Status: Proposed Date: 2026-09-15 Deciders: SIAX 0pt product and platform owners
Context
The existing order configurator creates anonymous drafts, stores no verified
buyer or tenant on them, and later refers to an order by its ID. A valid
Zitadel principal proves who is calling but does not prove that this caller
owns that particular order. An order ID is an identifier, not an authorization
secret. The nullable orders.org_id UUID cannot directly hold the verified
tenant ID, which is a string. The repository has no automated SQL migration
runner, and legacy rows may remain unowned.
The payment flow must remain API-first and work consistently in UI, CLI and MCP. It must not make anonymous drafts payable by treating a guessed or leaked ID as ownership.
Decision
Require a verified Zitadel principal before creating a payable order. Persist
tenant_id and buyer subject on each new order in a database migration.
Every read, status mutation and Checkout creation must use a tenant-scoped
query predicate; a cross-tenant order returns 404. The Stripe webhook uses
its verified signature plus recorded order ID and payment facts to advance
status, never a browser-supplied tenant claim. Legacy null-owned orders remain
unpayable until an audited, explicit migration or support workflow binds
them to a verified buyer. Keep the anonymous configurator as an estimate
without creating a payable order until sign-in.
Options considered
| Option | Complexity | Scale | Consequence |
|---|---|---|---|
| Authenticate only, lookup by order ID | Low | High | Rejected: any signed-in user can access another order. |
| Bearer claim token for anonymous drafts | Medium | High | Requires capability issuance, hashing, secure browser storage and recovery. Not selected for initial production. |
| Verified tenant + buyer subject at order creation | Medium | High | Chosen: explicit ownership at source, shared API boundary. |
Consequences
- UI must obtain a Zitadel session before order creation and send credentials to the order and payment APIs; estimates stay anonymous.
- SQL migration must be applied and verified before the scoped code is deployed.
- Existing unowned rows are not silently assigned to a tenant.
- Idempotency keys must be scoped to the verified tenant.
- Admin operations require an explicit, audited role-bound path rather than bypassing the buyer predicate.
Action items
- Build and smoke-verify
sql/011_orders_tenant_ownership.sqlon throwaway pgvector/Postgres 16, including a second idempotent application. A deploy migration runner and production application remain open. - Bind create-order to verified tenant and buyer subject; scope idempotency.
- Scope buyer GET/PATCH/deposit/release to tenant at the SQL boundary.
- Wire UI Zitadel login/session and CLI/MCP bearer auth; keep anonymous estimates.
- Test cross-tenant 404, legacy unowned rejection, webhook, and staging purchase/refund end-to-end before enabling live Stripe.
Implementation is pending PR review and merge. It is not evidence that the production database has been migrated or that the browser purchase path is ready: the current UI does not send a verified Zitadel credential.