@stwrd-auth/core 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# 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
+
+- Configuration resolution (`resolveConfig`, `configFromEnv`, `stwrdOptionsFromEnv`) with fail-closed validation and `ConfigError`.
+- `StwrdCore`: session resolution with expiry and token renewal, HMAC-signed cookie sealing, CSRF tokens and webhook verification, independent of any web framework or runtime.
+- OpenID Connect relying-party client (`OidcClient`): discovery, JWKS caching, authorization-code flow with PKCE, ID token and logout token validation, refresh-token exchange, userinfo. Redirects are never followed.
+- Distinct errors for a rejection by the identity provider (`OidcError`) and for no answer (`IdpUnavailable`, `RefreshUncertain`).
+- Session store contract (`SessionStore`) with a refresh lease and fencing, so a refresh token is exchanged at most once across processes, plus the in-memory `MemoryStore`.
+- `Keyring` for encrypting stored sessions (JWE `dir` + `A256GCM`) with key rotation.
+- `authHandler`: the `/auth/*` routes (sign-in, callback, sign-out, session, organizations, back-channel logout, webhook) as a `Request` to `Response` function.
+- Access guards on `Request` and `Response` (`checkAccess`, `resolveAccess`, `safeTarget`, `isPublicPath`).
+- Back-channel logout bookkeeping (`BackChannelSink`, `MemoryBackChannelSink`).
+- Standard Webhooks signature verification and signing (`verifyWebhook`, `signWebhook`) with replay window and `SeenEventIds` deduplication.
+- Typed Management API client (`createManagement`) with discovery validation, token caching and cursor iteration.
+- Cookie, bounded request-body and response helpers.

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,173 @@
-# Temporary Holding Version
+# @stwrd-auth/core
 
