oc_chat.registry.auth.signing Namespace Reference

Classes
class	HmacProof
class	CredentialMaterial
class	VerifyResult

Functions
HmacProof	sign_command (*, str slot, str command, Mapping[str, object] args, bytes raw_secret, str hmac_key_id, Clock|None clock=None, int|None ts_ms=None)
VerifyResult	verify_hmac (*, str slot, str command, Mapping[str, object] args, HmacProof proof, CredentialMaterial|None credential, Clock|None clock=None, int max_skew_seconds=300)
str	canonical_payload (*, str slot, str command, Mapping[str, object] args, int ts_ms, str hmac_key_id)
str	payload_sha256 (Mapping[str, object] args)
str	_sign (str payload, bytes raw_secret)
int	_now_ms (Clock|None clock)

Variables
str	SIGNATURE_ALGORITHM = "HMAC-SHA256"

Detailed Description

Actor HMAC signing and verification.

Purpose
-------
Build and verify canonical HMAC-SHA256 proofs for mutating registry
commands.

Responsibilities
----------------
- Canonicalize the signed command payload.
- Produce proof mappings for CLI/API callers.
- Verify signatures with constant-time comparison and skew checks.

Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - lifecycle events
    L3 - semantic details
    L4 - deep tracing

Contracts
---------
- The signed payload includes slot, command, args, timestamp, and key id.
- Verification returns a structured failure reason for ``auth_events``.
- This module performs no registry writes and reads no secret files.

Dependencies
------------
- dataclasses (proof, credential and result records)
- hashlib (SHA-256 for signatures and payload digests)
- hmac (HMAC signing and constant-time comparison)
- oc_chat.registry.canonical (canonical JSON of the signed payload)
- oc_chat.registry.clock (timestamps for signing, skew and expiry checks)
- oc_diagnostics (structured debug logging via _dbg)

Function Documentation

_now_ms()

int oc_chat.registry.auth.signing._now_ms ( Clock | None clock )

protected

Definition at line 224 of file signing.py.

Here is the caller graph for this function:

_sign()

str oc_chat.registry.auth.signing._sign ( str payload, bytes raw_secret )

protected

Definition at line 216 of file signing.py.

Here is the caller graph for this function:

canonical_payload()

str oc_chat.registry.auth.signing.canonical_payload	(	*	,
		str	slot,
		str	command,
		Mapping[str, object]	args,
		int	ts_ms,
		str	hmac_key_id )

Return canonical JSON text for the signed command.

Definition at line 188 of file signing.py.

Here is the caller graph for this function:

payload_sha256()

str oc_chat.registry.auth.signing.payload_sha256

(

Mapping[str, object]

args

)

Return the canonical payload digest used in ``auth_events``.

Definition at line 210 of file signing.py.

sign_command()

HmacProof oc_chat.registry.auth.signing.sign_command	(	*	,
		str	slot,
		str	command,
		Mapping[str, object]	args,
		bytes	raw_secret,
		str	hmac_key_id,
		Clock | None	clock = None,
		int | None	ts_ms = None )

Return an HMAC proof for one command payload.

Definition at line 120 of file signing.py.

Here is the call graph for this function:

verify_hmac()

VerifyResult oc_chat.registry.auth.signing.verify_hmac	(	*	,
		str	slot,
		str	command,
		Mapping[str, object]	args,
		HmacProof	proof,
		CredentialMaterial | None	credential,
		Clock | None	clock = None,
		int	max_skew_seconds = 300 )

Verify one HMAC proof against resolved credential material.

Definition at line 147 of file signing.py.

Here is the call graph for this function:

Variable Documentation

SIGNATURE_ALGORITHM

str oc_chat.registry.auth.signing.SIGNATURE_ALGORITHM = "HMAC-SHA256"

Definition at line 58 of file signing.py.