feat(phase-4a): groups sync + X-Project-Key header substrate

Foundational work for the upcoming group-scoped sharing feature.

Schema (migration 0003_groups.sql + drizzle schema):
  - memory_access enum ('ro' | 'rw') reserved for Agent B's project_shares
  - groups (id, oidc_iss, name, display_name, …) keyed by (oidc_iss, name)
    so different IdPs can both have e.g. "platform" without colliding
  - user_groups (user_id, group_id, synced_at) PK (user_id, group_id)

Auth (auth.ts + lib/auth/sync-groups.ts):
  - jwt callback now syncs `profile.groups` after upserting the user
  - syncUserGroupsFromClaim runs in a single tx: upserts each group,
    inserts new memberships, deletes ones no longer in the claim
  - missing/empty claim → user has zero groups (wipe memberships)
  - EntraID GUID-vs-name edge case: we treat whatever strings the claim
    emits as names verbatim; groups overage (>200 groups → no claim)
    is documented as unsupported in v1

UserContext + JWT (lib/mcp/context.ts, lib/auth/jwt.ts):
  - AuthenticatedClaims.groups surfaced from verified JWT payload
  - UserContext.groups: string[] — live from OIDC token claim, falls
    back to DB snapshot for CLI (HMAC) tokens which carry no claim
  - UserContext.defaultProjectKey: optional, set from header

MCP route (app/api/mcp/route.ts):
  - reads X-Project-Key header, validates against ProjectKey Zod schema,
    400 on invalid; empty/missing leaves defaultProjectKey undefined
  - auto-upserts the header-supplied project so first-use works without
    a separate project.identify call

Tools (lib/mcp/tools.ts):
  - withDefaultProject helper injects ctx.defaultProjectKey when the
    caller omits `project`. Per-tool defaultScope hint avoids breaking
    snippet.put (user-scope default) while making memory.write
    (project-scope default) honor the header
  - applied to memory.write/list/search/update and all snippet.* tools

Web UI:
  - /settings/groups debug page lists current memberships with synced_at
    and a clear empty state pointing at README troubleshooting
  - /settings/tokens grows a "Pin to project" dropdown; selected key is
    baked into the generated `claude mcp add` snippet as
    `--header "X-Project-Key: <key>"`. The JWT itself stays
    identity-only — pinning is purely a UX shortcut
  - settings landing page links to /settings/groups
  - README troubleshooting bullet covers the empty-groups path for
    Authentik / EntraID / Keycloak

Refactor:
  - extracted resolveProjectId + upsertProject from memory-actions.ts
    into lib/projects.ts so the MCP route can reuse upsertProject

Verification:
  - pnpm typecheck clean
  - SKIP_ENV_VALIDATION=true pnpm build clean; /settings/groups in route table

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

apps/web/app/(authed)/settings/groups/page.tsx

