@vibe-commit/capture 0.1.0

package/dist/oauth/discovery.d.ts

@@ -0,0 +1,96 @@
+/**
+ * RFC 9728 + RFC 8414 discovery — where the authorize and token endpoints are.
+ *
+ * **The authorize URL is DISCOVERED, never constructed.** `vibecommit-mcp`
+ * deliberately does not route `/oauth/authorize`: the authorize UI lives in
+ * `vibecommit-web` on a different host in production, and the server carries its
+ * address as configuration (`DiscoveryUrls.authorizeEndpointUrl`, whose own
+ * docblock says *"there is no correct cross-repo default (any `${issuer}/...`
+ * 404s on the MCP host)"*). A hardcoded path has already cost this project once:
+ * the constant pointed at `/oauth/authorize` while the live route was
+ * `/auth/claude`, and every failure read as a config problem.
+ *
+ * So the chain is:
+ *
+ *   1. `GET <resource-origin>/.well-known/oauth-protected-resource` → RFC 9728
+ *      protected-resource metadata → `authorization_servers[0]` is the issuer.
+ *   2. `GET <issuer>/.well-known/oauth-authorization-server` → RFC 8414
+ *      authorization-server metadata → `authorization_endpoint`, `token_endpoint`.
+ *
+ * ## The issuer check is not paperwork
+ *
+ * RFC 8414 §3.3 requires the `issuer` INSIDE the metadata to equal the issuer
+ * the document was fetched from. That exact-string equality is the same
+ * constraint D26 records on the other side of the wire — the authorization
+ * response carries RFC 9207 `iss`, and it must string-equal both the PRM
+ * `authorization_servers[]` entry and this document's `issuer`. Three places,
+ * one string; a mismatch anywhere is a mix-up attack or a misconfiguration, and
+ * either way the flow must stop rather than proceed against an issuer nobody
+ * vouched for.
+ *
+ * Nothing is imported from `vibecommit-mcp` and nothing may be: it is closed
+ * source and this package is MIT (D60 §D1a). The two documents below are the
+ * WIRE SHAPE, retyped from reading it.
+ *
+ * @provenance vibecommit-mcp src/oauth/discovery.ts — both metadata documents, retyped
+ * @provenance vibecommit-mcp src/transport/server.ts — both `.well-known` routes, retyped
+ * @provenance vibecommit-web /auth/* — authorize UI is hosted there, not on the MCP host
+ */
+/** RFC 9728 §3.1. */
+export declare const PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+/** RFC 8414 §3. */
+export declare const AUTHORIZATION_SERVER_PATH = "/.well-known/oauth-authorization-server";
+/**
+ * The `/mcp` resource this client reads from. One `tools/call` POST goes here
+ * with the user token as bearer — there is no second Fly app, no `/read` route
+ * and no second hostname (D73, which closed `CR-083` as not needed).
+ */
+export declare const DEFAULT_MCP_URL = "https://api.vibecommit.ai/mcp";
+/** Override for tests and for a self-hosted server, same shape as the ingest lane's. */
+export declare function mcpUrl(env: NodeJS.ProcessEnv): string | null;
+/**
+ * What this client needs out of the two documents.
+ *
+ * A subset, deliberately: the server publishes `scopes_supported`,
+ * `response_types_supported` and more, and a client that retyped every field
+ * would break on an addition it does not use.
+ */
+export interface AuthorizationServerMetadata {
+    readonly issuer: string;
+    readonly authorization_endpoint: string;
+    readonly token_endpoint: string;
+    readonly code_challenge_methods_supported?: readonly string[];
+}
+export type Discovery = {
+    readonly kind: "ok";
+    readonly metadata: AuthorizationServerMetadata;
+}
+/** No document, or one that is not JSON. The server may simply be down. */
+ | {
+    readonly kind: "unreachable";
+    readonly url: string;
+}
+/** A document arrived and is not usable. `detail` names WHICH rule failed. */
+ | {
+    readonly kind: "malformed";
+    readonly url: string;
+    readonly detail: DiscoveryFault;
+};
+/**
+ * Why a document was refused. A named cause rather than a boolean, because
+ * "issuer does not match" and "S256 not offered" want different fixes and the
+ * error block has to say which.
+ */
+export type DiscoveryFault = "no_authorization_server" | "issuer_mismatch" | "no_authorize_endpoint" | "no_token_endpoint" | "insecure_endpoint" | "no_s256";
+/** Injected so tests drive a real local server rather than the network. */
+export interface DiscoveryDeps {
+    readonly fetch: typeof fetch;
+    readonly timeoutMs: number;
+}
+/**
+ * Discover the authorization server for `resourceUrl`.
+ *
+ * `resourceUrl` is the `/mcp` endpoint. Both documents are public by design
+ * (RFC 9728/8414 §"no auth"), so nothing here carries a credential.
+ */
+export declare function discover(resourceUrl: string, deps: DiscoveryDeps): Promise<Discovery>;

