@taprootio/integration-sdk 0.0.0-stage → 0.1.2

package/src/handoff.js

@@ -0,0 +1,223 @@
+import { webcrypto } from "node:crypto";
+import { isIP } from "node:net";
+
+import { HANDOFF_JWKS_PATH, HANDOFF_LIFETIME_SECONDS } from "./constants.js";
+import { IntegrationSdkError } from "./errors.js";
+import { isPlainObject } from "./bytes.js";
+import { DuplicateJsonKeyError, parseJsonWithoutDuplicateKeys } from "./json.js";
+
+const MAX_TOKEN_LENGTH = 8 * 1024;
+const MAX_JWKS_BYTES = 64 * 1024;
+const MAX_JWKS_KEYS = 16;
+const MAX_JWKS_CACHE_SECONDS = 300;
+const MIN_UNKNOWN_KID_REFRESH_MILLISECONDS = 30_000;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const EMPTY_UUID = "00000000-0000-0000-0000-000000000000";
+const cache = new Map();
+const refreshes = new Map();
+
+function invalid(message = "The settings handoff is invalid.") {
+  return new IntegrationSdkError("invalid_handoff", message);
+}
+
+function canonicalUuid(value) {
+  if (typeof value !== "string" || !UUID.test(value) || value.toLowerCase() === EMPTY_UUID) throw invalid();
+  return value.toLowerCase();
+}
+
+function epochMilliseconds(now) {
+  if (now instanceof Date) return now.getTime();
+  if (typeof now === "number" && Number.isFinite(now)) return now;
+  throw new IntegrationSdkError("invalid_now", "now must be a Date or Unix milliseconds.");
+}
+
+function decodeBase64Url(value) {
+  if (typeof value !== "string" || value.length === 0 || !/^[A-Za-z0-9_-]+$/.test(value)) throw invalid();
+  const bytes = Buffer.from(value, "base64url");
+  if (bytes.length === 0 || bytes.toString("base64url") !== value) throw invalid();
+  return bytes;
+}
+
+function parseJson(bytes) {
+  let source;
+  try {
+    source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return parseJsonWithoutDuplicateKeys(source);
+  } catch (error) {
+    if (error instanceof DuplicateJsonKeyError) throw invalid("The settings handoff contains duplicate JSON claims.");
+    if (error instanceof IntegrationSdkError) throw error;
+    throw invalid();
+  }
+}
+
+function exactKeys(value, keys) {
+  return isPlainObject(value) && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+
+function parseToken(token) {
+  if (typeof token !== "string" || token.length === 0 || token.length > MAX_TOKEN_LENGTH) throw invalid();
+  const parts = token.split(".");
+  if (parts.length !== 3 || parts.some((part) => part.length === 0)) throw invalid();
+  return {
+    header: parseJson(decodeBase64Url(parts[0])),
+    payload: parseJson(decodeBase64Url(parts[1])),
+    signature: decodeBase64Url(parts[2]),
+    signed: new TextEncoder().encode(`${parts[0]}.${parts[1]}`),
+  };
+}
+
+function jwksCacheSeconds(value) {
+  const match = /(?:^|,)\s*max-age=(\d+)/i.exec(value ?? "");
+  return match ? Math.min(Number(match[1]), MAX_JWKS_CACHE_SECONDS) : MAX_JWKS_CACHE_SECONDS;
+}
+
+async function readJwks(response) {
+  const contentLength = response.headers.get("content-length");
+  if (contentLength && (!/^\d+$/.test(contentLength) || Number(contentLength) > MAX_JWKS_BYTES)) throw new IntegrationSdkError("jwks_unavailable", "JWKS exceeds the public handoff limit.");
+  const reader = response.body?.getReader();
+  if (!reader) throw new IntegrationSdkError("jwks_unavailable", "JWKS response has no body.");
+  const chunks = [];
+  let length = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      length += value.length;
+      if (length > MAX_JWKS_BYTES) throw new IntegrationSdkError("jwks_unavailable", "JWKS exceeds the public handoff limit.");
+      chunks.push(value);
+    }
+  } finally { reader.releaseLock(); }
+  const bytes = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length; }
+  const document = parseJson(bytes);
+  if (!exactKeys(document, ["keys"]) || !Array.isArray(document.keys) || document.keys.length > MAX_JWKS_KEYS) {
+    throw new IntegrationSdkError("jwks_unavailable", "JWKS does not match the Taproot handoff contract.");
+  }
+  const keys = new Map();
+  for (const key of document.keys) {
+    if (!exactKeys(key, ["kty", "use", "alg", "kid", "n", "e"]) || key.kty !== "RSA" || key.use !== "sig" || key.alg !== "RS256" ||
+        typeof key.kid !== "string" || key.kid.length === 0 || key.kid.length > 128 || typeof key.n !== "string" || typeof key.e !== "string" || keys.has(key.kid)) {
+      throw new IntegrationSdkError("jwks_unavailable", "JWKS does not contain valid handoff signing keys.");
+    }
+    try {
+      keys.set(key.kid, await webcrypto.subtle.importKey("jwk", key, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["verify"]));
+    } catch { throw new IntegrationSdkError("jwks_unavailable", "JWKS contains an invalid RSA key."); }
+  }
+  return keys;
+}
+
+function resolveJwksUrl(issuer, supplied) {
+  let base;
+  try { base = new URL(issuer); } catch { throw new IntegrationSdkError("invalid_issuer", "issuer must be an absolute URL."); }
+  const validOrigin = (url) => {
+    const loopback = url.hostname === "localhost" || url.hostname === "::1" || (isIP(url.hostname) === 4 && url.hostname.startsWith("127."));
+    return url.protocol === "https:" || (url.protocol === "http:" && loopback);
+  };
+  if (!validOrigin(base) || base.username || base.password || base.search || base.hash) throw new IntegrationSdkError("invalid_issuer", "issuer must be HTTPS (or loopback HTTP) without credentials, a query, or a fragment.");
+  if (supplied === undefined) return new URL(HANDOFF_JWKS_PATH, `${base.toString().replace(/\/$/, "")}/`).toString();
+  let configured;
+  try { configured = new URL(supplied); } catch { throw new IntegrationSdkError("invalid_jwks_url", "jwksUrl must be an absolute URL."); }
+  if (!validOrigin(configured) || configured.username || configured.password || configured.search || configured.hash) {
+    throw new IntegrationSdkError("invalid_jwks_url", "jwksUrl must be HTTPS (or loopback HTTP) without credentials, a query, or a fragment.");
+  }
+  return configured.toString();
+}
+
+async function refreshJwks(url, fetchImplementation, now) {
+  const existingRefresh = refreshes.get(url);
+  if (existingRefresh) return existingRefresh;
+  const refresh = (async () => {
+    let response;
+    try {
+      response = await fetchImplementation(url, { method: "GET", redirect: "manual", cache: "no-store", referrerPolicy: "no-referrer", signal: AbortSignal.timeout(10_000) });
+    } catch { throw new IntegrationSdkError("jwks_unavailable", "The handoff JWKS could not be loaded."); }
+    if (response.redirected || response.status >= 300 && response.status < 400 || !response.ok) throw new IntegrationSdkError("jwks_unavailable", "The handoff JWKS could not be loaded.");
+    const keys = await readJwks(response);
+    cache.set(url, {
+      keys,
+      fetchedAt: now,
+      expiresAt: now + jwksCacheSeconds(response.headers.get("cache-control")) * 1_000,
+    });
+    return keys;
+  })();
+  refreshes.set(url, refresh);
+  try { return await refresh; }
+  finally {
+    if (refreshes.get(url) === refresh) refreshes.delete(url);
+  }
+}
+
+async function keyFor({ issuer, jwksUrl, fetch: fetchImplementation, now, jwks }, kid) {
+  if (jwks !== undefined) {
+    const response = new Response(JSON.stringify(jwks), { headers: { "content-type": "application/jwk-set+json" } });
+    return (await readJwks(response)).get(kid);
+  }
+  if (typeof fetchImplementation !== "function") throw new IntegrationSdkError("fetch_required", "Fetching JWKS requires a Fetch-compatible implementation.");
+  const url = resolveJwksUrl(issuer, jwksUrl);
+  const existing = cache.get(url);
+  if (existing && existing.expiresAt > now && existing.keys.has(kid)) return existing.keys.get(kid);
+  if (existing && !existing.keys.has(kid) && existing.fetchedAt + MIN_UNKNOWN_KID_REFRESH_MILLISECONDS > now) return undefined;
+  const keys = await refreshJwks(url, fetchImplementation, now);
+  return keys.get(kid);
+}
+
+/**
+ * Verifies the five-minute RS256 settings handoff against the dedicated Taproot JWK set. A valid
+ * token is still only an invitation: call `confirmHandoff` once before creating a local session.
+ */
+export async function verifyHandoff({ token, issuer, audience, installationId, jwksUrl, jwks, fetch: fetchImplementation = globalThis.fetch, now = new Date() }) {
+  const parsed = parseToken(token);
+  if (!exactKeys(parsed.header, ["alg", "typ", "kid"]) || parsed.header.alg !== "RS256" || parsed.header.typ !== "JWT" ||
+      typeof parsed.header.kid !== "string" || parsed.header.kid.length === 0 || parsed.header.kid.length > 128) throw invalid();
+  const nowMilliseconds = epochMilliseconds(now);
+  const key = await keyFor({ issuer, jwksUrl, jwks, fetch: fetchImplementation, now: nowMilliseconds }, parsed.header.kid);
+  if (!key || !await webcrypto.subtle.verify("RSASSA-PKCS1-v1_5", key, parsed.signature, parsed.signed)) throw invalid();
+  const payload = parsed.payload;
+  const fields = ["iss", "aud", "sub", "site_id", "installation_id", "credential_id", "role", "engagement_id", "jti", "iat", "exp"];
+  if (!exactKeys(payload, fields) || payload.iss !== issuer || canonicalUuid(payload.aud) !== canonicalUuid(audience) ||
+      canonicalUuid(payload.installation_id) !== canonicalUuid(installationId) || !Number.isSafeInteger(payload.iat) || !Number.isSafeInteger(payload.exp)) throw invalid();
+  const issuedAt = payload.iat * 1_000;
+  const expiresAt = payload.exp * 1_000;
+  if (payload.iat <= 0 || payload.exp <= 0 || issuedAt > nowMilliseconds + 60_000 || expiresAt <= nowMilliseconds || expiresAt - issuedAt !== HANDOFF_LIFETIME_SECONDS * 1_000) throw invalid();
+  const role = payload.role;
+  const engagementId = payload.engagement_id === null ? null : canonicalUuid(payload.engagement_id);
+  if ((role !== "owner" && role !== "engagement") || (role === "owner") !== (engagementId === null)) throw invalid();
+  return Object.freeze({
+    userId: canonicalUuid(payload.sub),
+    siteId: canonicalUuid(payload.site_id),
+    installationId: canonicalUuid(payload.installation_id),
+    integrationId: canonicalUuid(payload.aud),
+    credentialId: canonicalUuid(payload.credential_id),
+    jti: canonicalUuid(payload.jti),
+    role,
+    engagementId,
+    issuedAt: new Date(issuedAt).toISOString(),
+    expiresAt: new Date(expiresAt).toISOString(),
+  });
+}
+
+/**
+ * Consumes the authoritative, single-use Taproot handoff after local verification. The caller
+ * must discard the URL token before this call and, if the response is lost, begin a new handoff.
+ */
+export async function confirmHandoff({ client, claims, token, now = new Date(), maximumSessionLifetimeSeconds = 24 * 60 * 60 }) {
+  if (!client || typeof client.confirmHandoff !== "function" || !isPlainObject(claims)) throw new IntegrationSdkError("invalid_handoff_confirmation", "A client and verified claims are required.");
+  if (!Number.isSafeInteger(maximumSessionLifetimeSeconds) || maximumSessionLifetimeSeconds < 1 || maximumSessionLifetimeSeconds > 24 * 60 * 60) throw new IntegrationSdkError("invalid_session_lifetime", "maximumSessionLifetimeSeconds must be from one through 86400.");
+  const confirmed = await client.confirmHandoff({ installationId: claims.installationId, token });
+  for (const field of ["userId", "siteId", "installationId", "integrationId", "credentialId", "role", "engagementId"]) {
+    if ((confirmed[field] || null) !== (claims[field] || null)) throw new IntegrationSdkError("handoff_confirmation_mismatch", "Taproot confirmation did not match the verified handoff.");
+  }
+  const expiresAt = Date.parse(confirmed.expiresAt);
+  const nowMilliseconds = epochMilliseconds(now);
+  if (!Number.isSafeInteger(expiresAt) || expiresAt <= nowMilliseconds || expiresAt > nowMilliseconds + maximumSessionLifetimeSeconds * 1_000) {
+    throw new IntegrationSdkError("invalid_handoff_confirmation", "Taproot returned an invalid settings session expiry.");
+  }
+  return Object.freeze({ ...claims, sessionExpiresAt: new Date(expiresAt).toISOString() });
+}
+
+/** Clears process-local public-key cache entries, primarily for controlled test or key-rollover recovery. */
+export function clearHandoffJwksCache(jwksUrl) {
+  if (jwksUrl === undefined) return cache.clear();
+  cache.delete(new URL(jwksUrl).toString());
+}

