@vibe-commit/capture 0.1.0

package/dist/oauth/loopback.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The one-shot loopback listener that catches the authorization redirect.
+ *
+ * ## ⚠ THE HOST IS THE LITERAL `127.0.0.1`, NEVER `localhost`
+ *
+ * The server's redirect-URI policy (`vibecommit-mcp/src/oauth/loopback.ts`,
+ * read for its RULE and not imported — closed source, D60 §D1a) accepts
+ * `http://127.0.0.1:<any port>` and `http://[::1]:<any port>` per RFC 8252 §7.3,
+ * and REJECTS the literal string `localhost` with `localhost_disallowed`,
+ * because DNS resolution of `localhost` is OS-configurable and could point at a
+ * different host. So `redirect_uri` is built from the literal below, and the
+ * socket is bound to that same literal.
+ *
+ * **A client that builds `http://localhost:<port>` fails in a way that looks
+ * like a config problem rather than a spelling one** — the browser round-trip
+ * works, the listener receives nothing, and the visible symptom is a hang. That
+ * is why `test/oauth-loopback.test.ts` asserts the host rather than asserting
+ * that the flow completes.
+ *
+ * ## What this listener refuses
+ *
+ * `state` (RFC 6749 §10.12) and `iss` (RFC 9207) are both checked, and a request
+ * failing either is answered 400 and **does not end the wait**. Ending the wait
+ * on a bad request would let anything able to reach the port cancel a sign-in;
+ * accepting it would be a CSRF hole with a green happy-path suite over it, which
+ * is the specific vacuity this task was briefed on.
+ *
+ * @provenance vibecommit-mcp src/oauth/loopback.ts — redirect-URI policy, retyped
+ * @provenance vibecommit-mcp src/transport/server.ts — the code+state+iss handoff, retyped
+ */
+/**
+ * The literal the server's policy admits. **Not a default — a requirement.**
+ * Changing this to `localhost` is refused by the authorization server.
+ */
+export declare const LOOPBACK_HOST = "127.0.0.1";
+/** The path the redirect lands on. Any path is legal; a fixed one is readable. */
+export declare const CALLBACK_PATH = "/callback";
+export type Callback = 
+/** The authorization code, with `state` and `iss` already verified. */
+{
+    readonly kind: "code";
+    readonly code: string;
+}
+/** The AS redirected with an OAuth error — `access_denied` when a user declines. */
+ | {
+    readonly kind: "denied";
+    readonly error: string;
+}
+/** The deadline passed with no acceptable callback. */
+ | {
+    readonly kind: "timeout";
+};
+export interface LoopbackOptions {
+    /** The exact `state` this attempt sent. */
+    readonly expectedState: string;
+    /**
+     * The issuer discovered from RFC 8414 metadata. RFC 9207 requires the
+     * authorization response to carry it, and D26 makes the comparison
+     * EXACT-STRING — scheme, host, apex-vs-www and trailing slash all count.
+     */
+    readonly expectedIssuer: string;
+    /** How long to wait before giving up. The browser round-trip includes a login. */
+    readonly deadlineMs: number;
+    /** What the browser tab shows. Copy lives in `src/copy/`, never here. */
+    readonly page: {
+        readonly done: string;
+        readonly refused: string;
+    };
+}
+export interface Loopback {
+    /** `http://127.0.0.1:<ephemeral>/callback` — presented as `redirect_uri`. */
+    readonly redirectUri: string;
+    /** Resolves once, on the first acceptable callback, a denial, or the deadline. */
+    readonly result: Promise<Callback>;
+    /** Idempotent. Always call it — a listening socket outliving the flow is a bug. */
+    close(): void;
+}
+/**
+ * Bind an ephemeral loopback port and wait for one authorization redirect.
+ *
+ * Port 0 rather than a fixed port: RFC 8252 §7.3 requires the AS to accept any
+ * port on the loopback for exactly this reason, and a fixed port collides with a
+ * second terminal and with whatever else on the machine wanted it.
+ */
+export declare function listenForCallback(opts: LoopbackOptions): Promise<Loopback>;

package/dist/oauth/loopback.js

