@faable/faable 3.3.2 → 3.4.0

package/dist/commands/auth/users/export.js

@@ -0,0 +1,116 @@
+import { openSync, fchmodSync, writeSync, closeSync } from 'node:fs';
+import prompts from 'prompts';
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { tenant_options } from '../options.js';
+
+// GET /user/export pages at most this many users.
+const PAGE_SIZE = 500;
+const users_export = {
+    command: 'export [file]',
+    describe: 'Export every user as NDJSON, optionally with password hashes (the input of `faable auth users import --from faable`)',
+    builder: yargs => tenant_options(yargs)
+        .positional('file', {
+        type: 'string',
+        description: 'Output file (created with mode 0600). Omit to write to stdout'
+    })
+        .option('include-hashes', {
+        type: 'boolean',
+        default: false,
+        description: 'Include password hashes. Needs the read:password_hashes permission, is audited and notifies the tenant credentials.exported subscribers'
+    })
+        .option('connection', {
+        type: 'string',
+        description: 'Database connection (connection_name) whose hashes are exported. Defaults to the tenant database connection'
+    })
+        .option('force', {
+        type: 'boolean',
+        default: false,
+        description: 'Allow writing password hashes to a terminal'
+    })
+        .option('yes', {
+        alias: 'y',
+        type: 'boolean',
+        default: false,
+        description: 'Skip the confirmation prompt'
+    })
+        .example('$0 auth users export users.ndjson', 'Export profiles and identities')
+        .example('$0 auth users export users.ndjson --include-hashes', 'Export with password hashes (to move users to another tenant or provider)')
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const hashes = !!args['include-hashes'];
+        const to_stdout = !args.file;
+        // A hash dump scrolling past in a terminal ends up in scrollback, screen
+        // recordings and shell logs.
+        if (hashes && to_stdout && process.stdout.isTTY && !args.force) {
+            throw new Error('Refusing to print password hashes to a terminal: pass a file, pipe stdout, or add --force');
+        }
+        if (hashes && !args.yes) {
+            // The prompt goes to stderr so a piped stdout stays pure NDJSON.
+            const { confirm } = await prompts({
+                type: 'toggle',
+                name: 'confirm',
+                message: 'Export password hashes? Anyone holding the file can attack every password offline. The export is audited and notifies the tenant subscribers.',
+                initial: false,
+                active: 'yes',
+                inactive: 'no',
+                stdout: process.stderr
+            }, { onCancel: () => false });
+            if (!confirm) {
+                process.stderr.write('Cancelled.\n');
+                return;
+            }
+        }
+        const api = await requireAuthAdmin(args);
+        // 0600: only the owner can read a file that holds password hashes. The
+        // mode of `openSync` only applies when it creates the file, so an existing
+        // one is tightened explicitly.
+        const fd = to_stdout ? 1 : openSync(args.file, 'w', 0o600);
+        if (!to_stdout)
+            fchmodSync(fd, 0o600);
+        const counts = { users: 0, with_hash: 0, legacy: 0, not_set: 0, no_credential: 0 };
+        try {
+            let cursor;
+            do {
+                const page = await api.userExport({
+                    cursor,
+                    limit: PAGE_SIZE,
+                    connection: args.connection,
+                    include_hashes: hashes
+                });
+                for (const row of page.users) {
+                    writeSync(fd, JSON.stringify(row) + '\n');
+                    counts.users += 1;
+                    if (row.password_hash)
+                        counts.with_hash += 1;
+                    if (row.password_hash_status === 'legacy_unexportable')
+                        counts.legacy += 1;
+                    if (row.password_hash_status === 'not_set')
+                        counts.not_set += 1;
+                    if (row.password_hash_status === 'no_credential')
+                        counts.no_credential += 1;
+                }
+                cursor = page.next_cursor ?? undefined;
+                if (!to_stdout)
+                    log.info(`📤 ${counts.users} user(s)…`);
+            } while (cursor);
+        }
+        finally {
+            if (!to_stdout)
+                closeSync(fd);
+        }
+        // The report goes to stderr: stdout may be the export itself.
+        const report = [
+            `Exported ${counts.users} user(s)${to_stdout ? '' : ` to ${args.file}`}.`,
+            hashes ? `${counts.with_hash} with a password hash.` : 'No password hashes (add --include-hashes).',
+            counts.legacy
+                ? `${counts.legacy} still use a pre-2026 password format that is not exported: they need a password reset, or to sign in once before you export again.`
+                : '',
+            counts.not_set ? `${counts.not_set} never set a password.` : '',
+            counts.no_credential ? `${counts.no_credential} have no password (social or passwordless only).` : ''
+        ].filter(Boolean);
+        process.stderr.write(report.join('\n') + '\n');
+    })
+};
+
+export { users_export };

