@agentlayer.tech/wallet 0.1.101 → 0.1.102

package/connectors/sdk-typescript/test/sdk.test.mjs

@@ -0,0 +1,181 @@
+import assert from "node:assert/strict";
+import { Readable } from "node:stream";
+import test from "node:test";
+
+import {
+  ConnectorSdkError,
+  createConnectorHttpHandler,
+  defineReadOnlyConnector,
+} from "../dist/index.js";
+
+function manifest(overrides = {}) {
+  return {
+    schema_version: 1,
+    id: "com.example.markets",
+    name: "Example Markets",
+    version: "1.0.0",
+    artifact_digest: `sha256:${"a".repeat(64)}`,
+    publisher: { id: "example", name: "Example" },
+    agentlayer: { protocol_version: 1, runtime_range: ">=0.1.101" },
+    trust: "community_read_only",
+    transport: { type: "https", url: "https://connector.example.com/v1" },
+    permissions: {
+      wallet_address: false,
+      transaction_intents: false,
+      network_hosts: ["api.example.com"],
+    },
+    tools: [
+      {
+        name: "get_markets",
+        description: "Get markets.",
+        read_only: true,
+        risk_level: "low",
+        input_schema: {
+          type: "object",
+          properties: { limit: { type: "integer", minimum: 1, maximum: 10 } },
+          required: ["limit"],
+          additionalProperties: false,
+        },
+        output_schema: {
+          type: "object",
+          properties: { markets: { type: "array", items: { type: "string" } } },
+          required: ["markets"],
+          additionalProperties: false,
+        },
+      },
+    ],
+    ...overrides,
+  };
+}
+
+function request(overrides = {}) {
+  return {
+    protocol_version: 1,
+    request_id: "request-123",
+    connector: {
+      id: "com.example.markets",
+      version: "1.0.0",
+      artifact_digest: `sha256:${"a".repeat(64)}`,
+    },
+    tool: "get_markets",
+    arguments: { limit: 2 },
+    context: { chain: "evm", network: "base" },
+    ...overrides,
+  };
+}
+
+test("builds a short-lived identity-bound read result", async () => {
+  const connector = defineReadOnlyConnector({
+    manifest: manifest(),
+    handlers: { get_markets: ({ limit }) => ({ markets: Array(limit).fill("USDC") }) },
+  });
+  const result = await connector.invoke(request());
+  assert.equal(result.kind, "read_result");
+  assert.deepEqual(result.result, { markets: ["USDC", "USDC"] });
+  assert.equal(result.connector.artifact_digest, `sha256:${"a".repeat(64)}`);
+  assert.ok(Date.parse(result.expires_at) > Date.now());
+});
+
+test("rejects identity mismatch and invalid arguments", async () => {
+  const connector = defineReadOnlyConnector({
+    manifest: manifest(),
+    handlers: { get_markets: () => ({ markets: [] }) },
+  });
+  await assert.rejects(
+    connector.invoke(request({ connector: { id: "com.attacker", version: "1.0.0" } })),
+    (error) => error instanceof ConnectorSdkError && error.code === "identity_mismatch"
+  );
+  await assert.rejects(
+    connector.invoke(request({ arguments: { limit: 100 } })),
+    (error) => error instanceof ConnectorSdkError && error.code === "invalid_arguments"
+  );
+});
+
+test("rejects handler output that violates the public schema", async () => {
+  const connector = defineReadOnlyConnector({
+    manifest: manifest(),
+    handlers: { get_markets: () => ({ markets: "not-an-array" }) },
+  });
+  await assert.rejects(
+    connector.invoke(request()),
+    (error) => error instanceof ConnectorSdkError && error.code === "invalid_result"
+  );
+});
+
+test("rejects write envelopes embedded in read-only output", async () => {
+  const permissiveManifest = manifest();
+  permissiveManifest.tools[0].output_schema = { type: "object" };
+  const connector = defineReadOnlyConnector({
+    manifest: permissiveManifest,
+    handlers: {
+      get_markets: () => ({ data: { transaction_intent: { to: "0xdead" } } }),
+    },
+  });
+  await assert.rejects(
+    connector.invoke(request()),
+    (error) => error instanceof ConnectorSdkError && error.code === "write_not_supported"
+  );
+});
+
+test("rejects a response larger than the wallet protocol limit", async () => {
+  const permissiveManifest = manifest();
+  permissiveManifest.tools[0].output_schema = { type: "object" };
+  const connector = defineReadOnlyConnector({
+    manifest: permissiveManifest,
+    handlers: { get_markets: () => ({ data: "x".repeat(1024 * 1024) }) },
+  });
+  await assert.rejects(
+    connector.invoke(request()),
+    (error) => error instanceof ConnectorSdkError && error.code === "response_too_large"
+  );
+});
+
+test("refuses write-capable manifests and undeclared handlers", () => {
+  assert.throws(
+    () =>
+      defineReadOnlyConnector({
+        manifest: manifest({ trust: "verified_write" }),
+        handlers: { get_markets: () => ({ markets: [] }) },
+      }),
+    (error) => error instanceof ConnectorSdkError && error.code === "write_not_supported"
+  );
+  assert.throws(
+    () =>
+      defineReadOnlyConnector({
+        manifest: manifest(),
+        handlers: {
+          get_markets: () => ({ markets: [] }),
+          hidden_write: () => ({ transaction: "0x" }),
+        },
+      }),
+    (error) => error instanceof ConnectorSdkError && error.code === "unknown_handler"
+  );
+});
+
+test("serves only health and JSON invoke routes", async () => {
+  const connector = defineReadOnlyConnector({
+    manifest: manifest(),
+    handlers: { get_markets: () => ({ markets: ["USDC"] }) },
+  });
+  const handler = createConnectorHttpHandler(connector);
+  const body = JSON.stringify(request());
+  const incoming = Object.assign(Readable.from([body]), {
+    method: "POST",
+    url: "/invoke",
+    headers: { "content-type": "application/json", "content-length": String(Buffer.byteLength(body)) },
+  });
+  const captured = { statusCode: 0, headers: {}, body: "" };
+  const response = {
+    writeHead(statusCode, headers) {
+      captured.statusCode = statusCode;
+      captured.headers = headers;
+    },
+    end(value) {
+      captured.body = String(value ?? "");
+    },
+  };
+  await handler(incoming, response);
+  assert.equal(captured.statusCode, 200);
+  assert.equal(JSON.parse(captured.body).kind, "read_result");
+  assert.equal(captured.headers["cache-control"], "no-store");
+});

