cadrumo.adapters.persistence.storage.bucket.keystore_paths module

Keystore separation contract enforcing the isolation invariant.

The KEK / DEK / passphrase / OS-keystore custody artefacts live under a keystore root that is structurally outside the buckets parent. The two invariants enforced here are:

• The keystore root is sibling to buckets/ under the Cadrumo root (<cadrumo-root>/keystore/<bucket-id>/), never nested inside any bucket directory and never co-located under the relational database directory.

• A configuration that resolves the keystore path under either parent is rejected by validate_keystore_separation() so a subsequent unlock cannot silently violate the invariant.

The pure helpers do not materialise the directory; the cryptographic core owns provisioning when an enrolment first lands.

keystore_root(root)

Return the keystore parent <root>/keystore/ (no IO).

Return type:

Path

Parameters:

root (Path)

keystore_path(root, bucket_id)

Return <root>/keystore/<bucket_id>/ (no IO).

Parameters:

• root (Path) – The Cadrumo storage root.

• bucket_id (str) – Bucket identifier to include in the path.

Return type:

Path

Returns:

The computed keystore directory path.

Raises:

BucketValidationError – When bucket_id is empty or carries a path separator.

validate_keystore_separation(root, bucket_id, *, configured_keystore=None)

Fail closed if the keystore path resolves under the buckets parent or db dir.

Parameters:

• root (Path) – The Cadrumo storage root.

• bucket_id (str) – The bucket identifier whose layout to validate against.

• configured_keystore (Path | None) – Optional override path; defaults to keystore_path(). A custom configuration that points at a location nested under the buckets parent or the per-bucket relational database directory is rejected.

Raises:

BucketValidationError – When the configured keystore path violates separation.

Return type:

None

keystore_sidecar_path(*, storage_root, bucket_id, filename)

Return <root>/keystore/<bucket_id>/<filename>, refusing an unseparated keystore.

Validates the keystore-separation invariant via validate_keystore_separation() before joining filename onto the bucket’s keystore directory, so a violation raises before any sidecar path is returned to the caller. Canonical join point for every keystore-resident sidecar (the persisted session record, the wrapped bucket DEK, the login-throttle cache).

Parameters:

• storage_root (Path) – The Cadrumo storage root.

• bucket_id (str) – Bucket identifier whose keystore directory to resolve.

• filename (str) – The sidecar filename to join onto the keystore directory.

Return type:

Path

Returns:

The keystore-separated sidecar path.

Both inputs are checked, which they were not before: separation is a statement about bucket_id, and filename was joined unexamined. This is the join point for the persisted session record, the wrapped bucket DEK and the login-throttle cache, so an unchecked filename places key material wherever it says – measured, "../../secrets.json" reached the storage root and "C:/evil.json" reached the drive root. Every caller passes a module constant today; the check is here so that stays a property of the join rather than of the callers.

Raises:

BucketValidationError – When the keystore path violates separation, or when bucket_id or filename is not a single containable path component.

Parameters:

• storage_root (Path)

• bucket_id (str)

• filename (str)

Return type:

Path