pipework 0.252.0 → 0.253.0

package/src/infra/support/http.ts

@@ -0,0 +1,229 @@
+import { createHash, timingSafeEqual } from 'node:crypto'
+import { Builder } from '../../request/di/builder.js'
+import type { Handler } from '../../request/di/types.js'
+import { schema } from '../../data/schema/namespace.js'
+import { NotFoundError, UnauthorizedError, ForbiddenError } from '../../core/errors/index.js'
+import { requireContext, runInContext } from '../../request/context/store.js'
+import { __flowStep } from '../../trace/runtime/flow-step.js'
+import { pipeSystem } from '../../data/db/db.js'
+import { sql } from '../../data/db/sql.js'
+import { BadRequestError } from '../alerts/http.js'
+import { TICKET_STATES } from './schema.js'
+import type { Support, TicketState, DraftInput } from './handle.js'
+
+export interface SupportHttpOptions {
+  /** Route prefix, e.g. '/ops/support'. No trailing slash. */
+  readonly path: string
+  /**
+   * Service credentials, name -> secret, or name -> `{ secret, approve? }`. A request sends `Authorization: Bearer <secret>`.
+   * The name is the actor: audit rows, a draft's author and an approval carry it. A key approves only with `approve: true`;
+   * a plain secret is a drafting key. At least one; secrets at least 32 chars.
+   */
+  readonly credentials: Readonly<Record<string, string | { readonly secret: string; readonly approve?: boolean }>>
+}
+
+interface Principal { readonly name: string; readonly approve: boolean }
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const sha = (s: string): Buffer => createHash('sha256').update(s).digest()
+
+function authenticate(credentials: readonly (readonly [Principal, Buffer])[], header: string | undefined): Principal {
+  const match = header !== undefined ? /^Bearer (.+)$/.exec(header) : null
+  const given = sha(match?.[1] ?? '')
+  let found: Principal | null = null
+  for (const [principal, digest] of credentials) {
+    if (timingSafeEqual(given, digest) && match !== null && found === null) found = principal
+  }
+  if (found === null) throw new UnauthorizedError('A valid service credential is required: send Authorization: Bearer <secret>.')
+  return found
+}
+
+function bad(field: string, problem: string): never {
+  throw new BadRequestError(`Invalid ${field}: ${problem}.`, { field })
+}
+
+function optString(source: unknown, field: string): string | undefined {
+  const value = (source as Record<string, unknown> | null | undefined)?.[field]
+  if (value === undefined) return undefined
+  if (typeof value !== 'string') bad(field, 'must be a string')
+  return value
+}
+
+function reqString(source: unknown, field: string): string {
+  const value = optString(source, field)
+  if (value === undefined) bad(field, 'is required')
+  return value
+}
+
+function body(raw: unknown): Record<string, unknown> {
+  if (raw === undefined || raw === null) return {}
+  if (typeof raw !== 'object' || Array.isArray(raw)) bad('body', 'must be a JSON object')
+  return raw as Record<string, unknown>
+}
+
+function limitOf(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined
+  if (!/^[1-9][0-9]*$/.test(raw)) bad('limit', 'must be a positive integer')
+  return Number(raw)
+}
+
+function validateOptions(options: SupportHttpOptions): void {
+  if (!options.path.startsWith('/') || options.path.length < 2 || options.path.endsWith('/')) {
+    throw new Error(`support.http: path "${options.path}" must start with "/" and have no trailing slash, e.g. "/ops/support".`)
+  }
+  const entries = Object.entries(options.credentials)
+  if (entries.length === 0) {
+    throw new Error('support.http: credentials needs at least one entry, name -> secret (the secret is at least 32 characters).')
+  }
+  for (const [name, cred] of entries) {
+    const secret = typeof cred === 'string' ? cred : (cred as { secret?: unknown } | null)?.secret
+    if (typeof secret !== 'string' || secret.length < 32) {
+      throw new Error(`support.http: the secret for credential "${name}" is under 32 characters; use a long random value.`)
+    }
+    if (typeof cred !== 'string' && cred.approve !== undefined && typeof cred.approve !== 'boolean') {
+      throw new Error(`support.http: "approve" for credential "${name}" must be true or false.`)
+    }
+  }
+}
+
+/**
+ * Routes for a support agent, under `options.path` (all JSON, no session, no tenant): GET list (`state`, `category`,
+ * `tenantId`, `limit`, `cursor`), GET `/:id` (ticket, messages, links), PATCH `/:id` (`{ category }`, null clears),
+ * POST `/:id/transition` (`{ to }`), `/:id/notes` (`{ text }`), `/:id/links` (`{ kind, ref, label? }`),
+ * `/:id/drafts` (`{ text, html?, subject? }`, answers `{ draftId, version }`), PATCH and DELETE `/drafts/:id`, and
+ * POST `/drafts/:id/approve` (`{ version }`, 403 for a key without `approve: true`). A stale or already-approved draft is 409.
+ * Every request needs `Authorization: Bearer <secret>` matching one of `credentials`; the credential's name is the actor
+ * (audit rows, a draft's author, the approver), so `canApprove` and `distinctApprover` judge the key's name.
+ * Each call is the handle's own, traced and audited by it. Ids are looked up across tenants on the system channel, which a
+ * database with `rls.platformRole` refuses over the support tables; there these routes do not work. A bad value is 400 naming the field.
+ */
+export function supportHttp(handle: Support, options: SupportHttpOptions): Handler<Record<string, unknown>, unknown>[] {
+  validateOptions(options)
+  const credentials = Object.entries(options.credentials).map(([name, cred]) => {
+    const principal: Principal = typeof cred === 'string' ? { name, approve: false } : { name, approve: cred.approve === true }
+    return [principal, sha(typeof cred === 'string' ? cred : cred.secret)] as const
+  })
+  const base = options.path
+  const any = schema.check.unknown()
+
+  const get = (path: string) => new Builder().public().request().query(any).params(any).route('GET', path)
+  const withBody = (method: 'POST' | 'PATCH', path: string) => new Builder().public().request().query(any).params(any).input(any).route(method, path)
+  const del = (path: string) => new Builder().public().request().query(any).params(any).route('DELETE', path)
+
+  const idOf = (params: unknown): string => String((params as { id: string }).id)
+
+  // The handle takes its actor from the Flow's auth: run each call as the key's name, in a trace step so its audit
+  // records have one to sit under.
+  const as = <T>(who: Principal, fn: () => Promise<T>): Promise<T> => {
+    const flow = requireContext()
+    const step = __flowStep({ ref: 'src/infra/support/http.ts:supportHttp' }, fn)
+    return runInContext({ ...flow, auth: { userId: who.name } }, step)
+  }
+
+  const tenantOfTicket = async (id: string): Promise<string> => {
+    if (UUID_RE.test(id)) {
+      const rows = await pipeSystem().execute(sql`SELECT tenant_id FROM support_ticket WHERE id = ${id}::uuid`)
+      if (rows[0] !== undefined) return rows[0]['tenant_id'] as string
+    }
+    throw new NotFoundError('Support ticket', { ticketId: id })
+  }
+  const tenantOfDraft = async (id: string): Promise<string> => {
+    if (UUID_RE.test(id)) {
+      const rows = await pipeSystem().execute(sql`SELECT tenant_id FROM support_message WHERE id = ${id}::uuid AND kind = 'draft'`)
+      if (rows[0] !== undefined) return rows[0]['tenant_id'] as string
+    }
+    throw new NotFoundError('Support draft', { draftId: id })
+  }
+
+  const draftPatch = (b: Record<string, unknown>): Partial<DraftInput> => {
+    const text = optString(b, 'text')
+    const html = optString(b, 'html')
+    const subject = optString(b, 'subject')
+    return { ...(text === undefined ? {} : { text }), ...(html === undefined ? {} : { html }), ...(subject === undefined ? {} : { subject }) }
+  }
+
+  return [
+    get(base).fit(async ({ request, query }) => {
+      const who = authenticate(credentials, request.headers['authorization'])
+      const state = optString(query, 'state')
+      if (state !== undefined && !(TICKET_STATES as readonly string[]).includes(state)) bad('state', `"${state}" is not one of ${TICKET_STATES.join(', ')}`)
+      const category = optString(query, 'category')
+      const tenantId = optString(query, 'tenantId')
+      const limit = limitOf(optString(query, 'limit'))
+      const cursor = optString(query, 'cursor')
+      if (tenantId !== undefined && !UUID_RE.test(tenantId)) bad('tenantId', 'must be a UUID')
+      return as(who, () => handle.listAll({
+        ...(state === undefined ? {} : { state: state as TicketState }), ...(category === undefined ? {} : { category }), ...(tenantId === undefined ? {} : { tenantId }),
+        ...(limit === undefined ? {} : { limit }), ...(cursor === undefined ? {} : { cursor }),
+      }))
+    }),
+    get(`${base}/:id`).fit(async ({ request, params }) => {
+      const who = authenticate(credentials, request.headers['authorization'])
+      const id = idOf(params)
+      return as(who, async () => handle.getFor(await tenantOfTicket(id), id))
+    }),
+    withBody('PATCH', `${base}/:id`).fit(async ({ request, params, input }) => {
+      const who = authenticate(credentials, request.headers['authorization'])
+      const b = body(input)
+      const category = b['category']
+      if (category !== null && typeof category !== 'string') bad('category', 'must be a string or null')
+      const id = idOf(params)
+      return as(who, async () => handle.setCategoryFor(await tenantOfTicket(id), id, category))
+    }),
+    withBody('POST', `${base}/:id/transition`).fit(async ({ request, params, input }) => {
+      const who = authenticate(credentials, request.headers['authorization'])
+      const to = reqString(body(input), 'to')
+      if (!(TICKET_STATES as readonly string[]).includes(to)) bad('to', `"${to}" is not one of ${TICKET_STATES.join(', ')}`)
+      const id = idOf(params)
+      return as(who, async () => handle.transitionFor(await tenantOfTicket(id), id, to as TicketState))
+    }),
+    withBody('POST', `${base}/:id/notes`).fit(async ({ request, params, input }) => {
+      const who = authenticate(credentials, request.headers['authorization'])
+      const text = reqString(body(input), 'text')
+      const id = idOf(params)
+      return as(who, async () => handle.addNoteFor(await tenantOfTicket(id), id, text))
+    }),
+    withBody('POST', `${base}/:id/links`).fit(async ({ request, params, input }) => {
+      const who = authenticate(credentials, request.headers['authorization'])
+      const b = body(input)
+      const kind = reqString(b, 'kind')
+      const ref = reqString(b, 'ref')
+      const label = optString(b, 'label')
+      const id = idOf(params)
+      return as(who, async () => handle.linkFor(await tenantOfTicket(id), id, { kind, ref, ...(label === undefined ? {} : { label }) }))
+    }),
+    withBody('POST', `${base}/:id/drafts`).fit(async ({ request, params, input }) => {
+      const who = authenticate(credentials, request.headers['authorization'])
+      const b = body(input)
+      const text = reqString(b, 'text')
+      const html = optString(b, 'html')
+      const subject = optString(b, 'subject')
+      const id = idOf(params)
+      return as(who, async () => handle.draftReplyFor(await tenantOfTicket(id), id, {
+        text, ...(html === undefined ? {} : { html }), ...(subject === undefined ? {} : { subject }),
+      }))
+    }),
+    withBody('PATCH', `${base}/drafts/:id`).fit(async ({ request, params, input }) => {
+      const who = authenticate(credentials, request.headers['authorization'])
+      const patch = draftPatch(body(input))
+      const id = idOf(params)
+      return as(who, async () => handle.editDraftFor(await tenantOfDraft(id), id, patch))
+    }),
+    del(`${base}/drafts/:id`).fit(async ({ request, params }) => {
+      const who = authenticate(credentials, request.headers['authorization'])
+      const id = idOf(params)
+      return as(who, async () => {
+        await handle.discardDraftFor(await tenantOfDraft(id), id)
+        return { discarded: true }
+      })
+    }),
+    withBody('POST', `${base}/drafts/:id/approve`).fit(async ({ request, params, input }) => {
+      const who = authenticate(credentials, request.headers['authorization'])
+      if (!who.approve) throw new ForbiddenError('This credential may not approve replies.', { actorId: who.name })
+      const version = body(input)['version']
+      if (typeof version !== 'number' || !Number.isInteger(version)) bad('version', 'must be an integer')
+      const id = idOf(params)
+      return as(who, async () => handle.approveFor(await tenantOfDraft(id), id, { expectedVersion: version }))
+    }),
+  ]
+}