package/connectors/sdk-typescript/tsconfig.json

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

package/connectors/spec/connector-manifest.schema.json

@@ -0,0 +1,340 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-layer.tech/schemas/connectors/v1/connector-manifest.schema.json",
+  "title": "AgentLayer Connector Manifest v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "id",
+    "name",
+    "version",
+    "publisher",
+    "agentlayer",
+    "trust",
+    "transport",
+    "permissions",
+    "tools"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)+$",
+      "maxLength": 128
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$",
+      "maxLength": 64
+    },
+    "artifact_digest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "publisher": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9_-]{1,63}$"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^https://"
+        }
+      }
+    },
+    "agentlayer": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["protocol_version", "runtime_range"],
+      "properties": {
+        "protocol_version": {
+          "const": 1
+        },
+        "runtime_range": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        }
+      }
+    },
+    "trust": {
+      "type": "string",
+      "enum": [
+        "community_read_only",
+        "verified_read_only",
+        "verified_write",
+        "local_development"
+      ]
+    },
+    "transport": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "url"],
+      "properties": {
+        "type": {
+          "const": "https"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^https://",
+          "maxLength": 2048
+        },
+        "timeout_ms": {
+          "type": "integer",
+          "minimum": 100,
+          "maximum": 30000,
+          "default": 10000
+        }
+      }
+    },
+    "permissions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["wallet_address", "transaction_intents", "network_hosts"],
+      "properties": {
+        "wallet_address": {
+          "type": "boolean"
+        },
+        "balance_read": {
+          "type": "boolean",
+          "default": false
+        },
+        "transaction_intents": {
+          "type": "boolean"
+        },
+        "x402_discovery": {
+          "type": "boolean",
+          "default": false
+        },
+        "network_hosts": {
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
+          }
+        }
+      }
+    },
+    "chains": {
+      "type": "array",
+      "maxItems": 32,
+      "items": {
+        "$ref": "#/$defs/chainPolicy"
+      }
+    },
+    "tools": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "items": {
+        "$ref": "#/$defs/tool"
+      }
+    }
+  },
+  "$defs": {
+    "jsonSchema": {
+      "type": "object"
+    },
+    "tool": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "description", "read_only", "risk_level", "input_schema", "output_schema"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]{1,63}$"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500
+        },
+        "read_only": {
+          "type": "boolean"
+        },
+        "risk_level": {
+          "type": "string",
+          "enum": ["low", "medium", "high"]
+        },
+        "input_schema": {
+          "$ref": "#/$defs/jsonSchema"
+        },
+        "output_schema": {
+          "$ref": "#/$defs/jsonSchema"
+        }
+      }
+    },
+    "chainPolicy": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/evmPolicy"
+        },
+        {
+          "$ref": "#/$defs/solanaPolicy"
+        }
+      ]
+    },
+    "evmPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["chain", "chain_ids", "contracts"],
+      "properties": {
+        "chain": {
+          "const": "evm"
+        },
+        "chain_ids": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "integer",
+            "minimum": 1
+          }
+        },
+        "contracts": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 128,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["chain_id", "address", "selectors"],
+            "properties": {
+              "chain_id": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "address": {
+                "type": "string",
+                "pattern": "^0x[0-9a-fA-F]{40}$"
+              },
+              "selectors": {
+                "type": "array",
+                "minItems": 1,
+                "uniqueItems": true,
+                "items": {
+                  "type": "string",
+                  "pattern": "^0x[0-9a-fA-F]{8}$"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "solanaPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["chain", "networks", "program_ids"],
+      "properties": {
+        "chain": {
+          "const": "solana"
+        },
+        "networks": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": ["mainnet", "devnet", "testnet"]
+          }
+        },
+        "program_ids": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$"
+          }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "trust": {
+            "enum": ["community_read_only", "verified_read_only"]
+          }
+        },
+        "required": ["trust"]
+      },
+      "then": {
+        "properties": {
+          "permissions": {
+            "type": "object",
+            "properties": {
+              "transaction_intents": {
+                "const": false
+              }
+            }
+          },
+          "tools": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "read_only": {
+                  "const": true
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "trust": {
+            "const": "verified_write"
+          }
+        },
+        "required": ["trust"]
+      },
+      "then": {
+        "required": ["artifact_digest", "chains"],
+        "properties": {
+          "artifact_digest": true,
+          "chains": true,
+          "permissions": {
+            "type": "object",
+            "properties": {
+              "transaction_intents": {
+                "const": true
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/connectors/spec/connector-protocol.md

@@ -0,0 +1,159 @@
+# AgentLayer Connector Protocol v1
+
+## Status
+
+Protocol v1 is frozen for the read-only public beta. Additive optional fields
+may be introduced in v1, but existing required fields, response binding, trust
+semantics, and tool namespaces cannot change without a new protocol version.
+
+The read-only beta supports direct HTTPS invocation of publisher-hosted
+`community_read_only` and `verified_read_only` connectors. Gateway-attested
+requests are an additive deployment mode. Write-capable execution remains
+experimental and is not part of the read-only beta release.
+
+## Components
+
+- **Local registry** pins manifests selected by the user.
+- **Gateway** may authenticate invocations and route them to an exact connector
+  version; direct read-only HTTPS invocation does not require it.
+- **Connector runtime** returns structured read results or unsigned intents.
+- **Local wallet** validates schemas, policy, simulation, approval, signing,
+  broadcast, and final confirmation.
+
+## Identity and immutability
+
+A connector is identified by `(id, version, artifact_digest)`. Published
+versions are immutable. A changed artifact requires a new version. The local
+registry pins all three values and refuses a response that names a different
+identity.
+
+## Tool namespaces
+
+Tool names in a manifest are connector-local. Hosts expose them as:
+
+```text
+connector__<normalized_connector_id>__<tool_name>
+```
+
+Normalized names contain lowercase ASCII letters, digits, and underscores.
+
+## Invocation request
+
+The wallet sends a JSON request containing:
+
+```json
+{
+  "protocol_version": 1,
+  "request_id": "uuid",
+  "connector": {
+    "id": "com.example.protocol",
+    "version": "1.0.0",
+    "artifact_digest": "sha256:..."
+  },
+  "tool": "get_markets",
+  "arguments": {},
+  "context": {
+    "chain": "evm",
+    "network": "base",
+    "chain_id": 8453,
+    "wallet_address": "0x..."
+  },
+  "issued_at": "2026-08-25T12:00:00Z",
+  "expires_at": "2026-08-25T12:00:30Z",
+  "nonce": "opaque-single-use-value"
+}
+```
+
+`wallet_address` is omitted unless the installed manifest grants that
+permission. `issued_at`, `expires_at`, and `nonce` are optional for direct
+read-only HTTPS invocation and required for gateway-attested requests. A
+connector must ignore unknown optional context fields and must never infer
+permission from their presence.
+
+The required request fields are `protocol_version`, `request_id`, `connector`,
+`tool`, `arguments`, and `context`.
+
+## Invocation response
+
+Every successful response contains the exact connector identity, request ID,
+tool name, expiry, and one result kind:
+
+```json
+{
+  "protocol_version": 1,
+  "request_id": "uuid",
+  "connector": {
+    "id": "com.example.protocol",
+    "version": "1.0.0",
+    "artifact_digest": "sha256:..."
+  },
+  "tool": "get_markets",
+  "kind": "read_result",
+  "result": {},
+  "expires_at": "2026-08-25T12:01:00Z"
+}
+```
+
+The complete encoded response body must not exceed 1 MiB and must use
+`Content-Type: application/json`.
+
+Write-capable responses use `evm_transaction_intent` or
+`solana_transaction_intent`. They remain unsigned and unbroadcasted.
+
+## Read-only enforcement
+
+Community and verified read-only connectors may return only `read_result`.
+Returning any transaction, payment, signature, or broadcast intent is a hard
+protocol violation. Read output is untrusted external data and must be checked
+against the manifest's output schema before it reaches an agent host.
+
+To prevent a read result from masquerading as an executable envelope, these
+field names are reserved at every depth of `result`: `approval_token`,
+`broadcast_request`, `evm_transaction_intent`, `payment_intent`,
+`raw_transaction`, `signed_transaction`, `signing_request`,
+`solana_transaction_intent`, and `transaction_intent`.
+
+Connector output is data, never agent instruction. Hosts must not treat text in
+a connector result as authorization, policy, tool-routing guidance, or a reason
+to perform another action.
+
+## Read-only beta compatibility
+
+- A connector built for Protocol v1 must keep accepting all v1 required fields.
+- Adding a required manifest, request, response, or tool field requires a new
+  protocol version or a new connector tool/version.
+- Tool input/output schemas are immutable for a published connector version.
+- `artifact_digest`, when present, is identity-bound and must match exactly.
+- Community connectors cannot become write-capable without a new verified
+  connector version and a different release track.
+
+## Write execution
+
+Only an enabled `verified_write` connector may return a transaction intent.
+The local wallet must independently enforce:
+
+- exact connector identity and artifact digest
+- supported chain and network
+- wallet/from/fee-payer binding
+- contract addresses or Solana program IDs
+- EVM selectors or Solana instruction constraints
+- assets, amounts, recipients, spenders, and native value
+- bounded approvals
+- intent expiry and replay protection
+- successful local simulation
+- preview-to-execute binding
+
+The connector never signs or broadcasts. The local wallet refreshes the intent
+after confirmation, repeats all checks, then signs and sends it.
+
+## Fees
+
+Connector, referral, builder, and AgentLayer integration fees are prohibited.
+Protocol fees, network fees, and x402 service prices must be explicit in the
+preview and expected-effects data.
+
+## Failure behavior
+
+Unknown fields required for safe interpretation, schema mismatch, identity
+mismatch, stale intent, failed simulation, unknown target, unknown program,
+unknown selector, or expanded approval must fail closed.