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

ADR 0001: Work-order media uses single-org scope (board-aligned)

Status

Accepted — 2026-08-04

Context

SH-116 requires that cross-tenant, unauthorized, and out-of-scope media access be rejected without metadata disclosure. The repository hard rule (ARCHITECTURE_AND_CODE_QUALITY.md §2) requires server-derived tenant scope: filtering by tenant/customer/owner comes from the authenticated principal and the data layer, never from client-supplied body/query as the source of truth.

The work-order domain does not model TenantId / CustomerId on WorkOrder or on JWT claims. The board, search, and detail paths already treat the deployment as a single organization: staff see any work order that passes ApplyBaseScope (non-deleted, non-template). Introducing a multi-tenant key would require product modeling plus a schema migration, which is out of scope for the SH-116 media contract.

Decision

Work-order media authorization matches the board:

1. Organization / “tenant” boundary = ApplyBaseScope in the data layer (istemplate != true and not deleted). Lookups outside that set resolve as missing → NotFound / null (no disclosure).
2. Authorization at service entry from claims: staff roles (Admin, Manager, Dispatcher, Supervisor) may read/mutate any in-org work order; role User (technician) only when WorkOrder.AssignTo == actorId; delete remains staff-only.
3. Scope is never taken from request body or query as the trust source; actorId and roles come from the authenticated principal.

This satisfies server-derived scope for the current single-org deployment. True multi-tenant isolation remains deferred until product models a tenant key and emits a matching claim.

Consequences

• Out-of-organization-scope tests cover deleted, template, and missing work order ids (GET and mutations) as the single-org analogue of SH-116 “cross-tenant” rejection.
• Staff org-wide access by numeric id remains intentional and aligned with the board; it is not a substitute for future multi-tenant keys.
• Reviewers of media PRs should cite this ADR when evaluating tenant-scope findings against SH-116.

Excepted / clarified rule

Hard rule: server-derived tenant scope (ARCHITECTURE_AND_CODE_QUALITY.md §2).

Clarification: in the work-order domain, the server-derived scope key is the organization boundary enforced by ApplyBaseScope plus claims-derived role/assignee — not a TenantId/CustomerId column. Absence of a multi-tenant key is an accepted product/architecture state until superseded.

Review / expiry

Re-review by 2027-02-04, or earlier if product introduces TenantId/CustomerId on work orders or JWT claims.

References

• SH-116 — Completion document: fields + media categorization
• PR that relies on this ADR: Sea-Haven-Industries/shoc-backend#47
• WorkOrderBoardQueryFilters.ApplyBaseScope
• WorkOrderMediaAuthorization