overturo-sdk 2.0.0__tar.gz

overturo_sdk-2.0.0/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+# Release workflow for overturo-sdk. Runs on this repository's version
+# tag, builds the package from this tree and publishes it with the registry's
+# short-lived trusted-publisher credential. No token is stored anywhere.
+#
+# First version: until the repository variable OVERTURO_PUBLISH is set, the
+# workflow builds and keeps the artefact without publishing (a trusted publisher
+# on npm can only be named for a package that already exists; a maintainer
+# publishes the first version from a session, names the publisher, then sets
+# the variable). A version the registry already serves is left alone, so a
+# re-run is never red. This workflow never commits, tags or pushes.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+      - name: Version from the tag
+        id: v
+        run: echo "version=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_OUTPUT"
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build
+      - run: python -m build
+      - uses: actions/upload-artifact@v6
+        with:
+          name: package
+          path: dist/
+      - name: First version — not published by this run
+        if: vars.OVERTURO_PUBLISH == ''
+        run: echo "::notice::OVERTURO_PUBLISH is not set on this repository; the build is kept as a run artefact."
+      - name: Publish
+        if: vars.OVERTURO_PUBLISH != ''
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

overturo_sdk-2.0.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

overturo_sdk-2.0.0/CHANGELOG.md

@@ -0,0 +1,110 @@
+# CHANGELOG
+
+## 2.0.0 (2026-10-26)
+### Changed — public names, before the first registry publish
+- The audit-record pointer is `record_id` everywhere (`OverturoDecision.record_id`, the receipt claim, the audit-trail entries); `chronicle_id` is gone from the wire and the models — nothing is dual-emitted.
+- `overturo.oversight` takes `application_id` (was `touchpoint_id`) and sends it on the attestation, escalation and revocation requests.
+- `OverturoRecordStream` (module `overturo.authorize.record_stream`) replaces `OverturoChronicleStream`.
+### Changed
+- Vendored corpus refreshed: `Oap_Authorize_create` (allow and `.escalate`) and `Oap_EscalationSettlements_show` (pending and `.approved`) join; the OAP recordings carry `record_id`.
+
+## 1.2.0 (2026-10-15)
+### Added
+- `overturo.consent_records` — consents captured outside Overturo's surfaces (API token): `create_record` (capture and commit in one call, idempotent on your key), `commit_capture` (commit the capture token your own form received), `retrieve_record`, `import_records` (consents you already hold, up to 5000 rows per batch, with a dry run), `retrieve_import` and `status` (the per-purpose status for a subject, by email or your own identifier), each with an `_async` twin except `commit_capture`. Tests run against the recorded corpus.
+### Changed
+- Vendored corpus refreshed to the shared corpus 1.0.5 and the signed-record fixtures regenerated against schema `overturo-cr/2.12`; published keys unchanged.
+
+## 1.1.0 (2026-10-10)
+### Added
+- `overturo.meetings` — the organisation's side of meeting consent (API token): `list_meetings`, `create_meeting`, `retrieve_meeting`, `update_meeting` (rename / reschedule), `cancel_meeting`, `list_participants` (each person's decision per purpose), each with an `_async` twin. A meeting is the unit of record: window, platform identity, cancellation, participant rows. Tests run against the recorded corpus; the module joins the strict mypy surface.
+
+## 1.0.3 (2026-10-09)
+### Changed
+- Vendored discovery corpus refreshed to the shared corpus 1.0.3: the canonical flow's `care_reminders` purpose now runs on legitimate interest with the opt-out (right to object) mechanism, and its choices step is titled "Your Choices"; the discovery test follows. Tests only — the published package is unchanged.
+
+## 1.0.2 (2026-10-09)
+### Changed
+- Vendored signed-record corpus refreshed to the shared corpus 1.0.2: a new `consent_record_escaped_text` case (receipt text containing `<`, `>`, `&` and U+2028), regenerated record identifiers and the `overturo-cr/2.9` schema label; published keys unchanged. Tests only — the published package is unchanged.
+
+## 1.0.1 (2026-09-12)
+
+### Changed
+
+- The README links the public documentation and the rendered API reference at overturo.com/developers; the vendored API response corpus is re-recorded against the published document, whose operations now list the SDKs that reach them (`x-overturo-sdks`).
+
+## 1.0.0 (unreleased)
+
+Initial release. Consolidates `overturo-authorize` v1.2.0 and
+`overturo-oversight` v0.2.0 into a single package.
+
+### Changed
+
+- Source comments, tests, the example adapter and this changelog describe behaviour only; planning references were removed.
+- The test suite is self-contained: the signed-record corpus and the discovery fixture are vendored under `tests/fixtures/` (the shared copies are read when the package sits next to them).
+
+### Fixed — decision envelopes (found by the recorded API corpus)
+
+- `DecisionToken.from_response` / `DecisionStatus.from_response` read the
+  envelope the API actually sends: the token and the one-shot status arrive
+  wrapped under `decision`, the validity bound is `deadline_at`, and a pending
+  long-poll envelope carries no `session_token`. The previous parser raised
+  `KeyError` on every real response.
+- The test suite stubs recorded operations from the shared API response corpus
+  (`tests/corpus.py`; vendored under `tests/fixtures/api_responses`); the discovery
+  test reads a vendored copy of the shared discovery fixture when the shared corpus
+  is not present.
+
+### Added — pre-flight disclosure discovery
+
+- **`overturo.decisions.discover(base_url, *, flow_id, publishable_key,
+  locale=None)`** — fetch what a consent flow would ask a person (purposes,
+  fields, steps, the action label, expiry, application branding) BEFORE any
+  session exists, in public vocabulary and the requested locale. The publishable
+  key is an embed-safe, per-application credential passed explicitly (this
+  endpoint ignores any bearer token). Sync, standalone (takes `base_url`, not a
+  client). An unknown / foreign / non-consent flow raises `OverturoApiError`
+  (`http_status=404`). Returns the `FlowDisclosures` TypedDict.
+- Cross-language parity is gated by the shared corpus at
+  `lib/sdk/shared/conformance/discovery/flow_disclosures.json`.
+
+### Added — authority records
+
+- **`overturo.records`** — `verify_record` (durable signed-record
+  verification: overturo-jcs-1 canonical bytes, a detached signature,
+  published-key resolution by key_version, opt-in embedded-key mode),
+  `verify_manifest_pin` / `manifest_content_hash` (the
+  capability-manifest pin), and the `RecordInvalid` typed error.
+  Cross-language parity is gated by the shared corpus at
+  `lib/sdk/shared/conformance/signed_records/`.
+- **`overturo.receipts`** — `retrieve_authorization_receipt` (the
+  durable record, `audit:verify` scope; canonical/signed/dpv flavors)
+  and `create_disclosure_receipt` (the operator-declared disclosure
+  mint, `disclosures:write` scope). Typed refusals raise
+  `OverturoValidationError` with the machine code in `reason_code`.
+
+### Added — cross-border
+
+- **`authorize(..., jurisdiction=...)`** — declare the action's target
+  jurisdiction (an ISO country) so the platform can enforce a jurisdiction
+  bound; mapped into the authorize context. A refusal arrives with
+  `failed_bound == "jurisdiction_bounds"` (reason code
+  `jurisdiction_not_permitted`), distinct from a transport-level refusal.
+- **Cross-border credential verification** in `verify` — resolve a presented
+  credential against its issuer's own published key (shares the
+  `@overturo/verify` resolution; see that SDK's notes).
+
+### Replaces
+
+- `overturo-authorize` v1.2.0 → `overturo.authorize`
+- `overturo-oversight` v0.2.0 → `overturo.oversight`
+
+### Added
+
+- `overturo.models` — single home for cross-cutting dataclasses (the earlier
+  vendored `_shared.py` is gone).
+- `overturo.errors.OverturoError` is now the unified root for both the
+  protocol (`OapError`) and transport (`OverturoApiError`, etc.) families.
+- `overturo.decisions` promoted from `overturo_oversight.decisions` to
+  a top-level subpackage.
+- `@experimental` decorator marks pre-1.0 oversight surfaces
+  (`heartbeat`, `iss_role`, `sequence`).

