TenantAtlas/specs/093-scope-001-workspace-id-isolation/spec.md

#+#+#+#+markdown

Feature Specification: SCOPE-001 Workspace ID Isolation

Feature Branch: 093-scope-001-workspace-id-isolation
Created: 2026-02-14
Status: Draft
Input: Enforce workspace isolation by binding all tenant-owned records to a workspace, with a safe staged rollout and corrected audit invariants.

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes: No new pages/routes. Affects all create/write paths that persist tenant-owned records in the tables listed below, plus operational tooling for a one-time backfill.
• Data Ownership:
  • Tenant-owned tables impacted (must become explicitly workspace-bound):
    • policies
    • policy_versions
    • backup_sets
    • backup_items
    • restore_runs
    • backup_schedules
    • inventory_items
    • inventory_links
    • entra_groups
    • findings
    • entra_role_definitions
    • tenant_permissions
  • Audit trail invariants impacted: audit_logs
• RBAC: No user-facing permissions change. Backfill execution is an operator-only workflow (platform/ops).

Clarifications

Session 2026-02-14

• Q: For the 12 tenant-owned tables, how strict should deterministic workspace binding be when a caller explicitly provides a workspace binding? → A: Reject any mismatch; if a record references a tenant, its workspace binding MUST equal the tenant’s workspace.
• Q: During backfill, what should happen if a row’s tenant reference is invalid (tenant missing / cannot map tenant → workspace)? → A: Abort the backfill run and report the offending table plus sample identifiers for remediation.
• Q: Should tenant_id be allowed to change on existing rows in the 12 tenant-owned tables? → A: No; tenant_id is immutable and updates are rejected.
• Q: How should the backfill workflow be recorded for observability/audit? → A: Create/reuse an OperationRun for the backfill and also write an AuditLog summary for start/end/outcome.
• Q: Should this feature include updating existing canonical/operational queries/views to scope by workspace binding? → A: No; query/view changes are out of scope for 093 (follow-up later).

User Scenarios & Testing (mandatory)

User Story 1 - Enforce workspace ownership at the data layer (Priority: P1)

As a platform owner, I want every tenant-owned record to be explicitly bound to a workspace so that workspace isolation does not depend on application-only guardrails.

Why this priority: This closes a class of potential cross-workspace data leakage and makes operational reporting safer and simpler.

Independent Test: Can be tested by creating a tenant-owned record with a tenant reference and asserting that workspace_id is derived from the tenant and that any explicit mismatched workspace_id is rejected; backfill behavior is validated in User Story 2.

Acceptance Scenarios:

1. Given tenant-owned records exist without a workspace binding, When the staged rollout completes, Then all tenant-owned records are workspace-bound.
2. Given the rollout is in progress, When the system is used normally, Then there is no required downtime for administrators.

---

User Story 2 - Safely backfill existing production data (Priority: P2)

As an operator, I want a safe, resumable way to backfill missing workspace bindings so that large datasets can be migrated without risky one-shot operations.

Why this priority: Without a safe backfill, enforcing data-level constraints risks outages and operational incidents.

Independent Test: Can be tested by seeding rows with missing workspace bindings, running the backfill workflow twice, and confirming idempotent outcomes.

Acceptance Scenarios:

1. Given a table contains rows missing workspace bindings, When the backfill is executed, Then those rows are updated to the correct workspace.
2. Given the backfill is interrupted and restarted, When it runs again, Then it resumes safely without corrupting already-correct rows.

---

User Story 3 - Make audit logs unambiguous across scopes (Priority: P3)

As an auditor, I want tenant-scoped audit events to always be workspace-bound so that workspace isolation semantics are preserved in audit trails.

Why this priority: Audit trails are only reliable if their scope is structurally consistent and queryable.

Independent Test: Can be tested by attempting to store a tenant-scoped audit entry without a workspace binding and verifying it is rejected, while allowing workspace-only and platform-only entries.

Acceptance Scenarios:

1. Given an audit log entry references a tenant, When it is persisted, Then it must also reference a workspace.
2. Given an audit log entry is workspace-only or platform-only, When it is persisted, Then it remains valid according to the documented rules.

---

Edge Cases

• Tenant-owned row references a tenant that no longer exists (or is otherwise invalid).
• Backfill is executed concurrently (must not produce conflicting outcomes).
• New rows are created while the backfill is in progress (must not reintroduce missing bindings).
• Partial completion: some tables are fully backfilled while others are pending.
• Mixed-scope audit events: tenant-scoped vs workspace-only vs platform-only.
• Attempt to change tenant_id on an existing tenant-owned record.

Requirements (mandatory)

Constitution alignment (required): If this feature introduces any Microsoft Graph calls, any write/change behavior, or any long-running/queued/scheduled work, the spec MUST describe contract registry updates, safety gates (preview/confirmation/audit), tenant isolation, run observability (OperationRun type/identity/visibility), and tests. If security-relevant DB-only actions intentionally skip OperationRun, the spec MUST describe AuditLog entries.

Constitution alignment (RBAC-UX): If this feature introduces or changes authorization behavior, the spec MUST:

• state which authorization plane(s) are involved (tenant/admin /admin + tenant-context /admin/t/{tenant}/... vs platform /system),
• ensure any cross-plane access is deny-as-not-found (404),
• explicitly define 404 vs 403 semantics:
  • non-member / not entitled to workspace scope OR tenant scope → 404 (deny-as-not-found)
  • member but missing capability → 403
• describe how authorization is enforced server-side (Gates/Policies) for every mutation/operation-start/credential change,
• reference the canonical capability registry (no raw capability strings; no role-string checks in feature code),
• ensure global search is tenant-scoped and non-member-safe (no hints; inaccessible results treated as 404 semantics),
• ensure destructive-like actions require confirmation (->requiresConfirmation()),
• include at least one positive and one negative authorization test, and note any RBAC regression tests added/updated.

Constitution alignment (OPS-EX-AUTH-001): OIDC/SAML login handshakes may perform synchronous outbound HTTP (e.g., token exchange) on /auth/* endpoints without an OperationRun. This MUST NOT be used for Monitoring/Operations pages.

Constitution alignment (BADGE-001): If this feature changes status-like badges (status/outcome/severity/risk/availability/boolean), the spec MUST describe how badge semantics stay centralized (no ad-hoc mappings) and which tests cover any new/changed values.

Constitution alignment (Filament Action Surfaces): If this feature adds or modifies any Filament Resource / RelationManager / Page, the spec MUST include a “UI Action Matrix” (see below) and explicitly state whether the Action Surface Contract is satisfied. If the contract is not satisfied, the spec MUST include an explicit exemption with rationale.

Functional Requirements

• FR-001 (Schema coverage): The system MUST represent a workspace binding for every tenant-owned record in the 12 listed tables.
• FR-002 (No missing bindings post-rollout): After completion of the rollout, the system MUST prevent creation or persistence of tenant-owned records without a workspace binding.
• FR-003 (Deterministic binding for new writes): For any new or updated tenant-owned record, the system MUST derive the workspace binding from the referenced tenant (not from user/session context alone).
• FR-003a (Mismatch handling): If a caller provides a workspace binding that does not match the referenced tenant’s workspace, the write MUST be rejected.
• FR-004 (Safe staged rollout): The system MUST support a staged rollout that allows introducing the new field, deploying write-path enforcement, backfilling existing data, and only then enforcing strict constraints.
• FR-005 (Idempotent backfill): Operators MUST be able to re-run the backfill safely; repeated runs MUST not regress already-correct data.
• FR-006 (Operational safety): The backfill workflow MUST be safe for large datasets (batching/resume) and MUST prevent concurrent executions.
• FR-006a (Invalid mapping handling): If the backfill workflow encounters a tenant-owned row that cannot be mapped from tenant → workspace, it MUST abort and report the offending table and sample identifiers for operator remediation.
• FR-007 (Validation): Operators MUST be able to validate that no tenant-owned records remain without a workspace binding before strict constraints are enforced.
• FR-011 (Tenant immutability): For tenant-owned records, tenant identity MUST be immutable after creation; attempts to change tenant_id MUST be rejected.
• FR-012 (Backfill observability and audit): The backfill workflow MUST be observable via an OperationRun (progress + outcome) and MUST write an audit log summary entry for start/end/outcome.
• FR-013 (Query/view scope): This feature MUST NOT require broad refactors of canonical/operational queries; it MUST focus on making workspace scoping structurally correct at the data layer.
• FR-008 (Audit log invariant): If an audit log entry references a tenant, it MUST also reference a workspace.
• FR-009 (Audit scope flexibility): The audit log MUST continue to support workspace-only events (workspace present, tenant absent) and platform-only events (both absent).
• FR-010 (Canonical view scoping readiness): After rollout, operational/canonical queries SHOULD be able to scope tenant-owned data by workspace without relying on implicit joins or assumptions.

Assumptions & Dependencies

• Each tenant belongs to exactly one workspace, and that mapping is the source of truth for deriving workspace bindings.
• The 12 listed tables are “tenant-owned” per SCOPE-001 and are expected to remain tenant-owned.
• Any existing tooling that creates tenant-owned records has enough information to reference the tenant (directly or indirectly) at write time.

Key Entities (include if feature involves data)

• Workspace: The top-level isolation boundary for data access and operations.
• Tenant: A unit of configuration/data that is owned by exactly one workspace.
• Tenant-owned record: Any record that must be both tenant-scoped and workspace-scoped.
• Audit event: An immutable entry describing an action/event, which may be tenant-scoped, workspace-scoped, or platform-scoped.
• Backfill run: A controlled operational execution that updates legacy data and reports progress/outcomes.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001 (Completeness): 100% of records in the 12 tenant-owned tables have a workspace binding after backfill and validation.
• SC-002 (Integrity): After strict constraints are enabled, creating a tenant-owned record without a workspace binding is rejected.
• SC-003 (Audit correctness): 100% of tenant-scoped audit events include a workspace binding; workspace-only and platform-only audit events remain valid.
• SC-004 (Operational safety): The rollout requires no planned downtime for administrators.
• SC-005 (Repeatability): Re-running the backfill after completion does not change already-correct records and can be used as a safety check.