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>
2026-05-17 09:39:47 -07:00
parent 5b2bf7d19d
commit 7712023c32
15 changed files with 679 additions and 73 deletions
@@ -373,6 +373,15 @@ The OIDC client you use locally must accept
  testing to avoid hitting the production rate limit.
 - **`pg_isready` healthcheck loops** — check that `POSTGRES_USER` /
  `POSTGRES_PASSWORD` / `POSTGRES_DB` are all set in `.env`.
+- **`/settings/groups` is empty even though I'm in groups** — your IdP isn't
+  emitting a `groups` claim. On Authentik, edit the OIDC provider and add
+  the built-in `authentik default OAuth Mapping: OpenID 'profile'` (or a
+  custom property mapping that returns `{"groups": [g.name for g in
+  request.user.ak_groups.all()]}`), then sign out and back in. On EntraID,
+  add a "groups" optional claim under **Token configuration → Optional
+  claims**; tick "Emit groups as group names" if you want names (we treat
+  GUIDs as opaque strings). Keycloak: add a Group Membership mapper with
+  "Full group path" off and the token claim name `groups`.

 ---

@@ -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>
+  );
+}
@@ -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>
  );
@@ -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>

@@ -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");
+}
@@ -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)) {
@@ -2,6 +2,7 @@ import NextAuth from "next-auth";
 import { env } from "@/lib/env";
 import { db } from "@/lib/db/client";
 import { users } from "@/lib/db/schema";
+import { syncUserGroupsFromClaim } from "@/lib/auth/sync-groups";

 /**
 * NextAuth (Auth.js v5) configuration.
@@ -60,9 +61,21 @@ export const { auth, handlers, signIn, signOut } = NextAuth({
          })
          .returning({ id: users.id });

-        token.userId = row[0]?.id;
+        const userId = row[0]?.id;
+        token.userId = userId;
        token.sub = sub;
        token.iss = iss;
+
+        // Sync group memberships from the OIDC `groups` claim. Missing or
+        // empty claim is treated as "user is in zero groups" — that path
+        // wipes the user's existing memberships, which is the conservative
+        // choice (don't keep stale grants alive if the IdP stopped
+        // asserting them).
+        if (userId) {
+          // `profile.groups` is untyped at the next-auth boundary — coerce.
+          const claimGroups = (profile as { groups?: unknown }).groups;
+          await syncUserGroupsFromClaim(userId, iss, claimGroups);
+        }
      }
      return token;
    },
@@ -0,0 +1,63 @@
+-- Groups + per-user group memberships, plus the `memory_access` enum.
+--
+-- This migration is the substrate for the upcoming group-scoped sharing
+-- feature (project_shares). It owns:
+--
+--   * memory_access enum  — reserved for project_shares to reference.
+--   * groups table        — one row per distinct group seen in any user's
+--                            OIDC `groups` claim, keyed by (oidc_iss, name)
+--                            so different IdPs can both have a group called
+--                            e.g. "platform" without colliding.
+--   * user_groups table   — current group memberships for each user. Synced
+--                            on every sign-in: rows are inserted/deleted to
+--                            mirror the freshly-issued claim, so IdP
+--                            membership changes propagate at next login.
+--
+-- We deliberately do NOT add project_shares here — that's Agent B's 0004.
+-- Defining the enum in 0003 lets 0004 reference it without sequencing
+-- gymnastics.
+
+-- =============================================================================
+-- Enums
+-- =============================================================================
+
+CREATE TYPE "memory_access" AS ENUM ('ro', 'rw');
+
+-- =============================================================================
+-- groups
+-- =============================================================================
+
+CREATE TABLE "groups" (
+  "id"           uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  -- OIDC issuer this group's identity comes from. Pairs with `name` to
+  -- form the natural key — same group name in two IdPs are distinct rows.
+  "oidc_iss"     text NOT NULL,
+  -- The group name as it appears in the OIDC `groups` claim.
+  "name"         text NOT NULL,
+  -- Optional human-friendly label. Most IdPs only emit names so this is
+  -- typically NULL; reserved for future enrichment.
+  "display_name" text,
+  "created_at"   timestamptz NOT NULL DEFAULT now(),
+  "updated_at"   timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE UNIQUE INDEX "groups_iss_name_uq" ON "groups" ("oidc_iss", "name");
+
+CREATE TRIGGER groups_set_updated_at BEFORE UPDATE ON "groups"
+  FOR EACH ROW EXECUTE FUNCTION set_updated_at();
+
+-- =============================================================================
+-- user_groups
+-- =============================================================================
+
+CREATE TABLE "user_groups" (
+  "user_id"    uuid NOT NULL REFERENCES "users"("id")  ON DELETE CASCADE,
+  "group_id"   uuid NOT NULL REFERENCES "groups"("id") ON DELETE CASCADE,
+  -- When this membership was last observed in a sign-in claim. The auth
+  -- callback rewrites this on every login (insert ... on conflict do
+  -- update) so it's effectively "last sign-in seen this membership".
+  "synced_at"  timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY ("user_id", "group_id")
+);
+
+CREATE INDEX "user_groups_user_idx" ON "user_groups" ("user_id");
@@ -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 =
@@ -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);
+}
+
@@ -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;
@@ -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);
 }
@@ -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, {
@@ -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
@@ -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;
+}