@gajae-code/ai 0.1.1

package/src/auth-broker/types.ts

@@ -0,0 +1,127 @@
+/**
+ * Wire types shared between the auth-broker server and clients.
+ *
+ * The broker holds OAuth refresh tokens and exposes a redacted snapshot;
+ * clients use `access` tokens directly and call back to the broker when a
+ * credential expires or a 401 surfaces on a supposedly-fresh credential.
+ */
+
+import type { AuthCredential, AuthCredentialSnapshot, AuthCredentialSnapshotEntry } from "../auth-storage";
+import type { UsageReport } from "../usage";
+
+/** GET /v1/healthz response body. */
+export interface HealthzResponse {
+	ok: boolean;
+	version?: string;
+}
+
+export interface RefresherSchedule {
+	enabled: boolean;
+	intervalMs: number;
+	skewMs: number;
+	nextSweepInMs: number;
+}
+
+export type SnapshotEntry = AuthCredentialSnapshotEntry & {
+	rotatesInMs: number | null;
+};
+
+/** GET /v1/snapshot response body. */
+export interface SnapshotResponse extends Omit<AuthCredentialSnapshot, "credentials"> {
+	serverNowMs: number;
+	refresher: RefresherSchedule;
+	credentials: SnapshotEntry[];
+}
+
+/** GET /v1/usage response body — matches the local `AuthStorage.fetchUsageReports` shape. */
+export interface UsageResponse {
+	generatedAt: number;
+	reports: UsageReport[];
+}
+
+/** POST /v1/credential/:id/refresh response body. */
+export interface CredentialRefreshResponse {
+	entry: AuthCredentialSnapshotEntry;
+}
+
+/** POST /v1/credential/:id/disable request body. */
+export interface CredentialDisableRequest {
+	cause: string;
+}
+
+/** POST /v1/credential/:id/disable response body. */
+export interface CredentialDisableResponse {
+	ok: boolean;
+}
+
+/**
+ * POST /v1/credential request body. The OAuth `refresh` must be the *real*
+ * refresh token (not the sentinel) — the broker is the canonical writer.
+ */
+export interface CredentialUploadRequest {
+	provider: string;
+	credential: AuthCredential;
+}
+
+/** POST /v1/credential response body — redacted snapshot of the provider's rows after upsert. */
+export interface CredentialUploadResponse {
+	entries: AuthCredentialSnapshotEntry[];
+}
+
+/**
+ * SSE event kinds emitted on `GET /v1/snapshot/stream`. The same value is set
+ * as the SSE `event:` name (load-bearing for clients) **and** embedded as a
+ * `kind` field inside the JSON body so a Zod discriminated union can validate
+ * the payload without consulting the line metadata.
+ */
+export type SnapshotStreamEventKind = "snapshot" | "entry" | "removed";
+
+/** Initial frame emitted on connect — the full {@link SnapshotResponse}. */
+export interface SnapshotStreamSnapshotEvent extends SnapshotResponse {
+	kind: "snapshot";
+}
+
+/** Single credential added/changed (upsert or refresh). */
+export interface SnapshotStreamEntryEvent {
+	kind: "entry";
+	generation: number;
+	serverNowMs: number;
+	refresher: RefresherSchedule;
+	entry: SnapshotEntry;
+}
+
+/** Single credential disabled/deleted. */
+export interface SnapshotStreamRemovedEvent {
+	kind: "removed";
+	generation: number;
+	serverNowMs: number;
+	refresher: RefresherSchedule;
+	id: number;
+}
+
+/** Discriminated union of every event the snapshot stream emits. */
+export type SnapshotStreamEvent = SnapshotStreamSnapshotEvent | SnapshotStreamEntryEvent | SnapshotStreamRemovedEvent;
+
+/**
+ * Default bearer-protected route prefix. The broker exposes `/v1/healthz`
+ * unauthenticated for liveness probes; everything else requires a bearer.
+ */
+export const AUTH_BROKER_API_PREFIX = "/v1";
+
+/** Default port when none is configured. Loopback-only, no external exposure. */
+export const DEFAULT_AUTH_BROKER_BIND = "127.0.0.1:8765";
+
+/** Default broker→provider refresh skew. Refresh credentials this close to expiry. */
+export const DEFAULT_REFRESH_SKEW_MS = 5 * 60_000;
+
+/** Default broker refresh-loop cadence. */
+export const DEFAULT_REFRESH_INTERVAL_MS = 60_000;
+
+/** Keepalive cadence for `GET /v1/snapshot/stream` SSE comments. */
+export const DEFAULT_STREAM_KEEPALIVE_MS = 20_000;
+
+/**
+ * Bun.serve `idleTimeout` (seconds) used by the broker. Default Bun idle
+ * timeout (10s) would close long-lived SSE connections between keepalives.
+ */
+export const DEFAULT_SERVER_IDLE_TIMEOUT_S = 255;

