burnedsecret 1.1.0__tar.gz

burnedsecret-1.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.venv/

burnedsecret-1.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.5
+Name: burnedsecret
+Version: 1.1.0
+Summary: Official zero-knowledge SDK for burnedsecret.com
+Project-URL: Homepage, https://burnedsecret.com
+Project-URL: Documentation, https://burnedsecret.com/docs
+Project-URL: Repository, https://github.com/JensrudJ/burnedsecret
+Author: burnedsecret
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42
+Requires-Dist: requests>=2.32
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# burnedsecret — Official Python SDK for burnedsecret.com
+
+When you put a secret into burnedsecret, your browser (or your client library)
+encrypts it on your own device before anything leaves you. The encryption key
+never goes to our server. We store an opaque blob of encrypted bytes; we cannot
+read it, and neither can anyone who breaches our database, subpoenas us, or
+gets a court order against us. We have nothing to hand over.
+
+This package is the official Python client. All crypto runs in your process —
+the server only sees ciphertext, IVs, and (for the request flow) RSA-OAEP
+wrapped keys. The decryption material lives in your code (URL fragments, or
+PKCS8 bytes you stash in a KMS), never on our servers.
+
+## Installation
+
+```bash
+pip install burnedsecret
+```
+
+Python 3.10 or newer is required. The SDK pulls in `cryptography>=42` and
+`requests>=2.32` and nothing else.
+
+## Quick start
+
+### One-way secret (you share a password with someone)
+
+```python
+from burnedsecret import BurnedSecret
+
+bs = BurnedSecret(api_key="bs_...")
+
+url, secret_id = bs.create_secret("hunter2", ttl=86400)
+# url looks like: https://burnedsecret.com/s/<id>#k=<base64url AES key>
+# the part after '#' never leaves the caller's process — browsers do not
+# transmit URL fragments to servers, and this SDK only sends ciphertext + IV.
+
+plaintext = bs.read_secret(url)   # burns the secret on read
+```
+
+### Secret request (you ask someone to send you a password)
+
+```python
+url, request_id, private_key = bs.create_request(
+    prompt="Send me your AWS root key",
+    webhook_url="https://acme.example/hooks/bs",
+    ttl=86400,
+)
+# Persist `private_key` (PKCS8 DER bytes) — without it, the fulfillment is
+# unrecoverable. Use bs.export_private_key(private_key) → str for KMS storage.
+
+# Later, after the fulfiller has submitted their answer:
+plaintext = bs.read_fulfillment(request_id, private_key)
+```
+
+When the request was created with custom fields, `read_fulfillment` returns a
+`dict` mapping field name → value instead of a string:
+
+```python
+url, request_id, private_key = bs.create_request(
+    prompt="Send me your AWS keypair",
+    fields=[
+        {"name": "access_key_id", "type": "text", "required": True},
+        {"name": "secret_access_key", "type": "password", "required": True},
+    ],
+)
+data = bs.read_fulfillment(request_id, private_key)
+# data == {"access_key_id": "AKIA...", "secret_access_key": "wJal..."}
+```
+
+### Storing private keys in your KMS
+
+```python
+# At request-creation time:
+url, request_id, priv = bs.create_request(prompt="...")
+kms_blob = BurnedSecret.export_private_key(priv)   # str (base64url no-padding)
+my_kms.put(f"bs/req/{request_id}", kms_blob)
+
+# At fulfillment-retrieval time:
+kms_blob = my_kms.get(f"bs/req/{request_id}")
+priv = BurnedSecret.import_private_key(kms_blob)
+plaintext = bs.read_fulfillment(request_id, priv)
+```
+
+## Public-key handling
+
+Your decryption material never goes to our servers. For requests, the SDK
+generates an RSA-4096 keypair locally and only sends the public key (SPKI DER,
+base64url). The private key is returned to you as PKCS8 DER bytes — persist it
+in your KMS or secret store. If you lose it, the fulfillment is unrecoverable.
+That's the whole point.
+
+The SDK never derives or stores key material outside of the values you receive
+from `create_secret` (which returns the URL containing the key in its fragment)
+and `create_request` (which returns the private key bytes). Anything your
+process needs to keep, the SDK hands you and forgets.
+
+## Error handling
+
+The SDK raises a small exception hierarchy:
+
+```
+BurnedSecretError
+├── ApiError                  (HTTP-level failure; has .status_code, .code)
+│   ├── NotFoundError         404 — secret/request not found
+│   ├── BurnedError           410 — secret or fulfillment already consumed
+│   ├── LegacyApiError        410 — pre-Phase-21 document, not API-accessible
+│   └── RateLimitError        429 — has .retry_after_seconds
+└── CryptoError               local AES/RSA failure (bad key, malformed data)
+```
+
+```python
+from burnedsecret import (
+    BurnedSecret, BurnedError, NotFoundError, RateLimitError, CryptoError,
+)
+
+bs = BurnedSecret(api_key="bs_...")
+try:
+    plaintext = bs.read_secret(url)
+except BurnedError:
+    print("Secret has already been viewed and burned.")
+except NotFoundError:
+    print("Secret never existed or expired.")
+except RateLimitError as e:
+    print(f"Too many requests — retry after {e.retry_after_seconds}s")
+except CryptoError:
+    print("The URL fragment is wrong or the ciphertext is corrupted.")
+```
+
+`BurnedSecret(api_key="...")` itself raises `ValueError` when the API key is
+missing or does not start with `bs_`.
+
+## Test vectors and interop
+
+The wire format — AES-256-GCM with a 12-byte IV and a 128-bit appended tag,
+RSA-OAEP-SHA256 over a 4096-bit modulus, SPKI/PKCS8 DER with base64url no
+padding — is pinned at `https://burnedsecret.com/api/v1/test-vectors.json`.
+
+Any third-party Python implementation can prove conformance by round-tripping
+that file. The same file lives in this repo at `web/api/v1/test-vectors.json`
+and powers `tests/test_interop.py`, which asserts four invariants:
+
+1. AES encrypt with `secret.aes_key + iv + plaintext` is byte-identical to
+   `secret.ciphertext`.
+2. AES decrypt of `secret.ciphertext` recovers `secret.plaintext_utf8`.
+3. RSA-OAEP decrypt of `request.wrapped_key` with `request.private_key_pkcs8`
+   recovers `request.content_aes_key`.
+4. AES encrypt with the unwrapped key reproduces `request.ciphertext`.
+
+If your SDK round-trips all four, it is wire-compatible with this one and with
+the official JavaScript and Flutter clients.
+
+## Crypto specification
+
+Full algorithm parameters, key formats, and design rationale:
+`.planning/design/zero-knowledge-architecture.md` in this repository.
+
+## Development
+
+```bash
+git clone https://github.com/JensrudJ/burnedsecret
+cd burnedsecret/sdk-python
+pip install -e ".[dev]"
+pytest -v
+```
+
+The test suite has 18 cases: 4 interop conformance + 4 crypto round-trips +
+6 client wire-contract + 4 error-mapping. The RSA-4096 keygen test is marked
+`@pytest.mark.slow` and runs in about three seconds; run `pytest -v -m "not slow"`
+to skip it during fast inner-loop iteration.
+
+## Releases
+
+Releases are published from Codemagic on tags pushed to the burnedsecret repo:
+- `@burnedsecret/sdk` (npm): tag matching `sdk-js-vMAJOR.MINOR.PATCH`
+- `burnedsecret` (PyPI): tag matching `sdk-py-vMAJOR.MINOR.PATCH`
+
+The version in the tag must match the version in `package.json` / `pyproject.toml`.
+
+Every push to `dev` runs the test suite and the cross-SDK round-trip gate (D-15) but does NOT publish.
+
+Each SDK release workflow also runs cross-SDK round trips at its own checkout
+before publishing. Built packages must pass clean consumer installation checks.
+A release tag must exactly match its package version; a tagged release fails
+if its publishing credential is missing. Builds and publication run in Codemagic.
+
+## License
+
+MIT — see `LICENSE` in the repository root.
+
+
+### Authenticated envelope formats
+
+File secrets now use **BSF2**, which authenticates the complete header and each
+chunk's position. Old BSF1 files are rejected; there is no legacy fallback.
+This is an intentional format break for previously disposable test data.
+Python 1.1.0, JavaScript 2.0.0 and the updated web file viewer use this format;
+JavaScript 1.2.0 does not support it.
+
+Unprotected text remains raw UTF-8, including literal `PP:` strings. Protected
+SDK text uses a binary BSP2 marker that cannot collide with UTF-8 plaintext.
+Collect a passphrase before fetching a protected secret: a missing/wrong
+passphrase discovered after burn-on-read cannot be recovered by refetching.
+See [the envelope specification](../docs/crypto-envelopes.md) for framing and
+interop vector version 3. Browser text protection is a separate flow; SDK
+passphrase-protected text still requires an SDK reader.

