create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/routes/workspaces/config.ts

@@ -0,0 +1,125 @@
+// oss: false
+/**
+ * Workspace site-config routes (multi-tenant module — FEAT-042; STC-P4 #3634).
+ *
+ * The write surface an end-tenant uses to theme THEIR OWN workspace at runtime:
+ *
+ *   GET /v1/workspaces/:workspaceId/theme     · PUT /v1/workspaces/:workspaceId/theme
+ *   GET /v1/workspaces/:workspaceId/identity  · PUT /v1/workspaces/:workspaceId/identity
+ *   GET /v1/workspaces/:workspaceId/seo       · PUT /v1/workspaces/:workspaceId/seo
+ *
+ * All tenant-guarded (tenantPreHandlerPlugin runs first): the cross-workspace
+ * 403 is enforced by the guard's `params.workspaceId ≠ resolved` check BEFORE
+ * any handler runs — no config query executes for a foreign workspace. The
+ * scope is ALWAYS `request.tenant.workspaceId` (server-resolved from the
+ * validated session); no handler reads a scope from the body/query. Each config
+ * model is `workspaceId @unique`, so the `tenantDb` accessor's
+ * `findUnique`/`upsert` on `{ workspaceId }` is inherently tenant-scoped.
+ *
+ * PUT validates the body against the shared @working-theory/site-config schema
+ * (400 on failure) and stores the validated blob in the `data` Json column. GET
+ * returns the stored blob, or `{ ok: true, data: null }` for a not-yet-configured
+ * workspace (a valid runtime state — the render/seed default is Phase 5).
+ *
+ * Envelope per apps/api/CLAUDE.md: `{ ok: true, data }` /
+ * `{ ok: false, error: { code, message } }`, real HTTP status codes.
+ *
+ * MCP parity note: identity-bound tenant routes; the OSS MCP surface is
+ * identity-blind (apps/mcp/CLAUDE.md), so — like the sibling /v1/workspaces
+ * routes — they have no anonymous MCP twin. The tenant-scoped authed MCP
+ * surface is tracked in #3591.
+ */
+import { zWorkspaceId } from "@working-theory/ids";
+import {
+  SEOSchema,
+  SiteIdentitySchema,
+  ThemeSchema,
+} from "@working-theory/site-config/schema";
+import type { FastifyPluginAsync, FastifyReply } from "fastify";
+import type { ZodType } from "zod";
+import { z } from "zod";
+
+import { tenantDb } from "../../lib/tenant-db.js";
+import type { TenantDb } from "../../lib/tenant-db.js";
+
+function unauthorized(reply: FastifyReply) {
+  return reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required" },
+  });
+}
+
+function invalidId(reply: FastifyReply) {
+  return reply.status(400).send({
+    ok: false,
+    error: { code: "validation_failed", message: "Invalid workspace id" },
+  });
+}
+
+// Boundary id validation (ADR-0031 rule 5): the :workspaceId param must be a
+// well-formed workspace id before any handler logic runs.
+const workspaceParamsSchema = z.object({ workspaceId: zWorkspaceId });
+
+/**
+ * The three config types share one GET/PUT shape — the only per-type differences
+ * are the URL segment, the validation schema, and which `tenantDb` accessor to
+ * reach. `accessor` names a config accessor on `TenantDb` (`get` + `upsert`).
+ */
+type ConfigAccessorKey = "theme" | "siteIdentity" | "seo";
+
+interface ConfigType {
+  segment: string;
+  schema: ZodType;
+  accessor: ConfigAccessorKey;
+}
+
+const CONFIG_TYPES: ConfigType[] = [
+  { segment: "theme", schema: ThemeSchema, accessor: "theme" },
+  { segment: "identity", schema: SiteIdentitySchema, accessor: "siteIdentity" },
+  { segment: "seo", schema: SEOSchema, accessor: "seo" },
+];
+
+export const workspaceConfigRoutes: FastifyPluginAsync = async (fastify) => {
+  for (const { segment, schema, accessor } of CONFIG_TYPES) {
+    fastify.get<{ Params: { workspaceId: string } }>(
+      `/v1/workspaces/:workspaceId/${segment}`,
+      async (request, reply) => {
+        const tenant = request.tenant;
+        if (!tenant) return unauthorized(reply);
+
+        const params = workspaceParamsSchema.safeParse(request.params);
+        if (!params.success) return invalidId(reply);
+
+        const db: TenantDb = tenantDb(tenant);
+        const row = await db[accessor].get();
+        // A not-yet-configured workspace is a valid state, not an error (D6).
+        return reply.send({ ok: true, data: row?.data ?? null });
+      },
+    );
+
+    fastify.put<{ Params: { workspaceId: string } }>(
+      `/v1/workspaces/:workspaceId/${segment}`,
+      async (request, reply) => {
+        const tenant = request.tenant;
+        if (!tenant) return unauthorized(reply);
+
+        const params = workspaceParamsSchema.safeParse(request.params);
+        if (!params.success) return invalidId(reply);
+
+        // The ONLY untrusted input: validate against the shared schema. The
+        // scope is NEVER read from the body — it is tenant.workspaceId.
+        const parsed = schema.safeParse(request.body);
+        if (!parsed.success) {
+          return reply.status(400).send({
+            ok: false,
+            error: { code: "validation_failed", message: "Invalid config" },
+          });
+        }
+
+        const db: TenantDb = tenantDb(tenant);
+        const row = await db[accessor].upsert(parsed.data);
+        return reply.send({ ok: true, data: row.data });
+      },
+    );
+  }
+};

