@learncard/lca-api-service 1.3.2 → 1.5.0

package/src/helpers/auth.helpers.ts

@@ -5,6 +5,16 @@
 import { environment } from '@environment';
 import { TRPCError } from '@trpc/server';
 import admin from 'firebase-admin';
+import { z } from 'zod';
+import { getKeycloakVerifyOptionsFromEnv, verifyKeycloakJwt } from './keycloak.helpers';
+
+const offlineFirebaseClaimsSchema = z.object({
+    sub: z.string().optional(),
+    uid: z.string().optional(),
+    user_id: z.string().optional(),
+    email: z.string().nullish(),
+    phone_number: z.string().nullish(),
+});
 
 export interface VerifiedUser {
     id: string;
@@ -15,31 +25,35 @@ export interface VerifiedUser {
 
 export type AuthProviderType = 'firebase' | 'supertokens' | 'keycloak' | 'oidc';
 
+const parseOfflineFirebaseClaims = (
+    token: string
+): z.infer<typeof offlineFirebaseClaimsSchema> | undefined => {
+    const payloadPart = token.split('.')[1];
+    if (!payloadPart) return undefined;
+    try {
+        const decoded: unknown = JSON.parse(Buffer.from(payloadPart, 'base64url').toString());
+        return offlineFirebaseClaimsSchema.parse(decoded);
+    } catch {
+        return undefined;
+    }
+};
+
 export async function verifyFirebaseToken(token: string): Promise<VerifiedUser> {
     // E2E test or offline bypass - parse JWT without Firebase Admin verification
     if (environment.IS_E2E_TEST || environment.IS_OFFLINE) {
-        try {
-            const parts = token.split('.');
-            const payloadPart = parts[1];
-            if (parts.length >= 2 && payloadPart) {
-                // Try base64url first, then regular base64
-                let payload;
-                try {
-                    payload = JSON.parse(Buffer.from(payloadPart, 'base64url').toString());
-                } catch {
-                    payload = JSON.parse(Buffer.from(payloadPart, 'base64').toString());
-                }
-                return {
-                    id: payload.sub || payload.uid || payload.user_id || 'offline-user',
-                    email: payload.email,
-                    phone: payload.phone_number,
-                    providerType: 'firebase',
-                };
-            }
-        } catch (e) {
-            console.warn('Failed to parse JWT in offline mode:', e);
-            // Fall through to normal verification
+        const payload = parseOfflineFirebaseClaims(token);
+        if (payload) {
+            return {
+                id: payload.sub || payload.uid || payload.user_id || 'offline-user',
+                email: payload.email ?? undefined,
+                phone: payload.phone_number ?? undefined,
+                providerType: 'firebase',
+            };
         }
+        throw new TRPCError({
+            code: 'UNAUTHORIZED',
+            message: 'Could not decode Firebase token in offline/E2E mode',
+        });
     }
 
     try {
@@ -52,7 +66,7 @@ export async function verifyFirebaseToken(token: string): Promise<VerifiedUser>
             providerType: 'firebase',
         };
     } catch (error) {
-        console.error('Firebase token verification failed:', error);
+        console.warn('Firebase token verification failed:', error);
         throw new TRPCError({
             code: 'UNAUTHORIZED',
             message: 'Invalid Firebase token',
@@ -70,14 +84,38 @@ export async function verifySuperTokensToken(_token: string): Promise<VerifiedUs
     });
 }
 
-export async function verifyKeycloakToken(_token: string): Promise<VerifiedUser> {
-    // Keycloak verification would go here
-    // This would use the existing verifyKeycloakToken from firebase.helpers.ts
-    // but return a VerifiedUser instead of creating a Firebase user
-    throw new TRPCError({
-        code: 'NOT_IMPLEMENTED',
-        message: 'Keycloak verification not yet implemented for SSS',
-    });
+export async function verifyKeycloakToken(token: string): Promise<VerifiedUser> {
+    const options = getKeycloakVerifyOptionsFromEnv();
+    if (!options) {
+        throw new TRPCError({
+            code: 'UNAUTHORIZED',
+            message: 'Keycloak verification is not configured',
+        });
+    }
+    let claims;
+    try {
+        claims = await verifyKeycloakJwt(token, options);
+    } catch {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid Keycloak token' });
+    }
+    if (claims.email !== undefined && claims.email_verified !== true) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Email address is not verified' });
+    }
+    if (claims.phone_number !== undefined && claims.phone_number_verified !== true) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Phone number is not verified' });
+    }
+    if (!claims.email && !claims.phone_number) {
+        throw new TRPCError({
+            code: 'UNAUTHORIZED',
+            message: 'Token has no verified contact method',
+        });
+    }
+    return {
+        id: claims.sub,
+        email: claims.email,
+        phone: claims.phone_number,
+        providerType: 'keycloak',
+    };
 }
 
 export async function verifyOidcToken(_token: string): Promise<VerifiedUser> {

package/src/helpers/escrowCancelLink.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildEscrowCancelUrl, resolveEscrowAppBaseUrl } from './escrowCancelLink';
+
+describe('buildEscrowCancelUrl', () => {
+    const holdId = '5b1f6e2e-6e2a-4e8a-9e2a-6e2a4e8a9e2a';
+    const token = 'a'.repeat(64);
+
+    it('builds the expected path and query', () => {
+        expect(buildEscrowCancelUrl({ baseUrl: 'https://learncard.app', holdId, token })).toBe(
+            `https://learncard.app/recovery/cancel?holdId=${holdId}&token=${token}`
+        );
+    });
+
+    it('never doubles the slash when baseUrl has a trailing slash', () => {
+        expect(buildEscrowCancelUrl({ baseUrl: 'https://learncard.app/', holdId, token })).toBe(
+            `https://learncard.app/recovery/cancel?holdId=${holdId}&token=${token}`
+        );
+    });
+
+    it('percent-encodes query values that need it', () => {
+        const url = buildEscrowCancelUrl({
+            baseUrl: 'https://learncard.app',
+            holdId: 'weird id/with&chars',
+            token,
+        });
+        expect(url).toBe(
+            `https://learncard.app/recovery/cancel?holdId=weird+id%2Fwith%26chars&token=${token}`
+        );
+        expect(new URL(url).searchParams.get('holdId')).toBe('weird id/with&chars');
+    });
+
+    it('ignores any path segment already present on baseUrl (host + protocol only, matching every tenant appUrl in the registry)', () => {
+        expect(buildEscrowCancelUrl({ baseUrl: 'https://vetpass.app', holdId, token })).toBe(
+            `https://vetpass.app/recovery/cancel?holdId=${holdId}&token=${token}`
+        );
+    });
+});
+
+describe('resolveEscrowAppBaseUrl', () => {
+    it('falls back to the LearnCard default when the tenant has no appUrl override', () => {
+        expect(
+            resolveEscrowAppBaseUrl({
+                tenant: { id: 'learncard', emailBranding: {}, resolvedVia: 'default' },
+            })
+        ).toBe('https://learncard.app');
+    });
+
+    it('prefers the resolved tenant appUrl', () => {
+        expect(
+            resolveEscrowAppBaseUrl({
+                tenant: {
+                    id: 'vetpass',
+                    emailBranding: { appUrl: 'https://vetpass.app' },
+                    resolvedVia: 'origin',
+                },
+            })
+        ).toBe('https://vetpass.app');
+    });
+});

package/src/helpers/escrowCancelLink.ts

@@ -0,0 +1,38 @@
+/**
+ * Escrow recovery cancel-link deep-link builder.
+ *
+ * Mirrors the existing tenant-branded app-link pattern used elsewhere in the
+ * monorepo (brain-service's `generateClaimUrl` / `generateGuardianApprovalUrl`,
+ * `inbox.helpers.ts`'s `new URL('/notifications', appUrl)`): prefer the
+ * resolved tenant's `TenantBranding.appUrl`, which already falls back to the
+ * LearnCard default (`https://learncard.app`) via `resolveBranding()` when a
+ * tenant has no override.
+ */
+
+import { resolveBranding } from '@learncard/email-templates';
+import type { Context } from '@routes';
+
+/** Base app URL (e.g. `https://vetpass.app`) for constructing escrow deep links. */
+export const resolveEscrowAppBaseUrl = (ctx: Pick<Context, 'tenant'>): string =>
+    resolveBranding(ctx.tenant?.emailBranding).appUrl;
+
+/**
+ * Builds the single-use "cancel this recovery" link sent in the hold-started
+ * email. Uses `URL`/`URLSearchParams` rather than string concatenation so
+ * `holdId`/`token` are correctly percent-encoded and a trailing slash on
+ * `baseUrl` never produces a doubled `//recovery/cancel`.
+ */
+export const buildEscrowCancelUrl = ({
+    baseUrl,
+    holdId,
+    token,
+}: {
+    baseUrl: string;
+    holdId: string;
+    token: string;
+}): string => {
+    const url = new URL('/recovery/cancel', baseUrl);
+    url.searchParams.set('holdId', holdId);
+    url.searchParams.set('token', token);
+    return url.toString();
+};

package/src/helpers/escrowCancelToken.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+    generateEscrowCancelToken,
+    hashEscrowCancelToken,
+    escrowCancelTokenMatches,
+} from './escrowCancelToken';
+
+import type { EscrowHold } from '@models';
+
+const baseHold = (overrides: Partial<EscrowHold> = {}): EscrowHold => {
+    const now = new Date();
+    return {
+        holdRecord: {
+            hold: {
+                holdId: 'hold-id',
+                did: 'did:key:test',
+                shareVersion: 1,
+                blobHash: 'ab'.repeat(32),
+                enrollmentEpoch: 1,
+                releasePolicy: 'hold',
+                clientEphemeralPublicKey: 'public-key',
+                createdLo: 0,
+                createdHi: 0,
+                policyVersion: 1,
+                signature: 'test-signature',
+            },
+            holdDurationMs: 0,
+            ledgerSeq: 0,
+        },
+        _id: 'hold-id',
+        authProvider: { type: 'firebase', id: 'user-1' },
+        primaryDid: 'did:key:test',
+        shareVersion: 1,
+        status: 'pending',
+        identityProofType: 'auth-token',
+        requestedAt: now,
+        releaseAfter: now,
+        releasePolicy: 'hold',
+        clientEphemeralPublicKey: 'public-key',
+        resumeTokenHash: 'a'.repeat(64),
+        notifications: [],
+        createdAt: now,
+        updatedAt: now,
+        ...overrides,
+    };
+};
+
+describe('escrowCancelToken helpers', () => {
+    it('generates unique, high-entropy hex tokens', () => {
+        const token = generateEscrowCancelToken();
+
+        expect(token).toMatch(/^[0-9a-f]{64}$/);
+        expect(generateEscrowCancelToken()).not.toBe(token);
+    });
+
+    it('hashes deterministically without ever equaling the plaintext', () => {
+        const token = generateEscrowCancelToken();
+        const hash = hashEscrowCancelToken(token);
+
+        expect(hash).toMatch(/^[0-9a-f]{64}$/);
+        expect(hash).not.toBe(token);
+        expect(hashEscrowCancelToken(token)).toBe(hash);
+    });
+
+    it('matches the correct token against a pending, unused hold', () => {
+        const token = generateEscrowCancelToken();
+        const hold = baseHold({ cancelTokenHash: hashEscrowCancelToken(token) });
+
+        expect(escrowCancelTokenMatches(hold, token)).toBe(true);
+    });
+
+    it('rejects a wrong token', () => {
+        const token = generateEscrowCancelToken();
+        const hold = baseHold({ cancelTokenHash: hashEscrowCancelToken(token) });
+
+        expect(escrowCancelTokenMatches(hold, generateEscrowCancelToken())).toBe(false);
+    });
+
+    it('rejects an already-used token', () => {
+        const token = generateEscrowCancelToken();
+        const hold = baseHold({
+            cancelTokenHash: hashEscrowCancelToken(token),
+            cancelTokenUsedAt: new Date(),
+        });
+
+        expect(escrowCancelTokenMatches(hold, token)).toBe(false);
+    });
+
+    it('rejects a non-pending hold even with a correct, unused token', () => {
+        const token = generateEscrowCancelToken();
+
+        for (const status of ['cancelled', 'completed', 'expired'] as const) {
+            const hold = baseHold({ status, cancelTokenHash: hashEscrowCancelToken(token) });
+
+            expect(escrowCancelTokenMatches(hold, token)).toBe(false);
+        }
+    });
+
+    it('rejects when no cancel token was ever issued on the hold', () => {
+        const hold = baseHold();
+
+        expect(escrowCancelTokenMatches(hold, generateEscrowCancelToken())).toBe(false);
+    });
+});

package/src/helpers/escrowCancelToken.ts

@@ -0,0 +1,47 @@
+/**
+ * Escrow recovery cancel-link token.
+ *
+ * Mirrors the resume-token primitive in `models/EscrowHold.ts`: a random,
+ * high-entropy token whose SHA-256 hash is stored on the hold so the
+ * plaintext never needs to be persisted. There is no HMAC key involved —
+ * the token's own entropy is the secret, exactly like `resumeTokenHash`.
+ *
+ * The token is single-use (burned via `cancelTokenUsedAt`) and its
+ * effective TTL is the hold's own lifetime: it stops matching the moment
+ * the hold leaves the `pending` status (cancelled, completed, or expired),
+ * so no separate expiry timestamp is needed.
+ *
+ * Never log the plaintext token.
+ */
+
+import { createHash, randomBytes, timingSafeEqual } from 'crypto';
+
+import type { EscrowHold } from '@models';
+
+/** 256 bits of entropy, hex-encoded — same shape as `generateEscrowResumeToken`. */
+export const generateEscrowCancelToken = (): string => randomBytes(32).toString('hex');
+
+/** Plain SHA-256, matching `hashEscrowResumeToken` — the token's own entropy is the secret. */
+export const hashEscrowCancelToken = (token: string): string =>
+    createHash('sha256').update(token).digest('hex');
+
+/**
+ * Timing-safe cancel-token check.
+ *
+ * Returns `false` (never throws) when the hold has no cancel token, the
+ * token was already used, or the hold is no longer `pending` — a cancel
+ * link's effective TTL is the hold's own lifetime, not a separate clock.
+ */
+export const escrowCancelTokenMatches = (hold: EscrowHold, token: string): boolean => {
+    if (hold.status !== 'pending' || hold.cancelTokenUsedAt) return false;
+    const actual = Buffer.from(hashEscrowCancelToken(token), 'hex');
+    const hashes = [
+        ...(hold.cancelTokenHashes ?? []),
+        ...(hold.cancelTokenHash ? [hold.cancelTokenHash] : []),
+    ];
+    // Evaluate every hash, including after a match, rather than short-circuiting.
+    return hashes.reduce((matches, hash) => {
+        const expected = Buffer.from(hash, 'hex');
+        return (actual.length === expected.length && timingSafeEqual(actual, expected)) || matches;
+    }, false);
+};

package/src/helpers/keycloak.helpers.ts

@@ -0,0 +1,120 @@
+import { environment } from '@environment';
+import { TRPCError } from '@trpc/server';
+import { createRemoteJWKSet, decodeJwt, decodeProtectedHeader, jwtVerify } from 'jose';
+import type { JWTVerifyGetKey } from 'jose';
+import { z } from 'zod';
+
+export interface KeycloakVerifyOptions {
+    issuers: string[];
+    audiences: string[];
+}
+
+export interface KeycloakClaims {
+    sub: string;
+    iss: string;
+    typ?: string;
+    azp?: string;
+    aud?: string | string[];
+    email?: string;
+    email_verified?: boolean;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+    name?: string;
+    picture?: string;
+}
+
+const claimsSchema = z.object({
+    sub: z.string().min(1),
+    iss: z.string(),
+    // The payload typ is a Keycloak extension, not a required OIDC claim.
+    typ: z.enum(['ID', 'Bearer']).optional(),
+    azp: z.string().optional(),
+    aud: z.union([z.string(), z.array(z.string())]).optional(),
+    email: z.string().min(1).optional(),
+    email_verified: z.boolean().optional(),
+    phone_number: z.string().min(1).optional(),
+    phone_number_verified: z.boolean().optional(),
+    name: z.string().optional(),
+    picture: z.string().optional(),
+});
+
+const jwksByIssuer = new Map<string, { url: string; resolver: JWTVerifyGetKey }>();
+let resolverForTests: ((issuer: string) => JWTVerifyGetKey) | undefined;
+
+/** Replace JWKS resolution in isolated tests; resetting also clears memoized resolvers. */
+export const setKeycloakJwksResolverForTests = (
+    resolver: ((issuer: string) => JWTVerifyGetKey) | undefined
+): void => {
+    resolverForTests = resolver;
+    jwksByIssuer.clear();
+};
+
+/** Resolve an issuer's JWKS endpoint, optionally using a configured internal hostname. */
+export const getKeycloakIssuerJwksUrl = (issuer: string): string => {
+    for (const entry of (environment.KEYCLOAK_JWKS_URL_OVERRIDES ?? '').split(',')) {
+        const separator = entry.indexOf('=');
+        if (separator < 0) continue;
+        const configuredIssuer = entry.slice(0, separator).trim();
+        const url = entry.slice(separator + 1).trim();
+        if (configuredIssuer === issuer && url) return url;
+    }
+    return `${issuer}/protocol/openid-connect/certs`;
+};
+
+/** Reuse remote key caches and rotation handling per trusted issuer. */
+export const getKeycloakJwks = (issuer: string): JWTVerifyGetKey => {
+    const url = getKeycloakIssuerJwksUrl(issuer);
+    const cached = jwksByIssuer.get(issuer);
+    if (cached?.url === url) return cached.resolver;
+    const resolver = resolverForTests ? resolverForTests(issuer) : createRemoteJWKSet(new URL(url));
+    jwksByIssuer.set(issuer, { url, resolver });
+    return resolver;
+};
+
+/** Verify signature and claims, checking the issuer allowlist before resolving keys. */
+export const verifyKeycloakJwt = async (
+    token: string,
+    opts: KeycloakVerifyOptions
+): Promise<KeycloakClaims> => {
+    decodeProtectedHeader(token);
+    const { iss } = decodeJwt(token);
+    if (typeof iss !== 'string' || !opts.issuers.includes(iss)) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid Keycloak token' });
+    }
+
+    const { payload } = await jwtVerify(token, getKeycloakJwks(iss), {
+        issuer: iss,
+        algorithms: ['RS256', 'ES256'],
+        clockTolerance: 30,
+    });
+    const result = claimsSchema.safeParse(payload);
+    if (!result.success) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid Keycloak token' });
+    }
+    const claims = result.data;
+    const audiences = typeof claims.aud === 'string' ? [claims.aud] : (claims.aud ?? []);
+    if (claims.azp) audiences.push(claims.azp);
+    if (!audiences.some(audience => opts.audiences.includes(audience))) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid Keycloak token' });
+    }
+    return claims;
+};
+
+/** Read comma-separated issuer and client allowlists from the service configuration. */
+export const getKeycloakVerifyOptionsFromEnv = (): KeycloakVerifyOptions | null => {
+    const split = (value: string | undefined): string[] =>
+        (value ?? '')
+            .split(',')
+            .map(entry => entry.trim())
+            .filter(Boolean);
+    const issuers = split(environment.KEYCLOAK_ISSUERS);
+    if (!issuers.length) return null;
+    const audiences = split(environment.KEYCLOAK_AUDIENCES);
+    if (!audiences.length) {
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'KEYCLOAK_AUDIENCES is required when KEYCLOAK_ISSUERS is configured',
+        });
+    }
+    return { issuers, audiences };
+};

