feat(sdk): JS/TS Aggregator SDK — @agentgraph/trust (#118 complete)

The JS half of the aggregator SDK, peer to the Python client. Completes #118.
- src/verify.js: standalone verifyEnvelope(env, jwks) — strips proof, JCS via
  canonicalize@2.1.0, SHA-256 raw digest, Ed25519 verify via node:crypto, freshness.
- src/client.js: TrustClient.getAggregate/getContributions/checkRepo/getJwks/
  verify/verifyEnvelope (global fetch, Node>=18).
- 9 node:test cases incl LIVE-PROD verification: canonicalize@2.1.0 produces a
  byte-identical JCS preimage to Python rfc8785 + the server signature →
  valid=true, kid=trust-v2-2026. Cross-language byte-compat proven.
- Single runtime dep (canonicalize); Ed25519 + tests use Node built-ins.

NOTE: envelope §5 prose says JWS payload is hex(SHA-256), but the working
server+verifiers sign the RAW 32-byte digest (live verify confirms). Spec-doc
prose should be clarified to match the implementation.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kenneives

sdk/js/README.md

@@ -0,0 +1,111 @@
+# @agentgraph/trust
+
+JavaScript/TypeScript SDK for **AgentGraph Trust Score v2** — signed,
+self-verifiable trust-score envelopes. This is the JS peer of the Python
+`agentgraph-sdk` verify module; both reproduce the server's
+JCS-canonical, Ed25519-over-SHA-256 verification **byte-for-byte**.
+
+- Zero crypto deps: uses Node's built-in `node:crypto` for Ed25519.
+- One runtime dep: [`canonicalize`](https://www.npmjs.com/package/canonicalize)
+  (RFC 8785 JCS — byte-matches Python's `rfc8785`).
+- Node >= 18 (uses the global `fetch`).
+
+## Install
+
+```bash
+npm install @agentgraph/trust
+```
+
+## Trust Score v2 — signed, self-verifiable envelopes
+
+Every v2 trust score is a signed envelope you can verify **without trusting our
+server** — fetch it, then check the Ed25519 signature against our published JWKS
+yourself.
+
+```js
+import { TrustClient } from '@agentgraph/trust';
+
+const client = new TrustClient('https://agentgraph.co');
+const did = 'did:web:agentgraph.co:agents:<id>';
+
+// Signed envelope: score + per-source methodology breakdown + proof
+const env = await client.getAggregate(did);
+console.log(env.trust_score, env.contributions.map((c) => c.source));
+
+// Verify it client-side (fetches JWKS, checks signature + freshness)
+const result = await client.verify(did);
+if (result.valid) {            // true iff signature valid AND fresh
+  console.log('verified:', result.kid);
+} else {
+  console.log('NOT verified:', result.reason);
+}
+
+// Scan any GitHub repo -> grade + findings + a verifiable envelope
+const scan = await client.checkRepo('owner', 'repo');
+if (scan.trust_envelope) {
+  console.log(await client.verifyEnvelope(scan.trust_envelope));
+}
+```
+
+### Standalone verification (no client)
+
+`verifyEnvelope(envelope, jwks, { now })` only needs `canonicalize` plus
+`node:crypto`, reproducing the server's JCS-canonical, Ed25519-over-SHA-256
+check byte-for-byte.
+
+```js
+import { verifyEnvelope } from '@agentgraph/trust';
+
+const result = verifyEnvelope(envelope, jwks);
+// => { valid, signatureValid, fresh, kid, reason }
+```
+
+It (1) strips the top-level `proof` key, (2) JCS-canonicalizes the rest,
+(3) SHA-256s it, (4) reads `kid` from the detached JWS header, (5) finds the
+matching `{ kty: 'OKP', crv: 'Ed25519', x }` key in the JWKS, (6) verifies the
+Ed25519 signature over the digest, then (7) checks
+`computed_at + freshness_ttl_seconds >= now`. `valid` is
+`signatureValid && fresh`.
+
+## API
+
+### `new TrustClient(baseUrl, { apiKey?, token?, timeout? })`
+
+| Method | Description |
+|--------|-------------|
+| `getAggregate(did)` | Signed v2 envelope for a subject DID |
+| `getContributions(did)` | Just the methodology breakdown |
+| `checkRepo(owner, repo)` | Scan a GitHub repo -> grade + findings + envelope |
+| `getJwks()` | Issuer JWKS from `<baseUrl>/.well-known/jwks.json` |
+| `verifyEnvelope(env, { now? })` | Fetch JWKS + verify an envelope client-side |
+| `verify(did, { now? })` | `getAggregate` + `verifyEnvelope` in one call |
+
+API base is `<baseUrl>/api/v1`; the JWKS is served outside that prefix.
+
+### `verifyEnvelope(envelope, jwks, { now? })`
+
+Returns `{ valid, signatureValid, fresh, kid, reason }`. `reason` is one of:
+`ok`, `missing or unsupported proof`, `malformed jws`,
+`no matching key in JWKS`, `signature invalid`, `envelope expired (stale)`.
+
+Also exported: `envelopeDigest(envelope)` (raw 32-byte SHA-256 of the
+JCS-canonical, proof-stripped envelope), `isFresh(envelope, { now? })`,
+`PROOF_TYPE`.
+
+## Verification / tests
+
+```bash
+npm install
+npm test          # node --test
+```
+
+The test suite validates against **production**: it fetches the real JWKS and a
+real signed aggregate from `agentgraph.co` and asserts the JS verifier accepts
+it (`valid === true`, `kid === 'trust-v2-2026'`). A passing live check proves
+byte-compatible JCS canonicalization + Ed25519 with the Python/server side. If
+prod is unreachable it falls back to a pinned fixture captured from prod.
+
+## Spec
+
+[`docs/standards/trust-score-envelope-v2.0.md`](../../docs/standards/trust-score-envelope-v2.0.md)
+(§6 verification). MIT licensed.

sdk/js/index.js

@@ -0,0 +1,8 @@
+// @agentgraph/trust — JS/TS peer of the Python agentgraph-sdk Trust Score v2 surface.
+//
+// Standalone client-side verification of signed v2 trust-score envelopes
+// (JCS-canonical, proof-stripped, Ed25519 over SHA-256), plus a thin async API
+// client. Byte-compatible with the Python SDK and the server.
+
+export { verifyEnvelope, envelopeDigest, isFresh, PROOF_TYPE } from './src/verify.js';
+export { TrustClient, AgentGraphError } from './src/client.js';

sdk/js/package-lock.json

@@ -0,0 +1,39 @@
+{
+  "name": "@agentgraph/trust",
+  "version": "0.1.0",
+  "description": "Client-side verification of AgentGraph Trust Score v2 signed envelopes (JCS-canonical, Ed25519-over-SHA-256). Peer of the Python agentgraph-sdk verify module.",
+  "type": "module",
+  "license": "MIT",
+  "author": "AgentGraph",
+  "homepage": "https://agentgraph.co",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./verify": "./src/verify.js",
+    "./client": "./src/client.js"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "canonicalize": "2.1.0"
+  },
+  "keywords": [
+    "agentgraph",
+    "trust-score",
+    "ed25519",
+    "jcs",
+    "rfc8785",
+    "jws",
+    "did",
+    "verifiable"
+  ]
+}

sdk/js/package.json

@@ -0,0 +1,181 @@
+// Async API client for the AgentGraph Trust Score v2 surface.
+//
+// Peer of the Python agentgraph_sdk.client.AgentGraphClient (Trust Score v2
+// methods). Uses the global `fetch` (Node 18+). API base is `<baseUrl>/api/v1`;
+// the JWKS lives outside that prefix at `<baseUrl>/.well-known/jwks.json`.
+
+import { verifyEnvelope } from './verify.js';
+
+/** Base error for AgentGraph API failures. */
+export class AgentGraphError extends Error {
+  /**
+   * @param {string} message
+   * @param {number|null} [statusCode]
+   */
+  constructor(message, statusCode = null) {
+    super(message);
+    this.name = 'AgentGraphError';
+    this.statusCode = statusCode;
+  }
+}
+
+/**
+ * Async client for the AgentGraph API (Trust Score v2 surface).
+ *
+ * @example
+ * const client = new TrustClient('https://agentgraph.co');
+ * const env = await client.getAggregate('did:web:agentgraph.co:agents:<id>');
+ * const result = await client.verifyEnvelope(env);
+ * if (result.valid) console.log('verified:', result.kid);
+ */
+export class TrustClient {
+  /**
+   * @param {string} baseUrl
+   * @param {{apiKey?: string, token?: string, timeout?: number}} [opts]
+   */
+  constructor(baseUrl, { apiKey, token, timeout = 30000 } = {}) {
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this._apiPrefix = `${this.baseUrl}/api/v1`;
+    this._apiKey = apiKey ?? null;
+    this._token = token ?? null;
+    this._timeout = timeout;
+  }
+
+  _headers() {
+    const headers = {};
+    if (this._apiKey) {
+      headers['X-API-Key'] = this._apiKey;
+    } else if (this._token) {
+      headers['Authorization'] = `Bearer ${this._token}`;
+    }
+    return headers;
+  }
+
+  /**
+   * Low-level request against the API prefix (`<baseUrl>/api/v1`).
+   * @param {string} method
+   * @param {string} path
+   * @param {{json?: object, params?: object}} [opts]
+   */
+  async _request(method, path, { json, params } = {}) {
+    let url = `${this._apiPrefix}${path}`;
+    if (params) {
+      const qs = new URLSearchParams();
+      for (const [k, v] of Object.entries(params)) {
+        if (v !== null && v !== undefined) qs.append(k, String(v));
+      }
+      const s = qs.toString();
+      if (s) url += `?${s}`;
+    }
+    return this._fetch(method, url, json);
+  }
+
+  async _fetch(method, url, json) {
+    const headers = this._headers();
+    const init = { method, headers };
+    if (json !== undefined) {
+      headers['Content-Type'] = 'application/json';
+      init.body = JSON.stringify(json);
+    }
+
+    let controller;
+    let timer;
+    if (this._timeout && typeof AbortController !== 'undefined') {
+      controller = new AbortController();
+      init.signal = controller.signal;
+      timer = setTimeout(() => controller.abort(), this._timeout);
+    }
+
+    let resp;
+    try {
+      resp = await fetch(url, init);
+    } catch (err) {
+      throw new AgentGraphError(`request failed: ${err.message}`, null);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+    return this._parseResponse(resp);
+  }
+
+  async _parseResponse(resp) {
+    if (resp.status === 204) return null;
+    const text = await resp.text();
+    if (resp.status >= 400) {
+      let detail = text;
+      try {
+        detail = JSON.parse(text).detail ?? text;
+      } catch {
+        // keep raw text
+      }
+      throw new AgentGraphError(String(detail) || `HTTP ${resp.status}`, resp.status);
+    }
+    if (!text) return null;
+    return JSON.parse(text);
+  }
+
+  // ------------------------------------------------------------------
+  // Trust Score v2 — signed aggregate envelopes
+  // ------------------------------------------------------------------
+
+  /**
+   * Fetch the signed v2 trust-score envelope for a subject DID.
+   * The envelope carries the score, a per-source methodology breakdown, and an
+   * Ed25519 proof. Use `verify()` to check it client-side.
+   * @param {string} subjectDid
+   */
+  async getAggregate(subjectDid) {
+    return this._request('GET', `/aggregate/${subjectDid}`);
+  }
+
+  /**
+   * Fetch just the methodology breakdown (contributions) for a subject.
+   * @param {string} subjectDid
+   */
+  async getContributions(subjectDid) {
+    return this._request('GET', `/aggregate/${subjectDid}/contributions`);
+  }
+
+  /**
+   * Scan a GitHub repo and return its grade + findings + signed v2 envelope.
+   * The `trust_envelope` field (when present) is verifiable via verifyEnvelope().
+   * @param {string} owner
+   * @param {string} repo
+   */
+  async checkRepo(owner, repo) {
+    return this._request('GET', `/public/scan/${owner}/${repo}`);
+  }
+
+  /**
+   * Fetch the issuer JWKS (RFC 7517) used to verify signed envelopes.
+   * Served at `<baseUrl>/.well-known/jwks.json` (outside the API prefix).
+   */
+  async getJwks() {
+    return this._fetch('GET', `${this.baseUrl}/.well-known/jwks.json`);
+  }
+
+  /**
+   * Verify a signed envelope client-side against the issuer's JWKS.
+   * Fetches the JWKS, then checks the Ed25519 signature + freshness WITHOUT
+   * trusting this server's verdict — the whole point of the signed envelope.
+   * @param {object} envelope
+   * @param {{now?: Date}} [opts]
+   * @returns {Promise<import('./verify.js').VerificationResult>}
+   */
+  async verifyEnvelope(envelope, { now } = {}) {
+    const jwks = await this.getJwks();
+    return verifyEnvelope(envelope, jwks, { now });
+  }
+
+  /**
+   * Fetch a subject's envelope and verify it client-side in one call.
+   * @param {string} subjectDid
+   * @param {{now?: Date}} [opts]
+   * @returns {Promise<import('./verify.js').VerificationResult>}
+   */
+  async verify(subjectDid, { now } = {}) {
+    const envelope = await this.getAggregate(subjectDid);
+    return this.verifyEnvelope(envelope, { now });
+  }
+}
+
+export default TrustClient;