burnedsecret-1.1.0/README.md

@@ -0,0 +1,205 @@
+# burnedsecret — Official Python SDK for burnedsecret.com
+
+When you put a secret into burnedsecret, your browser (or your client library)
+encrypts it on your own device before anything leaves you. The encryption key
+never goes to our server. We store an opaque blob of encrypted bytes; we cannot
+read it, and neither can anyone who breaches our database, subpoenas us, or
+gets a court order against us. We have nothing to hand over.
+
+This package is the official Python client. All crypto runs in your process —
+the server only sees ciphertext, IVs, and (for the request flow) RSA-OAEP
+wrapped keys. The decryption material lives in your code (URL fragments, or
+PKCS8 bytes you stash in a KMS), never on our servers.
+
+## Installation
+
+```bash
+pip install burnedsecret
+```
+
+Python 3.10 or newer is required. The SDK pulls in `cryptography>=42` and
+`requests>=2.32` and nothing else.
+
+## Quick start
+
+### One-way secret (you share a password with someone)
+
+```python
+from burnedsecret import BurnedSecret
+
+bs = BurnedSecret(api_key="bs_...")
+
+url, secret_id = bs.create_secret("hunter2", ttl=86400)
+# url looks like: https://burnedsecret.com/s/<id>#k=<base64url AES key>
+# the part after '#' never leaves the caller's process — browsers do not
+# transmit URL fragments to servers, and this SDK only sends ciphertext + IV.
+
+plaintext = bs.read_secret(url)   # burns the secret on read
+```
+
+### Secret request (you ask someone to send you a password)
+
+```python
+url, request_id, private_key = bs.create_request(
+    prompt="Send me your AWS root key",
+    webhook_url="https://acme.example/hooks/bs",
+    ttl=86400,
+)
+# Persist `private_key` (PKCS8 DER bytes) — without it, the fulfillment is
+# unrecoverable. Use bs.export_private_key(private_key) → str for KMS storage.
+
+# Later, after the fulfiller has submitted their answer:
+plaintext = bs.read_fulfillment(request_id, private_key)
+```
+
+When the request was created with custom fields, `read_fulfillment` returns a
+`dict` mapping field name → value instead of a string:
+
+```python
+url, request_id, private_key = bs.create_request(
+    prompt="Send me your AWS keypair",
+    fields=[
+        {"name": "access_key_id", "type": "text", "required": True},
+        {"name": "secret_access_key", "type": "password", "required": True},
+    ],
+)
+data = bs.read_fulfillment(request_id, private_key)
+# data == {"access_key_id": "AKIA...", "secret_access_key": "wJal..."}
+```
+
+### Storing private keys in your KMS
+
+```python
+# At request-creation time:
+url, request_id, priv = bs.create_request(prompt="...")
+kms_blob = BurnedSecret.export_private_key(priv)   # str (base64url no-padding)
+my_kms.put(f"bs/req/{request_id}", kms_blob)
+
+# At fulfillment-retrieval time:
+kms_blob = my_kms.get(f"bs/req/{request_id}")
+priv = BurnedSecret.import_private_key(kms_blob)
+plaintext = bs.read_fulfillment(request_id, priv)
+```
+
+## Public-key handling
+
+Your decryption material never goes to our servers. For requests, the SDK
+generates an RSA-4096 keypair locally and only sends the public key (SPKI DER,
+base64url). The private key is returned to you as PKCS8 DER bytes — persist it
+in your KMS or secret store. If you lose it, the fulfillment is unrecoverable.
+That's the whole point.
+
+The SDK never derives or stores key material outside of the values you receive
+from `create_secret` (which returns the URL containing the key in its fragment)
+and `create_request` (which returns the private key bytes). Anything your
+process needs to keep, the SDK hands you and forgets.
+
+## Error handling
+
+The SDK raises a small exception hierarchy:
+
+```
+BurnedSecretError
+├── ApiError                  (HTTP-level failure; has .status_code, .code)
+│   ├── NotFoundError         404 — secret/request not found
+│   ├── BurnedError           410 — secret or fulfillment already consumed
+│   ├── LegacyApiError        410 — pre-Phase-21 document, not API-accessible
+│   └── RateLimitError        429 — has .retry_after_seconds
+└── CryptoError               local AES/RSA failure (bad key, malformed data)
+```
+
+```python
+from burnedsecret import (
+    BurnedSecret, BurnedError, NotFoundError, RateLimitError, CryptoError,
+)
+
+bs = BurnedSecret(api_key="bs_...")
+try:
+    plaintext = bs.read_secret(url)
+except BurnedError:
+    print("Secret has already been viewed and burned.")
+except NotFoundError:
+    print("Secret never existed or expired.")
+except RateLimitError as e:
+    print(f"Too many requests — retry after {e.retry_after_seconds}s")
+except CryptoError:
+    print("The URL fragment is wrong or the ciphertext is corrupted.")
+```
+
+`BurnedSecret(api_key="...")` itself raises `ValueError` when the API key is
+missing or does not start with `bs_`.
+
+## Test vectors and interop
+
+The wire format — AES-256-GCM with a 12-byte IV and a 128-bit appended tag,
+RSA-OAEP-SHA256 over a 4096-bit modulus, SPKI/PKCS8 DER with base64url no
+padding — is pinned at `https://burnedsecret.com/api/v1/test-vectors.json`.
+
+Any third-party Python implementation can prove conformance by round-tripping
+that file. The same file lives in this repo at `web/api/v1/test-vectors.json`
+and powers `tests/test_interop.py`, which asserts four invariants:
+
+1. AES encrypt with `secret.aes_key + iv + plaintext` is byte-identical to
+   `secret.ciphertext`.
+2. AES decrypt of `secret.ciphertext` recovers `secret.plaintext_utf8`.
+3. RSA-OAEP decrypt of `request.wrapped_key` with `request.private_key_pkcs8`
+   recovers `request.content_aes_key`.
+4. AES encrypt with the unwrapped key reproduces `request.ciphertext`.
+
+If your SDK round-trips all four, it is wire-compatible with this one and with
+the official JavaScript and Flutter clients.
+
+## Crypto specification
+
+Full algorithm parameters, key formats, and design rationale:
+`.planning/design/zero-knowledge-architecture.md` in this repository.
+
+## Development
+
+```bash
+git clone https://github.com/JensrudJ/burnedsecret
+cd burnedsecret/sdk-python
+pip install -e ".[dev]"
+pytest -v
+```
+
+The test suite has 18 cases: 4 interop conformance + 4 crypto round-trips +
+6 client wire-contract + 4 error-mapping. The RSA-4096 keygen test is marked
+`@pytest.mark.slow` and runs in about three seconds; run `pytest -v -m "not slow"`
+to skip it during fast inner-loop iteration.
+
+## Releases
+
+Releases are published from Codemagic on tags pushed to the burnedsecret repo:
+- `@burnedsecret/sdk` (npm): tag matching `sdk-js-vMAJOR.MINOR.PATCH`
+- `burnedsecret` (PyPI): tag matching `sdk-py-vMAJOR.MINOR.PATCH`
+
+The version in the tag must match the version in `package.json` / `pyproject.toml`.
+
+Every push to `dev` runs the test suite and the cross-SDK round-trip gate (D-15) but does NOT publish.
+
+Each SDK release workflow also runs cross-SDK round trips at its own checkout
+before publishing. Built packages must pass clean consumer installation checks.
+A release tag must exactly match its package version; a tagged release fails
+if its publishing credential is missing. Builds and publication run in Codemagic.
+
+## License
+
+MIT — see `LICENSE` in the repository root.
+
+
+### Authenticated envelope formats
+
+File secrets now use **BSF2**, which authenticates the complete header and each
+chunk's position. Old BSF1 files are rejected; there is no legacy fallback.
+This is an intentional format break for previously disposable test data.
+Python 1.1.0, JavaScript 2.0.0 and the updated web file viewer use this format;
+JavaScript 1.2.0 does not support it.
+
+Unprotected text remains raw UTF-8, including literal `PP:` strings. Protected
+SDK text uses a binary BSP2 marker that cannot collide with UTF-8 plaintext.
+Collect a passphrase before fetching a protected secret: a missing/wrong
+passphrase discovered after burn-on-read cannot be recovered by refetching.
+See [the envelope specification](../docs/crypto-envelopes.md) for framing and
+interop vector version 3. Browser text protection is a separate flow; SDK
+passphrase-protected text still requires an SDK reader.

