@agentlayer.tech/wallet 0.1.100 → 0.1.102

package/connectors/conformance/README.md

@@ -0,0 +1,31 @@
+# AgentLayer connector conformance
+
+Run Protocol v1 contract checks against a deployed read-only connector:
+
+```bash
+npx @agentlayer.tech/connector-conformance@beta \
+  --manifest ./connector.json \
+  --fixture ./conformance.json \
+  --endpoint https://your-connector.up.railway.app
+```
+
+The suite validates the official manifest schema, fixture coverage, health
+identity, every declared read tool's input/output schemas, response binding and
+expiry, and rejection of wrong identities and undeclared tools.
+
+Example fixture:
+
+```json
+{
+  "schema_version": 1,
+  "tools": {
+    "get_pools": {
+      "arguments": { "chain": "base", "limit": 10 }
+    }
+  }
+}
+```
+
+Run conformance against the final immutable deployment URL before publishing a
+manifest. A passing report is required for review, but it does not grant
+`verified_write` status.

package/connectors/conformance/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@agentlayer.tech/connector-conformance",
+  "version": "0.1.0-beta.1",
+  "description": "Conformance runner for AgentLayer Connector Protocol v1.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lopushok9/Agent-Layer.git",
+    "directory": "connectors/conformance"
+  },
+  "homepage": "https://github.com/lopushok9/Agent-Layer/tree/main/connectors/conformance#readme",
+  "bugs": {
+    "url": "https://github.com/lopushok9/Agent-Layer/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "agentlayer-connector-conformance": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "spec/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "sync-license": "node scripts/sync-license.mjs",
+    "sync-spec": "node scripts/sync-spec.mjs",
+    "build": "npm run sync-spec && tsc -p tsconfig.json",
+    "check": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run sync-license && npm run build"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1"
+  },
+  "devDependencies": {
+    "@agentlayer.tech/connector-sdk": "0.1.0-beta.1",
+    "@types/node": "^24.0.0",
+    "typescript": "^7.0.2"
+  }
+}

package/connectors/conformance/scripts/sync-license.mjs

@@ -0,0 +1,3 @@
+import { copyFileSync } from "node:fs";
+
+copyFileSync(new URL("../../../LICENSE", import.meta.url), new URL("../LICENSE", import.meta.url));

package/connectors/conformance/scripts/sync-spec.mjs

