@faable/faable 1.31.0 → 1.32.0

package/dist/api/auth_admin.js

@@ -0,0 +1,67 @@
+import { FaableAuthApi } from '@faable/auth-sdk';
+import { CredentialsStore } from '../lib/CredentialsStore.js';
+import { log } from '../log.js';
+import { loadLiveCredentials } from './session.js';
+
+// Default tenant host. `faable auth` is customer-facing: a customer targets
+// their own tenant with --auth-url https://<account>.auth.faable.link (or
+// FAABLE_AUTH_URL); the default points at the Faable tenant.
+const DEFAULT_AUTH_URL = 'https://faable.auth.faable.link';
+// Build a management-API client for the Auth server reusing the CLI session
+// (FAABLE_TOKEN → `faable login` credentials, auto-refreshed). The bearer is
+// sent as-is and the SERVER decides whether it may manage the target tenant
+// (today MGMT_AUTH_ENFORCE is authz dry-run; when enforced, tokens without the
+// management audience/scopes for the tenant will get 403 — see
+// auth/docs/management-api-m2m-token.md for the M2M path).
+const requireAuthAdmin = async (opts = {}) => {
+    let token = process.env.FAABLE_TOKEN;
+    if (!token) {
+        const store = new CredentialsStore();
+        const config = await loadLiveCredentials(store);
+        if (config?.apikey && !config.token) {
+            // Deploy API keys are not Auth management credentials.
+            log.error("❌ You are logged in with an API key, but `faable auth` needs a browser session. Run 'faable login' (without --apikey) first.");
+            process.exit(1);
+        }
+        token = config?.token;
+    }
+    if (!token) {
+        log.error("❌ Not logged in. Run 'faable login' first.");
+        process.exit(1);
+    }
+    const domain = opts.authUrl || process.env.FAABLE_AUTH_URL || DEFAULT_AUTH_URL;
+    const account = opts.account || process.env.FAABLE_AUTH_ACCOUNT;
+    return new FaableAuthApi({
+        domain,
+        ...(account ? { headers: { account_id: account } } : {}),
+        // Static bearer: passing no `auth` keeps sdk-base from attaching any token
+        // strategy, so this header is used verbatim on every request.
+        fetcher: { headers: { Authorization: `Bearer ${token}` } }
+    });
+};
+// Translate raw management-API failures into actionable CLI errors. Everything
+// else is rethrown untouched (FaableApiError messages already carry
+// status+url) and lands in the global yargs .fail() handler.
+const hintAuthError = (e) => {
+    const status = e?.response?.status;
+    if (status === 401) {
+        throw new Error("Unauthorized (401) by the Auth management API. Your session may have expired — run 'faable login' and retry.");
+    }
+    if (status === 403) {
+        throw new Error('Forbidden (403): your session is not allowed to manage this tenant. Check --auth-url/--account, or use credentials with management access for it.');
+    }
+    throw e;
+};
+// Wrap a yargs handler so management-API errors surface with the hints above.
+const withAuthHints = (handler) => {
+    return async (args) => {
+        try {
+            await handler(args);
+        }
+        catch (e) {
+            hintAuthError(e);
+        }
+    };
+};
+
+export { hintAuthError, requireAuthAdmin, withAuthHints };

package/dist/commands/auth/actions/create.js

@@ -0,0 +1,62 @@
+import fs from 'fs-extra';
+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';
+
+const actions_create = {
+    command: 'create',
+    describe: 'Create an action',
+    builder: yargs => json_option(tenant_options(yargs))
+        .option('name', {
+        alias: 'n',
+        type: 'string',
+        demandOption: true,
+        description: 'Action name (max 200 chars)'
+    })
+        .option('trigger', {
+        alias: 't',
+        type: 'string',
+        choices: ['post-login', 'continue'],
+        demandOption: true,
+        description: 'Trigger point'
+    })
+        .option('code-file', {
+        alias: 'f',
+        type: 'string',
+        description: 'Path to a JS file with the action code'
+    })
+        .option('disabled', {
+        type: 'boolean',
+        default: false,
+        description: 'Create the action disabled'
+    })
+        .option('order', {
+        type: 'number',
+        description: 'Execution order (lower runs first, default 0)'
+    })
+        .example('$0 auth actions create -n add-claims -t post-login -f ./claims.js', 'Create a post-login action from a file')
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        let code;
+        if (args.codeFile) {
+            if (!(await fs.pathExists(args.codeFile))) {
+                throw new Error(`Code file not found: ${args.codeFile}`);
+            }
+            code = await fs.readFile(args.codeFile, 'utf8');
+        }
+        const api = await requireAuthAdmin(args);
+        const action = await api.actionCreate({
+            name: args.name,
+            trigger: args.trigger,
+            ...(code !== undefined ? { code } : {}),
+            ...(args.disabled ? { enabled: false } : {}),
+            ...(args.order !== undefined ? { order: args.order } : {})
+        });
+        if (args.json)
+            return print_json(action);
+        log.info(`✅ Created action ${action.id} (${action.name}, trigger ${action.trigger})`);
+    })
+};
+
+export { actions_create };

