@passioncode-ai/fabric-agent-adapter 0.19.0 → 0.21.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-estate.mjs

@@ -0,0 +1,443 @@
+// `estate-record/1` (Fabric Agent Contract DEC-0055): verify an estate revision and check its rules — the twin of
+// fabric_estate.py. The contract's src/estate-record-rules.ts, src/webauthn.ts and src/p256.ts at the pin, held to the
+// contract's own vectors (test/fixtures/contract/estate-vectors.json):
+//
+// - verifyEstateRecord(record, { at, parent } | { at, authorities }) — the verdict a machine applies a revision on, after
+//   it has checked the revision against estate-record.schema.json (the verifier does not check the schema);
+// - estateRecordRules(kind, value) — FAC-SEM-072…076;
+// - hubKeyCertified(record, kid, x, at) — DL-14: a delegation verifier that reads the estate record trusts a token's
+//   `kid` only while a current revision certifies it for a machine (fabric-delegation.mjs calls it).
+//
+// Node's own crypto: ES256 through createPublicKey (JWK) and verify (DER), EdDSA through Ed25519.
+
+import crypto from 'node:crypto';
+import { jcs } from './fabric-delegation.mjs';
+import { secretValue } from './fabric-secrets.mjs';
+
+export const ESTATE_RECORD_SCHEMA = 'estate-record/1';
+export const ESTATE_CHALLENGE_TYPE = 'estate-revision/1';
+export const MAX_VALIDITY_SECONDS = 30 * 24 * 60 * 60;
+export const ASSERTION_ALGORITHMS = Object.freeze(['ES256', 'EdDSA']);
+export const FLAGS = Object.freeze({ UP: 0x01, UV: 0x04, BE: 0x08, BS: 0x10, AT: 0x40, ED: 0x80 });
+
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isString = (value) => typeof value === 'string';
+const list = (value) => (Array.isArray(value) ? value.filter(isObject) : []);
+const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest();
+const B64URL = /^[A-Za-z0-9_-]+$/;
+const bytes = (text) => Buffer.from(text, 'base64url');
+const canonical = (text) => Buffer.from(text, 'base64url').toString('base64url') === text;
+
+const SMALL_ORDER = new Set([
+  '0000000000000000000000000000000000000000000000000000000000000000', '0100000000000000000000000000000000000000000000000000000000000000',
+  '26e8958fc2b227b045c3f489f2ef98f0d5dfac05d3c63339b13802886d53fc05', 'c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac037a',
+  'ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f', 'edffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f',
+  'eeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f',
+]);
+/** The contract's isSmallOrderKey: a key that is not 32 bytes counts as one too. */
+function smallOrder(raw) {
+  if (raw.length !== 32) return true;
+  const cleared = Buffer.from(raw);
+  cleared[31] &= 0x7f;
+  return SMALL_ORDER.has(cleared.toString('hex'));
+}
+
+// ---- P-256 (DEC-0053; SEC 1 v2 §3.2.2) ----
+
+const P = 0xffffffff00000001000000000000000000000000ffffffffffffffffffffffffn;
+const B = 0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604bn;
+const toBig = (part) => BigInt(`0x${Buffer.from(part).toString('hex')}`);
+
+/** Whether `raw` is a valid uncompressed P-256 public key: 0x04 ‖ X ‖ Y, both below p, on the curve. */
+export function isValidP256Key(raw) {
+  if (raw.length !== 65 || raw[0] !== 0x04) return false;
+  const x = toBig(raw.subarray(1, 33));
+  const y = toBig(raw.subarray(33, 65));
+  if (x >= P || y >= P) return false;
+  const left = (y * y) % P;
+  const right = (((x * x) % P) * x - 3n * x + B) % P;
+  return left === ((right % P) + P) % P;
+}
+
+// ---- WebAuthn Level 3 §7.2, offline ----
+
+/** The credential's public key, validated before use: `{key}` or `{problem: "unusable-key" | "small-order-key"}`. */
+export function credentialKey(publicKey, alg) {
+  if (!ASSERTION_ALGORITHMS.includes(alg)) return { problem: 'unusable-key' };
+  if (!isObject(publicKey) || publicKey.d !== undefined || !isString(publicKey.x) || !B64URL.test(publicKey.x) || !canonical(publicKey.x)) return { problem: 'unusable-key' };
+  if (alg === 'ES256') {
+    if (publicKey.kty !== 'EC' || publicKey.crv !== 'P-256' || !isString(publicKey.y) || !B64URL.test(publicKey.y) || !canonical(publicKey.y)) return { problem: 'unusable-key' };
+    const x = bytes(publicKey.x);
+    const y = bytes(publicKey.y);
+    if (x.length !== 32 || y.length !== 32 || !isValidP256Key(Buffer.concat([Buffer.from([4]), x, y]))) return { problem: 'unusable-key' };
+    return { key: crypto.createPublicKey({ key: { kty: 'EC', crv: 'P-256', x: publicKey.x, y: publicKey.y }, format: 'jwk' }) };
+  }
+  if (publicKey.kty !== 'OKP' || publicKey.crv !== 'Ed25519') return { problem: 'unusable-key' };
+  const raw = bytes(publicKey.x);
+  if (raw.length !== 32) return { problem: 'unusable-key' };
+  // DEC-0045 (CT-29): a small-order key verifies forged signatures on Node 20 and 22; it is refused before any use.
+  if (smallOrder(raw)) return { problem: 'small-order-key' };
+  return { key: crypto.createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: publicKey.x }, format: 'jwk' }) };
+}
+
+/**
+ * Verify a passkey assertion under a credential the caller pinned (`credentialId`, `alg`, `publicKey`, `rpId`,
+ * `origins`) for the expected challenge bytes: `{ok: true, flags, signCount}` or `{ok: false, problem}`.
+ */
+export function verifyAssertion(assertion, credential, challenge) {
+  if (!isObject(assertion)) return { ok: false, problem: 'malformed' };
+  const { credentialId, alg, authenticatorData, clientDataJSON, sig } = assertion;
+  for (const field of [credentialId, alg, authenticatorData, clientDataJSON, sig]) if (!isString(field)) return { ok: false, problem: 'malformed' };
+  if (![credentialId, authenticatorData, clientDataJSON, sig].every((field) => B64URL.test(field))) return { ok: false, problem: 'malformed' };
+  if (credentialId !== credential.credentialId) return { ok: false, problem: 'malformed' };
+  if (!ASSERTION_ALGORITHMS.includes(alg)) return { ok: false, problem: 'unknown-algorithm' };
+  if (alg !== credential.alg) return { ok: false, problem: 'key-algorithm-mismatch' };
+  const found = credentialKey(credential.publicKey, alg);
+  if ('problem' in found) return { ok: false, problem: found.problem };
+
+  const cData = bytes(clientDataJSON);
+  let client;
+  try {
+    client = JSON.parse(new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(cData));
+  } catch {
+    return { ok: false, problem: 'malformed' };
+  }
+  if (!isObject(client)) return { ok: false, problem: 'malformed' };
+  if (client.type !== 'webauthn.get') return { ok: false, problem: 'wrong-type' };
+  if (client.challenge !== Buffer.from(challenge).toString('base64url')) return { ok: false, problem: 'wrong-challenge' };
+  if (!isString(client.origin) || !credential.origins.includes(client.origin)) return { ok: false, problem: 'wrong-origin' };
+  if (client.crossOrigin === true || client.topOrigin !== undefined) return { ok: false, problem: 'cross-origin' };
+
+  const authData = bytes(authenticatorData);
+  if (authData.length < 37) return { ok: false, problem: 'malformed' };
+  if (!authData.subarray(0, 32).equals(sha256(Buffer.from(credential.rpId, 'utf8')))) return { ok: false, problem: 'wrong-rp' };
+  const flags = authData[32];
+  if ((flags & FLAGS.AT) !== 0 || ((flags & FLAGS.BS) !== 0 && (flags & FLAGS.BE) === 0)) return { ok: false, problem: 'bad-flags' };
+  if ((flags & FLAGS.UP) === 0) return { ok: false, problem: 'no-user-presence' };
+  if ((flags & FLAGS.UV) === 0) return { ok: false, problem: 'no-user-verification' };
+
+  const signed = Buffer.concat([authData, sha256(cData)]);
+  const signature = bytes(sig);
+  let good;
+  try {
+    good = alg === 'ES256'
+      ? crypto.verify('sha256', signed, { key: found.key, dsaEncoding: 'der' }, signature)
+      : signature.length === 64 && crypto.verify(null, signed, found.key, signature);
+  } catch {
+    good = false;
+  }
+  if (!good) return { ok: false, problem: 'bad-signature' };
+  return { ok: true, flags, signCount: authData.readUInt32BE(33) };
+}
+
+// ---- the record ----
+
+/** `sha256:` and the hex SHA-256 of the UTF-8 RFC 8785 form of the record without `digest` and `signature`. */
+export function estateRecordDigest(record) {
+  const { digest: _digest, signature: _signature, ...covered } = record;
+  return `sha256:${sha256(Buffer.from(jcs(covered), 'utf8')).toString('hex')}`;
+}
+
+export const estateChallengeInput = (digest) => Buffer.from(jcs({ type: ESTATE_CHALLENGE_TYPE, digest }), 'utf8');
+/** The WebAuthn challenge a signer passes to navigator.credentials.get(): SHA-256 of estateChallengeInput. */
+export const estateChallenge = (digest) => sha256(estateChallengeInput(digest));
+
+const RFC3339 = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+/** An RFC 3339 date-time as milliseconds, or NaN: `T`, an offset and a day that exists; a space and `:60` refused (ER-10). */
+export function estateTime(value) {
+  const match = isString(value) ? RFC3339.exec(value) : null;
+  if (!match) return Number.NaN;
+  const [year, month, day, hour, minute, second] = match.slice(1, 7).map(Number);
+  const date = new Date(0);
+  date.setUTCFullYear(year, month - 1, day);
+  if (date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day || hour > 23 || minute > 59 || second > 59) return Number.NaN;
+  return Date.parse(value);
+}
+const revocationKey = (entry) => `${String(entry.kind)} ${String(entry.ref)}`;
+const clockOf = (at) => (at instanceof Date ? at.getTime() : (typeof at === 'number' && Number.isFinite(at) ? at * 1000 : Number.NaN));
+
+/**
+ * The reference verifier, in the order of estate-record.md's ER table. `at` is the clock (a Date, or epoch seconds); pass
+ * the verified `parent`, or for revision 1 the `authorities` the machine pinned at enrollment.
+ */
+export function verifyEstateRecord(record, trust) {
+  const at = isObject(trust) ? clockOf(trust.at) : Number.NaN;
+  if (!Number.isFinite(at)) return { ok: false, problem: 'no-clock' };
+  if (!isObject(record) || !isString(record.digest) || !Number.isSafeInteger(record.revision) || !isObject(record.signature)) return { ok: false, problem: 'malformed' };
+  const signature = record.signature;
+  if (signature.format !== 'webauthn-assertion' || !isString(signature.credentialId)) return { ok: false, problem: 'malformed' };
+  let digest;
+  try {
+    digest = estateRecordDigest(record);
+  } catch {
+    return { ok: false, problem: 'malformed' };
+  }
+  if (digest !== record.digest) return { ok: false, problem: 'digest-mismatch' };
+
+  let trusted;
+  let revoked = new Set();
+  if (trust.parent !== undefined) {
+    const parent = trust.parent;
+    if (!isObject(parent)) return { ok: false, problem: 'broken-chain' };
+    let parentDigest;
+    try {
+      parentDigest = estateRecordDigest(parent);
+    } catch {
+      return { ok: false, problem: 'broken-chain' };
+    }
+    if (parent.estate !== record.estate || record.revision !== Number(parent.revision) + 1 || record.parent !== parentDigest) return { ok: false, problem: 'broken-chain' };
+    if (estateTime(record.issuedAt) < estateTime(parent.issuedAt)) return { ok: false, problem: 'broken-chain' };
+    const kept = new Set(list(record.revocations).map(revocationKey));
+    if (list(parent.revocations).some((entry) => !kept.has(revocationKey(entry)))) return { ok: false, problem: 'broken-chain' };
+    // A passkey the parent revokes signs nothing after it; a revision may still revoke its own signer (rotation).
+    revoked = new Set(list(parent.revocations).filter((entry) => entry.kind === 'authority').map((entry) => entry.ref));
+    trusted = list(parent.authorities);
+  } else {
+    if (record.revision !== 1 || record.parent !== undefined) return { ok: false, problem: 'broken-chain' };
+    trusted = Array.isArray(trust.authorities) ? trust.authorities : [];
+  }
+  if (trusted.length === 0) return { ok: false, problem: 'no-trusted-authority' };
+  const matches = trusted.filter((entry) => isObject(entry) && entry.credentialId === signature.credentialId);
+  if (matches.length > 1) return { ok: false, problem: 'duplicate-authority' };
+  const authority = matches[0];
+  if (!authority) return { ok: false, problem: 'unknown-authority' };
+  if (revoked.has(authority.credentialId)) return { ok: false, problem: 'revoked-authority' };
+  const credential = {
+    credentialId: String(authority.credentialId), alg: String(authority.alg), publicKey: isObject(authority.publicKey) ? authority.publicKey : {},
+    rpId: String(authority.rpId), origins: Array.isArray(authority.origins) ? authority.origins.filter(isString) : [],
+  };
+  const assertion = verifyAssertion(signature, credential, estateChallenge(digest));
+  if (!assertion.ok) return { ok: false, problem: assertion.problem };
+
+  const issuedAt = estateTime(record.issuedAt);
+  const validUntil = estateTime(record.validUntil);
+  if (!Number.isFinite(issuedAt) || !Number.isFinite(validUntil) || validUntil <= issuedAt || validUntil - issuedAt > MAX_VALIDITY_SECONDS * 1000) return { ok: false, problem: 'too-long-lived' };
+  if (at < issuedAt) return { ok: false, problem: 'not-yet-valid' };
+  if (at > validUntil) return { ok: false, problem: 'expired' };
+  const codes = [...new Set(recordFindings(record).map((finding) => finding.code))];
+  if (codes.length > 0) return { ok: false, problem: 'rule-violation', codes };
+  return { ok: true, digest, revision: record.revision, signedBy: credential.credentialId, signCount: assertion.signCount };
+}
+
+/** What a package verifier trusts for a package placed on a machine; undefined when the record places no such agent there. */
+export function placementTrust(record, machineId, agentRef) {
+  const machine = list(record.machines).find((entry) => entry.id === machineId);
+  const placement = list(machine?.packages).find((entry) => entry.agentRef === agentRef);
+  if (!placement) return undefined;
+  return { publisher: list(record.publisherKeys).filter((key) => key.kid === placement.publisherKid) };
+}
+
+/**
+ * DL-14 with DEC-0055: trust a token's `kid` only while a current revision certifies it for a machine and does not revoke
+ * it. `record` is a revision the caller verified; `x` the key the published key set gives for `kid`; `at` the clock.
+ */
+export function hubKeyCertified(record, kid, x, at) {
+  const now = clockOf(at);
+  if (!isObject(record) || !Number.isFinite(now)) return false;
+  const issuedAt = estateTime(record.issuedAt);
+  const validUntil = estateTime(record.validUntil);
+  if (!(Number.isFinite(issuedAt) && Number.isFinite(validUntil) && issuedAt <= now && now <= validUntil)) return false;
+  const revoked = new Set(list(record.revocations).map(revocationKey));
+  return list(record.machines).some((machine) => isObject(machine.hubKey) && machine.hubKey.kid === kid && machine.hubKey.x === x
+    && !revoked.has(`hub-key ${kid}`) && !revoked.has(`machine ${String(machine.id)}`));
+}
+
+// ---- FAC-SEM-072…076 ----
+
+const flagger = (findings, code) => (instancePath, message) => findings.push({ code, instancePath, message });
+
+function revisionWhole(value, flag) {
+  try {
+    const digest = estateRecordDigest(value);
+    if (digest !== value.digest) flag('/digest', `the digest is ${digest}: the record changed after it was drafted, or was hashed over another form than RFC 8785`);
+  } catch {
+    flag('/digest', 'the record has no RFC 8785 form, so it has no digest');
+  }
+  const issuedAt = estateTime(value.issuedAt);
+  const validUntil = estateTime(value.validUntil);
+  if (!Number.isFinite(issuedAt) || !Number.isFinite(validUntil)) {
+    flag(Number.isFinite(issuedAt) ? '/validUntil' : '/issuedAt', 'issuedAt and validUntil are RFC 3339 date-times with an offset, on days that exist');
+  } else if (validUntil <= issuedAt || validUntil - issuedAt > MAX_VALIDITY_SECONDS * 1000) {
+    flag('/validUntil', 'an estate record is valid after it is issued and for at most 30 days');
+  }
+}
+
+function revisionChain(value) {
+  const findings = [];
+  const flag = flagger(findings, 'FAC-SEM-072');
+  const parent = isObject(value.parent) ? value.parent : {};
+  const next = isObject(value.next) ? value.next : {};
+  if (next.estate !== parent.estate) flag('/next/estate', "a revision continues its parent's estate");
+  if (next.revision !== Number(parent.revision) + 1) flag('/next/revision', `the revision after ${String(parent.revision)} is ${Number(parent.revision) + 1}: a revision never skips or repeats one`);
+  let parentDigest;
+  try {
+    parentDigest = estateRecordDigest(parent);
+  } catch {
+    parentDigest = undefined;
+  }
+  if (next.parent !== parentDigest) flag('/next/parent', 'parent names the digest of the revision before it');
+  if (estateTime(next.issuedAt) < estateTime(parent.issuedAt)) flag('/next/issuedAt', 'a revision is never issued before its parent');
+  const kept = new Set(list(next.revocations).map(revocationKey));
+  list(parent.revocations).forEach((entry, index) => {
+    if (!kept.has(revocationKey(entry))) flag(`/parent/revocations/${index}`, `the ${String(entry.kind)} revocation of ${String(entry.ref)} is dropped: a revision keeps every revocation before it`);
+  });
+  return findings;
+}
+
+const validDeviceKey = (key) => {
+  const raw = Buffer.from(String(key.publicKey ?? ''), 'base64');
+  return key.alg === 'ed25519' ? raw.length === 32 && !smallOrder(raw) : isValidP256Key(raw);
+};
+
+function keys(value, flag) {
+  const ids = new Set();
+  const hubKids = new Set();
+  const hubKeys = new Set();
+  list(value.machines).forEach((machine, m) => {
+    const at = `/machines/${m}`;
+    if (ids.has(machine.id)) flag(`${at}/id`, `machine ${String(machine.id)} is listed twice`);
+    ids.add(machine.id);
+    const deviceKeys = list(machine.deviceKeys);
+    if (deviceKeys.filter((key) => key.use === 'sig').length !== 1) flag(`${at}/deviceKeys`, 'a machine has exactly one signing device key, <id>#sig');
+    if (deviceKeys.filter((key) => key.use === 'kem').length > 1) flag(`${at}/deviceKeys`, 'a machine has at most one key-agreement device key, <id>#kem');
+    const seen = new Set();
+    deviceKeys.forEach((key, k) => {
+      if (key.kid !== `${String(machine.id)}#${String(key.use)}`) flag(`${at}/deviceKeys/${k}/kid`, 'a device key is listed as <machine id>#sig or <machine id>#kem, by its role');
+      if (!validDeviceKey(key)) flag(`${at}/deviceKeys/${k}/publicKey`, 'an Ed25519 key is never of small order (DEC-0045) and a P-256 key is a valid point (SEC 1 §3.2.2)');
+      if (seen.has(key.publicKey)) flag(`${at}/deviceKeys/${k}/publicKey`, 'one key is never used for the other role');
+      seen.add(key.publicKey);
+    });
+    if (isObject(machine.hubKey)) {
+      const hub = machine.hubKey;
+      if (hubKids.has(hub.kid)) flag(`${at}/hubKey/kid`, `hub key ${String(hub.kid)} is certified for two machines: one kid per machine`);
+      hubKids.add(hub.kid);
+      if (hubKeys.has(hub.x)) flag(`${at}/hubKey/x`, 'one hub public key is certified for two machines under two kids: one key per machine');
+      hubKeys.add(hub.x);
+      if (smallOrder(Buffer.from(String(hub.x ?? ''), 'base64url'))) flag(`${at}/hubKey/x`, 'a hub key of small order verifies forged tokens and is never certified (DEC-0045)');
+    }
+  });
+  const credentials = new Set();
+  list(value.authorities).forEach((authority, index) => {
+    if (credentials.has(authority.credentialId)) flag(`/authorities/${index}/credentialId`, 'a passkey is listed once');
+    credentials.add(authority.credentialId);
+    if ('problem' in credentialKey(authority.publicKey, String(authority.alg))) flag(`/authorities/${index}/publicKey`, "a passkey's public key is a valid P-256 point for ES256 or an Ed25519 key of full order for EdDSA");
+  });
+}
+
+function placements(value, flag) {
+  const kids = new Set();
+  list(value.publisherKeys).forEach((key, index) => {
+    if (kids.has(key.kid)) flag(`/publisherKeys/${index}/kid`, `publisher key ${String(key.kid)} is pinned twice`);
+    kids.add(key.kid);
+  });
+  list(value.machines).forEach((machine, m) => {
+    const agents = new Set();
+    list(machine.packages).forEach((placement, p) => {
+      const at = `/machines/${m}/packages/${p}`;
+      if (agents.has(placement.agentRef)) flag(`${at}/agentRef`, `${String(placement.agentRef)} is placed twice on one machine`);
+      agents.add(placement.agentRef);
+      if (!kids.has(placement.publisherKid)) flag(`${at}/publisherKid`, `publisher key ${String(placement.publisherKid)} is not in publisherKeys, so the machine pins no key to verify the package under`);
+    });
+  });
+}
+
+function secretReferences(value, flag) {
+  const machineIds = new Set(list(value.machines).map((machine) => machine.id));
+  list(value.machines).forEach((machine, m) => {
+    const placed = new Set(list(machine.packages).map((placement) => placement.agentRef));
+    const slots = new Set();
+    list(machine.secrets).forEach((secret, s) => {
+      const at = `/machines/${m}/secrets/${s}`;
+      for (const field of ['slot', 'from', 'agentRef']) {
+        const text = secret[field];
+        if (isString(text) && secretValue(text)) flag(`${at}/${field}`, 'a secret placement names a slot, never a value: this looks like a credential');
+      }
+      if (!placed.has(secret.agentRef)) flag(`${at}/agentRef`, 'a secret goes only where a placed package declares it (v4 Path 2): this agent is not placed on this machine');
+      if (!machineIds.has(secret.from)) flag(`${at}/from`, 'the slot is filled from a machine of this estate');
+      const key = `${String(secret.agentRef)} ${String(secret.slot)}`;
+      if (slots.has(key)) flag(`${at}/slot`, `slot ${String(secret.slot)} is placed twice for one agent on one machine`);
+      slots.add(key);
+    });
+  });
+}
+
+function grantsAndRevocations(value, flag) {
+  const grantIds = new Set();
+  list(value.shareGrants).forEach((grant, index) => {
+    if (grant.principalKind !== 'external') flag(`/shareGrants/${index}/principalKind`, 'a share grant is to a principal outside the estate: principalKind external');
+    const id = isObject(grant.meta) ? grant.meta.id : undefined;
+    if (grantIds.has(id)) flag(`/shareGrants/${index}/meta/id`, `grant ${String(id)} is listed twice`);
+    grantIds.add(id);
+  });
+  const machines = list(value.machines);
+  // A Map, so a kind such as `constructor` or `__proto__` reads nothing from Object.prototype.
+  const listed = new Map(Object.entries({
+    authority: new Set(list(value.authorities).map((entry) => entry.credentialId)),
+    machine: new Set(machines.map((machine) => machine.id)),
+    'device-key': new Set(machines.flatMap((machine) => list(machine.deviceKeys).map((key) => key.kid))),
+    'hub-key': new Set(machines.flatMap((machine) => (isObject(machine.hubKey) ? [machine.hubKey.kid] : []))),
+    'publisher-key': new Set(list(value.publisherKeys).map((key) => key.kid)),
+    package: new Set(machines.flatMap((machine) => list(machine.packages).map((placement) => placement.digest))),
+    grant: grantIds,
+  }));
+  const seen = new Set();
+  list(value.revocations).forEach((revocation, index) => {
+    const key = `${String(revocation.kind)} ${String(revocation.ref)}`;
+    if (seen.has(key)) flag(`/revocations/${index}`, `the ${String(revocation.kind)} ${String(revocation.ref)} is revoked twice`);
+    seen.add(key);
+    if (listed.get(String(revocation.kind))?.has(revocation.ref)) flag(`/revocations/${index}/ref`, `the record still lists the ${String(revocation.kind)} it revokes: revocation outranks addition`);
+  });
+}
+
+function recordFindings(value) {
+  const findings = [];
+  revisionWhole(value, flagger(findings, 'FAC-SEM-072'));
+  keys(value, flagger(findings, 'FAC-SEM-073'));
+  placements(value, flagger(findings, 'FAC-SEM-074'));
+  secretReferences(value, flagger(findings, 'FAC-SEM-075'));
+  grantsAndRevocations(value, flagger(findings, 'FAC-SEM-076'));
+  return findings;
+}
+
+function packageDigest(pkg) {
+  const { digest: _digest, signatures: _signatures, ...covered } = pkg;
+  return `sha256:${sha256(Buffer.from(jcs(covered), 'utf8')).toString('hex')}`;
+}
+
+function installation(value) {
+  const findings = [];
+  const record = isObject(value.record) ? value.record : {};
+  const pkg = isObject(value.package) ? value.package : {};
+  const machineIndex = list(record.machines).findIndex((entry) => entry.id === value.machine);
+  const machine = list(record.machines)[machineIndex];
+  let digest;
+  try {
+    digest = packageDigest(pkg);
+  } catch {
+    digest = undefined;
+  }
+  const flag074 = flagger(findings, 'FAC-SEM-074');
+  if (!machine) {
+    flag074('/machine', `machine ${String(value.machine)} is not in the estate record`);
+    return findings;
+  }
+  if (digest === undefined || digest !== pkg.digest) flag074('/package/digest', 'the package is not the one its digest names: it changed after it was packed');
+  const placement = list(machine.packages).find((entry) => entry.agentRef === pkg.agentRef);
+  if (!placement) flag074('/package/agentRef', `the record places no ${String(pkg.agentRef)} on machine ${String(value.machine)}`);
+  else if (placement.digest !== digest) flag074('/package', `the record places ${String(placement.digest)} of this agent on this machine, not this package`);
+  const declared = new Set(list(pkg.secrets).map((slot) => slot.name));
+  const flag075 = flagger(findings, 'FAC-SEM-075');
+  list(machine.secrets).forEach((secret, index) => {
+    if (secret.agentRef === pkg.agentRef && !declared.has(secret.slot)) flag075(`/record/machines/${machineIndex}/secrets/${index}/slot`, `the package declares no slot ${String(secret.slot)}: a secret goes only where a placed package declares it`);
+  });
+  return findings;
+}
+
+/** FAC-SEM-072…076 for an `estate-record`, an `estate-record-revision` `{parent, next}` or an `estate-placement`. */
+export function estateRecordRules(kind, value) {
+  const doc = isObject(value) ? value : {};
+  if (kind === 'estate-record') return recordFindings(doc);
+  if (kind === 'estate-record-revision') return revisionChain(doc);
+  if (kind === 'estate-placement') return installation(doc);
+  return undefined;
+}

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-profiles.mjs

