@learncard/lca-api-service 1.3.2 → 1.5.0

package/scripts/keycloak-provider-links.ts

@@ -0,0 +1,147 @@
+import { setTimeout } from 'node:timers/promises';
+import { KeycloakAdminError, type createKeycloakAdmin } from './keycloak-admin';
+
+export interface FirebaseProvider {
+    providerId: string;
+    uid: string;
+    email?: string;
+}
+
+export interface FirebaseUser {
+    uid: string;
+    disabled: boolean;
+    emailVerified: boolean;
+    email?: string;
+    providerData: FirebaseProvider[];
+}
+
+export interface FirebaseReader {
+    getUsers: (identifiers: { uid: string }[]) => Promise<{ users: FirebaseUser[] }>;
+}
+
+export interface ProviderLinkSummary {
+    linked: number;
+    alreadyLinked: number;
+    conflicts: number;
+    noSocialProvider: number;
+    wouldLink: number;
+}
+
+/** Firebase accepts at most 100 identifiers per call; keep requests sequential and paced. */
+export const fetchFirebaseUsers = async (
+    uids: string[],
+    firebase: FirebaseReader,
+    sleep: (ms: number) => Promise<void> = setTimeout
+): Promise<Map<string, FirebaseUser>> => {
+    const unique = [...new Set(uids)];
+    const users = new Map<string, FirebaseUser>();
+    for (let offset = 0; offset < unique.length; offset += 100) {
+        if (offset) await sleep(1000);
+        const identifiers = unique.slice(offset, offset + 100).map(uid => ({ uid }));
+        for (let attempt = 0; ; attempt++) {
+            try {
+                const result = await firebase.getUsers(identifiers);
+                for (const user of result.users) users.set(user.uid, user);
+                break;
+            } catch (error) {
+                const code =
+                    typeof error === 'object' && error !== null && 'code' in error
+                        ? error.code
+                        : undefined;
+                if (
+                    attempt >= 3 ||
+                    (code !== 'auth/too-many-requests' && code !== 'auth/quota-exceeded')
+                ) {
+                    throw error;
+                }
+                await sleep(1000 * 2 ** attempt);
+            }
+        }
+    }
+    return users;
+};
+
+/** Read-only preflight: reject the whole user before adding any provider links. */
+export const findProviderLinkConflicts = (
+    providers: FirebaseProvider[],
+    links: { identityProvider: string; userId: string }[]
+): string[] =>
+    ['google', 'apple'].filter(alias => {
+        const matches = providers.filter(provider => provider.providerId === `${alias}.com`);
+        if (!matches.length) return false;
+        const existing = links.find(link => link.identityProvider === alias);
+        return (
+            matches.some(provider => !provider.uid) ||
+            new Set(matches.map(provider => provider.uid)).size > 1 ||
+            Boolean(existing && existing.userId !== matches[0]!.uid)
+        );
+    });
+
+/** Only add identities; never remove or reassign a provider link, even on conflicts. */
+export const linkFirebaseProviders = async ({
+    userId,
+    providers,
+    apply,
+    admin,
+    log,
+    summary = { linked: 0, alreadyLinked: 0, conflicts: 0, noSocialProvider: 0, wouldLink: 0 },
+}: {
+    userId?: string;
+    providers: FirebaseProvider[];
+    apply: boolean;
+    admin: Pick<Awaited<ReturnType<typeof createKeycloakAdmin>>, 'links' | 'request'>;
+    log: (message: string) => void;
+    summary?: ProviderLinkSummary;
+}): Promise<ProviderLinkSummary> => {
+    const social = providers.filter(
+        provider => provider.providerId === 'google.com' || provider.providerId === 'apple.com'
+    );
+    if (!social.length) {
+        summary.noSocialProvider++;
+        return summary;
+    }
+    const links = userId ? await admin.links(userId) : [];
+    const conflicts = findProviderLinkConflicts(providers, links);
+    if (conflicts.length) {
+        summary.conflicts += conflicts.length;
+        for (const alias of conflicts)
+            log(`CONFLICT: ${alias} identity differs; manual review required`);
+        return summary;
+    }
+    for (const alias of ['google', 'apple']) {
+        const matches = social.filter(provider => provider.providerId === `${alias}.com`);
+        if (!matches.length) continue;
+        const provider = matches[0]!;
+        const existing = links.find(link => link.identityProvider === alias);
+        if (existing) {
+            summary.alreadyLinked++;
+            continue;
+        }
+        if (!apply) {
+            summary.wouldLink++;
+            log(`PLAN: link ${alias} (ownership conflicts checked on apply)`);
+            continue;
+        }
+        if (!userId) throw new Error('A provisioned Keycloak user is required for linking');
+        try {
+            await admin.request(
+                `/users/${encodeURIComponent(userId)}/federated-identity/${alias}`,
+                {
+                    method: 'POST',
+                    body: JSON.stringify({
+                        identityProvider: alias,
+                        userId: provider.uid,
+                        userName: provider.email || provider.uid,
+                    }),
+                }
+            );
+            summary.linked++;
+            log(`Linked ${alias}`);
+        } catch (error) {
+            if (!(error instanceof KeycloakAdminError) || error.status !== 409) throw error;
+            summary.conflicts++;
+            log(`CONFLICT: ${alias} identity already linked; manual review required`);
+        }
+    }
+    return summary;
+};