package/dist/commands/auth/actions/get.js

@@ -0,0 +1,40 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { json_option, tenant_options } from '../options.js';
+import { print_json, yes_no } from '../render.js';
+
+const actions_get = {
+    command: 'get <action_id>',
+    describe: 'Show an action (use --code to print its source)',
+    builder: yargs => json_option(tenant_options(yargs))
+        .positional('action_id', {
+        type: 'string',
+        demandOption: true,
+        description: 'Action identifier'
+    })
+        .option('code', {
+        type: 'boolean',
+        default: false,
+        description: 'Print the action source code'
+    })
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const action = await api.actionGet(args.action_id);
+        if (args.json)
+            return print_json(action);
+        log.info(`⚙️ ${action.id}`);
+        log.info(`  Name:    ${action.name ?? '-'}`);
+        log.info(`  Trigger: ${action.trigger ?? '-'}`);
+        log.info(`  Enabled: ${yes_no(action.enabled)}`);
+        log.info(`  Order:   ${action.order ?? 0}`);
+        log.info(`  Created: ${action.createdAt ?? '-'}`);
+        if (args.code) {
+            log.info('  Code:');
+            // Raw to stdout so it can be piped to a file untouched.
+            process.stdout.write((action.code ?? '') + '\n');
+        }
+    })
+};
+
+export { actions_get };

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

@@ -0,0 +1,19 @@
+import { actions_create } from './create.js';
+import { actions_get } from './get.js';
+import { actions_list } from './list.js';
+import { actions_rm } from './rm.js';
+
+const actions = {
+    command: 'actions',
+    describe: 'Manage auth actions (login-flow hooks)',
+    builder: yargs => yargs
+        .command(actions_list)
+        .command(actions_get)
+        .command(actions_create)
+        .command(actions_rm)
+        .demandCommand(1)
+        .showHelpOnFail(false),
+    handler: () => { }
+};
+
+export { actions };

package/dist/commands/auth/actions/list.js

@@ -0,0 +1,43 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { json_option, list_options, tenant_options } from '../options.js';
+import { fetch_items } from '../paging.js';
+import { print_json, yes_no, when, table_lines } from '../render.js';
+
+const actions_list = {
+    command: 'list',
+    describe: 'List actions',
+    builder: yargs => json_option(list_options(tenant_options(yargs)))
+        .option('query', {
+        type: 'string',
+        description: 'FaableQL filter, e.g. "trigger:post-login"'
+    })
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const { items, more } = await fetch_items(api.actionList({ query: args.query, pageSize: args.limit }), args.all);
+        if (args.json)
+            return print_json(items);
+        if (items.length === 0) {
+            log.info('📭 No actions.');
+            return;
+        }
+        log.info(`⚙️ ${items.length} action(s):`);
+        const rows = items.map(a => [
+            a.id ?? '-',
+            a.name ?? '-',
+            a.trigger ?? '-',
+            yes_no(a.enabled),
+            String(a.order ?? 0),
+            when(a.createdAt)
+        ]);
+        for (const line of table_lines(['ID', 'NAME', 'TRIGGER', 'ENABLED', 'ORDER', 'CREATED'], rows)) {
+            log.info(`  ${line}`);
+        }
+        if (more) {
+            log.info('… more results available: raise --limit or use --all.');
+        }
+    })
+};
+
+export { actions_list };

package/dist/commands/auth/actions/rm.js

@@ -0,0 +1,45 @@
+import prompts from 'prompts';
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { tenant_options } from '../options.js';
+
+const actions_rm = {
+    command: 'rm <action_id>',
+    describe: 'Delete an action',
+    builder: yargs => tenant_options(yargs)
+        .positional('action_id', {
+        type: 'string',
+        demandOption: true,
+        description: 'Action identifier'
+    })
+        .option('yes', {
+        alias: 'y',
+        type: 'boolean',
+        default: false,
+        description: 'Skip the confirmation prompt'
+    })
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        // Fetch first: shows WHAT will be deleted and 404s before the prompt.
+        const action = await api.actionGet(args.action_id);
+        if (!args.yes) {
+            const { confirm } = await prompts({
+                type: 'toggle',
+                name: 'confirm',
+                message: `Delete action "${action.name}" (${action.id}, trigger ${action.trigger})?`,
+                initial: false,
+                active: 'yes',
+                inactive: 'no'
+            });
+            if (!confirm) {
+                log.info('Cancelled.');
+                return;
+            }
+        }
+        await api.actionDelete(args.action_id);
+        log.info(`🗑️ Deleted action ${args.action_id}.`);
+    })
+};
+
+export { actions_rm };

