frutebox-node 0.1.0__py3-none-any.whl

frutebox/envelope.py

@@ -0,0 +1,77 @@
+"""What remains of the Python envelope: two SHAPE checks, and no cryptography.
+
+THE CRYPTOGRAPHY LIVED HERE AND WAS NEVER USED. `master_key`, `field_key`, `encrypt_field` and
+`decrypt_field` were deleted on 2026-09-22 (owner ruling) because nothing called them and nothing
+could. Their only Python consumers were `providers.encrypt_credentials`/`decrypt_credentials`,
+themselves uncalled, and a caller could not have been created without breaking the constraint the
+whole design rests on: **`frutebox-directory` holds neither `DATABASE_URL` nor `STEVAI_DATA_KEY`
+by design**, so it never sees a `valueEnc` row and `master_key()` raised on it. That is exactly the
+28 §O1 failure that had the live doctor reporting `EnvelopeError` for every provider on
+2026-09-18.
+
+DEAD CRYPTOGRAPHY IS WORSE THAN NO CRYPTOGRAPHY. It reads as protection while protecting nothing,
+and it is the first thing someone wires up in a hurry — which here would mean handing the
+provisioning service the key that decrypts every encrypted field in the product, to solve a
+problem that is only about provider API keys.
+
+THE REAL ENVELOPE IS `web/src/lib/crypto/identity-core.ts`. It runs in
+`web/src/app/api/internal/provider-credentials/route.ts`: `encryptField` on the PUT,
+`decryptField` on the GET, both under the master key the web app legitimately holds. That is where
+a credential is encrypted at rest (readme rule 10, no cloud KMS), and where it should be changed.
+
+WHAT IS LEFT, AND WHY IT IS NOT CRYPTOGRAPHY
+  - `mask()` — the doctor prints PRESENCE, never a value, a length or a tail.
+  - `looks_like_field_token()` — a SHAPE check so `resolve_credentials` can REFUSE ciphertext
+    rather than decrypt it. It reads the version byte and a length; it holds no key and decides
+    nothing safe.
+"""
+from __future__ import annotations
+
+import base64
+from typing import Optional
+
+#: Matches `VERSION` in identity-core.ts. A version byte on every token so the format can change
+#: without a migration that must guess what it is reading.
+VERSION = 1
+
+
+def mask(secret: Optional[str]) -> str:
+    """What `providers doctor` prints: PRESENCE, and nothing else.
+
+    It used to print `set (50 chars, ends 8l7y)`. The intent was "enough to recognise a key,
+    never enough to use one", and that reasoning is wrong twice over. The length narrows the
+    search space and identifies which credential format a provider issued; the last four
+    characters are secret material outright. The standing rule is that a secret is never printed
+    — not its value, not its length, not any part of it — and a doctor endpoint exists to be
+    pasted into a report, which is precisely where those details would travel.
+
+    "set" answers the only question the doctor is for: is a credential installed. Anything more
+    is the caller's curiosity, not the operator's need.
+    """
+    return "set" if (secret or "").strip() else "(unset)"
+
+
+def looks_like_field_token(value: str) -> bool:
+    """True when `value` has the shape of an `encrypt_field` token rather than a plaintext secret.
+
+    WHY THIS EXISTS (file 28 §O1). The provider-credential path decrypted twice: the web endpoint
+    returns plaintext, and `resolve_credentials` then decrypted it again. The two halves were each
+    tested in isolation and never against each other, so the break only ever showed as
+    `EnvelopeError` in a live doctor run.
+
+    Now that `resolve_credentials` treats what it receives as plaintext, the same class of mistake
+    would be SILENT and worse: ciphertext handed to a provider as an API key. This makes it loud.
+    It is a shape check, not a security boundary — the caller uses it to refuse, never to decide
+    that something is safe.
+
+    A token is base64url of `VERSION || iv(12) || tag(16) || ct`, so a plaintext key would have to
+    be valid base64url, decode to at least 29 bytes, AND begin with exactly our version byte.
+    """
+    s = (value or "").strip()
+    if not s:
+        return False
+    try:
+        packed = base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+    except Exception:
+        return False
+    return len(packed) >= 29 and packed[0] == VERSION

frutebox/envvars.py

