@twin3-ai/agent-id 0.1.0

package/browser-sdk.js

@@ -0,0 +1,149 @@
+(function () {
+  "use strict";
+  var w = window;
+  var d = document;
+  var script = d.currentScript || {};
+  var previous = w.twin3AEO || {};
+  var endpoint = previous.endpoint || (script.getAttribute && script.getAttribute("data-endpoint")) || "/api/agent/sdk_event";
+  var agentId = previous.agentId || (script.getAttribute && script.getAttribute("data-agent-id")) || "";
+  var defaultEvent = previous.event || "page_view";
+  var aiReferrer = /(chatgpt|openai|perplexity|gemini|bard|claude|anthropic|copilot|bing|you\.com|poe\.com)/i;
+
+  function clip(value, limit) {
+    value = value == null ? "" : String(value);
+    return value.length > limit ? value.slice(0, limit) : value;
+  }
+
+  function attr(element, name) {
+    return element && element.getAttribute ? (element.getAttribute(name) || "") : "";
+  }
+
+  function text(element) {
+    return clip((element && element.textContent || "").replace(/\s+/g, " ").trim(), 160);
+  }
+
+  function meta(name) {
+    var element = d.querySelector('meta[name="' + name + '"],meta[property="' + name + '"]');
+    return attr(element, "content");
+  }
+
+  function hasAccessibleName(element) {
+    if (!element) return false;
+    return !!(attr(element, "aria-label") || attr(element, "title") || attr(element, "alt") || attr(element, "placeholder") || attr(element, "name") || text(element));
+  }
+
+  function cleanData(value, depth) {
+    if (!value || typeof value !== "object" || depth > 2) return value;
+    var output = Array.isArray(value) ? [] : {};
+    Object.keys(value).slice(0, 40).forEach(function (key) {
+      var low = key.toLowerCase();
+      if (/email|phone|tel|name|note|message|token|key|secret|password/.test(low)) {
+        output[key] = "[redacted]";
+        return;
+      }
+      var item = value[key];
+      if (typeof item === "string") output[key] = clip(item, 160);
+      else if (typeof item === "number" || typeof item === "boolean") output[key] = item;
+      else if (item && typeof item === "object") output[key] = cleanData(item, depth + 1);
+    });
+    return output;
+  }
+
+  function collectSignals() {
+    var forms = Array.prototype.slice.call(d.querySelectorAll("form"));
+    var webmcpForms = forms.filter(function (form) { return attr(form, "toolname") && attr(form, "tooldescription"); });
+    var badToolInputs = 0;
+    webmcpForms.forEach(function (form) {
+      Array.prototype.slice.call(form.querySelectorAll("input,select,textarea")).forEach(function (element) {
+        if ((attr(element, "type") || "").toLowerCase() === "hidden") return;
+        if (!attr(element, "name")) badToolInputs += 1;
+      });
+    });
+    var interactive = Array.prototype.slice.call(d.querySelectorAll("a,button,input,select,textarea"));
+    var namedInteractive = interactive.filter(function (element) {
+      if (element.tagName === "INPUT" && (attr(element, "type") || "").toLowerCase() === "hidden") return true;
+      return hasAccessibleName(element);
+    });
+    var images = Array.prototype.slice.call(d.querySelectorAll("img"));
+    var missingImageSize = images.filter(function (image) { return !(attr(image, "width") && attr(image, "height")); });
+    var referrer = d.referrer || "";
+    var referrerHost = "";
+    try { referrerHost = referrer ? (new URL(referrer)).hostname : ""; } catch (_) { referrerHost = ""; }
+    return {
+      title_len: (d.title || "").length,
+      description_len: meta("description").length,
+      canonical: !!d.querySelector('link[rel~="canonical"]'),
+      viewport: !!meta("viewport"),
+      lang: clip(d.documentElement && d.documentElement.lang || "", 24),
+      h1_count: d.querySelectorAll("h1").length,
+      jsonld_count: d.querySelectorAll('script[type="application/ld+json"]').length,
+      links: d.querySelectorAll("a[href]").length,
+      forms: forms.length,
+      webmcp_forms: webmcpForms.length,
+      webmcp_bad_inputs: badToolInputs,
+      interactive: interactive.length,
+      named_interactive: namedInteractive.length,
+      images: images.length,
+      images_missing_size: missingImageSize.length,
+      referrer_host: clip(referrerHost, 80),
+      ai_referrer: aiReferrer.test(referrer)
+    };
+  }
+
+  function payload(event, data) {
+    var output = {
+      sdk: "agent-id-browser-sdk",
+      sdk_version: "0.3.0",
+      event: event || defaultEvent,
+      agent_id: agentId,
+      url: location.href,
+      path: location.pathname
+    };
+    if (data) output.data = cleanData(data, 0);
+    return JSON.stringify(output);
+  }
+
+  function post(body) {
+    if (navigator.sendBeacon) {
+      var accepted = navigator.sendBeacon(endpoint, new Blob([body], { type: "application/json" }));
+      if (accepted) return;
+    }
+    fetch(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: body,
+      keepalive: true,
+      credentials: "omit"
+    }).catch(function () {});
+  }
+
+  function track(event, data) {
+    post(payload(event, data));
+  }
+
+  function signal(extra) {
+    track("page_signal", { signals: collectSignals(), extra: extra || {} });
+  }
+
+  function conversion(name, data) {
+    track("conversion", { conversion: clip(name || "conversion", 80), value: cleanData(data || {}, 0) });
+  }
+
+  w.twin3AEO = {
+    agentId: agentId,
+    endpoint: endpoint,
+    version: "0.3.0",
+    track: track,
+    signal: signal,
+    conversion: conversion,
+    collectSignals: collectSignals
+  };
+
+  function boot() {
+    track("page_view");
+    setTimeout(function () { signal(); }, 700);
+  }
+
+  if (d.readyState === "loading") d.addEventListener("DOMContentLoaded", boot, { once: true });
+  else boot();
+})();

