@vibe-commit/capture 0.1.0

package/dist/oauth/token.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The `/oauth/token` client — both grants.
+ *
+ * RFC 6749 §4.1.3 (`authorization_code`) and §6 (`refresh_token`), posted
+ * form-encoded, which is the shape the server prefers and parses first. No
+ * client secret: this is a PUBLIC client (the server advertises
+ * `token_endpoint_auth_methods_supported: ["none"]`), and a secret shipped
+ * inside a CLI on a developer's disk is not a secret.
+ *
+ * ## ⚠ THE CLIENT ID IS NOT REGISTERED SERVER-SIDE YET
+ *
+ * `vibecommit-mcp`'s `REGISTERED_CLIENT_IDS` is a hard-coded membership set
+ * (RFC 7591 dynamic registration is deferred) holding ten entries — `claude-ai`,
+ * `cursor-mcp`, `vscode-copilot`, `codex-cli`, `windsurf-mcp`, `cline`,
+ * `continue-dev`, `roo-code`, `kiro`, `mcp-inspector` — and **none of them is
+ * this CLI**. `isRegisteredClient` gates BOTH `/oauth/authorize` and
+ * `/oauth/token`, so against the live server every sign-in below returns
+ * `unauthorized_client` until `CLIENT_ID` below is added to that list.
+ *
+ * That is a one-line server-side change in another repo, and it is REPORTED
+ * rather than worked around: the two alternatives are both worse. Borrowing
+ * `mcp-inspector` would ship a dev/testing identity in a released binary, and
+ * borrowing `claude-ai` would make this client indistinguishable from Claude
+ * Code in the audit trail of a product whose entire value is an audit trail.
+ *
+ * One constant, named, so the registration is a one-line change on this side too.
+ *
+ * ⚠ AND THE NAME IS `capture-cli` RATHER THAN THE OBVIOUS PRODUCT-PREFIXED ONE.
+ * Every sibling repo in this project is named with that product prefix, and
+ * `test/provenance.test.ts`'s `REPO_TOKEN` matches exactly that shape to find
+ * closed-core references — so a client id built the obvious way is read by the
+ * licensing gate as a reference to a closed sibling repo that does not exist.
+ * The collision is a real signal rather than a tooling annoyance: an OAuth
+ * client id indistinguishable from a repository name is ambiguous to a human
+ * reader too. `capture-cli` names the package (`@vibe-commit/capture`) and
+ * matches the server's own convention for the ids beside it (`codex-cli`).
+ *
+ * @provenance vibecommit-mcp src/oauth/token.ts — both grants, request + response shapes, retyped
+ * @provenance vibecommit-mcp src/transport/server.ts — form-encoded body parse, retyped
+ * @provenance vibecommit-mcp src/db/supabase.ts — the registered-client gate, retyped
+ */
+import { AccessToken, RefreshToken } from "../credential.js";
+/** This CLI's OAuth client identity. ⚠ Not yet in the server's set — see above. */
+export declare const CLIENT_ID = "capture-cli";
+/** The only scope the server registers. */
+export declare const SCOPE = "mcp:tools";
+/**
+ * Refresh this many milliseconds BEFORE the access token actually expires.
+ *
+ * Without a margin, a read starting at t=899s on a 900s token races its own
+ * round trip and fails with a 401 it could have avoided. 60s comfortably exceeds
+ * both the request budget and any plausible clock disagreement between this
+ * machine and the issuer, and costs one extra refresh per 15 minutes of
+ * continuous use.
+ */
+export declare const EXPIRY_SKEW_MS = 60000;
+/** A live token pair, both halves opaque, with the expiry carried as DATA. */
+export interface TokenSet {
+    readonly access: AccessToken;
+    readonly refresh: RefreshToken;
+    /** Epoch ms. From `expires_in`, never from parsing the JWT — see `AccessToken`. */
+    readonly expiresAtMs: number;
+    readonly scope: string;
+}
+export type TokenOutcome = {
+    readonly kind: "ok";
+    readonly tokens: TokenSet;
+}
+/**
+ * The server answered with an RFC 6749 §5.2 error. A FIRST-CLASS OUTCOME and
+ * not an exception: `invalid_grant` on the refresh path is the ordinary way a
+ * user learns their session ended, and `unauthorized_client` is how this
+ * client will learn its id was never registered.
+ */
+ | {
+    readonly kind: "denied";
+    readonly error: string;
+}
+/** No response at all — DNS, refused, TLS, timeout. Not an HTTP status. */
+ | {
+    readonly kind: "unreachable";
+}
+/** A 2xx whose body is not a token response. Never treated as success. */
+ | {
+    readonly kind: "malformed";
+};
+export interface TokenDeps {
+    readonly fetch: typeof fetch;
+    readonly timeoutMs: number;
+    /** Epoch ms. Injected so the expiry arithmetic is reachable from a test. */
+    readonly nowMs: number;
+}
+/**
+ * Turn a token response into two opaque tokens, or refuse it.
+ *
+ * ⚠ Both halves are CLASS-CHECKED before they are wrapped, and this is the
+ * mirror of the ingest lane's `wrong-class` refusal rather than belt-and-braces.
+ * A response that put the JWT in `refresh_token` would otherwise be stored and
+ * then presented to the refresh grant on every subsequent read, and the symptom
+ * — `invalid_grant`, a signed-out user — names neither the cause nor the field.
+ * Refusing at the boundary makes the fault land where it happened.
+ *
+ * Exported so a test can drive known-bad bodies at it without a socket.
+ */
+export declare function parseTokenResponse(body: unknown, nowMs: number): TokenOutcome;
+/**
+ * `grant_type=authorization_code`.
+ *
+ * `redirect_uri` is sent again and MUST be byte-identical to the one presented
+ * at authorize — the server compares them (`candidate.redirect_uri !==
+ * input.redirectUri` → `invalid_grant`). That is the second place the
+ * `127.0.0.1`-vs-`localhost` spelling decides whether this works.
+ */
+export declare function exchangeCode(tokenEndpoint: string, input: {
+    code: string;
+    codeVerifier: string;
+    redirectUri: string;
+}, deps: TokenDeps): Promise<TokenOutcome>;
+/**
+ * `grant_type=refresh_token` — rotation. The response carries a NEW refresh
+ * token and the old one is dead the instant this succeeds.
+ *
+ * ⚠ CALL THIS ONLY UNDER `withRefreshLock`. Presenting a token that has already
+ * been rotated revokes the whole family server-side. `lock.ts`'s module note is
+ * the long version; this is the line that stops a reader wiring it up directly.
+ */
+export declare function refreshGrant(tokenEndpoint: string, refresh: RefreshToken, deps: TokenDeps): Promise<TokenOutcome>;
+/**
+ * The authorize URL, built from the DISCOVERED endpoint.
+ *
+ * Every parameter is appended to whatever query the discovered endpoint already
+ * carries rather than replacing it: the authorize UI lives in another repo on
+ * another host and may legitimately carry its own.
+ */
+export declare function buildAuthorizeUrl(authorizationEndpoint: string, input: {
+    challenge: string;
+    state: string;
+    redirectUri: string;
+}): string;