@@ -0,0 +1,124 @@
+/**
+ * The one-shot loopback listener that catches the authorization redirect.
+ *
+ * ## ⚠ THE HOST IS THE LITERAL `127.0.0.1`, NEVER `localhost`
+ *
+ * The server's redirect-URI policy (`vibecommit-mcp/src/oauth/loopback.ts`,
+ * read for its RULE and not imported — closed source, D60 §D1a) accepts
+ * `http://127.0.0.1:<any port>` and `http://[::1]:<any port>` per RFC 8252 §7.3,
+ * and REJECTS the literal string `localhost` with `localhost_disallowed`,
+ * because DNS resolution of `localhost` is OS-configurable and could point at a
+ * different host. So `redirect_uri` is built from the literal below, and the
+ * socket is bound to that same literal.
+ *
+ * **A client that builds `http://localhost:<port>` fails in a way that looks
+ * like a config problem rather than a spelling one** — the browser round-trip
+ * works, the listener receives nothing, and the visible symptom is a hang. That
+ * is why `test/oauth-loopback.test.ts` asserts the host rather than asserting
+ * that the flow completes.
+ *
+ * ## What this listener refuses
+ *
+ * `state` (RFC 6749 §10.12) and `iss` (RFC 9207) are both checked, and a request
+ * failing either is answered 400 and **does not end the wait**. Ending the wait
+ * on a bad request would let anything able to reach the port cancel a sign-in;
+ * accepting it would be a CSRF hole with a green happy-path suite over it, which
+ * is the specific vacuity this task was briefed on.
+ *
+ * @provenance vibecommit-mcp src/oauth/loopback.ts — redirect-URI policy, retyped
+ * @provenance vibecommit-mcp src/transport/server.ts — the code+state+iss handoff, retyped
+ */
+import { createServer } from "node:http";
+import { statesMatch } from "./pkce.js";
+/**
+ * The literal the server's policy admits. **Not a default — a requirement.**
+ * Changing this to `localhost` is refused by the authorization server.
+ */
+export const LOOPBACK_HOST = "127.0.0.1";
+/** The path the redirect lands on. Any path is legal; a fixed one is readable. */
+export const CALLBACK_PATH = "/callback";
+/**
+ * Bind an ephemeral loopback port and wait for one authorization redirect.
+ *
+ * Port 0 rather than a fixed port: RFC 8252 §7.3 requires the AS to accept any
+ * port on the loopback for exactly this reason, and a fixed port collides with a
+ * second terminal and with whatever else on the machine wanted it.
+ */
+export async function listenForCallback(opts) {
+    let settle;
+    const result = new Promise((resolve) => {
+        settle = resolve;
+    });
+    const server = createServer((req, res) => {
+        // `req.url` is a path with a query, so it needs a base to parse. The base is
+        // this listener's own address and is never used for anything else.
+        const url = new URL(req.url ?? "/", `http://${LOOPBACK_HOST}`);
+        const verdict = classify(url.searchParams, opts);
+        if (verdict === null) {
+            // Neither acceptable nor a recognised denial: answer, and keep waiting.
+            // A stray request must not be able to cancel somebody's sign-in.
+            res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+            res.end(opts.page.refused);
+            return;
+        }
+        res.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+        res.end(verdict.kind === "code" ? opts.page.done : opts.page.refused);
+        finish(verdict);
+    });
+    const timer = setTimeout(() => finish({ kind: "timeout" }), opts.deadlineMs);
+    // The deadline must not by itself hold the process open — the flow is awaited
+    // elsewhere, and a stray timer keeping Node alive after a `close()` is the
+    // same class of bug as the socket this module is careful to shut.
+    timer.unref();
+    let closed = false;
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        clearTimeout(timer);
+        // ⚠ `close()` alone waits for KEEP-ALIVE sockets to go idle, and a browser
+        // holds one open after the tab renders. Without this the CLI sits there with
+        // the code already exchanged, which reads to a user as a hang at the last
+        // step. `closeAllConnections` is why the listener actually goes away.
+        server.closeAllConnections();
+        server.close();
+    };
+    const finish = (value) => {
+        close();
+        settle(value);
+    };
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        // The LITERAL, both here and in the redirect_uri below. See the module note.
+        server.listen(0, LOOPBACK_HOST, resolve);
+    });
+    const { port } = server.address();
+    return { redirectUri: `http://${LOOPBACK_HOST}:${port}${CALLBACK_PATH}`, result, close };
+}
+/**
+ * Decide what one inbound request is: the callback, a denial, or noise.
+ *
+ * Null means "not this attempt's callback" — the caller keeps waiting. The
+ * ORDER matters: `state` is checked before anything is read out of the query,
+ * so an unauthenticated caller cannot use the `error` branch to end a wait it
+ * does not own.
+ */
+function classify(params, opts) {
+    const state = params.get("state");
+    if (state === null || !statesMatch(opts.expectedState, state))
+        return null;
+    // RFC 9207 issuer identification, D26's exact-string match. Applied to the
+    // ERROR redirect too: a mix-up attack is not less of one because the response
+    // it forged happens to be a refusal.
+    const iss = params.get("iss");
+    if (iss !== opts.expectedIssuer)
+        return null;
+    const error = params.get("error");
+    if (error !== null && error !== "")
+        return { kind: "denied", error };
+    const code = params.get("code");
+    if (code === null || code === "")
+        return null;
+    return { kind: "code", code };
+}
+//# sourceMappingURL=loopback.js.map

