osyra_ome.verify

Private pre-release / network boundary: The currently usable customer surface is offline verification of an existing signed artifact against an out-of-band trust anchor. Memory/network RPC APIs and host snippets on this page describe protocol and interface shape; the public Edge bridge, package publication, and release acceptance remain pending. Do not treat api.osyra.ai:443 examples as a released customer route.

Osyra OME — verify sub-namespace.

Apache-2.0 surface (per design §2.5 + ADR-043 β extension). Imports ONLY from ``osyra_ome.verify._kernel`` — NEVER from ``osyra_ome._kernel``, ``osyra_ome.memory``, ``osyra_ome.proof``, ``osyra_ome.witness``, or ``osyra_ome._internal``. This isolation is structurally enforced at PR-gate via ``scripts/verify-no-kernel-imports.py`` (BC-9a + BC-13) AND at runtime via :class:`_VerifyBoundaryFinder` (BC-14).

Layered guards (defense-in-depth per threat model §5.1):

• BC-9a (PR-gate AST scan) catches static ``from`` / ``import`` / importlib.import_module("literal") references.
• BC-13 (PR-gate AST scan, same script) catches structural imports in the verify package source tree.
• BC-14 (this module, runtime) catches dynamic imports that slip past static analysis — e.g. getattr(importlib, 'import_module') (computed_name) or third-party shims that load forbidden modules when invoked from a verify-context call frame.

The BC-14 finder is installed at first import of this package and stays registered for the process lifetime. It is intentionally idempotent: a second registration is a no-op so test harnesses that import-reset the package don't double-register.

Functions

extract_attested_claim_fields

def extract_attested_claim_fields(encoded_cbor: bytes) -> AttestedClaimFields

Extract the attested ``content_hash`` (+ ``embedding_hash``) from a preimage.

Strict-canonical-decodes the Form-B claim signing-preimage bytes (the bytes the Ed25519 signature attests), asserts the claim dsTag, and reads the short-key ``ch`` / ``eh`` byte-string fields from the claim map.

Args: encoded_cbor: The claim signing-preimage bytes (SignedClaim.encoded_cbor; the bytes verify_receipt covers).

Returns: An :class:AttestedClaimFields carrying the authentic 32-byte content_hash and, when present (non-zero), the authentic 32-byte embedding_hash.

Raises: OmeWireFormatError: the bytes are not strict-canonical CBOR, are not a 2-tuple, carry the wrong dsTag (cross-protocol confusion), the payload is not a CBOR map, or ch is absent / not a 32-byte byte string. Fail-CLOSED: there is no path that returns a partial or default result.

verify_body_against_signed_claim

def verify_body_against_signed_claim(body: bytes, encoded_cbor: bytes, signature: bytes, trusted_pub_key: bytes) -> bytes

Bind a read-back ``body`` to the signature-attested content hash.

The single mandatory read-path control for a body-bearing claim. Verifies the signature, extracts the ATTESTED ``ch`` from the SIGNED preimage, and asserts ``SHA-256(body) == ch`` in constant time. On success returns the ``body`` unchanged (so the call site can write ``body = verify_body_...``).

