fscryptography 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,294 @@
1
+ """Production MasterKey v1.0 container and Tink keyset integration."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import base64
6
+ import binascii
7
+ import os
8
+ import struct
9
+ from dataclasses import dataclass
10
+
11
+ import tink
12
+ from argon2.low_level import Type, hash_secret_raw
13
+ from cryptography.exceptions import InvalidTag
14
+ from cryptography.hazmat.primitives.ciphers.aead import AESGCM
15
+ from tink import aead, secret_key_access, streaming_aead
16
+
17
+ from .errors import (
18
+ AuthenticationError,
19
+ BackendError,
20
+ FormatError,
21
+ KeyDerivationError,
22
+ UnsupportedFormatVersionError,
23
+ )
24
+
25
+ _MAGIC = b"FSCRKEY\0"
26
+ _MAJOR = 1
27
+ _MINOR = 0
28
+ _SCHEMA = 1
29
+ _MODE_RANDOM = 0
30
+ _MODE_PASSWORD = 1
31
+ _HEADER_RANDOM = 20
32
+ _HEADER_PASSWORD = 61
33
+ _MAX_KEYSET = 32 * 1024
34
+ _MAX_LOGICAL_PAYLOAD = 128 * 1024
35
+ _MAX_BINARY = 131_149
36
+ _MAX_BASE64 = 174_868
37
+ _ARGON2_VERSION = 19
38
+ _ARGON2_MEMORY_KIB = 65_536
39
+ _ARGON2_TIME = 3
40
+ _ARGON2_PARALLELISM = 1
41
+ _SALT_LENGTH = 16
42
+ _NONCE_LENGTH = 12
43
+ _TAG_LENGTH = 16
44
+
45
+
46
+ @dataclass(frozen=True, slots=True)
47
+ class _KeyMaterial:
48
+ content: streaming_aead.StreamingAead
49
+ names: aead.Aead
50
+
51
+
52
+ def _password_bytes(password: str) -> bytes:
53
+ if not isinstance(password, str):
54
+ raise TypeError("password must be str")
55
+ try:
56
+ value = password.encode("utf-8", errors="strict")
57
+ except UnicodeEncodeError as exc:
58
+ raise ValueError("password must be valid UTF-8 text") from exc
59
+ if not value or len(value) > 1024:
60
+ raise ValueError("password must contain 1 to 1024 UTF-8 bytes")
61
+ return value
62
+
63
+
64
+ def _derive_wrapping_key(password: bytes, salt: bytes) -> bytes:
65
+ try:
66
+ return hash_secret_raw(
67
+ secret=password,
68
+ salt=salt,
69
+ time_cost=_ARGON2_TIME,
70
+ memory_cost=_ARGON2_MEMORY_KIB,
71
+ parallelism=_ARGON2_PARALLELISM,
72
+ hash_len=32,
73
+ type=Type.ID,
74
+ version=_ARGON2_VERSION,
75
+ )
76
+ except Exception as exc:
77
+ raise KeyDerivationError("MasterKey key derivation failed") from exc
78
+
79
+
80
+ def _serialize_keyset(handle: tink.KeysetHandle) -> bytes:
81
+ try:
82
+ return tink.proto_keyset_format.serialize(
83
+ handle, secret_key_access.TOKEN
84
+ )
85
+ except Exception as exc:
86
+ raise BackendError("unable to serialize MasterKey keyset") from exc
87
+
88
+
89
+ def _new_keysets() -> tuple[bytes, bytes]:
90
+ try:
91
+ streaming_aead.register()
92
+ aead.register()
93
+ content_template = getattr(
94
+ streaming_aead.streaming_aead_key_templates,
95
+ "AES256_GCM_HKDF_1MB",
96
+ )
97
+ names_template = aead.aead_key_templates.AES256_GCM
98
+ content = _serialize_keyset(tink.new_keyset_handle(content_template))
99
+ names = _serialize_keyset(tink.new_keyset_handle(names_template))
100
+ except BackendError:
101
+ raise
102
+ except Exception as exc:
103
+ raise BackendError("unable to generate MasterKey keysets") from exc
104
+ return content, names
105
+
106
+
107
+ def _frame_payload(content_keyset: bytes, names_keyset: bytes) -> bytes:
108
+ if not content_keyset or not names_keyset:
109
+ raise BackendError("Tink generated an empty keyset")
110
+ if len(content_keyset) > _MAX_KEYSET or len(names_keyset) > _MAX_KEYSET:
111
+ raise BackendError("Tink keyset exceeds the MasterKey size limit")
112
+ payload = (
113
+ struct.pack(">I", len(content_keyset))
114
+ + content_keyset
115
+ + struct.pack(">I", len(names_keyset))
116
+ + names_keyset
117
+ )
118
+ if len(payload) > _MAX_LOGICAL_PAYLOAD:
119
+ raise BackendError("MasterKey payload exceeds the size limit")
120
+ return payload
121
+
122
+
123
+ def _split_payload(payload: bytes) -> tuple[bytes, bytes]:
124
+ if not isinstance(payload, bytes) or len(payload) < 8:
125
+ raise FormatError("MasterKey payload framing is truncated")
126
+ first_length = struct.unpack_from(">I", payload, 0)[0]
127
+ if first_length == 0 or first_length > _MAX_KEYSET:
128
+ raise FormatError("invalid content keyset length")
129
+ first_end = 4 + first_length
130
+ if len(payload) < first_end + 4:
131
+ raise FormatError("MasterKey name keyset length is missing")
132
+ second_length = struct.unpack_from(">I", payload, first_end)[0]
133
+ if second_length == 0 or second_length > _MAX_KEYSET:
134
+ raise FormatError("invalid name keyset length")
135
+ second_start = first_end + 4
136
+ second_end = second_start + second_length
137
+ if second_end != len(payload):
138
+ raise FormatError("MasterKey payload has truncated or trailing data")
139
+ return payload[4:first_end], payload[second_start:second_end]
140
+
141
+
142
+ def _restore_key_material(content_keyset: bytes, names_keyset: bytes) -> _KeyMaterial:
143
+ try:
144
+ streaming_aead.register()
145
+ aead.register()
146
+ content_handle = tink.proto_keyset_format.parse(
147
+ content_keyset, secret_key_access.TOKEN
148
+ )
149
+ names_handle = tink.proto_keyset_format.parse(
150
+ names_keyset, secret_key_access.TOKEN
151
+ )
152
+ content = content_handle.primitive(streaming_aead.StreamingAead)
153
+ names = names_handle.primitive(aead.Aead)
154
+ except Exception as exc:
155
+ raise FormatError("MasterKey contains invalid or unexpected Tink keysets") from exc
156
+ return _KeyMaterial(content=content, names=names)
157
+
158
+
159
+ def generate_master_key(*, password: str | None = None) -> str:
160
+ """Generate an opaque Base64 MasterKey v1.0 container."""
161
+ password_raw = None if password is None else _password_bytes(password)
162
+ content_keyset, names_keyset = _new_keysets()
163
+ logical_payload = _frame_payload(content_keyset, names_keyset)
164
+
165
+ if password is None:
166
+ header = (
167
+ _MAGIC
168
+ + bytes((_MAJOR, _MINOR, _MODE_RANDOM, _SCHEMA))
169
+ + struct.pack(">HHI", 0, _HEADER_RANDOM, len(logical_payload))
170
+ )
171
+ binary = header + logical_payload
172
+ else:
173
+ salt = os.urandom(_SALT_LENGTH)
174
+ nonce = os.urandom(_NONCE_LENGTH)
175
+ header = (
176
+ _MAGIC
177
+ + bytes((_MAJOR, _MINOR, _MODE_PASSWORD, _SCHEMA))
178
+ + struct.pack(">HHI", 0, _HEADER_PASSWORD, len(logical_payload) + _TAG_LENGTH)
179
+ + bytes((1, _ARGON2_VERSION))
180
+ + struct.pack(">IIH", _ARGON2_MEMORY_KIB, _ARGON2_TIME, _ARGON2_PARALLELISM)
181
+ + salt
182
+ + bytes((1,))
183
+ + nonce
184
+ )
185
+ wrapping_key = _derive_wrapping_key(password_raw, salt)
186
+ try:
187
+ encrypted_payload = AESGCM(wrapping_key).encrypt(
188
+ nonce, logical_payload, header
189
+ )
190
+ except Exception as exc:
191
+ raise BackendError("MasterKey payload protection failed") from exc
192
+ binary = header + encrypted_payload
193
+
194
+ if len(binary) > _MAX_BINARY:
195
+ raise BackendError("generated MasterKey exceeds the binary size limit")
196
+ return base64.b64encode(binary).decode("ascii")
197
+
198
+
199
+ def _decode_master_key(master_key: str) -> bytes:
200
+ """Decode and validate the public Base64 representation."""
201
+ if not isinstance(master_key, str):
202
+ raise TypeError("master_key must be str")
203
+ try:
204
+ encoded = master_key.encode("ascii", errors="strict")
205
+ except UnicodeEncodeError as exc:
206
+ raise FormatError("MasterKey must be standard Base64 ASCII") from exc
207
+ if not encoded or len(encoded) > _MAX_BASE64:
208
+ raise FormatError("MasterKey Base64 length is invalid")
209
+ try:
210
+ binary = base64.b64decode(encoded, validate=True)
211
+ except (binascii.Error, ValueError) as exc:
212
+ raise FormatError("MasterKey is not valid Base64") from exc
213
+ if base64.b64encode(binary) != encoded:
214
+ raise FormatError("MasterKey Base64 is not canonical")
215
+ return binary
216
+
217
+
218
+ def _open_master_key_bytes(binary: bytes, *, password: str | None = None) -> _KeyMaterial:
219
+ """Open an already-decoded MasterKey container."""
220
+ if not isinstance(binary, bytes):
221
+ raise TypeError("binary MasterKey must be bytes")
222
+ if len(binary) > _MAX_BINARY or len(binary) < _HEADER_RANDOM:
223
+ raise FormatError("MasterKey binary size is invalid")
224
+ if binary[:8] != _MAGIC:
225
+ raise FormatError("MasterKey magic is invalid")
226
+ if binary[8] != _MAJOR or binary[9] != _MINOR:
227
+ raise UnsupportedFormatVersionError("unsupported MasterKey version")
228
+
229
+ mode, schema = binary[10], binary[11]
230
+ if mode not in (_MODE_RANDOM, _MODE_PASSWORD) or schema != _SCHEMA:
231
+ raise FormatError("unsupported MasterKey mode or payload schema")
232
+ flags, header_length, payload_length = struct.unpack_from(">HHI", binary, 12)
233
+ if flags != 0:
234
+ raise FormatError("MasterKey reserved flags must be zero")
235
+ expected_header = _HEADER_RANDOM if mode == _MODE_RANDOM else _HEADER_PASSWORD
236
+ payload_limit = (
237
+ _MAX_LOGICAL_PAYLOAD
238
+ if mode == _MODE_RANDOM
239
+ else _MAX_LOGICAL_PAYLOAD + _TAG_LENGTH
240
+ )
241
+ if header_length != expected_header:
242
+ raise FormatError("MasterKey header length is invalid")
243
+ if payload_length > payload_limit:
244
+ raise FormatError("MasterKey payload exceeds the size limit")
245
+ if mode == _MODE_PASSWORD and payload_length < _TAG_LENGTH:
246
+ raise FormatError("protected MasterKey payload is shorter than its AEAD tag")
247
+ if len(binary) != header_length + payload_length:
248
+ raise FormatError("MasterKey total length does not match its header")
249
+
250
+ header = binary[:header_length]
251
+ payload = binary[header_length:]
252
+ if mode == _MODE_RANDOM:
253
+ if password is not None:
254
+ raise ValueError("password must not be supplied for an unprotected MasterKey")
255
+ logical_payload = payload
256
+ else:
257
+ if password is None:
258
+ raise ValueError("password is required for this MasterKey")
259
+ password_raw = _password_bytes(password)
260
+ if (
261
+ header[20] != 1
262
+ or header[21] != _ARGON2_VERSION
263
+ or struct.unpack_from(">I", header, 22)[0] != _ARGON2_MEMORY_KIB
264
+ or struct.unpack_from(">I", header, 26)[0] != _ARGON2_TIME
265
+ or struct.unpack_from(">H", header, 30)[0] != _ARGON2_PARALLELISM
266
+ or header[48] != 1
267
+ ):
268
+ raise FormatError("MasterKey KDF or wrapping profile is unsupported")
269
+ salt = header[32:48]
270
+ nonce = header[49:61]
271
+ if len(salt) != _SALT_LENGTH or len(nonce) != _NONCE_LENGTH:
272
+ raise FormatError("MasterKey salt or nonce length is invalid")
273
+ wrapping_key = _derive_wrapping_key(password_raw, salt)
274
+ try:
275
+ logical_payload = AESGCM(wrapping_key).decrypt(
276
+ nonce, payload, header
277
+ )
278
+ except InvalidTag as exc:
279
+ raise AuthenticationError(
280
+ "MasterKey password or protected payload is invalid"
281
+ ) from exc
282
+ except Exception as exc:
283
+ raise BackendError("MasterKey payload decryption failed") from exc
284
+
285
+ if len(logical_payload) > _MAX_LOGICAL_PAYLOAD:
286
+ raise FormatError("MasterKey logical payload exceeds the size limit")
287
+ content_keyset, names_keyset = _split_payload(logical_payload)
288
+ return _restore_key_material(content_keyset, names_keyset)
289
+
290
+
291
+
292
+ def open_master_key(master_key: str, *, password: str | None = None) -> _KeyMaterial:
293
+ """Validate and open the public Base64 MasterKey representation."""
294
+ return _open_master_key_bytes(_decode_master_key(master_key), password=password)
@@ -0,0 +1,89 @@
1
+ """Public Manager API for MasterKey-backed filesystem cryptography."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import base64
6
+
7
+ from ._master_key import (
8
+ _KeyMaterial,
9
+ _decode_master_key,
10
+ _open_master_key_bytes,
11
+ generate_master_key,
12
+ )
13
+ from .errors import ClosedInstanceError
14
+
15
+
16
+ def generate(*, password: str | None = None) -> str:
17
+ """Generate a Base64 MasterKey, optionally protected by a password."""
18
+ return generate_master_key(password=password)
19
+
20
+
21
+ class Manager:
22
+ """An opened cryptographic context bound to one MasterKey.
23
+
24
+ The public key representation is Base64 text. The manager retains the
25
+ decoded binary container and the opened Tink primitives. Passwords are
26
+ consumed during initialization or key replacement and are never retained.
27
+ """
28
+
29
+ def __init__(self, key: str, *, password: str | None = None) -> None:
30
+ key_bytes = _decode_master_key(key)
31
+ material = _open_master_key_bytes(key_bytes, password=password)
32
+ self._key: bytes | None = key_bytes
33
+ self._material: _KeyMaterial | None = material
34
+ from ._filesystem import _DirectoryOperations, _FileOperations
35
+ self._file_operations = _FileOperations(self)
36
+ self._directory_operations = _DirectoryOperations(self)
37
+
38
+ def _require_open(self) -> _KeyMaterial:
39
+ if self._material is None or self._key is None:
40
+ raise ClosedInstanceError("Manager is closed")
41
+ return self._material
42
+
43
+ @property
44
+ def _content_primitive(self):
45
+ return self._require_open().content
46
+
47
+ @property
48
+ def _names_primitive(self):
49
+ return self._require_open().names
50
+
51
+ @property
52
+ def file(self):
53
+ self._require_open()
54
+ return self._file_operations
55
+
56
+ @property
57
+ def dir(self):
58
+ self._require_open()
59
+ return self._directory_operations
60
+
61
+ def change_key(self, new_key: str, *, password: str | None = None) -> None:
62
+ """Replace the active context only after the new key opens successfully."""
63
+ self._require_open()
64
+ key_bytes = _decode_master_key(new_key)
65
+ material = _open_master_key_bytes(key_bytes, password=password)
66
+ self._key = key_bytes
67
+ self._material = material
68
+
69
+ def inspect_recovery(self, parent):
70
+ """Return immutable, read-only diagnostics for transactions under parent."""
71
+ from ._journal import inspect
72
+ return inspect(parent)
73
+
74
+ def export_key(self) -> str:
75
+ """Return the current MasterKey container as canonical Base64 text."""
76
+ self._require_open()
77
+ return base64.b64encode(self._key).decode("ascii")
78
+
79
+ def close(self) -> None:
80
+ """Invalidate this manager and release references to its key material."""
81
+ self._material = None
82
+ self._key = None
83
+
84
+ def __enter__(self) -> Manager:
85
+ self._require_open()
86
+ return self
87
+
88
+ def __exit__(self, exc_type, exc, traceback) -> None:
89
+ self.close()
@@ -0,0 +1,52 @@
1
+ """Public exception hierarchy for fscryptography."""
2
+
3
+ class FsCryptographyError(Exception):
4
+ """Base class for errors raised by fscryptography."""
5
+
6
+
7
+ class InvalidPathError(FsCryptographyError):
8
+ """A path or path component cannot be used by the requested operation."""
9
+
10
+
11
+ class UnsupportedResourceError(FsCryptographyError):
12
+ """The resource exists but is not supported by the operation."""
13
+
14
+
15
+ class FormatError(FsCryptographyError):
16
+ """An encoded representation is malformed or not recognized."""
17
+
18
+
19
+ class UnsupportedFormatVersionError(FormatError):
20
+ """The encoded representation uses an unsupported version."""
21
+
22
+
23
+ class AuthenticationError(FsCryptographyError):
24
+ """Authenticated decryption failed."""
25
+
26
+
27
+ class KeyDerivationError(FsCryptographyError):
28
+ """A key derivation operation failed."""
29
+
30
+
31
+ class DestinationConflictError(FsCryptographyError):
32
+ """The destination conflicts with an existing filesystem entry."""
33
+
34
+
35
+ class NameConstraintError(FsCryptographyError):
36
+ """A name violates the selected filesystem name profile."""
37
+
38
+
39
+ class BackendError(FsCryptographyError):
40
+ """A cryptographic backend operation failed unexpectedly."""
41
+
42
+
43
+ class ClosedInstanceError(FsCryptographyError):
44
+ """An operation was attempted on a closed Crypto instance."""
45
+
46
+
47
+ class AtomicOperationError(FsCryptographyError):
48
+ """An atomic filesystem operation could not be completed safely."""
49
+
50
+
51
+ class RecoveryError(AtomicOperationError):
52
+ """Rollback or recovery failed."""
@@ -0,0 +1,178 @@
1
+ """Binary file envelope header for fscryptography v1.0."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import struct
6
+ from dataclasses import dataclass
7
+
8
+ from .errors import FormatError, UnsupportedFormatVersionError
9
+
10
+ MAGIC = b"FSCRFIL\0"
11
+ MAJOR_VERSION = 1
12
+ MINOR_VERSION = 0
13
+ FIXED_HEADER_SIZE = 16
14
+ METADATA_PREFIX_SIZE = 4
15
+ MAX_EXTENSION_BYTES = 1020
16
+ MAX_HEADER_SIZE = FIXED_HEADER_SIZE + METADATA_PREFIX_SIZE + 2 * MAX_EXTENSION_BYTES
17
+
18
+ FLAG_ORIGINAL_EXTENSION = 0x0001
19
+ FLAG_ENCRYPTED_NAME = 0x0002
20
+ _KNOWN_FLAGS = FLAG_ORIGINAL_EXTENSION | FLAG_ENCRYPTED_NAME
21
+
22
+
23
+ @dataclass(frozen=True, slots=True)
24
+ class FileHeader:
25
+ """Validated, authenticated metadata carried by a file header."""
26
+
27
+ original_extension: str | None
28
+ output_extension: str | None
29
+ encrypted_name: bool
30
+ raw: bytes
31
+
32
+
33
+ def split_extension(name: str) -> tuple[str, str | None]:
34
+ """Return (base, extension); dotfiles and trailing dots have no extension."""
35
+ if not isinstance(name, str):
36
+ raise TypeError("name must be str")
37
+ if not name or name in {".", ".."} or "/" in name or "\\x00" in name:
38
+ raise ValueError("name must be one non-empty filename component")
39
+ dot = name.rfind(".")
40
+ if dot <= 0 or dot == len(name) - 1:
41
+ return name, None
42
+ return name[:dot], name[dot:]
43
+
44
+
45
+ def validate_extension(extension: str | None, *, allow_none: bool = True) -> str | None:
46
+ """Validate an extension value without adding, stripping, or normalizing."""
47
+ if extension is None:
48
+ if allow_none:
49
+ return None
50
+ raise ValueError("extension is required")
51
+ if not isinstance(extension, str):
52
+ raise TypeError("extension must be str or None")
53
+ if extension == "":
54
+ return ""
55
+ if (
56
+ not extension.startswith(".")
57
+ or extension.startswith("..")
58
+ or "/" in extension
59
+ or "\\x00" in extension
60
+ or len(extension) < 2
61
+ or any(ord(char) < 0x20 for char in extension)
62
+ ):
63
+ raise ValueError("extension must be a valid single-component suffix")
64
+ try:
65
+ encoded = extension.encode("utf-8", errors="strict")
66
+ except UnicodeEncodeError as exc:
67
+ raise ValueError("extension must be valid UTF-8") from exc
68
+ if len(encoded) > MAX_EXTENSION_BYTES:
69
+ raise ValueError("extension exceeds the format metadata limit")
70
+ return extension
71
+
72
+
73
+ def build_header(
74
+ *,
75
+ original_extension: str | None,
76
+ output_extension: str | None,
77
+ encrypted_name: bool = False,
78
+ ) -> bytes:
79
+ """Serialize the v1.0 header; both extension values are authenticated as AAD.
80
+
81
+ For visible names, output_extension is mandatory and may be empty. For
82
+ encrypted names, neither extension is stored in cleartext.
83
+ """
84
+ original = validate_extension(original_extension)
85
+ output = validate_extension(output_extension)
86
+ if original == "":
87
+ raise ValueError("original_extension must be None or a non-empty suffix")
88
+ if not isinstance(encrypted_name, bool):
89
+ raise TypeError("encrypted_name must be bool")
90
+ if encrypted_name:
91
+ if original is not None or output is not None:
92
+ raise ValueError("encrypted-name headers must not expose extensions")
93
+ flags = FLAG_ENCRYPTED_NAME
94
+ original_bytes = output_bytes = b""
95
+ else:
96
+ if output is None:
97
+ raise ValueError("visible-name headers require output_extension")
98
+ flags = 0
99
+ if original is not None:
100
+ flags |= FLAG_ORIGINAL_EXTENSION
101
+ original_bytes = b"" if original is None else original.encode("utf-8")
102
+ output_bytes = output.encode("utf-8")
103
+
104
+ metadata = struct.pack(">HH", len(original_bytes), len(output_bytes))
105
+ metadata += original_bytes + output_bytes
106
+ header_length = FIXED_HEADER_SIZE + len(metadata)
107
+ if header_length > MAX_HEADER_SIZE:
108
+ raise ValueError("file header exceeds the format limit")
109
+ fixed = (
110
+ MAGIC
111
+ + bytes((MAJOR_VERSION, MINOR_VERSION))
112
+ + struct.pack(">HI", flags, header_length)
113
+ )
114
+ return fixed + metadata
115
+
116
+
117
+ def parse_header(raw: bytes) -> FileHeader:
118
+ """Parse and strictly validate one complete v1.0 header."""
119
+ if not isinstance(raw, bytes):
120
+ raise TypeError("header must be bytes")
121
+ if len(raw) < FIXED_HEADER_SIZE:
122
+ raise FormatError("file header is truncated")
123
+ if raw[:8] != MAGIC:
124
+ raise FormatError("file magic is invalid")
125
+ if raw[8] != MAJOR_VERSION or raw[9] != MINOR_VERSION:
126
+ raise UnsupportedFormatVersionError("unsupported file format version")
127
+ flags, header_length = struct.unpack_from(">HI", raw, 10)
128
+ if flags & ~_KNOWN_FLAGS:
129
+ raise FormatError("file header contains reserved flags")
130
+ if header_length < FIXED_HEADER_SIZE + METADATA_PREFIX_SIZE:
131
+ raise FormatError("file header length is too small")
132
+ if header_length > MAX_HEADER_SIZE:
133
+ raise FormatError("file header exceeds the format limit")
134
+ if len(raw) != header_length:
135
+ raise FormatError("file header length does not match supplied bytes")
136
+
137
+ original_length, output_length = struct.unpack_from(">HH", raw, FIXED_HEADER_SIZE)
138
+ if original_length > MAX_EXTENSION_BYTES or output_length > MAX_EXTENSION_BYTES:
139
+ raise FormatError("file extension metadata exceeds the format limit")
140
+ expected_length = FIXED_HEADER_SIZE + METADATA_PREFIX_SIZE + original_length + output_length
141
+ if expected_length != header_length:
142
+ raise FormatError("file extension metadata lengths are inconsistent")
143
+
144
+ original_raw = raw[20 : 20 + original_length]
145
+ output_raw = raw[20 + original_length : header_length]
146
+ try:
147
+ original = original_raw.decode("utf-8", errors="strict") if original_length else None
148
+ output = output_raw.decode("utf-8", errors="strict") if output_length else ""
149
+ except UnicodeDecodeError as exc:
150
+ raise FormatError("file extension metadata is not valid UTF-8") from exc
151
+
152
+ original_flag = bool(flags & FLAG_ORIGINAL_EXTENSION)
153
+ encrypted_name = bool(flags & FLAG_ENCRYPTED_NAME)
154
+ if original_flag != (original is not None):
155
+ raise FormatError("original-extension flag and metadata disagree")
156
+ if original is not None:
157
+ try:
158
+ validate_extension(original, allow_none=False)
159
+ except (TypeError, ValueError) as exc:
160
+ raise FormatError("original extension metadata is invalid") from exc
161
+ if encrypted_name:
162
+ if original_length or output_length or original_flag:
163
+ raise FormatError("encrypted-name header exposes extension metadata")
164
+ output_value = None
165
+ else:
166
+ if output_length:
167
+ try:
168
+ validate_extension(output, allow_none=False)
169
+ except (TypeError, ValueError) as exc:
170
+ raise FormatError("output extension metadata is invalid") from exc
171
+ output_value = output
172
+
173
+ return FileHeader(
174
+ original_extension=original,
175
+ output_extension=output_value,
176
+ encrypted_name=encrypted_name,
177
+ raw=raw,
178
+ )
@@ -0,0 +1,16 @@
1
+ """Filename encryption and validation primitives."""
2
+
3
+ from .codec import AAD, MARKER, decrypt_name, encrypt_name, is_canonical_candidate
4
+ from .validation import NameProfile, validate_name
5
+ from .tink_backend import load_name_primitive
6
+
7
+ __all__ = [
8
+ "AAD",
9
+ "MARKER",
10
+ "NameProfile",
11
+ "decrypt_name",
12
+ "encrypt_name",
13
+ "is_canonical_candidate",
14
+ "load_name_primitive",
15
+ "validate_name",
16
+ ]