genesis-mesh-sdk 0.59.0 → 0.59.1

package/dist/cjs/client.js

@@ -1,76 +1,142 @@
 "use strict";
 /**
  * HTTP transport layer for the Genesis Mesh SDK.
- * Handles request dispatch, response parsing, and error mapping.
+ * Handles request dispatch, response parsing, error mapping and opt-in retries.
  * Admin-route authentication is delegated to auth.ts.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpTransport = void 0;
+exports.buildPath = buildPath;
 const auth_js_1 = require("./auth.js");
 const errors_js_1 = require("./errors.js");
+const RETRYABLE_STATUS = new Set([429, 502, 503, 504]);
+function buildPath(path, query) {
+    if (!query)
+        return path;
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined && value !== null)
+            params.append(key, String(value));
+    }
+    const qs = params.toString();
+    return qs ? `${path}?${qs}` : path;
+}
 class HttpTransport {
     baseUrl;
-    signingKeyBase64;
+    /** Key ID sent in X-Admin-Key-Id. */
     keyId;
+    signer;
     timeout;
+    retry;
+    headers;
     _fetch;
     constructor(options) {
         this.baseUrl = options.baseUrl.replace(/\/$/, '');
-        this.signingKeyBase64 = options.signingKeyBase64;
-        this.keyId = options.keyId ?? 'operator-local';
+        this.signer = options.signer
+            ?? (options.signingKeyBase64
+                ? (0, auth_js_1.seedSigner)(options.signingKeyBase64, options.keyId ?? 'operator-local')
+                : undefined);
+        this.keyId = this.signer?.keyId ?? options.keyId ?? 'operator-local';
         this.timeout = options.timeout ?? 10_000;
+        this.retry = { attempts: options.retry?.attempts ?? 0, baseDelayMs: options.retry?.baseDelayMs ?? 200 };
+        if (!Number.isSafeInteger(this.retry.attempts) || this.retry.attempts < 0 || this.retry.attempts > 10
+            || !Number.isFinite(this.retry.baseDelayMs) || this.retry.baseDelayMs < 0 || this.retry.baseDelayMs > 60_000) {
+            throw new Error('retry requires 0..10 attempts and a finite baseDelayMs between 0 and 60000');
+        }
+        this.headers = options.headers ?? {};
         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);
+    /** Signed admin POST. Not retried unless `idempotent` is set. */
+    async adminPost(path, body, idempotent = false) {
+        const response = await this._send({ method: 'POST', path, body, admin: true, idempotent });
+        return this._parse(response);
     }
