fscryptography 0.1.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 (45) hide show
  1. fscryptography-0.1.0/LICENSE +25 -0
  2. fscryptography-0.1.0/MANIFEST.in +3 -0
  3. fscryptography-0.1.0/PKG-INFO +168 -0
  4. fscryptography-0.1.0/README.md +133 -0
  5. fscryptography-0.1.0/docs/api-reference.md +108 -0
  6. fscryptography-0.1.0/docs/architecture.md +46 -0
  7. fscryptography-0.1.0/docs/argon2id-benchmark.md +134 -0
  8. fscryptography-0.1.0/docs/argon2id-policy.md +109 -0
  9. fscryptography-0.1.0/docs/atomic-operations.md +72 -0
  10. fscryptography-0.1.0/docs/backend-validation.md +175 -0
  11. fscryptography-0.1.0/docs/cryptographic-design.md +39 -0
  12. fscryptography-0.1.0/docs/decisions/0001-initial-design.md +42 -0
  13. fscryptography-0.1.0/docs/errors.md +82 -0
  14. fscryptography-0.1.0/docs/file-format.md +156 -0
  15. fscryptography-0.1.0/docs/filename-encryption.md +149 -0
  16. fscryptography-0.1.0/docs/filesystem-hardening.md +86 -0
  17. fscryptography-0.1.0/docs/index.md +29 -0
  18. fscryptography-0.1.0/docs/key-management.md +66 -0
  19. fscryptography-0.1.0/docs/master-key-format-test-plan.md +108 -0
  20. fscryptography-0.1.0/docs/master-key-format.md +205 -0
  21. fscryptography-0.1.0/docs/platform-compatibility.md +147 -0
  22. fscryptography-0.1.0/docs/recovery-journal.md +165 -0
  23. fscryptography-0.1.0/docs/releasing.md +82 -0
  24. fscryptography-0.1.0/docs/scope.md +26 -0
  25. fscryptography-0.1.0/docs/security-model.md +28 -0
  26. fscryptography-0.1.0/pyproject.toml +65 -0
  27. fscryptography-0.1.0/setup.cfg +4 -0
  28. fscryptography-0.1.0/src/fscryptography/__init__.py +41 -0
  29. fscryptography-0.1.0/src/fscryptography/_directory.py +99 -0
  30. fscryptography-0.1.0/src/fscryptography/_filesystem.py +671 -0
  31. fscryptography-0.1.0/src/fscryptography/_journal.py +493 -0
  32. fscryptography-0.1.0/src/fscryptography/_master_key.py +294 -0
  33. fscryptography-0.1.0/src/fscryptography/crypto.py +89 -0
  34. fscryptography-0.1.0/src/fscryptography/errors.py +52 -0
  35. fscryptography-0.1.0/src/fscryptography/file_format.py +178 -0
  36. fscryptography-0.1.0/src/fscryptography/names/__init__.py +16 -0
  37. fscryptography-0.1.0/src/fscryptography/names/codec.py +116 -0
  38. fscryptography-0.1.0/src/fscryptography/names/tink_backend.py +28 -0
  39. fscryptography-0.1.0/src/fscryptography/names/validation.py +84 -0
  40. fscryptography-0.1.0/src/fscryptography/py.typed +0 -0
  41. fscryptography-0.1.0/src/fscryptography.egg-info/PKG-INFO +168 -0
  42. fscryptography-0.1.0/src/fscryptography.egg-info/SOURCES.txt +43 -0
  43. fscryptography-0.1.0/src/fscryptography.egg-info/dependency_links.txt +1 -0
  44. fscryptography-0.1.0/src/fscryptography.egg-info/requires.txt +11 -0
  45. fscryptography-0.1.0/src/fscryptography.egg-info/top_level.txt +1 -0
