@antasphere/chassis-server 1.0.0

package/dist/mcp/server.js

@@ -0,0 +1,93 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { mcpInputs } from './inputs.js';
+import { jsonText, mergeErrorHints, wrapToolErrors } from './errors.js';
+import { projectErrorHints, registerProjectTools } from './projects.js';
+import { registerTeamTools } from './teams.js';
+import { callApi, createScopeCheck, forWorkspace, pageQuery } from './tool-kit.js';
+/**
+ * The ONE composition of an instance's hint table: the domain hints, then
+ * every chassis group (the projects today), then the tool's own last, so a
+ * tool may re-word a chassis code and never the reverse. A tool set that
+ * wraps its own errors reads the same composition (never a copy), so a
+ * chassis group added here reaches the tool's tools without a second edit.
+ */
+export function composeErrorHints(toolHints, toolPrefix) {
+    return mergeErrorHints({ ...projectErrorHints(toolPrefix), ...toolHints });
+}
+export function buildMcpServer(ctx, info, tool, identity) {
+    // `<prefix>whoami` (the contract of `toolPrefix`), registered below: the other chassis tools point at it.
+    const whoami = `${identity.toolPrefix}whoami`;
+    const checkScope = createScopeCheck(tool.scopes);
+    const hints = composeErrorHints(tool.errorHints, identity.toolPrefix);
+    const server = new McpServer({ name: identity.serverName, version: info.version }, {
+        instructions: tool.instructions(info)
+    });
+    // The shared inputs (`inputs.ts`): the ones a tool's own set declares its tools with.
+    const { workspaceInput, cursorInput, limitInput } = mcpInputs(identity);
+    // ── Pattern 1: READ tool — the end-to-end whoami proof ────────────────────
+    server.registerTool('get_me', {
+        description: 'Who is connected: the user this MCP connection acts as, with all their organizations. ' +
+            'Returns { user: { id, email, name }, workspace, role, via, scopes, workspaces }. ' +
+            `Everything done through this server happens as this user. (Alias of ${whoami}.)`,
+        inputSchema: { workspace: workspaceInput },
+        annotations: { readOnlyHint: true }
+    }, async ({ workspace }) => {
+        const denied = checkScope(ctx.principal, tool.scopes.read);
+        if (denied)
+            return denied;
+        const c = forWorkspace(ctx, workspace);
+        return wrapToolErrors(async () => jsonText(await callApi(c, '/api/v1/me')), hints);
+    });
+    // ── Pattern 2: LIST tool with cursor pagination passed through ────────────
+    server.registerTool('list_files', {
+        description: "List a workspace's files, newest first. Returns { files: [{ id, sha256, sizeBytes, " +
+            'contentType, originalName, createdBy, createdAt }], nextCursor }. When nextCursor is ' +
+            'non-null, call again with cursor set to it for the next page. Download or upload happen ' +
+            'through the API, not through tools.',
+        inputSchema: {
+            workspace: workspaceInput,
+            limit: limitInput,
+            cursor: cursorInput
+        },
+        annotations: { readOnlyHint: true }
+    }, async ({ workspace, limit, cursor }) => {
+        const denied = checkScope(ctx.principal, tool.scopes.read);
+        if (denied)
+            return denied;
+        const c = forWorkspace(ctx, workspace);
+        return wrapToolErrors(async () => jsonText(await callApi(c, pageQuery('/api/v1/files', { cursor, limit }))), hints);
+    });
+    // ── Identity under the tool's own prefix ───────────────────────────────────
+    // Registered by the chassis (it reads `/me`, nothing of a domain) so that the
+    // name every `workspace` argument and `get_me` point at always exists. Third,
+    // right before the tool's set: `tools/list` keeps its order.
+    server.registerTool(whoami, {
+        description: 'Who is connected: the user this MCP connection acts as, plus ALL their organizations ' +
+            '(workspaces) with per-entry role/default/suspended flags. Returns { user: { id, email, ' +
+            'name }, workspace, role, via, scopes, workspaces: [...], activeWorkspaceId }. The ' +
+            'credential is the USER; the organization is a PER-CALL parameter: every tool accepts an ' +
+            'optional `workspace` (an id from `workspaces[]`) — omitted, the entry flagged `default: ' +
+            'true` is used (else the oldest membership). Call this first to discover the ids.',
+        inputSchema: { workspace: workspaceInput },
+        annotations: { readOnlyHint: true }
+    }, async ({ workspace }) => {
+        const denied = checkScope(ctx.principal, tool.scopes.read);
+        if (denied)
+            return denied;
+        const c = forWorkspace(ctx, workspace);
+        return wrapToolErrors(async () => jsonText(await callApi(c, '/api/v1/me')), hints);
+    });
+    // ── Projects: a chassis concept, so a chassis tool set ─────────────────────
+    // A project is a subgroup of a workspace with its own members and roles —
+    // the chassis owns it, and therefore owns the eleven tools over it. Registered
+    // under the tool's prefix, after whoami and before the tool's own set, so
+    // `tools/list` keeps one stable order across every instance.
+    registerProjectTools(server, ctx, identity, tool.scopes, checkScope, hints);
+    // Teams (PRDCT-2813): a chassis concept too, read-only over MCP, right after
+    // the projects they can be members of.
+    registerTeamTools(server, ctx, identity, tool.scopes, checkScope, hints);
+    // The product surface: the tool's own set, after the chassis tools.
+    tool.registerTools(server, ctx);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAmB,MAAM,aAAa,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EACL,OAAO,EACP,gBAAgB,EAChB,YAAY,EACZ,SAAS,EAGV,MAAM,eAAe,CAAC;AA4CvB;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAqB,EAAE,UAAkB;IACzE,OAAO,eAAe,CAAC,EAAE,GAAG,iBAAiB,CAAC,UAAU,CAAC,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,GAAmB,EACnB,IAAmB,EACnB,IAAuB,EACvB,QAAqB;IAErB,0GAA0G;IAC1G,MAAM,MAAM,GAAG,GAAG,QAAQ,CAAC,UAAU,QAAQ,CAAC;IAC9C,MAAM,UAAU,GAAG,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IACtE,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EACpD;QACE,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;KACtC,CACF,CAAC;IAEF,sFAAsF;IACtF,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAExE,6EAA6E;IAC7E,MAAM,CAAC,YAAY,CACjB,QAAQ,EACR;QACE,WAAW,EACT,wFAAwF;YACxF,mFAAmF;YACnF,uEAAuE,MAAM,IAAI;QACnF,WAAW,EAAE,EAAE,SAAS,EAAE,cAAc,EAAE;QAC1C,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;KACpC,EACD,KAAK,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;QACtB,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3D,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAC1B,MAAM,CAAC,GAAG,YAAY,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACvC,OAAO,cAAc,CAAC,KAAK,IAAI,EAAE,CAAC,QAAQ,CAAC,MAAM,OAAO,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACrF,CAAC,CACF,CAAC;IAEF,6EAA6E;IAC7E,MAAM,CAAC,YAAY,CACjB,YAAY,EACZ;QACE,WAAW,EACT,qFAAqF;YACrF,uFAAuF;YACvF,0FAA0F;YAC1F,qCAAqC;QACvC,WAAW,EAAE;YACX,SAAS,EAAE,cAAc;YACzB,KAAK,EAAE,UAAU;YACjB,MAAM,EAAE,WAAW;SACpB;QACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;KACpC,EACD,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE;QACrC,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3D,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAC1B,MAAM,CAAC,GAAG,YAAY,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACvC,OAAO,cAAc,CACnB,KAAK,IAAI,EAAE,CAAC,QAAQ,CAAC,MAAM,OAAO,CAAC,CAAC,EAAE,SAAS,CAAC,eAAe,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EACrF,KAAK,CACN,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,8EAA8E;IAC9E,8EAA8E;IAC9E,8EAA8E;IAC9E,6DAA6D;IAC7D,MAAM,CAAC,YAAY,CACjB,MAAM,EACN;QACE,WAAW,EACT,uFAAuF;YACvF,yFAAyF;YACzF,oFAAoF;YACpF,0FAA0F;YAC1F,0FAA0F;YAC1F,kFAAkF;QACpF,WAAW,EAAE,EAAE,SAAS,EAAE,cAAc,EAAE;QAC1C,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;KACpC,EACD,KAAK,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;QACtB,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3D,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAC1B,MAAM,CAAC,GAAG,YAAY,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACvC,OAAO,cAAc,CAAC,KAAK,IAAI,EAAE,CAAC,QAAQ,CAAC,MAAM,OAAO,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACrF,CAAC,CACF,CAAC;IAEF,8EAA8E;IAC9E,0EAA0E;IAC1E,+EAA+E;IAC/E,0EAA0E;IAC1E,6DAA6D;IAC7D,oBAAoB,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IAC5E,6EAA6E;IAC7E,uCAAuC;IACvC,iBAAiB,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IAEzE,oEAAoE;IACpE,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEhC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/mcp/teams.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ErrorHints } from './errors.js';
+import { type McpScopes, type McpToolContext, type ScopeCheck } from './tool-kit.js';
+import type { McpIdentity } from './server.js';
+/** Register the two team reads on a server, after the project tools. */
+export declare function registerTeamTools(server: McpServer, ctx: McpToolContext, identity: McpIdentity, scopes: McpScopes, checkScope: ScopeCheck<string>, hints: ErrorHints): void;
+//# sourceMappingURL=teams.d.ts.map

