@vibe-commit/capture 0.1.0

package/dist/oauth/session.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The signed-in session on disk — the human lane's persistence.
+ *
+ * Lands in `~/.vibecommit/session.json` and therefore inherits the two checks
+ * `credential.ts`'s `readSecretFile` makes: the DIRECTORY must not be writable
+ * by group or other (`/cso` finding 3 — a writable `~/.vibecommit` lets a second
+ * local account unlink the file and drop in its own), and the FILE must not be
+ * readable by group or other, checked with `lstat` so a symlink cannot report
+ * its target's mode instead.
+ *
+ * ## What is stored, and what deliberately is not
+ *
+ * The refresh token, the access token, the access token's expiry as an epoch
+ * millisecond, and the two discovered endpoints. **Not** the code verifier or
+ * the `state` — both are per-attempt secrets that die with the sign-in that
+ * minted them, and a verifier surviving on disk would let a stolen code be
+ * exchanged later by whoever could read the file.
+ *
+ * The endpoints are cached because a read verb that re-ran discovery on every
+ * invocation would put two network round trips in front of every command, and
+ * because the ISSUER is the value RFC 9207's `iss` check compares against — so
+ * it has to be the one this session was established with, not whatever the
+ * server says today.
+ */
+import { type TokenSet } from "./token.js";
+export interface Session {
+    readonly tokens: TokenSet;
+    /** The RFC 8414 issuer this session was established against. */
+    readonly issuer: string;
+    readonly tokenEndpoint: string;
+}
+export type SessionLoad = {
+    readonly kind: "ok";
+    readonly session: Session;
+}
+/** Not signed in. The overwhelmingly common case, and not an error. */
+ | {
+    readonly kind: "absent";
+} | {
+    readonly kind: "insecure-file";
+    readonly path: string;
+    readonly mode: string;
+} | {
+    readonly kind: "unreadable";
+    readonly path: string;
+}
+/**
+ * A secret of the wrong class in one of the two slots — an ingest credential
+ * pasted into `refresh_token`, or a JWT where the opaque token belongs.
+ * Refused CLIENT-side and never sent, the mirror of `loadCredential`'s
+ * `wrong-class`: a credential is only meaningful on the lane it was minted for.
+ */
+ | {
+    readonly kind: "wrong-class";
+    readonly path: string;
+};
+/** Has the access token expired, allowing for the refresh margin? */
+export declare function isFresh(session: Session, nowMs: number): boolean;
+/**
+ * Read the session.
+ *
+ * Returns a discriminated union rather than throwing, for the same reason
+ * `loadCredential` does: the caller wants to distinguish "not signed in" from
+ * "signed in but the file is unsafe" so it can print two different fixes.
+ */
+export declare function loadSession(home: string): SessionLoad;
+/**
+ * Write the session. 0700 on the directory, 0600 on the file.
+ *
+ * `chmod` after `writeFileSync` for both, because `writeFileSync`'s `mode` is
+ * masked by the umask and is IGNORED ENTIRELY when the file already exists — so
+ * a session rewritten after a rotation would silently inherit whatever mode the
+ * previous write left. `consent.ts`'s `grantProject` learned this first; this is
+ * the same two lines for the same reason.
+ *
+ * The two `expose()` calls here are the only ones outside the request boundary,
+ * and they are unavoidable: persisting a secret means writing its bytes. They
+ * are greppable, which is the property the wrapper buys.
+ */
+export declare function saveSession(home: string, session: Session): void;

package/dist/oauth/session.js

