genesis-mesh-sdk 0.53.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to `genesis-mesh-sdk` are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions align with the [Genesis Mesh release sequence](https://github.com/GenesisMeshLabs/genesismesh/blob/main/CHANGELOG.md).
+
+---
+
+## [0.53.0] — 2026-06-29
+
+### Added
+
+- `GenesisMeshClient` — unified entry point with 7 domain sub-clients
+- `AgreementClient` — capability offer, counter, accept, verify
+- `BoundaryClient` — boundary decision and verification
+- `EvidenceClient` — trust evidence build and verify
+- `AttestationClient` — membership attestation issue, revoke, recognition policy
+- `DisclosureClient` — selective Merkle capability disclosure, nullifier
+- `ConsensusClient` — validator vote, consensus proof assembly and verify
+- `DataUsageClient` — data license policy, access intent, verify
+- `src/auth.ts` — `canonicalJson`, `signBytes`, `buildAdminHeaders` (Ed25519 / PKCS8-DER)
+- `src/client.ts` — `HttpTransport` with fetch, timeout, and typed error mapping
+- `src/errors.ts` — `GenesisMeshError` and typed subclasses for all NA error codes
+- `src/types.ts` — 30+ protocol interfaces matching the NA JSON wire format
+- ESM and CJS dual build (`dist/esm/`, `dist/cjs/`, `dist/types/`)
+- 74 Jest unit tests covering all sub-clients
+
+[0.53.0]: https://github.com/GenesisMeshLabs/sdk-typescript/releases/tag/v0.53.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Genesis Mesh Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,276 @@
+# genesis-mesh-sdk
+
+TypeScript SDK for the Genesis Mesh Network Authority HTTP API.
+
+**Node.js ≥ 20 required. Zero runtime dependencies.**
+
+## Install
+
+```bash
+npm install genesis-mesh-sdk
+```
+
+## Quick start
+
+```typescript
+import { GenesisMeshClient } from 'genesis-mesh-sdk';
+import { readFileSync } from 'node:fs';
+
+// Load operator key seed (32 bytes, base64-encoded, from operator.key file)
+const signingKeyBase64 = readFileSync('/path/to/keys/operator.key', 'utf-8')
+  .split('\n')
+  .find(l => !l.startsWith('#'))!
+  .trim();
+
+const client = new GenesisMeshClient({
+  baseUrl: 'http://127.0.0.1:9443',
+  signingKeyBase64,
+  keyId: 'operator-local',   // must match the NA's registered operator key
+});
+```
+
+## Sub-clients
+
+### agreement
+
+> **Note:** `accept` requires the NA to have a recognition treaty for the
+> responder sovereign. Issue one first via `/admin/recognition-treaties` (see
+> [Raw admin calls](#raw-admin-calls) below).
+
+```typescript
+// Create a capability offer (admin — requires signing key)
+const offer = await client.agreement.offer({
+  responder_sovereign_id: 'BETA-NA',
+  capabilities: ['read:data', 'write:log'],
+  valid_from: '2026-01-01T00:00:00Z',
+  valid_until: '2026-12-31T00:00:00Z',
+  expires_at: '2026-01-15T00:00:00Z',
+});
+
+// Counter an offer
+const counter = await client.agreement.counter({
+  offer,
+  capabilities: ['read:data'],   // narrowed scope
+  valid_from: '2026-01-01T00:00:00Z',
+  valid_until: '2026-06-30T00:00:00Z',
+});
+
+// Accept an offer or counter
+const agreement = await client.agreement.accept({ offer });
+// or: await client.agreement.accept({ counter, original_offer: offer });
+
+// Verify agreement signatures (no auth required)
+const check = await client.agreement.verify({ agreement });
+console.log(check.accepted); // true | false
+```
+
+### boundary
+
+```typescript
+// Issue a boundary decision (admin)
+const decision = await client.boundary.decide({
+  agreement,
+  requested_capability: 'read:data',
+  context: { session_id: 'sess-123' },
+});
+console.log(decision.authorized); // true | false
+
+// Verify a boundary decision (no auth required)
+const v = await client.boundary.verify({ decision });
+console.log(v.accepted, v.authorized);
+```
+
+### evidence
+
+```typescript
+// Build signed trust evidence (admin)
+// verdict must be one of: "allow" | "block" | "escalate" | "warn"
+const evidence = await client.evidence.build({
+  decision: {
+    source_sovereign_id: 'ALPHA',
+    target_sovereign_id: 'BETA',
+    verdict: 'allow',
+    reason: 'long-standing member',
+  },
+});
+
+// Verify trust evidence (no auth required)
+const ev = await client.evidence.verify({ evidence });
+console.log(ev.accepted, ev.verdict);
+```
+
+### attestation
+
+```typescript
+// Issue a membership attestation (admin)
+// roles must use a recognized prefix:
+//   role:anchor | role:bridge | role:client | role:operator | role:service:<name>
+const att = await client.attestation.issue({
+  subject_id: 'node-xyz',
+  roles: ['role:client', 'role:anchor'],
+  validity_hours: 8760,
+  claims: { department: 'engineering' },
+});
+
+// Revoke an attestation (admin)
+await client.attestation.revoke(att.attestation_id, { reason: 'key compromised' });
+
+// Set recognition policy (admin)
+await client.attestation.savePolicy({
+  recognition_policy: {
+    local_sovereign_id: 'MY-NA',
+    recognized_issuers: [],   // add RecognizedIssuer entries as needed
+  },
+});
+```
+
+### disclosure
+
+```typescript
+// Commit to a set of capabilities (admin)
+const commitment = await client.disclosure.commit({
+  capabilities: ['read:data', 'write:log'],
+  agreement,
+});
+
+// Generate a Merkle membership proof (no auth required)
+const proof = await client.disclosure.prove({
+  capability: 'read:data',
+  capabilities: ['read:data', 'write:log'],
+  commitment,
+  prover_sovereign_id: 'BETA',
+});
+
+// Issue a one-time nullifier (admin)
+const nullifier = await client.disclosure.nullifier({ proof });
+
+// Verify the proof (no auth required)
+const dv = await client.disclosure.verify({ proof, commitment });
+console.log(dv.valid);
+```
+
+### consensus
+
+```typescript
+// Cast a validator vote (admin)
+const vote = await client.consensus.vote({
+  justification_proof: { proof_id: 'jp-001', decision_id: 'dec-001' },
+  vote: true,
+  reason: 'evidence satisfactory',
+});
+
+// Assemble a consensus proof (admin)
+const cp = await client.consensus.proof({
+  justification_proof: { proof_id: 'jp-001', decision_id: 'dec-001' },
+  votes: [vote],
+  required_threshold: 1,
+  validator_sovereign_ids: ['ALPHA'],
+});
+
+// Verify the consensus proof (no auth required)
+const cv = await client.consensus.verify({ proof: cp });
+console.log(cv.valid);
+```
+
+### dataUsage
+
+```typescript
+// Create a data license policy (admin)
+const pol = await client.dataUsage.createPolicy({
+  licensee_sovereign_id: 'BETA',
+  allowed_source_ids: ['src-a'],
+  allowed_access_types: ['read', 'aggregate'],
+  valid_from: '2026-01-01T00:00:00Z',
+  valid_until: '2026-12-31T00:00:00Z',
+  max_volume_bytes_per_session: 104857600,
+  prohibited_classification_tags: ['pii'],
+});
+
+// Create a data access intent (admin)
+// source_type: "personal" | "proprietary" | "public" | "synthetic"
+const intent = await client.dataUsage.createIntent({
+  sources: [{
+    source_id: 'src-a',
+    source_type: 'public',
+    owner_sovereign_id: 'MY-NA',
+    classification_tags: ['public'],
+  }],
+  access_types: ['read'],
+});
+
+// Get the active policy (no auth required)
+const activePol = await client.dataUsage.getPolicy();
+
+// Verify intent against policy (no auth required)
+const dv = await client.dataUsage.verify({ intent, policy: pol });
+console.log(dv.valid, dv.violations);
+```
+
+## Raw admin calls
+
+For NA routes not yet covered by a sub-client (e.g. `/admin/recognition-treaties`),
+use `buildAdminHeaders` directly:
+
+```typescript
+import { buildAdminHeaders } from 'genesis-mesh-sdk';
+
+const body = {
+  subject_sovereign_id: 'BETA-NA',
+  subject_public_keys: ['<base64-ed25519-pubkey>'],
+  scope: { allowed_roles: ['role:client'] },
+  validity_hours: 24,
+};
+
+const headers = buildAdminHeaders(body, keyId, signingKeyBase64);
+const res = await fetch(`${baseUrl}/admin/recognition-treaties`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json', ...headers },
+  body: JSON.stringify(body),
+});
+```
+
+## Error handling
+
+```typescript
+import {
+  UnauthorizedError,
+  RateLimitError,
+  ValidationError,
+  NotFoundError,
+  NetworkError,
+} from 'genesis-mesh-sdk';
+
+try {
+  await client.agreement.offer({ ... });
+} catch (err) {
+  if (err instanceof UnauthorizedError) { /* bad signing key or stale timestamp */ }
+  if (err instanceof RateLimitError)    { /* back off and retry */ }
+  if (err instanceof ValidationError)   { /* inspect err.message and err.code */ }
+  if (err instanceof NetworkError)      { /* connection refused or timeout */ }
+}
+```
+
+## Admin authentication
+
+Admin routes are authenticated with four HTTP headers generated from an Ed25519 operator key:
+
+| Header | Description |
+|---|---|
+| `X-Admin-Key-Id` | Key identifier registered with the NA |
+| `X-Admin-Signature` | Ed25519 signature over `canonicalJson({body, key_id, nonce, timestamp})` |
+| `X-Admin-Timestamp` | ISO 8601 UTC timestamp (must be within NA's nonce window) |
+| `X-Admin-Nonce` | UUID v4 replay-protection token (single use) |
+
+The SDK handles all of this automatically when `signingKeyBase64` is provided.
+
+## Build
+
+```bash
+npm run build       # ESM → dist/esm/ and CJS → dist/cjs/
+npm run typecheck   # type-check without emitting
+npm test            # run 74 Jest tests
+```
+
+## License
+
+MIT

package/dist/cjs/agreement.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgreementClient = void 0;
+class AgreementClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Create and sign a capability offer (admin). */
+    offer(params) {
+        return this.http.adminPost('/admin/agreements/offer', params);
+    }
+    /** Create and sign a counter-offer (admin). */
+    counter(params) {
+        return this.http.adminPost('/admin/agreements/counter', params);
+    }
+    /** Accept an offer or counter (admin). */
+    accept(params) {
+        return this.http.adminPost('/admin/agreements/accept', params);
+    }
+    /** Verify agreement signatures (unauthenticated). */
+    verify(params) {
+        return this.http.publicPost('/agreements/verify', params);
+    }
+}
+exports.AgreementClient = AgreementClient;

package/dist/cjs/attestation.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttestationClient = void 0;
+class AttestationClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Issue a signed membership attestation (admin). */
+    issue(params) {
+        return this.http.adminPost('/admin/attestations', params);
+    }
+    /** Revoke a membership attestation by ID (admin). */
+    revoke(attestationId, params = {}) {
+        return this.http.adminPost(`/admin/attestations/${attestationId}/revoke`, params);
+    }
+    /** Set the active recognition policy for this sovereign (admin). */
+    savePolicy(params) {
+        return this.http.adminPost('/admin/recognition-policy', params);
+    }
+}
+exports.AttestationClient = AttestationClient;

package/dist/cjs/auth.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Admin authentication for Genesis Mesh NA endpoints.
+ *
+ * The NA verifies requests via four HTTP headers:
+ *   X-Admin-Key-Id        — which operator key was used
+ *   X-Admin-Signature     — Ed25519(canonicalJson({body,key_id,nonce,timestamp}))
+ *   X-Admin-Timestamp     — ISO 8601 UTC timestamp
+ *   X-Admin-Nonce         — UUID v4 replay-protection token
+ *
+ * Canonical JSON matches Python json.dumps(..., sort_keys=True, separators=(",",":")):
+ * keys are recursively sorted, output is compact with no whitespace.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalJson = canonicalJson;
+exports.signBytes = signBytes;
+exports.buildAdminHeaders = buildAdminHeaders;
+const node_crypto_1 = require("node:crypto");
+/** Recursively produce compact sorted JSON — stable across Python and Node.js. */
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(canonicalJson).join(',') + ']';
+    const keys = Object.keys(value).sort();
+    const pairs = keys.map(k => `${JSON.stringify(k)}:${canonicalJson(value[k])}`);
+    return '{' + pairs.join(',') + '}';
+}
+/**
+ * PKCS8 DER prefix for an Ed25519 private key.
+ * Layout: SEQUENCE { INTEGER 0, SEQUENCE { OID 1.3.101.112 }, OCTET STRING { OCTET STRING <seed> } }
+ * Concatenate with the 32-byte seed to form a valid PKCS8 DER buffer.
+ */
+const ED25519_PKCS8_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+/** Sign raw bytes with an Ed25519 seed (32-byte base64-encoded private key seed). */
+function signBytes(message, seedBase64) {
+    const seed = Buffer.from(seedBase64, 'base64');
+    const pkcs8 = Buffer.concat([ED25519_PKCS8_PREFIX, seed]);
+    const privateKey = (0, node_crypto_1.createPrivateKey)({ key: pkcs8, format: 'der', type: 'pkcs8' });
+    return (0, node_crypto_1.sign)(null, message, privateKey);
+}
+/** Build the four admin auth headers for a given request body. */
+function buildAdminHeaders(body, keyId, signingKeyBase64) {
+    const timestamp = new Date().toISOString();
+    const nonce = (0, node_crypto_1.randomUUID)();
+    const canonical = canonicalJson({ body, key_id: keyId, nonce, timestamp });
+    const sig = signBytes(Buffer.from(canonical, 'utf-8'), signingKeyBase64);
+    return {
+        'X-Admin-Key-Id': keyId,
+        'X-Admin-Signature': sig.toString('base64'),
+        'X-Admin-Timestamp': timestamp,
+        'X-Admin-Nonce': nonce,
+    };
+}

package/dist/cjs/boundary.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BoundaryClient = void 0;
+class BoundaryClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Issue a signed boundary decision for a capability request (admin). */
+    decide(params) {
+        return this.http.adminPost('/admin/boundary/decide', params);
+    }
+    /** Verify a boundary decision signature (unauthenticated). */
+    verify(params) {
+        return this.http.publicPost('/boundary/verify', params);
+    }
+}
+exports.BoundaryClient = BoundaryClient;

