@stwrd-auth/node 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this package are documented in this file.
+
+The format is based on Keep a Changelog 1.1.0, and this package adheres to Semantic Versioning (SemVer).
+
+## [0.1.0] - Unreleased
+
+Initial release.
+
+### Added
+
+- `Stwrd` and `createStwrd`, with `Stwrd.fromEnv()` reading the `STWRD_*` environment variables.
+- `authRouter()`: Express router for the `/auth/sign-in`, `/auth/callback`, `/auth/sign-out`, `/auth/session`, `/auth/organizations`, `/auth/organization`, `/auth/back-channel` and `/auth/webhook` routes, with `onUserRegistered` and `onEvent` hooks.
+- `attach()` middleware that resolves the session once per request into `req.stwrd`.
+- Guards: `requireAuth`, `requireRole`, `requirePermission`, `requireOrg` and `apiMode`.
+- `protectAll()`: opt-in fail-closed protection of an entire app by path.
+- Server-side sessions, signed `__Host-` session cookie, CSRF protection and automatic token renewal.
+- Organization selection when the `org` scope is requested.
+- Webhook verification (`@stwrd-auth/node/webhooks`).
+- Typed Management API client (`@stwrd-auth/node/management`).
+- PostgreSQL session store with encrypted sessions and a refresh lease (`@stwrd-auth/node/postgres`).
+- `makeHostFetch` for developing against a local identity provider that routes by `Host`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stwrd
+
+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

