@antasphere/chassis-server 1.0.0

package/src/mcp/teams.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { mcpInputs } from './inputs.js';
+import { jsonText, wrapToolErrors, type ErrorHints, type ToolTextResult } from './errors.js';
+import {
+  callApi,
+  forWorkspace,
+  pageQuery,
+  type McpScopes,
+  type McpToolContext,
+  type ScopeCheck
+} from './tool-kit.js';
+import type { McpIdentity } from './server.js';
+
+/**
+ * The two TEAM reads (PRDCT-2813), registered by the chassis right after the
+ * project tools: a team is a chassis concept (a named group of a workspace's
+ * own members, on both editions), so the tools over it are the chassis'. Thin
+ * shims over the instance's own /api/v1/teams called IN-PROCESS with the
+ * caller's bearer forwarded verbatim, like every other chassis tool.
+ *
+ * READS ONLY, by design: shaping a team (creating it, seating people) is a
+ * person's act on the People page, or on the Antasphere account site for a
+ * workspace it manages; an agent puts a team on a project through
+ * `<toolPrefix>add_project_member` with `teamId`. Nothing here names a tool,
+ * a brand or a domain.
+ */
+
+/** What a team IS, opening both descriptions. */
+const WHAT_IS_A_TEAM =
+  'A team is a named group of the organization’s own members (for example "Design" or "Sales"). ' +
+  'A team can be put on a project with a role, and every member of the team then holds that role ' +
+  'on the project.';
+
+/** Where teams come from and where they are shaped. */
+const WHERE_TEAMS_LIVE =
+  'In an organization managed by the Antasphere account site, the teams come from there and are ' +
+  'read-only here. Creating a team or adding people to one is done by a person on the People page, ' +
+  'or on the Antasphere account site for an organization it manages, never through these tools.';
+
+const teamIdInput = z.uuid().describe('The team id, from the teams list (never the team name or slug).');
+
+/** Register the two team reads on a server, after the project tools. */
+export function registerTeamTools(
+  server: McpServer,
+  ctx: McpToolContext,
+  identity: McpIdentity,
+  scopes: McpScopes,
+  checkScope: ScopeCheck<string>,
+  hints: ErrorHints
+): void {
+  const { workspaceInput, cursorInput, limitInput } = mcpInputs(identity);
+  const prefix = identity.toolPrefix;
+
+  const read = (workspace: string | undefined, path: string): Promise<ToolTextResult> => {
+    const denied = checkScope(ctx.principal, scopes.read);
+    if (denied) return Promise.resolve(denied);
+    const c = forWorkspace(ctx, workspace);
+    return wrapToolErrors(async () => jsonText(await callApi(c, path)), hints);
+  };
+
+  server.registerTool(
+    `${prefix}list_teams`,
+    {
+      description:
+        `List the teams of an organization, newest first. ${WHAT_IS_A_TEAM} ${WHERE_TEAMS_LIVE} ` +
+        'Returns { teams: [{ id, slug, name, membersCount, isMember, hubTeamId, createdAt, ' +
+        'updatedAt }], nextCursor } — `isMember` says whether YOU are in the team, and `hubTeamId` ' +
+        'is set when the team comes from the Antasphere account site. Pass a team `id` as `teamId` ' +
+        `to ${prefix}list_team_members or ${prefix}add_project_member. When nextCursor is non-null, ` +
+        'call again with cursor set to it.',
+      inputSchema: { workspace: workspaceInput, limit: limitInput, cursor: cursorInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, limit, cursor }) => read(workspace, pageQuery('/api/v1/teams', { cursor, limit }))
+  );
+
+  server.registerTool(
+    `${prefix}list_team_members`,
+    {
+      description:
+        `List the members of one team. ${WHAT_IS_A_TEAM} ${WHERE_TEAMS_LIVE} Returns { members: ` +
+        '[{ userId, email, name, role, isActive, addedAt }], nextCursor } — `role` is the person’s ' +
+        'role in the ORGANIZATION (a team has no roles of its own). When nextCursor is non-null, call ' +
+        'again with cursor set to it.',
+      inputSchema: {
+        workspace: workspaceInput,
+        teamId: teamIdInput,
+        limit: limitInput,
+        cursor: cursorInput
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, teamId, limit, cursor }) =>
+      read(workspace, pageQuery(`/api/v1/teams/${teamId}/members`, { cursor, limit }))
+  );
+}

package/src/mcp/tool-kit.ts