package/templates/apps/api/src/routes/workspaces/index.ts

@@ -0,0 +1,194 @@
+// oss: false
+/**
+ * Workspace routes (multi-tenant module — FEAT-042).
+ *
+ * Two registration scopes (see server.ts):
+ *
+ *   AUTH-ONLY (no tenant guard — they establish/inspect tenant context):
+ *     GET  /v1/workspaces                      — switcher listing (orgs + workspaces)
+ *     POST /v1/workspaces                      — create workspace (role admin+)
+ *     POST /v1/workspaces/:workspaceId/activate — switch active workspace
+ *
+ *   TENANT-GUARDED (tenantPreHandlerPlugin runs first; request.tenant set):
+ *     GET  /v1/workspaces/:workspaceId/sessions — list agent sessions (+unread)
+ *     POST /v1/workspaces/:workspaceId/sessions — create agent session
+ *
+ * Envelope per apps/api/CLAUDE.md: `{ ok: true, data }` /
+ * `{ ok: false, error: { code, message } }`, real HTTP status codes.
+ *
+ * MCP parity note: these are identity-bound tenant routes; the OSS MCP
+ * surface is identity-blind (apps/mcp/CLAUDE.md), so — like the existing
+ * /v1/auth/tokens and /v1/user routes — they have no anonymous MCP twin.
+ * The tenant-scoped authed MCP surface is tracked in #3591.
+ */
+import { zOrganizationId, zWorkspaceId } from "@working-theory/ids";
+import type { FastifyPluginAsync, FastifyReply } from "fastify";
+import { z } from "zod";
+
+import { tenantDb } from "../../lib/tenant-db.js";
+import {
+  activateWorkspace,
+  createWorkspace,
+  listTenancy,
+  type TenantErrorKind,
+} from "../../services/tenant-context.js";
+
+const TENANT_ERROR_STATUS: Record<TenantErrorKind, number> = {
+  forbidden: 403,
+  not_found: 404,
+  conflict: 409,
+};
+
+function sendTenantError(
+  reply: FastifyReply,
+  error: { kind: TenantErrorKind; message: string },
+) {
+  return reply.status(TENANT_ERROR_STATUS[error.kind]).send({
+    ok: false,
+    error: { code: error.kind, message: error.message },
+  });
+}
+
+function unauthorized(reply: FastifyReply) {
+  return reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required" },
+  });
+}
+
+const createWorkspaceSchema = z.object({
+  // Boundary id validation (ADR-0031 rule 5): the entity-typed Zod schema,
+  // not z.string().min(1) — a user_/wksp_ id passed here is a 400, not a query.
+  organizationId: zOrganizationId,
+  name: z.string().min(1).max(80),
+});
+
+const workspaceParamsSchema = z.object({ workspaceId: zWorkspaceId });
+
+const createSessionSchema = z.object({
+  title: z.string().min(1).max(200).optional(),
+});
+
+const listSessionsQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(50),
+});
+
+/** Auth-only workspace routes — establish/inspect tenant context. */
+export const workspaceContextRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get("/v1/workspaces", async (request, reply) => {
+    const userId = request.userId;
+    if (!userId) return unauthorized(reply);
+
+    const result = await listTenancy({
+      userId,
+      sessionTenant: request.sessionTenant,
+    });
+    if (!result.ok) return sendTenantError(reply, result.error);
+    return reply.send({ ok: true, data: result.value });
+  });
+
+  fastify.post("/v1/workspaces", async (request, reply) => {
+    const userId = request.userId;
+    if (!userId) return unauthorized(reply);
+
+    const parsed = createWorkspaceSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.status(400).send({
+        ok: false,
+        error: { code: "validation_failed", message: "Invalid workspace input" },
+      });
+    }
+
+    const result = await createWorkspace({ userId, ...parsed.data });
+    if (!result.ok) return sendTenantError(reply, result.error);
+    return reply.status(201).send({ ok: true, data: result.value });
+  });
+
+  fastify.post<{ Params: { workspaceId: string } }>(
+    "/v1/workspaces/:workspaceId/activate",
+    async (request, reply) => {
+      const userId = request.userId;
+      if (!userId) return unauthorized(reply);
+
+      const params = workspaceParamsSchema.safeParse(request.params);
+      if (!params.success) {
+        return reply.status(400).send({
+          ok: false,
+          error: { code: "validation_failed", message: "Invalid workspace id" },
+        });
+      }
+
+      const result = await activateWorkspace({
+        userId,
+        sessionTenant: request.sessionTenant,
+        workspaceId: params.data.workspaceId,
+      });
+      if (!result.ok) return sendTenantError(reply, result.error);
+      return reply.send({ ok: true, data: result.value });
+    },
+  );
+};
+
+/** Tenant-guarded, workspace-scoped domain routes. */
+export const workspaceSessionRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get<{ Params: { workspaceId: string } }>(
+    "/v1/workspaces/:workspaceId/sessions",
+    async (request, reply) => {
+      const tenant = request.tenant;
+      if (!tenant) return unauthorized(reply);
+
+      const query = listSessionsQuerySchema.safeParse(request.query ?? {});
+      if (!query.success) {
+        return reply.status(400).send({
+          ok: false,
+          error: { code: "validation_failed", message: "Invalid query" },
+        });
+      }
+
+      const db = tenantDb(tenant);
+      const [sessions, receipts] = await Promise.all([
+        db.agentSession.list(query.data.limit),
+        db.readReceipt.listForUser(),
+      ]);
+      const readBySession = new Map(
+        receipts.map((r) => [r.sessionId, r.lastReadSeq]),
+      );
+
+      return reply.send({
+        ok: true,
+        data: {
+          sessions: sessions.map((s) => ({
+            id: s.id,
+            title: s.title,
+            status: s.status,
+            lastMessageAt: s.lastMessageAt,
+            isWorking: s.status === "working",
+            hasUnread: s.lastSeq > (readBySession.get(s.id) ?? 0),
+            createdAt: s.createdAt,
+          })),
+        },
+      });
+    },
+  );
+
+  fastify.post<{ Params: { workspaceId: string } }>(
+    "/v1/workspaces/:workspaceId/sessions",
+    async (request, reply) => {
+      const tenant = request.tenant;
+      if (!tenant) return unauthorized(reply);
+
+      const parsed = createSessionSchema.safeParse(request.body ?? {});
+      if (!parsed.success) {
+        return reply.status(400).send({
+          ok: false,
+          error: { code: "validation_failed", message: "Invalid session input" },
+        });
+      }
+
+      const session = await tenantDb(tenant).agentSession.create({
+        title: parsed.data.title ?? null,
+      });
+      return reply.status(201).send({ ok: true, data: session });
+    },
+  );
+};

