@hexis-ai/engram-server 0.1.4 → 0.1.5

package/dist/adapters/postgres.js

@@ -6,10 +6,15 @@ CREATE TABLE IF NOT EXISTS engram_sessions (
   title         TEXT,
   channel       TEXT,
   participants  TEXT[]    NOT NULL DEFAULT '{}',
+  viewable_by   TEXT[]    NOT NULL DEFAULT '{}',
   created_at    TIMESTAMPTZ NOT NULL,
   PRIMARY KEY (workspace_id, id)
 );
 
+-- Existing deployments may pre-date viewable_by; backfill the column on
+-- upgrade. Idempotent.
+ALTER TABLE engram_sessions ADD COLUMN IF NOT EXISTS viewable_by TEXT[] NOT NULL DEFAULT '{}';
+
 CREATE TABLE IF NOT EXISTS engram_events (
   workspace_id TEXT NOT NULL,
   session_id   TEXT NOT NULL,
@@ -22,15 +27,49 @@ CREATE TABLE IF NOT EXISTS engram_events (
     REFERENCES engram_sessions(workspace_id, id) ON DELETE CASCADE
 );
 
+CREATE TABLE IF NOT EXISTS engram_persons (
+  workspace_id  TEXT NOT NULL,
+  id            TEXT NOT NULL,
+  display_name  TEXT,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (workspace_id, id)
+);
+
 CREATE INDEX IF NOT EXISTS idx_engram_sessions_workspace_created
   ON engram_sessions (workspace_id, created_at DESC);
+
+-- Person-axis lookups. GIN supports the @> contains operator efficiently.
+CREATE INDEX IF NOT EXISTS idx_engram_sessions_participants
+  ON engram_sessions USING GIN (participants);
+CREATE INDEX IF NOT EXISTS idx_engram_sessions_viewable_by
+  ON engram_sessions USING GIN (viewable_by);
+
+CREATE INDEX IF NOT EXISTS idx_engram_persons_updated
+  ON engram_persons (workspace_id, updated_at DESC);
 `;
+/**
+ * 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;
+}
 export class PostgresAdapter {
     workspaceId;
     sql;
+    newPersonId;
     constructor(opts) {
         this.workspaceId = opts.workspaceId;
         this.sql = opts.sql;
+        this.newPersonId = opts.newPersonId ?? defaultPersonId;
     }
     /**
      * Create the schema. Call once at boot. Safe to invoke repeatedly.
@@ -39,15 +78,23 @@ export class PostgresAdapter {
     async ensureSchema() {
         await this.sql.unsafe(SCHEMA_SQL);
     }
+    // --- Sessions -----------------------------------------------------
     async createSession(init) {
+        const participants = init.participants ?? [];
+        // viewable_by defaults to participants if omitted; if supplied, union
+        // with participants so participants ⊆ viewable_by always holds.
+        const viewableBy = init.viewable_by
+            ? Array.from(new Set([...init.viewable_by, ...participants]))
+            : [...participants];
         await this.sql `
-      INSERT INTO engram_sessions (workspace_id, id, title, channel, participants, created_at)
+      INSERT INTO engram_sessions (workspace_id, id, title, channel, participants, viewable_by, created_at)
       VALUES (
         ${this.workspaceId},
         ${init.id},
         ${init.title ?? null},
         ${init.channel ?? null},
-        ${init.participants ?? []},
+        ${participants},
+        ${viewableBy},
         ${init.createdAt}
       )
       ON CONFLICT (workspace_id, id) DO NOTHING
@@ -57,10 +104,6 @@ export class PostgresAdapter {
         if (events.length === 0)
             return;
         for (const ev of events) {
-            // Pass the event object directly: postgres serializes JS objects as
-            // JSON for jsonb columns. Doing JSON.stringify ourselves then casting
-            // ::jsonb produced a doubly-encoded string value (jsonb containing
-            // a string instead of an object).
             await this.sql `
         INSERT INTO engram_events (workspace_id, session_id, seq, type, at, payload)
         VALUES (
@@ -73,11 +116,26 @@ export class PostgresAdapter {
         )
         ON CONFLICT (workspace_id, session_id, seq) DO NOTHING
       `;
+            // Participant events also widen the session's participants array so
+            // a one-shot listSessions can answer "who took part" without folding
+            // events at read time. viewable_by widens too (participants ⊆ viewable_by).
+            if (ev.type === "participant") {
+                await this.sql `
+          UPDATE engram_sessions
+          SET participants = (
+                SELECT ARRAY(SELECT DISTINCT unnest(participants || ARRAY[${ev.personId}]::text[]))
+              ),
+              viewable_by  = (
+                SELECT ARRAY(SELECT DISTINCT unnest(viewable_by || ARRAY[${ev.personId}]::text[]))
+              )
+          WHERE workspace_id = ${this.workspaceId} AND id = ${sessionId}
+        `;
+            }
         }
     }
     async getSession(sessionId) {
         const rows = await this.sql `
-      SELECT id, title, channel, participants, created_at
+      SELECT id, title, channel, participants, viewable_by, created_at
       FROM engram_sessions
       WHERE workspace_id = ${this.workspaceId} AND id = ${sessionId}
       LIMIT 1
@@ -95,6 +153,7 @@ export class PostgresAdapter {
             ...(r.title ? { title: r.title } : {}),
             ...(r.channel ? { channel: r.channel } : {}),
             participants: r.participants,
+            viewable_by: r.viewable_by,
             createdAt: typeof r.created_at === "string" ? r.created_at : r.created_at.toISOString(),
         };
         return foldEvents(row, events.map((e) => e.payload), new Date());
@@ -111,4 +170,113 @@ export class PostgresAdapter {
         const sessions = await Promise.all(rows.map((r) => this.getSession(r.id)));
         return sessions.filter((s) => s !== null);
     }
+    async sessionsForPerson(personId, opts) {
+        const channelFilter = opts.channel ?? null;
+        const scope = opts.scope ?? "participant";
+        // Identifier (column name) can't be parameterized in tagged templates,
+        // so branch the query. Both arms are otherwise identical.
+        const rows = scope === "viewable"
+            ? await this.sql `
+          SELECT id FROM engram_sessions
+          WHERE workspace_id = ${this.workspaceId}
+            AND viewable_by @> ARRAY[${personId}]::text[]
+            AND (${channelFilter}::text IS NULL OR channel = ${channelFilter}::text)
+          ORDER BY created_at DESC
+          LIMIT ${opts.limit}
+        `
+            : await this.sql `
+          SELECT id FROM engram_sessions
+          WHERE workspace_id = ${this.workspaceId}
+            AND participants @> ARRAY[${personId}]::text[]
+            AND (${channelFilter}::text IS NULL OR channel = ${channelFilter}::text)
+          ORDER BY created_at DESC
+          LIMIT ${opts.limit}
+        `;
+        const sessions = await Promise.all(rows.map((r) => this.getSession(r.id)));
+        return sessions.filter((s) => s !== null);
+    }
+    // --- Persons ------------------------------------------------------
+    async createPerson(input) {
+        const id = this.newPersonId();
+        return this.upsertPerson(id, input);
+    }
+    async upsertPerson(id, input) {
+        const rows = await this.sql `
+      INSERT INTO engram_persons (workspace_id, id, display_name)
+      VALUES (${this.workspaceId}, ${id}, ${input.display_name ?? null})
+      ON CONFLICT (workspace_id, id) DO UPDATE SET
+        display_name = COALESCE(EXCLUDED.display_name, engram_persons.display_name),
+        updated_at   = now()
+      RETURNING id, display_name, created_at, updated_at
+    `;
+        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 rows = await this.sql `
+      UPDATE engram_persons
+      SET display_name = CASE WHEN ${nameProvided} THEN ${patch.display_name ?? null} ELSE display_name END,
+          updated_at   = now()
+      WHERE workspace_id = ${this.workspaceId} AND id = ${id}
+      RETURNING id, display_name, created_at, updated_at
+    `;
+        if (rows.length === 0)
+            return null;
+        return toPersonInfo(rows[0]);
+    }
+    async getPerson(id) {
+        const rows = await this.sql `
+      SELECT id, display_name, created_at, updated_at
+      FROM engram_persons
+      WHERE workspace_id = ${this.workspaceId} AND id = ${id}
+      LIMIT 1
+    `;
+        if (rows.length === 0)
+            return null;
+        return toPersonInfo(rows[0]);
+    }
+    async getPersons(ids) {
+        if (ids.length === 0)
+            return [];
+        const rows = await this.sql `
+      SELECT id, display_name, created_at, updated_at
+      FROM engram_persons
+      WHERE workspace_id = ${this.workspaceId}
+        AND id = ANY(${ids}::text[])
+    `;
+        return rows.map(toPersonInfo);
+    }
+    async listPersons(opts) {
+        const q = opts.q?.trim() ?? "";
+        if (q) {
+            const pattern = `%${q.toLowerCase()}%`;
+            const rows = await this.sql `
+        SELECT id, display_name, created_at, updated_at
+        FROM engram_persons
+        WHERE workspace_id = ${this.workspaceId}
+          AND (lower(id) LIKE ${pattern} OR lower(coalesce(display_name, '')) LIKE ${pattern})
+        ORDER BY updated_at DESC
+        LIMIT ${opts.limit}
+      `;
+            return rows.map(toPersonInfo);
+        }
+        const rows = await this.sql `
+      SELECT id, display_name, created_at, updated_at
+      FROM engram_persons
+      WHERE workspace_id = ${this.workspaceId}
+      ORDER BY updated_at DESC
+      LIMIT ${opts.limit}
+    `;
+        return rows.map(toPersonInfo);
+    }
+}
+function toPersonInfo(r) {
+    const toIso = (v) => (typeof v === "string" ? v : v.toISOString());
+    return {
+        id: r.id,
+        display_name: r.display_name,
+        created_at: toIso(r.created_at),
+        updated_at: toIso(r.updated_at),
+    };
 }

package/dist/admin.d.ts

@@ -0,0 +1,21 @@
+import { Hono } from "hono";
+import { type KeyStore } from "./key-store";
+export interface AdminOptions {
+    /** Bearer token required for every /admin/v1 request. */
+    token: string;
+    keyStore: KeyStore;
+}
+interface Env {
+    Variables: {
+        request_id: string;
+    };
+}
+/**
+ * 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.
+ */
+export declare function createAdminRouter(opts: AdminOptions): Hono<Env>;
+export {};

package/dist/admin.js

@@ -0,0 +1,99 @@
+import { Hono } from "hono";
+import { isValidWorkspaceId } from "./key-store";
+/**
+ * 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.
+ */
+export function createAdminRouter(opts) {
+    const app = new Hono();
+    app.use("*", async (c, next) => {
+        const supplied = c.req.header("x-admin-token") ??
+            c.req.header("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1];
+        if (!supplied || supplied !== opts.token) {
+            return c.json({ error: "unauthorized" }, 401);
+        }
+        await next();
+    });
+    app.post("/workspaces", async (c) => {
+        const body = (await c.req.json().catch(() => null));
+        if (body === null)
+            return c.json({ error: "invalid_json" }, 400);
+        if (body.id !== undefined && !isValidWorkspaceId(body.id)) {
+            return c.json({ error: "invalid_workspace_id" }, 400);
+        }
+        try {
+            const ws = await opts.keyStore.createWorkspace({
+                ...(body.id !== undefined ? { id: body.id } : {}),
+                ...(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 });
+            }
+            const key = await opts.keyStore.issueKey(ws.id, {
+                ...(body.keyName !== undefined ? { name: body.keyName } : {}),
+            });
+            return c.json({ workspace: ws, key });
+        }
+        catch (e) {
+            return c.json({ error: e.message }, 400);
+        }
+    });
+    app.get("/workspaces", async (c) => {
+        const workspaces = await opts.keyStore.listWorkspaces();
+        return c.json({ workspaces });
+    });
+    app.get("/workspaces/:id", async (c) => {
+        const ws = await opts.keyStore.getWorkspace(c.req.param("id"));
+        if (!ws)
+            return c.json({ error: "workspace_not_found" }, 404);
+        return c.json(ws);
+    });
+    app.delete("/workspaces/:id", async (c) => {
+        const id = c.req.param("id");
+        const ws = await opts.keyStore.getWorkspace(id);
+        if (!ws)
+            return c.json({ error: "workspace_not_found" }, 404);
+        await opts.keyStore.deleteWorkspace(id);
+        return c.body(null, 204);
+    });
+    app.post("/workspaces/:id/keys", async (c) => {
+        const workspaceId = c.req.param("id");
+        const ws = await opts.keyStore.getWorkspace(workspaceId);
+        if (!ws)
+            return c.json({ error: "workspace_not_found" }, 404);
+        const body = (await c.req.json().catch(() => ({})));
+        const key = await opts.keyStore.issueKey(workspaceId, {
+            ...(body.name !== undefined ? { name: body.name } : {}),
+        });
+        return c.json(key);
+    });
+    app.get("/workspaces/:id/keys", async (c) => {
+        const workspaceId = c.req.param("id");
+        const ws = await opts.keyStore.getWorkspace(workspaceId);
+        if (!ws)
+            return c.json({ error: "workspace_not_found" }, 404);
+        const keys = await opts.keyStore.listKeys(workspaceId);
+        return c.json({ keys });
+    });
+    app.delete("/workspaces/:id/keys/:keyId", async (c) => {
+        const workspaceId = c.req.param("id");
+        const keyId = c.req.param("keyId");
+        try {
+            await opts.keyStore.revokeKey(workspaceId, keyId);
+        }
+        catch (e) {
+            if (e.message === "key_not_found") {
+                return c.json({ error: "key_not_found" }, 404);
+            }
+            throw e;
+        }
+        return c.body(null, 204);
+    });
+    return app;
+}

package/dist/index.d.ts

@@ -2,3 +2,7 @@ export { createServer, type CreateServerOptions, type AuthResolver, type Workspa
 export { foldEvents, type StorageAdapter, type SessionRow, } from "./storage";
 export { InMemoryAdapter } from "./adapters/memory";
 export { PostgresAdapter, type PostgresAdapterOptions, type SqlClient, } from "./adapters/postgres";
+export { type KeyStore, type Workspace, type ApiKeyInfo, type IssuedKey, type KeyResolution, generateRawKey, hashKey, keyPrefix, isValidWorkspaceId, } from "./key-store";
+export { InMemoryKeyStore } from "./adapters/memory-key-store";
+export { PostgresKeyStore } from "./adapters/postgres-key-store";
+export { createAdminRouter, type AdminOptions } from "./admin";

package/dist/index.js

@@ -2,3 +2,7 @@ export { createServer, } from "./server";
 export { foldEvents, } from "./storage";
 export { InMemoryAdapter } from "./adapters/memory";
 export { PostgresAdapter, } from "./adapters/postgres";
+export { generateRawKey, hashKey, keyPrefix, isValidWorkspaceId, } from "./key-store";
+export { InMemoryKeyStore } from "./adapters/memory-key-store";
+export { PostgresKeyStore } from "./adapters/postgres-key-store";
+export { createAdminRouter } from "./admin";

package/dist/key-store.d.ts

@@ -0,0 +1,63 @@
+/**
+ * KeyStore owns the workspace + API key registry. It is separate from the
+ * session StorageAdapter so the two can scale (and be persisted) independently.
+ *
+ * Wire format for raw keys: `eng_<32-bytes-base64url>`. Only the SHA-256 hash
+ * is persisted — the plaintext key is returned exactly once on issuance.
+ */
+export interface Workspace {
+    id: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+}
+export interface ApiKeyInfo {
+    id: string;
+    workspaceId: string;
+    prefix: string;
+    name?: string;
+    createdAt: string;
+    lastUsedAt?: string;
+    revokedAt?: string;
+}
+export interface IssuedKey extends ApiKeyInfo {
+    /** Plaintext key. Returned only at creation; never re-derivable. */
+    raw: string;
+}
+export interface KeyResolution {
+    workspaceId: string;
+    keyId: string;
+}
+export interface KeyStore {
+    createWorkspace(input: {
+        id?: string;
+        name?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Workspace>;
+    getWorkspace(id: string): Promise<Workspace | null>;
+    listWorkspaces(): Promise<Workspace[]>;
+    /** Hard delete: cascades to keys, sessions, and events for this workspace. */
+    deleteWorkspace(id: string): Promise<void>;
+    issueKey(workspaceId: string, opts?: {
+        name?: string;
+    }): Promise<IssuedKey>;
+    listKeys(workspaceId: string): Promise<ApiKeyInfo[]>;
+    revokeKey(workspaceId: string, keyId: string): Promise<void>;
+    /**
+     * Verify a raw bearer token. Returns the workspace it belongs to, or null
+     * if unknown or revoked. Implementations may update last_used_at as a
+     * best-effort side effect.
+     */
+    resolveKey(rawKey: string): Promise<KeyResolution | null>;
+    /**
+     * Register a pre-existing raw key under a workspace. Used at bootstrap to
+     * preserve a legacy `ENGRAM_API_KEY` without forcing a re-provisioning of
+     * existing callers. Idempotent on (workspace_id, key_hash).
+     */
+    registerLegacyKey(workspaceId: string, rawKey: string, name?: string): Promise<void>;
+}
+export declare const KEY_PREFIX = "eng_";
+export declare function generateRawKey(): string;
+export declare function hashKey(raw: string): string;
+export declare function keyPrefix(raw: string): string;
+export declare function isValidWorkspaceId(id: string): boolean;

package/dist/key-store.js

@@ -0,0 +1,17 @@
+import { createHash, randomBytes } from "node:crypto";
+export const KEY_PREFIX = "eng_";
+const RANDOM_BYTES = 32;
+const PREFIX_DISPLAY_LEN = KEY_PREFIX.length + 8;
+const WORKSPACE_ID_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+export function generateRawKey() {
+    return `${KEY_PREFIX}${randomBytes(RANDOM_BYTES).toString("base64url")}`;
+}
+export function hashKey(raw) {
+    return createHash("sha256").update(raw).digest("hex");
+}
+export function keyPrefix(raw) {
+    return raw.slice(0, PREFIX_DISPLAY_LEN);
+}
+export function isValidWorkspaceId(id) {
+    return WORKSPACE_ID_RE.test(id);
+}

package/dist/main.js

@@ -1,53 +1,91 @@
 /**
  * Production entrypoint.
  *
- * Reads configuration from environment:
+ * Required env:
+ *   ENGRAM_ADMIN_TOKEN  platform-level bearer for `/admin/v1/*`. Treat as a
+ *                       root credential — anyone with it can mint workspaces
+ *                       and API keys.
  *
- *   ENGRAM_API_KEY      required        single bearer key. Multi-tenant deploys
- *                                       should swap this for a real key store.
- *   PORT                default 8080    HTTP listen port.
- *   DATABASE_URL        optional        if set, uses PostgresAdapter; otherwise
- *                                       falls back to InMemoryAdapter (NOT
- *                                       durable across restarts).
- *   DATABASE_SOCKET_PATH optional       Cloud SQL Auth Proxy unix socket dir.
- *                                       When set, postgres connects via
- *                                       `host=<DATABASE_SOCKET_PATH>`.
- *   ENGRAM_WORKSPACE_ID default "default"
- *                                       workspace id baked into the postgres
- *                                       adapter for this single-tenant deploy.
+ * Optional env:
+ *   PORT                       default 8080
+ *   DATABASE_URL               if unset, falls back to InMemoryKeyStore +
+ *                              InMemoryAdapter (NOT durable across restarts)
+ *   DATABASE_SOCKET_PATH       Cloud SQL Auth Proxy unix socket dir
+ *   ENGRAM_API_KEY             legacy single-tenant key. When set, a workspace
+ *                              identified by ENGRAM_WORKSPACE_ID is created on
+ *                              boot and this raw key is registered against it,
+ *                              keeping existing single-tenant deploys working
+ *                              while the multi-tenant flow rolls out.
+ *   ENGRAM_WORKSPACE_ID        default "default" — the workspace id used for
+ *                              the legacy bootstrap above.
  */
 import { createServer } from "./server";
 import { InMemoryAdapter } from "./adapters/memory";
 import { PostgresAdapter } from "./adapters/postgres";
+import { InMemoryKeyStore } from "./adapters/memory-key-store";
+import { PostgresKeyStore } from "./adapters/postgres-key-store";
 const PORT = Number(process.env.PORT ?? 8080);
-const API_KEY = process.env.ENGRAM_API_KEY;
-const WORKSPACE_ID = process.env.ENGRAM_WORKSPACE_ID ?? "default";
+const ADMIN_TOKEN = process.env.ENGRAM_ADMIN_TOKEN;
+const LEGACY_API_KEY = process.env.ENGRAM_API_KEY;
+const LEGACY_WORKSPACE_ID = process.env.ENGRAM_WORKSPACE_ID ?? "default";
 const DATABASE_URL = process.env.DATABASE_URL;
 const DATABASE_SOCKET_PATH = process.env.DATABASE_SOCKET_PATH;
-if (!API_KEY) {
-    console.error("[engram-server] ENGRAM_API_KEY is required");
+if (!ADMIN_TOKEN) {
+    console.error("[engram-server] ENGRAM_ADMIN_TOKEN is required");
     process.exit(1);
 }
-const storage = await (async () => {
-    if (!DATABASE_URL) {
-        console.warn("[engram-server] DATABASE_URL not set — using InMemoryAdapter (data is volatile)");
-        return new InMemoryAdapter();
-    }
-    // postgres is a peer dep so we import it lazily; absence is a hard error here.
-    const { default: postgres } = await import("postgres");
-    const sql = DATABASE_SOCKET_PATH
-        ? postgres(DATABASE_URL, { host: DATABASE_SOCKET_PATH })
-        : postgres(DATABASE_URL);
-    const adapter = new PostgresAdapter({
-        workspaceId: WORKSPACE_ID,
-        sql: sql,
-    });
-    await adapter.ensureSchema();
-    console.log(`[engram-server] postgres adapter ready (workspace=${WORKSPACE_ID})`);
-    return adapter;
-})();
+const { keyStore, getStorage } = await buildStores();
+if (LEGACY_API_KEY) {
+    await keyStore.createWorkspace({ id: LEGACY_WORKSPACE_ID, name: "Legacy" });
+    await keyStore.registerLegacyKey(LEGACY_WORKSPACE_ID, LEGACY_API_KEY, "ENGRAM_API_KEY");
+    console.log(`[engram-server] legacy key bootstrapped (workspace=${LEGACY_WORKSPACE_ID})`);
+}
 const app = createServer({
-    auth: (key) => (key === API_KEY ? { workspaceId: WORKSPACE_ID, storage } : null),
+    auth: async (key) => {
+        const r = await keyStore.resolveKey(key);
+        if (!r)
+            return null;
+        return { workspaceId: r.workspaceId, storage: getStorage(r.workspaceId) };
+    },
+    admin: { token: ADMIN_TOKEN, keyStore },
 });
 console.log(`[engram-server] listening on :${PORT}`);
 export default { port: PORT, fetch: app.fetch };
+async function buildStores() {
+    if (!DATABASE_URL) {
+        console.warn("[engram-server] DATABASE_URL not set — in-memory mode (data is volatile)");
+        const ks = new InMemoryKeyStore();
+        const adapters = new Map();
+        return {
+            keyStore: ks,
+            getStorage: (workspaceId) => {
+                let a = adapters.get(workspaceId);
+                if (!a) {
+                    a = new InMemoryAdapter();
+                    adapters.set(workspaceId, a);
+                }
+                return a;
+            },
+        };
+    }
+    const { default: postgres } = await import("postgres");
+    const sql = (DATABASE_SOCKET_PATH
+        ? postgres(DATABASE_URL, { host: DATABASE_SOCKET_PATH })
+        : postgres(DATABASE_URL));
+    const ks = new PostgresKeyStore(sql);
+    await ks.ensureSchema();
+    // Session schema is workspace-independent — one bootstrap call is enough.
+    await new PostgresAdapter({ workspaceId: "__bootstrap__", sql }).ensureSchema();
+    const adapters = new Map();
+    return {
+        keyStore: ks,
+        getStorage: (workspaceId) => {
+            let a = adapters.get(workspaceId);
+            if (!a) {
+                a = new PostgresAdapter({ workspaceId, sql });
+                adapters.set(workspaceId, a);
+            }
+            return a;
+        },
+    };
+}

package/dist/server.d.ts

@@ -1,5 +1,6 @@
 import { Hono } from "hono";
 import type { StorageAdapter } from "./storage";
+import { type AdminOptions } from "./admin";
 /**
  * Resolve an API key (raw `Authorization: Bearer <key>` token) into a
  * workspace context. Throwing or returning null short-circuits to 401.
@@ -25,6 +26,11 @@ export interface CreateServerOptions {
      */
     defaultListLimit?: number;
     maxListLimit?: number;
+    /**
+     * When set, mounts the admin sub-router at `/admin/v1`. Admin auth is
+     * a separate platform token, never crossed with workspace API keys.
+     */
+    admin?: AdminOptions;
 }
 interface Env {
     Variables: {