ecz-id-api 0.1.0

Inspects API projects for ECZ-ID configuration and explains public evidence posture.

ECZ-ID API Inspection

ecz-id-api inspects API projects for ECZ-ID configuration posture and, optionally, checks read-only public proof on the Resolver. It is part of the ECZ-ID PyPI family. It inspects, explains and routes only.

It never issues or activates an ECZ-ID, never determines BOUND, never calculates carts or prices, never creates proof, and never executes discovered project, agent, MCP or robot code. It is not a safety, certification, approval, compliance, insurance or premium decision, and it is not an API security, vulnerability, availability or correctness assessment. Missing public proof is neutral: it does not mean unsafe. Local policy decides. Re-check before reliance.

One-command first run

$ ecz-id-api inspect ./my-api-project
ECZ-ID inspection: ./my-api-project [ecz-id-api]
A. configuration posture : PRESENT
B. public proof posture  : NOT_CHECKED  (neutral)
means        : Local ECZ-ID configuration was found for this subject. | Public Resolver proof was not checked.
does not mean: This is not an API security, vulnerability, availability or correctness assessment. | This result is not a safety, certification, approval, compliance, insurance or premium decision. | Missing public proof is neutral: it does not mean unsafe, non-compliant or untrustworthy.
reason codes : ECZ-1000, ECZ-2002
local policy decides; re-check before reliance

The first result is useful with no account, no network and no configuration. The public check is strictly opt-in (--check-public), so first runs are network-silent.

Supported inputs

• A project directory containing an ECZ-ID API descriptor, or the descriptor file itself.
• Descriptor names: ecz_id_config.json, ecz-id.json, ecz-id.toml, .ecz-id.toml.
• Co-located OpenAPI / Swagger documents (openapi.json, openapi.yaml, openapi.yml, swagger.json) are observed for title, version, servers, contact and external docs — never fetched.

JSON is parsed natively. TOML needs Python 3.11+ or pip install ecz-id-api[toml]; YAML needs pip install ecz-id-api[yaml]. Without them, those formats degrade to a neutral note instead of failing.

Privacy boundaries

• Bounded, read-only enumeration; never follows symlinks or escapes the root.
• No telemetry, no uploads. The optional public check sends a lookup key only, to the validated Resolver host, over HTTPS.
• Secrets are redacted from every export.
• Offline mode (--offline or ECZ_ID_OFFLINE=1) skips all network.

Explicit non-claims

Not a safety / certification / approval / compliance / insurance / premium decision. Not an API security or vulnerability assessment. Does not issue, activate or bind an ECZ-ID. Does not price or cart.

Python API

from ecz_id_api import inspect

result = inspect("./my-api-project", check_public=False)
print(result.configuration_evidence.posture.value)   # PRESENT / PARTIAL / ABSENT / INVALID
print(result.public_evidence.posture.value)           # NOT_CHECKED by default

# Fully offline-testable: inject a fake opener so no real network call happens.
proof = b'{"proof": {"status": "PUBLIC_RECORD_PRESENT"}}'
checked = inspect("./my-api-project", check_public=True, opener=lambda url, t: proof)

CI / test example

$ ecz-id-api inspect . --json > ecz-id-api.json   # exit 0 for any completed inspection
$ ecz-id-api doctor --json                          # environment / parser availability

Exit code is 0 for every completed inspection regardless of posture (neutrality rule); non-zero only for genuine input/tool errors.

Routes

• Resolver (read-only public proof): https://resolver.ecocitizenz.org
• TrustOps (recommendation, setup, lifecycle, repair): https://trustops.ecocitizenz.com/start
• Developer Gateway (docs and routing): https://developers.ecocitizenz.com
• Central Machine Interface (public-safe manifests): https://machine.ecocitizenz.org/.well-known/ecz-machine.json

Setup, payment, lifecycle and repair happen in TrustOps — this package only routes you there.

Re-check

Posture and public proof can change at any time. Re-run before reliance:

$ ecz-id-api recheck ./my-api-project --json

Machine Interface & Quiet manifest

Machine Interface · Manifest · Resolve · Operator Setup · Developer Guidance

Every install ships a public-safe ecz_quiet_machine_interface.json, and every JSON report embeds a compact machine_interface object with the canonical roots and safe actions (it exposes the interface and protects the playbook).

$ ecz-id-api manifest --json
$ ecz-id-api compare ./old ./new --json    # neutral drift
$ ecz-id-api inspect . --sarif             # SARIF for code scanning
$ uvx ecz-id-api inspect .                 # or: pipx run ecz-id-api inspect .

• Central Machine Interface: https://machine.ecocitizenz.org/.well-known/ecz-machine.json
• Resolver (read-only public proof): https://resolver.ecocitizenz.org
• Operator setup (TrustOps): https://trustops.ecocitizenz.com/start
• Developer Gateway: https://developers.ecocitizenz.com

Licence and trademarks

Apache-2.0 (see LICENSE, NOTICE). The code licence grants no trademark rights; “ECZ-ID” and “EcoCitizenz” are trademarks of their owner(s) — see TRADEMARKS.md. Changelog: CHANGELOG.md. Security: SECURITY.md.

CLI: ecz-id-api  |  Import: ecz_id_api  |  Plugin group: ecz_id.plugins