@learncard/lca-api-service 1.3.2 → 1.5.0

package/src/services/escrow-enclave/softwareEnclave.ts

@@ -0,0 +1,254 @@
+import { timingSafeEqual } from 'crypto';
+import { escrowBlobIdentity } from './blobIdentity';
+import type { EnclaveCreateHoldInput, EscrowHoldRecord, CancelHoldRequest } from './types';
+import {
+    decryptEscrowBlob,
+    encryptEscrowBlob,
+    sealEscrowRelease,
+    parseEscrowEnvelope,
+    type EscrowBlobPlaintext,
+} from '@learncard/sss-key-manager';
+import {
+    EscrowBlobError,
+    EscrowPolicyError,
+    EscrowPinMismatchError,
+    EscrowUnavailableError,
+    type EscrowEnclave,
+    type EnclaveAttestation,
+    type VerifyEscrowBlobInput,
+    type VerifyEscrowBlobResult,
+    type ReleaseRequest,
+    type ReleaseResult,
+    type CarryPinVerifierInput,
+    type RewrapEscrowBlobInput,
+} from './types';
+
+export interface SoftwareEnclaveConfig {
+    privateKeys: Record<string, string>;
+    activeKeyId: string;
+    /** Supplied by the factory to match its configured host-trusted waiting period. */
+    holdDurationMs?: number;
+}
+
+/** In-process backend for development; host time is not an attested clock. */
+export class SoftwareEnclave implements EscrowEnclave {
+    private readonly privateKeys: ReadonlyMap<string, string>;
+    private readonly activeKeyId: string;
+    private readonly holdDurationMs: number;
+    constructor(config: SoftwareEnclaveConfig) {
+        this.privateKeys = new Map(Object.entries(config.privateKeys));
+        this.activeKeyId = config.activeKeyId;
+        if (!this.privateKeys.has(this.activeKeyId)) throw new EscrowUnavailableError();
+        // Match the factory configuration without a circular import; default is seven days.
+        this.holdDurationMs = config.holdDurationMs ?? 7 * 24 * 60 * 60 * 1000;
+    }
+    async createHold(input: EnclaveCreateHoldInput): Promise<{ holdRecord: EscrowHoldRecord }> {
+        const blob = await this.decrypt(input.envelope);
+        if (
+            blob.did !== input.expectedDid ||
+            blob.shareVersion !== input.expectedShareVersion ||
+            !Number.isInteger(input.enrollmentEpoch) ||
+            input.enrollmentEpoch <= 0 ||
+            (input.releasePolicy === 'pin' && !blob.pinVerifier)
+        )
+            throw new EscrowPolicyError();
+        const blobHash = escrowBlobIdentity(input.envelope);
+        const now = Date.now();
+        return {
+            holdRecord: {
+                hold: {
+                    holdId: input.holdId,
+                    did: blob.did,
+                    shareVersion: input.expectedShareVersion,
+                    blobHash,
+                    enrollmentEpoch: input.enrollmentEpoch,
+                    releasePolicy: input.releasePolicy,
+                    clientEphemeralPublicKey: input.clientEphemeralPublicKey,
+                    createdLo: now,
+                    createdHi: now,
+                    policyVersion: 1,
+                    // Non-cryptographic placeholder: software mode trusts the host entirely.
+                    signature: 'software-mode-unsigned',
+                },
+                holdDurationMs: input.releasePolicy === 'pin' ? 0 : this.holdDurationMs,
+                ledgerSeq: 0,
+            },
+        };
+    }
+    async cancelHold(input: CancelHoldRequest): Promise<void> {
+        const blob = await this.decrypt(input.envelope);
+        if (
+            blob.did !== input.expectedDid ||
+            blob.did !== input.hold.hold.did ||
+            input.clientEphemeralPublicKey !== input.hold.hold.clientEphemeralPublicKey
+        )
+            throw new EscrowPolicyError();
+        // Development only: Mongo owns cancellation; there is no software enclave ledger.
+    }
+    async getAttestation(_nonce?: Uint8Array): Promise<EnclaveAttestation> {
+        try {
+            const subtle = globalThis.crypto.subtle;
+            const key = await subtle.importKey(
+                'pkcs8',
+                new Uint8Array(Buffer.from(this.privateKeys.get(this.activeKeyId)!, 'base64')),
+                { name: 'ECDH', namedCurve: 'P-256' },
+                true,
+                ['deriveBits']
+            );
+            // WebCrypto cannot export a private CryptoKey as SPKI. Export its public
+            // coordinates as JWK, import a public-only key, then export that as SPKI.
+            const jwk = await subtle.exportKey('jwk', key);
+            const publicKeyObject = await subtle.importKey(
+                'jwk',
+                { kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y, ext: true },
+                { name: 'ECDH', namedCurve: 'P-256' },
+                true,
+                []
+            );
+            const publicKey = Buffer.from(await subtle.exportKey('spki', publicKeyObject)).toString(
+                'base64'
+            );
+            const description = {
+                mode: 'software' as const,
+                keyId: this.activeKeyId,
+                // P9.1 software-enclave equivalent: every OTHER configured key is
+                // already decrypt-eligible in `decrypt()` below (keyed lookup by
+                // envelope keyId, not restricted to `activeKeyId`) — this just
+                // advertises that existing behaviour the same way the Nitro
+                // backend advertises its `ESCROW_PREVIOUS_KEY_IDS`.
+                previousKeyIds: [...this.privateKeys.keys()].filter(id => id !== this.activeKeyId),
+                publicKey,
+                issuedAt: new Date().toISOString(),
+            };
+            return {
+                ...description,
+                measurements: {},
+                document: Buffer.from(JSON.stringify(description)).toString('base64'),
+            };
+        } catch {
+            throw new EscrowUnavailableError();
+        }
+    }
+
+    private async decrypt(envelope: unknown): Promise<EscrowBlobPlaintext> {
+        try {
+            const parsed = parseEscrowEnvelope(envelope);
+            const key = this.privateKeys.get(parsed.keyId);
+            if (!key) throw new EscrowBlobError();
+            return await decryptEscrowBlob(parsed, key);
+        } catch {
+            throw new EscrowBlobError();
+        }
+    }
+
+    async verifyEscrowBlob(input: VerifyEscrowBlobInput): Promise<VerifyEscrowBlobResult> {
+        const blob = await this.decrypt(input.envelope);
+        if (blob.did !== input.expectedDid || blob.shareVersion !== input.expectedShareVersion) {
+            return {
+                ok: false,
+                hasPin: !!blob.pinVerifier,
+                reason: 'Escrow recovery is not permitted.',
+            };
+        }
+        return { ok: true, hasPin: !!blob.pinVerifier };
+    }
+
+    /**
+     * Transfer only the verifier; recovery material remains sealed within the enclave.
+     *
+     * `input.sourceEnrollmentEpoch` is intentionally unused: software mode has no
+     * enclave ledger to reset in the first place, so there is no epoch-scoped PIN
+     * attempt budget to carry. The PIN attempt budget here is `escrowPin.failedAttempts`
+     * / `verifiedFailedAttempts` in MongoDB (see routes/escrow.ts), which the enroll
+     * route already copies forward unchanged on every carry, independent of
+     * `enrollmentEpoch` — so software mode never had the epoch-reset bug this field
+     * exists to fix in remote/nitro mode.
+     */
+    async carryPinVerifier(input: CarryPinVerifierInput) {
+        const source = await this.decrypt(input.sourceEnvelope);
+        const target = await this.decrypt(input.targetEnvelope);
+        if (
+            source.did !== input.expectedDid ||
+            target.did !== input.expectedDid ||
+            source.shareVersion !== input.sourceShareVersion ||
+            target.shareVersion !== input.targetShareVersion ||
+            target.shareVersion <= source.shareVersion ||
+            !source.pinVerifier ||
+            target.pinVerifier
+        )
+            throw new EscrowBlobError();
+        const attestation = await this.getAttestation();
+        return {
+            envelope: await encryptEscrowBlob(
+                { ...target, pinVerifier: source.pinVerifier },
+                attestation.publicKey,
+                attestation.keyId
+            ),
+        };
+    }
+
+    /**
+     * Software-mode equivalent of the Nitro enclave's `rewrap_escrow_blob`
+     * (P9.3): moves a blob sealed under any OTHER configured key onto the
+     * active key, unchanged otherwise. Mirrors its refusal shape — an
+     * envelope already under `activeKeyId` has nothing to migrate, and
+     * `decrypt()` already throws `EscrowBlobError` for a keyId this backend
+     * was never configured with, so both collapse into the same generic
+     * error. `sourceEnrollmentEpoch` is unused for the same reason
+     * `carryPinVerifier` ignores it above: no enclave ledger here, so no
+     * epoch-scoped PIN attempt budget to carry.
+     */
+    async rewrapEscrowBlob(input: RewrapEscrowBlobInput) {
+        const parsed = parseEscrowEnvelope(input.envelope);
+        if (parsed.keyId === this.activeKeyId) throw new EscrowBlobError();
+        const blob = await this.decrypt(input.envelope);
+        if (blob.did !== input.expectedDid || blob.shareVersion !== input.expectedShareVersion)
+            throw new EscrowBlobError();
+        const attestation = await this.getAttestation();
+        return {
+            envelope: await encryptEscrowBlob(blob, attestation.publicKey, attestation.keyId),
+        };
+    }
+
+    async releaseEscrow(input: ReleaseRequest): Promise<ReleaseResult> {
+        const { hold } = input.hold;
+        if (
+            input.clientEphemeralPublicKey !== hold.clientEphemeralPublicKey ||
+            !((input.now ?? new Date()).getTime() >= hold.createdHi + input.hold.holdDurationMs)
+        )
+            throw new EscrowPolicyError();
+        const blob = await this.decrypt(input.envelope);
+        if (
+            blob.did !== input.expectedDid ||
+            blob.did !== hold.did ||
+            blob.shareVersion !== hold.shareVersion
+        )
+            throw new EscrowPolicyError();
+        if (hold.releasePolicy === 'pin') {
+            if (!blob.pinVerifier || !input.pinProof) throw new EscrowPolicyError();
+            const expected = Buffer.from(blob.pinVerifier, 'hex');
+            const actual = Buffer.from(input.pinProof, 'hex');
+            if (
+                !/^[0-9a-f]{64}$/i.test(input.pinProof) ||
+                actual.length !== expected.length ||
+                !timingSafeEqual(actual, expected)
+            )
+                throw new EscrowPinMismatchError();
+        }
+        try {
+            return {
+                sealed: await sealEscrowRelease(
+                    {
+                        recoveryShare: blob.recoveryShare,
+                        did: blob.did,
+                        shareVersion: blob.shareVersion,
+                        holdId: hold.holdId,
+                    },
+                    input.clientEphemeralPublicKey
+                ),
+            };
+        } catch {
+            throw new EscrowBlobError();
+        }
+    }
+}