package/dist/cjs/client.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * HTTP transport layer for the Genesis Mesh SDK.
+ * Handles request dispatch, response parsing, and error mapping.
+ * Admin-route authentication is delegated to auth.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpTransport = void 0;
+const auth_js_1 = require("./auth.js");
+const errors_js_1 = require("./errors.js");
+class HttpTransport {
+    baseUrl;
+    signingKeyBase64;
+    keyId;
+    timeout;
+    _fetch;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.signingKeyBase64 = options.signingKeyBase64;
+        this.keyId = options.keyId ?? 'operator-local';
+        this.timeout = options.timeout ?? 10_000;
+        this._fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    async adminPost(path, body) {
+        if (!this.signingKeyBase64) {
+            throw new Error('signingKeyBase64 is required for admin routes');
+        }
+        const adminHeaders = (0, auth_js_1.buildAdminHeaders)(body, this.keyId, this.signingKeyBase64);
+        return this._post(path, body, adminHeaders);
+    }
+    async publicPost(path, body) {
+        return this._post(path, body, {});
+    }
+    async publicGet(path) {
+        const url = this.baseUrl + path;
+        let response;
+        try {
+            response = await this._fetch(url, {
+                method: 'GET',
+                signal: AbortSignal.timeout(this.timeout),
+            });
+        }
+        catch (err) {
+            throw new errors_js_1.NetworkError(`GET ${path} failed: ${err.message}`);
+        }
+        return this._parse(response);
+    }
+    async _post(path, body, extraHeaders) {
+        const url = this.baseUrl + path;
+        let response;
+        try {
+            response = await this._fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', ...extraHeaders },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(this.timeout),
+            });
+        }
+        catch (err) {
+            throw new errors_js_1.NetworkError(`POST ${path} failed: ${err.message}`);
+        }
+        return this._parse(response);
+    }
+    async _parse(response) {
+        let data;
+        try {
+            data = await response.json();
+        }
+        catch {
+            throw new errors_js_1.NetworkError(`Failed to parse response body (HTTP ${response.status})`);
+        }
+        if (!response.ok) {
+            throw (0, errors_js_1.fromHttpError)(response.status, data);
+        }
+        return data;
+    }
+}
+exports.HttpTransport = HttpTransport;