package/dist/commands/auth/clients/create.js

@@ -0,0 +1,56 @@
+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';
+
+const clients_create = {
+    command: 'create',
+    describe: 'Create an OAuth client',
+    builder: yargs => json_option(tenant_options(yargs))
+        .option('name', {
+        alias: 'n',
+        type: 'string',
+        demandOption: true,
+        description: 'Client name'
+    })
+        .option('description', {
+        alias: 'd',
+        type: 'string',
+        description: 'Client description'
+    })
+        .option('callback', {
+        type: 'string',
+        array: true,
+        description: 'Allowed callback (redirect) URL — repeatable'
+    })
+        .option('logout-url', {
+        type: 'string',
+        array: true,
+        description: 'Allowed post-logout URL — repeatable'
+    })
+        .option('web-origin', {
+        type: 'string',
+        array: true,
+        description: 'Allowed web origin (CORS) — repeatable'
+    })
+        .example('$0 auth clients create -n my-app --callback https://app.example.com/callback', 'Create a client with one redirect URL')
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const client = await api.clientCreate({
+            name: args.name,
+            ...(args.description ? { description: args.description } : {}),
+            ...(args.callback?.length ? { callbacks: args.callback } : {}),
+            ...(args.logoutUrl?.length ? { logout_urls: args.logoutUrl } : {}),
+            ...(args.webOrigin?.length ? { web_origins: args.webOrigin } : {})
+        });
+        if (args.json)
+            return print_json(client);
+        log.info(`✅ Created client "${client.name}" (${client.id})`);
+        log.info(`  Client ID:     ${client.client_id}`);
+        log.info(`  Client secret: ${client.client_secret}`);
+        log.info('  ⚠️ Store the secret now — treat it like a password.');
+    })
+};
+
+export { clients_create };

package/dist/commands/auth/clients/get.js

@@ -0,0 +1,46 @@
+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 { resolve_client } from './resolve.js';
+
+const clients_get = {
+    command: 'get <client_id>',
+    describe: 'Show an OAuth client',
+    builder: yargs => json_option(tenant_options(yargs))
+        .positional('client_id', {
+        type: 'string',
+        demandOption: true,
+        description: 'Client resource id or OAuth client_id'
+    })
+        .option('secret', {
+        type: 'boolean',
+        default: false,
+        description: 'Also print the client secret'
+    })
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const client = await resolve_client(api, args.client_id);
+        if (args.json)
+            return print_json(client);
+        log.info(`🔑 ${client.name ?? client.id}`);
+        log.info(`  ID:          ${client.id}`);
+        log.info(`  Client ID:   ${client.client_id ?? '-'}`);
+        if (args.secret) {
+            log.info(`  Secret:      ${client.client_secret ?? '-'}`);
+        }
+        if (client.description)
+            log.info(`  Description: ${client.description}`);
+        log.info(`  Callbacks:   ${client.callbacks?.length ? client.callbacks.join(', ') : '-'}`);
+        if (client.logout_urls?.length) {
+            log.info(`  Logout URLs: ${client.logout_urls.join(', ')}`);
+        }
+        if (client.web_origins?.length) {
+            log.info(`  Web origins: ${client.web_origins.join(', ')}`);
+        }
+        log.info(`  Created:     ${client.createdAt ?? '-'}`);
+    })
+};
+
+export { clients_get };

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

@@ -0,0 +1,19 @@
+import { clients_create } from './create.js';
+import { clients_get } from './get.js';
+import { clients_list } from './list.js';
+import { clients_rm } from './rm.js';
+
+const clients = {
+    command: 'clients',
+    describe: 'Manage OAuth clients',
+    builder: yargs => yargs
+        .command(clients_list)
+        .command(clients_get)
+        .command(clients_create)
+        .command(clients_rm)
+        .demandCommand(1)
+        .showHelpOnFail(false),
+    handler: () => { }
+};
+
+export { clients };

package/dist/commands/auth/clients/list.js

@@ -0,0 +1,41 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { json_option, list_options, tenant_options } from '../options.js';
+import { fetch_items } from '../paging.js';
+import { print_json, truncate, when, table_lines } from '../render.js';
+
+const clients_list = {
+    command: 'list',
+    describe: 'List OAuth clients',
+    builder: yargs => json_option(list_options(tenant_options(yargs)))
+        .option('q', {
+        type: 'string',
+        description: 'Full-text search over name/description/client_id'
+    })
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const { items, more } = await fetch_items(api.clientList({ q: args.q, pageSize: args.limit }), args.all);
+        if (args.json)
+            return print_json(items);
+        if (items.length === 0) {
+            log.info('📭 No clients.');
+            return;
+        }
+        log.info(`🔑 ${items.length} client(s):`);
+        const rows = items.map(c => [
+            c.client_id ?? '-',
+            truncate(c.name, 28),
+            String(c.callbacks?.length ?? 0),
+            when(c.createdAt)
+        ]);
+        for (const line of table_lines(['CLIENT_ID', 'NAME', 'CALLBACKS', 'CREATED'], rows)) {
+            log.info(`  ${line}`);
+        }
+        if (more) {
+            log.info('… more results available: raise --limit or use --all.');
+        }
+    })
+};
+
+export { clients_list };

