@hexis-ai/engram-server 0.11.2 → 0.12.0

package/dist/auth.js

@@ -0,0 +1,164 @@
+/**
+ * better-auth instance for engram-server.
+ *
+ * Two auth modes coexist on /v1/*:
+ *   - x-api-key / Bearer  → machine callers (monet telemetry / MCP),
+ *                           resolved through KeyStore → workspace.
+ *   - cookie session       → human users from engram-web,
+ *                           resolved through this module → user →
+ *                           membership check → workspace.
+ *
+ * Tables live under \`engram_auth_*\` (see migration 0006-auth) so the
+ * shorter \`engram_session\` namespace remains agent-trajectory only.
+ *
+ * Required env (production):
+ *   ENGRAM_AUTH_SECRET           cookie/JWT signing secret (>= 32 chars)
+ *   ENGRAM_AUTH_URL              full base URL of this server
+ *                                (e.g. https://api.engram.hexis.ltd)
+ *   ENGRAM_AUTH_GOOGLE_ID        Google OAuth client id
+ *   ENGRAM_AUTH_GOOGLE_SECRET    Google OAuth client secret
+ *
+ * Optional:
+ *   ENGRAM_AUTH_COOKIE_DOMAIN    set to .hexis.ltd to share cookies
+ *                                between engram.hexis.ltd (web) and
+ *                                api.engram.hexis.ltd (this server)
+ *   ENGRAM_AUTH_TRUSTED_ORIGINS  comma-separated extra origins, e.g.
+ *                                engram-web's URL in dev
+ *   ENGRAM_AUTH_EMAIL_DOMAIN     restrict sign-in to one email domain
+ *                                (default: hexis.ltd)
+ */
+import { randomUUID } from "node:crypto";
+import { betterAuth } from "better-auth";
+import { bearer } from "better-auth/plugins";
+/**
+ * Construct the better-auth instance. The returned value exposes
+ *   - \`handler(req: Request): Response\` for Hono \`.all("/auth/*", ...)\`
+ *   - \`api.getSession({ headers })\` for cookie → session lookup
+ */
+export function buildAuth(opts) {
+    const emailDomain = opts.emailDomain ?? "hexis.ltd";
+    const secure = opts.secureCookies ?? process.env.NODE_ENV === "production";
+    return betterAuth({
+        database: opts.pool,
+        secret: opts.secret,
+        baseURL: opts.baseURL,
+        basePath: "/auth",
+        trustedOrigins: opts.trustedOrigins ?? [],
+        // ---------- table mapping → engram_auth_* ---------------------
+        user: {
+            modelName: "engram_auth_users",
+            fields: {
+                emailVerified: "email_verified",
+                createdAt: "created_at",
+                updatedAt: "updated_at",
+            },
+        },
+        session: {
+            modelName: "engram_auth_sessions",
+            fields: {
+                userId: "user_id",
+                expiresAt: "expires_at",
+                ipAddress: "ip_address",
+                userAgent: "user_agent",
+                createdAt: "created_at",
+                updatedAt: "updated_at",
+                token: "token",
+            },
+            additionalFields: {
+                currentWorkspaceId: {
+                    type: "string",
+                    required: false,
+                    input: false,
+                    fieldName: "current_workspace_id",
+                },
+            },
+            cookieCache: { enabled: true, maxAge: 5 * 60 },
+        },
+        account: {
+            modelName: "engram_auth_accounts",
+            fields: {
+                userId: "user_id",
+                accountId: "account_id",
+                providerId: "provider_id",
+                accessToken: "access_token",
+                refreshToken: "refresh_token",
+                idToken: "id_token",
+                accessTokenExpiresAt: "access_token_expires_at",
+                refreshTokenExpiresAt: "refresh_token_expires_at",
+                scope: "scope",
+                password: "password",
+                createdAt: "created_at",
+                updatedAt: "updated_at",
+            },
+            // Auto-link the Google account to a same-email user. Engram
+            // doesn't pre-seed users — every user shows up via OAuth — so
+            // this is mostly defensive (covers DB restores / re-imports).
+            accountLinking: { enabled: true, trustedProviders: ["google"] },
+        },
+        verification: {
+            modelName: "engram_auth_verifications",
+            fields: {
+                expiresAt: "expires_at",
+                createdAt: "created_at",
+                updatedAt: "updated_at",
+            },
+        },
+        // ---------- ID + cookie scope ---------------------------------
+        advanced: {
+            database: {
+                generateId: () => `u_${randomUUID().replace(/-/g, "").substring(0, 16)}`,
+            },
+            // Distinct prefix so engram's cookie doesn't clobber monet's
+            // (both live under .hexis.ltd, both use better-auth defaults).
+            cookiePrefix: "engram",
+            cookies: opts.cookieDomain
+                ? {
+                    sessionToken: {
+                        attributes: {
+                            domain: opts.cookieDomain,
+                            sameSite: "lax",
+                            secure,
+                            httpOnly: true,
+                            path: "/",
+                        },
+                    },
+                }
+                : undefined,
+            useSecureCookies: secure,
+            crossSubDomainCookies: opts.cookieDomain
+                ? { enabled: true, domain: opts.cookieDomain }
+                : undefined,
+        },
+        // ---------- providers -----------------------------------------
+        socialProviders: {
+            google: {
+                clientId: opts.google.clientId,
+                clientSecret: opts.google.clientSecret,
+            },
+        },
+        // ---------- email-domain allowlist ----------------------------
+        // Reject sign-ins whose verified email is outside the allowlist.
+        // Throwing here surfaces as a generic OAuth failure to the
+        // client; we deliberately don't expose the rejected domain.
+        databaseHooks: {
+            user: {
+                create: {
+                    before: async (user) => {
+                        const email = user.email ?? "";
+                        const domain = email.split("@")[1]?.toLowerCase() ?? "";
+                        if (domain !== emailDomain) {
+                            throw new Error(`email_domain_not_allowed:${domain}`);
+                        }
+                        return { data: user };
+                    },
+                },
+            },
+        },
+        // ---------- plugins -------------------------------------------
+        plugins: [
+            // Accept Authorization: Bearer <session-token> for clients
+            // that can't carry cookies (SPA → cross-domain XHR fallback).
+            bearer(),
+        ],
+    });
+}

