cayu.runtime.public_authority

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

`parse_public_authority_alias`

from cayu import parse_public_authority_alias

Return the canonical alias components, or None for malformed input.

parse_public_authority_alias(value: str) -> ParsedPublicAuthorityAlias | None

Release source · Runtime guarantees · Capability guides

`ParsedPublicAuthorityAlias`

from cayu import ParsedPublicAuthorityAlias

Canonical, non-secret fields parsed from a public authority alias.

Decorators: @dataclass(frozen=True, slots=True).

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
`version`	`str`	`required`
`key_id`	`str`	`required`
`field_name`	`str`	`required`
`tag`	`str`	`required`

Release source · Runtime guarantees · Capability guides

`PUBLIC_AUTHORITY_ALIAS_ACTIVE_KEY_ID_ENV`

from cayu import PUBLIC_AUTHORITY_ALIAS_ACTIVE_KEY_ID_ENV

PUBLIC_AUTHORITY_ALIAS_ACTIVE_KEY_ID_ENV = 'CAYU_PUBLIC_AUTHORITY_ALIAS_ACTIVE_KEY_ID'

Release source · Runtime guarantees · Capability guides

`public_authority_alias_codec_from_environment`

from cayu import public_authority_alias_codec_from_environment

Load an explicit deployment codec from two environment variables.

CAYU_PUBLIC_AUTHORITY_ALIAS_KEYS is a JSON object mapping key IDs to canonical base64url key material. The active key ID is supplied separately so rotation never depends on mapping order. No variables means aliases are unconfigured; partial or malformed configuration fails closed.

public_authority_alias_codec_from_environment(environ: Mapping[str, str] | None=None) -> PublicAuthorityAliasCodec | None

Release source · Runtime guarantees · Capability guides

`public_authority_alias_is_reserved`

from cayu import public_authority_alias_is_reserved

Return whether a value occupies the public-authority alias namespace.

public_authority_alias_is_reserved(value: object) -> bool

Release source · Runtime guarantees · Capability guides

`PUBLIC_AUTHORITY_ALIAS_KEYS_ENV`

from cayu import PUBLIC_AUTHORITY_ALIAS_KEYS_ENV

PUBLIC_AUTHORITY_ALIAS_KEYS_ENV = 'CAYU_PUBLIC_AUTHORITY_ALIAS_KEYS'

Release source · Runtime guarantees · Capability guides

`PUBLIC_AUTHORITY_ALIAS_MAX_KEYS`

from cayu import PUBLIC_AUTHORITY_ALIAS_MAX_KEYS

PUBLIC_AUTHORITY_ALIAS_MAX_KEYS = 4

Release source · Runtime guarantees · Capability guides

`PUBLIC_AUTHORITY_ALIAS_PREFIX`

from cayu import PUBLIC_AUTHORITY_ALIAS_PREFIX

PUBLIC_AUTHORITY_ALIAS_PREFIX = 'cayu_authority_'

Release source · Runtime guarantees · Capability guides

`PUBLIC_AUTHORITY_ALIAS_VERSION`

from cayu import PUBLIC_AUTHORITY_ALIAS_VERSION

PUBLIC_AUTHORITY_ALIAS_VERSION = 'v1'

Release source · Runtime guarantees · Capability guides

`PublicAuthorityAliasCodec`

from cayu import PublicAuthorityAliasCodec

Create and verify versioned, field- and session-scoped HMAC aliases.

Decorators: @dataclass(frozen=True, slots=True).

Fields and attributes

Name	Type	Default
`keyring`	`PublicAuthorityAliasKeyring`	`required`

encode (method)

PublicAuthorityAliasCodec.encode(private_value: str, *, field_name: str, session_id: str | None=None) -> str

aliases (method)

PublicAuthorityAliasCodec.aliases(private_value: str, *, field_name: str, session_id: str | None=None) -> tuple[str, ...]

Return aliases for every accepted key, active key first.

Persistent stores use this during a keyed backfill so aliases issued before rotation remain resolvable without request-time scans.

key_fingerprint (method)

PublicAuthorityAliasCodec.key_fingerprint(key_id: str) -> str

Return a non-secret stable fingerprint for deployment validation.

keyring_fingerprint (method)

PublicAuthorityAliasCodec.keyring_fingerprint() -> str

Return a stable non-secret digest of the exact configured key set.

parse (method)

PublicAuthorityAliasCodec.parse(value: str) -> ParsedPublicAuthorityAlias | None

Parse a canonical supported alias without verifying private authority.

matches (method)

PublicAuthorityAliasCodec.matches(alias: str, private_value: str, *, field_name: str, session_id: str | None=None) -> bool

rotated (method)

PublicAuthorityAliasCodec.rotated(*, active_key_id: str, key: SecretStr, retire_key_ids: tuple[str, ...]=()) -> PublicAuthorityAliasCodec

Return an immutable codec using a rotated copy of this keyring.

is_reserved (method)

PublicAuthorityAliasCodec.is_reserved(value: object) -> bool

Release source · Runtime guarantees · Capability guides

`PublicAuthorityAliasKeyring`

from cayu import PublicAuthorityAliasKeyring

An immutable, secret-safe keyring for public authority aliases.

Key material is supplied as canonical, unpadded base64url text wrapping exactly 32 bytes. The active key signs new aliases; retained keys only verify aliases produced before rotation.

Decorators: @dataclass(frozen=True, slots=True, init=False).

Fields and attributes

Name	Type	Default
`active_key_id`	`str`	`required`

init (method)

PublicAuthorityAliasKeyring.__init__(*, active_key_id: str, keys: Mapping[str, SecretStr]) -> None

key_ids (property)

PublicAuthorityAliasKeyring.key_ids() -> tuple[str, ...]

keys (property)

PublicAuthorityAliasKeyring.keys() -> Mapping[str, SecretStr]

Return an immutable mapping whose values remain masked SecretStr objects.

rotated (method)

PublicAuthorityAliasKeyring.rotated(*, active_key_id: str, key: SecretStr, retire_key_ids: tuple[str, ...]=()) -> PublicAuthorityAliasKeyring

Return a new keyring with a new active key and optional retirements.

Release source · Runtime guarantees · Capability guides