borgmcp 0.9.56 → 0.9.58

package/dist/config.js

@@ -1,79 +1,117 @@
 /**
- * Secure token storage using OS keychain.
+ * Secure token storage.
  *
- * Uses @napi-rs/keyring (NAPI-RS binding over the Rust `keyring-rs`
- * crate) for cross-platform credential storage:
- *   - macOS: Keychain Services
- *   - Windows: Credential Vault (Credential Manager)
- *   - Linux: Secret Service (libsecret / gnome-keyring)
+ * The public API (storeIdToken / getIdToken / getRefreshToken / clearTokens /
+ * isAuthenticated) is unchanged; what changed in gh#557 is what sits beneath
+ * it. Three storage paths, in precedence order:
  *
- * Migrated from `keytar` in 0.7.2 (gh#22). Same encryption-at-rest
- * shape as keytar (delegates to the platform's native keychain
- * service); eliminates the maintenance-orphaned keytar + prebuild-
- * install dependency chain.
+ *   1. Caller-managed (read-only): if BORG_TOKEN / BORG_TOKEN_FILE supplies an
+ *      id_token, it's served verbatim — no keychain, no expiry check, no
+ *      refresh_token. The caller owns the token's lifecycle (CI, containers,
+ *      `borg --token-file`).
+ *   2. OS keychain (default): @napi-rs/keyring — real platform at-rest
+ *      encryption (macOS Keychain / Windows Credential Vault / libsecret).
+ *   3. Encrypted file (fallback): ~/.borg/credentials, AES-256-GCM under a
+ *      machine-derived key, 0600. Engages only when no keychain is available
+ *      (headless Linux without Secret Service). Obfuscation-grade — see
+ *      token-crypto.ts.
  *
- * `AsyncEntry` is used (over the sync `Entry` class) so the public
- * API surface — every function below is `async` — stays identical
- * to the pre-migration shape. No call sites needed to change.
+ * The persistent backend (2 or 3) is selected once per process and memoized.
+ * BORG_TOKEN_STORE=keychain|file forces the choice and skips the probe.
  */
-import { AsyncEntry } from '@napi-rs/keyring';
-const SERVICE_NAME = 'borg-mcp';
+import os from 'os';
+import path from 'path';
+import { promises as fsp } from 'fs';
+import { isKeyringAvailable } from './auth-env.js';
+import { deriveMachineKey } from './token-crypto.js';
+import { makeKeychainBackend, makeEncryptedFileBackend, selectTokenBackend, readCallerManagedIdToken, } from './token-store.js';
 const ID_TOKEN_ACCOUNT = 'google-id-token';
 const REFRESH_TOKEN_ACCOUNT = 'google-refresh-token';
 const TOKEN_EXPIRY_ACCOUNT = 'token-expiry';
