@adtl/gateway 0.8.0 → 0.8.1

package/src/hooks/claudeCode.ts

@@ -26,7 +26,7 @@
  *
  * Errors fail closed: a PreToolUse hook that can't decide denies the call.
  */
-import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import {
   callHash,
   evaluatePolicy,
@@ -41,6 +41,7 @@ import {
 } from "@adtl/labels";
 import { chunkHashes, valueHashes, type Ledger } from "@adtl/ledger";
 import type { AuditEntry, AuditSink } from "../audit.js";
+import { TOTP_KEYCHAIN_SERVICE } from "../totp.js";
 import type { AgentLinks } from "./agentLinks.js";
 import { CLAUDE_CODE_PRESET, CLAUDE_CODE_SERVER } from "./preset.js";
 
@@ -71,7 +72,7 @@ export interface HookOptions {
   /** Sub-agent → parent session links, from SubagentStart. */
   agents?: AgentLinks;
   /** Files the agent must not change: the ADTL config, the session directory and the ledger. */
-  protect?: { configPath?: string; sessionsDir?: string; ledgerPath?: string; auditPath?: string; signingKeyPath?: string };
+  protect?: { configPath?: string; sessionsDir?: string; ledgerPath?: string; auditPath?: string; signingKeyPath?: string; totpPath?: string };
 }
 
 /** What the hook process prints and exits with. */
@@ -144,6 +145,9 @@ function protectedTarget(input: HookInput, route: { server: string; tool: string
     if (protect.signingKeyPath && abs === resolve(protect.signingKeyPath)) {
       return { decision: "block", reason: "The agent may not touch the ADTL signing key" };
     }
+    if (protect.totpPath && abs.startsWith(dirname(resolve(protect.totpPath)) + sep + "totp-")) {
+      return { decision: "block", reason: "The agent may not touch the ADTL TOTP secret" };
+    }
   }
   const command = typeof args.command === "string" ? args.command : undefined;
   if (command !== undefined && ["Bash", "Monitor"].includes(route.tool)) {
@@ -161,6 +165,9 @@ function protectedTarget(input: HookInput, route: { server: string; tool: string
     if (protect.signingKeyPath && command.includes(basename(protect.signingKeyPath))) {
       return { decision: "ask", reason: "This command touches the ADTL signing key" };
     }
+    if ([TOTP_KEYCHAIN_SERVICE, "totp-secret", "totp-last-step", protect.totpPath].some((m) => m && command.includes(m))) {
+      return { decision: "ask", reason: "This command touches the ADTL TOTP secret" };
+    }
   }
   return undefined;
 }

package/src/hooks/run.ts

@@ -13,6 +13,7 @@ import { Ledger, defaultLedgerPath } from "@adtl/ledger";
 import { parseConfigText } from "@adtl/interceptors";
 import { parse as parseYaml } from "yaml";
 import { JsonlAuditLog } from "../audit.js";
+import { totpSecretPath } from "../totp.js";
 import { FileAgentLinks } from "./agentLinks.js";
 import { failure, handleHook, type HookInput, type HookOutcome } from "./claudeCode.js";
 
@@ -52,7 +53,7 @@ export async function runHook(opts: RunHookOptions): Promise<HookOutcome> {
       ...(opts.gatewayServer ? { gatewayServer: opts.gatewayServer } : {}),
       mode: gw.mode === "audit" ? "audit" : "active",
       ...(auditPath ? { audit: new JsonlAuditLog(auditPath) } : {}),
-      protect: { configPath: path, sessionsDir, ledgerPath, ...(auditPath ? { auditPath } : {}), signingKeyPath: defaultSigningKeyPath(env) },
+      protect: { configPath: path, sessionsDir, ledgerPath, ...(auditPath ? { auditPath } : {}), signingKeyPath: defaultSigningKeyPath(env), totpPath: totpSecretPath(env) },
     });
   } catch (err) {
     return failure(input.hook_event_name, (err as Error).message);

package/src/index.ts

@@ -13,6 +13,9 @@ export * from "./ledgerCli.js";
 export * from "./auditCli.js";
 export * from "./roles.js";
 export * from "./cedar.js";
+export * from "./openfga.js";
+export * from "./totp.js";
+export * from "./totpCli.js";
 export * from "./elicitation.js";
 export * from "./receipt.js";
 export * from "./receiptCli.js";

package/src/invoker.ts

@@ -160,6 +160,13 @@ export function checkOverrides(defs: InterceptorDefinition[], overrides: Record<
   return problems;
 }
 
+/** Interceptors of a type this invoker doesn't run (e.g. the proposed `sink`). They are never invoked. */
+export function unsupportedInterceptors(bound: BoundInterceptor[]): string[] {
+  return bound
+    .filter((b) => b.definition.type !== "validation" && b.definition.type !== "mutation")
+    .map((b) => `${b.definition.name} (${String(b.definition.type)})`);
+}
+
 /** Interceptor names offered by more than one server: each must be invoked on its own server, so names must be unique. */
 export function duplicateInterceptors(bound: BoundInterceptor[]): string[] {
   const servers = new Map<string, string[]>();

package/src/openfga.ts

@@ -0,0 +1,101 @@
+/**
+ * Relationship-based authorization with OpenFGA (`gateway.openfga`):
+ *
+ *   openfga:
+ *     url: http://localhost:8080
+ *     storeId: "${FGA_STORE_ID}"
+ *     modelId: "${FGA_MODEL_ID}"     # optional: pin an authorization model
+ *     token: "${FGA_TOKEN}"          # optional: bearer token
+ *     relation: can_use              # optional: the default relation
+ *     timeoutMs: 2000                # optional
+ *     tools:                         # optional: per-resource rules, from the call's arguments
+ *       github.add_issue_comment: { relation: can_comment, object: "repo:{owner}/{repo}" }
+ *
+ * Every call becomes one OpenFGA check:
+ *
+ *   user      user:<id>, service:<id>, or user:anonymous without an id
+ *   relation  the tool's rule, else `relation`
+ *   object    the tool's rule, else tool:<server>.<tool>, prompt:<server>.<name> or resource:<uri>
+ *
+ * Ids are percent-encoded, because OpenFGA ids can't hold `:`, `#`, `@` or
+ * spaces; ids too long for OpenFGA are replaced by their SHA-256. A rule's
+ * `{argument}` must be a string or number, or the call is denied. Tool lists
+ * have no arguments, so tools whose object needs them stay listed and are
+ * checked when called. An unreachable server or an error denies the call.
+ *
+ * Works with Auth0 FGA too, by pointing `url` at its API and passing a token.
+ */
+import { createHash } from "node:crypto";
+import type { AuthorizationDecision, AuthorizationRequest, Authorizer } from "./authorizer.js";
+import type { OpenFgaConfig } from "./config.js";
+
+/** OpenFGA's limit on the id part of an object or user. */
+const MAX_ID = 254;
+
+function fgaId(value: string): string {
+  const id = encodeURIComponent(value);
+  return id.length <= MAX_ID ? id : `sha256-${createHash("sha256").update(value).digest("hex")}`;
+}
+
+const PLACEHOLDER = /\{([A-Za-z0-9_.-]+)\}/g;
+
+export class OpenFgaAuthorizer implements Authorizer {
+  readonly name = "openfga";
+
+  constructor(
+    private readonly cfg: OpenFgaConfig,
+    private readonly fetchFn: typeof fetch = fetch,
+  ) {}
+
+  private user(req: AuthorizationRequest): string {
+    const p = req.principal;
+    if (p.type === "anonymous" || !p.id) return "user:anonymous";
+    return `${p.type === "service" ? "service" : "user"}:${fgaId(p.id)}`;
+  }
+
+  /** The object of this call, or a reason it can't be built. "listing" means: decide when called. */
+  private object(req: AuthorizationRequest, template?: string): { object: string } | { missing: string } | "listing" {
+    if (template !== undefined) {
+      if (req.arguments === undefined && template.search(PLACEHOLDER) !== -1) return "listing";
+      const colon = template.indexOf(":");
+      const type = template.slice(0, colon + 1);
+      let missing: string | undefined;
+      const id = template.slice(colon + 1).replace(PLACEHOLDER, (_, name: string) => {
+        const v = req.arguments?.[name];
+        if (typeof v !== "string" && typeof v !== "number") {
+          missing ??= name;
+          return "";
+        }
+        return String(v);
+      });
+      return missing !== undefined ? { missing } : { object: `${type}${fgaId(id)}` };
+    }
+    if (req.tool !== undefined) return { object: `tool:${fgaId(`${req.server}.${req.tool}`)}` };
+    if (req.prompt !== undefined) return { object: `prompt:${fgaId(`${req.server}.${req.prompt}`)}` };
+    return { object: `resource:${fgaId(req.resource ?? "")}` };
+  }
+
+  async check(req: AuthorizationRequest): Promise<AuthorizationDecision> {
+    const rule = req.tool !== undefined ? this.cfg.tools[`${req.server}.${req.tool}`] : undefined;
+    const target = this.object(req, rule?.object);
+    if (target === "listing") return { allow: true };
+    const what = req.tool ?? req.prompt ?? req.resource;
+    if ("missing" in target) return { allow: false, reason: `openfga: ${what} has no usable argument "${target.missing}"` };
+
+    const user = this.user(req);
+    const relation = rule?.relation ?? this.cfg.relation;
+    const res = await this.fetchFn(`${this.cfg.url.replace(/\/+$/, "")}/stores/${encodeURIComponent(this.cfg.storeId)}/check`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...(this.cfg.token ? { authorization: `Bearer ${this.cfg.token}` } : {}) },
+      body: JSON.stringify({
+        tuple_key: { user, relation, object: target.object },
+        ...(this.cfg.modelId ? { authorization_model_id: this.cfg.modelId } : {}),
+      }),
+      signal: AbortSignal.timeout(this.cfg.timeoutMs),
+    });
+    if (!res.ok) throw new Error(`OpenFGA answered ${res.status}`);
+    const body = (await res.json()) as { allowed?: unknown };
+    if (body.allowed === true) return { allow: true };
+    return { allow: false, reason: `OpenFGA: ${user} has no ${relation} on ${target.object}` };
+  }
+}

package/src/startup.ts

@@ -28,7 +28,9 @@ import {
 } from "./config.js";
 import { EmailNotifier } from "./email.js";
 import { AdtlGateway, GATEWAY_VERSION, type GatewayLogger } from "./gateway.js";
-import { InterceptorInvoker, checkOverrides, duplicateInterceptors, mutatorsAfter } from "./invoker.js";
+import { InterceptorInvoker, checkOverrides, duplicateInterceptors, mutatorsAfter, unsupportedInterceptors } from "./invoker.js";
+import { OpenFgaAuthorizer } from "./openfga.js";
+import { loadTotpVerifier } from "./totp.js";
 import { NtfyNotifier } from "./ntfy.js";
 import { RoleAuthorizer } from "./roles.js";
 
@@ -124,12 +126,13 @@ export function createApprovals(cfg: GatewayConfig, env: NodeJS.ProcessEnv, log:
   const approverChannels = new Map<string, Notifier[]>(
     Object.entries(a.approvers ?? {}).map(([id, c]) => [id, [new NtfyNotifier({ ...c.ntfy, name: `ntfy:${id}` })]]),
   );
-  if (notifiers.length === 0 && approverChannels.size === 0 && !a.elicitation) return undefined;
-  if (!notifiers.some((n) => n.listen) && approverChannels.size === 0 && !a.elicitation) {
+  if (notifiers.length === 0 && approverChannels.size === 0 && !a.elicitation && !a.totp) return undefined;
+  if (!notifiers.some((n) => n.listen) && approverChannels.size === 0 && !a.elicitation && !a.totp) {
     log.warn('no approval channel can carry answers (configure gateway.approvals.ntfy); "ask" still blocks');
   }
   const approvers = approverChannels.size ? `; approvers: ${[...approverChannels.keys()].join(", ")}` : "";
-  const shared = [...notifiers.map((n) => n.name), ...(a.elicitation ? ["elicitation (if the client supports it)"] : [])];
+  const inClient = a.totp ? ["authenticator code (if the client supports elicitation)"] : a.elicitation ? ["elicitation (if the client supports it)"] : [];
+  const shared = [...notifiers.map((n) => n.name), ...inClient];
   log.info(`approvals: ${shared.join(", ") || "none shared"}${approvers} (timeout ${a.timeoutSeconds}s)`);
   return new ApprovalBroker({ notifiers, approverChannels, timeoutMs: a.timeoutSeconds * 1000, log });
 }
@@ -175,7 +178,7 @@ export function gatewayPrincipal(cfg: GatewayConfig, env: NodeJS.ProcessEnv): Pr
  * The configured authorizers, in the order they are asked: roles, then cedar.
  * Cedar files are read and parsed here, so a bad policy fails startup.
  */
-export async function gatewayAuthorizers(cfg: GatewayConfig, baseDir: string): Promise<Authorizer[]> {
+export async function gatewayAuthorizers(cfg: GatewayConfig, baseDir: string, env: NodeJS.ProcessEnv = process.env): Promise<Authorizer[]> {
   const out: Authorizer[] = [];
   if (cfg.roles) out.push(new RoleAuthorizer(cfg.roles));
   if (cfg.cedar) {
@@ -185,6 +188,19 @@ export async function gatewayAuthorizers(cfg: GatewayConfig, baseDir: string): P
       throw new GatewayConfigError((err as Error).message);
     }
   }
+  if (cfg.openfga) {
+    const f = cfg.openfga;
+    const expand = (v: string, key: string) => expandEnv(v, env, `gateway.openfga.${key}`);
+    out.push(
+      new OpenFgaAuthorizer({
+        ...f,
+        url: expand(f.url, "url"),
+        storeId: expand(f.storeId, "storeId"),
+        ...(f.modelId !== undefined ? { modelId: expand(f.modelId, "modelId") } : {}),
+        ...(f.token !== undefined ? { token: expand(f.token, "token") } : {}),
+      }),
+    );
+  }
   return out;
 }
 
@@ -222,7 +238,7 @@ export async function startGateway(
   // Config problems that need no process: fail before starting any.
   const approverMembers = approverRoles(loaded.labels, loaded.gateway);
   const baseDir = dirname(loaded.path);
-  const authorizers = await gatewayAuthorizers(loaded.gateway, baseDir);
+  const authorizers = await gatewayAuthorizers(loaded.gateway, baseDir, env);
   const log = opts.logger ?? { info: (m: string) => console.error(`[adtl-gateway] ${m}`), warn: (m: string) => console.error(`[adtl-gateway] warning: ${m}`) };
   const clients: Client[] = [];
   const closeAll = () => Promise.allSettled(clients.map((c) => c.close())).then(() => undefined);
@@ -278,6 +294,8 @@ export async function startGateway(
     const overrides = loaded.gateway.interceptorOverrides;
     const problems = checkOverrides(bound.map((b) => b.definition), overrides);
     if (problems.length) throw new GatewayConfigError(`gateway.interceptorOverrides: ${problems.join("; ")}`);
+    const unsupported = unsupportedInterceptors(bound);
+    if (unsupported.length) log.warn(`not running interceptors of an unknown type: ${unsupported.join(", ")}`);
     const late = mutatorsAfter(bound, LABEL_INTERCEPTOR, overrides);
     if (late.length) {
       log.warn(`${late.join(", ")} run after ${LABEL_INTERCEPTOR} and could change or drop its label; give them a lower priorityHint`);
@@ -324,11 +342,14 @@ export async function startGateway(
       if (!principal) log.warn('roles are set but gateway.principal is not: only roles with members ["*"] apply');
     }
     for (const a of authorizers) if (a.name !== "roles") log.info(`authorizer: ${a.name}`);
+    const totp = loaded.gateway.approvals?.totp ? loadTotpVerifier(env) : undefined;
+    if (loaded.gateway.approvals?.totp && !totp) throw new GatewayConfigError("gateway.approvals.totp is on, but no secret is set up: run adtl-gateway totp setup");
     const agent = gatewayAgent(env);
     if (agent) log.info(`agent: ${agent.id}${agent.type ? ` (${agent.type})` : ""}`);
     const gateway = new AdtlGateway({
       ...(shared ? { sessionId: shared.sessionId } : {}),
       ...(agent ? { agent } : {}),
+      ...(totp ? { totp } : {}),
       upstreams,
       invoker,
       ...(auditLog ? { audit: auditLog } : {}),

package/src/totp.ts

@@ -0,0 +1,191 @@
+/**
+ * Approval codes from an authenticator app (TOTP, RFC 6238: SHA-1, 6 digits,
+ * 30 seconds), entered in the MCP client's prompt. Codes are made offline on
+ * the phone, and a client that accepts prompts by itself can't produce one.
+ *
+ * The secret lives in the macOS Keychain, or elsewhere in a file only its
+ * owner can read (`ADTL_TOTP_FILE`, or `~/.adtl/totp-secret`). An agent with
+ * shell access as the same user may still reach either: the hooks ask before
+ * commands that mention them, but only a gateway on another machine rules it out.
+ *
+ * A code is accepted within one time step either way, and once: the last used
+ * step is kept in a file, so a code can't be replayed after a restart either.
+ */
+import { execFileSync } from "node:child_process";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const STEP_SECONDS = 30;
+const DIGITS = 6;
+const BASE32 = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+/** The Keychain service name, also how the hooks recognize commands that read it. */
+export const TOTP_KEYCHAIN_SERVICE = "adtl-totp";
+
+export function base32Encode(bytes: Buffer): string {
+  let bits = 0;
+  let value = 0;
+  let out = "";
+  for (const b of bytes) {
+    value = (value << 8) | b;
+    bits += 8;
+    while (bits >= 5) {
+      out += BASE32[(value >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+    value &= (1 << bits) - 1;
+  }
+  return bits > 0 ? out + BASE32[(value << (5 - bits)) & 31] : out;
+}
+
+export function base32Decode(text: string): Buffer {
+  let bits = 0;
+  let value = 0;
+  const out: number[] = [];
+  for (const c of text.toUpperCase().replace(/[\s=]/g, "")) {
+    const i = BASE32.indexOf(c);
+    if (i < 0) throw new Error("The TOTP secret is not valid base32");
+    value = (value << 5) | i;
+    bits += 5;
+    if (bits >= 8) {
+      out.push((value >>> (bits - 8)) & 255);
+      bits -= 8;
+    }
+    value &= (1 << bits) - 1;
+  }
+  return Buffer.from(out);
+}
+
+/** The code for one time step (RFC 4226's HOTP with the step as the counter). */
+export function totpCode(secret: Buffer, step: number, digits = DIGITS): string {
+  const counter = Buffer.alloc(8);
+  counter.writeBigUInt64BE(BigInt(step));
+  const mac = createHmac("sha1", secret).update(counter).digest();
+  const offset = mac[mac.length - 1]! & 15;
+  const n = mac.readUInt32BE(offset) & 0x7fffffff;
+  return String(n % 10 ** digits).padStart(digits, "0");
+}
+
+export function totpStep(ms: number): number {
+  return Math.floor(ms / 1000 / STEP_SECONDS);
+}
+
+/** The `otpauth://` URI authenticator apps scan. */
+export function totpUri(secretBase32: string, account: string): string {
+  const label = encodeURIComponent(`ADTL:${account}`);
+  return `otpauth://totp/${label}?secret=${secretBase32}&issuer=ADTL&algorithm=SHA1&digits=${DIGITS}&period=${STEP_SECONDS}`;
+}
+
+export interface TotpState {
+  /** The last time step a code was accepted for. */
+  lastStep(): number;
+  setLastStep(step: number): void;
+}
+
+export class FileTotpState implements TotpState {
+  constructor(private readonly path: string) {}
+
+  lastStep(): number {
+    try {
+      const n = Number(readFileSync(this.path, "utf8").trim());
+      return Number.isSafeInteger(n) ? n : Number.MAX_SAFE_INTEGER; // damaged: accept nothing
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return 0;
+      throw err;
+    }
+  }
+
+  setLastStep(step: number): void {
+    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+    writeFileSync(this.path, String(step), { encoding: "utf8", mode: 0o600 });
+  }
+}
+
+export class TotpVerifier {
+  constructor(
+    private readonly secret: Buffer,
+    private readonly state: TotpState,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  /** True if `code` is right for now, give or take one step, and that step or a later one wasn't used yet. */
+  verify(code: string): boolean {
+    const given = Buffer.from(code.trim());
+    const current = totpStep(this.now());
+    const last = this.state.lastStep();
+    let matched: number | undefined;
+    for (const step of [current - 1, current, current + 1]) {
+      const expected = Buffer.from(totpCode(this.secret, step));
+      if (given.length === expected.length && timingSafeEqual(given, expected) && step > last) matched = step;
+    }
+    if (matched === undefined) return false;
+    this.state.setLastStep(matched);
+    return true;
+  }
+}
+
+export interface TotpSecretStore {
+  /** Where the secret is kept, for messages. */
+  readonly where: string;
+  read(): string | undefined;
+  write(secretBase32: string): void;
+}
+
+/** `ADTL_TOTP_FILE`, or `~/.adtl/totp-secret`. */
+export function totpSecretPath(env: NodeJS.ProcessEnv = process.env): string {
+  return env.ADTL_TOTP_FILE?.trim() || join(homedir(), ".adtl", "totp-secret");
+}
+
+function totpStatePath(env: NodeJS.ProcessEnv): string {
+  return join(dirname(totpSecretPath(env)), "totp-last-step");
+}
+
+class FileSecretStore implements TotpSecretStore {
+  readonly where: string;
+  constructor(private readonly path: string) {
+    this.where = path;
+  }
+  read(): string | undefined {
+    try {
+      return readFileSync(this.path, "utf8").trim() || undefined;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw err;
+    }
+  }
+  write(secretBase32: string): void {
+    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+    writeFileSync(this.path, `${secretBase32}\n`, { encoding: "utf8", mode: 0o600 });
+  }
+}
+
+class KeychainSecretStore implements TotpSecretStore {
+  readonly where = "the macOS Keychain";
+  read(): string | undefined {
+    try {
+      return execFileSync("security", ["find-generic-password", "-s", TOTP_KEYCHAIN_SERVICE, "-w"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined;
+    } catch {
+      return undefined; // no such item
+    }
+  }
+  write(secretBase32: string): void {
+    execFileSync("security", ["add-generic-password", "-U", "-a", "adtl", "-s", TOTP_KEYCHAIN_SERVICE, "-w", secretBase32], { stdio: "ignore" });
+  }
+}
+
+/** The macOS Keychain, unless `ADTL_TOTP_FILE` is set; a file on other systems. */
+export function totpSecretStore(env: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform): TotpSecretStore {
+  return platform === "darwin" && !env.ADTL_TOTP_FILE?.trim() ? new KeychainSecretStore() : new FileSecretStore(totpSecretPath(env));
+}
+
+export function newTotpSecret(): string {
+  return base32Encode(randomBytes(20));
+}
+
+/** The verifier for `gateway.approvals.totp`, or undefined if no secret was set up. */
+export function loadTotpVerifier(env: NodeJS.ProcessEnv = process.env, store: TotpSecretStore = totpSecretStore(env)): TotpVerifier | undefined {
+  const secret = store.read();
+  return secret ? new TotpVerifier(base32Decode(secret), new FileTotpState(totpStatePath(env))) : undefined;
+}

package/src/totpCli.ts

@@ -0,0 +1,52 @@
+/**
+ * `adtl-gateway totp`: set up authenticator-app approvals.
+ *
+ *   adtl-gateway totp setup [--force]
+ *   adtl-gateway totp check <code>
+ */
+import { userInfo } from "node:os";
+import qrcode from "qrcode-terminal";
+import { base32Decode, newTotpSecret, totpCode, totpSecretStore, totpStep, totpUri, type TotpSecretStore } from "./totp.js";
+
+export const TOTP_USAGE = `Usage: adtl-gateway totp setup [--force]
+       adtl-gateway totp check <code>
+
+setup makes a secret, stores it, and shows a QR code to scan into an
+authenticator app. --force replaces an existing secret. check tells you
+whether a code matches right now, without using it up. Then set
+gateway.approvals.totp: true.`;
+
+export interface TotpCommandResult {
+  stdout: string;
+  exitCode: number;
+}
+
+function qr(text: string): Promise<string> {
+  return new Promise((resolve) => qrcode.generate(text, { small: true }, resolve));
+}
+
+export async function runTotpCommand(argv: string[], opts: { store?: TotpSecretStore; now?: () => number } = {}): Promise<TotpCommandResult> {
+  const store = opts.store ?? totpSecretStore();
+  const [cmd, ...rest] = argv;
+  if (cmd === "setup" && rest.every((a) => a === "--force")) {
+    if (store.read() && !rest.includes("--force")) {
+      return { stdout: `A secret is already stored in ${store.where}. Use --force to replace it; codes from the old one stop working.`, exitCode: 1 };
+    }
+    const secret = newTotpSecret();
+    store.write(secret);
+    const uri = totpUri(secret, userInfo().username);
+    return {
+      stdout: `${await qr(uri)}\nScan this with your authenticator app, or enter the key by hand:\n\n  ${secret}\n\nStored in ${store.where}. Clear your terminal afterwards: this screen shows the secret.\nThen set gateway.approvals.totp: true, and test a code with: adtl-gateway totp check <code>`,
+      exitCode: 0,
+    };
+  }
+  if (cmd === "check" && rest.length === 1) {
+    const secret = store.read();
+    if (!secret) return { stdout: "No secret yet: run adtl-gateway totp setup", exitCode: 1 };
+    const key = base32Decode(secret);
+    const step = totpStep((opts.now ?? Date.now)());
+    const ok = [step - 1, step, step + 1].some((s) => totpCode(key, s) === rest[0]);
+    return { stdout: ok ? "The code matches." : "The code doesn't match. Check the time on your phone.", exitCode: ok ? 0 : 1 };
+  }
+  return { stdout: TOTP_USAGE, exitCode: cmd === undefined || cmd === "--help" || cmd === "-h" ? 0 : 1 };
+}

package/src/types/qrcode-terminal.d.ts

@@ -0,0 +1,4 @@
+declare module "qrcode-terminal" {
+  const qrcode: { generate(text: string, opts: { small: boolean }, callback: (qr: string) => void): void };
+  export default qrcode;
+}