@hexis-ai/engram-server 0.11.3 → 0.13.0

package/dist/routes/orgs.js

@@ -0,0 +1,185 @@
+/**
+ * Cookie-auth org self-service routes (Wave G5).
+ *
+ * Auth gating only — the underlying logic lives in services/orgs.ts so
+ * the admin-token surface (`/admin/v1/orgs/*`) can call the same code
+ * without duplicating it.
+ *
+ * Mount BEFORE the workspace gate in src/server.ts; these endpoints
+ * have their own membership check and a chosen workspace would be
+ * irrelevant noise.
+ */
+import { Hono } from "hono";
+import { addMember, createWorkspaceUnderOrg, OrgServiceError, removeMember, revokeWorkspaceKey, updateOrg, updateOrgWorkspace, } from "../services/orgs";
+const WRITE_ROLES = new Set(["owner", "admin"]);
+export function orgsRoutes(opts) {
+    const app = new Hono();
+    const deps = { orgStore: opts.orgStore, keyStore: opts.keyStore };
+    const requireMember = async (req, orgId, minRole = "member") => {
+        const s = await opts.authHandler.api
+            .getSession({ headers: req.headers })
+            .catch(() => null);
+        if (!s?.user)
+            return jsonResponse(401, "unauthorized");
+        const memberships = await opts.orgStore.listOrgsForUser(s.user.id);
+        const here = memberships.find((m) => m.orgId === orgId);
+        if (!here)
+            return jsonResponse(403, "forbidden");
+        if (minRole !== "member" && !WRITE_ROLES.has(here.role)) {
+            return jsonResponse(403, "forbidden");
+        }
+        return { user: { id: s.user.id }, role: here.role };
+    };
+    // ---------- org ---------------------------------------------
+    app.get("/v1/orgs/:id", async (c) => {
+        const gate = await requireMember(c.req.raw, c.req.param("id"));
+        if (gate instanceof Response)
+            return gate;
+        const org = await opts.orgStore.getOrg(c.req.param("id"));
+        if (!org)
+            return c.json({ error: "org_not_found" }, 404);
+        return c.json({ org, role: gate.role });
+    });
+    app.patch("/v1/orgs/:id", async (c) => {
+        const id = c.req.param("id");
+        const gate = await requireMember(c.req.raw, id, "admin");
+        if (gate instanceof Response)
+            return gate;
+        return runService(c, async () => {
+            const body = (await c.req.json().catch(() => ({})));
+            const org = await updateOrg(deps, id, body);
+            return c.json({ org });
+        });
+    });
+    // ---------- members -----------------------------------------
+    app.get("/v1/orgs/:id/members", async (c) => {
+        const gate = await requireMember(c.req.raw, c.req.param("id"));
+        if (gate instanceof Response)
+            return gate;
+        return c.json({ members: await opts.orgStore.listMembers(c.req.param("id")) });
+    });
+    app.post("/v1/orgs/:id/members", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        return runService(c, async () => {
+            const body = (await c.req.json().catch(() => ({})));
+            const member = await addMember(deps, orgId, body);
+            return c.json({ member });
+        });
+    });
+    app.delete("/v1/orgs/:id/members/:userId", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        return runService(c, async () => {
+            await removeMember(deps, orgId, c.req.param("userId"));
+            return c.body(null, 204);
+        });
+    });
+    // ---------- workspaces -------------------------------------
+    app.get("/v1/orgs/:id/workspaces", async (c) => {
+        const gate = await requireMember(c.req.raw, c.req.param("id"));
+        if (gate instanceof Response)
+            return gate;
+        const workspaces = await opts.orgStore.listWorkspacesForOrg(c.req.param("id"));
+        return c.json({ workspaces });
+    });
+    app.patch("/v1/orgs/:id/workspaces/:wsId", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        const wsId = c.req.param("wsId");
+        const ok = await opts.orgStore.userCanAccessWorkspace(gate.user.id, wsId);
+        if (!ok)
+            return c.json({ error: "workspace_not_in_org" }, 404);
+        return runService(c, async () => {
+            const body = (await c.req.json().catch(() => ({})));
+            return c.json(await updateOrgWorkspace(deps, orgId, wsId, body));
+        });
+    });
+    app.delete("/v1/orgs/:id/workspaces/:wsId", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        const wsId = c.req.param("wsId");
+        const ok = await opts.orgStore.userCanAccessWorkspace(gate.user.id, wsId);
+        if (!ok)
+            return c.json({ error: "workspace_not_in_org" }, 404);
+        await opts.keyStore.deleteWorkspace(wsId);
+        return c.body(null, 204);
+    });
+    app.post("/v1/orgs/:id/workspaces", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        return runService(c, async () => {
+            const body = (await c.req.json().catch(() => ({})));
+            return c.json(await createWorkspaceUnderOrg(deps, orgId, body));
+        });
+    });
+    // ---------- api keys (scoped to a workspace) ----------------
+    app.get("/v1/orgs/:id/workspaces/:wsId/keys", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        const wsId = c.req.param("wsId");
+        const ok = await opts.orgStore.userCanAccessWorkspace(gate.user.id, wsId);
+        if (!ok)
+            return c.json({ error: "workspace_not_in_org" }, 404);
+        return c.json({ keys: await opts.keyStore.listKeys(wsId) });
+    });
+    app.post("/v1/orgs/:id/workspaces/:wsId/keys", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        const wsId = c.req.param("wsId");
+        const ok = await opts.orgStore.userCanAccessWorkspace(gate.user.id, wsId);
+        if (!ok)
+            return c.json({ error: "workspace_not_in_org" }, 404);
+        const body = (await c.req.json().catch(() => ({})));
+        const key = await opts.keyStore.issueKey(wsId, {
+            ...(body.name !== undefined ? { name: body.name } : {}),
+        });
+        return c.json(key);
+    });
+    app.delete("/v1/orgs/:id/workspaces/:wsId/keys/:keyId", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        const wsId = c.req.param("wsId");
+        const ok = await opts.orgStore.userCanAccessWorkspace(gate.user.id, wsId);
+        if (!ok)
+            return c.json({ error: "workspace_not_in_org" }, 404);
+        return runService(c, async () => {
+            await revokeWorkspaceKey(deps, wsId, c.req.param("keyId"));
+            return c.body(null, 204);
+        });
+    });
+    return app;
+}
+function jsonResponse(status, error) {
+    return new Response(JSON.stringify({ error }), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}
+/** 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/schemas.d.ts

@@ -161,6 +161,24 @@ export declare const createWorkspaceSchema: z.ZodObject<{
 export declare const issueKeySchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+export declare const createOrgSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const orgPatchSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const workspacePatchSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const addMemberSchema: z.ZodObject<{
+    userId: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 /**
  * Read and validate a JSON request body. Returns the parsed value, or a
  * `Response` (400) the caller should return as-is:

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

@@ -1,9 +1,42 @@
 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";
+import type { KeyStore } from "./key-store";
 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.
+     *
+     * 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.
@@ -19,6 +52,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

package/dist/server.js

@@ -1,4 +1,5 @@
 import { Hono } from "hono";
+import { cors } from "hono/cors";
 import { log, newRequestId } from "./logger";
 import { createAdminRouter } from "./admin";
 import { aliasesRoutes } from "./routes/aliases";
@@ -6,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
@@ -39,6 +42,28 @@ export function createServer(opts) {
             });
         }
     });
+    // CORS — required so engram-web (different origin) can carry the
+    // auth cookie. Applies to /auth/* and /v1/* only; admin uses a
+    // bearer token from server-side callers and doesn't need CORS.
+    if (opts.corsOrigins && opts.corsOrigins.length > 0) {
+        const origins = opts.corsOrigins;
+        const corsMw = cors({
+            origin: (o) => (origins.includes(o) ? o : null),
+            credentials: true,
+            allowMethods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+            allowHeaders: [
+                "content-type",
+                "x-api-key",
+                "x-workspace-id",
+                "x-request-id",
+                "authorization",
+            ],
+            exposeHeaders: ["x-request-id"],
+            maxAge: 600,
+        });
+        app.use("/auth/*", corsMw);
+        app.use("/v1/*", corsMw);
+    }
     app.onError((err, c) => {
         log.error("unhandled", {
             request_id: c.var.request_id,
@@ -68,24 +93,77 @@ 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));
     }
-    // Workspace auth gate — every `/v1/*` route runs behind this.
+    // better-auth catchall. Mounted before `/v1` so /auth/* never falls
+    // through to the workspace gate.
+    if (opts.authHandler) {
+        const handler = opts.authHandler;
+        app.all("/auth/*", (c) => handler.handler(c.req.raw));
+    }
+    // Cookie-auth helpers for engram-web: list every workspace / org
+    // 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 handler = opts.authHandler;
+        const orgStore = opts.orgStore;
+        const requireUser = async (req) => {
+            const s = await handler.api.getSession({ headers: req.headers }).catch(() => null);
+            return s?.user ?? null;
+        };
+        app.get("/v1/me/workspaces", async (c) => {
+            const user = await requireUser(c.req.raw);
+            if (!user)
+                return c.json({ error: "unauthorized" }, 401);
+            const workspaces = await orgStore.listWorkspacesForUser(user.id);
+            return c.json({ workspaces });
+        });
+        app.get("/v1/me/orgs", async (c) => {
+            const user = await requireUser(c.req.raw);
+            if (!user)
+                return c.json({ error: "unauthorized" }, 401);
+            const memberships = await orgStore.listOrgsForUser(user.id);
+            const orgs = await Promise.all(memberships.map(async (m) => ({
+                ...(await orgStore.getOrg(m.orgId)),
+                role: m.role,
+            })));
+            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];
-        if (!apiKey)
-            return c.json({ error: "unauthorized" }, 401);
-        const ctx = await opts.auth(apiKey);
+        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 key resolves to.
-    // Used by host clients (e.g. monet's `/v1/engram/*` proxy) to label
-    // which tenant they're viewing.
+    // 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));

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