package/dist/oauth/loopback.js.map

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

package/dist/oauth/pkce.d.ts

@@ -0,0 +1,58 @@
+/**
+ * PKCE (RFC 7636) and the authorization-request `state` — `CR-084d`.
+ *
+ * Two secrets are minted here and both are one-shot: the `code_verifier`, which
+ * is what stops an attacker who steals the authorization code from exchanging
+ * it, and `state`, which is what stops an attacker who can reach the loopback
+ * listener from injecting THEIR code into OUR flow.
+ *
+ * **`S256` is the only method, and it is a TYPE and not a default.** The server
+ * advertises `code_challenge_methods_supported: ["S256"]` and rejects `plain`
+ * (its `verifyPkce` recomputes the SHA-256 unconditionally), so a client that
+ * downgraded would not be refused by an obvious error — it would send a
+ * challenge the server hashes anyway and fail as `invalid_grant`, which reads as
+ * a config problem. Making the literal the field's type means the downgrade
+ * cannot compile, and `test/oauth-pkce.test.ts` proves the challenge really is
+ * the digest rather than the verifier copied across.
+ *
+ * @provenance vibecommit-mcp src/oauth/token.ts — `verifyPkce` base64url-of-SHA-256 rule, retyped
+ * @provenance vibecommit-mcp src/oauth/discovery.ts — `code_challenge_methods_supported`, retyped
+ */
+/**
+ * The one supported challenge method. Declared `const` so it is a literal type:
+ * `method: "S256"` cannot be assigned `"plain"` anywhere downstream.
+ */
+export declare const CHALLENGE_METHOD: "S256";
+export type ChallengeMethod = typeof CHALLENGE_METHOD;
+export interface PkcePair {
+    /** Secret. Sent ONLY to the token endpoint, never on the authorize URL. */
+    readonly verifier: string;
+    /** Public. Sent on the authorize URL; safe to log. */
+    readonly challenge: string;
+    readonly method: ChallengeMethod;
+}
+/** RFC 4648 §5 base64url, unpadded — the encoding both ends of PKCE use. */
+export declare function base64url(bytes: Buffer): string;
+/**
+ * Mint a fresh verifier and its challenge.
+ *
+ * `randomBytes` and not `Math.random`: this is the value an attacker must guess
+ * to exchange a stolen code, so it comes from the CSPRNG or it is decoration.
+ */
+export declare function generatePkce(): PkcePair;
+/** base64url(SHA-256(verifier)) — the server recomputes exactly this. */
+export declare function challengeFor(verifier: string): string;
+/** A fresh per-attempt `state`. Never reused across sign-ins. */
+export declare function generateState(): string;
+/**
+ * Compare two `state` values without leaking the position of the first
+ * difference.
+ *
+ * The timing channel here is thin — an attacker would need many attempts against
+ * a listener that closes after one — but the comparison is one line either way,
+ * and `===` on a secret is the habit that matters. Lengths are compared first
+ * because `timingSafeEqual` THROWS on a length mismatch rather than returning
+ * false, which would turn a wrong-length callback into an unhandled exception on
+ * the sign-in path.
+ */
+export declare function statesMatch(expected: string, presented: string): boolean;

