@zapqr/cli 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# `zapqr` — sign in with ZapQR from a terminal
+
+**Not published to npm yet** — `npx @zapqr/cli` will 404. Run it from a checkout:
+
+```sh
+git clone -b feat/cli-device-login https://github.com/dasecure/zapqr-auth-idp.git
+cd zapqr-auth-idp/cli
+npm install          # optional: pulls qrcode, for the terminal QR
+node src/index.js login
+```
+
+Once it is published, that becomes:
+
+```sh
+npx @zapqr/cli login
+```
+
+Either way: a QR appears in your terminal. Scan it with your phone, approve, and this
+machine holds tokens. No password to type, no browser needed on this box —
+which is the point: the machine may be one you SSH'd into, and it has no
+business holding your passkey.
+
+Under the hood it's the OAuth 2.0 Device Authorization Grant (RFC 8628) — the
+same grant `gh auth login`, Apple TV and Roku use — against `auth.zapqr.ai`.
+
+## Commands
+
+| | |
+|---|---|
+| `zapqr login` | Approve on your phone; tokens land here |
+| `zapqr whoami` | Who this machine is signed in as (`--json` for scripts) |
+| `zapqr token` | Print a fresh access token to stdout |
+| `zapqr logout` | Revoke at the provider, then forget locally |
+
+`zapqr token` refreshes automatically when the access token has expired, so it
+is safe in a script:
+
+```sh
+curl -H "Authorization: Bearer $(zapqr token)" https://api.example.com/thing
+```
+
+## Options
+
+| Flag | Env | Default |
+|---|---|---|
+| `--issuer <url>` | `ZAPQR_ISSUER` | `https://auth.zapqr.ai` |
+| `--client-id <id>` | `ZAPQR_CLIENT_ID` | `zq-cli` |
+| `--scope <scope>` | `ZAPQR_SCOPE` | `openid email offline_access` |
+| `--no-qr` | | show the code without the QR |
+
+## Registering the client
+
+The device grant is opt-in per client. Before `zapqr login` works against a
+provider, register a client there of type **device** with the id `zq-cli`.
+Device clients are public — a CLI on someone else's laptop cannot keep a secret
+— and register with no redirect URIs.
+
+Until that client exists you'll get:
+
+```
+unauthorized_client
+  "zq-cli" is not registered for the device grant.
+```
+
+To try it before that client exists, borrow the demo one:
+
+```sh
+ZAPQR_CLIENT_ID=zq-unihiker-demo node src/index.js login
+```
+
+## Where tokens are stored
+
+`$XDG_CONFIG_HOME/zapqr/credentials.json` (or `~/.config/...`), mode `0600`,
+keyed by issuer so a staging provider can't overwrite production.
+
+Not the OS keychain, deliberately. The obvious macOS route is
+`security add-generic-password -w <secret>`, which puts the refresh token in
+argv where any process running `ps` can read it. Trading a file only you can
+read for a token that briefly leaks to every process on the machine is not an
+upgrade. A proper keychain integration needs a native binding — a dependency
+this CLI doesn't currently pay for.
+
+## Dependencies
+
+None required. `qrcode` is an *optional* dependency: with it you get the
+scannable QR, without it you get the URL and code, and the flow is identical.
+That keeps `npx` fast and lets the CLI run from a bare checkout.
+
+## What you'll see
+
+```
+  █▀▀▀▀▀█ ▄▀ ▄▄▀█ █▀▀▀▀▀█
+  █ ███ █ ▀█▄▀▄ █ █ ███ █
+  █ ▀▀▀ █ █▄▀▄█▀▀ █ ▀▀▀ █
+  ▀▀▀▀▀▀▀ █▄█▄█▄█ ▀▀▀▀▀▀▀
+
+  Scan with your phone, or open auth.zapqr.ai/device
+  and enter the code  WXTM-9K4P
+
+  Only approve this if you started it. Nobody legitimate will
+  ever send you a code to enter here.
+
+  waiting for approval… 04:31 left
+```
+
+That last warning is not decoration. A code someone else sends you, with a
+plausible reason to type it in, is exactly how this flow gets stolen — the
+same attack the device-link ceremony's copy defends against.
+
+## Exit codes
+
+`0` success · `1` failure or declined · `2` the code expired (retry)

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@zapqr/cli",
+  "version": "0.1.0",
+  "description": "Sign in with ZapQR from a terminal — OAuth 2.0 Device Authorization Grant (RFC 8628)",
+  "type": "module",
+  "bin": {
+    "zapqr": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "node --test test/*.test.js"
+  },
+  "optionalDependencies": {
+    "qrcode": "^1.5.4"
+  },
+  "keywords": [
+    "zapqr",
+    "oidc",
+    "oauth",
+    "device-flow",
+    "rfc8628",
+    "passwordless",
+    "cli"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dasecure/zapqr-auth-idp.git",
+    "directory": "cli"
+  },
+  "homepage": "https://zapqr.ai",
+  "bugs": {
+    "url": "https://github.com/dasecure/zapqr-auth-idp/issues"
+  }
+}