package/src/index.js

@@ -0,0 +1,16 @@
+export {
+  DEFAULT_RETRY_ATTEMPTS,
+  DEFAULT_TIMESTAMP_TOLERANCE_SECONDS,
+  HANDOFF_JWKS_PATH,
+  HANDOFF_LIFETIME_SECONDS,
+  INTEGRATION_CAPABILITIES,
+  INTEGRATION_SDK_VERSION,
+  WEBHOOK_EVENT_TYPES,
+  WEBHOOK_VERSION,
+} from "./constants.js";
+export { IntegrationApiError, IntegrationSdkError } from "./errors.js";
+export { INTEGRATION_OPENAPI_OPERATIONS, INTEGRATION_OPENAPI_SCHEMAS, INTEGRATION_WEBHOOK_EVENTS } from "./openapi-contract.js";
+export { assertValidManifest, validateFragment, validateManifest } from "./manifest.js";
+export { createIdempotencyKey, TaprootIntegrationClient } from "./client.js";
+export { clearHandoffJwksCache, confirmHandoff, verifyHandoff } from "./handoff.js";
+export { claimWebhookReceipt, finishWebhookReceipt, parseWebhookEvent, verifyWebhookSignature } from "./webhooks.js";

package/src/json.js

@@ -0,0 +1,56 @@
+export class DuplicateJsonKeyError extends Error {
+  constructor(path, key) {
+    super("JSON contains duplicate object keys.");
+    this.name = "DuplicateJsonKeyError";
+    this.path = path;
+    this.key = key;
+  }
+}
+
+function childPath(context) {
+  if (!context) return [];
+  return context.object ? [...context.path, context.key] : [...context.path, context.index];
+}
+
+/**
+ * Rejects duplicate keys in every object before returning parsed JSON. JavaScript's JSON parser
+ * keeps the last duplicate key, while the public Taproot contracts treat every object as closed.
+ */
+export function parseJsonWithoutDuplicateKeys(source) {
+  const value = JSON.parse(source);
+  const contexts = [];
+
+  for (let index = 0; index < source.length; index++) {
+    const character = source[index];
+    if (character === '"') {
+      const start = index;
+      let escaped = false;
+      for (++index; index < source.length; index++) {
+        if (!escaped && source[index] === '"') break;
+        escaped = !escaped && source[index] === "\\";
+        if (escaped && source[index] !== "\\") escaped = false;
+      }
+
+      const context = contexts.at(-1);
+      if (context?.object && context.expectingKey) {
+        const key = JSON.parse(source.slice(start, index + 1));
+        if (context.keys.has(key)) throw new DuplicateJsonKeyError(context.path, key);
+        context.keys.add(key);
+        context.key = key;
+        context.expectingKey = false;
+      }
+    } else if (character === "{") {
+      contexts.push({ object: true, expectingKey: true, key: undefined, keys: new Set(), path: childPath(contexts.at(-1)) });
+    } else if (character === "[") {
+      contexts.push({ object: false, index: 0, path: childPath(contexts.at(-1)) });
+    } else if (character === "}" || character === "]") {
+      contexts.pop();
+    } else if (character === ",") {
+      const context = contexts.at(-1);
+      if (context?.object) context.expectingKey = true;
+      else if (context) context.index++;
+    }
+  }
+
+  return value;
+}

