adam/shoc-backend
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/shoc-backend.git synced 2026-09-30 06:03:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
shoc-backend/docs/adr/0001-work-order-single-org-scope.md
Arthur Bassi 1edcf479ae fix(work-orders): apply account scope across create and reads [SH-221] 
Stamp WorkOrder.AccountId on all create paths and filter board/list/search/detail by server-derived account claims so scoped callers cannot cross accounts.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-11 10:45:37 -03:00

3.3 KiB
Raw Blame History

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): ApplyBaseScope + ApplyAccountScope(int) when account-scoped; org-wide path skips account filter
  • Creates (board, AddWorkorder, ingest, webhook/recon, sync): stamp AccountId from claim or unique Accounts.Name ↔ Customer match; 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:
    • Authenticated + account_id → stamp claim (ignore client AccountId).
    • 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.
  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).
  • Locations do not carry AccountId in the EF model; Customer name match is the unauthenticated 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