@learncard/lca-api-service 1.4.0 → 1.5.0

package/src/helpers/rate-limit.helpers.ts

@@ -0,0 +1,73 @@
+import type { FastifyRequest } from 'fastify';
+
+import cache from '@cache';
+
+export const DEFAULT_MAX_FAILED_ATTEMPTS = 50;
+export const DEFAULT_RATE_LIMIT_WINDOW_SECONDS = 10 * 60;
+
+// Repair legacy counters during reads too: an already-blocked caller never reaches recordFailure.
+const READ_ATTEMPTS = `
+local attempts = redis.call('GET', KEYS[1])
+if attempts and redis.call('TTL', KEYS[1]) < 0 then
+    redis.call('EXPIRE', KEYS[1], ARGV[1])
+end
+return attempts
+`;
+
+const RECORD_FAILURE = `
+local attempts = redis.call('INCR', KEYS[1])
+if redis.call('TTL', KEYS[1]) < 0 then
+    redis.call('EXPIRE', KEYS[1], ARGV[1])
+end
+return attempts
+`;
+
+/**
+ * Failures-only rate limiting. Callers check `isRateLimited` up front and call
+ * `recordFailure` only on rejected attempts, so legitimate traffic behind a
+ * shared NAT never counts toward the ceiling. Increment and TTL repair run in
+ * one script without extending an existing window.
+ *
+ * Both halves fail open: if Redis is unreachable, reads return false and
+ * `recordFailure` logs and returns
+ * rather than turning a rejected login attempt into a 500. Limiting is a
+ * brute-force speed bump, not the access control — that is the ticket / code /
+ * client secret entropy.
+ */
+export const isRateLimited = async (
+    key: string,
+    max = DEFAULT_MAX_FAILED_ATTEMPTS
+): Promise<boolean> => {
+    const redis = cache.redis ?? cache.node;
+    try {
+        const attempts =
+            Number(await redis.eval(READ_ATTEMPTS, 1, key, DEFAULT_RATE_LIMIT_WINDOW_SECONDS)) || 0;
+        return attempts >= max;
+    } catch {
+        return false;
+    }
+};
+
+export const recordFailure = async (
+    key: string,
+    windowSeconds = DEFAULT_RATE_LIMIT_WINDOW_SECONDS
+): Promise<void> => {
+    const redis = cache.redis ?? cache.node;
+    try {
+        await redis.eval(RECORD_FAILURE, 1, key, windowSeconds);
+    } catch (error) {
+        console.error('Rate limit recordFailure error', error);
+    }
+};
+
+/**
+ * Client address for rate-limit keys.
+ *
+ * `request.ip` is the transport-level peer: under `serverless-http` it is API
+ * Gateway's `requestContext.http.sourceIp`, which the caller cannot forge. The
+ * `x-forwarded-for` header is NOT trusted — API Gateway appends the real source
+ * to whatever the client sent, so the first hop is attacker-controlled and would
+ * let anyone mint a fresh per-IP bucket per request.
+ */
+export const getRequestClientIp = (request: Pick<FastifyRequest, 'ip'>): string =>
+    request.ip || 'unknown';

package/src/helpers/social-token.helpers.ts