@@ -0,0 +1,167 @@
+"""Dual-read environment lookup: FRUTEBOX_* first, STEVAI_* second.
+
+WHY THIS EXISTS
+The brand rename touches ~320 distinct STEVAI_* variable names that are set on
+LIVE, RUNNING services. Renaming a variable in code while the deployed service still sets the old
+name breaks that service the instant the new code ships — silently, because a missing env var
+usually reads as "unset" rather than as an error.
+
+This helper decouples the two halves. Code can move to FRUTEBOX_* today; deployments can keep
+setting STEVAI_* until someone gets round to them, in any order, with no flag day. When the last
+deployment has moved, the STEVAI_* arm becomes dead and can be deleted — and until then it is the
+only thing keeping production alive.
+
+    env("ADMIN_TOKEN")            -> $FRUTEBOX_ADMIN_TOKEN, else $STEVAI_ADMIN_TOKEN, else None
+    env("ADMIN_TOKEN", "dev")     -> ... else "dev"
+    env_bool("REQUIRE_ADMISSION") -> True for 1/true/yes/on (case-insensitive)
+
+Pass the BARE suffix, not the prefixed name: `env("ADMIN_TOKEN")`, never `env("STEVAI_ADMIN_TOKEN")`.
+Passing a prefixed name is a mistake that would otherwise look up FRUTEBOX_STEVAI_ADMIN_TOKEN and
+quietly find nothing, so it raises instead.
+"""
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+NEW_PREFIX = "FRUTEBOX_"
+OLD_PREFIX = "STEVAI_"
+
+_TRUE = {"1", "true", "yes", "on"}
+_FALSE = {"0", "false", "no", "off"}
+
+
+def _names(suffix: str) -> tuple[str, str]:
+    s = (suffix or "").strip()
+    if not s:
+        raise ValueError("env() needs a variable name")
+    if s.startswith(NEW_PREFIX) or s.startswith(OLD_PREFIX):
+        raise ValueError(
+            f"pass the bare suffix, not {s!r} — e.g. env('ADMIN_TOKEN'), not env('{s}')"
+        )
+    return NEW_PREFIX + s, OLD_PREFIX + s
+
+
+def env(suffix: str, default: Optional[str] = None) -> Optional[str]:
+    """FRUTEBOX_<suffix>, else STEVAI_<suffix>, else `default`.
+
+    An EMPTY value counts as set and wins, exactly as `os.environ.get` would treat it: a deployment
+    that deliberately blanks a variable must not silently fall through to the old one.
+    """
+    new, old = _names(suffix)
+    if new in os.environ:
+        return os.environ[new]
+    if old in os.environ:
+        return os.environ[old]
+    return default
+
+
+class MissingConfig(RuntimeError):
+    """A required variable is unset. Raised at import, so the process refuses to start."""
+
+
+def env_required(suffix: str, *, why: str = "") -> str:
+    """FRUTEBOX_<suffix>, else STEVAI_<suffix>. **No default. Unset is FATAL.**
+
+    WHY THERE IS NO DEFAULT HERE, AND WHY IT MATTERS MORE THAN IT LOOKS
+    These variables used to default to `https://stevai.com`. That domain is being removed, so
+    every one of those defaults was a time-bomb whose fuse is a deletion the owner is entitled
+    to perform without consulting the code.
+
+    `revocations.py` shows the shape of the damage. Admission FAILS CLOSED: an unreachable
+    revocation list refuses every node, which is correct. Point it at a dead domain and the
+    network stops admitting anyone at all — safely, and with logs blaming a revocation service
+    rather than a decommissioned domain. Safe and completely unreadable is the worst failure
+    mode this codebase produces.
+
+    An unset variable is a QUESTION. The honest answer is to stop and name it, not to guess the
+    old answer. Same rule `deploy-gateway.sh` already follows.
+
+    NOTE the deliberate asymmetry with code we SHIP: an SDK, desktop app or extension keeps a
+    default and points it at the new host, because a user's upgrade is not supervised and making
+    their client throw would be a worse failure than the one being removed.
+    """
+    new, old = _names(suffix)
+    val = os.environ.get(new, os.environ.get(old))
+    if val is None or not val.strip():
+        raise MissingConfig(
+            f"{new} is not set (nor {old}). {why or 'It has no default: the old default was '
+            'https://stevai.com, a domain being removed.'} Set it, e.g.:\n"
+            f"    export {new}=https://frutebox-web-qmatfu5ovq-ew.a.run.app")
+    return val
+
+
+def env_bool(suffix: str, default: bool = False) -> bool:
+    """The same lookup, parsed as a flag. Unrecognised values fall back to `default`."""
+    raw = env(suffix)
+    if raw is None:
+        return default
+    v = raw.strip().lower()
+    if v in _TRUE:
+        return True
+    if v in _FALSE:
+        return False
+    return default
+
+
+def env_int(suffix: str, default: int = 0) -> int:
+    """The same lookup, parsed as an int. Unparseable values fall back to `default`."""
+    raw = env(suffix)
+    if raw is None:
+        return default
+    try:
+        return int(raw.strip())
+    except (TypeError, ValueError):
+        return default
+
+
+def source_of(suffix: str) -> str:
+    """Which arm answered: "frutebox", "stevai" or "default". For migration reporting."""
+    new, old = _names(suffix)
+    if new in os.environ:
+        return "frutebox"
+    if old in os.environ:
+        return "stevai"
+    return "default"
+
+
+# --- the on-disk config directory -----------------------------------------------------------
+# Same problem as the variable names, one level up: every existing install has its state in
+# ~/.stevai. Renaming the path blind would not migrate that state, it would ORPHAN it — the
+# software would start up looking healthy and empty, which is worse than failing.
+
+import shutil
+from pathlib import Path
+
+NEW_DIR = ".frutebox"
+OLD_DIR = ".stevai"
+
+
+def config_dir(home: Optional[str] = None, *, migrate: bool = False) -> Path:
+    """Where this machine keeps its config: ~/.frutebox, else ~/.stevai, else ~/.frutebox.
+
+    Resolution mirrors `env()`: the new name wins if it exists, the old one is honoured while
+    it is all that exists, and a fresh install gets the new name. `migrate=True` performs a
+    one-time MOVE of the old directory to the new one and is what a CLI should pass on startup;
+    it is off by default so that merely *reading* the path can never mutate the disk.
+    """
+    root = Path(home) if home else Path.home()
+    new, old = root / NEW_DIR, root / OLD_DIR
+    if new.exists():
+        return new
+    if old.exists():
+        if migrate:
+            shutil.move(str(old), str(new))       # atomic on the same filesystem
+            return new
+        return old
+    return new
+
+
+def config_dir_source(home: Optional[str] = None) -> str:
+    """Which directory answered: "frutebox", "stevai" or "new". For migration reporting."""
+    root = Path(home) if home else Path.home()
+    if (root / NEW_DIR).exists():
+        return "frutebox"
+    if (root / OLD_DIR).exists():
+        return "stevai"
+    return "new"