@@ -0,0 +1,25 @@
1
+ Copyright (c) 2026 Specter327. All rights reserved.
2
+
3
+ PROPRIETARY SOFTWARE — ALL RIGHTS RESERVED
4
+
5
+ This software, including its source code, documentation, and associated
6
+ materials (the "Software"), is proprietary and is protected by applicable
7
+ copyright and other intellectual property laws.
8
+
9
+ No license or other permission is granted, expressly or by implication, to
10
+ any person to use, reproduce, modify, adapt, translate, publish, distribute,
11
+ sublicense, sell, rent, publicly display, publicly perform, or create
12
+ derivative works of the Software, in whole or in part.
13
+
14
+ Access to, viewing of, or possession of a copy of the Software does not
15
+ constitute permission to exercise any of the rights listed above. Any use,
16
+ copying, modification, or distribution requires the prior express written
17
+ authorization of the copyright holder, unless such activity is permitted
18
+ under applicable mandatory law.
19
+
20
+ To request a separate license or written authorization, contact the
21
+ copyright holder through the repository's official communication channels.
22
+
23
+ THE SOFTWARE IS PROVIDED "AS IS", TO THE MAXIMUM EXTENT PERMITTED BY
24
+ APPLICABLE LAW. THE COPYRIGHT HOLDER DISCLAIMS ALL WARRANTIES AND
25
+ LIABILITY TO THE EXTENT PERMITTED BY LAW.
@@ -0,0 +1,3 @@
1
+ include LICENSE
2
+ include README.md
3
+ recursive-include docs *.md
@@ -0,0 +1,168 @@
1
+ Metadata-Version: 2.4
2
+ Name: fscryptography
3
+ Version: 0.1.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/releases
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
+ Provides-Extra: dev
31
+ Requires-Dist: build<2,>=1.2; extra == "dev"
32
+ Requires-Dist: pytest<9,>=8; extra == "dev"
33
+ Requires-Dist: twine<7,>=5; extra == "dev"
34
+ Dynamic: license-file
35
+
36
+ # fscryptography
37
+
38
+ **fscryptography** (*filesystem-cryptography*) es una librería Python para cifrar y descifrar archivos y nombres de archivos y directorios directamente sobre rutas del sistema de archivos.
39
+
40
+ Proporciona una API de alto nivel basada en rutas, cifrado autenticado y procesamiento segmentado para archivos grandes. No depende de herramientas de exploración de recursos ni de aplicaciones concretas.
41
+
42
+ ## Instalación
43
+
44
+ Requiere Python 3.11 o posterior.
45
+
46
+ ```bash
47
+ python -m pip install fscryptography
48
+ ```
49
+
50
+ ## Inicio rápido
51
+
52
+ ```python
53
+ from pathlib import Path
54
+
55
+ import fscryptography
56
+
57
+ # Genera una clave maestra aleatoria codificada en Base64.
58
+ master_key = fscryptography.generate()
59
+
60
+ # Guarda la clave de forma segura fuera del directorio que se cifra.
61
+ # Quien obtenga la clave podrá descifrar los recursos protegidos.
62
+
63
+ with fscryptography.Manager(key=master_key) as manager:
64
+ manager.file.encrypt(Path("document.txt"))
65
+ manager.file.decrypt(Path("document.fscrypt"))
66
+ ```
67
+
68
+ Para proteger el contenedor de clave maestra con contraseña:
69
+
70
+ ```python
71
+ master_key = fscryptography.generate(password="correct horse battery staple")
72
+
73
+ with fscryptography.Manager(
74
+ key=master_key,
75
+ password="correct horse battery staple",
76
+ ) as manager:
77
+ manager.file.encrypt("confidential.pdf", encrypt_name=True)
78
+ ```
79
+
80
+ La contraseña se consume al abrir el contenedor y no se conserva en el gestor. No debe confundirse la contraseña con una copia de seguridad de la clave: conserva la cadena Base64 de la MasterKey en un lugar seguro.
81
+
82
+ ## API principal
83
+
84
+ ```python
85
+ import fscryptography
86
+
87
+ master_key = fscryptography.generate()
88
+ # O bien: fscryptography.generate(password="...")
89
+
90
+ manager = fscryptography.Manager(key=master_key)
91
+ # Para una MasterKey protegida: Manager(key=master_key, password="...")
92
+
93
+ manager.file.encrypt("report.txt")
94
+ manager.file.encrypt("archive.tar.gz", new_extension=".locked")
95
+ manager.file.encrypt("private.txt", encrypt_name=True)
96
+ manager.file.decrypt("report.fscrypt")
97
+
98
+ manager.dir.encrypt("private-directory")
99
+ manager.dir.decrypt("~1...")
100
+
101
+ records = manager.inspect_recovery("/path/to/parent") # Inspección de solo lectura
102
+ exported_key = manager.export_key()
103
+ manager.close()
104
+ ```
105
+
106
+ Las operaciones de directorio transforman exclusivamente el nombre del directorio: **no recorren ni cifran su contenido**. La librería no ofrece una API pública de cifrado genérico de bytes o streams.
107
+
108
+ ## Diseño criptográfico
109
+
110
+ - Google Tink para Streaming AEAD de contenido (`AES256_GCM_HKDF_1MB`) y AEAD de nombres (`AES256_GCM`).
111
+ - Argon2id y AES-256-GCM para proteger una MasterKey cuando se especifica contraseña.
112
+ - Keysets independientes para contenido y nombres.
113
+ - Formatos versionados y metadata de archivo autenticada.
114
+ - Operaciones de filesystem diseñadas para evitar sobrescrituras accidentales y preservar información de transacciones interrumpidas.
115
+
116
+ ## Compatibilidad y límites
117
+
118
+ - Python 3.11+.
119
+ - GNU/Linux y Windows.
120
+ - En GNU/Linux se utilizan operaciones relativas a descriptores de directorio y publicación no-replace cuando el sistema las soporta.
121
+ - En Windows existen diferencias documentadas: no se ofrece el mismo anclaje de directorio ni la misma garantía de cuarentena del origen.
122
+ - No se garantiza protección frente a procesos hostiles que operen bajo el mismo UID/usuario.
123
+ - Las semánticas de durabilidad y renombrado de sistemas de archivos alternativos o de red no están validadas exhaustivamente.
124
+
125
+ La inspección del journal es explícita y de solo lectura. No hay recuperación destructiva ni limpieza automática de transacciones completadas.
126
+
127
+ ## Seguridad
128
+
129
+ Esta librería manipula claves criptográficas y archivos del usuario. Revisa el [modelo de seguridad](docs/security-model.md), la [política de gestión de claves](docs/key-management.md), la [compatibilidad de plataformas](docs/platform-compatibility.md) y la [documentación técnica](docs/index.md) antes de integrarla en un flujo sensible.
130
+
131
+ La protección criptográfica no sustituye las copias de seguridad, el control de acceso del sistema operativo ni una política de gestión y rotación de claves. La implementación y sus pruebas automatizadas no equivalen a una auditoría criptográfica independiente.
132
+
133
+ ## Licencia y derechos de uso
134
+
135
+ Este proyecto es software propietario y se distribuye bajo una política de **todos los derechos reservados**. No se concede una licencia pública para usar, copiar, modificar o redistribuir el software. Cualquier autorización requiere permiso previo y expreso por escrito del titular de los derechos.
136
+
137
+ Consulta el archivo [LICENSE](LICENSE). La disponibilidad del código fuente en GitHub o de un paquete en PyPI no implica la concesión de derechos adicionales.
138
+
139
+ ## Desarrollo
140
+
141
+ Instala las dependencias de desarrollo:
142
+
143
+ ```bash
144
+ python -m pip install -e ".[dev]"
145
+ ```
146
+
147
+ Ejecuta las pruebas:
148
+
149
+ ```bash
150
+ python -m pytest
151
+ ```
152
+
153
+ Construye y valida los artefactos de distribución:
154
+
155
+ ```bash
156
+ python -m build
157
+ python -m twine check dist/*
158
+ ```
159
+
160
+ El proyecto utiliza un diseño `src/` y publica un wheel y un source distribution (sdist). La publicación a PyPI se automatiza mediante GitHub Actions y Trusted Publishing (OIDC); no requiere almacenar un token PyPI de larga duración en los secretos del repositorio.
161
+
162
+ ## Estado
163
+
164
+ Versión inicial de distribución: **0.1.0**. El proyecto continúa en fase alpha. Consulta [GitHub Releases](https://github.com/specter327/fscryptography/releases) para conocer las versiones publicadas y sus notas.
165
+
166
+ ## Documentación
167
+
168
+ La documentación normativa y técnica está en [docs/](docs/index.md). El [contrato de API](docs/api-reference.md) describe las operaciones, retornos y excepciones.
@@ -0,0 +1,133 @@
1
+ # fscryptography
2
+
3
+ **fscryptography** (*filesystem-cryptography*) es una librería Python para cifrar y descifrar archivos y nombres de archivos y directorios directamente sobre rutas del sistema de archivos.
4
+
5
+ Proporciona una API de alto nivel basada en rutas, cifrado autenticado y procesamiento segmentado para archivos grandes. No depende de herramientas de exploración de recursos ni de aplicaciones concretas.
6
+
7
+ ## Instalación
8
+
9
+ Requiere Python 3.11 o posterior.
10
+
11
+ ```bash
12
+ python -m pip install fscryptography
13
+ ```
14
+
15
+ ## Inicio rápido
16
+
17
+ ```python
18
+ from pathlib import Path
19
+
20
+ import fscryptography
21
+
22
+ # Genera una clave maestra aleatoria codificada en Base64.
23
+ master_key = fscryptography.generate()
24
+
25
+ # Guarda la clave de forma segura fuera del directorio que se cifra.
26
+ # Quien obtenga la clave podrá descifrar los recursos protegidos.
27
+
28
+ with fscryptography.Manager(key=master_key) as manager:
29
+ manager.file.encrypt(Path("document.txt"))
30
+ manager.file.decrypt(Path("document.fscrypt"))
31
+ ```
32
+
33
+ Para proteger el contenedor de clave maestra con contraseña:
34
+
35
+ ```python
36
+ master_key = fscryptography.generate(password="correct horse battery staple")
37
+
38
+ with fscryptography.Manager(
39
+ key=master_key,
40
+ password="correct horse battery staple",
41
+ ) as manager:
42
+ manager.file.encrypt("confidential.pdf", encrypt_name=True)
43
+ ```
44
+
45
+ La contraseña se consume al abrir el contenedor y no se conserva en el gestor. No debe confundirse la contraseña con una copia de seguridad de la clave: conserva la cadena Base64 de la MasterKey en un lugar seguro.
46
+
47
+ ## API principal
48
+
49
+ ```python
50
+ import fscryptography
51
+
52
+ master_key = fscryptography.generate()
53
+ # O bien: fscryptography.generate(password="...")
54
+
55
+ manager = fscryptography.Manager(key=master_key)
56
+ # Para una MasterKey protegida: Manager(key=master_key, password="...")
57
+
58
+ manager.file.encrypt("report.txt")
59
+ manager.file.encrypt("archive.tar.gz", new_extension=".locked")
60
+ manager.file.encrypt("private.txt", encrypt_name=True)
61
+ manager.file.decrypt("report.fscrypt")
62
+
63
+ manager.dir.encrypt("private-directory")
64
+ manager.dir.decrypt("~1...")
65
+
66
+ records = manager.inspect_recovery("/path/to/parent") # Inspección de solo lectura
67
+ exported_key = manager.export_key()
68
+ manager.close()
69
+ ```
70
+
71
+ Las operaciones de directorio transforman exclusivamente el nombre del directorio: **no recorren ni cifran su contenido**. La librería no ofrece una API pública de cifrado genérico de bytes o streams.
72
+
73
+ ## Diseño criptográfico
74
+
75
+ - Google Tink para Streaming AEAD de contenido (`AES256_GCM_HKDF_1MB`) y AEAD de nombres (`AES256_GCM`).
76
+ - Argon2id y AES-256-GCM para proteger una MasterKey cuando se especifica contraseña.
77
+ - Keysets independientes para contenido y nombres.
78
+ - Formatos versionados y metadata de archivo autenticada.
79
+ - Operaciones de filesystem diseñadas para evitar sobrescrituras accidentales y preservar información de transacciones interrumpidas.
80
+
81
+ ## Compatibilidad y límites
82
+
83
+ - Python 3.11+.
84
+ - GNU/Linux y Windows.
85
+ - En GNU/Linux se utilizan operaciones relativas a descriptores de directorio y publicación no-replace cuando el sistema las soporta.
86
+ - En Windows existen diferencias documentadas: no se ofrece el mismo anclaje de directorio ni la misma garantía de cuarentena del origen.
87
+ - No se garantiza protección frente a procesos hostiles que operen bajo el mismo UID/usuario.
88
+ - Las semánticas de durabilidad y renombrado de sistemas de archivos alternativos o de red no están validadas exhaustivamente.
89
+
90
+ La inspección del journal es explícita y de solo lectura. No hay recuperación destructiva ni limpieza automática de transacciones completadas.
91
+
92
+ ## Seguridad
93
+
94
+ Esta librería manipula claves criptográficas y archivos del usuario. Revisa el [modelo de seguridad](docs/security-model.md), la [política de gestión de claves](docs/key-management.md), la [compatibilidad de plataformas](docs/platform-compatibility.md) y la [documentación técnica](docs/index.md) antes de integrarla en un flujo sensible.
95
+
96
+ La protección criptográfica no sustituye las copias de seguridad, el control de acceso del sistema operativo ni una política de gestión y rotación de claves. La implementación y sus pruebas automatizadas no equivalen a una auditoría criptográfica independiente.
97
+
98
+ ## Licencia y derechos de uso
99
+
100
+ Este proyecto es software propietario y se distribuye bajo una política de **todos los derechos reservados**. No se concede una licencia pública para usar, copiar, modificar o redistribuir el software. Cualquier autorización requiere permiso previo y expreso por escrito del titular de los derechos.
101
+
102
+ Consulta el archivo [LICENSE](LICENSE). La disponibilidad del código fuente en GitHub o de un paquete en PyPI no implica la concesión de derechos adicionales.
103
+
104
+ ## Desarrollo
105
+
106
+ Instala las dependencias de desarrollo:
107
+
108
+ ```bash
109
+ python -m pip install -e ".[dev]"
110
+ ```
111
+
112
+ Ejecuta las pruebas:
113
+
114
+ ```bash
115
+ python -m pytest
116
+ ```
117
+
118
+ Construye y valida los artefactos de distribución:
119
+
120
+ ```bash
121
+ python -m build
122
+ python -m twine check dist/*
123
+ ```
124
+
125
+ El proyecto utiliza un diseño `src/` y publica un wheel y un source distribution (sdist). La publicación a PyPI se automatiza mediante GitHub Actions y Trusted Publishing (OIDC); no requiere almacenar un token PyPI de larga duración en los secretos del repositorio.
126
+
127
+ ## Estado
128
+
129
+ Versión inicial de distribución: **0.1.0**. El proyecto continúa en fase alpha. Consulta [GitHub Releases](https://github.com/specter327/fscryptography/releases) para conocer las versiones publicadas y sus notas.
130
+
131
+ ## Documentación
132
+
133
+ La documentación normativa y técnica está en [docs/](docs/index.md). El [contrato de API](docs/api-reference.md) describe las operaciones, retornos y excepciones.
@@ -0,0 +1,108 @@
1
+ # API pública
2
+
3
+ ## Principios
4
+
5
+ La API opera sobre rutas del filesystem. No expone cifrado general de bytes ni streams suministrados por el consumidor. La clave maestra se representa públicamente como texto Base64 estándar y se decodifica a bytes al entrar en la librería.
6
+
7
+ ## Generación de clave maestra
8
+
9
+ import fscryptography
10
+
11
+ # Generación aleatoria
12
+ master_key = fscryptography.generate()
13
+
14
+ # Generación de keysets protegidos por contraseña
15
+ master_key = fscryptography.generate(password="passphrase")
16
+
17
+ Ambas variantes devuelven una cadena Base64 canónica. La cadena representa el contenedor autocontenido MasterKey; no representa una clave AES plana. La variante con contraseña protege el contenedor mediante Argon2id y AES-256-GCM.
18
+
19
+ ## Gestor y contexto criptográfico
20
+
21
+ manager = fscryptography.Manager(key=master_key)
22
+
23
+ # Para un contenedor protegido:
24
+ manager = fscryptography.Manager(
25
+ key=master_key,
26
+ password="passphrase",
27
+ )
28
+
29
+ with fscryptography.Manager(key=master_key) as manager:
30
+ ...
31
+
32
+ El gestor decodifica Base64 a bytes, valida y abre el contenedor una sola vez, y conserva en su contexto las primitivas Tink independientes para contenido y nombres. Las operaciones posteriores reutilizan ese contexto; no reciben la clave en cada llamada.
33
+
34
+ Si el contenedor fue generado con password=..., la contraseña debe suministrarse al construir el gestor. La contraseña se consume durante la apertura y no se conserva en el objeto. Esto es obligatorio para mantener el contrato MasterKey protegido ya aprobado; no es posible abrirlo únicamente con la cadena Base64.
35
+
36
+ ## Cambio y exportación de clave
37
+
38
+ manager.change_key(new_key)
39
+
40
+ # Para una nueva clave protegida:
41
+ manager.change_key(new_key, password="new passphrase")
42
+
43
+ exported_key: str = manager.export_key()
44
+
45
+ change_key() valida y abre completamente la nueva clave antes de sustituir el contexto activo. Si falla, el contexto anterior permanece intacto. export_key() devuelve la representación Base64 canónica de la clave activa.
46
+
47
+ ## Operaciones sobre recursos
48
+
49
+ # Nombre visible: salida document.fscrypt
50
+ manager.file.encrypt(path="document.txt")
51
+
52
+ # Extensión de salida personalizada o sin extensión
53
+ manager.file.encrypt(path="archive.tar.gz", new_extension=".locked")
54
+ manager.file.encrypt(path="secret.txt", new_extension="")
55
+
56
+ # El nombre completo se cifra con el keyset AEAD de nombres
57
+ manager.file.encrypt(path="private.txt", encrypt_name=True)
58
+
59
+ manager.file.decrypt(path="document.fscrypt")
60
+
61
+ # Los directorios solo transforman su propio nombre
62
+ manager.dir.encrypt(path="private-directory")
63
+ manager.dir.decrypt(path="~1...")
64
+
65
+ Las operaciones son métodos del contexto del gestor y reutilizan las primitivas abiertas. El cifrado de archivos utiliza Tink Streaming AEAD y la cabecera v1.0 autenticada como AAD. La extensión original y la de salida se guardan en metadata autenticada. `new_extension=None` selecciona `.fscrypt`; `""` elimina la extensión visible; un sufijo explícito como `.locked` la sustituye. Con `encrypt_name=True`, se cifra el nombre completo y `new_extension` debe ser `None`. Los directorios transforman exclusivamente su propio nombre; no recorren ni cifran su contenido.
66
+
67
+ ## Representación de claves
68
+
69
+ - Frontera pública: Base64 estándar ASCII (str).
70
+ - Interior de la librería: contenedor binario (bytes) y primitivas criptográficas abiertas.
71
+ - Exportación: serialización de los bytes internos a Base64 estándar.
72
+ - La codificación Base64 no es cifrado ni protección de secretos.
73
+
74
+ El gestor no conserva la contraseña. close() invalida el contexto y libera referencias a la clave y las primitivas; el borrado seguro de memoria no está garantizado por Python.
75
+
76
+ ## Retornos y errores
77
+
78
+ Las operaciones file.encrypt(), file.decrypt(), dir.encrypt() y dir.decrypt() devolverán None al completarse correctamente. Los fallos se comunicarán mediante excepciones tipadas; no se devolverá False como sustituto de una excepción.
79
+
80
+ Todas las excepciones propias derivan de FsCryptographyError. La jerarquía, la clasificación de fallos y la política de preservación de excepciones estándar se definen en [Errores y excepciones](errors.md).
81
+
82
+ Los errores de argumentos conservan TypeError o ValueError; los errores ordinarios del filesystem conservan las excepciones estándar de Python cuando sea posible. La contraseña incorrecta y la alteración de un contenedor protegido se presentan como AuthenticationError, sin distinguir públicamente ambos casos.
83
+
84
+ ## Inspección de operaciones interrumpidas
85
+
86
+ records = manager.inspect_recovery("/path/to/parent")
87
+
88
+ La llamada inspecciona exclusivamente los directorios `.fscryptography-txn-*` situados directamente bajo el directorio indicado. Devuelve una tupla inmutable de objetos `fscryptography.RecoveryRecord`. Las clasificaciones incluyen `prepared_no_output`, `result_incomplete_or_unverified`, `result_ready`, `published_source_present`, `published_source_missing`, `source_removed`, `ambiguous` y `corrupt`.
89
+
90
+ La inspección es de solo lectura y no requiere una clave abierta: no descifra ni autentica contenido. Los registros completados se conservan como evidencia; no hay limpieza automática ni resolución destructiva. Una clasificación nunca autoriza por sí sola a borrar, restaurar o reemplazar recursos.
91
+
92
+ ## Estado de implementación
93
+
94
+ Implementado:
95
+ - fscryptography.generate(password=None).
96
+ - fscryptography.Manager(key, password=None).
97
+ - Decodificación Base64 a bytes para el contexto interno.
98
+ - Reutilización de primitivas abiertas por el gestor.
99
+ - Manager.change_key() con sustitución atómica del contexto.
100
+ - Manager.export_key() a Base64.
101
+ - close() y administrador de contexto.
102
+
103
+ Pendiente:
104
+ - Pruebas de interrupción inyectada en cada barrera de persistencia, fallos de filesystem y carreras hostiles.
105
+ - Política segura de retención/limpieza de journals completados.
106
+ - API separada de resolución explícita; no forma parte de esta versión.
107
+ - Pruebas de conformidad ampliadas, vectores golden y validación de mutaciones.
108
+ - Validación de atomicidad/no-sobrescritura y round-trip en Windows/NTFS y GNU/Linux/ext4 reales.
@@ -0,0 +1,46 @@
1
+ # Arquitectura
2
+
3
+ ## Principios
4
+
5
+ La API pública, las operaciones de filesystem, el formato y el backend criptográfico mantienen responsabilidades separadas. La arquitectura interna no debe filtrar objetos específicos del backend a la API pública.
6
+
7
+ ## Componentes lógicos
8
+
9
+ - Manager: inicialización, ciclo de vida, almacenamiento binario de la clave y contexto reutilizable de operaciones.
10
+ - File operations: cifrado y descifrado del contenido.
11
+ - Directory operations: transformación del nombre de directorio.
12
+ - Name codec: codificación y validación de nombres cifrados.
13
+ - Key management: generación, derivación, parsing y separación de claves.
14
+ - Format: cabeceras, metadatos y versionado.
15
+ - Filesystem operations: rutas, temporales, publicación no-replace, sincronización y manejo de fallos.
16
+ - Cryptographic backend: integración interna de Tink, Argon2id y AES-GCM de envoltura.
17
+ - Transaction journal (diseño): registro persistente de operaciones interrumpidas e inspección explícita de sus identidades.
18
+
19
+ Esta división define responsabilidades, no obliga a crear un archivo por componente.
20
+
21
+ ## Dependencias
22
+
23
+ La biblioteca estándar proporciona I/O, rutas y operaciones de sistema. Google Tink proporciona las primitivas AEAD y Streaming AEAD. Argon2id se integra mediante argon2-cffi y AES-GCM de envoltura mediante cryptography.
24
+
25
+ La primera versión utiliza un único backend criptográfico; no se diseña una arquitectura de backends intercambiables.
26
+
27
+ ## Estado de componentes
28
+
29
+ - **Implementado:** validación y codec de nombres Tink; generación/apertura de MasterKey; recuperación de keysets; API `generate()`/`Manager`; cambio y exportación de clave; formato binario de archivo v1.0; cifrado/descifrado de archivos con Tink Streaming AEAD; cifrado/descifrado de nombres de archivos y directorios; temporales privados; publicación no-replace; sincronización del archivo temporal y del directorio padre en GNU/Linux.
30
+ - **Diseño especificado, implementación pendiente:** protocolo de journal por transacción, formato estricto, estados persistentes, validación de identidades y recuperación inicial de solo lectura.
31
+ - **Pendiente de validación de plataforma:** comportamiento real en NTFS y ext4, límites Unicode exactos en Windows, colisiones bajo configuraciones case-sensitive y garantías de durabilidad.
32
+ - **Pendiente de robustecimiento:** integración del journal en operaciones, API tipada de inspección, resolución explícita de transacciones, flush de directorio en Windows, pruebas de concurrencia/cambios hostiles y preservación de metadatos de filesystem.
33
+
34
+ ## Flujo de cifrado implementado
35
+
36
+ Validar origen y destino; crear temporal exclusivo en el mismo directorio; escribir la cabecera y cifrar secuencialmente; finalizar el flujo autenticado; sincronizar el archivo temporal; publicar sin reemplazar destinos existentes; sincronizar el directorio padre en GNU/Linux; revalidar y retirar el origen; volver a sincronizar el directorio padre en GNU/Linux. Si falla la primera sincronización del directorio, se conservan origen y destino.
37
+
38
+ ## Flujo de descifrado implementado
39
+
40
+ Reconocer y validar la cabecera; preparar temporal privado; descifrar y autenticar todos los segmentos; validar el cierre; sincronizar el archivo temporal; validar el nombre original; publicar únicamente tras autenticación completa; sincronizar el directorio padre en GNU/Linux; retirar el ciphertext y sincronizar nuevamente el directorio padre.
41
+
42
+ ## Recuperación y límites
43
+
44
+ No existe todavía journal persistente ni recuperación automática de operaciones interrumpidas abruptamente. Los temporales huérfanos no se eliminan automáticamente. Si la publicación se completó pero el origen no pudo retirarse, ambos recursos se conservan y se informa `AtomicOperationError`.
45
+
46
+ El protocolo propuesto está en `docs/recovery-journal.md`. La primera implementación será de inspección explícita y no mutará el filesystem. No implementar primitivas propias. No publicar plaintext parcial. No sobrescribir destinos por defecto. No asumir que múltiples renames forman una transacción. No prometer borrado seguro absoluto de secretos en memoria Python.
@@ -0,0 +1,134 @@
1
+ # Benchmark reproducible de Argon2id
2
+
3
+ ## Estado
4
+
5
+ Herramienta de medición disponible para desarrollo. **El perfil 64 MiB / 3 / p=1 está aprobado como perfil de producción v1** con base en los resultados del equipo de referencia registrados en este documento. Por decisión del proyecto no se realizó validación en otros equipos; la aprobación no certifica todas las plataformas. Este benchmark no implementa ni modifica la apertura de `MasterKey`.
6
+
7
+ ## Artefacto
8
+
9
+ El ejecutable `tests/backend_validation/benchmark_argon2id.py` mide la derivación Argon2id usando `argon2-cffi` y los parámetros seleccionados para la propuesta:
10
+
11
+ - Argon2id, versión 19 (`0x13`).
12
+ - Memoria: 65.536 KiB.
13
+ - Iteraciones: 3.
14
+ - Paralelismo: 1.
15
+ - Salida: 32 bytes.
16
+
17
+ No requiere dependencias adicionales a `argon2-cffi` y la biblioteca estándar de Python. No se ejecuta automáticamente en CI: sus tiempos dependen del hardware y no constituyen una prueba estable de regresión.
18
+
19
+ ## Ejecución de referencia
20
+
21
+ Desde la raíz del repositorio, con `argon2-cffi` instalado:
22
+
23
+ ```bash
24
+ python tests/backend_validation/benchmark_argon2id.py
25
+ ```
26
+
27
+ Por defecto realiza dos derivaciones de calentamiento y siete lotes medidos para cada nivel de concurrencia (1 y 2). El nivel máximo está limitado por un presupuesto estimado predeterminado de 256 MiB de memoria Argon2. La herramienta aborta antes de ejecutar la KDF si la memoria configurada multiplicada por la concurrencia excede ese presupuesto.
28
+
29
+ Para guardar el informe:
30
+
31
+ ```bash
32
+ python tests/backend_validation/benchmark_argon2id.py --json argon2id-benchmark.json
33
+ ```
34
+
35
+ Los parámetros de ejecución se pueden ajustar explícitamente:
36
+
37
+ ```bash
38
+ python tests/backend_validation/benchmark_argon2id.py \
39
+ --iterations 10 \
40
+ --warmup 3 \
41
+ --concurrency 1 2 \
42
+ --max-memory-mib 256
43
+ ```
44
+
45
+ El presupuesto es una salvaguarda de memoria de trabajo Argon2 estimada, no una detección de RAM disponible ni una garantía contra OOM. Antes de elevarlo, comprobar memoria libre y cerrar cargas innecesarias.
46
+
47
+ ## Resultados de referencia aprobados
48
+
49
+ ### Entorno
50
+
51
+ - Sistema: Linux x86_64, kernel `6.17.0-35-generic`, glibc 2.39.
52
+ - Python: CPython 3.12.3.
53
+ - `argon2-cffi`: 25.1.0.
54
+ - CPU lógica: 4.
55
+ - Perfil: Argon2id v19, 65.536 KiB, 3 iteraciones, paralelismo 1, salida de 32 bytes.
56
+ - Presupuesto configurado en el benchmark: 256 MiB de memoria Argon2 estimada.
57
+
58
+ ### Latencia (30 lotes por nivel; 5 warmups)
59
+
60
+ | Métrica | Concurrencia 1 | Concurrencia 2 |
61
+ |---|---:|---:|
62
+ | Mediana por derivación | 480,58 ms | 551,85 ms |
63
+ | P95 por derivación | 581,59 ms | 760,73 ms |
64
+ | Máximo por derivación | 584,78 ms | 1.085,04 ms |
65
+ | Mediana de tiempo de lote | 481,14 ms | 559,55 ms |
66
+ | P95 de tiempo de lote | 582,27 ms | 1.040,04 ms |
67
+
68
+ ### Memoria residente máxima (medición separada con GNU time)
69
+
70
+ Se ejecutó el benchmark en procesos independientes con `/usr/bin/time -v`, 30 lotes y 5 warmups para cada nivel:
71
+
72
+ | Métrica | Concurrencia 1 | Concurrencia 2 |
73
+ |---|---:|---:|
74
+ | RSS máximo | 85.712 KiB (83,70 MiB) | 151.180 KiB (147,64 MiB) |
75
+ | Presupuesto | 256 MiB | 256 MiB |
76
+ | Margen respecto al presupuesto | 172,30 MiB | 108,36 MiB |
77
+ | Swap reportado | 0 | 0 |
78
+ | Exit status | 0 | 0 |
79
+
80
+ La RSS incluye Python, bibliotecas y memoria auxiliar; no es una medición aislada del área de trabajo de Argon2. Los valores son high-water marks del proceso informados por GNU time. Las mediciones de latencia de estos procesos separados fueron: concurrencia 1, mediana 521,30 ms, P95 658,61 ms y máximo 673,08 ms; concurrencia 2, mediana 560,83 ms, P95 639,99 ms y máximo 955,94 ms. Las variaciones entre ejecuciones son esperables y no deben mezclarse como si fueran una única muestra.
81
+
82
+ **Decisión:** el perfil 64 MiB / 3 / p=1 se aprueba para MasterKey v1. En el equipo medido, dos derivaciones simultáneas alcanzaron 147,64 MiB de RSS máximo, dentro del presupuesto de referencia de 256 MiB. La librería no creará concurrencia interna; la aplicación integradora seguirá siendo responsable de limitar aperturas simultáneas según su presupuesto real. La omisión de pruebas en otros equipos es una decisión de alcance, no evidencia de compatibilidad universal.
83
+
84
+ ## Métricas
85
+
86
+ El informe JSON incluye:
87
+
88
+ - Identificación del intérprete, plataforma, arquitectura, procesador y CPUs lógicas.
89
+ - Versión instalada de `argon2-cffi`.
90
+ - Parámetros Argon2id y memoria teórica estimada para la concurrencia máxima.
91
+ - Latencia por derivación: mínimo, mediana, máximo y percentil 95 (nearest-rank).
92
+ - Tiempo de pared por lote concurrente: mediana y percentil 95.
93
+
94
+ La memoria estimada corresponde al coste de trabajo configurado multiplicado por el número de derivaciones concurrentes. No incluye overhead del proceso, bibliotecas, runtime ni sistema operativo. No se presenta una medición portable de memoria residente máxima: comparar RSS entre sistemas requeriría instrumentación específica de plataforma y puede confundir el high-water mark histórico del proceso con el consumo de una ejecución concreta.
95
+
96
+ ## Protocolo de medición recomendado
97
+
98
+ 1. Ejecutar en el equipo más modesto que se pretenda soportar, conectado a corriente y en un modo de energía documentado.
99
+ 2. Registrar modelo de CPU, RAM instalada, sistema operativo, arquitectura, versión de Python y versión de `argon2-cffi`.
100
+ 3. Cerrar tareas intensivas y evitar medir durante actualizaciones, compilaciones u otras cargas concurrentes.
101
+ 4. Ejecutar el comando predeterminado al menos tres veces como procesos independientes.
102
+ 5. Conservar los informes JSON sin modificar y comparar mediana y p95, no una sola observación.
103
+ 6. Repetir en cada plataforma objetivo, en particular en equipos de memoria limitada.
104
+ 7. Evaluar la concurrencia según el presupuesto real de memoria de la aplicación. El resultado concurrente no debe interpretarse como autorización para que la librería cree concurrencia interna.
105
+
106
+ No combinar mediciones tomadas con distintos perfiles de energía, condiciones térmicas o cargas de fondo como si fueran equivalentes.
107
+
108
+ ## Perfil alternativo y pruebas rápidas
109
+
110
+ El script admite parámetros personalizados para experimentación. Cualquier resultado cuyo perfil no sea exactamente 65.536 KiB / 3 / 1 queda etiquetado como `custom-profile-not-production`.
111
+
112
+ Un perfil reducido puede servir para comprobar el funcionamiento del script, pero **no** para estimar el rendimiento del perfil propuesto, validar seguridad ni justificar una decisión de producción. Los parámetros reducidos de los golden vectors tampoco son un perfil de producción.
113
+
114
+ ## Seguridad y reproducibilidad
115
+
116
+ - El benchmark usa una contraseña y un salt fijos, públicos y exclusivos de esta herramienta. No son secretos ni deben reutilizarse en producción.
117
+ - No solicita, registra ni persiste contraseñas del usuario.
118
+ - No guarda ni muestra las claves derivadas; solo comprueba su longitud.
119
+ - El salt fijo hace repetible el trabajo de la KDF, pero no modela la generación aleatoria de salt de producción.
120
+ - La herramienta no abre contenedores MasterKey ni keysets Tink y no valida la implementación de producción.
121
+ - No debe ejecutarse automáticamente en cada push ni usarse como umbral de CI.
122
+
123
+ ## Criterio de decisión
124
+
125
+ La propuesta actual plantea una latencia orientativa de 0,5–1,5 segundos para una apertura individual en hardware modesto. El benchmark debe aportar evidencia para decidir si ese objetivo es razonable en los dispositivos objetivo. No se debe reducir automáticamente el coste criptográfico para satisfacer el objetivo temporal.
126
+
127
+ La decisión final debe registrar:
128
+ - Equipos y plataformas medidos.
129
+ - Informes completos y condiciones de ejecución.
130
+ - Mediana y p95 por dispositivo.
131
+ - Memoria teórica por concurrencia y presupuesto operativo de la aplicación.
132
+ - Perfil aprobado o cambios explícitos a la política.
133
+
134
+ El perfil está aprobado para v1. Los límites de entrada y contraseña continúan pendientes de confirmación contractual; las pruebas del parser productivo también siguen pendientes.