-    async publicPost(path, body) {
-        return this._post(path, body, {});
+    /** Signed admin GET (the NA verifies the signature over an empty body). */
+    async adminGet(path, query) {
+        const response = await this._send({ method: 'GET', path, query, admin: true, idempotent: true });
+        return this._parse(response);
     }
-    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}`);
-        }
+    /** Signed admin GET returning the raw response text (e.g. NDJSON export). */
+    async adminGetText(path, query) {
+        const response = await this._send({ method: 'GET', path, query, admin: true, idempotent: true });
+        if (!response.ok)
+            return this._parse(response);
+        return response.text();
+    }
+    /** Unauthenticated POST. Verification routes are idempotent; pass `true` to allow retries. */
+    async publicPost(path, body, idempotent = false) {
+        const response = await this._send({ method: 'POST', path, body, admin: false, idempotent });
+        return this._parse(response);
+    }
+    async publicGet(path, query) {
+        const response = await this._send({ method: 'GET', path, query, admin: false, idempotent: true });
         return this._parse(response);
     }
-    async _post(path, body, extraHeaders) {
-        const url = this.baseUrl + path;
-        let response;
+    async _send(spec) {
+        const attempts = spec.idempotent ? this.retry.attempts : 0;
+        for (let attempt = 0;; attempt++) {
+            try {
+                const response = await this._once(spec);
+                if (attempt < attempts && RETRYABLE_STATUS.has(response.status)) {
+                    await this._backoff(attempt);
+                    continue;
+                }
+                let body;
+                try {
+                    body = await response.text();
+                }
+                catch {
+                    throw new errors_js_1.NetworkError(`Failed to read response body (${spec.method} ${spec.path})`);
+                }
+                return { ok: response.ok, status: response.status, text: async () => body };
+            }
+            catch (err) {
+                if (attempt < attempts && err instanceof errors_js_1.NetworkError) {
+                    await this._backoff(attempt);
+                    continue;
+                }
+                throw err;
+            }
+        }
+    }
+    async _once(spec) {
+        const headers = { ...this.headers };
+        if (spec.admin) {
+            if (!this.signer) {
+                throw new Error('signingKeyBase64 is required for admin routes (or pass a signer)');
+            }
+            Object.assign(headers, await (0, auth_js_1.buildAdminHeadersWithSigner)(spec.method === 'GET' ? {} : spec.body, this.signer));
+        }
+        const init = { method: spec.method, headers, signal: AbortSignal.timeout(this.timeout) };
+        if (spec.method === 'POST') {
+            headers['Content-Type'] = 'application/json';
+            init.body = (0, auth_js_1.canonicalJson)(spec.body);
+        }
+        const path = buildPath(spec.path, spec.query);
         try {
-            response = await this._fetch(url, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...extraHeaders },
-                body: JSON.stringify(body),
-                signal: AbortSignal.timeout(this.timeout),
-            });
+            return await this._fetch(this.baseUrl + path, init);
         }
         catch (err) {
-            throw new errors_js_1.NetworkError(`POST ${path} failed: ${err.message}`);
+            throw new errors_js_1.NetworkError(`${spec.method} ${spec.path} failed: ${err.message}`);
         }
-        return this._parse(response);
+    }
+    _backoff(attempt) {
+        const delay = Math.min(60_000, this.retry.baseDelayMs * 2 ** attempt);
+        return new Promise(resolve => setTimeout(resolve, delay));
     }
     async _parse(response) {
         let data;
         try {
-            data = await response.json();
+            data = (0, auth_js_1.parseJson)(await response.text());
         }
         catch {
+            if (!response.ok) {
+                throw new errors_js_1.GenesisMeshError(`HTTP ${response.status} with a non-JSON body`, 'unknown', response.status);
+            }
             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);
+            throw (0, errors_js_1.fromHttpError)(response.status, (data ?? {}));
         }
         return data;
     }

package/dist/cjs/errors.js

@@ -1,11 +1,15 @@
 "use strict";
 /** Typed error classes mirroring the NA HTTP error surface. */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BadRequestError = exports.NetworkError = exports.RateLimitError = exports.NotFoundError = exports.ValidationError = exports.UnauthorizedError = exports.GenesisMeshError = void 0;
+exports.BadRequestError = exports.NetworkError = exports.RateLimitError = exports.NotFoundError = exports.ServiceUnavailableError = exports.ConflictError = exports.ForbiddenError = exports.ValidationError = exports.UnauthorizedError = exports.GenesisMeshError = void 0;
 exports.fromHttpError = fromHttpError;
 class GenesisMeshError extends Error {
     code;
     status;
+    /** Structured `error.details` from the NA envelope (empty when absent). */
+    details = {};
+    /** `error.request_id` from the NA envelope, for correlating with NA logs. */
+    requestId = null;
     constructor(message, code, status) {
         super(message);
         this.name = 'GenesisMeshError';
@@ -29,6 +33,28 @@ class ValidationError extends GenesisMeshError {
     }
 }
 exports.ValidationError = ValidationError;
+class ForbiddenError extends GenesisMeshError {
+    constructor(message = 'Forbidden', code = 'forbidden') {
+        super(message, code, 403);
+        this.name = 'ForbiddenError';
+    }
+}
+exports.ForbiddenError = ForbiddenError;
+/** 409: the request conflicts with stored state (e.g. `evidence_conflict`, `executor_key_exists`). */
+class ConflictError extends GenesisMeshError {
+    constructor(message, code = 'conflict') {
+        super(message, code, 409);
+        this.name = 'ConflictError';
+    }
+}
+exports.ConflictError = ConflictError;
+class ServiceUnavailableError extends GenesisMeshError {
+    constructor(message = 'Service unavailable', code = 'service_unavailable') {
+        super(message, code, 503);
+        this.name = 'ServiceUnavailableError';
+    }
+}
+exports.ServiceUnavailableError = ServiceUnavailableError;
 class NotFoundError extends GenesisMeshError {
     constructor(message, code = 'not_found') {
         super(message, code, 404);
@@ -67,21 +93,37 @@ function fromHttpError(status, body) {
     const errorField = body['error'];
     let message;
     let code;
+    let details;
+    let requestId;
     if (typeof errorField === 'object' && errorField !== null) {
         const nested = errorField;
         message = String(nested['message'] ?? 'Unknown error');
         code = String(nested['code'] ?? 'unknown');
+        details = nested['details'];
+        requestId = nested['request_id'];
     }
     else {
         message = String(errorField ?? body['message'] ?? 'Unknown error');
         code = String(body['code'] ?? 'unknown');
     }
+    const error = errorForStatus(status, message, code);
+    if (typeof details === 'object' && details !== null && !Array.isArray(details)) {
+        error.details = details;
+    }
+    if (typeof requestId === 'string')
+        error.requestId = requestId;
+    return error;
+}
+function errorForStatus(status, message, code) {
     switch (status) {
         case 400: return new BadRequestError(message, code);
         case 401: return new UnauthorizedError(message, code);
+        case 403: return new ForbiddenError(message, code);
         case 404: return new NotFoundError(message, code);
+        case 409: return new ConflictError(message, code);
         case 422: return new ValidationError(message, code);
         case 429: return new RateLimitError(message, code);
+        case 503: return new ServiceUnavailableError(message, code);
         default: return new GenesisMeshError(message, code, status);
     }
 }

package/dist/cjs/evidence_store.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceStoreClient = void 0;
+const execution_js_1 = require("./execution.js");
+const canonical_js_1 = require("./canonical.js");
+const errors_js_1 = require("./errors.js");
+const verify_js_1 = require("./verify.js");
+const MAX_PAGE = 1000;
+function resourcePath(resourceId) {
+    return resourceId.split('/').map(encodeURIComponent).join('/');
+}
+/** The NA evidence store (v0.59): controller submission, operator search, history, export. */
+class EvidenceStoreClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Submit one signed ExecutionEvidence record. Authenticated by the executor
+     * signature, not by operator headers. An identical resubmission returns
+     * `status: "duplicate"`, so it is safe to retry.
+     */
+    async submit(evidence) {
+        const reason = (0, execution_js_1.checkMetadataOnly)(evidence.execution_parameters, evidence.outcome_detail);
+        if (reason)
+            throw new execution_js_1.SecretMaterialError(reason);
+        return this.http.publicPost('/evidence/execution', { evidence }, true);
+    }
+    /** Search stored entries (admin). Use `next_after_sequence` as the next `after_sequence`. */
+    search(params = {}) {
+        return this.http.adminGet('/admin/evidence', { ...params });
+    }
+    /** Every matching entry, following pages (admin). */
+    async *iterate(params = {}) {
+        let after = 0;
+        while (after !== null) {
+            const page = await this.search({ ...params, after_sequence: after });
+            if (page.next_after_sequence !== null && (!Number.isSafeInteger(page.next_after_sequence) || page.next_after_sequence <= after)) {
+                throw new Error('evidence search cursor did not advance');
+            }
+            yield* page.entries;
+            after = page.next_after_sequence;
+        }
+    }
+    /** Store mode, size, last sequence and retention checkpoint (admin). */
+    status() {
+        return this.http.adminGet('/admin/evidence/status');
+    }
+    /** Verify every stored entry, chain and signature on the NA (admin). */
+    verify() {
+        return this.http.adminGet('/admin/evidence/verify');
+    }
+    /** One resource's full history, decision to execution, verified by the NA (admin). */
+    resourceHistory(resourceId) {
+        return this.http.adminGet(`/admin/evidence/resources/${resourcePath(resourceId)}`);
+    }
+    /** A vendor's decisions and the evidence under them, verified by the NA (admin). */
+    vendorHistory(vendorId) {
+        return this.http.adminGet(`/admin/evidence/vendors/${encodeURIComponent(vendorId)}`);
+    }
+    /** One page of `gm.evidence.event` JSON Lines, unparsed (admin). */
+    exportText(params = {}) {
+        return this.http.adminGetText('/admin/evidence/export', { ...params });
+    }
+    /** One page of export events, parsed (admin). */
+    async export(params = {}) {
+        return (0, verify_js_1.parseExportLines)(await this.exportText(params));
+    }
+    /** Every event from `since_sequence` onward, following pages - an incremental SIEM pull (admin). */
+    async *exportAll(sinceSequence = 0, pageSize = MAX_PAGE) {
+        if (!Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > MAX_PAGE
+            || !Number.isSafeInteger(sinceSequence) || sinceSequence < 0) {
+            throw new Error('export requires a nonnegative cursor and page size between 1 and 1000');
+        }
+        let since = sinceSequence;
+        for (;;) {
+            const events = await this.export({ since_sequence: since, limit: pageSize });
+            if (events.length && events[events.length - 1].entry.store_sequence <= since) {
+                throw new Error('evidence export cursor did not advance');
+            }
+            yield* events;
+            if (events.length < pageSize)
+                return;
+            since = events[events.length - 1].entry.store_sequence;
+        }
+    }
+    /** Registered executor keys, retired keys included (admin). */
+    async listExecutorKeys() {
+        const body = await this.http.adminGet('/admin/evidence/executor-keys');
+        return body.executor_keys;
+    }
+    /** Register a controller's executor signing key (admin, privileged). */
+    registerExecutorKey(params) {
+        return this.http.adminPost('/admin/evidence/executor-keys', params);
+    }
+    /** Retire an executor key: it still verifies old records and can sign no new ones (admin, privileged). */
+    retireExecutorKey(keyId) {
+        return this.http.adminPost(`/admin/evidence/executor-keys/${encodeURIComponent(keyId)}/retire`, {});
+    }
+    /** Remove entries older than `olderThanDays` behind a signed checkpoint (admin, privileged). */
+    applyRetention(olderThanDays) {
+        return this.http.adminPost('/admin/evidence/retention/apply', { older_than_days: olderThanDays });
+    }
+    /** The most recent retention checkpoint in the store, or null (admin). */
+    async latestCheckpoint() {
+        let latest = null;
+        for await (const event of this.iterate({ entry_kind: 'retention_checkpoint' })) {
+            latest = event.payload;
+        }
+        return latest;
+    }
+    /**
+     * The head of a resource chain - what the next record must link to - or null
+     * for a resource with no history. Falls back to the latest retention
+     * checkpoint when retention removed every stored record (admin).
+     */
+    async resourceHead(resourceId) {
+        let history;
+        try {
+            history = await this.resourceHistory(resourceId);
+        }
+        catch (err) {
+            if (err instanceof errors_js_1.NotFoundError && err.code === 'resource_not_found') {
+                return (await this.latestCheckpoint())?.resource_heads[resourceId] ?? null;
+            }
+            throw err;
+        }
+        if (!history.verification?.verified)
+            throw new Error('resource history did not verify');
+        let head = null;
+        for (const event of history.entries) {
+            if (event.entry.entry_kind !== 'execution')
+                continue;
+            const record = event.payload;
+            if (record.resource_id !== resourceId || record.resource_sequence === undefined)
+                continue;
+            if (!head || record.resource_sequence > head.resource_sequence) {
+                head = { resource_sequence: record.resource_sequence, record_digest: (0, canonical_js_1.executionDigest)(record) };
+            }
+        }
+        return head;
+    }
+    /**
+     * Latest state of every resource with stored execution evidence, for
+     * reconciliation against a cloud inventory (admin).
+     */
+    async resourceStates() {
+        const states = new Map();
+        for await (const event of this.iterate({ entry_kind: 'execution' })) {
+            const record = event.payload;
+            if (record.resource_id === undefined || record.resource_sequence === undefined)
+                continue;
+            const previous = states.get(record.resource_id);
+            if (previous && previous.resource_sequence >= record.resource_sequence)
+                continue;
+            const success = record.outcome === 'success';
+            states.set(record.resource_id, {
+                resource_id: record.resource_id,
+                resource_sequence: record.resource_sequence,
+                record_digest: (0, canonical_js_1.executionDigest)(record),
+                last_action: record.resource_action ?? null,
+                last_outcome: record.outcome,
+                last_success_action: success ? record.resource_action ?? null : previous?.last_success_action ?? null,
+                last_success_parameters: success ? record.execution_parameters : previous?.last_success_parameters ?? null,
+                last_executed_at: record.executed_at,
+                last_decision_id: record.decision_id,
+            });
+        }
+        return states;
+    }
+}
+exports.EvidenceStoreClient = EvidenceStoreClient;

package/dist/cjs/execution.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Execution evidence: build and sign records exactly as the Python reference
+ * `record_execution` does, and refuse secret material before anything is signed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionRecorder = exports.SecretMaterialError = exports.MAX_METADATA_BYTES = void 0;
+exports.checkMetadataOnly = checkMetadataOnly;
+const node_crypto_1 = require("node:crypto");
+const auth_js_1 = require("./auth.js");
+const canonical_js_1 = require("./canonical.js");
+const errors_js_1 = require("./errors.js");
+/** Limit on execution_parameters + outcome_detail, as enforced by the NA. */
+exports.MAX_METADATA_BYTES = 16 * 1024;
+const SECRET_KEYS = new Set([
+    'value', 'secret', 'secretvalue', 'password', 'passwd', 'passphrase', 'token',
+    'accesstoken', 'refreshtoken', 'bearer', 'privatekey', 'keymaterial',
+    'credential', 'credentials', 'clientsecret', 'apikey', 'pem', 'connectionstring',
+]);
+const LONG_OPAQUE = /^[A-Za-z0-9+/=_-]{120,}$/;
+const JWT = /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*$/;
+/** Thrown before signing when a record would carry secret material; the NA would refuse it. */
+class SecretMaterialError extends errors_js_1.GenesisMeshError {
+    constructor(message) {
+        super(message, 'evidence_secret_material', 0);
+        this.name = 'SecretMaterialError';
+    }
+}
+exports.SecretMaterialError = SecretMaterialError;
+function normaliseKey(key) {
+    return key.toLowerCase().replace(/[-_.]/g, '');
+}
+function secretMaterial(value, path = '') {
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            const found = secretMaterial(value[i], `${path}${i}.`);
+            if (found)
+                return found;
+        }
+    }
+    else if (value !== null && typeof value === 'object') {
+        for (const [key, inner] of Object.entries(value)) {
+            if (SECRET_KEYS.has(normaliseKey(key)))
+                return `field '${path}${key}' is not allowed in evidence metadata`;
+            const found = secretMaterial(inner, `${path}${key}.`);
+            if (found)
+                return found;
+        }
+    }
+    else if (typeof value === 'string') {
+        const field = path.replace(/\.$/, '');
+        if (value.includes('-----BEGIN'))
+            return `field '${field}' contains a PEM block`;
+        if (LONG_OPAQUE.test(value) || JWT.test(value))
+            return `field '${field}' looks like key or token material`;
+    }
+    return null;
+}
+/**
+ * Why the metadata would be refused as secret material, or null. A guard, not a
+ * guarantee: send identifiers, versions and timestamps, never secret values.
+ */
+function checkMetadataOnly(executionParameters, outcomeDetail = null) {
+    const size = Buffer.byteLength(JSON.stringify({ execution_parameters: executionParameters, outcome_detail: outcomeDetail }), 'utf-8');
+    if (size > exports.MAX_METADATA_BYTES)
+        return `metadata is ${size} bytes, over the ${exports.MAX_METADATA_BYTES}-byte limit`;
+    return secretMaterial(executionParameters) ?? (outcomeDetail ? secretMaterial({ outcome_detail: outcomeDetail }) : null);
+}
+function resourceHeadOf(prior) {
+    if ('record_digest' in prior)
+        return prior;
+    return { resource_sequence: prior.resource_sequence ?? 0, record_digest: (0, canonical_js_1.executionDigest)(prior) };
+}
+/** Builds and signs ExecutionEvidence for one executor. */
+class ExecutionRecorder {
+    executorSovereignId;
+    signer;
+    constructor(options) {
+        this.executorSovereignId = options.executorSovereignId;
+        this.signer = options.signer;
+    }
+    get keyId() {
+        return this.signer.keyId;
+    }
+    async record(params) {
+        if ((params.resource_id === undefined) !== (params.resource_action === undefined)) {
+            throw new Error('resource_id and resource_action go together');
+        }
+        const execution_parameters = params.execution_parameters ?? {};
+        const outcome_detail = params.outcome_detail ?? null;
+        const secret = checkMetadataOnly(execution_parameters, outcome_detail);
+        if (secret)
+            throw new SecretMaterialError(secret);
+        const prior = params.prior_record ?? null;
+        const record = {
+            evidence_id: params.evidence_id ?? (0, node_crypto_1.randomUUID)(),
+            sequence_no: prior ? prior.sequence_no + 1 : 1,
+            decision_id: params.decision.decision_id,
+            context_id: params.decision.context_id,
+            agreement_id: params.decision.agreement_id,
+            executor_sovereign_id: this.executorSovereignId,
+            executed_capability: params.executed_capability,
+            execution_parameters,
+            executed_at: (0, auth_js_1.pythonTimestamp)(params.executed_at ?? new Date()),
+            outcome: params.outcome,
+            outcome_detail,
+            prev_evidence_digest: prior ? (0, canonical_js_1.executionDigest)(prior) : null,
+            signature: null,
+        };
+        if (params.resource_id !== undefined && params.resource_action !== undefined) {
+            const head = params.prior_resource ? resourceHeadOf(params.prior_resource) : null;
+            record.resource_id = params.resource_id;
+            record.resource_action = params.resource_action;
+            record.resource_sequence = head ? head.resource_sequence + 1 : 1;
+            record.prev_resource_digest = head ? head.record_digest : null;
+        }
+        record.signature = await (0, auth_js_1.signCanonical)((0, canonical_js_1.executionCanonical)(record), this.signer);
+        return record;
+    }
+}
+exports.ExecutionRecorder = ExecutionRecorder;