@@ -0,0 +1,144 @@
+/**
+ * Native Google / Apple `id_token` verification for the lca-api auth router
+ * (AD-2 / AD-3).
+ *
+ * The native app obtains an Apple/Google `id_token` through the platform SDK
+ * and posts it here. We verify it against the provider's published JWKS — exact
+ * issuer + audience (client id) allowlists, signature, `exp`/`nbf` — before
+ * issuing a login ticket. A test seam (`setSocialJwksResolverForTests`) swaps
+ * the remote JWKS for a local key set so the flow is unit-testable without
+ * network access.
+ */
+
+import { environment } from '@environment';
+import { TRPCError } from '@trpc/server';
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import type { JWTVerifyGetKey } from 'jose';
+import { z } from 'zod';
+
+export type SocialProviderId = 'google' | 'apple';
+
+export interface SocialProviderConfig {
+    issuers: string[];
+    audiences: string[];
+    jwksUri: string;
+}
+
+export interface SocialClaims {
+    sub: string;
+    iss: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    picture?: string;
+}
+
+const GOOGLE_DEFAULT_ISSUERS = ['https://accounts.google.com', 'accounts.google.com'];
+const GOOGLE_JWKS_URI = 'https://www.googleapis.com/oauth2/v3/certs';
+const APPLE_DEFAULT_ISSUERS = ['https://appleid.apple.com'];
+const APPLE_JWKS_URI = 'https://appleid.apple.com/auth/keys';
+
+const claimsSchema = z
+    .object({
+        sub: z.string().min(1),
+        iss: z.string().min(1),
+        email: z.string().min(1).optional(),
+        email_verified: z.union([z.boolean(), z.string()]).optional(),
+        name: z.string().optional(),
+        picture: z.string().optional(),
+    })
+    .passthrough();
+
+const splitCsv = (value: string | undefined): string[] =>
+    (value ?? '')
+        .split(',')
+        .map(entry => entry.trim())
+        .filter(Boolean);
+
+export const getSocialProviderConfig = (
+    provider: SocialProviderId
+): SocialProviderConfig | null => {
+    if (provider === 'google') {
+        const audiences = splitCsv(environment.GOOGLE_OAUTH_CLIENT_IDS);
+        if (audiences.length === 0) return null;
+        return {
+            audiences,
+            issuers: GOOGLE_DEFAULT_ISSUERS,
+            jwksUri: GOOGLE_JWKS_URI,
+        };
+    }
+
+    const audiences = splitCsv(environment.APPLE_OAUTH_CLIENT_IDS);
+    if (audiences.length === 0) return null;
+    return {
+        audiences,
+        issuers: APPLE_DEFAULT_ISSUERS,
+        jwksUri: APPLE_JWKS_URI,
+    };
+};
+
+const jwksByUri = new Map<string, JWTVerifyGetKey>();
+let resolverForTests: ((jwksUri: string) => JWTVerifyGetKey) | undefined;
+
+export const setSocialJwksResolverForTests = (
+    resolver: ((jwksUri: string) => JWTVerifyGetKey) | undefined
+): void => {
+    resolverForTests = resolver;
+    jwksByUri.clear();
+};
+
+export const getSocialJwks = (jwksUri: string): JWTVerifyGetKey => {
+    let jwks = jwksByUri.get(jwksUri);
+    if (!jwks) {
+        jwks = resolverForTests ? resolverForTests(jwksUri) : createRemoteJWKSet(new URL(jwksUri));
+        jwksByUri.set(jwksUri, jwks);
+    }
+    return jwks;
+};
+
+export const verifySocialIdToken = async (
+    provider: SocialProviderId,
+    token: string
+): Promise<SocialClaims> => {
+    const config = getSocialProviderConfig(provider);
+    if (!config) {
+        throw new TRPCError({
+            code: 'UNAUTHORIZED',
+            message: `Sign-in with ${provider} is not configured.`,
+        });
+    }
+
+    let payload: unknown;
+    try {
+        ({ payload } = await jwtVerify(token, getSocialJwks(config.jwksUri), {
+            issuer: config.issuers,
+            audience: config.audiences,
+            algorithms: ['RS256', 'ES256'],
+            requiredClaims: ['sub', 'exp', 'email', 'email_verified'],
+        }));
+    } catch {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid social token' });
+    }
+
+    const result = claimsSchema.safeParse(payload);
+    if (!result.success) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid social token' });
+    }
+
+    const claims = result.data;
+    const emailVerified =
+        claims.email_verified === true ||
+        (provider === 'apple' && claims.email_verified === 'true');
+    if (!claims.email || !emailVerified) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid social token' });
+    }
+
+    return {
+        sub: claims.sub,
+        iss: claims.iss,
+        email: claims.email,
+        email_verified: emailVerified,
+        name: claims.name,
+        picture: claims.picture,
+    };
+};

