oc_chat.registry.auth.rotation Namespace Reference

Classes
class	RotationResult

Functions
RotationResult	rotate_secret (Registry registry, *, str slot, str actor_slot, str actor_type="human_operator", int|None grace_seconds=None, str|Path|None secrets_path=None, str trigger="manual")
RotationResult	finalize_rotation (Registry registry, *, str slot, str actor_slot, str actor_type="human_operator", str|Path|None secrets_path=None, str trigger="manual_finalize")
int	_effective_grace_seconds (object backend, str slot, int|None grace_seconds)
None	_write_rotation_secret (object backend, *, str slot, SecretBlock new_block, str|Path|None secrets_path, str expires_at)
None	_promote_secret_block (object backend, *, str slot, str|Path|None secrets_path)
int|None	_latest_rotation_start_id (object backend, str slot, str old_key_id, str new_key_id)
Path	_secrets_path (object backend, str|Path|None override)

Detailed Description

Actor HMAC credential rotation.

Purpose
-------
Implement the two-phase credential rotation used by M11.5 actor auth.

Responsibilities
----------------
- Create a rotating-new credential and expire the previous active key.
- Finalize a rotation by revoking the old key and promoting the new key.
- Keep the local secret file in sync with generated key material.
- Emit audited ``auth.rotate_*`` rows through the registry seam.

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

Contracts
---------
- Raw secrets are written only to ``agent_secrets.json``.
- Credential-table writes happen before their audit operation is emitted.
- Nested rotations for one slot are rejected.

Dependencies
------------
- pathlib (secrets file paths)
- uuid (key ids for new credentials)
- oc_chat.registry.auth.secrets_store (generate new secrets and keep the local secrets file in sync)
- oc_chat.registry.clock (grace-period expiry timestamp)
- oc_chat.registry.errors (RotationInFlightError for a nested rotation)
- oc_chat.registry.api (Registry that emits the audited rotation operations)
- oc_chat.registry.backends.base (OperationLogRow carried in the rotation result)
- oc_diagnostics (structured debug logging via _dbg)

Function Documentation

_effective_grace_seconds()

int oc_chat.registry.auth.rotation._effective_grace_seconds ( object backend, str slot, int | None grace_seconds )

protected

Definition at line 240 of file rotation.py.

Here is the caller graph for this function:

_latest_rotation_start_id()

int | None oc_chat.registry.auth.rotation._latest_rotation_start_id ( object backend, str slot, str old_key_id, str new_key_id )

protected

Definition at line 316 of file rotation.py.

Here is the caller graph for this function:

_promote_secret_block()

None oc_chat.registry.auth.rotation._promote_secret_block ( object backend, * , str slot, str | Path | None secrets_path )

protected

Definition at line 289 of file rotation.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_secrets_path()

Path oc_chat.registry.auth.rotation._secrets_path ( object backend, str | Path | None override )

protected

Definition at line 334 of file rotation.py.

Here is the caller graph for this function:

_write_rotation_secret()

None oc_chat.registry.auth.rotation._write_rotation_secret ( object backend, * , str slot, SecretBlock new_block, str | Path | None secrets_path, str expires_at )

protected

Definition at line 261 of file rotation.py.

Here is the call graph for this function:

Here is the caller graph for this function:

finalize_rotation()

RotationResult oc_chat.registry.auth.rotation.finalize_rotation	(	Registry	registry,
		*	,
		str	slot,
		str	actor_slot,
		str	actor_type = "human_operator",
		str | Path | None	secrets_path = None,
		str	trigger = "manual_finalize" )

Finalize a pending rotation for ``slot``.

Definition at line 172 of file rotation.py.

Here is the call graph for this function:

rotate_secret()

RotationResult oc_chat.registry.auth.rotation.rotate_secret	(	Registry	registry,
		*	,
		str	slot,
		str	actor_slot,
		str	actor_type = "human_operator",
		int | None	grace_seconds = None,
		str | Path | None	secrets_path = None,
		str	trigger = "manual" )

Start a two-phase credential rotation for ``slot``.

Definition at line 79 of file rotation.py.

Here is the call graph for this function: