Merge pull request 'fix: serve RFC 9728 path-suffixed metadata, document connector redirect URIs' (#26 ) from fix/oauth-redirect-uris-and-rfc9728-discovery into main

docs: correct the segment-decoding comment on the catch-all route
Review caught the stated invariant being false. Next splits the matched suffix on literal `/` before decoding each piece, so a segment can be empty (`api//mcp`) and a single segment can carry a decoded slash (`api%2Fmcp`). Neither reaches the allowlist — both fail closed — but the comment claimed an invariant the router does not provide. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-16 23:33:06 +00:00 · 2026-09-16 16:32:46 -07:00 · 2026-09-16 16:11:08 -07:00 · 2026-09-16 16:08:06 -07:00 · 2026-08-13 02:40:44 +00:00 · 2026-08-12 19:40:31 -07:00
21 changed files with 2016 additions and 131 deletions
@@ -1,4 +1,4 @@
-# shared-memory
+# <img src="docs/assets/lockup.svg" alt="shared-memory" width="283">
 A self-hosted MCP server that gives Claude Code sessions a **shared, persistent
 memory** plus a **reusable snippet library**, behind your own OIDC login.
@@ -37,8 +37,10 @@ Workspace. Anything that publishes a `/.well-known/openid-configuration`.
 The same container serves both the MCP endpoint (under `/api/mcp`) and the
 Web UI. Users authenticate via your OIDC provider with pre-registered
-confidential clients. Identity is keyed on the OIDC `sub` + `iss` so
+confidential clients. Identity is keyed on the OIDC `iss` + `sub` so memories
-memories are scoped per user.
+are scoped per user — except on Microsoft Entra ID, where `sub` is pairwise
 (a different value per app registration for the same person) and `oid` is
 used instead. See [`docs/oidc-entra-id.md`](docs/oidc-entra-id.md) §7.
 ---
@@ -249,6 +251,13 @@ shape is the same on any OIDC provider; the UI labels differ:
 | Redirect URI list | Provider's "Redirect URIs / Origins" | App's "Redirect URIs" | Client's "Valid Redirect URIs" |
 | Audience claim | Scope mapping or property mapping | "Expose an API" + scope | Client scope with audience mapper |
 > **Using Microsoft Entra ID?** The differences are large enough that Entra
 > gets its own walkthrough: **[docs/oidc-entra-id.md](docs/oidc-entra-id.md)**.
 > It follows the same A/B structure as the steps below, and covers the
 > Entra-specific traps — access token version, tenant-specific authority,
 > `aud` vs. scope URI, redirect-URI platform type, group GUIDs and overage —
 > which otherwise surface only as opaque 401s.
 ### A. Web UI provider
 **Admin → Applications → Providers → Create → OAuth2/OpenID Provider**
@@ -289,12 +298,75 @@ tokens carry `aud: shared-memory` (or whatever value you chose).
  or `Confidential` if you prefer to issue a secret to each Claude Code
  install — both work. Phase 1 expects Public.
 - **Client ID:** auto-generated → copy to `.env` as `OIDC_CLIENT_ID_MCP`
- **Redirect URIs:** Claude Code prints the exact value when it first
+- **Redirect URIs:** more than one, and which ones depends on how people
-  connects to the MCP endpoint. Paste it into Authentik then.
+  reach the server — see **Which redirect URIs to register** below.
 - **Scopes:** `openid`, `profile`, `email` (plus `offline_access` — see
  **Keeping sessions alive** below)
 - **Signing Key:** same cert as the Web provider
 #### Which redirect URIs to register
 The MCP provider is reached by clients of two different shapes — one running on
 your machine, one running inside claude.ai — and they come back from the IdP at
 **different** redirect URIs. Register every one you intend to use, before the
 first connection attempt:
 - **Claude Code CLI, including this repo's plugin** — the CLI catches the
  callback on a loopback listener, so the URI is
  `http://localhost:<port>/callback`, where `<port>` is whatever
  `--callback-port` (or the plugin's `callbackPort`) is set to. Set the entry's
  matching mode to **Regex** so any port works without re-registering:
  ```
  ^http://(127\.0\.0\.1|localhost):\d+(/.*)?$
  ```
  **The port is not optional.** Authentik rejects a portless
  `http://localhost/callback`, so an entry copied from the Entra ID walkthrough
  — where the port component is ignored on purpose, see
  [docs/oidc-entra-id.md](docs/oidc-entra-id.md) — matches nothing the CLI ever
  sends.
 - **A claude.ai custom connector** — the server added through claude.ai's web
  UI rather than installed locally. claude.ai brokers the OAuth flow, so the
  browser never returns to your machine and the loopback entries above are
  irrelevant. Register the exact string:
  ```
  https://claude.ai/api/mcp/auth_callback
  ```
 - **The manual-paste fallback** (*C. Manual-paste fallback* below) — that
  callback is hosted by *this* server, not by the client:
  ```
  https://memory.example.com/auth/cli-callback
  ```
 > **A missing entry shows up as Authentik's "Redirect URI Error" page** — *"The
 > request fails due to a missing, invalid, or mismatching redirection URI
 > (redirect_uri)"* — served **after** the client sends you to Authentik but
 > **before** any login or consent screen. Nothing in the client says which URI
 > was rejected, so it reads as "the connector is broken" when the provider
 > simply has no entry matching what was sent. Adding the server as a claude.ai
 > connector without the `https://claude.ai/api/mcp/auth_callback` entry is the
 > common way to land here.
 >
 > **Nothing registers these for you — on a FOSS instance.** Authentik *does*
 > implement RFC 7591 Dynamic Client Registration
 > ([goauthentik/authentik#8751](https://github.com/goauthentik/authentik/issues/8751),
 > closed July 2026), but gated behind an **enterprise** licence; a maintainer
 > has since said it will move to the open-source build. Until it does, a FOSS
 > instance advertises no `registration_endpoint` at all. Check yours:
 >
 > ```
 > curl -s "${OIDC_ISSUER_MCP}.well-known/openid-configuration" | jq .registration_endpoint
 > ```
 >
 > `null` means no client — CLI or claude.ai — can add its own redirect URI, so
 > every URI above is typed into the provider by hand. (Same gap as **Why no
 > zero-config plugin yet** below.)
 #### Keeping sessions alive (`offline_access`)
 Without this, a connected MCP client gets an access token and **no refresh
@@ -404,6 +476,13 @@ prompt, never reaching the app.
 Three paths, in order of preference:
 > **Connecting from claude.ai instead?** A server added there as a *custom
 > connector* needs nothing on your machine, but its OAuth callback is
 > `https://claude.ai/api/mcp/auth_callback`, not a loopback URI. Register it on
 > the MCP provider first (**Which redirect URIs to register** above) or the
 > connector stops at Authentik's *Redirect URI Error* page before you ever see
 > a login prompt.
 ### A. Plugin (recommended — one command, no flags to remember)
 This repo doubles as a Claude Code plugin marketplace. `plugin/.mcp.json` ships a
@@ -492,8 +571,8 @@ What happens:
 `--callback-port` is required because your IdP only accepts pre-registered
 redirect URIs. Pick any free port; just make sure the matching URI is in
 your MCP client's **Redirect URIs** list. Authentik users with the regex
-pattern from the setup step (`^http://(127\.0\.0\.1|localhost):\d+/.*$`)
+entry from the setup step (`^http://(127\.0\.0\.1|localhost):\d+(/.*)?$`) can
-can use any port without re-registering.
+use any port without re-registering.
 ### C. Manual-paste fallback (when loopback isn't reachable)
@@ -716,6 +795,14 @@ reopen a closed question.
  scope mapping; on EntraID it's the API "Application ID URI"; on Keycloak
  it's a client-scope audience mapper. See **Setting the `aud` claim** above
  for the Authentik recipe; other IdPs need the equivalent in their UI.
 - **Authentik shows "Redirect URI Error — The request fails due to a missing,
  invalid, or mismatching redirection URI (redirect_uri)"** — the redirect URI
  the client sent is not registered on the `shared-memory-mcp` provider. From a
  claude.ai custom connector the missing entry is
  `https://claude.ai/api/mcp/auth_callback`; from the CLI it's the loopback URI
  for your `--callback-port`, and a portless `http://localhost/callback` entry
  will not match it. Authentik has no Dynamic Client Registration, so no client
  can add the URI itself — see **Which redirect URIs to register** above.
 - **Auth.js callback fails with `OAUTH_CALLBACK_ERROR`** — your `PUBLIC_URL`
  doesn't match the redirect URI your IdP is configured with. They must be
  exactly equal, scheme and trailing slash included.
@@ -0,0 +1,86 @@
 import { afterEach, describe, expect, test, vi } from "vitest";
 /**
 * RFC 9728 §3.1 puts the metadata for `https://host/api/mcp` at
 * `https://host/.well-known/oauth-protected-resource/api/mcp`. MCP clients
 * that derive that URL from the endpoint URL — instead of following the
 * `resource_metadata` parameter on our 401 — used to receive the Next.js 404
 * HTML page here, so discovery died on a JSON parse error.
 *
 * Two things therefore have to hold, and both are easy to break silently:
 * the document must name the SUFFIXED resource (§3.3 has the client reject a
 * document whose `resource` isn't the identifier it asked about), and it must
 * stay byte-for-byte in step with the root document's scope list, because a
 * scope missing from whichever document a given client reads is a scope that
 * client will never request.
 */
 type Metadata = { resource: string; scopes_supported: string[] };
 async function fetchSuffixed(
  segments: string[],
 ): Promise<{ status: number; body: Metadata }> {
  vi.resetModules();
  const { GET } = await import(
    "@/app/.well-known/oauth-protected-resource/[...path]/route"
  );
  const res = await GET(new Request("http://localhost/ignored"), {
    params: Promise.resolve({ path: segments }),
  });
  return { status: res.status, body: (await res.json()) as Metadata };
 }
 async function fetchRoot(): Promise<Metadata> {
  vi.resetModules();
  const { GET } = await import("@/app/.well-known/oauth-protected-resource/route");
  return (await GET().json()) as Metadata;
 }
 afterEach(() => {
  delete process.env.OIDC_OFFLINE_ACCESS;
  delete process.env.OIDC_AUDIENCE_SCOPE;
 });
 describe("path-suffixed oauth-protected-resource metadata", () => {
  test("serves the MCP endpoint's document with the suffixed resource identifier", async () => {
    const { status, body } = await fetchSuffixed(["api", "mcp"]);
    expect(status).toBe(200);
    // §3.3: a strict client compares this against the identifier it asked
    // about, so the bare origin would get the whole document rejected.
    expect(body.resource).toBe("http://localhost:3000/api/mcp");
  });
  test("404s for a path this app does not serve, rather than advertising it", async () => {
    // The allowlist exists so we never claim that arbitrary paths are
    // OAuth-protected resources of this deployment.
    const { status } = await fetchSuffixed(["api", "not-mcp"]);
    expect(status).toBe(404);
  });
  test("advertises exactly the scopes the root document does", async () => {
    // Regression guard against the two documents drifting apart: the audience
    // scope is what makes `aud` appear on the token at all, and a client that
    // discovered us through the suffixed URL would never request a scope that
    // only the root document lists.
    process.env.OIDC_OFFLINE_ACCESS = "true";
    const root = await fetchRoot();
    const { body: suffixed } = await fetchSuffixed(["api", "mcp"]);
    expect(suffixed.scopes_supported).toEqual(root.scopes_supported);
    expect(suffixed.scopes_supported).toContain("aud-test-audience");
    expect(suffixed.scopes_supported).toContain("offline_access");
  });
  test("honours an explicit audience scope name, like the root document", async () => {
    process.env.OIDC_AUDIENCE_SCOPE = "custom-aud-scope";
    const root = await fetchRoot();
    const { body: suffixed } = await fetchSuffixed(["api", "mcp"]);
    expect(suffixed.scopes_supported).toContain("custom-aud-scope");
    expect(suffixed.scopes_supported).toEqual(root.scopes_supported);
  });
 });
@@ -0,0 +1,63 @@
 import { NextResponse } from "next/server";
 import { buildResourceMetadata, publicOrigin } from "@/lib/auth/resource-metadata";
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 /**
 * Resource paths this deployment will publish metadata for.
 *
 * An allowlist rather than a wildcard, for two reasons. RFC 9728 §3.1 maps a
 * metadata URL to one specific protected resource, so answering for arbitrary
 * paths would advertise resources this app does not serve — a client could
 * "discover" `https://host/anything` as an OAuth-protected resource and be
 * told, wrongly, that tokens for it are obtainable from our IdP. And every
 * path that answers is surface: a wildcard turns this into an open reflector
 * that echoes attacker-chosen path segments back inside a JSON document.
 *
 * `api/mcp` is the only MCP endpoint here (app/api/mcp/route.ts). Add an
 * entry when a second one ships — not before.
 */
 const METADATA_RESOURCE_PATHS: ReadonlySet<string> = new Set(["api/mcp"]);
 /**
 * RFC 9728 §3.1 — path-suffixed protected resource metadata.
 *
 * For a resource identified by `https://host/api/mcp`, the spec puts its
 * metadata at `https://host/.well-known/oauth-protected-resource/api/mcp`:
 * the resource's path is appended to the well-known path. Clients that derive
 * the metadata URL from the MCP endpoint URL — rather than reading
 * `resource_metadata` off our 401's `WWW-Authenticate` header — probe that URL
 * first, and before this route existed they got Next.js's 404 HTML page, which
 * fails discovery with a JSON parse error rather than anything diagnosable.
 *
 * The document is identical to the root one except for `resource`, which must
 * name the suffixed identifier: §3.3 requires the client to check that the
 * returned `resource` equals the identifier it asked about, so echoing the
 * bare origin here would make a strict client reject the document outright.
 */
 export async function GET(
  _req: Request,
  ctx: { params: Promise<{ path: string[] }> },
 ): Promise<NextResponse> {
  const { path } = await ctx.params;
  // Next splits the matched suffix on literal `/` and only then decodes each
  // piece, so a segment can be empty (`api//mcp` -> ["api","","mcp"]) and a
  // single segment can itself contain a decoded slash (`api%2Fmcp` -> one
  // element, "api/mcp"). Join and compare on the same normalized form the
  // allowlist is written in, and let anything else fail closed.
  const resourcePath = path.join("/");
  if (!METADATA_RESOURCE_PATHS.has(resourcePath)) {
    // JSON, not the HTML 404 page, so a client that probes a wrong path gets
    // a parseable answer instead of the failure mode this route exists to fix.
    return NextResponse.json(
      { error: "not_found", error_description: "no such protected resource" },
      { status: 404 },
    );
  }
  return NextResponse.json(
    buildResourceMetadata(`${publicOrigin()}/${resourcePath}`),
  );
 }
@@ -1,6 +1,5 @@
 import { NextResponse } from "next/server";
-import { env } from "@/lib/env";
+import { buildResourceMetadata, publicOrigin } from "@/lib/auth/resource-metadata";
 import { mcpIssuer } from "@/lib/auth/jwt";
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
@@ -10,36 +9,12 @@ export const dynamic = "force-dynamic";
 *
 * MCP clients discover the authorization server (Authentik) via this
 * endpoint after receiving a 401 with `WWW-Authenticate: resource_metadata=...`.
 *
 * This is the root form of the document, describing the deployment origin as
 * the protected resource. Clients that derive the metadata URL from the MCP
 * endpoint URL instead of following the header land on the path-suffixed form
 * (§3.1) served by the sibling `[...path]` route.
 */
 export function GET() {
-  const resource = env().PUBLIC_URL.replace(/\/$/, "");
+  return NextResponse.json(buildResourceMetadata(publicOrigin()));
  // The audience scope MUST be advertised. Authentik only evaluates a scope
  // mapping when the client requests that scope by name, and the client only
  // learns scope names from this document. Omit it and every access token
  // arrives without `aud`, which jwt.ts rejects as "claim invalid: aud".
  const audienceScope =
    env().OIDC_AUDIENCE_SCOPE ?? `aud-${env().OIDC_AUDIENCE}`;
  // Same mechanism as the audience scope, different consequence: a client
  // only requests `offline_access` if it sees the name here, and without
  // that request the IdP returns no refresh token — so the client cannot
  // renew and the user gets kicked back to an interactive login whenever
  // the access token expires.
  //
  // Opt-in, because the IdP needs a matching scope mapping; advertising one
  // it doesn't offer can fail the whole authorization request.
  const scopes = ["openid", "profile", "email", audienceScope];
  if (env().OIDC_OFFLINE_ACCESS) scopes.push("offline_access");
  return NextResponse.json({
    resource,
    // The MCP application's issuer, which is not necessarily the Web UI's —
    // see mcpIssuer(). Advertising the wrong one sends clients to a discovery
    // document whose tokens this endpoint will then reject on `iss`.
    authorization_servers: [mcpIssuer()],  // as configured, slash and all
    scopes_supported: scopes,
    bearer_methods_supported: ["header"],
    resource_documentation: `${resource}/`,
  });
 }
@@ -5,12 +5,17 @@
    Three retrieval signals - vector, full-text, tags - converging on a single
    memory. The direct match runs straight through at full strength; the two
    ranked neighbours fall back, which is the fusion the search actually does.
-    Opacity is held equal on the outer pair so the mark stays balanced at 16px.
+
    Every proportion here is set by the 16px browser-tab case. The outer pair
    is held at .7 (not .55) because below that it rasterises away entirely,
    the strokes stop at x=30 so the gap to the node doesn't fill in, and the
    node is r=8.5 so it still reads as a disc. Geometry is identical to
    public/logo.svg; only the palette differs.
  -->
  <g fill="none" stroke-linecap="round" stroke-width="7">
-    <path d="M13 15C25 15 26 32 35 32" stroke="#0092fd" opacity=".55"/>
+    <path d="M12 16C24 16 25 32 30 32" stroke="#0092fd" opacity=".7"/>
-    <path d="M13 32H35" stroke="#49a9ff"/>
+    <path d="M12 32H30" stroke="#49a9ff"/>
-    <path d="M13 49C25 49 26 32 35 32" stroke="#0092fd" opacity=".55"/>
+    <path d="M12 48C24 48 25 32 30 32" stroke="#0092fd" opacity=".7"/>
  </g>
-  <circle cx="45" cy="32" r="7.5" fill="#76c0ff"/>
+  <circle cx="46" cy="32" r="8.5" fill="#76c0ff"/>
 </svg>
@@ -1,7 +1,6 @@
 import NextAuth from "next-auth";
 import { env } from "@/lib/env";
-import { db } from "@/lib/db/client";
+import { oidClaim, resolveUserId } from "@/lib/auth/identity";
 import { users } from "@/lib/db/schema";
 import { syncUserGroupsFromClaim } from "@/lib/auth/sync-groups";
 /**
@@ -41,27 +40,18 @@ export const { auth, handlers, signIn, signOut } = NextAuth({
        const iss = (profile.iss as string | undefined) ?? env().OIDC_ISSUER;
        if (!sub) throw new Error("OIDC profile missing `sub` claim");
-        const row = await db
+        // Shared with the MCP path (lib/mcp/context.ts). On EntraID the `oid`
-          .insert(users)
+        // claim is what keeps the two surfaces resolving to one account —
-          .values({
+        // `sub` differs per app registration there. See lib/auth/identity.ts.
-            oidcSub: sub,
+        const userId = await resolveUserId({
-            oidcIss: iss,
+          iss,
-            email: profile.email ?? null,
+          sub,
-            name: profile.name ?? null,
+          oid: oidClaim(profile),
-            picture: (profile.picture as string | undefined) ?? null,
+          email: profile.email ?? null,
-          })
+          name: profile.name ?? null,
-          .onConflictDoUpdate({
+          picture: (profile.picture as string | undefined) ?? null,
-            target: [users.oidcIss, users.oidcSub],
+        });
            set: {
              email: profile.email ?? null,
              name: profile.name ?? null,
              picture: (profile.picture as string | undefined) ?? null,
              lastSeenAt: new Date(),
            },
          })
          .returning({ id: users.id });
        const userId = row[0]?.id;
        token.userId = userId;
        token.sub = sub;
        token.iss = iss;
@@ -71,10 +61,15 @@ export const { auth, handlers, signIn, signOut } = NextAuth({
        // wipes the user's existing memberships, which is the conservative
        // choice (don't keep stale grants alive if the IdP stopped
        // asserting them).
        //
        // The whole profile goes in, not just `profile.groups`: an absent
        // claim means one thing on its own and something else entirely next
        // to EntraID's overage markers, and only the second case must abort.
        // A GroupsOverageError thrown here fails the sign-in, which is the
        // intent — it leaves the user's existing memberships untouched
        // instead of silently deleting them.
        if (userId) {
-          // `profile.groups` is untyped at the next-auth boundary — coerce.
+          await syncUserGroupsFromClaim(userId, iss, profile);
          const claimGroups = (profile as { groups?: unknown }).groups;
          await syncUserGroupsFromClaim(userId, iss, claimGroups);
        }
      }
      return token;
@@ -0,0 +1,29 @@
 -- EntraID identity: key users on `oid` when the IdP emits it.
 --
 -- EntraID's `sub` is a PAIRWISE identifier — derived from the token recipient,
 -- so the Web UI app registration and the MCP app registration hand out
 -- different `sub` values for the same person. Both `auth.ts` and
 -- `lib/mcp/context.ts` upsert on (oidc_iss, oidc_sub), so on EntraID one human
 -- resolves to two rows: they sign into the Web UI, connect an MCP client, and
 -- land in an empty account with their memories nowhere to be seen. Nothing
 -- errors, which is what makes it dangerous.
 --
 -- `oid` is the user's directory object id, which Microsoft documents as
 -- constant for a user across every application in a tenant. Recording it gives
 -- us a key that holds across both surfaces.
 --
 -- Nullable on purpose: Authentik, Keycloak and Okta emit no `oid`, and there
 -- `sub` is already application-independent. Those deployments keep using
 -- (oidc_iss, oidc_sub) and are untouched by this migration.
 ALTER TABLE "users" ADD COLUMN "oidc_oid" text;
 -- Partial index. Every non-EntraID row holds NULL here; a plain unique index
 -- would treat those as colliding and permit exactly one such user.
 CREATE UNIQUE INDEX "users_iss_oid_uq"
  ON "users" ("oidc_iss", "oidc_oid")
  WHERE "oidc_oid" IS NOT NULL;
 -- No backfill. `oid` is only knowable from a token, so existing rows adopt
 -- theirs on the owner's next sign-in (see `adoptLegacyRow` in
 -- lib/auth/identity.ts). Backfilling would mean guessing.
@@ -0,0 +1,165 @@
 import { afterAll, beforeEach, describe, expect, test } from "vitest";
 /**
 * Identity resolution across the two surfaces.
 *
 * The bug these guard against is silent: on EntraID the Web UI and the MCP
 * endpoint see different `sub` values for the same person, both code paths
 * UPSERT rather than fail, and the result is two accounts — the user signs in,
 * connects an MCP client, and finds their memories gone. Nothing errors, so
 * only a test that asserts "same person ⇒ same row id" catches it.
 */
 const { db, pg } = await import("@/lib/db/client");
 const { users } = await import("@/lib/db/schema");
 const { resolveUserId, oidClaim } = await import("@/lib/auth/identity");
 const { eq } = await import("drizzle-orm");
 /** `noUncheckedIndexedAccess` is on; narrow once rather than at every use. */
 function first<T>(rows: T[]): T {
  const row = rows[0];
  if (!row) throw new Error("expected at least one row");
  return row;
 }
 const ISS = "https://login.microsoftonline.com/test-tenant/v2.0";
 /** Distinct `sub` values, as EntraID's pairwise identifiers would be. */
 const WEB_SUB = "pairwise-sub-for-web-registration";
 const MCP_SUB = "pairwise-sub-for-mcp-registration";
 const OID = "00000000-1111-2222-3333-444444444444";
 function claims(overrides: Record<string, unknown> = {}) {
  return {
    iss: ISS,
    sub: WEB_SUB,
    oid: OID,
    email: "person@example.com",
    name: "Person",
    picture: null,
    ...overrides,
  } as Parameters<typeof resolveUserId>[0];
 }
 beforeEach(async () => {
  await db.delete(users).where(eq(users.oidcIss, ISS));
 });
 afterAll(async () => {
  await db.delete(users).where(eq(users.oidcIss, ISS));
  await pg.end();
 });
 describe("oidClaim", () => {
  test("reads a string oid", () => {
    expect(oidClaim({ oid: OID })).toBe(OID);
  });
  test("is null when absent, blank, or not a string", () => {
    expect(oidClaim({})).toBeNull();
    expect(oidClaim({ oid: "   " })).toBeNull();
    expect(oidClaim({ oid: 42 })).toBeNull();
    expect(oidClaim(null)).toBeNull();
  });
 });
 describe("resolveUserId with an oid (EntraID)", () => {
  test("both surfaces resolve to ONE row despite different subs", async () => {
    const fromWeb = await resolveUserId(claims({ sub: WEB_SUB }));
    const fromMcp = await resolveUserId(claims({ sub: MCP_SUB }));
    expect(fromMcp).toBe(fromWeb);
    const rows = await db.select().from(users).where(eq(users.oidcIss, ISS));
    expect(rows).toHaveLength(1);
  });
  test("does not rewrite oidc_sub once the row exists", async () => {
    await resolveUserId(claims({ sub: WEB_SUB }));
    await resolveUserId(claims({ sub: MCP_SUB }));
    const rows = await db.select().from(users).where(eq(users.oidcIss, ISS));
    // Whichever arrived first stays put; flip-flopping it on every request
    // could collide with the (iss, sub) unique index.
    expect(first(rows).oidcSub).toBe(WEB_SUB);
    expect(first(rows).oidcOid).toBe(OID);
  });
  test("adopts a pre-migration row instead of stranding it", async () => {
    // A deployment that signed this person in before 0005 ran: correct sub,
    // no oid recorded.
    const legacy = first(
      await db
        .insert(users)
        .values({ oidcIss: ISS, oidcSub: WEB_SUB, email: "old@example.com" })
        .returning({ id: users.id }),
    );
    const resolved = await resolveUserId(claims({ sub: WEB_SUB }));
    expect(resolved).toBe(legacy.id);
    const rows = await db.select().from(users).where(eq(users.oidcIss, ISS));
    expect(rows).toHaveLength(1);
    expect(first(rows).oidcOid).toBe(OID);
  });
  test("refreshes profile fields on an existing row", async () => {
    await resolveUserId(claims({ name: "Old Name" }));
    await resolveUserId(claims({ sub: MCP_SUB, name: "New Name" }));
    const rows = await db.select().from(users).where(eq(users.oidcIss, ISS));
    expect(first(rows).name).toBe("New Name");
  });
  test("concurrent first-contact from both surfaces yields one row", async () => {
    const [a, b] = await Promise.all([
      resolveUserId(claims({ sub: WEB_SUB })),
      resolveUserId(claims({ sub: MCP_SUB })),
    ]);
    expect(a).toBe(b);
    const rows = await db.select().from(users).where(eq(users.oidcIss, ISS));
    expect(rows).toHaveLength(1);
  });
  test("different people in one tenant stay separate", async () => {
    const one = await resolveUserId(claims());
    const two = await resolveUserId(
      claims({ sub: "other-sub", oid: "99999999-1111-2222-3333-444444444444" }),
    );
    expect(two).not.toBe(one);
    const rows = await db.select().from(users).where(eq(users.oidcIss, ISS));
    expect(rows).toHaveLength(2);
  });
 });
 describe("resolveUserId without an oid (Authentik and friends)", () => {
  test("keys on (iss, sub) exactly as before", async () => {
    const initial = await resolveUserId(claims({ oid: null }));
    const again = await resolveUserId(claims({ oid: null, name: "Renamed" }));
    expect(again).toBe(initial);
    const rows = await db.select().from(users).where(eq(users.oidcIss, ISS));
    expect(rows).toHaveLength(1);
    expect(first(rows).oidcOid).toBeNull();
    expect(first(rows).name).toBe("Renamed");
  });
  test("distinct subs are distinct people", async () => {
    await resolveUserId(claims({ oid: null, sub: "a" }));
    await resolveUserId(claims({ oid: null, sub: "b" }));
    const rows = await db.select().from(users).where(eq(users.oidcIss, ISS));
    expect(rows).toHaveLength(2);
  });
  test("several oid-less users coexist — the unique index is partial", async () => {
    // A non-partial unique index on (iss, oid) would allow exactly one NULL
    // pair and reject everyone after the first.
    for (const sub of ["u1", "u2", "u3"]) {
      await resolveUserId(claims({ oid: null, sub }));
    }
    const rows = await db.select().from(users).where(eq(users.oidcIss, ISS));
    expect(rows).toHaveLength(3);
  });
 });
@@ -0,0 +1,125 @@
 import { and, eq, isNull } from "drizzle-orm";
 import { db } from "@/lib/db/client";
 import { users } from "@/lib/db/schema";
 /**
 * Resolving OIDC claims to the internal `users.id`.
 *
 * Both surfaces come through here — the Web UI (`auth.ts`) and the MCP
 * endpoint (`lib/mcp/context.ts`) — and that is the point. They each used to
 * carry their own copy of this upsert, which is how the two drifted into
 * disagreeing about who a user is.
 *
 * ## Why `oid` exists here
 *
 * Authentik's `sub` is `user.uid`, identical across every provider, so
 * (iss, sub) identifies a person. EntraID's `sub` is PAIRWISE: Microsoft
 * derives it from the token recipient, so the Web UI app registration and the
 * MCP app registration emit different `sub` values for the same human. Keyed
 * on `sub`, that person gets two rows — they sign into the Web UI, connect
 * Claude Code, and find an empty account. Both paths upsert, so nothing
 * errors; the split is completely silent.
 *
 * `oid` is the directory object id, which Microsoft documents as constant for
 * a user across every application in a tenant. When it's present it wins.
 * When it's absent (Authentik, Keycloak, Okta) behaviour is exactly as before.
 */
 /** Extract a usable EntraID `oid` claim, or null on IdPs that don't emit one. */
 export function oidClaim(claims: unknown): string | null {
  const raw = (claims as { oid?: unknown } | null | undefined)?.oid;
  if (typeof raw !== "string") return null;
  const trimmed = raw.trim();
  return trimmed.length > 0 ? trimmed : null;
 }
 export interface IdentityInput {
  iss: string;
  sub: string;
  /** EntraID object id, or null. */
  oid: string | null;
  email: string | null;
  name: string | null;
  picture: string | null;
 }
 /** Postgres unique-violation. */
 function isUniqueViolation(err: unknown): boolean {
  return (err as { code?: unknown } | null)?.code === "23505";
 }
 /**
 * Resolve (creating if needed) the `users` row for a set of verified claims.
 *
 * Resolution order when `oid` is present:
 *
 *   1. a row already keyed on this `oid` — the steady state
 *   2. a pre-`oid` row for the same (iss, sub), which gets its `oid`
 *      backfilled in place. This is how a deployment that ran before the
 *      0005 migration keeps its accounts instead of stranding them.
 *   3. insert
 *
 * Without `oid` this collapses to the original (iss, sub) upsert.
 */
 export async function resolveUserId(input: IdentityInput): Promise<string> {
  const { iss, sub, oid, email, name, picture } = input;
  const profile = { email, name, picture, lastSeenAt: new Date() };
  if (oid) {
    // 1. Steady state.
    //
    // Deliberately does NOT touch `oidc_sub`. The stored value is whichever
    // app registration this person first arrived through; rewriting it on
    // every request would flip it back and forth between the Web and MCP
    // values and could collide with the (iss, sub) unique index.
    const byOid = await db
      .update(users)
      .set(profile)
      .where(and(eq(users.oidcIss, iss), eq(users.oidcOid, oid)))
      .returning({ id: users.id });
    if (byOid[0]) return byOid[0].id;
    // 2. Adopt a row created before `oid` was recorded.
    const adopted = await db
      .update(users)
      .set({ ...profile, oidcOid: oid })
      .where(
        and(eq(users.oidcIss, iss), eq(users.oidcSub, sub), isNull(users.oidcOid)),
      )
      .returning({ id: users.id });
    if (adopted[0]) return adopted[0].id;
  }
  // 3. Insert. The conflict target stays (iss, sub) because that is the index
  //    every row has; a concurrent writer racing us on `oid` instead is caught
  //    below.
  try {
    const inserted = await db
      .insert(users)
      .values({ oidcIss: iss, oidcSub: sub, oidcOid: oid, email, name, picture })
      .onConflictDoUpdate({
        target: [users.oidcIss, users.oidcSub],
        set: profile,
      })
      .returning({ id: users.id });
    if (inserted[0]) return inserted[0].id;
  } catch (err) {
    // Two requests for the same person arriving together through DIFFERENT
    // app registrations: same `oid`, different `sub`, so the (iss, sub)
    // conflict target doesn't fire and the partial (iss, oid) index rejects
    // the loser. Fall through and read the winner's row.
    if (!isUniqueViolation(err)) throw err;
  }
  const existing = await db
    .select({ id: users.id })
    .from(users)
    .where(
      oid
        ? and(eq(users.oidcIss, iss), eq(users.oidcOid, oid))
        : and(eq(users.oidcIss, iss), eq(users.oidcSub, sub)),
    )
    .limit(1);
  if (!existing[0]) throw new Error("user upsert failed and not found on re-read");
  return existing[0].id;
 }
@@ -0,0 +1,226 @@
 import { createServer, type Server } from "node:http";
 import { AddressInfo } from "node:net";
 import { SignJWT, exportJWK, generateKeyPair } from "jose";
 import type { JWK, KeyLike } from "jose";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 /**
 * The JWKS location is discovered, not assumed.
 *
 * `${issuer}/jwks/` used to be hardcoded here. That is an Authentik
 * convention — EntraID serves its keys at
 * `https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys`, so on
 * EntraID the hardcoded path 404s and NO MCP token can ever verify. These
 * tests pin the three behaviours that make the discovery path safe to ship:
 * discovery is honoured, failure degrades to the old path rather than to a
 * broken deployment, and it happens once rather than per request.
 *
 * A real loopback HTTP server is used rather than a `fetch` mock because jose
 * fetches the key set through `node:http` directly, not through global
 * `fetch` — a mocked `fetch` would silently never be consulted for the JWKS
 * request, and the assertion about *which* URL was used would prove nothing.
 */
 const TENANT = "11111111-2222-3333-4444-555555555555";
 const AUDIENCE = "99999999-8888-7777-6666-555555555555";
 /** Paths the fake IdP was asked for, in order. */
 let requested: string[] = [];
 /** Response the fake IdP gives for the discovery document. */
 let discoveryResponse: { status: number; body: string };
 let server: Server;
 let origin: string;
 let privateKey: KeyLike;
 let publicJwk: JWK;
 /** Authentik-shaped issuer: application-scoped path, trailing slash. */
 function authentikIssuer(): string {
  return `${origin}/application/o/shared-memory-mcp/`;
 }
 /** EntraID-shaped issuer: tenant-scoped, no trailing slash. */
 function entraIssuer(): string {
  return `${origin}/${TENANT}/v2.0`;
 }
 /** Where an EntraID discovery document points for keys. */
 function entraKeysPath(): string {
  return `/${TENANT}/discovery/v2.0/keys`;
 }
 beforeEach(async () => {
  const pair = await generateKeyPair("RS256");
  privateKey = pair.privateKey;
  publicJwk = { ...(await exportJWK(pair.publicKey)), kid: "test-key", alg: "RS256", use: "sig" };
  requested = [];
  server = createServer((req, res) => {
    requested.push(req.url ?? "");
    if (req.url?.endsWith("/.well-known/openid-configuration")) {
      res.writeHead(discoveryResponse.status, { "content-type": "application/json" });
      res.end(discoveryResponse.body);
      return;
    }
    // Every other path is treated as a key set endpoint. Which path the
    // request actually arrived on is the thing under test.
    res.writeHead(200, { "content-type": "application/json" });
    res.end(JSON.stringify({ keys: [publicJwk] }));
  });
  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
  origin = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
 });
 afterEach(async () => {
  // The key set is memoised on globalThis, which survives vi.resetModules().
  // Without clearing it, the second test in this file would silently reuse
  // the first test's resolution and assert nothing.
  delete (globalThis as Record<string, unknown>).__sharedMemoryJwks;
  delete (globalThis as Record<string, unknown>).__sharedMemoryJwksRetryAt;
  delete process.env.OIDC_ISSUER_MCP;
  delete process.env.OIDC_AUDIENCE;
  await new Promise<void>((resolve) => server.close(() => resolve()));
 });
 /**
 * Import `authenticateBearer` fresh so it observes the env vars this test set
 * (lib/env.ts caches its parse in a module singleton).
 */
 async function loadAuthenticateBearer() {
  vi.resetModules();
  const mod = await import("@/lib/auth/jwt");
  return mod.authenticateBearer;
 }
 async function signAccessToken(issuer: string): Promise<string> {
  return new SignJWT({ groups: ["memory-users"] })
    .setProtectedHeader({ alg: "RS256", kid: "test-key" })
    .setIssuer(issuer)
    .setAudience(AUDIENCE)
    .setSubject("user-object-id")
    .setIssuedAt()
    .setExpirationTime("5m")
    .sign(privateKey);
 }
 function discoveryPathsSeen(): string[] {
  return requested.filter((p) => p.endsWith("/.well-known/openid-configuration"));
 }
 describe("MCP JWKS resolution", () => {
  test("uses the jwks_uri from discovery, so EntraID's key endpoint is reached", async () => {
    process.env.OIDC_ISSUER_MCP = entraIssuer();
    process.env.OIDC_AUDIENCE = AUDIENCE;
    discoveryResponse = {
      status: 200,
      // Shape of https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration
      body: JSON.stringify({
        issuer: entraIssuer(),
        jwks_uri: `${origin}${entraKeysPath()}`,
        token_endpoint: `${origin}/${TENANT}/oauth2/v2.0/token`,
      }),
    };
    const authenticateBearer = await loadAuthenticateBearer();
    const claims = await authenticateBearer(`Bearer ${await signAccessToken(entraIssuer())}`);
    expect(claims.sub).toBe("user-object-id");
    expect(requested).toContain(entraKeysPath());
    // The Authentik convention must NOT have been tried.
    expect(requested).not.toContain(`/${TENANT}/v2.0/jwks/`);
  });
  test("tolerates a trailing slash on the issuer while still honouring discovery", async () => {
    // acceptedIssuers() takes both spellings; discovery must not regress that.
    process.env.OIDC_ISSUER_MCP = `${entraIssuer()}/`;
    process.env.OIDC_AUDIENCE = AUDIENCE;
    discoveryResponse = {
      status: 200,
      body: JSON.stringify({ jwks_uri: `${origin}${entraKeysPath()}` }),
    };
    const authenticateBearer = await loadAuthenticateBearer();
    // Token carries the un-slashed spelling; the env var carries the slashed one.
    const claims = await authenticateBearer(`Bearer ${await signAccessToken(entraIssuer())}`);
    expect(claims.sub).toBe("user-object-id");
    expect(requested).toContain(entraKeysPath());
  });
  test("falls back to ${issuer}/jwks/ when discovery is unreachable", async () => {
    process.env.OIDC_ISSUER_MCP = authentikIssuer();
    process.env.OIDC_AUDIENCE = AUDIENCE;
    discoveryResponse = { status: 500, body: "upstream exploded" };
    const authenticateBearer = await loadAuthenticateBearer();
    const claims = await authenticateBearer(`Bearer ${await signAccessToken(authentikIssuer())}`);
    // Existing Authentik deployments keep working with no discovery document.
    expect(claims.sub).toBe("user-object-id");
    expect(requested).toContain("/application/o/shared-memory-mcp/jwks/");
  });
  test("falls back to ${issuer}/jwks/ when discovery omits jwks_uri", async () => {
    process.env.OIDC_ISSUER_MCP = authentikIssuer();
    process.env.OIDC_AUDIENCE = AUDIENCE;
    // 200 OK, valid JSON, no usable key set pointer — the malformed case that
    // a naive `doc.jwks_uri` read would turn into `new URL(undefined)`.
    discoveryResponse = { status: 200, body: JSON.stringify({ issuer: authentikIssuer() }) };
    const authenticateBearer = await loadAuthenticateBearer();
    const claims = await authenticateBearer(`Bearer ${await signAccessToken(authentikIssuer())}`);
    expect(claims.sub).toBe("user-object-id");
    expect(requested).toContain("/application/o/shared-memory-mcp/jwks/");
  });
  test("falls back when discovery returns non-JSON", async () => {
    process.env.OIDC_ISSUER_MCP = authentikIssuer();
    process.env.OIDC_AUDIENCE = AUDIENCE;
    discoveryResponse = { status: 200, body: "<html>login page</html>" };
    const authenticateBearer = await loadAuthenticateBearer();
    const claims = await authenticateBearer(`Bearer ${await signAccessToken(authentikIssuer())}`);
    expect(claims.sub).toBe("user-object-id");
    expect(requested).toContain("/application/o/shared-memory-mcp/jwks/");
  });
  test("discovers once across many verifications, not once per request", async () => {
    // The MCP endpoint verifies a token on essentially every request. A
    // discovery fetch per request would add a round-trip to every tool call.
    process.env.OIDC_ISSUER_MCP = entraIssuer();
    process.env.OIDC_AUDIENCE = AUDIENCE;
    discoveryResponse = {
      status: 200,
      body: JSON.stringify({ jwks_uri: `${origin}${entraKeysPath()}` }),
    };
    const authenticateBearer = await loadAuthenticateBearer();
    for (let i = 0; i < 3; i++) {
      await authenticateBearer(`Bearer ${await signAccessToken(entraIssuer())}`);
    }
    expect(discoveryPathsSeen()).toHaveLength(1);
  });
  test("concurrent cold requests share a single discovery fetch", async () => {
    // Caching the settled value rather than the in-flight promise would let
    // every request that arrives before the first one resolves start its own
    // discovery fetch — a thundering herd at process start.
    process.env.OIDC_ISSUER_MCP = entraIssuer();
    process.env.OIDC_AUDIENCE = AUDIENCE;
    discoveryResponse = {
      status: 200,
      body: JSON.stringify({ jwks_uri: `${origin}${entraKeysPath()}` }),
    };
    const authenticateBearer = await loadAuthenticateBearer();
    const token = await signAccessToken(entraIssuer());
    await Promise.all(
      Array.from({ length: 5 }, () => authenticateBearer(`Bearer ${token}`)),
    );
    expect(discoveryPathsSeen()).toHaveLength(1);
  });
 });
@@ -2,13 +2,14 @@ import { createRemoteJWKSet, jwtVerify, errors as joseErrors } from "jose";
 import type { JWTPayload } from "jose";
 import { env } from "@/lib/env";
 import { CLI_TOKEN_KID, tokenKid, verifyCliToken } from "./cli-token";
 import { detectGroupsOverage } from "./sync-groups";
 /**
 * Authenticates a bearer token presented to the MCP endpoint. Two token
 * kinds are accepted, dispatched by the JWT `kid` header:
 *
- *   - Authentik-issued OIDC access tokens (any kid) — verified against
+ *   - IdP-issued OIDC access tokens (any kid) — verified against the
- *     Authentik's JWKS over the network.
+ *     issuer's JWKS over the network, located via OIDC discovery.
 *   - CLI tokens minted at /connect (kid="cli-v1") — verified locally
 *     with the HMAC CLI_TOKEN_SECRET.
 *
@@ -18,8 +19,25 @@ import { CLI_TOKEN_KID, tokenKid, verifyCliToken } from "./cli-token";
 * This is distinct from the NextAuth session cookie path used by the Web UI.
 */
 type JwkSet = ReturnType<typeof createRemoteJWKSet>;
 type GlobalWithJwks = typeof globalThis & {
-  __sharedMemoryJwks?: ReturnType<typeof createRemoteJWKSet>;
+  /**
   * Resolved key set, cached as a *promise* rather than a value.
   *
   * Resolution now involves a network round-trip (OIDC discovery), and the
   * MCP endpoint verifies a token on essentially every request. Caching the
   * settled value would leave a window in which N concurrent cold requests
   * each start their own discovery fetch; caching the in-flight promise means
   * the first caller does the work and everyone else awaits the same result.
   */
  __sharedMemoryJwks?: Promise<JwkSet>;
  /**
   * Epoch ms after which discovery should be re-attempted, set only when we
   * had to fall back (see `jwks()`). Undefined means the cached set came from
   * a successful discovery and is good indefinitely.
   */
  __sharedMemoryJwksRetryAt?: number;
 };
 const g = globalThis as GlobalWithJwks;
@@ -27,6 +45,10 @@ const g = globalThis as GlobalWithJwks;
 * Issuer of MCP access tokens. The MCP endpoint is a separate application in
 * the IdP from the Web UI, and Authentik stamps each token with its own
 * application slug, so this is NOT interchangeable with OIDC_ISSUER.
 *
 * Not every IdP works that way: EntraID has one issuer per tenant regardless
 * of how many app registrations you create, so OIDC_ISSUER_MCP is left unset
 * there and this falls through to OIDC_ISSUER.
 */
 export function mcpIssuer(): string {
  return env().OIDC_ISSUER_MCP ?? env().OIDC_ISSUER;
@@ -50,16 +72,88 @@ function acceptedIssuers(): [string, string] {
  return [bare, `${bare}/`];
 }
-function jwks() {
+const JWKS_OPTIONS = {
-  if (g.__sharedMemoryJwks) return g.__sharedMemoryJwks;
+  cacheMaxAge: 10 * 60 * 1000, // 10 min
-  // Authentik discovery is at `${issuer}/.well-known/openid-configuration`;
+  cooldownDuration: 30 * 1000,
-  // the JWKS URI is normally `${issuer}/jwks/` or `${issuer}/.well-known/jwks.json`.
+} as const;
-  // Authentik canonically serves `${issuer}/jwks/`.
+
-  const url = new URL(`${mcpIssuer().replace(/\/$/, "")}/jwks/`);
+/** How long to keep serving a fallback key set before retrying discovery. */
-  g.__sharedMemoryJwks = createRemoteJWKSet(url, {
+const DISCOVERY_RETRY_COOLDOWN_MS = 60 * 1000;
-    cacheMaxAge: 10 * 60 * 1000, // 10 min
+
-    cooldownDuration: 30 * 1000,
+/** Discovery can hang; every MCP request waits on it, so bound it. */
-  });
+const DISCOVERY_TIMEOUT_MS = 5 * 1000;
 /**
 * The pre-discovery convention: `${issuer}/jwks/`.
 *
 * This is Authentik's canonical JWKS path and was hardcoded here. It stays as
 * the fallback so that a deployment whose discovery document is unreachable
 * behaves exactly as it did before this change.
 */
 function fallbackJwksUri(): string {
  return `${mcpIssuer().replace(/\/$/, "")}/jwks/`;
 }
 /**
 * Read `jwks_uri` out of the MCP issuer's OIDC discovery document.
 *
 * `${issuer}/jwks/` is an Authentik convention, not a standard — RFC 8414
 * says the key set lives wherever `jwks_uri` points, and providers disagree
 * wildly. EntraID serves keys at
 * `https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys`, nowhere
 * near `${issuer}/jwks/`, so with the path hardcoded every EntraID-issued MCP
 * token fails verification with a 404 on the key set — authentication is
 * simply impossible, not merely misconfigured. Ask the issuer where its keys
 * are instead of guessing.
 *
 * Returns null (never throws) on any failure, so the caller can fall back.
 */
 async function discoverJwksUri(): Promise<string | null> {
  const url = `${mcpIssuer().replace(/\/$/, "")}/.well-known/openid-configuration`;
  try {
    const res = await fetch(url, {
      headers: { accept: "application/json" },
      signal: AbortSignal.timeout(DISCOVERY_TIMEOUT_MS),
    });
    if (!res.ok) return null;
    const doc: unknown = await res.json();
    const uri = (doc as { jwks_uri?: unknown } | null)?.jwks_uri;
    if (typeof uri !== "string" || uri.trim().length === 0) return null;
    // A malformed jwks_uri must not blow up the request path.
    new URL(uri);
    return uri;
  } catch {
    return null;
  }
 }
 /**
 * The key set MCP access tokens are verified against, resolved once per
 * process.
 *
 * Async because discovery is a network call. The cached promise is installed
 * synchronously — before the first `await` inside the IIFE runs — so
 * concurrent callers always join the existing resolution rather than racing
 * to start their own.
 *
 * When discovery fails we serve the legacy fallback but arm a retry: a single
 * blip at process start would otherwise pin the wrong URL for the lifetime of
 * the container, which on EntraID means MCP auth stays broken until someone
 * restarts it. The cooldown keeps a persistently-unreachable discovery
 * endpoint from being hit on every request.
 */
 function jwks(): Promise<JwkSet> {
  const retryAt = g.__sharedMemoryJwksRetryAt;
  const dueForRetry = retryAt !== undefined && Date.now() >= retryAt;
  if (g.__sharedMemoryJwks && !dueForRetry) return g.__sharedMemoryJwks;
  g.__sharedMemoryJwksRetryAt = undefined;
  g.__sharedMemoryJwks = (async () => {
    const discovered = await discoverJwksUri();
    if (discovered) return createRemoteJWKSet(new URL(discovered), JWKS_OPTIONS);
    g.__sharedMemoryJwksRetryAt = Date.now() + DISCOVERY_RETRY_COOLDOWN_MS;
    return createRemoteJWKSet(new URL(fallbackJwksUri()), JWKS_OPTIONS);
  })();
  return g.__sharedMemoryJwks;
 }
@@ -143,7 +237,7 @@ export async function authenticateBearer(authHeader: string | null): Promise<Aut
      } as AuthenticatedClaims;
    }
-    const { payload } = await jwtVerify(token, jwks(), {
+    const { payload } = await jwtVerify(token, await jwks(), {
      issuer: acceptedIssuers(),
      audience: env().OIDC_AUDIENCE,
    });
@@ -153,6 +247,17 @@ export async function authenticateBearer(authHeader: string | null): Promise<Aut
        buildWwwAuthenticate("invalid_token", "missing sub"),
      );
    }
    // Groups overage: the IdP is telling us it holds memberships it declined
    // to list. `extractGroupsClaim` would read that as "no claim emitted" and
    // userContextFromClaims would fall back to the DB snapshot — granting
    // project access from a stale record while the live state is admittedly
    // unknown. Refuse; the operator fix is in the description.
    if (detectGroupsOverage(payload)) {
      const desc =
        "groups overage: IdP did not enumerate group membership " +
        "(set groupMembershipClaims=ApplicationGroup on EntraID)";
      throw new UnauthorizedError(desc, buildWwwAuthenticate("invalid_token", desc));
    }
    // Normalize the issuer for identity purposes.
    //
    // The token was just verified against mcpIssuer() — that check is done.
@@ -0,0 +1,73 @@
 import { env } from "@/lib/env";
 import { mcpIssuer } from "@/lib/auth/jwt";
 /**
 * The protected-resource metadata document, RFC 9728 §2.
 *
 * Shared by both metadata routes — the root `/.well-known/oauth-protected-
 * resource` and the path-suffixed `/.well-known/oauth-protected-resource/
 * <resource path>` form of §3.1 — because the two documents differ ONLY in
 * the `resource` identifier they describe. Anything else drifting between
 * them is a bug: a client that discovers us through the suffixed URL would
 * be told to request a different scope set than one that follows the
 * `WWW-Authenticate: resource_metadata=...` header, and whichever of the two
 * lost the audience scope would hand back tokens with no `aud` claim.
 */
 export interface ResourceMetadata {
  resource: string;
  authorization_servers: string[];
  scopes_supported: string[];
  bearer_methods_supported: string[];
  resource_documentation: string;
 }
 /**
 * The public origin, with any trailing slash stripped.
 *
 * `resource` values are compared as exact strings by clients (RFC 9728 §3.3),
 * so `https://host/` and `https://host` are not interchangeable — PUBLIC_URL
 * is written both ways in the wild and only the stripped form is emitted.
 */
 export function publicOrigin(): string {
  return env().PUBLIC_URL.replace(/\/$/, "");
 }
 /**
 * Build the metadata document for `resource`.
 *
 * The caller supplies the resource identifier because it depends on which
 * URL the document was fetched from; everything else is deployment config.
 */
 export function buildResourceMetadata(resource: string): ResourceMetadata {
  // The audience scope MUST be advertised. Authentik only evaluates a scope
  // mapping when the client requests that scope by name, and the client only
  // learns scope names from this document. Omit it and every access token
  // arrives without `aud`, which jwt.ts rejects as "claim invalid: aud".
  const audienceScope =
    env().OIDC_AUDIENCE_SCOPE ?? `aud-${env().OIDC_AUDIENCE}`;
  // Same mechanism as the audience scope, different consequence: a client
  // only requests `offline_access` if it sees the name here, and without
  // that request the IdP returns no refresh token — so the client cannot
  // renew and the user gets kicked back to an interactive login whenever
  // the access token expires.
  //
  // Opt-in, because the IdP needs a matching scope mapping; advertising one
  // it doesn't offer can fail the whole authorization request.
  const scopes = ["openid", "profile", "email", audienceScope];
  if (env().OIDC_OFFLINE_ACCESS) scopes.push("offline_access");
  return {
    resource,
    // The MCP application's issuer, which is not necessarily the Web UI's —
    // see mcpIssuer(). Advertising the wrong one sends clients to a discovery
    // document whose tokens this endpoint will then reject on `iss`.
    authorization_servers: [mcpIssuer()],  // as configured, slash and all
    scopes_supported: scopes,
    bearer_methods_supported: ["header"],
    // Documentation lives at the site root regardless of which resource this
    // document describes, so it is always derived from the public origin and
    // not from `resource`.
    resource_documentation: `${publicOrigin()}/`,
  };
 }
@@ -0,0 +1,126 @@
 import { afterAll, beforeEach, describe, expect, test } from "vitest";
 /**
 * Group sync, and specifically the overage case.
 *
 * `syncUserGroupsFromClaim` deletes every membership when it sees no groups.
 * That is correct for "the IdP says zero groups" and catastrophic for "the
 * IdP declined to enumerate them" — EntraID past 200 groups. The two look
 * identical if you only inspect `claims.groups`, which is why the function
 * takes the whole claims object.
 */
 const { db, pg } = await import("@/lib/db/client");
 const { users, groups, userGroups } = await import("@/lib/db/schema");
 const { syncUserGroupsFromClaim, detectGroupsOverage, GroupsOverageError } =
  await import("@/lib/auth/sync-groups");
 const { eq } = await import("drizzle-orm");
 const ISS = "https://login.microsoftonline.com/sync-test/v2.0";
 let userId: string;
 async function memberships(): Promise<string[]> {
  const rows = await db
    .select({ name: groups.name })
    .from(userGroups)
    .innerJoin(groups, eq(userGroups.groupId, groups.id))
    .where(eq(userGroups.userId, userId));
  return rows.map((r) => r.name).sort();
 }
 beforeEach(async () => {
  await db.delete(users).where(eq(users.oidcIss, ISS));
  await db.delete(groups).where(eq(groups.oidcIss, ISS));
  const rows = await db
    .insert(users)
    .values({ oidcIss: ISS, oidcSub: "sync-test-sub" })
    .returning({ id: users.id });
  const row = rows[0];
  if (!row) throw new Error("failed to seed test user");
  userId = row.id;
 });
 afterAll(async () => {
  await db.delete(users).where(eq(users.oidcIss, ISS));
  await db.delete(groups).where(eq(groups.oidcIss, ISS));
  await pg.end();
 });
 describe("detectGroupsOverage", () => {
  test("spots the JWT overage pointer", () => {
    expect(
      detectGroupsOverage({
        _claim_names: { groups: "src1" },
        _claim_sources: { src1: { endpoint: "https://graph.windows.net/x" } },
      }),
    ).toBe(true);
  });
  test("spots the implicit-flow indicator", () => {
    expect(detectGroupsOverage({ hasgroups: true })).toBe(true);
  });
  test("is false for ordinary claims", () => {
    expect(detectGroupsOverage({ groups: ["a"] })).toBe(false);
    expect(detectGroupsOverage({})).toBe(false);
    expect(detectGroupsOverage(null)).toBe(false);
    // A _claim_names for some OTHER claim is not a groups overage.
    expect(detectGroupsOverage({ _claim_names: { roles: "src1" } })).toBe(false);
    expect(detectGroupsOverage({ hasgroups: false })).toBe(false);
  });
 });
 describe("syncUserGroupsFromClaim", () => {
  test("stores the claim's names", async () => {
    await syncUserGroupsFromClaim(userId, ISS, { groups: ["eng", "ops"] });
    expect(await memberships()).toEqual(["eng", "ops"]);
  });
  test("an empty claim really does clear memberships", async () => {
    await syncUserGroupsFromClaim(userId, ISS, { groups: ["eng"] });
    await syncUserGroupsFromClaim(userId, ISS, { groups: [] });
    expect(await memberships()).toEqual([]);
  });
  test("an absent claim clears memberships", async () => {
    // Unchanged behaviour: the IdP has stopped asserting groups, so we stop
    // honouring them rather than keeping stale grants alive.
    await syncUserGroupsFromClaim(userId, ISS, { groups: ["eng"] });
    await syncUserGroupsFromClaim(userId, ISS, {});
    expect(await memberships()).toEqual([]);
  });
  test("overage throws instead of clearing", async () => {
    await syncUserGroupsFromClaim(userId, ISS, { groups: ["eng", "ops"] });
    await expect(
      syncUserGroupsFromClaim(userId, ISS, {
        _claim_names: { groups: "src1" },
        _claim_sources: { src1: { endpoint: "https://graph.windows.net/x" } },
      }),
    ).rejects.toBeInstanceOf(GroupsOverageError);
    // The whole point: the snapshot survives, so the operator can fix the IdP
    // and the user comes back with their access intact.
    expect(await memberships()).toEqual(["eng", "ops"]);
  });
  test("the overage error names the fix", async () => {
    let err: Error | null = null;
    try {
      await syncUserGroupsFromClaim(userId, ISS, { hasgroups: true });
    } catch (e) {
      err = e as Error;
    }
    expect(err).toBeInstanceOf(GroupsOverageError);
    expect(err?.message).toContain("groupMembershipClaims");
    expect(err?.message).toContain("ApplicationGroup");
  });
  test("non-string entries are dropped, names are de-duplicated", async () => {
    await syncUserGroupsFromClaim(userId, ISS, {
      groups: ["eng", 7, null, " eng ", "ops"],
    });
    expect(await memberships()).toEqual(["eng", "ops"]);
  });
 });
@@ -2,34 +2,99 @@ import { and, eq, notInArray, sql } from "drizzle-orm";
 import { db } from "@/lib/db/client";
 import { groups, userGroups } from "@/lib/db/schema";
 /**
 * Raised when the IdP signals that it holds group memberships it declined to
 * enumerate (EntraID's "groups overage"). Callers must abort — see
 * `detectGroupsOverage` for why this cannot be treated as "no groups".
 */
 export class GroupsOverageError extends Error {
  constructor() {
    super(
      "OIDC groups overage: the identity provider signalled group membership " +
        "it did not enumerate, so the user's groups cannot be determined. On " +
        "EntraID, set the app registration's `groupMembershipClaims` to " +
        '"ApplicationGroup" (portal: "Groups assigned to the application") and ' +
        "assign the groups you share projects with. See docs/oidc-entra-id.md " +
        "§10b.",
    );
    this.name = "GroupsOverageError";
  }
 }
 /**
 * Does this token say "there are groups, but I'm not listing them"?
 *
 * EntraID stops emitting `groups` past 200 entries in a JWT (150 in SAML, 5 in
 * implicit flow) and substitutes a pointer:
 *
 *     "_claim_names":   { "groups": "src1" },
 *     "_claim_sources": { "src1": { "endpoint": "https://graph.windows.net/…" } }
 *
 * or, for implicit flow, `"hasgroups": true`.
 *
 * This is NOT a truncated list — it is no list at all, and it is materially
 * different from "this user belongs to zero groups". Conflating the two is
 * what made this dangerous: the absent-claim branch below deletes every one of
 * the user's memberships, so a user crossing the 200-group line would silently
 * lose access to every shared project on both surfaces, with no error raised
 * anywhere.
 *
 * We refuse instead. Group state gates `readableProjectIds` / `canWriteProject`,
 * and granting or revoking access on state we know we don't have is guesswork
 * either way. Failing loudly destroys nothing and names its own fix.
 */
 export function detectGroupsOverage(claims: unknown): boolean {
  const c = claims as
    | { _claim_names?: unknown; hasgroups?: unknown }
    | null
    | undefined;
  if (!c || typeof c !== "object") return false;
  if (c.hasgroups === true) return true;
  const names = c._claim_names;
  return (
    typeof names === "object" &&
    names !== null &&
    "groups" in (names as Record<string, unknown>)
  );
 }
 /**
 * Sync a user's group memberships from the OIDC `groups` claim on sign-in.
 *
 * Takes the whole claims object, not just the claim value, because deciding
 * what an absent `groups` means requires seeing the overage markers that sit
 * beside it.
 *
 * Claim shape: `string[]`. Authentik emits group *names* directly here;
- * Keycloak and Okta likewise (with the right mappers configured). EntraID,
+ * Keycloak and Okta likewise (with the right mappers configured). EntraID
- * when correctly configured per README, emits names too — but the default
+ * emits object-id GUIDs by default — `cloud_displayname` gets you names, but
- * "groups" optional-claim variant emits object-id GUIDs instead, and if the
+ * only under `groupMembershipClaims: "ApplicationGroup"`, and only for
- * user is in too many groups EntraID switches to a "groups overage"
+ * directly assigned groups. See docs/oidc-entra-id.md §10a.
 * indicator (no group list at all). We take the conservative path:
 *
 *   - whatever strings appear in the claim are treated as names verbatim
 *     and stored as-is. If your IdP emits GUIDs, the UI will show GUIDs;
 *     fix it at the IdP layer (we don't attempt resolution).
 *   - if the claim is missing/empty, the user is treated as having zero
- *     groups and all existing memberships are deleted.
+ *     groups and all existing memberships are deleted. That is the
- *   - groups overage (where EntraID emits `_claim_names.groups` instead of
+ *     conservative reading: don't keep stale grants alive once the IdP has
- *     `groups`) is not handled in v1 — the user appears as having no
+ *     stopped asserting them.
- *     groups. Documented limit; revisit if it bites someone.
+ *   - if the IdP signals an overage, we throw rather than apply either
 *     reading. See `detectGroupsOverage`.
 *
 * The whole operation runs in a single transaction so the membership
 * snapshot is atomic (no window where a user partially has new memberships
 * and still has stale ones).
 *
 * @throws {GroupsOverageError} when the claims carry an overage indicator.
 */
 export async function syncUserGroupsFromClaim(
  userId: string,
  oidcIss: string,
-  rawClaim: unknown,
+  claims: unknown,
 ): Promise<void> {
  if (detectGroupsOverage(claims)) throw new GroupsOverageError();
  const rawClaim = (claims as { groups?: unknown } | null | undefined)?.groups;
  const names = normalizeGroupsClaim(rawClaim);
  await db.transaction(async (tx) => {
@@ -53,6 +53,21 @@ export const users = pgTable(
    oidcSub: text("oidc_sub").notNull(),
    // OIDC `iss` so we can disambiguate if we ever federate.
    oidcIss: text("oidc_iss").notNull(),
    /**
     * EntraID `oid` — the user's directory object id.
     *
     * Null on IdPs that don't emit it (Authentik, Keycloak, Okta), where
     * `sub` is already stable across applications and remains the key.
     *
     * EntraID's `sub` is PAIRWISE: it is derived from the token recipient,
     * so the Web UI app registration and the MCP app registration produce
     * different `sub` values for the same human. Keying on `sub` there
     * silently creates two accounts for one person — sign in on the web,
     * connect an MCP client, find an empty account. `oid` is the identifier
     * Microsoft documents as constant for a user across every application in
     * a tenant, so it takes precedence whenever it's present.
     */
    oidcOid: text("oidc_oid"),
    email: text("email"),
    name: text("name"),
    picture: text("picture"),
@@ -61,6 +76,11 @@ export const users = pgTable(
  },
  (t) => ({
    uniqueIss: uniqueIndex("users_iss_sub_uq").on(t.oidcIss, t.oidcSub),
    // Partial: rows from IdPs that emit no `oid` all hold NULL here, and a
    // plain unique index would collapse them into a single allowed row.
    uniqueOid: uniqueIndex("users_iss_oid_uq")
      .on(t.oidcIss, t.oidcOid)
      .where(sql`${t.oidcOid} IS NOT NULL`),
  }),
 );
@@ -1,6 +1,7 @@
 import { db } from "@/lib/db/client";
-import { users, groups, userGroups } from "@/lib/db/schema";
+import { groups, userGroups } from "@/lib/db/schema";
-import { and, eq } from "drizzle-orm";
+import { eq } from "drizzle-orm";
 import { oidClaim, resolveUserId } from "@/lib/auth/identity";
 import type { AuthenticatedClaims } from "@/lib/auth/jwt";
 /**
@@ -55,37 +56,18 @@ export async function userContextFromClaims(
  const name = (claims.name as string | undefined) ?? null;
  const picture = (claims.picture as string | undefined) ?? null;
-  const row = await db
+  // Shared with the Web UI sign-in path (auth.ts). Keeping one resolver is
-    .insert(users)
+  // what stops the two surfaces disagreeing about who a user is — on EntraID
-    .values({
+  // they see different `sub` values for the same person and would otherwise
-      oidcSub: claims.sub,
+  // each create their own account. See lib/auth/identity.ts.
-      oidcIss: claims.iss,
+  const userId = await resolveUserId({
-      email,
+    iss: claims.iss,
-      name,
+    sub: claims.sub,
-      picture,
+    oid: oidClaim(claims),
-    })
+    email,
-    .onConflictDoUpdate({
+    name,
-      target: [users.oidcIss, users.oidcSub],
+    picture,
-      set: {
+  });
        email,
        name,
        picture,
        lastSeenAt: new Date(),
      },
    })
    .returning({ id: users.id });
  let userId = row[0]?.id;
  if (!userId) {
    // Race against another upsert — fall back to a select.
    const existing = await db
      .select({ id: users.id })
      .from(users)
      .where(and(eq(users.oidcIss, claims.iss), eq(users.oidcSub, claims.sub)))
      .limit(1);
    if (!existing[0]) throw new Error("user upsert failed and not found on re-read");
    userId = existing[0].id;
  }
  // OIDC bearer tokens carry a `groups` claim (when the IdP is configured to
  // emit it). CLI tokens never do — they go through verifyCliToken which
@@ -0,0 +1,24 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 283 64" width="283" height="64" role="img" aria-label="shared-memory">
  <title>shared-memory</title>
  <!--
    Horizontal lockup for headers, docs, and the OAuth consent screen, where a
    bare 64px glyph is too little and the full app header is too much.
    currentColor, so it inherits the surrounding text colour. That does NOT
    survive being referenced as <img src>, which resolves currentColor to
    black - use docs/assets/lockup.svg for anything outside the app.
    `textLength` is not decoration: the wordmark is set in whatever monospace
    the viewer has, and without a locked advance width the text overruns the
    viewBox on wider fonts.
  -->
  <g fill="none" stroke="currentColor" stroke-linecap="round" stroke-width="7">
    <path d="M12 16C24 16 25 32 30 32" opacity=".7"/>
    <path d="M12 32H30"/>
    <path d="M12 48C24 48 25 32 30 32" opacity=".7"/>
  </g>
  <circle cx="46" cy="32" r="8.5" fill="currentColor"/>
  <text x="72" y="41" fill="currentColor" textLength="203" lengthAdjust="spacingAndGlyphs"
        font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
        font-size="26" letter-spacing="-0.8">shared<tspan opacity=".45">-</tspan>memory</text>
 </svg>
@@ -3,12 +3,20 @@
  <!--
    Transparent, currentColor variant of the mark for in-app use - inherits
    the surrounding text color so it works on any surface. The tile version
-    used as the favicon lives at app/icon.svg.
+    used as the favicon lives at app/icon.svg, and the horizontal lockup at
    public/lockup.svg.
    Three retrieval signals converging on a single memory. Proportions are
    set by the 16px case, which is the one that breaks: the strokes stop at
    x=30 so the gap to the node survives rasterisation, the outer pair sits
    at .7 rather than .45 so it doesn't drop out, and the node is r=8.5.
    The earlier proportions rendered as an indeterminate smear in a browser
    tab.
  -->
  <g fill="none" stroke="currentColor" stroke-linecap="round" stroke-width="7">
-    <path d="M13 15C25 15 27 32 37 32" opacity=".45"/>
+    <path d="M12 16C24 16 25 32 30 32" opacity=".7"/>
-    <path d="M13 32H37"/>
+    <path d="M12 32H30"/>
-    <path d="M13 49C25 49 27 32 37 32" opacity=".7"/>
+    <path d="M12 48C24 48 25 32 30 32" opacity=".7"/>
  </g>
-  <circle cx="43" cy="32" r="8" fill="currentColor"/>
+  <circle cx="46" cy="32" r="8.5" fill="currentColor"/>
 </svg>
@@ -0,0 +1,24 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 283 64" width="283" height="64" role="img" aria-label="shared-memory">
  <title>shared-memory</title>
  <!--
    Horizontal lockup for headers, docs, and the OAuth consent screen, where a
    bare 64px glyph is too little and the full app header is too much.
    Fixed-colour twin of apps/web/public/lockup.svg, for README and any other
    context that references the file as <img src> - there currentColor resolves
    to black and vanishes on a dark page. #0092fd holds on both git-host themes.
    `textLength` is not decoration: the wordmark is set in whatever monospace
    the viewer has, and without a locked advance width the text overruns the
    viewBox on wider fonts.
  -->
  <g fill="none" stroke="#0092fd" stroke-linecap="round" stroke-width="7">
    <path d="M12 16C24 16 25 32 30 32" opacity=".7"/>
    <path d="M12 32H30"/>
    <path d="M12 48C24 48 25 32 30 32" opacity=".7"/>
  </g>
  <circle cx="46" cy="32" r="8.5" fill="#0092fd"/>
  <text x="72" y="41" fill="#0092fd" textLength="203" lengthAdjust="spacingAndGlyphs"
        font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
        font-size="26" letter-spacing="-0.8">shared<tspan opacity=".45">-</tspan>memory</text>
 </svg>
@@ -0,0 +1,692 @@
 # OIDC provider setup: Microsoft Entra ID
 Companion to the **OIDC provider setup** section in [`README.md`](../README.md),
 which walks through Authentik. The structure here deliberately mirrors it —
 app registration A (Web UI), app registration B (MCP resource server), env var
 mapping, verification — so the two are diffable. Where Entra genuinely differs
 from Authentik, the difference is called out rather than smoothed over.
 Everything below assumes a **single-tenant** deployment (`signInAudience` =
 "Accounts in this organizational directory only"). Multitenant is possible but
 the `iss` verification in `apps/web/lib/auth/jwt.ts` compares against a fixed
 string, so it would need code changes — see [Multitenant](#13-multitenant-is-not-supported)
 at the end.
 ---
 ## 0. Prerequisite: your build must have JWKS discovery
 **Check this first. Nothing else in this document works without it.**
 Until recently `apps/web/lib/auth/jwt.ts` hardcoded the JWKS location as
 `${issuer}/jwks/`. That is an *Authentik* convention, not a standard — RFC 8414
 says the key set lives wherever the discovery document's `jwks_uri` points, and
 Entra puts it somewhere else entirely:
 | IdP | JWKS URL |
 |---|---|
 | Authentik | `https://auth.example.com/application/o/<slug>/jwks/` |
 | Entra ID | `https://login.microsoftonline.com/<tenant>/discovery/v2.0/keys` |
 With the path hardcoded, every Entra-issued MCP access token fails verification
 because the key set fetch 404s. There is no configuration that works around it;
 MCP authentication is simply impossible.
 The current code resolves `jwks_uri` from
 `${OIDC_ISSUER_MCP or OIDC_ISSUER}/.well-known/openid-configuration`, caches the
 result for the process lifetime, and falls back to `${issuer}/jwks/` only if
 discovery is unreachable (so existing Authentik deployments are untouched).
 Confirm your deployment has it before debugging anything else:
 ```bash
 # Should return the Entra keys endpoint, not a 404.
 curl -s "https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration" \
  | jq -r .jwks_uri
 # → https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys
 ```
 If MCP calls 401 with `error_description="verification failed"` and your app
 logs show a fetch to `.../v2.0/jwks/`, you are on an older build.
 ---
 ## 1. Concepts, Authentik → Entra
 | Concept here | Authentik | Entra ID |
 |---|---|---|
 | OAuth2 client | Provider + Application | App registration |
 | Issuer | Per-application (`.../application/o/<slug>/`) | **Per-tenant only** — one issuer for the whole directory |
 | Audience claim | Scope mapping returning `{"aud": …}` | "Expose an API" scope on the resource app; `aud` is set automatically |
 | Redirect URI matching | Regex allowed (any port) | **Exact string match**, with one loopback exception |
 | Dynamic client registration | Not implemented | Not implemented |
 The **issuer** row is the one that reshapes the setup. On Authentik, the Web UI
 and MCP endpoint are separate applications with separate issuers, which is why
 `OIDC_ISSUER_MCP` exists. Entra has exactly one issuer per tenant no matter how
 many app registrations you create, so **`OIDC_ISSUER_MCP` is left unset on
 Entra** and `mcpIssuer()` falls through to `OIDC_ISSUER`.
 You still create **two app registrations**, for the same reason as on Authentik:
 one confidential client for the browser sign-in, one resource server that owns
 the audience the MCP endpoint validates. (A third participant — the *public
 PKCE client* Claude Code uses — is covered in §4; you can fold it into
 registration B or split it out.)
 ---
 ## 2. Find your tenant ID and use it explicitly
 Everywhere below, `<tenant-id>` is your directory (tenant) GUID, from
 **Entra admin center → Overview → Tenant ID**.
 **Do not use the `common` or `organizations` authority.** Their discovery
 documents return a *templated* issuer — the literal string, verified live:
 ```bash
 curl -s https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration | jq -r .issuer
 # → https://login.microsoftonline.com/{tenantid}/v2.0
 ```
 That `{tenantid}` is not a formatting artifact; it is what the endpoint really
 returns. `jwt.ts` compares `iss` by exact string (via `acceptedIssuers()`), so
 against a templated issuer **no token can ever match** and every MCP call fails
 with `claim invalid: iss`.
 Microsoft's documented pattern for multitenant apps is to substitute the token's
 `tid` claim into the placeholder and then compare — this app does not do that
 (see [Multitenant](#13-multitenant-is-not-supported)). For single-tenant, the fix
 is simply to use the tenant-specific authority, whose discovery document
 returns a concrete issuer:
 ```bash
 curl -s "https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration" | jq -r .issuer
 # → https://login.microsoftonline.com/<tenant-id>/v2.0     (no trailing slash)
 ```
 A verified domain (`contoso.onmicrosoft.com`) also works as the authority
 segment — Entra resolves it server-side and returns the GUID form in both
 `issuer` and `jwks_uri`. Since the *returned* issuer is what tokens carry,
 `OIDC_ISSUER` must be the GUID form regardless of which you typed.
 ---
 ## 3. App registration A — Web UI (confidential client)
 **Entra admin center → Entra ID → App registrations → New registration**
 - **Name:** `shared-memory-web`
 - **Supported account types:** Accounts in this organizational directory only
 - **Redirect URI:** platform **Web**, value:
  ```
  https://memory.example.com/api/auth/callback/oidc
  ```
  (replace with your `PUBLIC_URL`; the `/oidc` suffix comes from the provider
  id in `apps/web/auth.ts` and is not configurable without a code change)
 Register, then collect:
 - **Overview → Application (client) ID** → `.env` as `OIDC_CLIENT_ID_WEB`
 - **Certificates & secrets → New client secret** → `.env` as
  `OIDC_CLIENT_SECRET_WEB` (copy the *Value*, not the Secret ID; it is shown
  once)
 **API permissions:** `openid`, `profile`, `email` are Microsoft Graph delegated
 permissions and are present by default via `User.Read`. Add `profile`
 explicitly if it is missing — it gates the `oid` and `tid` claims, which
 matter for §7.
 No "Expose an API" configuration is needed on this registration. Auth.js only
 consumes the ID token here.
 ---
 ## 4. App registration B — MCP resource server
 This registration is what `OIDC_AUDIENCE` refers to. It owns the API scope that
 Claude Code requests, and the MCP endpoint validates that tokens were minted
 for it.
 **App registrations → New registration**
 - **Name:** `shared-memory-mcp`
 - **Supported account types:** same as A
 ### 4a. Set the access token version — the single most common failure
 **Manage → Manifest**, find and set:
 ```json
 "api": {
    "requestedAccessTokenVersion": 2
 }
 ```
 There is no checkbox for this; it is a manifest edit.
 > **Note on the property name.** Older guides (and older versions of this
 > project's notes) call this `accessTokenAcceptedVersion` at the top level of
 > the manifest. That is the **retired Azure AD Graph** manifest format —
 > Microsoft removed it from the portal's manifest editor on 2025-01-07, so you
 > will not find that property. The current Microsoft Graph app manifest nests
 > it as `api.requestedAccessTokenVersion`. The semantics are identical:
 > `null` or `1` → v1.0 tokens, `2` → v2.0 tokens.
 Leave it at the default `null` and Entra issues **v1.0** access tokens, whose
 issuer is:
 ```
 https://sts.windows.net/<tenant-id>/          ← note the trailing slash
 ```
 not `https://login.microsoftonline.com/<tenant-id>/v2.0`. Verification then
 fails with `claim invalid: iss`, and — because everything else in the OAuth
 handshake succeeded — it looks like a mysterious 401 rather than a
 configuration error.
 The setting lives on the **resource** app and wins over whichever endpoint the
 client used: with `requestedAccessTokenVersion: 2`, a client hitting the v1.0
 endpoint still receives a v2.0 access token.
 ### 4b. Expose an API
 **Manage → Expose an API**
 1. **Application ID URI** → *Add* → accept the default `api://<client-id-of-B>`.
 2. **Add a scope**:
   - **Scope name:** `access_as_user`
   - **Who can consent:** **Admins and users** (see §9)
   - Fill in the admin/user consent display strings; they appear on the consent
     prompt.
 The resulting full scope string is `api://<client-id-of-B>/access_as_user`.
 ### 4c. The public PKCE client (Claude Code)
 Claude Code is a public client using PKCE. Add a platform to registration B
 (or to a third registration if you prefer them separated — then that
 registration's client ID is `OIDC_CLIENT_ID_MCP`, and it needs
 `api://<client-id-of-B>/access_as_user` under **API permissions**):
 **Manage → Authentication → Add a platform → Mobile and desktop applications**
 > **The platform type is not cosmetic.** A redirect URI registered under the
 > **Web** platform classifies the app as a *confidential* client, and the
 > token exchange then demands a `client_secret` or `client_assertion` —
 > Claude Code has neither, so the flow dies with
 > `AADSTS7000218: The request body must contain the following parameter:
 > 'client_assertion' or 'client_secret'`. The portal will happily accept
 > `http://localhost:33418/callback` as a Web redirect URI, which is what makes
 > this trap easy to fall into. **Mobile and desktop applications**
 > (`publicClient` in the manifest) is the correct platform. SPA is not an
 > option either — Entra rejects SPA redirect URIs for non-SPA flows.
 Under **Custom redirect URIs**, register:
 ```
 http://localhost/callback
 https://memory.example.com/auth/cli-callback
 ```
 The first covers the loopback listener from README → *B. OAuth flow*; the
 second is the manual-paste fallback from *C*. "Mobile and desktop
 applications" permits arbitrary `https://` URIs alongside the loopback one, so
 both live on the same platform. If the server will also be added as a claude.ai
 custom connector, that flow is brokered by claude.ai and comes back to
 `https://claude.ai/api/mcp/auth_callback` — register it here too, or the
 connector stops at the IdP's redirect-URI mismatch error before any login
 prompt. See README → *Which redirect URIs to register*.
 **Note the missing port.** Entra ignores the port component when matching
 `http://localhost` redirect URIs, so the single registration
 `http://localhost/callback` matches `http://localhost:33418/callback`,
 `http://localhost:9999/callback`, and any other port. This is Entra's
 equivalent of the Authentik regex (`^http://(127\.0\.0\.1|localhost):\d+(/.*)?$`)
 the README mentions — users can pick any `--callback-port` without
 re-registering.
 Three constraints on that convenience:
 - **The path is still matched exactly.** Registering bare `http://localhost`
  does *not* match `http://localhost:33418/callback`. The `/callback` suffix
  must be there, and paths are case-sensitive.
 - **Do not register several localhost URIs differing only by port.** Entra
  picks one arbitrarily when matching.
 - **Port-agnostic matching is documented for `localhost` only**, not for
  `127.0.0.1` — and the portal text box refuses the `http://127.0.0.1` form
  anyway (it requires a manifest edit). Use `localhost`. `[::1]` is not
  supported at all.
 You do **not** need to enable **Allow public client flows**
 (`allowPublicClient`). That toggle is a *fallback* for flows where Entra can't
 infer the client type from a redirect URI — device code, ROPC, Windows
 Integrated Auth. Authorization code + PKCE with a registered
 mobile-and-desktop redirect URI is inferred correctly without it. (Entra's own
 `reply-url` doc says otherwise in one sentence; the manifest reference and the
 AADSTS7000218 troubleshooting article agree it is a fallback. Leave it off
 unless you hit a problem — Microsoft warns that flipping a confidential client
 to public has security implications.)
 **Application (client) ID** of whichever registration Claude Code
 authenticates as → `.env` as `OIDC_CLIENT_ID_MCP`.
 ---
 ## 5. `OIDC_AUDIENCE` vs. `OIDC_AUDIENCE_SCOPE`
 On Authentik these two look redundant — the scope mapping is named
 `aud-shared-memory` and it emits `aud: shared-memory`, so the values track each
 other. On Entra they are **necessarily different strings**, and swapping them is
 the easiest mistake to make here.
 | Var | What it is | Entra value |
 |---|---|---|
 | `OIDC_AUDIENCE` | The `aud` claim `jwt.ts` requires on the token | `<client-id-of-B>` — a bare GUID |
 | `OIDC_AUDIENCE_SCOPE` | The scope string the *client* asks for, advertised in `/.well-known/oauth-protected-resource` | `api://<client-id-of-B>/access_as_user` |
 Why they differ: the client requests a scope by its full URI
 (*Application ID URI* + `/` + scope name), but Entra does not put that URI in the
 token. For **v2.0** access tokens it splits the request into `aud` (the API's
 **client-ID GUID**) and `scp` (the **short** scope name, `access_as_user`).
 Three distinct strings for what feels like one concept.
 > **Do not trust this document — decode a real token.** Microsoft's own
 > [access-tokens](https://learn.microsoft.com/en-us/entra/identity-platform/access-tokens)
 > page says web APIs "must only accept tokens containing one of their AppId
 > URIs as the `aud` claim", which contradicts the authoritative
 > [access token claims reference](https://learn.microsoft.com/en-us/entra/identity-platform/access-token-claims-reference)
 > ("In v2.0 tokens, this value is always the client ID of the API"). The
 > claims reference is correct for v2.0, but given that Microsoft's docs
 > disagree with each other, verify empirically — see §8.
 `OIDC_AUDIENCE_SCOPE` **must** be set explicitly on Entra. Left unset, the code
 defaults to `aud-${OIDC_AUDIENCE}`, which is an Authentik naming convention and
 means nothing to Entra — the client would request a nonexistent scope and the
 authorize request fails outright.
 ---
 ## 6. `offline_access`
 Set `OIDC_OFFLINE_ACCESS=true` from the start. Unlike Authentik — where you must
 first attach an `offline_access` scope mapping to the provider — Entra treats
 `offline_access` as one of its well-defined platform scopes (`openid`, `email`,
 `profile`, `offline_access`). Nothing to create, and it is **implicitly
 granted**: if any delegated permission is consented, `offline_access` is too.
 Two caveats:
 - It must still be *requested* at runtime, which is exactly what
  `OIDC_OFFLINE_ACCESS=true` achieves — the flag adds it to `scopes_supported`
  in `/.well-known/oauth-protected-resource`, and MCP clients only request
  scopes they see advertised there.
 - A refresh token comes back only on authorization-code-style flows. That is
  what Claude Code uses, so this is satisfied; implicit flow would not be.
 The `.env` comment on this var warns that advertising a scope the IdP doesn't
 offer risks `invalid_scope`. On Entra that risk doesn't apply.
 ---
 ## 7. Identity: `sub` splits accounts across app registrations
 **Handled as of migration `0005_user_oid.sql`. Read this anyway — it explains
 why `oid` is in your database, and what happens if you deploy the migration
 late.**
 The app keys the `users` row on `(oidc_iss, oidc_sub)` — see the upsert in
 `apps/web/lib/mcp/context.ts` and the one in `apps/web/auth.ts`. On Authentik
 that is safe, because Authentik's `sub` is `user.uid`, a user-level value that
 is identical across providers.
 Entra's `sub` is a **pairwise identifier**. Microsoft documents it as *"based on
 a combination of the token recipient, tenant, and user"* — so the value is
 scoped to the app registration in the `aud` position of that particular token:
 - Web UI sign-in → ID token with `aud` = registration **A** → `sub` = *X*
 - MCP access token → `aud` = registration **B** → `sub` = *Y*
 *X ≠ Y*, by design, for privacy. `iss` is identical for both (one tenant, one
 issuer), so `(iss, sub)` yields **two different keys for the same human**. Both
 code paths *upsert* rather than fail, so nothing looks broken: the person signs
 into the Web UI, sees their memories, connects Claude Code, and finds an empty
 account. Writes land in the second row.
 There is no configuration fix. `sub` is in Entra's restricted claim set (no
 claims-mapping policy can alter it), `subject_types_supported` advertises only
 `pairwise`, and Microsoft has stated that `sector_identifier_uri` is not used to
 generate it.
 **How it's handled.** Identity is keyed on `oid` — the directory object id,
 which Microsoft documents as constant for a user across every application in a
 tenant (*"all apps get the same `oid` and `tid` claims for a user acting in a
 tenant"*). It is emitted by default in v2.0 ID *and* access tokens as long as
 the `profile` scope is requested, which it is.
 `apps/web/lib/auth/identity.ts` holds the single resolver both surfaces call.
 Resolution order when `oid` is present:
 1. an existing row keyed on `(oidc_iss, oidc_oid)` — the steady state
 2. a pre-migration row matching `(oidc_iss, oidc_sub)` with no `oid` yet, which
   gets its `oid` backfilled in place
 3. insert
 IdPs that emit no `oid` (Authentik, Keycloak, Okta) skip straight to the
 original `(iss, sub)` behaviour, unchanged.
 > **One upgrade-ordering caveat.** Step 2 adopts a legacy row by matching
 > `sub`, and the only `sub` that can match is the one that created it — the
 > **Web UI** one, since MCP auth against Entra was impossible before the JWKS
 > fix in §0. So if you already had Entra users signing into the Web UI, have
 > them **sign into the Web UI once** after deploying this migration, before
 > connecting an MCP client. Connecting MCP first creates a fresh row keyed on
 > `oid` and leaves the original stranded, with the memories in it invisible.
 > Deployments that have never run Entra are unaffected.
 The single-registration layout (making registration A the resource server too)
 also works and needs no migration, but you lose audience separation between the
 Web UI and MCP.
 ---
 ## 8. Verification
 Run these in order; each one isolates a different failure.
 **1. The issuer is concrete, not templated.**
 ```bash
 curl -s "https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration" \
  | jq '{issuer, jwks_uri}'
 ```
 `issuer` must be a GUID URL, not `{tenantid}`. Copy it verbatim into
 `OIDC_ISSUER`.
 **2. Our metadata advertises the right scopes.**
 ```bash
 curl -s https://memory.example.com/.well-known/oauth-protected-resource | jq
 ```
 `scopes_supported` must contain `api://<client-id-of-B>/access_as_user` (not
 `aud-…`), plus `offline_access` if you enabled it. `authorization_servers[0]`
 must be the tenant-specific v2.0 issuer.
 **3. Decode a real access token.** This is the only step that proves the
 `aud`/`iss`/version questions. Get a token (from Claude Code's stored
 credentials, or by running the flow manually) and inspect the payload:
 ```bash
 TOKEN='eyJ...'
 echo "$TOKEN" | cut -d. -f2 | tr '_-' '/+' | base64 -d 2>/dev/null | jq '{ver, iss, aud, sub, oid, tid, scp, groups}'
 ```
 Expected:
 | Field | Expected value | If wrong |
 |---|---|---|
 | `ver` | `"2.0"` | `api.requestedAccessTokenVersion` is not `2` (§4a) |
 | `iss` | `https://login.microsoftonline.com/<tenant-id>/v2.0` | v1 token, or `common` authority (§2, §4a) |
 | `aud` | `<client-id-of-B>`, a bare GUID | set `OIDC_AUDIENCE` to whatever is actually here (§5) |
 | `scp` | `access_as_user` | the scope wasn't requested or consented (§9) |
 | `groups` | array of GUIDs, or absent | see §10 |
 **4. Confirm the 401 reason** when something is still wrong — the MCP endpoint
 names the failing claim:
 ```bash
 curl -s -i -H "Authorization: Bearer $TOKEN" https://memory.example.com/api/mcp | head -20
 ```
 Look at `WWW-Authenticate`: `error_description="claim invalid: iss"` →
 §2/§4a. `"claim invalid: aud"` → §5. `"verification failed"` → JWKS could not
 be fetched, §0.
 ---
 ## 9. Consent for the API scope
 A custom scope is not inherently admin-only. Two levers decide it:
 - **The scope's own setting.** "Who can consent?" on the scope — **Admins and
  users** lets users self-consent; **Admins only** always requires an admin.
  Select "Admins and users" (§4b). Microsoft's docs don't state which radio the
  portal preselects, so set it deliberately rather than assuming.
 - **The tenant's user-consent policy.** The default is *"users are allowed to
  consent to applications for permissions that don't require administrator
  consent"*, but many tenants tighten this to "verified publishers only" or
  disable user consent entirely, in which case an admin must consent regardless
  of the scope setting.
 Admin consent becomes **mandatory** if: the scope is "Admins only"; the tenant
 policy restricts user consent; or — the one that catches people — the enterprise
 application is set to **require user assignment**, which forces admin consent
 even when tenant policy would otherwise permit self-consent.
 **To grant it:** App registrations → *the client app* (the one Claude Code uses,
 not the API) → **API permissions** → **Grant admin consent for \<tenant\>**. The
 button is disabled if you aren't an admin or no permissions are configured.
 Alternatively, suppress the prompt entirely with **pre-authorization**: on
 registration B, **Expose an API → Authorized client applications → Add a client
 application**, select the MCP client ID and tick `access_as_user`. Consent is
 then implicit. Reasonable here, since you control both registrations.
 If you prefer the URL form of admin consent, note it needs the `/v2.0/` segment
 and must not use `common`:
 ```
 https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent
  ?client_id=<OIDC_CLIENT_ID_MCP>
  &scope=api://<client-id-of-B>/access_as_user
  &redirect_uri=https://memory.example.com/auth/cli-callback
  &state=12345
 ```
 ---
 ## 10. Groups
 Group memberships gate access to shared projects (`readableProjectIds` /
 `canWriteProject` in `apps/web/lib/mcp/tools.ts` and
 `apps/web/lib/memory-mutations.ts`). Entra's groups claim needs care on two
 independent axes: **what the values look like**, and **what happens when the
 claim goes missing**.
 ### 10a. By default you get GUIDs, not names
 Entra emits `groups` as a **JSON array of group object-ID GUIDs**. Not display
 names. `apps/web/lib/auth/sync-groups.ts` stores whatever strings arrive
 verbatim and makes no attempt to resolve them, so the Web UI will list
 memberships like `8f4c…-b21a` and your project ACLs must be written against
 those GUIDs.
 There *is* a supported way to get display names for cloud-only groups —
 contrary to the older note in `sync-groups.ts`, which says names are available
 only for AD-synced groups. That was true of the `sam_account_name` family
 (those attributes genuinely exist only on groups synced from on-premises AD via
 Entra Connect 1.2.70+), but Entra also has `cloud_displayname`:
 **App registrations → \<B\> → Token configuration → Add groups claim**, select
 **Groups assigned to the application**, then tick the cloud-only display name
 option. In the manifest:
 ```json
 "groupMembershipClaims": "ApplicationGroup",
 "optionalClaims": {
  "accessToken": [
    { "name": "groups",
      "additionalProperties": ["cloud_displayname"] }
  ],
  "idToken": [
    { "name": "groups",
      "additionalProperties": ["cloud_displayname"] }
  ]
 }
 ```
 Both collections matter: `idToken` feeds the Web UI sign-in path (`auth.ts`),
 `accessToken` feeds the MCP path (`jwt.ts`). Configure only one and the two
 surfaces disagree about your group names.
 Constraints, all of them load-bearing:
 - `cloud_displayname` **only works with `groupMembershipClaims:
  "ApplicationGroup"`**. Microsoft's stated reason is that group display names
  aren't unique, so they only emit them for groups explicitly assigned to the
  application.
 - Only **directly assigned** groups appear. **Nested groups are excluded.**
 - Assign the groups under **Enterprise applications → \<B\> → Users and
  groups**, or they simply won't be emitted.
 - Microsoft's published `cloud_displayname` examples cover `idToken` and
  `saml2Token`; we found no official example pairing it with `accessToken`.
  It is a documented-valid collection, but **decode a real access token (§8)
  and confirm `groups` contains names before relying on it** rather than
  assuming symmetry.
 A claims-mapping policy cannot fix this instead: `groups` is a restricted
 claim, so its data source can't be changed and no transformation applies.
 If none of this appeals, Microsoft's own recommendation is to use **app roles**
 rather than groups for authorization — but this app reads `groups`, so that
 would need a code change.
 ### 10b. Groups overage — now refused rather than obeyed
 **This was the sharpest edge in this document. It is now a hard failure with a
 readable message, which is a much better outcome than what it used to do.**
 Past a limit, Entra stops emitting `groups` altogether and substitutes an
 overage indicator:
 | Token | Limit | What you get past it |
 |---|---|---|
 | JWT (access + ID) | **200** groups | `groups` absent; `_claim_names` / `_claim_sources` present |
 | SAML | 150 groups | same |
 | Implicit flow | **5** groups | `"hasgroups": true` |
 The indicator looks like this — note it is *not* a truncated list, it is no
 list at all:
 ```json
 {
  "_claim_names":   { "groups": "src1" },
  "_claim_sources": { "src1": { "endpoint": "https://graph.windows.net/…" } }
 }
 ```
 (That endpoint is an **Azure AD Graph** URL, not Microsoft Graph. Don't follow
 it; Microsoft says to construct
 `https://graph.microsoft.com/v1.0/users/{id}/getMemberObjects` yourself.
 Limits are inclusive of nested groups.)
 **What this used to do.** An absent `groups` claim and a claim saying "zero
 groups" were indistinguishable to `normalizeGroupsClaim`, which returned `[]`
 for both — and the `names.length === 0` branch **deletes every one of that
 user's `user_groups` rows**. So a user crossing 200 groups signed into the Web
 UI once and silently lost access to every shared project, on both surfaces,
 with no error anywhere. (The MCP path never deleted anything, but it then read
 the snapshot the Web sign-in had just emptied.)
 **What happens now.** `detectGroupsOverage` looks for `_claim_names.groups` and
 `hasgroups`, and both surfaces refuse the token rather than acting on group
 state they know they don't have:
 - **Web sign-in** throws `GroupsOverageError`, which fails the sign-in. Existing
  memberships are left completely untouched.
 - **MCP** returns 401 with
  `error_description="groups overage: IdP did not enumerate group membership …"`.
 The user is blocked until an admin fixes the claim configuration — and then
 signs in and finds their access exactly as it was. Nothing to restore, because
 nothing was destroyed. Granting access from a stale snapshot, or revoking it on
 a claim the IdP never made, are both guesses; refusing is the only honest
 answer available.
 An absent `groups` claim with **no** overage marker still clears memberships.
 That is unchanged and deliberate: the IdP has genuinely stopped asserting the
 groups, so we stop honouring them.
 #### Getting a blocked user back in
 1. App registration → **Token configuration** (or the manifest) → set
   `groupMembershipClaims` to **`ApplicationGroup`** — the portal labels this
   **"Groups assigned to the application"**. It emits only the groups
   explicitly assigned to *this* application, which for a memory server is a
   handful, so the 200-group ceiling stops being reachable. Microsoft
   recommends it for exactly this reason, and it is the same setting
   `cloud_displayname` requires — §10a and §10b have one shared fix.
 2. Enterprise applications → your app → **Users and groups** → assign the
   groups you actually share projects with. `ApplicationGroup` emits **directly
   assigned groups only**; nested and transitive membership is excluded, so
   assign the real groups rather than a parent.
 3. Confirm the `groups` optional claim is configured for the **access token**,
   not only the ID token — the MCP path reads the access token.
 4. The user signs in again. Their memberships were never deleted, so their
   access returns as it was.
 Leaving `groupMembershipClaims` at `All` or `SecurityGroup` in a large tenant is
 what makes this bite in the first place.
 If a group genuinely must exceed the limit, the other way out is **app roles**,
 which are app-scoped and never overage — but they arrive in a `roles` claim and
 this codebase reads `groups`, so that is a code change, not a config change.
 ---
 ## 11. Connecting Claude Code
 Everything in README → **Connecting Claude Code** applies unchanged, with one
 Entra-specific confirmation: **the pre-registered client-id path is
 mandatory.**
 Entra does not implement RFC 7591 Dynamic Client Registration. Its discovery
 document publishes no `registration_endpoint`, it serves no RFC 8414
 authorization-server metadata at all (only OIDC discovery), and it does not
 advertise `client_id_metadata_document_supported` — so neither DCR nor the CIMD
 mechanism that superseded it in the MCP spec is available. Microsoft states this
 plainly in its own MCP guidance ("Microsoft Entra ID doesn't currently support
 client registration") and has said it is not on the near-term roadmap.
 Practically, this means:
 - Use the plugin (`plugin/.mcp.json` ships a pre-registered `clientId`), or
 - Pass `--client-id <OIDC_CLIENT_ID_MCP>` explicitly on `claude mcp add`.
 A client that expects to self-register will fail. This is the same situation as
 Authentik, so the README's guidance needs no adjustment.
 ---
 ## 12. Env var reference card
 Straight from Entra's UI labels to `.env` keys. `<A>` is app registration A
 (Web UI, §3); `<B>` is app registration B (MCP resource server, §4).
 | `.env` key | Where it comes from in Entra | Example |
 |---|---|---|
 | `OIDC_ISSUER` | `issuer` from the **tenant-specific** discovery document (§2). Not the authority you typed — the value the endpoint returns. | `https://login.microsoftonline.com/<tenant-id>/v2.0` |
 | `OIDC_ISSUER_MCP` | **Leave unset.** Entra has one issuer per tenant; there is no per-application issuer to point at. `mcpIssuer()` falls back to `OIDC_ISSUER`. | *(unset)* |
 | `OIDC_CLIENT_ID_WEB` | `<A>` → **Overview → Application (client) ID** | `1111…-aaaa` |
 | `OIDC_CLIENT_SECRET_WEB` | `<A>` → **Certificates & secrets → Client secrets → Value** (not Secret ID; shown once) | `abc8Q~…` |
 | `OIDC_CLIENT_ID_MCP` | Client ID of the **public PKCE** registration Claude Code authenticates as (§4c) | `3333…-cccc` |
 | `OIDC_AUDIENCE` | `<B>` → **Overview → Application (client) ID**. The bare GUID, *not* the `api://` URI. Confirm by decoding a token (§8). | `2222…-bbbb` |
 | `OIDC_AUDIENCE_SCOPE` | `<B>` → **Expose an API** → the scope's full string: Application ID URI + `/` + scope name. Must be set explicitly; the `aud-…` default is Authentik-only. | `api://2222…-bbbb/access_as_user` |
 | `OIDC_OFFLINE_ACCESS` | Nothing to configure in Entra — set it to `true` (§6). | `true` |
 `PUBLIC_URL` and the non-OIDC vars are unchanged from the README.
 ---
 ## 13. Multitenant is not supported
 `acceptedIssuers()` in `apps/web/lib/auth/jwt.ts` compares `iss` against a
 fixed pair of strings (with and without a trailing slash). Multitenant Entra
 apps require substituting each token's `tid` claim into the `{tenantid}`
 placeholder before comparing, and separately validating the signing key's own
 issuer. Neither is implemented.
 Beyond `iss`, multitenant would also need the identity keying in §7 resolved,
 since Microsoft is explicit that `oid` and `sub` differ per tenant by design and
 that a guest user authenticating in another tenant *"should be treated as if
 they're a brand new user to the service."*
 Single-tenant is the supported configuration.
@@ -72,6 +72,16 @@ The redirect URI you register on the Web UI client is
 `https://${domain_name}/api/auth/callback/oidc`, so plan the domain name
 *before* configuring the IdP.
 The MCP client needs its own list, and most of it does not depend on the
 domain: a loopback URI for the Claude Code CLI, plus
 `https://claude.ai/api/mcp/auth_callback` if anyone will add the server as a
 claude.ai custom connector. Only the manual-paste fallback,
 `https://${domain_name}/auth/cli-callback`, follows the domain. See
 [Which redirect URIs to register](../README.md#which-redirect-uris-to-register)
 — a client can only register its own redirect URI against an IdP that offers
 Dynamic Client Registration, which Authentik gates behind an enterprise
 licence, so plan on adding all of these by hand.
 ---
 ## Quick start
Author	SHA1	Message	Date
jknapp	87475e60d0	Merge pull request 'fix: serve RFC 9728 path-suffixed metadata, document connector redirect URIs' (#26 ) from fix/oauth-redirect-uris-and-rfc9728-discovery into main	2026-09-16 23:33:06 +00:00
shadowdaoandClaude Opus 5	3be9135aee	docs: correct the segment-decoding comment on the catch-all route Review caught the stated invariant being false. Next splits the matched suffix on literal `/` before decoding each piece, so a segment can be empty (`api//mcp`) and a single segment can carry a decoded slash (`api%2Fmcp`). Neither reaches the allowlist — both fail closed — but the comment claimed an invariant the router does not provide. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-09-16 16:32:46 -07:00
shadowdaoandClaude Opus 5	f46f54d50b	docs: quote the loopback regex actually deployed on the provider The pattern in the walkthrough was written from memory and differs from the one on the `shared-memory-mcp` provider in a way that matters: `…:[0-9]+/.` requires a path component, so it fails to match a bare `http://localhost:5693`, which the deployed `…:\d+(/.)?$` accepts. Copy the live value verbatim instead. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-09-16 16:11:08 -07:00
shadowdaoandClaude Opus 5	29f5673eac	fix: serve RFC 9728 path-suffixed metadata, document connector redirect URIs Two separate discovery footguns, both found while debugging an Authentik "Redirect URI Error" on a claude.ai custom connector. RFC 9728 §3.1 puts the metadata for a resource identified by `https://host/api/mcp` at `/.well-known/oauth-protected-resource/api/mcp`. Only the root form was served, so clients that derive the metadata URL from the MCP endpoint URL — rather than reading `resource_metadata` off our 401 — got Next.js's HTML 404 and failed discovery with a JSON parse error. Add a `[...path]` route serving the same document with `resource` naming the suffixed identifier (§3.3 has the client compare it as an exact string, so echoing the bare origin would be rejected). The document body moves to `lib/auth/resource-metadata.ts` so the two routes cannot drift apart on `scopes_supported` — a divergence there costs you the `aud` claim or the refresh token. Paths are allowlisted rather than wildcarded so this cannot advertise resources the app does not serve. `buildWwwAuthenticate()` still points at the root URL; this change is purely additive. Separately, the redirect URIs an MCP provider needs depend on how clients reach it: a loopback URI for the CLI, `https://claude.ai/api/mcp/auth_callback` for a claude.ai custom connector. Registering only the former is what produces the "Redirect URI Error" page, and a portless `http://localhost/callback` entry matches nothing the CLI sends. Document both, keyed on the literal error text, and note that DCR is enterprise-gated on Authentik so these are hand-registered on a FOSS instance. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-09-16 16:08:06 -07:00
jknapp	c68d72857f	Merge pull request 'docs: note that Entra keys identity on oid, not sub' (#25 ) from docs/identity-keying-note into main	2026-08-13 02:40:44 +00:00
shadowdaoandClaude Opus 5	391d8e0360	docs: note that Entra keys identity on oid, not sub The Architecture section still described identity as keyed on `sub` + `iss`, which stopped being universally true when 0005_user_oid.sql landed. It is still correct for Authentik, Keycloak and Okta — but on Entra, `sub` is pairwise per app registration and `oid` is the key. Someone reading only this section would draw exactly the wrong conclusion about why a second account appeared. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-12 19:40:31 -07:00
jknapp	bd7a1ca59a	Merge pull request 'feat: adopt the rebalanced mark and add a wordmark lockup' (#24 ) from feat/rebalanced-mark-and-lockup into main	2026-08-13 01:46:31 +00:00
jknapp	a3f28c52a5	Merge pull request 'feat: support Microsoft Entra ID as an OIDC provider' (#22 ) from feat/entra-id-support into main	2026-08-13 01:46:29 +00:00
shadowdaoandClaude Opus 5	5d06095883	feat: adopt the rebalanced mark and add a wordmark lockup The shipped mark failed the one size it most needed to survive. At 16px in a browser tab its outer strokes rasterised away entirely and the 2.5px gap between stroke and node filled in, so the favicon rendered as an indeterminate horizontal smear rather than as anything. Three changes fix it, all driven by that case and verified by rendering rather than by reasoning: strokes stop at x=30 so the gap survives, outer opacity goes .45/.55 -> .7 so the neighbours stay visible, and the node grows to r=8.5 so it still reads as a disc. This is not a rebrand. The mark is the same three-signals-converging figure and keeps whatever recognition it has earned; only its proportions changed. icon.svg and logo.svg had drifted slightly apart (different node radii and stroke ends) and are now geometrically identical, differing only in palette. Adds the lockup, which had no asset at all, in two variants because one cannot serve both jobs: public/lockup.svg uses currentColor for in-app use, and docs/assets/lockup.svg fixes the colour to #0092fd for the README. An <img src> reference resolves currentColor to black, so the currentColor variant would be invisible against a dark README. The wordmark carries textLength, without which it overruns the viewBox on wider monospace fonts. Concepts and the reasoning behind the ones not chosen are on the docs/logo-concepts branch. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-12 14:09:56 -07:00
shadowdaoandClaude Opus 5	4d6694620a	docs: add the Entra ID provider walkthrough The README's OIDC section is written against Authentik and stays that way; Entra differs enough that inlining it would have doubled a file that is already 32k. The new doc parallels the README's A/B structure so the two are diffable, and leads with the traps, since every one of them surfaces as an opaque 401 rather than as anything resembling its cause: the access token version, the tenant-specific authority, `aud` being the client-ID GUID while the requested scope is an `api://` URI, redirect-URI platform types, and group GUIDs. Sections 7 and 10b document the identity and overage behaviour shipped in the previous commit, including the one upgrade-ordering caveat: an existing Entra deployment should sign a user into the Web UI once before reconnecting their MCP client, or the pre-migration row is stranded. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-12 10:51:39 -07:00
shadowdaoandClaude Opus 5	bbea0f74f3	feat: support Microsoft Entra ID as an OIDC provider Three defects stood between this codebase and a working Entra deployment. All three fail silently, which is why they are grouped: each one masks the next, and fixing any two still leaves a broken or dangerous install. 1. JWKS discovery. The key set URL was hardcoded to `${issuer}/jwks/`, which is Authentik's convention, not a standard. Entra serves keys at `/{tenant}/discovery/v2.0/keys`, so every Entra-issued MCP token failed verification on a 404 — authentication was impossible, not merely misconfigured. We now read `jwks_uri` from the issuer's discovery document and fall back to the old path, so Authentik is untouched. Discovery failure arms a 60s retry rather than pinning the wrong URL for the life of the container. 2. Identity. Entra's `sub` is pairwise — derived from the token recipient — so the Web UI and MCP app registrations emit different `sub` values for the same human. Keyed on (iss, sub), that person got two rows: sign into the Web UI, connect Claude Code, land in an empty account. Both paths upsert, so nothing errored. Identity now keys on `oid`, which Microsoft documents as constant across applications in a tenant, via one resolver both surfaces share. Rows created before the 0005 migration adopt their `oid` on next sign-in. 3. Groups overage. Past 200 groups Entra omits `groups` entirely and substitutes a `_claim_names` pointer. `normalizeGroupsClaim` read that as "zero groups" and the sync deleted every membership the user had, revoking access to every shared project on both surfaces with no error raised. Both surfaces now refuse such a token instead — the Web UI fails the sign-in, MCP returns 401 — leaving memberships intact and naming the operator fix. An absent claim with no overage marker still clears memberships, which is unchanged and deliberate. Verified against a real pgvector instance: 66 tests pass, and reverting either new behaviour fails exactly the tests that cover it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-12 10:51:29 -07:00