@adtl/gateway 0.8.0 → 0.8.2

package/dist/totp.js

@@ -0,0 +1,176 @@
+/**
+ * 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) {
+    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) {
+    let bits = 0;
+    let value = 0;
+    const out = [];
+    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, step, digits = DIGITS) {
+    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) {
+    return Math.floor(ms / 1000 / STEP_SECONDS);
+}
+/** The `otpauth://` URI authenticator apps scan. */
+export function totpUri(secretBase32, account) {
+    const label = encodeURIComponent(`ADTL:${account}`);
+    return `otpauth://totp/${label}?secret=${secretBase32}&issuer=ADTL&algorithm=SHA1&digits=${DIGITS}&period=${STEP_SECONDS}`;
+}
+export class FileTotpState {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    lastStep() {
+        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.code === "ENOENT")
+                return 0;
+            throw err;
+        }
+    }
+    setLastStep(step) {
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+        writeFileSync(this.path, String(step), { encoding: "utf8", mode: 0o600 });
+    }
+}
+export class TotpVerifier {
+    secret;
+    state;
+    now;
+    constructor(secret, state, now = Date.now) {
+        this.secret = secret;
+        this.state = state;
+        this.now = 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) {
+        const given = Buffer.from(code.trim());
+        const current = totpStep(this.now());
+        const last = this.state.lastStep();
+        let matched;
+        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;
+    }
+}
+/** `ADTL_TOTP_FILE`, or `~/.adtl/totp-secret`. */
+export function totpSecretPath(env = process.env) {
+    return env.ADTL_TOTP_FILE?.trim() || join(homedir(), ".adtl", "totp-secret");
+}
+function totpStatePath(env) {
+    return join(dirname(totpSecretPath(env)), "totp-last-step");
+}
+class FileSecretStore {
+    path;
+    where;
+    constructor(path) {
+        this.path = path;
+        this.where = path;
+    }
+    read() {
+        try {
+            return readFileSync(this.path, "utf8").trim() || undefined;
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return undefined;
+            throw err;
+        }
+    }
+    write(secretBase32) {
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+        writeFileSync(this.path, `${secretBase32}\n`, { encoding: "utf8", mode: 0o600 });
+    }
+}
+class KeychainSecretStore {
+    where = "the macOS Keychain";
+    read() {
+        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) {
+        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 = process.env, platform = process.platform) {
+    return platform === "darwin" && !env.ADTL_TOTP_FILE?.trim() ? new KeychainSecretStore() : new FileSecretStore(totpSecretPath(env));
+}
+export function newTotpSecret() {
+    return base32Encode(randomBytes(20));
+}
+/** The verifier for `gateway.approvals.totp`, or undefined if no secret was set up. */
+export function loadTotpVerifier(env = process.env, store = totpSecretStore(env)) {
+    const secret = store.read();
+    return secret ? new TotpVerifier(base32Decode(secret), new FileTotpState(totpStatePath(env))) : undefined;
+}
+//# sourceMappingURL=totp.js.map

package/dist/totp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp.js","sourceRoot":"","sources":["../src/totp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,MAAM,GAAG,CAAC,CAAC;AACjB,MAAM,MAAM,GAAG,kCAAkC,CAAC;AAElD,qFAAqF;AACrF,MAAM,CAAC,MAAM,qBAAqB,GAAG,WAAW,CAAC;AAEjD,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,KAAK,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,IAAI,CAAC,CAAC;QACV,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC;YACjB,GAAG,IAAI,MAAM,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;YAC3C,IAAI,IAAI,CAAC,CAAC;QACZ,CAAC;QACD,KAAK,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,MAAM,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,CAAC;QACzD,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;QAClE,KAAK,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,IAAI,CAAC,CAAC;QACV,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;YACd,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;YACvC,IAAI,IAAI,CAAC,CAAC;QACZ,CAAC;QACD,KAAK,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,QAAQ,CAAC,MAAc,EAAE,IAAY,EAAE,MAAM,GAAG,MAAM;IACpE,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAChC,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACvC,MAAM,GAAG,GAAG,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC;IAChE,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAE,GAAG,EAAE,CAAC;IACzC,MAAM,CAAC,GAAG,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC;IAChD,OAAO,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,EAAU;IACjC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,GAAG,YAAY,CAAC,CAAC;AAC9C,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,OAAO,CAAC,YAAoB,EAAE,OAAe;IAC3D,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAC;IACpD,OAAO,kBAAkB,KAAK,WAAW,YAAY,sCAAsC,MAAM,WAAW,YAAY,EAAE,CAAC;AAC7H,CAAC;AAQD,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,IAAY;QAAZ,SAAI,GAAJ,IAAI,CAAQ;IAAG,CAAC;IAE7C,QAAQ;QACN,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YACzD,OAAO,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,0BAA0B;QAC1F,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,CAAC,CAAC;YAC/D,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,WAAW,CAAC,IAAY;QACtB,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAChE,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5E,CAAC;CACF;AAED,MAAM,OAAO,YAAY;IAEJ;IACA;IACA;IAHnB,YACmB,MAAc,EACd,KAAgB,EAChB,MAAoB,IAAI,CAAC,GAAG;QAF5B,WAAM,GAAN,MAAM,CAAQ;QACd,UAAK,GAAL,KAAK,CAAW;QAChB,QAAG,GAAH,GAAG,CAAyB;IAC5C,CAAC;IAEJ,4GAA4G;IAC5G,MAAM,CAAC,IAAY;QACjB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnC,IAAI,OAA2B,CAAC;QAChC,KAAK,MAAM,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC;YACvD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;YAC1D,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,IAAI,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,IAAI,GAAG,IAAI;gBAAE,OAAO,GAAG,IAAI,CAAC;QAC1G,CAAC;QACD,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AASD,kDAAkD;AAClD,MAAM,UAAU,cAAc,CAAC,MAAyB,OAAO,CAAC,GAAG;IACjE,OAAO,GAAG,CAAC,cAAc,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;AAC/E,CAAC;AAED,SAAS,aAAa,CAAC,GAAsB;IAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC;AAC9D,CAAC;AAED,MAAM,eAAe;IAEU;IADpB,KAAK,CAAS;IACvB,YAA6B,IAAY;QAAZ,SAAI,GAAJ,IAAI,CAAQ;QACvC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IACD,IAAI;QACF,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;QAC7D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,SAAS,CAAC;YACvE,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IACD,KAAK,CAAC,YAAoB;QACxB,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAChE,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,YAAY,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACnF,CAAC;CACF;AAED,MAAM,mBAAmB;IACd,KAAK,GAAG,oBAAoB,CAAC;IACtC,IAAI;QACF,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,UAAU,EAAE,CAAC,uBAAuB,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;QAC/K,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC,CAAC,eAAe;QACnC,CAAC;IACH,CAAC;IACD,KAAK,CAAC,YAAoB;QACxB,YAAY,CAAC,UAAU,EAAE,CAAC,sBAAsB,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,YAAY,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC/I,CAAC;CACF;AAED,mFAAmF;AACnF,MAAM,UAAU,eAAe,CAAC,MAAyB,OAAO,CAAC,GAAG,EAAE,WAA4B,OAAO,CAAC,QAAQ;IAChH,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,mBAAmB,EAAE,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;AACrI,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,YAAY,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;AACvC,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,gBAAgB,CAAC,MAAyB,OAAO,CAAC,GAAG,EAAE,QAAyB,eAAe,CAAC,GAAG,CAAC;IAClH,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC5B,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,IAAI,aAAa,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5G,CAAC"}

package/dist/totpCli.d.ts

@@ -0,0 +1,11 @@
+import { type TotpSecretStore } from "./totp.js";
+export declare const TOTP_USAGE = "Usage: adtl-gateway totp setup [--force]\n       adtl-gateway totp check <code>\n\nsetup makes a secret, stores it, and shows a QR code to scan into an\nauthenticator app. --force replaces an existing secret. check tells you\nwhether a code matches right now, without using it up. Then set\ngateway.approvals.totp: true.";
+export interface TotpCommandResult {
+    stdout: string;
+    exitCode: number;
+}
+export declare function runTotpCommand(argv: string[], opts?: {
+    store?: TotpSecretStore;
+    now?: () => number;
+}): Promise<TotpCommandResult>;
+//# sourceMappingURL=totpCli.d.ts.map

package/dist/totpCli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"totpCli.d.ts","sourceRoot":"","sources":["../src/totpCli.ts"],"names":[],"mappings":"AAQA,OAAO,EAA6E,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5H,eAAO,MAAM,UAAU,qUAMO,CAAC;AAE/B,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,eAAe,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAwB3I"}

