@faable/faable 4.9.1 → 4.10.1

package/dist/commands/auth/index.js

@@ -5,6 +5,7 @@ import { connections } from './connections/index.js';
 import { logs } from './logs/index.js';
 import { sessions } from './sessions/index.js';
 import { users } from './users/index.js';
+import { webhooks } from './webhooks/index.js';
 
 // `faable auth` — management commands for a Faable Auth tenant. Auth: reuses
 // the `faable login` session (or FAABLE_TOKEN); tenant: --account /
@@ -12,7 +13,7 @@ import { users } from './users/index.js';
 // resolveTenant in src/api/auth_admin.ts.
 const auth = {
     command: 'auth',
-    describe: 'Manage Faable Auth (users, sessions, logins, actions, clients, audit logs)',
+    describe: 'Manage Faable Auth (users, sessions, logins, actions, clients, webhooks, audit logs)',
     builder: yargs => yargs
         .command(users)
         .command(actions)
@@ -20,6 +21,7 @@ const auth = {
         .command(logs)
         .command(sessions)
         .command(connections)
+        .command(webhooks)
         .command(accounts)
         .command(auth_use)
         .demandCommand(1)

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

@@ -36,12 +36,5 @@ const parse_user_ids = (args, stdin) => {
     }
     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 };
+export { parse_user_ids, wants_stdin };

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

@@ -2,9 +2,10 @@ import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
 import { log } from '../../../log.js';
 import { tenant_options } from '../options.js';
 import { json_option, print_json } from '../../../lib/listing.js';
-import { wants_stdin, read_stdin, parse_user_ids } from './ids.js';
+import { wants_stdin, parse_user_ids } from './ids.js';
 import { resolve_user_refs } from './resolve.js';
 import { confirm } from '../../../lib/interactive.js';
+import { read_stdin } from '../../../lib/stdin.js';
 
 const users_reinstate = {
     command: 'reinstate [user_ids..]',

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

@@ -2,9 +2,10 @@ import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
 import { log } from '../../../log.js';
 import { tenant_options } from '../options.js';
 import { json_option, print_json } from '../../../lib/listing.js';
-import { wants_stdin, read_stdin, parse_user_ids } from './ids.js';
+import { wants_stdin, parse_user_ids } from './ids.js';
 import { resolve_user_refs } from './resolve.js';
 import { confirm } from '../../../lib/interactive.js';
+import { read_stdin } from '../../../lib/stdin.js';
 
 const users_suspend = {
     command: 'suspend [user_ids..]',

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

@@ -0,0 +1,60 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { tenant_options } from '../options.js';
+import { json_option, print_json } from '../../../lib/listing.js';
+import { SECRET_WARNING } from './shared.js';
+
+const webhooks_create = {
+    command: 'create',
+    describe: 'Create a webhook (prints its signing secret once)',
+    builder: yargs => json_option(tenant_options(yargs))
+        .option('url', {
+        type: 'string',
+        demandOption: true,
+        description: 'Where deliveries are POSTed. Must be https.'
+    })
+        .option('event', {
+        alias: 'e',
+        type: 'string',
+        array: true,
+        demandOption: true,
+        description: 'Event to subscribe to, e.g. user.created — repeatable. Unknown events are refused by the server with the list of valid ones.'
+    })
+        .option('secret', {
+        type: 'string',
+        description: 'Use this signing secret instead of a generated one (whsec_…)'
+    })
+        .option('disabled', {
+        type: 'boolean',
+        default: false,
+        description: 'Create it inactive: nothing is delivered until enabled'
+    })
+        .example('$0 auth webhooks create --url https://app.example.com/api/webhooks/faable-auth -e user.created', 'Get a signed POST on every new user')
+        .example('$0 auth webhooks create --url https://… -e user.created --json | jq -r .secret', 'Capture the secret for a script')
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const created = (await api.notificationsubscriptionCreate({
+            channel: 'webhook',
+            events: args.event,
+            active: !args.disabled,
+            config: {
+                url: args.url,
+                ...(args.secret ? { secret: args.secret } : {})
+            }
+        }));
+        if (args.json)
+            return print_json(created);
+        log.info(`✅ Created webhook ${created.id}`);
+        log.info(`  URL:    ${created.config?.url}`);
+        log.info(`  Events: ${(created.events ?? []).join(', ')}`);
+        log.info(`  Active: ${created.active ? 'yes' : 'no'}`);
+        if (created.secret) {
+            log.info(`  Signing secret: ${created.secret}`);
+            log.info(`  ${SECRET_WARNING}`);
+        }
+        log.info(`  Check it end to end with \`faable auth webhooks test ${created.id}\`.`);
+    })
+};
+
+export { webhooks_create };

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

@@ -0,0 +1,35 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { tenant_options } from '../options.js';
+import { yes_no, when } from '../render.js';
+import { json_option, print_json } from '../../../lib/listing.js';
+
+const webhooks_get = {
+    command: 'get <webhook_id>',
+    describe: 'Show a webhook',
+    builder: yargs => json_option(tenant_options(yargs))
+        .positional('webhook_id', {
+        type: 'string',
+        demandOption: true,
+        description: 'Webhook id (notificationsubscription_…)'
+    })
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const w = (await api.notificationsubscriptionGet(args.webhook_id));
+        if (args.json)
+            return print_json(w);
+        log.info(`🪝 ${w.id}`);
+        log.info(`  URL:       ${w.config?.url ?? '-'}`);
+        log.info(`  Events:    ${w.events.join(', ')}`);
+        log.info(`  Active:    ${yes_no(w.active)}`);
+        log.info(`  Status:    ${w.status ?? '-'}${w.consecutive_failures ? ` (${w.consecutive_failures} failures in a row)` : ''}`);
+        log.info(`  Last OK:   ${when(w.last_success_at)}`);
+        log.info(`  Last fail: ${when(w.last_failure_at)}`);
+        if (w.config?.previous_secret_expires_at) {
+            log.info(`  Previous secret valid until ${w.config.previous_secret_expires_at} (rotation overlap)`);
+        }
+    })
+};
+
+export { webhooks_get };

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

