@faable/faable 4.9.0 → 4.10.0

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/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/upgrade/index.js

@@ -1,7 +1,7 @@
 import ora from 'ora';
 import { version } from '../../config.js';
 import { isDevBuild, getLatestVersion, isNewerVersion, CLI_PACKAGE } from '../../lib/UpdateChecker.js';
-import { cmd } from '../../lib/cmd.js';
+import { upgradeTo, npmDeps } from '../../lib/self_upgrade.js';
 import { log } from '../../log.js';
 
 const upgrade = {
@@ -22,15 +22,25 @@ const upgrade = {
             return;
         }
         const spinner = ora(`Upgrading ${CLI_PACKAGE} ${version} → ${latest}`).start();
-        try {
-            await cmd(`npm install -g --prefer-online ${CLI_PACKAGE}@latest`, { timeout: 180_000 });
+        const res = await upgradeTo(latest, npmDeps, {
+            onRetry: () => {
+                spinner.text = `${latest} was just published and the npm registry is still propagating it — retrying…`;
+            },
+        });
+        if (res.ok) {
             spinner.succeed(`Upgraded to ${latest}`);
+            return;
         }
-        catch {
-            spinner.fail("Upgrade failed");
-            log.error(`❌ Could not upgrade automatically. Try manually: npm install -g --prefer-online ${CLI_PACKAGE}@latest`);
-            process.exit(1);
+        spinner.fail("Upgrade failed");
+        if (res.reason === "not_propagated") {
+            log.error(`❌ ${latest} is not available from the npm registry yet (still on ${res.installed ?? version}). A release takes a few minutes to propagate — run \`faable upgrade\` again shortly.`);
+        }
+        else {
+            if (res.output)
+                log.error(res.output.trim());
+            log.error(`❌ Could not upgrade automatically. Try manually: npm install -g ${CLI_PACKAGE}@${latest}`);
         }
+        process.exit(1);
     },
 };
 

package/dist/lib/self_upgrade.js

@@ -0,0 +1,51 @@
+import { execFile } from 'child_process';
+import { CLI_PACKAGE } from './UpdateChecker.js';
+
+// npm's ways of saying "that version does not exist (here, yet)".
+const NOT_FOUND = /ETARGET|notarget|No matching version|E404/i;
+const upgradeTo = async (target, deps, { attempts = 5, wait_ms = 30_000, onRetry = (_n) => { } } = {}) => {
+    let output = "";
+    for (let n = 1; n <= attempts; n++) {
+        const res = await deps.install(target);
+        output = res.output;
+        if (res.ok) {
+            const installed = await deps.installed();
+            if (installed === target)
+                return { ok: true, attempts: n };
+            // npm said yes and changed nothing: the same lag, from another angle.
+        }
+        else if (!NOT_FOUND.test(res.output)) {
+            return { ok: false, reason: "install_failed", output };
+        }
+        if (n < attempts) {
+            onRetry(n);
+            await deps.sleep(wait_ms);
+        }
+    }
+    return {
+        ok: false,
+        reason: "not_propagated",
+        output,
+        installed: await deps.installed(),
+    };
+};
+const run = (file, args, timeout) => new Promise((resolve) => {
+    execFile(file, args, { timeout, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => resolve({ ok: !err, output: `${stdout ?? ""}${stderr ?? ""}` }));
+});
+const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+/** The real thing: global npm. */
+const npmDeps = {
+    install: (version) => run(npm, ["install", "-g", "--prefer-online", `${CLI_PACKAGE}@${version}`], 180_000),
+    installed: async () => {
+        const res = await run(npm, ["ls", "-g", "--json", "--depth=0", CLI_PACKAGE], 30_000);
+        try {
+            return JSON.parse(res.output).dependencies?.[CLI_PACKAGE]?.version;
+        }
+        catch {
+            return undefined;
+        }
+    },
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+};
+
+export { npmDeps, upgradeTo };

package/package.json

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