Auth Boundary Isolation
When this skill activates
Use this skill whenever the work introduces privileged actions, admin dashboards, role-aware endpoints, background jobs that impersonate users, or any code path that must not be reachable by an unauthenticated caller.
Also use it when a user-facing flow starts reading admin headers, service tokens, support roles, feature flags, tenant ids, organization ids, or account-linking state.
Baseline rules
- Privileged code lives behind a single explicit boundary. Any code reachable on a user request path is treated as user code.
- A request that authenticates a user never silently elevates to admin scope later in the same handler.
- Background workers that act "as" a user declare the impersonation explicitly and log it.
- Session identifiers, API tokens, and admin credentials are never interchangeable in middleware.
- Access control is deny-by-default and checked server-side on every privileged action, not only in navigation or client state.
- Authorization decisions must include subject, action, resource, tenant/scope, and reason. Role names alone are not enough for sensitive operations.
Design patterns
Dedicated admin surface
- Route admin endpoints through a distinct router mounted under a clearly named prefix.
- Give the admin surface its own middleware stack — not a flag on the user middleware.
- Deny by default. An endpoint that is not explicitly admin-allowed is not reachable through the admin surface.
- Keep admin CORS, cookie, session, CSRF, and rate-limit policy separate from user-facing routes.
Context objects
- Build an explicit request context that carries the authenticated principal, the allowed scopes, and the session id.
- Pass the context object to business code. Do not read session globals from inside domain logic.
- Treat the context as immutable per request. Re-issuing a context means restarting the request.
- Include tenant or organization scope in the context. Missing scope should fail closed.
Privilege escalation
- Escalation is a discrete action with its own audit record — not an
if (admin) branch buried in a handler.
- Require fresh authentication for destructive admin actions even inside an already-authenticated session.
- Rate-limit admin actions separately from user actions.
- Expire elevated sessions quickly and bind them to the actor, device/session, reason, and target scope.
Failure modes to flag
- A user endpoint that reads an admin token header "if present." That is not isolation.
- A shared middleware that uses
req.user.isAdmin to toggle behavior on the same endpoint for different actors.
- Background jobs that fabricate a user object without referencing a real identity.
- Admin APIs proxied through user-facing CORS rules.
- Tenant or account ids accepted from the client without checking that the principal can access that resource.
- Feature flags used as authorization controls.
- Support impersonation that can be triggered from a normal browser session without a separate audit path.
Required tests
- A normal user cannot reach every admin route, even by changing headers, tenant ids, or request body scope.
- An admin without the required resource scope is rejected.
- Expired, revoked, or downgraded sessions cannot reuse cached authorization.
- Impersonation records actor, target, reason, start, end, and outcome.
Related skills
- Use
secrets-baseline when admin tokens, service credentials, or signing keys are introduced.
- Use
pdpl-basics when privileged users can view, export, correct, or delete personal data.
References
- Read
references/auth-isolation-checklist.md before merging a change that introduces an admin or privileged code path.
Version: 0.4.0 · Last verified: 2026-04-24 · Status: community-maintained
Sources