/docs
  /adr
    0001-use-bff-http-only-cookie-session.md
    0002-use-authorization-code-pkce.md
    0003-permission-contract-not-role-checks.md
    0004-tenant-context-server-validated.md
    0005-session-epoch-for-forced-logout.md
    README.md

# Auth ADR Index

| ADR | Status | Area | Decision | Supersedes |
|---|---|---|---|---|
| 0001 | Accepted | Session | Use BFF + HttpOnly cookie app session | - |
| 0002 | Accepted | OAuth | Use Authorization Code with PKCE | - |
| 0003 | Accepted | Authorization | Use permission contract instead of role checks | - |
| 0004 | Accepted | Multi-tenancy | Validate tenant context server-side per request | - |
| 0005 | Proposed | Incident response | Introduce session epoch for forced logout | - |

# ADR-XXXX: <Decision title>

## Status

Proposed | Accepted | Rejected | Deprecated | Superseded

## Date

YYYY-MM-DD

## Owners

- Engineering owner:
- Security owner:
- Product/domain owner:
- Operations owner:

## Decision

State the decision in one or two paragraphs.

## Context

Explain why this decision is needed now.
Include business, security, operational, and migration context.

## Threat model

List relevant threats:

- XSS
- CSRF
- BOLA/IDOR
- open redirect
- stale privilege
- tenant confusion
- token replay
- session fixation
- audit gap
- provider outage

## Requirements

### Functional requirements

- ...

### Security requirements

- ...

### Operational requirements

- ...

### Regulatory/audit requirements

- ...

## Options considered

### Option A: ...

Pros:

- ...

Cons:

- ...

### Option B: ...

Pros:

- ...

Cons:

- ...

## Decision criteria

| Criterion | Weight | Option A | Option B | Notes |
|---|---:|---:|---:|---|
| Token leakage blast radius | 5 |  |  |  |
| CSRF exposure | 4 |  |  |  |
| Revocation latency | 5 |  |  |  |
| SSR/BFF compatibility | 3 |  |  |  |
| Developer ergonomics | 3 |  |  |  |
| Migration cost | 2 |  |  |  |

## Consequences

### Positive consequences

- ...

### Negative consequences

- ...

### New failure modes

- ...

## Invariants

These must remain true after implementation:

- ...

## Implementation plan

1. ...
2. ...
3. ...

## Rollout plan

- Feature flag / cohort / environment strategy.
- Backward compatibility.
- Monitoring.
- Rollback trigger.

## Rollback/reversal plan

Explain how to undo or supersede the decision.

## Testing requirements

- Unit tests:
- Integration tests:
- E2E tests:
- Security tests:
- Contract tests:

## Observability

Metrics, logs, traces, audit events, alerts.

## Runbooks impacted

- Link to runbook(s).

## References

- OWASP / RFC / provider docs / internal docs.

# ADR-0001: Use BFF with HttpOnly cookie app session

## Status

Accepted

## Decision

We will use a Backend-for-Frontend session model for the React application.
The browser receives an opaque app session cookie with `HttpOnly`, `Secure`, and `SameSite` attributes.
OAuth provider access/refresh tokens are stored server-side in the BFF token vault and are never exposed to React runtime code.

## Context

The application handles regulated case data, tenant-scoped resources, file downloads, and privileged administrative workflows.
The previous SPA prototype stored access tokens in browser storage.
This increased the blast radius of XSS and made token revocation and incident response harder.

## Threat model

- XSS may execute JavaScript within the app origin.
- CSRF may target cookie-authenticated mutation endpoints.
- Browser extensions may observe page state.
- Stale tokens may survive role/tenant changes.
- OAuth refresh token compromise requires containment.

## Options considered

### Option A: localStorage bearer token

Pros:

- Simple to implement.
- Works with cross-origin APIs.
- Easy developer debugging.

Cons:

- Token is readable by any successful XSS.
- Logout/revocation is harder.
- Every frontend API path must handle refresh correctly.
- Sensitive credential can be exposed through browser debugging artifacts.

### Option B: in-memory access token with refresh rotation

Pros:

- Access token is not persisted in browser storage.
- Better than localStorage for XSS persistence.
- Works with cross-origin APIs.