@@ -0,0 +1,29 @@
+import { webhooks_create } from './create.js';
+import { webhooks_get } from './get.js';
+import { webhooks_list } from './list.js';
+import { webhooks_rm } from './rm.js';
+import { webhooks_rotate_secret } from './rotate_secret.js';
+import { webhooks_test } from './test.js';
+import { webhooks_update } from './update.js';
+
+// Signed HTTP notifications of the tenant's events (user.created, …) to your
+// server. Deliveries carry `x-faable-signature` (HMAC-SHA256 of
+// `${x-faable-timestamp}.${body}`) and `x-faable-delivery` (same id on every
+// retry); failures are retried for ~15 h.
+const webhooks = {
+    command: 'webhooks',
+    describe: 'Manage webhooks (signed notifications of tenant events)',
+    builder: yargs => yargs
+        .command(webhooks_list)
+        .command(webhooks_get)
+        .command(webhooks_create)
+        .command(webhooks_update)
+        .command(webhooks_test)
+        .command(webhooks_rotate_secret)
+        .command(webhooks_rm)
+        .demandCommand(1)
+        .showHelpOnFail(false),
+    handler: () => { }
+};
+
+export { webhooks };

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

@@ -0,0 +1,41 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { list_options, fetch_page, from_paginator, print_json, table_lines, print, more_hint } from '../../../lib/listing.js';
+import { log } from '../../../log.js';
+import { tenant_options } from '../options.js';
+import { yes_no, when } from '../render.js';
+import { isWebhook } from './shared.js';
+
+const webhooks_list = {
+    command: 'list',
+    describe: 'List webhooks',
+    builder: yargs => list_options(tenant_options(yargs)).showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const page = await fetch_page(from_paginator(api.notificationsubscriptionList({})), args);
+        // The resource also holds email subscriptions; this command is webhooks.
+        const data = page.data.filter(isWebhook);
+        if (args.json)
+            return print_json({ ...page, data });
+        if (data.length === 0) {
+            log.info('📭 No webhooks. Create one with `faable auth webhooks create`.');
+            return;
+        }
+        log.info(`🪝 ${data.length} webhook(s):`);
+        const rows = data.map(w => [
+            w.id,
+            w.config?.url ?? '-',
+            w.events.join(','),
+            yes_no(w.active),
+            w.status ?? '-',
+            when(w.last_success_at)
+        ]);
+        for (const line of table_lines(['ID', 'URL', 'EVENTS', 'ACTIVE', 'STATUS', 'LAST OK'], rows)) {
+            print(line);
+        }
+        const hint = more_hint(page);
+        if (hint)
+            log.info(hint);
+    })
+};
+
+export { webhooks_list };

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

