Metadata-Version: 2.4
Name: polaris-sdk-python
Version: 1.0.0rc6
Summary: Python SDK for verifying Polaris ID credentials: offline authenticity and online status. A library; the command-line verifier is the separate polaris-verify package.
Author: Egor Khaklin
License: Apache-2.0
Project-URL: Homepage, https://github.com/EgorKhaklin/polaris-id
Project-URL: Documentation, https://github.com/EgorKhaklin/polaris-id/tree/main/sdk/python#readme
Project-URL: Changelog, https://github.com/EgorKhaklin/polaris-id/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/EgorKhaklin/polaris-id/issues
Project-URL: Source, https://github.com/EgorKhaklin/polaris-id/tree/main/sdk/python
Project-URL: Conformance, https://github.com/EgorKhaklin/polaris-id/tree/main/conformance
Keywords: identity,credential,verifier,ml-dsa,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: cryptography>=48
Dynamic: license-file

# polaris-sdk-python

A server-side SDK for a relying party to verify Polaris identity credentials. It
answers one narrow question about a credential a holder presented: is it authentic,
and is it authoritative right now? It never returns a person's data.

> **Naming:** this project installs the module `polaris_verify` (the library). The command-line
> verifier is the separate project `polaris-verify` (module `polaris_verify_cli`).

- **Authenticity** (offline, cacheable): the ML-DSA-65 signature over
  `SHA3-256(token_value)`, verified with `cryptography` (and liboqs as a second
  witness when present), optionally against trusted issuer anchor keys.
- **Authorization** (online, fresh): the issuer's `POST /api/v1/verify`,
  authenticating as a registered organization with OAuth2 client-credentials.

`accept` requires both; without a reachable issuer the verdict is `provisional`.
Self-contained: only `cryptography` plus the standard library.

```python
from polaris_verify import PolarisVerifier

v = PolarisVerifier(
    issuer_url="https://issuer.example",
    client_id="rp_...", client_secret="...",         # from `polaris rp-register`
    anchors=["<issuer public key hex>"],             # optional trust anchors
)
verdict = v.verify_presentation(presentation)        # a wallet presentation, or a bare pack
print(verdict.decision)                              # "accept" | "reject" | "provisional"
```

Offline only (no `issuer_url`) yields a `provisional` verdict from authenticity
alone. `verify_authenticity(pack, anchors)` exposes the offline check directly.

A first run needs no issuer and no credential of your own: the repository publishes test
vectors.

```bash
base=https://raw.githubusercontent.com/EgorKhaklin/polaris-id/main/vectors
curl -sO $base/ml-dsa-65-valid.json && curl -sO $base/ml-dsa-65-tampered-signature.json
python3 -c "
import json
from polaris_verify import verify_authenticity
for f in ('ml-dsa-65-valid.json', 'ml-dsa-65-tampered-signature.json'):
    print(f, verify_authenticity(json.load(open(f)), None).authentic)"
```

The first prints `True`, the second `False`. Walked on 2026-09-23 from a clean virtualenv
against the package on PyPI.

## What it verifies

Everything below is offline and self-contained. Signatures are accepted under two FIPS 204
parameter sets, ML-DSA-65 (the default) and ML-DSA-87; ML-DSA-44 and any other value are
refused (wire spec section 6).

- `verify_authenticity(pack, anchors)`: the authenticity pack.
- `verify_status_assertion(assertion, now)`: the short-lived signed status assertion.
- `verify_presentation(presentation, ...)`: a wallet presentation, or a bare pack.
- `verify_signed_artifact(obj, now)`: every other signed artifact of the wire spec: the epoch
  checkpoint, revocation feed, federation manifest, status bundle, transparency STH,
  timestamp, registry, exchange request, exchange receipt, mint statement, signed document,
  ID token and trust list (authenticity, freshness where windowed, and the artifact's
  commitment or self-consistency).
- `verify_cross_authority(...)`: the federation trust decision (accept / reject) under the relying party's trust anchors; with none, no manifest is trusted.
- `verify_exchange_request(...)`, `verify_exchange_receipt(...)`, `verify_exchange_mint(...)`: an
  exchange artifact in use: whether it is by the party expected, whether the requester was
  attested in its context at a stated instant (and by whom, for a receipt), and whether the
  bodies held match the commitments.

The SDK passes every case of the conformance suite (219 cases, measured against the repository on 2026-09-30) and every case of the frozen
version-1 set under `scripts/polaris-compat-suite.py`, which runs on every CI push.

## Conformance

This SDK is the reference implementation of the Polaris verification **conformance
suite** (`../../conformance/`). `python -m polaris_verify.conformance` implements the
language-agnostic verifier CLI the suite drives; passing the suite is the integration
contract. See [`conformance/SPEC.md`](https://github.com/EgorKhaklin/polaris-id/blob/main/conformance/SPEC.md).
