# TenantPilot Constitution ## Core Principles ### Inventory-first, Snapshots-second - All modules MUST operate primarily on Inventory as “last observed” state. - Inventory is the source of truth for what TenantPilot last observed; Microsoft Intune remains the external truth. - Snapshots/Backups MUST be explicit actions (manual or scheduled) and MUST remain immutable. ### Read/Write Separation by Default - Analysis, reporting, and monitoring features MUST be read-only by default. - Any write/change function (restore, remediation, promotion) MUST include preview/dry-run, explicit confirmation, audit logging, and tests. - High-risk policy types default to `preview-only` restore unless explicitly enabled by a feature spec + tests. ### Single Contract Path to Graph - All Microsoft Graph calls MUST go through `GraphClientInterface`. - Object types and endpoints MUST be modeled first in the contract registry (`config/graph_contracts.php`). - Feature code MUST NOT hardcode “quick endpoints” or bypass contracts. - Unknown/missing policy types MUST fail safe (preview-only / no Graph calls) rather than guessing endpoints. ### Deterministic Capabilities - Backup/restore/risk/support flags MUST be derived deterministically from config/contracts via a Capabilities Resolver. - The resolver output MUST be programmatically testable (snapshot/golden tests) so config changes cannot silently break behavior. ### 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. - Tenant membership is an isolation boundary. If the actor is not entitled to the tenant scope, the system MUST respond as deny-as-not-found (404). ### RBAC & UI Enforcement Standards (RBAC-UX) RBAC Context — Planes, Roles, and Auditability - 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. - Tenant role semantics MUST remain least-privilege: - 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. - The system MUST prevent removing or demoting the last remaining Owner of a tenant. - All access-control relevant changes MUST write `AuditLog` entries with stable action IDs, and MUST be redacted (no secrets). RBAC-UX-001 — Server-side is the source of truth - UI visibility / disabled state is never a security boundary. - Every mutating action (create/update/delete/restore/archive/force-delete), every operation start, and every credential/ config change MUST enforce authorization server-side via `Gate::authorize(...)` or a Policy method. - Any missing server-side authorization is a P0 security bug. RBAC-UX-002 — Deny-as-not-found for non-members - Tenant membership (and plane membership) is an isolation boundary. - If the current actor is not a member of the current tenant (or otherwise not entitled to the tenant scope), the system MUST respond as 404 (deny-as-not-found) for tenant-scoped routes/actions/resources. - This applies to Filament resources/pages under tenant routing (`/admin/t/{tenant}/...`), Global Search results, and all action endpoints (Livewire calls included). RBAC-UX-003 — Capability denial is 403 (after membership is established) - Within an established tenant scope, missing permissions are authorization failures. - If the actor is a tenant member, but lacks the required capability for an action, the server MUST fail with 403. - The UI may render disabled actions, but the server MUST still enforce 403 on execution. RBAC-UX-004 — Visible vs disabled UX rule - For tenant members: actions SHOULD be visible but disabled when capability is missing. - Disabled actions MUST provide helper text explaining the missing permission. - For non-members: actions MUST behave as not found (404) and SHOULD NOT leak resource existence. - Exception: highly sensitive controls (e.g., credential rotation) MAY be hidden even for members without permission. RBAC-UX-005 — Destructive confirmation standard - All destructive-like actions MUST require confirmation. - Delete/force-delete/archive/restore/remove membership/role downgrade/credential rotation/break-glass enter/exit MUST use `->requiresConfirmation()` and SHOULD include clear warning text. - Confirmation is UX only; authorization still MUST be server-side. RBAC-UX-006 — Capability registry is canonical - Capabilities MUST be centrally defined in a single canonical registry (constants/enum). - Feature code MUST reference capabilities only via the registry (no raw string literals). - Role → capability mapping MUST reference only registry entries. - CI MUST fail if unknown/unregistered capabilities are used. RBAC-UX-007 — Global search must be tenant-safe - Global search results MUST be scoped to the current tenant. - Non-members MUST never learn about resources in other tenants (no results, no hints). - If a result exists but is not accessible, it MUST be treated as not found (404 semantics). RBAC-UX-008 — Regression guards are mandatory - The repo MUST include RBAC regression tests asserting at least: - Readonly cannot mutate or start operations. - Operator can run allowed operations but cannot manage configuration. - Manager/Owner behave according to the role matrix. - The repo SHOULD include an automated “no ad-hoc authorization” guard that blocks new status/permission mappings sprinkled across `app/Filament/**`, pushing patterns into central helpers. ### Operations / Run Observability Standard - Every long-running or operationally relevant action MUST be observable, deduplicated, and auditable via Monitoring → Operations. - An action MUST create/reuse a canonical `OperationRun` and execute asynchronously when any of the following applies: 1. It can take > 2 seconds under normal conditions. 2. It performs remote/external calls (e.g., Microsoft Graph). 3. It is queued or scheduled. 4. It is operationally relevant for troubleshooting/audit (“what ran, who started it, did it succeed, what failed?”). - Actions that are DB-only and typically complete in < 2 seconds MAY skip `OperationRun`. - OPS-EX-AUTH-001 — Auth Handshake Exception: - OIDC/SAML login handshakes MAY perform synchronous outbound HTTP (e.g., token exchange) without an `OperationRun`. - Rationale: interactive, session-critical, and not a tenant-operational “background job”. - Guardrail: outbound HTTP for auth handshakes is allowed only on `/auth/*` endpoints and MUST NOT occur on Monitoring/Operations pages. - If an action is security-relevant or affects operational behavior (e.g., “Ignore policy”), it MUST write an `AuditLog` entry including actor, tenant, action, target, before/after, and timestamp. - The `OperationRun` record is the canonical source of truth for Monitoring (status, timestamps, counts, failures), even if implemented by multiple jobs/steps (“umbrella run”). - “Single-row” runs MUST still use consistent counters (e.g., `total=1`, `processed=0|1`) and outcome derived from success/failure. - Monitoring pages MUST be DB-only at render time (no external calls). - Start surfaces MUST NOT perform remote work inline; they only: authorize, create/reuse run (dedupe), enqueue work, confirm + “View run”. - Active-run dedupe MUST be enforced at DB level (partial unique index/constraint for active states). - Failures MUST be stored as stable reason codes + sanitized messages; never persist secrets/tokens/PII/raw payload dumps in failures or notifications. - Graph calls are allowed only via explicit user interaction and only when delegated auth is present; never as a render side-effect (restore group mapping is intentionally DB-only). - Monitoring → Operations is reserved for `OperationRun`-tracked operations. - Scheduled/queued operations MUST use locks + idempotency (no duplicates). - Graph throttling and transient failures MUST be handled with backoff + jitter (e.g., 429/503). ### Data Minimization & Safe Logging - Inventory MUST store only metadata + whitelisted `meta_jsonb`. - Payload-heavy content belongs in immutable snapshots/backup storage, not Inventory. - Logs MUST not contain secrets/tokens; monitoring MUST rely on run records + error codes (not log parsing). ### Badge Semantics Are Centralized (BADGE-001) - Status-like badges (status/outcome/severity/risk/availability/boolean signals) MUST render via `BadgeCatalog` / `BadgeRenderer`. - Filament resources/pages/widgets/views MUST NOT introduce ad-hoc status-like badge mappings (use a `BadgeDomain` instead). - Introducing or changing a status-like value MUST include updating the relevant badge mapper and adding/updating tests for the mapping. - Tag/category chips (e.g., type/platform/environment) are not status-like and are not governed by BADGE-001. ### Spec-First Workflow - For any feature that changes runtime behavior, include or update `specs/-/` with `spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md`. - New work branches from `dev` using `feat/-` (spec + code in the same PR). ## Quality Gates - Changes MUST be programmatically tested (Pest) and run via targeted `php artisan test ...`. - Run `./vendor/bin/sail bin pint --dirty` before finalizing. ## Governance ### Scope & Compliance - This constitution applies across the repo. Feature specs may add stricter constraints but not weaker ones. - Restore semantics changes require: spec update, checklist update (if applicable), and tests proving safety. ### Amendment Procedure - Propose changes as a PR that updates `.specify/memory/constitution.md`. - The PR MUST include a short rationale and list of impacted templates/specs. - Amendments MUST update **Last Amended** date. ### Versioning Policy (SemVer) - **PATCH**: clarifications/typos/non-semantic refinements. - **MINOR**: new principle/section or materially expanded guidance. - **MAJOR**: removing/redefining principles in a backward-incompatible way. **Version**: 1.6.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-01-28