@@ -0,0 +1,41 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { confirm } from '../../../lib/interactive.js';
+import { log } from '../../../log.js';
+import { tenant_options } from '../options.js';
+import { json_option, print_json } from '../../../lib/listing.js';
+
+const webhooks_rm = {
+    command: 'rm <webhook_id>',
+    describe: 'Delete a webhook',
+    builder: yargs => json_option(tenant_options(yargs))
+        .positional('webhook_id', {
+        type: 'string',
+        demandOption: true,
+        description: 'Webhook id (notificationsubscription_…)'
+    })
+        .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 w = (await api.notificationsubscriptionGet(args.webhook_id));
+        const go = await confirm({
+            message: `Delete webhook ${w.id} → ${w.config?.url}? Its events stop being delivered.`,
+            yes: args.yes
+        });
+        if (!go) {
+            log.info('Cancelled.');
+            return;
+        }
+        await api.notificationsubscriptionDelete(w.id);
+        if (args.json)
+            return print_json({ deleted: true, id: w.id });
+        log.info(`🗑️ Deleted webhook ${w.id}.`);
+    })
+};
+
+export { webhooks_rm };

package/dist/commands/auth/webhooks/rotate_secret.js

@@ -0,0 +1,32 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { tenant_options } from '../options.js';
+import { json_option, print_json } from '../../../lib/listing.js';
+import { SECRET_WARNING } from './shared.js';
+
+const webhooks_rotate_secret = {
+    command: 'rotate-secret <webhook_id>',
+    describe: "Rotate a webhook's signing secret (the old one stays valid 24 h)",
+    builder: yargs => json_option(tenant_options(yargs))
+        .positional('webhook_id', {
+        type: 'string',
+        demandOption: true,
+        description: 'Webhook id (notificationsubscription_…)'
+    })
+        .option('secret', {
+        type: 'string',
+        description: 'Use this secret instead of a generated one'
+    })
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const r = (await api.notificationsubscriptionRotateSecret(args.webhook_id, (args.secret ? { secret: args.secret } : {})));
+        if (args.json)
+            return print_json(r);
+        log.info(`🔑 New signing secret: ${r.secret}`);
+        log.info(`  ${SECRET_WARNING}`);
+        log.info(`  Until ${r.previous_secret_expires_at} deliveries carry both signatures, so the receiver can switch over without dropping any.`);
+    })
+};
+
+export { webhooks_rotate_secret };

package/dist/commands/auth/webhooks/shared.js

@@ -0,0 +1,7 @@
+// Pieces shared by the `faable auth webhooks` commands.
+const isWebhook = (s) => s.channel === 'webhook';
+// The secret is returned exactly once (create, rotate-secret): say so where
+// the person will see it, not in the docs.
+const SECRET_WARNING = "⚠️ Store it now (e.g. as the receiver's environment variable): it is never shown again. `faable auth webhooks rotate-secret` issues a new one.";
+
+export { SECRET_WARNING, isWebhook };

package/dist/commands/auth/webhooks/test.js

@@ -0,0 +1,32 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { tenant_options } from '../options.js';
+import { json_option, print_json } from '../../../lib/listing.js';
+
+const webhooks_test = {
+    command: 'test <webhook_id>',
+    describe: 'Send a signed `ping` to a webhook and show what it answered',
+    builder: yargs => json_option(tenant_options(yargs))
+        .positional('webhook_id', {
+        type: 'string',
+        demandOption: true,
+        description: 'Webhook id (notificationsubscription_…)'
+    })
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const api = await requireAuthAdmin(args);
+        const r = (await api.notificationsubscriptionTest(args.webhook_id));
+        if (args.json)
+            return print_json(r);
+        const what = r.status ? `HTTP ${r.status}` : (r.error ?? 'no answer');
+        if (r.ok) {
+            log.info(`✅ The endpoint answered ${what} (event ${r.event_id}).`);
+        }
+        else {
+            log.error(`❌ The endpoint answered ${what} (event ${r.event_id}).`);
+            process.exitCode = 1;
+        }
+    })
+};
+
+export { webhooks_test };