package/scripts/migrate-signing-authority-seeds-local.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Run one local migration phase using the API container's database and keys.
+set -euo pipefail
+
+usage() {
+    echo 'Usage: bun run migrate:sa-seeds:local --dry-run|--prepare|--verify|--purge'
+    echo 'Defaults to read-only dry-run. Runs one phase to completion and streams logs.'
+}
+
+if [[ "$#" -gt 1 ]]; then
+    usage >&2
+    exit 1
+fi
+
+case "${1:---dry-run}" in
+    --dry-run|--prepare|--verify|--purge) SA_PHASE="${1:---dry-run}"; SA_PHASE="${SA_PHASE#--}" ;;
+    --help|-h) usage; exit 0 ;;
+    *) usage >&2; exit 1 ;;
+esac
+
+SA_REPO_ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../../../.." && pwd)"
+cd "$SA_REPO_ROOT"
+printf 'Running local signing-authority migration: %s\n' "$SA_PHASE"
+
+docker compose -f apps/learn-card-app/compose-local.yaml exec -T \
+  -e "SA_MIGRATION_PHASE=$SA_PHASE" \
+  -w /app/services/learn-card-network/lca-api api bun --conditions=development -e '
+import { environment } from "./src/config/environment";
+import { client, mongodb } from "./src/mongo";
+import { runSeedMigrationBatch, SeedMigrationError } from "./src/migrations/signingAuthoritySeeds";
+
+try {
+    let result;
+    do {
+        result = await runSeedMigrationBatch(
+            mongodb,
+            { phase: process.env.SA_MIGRATION_PHASE, batchSize: 50 },
+            { encryptedWritesEnabled: environment.SA_SEED_ENCRYPT_WRITES }
+        );
+        console.log(JSON.stringify(result, null, 2));
+        if (!result.done && result.processed === 0 && !result.rescanRequired) {
+            throw new Error("No progress");
+        }
+    } while (!result.done);
+} catch (error) {
+    console.error(error instanceof SeedMigrationError ? error.category : "operation_failed");
+    process.exitCode = 1;
+} finally {
+    await client.close();
+}
+'

