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/lib/auth/jwt.ts

@@ -40,6 +40,14 @@ function jwks() {
 export interface AuthenticatedClaims extends JWTPayload {
   sub: string;
   iss: string;
+  /**
+   * Group names from the OIDC `groups` claim. Authentik / Keycloak / properly-
+   * configured EntraID emit `string[]` here. We coerce non-array / non-string
+   * entries away and present an empty array if the claim is absent. For CLI
+   * (HMAC) tokens this is always undefined — the consumer (userContextFromClaims)
+   * falls back to the DB snapshot from the user's last interactive sign-in.
+   */
+  groups?: string[];
 }
 
 export class UnauthorizedError extends Error {
@@ -52,6 +60,23 @@ export class UnauthorizedError extends Error {
   }
 }
 
+/**
+ * Pull `groups` off a verified OIDC payload as a clean `string[]`. Non-
+ * string entries are dropped silently. Returns undefined when the claim
+ * is absent so callers can distinguish "no claim emitted" from "user is
+ * in zero groups" (`[]`).
+ */
+function extractGroupsClaim(payload: JWTPayload): string[] | undefined {
+  const raw = (payload as { groups?: unknown }).groups;
+  if (raw === undefined || raw === null) return undefined;
+  if (!Array.isArray(raw)) return [];
+  const out: string[] = [];
+  for (const v of raw) {
+    if (typeof v === "string" && v.trim().length > 0) out.push(v.trim());
+  }
+  return out;
+}
+
 function buildWwwAuthenticate(error?: string, description?: string): string {
   const parts: string[] = [`Bearer realm="OAuth"`];
   // RFC 9728 — point clients at our protected-resource metadata so they can
@@ -82,7 +107,9 @@ export async function authenticateBearer(authHeader: string | null): Promise<Aut
       const claims = await verifyCliToken(token);
       // CLI tokens carry the user's real Authentik identity in oidc_iss /
       // oidc_sub. Surface those on the standard claims shape so user
-      // context resolution is identical to the Authentik path.
+      // context resolution is identical to the Authentik path. CLI tokens
+      // never carry a groups claim — leave `groups` undefined; the user-
+      // context resolver falls back to the DB snapshot.
       return {
         ...claims,
         iss: claims.oidc_iss,
@@ -100,7 +127,7 @@ export async function authenticateBearer(authHeader: string | null): Promise<Aut
         buildWwwAuthenticate("invalid_token", "missing sub"),
       );
     }
-    return payload as AuthenticatedClaims;
+    return { ...payload, groups: extractGroupsClaim(payload) } as AuthenticatedClaims;
   } catch (err) {
     if (err instanceof UnauthorizedError) throw err;
     const desc =

apps/web/lib/auth/sync-groups.ts

@@ -0,0 +1,93 @@
+import { and, eq, notInArray, sql } from "drizzle-orm";
+import { db } from "@/lib/db/client";
+import { groups, userGroups } from "@/lib/db/schema";
+
+/**
+ * Sync a user's group memberships from the OIDC `groups` claim on sign-in.
+ *
+ * Claim shape: `string[]`. Authentik emits group *names* directly here;
+ * Keycloak and Okta likewise (with the right mappers configured). EntraID,
+ * when correctly configured per README, emits names too — but the default
+ * "groups" optional-claim variant emits object-id GUIDs instead, and if the
+ * user is in too many groups EntraID switches to a "groups overage"
+ * 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 overage (where EntraID emits `_claim_names.groups` instead of
+ *     `groups`) is not handled in v1 — the user appears as having no
+ *     groups. Documented limit; revisit if it bites someone.
+ *
+ * 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).
+ */
+export async function syncUserGroupsFromClaim(
+  userId: string,
+  oidcIss: string,
+  rawClaim: unknown,
+): Promise<void> {
+  const names = normalizeGroupsClaim(rawClaim);
+
+  await db.transaction(async (tx) => {
+    if (names.length === 0) {
+      // Claim missing/empty → user has zero groups now.
+      await tx.delete(userGroups).where(eq(userGroups.userId, userId));
+      return;
+    }
+
+    // Upsert each group row keyed by (oidc_iss, name) and collect ids.
+    // We use a single multi-row insert for the round-trip win; the DB
+    // resolves duplicates via the unique index.
+    const inserted = await tx
+      .insert(groups)
+      .values(names.map((name) => ({ oidcIss, name })))
+      .onConflictDoUpdate({
+        target: [groups.oidcIss, groups.name],
+        // Touch updated_at so we have a "last seen" signal at the group
+        // level too; otherwise this would be a do-nothing on conflict.
+        set: { updatedAt: new Date() },
+      })
+      .returning({ id: groups.id, name: groups.name });
+
+    const groupIds = inserted.map((g) => g.id);
+
+    // Insert (or refresh synced_at on) every current membership.
+    await tx
+      .insert(userGroups)
+      .values(groupIds.map((groupId) => ({ userId, groupId })))
+      .onConflictDoUpdate({
+        target: [userGroups.userId, userGroups.groupId],
+        set: { syncedAt: sql`now()` },
+      });
+
+    // Delete memberships that no longer appear in the claim. We could
+    // alternatively rely on `synced_at < now()` to find stale rows, but
+    // an explicit NOT IN is cheaper and clearer.
+    await tx
+      .delete(userGroups)
+      .where(
+        and(eq(userGroups.userId, userId), notInArray(userGroups.groupId, groupIds)),
+      );
+  });
+}
+
+/**
+ * Coerce whatever the IdP put in `profile.groups` into a clean string[]
+ * of distinct, trimmed, non-empty names. Anything non-string is dropped.
+ */
+function normalizeGroupsClaim(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  const out = new Set<string>();
+  for (const v of raw) {
+    if (typeof v !== "string") continue;
+    const t = v.trim();
+    if (t.length === 0) continue;
+    out.add(t);
+  }
+  return Array.from(out);
+}
+

apps/web/lib/db/schema.ts

@@ -7,6 +7,7 @@ import {
   jsonb,
   uniqueIndex,
   index,
+  primaryKey,
   customType,
   vector,
   varchar,
@@ -37,6 +38,10 @@ const textArray = customType<{ data: string[]; driverData: string }>({
 export const memoryScope = pgEnum("memory_scope", ["project", "user"]);
 export const memoryVisibility = pgEnum("memory_visibility", ["private", "shared", "team"]);
 export const auditActor = pgEnum("audit_actor", ["mcp", "web", "system"]);
+// Reserved here so 0003 (this file's matching migration) owns it. Used
+// by Agent B's upcoming `project_shares` table to express RO vs RW
+// grants per shared group.
+export const memoryAccess = pgEnum("memory_access", ["ro", "rw"]);
 
 // ---------- tables ----------
 
@@ -152,6 +157,43 @@ export const cliTokens = pgTable(
   }),
 );
 
+export const groups = pgTable(
+  "groups",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    // OIDC issuer this group originates from — pairs with `name` so two
+    // IdPs can both have a "platform" group without collision.
+    oidcIss: text("oidc_iss").notNull(),
+    name: text("name").notNull(),
+    // Optional human-friendly label. Most IdPs only emit names, so this
+    // is usually NULL; reserved for future enrichment.
+    displayName: text("display_name"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    uniqueIssName: uniqueIndex("groups_iss_name_uq").on(t.oidcIss, t.name),
+  }),
+);
+
+export const userGroups = pgTable(
+  "user_groups",
+  {
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    groupId: uuid("group_id")
+      .notNull()
+      .references(() => groups.id, { onDelete: "cascade" }),
+    // Refreshed on every sign-in that re-observes this membership.
+    syncedAt: timestamp("synced_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.userId, t.groupId] }),
+    userIdx: index("user_groups_user_idx").on(t.userId),
+  }),
+);
+
 export const auditLog = pgTable(
   "audit_log",
   {
@@ -188,3 +230,7 @@ export type CliToken = typeof cliTokens.$inferSelect;
 export type NewCliToken = typeof cliTokens.$inferInsert;
 export type AuditEntry = typeof auditLog.$inferSelect;
 export type NewAuditEntry = typeof auditLog.$inferInsert;
+export type Group = typeof groups.$inferSelect;
+export type NewGroup = typeof groups.$inferInsert;
+export type UserGroup = typeof userGroups.$inferSelect;
+export type NewUserGroup = typeof userGroups.$inferInsert;

apps/web/lib/mcp/context.ts

@@ -1,28 +1,50 @@
 import { db } from "@/lib/db/client";
-import { users } from "@/lib/db/schema";
+import { users, groups, userGroups } from "@/lib/db/schema";
 import { and, eq } from "drizzle-orm";
 import type { AuthenticatedClaims } from "@/lib/auth/jwt";
 
 /**
  * Per-request user context for MCP tool handlers.
  *
- * Resolves (or creates) the internal `users` row from the Authentik OIDC
- * claims so tools work with stable UUID foreign keys rather than raw `sub`
- * strings.
+ * Resolves (or creates) the internal `users` row from the OIDC claims so
+ * tools work with stable UUID foreign keys rather than raw `sub` strings.
  */
 export interface UserContext {
   /** Internal users.id UUID. */
   userId: string;
-  /** OIDC sub claim (stable identifier from Authentik). */
+  /** OIDC sub claim (stable identifier from the IdP). */
   sub: string;
   /** OIDC issuer. */
   iss: string;
   /** Optional profile fields if present in the access token. */
   email: string | null;
   name: string | null;
+  /**
+   * Group *names* the user is a member of. For OIDC bearer tokens these are
+   * the live values from the verified token's `groups` claim. For CLI tokens
+   * (which carry no groups claim), this is the DB snapshot from the user's
+   * last interactive sign-in — necessarily stale, but the only signal we
+   * have without going back to the IdP.
+   */
+  groups: string[];
+  /**
+   * Project key supplied via the `X-Project-Key` request header. Tools that
+   * accept an optional `project` argument use this as a fallback when the
+   * caller didn't pass one explicitly. Always validated upstream against
+   * the same Zod schema as the tool argument.
+   */
+  defaultProjectKey?: string;
 }
 
-export async function userContextFromClaims(claims: AuthenticatedClaims): Promise<UserContext> {
+export interface UserContextOverrides {
+  /** Project key from the X-Project-Key request header (already validated). */
+  defaultProjectKey?: string;
+}
+
+export async function userContextFromClaims(
+  claims: AuthenticatedClaims,
+  overrides: UserContextOverrides = {},
+): Promise<UserContext> {
   const email = (claims.email as string | undefined) ?? null;
   const name = (claims.name as string | undefined) ?? null;
   const picture = (claims.picture as string | undefined) ?? null;
@@ -47,7 +69,7 @@ export async function userContextFromClaims(claims: AuthenticatedClaims): Promis
     })
     .returning({ id: users.id });
 
-  const userId = row[0]?.id;
+  let userId = row[0]?.id;
   if (!userId) {
     // Race against another upsert — fall back to a select.
     const existing = await db
@@ -56,8 +78,32 @@ export async function userContextFromClaims(claims: AuthenticatedClaims): Promis
       .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");
-    return { userId: existing[0].id, sub: claims.sub, iss: claims.iss, email, name };
+    userId = existing[0].id;
   }
 
-  return { userId, sub: claims.sub, iss: claims.iss, email, name };
+  // OIDC bearer tokens carry a `groups` claim (when the IdP is configured to
+  // emit it). CLI tokens never do — they go through verifyCliToken which
+  // doesn't set claims.groups. In that case fall back to the DB snapshot
+  // from the user's last interactive sign-in.
+  const groupNames =
+    claims.groups ?? (await loadUserGroups(userId));
+
+  return {
+    userId,
+    sub: claims.sub,
+    iss: claims.iss,
+    email,
+    name,
+    groups: groupNames,
+    defaultProjectKey: overrides.defaultProjectKey,
+  };
+}
+
+async function loadUserGroups(userId: string): 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);
 }