package/dist/mcp/teams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"teams.d.ts","sourceRoot":"","sources":["../../src/mcp/teams.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,EAA4B,KAAK,UAAU,EAAuB,MAAM,aAAa,CAAC;AAC7F,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA8B/C,wEAAwE;AACxE,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,EAC9B,KAAK,EAAE,UAAU,GAChB,IAAI,CA8CN"}

package/dist/mcp/teams.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { mcpInputs } from './inputs.js';
+import { jsonText, wrapToolErrors } from './errors.js';
+import { callApi, forWorkspace, pageQuery } from './tool-kit.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, ctx, identity, scopes, checkScope, hints) {
+    const { workspaceInput, cursorInput, limitInput } = mcpInputs(identity);
+    const prefix = identity.toolPrefix;
+    const read = (workspace, path) => {
+        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 })));
+}
+//# sourceMappingURL=teams.js.map

package/dist/mcp/teams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teams.js","sourceRoot":"","sources":["../../src/mcp/teams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAwC,MAAM,aAAa,CAAC;AAC7F,OAAO,EACL,OAAO,EACP,YAAY,EACZ,SAAS,EAIV,MAAM,eAAe,CAAC;AAGvB;;;;;;;;;;;;GAYG;AAEH,iDAAiD;AACjD,MAAM,cAAc,GAClB,+FAA+F;IAC/F,gGAAgG;IAChG,iBAAiB,CAAC;AAEpB,uDAAuD;AACvD,MAAM,gBAAgB,GACpB,+FAA+F;IAC/F,kGAAkG;IAClG,8FAA8F,CAAC;AAEjG,MAAM,WAAW,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,iEAAiE,CAAC,CAAC;AAEzG,wEAAwE;AACxE,MAAM,UAAU,iBAAiB,CAC/B,MAAiB,EACjB,GAAmB,EACnB,QAAqB,EACrB,MAAiB,EACjB,UAA8B,EAC9B,KAAiB;IAEjB,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IACxE,MAAM,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC;IAEnC,MAAM,IAAI,GAAG,CAAC,SAA6B,EAAE,IAAY,EAA2B,EAAE;QACpF,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QACtD,IAAI,MAAM;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,CAAC,GAAG,YAAY,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACvC,OAAO,cAAc,CAAC,KAAK,IAAI,EAAE,CAAC,QAAQ,CAAC,MAAM,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAC7E,CAAC,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,GAAG,MAAM,YAAY,EACrB;QACE,WAAW,EACT,oDAAoD,cAAc,IAAI,gBAAgB,GAAG;YACzF,oFAAoF;YACpF,4FAA4F;YAC5F,4FAA4F;YAC5F,MAAM,MAAM,wBAAwB,MAAM,mDAAmD;YAC7F,mCAAmC;QACrC,WAAW,EAAE,EAAE,SAAS,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE;QAClF,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;KACpC,EACD,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,eAAe,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CACvG,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,GAAG,MAAM,mBAAmB,EAC5B;QACE,WAAW,EACT,iCAAiC,cAAc,IAAI,gBAAgB,sBAAsB;YACzF,4FAA4F;YAC5F,+FAA+F;YAC/F,8BAA8B;QAChC,WAAW,EAAE;YACX,SAAS,EAAE,cAAc;YACzB,MAAM,EAAE,WAAW;YACnB,KAAK,EAAE,UAAU;YACjB,MAAM,EAAE,WAAW;SACpB;QACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;KACpC,EACD,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAC7C,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,iBAAiB,MAAM,UAAU,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CACnF,CAAC;AACJ,CAAC"}

