@agentlayer.tech/wallet 0.1.101 → 0.1.102

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"]
+}

package/connectors/examples/reference-crypto-data/Dockerfile

@@ -0,0 +1,21 @@
+FROM node:24-alpine AS build
+
+WORKDIR /app/connectors
+COPY connectors/package.json connectors/package-lock.json ./
+COPY connectors/sdk-typescript ./sdk-typescript
+COPY connectors/conformance ./conformance
+COPY connectors/templates/read-only ./templates/read-only
+COPY connectors/examples/reference-crypto-data ./examples/reference-crypto-data
+RUN npm ci
+RUN npm run build --workspace @agentlayer.tech/connector-sdk
+RUN npm run build --workspace @agentlayer.tech/reference-crypto-data-connector
+
+FROM node:24-alpine
+
+ENV NODE_ENV=production
+WORKDIR /app/connectors
+COPY --from=build --chown=node:node /app/connectors /app/connectors
+USER node
+EXPOSE 3000
+
+CMD ["npm", "run", "start", "--workspace", "@agentlayer.tech/reference-crypto-data-connector"]

package/connectors/examples/reference-crypto-data/README.md

@@ -0,0 +1,51 @@
+# AgentLayer crypto-data reference connector
+
+This is a neutral, read-only reference implementation for Connector Protocol
+v1. It exposes public spot-price and asset-metadata tools. It does not receive a
+wallet address, construct transactions, make payments, sign, or broadcast.
+
+The upstream is Coinbase Exchange's public market-data API. The reference uses
+the documented public ticker and currency endpoints and requires no API key:
+
+- https://docs.cdp.coinbase.com/api-reference/exchange-api/rest-api/products/get-product-ticker
+- https://docs.cdp.coinbase.com/api-reference/exchange-api/rest-api/currencies/get-a-currency
+
+Run locally:
+
+```bash
+npm ci --prefix connectors
+npm run build --workspace @agentlayer.tech/reference-crypto-data-connector --prefix connectors
+npm run start --workspace @agentlayer.tech/reference-crypto-data-connector --prefix connectors
+```
+
+The reviewed beta deployment is available at
+`https://reference-crypto-data-production.up.railway.app`. Its manifest is
+already pinned to that exact HTTPS endpoint. Re-run its live conformance check
+after any immutable version release:
+
+```bash
+cd connectors
+node conformance/dist/cli.js \
+  --manifest examples/reference-crypto-data/connector.json \
+  --fixture examples/reference-crypto-data/conformance.json \
+  --endpoint https://reference-crypto-data-production.up.railway.app
+```
+
+## Railway deployment
+
+Deploy this directory as one stateless service in a new, isolated Railway
+project. Keep the repository root as the Docker build context and point the
+service Dockerfile at
+`connectors/examples/reference-crypto-data/Dockerfile` (for a root deployment,
+set Railway's `RAILWAY_DOCKERFILE_PATH` service variable to that value).
+Configure the Railway deployment health-check path as `/healthz` with a
+10-second timeout and an `ON_FAILURE` restart policy. The service needs no
+application variables, volume, database, wallet material, or connection to the
+AgentLayer provider gateway.
+
+After Railway generates the public domain:
+
+1. update `connector.json` to that exact HTTPS URL;
+2. redeploy the immutable manifest version;
+3. run both live conformance and wallet invocation tests;
+4. install the reviewed manifest with `wallet connectors install ... --enable --yes`.

package/connectors/examples/reference-crypto-data/conformance.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": 1,
+  "tools": {
+    "get_spot_price": {
+      "arguments": { "base": "BTC", "quote": "USD" }
+    },
+    "get_asset_metadata": {
+      "arguments": { "asset": "BTC" }
+    }
+  }
+}