package/dist/oauth/pkce.js

@@ -0,0 +1,77 @@
+/**
+ * PKCE (RFC 7636) and the authorization-request `state` — `CR-084d`.
+ *
+ * Two secrets are minted here and both are one-shot: the `code_verifier`, which
+ * is what stops an attacker who steals the authorization code from exchanging
+ * it, and `state`, which is what stops an attacker who can reach the loopback
+ * listener from injecting THEIR code into OUR flow.
+ *
+ * **`S256` is the only method, and it is a TYPE and not a default.** The server
+ * advertises `code_challenge_methods_supported: ["S256"]` and rejects `plain`
+ * (its `verifyPkce` recomputes the SHA-256 unconditionally), so a client that
+ * downgraded would not be refused by an obvious error — it would send a
+ * challenge the server hashes anyway and fail as `invalid_grant`, which reads as
+ * a config problem. Making the literal the field's type means the downgrade
+ * cannot compile, and `test/oauth-pkce.test.ts` proves the challenge really is
+ * the digest rather than the verifier copied across.
+ *
+ * @provenance vibecommit-mcp src/oauth/token.ts — `verifyPkce` base64url-of-SHA-256 rule, retyped
+ * @provenance vibecommit-mcp src/oauth/discovery.ts — `code_challenge_methods_supported`, retyped
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+/**
+ * The one supported challenge method. Declared `const` so it is a literal type:
+ * `method: "S256"` cannot be assigned `"plain"` anywhere downstream.
+ */
+export const CHALLENGE_METHOD = "S256";
+/**
+ * 32 random bytes, which base64url-encode to exactly 43 characters — the FLOOR
+ * of RFC 7636 §4.1's 43..128 range, and the server enforces that range verbatim
+ * (`codeVerifier.length < 43 || > 128` → PKCE mismatch). 32 bytes is also the
+ * size the digest itself is, so a longer verifier buys no entropy the challenge
+ * can carry.
+ */
+const VERIFIER_BYTES = 32;
+/** `state` needs unguessability, not length. 32 bytes matches the verifier. */
+const STATE_BYTES = 32;
+/** RFC 4648 §5 base64url, unpadded — the encoding both ends of PKCE use. */
+export function base64url(bytes) {
+    return bytes.toString("base64").replace(/=+$/, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+/**
+ * Mint a fresh verifier and its challenge.
+ *
+ * `randomBytes` and not `Math.random`: this is the value an attacker must guess
+ * to exchange a stolen code, so it comes from the CSPRNG or it is decoration.
+ */
+export function generatePkce() {
+    const verifier = base64url(randomBytes(VERIFIER_BYTES));
+    return { verifier, challenge: challengeFor(verifier), method: CHALLENGE_METHOD };
+}
+/** base64url(SHA-256(verifier)) — the server recomputes exactly this. */
+export function challengeFor(verifier) {
+    return base64url(createHash("sha256").update(verifier).digest());
+}
+/** A fresh per-attempt `state`. Never reused across sign-ins. */
+export function generateState() {
+    return base64url(randomBytes(STATE_BYTES));
+}
+/**
+ * Compare two `state` values without leaking the position of the first
+ * difference.
+ *
+ * The timing channel here is thin — an attacker would need many attempts against
+ * a listener that closes after one — but the comparison is one line either way,
+ * and `===` on a secret is the habit that matters. Lengths are compared first
+ * because `timingSafeEqual` THROWS on a length mismatch rather than returning
+ * false, which would turn a wrong-length callback into an unhandled exception on
+ * the sign-in path.
+ */
+export function statesMatch(expected, presented) {
+    const a = Buffer.from(expected, "utf8");
+    const b = Buffer.from(presented, "utf8");
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+//# sourceMappingURL=pkce.js.map

package/dist/oauth/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../../src/oauth/pkce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEvE;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAe,CAAC;AAGhD;;;;;;GAMG;AACH,MAAM,cAAc,GAAG,EAAE,CAAC;AAE1B,+EAA+E;AAC/E,MAAM,WAAW,GAAG,EAAE,CAAC;AAUvB,4EAA4E;AAC5E,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAC7F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,QAAQ,GAAG,SAAS,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC;IACxD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;AACnF,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,OAAO,SAAS,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AACnE,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,aAAa;IAC3B,OAAO,SAAS,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,SAAiB;IAC7D,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC"}

package/dist/oauth/read.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The read transport: ONE `tools/call` POST to the EXISTING `/mcp` endpoint.
+ *
+ * ## What this is not
+ *
+ * There is no REST `/read` route, no second Fly app, no second hostname and no
+ * second PRM document (D73, which closed `CR-083` as unnecessary and recorded
+ * the "2nd Fly app (read lane)" provisioning item as CLOSED — NOT NEEDED). A
+ * read is the same endpoint the agent already talks to, with a user-principal
+ * bearer instead of a machine one.
+ *
+ * There is also no third audience set. The access token is minted at
+ * `mcpAcceptedAudiences`, which is typed `readonly [string]` and populated as a
+ * ONE-element tuple. `readAcceptedAudiences` is GONE — `CR-084b` deleted it
+ * (merged after this client was written, re-verified against it), and the claim
+ * it encoded (that a machine credential can read) was false as built anyway: a
+ * `vcik_` is opaque base64url with no dots, so the JWT verifier rejects it
+ * before any audience check runs.
+ *
+ * ## The envelope
+ *
+ * A successful `tools/call` returns `result.content[0].text` carrying a JSON
+ * DOCUMENT — every tool in the server ends
+ * `{ content: [{ type: "text", text: JSON.stringify(payload) }] }`. So the
+ * caller parses that string; it does not read a typed result off the JSON-RPC
+ * envelope directly.
+ *
+ * ⚠ A tool's OWN failures travel the same way — one text part with a JSON body,
+ * plus `isError: true`. They are not JSON-RPC errors and not HTTP errors, and a
+ * caller that only branched on the transport would read one as success. So
+ * `document` is returned uninterpreted with `isError` beside it: parse ONCE,
+ * branch after, which is exactly what the server's seam says this client does.
+ *
+ * `CR-084b` pins both forms with a golden test and names this client as the
+ * envelope's external consumer, so the shape is a contract with an owner rather
+ * than a convention that happens to hold.
+ *
+ * @provenance vibecommit-mcp src/handshake/router.ts — JSON-RPC methods, retyped
+ * @provenance vibecommit-mcp src/handshake/tools.ts — `tools/call` params, retyped
+ * @provenance vibecommit-mcp src/read/envelope.ts — `content[0].text` envelope, retyped
+ *
+ * ⚠ THAT THIRD CITATION WAS RE-POINTED, NOT ADDED (`CR-163`, D136 §2). It named
+ * `src/tools/query_history.ts`, and **no such file exists**: `query_history` was
+ * retired by `CR-076b` and now has an entry in `vibecommit-mcp/src/tools/
+ * retired.ts` that returns a migration error. A dangling citation is worse than
+ * none (D54) — it points a reader at a file they cannot open and stops them
+ * looking further.
+ *
+ * ⚠ AND THE TAG NAME IS NOT SPELLED OUT IN PROSE ANYWHERE BELOW THIS LINE.
+ * `test/provenance.test.ts` counts the tags in this file by scanning for the
+ * literal token, so writing it inside a sentence adds a fourth "tag" that cannot
+ * parse and turns the gate RED against correct prose. It did, on the first
+ * wording of this note. Same species as the linkage wall reading `from` plus a
+ * quoted phrase as an import — see `src/json.ts` and `src/commands/why.ts`.
+ *
+ * The envelope is still real and still has a source: `readEnvelope()` in
+ * `vibecommit-mcp/src/read/envelope.ts` is the single function that builds
+ * `{ content: [{ type: "text", text: JSON.stringify(payload) }] }`, and
+ * `readErrorEnvelope()` beside it builds the `isError` form. Both live read
+ * tools return them — verified 2026-08-16 against `vibecommit-mcp` `main`:
+ * `src/tools/blame_commit.ts` and `src/tools/commit_coverage.ts` each import
+ * from that module and return it. The citation is MUTUAL: that file names this
+ * client as the envelope's external consumer by name.
+ */
+import type { AccessToken } from "../credential.js";
+export type ReadOutcome = 
+/**
+ * `content[0].text`, JSON-parsed.
+ *
+ * `isError` is MCP's flag for a failed call and is part of the SAME envelope:
+ * the error form carries one text part with a JSON body, plus `isError: true`.
+ * That is what lets this client `JSON.parse` ONCE and branch afterwards,
+ * rather than needing to know which shape it is about to receive.
+ *
+ * ⚠ Surfaced rather than dropped because it is a documented field of a
+ * contract with an external owner. `document` alone would still carry
+ * `{ error, detail }`, so a caller COULD infer the failure by sniffing for an
+ * `error` key — and inferring a fact the wire states outright is how a caller
+ * ends up treating a legitimate payload that has an `error` field as a failure.
+ */
+{
+    readonly kind: "ok";
+    readonly document: unknown;
+    readonly isError: boolean;
+}
+/**
+ * The bearer was rejected. A FIRST-CLASS OUTCOME so the caller can refresh
+ * ONCE and retry ONCE — never in a loop. A loop here would present a rotated
+ * refresh token repeatedly and end in a family revoke, which is a signed-out
+ * user produced by the error handling rather than by the error.
+ */
+ | {
+    readonly kind: "unauthorized";
+}
+/** A JSON-RPC error object. Data, not an exception (`CR-084d` scope). */
+ | {
+    readonly kind: "rpc-error";
+    readonly code: number;
+    readonly message: string;
+}
+/** No response at all — DNS, refused, TLS, timeout. */
+ | {
+    readonly kind: "unreachable";
+}
+/** A 200 whose body is not the envelope. Never treated as success. */
+ | {
+    readonly kind: "malformed";
+};
+export interface ReadDeps {
+    readonly fetch: typeof fetch;
+    readonly timeoutMs: number;
+}
+/**
+ * Call one read tool.
+ *
+ * `id` is fixed at 1: this is a single request/response over a fresh connection
+ * with no batching and no notifications, so a counter would be state kept for
+ * nobody. The server echoes it and nothing correlates on it.
+ */
+export declare function callTool(mcpEndpoint: string, access: AccessToken, name: string, args: Record<string, unknown>, deps: ReadDeps): Promise<ReadOutcome>;

package/dist/oauth/read.js

@@ -0,0 +1,144 @@
+/**
+ * The read transport: ONE `tools/call` POST to the EXISTING `/mcp` endpoint.
+ *
+ * ## What this is not
+ *
+ * There is no REST `/read` route, no second Fly app, no second hostname and no
+ * second PRM document (D73, which closed `CR-083` as unnecessary and recorded
+ * the "2nd Fly app (read lane)" provisioning item as CLOSED — NOT NEEDED). A
+ * read is the same endpoint the agent already talks to, with a user-principal
+ * bearer instead of a machine one.
+ *
+ * There is also no third audience set. The access token is minted at
+ * `mcpAcceptedAudiences`, which is typed `readonly [string]` and populated as a
+ * ONE-element tuple. `readAcceptedAudiences` is GONE — `CR-084b` deleted it
+ * (merged after this client was written, re-verified against it), and the claim
+ * it encoded (that a machine credential can read) was false as built anyway: a
+ * `vcik_` is opaque base64url with no dots, so the JWT verifier rejects it
+ * before any audience check runs.
+ *
+ * ## The envelope
+ *
+ * A successful `tools/call` returns `result.content[0].text` carrying a JSON
+ * DOCUMENT — every tool in the server ends
+ * `{ content: [{ type: "text", text: JSON.stringify(payload) }] }`. So the
+ * caller parses that string; it does not read a typed result off the JSON-RPC
+ * envelope directly.
+ *
+ * ⚠ A tool's OWN failures travel the same way — one text part with a JSON body,
+ * plus `isError: true`. They are not JSON-RPC errors and not HTTP errors, and a
+ * caller that only branched on the transport would read one as success. So
+ * `document` is returned uninterpreted with `isError` beside it: parse ONCE,
+ * branch after, which is exactly what the server's seam says this client does.
+ *
+ * `CR-084b` pins both forms with a golden test and names this client as the
+ * envelope's external consumer, so the shape is a contract with an owner rather
+ * than a convention that happens to hold.
+ *
+ * @provenance vibecommit-mcp src/handshake/router.ts — JSON-RPC methods, retyped
+ * @provenance vibecommit-mcp src/handshake/tools.ts — `tools/call` params, retyped
+ * @provenance vibecommit-mcp src/read/envelope.ts — `content[0].text` envelope, retyped
+ *
+ * ⚠ THAT THIRD CITATION WAS RE-POINTED, NOT ADDED (`CR-163`, D136 §2). It named
+ * `src/tools/query_history.ts`, and **no such file exists**: `query_history` was
+ * retired by `CR-076b` and now has an entry in `vibecommit-mcp/src/tools/
+ * retired.ts` that returns a migration error. A dangling citation is worse than
+ * none (D54) — it points a reader at a file they cannot open and stops them
+ * looking further.
+ *
+ * ⚠ AND THE TAG NAME IS NOT SPELLED OUT IN PROSE ANYWHERE BELOW THIS LINE.
+ * `test/provenance.test.ts` counts the tags in this file by scanning for the
+ * literal token, so writing it inside a sentence adds a fourth "tag" that cannot
+ * parse and turns the gate RED against correct prose. It did, on the first
+ * wording of this note. Same species as the linkage wall reading `from` plus a
+ * quoted phrase as an import — see `src/json.ts` and `src/commands/why.ts`.
+ *
+ * The envelope is still real and still has a source: `readEnvelope()` in
+ * `vibecommit-mcp/src/read/envelope.ts` is the single function that builds
+ * `{ content: [{ type: "text", text: JSON.stringify(payload) }] }`, and
+ * `readErrorEnvelope()` beside it builds the `isError` form. Both live read
+ * tools return them — verified 2026-08-16 against `vibecommit-mcp` `main`:
+ * `src/tools/blame_commit.ts` and `src/tools/commit_coverage.ts` each import
+ * from that module and return it. The citation is MUTUAL: that file names this
+ * client as the envelope's external consumer by name.
+ */
+/** JSON-RPC 2.0. The server rejects anything else at `validateRequest`. */
+const JSONRPC_VERSION = "2.0";
+/**
+ * Call one read tool.
+ *
+ * `id` is fixed at 1: this is a single request/response over a fresh connection
+ * with no batching and no notifications, so a counter would be state kept for
+ * nobody. The server echoes it and nothing correlates on it.
+ */
+export async function callTool(mcpEndpoint, access, name, args, deps) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.timeoutMs);
+    let res;
+    try {
+        res = await deps.fetch(mcpEndpoint, {
+            method: "POST",
+            headers: {
+                // The one place this token's plaintext is used — the request boundary,
+                // the same discipline `post.ts` states for the ingest credential.
+                authorization: `Bearer ${access.expose()}`,
+                "content-type": "application/json",
+                accept: "application/json",
+            },
+            body: JSON.stringify({
+                jsonrpc: JSONRPC_VERSION,
+                id: 1,
+                method: "tools/call",
+                params: { name, arguments: args },
+            }),
+            signal: controller.signal,
+            // undici strips Authorization across origins, so a followed redirect would
+            // arrive unauthenticated and read as a mysterious 401 — and one that did
+            // NOT cross origins would carry the bearer somewhere unconfigured.
+            redirect: "error",
+        });
+    }
+    catch {
+        return { kind: "unreachable" };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (res.status === 401)
+        return { kind: "unauthorized" };
+    let body;
+    try {
+        body = (await res.json());
+    }
+    catch {
+        return { kind: "malformed" };
+    }
+    const envelope = body;
+    if (envelope.error !== undefined && envelope.error !== null) {
+        const { code, message } = envelope.error;
+        return {
+            kind: "rpc-error",
+            code: typeof code === "number" ? code : 0,
+            message: typeof message === "string" ? message : "",
+        };
+    }
+    const content = envelope.result?.content;
+    if (!Array.isArray(content) || content.length === 0)
+        return { kind: "malformed" };
+    const text = content[0].text;
+    if (typeof text !== "string")
+        return { kind: "malformed" };
+    try {
+        return {
+            kind: "ok",
+            document: JSON.parse(text),
+            // Strictly `=== true`: the field is OPTIONAL on the wire, so an absent one
+            // must read as "not an error" rather than as anything truthy-ish.
+            isError: envelope.result?.isError === true,
+        };
+    }
+    catch {
+        return { kind: "malformed" };
+    }
+}
+//# sourceMappingURL=read.js.map

package/dist/oauth/read.js.map

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