@@ -126,6 +126,10 @@ function which(name, searchPath) {
  * runners.md C2: is the catalogued runner installed, which version answers, and is it signed in. Only a bare
  * catalogued binary on PATH is run, only with the catalogued version (and auth) argv, without a shell, within its
  * timeout (at most 5 s). An entry outside these rules is refused and nothing runs.
+ *
+ * `probe` is the contract's closed probe result for a walk (DEC-0026): `not-installed`, `not-responding` (the version
+ * probe did not answer, failed or did not match), `not-connected` (signed out by the `auth` probe), or null when the
+ * runner can serve. The twin of fabric_profiles.runner_check.
  */
 export function runnerCheck(entry, { searchPath = process.env.PATH, run = spawnSync } = {}) {
   const { kind, binaries } = entry ?? {};
@@ -136,10 +140,10 @@ export function runnerCheck(entry, { searchPath = process.env.PATH, run = spawnS
   const timeoutMs = version.timeoutMs ?? MAX_PROBE_MS;
   if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_PROBE_MS) throw new ProfileError(`version.timeoutMs is at most ${MAX_PROBE_MS}`);
   const authArgv = 'auth' in entry ? argvOf(entry.auth, 'auth') : null;
-  const out = { kind, installed: false, binary: null, version: null, signedIn: null, problems: [] };
+  const out = { kind, installed: false, binary: null, version: null, signedIn: null, probe: 'not-installed', problems: [] };
   const binary = binaries.map((name) => which(name, searchPath)).find(Boolean) ?? null;
   if (!binary) { out.problems.push(`${kind} is not installed: none of ${binaries.join(', ')} is on PATH`); return out; }
-  Object.assign(out, { installed: true, binary });
+  Object.assign(out, { installed: true, binary, probe: 'not-responding' });
   const probe = (argv) => {
     const result = run(binary, argv, { encoding: 'utf8', timeout: timeoutMs, shell: false });
     if (result.error?.code === 'ETIMEDOUT' || result.signal === 'SIGTERM') { out.problems.push(`${kind} ${argv.join(' ')} did not answer within ${timeoutMs} ms`); return null; }
@@ -153,10 +157,12 @@ export function runnerCheck(entry, { searchPath = process.env.PATH, run = spawnS
     if (match && match.length > 1) out.version = match[1];
     else out.problems.push(`${kind} answered, but its version did not match the catalogue's pattern`);
   }
-  if (authArgv) {
-    const signed = probe(authArgv);
-    if (signed) { out.signedIn = signed.status === 0; if (!out.signedIn) out.problems.push(`${kind} is installed but not signed in`); }
-  }
+  const signed = authArgv ? probe(authArgv) : null;
+  if (signed) { out.signedIn = signed.status === 0; if (!out.signedIn) out.problems.push(`${kind} is installed but not signed in`); }
+  // The walk's order (runners.md): installed, then responding, then connected. The doctor still reports every problem.
+  if (out.version === null || (authArgv && !signed)) out.probe = 'not-responding';
+  else if (out.signedIn === false) out.probe = 'not-connected';
+  else out.probe = null;
   return out;
 }
 
@@ -194,3 +200,131 @@ export function configurationSummary(doc) {
   if (resolved.modelProfile) tiles.push({ label: 'Model', value: [resolved.modelProfile, (resolved.models ?? [])[0]].filter(Boolean).join(' · ') });
   return tiles;
 }
+
+// ---- runner routes (DEC-0026, DEC-0029; FAC-SEM-028…034) ----
+// The contract's routeRules (src/route-rules.ts), finding for finding: code, path and message. The twin of
+// fabric_profiles.route_problems.
+
+/** The closed probe results a walk records for a candidate it passed over (runner-route-event.schema.json). */
+export const PROBE_RESULTS = Object.freeze(['not-catalogued', 'not-admitted', 'not-installed', 'not-responding', 'not-connected', 'no-held-session', 'quota-unknown', 'refused', 'spawn-failed']);
+
+const routeCandidates = (value) => (Array.isArray(value?.candidates) ? value.candidates.filter(isObject) : []);
+const objectAt = (value, key) => (isObject(value?.[key]) ? value[key] : {});
+const refKey = (ref) => (isObject(ref) ? `${String(ref.id)}@${String(ref.revision)}#${String(ref.contentHash)}` : '');
+const sameRef = (a, b) => refKey(a) !== '' && refKey(a) === refKey(b);
+
+function runnerRoute(value) {
+  const findings = [];
+  const kinds = new Set();
+  routeCandidates(value).forEach((candidate, index) => {
+    const kind = String(candidate.runnerKind);
+    if (kinds.has(kind)) findings.push(finding('FAC-SEM-028', `/candidates/${index}/runnerKind`, `runner kind ${kind} appears in the route more than once`));
+    kinds.add(kind);
+    const session = objectAt(candidate, 'session');
+    if (session.attach === 'never' && session.spawn === 'never') findings.push(finding('FAC-SEM-029', `/candidates/${index}/session`, `candidate ${kind} can never run: attach and spawn are both "never"`));
+  });
+  return findings;
+}
+
+function routeBundle(value) {
+  const route = objectAt(value, 'route');
+  const admissions = Array.isArray(value.admissions) ? value.admissions.filter(isObject) : [];
+  const admitted = new Set(admissions.filter((a) => a.state === 'admitted' && a.capability === route.capability).map((a) => refKey(a.provider)));
+  const findings = [];
+  routeCandidates(route).forEach((candidate, index) => {
+    const key = refKey(candidate.provider);
+    if (!admitted.has(key)) findings.push(finding('FAC-SEM-030', `/route/candidates/${index}/provider`, `candidate ${String(candidate.runnerKind)} names provider ${key}, which is not a revision admitted for ${String(route.capability)}`));
+  });
+  if (isObject(value.binding)) {
+    const binding = value.binding;
+    const disagree = (where, message) => findings.push(finding('FAC-SEM-032', `/binding/${where}`, message));
+    if (binding.project !== route.project) disagree('project', `the binding is for ${String(binding.project)}, the route for ${String(route.project)}`);
+    if (binding.capability !== route.capability) disagree('capability', `the binding binds ${String(binding.capability)}, the route orders ${String(route.capability)}`);
+    if (binding.profileKind !== 'local-runner') disagree('profileKind', `a runner route serves the local-runner profile, not ${String(binding.profileKind)}`);
+    if (!routeCandidates(route).some((c) => sameRef(c.provider, binding.provider))) disagree('provider', `the binding's provider ${refKey(binding.provider)} is not a candidate of the route`);
+    if (binding.runnerRoute !== undefined && !sameRef(binding.runnerRoute, route.meta)) disagree('runnerRoute', `the binding pins ${refKey(binding.runnerRoute)}, not this route ${refKey(route.meta)}`);
+  }
+  if (Array.isArray(value.catalogue)) {
+    const byKind = new Map(value.catalogue.filter(isObject).map((entry) => [String(entry.kind), entry]));
+    routeCandidates(route).forEach((candidate, index) => {
+      const kind = String(candidate.runnerKind);
+      const entry = byKind.get(kind);
+      if (!entry) { findings.push(finding('FAC-SEM-033', `/route/candidates/${index}/runnerKind`, `runner kind ${kind} has no entry in the host's catalogue`)); return; }
+      if (candidate.drive !== undefined && !Object.hasOwn(objectAt(entry, 'drives'), String(candidate.drive))) findings.push(finding('FAC-SEM-033', `/route/candidates/${index}/drive`, `the catalogue entry for ${kind} offers no drive ${String(candidate.drive)}`));
+    });
+  }
+  return findings;
+}
+
+function routeEvent(value) {
+  const route = objectAt(value, 'route');
+  const event = objectAt(value, 'event');
+  const list = routeCandidates(route);
+  const findings = [];
+  const wrong = (where, message) => findings.push(finding('FAC-SEM-034', `/event${where}`, message));
+  if (!sameRef(event.route, route.meta)) wrong('/route', `the event names route ${refKey(event.route)}, not ${refKey(route.meta)}`);
+  if (event.project !== route.project) wrong('/project', `the event is for ${String(event.project)}, the route for ${String(route.project)}`);
+  if (event.capability !== route.capability) wrong('/capability', `the event names ${String(event.capability)}, the route orders ${String(route.capability)}`);
+  const indexOf = (ref) => (typeof ref.index === 'number' && Number.isInteger(ref.index) ? ref.index : -1);
+  const candidateAt = (ref, where) => {
+    const index = indexOf(ref);
+    const candidate = index >= 0 ? list[index] : undefined;
+    if (!candidate || candidate.runnerKind !== ref.runnerKind || (ref.provider !== undefined && !sameRef(candidate.provider, ref.provider))) {
+      wrong(where, `candidate ${String(ref.index)} (${String(ref.runnerKind)}) is not that position of the route`);
+      return undefined;
+    }
+    return candidate;
+  };
+  const probes = Array.isArray(event.probes) ? event.probes.filter(isObject) : [];
+  probes.forEach((probe, position) => {
+    const candidate = candidateAt(probe, `/probes/${position}`);
+    if (candidate && probe.result === 'no-held-session' && objectAt(candidate, 'session').spawn !== 'never') wrong(`/probes/${position}/result`, `${String(probe.runnerKind)} may spawn, so finding no held session does not pass it over`);
+    if (candidate && probe.result === 'spawn-failed' && objectAt(candidate, 'session').spawn !== 'allowed') wrong(`/probes/${position}/result`, `${String(probe.runnerKind)} has spawn: never, so it cannot have failed to spawn`);
+  });
+  const expectProbes = (count) => {
+    const indexes = probes.map(indexOf);
+    const expected = Array.from({ length: Math.max(count, 0) }, (_, index) => index);
+    if (indexes.length !== expected.length || indexes.some((index, position) => index !== expected[position])) {
+      wrong('/probes', `the walk must record candidates ${expected.join(', ') || 'none'} in order; it records ${indexes.join(', ') || 'none'}`);
+    }
+  };
+  if (event.kind === 'runner-exhausted') {
+    expectProbes(list.length);
+    if (event.answer === 'held' && route.exhausted !== 'hold') wrong('/answer', 'the route does not declare exhausted: hold, so an exhausted walk answers capability-unavailable');
+    return findings;
+  }
+  const selected = objectAt(event, 'selected');
+  const chosen = candidateAt(selected, '/selected');
+  if (chosen) {
+    const session = objectAt(chosen, 'session');
+    if (selected.session === 'attached' && session.attach !== 'preferred') wrong('/selected/session', `${String(selected.runnerKind)} has attach: never, so the host cannot attach it`);
+    if (selected.session === 'spawned' && session.spawn !== 'allowed') wrong('/selected/session', `${String(selected.runnerKind)} has spawn: never, so the host cannot spawn it`);
+    if (chosen.drive !== undefined && selected.drive !== undefined && selected.drive !== chosen.drive) wrong('/selected/drive', `the route runs ${String(selected.runnerKind)} through ${String(chosen.drive)}, not ${String(selected.drive)}`);
+    if (event.sticky === true) {
+      // A sticky relaunch keeps the conversation's runner and walks nothing above it.
+      if (route.recovery === 'reprobe') wrong('/sticky', 'a route with recovery: reprobe walks from the top at every launch');
+      if (event.conversation === undefined) wrong('/sticky', 'only a conversation can keep its runner');
+      expectProbes(0);
+    } else expectProbes(indexOf(selected));
+  }
+  if (event.kind === 'runner-switched') {
+    const from = objectAt(event, 'from');
+    candidateAt(from, '/from');
+    if (indexOf(from) === indexOf(selected)) wrong('/from', 'a switch moves to another candidate');
+    if (event.reason === 'preferred-available') {
+      if (route.recovery !== 'reprobe') wrong('/reason', 'only a route with recovery: reprobe moves a conversation back to a preferred runner');
+      if (!(indexOf(selected) < indexOf(from))) wrong('/reason', 'preferred-available moves to a higher-preference candidate');
+    }
+  }
+  return findings;
+}
+
+/**
+ * The contract's routeRules: findings for a `runner-route` (FAC-SEM-028, 029), a `route-bundle` `{route, admissions,
+ * binding?, catalogue?}` (030, 032, 033) or a `route-event` `{route, event}` (034); undefined for another kind or a
+ * value that is not an object.
+ */
+export function routeProblems(kind, value) {
+  if (!isObject(value)) return undefined;
+  return { 'runner-route': runnerRoute, 'route-bundle': routeBundle, 'route-event': routeEvent }[kind]?.(value);
+}

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-service.mjs

@@ -866,6 +866,12 @@ function byCodePoint(a, b) {
  * strings escaped as JSON requires and nothing else, integers in decimal — Python's
  * `json.dumps(value, sort_keys=True, ensure_ascii=False)`. Refuses a fraction, an unsafe integer and non-JSON.
  */
+/** CT-25 (DEC-0052): a lone surrogate in a string or a key has no canonical form — Python cannot encode it as UTF-8. */
+function settingsString(text) {
+  if (/\p{Surrogate}/u.test(text)) throw new ServiceError('a lone surrogate has no canonical form');
+  return JSON.stringify(text);
+}
+
 export function settingsCanonicalJson(value) {
   if (value === null) return 'null';
   if (typeof value === 'boolean') return value ? 'true' : 'false';
@@ -873,10 +879,10 @@ export function settingsCanonicalJson(value) {
     if (!Number.isSafeInteger(value)) throw new ServiceError(`${value} has no canonical form: a settings backup stores a fraction as its decimal string`);
     return String(value);
   }
-  if (typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'string') return settingsString(value);
   if (Array.isArray(value)) return `[${value.map(settingsCanonicalJson).join(', ')}]`;
   if (isPlainObject(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value))) {
-    return `{${Object.keys(value).sort(byCodePoint).map((key) => `${JSON.stringify(key)}: ${settingsCanonicalJson(value[key])}`).join(', ')}}`;
+    return `{${Object.keys(value).sort(byCodePoint).map((key) => `${settingsString(key)}: ${settingsCanonicalJson(value[key])}`).join(', ')}}`;
   }
   throw new ServiceError(`${typeof value} is not a JSON value`);
 }