workers-gate 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,9 @@
 # workers-gate
 
+[![npm](https://img.shields.io/npm/v/workers-gate)](https://www.npmjs.com/package/workers-gate)
+[![CI](https://github.com/sunya9/workers-gate/actions/workflows/ci.yml/badge.svg)](https://github.com/sunya9/workers-gate/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/workers-gate)](./LICENSE)
+
 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.
@@ -138,7 +142,7 @@ OIDC — implement `GateProvider` with openid-client, return the ID-token claims
 
 | Field                                       | Default                                       | Description                                                                      |
 | ------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------- |
-| `cookieSecret`                              | required                                      | HMAC key for session/state cookies                                               |
+| `cookieSecret`                              | required                                      | HMAC key for session/state cookies, 32+ characters                               |
 | `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` |
@@ -146,7 +150,17 @@ OIDC — implement `GateProvider` with openid-client, return the ID-token claims
 | `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                                                                     |
+| `cookieName` / `stateCookieName`            | `__Host-gate` `__Host-gate_state`             | Cookie names                                                                     |
+| `sessionVersion`                            | unset                                         | Bump to send every outstanding session back through re-authorization             |
+
+## Security notes
+
+- Sessions are bound to the request origin via the JWT `aud` claim: a cookie minted on one hostname does not pass on another, and reusing a `cookieSecret` across apps no longer lets their sessions cross.
+- `createGate` rejects a `cookieSecret` shorter than 32 characters.
+- `sessionVersion` is the stateless revocation lever: bumping it invalidates every session at once, and holders are silently re-authorized — which re-runs `identify` and your `filter`.
+- Exceptions from `identify`/`filter` and malformed token-endpoint responses fail closed to the denied response; the cause is logged via `console.error` (visible in `wrangler tail`).
+- Cookies default to `__Host-` prefixed names for cookie-tossing resistance: no parent or sibling (sub)domain can plant or shadow them. Override with plain names only if you must; a non-prefixed `stateCookieName` also narrows the state cookie back to the callback path.
+- Local dev note: all gate cookies carry `Secure`, which Safari drops on plain-HTTP localhost — use Chrome or Firefox with `wrangler dev` (both treat localhost as trustworthy).
 
 ## Screens are yours
 
@@ -196,6 +210,6 @@ If the silent pass fails (signed out of the IdP), the gate falls back to an inte
 
 ## 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.
+- Stateless means no per-visitor revocation: someone who no longer satisfies your policy keeps access until their cookie expires (default 24h). Shorten `sessionTtlSeconds`, or bump `sessionVersion` to cut off everyone at once.
 - 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

@@ -4,5 +4,5 @@ export interface VerifiedToken {
     /** 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>;
+export declare function sign(payload: JWTPayload, secret: string, audience?: string): Promise<string>;
+export declare function verify(token: string, secret: string, audience?: string): Promise<VerifiedToken | null>;

package/dist/cookie.js

@@ -1,12 +1,16 @@
 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 function sign(payload, secret, audience) {
+    const jwt = new SignJWT(payload).setProtectedHeader({ alg: "HS256" });
+    if (audience)
+        jwt.setAudience(audience);
+    return jwt.sign(encoder.encode(secret));
 }
-export async function verify(token, secret) {
+export async function verify(token, secret, audience) {
     try {
         const { payload } = await jwtVerify(token, encoder.encode(secret), {
             algorithms: ["HS256"],
+            ...(audience ? { audience } : {}),
         });
         return { payload, expired: false };
     }

package/dist/gate.d.ts

@@ -64,6 +64,12 @@ export interface GateConfig<Data extends {} = {}> {
         request: Request;
         loginUrl: string;
     }) => Response | Promise<Response>;
+    /**
+     * Stamped into every session; sessions carrying a different value are sent
+     * back through (silent) re-authorization. Bump it to invalidate all
+     * outstanding sessions at once — the stateless substitute for revocation.
+     */
+    sessionVersion?: string | number;
     loginPath?: string;
     callbackPath?: string;
     logoutPath?: string;

package/dist/gate.js

@@ -30,10 +30,13 @@ function isStatePayload(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");
+    const { cookieSecret, provider, filter, denied, unauthorized, signin, sessionVersion, loginPath = "/auth/login", callbackPath = "/auth/callback", logoutPath = "/auth/logout", sessionTtlSeconds = 60 * 60 * 24, cookieName = "__Host-gate", stateCookieName = "__Host-gate_state", } = config;
+    if (cookieSecret.length < 32) {
+        throw new TypeError("createGate: cookieSecret must be at least 32 characters (e.g. openssl rand -hex 32)");
     }
+    // __Host- prefixed cookies require Path=/; otherwise keep the state
+    // cookie scoped to the callback route only
+    const stateCookiePath = stateCookieName.startsWith("__Host-") ? "/" : callbackPath;
     return async function gate(request) {
         const url = new URL(request.url);
         const redirectUri = `${url.origin}${callbackPath}`;
@@ -50,14 +53,14 @@ export function createGate(config) {
         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 stateToken = await sign({ state, returnTo, exp: nowSec() + 600 }, cookieSecret, url.origin);
             const res = redirect(provider.authorizeUrl({ redirectUri, state, silent }));
-            res.headers.set("Set-Cookie", `${stateCookieName}=${stateToken}; Path=${callbackPath}; HttpOnly; Secure; SameSite=Lax; Max-Age=600`);
+            res.headers.set("Set-Cookie", `${stateCookieName}=${stateToken}; Path=${stateCookiePath}; 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 verified = stateToken ? await verify(stateToken, cookieSecret, url.origin) : 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
@@ -70,9 +73,26 @@ export function createGate(config) {
             if (!statePayload || !code || !state || state !== statePayload.state) {
                 return new Response("Invalid OAuth state", { status: 400 });
             }
-            const data = await provider.identify({ code, redirectUri });
+            // exceptions fail closed: an IdP outage or a filter bug must deny,
+            // never crash into the platform error page; keep the cause in logs
+            let data;
+            try {
+                data = await provider.identify({ code, redirectUri });
+            }
+            catch (error) {
+                console.error("workers-gate: provider.identify threw", error);
+                data = null;
+            }
             // loose != so a sloppy provider resolving undefined fails closed
-            const allowed = data != null && (filter ? await filter(data, { request }) : true);
+            let allowed = false;
+            if (data != null) {
+                try {
+                    allowed = filter ? await filter(data, { request }) : true;
+                }
+                catch (error) {
+                    console.error("workers-gate: filter threw", error);
+                }
+            }
             if (!allowed) {
                 const retryUrl = `${loginPath}?returnTo=${encodeURIComponent(safeReturnTo(statePayload.returnTo))}`;
                 if (denied)
@@ -82,10 +102,13 @@ export function createGate(config) {
                     headers: { "Content-Type": "text/html; charset=utf-8" },
                 });
             }
-            const session = await sign({ exp: nowSec() + sessionTtlSeconds }, cookieSecret);
+            const session = await sign({
+                exp: nowSec() + sessionTtlSeconds,
+                ...(sessionVersion !== undefined ? { v: sessionVersion } : {}),
+            }, cookieSecret, url.origin);
             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`);
+            res.headers.append("Set-Cookie", `${stateCookieName}=; Path=${stateCookiePath}; HttpOnly; Secure; SameSite=Lax; Max-Age=0`);
             return res;
         };
         const logout = () => {
@@ -102,9 +125,12 @@ export function createGate(config) {
                 return logout();
         }
         const sessionToken = readCookie(cookieName);
-        const verified = sessionToken ? await verify(sessionToken, cookieSecret) : null;
+        const verified = sessionToken ? await verify(sessionToken, cookieSecret, url.origin) : null;
         const session = verified && isSessionPayload(verified.payload) ? verified.payload : null;
-        if (session && !verified?.expired) {
+        // a stale sessionVersion is treated like expiry: the visitor is real,
+        // but the policy changed — send them back through re-authorization
+        const versionOk = sessionVersion === undefined || session?.v === sessionVersion;
+        if (session && !verified?.expired && versionOk) {
             return null; // authorized — the request is yours
         }
         const returnTo = encodeURIComponent(url.pathname + url.search);

package/dist/oauth.js

@@ -41,7 +41,14 @@ export function oauthProvider(config) {
             });
             if (!res.ok)
                 return null;
-            const data = await res.json();
+            // a token endpoint answering non-JSON is out of contract: fail closed
+            let data;
+            try {
+                data = await res.json();
+            }
+            catch {
+                return null;
+            }
             if (typeof data !== "object" ||
                 data === null ||
                 !("access_token" in data) ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workers-gate",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Stateless authorization gate for apps on Cloudflare Workers — bring your own provider, no database, cookie signing delegated to jose",
   "keywords": [
     "authorization",