vikunja-mcp-ng 0.6.2 → 0.7.0-beta.0

package/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2025 Jeremy Green
+Copyright (c) 2026 Pierre Christen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -3,33 +3,19 @@
 **Give your AI assistant real hands on your Vikunja instance** — create and triage tasks, manage projects and Kanban boards, assign teammates, and more, through natural conversation.
 
 [![npm](https://img.shields.io/npm/v/vikunja-mcp-ng.svg)](https://www.npmjs.com/package/vikunja-mcp-ng)
-[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![node: 20+](https://img.shields.io/badge/node-20%2B-brightgreen.svg)](package.json)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/netadvanced/vikunja-mcp-ng/blob/main/LICENSE)
+[![node: 22+](https://img.shields.io/badge/node-22%2B-brightgreen.svg)](https://github.com/netadvanced/vikunja-mcp-ng/blob/main/package.json)
 [![MCP](https://img.shields.io/badge/MCP-server-purple.svg)](https://modelcontextprotocol.io)
 
-> 👋 **Why this fork exists:** we rely on this project and noticed the [upstream repo](https://github.com/democratize-technology/vikunja-mcp) had gone quiet, with a growing backlog of open PRs and issues. So we've taken over active maintenance here — triaging and resolving most of that backlog (tracked in [this issue](https://github.com/netadvanced/vikunja-mcp-ng/issues/19)). Full credit to the original authors for the foundation. If they'd like to pick it back up, we'll gladly hand the reins back — or work together.
+This server exposes Vikunja as **27 tools**, each covering one entity (tasks, projects, labels, teams…) with a consistent `subcommand` pattern — not a 1:1 REST proxy, but composite operations built for how an AI actually works: resolve a username instead of demanding a user ID, verify that tricky writes actually stuck instead of trusting a `200`, and require explicit confirmation on destructive operations. Your assistant reasons in natural language; the server turns that into correct Vikunja API calls and reports partial failures honestly instead of pretending success.
 
----
+## Requirements
 
-## What this gives your AI assistant
+- **Node.js 22+** (Node 20 reached end-of-life in April 2026)
+- A Vikunja instance, **2.3.0 or newer** — tested against 2.4.0, with 2.3.0 as the supported floor
+- An API token (`tk_…`) or JWT from that instance
 
-This server exposes Vikunja as **27 tools** (a session tool, 22 available by default or by auth type, and 4 sensitive ones that are off until an operator opts in), each covering one entity (tasks, projects, labels, teams…) with a consistent `subcommand` pattern — not a 1:1 REST proxy, but composite operations built for how an AI actually works: resolve a username instead of demanding a user ID, verify that tricky writes actually stuck instead of trusting a 200, and explicit confirmation gates on destructive operations. Your assistant reasons in natural language; the server turns that into correct Vikunja API calls and reports partial failures honestly instead of pretending success.
-
-## See it in action
-
-> **You:** "Move 'Fix login redirect bug' to In Review and show me the board."
-
-```typescript
-vikunja_tasks({ subcommand: "set-bucket", id: 342, bucketId: 43 })
-```
-
-`projectId`/`viewId` auto-resolve from the task — no need to know which view is the Kanban one. The task card slides from *Backlog* into *In Review* on the Kanban board, instantly visible to anyone else looking at the board.
-
-More end-to-end scenarios — daily triage, team sharing, project planning, staying informed, bulk imports, admin ops — each paired with the exact tool call and the resulting Vikunja UI state, live in [`docs/samples/`](docs/samples/).
-
-## Quick Start
-
-### From npm (recommended)
+## Quick start
 
 No install step needed — point your MCP client at `npx`:
 
@@ -40,7 +26,7 @@ No install step needed — point your MCP client at `npx`:
       "command": "npx",
       "args": ["-y", "vikunja-mcp-ng"],
       "env": {
-        "VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
+        "VIKUNJA_URL": "https://your-vikunja-instance.com",
         "VIKUNJA_API_TOKEN": "your-api-token"
       }
     }
@@ -48,35 +34,13 @@ No install step needed — point your MCP client at `npx`:
 }
 ```
 
-Or install globally (`npm install -g vikunja-mcp-ng`) and use `"command": "vikunja-mcp-ng"` with no args.
-
-### From source
-
-```bash
-git clone https://github.com/netadvanced/vikunja-mcp-ng.git
-cd vikunja-mcp-ng
-npm ci
-npm run build
-```
+Use the bare instance URL for `VIKUNJA_URL` — the server resolves the right API path itself (today that's always `/api/v1`; an explicit `/api/v1` suffix still works too). The bare form is also the future-proof choice: it's the same URL the server will use to pick between v1 and v2 automatically once v2 support lands.
 
-```json
-{
-  "mcpServers": {
-    "vikunja": {
-      "command": "node",
-      "args": ["/path/to/vikunja-mcp/dist/index.js"],
-      "env": {
-        "VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
-        "VIKUNJA_API_TOKEN": "your-api-token"
-      }
-    }
-  }
-}
-```
+Or install globally (`npm install -g vikunja-mcp-ng`) and use `"command": "vikunja-mcp-ng"` with no args.
 
 ### Docker
 
-Images are published to GHCR on every release (also tagged `X.Y.Z` and `X.Y.Z-vikunja<A.B.C>` for Vikunja compatibility):
+Multi-architecture images (`linux/amd64` + `linux/arm64`) are published to GHCR on every release, with `X.Y.Z`, `latest`, and `X.Y.Z-vikunja<A.B.C>` compatibility tags:
 
 ```bash
 docker pull ghcr.io/netadvanced/vikunja-mcp-ng:latest
@@ -94,7 +58,7 @@ docker pull ghcr.io/netadvanced/vikunja-mcp-ng:latest
         "ghcr.io/netadvanced/vikunja-mcp-ng:latest"
       ],
       "env": {
-        "VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
+        "VIKUNJA_URL": "https://your-vikunja-instance.com",
         "VIKUNJA_API_TOKEN": "your-api-token"
       }
     }
@@ -102,42 +66,61 @@ docker pull ghcr.io/netadvanced/vikunja-mcp-ng:latest
 }
 ```
 
-Using Docker Desktop's MCP Toolkit instead of a bare `docker run`? See [docs/DOCKER-DESKTOP-MCP.md](docs/DOCKER-DESKTOP-MCP.md) for the tested, step-by-step path.
+Using Docker Desktop's MCP Toolkit rather than a bare `docker run`? There's a tested, step-by-step path in the [Docker Desktop guide](https://github.com/netadvanced/vikunja-mcp-ng/blob/main/docs/DOCKER-DESKTOP-MCP.md).
+
+## What it looks like in use
+
+> **You:** "Move 'Fix login redirect bug' to In Review and show me the board."
+
+```typescript
+vikunja_tasks({ subcommand: "set-bucket", id: 342, bucketId: 43 })
+```
+
+`projectId`/`viewId` resolve from the task itself — no need to know which view is the Kanban one. The card slides from *Backlog* into *In Review*, instantly visible to anyone else watching the board.
 
-Full install options, JWT vs. API-token auth, module gating, and every environment variable live in the [Configuration guide](docs/CONFIGURATION.md).
+Setting up a whole board is one call too:
+
+```typescript
+vikunja_projects({
+  subcommand: "setup-kanban",
+  title: "Q3 Offsite",
+  columns: ["To Do", "Doing", "Done"],
+  tasks: [{ title: "Book venue", column: "To Do", priority: 4 }]
+})
+```
+
+Omit `columns` entirely and it becomes a plain "create a project with its tasks" call, touching no Kanban structure at all.
 
 ## Capabilities
 
 | Group | Tools | Covers |
 |---|---|---|
-| **Tasks** | `vikunja_tasks`, `vikunja_task_bulk`, `vikunja_task_assignees`, `vikunja_task_comments`, `vikunja_task_labels`, `vikunja_task_relations`, `vikunja_task_reminders` | CRUD, filtering, bulk ops, Kanban placement, subtasks, duplication, mark-read, comments, relations |
-| **Projects** | `vikunja_projects` | CRUD, hierarchy, views, Kanban buckets, one-call Kanban board setup (`setup-kanban`), sharing, duplication, opt-in backgrounds |
-| **Organize** | `vikunja_labels`, `vikunja_filters`, `vikunja_templates` | Labels, saved filters, reusable task templates |
+| **Tasks** | `vikunja_tasks`, `vikunja_task_bulk`, `vikunja_task_assignees`, `vikunja_task_comments`, `vikunja_task_labels`, `vikunja_task_relations`, `vikunja_task_reminders` | CRUD, filtering, bulk ops, Kanban placement, subtasks, duplication, comments, relations, reminders |
+| **Projects** | `vikunja_projects` | CRUD, hierarchy, views, Kanban buckets, one-call board setup (`setup-kanban`), sharing, duplication |
+| **Organize** | `vikunja_labels`, `vikunja_filters`, `vikunja_templates` | Labels (including attach-by-title), saved filters, reusable task templates |
 | **Collaborate** | `vikunja_teams`, `vikunja_users`\*, `vikunja_notifications`, `vikunja_subscriptions`, `vikunja_reactions` | Team membership, user search, avatar settings, notifications, watch/react |
-| **Automate & move data** | `vikunja_webhooks`, `vikunja_batch_import`, `vikunja_export_project`\* | Webhooks (per-project and account-wide), CSV/JSON import, project export |
+| **Automate & move data** | `vikunja_webhooks`, `vikunja_batch_import`, `vikunja_export_project`\* | Webhooks, CSV/JSON import, project export |
 
-\* JWT authentication only. User data export also has request/status/download tools (`vikunja_request_user_export`, `vikunja_user_export_status`, `vikunja_download_user_export`), all JWT-only. (`vikunja_webhooks`' account-wide `scope: 'user'` is JWT-only too; its default `scope: 'project'` works with either auth type.)
+\* JWT authentication only, along with the three user-data-export tools.
 
-A session tool, `vikunja_auth` (connect / status / info / refresh / disconnect), rounds out the always-on surface. Four more tools — `vikunja_tokens`, `vikunja_caldav_tokens`, `vikunja_admin`, and `vikunja_user_deletion` — exist for API-token management, CalDAV-token management, instance administration, and self account deletion. All are **disabled by default**; an operator opts in explicitly (see Configuration). `vikunja_user_deletion` is the most sensitive of the four — it can delete the connected account — so read its [Configuration guide entry](docs/CONFIGURATION.md#known-modules) before enabling it. `vikunja_projects` also has three opt-in cosmetic subcommands (project backgrounds) behind a `backgrounds` module toggle, off by default for the opposite reason: low value, not danger.
+A session tool, `vikunja_auth` (connect / status / info / refresh / disconnect), rounds out the always-on surface. Four further tools — `vikunja_tokens`, `vikunja_caldav_tokens`, `vikunja_admin`, `vikunja_user_deletion` — are **disabled by default** and require an operator to opt in explicitly.
 
-Full subcommand-by-subcommand reference: [`docs/TOOLS.md`](docs/TOOLS.md).
+Full subcommand-by-subcommand reference: [`docs/TOOLS.md`](https://github.com/netadvanced/vikunja-mcp-ng/blob/main/docs/TOOLS.md).
 
 ## Safety by design
 
-Every entity is a toggle you can disable in config, `vikunja_admin`/`vikunja_tokens`/`vikunja_caldav_tokens`/`vikunja_user_deletion` ship off until an operator opts in (and `vikunja_admin`/`vikunja_caldav_tokens`/`vikunja_user_deletion` additionally require an active JWT session), and a global read-only mode can reject every write/destructive subcommand while reads keep working. Full details: [Configuration guide](docs/CONFIGURATION.md#module-gating).
+Every entity group is a toggle you can disable in config. The four sensitive tools ship off until an operator opts in — `vikunja_admin`, `vikunja_caldav_tokens`, and `vikunja_user_deletion` additionally require an active JWT session. A global **read-only mode** rejects every write and destructive subcommand while reads keep working.
+
+Details, plus auth, secrets handling, and rate limits: [Configuration guide](https://github.com/netadvanced/vikunja-mcp-ng/blob/main/docs/CONFIGURATION.md).
 
 ## Links
 
-- [Sample walkthroughs](docs/samples/) — real conversations paired with the tool calls and UI results behind them
-- [Full tool reference](docs/TOOLS.md) — every tool, subcommand, and argument
-- [Configuration guide](docs/CONFIGURATION.md) — auth, secrets, module gating, rate limits
-- [Roadmap](docs/ROADMAP.md) — where the project is headed and why
-- [Contributing / endpoint playbook](docs/ENDPOINT-PLAYBOOK.md) — conventions for adding new coverage
-- [Local test stack](docs/LOCAL-TESTING.md) — disposable Vikunja+Postgres via Docker for trying this out safely
-- [Agent battle-testing harness](docs/BATTLE-TESTING.md) — spawns a real AI agent against the tool surface and grades it on correctness and ergonomics (manual, costs real money — see the doc before running)
-- [Docker Desktop MCP Toolkit how-to](docs/DOCKER-DESKTOP-MCP.md) — registering this server with `docker mcp`
-- [Releasing](docs/RELEASING.md) — versioning policy and the release checklist · [CHANGELOG](CHANGELOG.md)
+- [Sample walkthroughs](https://github.com/netadvanced/vikunja-mcp-ng/tree/main/docs/samples) — real conversations paired with the tool calls and UI results behind them
+- [Full tool reference](https://github.com/netadvanced/vikunja-mcp-ng/blob/main/docs/TOOLS.md)
+- [Configuration guide](https://github.com/netadvanced/vikunja-mcp-ng/blob/main/docs/CONFIGURATION.md)
+- [Changelog](https://github.com/netadvanced/vikunja-mcp-ng/blob/main/CHANGELOG.md)
+- [Source, issues, and contributing](https://github.com/netadvanced/vikunja-mcp-ng)
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](https://github.com/netadvanced/vikunja-mcp-ng/blob/main/LICENSE).

package/dist/auth/CredentialSource.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Credential source: identity -> Vikunja credential.
+ *
+ * Spec: docs/OIDC-RESOURCE-SERVER.md §3(c)/§3(d). A Keycloak/OIDC access
+ * token authenticates a *person*, it is not itself a Vikunja credential —
+ * the server needs a lookup from the validated identity to a Vikunja `tk_`
+ * token. §3(c) specifies that lookup as an encrypted-JSON-file vault, but
+ * that is explicitly H2 scope (wave plan, H2-1/H2-3). H1's job is only to
+ * shape the seam so H2 plugs in without touching a single call site:
+ *
+ *  - `VikunjaCredentialSource` — the interface every call site programs
+ *    against. `getCredential` returns `null` (never throws) when an
+ *    identity has no linked credential; callers turn that into the
+ *    structured `AUTH_REQUIRED` "provision" error (`createOidcAuthRequiredError`
+ *    below), never a 500, and never anything that reveals whether some
+ *    *other* identity is provisioned.
+ *  - `StdioCredentialSource` — today's behaviour: one static credential
+ *    (from env/config, `src/index.ts`'s existing bootstrap), identity-
+ *    independent, because `stdio` mode is single-tenant. This is not a
+ *    stub — it's the permanent stdio-mode implementation.
+ *  - `OidcStubCredentialSource` — the H1 stand-in for the real vault.
+ *    Always returns `null`, so every `oidc-http` caller gets the
+ *    provisioning prompt until H2 lands `src/storage/vaultFileStore.ts` and
+ *    a vault-backed implementation of this same interface (H2-3). Retained
+ *    (not deleted) after H2 lands — still used by tests that want a
+ *    deterministic "nobody is ever provisioned" source without touching a
+ *    real vault file.
+ *  - `VaultCredentialSource` — H2's real implementation, a thin adapter over
+ *    `VaultFileStore` (`src/storage/vaultFileStore.ts`). Replaces
+ *    `OidcStubCredentialSource` in the production `oidc-http` wiring
+ *    (`src/transport/oidcHttpAuth.ts`'s `setupOidcHttpAuth`).
+ */
+import type { Identity } from '../context/requestContext';
+import { MCPError } from '../types/errors';
+import type { VaultFileStore } from '../storage/vaultFileStore';
+/** A Vikunja credential resolved for one identity. */
+export interface VikunjaCredential {
+    readonly apiUrl: string;
+    readonly apiToken: string;
+    readonly authType?: 'api-token' | 'jwt';
+}
+/**
+ * Resolves the Vikunja credential for a validated identity. Implementations
+ * MUST derive the credential from `identity` alone (or, for `stdio`,
+ * ignore it entirely in favour of the one process-wide credential) — never
+ * from anything caller-supplied outside the validated request context. That
+ * is what closes the "claim to be someone else" spoofing vector (§4,
+ * isolation-matrix row "Vault lookup can't be spoofed").
+ */
+export interface VikunjaCredentialSource {
+    getCredential(identity: Identity): VikunjaCredential | null;
+}
+/**
+ * `stdio` mode: the one static credential configured for the whole
+ * process (env `VIKUNJA_URL`/`VIKUNJA_API_TOKEN` today), identical for
+ * every call regardless of `identity`.
+ */
+export declare class StdioCredentialSource implements VikunjaCredentialSource {
+    private readonly credential;
+    constructor(credential: VikunjaCredential | null);
+    getCredential(_identity: Identity): VikunjaCredential | null;
+}
+/**
+ * `oidc-http` mode, H1 scope: no vault yet (H2-1/H2-3). Every identity is
+ * unprovisioned until a real, vault-backed `VikunjaCredentialSource`
+ * replaces this stub.
+ */
+export declare class OidcStubCredentialSource implements VikunjaCredentialSource {
+    getCredential(_identity: Identity): VikunjaCredential | null;
+}
+/**
+ * `oidc-http` mode, H2 scope: the real, vault-backed credential source.
+ * Delegates directly to a `VaultFileStore` (`src/storage/
+ * vaultFileStore.ts`) — `getCredential` is already synchronous and never
+ * throws there (a missing record and an undecryptable one both resolve to
+ * `null`), so this adapter adds no behaviour of its own beyond satisfying
+ * the interface type.
+ */
+export declare class VaultCredentialSource implements VikunjaCredentialSource {
+    private readonly vault;
+    constructor(vault: Pick<VaultFileStore, 'getCredential'>);
+    getCredential(identity: Identity): VikunjaCredential | null;
+}
+/**
+ * The structured `AUTH_REQUIRED` error for a validly-authenticated identity
+ * that has no linked Vikunja credential — exact shape from §3(c)'s
+ * "Missing-credential behaviour": never a 500, and the message masks the
+ * `sub` (never echoes it in full) and never leaks whether any other
+ * identity is provisioned.
+ */
+export declare function createOidcAuthRequiredError(identity: Identity): MCPError;
+//# sourceMappingURL=CredentialSource.d.ts.map

package/dist/auth/CredentialSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CredentialSource.d.ts","sourceRoot":"","sources":["../../src/auth/CredentialSource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAa,MAAM,iBAAiB,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE,sDAAsD;AACtD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CACzC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,iBAAiB,GAAG,IAAI,CAAC;CAC7D;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,uBAAuB;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,iBAAiB,GAAG,IAAI;IAMjE,aAAa,CAAC,SAAS,EAAE,QAAQ,GAAG,iBAAiB,GAAG,IAAI;CAG7D;AAED;;;;GAIG;AACH,qBAAa,wBAAyB,YAAW,uBAAuB;IACtE,aAAa,CAAC,SAAS,EAAE,QAAQ,GAAG,iBAAiB,GAAG,IAAI;CAG7D;AAED;;;;;;;GAOG;AACH,qBAAa,qBAAsB,YAAW,uBAAuB;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC;IAEzE,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,iBAAiB,GAAG,IAAI;CAG5D;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAOxE"}

package/dist/auth/CredentialSource.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Credential source: identity -> Vikunja credential.
+ *
+ * Spec: docs/OIDC-RESOURCE-SERVER.md §3(c)/§3(d). A Keycloak/OIDC access
+ * token authenticates a *person*, it is not itself a Vikunja credential —
+ * the server needs a lookup from the validated identity to a Vikunja `tk_`
+ * token. §3(c) specifies that lookup as an encrypted-JSON-file vault, but
+ * that is explicitly H2 scope (wave plan, H2-1/H2-3). H1's job is only to
+ * shape the seam so H2 plugs in without touching a single call site:
+ *
+ *  - `VikunjaCredentialSource` — the interface every call site programs
+ *    against. `getCredential` returns `null` (never throws) when an
+ *    identity has no linked credential; callers turn that into the
+ *    structured `AUTH_REQUIRED` "provision" error (`createOidcAuthRequiredError`
+ *    below), never a 500, and never anything that reveals whether some
+ *    *other* identity is provisioned.
+ *  - `StdioCredentialSource` — today's behaviour: one static credential
+ *    (from env/config, `src/index.ts`'s existing bootstrap), identity-
+ *    independent, because `stdio` mode is single-tenant. This is not a
+ *    stub — it's the permanent stdio-mode implementation.
+ *  - `OidcStubCredentialSource` — the H1 stand-in for the real vault.
+ *    Always returns `null`, so every `oidc-http` caller gets the
+ *    provisioning prompt until H2 lands `src/storage/vaultFileStore.ts` and
+ *    a vault-backed implementation of this same interface (H2-3). Retained
+ *    (not deleted) after H2 lands — still used by tests that want a
+ *    deterministic "nobody is ever provisioned" source without touching a
+ *    real vault file.
+ *  - `VaultCredentialSource` — H2's real implementation, a thin adapter over
+ *    `VaultFileStore` (`src/storage/vaultFileStore.ts`). Replaces
+ *    `OidcStubCredentialSource` in the production `oidc-http` wiring
+ *    (`src/transport/oidcHttpAuth.ts`'s `setupOidcHttpAuth`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VaultCredentialSource = exports.OidcStubCredentialSource = exports.StdioCredentialSource = void 0;
+exports.createOidcAuthRequiredError = createOidcAuthRequiredError;
+const errors_1 = require("../types/errors");
+const security_1 = require("../utils/security");
+/**
+ * `stdio` mode: the one static credential configured for the whole
+ * process (env `VIKUNJA_URL`/`VIKUNJA_API_TOKEN` today), identical for
+ * every call regardless of `identity`.
+ */
+class StdioCredentialSource {
+    credential;
+    constructor(credential) {
+        this.credential = credential;
+    }
+    // `identity` is intentionally unused — stdio is single-tenant, one
+    // credential for the one process, exactly as today. The parameter stays
+    // so this class satisfies the same interface as every oidc-mode source,
+    // and so no stdio call site is ever tempted to special-case identity.
+    getCredential(_identity) {
+        return this.credential;
+    }
+}
+exports.StdioCredentialSource = StdioCredentialSource;
+/**
+ * `oidc-http` mode, H1 scope: no vault yet (H2-1/H2-3). Every identity is
+ * unprovisioned until a real, vault-backed `VikunjaCredentialSource`
+ * replaces this stub.
+ */
+class OidcStubCredentialSource {
+    getCredential(_identity) {
+        return null;
+    }
+}
+exports.OidcStubCredentialSource = OidcStubCredentialSource;
+/**
+ * `oidc-http` mode, H2 scope: the real, vault-backed credential source.
+ * Delegates directly to a `VaultFileStore` (`src/storage/
+ * vaultFileStore.ts`) — `getCredential` is already synchronous and never
+ * throws there (a missing record and an undecryptable one both resolve to
+ * `null`), so this adapter adds no behaviour of its own beyond satisfying
+ * the interface type.
+ */
+class VaultCredentialSource {
+    vault;
+    constructor(vault) {
+        this.vault = vault;
+    }
+    getCredential(identity) {
+        return this.vault.getCredential(identity);
+    }
+}
+exports.VaultCredentialSource = VaultCredentialSource;
+/**
+ * The structured `AUTH_REQUIRED` error for a validly-authenticated identity
+ * that has no linked Vikunja credential — exact shape from §3(c)'s
+ * "Missing-credential behaviour": never a 500, and the message masks the
+ * `sub` (never echoes it in full) and never leaks whether any other
+ * identity is provisioned.
+ */
+function createOidcAuthRequiredError(identity) {
+    const maskedSub = (0, security_1.maskCredential)(identity.sub) || '[REDACTED]';
+    return new errors_1.MCPError(errors_1.ErrorCode.AUTH_REQUIRED, `You're authenticated as ${maskedSub} but haven't linked a Vikunja API token yet. ` +
+        `Run vikunja_auth provision with a token you create in Vikunja → Settings → API Tokens.`);
+}
+//# sourceMappingURL=CredentialSource.js.map

package/dist/auth/CredentialSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CredentialSource.js","sourceRoot":"","sources":["../../src/auth/CredentialSource.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;AA6EH,kEAOC;AAjFD,4CAAsD;AACtD,gDAAmD;AAsBnD;;;;GAIG;AACH,MAAa,qBAAqB;IACH;IAA7B,YAA6B,UAAoC;QAApC,eAAU,GAAV,UAAU,CAA0B;IAAG,CAAC;IAErE,mEAAmE;IACnE,wEAAwE;IACxE,wEAAwE;IACxE,sEAAsE;IACtE,aAAa,CAAC,SAAmB;QAC/B,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;CACF;AAVD,sDAUC;AAED;;;;GAIG;AACH,MAAa,wBAAwB;IACnC,aAAa,CAAC,SAAmB;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAJD,4DAIC;AAED;;;;;;;GAOG;AACH,MAAa,qBAAqB;IACH;IAA7B,YAA6B,KAA4C;QAA5C,UAAK,GAAL,KAAK,CAAuC;IAAG,CAAC;IAE7E,aAAa,CAAC,QAAkB;QAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC;CACF;AAND,sDAMC;AAED;;;;;;GAMG;AACH,SAAgB,2BAA2B,CAAC,QAAkB;IAC5D,MAAM,SAAS,GAAG,IAAA,yBAAc,EAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC;IAC/D,OAAO,IAAI,iBAAQ,CACjB,kBAAS,CAAC,aAAa,EACvB,2BAA2B,SAAS,+CAA+C;QACjF,wFAAwF,CAC3F,CAAC;AACJ,CAAC"}

package/dist/auth/index.d.ts

@@ -4,4 +4,7 @@
  */
 export { AuthManager } from './AuthManager';
 export { Permission, PermissionManager, TOOL_PERMISSIONS, type PermissionCheckResult, } from './permissions';
+export { createOidcJwtValidator, type OidcJwtValidator } from './oidc/jwtValidator';
+export { loadJose } from './oidc/joseLoader';
+export type { Identity, JoseDeps, JoseCreateRemoteJWKSet, JoseJwtVerify, OidcJwksCacheConfig, OidcJwtValidatorConfig, } from './oidc/types';
 //# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,qBAAqB,GAC3B,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,qBAAqB,GAC3B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,YAAY,EACV,QAAQ,EACR,QAAQ,EACR,sBAAsB,EACtB,aAAa,EACb,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,cAAc,CAAC"}

package/dist/auth/index.js

@@ -4,11 +4,15 @@
  * Eliminated over-engineered testing infrastructure
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TOOL_PERMISSIONS = exports.PermissionManager = exports.Permission = exports.AuthManager = void 0;
+exports.loadJose = exports.createOidcJwtValidator = exports.TOOL_PERMISSIONS = exports.PermissionManager = exports.Permission = exports.AuthManager = void 0;
 var AuthManager_1 = require("./AuthManager");
 Object.defineProperty(exports, "AuthManager", { enumerable: true, get: function () { return AuthManager_1.AuthManager; } });
 var permissions_1 = require("./permissions");
 Object.defineProperty(exports, "Permission", { enumerable: true, get: function () { return permissions_1.Permission; } });
 Object.defineProperty(exports, "PermissionManager", { enumerable: true, get: function () { return permissions_1.PermissionManager; } });
 Object.defineProperty(exports, "TOOL_PERMISSIONS", { enumerable: true, get: function () { return permissions_1.TOOL_PERMISSIONS; } });
+var jwtValidator_1 = require("./oidc/jwtValidator");
+Object.defineProperty(exports, "createOidcJwtValidator", { enumerable: true, get: function () { return jwtValidator_1.createOidcJwtValidator; } });
+var joseLoader_1 = require("./oidc/joseLoader");
+Object.defineProperty(exports, "loadJose", { enumerable: true, get: function () { return joseLoader_1.loadJose; } });
 //# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,6CAA4C;AAAnC,0GAAA,WAAW,OAAA;AACpB,6CAKuB;AAJrB,yGAAA,UAAU,OAAA;AACV,gHAAA,iBAAiB,OAAA;AACjB,+GAAA,gBAAgB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,6CAA4C;AAAnC,0GAAA,WAAW,OAAA;AACpB,6CAKuB;AAJrB,yGAAA,UAAU,OAAA;AACV,gHAAA,iBAAiB,OAAA;AACjB,+GAAA,gBAAgB,OAAA;AAGlB,oDAAoF;AAA3E,sHAAA,sBAAsB,OAAA;AAC/B,gDAA6C;AAApC,sGAAA,QAAQ,OAAA"}

package/dist/auth/oidc/joseLoader.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Loads the `jose` package for production use.
+ *
+ * `jose@6` ships ESM-only (no CommonJS build); this project compiles to
+ * CommonJS (see tsconfig.json's `module: "NodeNext"` with no `"type": "module"`
+ * in package.json). A dynamic `import()` is the interop path the Node.js docs
+ * themselves recommend for a CommonJS module consuming an ESM-only package,
+ * and it works unmodified on every Node 20+ runtime this project targets —
+ * unlike newer `require(esm)` semantics, it needs no engine-version caveats.
+ *
+ * This function is intentionally the *only* place that dynamic import lives.
+ * Jest's CommonJS-mode test runner cannot execute a genuine dynamic `import()`
+ * of a real ES module without globally enabling `--experimental-vm-modules`
+ * (which, in turn, requires re-plumbing the whole suite's module handling and
+ * was rejected as disproportionate for a single dependency — see the PR
+ * description). So {@link createOidcJwtValidator} takes its `jose` functions
+ * as an explicit, fully unit-testable dependency instead of importing them
+ * itself; tests inject `jose`'s own statically-imported exports (which do
+ * load fine under Jest, see tests/auth/oidc/jwtValidator.test.ts) and never
+ * exercise this function. Only real Node execution (and the manual/e2e OIDC
+ * lane) exercises this path, hence the coverage exclusion below.
+ */
+import type { JoseDeps } from './types';
+export declare function loadJose(): Promise<JoseDeps>;
+//# sourceMappingURL=joseLoader.d.ts.map

package/dist/auth/oidc/joseLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"joseLoader.d.ts","sourceRoot":"","sources":["../../../src/auth/oidc/joseLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAOxC,wBAAgB,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,CAK5C"}

package/dist/auth/oidc/joseLoader.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Loads the `jose` package for production use.
+ *
+ * `jose@6` ships ESM-only (no CommonJS build); this project compiles to
+ * CommonJS (see tsconfig.json's `module: "NodeNext"` with no `"type": "module"`
+ * in package.json). A dynamic `import()` is the interop path the Node.js docs
+ * themselves recommend for a CommonJS module consuming an ESM-only package,
+ * and it works unmodified on every Node 20+ runtime this project targets —
+ * unlike newer `require(esm)` semantics, it needs no engine-version caveats.
+ *
+ * This function is intentionally the *only* place that dynamic import lives.
+ * Jest's CommonJS-mode test runner cannot execute a genuine dynamic `import()`
+ * of a real ES module without globally enabling `--experimental-vm-modules`
+ * (which, in turn, requires re-plumbing the whole suite's module handling and
+ * was rejected as disproportionate for a single dependency — see the PR
+ * description). So {@link createOidcJwtValidator} takes its `jose` functions
+ * as an explicit, fully unit-testable dependency instead of importing them
+ * itself; tests inject `jose`'s own statically-imported exports (which do
+ * load fine under Jest, see tests/auth/oidc/jwtValidator.test.ts) and never
+ * exercise this function. Only real Node execution (and the manual/e2e OIDC
+ * lane) exercises this path, hence the coverage exclusion below.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadJose = loadJose;
+let cachedDeps;
+// See file header: only a genuine ESM dynamic import exercises this function;
+// Jest cannot run one without --experimental-vm-modules, so no test calls it.
+/* istanbul ignore next */
+function loadJose() {
+    if (!cachedDeps) {
+        cachedDeps = import('jose');
+    }
+    return cachedDeps;
+}
+//# sourceMappingURL=joseLoader.js.map

package/dist/auth/oidc/joseLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"joseLoader.js","sourceRoot":"","sources":["../../../src/auth/oidc/joseLoader.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;AASH,4BAKC;AAVD,IAAI,UAAyC,CAAC;AAE9C,8EAA8E;AAC9E,8EAA8E;AAC9E,0BAA0B;AAC1B,SAAgB,QAAQ;IACtB,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/auth/oidc/jwtValidator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * OIDC resource-server JWT validation middleware.
+ *
+ * Implements docs/OIDC-RESOURCE-SERVER.md §3(b)'s validation contract: strict
+ * issuer/audience checking, an explicit `alg` allowlist (default `['RS256']`,
+ * rejecting `none` and unexpected HMAC algorithms), bounded clock skew, and a
+ * generic 401/403 failure contract that never echoes token material back to
+ * the caller and never logs a token at any level.
+ *
+ * Deliberately transport-agnostic: {@link createOidcJwtValidator} returns a
+ * `validate(authorizationHeaderValue) => Promise<Identity>` function with no
+ * dependency on Node's `http`, the MCP SDK transport, or any request/response
+ * object — so an HTTP transport seam can call it directly, and unit tests
+ * need no HTTP server (see tests/auth/oidc/jwtValidator.test.ts).
+ */
+import type { Identity, JoseDeps, OidcJwtValidatorConfig } from './types';
+export interface OidcJwtValidator {
+    /**
+     * Validates an `Authorization` header value and returns the caller's
+     * identity on success.
+     *
+     * On any failure, throws an {@link MCPError} carrying the generic,
+     * safe-to-return-verbatim message plus `details.statusCode` (401 or 403)
+     * and `details.wwwAuthenticateError` (`'invalid_token'` or
+     * `'insufficient_scope'`) for the transport to build its HTTP response.
+     * The specific failure reason is logged at `warn` — the token itself is
+     * never included in that log line.
+     */
+    validate(authorizationHeader: string | null | undefined): Promise<Identity>;
+    /**
+     * Forces an immediate JWKS refetch, bypassing the cooldown window. Not
+     * required for normal operation — jose's remote JWKS resolver already
+     * refetches automatically when it sees an unrecognized `kid` — but useful
+     * for an operator reacting to a known key rotation, or for tests.
+     */
+    reloadJwks(): Promise<void>;
+}
+/**
+ * Builds an {@link OidcJwtValidator} bound to the given config.
+ *
+ * `deps` is required rather than defaulted to a live `import('jose')` so this
+ * function stays synchronous and trivially unit-testable; see
+ * src/auth/oidc/joseLoader.ts for how production code obtains `deps`.
+ */
+export declare function createOidcJwtValidator(config: OidcJwtValidatorConfig, deps: JoseDeps): OidcJwtValidator;
+//# sourceMappingURL=jwtValidator.d.ts.map

package/dist/auth/oidc/jwtValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwtValidator.d.ts","sourceRoot":"","sources":["../../../src/auth/oidc/jwtValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAuB,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAU/F,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5E;;;;;OAKG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,sBAAsB,EAC9B,IAAI,EAAE,QAAQ,GACb,gBAAgB,CA+DlB"}