@faable/faable 4.8.0 → 4.9.1

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

@@ -2,6 +2,7 @@ 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 { format_field } from './profile_fields.js';
 import { resolve_client } from './resolve.js';
 
 const clients_get = {
@@ -39,6 +40,8 @@ const clients_get = {
         if (client.web_origins?.length) {
             log.info(`  Web origins: ${client.web_origins.join(', ')}`);
         }
+        const fields = client.profile_fields;
+        log.info(`  Fields:      ${fields ? (fields.length ? fields.map(format_field).join(', ') : 'none') : 'inherited from the tenant'}`);
         log.info(`  Created:     ${client.createdAt ?? '-'}`);
     })
 };

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

@@ -2,6 +2,7 @@ import { clients_create } from './create.js';
 import { clients_get } from './get.js';
 import { clients_list } from './list.js';
 import { clients_rm } from './rm.js';
+import { clients_update } from './update.js';
 
 const clients = {
     command: 'clients',
@@ -10,6 +11,7 @@ const clients = {
         .command(clients_list)
         .command(clients_get)
         .command(clients_create)
+        .command(clients_update)
         .command(clients_rm)
         .demandCommand(1)
         .showHelpOnFail(false),

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

@@ -0,0 +1,121 @@
+// The `profile_fields` of a client: which custom fields its users may write on
+// themselves with `PATCH /me` (`auth-js updateProfile`), stored in
+// `user_metadata["faable.com/fields"]`. A client's list REPLACES the tenant's
+// for that app; no list (`null`) inherits the tenant's.
+const KEY = /^[a-z0-9_]{1,40}$/;
+const invalid = (spec, why) => new Error(`Invalid field "${spec}": ${why}`);
+const checkKey = (key, spec) => {
+    if (!KEY.test(key)) {
+        throw invalid(spec, 'the key takes lowercase letters, digits and _ (1-40 characters)');
+    }
+};
+/**
+ * `--add-field` syntax:
+ *
+ *   profile                     a string field, default max length (200)
+ *   school:string:120           a string field of at most 120 characters
+ *   profile:enum:student,teacher  one of the listed values
+ */
+const parse_field_spec = (spec) => {
+    const [key, type, rest] = spec.includes(':')
+        ? splitSpec(spec)
+        : [spec, 'string', undefined];
+    checkKey(key, spec);
+    if (type === 'enum') {
+        const options = (rest ?? '')
+            .split(',')
+            .map(o => o.trim())
+            .filter(Boolean);
+        if (!options.length) {
+            throw invalid(spec, 'an enum needs its values: key:enum:a,b,c');
+        }
+        return { key, type: 'enum', options: [...new Set(options)] };
+    }
+    if (type === 'string') {
+        if (rest === undefined || rest === '')
+            return { key, type: 'string' };
+        const max = Number(rest);
+        if (!Number.isInteger(max) || max < 1 || max > 1000) {
+            throw invalid(spec, 'the max length is a whole number from 1 to 1000');
+        }
+        return { key, type: 'string', max_length: max };
+    }
+    throw invalid(spec, `unknown type "${type}" (string or enum)`);
+};
+// `key:type:rest`, where `rest` may itself contain `:` (an enum value).
+const splitSpec = (spec) => {
+    const first = spec.indexOf(':');
+    const key = spec.slice(0, first);
+    const after = spec.slice(first + 1);
+    const second = after.indexOf(':');
+    if (second < 0)
+        return [key, after, undefined];
+    return [key, after.slice(0, second), after.slice(second + 1)];
+};
+/** `--fields-json`: the whole list, validated the same way. */
+const parse_fields_json = (raw) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('--fields-json is not valid JSON');
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error('--fields-json must be a JSON array of field declarations');
+    }
+    return parsed.map((f, i) => {
+        const d = f;
+        const spec = `--fields-json[${i}]`;
+        if (typeof d?.key !== 'string')
+            throw invalid(spec, 'missing "key"');
+        checkKey(d.key, spec);
+        if (d.type === 'enum') {
+            if (!Array.isArray(d.options) || !d.options.length) {
+                throw invalid(spec, 'an enum needs "options"');
+            }
+            return { key: d.key, type: 'enum', options: d.options.map(String) };
+        }
+        if (d.type !== 'string') {
+            throw invalid(spec, '"type" is "string" or "enum"');
+        }
+        return {
+            key: d.key,
+            type: 'string',
+            ...(d.max_length !== undefined ? { max_length: d.max_length } : {})
+        };
+    });
+};
+/**
+ * The client's new list after removing and adding. Adding a key that is
+ * already declared replaces its declaration in place; removing a key that is
+ * not there is an error, so a typo does not look like success.
+ */
+const apply_field_changes = (current, adds, removes) => {
+    const next = [...(current ?? [])];
+    for (const key of removes) {
+        const at = next.findIndex(f => f.key === key);
+        if (at < 0) {
+            const have = next.map(f => f.key).join(', ') || 'none';
+            throw new Error(`The client has no field "${key}" (declared: ${have})`);
+        }
+        next.splice(at, 1);
+    }
+    for (const field of adds) {
+        const at = next.findIndex(f => f.key === field.key);
+        if (at >= 0)
+            next[at] = field;
+        else
+            next.push(field);
+    }
+    if (next.length > 20) {
+        throw new Error(`A client declares at most 20 fields (this would be ${next.length})`);
+    }
+    return next;
+};
+/** One line per field, for `clients get` and the update summary. */
+const format_field = (f) => f.type === 'enum'
+    ? `${f.key} (enum: ${(f.options ?? []).join(', ')})`
+    : `${f.key} (string${f.max_length ? `, max ${f.max_length}` : ''})`;
+
+export { apply_field_changes, format_field, parse_field_spec, parse_fields_json };

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