Cons:

- Refresh token/session continuity remains complex.
- Multi-tab coordination is error-prone.
- Harder SSR story.
- Browser still handles bearer capability.

### Option C: BFF + HttpOnly cookie app session

Pros:

- Provider tokens are hidden from browser JavaScript.
- Server controls refresh, revocation, downstream authorization, and audit.
- Works well with SSR and route handlers.
- Centralizes CSRF, token refresh, and downstream API policy.

Cons:

- Requires BFF infrastructure.
- Cookie auth needs CSRF defense.
- API calls generally flow through same-origin BFF endpoints.
- Operational outage of BFF affects app access.

## Decision criteria

The decisive criteria were token leakage blast radius, revocation, auditability, SSR compatibility, and incident containment.

## Consequences

Positive:

- React runtime receives only session projection, not raw tokens.
- Refresh token rotation is handled server-side.
- Forced logout is possible through server-side session invalidation.

Negative:

- We must build and operate BFF endpoints.
- CSRF defense becomes mandatory for unsafe methods.
- BFF latency and availability become product concerns.

## Invariants

- Provider access tokens and refresh tokens never enter React runtime.
- React app calls same-origin BFF endpoints for protected operations.
- Unsafe methods require CSRF protection.
- Logout revokes the app session server-side and clears browser projection state.
- `/api/session` returns only safe projection fields.

## Testing requirements

- Assert no provider token appears in HTML, JS, logs, or `/api/session`.
- Test CSRF rejection on unsafe methods.
- Test logout invalidates BFF session server-side.
- Test forced logout through session epoch.
- Test tenant switch clears query/cache state.

# ADR-0003: Use permission contract instead of frontend role checks

## Status

Accepted

## Decision

React components and route metadata must use a permission decision contract instead of checking raw roles.
The backend remains the enforcement authority.
The frontend consumes server-projected capabilities such as `allowedActions`, field modes, constraints, and denial reasons.

## Context

The app began with `user.role === "admin"` checks.
That pattern caused drift because roles differ by tenant, workflow state, object ownership, and temporary grants.

## Options considered

### Option A: Continue role checks

Pros:

- Simple.
- Familiar.

Cons:

- Causes role explosion.
- Cannot express object-level grants or workflow constraints.
- Encourages frontend-only authorization mistakes.

### Option B: Permission contract

Pros:

- UI speaks in product actions.
- Works with RBAC, ABAC, ACL, or ReBAC behind the scenes.
- Supports denial reasons and access request workflows.
- Easier to test with golden matrices.

Cons:

- Requires action vocabulary governance.
- Requires contract testing.
- Requires cache invalidation policy.

## Invariants

- Components do not check raw roles for access decisions.
- Components check product actions such as `case.close`, `case.assign`, or `document.export`.
- Backend validates every protected action regardless of UI state.
- Unknown permission state renders denied or loading-safe UI.
- Permission projection includes version/epoch metadata for invalidation.

# ADR-0006: Use signed double-submit CSRF token for cookie-authenticated BFF mutations

## Status

Accepted

## Decision

Cookie-authenticated unsafe BFF requests must include a CSRF token in a custom header.
The CSRF token is generated server-side, signed, and bound to the app session.
The BFF validates the header token against the signed session-bound value for unsafe methods.

## Context

The BFF uses cookies for session continuity.
Cookie authentication introduces CSRF risk for unsafe methods.
SameSite cookies reduce but do not fully replace explicit CSRF protection for sensitive applications.

## Invariants

- `GET`, `HEAD`, and safe methods do not mutate server state.
- `POST`, `PUT`, `PATCH`, and `DELETE` require valid CSRF token.
- Token validation happens before business mutation.
- CORS does not allow arbitrary origins to send credentialed unsafe requests.
- Sensitive operations may require additional step-up authentication.

# ADR-0007: Use route loaders for authentication gate and server-side authorization for resource access

## Status

Accepted

## Decision

React Router route loaders perform early authentication and safe session projection before render.
Resource authorization remains server-side at API/BFF/resource boundary.
Route metadata may declare required product capabilities for UI exposure, but it does not replace backend checks.

## Context

