Skip to content

Submodule _types

derivepassphrase._types

Types used by derivepassphrase.

VaultConfigGlobalSettings

Bases: TypedDict

Configuration for vault: global settings.

Attributes:

Name Type Description
key NotRequired[str]

The base64-encoded ssh public key to use, overriding the master passphrase. Optional.

phrase NotRequired[str]

The master passphrase. Optional.

unicode_normalization_form NotRequired[Literal['NFC', 'NFD', 'NFKC', 'NFKD']]

The preferred Unicode normalization form; we warn the user if textual passphrases do not match their normalized forms. Optional, and a derivepassphrase extension.

length NotRequired[int]

Desired passphrase length.

repeat NotRequired[int]

The maximum number of immediate character repetitions allowed in the passphrase. Disabled if set to 0.

lower NotRequired[int]

Optional constraint on ASCII lowercase characters. If positive, include this many lowercase characters somewhere in the passphrase. If 0, avoid lowercase characters altogether.

upper NotRequired[int]

Same as lower, but for ASCII uppercase characters.

number NotRequired[int]

Same as lower, but for ASCII digits.

space NotRequired[int]

Same as lower, but for the space character.

dash NotRequired[int]

Same as lower, but for the hyphen-minus and underscore characters.

symbol NotRequired[int]

Same as lower, but for all other hitherto unlisted ASCII printable characters (except backquote).

key instance-attribute

phrase instance-attribute

phrase: NotRequired[str]

unicode_normalization_form instance-attribute

unicode_normalization_form: NotRequired[
    Literal["NFC", "NFD", "NFKC", "NFKD"]
]

length instance-attribute

length: NotRequired[int]

repeat instance-attribute

repeat: NotRequired[int]

lower instance-attribute

lower: NotRequired[int]

upper instance-attribute

upper: NotRequired[int]

number instance-attribute

number: NotRequired[int]

space instance-attribute

space: NotRequired[int]

dash instance-attribute

symbol instance-attribute

symbol: NotRequired[int]

VaultConfigServicesSettings

Bases: VaultConfigGlobalSettings

Configuration for vault: services settings.

Attributes:

Name Type Description
notes NotRequired[str]

Optional notes for this service, to display to the user when generating the passphrase.

key NotRequired[str]

As per the global settings.

phrase NotRequired[str]

As per the global settings.

unicode_normalization_form NotRequired[str]

As per the global settings.

length NotRequired[str]

As per the global settings.

repeat NotRequired[str]

As per the global settings.

lower NotRequired[str]

As per the global settings.

upper NotRequired[str]

As per the global settings.

number NotRequired[str]

As per the global settings.

space NotRequired[str]

As per the global settings.

dash NotRequired[str]

As per the global settings.

symbol NotRequired[str]

As per the global settings.

notes instance-attribute

notes: NotRequired[str]

VaultConfig

Bases: TypedDict, _VaultConfig

Configuration for vault. For typing purposes.

Usually stored as JSON.

Attributes:

Name Type Description
global NotRequired[VaultConfigGlobalSettings]

Global settings.

services Required[dict[str, VaultConfigServicesSettings]]

Service-specific settings.

CleanupStep

Bases: NamedTuple

A single executed step during vault config cleanup.

Attributes:

Name Type Description
path Sequence[str | int]

A sequence of object keys or array indices to navigate to the JSON value that was cleaned up.

old_value Any

The old value.

action Literal['replace', 'remove']

Either 'replace' if old_value was replaced with new_value, or 'remove' if old_value was removed.

new_value Any

The new value.

path instance-attribute

path: Sequence[str | int]

old_value instance-attribute

old_value: Any

action instance-attribute

action: Literal['replace', 'remove']

new_value instance-attribute

new_value: Any

KeyCommentPair

Bases: NamedTuple

SSH key plus comment pair. For typing purposes.

Attributes:

Name Type Description
key bytes | bytearray

SSH key.

comment bytes | bytearray

SSH key comment.

key instance-attribute

comment instance-attribute

comment: bytes | bytearray

SSH_AGENTC

Bases: Enum

SSH agent protocol numbers: client requests.

Attributes:

Name Type Description
REQUEST_IDENTITIES int

List identities. Expecting SSH_AGENT.IDENTITIES_ANSWER.

SIGN_REQUEST int

Sign data. Expecting SSH_AGENT.SIGN_RESPONSE.

ADD_IDENTITY int

Add an (SSH2) identity.

REMOVE_IDENTITY int

Remove an (SSH2) identity.

ADD_ID_CONSTRAINED int

Add an (SSH2) identity, including key constraints.

EXTENSION int

Issue a named request that isn’t part of the core agent protocol. Expecting SSH_AGENT.EXTENSION_RESPONSE or SSH_AGENT.EXTENSION_FAILURE if the named request is supported, SSH_AGENT.FAILURE otherwise.

REQUEST_IDENTITIES class-attribute instance-attribute

REQUEST_IDENTITIES: int = 11

SIGN_REQUEST class-attribute instance-attribute

SIGN_REQUEST: int = 13

ADD_IDENTITY class-attribute instance-attribute

ADD_IDENTITY: int = 17

REMOVE_IDENTITY class-attribute instance-attribute

REMOVE_IDENTITY: int = 18

ADD_ID_CONSTRAINED class-attribute instance-attribute