package/src/infra/support/index.ts

@@ -0,0 +1,7 @@
+export { createSupport, supportTemplates, DraftStateError } from './handle.js'
+export { supportHttp } from './http.js'
+export type { SupportHttpOptions } from './http.js'
+export type {
+  Support, SupportConfig, TicketApi, Ticket, TicketMessage, TicketLink, TicketDetail, TicketState, ListOptions, ListPage,
+  DraftInput, SupportSink, SupportDelivery, ScreenVerdict, ReceiveResult, ReceiveInput, SupportEventKind, SupportEventPayload,
+} from './handle.js'

package/src/infra/support/namespace.ts

@@ -0,0 +1,12 @@
+import { createSupport, supportTemplates } from './handle.js'
+import { supportHttp } from './http.js'
+
+/** Support namespace — tickets from email (and later chat), with replies sent only after an approval. */
+export const support = {
+  /** Creates the support handle: tickets, messages, notes, links, drafts, `approve`, `receiveEmail`, and the events job. */
+  create: createSupport,
+  /** Routes for a support agent: list, read, triage, notes, links, drafts, approve; bearer credentials that name the actor, and only some may approve. */
+  http: supportHttp,
+  /** The reply template to spread into `mail.create({ templates })`; it renders the approved draft verbatim. */
+  templates: supportTemplates,
+} as const

