@learncard/lca-api-service 1.3.2 → 1.5.0

package/src/helpers/seedEncryption.helpers.ts

@@ -0,0 +1,372 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+import { DecryptCommand, GenerateDataKeyCommand, KMSClient } from '@aws-sdk/client-kms';
+import { MongoServerError } from 'mongodb';
+
+import { environment } from '@environment';
+import type {
+    EncryptedSigningAuthoritySeed,
+    SeedEncryptionConfig,
+    SeedEncryption,
+    SeedEncryptionFailure,
+    SigningAuthoritySeedIdentity,
+    SigningAuthoritySeedRecord,
+} from 'types/seed-encryption';
+
+export const SA_SEED_ENCRYPTION_PURPOSE = 'lca-signing-authority-seed';
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+const KEY_LENGTH = 32;
+const SEED_PATTERN = /^[a-fA-F0-9]{64}$/;
+// Error names are mutable and may contain secrets; only emit known diagnostic names.
+const SAFE_ERROR_NAMES = new Set([
+    'Error',
+    'TypeError',
+    'RangeError',
+    'ReferenceError',
+    'SyntaxError',
+    'URIError',
+    'EvalError',
+    'AggregateError',
+    'RuntimeError',
+    'CompileError',
+    'LinkError',
+    'MongoError',
+    'MongoNetworkError',
+    'MongoNetworkTimeoutError',
+    'MongoServerSelectionError',
+    'MongoOperationTimeoutError',
+    'MongoNotConnectedError',
+    'MongoTopologyClosedError',
+]);
+
+/** Deliberately contains no original exception/cause: SDK and Mongo errors can carry secrets. */
+export class SeedEncryptionError extends Error {
+    constructor(
+        public readonly category: SeedEncryptionFailure,
+        public readonly awsRequestId?: string
+    ) {
+        super('Signing authority key is unavailable.');
+        this.name = 'SeedEncryptionError';
+    }
+}
+
+const getKmsFailureCategory = (name?: string): SeedEncryptionFailure => {
+    switch (name) {
+        case 'AccessDeniedException':
+            return 'kms_access_denied';
+        case 'InvalidCiphertextException':
+            return 'authentication_failed';
+        case 'TimeoutError':
+        case 'DependencyTimeoutException':
+        case 'ThrottlingException':
+        case 'KMSInternalException':
+        case 'KeyUnavailableException':
+        case 'DisabledException':
+            return 'kms_unavailable';
+        default:
+            return 'kms_failed';
+    }
+};
+
+const kmsFailure = (error: unknown): SeedEncryptionError => {
+    const failure = error as { name?: string; $metadata?: { requestId?: string } } | undefined;
+    const requestId = failure?.$metadata?.requestId;
+    const safeRequestId = requestId && /^[\w-]{1,128}$/.test(requestId) ? requestId : undefined;
+    const category = getKmsFailureCategory(failure?.name);
+    return new SeedEncryptionError(category, safeRequestId);
+};
+
+/** Log only an allowlist of metadata; never pass the original error or document to a logger. */
+export const logSeedEncryptionFailure = (
+    error: unknown,
+    operation: string,
+    record?: { _id?: unknown; keyVersion?: unknown }
+): void => {
+    console.error({
+        event: 'signing_authority_seed_failure',
+        operation,
+        recordId: record?._id?.toString(),
+        keyVersion: ['kms-v1', 'local-v1'].includes(String(record?.keyVersion))
+            ? record?.keyVersion
+            : 'unknown',
+        category: error instanceof SeedEncryptionError ? error.category : 'operation_failed',
+        awsRequestId: error instanceof SeedEncryptionError ? error.awsRequestId : undefined,
+        ...(error instanceof Error && SAFE_ERROR_NAMES.has(error.name)
+            ? { errorName: error.name }
+            : {}),
+        // Mongo messages/keyValue can contain the duplicate document or seed. Only log
+        // the known error class and numeric server code (e.g. 11000 for duplicate keys).
+        ...(error instanceof MongoServerError
+            ? {
+                  errorName: 'MongoServerError',
+                  mongoCode: Number.isInteger(error.code) ? error.code : undefined,
+              }
+            : {}),
+    });
+};
+
+export const getSeedIdentity = (record: {
+    _id?: unknown;
+    ownerDid: string;
+    name: string;
+    did?: string;
+}): SigningAuthoritySeedIdentity => {
+    if (
+        !record._id ||
+        typeof record.ownerDid !== 'string' ||
+        typeof record.name !== 'string' ||
+        (record.did !== undefined && typeof record.did !== 'string')
+    ) {
+        throw new SeedEncryptionError('invalid_record');
+    }
+    return {
+        _id: String(record._id),
+        ownerDid: record.ownerDid,
+        name: record.name,
+        did: record.did,
+    };
+};
+
+const getContext = (
+    identity: SigningAuthoritySeedIdentity,
+    keyVersion: string
+): Record<string, string> => ({
+    purpose: SA_SEED_ENCRYPTION_PURPOSE,
+    recordId: identity._id,
+    identity: createHash('sha256')
+        .update(JSON.stringify([identity.ownerDid, identity.name, identity.did ?? null]))
+        .digest('hex'),
+    keyVersion,
+});
+
+const decodeBase64 = (encoded: string, minimum: number): Buffer => {
+    const bytes = Buffer.from(encoded, 'base64');
+    if (bytes.length < minimum || bytes.toString('base64') !== encoded) {
+        throw new SeedEncryptionError('invalid_envelope');
+    }
+    return bytes;
+};
+
+const seal = (plaintext: Buffer, key: Buffer, aad: Buffer): string => {
+    const iv = randomBytes(IV_LENGTH);
+    const cipher = createCipheriv('aes-256-gcm', key, iv, { authTagLength: TAG_LENGTH });
+    cipher.setAAD(aad);
+    return Buffer.concat([
+        iv,
+        cipher.update(plaintext),
+        cipher.final(),
+        cipher.getAuthTag(),
+    ]).toString('base64');
+};
+
+const open = (encoded: string, key: Buffer, aad: Buffer): Buffer => {
+    const bytes = decodeBase64(encoded, IV_LENGTH + TAG_LENGTH + 1);
+    let plaintextChunk: Buffer | undefined;
+    let finalChunk: Buffer | undefined;
+    try {
+        const decipher = createDecipheriv('aes-256-gcm', key, bytes.subarray(0, IV_LENGTH), {
+            authTagLength: TAG_LENGTH,
+        });
+        decipher.setAAD(aad);
+        decipher.setAuthTag(bytes.subarray(-TAG_LENGTH));
+        plaintextChunk = decipher.update(bytes.subarray(IV_LENGTH, -TAG_LENGTH));
+        finalChunk = decipher.final();
+        return Buffer.concat([plaintextChunk, finalChunk]);
+    } catch {
+        throw new SeedEncryptionError('authentication_failed');
+    } finally {
+        // The caller clears the returned copy; clear the originals even when final() rejects the tag.
+        plaintextChunk?.fill(0);
+        finalChunk?.fill(0);
+    }
+};
+
+/** Absence means legacy only when ALL envelope fields are absent. Never downgrade corrupt envelopes. */
+export const parseSeedEnvelope = (record: object): EncryptedSigningAuthoritySeed | undefined => {
+    const value = record as Partial<EncryptedSigningAuthoritySeed>;
+    if (!('keyVersion' in record) && !('encryptedSeed' in record) && !('encryptedDek' in record)) {
+        return undefined;
+    }
+    if (
+        (value.keyVersion !== 'kms-v1' && value.keyVersion !== 'local-v1') ||
+        typeof value.encryptedSeed !== 'string' ||
+        typeof value.encryptedDek !== 'string'
+    ) {
+        throw new SeedEncryptionError('invalid_envelope');
+    }
+    decodeBase64(value.encryptedSeed, IV_LENGTH + TAG_LENGTH + 1);
+    decodeBase64(value.encryptedDek, 1);
+    // Never return the source document: migration rows may still contain the plaintext seed.
+    return {
+        encryptedSeed: value.encryptedSeed,
+        encryptedDek: value.encryptedDek,
+        keyVersion: value.keyVersion,
+    };
+};
+
+/**
+ * KMS takes precedence for new writes. Reads dispatch by envelope version and require the
+ * original provider's key; KMS failures never trigger a local or plaintext fallback.
+ */
+export const createSeedEncryption = (
+    config: SeedEncryptionConfig,
+    kms?: KMSClient
+): SeedEncryption => {
+    const keyVersion = config.kmsKeyArn ? 'kms-v1' : 'local-v1';
+    let client = kms;
+    const getClient = (): KMSClient => {
+        // Recover transient failures on cache misses without relying on issuance callers to retry.
+        // Keep each attempt bounded by the existing connection/request timeouts.
+        client ??= new KMSClient({
+            maxAttempts: 3,
+            retryMode: 'standard',
+            requestHandler: {
+                connectionTimeout: 2_000,
+                requestTimeout: 5_000,
+                throwOnRequestTimeout: true,
+            },
+        });
+        return client;
+    };
+    const getLocalKek = (): Buffer => {
+        if (!config.allowLocal || !config.localKek || !SEED_PATTERN.test(config.localKek)) {
+            throw new SeedEncryptionError('configuration');
+        }
+        return Buffer.from(config.localKek, 'hex');
+    };
+
+    const encrypt = async (
+        seed: string,
+        identity: SigningAuthoritySeedIdentity
+    ): Promise<EncryptedSigningAuthoritySeed> => {
+        if (!SEED_PATTERN.test(seed)) throw new SeedEncryptionError('invalid_record');
+        const context = getContext(identity, keyVersion);
+        const aad = Buffer.from(JSON.stringify(context));
+        const plaintext = Buffer.from(seed, 'utf8');
+        let dek: Buffer | undefined;
+        let kmsPlaintext: Uint8Array | undefined;
+        let kek: Buffer | undefined;
+        try {
+            let encryptedDek: string;
+            if (config.kmsKeyArn) {
+                const result = await getClient()
+                    .send(
+                        new GenerateDataKeyCommand({
+                            KeyId: config.kmsKeyArn,
+                            KeySpec: 'AES_256',
+                            EncryptionContext: context,
+                        })
+                    )
+                    .catch(error => {
+                        throw kmsFailure(error);
+                    });
+                kmsPlaintext = result.Plaintext;
+                if (
+                    kmsPlaintext?.length !== KEY_LENGTH ||
+                    !result.CiphertextBlob?.length ||
+                    result.KeyId !== config.kmsKeyArn
+                ) {
+                    throw new SeedEncryptionError('kms_failed');
+                }
+                dek = Buffer.from(kmsPlaintext);
+                encryptedDek = Buffer.from(result.CiphertextBlob).toString('base64');
+            } else {
+                kek = getLocalKek();
+                dek = randomBytes(KEY_LENGTH);
+                encryptedDek = seal(dek, kek, Buffer.concat([aad, Buffer.from('/dek')]));
+            }
+            return { encryptedSeed: seal(plaintext, dek, aad), encryptedDek, keyVersion };
+        } finally {
+            plaintext.fill(0);
+            dek?.fill(0);
+            kmsPlaintext?.fill(0);
+            kek?.fill(0);
+        }
+    };
+
+    const decrypt = async (
+        envelope: EncryptedSigningAuthoritySeed,
+        identity: SigningAuthoritySeedIdentity
+    ): Promise<string> => {
+        parseSeedEnvelope(envelope);
+        const context = getContext(identity, envelope.keyVersion);
+        const aad = Buffer.from(JSON.stringify(context));
+        let dek: Buffer | undefined;
+        let kmsPlaintext: Uint8Array | undefined;
+        let plaintext: Buffer | undefined;
+        let kek: Buffer | undefined;
+        try {
+            if (envelope.keyVersion === 'kms-v1') {
+                if (!config.kmsKeyArn) throw new SeedEncryptionError('configuration');
+                const result = await getClient()
+                    .send(
+                        new DecryptCommand({
+                            KeyId: config.kmsKeyArn,
+                            CiphertextBlob: decodeBase64(envelope.encryptedDek, 1),
+                            EncryptionContext: context,
+                            EncryptionAlgorithm: 'SYMMETRIC_DEFAULT',
+                        })
+                    )
+                    .catch(error => {
+                        throw kmsFailure(error);
+                    });
+                kmsPlaintext = result.Plaintext;
+                if (kmsPlaintext?.length !== KEY_LENGTH || result.KeyId !== config.kmsKeyArn) {
+                    throw new SeedEncryptionError('kms_failed');
+                }
+                dek = Buffer.from(kmsPlaintext);
+            } else {
+                kek = getLocalKek();
+                dek = open(envelope.encryptedDek, kek, Buffer.concat([aad, Buffer.from('/dek')]));
+                if (dek.length !== KEY_LENGTH) throw new SeedEncryptionError('invalid_envelope');
+            }
+            plaintext = open(envelope.encryptedSeed, dek, aad);
+            const seed = plaintext.toString('utf8');
+            if (!SEED_PATTERN.test(seed)) throw new SeedEncryptionError('invalid_record');
+            return seed;
+        } finally {
+            dek?.fill(0);
+            kmsPlaintext?.fill(0);
+            plaintext?.fill(0);
+            kek?.fill(0);
+        }
+    };
+    return { encrypt, decrypt };
+};
+
+export const seedEncryption = createSeedEncryption({
+    kmsKeyArn: environment.SA_SEED_KMS_KEY_ARN,
+    localKek: environment.SA_SEED_LOCAL_KEK,
+    allowLocal: environment.IS_OFFLINE || environment.NODE_ENV === 'test',
+});
+
+/** Temporary dual reader; remove the legacy branch after the verified production migration. */
+export const decryptSigningAuthoritySeed = async (
+    record: SigningAuthoritySeedRecord
+): Promise<string> => {
+    const envelope = parseSeedEnvelope(record);
+    if (envelope) return seedEncryption.decrypt(envelope, getSeedIdentity(record));
+    if (!environment.SA_SEED_ALLOW_LEGACY_READ) throw new SeedEncryptionError('legacy_disabled');
+    if (!record.seed || !SEED_PATTERN.test(record.seed))
+        throw new SeedEncryptionError('invalid_record');
+    return record.seed;
+};
+
+/** Non-secret cache fingerprint. Hash legacy seeds only during the compatibility window. */
+export const getSeedCacheFingerprint = (record: SigningAuthoritySeedRecord): string => {
+    const envelope = parseSeedEnvelope(record);
+    if (!envelope && !environment.SA_SEED_ALLOW_LEGACY_READ) {
+        throw new SeedEncryptionError('legacy_disabled');
+    }
+    return createHash('sha256')
+        .update(
+            JSON.stringify([
+                String(record._id),
+                record.ownerDid,
+                record.name,
+                record.did,
+                envelope ?? record.seed,
+            ])
+        )
+        .digest('hex');
+};

package/src/helpers/signingAuthority.helpers.ts

@@ -12,7 +12,10 @@ export const getSigningAuthorityWithEndpoint = (
     domainName: string
 ): SigningAuthorityResponseType => {
     return {
-        ...signingAuthority,
+        _id: signingAuthority._id,
+        name: signingAuthority.name,
+        ownerDid: signingAuthority.ownerDid,
+        did: signingAuthority.did,
         endpoint: getEndpoint(domainName),
     };
 };

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 };
+};