ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

docs: enforce RBAC constitution gates in spec templates

Browse Source
This commit is contained in:
Ahmed Darrazi 2026-01-27 23:05:01 +01:00
parent 210cf5ce8b
commit c13e9e6d11
4 changed files with 70 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
.specify/memory/constitution.md
View File

@ -1,19 +1,18 @@
<!--
Sync Impact Report
- Version change: 1.3.0 → 1.4.0
- Version change: 1.4.0 → 1.5.0
- Modified principles:
- Operations / Run Observability Standard (added OPS-EX-AUTH-001)
- Tenant Isolation is Non-negotiable (added deny-as-not-found requirement)
- Added sections:
- OPS-EX-AUTH-001 — Auth Handshake Exception
- RBAC Standard (RBAC-001..RBAC-009)
- Removed sections: None
- Templates requiring updates:
- ✅ .specify/templates/plan-template.md
- ✅ .specify/templates/spec-template.md
- ✅ .specify/templates/tasks-template.md
- N/A: .specify/templates/commands/ (directory not present)
- Follow-up TODOs:
- TODO(DELETED_STATUS): Keep “deleted” reserved for Feature 900 / Policy Lifecycle.
- Follow-up TODOs: None
-->
# TenantPilot Constitution
@ -44,6 +43,58 @@ ### Tenant Isolation is Non-negotiable
- Every read/write MUST be tenant-scoped.
- Cross-tenant views (MSP/Platform) MUST be explicit, access-checked, and aggregation-based (no ID-based shortcuts).
- Prefer least-privilege roles/scopes; surface warnings when higher privileges are selected.
- A non-member attempting to access a tenant route MUST be deny-as-not-found (404).
### RBAC Standard (RBAC-001)
RBAC-001 Two Planes
- The platform MUST maintain two strictly separated authorization planes:
- Tenant plane (`/admin/t/{tenant}`): authenticated Entra users (`users`), authorization is tenant-scoped.
- Platform plane (`/system`): authenticated platform users (`platform_users`), authorization is platform-scoped.
- Cross-plane access MUST be deny-as-not-found (404) (not 403) to avoid route enumeration.
RBAC-002 Capabilities-first Authorization
- Feature code MUST NOT check raw roles directly (e.g. string role comparisons).
- Feature code MUST check capabilities via Gates/Policies only.
- A canonical capability registry MUST exist as the single source of truth (e.g. `TenantCapabilities` / `PlatformCapabilities`).
- Role → capability mapping MUST reference only registry entries.
RBAC-003 Least Privilege Role Semantics
- Tenant roles MUST follow least-privilege semantics:
- Readonly: view-only; MUST NOT start operations and MUST NOT mutate data.
- Operator: MAY start allowed tenant operations; MUST NOT manage credentials, settings, members, or perform destructive actions.
- Manager: MAY manage tenant configuration and start operations; MUST NOT manage tenant memberships (Owner-only).
- Owner: MAY manage memberships and all tenant configuration; Owner-only “danger zone” actions MUST remain Owner-only.
RBAC-004 UI is not Security
- Hiding UI elements is NOT sufficient.
- Every mutation endpoint and action MUST enforce authorization server-side (Policy/Gate).
RBAC-005 Destructive Actions Gate
- All destructive actions (delete / force delete / irreversible operations) MUST:
- require an explicit confirmation (e.g., `requiresConfirmation()` or equivalent),
- be protected by a Policy/Gate,
- have at least one regression test asserting the action is forbidden for non-authorized roles.
RBAC-006 Membership Safety Rule
- The system MUST prevent removing or demoting the last remaining Owner of a tenant.
RBAC-007 Tenant Isolation
- All tenant-plane queries MUST be tenant-scoped.
- A non-member attempting to access a tenant route MUST be deny-as-not-found (404).
RBAC-008 Auditing
- All access-control relevant changes MUST write `AuditLog` entries with stable action IDs, including:
- membership add / role change / remove
- provider credential rotation / connection disable
- break-glass enter / exit / expire (platform plane)
- `AuditLog` entries MUST be redacted (no secrets/tokens, minimal identity fields).
RBAC-009 Testability Gate
- Any new feature that introduces or changes authorization MUST include:
- at least one positive test (authorized user can do it),
- at least one negative test (unauthorized user cannot do it),
- and MUST NOT introduce role-string checks outside the central mapping/registry.
### Operations / Run Observability Standard
- Every long-running or operationally relevant action MUST be observable, deduplicated, and auditable via Monitoring → Operations.
@ -108,4 +159,4 @@ ### Versioning Policy (SemVer)
- **MINOR**: new principle/section or materially expanded guidance.
- **MAJOR**: removing/redefining principles in a backward-incompatible way.
**Version**: 1.4.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-01-27
**Version**: 1.5.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-01-27

1
.specify/templates/plan-template.md
View File

@ -35,6 +35,7 @@ ## Constitution Check
- Read/write separation: any writes require preview + confirmation + audit + tests
- Graph contract path: Graph calls only via `GraphClientInterface` + `config/graph_contracts.php`
- Deterministic capabilities: capability derivation is testable (snapshot/golden tests)
- RBAC Standard: two planes (/admin vs /system) remain separated; cross-plane is 404; authorization checks use Gates/Policies + capability registries (no role-string checks)
- Tenant isolation: all reads/writes tenant-scoped; cross-tenant views are explicit and access-checked
- Run observability: long-running/remote/queued work creates/reuses `OperationRun`; start surfaces enqueue-only; Monitoring is DB-only; DB-only <2s actions may skip runs but security-relevant ones still audit-log; auth handshake exception OPS-EX-AUTH-001 allows synchronous outbound HTTP on `/auth/*` without `OperationRun`
- Automation: queued/scheduled ops use locks + idempotency; handle 429/503 with backoff+jitter

7
.specify/templates/spec-template.md
View File

@ -82,6 +82,13 @@ ## Requirements *(mandatory)*
(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 Standard):** If this feature introduces or changes authorization behavior, the spec MUST:
- state which authorization plane(s) are involved (tenant `/admin/t/{tenant}` vs platform `/system`),
- ensure any cross-plane access is deny-as-not-found (404),
- describe how authorization is enforced server-side (Gates/Policies),
- reference the canonical capability registry (no role-string checks in feature code),
- include at least one positive and one negative authorization test.
**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.

5
.specify/templates/tasks-template.md
View File

@ -14,6 +14,11 @@ # Tasks: [FEATURE NAME]
If security-relevant DB-only actions skip `OperationRun`, include tasks for `AuditLog` entries (before/after + actor + tenant).
Auth handshake exception (OPS-EX-AUTH-001): OIDC/SAML login handshakes may perform synchronous outbound HTTP on `/auth/*` endpoints
without an `OperationRun`.
**RBAC**: If this feature introduces or changes authorization, tasks MUST include:
- explicit Gate/Policy enforcement for all mutation endpoints/actions,
- capability registry usage (no role-string checks in feature code),
- cross-plane deny-as-not-found (404) checks where applicable,
- at least one positive + one negative authorization test.
**Badges**: If this feature changes status-like badge semantics, tasks MUST use `BadgeCatalog` / `BadgeRenderer` (BADGE-001),
avoid ad-hoc mappings in Filament, and include mapping tests for any new/changed values.