@twin3-ai/agent-id 0.1.0 → 0.3.0

package/artifact-bundle.js

@@ -0,0 +1,92 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const { AUTO_MANAGED_PATHS } = require("./repository-connector.js");
+
+const SCHEMA = "agentx-signed-artifact-bundle-v0.2";
+const MAX_LIFETIME_SECONDS = 7 * 24 * 60 * 60;
+const SECRET_CONTENT = /(?:-----BEGIN [A-Z ]*PRIVATE KEY-----|\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)/i;
+
+function bundleError(code) {
+  const error = new Error(code);
+  error.code = code;
+  return error;
+}
+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 canonical(value) { return Buffer.from(JSON.stringify(stableValue(value)), "utf8"); }
+function hash(value) { return `sha256:${crypto.createHash("sha256").update(value).digest("hex")}`; }
+function sameSubject(left, right) {
+  return ["tenant_id", "host", "environment", "agent_id"].every((field) => String(left && left[field] || "") === String(right && right[field] || ""));
+}
+function keyId(key) {
+  const publicKey = key && key.type === "public" ? key : crypto.createPublicKey(key);
+  const der = publicKey.export({ type: "spki", format: "der" });
+  return `ed25519:${crypto.createHash("sha256").update(der).digest("hex").slice(0, 24)}`;
+}
+function normalizeArtifacts(artifacts) {
+  if (!Array.isArray(artifacts) || artifacts.length === 0) throw bundleError("ARTIFACT_BUNDLE_ARTIFACTS_REQUIRED");
+  const seen = new Set();
+  return artifacts.map((artifact) => {
+    const path = String(artifact && artifact.path || "").replace(/^\/+/, "");
+    const content = artifact && artifact.content;
+    if (!AUTO_MANAGED_PATHS.has(path)) throw bundleError("ARTIFACT_BUNDLE_PATH_NOT_ALLOWED");
+    if (seen.has(path)) throw bundleError("ARTIFACT_BUNDLE_DUPLICATE_PATH");
+    if (typeof content !== "string" || Buffer.byteLength(content, "utf8") > 1024 * 1024 || SECRET_CONTENT.test(content)) throw bundleError("ARTIFACT_BUNDLE_INVALID_CONTENT");
+    if (path.endsWith(".json")) {
+      try { JSON.parse(content); } catch (_error) { throw bundleError("ARTIFACT_BUNDLE_INVALID_JSON"); }
+    }
+    seen.add(path);
+    return {
+      path,
+      content_type: String(artifact.content_type || "text/plain; charset=utf-8").slice(0, 120),
+      content,
+      content_hash: hash(Buffer.from(content, "utf8"))
+    };
+  });
+}
+function unsignedBundle(bundle) {
+  const copy = { ...bundle };
+  delete copy.signature;
+  return copy;
+}
+function createArtifactBundle({ subject, artifacts, issuerPrivateKey, issuerPublicKey, source = {}, issuedAt = Math.floor(Date.now() / 1000), expiresAt = issuedAt + 3600 } = {}) {
+  if (!subject || !issuerPrivateKey || !issuerPublicKey) throw bundleError("ARTIFACT_BUNDLE_CONFIGURATION_INVALID");
+  if (!["tenant_id", "host", "environment", "agent_id"].every((field) => typeof subject[field] === "string" && subject[field])) throw bundleError("ARTIFACT_BUNDLE_SUBJECT_INVALID");
+  if (typeof source.run_id !== "string" || !source.run_id || typeof source.receipt_hash !== "string" || !/^sha256:[a-f0-9]{6,}$/i.test(source.receipt_hash)) throw bundleError("ARTIFACT_BUNDLE_SOURCE_INVALID");
+  if (!Number.isInteger(issuedAt) || !Number.isInteger(expiresAt) || expiresAt <= issuedAt || expiresAt - issuedAt > MAX_LIFETIME_SECONDS) throw bundleError("ARTIFACT_BUNDLE_TIME_INVALID");
+  const bundle = {
+    schema: SCHEMA,
+    bundle_version: 2,
+    subject: stableValue(subject),
+    source: { run_id: source.run_id, receipt_hash: source.receipt_hash },
+    issued_at: issuedAt,
+    expires_at: expiresAt,
+    issuer_key_id: keyId(issuerPublicKey),
+    artifacts: normalizeArtifacts(artifacts)
+  };
+  bundle.bundle_hash = hash(canonical(bundle));
+  bundle.signature = crypto.sign(null, canonical(bundle), issuerPrivateKey).toString("base64url");
+  return bundle;
+}
+function verifyArtifactBundle(bundle, { issuerPublicKey, expectedSubject, now = Math.floor(Date.now() / 1000) } = {}) {
+  if (!bundle || bundle.schema !== SCHEMA || bundle.bundle_version !== 2 || !issuerPublicKey || !bundle.signature) throw bundleError("ARTIFACT_BUNDLE_INVALID");
+  if (!sameSubject(bundle.subject, expectedSubject)) throw bundleError("ARTIFACT_BUNDLE_SUBJECT_MISMATCH");
+  if (!Number.isInteger(bundle.issued_at) || !Number.isInteger(bundle.expires_at) || now < bundle.issued_at || now >= bundle.expires_at || bundle.expires_at - bundle.issued_at > MAX_LIFETIME_SECONDS) throw bundleError("ARTIFACT_BUNDLE_EXPIRED");
+  if (bundle.issuer_key_id !== keyId(issuerPublicKey)) throw bundleError("ARTIFACT_BUNDLE_SIGNATURE_INVALID");
+  const artifacts = normalizeArtifacts(bundle.artifacts);
+  if (artifacts.some((artifact, index) => artifact.content_hash !== bundle.artifacts[index].content_hash)) throw bundleError("ARTIFACT_BUNDLE_SIGNATURE_INVALID");
+  const unsigned = unsignedBundle(bundle);
+  const claimedHash = unsigned.bundle_hash;
+  delete unsigned.bundle_hash;
+  if (claimedHash !== hash(canonical(unsigned))) throw bundleError("ARTIFACT_BUNDLE_SIGNATURE_INVALID");
+  const verificationKey = issuerPublicKey && issuerPublicKey.type === "public" ? issuerPublicKey : crypto.createPublicKey(issuerPublicKey);
+  const verified = crypto.verify(null, canonical({ ...unsigned, bundle_hash: claimedHash }), verificationKey, Buffer.from(bundle.signature, "base64url"));
+  if (!verified) throw bundleError("ARTIFACT_BUNDLE_SIGNATURE_INVALID");
+  return { verified: true, bundle_hash: claimedHash, subject: bundle.subject, artifacts: artifacts.map(({ content, ...item }) => item) };
+}
+
+module.exports = { SCHEMA, MAX_LIFETIME_SECONDS, createArtifactBundle, verifyArtifactBundle };