-/**
- * Build an AsyncEntry bound to the borg-mcp service + given account.
- * One per call site rather than module-level singletons so the
- * underlying Rust handle isn't held longer than necessary.
- */
-function entry(account) {
-    return new AsyncEntry(SERVICE_NAME, account);
+/** Where the encrypted-file fallback lives when no keychain is available. */
+function credentialsPath() {
+    return path.join(os.homedir(), '.borg', 'credentials');
 }
-/**
- * `@napi-rs/keyring`'s `deletePassword` returns a `NoEntry` error
- * when the entry doesn't exist. `keytar.deletePassword` returned
- * `false` silently in the same case. We preserve the silent-on-
- * missing semantic so `clearTokens()` stays idempotent across
- * repeat calls.
- *
- * Other errors (platform unavailable, ambiguous credential, etc.)
- * propagate — fail-loud is correct for those classes.
- */
-async function deleteIfExists(account) {
-    try {
-        await entry(account).deletePassword();
-    }
-    catch (err) {
-        const msg = String(err?.message ?? '');
-        if (/no entry|not found/i.test(msg))
-            return;
-        throw err;
+/** Production fs adapter for the encrypted-file backend. */
+const nodeFs = {
+    readFile: (filePath) => fsp.readFile(filePath, 'utf8'),
+    writeFile: async (filePath, data, mode) => {
+        // `mode` on writeFile only applies when the file is CREATED; chmod after
+        // guarantees 0600 even when rewriting an existing credentials file.
+        await fsp.writeFile(filePath, data, { mode });
+        await fsp.chmod(filePath, mode);
+    },
+    mkdir: async (dir, mode) => {
+        await fsp.mkdir(dir, { recursive: true, mode });
+    },
+};
+/** Map the user-facing BORG_TOKEN_STORE value to a forced backend, if valid. */
+function parseForcedStore(value) {
+    const v = value?.trim().toLowerCase();
+    if (v === 'keychain')
+        return 'keychain';
+    if (v === 'file' || v === 'encrypted-file')
+        return 'file';
+    return undefined;
+}
+// Memoized persistent-backend selection (one keychain probe per process).
+let backendPromise = null;
+function getBackend() {
+    if (!backendPromise) {
+        backendPromise = selectTokenBackend({
+            keyringAvailable: () => isKeyringAvailable(),
+            makeKeychain: () => makeKeychainBackend(),
+            makeFile: () => makeEncryptedFileBackend({
+                filePath: credentialsPath(),
+                key: deriveMachineKey({
+                    hostname: os.hostname(),
+                    username: os.userInfo().username,
+                    platform: process.platform,
+                }),
+                fs: nodeFs,
+            }),
+            forced: parseForcedStore(process.env.BORG_TOKEN_STORE),
+        });
     }
+    return backendPromise;
+}
+/** Caller-managed id_token (BORG_TOKEN / BORG_TOKEN_FILE), or null. */
+function callerManagedIdToken() {
+    return readCallerManagedIdToken({
+        env: process.env,
+        readFile: (filePath) => fsp.readFile(filePath, 'utf8'),
+    });
 }
 /**
- * Store Google OAuth ID token securely in the OS keychain.
+ * Store Google OAuth ID token securely in the selected backend.
  */
 export async function storeIdToken(idToken, expiresAt) {
-    await entry(ID_TOKEN_ACCOUNT).setPassword(idToken);
-    await entry(TOKEN_EXPIRY_ACCOUNT).setPassword(expiresAt.toString());
+    const backend = await getBackend();
+    await backend.set(ID_TOKEN_ACCOUNT, idToken);
+    await backend.set(TOKEN_EXPIRY_ACCOUNT, expiresAt.toString());
 }
 /**
- * Store Google OAuth refresh token securely in the OS keychain.
+ * Store Google OAuth refresh token securely in the selected backend.
  */
 export async function storeRefreshToken(refreshToken) {
-    await entry(REFRESH_TOKEN_ACCOUNT).setPassword(refreshToken);
+    const backend = await getBackend();
+    await backend.set(REFRESH_TOKEN_ACCOUNT, refreshToken);
 }
 /**
- * Retrieve the Google OAuth ID token from the OS keychain.
- * Returns null if not stored or expired (5-minute buffer).
+ * Retrieve the Google OAuth ID token.
  *
- * `getPassword` on a missing entry returns null/undefined depending
- * on platform binding; normalize with `?? null` so the caller
- * contract (`string | null`) is platform-stable.
+ * A caller-managed token (BORG_TOKEN / BORG_TOKEN_FILE) takes precedence and
+ * is returned verbatim — the caller owns its freshness, so the expiry buffer
+ * does not apply. Otherwise reads the persistent backend and returns null if
+ * not stored or within the 5-minute expiry buffer.
  */
 export async function getIdToken() {
-    const token = (await entry(ID_TOKEN_ACCOUNT).getPassword()) ?? null;
-    const expiryStr = (await entry(TOKEN_EXPIRY_ACCOUNT).getPassword()) ?? null;
+    const callerManaged = await callerManagedIdToken();
+    if (callerManaged)
+        return callerManaged;
+    const backend = await getBackend();
+    const token = await backend.get(ID_TOKEN_ACCOUNT);
+    const expiryStr = await backend.get(TOKEN_EXPIRY_ACCOUNT);
     if (!token || !expiryStr) {
         return null;
     }
@@ -86,19 +124,26 @@ export async function getIdToken() {
     return token;
 }
 /**
- * Retrieve the Google OAuth refresh token from the OS keychain.
+ * Retrieve the Google OAuth refresh token. There is no refresh_token in
+ * caller-managed mode (the externally-supplied id_token has no refresh
+ * counterpart), so this returns null whenever a caller-managed token is set.
  */
 export async function getRefreshToken() {
-    return (await entry(REFRESH_TOKEN_ACCOUNT).getPassword()) ?? null;
+    if (await callerManagedIdToken())
+        return null;
+    const backend = await getBackend();
+    return backend.get(REFRESH_TOKEN_ACCOUNT);
 }
 /**
- * Clear all stored tokens from the OS keychain. Idempotent — calling
- * on an already-empty keychain is a no-op (NoEntry errors absorbed).
+ * Clear all stored tokens from the selected backend. Idempotent — clearing
+ * an already-empty store is a no-op. Does not touch caller-managed env vars
+ * (those are the caller's to manage).
  */
 export async function clearTokens() {
-    await deleteIfExists(ID_TOKEN_ACCOUNT);
-    await deleteIfExists(REFRESH_TOKEN_ACCOUNT);
-    await deleteIfExists(TOKEN_EXPIRY_ACCOUNT);
+    const backend = await getBackend();
+    await backend.delete(ID_TOKEN_ACCOUNT);
+    await backend.delete(REFRESH_TOKEN_ACCOUNT);
+    await backend.delete(TOKEN_EXPIRY_ACCOUNT);
 }
 /**
  * Check if user has valid authentication.

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,MAAM,YAAY,GAAG,UAAU,CAAC;AAChC,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAC3C,MAAM,qBAAqB,GAAG,sBAAsB,CAAC;AACrD,MAAM,oBAAoB,GAAG,cAAc,CAAC;AAE5C;;;;GAIG;AACH,SAAS,KAAK,CAAC,OAAe;IAC5B,OAAO,IAAI,UAAU,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;GASG;AACH,KAAK,UAAU,cAAc,CAAC,OAAe;IAC3C,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC,cAAc,EAAE,CAAC;IACxC,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;QACvC,IAAI,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO;QAC5C,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAe,EAAE,SAAiB;IACnE,MAAM,KAAK,CAAC,gBAAgB,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACnD,MAAM,KAAK,CAAC,oBAAoB,CAAC,CAAC,WAAW,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,YAAoB;IAC1D,MAAM,KAAK,CAAC,qBAAqB,CAAC,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,KAAK,GAAG,CAAC,MAAM,KAAK,CAAC,gBAAgB,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,IAAI,CAAC;IACpE,MAAM,SAAS,GAAG,CAAC,MAAM,KAAK,CAAC,oBAAoB,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,IAAI,CAAC;IAE5E,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEvB,oDAAoD;IACpD,IAAI,SAAS,GAAG,GAAG,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,OAAO,CAAC,MAAM,KAAK,CAAC,qBAAqB,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,IAAI,CAAC;AACpE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,cAAc,CAAC,gBAAgB,CAAC,CAAC;IACvC,MAAM,cAAc,CAAC,qBAAqB,CAAC,CAAC;IAC5C,MAAM,cAAc,CAAC,oBAAoB,CAAC,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,MAAM,KAAK,GAAG,MAAM,UAAU,EAAE,CAAC;IACjC,OAAO,KAAK,KAAK,IAAI,CAAC;AACxB,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/device-auth.d.ts

@@ -0,0 +1,75 @@
+/**
+ * gh#557 — Google OAuth 2.0 Device Authorization Grant (RFC 8628).
+ *
+ * The no-browser counterpart to the loopback flow in auth.ts. Instead of
+ * opening a browser and listening on localhost, the device flow:
+ *   1. asks Google for a device_code + a short human-typable user_code,
+ *   2. prints a verification URL + the user_code for the human to open on
+ *      ANY device (their phone, a laptop with a browser), and
+ *   3. polls Google's token endpoint until the human authorizes (or the
+ *      code expires / is denied).
+ *
+ * This module is decoupled from the live Google client: `fetch`, `sleep`,
+ * and `now` are injected, and the client_id / client_secret / endpoints
+ * come from the caller. The live device flow needs a Google OAuth client
+ * of type "TVs & Limited Input devices" (a separate GOOGLE_DEVICE_CLIENT_ID
+ * — Desktop/loopback clients reject /device/code with invalid_client); the
+ * wiring layer supplies those credentials. Everything here is unit-tested
+ * against a mocked Google.
+ */
+/**
+ * Failure of the device-grant flow. `code` is Google's OAuth error code
+ * where one exists (`access_denied`, `expired_token`, `invalid_client`,
+ * `slow_down`, `authorization_pending`) or a synthetic code for
+ * transport/shape failures (`device_code_request_failed`,
+ * `device_token_request_failed`, `malformed_token_response`).
+ *
+ * Token material is never placed in the message — only Google's error
+ * code + description, mirroring RefreshTokenInvalidError's discipline.
+ */
+export declare class DeviceAuthError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+export interface DeviceAuthConfig {
+    clientId: string;
+    /** Limited-Input clients are issued a secret; included in the token poll. */
+    clientSecret?: string;
+    scopes: string[];
+    /** Overridable for tests; defaults to Google's production endpoints. */
+    deviceCodeUrl?: string;
+    tokenUrl?: string;
+}
+export interface DeviceAuthDeps {
+    fetch: typeof fetch;
+    sleep: (ms: number) => Promise<void>;
+    /** Monotonic-ish clock for the local expiry deadline; defaults to Date.now. */
+    now?: () => number;
+}
+export interface DeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    /** Google returns `verification_url` (not the RFC's `verification_uri`). */
+    verification_url: string;
+    expires_in: number;
+    interval: number;
+}
+export interface DeviceTokenResult {
+    id_token: string;
+    refresh_token?: string;
+    expires_in: number;
+}
+/**
+ * Step 1 — request a device_code + user_code from Google.
+ */
+export declare function requestDeviceCode(config: DeviceAuthConfig, deps: DeviceAuthDeps): Promise<DeviceCodeResponse>;
+/**
+ * Step 2 — poll Google's token endpoint until the user authorizes the
+ * device_code, honoring the RFC 8628 poll semantics.
+ *
+ * Sleeps `interval` BEFORE each poll (never hammers immediately). A local
+ * deadline derived from `expires_in` bounds the loop so a code the user
+ * abandons can't poll forever even if Google never returns expired_token.
+ */
+export declare function pollForDeviceToken(deviceCode: DeviceCodeResponse, config: DeviceAuthConfig, deps: DeviceAuthDeps): Promise<DeviceTokenResult>;
+//# sourceMappingURL=device-auth.d.ts.map

package/dist/device-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-auth.d.ts","sourceRoot":"","sources":["../src/device-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH;;;;;;;;;GASG;AACH,qBAAa,eAAgB,SAAQ,KAAK;aACZ,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAI3D;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,kBAAkB,CAAC,CAiD7B;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,kBAAkB,EAC9B,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,iBAAiB,CAAC,CA4E5B"}

package/dist/device-auth.js

@@ -0,0 +1,167 @@
+/**
+ * gh#557 — Google OAuth 2.0 Device Authorization Grant (RFC 8628).
+ *
+ * The no-browser counterpart to the loopback flow in auth.ts. Instead of
+ * opening a browser and listening on localhost, the device flow:
+ *   1. asks Google for a device_code + a short human-typable user_code,
+ *   2. prints a verification URL + the user_code for the human to open on
+ *      ANY device (their phone, a laptop with a browser), and
+ *   3. polls Google's token endpoint until the human authorizes (or the
+ *      code expires / is denied).
+ *
+ * This module is decoupled from the live Google client: `fetch`, `sleep`,
+ * and `now` are injected, and the client_id / client_secret / endpoints
+ * come from the caller. The live device flow needs a Google OAuth client
+ * of type "TVs & Limited Input devices" (a separate GOOGLE_DEVICE_CLIENT_ID
+ * — Desktop/loopback clients reject /device/code with invalid_client); the
+ * wiring layer supplies those credentials. Everything here is unit-tested
+ * against a mocked Google.
+ */
+const GOOGLE_DEVICE_CODE_URL = 'https://oauth2.googleapis.com/device/code';
+const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const DEVICE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code';
+const DEFAULT_INTERVAL_SECONDS = 5;
+const SLOW_DOWN_INCREMENT_SECONDS = 5;
+/**
+ * Failure of the device-grant flow. `code` is Google's OAuth error code
+ * where one exists (`access_denied`, `expired_token`, `invalid_client`,
+ * `slow_down`, `authorization_pending`) or a synthetic code for
+ * transport/shape failures (`device_code_request_failed`,
+ * `device_token_request_failed`, `malformed_token_response`).
+ *
+ * Token material is never placed in the message — only Google's error
+ * code + description, mirroring RefreshTokenInvalidError's discipline.
+ */
+export class DeviceAuthError extends Error {
+    code;
+    constructor(code, message) {
+        super(message ?? code);
+        this.code = code;
+        this.name = 'DeviceAuthError';
+    }
+}
+/**
+ * Step 1 — request a device_code + user_code from Google.
+ */
+export async function requestDeviceCode(config, deps) {
+    const url = config.deviceCodeUrl ?? GOOGLE_DEVICE_CODE_URL;
+    let response;
+    try {
+        response = await deps.fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                client_id: config.clientId,
+                scope: config.scopes.join(' '),
+            }),
+        });
+    }
+    catch (err) {
+        throw new DeviceAuthError('device_code_request_failed', `Could not reach Google device endpoint: ${err?.message ?? 'unknown'}`);
+    }
+    if (!response.ok) {
+        const code = await readErrorCode(response);
+        throw new DeviceAuthError(code ?? 'device_code_request_failed', `Device-code request failed (HTTP ${response.status}${code ? `, ${code}` : ''})`);
+    }
+    let data;
+    try {
+        data = (await response.json());
+    }
+    catch {
+        throw new DeviceAuthError('malformed_token_response', 'Device-code response was not JSON');
+    }
+    if (!data.device_code || !data.user_code || !data.verification_url) {
+        throw new DeviceAuthError('malformed_token_response', 'Device-code response missing device_code/user_code/verification_url');
+    }
+    return {
+        device_code: data.device_code,
+        user_code: data.user_code,
+        verification_url: data.verification_url,
+        expires_in: typeof data.expires_in === 'number' ? data.expires_in : 1800,
+        interval: typeof data.interval === 'number' ? data.interval : DEFAULT_INTERVAL_SECONDS,
+    };
+}
+/**
+ * Step 2 — poll Google's token endpoint until the user authorizes the
+ * device_code, honoring the RFC 8628 poll semantics.
+ *
+ * Sleeps `interval` BEFORE each poll (never hammers immediately). A local
+ * deadline derived from `expires_in` bounds the loop so a code the user
+ * abandons can't poll forever even if Google never returns expired_token.
+ */
+export async function pollForDeviceToken(deviceCode, config, deps) {
+    const tokenUrl = config.tokenUrl ?? GOOGLE_TOKEN_URL;
+    const now = deps.now ?? Date.now;
+    const deadline = now() + deviceCode.expires_in * 1000;
+    let intervalSeconds = deviceCode.interval > 0 ? deviceCode.interval : DEFAULT_INTERVAL_SECONDS;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        if (now() >= deadline) {
+            throw new DeviceAuthError('expired_token', 'Device code expired before the authorization was completed');
+        }
+        await deps.sleep(intervalSeconds * 1000);
+        let response;
+        try {
+            response = await deps.fetch(tokenUrl, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams({
+                    client_id: config.clientId,
+                    ...(config.clientSecret ? { client_secret: config.clientSecret } : {}),
+                    device_code: deviceCode.device_code,
+                    grant_type: DEVICE_GRANT_TYPE,
+                }),
+            });
+        }
+        catch (err) {
+            throw new DeviceAuthError('device_token_request_failed', `Could not reach Google token endpoint: ${err?.message ?? 'unknown'}`);
+        }
+        if (response.ok) {
+            let data;
+            try {
+                data = (await response.json());
+            }
+            catch {
+                throw new DeviceAuthError('malformed_token_response', 'Token response was not JSON');
+            }
+            if (!data.id_token || typeof data.expires_in !== 'number') {
+                throw new DeviceAuthError('malformed_token_response', 'Token response missing id_token or expires_in');
+            }
+            return {
+                id_token: data.id_token,
+                refresh_token: data.refresh_token,
+                expires_in: data.expires_in,
+            };
+        }
+        const code = await readErrorCode(response);
+        switch (code) {
+            case 'authorization_pending':
+                // The user hasn't finished yet — keep polling at the same interval.
+                continue;
+            case 'slow_down':
+                // Google asks us to back off; RFC 8628 §3.5 → bump the interval.
+                intervalSeconds += SLOW_DOWN_INCREMENT_SECONDS;
+                continue;
+            case 'access_denied':
+                throw new DeviceAuthError('access_denied', 'Authorization was denied by the user');
+            case 'expired_token':
+                throw new DeviceAuthError('expired_token', 'Device code expired before authorization');
+            default:
+                throw new DeviceAuthError(code ?? 'device_token_request_failed', `Device token poll failed (HTTP ${response.status}${code ? `, ${code}` : ''})`);
+        }
+    }
+}
+/**
+ * Extract Google's OAuth `error` code from a non-2xx response body without
+ * throwing. Returns null when the body isn't JSON or has no error field.
+ */
+async function readErrorCode(response) {
+    try {
+        const body = (await response.json());
+        return typeof body?.error === 'string' ? body.error : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=device-auth.js.map

package/dist/device-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-auth.js","sourceRoot":"","sources":["../src/device-auth.ts"],"names":[],"mappings":"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"}

package/dist/inbox-monitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inbox-monitor.d.ts","sourceRoot":"","sources":["../src/inbox-monitor.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAUH;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMhE;AA8CD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAM/E"}
+{"version":3,"file":"inbox-monitor.d.ts","sourceRoot":"","sources":["../src/inbox-monitor.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAUH;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMhE;AA6DD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAM/E"}

package/dist/inbox-monitor.js

@@ -71,6 +71,7 @@ function main() {
         process.exit(1);
     }
     const rl = createInterface({ input: tail.stdout, crlfDelay: Infinity });
+    let shuttingDown = false;
     rl.on('line', (line) => {
         const pretty = formatEventLine(line);
         if (pretty !== null) {
@@ -82,10 +83,24 @@ function main() {
         process.exit(1);
     });
     tail.on('exit', (code, signal) => {
+        if (shuttingDown)
+            process.exit(0);
         if (signal)
             process.exit(0);
         process.exit(code ?? 0);
     });
+    const shutdown = (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        rl.close();
+        if (!tail.killed && !tail.kill(signal)) {
+            process.exit(0);
+        }
+        setTimeout(() => process.exit(0), 1000).unref();
+    };
+    process.once('SIGTERM', () => shutdown('SIGTERM'));
+    process.once('SIGINT', () => shutdown('SIGINT'));
 }
 /**
  * Is this module being invoked as the bin entry point?

package/dist/inbox-monitor.js.map

@@ -1 +1 @@
-{"version":3,"file":"inbox-monitor.js","sourceRoot":"","sources":["../src/inbox-monitor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"inbox-monitor.js","sourceRoot":"","sources":["../src/inbox-monitor.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -374,7 +374,7 @@ async function main() {
                             cube_directive: { type: 'string', description: 'New cube directive markdown (optional).' },
                             message_taxonomy: {
                                 type: 'array',
-                                description: 'New message-class taxonomy (optional). REPLACES the whole taxonomy; the worker re-validates the full array (non-overlapping prefixes, unique class names, directed classes need default_to). Pass [] to clear. To change ONE class without resending the whole array, use borg:patch-taxonomy-class instead. In default_to, pass @human-seat to route to drones in the cube human-seat role(s); literal role names/slugs/labels still work.',
+                                description: 'New message-class taxonomy (optional). REPLACES the whole taxonomy; the worker re-validates the full array (non-overlapping prefixes, unique class names, directed classes need default_to). Pass [] to clear. To change ONE class without resending the whole array, use borg:patch-taxonomy-class instead. In default_to, pass @human-seat to route to drones in the cube human-seat role(s); literal role names/slugs/labels still work. Optional lifecycle tags mark dispatch/completion classes for stuck-dispatch detection.',
                                 items: {
                                     type: 'object',
                                     properties: {
@@ -382,6 +382,7 @@ async function main() {
                                         prefixes: { type: 'array', items: { type: 'string' }, description: 'Message prefixes routed by this class.' },
                                         routing: { type: 'string', enum: ['broadcast', 'directed'], description: 'Routing mode.' },
                                         default_to: { type: 'array', items: { type: 'string' }, description: 'Default recipients (role name/slug/label, or @human-seat) for a directed class.' },
+                                        lifecycle: { type: 'string', enum: ['dispatch', 'completion'], description: 'Optional lifecycle marker for stuck-dispatch detection.' },
                                     },
                                 },
                             },
@@ -391,7 +392,7 @@ async function main() {
                 },
                 {
                     name: 'borg:patch-taxonomy-class',
-                    description: "Surgically patch ONE message-class within a cube's message_taxonomy, leaving other classes unchanged. Use this instead of borg:update-cube when adding/changing a single class so you don't resend (and risk clobbering) the whole taxonomy. action=add appends a new class; action=replace overwrites the class with the same name (case-insensitive); action=remove drops a class. The whole resulting taxonomy is re-validated (non-overlapping prefixes, unique class names, directed classes need default_to) — a single-class patch that breaks a cross-class rule against an untouched class is rejected. In default_to, pass @human-seat to route to drones in the cube human-seat role(s); literal role names/slugs/labels still work.",
+                    description: "Surgically patch ONE message-class within a cube's message_taxonomy, leaving other classes unchanged. Use this instead of borg:update-cube when adding/changing a single class so you don't resend (and risk clobbering) the whole taxonomy. action=add appends a new class; action=replace overwrites the class with the same name (case-insensitive); action=remove drops a class. The whole resulting taxonomy is re-validated (non-overlapping prefixes, unique class names, directed classes need default_to) — a single-class patch that breaks a cross-class rule against an untouched class is rejected. In default_to, pass @human-seat to route to drones in the cube human-seat role(s); literal role names/slugs/labels still work. Optional lifecycle tags mark dispatch/completion classes for stuck-dispatch detection.",
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -399,12 +400,13 @@ async function main() {
                             action: { type: 'string', enum: ['add', 'replace', 'remove'], description: 'add / replace / remove a single class.' },
                             class_def: {
                                 type: 'object',
-                                description: 'The class definition (for add/replace). Shape: { class, prefixes?, routing: "broadcast"|"directed", default_to? }.',
+                                description: 'The class definition (for add/replace). Shape: { class, prefixes?, routing: "broadcast"|"directed", default_to?, lifecycle? }.',
                                 properties: {
                                     class: { type: 'string', description: 'Unique class name.' },
                                     prefixes: { type: 'array', items: { type: 'string' }, description: 'Message prefixes routed by this class.' },
                                     routing: { type: 'string', enum: ['broadcast', 'directed'], description: 'Routing mode.' },
                                     default_to: { type: 'array', items: { type: 'string' }, description: 'Default recipients (required for directed classes): role name/slug/label, or @human-seat.' },
+                                    lifecycle: { type: 'string', enum: ['dispatch', 'completion'], description: 'Optional lifecycle marker for stuck-dispatch detection.' },
                                 },
                                 required: ['class', 'routing'],
                             },