@learncard/lca-api-service 1.4.0 → 1.5.1

package/dist/routes/auth.d.ts

@@ -0,0 +1,31 @@
+export declare const authRouter: import("@trpc/server").TRPCBuiltRouter<{
+    ctx: import("@routes").Context;
+    meta: import("trpc-to-openapi").OpenApiMeta;
+    errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+    transformer: false;
+}, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
+    requestLoginTicket: import("@trpc/server").TRPCMutationProcedure<{
+        input: {
+            email: string;
+            code: string;
+        };
+        output: {
+            success: boolean;
+            ticket?: string | undefined;
+            error?: string | undefined;
+        };
+        meta: import("trpc-to-openapi").OpenApiMeta;
+    }>;
+    requestSocialLoginTicket: import("@trpc/server").TRPCMutationProcedure<{
+        input: {
+            provider: "google" | "apple";
+            idToken: string;
+        };
+        output: {
+            success: boolean;
+            ticket?: string | undefined;
+            error?: string | undefined;
+        };
+        meta: import("trpc-to-openapi").OpenApiMeta;
+    }>;
+}>>;

package/dist/routes/escrow.d.ts

@@ -1,11 +1,14 @@
+import { type Context } from '@routes';
 export declare const escrowRouter: import("@trpc/server").TRPCBuiltRouter<{
-    ctx: import("@routes").Context;
+    ctx: Context;
     meta: import("trpc-to-openapi").OpenApiMeta;
     errorShape: import("@trpc/server").TRPCDefaultErrorShape;
     transformer: false;
 }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
     getAttestation: import("@trpc/server").TRPCQueryProcedure<{
-        input: Record<string, never>;
+        input: {
+            nonce?: string | undefined;
+        };
         output: {
             attestation: {
                 mode: "software" | "nitro";
@@ -19,6 +22,7 @@ export declare const escrowRouter: import("@trpc/server").TRPCBuiltRouter<{
                 };
                 document: string;
                 issuedAt: string;
+                previousKeyIds?: string[] | undefined;
             };
             holdDurationMs: number;
         };
@@ -79,10 +83,10 @@ export declare const escrowRouter: import("@trpc/server").TRPCBuiltRouter<{
             recoverySessionToken?: string | undefined;
         };
         output: {
+            holdId: string;
+            releasePolicy: "pin" | "hold";
             requestedAt: string;
             releaseAfter: string;
-            releasePolicy: "pin" | "hold";
-            holdId: string;
             status: "pending";
             resumeToken: string | null;
             pinSalt?: string | undefined;
@@ -120,6 +124,16 @@ export declare const escrowRouter: import("@trpc/server").TRPCBuiltRouter<{
         };
         meta: import("trpc-to-openapi").OpenApiMeta;
     }>;
+    cancelRecoveryByLink: import("@trpc/server").TRPCMutationProcedure<{
+        input: {
+            holdId: string;
+            token: string;
+        };
+        output: {
+            cancelled: boolean;
+        };
+        meta: import("trpc-to-openapi").OpenApiMeta;
+    }>;
     completeRecovery: import("@trpc/server").TRPCMutationProcedure<{
         input: {
             holdId: string;

package/dist/routes/keys.d.ts

@@ -153,6 +153,7 @@ export declare const keysRouter: import("@trpc/server").TRPCBuiltRouter<{
                 salt?: string | undefined;
             };
             sssActivationState: "provisional" | "active";
+            escrowStale?: "mode-mismatch" | "key-rotated" | undefined;
         } | null;
         meta: import("trpc-to-openapi").OpenApiMeta;
     }>;

package/dist/routes/notifications.d.ts

@@ -207,6 +207,11 @@ export declare const notificationsRouter: import("@trpc/server").TRPCBuiltRouter
                         approvedAt: string;
                         contractUpdatedAt: string;
                     } | undefined;
+                    referral?: {
+                        requestId: string;
+                        requestedBy: string;
+                        externalReferenceId?: string | undefined;
+                    } | undefined;
                     uris?: string[] | undefined;
                 } | undefined;
                 inbox?: {

package/dist/routes/signing-authority.d.ts

@@ -18,6 +18,20 @@ export declare const signingAuthorityRouter: import("@trpc/server").TRPCBuiltRou
         };
         meta: import("trpc-to-openapi").OpenApiMeta;
     }>;
