trustdex 0.9.0 → 0.11.0

package/schemas/effective-runtime-tools-v1.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/grigent/trustdex/blob/main/schemas/effective-runtime-tools-v1.schema.json",
+  "title": "TrustDex effective runtime tool boundary v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion", "kind", "createdAt", "runtime", "capturedAt", "captureMethod",
+    "bindingDigest", "inventoryDigest", "status", "summary", "servers", "digest"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "agent-effective-tool-boundary" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "runtime": { "enum": ["claude", "codex"] },
+    "capturedAt": { "type": "string", "format": "date-time" },
+    "captureMethod": { "enum": ["runtime-export", "runtime-adapter"] },
+    "bindingDigest": { "$ref": "#/$defs/digest" },
+    "inventoryDigest": { "$ref": "#/$defs/digest" },
+    "status": { "enum": ["matched", "restricted", "needs-review", "block"] },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "configuredServerCount", "observedServerCount", "observedToolCount", "matchedCount",
+        "reviewCount", "blockedCount", "unexpectedCount", "notObservedCount"
+      ],
+      "properties": {
+        "configuredServerCount": { "$ref": "#/$defs/count" },
+        "observedServerCount": { "$ref": "#/$defs/count" },
+        "observedToolCount": { "$ref": "#/$defs/count" },
+        "matchedCount": { "$ref": "#/$defs/count" },
+        "reviewCount": { "$ref": "#/$defs/count" },
+        "blockedCount": { "$ref": "#/$defs/count" },
+        "unexpectedCount": { "$ref": "#/$defs/count" },
+        "notObservedCount": { "$ref": "#/$defs/count" }
+      }
+    },
+    "servers": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/server" }
+    },
+    "digest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "count": { "type": "integer", "minimum": 0 },
+    "server": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name", "configured", "observed", "toolCount", "sourceDecision", "provenanceStatus",
+        "automaticGrant", "bindingStatus", "status"
+      ],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "configured": { "type": "boolean" },
+        "observed": { "type": "boolean" },
+        "toolCount": { "oneOf": [{ "$ref": "#/$defs/count" }, { "type": "null" }] },
+        "sourceDecision": { "oneOf": [{ "enum": ["allow", "ask", "block"] }, { "type": "null" }] },
+        "provenanceStatus": { "oneOf": [{ "enum": ["unknown", "verified", "mismatch"] }, { "type": "null" }] },
+        "automaticGrant": { "oneOf": [{ "enum": ["none", "scoped", "all"] }, { "type": "null" }] },
+        "bindingStatus": { "oneOf": [{ "enum": ["not-granted", "bound", "needs-review", "blocked"] }, { "type": "null" }] },
+        "status": { "enum": ["matched", "not-observed", "needs-review", "blocked", "unexpected"] }
+      }
+    }
+  }
+}