package/src/index.js

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+// Sign in with ZapQR from a terminal.
+//
+//   zapqr login      approve on your phone, tokens land here
+//   zapqr whoami     who this machine is signed in as
+//   zapqr token      print a fresh access token (for scripts)
+//   zapqr logout     revoke at the provider, then forget locally
+//
+// The point of the device grant here: the machine running this command may be
+// a box you SSH'd into, with no browser and no business holding your passkey.
+// It shows a code; the phone in your pocket does the authenticating.
+
+import { discover, pollForToken, refresh, requestDeviceCode, revoke, userinfo } from './oauth.js';
+import { clear, load, save, storePath } from './store.js';
+
+const DEFAULTS = {
+  issuer: process.env.ZAPQR_ISSUER || 'https://auth.zapqr.ai',
+  clientId: process.env.ZAPQR_CLIENT_ID || 'zq-cli',
+  scope: process.env.ZAPQR_SCOPE || 'openid email offline_access',
+};
+
+const isTTY = process.stderr.isTTY;
+const bold = (s) => (isTTY ? `\x1b[1m${s}\x1b[0m` : s);
+const dim = (s) => (isTTY ? `\x1b[2m${s}\x1b[0m` : s);
+const red = (s) => (isTTY ? `\x1b[31m${s}\x1b[0m` : s);
+const green = (s) => (isTTY ? `\x1b[32m${s}\x1b[0m` : s);
+
+/** Human output goes to stderr; only machine-readable values go to stdout, so
+ *  `zapqr token` stays pipeable. */
+const say = (...a) => console.error(...a);
+
+function parseArgs(argv) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--no-qr') flags.noQr = true;
+    else if (a === '--json') flags.json = true;
+    else if (a === '--issuer') flags.issuer = argv[++i];
+    else if (a === '--client-id') flags.clientId = argv[++i];
+    else if (a === '--scope') flags.scope = argv[++i];
+    else if (a === '-h' || a === '--help') flags.help = true;
+    else rest.push(a);
+  }
+  return { flags, rest };
+}
+
+function config(flags) {
+  return {
+    issuer: (flags.issuer || DEFAULTS.issuer).replace(/\/+$/, ''),
+    clientId: flags.clientId || DEFAULTS.clientId,
+    scope: flags.scope || DEFAULTS.scope,
+  };
+}
+
+/** The QR is what makes this feel like ZapQR rather than code-typing: scan the
+ *  terminal, approve, done. It is optional on purpose — the CLI has no required
+ *  dependencies, so a bare `node src/index.js` still signs you in. */
+async function renderQR(url) {
+  try {
+    const { default: QRCode } = await import('qrcode');
+    return await QRCode.toString(url, { type: 'terminal', small: true, errorCorrectionLevel: 'M' });
+  } catch {
+    return null;
+  }
+}
+
+async function cmdLogin(flags) {
+  const { issuer, clientId, scope } = config(flags);
+  const doc = await discover(issuer);
+  const auth = await requestDeviceCode({ doc, clientId, scope });
+
+  const verifyFull = auth.verification_uri_complete || auth.verification_uri;
+  const qr = flags.noQr ? null : await renderQR(verifyFull);
+
+  say('');
+  if (qr) {
+    say(qr);
+    say(`  ${dim('Scan with your phone, or open')} ${bold(auth.verification_uri)}`);
+  } else {
+    say(`  ${dim('On your phone, open')} ${bold(auth.verification_uri)}`);
+  }
+  say(`  ${dim('and enter the code')}  ${bold(auth.user_code)}`);
+  say('');
+  say(`  ${dim('Only approve this if you started it. Nobody legitimate will')}`);
+  say(`  ${dim('ever send you a code to enter here.')}`);
+  say('');
+
+  const result = await pollForToken({
+    doc,
+    clientId,
+    deviceCode: auth.device_code,
+    interval: auth.interval,
+    expiresIn: auth.expires_in,
+    onTick: (left) => {
+      if (!isTTY) return;
+      const m = String(Math.floor(left / 60)).padStart(2, '0');
+      const s = String(left % 60).padStart(2, '0');
+      process.stderr.write(`\r  waiting for approval… ${m}:${s} left `);
+    },
+  });
+  if (isTTY) process.stderr.write('\r' + ' '.repeat(40) + '\r');
+
+  if (!result.ok) {
+    const msg = {
+      declined: 'Declined on the phone.',
+      expired: 'The code expired. Run `zapqr login` again.',
+    }[result.reason] || `Sign-in failed: ${result.reason}`;
+    say(red(`  ${msg}`));
+    return result.reason === 'expired' ? 2 : 1;
+  }
+
+  const tokens = result.tokens;
+  let email = null;
+  try {
+    email = (await userinfo({ doc, accessToken: tokens.access_token })).email ?? null;
+  } catch {
+    // A userinfo hiccup does not undo a successful sign-in.
+  }
+
+  save(issuer, {
+    client_id: clientId,
+    scope,
+    email,
+    access_token: tokens.access_token,
+    refresh_token: tokens.refresh_token ?? null,
+    id_token: tokens.id_token ?? null,
+    // 30s of slack so a token that dies mid-request is refreshed beforehand.
+    expires_at: Date.now() + ((tokens.expires_in ?? 3600) - 30) * 1000,
+  });
+
+  say(green(`  ✓ Signed in${email ? ` as ${bold(email)}` : ''}`));
+  say(dim(`  Tokens stored in ${storePath()} (0600)`));
+  if (!tokens.refresh_token) {
+    say(dim('  No refresh token — add the offline_access scope to stay signed in.'));
+  }
+  return 0;
+}
+
+/** Anything needing a live token comes through here, so refresh-on-expiry is
+ *  in exactly one place. rotateRefreshToken is on at the provider: the refresh
+ *  token that comes back replaces the one we sent, and losing it means the
+ *  session is stranded. */
+async function freshAccessToken(issuer, flags) {
+  const rec = load(issuer);
+  if (!rec) return null;
+  if (Date.now() < rec.expires_at) return rec;
+  if (!rec.refresh_token) return null;
+
+  const doc = await discover(issuer);
+  const tokens = await refresh({ doc, clientId: rec.client_id, refreshToken: rec.refresh_token });
+  const updated = {
+    ...rec,
+    access_token: tokens.access_token,
+    refresh_token: tokens.refresh_token ?? rec.refresh_token,
+    id_token: tokens.id_token ?? rec.id_token,
+    expires_at: Date.now() + ((tokens.expires_in ?? 3600) - 30) * 1000,
+  };
+  save(issuer, updated);
+  return updated;
+}
+
+async function cmdWhoami(flags) {
+  const { issuer } = config(flags);
+  let rec;
+  try {
+    rec = await freshAccessToken(issuer, flags);
+  } catch (err) {
+    say(red(`  Session could not be refreshed: ${err.message}`));
+    say(dim('  Run `zapqr login` again.'));
+    return 1;
+  }
+  if (!rec) {
+    say(dim(`  Not signed in to ${issuer}. Run \`zapqr login\`.`));
+    return 1;
+  }
+
+  const doc = await discover(issuer);
+  let info = { email: rec.email };
+  try {
+    info = await userinfo({ doc, accessToken: rec.access_token });
+  } catch {
+    // Fall back to what we stored at login rather than failing the command.
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify({ issuer, client_id: rec.client_id, ...info }, null, 2));
+  } else {
+    say(`  ${bold(info.email ?? '(unknown)')}`);
+    say(dim(`  ${issuer} · client ${rec.client_id}${info.sub ? ` · sub ${info.sub}` : ''}`));
+  }
+  return 0;
+}
+
+async function cmdToken(flags) {
+  const { issuer } = config(flags);
+  const rec = await freshAccessToken(issuer, flags);
+  if (!rec) {
+    say(dim('  Not signed in. Run `zapqr login`.'));
+    return 1;
+  }
+  console.log(rec.access_token); // stdout: the whole point is `$(zapqr token)`
+  return 0;
+}
+
+async function cmdLogout(flags) {
+  const { issuer } = config(flags);
+  const rec = load(issuer);
+  if (!rec) {
+    say(dim('  Not signed in.'));
+    return 0;
+  }
+  try {
+    const doc = await discover(issuer);
+    // Revoking the refresh token is what actually ends the grant; the access
+    // token expires on its own within the hour either way.
+    if (rec.refresh_token) {
+      await revoke({ doc, clientId: rec.client_id, token: rec.refresh_token, hint: 'refresh_token' });
+    }
+    await revoke({ doc, clientId: rec.client_id, token: rec.access_token, hint: 'access_token' });
+  } catch {
+    // Offline, or the provider is down: still forget the local copy.
+  }
+  clear(issuer);
+  say(green('  ✓ Signed out'));
+  return 0;
+}
+
+function usage() {
+  say(`${bold('zapqr')} — sign in with ZapQR from a terminal
+
+  ${bold('zapqr login')}     approve on your phone, tokens land here
+  ${bold('zapqr whoami')}    who this machine is signed in as  ${dim('[--json]')}
+  ${bold('zapqr token')}     print a fresh access token, for scripts
+  ${bold('zapqr logout')}    revoke at the provider, then forget locally
+
+${dim('Options')}
+  --issuer <url>      default ${DEFAULTS.issuer}  ${dim('(ZAPQR_ISSUER)')}
+  --client-id <id>    default ${DEFAULTS.clientId}  ${dim('(ZAPQR_CLIENT_ID)')}
+  --scope <scope>     default "${DEFAULTS.scope}"  ${dim('(ZAPQR_SCOPE)')}
+  --no-qr             show the code without the QR
+`);
+}
+
+const COMMANDS = { login: cmdLogin, whoami: cmdWhoami, token: cmdToken, logout: cmdLogout };
+
+const { flags, rest } = parseArgs(process.argv.slice(2));
+const name = rest[0];
+
+if (flags.help || !name) {
+  usage();
+  // Asking for help is a success; being given no command at all is not.
+  process.exit(flags.help ? 0 : 1);
+}
+const run = COMMANDS[name];
+if (!run) {
+  say(red(`  Unknown command "${name}"`));
+  usage();
+  process.exit(1);
+}
+
+try {
+  process.exit(await run(flags));
+} catch (err) {
+  say(red(`  ${err.message}`));
+  process.exit(1);
+}