@@ -0,0 +1,112 @@
+/**
+ * The signed-in session on disk — the human lane's persistence.
+ *
+ * Lands in `~/.vibecommit/session.json` and therefore inherits the two checks
+ * `credential.ts`'s `readSecretFile` makes: the DIRECTORY must not be writable
+ * by group or other (`/cso` finding 3 — a writable `~/.vibecommit` lets a second
+ * local account unlink the file and drop in its own), and the FILE must not be
+ * readable by group or other, checked with `lstat` so a symlink cannot report
+ * its target's mode instead.
+ *
+ * ## What is stored, and what deliberately is not
+ *
+ * The refresh token, the access token, the access token's expiry as an epoch
+ * millisecond, and the two discovered endpoints. **Not** the code verifier or
+ * the `state` — both are per-attempt secrets that die with the sign-in that
+ * minted them, and a verifier surviving on disk would let a stolen code be
+ * exchanged later by whoever could read the file.
+ *
+ * The endpoints are cached because a read verb that re-ran discovery on every
+ * invocation would put two network round trips in front of every command, and
+ * because the ISSUER is the value RFC 9207's `iss` check compares against — so
+ * it has to be the one this session was established with, not whatever the
+ * server says today.
+ */
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { AccessToken, RefreshToken, isAccessTokenShape, isRefreshTokenShape, readSecretFile, } from "../credential.js";
+import { rootDir, sessionPath } from "../paths.js";
+import { EXPIRY_SKEW_MS } from "./token.js";
+/** Has the access token expired, allowing for the refresh margin? */
+export function isFresh(session, nowMs) {
+    return session.tokens.expiresAtMs - EXPIRY_SKEW_MS > nowMs;
+}
+/**
+ * Read the session.
+ *
+ * Returns a discriminated union rather than throwing, for the same reason
+ * `loadCredential` does: the caller wants to distinguish "not signed in" from
+ * "signed in but the file is unsafe" so it can print two different fixes.
+ */
+export function loadSession(home) {
+    const path = sessionPath(home);
+    const read = readSecretFile(home, path);
+    if (read.kind !== "ok")
+        return read;
+    let doc;
+    try {
+        doc = JSON.parse(read.raw);
+    }
+    catch {
+        return { kind: "unreadable", path };
+    }
+    const { refresh_token: refresh, access_token: access } = doc;
+    if (typeof refresh !== "string" || typeof access !== "string") {
+        return { kind: "unreadable", path };
+    }
+    // Class before shape-of-envelope: a `vcik_` here is the interesting mistake,
+    // and reporting it as "unreadable" would send the user to fix the wrong thing.
+    if (!isRefreshTokenShape(refresh) || !isAccessTokenShape(access)) {
+        return { kind: "wrong-class", path };
+    }
+    if (typeof doc.expires_at_ms !== "number" ||
+        !Number.isFinite(doc.expires_at_ms) ||
+        typeof doc.issuer !== "string" ||
+        doc.issuer === "" ||
+        typeof doc.token_endpoint !== "string" ||
+        doc.token_endpoint === "") {
+        return { kind: "unreadable", path };
+    }
+    return {
+        kind: "ok",
+        session: {
+            tokens: {
+                access: new AccessToken(access),
+                refresh: new RefreshToken(refresh),
+                expiresAtMs: doc.expires_at_ms,
+                scope: typeof doc.scope === "string" ? doc.scope : "",
+            },
+            issuer: doc.issuer,
+            tokenEndpoint: doc.token_endpoint,
+        },
+    };
+}
+/**
+ * Write the session. 0700 on the directory, 0600 on the file.
+ *
+ * `chmod` after `writeFileSync` for both, because `writeFileSync`'s `mode` is
+ * masked by the umask and is IGNORED ENTIRELY when the file already exists — so
+ * a session rewritten after a rotation would silently inherit whatever mode the
+ * previous write left. `consent.ts`'s `grantProject` learned this first; this is
+ * the same two lines for the same reason.
+ *
+ * The two `expose()` calls here are the only ones outside the request boundary,
+ * and they are unavoidable: persisting a secret means writing its bytes. They
+ * are greppable, which is the property the wrapper buys.
+ */
+export function saveSession(home, session) {
+    const path = sessionPath(home);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    chmodSync(rootDir(home), 0o700);
+    const body = {
+        refresh_token: session.tokens.refresh.expose(),
+        access_token: session.tokens.access.expose(),
+        expires_at_ms: session.tokens.expiresAtMs,
+        scope: session.tokens.scope,
+        issuer: session.issuer,
+        token_endpoint: session.tokenEndpoint,
+    };
+    writeFileSync(path, `${JSON.stringify(body, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+//# sourceMappingURL=session.js.map

package/dist/oauth/session.js.map

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

package/dist/oauth/signin.d.ts

@@ -0,0 +1,178 @@
+/**
+ * The sign-in flow, and the refresh that keeps it alive.
+ *
+ * ```
+ *   discover  ──►  PKCE + state  ──►  loopback listener on 127.0.0.1:0
+ *       │                                      │
+ *       │                          browser ────┘  code + state + iss
+ *       ▼                                      ▼
+ *   authorize URL  ─────────────────────►  exchange  ──►  session.json
+ * ```
+ *
+ * Every step's failure is a NAMED outcome rather than an exception, because each
+ * one wants a different fix line: an unreachable discovery document is "the
+ * server is down", a denied grant is "you declined", and a malformed token
+ * response is ours to fix, not the user's.
+ *
+ * ## `authorizedAccessToken` is the part to read carefully
+ *
+ * It is the only caller of `refreshGrant`, and it takes `withRefreshLock` around
+ * a **re-read of the session from disk**. That order is the whole control: by
+ * the time a waiter gets the lock, the winner has rotated and saved, so the tail
+ * the waiter loaded before waiting is already a parent row — and presenting it
+ * is the replay that revokes the family and signs the user out everywhere. See
+ * `lock.ts`'s module note for why that is a Tuesday and not an edge case.
+ */
+import type { AccessToken, RefreshToken } from "../credential.js";
+import { type DiscoveryFault } from "./discovery.js";
+import { type ReadDeps, type ReadOutcome } from "./read.js";
+import { type Session, type SessionLoad } from "./session.js";
+/**
+ * How long the browser round trip may take. It contains a full identity-provider
+ * login — reading an email, a password manager, possibly a second factor — so
+ * the bound is a human's attention span rather than a network budget. Five
+ * minutes is long enough not to punish a slow login and short enough that an
+ * abandoned attempt does not leave a listener bound for the rest of the session.
+ */
+export declare const SIGNIN_DEADLINE_MS: number;
+/** How long each HTTP step gets. Discovery and the code exchange are both fast. */
+export declare const HTTP_TIMEOUT_MS = 10000;
+export interface SignInDeps {
+    readonly home: string;
+    readonly mcpEndpoint: string;
+    readonly fetch: typeof fetch;
+    readonly nowMs: () => number;
+    /** Injected so a test never launches a browser. Returns false if it could not. */
+    readonly openBrowser: (url: string) => boolean;
+    /** Called with the authorize URL so the caller can print it. Copy stays in `src/copy/`. */
+    readonly onAuthorizeUrl: (url: string, opened: boolean) => void;
+    /** The browser tab's text. Supplied by the caller from `src/copy/`. */
+    readonly page: {
+        readonly done: string;
+        readonly refused: string;
+    };
+    readonly deadlineMs?: number;
+    readonly timeoutMs?: number;
+}
+export type SignIn = {
+    readonly kind: "ok";
+    readonly session: Session;
+}
+/** Discovery failed. Carries the cause so the fix line can name it. */
+ | {
+    readonly kind: "no-server";
+    readonly detail: DiscoveryFault | "unreachable";
+}
+/** The user declined at the authorize screen, or the AS refused. */
+ | {
+    readonly kind: "denied";
+    readonly error: string;
+}
+/** Nobody came back before the deadline. */
+ | {
+    readonly kind: "timeout";
+}
+/** The code exchange failed. `unauthorized_client` lands here — see `token.ts`. */
+ | {
+    readonly kind: "rejected";
+    readonly error: string;
+} | {
+    readonly kind: "unreachable";
+} | {
+    readonly kind: "malformed";
+};
+/**
+ * Open a URL in the platform browser.
+ *
+ * Detached and with its streams discarded: the browser is not this process's
+ * child in any meaningful sense, and leaving a pipe attached would keep the CLI
+ * alive until the browser exits — which on a long-running browser is forever.
+ * Returns false rather than throwing when there is nothing to open with, because
+ * a headless machine is a perfectly ordinary place to run this and the URL
+ * printed to the terminal is a complete fallback.
+ */
+export declare function openBrowser(url: string): boolean;
+/**
+ * Run one sign-in, end to end.
+ *
+ * The listener is started BEFORE the browser is opened and closed in a
+ * `finally`, so there is no window in which the redirect can arrive at a port
+ * nobody is listening on, and no path on which a socket outlives the attempt.
+ */
+export declare function signIn(deps: SignInDeps): Promise<SignIn>;
+export type Authorized = 
+/**
+ * `refresh` travels with the token so a caller that gets a 401 anyway can say
+ * WHICH session failed. That is what lets the forced refresh below separate a
+ * stale token of our own from one another process has already replaced;
+ * without it the retry path would rotate a token that had just been rotated,
+ * which is the family revoke arriving through the error handling.
+ *
+ * `expiresAtMs` rides along for callers that want to reason about lifetime.
+ * It is deliberately NOT the identity used for that comparison — see
+ * `rotateUnderLock`, where using it was a `/cso` finding.
+ *
+ * (Phrasing note: those sentences avoid putting a quoted phrase immediately
+ * after the word f-r-o-m. The linkage scan in `test/provenance.test.ts` is a
+ * REGEX over raw text rather than an AST, so prose of that shape inside a
+ * comment is read as an import specifier and reported as escaping the package.
+ * Worth knowing before writing the obvious sentence.)
+ */
+{
+    readonly kind: "ok";
+    readonly access: AccessToken;
+    readonly expiresAtMs: number;
+    readonly refresh: RefreshToken;
+}
+/** Not signed in, or the session file is unusable. Carries the load for the fix line. */
+ | {
+    readonly kind: "no-session";
+    readonly load: SessionLoad;
+}
+/** The refresh grant was refused — the session is over and sign-in must run again. */
+ | {
+    readonly kind: "expired";
+    readonly error: string;
+}
+/** Another process held the refresh lock for longer than a healthy holder can. */
+ | {
+    readonly kind: "busy";
+} | {
+    readonly kind: "unreachable";
+} | {
+    readonly kind: "malformed";
+};
+export interface AuthorizeDeps {
+    readonly home: string;
+    readonly fetch: typeof fetch;
+    readonly nowMs: () => number;
+    readonly timeoutMs?: number;
+}
+/**
+ * A usable access token, refreshing under the cross-process lock if needed.
+ *
+ * The fast path takes no lock at all: a fresh access token is the common case
+ * and serialising every read behind a lock file would be a needless cost on
+ * every command.
+ */
+export declare function authorizedAccessToken(deps: AuthorizeDeps): Promise<Authorized>;
+/** What a read produces: a transport outcome, or the reason there was no token. */
+export type Read = ReadOutcome | {
+    readonly kind: "not-authorized";
+    readonly authorized: Authorized;
+};
+/**
+ * Call a read tool with the signed-in user's token: refresh ONCE, retry ONCE.
+ *
+ * The bound is STRUCTURAL rather than a counter — two `callTool` statements, no
+ * loop — because "retry until it works" against an endpoint that keeps answering
+ * 401 is how a client turns one expired token into a revoked family.
+ *
+ * The second attempt exists because a token can be fresh by the clock and
+ * rejected anyway: a revoked family, a rotated signing key, or a machine whose
+ * clock is simply wrong. Those look identical from here, and one retry after a
+ * genuine rotation resolves all three or fails honestly.
+ */
+export declare function readWithSession(mcpEndpoint: string, name: string, args: Record<string, unknown>, deps: AuthorizeDeps & {
+    readonly read: ReadDeps;
+}): Promise<Read>;

package/dist/oauth/signin.js

@@ -0,0 +1,225 @@
+/**
+ * The sign-in flow, and the refresh that keeps it alive.
+ *
+ * ```
+ *   discover  ──►  PKCE + state  ──►  loopback listener on 127.0.0.1:0
+ *       │                                      │
+ *       │                          browser ────┘  code + state + iss
+ *       ▼                                      ▼
+ *   authorize URL  ─────────────────────►  exchange  ──►  session.json
+ * ```
+ *
+ * Every step's failure is a NAMED outcome rather than an exception, because each
+ * one wants a different fix line: an unreachable discovery document is "the
+ * server is down", a denied grant is "you declined", and a malformed token
+ * response is ours to fix, not the user's.
+ *
+ * ## `authorizedAccessToken` is the part to read carefully
+ *
+ * It is the only caller of `refreshGrant`, and it takes `withRefreshLock` around
+ * a **re-read of the session from disk**. That order is the whole control: by
+ * the time a waiter gets the lock, the winner has rotated and saved, so the tail
+ * the waiter loaded before waiting is already a parent row — and presenting it
+ * is the replay that revokes the family and signs the user out everywhere. See
+ * `lock.ts`'s module note for why that is a Tuesday and not an edge case.
+ */
+import { spawn } from "node:child_process";
+import { discover } from "./discovery.js";
+import { listenForCallback } from "./loopback.js";
+import { REFRESH_REQUEST_TIMEOUT_MS, withRefreshLock } from "./lock.js";
+import { generatePkce, generateState } from "./pkce.js";
+import { callTool } from "./read.js";
+import { isFresh, loadSession, saveSession } from "./session.js";
+import { buildAuthorizeUrl, exchangeCode, refreshGrant } from "./token.js";
+/**
+ * How long the browser round trip may take. It contains a full identity-provider
+ * login — reading an email, a password manager, possibly a second factor — so
+ * the bound is a human's attention span rather than a network budget. Five
+ * minutes is long enough not to punish a slow login and short enough that an
+ * abandoned attempt does not leave a listener bound for the rest of the session.
+ */
+export const SIGNIN_DEADLINE_MS = 5 * 60_000;
+/** How long each HTTP step gets. Discovery and the code exchange are both fast. */
+export const HTTP_TIMEOUT_MS = 10_000;
+/**
+ * Open a URL in the platform browser.
+ *
+ * Detached and with its streams discarded: the browser is not this process's
+ * child in any meaningful sense, and leaving a pipe attached would keep the CLI
+ * alive until the browser exits — which on a long-running browser is forever.
+ * Returns false rather than throwing when there is nothing to open with, because
+ * a headless machine is a perfectly ordinary place to run this and the URL
+ * printed to the terminal is a complete fallback.
+ */
+export function openBrowser(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+        const child = spawn(command, [url], { detached: true, stdio: "ignore" });
+        // An ENOENT from `spawn` arrives asynchronously as an 'error' event, not as
+        // a throw. Without this handler it becomes an unhandled exception on a
+        // machine that simply has no `xdg-open` — a crash instead of a fallback.
+        child.on("error", () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Discovery's failure, flattened to the shape the caller renders. */
+function noServer(d) {
+    return { kind: "no-server", detail: d.kind === "unreachable" ? "unreachable" : d.detail };
+}
+/** A token-endpoint failure, flattened the same way. */
+function fromToken(outcome) {
+    if (outcome.kind === "denied")
+        return { kind: "rejected", error: outcome.error };
+    return outcome.kind === "unreachable" ? { kind: "unreachable" } : { kind: "malformed" };
+}
+/**
+ * Run one sign-in, end to end.
+ *
+ * The listener is started BEFORE the browser is opened and closed in a
+ * `finally`, so there is no window in which the redirect can arrive at a port
+ * nobody is listening on, and no path on which a socket outlives the attempt.
+ */
+export async function signIn(deps) {
+    const timeoutMs = deps.timeoutMs ?? HTTP_TIMEOUT_MS;
+    const discovery = await discover(deps.mcpEndpoint, { fetch: deps.fetch, timeoutMs });
+    if (discovery.kind !== "ok")
+        return noServer(discovery);
+    const { issuer, authorization_endpoint, token_endpoint } = discovery.metadata;
+    const pkce = generatePkce();
+    const state = generateState();
+    const loopback = await listenForCallback({
+        expectedState: state,
+        expectedIssuer: issuer,
+        deadlineMs: deps.deadlineMs ?? SIGNIN_DEADLINE_MS,
+        page: deps.page,
+    });
+    let callback;
+    try {
+        const url = buildAuthorizeUrl(authorization_endpoint, {
+            challenge: pkce.challenge,
+            state,
+            redirectUri: loopback.redirectUri,
+        });
+        deps.onAuthorizeUrl(url, deps.openBrowser(url));
+        callback = await loopback.result;
+    }
+    finally {
+        loopback.close();
+    }
+    if (callback.kind === "timeout")
+        return { kind: "timeout" };
+    if (callback.kind === "denied")
+        return { kind: "denied", error: callback.error };
+    const exchanged = await exchangeCode(token_endpoint, {
+        code: callback.code,
+        codeVerifier: pkce.verifier,
+        // Byte-identical to the one presented at authorize — the server compares
+        // them and answers `invalid_grant` on any difference.
+        redirectUri: loopback.redirectUri,
+    }, { fetch: deps.fetch, timeoutMs, nowMs: deps.nowMs() });
+    if (exchanged.kind !== "ok")
+        return fromToken(exchanged);
+    const session = { tokens: exchanged.tokens, issuer, tokenEndpoint: token_endpoint };
+    saveSession(deps.home, session);
+    return { kind: "ok", session };
+}
+/**
+ * A usable access token, refreshing under the cross-process lock if needed.
+ *
+ * The fast path takes no lock at all: a fresh access token is the common case
+ * and serialising every read behind a lock file would be a needless cost on
+ * every command.
+ */
+export async function authorizedAccessToken(deps) {
+    const load = loadSession(deps.home);
+    if (load.kind !== "ok")
+        return { kind: "no-session", load };
+    const { access, expiresAtMs, refresh } = load.session.tokens;
+    if (isFresh(load.session, deps.nowMs()))
+        return { kind: "ok", access, expiresAtMs, refresh };
+    return await rotateUnderLock(deps, refresh);
+}
+/**
+ * Take the cross-process lock and rotate — unless somebody else already did.
+ *
+ * `superseded` is the refresh token the caller found unusable. Under the lock
+ * the session is re-read, and if the stored token is no longer that one, another
+ * process rotated while we waited: its token is the live one, and rotating again
+ * would present a token that is already a parent row. That is the family revoke,
+ * so the check is the point of the function rather than an optimisation.
+ *
+ * ⚠ `/cso` finding, HIGH: this compares the TOKEN, not the expiry it used to
+ * compare. `expiresAtMs` is `nowMs + expires_in * 1000`, so two rotations
+ * sampling the same millisecond with the same lifetime produce the SAME number —
+ * and the guard would then read "nobody rotated" immediately after somebody did,
+ * present the dead token, and revoke the family. Over a real network the
+ * round trip makes that collision vanishingly unlikely; over loopback it is
+ * merely unlikely. The refresh token is 32 random bytes and cannot collide, so
+ * the narrow window closes rather than shrinking.
+ */
+async function rotateUnderLock(deps, superseded) {
+    const locked = await withRefreshLock(deps.home, async () => {
+        // ⚠ RE-READ INSIDE THE LOCK, ALWAYS. See the module note: the session was
+        // loaded before waiting, and if we waited at all, the winner has already
+        // rotated and saved.
+        const current = loadSession(deps.home);
+        if (current.kind !== "ok")
+            return { kind: "no-session", load: current };
+        if (current.session.tokens.refresh.expose() !== superseded.expose()) {
+            const { access, expiresAtMs, refresh } = current.session.tokens;
+            return { kind: "ok", access, expiresAtMs, refresh };
+        }
+        const rotated = await refreshGrant(current.session.tokenEndpoint, current.session.tokens.refresh, {
+            fetch: deps.fetch,
+            timeoutMs: deps.timeoutMs ?? REFRESH_REQUEST_TIMEOUT_MS,
+            nowMs: deps.nowMs(),
+        });
+        if (rotated.kind === "denied")
+            return { kind: "expired", error: rotated.error };
+        if (rotated.kind === "unreachable")
+            return { kind: "unreachable" };
+        if (rotated.kind === "malformed")
+            return { kind: "malformed" };
+        // Saved BEFORE returning, and before any read uses it: the old token is dead
+        // the instant the server answered, so a crash between here and the save
+        // would lose the only live token in the family.
+        const next = { ...current.session, tokens: rotated.tokens };
+        saveSession(deps.home, next);
+        return {
+            kind: "ok",
+            access: next.tokens.access,
+            expiresAtMs: next.tokens.expiresAtMs,
+            refresh: next.tokens.refresh,
+        };
+    });
+    return locked.kind === "ok" ? locked.value : { kind: "busy" };
+}
+/**
+ * Call a read tool with the signed-in user's token: refresh ONCE, retry ONCE.
+ *
+ * The bound is STRUCTURAL rather than a counter — two `callTool` statements, no
+ * loop — because "retry until it works" against an endpoint that keeps answering
+ * 401 is how a client turns one expired token into a revoked family.
+ *
+ * The second attempt exists because a token can be fresh by the clock and
+ * rejected anyway: a revoked family, a rotated signing key, or a machine whose
+ * clock is simply wrong. Those look identical from here, and one retry after a
+ * genuine rotation resolves all three or fails honestly.
+ */
+export async function readWithSession(mcpEndpoint, name, args, deps) {
+    const first = await authorizedAccessToken(deps);
+    if (first.kind !== "ok")
+        return { kind: "not-authorized", authorized: first };
+    const outcome = await callTool(mcpEndpoint, first.access, name, args, deps.read);
+    if (outcome.kind !== "unauthorized")
+        return outcome;
+    const second = await rotateUnderLock(deps, first.refresh);
+    if (second.kind !== "ok")
+        return { kind: "not-authorized", authorized: second };
+    return await callTool(mcpEndpoint, second.access, name, args, deps.read);
+}
+//# sourceMappingURL=signin.js.map

package/dist/oauth/signin.js.map

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