package/dist/mcp/tool-kit.d.ts

@@ -0,0 +1,67 @@
+import { type Principal } from '@antasphere/chassis-contract';
+import { 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 declare function forWorkspace(ctx: McpToolContext, workspace: string | undefined): McpToolContext;
+/**
+ * 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 declare function createScopeCheck<TRead extends string, TWrite extends string>(scopes: McpScopes<TRead, TWrite>): ScopeCheck<TRead | TWrite>;
+/**
+ * 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 declare function fetchApiRaw(ctx: McpToolContext, path: string, init?: RequestInit): Promise<Response>;
+/** In-process JSON API call: parses the body, maps non-2xx to ApiToolError. */
+export declare function callApi(ctx: McpToolContext, path: string, init?: RequestInit): Promise<unknown>;
+/**
+ * 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 declare function pageQuery(base: string, params: {
+    cursor?: string | undefined;
+    limit?: number | undefined;
+}, extra?: Record<string, string | undefined>): string;
+//# sourceMappingURL=tool-kit.d.ts.map

package/dist/mcp/tool-kit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-kit.d.ts","sourceRoot":"","sources":["../../src/mcp/tool-kit.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACvF,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClE,8DAA8D;IAC9D,SAAS,EAAE,SAAS,CAAC;IACrB,uDAAuD;IACvD,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,CAE/F;AAUD;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,MAAM,SAAS,MAAM,IAAI,CAC9C,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,KACV,cAAc,GAAG,IAAI,CAAC;AAE3B,mFAAmF;AACnF,MAAM,WAAW,SAAS,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,SAAS,MAAM,GAAG,MAAM;IACtF,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,MAAM,EAAE,MAAM,SAAS,MAAM,EAC1E,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,GAC/B,UAAU,CAAC,KAAK,GAAG,MAAM,CAAC,CAW5B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,QAAQ,CAAC,CAiBnB;AAED,+EAA+E;AAC/E,wBAAsB,OAAO,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAiBzG;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EACnE,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAM,GAC7C,MAAM,CASR"}

package/dist/mcp/tool-kit.js

@@ -0,0 +1,74 @@
+import { ACTIVE_WORKSPACE_HEADER } from '@antasphere/chassis-contract';
+import { ApiToolError, deny } from './errors.js';
+/**
+ * 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, workspace) {
+    return workspace ? { ...ctx, workspaceId: workspace } : ctx;
+}
+/** The re-entry headers: caller's bearer + the per-call workspace selector. */
+function apiHeaders(ctx) {
+    return {
+        authorization: ctx.authorizationHeader,
+        ...(ctx.workspaceId ? { [ACTIVE_WORKSPACE_HEADER]: ctx.workspaceId } : {})
+    };
+}
+export function createScopeCheck(scopes) {
+    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, path, init = {}) {
+    const res = await ctx.fetchApi(path, {
+        ...init,
+        headers: { ...(init.headers ?? {}), ...apiHeaders(ctx) }
+    });
+    if (!res.ok) {
+        const body = (await res.json().catch(() => 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, path, init = {}) {
+    const res = await ctx.fetchApi(path, {
+        ...init,
+        headers: { ...(init.headers ?? {}), ...apiHeaders(ctx) }
+    });
+    const body = (await res.json().catch(() => 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, params, extra = {}) {
+    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;
+}
+//# sourceMappingURL=tool-kit.js.map

package/dist/mcp/tool-kit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-kit.js","sourceRoot":"","sources":["../../src/mcp/tool-kit.ts"],"names":[],"mappings":"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"}

package/dist/members/removal.d.ts

@@ -0,0 +1,95 @@
+import { 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 declare function holdLiveMembership(tx: DbConn, workspaceId: string, who: {
+    memberId: string;
+} | {
+    userId: string;
+}): Promise<boolean>;
+/** 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 declare function deleteMembershipGrants(tx: DbConn, removed: readonly RemovedMembership[], toolHook?: MembershipRemovalHook): Promise<RemovalCounts>;
+/** Two passes of `deleteMembershipGrants` as one record: every count summed, the tool's by name. */
+export declare function mergeRemovalCounts(a: RemovalCounts, b: RemovalCounts): RemovalCounts;
+//# sourceMappingURL=removal.d.ts.map

package/dist/members/removal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"removal.d.ts","sourceRoot":"","sources":["../../src/members/removal.ts"],"names":[],"mappings":"AACA,OAAO,EAWL,KAAK,MAAM,EACZ,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,MAAM,EACV,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAC7C,OAAO,CAAC,OAAO,CAAC,CAclB;AAED,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,SAAS,iBAAiB,EAAE,KAClC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAErC,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,WAAW,EAAE,MAAM,CAAC;IACpB,4GAA4G;IAC5G,UAAU,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,SAAS,iBAAiB,EAAE,EACrC,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,OAAO,CAAC,aAAa,CAAC,CAwExB;AAED,oGAAoG;AACpG,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,aAAa,CAUpF"}

package/dist/members/removal.js

@@ -0,0 +1,143 @@
+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 } 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, workspaceId, who) {
+    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;
+}
+/**
+ * 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, removed, toolHook) {
+    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, b) {
+    const tool = { ...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
+    };
+}
+//# sourceMappingURL=removal.js.map

package/dist/members/removal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"removal.js","sourceRoot":"","sources":["../../src/members/removal.ts"],"names":[],"mappings":"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"}

package/dist/middleware/auth-body.d.ts

@@ -0,0 +1,25 @@
+import type { MiddlewareHandler } from 'hono';
+/**
+ * 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 declare function authBodyGuard(): MiddlewareHandler;
+//# sourceMappingURL=auth-body.d.ts.map

package/dist/middleware/auth-body.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-body.d.ts","sourceRoot":"","sources":["../../src/middleware/auth-body.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAO9C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,IAAI,iBAAiB,CA4BjD"}