fscryptography 0.1.0__tar.gz → 0.2.0__tar.gz

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.
Files changed (61) hide show
  1. {fscryptography-0.1.0 → fscryptography-0.2.0}/MANIFEST.in +1 -0
  2. fscryptography-0.2.0/PKG-INFO +488 -0
  3. fscryptography-0.2.0/README.md +451 -0
  4. fscryptography-0.2.0/assets/fscryptography-architecture.svg +22 -0
  5. fscryptography-0.2.0/assets/fscryptography-banner.svg +20 -0
  6. fscryptography-0.2.0/assets/manual-test-ubuntu-24.04.svg +38 -0
  7. fscryptography-0.2.0/docs/100-files-roundtrip.md +65 -0
  8. {fscryptography-0.1.0 → fscryptography-0.2.0}/docs/api-reference.md +17 -12
  9. {fscryptography-0.1.0 → fscryptography-0.2.0}/docs/architecture.md +7 -7
  10. {fscryptography-0.1.0 → fscryptography-0.2.0}/docs/argon2id-policy.md +4 -3
  11. fscryptography-0.2.0/docs/atomic-operations.md +76 -0
  12. {fscryptography-0.1.0 → fscryptography-0.2.0}/docs/cryptographic-design.md +4 -4
  13. fscryptography-0.2.0/docs/errors.md +125 -0
  14. {fscryptography-0.1.0 → fscryptography-0.2.0}/docs/file-format.md +5 -4
  15. {fscryptography-0.1.0 → fscryptography-0.2.0}/docs/filename-encryption.md +12 -2
  16. fscryptography-0.2.0/docs/fuzzing-plan.md +126 -0
  17. {fscryptography-0.1.0 → fscryptography-0.2.0}/docs/index.md +10 -4
  18. {fscryptography-0.1.0 → fscryptography-0.2.0}/docs/key-management.md +13 -3
  19. {fscryptography-0.1.0 → fscryptography-0.2.0}/docs/master-key-format-test-plan.md +10 -11
  20. {fscryptography-0.1.0 → fscryptography-0.2.0}/docs/platform-compatibility.md +40 -18
  21. fscryptography-0.2.0/docs/releasing.md +129 -0
  22. fscryptography-0.2.0/docs/scope.md +43 -0
  23. fscryptography-0.2.0/docs/security-model.md +84 -0
  24. fscryptography-0.2.0/docs/versioning.md +69 -0
  25. fscryptography-0.2.0/docs/windows-11-validation.md +123 -0
  26. {fscryptography-0.1.0 → fscryptography-0.2.0}/pyproject.toml +4 -3
  27. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography/__init__.py +1 -5
  28. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography/_directory.py +17 -3
  29. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography/_filesystem.py +353 -63
  30. fscryptography-0.2.0/src/fscryptography/_transaction.py +121 -0
  31. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography/crypto.py +21 -16
  32. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography/errors.py +2 -5
  33. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography/names/validation.py +9 -1
  34. fscryptography-0.2.0/src/fscryptography.egg-info/PKG-INFO +488 -0
  35. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography.egg-info/SOURCES.txt +8 -2
  36. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography.egg-info/requires.txt +2 -0
  37. fscryptography-0.1.0/PKG-INFO +0 -168
  38. fscryptography-0.1.0/README.md +0 -133
  39. fscryptography-0.1.0/docs/atomic-operations.md +0 -72
  40. fscryptography-0.1.0/docs/errors.md +0 -82
  41. fscryptography-0.1.0/docs/recovery-journal.md +0 -165
  42. fscryptography-0.1.0/docs/releasing.md +0 -82
  43. fscryptography-0.1.0/docs/scope.md +0 -26
  44. fscryptography-0.1.0/docs/security-model.md +0 -28
  45. fscryptography-0.1.0/src/fscryptography/_journal.py +0 -493
  46. fscryptography-0.1.0/src/fscryptography.egg-info/PKG-INFO +0 -168
  47. {fscryptography-0.1.0 → fscryptography-0.2.0}/LICENSE +0 -0
  48. {fscryptography-0.1.0 → fscryptography-0.2.0}/docs/argon2id-benchmark.md +0 -0
  49. {fscryptography-0.1.0 → fscryptography-0.2.0}/docs/backend-validation.md +0 -0
  50. {fscryptography-0.1.0 → fscryptography-0.2.0}/docs/decisions/0001-initial-design.md +0 -0
  51. {fscryptography-0.1.0 → fscryptography-0.2.0}/docs/filesystem-hardening.md +0 -0
  52. {fscryptography-0.1.0 → fscryptography-0.2.0}/docs/master-key-format.md +0 -0
  53. {fscryptography-0.1.0 → fscryptography-0.2.0}/setup.cfg +0 -0
  54. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography/_master_key.py +0 -0
  55. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography/file_format.py +0 -0
  56. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography/names/__init__.py +0 -0
  57. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography/names/codec.py +0 -0
  58. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography/names/tink_backend.py +0 -0
  59. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography/py.typed +0 -0
  60. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography.egg-info/dependency_links.txt +0 -0
  61. {fscryptography-0.1.0 → fscryptography-0.2.0}/src/fscryptography.egg-info/top_level.txt +0 -0