package/src/auth-broker/wire-schemas.ts

@@ -0,0 +1,200 @@
+/**
+ * Zod schemas for the auth-broker wire protocol.
+ *
+ * Shared between the server (validates inbound request bodies) and the client
+ * (validates responses from the broker). Schemas mirror the TypeScript types
+ * in `./types.ts` 1:1; the types remain the source of truth for static typing,
+ * and `z.infer<typeof Schema>` is asserted-compatible with them where possible.
+ *
+ * Schemas use `.strict()` on objects with a closed set of fields so unknown
+ * keys are rejected — the previous implementation used a hand-rolled
+ * `hasOnlyFields` allowlist for the same effect.
+ */
+import * as z from "zod/v4";
+import { REMOTE_REFRESH_SENTINEL } from "../auth-storage";
+import { usageReportSchema } from "../usage";
+
+// ─── Credential payloads ───────────────────────────────────────────────────
+
+/** Real OAuth credential (broker-side) — refresh token is the actual upstream value. */
+export const oauthCredentialSchema = z
+	.object({
+		type: z.literal("oauth"),
+		refresh: z
+			.string()
+			.min(1)
+			// Reject the sentinel literal on writes: if a client somehow round-trips
+			// a snapshot back into POST /v1/credential, accepting the sentinel as a
+			// real refresh token would silently break that credential's refresh
+			// forever (the broker would store `"__remote__"` and try to use it as
+			// the upstream refresh token).
+			.refine(value => value !== REMOTE_REFRESH_SENTINEL, {
+				message: `refresh token must not equal the remote sentinel (${REMOTE_REFRESH_SENTINEL})`,
+			}),
+		access: z.string().min(1),
+		expires: z.number(),
+		enterpriseUrl: z.string().optional(),
+		projectId: z.string().optional(),
+		email: z.string().optional(),
+		accountId: z.string().optional(),
+	})
+	.strict();
+
+/** OAuth credential as it appears in broker snapshots — refresh replaced with sentinel. */
+export const remoteOauthCredentialSchema = oauthCredentialSchema.extend({
+	refresh: z.literal(REMOTE_REFRESH_SENTINEL),
+});
+
+export const apiKeyCredentialSchema = z
+	.object({
+		type: z.literal("api_key"),
+		key: z.string().min(1),
+	})
+	.strict();
+
+/** Discriminated union accepted on POST /v1/credential (writes). */
+export const writableAuthCredentialSchema = z.discriminatedUnion("type", [
+	oauthCredentialSchema,
+	apiKeyCredentialSchema,
+]);
+
+/** Discriminated union returned in snapshots (refresh is sentinel for OAuth). */
+export const snapshotCredentialSchema = z.discriminatedUnion("type", [
+	remoteOauthCredentialSchema,
+	apiKeyCredentialSchema,
+]);
+
+// ─── Snapshot ──────────────────────────────────────────────────────────────
+
+export const credentialSnapshotEntrySchema = z
+	.object({
+		id: z.number().int(),
+		provider: z.string().min(1),
+		credential: snapshotCredentialSchema,
+		identityKey: z.string().nullable(),
+	})
+	.strict();
+
+export const snapshotEntrySchema = credentialSnapshotEntrySchema
+	.extend({
+		rotatesInMs: z.number().nullable(),
+	})
+	.strict();
+
+export const refresherScheduleSchema = z
+	.object({
+		enabled: z.boolean(),
+		intervalMs: z.number(),
+		skewMs: z.number(),
+		nextSweepInMs: z.number(),
+	})
+	.strict();
+
+export const snapshotResponseSchema = z
+	.object({
+		generation: z.number().int(),
+		generatedAt: z.number(),
+		serverNowMs: z.number(),
+		refresher: refresherScheduleSchema,
+		credentials: z.array(snapshotEntrySchema),
+	})
+	.strict();
+
+// ─── Snapshot stream (SSE) ────────────────────────────────────────────────
+
+/** First frame on connect — full snapshot embedded inline with a `kind` tag. */
+export const snapshotStreamSnapshotEventSchema = snapshotResponseSchema
+	.extend({
+		kind: z.literal("snapshot"),
+	})
+	.strict();
+
+/** Per-credential upsert/refresh delta. */
+export const snapshotStreamEntryEventSchema = z
+	.object({
+		kind: z.literal("entry"),
+		generation: z.number().int(),
+		serverNowMs: z.number(),
+		refresher: refresherScheduleSchema,
+		entry: snapshotEntrySchema,
+	})
+	.strict();
+
+/** Per-credential delete delta. */
+export const snapshotStreamRemovedEventSchema = z
+	.object({
+		kind: z.literal("removed"),
+		generation: z.number().int(),
+		serverNowMs: z.number(),
+		refresher: refresherScheduleSchema,
+		id: z.number().int(),
+	})
+	.strict();
+
+/** Discriminated union over every event frame the snapshot stream emits. */
+export const snapshotStreamEventSchema = z.discriminatedUnion("kind", [
+	snapshotStreamSnapshotEventSchema,
+	snapshotStreamEntryEventSchema,
+	snapshotStreamRemovedEventSchema,
+]);
+
+// ─── Healthz ────────────────────────────────────────────────────────────────
+
+export const healthzResponseSchema = z
+	.object({
+		ok: z.boolean(),
+		version: z.string().optional(),
+	})
+	.strict();
+
+// ─── Usage ─────────────────────────────────────────────────────────────────
+
+/**
+ * Broker `/v1/usage` response. Reports are full {@link UsageReport}s minus the
+ * heavy provider-specific `raw` field (the server strips it before send) — we
+ * keep `raw` optional in the underlying schema so a misconfigured broker that
+ * forgot to strip still validates.
+ */
+export const usageResponseSchema = z
+	.object({
+		generatedAt: z.number(),
+		reports: z.array(usageReportSchema),
+	})
+	.strict();
+
+// ─── Refresh ───────────────────────────────────────────────────────────────
+
+export const credentialRefreshResponseSchema = z
+	.object({
+		entry: credentialSnapshotEntrySchema,
+	})
+	.strict();
+
+// ─── Disable ───────────────────────────────────────────────────────────────
+
+export const credentialDisableRequestSchema = z
+	.object({
+		cause: z.string().optional(),
+	})
+	.strict();
+
+export const credentialDisableResponseSchema = z
+	.object({
+		ok: z.boolean(),
+	})
+	.strict();
+
+// ─── Upload ────────────────────────────────────────────────────────────────
+
+export const credentialUploadRequestSchema = z
+	.object({
+		provider: z.string().min(1),
+		credential: writableAuthCredentialSchema,
+	})
+	.strict();
+
+export const credentialUploadResponseSchema = z
+	.object({
+		entries: z.array(credentialSnapshotEntrySchema),
+	})
+	.strict();