package/src/infra/support/schema.ts

@@ -0,0 +1,96 @@
+// The tables behind support tickets. Tickets, messages and links are tenant-scoped (forced
+// row-level security in generated migrations); the event outbox is not, because one tick
+// delivers every tenant's events.
+
+import { define } from '../../data/domain/index.js'
+import { field } from '../../data/domain/field.js'
+import { schema } from '../../data/schema/namespace.js'
+import { index, uniqueIndex } from '../../data/db/idx/index.js'
+import { sql } from '../../data/db/sql.js'
+
+export const TICKET_STATES = ['open', 'triaged', 'awaiting_approval', 'answered', 'closed'] as const
+export const MESSAGE_KINDS = ['inbound', 'note', 'draft', 'outbound'] as const
+export const MESSAGE_CHANNELS = ['email', 'chat', 'api'] as const
+export const DRAFT_STATUSES = ['draft', 'approved', 'discarded'] as const
+export const EVENT_KINDS = ['ticket.created', 'ticket.customer-replied', 'draft.awaiting-approval'] as const
+
+export const supportTicket = define('support_ticket', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  tenantId: field.uuid().tenant(),
+  state: field.enum(TICKET_STATES).default('open'),
+  category: field.text().nullable(),
+  subject: field.text(),
+  contactEmail: field.text(),
+  contactName: field.text().nullable(),
+  userId: field.text().nullable(),
+  conversationId: field.uuid().nullable(),
+  createdAt: field.timestamp().default('now'),
+  updatedAt: field.timestamp().default('now'),
+  lastCustomerMessageAt: field.timestamp().default('now'),
+}, {
+  indexes: (t) => ({
+    byConversation: uniqueIndex('uq_support_ticket_conversation').on(t['tenantId'], t['conversationId']),
+    byState: index('idx_support_ticket_state').on(t['tenantId'], t['state'], t['createdAt']),
+  }),
+})
+
+export const supportMessage = define('support_message', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  tenantId: field.uuid().tenant(),
+  ticketId: field.uuid(),
+  kind: field.enum(MESSAGE_KINDS),
+  channel: field.enum(MESSAGE_CHANNELS),
+  subject: field.text().nullable(),
+  text: field.text(),
+  html: field.text().nullable(),
+  fromAddress: field.text().nullable(),
+  inboundEmailId: field.uuid().nullable(),
+  attachments: field.jsonb(schema.check.json()).nullable(),
+  draftStatus: field.enum(DRAFT_STATUSES).nullable(),
+  version: field.integer().default(1),
+  approvedBy: field.text().nullable(),
+  approvedAt: field.timestamp().nullable(),
+  emailMessageId: field.uuid().nullable(),
+  createdBy: field.text().nullable(),
+  createdAt: field.timestamp().default('now'),
+}, {
+  indexes: (t) => ({
+    byInbound: uniqueIndex('uq_support_message_inbound').on(t['tenantId'], t['inboundEmailId']),
+    byTicket: index('idx_support_message_ticket').on(t['ticketId'], t['createdAt']),
+  }),
+})
+
+export const supportLink = define('support_link', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  tenantId: field.uuid().tenant(),
+  ticketId: field.uuid(),
+  kind: field.text(),
+  ref: field.text(),
+  label: field.text().nullable(),
+  createdAt: field.timestamp().default('now'),
+}, {
+  indexes: (t) => ({
+    byTarget: uniqueIndex('uq_support_link_target').on(t['ticketId'], t['kind'], t['ref']),
+  }),
+})
+
+export const supportEventDelivery = define('support_event_delivery', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  ticketId: field.uuid(),
+  kind: field.enum(EVENT_KINDS),
+  sink: field.text(),
+  payload: field.jsonb(schema.check.json()),
+  attempts: field.integer().default(0),
+  nextAttemptAt: field.timestamp().default('now'),
+  deliveredAt: field.timestamp().nullable(),
+  failedAt: field.timestamp().nullable(),
+  lastError: field.text().nullable(),
+  createdAt: field.timestamp().default('now'),
+}, {
+  indexes: (t) => ({
+    due: index('idx_support_event_delivery_due')
+      .on(t['nextAttemptAt'])
+      .where(sql.raw('delivered_at IS NULL AND failed_at IS NULL')),
+    byTicket: index('idx_support_event_delivery_ticket').on(t['ticketId']),
+  }),
+})