package/schemas/effective-runtime-tools-v2.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/grigent/trustdex/blob/main/schemas/effective-runtime-tools-v2.schema.json",
+  "title": "TrustDex authenticated effective runtime tool boundary v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion", "kind", "createdAt", "runtime", "capturedAt", "captureMethod",
+    "bindingDigest", "inventoryDigest", "inventoryAuthentication", "producerKeyId",
+    "attestationDigest", "status", "summary", "servers", "digest"
+  ],
+  "allOf": [
+    {
+      "if": {
+        "properties": { "inventoryAuthentication": { "const": "verified" } },
+        "required": ["inventoryAuthentication"]
+      },
+      "then": {
+        "properties": {
+          "producerKeyId": { "$ref": "#/$defs/digest" },
+          "attestationDigest": { "$ref": "#/$defs/digest" }
+        }
+      },
+      "else": {
+        "properties": {
+          "producerKeyId": { "type": "null" },
+          "attestationDigest": { "type": "null" }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "inventoryAuthentication": { "const": "unverified" } },
+        "required": ["inventoryAuthentication"]
+      },
+      "then": {
+        "properties": { "status": { "enum": ["needs-review", "block"] } }
+      }
+    }
+  ],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "kind": { "const": "agent-effective-tool-boundary" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "runtime": { "enum": ["claude", "codex"] },
+    "capturedAt": { "type": "string", "format": "date-time" },
+    "captureMethod": { "enum": ["runtime-export", "runtime-adapter"] },
+    "bindingDigest": { "$ref": "#/$defs/digest" },
+    "inventoryDigest": { "$ref": "#/$defs/digest" },
+    "inventoryAuthentication": { "enum": ["unverified", "verified"] },
+    "producerKeyId": { "oneOf": [{ "$ref": "#/$defs/digest" }, { "type": "null" }] },
+    "attestationDigest": { "oneOf": [{ "$ref": "#/$defs/digest" }, { "type": "null" }] },
+    "status": { "enum": ["matched", "restricted", "needs-review", "block"] },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "configuredServerCount", "observedServerCount", "observedToolCount", "matchedCount",
+        "reviewCount", "blockedCount", "unexpectedCount", "notObservedCount"
+      ],
+      "properties": {
+        "configuredServerCount": { "$ref": "#/$defs/count" },
+        "observedServerCount": { "$ref": "#/$defs/count" },
+        "observedToolCount": { "$ref": "#/$defs/count" },
+        "matchedCount": { "$ref": "#/$defs/count" },
+        "reviewCount": { "$ref": "#/$defs/count" },
+        "blockedCount": { "$ref": "#/$defs/count" },
+        "unexpectedCount": { "$ref": "#/$defs/count" },
+        "notObservedCount": { "$ref": "#/$defs/count" }
+      }
+    },
+    "servers": { "type": "array", "items": { "$ref": "#/$defs/server" } },
+    "digest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "count": { "type": "integer", "minimum": 0 },
+    "server": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name", "configured", "observed", "toolCount", "sourceDecision", "provenanceStatus",
+        "automaticGrant", "bindingStatus", "status"
+      ],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "configured": { "type": "boolean" },
+        "observed": { "type": "boolean" },
+        "toolCount": { "oneOf": [{ "$ref": "#/$defs/count" }, { "type": "null" }] },
+        "sourceDecision": { "oneOf": [{ "enum": ["allow", "ask", "block"] }, { "type": "null" }] },
+        "provenanceStatus": { "oneOf": [{ "enum": ["unknown", "verified", "mismatch"] }, { "type": "null" }] },
+        "automaticGrant": { "oneOf": [{ "enum": ["none", "scoped", "all"] }, { "type": "null" }] },
+        "bindingStatus": { "oneOf": [{ "enum": ["not-granted", "bound", "needs-review", "blocked"] }, { "type": "null" }] },
+        "status": { "enum": ["matched", "not-observed", "needs-review", "blocked", "unexpected"] }
+      }
+    }
+  }
+}

package/schemas/runtime-tool-inventory-attestation-v1.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/grigent/trustdex/blob/main/schemas/runtime-tool-inventory-attestation-v1.schema.json",
+  "title": "TrustDex signed runtime tool inventory attestation v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion", "kind", "algorithm", "inventoryDigest", "runtime", "capturedAt",
+    "captureMethod", "producerKeyId", "createdAt", "expiresAt", "signature"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "agent-runtime-tool-inventory-attestation" },
+    "algorithm": { "const": "ed25519" },
+    "inventoryDigest": { "$ref": "#/$defs/digest" },
+    "runtime": { "enum": ["claude", "codex"] },
+    "capturedAt": { "type": "string", "format": "date-time" },
+    "captureMethod": { "enum": ["runtime-export", "runtime-adapter"] },
+    "producerKeyId": { "$ref": "#/$defs/digest" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "expiresAt": { "type": "string", "format": "date-time" },
+    "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$" }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  }
+}

package/schemas/runtime-tool-inventory-v1.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/grigent/trustdex/blob/main/schemas/runtime-tool-inventory-v1.schema.json",
+  "title": "TrustDex value-free runtime tool inventory v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "runtime", "capturedAt", "captureMethod", "servers"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "agent-runtime-tool-inventory" },
+    "runtime": { "enum": ["claude", "codex"] },
+    "capturedAt": { "type": "string", "format": "date-time" },
+    "captureMethod": { "enum": ["runtime-export", "runtime-adapter"] },
+    "servers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "toolCount"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "toolCount": { "type": "integer", "minimum": 0 }
+        }
+      }
+    }
+  }
+}

package/src/bindings.mjs

@@ -214,6 +214,10 @@ function validateSnapshot(snapshot) {
   return snapshot;
 }
 