overturo_sdk-2.0.0/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include
+the brackets!)  The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+Copyright 2026 Overturo Geneva Association
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

overturo_sdk-2.0.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: overturo-sdk
+Version: 2.0.0
+Summary: Overturo SDK — authorize, oversight, and decisions for backend integrators
+Project-URL: Homepage, https://overturo.com/developers/docs
+Project-URL: Repository, https://github.com/overturo/sdk-python
+Project-URL: Issues, https://github.com/overturo/sdk-python/issues
+Author-email: Overturo <sdk@overturo.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agent,agent-authorization,ai-agent,attestation,consent,decisions,oap,oversight,overturo
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.27
+Provides-Extra: lint
+Requires-Dist: mypy>=1.10; extra == 'lint'
+Requires-Dist: ruff>=0.6; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: respx>=0.21; extra == 'test'
+Description-Content-Type: text/markdown
+
+> **Release mirror.** This repository is a read-only snapshot of
+> `overturo-sdk` 2.0.0, published from Overturo's main
+> development repository. Issues and pull requests are welcome here; accepted
+> changes are ported upstream and appear in the next release snapshot.
+> Security reports: see [SECURITY.md](./SECURITY.md).
+
+# overturo-sdk
+
+**Documentation:** <https://overturo.com/developers/docs> · **Agent authorization:** <https://overturo.com/developers/agent-authorization> · **API reference:** <https://overturo.com/developers/openapi>
+
+Python SDK for [Overturo](https://overturo.com) — the trust conductor.
+
+## Install
+
+    pip install overturo-sdk
+
+The distribution is `overturo-sdk`; the import is `overturo`.
+
+## Quickstart
+
+    from overturo import OverturoAuthorize, OverturoOversight
+    from overturo import decisions
+    from overturo.errors import OapError, OapApprovalRequired, OverturoError
+
+Subpackages:
+
+- `overturo.authorize` — Relying-party SDK (OAP v1.0 authorize + verify)
+- `overturo.oversight` — Issuer / attester SDK (Oversight Mode)
+- `overturo.decisions` — Needs-approval URL minting + long-poll subscription
+- `overturo.receipts` — Authority record client methods (durable Authorization Receipts + disclosure mint)
+- `overturo.consent_records` — Consent records captured outside Overturo's surfaces (create, commit a capture, read, import, status)
+
+## Authority records
+
+The durable **Authorization Receipt** is a different artifact from the short-lived runtime receipt `authorize()` returns — the runtime receipt's TTL bounds *honoring*, not evidence, while the durable record is the archival, offline-verifiable account of the authorization.
+
+    from overturo import verify_record
+    from overturo.receipts import retrieve_authorization_receipt, create_disclosure_receipt
+
+    # The durable record (audit:verify scope). Flavors: canonical (default), signed, dpv.
+    envelope = retrieve_authorization_receipt(
+        base_url="https://overturo.us", api_token=token, record_id="acc_...", flavor="signed"
+    )
+
+    # Verify offline against the region's published keys (key_version -> base64 key,
+    # e.g. reshaped from the region's key-discovery document).
+    verified = verify_record(envelope, published_keys=published_keys)
+
+    # Mint an operator-declared disclosure receipt (disclosures:write scope).
+    minted = create_disclosure_receipt(
+        base_url="https://overturo.us", api_token=token,
+        flow_id="acc_...", agent_id="agt_...", disclosed_at="2026-08-06T10:00:00Z",
+    )
+
+Typed refusals raise `OverturoValidationError` carrying the machine code in `reason_code` (`unknown_flavor`, `not_signable`, `dpv_unavailable`; `agent_not_disclosed`, `invalid_disclosed_at`, `purposes_missing`). The 404 contract is parity-preserving: unknown, foreign, and non-authority ids are indistinguishable. An authorization-kind record is refused by the consent-receipts read with a typed hint — authority records are served only by these endpoints. Field semantics and verification: the Receipt Interop & Verification guide in the developer documentation.
+
+## Consent records
+
+Consents captured outside Overturo's surfaces — in your own form, or already held in your systems — become records with the same receipt, status and evidence as a decision taken on an Overturo surface.
+
+    from overturo import consent_records
+
+    # Capture and commit in one call — idempotent on your key.
+    envelope = consent_records.create_record(
+        base_url="https://overturo.us", api_token=token,
+        flow_id="flw_...", subject={"email": "ana@example.com", "external_id": "crm-1842"},
+        decisions={"marketing_email": {"decision": "granted"}, "analytics": {"decision": "declined"}},
+        idempotency_key="signup-1842",
+    )
+
+    # Commit the capture token your own form received (the form-capture path of @overturo/js).
+    decision = consent_records.commit_capture(
+        base_url="https://overturo.us", api_token=token, token=capture_token, subject={"email": "ana@example.com"},
+    )
+
+    # Import consents you already hold — up to 5000 rows per batch; dry_run reports without writing.
+    batch = consent_records.import_records(
+        base_url="https://overturo.us", api_token=token, flow_id="flw_...", records=rows, dry_run=True,
+    )
+    progress = consent_records.retrieve_import(
+        base_url="https://overturo.us", api_token=token, import_id=batch["import"]["id"]
+    )
+
+    # The per-purpose status for a subject, by email or your own identifier.
+    status = consent_records.status(
+        base_url="https://overturo.us", api_token=token, application_id="app_...", email="ana@example.com"
+    )
+
+Every read and write except `commit_capture` has an `_async` twin.
+
+## Contract and testing
+
+This client is written against Overturo's published OpenAPI document, kept at
+<https://github.com/overturo/openapi> and rendered at
+<https://overturo.com/developers/openapi>, where each operation lists the SDKs that reach it. When the client and the API disagree, the
+document is the authority; a change to it is a change to this client.
+
+The test suite stubs recorded operations from the shared API response corpus
+(<https://github.com/overturo/conformance>, `api_responses/`), vendored under
+`tests/fixtures/api_responses`. Each recording was made against the real API and checked against
+the published document before it was committed, so a passing suite means the
+client parses what the API actually sends — not what a test author remembered.
+Identifiers, timestamps and tokens in the recordings are placeholders
+(`<PREFIX_ID:1>`, `2026-01-01T00:00:00Z`, `<TOKEN>`); the corpus README documents the
+grammar.
+
+Run the suite with `pytest`. When you add a test for a recorded operation, stub it
+from the recording (`corpus_route(router, "Decisions_create", BASE)`) rather than writing the response by hand.
+
+## License
+
+Apache-2.0

overturo_sdk-2.0.0/README.md

@@ -0,0 +1,112 @@
+> **Release mirror.** This repository is a read-only snapshot of
+> `overturo-sdk` 2.0.0, published from Overturo's main
+> development repository. Issues and pull requests are welcome here; accepted
+> changes are ported upstream and appear in the next release snapshot.
+> Security reports: see [SECURITY.md](./SECURITY.md).
+
+# overturo-sdk
+
+**Documentation:** <https://overturo.com/developers/docs> · **Agent authorization:** <https://overturo.com/developers/agent-authorization> · **API reference:** <https://overturo.com/developers/openapi>
+
+Python SDK for [Overturo](https://overturo.com) — the trust conductor.
+
+## Install
+
+    pip install overturo-sdk
+
+The distribution is `overturo-sdk`; the import is `overturo`.
+
+## Quickstart
+
+    from overturo import OverturoAuthorize, OverturoOversight
+    from overturo import decisions
+    from overturo.errors import OapError, OapApprovalRequired, OverturoError
+
+Subpackages:
+
+- `overturo.authorize` — Relying-party SDK (OAP v1.0 authorize + verify)
+- `overturo.oversight` — Issuer / attester SDK (Oversight Mode)
+- `overturo.decisions` — Needs-approval URL minting + long-poll subscription
+- `overturo.receipts` — Authority record client methods (durable Authorization Receipts + disclosure mint)
+- `overturo.consent_records` — Consent records captured outside Overturo's surfaces (create, commit a capture, read, import, status)
+
+## Authority records
+
+The durable **Authorization Receipt** is a different artifact from the short-lived runtime receipt `authorize()` returns — the runtime receipt's TTL bounds *honoring*, not evidence, while the durable record is the archival, offline-verifiable account of the authorization.
+
+    from overturo import verify_record
+    from overturo.receipts import retrieve_authorization_receipt, create_disclosure_receipt
+
+    # The durable record (audit:verify scope). Flavors: canonical (default), signed, dpv.
+    envelope = retrieve_authorization_receipt(
+        base_url="https://overturo.us", api_token=token, record_id="acc_...", flavor="signed"
+    )
+
+    # Verify offline against the region's published keys (key_version -> base64 key,
+    # e.g. reshaped from the region's key-discovery document).
+    verified = verify_record(envelope, published_keys=published_keys)
+
+    # Mint an operator-declared disclosure receipt (disclosures:write scope).
+    minted = create_disclosure_receipt(
+        base_url="https://overturo.us", api_token=token,
+        flow_id="acc_...", agent_id="agt_...", disclosed_at="2026-08-06T10:00:00Z",
+    )
+
+Typed refusals raise `OverturoValidationError` carrying the machine code in `reason_code` (`unknown_flavor`, `not_signable`, `dpv_unavailable`; `agent_not_disclosed`, `invalid_disclosed_at`, `purposes_missing`). The 404 contract is parity-preserving: unknown, foreign, and non-authority ids are indistinguishable. An authorization-kind record is refused by the consent-receipts read with a typed hint — authority records are served only by these endpoints. Field semantics and verification: the Receipt Interop & Verification guide in the developer documentation.
+
+## Consent records
+
+Consents captured outside Overturo's surfaces — in your own form, or already held in your systems — become records with the same receipt, status and evidence as a decision taken on an Overturo surface.
+
+    from overturo import consent_records
+
+    # Capture and commit in one call — idempotent on your key.
+    envelope = consent_records.create_record(
+        base_url="https://overturo.us", api_token=token,
+        flow_id="flw_...", subject={"email": "ana@example.com", "external_id": "crm-1842"},
+        decisions={"marketing_email": {"decision": "granted"}, "analytics": {"decision": "declined"}},
+        idempotency_key="signup-1842",
+    )
+
+    # Commit the capture token your own form received (the form-capture path of @overturo/js).
+    decision = consent_records.commit_capture(
+        base_url="https://overturo.us", api_token=token, token=capture_token, subject={"email": "ana@example.com"},
+    )
+
+    # Import consents you already hold — up to 5000 rows per batch; dry_run reports without writing.
+    batch = consent_records.import_records(
+        base_url="https://overturo.us", api_token=token, flow_id="flw_...", records=rows, dry_run=True,
+    )
+    progress = consent_records.retrieve_import(
+        base_url="https://overturo.us", api_token=token, import_id=batch["import"]["id"]
+    )
+
+    # The per-purpose status for a subject, by email or your own identifier.
+    status = consent_records.status(
+        base_url="https://overturo.us", api_token=token, application_id="app_...", email="ana@example.com"
+    )
+
+Every read and write except `commit_capture` has an `_async` twin.
+
+## Contract and testing
+
+This client is written against Overturo's published OpenAPI document, kept at
+<https://github.com/overturo/openapi> and rendered at
+<https://overturo.com/developers/openapi>, where each operation lists the SDKs that reach it. When the client and the API disagree, the
+document is the authority; a change to it is a change to this client.
+
+The test suite stubs recorded operations from the shared API response corpus
+(<https://github.com/overturo/conformance>, `api_responses/`), vendored under
+`tests/fixtures/api_responses`. Each recording was made against the real API and checked against
+the published document before it was committed, so a passing suite means the
+client parses what the API actually sends — not what a test author remembered.
+Identifiers, timestamps and tokens in the recordings are placeholders
+(`<PREFIX_ID:1>`, `2026-01-01T00:00:00Z`, `<TOKEN>`); the corpus README documents the
+grammar.
+
+Run the suite with `pytest`. When you add a test for a recorded operation, stub it
+from the recording (`corpus_route(router, "Decisions_create", BASE)`) rather than writing the response by hand.
+
+## License
+
+Apache-2.0

overturo_sdk-2.0.0/SECURITY.md

@@ -0,0 +1,14 @@
+# Security policy
+
+## Supported version
+
+The latest release snapshot in this repository (2.0.0) is supported.
+Older snapshots receive no fixes; upgrade to the latest release.
+
+## Reporting a vulnerability
+
+Email **security@overturo.com**. Do not open a public issue for a security
+report. You will receive an acknowledgement within two working days and a
+resolution plan once the report is confirmed.
+
+Issues that are not security-sensitive go to https://github.com/overturo/sdk-python/issues.