package/dist/cjs/consensus.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsensusClient = void 0;
+class ConsensusClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Cast a validator vote signed by the NA (admin). */
+    vote(params) {
+        return this.http.adminPost('/admin/consensus/vote', params);
+    }
+    /** Assemble a consensus proof from votes (admin). */
+    proof(params) {
+        return this.http.adminPost('/admin/consensus/proof', params);
+    }
+    /** Verify consensus proof signature and threshold (unauthenticated). */
+    verify(params) {
+        return this.http.publicPost('/consensus/verify', params);
+    }
+}
+exports.ConsensusClient = ConsensusClient;

package/dist/cjs/data_usage.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataUsageClient = void 0;
+class DataUsageClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Create and sign a data license policy (admin). */
+    createPolicy(params) {
+        return this.http.adminPost('/admin/data-usage/policy', params);
+    }
+    /** Create and sign a data access intent (admin). */
+    createIntent(params) {
+        return this.http.adminPost('/admin/data-usage/intent', params);
+    }
+    /** Get the currently active data license policy (unauthenticated). */
+    getPolicy() {
+        return this.http.publicGet('/data-usage/policy');
+    }
+    /** Verify a data access intent against a policy (unauthenticated). */
+    verify(params) {
+        return this.http.publicPost('/data-usage/verify', params);
+    }
+}
+exports.DataUsageClient = DataUsageClient;

package/dist/cjs/disclosure.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DisclosureClient = void 0;
+class DisclosureClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Commit to a set of capabilities under an agreement (admin). */
+    commit(params) {
+        return this.http.adminPost('/admin/disclosure/commit', params);
+    }
+    /** Issue a one-time nullifier for a proof (admin). */
+    nullifier(params) {
+        return this.http.adminPost('/admin/disclosure/nullifier', params);
+    }
+    /** Generate a Merkle membership proof (unauthenticated). */
+    prove(params) {
+        return this.http.publicPost('/disclosure/prove', params);
+    }
+    /** Verify a capability membership proof (unauthenticated). */
+    verify(params) {
+        return this.http.publicPost('/disclosure/verify', params);
+    }
+}
+exports.DisclosureClient = DisclosureClient;