package/src/services/escrow-enclave/types.ts

@@ -0,0 +1,122 @@
+import type { EscrowEnvelope } from '@learncard/sss-key-manager';
+// Hold records are independent of host Mongo status and deadlines.
+
+export interface EnclaveAttestation {
+    mode: 'software' | 'nitro';
+    keyId: string;
+    /** P9.1: retired keyIds the enclave still accepts for decrypt only (never
+     * for sealing output). Empty/absent means no previous key is configured. */
+    previousKeyIds?: string[];
+    publicKey: string;
+    measurements: { imageSha384?: string; pcr0?: string; pcr1?: string; pcr2?: string };
+    document: string;
+    issuedAt: string;
+}
+export interface EscrowHoldRecord {
+    [key: string]: unknown;
+    hold: {
+        [key: string]: unknown;
+        holdId: string;
+        did: string;
+        shareVersion: number;
+        blobHash: string;
+        enrollmentEpoch: number;
+        releasePolicy: 'hold' | 'pin';
+        clientEphemeralPublicKey: string;
+        createdLo: number;
+        createdHi: number;
+        policyVersion: number;
+        signature: string;
+    };
+    holdDurationMs: number;
+    ledgerSeq: number;
+}
+export interface EnclaveCreateHoldInput {
+    envelope: EscrowEnvelope;
+    holdId: string;
+    expectedDid: string;
+    expectedShareVersion: number;
+    enrollmentEpoch: number;
+    releasePolicy: 'hold' | 'pin';
+    clientEphemeralPublicKey: string;
+}
+export interface CancelHoldRequest {
+    envelope: EscrowEnvelope;
+    hold: EscrowHoldRecord;
+    clientEphemeralPublicKey: string;
+    expectedDid: string;
+}
+export interface VerifyEscrowBlobInput {
+    envelope: EscrowEnvelope;
+    expectedDid: string;
+    expectedShareVersion: number;
+}
+export type VerifyEscrowBlobResult =
+    { ok: true; hasPin: boolean } | { ok: false; hasPin: boolean; reason: string };
+export interface ReleaseRequest extends CancelHoldRequest {
+    /** Development-only host clock; never forwarded by the remote backend. */
+    now?: Date;
+    pinProof?: string;
+}
+export interface ReleaseResult {
+    sealed: EscrowEnvelope;
+}
+export interface CarryPinVerifierInput {
+    sourceEnvelope: EscrowEnvelope;
+    targetEnvelope: EscrowEnvelope;
+    expectedDid: string;
+    sourceShareVersion: number;
+    targetShareVersion: number;
+    /** Signed source-record binding; blob hash, not epoch, selects the chain. */
+    sourceEnrollmentEpoch: number;
+    /** Signed binding for the output blob's first Carried record. */
+    targetEnrollmentEpoch: number;
+}
+export interface RewrapEscrowBlobInput {
+    envelope: EscrowEnvelope;
+    expectedDid: string;
+    expectedShareVersion: number;
+    /** Source and destination record binding. Rewrap preserves this epoch. */
+    sourceEnrollmentEpoch: number;
+}
+export interface EscrowEnclave {
+    /** `nonce` binds a nitro attestation to one client-generated challenge (64 hex chars,
+     * decoded to bytes); the software backend has no freshness story and ignores it. */
+    getAttestation(nonce?: Uint8Array): Promise<EnclaveAttestation>;
+    verifyEscrowBlob(input: VerifyEscrowBlobInput): Promise<VerifyEscrowBlobResult>;
+    carryPinVerifier(input: CarryPinVerifierInput): Promise<{ envelope: EscrowEnvelope }>;
+    /** P9.3: migrates a copy sealed under a recognised PREVIOUS key onto the
+     * CURRENT key (same did/shareVersion/recoveryShare/pinVerifier), so a
+     * previous key can eventually be retired. Refuses (generic
+     * `EscrowBlobError`) unless the envelope's own keyId is a recognised
+     * previous key — never the current key (nothing to migrate) or an
+     * unknown one. */
+    rewrapEscrowBlob(input: RewrapEscrowBlobInput): Promise<{ envelope: EscrowEnvelope }>;
+    releaseEscrow(input: ReleaseRequest): Promise<ReleaseResult>;
+    createHold(input: EnclaveCreateHoldInput): Promise<{ holdRecord: EscrowHoldRecord }>;
+    cancelHold(input: CancelHoldRequest): Promise<void>;
+}
+export class EscrowPolicyError extends Error {
+    constructor() {
+        super('Escrow recovery is not permitted.');
+        this.name = 'EscrowPolicyError';
+    }
+}
+export class EscrowPinMismatchError extends Error {
+    constructor() {
+        super('Incorrect PIN.');
+        this.name = 'EscrowPinMismatchError';
+    }
+}
+export class EscrowBlobError extends Error {
+    constructor() {
+        super('Invalid escrow payload.');
+        this.name = 'EscrowBlobError';
+    }
+}
+export class EscrowUnavailableError extends Error {
+    constructor() {
+        super('Escrow recovery is not available.');
+        this.name = 'EscrowUnavailableError';
+    }
+}