apps/web/lib/mcp/tools.ts

@@ -73,6 +73,42 @@ async function resolveProjectId(
   return row[0]?.id ?? null;
 }
 
+/**
+ * If the args object has no explicit `project` key, inject the request-
+ * scoped `defaultProjectKey` from the `X-Project-Key` header (when set).
+ * This lets a client pin every call to one project without restating it
+ * per tool invocation. Returns a new object — the original is untouched.
+ *
+ * The injection rule is: inject when the caller plausibly intends a
+ * project scope. Concretely we inject when EITHER:
+ *
+ *   * `scope` is explicitly `'project'`, OR
+ *   * `scope` is omitted AND the tool's natural default IS project-scope
+ *     (memory.write defaults to project; snippet.put defaults to user).
+ *
+ * We never inject when `scope === 'user'` is explicit — the schemas refine
+ * `(scope='user', project=<anything>)` as invalid. An explicit `project`
+ * argument always wins and we never overwrite it.
+ *
+ * `defaultScope` is the tool's own default (e.g. 'project' for memory.*,
+ * 'user' for snippet.*). For filter tools that have no scope default
+ * (memory.list, memory.search, snippet.list), pass 'project' — those
+ * cases treat the header as a project filter and benefit from injection.
+ */
+function withDefaultProject(
+  args: unknown,
+  ctx: UserContext,
+  defaultScope: "project" | "user" = "project",
+): unknown {
+  if (!ctx.defaultProjectKey) return args;
+  if (args === null || typeof args !== "object" || Array.isArray(args)) return args;
+  const obj = args as Record<string, unknown>;
+  if (obj.project !== undefined) return args;
+  if (obj.scope === "user") return args;
+  if (obj.scope === undefined && defaultScope === "user") return args;
+  return { ...obj, project: ctx.defaultProjectKey };
+}
+
 // ---------- tools ----------
 
 const projectIdentify: ToolDef = {
@@ -150,7 +186,7 @@ const memoryWrite: ToolDef = {
     required: ["content"],
   },
   async handler(args, ctx) {
-    const parsed = MemoryWriteInput.safeParse(args);
+    const parsed = MemoryWriteInput.safeParse(withDefaultProject(args, ctx));
     if (!parsed.success) return err(parsed.error.message);
 
     const scope = parsed.data.scope;
@@ -213,7 +249,7 @@ const memoryList: ToolDef = {
     },
   },
   async handler(args, ctx) {
-    const parsed = MemoryListInput.safeParse(args);
+    const parsed = MemoryListInput.safeParse(withDefaultProject(args, ctx));
     if (!parsed.success) return err(parsed.error.message);
 
     const where = [eq(memories.userId, ctx.userId), isNull(memories.deletedAt)];
@@ -343,7 +379,7 @@ const memoryUpdate: ToolDef = {
     required: ["id"],
   },
   async handler(args, ctx) {
-    const parsed = MemoryUpdateInput.safeParse(args);
+    const parsed = MemoryUpdateInput.safeParse(withDefaultProject(args, ctx));
     if (!parsed.success) return err(parsed.error.message);
 
     const existingRows = await db
@@ -456,7 +492,7 @@ const memorySearch: ToolDef = {
     required: ["query"],
   },
   async handler(args, ctx) {
-    const parsed = MemorySearchInput.safeParse(args);
+    const parsed = MemorySearchInput.safeParse(withDefaultProject(args, ctx));
     if (!parsed.success) return err(parsed.error.message);
 
     const { query, scope, tags, limit } = parsed.data;
@@ -549,7 +585,9 @@ const snippetPut: ToolDef = {
     required: ["name", "body"],
   },
   async handler(args, ctx) {
-    const parsed = SnippetPutInput.safeParse(args);
+    // snippet.put defaults to user-scope, so a header-supplied project key
+    // is only honored when the caller explicitly says `scope='project'`.
+    const parsed = SnippetPutInput.safeParse(withDefaultProject(args, ctx, "user"));
     if (!parsed.success) return err(parsed.error.message);
 
     if (parsed.data.scope === "project") {
@@ -620,7 +658,7 @@ const snippetGet: ToolDef = {
     required: ["name"],
   },
   async handler(args, ctx) {
-    const parsed = SnippetGetInput.safeParse(args);
+    const parsed = SnippetGetInput.safeParse(withDefaultProject(args, ctx));
     if (!parsed.success) return err(parsed.error.message);
 
     const snippet = await getSnippet(ctx.userId, {
@@ -669,7 +707,7 @@ const snippetList: ToolDef = {
     },
   },
   async handler(args, ctx) {
-    const parsed = SnippetListInput.safeParse(args);
+    const parsed = SnippetListInput.safeParse(withDefaultProject(args, ctx));
     if (!parsed.success) return err(parsed.error.message);
 
     const rows = await listSnippets(ctx.userId, {
@@ -708,7 +746,7 @@ const snippetDelete: ToolDef = {
     required: ["name"],
   },
   async handler(args, ctx) {
-    const parsed = SnippetDeleteInput.safeParse(args);
+    const parsed = SnippetDeleteInput.safeParse(withDefaultProject(args, ctx));
     if (!parsed.success) return err(parsed.error.message);
 
     const deleted = await softDeleteSnippet(ctx.userId, {

apps/web/lib/memory-actions.ts

@@ -7,6 +7,7 @@ import { auth } from "@/auth";
 import { db } from "@/lib/db/client";
 import { memories, projects, auditLog } from "@/lib/db/schema";
 import { embedText } from "@/lib/embedder";
+import { upsertProject } from "@/lib/projects";
 import {
   MemoryWriteInput,
   MemoryUpdateInput,
@@ -27,29 +28,6 @@ async function requireUserId(): Promise<string> {
   return session.user.id;
 }
 
-async function resolveProjectId(userId: string, key: string): Promise<string | null> {
-  const row = await db
-    .select({ id: projects.id })
-    .from(projects)
-    .where(and(eq(projects.userId, userId), eq(projects.key, key)))
-    .limit(1);
-  return row[0]?.id ?? null;
-}
-
-async function upsertProject(
-  userId: string,
-  key: string,
-  displayName?: string,
-): Promise<string> {
-  const existing = await resolveProjectId(userId, key);
-  if (existing) return existing;
-  const row = await db
-    .insert(projects)
-    .values({ userId, key, displayName: displayName ?? null })
-    .returning({ id: projects.id });
-  return row[0]!.id;
-}
-
 function parseTags(raw: FormDataEntryValue | null): string[] {
   if (typeof raw !== "string") return [];
   return raw

apps/web/lib/projects.ts

@@ -0,0 +1,43 @@
+import { and, eq } from "drizzle-orm";
+import { db } from "@/lib/db/client";
+import { projects } from "@/lib/db/schema";
+
+/**
+ * Look up a project id by (user, key). Returns null when not found.
+ * No write side-effects.
+ */
+export async function resolveProjectId(
+  userId: string,
+  key: string,
+): Promise<string | null> {
+  const row = await db
+    .select({ id: projects.id })
+    .from(projects)
+    .where(and(eq(projects.userId, userId), eq(projects.key, key)))
+    .limit(1);
+  return row[0]?.id ?? null;
+}
+
+/**
+ * Idempotent project creation. Returns the existing row's id when one
+ * exists, otherwise inserts and returns the new id. Tolerates concurrent
+ * inserts via ON CONFLICT — two simultaneous calls converge on one row.
+ */
+export async function upsertProject(
+  userId: string,
+  key: string,
+  displayName?: string,
+): Promise<string> {
+  const existing = await resolveProjectId(userId, key);
+  if (existing) return existing;
+  const row = await db
+    .insert(projects)
+    .values({ userId, key, displayName: displayName ?? null })
+    .onConflictDoNothing({ target: [projects.userId, projects.key] })
+    .returning({ id: projects.id });
+  if (row[0]) return row[0].id;
+  // ON CONFLICT DO NOTHING returns no rows on conflict — re-read.
+  const reread = await resolveProjectId(userId, key);
+  if (!reread) throw new Error("project upsert raced and re-read still empty");
+  return reread;
+}