@@ -0,0 +1,148 @@
+import { ACTIVE_WORKSPACE_HEADER, type Principal } from '@antasphere/chassis-contract';
+import { ApiToolError, deny, type ToolTextResult } from './errors.js';
+
+/**
+ * Shared plumbing for MCP tools (used by the chassis examples in server.ts
+ * and the tool's own set). Every call goes through the
+ * instance's own /api/v1 IN-PROCESS with the caller's Authorization header
+ * forwarded verbatim — MCP is just another API client, no privileged path.
+ */
+export interface McpToolContext {
+  /** In-process fetch against the root app (path → Response). */
+  fetchApi: (path: string, init?: RequestInit) => Promise<Response>;
+  /** The verified caller (OAuth token or API key principal). */
+  principal: Principal;
+  /** Forwarded verbatim on every in-process API call. */
+  authorizationHeader: string;
+  /**
+   * The instance's public origin (`PUBLIC_BASE_URL`), for the one thing a
+   * tool composes for a human rather than for the API: the page of the tool's
+   * resource that a push answers with (PRDCT-2280). Never used to reach the API.
+   */
+  publicBaseUrl: string;
+  /**
+   * Target workspace of THIS tool call (user-scoped credential model): set
+   * from the tool's optional `workspace` argument via {@link forWorkspace},
+   * it rides the in-process re-entry as the X-Workspace-Id header, where
+   * the API's own resolvers authorize it against the caller's live
+   * memberships — a tool argument can never grant what the credential's
+   * user does not hold. Absent = the caller's default workspace.
+   */
+  workspaceId?: string | undefined;
+}
+
+/**
+ * The per-call workspace seam: every workspace-scoped tool passes its
+ * optional `workspace` argument through here so the selection travels on
+ * the ONE header the whole platform authorizes.
+ */
+export function forWorkspace(ctx: McpToolContext, workspace: string | undefined): McpToolContext {
+  return workspace ? { ...ctx, workspaceId: workspace } : ctx;
+}
+
+/** The re-entry headers: caller's bearer + the per-call workspace selector. */
+function apiHeaders(ctx: McpToolContext): Record<string, string> {
+  return {
+    authorization: ctx.authorizationHeader,
+    ...(ctx.workspaceId ? { [ACTIVE_WORKSPACE_HEADER]: ctx.workspaceId } : {})
+  };
+}
+
+/**
+ * Tool-level scope pre-check — UX only: the API's fail-closed allowlist
+ * (middleware/scopes.ts) is the enforcement point; this just gives the model
+ * a clean, actionable error instead of a raw 403.
+ */
+export type ScopeCheck<TScope extends string> = (
+  principal: Principal,
+  scope: TScope
+) => ToolTextResult | null;
+
+/** The tool's two MCP scope names: what a read tool and a write tool pre-check. */
+export interface McpScopes<TRead extends string = string, TWrite extends string = string> {
+  read: TRead;
+  write: TWrite;
+}
+
+export function createScopeCheck<TRead extends string, TWrite extends string>(
+  scopes: McpScopes<TRead, TWrite>
+): ScopeCheck<TRead | TWrite> {
+  return (principal, scope) => {
+    if (principal.scopes && !principal.scopes.has(scope)) {
+      return deny(
+        `Missing scope "${scope}": this connection was not granted ` +
+          (scope === scopes.write ? 'permission to create or edit data.' : 'permission to read data.') +
+          ' Reconnect the MCP server and approve the permission on the consent screen.'
+      );
+    }
+    return null;
+  };
+}
+
+/**
+ * In-process API call returning the raw Response (asset downloads, multipart
+ * uploads). A non-2xx answer is parsed into an ApiToolError so wrapToolErrors
+ * renders the code + `Next:` hint.
+ */
+export async function fetchApiRaw(
+  ctx: McpToolContext,
+  path: string,
+  init: RequestInit = {}
+): Promise<Response> {
+  const res = await ctx.fetchApi(path, {
+    ...init,
+    headers: { ...(init.headers ?? {}), ...apiHeaders(ctx) }
+  });
+  if (!res.ok) {
+    const body = (await res.json().catch(() => null)) as {
+      error?: { code?: string; message?: string; details?: unknown };
+    } | null;
+    throw new ApiToolError(
+      res.status,
+      body?.error?.code ?? null,
+      body?.error?.message ?? `unexpected response from ${path}`,
+      body?.error?.details
+    );
+  }
+  return res;
+}
+
+/** In-process JSON API call: parses the body, maps non-2xx to ApiToolError. */
+export async function callApi(ctx: McpToolContext, path: string, init: RequestInit = {}): Promise<unknown> {
+  const res = await ctx.fetchApi(path, {
+    ...init,
+    headers: { ...(init.headers ?? {}), ...apiHeaders(ctx) }
+  });
+  const body = (await res.json().catch(() => null)) as {
+    error?: { code?: string; message?: string; details?: unknown };
+  } | null;
+  if (!res.ok) {
+    throw new ApiToolError(
+      res.status,
+      body?.error?.code ?? null,
+      body?.error?.message ?? `unexpected response from ${path}`,
+      body?.error?.details
+    );
+  }
+  return body;
+}
+
+/**
+ * Append cursor/limit list params to a path, after the route's own filters
+ * (`extra`, e.g. the `type` of the tool's resource list); an undefined filter is
+ * left out.
+ */
+export function pageQuery(
+  base: string,
+  params: { cursor?: string | undefined; limit?: number | undefined },
+  extra: Record<string, string | undefined> = {}
+): string {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(extra)) {
+    if (value !== undefined) query.set(key, value);
+  }
+  if (params.cursor) query.set('cursor', params.cursor);
+  if (params.limit !== undefined) query.set('limit', String(params.limit));
+  const qs = query.toString();
+  return qs ? `${base}?${qs}` : base;
+}

