Status: Accepted Date: 2026-02-06 Deciders: Reflections Maintainers
Context
Reflection data is tenant-scoped. Today, the API enforces reflection membership/role checks before data access and mutation, while database policy hardening is being added for future PostgREST enablement and direct SQL misuse defense.Decision
Adopt a dual-layer tenant isolation model:- Application boundary: all authenticated reflection-scoped endpoints enforce server-derived membership roles (
member/admin/owner). - Public boundary: explicitly scoped anonymous routes are isolated to share-link flows with constrained namespaces and expiry/use controls.
- Database boundary: enforce RLS policies and helper functions across tenant tables as defense in depth, independent of API route correctness.
Alternatives considered
Alternative 1: API-only authorization, no RLS
Pros:- Simpler operational model.
- Less SQL policy maintenance.
- Larger blast radius from API bugs or bypasses.
- Weak defense against accidental direct DB access paths.
Alternative 2: RLS-only authorization, thin API checks
Pros:- Centralized data policy model in DB.
- Harder app-level intent checks and resource-specific semantics.
- More complex policy debugging at request boundaries.
Alternative 3: Separate databases per tenant
Pros:- Strong physical isolation.
- Operationally expensive and complex at this stage.
- Significant deployment and migration overhead.
Consequences
Benefits:- Defense-in-depth against authz regressions.
- Clear delineation of authenticated, privileged, and anonymous access surfaces.
- Better long-term portability if API access patterns evolve.
- Additional policy complexity and verification burden.
- Need to keep API and DB policy semantics aligned.
Implementation notes
- API role enforcement is centralized in the authorization module.
- Anonymous share-path controls are in the public routes module.
- DB RLS policy layer is codified in dedicated migrations.