package/dist/commands/auth/clients/resolve.js

@@ -0,0 +1,21 @@
+// Accept either the resource id (the /client/:id param) or the OAuth
+// `client_id`. The direct lookup rejects a non-resource id with 400 (schema
+// format) or 404 — on either, fall back to a search (the management list is
+// searchable by client_id) and use a single exact match.
+const resolve_client = async (api, id) => {
+    try {
+        return await api.clientGet(id);
+    }
+    catch (e) {
+        const status = e?.response?.status;
+        if (status !== 404 && status !== 400)
+            throw e;
+        const candidates = await api.clientList({ q: id, pageSize: 10 }).pass();
+        const exact = candidates.results.filter(c => c.client_id === id);
+        if (exact.length === 1)
+            return exact[0];
+        throw new Error(`Client not found: ${id}`, { cause: e });
+    }
+};
+
+export { resolve_client };

package/dist/commands/auth/clients/rm.js

@@ -0,0 +1,45 @@
+import prompts from 'prompts';
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { tenant_options } from '../options.js';
+import { resolve_client } from './resolve.js';
+
+const clients_rm = {
+    command: 'rm <client_id>',
+    describe: 'Delete an OAuth client',
+    builder: yargs => tenant_options(yargs)
+        .positional('client_id', {
+        type: 'string',
+        demandOption: true,
+        description: 'Client resource id or OAuth client_id'
+    })
+        .option('yes', {
+        alias: 'y',
+        type: 'boolean',
+        default: false,
+        description: 'Skip the confirmation prompt'
+    })
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const client = await resolve_client(api, args.client_id);
+        if (!args.yes) {
+            const { confirm } = await prompts({
+                type: 'toggle',
+                name: 'confirm',
+                message: `Delete client "${client.name}" (${client.client_id})? Apps using it will stop authenticating.`,
+                initial: false,
+                active: 'yes',
+                inactive: 'no'
+            });
+            if (!confirm) {
+                log.info('Cancelled.');
+                return;
+            }
+        }
+        await api.clientDelete(client.id);
+        log.info(`🗑️ Deleted client ${client.client_id} (${client.id}).`);
+    })
+};
+
+export { clients_rm };

package/dist/commands/auth/index.js

@@ -0,0 +1,23 @@
+import { actions } from './actions/index.js';
+import { clients } from './clients/index.js';
+import { logs } from './logs/index.js';
+import { users } from './users/index.js';
+
+// `faable auth` — management commands for a Faable Auth tenant. Auth: reuses
+// the `faable login` session (or FAABLE_TOKEN); tenant: --auth-url /
+// FAABLE_AUTH_URL (defaults to the Faable tenant host). See
+// src/api/auth_admin.ts.
+const auth = {
+    command: 'auth',
+    describe: 'Manage Faable Auth (users, actions, clients, audit logs)',
+    builder: yargs => yargs
+        .command(users)
+        .command(actions)
+        .command(clients)
+        .command(logs)
+        .demandCommand(1)
+        .showHelpOnFail(false),
+    handler: () => { }
+};
+
+export { auth };

package/dist/commands/auth/logs/get.js

@@ -0,0 +1,48 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { json_option, tenant_options } from '../options.js';
+import { print_json, log_status_badge } from '../render.js';
+
+const logs_get = {
+    command: 'get <log_id>',
+    describe: 'Show an audit log entry',
+    builder: yargs => json_option(tenant_options(yargs))
+        .positional('log_id', {
+        type: 'string',
+        demandOption: true,
+        description: 'Log entry identifier'
+    })
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const entry = await api.logGet(args.log_id);
+        if (args.json)
+            return print_json(entry);
+        log.info(`📜 ${entry.id}`);
+        log.info(`  Date:    ${entry.createdAt ?? '-'}`);
+        log.info(`  Type:    ${entry.type ?? '-'}`);
+        log.info(`  Status:  ${log_status_badge(entry.status)}`);
+        if (entry.message)
+            log.info(`  Message: ${entry.message}`);
+        const refs = [
+            ['User', entry.user],
+            ['Client', entry.client],
+            ['Connection', entry.connection],
+            ['Team', entry.team],
+            ['Identity', entry.identity]
+        ];
+        for (const [label, ref] of refs) {
+            if (!ref)
+                continue;
+            const id = typeof ref === 'string' ? ref : ref.id;
+            if (id)
+                log.info(`  ${label}:${' '.repeat(Math.max(1, 8 - label.length))}${id}`);
+        }
+        if (entry.data !== undefined && entry.data !== null) {
+            log.info('  Data:');
+            process.stdout.write(JSON.stringify(entry.data, null, 2) + '\n');
+        }
+    })
+};
+
+export { logs_get };

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