package/src/manifest.js

@@ -0,0 +1,284 @@
+import { INTEGRATION_CAPABILITIES } from "./constants.js";
+import { IntegrationSdkError } from "./errors.js";
+import { asBytes, isPlainObject } from "./bytes.js";
+import { DuplicateJsonKeyError, parseJsonWithoutDuplicateKeys } from "./json.js";
+
+const ROOT_FIELDS = new Set([
+  "slug", "displayName", "webhookEndpointUrl", "settingsUrl", "requestedCapabilities",
+  "offeredComponents", "externalScriptOrigins", "defaultPublishPolicy", "recommendedUninstallDisposition",
+  "contractVersion", "pricingOptions", "description", "externalScriptOriginReasons",
+  "externalConnectOrigins", "externalConnectOriginReasons",
+]);
+const REQUIRED_ROOT_FIELDS = [
+  "slug", "displayName", "webhookEndpointUrl", "settingsUrl", "requestedCapabilities",
+  "offeredComponents", "externalScriptOrigins", "defaultPublishPolicy", "recommendedUninstallDisposition",
+  "contractVersion", "pricingOptions",
+];
+const IDENTIFIER = /^[A-Za-z0-9_.-]+$/;
+const VERSION = /^[A-Za-z0-9.-]+$/;
+const SLUG = /^[a-z][a-z0-9-]*$/;
+const MAX_MANIFEST_BYTES = 1024 * 1024;
+const MAX_SCHEMA_DEPTH = 12;
+const MAX_SCHEMA_NODES = 256;
+const MAX_SCHEMA_PROPERTIES = 32;
+const MAX_SCHEMA_ENUM_VALUES = 64;
+const MAX_QUANTITY = 100_000;
+const MAX_SCHEMA_BYTES = 64 * 1024;
+const TEXT_ENCODER = new TextEncoder();
+
+function failure(field, code) {
+  throw new IntegrationSdkError(code, `Manifest validation failed for ${field}.`, { details: { field, code } });
+}
+
+function object(value, field, allowed, required) {
+  if (!isPlainObject(value)) failure(field, "invalid_object");
+  for (const key of Object.keys(value)) if (!allowed.has(key)) failure(field, "unknown_property");
+  for (const key of required) if (!Object.hasOwn(value, key)) failure(field, "missing_property");
+}
+
+function text(value, field, maximum) {
+  if (typeof value !== "string" || value.trim().length === 0 || value.length > maximum || /[\u0000-\u001f\u007f]/.test(value)) {
+    failure(field, "invalid_value");
+  }
+  return value;
+}
+
+function array(value, field, maximum, itemMaximum) {
+  if (!Array.isArray(value) || value.length > maximum) failure(field, "invalid_value");
+  const seen = new Set();
+  for (const item of value) {
+    text(item, field, itemMaximum);
+    if (seen.has(item)) failure(field, "invalid_value");
+    seen.add(item);
+  }
+  return value;
+}
+
+function endpoint(value, field, originOnly = false) {
+  text(value, field, 2048);
+  let parsed;
+  try { parsed = new URL(value); } catch { failure(field, "invalid_url"); }
+  if (parsed.protocol !== "https:" || parsed.port || parsed.username || parsed.password || parsed.search || parsed.hash ||
+      !parsed.hostname || /^\d/.test(parsed.hostname) || parsed.hostname.includes(":")) {
+    failure(field, "invalid_url");
+  }
+  if (originOnly && parsed.pathname !== "/") failure(field, "invalid_origin");
+  return originOnly ? `https://${parsed.hostname.toLowerCase()}` : parsed.toString();
+}
+
+function positiveInteger(value, field, nullable = false) {
+  if (nullable && value === null) return null;
+  if (!Number.isSafeInteger(value) || value < 1 || value > MAX_QUANTITY) failure(field, "invalid_value");
+  return value;
+}
+
+function validateSchema(schema, field, depth, state) {
+  if (depth > MAX_SCHEMA_DEPTH || ++state.nodes > MAX_SCHEMA_NODES || !isPlainObject(schema)) failure(field, "invalid_schema");
+  const allowed = new Set(["type", "properties", "required", "items", "enum", "additionalProperties", "minLength", "maxLength", "minimum", "maximum"]);
+  object(schema, field, allowed, ["type"]);
+  if (!["object", "array", "string", "number", "integer", "boolean"].includes(schema.type)) failure(field, "invalid_schema");
+  let declared;
+  if (Object.hasOwn(schema, "properties")) {
+    if (schema.type !== "object" || !isPlainObject(schema.properties) || Object.keys(schema.properties).length > MAX_SCHEMA_PROPERTIES) failure(field, "invalid_schema");
+    declared = new Set();
+    for (const [name, child] of Object.entries(schema.properties)) {
+      text(name, field, 64);
+      if (declared.has(name)) failure(field, "invalid_schema");
+      declared.add(name);
+      validateSchema(child, field, depth + 1, state);
+    }
+  }
+  if (Object.hasOwn(schema, "required")) {
+    if (schema.type !== "object" || !declared || !Array.isArray(schema.required) || schema.required.length > MAX_SCHEMA_PROPERTIES) failure(field, "invalid_schema");
+    const required = new Set();
+    for (const name of schema.required) {
+      if (typeof name !== "string" || !declared.has(name) || required.has(name)) failure(field, "invalid_schema");
+      required.add(name);
+    }
+  }
+  if (schema.type === "array" && !Object.hasOwn(schema, "items")) failure(field, "invalid_schema");
+  if (Object.hasOwn(schema, "items")) {
+    if (schema.type !== "array") failure(field, "invalid_schema");
+    validateSchema(schema.items, field, depth + 1, state);
+  }
+  if (Object.hasOwn(schema, "enum")) {
+    if (!Array.isArray(schema.enum) || schema.enum.length === 0 || schema.enum.length > MAX_SCHEMA_ENUM_VALUES ||
+        schema.enum.some((item) => !["string", "number", "boolean"].includes(typeof item) ||
+          (typeof item === "string" && (item.length > 256 || /[\u0000-\u001f\u007f]/.test(item))) ||
+          (typeof item === "number" && !Number.isFinite(item)))) failure(field, "invalid_schema");
+  }
+  if (Object.hasOwn(schema, "additionalProperties") && (schema.type !== "object" || schema.additionalProperties !== false)) failure(field, "invalid_schema");
+  for (const key of ["minLength", "maxLength"]) {
+    if (Object.hasOwn(schema, key) && (schema.type !== "string" || !Number.isSafeInteger(schema[key]) || schema[key] < 0 || schema[key] > MAX_QUANTITY)) failure(field, "invalid_schema");
+  }
+  if (Object.hasOwn(schema, "minLength") && Object.hasOwn(schema, "maxLength") && schema.minLength > schema.maxLength) failure(field, "invalid_schema");
+  for (const key of ["minimum", "maximum"]) {
+    if (Object.hasOwn(schema, key) && (!["number", "integer"].includes(schema.type) || typeof schema[key] !== "number" || !Number.isFinite(schema[key]))) failure(field, "invalid_schema");
+  }
+  if (Object.hasOwn(schema, "minimum") && Object.hasOwn(schema, "maximum") && schema.minimum > schema.maximum) failure(field, "invalid_schema");
+}
+
+function origins(manifest, name) {
+  if (!Object.hasOwn(manifest, name)) return [];
+  if (!Array.isArray(manifest[name]) || manifest[name].length > 16) failure(name, "invalid_value");
+  const values = manifest[name].map((value) => endpoint(value, name, true));
+  if (new Set(values).size !== values.length) failure(name, "duplicate_value");
+  return values;
+}
+
+function originReasons(manifest, name, values) {
+  if (!Object.hasOwn(manifest, name)) return;
+  if (!isPlainObject(manifest[name]) || Object.keys(manifest[name]).length !== values.length) failure(name, "invalid_value");
+  for (const [origin, reason] of Object.entries(manifest[name])) {
+    if (!values.includes(origin)) failure(name, "invalid_value");
+    text(reason, name, 500);
+  }
+}
+
+function jsonByteLength(value, field, code) {
+  let serialized;
+  try { serialized = JSON.stringify(value); } catch { failure(field, code); }
+  if (typeof serialized !== "string") failure(field, code);
+  return TEXT_ENCODER.encode(serialized).length;
+}
+
+function serializedJsonBytes(value) {
+  try {
+    const serialized = JSON.stringify(value);
+    return typeof serialized === "string" ? TEXT_ENCODER.encode(serialized) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function duplicateKeyFailure(error) {
+  const path = error.path;
+  if (path.length === 0) failure("$", "unknown_property");
+
+  if (path[0] === "offeredComponents" && Number.isSafeInteger(path[1])) {
+    const field = `offeredComponents[${path[1]}]`;
+    if (path[2] === "configSchema" && path.at(-1) === "properties") failure(field, "invalid_schema");
+    failure(field, "unknown_property");
+  }
+
+  if (path[0] === "pricingOptions" && Number.isSafeInteger(path[1])) {
+    failure(`pricingOptions[${path[1]}]`, "unknown_property");
+  }
+
+  if (path.length === 1 && (path[0] === "externalScriptOriginReasons" || path[0] === "externalConnectOriginReasons")) {
+    failure(path[0], "invalid_value");
+  }
+
+  failure("$", "invalid_json");
+}
+
+function parseManifestJson(bytes) {
+  let source;
+  try { source = new TextDecoder("utf-8", { fatal: true }).decode(bytes); } catch { failure("$", "invalid_json"); }
+  try { return parseJsonWithoutDuplicateKeys(source); } catch (error) {
+    if (error instanceof DuplicateJsonKeyError) duplicateKeyFailure(error);
+    failure("$", "invalid_json");
+  }
+}
+
+function normalizeManifestInput(input) {
+  if (typeof input === "string" || input instanceof Uint8Array || input instanceof ArrayBuffer) {
+    const bytes = asBytes(input, "invalid_json");
+    if (bytes.length > MAX_MANIFEST_BYTES) failure("$", "size_exceeded");
+    return { value: parseManifestJson(bytes), serializationFailed: false };
+  }
+
+  let plainObject;
+  try { plainObject = isPlainObject(input); } catch { failure("$", "invalid_object"); }
+  if (!plainObject) return { value: input, serializationFailed: false };
+
+  const bytes = serializedJsonBytes(input);
+  if (bytes && bytes.length > MAX_MANIFEST_BYTES) failure("$", "size_exceeded");
+  return { value: input, serializationFailed: !bytes };
+}
+
+function validateManifestOrThrow(input) {
+  const normalized = normalizeManifestInput(input);
+  const value = normalized.value;
+  object(value, "$", ROOT_FIELDS, REQUIRED_ROOT_FIELDS);
+  if (!SLUG.test(text(value.slug, "slug", 64))) failure("slug", "invalid_value");
+  text(value.displayName, "displayName", 100);
+  endpoint(value.webhookEndpointUrl, "webhookEndpointUrl");
+  endpoint(value.settingsUrl, "settingsUrl");
+  const capabilities = array(value.requestedCapabilities, "requestedCapabilities", 32, 128);
+  if (capabilities.some((capability) => !INTEGRATION_CAPABILITIES.includes(capability))) failure("requestedCapabilities", "unavailable_capability");
+  if (!Array.isArray(value.offeredComponents) || value.offeredComponents.length > 32) failure("offeredComponents", "invalid_value");
+  const componentIds = new Set();
+  for (let index = 0; index < value.offeredComponents.length; index++) {
+    const component = value.offeredComponents[index];
+    const field = `offeredComponents[${index}]`;
+    object(component, field, new Set(["id", "name", "configSchema"]), ["id", "name", "configSchema"]);
+    if (!IDENTIFIER.test(text(component.id, field, 64)) || componentIds.has(component.id)) failure(field, "invalid_identifier");
+    componentIds.add(component.id);
+    text(component.name, field, 100);
+    if (jsonByteLength(component.configSchema, field, "invalid_schema") > MAX_SCHEMA_BYTES) failure(field, "invalid_schema");
+    validateSchema(component.configSchema, field, 0, { nodes: 0 });
+  }
+  const scriptOrigins = origins(value, "externalScriptOrigins");
+  const connectOrigins = origins(value, "externalConnectOrigins");
+  originReasons(value, "externalScriptOriginReasons", scriptOrigins);
+  originReasons(value, "externalConnectOriginReasons", connectOrigins);
+  if (!["auto", "stage"].includes(value.defaultPublishPolicy)) failure("defaultPublishPolicy", "invalid_value");
+  if (!["freeze", "remove"].includes(value.recommendedUninstallDisposition)) failure("recommendedUninstallDisposition", "invalid_value");
+  if (!VERSION.test(text(value.contractVersion, "contractVersion", 64))) failure("contractVersion", "invalid_value");
+  if (!Array.isArray(value.pricingOptions) || value.pricingOptions.length > 16) failure("pricingOptions", "invalid_value");
+  const optionIds = new Set();
+  value.pricingOptions.forEach((option, index) => {
+    const field = `pricingOptions[${index}]`;
+    object(option, field, new Set(["id", "version", "quantityMin", "quantityMax", "cadence", "catalogueItemKey"]),
+      ["id", "version", "quantityMin", "quantityMax", "cadence", "catalogueItemKey"]);
+    if (!IDENTIFIER.test(text(option.id, field, 64)) || optionIds.has(option.id) || !VERSION.test(text(option.version, field, 64))) failure(field, "invalid_value");
+    optionIds.add(option.id);
+    const minimum = positiveInteger(option.quantityMin, field);
+    const maximum = positiveInteger(option.quantityMax, field, true);
+    if (maximum !== null && maximum < minimum) failure(field, "invalid_value");
+    if (option.cadence === "free" ? option.catalogueItemKey !== null :
+      (!["monthly", "annual"].includes(option.cadence) || !IDENTIFIER.test(text(option.catalogueItemKey, field, 128)))) failure(field, "invalid_value");
+  });
+  if (Object.hasOwn(value, "description")) text(value.description, "description", 2000);
+  if (normalized.serializationFailed) failure("$", "invalid_json");
+  return value;
+}
+
+/**
+ * Checks the bounded public manifest grammar before registration. DNS resolution, public-route
+ * validation, and all authorization decisions remain server-authoritative.
+ */
+export function validateManifest(input) {
+  try { return { ok: true, value: validateManifestOrThrow(input) }; }
+  catch (error) {
+    if (error instanceof IntegrationSdkError) {
+      return { ok: false, errors: [{ field: error.details?.field ?? "$", code: error.code }] };
+    }
+    throw error;
+  }
+}
+
+export function assertValidManifest(input) {
+  const result = validateManifest(input);
+  if (!result.ok) {
+    const first = result.errors[0];
+    throw new IntegrationSdkError(first.code, `Manifest validation failed for ${first.field}.`, { details: first });
+  }
+  return result.value;
+}
+
+/**
+ * Advisory preflight only. It catches a few common server rejections but intentionally does not
+ * implement a second HTML sanitizer. Taproot validates the final fragment on every write.
+ */
+export function validateFragment(html) {
+  const errors = [];
+  if (typeof html !== "string" || html.length === 0) errors.push({ code: "invalid_html", message: "A non-empty HTML fragment is required." });
+  if (typeof html === "string" && new TextEncoder().encode(html).length > 64 * 1024) errors.push({ code: "size_exceeded", message: "Fragment exceeds the public preflight size limit." });
+  if (typeof html === "string" && /<\/?(?:script|iframe|object|embed|form|input|svg|math)\b/i.test(html)) errors.push({ code: "element_not_allowed", message: "The fragment contains an element the server normally rejects." });
+  if (typeof html === "string" && /\son[a-z]+\s*=/i.test(html)) errors.push({ code: "attribute_not_allowed", message: "Event-handler attributes are not accepted." });
+  if (typeof html === "string" && /(?:href|src)\s*=\s*['"]?\s*(?:javascript:|data:|\/\\|\\\\)/i.test(html)) errors.push({ code: "invalid_url", message: "The fragment contains an unsafe URL form." });
+  if (typeof html === "string" && /<(?!template\b[^>]*\bshadowrootmode\s*=)[^>]*\bstyle\b/i.test(html)) errors.push({ code: "element_not_allowed", message: "Styles are only supported inside an allowed declarative shadow root." });
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}