@passioncode-ai/fabric-agent-adapter 0.35.3 → 0.36.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_ceremonies.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""The estate ceremonies' headless join (contract DEC-0084), the Python kit; the Node twin is fabric-ceremonies.mjs.
+Standard library only.
+
+An ``enroll-token/1`` lets a machine with no screen join an estate: Fabric issues it under the person's signing passkey
+for at most 15 minutes and one use, the machine reads it from stdin or a 0600 file (never argv, a URL or a log) and
+presents it with its ``#sig`` key, and the hub binds its nonce to that key on the first use. The token gives the machine
+no trust; only a passkey-signed revision that lists it does. Its ``genesis`` authenticates the estate to the machine.
+
+- ``verify_enroll_token(token, record=, genesis=, at=)``: the reference verifier, the hub's and the node's.
+- ``enroll_join_input(token)``: the ``enroll-join/1`` statement the joining machine signs with its ``#sig`` key.
+- ``enroll_token_rules("enroll-token", token)``: FAC-SEM-113.
+
+Every function answers and never raises on malformed input. Normative source: the contract's src/enroll-token.ts,
+src/signing-challenges.ts and docs/specification/ceremonies.md.
+"""
+# #region ceremonies-kit, docs: plugins/fabric-agent-adapter/skills/building-fabric-services/references/estate-record.md#the-estate-ceremonies
+
+from __future__ import annotations
+
+import hashlib
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import fabric_delegation as _delegation  # noqa: E402 - beside this file: RFC 8785
+import fabric_estate as _estate  # noqa: E402 - beside this file: passkey assertions, times, show
+
+ENROLL_TOKEN_SCHEMA = "enroll-token/1"
+ENROLL_TOKEN_TYPE = "enroll-token/1"
+ENROLL_JOIN_TYPE = "enroll-join/1"
+ENROLL_PURPOSE = "agent-host"
+MAX_ENROLL_TOKEN_SECONDS = 900
+#: The register's fields of enroll-token/1 beside ``type`` (DEC-0084), one list for good.
+ENROLL_TOKEN_FIELDS = ("scope", "genesis", "purpose", "ceiling", "notBefore", "expiresAt", "nonce", "uses")
+_SHA256 = re.compile(r"sha256:[a-f0-9]{64}\Z")
+_ESTATE_SCOPE = re.compile(r"estate:[A-Za-z0-9][A-Za-z0-9._:~-]{0,127}\Z")
+#: 32 random bytes as unpadded base64url.
+_NONCE32 = re.compile(r"[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]\Z")
+_ASSERTION_MEMBERS = "alg,authenticatorData,clientDataJSON,credentialId,format,sig"
+
+
+def _matches(pattern: Any, value: Any) -> bool:
+    return isinstance(value, str) and pattern.match(value) is not None
+
+
+def _is_one(value: Any) -> bool:
+    """JavaScript's ``value === 1`` on parsed JSON: true is not 1."""
+    return not isinstance(value, bool) and isinstance(value, (int, float)) and value == 1
+
+
+def _finite(value: float) -> bool:
+    return value == value and value not in (float("inf"), float("-inf"))
+
+
+def _register_ok(kind: str, fields: Dict[str, Any]) -> bool:
+    if kind == ENROLL_TOKEN_TYPE:
+        return (_matches(_ESTATE_SCOPE, fields["scope"]) and _matches(_SHA256, fields["genesis"]) and fields["purpose"] == ENROLL_PURPOSE
+                and (fields["ceiling"] is None or _matches(_SHA256, fields["ceiling"])) and _finite(_estate.estate_time(fields["notBefore"]))
+                and _finite(_estate.estate_time(fields["expiresAt"])) and _matches(_NONCE32, fields["nonce"]) and _is_one(fields["uses"]))
+    return _matches(_SHA256, fields["digest"]) and _matches(_NONCE32, fields["nonce"])
+
+
+def signing_statement(kind: str, fields: Any) -> Optional[bytes]:
+    """The bytes of a registered statement (DEC-0063): the UTF-8 RFC 8785 form of ``{type, ...fields}``, for the two types
+    this kit uses (``enroll-token/1``, ``enroll-join/1``); None when the fields are not exactly the type's or a value is
+    outside what the register admits."""
+    names = {ENROLL_TOKEN_TYPE: ENROLL_TOKEN_FIELDS, ENROLL_JOIN_TYPE: ("digest", "nonce")}.get(kind)
+    if names is None or not isinstance(fields, dict) or len(fields) != len(names) or any(name not in fields for name in names):
+        return None
+    if not _register_ok(kind, fields):
+        return None
+    try:
+        return _delegation.jcs(dict(fields, type=kind)).encode("utf-8")
+    except (TypeError, ValueError):
+        return None
+
+
+def _statement_fields(token: Any) -> Optional[Dict[str, Any]]:
+    if not isinstance(token, dict) or token.get("schema") != ENROLL_TOKEN_SCHEMA or not isinstance(token.get("statement"), dict):
+        return None
+    if token["statement"].get("type") != ENROLL_TOKEN_TYPE:
+        return None
+    # The token holds exactly the schema's members: nothing unsigned rides beside the statement (DEC-0084).
+    if sorted(token) != ["schema", "signature", "statement"]:
+        return None
+    fields = {name: value for name, value in token["statement"].items() if name != "type"}
+    return fields if signing_statement(ENROLL_TOKEN_TYPE, fields) is not None else None
+
+
+def verify_enroll_token(token: Any, *, record: Any, genesis: Any, at: Any) -> Dict[str, Any]:
+    """The reference verifier of an enroll-token/1, for the hub that admits a join and the node that pins the estate.
+    ``record`` is the current estate revision the verifier applied, ``genesis`` the digest of its revision 1, ``at`` the
+    clock (an aware datetime or epoch seconds). The first failure answers: no-clock, malformed, wrong-estate, the passkey
+    (no-trusted-authority, revoked-authority, duplicate-authority, unknown-authority), the assertion, then the window
+    (too-long-lived, not-yet-valid, expired). Success: ``{"ok": True, "nonce", "expiresAt", "signedBy"}``."""
+    now = _estate._clock(at)
+    if not _finite(now):
+        return {"ok": False, "problem": "no-clock"}
+    fields = _statement_fields(token)
+    if fields is None or not isinstance(record, dict) or not isinstance(record.get("estate"), str):
+        return {"ok": False, "problem": "malformed"}
+    signature = token.get("signature")
+    if (not isinstance(signature, dict) or ",".join(sorted(signature)) != _ASSERTION_MEMBERS
+            or signature.get("format") != "webauthn-assertion" or not isinstance(signature.get("credentialId"), str)):
+        return {"ok": False, "problem": "malformed"}
+    if fields["scope"] != "estate:%s" % record["estate"] or not isinstance(genesis, str) or fields["genesis"] != genesis:
+        return {"ok": False, "problem": "wrong-estate"}
+    authorities = _estate._list(record.get("authorities"))
+    if not authorities:
+        return {"ok": False, "problem": "no-trusted-authority"}
+    credential_id = signature["credentialId"]
+    if any(entry.get("kind") == "authority" and _estate._same(entry.get("ref", _estate._MISSING), credential_id) for entry in _estate._list(record.get("revocations"))):
+        return {"ok": False, "problem": "revoked-authority"}
+    matches = [entry for entry in authorities if _estate._same(entry.get("credentialId", _estate._MISSING), credential_id)]
+    if len(matches) > 1:
+        return {"ok": False, "problem": "duplicate-authority"}
+    if not matches:
+        return {"ok": False, "problem": "unknown-authority"}
+    authority = matches[0]
+    origins = authority.get("origins")
+    rp_id = _estate._show(authority.get("rpId", _estate._MISSING))
+    if not _estate.is_signing_rp_id(rp_id):
+        return {"ok": False, "problem": "wrong-rp"}
+    credential = {"credentialId": credential_id, "alg": _estate._show(authority.get("alg", _estate._MISSING)),
+                  "publicKey": authority["publicKey"] if isinstance(authority.get("publicKey"), dict) else {}, "rpId": rp_id,
+                  "origins": [o for o in origins if isinstance(o, str) and _estate.origin_within(o, rp_id)] if isinstance(origins, list) else []}
+    challenge = hashlib.sha256(signing_statement(ENROLL_TOKEN_TYPE, fields)).digest()
+    assertion = _estate.verify_assertion(signature, credential, challenge)
+    if not assertion["ok"]:
+        return {"ok": False, "problem": assertion["problem"]}
+    not_before = _estate.estate_time(fields["notBefore"])
+    expires_at = _estate.estate_time(fields["expiresAt"])
+    if expires_at <= not_before or expires_at - not_before > MAX_ENROLL_TOKEN_SECONDS * 1000:
+        return {"ok": False, "problem": "too-long-lived"}
+    if now < not_before - _estate.CLOCK_SKEW_SECONDS * 1000:
+        return {"ok": False, "problem": "not-yet-valid"}
+    if now > expires_at:
+        return {"ok": False, "problem": "expired"}
+    return {"ok": True, "nonce": fields["nonce"], "expiresAt": fields["expiresAt"], "signedBy": credential_id}
+
+
+def enroll_join_input(token: Any) -> Optional[str]:
+    """What the joining machine signs with the #sig key it presents (DEC-0084): the enroll-join/1 statement
+    ``{type, digest, nonce}``, ``digest`` the SHA-256 of the token's statement bytes; None without a register statement."""
+    fields = _statement_fields(token)
+    statement = signing_statement(ENROLL_TOKEN_TYPE, fields) if fields is not None else None
+    if statement is None:
+        return None
+    joined = signing_statement(ENROLL_JOIN_TYPE, {"digest": "sha256:" + hashlib.sha256(statement).hexdigest(), "nonce": fields["nonce"]})
+    return joined.decode("utf-8") if joined is not None else None
+
+
+def _token_findings(value: Dict[str, Any]) -> List[Dict[str, str]]:
+    findings: List[Dict[str, str]] = []
+
+    def flag(at: str, message: str) -> None:
+        findings.append({"code": "FAC-SEM-113", "instancePath": at, "message": message})
+
+    statement = value.get("statement") if isinstance(value.get("statement"), dict) else None
+    if statement is None:
+        flag("/statement", "an enroll token carries its signed statement")
+        return findings
+    if statement.get("type") != ENROLL_TOKEN_TYPE:
+        flag("/statement/type", "the statement's type is enroll-token/1, the register's (DEC-0063)")
+    extra = [name for name in statement if name != "type" and name not in ENROLL_TOKEN_FIELDS]
+    missing = [name for name in ENROLL_TOKEN_FIELDS if name not in statement]
+    if extra or missing:
+        flag("/statement", "the statement has exactly the register's fields: %s" % ", ".join(ENROLL_TOKEN_FIELDS))
+    if statement.get("purpose") != ENROLL_PURPOSE:
+        flag("/statement/purpose", "an enroll token's purpose is agent-host")
+    if not _is_one(statement.get("uses")):
+        flag("/statement/uses", "an enroll token is used once: uses is 1, and the hub binds its nonce on the first use")
+    not_before = _estate.estate_time(statement.get("notBefore"))
+    expires_at = _estate.estate_time(statement.get("expiresAt"))
+    rest = {name: v for name, v in statement.items() if name != "type"}
+    named = not extra and not missing and statement.get("purpose") == ENROLL_PURPOSE and _is_one(statement.get("uses")) and _finite(not_before) and _finite(expires_at)
+    if named and signing_statement(ENROLL_TOKEN_TYPE, rest) is None:
+        flag("/statement", "scope is estate:<id>, genesis a sha256: digest, nonce 32 bytes in base64url, and ceiling null or a digest")
+    if not _finite(not_before) or not _finite(expires_at):
+        flag("/statement/expiresAt" if _finite(not_before) else "/statement/notBefore", "notBefore and expiresAt are RFC 3339 date-times with an offset, on days that exist")
+    elif expires_at <= not_before or expires_at - not_before > MAX_ENROLL_TOKEN_SECONDS * 1000:
+        flag("/statement/expiresAt", "an enroll token is valid after notBefore and for at most 15 minutes (900 s)")
+    return findings
+
+
+def enroll_token_rules(kind: str, value: Any) -> Optional[List[Dict[str, str]]]:
+    """FAC-SEM-113 (kind ``enroll-token``); None for another kind."""
+    if kind == "enroll-token":
+        return _token_findings(value if isinstance(value, dict) else {})
+    return None
+# #endregion ceremonies-kit

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_estate.py

