@bojanrajkovic/mcp-paprika 1.0.4 → 1.2.0-beta.1

package/README.md

@@ -4,14 +4,27 @@ An [MCP](https://modelcontextprotocol.io/) server for [Paprika](https://www.papr
 
 ## Features
 
-- **10 tools** for recipe management — search, filter, CRUD, categories, pagination
+- **14 tools** for recipe and pantry management — search, filter, CRUD, categories, pagination, pantry inventory
 - **Semantic search** via `discover_recipes` — find recipes by natural language description using any OpenAI-compatible embedding provider
 - **Background sync** — keeps your local cache in sync with Paprika's cloud
-- **MCP resources** — expose recipes as `paprika://recipe/{uid}` resources
+- **MCP resources** — expose recipes as `paprika://recipe/{uid}` and pantry items as `paprika://pantry/{uid}` resources
+- **Two transports** — stdio (default, for CLI clients) and Streamable HTTP (for mobile/web clients)
+- **Container image** — `Dockerfile` ships a distroless runtime ready for self-hosting
 
-## Quick start
+## Transports
 
-Add to your MCP client config (e.g. Claude Desktop):
+`mcp-paprika` can speak the MCP protocol over two transports, selected via `MCP_TRANSPORT`:
+
+| Transport | Default? | Use it for                                                                          |
+| --------- | -------- | ----------------------------------------------------------------------------------- |
+| `stdio`   | yes      | Local CLI clients: Claude Code, Claude Desktop, Cursor, mcp-cli                     |
+| `http`    | no       | Streamable HTTP for Claude Mobile and other HTTP-based MCP clients, or self-hosting |
+
+The HTTP transport ships with **OAuth 2.1** (authorization code + PKCE, RFC 7591 dynamic client registration). See the [HTTP transport quick start](#quick-start--http-transport) below.
+
+## Quick start — stdio (Claude Desktop / Claude Code / Cursor)
+
+Add to your MCP client config:
 
 ```json
 {
@@ -28,14 +41,226 @@ Add to your MCP client config (e.g. Claude Desktop):
 }
 ```
 
-See [configuration](docs/configuration.md) for all available options including background sync and semantic search.
+## Quick start — HTTP transport
+
+The HTTP transport uses **OAuth 2.1 with OIDC delegation**: `mcp-paprika` acts as the OAuth authorization server toward MCP clients, and delegates authentication to an upstream identity provider (IdP) of your choice.
+
+### Step 1 — Choose an upstream IdP
+
+Pick a preset or supply a raw discovery URL:
+
+| Preset value | IdP                           | Notes                                                         |
+| ------------ | ----------------------------- | ------------------------------------------------------------- |
+| `google`     | Google                        | Discovery URL built-in                                        |
+| `entra`      | Microsoft Entra ID (Azure AD) | Tenant-bound — requires `MCP_OIDC_DISCOVERY_URL`              |
+| `okta`       | Okta                          | Tenant-bound — requires `MCP_OIDC_DISCOVERY_URL`              |
+| `auth0`      | Auth0                         | Tenant-bound — requires `MCP_OIDC_DISCOVERY_URL`              |
+| `keycloak`   | Keycloak                      | Tenant-bound — requires `MCP_OIDC_DISCOVERY_URL`              |
+| _(none)_     | Custom                        | Set `MCP_OIDC_DISCOVERY_URL` directly; omit `MCP_OIDC_PRESET` |
+
+### Step 2 — Register one OAuth client in your IdP
+
+In your IdP's developer console (e.g., Google Cloud Console → APIs & Services → Credentials → OAuth 2.0 Client IDs), create a **single** OAuth 2.0 client with:
+
+- **Application type:** Web application
+- **Redirect URI:** `https://<your-MCP_PUBLIC_URL>/oauth/callback`
+
+Copy the resulting client ID and client secret — these become `MCP_OIDC_CLIENT_ID` and `MCP_OIDC_CLIENT_SECRET`.
+
+> **Tenant-bound presets (entra, okta, auth0, keycloak):** also copy the tenant-specific discovery URL from your IdP. For Entra this is `https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration`.
+
+### Step 3 — Configure and start the server
+
+Full env-var reference:
+
+| Env var                          | Required?                     | Description                                                                                                                                                                                                                   |
+| -------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MCP_TRANSPORT`                  | yes                           | Set to `http`                                                                                                                                                                                                                 |
+| `MCP_PUBLIC_URL`                 | yes                           | Canonical `https://` URL of this server; used as OAuth issuer. No trailing slash.                                                                                                                                             |
+| `MCP_OIDC_PRESET`                | one of preset or discoveryUrl | `google`, `entra`, `okta`, `auth0`, or `keycloak`                                                                                                                                                                             |
+| `MCP_OIDC_DISCOVERY_URL`         | one of preset or discoveryUrl | Raw OIDC discovery URL; required for tenant-bound presets                                                                                                                                                                     |
+| `MCP_OIDC_CLIENT_ID`             | yes                           | Client ID from upstream IdP                                                                                                                                                                                                   |
+| `MCP_OIDC_CLIENT_SECRET`         | yes                           | Client secret from upstream IdP                                                                                                                                                                                               |
+| `MCP_ALLOWED_EMAILS`             | one of emails or subs         | Comma-separated list of allowed email addresses                                                                                                                                                                               |
+| `MCP_ALLOWED_SUBS`               | one of emails or subs         | Comma-separated list of allowed subject IDs                                                                                                                                                                                   |
+| `MCP_OIDC_SCOPES`                | no                            | Override preset's scope list (comma-separated; default `openid email profile`)                                                                                                                                                |
+| `MCP_OIDC_EMAIL_VERIFIED_POLICY` | no                            | `strict` (default), `skip`, or `if-present`                                                                                                                                                                                   |
+| `MCP_OIDC_ALLOWED_ALGS`          | no                            | Override preset's allowed id_token signing algorithms (comma-separated)                                                                                                                                                       |
+| `MCP_TRUST_PROXY`                | no                            | `true` to trust `X-Forwarded-For` / `CF-Connecting-IP` for the DCR rate-limit key. Default `false` (safe for direct exposure). Set `true` only behind a sanitizing reverse proxy (k8s ingress, Tailscale Funnel, Cloudflare). |
+
+Example startup command:
+
+```bash
+MCP_TRANSPORT=http \
+MCP_PUBLIC_URL=https://mcp.example.com \
+MCP_OIDC_PRESET=google \
+MCP_OIDC_CLIENT_ID=123456789-abc.apps.googleusercontent.com \
+MCP_OIDC_CLIENT_SECRET=GOCSPX-... \
+MCP_ALLOWED_EMAILS=you@example.com \
+PAPRIKA_EMAIL=you@example.com \
+PAPRIKA_PASSWORD=your-password \
+  npx -y @bojanrajkovic/mcp-paprika
+```
+
+### Step 4 — Configure the allowlist
+
+The allowlist uses **OR semantics**: access is granted if the authenticated user's email is in `MCP_ALLOWED_EMAILS` OR their subject ID is in `MCP_ALLOWED_SUBS`. At least one list must be non-empty.
+
+- **`MCP_ALLOWED_EMAILS`** — comma-separated email addresses. Subject to `MCP_OIDC_EMAIL_VERIFIED_POLICY`:
+  - `strict` (default): email must be present and `email_verified = true`
+  - `skip`: email is accepted without checking `email_verified`
+  - `if-present`: if `email_verified` is in the id_token, it must be `true`; if absent, the email is accepted
+- **`MCP_ALLOWED_SUBS`** — comma-separated subject IDs (stable per-user opaque identifiers from the IdP). Useful when you want to allow access regardless of email verification status.
+
+### Step 5 — Add as a Claude connector
+
+1. Open [claude.ai](https://claude.ai) → Settings → Connectors
+2. Click "Add custom connector"
+3. Enter your server URL: `https://<MCP_PUBLIC_URL>/mcp`
+4. Claude will redirect your browser to the upstream IdP for authentication
+5. After sign-in, you are redirected back and the connector is authorized
+
+### Verify the OAuth metadata
+
+```bash
+curl -sf https://<MCP_PUBLIC_URL>/.well-known/oauth-authorization-server | jq .issuer
+# → "https://<MCP_PUBLIC_URL>"
+```
+
+The server also exposes:
+
+- `POST /mcp` — MCP JSON-RPC over Streamable HTTP
+- `GET  /mcp` — long-lived SSE channel for server→client notifications
+- `DELETE /mcp` — session termination
+- `GET /healthz` — liveness probe returning `{ "ok": true, "sessions": <n> }`
+
+## Quick start — container
+
+The image defaults to `MCP_TRANSPORT=http`, so a container run needs the same
+OAuth environment that the [HTTP transport quick start](#quick-start--http-transport)
+walks through — `MCP_PUBLIC_URL`, an OIDC preset (or discovery URL), upstream
+client credentials, and a non-empty allowlist. Without those, the server exits
+during config validation.
+
+Pull the published image (multi-arch: `linux/amd64`, `linux/arm64`):
+
+```bash
+docker pull ghcr.io/bojanrajkovic/mcp-paprika:latest
+
+docker run --rm \
+  -e PAPRIKA_EMAIL=you@example.com \
+  -e PAPRIKA_PASSWORD=your-password \
+  -e MCP_PUBLIC_URL=https://mcp.example.com \
+  -e MCP_OIDC_PRESET=google \
+  -e MCP_OIDC_CLIENT_ID=123456789-abc.apps.googleusercontent.com \
+  -e MCP_OIDC_CLIENT_SECRET=GOCSPX-... \
+  -e MCP_ALLOWED_EMAILS=you@example.com \
+  -v "$(pwd)/data:/data" \
+  -p 3000:3000 \
+  ghcr.io/bojanrajkovic/mcp-paprika:latest
+```
+
+The image is signed with [sigstore/cosign](https://github.com/sigstore/cosign) keyless OIDC and ships SLSA build provenance + an SPDX SBOM as OCI attestations. Verify both before running in untrusted environments — `gh attestation verify` without `--predicate-type` only validates the default (provenance) attestation, so the SBOM needs its own verification:
+
+```bash
+# SLSA build provenance
+gh attestation verify oci://ghcr.io/bojanrajkovic/mcp-paprika:latest \
+  --owner bojanrajkovic \
+  --predicate-type https://slsa.dev/provenance/v1
+
+# SPDX SBOM
+gh attestation verify oci://ghcr.io/bojanrajkovic/mcp-paprika:latest \
+  --owner bojanrajkovic \
+  --predicate-type https://spdx.dev/Document/v2.3
+```
+
+Contributors building from source can use `docker build -t mcp-paprika:dev .` and substitute `mcp-paprika:dev` for the image reference below.
+
+For a one-shot smoke test that just verifies the image launches (no OAuth, no
+remote clients), override the transport to `stdio` — note that this turns the
+container into a CLI process that speaks MCP on stdin/stdout, so the port
+mapping isn't used:
+
+```bash
+docker run --rm -i \
+  -e MCP_TRANSPORT=stdio \
+  -e PAPRIKA_EMAIL=you@example.com \
+  -e PAPRIKA_PASSWORD=your-password \
+  -v "$(pwd)/data:/data" \
+  ghcr.io/bojanrajkovic/mcp-paprika:latest
+```
+
+The HTTP-mode image binds on `0.0.0.0:3000` and persists the disk cache and
+vector index under `/data` (the documented mount point). Both `/data`
+sub-directories (`config/`, `cache/`) are pre-created with `nonroot` (UID 65532)
+ownership in the image so writes work the first time even on a fresh bind-mount.
+
+If you bind-mount a host directory you created as root, pre-chown it:
+
+```bash
+mkdir -p ./data && sudo chown -R 65532:65532 ./data
+```
+
+Or use a named volume (Docker handles ownership automatically):
+
+```bash
+docker run --rm \
+  -e PAPRIKA_EMAIL=... -e PAPRIKA_PASSWORD=... \
+  -v mcp-paprika-data:/data \
+  -p 3000:3000 \
+  ghcr.io/bojanrajkovic/mcp-paprika:latest
+```
+
+The image also declares a `HEALTHCHECK` that hits `GET /healthz`; verify with:
+
+```bash
+docker inspect --format '{{.State.Health.Status}}' <container>
+# → healthy
+```
+
+## Deployment patterns (HTTP transport)
+
+The HTTP transport ships with OAuth 2.1 built in. The primary remaining concerns are TLS termination and, optionally, additional network-layer controls.
+
+**TLS termination** is required — `MCP_PUBLIC_URL` must be `https://` and OAuth requires encrypted connections end-to-end. Recommended options:
+
+- **Reverse proxy with TLS** (nginx / Caddy) — terminates TLS, passes `X-Forwarded-For` headers (required for rate limiting), and forwards to the container on a private port.
+- **Cloudflare Tunnel** — no inbound port exposed; Cloudflare terminates TLS. Works well with Cloudflare Access for an additional authentication layer if desired.
+- **Tailscale HTTPS** — Tailscale's built-in HTTPS cert provisioning; suitable for homelab setups where all clients are on your tailnet.
+
+**Container deployment with Docker Compose:**
+
+```yaml
+services:
+  mcp-paprika:
+    image: ghcr.io/bojanrajkovic/mcp-paprika:latest
+    environment:
+      MCP_TRANSPORT: http
+      MCP_PUBLIC_URL: https://mcp.example.com
+      MCP_OIDC_PRESET: google
+      MCP_OIDC_CLIENT_ID: "<your-client-id>"
+      MCP_OIDC_CLIENT_SECRET: "<your-client-secret>"
+      MCP_ALLOWED_EMAILS: "you@example.com"
+      PAPRIKA_EMAIL: "you@example.com"
+      PAPRIKA_PASSWORD: "<your-paprika-password>"
+    volumes:
+      - mcp-paprika-data:/data
+    ports:
+      - "127.0.0.1:3000:3000"
+
+volumes:
+  mcp-paprika-data:
+```
+
+OAuth provides authentication-level controls; the reverse proxy provides TLS, rate limiting, and any additional network-level restrictions the deployment requires.
 
 ## Documentation
 
-- **[Configuration](docs/configuration.md)** — env vars, config files, platform paths
-- **[Tools reference](docs/tools/)** — all 10 tools with parameters and examples
+- **[Configuration](docs/configuration.md)** — env vars, config files, transport options, platform paths
+- **[Tools reference](docs/tools/)** — every tool with parameters and examples
 - **[Embedding providers](docs/embedding-providers.md)** — set up semantic search with Ollama, OpenAI, OpenRouter, etc.
 - **[Architecture](docs/architecture.md)** — how it works under the hood
+- **[Releasing](docs/releasing.md)** — maintainer-facing release model, prerelease validation, attestation verification
 
 ## License
 

package/dist/auth/allowlist.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Identity verification against allowlists with email_verified policy enforcement.
+ *
+ * Pure function — no I/O, no side effects. Returns Result<VerifiedIdentity, OAuthAllowlistDenialError>.
+ *
+ * Algorithm (email-precedence):
+ * 1. If email would be admitted (email in list AND policy allows), return with source=email
+ * 2. If email is in list but policy denies, return emailNotVerified error (blocks sub fallback)
+ * 3. Else if sub is in allowlist, return with source=sub
+ * 4. Else return notAllowlisted error
+ *
+ * Policy semantics:
+ * - strict: require email_verified === true; undefined or false both deny
+ * - skip: ignore email_verified entirely
+ * - if-present: deny only if email_verified === false; undefined (missing) is OK
+ */
+import { type Result } from "neverthrow";
+import { OAuthAllowlistDenialError } from "./errors.js";
+import type { IdTokenPayload, EmailVerifiedPolicy } from "./types.js";
+export interface AllowlistInput {
+    readonly emails: ReadonlySet<string>;
+    readonly subs: ReadonlySet<string>;
+}
+export interface VerifiedIdentity {
+    readonly email: string | null;
+    readonly sub: string;
+    readonly source: "email" | "sub";
+}
+/**
+ * Verifies an identity against email and sub allowlists with email_verified policy enforcement.
+ *
+ * @param payload The id_token payload from upstream OIDC provider
+ * @param policy The email verification policy (strict | skip | if-present)
+ * @param allowlist Email and sub allowlists as ReadonlySets
+ * @returns Ok(VerifiedIdentity) if admitted; Err(OAuthAllowlistDenialError) if denied
+ */
+export declare function verifyIdentity(payload: IdTokenPayload, policy: EmailVerifiedPolicy, allowlist: AllowlistInput): Result<VerifiedIdentity, OAuthAllowlistDenialError>;

package/dist/auth/allowlist.js

@@ -0,0 +1,69 @@
+/**
+ * Identity verification against allowlists with email_verified policy enforcement.
+ *
+ * Pure function — no I/O, no side effects. Returns Result<VerifiedIdentity, OAuthAllowlistDenialError>.
+ *
+ * Algorithm (email-precedence):
+ * 1. If email would be admitted (email in list AND policy allows), return with source=email
+ * 2. If email is in list but policy denies, return emailNotVerified error (blocks sub fallback)
+ * 3. Else if sub is in allowlist, return with source=sub
+ * 4. Else return notAllowlisted error
+ *
+ * Policy semantics:
+ * - strict: require email_verified === true; undefined or false both deny
+ * - skip: ignore email_verified entirely
+ * - if-present: deny only if email_verified === false; undefined (missing) is OK
+ */
+import { ok, err } from "neverthrow";
+import { OAuthAllowlistDenialError } from "./errors.js";
+/**
+ * Determines if a policy allows the given email_verified claim.
+ *
+ * @param verified The email_verified claim from the id_token (true | false | undefined)
+ * @param policy The email verification policy (strict | skip | if-present)
+ * @returns true if policy allows; false if policy denies
+ */
+function policyAllows(verified, policy) {
+    switch (policy) {
+        case "strict":
+            // Only true is allowed; false and undefined both deny
+            return verified === true;
+        case "skip":
+            // Always allow, ignore verified entirely
+            return true;
+        case "if-present":
+            // Allow if verified is true or undefined; deny only if false
+            return verified !== false;
+    }
+}
+/**
+ * Verifies an identity against email and sub allowlists with email_verified policy enforcement.
+ *
+ * @param payload The id_token payload from upstream OIDC provider
+ * @param policy The email verification policy (strict | skip | if-present)
+ * @param allowlist Email and sub allowlists as ReadonlySets
+ * @returns Ok(VerifiedIdentity) if admitted; Err(OAuthAllowlistDenialError) if denied
+ */
+export function verifyIdentity(payload, policy, allowlist) {
+    const email = payload.email;
+    const sub = payload.sub;
+    const verified = payload.email_verified;
+    // Step 1: Resolve email match — would email be admitted by policy?
+    const emailWouldAdmit = email && allowlist.emails.has(email) && policyAllows(verified, policy);
+    // Step 2: If email would be admitted, return with source=email
+    if (emailWouldAdmit) {
+        return ok({ email, sub, source: "email" });
+    }
+    // Step 3: Else if sub is in allowlist, return with source=sub
+    // (sub does not depend on email_verified, so this is a fallback)
+    if (sub && allowlist.subs.has(sub)) {
+        return ok({ email: email ?? null, sub, source: "sub" });
+    }
+    // Step 4: Else if email is in list but policy denies it, return emailNotVerified error
+    // (This is only reached if sub did not match, ensuring email takes precedence)
+    if (email && allowlist.emails.has(email) && !policyAllows(verified, policy)) {
+        return err(OAuthAllowlistDenialError.emailNotVerified(email, policy));
+    }
+    // Step 5: Neither email nor sub admitted the identity
+    return err(OAuthAllowlistDenialError.notAllowlisted(email ?? null, sub));
+}

package/dist/auth/auth-code-store.d.ts

@@ -0,0 +1,41 @@
+/**
+ * In-memory TTL store for OAuth 2.1 post-callback state (authorization code).
+ *
+ * Keyed by `our_auth_code` (our unique authorization code). Default TTL: 60 seconds.
+ * Consume-on-read: calling `consume()` atomically deletes the entry for single-use replay protection.
+ * Lazy TTL eviction: expired entries are deleted on `consume()`, `peek()`, or `sweepExpired()`.
+ *
+ * Identity is populated by the `/oauth/callback` handler after verifying the
+ * upstream id_token and checking the allowlist. The store does not enrich; it stores
+ * whatever is handed to `put()`.
+ *
+ * No persistence across restart (in-memory only). Auth codes do NOT survive process restart,
+ * which aligns with OAuth 2.1 short-lived code semantics and prevents code-reuse across restarts.
+ */
+import type { AuthCodeState } from "./types.js";
+import { TtlStore } from "./ttl-store.js";
+export declare class AuthCodeStore extends TtlStore<AuthCodeState> {
+    /**
+     * Constructor with optional TTL and clock injection for testing.
+     *
+     * @param opts.ttlMs - TTL in milliseconds (default: AUTH_CODE_TTL_SECONDS * 1000)
+     * @param opts.now - Clock function returning milliseconds (default: Date.now)
+     */
+    constructor(opts?: {
+        readonly ttlMs?: number;
+        readonly now?: () => number;
+    });
+    /**
+     * Retrieve WITHOUT consuming an authorization code state.
+     *
+     * Used by the provider's challengeForAuthorizationCode which runs BEFORE
+     * exchangeAuthorizationCode in the same /token request. The actual consume
+     * happens later in exchangeAuthorizationCode.
+     *
+     * Still evicts expired entries on peek (lazy eviction).
+     *
+     * @param authCode - The authorization code to peek at
+     * @returns The AuthCodeState, or null if not found or expired
+     */
+    peek(authCode: string): AuthCodeState | null;
+}

package/dist/auth/auth-code-store.js

@@ -0,0 +1,56 @@
+/**
+ * In-memory TTL store for OAuth 2.1 post-callback state (authorization code).
+ *
+ * Keyed by `our_auth_code` (our unique authorization code). Default TTL: 60 seconds.
+ * Consume-on-read: calling `consume()` atomically deletes the entry for single-use replay protection.
+ * Lazy TTL eviction: expired entries are deleted on `consume()`, `peek()`, or `sweepExpired()`.
+ *
+ * Identity is populated by the `/oauth/callback` handler after verifying the
+ * upstream id_token and checking the allowlist. The store does not enrich; it stores
+ * whatever is handed to `put()`.
+ *
+ * No persistence across restart (in-memory only). Auth codes do NOT survive process restart,
+ * which aligns with OAuth 2.1 short-lived code semantics and prevents code-reuse across restarts.
+ */
+import { AUTH_CODE_TTL_SECONDS } from "./tokens.js";
+import { TtlStore } from "./ttl-store.js";
+export class AuthCodeStore extends TtlStore {
+    /**
+     * Constructor with optional TTL and clock injection for testing.
+     *
+     * @param opts.ttlMs - TTL in milliseconds (default: AUTH_CODE_TTL_SECONDS * 1000)
+     * @param opts.now - Clock function returning milliseconds (default: Date.now)
+     */
+    constructor(opts) {
+        super({
+            ttlMs: opts?.ttlMs ?? AUTH_CODE_TTL_SECONDS * 1000,
+            ...(opts?.now !== undefined ? { now: opts.now } : {}),
+        });
+    }
+    /**
+     * Retrieve WITHOUT consuming an authorization code state.
+     *
+     * Used by the provider's challengeForAuthorizationCode which runs BEFORE
+     * exchangeAuthorizationCode in the same /token request. The actual consume
+     * happens later in exchangeAuthorizationCode.
+     *
+     * Still evicts expired entries on peek (lazy eviction).
+     *
+     * @param authCode - The authorization code to peek at
+     * @returns The AuthCodeState, or null if not found or expired
+     */
+    peek(authCode) {
+        const entry = this._entries.get(authCode);
+        if (entry === undefined)
+            return null;
+        // Check TTL: entry.createdAt is in seconds, _ttlMs is in milliseconds, _now() is in milliseconds
+        const expiresAt = entry.createdAt + this._ttlMs / 1000;
+        const now = Math.floor(this._now() / 1000);
+        if (expiresAt < now) {
+            // Still evict expired entries on peek
+            this._entries.delete(authCode);
+            return null; // expired
+        }
+        return entry;
+    }
+}

package/dist/auth/auth-request-store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * In-memory TTL store for OAuth 2.1 pre-callback state (OIDC auth_request).
+ *
+ * Keyed by `our_state` (CSRF token). Default TTL: 5 minutes.
+ * Consume-on-read: calling `consume()` atomically deletes the entry for single-use semantics.
+ * Lazy TTL eviction: expired entries are deleted on `consume()` or `sweepExpired()`.
+ *
+ * No persistence across restart (in-memory only). Not used in normal production cleanup
+ * as the entries typically consume within seconds of creation. `sweepExpired()` is called
+ * periodically by `AuthCleanup` for memory hygiene.
+ */
+import type { AuthRequestState } from "./types.js";
+import { TtlStore } from "./ttl-store.js";
+export declare class AuthRequestStore extends TtlStore<AuthRequestState> {
+    /**
+     * Constructor with optional TTL and clock injection for testing.
+     *
+     * @param opts.ttlMs - TTL in milliseconds (default: AUTH_REQUEST_TTL_SECONDS * 1000)
+     * @param opts.now - Clock function returning milliseconds (default: Date.now)
+     */
+    constructor(opts?: {
+        readonly ttlMs?: number;
+        readonly now?: () => number;
+    });
+}

package/dist/auth/auth-request-store.js

@@ -0,0 +1,27 @@
+/**
+ * In-memory TTL store for OAuth 2.1 pre-callback state (OIDC auth_request).
+ *
+ * Keyed by `our_state` (CSRF token). Default TTL: 5 minutes.
+ * Consume-on-read: calling `consume()` atomically deletes the entry for single-use semantics.
+ * Lazy TTL eviction: expired entries are deleted on `consume()` or `sweepExpired()`.
+ *
+ * No persistence across restart (in-memory only). Not used in normal production cleanup
+ * as the entries typically consume within seconds of creation. `sweepExpired()` is called
+ * periodically by `AuthCleanup` for memory hygiene.
+ */
+import { AUTH_REQUEST_TTL_SECONDS } from "./tokens.js";
+import { TtlStore } from "./ttl-store.js";
+export class AuthRequestStore extends TtlStore {
+    /**
+     * Constructor with optional TTL and clock injection for testing.
+     *
+     * @param opts.ttlMs - TTL in milliseconds (default: AUTH_REQUEST_TTL_SECONDS * 1000)
+     * @param opts.now - Clock function returning milliseconds (default: Date.now)
+     */
+    constructor(opts) {
+        super({
+            ttlMs: opts?.ttlMs ?? AUTH_REQUEST_TTL_SECONDS * 1000,
+            ...(opts?.now !== undefined ? { now: opts.now } : {}),
+        });
+    }
+}

package/dist/auth/build.d.ts

@@ -0,0 +1,15 @@
+/**
+ * buildAuthContext — constructs the OAuth 2.1 runtime for HTTP mode.
+ *
+ * Returns null when transport !== "http" (stdio mode needs no auth).
+ * Throws on misconfiguration or upstream discovery failure — this is a
+ * fail-fast startup operation; there is no value running HTTP mode if
+ * the OAuth stack can't authenticate anyone.
+ *
+ * Called once per process from buildAppContext (src/server/build.ts)
+ * after cache.init() completes.
+ */
+import type { DiskCache } from "../cache/disk-cache.js";
+import type { PaprikaConfig } from "../utils/config.js";
+import type { AuthContext } from "./types.js";
+export declare function buildAuthContext(config: PaprikaConfig, cache: DiskCache): Promise<AuthContext | null>;

package/dist/auth/build.js

@@ -0,0 +1,84 @@
+/**
+ * buildAuthContext — constructs the OAuth 2.1 runtime for HTTP mode.
+ *
+ * Returns null when transport !== "http" (stdio mode needs no auth).
+ * Throws on misconfiguration or upstream discovery failure — this is a
+ * fail-fast startup operation; there is no value running HTTP mode if
+ * the OAuth stack can't authenticate anyone.
+ *
+ * Called once per process from buildAppContext (src/server/build.ts)
+ * after cache.init() completes.
+ */
+import { resolvePreset } from "./presets.js";
+import { loadDiscovery, createJwksFor } from "./oidc-client.js";
+import { DiskClientRegistrationStore } from "./client-registration.js";
+import { TokenStore } from "./token-store.js";
+import { AuthRequestStore } from "./auth-request-store.js";
+import { AuthCodeStore } from "./auth-code-store.js";
+import { MintingOAuthServerProvider } from "./provider.js";
+import { AuthCleanup } from "./cleanup.js";
+import { MAX_REGISTERED_CLIENTS } from "./routes.js";
+export async function buildAuthContext(config, cache) {
+    if (config.transport !== "http")
+        return null;
+    if (config.oauth === undefined) {
+        // The root-level superRefine in src/utils/config.ts catches this case before
+        // we get here, but defensively re-check so downstream code can rely on non-null.
+        throw new Error("OAuth config required for HTTP transport (should have failed at config load)");
+    }
+    const presetOverrides = {};
+    if (config.oauth.discoveryUrl !== undefined)
+        presetOverrides.discoveryUrl = config.oauth.discoveryUrl;
+    if (config.oauth.scopes !== undefined)
+        presetOverrides.scopes = config.oauth.scopes;
+    if (config.oauth.emailVerifiedPolicy !== undefined)
+        presetOverrides.emailVerifiedPolicy = config.oauth.emailVerifiedPolicy;
+    if (config.oauth.allowedAlgs !== undefined)
+        presetOverrides.allowedAlgs = config.oauth.allowedAlgs;
+    const resolveResult = resolvePreset(config.oauth.preset, presetOverrides);
+    const presetResult = resolveResult.match((r) => r, (e) => {
+        throw e; // fail-fast at startup
+    });
+    // Assemble full ResolvedOAuthConfig by merging the preset result with
+    // the deployment-specific fields validated by superRefine.
+    // These three fields are guaranteed non-undefined when transport === "http"
+    // by superRefine in src/utils/config.ts.  The invariant guards below make
+    // that contract explicit and narrow the types without `as string` casts.
+    if (config.oauth.publicUrl === undefined) {
+        throw new Error("invariant: oauth.publicUrl must be set when transport=http");
+    }
+    if (config.oauth.clientId === undefined) {
+        throw new Error("invariant: oauth.clientId must be set when transport=http");
+    }
+    if (config.oauth.clientSecret === undefined) {
+        throw new Error("invariant: oauth.clientSecret must be set when transport=http");
+    }
+    const resolved = {
+        ...presetResult,
+        publicUrl: config.oauth.publicUrl,
+        clientId: config.oauth.clientId,
+        clientSecret: config.oauth.clientSecret,
+        trustProxy: config.oauth.trustProxy,
+        allowlist: config.oauth.allowlist,
+    };
+    // Fetch + validate upstream discovery document (rejects http:// endpoints; checks alg overlap)
+    const discovery = await loadDiscovery(resolved.discoveryUrl, resolved.allowedAlgs);
+    const jwks = createJwksFor(discovery);
+    const clientStore = new DiskClientRegistrationStore(cache, resolved.publicUrl, MAX_REGISTERED_CLIENTS);
+    const tokenStore = new TokenStore(cache);
+    const requestStore = new AuthRequestStore();
+    const codeStore = new AuthCodeStore();
+    const provider = new MintingOAuthServerProvider(clientStore, tokenStore, requestStore, codeStore, discovery, resolved, resolved.publicUrl);
+    const cleanup = new AuthCleanup(clientStore, tokenStore, cache, requestStore, codeStore);
+    return {
+        provider,
+        config: resolved,
+        discovery,
+        jwks,
+        authRequests: requestStore,
+        authCodes: codeStore,
+        tokenStore,
+        clientStore,
+        cleanup,
+    };
+}