@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/src/webhook-endpoint-binding.ts

@@ -0,0 +1,246 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type {
+  Cursor,
+  EnvName,
+  ProjectId,
+  RunId,
+  TenantId,
+  Timestamp,
+  WebhookDeliveryId,
+  WebhookEndpointId,
+  WebhookEventId,
+} from '@kindgi/types';
+
+/**
+ * Outbound webhook endpoints: URLs the platform sends signed events to,
+ * such as `run.finished` when a run completes, fails or is cancelled.
+ * The inverse of `/v1/webhooks`, which are inbound triggers.
+ *
+ * Caller-plugged: the runtime owns storage, secrets, the delivery queue
+ * and the HTTP sender. This package defines the contract and the wire
+ * shapes, and mounts `/v1/webhook-endpoints` when a binding is supplied.
+ *
+ * **Secrets.** An endpoint's signing secret is shared with the receiver,
+ * so it lives where the deployment's other secrets do: the endpoint holds
+ * a reference (`secretRef`, like a provider's `secret_ref`), never the
+ * value. The caller stores the secret first (its own `.env` in
+ * development, the secrets store in production; `generate-secret` makes
+ * a strong one) and registers the endpoint with its name. The binding
+ * resolves it at tenant scope to sign each delivery, and checks on
+ * create and update that it exists and is strong (`whsec_` + base64 of
+ * at least 24 bytes, or the bare base64). Rotating is rotating that
+ * secret; while a store keeps the previous version, deliveries carry a
+ * signature for each version less than a day old. Deliveries are signed
+ * per `@kindgi/crypto` `signWebhook`; receivers verify with
+ * `verifyWebhook` or any Standard Webhooks library.
+ *
+ * **Delivery.** At least once: receivers deduplicate on the event id
+ * (the `webhook-id` header). Every method is tenant-scoped.
+ */
+export interface WebhookEndpointBinding {
+  /**
+   * Register an endpoint. The route has checked the body's shape and
+   * that `url` is an absolute http(s) URL; the binding applies the
+   * deployment's URL policy (e.g. https only, no private addresses) and
+   * answers `url-refused` with a reason, and checks the secret behind
+   * `secretRef` (`secret-not-found`, `secret-too-weak`).
+   */
+  create(input: WebhookEndpointCreateInput): Promise<WebhookEndpointCreateOutcome>;
+  list(input: WebhookEndpointListInput): Promise<WebhookEndpointPage>;
+  /** `null` when unknown or unregistered; the route answers 404. */
+  get(input: WebhookEndpointRef): Promise<WebhookEndpoint | null>;
+  update(input: WebhookEndpointUpdateInput): Promise<WebhookEndpointUpdateOutcome>;
+  /**
+   * Soft delete: the endpoint stops receiving events and its pending
+   * deliveries are abandoned. `{ unregistered: false }` when it was
+   * unknown or already unregistered.
+   */
+  unregister(input: WebhookEndpointRef): Promise<{ readonly unregistered: boolean }>;
+  /** The endpoint's deliveries, newest first. */
+  listDeliveries(input: WebhookDeliveryListInput): Promise<WebhookDeliveryListOutcome>;
+  /** Queue a delivery again now, whatever its status; attempts start over. */
+  redeliver(input: WebhookDeliveryRef): Promise<WebhookDeliveryOutcome>;
+  /** Queue a `webhook.test` event to the endpoint, to check the receiver end to end. */
+  sendTest(input: WebhookEndpointRef): Promise<WebhookDeliveryOutcome>;
+}
+
+/** Event types an endpoint can subscribe to. */
+export const WEBHOOK_EVENT_TYPES = ['run.finished'] as const;
+export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
+
+/**
+ * Which events reach the endpoint. Every field narrows; absent fields
+ * don't. `run.finished` is sent for top-level runs only (never for a
+ * child run, such as an agent step's turn).
+ */
+export interface WebhookEndpointFilter {
+  /** Only runs in this project. */
+  readonly projectId?: ProjectId;
+  /** Only runs of these flows (`flowId`, any version). */
+  readonly flowIds?: readonly string[];
+  /** Dry runs are left out unless this is `true`. */
+  readonly includeDryRuns?: boolean;
+}
+
+export interface WebhookEndpoint {
+  readonly endpointId: WebhookEndpointId;
+  readonly url: string;
+  readonly events: readonly WebhookEventType[];
+  readonly filter: WebhookEndpointFilter;
+  readonly description: string | null;
+  /** Where the signing secret is kept; the value never leaves the store. */
+  readonly secretRef: WebhookSecretRef;
+  readonly createdAt: Timestamp;
+  readonly updatedAt: Timestamp;
+}
+
+/**
+ * A secret by name in the deployment's secrets store, resolved at tenant
+ * scope — the same shape as a provider's `secret_ref`.
+ */
+export interface WebhookSecretRef {
+  readonly envName: EnvName;
+  readonly name: string;
+}
+
+export interface WebhookEndpointRef {
+  readonly tenantId: TenantId;
+  readonly endpointId: WebhookEndpointId;
+}
+
+export interface WebhookEndpointCreateInput {
+  readonly tenantId: TenantId;
+  readonly url: string;
+  readonly events: readonly WebhookEventType[];
+  readonly filter: WebhookEndpointFilter;
+  readonly secretRef: WebhookSecretRef;
+  readonly description?: string;
+}
+
+export interface WebhookEndpointListInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+}
+
+export interface WebhookEndpointPage {
+  readonly data: readonly WebhookEndpoint[];
+  readonly nextCursor?: Cursor;
+}
+
+/** Fields to change; absent fields are kept. `description: null` clears it. */
+export interface WebhookEndpointUpdateInput extends WebhookEndpointRef {
+  readonly url?: string;
+  readonly events?: readonly WebhookEventType[];
+  readonly filter?: WebhookEndpointFilter;
+  readonly secretRef?: WebhookSecretRef;
+  readonly description?: string | null;
+}
+
+/** Why an endpoint can't be saved as asked. */
+export type WebhookEndpointRefusal =
+  | { readonly kind: 'url-refused'; readonly reason: string }
+  | { readonly kind: 'project-not-found'; readonly projectId: ProjectId }
+  /** No secret by that name (at tenant scope) in the store. */
+  | { readonly kind: 'secret-not-found'; readonly secretRef: WebhookSecretRef }
+  /** The secret is not `whsec_` + base64 of at least 24 bytes (or that base64 alone). */
+  | { readonly kind: 'secret-too-weak'; readonly secretRef: WebhookSecretRef };
+
+export type WebhookEndpointCreateOutcome =
+  | { readonly kind: 'ok'; readonly endpoint: WebhookEndpoint }
+  | WebhookEndpointRefusal;
+
+export type WebhookEndpointUpdateOutcome =
+  | { readonly kind: 'ok'; readonly endpoint: WebhookEndpoint }
+  | { readonly kind: 'not-found' }
+  | WebhookEndpointRefusal;
+
+// ---------- events (what endpoints receive) ----------
+
+/**
+ * A finished top-level run, as `run.finished` carries it: the run's
+ * identity and outcome, never its input or output. Field names match
+ * `GET /v1/runs/:runId`.
+ */
+export interface FinishedRun {
+  readonly id: RunId;
+  readonly projectId: ProjectId;
+  readonly flowId: string;
+  readonly flowVersion: string;
+  readonly status: 'completed' | 'failed' | 'cancelled';
+  readonly dryRun: boolean;
+  /** Why the run failed or was cancelled; `null` when it completed. */
+  readonly failureMessage: string | null;
+  readonly createdAt: Timestamp;
+  readonly completedAt: Timestamp;
+}
+
+export interface RunFinishedEvent {
+  readonly id: WebhookEventId;
+  readonly type: 'run.finished';
+  readonly createdAt: Timestamp;
+  readonly data: { readonly run: FinishedRun };
+}
+
+/** Sent only by `POST /v1/webhook-endpoints/:endpointId/test`. */
+export interface WebhookTestEvent {
+  readonly id: WebhookEventId;
+  readonly type: 'webhook.test';
+  readonly createdAt: Timestamp;
+  readonly data: { readonly endpointId: WebhookEndpointId };
+}
+
+/** The JSON body of every webhook request. */
+export type WebhookEvent = RunFinishedEvent | WebhookTestEvent;
+
+// ---------- deliveries ----------
+
+/**
+ * `pending`: waiting for its next attempt. `delivered`: the endpoint
+ * answered 2xx. `failed`: every attempt failed, or the endpoint was
+ * unregistered first; `redeliver` queues it again.
+ */
+export const WEBHOOK_DELIVERY_STATUSES = ['pending', 'delivered', 'failed'] as const;
+export type WebhookDeliveryStatus = (typeof WEBHOOK_DELIVERY_STATUSES)[number];
+
+export interface WebhookDelivery {
+  readonly deliveryId: WebhookDeliveryId;
+  readonly endpointId: WebhookEndpointId;
+  readonly event: WebhookEvent;
+  readonly status: WebhookDeliveryStatus;
+  readonly attempts: number;
+  /** When the next attempt is due; `null` unless `pending`. */
+  readonly nextAttemptAt: Timestamp | null;
+  readonly lastAttemptAt: Timestamp | null;
+  /** HTTP status of the last attempt; `null` when it got no response. */
+  readonly lastResponseStatus: number | null;
+  /** Why the last attempt failed (`timeout`, `connection-refused`, `url-refused`, …). */
+  readonly lastError: string | null;
+  readonly createdAt: Timestamp;
+  readonly deliveredAt: Timestamp | null;
+}
+
+export interface WebhookDeliveryRef extends WebhookEndpointRef {
+  readonly deliveryId: WebhookDeliveryId;
+}
+
+export interface WebhookDeliveryListInput extends WebhookEndpointRef {
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  readonly status?: WebhookDeliveryStatus;
+}
+
+export type WebhookDeliveryListOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly data: readonly WebhookDelivery[];
+      readonly nextCursor?: Cursor;
+    }
+  | { readonly kind: 'not-found' };
+
+export type WebhookDeliveryOutcome =
+  | { readonly kind: 'ok'; readonly delivery: WebhookDelivery }
+  | { readonly kind: 'not-found' }
+  | { readonly kind: 'delivery-not-found' };