@@ -1,3 +1,4 @@
1
1
  include LICENSE
2
2
  include README.md
3
3
  recursive-include docs *.md
4
+ recursive-include assets *.svg
@@ -0,0 +1,488 @@
1
+ Metadata-Version: 2.4
2
+ Name: fscryptography
3
+ Version: 0.2.0
4
+ Summary: Filesystem-oriented authenticated encryption for files and names
5
+ License-Expression: LicenseRef-Proprietary
6
+ Project-URL: Homepage, https://github.com/specter327/fscryptography
7
+ Project-URL: Repository, https://github.com/specter327/fscryptography
8
+ Project-URL: Documentation, https://github.com/specter327/fscryptography/tree/main/docs
9
+ Project-URL: Issues, https://github.com/specter327/fscryptography/issues
10
+ Project-URL: Changelog, https://github.com/specter327/fscryptography/blob/main/CHANGELOG.md
11
+ Keywords: cryptography,filesystem,file-encryption,authenticated-encryption,tink,argon2id
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Topic :: Security :: Cryptography
15
+ Classifier: Operating System :: POSIX :: Linux
16
+ Classifier: Operating System :: Microsoft :: Windows
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.11
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Requires-Dist: tink<2,>=1.16.1
26
+ Requires-Dist: argon2-cffi<26,>=23.1
27
+ Requires-Dist: cryptography<47,>=42
28
+ Provides-Extra: test
29
+ Requires-Dist: pytest<9,>=8; extra == "test"
30
+ Requires-Dist: hypothesis<7,>=6.100; extra == "test"
31
+ Provides-Extra: dev
32
+ Requires-Dist: build<2,>=1.2; extra == "dev"
33
+ Requires-Dist: pytest<9,>=8; extra == "dev"
34
+ Requires-Dist: hypothesis<7,>=6.100; extra == "dev"
35
+ Requires-Dist: twine<7,>=5; extra == "dev"
36
+ Dynamic: license-file
37
+
38
+ <div align="center">
39
+
40
+ <img src="assets/fscryptography-banner.svg" alt="fscryptography — filesystem-oriented authenticated encryption" width="100%">
41
+
42
+ [![PyPI version](https://img.shields.io/pypi/v/fscryptography?label=PyPI&logo=pypi&logoColor=white)](https://pypi.org/project/fscryptography/)
43
+ [![Python](https://img.shields.io/pypi/pyversions/fscryptography?logo=python&logoColor=white)](https://pypi.org/project/fscryptography/)
44
+ [![Build](https://img.shields.io/github/actions/workflow/status/specter327/fscryptography/backend-validation.yml?label=backend%20tests&logo=githubactions&logoColor=white)](https://github.com/specter327/fscryptography/actions)
45
+ [![License](https://img.shields.io/badge/license-proprietary%20%2F%20all%20rights%20reserved-8b5cf6)](LICENSE)
46
+ [![Status](https://img.shields.io/badge/status-alpha-f59e0b)](https://github.com/specter327/fscryptography/releases)
47
+
48
+ **Cifrado autenticado de archivos y nombres, directamente sobre el sistema de archivos.**
49
+
50
+ [Instalación](#instalación) · [Inicio rápido](#inicio-rápido) · [Manual de API](#manual-de-la-api) · [Arquitectura](#arquitectura) · [Seguridad](#seguridad) · [Documentación](#documentación)
51
+
52
+ </div>
53
+
54
+ ---
55
+
56
+ ## ¿Qué es fscryptography?
57
+
58
+ **fscryptography** (*filesystem cryptography*) es una librería Python para cifrar y descifrar archivos y transformar nombres de archivos y directorios mediante operaciones sobre rutas del sistema de archivos.
59
+
60
+ Ofrece una interfaz de alto nivel basada en `pathlib.Path` y `os.PathLike`, cifrado autenticado, procesamiento segmentado para archivos grandes y un contexto criptográfico reutilizable.
61
+
62
+ No es un filesystem virtual, un gestor de secretos ni una herramienta de cifrado genérico de bytes o streams. Su alcance es deliberadamente concreto: **proteger archivos y nombres existentes en el filesystem**.
63
+
64
+ ## Características
65
+
66
+ - **Cifrado autenticado de contenido:** Google Tink Streaming AEAD con `AES256_GCM_HKDF_1MB`.
67
+ - **Procesamiento segmentado:** lectura y escritura secuencial en bloques de 1 MiB; no requiere cargar el archivo completo en memoria.
68
+ - **Cifrado de nombres:** AEAD independiente con `AES256_GCM` para nombres de archivos y directorios.
69
+ - **MasterKey autocontenida:** keysets independientes para contenido y nombres, transportados como Base64 estándar.
70
+ - **Protección opcional por contraseña:** Argon2id y AES-256-GCM para proteger el contenedor MasterKey.
71
+ - **Contexto reutilizable:** `Manager` abre las primitivas una vez y las reutiliza durante las operaciones.
72
+ - **Publicación sin sobrescritura:** evita reemplazar destinos existentes de forma accidental.
73
+ - **Errores tipados:** excepciones propias con una jerarquía pública, preservando errores estándar del filesystem cuando corresponde.
74
+ - **Estado transaccional en memoria:** no crea journals ni directorios de recuperación persistentes.
75
+
76
+ ## Instalación
77
+
78
+ Requisitos: **Python 3.11 o posterior**.
79
+
80
+ ```bash
81
+ python -m pip install fscryptography
82
+ ```
83
+
84
+ Comprueba la instalación:
85
+
86
+ ```bash
87
+ python -c "import fscryptography; print(fscryptography.__version__)"
88
+ ```
89
+
90
+ ## Inicio rápido
91
+
92
+ El ejemplo siguiente cifra un archivo y posteriormente lo descifra. Las operaciones transforman el recurso en el filesystem: al completar correctamente el cifrado, el archivo original se retira y se publica el archivo cifrado; al descifrar, sucede lo inverso.
93
+
94
+ ```python
95
+ from pathlib import Path
96
+
97
+ import fscryptography
98
+
99
+ # Genera una MasterKey aleatoria (contenedor autocontenido en Base64).
100
+ master_key = fscryptography.generate()
101
+
102
+ # Conserva esta clave fuera del directorio que vas a proteger.
103
+ # No la imprimas ni la incluyas en logs o en el control de versiones.
104
+ source = Path("documento.txt")
105
+
106
+ with fscryptography.Manager(key=master_key) as manager:
107
+ manager.file.encrypt(source)
108
+ # Resultado predeterminado: documento.fscrypt
109
+
110
+ manager.file.decrypt(source.with_name("documento.fscrypt"))
111
+ # Resultado: documento.txt
112
+ ```
113
+
114
+ > **Importante:** el cifrado y descifrado de archivos son transformaciones del filesystem, no operaciones de copia. La librería no conserva automáticamente una segunda copia del recurso original. Realiza y verifica un backup antes de usarla con datos importantes.
115
+
116
+ ## Manual de la API
117
+
118
+ ### 1. Generar una MasterKey
119
+
120
+ `generate()` crea una MasterKey y devuelve su representación canónica como cadena Base64.
121
+
122
+ ```python
123
+ import fscryptography
124
+
125
+ master_key: str = fscryptography.generate()
126
+ ```
127
+
128
+ La cadena Base64 representa un contenedor de keysets, no una clave AES plana. Base64 es codificación, no cifrado: protege el valor como cualquier otro secreto.
129
+
130
+ ### 2. Proteger la MasterKey con contraseña
131
+
132
+ Puedes generar el contenedor protegido mediante una contraseña:
133
+
134
+ ```python
135
+ import fscryptography
136
+
137
+ password = obtain_password_from_secure_input()
138
+ master_key = fscryptography.generate(password=password)
139
+
140
+ with fscryptography.Manager(
141
+ key=master_key,
142
+ password=password,
143
+ ) as manager:
144
+ manager.file.encrypt("confidencial.pdf")
145
+ ```
146
+
147
+ La contraseña se utiliza al abrir el contenedor y no se conserva dentro de `Manager`. Para volver a abrir una MasterKey protegida necesitarás tanto el contenedor como la contraseña correcta. La contraseña no sustituye el backup del contenedor.
148
+
149
+ La función `obtain_password_from_secure_input()` es ilustrativa: debe sustituirse por el mecanismo seguro de entrada o recuperación de secretos de tu aplicación.
150
+
151
+ ### 3. Crear y administrar el contexto
152
+
153
+ `Manager` valida y abre el contenedor MasterKey. Mantiene las primitivas criptográficas preparadas para las operaciones posteriores.
154
+
155
+ ```python
156
+ password = obtain_password_from_secure_input()
157
+
158
+ with fscryptography.Manager(
159
+ key=master_key,
160
+ password=password,
161
+ ) as manager:
162
+ manager.file.encrypt("informe.txt")
163
+ ```
164
+
165
+ Se recomienda el administrador de contexto:
166
+
167
+ ```python
168
+ plain_master_key = fscryptography.generate()
169
+
170
+ with fscryptography.Manager(key=plain_master_key) as manager:
171
+ manager.file.encrypt("informe.txt")
172
+ ```
173
+
174
+ Al salir del bloque, `close()` invalida el gestor y libera sus referencias al material criptográfico. Python no garantiza el borrado seguro de todas las copias de secretos en memoria.
175
+
176
+ ### 4. Cifrar archivos
177
+
178
+ ```python
179
+ from pathlib import Path
180
+
181
+ password = obtain_password_from_secure_input()
182
+
183
+ with fscryptography.Manager(
184
+ key=master_key,
185
+ password=password,
186
+ ) as manager:
187
+ # Salida predeterminada: reporte.fscrypt
188
+ manager.file.encrypt(Path("reporte.txt"))
189
+
190
+ # Extensión de salida personalizada: backup.tar.locked
191
+ manager.file.encrypt(
192
+ Path("backup.tar.gz"),
193
+ new_extension=".locked",
194
+ )
195
+
196
+ # Cadena vacía: salida sin extensión visible
197
+ manager.file.encrypt(
198
+ Path("datos.csv"),
199
+ new_extension="",
200
+ )
201
+ ```
202
+
203
+ Parámetros:
204
+
205
+ | Parámetro | Tipo | Comportamiento |
206
+ |---|---|---|
207
+ | `path` | `str \| os.PathLike[str]` | Ruta del archivo regular que se va a cifrar. |
208
+ | `new_extension` | `str \| None` | `None` usa `.fscrypt`; `""` no añade extensión; un sufijo como `.locked` la sustituye. |
209
+ | `encrypt_name` | `bool` | Si es `True`, cifra el nombre completo del archivo. |
210
+
211
+ Para cifrar también el nombre:
212
+
213
+ ```python
214
+ password = obtain_password_from_secure_input()
215
+
216
+ with fscryptography.Manager(
217
+ key=master_key,
218
+ password=password,
219
+ ) as manager:
220
+ manager.file.encrypt(
221
+ "informe-confidencial.txt",
222
+ encrypt_name=True,
223
+ )
224
+ ```
225
+
226
+ Cuando `encrypt_name=True`, no se puede especificar `new_extension`: el nombre completo se transforma mediante el codec de nombres.
227
+
228
+ ### 5. Descifrar archivos
229
+
230
+ ```python
231
+ password = obtain_password_from_secure_input()
232
+
233
+ with fscryptography.Manager(
234
+ key=master_key,
235
+ password=password,
236
+ ) as manager:
237
+ manager.file.decrypt("reporte.fscrypt")
238
+ ```
239
+
240
+ El nombre de salida se obtiene de los metadatos autenticados del archivo. Si el nombre también estaba cifrado, se restaura mediante el keyset independiente de nombres.
241
+
242
+ El contenido se publica únicamente después de completar la autenticación del flujo. Un archivo alterado, truncado o no autenticable no debe tratarse como plaintext válido.
243
+
244
+ ### 6. Cifrar y descifrar directorios
245
+
246
+ Las operaciones de directorio transforman **exclusivamente el nombre del directorio**. No recorren, cifran ni descifran los archivos que contiene.
247
+
248
+ ```python
249
+ from pathlib import Path
250
+
251
+ directory = Path("proyecto-privado")
252
+
253
+ password = obtain_password_from_secure_input()
254
+
255
+ with fscryptography.Manager(
256
+ key=master_key,
257
+ password=password,
258
+ ) as manager:
259
+ # Captura las entradas existentes antes de la transformación.
260
+ # Ejecuta este ejemplo sin modificaciones concurrentes en el padre.
261
+ parent = directory.parent
262
+ previous_entries = {item.name for item in parent.iterdir()}
263
+
264
+ manager.dir.encrypt(directory)
265
+
266
+ # La API transforma el nombre in-place y devuelve None.
267
+ # Identifica la nueva entrada comparando el estado anterior y posterior.
268
+ new_entries = [
269
+ item
270
+ for item in parent.iterdir()
271
+ if item.name not in previous_entries
272
+ and not item.name.startswith(".fscryptography-txn-")
273
+ ]
274
+ if len(new_entries) != 1:
275
+ raise RuntimeError(
276
+ "No se pudo identificar de forma inequívoca el directorio cifrado"
277
+ )
278
+
279
+ encrypted_directory = new_entries[0]
280
+ manager.dir.decrypt(encrypted_directory)
281
+ # Restaura el nombre original.
282
+ ```
283
+
284
+ Para proteger el contenido de un árbol de directorios, cada archivo debe procesarse explícitamente mediante la API de archivos y debe diseñarse una estrategia de recorrido y recuperación en la aplicación consumidora.
285
+
286
+ ### 7. Cambiar y exportar la MasterKey
287
+
288
+ `change_key()` abre y valida la nueva clave antes de reemplazar el contexto activo. Si la apertura falla, el contexto anterior permanece activo.
289
+
290
+ ```python
291
+ new_key = fscryptography.generate()
292
+ current_password = obtain_password_from_secure_input()
293
+
294
+ with fscryptography.Manager(
295
+ key=master_key,
296
+ password=current_password,
297
+ ) as manager:
298
+ manager.change_key(new_key)
299
+
300
+ exported_key: str = manager.export_key()
301
+ ```
302
+
303
+ **Importante:** `change_key()` solo cambia la clave utilizada por operaciones nuevas. No vuelve a cifrar archivos existentes ni migra sus nombres. Cada recurso sigue requiriendo la MasterKey con la que fue cifrado; conserva las claves anteriores mientras existan recursos que dependan de ellas.
304
+
305
+ Para cambiar a un contenedor protegido por contraseña:
306
+
307
+ ```python
308
+ current_password = obtain_password_from_secure_input()
309
+ new_password = obtain_password_from_secure_input()
310
+ protected_key = fscryptography.generate(password=new_password)
311
+
312
+ with fscryptography.Manager(
313
+ key=master_key,
314
+ password=current_password,
315
+ ) as manager:
316
+ manager.change_key(
317
+ protected_key,
318
+ password=new_password,
319
+ )
320
+ ```
321
+
322
+ `export_key()` devuelve la MasterKey activa en Base64 estándar. Trata el valor exportado como un secreto de máxima sensibilidad.
323
+
324
+ ### 8. Comportamiento ante interrupciones
325
+
326
+ El estado transaccional existe únicamente en memoria durante la operación. La librería no crea journals, directorios de transacción ni ofrece inspección o recuperación automática después de una interrupción.
327
+
328
+ Para procesar archivos grandes mediante streaming se utilizan temporales de resultado en el mismo directorio padre. La retirada segura del origen utiliza temporalmente un nombre hermano aleatorio. Si el proceso termina abruptamente o el equipo pierde energía, estos elementos pueden quedar en el filesystem; no existe un mecanismo de recuperación que los identifique, valide o elimine automáticamente. El consumidor debe inspeccionar el directorio y determinar manualmente qué conservar o eliminar. No borres un temporal sin verificar primero su contenido e identidad.
329
+
330
+ En ejecución normal, la limpieza de temporales de resultado se intenta al cerrar la operación. Un fallo de retirada del origen puede dejar un temporal hermano que contiene el recurso original; el resultado publicado también puede permanecer. Conserva backups y no interpretes la presencia de ambos archivos como una transacción recuperable.
331
+
332
+ fscryptography no promete rollback, recuperación tras crash ni ausencia absoluta de residuos en apagones.
333
+
334
+
335
+ ### 9. Excepciones
336
+
337
+ Las excepciones propias se exportan desde el paquete raíz y derivan de `FsCryptographyError`.
338
+
339
+ | Excepción | Significado |
340
+ |---|---|
341
+ | `FsCryptographyError` | Clase base de errores propios. |
342
+ | `AuthenticationError` | Fallo de autenticación de contenido o contenedor protegido. |
343
+ | `FormatError` | Formato, cabecera o estructura no válida. |
344
+ | `UnsupportedFormatVersionError` | Versión no admitida. |
345
+ | `InvalidPathError` | Ruta no utilizable o identidad de recurso alterada durante el inicio. |
346
+ | `UnsupportedResourceError` | Tipo de recurso no admitido, por ejemplo un enlace simbólico. |
347
+ | `DestinationConflictError` | El destino ya existe; no se sobrescribe por defecto. |
348
+ | `NameConstraintError` | Nombre no representable o fuera de los límites aplicables. |
349
+ | `KeyDerivationError` | Fallo operativo al derivar una clave. |
350
+ | `BackendError` | Fallo inesperado de integración criptográfica. |
351
+ | `ClosedInstanceError` | Se intentó usar un gestor cerrado. |
352
+ | `AtomicOperationError` | No se pudo asegurar el estado esperado durante la operación. |
353
+
354
+ Los errores ordinarios del sistema de archivos pueden conservar excepciones estándar como `FileNotFoundError`, `FileExistsError`, `PermissionError` y `OSError`. Los errores de argumentos pueden ser `TypeError` o `ValueError`.
355
+
356
+ Para el contrato completo y las reglas de clasificación, consulta [docs/errors.md](docs/errors.md).
357
+
358
+ ## Arquitectura
359
+
360
+ La API pública mantiene separado el ciclo de vida de claves, las operaciones de filesystem, el formato y el backend criptográfico.
361
+
362
+ <div align="center">
363
+ <img src="assets/fscryptography-architecture.svg" alt="Arquitectura lógica de fscryptography" width="100%">
364
+ </div>
365
+
366
+ Flujo simplificado de una transformación de archivo:
367
+
368
+ 1. Validación de ruta, tipo de recurso y destino.
369
+ 2. Creación de un temporal exclusivo en el mismo filesystem.
370
+ 3. Escritura de cabecera y procesamiento Streaming AEAD por segmentos.
371
+ 4. Finalización y sincronización del temporal.
372
+ 5. Publicación sin reemplazar un destino existente.
373
+ 6. Retiro del origen y sincronización del namespace cuando la plataforma lo permite.
374
+
375
+ La implementación no debe publicar plaintext parcial como resultado definitivo. La semántica de durabilidad y las garantías de operaciones del filesystem dependen de la plataforma.
376
+
377
+
378
+ ## Evidencia de ejecución real
379
+
380
+ La siguiente lámina resume una ejecución manual reportada en **Ubuntu 24.04, Linux x86_64 y Python 3.12.3**. Se han censurado la ruta de trabajo y los identificadores del entorno. Es una **reconstrucción vectorial de la salida y los resultados**, no una captura binaria del terminal original.
381
+
382
+ <div align="center">
383
+ <img src="assets/manual-test-ubuntu-24.04.svg" alt="Resumen visual censurado de la prueba manual de fscryptography en Ubuntu 24.04: 15 de 16 comprobaciones correctas" width="100%">
384
+ </div>
385
+
386
+ **Resultado informado: 15/16 comprobaciones correctas (93,75 %).** Las operaciones de cifrado y descifrado verificadas conservaron la integridad de los datos mediante SHA-256, incluidos archivos de hasta 1 MiB. La única comprobación fallida fue una invocación incompatible de la API: se pasó `new_extension` junto con `encrypt_name=True`, combinación que la API rechaza intencionalmente. Para cifrar el nombre se debe omitir `new_extension`.
387
+
388
+ Esta evidencia documenta una ejecución en un entorno concreto; no sustituye las pruebas automatizadas, las pruebas de endurecimiento ni la validación multiplataforma. No se muestran claves, contraseñas, contenido privado ni rutas personales.
389
+
390
+ ## Diseño criptográfico
391
+
392
+ | Dominio | Tecnología | Uso |
393
+ |---|---|---|
394
+ | Contenido | Tink Streaming AEAD · `AES256_GCM_HKDF_1MB` | Cifrado autenticado y segmentado de archivos. |
395
+ | Nombres | Tink AEAD · `AES256_GCM` | Protección de nombres de archivos y directorios. |
396
+ | Protección de MasterKey | Argon2id + AES-256-GCM | Protección opcional del contenedor mediante contraseña. |
397
+
398
+ Los keysets de contenido y nombres son independientes. La generación de nonces y las primitivas AEAD se delegan al backend seleccionado; la librería no implementa algoritmos criptográficos propios.
399
+
400
+ ## Compatibilidad y estado
401
+
402
+ - Python: requisito declarado `>=3.11`.
403
+ - Objetivos declarados: Windows 11 y GNU/Linux (Ubuntu 22.04/24.04 LTS), x86-64; Python 3.11–3.13.
404
+ - Integración filesystem validada en CI sobre Ubuntu 22.04.5/24.04.5 con ext4 y Windows Server 2025 Datacenter (build 26100) con NTFS.
405
+ - Windows 11 cliente todavía requiere validación específica; Windows Server 2025 no se presenta como sustituto de esa prueba.
406
+ - La matriz CI valida los runners y opciones de filesystem observados, no todas las versiones de kernel, dispositivos, configuraciones de montaje ni condiciones de pérdida de energía.
407
+
408
+ Consulta [docs/platform-compatibility.md](docs/platform-compatibility.md) para ver los entornos exactos, opciones de montaje y límites de extrapolación.
409
+
410
+ ## Seguridad
411
+
412
+ Esta librería manipula claves criptográficas y recursos del usuario. Antes de integrarla en un flujo sensible:
413
+
414
+ - Lee el [modelo de seguridad](docs/security-model.md) y la [política de reporte de vulnerabilidades](SECURITY.md).
415
+ - Define un procedimiento de backup y recuperación de MasterKey.
416
+ - Protege la MasterKey y, cuando aplique, su contraseña fuera del árbol cifrado.
417
+ - Prueba primero con datos desechables y verifica el resultado.
418
+ - No ejecutes operaciones destructivas sin backups recuperables.
419
+ - No asumas protección frente a malware, procesos privilegiados o procesos hostiles bajo el mismo usuario.
420
+ - No interpretes el cifrado como protección de metadatos: tamaños, cantidad de archivos, permisos, timestamps y patrones de acceso pueden seguir expuestos.
421
+ - Las operaciones de archivo rechazan recursos con hard links múltiples y crean resultados nuevos; no preservan automáticamente permisos, propietario, ACL, timestamps, xattrs ni alternate data streams. Consulta el [contrato de metadatos y enlaces](docs/atomic-operations.md#enlaces-duros-y-contrato-de-metadatos-fase-de-endurecimiento).
422
+
423
+ **La implementación y sus pruebas automatizadas no equivalen a una auditoría criptográfica independiente.** No se garantiza borrado seguro de secretos en memoria Python ni durabilidad uniforme en todos los filesystems.
424
+
425
+ ## Documentación técnica
426
+
427
+ La documentación normativa y de diseño se mantiene separada del manual de uso:
428
+
429
+ - [Prueba de integración de 100 archivos](docs/100-files-roundtrip.md)
430
+ - [Índice de documentación](docs/index.md)
431
+ - [Versionado y compatibilidad](docs/versioning.md)
432
+ - [Historial de cambios](CHANGELOG.md)
433
+ - [Contrato de API](docs/api-reference.md)
434
+ - [Arquitectura](docs/architecture.md)
435
+ - [Diseño criptográfico](docs/cryptographic-design.md)
436
+ - [Formato de archivos](docs/file-format.md)
437
+ - [Formato MasterKey](docs/master-key-format.md)
438
+ - [Gestión de claves](docs/key-management.md)
439
+ - [Política Argon2id](docs/argon2id-policy.md)
440
+ - [Cifrado de nombres](docs/filename-encryption.md)
441
+ - [Operaciones transaccionales y límites ante interrupciones](docs/atomic-operations.md)
442
+ - [Errores y excepciones](docs/errors.md)
443
+ - [Modelo de seguridad](docs/security-model.md)
444
+ - [Política de seguridad y reporte de vulnerabilidades](SECURITY.md)
445
+ - [Compatibilidad de plataformas](docs/platform-compatibility.md)
446
+ - [Construcción y publicación](docs/releasing.md)
447
+ - [Decisión de arquitectura inicial](docs/decisions/0001-initial-design.md)
448
+
449
+ ## Desarrollo
450
+
451
+ Clona el repositorio e instala dependencias de desarrollo:
452
+
453
+ ```bash
454
+ git clone https://github.com/specter327/fscryptography.git
455
+ cd fscryptography
456
+ python -m pip install -e ".[dev]"
457
+ ```
458
+
459
+ Ejecuta las pruebas:
460
+
461
+ ```bash
462
+ python -m pytest
463
+ ```
464
+
465
+ Construye y valida los artefactos:
466
+
467
+ ```bash
468
+ python -m build
469
+ python -m twine check dist/*
470
+ ```
471
+
472
+ ## Licencia y derechos de uso
473
+
474
+ **Software propietario — todos los derechos reservados.**
475
+
476
+ No se concede una licencia pública para usar, copiar, modificar o redistribuir este software. Cualquier autorización requiere permiso previo y expreso por escrito del titular de los derechos.
477
+
478
+ La disponibilidad del código fuente en GitHub o del paquete en PyPI no implica la concesión de derechos adicionales. Consulta [LICENSE](LICENSE).
479
+
480
+ ---
481
+
482
+ <div align="center">
483
+
484
+ **fscryptography** · filesystem-oriented authenticated encryption
485
+
486
+ [GitHub](https://github.com/specter327/fscryptography) · [PyPI](https://pypi.org/project/fscryptography/) · [Documentación](docs/index.md) · [Issues](https://github.com/specter327/fscryptography/issues)
487
+
488
+ </div>