@@ -0,0 +1,80 @@
+import Link from "next/link";
+import { eq } from "drizzle-orm";
+import { auth } from "@/auth";
+import { db } from "@/lib/db/client";
+import { groups, userGroups } from "@/lib/db/schema";
+import { Container, PageHeader } from "@/app/_components/ui/container";
+import { Card } from "@/app/_components/ui/card";
+import { EmptyState } from "@/app/_components/ui/empty-state";
+
+export const dynamic = "force-dynamic";
+
+/**
+ * Debug page showing the OIDC groups currently associated with the signed-in
+ * user. The list is rewritten on every sign-in from the IdP's `groups`
+ * claim (see `lib/auth/sync-groups.ts`), so this view is effectively a
+ * snapshot of "what your IdP told us about you at last login".
+ *
+ * Mainly intended as a sanity check for the upcoming sharing feature —
+ * if the user expects to see "platform" and doesn't, the IdP probably
+ * isn't emitting the claim, and the empty state points them at the
+ * README troubleshooting section.
+ */
+export default async function GroupsSettingsPage() {
+  const session = await auth();
+  const userId = session!.user.id;
+
+  const rows = await db
+    .select({
+      id: groups.id,
+      name: groups.name,
+      oidcIss: groups.oidcIss,
+      syncedAt: userGroups.syncedAt,
+    })
+    .from(userGroups)
+    .innerJoin(groups, eq(userGroups.groupId, groups.id))
+    .where(eq(userGroups.userId, userId))
+    .orderBy(groups.name);
+
+  return (
+    <Container className="pt-6 max-w-3xl">
+      <PageHeader
+        title="Groups"
+        description="OIDC groups your identity provider asserted for you at last sign-in. Used by the upcoming sharing feature to decide which projects you can see."
+      />
+
+      {rows.length === 0 ? (
+        <EmptyState
+          title="No groups yet"
+          description="Your IdP isn't emitting a `groups` claim on the access token, or you're not a member of any groups. See the troubleshooting section in the project README for how to configure Authentik / EntraID / Keycloak to emit group memberships."
+        />
+      ) : (
+        <Card>
+          {rows.map((g, i) => (
+            <div
+              key={g.id}
+              className={`px-4 py-3 ${i > 0 ? "border-t border-border" : ""}`}
+            >
+              <div className="flex items-baseline gap-3">
+                <div className="font-mono text-sm text-fg flex-1 truncate">
+                  {g.name}
+                </div>
+                <div className="text-xs text-fg-subtle whitespace-nowrap">
+                  synced {new Date(g.syncedAt).toLocaleString()}
+                </div>
+              </div>
+              <div className="text-xs text-fg-subtle font-mono mt-0.5 truncate">
+                {g.oidcIss}
+              </div>
+            </div>
+          ))}
+        </Card>
+      )}
+
+      <p className="text-xs text-fg-subtle mt-6">
+        Groups refresh on every sign-in. If something looks stale,{" "}
+        <Link href="/api/auth/signout">sign out</Link> and sign back in.
+      </p>
+    </Container>
+  );
+}

apps/web/app/(authed)/settings/page.tsx

@@ -53,6 +53,19 @@ export default async function SettingsPage() {
             and revoke them.
           </CardBody>
         </Card>
+
+        <Card>
+          <CardHeader className="flex items-center">
+            <span className="text-sm font-medium text-fg flex-1">Groups</span>
+            <Link href="/settings/groups" className="no-underline">
+              <Button variant="secondary" size="sm">View groups</Button>
+            </Link>
+          </CardHeader>
+          <CardBody className="text-sm text-fg-muted">
+            OIDC group memberships from your IdP, refreshed at sign-in. Used
+            by the upcoming sharing feature to scope project visibility.
+          </CardBody>
+        </Card>
       </div>
     </Container>
   );

apps/web/app/(authed)/settings/tokens/page.tsx

@@ -1,29 +1,68 @@
 import { revalidatePath } from "next/cache";
-import { and, desc, eq, isNull } from "drizzle-orm";
+import { and, asc, desc, eq, isNull } from "drizzle-orm";
 import { auth } from "@/auth";
 import { db } from "@/lib/db/client";
-import { cliTokens, users } from "@/lib/db/schema";
+import { cliTokens, projects, users } from "@/lib/db/schema";
 import {
   mintCliToken,
   revokeCliToken,
   CLI_TOKEN_TTL_SECONDS,
 } from "@/lib/auth/cli-token";
+import { ProjectKey } from "@shared-memory/schemas";
 import { Container, PageHeader } from "@/app/_components/ui/container";
 import { Card, CardBody, CardHeader } from "@/app/_components/ui/card";
 import { Badge } from "@/app/_components/ui/badge";
 import { EmptyState } from "@/app/_components/ui/empty-state";
-import TokensManager from "./tokens-manager";
+import TokensManager, { type CreateTokenState } from "./tokens-manager";
 
 export const dynamic = "force-dynamic";
 
