@hexis-ai/engram-server 0.11.3 → 0.13.0

package/dist/adapters/postgres.js

@@ -1,19 +1,6 @@
 import { runMigrations } from "../migrator";
-import { foldEvents } from "../storage";
-/**
- * 10-char alphanumeric id, e.g. `p_a8b3c2d4`. Cryptographic randomness via
- * the platform's getRandomValues; collision probability negligible for any
- * realistic person count.
- */
-function defaultPersonId() {
-    const ALPHA = "abcdefghijklmnopqrstuvwxyz0123456789";
-    const buf = new Uint8Array(8);
-    crypto.getRandomValues(buf);
-    let out = "p_";
-    for (const b of buf)
-        out += ALPHA[b % ALPHA.length];
-    return out;
-}
+import { foldEvents, newPersonId } from "../storage";
+import { isoString, pickPatch } from "./util";
 export class PostgresAdapter {
     workspaceId;
     sql;
@@ -21,7 +8,7 @@ export class PostgresAdapter {
     constructor(opts) {
         this.workspaceId = opts.workspaceId;
         this.sql = opts.sql;
-        this.newPersonId = opts.newPersonId ?? defaultPersonId;
+        this.newPersonId = opts.newPersonId ?? newPersonId;
     }
     /**
      * Apply all pending schema migrations. Safe to call repeatedly and
@@ -125,29 +112,27 @@ export class PostgresAdapter {
         return foldEvents(toSessionRow(rows[0]), events.map((e) => e.payload), new Date());
     }
     async updateSession(sessionId, patch) {
-        // Translate JS undefined → "no change" via a per-column "provided"
-        // flag the SQL evaluates with CASE WHEN. null in patch becomes a
-        // real null in the DB (clear), value becomes a set.
-        const titleProvided = patch.title !== undefined;
-        const channelProvided = patch.channel !== undefined;
-        const statusProvided = patch.status !== undefined;
-        const summaryProvided = patch.summary !== undefined;
-        const modelProvided = patch.model !== undefined;
-        const tcIdProvided = patch.trigger_conversation_id !== undefined;
-        const teIdProvided = patch.trigger_event_id !== undefined;
+        // Per-column "provided" flags drive a CASE WHEN per field: undefined
+        // leaves the column alone, null clears, value sets. `status` defaults
+        // to "active" on clear to match the column default.
+        const title = pickPatch(patch, "title");
+        const channel = pickPatch(patch, "channel");
+        const status = pickPatch(patch, "status", "active");
+        const summary = pickPatch(patch, "summary");
+        const model = pickPatch(patch, "model");
+        const tcId = pickPatch(patch, "trigger_conversation_id");
+        const teId = pickPatch(patch, "trigger_event_id");
         const rows = await this.sql `
       UPDATE engram_sessions SET
-        title    = CASE WHEN ${titleProvided}    THEN ${patch.title ?? null}    ELSE title    END,
-        channel  = CASE WHEN ${channelProvided}  THEN ${patch.channel ?? null}  ELSE channel  END,
-        status   = CASE WHEN ${statusProvided}   THEN ${patch.status ?? "active"} ELSE status END,
-        summary  = CASE WHEN ${summaryProvided}  THEN ${patch.summary ?? null}  ELSE summary  END,
-        model    = CASE WHEN ${modelProvided}    THEN ${patch.model ?? null}    ELSE model    END,
-        trigger_conversation_id = CASE WHEN ${tcIdProvided}
-          THEN ${patch.trigger_conversation_id ?? null}
-          ELSE trigger_conversation_id END,
-        trigger_event_id = CASE WHEN ${teIdProvided}
-          THEN ${patch.trigger_event_id ?? null}
-          ELSE trigger_event_id END,
+        title    = CASE WHEN ${title.provided}   THEN ${title.value}   ELSE title   END,
+        channel  = CASE WHEN ${channel.provided} THEN ${channel.value} ELSE channel END,
+        status   = CASE WHEN ${status.provided}  THEN ${status.value}  ELSE status  END,
+        summary  = CASE WHEN ${summary.provided} THEN ${summary.value} ELSE summary END,
+        model    = CASE WHEN ${model.provided}   THEN ${model.value}   ELSE model   END,
+        trigger_conversation_id = CASE WHEN ${tcId.provided}
+          THEN ${tcId.value} ELSE trigger_conversation_id END,
+        trigger_event_id = CASE WHEN ${teId.provided}
+          THEN ${teId.value} ELSE trigger_event_id END,
         updated_at = now()
       WHERE workspace_id = ${this.workspaceId} AND id = ${sessionId}
       RETURNING id
@@ -246,17 +231,18 @@ export class PostgresAdapter {
         return toPersonInfo(rows[0]);
     }
     async updatePerson(id, patch) {
-        // Treat `null` as an explicit clear; `undefined` as no-op.
-        const nameProvided = patch.display_name !== undefined;
-        const roleProvided = patch.role !== undefined;
-        const teamProvided = patch.team !== undefined;
-        const sourceProvided = patch.source !== undefined;
+        // undefined = no-op, null = clear (source clears to "auto" to match
+        // the column default).
+        const name = pickPatch(patch, "display_name");
+        const role = pickPatch(patch, "role");
+        const team = pickPatch(patch, "team");
+        const source = pickPatch(patch, "source", "auto");
         const rows = await this.sql `
       UPDATE engram_persons SET
-        display_name = CASE WHEN ${nameProvided}   THEN ${patch.display_name ?? null} ELSE display_name END,
-        role         = CASE WHEN ${roleProvided}   THEN ${patch.role ?? null}         ELSE role         END,
-        team         = CASE WHEN ${teamProvided}   THEN ${patch.team ?? null}         ELSE team         END,
-        source       = CASE WHEN ${sourceProvided} THEN ${patch.source ?? "auto"}     ELSE source       END,
+        display_name = CASE WHEN ${name.provided}   THEN ${name.value}   ELSE display_name END,
+        role         = CASE WHEN ${role.provided}   THEN ${role.value}   ELSE role         END,
+        team         = CASE WHEN ${team.provided}   THEN ${team.value}   ELSE team         END,
+        source       = CASE WHEN ${source.provided} THEN ${source.value} ELSE source       END,
         updated_at   = now()
       WHERE workspace_id = ${this.workspaceId} AND id = ${id}
       RETURNING id, display_name, role, team, source, created_at, updated_at
@@ -326,15 +312,13 @@ export class PostgresAdapter {
     }
     // --- Aliases ------------------------------------------------------
     async upsertAlias(personId, input) {
-        // Pre-check rather than rely on the FK so unknown persons return
-        // `null` instead of throwing a constraint violation.
-        const personExists = await this.sql `
-      SELECT id FROM engram_persons
-      WHERE workspace_id = ${this.workspaceId} AND id = ${personId}
-      LIMIT 1
+        // Same race as upsertIdentity — alias telemetry can land before
+        // the matching person telemetry. Auto-create a stub person.
+        await this.sql `
+      INSERT INTO engram_persons (workspace_id, id)
+      VALUES (${this.workspaceId}, ${personId})
+      ON CONFLICT (workspace_id, id) DO NOTHING
     `;
-        if (personExists.length === 0)
-            return null;
         const increment = input.increment ?? true;
         // Branch on the upsert behaviour. `increment=true` bumps usage_count
         // and replaces caller/last_used; `increment=false` is idempotent —
@@ -390,15 +374,15 @@ export class PostgresAdapter {
     }
     // --- Identities ---------------------------------------------------
     async upsertIdentity(ref, input) {
-        // Pre-check rather than rely on the FK so unknown persons return
-        // `null` instead of throwing a constraint violation.
-        const personExists = await this.sql `
-      SELECT id FROM engram_persons
-      WHERE workspace_id = ${this.workspaceId} AND id = ${input.person_id}
-      LIMIT 1
+        // Auto-create a stub person if missing. The two telemetry calls
+        // (person + identity) leave monet fire-and-forget and race over
+        // the network, so it's normal for the identity PUT to land first.
+        // Empty stub gets enriched by the trailing person PUT.
+        await this.sql `
+      INSERT INTO engram_persons (workspace_id, id)
+      VALUES (${this.workspaceId}, ${input.person_id})
+      ON CONFLICT (workspace_id, id) DO NOTHING
     `;
-        if (personExists.length === 0)
-            return null;
         // unlinked_at semantics: undefined = leave alone, null = clear,
         // value = set. matches the patch contract for the other fields.
         const unlinkedProvided = input.unlinked_at !== undefined;
@@ -460,27 +444,25 @@ export class PostgresAdapter {
     }
 }
 function toPersonInfo(r) {
-    const toIso = (v) => (typeof v === "string" ? v : v.toISOString());
     return {
         id: r.id,
         display_name: r.display_name,
         role: r.role,
         team: r.team,
         source: r.source,
-        created_at: toIso(r.created_at),
-        updated_at: toIso(r.updated_at),
+        created_at: isoString(r.created_at),
+        updated_at: isoString(r.updated_at),
     };
 }
 function toSessionRow(r) {
-    const toIso = (v) => (typeof v === "string" ? v : v.toISOString());
     return {
         id: r.id,
         ...(r.title ? { title: r.title } : {}),
         ...(r.channel ? { channel: r.channel } : {}),
         participants: r.participants,
         viewable_by: r.viewable_by,
-        createdAt: toIso(r.created_at),
-        updatedAt: toIso(r.updated_at),
+        createdAt: isoString(r.created_at),
+        updatedAt: isoString(r.updated_at),
         ...(r.status === "active" || r.status === "idle" || r.status === "completed"
             ? { status: r.status }
             : {}),
@@ -495,24 +477,19 @@ function toSessionRow(r) {
     };
 }
 function toAliasInfo(r) {
-    const toIso = (v) => (typeof v === "string" ? v : v.toISOString());
     // last_used is a DATE column; postgres-js returns it as a Date at UTC
     // midnight. Render as plain YYYY-MM-DD to match the wire type.
-    const lastUsed = typeof r.last_used === "string"
-        ? r.last_used.slice(0, 10)
-        : r.last_used.toISOString().slice(0, 10);
     return {
         person_id: r.person_id,
         name: r.name,
         caller: r.caller,
         usage_count: r.usage_count,
-        last_used: lastUsed,
-        created_at: toIso(r.created_at),
-        updated_at: toIso(r.updated_at),
+        last_used: isoString(r.last_used).slice(0, 10),
+        created_at: isoString(r.created_at),
+        updated_at: isoString(r.updated_at),
     };
 }
 function toIdentityInfo(r) {
-    const toIso = (v) => (typeof v === "string" ? v : v.toISOString());
     // linked_at is now TIMESTAMPTZ (post-migration 0004). Emit full ISO.
     return {
         ref: r.ref,
@@ -523,9 +500,9 @@ function toIdentityInfo(r) {
         source: r.source,
         is_primary: r.is_primary,
         picture: r.picture,
-        linked_at: toIso(r.linked_at),
-        unlinked_at: r.unlinked_at === null ? null : toIso(r.unlinked_at),
-        created_at: toIso(r.created_at),
-        updated_at: toIso(r.updated_at),
+        linked_at: isoString(r.linked_at),
+        unlinked_at: r.unlinked_at === null ? null : isoString(r.unlinked_at),
+        created_at: isoString(r.created_at),
+        updated_at: isoString(r.updated_at),
     };
 }

package/dist/adapters/util.d.ts

@@ -0,0 +1,27 @@
+/** Postgres drivers return timestamp columns as either string or Date depending
+ *  on the type parser. Normalise to ISO-8601 string for the wire format. */
+export declare function isoString(v: string | Date): string;
+/**
+ * Apply a partial patch with the SDK's three-state semantics:
+ *   - `undefined` → keep `existing[key]`
+ *   - `null`      → clear (set to `clearTo`, default `null`)
+ *   - value       → set
+ *
+ * Used by the in-memory adapter to mirror the postgres adapter's
+ * per-column CASE WHEN behaviour without hand-writing the if/else
+ * tree for every field. Returns a new object — never mutates.
+ */
+export declare function applyPartial<E, P>(existing: E, patch: P, 
+/** Default value when a key is explicitly cleared (`null` in the patch). */
+clearTo?: Partial<{
+    [K in keyof P]: unknown;
+}>): E;
+/**
+ * Per-field patch helper for postgres CASE WHEN. Returns the
+ * `{provided, value}` tuple the SQL template uses; `clearTo` plugs in
+ * when the patch explicitly cleared the field with `null`.
+ */
+export declare function pickPatch<P, K extends keyof P>(patch: P, key: K, clearTo?: NonNullable<P[K]> | null): {
+    provided: boolean;
+    value: NonNullable<P[K]> | null;
+};

package/dist/adapters/util.js

@@ -0,0 +1,47 @@
+/** Postgres drivers return timestamp columns as either string or Date depending
+ *  on the type parser. Normalise to ISO-8601 string for the wire format. */
+export function isoString(v) {
+    return typeof v === "string" ? v : v.toISOString();
+}
+/**
+ * Apply a partial patch with the SDK's three-state semantics:
+ *   - `undefined` → keep `existing[key]`
+ *   - `null`      → clear (set to `clearTo`, default `null`)
+ *   - value       → set
+ *
+ * Used by the in-memory adapter to mirror the postgres adapter's
+ * per-column CASE WHEN behaviour without hand-writing the if/else
+ * tree for every field. Returns a new object — never mutates.
+ */
+export function applyPartial(existing, patch, 
+/** Default value when a key is explicitly cleared (`null` in the patch). */
+clearTo = {}) {
+    const next = { ...existing };
+    for (const key of Object.keys(patch)) {
+        const value = patch[key];
+        if (value === undefined)
+            continue;
+        if (value === null) {
+            const fallback = clearTo[key];
+            if (fallback === undefined)
+                delete next[key];
+            else
+                next[key] = fallback;
+        }
+        else {
+            next[key] = value;
+        }
+    }
+    return next;
+}
+/**
+ * Per-field patch helper for postgres CASE WHEN. Returns the
+ * `{provided, value}` tuple the SQL template uses; `clearTo` plugs in
+ * when the patch explicitly cleared the field with `null`.
+ */
+export function pickPatch(patch, key, clearTo = null) {
+    const provided = patch[key] !== undefined;
+    const raw = patch[key];
+    const value = raw == null ? clearTo : raw;
+    return { provided, value };
+}

package/dist/admin.d.ts

@@ -1,9 +1,17 @@
 import { Hono } from "hono";
 import { type KeyStore } from "./key-store";
+import type { OrgStore } from "./org-store";
 export interface AdminOptions {
     /** Bearer token required for every /admin/v1 request. */
     token: string;
     keyStore: KeyStore;
+    /**
+     * Optional org store. When provided, mounts the orgs surface
+     * (\`/admin/v1/orgs/*\` plus \`/admin/v1/orgs/:id/workspaces\` for
+     * org-scoped workspace creation). Without it only the legacy
+     * \`/admin/v1/workspaces\` endpoints are exposed.
+     */
+    orgStore?: OrgStore;
 }
 interface Env {
     Variables: {
@@ -11,11 +19,25 @@ interface Env {
     };
 }
 /**
- * Build the admin sub-router. Mount under `/admin/v1`.
+ * Build the admin sub-router. Mount under \`/admin/v1\`.
  *
- * Auth model: a single platform-level bearer token (`ENGRAM_ADMIN_TOKEN`).
- * The admin token is checked here only — it never reaches the workspace
- * KeyStore, so an admin token cannot accidentally double as a workspace key.
+ * Auth model: a single platform-level bearer token
+ * (\`ENGRAM_ADMIN_TOKEN\`). Never crosses with workspace api-keys.
+ *
+ * Surface, when orgStore is wired:
+ *
+ *   POST   /orgs                                  create org
+ *   GET    /orgs                                  list orgs
+ *   GET    /orgs/:id                              get org
+ *   DELETE /orgs/:id                              delete org (CASCADE)
+ *   POST   /orgs/:id/members                      add member (email|userId)
+ *   GET    /orgs/:id/members
+ *   DELETE /orgs/:id/members/:userId
+ *   POST   /orgs/:id/workspaces                   create + key (under org)
+ *   GET    /orgs/:id/workspaces
+ *
+ * Plus the lower-level workspace + key endpoints from before
+ * (\`/workspaces\`, \`/workspaces/:id/keys\`, ...).
  */
 export declare function createAdminRouter(opts: AdminOptions): Hono<Env>;
 export {};

package/dist/admin.js

@@ -1,12 +1,27 @@
 import { Hono } from "hono";
 import { isValidWorkspaceId } from "./key-store";
 import { createWorkspaceSchema, issueKeySchema, parseJsonBody } from "./schemas";
+import { addMember, createOrg, createWorkspaceUnderOrg, deleteOrg, getOrgOrThrow, OrgServiceError, removeMember, requireWorkspaceInOrg, revokeWorkspaceKey, } from "./services/orgs";
 /**
- * Build the admin sub-router. Mount under `/admin/v1`.
+ * Build the admin sub-router. Mount under \`/admin/v1\`.
  *
- * Auth model: a single platform-level bearer token (`ENGRAM_ADMIN_TOKEN`).
- * The admin token is checked here only — it never reaches the workspace
- * KeyStore, so an admin token cannot accidentally double as a workspace key.
+ * Auth model: a single platform-level bearer token
+ * (\`ENGRAM_ADMIN_TOKEN\`). Never crosses with workspace api-keys.
+ *
+ * Surface, when orgStore is wired:
+ *
+ *   POST   /orgs                                  create org
+ *   GET    /orgs                                  list orgs
+ *   GET    /orgs/:id                              get org
+ *   DELETE /orgs/:id                              delete org (CASCADE)
+ *   POST   /orgs/:id/members                      add member (email|userId)
+ *   GET    /orgs/:id/members
+ *   DELETE /orgs/:id/members/:userId
+ *   POST   /orgs/:id/workspaces                   create + key (under org)
+ *   GET    /orgs/:id/workspaces
+ *
+ * Plus the lower-level workspace + key endpoints from before
+ * (\`/workspaces\`, \`/workspaces/:id/keys\`, ...).
  */
 export function createAdminRouter(opts) {
     const app = new Hono();
@@ -18,6 +33,9 @@ export function createAdminRouter(opts) {
         }
         await next();
     });
+    // -------------------- workspaces (legacy / api-key-only) ----
+    // Kept for backwards compatibility; new callers should create
+    // workspaces under an org so they're reachable from the web UI.
     app.post("/workspaces", async (c) => {
         const body = await parseJsonBody(c, createWorkspaceSchema);
         if (body instanceof Response)
@@ -31,8 +49,6 @@ export function createAdminRouter(opts) {
                 ...(body.name !== undefined ? { name: body.name } : {}),
                 ...(body.metadata !== undefined ? { metadata: body.metadata } : {}),
             });
-            // Default: issue an initial key so the caller can start using the
-            // workspace in one round trip. Opt out with `issueKey: false`.
             if (body.issueKey === false) {
                 return c.json({ workspace: ws });
             }
@@ -68,7 +84,6 @@ export function createAdminRouter(opts) {
         const ws = await opts.keyStore.getWorkspace(workspaceId);
         if (!ws)
             return c.json({ error: "workspace_not_found" }, 404);
-        // The body is optional here — an empty POST issues a key with no name.
         const raw = await c.req.json().catch(() => ({}));
         const parsed = issueKeySchema.safeParse(raw);
         if (!parsed.success) {
@@ -101,5 +116,109 @@ export function createAdminRouter(opts) {
         }
         return c.body(null, 204);
     });
+    // -------------------- orgs (org-scoped admin surface) -------
+    const orgStore = opts.orgStore;
+    if (!orgStore)
+        return app;
+    const deps = { orgStore, keyStore: opts.keyStore };
+    app.post("/orgs", async (c) => runService(c, async () => {
+        const body = (await c.req.json().catch(() => ({})));
+        const org = await createOrg(deps, body);
+        return c.json({ org });
+    }));
+    app.get("/orgs", async (c) => {
+        const orgs = await orgStore.listOrgs();
+        return c.json({ orgs });
+    });
+    app.get("/orgs/:id", async (c) => runService(c, async () => {
+        const org = await getOrgOrThrow(deps, c.req.param("id"));
+        return c.json({ org });
+    }));
+    app.delete("/orgs/:id", async (c) => runService(c, async () => {
+        await deleteOrg(deps, c.req.param("id"));
+        return c.body(null, 204);
+    }));
+    // ----- org members ------------------------------------------
+    app.get("/orgs/:id/members", async (c) => runService(c, async () => {
+        const id = c.req.param("id");
+        await getOrgOrThrow(deps, id);
+        return c.json({ members: await orgStore.listMembers(id) });
+    }));
+    app.post("/orgs/:id/members", async (c) => runService(c, async () => {
+        const orgId = c.req.param("id");
+        await getOrgOrThrow(deps, orgId);
+        const body = (await c.req.json().catch(() => ({})));
+        const member = await addMember(deps, orgId, body);
+        return c.json({ member });
+    }));
+    app.delete("/orgs/:id/members/:userId", async (c) => runService(c, async () => {
+        const orgId = c.req.param("id");
+        await getOrgOrThrow(deps, orgId);
+        await removeMember(deps, orgId, c.req.param("userId"));
+        return c.body(null, 204);
+    }));
+    // ----- org workspaces ---------------------------------------
+    // Stands up a tenant in one round-trip. createWorkspaceUnderOrg
+    // wraps createWorkspace + setWorkspaceOrg + issueKey and applies
+    // the same id validation as the legacy /workspaces POST.
+    app.post("/orgs/:id/workspaces", async (c) => runService(c, async () => {
+        const orgId = c.req.param("id");
+        await getOrgOrThrow(deps, orgId);
+        const body = await parseJsonBody(c, createWorkspaceSchema);
+        if (body instanceof Response)
+            return body;
+        return c.json(await createWorkspaceUnderOrg(deps, orgId, body));
+    }));
+    app.get("/orgs/:id/workspaces", async (c) => runService(c, async () => {
+        const orgId = c.req.param("id");
+        await getOrgOrThrow(deps, orgId);
+        const workspaces = await orgStore.listWorkspacesForOrg(orgId);
+        return c.json({ workspaces });
+    }));
+    // ----- per-workspace api keys (scoped to an org) -----------
+    // Org-scoped equivalent of the legacy /admin/v1/workspaces/:id/keys
+    // routes. monet uses these for key rotation after the initial
+    // createWorkspaceUnderOrg + key issuance.
+    app.get("/orgs/:id/workspaces/:wsId/keys", async (c) => runService(c, async () => {
+        const orgId = c.req.param("id");
+        const wsId = c.req.param("wsId");
+        await getOrgOrThrow(deps, orgId);
+        await requireWorkspaceInOrg(deps, orgId, wsId);
+        return c.json({ keys: await opts.keyStore.listKeys(wsId) });
+    }));
+    app.post("/orgs/:id/workspaces/:wsId/keys", async (c) => runService(c, async () => {
+        const orgId = c.req.param("id");
+        const wsId = c.req.param("wsId");
+        await getOrgOrThrow(deps, orgId);
+        await requireWorkspaceInOrg(deps, orgId, wsId);
+        const raw = await c.req.json().catch(() => ({}));
+        const parsed = issueKeySchema.safeParse(raw);
+        if (!parsed.success) {
+            return c.json({ error: "invalid_body", issues: parsed.error.issues }, 400);
+        }
+        const key = await opts.keyStore.issueKey(wsId, {
+            ...(parsed.data.name !== undefined ? { name: parsed.data.name } : {}),
+        });
+        return c.json(key);
+    }));
+    app.delete("/orgs/:id/workspaces/:wsId/keys/:keyId", async (c) => runService(c, async () => {
+        const orgId = c.req.param("id");
+        const wsId = c.req.param("wsId");
+        await getOrgOrThrow(deps, orgId);
+        await requireWorkspaceInOrg(deps, orgId, wsId);
+        await revokeWorkspaceKey(deps, wsId, c.req.param("keyId"));
+        return c.body(null, 204);
+    }));
     return app;
 }
+/** Run a service call, mapping OrgServiceError to a JSON response. */
+async function runService(c, fn) {
+    try {
+        return await fn();
+    }
+    catch (e) {
+        if (e instanceof OrgServiceError)
+            return c.json({ error: e.code }, e.status);
+        throw e;
+    }
+}

package/dist/auth-resolver.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cookie-session → WorkspaceContext bridge (org-based).
+ *
+ * Each user joins an org once; the org has many workspaces. To
+ * resolve a request:
+ *
+ *   1) Validate the cookie via better-auth.
+ *   2) Look up every workspace visible to the user via
+ *      \`engram_org_members\` JOIN \`engram_workspaces\`.
+ *   3) Pick one by, in order:
+ *        a) x-workspace-id header (verified against the visible list)
+ *        b) session.currentWorkspaceId (sticky from last UI choice)
+ *        c) the user's only visible workspace, if exactly one exists
+ *
+ * Membership at the workspace level is intentionally not modeled —
+ * any org member sees every workspace in that org. Add finer-grained
+ * scoping at the app level if needed later.
+ */
+import type { Pool } from "pg";
+import type { EngramAuth } from "./auth";
+import type { WorkspaceContext } from "./context";
+import type { OrgStore } from "./org-store";
+import type { StorageAdapter } from "./storage";
+export interface CookieResolverOptions {
+    auth: EngramAuth;
+    pool: Pool;
+    orgStore: OrgStore;
+    /** Workspace-scoped storage factory; same one wired into api-key auth. */
+    getStorage: (workspaceId: string) => StorageAdapter;
+}
+export type CookieAuthResolver = (req: Request) => Promise<WorkspaceContext | null>;
+export declare function makeCookieAuthResolver(opts: CookieResolverOptions): CookieAuthResolver;

package/dist/auth-resolver.js

@@ -0,0 +1,53 @@
+/**
+ * Cookie-session → WorkspaceContext bridge (org-based).
+ *
+ * Each user joins an org once; the org has many workspaces. To
+ * resolve a request:
+ *
+ *   1) Validate the cookie via better-auth.
+ *   2) Look up every workspace visible to the user via
+ *      \`engram_org_members\` JOIN \`engram_workspaces\`.
+ *   3) Pick one by, in order:
+ *        a) x-workspace-id header (verified against the visible list)
+ *        b) session.currentWorkspaceId (sticky from last UI choice)
+ *        c) the user's only visible workspace, if exactly one exists
+ *
+ * Membership at the workspace level is intentionally not modeled —
+ * any org member sees every workspace in that org. Add finer-grained
+ * scoping at the app level if needed later.
+ */
+async function sessionWorkspace(pool, sessionId) {
+    const { rows } = await pool.query(`SELECT current_workspace_id FROM engram_auth_sessions WHERE id = $1 LIMIT 1`, [sessionId]);
+    return rows[0]?.current_workspace_id ?? null;
+}
+export function makeCookieAuthResolver(opts) {
+    return async (req) => {
+        const session = await opts.auth.api
+            .getSession({ headers: req.headers })
+            .catch(() => null);
+        if (!session?.user)
+            return null;
+        const visible = await opts.orgStore.listWorkspacesForUser(session.user.id);
+        if (visible.length === 0)
+            return null;
+        const allowed = new Set(visible.map((w) => w.id));
+        const headerWs = req.headers.get("x-workspace-id");
+        let pick = null;
+        if (headerWs) {
+            if (allowed.has(headerWs))
+                pick = headerWs;
+            else
+                return null; // explicit header that isn't allowed → 401
+        }
+        else {
+            const stickied = await sessionWorkspace(opts.pool, session.session.id);
+            if (stickied && allowed.has(stickied))
+                pick = stickied;
+            else if (visible.length === 1)
+                pick = visible[0].id;
+        }
+        if (!pick)
+            return null;
+        return { workspaceId: pick, storage: opts.getStorage(pick) };
+    };
+}