burnedsecret-1.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "burnedsecret"
+version = "1.1.0"
+description = "Official zero-knowledge SDK for burnedsecret.com"
+readme = "README.md"
+authors = [{ name = "burnedsecret" }]
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+  "cryptography>=42",
+  "requests>=2.32",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "responses>=0.25",
+  "build>=1.2",
+  "twine>=5.0",
+]
+
+[project.urls]
+Homepage = "https://burnedsecret.com"
+Documentation = "https://burnedsecret.com/docs"
+Repository = "https://github.com/JensrudJ/burnedsecret"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/burnedsecret"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+  "slow: tests that take more than a couple seconds (RSA-4096 keygen, etc.)",
+]

burnedsecret-1.1.0/scripts/decrypt_from_js.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Python-side decrypter for the cross-SDK round-trip (Phase 26 capstone).
+
+Reads the JS-produced envelope JSON from argv[1] (or stdin), decrypts EVERY
+interop shape, asserts byte-exact recovery, and exits non-zero on any mismatch.
+Prints a literal PASS line that Codemagic greps as a gate predicate.
+
+Usage:  python sdk-python/scripts/decrypt_from_js.py /tmp/js_out.json
+        python sdk-python/scripts/decrypt_from_js.py < /tmp/js_out.json
+"""
+import json
+import sys
+
+from burnedsecret import file_envelope
+from burnedsecret.crypto import aes_decrypt, rsa_oaep_decrypt
+from burnedsecret.encoding import b64u_decode, b64u_encode
+from burnedsecret.passphrase import unwrap_text_envelope
+
+
+def _fail(msg: str) -> None:
+    print(f"MISMATCH: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def _eq(got, want, label: str) -> None:
+    if got != want:
+        _fail(f"{label}: got {got!r} want {want!r}")
+
+
+def _read_envelope() -> dict:
+    if len(sys.argv) >= 2:
+        with open(sys.argv[1], "r", encoding="utf-8") as f:
+            return json.load(f)
+    return json.load(sys.stdin)
+
+
+def main() -> int:
+    env = _read_envelope()
+
+    # -- Secret flow: AES only --------------------------------------------------
+    s_key = b64u_decode(env["secret"]["aes_key_b64u"])
+    s_iv = b64u_decode(env["secret"]["iv_b64u"])
+    s_ct = b64u_decode(env["secret"]["ciphertext_b64u"])
+    s_pt = aes_decrypt(s_ct, s_key, s_iv).decode("utf-8")
+    _eq(s_pt, env["secret"]["expected_plaintext"], "secret plaintext")
+
+    # -- Request flow: RSA-OAEP unwrap then AES decrypt -------------------------
+    pkcs8 = b64u_decode(env["request"]["private_key_pkcs8_b64u"])
+    wrapped = b64u_decode(env["request"]["wrapped_key_b64u"])
+    r_raw_key = rsa_oaep_decrypt(wrapped, pkcs8)
+    r_ct = b64u_decode(env["request"]["ciphertext_b64u"])
+    r_iv = b64u_decode(env["request"]["iv_b64u"])
+    r_pt = aes_decrypt(r_ct, r_raw_key, r_iv).decode("utf-8")
+    _eq(r_pt, env["request"]["expected_plaintext"], "request plaintext")
+    if b64u_encode(r_raw_key) != env["request"]["content_aes_key_b64u"]:
+        _fail("request AES key recovery - RSA-OAEP failure")
+
+    # -- Passphrase (text) flow: outer AES decrypt THEN inner PP: unwrap --------
+    pp_key = b64u_decode(env["passphrase"]["aes_key_b64u"])
+    pp_iv = b64u_decode(env["passphrase"]["iv_b64u"])
+    pp_ct = b64u_decode(env["passphrase"]["ciphertext_b64u"])
+    pp_inner = aes_decrypt(pp_ct, pp_key, pp_iv)
+    pp_pt = unwrap_text_envelope(pp_inner, env["passphrase"]["passphrase"])
+    _eq(pp_pt, env["passphrase"]["expected_plaintext"], "passphrase plaintext")
+
+    # -- File flow: BSF1 decrypt (no passphrase) --------------------------------
+    f_blob = b64u_decode(env["file"]["blob_b64u"])
+    f_master = b64u_decode(env["file"]["master_key_b64u"])
+    f_name, f_mime, f_msg, f_content = file_envelope.decrypt(f_blob, f_master)
+    _eq(f_name, env["file"]["expected_filename"], "file filename")
+    _eq(f_mime, env["file"]["expected_mime"], "file mime")
+    _eq(f_msg.decode("utf-8"), env["file"]["expected_message"], "file message")
+    if b64u_encode(f_content) != env["file"]["expected_content_b64u"]:
+        _fail("file content bytes")
+
+    # -- File + passphrase flow: BSF1 decrypt WITH passphrase -------------------
+    fp_blob = b64u_decode(env["file_passphrase"]["blob_b64u"])
+    fp_master = b64u_decode(env["file_passphrase"]["master_key_b64u"])
+    fp_name, fp_mime, fp_msg, fp_content = file_envelope.decrypt(
+        fp_blob, fp_master, passphrase=env["file_passphrase"]["passphrase"]
+    )
+    _eq(fp_name, env["file_passphrase"]["expected_filename"], "file_passphrase filename")
+    _eq(fp_mime, env["file_passphrase"]["expected_mime"], "file_passphrase mime")
+    _eq(fp_msg.decode("utf-8"), env["file_passphrase"]["expected_message"], "file_passphrase message")
+    if b64u_encode(fp_content) != env["file_passphrase"]["expected_content_b64u"]:
+        _fail("file_passphrase content bytes")
+
+    print(
+        "CROSS-SDK ROUND-TRIP (Python decrypts JS): PASS - "
+        "text + request + passphrase + file + file_passphrase"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())