@bojanrajkovic/mcp-paprika 1.6.0 → 2.0.0-beta.1

package/README.md

@@ -1,27 +1,29 @@
 # @bojanrajkovic/mcp-paprika
 
-An [MCP](https://modelcontextprotocol.io/) server for [Paprika](https://www.paprikaapp.com/) recipe manager. Search, browse, create, and manage your recipes from any MCP client.
+An [MCP](https://modelcontextprotocol.io/) server for the [Paprika](https://www.paprikaapp.com/) recipe manager. Search, browse, create, and manage your recipes from any MCP client.
 
 ## Features
 
-- **40 tools** for recipe, pantry, grocery, meal-planner, and menu management — search, filter, CRUD, categories, pagination, pantry inventory, aisles, grocery lists and items, meal planning (history, meal types, dated planner entries), and menus (recipe collections, their items, and one-shot add-to-planner)
+- **Full tool coverage** for recipe, pantry, grocery, meal-planner, and menu management — search, filter, CRUD, categories, pagination, pantry inventory, aisles, grocery lists and items, meal planning (the upcoming plan, history recall, meal types, dated planner entries), and menus (recipe collections, their items, and one-shot add-to-planner)
 - **Semantic search** via `discover_recipes` — find recipes by natural language description using any OpenAI-compatible embedding provider
-- **AI recipe photos** via `generate_photo` — generate a styled food photo for a recipe (or restyle its existing one) using OpenRouter image models, and attach it automatically
+- **AI recipe photos** via `generate_recipe_photo` — generate a styled food photo for a recipe (or restyle its existing one) using OpenRouter image models, and attach it automatically
 - **Background sync** — keeps your local cache in sync with Paprika's cloud
-- **MCP resources** — expose recipes as `paprika://recipe/{uid}`, grocery lists as `paprika://grocery-list/{uid}`, and menus as `paprika://menu/{uid}` resources
+- **MCP resources** — recipes as `paprika://recipe/{uid}`, grocery lists as `paprika://grocery-list/{uid}`, and menus as `paprika://menu/{uid}`
 - **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
+- **Container image** — a distroless runtime ready for self-hosting
 
 ## Transports
 
-`mcp-paprika` can speak the MCP protocol over two transports, selected via `MCP_TRANSPORT`:
+`mcp-paprika` speaks 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.
+The HTTP transport ships with **OAuth 2.1** (authorization code + PKCE, RFC 7591
+dynamic client registration); the [HTTP transport quick start](docs/quick-start-http.md)
+sets it up end to end.
 
 ## Quick start — stdio (Claude Desktop / Claude Code / Cursor)
 
@@ -42,226 +44,33 @@ Add to your MCP client config:
 }
 ```
 
-## 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`):
+That's the whole local setup. To enable semantic search or AI recipe photos, add the
+optional provider credentials from [configuration.md](docs/configuration.md).
 
-```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.
+## Quick start — HTTP transport
 
-**Container deployment with Docker Compose:**
+For remote clients (Claude Mobile, claude.ai), the server speaks Streamable HTTP behind
+OAuth 2.1, delegating identity to an upstream OIDC provider you choose. The
+[HTTP transport quick start](docs/quick-start-http.md) walks an IdP from zero to a
+working Claude connector, and [deployment.md](docs/deployment.md) covers running it in a
+container, behind a reverse proxy, or 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"
+## Documentation
 
-volumes:
-  mcp-paprika-data:
-```
+**Guides**
 
-OAuth provides authentication-level controls; the reverse proxy provides TLS, rate limiting, and any additional network-level restrictions the deployment requires.
+- **[HTTP transport quick start](docs/quick-start-http.md)** — OIDC setup from zero to a Claude connector
+- **[Deployment](docs/deployment.md)** — container, TLS termination, Docker Compose
 
-## Documentation
+**Reference**
 
