agent-trellis 0.5.2 → 0.6.0

package/dist/lib/oauth/flow.js

@@ -0,0 +1,193 @@
+/**
+ * The interactive half: dynamic client registration (RFC 7591) plus the
+ * authorization-code grant with PKCE (RFC 6749 §4.1, RFC 7636).
+ *
+ * Only ever reached from `trellis mcp auth`, run by a human. The gateway
+ * must never call into this file: it is spawned silently by an agent,
+ * typically with no terminal and no display, so it can neither show a
+ * browser nor wait for one (design.md D9).
+ */
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { createPkcePair } from "./pkce.js";
+export class AuthorizationError extends Error {
+}
+/**
+ * RFC 7591. Returns `undefined` when the AS advertises no registration
+ * endpoint — that is a legitimate configuration (a pre-registered
+ * client), not an error, so the caller falls back to whatever client id
+ * it was given.
+ */
+export async function registerClient(metadata, redirectUri, opts = {}) {
+    if (!metadata.registrationEndpoint)
+        return undefined;
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const response = await fetchImpl(metadata.registrationEndpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify({
+            client_name: "Trellis",
+            redirect_uris: [redirectUri],
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+            ...(opts.scope ? { scope: opts.scope } : {}),
+        }),
+    });
+    if (!response.ok) {
+        throw new AuthorizationError(`dynamic client registration failed with HTTP ${response.status}`);
+    }
+    const payload = (await response.json());
+    if (!payload.client_id) {
+        throw new AuthorizationError("dynamic client registration returned no client_id");
+    }
+    const out = { clientId: payload.client_id };
+    if (payload.client_secret)
+        out.clientSecret = payload.client_secret;
+    return out;
+}
+/** A one-shot loopback listener for the redirect. Bound to 127.0.0.1
+ * explicitly, never 0.0.0.0: the authorization code arrives in this URL,
+ * and a listener on all interfaces would accept it from the network. */
+function listenForCallback(port) {
+    return new Promise((resolve, reject) => {
+        let settle;
+        const received = new Promise((r) => {
+            settle = r;
+        });
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            const result = {};
+            const code = url.searchParams.get("code");
+            const state = url.searchParams.get("state");
+            const error = url.searchParams.get("error");
+            if (code)
+                result.code = code;
+            if (state)
+                result.state = state;
+            if (error) {
+                result.error = error;
+                const description = url.searchParams.get("error_description");
+                if (description)
+                    result.errorDescription = description;
+            }
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+            res.end(result.error
+                ? `<html><body><h1>Authorization failed</h1><p>${escapeHtml(result.errorDescription ?? result.error)}</p></body></html>`
+                : "<html><body><h1>Authorized</h1><p>You can close this tab and return to your terminal.</p></body></html>");
+            settle(result);
+        });
+        server.on("error", reject);
+        server.listen(port, "127.0.0.1", () => {
+            resolve({ server, port: server.address().port, received });
+        });
+    });
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
+}
+/**
+ * Runs the full authorization-code-plus-PKCE exchange and returns a
+ * token ready to persist. Does not write anything — storage is the
+ * caller's decision, so this stays testable without a home directory.
+ */
+export async function authorize(serverName, metadata, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const now = opts.now ?? Date.now;
+    const timeoutMs = opts.timeoutMs ?? 300_000;
+    const { server, port, received } = await listenForCallback(opts.callbackPort ?? 0);
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    try {
+        let clientId = opts.clientId;
+        let clientSecret = opts.clientSecret;
+        if (!clientId) {
+            const registered = await registerClient(metadata, redirectUri, { fetchImpl, scope: opts.scope });
+            if (!registered) {
+                throw new AuthorizationError(`"${serverName}"'s authorization server offers no dynamic client registration, and no client_id is configured for it`);
+            }
+            clientId = registered.clientId;
+            clientSecret = registered.clientSecret;
+        }
+        const pkce = createPkcePair();
+        const state = randomBytes(16).toString("base64url");
+        const authUrl = new URL(metadata.authorizationEndpoint);
+        authUrl.searchParams.set("response_type", "code");
+        authUrl.searchParams.set("client_id", clientId);
+        authUrl.searchParams.set("redirect_uri", redirectUri);
+        authUrl.searchParams.set("code_challenge", pkce.challenge);
+        authUrl.searchParams.set("code_challenge_method", pkce.method);
+        authUrl.searchParams.set("state", state);
+        if (opts.scope)
+            authUrl.searchParams.set("scope", opts.scope);
+        await (opts.openBrowser ?? defaultOpenBrowser)(authUrl.toString());
+        const callback = await withTimeout(received, timeoutMs, `timed out waiting for the authorization callback for "${serverName}"`);
+        if (callback.error) {
+            throw new AuthorizationError(`authorization for "${serverName}" was refused: ${callback.errorDescription ?? callback.error}`);
+        }
+        if (!callback.code) {
+            throw new AuthorizationError(`authorization for "${serverName}" returned no code`);
+        }
+        // CSRF: a callback carrying someone else's state is not ours to
+        // redeem, regardless of how good the code looks.
+        if (callback.state !== state) {
+            throw new AuthorizationError(`authorization callback for "${serverName}" carried an unexpected state parameter`);
+        }
+        const body = new URLSearchParams({
+            grant_type: "authorization_code",
+            code: callback.code,
+            redirect_uri: redirectUri,
+            client_id: clientId,
+            code_verifier: pkce.verifier,
+        });
+        if (clientSecret)
+            body.set("client_secret", clientSecret);
+        const response = await fetchImpl(metadata.tokenEndpoint, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body: body.toString(),
+        });
+        if (!response.ok) {
+            throw new AuthorizationError(`token exchange for "${serverName}" failed with HTTP ${response.status}`);
+        }
+        const payload = (await response.json());
+        if (!payload.access_token) {
+            throw new AuthorizationError(`token exchange for "${serverName}" returned no access_token`);
+        }
+        const token = {
+            accessToken: payload.access_token,
+            tokenEndpoint: metadata.tokenEndpoint,
+            clientId,
+        };
+        if (payload.refresh_token)
+            token.refreshToken = payload.refresh_token;
+        if (payload.expires_in !== undefined)
+            token.expiresAt = now() + payload.expires_in * 1000;
+        if (clientSecret)
+            token.clientSecret = clientSecret;
+        if (payload.scope ?? opts.scope)
+            token.scope = payload.scope ?? opts.scope;
+        return token;
+    }
+    finally {
+        server.close();
+    }
+}
+function withTimeout(promise, timeoutMs, message) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new AuthorizationError(message)), timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+async function defaultOpenBrowser(url) {
+    const { spawn } = await import("node:child_process");
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    // Detached and fully ignored: a browser that outlives this command is
+    // correct, and its stdio must not be inherited onto ours.
+    spawn(command, [url], { detached: true, stdio: "ignore" }).unref();
+}

