@learncard/lca-api-service 1.3.1 → 1.4.0

package/src/models/EscrowHold.ts

@@ -0,0 +1,225 @@
+import { createHash, randomBytes, randomUUID } from 'crypto';
+import { z } from 'zod';
+import type { Collection } from 'mongodb';
+import mongodb from '@mongo';
+import { environment } from '@environment';
+import { AuthProviderMappingValidator, type AuthProviderMapping } from './UserKey';
+
+export const ESCROW_HOLDS_COLLECTION = 'escrowholds';
+export const ESCROW_HOLD_STALE_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+export const ESCROW_HOLD_RESTART_MIN_AGE_MS = environment.ESCROW_HOLD_RESTART_MIN_AGE_MS;
+export const EscrowHoldValidator = z.object({
+    _id: z.string().uuid(),
+    authProvider: AuthProviderMappingValidator,
+    primaryDid: z.string(),
+    shareVersion: z.number().int().positive(),
+    status: z.enum(['pending', 'cancelled', 'completed', 'expired']),
+    identityProofType: z.enum(['auth-token', 'recovery-session']),
+    requestedAt: z.date(),
+    releaseAfter: z.date(),
+    releasePolicy: z.enum(['hold', 'pin']).default('hold'),
+    cancelReason: z.enum(['pin-mismatch', 'pin-locked', 'superseded', 'release-failed']).optional(),
+    cancelledAt: z.date().optional(),
+    cancelledBy: z.enum(['did', 'system']).optional(),
+    completedAt: z.date().optional(),
+    clientEphemeralPublicKey: z.string().min(1).max(512),
+    resumeTokenHash: z.string().regex(/^[0-9a-f]{64}$/),
+    notifications: z
+        .array(
+            z.object({
+                kind: z.enum(['started', 'cancelled', 'completed']),
+                sentAt: z.date(),
+            })
+        )
+        .default([]),
+    requestIp: z.string().optional(),
+    createdAt: z.date(),
+    updatedAt: z.date(),
+});
+export type EscrowHold = z.infer<typeof EscrowHoldValidator>;
+export type CreateEscrowHoldInput = Omit<
+    z.input<typeof EscrowHoldValidator>,
+    | '_id'
+    | 'status'
+    | 'createdAt'
+    | 'updatedAt'
+    | 'notifications'
+    | 'cancelledAt'
+    | 'cancelledBy'
+    | 'completedAt'
+    | 'cancelReason'
+>;
+
+export const getEscrowHoldsCollection = (): Collection<EscrowHold> =>
+    mongodb.collection<EscrowHold>(ESCROW_HOLDS_COLLECTION);
+
+const runIndexMigrationOperation = async (operation: () => Promise<unknown>): Promise<void> => {
+    try {
+        await operation();
+    } catch (error) {
+        const code =
+            typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
+        // Unlike lookup indexes, uniqueness is a security invariant: fail closed on duplicates.
+        if (code === 27 || code === 85 || code === 86) {
+            const indexes = await getEscrowHoldsCollection().listIndexes().toArray();
+            if (
+                indexes.some(
+                    index =>
+                        index.unique &&
+                        Object.keys(index.key ?? {}).length === 3 &&
+                        index.key?.['authProvider.type'] === 1 &&
+                        index.key?.['authProvider.id'] === 1 &&
+                        index.key?.releasePolicy === 1 &&
+                        Object.keys(index.partialFilterExpression ?? {}).length === 1 &&
+                        index.partialFilterExpression?.status === 'pending'
+                )
+            )
+                return;
+        }
+        throw new Error('Escrow hold index initialization failed', { cause: error });
+    }
+};
+
+export const createEscrowHoldsIndexes = async (): Promise<void> => {
+    const collection = getEscrowHoldsCollection();
+    // Normalize legacy rows while the old, stricter index still protects them.
+    await collection.updateMany(
+        { releasePolicy: { $exists: false } },
+        { $set: { releasePolicy: 'hold' } }
+    );
+    await runIndexMigrationOperation(() =>
+        collection.createIndex(
+            { 'authProvider.type': 1, 'authProvider.id': 1, releasePolicy: 1 },
+            {
+                name: 'pending_escrow_identity_policy_unique',
+                unique: true,
+                partialFilterExpression: { status: 'pending' },
+            }
+        )
+    );
+    // Install the replacement before dropping the old index: no uniqueness gap.
+    try {
+        await collection.dropIndex('pending_escrow_identity_unique');
+    } catch (error) {
+        if (!(typeof error === 'object' && error !== null && 'code' in error && error.code === 27))
+            throw error;
+    }
+    await runIndexMigrationOperation(() =>
+        collection.createIndex({ 'authProvider.type': 1, 'authProvider.id': 1, status: 1 })
+    );
+    await runIndexMigrationOperation(() => collection.createIndex({ releaseAfter: 1 }));
+};
+
+export const createEscrowHold = async (input: CreateEscrowHoldInput): Promise<EscrowHold> => {
+    const now = new Date();
+    const parsed = EscrowHoldValidator.safeParse({
+        ...input,
+        _id: randomUUID(),
+        status: 'pending',
+        notifications: [],
+        createdAt: now,
+        updatedAt: now,
+    });
+    if (!parsed.success) throw new Error('Invalid escrow hold');
+    const hold = parsed.data;
+    await getEscrowHoldsCollection().insertOne(hold);
+    return hold;
+};
+export const findPendingEscrowHoldByAuthProvider = async (
+    authProvider: AuthProviderMapping,
+    releasePolicy?: EscrowHold['releasePolicy']
+): Promise<EscrowHold | null> =>
+    getEscrowHoldsCollection().findOne({
+        'authProvider.type': authProvider.type,
+        'authProvider.id': authProvider.id,
+        status: 'pending',
+        ...(releasePolicy === 'hold'
+            ? { $or: [{ releasePolicy: 'hold' as const }, { releasePolicy: { $exists: false } }] }
+            : releasePolicy
+              ? { releasePolicy }
+              : {}),
+    });
+export const findEscrowHoldById = async (id: string): Promise<EscrowHold | null> =>
+    getEscrowHoldsCollection().findOne({ _id: id });
+export const cancelEscrowHold = async (
+    id: string,
+    cancelledBy: 'did' | 'system',
+    cancelReason?: EscrowHold['cancelReason']
+): Promise<EscrowHold | null> => {
+    const now = new Date();
+    return getEscrowHoldsCollection().findOneAndUpdate(
+        { _id: id, status: 'pending' },
+        {
+            $set: {
+                status: 'cancelled',
+                cancelledBy,
+                cancelledAt: now,
+                updatedAt: now,
+                ...(cancelReason ? { cancelReason } : {}),
+            },
+        },
+        { returnDocument: 'after' }
+    );
+};
+export const completeEscrowHold = async (id: string): Promise<EscrowHold | null> => {
+    const now = new Date();
+    return getEscrowHoldsCollection().findOneAndUpdate(
+        {
+            _id: id,
+            status: 'pending',
+            releaseAfter: { $gte: new Date(now.getTime() - ESCROW_HOLD_STALE_WINDOW_MS) },
+        },
+        {
+            $set: { status: 'completed', completedAt: now, updatedAt: now },
+        },
+        { returnDocument: 'after' }
+    );
+};
+/** Whether escrow material at this share version has already been released. */
+export const hasCompletedEscrowHoldForVersion = async (
+    authProvider: AuthProviderMapping,
+    shareVersion: number
+): Promise<boolean> =>
+    (await getEscrowHoldsCollection().countDocuments(
+        {
+            'authProvider.type': authProvider.type,
+            'authProvider.id': authProvider.id,
+            shareVersion,
+            status: 'completed',
+        },
+        { limit: 1 }
+    )) > 0;
+export const expireStaleEscrowHolds = async (now: Date): Promise<number> => {
+    const result = await getEscrowHoldsCollection().updateMany(
+        {
+            status: 'pending',
+            releaseAfter: { $lt: new Date(now.getTime() - ESCROW_HOLD_STALE_WINDOW_MS) },
+        },
+        { $set: { status: 'expired', updatedAt: now } }
+    );
+    return result.modifiedCount;
+};
+
+/** Only rewrite the completed row claimed by this request; never reopen a burned hold. */
+export const markClaimedEscrowHoldFailed = async (
+    id: string,
+    reason: 'pin-mismatch' | 'pin-locked' | 'release-failed',
+    completedAt: Date
+): Promise<void> => {
+    const now = new Date();
+    await getEscrowHoldsCollection().updateOne(
+        { _id: id, status: 'completed', completedAt },
+        {
+            $set: {
+                status: 'cancelled',
+                cancelledBy: 'system',
+                cancelReason: reason,
+                cancelledAt: now,
+                updatedAt: now,
+            },
+        }
+    );
+};
+export const hashEscrowResumeToken = (token: string): string =>
+    createHash('sha256').update(token).digest('hex');
+export const generateEscrowResumeToken = (): string => randomBytes(32).toString('hex');