package/dist/commands/auth/webhooks/update.js

@@ -0,0 +1,46 @@
+import { withAuthHints, requireAuthAdmin } from '../../../api/auth_admin.js';
+import { log } from '../../../log.js';
+import { tenant_options } from '../options.js';
+import { yes_no } from '../render.js';
+import { json_option, print_json } from '../../../lib/listing.js';
+
+const webhooks_update = {
+    command: 'update <webhook_id>',
+    describe: 'Change a webhook (URL, events, enabled)',
+    builder: yargs => json_option(tenant_options(yargs))
+        .positional('webhook_id', {
+        type: 'string',
+        demandOption: true,
+        description: 'Webhook id (notificationsubscription_…)'
+    })
+        .option('url', { type: 'string', description: 'New https URL' })
+        .option('event', {
+        alias: 'e',
+        type: 'string',
+        array: true,
+        description: 'Replace the subscribed events — repeatable'
+    })
+        .option('enabled', {
+        type: 'boolean',
+        description: 'Enable (--enabled) or pause (--no-enabled) deliveries'
+    })
+        .example('$0 auth webhooks update notificationsubscription_… --no-enabled', 'Pause deliveries')
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        const patch = {
+            ...(args.url !== undefined ? { config: { url: args.url } } : {}),
+            ...(args.event?.length ? { events: args.event } : {}),
+            ...(args.enabled !== undefined ? { active: args.enabled } : {})
+        };
+        if (Object.keys(patch).length === 0) {
+            throw new Error('Nothing to update — pass at least one of --url, --event, --enabled');
+        }
+        const api = await requireAuthAdmin(args);
+        const w = (await api.notificationsubscriptionUpdate(args.webhook_id, patch));
+        if (args.json)
+            return print_json(w);
+        log.info(`✅ Updated webhook ${w.id} (${w.config?.url}, ${(w.events ?? []).join(', ')}, active ${yes_no(w.active)})`);
+    })
+};
+
+export { webhooks_update };

package/dist/commands/deploy/secrets/set.js

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { requireApi } from '../../../api/context.js';
 import { print_json, json_option } from '../../../lib/listing.js';
+import { read_stdin } from '../../../lib/stdin.js';
 import { log } from '../../../log.js';
 import { resolve_app_id } from '../resolve_app_id.js';
 import { managed_warning } from './managed_names.js';
@@ -20,9 +21,11 @@ const DEFAULT_ENV_FILE = '.env';
 // even after the script, and dies with "node: -: not found" before the CLI
 // runs; the short alias is invisible to it.
 const STDIN = '-';
-const read_env_file = (raw_path) => {
+const read_env_file = async (raw_path) => {
+    // Asynchronously: `readFileSync(0)` throws EAGAIN on a pipe that has not
+    // been written yet (lib/stdin.ts).
     if (raw_path === STDIN)
-        return parse_env(readFileSync(0, 'utf8'), 'stdin');
+        return parse_env(await read_stdin(), 'stdin');
     const path = raw_path || DEFAULT_ENV_FILE;
     let content;
     try {
@@ -86,7 +89,7 @@ const secrets_set = {
         }
         // Validate EVERYTHING before writing ANY, so one malformed line or pair
         // aborts the whole command with no partial writes.
-        const from_file = env_file === undefined ? [] : read_env_file(env_file);
+        const from_file = env_file === undefined ? [] : await read_env_file(env_file);
         const parsed = combine(from_file, parse_pairs(pairs));
         if (env_file !== undefined) {
             const path = env_file === STDIN ? 'stdin' : env_file || DEFAULT_ENV_FILE;

package/dist/lib/stdin.js

@@ -0,0 +1,15 @@
+// All of stdin, read asynchronously.
+//
+// Never `readFileSync(0)`: when stdin is a pipe from another process that has
+// not written yet (`faable auth webhooks create --json | … | faable deploy
+// secrets set -f -`), the descriptor is non-blocking and the synchronous read
+// throws EAGAIN instead of waiting.
+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 { read_stdin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/faable",
-  "version": "4.9.1",
+  "version": "4.10.1",
   "main": "dist/index.js",
   "license": "MIT",
   "author": "Marc Pomar <marc@faable.com>",