-async function createTokenAction(_prev: { token: string | null; error: string | null }, formData: FormData): Promise<{ token: string | null; error: string | null }> {
+async function createTokenAction(
+  _prev: CreateTokenState,
+  formData: FormData,
+): Promise<CreateTokenState> {
   "use server";
   try {
     const session = await auth();
-    if (!session?.user?.id) return { token: null, error: "not authenticated" };
+    if (!session?.user?.id) {
+      return { token: null, error: "not authenticated", projectKey: null };
+    }
 
     const name = String(formData.get("name") ?? "").trim() || `Token ${new Date().toISOString().slice(0, 10)}`;
 
+    // Optional pin-to-project. The token JWT itself does NOT need a project
+    // claim — pinning is purely a UX shortcut so the generated `claude mcp
+    // add` snippet bakes in `X-Project-Key: <key>` and every call from
+    // that client lands on the right project by default.
+    const rawProject = String(formData.get("projectKey") ?? "").trim();
+    let projectKey: string | null = null;
+    if (rawProject.length > 0) {
+      const parsed = ProjectKey.safeParse(rawProject);
+      if (!parsed.success) {
+        return {
+          token: null,
+          error: `invalid project key: ${parsed.error.issues.map((i) => i.message).join("; ")}`,
+          projectKey: null,
+        };
+      }
+      // Cross-check the project belongs to this user (defense in depth —
+      // the dropdown is built from the user's projects, but the form is
+      // re-submittable so don't trust the value).
+      const found = await db
+        .select({ key: projects.key })
+        .from(projects)
+        .where(and(eq(projects.userId, session.user.id), eq(projects.key, parsed.data)))
+        .limit(1);
+      if (!found[0]) {
+        return {
+          token: null,
+          error: `unknown project '${parsed.data}'`,
+          projectKey: null,
+        };
+      }
+      projectKey = found[0].key;
+    }
+
     const userRow = await db
       .select({
         oidcIss: users.oidcIss,
@@ -35,7 +74,7 @@ async function createTokenAction(_prev: { token: string | null; error: string |
       .where(eq(users.id, session.user.id))
       .limit(1);
     const u = userRow[0];
-    if (!u) return { token: null, error: "user row not found" };
+    if (!u) return { token: null, error: "user row not found", projectKey: null };
 
     const minted = await mintCliToken(
       {
@@ -49,9 +88,13 @@ async function createTokenAction(_prev: { token: string | null; error: string |
     );
 
     revalidatePath("/settings/tokens");
-    return { token: minted.token, error: null };
+    return { token: minted.token, error: null, projectKey };
   } catch (e) {
-    return { token: null, error: e instanceof Error ? e.message : "unknown error" };
+    return {
+      token: null,
+      error: e instanceof Error ? e.message : "unknown error",
+      projectKey: null,
+    };
   }
 }
 
@@ -68,19 +111,29 @@ export default async function TokensPage() {
   const session = await auth();
   const userId = session!.user.id;
 
-  const tokens = await db
-    .select({
-      id: cliTokens.id,
-      name: cliTokens.name,
-      jti: cliTokens.jti,
-      createdAt: cliTokens.createdAt,
-      lastUsedAt: cliTokens.lastUsedAt,
-      expiresAt: cliTokens.expiresAt,
-      revokedAt: cliTokens.revokedAt,
-    })
-    .from(cliTokens)
-    .where(eq(cliTokens.userId, userId))
-    .orderBy(desc(cliTokens.createdAt));
+  const [tokens, projectRows] = await Promise.all([
+    db
+      .select({
+        id: cliTokens.id,
+        name: cliTokens.name,
+        jti: cliTokens.jti,
+        createdAt: cliTokens.createdAt,
+        lastUsedAt: cliTokens.lastUsedAt,
+        expiresAt: cliTokens.expiresAt,
+        revokedAt: cliTokens.revokedAt,
+      })
+      .from(cliTokens)
+      .where(eq(cliTokens.userId, userId))
+      .orderBy(desc(cliTokens.createdAt)),
+    db
+      .select({
+        key: projects.key,
+        displayName: projects.displayName,
+      })
+      .from(projects)
+      .where(eq(projects.userId, userId))
+      .orderBy(asc(projects.key)),
+  ]);
 
   const active = tokens.filter((t) => !t.revokedAt && t.expiresAt > new Date());
   const inactive = tokens.filter((t) => t.revokedAt || t.expiresAt <= new Date());
@@ -96,7 +149,14 @@ export default async function TokensPage() {
       <Card className="mb-6">
         <CardHeader className="text-sm font-medium text-fg">Generate a new token</CardHeader>
         <CardBody>
-          <TokensManager action={createTokenAction} ttlDays={ttlDays} />
+          <TokensManager
+            action={createTokenAction}
+            ttlDays={ttlDays}
+            projects={projectRows.map((p) => ({
+              key: p.key,
+              displayName: p.displayName,
+            }))}
+          />
         </CardBody>
       </Card>
 

apps/web/app/(authed)/settings/tokens/tokens-manager.tsx

@@ -4,19 +4,35 @@ import { useActionState } from "react";
 import { Button } from "@/app/_components/ui/button";
 import { Input, Label } from "@/app/_components/ui/input";
 
-interface State {
+/**
+ * State returned by the `createTokenAction` server action.
+ *
+ * `projectKey` is the project the user chose to pin the token to. It's NOT
+ * baked into the JWT itself — the token remains identity-only — it just
+ * lets us bake `--header "X-Project-Key: <key>"` into the generated
+ * `claude mcp add` snippet so calls from this client default to that
+ * project without the model having to pass it explicitly.
+ */
+export interface CreateTokenState {
   token: string | null;
   error: string | null;
+  projectKey: string | null;
+}
+
+export interface ProjectOption {
+  key: string;
+  displayName: string | null;
 }
 
 interface Props {
-  action: (prev: State, formData: FormData) => Promise<State>;
+  action: (prev: CreateTokenState, formData: FormData) => Promise<CreateTokenState>;
   ttlDays: number;
+  projects: ProjectOption[];
 }
 
-const initial: State = { token: null, error: null };
+const initial: CreateTokenState = { token: null, error: null, projectKey: null };
 
-export default function TokensManager({ action, ttlDays }: Props) {
+export default function TokensManager({ action, ttlDays, projects }: Props) {
   const [state, formAction, pending] = useActionState(action, initial);
 
   if (state.token) {
@@ -33,12 +49,18 @@ export default function TokensManager({ action, ttlDays }: Props) {
         </pre>
         <details className="text-xs text-fg-muted">
           <summary className="cursor-pointer">claude mcp add command</summary>
-          <pre className="mt-2">{`claude mcp add --transport http --scope user \\
-  --header "Authorization: Bearer ${state.token}" \\
-  shared-memory https://memory.dnspegasus.net/api/mcp`}</pre>
+          <pre className="mt-2">{buildMcpAddSnippet(state.token, state.projectKey)}</pre>
         </details>
         <p className="text-xs text-fg-subtle">
           Valid for {ttlDays} days. Revoke individually below if it leaks.
+          {state.projectKey ? (
+            <>
+              {" "}This token is pinned to project{" "}
+              <code className="font-mono">{state.projectKey}</code> via the{" "}
+              <code className="font-mono">X-Project-Key</code> header in the
+              snippet above — the JWT itself is identity-only.
+            </>
+          ) : null}
         </p>
       </div>
     );
@@ -56,6 +78,10 @@ export default function TokensManager({ action, ttlDays }: Props) {
           autoComplete="off"
         />
       </div>
+      <div className="flex-1 min-w-[200px]">
+        <Label htmlFor="projectKey" hint="optional">Pin to project</Label>
+        <ProjectSelect projects={projects} />
+      </div>
       <Button type="submit" disabled={pending}>
         {pending ? "Generating…" : "Generate token"}
       </Button>
@@ -65,3 +91,43 @@ export default function TokensManager({ action, ttlDays }: Props) {
     </form>
   );
 }
+
+function ProjectSelect({ projects }: { projects: ProjectOption[] }) {
+  // Match Input styling — Tailwind v4 classes from `lib/ui/input.tsx`.
+  const cls =
+    "mt-1 block w-full h-9 px-3 text-sm rounded-md bg-surface-1 " +
+    "border border-border text-fg focus:border-accent-400 focus:outline-none " +
+    "disabled:opacity-50 transition-colors";
+
+  if (projects.length === 0) {
+    return (
+      <select id="projectKey" name="projectKey" className={cls} disabled>
+        <option value="">No projects yet</option>
+      </select>
+    );
+  }
+  return (
+    <select id="projectKey" name="projectKey" defaultValue="" className={cls}>
+      <option value="">(none — token works across all projects)</option>
+      {projects.map((p) => (
+        <option key={p.key} value={p.key}>
+          {p.displayName && p.displayName !== p.key
+            ? `${p.key} — ${p.displayName}`
+            : p.key}
+        </option>
+      ))}
+    </select>
+  );
+}
+
+function buildMcpAddSnippet(token: string, projectKey: string | null): string {
+  const headerLines = [`  --header "Authorization: Bearer ${token}"`];
+  if (projectKey) {
+    headerLines.push(`  --header "X-Project-Key: ${projectKey}"`);
+  }
+  return [
+    "claude mcp add --transport http --scope user \\",
+    ...headerLines.map((l) => `${l} \\`),
+    "  shared-memory https://memory.dnspegasus.net/api/mcp",
+  ].join("\n");
+}

apps/web/app/api/mcp/route.ts

@@ -1,7 +1,9 @@
 import { NextResponse } from "next/server";
+import { ProjectKey } from "@shared-memory/schemas";
 import { authenticateBearer, UnauthorizedError } from "@/lib/auth/jwt";
 import { userContextFromClaims } from "@/lib/mcp/context";
 import { dispatchMcpMessage } from "@/lib/mcp/server";
+import { upsertProject } from "@/lib/projects";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
@@ -49,8 +51,37 @@ export async function POST(req: Request) {
     );
   }
 
+  // ---- optional X-Project-Key header → default project for this request ----
+  // The header lets a client (e.g. a `claude mcp add` snippet generated from
+  // /settings/tokens) pin every call to a specific project without having to
+  // pass `project` on each tool invocation. Tools that take an optional
+  // `project` arg fall back to this when the caller omits it.
+  let defaultProjectKey: string | undefined;
+  const rawProjectKey = req.headers.get("x-project-key");
+  if (rawProjectKey !== null && rawProjectKey !== "") {
+    const parsed = ProjectKey.safeParse(rawProjectKey);
+    if (!parsed.success) {
+      return NextResponse.json(
+        {
+          error: "invalid X-Project-Key",
+          detail: parsed.error.issues.map((i) => i.message).join("; "),
+        },
+        { status: 400 },
+      );
+    }
+    defaultProjectKey = parsed.data;
+  }
+
   // ---- resolve user, dispatch ----
-  const ctx = await userContextFromClaims(claims);
+  const ctx = await userContextFromClaims(claims, { defaultProjectKey });
+
+  // Auto-create the header-supplied project if it doesn't exist yet. This
+  // makes pinning via `X-Project-Key` work transparently — the user doesn't
+  // have to call `project.identify` first when they paste the generated
+  // `claude mcp add` snippet from /settings/tokens.
+  if (defaultProjectKey) {
+    await upsertProject(ctx.userId, defaultProjectKey);
+  }
 
   // MCP supports batched requests (array) and single. Handle both.
   if (Array.isArray(body)) {