@twin3-ai/agent-id 0.1.0

package/local-policy.js

@@ -0,0 +1,118 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const POLICY_SCHEMA = "agentx-local-policy-v1";
+const MAX_BYTES = 1024 * 1024;
+const OPERATIONS = new Set(["upsert", "replace", "delete"]);
+const SENSITIVE_PATHS = /(^|\/)(\.env(?:\.|$)|\.git|id_rsa|id_ed25519|secrets?|credentials?|private[-_.]?key|package-lock\.json)(\/|$)/i;
+const EXECUTABLE_PATHS = /\.(?:sh|bash|zsh|fish|cmd|bat|ps1|exe|dll|so|dylib|js|mjs|cjs|py|rb|php|pl)$/i;
+const SECRET_CONTENT = /(?:-----BEGIN [A-Z ]*PRIVATE KEY-----|\b(?:SITE_AGENT_KEY|AEO_AGENT_KEY|API_KEY|ACCESS_TOKEN|SECRET)\s*[:=]|\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b)/i;
+
+function policyError(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 digest(policy) {
+  const material = { ...policy };
+  delete material.digest;
+  return `sha256:${crypto.createHash("sha256").update(JSON.stringify(stableValue(material))).digest("hex")}`;
+}
+function writePolicy(filePath, policy) {
+  const target = path.resolve(String(filePath || ""));
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  const temporary = `${target}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, JSON.stringify(policy, 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 initializeLocalPolicy(filePath) {
+  const policy = { schema: POLICY_SCHEMA, version: 1, default: "deny", rules: [], approvals: [] };
+  policy.digest = digest(policy);
+  writePolicy(filePath, policy);
+  Object.defineProperty(policy, "_path", { value: path.resolve(filePath), enumerable: false });
+  return policy;
+}
+function loadLocalPolicy(filePath) {
+  if (fs.statSync(filePath).size > MAX_BYTES) throw policyError("policy_file_too_large");
+  const policy = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  if (!policy || policy.schema !== POLICY_SCHEMA || policy.default !== "deny" || !Number.isInteger(policy.version) || !Array.isArray(policy.rules) || !Array.isArray(policy.approvals || [])) throw policyError("invalid_policy");
+  const expected = digest(policy);
+  if (typeof policy.digest !== "string" || policy.digest !== expected) throw policyError("invalid_policy_digest");
+  policy.digest = expected;
+  Object.defineProperty(policy, "_path", { value: path.resolve(filePath), enumerable: false });
+  return policy;
+}
+function validRule(rule) {
+  return rule && typeof rule.connector === "string" && /^[a-z][a-z0-9_-]+$/.test(rule.connector) && rule.connector !== "*"
+    && typeof rule.environment === "string" && /^[a-z][a-z0-9_-]+$/.test(rule.environment) && rule.environment !== "*"
+    && typeof rule.resource_type === "string" && rule.resource_type !== "*"
+    && typeof rule.resource_id === "string" && rule.resource_id.length > 0 && rule.resource_id !== "*"
+    && safeRelative(rule.path_prefix) && !rule.path_prefix.includes("*")
+    && Array.isArray(rule.allowed_operations) && rule.allowed_operations.length > 0 && rule.allowed_operations.every((item) => OPERATIONS.has(item))
+    && Number.isInteger(rule.max_bytes) && rule.max_bytes > 0 && rule.max_bytes <= MAX_BYTES
+    && rule.approval_mode === "explicit" && Number.isInteger(rule.version) && rule.version > 0;
+}
+function approvePolicyRule(policy, rule, { approved = false, approvedBy = "", now = Math.floor(Date.now() / 1000) } = {}) {
+  if (approved !== true || typeof approvedBy !== "string" || !approvedBy.trim()) throw policyError("policy_approval_required");
+  if (!validRule(rule)) throw policyError("invalid_policy_rule");
+  const updated = JSON.parse(JSON.stringify(policy));
+  if (updated.default !== "deny") throw policyError("invalid_policy");
+  updated.version += 1;
+  updated.rules.push({ ...rule, allowed_operations: [...new Set(rule.allowed_operations)].sort() });
+  updated.approvals = [...(updated.approvals || []), { policy_version: updated.version, rule_version: rule.version, approved_by: approvedBy.trim(), approved_at: now, scope_digest: `sha256:${crypto.createHash("sha256").update(JSON.stringify(stableValue(rule))).digest("hex")}` }];
+  updated.digest = digest(updated);
+  if (policy._path) writePolicy(policy._path, updated);
+  if (policy._path) Object.defineProperty(updated, "_path", { value: policy._path, enumerable: false });
+  return updated;
+}
+function safeRelative(value) {
+  return typeof value === "string" && value.length > 0 && !path.isAbsolute(value)
+    && !value.split(/[\\/]+/).includes("..") && !/[%\0-\x1f\x7f]/.test(value);
+}
+function pathWithinPrefix(value, prefix) {
+  const normalizedValue = value.replace(/\\/g, "/");
+  const normalizedPrefix = prefix.replace(/\\/g, "/");
+  return normalizedValue === normalizedPrefix
+    || (normalizedPrefix.endsWith("/") && normalizedValue.startsWith(normalizedPrefix));
+}
+function immutableGuards(task, currentResource) {
+  if (!task || typeof task !== "object" || !currentResource || typeof currentResource !== "object" || !Array.isArray(task.operations) || !task.operations.length) throw policyError("unsafe_task");
+  if (currentResource.real_path && currentResource.root_path) {
+    const rootInput = path.resolve(currentResource.root_path);
+    const realInput = path.resolve(currentResource.real_path);
+    const root = fs.existsSync(rootInput) ? fs.realpathSync.native(rootInput) : rootInput;
+    const real = fs.existsSync(realInput) ? fs.realpathSync.native(realInput) : realInput;
+    if (real !== root && !real.startsWith(root + path.sep)) throw policyError("unsafe_task_symlink_escape");
+  }
+  for (const operation of task.operations) {
+    if (!operation || !OPERATIONS.has(operation.operation) || !safeRelative(operation.path)) throw policyError("unsafe_task_operation");
+    const normalized = operation.path.replace(/\\/g, "/");
+    if (SENSITIVE_PATHS.test(normalized) || EXECUTABLE_PATHS.test(normalized)) throw policyError("unsafe_task_sensitive_path");
+    const value = operation.value == null ? "" : operation.value;
+    if (typeof value !== "string") throw policyError("unsafe_task_payload");
+    if (Buffer.byteLength(value, "utf8") > MAX_BYTES || SECRET_CONTENT.test(value) || /^\s*(?:#!.*(?:sh|bash|node|python)|(?:powershell|cmd\.exe)\b)/im.test(value)) throw policyError("unsafe_task_payload");
+    if (normalized === "robots.txt" && /^\s*Disallow:\s*\/\s*$/im.test(value)) throw policyError("unsafe_task_robots_global_disallow");
+    if (operation.expected_hash !== currentResource.sha256) throw policyError("unsafe_task_stale_hash");
+  }
+}
+function authorizeTask(policy, task, currentResource) {
+  immutableGuards(task, currentResource);
+  if (!policy || policy.default !== "deny" || policy.digest !== digest(policy) || task.policy_digest !== policy.digest) throw policyError("policy_denied");
+  const resource = task.resource;
+  if (!resource || task.connector !== currentResource.connector || task.environment !== currentResource.environment || resource.resource_type !== currentResource.resource_type || resource.resource_id !== currentResource.resource_id || resource.path !== currentResource.path) throw policyError("policy_denied");
+  const rule = policy.rules.find((item) => item.connector === task.connector && item.environment === task.environment && item.resource_type === resource.resource_type && item.resource_id === resource.resource_id && pathWithinPrefix(resource.path, item.path_prefix));
+  if (!rule || !validRule(rule)) throw policyError("policy_denied");
+  for (const operation of task.operations) {
+    if (!rule.allowed_operations.includes(operation.operation) || !pathWithinPrefix(operation.path, rule.path_prefix) || Buffer.byteLength(operation.value || "", "utf8") > rule.max_bytes) throw policyError("policy_denied");
+  }
+  return { authorized: true, policy_version: policy.version, policy_digest: policy.digest, rule_version: rule.version, approval_mode: rule.approval_mode };
+}
+
+module.exports = { POLICY_SCHEMA, initializeLocalPolicy, loadLocalPolicy, approvePolicyRule, authorizeTask };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@twin3-ai/agent-id",
+  "version": "0.1.0",
+  "description": "Domain-bound Agent identity, AEO evidence, and website-Agent integration SDK.",
+  "license": "UNLICENSED",
+  "private": false,
+  "files": [
+    "bin",
+    "*.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20",
+    "npm": ">=10"
+  },
+  "scripts": {
+    "prepublishOnly": "node --check bin/agent-id.js && node --check installer.js && node --check enterprise-identity.js && node --check release-verifier.js && node --check production-preflight.js"
+  },
+  "main": "site-agent.js",
+  "exports": {
+    ".": "./site-agent.js",
+    "./site-agent": "./site-agent.js",
+    "./runtime-config": "./runtime-config.js",
+    "./browser-sdk": "./browser-sdk.js",
+    "./sync-service": "./sync-service.js",
+    "./installer": "./installer.js",
+    "./enterprise-identity": "./enterprise-identity.js",
+    "./domain-proof": "./domain-proof.js",
+    "./local-policy": "./local-policy.js",
+    "./task-executor": "./task-executor.js",
+    "./telemetry-collector": "./telemetry-collector.js",
+    "./trust-verifier": "./trust-verifier.js",
+    "./repository-connector": "./repository-connector.js",
+    "./cloudflare-worker-adapter": "./cloudflare-worker-adapter.js",
+    "./release-verifier": "./release-verifier.js",
+    "./production-preflight": "./production-preflight.js"
+  },
+  "bin": {
+    "agent-id": "bin/agent-id.js",
+    "agent-id-sync": "bin/agent-id-sync.js"
+  }
+}

package/production-preflight.js

@@ -0,0 +1,123 @@
+"use strict";
+
+const net = require("node:net");
+const { verifyReleaseManifest } = require("./release-verifier.js");
+
+const PACKAGE_NAME = "@twin3-ai/agent-id";
+
+function stableProductionOrigin(value) {
+  try {
+    const parsed = new URL(String(value || ""));
+    const host = parsed.hostname.toLowerCase().replace(/\.$/, "");
+    if (parsed.protocol !== "https:" || parsed.username || parsed.password || parsed.port || parsed.pathname !== "/" || parsed.search || parsed.hash) return "";
+    if (!host.includes(".") || net.isIP(host)) return "";
+    if (host === "localhost" || host.endsWith(".local") || host.endsWith(".internal") || host.endsWith(".test") || host.endsWith(".invalid") || host.endsWith(".example")) return "";
+    if (host.endsWith(".run.app") || host.endsWith(".a.run.app") || host.endsWith(".appspot.com")) return "";
+    return `https://${host}`;
+  } catch (_error) {
+    return "";
+  }
+}
+
+async function fetchJson(fetchImpl, url) {
+  try {
+    const response = await fetchImpl(url, { headers: { accept: "application/json" } });
+    const text = await response.text();
+    let body = null;
+    try { body = JSON.parse(text); } catch (_error) { body = null; }
+    return { ok: response.ok, status: response.status, body };
+  } catch (error) {
+    return { ok: false, status: 0, body: null, error: String(error && error.message || error) };
+  }
+}
+
+async function runProductionPreflight({ endpoint, packageVersion, expectedIssuerKeySha256, fetchImpl = fetch }) {
+  const origin = stableProductionOrigin(endpoint);
+  if (!origin) {
+    return {
+      ok: false,
+      schema: "agentx-production-preflight-v1",
+      endpoint: String(endpoint || ""),
+      package: `${PACKAGE_NAME}@${String(packageVersion || "")}`,
+      checks: {
+        stable_api_origin_format: false,
+        api_https_reachable: false,
+        stable_api_origin: false,
+      },
+      blockers: ["stable_api_origin_required"],
+    };
+  }
+
+  const packageId = encodeURIComponent(PACKAGE_NAME);
+  const version = String(packageVersion || "");
+  const [manifestResponse, issuerResponse, registryResponse, healthResponse, cardResponse] = await Promise.all([
+    fetchJson(fetchImpl, `${origin}/.well-known/agent-id-release.json`),
+    fetchJson(fetchImpl, `${origin}/.well-known/agentx-issuer-key.json`),
+    fetchJson(fetchImpl, `https://registry.npmjs.org/${packageId}/${encodeURIComponent(version)}`),
+    fetchJson(fetchImpl, `${origin}/agent/health.json`),
+    fetchJson(fetchImpl, `${origin}/.well-known/agent-card.json`),
+  ]);
+
+  const manifest = manifestResponse.body;
+  const registry = registryResponse.body;
+  const release = manifestResponse.ok && manifest
+    ? verifyReleaseManifest({
+      manifest,
+      issuerDescriptor: issuerResponse.body,
+      expectedOrigin: origin,
+      packageVersion: version,
+      expectedIssuerKeySha256,
+    })
+    : {
+      ok: false,
+      signature_verified: false,
+      blockers: Array.isArray(manifest?.blockers) ? manifest.blockers : [],
+    };
+  const registryIdentity = registryResponse.ok && registry?.name === PACKAGE_NAME && registry?.version === version;
+  const registryIntegrity = registryIdentity
+    && typeof registry?.dist?.integrity === "string"
+    && registry.dist.integrity === manifest?.package?.integrity;
+  const health = healthResponse.ok && healthResponse.body && healthResponse.body.ok !== false;
+  const agentCard = cardResponse.ok && typeof cardResponse.body?.name === "string" && cardResponse.body.name.length > 0;
+  const apiReachable = [manifestResponse, issuerResponse, healthResponse, cardResponse]
+    .some(response => Number(response.status) > 0);
+  const checks = {
+    stable_api_origin_format: true,
+    api_https_reachable: apiReachable,
+    stable_api_origin: apiReachable,
+    release_manifest_http: manifestResponse.ok,
+    issuer_descriptor_http: issuerResponse.ok,
+    release_signature: release.signature_verified === true,
+    release_contract: release.ok === true,
+    npm_package_identity: registryIdentity,
+    registry_integrity: registryIntegrity,
+    health_endpoint: health,
+    agent_card: agentCard,
+  };
+  const blockers = [...release.blockers];
+  if (!apiReachable) blockers.push("stable_api_unreachable");
+  if (apiReachable && !manifestResponse.ok) blockers.push("release_manifest_unavailable");
+  if (apiReachable && !issuerResponse.ok) blockers.push("issuer_descriptor_unavailable");
+  if (!registryIdentity) blockers.push("npm_package_unpublished_or_version_mismatch");
+  if (manifestResponse.ok && registryIdentity && !registryIntegrity) blockers.push("npm_integrity_mismatch");
+  if (apiReachable && !health) blockers.push("health_endpoint_unavailable");
+  if (apiReachable && !agentCard) blockers.push("agent_card_unavailable");
+
+  return {
+    ok: blockers.length === 0,
+    schema: "agentx-production-preflight-v1",
+    endpoint: origin,
+    package: `${PACKAGE_NAME}@${version}`,
+    checks,
+    blockers: [...new Set(blockers)],
+    install_template: `npm exec --yes --package=${PACKAGE_NAME}@${version} -- agent-id install https://customer.example --apply`,
+    release: {
+      commit: manifest?.release_commit || "",
+      published_at: manifest?.published_at || "",
+      integrity: manifest?.package?.integrity || "",
+      signature_verified: release.signature_verified === true,
+    },
+  };
+}
+
+module.exports = { runProductionPreflight, stableProductionOrigin };