@@ -0,0 +1,15 @@
+import { logs_get } from './get.js';
+import { logs_list } from './list.js';
+
+const logs = {
+    command: 'logs',
+    describe: 'Browse the audit log (read-only)',
+    builder: yargs => yargs
+        .command(logs_list)
+        .command(logs_get)
+        .demandCommand(1)
+        .showHelpOnFail(false),
+    handler: () => { }
+};
+
+export { logs };

package/dist/commands/auth/logs/list.js

@@ -0,0 +1,90 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { json_option, list_options, tenant_options } from '../options.js';
+import { fetch_items } from '../paging.js';
+import { compose_query, term, time_term } from '../query.js';
+import { print_json, log_status_badge, truncate, table_lines } from '../render.js';
+
+const logs_list = {
+    command: 'list',
+    describe: 'List and filter audit logs',
+    builder: yargs => json_option(list_options(tenant_options(yargs)))
+        .option('query', {
+        type: 'string',
+        description: 'Raw FaableQL filter (combined with the flags below)'
+    })
+        .option('q', {
+        type: 'string',
+        description: 'Full-text search over the log message'
+    })
+        .option('type', {
+        type: 'string',
+        description: 'Exact event type, e.g. admin.user.updated'
+    })
+        .option('status', {
+        type: 'string',
+        choices: ['success', 'failed', 'skipped', 'info'],
+        description: 'Event status'
+    })
+        .option('origin', {
+        type: 'string',
+        description: 'Subsystem prefix, e.g. oauth (matches oauth.*)'
+    })
+        .option('user', {
+        type: 'string',
+        description: 'Filter by subject user id'
+    })
+        .option('client', {
+        type: 'string',
+        description: 'Filter by subject client id'
+    })
+        .option('since', {
+        type: 'string',
+        description: 'From date: unix-millis or YYYY-MM-DD'
+    })
+        .option('until', {
+        type: 'string',
+        description: 'To date: unix-millis or YYYY-MM-DD'
+    })
+        .example('$0 auth logs list --user user_abc123 --since 2026-08-01', "One user's audit trail since August 1st")
+        .example('$0 auth logs list --origin oauth --status failed', 'Failed OAuth events')
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const query = compose_query([
+            term('type', args.type),
+            term('status', args.status),
+            term('origin', args.origin),
+            term('user', args.user),
+            term('client', args.client),
+            time_term('since', args.since),
+            time_term('until', args.until)
+        ], args.query);
+        const api = await requireAuthAdmin(args);
+        const { items, more } = await fetch_items(api.logList({ query, q: args.q, pageSize: args.limit }), args.all);
+        if (args.json)
+            return print_json(items);
+        if (items.length === 0) {
+            log.info('📭 No audit log entries match.');
+            return;
+        }
+        log.info(`📜 ${items.length} entr${items.length === 1 ? 'y' : 'ies'}:`);
+        const rows = items.map(entry => [
+            entry.createdAt ?? '-',
+            entry.type ?? '-',
+            log_status_badge(entry.status),
+            typeof entry.user === 'string'
+                ? entry.user
+                : (entry.user?.id ?? '-'),
+            truncate(entry.message, 48),
+            entry.id ?? '-'
+        ]);
+        for (const line of table_lines(['DATE', 'TYPE', 'STATUS', 'USER', 'MESSAGE', 'ID'], rows)) {
+            log.info(`  ${line}`);
+        }
+        if (more) {
+            log.info('… more results available: raise --limit, use --all, or narrow with --since/--type.');
+        }
+    })
+};
+
+export { logs_list };

package/dist/commands/auth/options.js

@@ -0,0 +1,34 @@
+const tenant_options = (yargs) => yargs
+    .option('auth-url', {
+    type: 'string',
+    description: 'Auth tenant base URL, e.g. https://<account>.auth.faable.link (env FAABLE_AUTH_URL)'
+})
+    .option('account', {
+    type: 'string',
+    description: 'Resolve a different account id on the target host (env FAABLE_AUTH_ACCOUNT)'
+});
+const json_option = (yargs) => yargs.option('json', {
+    type: 'boolean',
+    default: false,
+    description: 'Output raw JSON (for scripting)'
+});
+const list_options = (yargs) => yargs
+    .option('limit', {
+    type: 'number',
+    default: 100,
+    description: 'Max items to fetch in one page (1-200)'
+})
+    .option('all', {
+    type: 'boolean',
+    default: false,
+    description: 'Fetch every page (ignores --limit)'
+})
+    .check(argv => {
+    const limit = argv.limit;
+    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 200)) {
+        throw new Error('--limit must be an integer between 1 and 200');
+    }
+    return true;
+});
+
+export { json_option, list_options, tenant_options };

