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#

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