package/dist/commands/auth/users/import/adapters.js

@@ -0,0 +1,261 @@
+const SOURCES = [
+    'auth0',
+    'clerk',
+    'firebase',
+    'supabase',
+    'keycloak',
+    'faable'
+];
+const SOURCE_FORMAT = {
+    auth0: 'json',
+    clerk: 'csv',
+    firebase: 'json',
+    // A Supabase table dump can be either; `--format` overrides.
+    supabase: 'csv',
+    keycloak: 'json',
+    faable: 'json'
+};
+const str = (v) => typeof v === 'string' && v.trim() !== '' ? v.trim() : undefined;
+const bool = (v) => {
+    if (typeof v === 'boolean')
+        return v;
+    if (v === 'true' || v === 't' || v === '1')
+        return true;
+    if (v === 'false' || v === 'f' || v === '0')
+        return false;
+    return undefined;
+};
+const obj = (v) => {
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+        return v;
+    }
+    if (typeof v === 'string' && v.trim().startsWith('{')) {
+        try {
+            return JSON.parse(v);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+};
+const unpad = (b64) => b64.replace(/=+$/, '');
+// Drops undefined keys so the row stays small and `additionalProperties`
+// never sees a `null` where the server expects a string.
+const clean = (row) => Object.fromEntries(Object.entries(row).filter(([, v]) => v !== undefined && v !== null));
+const map_connection = (name, opts) => opts.connection_map?.[name] ?? name;
+const with_email = (row) => row.email ? { row: clean(row) } : { skip: 'no email' };
+// ── Auth0 ──────────────────────────────────────────────────────────────────
+// The password-hash export Auth0 support hands over (NDJSON, `passwordHash`
+// in bcrypt), or its own bulk-import shape (`custom_password_hash`).
+const auth0 = (r, opts) => {
+    const custom = obj(r.custom_password_hash);
+    const custom_hash = obj(custom?.hash);
+    const password_hash = str(r.passwordHash) ??
+        str(r.password_hash) ??
+        (custom && str(custom_hash?.value)
+            ? String(custom_hash.value)
+            : undefined);
+    const identities = (Array.isArray(r.identities) ? r.identities : [])
+        .map(obj)
+        .filter((i) => !!i && i.provider !== 'auth0' && i.user_id !== undefined)
+        .map(i => ({
+        connection: map_connection(String(i.connection ?? i.provider), opts),
+        identity_id: String(i.user_id)
+    }));
+    // A social-only user exported without `identities`: `provider|id`.
+    const user_id = str(r.user_id);
+    if (!identities.length && user_id?.includes('|') && !user_id.startsWith('auth0|')) {
+        const [provider, id] = user_id.split('|');
+        identities.push({ connection: map_connection(provider, opts), identity_id: id });
+    }
+    return with_email({
+        email: str(r.email),
+        email_verified: bool(r.email_verified),
+        name: str(r.name),
+        given_name: str(r.given_name),
+        family_name: str(r.family_name),
+        picture: str(r.picture),
+        user_metadata: obj(r.user_metadata),
+        app_metadata: obj(r.app_metadata),
+        password_hash,
+        identities: identities.length ? identities : undefined
+    });
+};
+// ── Clerk ──────────────────────────────────────────────────────────────────
+// The CSV from the Clerk dashboard: `password_digest` + `password_hasher`.
+const clerk_hash = (digest, hasher) => {
+    if (!digest)
+        return undefined;
+    switch (hasher) {
+        // Self-describing digests go as they are. Clerk keeps Django's
+        // `pbkdf2_sha256$iterations$salt$hash` unchanged.
+        case 'bcrypt':
+        case 'argon2id':
+        case 'argon2i':
+        case 'pbkdf2_sha256':
+        case 'pbkdf2_sha256_django':
+        case undefined:
+            return digest;
+        case 'scrypt_firebase': {
+            // `<hash>$<salt>$<signer key>$<salt separator>$<rounds>$<mem cost>`
+            const [hash, salt, signer_key, salt_separator, rounds, mem_cost] = digest.split('$');
+            return {
+                algorithm: 'firebase-scrypt',
+                hash,
+                salt,
+                params: { signer_key, salt_separator, rounds, mem_cost }
+            };
+        }
+        default:
+            // md5, sha256, bcrypt_sha256_django…: the server answers
+            // weak_password_hash for that row.
+            return { algorithm: hasher, hash: digest };
+    }
+};
+const clerk = (r) => {
+    const email = str(r.primary_email_address) ?? str(r.email_address);
+    const verified = String(r.verified_email_addresses ?? '')
+        .split(/[|,;\s]+/)
+        .filter(Boolean);
+    const given_name = str(r.first_name);
+    const family_name = str(r.last_name);
+    return with_email({
+        email,
+        email_verified: email ? verified.includes(email) : undefined,
+        given_name,
+        family_name,
+        name: [given_name, family_name].filter(Boolean).join(' ') || undefined,
+        phone: str(r.primary_phone_number),
+        password_hash: clerk_hash(str(r.password_digest), str(r.password_hasher))
+    });
+};
+// ── Firebase ───────────────────────────────────────────────────────────────
+// `firebase auth:export users.json --format=json`. The hash parameters are
+// project-wide and live in the console (Authentication → Users → ⋮ →
+// Password hash parameters), not in the export.
+const FIREBASE_PROVIDERS = {
+    'google.com': 'google',
+    'github.com': 'github',
+    'facebook.com': 'facebook',
+    'apple.com': 'apple',
+    'twitter.com': 'twitter',
+    'microsoft.com': 'microsoft'
+};
+const firebase = (r, opts) => {
+    let password_hash;
+    const hash = str(r.passwordHash);
+    if (hash) {
+        if (!opts.firebase) {
+            throw new Error('Firebase exports need the project hash parameters: --hash-key, --salt-separator, --rounds and --mem-cost (Firebase console → Authentication → Users → ⋮ → Password hash parameters)');
+        }
+        password_hash = {
+            algorithm: 'firebase-scrypt',
+            hash,
+            salt: str(r.salt) ?? '',
+            params: { ...opts.firebase }
+        };
+    }
+    const identities = (Array.isArray(r.providerUserInfo) ? r.providerUserInfo : [])
+        .map(obj)
+        .filter((p) => !!p && p.providerId !== 'password' && p.providerId !== 'phone')
+        .map(p => {
+        const provider = String(p.providerId);
+        return {
+            connection: map_connection(FIREBASE_PROVIDERS[provider] ?? provider.replace(/\.com$/, ''), opts),
+            identity_id: String(p.rawId)
+        };
+    });
+    return with_email({
+        email: str(r.email),
+        email_verified: bool(r.emailVerified),
+        name: str(r.displayName),
+        picture: str(r.photoUrl),
+        phone: str(r.phoneNumber),
+        password_hash,
+        identities: identities.length ? identities : undefined
+    });
+};
+// ── Supabase ───────────────────────────────────────────────────────────────
+// A dump of `auth.users` (CSV or JSON): `encrypted_password` is bcrypt.
+const supabase = (r) => {
+    const meta = obj(r.raw_user_meta_data);
+    return with_email({
+        email: str(r.email),
+        email_verified: !!str(r.email_confirmed_at) || bool(r.email_verified),
+        name: str(meta?.full_name) ?? str(meta?.name),
+        picture: str(meta?.avatar_url) ?? str(meta?.picture),
+        phone: str(r.phone),
+        user_metadata: meta,
+        password_hash: str(r.encrypted_password)
+    });
+};
+// ── Keycloak ───────────────────────────────────────────────────────────────
+// A realm export (`kc.sh export --users realm_file`), or one of its
+// `<realm>-users-N.json` files. Password credentials keep the hash in
+// `secretData` and the algorithm in `credentialData`, both JSON strings.
+const keycloak_hash = (credential) => {
+    const secret = obj(credential.secretData);
+    const data = obj(credential.credentialData);
+    const value = str(secret?.value);
+    const salt = str(secret?.salt);
+    if (!value || !data)
+        return undefined;
+    const algorithm = String(data.algorithm ?? '');
+    const iterations = Number(data.hashIterations);
+    const extra = (obj(data.additionalParameters) ?? {});
+    const first = (k) => Array.isArray(extra[k]) ? String(extra[k][0]) : undefined;
+    if (algorithm === 'argon2') {
+        // Keycloak 24+: parameters split out; rebuild the PHC string.
+        const type = first('type') ?? 'id';
+        const memory = first('memory') ?? '7168';
+        const parallelism = first('parallelism') ?? '1';
+        return `$argon2${type}$v=19$m=${memory},t=${iterations},p=${parallelism}$${unpad(salt ?? '')}$${unpad(value)}`;
+    }
+    return {
+        // `pbkdf2` (no suffix) is PBKDF2-SHA1: sent as such, refused as weak.
+        algorithm: algorithm === 'pbkdf2' ? 'pbkdf2-sha1' : algorithm,
+        hash: value,
+        salt,
+        params: { iterations }
+    };
+};
+const keycloak = (r, opts) => {
+    const credential = (Array.isArray(r.credentials) ? r.credentials : [])
+        .map(obj)
+        .find(c => c?.type === 'password');
+    const identities = (Array.isArray(r.federatedIdentities) ? r.federatedIdentities : [])
+        .map(obj)
+        .filter((i) => !!i)
+        .map(i => ({
+        connection: map_connection(String(i.identityProvider), opts),
+        identity_id: String(i.userId)
+    }));
+    const given_name = str(r.firstName);
+    const family_name = str(r.lastName);
+    return with_email({
+        email: str(r.email),
+        email_verified: bool(r.emailVerified),
+        given_name,
+        family_name,
+        name: [given_name, family_name].filter(Boolean).join(' ') || undefined,
+        password_hash: credential ? keycloak_hash(credential) : undefined,
+        identities: identities.length ? identities : undefined
+    });
+};
+// ── Faable ─────────────────────────────────────────────────────────────────
+// `faable auth users export` output: already the import shape. The server
+// drops `user_id` / `password_hash_status` itself.
+const faable = (r, opts) => {
+    const row = { ...r };
+    if (Array.isArray(row.identities)) {
+        row.identities = row.identities.map(i => ({
+            ...i,
+            connection: map_connection(i.connection, opts)
+        }));
+    }
+    return with_email(row);
+};
+const ADAPTERS = { auth0, clerk, firebase, supabase, keycloak, faable };
+
+export { ADAPTERS, SOURCES, SOURCE_FORMAT };

package/dist/commands/auth/users/import/records.js

@@ -0,0 +1,98 @@
+// Reading an export file into plain records, before any provider-specific
+// mapping. Exports come as a JSON array, a JSON object wrapping the array
+// (`{ "users": [...] }` — Firebase, Keycloak), NDJSON (Auth0, `faable auth
+// users export`) or CSV (Clerk, a Supabase table dump).
+// RFC 4180: comma-separated, `"` quotes a field, `""` is a literal quote, and
+// quoted fields may span lines. The first row is the header.
+const parse_csv = (text) => {
+    const rows = [];
+    let row = [];
+    let field = '';
+    let quoted = false;
+    const input = text.replace(/^\uFEFF/, '');
+    for (let i = 0; i < input.length; i++) {
+        const c = input[i];
+        if (quoted) {
+            if (c === '"') {
+                if (input[i + 1] === '"') {
+                    field += '"';
+                    i++;
+                }
+                else {
+                    quoted = false;
+                }
+            }
+            else {
+                field += c;
+            }
+        }
+        else if (c === '"' && field === '') {
+            quoted = true;
+        }
+        else if (c === ',') {
+            row.push(field);
+            field = '';
+        }
+        else if (c === '\n' || c === '\r') {
+            if (c === '\r' && input[i + 1] === '\n')
+                i++;
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = '';
+        }
+        else {
+            field += c;
+        }
+    }
+    if (quoted)
+        throw new Error('CSV: unterminated quoted field');
+    if (field !== '' || row.length > 0) {
+        row.push(field);
+        rows.push(row);
+    }
+    const [header, ...body] = rows.filter(r => !(r.length === 1 && r[0] === ''));
+    if (!header)
+        return [];
+    return body.map((cells, line) => {
+        if (cells.length !== header.length) {
+            throw new Error(`CSV: row ${line + 2} has ${cells.length} fields, the header has ${header.length}`);
+        }
+        return Object.fromEntries(header.map((h, i) => [h.trim(), cells[i]]));
+    });
+};
+const parse_records = (text, format) => {
+    if (format === 'csv')
+        return parse_csv(text);
+    const trimmed = text.trim();
+    if (!trimmed)
+        return [];
+    if (trimmed.startsWith('[') || trimmed.startsWith('{')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (Array.isArray(parsed))
+                return parsed;
+            if (Array.isArray(parsed?.users))
+                return parsed.users;
+            // A single object on one line is NDJSON with one record.
+            if (!trimmed.includes('\n'))
+                return [parsed];
+        }
+        catch {
+            // Not one JSON document: fall through to NDJSON.
+        }
+    }
+    return trimmed
+        .split(/\r?\n/)
+        .filter(line => line.trim())
+        .map((line, i) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            throw new Error(`NDJSON: line ${i + 1} is not valid JSON`);
+        }
+    });
+};
+
+export { parse_csv, parse_records };

