Security & threat model

​

Motivation

​

Theory & background

1. Tenant isolation is explicit, not magic. There is no global query scope to forget to bypass; every tenant-aware read must opt in to scoping, and an architecture test proves it did.
2. Authorization is a matrix, not per-route hope. Every protected endpoint is pinned to an exact allow-set of roles in a regression-gating test.
3. Single-use means atomic. A confirm token’s read-and-consume holds the lock until used_at is written, in one transaction — or the invariant does not exist.
4. Feature flags are safe in both states. A default-off flag must degrade cleanly when off and not 500 when on-but-unwired.

​

Design

​

Multi-tenant isolation (R30 / R31)

• On creating, it auto-fills tenant_id from TenantContext if unset.
• It provides scopeForTenant(string $tenantId) for explicit query scoping.
• It does not register a global read scope.

​

RBAC (R32)

​

Atomic single-use confirm tokens (R21)

​

Audit trails

• kb_canonical_audit — immutable canonical-layer events (no updated_at, no FK to documents, survives hard deletes).
• admin_command_audit — every maintenance command execution (actor, args, result), retained audit_retention_days (default 365).
• activity_log — Spatie polymorphic audit for users/roles/permissions.

​

Secrets & logging

​

Decision rationale (ADR-style)

• Why no global tenant scope? A global scope is a single point of silent failure — one withoutGlobalScope() and the boundary is gone, invisibly. Explicit forTenant() + a failing architecture test makes leaks loud at CI time, not in production.
• Why a matrix test, not per-controller tests? Per-controller tests each cover one endpoint; a new route that forgets its gate ships green. The matrix enumerates the full allow-set, so a missing gate fails the build. Graded on blast radius — one missing gate is a public breach.
• Why atomic consume, not “rare race”? For a destructive-command token the TOCTOU window is RCE-class. The lock must hold until the write — frequency is irrelevant, blast radius is everything.
• Why default-off isolation? Backward compatibility: v8.9 shipped per-project isolation opt-in so existing tenants keep their cross-project reads until they choose to tighten.

​

Worked example

// every tenant-aware read opts in — a bare query fails the architecture test
$docs = KnowledgeDocument::query()
    ->forTenant($ctx->current())     // R30 — required
    ->canonical()->accepted()        // canonical scopes
    ->get();

# concurrent destructive-command requests with the same token
req A: BEGIN; SELECT … FOR UPDATE; used_at NULL → write used_at; COMMIT  ✓ runs
req B: BEGIN; SELECT … FOR UPDATE (blocks) → used_at SET → reject       ✗ 422

​

Gotchas & operations

• Forgetting forTenant() fails CI, not silently in prod — fix the query, do not suppress the test.
• New protected route → add its matrix row in the same PR, or it ships ungated-and-green.
• lockForUpdate() read and the state write live in the same transaction — never consume a single-use resource across a transaction boundary.
• Test feature flags in both states — a default-off flag that 500s when enabled (or crashes a consumer when disabled) is a public incident the first time an operator flips it.