package/b1-sync.js

@@ -0,0 +1,85 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const GA4_ENDPOINT = "https://analyticsdata.googleapis.com/v1beta/properties";
+const AI_HOSTS = Object.freeze(["chat.openai.com", "chatgpt.com", "claude.ai", "copilot.microsoft.com", "gemini.google.com", "perplexity.ai"]);
+
+function hash(value) { return crypto.createHash("sha256").update(String(value)).digest("hex"); }
+function emptyState() { return { schema: "agentx-b1-sync-state-v1", cursor: "", pending: null, seen: [], retry_at: 0, attempts: 0, next_run_at: 0, last_sync_at: 0, last_error: null }; }
+function loadState(statePath) {
+  try { return { ...emptyState(), ...JSON.parse(fs.readFileSync(statePath, "utf8")) }; }
+  catch (error) { if (error.code === "ENOENT") return emptyState(); throw new Error("b1_sync_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 aiHost(value) {
+  const raw = String(value || "").trim().toLowerCase();
+  if (!raw || ["(direct)", "(none)", "(not set)"].includes(raw)) return "";
+  try {
+    const host = new URL(raw.includes("://") ? raw : `https://${raw}`).hostname.replace(/\.$/, "");
+    return AI_HOSTS.find((known) => host === known || host.endsWith(`.${known}`)) ? host : "";
+  } catch (_error) { return ""; }
+}
+function safeLabel(value) { return /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(String(value || "")) ? String(value) : ""; }
+function reportMap(row, dimensionHeaders, metricHeaders) {
+  const dimensions = Object.fromEntries(dimensionHeaders.map((name, index) => [name, String(row.dimensionValues && row.dimensionValues[index] && row.dimensionValues[index].value || "")]));
+  const metrics = Object.fromEntries(metricHeaders.map((name, index) => [name, String(row.metricValues && row.metricValues[index] && row.metricValues[index].value || "0")]));
+  return { dimensions, metrics };
+}
+function ga4Conversions(response, siteUrl, windowKey) {
+  const dimensions = (response.dimensionHeaders || []).map((item) => item && item.name).filter(Boolean);
+  const metrics = (response.metricHeaders || []).map((item) => item && item.name).filter(Boolean);
+  return (response.rows || []).flatMap((row) => {
+    const mapped = reportMap(row || {}, dimensions, metrics);
+    const source = aiHost(mapped.dimensions.sessionSource);
+    const count = Math.max(0, Math.floor(Number(mapped.metrics.keyEvents || 0)));
+    const revenue = Math.max(0, Number(mapped.metrics.totalRevenue || 0));
+    if (!source || count < 1 || !Number.isFinite(revenue)) return [];
+    const campaign = safeLabel(mapped.dimensions.sessionCampaignName);
+    const currency = String(response.currencyCode || response.metadata && response.metadata.currencyCode || "USD").toUpperCase();
+    return [{ conversion_id:`ga4_${hash(JSON.stringify([windowKey, source, campaign])).slice(0,32)}`, event:"ga4_key_event", url:siteUrl, referrer:`https://${source}/`, utm_source:source, utm_campaign:campaign, conversion_count:count, value:Number(revenue.toFixed(2)), currency:/^[A-Z]{3}$/.test(currency)?currency:"USD", timestamp:Date.parse(`${windowKey}T23:59:59Z`) }];
+  });
+}
+async function defaultFetchGa4({ token, propertyId, startDate, endDate, fetchImpl = globalThis.fetch }) {
+  if (typeof fetchImpl !== "function") throw new Error("ga4_fetch_unavailable");
+  const response = await fetchImpl(`${GA4_ENDPOINT}/${encodeURIComponent(propertyId)}:runReport`, { method:"POST", headers:{ authorization:`Bearer ${token}`, "content-type":"application/json" }, body:JSON.stringify({ dateRanges:[{startDate,endDate}], dimensions:[{name:"sessionSource"},{name:"sessionMedium"},{name:"sessionCampaignName"}], metrics:[{name:"sessions"},{name:"keyEvents"},{name:"totalRevenue"}] }), redirect:"error" });
+  if (!response.ok) throw new Error(`ga4_http_${response.status}`);
+  const body = await response.json(); if (body.error) throw new Error("ga4_provider_error"); return body;
+}
+function createBaseSync({ client, statePath, siteUrl, intervalMs, collect, now, random }) {
+  if (!client || typeof client.conversions !== "function" || !statePath || !siteUrl || typeof collect !== "function") throw new Error("b1_sync_configuration_invalid");
+  const url = new URL(siteUrl).origin; const state = loadState(statePath); const persist = () => saveState(statePath, state);
+  async function upload(batch, cursor) {
+    try {
+      const result = batch.length ? await client.conversions({ url, conversions:batch, source:"b1_automatic_sync" }) : { stored:0 };
+      state.pending=null; state.cursor=cursor; state.seen=[...new Set([...state.seen,...batch.map(item=>item.conversion_id)])].slice(-10000); 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:batch.length,conversions:batch.reduce((sum,item)=>sum+Math.max(1,Number(item.conversion_count||1)),0),stored:Number(result.stored||0),cursor};
+    } catch (error) {
+      state.pending={batch:batch.slice(0,5000),cursor}; 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||"b1_delivery_failed").slice(0,80)}; persist();
+      return {ok:false,status:"queued_for_retry",pending:state.pending.batch.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}; if(state.pending)return upload(state.pending.batch,state.pending.cursor); if(!force&&state.next_run_at>timestamp)return {ok:true,status:"not_due",next_run_at:state.next_run_at};
+    const collected=await collect({timestamp,cursor:state.cursor,seen:new Set(state.seen)}); return upload(collected.batch||[],collected.cursor||state.cursor);
+  }
+  async function status(){return {schema:state.schema,host:new URL(url).hostname,cursor:state.cursor,pending:state.pending?state.pending.batch.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});
+}
+function createGa4B1Sync({client,statePath,siteUrl,propertyId,accessToken,fetchGa4=defaultFetchGa4,intervalMs=86400000,now=Date.now,random=Math.random}={}) {
+  if(!propertyId||!accessToken)throw new Error("ga4_b1_configuration_invalid");
+  return createBaseSync({client,statePath,siteUrl,intervalMs,now,random,collect:async({timestamp,cursor})=>{const date=new Date(timestamp-86400000).toISOString().slice(0,10);if(cursor===date)return {batch:[],cursor};const response=await fetchGa4({token:accessToken,propertyId,startDate:date,endDate:date});return {batch:ga4Conversions(response,new URL(siteUrl).origin,date),cursor:date};}});
+}
+function createOrderB1Sync({client,statePath,siteUrl,sourceId,loadOrders,intervalMs=3600000,now=Date.now,random=Math.random}={}) {
+  if(!safeLabel(sourceId)||typeof loadOrders!=="function")throw new Error("order_b1_configuration_invalid");
+  return createBaseSync({client,statePath,siteUrl,intervalMs,now,random,collect:async({timestamp,seen})=>{const rows=await loadOrders();const batch=(Array.isArray(rows)?rows:[]).flatMap((row)=>{const source=aiHost(row&&row.source);const rawId=String(row&&row.order_id||"");const receipt=rawId?`order_${hash(`${sourceId}:${rawId}`).slice(0,32)}`:"";const amount=Number(row&&row.amount||0);if(!source||!receipt||seen.has(receipt)||!Number.isFinite(amount)||amount<0)return [];return [{conversion_id:receipt,event:safeLabel(row.event)||"order",url:new URL(siteUrl).origin,referrer:`https://${source}/`,value:Number(amount.toFixed(2)),currency:/^[A-Z]{3}$/.test(String(row.currency||"").toUpperCase())?String(row.currency).toUpperCase():"USD",timestamp:Number(row.timestamp||timestamp)}];});return {batch,cursor:String(timestamp)};}});
+}
+
+module.exports={createGa4B1Sync,createOrderB1Sync,ga4Conversions,defaultFetchGa4};