package/src/types/seed-encryption.ts

@@ -0,0 +1,51 @@
+export interface SigningAuthoritySeedIdentity {
+    _id: string;
+    ownerDid: string;
+    name: string;
+    did?: string;
+}
+
+export interface EncryptedSigningAuthoritySeed {
+    encryptedSeed: string;
+    encryptedDek: string;
+    keyVersion: 'kms-v1' | 'local-v1';
+}
+
+/** Untrusted persisted fields are validated before use, including on cache hits. */
+export interface SigningAuthoritySeedRecord {
+    _id?: unknown;
+    ownerDid: string;
+    name: string;
+    did?: string;
+    seed?: string;
+    encryptedSeed?: unknown;
+    encryptedDek?: unknown;
+    keyVersion?: unknown;
+}
+
+export interface SeedEncryptionConfig {
+    kmsKeyArn?: string;
+    localKek?: string;
+    allowLocal: boolean;
+}
+
+export interface SeedEncryption {
+    encrypt: (
+        seed: string,
+        identity: SigningAuthoritySeedIdentity
+    ) => Promise<EncryptedSigningAuthoritySeed>;
+    decrypt: (
+        envelope: EncryptedSigningAuthoritySeed,
+        identity: SigningAuthoritySeedIdentity
+    ) => Promise<string>;
+}
+
+export type SeedEncryptionFailure =
+    | 'invalid_record'
+    | 'invalid_envelope'
+    | 'configuration'
+    | 'legacy_disabled'
+    | 'authentication_failed'
+    | 'kms_access_denied'
+    | 'kms_unavailable'
+    | 'kms_failed';

