flechtctl 0.16.0__tar.gz

flechtctl-0.16.0/.gitignore

@@ -0,0 +1,18 @@
+*.egg-info
+.cache/
+.coverage
+.coverage.*
+.hypothesis/
+.idea/
+.pytest_cache/
+.venv
+.vscode/
+/.claude/settings.local.json
+/CLAUDE.local.md
+/graphify-out/
+/site/
+__pycache__/
+build/
+coverage.xml
+dist/
+htmlcov/

flechtctl-0.16.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.5
+Name: flechtctl
+Version: 0.16.0
+Summary: Keyrings and flenc:/flsig: secret tokens for Flechtwerk, without the framework: a library and a command line tool.
+Project-URL: Documentation, https://bsure-analytics.github.io/flechtwerk/guides/flechtctl/
+Project-URL: Homepage, https://github.com/bsure-analytics/flechtwerk
+Project-URL: Issues, https://github.com/bsure-analytics/flechtwerk/issues
+Project-URL: Repository, https://github.com/bsure-analytics/flechtwerk
+Author: Christian Schlichtherle, Viktor Penev
+Maintainer: b.sure GmbH
+License: MIT
+Keywords: flechtwerk,jwe,jws,keyring,secrets
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.12
+Requires-Dist: joserfc~=1.7
+Description-Content-Type: text/markdown
+
+# flechtctl
+
+Keyrings and `flenc:` / `flsig:` secret tokens for
+[Flechtwerk](https://github.com/bsure-analytics/flechtwerk) — as a small library and a
+command line tool, **without the framework**. `flechtctl` depends on
+[joserfc](https://jose.authlib.org/) only; it never imports `flechtwerk`, so it installs and
+runs wherever Python does (including interpreters the full stream-processing framework does
+not support yet).
+
+It does three things:
+
+- **Keyrings.** Create and edit keyring files — an RFC 7517 JWK Set holding oct (symmetric),
+  X25519 (sealing) and Ed25519 (signing) keys, each optionally bound to scopes. Optionally
+  password-protected.
+- **Value crypto.** Seal, open, sign and verify values: `flenc:jwe:…` compact JWE tokens and
+  `flsig:jws:…` Ed25519 compact JWS tokens.
+- **Token tooling.** Inspect a token's header, re-seal a token under another key.
+
+## Install
+
+```bash
+uvx flechtctl --help            # run it without installing
+uv tool install flechtctl       # or install the command
+pip install flechtctl           # or use it as a library
+```
+
+Python 3.12 or newer.
+
+## Command line quick start
+
+```bash
+flechtctl keyring new keyring.json --kid prod-2026-10          # a keyring with one fresh 32-byte key
+TOKEN=$(flechtctl encrypt -k keyring.json --scope api_key --string 's3cret')
+flechtctl inspect "$TOKEN"                                     # the unauthenticated header: kid, scope, alg
+flechtctl decrypt -k keyring.json --scope api_key --string "$TOKEN"
+```
+
+`-k/--keyring` is required for every command that needs key material: the command reads no
+environment variables. `flechtctl keyring --help` lists the keyring commands — `new`, `add`,
+`remove`, `primary`, `signing`, `show`, `export`, `import`, `protect` and `unprotect`. A keyring
+file works like a keystore: a set of named entries, handed on one public half at a time with
+`export` and `import`.
+
+## Library quick start
+
+The functions take the keyring explicitly — there is no global state:
+
+```python
+from pathlib import Path
+
+from flechtctl import Keyring, decrypt, encrypt, sign, verify
+
+keyring = Keyring.from_json(Path("keyring.json").read_text())
+
+token = encrypt(keyring, "s3cret", scope="api_key")        # "flenc:jwe:…"
+assert decrypt(keyring, token, scope="api_key") == "s3cret"
+
+signed = sign(keyring, {"order": 17}, scope="orders")       # "flsig:jws:…" — needs a signing key for the scope
+assert verify(keyring, signed, scope="orders") == {"order": 17}
+```
+
+`encrypt`, `decrypt`, `sign` and `verify` work on any JSON value; the `*_bytes` variants take
+raw payload bytes. `reencrypt` moves a token to the scope's current sealing key, `read_header`
+shows a token's unauthenticated header, and `generate_oct_key`, `generate_x25519_key` and
+`generate_ed25519_key` mint key material.
+
+## Equivalence with Flechtwerk's codecs
+
+`flechtctl.encrypt(keyring, value, scope=s)` writes exactly the token that Flechtwerk's
+`ENCRYPTED(inner, scope=s)` codec writes for `value == inner.encode(x)`, and every token
+Flechtwerk writes opens here. For a `BYTES` field, pass the base64 string. Flechtwerk itself
+is built on this package: `pip install "flechtwerk[secrets]"` installs the matching `flechtctl`.
+
+## More
+
+The guide [Keyrings and Secret Tokens with flechtctl](https://bsure-analytics.github.io/flechtwerk/guides/flechtctl/)
+walks through a complete reader/writer setup, password-protected keyrings and the library API.
+The format itself is specified on the
+[Encrypted Secrets](https://bsure-analytics.github.io/flechtwerk/concepts/secrets/) page.
+
+MIT licensed.

flechtctl-0.16.0/README.md

@@ -0,0 +1,81 @@
+# flechtctl
+
+Keyrings and `flenc:` / `flsig:` secret tokens for
+[Flechtwerk](https://github.com/bsure-analytics/flechtwerk) — as a small library and a
+command line tool, **without the framework**. `flechtctl` depends on
+[joserfc](https://jose.authlib.org/) only; it never imports `flechtwerk`, so it installs and
+runs wherever Python does (including interpreters the full stream-processing framework does
+not support yet).
+
+It does three things:
+
+- **Keyrings.** Create and edit keyring files — an RFC 7517 JWK Set holding oct (symmetric),
+  X25519 (sealing) and Ed25519 (signing) keys, each optionally bound to scopes. Optionally
+  password-protected.
+- **Value crypto.** Seal, open, sign and verify values: `flenc:jwe:…` compact JWE tokens and
+  `flsig:jws:…` Ed25519 compact JWS tokens.
+- **Token tooling.** Inspect a token's header, re-seal a token under another key.
+
+## Install
+
+```bash
+uvx flechtctl --help            # run it without installing
+uv tool install flechtctl       # or install the command
+pip install flechtctl           # or use it as a library
+```
+
+Python 3.12 or newer.
+
+## Command line quick start
+
+```bash
+flechtctl keyring new keyring.json --kid prod-2026-10          # a keyring with one fresh 32-byte key
+TOKEN=$(flechtctl encrypt -k keyring.json --scope api_key --string 's3cret')
+flechtctl inspect "$TOKEN"                                     # the unauthenticated header: kid, scope, alg
+flechtctl decrypt -k keyring.json --scope api_key --string "$TOKEN"
+```
+
+`-k/--keyring` is required for every command that needs key material: the command reads no
+environment variables. `flechtctl keyring --help` lists the keyring commands — `new`, `add`,
+`remove`, `primary`, `signing`, `show`, `export`, `import`, `protect` and `unprotect`. A keyring
+file works like a keystore: a set of named entries, handed on one public half at a time with
+`export` and `import`.
+
+## Library quick start
+
+The functions take the keyring explicitly — there is no global state:
+
+```python
+from pathlib import Path
+
+from flechtctl import Keyring, decrypt, encrypt, sign, verify
+
+keyring = Keyring.from_json(Path("keyring.json").read_text())
+
+token = encrypt(keyring, "s3cret", scope="api_key")        # "flenc:jwe:…"
+assert decrypt(keyring, token, scope="api_key") == "s3cret"
+
+signed = sign(keyring, {"order": 17}, scope="orders")       # "flsig:jws:…" — needs a signing key for the scope
+assert verify(keyring, signed, scope="orders") == {"order": 17}
+```
+
+`encrypt`, `decrypt`, `sign` and `verify` work on any JSON value; the `*_bytes` variants take
+raw payload bytes. `reencrypt` moves a token to the scope's current sealing key, `read_header`
+shows a token's unauthenticated header, and `generate_oct_key`, `generate_x25519_key` and
+`generate_ed25519_key` mint key material.
+
+## Equivalence with Flechtwerk's codecs
+
+`flechtctl.encrypt(keyring, value, scope=s)` writes exactly the token that Flechtwerk's
+`ENCRYPTED(inner, scope=s)` codec writes for `value == inner.encode(x)`, and every token
+Flechtwerk writes opens here. For a `BYTES` field, pass the base64 string. Flechtwerk itself
+is built on this package: `pip install "flechtwerk[secrets]"` installs the matching `flechtctl`.
+
+## More
+
+The guide [Keyrings and Secret Tokens with flechtctl](https://bsure-analytics.github.io/flechtwerk/guides/flechtctl/)
+walks through a complete reader/writer setup, password-protected keyrings and the library API.
+The format itself is specified on the
+[Encrypted Secrets](https://bsure-analytics.github.io/flechtwerk/concepts/secrets/) page.
+
+MIT licensed.

flechtctl-0.16.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling", "hatch-vcs"]
+
+[project]
+authors = [
+    { name = "Christian Schlichtherle" },
+    { name = "Viktor Penev" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "joserfc~=1.7",
+]
+description = "Keyrings and flenc:/flsig: secret tokens for Flechtwerk, without the framework: a library and a command line tool."
+dynamic = ["version"]
+keywords = ["flechtwerk", "jwe", "jws", "keyring", "secrets"]
+license = { text = "MIT" }
+maintainers = [
+    { name = "b.sure GmbH" },
+]
+name = "flechtctl"
+readme = "README.md"
+requires-python = ">=3.12"
+
+[project.scripts]
+flechtctl = "flechtctl.cli:main"
+
+[project.urls]
+Documentation = "https://bsure-analytics.github.io/flechtwerk/guides/flechtctl/"
+Homepage = "https://github.com/bsure-analytics/flechtwerk"
+Issues = "https://github.com/bsure-analytics/flechtwerk/issues"
+Repository = "https://github.com/bsure-analytics/flechtwerk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flechtctl"]
+
+[tool.hatch.version]
+raw-options = { root = ".." }
+source = "vcs"

flechtctl-0.16.0/src/flechtctl/__init__.py

@@ -0,0 +1,90 @@
+"""Keyrings and `flenc:`/`flsig:` secret tokens for Flechtwerk — without the framework.
+
+This package owns the keyring model (`Keyring`, `X25519Key`, `Ed25519Key`) and
+the token format (seal, open, sign, verify, the scope ratchet, the key-binding
+checks), and depends on joserfc only — never on flechtwerk. The API takes the
+keyring explicitly, with no process-global state:
+
+    from flechtctl import Keyring, decrypt, encrypt
+
+    keyring = Keyring.from_json(open("keyring.json").read())
+    token = encrypt(keyring, "s3cret", scope="api_key")   # flenc:jwe:...
+    decrypt(keyring, token, scope="api_key")              # "s3cret"
+
+`encrypt(k, v, scope=s)` writes the same token flechtwerk's
+`ENCRYPTED(inner, scope=s)` codec writes for `v == inner.encode(x)` — for a
+`BYTES` field, pass the base64 string. The `flechtctl` command wraps the same
+functions for the shell (`flechtctl --help`).
+
+`import flechtctl` loads no joserfc: the keyring and error names are imported
+eagerly, every `flechtctl.tokens` name lazily on first access (PEP 562).
+"""
+import importlib
+
+from .errors import (
+    PlaintextSecretError,
+    SecretDecryptError,
+    SecretError,
+    SecretFormatError,
+    SecretSignatureError,
+    UnsignedSecretError,
+)
+from .keyring import (
+    Ed25519Key,
+    KEY_BYTES,
+    Keyring,
+    KeyringError,
+    UnknownKeyError,
+    X25519Key,
+    is_encrypted_keyring,
+    keyring_from_jwk,
+)
+
+__all__ = [
+    "Ed25519Key",
+    "KEY_BYTES",
+    "Keyring",
+    "KeyringError",
+    "PREFIX",
+    "PlaintextSecretError",
+    "SCHEME",
+    "SIGNATURE_PREFIX",
+    "SIGNATURE_SCHEME",
+    "SecretDecryptError",
+    "SecretError",
+    "SecretFormatError",
+    "SecretSignatureError",
+    "UnknownKeyError",
+    "UnsignedSecretError",
+    "X25519Key",
+    "canonical_json",
+    "decrypt",
+    "decrypt_bytes",
+    "decrypt_keyring",
+    "encrypt",
+    "encrypt_bytes",
+    "encrypt_keyring",
+    "generate_ed25519_key",
+    "generate_oct_key",
+    "generate_x25519_key",
+    "is_encrypted",
+    "is_encrypted_keyring",
+    "is_signed",
+    "keyring_from_jwk",
+    "kid_of",
+    "read_header",
+    "reencrypt",
+    "sign",
+    "sign_bytes",
+    "signer_of",
+    "verify",
+    "verify_bytes",
+]
+
+_TOKEN_NAMES = frozenset(name for name in __all__ if name not in globals())  # everything the eager imports did not bind
+
+
+def __getattr__(name: str) -> object:
+    if name in _TOKEN_NAMES:
+        return getattr(importlib.import_module(".tokens", __name__), name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

flechtctl-0.16.0/src/flechtctl/__main__.py

@@ -0,0 +1,7 @@
+import sys
+
+from .cli import main
+
+__all__: list[str] = []  # purely internal: `python -m flechtctl` is an entry point, not an API
+
+sys.exit(main())