@canner-ca/cli 0.5.1 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canner-ca/cli",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Canner deploy CLI — git push from any terminal, no GitHub required",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -28,7 +28,7 @@ import { randomUUID } from 'node:crypto';
 import { stdin as input, stdout as output } from 'node:process';
 import { create as tarCreate } from 'tar';
 
-const VERSION = '0.5.1';
+const VERSION = '0.5.3';
 const DEFAULT_API_BASE = 'https://api.canner.ca';
 const CONFIG_DIR = join(homedir(), '.canner');
 const CREDENTIALS_PATH = join(CONFIG_DIR, 'credentials');
@@ -1119,8 +1119,11 @@ function sluggify(s) {
 const BOOLEAN_FLAGS = new Set([
   'json', 'reveal', 'sensitive', 'follow', 'dashboard', 'version', 'help',
   'replace', 'yes', 'no-wait', 'enable', 'disable', 'restore', 'download', 'rm', 'delete', 'instance', 'pitr',
+  'read-only', 'read-write', 'replication', 'group', 'login', 'adopt', 'strict',
 ]);
 
+const splitList = (v) => String(v).split(',').map((x) => x.trim()).filter(Boolean);
+
 // A flag repeated on the command line (e.g. `--allow a --allow b`) accumulates
 // into an array instead of the last one silently winning.
 function setArg(out, key, value) {
@@ -1174,6 +1177,10 @@ function parseArgs(argv) {
 //   canner db migrate-out [--from <name>] --to-url <url>|--to-env VAR|--to-url - --yes
 //   canner db copy <from> <to> [--to-project SLUG] [--replace]
 //   canner db ops [<id>]                                 recent operations / one operation
+//   canner db roles [<name>] [create|member-of|audit|rotate|rm|write-exclusions …]   roles, groups and logins
+//   canner db inject [<name>] [<login>|owner|off|on]     which credential the app receives
+//   canner db least-privilege [<name>] [--label app] --yes   run the app as a limited role; the owner goes to the build only
+//   canner db check [<name>] [--category security|performance] [--strict] [--json]   security and performance check
 //
 // Long operations (export, import, migrate, copy) run on the platform: the CLI
 // starts one, then waits and shows progress. Pass --no-wait to return the
@@ -1299,7 +1306,7 @@ async function cmdDb(args) {
     info(`${pad(bold('NAME'), 22)}${pad(bold('POSTGRES'), 11)}${pad(bold('SIZE'), 11)}${bold('STATUS')}`);
     for (const d of rows) {
       const status = d.over_quota_at ? red('write-locked (over quota)') : green('ok');
-      info(`${pad(d.is_primary ? `${d.name} ${dim('(DATABASE_URL)')}` : d.name, 22)}${pad(d.pg_version, 11)}${pad(`${d.size_mb} MB`, 11)}${status}`);
+      info(`${pad(d.is_primary ? `${d.name} ${dim(`(DATABASE_URL${d.inject_role ? ` as ${d.inject_role}` : ''})`)}` : d.name, 22)}${pad(d.pg_version, 11)}${pad(`${d.size_mb} MB`, 11)}${status}`);
     }
     const l = body?.limits;
     if (l && !l.advanced_enabled) muted('Additional databases, import and migration are available on paid plans.');
@@ -2015,19 +2022,110 @@ async function cmdDb(args) {
     return;
   }
 
+  if (sub === 'check') {
+    // A read-only security and performance check of one database (catalog only, never data). Works on every plan.
+    const label = args._[1] ?? 'primary';
+    if (args.category !== undefined && args.category !== 'security' && args.category !== 'performance') die('--category must be security or performance.', 2);
+    const r = await apiJSON(creds, 'GET', `${base}/databases/${encodeURIComponent(label)}/security-check`);
+    const findings = typeof args.category === 'string' ? r.check.findings.filter((f) => f.category === args.category) : r.check.findings;
+    const warn = findings.filter((f) => f.severity === 'warn').length;
+    const note = findings.length - warn;
+    if (JSON_MODE) emitJSON({ ...r.check, findings, summary: { warn, info: note } });
+    else {
+      info(`${bold(label)}  ${warn > 0 ? yellow(`${warn} warning${warn === 1 ? '' : 's'}`) : green('no warnings')}  ${dim(`· ${note} note${note === 1 ? '' : 's'}`)}`);
+      for (const category of ['security', 'performance']) {
+        const group = findings.filter((f) => f.category === category);
+        if (group.length === 0) continue;
+        info('');
+        info(bold(category.toUpperCase()));
+        for (const f of group) {
+          const objs = f.objects.length > 0 ? `  ${dim(`[${f.objects.join(', ')}${f.more ? ', …' : ''}]`)}` : '';
+          info(`  ${f.severity === 'warn' ? yellow('warn') : dim('info')}  ${f.message}${objs}`);
+        }
+      }
+      if (findings.length === 0) info(green('nothing to report'));
+    }
+    // For CI: --strict fails the run when anything is a warning.
+    if (args.strict === true && warn > 0) process.exitCode = 1;
+    return;
+  }
+
+  if (sub === 'inject') {
+    // Which credential the app receives as DATABASE_URL (or DATABASE_URL_<NAME>): the owner's (the default) or one of your logins.
+    const label = args._[1] ?? 'primary';
+    const what = args._[2];
+    const envVar = label === 'primary' ? 'DATABASE_URL' : `DATABASE_URL_${label.toUpperCase()}`;
+    if (what === undefined) {
+      const body = await apiJSON(creds, 'GET', `${base}/databases`);
+      const d = (body?.databases ?? []).find((x) => x.name === label);
+      if (!d) die(`no database named "${label}".`);
+      if (JSON_MODE) return emitJSON({ name: d.name, auto_inject: d.auto_inject, inject_role: d.inject_role ?? null });
+      info(`${bold(envVar)}  ${!d.auto_inject ? yellow('not injected') : d.inject_role ? `the login ${green(d.inject_role)}` : 'the database owner'}`);
+      muted('Change it: canner db inject <db> <login> | owner | off | on');
+      return;
+    }
+    const patch = what === 'on' ? { auto_inject: true } : what === 'off' ? { auto_inject: false } : what === 'owner' ? { inject_role: null } : { inject_role: what };
+    const r = await apiJSON(creds, 'PATCH', `${base}/databases/${encodeURIComponent(label)}/settings`, patch);
+    if (JSON_MODE) return emitJSON(r.settings);
+    const st = r.settings;
+    info(`${green('saved')}  ${bold(envVar)}  ${!st.auto_inject ? yellow('not injected') : st.inject_role ? `the login ${green(st.inject_role)}` : 'the database owner'}`);
+    muted('Takes effect on the next deploy.');
+    return;
+  }
+
+  if (sub === 'least-privilege') {
+    // One step to the usual safe arrangement: the app logs in as a limited role, the owner (which can change the schema) is
+    // given to the BUILD only, as DATABASE_URL_MIGRATE, and every migration ledger stays read-only for the app's role.
+    const label = args._[1] ?? 'primary';
+    requireYes(args, 'The app will run as a limited role (it can read and write data but cannot change the schema) from its next deploy, and the database owner will be given to the build only, as DATABASE_URL_MIGRATE: run your migrations there.');
+    const r = await apiJSON(creds, 'POST', `${base}/databases/${encodeURIComponent(label)}/least-privilege`, {
+      confirm: true,
+      ...(typeof args.label === 'string' ? { label: args.label } : {}),
+    });
+    if (JSON_MODE) return emitJSON(r.least_privilege);
+    const lp = r.least_privilege;
+    const envVar = label === 'primary' ? 'DATABASE_URL' : `DATABASE_URL_${label.toUpperCase()}`;
+    info(`${green(lp.role.created ? 'created' : 'using')} the role ${bold(lp.role.label)}; ${bold(envVar)} will carry it from the next deploy`);
+    if (lp.protected_tables.length) info(`  kept read-only for it: ${lp.protected_tables.join(', ')}`);
+    for (const t of lp.suggestions ?? []) info(`  ${yellow('look at')} ${t} ${dim(`(looks like a ledger; keep it read-only with: canner db roles ${label} write-exclusions ${lp.role.label} ${t})`)}`);
+    info(`  ${bold(lp.migration_var)} is available to the build only: run your migrations with it (for example ${dim(`DATABASE_URL=$${lp.migration_var} npx prisma migrate deploy`)}).`);
+    muted('Run it again after your first migration: a ledger created later is also kept read-only for the app, within minutes, without this.');
+    return;
+  }
+
   if (sub === 'roles') {
     const label = args._[1] ?? 'primary';
     const action = args._[2];
     const path = `${base}/databases/${encodeURIComponent(label)}/roles`;
     if (action === 'create') {
       const name = args._[3];
-      if (!name) die('usage: canner db roles <db> create <name> --read-only | --read-write | --replication', 2);
-      const picked = ['read-only', 'read-write', 'replication'].filter((k) => args[k] === true);
-      if (picked.length !== 1) die('choose exactly one of --read-only, --read-write or --replication.', 2);
-      const r = await apiJSON(creds, 'POST', path, { label: name, kind: picked[0].replace('-', '_') });
+      if (!name) die('usage: canner db roles <db> create <name> --read-only | --read-write | --replication | --group | --login [--member-of g1,g2] [--adopt]', 2);
+      const picked = ['read-only', 'read-write', 'replication', 'group', 'login'].filter((k) => args[k] === true);
+      if (picked.length !== 1) die('choose exactly one of --read-only, --read-write, --replication, --group or --login.', 2);
+      const kind = picked[0].replace('-', '_');
+      const body = { label: name, kind };
+      if (args['member-of'] !== undefined) {
+        if (kind !== 'login') die('--member-of only applies to --login.', 2);
+        body.member_of = splitList(args['member-of']);
+      }
+      if (args.adopt === true) {
+        if (kind !== 'group') die('--adopt only applies to --group.', 2);
+        body.adopt = true;
+      }
+      const r = await apiJSON(creds, 'POST', path, body);
       if (JSON_MODE) return emitJSON({ ...r.role, write_exclusion_suggestions: r.write_exclusion_suggestions });
-      info(`${green('created')} ${r.role.kind === 'read_write' ? 'read-write' : r.role.kind === 'replication' ? 'replication' : 'read-only'} role ${bold(r.role.label)}`);
+      const kindWord = { read_write: 'read-write', replication: 'replication', read_only: 'read-only', group: 'group', login: 'login' }[r.role.kind];
+      info(`${green(args.adopt === true ? 'adopted' : 'created')} ${kindWord} ${kind === 'group' || kind === 'login' ? '' : 'role '}${bold(r.role.label)}`);
+      if (r.role.kind === 'group') {
+        muted('Nothing logs in as a group. Grant it privileges (and attach row-level security policies) in your migrations, then give an app login membership:');
+        info(`  ${dim('canner db roles')} ${label} ${dim('create <name> --login --member-of')} ${bold(name)}`);
+        return;
+      }
       info(`  ${cyan(r.role.connection_string)}`);
+      if (r.role.kind === 'login') {
+        info(`  ${dim('member of:')} ${r.role.member_of?.length ? r.role.member_of.join(', ') : dim('no groups yet: it can connect and nothing else')}`);
+        muted(`To run the app as this login: canner db inject ${label} ${name}`);
+      }
       if (r.role.write_excluded_tables?.length) {
         info(`  ${dim('kept SELECT-only:')} ${r.role.write_excluded_tables.join(', ')}`);
       }
@@ -2045,7 +2143,14 @@ async function cmdDb(args) {
     if (action === 'rotate' || action === 'rm') {
       const name = args._[3];
       if (!name) die(`usage: canner db roles <db> ${action} <name> --yes`, 2);
-      requireYes(args, action === 'rm' ? `This drops the role "${name}"; anything using its connection string stops working.` : `This gives "${name}" a new password; anything using the old one stops working.`);
+      let rmMessage = `This drops the role "${name}"; anything using its connection string stops working.`;
+      if (action === 'rm') {
+        const cur = (await apiJSON(creds, 'GET', path)).roles?.find((x) => x.label === name);
+        if (cur?.kind === 'group') {
+          rmMessage = `This deletes the group "${name}", the grants you made to it in this database, and any row-level security policy that applies only to it. Logins that were members lose what it gave them.`;
+        }
+      }
+      requireYes(args, action === 'rm' ? rmMessage : `This gives "${name}" a new password; anything using the old one stops working.`);
       if (action === 'rm') {
         await apiJSON(creds, 'DELETE', `${path}/${encodeURIComponent(name)}`);
         if (JSON_MODE) return emitJSON({ ok: true, deleted: name });
@@ -2057,6 +2162,60 @@ async function cmdDb(args) {
       }
       return;
     }
+    if (action === 'member-of') {
+      const name = args._[3];
+      const list = args._[4];
+      if (!name || list === undefined) die('usage: canner db roles <db> member-of <login> <group>[,<group>...]   (use "none" to remove every membership)', 2);
+      const groups = list === 'none' ? [] : splitList(list);
+      const r = await apiJSON(creds, 'PATCH', `${path}/${encodeURIComponent(name)}`, { member_of: groups });
+      if (JSON_MODE) return emitJSON(r.role);
+      info(`${green('updated')} ${bold(name)}  ${dim('member of:')} ${r.role.member_of?.length ? r.role.member_of.join(', ') : dim('no groups')}`);
+      return;
+    }
+    if (action === 'audit') {
+      const r = await apiJSON(creds, 'GET', `${path}/audit`);
+      const au = r.audit;
+      if (JSON_MODE) emitJSON(au);
+      else {
+        info(`${bold('the app is given')} ${au.injected === 'owner' ? yellow('the owner') : green(au.injected)}${au.injected === 'owner' ? dim('  (change it with `canner db inject`)') : ''}`);
+        info('');
+        info(bold('roles'));
+        for (const x of au.roles) {
+          const flags = [
+            x.can_login ? 'can log in' : 'no login', x.reads_all_data && 'reads all data', x.writes_all_data && 'writes all data',
+            x.bypass_rls && 'bypasses RLS', x.superuser && 'superuser', x.create_role && 'creates roles', x.create_db && 'creates databases',
+          ].filter(Boolean);
+          info(`  ${pad(bold(x.label), 24)}${pad(x.kind, 13)}${dim(flags.join(', '))}${x.member_of?.length ? `  ${dim('member of')} ${x.member_of.join(', ')}` : ''}`);
+        }
+        if (au.tables.length > 0) {
+          info('');
+          info(bold('tables'));
+          info(dim('  S select  I insert  U update  D delete'));
+          for (const tb of au.tables) {
+            const rls = tb.rls_enabled ? (tb.rls_forced ? 'RLS on, forced' : 'RLS on') : 'RLS off';
+            const pol = tb.policies.length ? ` · ${tb.policies.length} polic${tb.policies.length === 1 ? 'y' : 'ies'}` : '';
+            info(`  ${bold(tb.schema === 'public' ? tb.table : `${tb.schema}.${tb.table}`)}  ${dim(`owner ${tb.owner} · ${rls}${pol}`)}`);
+            for (const x of au.roles) {
+              const pr = tb.privileges[x.label];
+              if (!pr) continue;
+              const letters = `${pr.select ? 'S' : '-'}${pr.insert ? 'I' : '-'}${pr.update ? 'U' : '-'}${pr.delete ? 'D' : '-'}`;
+              info(`      ${pad(x.label, 24)}${letters === '----' ? dim(letters) : letters}`);
+            }
+          }
+        }
+        info('');
+        if (au.findings.length === 0) info(green('no findings'));
+        else {
+          info(bold('findings'));
+          for (const f of au.findings) {
+            info(`  ${f.severity === 'warn' ? yellow('warn') : dim('info')}  ${f.message}${f.tables?.length ? `  ${dim(`[${f.tables.join(', ')}]`)}` : ''}${f.roles?.length ? `  ${dim(`(${f.roles.join(', ')})`)}` : ''}`);
+          }
+        }
+      }
+      // For CI: --strict fails the run when anything is a warning.
+      if (args.strict === true && au.findings.some((f) => f.severity === 'warn')) process.exitCode = 1;
+      return;
+    }
     if (action === 'write-exclusions') {
       const name = args._[3];
       const table = args._[4];
@@ -2068,9 +2227,12 @@ async function cmdDb(args) {
     }
     const r = await apiJSON(creds, 'GET', path);
     if (JSON_MODE) return emitJSON(r.roles);
-    if (r.roles.length === 0) { muted(`no roles on ${label}. Create one with \`canner db roles ${label} create <name> --read-only\`.`); return; }
+    if (r.roles.length === 0) { muted(`no roles on ${label}. Create one with \`canner db roles ${label} create <name> --read-only\`, or manage your own privileges with --group and --login.`); return; }
     for (const x of r.roles) {
-      info(`${pad(bold(x.label), 22)}${x.kind === 'read_write' ? yellow('read-write') : x.kind === 'replication' ? cyan('replication') : green('read-only')}  ${dim(relTime(x.created_at))}`);
+      const kindLabel = x.kind === 'read_write' ? yellow('read-write') : x.kind === 'replication' ? cyan('replication') : x.kind === 'group' ? bold('group') : x.kind === 'login' ? green('login') : green('read-only');
+      info(`${pad(bold(x.label), 22)}${kindLabel}  ${dim(relTime(x.created_at))}`);
+      if (x.kind === 'group') { info(`  ${dim('no login: holds the grants and policies you give it')}`); continue; }
+      if (x.kind === 'login') info(`  ${dim('member of:')} ${x.member_of?.length ? x.member_of.join(', ') : dim('no groups yet')}`);
       info(`  ${cyan(x.connection_string)}`);
       if (x.external_connection_string) info(`  ${cyan(x.external_connection_string)}`);
       if (x.write_excluded_tables?.length) info(`  ${dim('kept SELECT-only:')} ${x.write_excluded_tables.join(', ')}`);
@@ -2229,7 +2391,46 @@ async function cmdDb(args) {
       return;
     }
 
-    die('usage: canner db instance [show] | create [--pg 17|18] [--pitr] [--window DAYS] | start | stop --yes | destroy --yes', 2);
+    if (action === 'upgrade') {
+      const what = args._[2];
+      const up = `${path}/upgrade`;
+      if (!what || what === 'check') {
+        const body = await apiJSON(creds, 'GET', up);
+        if (JSON_MODE) return emitJSON(body);
+        info(`${bold('Postgres')} ${body.current}${body.targets.length ? dim(`  can be upgraded to ${body.targets.join(', ')}`) : dim('  (already on the newest version offered)')}`);
+        for (const b of body.blockers ?? []) info(`  ${yellow('blocked')} ${b.message}`);
+        if (body.targets.length && !(body.blockers ?? []).length) muted('Upgrade with `canner db instance upgrade run --yes` (every database on the instance goes offline for a few minutes).');
+        if (body.rollback) info(`  ${dim(`the previous version (Postgres ${body.rollback.to_version}) is kept until ${body.rollback.until}: \`canner db instance upgrade rollback --yes\` goes back, \`... finish --yes\` discards it`)}`);
+        return;
+      }
+      if (what === 'run') {
+        requireYes(args, 'Upgrading restarts every database on the instance on a newer Postgres: they are offline for a few minutes. Roles, grants, policies and extensions carry over and the connection strings do not change. Point-in-time recovery starts a fresh window. If it fails, the instance is left as it was.');
+        const done = await startAndWait(creds, base, args, 'POST', up, { ...(args.pg ? { target: String(args.pg) } : {}), confirm: true }, 'upgrading');
+        if (!done) return;
+        if (JSON_MODE) return emitJSON(done);
+        info(`${green('upgraded')} the instance from Postgres ${done.result?.from_pg_version} to ${done.result?.to_pg_version}`);
+        muted('The previous version is kept for 7 days in case you need to roll back: `canner db instance upgrade rollback --yes`.');
+        return;
+      }
+      if (what === 'rollback') {
+        requireYes(args, 'A rollback goes back to the version before the upgrade and LOSES everything written since. Point-in-time recovery starts a fresh window.');
+        const done = await startAndWait(creds, base, args, 'POST', `${up}/rollback`, { confirm: true }, 'rolling back');
+        if (!done) return;
+        if (JSON_MODE) return emitJSON(done);
+        info(`${green('rolled back')} the instance to Postgres ${done.result?.to_pg_version}`);
+        return;
+      }
+      if (what === 'finish') {
+        requireYes(args, 'This discards the previous version, so a rollback is no longer possible.');
+        const body = await apiJSON(creds, 'POST', `${up}/finish`, { confirm: true });
+        if (JSON_MODE) return emitJSON(body);
+        info(`${green('done')}: the previous version was removed`);
+        return;
+      }
+      die('usage: canner db instance upgrade [check] | run [--pg 18] --yes | rollback --yes | finish --yes', 2);
+    }
+
+    die('usage: canner db instance [show] | create [--pg 17|18] [--pitr] [--window DAYS] | start | stop --yes | upgrade [check|run|rollback|finish] | destroy --yes', 2);
   }
 
   if (sub === 'pitr') {
@@ -2327,7 +2528,7 @@ async function cmdDb(args) {
     return;
   }
 
-  die(`unknown db subcommand "${sub}". Use: list | init | create | info | url | rm | pg-version | export | import | migrate-in | migrate-out | copy | ops | external | rotate | backup-policy | backup | backups | diff | inspect | alerts | roles | offsite | metrics | monitoring | insights | logs | resources | extensions | tuning | restart | replication | subscriptions | instance | pitr | pitr-restore | move.`, 2);
+  die(`unknown db subcommand "${sub}". Use: list | init | create | info | url | rm | pg-version | export | import | migrate-in | migrate-out | copy | ops | external | rotate | backup-policy | backup | backups | diff | inspect | alerts | roles | least-privilege | offsite | metrics | monitoring | insights | logs | resources | extensions | tuning | restart | replication | subscriptions | instance | pitr | pitr-restore | move.`, 2);
 }
 
 function printHelp() {
@@ -2438,14 +2639,30 @@ ${bold('Databases:')}
   ${bold('db')} monitoring [on|off --yes] [--slow-ms N]     Query insights + logs on the dedicated instance (restarts it).
   ${bold('db')} insights [<name>] [--sort total|mean|calls|max] [--limit N] | --reset --yes
   ${bold('db')} logs [<name>] [--level ERROR,WARNING] [--min-ms N] [--search TEXT] [--limit N]
-  ${bold('db')} roles [<name>]              List a database's roles (read-only / read-write logins).
+  ${bold('db')} roles [<name>]              List a database's roles (presets, groups and logins).
   ${bold('db')} roles <name> create <role> --read-only | --read-write
                        A read-write role keeps a migration ledger (schema_migrations and similar)
                        SELECT-only automatically; the response may suggest other candidates by name.
+  ${bold('db')} roles <name> create <role> --group [--adopt]
+                       A role nobody logs in as, named by you: your migrations grant to it and attach row-level
+                       security policies to it. --adopt takes over an existing NOLOGIN role of that name.
+  ${bold('db')} roles <name> create <role> --login [--member-of g1,g2]
+                       A login that can connect and nothing else: it gets what its groups hold (no blanket read).
+  ${bold('db')} roles <name> member-of <login> <g1,g2|none>   Set the groups a login belongs to, live.
+  ${bold('db')} roles <name> audit [--strict] [--json]
+                       What every role can actually do here (tables, row-level security, policies) and what looks
+                       wrong; --strict fails the run on any warning, for CI.
   ${bold('db')} roles <name> rotate <role> --yes
   ${bold('db')} roles <name> rm <role> --yes
   ${bold('db')} roles <name> write-exclusions <role> <table>
                        Keep one more table SELECT-only for a read-write role, live — no recreation.
+  ${bold('db')} check [<name>] [--category security|performance] [--strict] [--json]
+                       A read-only security and performance check of a database (every plan): policies that allow every
+                       row, functions anyone can run as their owner, views that bypass row-level security, missing primary
+                       keys and indexes, duplicate indexes. --strict fails the run on any warning, for CI.
+  ${bold('db')} inject [<name>] [<login> | owner | off | on]
+                       Which credential the app receives as DATABASE_URL: the owner's (default) or one of your
+                       logins. Takes effect on the next deploy.
   ${bold('db')} offsite                     List the off-site backup destinations (S3-compatible buckets).
   ${bold('db')} offsite add <name> --endpoint HOST --bucket NAME --access-key KEY --secret-key SECRET [--region R] [--folder F]
   ${bold('db')} offsite edit <name> [--new-name N] [--endpoint HOST] [--bucket NAME] [--access-key KEY] [--secret-key SECRET] [--region R] [--folder F]