package/src/types/seed-migration.ts

@@ -0,0 +1,61 @@
+import type { Document, ObjectId } from 'mongodb';
+import type { EncryptedSigningAuthoritySeed } from './seed-encryption';
+
+export type SeedMigrationPhase = 'dry-run' | 'prepare' | 'verify' | 'purge';
+
+export interface SeedMigrationRequest {
+    phase: SeedMigrationPhase;
+    batchSize?: number;
+}
+
+export interface SeedMigrationCounts {
+    total: number;
+    encrypted: number;
+    legacyOnly: number;
+    malformed: number;
+    plaintextRemaining: number;
+}
+
+export interface SeedMigrationResult {
+    phase: SeedMigrationPhase;
+    done: boolean;
+    processed: number;
+    counts: SeedMigrationCounts;
+    /** False for an intermediate batch: counts are the last full reconciliation snapshot. */
+    countsReconciled: boolean;
+    /** A final sweep found work inserted/changed behind the saved cursor. */
+    rescanRequired?: boolean;
+}
+
+/** Read the historical Mongo shape without coercing BSON IDs or changing metadata. */
+export interface MigrationSigningAuthority extends Document {
+    _id: string | ObjectId;
+    ownerDid: string;
+    name: string;
+    did?: string;
+    seed?: string;
+}
+
+export interface SeedMigrationState {
+    _id: string;
+    leaseOwner?: string;
+    leaseExpiresAt?: Date;
+    phase?: SeedMigrationPhase;
+    epoch?: string;
+    verifiedEpoch?: string;
+    status?: 'running' | 'complete' | 'failed';
+    processed?: number;
+    counts?: SeedMigrationCounts;
+    updatedAt?: Date;
+    /** Last processed BSON ID, scoped to phase/epoch; final reconciliation rechecks earlier IDs. */
+    cursor?: string | ObjectId;
+}
+
+/** Ciphertext-only receipt: exact comparisons make changed rows pending during the final sweep. */
+export interface SeedMigrationReceipt extends EncryptedSigningAuthoritySeed {
+    _id: string | ObjectId;
+    epoch: string;
+    ownerDid: string;
+    name: string;
+    did: string | null;
+}