package/dist/totpCli.js

@@ -0,0 +1,46 @@
+/**
+ * `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 } 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.`;
+function qr(text) {
+    return new Promise((resolve) => qrcode.generate(text, { small: true }, resolve));
+}
+export async function runTotpCommand(argv, opts = {}) {
+    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 };
+}
+//# sourceMappingURL=totpCli.js.map

package/dist/totpCli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"totpCli.js","sourceRoot":"","sources":["../src/totpCli.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,MAAM,MAAM,iBAAiB,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,OAAO,EAAwB,MAAM,WAAW,CAAC;AAE5H,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;8BAMI,CAAC;AAO/B,SAAS,EAAE,CAAC,IAAY;IACtB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;AACnF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAc,EAAE,OAAwD,EAAE;IAC7G,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,eAAe,EAAE,CAAC;IAC9C,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAC5B,IAAI,GAAG,KAAK,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,EAAE,CAAC;QAC1D,IAAI,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9C,OAAO,EAAE,MAAM,EAAE,iCAAiC,KAAK,CAAC,KAAK,mEAAmE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QAClJ,CAAC;QACD,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;QAC/B,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACpB,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC;QACjD,OAAO;YACL,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,2EAA2E,MAAM,iBAAiB,KAAK,CAAC,KAAK,8JAA8J;YACnS,QAAQ,EAAE,CAAC;SACZ,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,KAAK,OAAO,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,MAAM,EAAE,4CAA4C,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QAC1F,MAAM,GAAG,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChD,MAAM,EAAE,GAAG,CAAC,IAAI,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAChF,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,uDAAuD,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9H,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACzG,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adtl/gateway",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Experimental: MCP gateway that labels every tool result and blocks risky tool calls using ADTL trust labels",
   "keywords": [
     "mcp",
@@ -47,13 +47,14 @@
     "url": "https://github.com/probita-ai/adtl/issues"
   },
   "dependencies": {
-    "@adtl/interceptors": "0.8.0",
-    "@adtl/labels": "0.8.0",
-    "@adtl/ledger": "0.8.0",
-    "@modelcontextprotocol/sdk": "1.31.0",
-    "nodemailer": "10.0.12",
+    "@adtl/interceptors": "0.8.2",
+    "@adtl/labels": "0.8.2",
+    "@adtl/ledger": "0.8.2",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "nodemailer": "10.3.1",
+    "qrcode-terminal": "0.12.0",
     "yaml": "2.9.1",
-    "zod": "3.25.76"
+    "zod": "4.6.7"
   },
   "peerDependencies": {
     "@cedar-policy/cedar-wasm": "^4.13.0"

package/playground/server.mjs

@@ -23,6 +23,7 @@ import {
   InterceptorInvoker,
   JsonlAuditLog,
   bundledInterceptorsCli,
+  checkOverrides,
   connectUpstream,
   loadGatewayConfig,
 } from "../dist/index.js";
@@ -84,7 +85,11 @@ async function close(s) {
 
 /** Fresh servers, ledger, audit log and session. Throws without side effects if the config is invalid. */
 async function build({ adtl, config }) {
-  if (adtl) parseConfigText(config); // a broken adtl.yaml fails here, before anything starts
+  // A broken adtl.yaml fails here, before anything starts.
+  const gateway = adtl ? parseConfigText(config).gateway : undefined;
+  // The playground supplies its own gateway section; only overrides carry over. Interceptor
+  // servers don't: a web page must not be able to start commands.
+  const overrides = gateway?.interceptorOverrides;
   const work = mkdtempSync(join(tmpdir(), "adtl-playground-"));
   const posted = join(work, "posted.jsonl");
   const s = { adtl, config, work, posted, audit: join(work, "audit.jsonl"), timeline: [], sessionNo: 1, closers: [], auditSeen: 0 };
@@ -95,7 +100,9 @@ async function build({ adtl, config }) {
         path,
         config.replace(/^(ledger|gateway):[\s\S]*$/m, "") +
           `\nledger:\n  path: ${JSON.stringify(join(work, "ledger.db"))}\n` +
-          `gateway:\n  audit: ${JSON.stringify(s.audit)}\n  upstreams:\n` +
+          `gateway:\n  audit: ${JSON.stringify(s.audit)}\n` +
+          (overrides ? `  interceptorOverrides: ${JSON.stringify(overrides)}\n` : "") +
+          `  upstreams:\n` +
           `    github:\n      command: ${JSON.stringify(process.execPath)}\n      args: [${JSON.stringify(FAKE_GITHUB)}]\n` +
           `      env: { FAKE_GITHUB_POSTED: ${JSON.stringify(posted)} }\n` +
           `    memory:\n      command: ${JSON.stringify(process.execPath)}\n      args: [${JSON.stringify(FAKE_MEMORY)}]\n`,
@@ -105,7 +112,10 @@ async function build({ adtl, config }) {
         command: process.execPath, args: [bundledInterceptorsCli(), "--config", path], env: {},
       }, work);
       s.closers.push(interceptors);
-      s.invoker = new InterceptorInvoker(await InterceptorInvoker.discover(interceptors), loaded.gateway.interceptorTimeoutMs);
+      const bound = await InterceptorInvoker.discover(interceptors);
+      const problems = checkOverrides(bound.map((b) => b.definition), loaded.gateway.interceptorOverrides);
+      if (problems.length) throw new Error(`gateway.interceptorOverrides: ${problems.join("; ")}`);
+      s.invoker = new InterceptorInvoker(bound, loaded.gateway.interceptorTimeoutMs, undefined, loaded.gateway.interceptorOverrides);
       s.upstreams = new Map();
       for (const [id, u] of Object.entries(loaded.gateway.upstreams)) {
         const c = await connectUpstream(id, u, work);

package/src/cli.ts

@@ -11,6 +11,7 @@
  *   adtl-gateway receipt list|<session>|verify <file>
  *   adtl-gateway key
  *   adtl-gateway playground [--port 4317] [--no-open]
+ *   adtl-gateway totp setup [--force]
  *
  * Point your MCP client (e.g. Claude Code's .mcp.json) at this command.
  * Logs go to stderr; stdout carries MCP JSON-RPC only.
@@ -21,6 +22,7 @@ import { GATEWAY_VERSION } from "./gateway.js";
 import { runAuditCommand } from "./auditCli.js";
 import { runKeyCommand, runReceiptCommand } from "./receiptCli.js";
 import { runPlayground } from "./playgroundCli.js";
+import { runTotpCommand } from "./totpCli.js";
 import { runHook } from "./hooks/run.js";
 import { runLedgerCommand } from "./ledgerCli.js";
 import { runInit, type InitResult } from "./init/run.js";
@@ -34,6 +36,7 @@ const USAGE = `Usage: adtl-gateway --config <adtl.yaml> [--audit]
        adtl-gateway receipt list|<session>|verify <file>  (see: adtl-gateway receipt --help)
        adtl-gateway key
        adtl-gateway playground [--port <n>] [--no-open]  (a local web UI with fake servers)
+       adtl-gateway totp setup [--force]  (authenticator-app approvals; see: adtl-gateway totp --help)
 
 Runs an MCP server over stdio that forwards tool calls to the upstream
 servers in the config, checking and labeling each call with ADTL.
@@ -113,6 +116,12 @@ async function main(): Promise<void> {
     return;
   }
   if (process.argv[2] === "playground") return runPlayground(process.argv.slice(3));
+  if (process.argv[2] === "totp") {
+    const r = await runTotpCommand(process.argv.slice(3));
+    console.log(r.stdout);
+    process.exitCode = r.exitCode;
+    return;
+  }
   if (process.argv[2] === "receipt" || process.argv[2] === "key") {
     const r = process.argv[2] === "key" ? await runKeyCommand() : await runReceiptCommand(process.argv.slice(3));
     console.log(r.stdout);
@@ -205,7 +214,7 @@ async function init(path: string, write: boolean, from?: string): Promise<void>
 }
 
 main().catch((err: unknown) => {
-  const known = err instanceof GatewayConfigError || err instanceof EnvExpansionError || ["ledger", "audit", "receipt", "key", "playground"].includes(process.argv[2] ?? "");
+  const known = err instanceof GatewayConfigError || err instanceof EnvExpansionError || ["ledger", "audit", "receipt", "key", "playground", "totp"].includes(process.argv[2] ?? "");
   console.error(known ? `[adtl-gateway] ${(err as Error).message}` : err);
   // For Claude Code hooks only exit code 2 stops the call; any other code lets it run.
   process.exit(process.argv[2] === "hook" ? 2 : 1);

package/src/config.ts

@@ -21,6 +21,7 @@
  *       maintainers: { members: [alice], tools: ["github.*"] }
  *       readers:     { members: ["*"],   tools: ["github.read_*", "github.get_*"] }
  *     cedar: { policies: ./adtl.cedar }  # optional: attribute-based rules (see cedar.ts)
+ *     openfga: { url: http://localhost:8080, storeId: "${FGA_STORE_ID}" }  # optional: relationship rules (see openfga.ts)
  *     approvals:                         # optional: make "ask" really ask
  *       timeoutSeconds: 50
  *       ntfy: { topic: "${ADTL_NTFY_TOPIC}" }
@@ -31,7 +32,7 @@
  *         from: adtl@example.com
  *         to: you@example.com
  *
- * `${VAR}` in command, args, env, cwd, url, headers, approval settings and principal.id is
+ * `${VAR}` in command, args, env, cwd, url, headers, approval settings, openfga settings and principal.id is
  * replaced from the gateway's environment. A missing variable is a config error,
  * unless a default is given: `${VAR:-default}`.
  */
@@ -44,7 +45,7 @@ export const StdioUpstreamSchema = z
   .object({
     command: z.string().min(1),
     args: z.array(z.string()).default([]),
-    env: z.record(z.string()).default({}),
+    env: z.record(z.string(), z.string()).default({}),
     cwd: z.string().optional(),
   })
   .strict();
@@ -52,7 +53,7 @@ export const StdioUpstreamSchema = z
 export const HttpUpstreamSchema = z
   .object({
     url: z.string().min(1),
-    headers: z.record(z.string()).default({}),
+    headers: z.record(z.string(), z.string()).default({}),
   })
   .strict();
 
@@ -104,11 +105,16 @@ export const ApprovalsConfigSchema = z
      * default: a client that accepts elicitations by itself would approve calls.
      */
     elicitation: z.boolean().default(false),
+    /**
+     * Ask in the MCP client for a code from an authenticator app (`adtl-gateway
+     * totp setup`), instead of Allow or Deny. Wins over `elicitation`.
+     */
+    totp: z.boolean().default(false),
     /**
      * Each approver's own channel, by principal id. Policy rules with
      * `approvers: [role]` ask only these people, so the answer names who approved.
      */
-    approvers: z.record(z.object({ ntfy: NtfyConfigSchema }).strict()).optional(),
+    approvers: z.record(z.string(), z.object({ ntfy: NtfyConfigSchema }).strict()).optional(),
   })
   .strict();
 export type ApprovalsConfig = z.infer<typeof ApprovalsConfigSchema>;
@@ -123,7 +129,7 @@ export const PrincipalConfigSchema = z
   .object({
     type: z.enum(["user", "service"]).default("user"),
     id: z.string().min(1),
-    claims: z.record(z.unknown()).optional(),
+    claims: z.record(z.string(), z.unknown()).optional(),
   })
   .strict();
 export type PrincipalConfig = z.infer<typeof PrincipalConfigSchema>;
@@ -166,6 +172,31 @@ export const CedarConfigSchema = z
   .strict();
 export type CedarConfig = z.infer<typeof CedarConfigSchema>;
 
+export const OpenFgaConfigSchema = z
+  .object({
+    url: z.string().min(1),
+    storeId: z.string().min(1),
+    modelId: z.string().min(1).optional(),
+    token: z.string().min(1).optional(),
+    /** Relation checked when a tool has no rule of its own. */
+    relation: z.string().min(1).default("can_use"),
+    timeoutMs: z.number().int().positive().max(60_000).default(2000),
+    /** Per-tool rules, keyed `server.tool`. `object` is `type:id`, and `{argument}` is taken from the call. */
+    tools: z
+      .record(
+        z.string(),
+        z
+          .object({
+            relation: z.string().min(1).optional(),
+            object: z.string().regex(/^[^:\s]+:.+$/, 'Use "type:id", e.g. "repo:{owner}/{repo}"').optional(),
+          })
+          .strict(),
+      )
+      .default({}),
+  })
+  .strict();
+export type OpenFgaConfig = z.infer<typeof OpenFgaConfigSchema>;
+
 const PhaseSchema = z.enum(["request", "response"]);
 
 /** SEP-2624 InterceptorOverrides, set by the gateway owner for one interceptor. */
@@ -187,7 +218,7 @@ export const InterceptorOverridesSchema = z
 export const GatewayConfigSchema = z
   .object({
     upstreams: z
-      .record(UpstreamSchema)
+      .record(z.string(), UpstreamSchema)
       .refine((u) => Object.keys(u).length > 0, "At least one upstream server is required")
       .refine((u) => Object.keys(u).every((id) => UPSTREAM_ID.test(id)), {
         message: "Upstream ids may only contain letters, digits and '-' (they prefix tool names as <id>__<tool>)",
@@ -196,7 +227,7 @@ export const GatewayConfigSchema = z
     interceptors: StdioUpstreamSchema.optional(),
     /** More interceptor servers (stdio or Streamable HTTP) whose interceptors run beside ADTL's. */
     interceptorServers: z
-      .record(UpstreamSchema)
+      .record(z.string(), UpstreamSchema)
       .refine((u) => Object.keys(u).every((id) => UPSTREAM_ID.test(id)), {
         message: "Interceptor server ids may only contain letters, digits and '-'",
       })
@@ -213,16 +244,18 @@ export const GatewayConfigSchema = z
     /** Timeout for each interceptor invocation, in milliseconds. */
     interceptorTimeoutMs: z.number().int().positive().default(5000),
     /** Per-interceptor overrides of failOpen, priorityHint, mode, timeoutMs and hooks, by interceptor name. */
-    interceptorOverrides: z.record(InterceptorOverridesSchema).default({}),
+    interceptorOverrides: z.record(z.string(), InterceptorOverridesSchema).default({}),
     /** Who runs this gateway. Passed to the authorizer and the interceptors. Default: anonymous. */
     principal: PrincipalConfigSchema.optional(),
     /** Role-based authorization: when present, a call no role grants is denied. */
     roles: z
-      .record(RoleSchema)
+      .record(z.string(), RoleSchema)
       .refine((r) => Object.keys(r).length > 0, "roles: needs at least one role (remove it to allow everyone)")
       .optional(),
     /** Cedar authorization. With roles as well, both must allow. */
     cedar: CedarConfigSchema.optional(),
+    /** OpenFGA authorization. With roles or cedar as well, all must allow. */
+    openfga: OpenFgaConfigSchema.optional(),
   })
   .strict();
 export type GatewayConfig = z.infer<typeof GatewayConfigSchema>;

package/src/elicitation.ts

@@ -9,10 +9,15 @@
  * when `gateway.approvals.elicitation` is on and the client declares the
  * elicitation capability, and never for rules with named approvers: the
  * client can't say who answered.
+ *
+ * With `gateway.approvals.totp`, the prompt asks for a code from the person's
+ * authenticator app instead of Allow or Deny, so a client that accepts
+ * prompts by itself can't approve anything. Three wrong codes count as Deny.
  */
 import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { ElicitResultSchema } from "@modelcontextprotocol/sdk/types.js";
 import type { AnswerFn, ApprovalEvent, ApprovalRequest, Notifier } from "./approvals.js";
+import type { TotpVerifier } from "./totp.js";
 
 interface Listening {
   answer: AnswerFn;
@@ -29,11 +34,22 @@ function message(request: ApprovalRequest): string {
   return `ADTL: allow ${request.server}.${request.tool}?\n\n${request.reason}\n\nRule: ${rule}. Allow runs this one call; Deny or no answer stops it.`;
 }
 
+function codeMessage(request: ApprovalRequest, wrong: number): string {
+  const rule = request.matched.join(", ") || "default";
+  const again = wrong > 0 ? "That code was not right. " : "";
+  return `ADTL: allow ${request.server}.${request.tool}?\n\n${request.reason}\n\nRule: ${rule}. ${again}Enter the code from your authenticator app to run this one call; decline or no answer stops it.`;
+}
+
+const MAX_CODE_ATTEMPTS = 3;
+
 export class ElicitationChannel implements Notifier {
   readonly name = "elicitation";
   private readonly listening = new Map<string, Listening>();
 
-  constructor(private readonly server: Server) {}
+  constructor(
+    private readonly server: Server,
+    private readonly totp?: TotpVerifier,
+  ) {}
 
   async listen(request: ApprovalRequest, answer: AnswerFn, signal: AbortSignal): Promise<void> {
     this.listening.set(request.id, { answer, signal });
@@ -46,22 +62,24 @@ export class ElicitationChannel implements Notifier {
     const l = this.listening.get(event.request.id);
     if (!l) throw new Error("not listening for this request");
     // A plain request, not Server.elicitInput(): clients that declare only `elicitation: {}` support forms too.
-    const result = await this.server.request(
-      {
-        method: "elicitation/create",
-        params: {
-          message: message(event.request),
-          requestedSchema: {
-            type: "object",
-            properties: {
-              decision: { type: "string", title: "Decision", enum: ["allow", "deny"], description: "allow runs this one call; deny stops it" },
-            },
-            required: ["decision"],
-          },
-        },
-      },
-      ElicitResultSchema,
-      { signal: l.signal, timeout: Math.max(1, event.request.expiresAt.getTime() - Date.now()) },
+    const ask = (text: string, properties: Record<string, unknown>, required: string) =>
+      this.server.request(
+        { method: "elicitation/create", params: { message: text, requestedSchema: { type: "object", properties, required: [required] } } } as never,
+        ElicitResultSchema,
+        { signal: l.signal, timeout: Math.max(1, event.request.expiresAt.getTime() - Date.now()) },
+      );
+    if (this.totp) {
+      for (let wrong = 0; wrong < MAX_CODE_ATTEMPTS; wrong++) {
+        const r = await ask(codeMessage(event.request, wrong), { code: { type: "string", title: "Code", description: "6 digits from your authenticator app" } }, "code");
+        if (r.action !== "accept") break;
+        if (this.totp.verify(String(r.content?.code ?? ""))) return void l.answer(event.tokens.allow);
+      }
+      return void l.answer(event.tokens.deny);
+    }
+    const result = await ask(
+      message(event.request),
+      { decision: { type: "string", title: "Decision", enum: ["allow", "deny"], description: "allow runs this one call; deny stops it" } },
+      "decision",
     );
     const allow = result.action === "accept" && result.content?.decision === "allow";
     l.answer(allow ? event.tokens.allow : event.tokens.deny);

package/src/gateway.ts

@@ -57,12 +57,13 @@ import type { InvocationContext } from "@adtl/interceptors";
 import { callBindingHash } from "@adtl/labels";
 import type { ApprovalBroker, ApprovalResult } from "./approvals.js";
 import { ElicitationChannel, supportsElicitation } from "./elicitation.js";
+import type { TotpVerifier } from "./totp.js";
 import type { AuditEntry, AuditSink } from "./audit.js";
 import { authorize, type AuthorizationRequest, type Authorizer, type Denial, type Principal } from "./authorizer.js";
 import { TOOL_SEPARATOR } from "./config.js";
 import type { Blocked, InterceptorInvoker, InterceptorRun, PhaseOutcome } from "./invoker.js";
 
-export const GATEWAY_VERSION = "0.8.0";
+export const GATEWAY_VERSION = "0.8.2";
 
 /** `_meta` key on gateway-generated error results describing why a call was stopped. */
 export const GATEWAY_DECISION_KEY = "adtl/gateway";
@@ -115,6 +116,8 @@ export interface AdtlGatewayOptions {
   approverRoles?: Map<string, string[]>;
   /** Also ask for approval in the MCP client, when it supports elicitation. */
   elicitApprovals?: boolean;
+  /** Ask for a code from an authenticator app in the MCP client, instead of Allow or Deny. */
+  totp?: TotpVerifier;
   /** The (sub-)agent this gateway serves, recorded on every audit entry. */
   agent?: { id: string; type?: string };
 }
@@ -179,6 +182,7 @@ export class AdtlGateway {
   private readonly agent: { agent: { id: string; type?: string } } | Record<string, never>;
   private readonly approverRoles: Map<string, string[]>;
   private readonly elicitApprovals: boolean;
+  private readonly totp: TotpVerifier | undefined;
   /** The server the agent is connected to, for elicitation. */
   private server: Server | undefined;
   private routes = new Map<string, Route>();
@@ -199,6 +203,7 @@ export class AdtlGateway {
     this.agent = opts.agent ? { agent: opts.agent } : {};
     this.approverRoles = opts.approverRoles ?? new Map();
     this.elicitApprovals = opts.elicitApprovals === true;
+    this.totp = opts.totp;
   }
 
   /** Ask each authorizer in turn. Returns the first denial; in audit mode the caller logs it and carries on. */
@@ -573,7 +578,7 @@ export class AdtlGateway {
       const lists = Array.isArray(policy.approvers) ? (policy.approvers as string[][]) : undefined;
       const approvers = lists ? eligibleApprovers(lists, this.approverRoles) : undefined;
       // The client's own prompt, if enabled and supported; never for named approvers (it can't say who answered).
-      const elicit = this.elicitApprovals && !approvers && this.server && supportsElicitation(this.server) ? [new ElicitationChannel(this.server)] : [];
+      const elicit = (this.elicitApprovals || this.totp) && !approvers && this.server && supportsElicitation(this.server) ? [new ElicitationChannel(this.server, this.totp)] : [];
       if (b.decision === "ask" && this.approvals && (this.approvals.canApprove || elicit.length > 0) && typeof hash === "string") {
         this.log.info(`ask ${name}: waiting for approval${approvers ? ` from ${approvers.join(", ") || "nobody"}` : ""} (${b.reason})`);
         approval = await this.waitForApproval(opts, () =>