`duck.secrets`¶

Provides utilities for generating and managing secure secrets and tokens for Duck applications.

This module generates and manages various secrets, including URL-safe tokens, ASCII-based secrets, and randomized domain names. The secrets are stored in environment variables to ensure they remain accessible and secure throughout the application lifecycle.

Main Components:

generate_secret(): Generates a URL-safe, cryptographically secure token.
generate_ascii_secret(): Generates a secure ASCII-only token for specific cases.
generate_random_domain(): Provides a randomized domain name for secure communication.
get_or_create_secret(): Retrieves or creates a named secret, persisting it to a secured file.

Environment Variables:

DXS: Stores a URL-safe token, generated if not already set.
RXS: Stores an ASCII-based token, generated if not already set, used in secret headers.
DXSD: Stores a randomized domain name, generated if not already set.

These environment variables are intended to enhance security by obfuscating sensitive values. When variables are not set initially, secure values are generated and assigned to them dynamically.

Module Contents¶

Functions¶

`generate_ascii_secret`	Generates a secure random ASCII-only token.
`generate_secret`	Generates a secure random URL-safe token.
`get_or_create_secret`	Retrieves a named secret from its persisted file, or creates and stores it.
`secure_mkdir`	Creates a directory with the tightest permissions available on the current OS.
`secure_read`	Enforces correct permissions on an existing secret file then reads it.
`secure_write`	Writes a secret to disk atomically with restricted file permissions.

Data¶

`IS_WINDOWS`
`SECRETS_DIR`
`SECRET_DIR_MODE`
`SECRET_FILE_MODE`

API¶

duck.secrets.IS_WINDOWS¶: None

duck.secrets.SECRETS_DIR¶: ‘Path(…)’

duck.secrets.SECRET_DIR_MODE¶: None

duck.secrets.SECRET_FILE_MODE¶: None

duck.secrets.generate_ascii_secret(length: int = 16) → str[source]¶

Generates a secure random ASCII-only token.

Uses only letters to ensure compatibility with contexts that require plain ASCII, such as secret header construction.

Parameters:: length – Number of characters in the generated token.
Returns:: A random ASCII letter token of the specified length.
Return type:: str

duck.secrets.generate_secret() → str[source]¶

Generates a secure random URL-safe token.

Returns:: A URL-safe token for use as a secret.
Return type:: str

duck.secrets.get_or_create_secret(name: str, generator: callable = generate_secret) → str[source]¶

Retrieves a named secret from its persisted file, or creates and stores it.

Lookup order:

Environment variable matching name — returned immediately if set.
Persisted file at SECRETS_DIR / name — read, permissions enforced, then returned.
Freshly generated via generator — written securely to disk, then returned.

File security per platform:

POSIX: file mode 0o600, directory mode 0o700.
Windows: icacls strips all inherited ACEs and grants only the current user R/W on files and full control on the directory.

Parameters:

name – Identifier for the secret. Used as the env var key and the filename.
generator – Callable that returns a new secret string when creation is needed.

Returns:

The secret value.

Return type:

str

Raises:

OSError – If the secrets directory or file cannot be created or secured.

duck.secrets.secure_mkdir(path: pathlib.Path) → None[source]¶

Creates a directory with the tightest permissions available on the current OS.

On POSIX systems, the directory is created with mode 0o700 (owner access only). On Windows, the directory is created normally and then locked down via icacls, removing all inherited and explicit ACEs except for the current user (full control).

Parameters:: path – The directory path to create and secure.
Raises:: OSError – If the directory cannot be created or secured.

duck.secrets.secure_read(path: pathlib.Path) → str[source]¶

Enforces correct permissions on an existing secret file then reads it.

This corrects permissions in case the file was created externally or copied without the expected ACL/mode, ensuring every read is from a locked-down file.

Parameters:: path – Path to the secret file to read.
Returns:: The secret value with surrounding whitespace stripped.
Return type:: str
Raises:: OSError – If permissions cannot be applied or the file cannot be read.

duck.secrets.secure_write(path: pathlib.Path, secret: str) → None[source]¶

Writes a secret to disk atomically with restricted file permissions.

The secret is written to a temporary file first, permissions are applied, and then the file is renamed to its final path. This prevents any window where the file exists with loose permissions.

On POSIX, the file is set to 0o600 (owner read/write only). On Windows, icacls removes all inherited ACEs and grants only the current user read/write access.