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.
- sm_conformance-0.3.1/.gitattributes +5 -0
- sm_conformance-0.3.1/.github/CODEOWNERS +1 -0
- sm_conformance-0.3.1/.github/workflows/ci.yml +22 -0
- sm_conformance-0.3.1/.github/workflows/release.yml +44 -0
- sm_conformance-0.3.1/.gitignore +20 -0
- sm_conformance-0.3.1/CHANGELOG.md +93 -0
- sm_conformance-0.3.1/GOVERNANCE.md +34 -0
- sm_conformance-0.3.1/LICENSE +21 -0
- sm_conformance-0.3.1/PKG-INFO +154 -0
- sm_conformance-0.3.1/PUBLISHING.md +40 -0
- sm_conformance-0.3.1/README.md +129 -0
- sm_conformance-0.3.1/SPEC.md +309 -0
- sm_conformance-0.3.1/WHITEPAPER.md +166 -0
- sm_conformance-0.3.1/examples/demo.py +61 -0
- sm_conformance-0.3.1/pyproject.toml +69 -0
- sm_conformance-0.3.1/sm_conformance/__init__.py +57 -0
- sm_conformance-0.3.1/sm_conformance/_badge_vector_gen.py +252 -0
- sm_conformance-0.3.1/sm_conformance/badge.py +390 -0
- sm_conformance-0.3.1/sm_conformance/countersign.py +149 -0
- sm_conformance-0.3.1/sm_conformance/py.typed +0 -0
- sm_conformance-0.3.1/sm_conformance/schema/common.schema.json +31 -0
- sm_conformance-0.3.1/sm_conformance/schema/conformance-envelope.schema.json +99 -0
- sm_conformance-0.3.1/sm_conformance/schema/counter-signed-envelope.schema.json +41 -0
- sm_conformance-0.3.1/sm_conformance/vectors/canonicalization.json +91 -0
- sm_conformance-0.3.1/sm_conformance/verify_badge.py +321 -0
- sm_conformance-0.3.1/tests/fixtures/failing-run.json +33 -0
- sm_conformance-0.3.1/tests/fixtures/missing-signature.json +32 -0
- sm_conformance-0.3.1/tests/fixtures/non-didkey-signer.json +33 -0
- sm_conformance-0.3.1/tests/fixtures/tampered-payload.json +33 -0
- sm_conformance-0.3.1/tests/fixtures/tampered-signature.json +33 -0
- sm_conformance-0.3.1/tests/fixtures/valid-signed-badge.json +33 -0
- sm_conformance-0.3.1/tests/fixtures/wrong-signer.json +34 -0
- sm_conformance-0.3.1/tests/test_badge.py +370 -0
- sm_conformance-0.3.1/tests/test_badge_vectors.py +151 -0
- sm_conformance-0.3.1/tests/test_canonicalization_vectors.py +35 -0
- sm_conformance-0.3.1/tests/test_countersign.py +168 -0
- sm_conformance-0.3.1/tests/test_hardening.py +301 -0
|
@@ -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)*
|