stitchkit 0.90.5 → 0.90.6

package/dist/oauth.js

@@ -0,0 +1,170 @@
+import {
+  deriveCodeChallenge
+} from "./index-hr4tzbwq.js";
+import {
+  bytesToBase64Url
+} from "./index-rxfy4cq7.js";
+
+// src/oauth.ts
+var TRANSACTION_VERSION = 1;
+var RESERVED_PARAMETERS = new Set([
+  "response_type",
+  "client_id",
+  "redirect_uri",
+  "scope",
+  "state",
+  "nonce",
+  "code_challenge",
+  "code_challenge_method"
+]);
+var ERROR_MESSAGES = {
+  INVALID_CONFIGURATION: "The OAuth client configuration is invalid.",
+  RESERVED_PARAMETER: "A provider parameter conflicts with the OAuth protocol.",
+  INVALID_CONTEXT: "The OAuth transaction context is invalid.",
+  STORAGE_FAILURE: "The OAuth transaction store is unavailable.",
+  MISSING_TRANSACTION: "The OAuth transaction is missing or was already consumed.",
+  MALFORMED_TRANSACTION: "The OAuth transaction is malformed.",
+  UNSUPPORTED_TRANSACTION_VERSION: "The OAuth transaction version is unsupported.",
+  STATE_MISMATCH: "The OAuth response state does not match the pending transaction."
+};
+
+class AuthorizationCodeClientError extends Error {
+  code;
+  constructor(code, options) {
+    super(ERROR_MESSAGES[code], options);
+    this.name = "AuthorizationCodeClientError";
+    this.code = code;
+  }
+}
+function recordOf(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? Object.fromEntries(Object.entries(value)) : null;
+}
+function randomToken(crypto) {
+  return bytesToBase64Url(crypto.getRandomValues(new Uint8Array(32)));
+}
+function runtimeCrypto() {
+  const runtime = globalThis.crypto;
+  if (!runtime?.subtle || typeof runtime.getRandomValues !== "function") {
+    throw new AuthorizationCodeClientError("INVALID_CONFIGURATION");
+  }
+  return {
+    getRandomValues: (bytes) => runtime.getRandomValues(bytes),
+    subtle: runtime.subtle
+  };
+}
+function parseTransaction(raw, contextSchema) {
+  let decoded;
+  try {
+    decoded = JSON.parse(raw);
+  } catch {
+    throw new AuthorizationCodeClientError("MALFORMED_TRANSACTION");
+  }
+  const record = recordOf(decoded);
+  if (!record)
+    throw new AuthorizationCodeClientError("MALFORMED_TRANSACTION");
+  if (record.version !== TRANSACTION_VERSION) {
+    throw new AuthorizationCodeClientError("UNSUPPORTED_TRANSACTION_VERSION");
+  }
+  const context = contextSchema.safeParse(record.context);
+  if (!context.success)
+    throw new AuthorizationCodeClientError("INVALID_CONTEXT");
+  if (typeof record.state !== "string" || typeof record.nonce !== "string" || typeof record.codeVerifier !== "string" || typeof record.redirectUri !== "string") {
+    throw new AuthorizationCodeClientError("MALFORMED_TRANSACTION");
+  }
+  return {
+    version: TRANSACTION_VERSION,
+    state: record.state,
+    nonce: record.nonce,
+    codeVerifier: record.codeVerifier,
+    redirectUri: record.redirectUri,
+    context: context.data
+  };
+}
+function createAuthorizationCodeClient(config) {
+  if (!config.authorizationEndpoint || !config.clientId || !config.redirectUri || !config.storageKey || config.scopes.length === 0 || config.scopes.some((scope) => !scope)) {
+    throw new AuthorizationCodeClientError("INVALID_CONFIGURATION");
+  }
+  for (const parameter of Object.keys(config.authorizationParameters ?? {})) {
+    if (RESERVED_PARAMETERS.has(parameter)) {
+      throw new AuthorizationCodeClientError("RESERVED_PARAMETER");
+    }
+  }
+  return {
+    async begin({ context }) {
+      const parsedContext = config.contextSchema.safeParse(context);
+      if (!parsedContext.success)
+        throw new AuthorizationCodeClientError("INVALID_CONTEXT");
+      const crypto = config.crypto ?? runtimeCrypto();
+      const state = randomToken(crypto);
+      const nonce = randomToken(crypto);
+      const codeVerifier = randomToken(crypto);
+      const codeChallenge = await deriveCodeChallenge(codeVerifier, crypto.subtle);
+      let url;
+      try {
+        url = new URL(config.authorizationEndpoint);
+      } catch {
+        throw new AuthorizationCodeClientError("INVALID_CONFIGURATION");
+      }
+      for (const [name, value] of Object.entries(config.authorizationParameters ?? {})) {
+        url.searchParams.set(name, value);
+      }
+      url.searchParams.set("response_type", "code");
+      url.searchParams.set("client_id", config.clientId);
+      url.searchParams.set("redirect_uri", config.redirectUri);
+      url.searchParams.set("scope", config.scopes.join(" "));
+      url.searchParams.set("state", state);
+      url.searchParams.set("nonce", nonce);
+      url.searchParams.set("code_challenge", codeChallenge);
+      url.searchParams.set("code_challenge_method", "S256");
+      const transaction = {
+        version: TRANSACTION_VERSION,
+        state,
+        nonce,
+        codeVerifier,
+        redirectUri: config.redirectUri,
+        context: parsedContext.data
+      };
+      try {
+        config.storage.setItem(config.storageKey, JSON.stringify(transaction));
+      } catch {
+        throw new AuthorizationCodeClientError("STORAGE_FAILURE");
+      }
+      return { authorizationUrl: url.toString() };
+    },
+    consume({ state }) {
+      let raw;
+      try {
+        raw = config.storage.getItem(config.storageKey);
+        config.storage.removeItem(config.storageKey);
+      } catch {
+        throw new AuthorizationCodeClientError("STORAGE_FAILURE");
+      }
+      if (raw === null)
+        throw new AuthorizationCodeClientError("MISSING_TRANSACTION");
+      const transaction = parseTransaction(raw, config.contextSchema);
+      if (transaction.state !== state)
+        throw new AuthorizationCodeClientError("STATE_MISMATCH");
+      return {
+        codeVerifier: transaction.codeVerifier,
+        nonce: transaction.nonce,
+        redirectUri: transaction.redirectUri,
+        context: transaction.context
+      };
+    }
+  };
+}
+function safeInternalReturnPath(candidate, fallback) {
+  const hasAsciiControl = [...candidate ?? ""].some((character) => {
+    const code = character.charCodeAt(0);
+    return code <= 31 || code === 127;
+  });
+  if (!candidate?.startsWith("/") || candidate.startsWith("//") || candidate.includes("\\") || hasAsciiControl) {
+    return fallback;
+  }
+  return candidate;
+}
+export {
+  safeInternalReturnPath,
+  createAuthorizationCodeClient,
+  AuthorizationCodeClientError
+};