package/dist/commands/auth/paging.js

@@ -0,0 +1,9 @@
+const fetch_items = async (listing, all) => {
+    if (all) {
+        return { items: await listing.all(), more: false };
+    }
+    const page = await listing.pass();
+    return { items: page.results, more: !!page.next };
+};
+
+export { fetch_items };

package/dist/commands/auth/query.js

@@ -0,0 +1,36 @@
+// Pure helpers to compose FaableQL filter strings from CLI flags.
+//
+// FaableQL grammar (server-side, @faablecloud/faableql): space-separated
+// `field:value` terms, ANDed; values only allow [alnum _ - @ .], so a `:`
+// inside a value (e.g. an ISO-8601 timestamp) is a parse error — dates must be
+// unix-millis or YYYY-MM-DD.
+// Join flag-derived terms with a user-provided --query passthrough.
+const compose_query = (terms, passthrough) => {
+    const parts = terms.filter((t) => !!t);
+    if (passthrough?.trim())
+        parts.push(passthrough.trim());
+    return parts.length ? parts.join(' ') : undefined;
+};
+// Build a single `field:value` term, refusing values FaableQL cannot parse
+// (anything outside [alnum _ - @ .]) with a readable error instead of a
+// server-side 400.
+const term = (field, value) => {
+    if (value === undefined || value === '')
+        return undefined;
+    if (!/^[a-zA-Z0-9_\-@.]+$/.test(value)) {
+        throw new Error(`Invalid value for --${field}: "${value}" (allowed: letters, digits, _ - @ .)`);
+    }
+    return `${field}:${value}`;
+};
+// Validate a --since/--until value: unix-millis or YYYY-MM-DD. ISO timestamps
+// carry ':' which FaableQL rejects, so we fail fast with the fix.
+const time_term = (field, value) => {
+    if (value === undefined || value === '')
+        return undefined;
+    if (!/^\d+$/.test(value) && !/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        throw new Error(`Invalid --${field}: "${value}". Use unix-millis or YYYY-MM-DD (ISO timestamps with ':' are not supported)`);
+    }
+    return `${field}:${value}`;
+};
+
+export { compose_query, term, time_term };

package/dist/commands/auth/render.js