-- **[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
+- **[Configuration](docs/configuration.md)** — env vars, config files, platform paths
+- **[HTTP transport](docs/http-transport.md)** — binding, host/origin allowlists, graceful shutdown
+- **[OAuth 2.1 configuration](docs/oauth-configuration.md)** — OIDC providers, allowlist, consent gate
+- **[Tools reference](https://github.com/bojanrajkovic/mcp-paprika/tree/main/docs/tools)** — every tool with parameters and examples
+- **[Embedding providers](docs/embedding-providers.md)** — semantic search with Ollama, OpenAI, OpenRouter
+- **[Architecture](https://github.com/bojanrajkovic/mcp-paprika/blob/main/docs/architecture.md)** — how it works under the hood
+- **[Releasing](https://github.com/bojanrajkovic/mcp-paprika/blob/main/docs/releasing.md)** — release model, prerelease validation, attestation verification
 
 ## License
 

package/dist/aisle/disk.d.ts

@@ -0,0 +1,3 @@
+import type { DiskCacheDescriptor } from "../cache/disk-cache.js";
+import type { Aisle } from "./types.js";
+export declare const aisleDiskDescriptor: DiskCacheDescriptor<Aisle>;

package/dist/aisle/disk.js

@@ -0,0 +1,6 @@
+import { AisleStoredSchema } from "./types.js";
+export const aisleDiskDescriptor = {
+    subdir: "aisles",
+    parse: (raw) => AisleStoredSchema.parse(raw),
+    getKey: (a) => a.uid,
+};

package/dist/{cache/aisle-store.d.ts → aisle/store.d.ts}

@@ -1,5 +1,6 @@
+import type { AisleUid } from "../ids.js";
+import type { Aisle } from "./types.js";
 import { EntityStore } from "../entity/index.js";
-import type { Aisle, AisleUid } from "../paprika/types.js";
 export declare class AisleStore extends EntityStore<Aisle, AisleUid> {
     constructor(opts?: {
         readonly pendingWriteTtlMs?: number;

package/dist/aisle/types.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+export declare const AisleStoredSchema: z.ZodObject<{
+    uid: z.ZodBranded<z.ZodString, "AisleUid">;
+    name: z.ZodString;
+    orderFlag: z.ZodNumber;
+    deleted: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    uid: string & z.BRAND<"AisleUid">;
+    name: string;
+    orderFlag: number;
+    deleted: boolean;
+}, {
+    uid: string;
+    name: string;
+    orderFlag: number;
+    deleted?: boolean | undefined;
+}>;
+export type Aisle = z.infer<typeof AisleStoredSchema>;
+export declare const AisleSchema: z.ZodEffects<z.ZodObject<{
+    uid: z.ZodBranded<z.ZodString, "AisleUid">;
+    name: z.ZodString;
+    order_flag: z.ZodNumber;
+    deleted: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    uid: string & z.BRAND<"AisleUid">;
+    name: string;
+    deleted: boolean;
+    order_flag: number;
+}, {
+    uid: string;
+    name: string;
+    order_flag: number;
+    deleted?: boolean | undefined;
+}>, {
+    uid: string & z.BRAND<"AisleUid">;
+    name: string;
+    orderFlag: number;
+    deleted: boolean;
+}, {
+    uid: string;
+    name: string;
+    order_flag: number;
+    deleted?: boolean | undefined;
+}>;

package/dist/aisle/types.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { AisleUidSchema } from "../ids.js";
+// AisleStoredSchema — validates camelCase JSON read back from disk. No transform.
+export const AisleStoredSchema = z.object({
+    uid: AisleUidSchema,
+    name: z.string(),
+    orderFlag: z.number().int(),
+    deleted: z.boolean().optional().default(false),
+});
+// AisleSchema — accepts snake_case wire format, transforms to camelCase Aisle.
+export const AisleSchema = z
+    .object({
+    uid: AisleUidSchema,
+    name: z.string(),
+    order_flag: z.number().int(),
+    deleted: z.boolean().optional().default(false),
+})
+    .transform(({ order_flag, ...rest }) => ({
+    ...rest,
+    orderFlag: order_flag,
+}));

package/dist/auth/allowlist.d.ts

@@ -15,8 +15,8 @@
  * - if-present: deny only if email_verified === false; undefined (missing) is OK
  */
 import { type Result } from "neverthrow";
+import type { EmailVerifiedPolicy, IdTokenPayload } from "./types.js";
 import { OAuthAllowlistDenialError } from "./errors.js";
-import type { IdTokenPayload, EmailVerifiedPolicy } from "./types.js";
 export interface AllowlistInput {
     readonly emails: ReadonlySet<string>;
     readonly subs: ReadonlySet<string>;

package/dist/auth/allowlist.js

@@ -14,7 +14,7 @@
  * - skip: ignore email_verified entirely
  * - if-present: deny only if email_verified === false; undefined (missing) is OK
  */
-import { ok, err } from "neverthrow";
+import { err, ok } from "neverthrow";
 import { OAuthAllowlistDenialError } from "./errors.js";
 /**
  * Determines if a policy allows the given email_verified claim.

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

@@ -20,10 +20,12 @@ export declare class AuthCodeStore extends TtlStore<AuthCodeState> {
      *
      * @param opts.ttlMs - TTL in milliseconds (default: AUTH_CODE_TTL_SECONDS * 1000)
      * @param opts.now - Clock function returning milliseconds (default: Date.now)
+     * @param opts.maxEntries - Entry cap (default: MAX_INMEMORY_AUTH_ENTRIES)
      */
     constructor(opts?: {
         readonly ttlMs?: number;
         readonly now?: () => number;
+        readonly maxEntries?: number;
     });
     /**
      * Retrieve WITHOUT consuming an authorization code state.

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

@@ -12,7 +12,7 @@
  * 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 { AUTH_CODE_TTL_SECONDS, MAX_INMEMORY_AUTH_ENTRIES } from "./tokens.js";
 import { TtlStore } from "./ttl-store.js";
 export class AuthCodeStore extends TtlStore {
     /**
@@ -20,10 +20,12 @@ export class AuthCodeStore extends TtlStore {
      *
      * @param opts.ttlMs - TTL in milliseconds (default: AUTH_CODE_TTL_SECONDS * 1000)
      * @param opts.now - Clock function returning milliseconds (default: Date.now)
+     * @param opts.maxEntries - Entry cap (default: MAX_INMEMORY_AUTH_ENTRIES)
      */
     constructor(opts) {
         super({
             ttlMs: opts?.ttlMs ?? AUTH_CODE_TTL_SECONDS * 1000,
+            maxEntries: opts?.maxEntries ?? MAX_INMEMORY_AUTH_ENTRIES,
             ...(opts?.now !== undefined ? { now: opts.now } : {}),
         });
     }

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

@@ -17,9 +17,11 @@ export declare class AuthRequestStore extends TtlStore<AuthRequestState> {
      *
      * @param opts.ttlMs - TTL in milliseconds (default: AUTH_REQUEST_TTL_SECONDS * 1000)
      * @param opts.now - Clock function returning milliseconds (default: Date.now)
+     * @param opts.maxEntries - Entry cap (default: MAX_INMEMORY_AUTH_ENTRIES)
      */
     constructor(opts?: {
         readonly ttlMs?: number;
         readonly now?: () => number;
+        readonly maxEntries?: number;
     });
 }

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

@@ -9,7 +9,7 @@
  * 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 { AUTH_REQUEST_TTL_SECONDS, MAX_INMEMORY_AUTH_ENTRIES } from "./tokens.js";
 import { TtlStore } from "./ttl-store.js";
 export class AuthRequestStore extends TtlStore {
     /**
@@ -17,10 +17,12 @@ export class AuthRequestStore extends TtlStore {
      *
      * @param opts.ttlMs - TTL in milliseconds (default: AUTH_REQUEST_TTL_SECONDS * 1000)
      * @param opts.now - Clock function returning milliseconds (default: Date.now)
+     * @param opts.maxEntries - Entry cap (default: MAX_INMEMORY_AUTH_ENTRIES)
      */
     constructor(opts) {
         super({
             ttlMs: opts?.ttlMs ?? AUTH_REQUEST_TTL_SECONDS * 1000,
+            maxEntries: opts?.maxEntries ?? MAX_INMEMORY_AUTH_ENTRIES,
             ...(opts?.now !== undefined ? { now: opts.now } : {}),
         });
     }

package/dist/auth/build.d.ts

@@ -10,7 +10,7 @@
  * after cache.init() completes.
  */
 import type { Logger } from "pino";
-import type { DiskCacheRoot } from "../cache/disk/index.js";
+import type { DiskCacheRoot } from "../cache/disk-cache-root.js";
 import type { PaprikaConfig } from "../utils/config.js";
 import type { AuthContext } from "./types.js";
 export declare function buildAuthContext(config: PaprikaConfig, cache: DiskCacheRoot, parentLog: Logger): Promise<AuthContext | null>;

package/dist/auth/build.js

@@ -9,15 +9,17 @@
  * 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 { AuthRequestStore } from "./auth-request-store.js";
 import { AuthCleanup } from "./cleanup.js";
+import { DiskClientRegistrationStore } from "./client-registration.js";
+import { createJwksFor, loadDiscovery } from "./oidc-client.js";
+import { PendingAuthorizationStore } from "./pending-authorization-store.js";
+import { resolvePreset } from "./presets.js";
+import { MintingOAuthServerProvider } from "./provider.js";
+import { normalizeOrigin } from "./redirect-allowlist.js";
 import { MAX_REGISTERED_CLIENTS } from "./routes.js";
+import { TokenStore } from "./token-store.js";
 export async function buildAuthContext(config, cache, parentLog) {
     if (config.transport !== "http")
         return null;
@@ -53,6 +55,13 @@ export async function buildAuthContext(config, cache, parentLog) {
     if (config.oauth.clientSecret === undefined) {
         throw new Error("invariant: oauth.clientSecret must be set when transport=http");
     }
+    // Normalize the raw redirect-allowlist strings to canonical origins, failing
+    // fast at startup on any malformed/non-permitted entry (#147). config.ts
+    // keeps the strings raw so it has no dependency on src/auth/; the auth layer
+    // owns origin validation.
+    const redirectAllowlist = config.oauth.redirectAllowlist.map((entry) => normalizeOrigin(entry).match((origin) => origin, (e) => {
+        throw e; // fail-fast at startup
+    }));
     const resolved = {
         ...presetResult,
         publicUrl: config.oauth.publicUrl,
@@ -60,6 +69,7 @@ export async function buildAuthContext(config, cache, parentLog) {
         clientSecret: config.oauth.clientSecret,
         trustProxy: config.oauth.trustProxy,
         allowlist: config.oauth.allowlist,
+        redirectAllowlist,
     };
     const authLog = parentLog.child({ component: "auth" });
     const oidcClientLog = parentLog.child({ component: "oidc-client" });
@@ -70,8 +80,9 @@ export async function buildAuthContext(config, cache, parentLog) {
     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, authLog);
-    const cleanup = new AuthCleanup(clientStore, tokenStore, cache, requestStore, codeStore, authLog);
+    const pendingStore = new PendingAuthorizationStore();
+    const provider = new MintingOAuthServerProvider(clientStore, tokenStore, requestStore, codeStore, pendingStore, discovery, resolved, resolved.publicUrl, authLog);
+    const cleanup = new AuthCleanup(clientStore, tokenStore, cache, requestStore, codeStore, pendingStore, authLog);
     return {
         provider,
         config: resolved,
@@ -79,6 +90,7 @@ export async function buildAuthContext(config, cache, parentLog) {
         jwks,
         authRequests: requestStore,
         authCodes: codeStore,
+        pendingAuthorizations: pendingStore,
         tokenStore,
         clientStore,
         cleanup,

package/dist/auth/cleanup.d.ts

@@ -6,7 +6,8 @@
  *
  * Responsibilities (run every CLEANUP_INTERVAL_MS = 6h):
  * 1. Remove stale DCR clients (lastTokenActivityAt > 90 days old) + cascade their tokens.
- * 2. Sweep expired in-memory AuthRequestStore and AuthCodeStore entries.
+ * 2. Sweep expired in-memory AuthRequestStore, AuthCodeStore, and
+ *    PendingAuthorizationStore (consent-ticket) entries.
  * 3. Sweep expired OAuth tokens (expiresAt < now). `rotateRefresh` deletes the
  *    previous refresh token but not the previous access token — every refresh
  *    leaves a soon-to-expire access record behind. Without this sweep,
@@ -16,10 +17,11 @@
  * Public `sweepOnce()` is exposed for direct testing and for startup use.
  */
 import type { Logger } from "pino";
-import type { DiskCacheRoot } from "../cache/disk/index.js";
-import type { AuthRequestStore } from "./auth-request-store.js";
+import type { DiskCacheRoot } from "../cache/disk-cache-root.js";
 import type { AuthCodeStore } from "./auth-code-store.js";
+import type { AuthRequestStore } from "./auth-request-store.js";
 import type { DiskClientRegistrationStore } from "./client-registration.js";
+import type { PendingAuthorizationStore } from "./pending-authorization-store.js";
 import type { TokenStore } from "./token-store.js";
 export declare class AuthCleanup {
     private readonly _clientStore;
@@ -27,11 +29,12 @@ export declare class AuthCleanup {
     private readonly _cache;
     private readonly _authRequests;
     private readonly _authCodes;
+    private readonly _pendingAuthorizations;
     private readonly log;
     private readonly _now;
     private readonly _intervalMs;
     private _ac;
-    constructor(_clientStore: DiskClientRegistrationStore, _tokenStore: TokenStore, _cache: DiskCacheRoot, _authRequests: AuthRequestStore, _authCodes: AuthCodeStore, log: Logger, _now?: () => number, _intervalMs?: number);
+    constructor(_clientStore: DiskClientRegistrationStore, _tokenStore: TokenStore, _cache: DiskCacheRoot, _authRequests: AuthRequestStore, _authCodes: AuthCodeStore, _pendingAuthorizations: PendingAuthorizationStore, log: Logger, _now?: () => number, _intervalMs?: number);
     /** Start the background cleanup loop. Idempotent — second call is a no-op. */
     start(): void;
     /** Stop the background cleanup loop. Idempotent — second call is a no-op. */
@@ -53,6 +56,7 @@ export declare class AuthCleanup {
         expiredTokensRemoved: number;
         authRequestsRemoved: number;
         authCodesRemoved: number;
+        pendingAuthorizationsRemoved: number;
     }>;
     private _loop;
 }

package/dist/auth/cleanup.js

@@ -6,7 +6,8 @@
  *
  * Responsibilities (run every CLEANUP_INTERVAL_MS = 6h):
  * 1. Remove stale DCR clients (lastTokenActivityAt > 90 days old) + cascade their tokens.
- * 2. Sweep expired in-memory AuthRequestStore and AuthCodeStore entries.
+ * 2. Sweep expired in-memory AuthRequestStore, AuthCodeStore, and
+ *    PendingAuthorizationStore (consent-ticket) entries.
  * 3. Sweep expired OAuth tokens (expiresAt < now). `rotateRefresh` deletes the
  *    previous refresh token but not the previous access token — every refresh
  *    leaves a soon-to-expire access record behind. Without this sweep,
@@ -24,16 +25,18 @@ export class AuthCleanup {
     _cache;
     _authRequests;
     _authCodes;
+    _pendingAuthorizations;
     log;
     _now;
     _intervalMs;
     _ac = null;
-    constructor(_clientStore, _tokenStore, _cache, _authRequests, _authCodes, log, _now = () => nowSeconds(), _intervalMs = CLEANUP_INTERVAL_MS) {
+    constructor(_clientStore, _tokenStore, _cache, _authRequests, _authCodes, _pendingAuthorizations, log, _now = () => nowSeconds(), _intervalMs = CLEANUP_INTERVAL_MS) {
         this._clientStore = _clientStore;
         this._tokenStore = _tokenStore;
         this._cache = _cache;
         this._authRequests = _authRequests;
         this._authCodes = _authCodes;
+        this._pendingAuthorizations = _pendingAuthorizations;
         this.log = log;
         this._now = _now;
         this._intervalMs = _intervalMs;
@@ -87,6 +90,7 @@ export class AuthCleanup {
         // (2) In-memory store sweeps — bound memory under sustained /authorize traffic
         const authRequestsRemoved = this._authRequests.sweepExpired();
         const authCodesRemoved = this._authCodes.sweepExpired();
+        const pendingAuthorizationsRemoved = this._pendingAuthorizations.sweepExpired();
         // (3) Expired-token sweep — remove tokens past `expiresAt` whose owning
         //     client is still active (stale-client cascade already covers the
         //     others). `rotateRefresh` deletes the old refresh but not the old
@@ -105,6 +109,7 @@ export class AuthCleanup {
             expiredTokensRemoved,
             authRequestsRemoved,
             authCodesRemoved,
+            pendingAuthorizationsRemoved,
         };
     }
     async _loop() {

package/dist/auth/client-registration.d.ts

@@ -10,7 +10,7 @@
  * - verifyRegistrationAccessToken: used by route handlers to gate PUT/DELETE access
  */
 import type { Logger } from "pino";
-import type { DiskCacheRoot } from "../cache/disk/index.js";
+import type { DiskCacheRoot } from "../cache/disk-cache-root.js";
 /**
  * Wire format for client information (RFC 7591 response format).
  * Snake_case to match RFC 7591.