sm-conformance 0.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. sm_conformance-0.3.1/.gitattributes +5 -0
  2. sm_conformance-0.3.1/.github/CODEOWNERS +1 -0
  3. sm_conformance-0.3.1/.github/workflows/ci.yml +22 -0
  4. sm_conformance-0.3.1/.github/workflows/release.yml +44 -0
  5. sm_conformance-0.3.1/.gitignore +20 -0
  6. sm_conformance-0.3.1/CHANGELOG.md +93 -0
  7. sm_conformance-0.3.1/GOVERNANCE.md +34 -0
  8. sm_conformance-0.3.1/LICENSE +21 -0
  9. sm_conformance-0.3.1/PKG-INFO +154 -0
  10. sm_conformance-0.3.1/PUBLISHING.md +40 -0
  11. sm_conformance-0.3.1/README.md +129 -0
  12. sm_conformance-0.3.1/SPEC.md +309 -0
  13. sm_conformance-0.3.1/WHITEPAPER.md +166 -0
  14. sm_conformance-0.3.1/examples/demo.py +61 -0
  15. sm_conformance-0.3.1/pyproject.toml +69 -0
  16. sm_conformance-0.3.1/sm_conformance/__init__.py +57 -0
  17. sm_conformance-0.3.1/sm_conformance/_badge_vector_gen.py +252 -0
  18. sm_conformance-0.3.1/sm_conformance/badge.py +390 -0
  19. sm_conformance-0.3.1/sm_conformance/countersign.py +149 -0
  20. sm_conformance-0.3.1/sm_conformance/py.typed +0 -0
  21. sm_conformance-0.3.1/sm_conformance/schema/common.schema.json +31 -0
  22. sm_conformance-0.3.1/sm_conformance/schema/conformance-envelope.schema.json +99 -0
  23. sm_conformance-0.3.1/sm_conformance/schema/counter-signed-envelope.schema.json +41 -0
  24. sm_conformance-0.3.1/sm_conformance/vectors/canonicalization.json +91 -0
  25. sm_conformance-0.3.1/sm_conformance/verify_badge.py +321 -0
  26. sm_conformance-0.3.1/tests/fixtures/failing-run.json +33 -0
  27. sm_conformance-0.3.1/tests/fixtures/missing-signature.json +32 -0
  28. sm_conformance-0.3.1/tests/fixtures/non-didkey-signer.json +33 -0
  29. sm_conformance-0.3.1/tests/fixtures/tampered-payload.json +33 -0
  30. sm_conformance-0.3.1/tests/fixtures/tampered-signature.json +33 -0
  31. sm_conformance-0.3.1/tests/fixtures/valid-signed-badge.json +33 -0
  32. sm_conformance-0.3.1/tests/fixtures/wrong-signer.json +34 -0
  33. sm_conformance-0.3.1/tests/test_badge.py +370 -0
  34. sm_conformance-0.3.1/tests/test_badge_vectors.py +151 -0
  35. sm_conformance-0.3.1/tests/test_canonicalization_vectors.py +35 -0
  36. sm_conformance-0.3.1/tests/test_countersign.py +168 -0
  37. sm_conformance-0.3.1/tests/test_hardening.py +301 -0