-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.
+The runtime-neutral core shared by the stwrd JavaScript SDKs: configuration, an OpenID Connect relying-party client, server-side sessions with a refresh lease, signed cookies, webhook verification and the Management API transport.
+
+## What it is
+
+[stwrd](https://stwrd.dev) is a multi-tenant identity provider. This package holds the logic that does not depend on a web framework or a runtime. It has no HTTP server and no framework integration of its own: applications normally install an adapter, and the adapter builds on this package.
+
+| Package | Use it for |
+|---|---|
+| [`@stwrd-auth/node`](https://www.npmjs.com/package/@stwrd-auth/node) | Express apps |
+| [`@stwrd-auth/workers`](https://www.npmjs.com/package/@stwrd-auth/workers) | Cloudflare Workers |
+| [`@stwrd-auth/react`](https://www.npmjs.com/package/@stwrd-auth/react) | React front ends that talk to one of the two above |
+
+Install this package directly to write an adapter for another runtime, to verify stwrd webhooks on their own, or to use the typed Management client without an adapter.
+
+## Installation
+
+```sh
+npm install @stwrd-auth/core
+```
+
+Requires Node.js 18 or newer, or any runtime that provides the Fetch API (`Request`, `Response`, `Headers`) and `node:crypto` (Cloudflare Workers with the `nodejs_compat` compatibility flag). The only runtime dependency is [`jose`](https://www.npmjs.com/package/jose) (`^6`). The package is ESM only and ships its own TypeScript declarations.
+
+Each module is a subpath export; there is no root entry point (`import ... from "@stwrd-auth/core/client"`). The adapters pin this package to an exact version, so install both from the same release.
+
+## Minimal example
+
+A server for any runtime that speaks `Request` and `Response` (Bun, Deno, Workers). The handler serves the `/auth/*` routes and returns `null` for any other path:
+
+```ts
+import { StwrdCore, stwrdOptionsFromEnv } from "@stwrd-auth/core/client";
+import { authHandler } from "@stwrd-auth/core/web/authHandler";
+
+const stwrd = new StwrdCore(stwrdOptionsFromEnv(process.env));
+const handle = authHandler(stwrd);
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    return (await handle(request)) ?? new Response("Not found", { status: 404 });
+  },
+};
+```
+
+Without a `sessions` option the sessions live in process memory (`MemoryStore`), which suits development and a single process. For several processes, pass a shared store that implements `SessionStore`; `@stwrd-auth/node/postgres` and `@stwrd-auth/workers` ship two.
+
+Verifying a webhook delivery, with the raw request body and the request headers:
+
+```ts
+import { SeenEventIds, verifyWebhook } from "@stwrd-auth/core/webhooks";
+
+const seen = new SeenEventIds();
+
+export function receive(rawBody: string | Buffer, headers: Record<string, string>) {
+  // Throws InvalidSignatureError or DuplicateEventError.
+  return verifyWebhook(rawBody, headers, process.env.STWRD_WEBHOOK_SECRET!, { seen });
+}
+```
+
+## Configuration
+
+`new StwrdCore(options)` and `resolveConfig(options)` validate the options and throw `ConfigError` when one is missing or invalid. `stwrdOptionsFromEnv(env, overrides?)` reads them from an environment object; the core never reads a global environment of its own.
+
+| Option | Environment variable | Required | Default | Description |
+|---|---|---|---|---|
+| `issuer` | `STWRD_ISSUER` | yes | | Issuer URL of the tenant. |
+| `clientId` | `STWRD_CLIENT_ID` | yes | | OIDC client ID of the application. |
+| `clientSecret` | `STWRD_CLIENT_SECRET` | yes | | Client secret of the application. |
+| `baseUrl` | `STWRD_BASE_URL` | yes | | Public URL of the application. `{baseUrl}{prefix}/callback` is the redirect URI. |
+| `cookieSecret` | `STWRD_COOKIE_SECRET` | yes | | HMAC key of the session cookie, at least 32 characters. |
+| `scope` | `STWRD_SCOPE` | no | `openid profile email offline_access` | Requested scopes. Add `org` to enable organizations. |
+| `webhookSecret` | `STWRD_WEBHOOK_SECRET` | no | none | Without it `/auth/webhook` answers 503. |
+| `prefix` | `STWRD_PREFIX` | no | `/auth` | Path prefix of the routes. |
+| `sessionTtlS` | `STWRD_SESSION_TTL_S` | no | `28800` | Sliding session lifetime in seconds. |
+| `cookieSecure` | `STWRD_COOKIE_SECURE` | no | `true` | `Secure` attribute of the cookies. |
+| `postLoginRedirect` | `STWRD_POST_LOGIN_REDIRECT` | no | `/` | Destination when a sign-in has no `return_to`. |
+| `postLogoutRedirect` | `STWRD_POST_LOGOUT_REDIRECT` | no | `/` | Destination after sign-out. |
+| `sessionCookie` | | no | `__Host-stwrd_session` | Name of the session cookie. |
+| `txCookie` | | no | `__Host-stwrd_tx` | Name of the sign-in transaction cookie. |
+| `transactionTtlS` | | no | `600` | Lifetime of a pending sign-in, in seconds. |
+| `sessions` | | no | `MemoryStore` | A `SessionStore`. |
+| `fetch` | | no | `globalThis.fetch` | The `fetch` used for every request to the identity provider. |
+
+## API reference
+
+| Subpath | Exports |
+|---|---|
+| `@stwrd-auth/core/client` | `StwrdCore` (sessions, cookie sealing, CSRF, webhook verification, organization listing), `stwrdOptionsFromEnv`, `RefreshTuning`, `KeepAlive` |
+| `@stwrd-auth/core/config` | `resolveConfig`, `configFromEnv`, `stwrdConfigFromEnv`, `ConfigError`, defaults and option types |
+| `@stwrd-auth/core/oidc` | `OidcClient`, `OidcError`, `IdpUnavailable`, `RefreshUncertain`, PKCE and `state` helpers |
+| `@stwrd-auth/core/sessions` | `SessionStore`, `MemoryStore`, `StwrdSession`, `StwrdUser`, `StwrdOrganization`, `sessionContext`, `sessionResponse`, `hasRole`, `hasPermission` |
+| `@stwrd-auth/core/keyring` | `Keyring`: named 32-byte keys that encrypt stored sessions (JWE `dir` + `A256GCM`) |
+| `@stwrd-auth/core/backchannel` | `BackChannelSink`, `MemoryBackChannelSink` |
+| `@stwrd-auth/core/webhooks` | `verifyWebhook`, `verifyWebhookSignature`, `signWebhook`, `SeenEventIds`, `InvalidSignatureError`, `DuplicateEventError` |
+| `@stwrd-auth/core/management` | `createManagement`, `ManagementClient`, `ManagementError`: typed Management API client |
+| `@stwrd-auth/core/crypto` | `sign`, `unsign`, `csrfToken` |
+| `@stwrd-auth/core/web/authHandler` | `authHandler(stwrd, options?)`: the `/auth/*` routes as `(Request) => Promise<Response \| null>` |
+| `@stwrd-auth/core/web/access` | `checkAccess`, `resolveAccess`, `safeTarget`, `isPublicPath`: the access guards on `Request` and `Response` |
+| `@stwrd-auth/core/web/cookies`, `body`, `response` | Cookie, bounded body-reading and response helpers |
+
+### Routes served by `authHandler`
+
+| Route | Behavior |
+|---|---|
+| `GET {prefix}/sign-in` | Starts the authorization-code flow with PKCE; accepts `return_to`; other query parameters are ignored. |
+| `GET {prefix}/callback` | Completes the flow, creates the session and sets the session cookie. |
+| `POST {prefix}/sign-out` | Ends the session. Requires the CSRF token (`x-csrf-token` header or `csrf_token` form field). |
+| `GET {prefix}/session` | JSON: `authenticated`, `user`, `organization`, `consents`, `csrf_token`, `account_url`. |
+| `GET {prefix}/organizations`, `POST {prefix}/organization` | List the person's organizations and switch the active one (requires the `org` scope). |
+| `POST {prefix}/back-channel` | Receives OIDC back-channel logout notices. |
+| `POST {prefix}/webhook` | Receives and verifies webhook deliveries. |
+
+### Management client
+
+```ts
+import { createManagement } from "@stwrd-auth/core/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"],
+});
+
+for await (const user of api.users.iterate()) {
+  console.log(user.id);
+}
+```
+
+Use it on a server only; never ship Management credentials to a browser. The client validates the discovery document before it sends any credential, refuses redirects, caches access tokens per validated destination and never retries a write on its own. Errors are `ManagementError` instances with `status`, `body` and `requestId`.
+
+## Security
+
+- Session cookies are HMAC-signed (tamper-evident, not encrypted) and carry only an opaque session identifier. Access, ID and refresh tokens stay in the server-side store and are never sent to the browser.
+- By default the cookies use the `__Host-` prefix and are `HttpOnly`, `Secure` and `SameSite=Lax`.
+- Authorization-code flows use PKCE (`S256`), `state` and `nonce`. ID tokens are verified for signature (`RS256` or `EdDSA`), issuer, audience, expiry, `nonce` and `at_hash`. The algorithm list is fixed and never read from the token.
+- Requests to the identity provider never follow redirects, so a redirect cannot carry a secret to another host. The redirect URI is built from `baseUrl`, never from the `Host` header.
+- State-changing routes (`sign-out`, organization switch) require a CSRF token derived from the session. Redirect targets taken from requests go through `safeTarget`: only paths of the same application are allowed.
+- Webhook signatures are compared in constant time, with a 300-second replay window. Deduplication by event `id` is process-local; a receiver that needs a hard guarantee must also deduplicate in its own storage.
+- Request bodies are read with a size ceiling measured on the stream (100 KiB for forms and JSON, 5 MiB for webhooks).
+- Across the processes that share a session store, a refresh token is exchanged at most once (a lease with fencing). When a refresh may have been processed but its result was not stored, the session becomes `uncertain` and the person signs in again; the consumed token is never replayed.
+
+Keep `cookieSecret`, `clientSecret`, `webhookSecret` and any session keyring out of source control and out of logs.
+
+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
+
+| Error | Meaning | What to do |
+|---|---|---|
+| `ConfigError` | A required option is missing or invalid, or an option has the wrong type. | Fix the configuration; the process should not start. |
+| `OidcError` | The identity provider answered and rejected the request (bad code, invalid token). | Treat the sign-in or the session as invalid. |
+| `IdpUnavailable` | The identity provider, or the session store, did not answer. `requestSent` says whether a request may have been processed. | Answer 503 and keep the session; retry later. |
+| `RefreshUncertain` | A refresh may have been processed without its result being stored. | Send the person through `/auth/sign-in`. |
+| `InvalidSignatureError` | The webhook headers, timestamp or signature are not valid. | Answer 400. |
+| `DuplicateEventError` | The webhook event `id` was already processed. | Answer 200 without reprocessing. |
+| `ManagementError` | The Management API answered with an error status. | Read `status`, `body` and `requestId`. |
+
+When the identity provider does not answer, the routes and guards answer 503 and never 401, so a person with a live session is not told that they signed out.
+
+## Compatibility
+
+- Node.js 18 or newer; Cloudflare Workers with `nodejs_compat`. The test suite runs on both Node and workerd.
+- ESM only. TypeScript declarations are included; they resolve under `node10`, `nodenext` and `bundler` module resolution.
+- Browsers are not supported: this package holds server-side secrets.
+
+## Versioning
+
+This package follows Semantic Versioning (SemVer). While the version is below 1.0, minor releases may contain breaking changes. Changes are listed in `CHANGELOG.md`.
+
+## License
+
+MIT © 2026 stwrd. See `LICENSE`.

package/dist/backchannel.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Back-channel logout bookkeeping: ending a local session and remembering the
+ * notice's `jti`, so the same notice is never accepted twice.
+ *
+ * The order is the contract: the session is deleted FIRST and the `jti` is
+ * marked SECOND. The IdP retries a 5xx and does not retry a 4xx; if the `jti`
+ * were marked first and the deletion then failed, the retry would find a seen
+ * `jti` and answer 400 "replay", and the local session would stay alive for
+ * good. A sink that cannot do both (a store that is down) throws and marks
+ * nothing.
+ */
+import type { SessionStore } from "./sessions.js";
+export interface BackChannelSink {
+    /** Ends `sessionId` (when the notice names a session) and marks `jti` as
+     * seen until `untilS` (epoch seconds, the notice's own `exp`: afterwards it
+     * cannot pass validation anyway). `"replay"` when `jti` was already seen; in
+     * that case nothing is deleted. Throws when the store cannot be reached. */
+    terminate(sessionId: string | null, jti: string, untilS: number): Promise<"terminated" | "replay">;
+}
+/** The default sink: process-local `jti` memory in front of a `SessionStore`.
+ * With several processes each one remembers its own; a sink that spans them
+ * (one transaction in the store) is the adapter's to provide. */
+export declare class MemoryBackChannelSink implements BackChannelSink {
+    private readonly sessions;
+    private readonly seen;
+    constructor(sessions: SessionStore);
+    terminate(sessionId: string | null, jti: string, untilS: number): Promise<"terminated" | "replay">;
+}

package/dist/backchannel.js

@@ -0,0 +1,41 @@
+/**
+ * Back-channel logout bookkeeping: ending a local session and remembering the
+ * notice's `jti`, so the same notice is never accepted twice.
+ *
+ * The order is the contract: the session is deleted FIRST and the `jti` is
+ * marked SECOND. The IdP retries a 5xx and does not retry a 4xx; if the `jti`
+ * were marked first and the deletion then failed, the retry would find a seen
+ * `jti` and answer 400 "replay", and the local session would stay alive for
+ * good. A sink that cannot do both (a store that is down) throws and marks
+ * nothing.
+ */
+/** The default sink: process-local `jti` memory in front of a `SessionStore`.
+ * With several processes each one remembers its own; a sink that spans them
+ * (one transaction in the store) is the adapter's to provide. */
+export class MemoryBackChannelSink {
+    sessions;
+    seen = new Map();
+    constructor(sessions) {
+        this.sessions = sessions;
+    }
+    async terminate(sessionId, jti, untilS) {
+        const now = Date.now() / 1000;
+        for (const [seenJti, until] of this.seen) {
+            if (until <= now) {
+                this.seen.delete(seenJti);
+            }
+        }
+        if (this.seen.has(jti)) {
+            return "replay";
+        }
+        // The store is keyed by the BFF's own id and the notice only carries
+        // `sid`, so the id was derived (`sessionIdForSid`) and the deletion is the
+        // plain `delete(id)` of the store contract: every store, third-party ones
+        // included, terminates sessions correctly with no extra method.
+        if (sessionId) {
+            await this.sessions.delete(sessionId);
+        }
+        this.seen.set(jti, untilS);
+        return "terminated";
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `StwrdCore` — the runtime-neutral object behind every JavaScript adapter:
+ * configuration, OIDC client, session store, cookie sealing, session
+ * resolution with the refresh lease, organization listing and webhook
+ * verification. It knows nothing about Express, Node's `http` or a Worker's
+ * `env`: `@stwrd-auth/node` extends it with the Express wiring. The Python SDK
+ * implements the same session logic.
+ */
+import { type EnvLike, type ResolvedConfig, type StwrdConfigOptions } from "./config.js";
+import { type FetchLike, OidcClient } from "./oidc.js";
+import { type OwnOrganization } from "./organizations.js";
+import { type SessionStore, type StwrdSession } from "./sessions.js";
+import { SeenEventIds, type WebhookEvent } from "./webhooks.js";
+/** How long the IdP gets to answer the discovery probe (`probeBeforeExchange`). */
+export declare const DISCOVERY_PROBE_TIMEOUT_MS = 5000;
+/** How a runtime waits for, and checks the IdP before, a refresh. The defaults
+ * suit Node; an adapter for a runtime where each store call is expensive (Workers: one Durable Object
+ * call per poll) or where a failed exchange cannot be told apart from a lost
+ * one passes its own. */
+export interface RefreshTuning {
+    /** Seconds a request waits for another owner's refresh of the same session
+     * to finish, before answering "the IdP is unavailable". */
+    waitS: number;
+    /** Milliseconds to wait before polling the store again, given how many polls
+     * (0 for the first) already found the lease busy. */
+    pollDelayMs(attempt: number): number;
+    /** Ask the IdP for its discovery document again, with a
+     * `DISCOVERY_PROBE_TIMEOUT_MS` timeout, just BEFORE the exchange is marked as
+     * sent. If the IdP does not answer, nothing was marked and nothing sent: the
+     * lease is released and the next request tries again. Where a failure of the
+     * exchange itself can never be proven "not sent" (the session would go
+     * `uncertain`), this is what keeps an IdP that is down from costing a session. */
+    probeBeforeExchange: boolean;
+}
+export declare const DEFAULT_REFRESH_TUNING: RefreshTuning;
+/** How a runtime keeps a renewal alive past the request that started it: given
+ * the work (a promise that never rejects), it must not let the runtime cut it
+ * short. On Workers this is `ctx.waitUntil`; where nothing cuts a request off
+ * (Node) there is none, and a renewal runs inline. The caller still awaits the
+ * renewal itself; this only stops "the person closed the tab" from killing it
+ * between "marked sent" and "saved". */
+export type KeepAlive = (work: Promise<void>) => void;
+export interface StwrdOptions extends StwrdConfigOptions {
+    sessions?: SessionStore;
+    fetch?: FetchLike;
+}
+export declare class StwrdCore {
+    readonly config: ResolvedConfig;
+    readonly oidc: OidcClient;
+    readonly sessions: SessionStore;
+    readonly seenWebhookIds: SeenEventIds;
+    private readonly fetchImpl;
+    private readonly tuning;
+    constructor(options: StwrdOptions, tuning?: RefreshTuning);
+    /** HMAC-signed, base64url cookie value. Not encryption — nothing sealed
+     * carries a secret the browser must not read; what this buys is
+     * tamper-evidence, so a forged cookie unseals to nothing. */
+    seal(value: unknown): string;
+    /** `null` on anything wrong — missing cookie, bad signature, bad JSON. */
+    unseal(cookie: string | null | undefined): unknown;
+    csrf(sessionId: string): string;
+    /** The local session id for an IdP session — derived, never random. It is
+     * what lets back-channel logout reach a session with only the IdP's `sid`,
+     * through `SessionStore.delete(id)` and no secondary index. */
+    sessionIdForSid(sid: string): string;
+    /** Organization selection needs the `org` scope to be requested
+     * explicitly; it is never added automatically. */
+    organizationSelectionEnabled(): boolean;
+    /** The person's own usable organizations, read with their access token. */
+    listOrganizations(session: StwrdSession): Promise<OwnOrganization[]>;
+    /** The session ready to authorize with — renews the tokens if the session
+     * holds a refresh token and the access token has expired. */
+    resolveSession(cookie: string | null | undefined, keepAlive?: KeepAlive): Promise<StwrdSession | null>;
+    /** Raw store read: unseals the cookie and looks the session up, with no
+     * renewal and no expiry side effects. */
+    sessionFromCookie(cookie: string | null | undefined): Promise<StwrdSession | null>;
+    /** Refresh `session` under the store's lease: across every worker the
+     * refresh token is exchanged at most once. `null` when the IdP REJECTED the
+     * renewal or the session was deleted meanwhile (`resolveSession` then ends
+     * the local session). `IdpUnavailable` propagates when nothing can be
+     * vouched for right now: the IdP is silent, another worker holds the lease
+     * too long, or an earlier exchange may have rotated the token without its
+     * result stored (`uncertain`: permanent for that session, the consumed token
+     * is never replayed). With `keepAlive`, the owned renewal (marked sent →
+     * exchange → saved) is handed to the runtime to finish even if the request
+     * ends first. */
+    private renew;
+    /** A lost lease is not a rejection: only a session that no longer exists
+     * ends (logout). One that is still there, possibly re-created by a new
+     * sign-in, must not be deleted by a stale owner. */
+    private leaseLost;
+    private renewOwned;
+    /** Verifies a webhook delivery and deduplicates it against
+     * `this.seenWebhookIds`. Throws `ConfigError` if no `webhookSecret` is
+     * configured — the `/auth/webhook` route turns that into a 503. */
+    verifyWebhook(body: string | Buffer, headers: Record<string, string>): WebhookEvent;
+}
+/** Reads `STWRD_*` variables from `env`, with `overrides` winning over them,
+ * and fails closed (`ConfigError`) when a required one is missing from both.
+ * There is no default `env` here: `@stwrd-auth/node` passes `process.env`. */
+export declare function stwrdOptionsFromEnv(env: EnvLike, overrides?: Partial<StwrdOptions>): StwrdOptions;