package/release-verifier.js

@@ -0,0 +1,83 @@
+"use strict";
+
+const crypto = require("node:crypto");
+
+const SCHEMA = "agentx-release-manifest-v1";
+const PACKAGE_NAME = "@twin3-ai/agent-id";
+
+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 JSON.stringify(stableValue(value));
+}
+
+function sha256(value) {
+  return `sha256:${crypto.createHash("sha256").update(canonical(value)).digest("hex")}`;
+}
+
+function normalizedOrigin(value) {
+  try {
+    const parsed = new URL(String(value || ""));
+    if (parsed.protocol !== "https:" || parsed.username || parsed.password || parsed.port || parsed.pathname !== "/" || parsed.search || parsed.hash) return "";
+    return parsed.origin.toLowerCase();
+  } catch (_error) {
+    return "";
+  }
+}
+
+function decodeProof(value) {
+  const raw = String(value || "").replace(/^base64url:/, "");
+  return Buffer.from(raw, "base64url");
+}
+
+function verifyReleaseManifest({ manifest, issuerDescriptor, expectedOrigin, packageVersion, expectedIssuerKeySha256 }) {
+  const blockers = [];
+  const expected = normalizedOrigin(expectedOrigin);
+  if (!manifest || manifest.schema !== SCHEMA) blockers.push("invalid_release_manifest_schema");
+  if (!manifest || manifest.ready !== true) blockers.push(...(Array.isArray(manifest && manifest.blockers) ? manifest.blockers : ["release_not_ready"]));
+  if (!expected || normalizedOrigin(manifest && manifest.api_origin) !== expected) blockers.push("api_origin_mismatch");
+  if (!manifest || manifest.package?.name !== PACKAGE_NAME) blockers.push("package_name_mismatch");
+  if (!manifest || manifest.package?.version !== String(packageVersion || "")) blockers.push("package_version_mismatch");
+  if (!/^sha512-[A-Za-z0-9+/=]{80,120}$/.test(String(manifest?.package?.integrity || ""))) blockers.push("npm_integrity_missing");
+  const expectedVersionUrl = `https://www.npmjs.com/package/${PACKAGE_NAME}/v/${String(packageVersion || "")}`;
+  if (manifest?.package?.version_url !== expectedVersionUrl) blockers.push("npm_version_url_mismatch");
+  if (manifest?.supply_chain?.npm_provenance !== "not_claimed_private_repository") blockers.push("npm_provenance_claim_mismatch");
+
+  const proof = manifest && typeof manifest.proof === "object" ? manifest.proof : {};
+  const unsigned = manifest && typeof manifest === "object"
+    ? Object.fromEntries(Object.entries(manifest).filter(([key]) => !["proof", "content_hash"].includes(key)))
+    : {};
+  if (manifest?.content_hash !== sha256(unsigned)) blockers.push("manifest_content_hash_mismatch");
+  if (proof.verification_method !== `${expected}/.well-known/agentx-issuer-key.json#ed25519-2026`) blockers.push("verification_method_mismatch");
+
+  let signatureVerified = false;
+  const publicKey = String(issuerDescriptor?.public_key_pem || "");
+  if (!publicKey) {
+    blockers.push("issuer_public_key_missing");
+  } else {
+    const issuerKeySha256 = `sha256:${crypto.createHash("sha256").update(publicKey).digest("hex")}`;
+    if (!expectedIssuerKeySha256 || issuerKeySha256 !== expectedIssuerKeySha256) blockers.push("issuer_key_pin_mismatch");
+    if (manifest?.authority?.issuer_key_sha256 !== issuerKeySha256) blockers.push("manifest_issuer_key_mismatch");
+    try {
+      signatureVerified = crypto.verify(null, Buffer.from(canonical(unsigned)), crypto.createPublicKey(publicKey), decodeProof(proof.proof_value));
+    } catch (_error) {
+      signatureVerified = false;
+    }
+    if (!signatureVerified) blockers.push("release_signature_invalid");
+  }
+
+  return {
+    ok: blockers.length === 0,
+    signature_verified: signatureVerified,
+    expected_origin: expected,
+    expected_package: `${PACKAGE_NAME}@${String(packageVersion || "")}`,
+    expected_issuer_key_sha256: String(expectedIssuerKeySha256 || ""),
+    blockers: [...new Set(blockers)],
+  };
+}
+
+module.exports = { verifyReleaseManifest };