@@ -0,0 +1,5 @@
1
+ # Conformance vectors and fixtures must hash identically across platforms.
2
+ # compute_suite_digest reads raw bytes; without this a Windows checkout would
3
+ # CRLF-normalize the JSON and fork the suite_digest. Pin LF.
4
+ *.json text eol=lf
5
+ *.py text eol=lf
@@ -0,0 +1 @@
1
+ * @Sharathvc23
@@ -0,0 +1,22 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ runs-on: ubuntu-latest
11
+ strategy:
12
+ matrix:
13
+ python-version: ["3.11", "3.12"]
14
+ steps:
15
+ - uses: actions/checkout@v4
16
+ - uses: actions/setup-python@v5
17
+ with:
18
+ python-version: ${{ matrix.python-version }}
19
+ - run: pip install -e ".[dev]"
20
+ - run: ruff check sm_conformance tests
21
+ - run: mypy sm_conformance
22
+ - run: coverage run -m pytest && coverage report
@@ -0,0 +1,44 @@
1
+ # Publish sm-conformance to PyPI on a version tag, via PyPI Trusted Publishing (OIDC).
2
+ #
3
+ # No API token: PyPI is told once (in its web UI) to trust THIS repo + THIS
4
+ # workflow file, and `id-token: write` lets the job mint a short-lived OIDC token
5
+ # PyPI accepts. See PUBLISHING.md for the one-time setup and the exact values to
6
+ # type into PyPI's "Add a publisher" form.
7
+ #
8
+ # Fires only when a tag like `v0.3.1` is pushed — never on normal commits.
9
+ name: release
10
+
11
+ on:
12
+ push:
13
+ tags:
14
+ - "v*"
15
+
16
+ permissions:
17
+ contents: read
18
+
19
+ jobs:
20
+ publish:
21
+ name: Build + publish to PyPI
22
+ runs-on: ubuntu-latest
23
+ permissions:
24
+ id-token: write # REQUIRED for Trusted Publishing — this is what replaces the token.
25
+ steps:
26
+ - uses: actions/checkout@v4
27
+
28
+ - uses: actions/setup-python@v5
29
+ with:
30
+ python-version: "3.12"
31
+
32
+ - name: Build sdist + wheel
33
+ run: |
34
+ python -m pip install --upgrade build
35
+ python -m build
36
+
37
+ - name: Check the built distributions
38
+ run: |
39
+ python -m pip install --upgrade twine
40
+ python -m twine check dist/*
41
+
42
+ - name: Publish to PyPI
43
+ # No `with: password:` — the action uses the OIDC token automatically.
44
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,20 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ build/
6
+ dist/
7
+ .venv/
8
+ venv/
9
+
10
+ # Tooling caches
11
+ .pytest_cache/
12
+ .mypy_cache/
13
+ .ruff_cache/
14
+ .coverage
15
+ htmlcov/
16
+ coverage/
17
+
18
+ # Agent tooling (never commit dev artifacts)
19
+ .claude/
20
+ .DS_Store
@@ -0,0 +1,93 @@
1
+ # Changelog
2
+
3
+ ## v0.3.1 — `errored` outcome bucket
4
+
5
+ - Add the optional `errored` payload count: a test that **errored** (setup/teardown
6
+ failure) rather than ran-and-failed. Previously such tests fell into no bucket and
7
+ silently vanished from the accounting.
8
+ - `errored` counts toward the `total_vectors` completeness sum, and a verifier rejects
9
+ `errored > 0` by default (not a passing run), like `failed`/`xfailed`.
10
+
11
+
12
+ ## v0.3.0 — Tier-3 audit fixes: cross-language vectors, tight regex, base64, freshness honesty
13
+
14
+ - **Cross-language canonicalization vectors** (`sm_conformance/vectors/canonicalization.json`):
15
+ valid→canonical-bytes + invalid (float / non-ASCII) the future Go/Rust/TS verifiers
16
+ check themselves against. Authoring them caught a real bug: **non-ASCII object keys**
17
+ were not rejected (only non-string keys) — now rejected.
18
+ - **Tighter `didKey` regex**: Ed25519 did:key is always `z6Mk`+44 base58 chars; bound it
19
+ (was `{32,}`), matching the tight signature regex.
20
+ - **SPEC §7**: signature is **standard** base64 (RFC 4648 §4), not url-safe.
21
+ - **SPEC §12.1**: a relying party **MUST NOT** gate freshness on the forgeable, unsigned
22
+ `countersigned_at`; use the signed inner `completed_at`. `method: "verified"` carries no
23
+ fresh signed timestamp.
24
+ - **SPEC §2**: the "why not Sigstore / in-toto / cosign" case (offline, no transparency log
25
+ or PKI, dependency-light cross-language verify; they compose as rungs above, not the base).
26
+
27
+
28
+ ## v0.2.0 — Second hardening: skip-identity, build & code binding, freshness, generator
29
+
30
+ Closes the holes that survive a correctly-configured verifier (an external audit's
31
+ Tier-1/2 findings), and adds the generate side the toolkit was missing.
32
+
33
+ - **build_badge()** — turnkey generator: counts + skipped-vector IDs + run provenance
34
+ → signed badge.
35
+ - **skipped_vectors** (signed) + `--max-skipped` / `--forbid-skip` / `--require-skip-ids`
36
+ — the bare `skipped` count let a runtime skip the adversarial vector it would fail
37
+ and still pass; the identities make skips gateable.
38
+ - **compute_code_digest** + `conformance.suite.code_digest` + `--expected-code-digest`
39
+ — pins a behavioral suite's *test code*, which `suite_digest` (vectors-only) cannot.
40
+ - **conformance.run.build** + `--expected-build` — "which build passed?"; fixed the
41
+ docstring that claimed commit-binding with no field.
42
+ - **`--max-age-days`** against the **signed** `completed_at` (not the forgeable
43
+ `countersigned_at`); reject **`xfailed > 0`** (drift-laundering) by default.
44
+ - **compute_suite_digest**: POSIX-string sort + `.gitattributes` (LF) — no cross-platform drift.
45
+ - SPEC §3.2/§5.2/§8/§9 (+ §9.1 locked-down invocation). All additive; `schema_version`
46
+ stays 1, every v0.1.0 badge still verifies.
47
+
48
+
49
+ ## v0.1.0 — Initial public release
50
+
51
+ First public release of `sm-conformance` — the signed conformance-badge toolkit,
52
+ shipping trust-ladder rungs 1 and 2 with an honest, load-bearing verify path.
53
+
54
+ **Badge (rung 1, self-signed)**
55
+ - Signed badge envelope: build, sign, verify, and pin to a vector corpus by
56
+ `suite_digest`; offline-verifiable against the runtime's `did:key`.
57
+ - `sm-verify-badge` CLI + JSON Schemas for the envelope.
58
+
59
+ **Counter-signature (rung 2, lab-attested)**
60
+ - `counter_sign` / `verify_countersigned` — a neutral lab wraps a runtime's badge
61
+ in its own Ed25519 signature, attesting it re-ran (`lab-rerun`) or verified
62
+ (`verified`) it; both signatures verify independently, the signed `method` is
63
+ unalterable.
64
+ - Admission gates — `--require-countersigned`, `--require-method`,
65
+ `--trusted-signer` let a relying party *require* rung 2, making registry
66
+ admission enforceable.
67
+ - Normative wire format: `SPEC.md` §12.
68
+
69
+ **Honest canonicalization**
70
+ - `canonical_json` uses **RFC 8785 (JCS)** via the `jcs` library — the same library
71
+ the `arp` receipt suite uses, so the two cannot diverge.
72
+ - The signed value space is **constrained**: floats, non-ASCII strings, and bytes
73
+ are rejected on *both* the sign and verify paths (`CanonicalizationError`), before
74
+ any signature is computed or checked.
75
+
76
+ **Load-bearing verification**
77
+ - `verify_envelope` validates against `conformance-envelope.schema.json` **after**
78
+ signature verification — a malformed-but-signed badge is rejected by the library,
79
+ not merely flagged in a test. `verify_countersigned` validates against
80
+ `counter-signed-envelope.schema.json`, so rung 2 is enforced like rung 1.
81
+ - Optional signed `total_vectors`; when present the counts MUST sum to it. It is
82
+ self-attested — `verify_badge --expected-total-vectors N` is the transferable
83
+ under-execution check (the count comes from what the verifier knows for the
84
+ `suite_digest`), with `--require-total-vectors` to demand the field. A badge
85
+ attests *one* run and is not a transferable credential (`SPEC.md` §3.1).
86
+
87
+ The attested-CI rung (SLSA / Sigstore) is the next slice.
88
+
89
+ **Known follow-up**
90
+ - The umbrella's forked `badge.py` (which signs the runtime badges) carries its own
91
+ encoder; aligning it to import this primitive is tracked separately.
92
+
93
+ - 74 tests; ruff + mypy --strict clean; 93% coverage.
@@ -0,0 +1,34 @@
1
+ # Governance
2
+
3
+ ## Scope
4
+
5
+ | In scope | Out of scope |
6
+ | --- | --- |
7
+ | The signed badge envelope: build, sign, suite-digest pin, verify, CLI, schemas, vectors. | A specific protocol's tests / vectors / adapter; transport and publication of badges; the counter-sign and attested-CI tooling (tracked for v0.2). |
8
+
9
+ The primitive owns one thing. Anything outside the table belongs to a companion
10
+ package or the consumer's stack.
11
+
12
+ ## Versioning
13
+
14
+ Semantic Versioning 2.0.0. The protocol surface (wire shape / algorithm) is
15
+ frozen within a major. A change to it requires an RFC-style PR to `SPEC.md`
16
+ before code.
17
+
18
+ ## Conformance
19
+
20
+ The test suite under `tests/` (and any vectors it loads) is the authoritative
21
+ behavioural specification. A change in behaviour without a corresponding test
22
+ change is a bug.
23
+
24
+ ## Contributions
25
+
26
+ - PRs must include tests and pass `ruff` + `mypy --strict` + `pytest`.
27
+ - No expansion of the protocol surface without an accepted RFC.
28
+ - No domain-specific or deployment-specific content — this is a generic
29
+ primitive (see the neutrality checklist in the extraction playbook).
30
+ - Sign off with the Developer Certificate of Origin (DCO), not a CLA.
31
+
32
+ ## Attribution
33
+
34
+ *Personal research contributions aligned with [Project NANDA](https://projectnanda.org) standards. [Stellarminds.ai](https://stellarminds.ai)*
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 stellarminds.ai
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,154 @@
1
+ Metadata-Version: 2.4
2
+ Name: sm-conformance
3
+ Version: 0.3.1
4
+ Summary: Mechanical, cryptographically-attestable protocol conformance — signed badges any party re-verifies offline
5
+ Author: stellarminds.ai
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Keywords: agents,attestation,conformance,did-key,ed25519
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Typing :: Typed
13
+ Requires-Python: >=3.11
14
+ Requires-Dist: base58>=2.1
15
+ Requires-Dist: cryptography>=41.0
16
+ Requires-Dist: jcs>=0.2.1
17
+ Requires-Dist: jsonschema>=4.0
18
+ Requires-Dist: referencing>=0.30
19
+ Provides-Extra: dev
20
+ Requires-Dist: coverage>=7.0; extra == 'dev'
21
+ Requires-Dist: mypy>=1.0; extra == 'dev'
22
+ Requires-Dist: pytest>=7.0; extra == 'dev'
23
+ Requires-Dist: ruff>=0.4; extra == 'dev'
24
+ Description-Content-Type: text/markdown
25
+
26
+ # sm-conformance
27
+
28
+ **Mechanical, cryptographically-attestable protocol conformance — signed badges any party re-verifies offline.**
29
+
30
+ A protocol is only "open" if compliance is *checkable*. `sm-conformance` is the
31
+ toolkit for that check: a runtime runs a vectors-driven suite, then ships a small
32
+ JSON **badge** signed by its own Ed25519 key recording *which* suite it passed
33
+ (pinned by a `suite_digest`) and the pass/fail counts. Anyone holding the
34
+ runtime's `did:key` can re-verify the badge **offline** — no service, no vendor,
35
+ no trust-me. This package owns exactly that envelope: building it, signing it,
36
+ pinning it, and verifying it. It does **not** define your protocol's tests — you
37
+ bring those.
38
+
39
+ ## What this package secures (v0.1)
40
+
41
+ - **Offline-verifiable attestation.** A badge is an Ed25519 signature over an
42
+ RFC 8785 (JCS) canonical JSON payload, with the signed value space constrained
43
+ to ASCII strings, integers, booleans, and null so two implementations cannot
44
+ diverge; verification needs only the embedded `did:key` and `cryptography` — no
45
+ network, no proprietary service.
46
+ - **Load-bearing structure.** `verify_envelope` validates the payload against the
47
+ JSON Schema *on the verify path* — a malformed-but-signed badge is rejected, not
48
+ merely flagged in a test.
49
+ - **Corpus pinning.** `suite_digest` is a SHA-256 over the vector corpus, so a
50
+ badge proves *which* suite ran; swapping in a weaker corpus changes the digest.
51
+ - **Honest gating.** The verifier refuses a badge that records `failed > 0` or a
52
+ non-zero exit status unless you explicitly opt into signature-only mode.
53
+ - **Adversarially tested.** Tampered payloads, tampered signatures, wrong signer,
54
+ non-`did:key` signer, missing fields, and pass-gate evasion are all covered by
55
+ golden vectors and unit tests (74 tests).
56
+
57
+ ## What this package does NOT do
58
+
59
+ - **Run your tests.** It attests *the result* of a suite; wiring a suite (and the
60
+ adapter that plugs a runtime in) is the consumer's responsibility — see the
61
+ reference example.
62
+ - **Prove a self-signed run happened.** A rung-1 badge is a *claim* by the key
63
+ holder; its `total_vectors` is self-attested and catches only an honest partial
64
+ run. Closing under-execution against an adversarial signer is what
65
+ `--expected-total-vectors` (a count the verifier knows independently) and rung-2
66
+ lab counter-signing are for — both shipped, see [`SPEC.md`](./SPEC.md) §9, §11.
67
+
68
+ ## Features
69
+
70
+ - `sign_envelope` / `verify_envelope` — build and check a signed badge.
71
+ - `build_badge(runtime, …)` — turnkey generator: assemble + sign a badge from a
72
+ test run's counts, the skipped-vector IDs, and run provenance.
73
+ - `compute_suite_digest(path)` — pin a badge to a vector corpus (cross-platform stable).
74
+ - `derive_did_key` / `parse_did_key` — W3C `did:key` (base58btc, multicodec `0xed01`).
75
+ - `run_extensions(surface, target, build=…)` — namespaced run provenance incl. build.
76
+ - `sm-verify-badge` CLI with admission gates: `--expected-suite-digest`,
77
+ `--expected-total-vectors`, `--max-skipped` / `--forbid-skip` / `--require-skip-ids`,
78
+ `--expected-build`, `--max-age-days`, `--require-countersigned` (see SPEC §9.1).
79
+ - JSON Schemas for the envelope + counter-signed envelope (`sm_conformance/schema/`),
80
+ enforced on the verify path.
81
+
82
+ ## Where the badge lives
83
+
84
+ On disk a runtime ships its badge at `.nanda/conformance.json`. A runtime that
85
+ serves it over HTTP **should** do so at the canonical URL **`/.well-known/conformance.json`**
86
+ — unauthenticated (it's verifiable offline by anyone against the embedded `did:key`)
87
+ — and advertise that URL from its discovery doc (a `conformance` field in
88
+ `/.well-known/nanda-agent.json`). See [`SPEC.md`](./SPEC.md) §3.2.
89
+
90
+ ## Installation
91
+
92
+ ```bash
93
+ pip install sm-conformance
94
+ # working draft: pip install git+https://github.com/Sharathvc23/sm-conformance.git
95
+ ```
96
+
97
+ ## Quick start
98
+
99
+ ```python
100
+ from sm_conformance import sign_envelope, verify_envelope, compute_suite_digest
101
+
102
+ payload = {
103
+ "schema_version": 1,
104
+ "runtime": "my-runtime",
105
+ "protocol_versions": ["0.1"],
106
+ "suite_digest": compute_suite_digest("vectors"), # SHA-256 over your corpus
107
+ "completed_at": "2026-05-31T00:00:00+00:00",
108
+ "exit_status": 0,
109
+ "passed": 42, "failed": 0, "skipped": 0, "xfailed": 0, "xpassed": 0,
110
+ }
111
+
112
+ seed = bytes(range(32)) # your runtime's Ed25519 seed (32 bytes)
113
+ badge = sign_envelope(payload, seed, "2026-05-31T00:00:00+00:00")
114
+
115
+ verify_envelope(badge) # raises VerificationError if invalid
116
+ ```
117
+
118
+ ```bash
119
+ sm-verify-badge badge.json --expected-suite-digest sha256:<hex>
120
+ ```
121
+
122
+ ## Reference fixtures
123
+
124
+ `tests/fixtures/` holds the golden badge vectors — one positive
125
+ (`valid-signed-badge`) and six negative (`tampered-payload`, `tampered-signature`,
126
+ `wrong-signer`, `non-didkey-signer`, `missing-signature`, `failing-run`), each
127
+ self-declaring its expected verification outcome. They are deterministic
128
+ (regenerate with `python -m sm_conformance._badge_vector_gen`). The keys are
129
+ fixed test seeds, not production signers.
130
+
131
+ ## Specification
132
+
133
+ - [`SPEC.md`](./SPEC.md) — normative envelope, canonical encoding, signing,
134
+ suite-digest, verification algorithm, and trust ladder. Working draft.
135
+ - [`WHITEPAPER.md`](./WHITEPAPER.md) — why mechanical conformance matters for an
136
+ internet of independently-built agents.
137
+
138
+ ## Related packages
139
+
140
+ | Package | Role |
141
+ | --- | --- |
142
+ | [`sm-attest-viewer`](https://github.com/Sharathvc23/sm-attest-viewer) | Renderer for attested agent action-envelope chains |
143
+ | [`sm-decision-inspector`](https://github.com/Sharathvc23/sm-decision-inspector) | Human-in-the-loop decision workbench |
144
+ | [`sm-locp`](https://github.com/Sharathvc23/sm-locp) | Open compliance protocol (defeasible logic + W3C VCs) |
145
+
146
+ ## License
147
+
148
+ [MIT](./LICENSE)
149
+
150
+ ---
151
+
152
+ *First published: 2026-05-31 | Last modified: 2026-05-31*
153
+
154
+ *Personal research contributions aligned with [Project NANDA](https://projectnanda.org) standards. [Stellarminds.ai](https://stellarminds.ai)*
@@ -0,0 +1,40 @@
1
+ # Publishing sm-conformance to PyPI
2
+
3
+ `sm-conformance` publishes via **PyPI Trusted Publishing** — no API tokens. PyPI
4
+ trusts this repo's `release.yml` workflow; pushing a version tag builds and
5
+ uploads automatically.
6
+
7
+ ## One-time setup (the part only you can do)
8
+
9
+ 1. PyPI account with 2FA → https://pypi.org/account/register/
10
+ 2. https://pypi.org/manage/account/publishing/ → "Add a pending publisher".
11
+ 3. Fill the form with **exactly**:
12
+
13
+ | Field | Value |
14
+ |-------|-------|
15
+ | PyPI Project Name | `sm-conformance` |
16
+ | Owner | `Sharathvc23` |
17
+ | Repository name | `sm-conformance` |
18
+ | **Workflow name** | `release.yml` |
19
+ | Environment name | *(leave blank)* |
20
+
21
+ > The **Workflow name must be `release.yml`** to match the file in this repo —
22
+ > a mismatch makes the publish step fail with a trust error.
23
+
24
+ ## Releasing
25
+
26
+ ```bash
27
+ # version in pyproject.toml is the one that publishes; tag should match it
28
+ git tag v0.3.1
29
+ git push origin v0.3.1
30
+ ```
31
+
32
+ The `release` workflow builds + `twine check`s + uploads over OIDC. Watch it
33
+ under the repo's **Actions** tab; within a minute `pip install sm-conformance`
34
+ works for everyone, and `sm-arp[conformance]` resolves against it.
35
+
36
+ ## Notes
37
+ - Tag and `pyproject.toml` `version` should match.
38
+ - Dry run, no upload: `python -m build && python -m twine check dist/*`.
39
+ - TestPyPI trial: add a pending publisher on test.pypi.org and add
40
+ `with: { repository-url: https://test.pypi.org/legacy/ }` to the publish step.
@@ -0,0 +1,129 @@
1
+ # sm-conformance
2
+
3
+ **Mechanical, cryptographically-attestable protocol conformance — signed badges any party re-verifies offline.**
4
+
5
+ A protocol is only "open" if compliance is *checkable*. `sm-conformance` is the
6
+ toolkit for that check: a runtime runs a vectors-driven suite, then ships a small
7
+ JSON **badge** signed by its own Ed25519 key recording *which* suite it passed
8
+ (pinned by a `suite_digest`) and the pass/fail counts. Anyone holding the
9
+ runtime's `did:key` can re-verify the badge **offline** — no service, no vendor,
10
+ no trust-me. This package owns exactly that envelope: building it, signing it,
11
+ pinning it, and verifying it. It does **not** define your protocol's tests — you
12
+ bring those.
13
+
14
+ ## What this package secures (v0.1)
15
+
16
+ - **Offline-verifiable attestation.** A badge is an Ed25519 signature over an
17
+ RFC 8785 (JCS) canonical JSON payload, with the signed value space constrained
18
+ to ASCII strings, integers, booleans, and null so two implementations cannot
19
+ diverge; verification needs only the embedded `did:key` and `cryptography` — no
20
+ network, no proprietary service.
21
+ - **Load-bearing structure.** `verify_envelope` validates the payload against the
22
+ JSON Schema *on the verify path* — a malformed-but-signed badge is rejected, not
23
+ merely flagged in a test.
24
+ - **Corpus pinning.** `suite_digest` is a SHA-256 over the vector corpus, so a
25
+ badge proves *which* suite ran; swapping in a weaker corpus changes the digest.
26
+ - **Honest gating.** The verifier refuses a badge that records `failed > 0` or a
27
+ non-zero exit status unless you explicitly opt into signature-only mode.
28
+ - **Adversarially tested.** Tampered payloads, tampered signatures, wrong signer,
29
+ non-`did:key` signer, missing fields, and pass-gate evasion are all covered by
30
+ golden vectors and unit tests (74 tests).
31
+
32
+ ## What this package does NOT do
33
+
34
+ - **Run your tests.** It attests *the result* of a suite; wiring a suite (and the
35
+ adapter that plugs a runtime in) is the consumer's responsibility — see the
36
+ reference example.
37
+ - **Prove a self-signed run happened.** A rung-1 badge is a *claim* by the key
38
+ holder; its `total_vectors` is self-attested and catches only an honest partial
39
+ run. Closing under-execution against an adversarial signer is what
40
+ `--expected-total-vectors` (a count the verifier knows independently) and rung-2
41
+ lab counter-signing are for — both shipped, see [`SPEC.md`](./SPEC.md) §9, §11.
42
+
43
+ ## Features
44
+
45
+ - `sign_envelope` / `verify_envelope` — build and check a signed badge.
46
+ - `build_badge(runtime, …)` — turnkey generator: assemble + sign a badge from a
47
+ test run's counts, the skipped-vector IDs, and run provenance.
48
+ - `compute_suite_digest(path)` — pin a badge to a vector corpus (cross-platform stable).
49
+ - `derive_did_key` / `parse_did_key` — W3C `did:key` (base58btc, multicodec `0xed01`).
50
+ - `run_extensions(surface, target, build=…)` — namespaced run provenance incl. build.
51
+ - `sm-verify-badge` CLI with admission gates: `--expected-suite-digest`,
52
+ `--expected-total-vectors`, `--max-skipped` / `--forbid-skip` / `--require-skip-ids`,
53
+ `--expected-build`, `--max-age-days`, `--require-countersigned` (see SPEC §9.1).
54
+ - JSON Schemas for the envelope + counter-signed envelope (`sm_conformance/schema/`),
55
+ enforced on the verify path.
56
+
57
+ ## Where the badge lives
58
+
59
+ On disk a runtime ships its badge at `.nanda/conformance.json`. A runtime that
60
+ serves it over HTTP **should** do so at the canonical URL **`/.well-known/conformance.json`**
61
+ — unauthenticated (it's verifiable offline by anyone against the embedded `did:key`)
62
+ — and advertise that URL from its discovery doc (a `conformance` field in
63
+ `/.well-known/nanda-agent.json`). See [`SPEC.md`](./SPEC.md) §3.2.
64
+
65
+ ## Installation
66
+
67
+ ```bash
68
+ pip install sm-conformance
69
+ # working draft: pip install git+https://github.com/Sharathvc23/sm-conformance.git
70
+ ```
71
+
72
+ ## Quick start
73
+
74
+ ```python
75
+ from sm_conformance import sign_envelope, verify_envelope, compute_suite_digest
76
+
77
+ payload = {
78
+ "schema_version": 1,
79
+ "runtime": "my-runtime",
80
+ "protocol_versions": ["0.1"],
81
+ "suite_digest": compute_suite_digest("vectors"), # SHA-256 over your corpus
82
+ "completed_at": "2026-05-31T00:00:00+00:00",
83
+ "exit_status": 0,
84
+ "passed": 42, "failed": 0, "skipped": 0, "xfailed": 0, "xpassed": 0,
85
+ }
86
+
87
+ seed = bytes(range(32)) # your runtime's Ed25519 seed (32 bytes)
88
+ badge = sign_envelope(payload, seed, "2026-05-31T00:00:00+00:00")
89
+
90
+ verify_envelope(badge) # raises VerificationError if invalid
91
+ ```
92
+
93
+ ```bash
94
+ sm-verify-badge badge.json --expected-suite-digest sha256:<hex>
95
+ ```
96
+
97
+ ## Reference fixtures
98
+
99
+ `tests/fixtures/` holds the golden badge vectors — one positive
100
+ (`valid-signed-badge`) and six negative (`tampered-payload`, `tampered-signature`,
101
+ `wrong-signer`, `non-didkey-signer`, `missing-signature`, `failing-run`), each
102
+ self-declaring its expected verification outcome. They are deterministic
103
+ (regenerate with `python -m sm_conformance._badge_vector_gen`). The keys are
104
+ fixed test seeds, not production signers.
105
+
106
+ ## Specification
107
+
108
+ - [`SPEC.md`](./SPEC.md) — normative envelope, canonical encoding, signing,
109
+ suite-digest, verification algorithm, and trust ladder. Working draft.
110
+ - [`WHITEPAPER.md`](./WHITEPAPER.md) — why mechanical conformance matters for an
111
+ internet of independently-built agents.
112
+
113
+ ## Related packages
114
+
115
+ | Package | Role |
116
+ | --- | --- |
117
+ | [`sm-attest-viewer`](https://github.com/Sharathvc23/sm-attest-viewer) | Renderer for attested agent action-envelope chains |
118
+ | [`sm-decision-inspector`](https://github.com/Sharathvc23/sm-decision-inspector) | Human-in-the-loop decision workbench |
119
+ | [`sm-locp`](https://github.com/Sharathvc23/sm-locp) | Open compliance protocol (defeasible logic + W3C VCs) |
120
+
121
+ ## License
122
+
123
+ [MIT](./LICENSE)
124
+
125
+ ---
126
+
127
+ *First published: 2026-05-31 | Last modified: 2026-05-31*
128
+
129
+ *Personal research contributions aligned with [Project NANDA](https://projectnanda.org) standards. [Stellarminds.ai](https://stellarminds.ai)*