@@ -0,0 +1,146 @@
+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 { parse_field_spec, parse_fields_json, apply_field_changes, format_field } from './profile_fields.js';
+import { resolve_client } from './resolve.js';
+
+// The update route replaces each list whole, so every list change here is a
+// read-modify-write of what the client has now: adding a callback never drops
+// the others.
+const edit_list = (current, add = [], remove = []) => {
+    if (!add.length && !remove.length)
+        return undefined;
+    const next = (current ?? []).filter(u => !remove.includes(u));
+    for (const u of add)
+        if (!next.includes(u))
+            next.push(u);
+    return next;
+};
+const clients_update = {
+    command: 'update <client_id>',
+    describe: 'Update an OAuth client (name, URLs, profile fields)',
+    builder: yargs => json_option(tenant_options(yargs))
+        .positional('client_id', {
+        type: 'string',
+        demandOption: true,
+        description: 'Client resource id or OAuth client_id'
+    })
+        .option('name', {
+        alias: 'n',
+        type: 'string',
+        description: 'New client name'
+    })
+        .option('description', {
+        alias: 'd',
+        type: 'string',
+        description: 'New client description'
+    })
+        .option('add-callback', {
+        type: 'string',
+        array: true,
+        description: 'Add an allowed callback (redirect) URL — repeatable'
+    })
+        .option('remove-callback', {
+        type: 'string',
+        array: true,
+        description: 'Remove an allowed callback URL — repeatable'
+    })
+        .option('add-logout-url', {
+        type: 'string',
+        array: true,
+        description: 'Add an allowed post-logout URL — repeatable'
+    })
+        .option('remove-logout-url', {
+        type: 'string',
+        array: true,
+        description: 'Remove an allowed post-logout URL — repeatable'
+    })
+        .option('add-web-origin', {
+        type: 'string',
+        array: true,
+        description: 'Add an allowed web origin (CORS) — repeatable'
+    })
+        .option('remove-web-origin', {
+        type: 'string',
+        array: true,
+        description: 'Remove an allowed web origin — repeatable'
+    })
+        .option('add-field', {
+        type: 'string',
+        array: true,
+        description: 'Declare a profile field users may write with PATCH /me: key, key:string[:max_length] or key:enum:a,b,c. Re-adding a key replaces it — repeatable'
+    })
+        .option('remove-field', {
+        type: 'string',
+        array: true,
+        description: 'Remove a declared profile field by key — repeatable'
+    })
+        .option('fields-json', {
+        type: 'string',
+        description: 'Replace the whole profile field list with a JSON array of {key, type, options?, max_length?}'
+    })
+        .option('inherit-fields', {
+        type: 'boolean',
+        description: "Drop this client's own profile field list and use the tenant's again"
+    })
+        .conflicts('fields-json', ['add-field', 'remove-field', 'inherit-fields'])
+        .conflicts('inherit-fields', ['add-field', 'remove-field'])
+        .example('$0 auth clients update my-app --add-field profile:enum:student,teacher', 'Let users of my-app pick their profile with auth-js updateProfile')
+        .example('$0 auth clients update my-app --remove-field school', 'Stop accepting a field')
+        .example('$0 auth clients update my-app --add-callback https://app.example.com/cb', 'Allow one more redirect URL, keeping the others')
+        .showHelpOnFail(false),
+    handler: withAuthHints(async (args) => {
+        // Parse everything before any request, so a bad spec costs nothing.
+        const adds = (args.addField ?? []).map(parse_field_spec);
+        const full = args.fieldsJson
+            ? parse_fields_json(args.fieldsJson)
+            : undefined;
+        const api = await requireAuthAdmin(args);
+        const client = await resolve_client(api, args.client_id);
+        const own = client.profile_fields;
+        let profile_fields;
+        if (full)
+            profile_fields = full;
+        else if (args.inheritFields)
+            profile_fields = null;
+        else if (adds.length || args.removeField?.length) {
+            profile_fields = apply_field_changes(own, adds, args.removeField ?? []);
+        }
+        const callbacks = edit_list(client.callbacks, args.addCallback, args.removeCallback);
+        const logout_urls = edit_list(client.logout_urls, args.addLogoutUrl, args.removeLogoutUrl);
+        const web_origins = edit_list(client.web_origins, args.addWebOrigin, args.removeWebOrigin);
+        const patch = {
+            ...(args.name !== undefined ? { name: args.name } : {}),
+            ...(args.description !== undefined
+                ? { description: args.description }
+                : {}),
+            ...(callbacks ? { callbacks } : {}),
+            ...(logout_urls ? { logout_urls } : {}),
+            ...(web_origins ? { web_origins } : {}),
+            ...(profile_fields !== undefined ? { profile_fields } : {})
+        };
+        if (Object.keys(patch).length === 0) {
+            throw new Error('Nothing to update — pass a --name, --description, an --add-*/--remove-* option, --fields-json or --inherit-fields');
+        }
+        const updated = await api.clientUpdate(client.id, patch);
+        if (args.json)
+            return print_json(updated);
+        log.info(`✅ Updated client "${updated.name}" (${updated.client_id})`);
+        if (profile_fields !== undefined) {
+            const now = updated.profile_fields;
+            if (!now) {
+                log.info('  Profile fields: inherited from the tenant');
+            }
+            else {
+                log.info(`  Profile fields: ${now.length ? now.map(format_field).join(', ') : 'none'}`);
+                // The first own list silently stops inheriting the tenant's: say so.
+                if (!own) {
+                    log.info("  ℹ️ This client now has its own list, which replaces the tenant's for it. --inherit-fields undoes that.");
+                }
+            }
+        }
+    })
+};
+
+export { clients_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/dist/mcp/tools.js

@@ -900,6 +900,53 @@ const TOOLS = [
         annotations: AUTH_WRITE,
         example: { user: 'ana@example.com' }
     },
+    {
+        name: 'update_auth_client_fields',
+        title: "Change an app's profile fields",
+        description: "Declare which custom profile fields the users of one Auth application may write on themselves (auth-js `updateProfile`, stored in user_metadata[\"faable.com/fields\"]). `add` takes `key`, `key:string:120` or `key:enum:a,b,c`; re-adding a key replaces it. `inherit: true` drops the app's own list and uses the tenant's again. An app's own list replaces the tenant's for that app. Only the fields: the app's URLs and settings are not changed here.",
+        input: {
+            client: z
+                .string()
+                .describe('The application: client resource id (client_…) or OAuth client_id'),
+            add: z
+                .array(z.string())
+                .max(20)
+                .optional()
+                .describe('Fields to declare: key, key:string[:max_length] or key:enum:a,b,c'),
+            remove: z
+                .array(z.string())
+                .max(20)
+                .optional()
+                .describe('Field keys to stop accepting'),
+            inherit: z
+                .boolean()
+                .optional()
+                .describe("Drop the app's own list and use the tenant's"),
+            tenant,
+            project
+        },
+        command: ['auth', 'clients', 'update'],
+        flags: a => [
+            a.client,
+            ...(a.add ?? []).flatMap((f) => ['--add-field', f]),
+            ...(a.remove ?? []).flatMap((k) => ['--remove-field', k]),
+            ...(a.inherit ? ['--inherit-fields'] : []),
+            ...auth_scope(a)
+        ],
+        shape: (c) => ({
+            id: c.id,
+            client_id: c.client_id,
+            name: c.name,
+            profile_fields: c.profile_fields ?? null
+        }),
+        write: true,
+        annotations: AUTH_WRITE,
+        example: {
+            client: 'client_1',
+            add: ['profile:enum:student,teacher'],
+            remove: ['school']
+        }
+    },
     {
         name: 'send_password_setup',
         title: 'Send a password setup email',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/faable",
-  "version": "4.8.0",
+  "version": "4.9.1",
   "main": "dist/index.js",
   "license": "MIT",
   "author": "Marc Pomar <marc@faable.com>",
@@ -27,7 +27,7 @@
   ],
   "dependencies": {
     "@actions/core": "^3.0.0",
-    "@faable/auth-sdk": "^2.7.29",
+    "@faable/auth-sdk": "^2.7.105",
     "@modelcontextprotocol/sdk": "^1.31.0",
     "axios": "^1.20.0",
     "fs-extra": "^11.3.2",