+export function validateToolPermissionBindingSnapshot(snapshot) {
+  return validateSnapshot(snapshot);
+}
+
 function createSummary(bindings, input) {
   return {
     serverCount: bindings.length,

package/src/runtime-attestation.mjs

@@ -0,0 +1,202 @@
+import crypto from 'node:crypto';
+
+import { canonicalJson, sha256Json } from './canonical.mjs';
+import {
+  normalizeRuntimeToolInventory,
+  runtimeToolInventoryDigest
+} from './runtime-evidence.mjs';
+
+const KIND = 'agent-runtime-tool-inventory-attestation';
+const ALGORITHM = 'ed25519';
+const MAX_TTL_SECONDS = 86_400;
+const MAX_FUTURE_SKEW_SECONDS = 300;
+const FIELDS = new Set([
+  'schemaVersion', 'kind', 'algorithm', 'inventoryDigest', 'runtime', 'capturedAt',
+  'captureMethod', 'producerKeyId', 'createdAt', 'expiresAt', 'signature'
+]);
+
+function requireObject(value, message) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(message);
+  return value;
+}
+
+function requireExactKeys(value, expected, message) {
+  const keys = Object.keys(requireObject(value, message));
+  if (keys.length !== expected.size || keys.some((key) => !expected.has(key))) throw new Error(message);
+  return value;
+}
+
+function requireDigest(value, field) {
+  if (typeof value !== 'string' || !/^[a-f0-9]{64}$/.test(value)) {
+    throw new Error(`Invalid runtime inventory attestation digest: ${field}`);
+  }
+  return value;
+}
+
+function requireTimestamp(value, field) {
+  if (typeof value !== 'string' || Number.isNaN(Date.parse(value)) ||
+      new Date(value).toISOString() !== value) {
+    throw new Error(`Invalid runtime inventory attestation timestamp: ${field}`);
+  }
+  return value;
+}
+
+function publicKeyId(publicKey) {
+  const key = publicKey?.type === 'public' ? publicKey : crypto.createPublicKey(publicKey);
+  if (key.asymmetricKeyType !== 'ed25519') {
+    throw new Error('Runtime inventory attestations require an Ed25519 key.');
+  }
+  const der = key.export({ type: 'spki', format: 'der' });
+  return crypto.createHash('sha256').update(der).digest('hex');
+}
+
+function payload(record) {
+  return {
+    schemaVersion: record.schemaVersion,
+    kind: record.kind,
+    algorithm: record.algorithm,
+    inventoryDigest: record.inventoryDigest,
+    runtime: record.runtime,
+    capturedAt: record.capturedAt,
+    captureMethod: record.captureMethod,
+    producerKeyId: record.producerKeyId,
+    createdAt: record.createdAt,
+    expiresAt: record.expiresAt
+  };
+}
+
+export function validateRuntimeInventoryAttestation(record) {
+  requireExactKeys(record, FIELDS, 'Invalid runtime inventory attestation.');
+  if (record.schemaVersion !== 1 || record.kind !== KIND || record.algorithm !== ALGORITHM) {
+    throw new Error('Unsupported runtime inventory attestation schema.');
+  }
+  requireDigest(record.inventoryDigest, 'inventoryDigest');
+  requireDigest(record.producerKeyId, 'producerKeyId');
+  if (!['claude', 'codex'].includes(record.runtime)) throw new Error('Invalid attested runtime.');
+  if (!['runtime-export', 'runtime-adapter'].includes(record.captureMethod)) {
+    throw new Error('Invalid attested capture method.');
+  }
+  requireTimestamp(record.capturedAt, 'capturedAt');
+  requireTimestamp(record.createdAt, 'createdAt');
+  requireTimestamp(record.expiresAt, 'expiresAt');
+  if (Date.parse(record.expiresAt) <= Date.parse(record.createdAt)) {
+    throw new Error('Runtime inventory attestation expiry must follow creation time.');
+  }
+  if (Date.parse(record.expiresAt) - Date.parse(record.createdAt) > MAX_TTL_SECONDS * 1000) {
+    throw new Error('Runtime inventory attestation lifetime exceeds 24 hours.');
+  }
+  if (Date.parse(record.capturedAt) > Date.parse(record.createdAt) + MAX_FUTURE_SKEW_SECONDS * 1000) {
+    throw new Error('Runtime inventory capture cannot postdate attestation creation by more than five minutes.');
+  }
+  if (typeof record.signature !== 'string' ||
+      !/^[A-Za-z0-9+/]{86}==$/.test(record.signature) ||
+      Buffer.from(record.signature, 'base64').toString('base64') !== record.signature) {
+    throw new Error('Invalid runtime inventory attestation signature.');
+  }
+  return record;
+}
+
+export function createRuntimeInventoryAttestation(inventoryInput, privateKeyPem, options = {}) {
+  const inventory = normalizeRuntimeToolInventory(inventoryInput);
+  const ttlSeconds = options.ttlSeconds === undefined ? 300 : options.ttlSeconds;
+  if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > MAX_TTL_SECONDS) {
+    throw new Error('Runtime inventory attestation TTL must be an integer from 1 to 86400 seconds.');
+  }
+  const createdAt = options.createdAt || new Date().toISOString();
+  requireTimestamp(createdAt, 'createdAt');
+  if (Date.parse(inventory.capturedAt) > Date.parse(createdAt) + MAX_FUTURE_SKEW_SECONDS * 1000) {
+    throw new Error('Runtime inventory capture cannot postdate attestation creation by more than five minutes.');
+  }
+  const expiresAt = new Date(Date.parse(createdAt) + ttlSeconds * 1000).toISOString();
+  const publicKey = crypto.createPublicKey(privateKeyPem);
+  const record = {
+    schemaVersion: 1,
+    kind: KIND,
+    algorithm: ALGORITHM,
+    inventoryDigest: runtimeToolInventoryDigest(inventory),
+    runtime: inventory.runtime,
+    capturedAt: inventory.capturedAt,
+    captureMethod: inventory.captureMethod,
+    producerKeyId: publicKeyId(publicKey),
+    createdAt,
+    expiresAt
+  };
+  const signature = crypto.sign(
+    null,
+    Buffer.from(canonicalJson(payload(record))),
+    privateKeyPem
+  );
+  return { ...record, signature: signature.toString('base64') };
+}
+
+function invalid(reason) {
+  return { valid: false, reason, producerKeyId: null, inventoryDigest: null, attestationDigest: null };
+}
+
+export function verifyRuntimeInventoryAttestation(inventoryInput, recordInput, publicKeyPem, options = {}) {
+  let inventory;
+  let record;
+  try {
+    inventory = normalizeRuntimeToolInventory(inventoryInput);
+    record = validateRuntimeInventoryAttestation(recordInput);
+  } catch (error) {
+    return invalid(error.message);
+  }
+
+  let keyId;
+  try { keyId = publicKeyId(publicKeyPem); } catch {
+    return invalid('Invalid runtime inventory attestation public key.');
+  }
+  if (record.producerKeyId !== keyId) return invalid('Runtime inventory producer key does not match.');
+  const inventoryDigest = runtimeToolInventoryDigest(inventory);
+  if (record.inventoryDigest !== inventoryDigest ||
+      record.runtime !== inventory.runtime ||
+      record.capturedAt !== inventory.capturedAt ||
+      record.captureMethod !== inventory.captureMethod) {
+    return invalid('Runtime inventory does not match its attestation.');
+  }
+
+  const nowMs = options.now === undefined ? Date.now() : Date.parse(options.now);
+  if (!Number.isFinite(nowMs)) return invalid('Invalid runtime inventory verification time.');
+  if (nowMs >= Date.parse(record.expiresAt)) return invalid('Runtime inventory attestation expired.');
+  const futureSkewSeconds = options.futureSkewSeconds === undefined
+    ? MAX_FUTURE_SKEW_SECONDS
+    : options.futureSkewSeconds;
+  if (!Number.isSafeInteger(futureSkewSeconds) || futureSkewSeconds < 0) {
+    return invalid('Invalid runtime inventory future-skew limit.');
+  }
+  if (Date.parse(record.createdAt) > nowMs + futureSkewSeconds * 1000) {
+    return invalid('Runtime inventory attestation creation time is too far in the future.');
+  }
+  if (Date.parse(inventory.capturedAt) > nowMs + futureSkewSeconds * 1000) {
+    return invalid('Runtime inventory capture time is too far in the future.');
+  }
+  if (options.maxAgeSeconds !== undefined) {
+    if (!Number.isSafeInteger(options.maxAgeSeconds) || options.maxAgeSeconds < 0) {
+      return invalid('Invalid runtime inventory maximum age.');
+    }
+    if (nowMs - Date.parse(inventory.capturedAt) > options.maxAgeSeconds * 1000) {
+      return invalid('Runtime inventory capture is too old.');
+    }
+  }
+
+  let valid = false;
+  try {
+    valid = crypto.verify(
+      null,
+      Buffer.from(canonicalJson(payload(record))),
+      publicKeyPem,
+      Buffer.from(record.signature, 'base64')
+    );
+  } catch {
+    return invalid('Runtime inventory attestation signature verification failed.');
+  }
+  if (!valid) return invalid('Runtime inventory attestation signature verification failed.');
+  return {
+    valid: true,
+    reason: null,
+    producerKeyId: keyId,
+    inventoryDigest,
+    attestationDigest: sha256Json(record)
+  };
+}