package/scripts/migrate-signing-authority-seeds.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+
+const { values } = parseArgs({
+    options: {
+        'function-name': { type: 'string' },
+        region: { type: 'string' },
+        phase: { type: 'string', default: 'dry-run' },
+        'batch-size': { type: 'string', default: '50' },
+        'one-batch': { type: 'boolean', default: false },
+        help: { type: 'boolean', default: false },
+    },
+});
+
+if (values.help) {
+    console.log(
+        'Usage: node scripts/migrate-signing-authority-seeds.mjs --function-name NAME --region REGION --phase dry-run|prepare|verify|purge [--batch-size 1..100] [--one-batch]'
+    );
+    process.exit(0);
+}
+const batchSize = Number(values['batch-size']);
+if (
+    !values['function-name'] ||
+    !values.region ||
+    !['dry-run', 'prepare', 'verify', 'purge'].includes(values.phase) ||
+    !Number.isInteger(batchSize) ||
+    batchSize < 1 ||
+    batchSize > 100
+) {
+    console.error('Provide --function-name, --region, a valid --phase, and --batch-size 1..100.');
+    process.exit(1);
+}
+
+// No database credentials or key material on the operator host. AWS CLI uses its normal credential chain.
+const directory = mkdtempSync(join(tmpdir(), 'lca-sa-migration-'));
+const payloadFile = join(directory, 'request.json');
+const outputFile = join(directory, 'response.json');
+writeFileSync(payloadFile, JSON.stringify({ phase: values.phase, batchSize }), { mode: 0o600 });
+try {
+    let done = false;
+    do {
+        const invocation = JSON.parse(
+            execFileSync(
+                'aws',
+                [
+                    'lambda',
+                    'invoke',
+                    '--function-name',
+                    values['function-name'],
+                    '--region',
+                    values.region,
+                    '--invocation-type',
+                    'RequestResponse',
+                    '--payload',
+                    `fileb://${payloadFile}`,
+                    '--cli-read-timeout',
+                    '910',
+                    '--cli-connect-timeout',
+                    '10',
+                    '--output',
+                    'json',
+                    outputFile,
+                ],
+                {
+                    encoding: 'utf8',
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                    env: { ...process.env, AWS_PAGER: '' },
+                }
+            )
+        );
+        const result = JSON.parse(readFileSync(outputFile, 'utf8'));
+        if (invocation.FunctionError || invocation.StatusCode !== 200) {
+            // The Lambda boundary emits only sanitized migration errors.
+            console.error(
+                result.errorMessage ?? 'Migration invocation failed. Inspect the function logs.'
+            );
+            process.exitCode = 1;
+            break;
+        }
+        console.log(JSON.stringify(result));
+        done = result.done === true;
+        if (!done && result.processed === 0 && !result.rescanRequired) {
+            console.error('No progress in this batch. Inspect the function logs before retrying.');
+            process.exitCode = 1;
+            break;
+        }
+    } while (!done && !values['one-batch']);
+} catch (error) {
+    // CLI diagnostics describe invocation/auth/transport failures. Never print the whole
+    // exec error: stdout and the Lambda response are handled separately above.
+    if (typeof error.stderr === 'string' || Buffer.isBuffer(error.stderr)) {
+        const diagnostic = error.stderr.toString().trim();
+        if (diagnostic) console.error(diagnostic);
+    }
+    console.error(
+        'AWS invocation failed. Check your credentials, region, and function name; rerun to resume.'
+    );
+    process.exitCode = 1;
+} finally {
+    rmSync(directory, { recursive: true, force: true });
+}

package/scripts/print-seed-rollout-flags.ts

@@ -0,0 +1,21 @@
+// Prints the signing-authority seed rollout flags a deployment loads from its checked-in
+// config.<tenant>.<stage>.json. Usage: CONFIG_TENANT=scouts bun run sa-seed:flags production
+import { resolveStageDefaults } from '@learncard/service-config';
+
+import { base, stages } from '../src/config/stageConfig';
+
+const stage = process.argv[2];
+if (!stage)
+    throw new Error(
+        'Usage: bun run sa-seed:flags <dev|production> (CONFIG_TENANT selects the tenant)'
+    );
+
+const resolved = resolveStageDefaults({ base, stages, stage, env: process.env });
+console.log(
+    JSON.stringify({
+        tenant: process.env.CONFIG_TENANT || 'learncard',
+        stage,
+        SA_SEED_ENCRYPT_WRITES: resolved.SA_SEED_ENCRYPT_WRITES ?? '(schema default)',
+        SA_SEED_ALLOW_LEGACY_READ: resolved.SA_SEED_ALLOW_LEGACY_READ ?? '(schema default)',
+    })
+);