# ADR-0010: Shared Identity and Cross-Domain Session Model

**Status**: Accepted **Date**: 2026-02-16 **Authors**: OSHUN Platform
Engineering, OSHUN Security Engineering, OSHUN Mobile/Web Engineering
**Reviewers**: Domain Leads (Tara, Veritas, Nyx, Arete) **Supersedes**: N/A
**Superseded by**: `docs/adr/ADR-0072-oshun-customer-auth-and-session-model.md`

## Context and Problem Statement

OSHUN requires one identity and session model across four domains (Tara,
Veritas, Nyx, Arete) and three surfaces (mobile, web, PWA).

Current implementations are partially aligned but fragmented:

- Veritas mobile has auth hooks, OAuth, token refresh, and secure storage usage.
- Tara web has a full auth context/store/API model with token refresh and
  cookie-capable requests.
- Platform-level reusable auth libraries already exist in `@oshun/auth` and
  `@oshun/auth-primitives`.
- Some local implementations still persist auth session data in less strict
  stores and use domain-specific contracts.

Without a single OSHUN auth model, we risk:

- repeated logins between domains
- inconsistent token/session security posture
- weak observability for auth incidents
- entitlement drift across shell and domain actions

## Decision Drivers

- **One-account UX** with true cross-domain SSO behavior.
- **Security** with rotating refresh tokens and session revocation.
- **Platform consistency** across mobile, web, and PWA.
- **Reuse** of existing shared auth libraries in monorepo.
- **Compliance** with auditable session and consent controls.
- **Operational reliability** under token expiration and partial outages.

## Considered Options

### Option 1: Domain-Local Auth Sessions

**Description**: each domain maintains independent auth and the shell brokers
between them.

**Pros**:

- ✅ High domain autonomy
- ✅ Less immediate centralization work

**Cons**:

- ❌ Breaks one-account OSHUN promise
- ❌ Session duplication and inconsistent logout/revocation
- ❌ Complex entitlement reconciliation and analytics attribution

### Option 2: Shared Access Token Only, No Session Registry

**Description**: a shared JWT identity token is used everywhere without strong
session registry and refresh-token family controls.

**Pros**:

- ✅ Simpler implementation
- ✅ Fewer moving parts initially

**Cons**:

- ❌ Weaker revocation model
- ❌ Harder compromise containment
- ❌ Poor device/session management UX

### Option 3: Shared Identity + Central Session Registry + Rotating Refresh Tokens (Chosen)

**Description**: OSHUN uses one identity provider and centralized session model
with short-lived access tokens, rotating refresh tokens, and per-device session
management.

**Pros**:

- ✅ True cross-domain SSO behavior
- ✅ Stronger security and revocation controls
- ✅ Better auditability and incident response
- ✅ Clear integration contract for shell + domain adapters

**Cons**:

- ❌ Requires central auth governance
- ❌ Requires migration from domain-local token models
- ❌ More coordination across mobile/web/domain teams

## Decision Outcome

**Chosen option**: Option 3 - shared identity with centralized cross-domain
session model.

### Identity Model (Normative)

- One canonical OSHUN user identity (`oshun_user_id`) across all domains.
- Domain membership/entitlements represented as claims and server-evaluated
  policies.
- Domain adapters consume auth context from shell/BFF, not local ad hoc
  identity.

### Token and Session Model (Normative)

- Access token: short-lived JWT (target 10-15 minutes).
- Refresh token: long-lived, rotating token family with reuse detection.
- Session registry: per-device session records with revocation and metadata.
- Token refresh failures due revocation/compromise must force re-auth.

### Storage Rules by Surface

- **Mobile (iOS/Android)**:
  - store refresh/access tokens only in secure encrypted storage
  - never persist auth tokens in plain AsyncStorage
- **Web/PWA**:
  - refresh token in `HttpOnly`, `Secure`, `SameSite` cookie
  - access token in memory (or equivalent ephemeral runtime storage)
  - avoid long-lived sensitive token persistence in localStorage

### SSO Behavior (Normative)

- Login once in OSHUN shell establishes session for all four domains.
- Domain launch requests carry authenticated shell context.
- Domain APIs are accessed through:
  - BFF-mediated token exchange, or
  - domain-scoped token issuance from central auth service.
- Re-auth is required only for policy events (expired refresh, revoked session,
  step-up auth requirement).

### Session Control Requirements

- User can view active sessions/devices.
- User can revoke individual sessions.
- User can revoke all sessions (`logout all`) remotely.
- Shell must enforce revocation in near real time (within refresh cycle).

