kya-os-verify 0.2.0__tar.gz

kya_os_verify-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+.claude/
+.venv/
+*.egg-info/
+dist/
+drafts/

kya_os_verify-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KYA-OS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kya_os_verify-0.2.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: kya-os-verify
+Version: 0.2.0
+Summary: Standalone stdlib-only verifier for KYA-OS primitives (org.kya-os/proof@1 holder-of-key proofs, did:key resolution) with vendored cross-language conformance vectors
+Project-URL: Specification, https://github.com/decentralized-identity/kya-os-mcp/blob/main/SPEC-ENTITY-CARD.md
+Project-URL: Vectors, https://github.com/decentralized-identity/kya-os-mcp/tree/main/conformance/vectors
+Author: KYA-OS contributors
+License: MIT
+License-File: LICENSE
+Keywords: conformance,did,ed25519,identity,kya-os,mcp,verifiable-credentials
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: cryptography>=42; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: fastmcp
+Requires-Dist: fastmcp>=2.9; extra == 'fastmcp'
+Description-Content-Type: text/markdown
+
+# kya-os-verify
+
+A standalone, stdlib-only Python verifier for KYA-OS's `org.kya-os/proof@1` holder-of-key proof and `did:key` DID resolution. It is a second-language implementation of the protocol reference-implemented in TypeScript by [`@kya-os/mcp`](https://github.com/decentralized-identity/kya-os-mcp), and it proves cross-language parity by running against the same signed conformance vectors, vendored from that repo at a pinned commit (`fcd38c7`, `@kya-os/mcp` 1.11.0).
+
+`pip install kya-os-verify` gets you a package with **zero runtime dependencies** and a CLI that self-checks against those vendored vectors.
+
+## Install
+
+```bash
+pip install kya-os-verify
+kya-os-verify selftest
+```
+
+Expected output: 10 `[PASS]` lines (7 card-proof + 3 did:key vectors) and:
+
+```
+RESULT: PASS — cross-language parity confirmed
+```
+
+## CLI
+
+```bash
+kya-os-verify selftest [--json]        # run the vendored conformance vectors
+kya-os-verify vectors PATH... [--json] # run one or more vector files
+```
+
+Exit codes: `0` everything matched, `1` at least one vector mismatched, `2` usage error or an unsupported vector category.
+
+## Library quickstart
+
+```python
+from kya_os_verify import verify_card_proof
+
+jwks = {"did:web:example.com:agents:acme#key-1": {"kty": "OKP", "crv": "Ed25519", "x": "..."}}
+
+result = verify_card_proof(
+    proof,                       # the org.kya-os/proof@1 object, e.g. from request._meta
+    request,                     # {"method": ..., "params": {...}}
+    resolve_key=lambda kid: jwks[kid],
+    resolve_did_keys=lambda did: [k for kid, k in jwks.items() if kid.split("#")[0] == did],
+    expected_audience="did:web:example.com:mcp:server",
+    consume_nonce=nonce_cache.consume,   # see kya_os_verify.InMemoryNonceCache
+)
+
+if result.ok:
+    print(result.did, result.level, result.warnings)
+else:
+    print(result.reasons)
+```
+
+`verify_card_proof` is fail-closed: it never raises on a bad proof, only on a programming error in the seams you supply. See `src/kya_os_verify/proof.py` for the full seam contract (`resolve_key`, `resolve_did_keys`, `consume_nonce`, `now_ms`, `skew_sec`, `token_cnf_jkt`, `trust_resolve_key_authority`).
+
+`resolve_did_keys` is what proves DID membership: without it (and without `trust_resolve_key_authority=True`), every proof fails closed with `did_membership_unverifiable`, because `resolve_key` alone doesn't prove the resolved key actually belongs to the DID document. If your `resolve_key` seam already authoritatively resolves keys scoped to their DID (e.g. it queries a DID document directly), pass `trust_resolve_key_authority=True` instead of `resolve_did_keys` to skip the separate membership check.
+
+## Reason codes
+
+`result.reasons` carries every binding that failed, using the reference implementation's codes verbatim:
+
+`malformed_proof`, `kid_did_mismatch`, `key_unresolvable`, `did_membership_unverifiable`, `did_keys_unresolvable`, `thumbprint_computation_failed`, `kid_not_in_did_document`, `alg_key_mismatch`, `audience_mismatch`, `request_hash_mismatch`, `invalid_window`, `ttl_too_long`, `created_in_future`, `expired`, `nonce_seam_missing`, `nonce_replayed`, `invalid_signature`, `cnf_key_mismatch`, `cnf_required_by_token`, `cnf_token_mismatch`.
+
+One warning code (non-fatal, in `result.warnings`): `cnf_present_but_token_unfused` — the proof carried a sender-constraint `cnf`, but no token `cnf.jkt` was supplied to fuse against, so the result is a valid `L3-minus` rather than `L3`.
+
+## Documented divergences from the TypeScript reference
+
+- **`es256_unsupported`**: Python's standard library has no P-256 (ES256) implementation. A proof with `alg: "ES256"` passes the schema and the alg/key-type binding, but signature verification fails closed with this Python-only reason code. Every vendored conformance vector is EdDSA, so vector parity is unaffected.
+- **Unsupported vector categories refuse loudly.** The upstream vector set also ships `audit-integrity`, `delegation-chain`, `did-web-resolution`, `entity-card`, `signed-proof`, and `status-list` categories. This package implements only `card-proof` and `did-key-resolution`; running any other category raises `UnsupportedCategoryError` rather than silently skipping it.
+- **Non-integer numbers in request params fail closed.** JCS canonicalization here (`jcs.py`) rejects any `float` value rather than attempting ECMAScript-style number formatting, so a request whose params contain a non-integer JSON number (e.g. `{"amount": 12.5}`) always yields `request_hash_mismatch`, even for an otherwise-valid proof. The TypeScript reference canonicalizes JS numbers and accepts the same proof. No vendored conformance vector exercises this path (all vectors use integer or string values); see `tests/test_proof.py::test_float_in_request_params_fails_closed_instead_of_raising`.
+
+## Provenance
+
+The vectors in `src/kya_os_verify/vectors/` are vendored byte-for-byte from `decentralized-identity/kya-os-mcp` at commit `fcd38c78502dbfb234b41c3ae8361ddeb3d7f83d` via `scripts/sync-vectors.sh`. CI re-runs that script and fails on any diff, so the vendored copies can never silently drift from the pin.
+
+- Protocol spec: [SPEC-ENTITY-CARD.md, section 8](https://github.com/decentralized-identity/kya-os-mcp/blob/main/SPEC-ENTITY-CARD.md)
+- Conformance vectors: [conformance/vectors](https://github.com/decentralized-identity/kya-os-mcp/tree/main/conformance/vectors)
+
+## FastMCP integration
+
+`pip install 'kya-os-verify[fastmcp]'` adds `with_kya_os()` (alias `with_KYA_OS`), a middleware for [FastMCP](https://github.com/PrefectHQ/fastmcp) (the PrefectHQ package) that gates every `tools/call` on a valid `org.kya-os/proof@1`:
+
+```python
+from fastmcp import FastMCP
+from kya_os_verify.fastmcp import with_KYA_OS
+
+mcp = FastMCP("my-server")
+# ... register tools ...
+with_KYA_OS(mcp, audience="did:web:my-server.example")
+```
+
+It is opt-in and zero-impact on any server that never calls it: nothing in `kya_os_verify.fastmcp` runs unless `with_kya_os`/`with_KYA_OS` is attached, and importing `kya_os_verify` (the core package) never imports `fastmcp`.
+
+**Which FastMCP?** This targets [`fastmcp`](https://github.com/PrefectHQ/fastmcp) (PrefectHQ's package, `pip install fastmcp`), the one with a middleware system. It is a *different* project from the official MCP Python SDK's bundled `mcp.server.fastmcp.FastMCP`, which does not support middleware and cannot use `with_kya_os`.
+
+**Key resolution**, in precedence order:
+1. `resolve_key=` (and optionally `resolve_did_keys=`) — an explicit seam, for a server backed by its own key store.
+2. `jwks={"keys": [...]}` — a static JWKS; keys are looked up by `kid`, and DID membership is checked against the same set unless `resolve_did_keys` overrides it.
+3. Neither supplied — zero-config `did:key` mode: the caller's `did:key` is resolved directly (self-certifying: membership is true by construction, since the DID *is* derived from the key).
+
+**Nonce cache caveat**: the default `InMemoryNonceCache` is per-middleware-instance and in-memory, so replay protection is scoped to a single server process. A multi-instance deployment needs a shared store (Redis, etc.) behind the same `consume(nonce, did) -> bool` seam, passed as `nonce_cache=`.
+
+See `examples/fastmcp-server/` for a runnable end-to-end demo.
+
+## License
+
+MIT. See `LICENSE`.

kya_os_verify-0.2.0/README.md

@@ -0,0 +1,104 @@
+# kya-os-verify
+
+A standalone, stdlib-only Python verifier for KYA-OS's `org.kya-os/proof@1` holder-of-key proof and `did:key` DID resolution. It is a second-language implementation of the protocol reference-implemented in TypeScript by [`@kya-os/mcp`](https://github.com/decentralized-identity/kya-os-mcp), and it proves cross-language parity by running against the same signed conformance vectors, vendored from that repo at a pinned commit (`fcd38c7`, `@kya-os/mcp` 1.11.0).
+
+`pip install kya-os-verify` gets you a package with **zero runtime dependencies** and a CLI that self-checks against those vendored vectors.
+
+## Install
+
+```bash
+pip install kya-os-verify
+kya-os-verify selftest
+```
+
+Expected output: 10 `[PASS]` lines (7 card-proof + 3 did:key vectors) and:
+
+```
+RESULT: PASS — cross-language parity confirmed
+```
+
+## CLI
+
+```bash
+kya-os-verify selftest [--json]        # run the vendored conformance vectors
+kya-os-verify vectors PATH... [--json] # run one or more vector files
+```
+
+Exit codes: `0` everything matched, `1` at least one vector mismatched, `2` usage error or an unsupported vector category.
+
+## Library quickstart
+
+```python
+from kya_os_verify import verify_card_proof
+
+jwks = {"did:web:example.com:agents:acme#key-1": {"kty": "OKP", "crv": "Ed25519", "x": "..."}}
+
+result = verify_card_proof(
+    proof,                       # the org.kya-os/proof@1 object, e.g. from request._meta
+    request,                     # {"method": ..., "params": {...}}
+    resolve_key=lambda kid: jwks[kid],
+    resolve_did_keys=lambda did: [k for kid, k in jwks.items() if kid.split("#")[0] == did],
+    expected_audience="did:web:example.com:mcp:server",
+    consume_nonce=nonce_cache.consume,   # see kya_os_verify.InMemoryNonceCache
+)
+
+if result.ok:
+    print(result.did, result.level, result.warnings)
+else:
+    print(result.reasons)
+```
+
+`verify_card_proof` is fail-closed: it never raises on a bad proof, only on a programming error in the seams you supply. See `src/kya_os_verify/proof.py` for the full seam contract (`resolve_key`, `resolve_did_keys`, `consume_nonce`, `now_ms`, `skew_sec`, `token_cnf_jkt`, `trust_resolve_key_authority`).
+
+`resolve_did_keys` is what proves DID membership: without it (and without `trust_resolve_key_authority=True`), every proof fails closed with `did_membership_unverifiable`, because `resolve_key` alone doesn't prove the resolved key actually belongs to the DID document. If your `resolve_key` seam already authoritatively resolves keys scoped to their DID (e.g. it queries a DID document directly), pass `trust_resolve_key_authority=True` instead of `resolve_did_keys` to skip the separate membership check.
+
+## Reason codes
+
+`result.reasons` carries every binding that failed, using the reference implementation's codes verbatim:
+
+`malformed_proof`, `kid_did_mismatch`, `key_unresolvable`, `did_membership_unverifiable`, `did_keys_unresolvable`, `thumbprint_computation_failed`, `kid_not_in_did_document`, `alg_key_mismatch`, `audience_mismatch`, `request_hash_mismatch`, `invalid_window`, `ttl_too_long`, `created_in_future`, `expired`, `nonce_seam_missing`, `nonce_replayed`, `invalid_signature`, `cnf_key_mismatch`, `cnf_required_by_token`, `cnf_token_mismatch`.
+
+One warning code (non-fatal, in `result.warnings`): `cnf_present_but_token_unfused` — the proof carried a sender-constraint `cnf`, but no token `cnf.jkt` was supplied to fuse against, so the result is a valid `L3-minus` rather than `L3`.
+
+## Documented divergences from the TypeScript reference
+
+- **`es256_unsupported`**: Python's standard library has no P-256 (ES256) implementation. A proof with `alg: "ES256"` passes the schema and the alg/key-type binding, but signature verification fails closed with this Python-only reason code. Every vendored conformance vector is EdDSA, so vector parity is unaffected.
+- **Unsupported vector categories refuse loudly.** The upstream vector set also ships `audit-integrity`, `delegation-chain`, `did-web-resolution`, `entity-card`, `signed-proof`, and `status-list` categories. This package implements only `card-proof` and `did-key-resolution`; running any other category raises `UnsupportedCategoryError` rather than silently skipping it.
+- **Non-integer numbers in request params fail closed.** JCS canonicalization here (`jcs.py`) rejects any `float` value rather than attempting ECMAScript-style number formatting, so a request whose params contain a non-integer JSON number (e.g. `{"amount": 12.5}`) always yields `request_hash_mismatch`, even for an otherwise-valid proof. The TypeScript reference canonicalizes JS numbers and accepts the same proof. No vendored conformance vector exercises this path (all vectors use integer or string values); see `tests/test_proof.py::test_float_in_request_params_fails_closed_instead_of_raising`.
+
+## Provenance
+
+The vectors in `src/kya_os_verify/vectors/` are vendored byte-for-byte from `decentralized-identity/kya-os-mcp` at commit `fcd38c78502dbfb234b41c3ae8361ddeb3d7f83d` via `scripts/sync-vectors.sh`. CI re-runs that script and fails on any diff, so the vendored copies can never silently drift from the pin.
+
+- Protocol spec: [SPEC-ENTITY-CARD.md, section 8](https://github.com/decentralized-identity/kya-os-mcp/blob/main/SPEC-ENTITY-CARD.md)
+- Conformance vectors: [conformance/vectors](https://github.com/decentralized-identity/kya-os-mcp/tree/main/conformance/vectors)
+
+## FastMCP integration
+
+`pip install 'kya-os-verify[fastmcp]'` adds `with_kya_os()` (alias `with_KYA_OS`), a middleware for [FastMCP](https://github.com/PrefectHQ/fastmcp) (the PrefectHQ package) that gates every `tools/call` on a valid `org.kya-os/proof@1`:
+
+```python
+from fastmcp import FastMCP
+from kya_os_verify.fastmcp import with_KYA_OS
+
+mcp = FastMCP("my-server")
+# ... register tools ...
+with_KYA_OS(mcp, audience="did:web:my-server.example")
+```
+
+It is opt-in and zero-impact on any server that never calls it: nothing in `kya_os_verify.fastmcp` runs unless `with_kya_os`/`with_KYA_OS` is attached, and importing `kya_os_verify` (the core package) never imports `fastmcp`.
+
+**Which FastMCP?** This targets [`fastmcp`](https://github.com/PrefectHQ/fastmcp) (PrefectHQ's package, `pip install fastmcp`), the one with a middleware system. It is a *different* project from the official MCP Python SDK's bundled `mcp.server.fastmcp.FastMCP`, which does not support middleware and cannot use `with_kya_os`.
+
+**Key resolution**, in precedence order:
+1. `resolve_key=` (and optionally `resolve_did_keys=`) — an explicit seam, for a server backed by its own key store.
+2. `jwks={"keys": [...]}` — a static JWKS; keys are looked up by `kid`, and DID membership is checked against the same set unless `resolve_did_keys` overrides it.
+3. Neither supplied — zero-config `did:key` mode: the caller's `did:key` is resolved directly (self-certifying: membership is true by construction, since the DID *is* derived from the key).
+
+**Nonce cache caveat**: the default `InMemoryNonceCache` is per-middleware-instance and in-memory, so replay protection is scoped to a single server process. A multi-instance deployment needs a shared store (Redis, etc.) behind the same `consume(nonce, did) -> bool` seam, passed as `nonce_cache=`.
+
+See `examples/fastmcp-server/` for a runnable end-to-end demo.
+
+## License
+
+MIT. See `LICENSE`.

kya_os_verify-0.2.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kya-os-verify"
+version = "0.2.0"
+description = "Standalone stdlib-only verifier for KYA-OS primitives (org.kya-os/proof@1 holder-of-key proofs, did:key resolution) with vendored cross-language conformance vectors"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "KYA-OS contributors" }]
+keywords = ["kya-os", "mcp", "did", "identity", "verifiable-credentials", "conformance", "ed25519"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Topic :: Security :: Cryptography",
+]
+
+[project.urls]
+Specification = "https://github.com/decentralized-identity/kya-os-mcp/blob/main/SPEC-ENTITY-CARD.md"
+Vectors = "https://github.com/decentralized-identity/kya-os-mcp/tree/main/conformance/vectors"
+
+[project.scripts]
+kya-os-verify = "kya_os_verify.cli:main"
+
+[project.optional-dependencies]
+fastmcp = ["fastmcp>=2.9"]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "cryptography>=42"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kya_os_verify"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/README.md", "/LICENSE"]

kya_os_verify-0.2.0/src/kya_os_verify/__init__.py

@@ -0,0 +1,43 @@
+"""kya-os-verify: standalone verifier for KYA-OS primitives.
+
+A pure-stdlib, second-language implementation of the org.kya-os/proof@1
+verification path defined by the KYA-OS protocol (SPEC-ENTITY-CARD.md
+section 8) and reference-implemented in TypeScript by @kya-os/mcp. It runs
+the same signed conformance vectors as the TypeScript harness, vendored at a
+pinned upstream commit, proving cross-language JCS (RFC 8785) and Ed25519
+signature parity.
+"""
+
+__version__ = "0.2.0"
+
+from .didkey import did_key_to_jwk
+from .nonce import NONCE_RETENTION_SEC, InMemoryNonceCache
+from .proof import (
+    DEFAULT_SKEW_SEC,
+    MAX_TTL_SEC,
+    PROOF_META_KEY,
+    PROOF_PROFILE_V1,
+    VerifyResult,
+    request_hash,
+    verify_card_proof,
+    verify_http_sig,
+)
+from .vectors import UnsupportedCategoryError, run_selftest, run_vector_file
+
+__all__ = [
+    "__version__",
+    "VerifyResult",
+    "verify_card_proof",
+    "verify_http_sig",
+    "request_hash",
+    "did_key_to_jwk",
+    "InMemoryNonceCache",
+    "NONCE_RETENTION_SEC",
+    "run_vector_file",
+    "run_selftest",
+    "UnsupportedCategoryError",
+    "PROOF_META_KEY",
+    "PROOF_PROFILE_V1",
+    "MAX_TTL_SEC",
+    "DEFAULT_SKEW_SEC",
+]

kya_os_verify-0.2.0/src/kya_os_verify/cli.py

@@ -0,0 +1,78 @@
+"""`kya-os-verify` console entry point: selftest and vectors subcommands."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Optional, Sequence
+
+from . import __version__
+from .vectors import UnsupportedCategoryError, run_selftest, run_vector_file
+
+
+def _print_report(report: dict, *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(report))
+        return
+    for r in report["results"]:
+        mark = "[PASS]" if r["matched"] else "[FAIL]"
+        print(f"{mark} {r['id']}: {r['detail']}")
+    if report["allMatched"]:
+        print("RESULT: PASS — cross-language parity confirmed")
+    else:
+        mismatched = sum(1 for r in report["results"] if not r["matched"])
+        print(f"RESULT: FAIL — {mismatched} of {len(report['results'])} vector(s) mismatched")
+
+
+def _cmd_selftest(args: argparse.Namespace) -> int:
+    report = run_selftest()
+    _print_report(report, as_json=args.json)
+    return 0 if report["allMatched"] else 1
+
+
+def _cmd_vectors(args: argparse.Namespace) -> int:
+    results: list = []
+    for path in args.paths:
+        try:
+            results.extend(run_vector_file(path))
+        except UnsupportedCategoryError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+    if not results:
+        # No silent caps: a file with zero vectors must not print
+        # "RESULT: PASS" — that reads as full coverage when nothing ran.
+        print("error: no vectors found in the given file(s)", file=sys.stderr)
+        return 2
+    report = {"allMatched": all(r["matched"] for r in results), "results": results}
+    _print_report(report, as_json=args.json)
+    return 0 if report["allMatched"] else 1
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="kya-os-verify")
+    parser.add_argument("--version", action="version", version=f"kya-os-verify {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    selftest = sub.add_parser("selftest", help="run all vendored conformance vectors")
+    selftest.add_argument("--json", action="store_true")
+    selftest.set_defaults(func=_cmd_selftest)
+
+    vectors = sub.add_parser("vectors", help="run one or more vector files")
+    vectors.add_argument("paths", nargs="+")
+    vectors.add_argument("--json", action="store_true")
+    vectors.set_defaults(func=_cmd_vectors)
+
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", None):
+        parser.print_usage(sys.stderr)
+        return 2
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

kya_os_verify-0.2.0/src/kya_os_verify/didkey.py

@@ -0,0 +1,48 @@
+"""did:key resolution to an Ed25519 JWK.
+
+Supports only the `z` (base58btc) multibase prefix and the Ed25519
+multicodec (0xed01), which is the only key type the vendored
+did-key-resolution.json vectors and the card-proof vectors exercise.
+Anything else (malformed multibase, wrong method, wrong multicodec) raises
+ValueError: fail-closed, no silent partial resolution.
+"""
+from __future__ import annotations
+
+from .encoding import b64url_nopad
+
+_B58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+_ED25519_MULTICODEC = b"\xed\x01"
+
+
+def _base58btc_decode(value: str) -> bytes:
+    num = 0
+    for char in value:
+        index = _B58_ALPHABET.find(char)
+        if index == -1:
+            raise ValueError(f"did:key: invalid base58btc character {char!r}")
+        num = num * 58 + index
+    decoded = num.to_bytes((num.bit_length() + 7) // 8, "big") if num else b""
+    n_leading_zeros = len(value) - len(value.lstrip("1"))
+    return b"\x00" * n_leading_zeros + decoded
+
+
+def did_key_to_jwk(did: str) -> dict:
+    """Resolve a did:key DID to an Ed25519 OKP JWK. Raises ValueError otherwise."""
+    prefix = "did:key:z"
+    if not did.startswith(prefix):
+        raise ValueError(f"did:key: not a did:key with z multibase: {did!r}")
+    try:
+        raw = _base58btc_decode(did[len(prefix) :])
+    except ValueError:
+        raise
+    except Exception as exc:
+        raise ValueError(f"did:key: base58btc decode failed: {exc}") from exc
+    if len(raw) != 34 or raw[:2] != _ED25519_MULTICODEC:
+        raise ValueError("did:key: not an Ed25519 (0xed01) multicodec key")
+    key_bytes = raw[2:]
+    return {
+        "kty": "OKP",
+        "crv": "Ed25519",
+        "x": b64url_nopad(key_bytes),
+        "kid": f"{did}#keys-1",
+    }

kya_os_verify-0.2.0/src/kya_os_verify/ed25519.py

@@ -0,0 +1,104 @@
+"""Ed25519 signature verification (RFC 8032), pure Python stdlib.
+
+Ported unchanged from decentralized-identity/kya-os-mcp
+conformance/verify.py (MIT), lines 27-121 at origin/main commit
+fcd38c78502dbfb234b41c3ae8361ddeb3d7f83d. Verification only (no signing).
+"""
+from __future__ import annotations
+
+import hashlib
+
+_p = 2 ** 255 - 19
+_L = 2 ** 252 + 27742317777372353535851937790883648493
+
+
+def _modp_inv(x):
+    return pow(x, _p - 2, _p)
+
+
+_d = -121665 * _modp_inv(121666) % _p
+_modp_sqrt_m1 = pow(2, (_p - 1) // 4, _p)
+
+
+def _sha512_modL(s):
+    return int.from_bytes(hashlib.sha512(s).digest(), "little") % _L
+
+
+def _point_add(P, Q):
+    A = (P[1] - P[0]) * (Q[1] - Q[0]) % _p
+    B = (P[1] + P[0]) * (Q[1] + Q[0]) % _p
+    C = 2 * P[3] * Q[3] * _d % _p
+    D = 2 * P[2] * Q[2] % _p
+    E, F, G, H = B - A, D - C, D + C, B + A
+    return (E * F % _p, G * H % _p, F * G % _p, E * H % _p)
+
+
+def _point_mul(s, P):
+    Q = (0, 1, 1, 0)  # neutral element
+    while s > 0:
+        if s & 1:
+            Q = _point_add(Q, P)
+        P = _point_add(P, P)
+        s >>= 1
+    return Q
+
+
+def _point_equal(P, Q):
+    if (P[0] * Q[2] - Q[0] * P[2]) % _p != 0:
+        return False
+    if (P[1] * Q[2] - Q[1] * P[2]) % _p != 0:
+        return False
+    return True
+
+
+def _recover_x(y, sign):
+    if y >= _p:
+        return None
+    x2 = (y * y - 1) * _modp_inv(_d * y * y + 1) % _p
+    if x2 == 0:
+        return None if sign else 0
+    x = pow(x2, (_p + 3) // 8, _p)
+    if (x * x - x2) % _p != 0:
+        x = x * _modp_sqrt_m1 % _p
+    if (x * x - x2) % _p != 0:
+        return None
+    if (x & 1) != sign:
+        x = _p - x
+    return x
+
+
+_g_y = 4 * _modp_inv(5) % _p
+_g_x = _recover_x(_g_y, 0)
+_G = (_g_x, _g_y, 1, _g_x * _g_y % _p)
+
+
+def _point_decompress(s):
+    if len(s) != 32:
+        return None
+    y = int.from_bytes(s, "little")
+    sign = y >> 255
+    y &= (1 << 255) - 1
+    x = _recover_x(y, sign)
+    if x is None:
+        return None
+    return (x, y, 1, x * y % _p)
+
+
+def ed25519_verify(public_key: bytes, message: bytes, signature: bytes) -> bool:
+    """Verify an Ed25519 signature (RFC 8032). Fail-closed on any malformed input."""
+    if len(public_key) != 32 or len(signature) != 64:
+        return False
+    A = _point_decompress(public_key)
+    if A is None:
+        return False
+    Rs = signature[:32]
+    R = _point_decompress(Rs)
+    if R is None:
+        return False
+    S = int.from_bytes(signature[32:], "little")
+    if S >= _L:
+        return False
+    h = _sha512_modL(Rs + public_key + message)
+    sB = _point_mul(S, _G)
+    hA = _point_mul(h, A)
+    return _point_equal(sB, _point_add(R, hA))

kya_os_verify-0.2.0/src/kya_os_verify/encoding.py

@@ -0,0 +1,20 @@
+"""base64url / base64 helpers for the wire encodings this protocol uses."""
+from __future__ import annotations
+
+import base64
+
+
+def b64url_decode(value: str) -> bytes:
+    """Decode base64url, re-padding as needed (the wire format omits padding)."""
+    padded = value + "=" * (-len(value) % 4)
+    return base64.urlsafe_b64decode(padded)
+
+
+def b64url_nopad(data: bytes) -> str:
+    """Encode as base64url without padding."""
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def std_b64(data: bytes) -> str:
+    """Encode as standard (non-url-safe) base64, with padding."""
+    return base64.b64encode(data).decode("ascii")