package/dist/oauth/token.js

@@ -0,0 +1,183 @@
+/**
+ * The `/oauth/token` client — both grants.
+ *
+ * RFC 6749 §4.1.3 (`authorization_code`) and §6 (`refresh_token`), posted
+ * form-encoded, which is the shape the server prefers and parses first. No
+ * client secret: this is a PUBLIC client (the server advertises
+ * `token_endpoint_auth_methods_supported: ["none"]`), and a secret shipped
+ * inside a CLI on a developer's disk is not a secret.
+ *
+ * ## ⚠ THE CLIENT ID IS NOT REGISTERED SERVER-SIDE YET
+ *
+ * `vibecommit-mcp`'s `REGISTERED_CLIENT_IDS` is a hard-coded membership set
+ * (RFC 7591 dynamic registration is deferred) holding ten entries — `claude-ai`,
+ * `cursor-mcp`, `vscode-copilot`, `codex-cli`, `windsurf-mcp`, `cline`,
+ * `continue-dev`, `roo-code`, `kiro`, `mcp-inspector` — and **none of them is
+ * this CLI**. `isRegisteredClient` gates BOTH `/oauth/authorize` and
+ * `/oauth/token`, so against the live server every sign-in below returns
+ * `unauthorized_client` until `CLIENT_ID` below is added to that list.
+ *
+ * That is a one-line server-side change in another repo, and it is REPORTED
+ * rather than worked around: the two alternatives are both worse. Borrowing
+ * `mcp-inspector` would ship a dev/testing identity in a released binary, and
+ * borrowing `claude-ai` would make this client indistinguishable from Claude
+ * Code in the audit trail of a product whose entire value is an audit trail.
+ *
+ * One constant, named, so the registration is a one-line change on this side too.
+ *
+ * ⚠ AND THE NAME IS `capture-cli` RATHER THAN THE OBVIOUS PRODUCT-PREFIXED ONE.
+ * Every sibling repo in this project is named with that product prefix, and
+ * `test/provenance.test.ts`'s `REPO_TOKEN` matches exactly that shape to find
+ * closed-core references — so a client id built the obvious way is read by the
+ * licensing gate as a reference to a closed sibling repo that does not exist.
+ * The collision is a real signal rather than a tooling annoyance: an OAuth
+ * client id indistinguishable from a repository name is ambiguous to a human
+ * reader too. `capture-cli` names the package (`@vibe-commit/capture`) and
+ * matches the server's own convention for the ids beside it (`codex-cli`).
+ *
+ * @provenance vibecommit-mcp src/oauth/token.ts — both grants, request + response shapes, retyped
+ * @provenance vibecommit-mcp src/transport/server.ts — form-encoded body parse, retyped
+ * @provenance vibecommit-mcp src/db/supabase.ts — the registered-client gate, retyped
+ */
+import { AccessToken, RefreshToken, isAccessTokenShape, isRefreshTokenShape } from "../credential.js";
+import { CHALLENGE_METHOD } from "./pkce.js";
+/** This CLI's OAuth client identity. ⚠ Not yet in the server's set — see above. */
+export const CLIENT_ID = "capture-cli";
+/** The only scope the server registers. */
+export const SCOPE = "mcp:tools";
+/**
+ * Refresh this many milliseconds BEFORE the access token actually expires.
+ *
+ * Without a margin, a read starting at t=899s on a 900s token races its own
+ * round trip and fails with a 401 it could have avoided. 60s comfortably exceeds
+ * both the request budget and any plausible clock disagreement between this
+ * machine and the issuer, and costs one extra refresh per 15 minutes of
+ * continuous use.
+ */
+export const EXPIRY_SKEW_MS = 60_000;
+async function post(endpoint, form, deps) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.timeoutMs);
+    let res;
+    try {
+        res = await deps.fetch(endpoint, {
+            method: "POST",
+            headers: {
+                "content-type": "application/x-www-form-urlencoded",
+                accept: "application/json",
+            },
+            body: new URLSearchParams(form).toString(),
+            signal: controller.signal,
+            // This request carries the code verifier or the refresh token in its
+            // BODY. undici does not strip a body on redirect the way it strips an
+            // Authorization header, so following one would hand the secret to a hop
+            // the operator never configured. `post.ts` refuses redirects on the same
+            // lane for the same reason.
+            redirect: "error",
+        });
+    }
+    catch {
+        return { kind: "unreachable" };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    let body;
+    try {
+        body = (await res.json());
+    }
+    catch {
+        return { kind: "malformed" };
+    }
+    if (!res.ok) {
+        const error = body.error;
+        return { kind: "denied", error: typeof error === "string" ? error : "invalid_request" };
+    }
+    return parseTokenResponse(body, deps.nowMs);
+}
+/**
+ * Turn a token response into two opaque tokens, or refuse it.
+ *
+ * ⚠ Both halves are CLASS-CHECKED before they are wrapped, and this is the
+ * mirror of the ingest lane's `wrong-class` refusal rather than belt-and-braces.
+ * A response that put the JWT in `refresh_token` would otherwise be stored and
+ * then presented to the refresh grant on every subsequent read, and the symptom
+ * — `invalid_grant`, a signed-out user — names neither the cause nor the field.
+ * Refusing at the boundary makes the fault land where it happened.
+ *
+ * Exported so a test can drive known-bad bodies at it without a socket.
+ */
+export function parseTokenResponse(body, nowMs) {
+    const doc = body;
+    if (typeof doc.access_token !== "string" || !isAccessTokenShape(doc.access_token)) {
+        return { kind: "malformed" };
+    }
+    if (typeof doc.refresh_token !== "string" || !isRefreshTokenShape(doc.refresh_token)) {
+        return { kind: "malformed" };
+    }
+    if (typeof doc.expires_in !== "number" || !Number.isFinite(doc.expires_in)) {
+        return { kind: "malformed" };
+    }
+    return {
+        kind: "ok",
+        tokens: {
+            access: new AccessToken(doc.access_token),
+            refresh: new RefreshToken(doc.refresh_token),
+            expiresAtMs: nowMs + doc.expires_in * 1000,
+            scope: typeof doc.scope === "string" ? doc.scope : SCOPE,
+        },
+    };
+}
+/**
+ * `grant_type=authorization_code`.
+ *
+ * `redirect_uri` is sent again and MUST be byte-identical to the one presented
+ * at authorize — the server compares them (`candidate.redirect_uri !==
+ * input.redirectUri` → `invalid_grant`). That is the second place the
+ * `127.0.0.1`-vs-`localhost` spelling decides whether this works.
+ */
+export async function exchangeCode(tokenEndpoint, input, deps) {
+    return await post(tokenEndpoint, {
+        grant_type: "authorization_code",
+        client_id: CLIENT_ID,
+        code: input.code,
+        code_verifier: input.codeVerifier,
+        redirect_uri: input.redirectUri,
+    }, deps);
+}
+/**
+ * `grant_type=refresh_token` — rotation. The response carries a NEW refresh
+ * token and the old one is dead the instant this succeeds.
+ *
+ * ⚠ CALL THIS ONLY UNDER `withRefreshLock`. Presenting a token that has already
+ * been rotated revokes the whole family server-side. `lock.ts`'s module note is
+ * the long version; this is the line that stops a reader wiring it up directly.
+ */
+export async function refreshGrant(tokenEndpoint, refresh, deps) {
+    return await post(tokenEndpoint, {
+        grant_type: "refresh_token",
+        client_id: CLIENT_ID,
+        // The one place this secret's plaintext is used, at the request boundary —
+        // the same discipline `post.ts` states for the ingest credential.
+        refresh_token: refresh.expose(),
+    }, deps);
+}
+/**
+ * The authorize URL, built from the DISCOVERED endpoint.
+ *
+ * Every parameter is appended to whatever query the discovered endpoint already
+ * carries rather than replacing it: the authorize UI lives in another repo on
+ * another host and may legitimately carry its own.
+ */
+export function buildAuthorizeUrl(authorizationEndpoint, input) {
+    const url = new URL(authorizationEndpoint);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", CLIENT_ID);
+    url.searchParams.set("redirect_uri", input.redirectUri);
+    url.searchParams.set("scope", SCOPE);
+    url.searchParams.set("state", input.state);
+    url.searchParams.set("code_challenge", input.challenge);
+    url.searchParams.set("code_challenge_method", CHALLENGE_METHOD);
+    return url.toString();
+}
+//# sourceMappingURL=token.js.map

package/dist/oauth/token.js.map

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