Repository navigation
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.
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) ownsinitSuperTokensandcreateSessionMiddleware;apps/backend/src/middlewares/auth.tsexposes the provider-neutral guardsrequireWebAuth,requireMobileAuth, andrequireAnyAuth(provider selected at deployment time viaAUTH_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 SuperTokenssigninup. See Mobile: Auth, Navigation, Bootstrap. -
Legacy: Cognito and Firebase survive only as grace-window verifiers (
packages/auth/src/providers/legacy-cognito/, gated byAUTH_LEGACY_TOKEN_GRACE), so residual pre-cutover tokens don't hard-fail during the migration window.
ADR-0003 introduced a provider-neutral authentication boundary and made self-hosted SuperTokens the first adapter behind it:
- Route protection stops naming a vendor —
requireWebAuthreplacedauthorizeCognito. - Email/OTP (Cognito) and social (Firebase) sign-in migrated onto self-hosted SuperTokens in
apps/backend,apps/frontend, andapps/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)
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.
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.
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.
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).
Home · Architecture · ADRs · Plans · Roadmap · Contributing · Main repo · DeepWiki · Discord
Yosemite Crew is a product of DuneXploration UG (haftungsbeschränkt). This wiki mirrors the repository; where a page and the repo disagree, the repo wins. See the Wiki Style Guide.
Product & Domain
Architecture
Applications
- Backend — Overview
- Frontend / PIMS Web — Overview
- Mobile — Overview
- Desktop PIMS Shell
- Developer Portal
- SuperAdmin
Design & Accessibility
Engineering Handbook
Decisions (ADRs)
Design Docs & Plans
Meta
Canonical code & docs: main repo · Auto-generated companion: DeepWiki