Skip to content

Authentication and Identity

Ankit Upadhyay edited this page Jul 24, 2026 · 2 revisions

Authentication and Identity

How users prove who they are, and the migration that moved auth off external providers. The decision is ADR-0003; the rollout plan was Plans - Authentication.

Current state

Authentication runs on self-hosted SuperTokens behind a provider-neutral boundary, across all three clients (landed via PR #1763, merged 2026-07-16):

  • Backend: packages/auth (@yosemite-crew/auth) owns initSuperTokens and createSessionMiddleware; apps/backend/src/middlewares/auth.ts exposes the provider-neutral guards requireWebAuth, requireMobileAuth, and requireAnyAuth (provider selected at deployment time via AUTH_PROVIDER).
  • Web (PIMS): supertokens-web-js — email/password sign-in with MFA (totp | otp-email) and cookie sessions with automatic refresh (src/app/lib/authClient.ts + authStore.ts), plus GitHub ThirdParty sign-in for developers. See Frontend: Auth and Session.
  • Mobile (pet owners): supertokens-react-native — passwordless OTP plus Google/Apple social sign-in exchanged through SuperTokens signinup. See Mobile: Auth, Navigation, Bootstrap.
  • Legacy: Cognito and Firebase survive only as grace-window verifiers (packages/auth/src/providers/legacy-cognito/, gated by AUTH_LEGACY_TOKEN_GRACE), so residual pre-cutover tokens don't hard-fail during the migration window.

The provider-neutral boundary with SuperTokens

ADR-0003 introduced a provider-neutral authentication boundary and made self-hosted SuperTokens the first adapter behind it:

  • Route protection stops naming a vendor — requireWebAuth replaced authorizeCognito.
  • Email/OTP (Cognito) and social (Firebase) sign-in migrated onto self-hosted SuperTokens in apps/backend, apps/frontend, and apps/mobileAppYC, rolled out behind a feature flag with a dual-verify window rather than a hard switch.
  • The SuperTokens deployment sits in the same declared region as tenant data, giving identity and tenant data one residency posture (ADR-0004).

The dual-verify cutover mechanism, as implemented (legacy verification is gated by AUTH_LEGACY_TOKEN_GRACE):

sequenceDiagram
    participant C as Client
    participant API as Backend (requireWebAuth)
    participant NEW as SuperTokens
    participant OLD as Cognito / Firebase (legacy)
    Note over API: dual-verify grace window (AUTH_LEGACY_TOKEN_GRACE)
    C->>API: request with token
    API->>NEW: verify (new provider)
    alt valid on SuperTokens
        NEW-->>API: ok
    else not yet migrated
        API->>OLD: verify (legacy)
        OLD-->>API: ok
    end
    API-->>C: authorized (org-scoped)
Loading

Landed as PR #1763 (merged 2026-07-16); epic #1672 stays open for follow-ups. Roadmap items on top of the migration — passkeys (WebAuthn) and the broader MFA/2FA rollout for the web PIMS — are captured in Plans - Authentication.

Authorization: org context + RBAC

Authentication answers "who are you"; authorization answers "what can you do here", and it is always organization-scoped. The session carries an org context claim:

interface OrgSessionClaim {
  orgId: string;
  role: 'OWNER' | 'ADMIN' | 'SUPERVISOR' | 'VETERINARIAN'
      | 'TECHNICIAN' | 'ASSISTANT' | 'RECEPTIONIST';
  permissions: string[]; // e.g. ['appointments:view:any', 'prescription:write']
}

The seven-role model and its fine-grained permission strings are documented in Multi-Tenancy and RBAC. This role structure was preserved across the SuperTokens migration.

Developer platform identity

External developers authenticate differently from clinic staff — via DeveloperApiKey (hashed keys, scoped) enforced by authorizeApiKey + requireScope, with usage metering and per-key rate limits. Publishing/promoting config still requires an interactive human web session (requireWebAuth). See Developer Portal, ADR-0004, and ADR-0005.

SuperAdmin

The separate SuperAdmin app uses SuperTokens exclusively (EmailPassword, EmailVerification, Session, UserMetadata, UserRoles, TOTP/MFA) with no dedicated database — even its audit log lives in UserMetadata (SuperAdmin ADR-0001).

Related

Product & Domain
Architecture
Applications
Design & Accessibility
Engineering Handbook
Decisions (ADRs)
Design Docs & Plans
Roadmap
Operations
Meta

Canonical code & docs: main repo · Auto-generated companion: DeepWiki

Clone this wiki locally