package/src/infra/webhook/inbound.ts

@@ -0,0 +1,45 @@
+import type { Handler, HttpMethod } from '../../request/di/types.js'
+import type { SignatureVerifier } from './verify.js'
+import { Builder } from '../../request/di/builder.js'
+import { UnauthorizedError } from '../../core/errors/index.js'
+
+export interface InboundWebhookConfig<TPayload> {
+  path: string
+  method?: HttpMethod
+  verifier: SignatureVerifier
+  parsePayload?: (rawBody: Buffer) => TPayload
+  idempotencyKey?: (payload: TPayload) => string
+}
+
+export interface InboundWebhookContext<TPayload> {
+  payload: TPayload
+  rawBody: Buffer
+  headers: Readonly<Record<string, string | undefined>>
+}
+
+export function defineInboundWebhook<TPayload = unknown>(
+  config: InboundWebhookConfig<TPayload>,
+  handler: (ctx: InboundWebhookContext<TPayload>) => Promise<unknown>,
+): Handler<Record<string, unknown>, unknown> {
+  const method = config.method ?? 'POST'
+  const parse = config.parsePayload ?? ((raw: Buffer) => JSON.parse(raw.toString('utf-8')) as TPayload)
+
+  return new Builder()
+    .public()
+    .rawBody()
+    .request()
+    .route(method, config.path)
+    .fit(async ({ rawBody, request }) => {
+      if (!config.verifier.verify(rawBody, request.headers)) {
+        throw new UnauthorizedError(
+          'Webhook signature verification failed.\n\n' +
+          '  The request signature does not match the expected value.\n' +
+          '  Check that the signing secret is correct and the raw body is unmodified.\n',
+        )
+      }
+
+      const payload = parse(rawBody)
+
+      return handler({ payload, rawBody, headers: request.headers })
+    })
+}

