Files
0pt/docs/architecture/ADR-001-order-ownership.md
T
admin a1557b2a7d
CI (SIAX Cloud) / integration (push) Has been skipped
masterplan-lock / check (push) Successful in 4s
CI (SIAX Cloud) / security (push) Successful in 14s
masterplan-lock / check (pull_request) Successful in 4s
CI (SIAX Cloud) / security (pull_request) Successful in 14s
Security Scan (SIAX Cloud) / security (push) Successful in 30s
CI (SIAX Cloud) / quality (push) Successful in 35s
CI (SIAX Cloud) / integration (pull_request) Successful in 25s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 54s
CI (SIAX Cloud) / quality (pull_request) Successful in 1m31s
feat(payments): bind orders to verified tenant and buyer
2026-09-15 19:53:58 +02:00

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

  1. Build and smoke-verify sql/011_orders_tenant_ownership.sql on throwaway pgvector/Postgres 16, including a second idempotent application. A deploy migration runner and production application remain open.
  2. Bind create-order to verified tenant and buyer subject; scope idempotency.
  3. Scope buyer GET/PATCH/deposit/release to tenant at the SQL boundary.
  4. Wire UI Zitadel login/session and CLI/MCP bearer auth; keep anonymous estimates.
  5. 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.