@@ -0,0 +1,48 @@
+// Pure rendering helpers for the `faable auth` read commands.
+const print_json = (data) => {
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+};
+// Left-padded fixed-width table lines. Cells are stringified as-is; column
+// width = max(header, cells).
+const table_lines = (headers, rows) => {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map(r => (r[i] ?? '').length)));
+    const render = (cells) => cells
+        .map((c, i) => (i === cells.length - 1 ? c : (c ?? '').padEnd(widths[i])))
+        .join('  ')
+        .trimEnd();
+    return [render(headers), ...rows.map(render)];
+};
+const yes_no = (v) => (v ? '✓' : '-');
+const truncate = (s, max) => {
+    if (!s)
+        return '-';
+    const one_line = s.replace(/\s+/g, ' ').trim();
+    return one_line.length > max ? one_line.slice(0, max - 1) + '…' : one_line;
+};
+// Relative age, matching the deploy commands' `when` formatting.
+const when = (iso) => {
+    if (!iso)
+        return '-';
+    const ms = Date.now() - new Date(iso).getTime();
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 1)
+        return 'just now';
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h ago`;
+    return `${Math.floor(hours / 24)}d ago`;
+};
+const STATUS_ICONS = {
+    success: '🟢',
+    info: '🔵',
+    skipped: '⚪',
+    failed: '🔴'
+};
+const log_status_badge = (status) => {
+    const s = status || 'info';
+    return `${STATUS_ICONS[s] ?? '⚪'} ${s}`;
+};
+
+export { log_status_badge, print_json, table_lines, truncate, when, yes_no };

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

@@ -0,0 +1,42 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { json_option, tenant_options } from '../options.js';
+import { print_json, yes_no, when } from '../render.js';
+
+const users_get = {
+    command: 'get <user_id>',
+    describe: 'Show a user',
+    builder: yargs => json_option(tenant_options(yargs))
+        .positional('user_id', {
+        type: 'string',
+        demandOption: true,
+        description: 'User identifier (user_…)'
+    })
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const user = await api.userGet(args.user_id);
+        if (args.json)
+            return print_json(user);
+        log.info(`👤 ${user.id}`);
+        log.info(`  Email:      ${user.email ?? '-'} (verified: ${yes_no(user.email_verified)})`);
+        log.info(`  Name:       ${user.name ?? '-'}`);
+        if (user.phone)
+            log.info(`  Phone:      ${user.phone}`);
+        if (user.country_iso)
+            log.info(`  Country:    ${user.country_iso}`);
+        log.info(`  Created:    ${user.createdAt ?? '-'}`);
+        log.info(`  Last login: ${user.last_login ? `${user.last_login} (${when(user.last_login)})` : '-'}${user.last_ip ? ` from ${user.last_ip}` : ''}`);
+        log.info(`  Logins:     ${user.logins_count ?? 0}`);
+        if (user.suspended) {
+            log.info(`  Suspended:  🔴 yes (${user.suspended_at ?? 'unknown date'})`);
+            if (user.suspended_reason)
+                log.info(`  Reason:     ${user.suspended_reason}`);
+        }
+        else {
+            log.info('  Suspended:  no');
+        }
+    })
+};
+
+export { users_get };

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

@@ -0,0 +1,45 @@
+// Resolve the target user ids for a bulk operation. Ids come from argv, from
+// stdin when none are given and input is piped (`… list --json | jq -r … |
+// faable auth users suspend`), or from a '-' placeholder. NB: yargs drops a
+// bare '-' from positionals, so piping with NO ids is the supported spelling;
+// '-' is still honored if it survives parsing. Dedupes, keeps order, and
+// rejects anything that doesn't look like a user id BEFORE any mutation runs.
+const wants_stdin = (args, is_tty) => args.includes('-') || (args.length === 0 && !is_tty);
+const parse_user_ids = (args, stdin) => {
+    const stdin_tokens = stdin === null ? null : stdin.split(/\s+/).filter(Boolean);
+    const raw = [];
+    let stdin_used = false;
+    for (const a of args) {
+        if (a === '-') {
+            if (stdin_tokens === null) {
+                throw new Error("'-' requires ids on stdin (one or more, whitespace-separated)");
+            }
+            raw.push(...stdin_tokens);
+            stdin_used = true;
+        }
+        else {
+            raw.push(a);
+        }
+    }
+    if (stdin_tokens !== null && !stdin_used) {
+        raw.push(...stdin_tokens);
+    }
+    const ids = [...new Set(raw)];
+    if (ids.length === 0) {
+        throw new Error('No user ids given (pass ids, or pipe them via stdin)');
+    }
+    const invalid = ids.filter(id => !/^user_[a-zA-Z0-9]+$/.test(id));
+    if (invalid.length > 0) {
+        throw new Error(`Invalid user id(s): ${invalid.join(', ')} (expected user_…)`);
+    }
+    return ids;
+};
+const read_stdin = async () => {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+};
+
+export { parse_user_ids, read_stdin, wants_stdin };

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

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

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

@@ -0,0 +1,55 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { json_option, list_options, tenant_options } from '../options.js';
+import { compose_query } from '../query.js';
+import { fetch_items } from '../paging.js';
+import { print_json, truncate, yes_no, when, table_lines } from '../render.js';
+
+const users_list = {
+    command: 'list',
+    describe: 'List and filter users',
+    builder: yargs => json_option(list_options(tenant_options(yargs)))
+        .option('query', {
+        type: 'string',
+        description: 'FaableQL filter, e.g. "suspended:true email_verified:false" (fields: email, name, phone, suspended, email_verified, country_iso, locale, last_ip)'
+    })
+        .option('q', {
+        type: 'string',
+        description: 'Full-text search over name/email/phone'
+    })
+        .option('suspended', {
+        type: 'boolean',
+        description: 'Only suspended users (shorthand for query suspended:true)'
+    })
+        .example('$0 auth users list --suspended', 'List suspended users')
+        .example('$0 auth users list --query email_verified:false --limit 50', 'First 50 unverified users')
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const query = compose_query([args.suspended !== undefined && `suspended:${args.suspended}`], args.query);
+        const { items, more } = await fetch_items(api.userList({ query, q: args.q, pageSize: args.limit }), args.all);
+        if (args.json)
+            return print_json(items);
+        if (items.length === 0) {
+            log.info('📭 No users match.');
+            return;
+        }
+        log.info(`👥 ${items.length} user(s):`);
+        const rows = items.map(u => [
+            u.id ?? '-',
+            truncate(u.email, 32),
+            truncate(u.name, 24),
+            yes_no(u.email_verified),
+            u.suspended ? '🔴 suspended' : '-',
+            when(u.last_login)
+        ]);
+        for (const line of table_lines(['ID', 'EMAIL', 'NAME', 'VERIFIED', 'SUSPENDED', 'LAST LOGIN'], rows)) {
+            log.info(`  ${line}`);
+        }
+        if (more) {
+            log.info('… more results available: raise --limit, use --all, or refine the filter.');
+        }
+    })
+};
+
+export { users_list };

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