package/dist/commands/auth/users/import.js

@@ -0,0 +1,192 @@
+import { readFile } from 'node:fs/promises';
+import prompts from 'prompts';
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { json_option, tenant_options } from '../options.js';
+import { print_json } from '../render.js';
+import { SOURCES, ADAPTERS, SOURCE_FORMAT } from './import/adapters.js';
+import { parse_records } from './import/records.js';
+
+// The server takes at most this many rows per request (POST /user/import).
+const BATCH_SIZE = 500;
+const parse_connection_map = (pairs = []) => Object.fromEntries(pairs.map(pair => {
+    const [from, to] = pair.split('=');
+    if (!from || !to) {
+        throw new Error(`--map-connection expects provider=connection, got "${pair}"`);
+    }
+    return [from, to];
+}));
+const firebase_config = (args) => {
+    const given = [args['hash-key'], args['salt-separator'], args.rounds, args['mem-cost']];
+    if (given.every(v => v === undefined))
+        return undefined;
+    if (given.some(v => v === undefined)) {
+        throw new Error('--hash-key, --salt-separator, --rounds and --mem-cost go together');
+    }
+    return {
+        signer_key: args['hash-key'],
+        salt_separator: args['salt-separator'],
+        rounds: args.rounds,
+        mem_cost: args['mem-cost']
+    };
+};
+// Reads and adapts the whole file before anything is sent: a malformed file
+// fails here, not after half of it went in.
+const prepare_rows = (text, source, opts) => {
+    const records = parse_records(text, opts.format ?? SOURCE_FORMAT[source]);
+    const rows = [];
+    const skipped = [];
+    records.forEach((raw, i) => {
+        const adapted = ADAPTERS[source](raw, opts);
+        if ('skip' in adapted) {
+            skipped.push({
+                record: i + 1,
+                status: 'error',
+                error: { code: 'unusable_record', message: adapted.skip }
+            });
+        }
+        else {
+            rows.push({ record: i + 1, row: adapted.row });
+        }
+    });
+    return { total: records.length, rows, skipped };
+};
+const users_import = {
+    command: 'import <file>',
+    describe: 'Import users from another provider, with their password hashes (bcrypt, scrypt, Firebase scrypt, PBKDF2, argon2)',
+    builder: yargs => json_option(tenant_options(yargs))
+        .positional('file', {
+        type: 'string',
+        demandOption: true,
+        description: 'The export file of the provider you are leaving'
+    })
+        .option('from', {
+        choices: SOURCES,
+        demandOption: true,
+        description: 'Where the file comes from: auth0 (NDJSON with passwordHash), clerk (CSV), firebase (auth:export JSON), supabase (auth.users dump), keycloak (realm export), faable (faable auth users export)'
+    })
+        .option('format', {
+        choices: ['json', 'csv'],
+        description: 'Override the file format guessed from --from'
+    })
+        .option('connection', {
+        type: 'string',
+        description: 'Database connection (connection_name) the passwords go to. Defaults to the tenant database connection'
+    })
+        .option('map-connection', {
+        type: 'string',
+        array: true,
+        description: 'Rename a social provider to your connection_name, e.g. google-oauth2=google (repeatable)'
+    })
+        .option('update-existing', {
+        type: 'boolean',
+        default: false,
+        description: 'Set the password hash of users that already exist (same email) instead of skipping them'
+    })
+        .option('dry-run', {
+        type: 'boolean',
+        default: false,
+        description: 'Validate every row on the server without writing anything'
+    })
+        .option('hash-key', {
+        type: 'string',
+        description: 'Firebase: base64_signer_key from the password hash parameters'
+    })
+        .option('salt-separator', {
+        type: 'string',
+        description: 'Firebase: base64_salt_separator'
+    })
+        .option('rounds', { type: 'number', description: 'Firebase: rounds' })
+        .option('mem-cost', { type: 'number', description: 'Firebase: mem_cost' })
+        .option('yes', {
+        alias: 'y',
+        type: 'boolean',
+        default: false,
+        description: 'Skip the confirmation prompt'
+    })
+        .example('$0 auth users import auth0-users.ndjson --from auth0 --dry-run', 'Check an Auth0 export without writing anything')
+        .example('$0 auth users import users.json --from firebase --hash-key … --salt-separator Bw== --rounds 8 --mem-cost 14', 'Import a Firebase export with its hash parameters')
+        .example('$0 auth users import users.csv --from clerk --map-connection oauth_google=google -y', 'Import a Clerk CSV without prompting')
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const text = await readFile(args.file, 'utf8');
+        const { total, rows, skipped } = prepare_rows(text, args.from, {
+            format: args.format,
+            connection_map: parse_connection_map(args['map-connection']),
+            firebase: firebase_config(args)
+        });
+        if (rows.length === 0) {
+            throw new Error(`No importable users in ${args.file} (${total} record(s) read)`);
+        }
+        const dry_run = !!args['dry-run'];
+        if (!args.yes && !dry_run) {
+            const { confirm } = await prompts({
+                type: 'toggle',
+                name: 'confirm',
+                message: `Import ${rows.length} user(s) from ${args.from}?`,
+                initial: false,
+                active: 'yes',
+                inactive: 'no'
+            });
+            if (!confirm) {
+                log.info('Cancelled.');
+                return;
+            }
+        }
+        const api = await requireAuthAdmin(args);
+        const results = [...skipped];
+        for (let start = 0; start < rows.length; start += BATCH_SIZE) {
+            const batch = rows.slice(start, start + BATCH_SIZE);
+            const res = await api.userImport({
+                users: batch.map(b => b.row),
+                connection: args.connection,
+                update_existing: !!args['update-existing'],
+                dry_run
+            });
+            for (const r of res.results) {
+                results.push({
+                    record: batch[r.index].record,
+                    email: r.email,
+                    status: r.status,
+                    user_id: r.user_id,
+                    error: r.error
+                });
+            }
+            if (!args.json) {
+                log.info(`${dry_run ? '🔎 Checked' : '📥 Imported'} ${Math.min(start + BATCH_SIZE, rows.length)}/${rows.length}`);
+            }
+        }
+        results.sort((a, b) => a.record - b.record);
+        const count = (s) => results.filter(r => r.status === s).length;
+        const summary = {
+            records: total,
+            created: count('created'),
+            updated: count('updated'),
+            skipped: count('skipped'),
+            errors: count('error')
+        };
+        if (args.json) {
+            print_json({ dry_run, summary, results });
+        }
+        else {
+            for (const r of results.filter(r => r.status === 'error')) {
+                log.error(`❌ record ${r.record}${r.email ? ` (${r.email})` : ''}: ${r.error?.code} — ${r.error?.message}`);
+            }
+            log.info(`${dry_run ? 'Dry run — nothing written. Would create' : 'Created'} ${summary.created}, ${dry_run ? 'update' : 'updated'} ${summary.updated}, skipped ${summary.skipped} existing, ${summary.errors} error(s) out of ${summary.records} record(s).`);
+            if (summary.created + summary.updated > 0 && !dry_run) {
+                log.info('🔐 Imported passwords are upgraded to argon2id the first time each user signs in.');
+            }
+        }
+        if (summary.errors > 0) {
+            // In --json mode stdout must stay one JSON document: the global failure
+            // handler would append its message to it. The exit code carries it.
+            if (args.json) {
+                process.exitCode = 1;
+                return;
+            }
+            throw new Error(`${summary.errors} record(s) were not imported`);
+        }
+    })
+};
+
+export { BATCH_SIZE, prepare_rows, users_import };

