@stwrd-auth/node 0.0.0-stage → 0.1.0

package/dist/http.js

@@ -0,0 +1,27 @@
+/**
+ * Small HTTP plumbing shared by `client.ts`, `router.ts` and `guards.ts`.
+ * Nothing here is exported from `index.ts`.
+ *
+ * Cookies are read straight off the raw `Cookie` header rather than through
+ * `req.cookies` (which needs the `cookie-parser` middleware): this SDK works
+ * whether or not an app happens to have that installed, and parsing
+ * `name=value; name=value` pairs is plain string splitting.
+ */
+import { parseCookies } from "@stwrd-auth/core/web/cookies";
+export function readCookie(req, name) {
+    return parseCookies(req.headers.cookie)[name];
+}
+/** Every header value Express-family requests can hand back, coerced to the
+ * plain `Record<string, string>` the webhook verifier expects. A repeated header keeps its first
+ * value — Standard Webhooks never sends the three signing headers more than
+ * once. */
+export function headersToRecord(headers) {
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (value === undefined) {
+            continue;
+        }
+        out[key] = Array.isArray(value) ? (value[0] ?? "") : value;
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@stwrd-auth/node` — the Node SDK (BFF profile).
+ *
+ * This module's exports are the public surface; every name here is part of
+ * the package's API.
+ */
+export declare const VERSION = "0.1.0";
+export { COOKIE_SECRET_MIN_LEN, ConfigError, ENV_PREFIX, REQUIRED_ENV, resolveConfig, } from "@stwrd-auth/core/config";
+export { configFromEnv } from "./env.js";
+export type { OidcParams, ResolvedConfig, StwrdConfigOptions } from "@stwrd-auth/core/config";
+export { csrfToken, sign, unsign } from "@stwrd-auth/core/crypto";
+export { MemoryStore, accessExpiry, hasPermission, hasRole, userFromClaims, sessionContext, sessionResponse, contextFromClaims } from "@stwrd-auth/core/sessions";
+export type { Claims, SessionResponse, SessionContext, StwrdOrganization, ConsentState, RefreshClaim, RefreshPhase, SessionStore, StwrdSession, StwrdUser, Tokens, } from "@stwrd-auth/core/sessions";
+export { JWKS_DEFAULT_TTL_S, JWKS_TTL_CEILING_S, JWKS_TTL_FLOOR_S, JWKS_UNKNOWN_KID_REFETCH_FLOOR_S, IdpUnavailable, RefreshUncertain, LOGOUT_EVENT_URI, OidcClient, OidcError, RETRY_STATUSES, challengeS256, generateVerifier, halfHash, newAuthorizationState, newNonce, newState, } from "@stwrd-auth/core/oidc";
+export type { AuthorizationState, Awaitable, Discovery, FetchLike, Transaction } from "@stwrd-auth/core/oidc";
+export { DEDUP_WINDOW_S, HEADER_ID, HEADER_SIGNATURE, HEADER_TIMESTAMP, SIGNATURE_PREFIX, TOLERANCE_S, DuplicateEventError, InvalidSignatureError, SeenEventIds, safeEqual, signWebhook, verifyWebhook, verifyWebhookSignature, } from "./webhooks.js";
+export type { SeenStore, VerifyWebhookOptions, WebhookEvent } from "./webhooks.js";
+export { Stwrd, createStwrd } from "./client.js";
+export { makeHostFetch } from "./hostFetch.js";
+export type { HostFetchOptions } from "./hostFetch.js";
+export type { StwrdOptions } from "./client.js";
+export { apiMode, requireAuth, requireOrg, requirePermission, requireRole, safeTarget, } from "./guards.js";
+export type { StwrdContext } from "./guards.js";
+export type { AuthRouterOptions, ProtectAllOptions } from "./router.js";

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * `@stwrd-auth/node` — the Node SDK (BFF profile).
+ *
+ * This module's exports are the public surface; every name here is part of
+ * the package's API.
+ */
+export const VERSION = "0.1.0";
+// --- config ------------------------------------------------------------
+export { COOKIE_SECRET_MIN_LEN, ConfigError, ENV_PREFIX, REQUIRED_ENV, resolveConfig, } from "@stwrd-auth/core/config";
+export { configFromEnv } from "./env.js";
+// --- crypto / session primitives ---------------------------------------
+export { csrfToken, sign, unsign } from "@stwrd-auth/core/crypto";
+// --- sessions ------------------------------------------------------------
+export { MemoryStore, accessExpiry, hasPermission, hasRole, userFromClaims, sessionContext, sessionResponse, contextFromClaims } from "@stwrd-auth/core/sessions";
+// --- OIDC ------------------------------------------------------------
+export { JWKS_DEFAULT_TTL_S, JWKS_TTL_CEILING_S, JWKS_TTL_FLOOR_S, JWKS_UNKNOWN_KID_REFETCH_FLOOR_S, IdpUnavailable, RefreshUncertain, LOGOUT_EVENT_URI, OidcClient, OidcError, RETRY_STATUSES, challengeS256, generateVerifier, halfHash, newAuthorizationState, newNonce, newState, } from "@stwrd-auth/core/oidc";
+// --- webhooks ------------------------------------------------------------
+export { DEDUP_WINDOW_S, HEADER_ID, HEADER_SIGNATURE, HEADER_TIMESTAMP, SIGNATURE_PREFIX, TOLERANCE_S, DuplicateEventError, InvalidSignatureError, SeenEventIds, safeEqual, signWebhook, verifyWebhook, verifyWebhookSignature, } from "./webhooks.js";
+// --- the Stwrd instance --------------------------------------------------
+export { Stwrd, createStwrd } from "./client.js";
+// A `FetchLike` for developing against a local IdP that routes by `Host`.
+export { makeHostFetch } from "./hostFetch.js";
+// --- Express wiring: guards ------------------------------------------------
+export { apiMode, requireAuth, requireOrg, requirePermission, requireRole, safeTarget, } from "./guards.js";

package/dist/management.d.ts

@@ -0,0 +1 @@
+export * from "@stwrd-auth/core/management";

package/dist/management.js

@@ -0,0 +1 @@
+export * from "@stwrd-auth/core/management";

package/dist/postgres.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A shared `SessionStore` on PostgreSQL, for deployments with several workers.
+ *
+ * Sessions are encrypted as JWE (`dir` + `A256GCM`, via jose) with a keyring
+ * independent of the cookie secret. The authenticated payload also carries the
+ * namespace (tenant/client), the session id and the purpose, so a row copied
+ * to another namespace or id is rejected on read. Lease phase, fence and
+ * expiry stay in plain columns because coordination needs them in SQL and they
+ * hold no secret; lease expiry is judged by the database clock. The schema is
+ * explicit: run `SCHEMA_SQL` from your own migration, the store never creates
+ * tables. A namespace belongs to one SDK language: the payload shape is not
+ * shared with the Python store.
+ */
+import { Keyring } from "@stwrd-auth/core/keyring";
+import type { RefreshClaim, SessionStore, StwrdSession, Tokens } from "@stwrd-auth/core/sessions";
+export declare const SCHEMA_SQL = "\nCREATE SEQUENCE stwrd_sdk_fence_seq;\nCREATE TABLE stwrd_sdk_sessions (\n    namespace text NOT NULL,\n    session_id text NOT NULL,\n    payload text NOT NULL,\n    expires_at double precision NOT NULL,\n    fence bigint NOT NULL DEFAULT nextval('stwrd_sdk_fence_seq'),\n    lease_owner text,\n    lease_phase text CHECK (lease_phase IN ('acquired', 'sent', 'hydrating', 'uncertain')),\n    lease_expires_at timestamptz,\n    fresh_id_token boolean NOT NULL DEFAULT false,\n    PRIMARY KEY (namespace, session_id),\n    CHECK ((lease_phase IS NULL) = (lease_owner IS NULL))\n);\nCREATE INDEX stwrd_sdk_sessions_expiry ON stwrd_sdk_sessions (namespace, expires_at);\n";
+export { Keyring };
+/** The slice of `pg.Pool` the store uses, so `pg` stays optional. */
+export interface PgClient {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Array<Record<string, unknown>>;
+    }>;
+    release(error?: Error | boolean): void;
+}
+export interface PgPool {
+    connect(): Promise<PgClient>;
+}
+export declare class PostgresSessionStore implements SessionStore {
+    private readonly pool;
+    private readonly options;
+    constructor(pool: PgPool, options: {
+        namespace: string;
+        keyring: Keyring;
+        onUnreadable?: (error: unknown) => void;
+    });
+    private get namespace();
+    private seal;
+    private open;
+    private withClient;
+    private transaction;
+    get(sessionId: string): Promise<StwrdSession | null>;
+    set(session: StwrdSession): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    /** Delete this namespace's sessions past their local expiry (and with them
+     * their stored refresh tokens). Run it periodically. */
+    purgeExpired(): Promise<number>;
+    replaceSession(oldId: string, session: StwrdSession): Promise<boolean>;
+    claimRefresh(sessionId: string, owner: string, leaseS: number): Promise<RefreshClaim>;
+    markRefreshSent(sessionId: string, fence: number): Promise<boolean>;
+    checkpointRefresh(sessionId: string, fence: number, tokens: Tokens, freshIdToken: boolean): Promise<boolean>;
+    completeRefresh(sessionId: string, fence: number, session: StwrdSession): Promise<boolean>;
+    releaseRefresh(sessionId: string, fence: number, sent: boolean): Promise<void>;
+}

package/dist/postgres.js

@@ -0,0 +1,207 @@
+/**
+ * A shared `SessionStore` on PostgreSQL, for deployments with several workers.
+ *
+ * Sessions are encrypted as JWE (`dir` + `A256GCM`, via jose) with a keyring
+ * independent of the cookie secret. The authenticated payload also carries the
+ * namespace (tenant/client), the session id and the purpose, so a row copied
+ * to another namespace or id is rejected on read. Lease phase, fence and
+ * expiry stay in plain columns because coordination needs them in SQL and they
+ * hold no secret; lease expiry is judged by the database clock. The schema is
+ * explicit: run `SCHEMA_SQL` from your own migration, the store never creates
+ * tables. A namespace belongs to one SDK language: the payload shape is not
+ * shared with the Python store.
+ */
+import { Keyring } from "@stwrd-auth/core/keyring";
+import { withoutCapabilities } from "@stwrd-auth/core/sessions";
+export const SCHEMA_SQL = `
+CREATE SEQUENCE stwrd_sdk_fence_seq;
+CREATE TABLE stwrd_sdk_sessions (
+    namespace text NOT NULL,
+    session_id text NOT NULL,
+    payload text NOT NULL,
+    expires_at double precision NOT NULL,
+    fence bigint NOT NULL DEFAULT nextval('stwrd_sdk_fence_seq'),
+    lease_owner text,
+    lease_phase text CHECK (lease_phase IN ('acquired', 'sent', 'hydrating', 'uncertain')),
+    lease_expires_at timestamptz,
+    fresh_id_token boolean NOT NULL DEFAULT false,
+    PRIMARY KEY (namespace, session_id),
+    CHECK ((lease_phase IS NULL) = (lease_owner IS NULL))
+);
+CREATE INDEX stwrd_sdk_sessions_expiry ON stwrd_sdk_sessions (namespace, expires_at);
+`;
+// `Keyring` lives in the core (the Durable Object store of `@stwrd-auth/workers` needs
+// it too); this entry point keeps exporting it.
+export { Keyring };
+const TABLE = "stwrd_sdk_sessions";
+function defaultUnreadable(error) {
+    console.warn("stwrd: unreadable session row", error);
+}
+export class PostgresSessionStore {
+    pool;
+    options;
+    constructor(pool, options) {
+        this.pool = pool;
+        this.options = options;
+        if (!options.namespace)
+            throw new Error("A namespace (tenant/client) is required.");
+    }
+    get namespace() {
+        return this.options.namespace;
+    }
+    async seal(session) {
+        return this.options.keyring.encrypt(JSON.stringify({ ns: this.namespace, sid: session.id, purpose: "session", session }));
+    }
+    async open(sessionId, payload) {
+        try {
+            const body = JSON.parse(await this.options.keyring.decrypt(payload));
+            if (body.ns !== this.namespace || body.sid !== sessionId || body.purpose !== "session") {
+                throw new Error("Row context does not match its location.");
+            }
+            return body.session;
+        }
+        catch (error) {
+            // Fail closed: a tampered, relocated or unreadable row is no session.
+            (this.options.onUnreadable ?? defaultUnreadable)(error);
+            return null;
+        }
+    }
+    async withClient(run) {
+        const client = await this.pool.connect();
+        let broken = false;
+        try {
+            return await run(client);
+        }
+        catch (error) {
+            broken = error.brokenConnection === true;
+            throw error;
+        }
+        finally {
+            // A connection whose ROLLBACK failed is destroyed, never reused.
+            client.release(broken);
+        }
+    }
+    async transaction(run) {
+        return this.withClient(async (client) => {
+            await client.query("BEGIN");
+            try {
+                const result = await run(client);
+                await client.query("COMMIT");
+                return result;
+            }
+            catch (error) {
+                try {
+                    await client.query("ROLLBACK");
+                }
+                catch {
+                    throw Object.assign(error, { brokenConnection: true });
+                }
+                throw error;
+            }
+        });
+    }
+    async get(sessionId) {
+        const { rows } = await this.withClient(client => client.query(`SELECT payload FROM ${TABLE} WHERE namespace = $1 AND session_id = $2`, [this.namespace, sessionId]));
+        return rows.length ? this.open(sessionId, rows[0].payload) : null;
+    }
+    async set(session) {
+        const payload = await this.seal(session);
+        await this.withClient(client => client.query(`INSERT INTO ${TABLE} (namespace, session_id, payload, expires_at) VALUES ($1, $2, $3, $4)
+       ON CONFLICT (namespace, session_id) DO UPDATE SET
+         payload = EXCLUDED.payload, expires_at = EXCLUDED.expires_at,
+         fence = nextval('stwrd_sdk_fence_seq'), lease_owner = NULL, lease_phase = NULL,
+         lease_expires_at = NULL, fresh_id_token = false`, [this.namespace, session.id, payload, session.expiresAt]));
+    }
+    async delete(sessionId) {
+        await this.withClient(client => client.query(`DELETE FROM ${TABLE} WHERE namespace = $1 AND session_id = $2`, [this.namespace, sessionId]));
+    }
+    /** Delete this namespace's sessions past their local expiry (and with them
+     * their stored refresh tokens). Run it periodically. */
+    async purgeExpired() {
+        const result = await this.withClient(client => client.query(`DELETE FROM ${TABLE} WHERE namespace = $1 AND expires_at < $2 RETURNING 1`, [this.namespace, Date.now() / 1000]));
+        return result.rows.length;
+    }
+    async replaceSession(oldId, session) {
+        const payload = await this.seal(session);
+        return this.transaction(async (client) => {
+            const removed = await client.query(`DELETE FROM ${TABLE} WHERE namespace = $1 AND session_id = $2 RETURNING 1`, [this.namespace, oldId]);
+            if (!removed.rows.length)
+                return false;
+            await client.query(`INSERT INTO ${TABLE} (namespace, session_id, payload, expires_at) VALUES ($1, $2, $3, $4)
+         ON CONFLICT (namespace, session_id) DO UPDATE SET
+           payload = EXCLUDED.payload, expires_at = EXCLUDED.expires_at,
+           fence = nextval('stwrd_sdk_fence_seq'), lease_owner = NULL, lease_phase = NULL,
+           lease_expires_at = NULL, fresh_id_token = false`, [this.namespace, session.id, payload, session.expiresAt]);
+            return true;
+        });
+    }
+    async claimRefresh(sessionId, owner, leaseS) {
+        return this.transaction(async (client) => {
+            const { rows } = await client.query(`SELECT payload, lease_phase, fresh_id_token,
+                coalesce(lease_expires_at <= clock_timestamp(), false) AS expired
+         FROM ${TABLE} WHERE namespace = $1 AND session_id = $2 FOR UPDATE`, [this.namespace, sessionId]);
+            if (!rows.length)
+                return { status: "gone" };
+            const row = rows[0];
+            const session = await this.open(sessionId, row.payload);
+            if (!session)
+                return { status: "gone" };
+            const phase = row.lease_phase;
+            if (phase === "uncertain")
+                return { status: "uncertain" };
+            if (phase !== null && !row.expired)
+                return { status: "busy" };
+            if (phase === "sent") {
+                await client.query(`UPDATE ${TABLE} SET lease_phase = 'uncertain' WHERE namespace = $1 AND session_id = $2`, [this.namespace, sessionId]);
+                return { status: "uncertain" };
+            }
+            const granted = phase === "hydrating" ? "hydrating" : "acquired";
+            const updated = await client.query(`UPDATE ${TABLE} SET fence = nextval('stwrd_sdk_fence_seq'), lease_owner = $1, lease_phase = $2,
+           lease_expires_at = clock_timestamp() + make_interval(secs => $3)
+         WHERE namespace = $4 AND session_id = $5 RETURNING fence`, [owner, granted, leaseS, this.namespace, sessionId]);
+            return { status: "granted", session, fence: Number(updated.rows[0].fence), phase: granted, freshIdToken: Boolean(row.fresh_id_token) };
+        });
+    }
+    async markRefreshSent(sessionId, fence) {
+        const { rows } = await this.withClient(client => client.query(`UPDATE ${TABLE} SET lease_phase = 'sent'
+       WHERE namespace = $1 AND session_id = $2 AND fence = $3 AND lease_phase = 'acquired' RETURNING 1`, [this.namespace, sessionId, fence]));
+        return rows.length > 0;
+    }
+    async checkpointRefresh(sessionId, fence, tokens, freshIdToken) {
+        return this.transaction(async (client) => {
+            const { rows } = await client.query(`SELECT payload FROM ${TABLE} WHERE namespace = $1 AND session_id = $2 AND fence = $3 AND lease_phase = 'sent' FOR UPDATE`, [this.namespace, sessionId, fence]);
+            const current = rows.length ? await this.open(sessionId, rows[0].payload) : null;
+            if (!current)
+                return false;
+            const payload = await this.seal({ ...current, claims: withoutCapabilities(current.claims), tokens });
+            await client.query(`UPDATE ${TABLE} SET payload = $1, lease_phase = 'hydrating', fresh_id_token = $2 WHERE namespace = $3 AND session_id = $4`, [payload, freshIdToken, this.namespace, sessionId]);
+            return true;
+        });
+    }
+    async completeRefresh(sessionId, fence, session) {
+        if (session.id !== sessionId)
+            return false;
+        const payload = await this.seal(session);
+        const { rows } = await this.withClient(client => client.query(`UPDATE ${TABLE} SET payload = $1, expires_at = $2, lease_owner = NULL, lease_phase = NULL,
+         lease_expires_at = NULL, fresh_id_token = false
+       WHERE namespace = $3 AND session_id = $4 AND fence = $5
+         AND lease_phase IS NOT NULL AND lease_phase <> 'uncertain' RETURNING 1`, [payload, session.expiresAt, this.namespace, sessionId, fence]));
+        return rows.length > 0;
+    }
+    async releaseRefresh(sessionId, fence, sent) {
+        await this.withClient(client => client.query(`UPDATE ${TABLE} SET
+         lease_phase = CASE
+           WHEN lease_phase = 'sent' AND $1::boolean THEN 'uncertain'
+           WHEN lease_phase = 'hydrating' THEN 'hydrating'
+           ELSE NULL END,
+         lease_owner = CASE
+           WHEN lease_phase = 'hydrating' OR (lease_phase = 'sent' AND $1::boolean) THEN lease_owner
+           ELSE NULL END,
+         lease_expires_at = CASE
+           WHEN lease_phase = 'hydrating' THEN clock_timestamp()
+           WHEN lease_phase = 'sent' AND $1::boolean THEN lease_expires_at
+           ELSE NULL END
+       WHERE namespace = $2 AND session_id = $3 AND fence = $4
+         AND lease_phase IS NOT NULL AND lease_phase <> 'uncertain'`, [sent, this.namespace, sessionId, fence]));
+    }
+}

package/dist/router.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `authRouter` and `protectAll` — a thin Express shim over the core's
+ * `authHandler` (`@stwrd-auth/core/web/authHandler`), which serves the routes
+ * under `stwrd.config.prefix`, and over `checkAccess` for the opt-in
+ * fail-closed middleware. The Python SDK's FastAPI integration behaves the
+ * same way.
+ */
+import { type RequestHandler, type Router } from "express";
+import type { StwrdUser } from "@stwrd-auth/core/sessions";
+import type { WebhookEvent } from "@stwrd-auth/core/webhooks";
+import type { Stwrd } from "./client.js";
+export interface AuthRouterOptions {
+    onUserRegistered?: (user: StwrdUser) => unknown | Promise<unknown>;
+    onEvent?: (event: WebhookEvent) => unknown | Promise<unknown>;
+}
+/**
+ * Serves the `/auth/*` routes under `stwrd.config.prefix`: every
+ * request goes to the core's handler, and one it does not serve (another path,
+ * a method the route does not take) falls through to the app.
+ *
+ * `onUserRegistered(user)` runs once per successful `/auth/callback`.
+ * Whether this is the very first login for that `sub` is the app's own
+ * question, so the hook fires on every login and an idempotent upsert on
+ * the app's side is what makes "registered" mean the first one.
+ * `onEvent(event)` runs once per accepted `/auth/webhook` delivery, after
+ * dedup.
+ */
+export declare function authRouter(stwrd: Stwrd, options?: AuthRouterOptions): Router;
+export interface ProtectAllOptions {
+    public?: Iterable<string>;
+}
+/** Fail-closed mode is opt-in (`protectAll({public})`): it requires a session
+ * on every path that is not declared public. Implementation behind
+ * `Stwrd.protectAll`. */
+export declare function protectAllMiddleware(stwrd: Stwrd, options?: ProtectAllOptions): RequestHandler;

package/dist/router.js

@@ -0,0 +1,71 @@
+/**
+ * `authRouter` and `protectAll` — a thin Express shim over the core's
+ * `authHandler` (`@stwrd-auth/core/web/authHandler`), which serves the routes
+ * under `stwrd.config.prefix`, and over `checkAccess` for the opt-in
+ * fail-closed middleware. The Python SDK's FastAPI integration behaves the
+ * same way.
+ */
+import express from "express";
+import { authHandler } from "@stwrd-auth/core/web/authHandler";
+import { checkAccess, isPublicPath } from "@stwrd-auth/core/web/access";
+import { readCookie } from "./http.js";
+import { sendWebResponse, toWebRequest } from "./webBridge.js";
+import { resolveRequest } from "./guards.js";
+/**
+ * Serves the `/auth/*` routes under `stwrd.config.prefix`: every
+ * request goes to the core's handler, and one it does not serve (another path,
+ * a method the route does not take) falls through to the app.
+ *
+ * `onUserRegistered(user)` runs once per successful `/auth/callback`.
+ * Whether this is the very first login for that `sub` is the app's own
+ * question, so the hook fires on every login and an idempotent upsert on
+ * the app's side is what makes "registered" mean the first one.
+ * `onEvent(event)` runs once per accepted `/auth/webhook` delivery, after
+ * dedup.
+ */
+export function authRouter(stwrd, options = {}) {
+    const handle = authHandler(stwrd, options);
+    const prefix = stwrd.config.prefix.replace(/\/$/, "").toLowerCase();
+    const router = express.Router();
+    router.use((req, res, next) => {
+        // Cheap exit for everything outside the prefix: no `Request` is built and
+        // the app's own body is left alone.
+        if (!req.path.toLowerCase().startsWith(`${prefix}/`)) {
+            next();
+            return;
+        }
+        void (async () => {
+            const webRequest = toWebRequest(req, stwrd);
+            const response = webRequest === null ? null : await handle(webRequest);
+            if (response === null) {
+                next();
+                return;
+            }
+            await sendWebResponse(res, response);
+        })().catch(next);
+    });
+    return router;
+}
+/** Fail-closed mode is opt-in (`protectAll({public})`): it requires a session
+ * on every path that is not declared public. Implementation behind
+ * `Stwrd.protectAll`. */
+export function protectAllMiddleware(stwrd, options = {}) {
+    const publicList = [...(options.public ?? [])];
+    return (req, res, next) => {
+        void (async () => {
+            if (isPublicPath(req.path, publicList, stwrd.config.prefix)) {
+                next();
+                return;
+            }
+            const resolved = await resolveRequest(stwrd, req);
+            const result = await checkAccess(stwrd, { cookie: readCookie(req, stwrd.config.sessionCookie), accept: req.headers.accept, target: req.originalUrl ?? req.url, api: req.stwrdApiMode, resolved }, { auth: true });
+            if (!result.ok) {
+                // A silent IdP is a 503, not the 401 or the redirect to sign-in: both
+                // tell someone with a live session that they lost it.
+                await sendWebResponse(res, result.response);
+                return;
+            }
+            next();
+        })().catch(next);
+    };
+}

package/dist/webBridge.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The seam between Express and the core's `Request → Response` handlers:
+ * `toWebRequest` builds the Fetch `Request` the core reads, `sendWebResponse`
+ * writes the core's `Response` back. Nothing here decides anything about
+ * authentication; it only translates. Internal — not exported from `index.ts`.
+ *
+ * Two rules make the translation safe:
+ *
+ * - The URL is relative to where the router is mounted (`req.url`, not
+ *   `originalUrl`: `app.use("/api", stwrd.authRouter())` still serves
+ *   `/api/auth/sign-in`) and its origin comes from `config.baseUrl`, never from
+ *   the `Host` header: a spoofed `Host` cannot move a `redirect_uri`.
+ * - A body is only read when the core asks for it, so a request this router
+ *   does not serve reaches the app's own handlers with its body intact.
+ */
+import type { Response as ExpressResponse, Request as ExpressRequest } from "express";
+import type { StwrdCore } from "@stwrd-auth/core/client";
+/** The Fetch `Request` for an Express one, or `null` when the URL parser would
+ * rewrite its path (`/auth/x/../session`, `/auth/x/..\\session`): the router
+ * does not serve such a path, and answering it would let a request slip past a
+ * WAF or CDN rule on the exact path. The app gets it as it came. */
+export declare function toWebRequest(req: ExpressRequest, stwrd: StwrdCore): globalThis.Request | null;
+/** Status, headers and every `Set-Cookie` of the core's response, then its body. */
+export declare function sendWebResponse(res: ExpressResponse, response: globalThis.Response): Promise<void>;

package/dist/webBridge.js

@@ -0,0 +1,143 @@
+/**
+ * The seam between Express and the core's `Request → Response` handlers:
+ * `toWebRequest` builds the Fetch `Request` the core reads, `sendWebResponse`
+ * writes the core's `Response` back. Nothing here decides anything about
+ * authentication; it only translates. Internal — not exported from `index.ts`.
+ *
+ * Two rules make the translation safe:
+ *
+ * - The URL is relative to where the router is mounted (`req.url`, not
+ *   `originalUrl`: `app.use("/api", stwrd.authRouter())` still serves
+ *   `/api/auth/sign-in`) and its origin comes from `config.baseUrl`, never from
+ *   the `Host` header: a spoofed `Host` cannot move a `redirect_uri`.
+ * - A body is only read when the core asks for it, so a request this router
+ *   does not serve reaches the app's own handlers with its body intact.
+ */
+/** A body the app's own global parser (`express.json()`, `express.urlencoded()`,
+ * `express.raw()`) already consumed: the stream is gone, `req.body` is what is left. */
+function wasConsumed(req) {
+    return req._body === true || req.readableDidRead === true || req.readableEnded;
+}
+function isWebhookPath(pathname, prefix) {
+    const path = pathname.length > 1 && pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+    return path.toLowerCase() === `${prefix.replace(/\/$/, "")}/webhook`.toLowerCase();
+}
+/** Puts back on the wire what a global parser took off it, by content type, so
+ * the routes that read a form or JSON (sign-out, organization, back-channel)
+ * still see it. The webhook is the exception: it verifies a signature over the
+ * exact bytes, which a parsed object cannot give back, so it
+ * only accepts a raw `Buffer` body and otherwise reads as empty (400
+ * `invalid_signature`). */
+function reserialize(req, webhook) {
+    const body = req.body;
+    if (Buffer.isBuffer(body)) {
+        return { body };
+    }
+    if (webhook || body === undefined || body === null) {
+        return { body: null };
+    }
+    if (typeof body === "string") {
+        return { body };
+    }
+    const type = (req.headers["content-type"] ?? "").split(";")[0].trim().toLowerCase();
+    if (type === "application/x-www-form-urlencoded" && typeof body === "object") {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(body)) {
+            for (const item of Array.isArray(value) ? value : [value]) {
+                if (typeof item === "string" || typeof item === "number" || typeof item === "boolean") {
+                    params.append(key, String(item));
+                }
+            }
+        }
+        return { body: params.toString() };
+    }
+    if (type === "application/json") {
+        return { body: JSON.stringify(body) };
+    }
+    return { body: null };
+}
+/** The request stream as a Fetch body that attaches to the Node stream only on
+ * the first read, and drains (instead of destroying the connection) when the
+ * core stops reading because a ceiling was crossed: the 413 still has a socket
+ * to travel on. */
+function lazyBody(req) {
+    let started = false;
+    let cancelled = false;
+    return new ReadableStream({
+        pull(controller) {
+            if (started) {
+                req.resume();
+                return;
+            }
+            started = true;
+            req.on("data", (chunk) => {
+                if (cancelled)
+                    return;
+                controller.enqueue(new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength));
+                if ((controller.desiredSize ?? 0) <= 0)
+                    req.pause();
+            });
+            req.on("end", () => {
+                if (!cancelled)
+                    controller.close();
+            });
+            req.on("error", (error) => {
+                if (!cancelled)
+                    controller.error(error);
+            });
+            req.on("close", () => {
+                if (!cancelled && !req.complete)
+                    controller.error(new Error("The request was aborted."));
+            });
+        },
+        cancel() {
+            cancelled = true;
+            req.resume();
+        },
+    }, { highWaterMark: 0 });
+}
+/** The Fetch `Request` for an Express one, or `null` when the URL parser would
+ * rewrite its path (`/auth/x/../session`, `/auth/x/..\\session`): the router
+ * does not serve such a path, and answering it would let a request slip past a
+ * WAF or CDN rule on the exact path. The app gets it as it came. */
+export function toWebRequest(req, stwrd) {
+    const target = req.url.startsWith("/") ? req.url : `/${req.url}`;
+    const url = new URL(new URL(stwrd.config.baseUrl).origin + target);
+    if (url.pathname !== target.split(/[?#]/, 1)[0]) {
+        return null;
+    }
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined || name.startsWith(":"))
+            continue;
+        for (const item of Array.isArray(value) ? value : [value])
+            headers.append(name, item);
+    }
+    if (req.method === "GET" || req.method === "HEAD") {
+        return new Request(url, { method: req.method, headers });
+    }
+    if (wasConsumed(req)) {
+        const { body } = reserialize(req, isWebhookPath(url.pathname, stwrd.config.prefix));
+        // The bytes put back are not the ones the headers describe.
+        headers.delete("content-length");
+        headers.delete("transfer-encoding");
+        return new Request(url, { method: req.method, headers, body: body });
+    }
+    return new Request(url, { method: req.method, headers, body: lazyBody(req), duplex: "half" });
+}
+/** Status, headers and every `Set-Cookie` of the core's response, then its body. */
+export async function sendWebResponse(res, response) {
+    res.status(response.status);
+    response.headers.forEach((value, name) => {
+        if (name.toLowerCase() !== "set-cookie")
+            res.setHeader(name, value);
+    });
+    for (const cookie of response.headers.getSetCookie()) {
+        res.append("Set-Cookie", cookie);
+    }
+    if (response.body === null) {
+        res.end();
+        return;
+    }
+    res.end(Buffer.from(await response.arrayBuffer()));
+}

package/dist/webhooks.d.ts

@@ -0,0 +1 @@
+export * from "@stwrd-auth/core/webhooks";

package/dist/webhooks.js

@@ -0,0 +1 @@
+export * from "@stwrd-auth/core/webhooks";