@atlasauth/cli 0.12.0 → 0.13.0

package/dist/migrate/export/keycloak.js

@@ -0,0 +1,878 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readKeycloakExport = readKeycloakExport;
+exports.keycloakBase = keycloakBase;
+exports.keycloakAdminHttp = keycloakAdminHttp;
+exports.fetchKeycloakRealm = fetchKeycloakRealm;
+exports.mapKeycloak = mapKeycloak;
+exports.mapKeycloakUser = mapKeycloakUser;
+exports.keycloakPassword = keycloakPassword;
+exports.keycloakOtp = keycloakOtp;
+exports.keycloakRecoveryCodes = keycloakRecoveryCodes;
+exports.keycloakPasskey = keycloakPasskey;
+exports.isBuiltInRole = isBuiltInRole;
+exports.isBuiltInClient = isBuiltInClient;
+exports.clientRoleKey = clientRoleKey;
+exports.groupKey = groupKey;
+exports.base32 = base32;
+exports.base64url = base64url;
+exports.exportKeycloak = exportKeycloak;
+const record_set_1 = require("./record-set");
+const translate_kit_1 = require("./translate-kit");
+const vendor_http_1 = require("./vendor-http");
+/** Realm roles every realm has; never imported as app roles. */
+const BUILT_IN_ROLES = new Set(['offline_access', 'uma_authorization']);
+/** Clients every realm has (their roles are Keycloak's own admin and account permissions). */
+const BUILT_IN_CLIENTS = new Set(['account', 'account-console', 'admin-cli', 'broker', 'realm-management', 'security-admin-console']);
+/** Brokered identity providers that are enterprise connections, not social sign-in. */
+const ENTERPRISE = new Set(['saml', 'oidc', 'keycloak-oidc']);
+/** Keycloak social provider ids that `socialKey` does not already know. */
+const KC_SOCIAL = { 'linkedin-openid-connect': 'linkedin' };
+/** User attributes the user record carries itself. */
+const PHONE_ATTRS = ['phoneNumber', 'phone_number', 'phone', 'mobile'];
+const CONSUMED_ATTRS = new Set([...PHONE_ATTRS, 'phoneNumberVerified', 'phone_number_verified', 'picture']);
+// ── reading a realm export ──────────────────────────────────────────────────
+/**
+ * Assemble a snapshot from the JSON documents of a realm export: one realm
+ * file (`--file`, a realm object or an array of realms), or a `--dir` export
+ * (`<realm>-realm.json` plus `<realm>-users-<n>.json` / `<realm>-federated-users-<n>.json`
+ * chunks, each `{ realm, users }`). `realmName` picks a realm when there are several.
+ */
+function readKeycloakExport(docs, realmName) {
+    const realms = [];
+    const chunks = [];
+    for (const doc of docs) {
+        for (const d of Array.isArray(doc) ? doc.filter(record_set_1.isObj) : (0, record_set_1.isObj)(doc) ? [doc] : []) {
+            // A users chunk carries only `realm` (the name) and the user lists.
+            if (typeof d.realm === 'string' && Object.keys(d).every((k) => ['realm', 'users', 'federatedUsers'].includes(k)))
+                chunks.push(d);
+            else if (typeof d.realm === 'string')
+                realms.push(d);
+        }
+    }
+    if (!realms.length)
+        throw new Error('No realm found in the Keycloak export (expected the JSON written by kc.sh export).');
+    let realm;
+    if (realmName)
+        realm = realms.find((r) => r.realm === realmName);
+    else if (realms.length === 1)
+        realm = realms[0];
+    else {
+        // A full-server export also holds master: the one other realm is the app's.
+        const apps = realms.filter((r) => r.realm !== 'master');
+        if (apps.length === 1)
+            realm = apps[0];
+    }
+    if (!realm) {
+        throw new Error(realmName
+            ? `Realm "${realmName}" is not in the export (found: ${realms.map((r) => String(r.realm)).join(', ')}).`
+            : `The export holds several realms (${realms.map((r) => String(r.realm)).join(', ')}): name one with --set keycloak-realm=<realm>.`);
+    }
+    const name = String(realm.realm);
+    const mine = chunks.filter((c) => c.realm === name);
+    const { users, federatedUsers, ...rest } = realm;
+    return {
+        realm: rest,
+        users: [...(0, record_set_1.objs)(users), ...mine.flatMap((c) => (0, record_set_1.objs)(c.users))],
+        federatedUsers: [...(0, record_set_1.objs)(federatedUsers), ...mine.flatMap((c) => (0, record_set_1.objs)(c.federatedUsers))],
+        groups: (0, record_set_1.objs)(realm.groups),
+        organizations: (0, record_set_1.objs)(realm.organizations),
+        invitations: [],
+        source: 'file',
+    };
+}
+/** `https://sso.example.com/` → `https://sso.example.com`; a bare host gets https. */
+function keycloakBase(raw) {
+    const s = raw.trim().replace(/\/+$/, '');
+    return /^https?:\/\//.test(s) ? s : `https://${s}`;
+}
+/**
+ * The Admin REST API (`{base}/admin/realms`) with an admin access token, fetched
+ * on first use and again shortly before it expires. Paths start with `/<realm>`.
+ */
+function keycloakAdminHttp(o) {
+    const base = keycloakBase(o.baseUrl);
+    const fetchImpl = o.fetchImpl ?? fetch;
+    const now = o.now ?? Date.now;
+    const byUser = !!(o.username && o.password);
+    if (!byUser && !(o.clientId && o.clientSecret))
+        throw new Error('Keycloak Admin API needs an admin client (client id + secret) or an admin user (username + password).');
+    const authRealm = o.authRealm ?? (byUser ? 'master' : o.realm);
+    const tokenPath = `/realms/${encodeURIComponent(authRealm)}/protocol/openid-connect/token`;
+    let cached = null;
+    const token = async () => {
+        if (cached && cached.until > now())
+            return cached.value;
+        const form = new URLSearchParams(byUser
+            ? { grant_type: 'password', client_id: o.clientId ?? 'admin-cli', username: o.username, password: o.password }
+            : { grant_type: 'client_credentials', client_id: o.clientId, client_secret: o.clientSecret });
+        if (byUser && o.clientSecret)
+            form.set('client_secret', o.clientSecret);
+        let res;
+        try {
+            res = await fetchImpl(`${base}${tokenPath}`, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' }, body: form.toString() });
+        }
+        catch (err) {
+            throw new vendor_http_1.VendorApiError('Keycloak', 0, tokenPath, err instanceof Error ? err.message : String(err));
+        }
+        const body = (await res.json().catch(() => null));
+        if (res.status !== 200 || typeof body?.access_token !== 'string') {
+            const detail = typeof body?.error_description === 'string' ? body.error_description : typeof body?.error === 'string' ? body.error : '';
+            throw new vendor_http_1.VendorApiError('Keycloak', res.status, tokenPath, detail);
+        }
+        const ttl = typeof body.expires_in === 'number' ? body.expires_in : 60;
+        cached = { value: body.access_token, until: now() + Math.max(ttl - 30, 5) * 1000 };
+        return cached.value;
+    };
+    return new vendor_http_1.VendorHttp({
+        vendor: 'Keycloak',
+        baseUrl: `${base}/admin/realms`,
+        headers: async () => ({ authorization: `Bearer ${await token()}` }),
+        fetchImpl,
+        sleep: o.sleep,
+        now,
+    });
+}
+/** Read a realm through the Admin REST API into the realm-export shape. */
+async function fetchKeycloakRealm(http, o) {
+    const r = `/${encodeURIComponent(o.realm)}`;
+    const max = o.pageSize ?? 100;
+    const progress = o.onProgress ?? (() => undefined);
+    const warn = o.warn ?? (() => undefined);
+    const list = async (path) => (0, record_set_1.objs)((await http.get(path)).body);
+    /** A listing the token may not be allowed to read, or the server too old to have. */
+    const optional = async (path, what) => {
+        try {
+            return await list(path);
+        }
+        catch (err) {
+            if (!(err instanceof vendor_http_1.VendorApiError) || ![403, 404].includes(err.status))
+                throw err;
+            if (err.status === 403)
+                warn(`${what} could not be read with this admin credential (403) and were skipped.`);
+            return [];
+        }
+    };
+    const paged = async (path) => {
+        const out = [];
+        const sep = path.includes('?') ? '&' : '?';
+        for (let first = 0;; first += max) {
+            const page = await list(`${path}${sep}first=${first}&max=${max}`);
+            out.push(...page);
+            if (page.length < max)
+                return out;
+        }
+    };
+    progress('realm');
+    const realm = (await http.get(r)).body;
+    if (!(0, record_set_1.isObj)(realm))
+        throw new Error(`Keycloak returned no realm "${o.realm}".`);
+    realm.identityProviders = await optional(`${r}/identity-provider/instances`, 'Identity providers');
+    const clients = await optional(`${r}/clients`, 'Clients');
+    realm.clients = clients;
+    const clientRoles = {};
+    for (const c of clients) {
+        const clientId = (0, record_set_1.str)(c.clientId);
+        if (!clientId || !(0, record_set_1.str)(c.id) || isBuiltInClient(clientId, o.realm))
+            continue;
+        const roles = await optional(`${r}/clients/${encodeURIComponent((0, record_set_1.str)(c.id))}/roles`, `Roles of client ${clientId}`);
+        if (roles.length)
+            clientRoles[clientId] = roles;
+    }
+    realm.roles = { realm: await optional(`${r}/roles?briefRepresentation=false`, 'Realm roles'), client: clientRoles };
+    progress('users');
+    const groups = new Map();
+    const users = await paged(`${r}/users?briefRepresentation=false`);
+    for (const u of users) {
+        const id = (0, record_set_1.str)(u.id);
+        if (!id || (0, record_set_1.str)(u.serviceAccountClientId))
+            continue;
+        const base = `${r}/users/${encodeURIComponent(id)}`;
+        u.federatedIdentities = await list(`${base}/federated-identity`);
+        const memberOf = await list(`${base}/groups?briefRepresentation=false`);
+        u.groups = memberOf.map((g) => (0, record_set_1.str)(g.path)).filter((p) => !!p);
+        for (const g of memberOf)
+            if ((0, record_set_1.str)(g.path))
+                groups.set((0, record_set_1.str)(g.path), g);
+        const mappings = (await http.get(`${base}/role-mappings`)).body;
+        u.realmRoles = (0, record_set_1.objs)((0, record_set_1.isObj)(mappings) ? mappings.realmMappings : undefined).map((m) => (0, record_set_1.str)(m.name)).filter((n) => !!n);
+        const byClient = {};
+        for (const [key, m] of Object.entries((0, record_set_1.isObj)(mappings) && (0, record_set_1.isObj)(mappings.clientMappings) ? mappings.clientMappings : {})) {
+            if (!(0, record_set_1.isObj)(m))
+                continue;
+            const names = (0, record_set_1.objs)(m.mappings).map((x) => (0, record_set_1.str)(x.name)).filter((n) => !!n);
+            if (names.length)
+                byClient[(0, record_set_1.str)(m.client) ?? key] = names;
+        }
+        u.clientRoles = byClient;
+        u.credentials = await list(`${base}/credentials`);
+    }
+    // Roles reach a member through every ancestor group: read the parents nobody is a direct member of.
+    for (const path of [...groups.keys()]) {
+        const parts = path.split('/').filter(Boolean);
+        for (let i = parts.length - 1; i > 0; i--) {
+            const parent = `/${parts.slice(0, i).join('/')}`;
+            if (groups.has(parent))
+                continue;
+            try {
+                const { body } = await http.get(`${r}/group-by-path/${parts.slice(0, i).map(encodeURIComponent).join('/')}`);
+                if ((0, record_set_1.isObj)(body))
+                    groups.set(parent, { ...body, path: parent, subGroups: [] });
+            }
+            catch (err) {
+                if (!(err instanceof vendor_http_1.VendorApiError))
+                    throw err;
+            }
+        }
+    }
+    const organizations = [];
+    const invitations = [];
+    if (realm.organizationsEnabled === true) {
+        progress('organizations');
+        for (const org of await optional(`${r}/organizations?briefRepresentation=false&first=0&max=100000`, 'Organizations')) {
+            const id = (0, record_set_1.str)(org.id);
+            if (!id)
+                continue;
+            const path = `${r}/organizations/${encodeURIComponent(id)}`;
+            org.members = await paged(`${path}/members`);
+            organizations.push(org);
+            // Invitations have an admin endpoint from Keycloak 26.2 on; older servers answer 404.
+            for (const inv of await optional(`${path}/invitations?first=0&max=100000`, `Invitations of ${(0, record_set_1.str)(org.name) ?? id}`))
+                invitations.push({ organizationId: id, ...inv });
+        }
+    }
+    return { realm, users, federatedUsers: [], groups: [...groups.values()], organizations, invitations, source: 'api', baseUrl: o.baseUrl ? keycloakBase(o.baseUrl) : undefined };
+}
+// ── mapping ─────────────────────────────────────────────────────────────────
+/** Map a snapshot (realm export or API) onto canonical records. */
+function mapKeycloak(snap, opts = {}) {
+    const set = new record_set_1.RecordSet();
+    const realm = snap.realm;
+    const realmName = (0, record_set_1.str)(realm.realm) ?? 'realm';
+    const groupsAs = opts.groupsAs ?? 'roles';
+    const groups = indexGroups(snap.groups);
+    // ── Keycloak organizations (25+) ──
+    const orgIds = new Set();
+    const orgOfIdp = new Map();
+    for (const o of snap.organizations) {
+        const id = (0, record_set_1.str)(o.id);
+        const name = (0, record_set_1.str)(o.name);
+        if (!id || !name)
+            continue;
+        orgIds.add(id);
+        for (const idp of (0, record_set_1.objs)(o.identityProviders))
+            if ((0, record_set_1.str)(idp.alias))
+                orgOfIdp.set((0, record_set_1.str)(idp.alias), id);
+        set.add('organization', (0, record_set_1.compact)({
+            id,
+            name,
+            slug: (0, record_set_1.str)(o.alias),
+            domains: (0, record_set_1.objs)(o.domains).map((d) => (0, record_set_1.str)(d.name)?.toLowerCase()).filter((d) => !!d),
+            public_metadata: (0, record_set_1.bag)((0, record_set_1.compact)({ description: (0, record_set_1.str)(o.description), redirect_url: (0, record_set_1.str)(o.redirectUrl), ...unwrapAttributes(o.attributes) })),
+            private_metadata: o.enabled === false ? { keycloak_enabled: false } : undefined,
+        }));
+    }
+    if (orgIds.size)
+        set.add('role', { key: 'member', name: 'Member', scope: 'organization' }, 'org:member');
+    // ── groups as organizations ──
+    if (groupsAs === 'organizations') {
+        for (const g of groups.values()) {
+            set.add('organization', (0, record_set_1.compact)({ id: g.id, name: g.name, slug: g.path.split('/').filter(Boolean).map((s) => (0, translate_kit_1.keyOf)(s).replace(/_/g, '-')).join('-'), public_metadata: (0, record_set_1.bag)({ keycloak_group_path: g.path, ...unwrapAttributes(g.attributes) }) }));
+        }
+        if (groups.size)
+            set.add('role', { key: 'member', name: 'Member', scope: 'organization' }, 'org:member');
+    }
+    // ── roles: realm roles, client roles, groups ──
+    const roles = (0, record_set_1.isObj)(realm.roles) ? realm.roles : {};
+    let composite = false;
+    for (const role of (0, record_set_1.objs)(roles.realm)) {
+        const name = (0, record_set_1.str)(role.name);
+        if (!name || isBuiltInRole(name))
+            continue;
+        if (role.composite === true)
+            composite = true;
+        set.add('role', (0, record_set_1.compact)({ key: (0, translate_kit_1.keyOf)(name), name, description: (0, record_set_1.str)(role.description), scope: 'app' }), (0, translate_kit_1.keyOf)(name));
+    }
+    for (const [clientId, list] of Object.entries((0, record_set_1.isObj)(roles.client) ? roles.client : {})) {
+        if (isBuiltInClient(clientId, realmName))
+            continue;
+        for (const role of (0, record_set_1.objs)(list)) {
+            const name = (0, record_set_1.str)(role.name);
+            if (!name)
+                continue;
+            if (role.composite === true)
+                composite = true;
+            set.add('role', (0, record_set_1.compact)({ key: clientRoleKey(clientId, name), name: `${clientId}: ${name}`, description: (0, record_set_1.str)(role.description), scope: 'app' }), clientRoleKey(clientId, name));
+        }
+    }
+    if (groupsAs === 'roles') {
+        for (const g of groups.values())
+            set.add('role', { key: groupKey(g.path), name: g.path, description: 'Keycloak group', scope: 'app' }, groupKey(g.path));
+    }
+    if (composite)
+        set.warn('Composite roles were imported as plain roles: a user holds the roles assigned to them and their groups, not the roles a composite role includes. Assign those in Atlas, or give the composite role the permissions it stood for.');
+    // ── identity providers ──
+    const idps = new Map();
+    for (const idp of (0, record_set_1.objs)(realm.identityProviders))
+        if ((0, record_set_1.str)(idp.alias))
+            idps.set((0, record_set_1.str)(idp.alias), idp);
+    const connections = new Set();
+    for (const [alias, idp] of idps) {
+        const providerId = (0, record_set_1.str)(idp.providerId) ?? '';
+        if (!ENTERPRISE.has(providerId))
+            continue;
+        const orgId = (0, record_set_1.str)(idp.organizationId) ?? orgOfIdp.get(alias);
+        const connection = ssoConnection(idp, {
+            realm: realmName,
+            baseUrl: snap.baseUrl,
+            organizationId: orgId && orgIds.has(orgId) ? orgId : undefined,
+            domains: [
+                ...(0, record_set_1.strs)((0, record_set_1.isObj)(idp.config) ? [idp.config['kc.org.domain']] : []),
+                ...snap.organizations.filter((o) => (0, record_set_1.str)(o.id) === orgId).flatMap((o) => (0, record_set_1.objs)(o.domains).filter((d) => !(0, record_set_1.str)(d.identityProviderAlias) || (0, record_set_1.str)(d.identityProviderAlias) === alias).map((d) => (0, record_set_1.str)(d.name))),
+            ],
+            warn: (m) => set.warn(m),
+        });
+        set.add('sso_connection', connection);
+        connections.add(alias);
+    }
+    // ── users ──
+    const rpIds = {
+        webauthn: (0, record_set_1.str)(realm.webAuthnPolicyRpId) ?? opts.rpId,
+        passwordless: (0, record_set_1.str)(realm.webAuthnPolicyPasswordlessRpId) ?? (0, record_set_1.str)(realm.webAuthnPolicyRpId) ?? opts.rpId,
+    };
+    const userIdByName = new Map();
+    const counts = { password: 0, federated: 0, otpWithoutSecret: 0, temporary: 0 };
+    const badHashes = new Map();
+    for (const u of snap.users) {
+        if ((0, record_set_1.str)(u.serviceAccountClientId)) {
+            set.omit('user', 'Keycloak service-account user (a client credential, not a person)');
+            continue;
+        }
+        const user = mapKeycloakUser(u, realm);
+        if (!user) {
+            set.omit('user', 'no id, email or username');
+            continue;
+        }
+        const id = user.id;
+        if ((0, record_set_1.str)(u.username))
+            userIdByName.set((0, record_set_1.str)(u.username).toLowerCase(), id);
+        if ((0, record_set_1.str)(u.federationLink))
+            counts.federated++;
+        if ((0, record_set_1.strs)(u.requiredActions).includes('UPDATE_PASSWORD'))
+            counts.temporary++;
+        const creds = (0, record_set_1.objs)(u.credentials);
+        // Keycloak lists credentials by priority: the first password is the one it checks.
+        const pw = creds.find((c) => (0, record_set_1.str)(c.type) === 'password');
+        if (pw) {
+            if (snap.source === 'api')
+                counts.password++;
+            else {
+                const r = keycloakPassword(pw);
+                if ('hash' in r)
+                    user.password = r.hash;
+                else
+                    badHashes.set(r.problem, (badHashes.get(r.problem) ?? 0) + 1);
+            }
+        }
+        user.roles = userRoleKeys(u, groups, realmName, groupsAs === 'roles');
+        set.add('user', (0, record_set_1.compact)(user));
+        for (const fi of (0, record_set_1.objs)(u.federatedIdentities)) {
+            const identity = mapFederatedIdentity(fi, id, idps, connections);
+            if (identity)
+                set.add('identity', identity, `${identity.provider}:${identity.provider_user_id}`);
+        }
+        let hasOtp = false;
+        for (const c of creds) {
+            const type = (0, record_set_1.str)(c.type) ?? '';
+            if (type === 'otp' || type === 'totp' || type === 'hotp') {
+                hasOtp = true;
+                if (snap.source === 'api')
+                    continue;
+                const f = keycloakOtp(c);
+                if ('factor' in f)
+                    set.add('mfa_factor', { user_id: id, ...f.factor }, `otp:${id}:${(0, record_set_1.str)(c.id) ?? set.count('mfa_factor')}`);
+                else
+                    set.omit('mfa_factor', f.problem);
+            }
+            else if (type === 'recovery-authn-codes') {
+                if (snap.source === 'api') {
+                    set.omit('mfa_factor', 'recovery codes: the Admin API does not return their hashes (use a realm export)');
+                    continue;
+                }
+                const f = keycloakRecoveryCodes(c);
+                if (f)
+                    set.add('mfa_factor', { user_id: id, ...f }, `recovery:${id}`);
+                else
+                    set.omit('mfa_factor', 'recovery codes: none left');
+            }
+            else if (type === 'webauthn' || type === 'webauthn-passwordless') {
+                const rp = type === 'webauthn' ? rpIds.webauthn : rpIds.passwordless;
+                const p = keycloakPasskey(c, rp);
+                if ('passkey' in p)
+                    set.add('passkey', { user_id: id, ...p.passkey }, `passkey:${p.passkey.credential_id}`);
+                else
+                    set.omit('passkey', p.problem);
+            }
+        }
+        if (hasOtp && snap.source === 'api')
+            counts.otpWithoutSecret++;
+        else if (u.totp === true && !hasOtp && snap.source === 'api')
+            counts.otpWithoutSecret++;
+        if (groupsAs === 'organizations') {
+            for (const path of (0, record_set_1.strs)(u.groups)) {
+                const g = groups.get(path);
+                if (g)
+                    set.add('membership', { organization_id: g.id, user_id: id, role: 'member' }, `${g.id}:${id}`);
+            }
+        }
+    }
+    // ── organization members and invitations ──
+    for (const o of snap.organizations) {
+        const orgId = (0, record_set_1.str)(o.id);
+        if (!orgId || !orgIds.has(orgId))
+            continue;
+        for (const m of (0, record_set_1.objs)(o.members)) {
+            const uid = (0, record_set_1.str)(m.id) ?? ((0, record_set_1.str)(m.username) ? userIdByName.get((0, record_set_1.str)(m.username).toLowerCase()) : undefined);
+            if (!uid) {
+                set.omit('membership', 'organization member not among the exported users');
+                continue;
+            }
+            set.add('membership', { organization_id: orgId, user_id: uid, role: 'member' }, `${orgId}:${uid}`);
+        }
+    }
+    for (const inv of snap.invitations) {
+        const id = (0, record_set_1.str)(inv.id);
+        const email = (0, record_set_1.str)(inv.email)?.toLowerCase();
+        const orgId = (0, record_set_1.str)(inv.organizationId);
+        if (!id || !email)
+            continue;
+        const status = (0, record_set_1.str)(inv.status)?.toUpperCase();
+        set.add('invitation', (0, record_set_1.compact)({
+            id,
+            organization_id: orgId && orgIds.has(orgId) ? orgId : undefined,
+            email,
+            role: 'member',
+            status: status === 'EXPIRED' ? 'expired' : 'pending',
+            // Keycloak keeps these as epoch seconds.
+            expires_at: typeof inv.expiresAt === 'number' && inv.expiresAt > 0 ? inv.expiresAt * 1000 : undefined,
+            created_at: typeof inv.sentDate === 'number' && inv.sentDate > 0 ? inv.sentDate * 1000 : undefined,
+        }));
+    }
+    if (snap.federatedUsers.length)
+        set.omit('user', 'kept by a user-storage provider without import (no local profile): they move by lazy migration through Keycloak', snap.federatedUsers.length);
+    // ── what could not move, in plain words ──
+    if (counts.password) {
+        set.warn(`${counts.password} user(s) have a Keycloak password, but the Admin API never returns password hashes. Export the realm with kc.sh export (the only path that carries hashes) or turn on the keycloak lazy-migration preset: each password is then checked against Keycloak on its first Atlas sign-in.`);
+    }
+    if (counts.otpWithoutSecret) {
+        set.warn(`${counts.otpWithoutSecret} user(s) use an authenticator app; the Admin API does not return OTP secrets. A realm export (kc.sh export) carries them; otherwise those users enrol again in Atlas.`);
+    }
+    if (counts.federated) {
+        set.warn(`${counts.federated} user(s) are federated from LDAP / Kerberos (federationLink): Keycloak stores no password for them. Use the keycloak lazy-migration preset (Keycloak checks the password against the directory).`);
+    }
+    if (counts.temporary)
+        set.warn(`${counts.temporary} user(s) must change their password at their next Keycloak sign-in (UPDATE_PASSWORD): their current password was set by an administrator.`);
+    for (const [problem, n] of badHashes)
+        set.warn(`${n} user(s) were imported without a password (${problem}); they reset it, or use lazy migration.`);
+    if (snap.users.some((u) => (0, record_set_1.objs)(u.credentials).some((c) => (0, record_set_1.str)(c.type)?.startsWith('webauthn'))) && !rpIds.passwordless && !rpIds.webauthn) {
+        set.warn('The realm sets no WebAuthn relying-party id (Keycloak then uses its own host name): pass --set keycloak-rp-id=<host> to carry passkeys.');
+    }
+    set.warn('Keycloak sessions are not exportable: the keycloak bridge preset exchanges Keycloak access and ID tokens for Atlas sessions instead.');
+    const otpAlgorithm = (0, record_set_1.str)(realm.otpPolicyAlgorithm);
+    set.manifest = {
+        origin: snap.baseUrl ? `${snap.baseUrl}/realms/${realmName}` : `realm ${realmName}`,
+        sourceVersion: (0, record_set_1.str)(realm.keycloakVersion) ?? null,
+        rpId: rpIds.passwordless ?? rpIds.webauthn ?? null,
+        providers: [...new Set(set.list('identity').map((i) => i.provider))].sort(),
+        settings: (0, record_set_1.compact)({
+            realm: realmName,
+            source: snap.source === 'file' ? 'realm_export' : 'admin_api',
+            groups_as: groupsAs,
+            password_policy: (0, record_set_1.str)(realm.passwordPolicy),
+            otp: (0, record_set_1.str)(realm.otpPolicyType)
+                ? { type: (0, record_set_1.str)(realm.otpPolicyType), algorithm: otpAlgorithm ? otpAlgorithmOf(otpAlgorithm) : 'SHA1', digits: realm.otpPolicyDigits ?? 6, period: realm.otpPolicyPeriod ?? 30 }
+                : undefined,
+        }),
+    };
+    return set;
+}
+/** One Keycloak user → a user record without password and roles (null when it has nothing to sign in with). */
+function mapKeycloakUser(u, realm = {}) {
+    const id = (0, record_set_1.str)(u.id);
+    if (!id)
+        return null;
+    const email = (0, record_set_1.str)(u.email)?.toLowerCase();
+    const username = (0, record_set_1.str)(u.username)?.toLowerCase();
+    const attrs = unwrapAttributes(u.attributes);
+    const phoneRaw = PHONE_ATTRS.map((k) => attrs[k]).find((v) => typeof v === 'string');
+    const phone = (0, record_set_1.e164)(phoneRaw);
+    const phoneVerified = attrs.phoneNumberVerified === 'true' || attrs.phone_number_verified === 'true';
+    const custom = Object.fromEntries(Object.entries(attrs).filter(([k]) => !CONSUMED_ATTRS.has(k)));
+    const actions = (0, record_set_1.strs)(u.requiredActions);
+    const user = (0, record_set_1.compact)({
+        id,
+        emails: email ? [{ email, verified: u.emailVerified === true, primary: true }] : [],
+        phones: phone ? [{ phone, verified: phoneVerified, primary: !email }] : [],
+        // With "email as username" the username is the address: keep it only when it is a real username.
+        username: username && username !== email && realm.registrationEmailAsUsername !== true ? username : undefined,
+        first_name: (0, record_set_1.str)(u.firstName),
+        last_name: (0, record_set_1.str)(u.lastName),
+        image_url: typeof attrs.picture === 'string' && /^https:\/\//.test(attrs.picture) ? attrs.picture : undefined,
+        banned: u.enabled === false ? true : undefined,
+        ban_reason: u.enabled === false ? 'Disabled in Keycloak' : undefined,
+        private_metadata: (0, record_set_1.bag)({
+            ...custom,
+            ...(actions.length ? { keycloak_required_actions: actions } : {}),
+            ...((0, record_set_1.str)(u.federationLink) ? { keycloak_federation_link: (0, record_set_1.str)(u.federationLink) } : {}),
+        }),
+        created_at: typeof u.createdTimestamp === 'number' ? u.createdTimestamp : undefined,
+    });
+    return user.emails?.length || user.phones?.length || user.username ? user : null;
+}
+// ── credentials ─────────────────────────────────────────────────────────────
+/** PBKDF2 provider ids → digest (`pbkdf2` is PBKDF2WithHmacSHA1). */
+const PBKDF2 = { pbkdf2: 'sha1', 'pbkdf2-sha1': 'sha1', 'pbkdf2-sha256': 'sha256', 'pbkdf2-sha512': 'sha512' };
+/** Keycloak's Argon2 version names → the PHC `v=` value. */
+const ARGON2_VERSIONS = { '1.3': 19, '1.0': 16 };
+/**
+ * A Keycloak password credential → an Atlas password hash. Keycloak 9+ keeps
+ * `secretData` `{ value, salt }` and `credentialData` `{ algorithm,
+ * hashIterations, additionalParameters }` as JSON strings; earlier exports
+ * (and hand-written import files) put `hashedSaltedValue`, `salt`,
+ * `hashIterations` and `algorithm` on the credential itself. Salts and values
+ * are standard base64.
+ */
+function keycloakPassword(cred) {
+    const secret = jsonObj(cred.secretData);
+    const data = jsonObj(cred.credentialData);
+    const value = (0, record_set_1.str)(secret.value) ?? (0, record_set_1.str)(cred.hashedSaltedValue);
+    const salt = (0, record_set_1.str)(secret.salt) ?? (0, record_set_1.str)(cred.salt);
+    const algorithm = ((0, record_set_1.str)(data.algorithm) ?? (0, record_set_1.str)(cred.algorithm))?.toLowerCase();
+    const iterations = Number(data.hashIterations ?? cred.hashIterations);
+    if (!value)
+        return { problem: 'no stored password value' };
+    // Community bcrypt providers store the whole digest as the value.
+    if (/^\$2[aby]\$\d{2}\$/.test(value))
+        return { hash: { algorithm: 'bcrypt', hash: value } };
+    if (!algorithm)
+        return { problem: 'the password credential names no algorithm' };
+    const digest = PBKDF2[algorithm];
+    if (digest) {
+        if (!salt || !Number.isInteger(iterations) || iterations < 1)
+            return { problem: `${algorithm} without a salt or iteration count` };
+        // PBEKeySpec over the password's UTF-8 bytes; the key length is the decoded value's (512 bits, or 256 for pbkdf2-sha256 from Keycloak 24 on).
+        return { hash: { algorithm: 'pbkdf2', hash: value, salt, params: { digest, iterations, encoding: 'base64', salt_encoding: 'base64' } } };
+    }
+    if (algorithm === 'argon2') {
+        const extra = (0, record_set_1.isObj)(data.additionalParameters) ? data.additionalParameters : {};
+        const first = (k) => (0, record_set_1.str)(Array.isArray(extra[k]) ? extra[k][0] : extra[k]);
+        const type = first('type') ?? 'id';
+        const version = ARGON2_VERSIONS[first('version') ?? '1.3'];
+        const memory = Number(first('memory') ?? 7168);
+        const parallelism = Number(first('parallelism') ?? 1);
+        const t = Number.isInteger(iterations) && iterations > 0 ? iterations : 5;
+        if (!salt || !['id', 'i', 'd'].includes(type) || version === undefined || !Number.isInteger(memory) || !Number.isInteger(parallelism)) {
+            return { problem: 'an Argon2 credential with parameters Keycloak never writes' };
+        }
+        // Keycloak's Argon2PasswordHashProvider (BouncyCastle, UTF-8 password) as the
+        // PHC string the reference argon2 tool prints for the same inputs.
+        const nopad = (s) => s.replace(/=+$/, '');
+        return { hash: { algorithm: 'argon2', hash: `$argon2${type}$v=${version}$m=${memory},t=${t},p=${parallelism}$${nopad(salt)}$${nopad(value)}` } };
+    }
+    return { problem: `unsupported hash algorithm "${algorithm}"` };
+}
+/**
+ * A Keycloak OTP credential → a TOTP factor. The secret is a plain string whose
+ * UTF-8 BYTES are the HMAC key (OTPCredentialModel.getDecodedSecret); Keycloak
+ * shows their base32 in the QR code. With `secretEncoding: "BASE32"` (secrets
+ * imported from elsewhere) the value already is base32.
+ */
+function keycloakOtp(cred) {
+    const secret = jsonObj(cred.secretData);
+    const data = jsonObj(cred.credentialData);
+    const raw = typeof secret.value === 'string' && secret.value ? secret.value : typeof cred.value === 'string' && cred.value ? cred.value : undefined;
+    const subType = ((0, record_set_1.str)(data.subType) ?? ((0, record_set_1.str)(cred.type) === 'hotp' ? 'hotp' : 'totp')).toLowerCase();
+    if (subType === 'hotp')
+        return { problem: 'HOTP (counter-based) authenticators have no Atlas counterpart; re-enrol in Atlas' };
+    if (!raw)
+        return { problem: 'OTP credential without its secret' };
+    const encoding = (0, record_set_1.str)(data.secretEncoding)?.toUpperCase();
+    const secretBase32 = encoding === 'BASE32' ? raw.toUpperCase().replace(/[\s=]/g, '') : base32(Buffer.from(raw, 'utf8'));
+    const digits = Number(data.digits ?? cred.digits ?? 6);
+    const period = Number(data.period ?? cred.period ?? 30);
+    return {
+        factor: (0, record_set_1.compact)({
+            type: 'totp',
+            secret_base32: secretBase32,
+            digits: Number.isInteger(digits) && digits > 0 ? digits : 6,
+            period: Number.isInteger(period) && period > 0 ? period : 30,
+            algorithm: otpAlgorithmOf((0, record_set_1.str)(data.algorithm) ?? (0, record_set_1.str)(cred.algorithm) ?? 'HmacSHA1'),
+            verified: true,
+            created_at: typeof cred.createdDate === 'number' ? cred.createdDate : undefined,
+        }),
+    };
+}
+/**
+ * Recovery codes (`recovery-authn-codes`): Keycloak keeps base64 SHA-512 of
+ * each remaining code (RecoveryAuthnCodesUtils.hashRawCode), in the order the
+ * user must use them; Atlas accepts any remaining one.
+ */
+function keycloakRecoveryCodes(cred) {
+    const codes = (0, record_set_1.objs)(jsonObj(cred.secretData).codes)
+        .map((c) => (0, record_set_1.str)(c.encodedHashedValue))
+        .filter((h) => !!h);
+    if (!codes.length)
+        return null;
+    return (0, record_set_1.compact)({
+        type: 'backup_codes',
+        backup_code_hashes: codes.map((hash) => ({ algorithm: 'sha512', hash, params: { encoding: 'base64' } })),
+        verified: true,
+        created_at: typeof cred.createdDate === 'number' ? cred.createdDate : undefined,
+    });
+}
+/**
+ * A WebAuthn credential (`webauthn` second factor or `webauthn-passwordless`
+ * passkey). `credentialId` is standard base64 and `credentialPublicKey` the
+ * base64url COSE key (CredentialPublicKeyConverter); both become base64url.
+ */
+function keycloakPasskey(cred, rpId) {
+    const data = jsonObj(cred.credentialData);
+    const credentialId = (0, record_set_1.str)(data.credentialId);
+    const publicKey = (0, record_set_1.str)(data.credentialPublicKey);
+    if (!credentialId || !publicKey)
+        return { problem: 'WebAuthn credential without its id or public key' };
+    if (!rpId)
+        return { problem: 'WebAuthn credential with no relying-party id (pass --set keycloak-rp-id=<host>)' };
+    const aaguid = (0, record_set_1.str)(data.aaguid);
+    const counter = Number(data.counter);
+    return {
+        passkey: (0, record_set_1.compact)({
+            credential_id: base64url(credentialId),
+            public_key: base64url(publicKey),
+            sign_count: Number.isInteger(counter) && counter >= 0 ? counter : undefined,
+            rp_id: rpId,
+            transports: (0, record_set_1.strs)(data.transports).sort(),
+            aaguid: aaguid && aaguid !== '00000000-0000-0000-0000-000000000000' ? aaguid : undefined,
+            name: (0, record_set_1.str)(cred.userLabel),
+            created_at: typeof cred.createdDate === 'number' ? cred.createdDate : undefined,
+        }),
+    };
+}
+// ── identities and connections ──────────────────────────────────────────────
+function mapFederatedIdentity(fi, userId, idps, connections) {
+    const alias = (0, record_set_1.str)(fi.identityProvider);
+    const subject = (0, record_set_1.str)(fi.userId);
+    if (!alias || !subject)
+        return null;
+    const idp = idps.get(alias);
+    const providerId = (0, record_set_1.str)(idp?.providerId) ?? alias;
+    const userName = (0, record_set_1.str)(fi.userName);
+    const email = userName?.includes('@') ? userName.toLowerCase() : undefined;
+    if (connections.has(alias)) {
+        return (0, record_set_1.compact)({ user_id: userId, provider: alias, provider_user_id: subject, kind: providerId === 'saml' ? 'saml' : 'oidc', sso_connection_id: alias, email, profile: (0, record_set_1.bag)((0, record_set_1.compact)({ username: userName })) });
+    }
+    const provider = KC_SOCIAL[providerId] ?? (0, translate_kit_1.socialKey)(providerId) ?? alias;
+    return (0, record_set_1.compact)({
+        user_id: userId,
+        provider,
+        provider_user_id: subject,
+        kind: idp ? 'oauth' : undefined,
+        email,
+        profile: (0, record_set_1.bag)((0, record_set_1.compact)({ username: userName, keycloak_alias: alias !== provider ? alias : undefined })),
+    });
+}
+function ssoConnection(idp, o) {
+    const alias = (0, record_set_1.str)(idp.alias);
+    const name = (0, record_set_1.str)(idp.displayName) ?? alias;
+    const config = (0, record_set_1.isObj)(idp.config) ? idp.config : {};
+    const domains = [...new Set(o.domains.filter((d) => !!d).map((d) => d.toLowerCase()))];
+    const realmUrl = o.baseUrl ? `${o.baseUrl}/realms/${o.realm}` : undefined;
+    if ((0, record_set_1.str)(idp.providerId) === 'saml') {
+        const certs = ((0, record_set_1.str)(config.signingCertificate) ?? '').split(',').map((c) => c.trim()).filter(Boolean);
+        if (certs.length > 1)
+            o.warn(`SAML identity provider ${name}: it has ${certs.length} signing certificates; the first was imported, add the others in Atlas.`);
+        return (0, record_set_1.compact)({
+            id: alias,
+            name,
+            organization_id: o.organizationId,
+            protocol: 'saml',
+            domains,
+            enabled: idp.enabled !== false,
+            saml: (0, record_set_1.compact)({
+                idp_entity_id: (0, record_set_1.str)(config.idpEntityId),
+                idp_sso_url: (0, record_set_1.str)(config.singleSignOnServiceUrl),
+                idp_certificate: certs[0] ? pem(certs[0]) : undefined,
+                idp_metadata_url: (0, record_set_1.str)(config.metadataDescriptorUrl),
+                // The IdP knows Keycloak by these: they change to Atlas's values at cutover.
+                sp_entity_id: (0, record_set_1.str)(config.entityId) ?? realmUrl,
+                sp_acs_url: realmUrl ? `${realmUrl}/broker/${alias}/endpoint` : undefined,
+            }),
+        });
+    }
+    const secret = (0, record_set_1.str)(config.clientSecret);
+    // The Admin API masks secrets; a realm export keeps them, unless they live in a vault.
+    const realSecret = secret && !/^\*+$/.test(secret) && !secret.startsWith('${vault.') ? secret : undefined;
+    if (!realSecret)
+        o.warn(`OIDC identity provider ${name}: its client secret was not available (masked or in a vault); enter it on the SSO connection after the import.`);
+    const issuer = (0, record_set_1.str)(config.issuer);
+    return (0, record_set_1.compact)({
+        id: alias,
+        name,
+        organization_id: o.organizationId,
+        protocol: 'oidc',
+        domains,
+        enabled: idp.enabled !== false,
+        oidc: (0, record_set_1.compact)({
+            issuer,
+            discovery_url: (0, record_set_1.str)(config.metadataDescriptorUrl) ?? (issuer ? `${issuer.replace(/\/+$/, '')}/.well-known/openid-configuration` : undefined),
+            client_id: (0, record_set_1.str)(config.clientId),
+            client_secret: realSecret,
+            scopes: ((0, record_set_1.str)(config.defaultScope) ?? '').split(/[\s,]+/).filter(Boolean),
+        }),
+    });
+}
+/** Flatten a group tree (or a flat list) by path. */
+function indexGroups(groups, parent = '', out = new Map()) {
+    for (const g of groups) {
+        const name = (0, record_set_1.str)(g.name);
+        if (!name)
+            continue;
+        const path = (0, record_set_1.str)(g.path) ?? `${parent}/${name}`;
+        const clientRoles = {};
+        for (const [client, list] of Object.entries((0, record_set_1.isObj)(g.clientRoles) ? g.clientRoles : {}))
+            clientRoles[client] = (0, record_set_1.strs)(list);
+        out.set(path, { id: (0, record_set_1.str)(g.id) ?? path, name, path, realmRoles: (0, record_set_1.strs)(g.realmRoles), clientRoles, attributes: g.attributes });
+        indexGroups((0, record_set_1.objs)(g.subGroups), path, out);
+    }
+    return out;
+}
+/**
+ * A user's app-role keys: realm and client roles mapped to the user, plus the
+ * roles of every group they belong to and of that group's ancestors (Keycloak
+ * hands a member all of those), plus one role per group with groups-as-roles.
+ */
+function userRoleKeys(u, groups, realm, groupRoles) {
+    const keys = new Set();
+    const addRealm = (name) => {
+        if (!isBuiltInRole(name))
+            keys.add((0, translate_kit_1.keyOf)(name));
+    };
+    const addClient = (client, names) => {
+        if (isBuiltInClient(client, realm))
+            return;
+        for (const n of names)
+            keys.add(clientRoleKey(client, n));
+    };
+    (0, record_set_1.strs)(u.realmRoles).forEach(addRealm);
+    for (const [client, names] of Object.entries((0, record_set_1.isObj)(u.clientRoles) ? u.clientRoles : {}))
+        addClient(client, (0, record_set_1.strs)(names));
+    for (const path of (0, record_set_1.strs)(u.groups)) {
+        if (groupRoles)
+            keys.add(groupKey(path));
+        const parts = path.split('/').filter(Boolean);
+        for (let i = 1; i <= parts.length; i++) {
+            const g = groups.get(`/${parts.slice(0, i).join('/')}`);
+            if (!g)
+                continue;
+            g.realmRoles.forEach(addRealm);
+            for (const [client, names] of Object.entries(g.clientRoles))
+                addClient(client, names);
+        }
+    }
+    return [...keys];
+}
+function isBuiltInRole(name) {
+    return BUILT_IN_ROLES.has(name) || name.startsWith('default-roles-');
+}
+function isBuiltInClient(clientId, realm) {
+    // The master realm has one `<realm>-realm` admin client per realm.
+    return BUILT_IN_CLIENTS.has(clientId) || (realm === 'master' && clientId.endsWith('-realm'));
+}
+/** `acme-web` + `billing` → `acme_web:billing`. */
+function clientRoleKey(clientId, role) {
+    return `${(0, translate_kit_1.keyOf)(clientId)}:${(0, translate_kit_1.keyOf)(role)}`;
+}
+/** `/Engineering/Backend` → `group:engineering_backend`. */
+function groupKey(path) {
+    return `group:${(0, translate_kit_1.keyOf)(path.split('/').filter(Boolean).join('_'))}`;
+}
+// ── small helpers ───────────────────────────────────────────────────────────
+/** Keycloak keeps credential data as JSON strings inside the JSON. */
+function jsonObj(v) {
+    if ((0, record_set_1.isObj)(v))
+        return v;
+    if (typeof v !== 'string' || !v.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(v);
+        return (0, record_set_1.isObj)(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** `{ dept: ["R&D"], tags: ["a", "b"] }` → `{ dept: "R&D", tags: ["a", "b"] }`. */
+function unwrapAttributes(v) {
+    const out = {};
+    for (const [k, raw] of Object.entries((0, record_set_1.isObj)(v) ? v : {})) {
+        const list = Array.isArray(raw) ? raw.filter((x) => x !== null && x !== undefined && x !== '') : raw === null || raw === undefined || raw === '' ? [] : [raw];
+        if (list.length === 1)
+            out[k] = list[0];
+        else if (list.length > 1)
+            out[k] = list;
+    }
+    return out;
+}
+const OTP_ALGORITHMS = { hmacsha1: 'SHA1', hmacsha256: 'SHA256', hmacsha512: 'SHA512', sha1: 'SHA1', sha256: 'SHA256', sha512: 'SHA512' };
+/** `HmacSHA256` → `SHA256` (SHA1 for anything unknown, Keycloak's default). */
+function otpAlgorithmOf(raw) {
+    return OTP_ALGORITHMS[raw.toLowerCase().replace(/[^a-z0-9]/g, '')] ?? 'SHA1';
+}
+const B32 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+/** RFC 4648 base32, upper case, no padding. */
+function base32(bytes) {
+    let out = '';
+    let bits = 0;
+    let value = 0;
+    for (const b of bytes) {
+        value = (value << 8) | b;
+        bits += 8;
+        while (bits >= 5) {
+            out += B32.charAt((value >>> (bits - 5)) & 31);
+            bits -= 5;
+        }
+        value &= (1 << bits) - 1;
+    }
+    if (bits > 0)
+        out += B32.charAt((value << (5 - bits)) & 31);
+    return out;
+}
+/** Standard or URL-safe base64 (padded or not) → unpadded base64url. */
+function base64url(s) {
+    return s.replace(/\s+/g, '').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function pem(b64) {
+    const body = b64.replace(/-----[^-]+-----/g, '').replace(/\s+/g, '');
+    return `-----BEGIN CERTIFICATE-----\n${body.match(/.{1,64}/g).join('\n')}\n-----END CERTIFICATE-----`;
+}
+/** Export a realm from an export file (hashes and OTP secrets included) or the Admin API (no secrets). */
+async function exportKeycloak(o) {
+    let snap;
+    if (o.exportDocs) {
+        snap = readKeycloakExport(o.exportDocs, o.realm);
+        if (o.api?.baseUrl)
+            snap.baseUrl = keycloakBase(o.api.baseUrl);
+    }
+    else {
+        if (!o.api || !o.realm)
+            throw new Error('Keycloak: name the realm and give an admin credential, or a realm export.');
+        const warnings = [];
+        snap = await fetchKeycloakRealm(keycloakAdminHttp({ ...o.api, realm: o.realm }), { realm: o.realm, baseUrl: o.api.baseUrl, onProgress: o.onProgress, warn: (m) => warnings.push(m) });
+        const set = mapKeycloak(snap, o);
+        for (const w of warnings)
+            set.warn(w);
+        return set;
+    }
+    return mapKeycloak(snap, o);
+}
+//# sourceMappingURL=keycloak.js.map