package/src/auth-gateway/http.ts

@@ -0,0 +1,194 @@
+/**
+ * Shared HTTP helpers for the auth-gateway routes.
+ *
+ * Centralized so we share the same JSON shape, auth check,
+ * and peer-resolution logic.
+ */
+import { timingSafeEqual as nodeTimingSafeEqual } from "node:crypto";
+
+const JSON_HEADERS = {
+	"Content-Type": "application/json",
+	"X-Content-Type-Options": "nosniff",
+} as const;
+
+export function json(status: number, body: unknown): Response {
+	return new Response(JSON.stringify(body) ?? "null", {
+		status,
+		headers: JSON_HEADERS,
+	});
+}
+
+export function resolvePeer(req: Request): string {
+	const fwd = req.headers.get("x-forwarded-for");
+	if (fwd) return fwd.split(",")[0].trim();
+	return req.headers.get("x-real-ip") ?? "unknown";
+}
+
+/**
+ * Constant-time byte comparison. Falls back to a manual XOR accumulator if
+ * `node:crypto.timingSafeEqual` isn't available. Always processes every byte
+ * of the longer input so length itself doesn't leak via timing.
+ */
+export function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {
+	if (a.length === b.length && typeof nodeTimingSafeEqual === "function") {
+		return nodeTimingSafeEqual(a, b);
+	}
+	const len = Math.max(a.length, b.length);
+	let diff = a.length ^ b.length;
+	for (let i = 0; i < len; i++) {
+		// Out-of-range reads return undefined → coerce to 0 via `| 0`.
+		const av = (i < a.length ? a[i] : 0) | 0;
+		const bv = (i < b.length ? b[i] : 0) | 0;
+		diff |= av ^ bv;
+	}
+	return diff === 0;
+}
+
+const TOKEN_ENCODER = new TextEncoder();
+
+export function isAuthorized(req: Request, tokens: ReadonlySet<string>): boolean {
+	if (tokens.size === 0) return true;
+	const header = req.headers.get("authorization");
+	if (!header) return false;
+	const match = header.match(/^Bearer\s+(.+)$/i);
+	if (!match) return false;
+	const presented = TOKEN_ENCODER.encode(match[1].trim());
+	// Iterate every allowed token regardless of early hits so the result
+	// timing reflects the full set, not the position of the match.
+	let ok = false;
+	for (const tok of tokens) {
+		const expected = TOKEN_ENCODER.encode(tok);
+		if (timingSafeEqual(presented, expected)) ok = true;
+	}
+	return ok;
+}
+
+/**
+ * Allow-list of inbound request headers that the gateway captures and forwards
+ * to the underlying parsers (which decide whether to surface them to the
+ * provider). Case-insensitive; `x-stainless-` is a prefix match.
+ */
+const PASSTHROUGH_HEADER_NAMES: Record<string, true> = {
+	"anthropic-beta": true,
+	"anthropic-version": true,
+	"openai-organization": true,
+	"openai-project": true,
+	"openai-beta": true,
+	// OpenAI code backend / ChatGPT-OAuth backend headers (see OpenAI code provider/constants.ts).
+	// `session_id` and `conversation_id` thread the upstream session so prompt
+	// caching and per-conversation rate limiting work; `chatgpt-account-id` and
+	// `originator` identify the calling account and client surface.
+	"chatgpt-account-id": true,
+	originator: true,
+	session_id: true,
+	conversation_id: true,
+	// Vendor-neutral cache-identity headers. The gateway also reads these to
+	// populate `options.promptCacheKey` (see `resolvePromptCacheKey` below)
+	// so explicit client hints win over the derived fallback.
+	"x-prompt-cache-key": true,
+	"x-session-id": true,
+	"x-conversation-id": true,
+};
+
+/**
+ * Extract allow-listed passthrough headers from an inbound request. Keys are
+ * lowercased; empty values are dropped. Called once per request in
+ * `handleFormatEndpoint`; parsers then read `options.headers`.
+ */
+export function captureRequestHeaders(headers: Headers): Record<string, string> {
+	const out: Record<string, string> = {};
+	headers.forEach((value, key) => {
+		if (!value) return;
+		const lower = key.toLowerCase();
+		if (PASSTHROUGH_HEADER_NAMES[lower] || lower.startsWith("x-stainless-")) {
+			out[lower] = value;
+		}
+	});
+	return out;
+}
+
+/**
+ * Priority order for resolving a client-supplied prompt-cache identity. The
+ * first non-empty value wins. When none are present, the gateway derives a
+ * stable UUID from the request's stable parts.
+ */
+const CACHE_KEY_HEADERS: readonly string[] = [
+	"x-prompt-cache-key",
+	"session_id",
+	"conversation_id",
+	"x-session-id",
+	"x-conversation-id",
+];
+
+function readBodyCacheKey(body: unknown): string | undefined {
+	if (body === null || typeof body !== "object") return undefined;
+	const root = body as Record<string, unknown>;
+	// Explicit body fields (OpenAI Responses / Chat).
+	const direct = root.prompt_cache_key;
+	if (typeof direct === "string" && direct.length > 0) return direct;
+	// Nested `metadata` (OpenAI code backend CLI / Anthropic clients that route a session
+	// identifier through the metadata bag).
+	const metadata = root.metadata;
+	if (metadata === null || typeof metadata !== "object") return undefined;
+	const meta = metadata as Record<string, unknown>;
+	for (const field of ["prompt_cache_key", "session_id", "conversation_id"] as const) {
+		const v = meta[field];
+		if (typeof v === "string" && v.length > 0) return v;
+	}
+	return undefined;
+}
+
+/**
+ * Resolve a prompt-cache identity from inbound request body + headers.
+ * Order of precedence (first wins):
+ *   1. Body `prompt_cache_key`
+ *   2. Body `metadata.{prompt_cache_key,session_id,conversation_id}`
+ *   3. Header `x-prompt-cache-key`
+ *   4. Header `session_id` / `conversation_id` (OpenAI code backend / ChatGPT-OAuth surface)
+ *   5. Header `x-session-id` / `x-conversation-id` (common informal)
+ * Returns undefined when none present; the gateway then derives a stable
+ * UUID from the request's stable parts.
+ */
+export function resolvePromptCacheKey(body: unknown, headers?: Headers): string | undefined {
+	const fromBody = readBodyCacheKey(body);
+	if (fromBody) return fromBody;
+	if (!headers) return undefined;
+	for (const name of CACHE_KEY_HEADERS) {
+		const v = headers.get(name);
+		if (v && v.length > 0) return v;
+	}
+	return undefined;
+}
+
+const CORS_HEADERS: Record<string, string> = {
+	"Access-Control-Allow-Origin": "*",
+	"Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+	"Access-Control-Allow-Headers":
+		"authorization, content-type, anthropic-version, anthropic-beta, openai-organization, openai-project, x-stainless-*, x-api-key",
+	"Access-Control-Max-Age": "86400",
+};
+
+/**
+ * CORS headers for the auth-gateway. Currently echoes a wildcard origin; the
+ * request is accepted so future tightening can mirror `Origin` without
+ * threading the request through every caller.
+ */
+export function corsHeaders(_req: Request): Record<string, string> {
+	return { ...CORS_HEADERS };
+}
+
+/**
+ * Re-emit `response` with CORS headers merged. The original response body is
+ * passed through unchanged. Used by the gateway wrapper so every outbound
+ * format-endpoint response carries the same CORS surface as the preflight.
+ */
+export function withCors(response: Response, req: Request): Response {
+	const headers = new Headers(response.headers);
+	const cors = corsHeaders(req);
+	for (const k in cors) headers.set(k, cors[k]);
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers,
+	});
+}

package/src/auth-gateway/index.ts

@@ -0,0 +1,3 @@
+export * from "./http";
+export * from "./server";
+export * from "./types";