@twin3-ai/agent-id 0.2.0 → 0.3.0

package/cloudflare-a1-sync.js

@@ -0,0 +1,105 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const ENDPOINT = "https://api.cloudflare.com/client/v4/graphql";
+const DEFAULT_USER_AGENTS = Object.freeze(["GPTBot", "ChatGPT-User", "OAI-SearchBot", "ClaudeBot", "Claude-User", "Google-Extended", "Googlebot", "PerplexityBot", "Amazonbot", "Bytespider"]);
+
+function emptyState() {
+  return { schema: "agentx-cloudflare-a1-sync-state-v1", cursor_end: "", pending: null, retry_at: 0, attempts: 0, next_run_at: 0, last_sync_at: 0, last_error: null };
+}
+function loadState(statePath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    return { ...emptyState(), ...parsed };
+  } catch (error) {
+    if (error.code === "ENOENT") return emptyState();
+    throw new Error("cloudflare_a1_state_invalid");
+  }
+}
+function saveState(statePath, state) {
+  const target = path.resolve(statePath);
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  const temporary = `${target}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, JSON.stringify(state, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+    fs.renameSync(temporary, target);
+    fs.chmodSync(target, 0o600);
+  } finally { try { fs.rmSync(temporary, { force: true }); } catch (_error) {} }
+}
+function cleanPath(value) {
+  const raw = String(value || "/");
+  try { return (new URL(raw, "https://redacted.invalid").pathname || "/").slice(0, 240); }
+  catch (_error) { return (raw.split(/[?#]/, 1)[0] || "/").slice(0, 240); }
+}
+function userAgentProduct(value) {
+  const match = String(value || "").trim().match(/^([A-Za-z][A-Za-z0-9_-]{0,63})(?:\/[^\s]+)?/);
+  return match ? match[1] : "";
+}
+function buildQuery(zoneId, start, end, userAgents) {
+  const filters = userAgents.map((item) => `{userAgent_like:${JSON.stringify(`%${item}%`)}}`).join(" ");
+  return `query AgentIdA1 { viewer { zones(filter:{zoneTag:${JSON.stringify(zoneId)}}) { a1:httpRequestsAdaptiveGroups(filter:{datetime_geq:${JSON.stringify(start)} datetime_leq:${JSON.stringify(end)} requestSource:"eyeball" OR:[${filters}]} limit:5000 orderBy:[count_DESC]) { count dimensions { userAgent clientRequestPath edgeResponseStatus } sum { edgeResponseBytes } } } } }`;
+}
+async function defaultFetchCloudflare({ token, query, fetchImpl = globalThis.fetch }) {
+  if (typeof fetchImpl !== "function") throw new Error("cloudflare_a1_fetch_unavailable");
+  const response = await fetchImpl(ENDPOINT, { method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body: JSON.stringify({ query }), redirect: "error" });
+  if (!response.ok) throw new Error(`cloudflare_a1_http_${response.status}`);
+  const body = await response.json();
+  if (Array.isArray(body.errors) && body.errors.length) throw new Error("cloudflare_a1_provider_error");
+  return body;
+}
+function responseRows(response, siteUrl, observedAt, windowKey = "") {
+  const groups = response && response.data && response.data.viewer && Array.isArray(response.data.viewer.zones) ? response.data.viewer.zones[0] && response.data.viewer.zones[0].a1 : null;
+  if (!Array.isArray(groups)) throw new Error("cloudflare_a1_response_invalid");
+  const host = new URL(siteUrl).hostname.toLowerCase();
+  return groups.slice(0, 5000).flatMap((group) => {
+    const dimensions = group && group.dimensions || {};
+    const userAgent = userAgentProduct(dimensions.userAgent);
+    const count = Math.max(0, Math.floor(Number(group && group.count || 0)));
+    const status = Math.floor(Number(dimensions.edgeResponseStatus || 0));
+    if (!userAgent || count < 1 || status < 100 || status > 599) return [];
+    const clean = cleanPath(dimensions.clientRequestPath);
+    const eventId = `cfa1_${crypto.createHash("sha256").update(JSON.stringify([host, windowKey, userAgent, clean, status])).digest("hex").slice(0, 32)}`;
+    return [{ event_id: eventId, host, path: clean, user_agent: userAgent, status, bytes: Math.max(0, Math.floor(Number(group && group.sum && group.sum.edgeResponseBytes || 0))), request_count: count, timestamp: observedAt, source: "cloudflare_ai_crawl_control" }];
+  });
+}
+function createCloudflareA1Sync({ client, statePath, siteUrl, zoneId, apiToken, userAgents = DEFAULT_USER_AGENTS, lookbackMs = 3600000, intervalMs = 900000, maxPendingRows = 5000, fetchCloudflare = defaultFetchCloudflare, now = Date.now, random = Math.random } = {}) {
+  if (!client || typeof client.aiReads !== "function" || !statePath || !siteUrl || !zoneId || !apiToken) throw new Error("cloudflare_a1_sync_configuration_invalid");
+  const normalizedUrl = new URL(siteUrl).origin;
+  const agents = [...new Set((userAgents || []).map(userAgentProduct).filter(Boolean))].slice(0, 50);
+  if (!agents.length) throw new Error("cloudflare_a1_user_agents_required");
+  const state = loadState(statePath);
+  const persist = () => saveState(statePath, state);
+  async function upload(rows, windowEnd) {
+    try {
+      const result = await client.aiReads({ url: normalizedUrl, logs: rows, source: "cloudflare_a1_sync" });
+      state.pending = null; state.cursor_end = windowEnd; state.retry_at = 0; state.attempts = 0; state.last_sync_at = now(); state.next_run_at = state.last_sync_at + Math.max(60000, intervalMs); state.last_error = null; persist();
+      return { ok: true, status: "synced", rows: rows.length, requests: rows.reduce((sum, row) => sum + row.request_count, 0), stored: Number(result && result.stored || 0), cursor_end: state.cursor_end };
+    } catch (error) {
+      state.pending = { rows: rows.slice(0, maxPendingRows), window_end: windowEnd }; state.attempts += 1;
+      const backoff = Math.min(300000, 1000 * (2 ** Math.min(8, state.attempts - 1))); state.retry_at = now() + Math.round(backoff * (0.5 + random())); state.last_error = { code: String(error.code || "a1_delivery_failed").slice(0, 80) }; persist();
+      return { ok: false, status: "queued_for_retry", pending_rows: state.pending.rows.length, retry_at: state.retry_at };
+    }
+  }
+  async function runOnce({ force = false } = {}) {
+    const timestamp = now();
+    if (!force && state.retry_at > timestamp) return { ok: false, status: "retry_wait", retry_at: state.retry_at, pending_rows: state.pending ? state.pending.rows.length : 0 };
+    if (state.pending) return upload(state.pending.rows, state.pending.window_end);
+    if (!force && state.next_run_at > timestamp) return { ok: true, status: "not_due", next_run_at: state.next_run_at };
+    const bucketMs = Math.max(60000, intervalMs);
+    const endMs = Math.floor(timestamp / bucketMs) * bucketMs;
+    const end = new Date(endMs).toISOString();
+    const start = state.cursor_end || new Date(timestamp - Math.max(60000, lookbackMs)).toISOString();
+    if (Date.parse(start) >= endMs) return { ok: true, status: "not_due", next_run_at: endMs + bucketMs };
+    const response = await fetchCloudflare({ token: apiToken, query: buildQuery(zoneId, start, end, agents) });
+    return upload(responseRows(response, normalizedUrl, timestamp, `${start}/${end}`), end);
+  }
+  async function status() {
+    return { schema: state.schema, provider: "cloudflare_ai_crawl_control", host: new URL(normalizedUrl).hostname, cursor_end: state.cursor_end, pending_rows: state.pending ? state.pending.rows.length : 0, retry_at: state.retry_at, next_run_at: state.next_run_at, last_sync_at: state.last_sync_at, last_error: state.last_error };
+  }
+  return Object.freeze({ runOnce, status });
+}
+
+module.exports = { DEFAULT_USER_AGENTS, buildQuery, responseRows, createCloudflareA1Sync };

package/domain-proof.js

@@ -1,12 +1,14 @@
 "use strict";
 
 const fs = require("node:fs/promises");
+const fsSync = require("node:fs");
 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 IDENTITY_SCHEMA = "agentx-site-identity-v1";
 const PROOF_RELATIVE_PATH = path.join(".well-known", "agent-id.json");
 
 function proofError(code, message) {
@@ -34,6 +36,151 @@ function exactHostname(value) {
   return host;
 }
 
+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 canonicalBytes(value) {
+  return Buffer.from(JSON.stringify(stableValue(value)), "utf8");
+}
+
+function sha256(value) {
+  return `sha256:${crypto.createHash("sha256").update(canonicalBytes(value)).digest("hex")}`;
+}
+
+function serviceOrigin(value) {
+  let parsed;
+  try { parsed = new URL(String(value || "")); } catch (_error) {
+    throw proofError("invalid_service_origin", "serviceOrigin must be an HTTPS origin");
+  }
+  if (parsed.protocol !== "https:" || parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash) {
+    throw proofError("invalid_service_origin", "serviceOrigin must be an HTTPS origin");
+  }
+  return parsed.origin;
+}
+
+function buildEnterpriseIdentityDocument({ state, credential, identity, serviceOrigin: issuerOrigin }) {
+  if (!state || state.status !== "verified_domain") {
+    throw proofError("identity_not_verified", "domain verification must complete before publishing identity");
+  }
+  if (!credential || credential.status !== "active") {
+    throw proofError("credential_not_active", "an active enterprise credential is required");
+  }
+  if (!identity || !identity.key_path || !identity.public_key_pem || !identity.public_key_thumbprint) {
+    throw proofError("identity_key_missing", "the customer Ed25519 identity is required");
+  }
+  const host = exactHostname(credential.host);
+  const agentId = requiredString(credential.agent_id, "credential.agent_id");
+  const environment = requiredString(credential.environment, "credential.environment");
+  const thumbprint = requiredString(credential.public_key_thumbprint, "credential.public_key_thumbprint");
+  const site = new URL(requiredString(state.site_url, "state.site_url"));
+  const issuer = serviceOrigin(issuerOrigin);
+  if (
+    site.protocol !== "https:" || site.hostname.toLowerCase() !== host ||
+    state.agent_id !== agentId || state.environment !== environment ||
+    identity.public_key_thumbprint !== thumbprint ||
+    (state.public_key_thumbprint && state.public_key_thumbprint !== thumbprint)
+  ) {
+    throw proofError("identity_subject_mismatch", "state, credential, site, and signing key must identify the same Agent");
+  }
+  const publicKey = crypto.createPublicKey(identity.public_key_pem);
+  const publicKeyJwk = publicKey.export({ format: "jwk" });
+  const body = {
+    schema: IDENTITY_SCHEMA,
+    agent_id: agentId,
+    tenant_id: requiredString(credential.tenant_id, "credential.tenant_id"),
+    host,
+    environment,
+    controller: `https://${host}`,
+    issuer: { id: issuer, name: "twin3 AgentX.ID" },
+    verification_method: {
+      id: `https://${host}/.well-known/agent-id.json#site-key`,
+      type: "JsonWebKey2020",
+      controller: `https://${host}`,
+      publicKeyJwk,
+      public_key_thumbprint: thumbprint,
+    },
+    credential_status: {
+      credential_id: requiredString(credential.credential_id, "credential.credential_id"),
+      state: "active",
+      issued_at: Number(credential.issued_at || state.verified_at || 0),
+      expires_at: Number(credential.expires_at || 0),
+      status_url: `${issuer}/agentx/id/${agentId}/status.json`,
+    },
+    services: {
+      passport: `${issuer}/agentx/id/${agentId}.json`,
+      proof_graph: `${issuer}/agentx/id/${agentId}/proof.json`,
+      agent_card: `https://${host}/.well-known/agent-card.json`,
+    },
+    trust_anchors: {
+      domain: { status: "verified", method: "well_known" },
+      erc_8004: { status: "not_registered" },
+      google_marketplace: { status: "not_asserted" },
+    },
+    non_claims: [
+      "not_a_google_issued_identity",
+      "not_registered_in_erc_8004",
+      "does_not_grant_website_mutation_authority",
+    ],
+  };
+  body.content_hash = sha256(body);
+  const privateKey = crypto.createPrivateKey(fsSync.readFileSync(identity.key_path, "utf8"));
+  const signature = crypto.sign(null, canonicalBytes(body), privateKey).toString("base64url");
+  return {
+    ...body,
+    proof: {
+      type: "DataIntegrityProof",
+      cryptosuite: "eddsa-agentx-stable-json-v1",
+      proofPurpose: "assertionMethod",
+      verificationMethod: body.verification_method.id,
+      proofValue: `base64url:${signature}`,
+    },
+  };
+}
+
+function verifyEnterpriseIdentityDocument(document, { now = Math.floor(Date.now() / 1000) } = {}) {
+  const failures = [];
+  if (!document || document.schema !== IDENTITY_SCHEMA) failures.push("unsupported_identity_schema");
+  const proof = document && document.proof || {};
+  const signed = document && typeof document === "object" ? { ...document } : {};
+  delete signed.proof;
+  const hashInput = { ...signed };
+  delete hashInput.content_hash;
+  if (!signed.content_hash || signed.content_hash !== sha256(hashInput)) failures.push("content_hash_mismatch");
+  const method = signed.verification_method || {};
+  if (signed.controller !== `https://${signed.host}` || method.controller !== signed.controller) failures.push("controller_binding_mismatch");
+  if (!/^agt_[A-Za-z0-9_-]{4,128}$/.test(String(signed.agent_id || ""))) failures.push("agent_id_invalid");
+  if (proof.verificationMethod !== method.id || proof.cryptosuite !== "eddsa-agentx-stable-json-v1") failures.push("proof_metadata_mismatch");
+  try {
+    const publicKey = crypto.createPublicKey({ key: method.publicKeyJwk, format: "jwk" });
+    const publicDer = publicKey.export({ type: "spki", format: "der" });
+    const actualThumbprint = `sha256:${crypto.createHash("sha256").update(publicDer).digest("base64url")}`;
+    if (actualThumbprint !== method.public_key_thumbprint) failures.push("public_key_thumbprint_mismatch");
+    const encoded = String(proof.proofValue || "");
+    const signature = encoded.startsWith("base64url:") ? Buffer.from(encoded.slice(10), "base64url") : null;
+    if (!signature || !crypto.verify(null, canonicalBytes(signed), publicKey, signature)) failures.push("proof_value_mismatch");
+  } catch (_error) {
+    failures.push("public_key_invalid");
+  }
+  const expiry = Number((signed.credential_status || {}).expires_at || 0);
+  if (!Number.isFinite(expiry) || expiry <= Number(now)) failures.push("credential_expired");
+  if ((signed.credential_status || {}).state !== "active") failures.push("credential_not_active");
+  return {
+    schema: "agentx-site-identity-verification-v1",
+    ok: failures.length === 0,
+    agent_id: signed.agent_id || "",
+    host: signed.host || "",
+    failure_codes: [...new Set(failures)],
+    offline_signature_valid: !failures.some(code => ["content_hash_mismatch", "controller_binding_mismatch", "proof_metadata_mismatch", "proof_value_mismatch", "public_key_invalid", "public_key_thumbprint_mismatch"].includes(code)),
+    offline_trust_level: "self_signature_only",
+    trust_established: false,
+    online_status_required: true,
+    status_url: (signed.credential_status || {}).status_url || "",
+  };
+}
+
 function buildWellKnownProofDocument(challenge, { now = null } = {}) {
   const isChallenge = challenge && challenge.schema === CHALLENGE_SCHEMA && challenge.method === "well_known";
   const isProof = challenge && challenge.schema === PROOF_SCHEMA;
@@ -196,13 +343,59 @@ async function writeSiteAgentVerificationDocument({ registration, projectRoot, p
   };
 }
 
+async function writeEnterpriseIdentityDocument({ document, projectRoot, publicRoot, approved = false }) {
+  if (approved !== true) {
+    throw proofError("approval_required", "publishing a durable Agent identity requires explicit approval");
+  }
+  const verification = verifyEnterpriseIdentityDocument(document);
+  if (!verification.ok) {
+    throw proofError("identity_document_invalid", verification.failure_codes.join(","));
+  }
+  const { project, root, directory, target } = resolveProofTarget({ projectRoot, publicRoot });
+  const [realProject, realRoot] = await Promise.all([fs.realpath(project), fs.realpath(root)]);
+  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 existing = await readExisting(target);
+  if (existing !== null) {
+    let parsed;
+    try { parsed = JSON.parse(existing); } catch (_error) { parsed = null; }
+    const managed = parsed && [PROOF_SCHEMA, IDENTITY_SCHEMA].includes(parsed.schema);
+    if (!managed || 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-identity-write-receipt-v1",
+    changed: existing !== serialized,
+    path: target,
+    relative_path: "/.well-known/agent-id.json",
+    sha256: `sha256:${crypto.createHash("sha256").update(serialized).digest("hex")}`,
+    agent_id: document.agent_id,
+    host: document.host,
+  };
+}
+
 module.exports = {
   PROOF_SCHEMA,
   SITE_VERIFICATION_SCHEMA,
+  IDENTITY_SCHEMA,
   PROOF_RELATIVE_PATH,
   buildWellKnownProofDocument,
   buildSiteAgentVerificationDocument,
+  buildEnterpriseIdentityDocument,
+  verifyEnterpriseIdentityDocument,
   resolveProofTarget,
   writeWellKnownProofDocument,
   writeSiteAgentVerificationDocument,
+  writeEnterpriseIdentityDocument,
 };

package/edge-html-injection.js

@@ -0,0 +1,258 @@
+"use strict";
+
+/**
+ * Edge HTML injection lane.
+ *
+ * The repository connector is deliberately limited to five allowlisted
+ * replaceable machine-readable files, which means `seo_jsonld`, `seo_og`, and
+ * `geo_org_entity` could only ever be delivered as snippets for a human to paste into
+ * HTML templates. This module closes those checks by rewriting the HTML response
+ * inside the customer's own edge worker. `geo_sameas` closes only when the customer
+ * supplies explicit external profile URLs. This structural signal does not verify
+ * ownership or authority of those third-party profiles.
+ *
+ * The trust boundary is unchanged: this code runs in the customer's
+ * infrastructure, it never writes to the customer's source tree, and the site
+ * owner's existing markup always wins over injected markup.
+ */
+
+const MAX_DOCUMENT_BYTES = 1024 * 1024;
+
+const SECRET_PATTERNS = [
+  /\bak_aeo_[A-Za-z0-9_-]{6,}\b/,
+  /\bav_[A-Za-z0-9_-]{8,}\b/,
+  /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/,
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/
+];
+
+const INJECTION_MARKER = "data-agent-id-injected";
+
+function injectionError(code, message) {
+  const error = new Error(message || code);
+  error.code = code;
+  return error;
+}
+
+function assertNoSecret(value) {
+  const text = typeof value === "string" ? value : JSON.stringify(value || "");
+  if (SECRET_PATTERNS.some((pattern) => pattern.test(text))) {
+    throw injectionError("EDGE_HTML_SECRET_DETECTED", "Injection content contains a credential-like value and was rejected.");
+  }
+}
+
+function escapeAttribute(value) {
+  return String(value == null ? "" : value)
+    .replace(/&/g, "&")
+    .replace(/"/g, """)
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * Escape a JSON-LD payload so it can never break out of its script element.
+ * `<` is escaped as `\u003c`, which is valid JSON and inert inside HTML.
+ */
+function serializeJsonLd(value) {
+  return JSON.stringify(value, null, 2).replace(/</g, "\\u003c");
+}
+
+function httpsUrl(value) {
+  const text = String(value || "").trim();
+  if (!text) return "";
+  if (!/^https:\/\//i.test(text)) throw injectionError("EDGE_HTML_INSECURE_URL", `Injection URLs must use https: ${text}`);
+  return text;
+}
+
+function normalizeSameAs(list) {
+  const values = Array.isArray(list) ? list : list ? [list] : [];
+  const seen = new Set();
+  const output = [];
+  for (const item of values) {
+    const url = httpsUrl(item);
+    if (!url || seen.has(url)) continue;
+    seen.add(url);
+    output.push(url);
+  }
+  return output;
+}
+
+function canonicalHost(value) {
+  const text = String(value || "").trim();
+  try {
+    return new URL(`https://${text}`).hostname.toLowerCase().replace(/\.$/, "");
+  } catch (_error) {
+    throw injectionError("EDGE_HTML_IDENTITY_REQUIRED", "Identity host must be a valid hostname.");
+  }
+}
+
+/**
+ * Build a reviewable injection plan. Nothing is applied here; the plan is the
+ * artifact an owner (or the optimization loop) approves.
+ */
+function createHtmlInjectionPlan({ identity, organization = {}, openGraph = {}, now } = {}) {
+  if (!identity || !identity.host || !identity.base_url) {
+    throw injectionError("EDGE_HTML_IDENTITY_REQUIRED", "An identity with host and base_url is required.");
+  }
+  assertNoSecret(identity);
+  assertNoSecret(organization);
+  assertNoSecret(openGraph);
+
+  const baseUrl = httpsUrl(identity.base_url);
+  const identityHost = canonicalHost(identity.host);
+  const baseHost = new URL(baseUrl).hostname.toLowerCase().replace(/\.$/, "");
+  if (identityHost !== baseHost) {
+    throw injectionError("EDGE_HTML_IDENTITY_HOST_MISMATCH", "Identity host must match the HTTPS base URL hostname.");
+  }
+  const sameAs = normalizeSameAs(organization.sameAs);
+
+  const jsonld = {
+    "@context": "https://schema.org",
+    "@type": String(organization.type || "Organization"),
+    name: String(organization.name || identity.host),
+    url: baseUrl,
+    identifier: {
+      "@type": "PropertyValue",
+      propertyID: "AgentX.ID",
+      value: String(identity.agent_id || "")
+    }
+  };
+  if (sameAs.length) jsonld.sameAs = sameAs;
+  if (organization.logo) jsonld.logo = httpsUrl(organization.logo);
+  if (organization.description) jsonld.description = String(organization.description);
+
+  const og = [];
+  og.push({ property: "og:title", content: String(openGraph.title || organization.name || identity.host) });
+  if (openGraph.description) og.push({ property: "og:description", content: String(openGraph.description) });
+  og.push({ property: "og:url", content: baseUrl });
+  if (openGraph.image) og.push({ property: "og:image", content: httpsUrl(openGraph.image) });
+  og.push({ property: "og:type", content: String(openGraph.type || "website") });
+
+  const closes = ["seo_jsonld", "seo_og", "geo_org_entity"];
+  if (sameAs.length) closes.push("geo_sameas");
+
+  return Object.freeze({
+    schema: "agentx-edge-html-injection-plan-v1",
+    lane: "edge_html_injection",
+    approval_required: true,
+    customer_source_write_access: false,
+    host: identity.host,
+    base_url: baseUrl,
+    agent_id: String(identity.agent_id || ""),
+    verification_status: String(identity.verification_status || "unverified_scan"),
+    created_at: Number(now || Date.now()),
+    jsonld,
+    open_graph: og,
+    sameas_present: sameAs.length > 0,
+    closes_checks: closes,
+    owner_markup_wins: true,
+    non_claims: [
+      "does_not_write_to_customer_source_tree",
+      "runs_in_customer_edge_infrastructure",
+      "never_overrides_existing_owner_markup",
+      "does_not_guarantee_ai_citation_or_ranking"
+    ]
+  });
+}
+
+function hasJsonLdOrganization(head) {
+  const blocks = head.match(/<script[^>]+type\s*=\s*["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi) || [];
+  return blocks.some((block) => /"@type"\s*:\s*"(Organization|LocalBusiness|Corporation)"/i.test(block));
+}
+
+function hasOgProperty(head, property) {
+  const escaped = String(property).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`<meta[^>]+property\\s*=\\s*["']${escaped}["']`, "i").test(head);
+}
+
+function alreadyInjected(head) {
+  return head.includes(INJECTION_MARKER);
+}
+
+/**
+ * Rewrite a single HTML document. Returns the original string untouched whenever
+ * the document is not safely rewritable, so the lane can never break a page.
+ */
+function applyHtmlInjection(html, plan) {
+  if (!plan || plan.schema !== "agentx-edge-html-injection-plan-v1") {
+    throw injectionError("EDGE_HTML_PLAN_INVALID", "A valid edge HTML injection plan is required.");
+  }
+  const source = typeof html === "string" ? html : "";
+  if (Buffer.byteLength(source, "utf8") > MAX_DOCUMENT_BYTES) {
+    return { html: source, injected_checks: [], skipped: "document_too_large" };
+  }
+  const headClose = source.search(/<\/head\s*>/i);
+  if (headClose === -1) {
+    return { html: source, injected_checks: [], skipped: "no_head_element" };
+  }
+  const head = source.slice(0, headClose);
+  if (alreadyInjected(head)) {
+    return { html: source, injected_checks: [], skipped: "already_injected" };
+  }
+
+  const parts = [];
+  const injected = [];
+
+  if (!hasJsonLdOrganization(head)) {
+    parts.push(`<script type="application/ld+json" ${INJECTION_MARKER}="seo_jsonld">${serializeJsonLd(plan.jsonld)}</script>`);
+    injected.push("seo_jsonld", "geo_org_entity");
+    if (plan.sameas_present) injected.push("geo_sameas");
+  }
+
+  if (!hasOgProperty(head, "og:title")) {
+    const missingTags = plan.open_graph.filter((tag) => !hasOgProperty(head, tag.property));
+    for (const tag of missingTags) {
+      parts.push(`<meta property="${escapeAttribute(tag.property)}" content="${escapeAttribute(tag.content)}" ${INJECTION_MARKER}="seo_og">`);
+    }
+    if (missingTags.some((tag) => tag.property === "og:title")) injected.push("seo_og");
+  }
+
+  if (!parts.length) {
+    return { html: source, injected_checks: [], skipped: "owner_markup_already_present" };
+  }
+
+  const block = `\n${parts.join("\n")}\n`;
+  const output = source.slice(0, headClose) + block + source.slice(headClose);
+  return { html: output, injected_checks: [...new Set(injected)], skipped: null };
+}
+
+const REWRITABLE_CONTENT_TYPE = /^text\/html\b/i;
+
+/**
+ * Wrap an origin fetch so HTML responses are rewritten and everything else is
+ * passed through byte-for-byte.
+ */
+function createHtmlInjectionHandler({ plan, origin } = {}) {
+  if (typeof origin !== "function") throw injectionError("EDGE_HTML_ORIGIN_REQUIRED", "An origin fetch function is required.");
+  if (!plan || plan.schema !== "agentx-edge-html-injection-plan-v1") {
+    throw injectionError("EDGE_HTML_PLAN_INVALID", "A valid edge HTML injection plan is required.");
+  }
+  return async function handle(request) {
+    const response = await origin(request);
+    const method = String((request && request.method) || "GET").toUpperCase();
+    if (!["GET", "HEAD"].includes(method)) return response;
+    if (!response || response.status !== 200) return response;
+    const contentType = response.headers.get("Content-Type") || "";
+    if (!REWRITABLE_CONTENT_TYPE.test(contentType)) return response;
+
+    const body = await response.text();
+    const result = applyHtmlInjection(body, plan);
+    const headers = new Headers(response.headers);
+    if (result.injected_checks.length) {
+      headers.set("X-Agent-ID-Injected", result.injected_checks.join(","));
+    }
+    headers.delete("Content-Length");
+    return new Response(method === "HEAD" ? null : result.html, {
+      status: response.status,
+      statusText: response.statusText,
+      headers
+    });
+  };
+}
+
+module.exports = {
+  MAX_DOCUMENT_BYTES,
+  INJECTION_MARKER,
+  createHtmlInjectionPlan,
+  applyHtmlInjection,
+  createHtmlInjectionHandler
+};

package/enterprise-identity.js

@@ -152,6 +152,13 @@ function createEnterpriseSession({ serviceOrigin, siteUrl, environment, credenti
     return responseJson(await fetcher(`${origin}/api/site_agents/v1/tasks${pathname}`, request));
   }
 
+  async function dashboardRequest(pathname, { method = "GET", body = null } = {}) {
+    const accessToken = await session.getAccessToken(["insights:read"]);
+    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/dashboard${pathname}`, request));
+  }
+
   const session = {
     schema: "agentx-enterprise-session-v1",
     site_url: site.url,
@@ -201,9 +208,23 @@ function createEnterpriseSession({ serviceOrigin, siteUrl, environment, credenti
       const bounded = Math.max(1, Math.min(Number(limit) || 20, 100));
       return managedRequest(`runs?limit=${encodeURIComponent(Math.trunc(bounded))}`);
     },
+    async createDashboardPairing() {
+      return dashboardRequest("/pairings", { method: "POST", body: {} });
+    },
     async listTasks() {
       return taskRequest("");
     },
+    async proposeTask({ path: resourcePath, content, policyDigest, idempotencyKey } = {}) {
+      if (typeof resourcePath !== "string" || !resourcePath.trim()) throw enterpriseError("enterprise_task_path_required");
+      if (typeof content !== "string" || !content) throw enterpriseError("enterprise_task_content_required");
+      if (typeof policyDigest !== "string" || !policyDigest) throw enterpriseError("enterprise_task_policy_digest_required");
+      if (typeof idempotencyKey !== "string" || !idempotencyKey.trim()) throw enterpriseError("enterprise_task_idempotency_key_required");
+      return taskRequest("", {
+        method: "POST",
+        scopes: ["tasks:execute"],
+        body: { path: resourcePath, content, policy_digest: policyDigest, idempotency_key: idempotencyKey }
+      });
+    },
     async getTaskComparison(taskId) {
       const id = encodeURIComponent(String(taskId || ""));
       if (!id) throw enterpriseError("enterprise_task_id_required");