package/src/models/SigningAuthority.ts

@@ -2,17 +2,28 @@ import { z } from 'zod';
 
 export const SIGNING_AUTHORITIES_COLLECTION = 'signingauthorities';
 
+/**
+ * Encrypted seeds authenticate _id, ownerDid, name, and did (including an absent did).
+ * Never rename/backfill these fields in place: decrypt using the ORIGINAL identity, then
+ * re-encrypt for the new identity and atomically replace the metadata and envelope together.
+ */
 export const MongoSigningAuthorityValidator = z.object({
     _id: z.string().optional(),
     ownerDid: z.string(),
     name: z.string(),
-    seed: z.string(),
+    // Legacy and prepared migration rows only. New writes use the envelope fields.
+    seed: z.string().optional(),
+    encryptedSeed: z.string().optional(),
+    encryptedDek: z.string().optional(),
+    keyVersion: z.enum(['kms-v1', 'local-v1']).optional(),
     did: z.string().optional(),
     endpoint: z.string().optional(),
 });
 
-export const SigningAuthorityResponseValidator = MongoSigningAuthorityValidator.omit({
-    seed: true,
+export const SigningAuthorityResponseValidator = MongoSigningAuthorityValidator.pick({
+    _id: true,
+    ownerDid: true,
+    name: true,
 }).extend({
     did: z.string(),
     endpoint: z.string(),

package/src/models/UserKey.escrowPin.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getEscrowPinStatus, type MongoUserKeyType } from './UserKey';
+
+vi.mock('@mongo', () => ({ default: {} }));
+
+describe('getEscrowPinStatus', () => {
+    it('distinguishes an absent PIN from lockout', () => {
+        const userKey = { shareVersion: 1 } as MongoUserKeyType;
+        expect(getEscrowPinStatus(userKey)).toEqual({
+            state: 'none',
+            enabled: false,
+            attemptsRemaining: 0,
+        });
+    });
+
+    it.each(['locked', 'stale'] as const)('reports %s without exposing salt', state => {
+        const userKey = {
+            shareVersion: 1,
+            escrowPin: {
+                salt: 'salt',
+                shareVersion: state === 'stale' ? 2 : 1,
+                failedAttempts: 0,
+                enabledAt: new Date(),
+                ...(state === 'locked' ? { disabledAt: new Date() } : {}),
+            },
+        } as MongoUserKeyType;
+        expect(getEscrowPinStatus(userKey)).toEqual({
+            state,
+            enabled: false,
+            attemptsRemaining: 10,
+        });
+    });
+
+    it.each([0, 9, 10, 11])(
+        'does not label reservations as verified lockout (%i reserved)',
+        failedAttempts => {
+            const userKey = {
+                shareVersion: 1,
+                escrowPin: { salt: 'salt', shareVersion: 1, failedAttempts, enabledAt: new Date() },
+            } as MongoUserKeyType;
+            expect(getEscrowPinStatus(userKey)).toEqual({
+                state: 'enabled',
+                enabled: true,
+                attemptsRemaining: Math.max(0, 10 - failedAttempts),
+                salt: 'salt',
+            });
+        }
+    );
+});