package/src/members/removal.ts

@@ -0,0 +1,216 @@
+import { and, eq, inArray, isNull, or, sql } from 'drizzle-orm';
+import {
+  demoPasses,
+  demoPassSessions,
+  invitations,
+  oauthAccessToken,
+  oauthRefreshToken,
+  projectMembers,
+  session as sessionTable,
+  user as userTable,
+  workspaceMembers,
+  workspaceTeamMembers,
+  type DbConn
+} from '@antasphere/chassis-db';
+
+/**
+ * The membership an ADD hangs a right on, re-read inside the add's own
+ * transaction and held FOR SHARE until it commits: true when the row is
+ * there, in that workspace, and active. Every add of something a removal
+ * takes (a project grant, a team seat, a demo pass) calls this before its
+ * insert, and refuses on false the way it refuses an inactive member.
+ *
+ * Why the lock (the end-to-end verification, finding 5): the add's first read
+ * is outside any transaction, and the insert's foreign key check takes only a
+ * KEY SHARE lock, which a removal's `UPDATE workspace_members` does not wait
+ * for. An add that read the row active, then waited on another lock (the
+ * project row, the team row), inserted after a removal had committed, on the
+ * now inactive row, and the right came back with the person at their
+ * re-invitation. Held FOR SHARE, the row makes the removal's update wait for
+ * the add to commit (the removal's second pass then takes what the add
+ * wrote, `deleteMembershipGrants`'s caller); an add that arrives after the
+ * update re-reads the row off and inserts nothing.
+ */
+export async function holdLiveMembership(
+  tx: DbConn,
+  workspaceId: string,
+  who: { memberId: string } | { userId: string }
+): Promise<boolean> {
+  const [row] = await tx
+    .select({ id: workspaceMembers.id })
+    .from(workspaceMembers)
+    .where(
+      and(
+        'memberId' in who ? eq(workspaceMembers.id, who.memberId) : eq(workspaceMembers.userId, who.userId),
+        eq(workspaceMembers.workspaceId, workspaceId),
+        eq(workspaceMembers.isActive, true)
+      )
+    )
+    .for('share')
+    .limit(1);
+  return row !== undefined;
+}
+
+/** One membership a removal switched off. */
+export interface RemovedMembership {
+  /** The `workspace_members` row. */
+  memberId: string;
+  workspaceId: string;
+  userId: string;
+}
+
+/**
+ * The tool's half of a removal (the `membershipRemoval` slot): what the TOOL
+ * hangs on a person in a workspace outside the chassis tables (an invite
+ * waiting for them, a grant on one of its resources). It runs in the
+ * removal's own transaction and answers what it ended, by name, for the
+ * audit record.
+ */
+export type MembershipRemovalHook = (
+  tx: DbConn,
+  removed: readonly RemovedMembership[]
+) => Promise<Record<string, number>>;
+
+export interface RemovalCounts {
+  projectGrants: number;
+  teamSeats: number;
+  /** Open workspace invitations revoked: the ones FOR the person and the ones they ISSUED. */
+  invitations: number;
+  /** Live demo passes revoked, their sessions ended: the ones opening the person and the ones they MINTED. */
+  demoPasses: number;
+  /** What the tool's hook ended, under the names it gave; empty without a hook. */
+  tool: Record<string, number>;
+}
+
+/**
+ * What a REMOVAL takes away beside the membership itself, stated once for
+ * both editions (PRDCT-2816): the person's project grants, their team seats
+ * (which is also every grant they held through a team), the open workspace
+ * invitations that name them or that they issued, and what the tool hangs
+ * on them in that workspace (`toolHook`).
+ *
+ * The demo passes are doors too (round 3, F1): a pass the person MINTED
+ * signs a demo person in, who could reactivate them; a pass minted FOR them
+ * works again the day they are re-invited, in whoever's hands it is. Both
+ * are revoked with the sessions they opened, the pass service's own way.
+ *
+ * ORDER (round 3, F2): the caller runs this BEFORE it switches the membership
+ * row off, inside the same transaction. An invitation's accept locks the
+ * invitation, then the membership row; a removal that locked the membership
+ * first and the invitation second met it head on and one of the two died
+ * of a deadlock. Same order on both sides, no deadlock.
+ *
+ * The invitations are doors, not rights (the verifier's round 2, N1 and N2).
+ * An invitation FOR the person that was open at the removal reactivates the
+ * row at the role it names: the person would come back alone, as admin if it
+ * says so. An invitation the person ISSUED is a way back in under another
+ * address. Both are revoked; an invitation made after the removal is the
+ * workspace's own act and brings the person back.
+ *
+ * A removal switches the membership row off and never deletes it (a re-add
+ * reactivates the very same row), so the foreign keys' cascade never fires:
+ * without these deletes, a person removed and added back later would find
+ * every old grant and seat waiting, and a door left open for them (a pending
+ * invite of the tool's) would let them switch the row back on themselves. A
+ * removal is a removal: only an act of the workspace brings the person back,
+ * and they come back with nothing. A PAUSE (`PATCH /members/{id}` with
+ * `isActive: false`) keeps everything, on purpose.
+ *
+ * The two callers: the hub reconcile's sweep (cloud, the hub removed the
+ * person) and `POST /members/{id}/remove` (a workspace managed here). Run it
+ * in the transaction that switches the rows off.
+ *
+ * Idempotent, so a caller may run it twice in one transaction: the deletes
+ * are by membership, the revokes filter on what is still open. The removal
+ * route does (a second pass after the row is off, `mergeRemovalCounts`).
+ */
+export async function deleteMembershipGrants(
+  tx: DbConn,
+  removed: readonly RemovedMembership[],
+  toolHook?: MembershipRemovalHook
+): Promise<RemovalCounts> {
+  if (removed.length === 0) {
+    return { projectGrants: 0, teamSeats: 0, invitations: 0, demoPasses: 0, tool: {} };
+  }
+  const ids = removed.map((row) => row.memberId);
+  const grants = await tx
+    .delete(projectMembers)
+    .where(inArray(projectMembers.memberId, ids))
+    .returning({ id: projectMembers.id });
+  const seats = await tx
+    .delete(workspaceTeamMembers)
+    .where(inArray(workspaceTeamMembers.memberId, ids))
+    .returning({ id: workspaceTeamMembers.id });
+  let revokedInvitations = 0;
+  let revokedPasses = 0;
+  for (const { workspaceId, userId } of removed) {
+    const passes = await tx
+      .update(demoPasses)
+      .set({ revokedAt: sql`now()` })
+      .where(
+        and(
+          eq(demoPasses.workspaceId, workspaceId),
+          isNull(demoPasses.revokedAt),
+          or(eq(demoPasses.userId, userId), eq(demoPasses.createdBy, userId))
+        )
+      )
+      .returning({ id: demoPasses.id });
+    if (passes.length > 0) {
+      const passIds = passes.map((p) => p.id);
+      const sessions = (
+        await tx
+          .select({ sessionId: demoPassSessions.sessionId })
+          .from(demoPassSessions)
+          .where(inArray(demoPassSessions.passId, passIds))
+      ).map((s) => s.sessionId);
+      if (sessions.length > 0) {
+        await tx.delete(oauthAccessToken).where(inArray(oauthAccessToken.sessionId, sessions));
+        await tx.delete(oauthRefreshToken).where(inArray(oauthRefreshToken.sessionId, sessions));
+        await tx.delete(demoPassSessions).where(inArray(demoPassSessions.sessionId, sessions));
+        await tx.delete(sessionTable).where(inArray(sessionTable.id, sessions));
+      }
+      revokedPasses += passes.length;
+    }
+    const [person] = await tx
+      .select({ email: userTable.email })
+      .from(userTable)
+      .where(eq(userTable.id, userId))
+      .limit(1);
+    const rows = await tx
+      .update(invitations)
+      .set({ revokedAt: sql`now()` })
+      .where(
+        and(
+          eq(invitations.workspaceId, workspaceId),
+          isNull(invitations.acceptedAt),
+          isNull(invitations.revokedAt),
+          person
+            ? or(eq(invitations.invitedBy, userId), sql`lower(${invitations.email}) = lower(${person.email})`)
+            : eq(invitations.invitedBy, userId)
+        )
+      )
+      .returning({ id: invitations.id });
+    revokedInvitations += rows.length;
+  }
+  const tool = toolHook ? await toolHook(tx, removed) : {};
+  return {
+    projectGrants: grants.length,
+    teamSeats: seats.length,
+    invitations: revokedInvitations,
+    demoPasses: revokedPasses,
+    tool
+  };
+}
+
+/** Two passes of `deleteMembershipGrants` as one record: every count summed, the tool's by name. */
+export function mergeRemovalCounts(a: RemovalCounts, b: RemovalCounts): RemovalCounts {
+  const tool: Record<string, number> = { ...a.tool };
+  for (const [key, n] of Object.entries(b.tool)) tool[key] = (tool[key] ?? 0) + n;
+  return {
+    projectGrants: a.projectGrants + b.projectGrants,
+    teamSeats: a.teamSeats + b.teamSeats,
+    invitations: a.invitations + b.invitations,
+    demoPasses: a.demoPasses + b.demoPasses,
+    tool
+  };
+}