package/src/index.ts

@@ -2,4 +2,5 @@ export type { AppRouter } from './app';
 
 export { appRouter as mainApp } from './app';
 export { app as didApp } from './dids';
+export { app as oidcApp } from './oidc';
 export { app as swaggerApp } from './openapi';

package/src/jobs/escrowBlobRewrap.ts

@@ -0,0 +1,121 @@
+import {
+    findPendingEscrowHoldByAuthProvider,
+    findUserKeysWithEscrowBlobKeyId,
+    rewrapEscrowBlobByAuthProvider,
+} from '@models';
+import {
+    getEnclaveAttestationIdentity,
+    getEscrowEnclave,
+    isEscrowEnabled,
+} from '../services/escrow-enclave';
+
+const DEFAULT_REWRAP_BATCH_LIMIT = 200;
+
+export interface EscrowBlobRewrapResult {
+    rewrapped: number;
+    skippedPendingHold: number;
+    failed: number;
+}
+
+export interface RunEscrowBlobRewrapOptions {
+    limit?: number;
+}
+
+/**
+ * Deliberately drops the caught error's message, not just its stack: a real
+ * enclave/decrypt failure could embed plaintext or a proof in its own
+ * message text, so forwarding it here would leak secrets through the one
+ * logging path meant to report the failure. Mirrors
+ * `escrowHoldReminders.ts`'s `logJobError`, which makes the same trade-off
+ * for the same reason. `userKeyId` (a Mongo id, not a DID/email) is safe to
+ * log for triage.
+ */
+const logJobError = (userKeyId: string | undefined, error: unknown): void => {
+    console.error('[escrow-blob-rewrap] failed to process user key', {
+        userKeyId,
+        errorType: error instanceof Error ? error.name : typeof error,
+    });
+};
+
+/**
+ * Scheduled maintenance job (P9.3): migrates escrow blobs still sealed
+ * under a previous enclave key onto the current key, so that key can
+ * eventually be retired. Covers accounts that never sign in again after a
+ * key rotation — those already migrate client-side on next login via P9.2's
+ * carry-on-enroll path.
+ *
+ * No-ops when escrow is disabled for this stage/tenant, or when the
+ * enclave's current (cached) identity reports no previous keys at all —
+ * the common case once every previous key has been fully retired. Skips
+ * (does not touch) any account with a pending recovery hold: the signed
+ * hold record binds the OLD blob's hash/epoch, so re-sealing mid-hold would
+ * break an in-progress recovery; those accounts are simply re-tried on a
+ * later run once their hold resolves. Every write is an atomic
+ * compare-and-swap (`rewrapEscrowBlobByAuthProvider`); losing that race to a
+ * concurrent re-enroll/carry/opt-out is a silent no-op, not a failure.
+ */
+export const runEscrowBlobRewrap = async (
+    options: RunEscrowBlobRewrapOptions = {}
+): Promise<EscrowBlobRewrapResult> => {
+    const empty: EscrowBlobRewrapResult = { rewrapped: 0, skippedPendingHold: 0, failed: 0 };
+    if (!isEscrowEnabled()) return empty;
+
+    // Cheap, cache-aware gate: avoids a real enclave round trip on every
+    // run once there is nothing left to migrate (see services/escrow-enclave/
+    // index.ts's `getEnclaveAttestationIdentity`).
+    const identity = await getEnclaveAttestationIdentity().catch(() => undefined);
+    if (!identity || identity.previousKeyIds.length === 0) return empty;
+
+    const limit = options.limit ?? DEFAULT_REWRAP_BATCH_LIMIT;
+    const candidates = await findUserKeysWithEscrowBlobKeyId(identity.previousKeyIds, limit);
+    if (candidates.length === 0) return empty;
+
+    // A fresh, full attestation call (not just the cached identity) for the
+    // measurements the migrated blob must carry; only fetched once there is
+    // actually something to migrate this run.
+    const attestation = await getEscrowEnclave().getAttestation();
+
+    let rewrapped = 0;
+    let skippedPendingHold = 0;
+    let failed = 0;
+
+    for (const userKey of candidates) {
+        const blob = userKey.escrowBlob;
+        const authProvider = userKey.authProviders[0];
+        // Already migrated (by this loop's own attestation refresh landing
+        // mid-batch, or a concurrent run) since the candidate query ran.
+        if (!blob || !authProvider || blob.enclaveKeyId === attestation.keyId) continue;
+        try {
+            if (await findPendingEscrowHoldByAuthProvider(authProvider)) {
+                skippedPendingHold += 1;
+                continue;
+            }
+            const { envelope } = await getEscrowEnclave().rewrapEscrowBlob({
+                envelope: blob.envelope,
+                expectedDid: userKey.primaryDid,
+                expectedShareVersion: blob.shareVersion,
+                sourceEnrollmentEpoch: blob.enrollmentEpoch,
+            });
+            const stored = await rewrapEscrowBlobByAuthProvider(
+                authProvider,
+                blob,
+                userKey.escrowPin,
+                envelope,
+                {
+                    enclaveKeyId: attestation.keyId,
+                    enclaveMode: attestation.mode,
+                    measurements: attestation.measurements,
+                }
+            );
+            if (stored) rewrapped += 1;
+            // else: lost the compare-and-swap race (a concurrent re-enroll,
+            // PIN change or opt-out since this candidate was read) — not a
+            // failure, just re-tried on a later run if still applicable.
+        } catch (error) {
+            failed += 1;
+            logJobError(userKey._id, error);
+        }
+    }
+
+    return { rewrapped, skippedPendingHold, failed };
+};

