workers-gate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sunya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# workers-gate
+
+A stateless authorization gate for apps on Cloudflare Workers. Bring your own provider; call the gate where you want it.
+
+Authorization, not authentication: it never asks or stores who the user is. No database, no KV, and a single dependency — cookie signing and verification are delegated to [jose](https://github.com/panva/jose). All that travels is a signed, expiring JWT cookie. Your filter says yes? You're in. Otherwise 403.
+
+## How it works
+
+`createGate(config)` gives you a plain function: `(request) => Promise<Response | null>`.
+
+```
+gate(request):
+  /auth/login    → Response: redirect to provider.authorizeUrl(...)
+  /auth/callback → provider.identify(...) fetches data → your filter(data) decides
+                   ├─ true  → Response: signed session cookie + redirect back
+                   └─ false → Response: 403
+  anything else  → valid session cookie? (signature + expiry, no I/O)
+                   ├─ yes → null   ← the request is yours
+                   └─ no  → Response: redirect to login (or 401 for non-document requests)
+```
+
+You call it inside your own `fetch` and return early when it hands you a Response — the standard middleware contract. No wrapping, no hidden routing, no implicit env reads: every value the gate uses is one you passed it.
+
+## Usage
+
+```ts
+// src/worker.ts
+import { env } from "cloudflare:workers";
+import { createGate, oauthProvider } from "workers-gate";
+
+const gate = createGate({
+  cookieSecret: env.COOKIE_SECRET,
+  provider: oauthProvider({
+    // endpoints, client credentials, scope, identify() —
+    // see Providers below; complete configs live in Recipes
+  }),
+  filter: (data) => data.team === "blue", // your policy, typed by the provider
+});
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return (await gate(request)) ?? env.ASSETS.fetch(request);
+  },
+};
+```
+
+- Build the gate once at module scope via the [`cloudflare:workers`](https://developers.cloudflare.com/workers/runtime-apis/bindings/#importing-env-as-a-module) env import (compatibility date 2025-03-10+), or per request inside `fetch` from the handler's `env` — either works the same.
+- `filter` receives whatever data `identify` returned — fully typed, re-evaluated on every (re-)login. Omit it to admit anyone the provider can identify.
+- The layering encodes ownership: `identify` lives in the provider (shareable, policy-free procurement), `filter` lives in your config (your deployment's policy). Folding the judgment into `identify` (return `null` for "no") is equally valid.
+- Public routes are your if-statement: `if (url.pathname === "/healthz") return ok()` before calling `gate(request)`.
+- Works with wrangler-generated `Env` types as-is — the gate never touches `env`; you hand it values.
+
+Route every request through the worker so static assets are gated too:
+
+```jsonc
+// wrangler.jsonc
+{
+  "main": "src/worker.ts",
+  "assets": {
+    "directory": "./dist",
+    "binding": "ASSETS",
+    "not_found_handling": "single-page-application", // for SPAs
+    "run_worker_first": true, // or ["/*", "!/assets/*"] to skip hashed assets
+  },
+}
+```
+
+The gate itself needs one binding: `COOKIE_SECRET` (`openssl rand -hex 32`, via `wrangler secret put`). Everything else belongs to your provider and filter.
+
+Set secrets before the first deploy: `createGate` fails fast on an empty `cookieSecret`, so a worker deployed without its secrets won't pass deploy validation. `wrangler secret put` offers to create a draft Worker when none exists — put the secrets first, then deploy. To keep deployment-specific values out of tracked files, `wrangler deploy --var KEY:value` overrides config vars at deploy time.
+
+## Providers
+
+A provider procures data about the visitor; it makes no decisions. For any vanilla OAuth2 authorization-code IdP, `oauthProvider()` covers the protocol plumbing — you supply two endpoints, client credentials, and an `identify()` that fetches the data your filter judges (see the Discord recipe below for a complete one).
+
+For IdPs with heavier dialects (PKCE-required, custom token-endpoint auth), implement `GateProvider` directly — two functions — on top of whatever client you like ([openid-client](https://github.com/panva/openid-client) for OIDC, [Arctic](https://arcticjs.dev) for 60+ providers; both run on Workers):
+
+```ts
+import { type GateProvider } from "workers-gate";
+
+const myProvider: GateProvider<MyData> = {
+  // Where visitors go to prove themselves.
+  authorizeUrl({ redirectUri, state, silent }) {
+    return "https://idp.example/authorize?...";
+  },
+  // Procure the data about the visitor. null = could not identify.
+  async identify({ code, redirectUri }) {
+    return {
+      /* whatever your filter needs */
+    };
+  },
+};
+```
+
+The contract: `authorizeUrl` must request whatever scope/claims `identify` needs to gather its data — the two are a pair. Keep the scope minimal.
+
+`silent` is `true` when a returning visitor's session just expired; OAuth-style providers can translate it to `prompt=none`. If the IdP answers the callback with an `error` param, the gate automatically retries an interactive login. `oauthProvider`'s `identify` also receives the full `tokenResponse` for extras like `id_token`.
+
+## Recipes
+
+The library ships no IdP presets — endpoints, scope, and policy are yours. Both example projects are deployable as-is (wrangler config, `.dev.vars` template, generated types).
+
+### Discord: guild members only — [`examples/discord-guild/`](./examples/discord-guild/)
+
+```ts
+provider: oauthProvider({
+  authorizeEndpoint: "https://discord.com/oauth2/authorize",
+  tokenEndpoint: "https://discord.com/api/v10/oauth2/token",
+  clientId: env.DISCORD_CLIENT_ID,
+  clientSecret: env.DISCORD_CLIENT_SECRET,
+  scope: "guilds.members.read",
+  silentParams: { prompt: "none" },
+  async identify({ accessToken }) {
+    // membership in this one guild, straight from Discord; 404 = not a member
+    const res = await fetch(
+      `https://discord.com/api/v10/users/@me/guilds/${env.GUILD_ID}/member`,
+      { headers: { Authorization: `Bearer ${accessToken}` } },
+    );
+    if (!res.ok) return null;
+    const member: { roles: string[] } = await res.json();
+    return member;
+  },
+}),
+// membership itself is the policy; add a filter for finer rules, e.g. roles
+```
+
+Prefer the broader `guilds` scope + `GET /users/@me/guilds` if you'd rather not let the app read your nickname/roles in that guild.
+
+### GitHub: org members only — [`examples/github-org/`](./examples/github-org/)
+
+Scope `read:org`, `identify` fetches `GET /user/memberships/orgs/{org}`, and the filter admits only `state === "active"`. The example also ships a denial page with GitHub-specific recovery guidance (GitHub has no `prompt` support, so switching accounts requires signing out of github.com first). An org-owned private GitHub App is the cleanest registration: installing it on the org doubles as the access approval that OAuth Apps need separately.
+
+### Google Workspace: domain members only
+
+OIDC — implement `GateProvider` with openid-client, return the ID-token claims from `identify`, and `filter: (claims) => claims.hd === "example.com"`.
+
+## GateConfig
+
+| Field                                       | Default                                       | Description                                                                      |
+| ------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------- |
+| `cookieSecret`                              | required                                      | HMAC key for session/state cookies                                               |
+| `provider`                                  | required                                      | Data procurement: `authorizeUrl` + `identify`                                    |
+| `filter`                                    | admit all identified                          | The authorization decision                                                       |
+| `signin`                                    | redirect straight to the IdP                  | Custom sign-in screen for unauthenticated document requests; receives `loginUrl` |
+| `denied`                                    | built-in minimal 403 page                     | Custom Response for rejected/unidentified visitors; receives `loginUrl`          |
+| `unauthorized`                              | plain-text 401                                | Custom Response for sessionless fetch/XHR; receives `loginUrl`                   |
+| `sessionTtlSeconds`                         | `86400`                                       | Session cookie lifetime                                                          |
+| `loginPath` / `callbackPath` / `logoutPath` | `/auth/login` `/auth/callback` `/auth/logout` | Routes the gate claims                                                           |
+| `cookieName` / `stateCookieName`            | `__gate` `__gate_state`                       | Cookie names                                                                     |
+
+## Screens are yours
+
+The gate ships no UI beyond a fallback 403/401. Every visible surface is replaceable:
+
+- Sign-in screen (`signin`): rendered in place of the default straight-to-IdP redirect for unauthenticated page visits — the URL stays put, your screen shows, its button points at `loginUrl` (which already carries the `returnTo`). Both examples render one. Silent re-authorization of expired sessions bypasses the screen and stays seamless.
+- Denied page (`denied`): `denied: ({ loginUrl }) => new Response(myBrandedHtml, { status: 403, headers: { "Content-Type": "text/html" } })`
+- API 401 shape (`unauthorized`): `unauthorized: ({ loginUrl }) => Response.json({ error: "login required", loginUrl }, { status: 401 })`
+
+By default there is no login screen at all: unauthenticated visitors are redirected straight to the IdP's own consent page.
+
+## Notes for SPAs
+
+- `not_found_handling: "single-page-application"` keeps client-side routing working: unknown paths serve the (gated) `index.html`.
+- Using `@cloudflare/vite-plugin`? Same worker entry, same wrangler config — `vite dev` runs the gate locally. Put the bindings in `.dev.vars` and register the localhost callback URL with your IdP.
+- When the session expires mid-visit, background `fetch` calls get `401` instead of a redirect (shape the body with the `unauthorized` hook). The simple recovery is `location.reload()` — the reload goes through silent re-authorization and comes back to the same URL.
+- To renew without losing app state, use a popup: top-level navigation carries the `SameSite=Lax` cookies, which hidden iframes and background fetches do not. Serve a self-closing page behind the gate and point the popup's `returnTo` at it:
+
+```ts
+// worker: after the gate has passed
+if (url.pathname === "/auth/done") {
+  return new Response("<script>window.close()</script>", {
+    headers: { "Content-Type": "text/html" },
+  });
+}
+```
+
+```ts
+// SPA: on 401 — tie this to a click so popup blockers stay calm
+const popup = window.open(
+  "/auth/login?returnTo=%2Fauth%2Fdone&silent=1",
+  "_blank",
+  "width=520,height=640",
+);
+await new Promise<void>((resolve) => {
+  const timer = setInterval(() => {
+    if (popup?.closed) {
+      clearInterval(timer);
+      resolve();
+    }
+  }, 300);
+});
+// retry the failed request — app state untouched
+```
+
+If the silent pass fails (signed out of the IdP), the gate falls back to an interactive login inside the popup; the app keeps running either way.
+
+## Limitations
+
+- Stateless means no early revocation: a visitor who no longer satisfies your policy keeps access until their cookie expires (default 24h). Shorten `sessionTtlSeconds` if that matters.
+- Scope is redirect-and-callback flows (OAuth/OIDC-style). Basic auth or IP allowlists are a different animal.
+- A `POST` issued with an expired session is redirected and loses its body — the follow-up navigation re-authorizes.

package/dist/cookie.d.ts

@@ -0,0 +1,8 @@
+import { type JWTPayload } from "jose";
+export interface VerifiedToken {
+    payload: unknown;
+    /** signature was valid but the exp claim has passed */
+    expired: boolean;
+}
+export declare function sign(payload: JWTPayload, secret: string): Promise<string>;
+export declare function verify(token: string, secret: string): Promise<VerifiedToken | null>;

package/dist/cookie.js

@@ -0,0 +1,20 @@
+import { errors, jwtVerify, SignJWT } from "jose";
+const encoder = new TextEncoder();
+export function sign(payload, secret) {
+    return new SignJWT(payload).setProtectedHeader({ alg: "HS256" }).sign(encoder.encode(secret));
+}
+export async function verify(token, secret) {
+    try {
+        const { payload } = await jwtVerify(token, encoder.encode(secret), {
+            algorithms: ["HS256"],
+        });
+        return { payload, expired: false };
+    }
+    catch (error) {
+        // expired-but-valid must stay distinguishable: it drives silent re-auth
+        if (error instanceof errors.JWTExpired) {
+            return { payload: error.payload, expired: true };
+        }
+        return null;
+    }
+}

package/dist/gate.d.ts

@@ -0,0 +1,79 @@
+export interface AuthorizeUrlInput {
+    redirectUri: string;
+    state: string;
+    /**
+     * true when re-authorizing a returning visitor whose session just expired.
+     * OAuth-style providers may map this to prompt=none for a seamless refresh.
+     */
+    silent: boolean;
+}
+export interface IdentifyInput {
+    code: string;
+    redirectUri: string;
+}
+/**
+ * The pluggable half of the gate: where to send visitors to prove themselves,
+ * and how to fetch the data about them that the filter will judge.
+ *
+ * Contract: authorizeUrl must request whatever scope/claims identify() needs
+ * to gather its data — the two are a pair. Providers procure, filters decide.
+ */
+export interface GateProvider<Data extends {} = {}> {
+    /** Build the URL the visitor is redirected to for authorization */
+    authorizeUrl(input: AuthorizeUrlInput): string;
+    /** Fetch the data about the returning visitor; null = could not identify */
+    identify(input: IdentifyInput): Promise<Data | null>;
+}
+export interface GateFilterContext {
+    request: Request;
+}
+export interface GateConfig<Data extends {} = {}> {
+    /** HMAC key for the session and state cookies, e.g. env.COOKIE_SECRET */
+    cookieSecret: string;
+    provider: GateProvider<Data>;
+    /**
+     * The authorization decision: given the data the provider identified,
+     * decide whether to let the visitor in. Runs on every (re-)login.
+     * Omitted = anyone the provider can identify is admitted.
+     */
+    filter?: (data: Data, context: GateFilterContext) => boolean | Promise<boolean>;
+    /**
+     * Custom 403 response for visitors the provider couldn't identify or the
+     * filter rejected. Default: a minimal built-in HTML page.
+     * loginUrl carries the returnTo, so a retry lands on the original page.
+     */
+    denied?: (context: {
+        request: Request;
+        loginUrl: string;
+    }) => Response | Promise<Response>;
+    /**
+     * Custom response for non-document requests (fetch/XHR) without a valid
+     * session. Default: a plain-text 401. loginUrl carries the returnTo.
+     */
+    unauthorized?: (context: {
+        request: Request;
+        loginUrl: string;
+    }) => Response | Promise<Response>;
+    /**
+     * Custom sign-in screen for unauthenticated document requests.
+     * Default: redirect straight to the provider's authorize URL.
+     * Not consulted for silent re-authorization of expired sessions,
+     * which stays a seamless redirect. loginUrl carries the returnTo.
+     */
+    signin?: (context: {
+        request: Request;
+        loginUrl: string;
+    }) => Response | Promise<Response>;
+    loginPath?: string;
+    callbackPath?: string;
+    logoutPath?: string;
+    sessionTtlSeconds?: number;
+    cookieName?: string;
+    stateCookieName?: string;
+}
+/**
+ * Returns a Response when the gate handles or denies the request
+ * (auth routes, redirects, 401/403), and null when the visitor may pass.
+ */
+export type Gate = (request: Request) => Promise<Response | null>;
+export declare function createGate<Data extends {}>(config: GateConfig<Data>): Gate;

package/dist/gate.js

@@ -0,0 +1,127 @@
+import { sign, verify } from "./cookie";
+function nowSec() {
+    return Math.floor(Date.now() / 1000);
+}
+function redirect(location) {
+    return new Response(null, { status: 302, headers: { Location: location } });
+}
+function randomState() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function forbiddenHtml(loginUrl) {
+    return `<!doctype html>
+<meta charset="utf-8">
+<title>403 Forbidden</title>
+<p>You are not authorized to access this application.</p>
+<p><a href="${loginUrl}">Sign in again</a></p>`;
+}
+function isSessionPayload(value) {
+    return (typeof value === "object" && value !== null && "exp" in value && typeof value.exp === "number");
+}
+function isStatePayload(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "state" in value &&
+        typeof value.state === "string" &&
+        "returnTo" in value &&
+        typeof value.returnTo === "string" &&
+        "exp" in value &&
+        typeof value.exp === "number");
+}
+export function createGate(config) {
+    const { cookieSecret, provider, filter, denied, unauthorized, signin, loginPath = "/auth/login", callbackPath = "/auth/callback", logoutPath = "/auth/logout", sessionTtlSeconds = 60 * 60 * 24, cookieName = "__gate", stateCookieName = "__gate_state", } = config;
+    if (!cookieSecret) {
+        throw new TypeError("createGate: cookieSecret is empty");
+    }
+    return async function gate(request) {
+        const url = new URL(request.url);
+        const redirectUri = `${url.origin}${callbackPath}`;
+        const readCookie = (name) => {
+            const header = request.headers.get("Cookie") ?? "";
+            for (const part of header.split(/;\s*/)) {
+                const eq = part.indexOf("=");
+                if (eq > 0 && part.slice(0, eq) === name)
+                    return part.slice(eq + 1);
+            }
+            return null;
+        };
+        const safeReturnTo = (value) => value?.startsWith("/") && !value.startsWith("//") ? value : "/";
+        const startLogin = async (silent) => {
+            const state = randomState();
+            const returnTo = safeReturnTo(url.searchParams.get("returnTo"));
+            const stateToken = await sign({ state, returnTo, exp: nowSec() + 600 }, cookieSecret);
+            const res = redirect(provider.authorizeUrl({ redirectUri, state, silent }));
+            res.headers.set("Set-Cookie", `${stateCookieName}=${stateToken}; Path=${callbackPath}; HttpOnly; Secure; SameSite=Lax; Max-Age=600`);
+            return res;
+        };
+        const handleCallback = async () => {
+            const stateToken = readCookie(stateCookieName);
+            const verified = stateToken ? await verify(stateToken, cookieSecret) : null;
+            const statePayload = verified && !verified.expired && isStatePayload(verified.payload) ? verified.payload : null;
+            // providers report failed silent re-auth as an error param;
+            // fall back to interactive login instead of surfacing it
+            if (url.searchParams.get("error")) {
+                const returnTo = safeReturnTo(statePayload?.returnTo);
+                return redirect(`${loginPath}?returnTo=${encodeURIComponent(returnTo)}`);
+            }
+            const code = url.searchParams.get("code");
+            const state = url.searchParams.get("state");
+            if (!statePayload || !code || !state || state !== statePayload.state) {
+                return new Response("Invalid OAuth state", { status: 400 });
+            }
+            const data = await provider.identify({ code, redirectUri });
+            // loose != so a sloppy provider resolving undefined fails closed
+            const allowed = data != null && (filter ? await filter(data, { request }) : true);
+            if (!allowed) {
+                const retryUrl = `${loginPath}?returnTo=${encodeURIComponent(safeReturnTo(statePayload.returnTo))}`;
+                if (denied)
+                    return denied({ request, loginUrl: retryUrl });
+                return new Response(forbiddenHtml(retryUrl), {
+                    status: 403,
+                    headers: { "Content-Type": "text/html; charset=utf-8" },
+                });
+            }
+            const session = await sign({ exp: nowSec() + sessionTtlSeconds }, cookieSecret);
+            const res = redirect(safeReturnTo(statePayload.returnTo));
+            res.headers.append("Set-Cookie", `${cookieName}=${session}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${sessionTtlSeconds}`);
+            res.headers.append("Set-Cookie", `${stateCookieName}=; Path=${callbackPath}; HttpOnly; Secure; SameSite=Lax; Max-Age=0`);
+            return res;
+        };
+        const logout = () => {
+            const res = redirect("/");
+            res.headers.set("Set-Cookie", `${cookieName}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0`);
+            return res;
+        };
+        switch (url.pathname) {
+            case loginPath:
+                return startLogin(url.searchParams.get("silent") === "1");
+            case callbackPath:
+                return handleCallback();
+            case logoutPath:
+                return logout();
+        }
+        const sessionToken = readCookie(cookieName);
+        const verified = sessionToken ? await verify(sessionToken, cookieSecret) : null;
+        const session = verified && isSessionPayload(verified.payload) ? verified.payload : null;
+        if (session && !verified?.expired) {
+            return null; // authorized — the request is yours
+        }
+        const returnTo = encodeURIComponent(url.pathname + url.search);
+        const loginUrl = `${loginPath}?returnTo=${returnTo}`;
+        const isDocument = request.headers.get("Sec-Fetch-Dest") === "document" ||
+            (request.headers.get("Accept") ?? "").includes("text/html");
+        if (!isDocument) {
+            if (unauthorized)
+                return unauthorized({ request, loginUrl });
+            return new Response("Unauthorized", { status: 401 });
+        }
+        // a validly-signed but expired session means a returning visitor:
+        // silent re-authorization stays a seamless redirect, skipping signin
+        if (session)
+            return redirect(`${loginUrl}&silent=1`);
+        if (signin)
+            return signin({ request, loginUrl });
+        return redirect(loginUrl);
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createGate } from "./gate";
+export type { AuthorizeUrlInput, Gate, GateConfig, GateFilterContext, GateProvider, IdentifyInput, } from "./gate";
+export { oauthProvider } from "./oauth";
+export type { OAuthIdentifyInput, OAuthProviderConfig } from "./oauth";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createGate } from "./gate";
+export { oauthProvider } from "./oauth";

package/dist/oauth.d.ts

@@ -0,0 +1,30 @@
+import type { GateProvider } from "./gate";
+export interface OAuthIdentifyInput {
+    accessToken: string;
+    /**
+     * The token endpoint's full parsed response — for extras like id_token
+     * (OIDC IdPs), granted scope, or refresh_token. Shape is IdP-specific.
+     */
+    tokenResponse: unknown;
+}
+export interface OAuthProviderConfig<Data extends {}> {
+    authorizeEndpoint: string;
+    tokenEndpoint: string;
+    clientId: string;
+    clientSecret: string;
+    /** Must cover whatever identify() fetches — scope and identify are a pair */
+    scope?: string;
+    /** Extra query params appended on silent re-authorization, e.g. { prompt: "none" } */
+    silentParams?: Record<string, string>;
+    /** Fetch the data about the visitor that the gate's filter will judge */
+    identify(input: OAuthIdentifyInput): Promise<Data | null>;
+}
+/**
+ * Build a GateProvider from a vanilla OAuth2 authorization-code flow.
+ * Covers the protocol plumbing (authorize URL, code→token exchange);
+ * you supply the endpoints and the data-fetching identify().
+ *
+ * IdPs with heavier dialects (PKCE-required, custom token auth) are better
+ * served by implementing GateProvider directly, e.g. on top of openid-client.
+ */
+export declare function oauthProvider<Data extends {}>(config: OAuthProviderConfig<Data>): GateProvider<Data>;

package/dist/oauth.js

@@ -0,0 +1,58 @@
+/**
+ * Build a GateProvider from a vanilla OAuth2 authorization-code flow.
+ * Covers the protocol plumbing (authorize URL, code→token exchange);
+ * you supply the endpoints and the data-fetching identify().
+ *
+ * IdPs with heavier dialects (PKCE-required, custom token auth) are better
+ * served by implementing GateProvider directly, e.g. on top of openid-client.
+ */
+export function oauthProvider(config) {
+    return {
+        authorizeUrl({ redirectUri, state, silent }) {
+            const url = new URL(config.authorizeEndpoint);
+            url.searchParams.set("client_id", config.clientId);
+            url.searchParams.set("response_type", "code");
+            url.searchParams.set("redirect_uri", redirectUri);
+            if (config.scope)
+                url.searchParams.set("scope", config.scope);
+            url.searchParams.set("state", state);
+            if (silent) {
+                for (const [key, value] of Object.entries(config.silentParams ?? {})) {
+                    url.searchParams.set(key, value);
+                }
+            }
+            return url.toString();
+        },
+        async identify({ code, redirectUri }) {
+            const res = await fetch(config.tokenEndpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    // some IdPs (GitHub) answer form-urlencoded unless asked for JSON
+                    Accept: "application/json",
+                },
+                body: new URLSearchParams({
+                    grant_type: "authorization_code",
+                    code,
+                    client_id: config.clientId,
+                    client_secret: config.clientSecret,
+                    redirect_uri: redirectUri,
+                }).toString(),
+            });
+            if (!res.ok)
+                return null;
+            const data = await res.json();
+            if (typeof data !== "object" ||
+                data === null ||
+                !("access_token" in data) ||
+                typeof data.access_token !== "string" ||
+                data.access_token === "") {
+                return null;
+            }
+            return config.identify({
+                accessToken: data.access_token,
+                tokenResponse: data,
+            });
+        },
+    };
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "workers-gate",
+  "version": "0.1.0",
+  "description": "Stateless authorization gate for apps on Cloudflare Workers — bring your own provider, no database, cookie signing delegated to jose",
+  "keywords": [
+    "authorization",
+    "cloudflare-workers",
+    "gate",
+    "oauth2",
+    "stateless"
+  ],
+  "homepage": "https://github.com/sunya9/workers-gate#readme",
+  "bugs": {
+    "url": "https://github.com/sunya9/workers-gate/issues"
+  },
+  "license": "MIT",
+  "author": "sunya (https://unsweets.net/)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sunya9/workers-gate.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "lint": "oxlint",
+    "typecheck": "tsc --noEmit",
+    "typecheck:examples": "pnpm --filter './examples/*' typecheck"
+  },
+  "dependencies": {
+    "jose": "^6.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "oxfmt": "^0.57.0",
+    "oxlint": "^1.72.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "packageManager": "pnpm@11.9.0"
+}