@hexis-ai/engram-server 0.12.0 → 0.13.0

package/dist/schemas.js

@@ -151,6 +151,25 @@ export const createWorkspaceSchema = z.object({
 export const issueKeySchema = z.object({
     name: z.string().optional(),
 });
+// --- Orgs (admin + self-serve share these bodies) --------------------
+export const createOrgSchema = z.object({
+    id: z.string().optional(),
+    name: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export const orgPatchSchema = z.object({
+    name: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export const workspacePatchSchema = z.object({
+    name: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export const addMemberSchema = z.object({
+    userId: z.string().optional(),
+    email: z.string().optional(),
+    role: z.string().optional(),
+});
 // --- Helper ----------------------------------------------------------
 /**
  * Read and validate a JSON request body. Returns the parsed value, or a

package/dist/server.d.ts

@@ -4,6 +4,7 @@ import type { CookieAuthResolver } from "./auth-resolver";
 import type { AuthResolver, Env } from "./context";
 import type { OrgStore } from "./org-store";
 import { type AdminOptions } from "./admin";
+import type { KeyStore } from "./key-store";
 export interface CreateServerOptions {
     /** Resolves Bearer / X-Api-Key tokens into workspace contexts. */
     auth: AuthResolver;
@@ -22,8 +23,20 @@ export interface CreateServerOptions {
      * 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.
+     *
+     * Combined with \`keyStore\` it also unlocks the cookie-auth
+     * \`/v1/orgs/:id/*\` self-service surface (members, workspaces,
+     * api keys) — see routes/orgs.ts.
      */
     orgStore?: OrgStore;
+    /**
+     * Optional: key store, shared between the admin router and the
+     * cookie-auth orgs surface. The admin router takes its own
+     * reference (\`admin.keyStore\`) for the legacy / api-key flows;
+     * this top-level handle lets \`/v1/orgs/:id/*\` issue and revoke
+     * workspace keys without the admin token.
+     */
+    keyStore?: KeyStore;
     /**
      * Generates session ids. Defaults to `crypto.randomUUID()`.
      * Provide a custom function for deterministic ids in tests.

package/dist/server.js

@@ -7,6 +7,8 @@ import { sessionsRoutes } from "./routes/sessions";
 import { personsRoutes } from "./routes/persons";
 import { identitiesRoutes } from "./routes/identities";
 import { searchRoutes } from "./routes/search";
+import { orgsRoutes } from "./routes/orgs";
+import { buildOpenApiDocument } from "./openapi";
 /**
  * Build the engram HTTP app. Wiring only: this sets up cross-cutting
  * middleware (request id + access log), the workspace auth gate, and mounts
@@ -91,6 +93,10 @@ export function createServer(opts) {
         },
     }));
     app.get("/healthz", (c) => c.json({ ok: true }));
+    // OpenAPI 3.1 document for the public /v1 surface. Served live
+    // from the same Zod schemas the server validates with, so it
+    // can't drift. engram-web's /docs renders this through Scalar.
+    app.get("/openapi.json", (c) => c.json(buildOpenApiDocument()));
     if (opts.admin) {
         app.route("/admin/v1", createAdminRouter(opts.admin));
     }
@@ -100,33 +106,15 @@ export function createServer(opts) {
         const handler = opts.authHandler;
         app.all("/auth/*", (c) => handler.handler(c.req.raw));
     }
-    // Workspace auth gate — every `/v1/*` route runs behind this. Tries
-    // api-key first; falls back to cookie session when configured. The
-    // Bearer header is reserved for api-keys here; engram-web uses the
-    // session cookie, not a Bearer.
-    app.use("/v1/*", async (c, next) => {
-        const apiKey = c.req.header("x-api-key") ??
-            c.req.header("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1];
-        let ctx = apiKey ? await opts.auth(apiKey) : null;
-        if (!ctx && !apiKey && opts.cookieAuth) {
-            ctx = await opts.cookieAuth(c.req.raw);
-        }
-        if (!ctx)
-            return c.json({ error: "unauthorized" }, 401);
-        c.set("ctx", ctx);
-        await next();
-    });
-    // Identity probe — echoes the workspace the caller's auth
-    // resolves to. Cheap, used as a health/whoami by clients.
-    app.get("/v1/me", (c) => c.json({ workspaceId: c.var.ctx.workspaceId }));
     // Cookie-auth helpers for engram-web: list every workspace / org
-    // the signed-in user can reach. api-key callers don't need these
-    // (they already know which workspace they're scoped to).
+    // the signed-in user can reach. Mounted BEFORE the workspace gate
+    // because these endpoints are how the UI chooses a workspace —
+    // gating them on x-workspace-id would deadlock new sign-ins.
     if (opts.authHandler && opts.orgStore) {
-        const auth = opts.authHandler;
+        const handler = opts.authHandler;
         const orgStore = opts.orgStore;
         const requireUser = async (req) => {
-            const s = await auth.api.getSession({ headers: req.headers }).catch(() => null);
+            const s = await handler.api.getSession({ headers: req.headers }).catch(() => null);
             return s?.user ?? null;
         };
         app.get("/v1/me/workspaces", async (c) => {
@@ -147,7 +135,36 @@ export function createServer(opts) {
             })));
             return c.json({ orgs: orgs.filter((o) => o.id) });
         });
+        // Org self-service surface (Wave G5): members, workspaces, api
+        // keys — same shape as the admin endpoints but cookie-auth +
+        // org-membership + role check.
+        if (opts.keyStore) {
+            app.route("/", orgsRoutes({
+                authHandler: handler,
+                orgStore,
+                keyStore: opts.keyStore,
+            }));
+        }
     }
+    // Workspace auth gate — every other `/v1/*` route runs behind this.
+    // Tries api-key first; falls back to cookie session when configured.
+    // The Bearer header is reserved for api-keys here; engram-web uses
+    // the session cookie, not a Bearer.
+    app.use("/v1/*", async (c, next) => {
+        const apiKey = c.req.header("x-api-key") ??
+            c.req.header("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1];
+        let ctx = apiKey ? await opts.auth(apiKey) : null;
+        if (!ctx && !apiKey && opts.cookieAuth) {
+            ctx = await opts.cookieAuth(c.req.raw);
+        }
+        if (!ctx)
+            return c.json({ error: "unauthorized" }, 401);
+        c.set("ctx", ctx);
+        await next();
+    });
+    // Identity probe — echoes the workspace the caller's auth
+    // resolves to. Cheap, used as a health/whoami by clients.
+    app.get("/v1/me", (c) => c.json({ workspaceId: c.var.ctx.workspaceId }));
     app.route("/v1", sessionsRoutes(cfg));
     app.route("/v1", personsRoutes(cfg));
     app.route("/v1", identitiesRoutes(cfg));

package/dist/services/orgs.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Org / workspace business logic shared between the admin-token surface
+ * (`/admin/v1/*`) and the cookie-auth self-service surface (`/v1/orgs/*`).
+ *
+ * Auth and HTTP framing stay in the route modules. This file owns:
+ *   - the multi-step orchestrations (createWorkspace + setWorkspaceOrg
+ *     + issueKey; email→userId lookup + upsertMember)
+ *   - the safety invariants (workspace id validation, last-owner
+ *     protection on member removal)
+ *   - the canonical error → status mapping (OrgServiceError.status)
+ *
+ * Functions throw {@link OrgServiceError} for caller errors; route
+ * handlers catch it and translate to JSON. Storage errors that aren't
+ * known caller faults propagate.
+ */
+import { type IssuedKey, type KeyStore, type Workspace } from "../key-store";
+import type { OrgMembershipRow, OrgRow, OrgStore } from "../org-store";
+export type OrgServiceErrorStatus = 400 | 403 | 404;
+/** Caller-fault errors with a stable code → status mapping. */
+export declare class OrgServiceError extends Error {
+    readonly code: string;
+    readonly status: OrgServiceErrorStatus;
+    constructor(code: string, status: OrgServiceErrorStatus);
+}
+export interface OrgServiceDeps {
+    orgStore: OrgStore;
+    keyStore: KeyStore;
+}
+export declare function getOrgOrThrow(deps: OrgServiceDeps, id: string): Promise<OrgRow>;
+export declare function createOrg(deps: OrgServiceDeps, body: {
+    id?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}): Promise<OrgRow>;
+export declare function updateOrg(deps: OrgServiceDeps, id: string, body: {
+    name?: string;
+    metadata?: Record<string, unknown>;
+}): Promise<OrgRow>;
+export declare function deleteOrg(deps: OrgServiceDeps, id: string): Promise<void>;
+export interface AddMemberInput {
+    userId?: string;
+    email?: string;
+    role?: string;
+}
+/**
+ * Resolve an email or explicit userId to a membership row, upserting at
+ * the requested role. Used by both the admin and self-serve surfaces.
+ */
+export declare function addMember(deps: OrgServiceDeps, orgId: string, input: AddMemberInput): Promise<OrgMembershipRow>;
+/**
+ * Remove a membership. Refuses to remove the org's sole remaining owner
+ * (would brick the org). Applies to admin-token callers too —
+ * `deleteOrg` is the path for tearing down an org entirely.
+ */
+export declare function removeMember(deps: OrgServiceDeps, orgId: string, userId: string): Promise<void>;
+export interface CreateWorkspaceInput {
+    id?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    /** Whether to issue an initial API key. Default true. */
+    issueKey?: boolean;
+    /** Optional name applied to the initial API key. */
+    keyName?: string;
+}
+export interface CreateWorkspaceResult {
+    workspace: Workspace & {
+        orgId: string;
+    };
+    /** Present unless `issueKey === false`. */
+    key?: IssuedKey;
+}
+/**
+ * Stand up a new workspace under an org in one round-trip:
+ *   createWorkspace → setWorkspaceOrg → (optional) issueKey.
+ *
+ * Validates the workspace id shape up front so a bad id fails before
+ * touching either store. Returns the workspace with `orgId` stamped on
+ * so callers don't need a second lookup.
+ */
+export declare function createWorkspaceUnderOrg(deps: OrgServiceDeps, orgId: string, body: CreateWorkspaceInput): Promise<CreateWorkspaceResult>;
+export declare function updateOrgWorkspace(deps: OrgServiceDeps, orgId: string, wsId: string, body: {
+    name?: string;
+    metadata?: Record<string, unknown>;
+}): Promise<{
+    workspace: Workspace & {
+        orgId: string;
+    };
+}>;
+export declare function revokeWorkspaceKey(deps: OrgServiceDeps, wsId: string, keyId: string): Promise<void>;
+/**
+ * Throw `workspace_not_in_org` (404) if the workspace's `org_id` is
+ * not `orgId`. Used by both the admin-token and cookie-auth surfaces
+ * to scope per-workspace operations to the URL's org.
+ */
+export declare function requireWorkspaceInOrg(deps: OrgServiceDeps, orgId: string, wsId: string): Promise<void>;

package/dist/services/orgs.js

@@ -0,0 +1,159 @@
+/**
+ * Org / workspace business logic shared between the admin-token surface
+ * (`/admin/v1/*`) and the cookie-auth self-service surface (`/v1/orgs/*`).
+ *
+ * Auth and HTTP framing stay in the route modules. This file owns:
+ *   - the multi-step orchestrations (createWorkspace + setWorkspaceOrg
+ *     + issueKey; email→userId lookup + upsertMember)
+ *   - the safety invariants (workspace id validation, last-owner
+ *     protection on member removal)
+ *   - the canonical error → status mapping (OrgServiceError.status)
+ *
+ * Functions throw {@link OrgServiceError} for caller errors; route
+ * handlers catch it and translate to JSON. Storage errors that aren't
+ * known caller faults propagate.
+ */
+import { isValidWorkspaceId, } from "../key-store";
+/** Caller-fault errors with a stable code → status mapping. */
+export class OrgServiceError extends Error {
+    code;
+    status;
+    constructor(code, status) {
+        super(code);
+        this.code = code;
+        this.status = status;
+    }
+}
+// ---------- orgs ---------------------------------------------------
+export async function getOrgOrThrow(deps, id) {
+    const org = await deps.orgStore.getOrg(id);
+    if (!org)
+        throw new OrgServiceError("org_not_found", 404);
+    return org;
+}
+export async function createOrg(deps, body) {
+    try {
+        return await deps.orgStore.createOrg({
+            ...(body.id !== undefined ? { id: body.id } : {}),
+            ...(body.name !== undefined ? { name: body.name } : {}),
+            ...(body.metadata !== undefined ? { metadata: body.metadata } : {}),
+        });
+    }
+    catch (e) {
+        throw new OrgServiceError(e.message, 400);
+    }
+}
+export async function updateOrg(deps, id, body) {
+    try {
+        return await deps.orgStore.updateOrg(id, body);
+    }
+    catch (e) {
+        if (e.message === "org_not_found") {
+            throw new OrgServiceError("org_not_found", 404);
+        }
+        throw e;
+    }
+}
+export async function deleteOrg(deps, id) {
+    await getOrgOrThrow(deps, id);
+    await deps.orgStore.deleteOrg(id);
+}
+/**
+ * Resolve an email or explicit userId to a membership row, upserting at
+ * the requested role. Used by both the admin and self-serve surfaces.
+ */
+export async function addMember(deps, orgId, input) {
+    let userId = input.userId;
+    if (!userId && input.email) {
+        const u = await deps.orgStore.findUserByEmail(input.email);
+        if (!u)
+            throw new OrgServiceError("user_not_found", 404);
+        userId = u.id;
+    }
+    if (!userId)
+        throw new OrgServiceError("userId_or_email_required", 400);
+    return await deps.orgStore.upsertMember({
+        orgId,
+        userId,
+        ...(input.role !== undefined ? { role: input.role } : {}),
+    });
+}
+/**
+ * Remove a membership. Refuses to remove the org's sole remaining owner
+ * (would brick the org). Applies to admin-token callers too —
+ * `deleteOrg` is the path for tearing down an org entirely.
+ */
+export async function removeMember(deps, orgId, userId) {
+    const members = await deps.orgStore.listMembers(orgId);
+    const owners = members.filter((m) => m.role === "owner");
+    if (owners.length === 1 && owners[0].userId === userId) {
+        throw new OrgServiceError("cannot_remove_last_owner", 400);
+    }
+    await deps.orgStore.removeMember(orgId, userId);
+}
+/**
+ * Stand up a new workspace under an org in one round-trip:
+ *   createWorkspace → setWorkspaceOrg → (optional) issueKey.
+ *
+ * Validates the workspace id shape up front so a bad id fails before
+ * touching either store. Returns the workspace with `orgId` stamped on
+ * so callers don't need a second lookup.
+ */
+export async function createWorkspaceUnderOrg(deps, orgId, body) {
+    if (body.id !== undefined && !isValidWorkspaceId(body.id)) {
+        throw new OrgServiceError("invalid_workspace_id", 400);
+    }
+    try {
+        const ws = await deps.keyStore.createWorkspace({
+            ...(body.id !== undefined ? { id: body.id } : {}),
+            ...(body.name !== undefined ? { name: body.name } : {}),
+            ...(body.metadata !== undefined ? { metadata: body.metadata } : {}),
+        });
+        await deps.orgStore.setWorkspaceOrg(ws.id, orgId);
+        if (body.issueKey === false) {
+            return { workspace: { ...ws, orgId } };
+        }
+        const key = await deps.keyStore.issueKey(ws.id, {
+            ...(body.keyName !== undefined ? { name: body.keyName } : {}),
+        });
+        return { workspace: { ...ws, orgId }, key };
+    }
+    catch (e) {
+        if (e instanceof OrgServiceError)
+            throw e;
+        throw new OrgServiceError(e.message, 400);
+    }
+}
+export async function updateOrgWorkspace(deps, orgId, wsId, body) {
+    try {
+        const ws = await deps.keyStore.updateWorkspace(wsId, body);
+        return { workspace: { ...ws, orgId } };
+    }
+    catch (e) {
+        if (e.message === "workspace_not_found") {
+            throw new OrgServiceError("workspace_not_found", 404);
+        }
+        throw e;
+    }
+}
+export async function revokeWorkspaceKey(deps, wsId, keyId) {
+    try {
+        await deps.keyStore.revokeKey(wsId, keyId);
+    }
+    catch (e) {
+        if (e.message === "key_not_found") {
+            throw new OrgServiceError("key_not_found", 404);
+        }
+        throw e;
+    }
+}
+/**
+ * Throw `workspace_not_in_org` (404) if the workspace's `org_id` is
+ * not `orgId`. Used by both the admin-token and cookie-auth surfaces
+ * to scope per-workspace operations to the URL's org.
+ */
+export async function requireWorkspaceInOrg(deps, orgId, wsId) {
+    if (!(await deps.orgStore.workspaceInOrg(orgId, wsId))) {
+        throw new OrgServiceError("workspace_not_in_org", 404);
+    }
+}

package/dist/storage.d.ts

@@ -149,3 +149,9 @@ export interface SessionRow {
     trigger_event_id?: string;
 }
 export declare function foldEvents(row: SessionRow, events: SessionEvent[], now: Date): Session;
+/**
+ * Allocate a fresh person id (`p_` + 8 alphanumeric chars). Cryptographically
+ * random via `crypto.getRandomValues`; shared between every adapter so id
+ * shape and entropy stay aligned.
+ */
+export declare function newPersonId(): string;

package/dist/storage.js

@@ -38,3 +38,17 @@ export function foldEvents(row, events, now) {
         updated_at: row.updatedAt,
     };
 }
+const PERSON_ID_ALPHA = "abcdefghijklmnopqrstuvwxyz0123456789";
+/**
+ * Allocate a fresh person id (`p_` + 8 alphanumeric chars). Cryptographically
+ * random via `crypto.getRandomValues`; shared between every adapter so id
+ * shape and entropy stay aligned.
+ */
+export function newPersonId() {
+    const buf = new Uint8Array(8);
+    crypto.getRandomValues(buf);
+    let out = "p_";
+    for (const b of buf)
+        out += PERSON_ID_ALPHA[b % PERSON_ID_ALPHA.length];
+    return out;
+}