@twin3-ai/agent-id 0.1.0

package/repository-connector.js

@@ -0,0 +1,306 @@
+"use strict";
+
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const ALLOWED_PATHS = new Set([
+  "llms.txt",
+  "robots.txt",
+  ".well-known/agent-card.json",
+  ".well-known/agent-id.json",
+  ".well-known/aeo-agent.json",
+  ".well-known/agent-knowledge.json"
+]);
+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-----/,
+  /AGENT_ID_RUNTIME_EVIDENCE_SECRET\s*[:=]/,
+  /(?:SITE_AGENT_KEY|AEO_AGENT_KEY)\s*[:=]\s*["'][^"']+["']/
+];
+
+function connectorError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function rootPath(value = process.cwd()) {
+  const root = path.resolve(String(value));
+  if (!path.isAbsolute(root)) throw connectorError("CONNECTOR_INVALID_ROOT", "Repository root must be absolute.");
+  return root;
+}
+
+function normalizeRelativePath(value) {
+  const relative = String(value || "").replace(/\\/g, "/").replace(/^\.\//, "");
+  if (!ALLOWED_PATHS.has(relative)) throw connectorError("CONNECTOR_PATH_NOT_ALLOWED", `Path is not on the connector allowlist: ${relative}`);
+  return relative;
+}
+async function safeAbsolute(root, relative) {
+  const normalized = normalizeRelativePath(relative);
+  const absolute = path.resolve(root, normalized);
+  const realRoot = await fs.realpath(root);
+  const parent = await fs.realpath(path.dirname(absolute)).catch((error) => {
+    if (error.code === "ENOENT") return path.resolve(realRoot, path.dirname(normalized));
+    throw error;
+  });
+  if (parent !== realRoot && !parent.startsWith(realRoot + path.sep)) throw connectorError("CONNECTOR_PATH_ESCAPE", "Connector path leaves repository root.");
+  const metadata = await fs.lstat(absolute).catch((error) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  if (metadata && metadata.isSymbolicLink()) throw connectorError("CONNECTOR_SYMLINK_REJECTED", "Connector refuses symlink resources.");
+  return absolute;
+}
+
+function hashText(value) {
+  return `sha256:${crypto.createHash("sha256").update(value).digest("hex")}`;
+}
+
+function assertSafeContent(content) {
+  if (typeof content !== "string") throw connectorError("CONNECTOR_INVALID_CONTENT", "Connector content must be text.");
+  if (Buffer.byteLength(content, "utf8") > 1024 * 1024) throw connectorError("CONNECTOR_CONTENT_TOO_LARGE", "Connector content is limited to 1 MiB per file.");
+  if (SECRET_PATTERNS.some((pattern) => pattern.test(content))) throw connectorError("CONNECTOR_SECRET_DETECTED", "Connector content contains a credential-like value and was rejected.");
+}
+
+async function readText(filePath) {
+  try { return await fs.readFile(filePath, "utf8"); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+function lineDiff(relative, before, after) {
+  const oldLines = before == null ? [] : before.split(/(?<=\n)/);
+  const newLines = after.split(/(?<=\n)/);
+  const rows = [`--- a/${relative}`, `+++ b/${relative}`, "@@"];
+  for (const line of oldLines) rows.push(`-${line.replace(/\n$/, "")}`);
+  for (const line of newLines) rows.push(`+${line.replace(/\n$/, "")}`);
+  return rows.join("\n");
+}
+
+async function buildRepositoryPatch({ repositoryRoot = process.cwd(), changes = [] } = {}) {
+  const root = rootPath(repositoryRoot);
+  if (!Array.isArray(changes) || changes.length === 0) throw connectorError("CONNECTOR_CHANGES_REQUIRED", "At least one allowlisted change is required.");
+  const seen = new Set();
+  const normalized = [];
+  for (const change of changes) {
+    const relative = normalizeRelativePath(change && change.path);
+    if (seen.has(relative)) throw connectorError("CONNECTOR_DUPLICATE_PATH", `Path appears more than once: ${relative}`);
+    seen.add(relative);
+    assertSafeContent(change.content);
+    const absolute = await safeAbsolute(root, relative);
+    const before = await readText(absolute);
+    const after = change.content;
+    const beforeHash = before == null ? "" : hashText(before);
+    const afterHash = hashText(after);
+    normalized.push({
+      path: relative,
+      operation: before == null ? "add" : before === after ? "noop" : "update",
+      reason: String(change.reason || "").slice(0, 240),
+      before_sha256: beforeHash,
+      after_sha256: afterHash,
+      after_content: after,
+      diff: before === after ? `--- a/${relative}\n+++ b/${relative}\n@@\n(no change)` : lineDiff(relative, before, after)
+    });
+  }
+  const material = JSON.stringify({ root, changes: normalized.map(({ after_content, ...item }) => item) });
+  return {
+    schema: "agentx-repository-patch-plan-v1",
+    connector: "repository_patch",
+    status: "pending_approval",
+    repository_root: root,
+    approval_required: true,
+    default_branch_push: false,
+    prohibited_paths: ["package.json", ".env", "secrets", "pricing", "legal", "checkout", "database"],
+    plan_id: hashText(material).slice(0, 24),
+    changes: normalized
+  };
+}
+
+function deploymentChanges({ implementationBundle, knowledgePack } = {}) {
+  if (!implementationBundle || implementationBundle.schema !== "agentx-f1-implementation-bundle-v0.1") {
+    throw connectorError("CONNECTOR_INVALID_BUNDLE", "A valid F1 implementation bundle is required.");
+  }
+  const changes = [];
+  for (const file of implementationBundle.files || []) {
+    const relative = normalizeRelativePath(String(file && file.path || "").replace(/^\//, ""));
+    assertSafeContent(file && file.content);
+    changes.push({
+      path: relative,
+      content: file.content,
+      content_type: String(file.content_type || "text/plain").slice(0, 120),
+      reason: String(file.purpose || "Publish Agent-readable website asset").slice(0, 240)
+    });
+  }
+  if (knowledgePack != null) {
+    if (!knowledgePack || knowledgePack.schema !== "agentx-knowledge-pack-v1") {
+      throw connectorError("CONNECTOR_INVALID_KNOWLEDGE_PACK", "A valid Agent Knowledge Pack is required.");
+    }
+    const content = JSON.stringify(knowledgePack, null, 2) + "\n";
+    assertSafeContent(content);
+    changes.push({
+      path: ".well-known/agent-knowledge.json",
+      content,
+      content_type: "application/json; charset=utf-8",
+      reason: "Publish observed Agent Knowledge Pack"
+    });
+  }
+  if (!changes.length) throw connectorError("CONNECTOR_CHANGES_REQUIRED", "The implementation bundle contains no deployable files.");
+  return changes;
+}
+
+async function buildImplementationPatch({ repositoryRoot = process.cwd(), implementationBundle, knowledgePack } = {}) {
+  return buildRepositoryPatch({
+    repositoryRoot,
+    changes: deploymentChanges({ implementationBundle, knowledgePack })
+  });
+}
+
+function validatePlan(plan, expectedRoot) {
+  if (!plan || plan.schema !== "agentx-repository-patch-plan-v1" || plan.approval_required !== true) throw connectorError("CONNECTOR_INVALID_PLAN", "Invalid repository patch plan.");
+  const root = rootPath(plan.repository_root);
+  if (expectedRoot && root !== rootPath(expectedRoot)) throw connectorError("CONNECTOR_ROOT_MISMATCH", "Repository root does not match the patch plan.");
+  for (const change of plan.changes || []) {
+    normalizeRelativePath(change.path);
+    assertSafeContent(change.after_content);
+  }
+  return root;
+}
+
+async function writeAtomic(filePath, content) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const temporary = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temporary, content, { encoding: "utf8", mode: 0o644 });
+    await fs.rename(temporary, filePath);
+  } finally {
+    await fs.rm(temporary, { force: true }).catch(() => {});
+  }
+}
+
+async function applyRepositoryPatch(plan, { approved = false } = {}) {
+  const root = validatePlan(plan);
+  if (approved !== true) throw connectorError("CONNECTOR_APPROVAL_REQUIRED", "Connector application requires explicit approved=true.");
+  const rollbackEntries = [];
+  const appliedChanges = [];
+  for (const change of plan.changes) {
+    const absolute = await safeAbsolute(root, change.path);
+    const current = await readText(absolute);
+    const currentHash = current == null ? "" : hashText(current);
+    if (currentHash !== change.before_sha256) throw connectorError("CONNECTOR_STALE_PLAN", `Repository changed since the plan was created: ${change.path}`);
+    rollbackEntries.push({ path: change.path, before_sha256: change.before_sha256, before_content: current, after_sha256: change.after_sha256 });
+  }
+  try {
+    for (const change of plan.changes) {
+      const absolute = await safeAbsolute(root, change.path);
+    if (change.operation !== "noop") {
+      await writeAtomic(absolute, change.after_content);
+      const verified = await readText(absolute);
+      if (verified == null || hashText(verified) !== change.after_sha256) throw connectorError("CONNECTOR_VERIFY_FAILED", `Post-write verification failed: ${change.path}`);
+    }
+    appliedChanges.push({ path: change.path, operation: change.operation, after_sha256: change.after_sha256 });
+    }
+  } catch (error) {
+    for (const item of rollbackEntries.slice(0, appliedChanges.length + 1).reverse()) {
+      const absolute = await safeAbsolute(root, item.path);
+      if (item.before_sha256) await writeAtomic(absolute, item.before_content);
+      else await fs.rm(absolute, { force: true });
+    }
+    throw error;
+  }
+  const receipt = {
+    schema: "agentx-repository-patch-receipt-v1",
+    connector: "repository_patch",
+    plan_id: plan.plan_id,
+    repository_root: root,
+    applied: true,
+    default_branch_push: false,
+    applied_changes: appliedChanges,
+    rollback_entries: rollbackEntries
+  };
+  const receiptPath = path.join(root, ".agent-id", "repository-patch-receipt.json");
+  await writeAtomic(receiptPath, JSON.stringify({ ...receipt, rollback_entries: rollbackEntries }, null, 2) + "\n");
+  return receipt;
+}
+
+async function rollbackRepositoryPatch(receiptOrRoot, { approved = false } = {}) {
+  if (approved !== true) throw connectorError("CONNECTOR_APPROVAL_REQUIRED", "Rollback requires explicit approved=true.");
+  const rootHint = typeof receiptOrRoot === "string" ? rootPath(receiptOrRoot) : "";
+  let receipt = typeof receiptOrRoot === "string" ? await (async () => {
+    const parsed = JSON.parse(await fs.readFile(path.join(rootHint, ".agent-id", "repository-patch-receipt.json"), "utf8"));
+    return parsed;
+  })() : receiptOrRoot;
+  if (!receipt || receipt.schema !== "agentx-repository-patch-receipt-v1") throw connectorError("CONNECTOR_INVALID_RECEIPT", "Invalid repository patch receipt.");
+  const root = rootPath(receipt.repository_root);
+  for (const item of receipt.rollback_entries || []) {
+    normalizeRelativePath(item.path);
+    if (item.before_sha256 && typeof item.before_content !== "string") throw connectorError("CONNECTOR_INVALID_RECEIPT", `Rollback content is missing for ${item.path}`);
+    if (item.before_sha256) assertSafeContent(item.before_content);
+  }
+  const restored = [];
+  for (const item of receipt.rollback_entries || []) {
+    const relative = normalizeRelativePath(item.path);
+    const absolute = await safeAbsolute(root, relative);
+    const current = await readText(absolute);
+    const currentHash = current == null ? "" : hashText(current);
+    if (currentHash !== item.after_sha256) throw connectorError("CONNECTOR_ROLLBACK_CONFLICT", `Repository changed after the patch: ${relative}`);
+    if (item.before_sha256) await writeAtomic(absolute, item.before_content);
+    else await fs.rm(absolute, { force: true });
+    restored.push({ path: relative, before_sha256: item.before_sha256 });
+  }
+  return { schema: "agentx-repository-rollback-receipt-v1", connector: "repository_patch", plan_id: receipt.plan_id || "", rolled_back: true, files: restored };
+}
+
+module.exports = {
+  ALLOWED_PATHS,
+  buildRepositoryPatch,
+  buildImplementationPatch,
+  deploymentChanges,
+  applyRepositoryPatch,
+  rollbackRepositoryPatch,
+  createRepositoryConnector
+};
+
+function createRepositoryConnector({ repositoryRoot = process.cwd() } = {}) {
+  const root = rootPath(repositoryRoot);
+  return Object.freeze({
+    describeCapabilities() {
+      return { connector: "repository_patch", operations: ["upsert", "replace"], paths: [...ALLOWED_PATHS].sort(), approval_required: true };
+    },
+    async readResource(resource) {
+      const relative = normalizeRelativePath(resource && resource.path);
+      const absolute = await safeAbsolute(root, relative);
+      const content = await readText(absolute);
+      return {
+        connector: "repository_patch",
+        environment: String(resource.environment || "production"),
+        resource_type: String(resource.resource_type || "file"),
+        resource_id: String(resource.resource_id || relative),
+        path: relative,
+        root_path: root,
+        real_path: absolute,
+        content,
+        sha256: content == null ? "" : hashText(content)
+      };
+    },
+    async planOperations(task, currentResource) {
+      const changes = task.operations.map((operation) => {
+        if (!["upsert", "replace"].includes(operation.operation)) throw connectorError("CONNECTOR_OPERATION_NOT_SUPPORTED", "Repository connector supports upsert and replace.");
+        return { path: operation.path, content: operation.value, reason: `Enterprise task ${task.task_id}` };
+      });
+      const plan = await buildRepositoryPatch({ repositoryRoot: root, changes });
+      if (plan.changes.some((change) => change.before_sha256 !== currentResource.sha256)) throw connectorError("CONNECTOR_STALE_PLAN", "Task expected hash does not match the current resource.");
+      return plan;
+    },
+    applyOperations(plan) { return applyRepositoryPatch(plan, { approved: true }); },
+    async verifyLocalResult(receipt) {
+      for (const item of receipt.applied_changes || []) {
+        const content = await readText(await safeAbsolute(root, item.path));
+        if (content == null || hashText(content) !== item.after_sha256) throw connectorError("CONNECTOR_VERIFY_FAILED", `Verification failed: ${item.path}`);
+      }
+      return { verified: true };
+    },
+    rollback(receipt) { return rollbackRepositoryPatch(receipt || root, { approved: true }); }
+  });
+}

package/runtime-config.js

@@ -0,0 +1,10 @@
+"use strict";
+
+const DEFAULT_ENDPOINT = "https://api.agentid.twin3.ai";
+const TRUSTED_ISSUER_KEY_SHA256 = "sha256:f1dd1844319a02a8ec3c32552ed730fdda286e733cf6b5d54029ec7bd59fda1a";
+
+function configuredEndpoint(env = process.env) {
+  return String(env.AGENT_ID_ENDPOINT || env.AEO_AGENT_ENDPOINT || DEFAULT_ENDPOINT).replace(/\/+$/, "");
+}
+
+module.exports = { DEFAULT_ENDPOINT, TRUSTED_ISSUER_KEY_SHA256, configuredEndpoint };