@antasphere/chassis-contract 1.5.1 → 1.6.0

package/src/routes/index.ts

@@ -5,6 +5,17 @@ import { apiErrorSchema, cursorPageQuerySchema } from '../schemas/common.js';
 import { instanceInfoSchema } from '../schemas/instance.js';
 import { appsListSchema } from '../schemas/apps.js';
 import { setupRequestSchema, setupResponseSchema } from '../schemas/setup.js';
+import {
+  connectionDeliveriesListQuerySchema,
+  connectionDeliveriesListSchema,
+  connectionFieldsUpdateSchema,
+  connectionParamsSchema,
+  connectionSchema,
+  connectionSecretSchema,
+  connectionsListSchema,
+  connectionTestResultSchema,
+  connectionUrlMadeSchema
+} from '../schemas/connections.js';
 import { onboardingDismissedSchema } from '../schemas/me.js';
 import {
   defaultWorkspaceSchema,
@@ -1232,6 +1243,199 @@ export interface ChassisRoutesCopy {
  * from its wording of the document — no module-level state, one instantiation
  * per tool, and no route object that no tool serves.
  */
+// ── Connections (PRDCT-3773) ──────────────────────────────────────────────────
+// Every inbound webhook source and outbound key a tool holds, declared by the
+// tool and stored by the chassis: one card per source on Settings › Connections.
+// The reads are every non-guest member's; the writes an owner's or an admin's.
+// No answer carries a secret; the receiving URL is answered once, when made.
+
+/** The refusals every connection route shares. */
+const connectionErrors = {
+  401: errorResponses[401],
+  403: jsonBody(apiErrorSchema, 'guest_forbidden, forbidden (not an owner or admin), or demo_session'),
+  404: jsonBody(apiErrorSchema, 'not_found: no such source is declared by this instance')
+};
+
+export const connectionsListRoute = createRoute({
+  method: 'get',
+  path: '/connections',
+  tags: ['connections'],
+  summary: 'Every connection source this instance declares, with its state in the workspace (never a secret)',
+  responses: {
+    200: jsonBody(connectionsListSchema, 'One entry per declared source, in the declared order'),
+    401: errorResponses[401],
+    403: jsonBody(apiErrorSchema, 'guest_forbidden')
+  }
+});
+
+export const connectionGetRoute = createRoute({
+  method: 'get',
+  path: '/connections/{source}',
+  tags: ['connections'],
+  summary: 'One connection source and its state in the workspace (never a secret, never the receiving URL)',
+  request: { params: connectionParamsSchema },
+  responses: { 200: jsonBody(connectionSchema, 'The connection'), ...connectionErrors }
+});
+
+export const connectionConnectRoute = createRoute({
+  method: 'post',
+  path: '/connections/{source}',
+  tags: ['connections'],
+  summary:
+    'Make the receiving URL of an inbound source, or rotate it (owner or admin): the URL is answered this once; the previous one answers 404 from now on; the secret stays',
+  request: { params: connectionParamsSchema },
+  responses: {
+    200: jsonBody(connectionUrlMadeSchema, 'The connection and the receiving URL, shown once'),
+    ...connectionErrors,
+    409: jsonBody(apiErrorSchema, 'not_inbound: a key source has no receiving URL')
+  }
+});
+
+export const connectionSecretRoute = createRoute({
+  method: 'put',
+  path: '/connections/{source}/secret',
+  tags: ['connections'],
+  summary:
+    "Set the source's signing secret or key (owner or admin): stored sealed, never read back; a key source is probed first and refused when the source refuses the key",
+  request: {
+    params: connectionParamsSchema,
+    body: jsonRequestBody(connectionSecretSchema, 'The secret or the key, as the source showed it')
+  },
+  responses: {
+    200: jsonBody(connectionSchema, 'The connection'),
+    400: jsonBody(
+      apiErrorSchema,
+      'Validation error, secret_invalid (not the shape the source declares) or secret_refused (the source refused the key; the detail says what it answered)'
+    ),
+    ...connectionErrors,
+    409: jsonBody(apiErrorSchema, 'not_connected: make the receiving URL first'),
+    502: jsonBody(apiErrorSchema, 'source_unavailable: the source did not answer the probe')
+  }
+});
+
+export const connectionFieldsRoute = createRoute({
+  method: 'patch',
+  path: '/connections/{source}',
+  tags: ['connections'],
+  summary:
+    "Store the source's declared fields (owner or admin): a key absent keeps its value, null clears it",
+  request: {
+    params: connectionParamsSchema,
+    body: jsonRequestBody(connectionFieldsUpdateSchema, 'The fields, by declared key')
+  },
+  responses: {
+    200: jsonBody(connectionSchema, 'The connection'),
+    400: jsonBody(apiErrorSchema, 'Validation error, unknown_field or field_required'),
+    ...connectionErrors,
+    409: jsonBody(apiErrorSchema, 'not_connected: connect the source first')
+  }
+});
+
+export const connectionTestRoute = createRoute({
+  method: 'post',
+  path: '/connections/{source}/test',
+  tags: ['connections'],
+  summary:
+    'Test the connection (owner or admin): a key source is probed with the stored key, an inbound source checks that its URL is made and its secret opens; the result is kept as the last check',
+  request: { params: connectionParamsSchema },
+  responses: {
+    200: jsonBody(connectionTestResultSchema, 'What the test found'),
+    ...connectionErrors,
+    409: jsonBody(apiErrorSchema, 'not_connected: nothing to test yet')
+  }
+});
+
+export const connectionDisconnectRoute = createRoute({
+  method: 'delete',
+  path: '/connections/{source}',
+  tags: ['connections'],
+  summary:
+    'Disconnect the source (owner or admin): the secret, the receiving URL and the delivery log of the workspace are gone',
+  request: { params: connectionParamsSchema },
+  responses: { 200: jsonBody(connectionSchema, 'The connection, disconnected'), ...connectionErrors }
+});
+
+export const connectionDeliveriesRoute = createRoute({
+  method: 'get',
+  path: '/connections/{source}/deliveries',
+  tags: ['connections'],
+  summary:
+    'The deliveries the door took for this source, newest first (every member but a guest; cursor-paginated)',
+  request: { params: connectionParamsSchema, query: connectionDeliveriesListQuerySchema },
+  responses: {
+    200: jsonBody(connectionDeliveriesListSchema, 'Deliveries, newest first'),
+    400: errorResponses[400],
+    ...connectionErrors
+  }
+});
+
+/**
+ * The sibling connect (PRDCT-3774): a source that declares a sibling tool of
+ * the same hub is connected AS THE PERSON, in one call. The instance turns
+ * the person's own hub grant into a two-minute token audienced to the
+ * sibling (`POST /sso/connect-token` on the hub, scope `sso:connect`),
+ * presents it at the sibling's `/sso/cli-connect` for a key of the person
+ * there, registers its receiving URL as a webhook endpoint of the sibling
+ * workspace that projects the same hub organization, stores the returned
+ * signing secret sealed and the endpoint id, and revokes the key. Nothing of
+ * the person outlives the call on the sibling; the person never sees a URL
+ * or a secret. A re-run replaces the endpoint, the URL and the secret.
+ */
+const siblingRefusals = jsonBody(
+  apiErrorSchema,
+  'sibling_unknown (the hub lists no tool of that slug), sibling_scope_missing (the person must sign in again so their grant carries sso:connect), ' +
+    'sibling_grant_missing (the person never opened the sibling: open it once, then retry), sibling_access_denied (the hub does not let this account use the sibling), ' +
+    'sibling_workspace_missing (no workspace of the sibling projects this organization), sibling_refused (the sibling refused the endpoint: its message says why)'
+);
+
+export const connectionSiblingConnectRoute = createRoute({
+  method: 'post',
+  path: '/connections/{source}/sibling',
+  tags: ['connections'],
+  summary:
+    'Connect a sibling tool as the person (owner or admin): the endpoint is registered on the sibling and the secret stored, nothing shown; a re-run replaces them',
+  request: { params: connectionParamsSchema },
+  responses: {
+    200: jsonBody(connectionSchema, 'The connection, with the endpoint registered on the sibling'),
+    400: siblingRefusals,
+    401: jsonBody(apiErrorSchema, 'unauthenticated, or hub_reauth_required (the person must sign in again)'),
+    403: connectionErrors[403],
+    404: connectionErrors[404],
+    409: jsonBody(
+      apiErrorSchema,
+      'not_sibling (the source declares no sibling), not_inbound, sibling_unavailable (this instance is not on a hub), or sibling_busy (another connect of this source is running: retry in a moment)'
+    ),
+    502: jsonBody(
+      apiErrorSchema,
+      'source_unavailable: the hub or the sibling did not answer; nothing changed'
+    )
+  }
+});
+
+export const connectionSiblingDisconnectRoute = createRoute({
+  method: 'delete',
+  path: '/connections/{source}/sibling',
+  tags: ['connections'],
+  summary:
+    "Disconnect a sibling source as the person (owner or admin): the endpoint is deleted on the sibling, then the connection's secret, URL and log here",
+  request: { params: connectionParamsSchema },
+  responses: {
+    200: jsonBody(connectionSchema, 'The connection, disconnected on both sides'),
+    400: siblingRefusals,
+    401: jsonBody(apiErrorSchema, 'unauthenticated, or hub_reauth_required (the person must sign in again)'),
+    403: connectionErrors[403],
+    404: connectionErrors[404],
+    409: jsonBody(
+      apiErrorSchema,
+      'not_sibling, sibling_unavailable (this instance is not on a hub), or sibling_busy (another connect of this source is running: retry in a moment)'
+    ),
+    502: jsonBody(
+      apiErrorSchema,
+      'source_unavailable: the hub or the sibling did not answer; nothing changed'
+    )
+  }
+});
+
 export function defineChassisRoutes<TScope extends string>(
   contract: ChassisContract<TScope>,
   identity: Pick<ToolIdentity, 'cliKeyScopesLabel'> & { scopes: Pick<ToolIdentity['scopes'], 'dataExport'> },

package/src/schemas/connections.ts

@@ -0,0 +1,174 @@
+import { z } from 'zod';
+import { cursorPageQuerySchema, hasControlChars, plainText } from './common.js';
+
+/**
+ * Connections (PRDCT-3773): every inbound webhook source a tool receives from
+ * and every outbound key it holds, declared by the tool (the `connections`
+ * slot: a key, a name, a kind, a verifier, the fields the source carries, a
+ * handler), stored by the chassis (one row per workspace and source: the
+ * sealed secret or key, the receiving token's hash, who connected it and
+ * when, the declared fields, the last delivery), served on ONE page
+ * (Settings › Connections, one card per source), one CLI group and one set
+ * of MCP tools. The door, `POST /hooks/{source}/{token}`, lives outside
+ * `/api/v1`: the signature is the credential.
+ *
+ * No answer ever carries a secret, a key or the receiving URL's token: the
+ * URL is answered once, when it is made or rotated, and the secret never.
+ */
+
+/** A source key: lowercase, digits and underscores, starting with a letter (`meet`, `lemlist`). */
+export const connectionSourceKeySchema = z
+  .string()
+  .min(1)
+  .max(40)
+  .regex(/^[a-z][a-z0-9_]*$/, 'lowercase letters, digits and underscores, starting with a letter');
+
+/** `inbound`: a source that posts to this instance; `key`: a key this instance holds; `both`. */
+export const connectionKindSchema = z.enum(['inbound', 'key', 'both']);
+export type ConnectionKind = z.infer<typeof connectionKindSchema>;
+
+/** The path of the door, outside `/api/v1`: `<PUBLIC_BASE_URL>/hooks/<source>/<token>`. */
+export const CONNECTION_HOOK_PATH = '/hooks';
+
+/** One declared field of a source, as the page and the CLI show it. */
+export const connectionFieldDeclarationSchema = z.object({
+  key: z.string(),
+  label: z.string(),
+  description: z.string().nullable(),
+  required: z.boolean(),
+  /** The value is a list of strings rather than one string. */
+  multiple: z.boolean()
+});
+export type ConnectionFieldDeclaration = z.infer<typeof connectionFieldDeclarationSchema>;
+
+/** What the tool declared about a source: the static half of a card. */
+export const connectionDeclaredSchema = z.object({
+  description: z.string().nullable(),
+  /** `standard-webhooks`, `stripe`, or `custom` (the tool's own function); null for a key source. */
+  verifier: z.string().nullable(),
+  /** The event types the source sends (an inbound source); informative. */
+  events: z.array(z.string()),
+  /** What the secret looks like, for the form's placeholder (`whsec_…`); never a value. */
+  secretHint: z.string().nullable(),
+  fields: z.array(connectionFieldDeclarationSchema),
+  /** The source is a sibling tool of the same hub (PRDCT-3774): its registry slug and the events to subscribe. */
+  sibling: z.object({ toolSlug: z.string(), events: z.array(z.string()) }).nullable()
+});
+export type ConnectionDeclared = z.infer<typeof connectionDeclaredSchema>;
+
+const member = z.object({ id: z.string(), name: z.string(), email: z.string() });
+
+/** A field's stored value: a string, a list of strings, or null (unset). */
+export const connectionFieldValueSchema = z.union([
+  plainText(0, 2000),
+  z.array(plainText(1, 2000)).max(200),
+  z.null()
+]);
+export type ConnectionFieldValue = z.infer<typeof connectionFieldValueSchema>;
+
+/** The stored fields of a connection, by declared key. */
+export const connectionFieldsSchema = z.record(connectionSourceKeySchema, connectionFieldValueSchema);
+export type ConnectionFields = z.infer<typeof connectionFieldsSchema>;
+
+/** The outcome of one delivery the door took. */
+export const connectionDeliveryOutcomeSchema = z.enum(['processed', 'ignored', 'failed']);
+export type ConnectionDeliveryOutcome = z.infer<typeof connectionDeliveryOutcomeSchema>;
+
+/**
+ * One source as the page, the CLI and an agent read it: the declaration,
+ * whether it is connected, who made the receiving URL and when (never the
+ * URL), whether the secret is set and readable, by whom and when (never the
+ * secret), the stored fields, the last delivery and the last test.
+ */
+export const connectionSchema = z.object({
+  source: connectionSourceKeySchema,
+  name: z.string(),
+  kind: connectionKindSchema,
+  declared: connectionDeclaredSchema,
+  /** An inbound source: the URL is made and the secret set; a key source: the key is set. */
+  connected: z.boolean(),
+  /** The receiving URL's state (an inbound source): when the current one was made and by whom; null until made. Never the URL. */
+  receiving: z.object({ madeAt: z.string(), madeBy: member.nullable() }).nullable(),
+  /** The secret's state: never the secret. */
+  secretState: z.object({
+    set: z.boolean(),
+    /** False when the stored value no longer opens (the instance's auth secret changed): set it again. */
+    readable: z.boolean(),
+    setAt: z.string().nullable(),
+    setBy: member.nullable()
+  }),
+  fields: connectionFieldsSchema,
+  /** When the connection row was first made, by whom. */
+  connectedAt: z.string().nullable(),
+  connectedBy: member.nullable(),
+  lastDelivery: z
+    .object({ at: z.string(), type: z.string(), outcome: connectionDeliveryOutcomeSchema })
+    .nullable(),
+  /** The last test or probe: when, whether it passed, what it said. */
+  check: z.object({ at: z.string(), ok: z.boolean(), detail: z.string() }).nullable(),
+  /** A sibling source (PRDCT-3774): the endpoint registered on the sibling, null until connected as the person. */
+  sibling: z.object({ endpointId: z.string().nullable() }).nullable()
+});
+export type Connection = z.infer<typeof connectionSchema>;
+
+export const connectionsListSchema = z.object({ connections: z.array(connectionSchema) });
+export type ConnectionsList = z.infer<typeof connectionsListSchema>;
+
+/** `POST /connections/{source}`: the connection and the receiving URL, shown this once. */
+export const connectionUrlMadeSchema = z.object({
+  connection: connectionSchema,
+  /** `<PUBLIC_BASE_URL>/hooks/<source>/<token>`: only the token's hash is kept, so the URL is never shown again. */
+  receivingUrl: z.string()
+});
+export type ConnectionUrlMade = z.infer<typeof connectionUrlMadeSchema>;
+
+/** `PUT /connections/{source}/secret`: the secret or the key as the source showed it. */
+export const connectionSecretSchema = z.object({
+  secret: z
+    .string()
+    .trim()
+    .min(1)
+    .max(4096)
+    .refine((v) => !/\s/.test(v) && !hasControlChars(v), {
+      error: 'must not contain whitespace or control characters'
+    })
+});
+export type ConnectionSecret = z.input<typeof connectionSecretSchema>;
+
+/** `PATCH /connections/{source}`: the declared fields to store (a key absent keeps its value; null clears it). */
+export const connectionFieldsUpdateSchema = z.object({ fields: connectionFieldsSchema });
+export type ConnectionFieldsUpdate = z.infer<typeof connectionFieldsUpdateSchema>;
+
+/** `POST /connections/{source}/test`: what the test found, and the connection after it. */
+export const connectionTestResultSchema = z.object({
+  ok: z.boolean(),
+  detail: z.string(),
+  connection: connectionSchema
+});
+export type ConnectionTestResult = z.infer<typeof connectionTestResultSchema>;
+
+/** One delivery the door took for a source of a workspace. */
+export const connectionDeliverySchema = z.object({
+  id: z.string(),
+  source: connectionSourceKeySchema,
+  /** The sender's own id of the delivery (the `webhook-id` header, Stripe's event id): the dedupe key. */
+  deliveryId: z.string(),
+  type: z.string(),
+  receivedAt: z.string(),
+  outcome: connectionDeliveryOutcomeSchema,
+  /** What the handler said, or null. */
+  detail: z.string().nullable(),
+  /** Why the handler failed, or null. */
+  error: z.string().nullable()
+});
+export type ConnectionDelivery = z.infer<typeof connectionDeliverySchema>;
+
+export const connectionDeliveriesListSchema = z.object({
+  deliveries: z.array(connectionDeliverySchema),
+  nextCursor: z.string().nullable()
+});
+export type ConnectionDeliveriesList = z.infer<typeof connectionDeliveriesListSchema>;
+
+export const connectionDeliveriesListQuerySchema = cursorPageQuerySchema;
+
+export const connectionParamsSchema = z.object({ source: connectionSourceKeySchema });