@learncard/lca-api-service 1.3.2 → 1.4.0

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

@@ -0,0 +1,168 @@
+import { timingSafeEqual } from 'crypto';
+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,
+} from './types';
+
+export interface SoftwareEnclaveConfig {
+    privateKeys: Record<string, string>;
+    activeKeyId: string;
+}
+
+/** 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;
+
+    constructor(config: SoftwareEnclaveConfig) {
+        this.privateKeys = new Map(Object.entries(config.privateKeys));
+        this.activeKeyId = config.activeKeyId;
+        if (!this.privateKeys.has(this.activeKeyId)) throw new EscrowUnavailableError();
+    }
+
+    async getAttestation(): 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,
+                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. */
+    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
+            ),
+        };
+    }
+
+    async releaseEscrow(input: ReleaseRequest): Promise<ReleaseResult> {
+        const { hold } = input;
+        if (
+            hold.status !== 'pending' ||
+            input.clientEphemeralPublicKey !== hold.clientEphemeralPublicKey ||
+            !((input.now ?? new Date()).getTime() >= hold.releaseAfter.getTime())
+        ) {
+            throw new EscrowPolicyError();
+        }
+        const blob = await this.decrypt(input.envelope);
+        if (
+            blob.did !== input.expectedDid ||
+            blob.did !== hold.primaryDid ||
+            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._id,
+                    },
+                    input.clientEphemeralPublicKey
+                ),
+            };
+        } catch {
+            throw new EscrowBlobError();
+        }
+    }
+}

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

@@ -0,0 +1,76 @@
+import type { EscrowEnvelope } from '@learncard/sss-key-manager';
+import type { EscrowHold } from '../../models/EscrowHold';
+
+export interface EnclaveAttestation {
+    mode: 'software' | 'nitro';
+    keyId: string;
+    publicKey: string;
+    measurements: { imageSha384?: string; pcr0?: string; pcr1?: string; pcr2?: string };
+    document: string;
+    issuedAt: string;
+}
+export type EscrowHoldForEnclave = Pick<
+    EscrowHold,
+    | '_id'
+    | 'status'
+    | 'releaseAfter'
+    | 'releasePolicy'
+    | 'primaryDid'
+    | 'shareVersion'
+    | 'clientEphemeralPublicKey'
+>;
+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 {
+    envelope: EscrowEnvelope;
+    hold: EscrowHoldForEnclave;
+    clientEphemeralPublicKey: string;
+    expectedDid: string;
+    now?: Date;
+    pinProof?: string;
+}
+export interface ReleaseResult {
+    sealed: EscrowEnvelope;
+}
+export interface CarryPinVerifierInput {
+    sourceEnvelope: EscrowEnvelope;
+    targetEnvelope: EscrowEnvelope;
+    expectedDid: string;
+    sourceShareVersion: number;
+    targetShareVersion: number;
+}
+export interface EscrowEnclave {
+    getAttestation(): Promise<EnclaveAttestation>;
+    verifyEscrowBlob(input: VerifyEscrowBlobInput): Promise<VerifyEscrowBlobResult>;
+    carryPinVerifier(input: CarryPinVerifierInput): Promise<{ envelope: EscrowEnvelope }>;
+    releaseEscrow(input: ReleaseRequest): Promise<ReleaseResult>;
+}
+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;
+}

package/test/credentials.spec.ts

@@ -95,6 +95,8 @@ describe('Credentials', () => {
             })
         );
         expect(proof).toBeDefined();
+        const verification = await userA.learnCard.invoke.verifyCredential(signedVc);
+        expect(verification.errors).toHaveLength(0);
     });
 
     it('rejects an unresolvable encryption recipient as BAD_REQUEST', async () => {