@@ -715,7 +715,9 @@ def verify_estate_record(record: Any, *, at: Any, parent: Any = _MISSING, author
     if now > valid_until:
         return {"ok": False, "problem": "expired"}
     codes: List[str] = []
-    for finding in _record_findings(record):
+    # With a parent, what the revision drops it revokes (FAC-SEM-114, DEC-0084): a removed machine, a replaced key.
+    dropped = _dropped_findings(parent, record) if isinstance(parent, dict) else []
+    for finding in _record_findings(record) + dropped:
         if finding["code"] not in codes:
             codes.append(finding["code"])
     if codes:
@@ -851,6 +853,32 @@ def _revision_chain(value: Dict[str, Any]) -> List[Dict[str, str]]:
     return findings
 
 
+#: Standard base64 with its padding, the one form DEC-0053 records a device key's octets in.
+_BASE64 = re.compile(r"(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?\Z")
+#: DEC-0084: a key reference, a device-key kid, ``@sha256:`` and 64 lower-case hex digits.
+KEY_REFERENCE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:~-]{0,127}#(sig|kem)@sha256:[a-f0-9]{64}\Z")
+
+
+def device_key_fingerprint(key: Any) -> Optional[str]:
+    """A device key's fingerprint (DEC-0084): ``sha256:`` and the hex SHA-256 of its octets, ``publicKey`` read as
+    canonical padded base64; None for any other form, so two readers never disagree on which key it names."""
+    text = key.get("publicKey") if isinstance(key, dict) else None
+    if not isinstance(text, str) or not text or not _BASE64.match(text):
+        return None
+    raw = base64.b64decode(text)
+    if base64.b64encode(raw).decode("ascii") != text:
+        return None
+    return "sha256:" + hashlib.sha256(raw).hexdigest()
+
+
+def device_key_ref(key: Any) -> Optional[str]:
+    """The ``device-key`` revocation reference of one key (DEC-0084): ``<kid>@<fingerprint>``; None without a string kid
+    or a fingerprint. A replacement revokes the old key by it and leaves the next key under the same kid usable."""
+    fingerprint = device_key_fingerprint(key)
+    kid = key.get("kid") if isinstance(key, dict) else None
+    return "%s@%s" % (kid, fingerprint) if fingerprint is not None and isinstance(kid, str) else None
+
+
 def _valid_device_key(key: Dict[str, Any]) -> bool:
     public = _get(key, "publicKey")
     raw = _node_base64("" if public is _MISSING or public is None else _show(public))