Component-only protected routes caused data flash and late redirects.
Loader-level auth prevents sensitive UI/data from rendering before session state is known.

## Invariants

- Protected routes must not render before session bootstrap resolves.
- Loaders may redirect anonymous users to login.
- Loaders must not fetch protected resource data before authentication is known.
- Resource APIs must still authorize every request.
- Route metadata and backend permission vocabulary are contract-tested.

# ADR-0010: Use session epoch for forced logout and stale privilege containment

## Status

Accepted

## Decision

Each user/session has a server-controlled session epoch.
The React app receives the current epoch in session projection.
When the server increments the epoch due to forced logout, password reset, token leak, role revocation, or incident containment, existing sessions become invalid and the frontend must clear projection state.

## Context

We need a way to invalidate sessions across devices and tabs without relying only on client-side logout.

## Invariants

- Server compares request session epoch with authoritative user/session epoch.
- Epoch mismatch invalidates the request.
- Client treats epoch mismatch as forced logout, not generic network failure.
- Query/cache/router state is cleared after forced logout.
- Forced logout emits audit and security telemetry.

We will use JWT because it is standard.

We considered JWT access tokens, opaque tokens with introspection, and server-side app sessions.
We chose opaque app sessions because revocation latency and incident containment matter more than stateless validation in this application.

We store tokens in browser storage for simplicity.

We explicitly accept that XSS can read tokens from browser storage.
This is rejected for regulated environments; browser storage is allowed only for low-risk internal tools with short-lived tokens and no refresh token persistence.

We use Provider X because it is popular.

We use Provider X because it supports OIDC Authorization Code with PKCE, organization-scoped SSO, SCIM provisioning, MFA policy, signed webhooks, and tenant discovery that matches our enterprise SaaS requirements.

We will migrate to BFF.

If BFF latency or outage rate exceeds threshold, we can temporarily route read-only calls through existing API gateway while keeping provider refresh tokens server-side. Full rollback requires keeping the legacy token exchange endpoint for 30 days.

Disable button when case is closed.

Case closure is enforced server-side by workflow policy. The frontend receives `allowedActions.close = false` with reason `workflow_state_denied` to avoid exposing a misleading action.

export type AdrStatus =
  | "proposed"
  | "accepted"
  | "rejected"
  | "deprecated"
  | "superseded";

export type AuthDecisionArea =
  | "session"
  | "oauth-oidc"
  | "token"
  | "cookie"
  | "csrf"
  | "authorization"
  | "permission-contract"
  | "tenant"
  | "cache"
  | "observability"
  | "incident-response"
  | "privacy"
  | "provider";

export interface AuthAdrMetadata {
  id: string;
  title: string;
  status: AdrStatus;
  date: string;
  owners: string[];
  areas: AuthDecisionArea[];
  supersedes?: string[];
  supersededBy?: string;
  affectedServices: string[];
  affectedPackages: string[];
  relatedRunbooks: string[];
  relatedTests: string[];
  invariants: string[];
}

function validateAdr(metadata: AuthAdrMetadata) {
  if (metadata.status === "accepted" && metadata.invariants.length === 0) {
    throw new Error(`${metadata.id} has no invariants`);
  }

  if (metadata.status === "accepted" && metadata.relatedTests.length === 0) {
    throw new Error(`${metadata.id} has no related tests`);
  }

  if (metadata.areas.includes("incident-response") && metadata.relatedRunbooks.length === 0) {
    throw new Error(`${metadata.id} impacts incident response but links no runbook`);
  }
}

## Auth impact

- [ ] No auth impact.
- [ ] Changes authentication/session behavior. ADR linked: ___
- [ ] Changes authorization/permission behavior. ADR linked: ___
- [ ] Changes tenant context/cache behavior. ADR linked: ___
- [ ] Changes audit/logging/observability. ADR linked: ___

## Required checks

- [ ] Existing ADR covers this change.
- [ ] New ADR added or old ADR superseded.
- [ ] Invariants updated.
- [ ] Tests updated.
- [ ] Runbook updated if operational behavior changed.

A user who can view a case summary is not automatically allowed to view evidence attachments, export documents, edit enforcement recommendations, or approve final action.