package/src/infra/webhook/index.ts

@@ -0,0 +1,5 @@
+export { defineInboundWebhook, type InboundWebhookConfig, type InboundWebhookContext } from './inbound.js'
+export { hmacVerifier, stripeVerifier, githubVerifier, type SignatureVerifier } from './verify.js'
+export { signPayload, type SignedPayload, type WebhookSignatureOptions } from './sign.js'
+export { createOutboundWebhook, type OutboundWebhookConfig, type OutboundWebhook,
+  type WebhookEndpoint, type DeliveryAttempt } from './outbound.js'

package/src/infra/webhook/namespace.ts

@@ -0,0 +1,24 @@
+import { defineInboundWebhook } from './inbound.js'
+import { hmacVerifier, stripeVerifier, githubVerifier } from './verify.js'
+import { signPayload } from './sign.js'
+import { createOutboundWebhook } from './outbound.js'
+
+/** Webhook namespace — inbound verification, outbound delivery with retries, HMAC signing. */
+export const webhook = {
+  /** Defines an inbound webhook handler with signature verification and optional idempotency. */
+  defineInbound: defineInboundWebhook,
+  /** Creates an outbound webhook system — endpoint registration, payload signing, delivery with retries. */
+  createOutbound: createOutboundWebhook,
+
+  verify: {
+    /** Creates an HMAC signature verifier for inbound webhooks. */
+    hmac: hmacVerifier,
+    /** Creates a Stripe-compatible signature verifier. */
+    stripe: stripeVerifier,
+    /** Creates a GitHub-compatible signature verifier. */
+    github: githubVerifier,
+  },
+
+  /** Signs a payload with HMAC for outbound delivery — returns body, signature, timestamp, messageId. */
+  sign: signPayload,
+} as const