package/src/helpers/learnCard.helpers.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
 
 const mocks = vi.hoisted(() => ({
-    getSigningAuthorityForDid: vi.fn(async () => ({ seed: 'shared-seed' })),
+    getSigningAuthorityForDid: vi.fn(),
     initLearnCard: vi.fn(async (options: { didWeb?: string }) => ({
         did: options.didWeb ?? 'did:key:cached-test',
     })),
@@ -18,9 +18,19 @@ vi.mock('@learncard/didkit-plugin-node', () => ({
 }));
 
 import { getSigningAuthorityLearnCard } from './learnCard.helpers';
+import { seedEncryption } from './seedEncryption.helpers';
 
 describe('getSigningAuthorityLearnCard', () => {
     it('isolates cached wallets by owner DID when authorities share a seed', async () => {
+        const authorities = await Promise.all(
+            ['did:key:z6MkOwner', 'did:web:example.com:owner'].map(async ownerDid => {
+                const identity = { _id: ownerDid, ownerDid, name: 'shared-authority' };
+                return { ...identity, ...(await seedEncryption.encrypt('a'.repeat(64), identity)) };
+            })
+        );
+        mocks.getSigningAuthorityForDid.mockImplementation(async ownerDid =>
+            authorities.find(authority => authority.ownerDid === ownerDid)
+        );
         const didKeyWallet = await getSigningAuthorityLearnCard(
             'did:key:z6MkOwner',
             'shared-authority'

package/src/helpers/learnCard.helpers.ts

@@ -8,6 +8,11 @@ import type { EmptyLearnCard, LearnCardFromSeed, DidWebLearnCardFromSeed } from
 
 import { getSigningAuthorityForDid } from '@accesslayer/signing-authority/read';
 import { getLRUCache } from '@cache/in-memory-lru';
+import {
+    decryptSigningAuthoritySeed,
+    getSeedCacheFingerprint,
+    logSeedEncryptionFailure,
+} from '@helpers/seedEncryption.helpers';
 
 const cloud = environment.LEARN_CLOUD_URL
     ? { url: environment.LEARN_CLOUD_URL }
@@ -16,11 +21,11 @@ const cloud = environment.LEARN_CLOUD_URL
 let emptyLearnCard: EmptyLearnCard['returnValue'];
 let learnCard: LearnCardFromSeed['returnValue'];
 
-const saCardsCache = getLRUCache<
-    LearnCardFromSeed['returnValue'] | DidWebLearnCardFromSeed['returnValue']
->();
+const saCardsCache = getLRUCache<{
+    fingerprint: string;
+    card: LearnCardFromSeed['returnValue'] | DidWebLearnCardFromSeed['returnValue'];
+}>();
 const didWebCardsCache = getLRUCache<DidWebLearnCardFromSeed['returnValue']>();
-const ephemeralCardsCache = getLRUCache<LearnCardFromSeed['returnValue']>();
 
 // The DIDKit WASM is copied next to the compiled handler at build time (see
 // esbuildPlugins.cjs). The Lambda bundle's node_modules layout doesn't match what
@@ -116,22 +121,20 @@ export const getSigningAuthorityLearnCard = async (
 
     const sa = await getSigningAuthorityForDid(ownerDID, name);
 
-    if (!sa?.seed) {
-        console.error('[LCA getSigningAuthorityLearnCard] SA not found or has no seed:', {
-            ownerDID,
-            name,
-            saFound: !!sa,
-            hasSeed: !!sa?.seed,
-        });
+    if (!sa) {
         throw new Error(`No signing authority found for ownerDID="${ownerDID}" name="${name}"`);
     }
-    const cacheKey = `${sa.seed}|${ownerDID}`;
-
-    const cachedValue = saCardsCache.get(cacheKey);
-
-    if (cachedValue) {
-        console.log('[LCA getSigningAuthorityLearnCard] Using cached SA LearnCard');
-        return cachedValue;
+    const cacheKey = `${ownerDID}|${name}`;
+    let fingerprint: string;
+    try {
+        // Validate the envelope before accepting a cache hit. The database lookup remains
+        // on the warm path so deletion/recreation or modification cannot reuse an old key.
+        fingerprint = getSeedCacheFingerprint(sa);
+        const cachedValue = saCardsCache.get(cacheKey);
+        if (cachedValue?.fingerprint === fingerprint) return cachedValue.card;
+    } catch (error) {
+        logSeedEncryptionFailure(error, 'decrypt', sa);
+        throw error;
     }
 
     console.log('[LCA getSigningAuthorityLearnCard] Initializing SA LearnCard:', {
@@ -139,24 +142,40 @@ export const getSigningAuthorityLearnCard = async (
         ownerDID,
     });
 
-    const saLearnCard = ownerDID.startsWith('did:web:')
-        ? await initLearnCard({
-              didkit: await getDidKitInit(),
-              seed: sa.seed,
-              didWeb: ownerDID,
-              cloud,
-              allowRemoteContexts: true,
-          })
-        : await initLearnCard({
-              didkit: await getDidKitInit(),
-              seed: sa.seed,
-              cloud,
-              allowRemoteContexts: true,
-          });
-
-    saCardsCache.add(cacheKey, saLearnCard);
-
-    return saLearnCard;
+    // Finish engine setup before decrypting so the seed is only materialized when
+    // the signer is ready to initialize.
+    const options: LearnCardFromSeed['args'] | DidWebLearnCardFromSeed['args'] = {
+        didkit: await getDidKitInit(),
+        seed: '',
+        cloud,
+        allowRemoteContexts: true,
+        ...(ownerDID.startsWith('did:web:') ? { didWeb: ownerDID } : {}),
+    };
+
+    try {
+        try {
+            options.seed = await decryptSigningAuthoritySeed(sa);
+        } catch (error) {
+            logSeedEncryptionFailure(error, 'decrypt', sa);
+            throw error;
+        }
+
+        // Select the seed initializer overload without copying the seed-bearing options.
+        const initialize: (
+            config: LearnCardFromSeed['args'] | DidWebLearnCardFromSeed['args']
+        ) => Promise<LearnCardFromSeed['returnValue'] | DidWebLearnCardFromSeed['returnValue']> =
+            initLearnCard;
+        const saLearnCard = await initialize(options);
+        saCardsCache.add(cacheKey, { fingerprint, card: saLearnCard });
+
+        return saLearnCard;
+    } finally {
+        // Release this transient reference on both success and failure. This is
+        // not zeroization: initLearnCard requires an immutable string, and its
+        // DID Key plugin retains the seed/private keys for the cached signer's
+        // lifetime. Envelope encryption protects storage, not process memory.
+        options.seed = '';
+    }
 };
 
 export const getServerDidWebDID = (): string => {
@@ -196,17 +215,10 @@ export const getDidWebLearnCard = async (
 export const getEphemeralLearnCard = async (
     seed: string
 ): Promise<LearnCardFromSeed['returnValue']> => {
-    const cachedValue = ephemeralCardsCache.get(seed);
-
-    if (cachedValue) return cachedValue;
-
-    const ephemeralLearnCard = await initLearnCard({
+    // Creation is a one-shot operation; do not retain its seed in a cache key.
+    return initLearnCard({
         didkit: await getDidKitInit(),
         seed,
         cloud,
     });
-
-    ephemeralCardsCache.add(seed, ephemeralLearnCard);
-
-    return ephemeralLearnCard;
 };