fkyh 0.1.0__py3-none-any.whl

fkyh/__init__.py

@@ -0,0 +1,37 @@
+"""
+FK YH — the reference implementation of the FK YH protocol.
+
+An open protocol for agent discovery, coordination, observability, and
+independently verifiable attestations. Piggybacks on existing protocol
+fields (mDNS, HTTP headers, Prometheus) — no new infrastructure.
+
+Modules:
+    state        agent and fleet state, and the FK YH response headers
+    discovery    mDNS advertisement and browsing
+    metrics      Prometheus exposition
+    gossip       the fleet scraper and the observer
+    attestation  the consumer side of the attestation protocol
+    node         the HTTP service that serves all of the above
+
+The package depends on the standard library only. `cryptography` is
+optional, and is needed for the two things that use a signature: the
+attestation layer (ATTESTATION.md) and the signed gossip headers of
+SPEC.md section 4.4.
+"""
+
+from fkyh.state import (
+    PROTOCOL_VERSION,
+    AgentState,
+    FleetState,
+    status_for,
+)
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "AgentState",
+    "FleetState",
+    "status_for",
+    "__version__",
+]
+
+__version__ = "0.1.0"

fkyh/__main__.py

@@ -0,0 +1,199 @@
+"""
+FK YH command line.
+
+    python3 -m fkyh keys create --keystore ./keys --name verifier-1
+    python3 -m fkyh keys show   --keystore ./keys
+    python3 -m fkyh keys revoke --keystore ./keys --name verifier-1 --reason "..."
+    python3 -m fkyh keys rotate --keystore ./keys --name verifier-1 --new-name verifier-2
+
+    python3 -m fkyh verify --attestation ./attestation.json --trust ./trust.json
+    python3 -m fkyh verify --attestation ./attestation.json --trust ./trust.json --json
+
+Key management exists because the reference node used to generate an
+ephemeral key on every start. A key that changes on every restart cannot be
+referenced by a trust configuration, so it cannot be authorised by anyone.
+
+`verify` exists because a specification nobody can run is a document, and a
+document is not a product. It is the one piece of this protocol that a
+stranger can point at their own code and use: give it an attestation and a
+trust configuration, and it tells you what can be relied upon. The three
+outcomes are kept distinct because they are three different facts:
+`verified` is an authentic attestation reporting success, `failed` is an
+authentic attestation reporting failure, and `inconclusive` is an authentic
+attestation that could not decide. All three are authentic; only the first
+is a success, and a verifier that collapses them would let a caller act on
+a report of failure.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from fkyh.attestation import AttestationError, Consumer, TrustConfig  # noqa: E402
+from fkyh.keys import KeyStore, KeyStoreError  # noqa: E402
+
+
+def _cmd_keys(args) -> int:
+    store = KeyStore(args.keystore)
+    try:
+        if args.action == "create":
+            key = store.create(args.name, policies=args.policy or [],
+                               overwrite=args.force)
+            print(f"created {key.name}")
+            print(f"  key id    : {key.key_id}")
+            print(f"  private   : {key.private_path} (mode 0600)")
+            print(f"  policies  : {key.policies or ['(any the consumer allows)']}")
+            print(f"  trust     : {store.trust_path}")
+            return 0
+
+        if args.action == "show":
+            config = store.trust_config()
+            print(json.dumps(config, indent=2, sort_keys=True))
+            return 0
+
+        if args.action == "revoke":
+            key_id = store.key_id_for(args.name)
+            if key_id is None:
+                print(f"no key named {args.name!r}", file=sys.stderr)
+                return 2
+            store.revoke(key_id, reason=args.reason)
+            print(f"revoked {key_id} ({args.name}): {args.reason}")
+            return 0
+
+        if args.action == "rotate":
+            successor = store.rotate(args.name, args.new_name,
+                                     policies=args.policy or None)
+            print(f"rotated {args.name} -> {args.new_name}")
+            print(f"  new key id : {successor.key_id}")
+            print(f"  private    : {successor.private_path} (mode 0600)")
+            return 0
+    except KeyStoreError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    return 2
+
+
+def _cmd_verify(args) -> int:
+    """Validate one attestation against a trust configuration.
+
+    The exit code is the part that matters to a caller, so it is defined
+    precisely and it is not a boolean. Zero means the attestation is
+    authentic AND reports success. One means it is authentic and reports
+    something else — a caller must not act on that, but the record is real
+    and the report may be exactly what a reader needs to see. Two means the
+    attestation could not be relied upon at all: forged, expired, replayed,
+    or malformed. Three is a usage or I/O failure, which is a different
+    thing again: nothing was concluded.
+
+    Collapsing those into pass/fail would lose the distinction that
+    ATTESTATION.md section 9 is about — an authentic report of failure is
+    evidence, and a forged report is not.
+    """
+    try:
+        with open(args.attestation, encoding="utf-8") as handle:
+            payload = json.load(handle)
+    except (OSError, ValueError) as exc:
+        print(f"error: cannot read attestation: {exc}", file=sys.stderr)
+        return 3
+
+    try:
+        trust = TrustConfig.load(args.trust)
+    except (OSError, ValueError) as exc:
+        print(f"error: cannot read trust configuration: {exc}",
+              file=sys.stderr)
+        return 3
+
+    consumer = Consumer(trust, evidence_root=args.evidence)
+    try:
+        result = consumer.validate(payload,
+                                   expected_task_id=args.task_id,
+                                   expected_attempt_id=args.attempt_id)
+    except AttestationError as exc:
+        # The package is standard library only, and `cryptography` is an
+        # optional extra because only the signature paths need it. That is
+        # the right shape for a LIBRARY, and the wrong shape for a COMMAND:
+        # a stranger who typed `pip install fkyh` and then `fkyh verify`
+        # must not be handed a traceback. The fix is one pip extra, and the
+        # message says exactly which one.
+        if "cryptography package is required" in str(exc):
+            print("error: verifying a signature needs the optional "
+                  "cryptography dependency.\n"
+                  "       install it with:  pip install 'fkyh[signing]'",
+                  file=sys.stderr)
+            return 3
+        raise
+
+    if args.json:
+        print(json.dumps(result.to_dict(), indent=2, sort_keys=True))
+    else:
+        print(f"outcome : {result.result or result.code}")
+        print(f"accepted: {result.accepted}")
+        print(f"trusted : {result.trusted}")
+        if result.code and result.code != result.result:
+            print(f"code    : {result.code}")
+        if result.detail:
+            print(f"detail  : {result.detail}")
+        if result.task_id:
+            print(f"task    : {result.task_id}")
+        if result.attempt_id:
+            print(f"attempt : {result.attempt_id}")
+        if result.policy_id:
+            print(f"policy  : {result.policy_id}")
+        if result.verifier_key_id:
+            print(f"verifier: {result.verifier_key_id}")
+        for check in result.checks:
+            print(f"  check  : {check}")
+
+    if result.trusted:
+        return 0
+    if result.accepted:
+        return 1
+    return 2
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="fkyh")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    keys = sub.add_parser("keys", help="manage verifier keys")
+    keys.add_argument("action", choices=["create", "show", "revoke", "rotate"])
+    keys.add_argument("--keystore", required=True,
+                       help="directory holding the keys and trust.json")
+    keys.add_argument("--name", default="verifier-1",
+                       help="name of the key")
+    keys.add_argument("--new-name", default=None,
+                       help="name of the successor key (rotate)")
+    keys.add_argument("--policy", action="append",
+                       help="a policy this key may attest under; repeatable")
+    keys.add_argument("--reason", default="unspecified",
+                       help="why the key is being revoked")
+    keys.add_argument("--force", action="store_true",
+                       help="overwrite an existing private key")
+    keys.set_defaults(func=_cmd_keys)
+
+    verify = sub.add_parser("verify", help="validate an attestation")
+    verify.add_argument("--attestation", required=True,
+                         help="the attestation JSON to validate")
+    verify.add_argument("--trust", required=True,
+                         help="the trust configuration to validate against")
+    verify.add_argument("--evidence", default=None,
+                         help="the evidence directory, so the consumer can "
+                              "re-derive digests (ATTESTATION.md section 10)")
+    verify.add_argument("--task-id", default=None,
+                         help="require this task_id")
+    verify.add_argument("--attempt-id", default=None,
+                         help="require this attempt_id")
+    verify.add_argument("--json", action="store_true",
+                         help="print the verdict as JSON")
+    verify.set_defaults(func=_cmd_verify)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())