+    ensureManagedSigningAuthority: import("@trpc/server").TRPCMutationProcedure<{
+        input: {
+            name: string;
+            ownerDid: string;
+        };
+        output: {
+            ownerDid: string;
+            name: string;
+            did: string;
+            endpoint: string;
+            _id?: string | undefined;
+        };
+        meta: import("trpc-to-openapi").OpenApiMeta;
+    }>;
     signingAuthorities: import("@trpc/server").TRPCQueryProcedure<{
         input: void;
         output: {

package/dist/services/escrow-enclave/blobIdentity.d.ts

@@ -0,0 +1,10 @@
+export interface EscrowEnvelopeFields {
+    version: number;
+    algorithm: string;
+    keyId: string;
+    ephemeralPublicKey: string;
+    salt: string;
+    iv: string;
+    ciphertext: string;
+}
+export declare const escrowBlobIdentity: (envelope: EscrowEnvelopeFields) => string;

package/dist/services/escrow-enclave/blobIdentity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/escrow-enclave/cancellation.d.ts

@@ -0,0 +1,3 @@
+import { type EscrowHold, type MongoUserKeyType } from '@models';
+export declare const logEscrowCancellationPending: (urgent: boolean) => void;
+export declare const cancelHoldInEnclave: (hold: EscrowHold, userKey?: MongoUserKeyType | null, now?: Date) => Promise<boolean>;

package/dist/services/escrow-enclave/enclaveTrustAnchors.d.ts

@@ -0,0 +1 @@
+export declare const pinnedEnclaveCa: (baseUrl: string) => string | undefined;

package/dist/services/escrow-enclave/index.d.ts

@@ -1,9 +1,25 @@
+import type { EscrowBlobStaleReason } from '@learncard/types';
 import { type EscrowEnclave } from './types';
 export * from './types';
 export * from './softwareEnclave';
+export * from './remoteEnclave';
 export * from './notifications';
 export declare const isEscrowEnabled: () => boolean;
+export declare const isEscrowRemoteMode: () => boolean;
+export declare const activeEscrowClientMode: () => "software" | "nitro";
 export declare const getEscrowHoldDurationMs: () => number;
 export declare const getEscrowHoldRestartMinAgeMs: () => number;
 export declare const getEscrowEnclave: () => EscrowEnclave;
+export type { EscrowBlobStaleReason };
+interface EscrowAttestationIdentity {
+    keyId: string;
+    previousKeyIds: string[];
+    mode: 'software' | 'nitro';
+}
+export declare const getEnclaveAttestationIdentity: () => Promise<EscrowAttestationIdentity>;
+export declare const getEscrowBlobStaleReason: (blob: {
+    enclaveMode: "software" | "nitro";
+    enclaveKeyId: string;
+}) => Promise<EscrowBlobStaleReason | undefined>;
 export declare const __setEscrowEnclaveForTests: (replacement: EscrowEnclave | undefined) => void;
+export declare const __resetEscrowAttestationCacheForTests: () => void;

package/dist/services/escrow-enclave/notifications.d.ts

@@ -1,9 +1,24 @@
-import type { EscrowHold } from '../../models/EscrowHold';
-import type { MongoUserKeyType } from '../../models/UserKey';
+import type { ResolvedTenant } from '@learncard/email-templates';
+import type { EscrowHold, MongoUserKeyType } from '@models';
+import { type DeliveryService } from '../delivery';
+export type EscrowHoldEventKind = 'started' | 'reminder' | 'completed' | 'cancelled' | 'pin-locked';
 export interface EscrowHoldEvent {
-    kind: 'started' | 'cancelled' | 'completed';
+    kind: EscrowHoldEventKind;
     hold: EscrowHold;
     userKey: MongoUserKeyType;
     reason?: 'superseded';
+    cancelToken?: string;
+    tenant?: ResolvedTenant;
+    activeHold?: EscrowHold;
 }
-export declare const notifyEscrowHoldEvent: (event: EscrowHoldEvent) => Promise<void>;
+type SendPushNotification = typeof import('@helpers/pushNotifications.helpers').sendPushNotification;
+export interface EscrowHoldNotifierDeps {
+    send: DeliveryService['send'];
+    sendPush: SendPushNotification;
+    now: () => Date;
+    rotateCancelToken: (holdId: string) => Promise<string | null>;
+    recordNotification: (holdId: string, kind: EscrowHoldEventKind) => Promise<void>;
+}
+export declare const ESCROW_NOTIFICATION_TIMEOUT_MS = 3000;
+export declare const notifyEscrowHoldEvent: (event: EscrowHoldEvent, overrides?: Partial<EscrowHoldNotifierDeps>) => Promise<boolean>;
+export {};

package/dist/services/escrow-enclave/notifications.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/escrow-enclave/production.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/escrow-enclave/remoteEnclave.contract.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/escrow-enclave/remoteEnclave.d.ts

@@ -0,0 +1,20 @@
+import { type EscrowEnclave } from './types';
+export interface RemoteEnclaveTransportResponse {
+    status: number;
+    data: unknown;
+}
+export interface RemoteEnclaveTransport {
+    post(url: string, body: unknown, config: {
+        headers: Record<string, string>;
+        timeout: number;
+    }): Promise<RemoteEnclaveTransportResponse>;
+}
+export declare const createHttpTransport: (caPem?: string) => RemoteEnclaveTransport;
+export interface RemoteEnclaveConfig {
+    baseUrl: string;
+    token: string;
+    timeoutMs: number;
+    caPem?: string;
+    transport?: RemoteEnclaveTransport;
+}
+export declare const createRemoteEnclave: (config: RemoteEnclaveConfig) => EscrowEnclave;

package/dist/services/escrow-enclave/remoteEnclave.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/escrow-enclave/remoteEnclave.tls.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/escrow-enclave/softwareEnclave.d.ts

@@ -1,17 +1,27 @@
-import { type EscrowEnclave, type EnclaveAttestation, type VerifyEscrowBlobInput, type VerifyEscrowBlobResult, type ReleaseRequest, type ReleaseResult, type CarryPinVerifierInput } from './types';
+import type { EnclaveCreateHoldInput, EscrowHoldRecord, CancelHoldRequest } from './types';
+import { 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;
+    holdDurationMs?: number;
 }
 export declare class SoftwareEnclave implements EscrowEnclave {
     private readonly privateKeys;
     private readonly activeKeyId;
+    private readonly holdDurationMs;
     constructor(config: SoftwareEnclaveConfig);
-    getAttestation(): Promise<EnclaveAttestation>;
+    createHold(input: EnclaveCreateHoldInput): Promise<{
+        holdRecord: EscrowHoldRecord;
+    }>;
+    cancelHold(input: CancelHoldRequest): Promise<void>;
+    getAttestation(_nonce?: Uint8Array): Promise<EnclaveAttestation>;
     private decrypt;
     verifyEscrowBlob(input: VerifyEscrowBlobInput): Promise<VerifyEscrowBlobResult>;
     carryPinVerifier(input: CarryPinVerifierInput): Promise<{
         envelope: import("@learncard/sss-key-manager").EscrowEnvelope;
     }>;
+    rewrapEscrowBlob(input: RewrapEscrowBlobInput): Promise<{
+        envelope: import("@learncard/sss-key-manager").EscrowEnvelope;
+    }>;
     releaseEscrow(input: ReleaseRequest): Promise<ReleaseResult>;
 }

package/dist/services/escrow-enclave/types.d.ts

@@ -1,8 +1,8 @@
 import type { EscrowEnvelope } from '@learncard/sss-key-manager';
-import type { EscrowHold } from '../../models/EscrowHold';
 export interface EnclaveAttestation {
     mode: 'software' | 'nitro';
     keyId: string;
+    previousKeyIds?: string[];
     publicKey: string;
     measurements: {
         imageSha384?: string;
@@ -13,7 +13,40 @@ export interface EnclaveAttestation {
     document: string;
     issuedAt: string;
 }
-export type EscrowHoldForEnclave = Pick<EscrowHold, '_id' | 'status' | 'releaseAfter' | 'releasePolicy' | 'primaryDid' | 'shareVersion' | 'clientEphemeralPublicKey'>;
+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;
@@ -27,11 +60,7 @@ export type VerifyEscrowBlobResult = {
     hasPin: boolean;
     reason: string;
 };
-export interface ReleaseRequest {
-    envelope: EscrowEnvelope;
-    hold: EscrowHoldForEnclave;
-    clientEphemeralPublicKey: string;
-    expectedDid: string;
+export interface ReleaseRequest extends CancelHoldRequest {
     now?: Date;
     pinProof?: string;
 }
@@ -44,14 +73,29 @@ export interface CarryPinVerifierInput {
     expectedDid: string;
     sourceShareVersion: number;
     targetShareVersion: number;
+    sourceEnrollmentEpoch: number;
+    targetEnrollmentEpoch: number;
+}
+export interface RewrapEscrowBlobInput {
+    envelope: EscrowEnvelope;
+    expectedDid: string;
+    expectedShareVersion: number;
+    sourceEnrollmentEpoch: number;
 }
 export interface EscrowEnclave {
-    getAttestation(): Promise<EnclaveAttestation>;
+    getAttestation(nonce?: Uint8Array): Promise<EnclaveAttestation>;
     verifyEscrowBlob(input: VerifyEscrowBlobInput): Promise<VerifyEscrowBlobResult>;
     carryPinVerifier(input: CarryPinVerifierInput): Promise<{
         envelope: EscrowEnvelope;
     }>;
+    rewrapEscrowBlob(input: RewrapEscrowBlobInput): Promise<{
+        envelope: EscrowEnvelope;
+    }>;
     releaseEscrow(input: ReleaseRequest): Promise<ReleaseResult>;
+    createHold(input: EnclaveCreateHoldInput): Promise<{
+        holdRecord: EscrowHoldRecord;
+    }>;
+    cancelHold(input: CancelHoldRequest): Promise<void>;
 }
 export declare class EscrowPolicyError extends Error {
     constructor();

package/dist/types/notifications.d.ts

@@ -237,6 +237,11 @@ export declare const PaginatedNotificationsValidator: z.ZodObject<{
                     approvedAt: z.ZodString;
                     contractUpdatedAt: z.ZodString;
                 }, z.core.$strip>>;
+                referral: z.ZodOptional<z.ZodObject<{
+                    requestId: z.ZodString;
+                    requestedBy: z.ZodString;
+                    externalReferenceId: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
                 id: z.ZodString;
                 action: z.ZodEnum<{
                     write: "write";

package/esbuildPlugins.cjs

@@ -41,6 +41,7 @@ module.exports = [
     forceCjsSodiumWrapperPlugin,
     copyDidkitWasmPlugin,
     sentryEsbuildPlugin({
+        telemetry: process.env.SENTRY_BUILD_TELEMETRY !== 'false',
         authToken: process.env.SENTRY_AUTH_TOKEN,
         org: process.env.SENTRY_ORG,
         project: process.env.SENTRY_PROJECT,

package/lambda.ts

@@ -1,128 +1,38 @@
-import serverlessHttp from 'serverless-http';
-import type { Context, APIGatewayProxyResultV2, APIGatewayProxyEventV2 } from 'aws-lambda';
-import { awsLambdaRequestHandler } from '@trpc/server/adapters/aws-lambda';
-import * as Sentry from '@sentry/serverless';
+import { bootstrapLambda } from '@learncard/service-config';
 
-import app from './src/openapi';
-import didWebApp from './src/dids';
-import { appRouter, createContext } from './src/app';
-import { getEmptyLearnCard } from './src/helpers/learnCard.helpers';
-import { createOpenApiAwsLambdaHandler } from './src/helpers/shim';
-import {
-    handleTrpcError,
-    sentryBeforeSend,
-    getTracesSampleRate,
-} from './src/helpers/sentry.helpers';
-import { environment } from './src/config/environment';
-import { toServerlessApplication } from './src/helpers/serverlessApplication';
-import { ensureUserKeysIndexes, createEscrowHoldsIndexes } from './src/models';
+import { base, stages } from './src/config/stageConfig';
 
-const startupPromise = Promise.all([
-    getEmptyLearnCard(), // Load WASM in for better cold starts
-    ensureUserKeysIndexes(),
-    createEscrowHoldsIndexes(),
-]);
+type LambdaApp = typeof import('./lambdaApp');
 
-const isWarmupEvent = (event: APIGatewayProxyEventV2): boolean =>
-    'source' in event && event.source === 'serverless-plugin-warmup';
-
-Sentry.AWSLambda.init({
-    dsn: environment.SENTRY_DSN,
-    environment: environment.SENTRY_ENV,
-    enabled: Boolean(environment.SENTRY_DSN),
-    tracesSampleRate: getTracesSampleRate(),
-    beforeSend: sentryBeforeSend,
-    integrations: [
-        new Sentry.Integrations.Console(),
-        new Sentry.Integrations.Http({ tracing: true }),
-        new Sentry.Integrations.ContextLines(),
-        new Sentry.Integrations.Mongo(),
-    ],
-});
-
-export const swaggerUiHandler = serverlessHttp(toServerlessApplication(app), {
-    basePath: '/docs',
-});
-export const didWebHandler = serverlessHttp(toServerlessApplication(didWebApp));
-
-export const _openApiHandler = createOpenApiAwsLambdaHandler({
-    router: appRouter,
-    responseMeta: () => {
-        return {
-            headers: {
-                'Access-Control-Allow-Origin': '*',
-                'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
-                'Access-Control-Allow-Headers': 'Authorization, Content-Type',
-            },
-        };
-    },
-    createContext,
-    onError: handleTrpcError,
-});
-
-export const _trpcHandler = awsLambdaRequestHandler({
-    router: appRouter,
-    createContext,
-    onError: handleTrpcError,
-    responseMeta: () => {
-        return {
-            headers: {
-                'Access-Control-Allow-Origin': '*',
-                'Access-Control-Allow-Methods': '*',
-                'Access-Control-Allow-Headers': 'authorization',
-            },
-        };
-    },
+const getApplication = bootstrapLambda<LambdaApp>({
+    base,
+    stages,
+    stage: process.env.AWS_LAMBDA_FUNCTION_NAME
+        ? process.env.LAMBDA_STAGE
+        : process.env.CONFIG_STAGE,
+    importApp: () => import('./lambdaApp'),
 });
 
-export const openApiHandler = Sentry.AWSLambda.wrapHandler(
-    async (event: APIGatewayProxyEventV2, context: Context): Promise<APIGatewayProxyResultV2> => {
-        await startupPromise;
-
-        if (isWarmupEvent(event)) {
-            console.log('[Warmup] Initializing LearnCard...');
-            await getEmptyLearnCard();
-            console.log('[Warmup] Done!');
-            return 'All done! 😄';
-        }
+export const trpcHandler = async (...args: Parameters<LambdaApp['trpcHandler']>) =>
+    (await getApplication()).trpcHandler(...args);
 
-        if (event.requestContext.http.method === 'OPTIONS') {
-            return {
-                statusCode: 200,
-                headers: {
-                    'Access-Control-Allow-Origin': '*',
-                    'Access-Control-Allow-Headers': '*',
-                    'Access-Control-Allow-Methods': '*',
-                },
-            };
-        }
+export const openApiHandler = async (...args: Parameters<LambdaApp['openApiHandler']>) =>
+    (await getApplication()).openApiHandler(...args);
 
-        return _openApiHandler(event, context);
-    }
-);
+export const swaggerUiHandler = async (...args: Parameters<LambdaApp['swaggerUiHandler']>) =>
+    (await getApplication()).swaggerUiHandler(...args);
 
-export const trpcHandler = Sentry.AWSLambda.wrapHandler(
-    async (event: APIGatewayProxyEventV2, context: Context): Promise<APIGatewayProxyResultV2> => {
-        await startupPromise;
+export const didWebHandler = async (...args: Parameters<LambdaApp['didWebHandler']>) =>
+    (await getApplication()).didWebHandler(...args);
 
-        if (isWarmupEvent(event)) {
-            console.log('[Warmup] Initializing LearnCard...');
-            await getEmptyLearnCard();
-            console.log('[Warmup] Done!');
-            return 'All done! 😄';
-        }
+// Preserve the local/offline handler name without importing the full API for OIDC.
+export { handler as oidcHandler } from './oidcLambda';
 
-        if (event.requestContext.http.method === 'OPTIONS') {
-            return {
-                statusCode: 200,
-                headers: {
-                    'Access-Control-Allow-Origin': '*',
-                    'Access-Control-Allow-Headers': '*',
-                    'Access-Control-Allow-Methods': '*',
-                },
-            };
-        }
+// Scheduled (EventBridge) escrow jobs share the API bootstrap: they need Mongo/Postmark from the bundle.
+export const escrowHoldRemindersHandler = async (
+    ...args: Parameters<LambdaApp['escrowHoldRemindersHandler']>
+) => (await getApplication()).escrowHoldRemindersHandler(...args);
 
-        return _trpcHandler(event, context);
-    }
-);
+export const escrowBlobRewrapHandler = async (
+    ...args: Parameters<LambdaApp['escrowBlobRewrapHandler']>
+) => (await getApplication()).escrowBlobRewrapHandler(...args);