package/src/jobs/escrowHoldReminders.ts

@@ -0,0 +1,177 @@
+import { resolveTenantFromRequest, type ResolvedTenant } from '@learncard/email-templates';
+import {
+    expireStaleEscrowHolds,
+    findEscrowHoldsPendingEnclaveCancellation,
+    countEscrowCancellationsNearRelease,
+    findEscrowHoldsDueForReminder,
+    claimEscrowHoldForReminder,
+    findUserKeyByAuthProvider,
+    findEscrowHoldsPendingStartNotification,
+    releaseEscrowReminderClaim,
+    recordEscrowStartNotificationAttempt,
+} from '@models';
+import { environment } from '@environment';
+import {
+    cancelHoldInEnclave,
+    logEscrowCancellationPending,
+} from '../services/escrow-enclave/cancellation';
+import { isEscrowEnabled, notifyEscrowHoldEvent } from '../services/escrow-enclave';
+
+// Two queues of ten 3-second deliveries leave half the 120-second Lambda
+// budget for database work. Least-recently-attempted ordering prevents starvation.
+const DEFAULT_REMINDER_BATCH_LIMIT = 10;
+
+export interface EscrowHoldReminderResult {
+    reminded: number;
+    expired: number;
+    failed: number;
+}
+
+export interface RunEscrowHoldRemindersOptions {
+    now?: Date;
+    limit?: number;
+    /**
+     * Test-only seam; defaults to the real `notifyEscrowHoldEvent`. Lets
+     * tests force a deterministic delivery failure without touching
+     * Postmark/FCM. Real callers (the Lambda handler) never pass this, so
+     * the effective public signature stays `{ now?, limit? }`.
+     */
+    notify?: typeof notifyEscrowHoldEvent;
+}
+
+/**
+ * Given a hold's stored `tenantId`, resolves the same `ResolvedTenant` shape
+ * route handlers get from `ctx.tenant`. A scheduled job has no request to
+ * read headers from, so this reuses `resolveTenantFromRequest`'s third
+ * resolution step directly (deploy-level id, same as `DEFAULT_TENANT_ID`)
+ * rather than duplicating the id → branding lookup it already does. Holds
+ * created before `tenantId` existed fall back to `DEFAULT_TENANT_ID` / the
+ * package's own 'learncard' default, exactly like any other unheadered call.
+ */
+const resolveTenantById = (tenantId: string | undefined): ResolvedTenant =>
+    resolveTenantFromRequest({}, tenantId);
+
+/**
+ * Deliberately drops the caught error's message, not just its stack: a real
+ * delivery-channel rejection (Postmark/FCM) can embed the recipient address
+ * in its own message text, so forwarding it here would leak PII through the
+ * one logging path meant to report the failure. Mirrors
+ * `notifications.ts`'s `logDeliveryFailure`, which makes the same trade-off
+ * for the same reason. The error's name/constructor is still useful for
+ * triage (e.g. "MongoServerError" vs "TypeError") without that risk.
+ */
+const logJobError = (holdId: string, error: unknown): void => {
+    console.error('[escrow-hold-reminders] failed to process hold', {
+        holdId,
+        errorType: error instanceof Error ? error.name : typeof error,
+    });
+};
+
+/**
+ * Hourly maintenance job: expires stale pending holds, then sends a T-24h
+ * `reminder` notification to every pending, hold-policy escrow hold whose
+ * waiting period ends within 24h and that has never been reminded.
+ *
+ * Escrow can be entirely disabled (no `ESCROW_ENCLAVE_MODE`) on a given
+ * stage/tenant deploy. Rather than a Serverless-level `schedule.enabled`
+ * conditional (its value must be a literal boolean, not an interpolated env
+ * string, so gating it from `${env:ESCROW_ENCLAVE_MODE}` is fragile), the
+ * schedule stays always-enabled in serverless.yml and this job no-ops
+ * instead — the same disabled/enabled signal the escrow router itself uses
+ * via `getEscrowEnclave()` throwing when `isEscrowEnabled()` is false.
+ */
+export const runEscrowHoldReminders = async (
+    options: RunEscrowHoldRemindersOptions = {}
+): Promise<EscrowHoldReminderResult> => {
+    const empty: EscrowHoldReminderResult = { reminded: 0, expired: 0, failed: 0 };
+    const now = options.now ?? new Date();
+    if (!isEscrowEnabled()) {
+        // Disabling recovery must not silence outstanding revocation alarms.
+        if (await countEscrowCancellationsNearRelease(now)) logEscrowCancellationPending(true);
+        return empty;
+    }
+    const limit = Math.max(
+        1,
+        Math.min(options.limit ?? DEFAULT_REMINDER_BATCH_LIMIT, DEFAULT_REMINDER_BATCH_LIMIT)
+    );
+    const notify = options.notify ?? notifyEscrowHoldEvent;
+
+    const expired = await expireStaleEscrowHolds(now);
+    const candidates = await findEscrowHoldsDueForReminder(now, limit);
+
+    let reminded = 0;
+    let failed = 0;
+
+    // Budget at most 30s of enclave calls beside the two 30s delivery queues.
+    // Attempts ordering ensures a repeatedly unavailable cancellation cannot starve others.
+    const cancelLimit = Math.min(
+        limit,
+        3,
+        Math.max(1, Math.floor(30_000 / environment.ESCROW_ENCLAVE_REMOTE_TIMEOUT_MS))
+    );
+    for (const hold of await findEscrowHoldsPendingEnclaveCancellation(cancelLimit)) {
+        try {
+            const userKey = hold.enclaveEnvelope
+                ? undefined
+                : await findUserKeyByAuthProvider(hold.authProvider.type, hold.authProvider.id);
+            if (!(await cancelHoldInEnclave(hold, userKey, now))) failed += 1;
+        } catch (error) {
+            failed += 1;
+            logJobError(hold._id, error);
+        }
+    }
+    // Check the whole backlog, not only this run's bounded retry batch.
+    if (await countEscrowCancellationsNearRelease(now)) logEscrowCancellationPending(true);
+
+    // A hold is inserted with this marker before the route attempts delivery,
+    // so Lambda freezes/timeouts cannot lose the security-critical start email.
+    for (const hold of await findEscrowHoldsPendingStartNotification(limit)) {
+        try {
+            await recordEscrowStartNotificationAttempt(hold._id, now);
+            const userKey = await findUserKeyByAuthProvider(
+                hold.authProvider.type,
+                hold.authProvider.id
+            );
+            if (
+                userKey &&
+                !(await notify({
+                    kind: 'started',
+                    hold,
+                    userKey,
+                    tenant: resolveTenantById(hold.tenantId),
+                }))
+            )
+                failed += 1;
+        } catch (error) {
+            failed += 1;
+            logJobError(hold._id, error);
+        }
+    }
+
+    for (const candidate of candidates) {
+        let claimed: Awaited<ReturnType<typeof claimEscrowHoldForReminder>> = null;
+        try {
+            // Lease before send; only successful delivery writes the sent marker.
+            claimed = await claimEscrowHoldForReminder(candidate._id, now);
+            if (!claimed) continue;
+
+            const userKey = await findUserKeyByAuthProvider(
+                claimed.authProvider.type,
+                claimed.authProvider.id
+            );
+            if (!userKey) continue;
+
+            const tenant = resolveTenantById(claimed.tenantId);
+
+            if (await notify({ kind: 'reminder', hold: claimed, userKey, tenant })) reminded += 1;
+            else failed += 1;
+        } catch (error) {
+            failed += 1;
+            logJobError(candidate._id, error);
+        } finally {
+            if (claimed) await releaseEscrowReminderClaim(claimed);
+        }
+    }
+
+    return { reminded, expired, failed };
+};

