@vinaverse/server 0.0.0-stage → 0.1.0-alpha.2

package/dist/index.cjs

@@ -0,0 +1,1481 @@
+'use strict';
+
+// src/webhooks/crypto.ts
+var WebCryptoUnavailableError = class extends Error {
+  constructor() {
+    super(
+      "Web Crypto (crypto.subtle) is not available in this runtime; @vinaverse/server needs Node 18+, an edge runtime or another runtime with Web Crypto"
+    );
+    this.name = "WebCryptoUnavailableError";
+  }
+};
+var fromNode;
+function webCrypto() {
+  const global = globalThis.crypto;
+  if (global?.subtle) return Promise.resolve(global);
+  fromNode ??= nodeWebCrypto();
+  return fromNode;
+}
+async function subtleCrypto() {
+  return (await webCrypto()).subtle;
+}
+async function nodeWebCrypto() {
+  if (typeof globalThis.process?.versions?.node !== "string") {
+    throw new WebCryptoUnavailableError();
+  }
+  const specifier = ["node", "crypto"].join(":");
+  const mod = await import(
+    /* webpackIgnore: true */
+    /* @vite-ignore */
+    specifier
+  );
+  if (!mod.webcrypto?.subtle) throw new WebCryptoUnavailableError();
+  return mod.webcrypto;
+}
+
+// src/internal/bytes.ts
+var encoder = new TextEncoder();
+function utf8(text) {
+  return encoder.encode(text);
+}
+function toBytes(body) {
+  if (typeof body === "string") return utf8(body);
+  if (body instanceof Uint8Array) return body;
+  return new Uint8Array(body);
+}
+function hexToBytes(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+function bytesToHex(bytes) {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function sha256Hex(data) {
+  const subtle = await subtleCrypto();
+  return bytesToHex(new Uint8Array(await subtle.digest("SHA-256", copy(data))));
+}
+async function hmacKey(secret, usage) {
+  const subtle = await subtleCrypto();
+  return subtle.importKey(
+    "raw",
+    utf8(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    [usage]
+  );
+}
+function copy(data) {
+  const out = new Uint8Array(data.length);
+  out.set(data);
+  return out;
+}
+function concat(...parts) {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const p of parts) {
+    out.set(p, at);
+    at += p.length;
+  }
+  return out;
+}
+
+// src/webhooks/errors.ts
+function webhookError(code, message) {
+  return { code, message };
+}
+
+// src/webhooks/events.ts
+var WEBHOOK_EVENT_TYPES = [
+  "moderation.item.completed",
+  "moderation.job.completed",
+  "document_check.completed",
+  "session.completed",
+  "subject.erased",
+  "usage.threshold_reached",
+  "feature.state_changed",
+  "media.job.queued",
+  "media.job.progress",
+  "media.job.step.completed",
+  "media.job.completed",
+  "media.job.failed",
+  "media.job.cancelled",
+  "conversation.updated",
+  "conversation.completed",
+  "conversation.failed",
+  "conversation.expired"
+];
+var KNOWN = new Set(WEBHOOK_EVENT_TYPES);
+var CONVERSATION_STATUSES = {
+  "conversation.updated": ["in_progress", "failed"],
+  "conversation.completed": ["completed"],
+  "conversation.failed": ["failed"],
+  "conversation.expired": ["expired"]
+};
+var ENVIRONMENTS = /* @__PURE__ */ new Set(["mock", "development", "production"]);
+function isConversationEvent(event) {
+  return event.type.startsWith("conversation.");
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readBody(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return webhookError("invalid_body", "the body is not JSON");
+  }
+  if (!isObject(parsed) || typeof parsed.id !== "string" || typeof parsed.type !== "string" || typeof parsed.created_at !== "string" || typeof parsed.environment !== "string" || !ENVIRONMENTS.has(parsed.environment) || !isObject(parsed.data)) {
+    return webhookError(
+      "invalid_body",
+      "the body is not a webhook envelope (id, type, created_at, environment, data)"
+    );
+  }
+  const envelope = parsed;
+  if (parsed.data.test === true) return { kind: "test", envelope };
+  if (!KNOWN.has(parsed.type)) return { kind: "unrecognized", envelope };
+  const statuses = CONVERSATION_STATUSES[parsed.type];
+  if (statuses) {
+    const { conversation_id, sequence, status, flow } = parsed.data;
+    if (typeof conversation_id !== "string" || !Number.isSafeInteger(sequence) || sequence < 1 || typeof status !== "string" || !statuses.includes(status) || typeof flow !== "string") {
+      return webhookError(
+        "invalid_body",
+        `a ${parsed.type} event carries a guided flow's state: conversation_id, a positive integer sequence, a flow, and status ${statuses.join(" or ")}`
+      );
+    }
+  }
+  return { kind: "event", event: parsed };
+}
+
+// src/webhooks/signature.ts
+var SIGNATURE_HEADER = "Vinaverse-Signature";
+var TOLERANCE_SECONDS = 300;
+var DIGITS = /^[0-9]+$/;
+var V1 = /^[0-9a-f]{64}$/;
+function parseSignatureHeader(header) {
+  const parts = header.split(",").map((p) => p.trim()).filter((p) => p.includes("=")).map((p) => {
+    const at = p.indexOf("=");
+    return [p.slice(0, at), p.slice(at + 1)];
+  });
+  const timestamps = parts.filter(([k]) => k === "t").map(([, v]) => v);
+  const [t] = timestamps;
+  if (timestamps.length !== 1 || t === void 0 || !DIGITS.test(t)) {
+    return webhookError(
+      "malformed",
+      "the signature header needs exactly one timestamp, t=<unix seconds>"
+    );
+  }
+  const signatures = parts.filter(([k, v]) => k === "v1" && V1.test(v)).map(([, v]) => hexToBytes(v));
+  if (signatures.length === 0) {
+    return webhookError(
+      "malformed",
+      "the signature header has no v1 signature"
+    );
+  }
+  return { timestamp: BigInt(t), signatures };
+}
+async function checkSignature(options) {
+  const parsed = parseSignatureHeader(options.header);
+  if ("code" in parsed) return parsed;
+  const now = BigInt(Math.floor(options.now.getTime() / 1e3));
+  const skew = now > parsed.timestamp ? now - parsed.timestamp : parsed.timestamp - now;
+  if (skew > BigInt(options.toleranceSeconds)) {
+    return webhookError(
+      "stale",
+      `the signature is ${skew} seconds from now; at most ${options.toleranceSeconds} are accepted`
+    );
+  }
+  const message = concat(utf8(`${parsed.timestamp}.`), options.body);
+  const subtle = await subtleCrypto();
+  for (const secret of options.secrets) {
+    const key = await hmacKey(secret, "verify");
+    for (const signature of parsed.signatures) {
+      if (await subtle.verify(
+        "HMAC",
+        key,
+        signature,
+        message
+      ))
+        return null;
+    }
+  }
+  return webhookError(
+    "mismatch",
+    "no signature matches the body with the signing secret: check the secret, and verify the raw body exactly as received"
+  );
+}
+
+// src/webhooks/verify.ts
+async function verifyWebhook(options) {
+  const secrets = signingSecrets(options.secret);
+  const toleranceSeconds = checkTolerance(options.toleranceSeconds);
+  const header = singleHeader(options.header);
+  if (header === void 0) {
+    return {
+      ok: false,
+      error: webhookError("missing", "no Vinaverse-Signature header")
+    };
+  }
+  if (header === null) {
+    return {
+      ok: false,
+      error: webhookError(
+        "malformed",
+        "more than one Vinaverse-Signature header"
+      )
+    };
+  }
+  const body = toBytes(options.rawBody);
+  const refused = await checkSignature({
+    body,
+    header,
+    secrets,
+    now: options.now ?? /* @__PURE__ */ new Date(),
+    toleranceSeconds
+  });
+  if (refused) return { ok: false, error: refused };
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(body);
+  } catch {
+    return {
+      ok: false,
+      error: webhookError("invalid_body", "the body is not UTF-8")
+    };
+  }
+  const read = readBody(text);
+  return "code" in read ? { ok: false, error: read } : { ok: true, ...read };
+}
+function singleHeader(header) {
+  if (header === null || header === void 0) return void 0;
+  if (typeof header === "string") return header === "" ? void 0 : header;
+  if (header.length === 0) return void 0;
+  return header.length === 1 ? header[0] : null;
+}
+function signingSecrets(secret) {
+  const list = typeof secret === "string" ? [secret] : Array.isArray(secret) ? [...secret] : [];
+  if (list.length === 0 || list.some((s) => typeof s !== "string" || s === "")) {
+    throw new TypeError(
+      "the webhook signing secret is required (vv_whsec_\u2026), and none was given"
+    );
+  }
+  return list;
+}
+function checkTolerance(seconds) {
+  if (seconds === void 0) return TOLERANCE_SECONDS;
+  if (!Number.isSafeInteger(seconds) || seconds < 0 || seconds > TOLERANCE_SECONDS) {
+    throw new TypeError(
+      `toleranceSeconds must be a whole number of seconds from 0 to ${TOLERANCE_SECONDS}, not ${seconds}`
+    );
+  }
+  return seconds;
+}
+
+// src/adapters/handler.ts
+var MAX_BODY_BYTES = 1024 * 1024;
+var RECEIVED = JSON.stringify({ received: true });
+function tooLarge() {
+  return {
+    status: 413,
+    body: JSON.stringify({ error: { code: "body_too_large" } })
+  };
+}
+function byteLength(body) {
+  return typeof body === "string" ? new TextEncoder().encode(body).length : body.byteLength;
+}
+async function handleWebhook(options, rawBody, header) {
+  if (byteLength(rawBody) > (options.maxBodyBytes ?? MAX_BODY_BYTES)) {
+    return tooLarge();
+  }
+  const result = await verifyWebhook({
+    rawBody,
+    header,
+    secret: options.secret,
+    ...options.now ? { now: options.now() } : {},
+    ...options.toleranceSeconds === void 0 ? {} : { toleranceSeconds: options.toleranceSeconds }
+  });
+  if (!result.ok) {
+    await options.onRejected?.(result.error);
+    return {
+      status: 400,
+      body: JSON.stringify({ error: { code: result.error.code } })
+    };
+  }
+  if (result.kind === "event") await options.onEvent(result.event);
+  else if (result.kind === "test") await options.onTest?.(result.envelope);
+  else await options.onUnrecognized?.(result.envelope);
+  return { status: 200, body: RECEIVED };
+}
+function checkHandlerOptions(options) {
+  signingSecrets(options.secret);
+  checkTolerance(options.toleranceSeconds);
+  if (typeof options.onEvent !== "function") {
+    throw new TypeError(
+      "onEvent is required: it receives every verified event"
+    );
+  }
+  const max = options.maxBodyBytes;
+  if (max !== void 0 && (!Number.isSafeInteger(max) || max <= 0)) {
+    throw new TypeError(
+      `maxBodyBytes must be a positive whole number of bytes, not ${max}`
+    );
+  }
+}
+
+// src/adapters/fetch.ts
+function createFetchWebhookHandler(options) {
+  checkHandlerOptions(options);
+  const max = options.maxBodyBytes ?? MAX_BODY_BYTES;
+  return async (request) => {
+    const body = await readCapped(request, max);
+    if (body === void 0) return toResponse(tooLarge());
+    return toResponse(
+      await handleWebhook(
+        options,
+        body,
+        request.headers.get("vinaverse-signature")
+      )
+    );
+  };
+}
+async function readCapped(request, max) {
+  const declared = Number(request.headers.get("content-length") ?? "0");
+  if (declared > max) return void 0;
+  if (!request.body) return new Uint8Array(0);
+  const reader = request.body.getReader();
+  const chunks = [];
+  let size = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.length;
+    if (size > max) {
+      await reader.cancel();
+      return void 0;
+    }
+    chunks.push(value);
+  }
+  const body = new Uint8Array(size);
+  let at = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, at);
+    at += chunk.length;
+  }
+  return body;
+}
+function toResponse(response) {
+  return new Response(response.body, {
+    status: response.status,
+    headers: { "content-type": "application/json" }
+  });
+}
+function createFetchToolHandler(provider, options = {}) {
+  const max = options.maxBodyBytes ?? MAX_BODY_BYTES;
+  return async (request) => {
+    const url = new URL(request.url);
+    const reads = request.method !== "GET" && request.method !== "HEAD";
+    const body = reads ? await readCapped(request, max) : null;
+    if (body === void 0) {
+      return new Response(
+        JSON.stringify({
+          status: 413,
+          code: "invalid_argument",
+          detail: "the request body is too large"
+        }),
+        {
+          status: 413,
+          headers: { "content-type": "application/problem+json" }
+        }
+      );
+    }
+    const response = await provider.handle({
+      method: request.method,
+      target: `${url.pathname}${url.search}`,
+      header: (name) => request.headers.get(name) ?? void 0,
+      body
+    });
+    return new Response(response.body, {
+      status: response.status,
+      headers: response.headers
+    });
+  };
+}
+
+// src/contract.ts
+var CONTRACT = {
+  api: "v1-draft.17",
+  commit: "fe4fb7d2945e1ced2bce7d44e85a4b28005e46df"
+};
+
+// src/generated/tool-operations.ts
+var TOOL_OPERATIONS = {
+  create_handoff: {
+    id: "create_handoff",
+    method: "POST",
+    path: "/handoffs",
+    effect: "write",
+    maxResultBytes: 16384,
+    successStatus: 201,
+    idempotencyKey: true,
+    body: true,
+    pathParams: {},
+    queryParams: {}
+  },
+  create_proposal: {
+    id: "create_proposal",
+    method: "POST",
+    path: "/proposals",
+    effect: "propose",
+    maxResultBytes: 16384,
+    successStatus: 201,
+    idempotencyKey: true,
+    body: true,
+    pathParams: {},
+    queryParams: {}
+  },
+  get_availability: {
+    id: "get_availability",
+    method: "GET",
+    path: "/availability",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      professional_id: { type: "string", required: true },
+      service_id: { type: "string", required: true },
+      from: { type: "string", required: true },
+      to: { type: "string", required: true },
+      limit: { type: "integer", required: false }
+    }
+  },
+  get_flow_definition: {
+    id: "get_flow_definition",
+    method: "GET",
+    path: "/flows/{flow}/definition",
+    effect: "read",
+    maxResultBytes: 131072,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: { flow: { type: "string", required: true } },
+    queryParams: { version: { type: "integer", required: false } }
+  },
+  get_my_booking: {
+    id: "get_my_booking",
+    method: "GET",
+    path: "/me/bookings/{id}",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: { id: { type: "string", required: true } },
+    queryParams: {}
+  },
+  get_my_kit: {
+    id: "get_my_kit",
+    method: "GET",
+    path: "/me/kits/{id}",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: { id: { type: "string", required: true } },
+    queryParams: {}
+  },
+  get_my_order: {
+    id: "get_my_order",
+    method: "GET",
+    path: "/me/orders/{id}",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: { id: { type: "string", required: true } },
+    queryParams: {}
+  },
+  get_policy: {
+    id: "get_policy",
+    method: "GET",
+    path: "/policies/{topic}",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: { topic: { type: "string", required: true } },
+    queryParams: {}
+  },
+  get_professional: {
+    id: "get_professional",
+    method: "GET",
+    path: "/professionals/{id}",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: { id: { type: "string", required: true } },
+    queryParams: {}
+  },
+  get_quote: {
+    id: "get_quote",
+    method: "POST",
+    path: "/quotes",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: true,
+    body: true,
+    pathParams: {},
+    queryParams: {}
+  },
+  get_workspace: {
+    id: "get_workspace",
+    method: "GET",
+    path: "/workspaces/{id}",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: { id: { type: "string", required: true } },
+    queryParams: {}
+  },
+  list_my_bookings: {
+    id: "list_my_bookings",
+    method: "GET",
+    path: "/me/bookings",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      scope: { type: "string", required: false },
+      limit: { type: "integer", required: false }
+    }
+  },
+  list_my_kits: {
+    id: "list_my_kits",
+    method: "GET",
+    path: "/me/kits",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      scope: { type: "string", required: false },
+      limit: { type: "integer", required: false }
+    }
+  },
+  list_my_orders: {
+    id: "list_my_orders",
+    method: "GET",
+    path: "/me/orders",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      kit_id: { type: "string", required: false },
+      limit: { type: "integer", required: false }
+    }
+  },
+  list_services: {
+    id: "list_services",
+    method: "GET",
+    path: "/catalog/services",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      q: { type: "string", required: true },
+      limit: { type: "integer", required: false }
+    }
+  },
+  resolve_place: {
+    id: "resolve_place",
+    method: "GET",
+    path: "/places/resolve",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      text: { type: "string", required: true },
+      near_lat: { type: "number", required: false },
+      near_lng: { type: "number", required: false }
+    }
+  },
+  search_professionals: {
+    id: "search_professionals",
+    method: "GET",
+    path: "/search/professionals",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      q: { type: "string", required: false },
+      category_id: { type: "string", required: false },
+      service_type_id: { type: "string", required: false },
+      lat: { type: "number", required: false },
+      lng: { type: "number", required: false },
+      radius_miles: { type: "integer", required: false },
+      date: { type: "string", required: false },
+      time_from: { type: "string", required: false },
+      time_to: { type: "string", required: false },
+      max_price: { type: "integer", required: false },
+      min_rating_ppm: { type: "integer", required: false },
+      sort: { type: "string", required: false },
+      limit: { type: "integer", required: false },
+      cursor: { type: "string", required: false }
+    }
+  },
+  search_workspaces: {
+    id: "search_workspaces",
+    method: "GET",
+    path: "/search/workspaces",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      q: { type: "string", required: false },
+      space_category: { type: "string", required: false },
+      lat: { type: "number", required: false },
+      lng: { type: "number", required: false },
+      radius_miles: { type: "integer", required: false },
+      max_price: { type: "integer", required: false },
+      min_rating_ppm: { type: "integer", required: false },
+      sort: { type: "string", required: false },
+      limit: { type: "integer", required: false },
+      cursor: { type: "string", required: false }
+    }
+  },
+  submit_flow: {
+    id: "submit_flow",
+    method: "POST",
+    path: "/flows/{flow}/submissions",
+    effect: "write",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: true,
+    pathParams: { flow: { type: "string", required: true } },
+    queryParams: {}
+  }
+};
+
+// src/tools/idempotency.ts
+var MemoryIdempotencyStore = class {
+  #held = /* @__PURE__ */ new Map();
+  #now;
+  #sweepEvery;
+  #starts = 0;
+  constructor(options = {}) {
+    this.#now = options.now ?? (() => Date.now() / 1e3);
+    this.#sweepEvery = Math.max(1, options.sweepEvery ?? 256);
+  }
+  async start(key, fingerprint2, pendingSeconds, owner) {
+    const now = this.#now();
+    if (++this.#starts % this.#sweepEvery === 0) {
+      for (const [k, h] of this.#held) if (h.until < now) this.#held.delete(k);
+    }
+    const held = this.#live(key);
+    if (held) return held.record;
+    this.#held.set(key, {
+      record: { fingerprint: fingerprint2, state: "pending" },
+      owner,
+      until: now + pendingSeconds
+    });
+    return null;
+  }
+  async finish(key, record, keepSeconds, owner) {
+    const held = this.#live(key);
+    if (held && (held.record.state !== "pending" || held.owner !== owner)) {
+      return false;
+    }
+    this.#held.set(key, {
+      record: { ...record, state: "done" },
+      until: this.#now() + keepSeconds
+    });
+    return true;
+  }
+  async release(key, owner) {
+    const held = this.#live(key);
+    if (held?.record.state === "pending" && held.owner === owner) {
+      this.#held.delete(key);
+    }
+  }
+  /** Records held, expired ones included until a sweep drops them. */
+  get size() {
+    return this.#held.size;
+  }
+  #live(key) {
+    const held = this.#held.get(key);
+    return held && held.until >= this.#now() ? held : void 0;
+  }
+};
+function fingerprint(value) {
+  return sha256Hex(utf8(canonicalJson(value)));
+}
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+// src/tools/nonces.ts
+var NONCE_KEEP_SECONDS = 360;
+var MemoryNonceStore = class {
+  #seen = /* @__PURE__ */ new Map();
+  #now;
+  #sweepEvery;
+  #claims = 0;
+  constructor(options = {}) {
+    this.#now = options.now ?? (() => Math.floor(Date.now() / 1e3));
+    this.#sweepEvery = Math.max(1, options.sweepEvery ?? 256);
+  }
+  async claim(nonce, keepUntil) {
+    const now = this.#now();
+    if (++this.#claims % this.#sweepEvery === 0) {
+      for (const [n, until2] of this.#seen) {
+        if (until2 < now) this.#seen.delete(n);
+      }
+    }
+    const until = this.#seen.get(nonce);
+    if (until !== void 0 && until >= now) return false;
+    this.#seen.set(nonce, keepUntil);
+    return true;
+  }
+  /** Nonces held, expired ones included until a sweep drops them. */
+  get size() {
+    return this.#seen.size;
+  }
+};
+
+// src/tools/refusals.ts
+var FLOW_REFUSAL_CODES = {
+  REQUIRED_MISSING: true,
+  UNKNOWN_VALUE: true,
+  TOO_LONG: true,
+  VERSION_NOT_ACCEPTED: true,
+  TOO_MANY: true,
+  TOO_FEW: true,
+  BAD_DATE: true,
+  UPLOAD_NOT_FOUND: true,
+  OUT_OF_RANGE: true
+};
+function isFlowRefusal(problem2) {
+  return problem2.status === 422 && Object.hasOwn(FLOW_REFUSAL_CODES, problem2.code) && (problem2.code === "VERSION_NOT_ACCEPTED" || !!problem2.question_id);
+}
+var STATUS = {
+  not_found: 404,
+  forbidden: 403,
+  invalid_argument: 422,
+  unavailable: 503,
+  token_expired: 401
+};
+var ToolRefusal = class _ToolRefusal extends Error {
+  problem;
+  constructor(problem2) {
+    super(problem2.detail ?? problem2.code);
+    this.name = "ToolRefusal";
+    this.problem = problem2;
+  }
+  get status() {
+    return this.problem.status;
+  }
+  /** The record does not exist, or the person may not see it (both are the same 404). */
+  static notFound(detail) {
+    return _ToolRefusal.#coded("not_found", detail);
+  }
+  static forbidden(detail) {
+    return _ToolRefusal.#coded("forbidden", detail);
+  }
+  /**
+   * A value the tenant does not accept. `field` is a JSON Pointer into the
+   * body (`/changes/address/postal_code`); `example` is a valid value the
+   * agent offers when it asks again.
+   */
+  static invalidArgument(options = {}) {
+    return new _ToolRefusal({
+      status: 422,
+      code: "invalid_argument",
+      ...clip("detail", options.detail, 300),
+      ...clip("field", options.field, 200),
+      ...clip("example", options.example, 200)
+    });
+  }
+  /** A temporary failure; a read is retried. */
+  static unavailable(detail) {
+    return _ToolRefusal.#coded("unavailable", detail);
+  }
+  /** The delegated token is not valid (expired, revoked, unknown): a 401, which ends the session's tool access. */
+  static tokenExpired(detail) {
+    return _ToolRefusal.#coded("token_expired", detail);
+  }
+  /** `get_flow_definition` with a `version` the tenant no longer accepts: `410 VERSION_GONE`. */
+  static versionGone(detail) {
+    return new _ToolRefusal({
+      status: 410,
+      code: "VERSION_GONE",
+      ...clip("detail", detail, 300)
+    });
+  }
+  /**
+   * `submit_flow` refused: `422` with a flow code and the question to ask
+   * again (none only for `VERSION_NOT_ACCEPTED`). Stored like an acceptance,
+   * so the same submission gets the same refusal again.
+   */
+  static flowRefused(code, questionId, detail) {
+    if (code !== "VERSION_NOT_ACCEPTED" && !questionId) {
+      throw new TypeError(`a ${code} refusal names the question to ask again`);
+    }
+    return new _ToolRefusal({
+      status: 422,
+      code,
+      ...questionId ? { question_id: questionId } : {},
+      ...clip("detail", detail, 300)
+    });
+  }
+  static #coded(code, detail) {
+    return new _ToolRefusal({
+      status: STATUS[code],
+      code,
+      ...clip("detail", detail, 300)
+    });
+  }
+};
+function clip(key, value, max) {
+  if (value === void 0) return {};
+  return { [key]: [...value].slice(0, max).join("") };
+}
+
+// src/tools/signature.ts
+var TOOL_TOLERANCE_SECONDS = 300;
+var T = /^[0-9]{1,12}$/;
+var NONCE = /^[A-Za-z0-9_-]{16,64}$/;
+var MAC = /^[0-9a-f]{64}$/;
+function parseToolSignature(header) {
+  let t;
+  let n;
+  let seenT = 0;
+  let seenN = 0;
+  const v2 = [];
+  for (const part of header.split(",")) {
+    const trimmed = part.trim();
+    const at = trimmed.indexOf("=");
+    const key = at < 0 ? trimmed : trimmed.slice(0, at);
+    const value = at < 0 ? "" : trimmed.slice(at + 1);
+    if (key === "t") {
+      seenT++;
+      if (T.test(value)) t = Number(value);
+    } else if (key === "n") {
+      seenN++;
+      n = value;
+    } else if (key === "v2" && MAC.test(value)) {
+      v2.push(value);
+    }
+  }
+  return { t, n, v2, repeated: seenT > 1 || seenN > 1 };
+}
+async function toolSigningString(call) {
+  const bodyHash = call.body && call.body.length > 0 ? await sha256Hex(call.body) : "";
+  return utf8(
+    [
+      "v2",
+      String(call.t),
+      call.n,
+      call.method.toUpperCase(),
+      call.target,
+      await sha256Hex(utf8(call.token)),
+      bodyHash
+    ].join("\n")
+  );
+}
+async function verifyToolCall(call, options) {
+  if (!call.header) {
+    return refusal("missing", "no Vinaverse-Signature header");
+  }
+  const { t, n, v2, repeated } = parseToolSignature(call.header);
+  if (repeated) {
+    return refusal(
+      "malformed",
+      "the signature repeats t or n: an ambiguous header"
+    );
+  }
+  if (t === void 0) {
+    return refusal(
+      "malformed",
+      "the signature has no timestamp t=<unix seconds>"
+    );
+  }
+  const now = Math.floor(options.now.getTime() / 1e3);
+  const tolerance = options.toleranceSeconds === void 0 ? TOOL_TOLERANCE_SECONDS : checkTolerance(options.toleranceSeconds);
+  if (Math.abs(now - t) > tolerance) {
+    return refusal(
+      "stale",
+      `the signature is ${Math.abs(now - t)} seconds from now; at most ${tolerance} are accepted`
+    );
+  }
+  if (v2.length === 0) {
+    return refusal(
+      "v2_required",
+      "the signature has no v2 (a v1-only header binds neither the token nor a nonce)"
+    );
+  }
+  if (n === void 0 || !NONCE.test(n)) {
+    return refusal(
+      "malformed",
+      "the signature has no valid nonce n (16 to 64 of A-Z a-z 0-9 - _)"
+    );
+  }
+  const message = await toolSigningString({ ...call, t, n });
+  const subtle = await subtleCrypto();
+  let matched = false;
+  for (const secret of options.secrets) {
+    const key = await hmacKey(secret, "verify");
+    for (const mac of v2) {
+      if (await subtle.verify("HMAC", key, hexToBytes(mac), message)) {
+        matched = true;
+        break;
+      }
+    }
+    if (matched) break;
+  }
+  if (!matched) {
+    return refusal(
+      "mismatch",
+      "no v2 signature matches: check the tool signing secret, and verify the method, target, token and body exactly as received"
+    );
+  }
+  if (!await options.nonces.claim(n, Math.max(t, now) + NONCE_KEEP_SECONDS)) {
+    return refusal("replayed", "this nonce was already used: a replayed call");
+  }
+  return null;
+}
+function refusal(code, message) {
+  return { code, message };
+}
+
+// src/tools/provider.ts
+var ACCEPTED = { ok: true };
+var KEEP_SECONDS = {
+  submit_flow: 31 * 86400,
+  // a conversation lives up to 30 days, and a submission is resent in later sessions
+  create_proposal: 8 * 86400,
+  // at least until the proposal expires (at most 7 days)
+  default: 86400,
+  pending: 60
+};
+var MAX_IDEMPOTENCY_KEY = 255;
+var MAX_REQUEST_BYTES = 1024 * 1024;
+var LeaseLostError = class extends Error {
+  constructor(operation, leaseSeconds) {
+    super(
+      `${operation} ran longer than its ${leaseSeconds}-second idempotency lease and another call took the key: the answer was sent but not stored (raise leaseSeconds)`
+    );
+    this.name = "LeaseLostError";
+  }
+};
+var ResultTooLargeError = class extends Error {
+  constructor(operation, bytes, limit) {
+    super(
+      `${operation} returned ${bytes} bytes; the contract allows ${limit}: the runtime would refuse it`
+    );
+    this.name = "ResultTooLargeError";
+  }
+};
+function createToolProvider(options) {
+  const secrets = typeof options.secret === "string" ? [options.secret] : [...options.secret];
+  if (secrets.length === 0 || secrets.some((s) => typeof s !== "string" || !s)) {
+    throw new TypeError("createToolProvider needs the tool signing secret");
+  }
+  checkTolerance(options.toleranceSeconds);
+  const maxRequest = options.maxRequestBytes;
+  if (maxRequest !== void 0 && (!Number.isSafeInteger(maxRequest) || maxRequest <= 0)) {
+    throw new TypeError(
+      `maxRequestBytes must be a positive whole number of bytes, not ${maxRequest}`
+    );
+  }
+  const lease = options.leaseSeconds ?? KEEP_SECONDS.pending;
+  if (!Number.isFinite(lease) || lease <= 0) {
+    throw new TypeError(
+      `leaseSeconds must be a positive number of seconds, not ${options.leaseSeconds}`
+    );
+  }
+  if (typeof options.authenticate !== "function") {
+    throw new TypeError(
+      "createToolProvider needs authenticate: it resolves the delegated token"
+    );
+  }
+  const base = (options.basePath ?? "").replace(/\/+$/, "");
+  const routes = Object.values(TOOL_OPERATIONS).map((o) => ({
+    id: o.id,
+    segments: o.path.split("/").filter(Boolean)
+  }));
+  async function handle(request) {
+    const raw = request.body ?? new Uint8Array(0);
+    const body = toBytes(raw);
+    if (body.length > (options.maxRequestBytes ?? MAX_REQUEST_BYTES)) {
+      return problem({
+        status: 413,
+        code: "invalid_argument",
+        detail: "the request body is too large"
+      });
+    }
+    const token = bearer(request.header("authorization"));
+    if (!token) {
+      return problem({
+        status: 401,
+        code: "token_expired",
+        detail: "no delegated token (Authorization: Bearer)"
+      });
+    }
+    const refused = await verifyToolCall(
+      {
+        method: request.method,
+        target: request.target,
+        token,
+        body,
+        header: request.header("vinaverse-signature")
+      },
+      {
+        secrets,
+        nonces: options.nonces,
+        now: options.now?.() ?? /* @__PURE__ */ new Date(),
+        ...options.toleranceSeconds === void 0 ? {} : { toleranceSeconds: options.toleranceSeconds }
+      }
+    );
+    if (refused) {
+      options.onRefused?.(refused.code, refused.message);
+      return problem({
+        status: 403,
+        code: "forbidden",
+        detail: "the signature was refused"
+      });
+    }
+    const matched = match(request.method, request.target);
+    if (!matched)
+      return problem({
+        status: 404,
+        code: "not_found",
+        detail: "no such tool"
+      });
+    const { id, params, query } = matched;
+    const operation = TOOL_OPERATIONS[id];
+    const handler = options.handlers[id];
+    if (!handler)
+      return problem({
+        status: 404,
+        code: "not_found",
+        detail: `${id} is not served here`
+      });
+    try {
+      const principal = await options.authenticate(token, id);
+      const typedQuery = readQuery(id, query);
+      const parsed = operation.body ? parseBody(body) : void 0;
+      const key = request.header("idempotency-key");
+      if (operation.idempotencyKey && !key) {
+        throw ToolRefusal.invalidArgument({
+          detail: "the Idempotency-Key header is required"
+        });
+      }
+      if (key && key.length > MAX_IDEMPOTENCY_KEY) {
+        throw ToolRefusal.invalidArgument({
+          detail: `the Idempotency-Key is longer than ${MAX_IDEMPOTENCY_KEY} characters`
+        });
+      }
+      const call = {
+        operation: id,
+        principal,
+        token,
+        params,
+        query: typedQuery,
+        body: parsed,
+        session: session(request),
+        ...key ? { idempotencyKey: key } : {}
+      };
+      const run = () => runHandler(id, handler, call);
+      const scope = options.scope?.(principal, id);
+      const keyOf = (...parts) => (scope === void 0 ? parts : [scope, ...parts]).map(encodeURIComponent).join(":");
+      if (id === "submit_flow")
+        return await submission(keyOf, params, parsed, run);
+      if (id === "create_proposal" && key)
+        return await proposal(keyOf(id, key), parsed, principal, run);
+      if (operation.idempotencyKey && key) {
+        return await keyed(
+          id,
+          keyOf(id, key),
+          await fingerprint(parsed),
+          KEEP_SECONDS.default,
+          run,
+          () => problem({
+            status: 409,
+            code: "IDEMPOTENCY_KEY_REUSED",
+            detail: "this Idempotency-Key was used with another body"
+          })
+        );
+      }
+      return await run();
+    } catch (error) {
+      return failure(error, id);
+    }
+  }
+  async function runHandler(id, handler, call) {
+    const result = await handler(call) ?? (id === "submit_flow" ? ACCEPTED : void 0);
+    if (result === void 0) {
+      throw new TypeError(`the ${id} handler returned nothing`);
+    }
+    const text = JSON.stringify(result);
+    const limit = TOOL_OPERATIONS[id].maxResultBytes;
+    const bytes = toBytes(text).length;
+    if (bytes > limit) throw new ResultTooLargeError(id, bytes, limit);
+    return json(TOOL_OPERATIONS[id].successStatus, text);
+  }
+  async function keyed(id, key, print, keepSeconds, run, conflict, replay, keeps = (r) => r.status === 422) {
+    const store = options.idempotency;
+    const owner = await ownerToken();
+    const held = await store.start(key, print, lease, owner);
+    if (held) {
+      if (held.state === "pending") {
+        return problem({
+          status: 503,
+          code: "unavailable",
+          detail: "the same call is still running"
+        });
+      }
+      if (held.fingerprint !== print) return conflict(held);
+      return replay ? replay(held) : stored(held);
+    }
+    let response;
+    try {
+      response = await run();
+    } catch (error) {
+      if (!(error instanceof ToolRefusal && keeps(error))) {
+        await store.release(key, owner);
+        throw error;
+      }
+      response = problem(error.problem);
+    }
+    try {
+      const kept = await store.finish(
+        key,
+        { fingerprint: print, status: response.status, body: response.body },
+        keepSeconds,
+        owner
+      );
+      if (!kept) options.onError?.(new LeaseLostError(id, lease), id);
+    } catch (error) {
+      options.onError?.(error, id);
+    }
+    return response;
+  }
+  async function submission(keyOf, params, body, run) {
+    const submissionId = body?.submission_id;
+    if (typeof submissionId !== "string" || submissionId === "") {
+      throw ToolRefusal.invalidArgument({
+        field: "/submission_id",
+        detail: "a submission needs its submission_id"
+      });
+    }
+    const refused = async () => {
+      try {
+        return await run();
+      } catch (error) {
+        if (error instanceof ToolRefusal && error.status === 422 && !isFlowRefusal(error.problem)) {
+          throw new TypeError(
+            `submit_flow refused with ${error.problem.code}: a submission is refused only with ToolRefusal.flowRefused (a flow code and the question to ask again)`
+          );
+        }
+        throw error;
+      }
+    };
+    return keyed(
+      "submit_flow",
+      keyOf("submit_flow", params.flow ?? "", submissionId),
+      await fingerprint(body),
+      KEEP_SECONDS.submit_flow,
+      refused,
+      (held) => {
+        const was = held.body ? JSON.parse(held.body) : {};
+        const storedResult = held.status === 200 ? { result: "accepted" } : {
+          result: "refused",
+          ...was.code ? { code: was.code } : {},
+          ...was.question_id ? { question_id: was.question_id } : {}
+        };
+        return json(
+          409,
+          JSON.stringify({
+            status: 409,
+            code: "SUBMISSION_ID_REUSED",
+            stored: storedResult
+          }),
+          "application/problem+json"
+        );
+      },
+      void 0,
+      (r) => isFlowRefusal(r.problem)
+    );
+  }
+  async function proposal(key, body, principal, run) {
+    const { topic, changes } = body ?? {};
+    const current = async (held) => {
+      const storedProposal = JSON.parse(
+        held.body ?? "null"
+      );
+      return options.currentProposal ? await options.currentProposal(storedProposal, principal) : storedProposal;
+    };
+    return keyed(
+      "create_proposal",
+      key,
+      await fingerprint({ topic, changes }),
+      KEEP_SECONDS.create_proposal,
+      run,
+      async (held) => held.status === 201 ? json(
+        409,
+        JSON.stringify({
+          status: 409,
+          code: "IDEMPOTENCY_KEY_REUSED",
+          proposal: await current(held)
+        }),
+        "application/problem+json"
+      ) : stored(held),
+      async (held) => held.status === 201 ? json(201, JSON.stringify(await current(held))) : stored(held)
+    );
+  }
+  function match(method, target) {
+    const at = target.indexOf("?");
+    const path = at < 0 ? target : target.slice(0, at);
+    const query = new URLSearchParams(at < 0 ? "" : target.slice(at + 1));
+    if (base && path !== base && !path.startsWith(`${base}/`)) return void 0;
+    const segments = path.slice(base.length).split("/").filter(Boolean);
+    for (const route of routes) {
+      if (TOOL_OPERATIONS[route.id].method !== method.toUpperCase()) continue;
+      if (route.segments.length !== segments.length) continue;
+      const params = {};
+      let ok = true;
+      for (const [i, part] of route.segments.entries()) {
+        const actual = segments[i];
+        if (part.startsWith("{") && part.endsWith("}")) {
+          try {
+            params[part.slice(1, -1)] = decodeURIComponent(actual);
+          } catch {
+            ok = false;
+          }
+        } else if (part !== actual) {
+          ok = false;
+        }
+        if (!ok) break;
+      }
+      if (ok) return { id: route.id, params, query };
+    }
+    return void 0;
+  }
+  function failure(error, id) {
+    if (error instanceof ToolRefusal) return problem(error.problem);
+    options.onError?.(error, id);
+    return problem({
+      status: 500,
+      code: "unavailable",
+      detail: "the tool failed"
+    });
+  }
+  return { handle };
+}
+function readQuery(id, query) {
+  const declared = TOOL_OPERATIONS[id].queryParams;
+  const out = {};
+  for (const [name, spec] of Object.entries(declared)) {
+    const value = query.get(name);
+    if (value === null) {
+      if (spec.required)
+        throw ToolRefusal.invalidArgument({
+          detail: `the query parameter ${name} is required`
+        });
+      continue;
+    }
+    if (spec.type === "integer" || spec.type === "number") {
+      const n = Number(value);
+      if (value.trim() === "" || !Number.isFinite(n) || spec.type === "integer" && !Number.isInteger(n)) {
+        throw ToolRefusal.invalidArgument({
+          detail: `the query parameter ${name} must be ${spec.type === "integer" ? "an integer" : "a number"}`
+        });
+      }
+      out[name] = n;
+    } else {
+      out[name] = value;
+    }
+  }
+  return out;
+}
+function parseBody(body) {
+  if (body.length === 0)
+    throw ToolRefusal.invalidArgument({
+      detail: "the request needs a JSON body"
+    });
+  try {
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(body));
+  } catch {
+    throw ToolRefusal.invalidArgument({
+      detail: "the request body is not JSON"
+    });
+  }
+}
+function bearer(value) {
+  const m = /^Bearer\s+(\S+)\s*$/i.exec(value ?? "");
+  return m?.[1];
+}
+function session(request) {
+  const pick = (name) => request.header(name);
+  const entries = {
+    id: pick("vinaverse-session") ?? pick("vinaverse-session-id"),
+    conversationId: pick("vinaverse-conversation"),
+    toolCallId: pick("vinaverse-tool-call-id"),
+    requestId: pick("vinaverse-request-id")
+  };
+  return Object.fromEntries(
+    Object.entries(entries).filter(([, v]) => v !== void 0)
+  );
+}
+async function ownerToken() {
+  const bytes = (await webCrypto()).getRandomValues(new Uint8Array(16));
+  return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function json(status, body, type = "application/json") {
+  return { status, headers: { "content-type": type }, body };
+}
+function problem(body) {
+  return json(body.status, JSON.stringify(body), "application/problem+json");
+}
+function stored(held) {
+  const status = held.status ?? 200;
+  return json(
+    status,
+    held.body ?? "",
+    status >= 400 ? "application/problem+json" : "application/json"
+  );
+}
+
+// src/webhooks/sequence.ts
+function sequenceVerdict(held, incoming) {
+  if (held && held.conversation_id !== incoming.conversation_id) {
+    throw new TypeError(
+      `the states belong to different conversations (${held.conversation_id}, ${incoming.conversation_id})`
+    );
+  }
+  return held && incoming.sequence <= held.sequence ? "stale" : "apply";
+}
+function applyConversationState(record, incoming) {
+  const action = sequenceVerdict(record?.state, incoming);
+  const seen = record?.seen.includes(incoming.sequence) ? record.seen : [...record?.seen ?? [], incoming.sequence].sort((a, b) => a - b);
+  if (action === "stale" && record)
+    return { record: { ...record, seen }, action };
+  if (incoming.answers_omitted === true) {
+    const { answers_omitted: _omitted, ...rest } = incoming;
+    const state = {
+      ...rest,
+      answers: record?.state.answers ?? [],
+      remarks: record?.state.remarks ?? {}
+    };
+    return { record: { state, seen, fullReadNeeded: true }, action };
+  }
+  return { record: { state: incoming, seen, fullReadNeeded: false }, action };
+}
+function missingSequences(record) {
+  const [lowest] = record.seen;
+  if (lowest === void 0) return [];
+  const missing = [];
+  for (let s = lowest + 1; s < record.state.sequence; s++) {
+    if (!record.seen.includes(s)) missing.push(s);
+  }
+  return missing;
+}
+var ConversationReceiver = class {
+  #ids = /* @__PURE__ */ new Set();
+  #records = /* @__PURE__ */ new Map();
+  /**
+   * One verified delivery (an event, or a Studio test delivery's envelope):
+   * what to do with it. The record for its conversation is then `record(id)`.
+   */
+  receive(delivery) {
+    if (this.#ids.has(delivery.id)) return "duplicate";
+    this.#ids.add(delivery.id);
+    const data = delivery.data;
+    if (data?.test === true) return "skip_test";
+    if (typeof data?.conversation_id !== "string") {
+      throw new TypeError(`${delivery.id} carries no conversation state`);
+    }
+    const state = data;
+    const { record, action } = applyConversationState(
+      this.#records.get(state.conversation_id),
+      state
+    );
+    this.#records.set(state.conversation_id, record);
+    return action;
+  }
+  record(conversationId) {
+    return this.#records.get(conversationId);
+  }
+  conversations() {
+    return [...this.#records.keys()].sort();
+  }
+};
+
+exports.CONTRACT = CONTRACT;
+exports.ConversationReceiver = ConversationReceiver;
+exports.KEEP_SECONDS = KEEP_SECONDS;
+exports.LeaseLostError = LeaseLostError;
+exports.MAX_REQUEST_BYTES = MAX_REQUEST_BYTES;
+exports.MemoryIdempotencyStore = MemoryIdempotencyStore;
+exports.MemoryNonceStore = MemoryNonceStore;
+exports.NONCE_KEEP_SECONDS = NONCE_KEEP_SECONDS;
+exports.ResultTooLargeError = ResultTooLargeError;
+exports.SIGNATURE_HEADER = SIGNATURE_HEADER;
+exports.TOLERANCE_SECONDS = TOLERANCE_SECONDS;
+exports.TOOL_OPERATIONS = TOOL_OPERATIONS;
+exports.ToolRefusal = ToolRefusal;
+exports.WEBHOOK_EVENT_TYPES = WEBHOOK_EVENT_TYPES;
+exports.WebCryptoUnavailableError = WebCryptoUnavailableError;
+exports.applyConversationState = applyConversationState;
+exports.canonicalJson = canonicalJson;
+exports.createFetchToolHandler = createFetchToolHandler;
+exports.createFetchWebhookHandler = createFetchWebhookHandler;
+exports.createToolProvider = createToolProvider;
+exports.fingerprint = fingerprint;
+exports.isConversationEvent = isConversationEvent;
+exports.missingSequences = missingSequences;
+exports.parseSignatureHeader = parseSignatureHeader;
+exports.sequenceVerdict = sequenceVerdict;
+exports.verifyToolCall = verifyToolCall;
+exports.verifyWebhook = verifyWebhook;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map