package/src/middleware/auth-body.ts

@@ -0,0 +1,58 @@
+import type { MiddlewareHandler } from 'hono';
+import { hasNulDeep } from '@antasphere/chassis-contract';
+import { apiError } from '../api/errors.js';
+
+/** Matches better-call's / Hono's JSON content-type test (the json-depth regex). */
+const JSON_CONTENT_TYPE = /^application\/([a-z0-9.+-]*\+)?json/i;
+
+/**
+ * Pre-validates JSON bodies bound for the Better Auth mount (AF-1 + the
+ * update-user half of SL-B4, PRDCT-1358).
+ *
+ * The load-bearing half is NUL: Better Auth's free-text sinks (`/update-user`'s
+ * `name`) are outside the contract, so a NUL rode through to Postgres (SQLSTATE
+ * 22021) and surfaced as Better Auth's OWN 500 — a response `app.onError` never
+ * sees, so the app-level 22021 backstop cannot reach `/auth/*`. Refusing it
+ * here, before the mount, is the only complete place.
+ *
+ * The malformed/empty-JSON half is defence in depth and a wire-shape
+ * normalizer: on the pinned Better Auth (better-call ≥ 1.3.7) a JSON parse
+ * error already answers 400 (`BAD_REQUEST`), not a 500 — but with better-call's
+ * own error code, not this API's. Answering `invalid_json` here keeps the auth
+ * surface's parse errors in the same envelope as every other route, and guards
+ * a future dependency change that reverts to a 500.
+ *
+ * A body under a JSON content-type must parse and carry no NUL anywhere;
+ * non-JSON content types pass untouched (the OAuth token endpoint is
+ * form-encoded), as do bodyless requests. The body is read from a clone — the
+ * mount consumes the original.
+ */
+export function authBodyGuard(): MiddlewareHandler {
+  return async (c, next) => {
+    const raw = c.req.raw;
+    if (!raw.body) return next();
+    if (!JSON_CONTENT_TYPE.test(raw.headers.get('content-type') ?? '')) return next();
+    let text: string;
+    try {
+      text = await raw.clone().text();
+    } catch {
+      // Unreadable body — let the mount produce its own error.
+      return next();
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return apiError(c, 400, 'invalid_json', 'Request body is not valid JSON');
+    }
+    if (hasNulDeep(parsed)) {
+      return apiError(
+        c,
+        400,
+        'invalid_characters',
+        'Request contains characters that cannot be stored (e.g. a NUL byte)'
+      );
+    }
+    return next();
+  };
+}