@@ -0,0 +1,16 @@
+import { cp, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const source = path.resolve(packageRoot, "..", "spec");
+const destination = path.join(packageRoot, "spec");
+
+await mkdir(destination, { recursive: true });
+for (const name of [
+  "connector-manifest.schema.json",
+  "connector-protocol.md",
+  "transaction-intent.schema.json",
+]) {
+  await cp(path.join(source, name), path.join(destination, name));
+}

package/connectors/conformance/src/cli.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { assertFixture, runConformance } from "./index.js";
+
+function valueAfter(args: string[], flag: string): string | undefined {
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+async function readJson(file: string): Promise<unknown> {
+  return JSON.parse(await readFile(path.resolve(file), "utf8"));
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const manifestPath = valueAfter(args, "--manifest");
+  const fixturePath = valueAfter(args, "--fixture");
+  const endpoint = valueAfter(args, "--endpoint");
+  if (!manifestPath || !fixturePath) {
+    throw new Error("Usage: agentlayer-connector-conformance --manifest connector.json --fixture conformance.json [--endpoint URL]");
+  }
+  const manifest = await readJson(manifestPath);
+  const fixture = await readJson(fixturePath);
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    throw new Error("Manifest root must be an object.");
+  }
+  assertFixture(fixture);
+  const report = await runConformance({
+    manifest: manifest as Record<string, unknown>,
+    fixture,
+    ...(endpoint ? { endpoint } : {}),
+  });
+  console.log(JSON.stringify(report, null, 2));
+  process.exitCode = report.ok ? 0 : 1;
+}
+
+main().catch((error) => {
+  console.error(JSON.stringify({ ok: false, error: String(error instanceof Error ? error.message : error) }));
+  process.exitCode = 2;
+});

package/connectors/conformance/src/index.ts

@@ -0,0 +1,7 @@
+export { assertFixture, runConformance } from "./runner.js";
+export type {
+  ConformanceCheck,
+  ConformanceFixture,
+  ConformanceOptions,
+  ConformanceReport,
+} from "./types.js";

package/connectors/conformance/src/runner.ts

@@ -0,0 +1,314 @@
+import { readFile } from "node:fs/promises";
+
+import { createRequire } from "node:module";
+import { Ajv2020, type ValidateFunction } from "ajv/dist/2020.js";
+import type { FormatsPlugin } from "ajv-formats";
+
+import type {
+  ConformanceCheck,
+  ConformanceFixture,
+  ConformanceOptions,
+  ConformanceReport,
+} from "./types.js";
+
+const require = createRequire(import.meta.url);
+const addFormats = require("ajv-formats") as FormatsPlugin;
+const MAX_RESPONSE_TTL_MS = 300_000;
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+const RESERVED_WRITE_RESULT_KEYS = new Set([
+  "approval_token",
+  "broadcast_request",
+  "evm_transaction_intent",
+  "payment_intent",
+  "raw_transaction",
+  "signed_transaction",
+  "signing_request",
+  "solana_transaction_intent",
+  "transaction_intent",
+]);
+
+function object(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+async function readJsonResponse(response: Response): Promise<unknown> {
+  const contentType = String(response.headers.get("content-type") ?? "").toLowerCase();
+  if (!contentType.startsWith("application/json")) {
+    throw new Error("Response Content-Type must be application/json.");
+  }
+  const contentLength = Number(response.headers.get("content-length") ?? 0);
+  if (Number.isFinite(contentLength) && contentLength > MAX_RESPONSE_BYTES) {
+    throw new Error("Response exceeds the 1 MiB protocol limit.");
+  }
+  if (!response.body) throw new Error("Response body is missing.");
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > MAX_RESPONSE_BYTES) {
+      await reader.cancel();
+      throw new Error("Response exceeds the 1 MiB protocol limit.");
+    }
+    chunks.push(value);
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    throw new Error("Response body is not valid JSON.");
+  }
+}
+
+async function defaultManifestSchema(): Promise<Record<string, unknown>> {
+  const url = new URL("../spec/connector-manifest.schema.json", import.meta.url);
+  return JSON.parse(await readFile(url, "utf8")) as Record<string, unknown>;
+}
+
+function buildAjv(): Ajv2020 {
+  const ajv = new Ajv2020({ allErrors: true, strict: true });
+  addFormats(ajv);
+  return ajv;
+}
+
+function identity(manifest: Record<string, unknown>): Record<string, string> {
+  return {
+    id: String(manifest.id),
+    version: String(manifest.version),
+    ...(manifest.artifact_digest ? { artifact_digest: String(manifest.artifact_digest) } : {}),
+  };
+}
+
+function assertNoWritePayload(value: unknown): void {
+  const pending: unknown[] = [value];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (Array.isArray(current)) {
+      pending.push(...current);
+    } else if (current && typeof current === "object") {
+      for (const [key, item] of Object.entries(current)) {
+        if (RESERVED_WRITE_RESULT_KEYS.has(key.toLowerCase())) {
+          throw new Error(`Read result contains reserved write field: ${key}.`);
+        }
+        pending.push(item);
+      }
+    }
+  }
+}
+
+function checkResponseBinding(
+  payload: unknown,
+  manifest: Record<string, unknown>,
+  requestId: string,
+  toolName: string,
+  validateOutput: ValidateFunction
+): void {
+  const response = object(payload);
+  if (!response) throw new Error("Response root must be an object.");
+  if (response.protocol_version !== 1 || response.request_id !== requestId) {
+    throw new Error("Response protocol/request binding does not match.");
+  }
+  const responseIdentity = object(response.connector);
+  const expectedIdentity = identity(manifest);
+  if (
+    !responseIdentity ||
+    responseIdentity.id !== expectedIdentity.id ||
+    responseIdentity.version !== expectedIdentity.version ||
+    responseIdentity.artifact_digest !== expectedIdentity.artifact_digest
+  ) {
+    throw new Error("Response connector identity does not match.");
+  }
+  if (response.tool !== toolName || response.kind !== "read_result") {
+    throw new Error("Response tool or kind does not match the read request.");
+  }
+  const expiresAt = Date.parse(String(response.expires_at ?? ""));
+  const remaining = expiresAt - Date.now();
+  if (!Number.isFinite(expiresAt) || remaining <= 0 || remaining > MAX_RESPONSE_TTL_MS) {
+    throw new Error("Response expiry must be in the next 300 seconds.");
+  }
+  assertNoWritePayload(response.result);
+  if (!validateOutput(response.result)) {
+    throw new Error("Response result does not match the declared output_schema.");
+  }
+}
+
+async function post(
+  fetchImpl: typeof fetch,
+  endpoint: string,
+  payload: Record<string, unknown>,
+  timeoutMs: number
+): Promise<Response> {
+  return fetchImpl(`${endpoint}/invoke`, {
+    method: "POST",
+    headers: { accept: "application/json", "content-type": "application/json" },
+    body: JSON.stringify(payload),
+    redirect: "error",
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+}
+
+export async function runConformance(options: ConformanceOptions): Promise<ConformanceReport> {
+  const endpoint = String(
+    options.endpoint ?? object(options.manifest.transport)?.url ?? ""
+  ).replace(/\/$/, "");
+  let endpointUrl: URL;
+  try {
+    endpointUrl = new URL(endpoint);
+  } catch {
+    throw new Error("A connector endpoint URL is required.");
+  }
+  const localHttp =
+    endpointUrl.protocol === "http:" &&
+    ["127.0.0.1", "::1", "localhost"].includes(endpointUrl.hostname);
+  if (endpointUrl.protocol !== "https:" && !localHttp) {
+    throw new Error("Connector endpoints must use HTTPS; HTTP is allowed only for loopback tests.");
+  }
+  const timeoutMs = options.timeoutMs ?? 10_000;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const checks: ConformanceCheck[] = [];
+  const runCheck = async (name: string, callback: () => void | Promise<void>): Promise<void> => {
+    try {
+      await callback();
+      checks.push({ name, ok: true });
+    } catch (error) {
+      checks.push({ name, ok: false, error: String(error instanceof Error ? error.message : error) });
+    }
+  };
+
+  const ajv = buildAjv();
+  const manifestSchema = options.manifestSchema ?? (await defaultManifestSchema());
+  const validateManifest = ajv.compile(manifestSchema);
+  await runCheck("manifest_schema", () => {
+    if (!validateManifest(options.manifest)) throw new Error("Manifest does not match Protocol v1 schema.");
+  });
+
+  const tools = Array.isArray(options.manifest.tools)
+    ? options.manifest.tools.map(object).filter((tool): tool is Record<string, unknown> => tool !== null)
+    : [];
+  const readTools = tools.filter((tool) => tool.read_only === true);
+  await runCheck("fixture_coverage", () => {
+    const declared = new Set(readTools.map((tool) => String(tool.name)));
+    for (const name of declared) {
+      if (!object(options.fixture.tools?.[name])?.arguments) {
+        throw new Error(`Missing fixture arguments for ${name}.`);
+      }
+    }
+    for (const name of Object.keys(options.fixture.tools ?? {})) {
+      if (!declared.has(name)) throw new Error(`Fixture names an undeclared read tool: ${name}.`);
+    }
+  });
+
+  await runCheck("healthz", async () => {
+    const response = await fetchImpl(`${endpoint}/healthz`, {
+      headers: { accept: "application/json" },
+      redirect: "error",
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (response.status !== 200) throw new Error(`Health endpoint returned HTTP ${response.status}.`);
+    const payload = object(await readJsonResponse(response));
+    const connector = object(payload?.connector);
+    if (
+      payload?.ok !== true ||
+      connector?.id !== options.manifest.id ||
+      connector?.version !== options.manifest.version
+    ) {
+      throw new Error("Health endpoint identity does not match the manifest.");
+    }
+  });
+
+  for (const tool of readTools) {
+    const toolName = String(tool.name);
+    const fixture = options.fixture.tools[toolName];
+    if (!fixture) continue;
+    let validateInput: ValidateFunction;
+    let validateOutput: ValidateFunction;
+    try {
+      validateInput = ajv.compile(tool.input_schema as Record<string, unknown>);
+      validateOutput = ajv.compile(tool.output_schema as Record<string, unknown>);
+    } catch (error) {
+      checks.push({ name: `tool:${toolName}:schemas`, ok: false, error: String(error) });
+      continue;
+    }
+    await runCheck(`tool:${toolName}:invoke`, async () => {
+      if (!validateInput(fixture.arguments)) throw new Error("Fixture arguments violate input_schema.");
+      const requestId = `conformance-${toolName}-${Date.now()}`;
+      const response = await post(
+        fetchImpl,
+        endpoint,
+        {
+          protocol_version: 1,
+          request_id: requestId,
+          connector: identity(options.manifest),
+          tool: toolName,
+          arguments: fixture.arguments,
+          context: {},
+        },
+        timeoutMs
+      );
+      if (response.status !== 200) throw new Error(`Invoke returned HTTP ${response.status}.`);
+      checkResponseBinding(
+        await readJsonResponse(response),
+        options.manifest,
+        requestId,
+        toolName,
+        validateOutput
+      );
+    });
+  }
+
+  await runCheck("reject_wrong_identity", async () => {
+    const response = await post(
+      fetchImpl,
+      endpoint,
+      {
+        protocol_version: 1,
+        request_id: `conformance-wrong-id-${Date.now()}`,
+        connector: { id: "com.agentlayer.conformance.invalid", version: "0.0.0" },
+        tool: String(readTools[0]?.name ?? "unknown"),
+        arguments: options.fixture.tools[String(readTools[0]?.name ?? "")]?.arguments ?? {},
+        context: {},
+      },
+      timeoutMs
+    );
+    if (response.status >= 200 && response.status < 300) {
+      throw new Error("Connector accepted a request for a different identity.");
+    }
+  });
+
+  await runCheck("reject_unknown_tool", async () => {
+    const response = await post(
+      fetchImpl,
+      endpoint,
+      {
+        protocol_version: 1,
+        request_id: `conformance-unknown-tool-${Date.now()}`,
+        connector: identity(options.manifest),
+        tool: "__conformance_unknown_tool__",
+        arguments: {},
+        context: {},
+      },
+      timeoutMs
+    );
+    if (response.status >= 200 && response.status < 300) {
+      throw new Error("Connector accepted an undeclared tool.");
+    }
+  });
+
+  return {
+    ok: checks.every((check) => check.ok),
+    connector_id: String(options.manifest.id ?? ""),
+    connector_version: String(options.manifest.version ?? ""),
+    endpoint,
+    checks,
+  };
+}
+
+export function assertFixture(value: unknown): asserts value is ConformanceFixture {
+  const fixture = object(value);
+  if (fixture?.schema_version !== 1 || !object(fixture.tools)) {
+    throw new Error("Conformance fixture must use schema_version 1 and contain a tools object.");
+  }
+}

package/connectors/conformance/src/types.ts

@@ -0,0 +1,27 @@
+export interface ConformanceFixture {
+  schema_version: 1;
+  tools: Record<string, { arguments: Record<string, unknown> }>;
+}
+
+export interface ConformanceCheck {
+  name: string;
+  ok: boolean;
+  error?: string;
+}
+
+export interface ConformanceReport {
+  ok: boolean;
+  connector_id: string;
+  connector_version: string;
+  endpoint: string;
+  checks: ConformanceCheck[];
+}
+
+export interface ConformanceOptions {
+  manifest: Record<string, unknown>;
+  fixture: ConformanceFixture;
+  endpoint?: string;
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+  manifestSchema?: Record<string, unknown>;
+}

package/connectors/conformance/test/fixtures/invalid-response-identity.json

@@ -0,0 +1,14 @@
+{
+  "protocol_version": 1,
+  "request_id": "replaced-by-test",
+  "connector": {
+    "id": "com.attacker",
+    "version": "1.0.0"
+  },
+  "tool": "get_pools",
+  "kind": "read_result",
+  "result": {
+    "pools": []
+  },
+  "expires_at": "replaced-by-test"
+}

package/connectors/conformance/test/fixtures/missing-tool-fixture.json

@@ -0,0 +1,4 @@
+{
+  "schema_version": 1,
+  "tools": {}
+}

package/connectors/conformance/test/runner.test.mjs

@@ -0,0 +1,151 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import test from "node:test";
+
+import {
+  createConnectorHttpHandler,
+  defineReadOnlyConnector,
+} from "@agentlayer.tech/connector-sdk";
+import { runConformance } from "../dist/index.js";
+
+const manifest = JSON.parse(
+  await readFile(new URL("../../templates/read-only/connector.json", import.meta.url), "utf8")
+);
+const fixture = { schema_version: 1, tools: { get_pools: { arguments: { chain: "base" } } } };
+const invalidIdentityResponse = JSON.parse(
+  await readFile(new URL("./fixtures/invalid-response-identity.json", import.meta.url), "utf8")
+);
+const missingToolFixture = JSON.parse(
+  await readFile(new URL("./fixtures/missing-tool-fixture.json", import.meta.url), "utf8")
+);
+
+function response(status, payload) {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function conformingFetch(url, options = {}) {
+  if (String(url).endsWith("/healthz")) {
+    return Promise.resolve(
+      response(200, { ok: true, connector: { id: manifest.id, version: manifest.version } })
+    );
+  }
+  const request = JSON.parse(options.body);
+  if (request.connector.id !== manifest.id || request.tool === "__conformance_unknown_tool__") {
+    return Promise.resolve(response(409, { ok: false }));
+  }
+  return Promise.resolve(
+    response(200, {
+      protocol_version: 1,
+      request_id: request.request_id,
+      connector: request.connector,
+      tool: request.tool,
+      kind: "read_result",
+      result: { pools: [] },
+      expires_at: new Date(Date.now() + 60_000).toISOString(),
+    })
+  );
+}
+
+test("passes a conforming read-only endpoint", async () => {
+  const report = await runConformance({
+    manifest,
+    fixture,
+    endpoint: "https://connector.example.com",
+    fetchImpl: conformingFetch,
+  });
+  assert.equal(report.ok, true, JSON.stringify(report.checks));
+  assert.ok(report.checks.length >= 6);
+});
+
+test("rejects public plaintext HTTP endpoints", async () => {
+  await assert.rejects(
+    runConformance({
+      manifest,
+      fixture,
+      endpoint: "http://connector.example.com",
+      fetchImpl: conformingFetch,
+    }),
+    /must use HTTPS/
+  );
+});
+
+test("reports response identity drift", async () => {
+  const report = await runConformance({
+    manifest,
+    fixture,
+    endpoint: "https://connector.example.com",
+    fetchImpl: async (url, options = {}) => {
+      const result = await conformingFetch(url, options);
+      if (!String(url).endsWith("/invoke") || result.status !== 200) return result;
+      const payload = await result.json();
+      return response(200, {
+        ...invalidIdentityResponse,
+        request_id: payload.request_id,
+        expires_at: payload.expires_at,
+      });
+    },
+  });
+  assert.equal(report.ok, false);
+  assert.equal(report.checks.find((check) => check.name === "tool:get_pools:invoke")?.ok, false);
+});
+
+test("reports write envelopes embedded in read-only output", async () => {
+  const permissiveManifest = structuredClone(manifest);
+  permissiveManifest.tools[0].output_schema = { type: "object" };
+  const report = await runConformance({
+    manifest: permissiveManifest,
+    fixture,
+    endpoint: "https://connector.example.com",
+    fetchImpl: async (url, options = {}) => {
+      const result = await conformingFetch(url, options);
+      if (!String(url).endsWith("/invoke") || result.status !== 200) return result;
+      const payload = await result.json();
+      return response(200, {
+        ...payload,
+        result: { data: { payment_intent: { amount: "1" } } },
+      });
+    },
+  });
+  assert.equal(report.ok, false);
+  const invoke = report.checks.find((check) => check.name === "tool:get_pools:invoke");
+  assert.equal(invoke?.ok, false);
+  assert.match(invoke?.error ?? "", /reserved write field/);
+});
+
+test("fails when a declared tool has no fixture", async () => {
+  const report = await runConformance({
+    manifest,
+    fixture: missingToolFixture,
+    endpoint: "https://connector.example.com",
+    fetchImpl: conformingFetch,
+  });
+  assert.equal(report.ok, false);
+  assert.equal(report.checks.find((check) => check.name === "fixture_coverage")?.ok, false);
+});
+
+test("passes against the real SDK HTTP wire contract", async (context) => {
+  const connector = defineReadOnlyConnector({
+    manifest,
+    handlers: { get_pools: () => ({ pools: [] }) },
+  });
+  const handler = createConnectorHttpHandler(connector);
+  const server = createServer((request, response_) => void handler(request, response_));
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  context.after(() => new Promise((resolve) => server.close(resolve)));
+  const address = server.address();
+  assert.ok(address && typeof address === "object");
+
+  const report = await runConformance({
+    manifest,
+    fixture,
+    endpoint: `http://127.0.0.1:${address.port}`,
+  });
+  assert.equal(report.ok, true, JSON.stringify(report.checks));
+});

package/connectors/conformance/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "types": ["node"],
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}