ahmido
c5fbcaa692
Key changes Adds Entra OIDC redirect + callback endpoints under /auth/entra/* (token exchange only there). Upserts tenant users keyed by (entra_tenant_id = tid, entra_object_id = oid); regenerates session; never stores tokens. Blocks disabled / soft-deleted users with a generic error and safe logging. Membership-based post-login routing: 0 memberships → /admin/no-access 1 membership → tenant dashboard (via Filament URL helpers) >1 memberships → /admin/choose-tenant Adds Filament pages: /admin/choose-tenant (tenant selection + redirect) /admin/no-access (tenantless-safe) Both use simple layout to avoid tenant-required UI. Guards / tests Adds DbOnlyPagesDoNotMakeHttpRequestsTest to enforce DB-only render/hydration for: /admin/login, /admin/no-access, /admin/choose-tenant with Http::preventStrayRequests() Adds session separation smoke coverage to ensure tenant session doesn’t access system and vice versa. Runs: vendor/bin/sail artisan test --compact tests/Feature/Auth Co-authored-by: Ahmed Darrazi <ahmeddarrazi@MacBookPro.fritz.box> Reviewed-on: #76
112 lines
6.7 KiB
Markdown
112 lines
6.7 KiB
Markdown
<!--
|
|
Sync Impact Report
|
|
|
|
- Version change: 1.3.0 → 1.4.0
|
|
- Modified principles:
|
|
- Operations / Run Observability Standard (added OPS-EX-AUTH-001)
|
|
- Added sections:
|
|
- OPS-EX-AUTH-001 — Auth Handshake Exception
|
|
- 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.
|
|
-->
|
|
|
|
# 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.
|
|
|
|
### 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/<NNN>-<slug>/` with `spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md`.
|
|
- New work branches from `dev` using `feat/<NNN>-<slug>` (spec + code in the same PR).
|
|
|
|
## Quality Gates
|
|
- Changes MUST be programmatically tested (Pest) and run via targeted `php artisan test ...`.
|
|
- Run `./vendor/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.4.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-01-27
|