package/dist/commands/auth/users/index.js

@@ -1,16 +1,20 @@
+import { users_export } from './export.js';
 import { users_get } from './get.js';
+import { users_import } from './import.js';
 import { users_list } from './list.js';
 import { users_reinstate } from './reinstate.js';
 import { users_suspend } from './suspend.js';
 
 const users = {
     command: 'users',
-    describe: 'List, inspect, suspend and reinstate users',
+    describe: 'List, inspect, suspend, reinstate, import and export users',
     builder: yargs => yargs
         .command(users_list)
         .command(users_get)
         .command(users_suspend)
         .command(users_reinstate)
+        .command(users_import)
+        .command(users_export)
         .demandCommand(1)
         .showHelpOnFail(false),
     handler: () => { }

package/dist/index.js

@@ -24,8 +24,10 @@ yg.scriptName('faable')
         return;
     banner_shown = true;
     // --json mode is for piping: keep stdout machine-clean (no banner, no
-    // update-check notice).
-    if (argv.json)
+    // update-check notice). Same for `auth users export` without a file,
+    // whose stdout IS the export.
+    const exports_to_stdout = argv._.slice(0, 3).join(' ') === 'auth users export' && !argv.file;
+    if (argv.json || exports_to_stdout)
         return;
     log.info(`Faable CLI ${version}`);
     // `upgrade` does its own (forced) check

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/faable",
-  "version": "3.3.2",
+  "version": "3.4.0",
   "main": "dist/index.js",
   "license": "MIT",
   "author": "Marc Pomar <marc@faable.com>",
@@ -27,7 +27,7 @@
   ],
   "dependencies": {
     "@actions/core": "^3.0.0",
-    "@faable/auth-sdk": "^2.6.3",
+    "@faable/auth-sdk": "^2.7.29",
     "axios": "^1.18.1",
     "fs-extra": "^11.3.2",
     "open": "^11.0.0",