package/src/oauth.js

@@ -0,0 +1,134 @@
+// The protocol half of the CLI: RFC 8628 device grant against auth.zapqr.ai.
+//
+// Three moves, and none of them involve a browser on this machine: ask the
+// provider for a code, show it to the human, poll until they approve on their
+// phone. The terminal never sees a credential — only a code that is worthless
+// without the person holding the phone.
+
+/** Endpoints move. Discovery is the only URL this file is allowed to know. */
+export async function discover(issuer) {
+  const url = issuer.replace(/\/+$/, '') + '/.well-known/openid-configuration';
+  const res = await fetch(url, { headers: { accept: 'application/json' } });
+  if (!res.ok) throw new Error(`discovery failed: ${res.status} ${url}`);
+  const doc = await res.json();
+  if (!doc.device_authorization_endpoint) {
+    throw new Error(`${issuer} does not advertise a device_authorization_endpoint`);
+  }
+  return doc;
+}
+
+/**
+ * OAuth returns its errors as JSON with a 4xx, so a non-2xx is data, not an
+ * exception — the poll loop below depends on reading the error code out of it.
+ */
+async function postForm(url, fields) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/x-www-form-urlencoded',
+      accept: 'application/json',
+    },
+    body: new URLSearchParams(fields).toString(),
+  });
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    body = { error: `http_${res.status}` };
+  }
+  return { status: res.status, body };
+}
+
+export async function requestDeviceCode({ doc, clientId, scope }) {
+  const { status, body } = await postForm(doc.device_authorization_endpoint, {
+    client_id: clientId,
+    scope,
+  });
+  if (status >= 400) {
+    const hint = body.error === 'unauthorized_client'
+      ? `\n  "${clientId}" is not registered for the device grant. Register it at ` +
+        `${doc.issuer}/account as a client of type "device", or set ZAPQR_CLIENT_ID.`
+      : '';
+    throw new Error(`${body.error ?? status}${body.error_description ? `: ${body.error_description}` : ''}${hint}`);
+  }
+  return body;
+}
+
+/**
+ * Poll until the human decides. Two rules that are easy to get wrong:
+ *  - the interval belongs to the SERVER. `slow_down` means back off and stay
+ *    backed off; a client that ignores it gets throttled or blocked.
+ *  - `expired_token` must leave the loop by returning, not by breaking out
+ *    into the success path with no tokens in hand.
+ * onTick reports remaining seconds so the caller can redraw a countdown.
+ * `sleep` and `now` are injectable so the back-off can be asserted in a test
+ * without the test actually sitting there for five seconds.
+ */
+export async function pollForToken({
+  doc, clientId, deviceCode, interval, expiresIn, onTick,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  now = () => Date.now(),
+}) {
+  let wait = (interval ?? 5) * 1000;
+  const deadline = now() + (expiresIn ?? 300) * 1000;
+
+  while (now() < deadline) {
+    await sleep(wait);
+    const { status, body } = await postForm(doc.token_endpoint, {
+      client_id: clientId,
+      device_code: deviceCode,
+      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+    });
+
+    if (status === 200) return { ok: true, tokens: body };
+
+    switch (body.error) {
+      case 'authorization_pending':
+        onTick?.(Math.max(0, Math.round((deadline - now()) / 1000)));
+        continue;
+      case 'slow_down':
+        wait += 5000;
+        continue;
+      case 'access_denied':
+        return { ok: false, reason: 'declined' };
+      case 'expired_token':
+        return { ok: false, reason: 'expired' };
+      default:
+        return { ok: false, reason: body.error_description || body.error || `http_${status}` };
+    }
+  }
+  return { ok: false, reason: 'expired' };
+}
+
+export async function refresh({ doc, clientId, refreshToken }) {
+  const { status, body } = await postForm(doc.token_endpoint, {
+    client_id: clientId,
+    grant_type: 'refresh_token',
+    refresh_token: refreshToken,
+  });
+  if (status !== 200) throw new Error(body.error_description || body.error || `refresh failed (${status})`);
+  return body;
+}
+
+/** Best-effort: a revoke that fails must not stop us deleting the local copy. */
+export async function revoke({ doc, clientId, token, hint }) {
+  if (!doc.revocation_endpoint) return false;
+  try {
+    const { status } = await postForm(doc.revocation_endpoint, {
+      client_id: clientId,
+      token,
+      token_type_hint: hint,
+    });
+    return status < 400;
+  } catch {
+    return false;
+  }
+}
+
+export async function userinfo({ doc, accessToken }) {
+  const res = await fetch(doc.userinfo_endpoint, {
+    headers: { authorization: `Bearer ${accessToken}`, accept: 'application/json' },
+  });
+  if (!res.ok) throw new Error(`userinfo failed: ${res.status}`);
+  return res.json();
+}