package/dist/lib/oauth/lock.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Per-server exclusive lock around OAuth refresh
+ * (trellis-mcp-gateway-hosting design.md D16).
+ *
+ * Why this is a correctness fix and not an optimization: most
+ * authorization servers rotate the refresh token on each
+ * `refresh_token` grant and invalidate the previous one. Two processes
+ * refreshing the same server concurrently therefore leave one of them
+ * holding a token that is already dead — and it fails later, somewhere
+ * else, looking like an unrelated auth error. This is reachable today
+ * with a single gateway, because `trellis mcp auth` can be run by hand
+ * while one is live.
+ *
+ * Scoped to one server: a slow refresh for server A must never delay
+ * connecting to server B.
+ */
+/**
+ * Runs `fn` while holding this server's lock, releasing it even if `fn`
+ * throws. `wx` is the atomic primitive: it either creates the file or
+ * fails, with no check-then-create window between two processes.
+ */
+export declare function withServerLock<T>(homeDir: string, serverName: string, fn: () => Promise<T>, opts?: {
+    timeoutMs?: number;
+    now?: () => number;
+}): Promise<T>;

package/dist/lib/oauth/lock.js

@@ -0,0 +1,98 @@
+/**
+ * Per-server exclusive lock around OAuth refresh
+ * (trellis-mcp-gateway-hosting design.md D16).
+ *
+ * Why this is a correctness fix and not an optimization: most
+ * authorization servers rotate the refresh token on each
+ * `refresh_token` grant and invalidate the previous one. Two processes
+ * refreshing the same server concurrently therefore leave one of them
+ * holding a token that is already dead — and it fails later, somewhere
+ * else, looking like an unrelated auth error. This is reachable today
+ * with a single gateway, because `trellis mcp auth` can be run by hand
+ * while one is live.
+ *
+ * Scoped to one server: a slow refresh for server A must never delay
+ * connecting to server B.
+ */
+import { existsSync, mkdirSync, openSync, closeSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { lockPath } from "./store.js";
+/** A holder that died without cleaning up would otherwise wedge every
+ * later refresh forever. Two independent recovery signals are used: the
+ * recorded pid no longer existing, and the lock simply being older than
+ * any plausible refresh. */
+const STALE_AFTER_MS = 60_000;
+const POLL_INTERVAL_MS = 50;
+const DEFAULT_TIMEOUT_MS = 30_000;
+function processAlive(pid) {
+    try {
+        // Signal 0 performs the permission/existence check without
+        // delivering anything.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means it exists but belongs to another user — alive.
+        return err.code === "EPERM";
+    }
+}
+function isStale(path, now) {
+    let contents;
+    try {
+        contents = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        // Unreadable or half-written: treat as stale rather than deadlocking
+        // on a file nobody can interpret.
+        return true;
+    }
+    if (typeof contents.pid !== "number" || typeof contents.acquiredAt !== "number")
+        return true;
+    if (now - contents.acquiredAt > STALE_AFTER_MS)
+        return true;
+    return !processAlive(contents.pid);
+}
+/**
+ * Runs `fn` while holding this server's lock, releasing it even if `fn`
+ * throws. `wx` is the atomic primitive: it either creates the file or
+ * fails, with no check-then-create window between two processes.
+ */
+export async function withServerLock(homeDir, serverName, fn, opts = {}) {
+    const path = lockPath(homeDir, serverName);
+    const now = opts.now ?? Date.now;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const deadline = now() + timeoutMs;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    for (;;) {
+        try {
+            const fd = openSync(path, "wx", 0o600);
+            try {
+                writeFileSync(fd, JSON.stringify({ pid: process.pid, acquiredAt: now() }));
+            }
+            finally {
+                closeSync(fd);
+            }
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            if (existsSync(path) && isStale(path, now())) {
+                // Best-effort: if another process removed it first, our next
+                // `wx` attempt simply succeeds.
+                rmSync(path, { force: true });
+                continue;
+            }
+            if (now() >= deadline) {
+                throw new Error(`timed out waiting for the OAuth refresh lock on "${serverName}" (${path})`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        rmSync(path, { force: true });
+    }
+}

package/dist/lib/oauth/pkce.d.ts

@@ -0,0 +1,27 @@
+/**
+ * PKCE (RFC 7636), S256 only.
+ *
+ * `plain` is deliberately not implemented. It exists in the RFC for
+ * clients that cannot compute SHA-256; Node can, and offering `plain`
+ * would only create a path where a downgrade turns the challenge into
+ * the verifier in cleartext.
+ */
+export interface PkcePair {
+    verifier: string;
+    challenge: string;
+    method: "S256";
+}
+/**
+ * 32 random bytes → 43 base64url chars, comfortably inside the RFC's
+ * 43–128 range. Longer buys nothing: the entropy is the 256 bits, not
+ * the string length.
+ */
+export declare function createPkcePair(): PkcePair;
+export declare function computeChallenge(verifier: string): string;
+/**
+ * Constant-time comparison. Only an authorization server actually needs
+ * to verify a challenge — this exists so the fake AS the OAuth tests are
+ * written against can do the real check rather than a stubbed one, which
+ * is what makes those tests evidence that the client half is correct.
+ */
+export declare function verifyChallenge(verifier: string, challenge: string): boolean;

package/dist/lib/oauth/pkce.js

@@ -0,0 +1,40 @@
+/**
+ * PKCE (RFC 7636), S256 only.
+ *
+ * `plain` is deliberately not implemented. It exists in the RFC for
+ * clients that cannot compute SHA-256; Node can, and offering `plain`
+ * would only create a path where a downgrade turns the challenge into
+ * the verifier in cleartext.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+/** base64url per RFC 7636 §A: base64 with `+/` mapped to `-_` and no
+ * padding. `Buffer`'s own "base64url" encoding already does exactly
+ * this. */
+function base64url(input) {
+    return input.toString("base64url");
+}
+/**
+ * 32 random bytes → 43 base64url chars, comfortably inside the RFC's
+ * 43–128 range. Longer buys nothing: the entropy is the 256 bits, not
+ * the string length.
+ */
+export function createPkcePair() {
+    const verifier = base64url(randomBytes(32));
+    return { verifier, challenge: computeChallenge(verifier), method: "S256" };
+}
+export function computeChallenge(verifier) {
+    return base64url(createHash("sha256").update(verifier).digest());
+}
+/**
+ * Constant-time comparison. Only an authorization server actually needs
+ * to verify a challenge — this exists so the fake AS the OAuth tests are
+ * written against can do the real check rather than a stubbed one, which
+ * is what makes those tests evidence that the client half is correct.
+ */
+export function verifyChallenge(verifier, challenge) {
+    const expected = Buffer.from(computeChallenge(verifier));
+    const actual = Buffer.from(challenge);
+    if (expected.length !== actual.length)
+        return false;
+    return timingSafeEqual(expected, actual);
+}

package/dist/lib/oauth/refresh.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The `refresh_token` grant (RFC 6749 §6).
+ *
+ * Callable from two places with different rules: `trellis mcp auth`, run
+ * by a human, and the gateway subcommand, spawned silently by an agent.
+ * Both use this identical path, because refreshing needs neither a
+ * browser nor a callback listener — which is exactly why the gateway is
+ * allowed to do it and is not allowed to do the initial authorization
+ * (design.md D9).
+ */
+import { type StoredToken } from "./store.js";
+import type { FetchLike } from "./discovery.js";
+export interface RefreshOptions {
+    fetchImpl?: FetchLike;
+    /** Test seam; also lets a caller widen the early-refresh skew. */
+    now?: () => number;
+    skewMs?: number;
+    lockTimeoutMs?: number;
+}
+export declare class RefreshError extends Error {
+}
+/**
+ * Returns a token that is valid now, refreshing first if it isn't.
+ *
+ * `undefined` means there is nothing stored for this server at all — the
+ * caller decides whether that is "skip this upstream" (the gateway) or
+ * "run the full flow" (`trellis mcp auth`). A refresh that is attempted
+ * and fails throws instead, because that is a different situation: a
+ * credential exists but is dead, and silently treating it as absent
+ * would hide a revoked grant.
+ */
+export declare function ensureFreshToken(homeDir: string, serverName: string, opts?: RefreshOptions): Promise<StoredToken | undefined>;
+export declare function performRefresh(serverName: string, token: StoredToken, opts?: RefreshOptions): Promise<StoredToken>;

package/dist/lib/oauth/refresh.js

@@ -0,0 +1,93 @@
+/**
+ * The `refresh_token` grant (RFC 6749 §6).
+ *
+ * Callable from two places with different rules: `trellis mcp auth`, run
+ * by a human, and the gateway subcommand, spawned silently by an agent.
+ * Both use this identical path, because refreshing needs neither a
+ * browser nor a callback listener — which is exactly why the gateway is
+ * allowed to do it and is not allowed to do the initial authorization
+ * (design.md D9).
+ */
+import { isExpired, readToken, writeToken } from "./store.js";
+import { withServerLock } from "./lock.js";
+export class RefreshError extends Error {
+}
+/**
+ * Returns a token that is valid now, refreshing first if it isn't.
+ *
+ * `undefined` means there is nothing stored for this server at all — the
+ * caller decides whether that is "skip this upstream" (the gateway) or
+ * "run the full flow" (`trellis mcp auth`). A refresh that is attempted
+ * and fails throws instead, because that is a different situation: a
+ * credential exists but is dead, and silently treating it as absent
+ * would hide a revoked grant.
+ */
+export async function ensureFreshToken(homeDir, serverName, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const existing = readToken(homeDir, serverName);
+    if (!existing)
+        return undefined;
+    if (!isExpired(existing, opts.skewMs, now()))
+        return existing;
+    if (!existing.refreshToken) {
+        throw new RefreshError(`OAuth token for "${serverName}" has expired and there is no refresh token — run \`trellis mcp auth ${serverName}\``);
+    }
+    return withServerLock(homeDir, serverName, async () => {
+        // Re-read inside the lock. Whoever held it before us may have just
+        // refreshed, in which case doing it again would rotate the token
+        // out from under them for nothing.
+        const current = readToken(homeDir, serverName);
+        if (current && !isExpired(current, opts.skewMs, now()))
+            return current;
+        const source = current ?? existing;
+        if (!source.refreshToken) {
+            throw new RefreshError(`OAuth token for "${serverName}" has expired and there is no refresh token — run \`trellis mcp auth ${serverName}\``);
+        }
+        const refreshed = await performRefresh(serverName, source, opts);
+        writeToken(homeDir, serverName, refreshed);
+        return refreshed;
+    }, { timeoutMs: opts.lockTimeoutMs, now });
+}
+export async function performRefresh(serverName, token, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const now = opts.now ?? Date.now;
+    if (!token.tokenEndpoint) {
+        throw new RefreshError(`OAuth token for "${serverName}" has no recorded token endpoint — run \`trellis mcp auth ${serverName}\``);
+    }
+    const body = new URLSearchParams({ grant_type: "refresh_token", refresh_token: token.refreshToken });
+    if (token.clientId)
+        body.set("client_id", token.clientId);
+    if (token.clientSecret)
+        body.set("client_secret", token.clientSecret);
+    const response = await fetchImpl(token.tokenEndpoint, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+        body: body.toString(),
+    });
+    if (!response.ok) {
+        throw new RefreshError(`refresh_token grant for "${serverName}" failed with HTTP ${response.status}: ${await safeText(response)}`);
+    }
+    const payload = (await response.json());
+    if (!payload.access_token) {
+        throw new RefreshError(`refresh_token grant for "${serverName}" returned no access_token`);
+    }
+    return {
+        ...token,
+        accessToken: payload.access_token,
+        // Rotation: a server that issues a new refresh token has invalidated
+        // the old one, so keeping the old one would be keeping a dead
+        // credential. A server that omits it is signalling the existing one
+        // stays valid.
+        refreshToken: payload.refresh_token ?? token.refreshToken,
+        expiresAt: payload.expires_in !== undefined ? now() + payload.expires_in * 1000 : undefined,
+        scope: payload.scope ?? token.scope,
+    };
+}
+async function safeText(response) {
+    try {
+        return (await response.text()).slice(0, 200);
+    }
+    catch {
+        return "<unreadable body>";
+    }
+}

package/dist/lib/oauth/store.d.ts

@@ -0,0 +1,55 @@
+/**
+ * OAuth token storage: one file per server under
+ * `~/.trellis/mcp/oauth/`, mode 0600 (trellis-mcp-gateway-hosting
+ * design.md D8).
+ *
+ * Deliberately NOT `resolveSecretEnv`, and deliberately NOT the OS
+ * keychain. `resolveSecretEnv`'s contract is "resolve a name the user
+ * wrote in canonical" — a token is the opposite: a value Trellis obtains
+ * and rotates on its own, which the user never names. And this change's
+ * research spike reproduced `security add-generic-password` failing
+ * (exit 152/154) in a non-interactive shell with no GUI session — exactly
+ * the environment an agent-spawned gateway subprocess runs in.
+ *
+ * Nothing here ever touches `servers.yaml`. A canonical file must stay
+ * safe to read, diff, and commit.
+ */
+export interface StoredToken {
+    accessToken: string;
+    refreshToken?: string;
+    /** Epoch ms. Absent means "no expiry was advertised" — treated as
+     * never expiring, since guessing one would refresh a perfectly valid
+     * token for no reason. */
+    expiresAt?: number;
+    /** From dynamic client registration, or configured by hand. Kept so a
+     * refresh never has to re-register. */
+    clientId?: string;
+    clientSecret?: string;
+    /** Kept so a silent refresh needs no network round trip to rediscover
+     * metadata — the gateway's refresh path should be one request. */
+    tokenEndpoint?: string;
+    scope?: string;
+}
+export declare function oauthDir(homeDir: string): string;
+/**
+ * Server names are YAML keys, so they can contain anything — including
+ * `/` and `..`. They are used verbatim as filenames here, so a name that
+ * could escape `oauthDir` is rejected rather than sanitized: silently
+ * mapping two different server names onto one file would cross two
+ * servers' credentials, which is worse than refusing.
+ */
+export declare function tokenPath(homeDir: string, serverName: string): string;
+export declare function lockPath(homeDir: string, serverName: string): string;
+export declare function readToken(homeDir: string, serverName: string): StoredToken | undefined;
+/**
+ * Written 0600 from the moment it first exists, never "create then
+ * chmod" — the gap between those two is a window where another local
+ * user can read the token. `writeFileSync`'s `mode` only applies on
+ * creation, so an existing file is chmod'd explicitly to repair a
+ * previously-loose permission.
+ */
+export declare function writeToken(homeDir: string, serverName: string, token: StoredToken): void;
+export declare function deleteToken(homeDir: string, serverName: string): void;
+/** A token with no `expiresAt` never expires. `skewMs` refreshes slightly
+ * early so a token doesn't die mid-request after passing this check. */
+export declare function isExpired(token: StoredToken, skewMs?: number, now?: number): boolean;

package/dist/lib/oauth/store.js

@@ -0,0 +1,85 @@
+/**
+ * OAuth token storage: one file per server under
+ * `~/.trellis/mcp/oauth/`, mode 0600 (trellis-mcp-gateway-hosting
+ * design.md D8).
+ *
+ * Deliberately NOT `resolveSecretEnv`, and deliberately NOT the OS
+ * keychain. `resolveSecretEnv`'s contract is "resolve a name the user
+ * wrote in canonical" — a token is the opposite: a value Trellis obtains
+ * and rotates on its own, which the user never names. And this change's
+ * research spike reproduced `security add-generic-password` failing
+ * (exit 152/154) in a non-interactive shell with no GUI session — exactly
+ * the environment an agent-spawned gateway subprocess runs in.
+ *
+ * Nothing here ever touches `servers.yaml`. A canonical file must stay
+ * safe to read, diff, and commit.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export function oauthDir(homeDir) {
+    return join(homeDir, ".trellis", "mcp", "oauth");
+}
+/**
+ * Server names are YAML keys, so they can contain anything — including
+ * `/` and `..`. They are used verbatim as filenames here, so a name that
+ * could escape `oauthDir` is rejected rather than sanitized: silently
+ * mapping two different server names onto one file would cross two
+ * servers' credentials, which is worse than refusing.
+ */
+export function tokenPath(homeDir, serverName) {
+    assertSafeServerName(serverName);
+    return join(oauthDir(homeDir), `${serverName}.json`);
+}
+export function lockPath(homeDir, serverName) {
+    assertSafeServerName(serverName);
+    return join(oauthDir(homeDir), `${serverName}.lock`);
+}
+function assertSafeServerName(serverName) {
+    if (serverName === "" || serverName === "." || serverName === ".." || /[/\\]/.test(serverName) || serverName.startsWith(".")) {
+        throw new Error(`refusing to use MCP server name "${serverName}" as an OAuth credential filename`);
+    }
+}
+export function readToken(homeDir, serverName) {
+    const path = tokenPath(homeDir, serverName);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        // A corrupt credential file is treated as "no credential": the
+        // recovery is to re-run `trellis mcp auth`, and refusing to start the
+        // gateway over it would take down every other server too.
+        return undefined;
+    }
+}
+/**
+ * Written 0600 from the moment it first exists, never "create then
+ * chmod" — the gap between those two is a window where another local
+ * user can read the token. `writeFileSync`'s `mode` only applies on
+ * creation, so an existing file is chmod'd explicitly to repair a
+ * previously-loose permission.
+ */
+export function writeToken(homeDir, serverName, token) {
+    const dir = oauthDir(homeDir);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = tokenPath(homeDir, serverName);
+    // Write-then-rename so a reader never observes a half-written file —
+    // the gateway reads these at startup while `trellis mcp auth` may be
+    // writing one.
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(token, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+    chmodSync(path, 0o600);
+}
+export function deleteToken(homeDir, serverName) {
+    rmSync(tokenPath(homeDir, serverName), { force: true });
+}
+/** A token with no `expiresAt` never expires. `skewMs` refreshes slightly
+ * early so a token doesn't die mid-request after passing this check. */
+export function isExpired(token, skewMs = 60_000, now = Date.now()) {
+    if (token.expiresAt === undefined)
+        return false;
+    return token.expiresAt - skewMs <= now;
+}