package/cloudflare-worker-adapter.js

@@ -0,0 +1,100 @@
+"use strict";
+
+const { deploymentChanges } = require("./repository-connector.js");
+const { ALLOWED_PATHS } = require("./repository-connector.js");
+
+function normalizeVerifiedRoute(value) {
+  const route = "/" + String(value || "").replace(/^\/+/, "");
+  const relative = route.slice(1);
+  if (!ALLOWED_PATHS.has(relative) || relative.includes("..")) throw new Error("cloudflare_route_not_verified");
+  return route;
+}
+
+function buildWorkerAssetManifest({ implementationBundle, knowledgePack } = {}) {
+  const changes = deploymentChanges({ implementationBundle, knowledgePack });
+  const assets = {};
+  for (const change of changes) {
+    const route = "/" + change.path;
+    assets[route] = {
+      content_type: change.content_type || "text/plain; charset=utf-8",
+      content: change.content
+    };
+  }
+  return {
+    schema: "agentx-cloudflare-worker-assets-v1",
+    status: "ready_for_external_deployment",
+    deployment_claim: "not_deployed",
+    routes: Object.keys(assets).sort(),
+    assets,
+    security: {
+      credentials_in_manifest: false,
+      exact_path_get_or_head_only: true,
+      owner_deployment_required: true
+    },
+    non_claims: [
+      "adapter_does_not_call_cloudflare_api",
+      "manifest_is_not_deployment_receipt",
+      "owner_must_deploy_and_verify_routes"
+    ]
+  };
+}
+
+function buildWorkerModule(manifest) {
+  if (!manifest || manifest.schema !== "agentx-cloudflare-worker-assets-v1") {
+    throw new Error("Invalid Worker asset manifest.");
+  }
+  const assets = JSON.stringify(manifest.assets).replace(/</g, "\\u003c");
+  return `const ASSETS = ${assets};
+export default {
+  async fetch(request) {
+    const method = String(request && request.method || "GET").toUpperCase();
+    if (!['GET', 'HEAD'].includes(method)) {
+      return new Response("Method Not Allowed", { status: 405, headers: { Allow: "GET, HEAD" } });
+    }
+    const pathname = new URL(request.url).pathname;
+    const asset = ASSETS[pathname];
+    if (!asset) return new Response("Not Found", { status: 404 });
+    return new Response(method === "HEAD" ? null : asset.content, {
+      status: 200,
+      headers: {
+        "Content-Type": asset.content_type,
+        "Cache-Control": "public, max-age=300",
+        "X-Content-Type-Options": "nosniff"
+      }
+    });
+  }
+};
+`;
+}
+
+function createCloudflareWorkerConnector({ verifiedRoutes = [], deployVerifiedRoutes, verifyDeployment, rollbackDeployment } = {}) {
+  const allowed = new Set(verifiedRoutes.map(normalizeVerifiedRoute));
+  return Object.freeze({
+    describeCapabilities() {
+      return { connector: "cloudflare_worker", operations: ["upsert", "replace"], verified_routes: [...allowed].sort(), owner_callback_required: true };
+    },
+    async readResource(resource) {
+      const route = normalizeVerifiedRoute(resource && resource.path);
+      if (!allowed.has(route)) throw new Error("cloudflare_route_not_verified");
+      return { connector: "cloudflare_worker", environment: String(resource.environment || "production"), resource_type: "route", resource_id: String(resource.resource_id || route), path: route, sha256: String(resource.sha256 || "") };
+    },
+    async planOperations(task) {
+      if (!task.operations.every((operation) => allowed.has(normalizeVerifiedRoute(operation.path)))) throw new Error("cloudflare_route_not_verified");
+      return { schema: "agentx-cloudflare-owner-plan-v1", approval_required: true, operations: task.operations.map((operation) => ({ operation: operation.operation, route: normalizeVerifiedRoute(operation.path), content: operation.value })) };
+    },
+    async applyOperations(plan) {
+      if (typeof deployVerifiedRoutes !== "function") throw new Error("cloudflare_owner_deployment_required");
+      return deployVerifiedRoutes(plan);
+    },
+    async verifyLocalResult(receipt) {
+      if (typeof verifyDeployment !== "function") throw new Error("cloudflare_owner_verification_required");
+      return verifyDeployment(receipt);
+    },
+    async rollback(receipt) {
+      if (typeof rollbackDeployment !== "function") throw new Error("cloudflare_owner_rollback_required");
+      return rollbackDeployment(receipt);
+    }
+  });
+}
+
+module.exports = { buildWorkerAssetManifest, buildWorkerModule, createCloudflareWorkerConnector };