package/dist/observability/index.js

@@ -28,7 +28,8 @@ import"../index-f9mb610r.js";
 import {
   recordedErrorMessage
 } from "../index-2hryh65w.js";
-import"../index-kazec06k.js";
+import"../index-nrqg8tks.js";
+import"../index-rxfy4cq7.js";
 import"../index-6k1937bx.js";
 import {
   childSpan,

package/dist/primitives.js

@@ -1,4 +1,5 @@
-import"./index-kazec06k.js";
+import"./index-nrqg8tks.js";
+import"./index-rxfy4cq7.js";
 import {
   ManagedFileRefSchema
 } from "./index-6k1937bx.js";

package/dist/remote.js

@@ -1,6 +1,6 @@
 import {
   createClient
-} from "./index-6q3zjwaz.js";
+} from "./index-vy2nxwg8.js";
 import"./index-1txvygak.js";
 import {
   ApiError
@@ -9,7 +9,8 @@ import"./index-2hryh65w.js";
 import {
   mergeMeta,
   resolveRouteParamsSchema
-} from "./index-kazec06k.js";
+} from "./index-nrqg8tks.js";
+import"./index-rxfy4cq7.js";
 import"./index-6k1937bx.js";
 import"./index-zcgf3gqf.js";
 import {

package/dist/server/bun.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../../src/server/bun.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB,yEAAyE;AACzE,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;AACrD,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC9C,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;AACtD,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAExD,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,KAAK,oBAAoB,GAAG,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC1D,KAAK,qBAAqB,GAAG,eAAe,SAAS;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3F,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,eAAe,EACf,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAChF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,gBAAgB,EAAE,mBAAmB;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,iGAAiG;IACjG,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;AAyD7D,qDAAqD;AACrD,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CA+NrE"}
+{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../../src/server/bun.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB,yEAAyE;AACzE,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;AACrD,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC9C,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;AACtD,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAExD,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,KAAK,oBAAoB,GAAG,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC1D,KAAK,qBAAqB,GAAG,eAAe,SAAS;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3F,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,eAAe,EACf,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAChF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,gBAAgB,EAAE,mBAAmB;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,iGAAiG;IACjG,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;AAyD7D,qDAAqD;AACrD,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAiOrE"}

package/dist/server/index.js

@@ -13,7 +13,7 @@ import {
   sseRoute,
   streamingRoute,
   webSocketLane
-} from "../index-ra6txecz.js";
+} from "../index-640tz39q.js";
 import"../index-y91ry9h2.js";
 import {
   withDeadline
@@ -37,7 +37,6 @@ import {
   createAuthHook,
   createBearerResolver,
   defineCookie,
-  deriveCodeChallenge,
   extractToken,
   parseCookieHeader,
   parseCookies,
@@ -45,7 +44,10 @@ import {
   signJwt,
   verifyJwt,
   verifyPkce
-} from "../index-bg8ypxzn.js";
+} from "../index-bva395we.js";
+import {
+  deriveCodeChallenge
+} from "../index-hr4tzbwq.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS,
   DEFAULT_CORS_EXPOSE_HEADERS,
@@ -59,7 +61,7 @@ import {
   defineMultipartStream,
   implement,
   implementRegistry
-} from "../index-z78bjcxj.js";
+} from "../index-aj9geeez.js";
 import {
   isWithinDir,
   realPathWithinDir
@@ -85,7 +87,8 @@ import {
   DEFAULT_CONTRACT_STREAM_FRAME_BYTES,
   joinRoutePath,
   parseTrailingWildcard
-} from "../index-kazec06k.js";
+} from "../index-nrqg8tks.js";
+import"../index-rxfy4cq7.js";
 import"../index-6k1937bx.js";
 import"../index-zcgf3gqf.js";
 import {
@@ -491,7 +494,7 @@ function createServer(config) {
   };
   if (unixPath !== undefined) {
     reclaimStaleUnixSocket(unixPath);
-    const { reusePort, ipv6Only, http3, http1, idleTimeout, ...unixExtra } = bunExtra ?? {};
+    const { reusePort, ipv6Only, http3, http2, http1, idleTimeout, ...unixExtra } = bunExtra ?? {};
     runtime = trackedWebSocket ? Bun.serve({
       ...unixExtra,
       ...development && { development },

package/dist/server/middleware/pkce.d.ts

@@ -1,7 +1,6 @@
+export { deriveCodeChallenge } from '../../internal/pkce.js';
 /** The only PKCE method OAuth 2.1 permits for public clients. */
 export type PkceMethod = 'S256';
-/** Derive the S256 `code_challenge` from a `code_verifier`. */
-export declare function deriveCodeChallenge(verifier: string): Promise<string>;
 /**
  * Verify a `code_verifier` against the stored S256 `code_challenge`. S256 is the
  * only method OAuth 2.1 permits for public clients — `plain` is intentionally

package/dist/server/middleware/pkce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/pkce.ts"],"names":[],"mappings":"AAQA,iEAAiE;AACjE,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC,+DAA+D;AAC/D,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG3E;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAItF"}
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/pkce.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D,iEAAiE;AACjE,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAItF"}

package/dist/testing.js

@@ -28,7 +28,7 @@ import {
 import {
   createClient,
   createClients
-} from "./index-6q3zjwaz.js";
+} from "./index-vy2nxwg8.js";
 import {
   RealtimeRequestDisconnectedError,
   RealtimeRequestInvalidAcknowledgementError,
@@ -39,7 +39,8 @@ import"./index-3xwxfj4z.js";
 import"./index-2hryh65w.js";
 import {
   joinRoutePath
-} from "./index-kazec06k.js";
+} from "./index-nrqg8tks.js";
+import"./index-rxfy4cq7.js";
 import"./index-6k1937bx.js";
 import"./index-zcgf3gqf.js";
 import {

package/dist/tool-invoker.js

@@ -6,7 +6,8 @@ import"./index-8pjqv3zh.js";
 import"./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
 import"./index-2hryh65w.js";
-import"./index-kazec06k.js";
+import"./index-nrqg8tks.js";
+import"./index-rxfy4cq7.js";
 import"./index-6k1937bx.js";
 import"./index-zcgf3gqf.js";
 import"./index-7zbps32p.js";

package/dist/tools.js

@@ -4,7 +4,8 @@ import {
 import {
   signJwt,
   verifyPkce
-} from "./index-bg8ypxzn.js";
+} from "./index-bva395we.js";
+import"./index-hr4tzbwq.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS,
   DEFAULT_PROCESS_SIGNALS,
@@ -13,7 +14,7 @@ import {
   guardSignalCallback,
   mediaTypeEssence,
   reportSignalError
-} from "./index-z78bjcxj.js";
+} from "./index-aj9geeez.js";
 import {
   redact
 } from "./index-xbppf54a.js";
@@ -73,7 +74,8 @@ import {
 } from "./index-2hryh65w.js";
 import {
   defineContract
-} from "./index-kazec06k.js";
+} from "./index-nrqg8tks.js";
+import"./index-rxfy4cq7.js";
 import {
   ManagedFilePathSchema,
   ManagedFileRefSchema

package/dist/tracking.js

@@ -3,7 +3,8 @@ import {
 } from "./index-3xwxfj4z.js";
 import {
   defineContract
-} from "./index-kazec06k.js";
+} from "./index-nrqg8tks.js";
+import"./index-rxfy4cq7.js";
 import"./index-6k1937bx.js";
 import"./index-zcgf3gqf.js";
 import"./index-scs3f1eg.js";

package/llms-full.txt

@@ -64,6 +64,8 @@ own, recorded as an ADR.
 | `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
+| `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
+| `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
 | `stitchkit/observability` | server | stable<br>_redefined in 1 of the 35 minors since 0.56.2, most recently 0.83.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the store and managed-resource conformance kits |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
@@ -190,6 +192,8 @@ map — feature → packages:
 | MCP Apps UI widgets | `@modelcontextprotocol/ext-apps` |
 | React data layer (`stitchkit/react`) | `@tanstack/react-query` `react-query-kit` |
 | MaxMind GeoIP (`stitchkit/geo`) | `maxmind` |
+| Browser OAuth client (`stitchkit/oauth`) | — |
+| Google OIDC verifier (`stitchkit/google`) | `google-auth-library` |
 | **Socket.IO server on Bun** | `socket.io` `@socket.io/bun-engine` |
 | **Socket.IO server on Node** | `socket.io` |
 | Socket.IO client | `socket.io-client` (runtime peer; unrelated root declarations remain peer-free) |
@@ -226,6 +230,7 @@ package. MCP hosts and client E2E additionally install
 - [MCP & agents](./mcp-and-agents.md) — contracts as AI tools.
 - [Realtime](./realtime.md) — Socket.IO and the cache bridge.
 - [Auth & errors](./auth-and-errors.md) — scopes, auth hooks, the error model.
+- [Browser OAuth and Google OIDC](./oauth.md) — PKCE transaction and verified provider identity.
 - [Testing & deployment](./testing-and-deployment.md).
 - [API reference](../api/reference.md) — every export, by entrypoint.
 
@@ -10098,6 +10103,118 @@ onError: (ctx, err) => {
 ```
 
 
+==============================================================================
+# Guide: OAuth & OpenID Connect  (docs/guide/oauth.md)
+==============================================================================
+
+# Browser OAuth and Google OIDC
+
+Stitchkit separates the browser's Authorization Code + PKCE transaction from the server's
+provider credential verification. The application still owns navigation, users, account matching
+and merge policy, persistence, sessions, roles, unlink policy and UI.
+
+## Supported profile
+
+The current Google adapter supports one explicit profile: **web OpenID Connect Authorization Code
+with PKCE**. A browser performs a top-level redirect, an application backend exchanges the
+one-time code, and Stitchkit returns a verified identity. It is the redirect-based sign-in path;
+it is not a generic name for every Google identity or authorization mechanism.
+
+Keep adjacent Google capabilities separate because their credentials, lifecycle and trust
+boundaries differ:
+
+| Capability | Credential/result | Stitchkit support |
+| --- | --- | --- |
+| Web OIDC Authorization Code + PKCE | verified user identity | `stitchkit/oauth` + `stitchkit/google` |
+| Google Identity Services button, One Tap or FedCM | browser-delivered ID credential | not implemented |
+| Incremental authorization for Drive, Calendar or other Google APIs | access/refresh tokens and granted scopes | not implemented |
+| Installed Android, iOS or desktop application | platform client and system-browser callback | not implemented |
+| Limited-input/device authorization | device/user codes and polling lifecycle | not implemented |
+| Service account or workload identity | application identity, possibly domain-wide delegation | not implemented |
+
+Do not add these as mode flags to `GoogleOidcClient`. Each future capability gets its own adapter
+and result type, while the provider-neutral PKCE transaction can be reused where its protocol
+actually applies. In particular, authentication establishes the person; authorization to Google
+APIs is requested later, in product context, and owns refresh-token persistence and revocation.
+
+## Browser transaction
+
+`stitchkit/oauth` is browser-safe and provider-neutral. It creates independent 32-byte `state`,
+`nonce` and PKCE verifier values, writes one versioned transaction to caller-provided storage and
+returns the authorization URL without navigating:
+
+```ts
+import { createAuthorizationCodeClient, safeInternalReturnPath } from 'stitchkit/oauth'
+import { z } from 'zod'
+
+const oauth = createAuthorizationCodeClient({
+  authorizationEndpoint: 'https://accounts.google.com/o/oauth2/v2/auth',
+  clientId,
+  redirectUri: `${window.location.origin}/auth/google/callback`,
+  scopes: ['openid', 'email', 'profile'],
+  storage: window.sessionStorage,
+  storageKey: 'app:google:oauth',
+  contextSchema: z.object({ mode: z.enum(['login', 'link']), returnTo: z.string() }),
+  authorizationParameters: { prompt: 'select_account' },
+})
+
+const { authorizationUrl } = await oauth.begin({
+  context: { mode: 'login', returnTo: '/account' },
+})
+window.location.assign(authorizationUrl)
+
+// In the callback route. Reading is one-shot even when validation fails.
+const pending = oauth.consume({ state: new URL(location.href).searchParams.get('state') ?? '' })
+const returnTo = safeInternalReturnPath(pending.context.returnTo, '/')
+```
+
+Provider parameters cannot replace protocol-owned fields. `consume` removes the pending value
+before parsing, version checking, context validation or state comparison, so a malformed callback
+and a React Strict Mode replay cannot reuse it. Errors expose a stable
+`AuthorizationCodeClientError.code` and never include transaction contents.
+
+Token exchange, ID-token verification, credential persistence and application identity do not
+belong to this browser entrypoint.
+
+## Google server adapter
+
+Install the optional peer only in an application that imports `stitchkit/google`:
+
+```bash
+bun add google-auth-library
+```
+
+```ts
+import { createGoogleOidcClient } from 'stitchkit/google'
+
+const google = createGoogleOidcClient({
+  clientId: env.GOOGLE_CLIENT_ID,
+  clientSecret: env.GOOGLE_CLIENT_SECRET,
+  allowedRedirectUris: [env.GOOGLE_WEB_CALLBACK, env.GOOGLE_LOOPBACK_CALLBACK],
+  timeoutMs: 10_000,
+})
+
+const identity = await google.exchangeAuthorizationCode({
+  code,
+  codeVerifier: pending.codeVerifier,
+  redirectUri: pending.redirectUri,
+  nonce: pending.nonce,
+})
+// { subject, email, name?, picture? }
+```
+
+The redirect must match the immutable allowlist exactly before any outbound call. The token
+exchange is bounded by an abort deadline; `google-auth-library` verifies the ID-token signature,
+issuer, audience and expiry. Stitchkit additionally requires `sub`, a valid verified email and an
+exact nonce. Access, refresh and raw ID tokens never leave the adapter.
+
+`GoogleOidcError.code` distinguishes `MISCONFIGURED`, `INVALID_CREDENTIAL` and
+`UPSTREAM_UNAVAILABLE` with fixed safe messages. Endpoints compose their own rate limiter and then
+map the verified identity into application-owned user/session policy. Offline access, Google API
+scopes, database writes, user lookup or merging, session rotation, roles and UI remain outside the
+adapter.
+
+
 ==============================================================================
 # Guide: Observability  (docs/guide/observability.md)
 ==============================================================================
@@ -17163,6 +17280,35 @@ adapter is used.
 
 ---
 
+## `stitchkit/oauth`
+
+Browser-safe, provider-neutral Authorization Code + PKCE transaction mechanics. Navigation,
+token exchange, identity and sessions remain application-owned. See the [OAuth guide](../guide/oauth.md).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createAuthorizationCodeClient` / `AuthorizationCodeClient` / `AuthorizationCodeClientConfig` | function / _type_ | begin one S256 authorization request and consume its versioned pending transaction exactly once |
+| `BeginAuthorizationCodeInput` / `BeginAuthorizationCodeResult` / `ConsumeAuthorizationCodeInput` / `ConsumedAuthorizationCode` | _type_ | inputs and safe protocol result around caller-validated context |
+| `AuthorizationCodeStorage` / `AuthorizationCodeCrypto` | _type_ | injected browser capabilities; neither is read at module initialisation |
+| `AuthorizationCodeClientError` / `AuthorizationCodeClientErrorCode` | class / _type_ | fixed safe failure codes for configuration, context, storage, transaction and state failures |
+| `safeInternalReturnPath` | function | accept only a single-slash current-origin path without backslashes or ASCII controls |
+
+---
+
+## `stitchkit/google`
+
+Server-only Google code exchange and verified OIDC identity. This entry requires the optional
+`google-auth-library` peer. See the [OAuth guide](../guide/oauth.md).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createGoogleOidcClient` / `GoogleOidcClient` / `GoogleOidcClientConfig` | function / _type_ | exact-redirect, deadline-bounded code exchange and verified identity projection |
+| `ExchangeGoogleAuthorizationCodeInput` / `GoogleOidcIdentity` / `GoogleOidcClaims` | _type_ | callback input, provider-neutral result and verifier seam claims |
+| `GoogleOidcExchangeInput` / `GoogleOidcTokenTransport` / `GoogleOidcIdTokenVerifier` | _type_ | injectable transport and verifier boundaries used by production and deterministic tests |
+| `GoogleOidcError` / `GoogleOidcErrorCode` | class / _type_ | safe `MISCONFIGURED`, `INVALID_CREDENTIAL` or retryable `UPSTREAM_UNAVAILABLE` failure |
+
+---
+
 ## `stitchkit/declaration`
 
 Zod-only, dependency-free. The **project declaration**: the single

package/llms.txt

@@ -21,6 +21,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 - [Realtime](https://github.com/max-listov/stitchkit/blob/master/docs/guide/realtime.md): Socket.IO server/client wrappers, handshake auth, the cache bridge, a raw WebSocket lane
 - [Live data](https://github.com/max-listov/stitchkit/blob/master/docs/guide/live.md): defineEvents beside the contract, watched reads shared by every subscriber, keyspaces with authoritative memory, and the trust fence
 - [Auth & errors](https://github.com/max-listov/stitchkit/blob/master/docs/guide/auth-and-errors.md): scopes, createAuthHook, JWT/cookies, the AppError model, the stitch error-code registry
+- [OAuth & OpenID Connect](https://github.com/max-listov/stitchkit/blob/master/docs/guide/oauth.md): browser Authorization Code + PKCE transactions and the optional Google OIDC server adapter
 - [Observability](https://github.com/max-listov/stitchkit/blob/master/docs/guide/observability.md): request and tool-call observability, W3C trace context, createObservability
 - [Testing & deployment](https://github.com/max-listov/stitchkit/blob/master/docs/guide/testing-and-deployment.md): in-process testing; deploying on Bun and on Node (serveNode)
 - [Multi-tenant](https://github.com/max-listov/stitchkit/blob/master/docs/guide/multi-tenant.md): a /tenants/:id/… scenario end-to-end — scopePrefixes, scoped client, extend