package/src/xml.ts

@@ -0,0 +1,196 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Minimal hand-rolled XML serialization for the S3-compat wire
+ * surface. S3 response shapes are shallow (5 or so total across the
+ * surface); pulling in a full XML library would be overkill.
+ *
+ * Every serializer emits a single top-level element with the XML prolog
+ * and the S3-standard namespace (`http://s3.amazonaws.com/doc/2006-03-01/`).
+ * Escaping is applied to text content and attribute values.
+ */
+
+const XML_PROLOG = '<?xml version="1.0" encoding="UTF-8"?>';
+const S3_NS = 'http://s3.amazonaws.com/doc/2006-03-01/';
+
+/**
+ * S3-standard error body. `<Error><Code>...</Code><Message>...</Message>...</Error>`.
+ */
+export function errorXml(
+  code: string,
+  message: string,
+  extra: Readonly<Record<string, string>> = {},
+): string {
+  const extraTags = Object.entries(extra)
+    .map(([k, v]) => tag(k, v))
+    .join('');
+  return `${XML_PROLOG}<Error>${tag('Code', code)}${tag('Message', message)}${extraTags}</Error>`;
+}
+
+/**
+ * S3 `ListObjectsV2` result envelope. `contents` are the matched keys
+ * with metadata; `CommonPrefixes` is never emitted — delimiters are not
+ * supported.
+ */
+export interface ListBucketResultInput {
+  readonly bucket: string;
+  readonly prefix: string;
+  readonly maxKeys: number;
+  readonly isTruncated: boolean;
+  readonly continuationToken?: string;
+  readonly nextContinuationToken?: string;
+  readonly contents: ReadonlyArray<{
+    readonly key: string;
+    readonly lastModified: string;
+    readonly etag: string;
+    readonly size: number;
+  }>;
+}
+
+export function listBucketResultXml(input: ListBucketResultInput): string {
+  const contents = input.contents
+    .map(
+      (c) =>
+        `<Contents>${tag('Key', c.key)}${tag('LastModified', c.lastModified)}${tag('ETag', quote(c.etag))}${tag('Size', String(c.size))}${tag('StorageClass', 'STANDARD')}</Contents>`,
+    )
+    .join('');
+  const parts = [
+    tag('Name', input.bucket),
+    tag('Prefix', input.prefix),
+    tag('KeyCount', String(input.contents.length)),
+    tag('MaxKeys', String(input.maxKeys)),
+    tag('IsTruncated', input.isTruncated ? 'true' : 'false'),
+    ...(input.continuationToken !== undefined
+      ? [tag('ContinuationToken', input.continuationToken)]
+      : []),
+    ...(input.nextContinuationToken !== undefined
+      ? [tag('NextContinuationToken', input.nextContinuationToken)]
+      : []),
+    contents,
+  ];
+  return `${XML_PROLOG}<ListBucketResult xmlns="${S3_NS}">${parts.join('')}</ListBucketResult>`;
+}
+
+/**
+ * S3 `InitiateMultipartUpload` result envelope.
+ */
+export interface InitiateMultipartUploadResultInput {
+  readonly bucket: string;
+  readonly key: string;
+  readonly uploadId: string;
+}
+
+export function initiateMultipartUploadResultXml(
+  input: InitiateMultipartUploadResultInput,
+): string {
+  const parts = [
+    tag('Bucket', input.bucket),
+    tag('Key', input.key),
+    tag('UploadId', input.uploadId),
+  ];
+  return `${XML_PROLOG}<InitiateMultipartUploadResult xmlns="${S3_NS}">${parts.join('')}</InitiateMultipartUploadResult>`;
+}
+
+/**
+ * S3 `CompleteMultipartUpload` result envelope.
+ */
+export interface CompleteMultipartUploadResultInput {
+  readonly bucket: string;
+  readonly key: string;
+  readonly etag: string;
+  readonly location: string;
+}
+
+export function completeMultipartUploadResultXml(
+  input: CompleteMultipartUploadResultInput,
+): string {
+  const parts = [
+    tag('Location', input.location),
+    tag('Bucket', input.bucket),
+    tag('Key', input.key),
+    tag('ETag', quote(input.etag)),
+  ];
+  return `${XML_PROLOG}<CompleteMultipartUploadResult xmlns="${S3_NS}">${parts.join('')}</CompleteMultipartUploadResult>`;
+}
+
+/**
+ * S3 `ListParts` result envelope.
+ */
+export interface ListPartsResultInput {
+  readonly bucket: string;
+  readonly key: string;
+  readonly uploadId: string;
+  readonly parts: ReadonlyArray<{
+    readonly partNumber: number;
+    readonly etag: string;
+    readonly size: number;
+    readonly lastModified: string;
+  }>;
+}
+
+export function listPartsResultXml(input: ListPartsResultInput): string {
+  const parts = input.parts
+    .map(
+      (p) =>
+        `<Part>${tag('PartNumber', String(p.partNumber))}${tag('LastModified', p.lastModified)}${tag('ETag', quote(p.etag))}${tag('Size', String(p.size))}</Part>`,
+    )
+    .join('');
+  return `${XML_PROLOG}<ListPartsResult xmlns="${S3_NS}">${tag('Bucket', input.bucket)}${tag('Key', input.key)}${tag('UploadId', input.uploadId)}${parts}</ListPartsResult>`;
+}
+
+// -------------------- parsing (CompleteMultipartUpload body) --------------------
+
+/**
+ * Parse the `CompleteMultipartUpload` request body:
+ *
+ *   <CompleteMultipartUpload>
+ *     <Part>
+ *       <PartNumber>1</PartNumber>
+ *       <ETag>"..."</ETag>
+ *     </Part>
+ *     ...
+ *   </CompleteMultipartUpload>
+ *
+ * Returns the declared parts in body order (S3 REQUIRES ascending
+ * PartNumber; the completer verifies before assembling). Hand-rolled
+ * regex — the shape is trivial and the input is machine-generated by
+ * AWS SDKs.
+ */
+export function parseCompleteMultipartUploadXml(
+  body: string,
+): { partNumber: number; etag: string }[] | null {
+  const parts: { partNumber: number; etag: string }[] = [];
+  const partRe =
+    /<Part>\s*(?:<PartNumber>(\d+)<\/PartNumber>\s*<ETag>([^<]+)<\/ETag>|<ETag>([^<]+)<\/ETag>\s*<PartNumber>(\d+)<\/PartNumber>)\s*<\/Part>/g;
+  let match: RegExpExecArray | null = partRe.exec(body);
+  while (match !== null) {
+    const partNumber = Number.parseInt((match[1] ?? match[4]) as string, 10);
+    const etagRaw = (match[2] ?? match[3]) as string;
+    const etag = etagRaw.replace(/^"|"$/g, '');
+    if (!Number.isFinite(partNumber) || partNumber < 1) return null;
+    parts.push({ partNumber, etag });
+    match = partRe.exec(body);
+  }
+  if (parts.length === 0) return null;
+  return parts;
+}
+
+// -------------------- primitives --------------------
+
+function tag(name: string, value: string): string {
+  return `<${name}>${escapeXml(value)}</${name}>`;
+}
+
+function quote(s: string): string {
+  return s.startsWith('"') ? s : `"${s}"`;
+}
+
+// In XML text content, only `&` and `<` MUST be escaped (`>` is only
+// required inside `]]>`). `"` and `'` need escaping only in attribute
+// values. S3 responses don't use attribute values, so we escape the
+// minimum set — matching what real S3 emits (e.g. `<ETag>"abc"</ETag>`
+// with literal quotes).
+function escapeXml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;');
+}