package/domain-proof.js

@@ -0,0 +1,208 @@
+"use strict";
+
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const PROOF_SCHEMA = "agentx-domain-proof-v1";
+const CHALLENGE_SCHEMA = "agentx-domain-challenge-v1";
+const SITE_VERIFICATION_SCHEMA = "agentx-site-agent-verification-v1";
+const PROOF_RELATIVE_PATH = path.join(".well-known", "agent-id.json");
+
+function proofError(code, message) {
+  const error = new Error(`${code}: ${message}`);
+  error.code = code;
+  return error;
+}
+
+function requiredString(value, field) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw proofError("invalid_domain_challenge", `${field} is required`);
+  }
+  return value.trim();
+}
+
+function exactHostname(value) {
+  const host = requiredString(value, "host").toLowerCase();
+  if (host.length > 253 || !/^[a-z0-9.-]+$/.test(host)) {
+    throw proofError("invalid_domain_challenge", "host must be an ASCII hostname");
+  }
+  const labels = host.split(".");
+  if (labels.some(label => !label || label.length > 63 || !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(label))) {
+    throw proofError("invalid_domain_challenge", "host contains an invalid DNS label");
+  }
+  return host;
+}
+
+function buildWellKnownProofDocument(challenge, { now = null } = {}) {
+  const isChallenge = challenge && challenge.schema === CHALLENGE_SCHEMA && challenge.method === "well_known";
+  const isProof = challenge && challenge.schema === PROOF_SCHEMA;
+  if (!isChallenge && !isProof) {
+    throw proofError("invalid_domain_challenge", "a well_known challenge is required");
+  }
+  const host = exactHostname(challenge.host);
+  const expiresAt = Number(challenge.expires_at);
+  if (!Number.isInteger(expiresAt) || expiresAt <= 0) {
+    throw proofError("invalid_domain_challenge", "expires_at must be an integer timestamp");
+  }
+  if (now !== null && expiresAt <= Number(now)) {
+    throw proofError("domain_challenge_expired", "request a new challenge before publishing proof");
+  }
+  return {
+    schema: PROOF_SCHEMA,
+    challenge_id: requiredString(challenge.challenge_id, "challenge_id"),
+    proof: requiredString(challenge.proof, "proof"),
+    agent_id: requiredString(challenge.agent_id, "agent_id"),
+    tenant_id: requiredString(challenge.tenant_id, "tenant_id"),
+    host,
+    environment: requiredString(challenge.environment, "environment"),
+    public_key_thumbprint: requiredString(challenge.public_key_thumbprint, "public_key_thumbprint"),
+    expires_at: expiresAt,
+  };
+}
+
+function buildSiteAgentVerificationDocument(registration) {
+  if (!registration || registration.ok !== true || !registration.verification) {
+    throw proofError("invalid_site_registration", "a successful Site Agent registration is required");
+  }
+  const host = exactHostname(registration.host);
+  const verificationToken = requiredString(registration.verification.token, "verification.token");
+  if (!verificationToken.startsWith("av_")) {
+    throw proofError("invalid_site_registration", "verification.token must be an Agent ID verification token");
+  }
+  return {
+    schema: SITE_VERIFICATION_SCHEMA,
+    agent_id: requiredString(registration.agent_id, "agent_id"),
+    host,
+    verification_token: verificationToken,
+  };
+}
+
+function resolveProofTarget({ projectRoot, publicRoot }) {
+  const project = path.resolve(String(projectRoot || publicRoot || ""));
+  const root = path.resolve(String(publicRoot || projectRoot || ""));
+  if (root !== project && !root.startsWith(project + path.sep)) {
+    throw proofError("unsafe_public_root", "publicRoot must be inside the customer project");
+  }
+  return { project, root, directory: path.join(root, ".well-known"), target: path.join(root, PROOF_RELATIVE_PATH) };
+}
+
+async function readExisting(target) {
+  try {
+    const stat = await fs.lstat(target);
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+      throw proofError("unsafe_proof_target", "proof target must be a regular file");
+    }
+    return await fs.readFile(target, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function writeWellKnownProofDocument({ challenge, projectRoot, publicRoot, approved = false, now }) {
+  if (approved !== true) {
+    throw proofError("approval_required", "writing a public domain proof requires explicit approval");
+  }
+  const document = buildWellKnownProofDocument(challenge, {
+    now: now === undefined ? Math.floor(Date.now() / 1000) : now,
+  });
+  const { project, root, directory, target } = resolveProofTarget({ projectRoot, publicRoot });
+  let realProject;
+  let realRoot;
+  try {
+    [realProject, realRoot] = await Promise.all([fs.realpath(project), fs.realpath(root)]);
+  } catch (error) {
+    throw proofError("invalid_public_root", "projectRoot and publicRoot must already exist");
+  }
+  if (realRoot !== realProject && !realRoot.startsWith(realProject + path.sep)) {
+    throw proofError("unsafe_public_root", "publicRoot cannot escape the customer project through a symlink");
+  }
+  await fs.mkdir(directory, { recursive: true, mode: 0o755 });
+  const directoryStat = await fs.lstat(directory);
+  if (directoryStat.isSymbolicLink() || !directoryStat.isDirectory()) {
+    throw proofError("unsafe_proof_target", ".well-known must be a real directory");
+  }
+  const existing = await readExisting(target);
+  if (existing !== null) {
+    let parsed;
+    try { parsed = JSON.parse(existing); } catch (_error) { parsed = null; }
+    if (!parsed || parsed.schema !== PROOF_SCHEMA || parsed.host !== document.host || parsed.agent_id !== document.agent_id) {
+      throw proofError("unmanaged_proof_conflict", "refusing to overwrite a customer-managed file");
+    }
+  }
+  const serialized = `${JSON.stringify(document, null, 2)}\n`;
+  const temporary = `${target}.tmp-${process.pid}-${crypto.randomBytes(6).toString("hex")}`;
+  try {
+    await fs.writeFile(temporary, serialized, { mode: 0o644, flag: "wx" });
+    await fs.rename(temporary, target);
+  } finally {
+    await fs.rm(temporary, { force: true }).catch(() => {});
+  }
+  return {
+    schema: "agentx-domain-proof-write-receipt-v1",
+    changed: existing !== serialized,
+    path: target,
+    relative_path: "/.well-known/agent-id.json",
+    sha256: `sha256:${crypto.createHash("sha256").update(serialized).digest("hex")}`,
+    document,
+  };
+}
+
+async function writeSiteAgentVerificationDocument({ registration, projectRoot, publicRoot, approved = false }) {
+  if (approved !== true) {
+    throw proofError("approval_required", "writing a public domain verification document requires explicit approval");
+  }
+  const document = buildSiteAgentVerificationDocument(registration);
+  const { project, root, directory, target } = resolveProofTarget({ projectRoot, publicRoot });
+  let realProject;
+  let realRoot;
+  try {
+    [realProject, realRoot] = await Promise.all([fs.realpath(project), fs.realpath(root)]);
+  } catch (_error) {
+    throw proofError("invalid_public_root", "projectRoot and publicRoot must already exist");
+  }
+  if (realRoot !== realProject && !realRoot.startsWith(realProject + path.sep)) {
+    throw proofError("unsafe_public_root", "publicRoot cannot escape the customer project through a symlink");
+  }
+  await fs.mkdir(directory, { recursive: true, mode: 0o755 });
+  const directoryStat = await fs.lstat(directory);
+  if (directoryStat.isSymbolicLink() || !directoryStat.isDirectory()) {
+    throw proofError("unsafe_proof_target", ".well-known must be a real directory");
+  }
+  const existing = await readExisting(target);
+  if (existing !== null) {
+    let parsed;
+    try { parsed = JSON.parse(existing); } catch (_error) { parsed = null; }
+    if (!parsed || parsed.schema !== SITE_VERIFICATION_SCHEMA || parsed.host !== document.host || parsed.agent_id !== document.agent_id) {
+      throw proofError("unmanaged_proof_conflict", "refusing to overwrite a customer-managed file");
+    }
+  }
+  const serialized = `${JSON.stringify(document, null, 2)}\n`;
+  const temporary = `${target}.tmp-${process.pid}-${crypto.randomBytes(6).toString("hex")}`;
+  try {
+    await fs.writeFile(temporary, serialized, { mode: 0o644, flag: "wx" });
+    await fs.rename(temporary, target);
+  } finally {
+    await fs.rm(temporary, { force: true }).catch(() => {});
+  }
+  return {
+    schema: "agentx-site-agent-verification-write-receipt-v1",
+    changed: existing !== serialized,
+    path: target,
+    relative_path: "/.well-known/agent-id.json",
+    sha256: `sha256:${crypto.createHash("sha256").update(serialized).digest("hex")}`,
+    document,
+  };
+}
+
+module.exports = {
+  PROOF_SCHEMA,
+  SITE_VERIFICATION_SCHEMA,
+  PROOF_RELATIVE_PATH,
+  buildWellKnownProofDocument,
+  buildSiteAgentVerificationDocument,
+  resolveProofTarget,
+  writeWellKnownProofDocument,
+  writeSiteAgentVerificationDocument,
+};

package/enterprise-identity.js

@@ -0,0 +1,202 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+function enterpriseError(code) {
+  const error = new Error(code);
+  error.code = code;
+  return error;
+}
+
+function normalizeOrigin(value) {
+  let parsed;
+  try { parsed = new URL(String(value || "")); } catch (_error) { throw enterpriseError("invalid_service_origin"); }
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash) {
+    throw enterpriseError("invalid_service_origin");
+  }
+  return parsed.origin;
+}
+
+function normalizeSite(value) {
+  let parsed;
+  try { parsed = new URL(String(value || "")); } catch (_error) { throw enterpriseError("invalid_site_url"); }
+  if (parsed.protocol !== 'https:' || parsed.username || parsed.password || !parsed.hostname || (parsed.port && parsed.port !== "443")) throw enterpriseError("invalid_site_url");
+  return { url: parsed.toString(), host: parsed.hostname.toLowerCase() };
+}
+
+function atomicPrivateWrite(keyPath, privatePem) {
+  const target = path.resolve(String(keyPath || ""));
+  if (!keyPath) throw enterpriseError("key_path_required");
+  const directory = path.dirname(target);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  if (fs.lstatSync(directory).isSymbolicLink()) throw enterpriseError("private_key_directory_invalid");
+  fs.chmodSync(directory, 0o700);
+  const temporary = `${target}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, privatePem, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    fs.renameSync(temporary, target);
+    fs.chmodSync(target, 0o600);
+  } finally {
+    try { fs.rmSync(temporary, { force: true }); } catch (_error) {}
+  }
+  return target;
+}
+
+function generateSiteAgentIdentity({ keyPath } = {}) {
+  const target = path.resolve(String(keyPath || ""));
+  if (!keyPath) throw enterpriseError("key_path_required");
+  let publicKey;
+  if (fs.existsSync(target)) {
+    const mode = fs.statSync(target).mode & 0o777;
+    if (mode !== 0o600) throw enterpriseError("private_key_permissions_invalid");
+    publicKey = crypto.createPublicKey(crypto.createPrivateKey(fs.readFileSync(target, "utf8")));
+  } else {
+    const pair = crypto.generateKeyPairSync("ed25519");
+    atomicPrivateWrite(target, pair.privateKey.export({ type: "pkcs8", format: "pem" }));
+    publicKey = pair.publicKey;
+  }
+  const publicPem = publicKey.export({ type: "spki", format: "pem" });
+  const publicDer = publicKey.export({ type: "spki", format: "der" });
+  return {
+    schema: "agentx-customer-identity-v1",
+    algorithm: "Ed25519",
+    public_key_pem: publicPem,
+    public_key_thumbprint: `sha256:${crypto.createHash("sha256").update(publicDer).digest("base64url")}`,
+    private_key_persisted_locally: true,
+    key_path: target
+  };
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]));
+}
+
+function signaturePayload(challenge) {
+  const fields = ["challenge_id", "nonce", "credential_id", "requested_scopes", "tenant_id", "host", "environment", "agent_id", "issued_at", "expires_at"];
+  const payload = Object.fromEntries(fields.map((field) => [field, challenge[field]]));
+  return Buffer.from(JSON.stringify(stableValue(payload)), "utf8");
+}
+
+function signChallenge(identity, challenge, { now = Math.floor(Date.now() / 1000) } = {}) {
+  if (!identity || !identity.key_path || !identity.subject || !challenge || challenge.schema !== "agentx-token-exchange-challenge-v1") throw enterpriseError("challenge_binding_mismatch");
+  const subject = identity.subject;
+  const exactFields = ["tenant_id", "host", "environment", "agent_id", "credential_id"];
+  if (exactFields.some((field) => challenge[field] !== subject[field])) throw enterpriseError("challenge_binding_mismatch");
+  const challengeScopes = [...new Set(challenge.requested_scopes || [])].sort();
+  const subjectScopes = [...new Set(subject.requested_scopes || [])].sort();
+  if (JSON.stringify(challengeScopes) !== JSON.stringify(subjectScopes) || normalizeOrigin(challenge.service_origin) !== normalizeOrigin(identity.service_origin)) {
+    throw enterpriseError("challenge_binding_mismatch");
+  }
+  if (!Number.isFinite(challenge.issued_at) || !Number.isFinite(challenge.expires_at) || now < challenge.issued_at || now >= challenge.expires_at) {
+    throw enterpriseError("challenge_time_invalid");
+  }
+  const privateKey = crypto.createPrivateKey(fs.readFileSync(identity.key_path, "utf8"));
+  return {
+    challenge_id: challenge.challenge_id,
+    signature: crypto.sign(null, signaturePayload(challenge), privateKey).toString("base64url")
+  };
+}
+
+async function responseJson(response) {
+  const payload = await response.json();
+  if (!response.ok) throw enterpriseError(payload && payload.error ? payload.error : `enterprise_http_${response.status}`);
+  return payload;
+}
+
+function createEnterpriseSession({ serviceOrigin, siteUrl, environment, credential, identity, fetch: fetcher = globalThis.fetch, now = () => Math.floor(Date.now() / 1000) } = {}) {
+  const origin = normalizeOrigin(serviceOrigin);
+  const site = normalizeSite(siteUrl);
+  if (!credential || !identity || typeof fetcher !== "function") throw enterpriseError("enterprise_session_invalid");
+  const subject = {
+    tenant_id: credential.tenant_id,
+    host: credential.host,
+    environment,
+    agent_id: credential.agent_id,
+    credential_id: credential.credential_id,
+    requested_scopes: []
+  };
+  if (site.host !== subject.host || credential.environment && credential.environment !== environment) throw enterpriseError("enterprise_session_subject_mismatch");
+  let cachedToken = "";
+  let cachedExpiry = 0;
+  let cachedScopes = [];
+
+  async function lifecycleRequest(operation, body = {}) {
+    const scope = `credentials:${operation}`;
+    const accessToken = await session.getAccessToken([scope]);
+    return responseJson(await fetcher(`${origin}/api/site_agents/v1/credentials/${operation}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${accessToken}` },
+      body: JSON.stringify(body)
+    }));
+  }
+
+  async function managedRequest(pathname, { method = "GET", body = null } = {}) {
+    const scope = method === "GET" ? "insights:read" : "managed:write";
+    const accessToken = await session.getAccessToken([scope]);
+    const request = {
+      method,
+      headers: { "content-type": "application/json", authorization: `Bearer ${accessToken}` }
+    };
+    if (body !== null) request.body = JSON.stringify(body);
+    return responseJson(await fetcher(`${origin}/api/site_agents/v1/managed/${pathname}`, request));
+  }
+
+  const session = {
+    schema: "agentx-enterprise-session-v1",
+    site_url: site.url,
+    environment,
+    async getAccessToken(scopes = ["tasks:read"]) {
+      if (!Array.isArray(scopes) || !scopes.length || scopes.some((scope) => typeof scope !== "string" || !scope)) throw enterpriseError("invalid_scope_set");
+      const requested = [...new Set(scopes)].sort();
+      if (cachedToken && now() + 60 < cachedExpiry && requested.every((scope) => cachedScopes.includes(scope))) return cachedToken;
+      const challengePayload = await responseJson(await fetcher(`${origin}/api/site_agents/v1/token/challenge`, {
+        method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ credential_id: credential.credential_id, scopes: requested })
+      }));
+      const challenge = { ...challengePayload.challenge, service_origin: origin };
+      const signed = signChallenge({ ...identity, subject: { ...subject, requested_scopes: requested }, service_origin: origin }, challenge, { now: now() });
+      const tokenPayload = await responseJson(await fetcher(`${origin}/api/site_agents/v1/token`, {
+        method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ credential_id: credential.credential_id, challenge_id: signed.challenge_id, signature: signed.signature, bootstrap_secret: credential.bootstrap_secret, scopes: requested })
+      }));
+      cachedToken = tokenPayload.access_token;
+      cachedExpiry = Number(tokenPayload.claims && tokenPayload.claims.exp || 0);
+      cachedScopes = requested;
+      return cachedToken;
+    },
+    async rotateCredential() {
+      return lifecycleRequest("rotate");
+    },
+    async revokeCredential(reason) {
+      const normalizedReason = String(reason || "").trim();
+      if (!normalizedReason) throw enterpriseError("revocation_reason_required");
+      return lifecycleRequest("revoke", { reason: normalizedReason });
+    },
+    async enableManagedInspection() {
+      return managedRequest("subscription", { method: "POST", body: { cadence: "monthly" } });
+    },
+    async getManagedInspection() {
+      return managedRequest("subscription");
+    },
+    async pauseManagedInspection(expectedVersion) {
+      const version = Number(expectedVersion);
+      if (!Number.isInteger(version) || version < 1) throw enterpriseError("managed_subscription_version_required");
+      return managedRequest("subscription/pause", { method: "POST", body: { expected_version: version } });
+    },
+    async resumeManagedInspection(expectedVersion) {
+      const version = Number(expectedVersion);
+      if (!Number.isInteger(version) || version < 1) throw enterpriseError("managed_subscription_version_required");
+      return managedRequest("subscription/resume", { method: "POST", body: { expected_version: version } });
+    },
+    async listManagedRuns(limit = 20) {
+      const bounded = Math.max(1, Math.min(Number(limit) || 20, 100));
+      return managedRequest(`runs?limit=${encodeURIComponent(Math.trunc(bounded))}`);
+    },
+    clear() { cachedToken = ""; cachedExpiry = 0; cachedScopes = []; }
+  };
+  return Object.freeze(session);
+}
+
+module.exports = { generateSiteAgentIdentity, signChallenge, createEnterpriseSession };