@@ -0,0 +1,87 @@
+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 { wants_stdin, read_stdin, parse_user_ids } from './ids.js';
+
+const users_suspend = {
+    command: 'suspend [user_ids..]',
+    describe: 'Suspend one or more users (blocks logins, refresh tokens and sessions)',
+    builder: yargs => json_option(tenant_options(yargs))
+        .positional('user_ids', {
+        type: 'string',
+        array: true,
+        description: 'User ids (user_…); omit them to read ids from stdin'
+    })
+        .option('reason', {
+        alias: 'r',
+        type: 'string',
+        description: 'Suspension reason, recorded on the user (max 512 chars)'
+    })
+        .option('yes', {
+        alias: 'y',
+        type: 'boolean',
+        default: false,
+        description: 'Skip the confirmation prompt'
+    })
+        .example('$0 auth users suspend user_abc123 --reason "abuse: proxy payload"', 'Suspend one user')
+        .example('$0 auth users suspend user_a user_b user_c -y -r "abuse wave"', 'Suspend several users without prompting')
+        .example('faable auth users list --query email_verified:false --json | jq -r ".[].id" | $0 auth users suspend -y', 'Bulk-suspend ids piped from a filtered listing')
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const argv_ids = args.user_ids ?? [];
+        const stdin = wants_stdin(argv_ids, !!process.stdin.isTTY)
+            ? await read_stdin()
+            : null;
+        const ids = parse_user_ids(argv_ids, stdin);
+        if (!args.yes) {
+            const preview = ids.slice(0, 5).join(', ') + (ids.length > 5 ? ', …' : '');
+            // In a non-TTY run without --yes, prompts resolves undefined → cancel.
+            const { confirm } = await prompts({
+                type: 'toggle',
+                name: 'confirm',
+                message: `Suspend ${ids.length} user(s) (${preview})?`,
+                initial: false,
+                active: 'yes',
+                inactive: 'no'
+            });
+            if (!confirm) {
+                log.info('Cancelled.');
+                return;
+            }
+        }
+        const api = await requireAuthAdmin(args);
+        const results = [];
+        for (const id of ids) {
+            try {
+                const user = await api.userUpdate(id, {
+                    suspended: true,
+                    ...(args.reason ? { suspended_reason: args.reason } : {})
+                });
+                results.push({ id, suspended: !!user.suspended });
+                // Progress lines stay off stdout in --json mode (machine-clean pipe).
+                if (!args.json) {
+                    log.info(`🔴 Suspended ${id}${user.email ? ` (${user.email})` : ''}`);
+                }
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                results.push({ id, suspended: false, error: message });
+                if (!args.json)
+                    log.error(`❌ Failed to suspend ${id}: ${message}`);
+            }
+        }
+        if (args.json)
+            print_json(results);
+        const failed = results.filter(r => r.error);
+        if (failed.length > 0) {
+            throw new Error(`${failed.length} of ${ids.length} suspension(s) failed${args.json ? '' : ' — see errors above'}`);
+        }
+        if (!args.json) {
+            log.info(`✅ ${ids.length} user(s) suspended. Live access tokens against external APIs remain valid until expiry (≤24h).`);
+        }
+    })
+};
+
+export { users_suspend };

package/dist/index.js

@@ -1,5 +1,6 @@
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
+import { auth } from './commands/auth/index.js';
 import { deploy } from './commands/deploy/index.js';
 import { link_deprecated } from './commands/link/index.js';
 import { login } from './commands/login/index.js';
@@ -22,6 +23,10 @@ yg.scriptName('faable')
     if (banner_shown)
         return;
     banner_shown = true;
+    // --json mode is for piping: keep stdout machine-clean (no banner, no
+    // update-check notice).
+    if (argv.json)
+        return;
     log.info(`Faable CLI ${version}`);
     // `upgrade` does its own (forced) check
     if (argv._[0] !== 'upgrade') {
@@ -44,6 +49,7 @@ yg.scriptName('faable')
     }
 }, true)
     .command(deploy)
+    .command(auth)
     .command(login)
     .command(logout)
     .command(whoami)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/faable",
-  "version": "1.31.0",
+  "version": "1.32.0",
   "main": "dist/index.js",
   "license": "MIT",
   "author": "Marc Pomar <marc@faable.com>",
@@ -27,6 +27,7 @@
   ],
   "dependencies": {
     "@actions/core": "^3.0.0",
+    "@faable/auth-sdk": "^2.5.18",
     "axios": "^1.18.1",
     "fs-extra": "^11.3.2",
     "handlebars": "^4.7.8",