harpocrate 0.8.0__tar.gz

harpocrate-0.8.0/.gitignore

@@ -0,0 +1,234 @@
+# Claude Code memory (local only)
+.claude/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+!cli-bash/lib/
+!frontend/src/lib/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.test
+.env.local
+.envrc
+
+# Données runtime (volumes Docker bind-mountés)
+/data/
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+frontend/node_modules/
+frontend/dist/
+
+# Wiki = dépôt séparé (gaelgael5/harpocrate.wiki). Un clone local ici ne doit pas
+# être ajouté : un gitlink sans .gitmodules casse actions/checkout (2026-10-20).
+/harpocrate.wiki/

harpocrate-0.8.0/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+## 0.8.0 — 2026-10-03
+
+### Nouveau — assistant « Se connecter avec Harpocrate » (`harpocrate.connect`)
+
+Une application déclarée dans le registre d'une instance Harpocrate obtient une API key
+sur un wallet choisi par l'utilisateur, sans copier-coller de token, et sans que
+Harpocrate voie jamais la `dkey` de la clé :
+
+- `connect.start(base_url, client_id, redirect_uri, permissions, ttl_days=None)` —
+  génère PKCE S256 et une paire de clés éphémère P-256, dépose la demande (PAR) et rend
+  `(browser_url, ConnectState)` ;
+- `connect.finish(pending, code=..., state=...)` — vérifie le `state` (CSRF), échange le
+  code (une seule fois), ouvre le scellé JWE ECDH-ES / A256GCM avec la clé privée
+  éphémère et rend un `ConnectResult(token, api_key_id, wallet_id)`.
+
+`ConnectState` contient le `code_verifier` et la clé privée éphémère : à garder côté
+serveur entre la redirection et le retour (`to_dict` / `from_dict`), jamais dans un
+cookie lisible ni dans l'URL. Ni `ConnectState` ni `ConnectResult` n'affichent leurs
+secrets dans `repr`.
+
+- `harpocrate.token.with_decryption_key(token, dkey_b64)` — inverse de
+  `truncate_token_for_transport` : réinsère la dkey dans un token signé sans elle.
+- Nouvelle exception `ConnectError` (attribut `error_code`).
+
+### Distribution
+
+- Première version publiée sur PyPI (`pip install harpocrate`, `uv add harpocrate`),
+  par la CI GitHub Actions en Trusted Publishing — voir `RELEASING.md`. PyPI devient le
+  canal officiel ; le téléchargement du wheel depuis une instance Harpocrate sera retiré.
+- Le paquet déclare ses types (`py.typed`) et sa licence en expression SPDX.
+
+### Dépendances
+
+- `joserfc>=1.7` (descellement JWE ; pas de primitive cryptographique maison).
+
+## 0.7.0 — 2026-05-17
+
+### Security — split-token client-side
+
+**La `decryption_key` ne transite plus jamais sur le canal HTTP.**
+
+Le `VaultHttpClient` tronque maintenant le token API key à l'instanciation :
+le segment `dkey` (43 chars base64url) est remplacé par un placeholder constant
+avant la première requête. La vraie `dkey` reste en RAM côté client, parsée par
+`VaultClient` pour le déchiffrement local des `encrypted_wallet_key`.
+
+Le HMAC du token ne couvre pas le segment `dkey` (cf.
+`backend/app/core/api_key_token.py:103-112`), donc la troncature est
+transparente pour la validation serveur.
+
+- **Avant 0.7.0** : le SDK envoyait le token complet `hrpv_1_id_exp_perms_auth_dkey_hmac`
+  dans le header `Authorization`. La dkey transitait sur TLS et était parsée
+  côté serveur (jamais utilisée par un handler, mais présente en mémoire).
+- **À partir de 0.7.0** : le SDK envoie `hrpv_1_id_exp_perms_auth_<placeholder43>_hmac`.
+  Un serveur compromis qui logue le header `Authorization` ne récupère plus la dkey.
+
+### Nouvelles API publiques
+
+- `harpocrate.token.truncate_token_for_transport(token: str) -> str` —
+  helper exposé pour les intégrations qui construisent leurs propres clients
+  HTTP. Lève `InvalidTokenError` si le token est mal formé.
+
+### Breaking changes
+
+- `VaultHttpClient(base_url, token=...)` **valide maintenant le format du
+  token au boot**. Un token de fixtures de test sans le format `hrpv_*`
+  complet (8 segments, longueurs fixes) lève `InvalidTokenError`. Mettez à
+  jour vos fixtures de test pour utiliser un token réel ou utilisez
+  `unittest.mock.patch("harpocrate.client.parse_token")` + `patch("harpocrate.client.VaultHttpClient")`
+  pour tester un client mocké de bout en bout (cf. `tests/test_rotation.py`).
+
+### Tests
+
+- Suite de tests `tests/unit/test_http_split_token.py` qui intercepte
+  `httpx.request` et vérifie que la `dkey` n'apparaît jamais dans le header
+  `Authorization` envoyé (GET, POST, PUT, PATCH, DELETE).
+- 8 nouveaux tests unitaires pour `truncate_token_for_transport`.
+- Suite totale : 140 tests verts.
+
+### Migration depuis 0.6.x
+
+Pour les utilisateurs du SDK :
+- **Aucun changement de code requis** : `VaultClient(token=..., base_url=...)`
+  fonctionne à l'identique. Le token complet est toujours accepté en entrée,
+  la troncature est interne.
+- Si vous instanciez directement `VaultHttpClient` avec un token de test
+  (`"hrpv_test"`, `"hrpv_x"`...), remplacez-le par un token au bon format
+  (cf. `tests/unit/test_http_split_token.py` pour un exemple).
+
+Les autres SDK officiels (TypeScript, JavaScript, Go, Rust, C#) n'ont **pas
+encore** ce changement — ils enverront toujours le token complet jusqu'à leur
+prochaine version.
+
+---
+
+## 0.6.0 — antérieur
+
+(historique non documenté dans ce CHANGELOG ; voir `git log` pour les détails).

harpocrate-0.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 black beard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

harpocrate-0.8.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: harpocrate
+Version: 0.8.0
+Summary: Client Python zero-knowledge pour le coffre de secrets Harpocrate : chiffrement côté client, le serveur ne voit jamais une valeur
+Project-URL: Homepage, https://github.com/gaelgael5/harpocrate
+Project-URL: Source, https://github.com/gaelgael5/harpocrate/tree/main/sdk-python
+Project-URL: Changelog, https://github.com/gaelgael5/harpocrate/blob/main/sdk-python/CHANGELOG.md
+Project-URL: Issues, https://github.com/gaelgael5/harpocrate/issues
+Author: gaelgael5
+License-Expression: MIT
+License-File: LICENSE
+Keywords: encryption,harpocrate,secrets,vault,zero-knowledge
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: argon2-cffi>=23
+Requires-Dist: bcrypt>=4.1
+Requires-Dist: cachetools>=5.3
+Requires-Dist: click>=8.1
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.27
+Requires-Dist: joserfc>=1.7
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Requires-Dist: types-cachetools>=5.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Harpocrate SDK Python
+
+Client Python zero-knowledge pour Harpocrate Vault.
+
+## Installation
+
+Depuis [PyPI](https://pypi.org/project/harpocrate/) :
+
+```bash
+pip install harpocrate
+# ou
+uv add harpocrate
+```
+
+Python 3.10 ou plus récent.
+
+## Usage rapide
+
+```python
+from harpocrate import VaultClient
+
+client = VaultClient(
+    token="hrpv_1_...",
+    base_url="https://vault.yoops.org",
+)
+
+# Lire un secret
+value = client.secrets.get("ANTHROPIC_API_KEY")
+
+# Lister les secrets
+for secret in client.secrets.list().secrets:
+    print(secret.name, "placeholder" if secret.is_placeholder else "valued")
+
+# Peupler tous les placeholders
+results = client.secrets.populate_all()
+for r in results:
+    print(r.name, "OK" if r.success else r.error)
+```
+
+## Détection de rotation (LOT_22, ≥ 0.5.0)
+
+Quand un secret est rotaté côté Harpocrate, l'application qui consomme ce
+secret détecte typiquement l'expiration via une réponse 401 de l'API tierce
+(Anthropic, OpenAI, etc.). Le SDK fournit un mécanisme déclaratif pour gérer
+ce cas :
+
+```python
+from harpocrate import VaultClient
+
+client = VaultClient(token="hrpv_...", base_url="https://vault.yoops.org")
+
+# 1. Enregistrer un callback pour un secret nommé
+@client.on_auth_error("anthropic_api_key")
+async def on_anthropic_rotated(new_value: str) -> None:
+    anthropic_client.api_key = new_value
+
+# 2. Filet de sécurité : callback pour TOUS les secrets
+@client.on_any_auth_error
+async def log_any_rotation(name: str, new_value: str) -> None:
+    logger.warning("secret rotated: %s", name)
+
+# 3. Quand l'app détecte un 401 sur un appel utilisant le secret :
+async def call_anthropic(prompt: str) -> str:
+    key = client.secrets.get("anthropic_api_key")
+    try:
+        return await anthropic.complete(prompt, api_key=key)
+    except anthropic.AuthenticationError:
+        # Le SDK refait un GET forcé, déchiffre, appelle les callbacks
+        new_key = await client.notify_auth_error("anthropic_api_key")
+        return await anthropic.complete(prompt, api_key=new_key)
+```
+
+### Context manager (sucre syntaxique)
+
+```python
+async with client.using_secret("anthropic_api_key") as get_value:
+    key = await get_value()
+    try:
+        return await anthropic.complete(prompt, api_key=key)
+    except anthropic.AuthenticationError:
+        key = await get_value(retry=True)  # force_refresh + callbacks
+        return await anthropic.complete(prompt, api_key=key)
+```
+
+### Force refresh ponctuel
+
+```python
+# Invalide le cache wallet_key local et refait un GET
+new_value = client.secrets.get("anthropic_api_key", force_refresh=True)
+```
+
+### Exceptions
+
+- `SecretRefreshFailed` : le refresh a échoué (secret supprimé, API key révoquée)
+
+## Se connecter avec Harpocrate (≥ 0.8.0)
+
+Pour qu'une application obtienne une API key sans copier-coller : l'application doit
+être déclarée par un admin Harpocrate (registre des applications, URL de retour exacte).
+
+```python
+from harpocrate import connect
+
+# Backend de l'application, au clic sur « Connecter » :
+browser_url, pending = connect.start(
+    base_url="https://vault.example",
+    client_id="ragflow",
+    redirect_uri="https://rag.example/harpocrate/callback",
+    permissions=0x01,  # read
+    ttl_days=90,
+)
+session["harpocrate_connect"] = pending.to_dict()  # côté serveur uniquement
+# → rediriger le navigateur vers browser_url
+
+# Sur redirect_uri :
+if "error" in request.args:  # access_denied : l'utilisateur a refusé
+    ...
+pending = connect.ConnectState.from_dict(session.pop("harpocrate_connect"))
+result = connect.finish(pending, code=request.args["code"], state=request.args["state"])
+# result.token : API key complète, à chiffrer au repos ; result.wallet_id, result.api_key_id
+```
+
+Le code de retour vaut 60 s et ne s'échange qu'une fois ; la demande vaut 15 min.
+
+## CLI harpocrate-gen
+
+```bash
+export HARPOCRATE_TOKEN=hrpv_1_...
+export HARPOCRATE_URL=https://vault.yoops.org
+
+harpocrate-gen list
+harpocrate-gen get --name ANTHROPIC_API_KEY
+harpocrate-gen populate --name DB_PASSWORD
+harpocrate-gen populate-all
+```

harpocrate-0.8.0/README.md

@@ -0,0 +1,135 @@
+# Harpocrate SDK Python
+
+Client Python zero-knowledge pour Harpocrate Vault.
+
+## Installation
+
+Depuis [PyPI](https://pypi.org/project/harpocrate/) :
+
+```bash
+pip install harpocrate
+# ou
+uv add harpocrate
+```
+
+Python 3.10 ou plus récent.
+
+## Usage rapide
+
+```python
+from harpocrate import VaultClient
+
+client = VaultClient(
+    token="hrpv_1_...",
+    base_url="https://vault.yoops.org",
+)
+
+# Lire un secret
+value = client.secrets.get("ANTHROPIC_API_KEY")
+
+# Lister les secrets
+for secret in client.secrets.list().secrets:
+    print(secret.name, "placeholder" if secret.is_placeholder else "valued")
+
+# Peupler tous les placeholders
+results = client.secrets.populate_all()
+for r in results:
+    print(r.name, "OK" if r.success else r.error)
+```
+
+## Détection de rotation (LOT_22, ≥ 0.5.0)
+
+Quand un secret est rotaté côté Harpocrate, l'application qui consomme ce
+secret détecte typiquement l'expiration via une réponse 401 de l'API tierce
+(Anthropic, OpenAI, etc.). Le SDK fournit un mécanisme déclaratif pour gérer
+ce cas :
+
+```python
+from harpocrate import VaultClient
+
+client = VaultClient(token="hrpv_...", base_url="https://vault.yoops.org")
+
+# 1. Enregistrer un callback pour un secret nommé
+@client.on_auth_error("anthropic_api_key")
+async def on_anthropic_rotated(new_value: str) -> None:
+    anthropic_client.api_key = new_value
+
+# 2. Filet de sécurité : callback pour TOUS les secrets
+@client.on_any_auth_error
+async def log_any_rotation(name: str, new_value: str) -> None:
+    logger.warning("secret rotated: %s", name)
+
+# 3. Quand l'app détecte un 401 sur un appel utilisant le secret :
+async def call_anthropic(prompt: str) -> str:
+    key = client.secrets.get("anthropic_api_key")
+    try:
+        return await anthropic.complete(prompt, api_key=key)
+    except anthropic.AuthenticationError:
+        # Le SDK refait un GET forcé, déchiffre, appelle les callbacks
+        new_key = await client.notify_auth_error("anthropic_api_key")
+        return await anthropic.complete(prompt, api_key=new_key)
+```
+
+### Context manager (sucre syntaxique)
+
+```python
+async with client.using_secret("anthropic_api_key") as get_value:
+    key = await get_value()
+    try:
+        return await anthropic.complete(prompt, api_key=key)
+    except anthropic.AuthenticationError:
+        key = await get_value(retry=True)  # force_refresh + callbacks
+        return await anthropic.complete(prompt, api_key=key)
+```
+
+### Force refresh ponctuel
+
+```python
+# Invalide le cache wallet_key local et refait un GET
+new_value = client.secrets.get("anthropic_api_key", force_refresh=True)
+```
+
+### Exceptions
+
+- `SecretRefreshFailed` : le refresh a échoué (secret supprimé, API key révoquée)
+
+## Se connecter avec Harpocrate (≥ 0.8.0)
+
+Pour qu'une application obtienne une API key sans copier-coller : l'application doit
+être déclarée par un admin Harpocrate (registre des applications, URL de retour exacte).
+
+```python
+from harpocrate import connect
+
+# Backend de l'application, au clic sur « Connecter » :
+browser_url, pending = connect.start(
+    base_url="https://vault.example",
+    client_id="ragflow",
+    redirect_uri="https://rag.example/harpocrate/callback",
+    permissions=0x01,  # read
+    ttl_days=90,
+)
+session["harpocrate_connect"] = pending.to_dict()  # côté serveur uniquement
+# → rediriger le navigateur vers browser_url
+
+# Sur redirect_uri :
+if "error" in request.args:  # access_denied : l'utilisateur a refusé
+    ...
+pending = connect.ConnectState.from_dict(session.pop("harpocrate_connect"))
+result = connect.finish(pending, code=request.args["code"], state=request.args["state"])
+# result.token : API key complète, à chiffrer au repos ; result.wallet_id, result.api_key_id
+```
+
+Le code de retour vaut 60 s et ne s'échange qu'une fois ; la demande vaut 15 min.
+
+## CLI harpocrate-gen
+
+```bash
+export HARPOCRATE_TOKEN=hrpv_1_...
+export HARPOCRATE_URL=https://vault.yoops.org
+
+harpocrate-gen list
+harpocrate-gen get --name ANTHROPIC_API_KEY
+harpocrate-gen populate --name DB_PASSWORD
+harpocrate-gen populate-all
+```