@learncard/lca-api-service 1.4.0 → 1.5.0

package/scripts/keycloak-admin.ts

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+
+export const keycloakUserSchema = z.object({
+    id: z.string(),
+    username: z.string().optional(),
+    email: z.string().optional(),
+    emailVerified: z.boolean().optional(),
+    enabled: z.boolean().optional(),
+    attributes: z.record(z.string(), z.array(z.string())).optional(),
+});
+export const federatedIdentitySchema = z.object({
+    identityProvider: z.string(),
+    userId: z.string(),
+    userName: z.string(),
+});
+export type KeycloakUser = z.infer<typeof keycloakUserSchema>;
+export type FederatedIdentity = z.infer<typeof federatedIdentitySchema>;
+
+export class KeycloakAdminError extends Error {
+    constructor(public readonly status: number) {
+        super(`Admin operation failed (${status})`);
+        this.name = 'KeycloakAdminError';
+    }
+}
+
+/** Minimal admin client; no tokens or response bodies are included in errors. */
+export const createKeycloakAdmin = async (
+    fetchRequest: typeof fetch = fetch,
+    now: () => number = Date.now
+): Promise<{
+    request: (path: string, init?: RequestInit) => Promise<Response>;
+    findUsers: (email: string) => Promise<KeycloakUser[]>;
+    links: (id: string) => Promise<FederatedIdentity[]>;
+}> => {
+    const origin = process.env.KEYCLOAK_ADMIN_URL ?? 'http://localhost:8081';
+    const realm = process.env.KEYCLOAK_ADMIN_REALM ?? 'master';
+    const targetRealm = process.env.KEYCLOAK_REALM ?? 'learncard';
+    const clientId = process.env.KEYCLOAK_ADMIN_CLIENT_ID ?? 'admin-cli';
+    const secret = process.env.KEYCLOAK_ADMIN_CLIENT_SECRET;
+    const username = process.env.KEYCLOAK_ADMIN_USERNAME;
+    const password = process.env.KEYCLOAK_ADMIN_PASSWORD;
+    if (!secret && (!username || !password)) throw new Error('Admin credentials are required');
+    let token = '';
+    let refreshAt = 0;
+    const refreshToken = async (): Promise<void> => {
+        const startedAt = now();
+        const tokenResponse = await fetchRequest(
+            `${origin}/realms/${encodeURIComponent(realm)}/protocol/openid-connect/token`,
+            {
+                method: 'POST',
+                redirect: 'error',
+                signal: AbortSignal.timeout(15_000),
+                body: new URLSearchParams({
+                    client_id: clientId,
+                    ...(secret
+                        ? { grant_type: 'client_credentials', client_secret: secret }
+                        : { grant_type: 'password', username: username!, password: password! }),
+                }),
+            }
+        );
+        if (!tokenResponse.ok)
+            throw new Error(`Admin authentication failed (${tokenResponse.status})`);
+        const result = z
+            .object({ access_token: z.string().min(1), expires_in: z.number().positive() })
+            .parse(await tokenResponse.json());
+        token = result.access_token;
+        const lifetime = result.expires_in * 1000;
+        refreshAt = startedAt + lifetime - Math.min(30_000, lifetime / 10);
+    };
+    await refreshToken();
+    const request = async (path: string, init: RequestInit = {}): Promise<Response> => {
+        if (now() >= refreshAt) await refreshToken();
+        const send = async (): Promise<Response> =>
+            fetchRequest(`${origin}/admin/realms/${encodeURIComponent(targetRealm)}${path}`, {
+                ...init,
+                redirect: 'error',
+                signal: AbortSignal.timeout(15_000),
+                headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+            });
+        let response = await send();
+        if (response.status === 401) {
+            await response.body?.cancel();
+            await refreshToken();
+            response = await send();
+        }
+        if (!response.ok) throw new KeycloakAdminError(response.status);
+        return response;
+    };
+    return {
+        request,
+        findUsers: async (email: string): Promise<KeycloakUser[]> =>
+            z
+                .array(keycloakUserSchema)
+                .parse(
+                    await (
+                        await request(`/users?${new URLSearchParams({ email, exact: 'true' })}`)
+                    ).json()
+                ),
+        links: async (id: string): Promise<FederatedIdentity[]> =>
+            z
+                .array(federatedIdentitySchema)
+                .parse(
+                    await (
+                        await request(`/users/${encodeURIComponent(id)}/federated-identity`)
+                    ).json()
+                ),
+    };
+};

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/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)',
+    })
+);