package/dist/index.d.ts

@@ -8,3 +8,7 @@ export { InMemoryKeyStore } from "./adapters/memory-key-store";
 export { PostgresKeyStore } from "./adapters/postgres-key-store";
 export { createAdminRouter, type AdminOptions } from "./admin";
 export { buildOpenApiDocument } from "./openapi";
+export { buildAuth, type BuildAuthOptions, type EngramAuth } from "./auth";
+export { makeCookieAuthResolver, type CookieAuthResolver, type CookieResolverOptions, } from "./auth-resolver";
+export { type OrgStore, type OrgRow, type OrgMembershipRow, } from "./org-store";
+export { PostgresOrgStore } from "./adapters/postgres-org-store";

package/dist/index.js

@@ -8,3 +8,7 @@ export { InMemoryKeyStore } from "./adapters/memory-key-store";
 export { PostgresKeyStore } from "./adapters/postgres-key-store";
 export { createAdminRouter } from "./admin";
 export { buildOpenApiDocument } from "./openapi";
+export { buildAuth } from "./auth";
+export { makeCookieAuthResolver, } from "./auth-resolver";
+export {} from "./org-store";
+export { PostgresOrgStore } from "./adapters/postgres-org-store";

package/dist/main.js

@@ -12,6 +12,12 @@
  *                              InMemoryAdapter (NOT durable across restarts)
  *   DATABASE_SOCKET_PATH       Cloud SQL Auth Proxy unix socket dir
  *