ADD_ID_CONSTRAINED: int = 25

EXTENSION class-attribute instance-attribute

EXTENSION: int = 27

SSH_AGENT

Bases: Enum

SSH agent protocol numbers: server replies.

Attributes:

Name Type Description
FAILURE int

Generic failure code.

SUCCESS int

Generic success code.

IDENTITIES_ANSWER int

Successful answer to SSH_AGENTC.REQUEST_IDENTITIES.

SIGN_RESPONSE int

Successful answer to SSH_AGENTC.SIGN_REQUEST.

EXTENSION_FAILURE int

Unsuccessful answer to SSH_AGENTC.EXTENSION.

EXTENSION_RESPONSE int

Successful answer to SSH_AGENTC.EXTENSION.

FAILURE class-attribute instance-attribute

FAILURE: int = 5

SUCCESS class-attribute instance-attribute

SUCCESS: int = 6

IDENTITIES_ANSWER class-attribute instance-attribute

IDENTITIES_ANSWER: int = 12

SIGN_RESPONSE class-attribute instance-attribute

SIGN_RESPONSE: int = 14

EXTENSION_FAILURE class-attribute instance-attribute

EXTENSION_FAILURE: int = 28

EXTENSION_RESPONSE class-attribute instance-attribute

EXTENSION_RESPONSE: int = 29

json_path

json_path(path: Sequence[str | int]) -> str

Transform a series of keys and indices into a JSONPath selector.

The resulting JSONPath selector conforms to RFC 9535, is always rooted at the JSON root node (i.e., starts with $), and only contains name and index selectors (in shorthand dot notation, where possible).

Parameters:

Name Type Description Default
path Sequence[str | int]

A sequence of object keys or array indices to navigate to the desired JSON value, starting from the root node.

required

Returns:

Type Description
str

A valid JSONPath selector (a string) identifying the desired JSON value.

Examples:

>>> json_path(['global', 'phrase'])
'$.global.phrase'
>>> json_path(['services', 'service name with spaces', 'length'])
'$.services["service name with spaces"].length'
>>> json_path(['services', 'special\u000acharacters', 'notes'])
'$.services["special\\ncharacters"].notes'
>>> print(json_path(['services', 'special\u000acharacters', 'notes']))
$.services["special\ncharacters"].notes
>>> json_path(['custom_array', 2, 0])
'$.custom_array[2][0]'

validate_vault_config

validate_vault_config(
    obj: Any,
    /,
    *,
    allow_unknown_settings: bool = False,
    allow_derivepassphrase_extensions: bool = False,
) -> None

Check that obj is a valid vault config.

Parameters:

Name Type Description Default
obj Any

The object to test.

required
allow_unknown_settings bool

If false, abort on unknown settings.

False
allow_derivepassphrase_extensions bool

If true, allow derivepassphrase extensions.

False

Raises:

Type Description
TypeError

An entry in the vault config, or the vault config itself, has the wrong type.

ValueError

An entry in the vault config is not allowed, or has a disallowed value.

is_vault_config

is_vault_config(obj: Any) -> TypeIs[VaultConfig]

Check if obj is a valid vault config, according to typing.

Parameters:

Name Type Description Default
obj Any

The object to test.

required

Returns:

Type Description
TypeIs[VaultConfig]

True if this is a vault config, false otherwise.

js_truthiness

js_truthiness(value: Any) -> bool

Return the truthiness of the value, according to JavaScript/ECMAScript.

Like Python, ECMAScript considers certain values to be false in a boolean context, and every other value to be true. These considerations do not agree: ECMAScript considers math.nan to be false too, and empty arrays and objects/dicts to be true, contrary to Python. Because of these discrepancies, we cannot defer to bool for ECMAScript truthiness checking, and need a separate, explicit predicate.

(Some falsy values in ECMAScript aren’t defined in Python: undefined, and document.all. We do not implement support for those.)

Note

We cannot use a simple value not in falsy_values check, because math.nan behaves in annoying and obstructive ways. In general, float('NaN') == float('NaN') is false, and float('NaN') != math.nan and math.nan != math.nan are true. CPython says float('NaN') in [math.nan] is false, PyPy3 says it is true. Seemingly the only reliable and portable way to check for math.nan is to use math.isnan directly.

Parameters:

Name Type Description Default
value Any

The value to test.

required

clean_up_falsy_vault_config_values

clean_up_falsy_vault_config_values(
    obj: Any,
) -> Sequence[CleanupStep] | None

Convert falsy values in a vault config to correct types, in-place.

Needed for compatibility with vault(1), which sometimes uses only truthiness checks.

If vault(1) considered obj to be valid, then after clean up, obj will be valid as per validate_vault_config.

Parameters:

Name Type Description Default
obj Any

A presumed valid vault configuration save for using falsy values of the wrong type.

required

Returns:

Type Description
Sequence[CleanupStep] | None

A list of 4-tuples (key_tup, old_value, action, new_value), indicating the cleanup actions performed. key_tup is a sequence of object keys and/or array indices indicating the JSON path to the leaf value that was cleaned up, old_value is the old value, new_value is the new value, and action is either replace (old_value was replaced with new_value) or remove (old_value was removed, and new_value is meaningless).

If cleanup was never attempted because of an obviously invalid vault configuration, then None is returned, directly.