Metadata-Version: 2.4
Name: ecz-id-api
Version: 0.1.0
Summary: Inspects API projects for ECZ-ID configuration and explains public evidence posture.
Project-URL: Documentation, https://developers.ecocitizenz.com
Project-URL: Machine Interface, https://machine.ecocitizenz.org/.well-known/ecz-machine.json
Project-URL: Resolver, https://resolver.ecocitizenz.org
Project-URL: Operator Setup, https://trustops.ecocitizenz.com/start
Project-URL: Developer Guidance, https://developers.ecocitizenz.com
Author-email: Ecocitizenz <ecocitizenz@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: ecz-id
Provides-Extra: toml
Requires-Dist: tomli>=2; (python_version < '3.11') and extra == 'toml'
Provides-Extra: yaml
Requires-Dist: pyyaml<7,>=6; extra == 'yaml'
Description-Content-Type: text/markdown

# 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

```console
$ 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

```python
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

```console
$ 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:

```console
$ 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).

```console
$ 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` &nbsp;|&nbsp; Import: `ecz_id_api` &nbsp;|&nbsp; Plugin group: `ecz_id.plugins`