@@ -1,3 +1,244 @@
-# Temporary Holding Version
+# @stwrd-auth/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+stwrd SDK for Node.js and Express (backend-for-frontend profile): the `/auth/*` routes, server-side sessions, route guards and webhook verification.
+
+## What it is
+
+[stwrd](https://stwrd.dev) is a multi-tenant identity provider. In the backend-for-frontend (BFF) profile the server performs the OpenID Connect flow and keeps the tokens; the browser only holds a signed session cookie. This package mounts the sign-in, callback, sign-out and session routes in an Express app and gives you guards to protect your own routes. It exposes the same routes, the same `GET /auth/session` JSON and the same environment variables as the Python SDK (`stwrd-auth` on PyPI).
+
+Related packages:
+
+- [`@stwrd-auth/core`](https://www.npmjs.com/package/@stwrd-auth/core): the runtime-neutral logic this package builds on (installed automatically).
+- [`@stwrd-auth/react`](https://www.npmjs.com/package/@stwrd-auth/react): session hooks and components for the front end.
+- [`@stwrd-auth/workers`](https://www.npmjs.com/package/@stwrd-auth/workers): the same SDK for Cloudflare Workers.
+
+## Installation
+
+```sh
+npm install @stwrd-auth/node express
+```
+
+Requires Node.js 20 or newer. `express` (`^4 || ^5`) is a peer dependency: the package uses the Express your app already has. `pg` (`^8`) is an optional peer dependency, needed only for the PostgreSQL session store. The package is ESM only and ships its own TypeScript declarations.
+
+## Minimal example
+
+Set the environment variables below, then:
+
+```ts
+import express from "express";
+import { Stwrd, requireAuth, requirePermission, requireRole, safeTarget } from "@stwrd-auth/node";
+
+const stwrd = Stwrd.fromEnv();
+const app = express();
+
+app.use(stwrd.attach()); // resolves the session once and leaves it in req.stwrd
+app.use(
+  stwrd.authRouter({
+    onEvent: (event) => console.log("webhook", event.type, event.data),
+  }),
+);
+
+app.get("/", (req, res) => {
+  const user = req.stwrd?.user ?? null;
+  if (!user) {
+    res.send('<a href="/auth/sign-in?return_to=/private">Sign in</a>');
+    return;
+  }
+  res.send(`<p>Hello, ${user.email}.</p><a href="/private">Private area</a>`);
+});
+
+app.get("/private", requireAuth(stwrd), (req, res) => {
+  const { user, session } = req.stwrd!;
+  // Sign-out is a POST with a CSRF token; this is the one /auth/session hands out.
+  const csrf = stwrd.csrf(session!.id);
+  res.send(
+    `<p>Welcome, ${user!.email}. Your id is ${user!.id}.</p>` +
+      '<form method="post" action="/auth/sign-out">' +
+      `<input type="hidden" name="csrf_token" value="${csrf}"><button>Sign out</button></form>`,
+  );
+});
+
+app.get("/admin", requireRole(stwrd, "org:admin"), (req, res) => {
+  res.json({ org: req.stwrd!.organization!.display_name, roles: req.stwrd!.organization!.roles });
+});
+
+app.post("/invitations", requirePermission(stwrd, "members:invite"), (req, res) => {
+  res.json({ invited_by: req.stwrd!.user!.id });
+});
+
+// A redirect target that came from a query parameter goes through safeTarget:
+// only relative paths of this app are accepted, anything else falls back.
+app.get("/go", (req, res) => {
+  res.redirect(303, safeTarget(String(req.query.to ?? ""), "/"));
+});
+
+app.listen(Number(process.env.PORT ?? 3000));
+```
+
+Register `{STWRD_BASE_URL}/auth/callback` as a redirect URI of the application in stwrd.
+
+`authRouter` reads its own request bodies (forms for sign-out and back-channel logout, JSON for the organization switch, the raw bytes for the webhook), so you do not need `express.json()` before it. If your app mounts a body parser globally before the router, sign-out, back-channel logout and the organization switch still work, but the webhook signature cannot be verified: it is computed over the exact bytes received, so the route answers 400 `invalid_signature`. Mount the parser after the router, or give the webhook path `express.raw()`.
+
+## Configuration
+
+`Stwrd.fromEnv(env = process.env, overrides = {})` reads these variables; `createStwrd(options)` takes the same values as camelCase options. A missing required variable, or a cookie secret shorter than 32 characters, throws `ConfigError` at construction.
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `STWRD_ISSUER` | yes | | Issuer URL of the tenant. |
+| `STWRD_CLIENT_ID` | yes | | OIDC client ID of the application. |
+| `STWRD_CLIENT_SECRET` | yes | | Client secret of the application. |
+| `STWRD_BASE_URL` | yes | | Public URL of the app. `{baseUrl}/auth/callback` is the redirect URI. |
+| `STWRD_COOKIE_SECRET` | yes | | HMAC key of the session cookie, at least 32 characters. |
+| `STWRD_SCOPE` | no | `openid profile email offline_access` | Requested scopes (see Scopes). |
+| `STWRD_WEBHOOK_SECRET` | no | none | Without it `/auth/webhook` answers 503. |
+| `STWRD_PREFIX` | no | `/auth` | Path prefix of the routes. |
+| `STWRD_SESSION_TTL_S` | no | `28800` | Sliding session lifetime in seconds. |
+| `STWRD_COOKIE_SECURE` | no | `true` | `Secure` attribute of the cookies. |
+| `STWRD_POST_LOGIN_REDIRECT` | no | `/` | Destination when a sign-in has no `return_to`. |
+| `STWRD_POST_LOGOUT_REDIRECT` | no | `/` | Destination after sign-out. |
+
+The remaining options (cookie names, transaction lifetime, `sessions`, `fetch`) are documented in [`@stwrd-auth/core`](https://www.npmjs.com/package/@stwrd-auth/core). `STWRD_COOKIE_SECURE=false` is for local development over plain HTTP only; browsers reject `__Host-` cookies that are not `Secure`, so also set the `sessionCookie` and `txCookie` options to names without that prefix.
+
+### Scopes
+
+The default scope does not include `org`; without it `organization` is `null`. Add `org` to `STWRD_SCOPE` (`openid profile email offline_access org`) to receive organization roles and permissions, and allow that scope for the application in stwrd: requesting a scope the application is not allowed makes the authorize request fail with `invalid_scope`. Individual roles and permissions are in `user.roles` and `user.permissions`; with an organization they are in `organization.roles` and `organization.permissions`.
+
+## API reference
+
+### Entry points
+
+| Import | Contents |
+|---|---|
+| `@stwrd-auth/node` | `Stwrd`, `createStwrd`, guards, `safeTarget`, session helpers, webhook helpers, configuration and OIDC primitives, `makeHostFetch` |
+| `@stwrd-auth/node/management` | `createManagement`: typed Management API client |
+| `@stwrd-auth/node/webhooks` | `verifyWebhook`, `signWebhook`, `SeenEventIds` and related errors |
+| `@stwrd-auth/node/postgres` | `PostgresSessionStore`, `SCHEMA_SQL`, `Keyring` |
+
+### `Stwrd`
+
+| Member | Description |
+|---|---|
+| `Stwrd.fromEnv(env?, overrides?)` / `createStwrd(options)` | Build the instance once and share it. |
+| `stwrd.attach()` | Middleware that resolves the session once per request and leaves `{ user, organization, consents, session }` in `req.stwrd`. |
+| `stwrd.authRouter({ onUserRegistered?, onEvent? })` | Express router for the `/auth/*` routes. `onUserRegistered(user)` runs on every successful sign-in, not only the first; `onEvent(event)` runs for each accepted webhook delivery, after deduplication. |
+| `stwrd.protectAll({ public })` | Opt-in fail-closed middleware: every path needs a session unless it is listed. Paths under the auth prefix are always public; `*` is a wildcard only at the end of an entry. |
+| `stwrd.csrf(sessionId)` | The CSRF token of a session. |
+| `stwrd.sessionFromRequest(req)`, `stwrd.resolveSessionFromRequest(req)` | Read a session outside the middleware; the second one renews expired tokens. |
+
+### Guards
+
+Each guard is a factory that takes the `Stwrd` instance and returns an Express `RequestHandler`.
+
+| Guard | If the requirement is not met |
+|---|---|
+| `requireAuth(stwrd)` | 303 to sign-in for a browser navigation, otherwise 401 `{"detail":"No session."}` |
+| `requireRole(stwrd, role)` | 403 `{"detail":"Missing role org:admin."}` |
+| `requirePermission(stwrd, permission)` | 403 `{"detail":"Missing permission members:invite."}` |
+| `requireOrg(stwrd)` | 403 `{"detail":"The session has no organization."}`; throws `ConfigError` at creation if the `org` scope is not requested |
+| `apiMode()` | Forces the 401 JSON instead of the 303 on this route |
+
+Roles and permissions are checked by membership against the organization when the session has one, otherwise against the individual lists.
+
+### Session JSON
+
+`GET /auth/session` answers `authenticated`, `user`, `organization`, `consents`, `csrf_token` and `account_url`. The profile has `id`, `display_name` and `avatar_url`; tokens, the identity provider's `sid` and the raw claims stay on the server. An anonymous answer has `user: null`, `organization: null`, `consents: {}` and `csrf_token: null`. `sessionContext(session)` produces the same context, and `hasRole(context, role)` and `hasPermission(context, permission)` check it.
+
+### Webhooks
+
+`/auth/webhook` verifies the signature and deduplicates by event `id` (30 hours, in memory). To verify by hand, in another route or framework:
+
+```ts
+import { verifyWebhook, SeenEventIds } from "@stwrd-auth/node/webhooks";
+
+const seen = new SeenEventIds();
+// rawBody: string | Buffer with the exact bytes received; headers: the request headers.
+const event = verifyWebhook(rawBody, headers, process.env.STWRD_WEBHOOK_SECRET!, { seen });
+```
+
+Deliveries carry `webhook-id`, `webhook-timestamp` and `webhook-signature` (`v1,` followed by the base64 HMAC-SHA256 of `id.timestamp.body`), with a 300-second tolerance. `signWebhook(secret, { eventId, timestamp, body })` produces the same signature for tests.
+
+### Management API
+
+```ts
+import { createManagement } from "@stwrd-auth/node/management";
+
+const api = createManagement({
+  issuer: process.env.STWRD_ISSUER!,
+  clientId: process.env.STWRD_MANAGEMENT_CLIENT_ID!,
+  clientSecret: process.env.STWRD_MANAGEMENT_CLIENT_SECRET!,
+  scopes: ["mgmt:users:read", "mgmt:users:write"],
+});
+
+const observed = await api.users.get({ path: { user_id: userId } });
+await api.users.update({ path: { user_id: userId }, body: { name: "Ada" }, options: { ifMatch: observed.etag ?? undefined } });
+for await (const user of api.users.iterate()) console.log(user.id);
+```
+
+Server-side only. Operations, request bodies and responses are typed. Writes are never retried automatically; errors are `ManagementError` with `status`, `body` and `requestId`.
+
+### Sessions across several processes
+
+`MemoryStore` (the default) keeps sessions in one process. With several processes, use the PostgreSQL store so that a refresh token is exchanged at most once and a sign-out is seen everywhere. Create the table with your own migration (`SCHEMA_SQL`; the store never creates tables), then:
+
+```ts
+import pg from "pg";
+import { Keyring, PostgresSessionStore } from "@stwrd-auth/node/postgres";
+
+const store = new PostgresSessionStore(new pg.Pool({ connectionString }), {
+  namespace: `${tenantId}/${clientId}`,
+  keyring: new Keyring({ "2026-10": keyBytes }, "2026-10"),
+});
+const stwrd = createStwrd({ ...options, sessions: store });
+```
+
+Sessions are encrypted (JWE) with the keyring, which is independent of the cookie secret, and are bound to their namespace and id. To rotate a key, deploy the new key to every process as a non-current key, switch `current`, and remove the old key only after `store.purgeExpired()` (run it periodically) has removed every session written under it. Lease expiry is judged by the database clock. Any other store can implement the `SessionStore` interface.
+
+### Developing against a local identity provider
+
+The identity provider resolves the tenant from the `Host` header, and Node's global `fetch` replaces that header with the destination's. `makeHostFetch` connects to a fixed address and sends the issuer's `Host` as is:
+
+```ts
+import { Stwrd, makeHostFetch } from "@stwrd-auth/node";
+
+const stwrd = Stwrd.fromEnv(process.env, {
+  fetch: makeHostFetch({ connectHost: "127.0.0.1", connectPort: 3005, host: "idp.example.com" }),
+});
+```
+
+## Security
+
+- The browser holds a single signed cookie (`__Host-stwrd_session`: HMAC-signed, `HttpOnly`, `SameSite=Lax`, `Secure` unless disabled). Access, ID and refresh tokens never leave the server. The signature makes the cookie tamper-evident; it is not encrypted.
+- Sign-out and the organization switch require a CSRF token (`x-csrf-token` header or `csrf_token` form field). Redirect targets taken from requests are confined to relative paths of the app (`safeTarget`).
+- Authorization uses PKCE, `state` and `nonce`; ID tokens are verified for signature, issuer, audience, expiry, `nonce` and `at_hash`. Requests to the identity provider never follow redirects, and the redirect URI is built from `STWRD_BASE_URL`, never from the `Host` header.
+- Webhook signatures are compared in constant time. The in-memory deduplication is a convenience; a receiver that needs a hard guarantee also deduplicates by event `id` in its own storage.
+- Keep `STWRD_COOKIE_SECRET`, `STWRD_CLIENT_SECRET`, `STWRD_WEBHOOK_SECRET` and the session keyring out of source control and logs. Changing the cookie secret signs everyone out.
+- Supported versions and how to report a vulnerability are described in the [security policy](https://github.com/stwrd-dev/sdk-js/security/policy).
+
+## Error handling and troubleshooting
+
+| Situation | Answer |
+|---|---|
+| Navigation without a session | 303 to `{prefix}/sign-in?return_to=...` |
+| API call without a session | 401 `{"detail":"No session."}` |
+| Missing role, permission, organization or CSRF token | 403 with `detail` |
+| The identity provider does not answer | 503 `The IdP did not respond.` (`Cache-Control: no-store` on `/auth/session`) |
+| Rejected sign-in callback | 400, plain text |
+| `/auth/webhook` | 200 `{"status":"ok"}` or `{"status":"duplicate"}`; 400 `{"error":"invalid_signature"}`; 503 `{"error":"webhook_not_configured"}` |
+| Request body above the limit | 413 |
+
+A 503 never means the person signed out: the session is kept and the next request tries again. A session that stays on 503 for one person is `uncertain` (a token renewal may have been processed without its result being stored); signing in again fixes it. The classes `ConfigError`, `OidcError`, `IdpUnavailable` and `RefreshUncertain` are exported for your own handling.
+
+## Compatibility
+
+- Node.js 20 or newer; Express 4 (the version the test suite runs against) and 5 (declared in the peer range).
+- ESM only. TypeScript declarations are included and resolve under `node10`, `nodenext` and `bundler` module resolution.
+- PostgreSQL store: `pg` 8.
+
+## Versioning
+
+This package follows Semantic Versioning (SemVer). While the version is below 1.0, minor releases may contain breaking changes. `@stwrd-auth/core` is pinned to an exact version, so the two always move together. Changes are listed in `CHANGELOG.md`.
+
+## License
+
+MIT © 2026 stwrd. See `LICENSE`.

package/dist/client.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `Stwrd` / `createStwrd` — the object an app builds once and hands to
+ * `authRouter`/`attach`/the guards. Everything that does not touch Express
+ * lives in `StwrdCore` (`@stwrd-auth/core/client`).
+ */
+import type { IncomingMessage } from "node:http";
+import { StwrdCore, type StwrdOptions } from "@stwrd-auth/core/client";
+import type { StwrdSession } from "@stwrd-auth/core/sessions";
+import { type AuthRouterOptions, type ProtectAllOptions } from "./router.js";
+import type { RequestHandler, Router } from "express";
+export type { StwrdOptions };
+export declare class Stwrd extends StwrdCore {
+    constructor(options: StwrdOptions);
+    /** Reads the `STWRD_*` variables from `env`, with `overrides` winning over
+     * the environment. */
+    static fromEnv(env?: NodeJS.ProcessEnv, overrides?: Partial<StwrdOptions>): Stwrd;
+    /** Resolves the session once per request and caches it on `req.stwrd`.
+     * Mount with `app.use(stwrd.attach())`, ahead of the guards and any route
+     * that reads `req.stwrd`. */
+    attach(): RequestHandler;
+    /** The `/auth/*` routes, mounted under `config.prefix`. */
+    authRouter(options?: AuthRouterOptions): Router;
+    /** The opt-in fail-closed guard: requires a session on every path that is
+     * not declared public. */
+    protectAll(options?: ProtectAllOptions): RequestHandler;
+    resolveSessionFromRequest(req: Pick<IncomingMessage, "headers">): Promise<StwrdSession | null>;
+    sessionFromRequest(req: Pick<IncomingMessage, "headers">): Promise<StwrdSession | null>;
+}
+export declare function createStwrd(options: StwrdOptions): Stwrd;

package/dist/client.js

@@ -0,0 +1,46 @@
+/**
+ * `Stwrd` / `createStwrd` — the object an app builds once and hands to
+ * `authRouter`/`attach`/the guards. Everything that does not touch Express
+ * lives in `StwrdCore` (`@stwrd-auth/core/client`).
+ */
+import { StwrdCore, stwrdOptionsFromEnv } from "@stwrd-auth/core/client";
+import { attachMiddleware } from "./guards.js";
+import { readCookie } from "./http.js";
+import { authRouter, protectAllMiddleware } from "./router.js";
+export class Stwrd extends StwrdCore {
+    // The refresh tuning of `StwrdCore` is for adapters of other runtimes: the
+    // Node SDK uses the defaults.
+    constructor(options) {
+        super(options);
+    }
+    /** Reads the `STWRD_*` variables from `env`, with `overrides` winning over
+     * the environment. */
+    static fromEnv(env = process.env, overrides = {}) {
+        return new Stwrd(stwrdOptionsFromEnv(env, overrides));
+    }
+    // --- Express wiring --------------------------------------------------
+    /** Resolves the session once per request and caches it on `req.stwrd`.
+     * Mount with `app.use(stwrd.attach())`, ahead of the guards and any route
+     * that reads `req.stwrd`. */
+    attach() {
+        return attachMiddleware(this);
+    }
+    /** The `/auth/*` routes, mounted under `config.prefix`. */
+    authRouter(options = {}) {
+        return authRouter(this, options);
+    }
+    /** The opt-in fail-closed guard: requires a session on every path that is
+     * not declared public. */
+    protectAll(options = {}) {
+        return protectAllMiddleware(this, options);
+    }
+    async resolveSessionFromRequest(req) {
+        return this.resolveSession(readCookie(req, this.config.sessionCookie));
+    }
+    async sessionFromRequest(req) {
+        return this.sessionFromCookie(readCookie(req, this.config.sessionCookie));
+    }
+}
+export function createStwrd(options) {
+    return new Stwrd(options);
+}

package/dist/env.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `configFromEnv` for Node: the core's reader with `process.env` as the
+ * default environment. The core has no default of its own (it also runs where
+ * there is no `process.env`); this wrapper keeps the public signature of
+ * `@stwrd-auth/node` stable.
+ */
+import { type StwrdConfigOptions } from "@stwrd-auth/core/config";
+export declare function configFromEnv(env?: NodeJS.ProcessEnv, envPrefix?: string): Partial<StwrdConfigOptions>;

package/dist/env.js

@@ -0,0 +1,10 @@
+/**
+ * `configFromEnv` for Node: the core's reader with `process.env` as the
+ * default environment. The core has no default of its own (it also runs where
+ * there is no `process.env`); this wrapper keeps the public signature of
+ * `@stwrd-auth/node` stable.
+ */
+import { ENV_PREFIX, configFromEnv as readConfigFromEnv } from "@stwrd-auth/core/config";
+export function configFromEnv(env = process.env, envPrefix = ENV_PREFIX) {
+    return readConfigFromEnv(env, envPrefix);
+}

package/dist/guards.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `attach` and the Express guards — a thin Express shim over the core's
+ * `checkAccess` (`@stwrd-auth/core/web/access`), which holds every decision: allow,
+ * 401 JSON, 303 to sign-in, 403, and 503 when the IdP does not answer.
+ *
+ * Every factory below takes `stwrd` explicitly
+ * (`requireRole(stwrd, "org:admin")`): there is no implicit registration step
+ * to read it from instead.
+ *
+ * `attach()` exists because Express has no built-in per-request memoization.
+ * It resolves the session once and caches it on `req.stwrd`; every guard
+ * below reads that cache if present and falls back to resolving directly
+ * otherwise, so a guard works whether or not `attach()` ran first.
+ */
+import type { Request, RequestHandler } from "express";
+import { type AccessContext, type AccessRule, type Resolution, IDP_SILENT, safeTarget } from "@stwrd-auth/core/web/access";
+import type { Stwrd } from "./client.js";
+/** What `attach()` leaves on `req.stwrd`: the user, the organization and the
+ * consents as separate objects, plus the private session. */
+export type StwrdContext = AccessContext;
+declare global {
+    namespace Express {
+        interface Request {
+            stwrd?: StwrdContext;
+            stwrdApiMode?: boolean;
+            /** The IdP did not answer while resolving this request: the context
+             * above says `user: null` because there is nothing else to put there,
+             * and **not** because there is no session. The guards check it to answer
+             * 503 instead of sending someone who is still signed in to the login. */
+            stwrdIdpUnavailable?: boolean;
+        }
+    }
+}
+/** Resolves the request's session once and caches it on the request. */
+export declare function resolveRequest(stwrd: Stwrd, req: Request): Promise<Resolution>;
+/** One guard per rule: the core decides, this only carries the request in and
+ * the response out. */
+export declare function guard(stwrd: Stwrd, rule: AccessRule): RequestHandler;
+/** Resolves the session once per request and caches it on `req.stwrd`,
+ * ahead of route handlers and any guard below. The public entry point is the
+ * bound method `Stwrd.attach`; this is its implementation. */
+export declare function attachMiddleware(stwrd: Stwrd): RequestHandler;
+/** Forces a 401 JSON denial on this route even for a browser navigation. */
+export declare function apiMode(): RequestHandler;
+/** A guard with no return value beyond "must be signed in" — does not read
+ * the user, unlike a route handler that reads `req.stwrd.user` directly
+ * after this passes. */
+export declare function requireAuth(stwrd: Stwrd): RequestHandler;
+/** Requires a role. `org_roles` is an open registry: the check is membership,
+ * never set equality. */
+export declare function requireRole(stwrd: Stwrd, role: string): RequestHandler;
+export declare function requireOrg(stwrd: Stwrd): RequestHandler;
+export declare function requirePermission(stwrd: Stwrd, permission: string): RequestHandler;
+export { IDP_SILENT, safeTarget };

package/dist/guards.js

@@ -0,0 +1,84 @@
+/**
+ * `attach` and the Express guards — a thin Express shim over the core's
+ * `checkAccess` (`@stwrd-auth/core/web/access`), which holds every decision: allow,
+ * 401 JSON, 303 to sign-in, 403, and 503 when the IdP does not answer.
+ *
+ * Every factory below takes `stwrd` explicitly
+ * (`requireRole(stwrd, "org:admin")`): there is no implicit registration step
+ * to read it from instead.
+ *
+ * `attach()` exists because Express has no built-in per-request memoization.
+ * It resolves the session once and caches it on `req.stwrd`; every guard
+ * below reads that cache if present and falls back to resolving directly
+ * otherwise, so a guard works whether or not `attach()` ran first.
+ */
+import { IDP_SILENT, assertOrgRuleAvailable, checkAccess, resolveAccess, safeTarget, } from "@stwrd-auth/core/web/access";
+import { readCookie } from "./http.js";
+import { sendWebResponse } from "./webBridge.js";
+/** Resolves the request's session once and caches it on the request. */
+export async function resolveRequest(stwrd, req) {
+    if (req.stwrd) {
+        return { context: req.stwrd, idpUnavailable: req.stwrdIdpUnavailable === true };
+    }
+    const resolution = await resolveAccess(stwrd, readCookie(req, stwrd.config.sessionCookie));
+    // Marked and NOT raised: an unguarded public route renders anyway (it has no
+    // session to lose) and each guard decides for itself.
+    if (resolution.idpUnavailable) {
+        req.stwrdIdpUnavailable = true;
+    }
+    req.stwrd = resolution.context;
+    return resolution;
+}
+/** One guard per rule: the core decides, this only carries the request in and
+ * the response out. */
+export function guard(stwrd, rule) {
+    return (req, res, next) => {
+        void (async () => {
+            const resolved = await resolveRequest(stwrd, req);
+            const result = await checkAccess(stwrd, { accept: req.headers.accept, target: req.originalUrl ?? req.url, api: req.stwrdApiMode, resolved }, rule);
+            if (!result.ok) {
+                await sendWebResponse(res, result.response);
+                return;
+            }
+            next();
+        })().catch(next);
+    };
+}
+/** Resolves the session once per request and caches it on `req.stwrd`,
+ * ahead of route handlers and any guard below. The public entry point is the
+ * bound method `Stwrd.attach`; this is its implementation. */
+export function attachMiddleware(stwrd) {
+    return (req, _res, next) => {
+        resolveRequest(stwrd, req)
+            .then(() => next())
+            .catch(next);
+    };
+}
+/** Forces a 401 JSON denial on this route even for a browser navigation. */
+export function apiMode() {
+    return (req, _res, next) => {
+        req.stwrdApiMode = true;
+        next();
+    };
+}
+/** A guard with no return value beyond "must be signed in" — does not read
+ * the user, unlike a route handler that reads `req.stwrd.user` directly
+ * after this passes. */
+export function requireAuth(stwrd) {
+    return guard(stwrd, { auth: true });
+}
+/** Requires a role. `org_roles` is an open registry: the check is membership,
+ * never set equality. */
+export function requireRole(stwrd, role) {
+    return guard(stwrd, { role });
+}
+export function requireOrg(stwrd) {
+    assertOrgRuleAvailable(stwrd);
+    return guard(stwrd, { org: true });
+}
+export function requirePermission(stwrd, permission) {
+    return guard(stwrd, { permission });
+}
+// `safeTarget` lives in the core, next to the guards that use it; this entry
+// point keeps exporting it.
+export { IDP_SILENT, safeTarget };

package/dist/hostFetch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `makeHostFetch` — a `FetchLike` that connects to a fixed address while
+ * sending an arbitrary `Host` header. The identity provider resolves the
+ * tenant by `Host`, so an app developing against one on `127.0.0.1` still has
+ * to talk to it as `idp.example.com`; this is how, without `/etc/hosts` or
+ * real DNS.
+ *
+ * Global `fetch` (undici) treats `Host` as a protected header and overwrites it
+ * to match the connection's own authority. `node:http.request` has no such
+ * restriction (`options.host`/`options.port` pick the TCP peer,
+ * `options.headers.Host` is sent as-is), so this wraps that instead and
+ * adapts the result back into a real `Response`, keeping every caller
+ * (`OidcClient` and the rest) working against the same Fetch-API shape.
+ */
+import type { FetchLike } from "@stwrd-auth/core/oidc";
+export interface HostFetchOptions {
+    /** Where the TCP connection goes — `127.0.0.1` for a local IdP. */
+    connectHost: string;
+    connectPort: number;
+    /** The `Host` header sent as-is — the issuer's host, what the IdP routes by. */
+    host: string;
+}
+export declare function makeHostFetch(options: HostFetchOptions): FetchLike;

package/dist/hostFetch.js

@@ -0,0 +1,84 @@
+/**
+ * `makeHostFetch` — a `FetchLike` that connects to a fixed address while
+ * sending an arbitrary `Host` header. The identity provider resolves the
+ * tenant by `Host`, so an app developing against one on `127.0.0.1` still has
+ * to talk to it as `idp.example.com`; this is how, without `/etc/hosts` or
+ * real DNS.
+ *
+ * Global `fetch` (undici) treats `Host` as a protected header and overwrites it
+ * to match the connection's own authority. `node:http.request` has no such
+ * restriction (`options.host`/`options.port` pick the TCP peer,
+ * `options.headers.Host` is sent as-is), so this wraps that instead and
+ * adapts the result back into a real `Response`, keeping every caller
+ * (`OidcClient` and the rest) working against the same Fetch-API shape.
+ */
+import { request as httpRequest } from "node:http";
+export function makeHostFetch(options) {
+    return async function hostFetch(input, init = {}) {
+        const url = new URL(String(input));
+        const method = init.method ?? "GET";
+        const headers = {};
+        new Headers(init.headers).forEach((value, key) => {
+            headers[key] = value;
+        });
+        headers.host = options.host;
+        const bodyBuffer = await toBuffer(init.body);
+        if (bodyBuffer && headers["content-length"] === undefined) {
+            headers["content-length"] = String(bodyBuffer.length);
+        }
+        return new Promise((resolve, reject) => {
+            const req = httpRequest({
+                host: options.connectHost,
+                port: options.connectPort,
+                method,
+                path: `${url.pathname}${url.search}`,
+                headers,
+            }, (res) => {
+                const chunks = [];
+                res.on("data", (chunk) => chunks.push(chunk));
+                res.on("end", () => {
+                    const responseHeaders = new Headers();
+                    for (const [key, value] of Object.entries(res.headers)) {
+                        if (value === undefined) {
+                            continue;
+                        }
+                        for (const one of Array.isArray(value) ? value : [value]) {
+                            responseHeaders.append(key, one);
+                        }
+                    }
+                    resolve(new Response(Buffer.concat(chunks), {
+                        status: res.statusCode ?? 0,
+                        statusText: res.statusMessage,
+                        headers: responseHeaders,
+                    }));
+                });
+            });
+            req.on("error", reject);
+            if (bodyBuffer) {
+                req.write(bodyBuffer);
+            }
+            req.end();
+        });
+    };
+}
+async function toBuffer(body) {
+    if (body === null || body === undefined) {
+        return null;
+    }
+    if (typeof body === "string") {
+        return Buffer.from(body, "utf-8");
+    }
+    if (body instanceof URLSearchParams) {
+        return Buffer.from(body.toString(), "utf-8");
+    }
+    if (Buffer.isBuffer(body)) {
+        return body;
+    }
+    if (body instanceof ArrayBuffer) {
+        return Buffer.from(body);
+    }
+    // Anything else Fetch's `BodyInit` allows (a `Blob`, a stream): none of
+    // the SDK's own requests need it, so this is a deliberately narrow adapter
+    // and not a full `BodyInit` implementation.
+    throw new TypeError("makeHostFetch: unsupported body (only string, Buffer, URLSearchParams or ArrayBuffer).");
+}

package/dist/http.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 type { IncomingHttpHeaders, IncomingMessage } from "node:http";
+export declare function readCookie(req: Pick<IncomingMessage, "headers">, name: string): string | undefined;
+/** 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 declare function headersToRecord(headers: IncomingHttpHeaders): Record<string, string>;