1 files changed, 69 insertions, 0 deletions
diff --git a/packages/meshbay-cli/src/meshbay_cli/client/keys.py b/packages/meshbay-cli/src/meshbay_cli/client/keys.py
index ecf44a5..2ac6f2c 100644
--- a/packages/meshbay-cli/src/meshbay_cli/client/keys.py
+++ b/packages/meshbay-cli/src/meshbay_cli/client/keys.py
@@ -135,6 +135,75 @@ def bundle_is_current(bundle_b64: str, *, master: bytes, user_id: str,
         return False
 
 
+def opens_under(bundle_b64: str, master: bytes, *, user_id: str,
+                node_pk: str) -> dict | None:
+    """The `{skEd, skX}` of an `MBK3` bundle sealed under `master`, else None."""
+    try:
+        raw = unb64(bundle_b64)
+        if raw[:4] != BUNDLE_MAGIC:
+            return None
+        aad = f"meshbay:bundle:v3|{user_id}|{node_pk}".encode()
+        return json.loads(AESGCM(node_bundle_key(master, node_pk)).decrypt(
+            raw[5:17], raw[17:], aad))
+    except Exception:
+        return None
+
+
+# ── The recovery key (docs/MESHBAY_DESIGN.md §3.6) ───────────────────────────
+#
+# 32 random bytes `R`, shown as 13 groups of four Base32 characters; the key
+# that seals a recovery copy is HKDF(R, "meshbay:recovery:v1:" + username),
+# used as it is — not per node — with the bundle's associated data and pepper
+# version 0. As `keyderive.js` `generateRecoveryKey`/`deriveRecoveryKey`.
+
+_B32 = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"
+
+
+def generate_recovery() -> tuple[bytes, str]:
+    """`R`, and the grouped mnemonic a person keeps."""
+    raw = os.urandom(32)
+    return raw, recovery_mnemonic(raw)
+
+
+def recovery_mnemonic(raw: bytes) -> str:
+    text = base64.b32encode(raw).decode().rstrip("=")
+    return " ".join(text[i:i + 4] for i in range(0, len(text), 4))
+
+
+def recovery_bytes(mnemonic: str) -> bytes:
+    """`R` from its mnemonic, however spaced or cased; ValueError if it is not one."""
+    clean = "".join(c for c in mnemonic.upper() if c.isalnum())
+    if any(c not in _B32 for c in clean):
+        raise ValueError("a recovery key is letters A to Z and digits 2 to 7")
+    raw = base64.b32decode(clean + "=" * (-len(clean) % 8)) if clean else b""
+    if len(raw) < 32:
+        raise ValueError("this recovery key is too short")
+    return raw[:32]
+
+
+def recovery_key(raw: bytes, username: str) -> bytes:
+    return hkdf(raw, f"meshbay:recovery:v1:{username}")
+
+
+def seal_recovery(keys: dict, *, rkey: bytes, user_id: str, node_pk: str) -> str:
+    nonce = os.urandom(12)
+    aad = f"meshbay:bundle:v3|{user_id}|{node_pk}".encode()
+    plain = json.dumps({"skEd": keys["skEd"], "skX": keys["skX"]}).encode()
+    return b64(BUNDLE_MAGIC + bytes([0]) + nonce + AESGCM(rkey).encrypt(nonce, plain, aad))
+
+
+def open_recovery(bundle_b64: str, *, rkey: bytes, user_id: str, node_pk: str) -> dict:
+    try:
+        raw = unb64(bundle_b64)
+        if raw[:4] != BUNDLE_MAGIC:
+            raise ValueError
+        aad = f"meshbay:bundle:v3|{user_id}|{node_pk}".encode()
+        return json.loads(AESGCM(rkey).decrypt(raw[5:17], raw[17:], aad))
+    except Exception as e:
+        raise BundleError("the node's recovery copy of your keys does not open with "
+                          "this recovery key") from e
+
+
 @dataclass
 class Identity:
     """One account's keys on one node."""