+ * Optional env (engram-web cookie auth — see ./auth.ts for the full set):
+ *   ENGRAM_AUTH_SECRET, ENGRAM_AUTH_URL,
+ *   ENGRAM_AUTH_GOOGLE_ID, ENGRAM_AUTH_GOOGLE_SECRET,
+ *   ENGRAM_AUTH_COOKIE_DOMAIN, ENGRAM_AUTH_TRUSTED_ORIGINS,
+ *   ENGRAM_AUTH_EMAIL_DOMAIN
+ *
  * Workspaces and their API keys are provisioned exclusively through the
  * admin API. There is no single-tenant fallback — every caller must hold a
  * workspace-scoped key issued by `POST /admin/v1/workspaces`.
@@ -21,6 +27,9 @@ import { InMemoryAdapter } from "./adapters/memory";
 import { PostgresAdapter } from "./adapters/postgres";
 import { InMemoryKeyStore } from "./adapters/memory-key-store";
 import { PostgresKeyStore } from "./adapters/postgres-key-store";
+import { buildAuth } from "./auth";
+import { makeCookieAuthResolver } from "./auth-resolver";
+import { PostgresOrgStore } from "./adapters/postgres-org-store";
 const PORT = Number(process.env.PORT ?? 8080);
 const ADMIN_TOKEN = process.env.ENGRAM_ADMIN_TOKEN;
 const DATABASE_URL = process.env.DATABASE_URL;
@@ -30,6 +39,11 @@ if (!ADMIN_TOKEN) {
     process.exit(1);
 }
 const { keyStore, getStorage } = await buildStores();