### Auth Method Requirements

Support at minimum:

- email/password
- OAuth providers used by platform domains
- optional biometric unlock on mobile (local convenience gate, not identity
  authority)

### Claim Contract Requirements

Access token claims must include at minimum:

- `sub` (`oshun_user_id`)
- `sid` (session id)
- `aud` (service audience)
- `exp`, `iat`, `jti`
- `entitlements`/tier info or policy reference

Sensitive authorization decisions remain server-side; client claims are hints,
not final authority.

## Implementation Guidance

### Reuse and Base Components

- Use `@oshun/auth-primitives` for JWT, sessions, refresh rotation primitives.
- Use `@oshun/auth` for auth service patterns, lockout, middleware, and RBAC.
- Align with platform auth direction from
  `docs/adr/ADR-0009-unified-auth-identity-strategy.md`.

### OSHUN Shell Integration

- Implement `libs/oshun/auth` as shell-facing auth client package.
- Provide one auth state source for mobile + web shell surfaces.
- Standardize auth error taxonomy (`unauthorized`, `session_revoked`,
  `refresh_failed`, `step_up_required`).

### Migration Rules

- Legacy domain-local auth tokens must be mapped into OSHUN session model.
- During migration, adapter boundary must prevent token leakage between domains.
- Any existing insecure token persistence paths must be removed before beta
  exit.

## Implementation Plan

### Phase 1: Contract and Client

- Define shared auth/session contract for OSHUN shell and BFF.
- Build `libs/oshun/auth` client wrappers over shared auth service.
- Define token/claim schema and session error taxonomy.

### Phase 2: Platform Integration

- Integrate mobile secure storage and refresh lifecycle.
- Integrate web cookie + in-memory token lifecycle.
- Add centralized session/device management endpoints.

### Phase 3: Domain Adapter Binding

- Ensure Tara/Veritas/Nyx/Arete adapter calls use unified auth context.
- Add entitlement gates at shell and BFF middleware layers.

### Phase 4: Hardening

- Add token reuse detection alerts.
- Add logout-all propagation tests.
- Add auth resilience tests for refresh failure/revocation/network loss.

## Success Metrics

- Cross-domain re-auth prompts reduced to policy-driven events only.
- Session refresh success rate >= 99% (excluding revoked/expired refresh
  tokens).
- 100% of shell auth tokens stored per policy (secure storage/cookie only).
- Logout-all revokes all active sessions within SLA.
- No P1 incidents caused by token desynchronization across domains.

## Consequences

### Positive Consequences

- ✅ Delivers true one-account OSHUN experience.
- ✅ Improves security posture via rotation + revocation controls.
- ✅ Simplifies auth observability and compliance auditing.
- ✅ Enables consistent entitlement enforcement.

### Negative Consequences

- ❌ Central auth service becomes a critical dependency.
- ❌ Migration complexity from mixed domain implementations.
- ❌ Requires tighter governance on auth contract changes.

### Risks and Mitigations

| Risk                                    | Probability | Impact | Mitigation                                                   |
| --------------------------------------- | ----------- | ------ | ------------------------------------------------------------ |
| Token storage regression on client      | Medium      | High   | Add static checks + auth storage integration tests           |
| Refresh token reuse attack              | Low         | High   | Enable family rotation + reuse detection + forced revocation |
| Session drift between shell and domains | Medium      | High   | BFF token exchange and centralized session introspection     |
| Central auth outage affects all domains | Medium      | High   | HA deployment, circuit breakers, graceful re-auth fallback   |

## Security and Compliance

- Enforce least-privilege token audiences and expiry windows.
- Log auth and session lifecycle events with audit-grade metadata.
- Protect refresh endpoints with abuse controls and anomaly detection.
- Honor privacy and account deletion/export requirements across all linked
  domain data.

## Monitoring and Observability

Track:

- auth success/failure by method
- refresh success/failure and error categories
- session revocations (single and global)
- suspicious refresh reuse events
- cross-domain launch failures attributable to auth state

## Related Decisions

- `docs/adr/ADR-0009-unified-auth-identity-strategy.md`
- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0015-deep-linking-and-cross-domain-routing.md`

## References

- `libs/shared/auth-primitives/src/token-refresh.ts`
- `libs/shared/auth/src/service.ts`
- `apps/veritas/mobile/src/hooks/useAuth.ts`
- `apps/veritas/mobile/src/services/storage.ts`
- `apps/tara/web/src/lib/auth/store.ts`