package/dist/oauth/discovery.js

@@ -0,0 +1,163 @@
+/**
+ * RFC 9728 + RFC 8414 discovery — where the authorize and token endpoints are.
+ *
+ * **The authorize URL is DISCOVERED, never constructed.** `vibecommit-mcp`
+ * deliberately does not route `/oauth/authorize`: the authorize UI lives in
+ * `vibecommit-web` on a different host in production, and the server carries its
+ * address as configuration (`DiscoveryUrls.authorizeEndpointUrl`, whose own
+ * docblock says *"there is no correct cross-repo default (any `${issuer}/...`
+ * 404s on the MCP host)"*). A hardcoded path has already cost this project once:
+ * the constant pointed at `/oauth/authorize` while the live route was
+ * `/auth/claude`, and every failure read as a config problem.
+ *
+ * So the chain is:
+ *
+ *   1. `GET <resource-origin>/.well-known/oauth-protected-resource` → RFC 9728
+ *      protected-resource metadata → `authorization_servers[0]` is the issuer.
+ *   2. `GET <issuer>/.well-known/oauth-authorization-server` → RFC 8414
+ *      authorization-server metadata → `authorization_endpoint`, `token_endpoint`.
+ *
+ * ## The issuer check is not paperwork
+ *
+ * RFC 8414 §3.3 requires the `issuer` INSIDE the metadata to equal the issuer
+ * the document was fetched from. That exact-string equality is the same
+ * constraint D26 records on the other side of the wire — the authorization
+ * response carries RFC 9207 `iss`, and it must string-equal both the PRM
+ * `authorization_servers[]` entry and this document's `issuer`. Three places,
+ * one string; a mismatch anywhere is a mix-up attack or a misconfiguration, and
+ * either way the flow must stop rather than proceed against an issuer nobody
+ * vouched for.
+ *
+ * Nothing is imported from `vibecommit-mcp` and nothing may be: it is closed
+ * source and this package is MIT (D60 §D1a). The two documents below are the
+ * WIRE SHAPE, retyped from reading it.
+ *
+ * @provenance vibecommit-mcp src/oauth/discovery.ts — both metadata documents, retyped
+ * @provenance vibecommit-mcp src/transport/server.ts — both `.well-known` routes, retyped
+ * @provenance vibecommit-web /auth/* — authorize UI is hosted there, not on the MCP host
+ */
+import { isAllowedIngestUrl } from "../post.js";
+import { CHALLENGE_METHOD } from "./pkce.js";
+/** RFC 9728 §3.1. */
+export const PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+/** RFC 8414 §3. */
+export const AUTHORIZATION_SERVER_PATH = "/.well-known/oauth-authorization-server";
+/**
+ * The `/mcp` resource this client reads from. One `tools/call` POST goes here
+ * with the user token as bearer — there is no second Fly app, no `/read` route
+ * and no second hostname (D73, which closed `CR-083` as not needed).
+ */
+export const DEFAULT_MCP_URL = "https://api.vibecommit.ai/mcp";
+/** Override for tests and for a self-hosted server, same shape as the ingest lane's. */
+export function mcpUrl(env) {
+    const override = env.VIBECOMMIT_MCP_URL;
+    if (override === undefined || override.trim() === "")
+        return DEFAULT_MCP_URL;
+    const candidate = override.trim();
+    return isAllowedIngestUrl(candidate) ? candidate : null;
+}
+async function getJson(url, deps) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.timeoutMs);
+    try {
+        const res = await deps.fetch(url, {
+            method: "GET",
+            headers: { accept: "application/json" },
+            signal: controller.signal,
+            // A discovery document that redirects is a document from somewhere the
+            // operator did not configure. `post.ts` refuses redirects on the same
+            // reasoning and for the same lane.
+            redirect: "error",
+        });
+        if (!res.ok)
+            return { ok: false };
+        return { ok: true, body: (await res.json()) };
+    }
+    catch {
+        return { ok: false };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** `https://host/mcp` → `https://host`. The `.well-known` paths sit at the root. */
+function originOf(url) {
+    return new URL(url).origin;
+}
+/**
+ * Discover the authorization server for `resourceUrl`.
+ *
+ * `resourceUrl` is the `/mcp` endpoint. Both documents are public by design
+ * (RFC 9728/8414 §"no auth"), so nothing here carries a credential.
+ */
+export async function discover(resourceUrl, deps) {
+    const prmUrl = `${originOf(resourceUrl)}${PROTECTED_RESOURCE_PATH}`;
+    const prm = await getJson(prmUrl, deps);
+    if (!prm.ok)
+        return { kind: "unreachable", url: prmUrl };
+    const servers = prm.body.authorization_servers;
+    const issuer = Array.isArray(servers) && typeof servers[0] === "string" ? servers[0] : null;
+    if (issuer === null || issuer === "") {
+        return { kind: "malformed", url: prmUrl, detail: "no_authorization_server" };
+    }
+    // ⚠ `/cso` finding, MEDIUM. VALIDATE BEFORE FETCHING, not after. The issuer
+    // arrives INSIDE a document, so it is remote input, and the next line turns it
+    // into an outbound request from the user's machine. Validating only the two
+    // ENDPOINTS below — which is what this did — left the AS-metadata GET itself
+    // unchecked, so a hostile or compromised discovery document could aim it at
+    // `http://169.254.169.254`, a private RFC 1918 address, or an arbitrary
+    // internal port: a blind SSRF probe with the request coming from inside the
+    // network. The response cannot be read back by the attacker, which is what
+    // keeps this MEDIUM rather than HIGH.
+    //
+    // Same predicate the endpoints get, applied one step earlier so the rule is
+    // consistent: every URL this module fetches passed it first.
+    if (!isAllowedIngestUrl(issuer)) {
+        return { kind: "malformed", url: prmUrl, detail: "insecure_endpoint" };
+    }
+    const asUrl = `${issuer.replace(/\/+$/, "")}${AUTHORIZATION_SERVER_PATH}`;
+    const as = await getJson(asUrl, deps);
+    if (!as.ok)
+        return { kind: "unreachable", url: asUrl };
+    const doc = as.body;
+    // RFC 8414 §3.3, and D26's exact-string rule. Not normalised, not
+    // case-folded, not trailing-slash-tolerant: the whole value of the check is
+    // that it is the SAME comparison the RFC 9207 `iss` check makes later, so a
+    // server whose three copies of this string disagree fails here rather than
+    // three steps further on where it reads as something else.
+    if (doc.issuer !== issuer)
+        return { kind: "malformed", url: asUrl, detail: "issuer_mismatch" };
+    if (typeof doc.authorization_endpoint !== "string" || doc.authorization_endpoint === "") {
+        return { kind: "malformed", url: asUrl, detail: "no_authorize_endpoint" };
+    }
+    if (typeof doc.token_endpoint !== "string" || doc.token_endpoint === "") {
+        return { kind: "malformed", url: asUrl, detail: "no_token_endpoint" };
+    }
+    // The token endpoint receives the verifier and returns the refresh token, and
+    // the authorize endpoint receives the challenge. Neither may be plaintext off
+    // the loopback. Same predicate as the ingest lane: https, or http to a
+    // loopback host. (⚠ NOT the redirect-URI rule — that one additionally
+    // forbids the literal `localhost`, and it lives in `loopback.ts` because it is
+    // the SERVER's policy about a value we send it, not ours about where we send.)
+    for (const endpoint of [doc.authorization_endpoint, doc.token_endpoint]) {
+        if (!isAllowedIngestUrl(endpoint)) {
+            return { kind: "malformed", url: asUrl, detail: "insecure_endpoint" };
+        }
+    }
+    // Absent means "unstated", and RFC 8414 §2 says a client that needs S256 must
+    // not assume it. We need it: it is the only method this client can produce.
+    const methods = doc.code_challenge_methods_supported;
+    if (!Array.isArray(methods) || !methods.includes(CHALLENGE_METHOD)) {
+        return { kind: "malformed", url: asUrl, detail: "no_s256" };
+    }
+    return {
+        kind: "ok",
+        metadata: {
+            issuer,
+            authorization_endpoint: doc.authorization_endpoint,
+            token_endpoint: doc.token_endpoint,
+            code_challenge_methods_supported: methods,
+        },
+    };
+}
+//# sourceMappingURL=discovery.js.map

package/dist/oauth/discovery.js.map

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

package/dist/oauth/lock.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Cross-process single-flight for the refresh grant.
+ *
+ * ## ⚠ WHY THIS FILE EXISTS AT ALL — read before simplifying it away
+ *
+ * `vibecommit-mcp/src/oauth/refresh.ts` implements refresh-token FAMILY rotation
+ * with application-layer reuse detection: presenting a token that already has a
+ * child row is treated as a replay and **revokes the ENTIRE FAMILY** with
+ * `revoked_reason = 'reuse_detected'`. There is a database-level guard behind it
+ * too — a partial unique index on `parent_token_id`, so of two concurrent
+ * rotations from the same tail exactly one INSERT wins and the loser's 23505 is
+ * *also* read as reuse.
+ *
+ * Two terminals running a read at the same moment present the same tail token.
+ * That is not an edge case; it is Tuesday. Without a lock, one of them wins, the
+ * other is classed a replay, and **the user is signed out of every machine at
+ * once** — from doing nothing but running the same command twice.
+ *
+ * So the mutual exclusion has to be BETWEEN PROCESSES. An in-process mutex, a
+ * module-level promise, an `async` queue — every in-memory construct is the
+ * wrong shape here, because the two racers are two separate `vibecommit`
+ * invocations that share nothing but a filesystem.
+ *
+ * ## The loser waits and RE-READS — it does not queue up to present the old token
+ *
+ * `withRefreshLock` gives its callback the lock, nothing more. The callback's
+ * first act must be to re-read the session from disk, because by the time a
+ * waiter acquires the lock the winner has already rotated and saved: the tail
+ * the waiter loaded BEFORE waiting is now the parent of a live row, and
+ * presenting it is precisely the replay this file exists to prevent. See
+ * `signin.ts`'s `authorizedAccessToken`, which is the only caller and is written
+ * in exactly that order.
+ *
+ * ## The stale timeout is DERIVED, not guessed
+ *
+ * A crashed holder must not wedge every future read, so a lock older than
+ * `STALE_MS` is reclaimable. That number is not a feel for how long things take:
+ * this project has already paid for one wall-clock guess (`CR-126`/D83 found a
+ * `setTimeout(..., 60)` that was a guess at boot duration, sitting between p50
+ * and p90 and firing ~14% of the time idle and ~28% under load).
+ *
+ * The holder does exactly ONE thing while holding this lock: a single POST to
+ * the token endpoint, and that POST is bounded by an `AbortController` at
+ * `REFRESH_REQUEST_TIMEOUT_MS`. So the longest a HEALTHY holder can hold the
+ * lock is that timeout plus the file I/O either side of it, and `STALE_MS` is
+ * that bound plus a margin — an arithmetic consequence of the operation it
+ * bounds, which means changing the request timeout moves it automatically
+ * rather than leaving a stale constant behind.
+ *
+ * Reclaiming too EARLY is the dangerous direction: it puts two processes into
+ * the refresh at once, which is the family revoke. Reclaiming too LATE only
+ * makes a rare recovery slower. The margin is therefore generous on purpose.
+ *
+ * Nothing is imported or copied from the closed core (D60 §D1a): what crossed
+ * the boundary is the RULE that concurrent rotation is a revoke, which is a
+ * behavioural contract this client must obey, not an implementation.
+ *
+ * @provenance vibecommit-mcp src/oauth/refresh.ts — family-rotation reuse-detection rule, retyped
+ */
+/**
+ * The whole budget for one refresh POST. Also the ONLY thing done under the
+ * lock, which is what makes `STALE_MS` below derivable.
+ */
+export declare const REFRESH_REQUEST_TIMEOUT_MS = 10000;
+/**
+ * When a lock is old enough to be a corpse rather than a holder.
+ *
+ * `REFRESH_REQUEST_TIMEOUT_MS` bounds the healthy hold; the rest is margin for
+ * the read/write either side and for a machine under enough load that a process
+ * does not get scheduled promptly. Erring long is the cheap direction — see the
+ * module note.
+ */
+export declare const STALE_MS: number;
+/**
+ * How long a waiter waits before giving up.
+ *
+ * Strictly greater than `STALE_MS`: a waiter that gave up sooner would abandon a
+ * refresh that a perfectly healthy holder was still allowed to be running, and
+ * the user would see a spurious failure while the thing they needed was in
+ * flight one process over.
+ */
+export declare const WAIT_TIMEOUT_MS: number;
+/** One lock for the refresh grant. Sits beside the session it protects. */
+export declare function refreshLockPath(home: string): string;
+export type LockFailure = "timeout";
+/**
+ * Run `fn` with the refresh lock held.
+ *
+ * Returns `{ kind: "timeout" }` rather than throwing when the lock cannot be
+ * taken: the caller is a read verb, and a read that cannot refresh should tell
+ * the user what happened, not take an exception out of a lock file.
+ *
+ * The lock is released in a `finally`, so a throwing callback still frees it.
+ */
+export declare function withRefreshLock<T>(home: string, fn: () => Promise<T>, now?: () => number): Promise<{
+    kind: "ok";
+    value: T;
+} | {
+    kind: LockFailure;
+}>;

package/dist/oauth/lock.js

@@ -0,0 +1,287 @@
+/**
+ * Cross-process single-flight for the refresh grant.
+ *
+ * ## ⚠ WHY THIS FILE EXISTS AT ALL — read before simplifying it away
+ *
+ * `vibecommit-mcp/src/oauth/refresh.ts` implements refresh-token FAMILY rotation
+ * with application-layer reuse detection: presenting a token that already has a
+ * child row is treated as a replay and **revokes the ENTIRE FAMILY** with
+ * `revoked_reason = 'reuse_detected'`. There is a database-level guard behind it
+ * too — a partial unique index on `parent_token_id`, so of two concurrent
+ * rotations from the same tail exactly one INSERT wins and the loser's 23505 is
+ * *also* read as reuse.
+ *
+ * Two terminals running a read at the same moment present the same tail token.
+ * That is not an edge case; it is Tuesday. Without a lock, one of them wins, the
+ * other is classed a replay, and **the user is signed out of every machine at
+ * once** — from doing nothing but running the same command twice.
+ *
+ * So the mutual exclusion has to be BETWEEN PROCESSES. An in-process mutex, a
+ * module-level promise, an `async` queue — every in-memory construct is the
+ * wrong shape here, because the two racers are two separate `vibecommit`
+ * invocations that share nothing but a filesystem.
+ *
+ * ## The loser waits and RE-READS — it does not queue up to present the old token
+ *
+ * `withRefreshLock` gives its callback the lock, nothing more. The callback's
+ * first act must be to re-read the session from disk, because by the time a
+ * waiter acquires the lock the winner has already rotated and saved: the tail
+ * the waiter loaded BEFORE waiting is now the parent of a live row, and
+ * presenting it is precisely the replay this file exists to prevent. See
+ * `signin.ts`'s `authorizedAccessToken`, which is the only caller and is written
+ * in exactly that order.
+ *
+ * ## The stale timeout is DERIVED, not guessed
+ *
+ * A crashed holder must not wedge every future read, so a lock older than
+ * `STALE_MS` is reclaimable. That number is not a feel for how long things take:
+ * this project has already paid for one wall-clock guess (`CR-126`/D83 found a
+ * `setTimeout(..., 60)` that was a guess at boot duration, sitting between p50
+ * and p90 and firing ~14% of the time idle and ~28% under load).
+ *
+ * The holder does exactly ONE thing while holding this lock: a single POST to
+ * the token endpoint, and that POST is bounded by an `AbortController` at
+ * `REFRESH_REQUEST_TIMEOUT_MS`. So the longest a HEALTHY holder can hold the
+ * lock is that timeout plus the file I/O either side of it, and `STALE_MS` is
+ * that bound plus a margin — an arithmetic consequence of the operation it
+ * bounds, which means changing the request timeout moves it automatically
+ * rather than leaving a stale constant behind.
+ *
+ * Reclaiming too EARLY is the dangerous direction: it puts two processes into
+ * the refresh at once, which is the family revoke. Reclaiming too LATE only
+ * makes a rare recovery slower. The margin is therefore generous on purpose.
+ *
+ * Nothing is imported or copied from the closed core (D60 §D1a): what crossed
+ * the boundary is the RULE that concurrent rotation is a revoke, which is a
+ * behavioural contract this client must obey, not an implementation.
+ *
+ * @provenance vibecommit-mcp src/oauth/refresh.ts — family-rotation reuse-detection rule, retyped
+ */
+import { randomBytes } from "node:crypto";
+import { closeSync, linkSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { rootDir } from "../paths.js";
+/**
+ * The whole budget for one refresh POST. Also the ONLY thing done under the
+ * lock, which is what makes `STALE_MS` below derivable.
+ */
+export const REFRESH_REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * When a lock is old enough to be a corpse rather than a holder.
+ *
+ * `REFRESH_REQUEST_TIMEOUT_MS` bounds the healthy hold; the rest is margin for
+ * the read/write either side and for a machine under enough load that a process
+ * does not get scheduled promptly. Erring long is the cheap direction — see the
+ * module note.
+ */
+export const STALE_MS = REFRESH_REQUEST_TIMEOUT_MS + 5_000;
+/**
+ * How long a waiter waits before giving up.
+ *
+ * Strictly greater than `STALE_MS`: a waiter that gave up sooner would abandon a
+ * refresh that a perfectly healthy holder was still allowed to be running, and
+ * the user would see a spurious failure while the thing they needed was in
+ * flight one process over.
+ */
+export const WAIT_TIMEOUT_MS = STALE_MS + 2_000;
+/**
+ * Poll interval while waiting. Short enough that the handoff is imperceptible,
+ * long enough that waiting costs nothing: over a full 10s refresh this is a few
+ * hundred `readFileSync` calls on a file in the page cache.
+ */
+const POLL_MS = 20;
+/** One lock for the refresh grant. Sits beside the session it protects. */
+export function refreshLockPath(home) {
+    return join(rootDir(home), "refresh.lock");
+}
+const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+/**
+ * The lock's contents: enough to tell one holder from another, and nothing
+ * secret. Never a token — a lock file has looser handling than a credential
+ * file by nature (it is created and destroyed constantly) and is exactly the
+ * wrong place to put a bearer secret.
+ */
+function stamp() {
+    // The nonce is what makes the stamp an IDENTITY rather than a description.
+    // `releaseIfMine` compares these bytes to decide whether the lock on disk is
+    // still ours, and pids are recycled — so without it, "same pid, same
+    // millisecond" would be a (remote) way to delete somebody else's lock.
+    return JSON.stringify({
+        pid: process.pid,
+        at: Date.now(),
+        nonce: randomBytes(8).toString("hex"),
+    });
+}
+function heldSince(raw) {
+    try {
+        const at = JSON.parse(raw).at;
+        return typeof at === "number" ? at : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Try once to create the lock exclusively.
+ *
+ * `wx` is `O_CREAT | O_EXCL | O_WRONLY`, which the kernel makes atomic: of any
+ * number of processes calling this at the same instant, exactly one gets the
+ * file and the rest get EEXIST. That atomicity is the entire mutual exclusion —
+ * a "does it exist? then create it" pair would have a window between the two
+ * calls, and a window is all this needs to fail.
+ */
+function tryAcquire(path) {
+    const mine = stamp();
+    // ⚠ WRITE FIRST, PUBLISH SECOND — and this ordering is a BUG FIX, not style.
+    //
+    // The obvious implementation is `openSync(path, "wx")` then `writeFileSync`.
+    // That creates the lock EMPTY and fills it a moment later, and in that window
+    // a second process reads a zero-byte file. `heldSince` cannot date it, the
+    // wait loop's "an undatable lock was not written by this code, treat it as
+    // stale" branch fires, and the racer RECLAIMS A LOCK THAT WAS JUST TAKEN.
+    // Both processes then refresh, and the server revokes the family — the exact
+    // outcome this module exists to prevent, reached through the module itself.
+    //
+    // Measured, not theorised: the two-process case in `test/oauth-signin.test.ts`
+    // failed on 2 of 8 runs with the second child getting `expired`, which is the
+    // server's answer to a replayed token.
+    //
+    // `link()` is the fix because it is ATOMIC and it fails with EEXIST when the
+    // target exists. The temp file already holds the full stamp before the link
+    // publishes it, so the lock is never observable half-written. The temp name
+    // carries a random component as well as the pid: two processes must not
+    // collide on the staging file either.
+    const staging = `${path}.${process.pid}.${randomBytes(6).toString("hex")}`;
+    try {
+        // `wx` on the STAGING file also refuses to follow a symlink (`O_CREAT |
+        // O_EXCL`), so a pre-planted link cannot be written through.
+        const fd = openSync(staging, "wx", 0o600);
+        try {
+            writeFileSync(fd, mine);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return null;
+    }
+    try {
+        linkSync(staging, path);
+    }
+    catch {
+        // Somebody else holds it. Ours never became visible.
+        return null;
+    }
+    finally {
+        try {
+            unlinkSync(staging);
+        }
+        catch {
+            // The lock path keeps the inode alive; a stranded staging file is inert.
+        }
+    }
+    // Returned so the RELEASE can prove the lock it deletes is still ours.
+    return mine;
+}
+/**
+ * Reclaim a lock whose holder is gone.
+ *
+ * Compare-then-delete: the same bytes we saw when we judged it stale must still
+ * be there when we unlink. Without that a third process that acquired the lock
+ * in between would have it deleted out from under it.
+ *
+ * ⚠ Residual, stated rather than papered over: the compare and the unlink are
+ * not one atomic operation, so a sufficiently unlucky interleaving can still
+ * drop a fresh lock. Reaching it requires a process to crash mid-refresh, a
+ * second to wait out the full `STALE_MS`, and a third to acquire inside the
+ * microseconds between the re-read and the unlink. The cost of closing it
+ * properly is a directory-rename protocol, and this package's failure mode on
+ * that path is one avoidable re-sign-in, not data loss.
+ */
+function reclaimIfUnchanged(path, observed) {
+    try {
+        if (readFileSync(path, "utf8") !== observed)
+            return;
+        unlinkSync(path);
+    }
+    catch {
+        // Gone already, or not ours to remove. Either way the next acquire decides.
+    }
+}
+/**
+ * Release, but ONLY if the lock on disk is still the one we took.
+ *
+ * ⚠ `/cso` finding, HIGH, and it is the family revoke arriving by the back door.
+ * An unconditional `unlink` on release is wrong whenever a holder outlived
+ * `STALE_MS`: a waiter reclaims the stale lock and starts its own refresh, and
+ * then the original holder wakes up and deletes THAT lock — letting a third
+ * process in while the second is mid-rotation. Two live refreshes is exactly the
+ * replay the server reads as `reuse_detected`.
+ *
+ * The obvious objection is that a healthy holder cannot exceed `STALE_MS`,
+ * because its one request is bounded by an `AbortController` well inside it.
+ * True — and irrelevant. **A laptop that sleeps mid-refresh does exceed it**, and
+ * so does any process the scheduler or a debugger suspends. Wall-clock bounds
+ * hold for code, not for the machine underneath it.
+ *
+ * Same compare-then-delete as the reclaim above, and the same stated residual:
+ * the read and the unlink are not one atomic operation.
+ */
+function releaseIfMine(path, mine) {
+    try {
+        if (readFileSync(path, "utf8") !== mine)
+            return;
+        unlinkSync(path);
+    }
+    catch {
+        // Already gone. Nothing to undo.
+    }
+}
+/**
+ * Run `fn` with the refresh lock held.
+ *
+ * Returns `{ kind: "timeout" }` rather than throwing when the lock cannot be
+ * taken: the caller is a read verb, and a read that cannot refresh should tell
+ * the user what happened, not take an exception out of a lock file.
+ *
+ * The lock is released in a `finally`, so a throwing callback still frees it.
+ */
+export async function withRefreshLock(home, fn, now = Date.now) {
+    const path = refreshLockPath(home);
+    const deadline = now() + WAIT_TIMEOUT_MS;
+    let mine = tryAcquire(path);
+    while (mine === null) {
+        let raw;
+        try {
+            raw = readFileSync(path, "utf8");
+        }
+        catch {
+            // Released between our failed acquire and this read. Go straight round.
+            mine = tryAcquire(path);
+            continue;
+        }
+        const since = heldSince(raw);
+        // An unparseable or timestamp-less lock is treated as stale immediately: it
+        // was not written by this code, and waiting `STALE_MS` for a file nobody can
+        // date is waiting for nothing.
+        if (since === null || now() - since > STALE_MS) {
+            reclaimIfUnchanged(path, raw);
+            mine = tryAcquire(path);
+            continue;
+        }
+        if (now() >= deadline)
+            return { kind: "timeout" };
+        await sleep(POLL_MS);
+        mine = tryAcquire(path);
+    }
+    try {
+        return { kind: "ok", value: await fn() };
+    }
+    finally {
+        releaseIfMine(path, mine);
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/oauth/lock.js.map

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