shoc-backend/docs/adr/0001-work-order-single-org-scope.md

ADR 0001: Work-order domain uses server-derived account scope

Status

Superseded (historical Proposed single-org ADR). Current contract (PR #47 / SH-221):

• WorkOrder.AccountId / ApplicationUser.AccountId schema keys (nullable; legacy null fail-closed)
• JWT account_id when ApplicationUser.AccountId is set
• JWT org_scope=all when Admin has no AccountId (explicit signed elevation)
• Reads (board, list, advanced search, detail, media, board comments, legacy comments-by-work-order-id, legacy GET GetComments): ApplyBaseScope + ApplyAccountScope(int) when account-scoped; org-wide path skips account filter
• Writes (board mutations, media, board/legacy comments, POST …/completion-doc): same account filter at service/data entry; authorize before storing blobs
• Creates (board): stamp AccountId from JWT account_id or Location.AccountId via required locationId; body customer/accountId are not trusted. AddWorkorder, ingest, webhook/recon, sync still stamp from claim or unique Accounts.Name ↔ Customer; unresolvable → reject/skip
• Missing/malformed scope → Forbidden (absence of claim does not elevate)

Context (historical)

SH-116 requires that cross-tenant, unauthorized, and out-of-scope media access be rejected without metadata disclosure. An interim Proposed ADR allowed org-wide staff access via absence of an account claim; that path was rejected in review (fail-open) and replaced by the contract below.

Current domain contract (superseding)

1. Organization boundary = ApplyBaseScope (non-deleted, non-template).
2. Account boundary = claim account_id → WorkOrder.AccountId == claim.
3. Org-wide = claim org_scope=all only (issued to Admin without AccountId). Not inferred from missing account_id.
4. Fail-closed = no valid account or org-scope claim → Forbidden.
5. Create stamp:
   • Board POST /workorders/board: required locationId. Scoped → stamp JWT account_id only when Location.AccountId matches (else Forbidden). Org-wide → stamp Location.AccountId. Missing location → NotFound; null Location.AccountId → AccountUnresolved. Body customer/accountId are ignored for the stamp.
   • Legacy AddWorkorder: authenticated + account_id → stamp claim; authenticated + org_scope=all → unique Customer→Accounts.Name; else AccountUnresolved.
   • Ingest / webhook / sync → same Customer resolution; unresolved create is rejected or skipped (no null AccountId on new rows).
6. Legacy rows with AccountId == null are invisible to account-scoped callers; only org_scope=all may read them.
7. Authorization at service entry: staff roles may read/mutate any resulting work order; role User only when AssignTo == actorId (media); delete staff-only. Board comments, legacy comments-by-WO-id, and completion-doc uploads apply the same account filter before read/write (and before blob storage).
8. User lifecycle persists AccountId on Admin create/edit so non-Admin principals can receive account_id.

Consequences

• Cross-account and missing-scope tests are required for create and read paths.
• Dispatcher/Manager/Supervisor/User without AccountId cannot access board, detail, search, list, or media until AccountId is assigned (or they are Admin with org_scope=all).
• Board create resolves from Location.AccountId. Customer name match remains the ingest/webhook/legacy resolution path.

Excepted rule

None. Hard rule server-derived tenant scope (ARCHITECTURE_AND_CODE_QUALITY.md §2) is enforced via claims + AccountId.

Review / expiry

Re-review by 2027-02-04, or when AccountId becomes non-nullable with a full backfill migration.

References

• SH-116 — Completion document: fields + media categorization
• SH-221 — Server-derived tenant/customer scope for Work Order domain
• PR: Sea-Haven-Industries/shoc-backend#47
• WorkOrderBoardQueryFilters.ApplyBaseScope / ApplyAccountScope
• IWorkOrderAccountResolver / WorkOrderMediaAuthorization / SeaHavenClaimTypes
• ARCHITECTURE_AND_CODE_QUALITY.md §2, §10