package/bin/agent-id-b1-sync.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { createSiteAgentClient } = require("../site-agent.js");
+const { createGa4B1Sync, createOrderB1Sync } = require("../b1-sync.js");
+
+function valueAfter(args, name, fallback = "") { const index=args.indexOf(name); return index>=0&&args[index+1]?args[index+1]:fallback; }
+function help() {
+  console.log(`agent-id-b1-sync
+
+Usage:
+  agent-id-b1-sync --ga4 --url https://example.com
+  agent-id-b1-sync --orders ./crm-orders.json --source-id crm-main --url https://example.com
+
+Shared environment:
+  SITE_AGENT_KEY       Agent ID Site Agent Key
+  AGENT_ID_ENDPOINT    Parent Agent ID origin
+  AGENT_ID_B1_STATE    Local cursor and retry state path
+
+GA4 environment:
+  GA4_PROPERTY_ID      GA4 numeric property ID
+  GA4_ACCESS_TOKEN     Read-only Analytics Data API OAuth token
+`);
+}
+async function main() {
+  const args=process.argv.slice(2); if(args.includes("--help")||args.includes("-h"))return help();
+  const siteUrl=valueAfter(args,"--url",process.env.SITE_URL||""); if(!siteUrl)throw new Error("--url or SITE_URL is required");
+  const endpoint=valueAfter(args,"--endpoint",process.env.AGENT_ID_ENDPOINT||"");
+  const statePath=valueAfter(args,"--state",process.env.AGENT_ID_B1_STATE||path.join(process.cwd(),".agent-id","b1-sync-state.json"));
+  const client=createSiteAgentClient({endpoint,agentKey:process.env.SITE_AGENT_KEY});
+  let sync;
+  if(args.includes("--ga4")) {
+    sync=createGa4B1Sync({client,statePath,siteUrl,propertyId:process.env.GA4_PROPERTY_ID,accessToken:process.env.GA4_ACCESS_TOKEN});
+  } else {
+    const orderPath=valueAfter(args,"--orders",""); const sourceId=valueAfter(args,"--source-id","");
+    if(!orderPath||!sourceId)throw new Error("--ga4 or both --orders and --source-id are required");
+    sync=createOrderB1Sync({client,statePath,siteUrl,sourceId,loadOrders:async()=>JSON.parse(fs.readFileSync(path.resolve(orderPath),"utf8"))});
+  }
+  const result=args.includes("--status")?await sync.status():await sync.runOnce({force:args.includes("--force")});
+  console.log(JSON.stringify(result,null,2));
+}
+main().catch((error)=>{console.error(error&&error.message?error.message:"b1_sync_failed");process.exit(1);});

