@faable/faable 4.6.0 → 4.8.0

package/dist/api/FaableApi.js

@@ -213,6 +213,12 @@ class FaableApi {
     async getDeployment(deployment_id) {
         return data(this.client.get(`/deployment/${deployment_id}`));
     }
+    // Whose failure it is (user | platform | unknown) and its stable code —
+    // the api's own fault attribution. Older apis don't have it: callers treat
+    // a 404 as "no verdict".
+    async getDeploymentFault(deployment_id) {
+        return data(this.client.get(`/deployment/${deployment_id}/fault`));
+    }
     // Build payload of a deployment (runnable descriptor: runtime, profile,
     // size, checksum). Authorized by the caller's access to the parent
     // deployment, so no team header is needed — same posture as getDeployment.

package/dist/api/auth_admin.js

@@ -8,6 +8,7 @@ import { FaableApi } from './FaableApi.js';
 import { AUTH_DOMAIN, createAnonymousAuthApi, createBearerAuthApi } from './auth.js';
 import { requireProject } from './project.js';
 import { loadLiveCredentials, isTokenLive } from './session.js';
+import { apikey_strategy } from './strategies/apikey.strategy.js';
 import { bearer_strategy } from './strategies/bearer.strategy.js';
 
 // The session bearer: FAABLE_TOKEN, else `faable login` (auto-refreshed).
@@ -75,6 +76,12 @@ const chooseAccount = async (project, accounts, store = new ContextStore()) => {
 // per-tenant token the deploy api issues (cached until it expires); the
 // session bearer is the fallback where no such token exists.
 const requireAuthAdmin = async (opts = {}) => {
+    // A deploy API key (the hosted MCP runs each call with the caller's key):
+    // the api issues a narrower tenant token for the tenants of the key's own
+    // project. Same precedence as `context()`: FAABLE_TOKEN wins over it.
+    if (!process.env.FAABLE_TOKEN && process.env.FAABLE_API_KEY) {
+        return requireAuthAdminWithApiKey(opts, process.env.FAABLE_API_KEY);
+    }
     const token = await requireSessionToken();
     const deploy = FaableApi.create({
         authStrategy: bearer_strategy,
@@ -89,6 +96,24 @@ const requireAuthAdmin = async (opts = {}) => {
         account: tenant.account
     });
 };
+// With an API key there is no session bearer to fall back on: no tenant
+// token is a refusal, not "use your own token". Not cached — the hosted
+// server gives each call an empty HOME, and a key's token is narrower than
+// its owner's, so it must never be served to a later session.
+const requireAuthAdminWithApiKey = async (opts, apikey, deploy = FaableApi.create({ authStrategy: apikey_strategy, auth: { apikey } })) => {
+    const tenant = await resolveTenant(opts, deploy);
+    if (!tenant.account) {
+        throw new CliError('usage', `Could not tell which Auth tenant ${tenant.domain} is. Pass --account <account_id>.`);
+    }
+    const issued = await issueTenantToken('', tenant.account, deploy);
+    if (!issued) {
+        throw new CliError('forbidden', `No management token for ${tenant.account} with an API key. It only works for the Auth tenants of the key's own project.`);
+    }
+    return createBearerAuthApi(issued, {
+        domain: tenant.domain,
+        account: tenant.account
+    });
+};
 // Every `faable auth` call used to mint a fresh tenant token — one extra
 // round trip per command, and a burst of them from a script or the MCP
 // server. It lives for minutes (`expires_in`), so it's kept next to the
@@ -209,4 +234,4 @@ const withAuthHints = (handler) => {
     };
 };
 
-export { TenantTokenCache, cachedTenantToken, chooseAccount, hintAuthError, issueTenantToken, requireAuthAdmin, requireSessionToken, resolveAccountByHost, resolveTenant, subject, withAuthHints };
+export { TenantTokenCache, cachedTenantToken, chooseAccount, hintAuthError, issueTenantToken, requireAuthAdmin, requireAuthAdminWithApiKey, requireSessionToken, resolveAccountByHost, resolveTenant, subject, withAuthHints };

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

@@ -1,15 +1,22 @@
 import { requireSessionToken } from '../../../api/auth_admin.js';
 import { FaableApi } from '../../../api/FaableApi.js';
 import { requireProject } from '../../../api/project.js';
+import { apikey_strategy } from '../../../api/strategies/apikey.strategy.js';
 import { bearer_strategy } from '../../../api/strategies/bearer.strategy.js';
 import { ContextStore } from '../../../lib/ContextStore.js';
 import { fetch_page, print_json, table_lines, print, more_hint, list_options } from '../../../lib/listing.js';
 import { log } from '../../../log.js';
 
-const deploy_api = async () => FaableApi.create({
-    authStrategy: bearer_strategy,
-    auth: { token: await requireSessionToken() }
-});
+// A deploy API key (the hosted MCP) lists its own project's tenants too.
+const deploy_api = async () => !process.env.FAABLE_TOKEN && process.env.FAABLE_API_KEY
+    ? FaableApi.create({
+        authStrategy: apikey_strategy,
+        auth: { apikey: process.env.FAABLE_API_KEY }
+    })
+    : FaableApi.create({
+        authStrategy: bearer_strategy,
+        auth: { token: await requireSessionToken() }
+    });
 // `faable auth accounts list` — the Auth tenants of the active project, the
 // ones `faable auth` can manage without --account.
 const accounts_list = {

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

@@ -0,0 +1,10 @@
+import { connections_list } from './list.js';
+
+const connections = {
+    command: 'connections',
+    describe: 'List the login methods of the tenant',
+    builder: yargs => yargs.command(connections_list).demandCommand(1).showHelpOnFail(false),
+    handler: () => { }
+};
+
+export { connections };

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

@@ -0,0 +1,48 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { list_options, fetch_page, from_paginator, print_json, table_lines, print, more_hint } from '../../../lib/listing.js';
+import { tenant_options } from '../options.js';
+import { yes_no } from '../render.js';
+
+// The tenant's login methods: social providers (Google, GitHub…),
+// passwordless (email/SMS codes) and username-password databases.
+const connections_list = {
+    command: 'list',
+    describe: 'List login methods (social, passwordless, database)',
+    builder: yargs => list_options(tenant_options(yargs))
+        .option('enabled', {
+        type: 'boolean',
+        description: 'Only enabled (or, with --no-enabled, disabled) connections'
+    })
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const page = await fetch_page(from_paginator(api.connectionList({
+            ...(args.enabled !== undefined ? { enabled: String(args.enabled) } : {})
+        })), args);
+        // Never the provider secrets: name, type and whether it is on.
+        const data = page.data.map((c) => ({
+            id: c.id,
+            connection_name: c.connection_name,
+            connection_type: c.connection_type,
+            enabled: !!c.enabled,
+            enabled_clients: Array.isArray(c.enabled_clients)
+                ? c.enabled_clients.length
+                : undefined
+        }));
+        if (args.json)
+            return print_json({ ...page, data });
+        if (data.length === 0) {
+            log.info('📭 No connections.');
+            return;
+        }
+        for (const line of table_lines(['ID', 'NAME', 'TYPE', 'ENABLED'], data.map(c => [c.id, c.connection_name ?? '-', c.connection_type ?? '-', yes_no(c.enabled)]))) {
+            print(line);
+        }
+        const hint = more_hint(page);
+        if (hint)
+            log.info(hint);
+    })
+};
+
+export { connections_list };

package/dist/commands/auth/index.js

@@ -1,7 +1,9 @@
 import { accounts, auth_use } from './accounts/index.js';
 import { actions } from './actions/index.js';
 import { clients } from './clients/index.js';
+import { connections } from './connections/index.js';
 import { logs } from './logs/index.js';
+import { sessions } from './sessions/index.js';
 import { users } from './users/index.js';
 
 // `faable auth` — management commands for a Faable Auth tenant. Auth: reuses
@@ -10,12 +12,14 @@ import { users } from './users/index.js';
 // resolveTenant in src/api/auth_admin.ts.
 const auth = {
     command: 'auth',
-    describe: 'Manage Faable Auth (users, actions, clients, audit logs)',
+    describe: 'Manage Faable Auth (users, sessions, logins, actions, clients, audit logs)',
     builder: yargs => yargs
         .command(users)
         .command(actions)
         .command(clients)
         .command(logs)
+        .command(sessions)
+        .command(connections)
         .command(accounts)
         .command(auth_use)
         .demandCommand(1)

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

@@ -2,7 +2,8 @@ import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
 import { log } from '../../../log.js';
 import { list_options, fetch_page, from_paginator, print_json, table_lines, print, more_hint } from '../../../lib/listing.js';
 import { tenant_options } from '../options.js';
-import { compose_query, term, time_term } from '../query.js';
+import { compose_query, term, range_term } from '../query.js';
+import { resolve_user_ref } from '../users/resolve.js';
 import { log_status_badge, truncate } from '../render.js';
 
 const logs_list = {
@@ -33,6 +34,14 @@ const logs_list = {
         .option('user', {
         type: 'string',
         description: 'Filter by subject user id'
+    })
+        .option('email', {
+        type: 'string',
+        description: "Filter by the subject user's email (exactly one user)"
+    })
+        .option('expand-user', {
+        type: 'boolean',
+        description: 'Embed each entry\'s user (email, name) instead of only its id'
     })
         .option('client', {
         type: 'string',
@@ -40,27 +49,35 @@ const logs_list = {
     })
         .option('since', {
         type: 'string',
-        description: 'From date: unix-millis or YYYY-MM-DD'
+        description: 'From: a relative age (30m, 24h, 7d), unix-millis or YYYY-MM-DD'
     })
         .option('until', {
         type: 'string',
-        description: 'To date: unix-millis or YYYY-MM-DD'
+        description: 'To: a relative age (30m, 24h, 7d), 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')
+        .example('$0 auth logs list --type user.login --since 24h --expand-user', 'Who logged in in the last 24 hours')
         .showHelpOnFail(false),
     handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const user = args.email
+            ? await resolve_user_ref(api, args.email)
+            : args.user;
         const query = compose_query([
             term('type', args.type),
             term('status', args.status),
             term('origin', args.origin),
-            term('user', args.user),
+            term('user', user),
             term('client', args.client),
-            time_term('since', args.since),
-            time_term('until', args.until)
+            range_term('since', 'since', args.since),
+            range_term('until', 'until', args.until)
         ], args.query);
-        const api = await requireAuthAdmin(args);
-        const page = await fetch_page(from_paginator(api.logList({ query, q: args.q })), args);
+        const page = await fetch_page(from_paginator(api.logList({
+            query,
+            q: args.q,
+            ...(args.expandUser ? { expand: ['user'] } : {})
+        })), args);
         if (args.json)
             return print_json(page);
         if (page.data.length === 0) {
@@ -74,7 +91,9 @@ const logs_list = {
             log_status_badge(entry.status),
             typeof entry.user === 'string'
                 ? entry.user
-                : (entry.user?.id ?? '-'),
+                : (entry.user?.email ??
+                    entry.user?.id ??
+                    '-'),
             truncate(entry.message, 48),
             entry.id ?? '-'
         ]);

package/dist/commands/auth/query.js

@@ -22,15 +22,23 @@ const term = (field, value) => {
     }
     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)`);
+// A point in time for a range flag: a relative age (`30m`, `24h`, `7d` — that
+// long ago), unix-millis, or YYYY-MM-DD. Returned as what FaableQL accepts:
+// unix-millis or the date as given.
+const time_value = (flag, value, now = Date.now()) => {
+    const rel = /^(\d+)([mhd])$/.exec(value);
+    if (rel) {
+        const unit = { m: 60_000, h: 3_600_000, d: 86_400_000 }[rel[2]];
+        return String(now - Number(rel[1]) * unit);
     }
-    return `${field}:${value}`;
+    if (/^\d+$/.test(value) || /^\d{4}-\d{2}-\d{2}$/.test(value))
+        return value;
+    throw new Error(`Invalid --${flag}: "${value}". Use a relative age (30m, 24h, 7d), unix-millis or YYYY-MM-DD`);
 };
+// `<field>:<time>` for a range field of the server (`last_login_since`,
+// `since`…), from a flag that takes a time_value.
+const range_term = (field, flag, value, now) => value === undefined || value === ''
+    ? undefined
+    : `${field}:${time_value(flag, value, now)}`;
 
-export { compose_query, term, time_term };
+export { compose_query, range_term, term, time_value };

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

@@ -0,0 +1,15 @@
+import { sessions_list } from './list.js';
+import { sessions_revoke } from './revoke.js';
+
+const sessions = {
+    command: 'sessions',
+    describe: "List and revoke users' sessions (signed-in devices)",
+    builder: yargs => yargs
+        .command(sessions_list)
+        .command(sessions_revoke)
+        .demandCommand(1)
+        .showHelpOnFail(false),
+    handler: () => { }
+};
+
+export { sessions };

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

@@ -0,0 +1,73 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { list_options, fetch_page, print_json, table_lines, print, more_hint } from '../../../lib/listing.js';
+import { tenant_options } from '../options.js';
+import { compose_query, term, range_term } from '../query.js';
+import { truncate, when } from '../render.js';
+import { resolve_user_ref } from '../users/resolve.js';
+
+// One row per authentication of a user (arch/auth/user-sessions-devices.md):
+// the devices a user is signed in on, and from where. Not in the generated
+// auth-sdk yet — called through its fetcher, as the dashboard does.
+const sessions_list = {
+    command: 'list',
+    describe: "List sessions (a user's signed-in devices)",
+    builder: yargs => list_options(tenant_options(yargs))
+        .option('user', {
+        type: 'string',
+        description: 'Only this user: id (user_…) or email'
+    })
+        .option('active', {
+        type: 'boolean',
+        description: 'Only sessions still active (not revoked)'
+    })
+        .option('since', {
+        type: 'string',
+        description: 'Seen at or after: a relative age (30m, 24h, 7d), unix-millis or YYYY-MM-DD'
+    })
+        .option('query', {
+        type: 'string',
+        description: 'Raw FaableQL filter (fields: user, client, connection, status, sid, since, until)'
+    })
+        .example('$0 auth sessions list --user ana@example.com --active', "Ana's devices")
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const user = args.user ? await resolve_user_ref(api, args.user) : undefined;
+        const query = compose_query([
+            term('user', user),
+            args.active !== undefined && `status:${args.active ? 'active' : 'revoked'}`,
+            range_term('since', 'since', args.since)
+        ], args.query);
+        const page = await fetch_page(({ pageSize, next }) => api.fetcher.get('/session', {
+            params: {
+                pageSize: String(pageSize),
+                ...(next ? { next } : {}),
+                ...(query ? { query } : {})
+            }
+        }), args);
+        if (args.json)
+            return print_json(page);
+        if (page.data.length === 0) {
+            log.info('📭 No sessions match.');
+            return;
+        }
+        log.info(`💻 ${page.data.length} session(s):`);
+        const rows = page.data.map((s) => [
+            s.id ?? '-',
+            typeof s.user === 'string' ? s.user : (s.user?.id ?? '-'),
+            s.status ?? '-',
+            s.ip ?? '-',
+            truncate(s.device_name ?? s.user_agent, 32),
+            when(s.last_seen_at)
+        ]);
+        for (const line of table_lines(['ID', 'USER', 'STATUS', 'IP', 'DEVICE', 'LAST SEEN'], rows)) {
+            print(line);
+        }
+        const hint = more_hint(page);
+        if (hint)
+            log.info(hint);
+    })
+};
+
+export { sessions_list };

package/dist/commands/auth/sessions/revoke.js

@@ -0,0 +1,96 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { CliError } from '../../../lib/errors.js';
+import { confirm } from '../../../lib/interactive.js';
+import { json_option, fetch_page, print_noop, print_json } from '../../../lib/listing.js';
+import { log } from '../../../log.js';
+import { tenant_options } from '../options.js';
+import { resolve_user_ref } from '../users/resolve.js';
+
+// Ends sessions: the cookie and every refresh token issued through each one
+// stop working. Access tokens already issued live until they expire. Either
+// explicit ids, or --user for every ACTIVE session of one user ("sign them out
+// everywhere").
+const sessions_revoke = {
+    command: 'revoke [session_ids..]',
+    describe: 'Revoke sessions (sign a user out of their devices)',
+    builder: yargs => json_option(tenant_options(yargs))
+        .positional('session_ids', {
+        type: 'string',
+        array: true,
+        description: 'Session ids (session_…)'
+    })
+        .option('user', {
+        type: 'string',
+        description: 'Every active session of this user: id (user_…) or email'
+    })
+        .option('yes', {
+        alias: 'y',
+        type: 'boolean',
+        default: false,
+        description: 'Skip the confirmation prompt'
+    })
+        .example('$0 auth sessions revoke --user ana@example.com -y', 'Sign Ana out everywhere')
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const given = args.session_ids ?? [];
+        if (given.length > 0 === !!args.user) {
+            throw new CliError('usage', 'Pass session ids, or --user — one of the two.');
+        }
+        // Explicit ids: the prompt comes before any request. --user has to look
+        // the sessions up first (reads only), so that what is confirmed is what
+        // runs.
+        let api = args.user ? await requireAuthAdmin(args) : undefined;
+        let ids = given;
+        let who = '';
+        if (args.user && api) {
+            const user = await resolve_user_ref(api, args.user);
+            who = ` of ${args.user}`;
+            const page = await fetch_page(({ pageSize, next }) => api.fetcher.get('/session', {
+                params: {
+                    pageSize: String(pageSize),
+                    ...(next ? { next } : {}),
+                    query: `user:${user} status:active`
+                }
+            }), { limit: 200, all: true });
+            ids = page.data.map(s => s.id);
+            if (ids.length === 0) {
+                return print_noop(`${args.user} has no active sessions`);
+            }
+        }
+        const go = await confirm({
+            message: `Revoke ${ids.length} session(s)${who}?`,
+            yes: args.yes
+        });
+        if (!go) {
+            log.info('Cancelled.');
+            return;
+        }
+        api ??= await requireAuthAdmin(args);
+        const results = [];
+        for (const id of ids) {
+            try {
+                await api.fetcher.post(`/session/${id}/revoke`, {});
+                results.push({ id, revoked: true });
+                if (!args.json)
+                    log.info(`🔒 Revoked ${id}`);
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                results.push({ id, revoked: false, error: message });
+                if (!args.json)
+                    log.error(`❌ Failed to revoke ${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} revocation(s) failed`);
+        }
+        if (!args.json) {
+            log.info(`✅ ${ids.length} session(s) revoked. Access tokens already issued stay valid until they expire.`);
+        }
+    })
+};
+
+export { sessions_revoke };

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

@@ -3,6 +3,7 @@ import { log } from '../../../log.js';
 import { tenant_options } from '../options.js';
 import { json_option, fetch_page, from_paginator, print_json } from '../../../lib/listing.js';
 import { yes_no, when } from '../render.js';
+import { resolve_user_ref } from './resolve.js';
 
 // Identity rows carry the RAW provider access/refresh tokens — strip them
 // before anything (json output included) can print one.
@@ -12,23 +13,24 @@ const sanitize_identity = (i) => {
 };
 const users_get = {
     command: 'get <user_id>',
-    describe: 'Show a user, including their federated identities',
+    describe: 'Show a user (by id or email), including their federated identities',
     builder: yargs => json_option(tenant_options(yargs))
         .positional('user_id', {
         type: 'string',
         demandOption: true,
-        description: 'User identifier (user_…)'
+        description: 'User id (user_…) or email'
     })
         .showHelpOnFail(false),
     handler: withAuthHints(async (args) => {
         const api = await requireAuthAdmin(args);
-        const user = await api.userGet(args.user_id);
+        const user_id = await resolve_user_ref(api, args.user_id);
+        const user = await api.userGet(user_id);
         // Federated identities (GitHub, Google…): who this user IS at the
         // provider — the piece the abuse playbook keeps needing (a Faable email
         // rarely matches the GitHub handle that owns the deployed repos).
         // Best-effort: a tenant where the session can't read /identity still
         // renders the user card.
-        const identities = await fetch_page(from_paginator(api.identityList({ query: `user:${args.user_id}` })), { limit: 200, all: true })
+        const identities = await fetch_page(from_paginator(api.identityList({ query: `user:${user_id}` })), { limit: 200, all: true })
             .then(r => r.data.map(i => sanitize_identity(i)))
             .catch(() => []);
         // Resolve connection ids to names ("github") once per distinct id.

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

@@ -28,9 +28,11 @@ const parse_user_ids = (args, stdin) => {
     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));
+    // An email is resolved to its one user later (resolve_user_refs), before
+    // any mutation runs.
+    const invalid = ids.filter(id => !/^user_[a-zA-Z0-9]+$/.test(id) && !/^[^\s@]+@[^\s@]+$/.test(id));
     if (invalid.length > 0) {
-        throw new Error(`Invalid user id(s): ${invalid.join(', ')} (expected user_…)`);
+        throw new Error(`Invalid user id(s): ${invalid.join(', ')} (expected user_… or an email)`);
     }
     return ids;
 };

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

@@ -2,17 +2,19 @@ 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_password_setup } from './password_setup.js';
 import { users_reinstate } from './reinstate.js';
 import { users_suspend } from './suspend.js';
 
 const users = {
     command: 'users',
-    describe: 'List, inspect, suspend, reinstate, import and export users',
+    describe: 'List, count, inspect, suspend, reinstate, import and export users',
     builder: yargs => yargs
         .command(users_list)
         .command(users_get)
         .command(users_suspend)
         .command(users_reinstate)
+        .command(users_password_setup)
         .command(users_import)
         .command(users_export)
         .demandCommand(1)