package/src/store.js

@@ -0,0 +1,65 @@
+// Where the tokens live between commands.
+//
+// A 0600 file under $XDG_CONFIG_HOME (or ~/.config), not the OS keychain, and
+// that is a deliberate choice rather than a shortcut. The obvious keychain
+// route on macOS is `security add-generic-password -w <secret>`, which puts the
+// refresh token in argv — readable by any process that can run `ps` for as long
+// as the call lasts. Trading a file only this user can read for a token that
+// briefly leaks to every process on the box is not an upgrade. A real keychain
+// integration wants a native binding, which is a dependency this CLI does not
+// currently pay for.
+
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+function configPath() {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(base, 'zapqr', 'credentials.json');
+}
+
+/** Keyed by issuer, so a staging provider cannot quietly overwrite production. */
+export function load(issuer) {
+  try {
+    const all = JSON.parse(readFileSync(configPath(), 'utf8'));
+    return all[issuer] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function save(issuer, record) {
+  const path = configPath();
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+
+  let all = {};
+  try {
+    all = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    // First write, or a file we cannot parse: start clean rather than refuse.
+  }
+  all[issuer] = record;
+
+  // Create with 0600 from the outset — writing then chmod'ing leaves a window
+  // where another user on the machine can open the file.
+  writeFileSync(path, JSON.stringify(all, null, 2) + '\n', { mode: 0o600 });
+  chmodSync(path, 0o600); // pre-existing file: writeFileSync's mode is ignored
+  return path;
+}
+
+export function clear(issuer) {
+  const path = configPath();
+  try {
+    const all = JSON.parse(readFileSync(path, 'utf8'));
+    delete all[issuer];
+    if (Object.keys(all).length === 0) rmSync(path, { force: true });
+    else writeFileSync(path, JSON.stringify(all, null, 2) + '\n', { mode: 0o600 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function storePath() {
+  return configPath();
+}