package/src/models/AuthSubject.ts

@@ -0,0 +1,147 @@
+import { randomUUID } from 'node:crypto';
+import type { Collection } from 'mongodb';
+import mongodb from '@mongo';
+
+export const AUTH_SUBJECTS_COLLECTION = 'authsubjects';
+
+export interface AuthSubjectAttributes {
+    email?: string;
+    emailVerified: boolean;
+    displayName?: string;
+    pictureUrl?: string;
+}
+
+export interface MongoAuthSubjectType extends AuthSubjectAttributes {
+    subject: string;
+    identityKey: string;
+    createdAt: Date;
+    lastLoginAt: Date;
+}
+
+export const getAuthSubjectsCollection = (): Collection<MongoAuthSubjectType> =>
+    mongodb.collection<MongoAuthSubjectType>(AUTH_SUBJECTS_COLLECTION);
+
+const MONGO_NAMESPACE_NOT_FOUND = 26;
+const MONGO_INDEX_NOT_FOUND = 27;
+
+const mongoErrorCode = (error: unknown): unknown =>
+    typeof error === 'object' && error !== null ? (error as { code?: unknown }).code : undefined;
+
+/**
+ * `identityKey` is unique: each sign-in method maps to exactly one subject.
+ * `subject` is deliberately NOT unique — linked sign-in methods for the same
+ * person (email code + native Google/Apple with the same verified email) share
+ * one subject, so Keycloak and the wallet see a single account. Databases
+ * created before linking existed carry a unique `subject` index; drop it.
+ */
+export const createAuthSubjectIndexes = async (): Promise<void> => {
+    const collection = getAuthSubjectsCollection();
+
+    const existing = await collection.indexes().catch(error => {
+        if (mongoErrorCode(error) === MONGO_NAMESPACE_NOT_FOUND) return [];
+        throw error;
+    });
+    const legacyUniqueSubject = existing.find(
+        index =>
+            index.unique === true && index.key?.subject === 1 && Object.keys(index.key).length === 1
+    );
+    if (legacyUniqueSubject?.name) {
+        await collection.dropIndex(legacyUniqueSubject.name).catch(error => {
+            if (mongoErrorCode(error) !== MONGO_INDEX_NOT_FOUND) throw error;
+        });
+    }
+
+    await collection.createIndex({ subject: 1 });
+    await collection.createIndex({ identityKey: 1 }, { unique: true });
+};
+
+let authSubjectIndexesReady: Promise<void> | undefined;
+
+/** Create the indexes once per process (startup in Docker, first login in Lambda). */
+export const ensureAuthSubjectIndexes = (): Promise<void> => {
+    if (!authSubjectIndexesReady) {
+        authSubjectIndexesReady = createAuthSubjectIndexes().catch(error => {
+            authSubjectIndexesReady = undefined;
+            console.error('Unable to create AuthSubject indexes:', error);
+            throw error;
+        });
+    }
+    return authSubjectIndexesReady;
+};
+
+const MONGO_DUPLICATE_KEY = 11000;
+
+const isDuplicateKeyError = (error: unknown): boolean =>
+    typeof error === 'object' &&
+    error !== null &&
+    (error as { code?: unknown }).code === MONGO_DUPLICATE_KEY;
+
+/**
+ * Shared upsert for both `getOrCreateAuthSubject` and `getOrCreateAuthSubjectLinkedTo`.
+ *
+ * Two concurrent first logins for the same identity can both miss the lookup
+ * and race on the insert; the unique `identityKey` index rejects the loser
+ * with E11000. Retrying once then finds the winner's document and only runs
+ * the `$set` half of the upsert. `subjectForInsert` only takes effect when this
+ * `identityKey` doesn't exist yet (`$setOnInsert`) — an existing record always
+ * keeps its own `subject`, regardless of what's passed here.
+ */
+const upsertAuthSubject = async (
+    identityKey: string,
+    subjectForInsert: string,
+    attrs: AuthSubjectAttributes
+): Promise<MongoAuthSubjectType> => {
+    await ensureAuthSubjectIndexes();
+    const now = new Date();
+    const fields: Partial<MongoAuthSubjectType> = {
+        lastLoginAt: now,
+        emailVerified: attrs.emailVerified,
+    };
+    if (attrs.email !== undefined) fields.email = attrs.email;
+    if (attrs.displayName !== undefined) fields.displayName = attrs.displayName;
+    if (attrs.pictureUrl !== undefined) fields.pictureUrl = attrs.pictureUrl;
+
+    const upsert = () =>
+        getAuthSubjectsCollection().findOneAndUpdate(
+            { identityKey },
+            {
+                $setOnInsert: { subject: subjectForInsert, identityKey, createdAt: now },
+                $set: fields,
+            },
+            { upsert: true, returnDocument: 'after' }
+        );
+
+    let record: MongoAuthSubjectType | null;
+    try {
+        record = await upsert();
+    } catch (error) {
+        if (!isDuplicateKeyError(error)) throw error;
+        record = await upsert();
+    }
+    if (!record) throw new Error('Unable to persist authentication subject');
+    return record;
+};
+
+/** Persist a random, permanent subject independently of Firebase and UserKey. */
+export const getOrCreateAuthSubject = (
+    identityKey: string,
+    attrs: AuthSubjectAttributes
+): Promise<MongoAuthSubjectType> => upsertAuthSubject(identityKey, randomUUID(), attrs);
+
+/**
+ * Same as `getOrCreateAuthSubject`, but a brand-new `identityKey` adopts the given
+ * `subject` instead of minting a random one — used to unify a native social sign-in
+ * onto an already-existing email-code identity for the same verified email. If
+ * `identityKey` already has its own record (e.g. this provider/sub was seen before),
+ * that record's existing `subject` is kept untouched; it is never overwritten.
+ */
+export const getOrCreateAuthSubjectLinkedTo = (
+    identityKey: string,
+    subject: string,
+    attrs: AuthSubjectAttributes
+): Promise<MongoAuthSubjectType> => upsertAuthSubject(identityKey, subject, attrs);
+
+/** Read-only lookup used to find an existing identity to link a new one to. */
+export const findAuthSubjectByIdentityKey = (
+    identityKey: string
+): Promise<MongoAuthSubjectType | null> => getAuthSubjectsCollection().findOne({ identityKey });