package/bin/agent-id-cloudflare-a1.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("node:path");
+const { createSiteAgentClient } = require("../site-agent.js");
+const { createCloudflareA1Sync } = require("../cloudflare-a1-sync.js");
+
+function valueAfter(args, name, fallback = "") {
+  const index = args.indexOf(name);
+  return index >= 0 && args[index + 1] ? args[index + 1] : fallback;
+}
+function help() {
+  console.log(`agent-id-cloudflare-a1
+
+Usage:
+  agent-id-cloudflare-a1 --url https://example.com --once
+  agent-id-cloudflare-a1 --url https://example.com --status
+
+Required environment:
+  SITE_AGENT_KEY          Agent ID Site Agent Key
+  CLOUDFLARE_API_TOKEN    Read-only Cloudflare Analytics token
+  CLOUDFLARE_ZONE_ID      Website zone ID
+
+Optional environment:
+  AGENT_ID_ENDPOINT       Parent Agent ID origin
+  AGENT_ID_A1_STATE       Local cursor and retry state path
+  AGENT_ID_A1_INTERVAL_MS Minimum interval between successful syncs
+`);
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) return help();
+  const siteUrl = valueAfter(args, "--url", process.env.SITE_URL || "");
+  const endpoint = valueAfter(args, "--endpoint", process.env.AGENT_ID_ENDPOINT || "");
+  const statePath = valueAfter(args, "--state", process.env.AGENT_ID_A1_STATE || path.join(process.cwd(), ".agent-id", "cloudflare-a1-state.json"));
+  if (!siteUrl) throw new Error("--url or SITE_URL is required");
+  const client = createSiteAgentClient({ endpoint, agentKey: process.env.SITE_AGENT_KEY });
+  const sync = createCloudflareA1Sync({
+    client,
+    statePath,
+    siteUrl,
+    zoneId: process.env.CLOUDFLARE_ZONE_ID,
+    apiToken: process.env.CLOUDFLARE_API_TOKEN,
+    intervalMs: Number(process.env.AGENT_ID_A1_INTERVAL_MS || 900000)
+  });
+  const result = args.includes("--status") ? await sync.status() : await sync.runOnce({ force: args.includes("--force") });
+  console.log(JSON.stringify(result, null, 2));
+}
+
+main().catch((error) => {
+  console.error(error && error.message ? error.message : "cloudflare_a1_sync_failed");
+  process.exit(1);
+});