+const { authHandler, cookieAuth, orgStore } = await buildCookieAuth(getStorage);
+const CORS_ORIGINS = (process.env.ENGRAM_CORS_ORIGINS ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
 const app = createServer({
     auth: async (key) => {
         const r = await keyStore.resolveKey(key);
@@ -37,7 +51,15 @@ const app = createServer({
             return null;
         return { workspaceId: r.workspaceId, storage: getStorage(r.workspaceId) };
     },
-    admin: { token: ADMIN_TOKEN, keyStore },
+    ...(authHandler ? { authHandler } : {}),
+    ...(cookieAuth ? { cookieAuth } : {}),
+    ...(orgStore ? { orgStore } : {}),
+    ...(CORS_ORIGINS.length > 0 ? { corsOrigins: CORS_ORIGINS } : {}),
+    admin: {
+        token: ADMIN_TOKEN,
+        keyStore,
+        ...(orgStore ? { orgStore } : {}),
+    },
 });
 console.log(`[engram-server] listening on :${PORT}`);
 export default { port: PORT, fetch: app.fetch };
@@ -79,3 +101,54 @@ async function buildStores() {
         },
     };
 }
+/**
+ * Wire better-auth + cookie resolver when the required env vars are
+ * set. Returns `{}` when auth is disabled (in-memory dev, or no
+ * Google OAuth configured) — the rest of the server still works,
+ * but only api-key callers can reach /v1.
+ */
+async function buildCookieAuth(getStorage) {
+    const secret = process.env.ENGRAM_AUTH_SECRET;
+    const baseURL = process.env.ENGRAM_AUTH_URL;
+    const googleId = process.env.ENGRAM_AUTH_GOOGLE_ID;
+    const googleSecret = process.env.ENGRAM_AUTH_GOOGLE_SECRET;
+    if (!secret || !baseURL || !googleId || !googleSecret) {
+        if (DATABASE_URL) {
+            console.warn("[engram-server] cookie auth disabled (set ENGRAM_AUTH_SECRET/URL/GOOGLE_ID/GOOGLE_SECRET to enable engram-web sign-in)");
+        }
+        return {};
+    }
+    if (!DATABASE_URL) {
+        console.warn("[engram-server] cookie auth requires DATABASE_URL — skipping");
+        return {};
+    }
+    const { Pool } = await import("pg");
+    const url = new URL(DATABASE_URL);
+    const pool = new Pool({
+        host: DATABASE_SOCKET_PATH ?? url.hostname,
+        port: DATABASE_SOCKET_PATH ? undefined : Number(url.port || 5432),
+        user: decodeURIComponent(url.username),
+        password: decodeURIComponent(url.password),
+        database: url.pathname.replace(/^\//, ""),
+    });
+    const trusted = (process.env.ENGRAM_AUTH_TRUSTED_ORIGINS ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const auth = buildAuth({
+        pool,
+        secret,
+        baseURL,
+        google: { clientId: googleId, clientSecret: googleSecret },
+        ...(process.env.ENGRAM_AUTH_COOKIE_DOMAIN
+            ? { cookieDomain: process.env.ENGRAM_AUTH_COOKIE_DOMAIN }
+            : {}),
+        ...(trusted.length > 0 ? { trustedOrigins: trusted } : {}),
+        ...(process.env.ENGRAM_AUTH_EMAIL_DOMAIN
+            ? { emailDomain: process.env.ENGRAM_AUTH_EMAIL_DOMAIN }
+            : {}),
+    });
+    const orgStore = new PostgresOrgStore(pool);
+    const cookieAuth = makeCookieAuthResolver({ auth, pool, orgStore, getStorage });
+    return { authHandler: auth, cookieAuth, orgStore };
+}

package/dist/migrations/0006-auth.d.ts

@@ -0,0 +1,2 @@
+export declare const name = "0006-auth";
+export declare const sql = "\n-- ============================================================\n-- Phase E1: human-user auth for engram-web\n--\n-- engram-server has always authenticated machine callers with\n-- per-workspace api keys (engram_api_keys). engram-web now wants\n-- to authenticate _people_ with Google SSO, so we add the\n-- standard better-auth quartet plus a workspace_members join.\n--\n-- All tables are namespaced `engram_auth_*` to keep them out of\n-- the `engram_*` domain (sessions / events / persons / aliases /\n-- identities) where `session` already means an agent trajectory.\n-- ============================================================\n\nCREATE TABLE IF NOT EXISTS engram_auth_users (\n  id              TEXT PRIMARY KEY,\n  email           TEXT NOT NULL UNIQUE,\n  email_verified  BOOLEAN NOT NULL DEFAULT FALSE,\n  name            TEXT,\n  image           TEXT,\n  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()\n);\nCREATE INDEX IF NOT EXISTS idx_engram_auth_users_email ON engram_auth_users (email);\n\nCREATE TABLE IF NOT EXISTS engram_auth_sessions (\n  id                    TEXT PRIMARY KEY,\n  user_id               TEXT NOT NULL REFERENCES engram_auth_users(id) ON DELETE CASCADE,\n  token                 TEXT NOT NULL UNIQUE,\n  expires_at            TIMESTAMPTZ NOT NULL,\n  ip_address            TEXT,\n  user_agent            TEXT,\n  current_workspace_id  TEXT,\n  created_at            TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  updated_at            TIMESTAMPTZ NOT NULL DEFAULT NOW()\n);\nCREATE INDEX IF NOT EXISTS idx_engram_auth_sessions_user ON engram_auth_sessions (user_id);\nCREATE INDEX IF NOT EXISTS idx_engram_auth_sessions_token ON engram_auth_sessions (token);\nCREATE INDEX IF NOT EXISTS idx_engram_auth_sessions_expires ON engram_auth_sessions (expires_at);\n\nCREATE TABLE IF NOT EXISTS engram_auth_accounts (\n  id                        TEXT PRIMARY KEY,\n  user_id                   TEXT NOT NULL REFERENCES engram_auth_users(id) ON DELETE CASCADE,\n  account_id                TEXT NOT NULL,\n  provider_id               TEXT NOT NULL,\n  access_token              TEXT,\n  refresh_token             TEXT,\n  id_token                  TEXT,\n  access_token_expires_at   TIMESTAMPTZ,\n  refresh_token_expires_at  TIMESTAMPTZ,\n  scope                     TEXT,\n  password                  TEXT,\n  created_at                TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  updated_at                TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  UNIQUE (provider_id, account_id)\n);\nCREATE INDEX IF NOT EXISTS idx_engram_auth_accounts_user ON engram_auth_accounts (user_id);\n\nCREATE TABLE IF NOT EXISTS engram_auth_verifications (\n  id          TEXT PRIMARY KEY,\n  identifier  TEXT NOT NULL,\n  value       TEXT NOT NULL,\n  expires_at  TIMESTAMPTZ NOT NULL,\n  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()\n);\nCREATE INDEX IF NOT EXISTS idx_engram_auth_verifications_identifier\n  ON engram_auth_verifications (identifier);\n\n-- workspace \u2194 user membership. A user can belong to many workspaces;\n-- a workspace can have many members. Roles are kept open-ended\n-- (validated at the app layer) since engram doesn't enforce any\n-- per-route authorization today \u2014 membership is the only check.\nCREATE TABLE IF NOT EXISTS engram_workspace_members (\n  workspace_id  TEXT NOT NULL REFERENCES engram_workspaces(id) ON DELETE CASCADE,\n  user_id       TEXT NOT NULL REFERENCES engram_auth_users(id) ON DELETE CASCADE,\n  role          TEXT NOT NULL DEFAULT 'member',\n  joined_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  PRIMARY KEY (workspace_id, user_id)\n);\nCREATE INDEX IF NOT EXISTS idx_engram_workspace_members_user\n  ON engram_workspace_members (user_id);\n";

package/dist/migrations/0006-auth.js

@@ -0,0 +1,84 @@
+export const name = "0006-auth";
+export const sql = `
+-- ============================================================
+-- Phase E1: human-user auth for engram-web
+--
+-- engram-server has always authenticated machine callers with
+-- per-workspace api keys (engram_api_keys). engram-web now wants
+-- to authenticate _people_ with Google SSO, so we add the
+-- standard better-auth quartet plus a workspace_members join.
+--
+-- All tables are namespaced \`engram_auth_*\` to keep them out of
+-- the \`engram_*\` domain (sessions / events / persons / aliases /
+-- identities) where \`session\` already means an agent trajectory.
+-- ============================================================
+
+CREATE TABLE IF NOT EXISTS engram_auth_users (
+  id              TEXT PRIMARY KEY,
+  email           TEXT NOT NULL UNIQUE,
+  email_verified  BOOLEAN NOT NULL DEFAULT FALSE,
+  name            TEXT,
+  image           TEXT,
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_engram_auth_users_email ON engram_auth_users (email);
+
+CREATE TABLE IF NOT EXISTS engram_auth_sessions (
+  id                    TEXT PRIMARY KEY,
+  user_id               TEXT NOT NULL REFERENCES engram_auth_users(id) ON DELETE CASCADE,
+  token                 TEXT NOT NULL UNIQUE,
+  expires_at            TIMESTAMPTZ NOT NULL,
+  ip_address            TEXT,
+  user_agent            TEXT,
+  current_workspace_id  TEXT,
+  created_at            TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at            TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_engram_auth_sessions_user ON engram_auth_sessions (user_id);
+CREATE INDEX IF NOT EXISTS idx_engram_auth_sessions_token ON engram_auth_sessions (token);
+CREATE INDEX IF NOT EXISTS idx_engram_auth_sessions_expires ON engram_auth_sessions (expires_at);
+
+CREATE TABLE IF NOT EXISTS engram_auth_accounts (
+  id                        TEXT PRIMARY KEY,
+  user_id                   TEXT NOT NULL REFERENCES engram_auth_users(id) ON DELETE CASCADE,
+  account_id                TEXT NOT NULL,
+  provider_id               TEXT NOT NULL,
+  access_token              TEXT,
+  refresh_token             TEXT,
+  id_token                  TEXT,
+  access_token_expires_at   TIMESTAMPTZ,
+  refresh_token_expires_at  TIMESTAMPTZ,
+  scope                     TEXT,
+  password                  TEXT,
+  created_at                TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at                TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  UNIQUE (provider_id, account_id)
+);
+CREATE INDEX IF NOT EXISTS idx_engram_auth_accounts_user ON engram_auth_accounts (user_id);
+
+CREATE TABLE IF NOT EXISTS engram_auth_verifications (
+  id          TEXT PRIMARY KEY,
+  identifier  TEXT NOT NULL,
+  value       TEXT NOT NULL,
+  expires_at  TIMESTAMPTZ NOT NULL,
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_engram_auth_verifications_identifier
+  ON engram_auth_verifications (identifier);
+
+-- workspace ↔ user membership. A user can belong to many workspaces;
+-- a workspace can have many members. Roles are kept open-ended
+-- (validated at the app layer) since engram doesn't enforce any
+-- per-route authorization today — membership is the only check.
+CREATE TABLE IF NOT EXISTS engram_workspace_members (
+  workspace_id  TEXT NOT NULL REFERENCES engram_workspaces(id) ON DELETE CASCADE,
+  user_id       TEXT NOT NULL REFERENCES engram_auth_users(id) ON DELETE CASCADE,
+  role          TEXT NOT NULL DEFAULT 'member',
+  joined_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (workspace_id, user_id)
+);
+CREATE INDEX IF NOT EXISTS idx_engram_workspace_members_user
+  ON engram_workspace_members (user_id);
+`;

package/dist/migrations/0007-orgs.d.ts

@@ -0,0 +1,2 @@
+export declare const name = "0007-orgs";
+export declare const sql = "\n-- ============================================================\n-- Wave G: orgs as the top-level grouping (Langfuse-style)\n--\n-- Before: cookie-auth users were members of individual workspaces\n-- (engram_workspace_members). That doesn't scale when a single\n-- dev team operates many tenant workspaces \u2014 every new tenant\n-- meant re-adding every dev. Move membership up one level so a\n-- user joins an org once and sees every workspace under it.\n--\n-- New shape:\n--   engram_orgs            top-level grouping\n--   engram_workspaces      now has org_id (NULL allowed only for\n--                          tests / legacy api-key-only rows;\n--                          cookie-auth requires the workspace's\n--                          org membership)\n--   engram_org_members     replaces engram_workspace_members\n-- ============================================================\n\nCREATE TABLE IF NOT EXISTS engram_orgs (\n  id          TEXT PRIMARY KEY,\n  name        TEXT,\n  metadata    JSONB NOT NULL DEFAULT '{}'::jsonb,\n  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()\n);\n\nALTER TABLE engram_workspaces ADD COLUMN IF NOT EXISTS org_id TEXT;\n\nDO $$\nBEGIN\n  IF NOT EXISTS (\n    SELECT 1 FROM pg_constraint\n    WHERE conname = 'engram_workspaces_org_id_fkey'\n  ) THEN\n    ALTER TABLE engram_workspaces\n      ADD CONSTRAINT engram_workspaces_org_id_fkey\n      FOREIGN KEY (org_id) REFERENCES engram_orgs(id) ON DELETE CASCADE;\n  END IF;\nEND $$;\n\nCREATE INDEX IF NOT EXISTS idx_engram_workspaces_org\n  ON engram_workspaces (org_id);\n\nCREATE TABLE IF NOT EXISTS engram_org_members (\n  org_id      TEXT NOT NULL REFERENCES engram_orgs(id) ON DELETE CASCADE,\n  user_id     TEXT NOT NULL REFERENCES engram_auth_users(id) ON DELETE CASCADE,\n  role        TEXT NOT NULL DEFAULT 'member',\n  joined_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  PRIMARY KEY (org_id, user_id)\n);\nCREATE INDEX IF NOT EXISTS idx_engram_org_members_user\n  ON engram_org_members (user_id);\n\n-- workspace_members from 0006-auth is obsolete in the org-based\n-- model. Drop it; the only path to workspace access is via org\n-- membership.\nDROP TABLE IF EXISTS engram_workspace_members;\n";

package/dist/migrations/0007-orgs.js

@@ -0,0 +1,59 @@
+export const name = "0007-orgs";
+export const sql = `
+-- ============================================================
+-- Wave G: orgs as the top-level grouping (Langfuse-style)
+--
+-- Before: cookie-auth users were members of individual workspaces
+-- (engram_workspace_members). That doesn't scale when a single
+-- dev team operates many tenant workspaces — every new tenant
+-- meant re-adding every dev. Move membership up one level so a
+-- user joins an org once and sees every workspace under it.
+--
+-- New shape:
+--   engram_orgs            top-level grouping
+--   engram_workspaces      now has org_id (NULL allowed only for
+--                          tests / legacy api-key-only rows;
+--                          cookie-auth requires the workspace's
+--                          org membership)
+--   engram_org_members     replaces engram_workspace_members
+-- ============================================================
+
+CREATE TABLE IF NOT EXISTS engram_orgs (
+  id          TEXT PRIMARY KEY,
+  name        TEXT,
+  metadata    JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+ALTER TABLE engram_workspaces ADD COLUMN IF NOT EXISTS org_id TEXT;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+    WHERE conname = 'engram_workspaces_org_id_fkey'
+  ) THEN
+    ALTER TABLE engram_workspaces
+      ADD CONSTRAINT engram_workspaces_org_id_fkey
+      FOREIGN KEY (org_id) REFERENCES engram_orgs(id) ON DELETE CASCADE;
+  END IF;
+END $$;
+
+CREATE INDEX IF NOT EXISTS idx_engram_workspaces_org
+  ON engram_workspaces (org_id);
+
+CREATE TABLE IF NOT EXISTS engram_org_members (
+  org_id      TEXT NOT NULL REFERENCES engram_orgs(id) ON DELETE CASCADE,
+  user_id     TEXT NOT NULL REFERENCES engram_auth_users(id) ON DELETE CASCADE,
+  role        TEXT NOT NULL DEFAULT 'member',
+  joined_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (org_id, user_id)
+);
+CREATE INDEX IF NOT EXISTS idx_engram_org_members_user
+  ON engram_org_members (user_id);
+
+-- workspace_members from 0006-auth is obsolete in the org-based
+-- model. Drop it; the only path to workspace access is via org
+-- membership.
+DROP TABLE IF EXISTS engram_workspace_members;
+`;

package/dist/migrations/index.js

@@ -3,6 +3,8 @@ import * as m0002 from "./0002-aliases";
 import * as m0003 from "./0003-identities";
 import * as m0004 from "./0004-schema-completion";
 import * as m0005 from "./0005-session-updated-at";
+import * as m0006 from "./0006-auth";
+import * as m0007 from "./0007-orgs";
 /**
  * Schema migrations, applied in array order. Add a new file under
  * `migrations/NNNN-<slug>.ts` exporting `name` and `sql`, then append it
@@ -16,4 +18,6 @@ export const MIGRATIONS = [
     { name: m0003.name, sql: m0003.sql },
     { name: m0004.name, sql: m0004.sql },
     { name: m0005.name, sql: m0005.sql },
+    { name: m0006.name, sql: m0006.sql },
+    { name: m0007.name, sql: m0007.sql },
 ];

package/dist/org-store.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Org / org-member / workspace-under-org persistence.
+ *
+ * Orgs are the top-level grouping in the cookie-auth model: a user
+ * joins an org once and gains access to every workspace owned by
+ * that org. Workspaces still exist as the data-isolation unit
+ * (sessions / persons / aliases / identities are per-workspace).
+ *
+ * Machine api-keys (api-key auth) are unaware of orgs — they
+ * continue to resolve directly to a workspace.
+ */
+export interface OrgRow {
+    id: string;
+    name: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
+export interface OrgMembershipRow {
+    orgId: string;
+    userId: string;
+    role: string;
+    joinedAt: string;
+}
+export interface OrgStore {
+    createOrg(input: {
+        id?: string;
+        name?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<OrgRow>;
+    getOrg(id: string): Promise<OrgRow | null>;
+    listOrgs(): Promise<OrgRow[]>;
+    deleteOrg(id: string): Promise<void>;
+    listMembers(orgId: string): Promise<OrgMembershipRow[]>;
+    upsertMember(input: {
+        orgId: string;
+        userId: string;
+        role?: string;
+    }): Promise<OrgMembershipRow>;
+    removeMember(orgId: string, userId: string): Promise<void>;
+    /** Look up a better-auth user by primary email. */
+    findUserByEmail(email: string): Promise<{
+        id: string;
+        email: string;
+    } | null>;
+    /** Orgs the given user is a member of. */
+    listOrgsForUser(userId: string): Promise<OrgMembershipRow[]>;
+    /**
+     * Set the org an already-existing workspace belongs to. Called
+     * by the admin endpoint that creates a workspace under an org
+     * (key issuance and engram_workspaces.org_id are written together).
+     */
+    setWorkspaceOrg(workspaceId: string, orgId: string): Promise<void>;
+    /** Workspaces in the given org. */
+    listWorkspacesForOrg(orgId: string): Promise<{
+        id: string;
+        name: string | null;
+    }[]>;
+    /** Workspaces visible to the user, aggregated across all their orgs. */
+    listWorkspacesForUser(userId: string): Promise<{
+        id: string;
+        name: string | null;
+        orgId: string;
+    }[]>;
+    /** Returns true if the user is an org-member of the workspace's org. */
+    userCanAccessWorkspace(userId: string, workspaceId: string): Promise<boolean>;
+}

package/dist/org-store.js

@@ -0,0 +1,12 @@
+/**
+ * Org / org-member / workspace-under-org persistence.
+ *
+ * Orgs are the top-level grouping in the cookie-auth model: a user
+ * joins an org once and gains access to every workspace owned by
+ * that org. Workspaces still exist as the data-isolation unit
+ * (sessions / persons / aliases / identities are per-workspace).
+ *
+ * Machine api-keys (api-key auth) are unaware of orgs — they
+ * continue to resolve directly to a workspace.
+ */
+export {};

package/dist/server.d.ts

@@ -1,9 +1,29 @@
 import { Hono } from "hono";
+import type { EngramAuth } from "./auth";
+import type { CookieAuthResolver } from "./auth-resolver";
 import type { AuthResolver, Env } from "./context";
+import type { OrgStore } from "./org-store";
 import { type AdminOptions } from "./admin";
 export interface CreateServerOptions {
     /** Resolves Bearer / X-Api-Key tokens into workspace contexts. */
     auth: AuthResolver;
+    /**
+     * Optional: cookie-session → workspace context. When provided and
+     * the request has no x-api-key / Bearer, the gate falls back to
+     * this resolver (engram-web human users).
+     */
+    cookieAuth?: CookieAuthResolver;
+    /**
+     * Optional: better-auth instance. When provided, mounted at
+     * `/auth/*` so engram-web can hit /auth/sign-in/social etc.
+     */
+    authHandler?: EngramAuth;
+    /**
+     * Optional: org store. When provided AND \`authHandler\` is set,
+     * exposes \`GET /v1/me/workspaces\` and \`GET /v1/me/orgs\` so
+     * engram-web can populate its org / workspace switcher.
+     */
+    orgStore?: OrgStore;
     /**
      * Generates session ids. Defaults to `crypto.randomUUID()`.
      * Provide a custom function for deterministic ids in tests.
@@ -19,6 +39,12 @@ export interface CreateServerOptions {
      * a separate platform token, never crossed with workspace API keys.
      */
     admin?: AdminOptions;
+    /**
+     * Origins allowed to make credentialed (cookie-bearing) requests to
+     * /auth/* and /v1/*. engram-web's URL goes here. When unset, CORS
+     * is not applied (api-key callers don't need it).
+     */
+    corsOrigins?: string[];
 }
 /**
  * Build the engram HTTP app. Wiring only: this sets up cross-cutting