Args: body: The raw claim body bytes returned by the read path (e.g. GetClaimBody). encoded_cbor: The claim signing-preimage bytes (the bytes the signature attests; from the SignedClaim for THIS body's claim). signature: The 64-byte detached Ed25519 signature over encoded_cbor. trusted_pub_key: The caller's trusted 32-byte Ed25519 public key. REQUIRED — a missing / wrong-length key fails closed (the in-band signer_pub is never a trust anchor).

Returns: body unchanged, once it is proven to match the signature-attested content hash.

Raises: OmeVerifyError: trusted_pub_key is missing / not 32 bytes, the signature does not verify over encoded_cbor under the trusted key, or SHA-256(body) does not equal the attested content hash. OmeWireFormatError: encoded_cbor is empty / not strict-canonical / wrong dsTag / missing the attested ch (propagated from :func:extract_attested_claim_fields and :func:verify_receipt).

verify_ocv_composite

def verify_ocv_composite(receipt_bytes: bytes, *, expected_signer_pub: bytes, leaf_signer_pubs: Sequence[bytes] | None = None) -> bool

Verify an OCV-1.0 composite receipt locally (offline, structural + crypto).

Proves the composite is a **well-formed, single-(outer)-signed, tenant-uniform, depth-1, correctly-bound chain** (see the module docstring's HONEST SCOPE for the boundary). It does NOT re-decide the per-kind leaf semantics or burn nonces — those are the L5 Verifier-of-Record's job (AP00016 ``verify_composite.go``).

Args: receipt_bytes: Canonical-CBOR bytes of the OUTER EAT COSE_Sign1 envelope (the composite receipt). expected_signer_pub: The 32-byte Ed25519 public key the caller trusts as the composite verifier-of-record (the OUTER envelope signer). REQUIRED — the SDK fails CLOSED with no implicit trust. leaf_signer_pubs: The rotation-tolerant candidate key set the leaves' COSE_Sign1 signatures are verified against (the first that verifies each leaf wins). V1 composites are tenant-uniform, so the leaves typically share the outer workspace anchor. Defaults to [expected_signer_pub] when omitted (the V1 single-anchor case).

Returns: True on successful verification.

Raises: OmeWireFormatError: the bytes are not well-formed strict-canonical CBOR, the envelope/claim/ocv-body shape is wrong, or a tree / binding-spec is malformed. OmeVerifyError: the outer or a leaf COSE signature does not verify, a tenant/depth/alg invariant is violated, or a committed-digest binding does not hold (anti-splice).

verify_oeraser

def verify_oeraser(oeraser_body: bytes, *, destruction_authority_pubkeys: Sequence[bytes], now: int) -> bool

Re-decide an OERaseR verified-forgetting receipt body, offline and fail-closed.

Re-derives the four legs (erasurePinned ∧ retentionPermits ∧ keyDestroyed ∧ noResurrection) + the erasure_binding terminal weld over the disclosed witnesses in ``oeraser_body``, trusting ONLY the relying-party-pinned key-destruction authority set. Byte-identical to the Go reference (``AP00016``) + Java emitter (``AP00011``) — the frozen ENG-2316 KAT is the cross-language oracle.

Args: oeraser_body: The canonical-CBOR oeraser-body bytes (§4.2.1) — the opaque EAT receipt body. The frozen ENG-2316 KAT unit. destruction_authority_pubkeys: The relying party's PINNED set of 32-byte raw Ed25519 key-destruction-authority public keys (rotation-tolerant — the attestation must verify under ANY one). An EMPTY set fails closed: with no pinned authority, the keyDestroyed leg cannot be satisfied (KEY_NOT_DESTROYED). This is the trust anchor — the DPA pins the authority it trusts, NOT the controller's say-so. now: The attested clock value (unsigned-64-bit seconds) the retention window is evaluated against. Supplied by the relying party; the re-decision NEVER reads a clock of its own, so it is reproducible offline.

Returns: True on a full accept (all four legs + the terminal weld passed). NEVER returns False — every reject raises, so a caller cannot accidentally trust a receipt that did not fully re-decide.

Raises: OmeWireFormatError: the body is not strict-canonical CBOR, or violates the fixed keyasint schema / a field byte-length (OSY-EAT-6308), or now / destruction_authority_pubkeys are the wrong type. OmeVerifyError: a leg or the terminal weld failed — carries the same OSY-EAT-NNNN code the Go re-decider emits (6370 KEY_NOT_DESTROYED, 6371 RETENTION_FORBIDS, 6372 LEGAL_HOLD_ACTIVE, 6373 ERASURE_ROOT_MISMATCH, 6374 TOMBSTONE_INCONSISTENT, 6375 RESURRECTION_DETECTED, 6376 UNVERIFIABLE_POLICY).

verify_receipt

def verify_receipt(preimage_bytes: bytes, signature: bytes, trusted_pub_key: bytes) -> bool

Verify a SignedClaim receipt: a DETACHED bare-Ed25519 signature.

The signature covers the wire signing-preimage bytes VERBATIM — the Form-B 2-tuple ``canonical_cbor([tstr("osyra-ome-claim-v1"), claimMap])`` (claim 2-tuple wire shape per ADR-157 + ADR-008; canonical-CBOR strict-decode per ``AP00011-OME-FILE-FORMAT-V1.md`` §4.2). Verification is::

Ed25519.verify(trusted_pub_key, signature, preimage_bytes)

over ``preimage_bytes`` exactly as supplied — **the preimage is NEVER re-encoded** (that is the CRYPTO-2 fix). The preimage is canonical- decoded only to confirm its 2-tuple shape and to bind the dsTag (a Claim signature must never be accepted as a Witness/Bundle — cross- protocol confusion guard).

Args: preimage_bytes: The raw wire signing-preimage bytes (the bytes the signature attests). For a :class:~osyra_ome.types.SignedClaim this is its encoded_cbor field. signature: The 64-byte detached Ed25519 signature. trusted_pub_key: The 32-byte Ed25519 public key the caller trusts (the trust anchor — CRYPTO-1 / A1). The envelope's in-band signer_pub is attacker-controlled and is NOT used here.

Returns: True iff the signature verifies over preimage_bytes under trusted_pub_key; False on a genuine Ed25519 verify-false over a well-formed, correctly-tagged preimage.

Raises: OmeWireFormatError: the preimage is not bytes, is empty, is not strict-canonical CBOR, is not a 2-tuple, or carries the wrong dsTag (cross-protocol confusion). OmeVerifyError: signature is not 64 bytes, trusted_pub_key is not 32 bytes / not a valid Ed25519 point.

Classes

class AttestedClaimFields

Bases: NamedTuple

The signature-attested hash fields decoded from a claim preimage.

Attributes: content_hash: The signature-attested content hash (SHA-256; 32 bytes). Always present (a claim preimage MUST carry ch). embedding_hash: The signature-attested embedding hash (SHA-256; 32 bytes), present ONLY when the claim carries a NON-ZERO embedding digest. The proto always encodes an eh field; a 32-byte zero digest means "no embedding" and is reported as None here (a chat-message claim has no embedding). Mirrors the TS AttestedClaimFields.embeddingHash? optionality.

Attributes

| Name | Type | Default | | --- | --- | --- | | content_hash | bytes | | | embedding_hash | bytes | None | |