@@ -877,7 +905,10 @@ def _keys(value: Dict[str, Any], flag) -> None:
         for key, k in _indexed(_get(machine, "deviceKeys")):
             if not _same(_get(key, "kid"), "%s#%s" % (_show(_get(machine, "id")), _show(_get(key, "use")))):
                 flag("%s/deviceKeys/%d/kid" % (at, k), "a device key is listed as <machine id>#sig or <machine id>#kem, by its role")
-            if not _valid_device_key(key):
+            # A key with no canonical fingerprint could be read as two keys by two readers, and no key reference names it (DEC-0084).
+            if device_key_fingerprint(key) is None:
+                flag("%s/deviceKeys/%d/publicKey" % (at, k), "a device key's octets are written in canonical padded base64, the one form a key reference can name (DEC-0084)")
+            elif not _valid_device_key(key):
                 flag("%s/deviceKeys/%d/publicKey" % (at, k), "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 _contains(seen, _get(key, "publicKey")):
                 flag("%s/deviceKeys/%d/publicKey" % (at, k), "one key is never used for the other role")
@@ -966,7 +997,9 @@ def _grants_and_revocations(value: Dict[str, Any], flag) -> None:
     listed = {
         "authority": [_get(e, "credentialId") for e in _list(_get(value, "authorities"))],
         "machine": [_get(m, "id") for m in machines],
-        "device-key": [_get(k, "kid") for m in machines for k in _list(_get(m, "deviceKeys"))],
+        # A kid, and each listed key's own reference (DEC-0084): revoking either while listing it is refused.
+        "device-key": [ref for m in machines for k in _list(_get(m, "deviceKeys"))
+                       for ref in ([_get(k, "kid")] if _get(k, "kid") is not _MISSING else []) + ([device_key_ref(k)] if device_key_ref(k) is not None else [])],
         "hub-key": [_get(m["hubKey"], "kid") for m in machines if isinstance(_get(m, "hubKey"), dict)],
         "publisher-key": [_get(k, "kid") for k in _list(_get(value, "publisherKeys"))],
         "package": [_get(p, "digest") for m in machines for p in _list(_get(m, "packages"))],
@@ -979,6 +1012,9 @@ def _grants_and_revocations(value: Dict[str, Any], flag) -> None:
         key = "%s %s" % (kind, _show(ref))
         if key in seen:
             flag("/revocations/%d" % index, "the %s %s is revoked twice" % (kind, _show(_get(revocation, "ref"))))
+        raw_ref = _get(revocation, "ref")
+        if _get(revocation, "kind") == "device-key" and isinstance(raw_ref, str) and "@" in raw_ref and not KEY_REFERENCE.match(raw_ref):
+            flag("/revocations/%d/ref" % index, "a device-key revocation names a kid or a key reference <kid>@sha256:<64 lower-case hex digits> (DEC-0084)")
         seen.append(key)
         if _contains(listed.get(kind, []), ref):
             flag("/revocations/%d/ref" % index, "the record still lists the %s it revokes: revocation outranks addition" % kind)
@@ -1029,6 +1065,46 @@ def _placement_grants(value: Dict[str, Any], flag) -> None:
                 flag("/machines/%d/packages/%d%s" % (m, p, suffix), message)
 
 
+def _dropped_findings(parent: Dict[str, Any], nxt: Dict[str, Any]) -> List[Dict[str, str]]:
+    """FAC-SEM-114 across two revisions (DEC-0084): what a revision drops, it revokes in the same revision. A removed
+    machine as ``machine <id>`` and its hub key as ``hub-key <kid>``; a replaced or dropped device key of a kept machine
+    as ``device-key`` by its reference or its kid; a hub key no longer certified as it was as ``hub-key <old kid>``."""
+    findings: List[Dict[str, str]] = []
+    flag = _finding(findings, "FAC-SEM-114")
+    revocations = _list(_get(nxt, "revocations"))
+
+    def revoked(kind: str, *refs: Any) -> bool:
+        return any(_get(entry, "kind") == kind and any(ref is not _MISSING and _same(_get(entry, "ref"), ref) for ref in refs)
+                   for entry in revocations)
+
+    kept_machines: List[Tuple[Any, Dict[str, Any]]] = []
+    for machine in _list(_get(nxt, "machines")):
+        if not any(_same(ident, _get(machine, "id")) for ident, _ in kept_machines):
+            kept_machines.append((_get(machine, "id"), machine))
+    for machine, m in _indexed(_get(parent, "machines")):
+        at = "/parent/machines/%d" % m
+        hub = _get(machine, "hubKey") if isinstance(_get(machine, "hubKey"), dict) else None
+        kept = next((found for ident, found in kept_machines if _same(ident, _get(machine, "id"))), None)
+        if kept is None:
+            if not revoked("machine", _get(machine, "id")):
+                flag("%s/id" % at, "machine %s is removed without its revocation: a revision that drops a machine lists machine %s in revocations" % (_show(_get(machine, "id")), _show(_get(machine, "id"))))
+            if hub is not None and not revoked("hub-key", _get(hub, "kid")):
+                flag("%s/hubKey/kid" % at, "the hub key %s of a removed machine is revoked in the same revision" % _show(_get(hub, "kid")))
+            continue
+        listed = {ref for ref in (device_key_ref(key) for key in _list(_get(kept, "deviceKeys"))) if ref is not None}
+        for key, k in _indexed(_get(machine, "deviceKeys")):
+            ref = device_key_ref(key)
+            if ref is None or ref in listed:
+                continue
+            if not revoked("device-key", ref, _get(key, "kid")):
+                flag("%s/deviceKeys/%d" % (at, k), "the device key %s is replaced or dropped without its revocation: the same revision lists device-key %s" % (_show(_get(key, "kid")), ref))
+        next_hub = _get(kept, "hubKey") if isinstance(_get(kept, "hubKey"), dict) else None
+        same_hub = next_hub is not None and _same(_get(next_hub, "kid"), _get(hub, "kid") if hub else _MISSING) and _same(_get(next_hub, "x"), _get(hub, "x") if hub else _MISSING)
+        if hub is not None and not same_hub and not revoked("hub-key", _get(hub, "kid")):
+            flag("%s/hubKey/kid" % at, "the hub key %s is no longer certified as it was: the same revision revokes hub-key %s, and a re-certified hub key takes a new kid" % (_show(_get(hub, "kid")), _show(_get(hub, "kid"))))
+    return findings
+
+
 def _record_findings(value: Dict[str, Any]) -> List[Dict[str, str]]:
     findings: List[Dict[str, str]] = []
     _revision_whole(value, _finding(findings, "FAC-SEM-072"))
@@ -1095,7 +1171,9 @@ def estate_record_rules(kind: str, value: Any) -> Optional[List[Dict[str, str]]]
     if kind == "estate-record":
         return _record_findings(value)
     if kind == "estate-record-revision":
-        return _revision_chain(value)
+        parent = value["parent"] if isinstance(_get(value, "parent"), dict) else {}
+        nxt = value["next"] if isinstance(_get(value, "next"), dict) else {}
+        return _revision_chain(value) + _dropped_findings(parent, nxt)
     if kind == "estate-placement":
         return _installation(value)
     return None