package/templates/apps/api/src/routes/workspaces/sessions.ts

@@ -0,0 +1,218 @@
+// oss: false
+/**
+ * Session-target routes (multi-tenant module — FEAT-042; transport contract
+ * from docs/research/ploy-capture/BACKEND-REQUIREMENTS.md §1/§3).
+ *
+ * All tenant-guarded (tenantPreHandlerPlugin): request.tenant is the caller's
+ * validated active workspace. Targets are session/artifact ids; every lookup
+ * goes through tenantDb's workspace-scoped `findFirst({ id, workspaceId })`,
+ * so a foreign-tenant target 404s exactly like a missing one — cross-org
+ * reads AND writes are denied without revealing existence.
+ *
+ *   GET  /v1/sessions/:sessionId/conversation-events?sinceSeq=N&limit=M
+ *        → { events[], lastSeq }  (R-T4 replay)
+ *   POST /v1/sessions/:sessionId/mark-read          (R-T7)
+ *   GET  /v1/sessions/:sessionId/ws-token           (R-T3 short-lived token)
+ *   GET  /v1/sessions/:sessionId/artifacts          (canvas hydration)
+ *   GET  /v1/artifacts/:artifactId/versions         (VersionHistory hydration)
+ *
+ * The realtime push channel itself (WS server consuming these tokens) is
+ * Phase-6 scope; this run supplies the replayable, workspace-scoped data
+ * plane the frame reads.
+ */
+import { zAgentSessionId, zArtifactId } from "@working-theory/ids";
+import type { FastifyPluginAsync, FastifyReply } from "fastify";
+import { z } from "zod";
+
+import { tenantDb } from "../../lib/tenant-db.js";
+import { mintWsToken } from "../../lib/ws-token.js";
+
+function notFound(reply: FastifyReply) {
+  return reply.status(404).send({
+    ok: false,
+    error: { code: "not_found", message: "Not found" },
+  });
+}
+
+function invalidId(reply: FastifyReply) {
+  return reply.status(400).send({
+    ok: false,
+    error: { code: "validation_failed", message: "Invalid id" },
+  });
+}
+
+// Boundary id validation (ADR-0031 rule 5): target params must be well-formed
+// entity ids (agsess_/artif_ prefixed uuids) before any lookup runs.
+const sessionParamsSchema = z.object({ sessionId: zAgentSessionId });
+const artifactParamsSchema = z.object({ artifactId: zArtifactId });
+
+function unauthorized(reply: FastifyReply) {
+  return reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required" },
+  });
+}
+
+const eventsQuerySchema = z.object({
+  sinceSeq: z.coerce.number().int().min(0).default(0),
+  limit: z.coerce.number().int().min(1).max(500).default(200),
+});
+
+const markReadSchema = z.object({
+  seq: z.coerce.number().int().min(0).optional(),
+});
+
+export const sessionRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get<{ Params: { sessionId: string } }>(
+    "/v1/sessions/:sessionId/conversation-events",
+    async (request, reply) => {
+      const tenant = request.tenant;
+      if (!tenant) return unauthorized(reply);
+
+      const query = eventsQuerySchema.safeParse(request.query ?? {});
+      if (!query.success) {
+        return reply.status(400).send({
+          ok: false,
+          error: { code: "validation_failed", message: "Invalid query" },
+        });
+      }
+
+      const params = sessionParamsSchema.safeParse(request.params);
+      if (!params.success) return invalidId(reply);
+
+      const db = tenantDb(tenant);
+      const session = await db.agentSession.byId(params.data.sessionId);
+      if (!session) return notFound(reply);
+
+      const events = await db.conversationEvent.listSince(
+        params.data.sessionId,
+        query.data.sinceSeq,
+        query.data.limit,
+      );
+
+      return reply.send({
+        ok: true,
+        data: {
+          events: events.map((e) => ({
+            agentId: e.agentId,
+            seq: e.seq,
+            type: e.type,
+            turnId: e.turnId,
+            payload: e.payload,
+            createdAt: e.createdAt,
+          })),
+          lastSeq: session.lastSeq,
+        },
+      });
+    },
+  );
+
+  fastify.post<{ Params: { sessionId: string } }>(
+    "/v1/sessions/:sessionId/mark-read",
+    async (request, reply) => {
+      const tenant = request.tenant;
+      if (!tenant) return unauthorized(reply);
+
+      const parsed = markReadSchema.safeParse(request.body ?? {});
+      if (!parsed.success) {
+        return reply.status(400).send({
+          ok: false,
+          error: { code: "validation_failed", message: "Invalid body" },
+        });
+      }
+
+      const params = sessionParamsSchema.safeParse(request.params);
+      if (!params.success) return invalidId(reply);
+
+      const db = tenantDb(tenant);
+      // Scoped resolve FIRST — the upsert below must never run for a session
+      // outside the tenant (a receipt row would attach to a foreign session).
+      const session = await db.agentSession.byId(params.data.sessionId);
+      if (!session) return notFound(reply);
+
+      const lastReadSeq = parsed.data.seq ?? session.lastSeq;
+      await db.readReceipt.upsert(params.data.sessionId, lastReadSeq);
+      return reply.send({ ok: true, data: { sessionId: session.id, lastReadSeq } });
+    },
+  );
+
+  fastify.get<{ Params: { sessionId: string } }>(
+    "/v1/sessions/:sessionId/ws-token",
+    async (request, reply) => {
+      const tenant = request.tenant;
+      if (!tenant) return unauthorized(reply);
+
+      const params = sessionParamsSchema.safeParse(request.params);
+      if (!params.success) return invalidId(reply);
+
+      const session = await tenantDb(tenant).agentSession.byId(
+        params.data.sessionId,
+      );
+      if (!session) return notFound(reply);
+
+      const minted = mintWsToken({
+        userId: tenant.userId,
+        sessionId: params.data.sessionId,
+        workspaceId: tenant.workspaceId,
+      });
+      return reply.send({ ok: true, data: minted });
+    },
+  );
+
+  fastify.get<{ Params: { sessionId: string } }>(
+    "/v1/sessions/:sessionId/artifacts",
+    async (request, reply) => {
+      const tenant = request.tenant;
+      if (!tenant) return unauthorized(reply);
+
+      const params = sessionParamsSchema.safeParse(request.params);
+      if (!params.success) return invalidId(reply);
+
+      const db = tenantDb(tenant);
+      const session = await db.agentSession.byId(params.data.sessionId);
+      if (!session) return notFound(reply);
+
+      const artifacts = await db.artifact.listBySession(params.data.sessionId);
+      return reply.send({
+        ok: true,
+        data: {
+          artifacts: artifacts.map((a) => ({
+            id: a.id,
+            type: a.type,
+            title: a.title,
+            updatedAt: a.updatedAt,
+          })),
+        },
+      });
+    },
+  );
+
+  fastify.get<{ Params: { artifactId: string } }>(
+    "/v1/artifacts/:artifactId/versions",
+    async (request, reply) => {
+      const tenant = request.tenant;
+      if (!tenant) return unauthorized(reply);
+
+      const params = artifactParamsSchema.safeParse(request.params);
+      if (!params.success) return invalidId(reply);
+
+      const db = tenantDb(tenant);
+      const artifact = await db.artifact.byId(params.data.artifactId);
+      if (!artifact) return notFound(reply);
+
+      const versions = await db.artifactVersion.listByArtifact(
+        params.data.artifactId,
+      );
+      return reply.send({
+        ok: true,
+        data: {
+          versions: versions.map((v) => ({
+            id: v.id,
+            savedAt: v.savedAt,
+            isCurrent: v.isCurrent,
+          })),
+        },
+      });
+    },
+  );
+};