compartment 2.1__tar.gz → 2.2__tar.gz

{compartment-2.1 → compartment-2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compartment
-Version: 2.1
+Version: 2.2
 Summary: Compartment - high-security, fully offline, encrypted vector memory for AI agents (MCP)
 Project-URL: Homepage, https://github.com/MaxFreedomPollard/Compartment
 Project-URL: Source, https://github.com/MaxFreedomPollard/Compartment

{compartment-2.1 → compartment-2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "compartment"
-version = "2.1"
+version = "2.2"
 description = "Compartment - high-security, fully offline, encrypted vector memory for AI agents (MCP)"
 readme = "README.md"
 requires-python = ">=3.11"

{compartment-2.1 → compartment-2.2}/src/compartment/__init__.py

@@ -1,6 +1,6 @@
 """Compartment - high-security, fully offline, encrypted vector memory for AI agents."""
 
-__version__ = "2.1"
+__version__ = "2.2"
 
 from . import offline_guard as _og
 

{compartment-2.1 → compartment-2.2}/src/compartment/crypto.py

@@ -19,6 +19,8 @@ from nacl.bindings import (
     crypto_aead_xchacha20poly1305_ietf_encrypt,
 )
 
+from . import wire
+
 KEY_LEN = 32
 NONCE_LEN = 24
 
@@ -81,6 +83,35 @@ def unseal(key: bytes, blob: bytes, aad: bytes = b"") -> bytes:
         ) from exc
 
 
+def unseal_which(key: bytes, blob: bytes, aad: bytes,
+                 legacy: tuple[bytes, ...] = ()) -> tuple[bytes, bytes]:
+    """unseal(), accepting associated data written by an older build.
+
+    Returns (plaintext, the aad that actually authenticated), so a caller can
+    tell a migrated blob from one still carrying a legacy label and rewrite it.
+
+    The current spelling is tried first, so anything already migrated costs
+    exactly one AEAD open. Legacy spellings are tried in order only after that
+    fails, which is what lets a pre-rename vault open at all. If none of them
+    authenticate the data really is tampered with, or the key really is wrong,
+    and the original error is raised."""
+    try:
+        return unseal(key, blob, aad=aad), aad
+    except TamperError:
+        for old in legacy:
+            try:
+                return unseal(key, blob, aad=old), old
+            except TamperError:
+                continue
+        raise
+
+
+def unseal_any(key: bytes, blob: bytes, aad: bytes,
+               legacy: tuple[bytes, ...] = ()) -> bytes:
+    """unseal_which() when the caller does not care which label was used."""
+    return unseal_which(key, blob, aad, legacy)[0]
+
+
 def wipe(buf: bytearray) -> None:
     """Best-effort zeroization (Python cannot guarantee no copies exist)."""
     for i in range(len(buf)):
@@ -99,7 +130,7 @@ def make_passphrase_slot(master_key: bytes, passphrase: str, kdf: dict | None =
         "type": "passphrase",
         "kdf": kdf,
         "salt": salt.hex(),
-        "wrapped": seal(wrap_key, master_key, aad=b"engram-keyslot").hex(),
+        "wrapped": seal(wrap_key, master_key, aad=wire.KEYSLOT).hex(),
     }
 
 
@@ -118,7 +149,7 @@ def make_recovery_slot(master_key: bytes, kdf: dict | None = None) -> tuple[dict
 # Domain separator between the knowledge factor (passphrase) and the
 # possession factor (keyfile bytes) before the KDF. Both factors feed
 # Argon2id, so two-factor unlock is enforced by arithmetic, not policy.
-KEYFILE_SEP = b"\x1f engram-2fa \x1f"
+KEYFILE_SEP = wire.KEYFILE_SEP
 KEYFILE_LEN = 32
 
 
@@ -137,19 +168,57 @@ def make_keyfile_slot(master_key: bytes, passphrase: str, keyfile: bytes,
         "kdf": kdf,
         "salt": salt.hex(),
         "keyfile_id": sha256(keyfile)[:16],   # UX only: detect the WRONG file
-        "wrapped": seal(wrap_key, master_key, aad=b"engram-keyslot").hex(),
+        "wrapped": seal(wrap_key, master_key, aad=wire.KEYSLOT).hex(),
     }
 
 
-def open_slot(slot: dict, secret: str, keyfile: bytes | None = None) -> bytes:
-    """Unwrap the master key from one slot."""
+def _slot_secrets(slot: dict, secret: str, keyfile: bytes | None) -> list[bytes]:
+    """The KDF inputs worth trying for this slot, current spelling first.
+
+    Only a two-factor slot has more than one. Its separator is a KDF input
+    rather than associated data, so an older separator derives a different
+    wrap key and can only be ruled out by deriving again."""
     raw = secret.encode("utf-8")
-    if slot["type"] == "passphrase+keyfile":
-        if keyfile is None:
-            raise CryptoError("This keyslot requires a keyfile")
-        raw = raw + KEYFILE_SEP + keyfile
-    wrap_key = derive_key(raw, bytes.fromhex(slot["salt"]), slot["kdf"])
-    return unseal(wrap_key, bytes.fromhex(slot["wrapped"]), aad=b"engram-keyslot")
+    if slot["type"] != "passphrase+keyfile":
+        return [raw]
+    if keyfile is None:
+        raise CryptoError("This keyslot requires a keyfile")
+    return [raw + sep + keyfile
+            for sep in (wire.KEYFILE_SEP, *wire.KEYFILE_SEP_LEGACY)]
+
+
+def open_slot(slot: dict, secret: str, keyfile: bytes | None = None) -> bytes:
+    """Unwrap the master key from one slot.
+
+    A slot written before 2.2 carries the legacy associated data, and a
+    two-factor one the legacy keyfile separator. Both still open. The slot is
+    then rewritten in place under the current spelling, so it migrates the
+    first time its credential is used; the caller persists that by saving the
+    header. Re-sealing only happens when something was actually legacy, or
+    every unlock would dirty the header and force a needless vault rewrite."""
+    salt, kdf = bytes.fromhex(slot["salt"]), slot["kdf"]
+    wrapped = bytes.fromhex(slot["wrapped"])
+    failure: TamperError | None = None
+    for i, raw in enumerate(_slot_secrets(slot, secret, keyfile)):
+        wrap_key = derive_key(raw, salt, kdf)
+        try:
+            master, used = unseal_which(wrap_key, wrapped, wire.KEYSLOT,
+                                        wire.KEYSLOT_LEGACY)
+        except TamperError as exc:
+            failure = exc
+            continue
+        if i:
+            # legacy separator: the wrap key itself is stale, so the slot has
+            # to be built again from scratch (a second Argon2id pass, once).
+            fresh = make_keyfile_slot(master, secret, keyfile, kdf)
+            fresh["type"] = slot["type"]
+            slot.clear()
+            slot.update(fresh)
+        elif used != wire.KEYSLOT:
+            # same wrap key, only the associated data moves. Free.
+            slot["wrapped"] = seal(wrap_key, master, aad=wire.KEYSLOT).hex()
+        return master
+    raise failure if failure is not None else TamperError("Keyslot did not open")
 
 
 def unwrap_master(keyslots: list[dict], secret: str,
@@ -190,16 +259,20 @@ def normalize_recovery(text: str) -> str:
 # Per-record keys → crypto-shred
 # ---------------------------------------------------------------------------
 
+def wrap_record_key(master_key: bytes, record_id: str, record_key: bytes) -> bytes:
+    aad, _ = wire.record_key(record_id)
+    return seal(master_key, record_key, aad=aad)
+
+
 def new_record_key(master_key: bytes, record_id: str) -> tuple[bytes, bytes]:
     """Returns (record_key, wrapped_record_key). Destroying the wrapped key
     makes the record's ciphertext permanently undecryptable (crypto-shred)."""
     rk = new_key()
-    wrapped = seal(master_key, rk, aad=b"engram-record:" + record_id.encode())
-    return rk, wrapped
+    return rk, wrap_record_key(master_key, record_id, rk)
 
 
 def unwrap_record_key(master_key: bytes, record_id: str, wrapped: bytes) -> bytes:
-    return unseal(master_key, wrapped, aad=b"engram-record:" + record_id.encode())
+    return unseal_any(master_key, wrapped, *wire.record_key(record_id))
 
 
 # 256 short, common, distinct words for recovery phrases (16 words = 128 bits).

{compartment-2.1 → compartment-2.2}/src/compartment/menubar.py

@@ -397,6 +397,7 @@ def run(vault: str | None = None, show: bool = False,
                             NSFont, NSImage, NSMakeRect, NSMenu, NSMenuItem,
                             NSPanel, NSPopover, NSScreen, NSSegmentedControl,
                             NSClipView, NSScrollView,
+                            NSBitmapImageRep, NSGraphicsContext,
                             NSSecureTextField, NSStackView, NSStatusBar,
                             NSSwitch, NSTextField,
                             NSButton, NSView, NSViewController,
@@ -852,14 +853,33 @@ def run(vault: str | None = None, show: bool = False,
     _d("controller ready")
 
     if render_to:
-        # app.run() normally does this; without it the text system is not up
-        # and the snapshot comes out with controls but no glyphs at all.
+        # app.run() normally does this; without it the text system is not up.
         app.finishLaunching()
         body = ctrl.buildBody()
         body.layoutSubtreeIfNeeded()
         bounds = body.bounds()
-        rep = body.bitmapImageRepForCachingDisplayInRect_(bounds)
-        body.cacheDisplayInRect_toBitmapImageRep_(bounds, rep)
+        # Render through PDF, not cacheDisplayInRect. Caching a view that
+        # belongs to no window gives you the switches and the segmented
+        # control and not one glyph of text, because there is no window
+        # backing store for the text system to lay glyphs into. Ordering an
+        # offscreen window in does not help either: it draws as an inactive
+        # window, so even the controls lose their tint. The PDF path records
+        # glyphs vectorially with their fonts embedded and needs no window at
+        # all, so it captures the panel exactly as designed. Rasterise at 2x
+        # for a Retina-sharp asset.
+        pdf = body.dataWithPDFInsideRect_(bounds)
+        w, h = bounds.size.width, bounds.size.height
+        image = NSImage.alloc().initWithData_(pdf)
+        rep = (NSBitmapImageRep.alloc()
+               .initWithBitmapDataPlanes_pixelsWide_pixelsHigh_bitsPerSample_samplesPerPixel_hasAlpha_isPlanar_colorSpaceName_bytesPerRow_bitsPerPixel_(
+                   None, int(w * 2), int(h * 2), 8, 4, True, False,
+                   "NSCalibratedRGBColorSpace", 0, 0))
+        rep.setSize_((w, h))
+        NSGraphicsContext.saveGraphicsState()
+        NSGraphicsContext.setCurrentContext_(
+            NSGraphicsContext.graphicsContextWithBitmapImageRep_(rep))
+        image.drawInRect_(NSMakeRect(0, 0, w, h))
+        NSGraphicsContext.restoreGraphicsState()
         png = rep.representationUsingType_properties_(4, {})   # 4 = PNG
         ok = png.writeToFile_atomically_(render_to, True)
         print(f"rendered popover -> {render_to}" if ok

{compartment-2.1 → compartment-2.2}/src/compartment/packs.py

@@ -20,7 +20,7 @@ import struct
 import numpy as np
 from nacl.signing import SigningKey, VerifyKey
 
-from . import crypto
+from . import crypto, wire
 from .crypto import CryptoError, TamperError
 from .vaultfile import pack_sections, unpack_sections
 
@@ -71,7 +71,7 @@ def build_pack(*, name: str, version: str, description: str, records: list[dict]
     if passphrase is not None:
         salt = secrets.token_bytes(16)
         key = crypto.derive_key(passphrase.encode(), salt)
-        body = crypto.seal(key, body, aad=b"engram-pack:" + name.encode())
+        body = crypto.seal(key, body, aad=wire.pack(name)[0])
         header["kdf"] = crypto.DEFAULT_KDF
         header["salt"] = salt.hex()
     header["content_sha256"] = crypto.sha256(body)
@@ -119,7 +119,7 @@ def read_pack(blob: bytes, passphrase: str | None = None
             raise PackError(f"Pack {header['name']!r} is encrypted; passphrase required")
         key = crypto.derive_key(passphrase.encode(), bytes.fromhex(header["salt"]),
                                 header["kdf"])
-        body = crypto.unseal(key, body, aad=b"engram-pack:" + header["name"].encode())
+        body = crypto.unseal_any(key, body, *wire.pack(header["name"]))
 
     sections = unpack_sections(body)
     records = [json.loads(l) for l in

{compartment-2.1 → compartment-2.2}/src/compartment/session.py

@@ -25,7 +25,7 @@ import os
 import stat
 from pathlib import Path
 
-from . import crypto
+from . import crypto, wire
 from .crypto import CryptoError, TamperError
 from .platforms import boot_time, machine_id
 
@@ -49,17 +49,16 @@ def _uid() -> str:
     return str(getuid()) if getuid else os.environ.get("USERNAME", "user")
 
 
-def _boot_key() -> bytes:
+def _boot_key(token: str = wire.SESSION_TOKEN) -> bytes:
     """Wrap key valid only for this boot session of this user on this
     machine. Uses the stable hardware machine id, NOT the hostname -
     macOS renames the host per network, which must not relock the vault."""
-    token = "|".join((
-        "engram-session-v2",
+    return hashlib.sha256("|".join((
+        token,
         _boot_time(),
         _uid(),
         machine_id(),
-    ))
-    return hashlib.sha256(token.encode()).digest()
+    )).encode()).digest()
 
 
 def _canon(vault_path: str) -> str:
@@ -83,7 +82,7 @@ def store(vault_path: str, master_key: bytes) -> Path:
     """Persist a boot-bound unlock credential for this vault."""
     p = _file_for(vault_path)
     blob = crypto.seal(_boot_key(), master_key,
-                       aad=b"engram-session:" + _canon(vault_path).encode())
+                       aad=wire.session(_canon(vault_path))[0])
     p.write_text(json.dumps({"vault": _canon(vault_path),
                              "wrapped": blob.hex()}), encoding="utf-8")
     os.chmod(p, stat.S_IRUSR | stat.S_IWUSR)  # 0600
@@ -92,15 +91,29 @@ def store(vault_path: str, master_key: bytes) -> Path:
 
 def get(vault_path: str) -> bytes | None:
     """Return the master key if a credential exists AND we are still in the
-    same boot session; otherwise remove the stale file and return None."""
+    same boot session; otherwise remove the stale file and return None.
+
+    A credential written before 2.2 is bound to the older token and sealed
+    under the older associated data. It is accepted and then rewritten in the
+    current form, so upgrading Compartment does not relock a vault that was
+    already open."""
     p = _file_for(vault_path)
     if not p.is_file():
         return None
+    canon = _canon(vault_path)
+    aad, legacy_aad = wire.session(canon)
     try:
-        data = json.loads(p.read_text(encoding="utf-8"))
-        return crypto.unseal(
-            _boot_key(), bytes.fromhex(data["wrapped"]),
-            aad=b"engram-session:" + _canon(vault_path).encode())
+        blob = bytes.fromhex(json.loads(p.read_text(encoding="utf-8"))["wrapped"])
+        for token in (wire.SESSION_TOKEN, *wire.SESSION_TOKEN_LEGACY):
+            try:
+                key, used = crypto.unseal_which(_boot_key(token), blob,
+                                                aad, legacy_aad)
+            except TamperError:
+                continue
+            if token != wire.SESSION_TOKEN or used != aad:
+                store(vault_path, key)
+            return key
+        raise TamperError("No boot-session token opened the credential")
     except (TamperError, CryptoError, ValueError, KeyError, OSError):
         # different boot (restart/power loss) or corrupt file → locked
         try:

{compartment-2.1 → compartment-2.2}/src/compartment/store.py

@@ -14,7 +14,7 @@ import uuid
 
 import numpy as np
 
-from . import crypto
+from . import crypto, wire
 from .crypto import CryptoError
 
 SCHEMA = """
@@ -110,7 +110,7 @@ class Store:
         rid = record_id or uuid.uuid4().hex
         rk, wrapped = crypto.new_record_key(master_key, rid)
         ct = crypto.seal(rk, crypto.canonical_json({"text": text}),
-                         aad=b"engram-record-body:" + rid.encode())
+                         aad=wire.record_body(rid)[0])
         now = time.time()
         self.conn.execute(
             "INSERT INTO records (id, ikey, ns, ct, key_wrapped, vec, dim, tags, importance,"
@@ -129,9 +129,35 @@ class Store:
 
     def decrypt_text(self, row: sqlite3.Row, master_key: bytes) -> str:
         rk = crypto.unwrap_record_key(master_key, row["id"], row["key_wrapped"])
-        body = crypto.unseal(rk, row["ct"], aad=b"engram-record-body:" + row["id"].encode())
+        body = crypto.unseal_any(rk, row["ct"], *wire.record_body(row["id"]))
         return json.loads(body)["text"]
 
+    def migrate_wire(self, master_key: bytes) -> int:
+        """Rewrite every record under the current associated data.
+
+        Records are the one place the labels do not migrate for free: a row's
+        key wrap and ciphertext are written on insert and never touched again,
+        so without this pass every read of every pre-2.2 record would pay a
+        failed AEAD open before the one that works, forever. Vault.unlock
+        calls this once and records it in the header.
+
+        The record key is kept and re-wrapped rather than rotated, so the
+        plaintext is the only thing that round-trips. Nothing is written to
+        disk here: this mutates the in-memory database, and the caller's
+        save() is what makes it real, atomically. If any row fails to decrypt
+        the error propagates and no save happens, so a vault is never left
+        half-converted."""
+        rows = self.conn.execute("SELECT id, ct, key_wrapped FROM records").fetchall()
+        for row in rows:
+            rid = row["id"]
+            rk = crypto.unwrap_record_key(master_key, rid, row["key_wrapped"])
+            body = crypto.unseal_any(rk, row["ct"], *wire.record_body(rid))
+            self.conn.execute(
+                "UPDATE records SET ct = ?, key_wrapped = ? WHERE id = ?",
+                (crypto.seal(rk, body, aad=wire.record_body(rid)[0]),
+                 crypto.wrap_record_key(master_key, rid, rk), rid))
+        return len(rows)
+
     def delete(self, record_id: str, shred: bool) -> bool:
         """Delete a record. shred=True also VACUUMs so the content (including
         FTS tokens and freed pages) is gone from the next serialized image,

{compartment-2.1 → compartment-2.2}/src/compartment/vault.py

@@ -25,7 +25,7 @@ import uuid
 
 import numpy as np
 
-from . import audit, crypto, vaultfile
+from . import audit, crypto, vaultfile, wire
 from .platforms import FileLock
 from .acl import AclError, VaultConfig
 from .crypto import CryptoError, TamperError
@@ -140,7 +140,7 @@ class Vault:
             keyslots=[slot_pw],
             payload_len=0,
             model={"name": model_name, "sha256": emb.model_sha256, "dim": emb.dim},
-            extra={"creator": creator},
+            extra={"creator": creator, "wire": wire.WIRE_FORMAT},
         )
         db = Store()
         db.set_meta("model_name", model_name)
@@ -164,9 +164,14 @@ class Vault:
         if raw_key is not None:
             master = raw_key
             # verify the key actually opens this vault (AEAD auth below)
+            slots_migrated = False
         elif passphrase is not None:
+            # open_slot rewrites a pre-2.2 keyslot in place as it opens it, so
+            # compare rather than trust: whatever changed has to reach disk.
+            before = crypto.canonical_json(loaded.header.keyslots)
             master = crypto.unwrap_master(loaded.header.keyslots, passphrase,
                                           keyfile=keyfile)
+            slots_migrated = crypto.canonical_json(loaded.header.keyslots) != before
         else:
             raise CryptoError("No credential provided (passphrase or key)")
         sections = vaultfile.decrypt_payload(loaded.header, loaded.payload_ct, master)
@@ -180,7 +185,8 @@ class Vault:
         for e in entries:
             v._replay(e)
         merged = v._merge_legacy_starter()
-        if entries or loaded.truncated_tail or merged:
+        rewired = v._migrate_wire_format()
+        if entries or loaded.truncated_tail or merged or rewired or slots_migrated:
             if loaded.truncated_tail:
                 print("notice: discarded one unacknowledged (crash-truncated) write")
             v.save()  # compact replayed journal into the payload
@@ -199,6 +205,24 @@ class Vault:
         v._rebuild_index()
         return v
 
+    def _migrate_wire_format(self) -> int:
+        """Bring a vault written by an older build onto the current labels.
+
+        Compartment was engRAM until 1.15.0 and the name was still in the
+        bytes until 2.2: associated data, KDF context, keychain identity. See
+        wire.py for what those are and why they are not branding.
+
+        Almost all of it moves for free, because the payload and journal are
+        resealed on every save anyway. Records are the exception, so they get
+        an explicit pass here. It runs once, gated on a header marker, and
+        writes nothing itself: the caller's save() commits the whole thing
+        atomically, or an exception means none of it lands."""
+        if self.header.extra.get("wire", 1) >= wire.WIRE_FORMAT:
+            return 0
+        n = self.db.migrate_wire(self._master)
+        self.header.extra["wire"] = wire.WIRE_FORMAT
+        return n or 1   # truthy even for an empty vault: the marker must save
+
     def _merge_legacy_starter(self) -> int:
         """One-time reorganization: fold the legacy read-only packs/starter
         section into "main", so starting memories are ordinary memories -
@@ -822,21 +846,33 @@ class Vault:
 # macOS Keychain integration (optional keyslot type "keychain")
 # ---------------------------------------------------------------------------
 
-def _keychain_service(path: str) -> str:
-    """Keychain identity for a vault.
+def _keychain_names(path: str) -> list[tuple[str, str]]:
+    """(account, service) pairs identifying this vault's Keychain item,
+    current spelling first.
 
-    Frozen at the pre-rename spelling, like the on-disk constants: this names
-    a credential macOS already stored. Renaming it does not migrate anything,
-    it just stops finding the item, and the vault reports itself locked with
-    no indication why."""
-    return f"engram-vault:{os.path.abspath(path)}"
+    These name a credential macOS has already stored, so they behave like the
+    on-disk labels: renaming does not move the item, it just stops finding it,
+    and the vault would report itself locked with no indication why. The
+    legacy pair is therefore still looked up, and keychain_get moves the item
+    across the first time it finds one."""
+    abspath = os.path.abspath(path)
+    pairs = [(wire.KEYCHAIN_ACCOUNT, wire.KEYCHAIN_SERVICE + abspath)]
+    pairs += [(acct, svc + abspath)
+              for acct in wire.KEYCHAIN_ACCOUNT_LEGACY
+              for svc in wire.KEYCHAIN_SERVICE_LEGACY]
+    return pairs
+
+
+def _keychain_service(path: str) -> str:
+    return wire.KEYCHAIN_SERVICE + os.path.abspath(path)
 
 
 def keychain_store(path: str, master_key: bytes) -> None:
     if platform.system() != "Darwin":
         raise CryptoError("Keychain unlock is only available on macOS")
     subprocess.run(
-        ["security", "add-generic-password", "-U", "-a", "engram",
+        ["security", "add-generic-password", "-U",
+         "-a", wire.KEYCHAIN_ACCOUNT,
          "-s", _keychain_service(path), "-w", master_key.hex()],
         check=True, capture_output=True)
 
@@ -844,23 +880,35 @@ def keychain_store(path: str, master_key: bytes) -> None:
 def keychain_get(path: str) -> bytes | None:
     if platform.system() != "Darwin":
         return None
-    r = subprocess.run(
-        ["security", "find-generic-password", "-a", "engram",
-         "-s", _keychain_service(path), "-w"],
-        capture_output=True, text=True)
-    if r.returncode != 0:
-        return None
-    try:
-        return bytes.fromhex(r.stdout.strip())
-    except ValueError:
-        return None
+    for i, (account, service) in enumerate(_keychain_names(path)):
+        r = subprocess.run(
+            ["security", "find-generic-password", "-a", account,
+             "-s", service, "-w"],
+            capture_output=True, text=True)
+        if r.returncode != 0:
+            continue
+        try:
+            key = bytes.fromhex(r.stdout.strip())
+        except ValueError:
+            return None
+        if i:
+            # found under the pre-rename name: re-file it, then drop the old
+            # item so this lookup costs one call again from here on.
+            keychain_store(path, key)
+            subprocess.run(
+                ["security", "delete-generic-password", "-a", account,
+                 "-s", service], capture_output=True)
+        return key
+    return None
 
 
 def keychain_clear(path: str) -> bool:
     if platform.system() != "Darwin":
         return False
-    r = subprocess.run(
-        ["security", "delete-generic-password", "-a", "engram",
-         "-s", _keychain_service(path)],
-        capture_output=True)
-    return r.returncode == 0
+    cleared = False
+    for account, service in _keychain_names(path):
+        r = subprocess.run(
+            ["security", "delete-generic-password", "-a", account,
+             "-s", service], capture_output=True)
+        cleared = cleared or r.returncode == 0
+    return cleared

{compartment-2.1 → compartment-2.2}/src/compartment/vaultfile.py

@@ -23,7 +23,7 @@ from dataclasses import dataclass, field
 
 from nacl.signing import SigningKey, VerifyKey
 
-from . import crypto
+from . import crypto, wire
 from .crypto import CryptoError, TamperError
 
 MAGIC = b"NUCV"
@@ -94,11 +94,11 @@ def _atomic_replace(tmp: str, path: str) -> None:
 
 
 def _payload_aad(vault_id: str) -> bytes:
-    return b"engram-payload:" + vault_id.encode()
+    return wire.payload(vault_id)[0]
 
 
 def _journal_aad(vault_id: str, seq: int) -> bytes:
-    return b"engram-journal:" + vault_id.encode() + b":" + struct.pack(">Q", seq)
+    return wire.journal(vault_id, seq)[0]
 
 
 # ---------------------------------------------------------------------------
@@ -188,14 +188,16 @@ def read_vault_file(path: str) -> LoadedVaultFile:
 
 
 def decrypt_payload(header: VaultHeader, payload_ct: bytes, master_key: bytes) -> dict[str, bytes]:
-    plain = crypto.unseal(master_key, payload_ct, aad=_payload_aad(header.vault_id))
+    plain = crypto.unseal_any(master_key, payload_ct, *wire.payload(header.vault_id))
     return unpack_sections(plain)
 
 
 def decrypt_journal(header: VaultHeader, journal_cts: list[bytes], master_key: bytes) -> list[dict]:
+    """Entries are decrypted one at a time and each falls back on its own, so
+    a vault upgraded mid-journal (older entries, newer appends) still replays."""
     entries = []
     for seq, ct in enumerate(journal_cts):
-        plain = crypto.unseal(master_key, ct, aad=_journal_aad(header.vault_id, seq))
+        plain = crypto.unseal_any(master_key, ct, *wire.journal(header.vault_id, seq))
         entries.append(json.loads(plain))
     return entries
 

compartment-2.2/src/compartment/wire.py

@@ -0,0 +1,130 @@
+"""The byte strings Compartment writes into vaults, packs and session files.
+
+None of this is naming. Every constant below is AEAD associated data, a KDF
+context label or a credential identifier, which means it is baked into bytes
+that are already on disk. Changing one does not rename anything: it makes data
+written under the old spelling undecryptable.
+
+So each constant comes as a pair. The plain name is what gets written. The
+`_LEGACY` tuple beside it is every spelling that has ever been written and
+must still open. Compartment was called engRAM until 1.15.0, so anything
+created before then carries `engram` in its bytes.
+
+Reading tries the current spelling first and falls back through the legacy
+ones (`crypto.unseal_any`). Writing only ever uses the current spelling. A
+vault made by an older build therefore opens normally, and `Vault.unlock`
+rewrites it in the current format once, on the spot. There is nothing for the
+user to run and nothing to convert.
+
+If you are modifying this file: to add a label, give it a value and an empty
+legacy tuple. To change one, move the old value into its legacy tuple and
+never delete it. A legacy entry removed is a vault nobody can open again.
+"""
+from __future__ import annotations
+
+import struct
+
+# Bumped when any label below changes. `Vault.unlock` compares it against
+# `header.extra["wire"]` to decide whether a vault needs rewriting, so this is
+# the one number that says "these bytes are current".
+#   1 = engRAM spelling, everything up to 2.1
+#   2 = Compartment spelling
+WIRE_FORMAT = 2
+
+# --- keyslots --------------------------------------------------------------
+
+# Associated data wrapping the vault master key. The most load-bearing string
+# in the project: if a keyslot will not unseal, the vault is gone.
+KEYSLOT = b"compartment-keyslot"
+KEYSLOT_LEGACY = (b"engram-keyslot",)
+
+# Domain separator between the knowledge factor (passphrase) and the
+# possession factor (keyfile bytes). This one is a KDF *input*, not associated
+# data, so an old separator produces a different wrap key and costs a second
+# Argon2id pass to migrate. See crypto.open_slot.
+KEYFILE_SEP = b"\x1f compartment-2fa \x1f"
+KEYFILE_SEP_LEGACY = (b"\x1f engram-2fa \x1f",)
+
+# --- vault file ------------------------------------------------------------
+
+_PAYLOAD = b"compartment-payload:"
+_PAYLOAD_LEGACY = (b"engram-payload:",)
+
+_JOURNAL = b"compartment-journal:"
+_JOURNAL_LEGACY = (b"engram-journal:",)
+
+# --- records ---------------------------------------------------------------
+
+_RECORD_KEY = b"compartment-record:"
+_RECORD_KEY_LEGACY = (b"engram-record:",)
+
+_RECORD_BODY = b"compartment-record-body:"
+_RECORD_BODY_LEGACY = (b"engram-record-body:",)
+
+# --- memory packs ----------------------------------------------------------
+
+_PACK = b"compartment-pack:"
+_PACK_LEGACY = (b"engram-pack:",)
+
+# --- boot session credential ----------------------------------------------
+
+_SESSION = b"compartment-session:"
+_SESSION_LEGACY = (b"engram-session:",)
+
+# Hashed into the boot-bound wrap key. Not associated data, but the same
+# hazard: change it and every live session file stops opening, which locks
+# every unlocked vault on the machine until the user types a passphrase again.
+SESSION_TOKEN = "compartment-session-v3"
+SESSION_TOKEN_LEGACY = ("engram-session-v2",)
+
+# --- macOS Keychain --------------------------------------------------------
+
+# Names an item macOS has already stored. A rename here does not move the
+# item, it just stops finding it, so keychain_get migrates on the way past.
+KEYCHAIN_SERVICE = "compartment-vault:"
+KEYCHAIN_SERVICE_LEGACY = ("engram-vault:",)
+
+KEYCHAIN_ACCOUNT = "compartment"
+KEYCHAIN_ACCOUNT_LEGACY = ("engram",)
+
+
+# ---------------------------------------------------------------------------
+# Labels that carry an identifier. Each returns (current, legacy_forms) ready
+# to splat into crypto.unseal_any.
+# ---------------------------------------------------------------------------
+
+def _with(current: bytes, legacy: tuple[bytes, ...], tail: bytes
+          ) -> tuple[bytes, tuple[bytes, ...]]:
+    return current + tail, tuple(old + tail for old in legacy)
+
+
+def payload(vault_id: str) -> tuple[bytes, tuple[bytes, ...]]:
+    """Associated data over the whole sealed payload."""
+    return _with(_PAYLOAD, _PAYLOAD_LEGACY, vault_id.encode())
+
+
+def journal(vault_id: str, seq: int) -> tuple[bytes, tuple[bytes, ...]]:
+    """Associated data over one journal entry. The sequence number is bound in
+    so entries cannot be reordered or replayed."""
+    return _with(_JOURNAL, _JOURNAL_LEGACY,
+                 vault_id.encode() + b":" + struct.pack(">Q", seq))
+
+
+def record_key(record_id: str) -> tuple[bytes, tuple[bytes, ...]]:
+    """Associated data wrapping one record's data key (the crypto-shred unit)."""
+    return _with(_RECORD_KEY, _RECORD_KEY_LEGACY, record_id.encode())
+
+
+def record_body(record_id: str) -> tuple[bytes, tuple[bytes, ...]]:
+    """Associated data over one record's ciphertext."""
+    return _with(_RECORD_BODY, _RECORD_BODY_LEGACY, record_id.encode())
+
+
+def pack(name: str) -> tuple[bytes, tuple[bytes, ...]]:
+    """Associated data over an encrypted memory pack body."""
+    return _with(_PACK, _PACK_LEGACY, name.encode())
+
+
+def session(vault_path: str) -> tuple[bytes, tuple[bytes, ...]]:
+    """Associated data over a boot-session unlock credential."""
+    return _with(_SESSION, _SESSION_LEGACY, vault_path.encode())

{compartment-2.1 → compartment-2.2}/src/compartment.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compartment
-Version: 2.1
+Version: 2.2
 Summary: Compartment - high-security, fully offline, encrypted vector memory for AI agents (MCP)
 Project-URL: Homepage, https://github.com/MaxFreedomPollard/Compartment
 Project-URL: Source, https://github.com/MaxFreedomPollard/Compartment

{compartment-2.1 → compartment-2.2}/src/compartment.egg-info/SOURCES.txt

@@ -25,6 +25,7 @@ src/compartment/systray.py
 src/compartment/vault.py
 src/compartment/vaultfile.py
 src/compartment/vindex.py
+src/compartment/wire.py
 src/compartment.egg-info/PKG-INFO
 src/compartment.egg-info/SOURCES.txt
 src/compartment.egg-info/dependency_links.txt

compartment-2.2/tests/test_ondisk_format.py

@@ -0,0 +1,213 @@
+"""The on-disk format is not branding, and must survive every rename.
+
+Compartment was called engRAM until 1.15.0, and the name was still in the
+bytes until 2.2: AEAD associated data, KDF context labels, credential
+identifiers. Changing one of those does not rename anything. It makes data
+already written under the old spelling undecryptable.
+
+`engram-keyslot` is the worst of them: it is the associated data wrapping the
+master key. Lose it and no keyslot unseals, which means the vault cannot be
+opened again by anyone, with any passphrase, ever. `engram-record:`,
+`engram-record-body:` and `engram-payload:` are the same hazard one layer down.
+
+This is not hypothetical. The 1.15.0 rename did a find-and-replace across the
+source and rewrote all sixteen of them. It surfaced only because the vault
+started reporting itself locked; had the session not broken first, the next
+person to run it against a real vault would have found their data unreadable
+and no error explaining why.
+
+2.2 renamed them deliberately, which is a different thing: every old spelling
+moved into a legacy tuple in wire.py and is still tried on read. So the rule
+is no longer "these constants are frozen". It is:
+
+    every spelling ever written stays readable, forever.
+
+These tests hold that line from both ends. The literal checks catch a legacy
+value being deleted or a find-and-replace sweeping through wire.py. The
+round-trip tests are the ones that matter: they build genuine pre-2.2 bytes
+and prove the current code still opens them.
+"""
+import pathlib
+
+import pytest
+
+from compartment import crypto, store, vaultfile, wire
+
+SRC = pathlib.Path(__file__).resolve().parents[1] / "src" / "compartment"
+
+# Every legacy spelling, and the wire.py attribute it has to stay in. Deleting
+# any one of these entries is the permanent-data-loss move.
+LEGACY = [
+    ("KEYSLOT_LEGACY", b"engram-keyslot"),
+    ("KEYFILE_SEP_LEGACY", b"\x1f engram-2fa \x1f"),
+    ("_PAYLOAD_LEGACY", b"engram-payload:"),
+    ("_JOURNAL_LEGACY", b"engram-journal:"),
+    ("_RECORD_KEY_LEGACY", b"engram-record:"),
+    ("_RECORD_BODY_LEGACY", b"engram-record-body:"),
+    ("_PACK_LEGACY", b"engram-pack:"),
+    ("_SESSION_LEGACY", b"engram-session:"),
+    ("SESSION_TOKEN_LEGACY", "engram-session-v2"),
+    ("KEYCHAIN_SERVICE_LEGACY", "engram-vault:"),
+    ("KEYCHAIN_ACCOUNT_LEGACY", "engram"),
+]
+
+
+@pytest.mark.parametrize("attr,value", LEGACY)
+def test_every_legacy_spelling_is_still_declared(attr, value):
+    assert value in getattr(wire, attr), (
+        f"wire.{attr} no longer lists {value!r}. That is not a name, it is "
+        f"associated data in bytes that are already on disk. Removing it "
+        f"makes every vault still carrying it undecryptable, permanently."
+    )
+
+
+def test_wire_is_the_only_place_the_labels_live():
+    """One file to check before the next rename.
+
+    The 1.15.0 accident happened because these constants were scattered across
+    six modules, so a find-and-replace hit them all and no single file looked
+    wrong afterwards."""
+    strays = []
+    for path in sorted(SRC.glob("*.py")):
+        if path.name in ("wire.py", "home.py"):
+            continue          # wire.py owns them; home.py handles ~/.engram
+        for n, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+            if "engram" in line:
+                strays.append(f"{path.name}:{n}: {line.strip()}")
+    assert not strays, (
+        "on-disk labels must be declared in wire.py, not inline:\n  "
+        + "\n  ".join(strays))
+
+
+# ---------------------------------------------------------------------------
+# The real test: build pre-2.2 bytes, open them with current code.
+# ---------------------------------------------------------------------------
+
+@pytest.fixture()
+def legacy_wire(monkeypatch):
+    """Make the writing side emit exactly what a pre-2.2 build emitted."""
+    for attr, value in LEGACY:
+        monkeypatch.setattr(wire, attr.removesuffix("_LEGACY"), value)
+    monkeypatch.setattr(wire, "WIRE_FORMAT", 1)
+    return wire
+
+
+def test_a_legacy_keyslot_still_opens_and_migrates_itself(legacy_wire, monkeypatch):
+    master = crypto.new_key()
+    slot = crypto.make_passphrase_slot(master, "correct horse")
+    assert b"engram-keyslot" == wire.KEYSLOT          # the fixture is honest
+    monkeypatch.undo()                                 # back to current code
+
+    assert crypto.open_slot(slot, "correct horse") == master
+    # and it rewrote itself on the way through, so the next open is direct
+    assert crypto.unseal(
+        crypto.derive_key(b"correct horse", bytes.fromhex(slot["salt"]),
+                          slot["kdf"]),
+        bytes.fromhex(slot["wrapped"]), aad=wire.KEYSLOT) == master
+
+
+def test_a_legacy_record_still_reads_and_migrates(legacy_wire, monkeypatch):
+    master = crypto.new_key()
+    db = store.Store()
+    rid = db.insert(record_id=None, ns="main", text="a legacy memory",
+                    vec=_vec(), tags=[], importance=0.5, quarantined=False,
+                    pack=None, prov={}, master_key=master)
+    monkeypatch.undo()
+
+    assert db.decrypt_text(db.get_row(rid), master) == "a legacy memory"
+    assert db.migrate_wire(master) == 1
+    row = db.get_row(rid)
+    assert db.decrypt_text(row, master) == "a legacy memory"
+    # now genuinely current: the legacy label is no longer what opens it
+    rk = crypto.unseal(master, row["key_wrapped"], aad=wire.record_key(rid)[0])
+    assert crypto.unseal(rk, row["ct"], aad=wire.record_body(rid)[0])
+
+
+def test_a_legacy_vault_opens_migrates_and_keeps_every_memory(
+        legacy_wire, monkeypatch, vault_path):
+    """End to end, through the real Vault, on a real file."""
+    from compartment.vault import Vault
+
+    v = Vault.create(vault_path, "CorrectHorse", creator="test")
+    for text in ("the first memory", "the second memory", "the third"):
+        v.store(text, caller="test")
+    v.save()
+    v.lock()
+    assert v.header.extra["wire"] == 1
+    monkeypatch.undo()
+
+    reopened = Vault.unlock(vault_path, passphrase="CorrectHorse")
+    assert reopened.header.extra["wire"] == wire.WIRE_FORMAT
+    texts = {reopened.db.decrypt_text(r, reopened._master)
+             for r in reopened.db.conn.execute("SELECT * FROM records")}
+    assert {"the first memory", "the second memory", "the third"} <= texts
+
+    # The migration persisted, and it is genuinely current rather than just
+    # marked so: every layer now authenticates under the current label with no
+    # fallback. Checking the file for "engram" would prove nothing - associated
+    # data is an input to the AEAD, never stored, so a legacy vault does not
+    # contain the string either.
+    reopened.lock()
+    again = Vault.unlock(vault_path, passphrase="CorrectHorse")
+    assert again.header.extra["wire"] == wire.WIRE_FORMAT
+
+    loaded = vaultfile.read_vault_file(vault_path)
+    key = again._master
+    crypto.unseal(key, loaded.payload_ct,
+                  aad=wire.payload(loaded.header.vault_id)[0])
+    for row in again.db.conn.execute("SELECT * FROM records"):
+        rk = crypto.unseal(key, row["key_wrapped"],
+                           aad=wire.record_key(row["id"])[0])
+        crypto.unseal(rk, row["ct"], aad=wire.record_body(row["id"])[0])
+    slot = again.header.keyslots[0]
+    crypto.unseal(
+        crypto.derive_key(b"CorrectHorse", bytes.fromhex(slot["salt"]),
+                          slot["kdf"]),
+        bytes.fromhex(slot["wrapped"]), aad=wire.KEYSLOT)
+
+
+def test_a_legacy_session_credential_is_accepted_and_rewritten(
+        legacy_wire, monkeypatch, tmp_path):
+    from compartment import session
+
+    monkeypatch.setenv("COMPARTMENT_SESSION_DIR", str(tmp_path / "session"))
+    master = crypto.new_key()
+    vault = str(tmp_path / "x.vault")
+    session.store(vault, master)
+    monkeypatch.undo()
+    monkeypatch.setenv("COMPARTMENT_SESSION_DIR", str(tmp_path / "session"))
+
+    assert session.get(vault) == master          # opened despite the old token
+    assert session.get(vault) == master          # and again, now rewritten
+
+
+def test_a_legacy_encrypted_pack_still_opens(legacy_wire, monkeypatch, tmp_path):
+    from compartment import packs
+    import numpy as np
+
+    identity = packs.new_identity("author")
+    blob = packs.build_pack(
+        name="demo", version="1", description="d",
+        records=[{"text": "packed memory", "namespace": "main", "tags": [],
+                  "importance": 0.5}],
+        vectors=np.zeros((1, 8), dtype=np.float32),
+        model={"name": "m", "sha256": "x", "dim": 8},
+        identity=identity, passphrase="packpass")
+    monkeypatch.undo()
+
+    header, records, _ = packs.read_pack(blob, passphrase="packpass")
+    assert records[0]["text"] == "packed memory"
+
+
+def test_a_vault_written_now_round_trips():
+    """Belt and braces: the current constants agree with themselves."""
+    master = crypto.new_key()
+    slot = crypto.make_passphrase_slot(master, "correct horse")
+    assert crypto.open_slot(slot, "correct horse") == master
+    rk, wrapped = crypto.new_record_key(master, "rec-1")
+    assert crypto.unwrap_record_key(master, "rec-1", wrapped) == rk
+
+
+def _vec():
+    import numpy as np
+    return np.zeros(8, dtype=np.float32)

compartment-2.1/tests/test_ondisk_format.py

@@ -1,97 +0,0 @@
-"""The on-disk format is not branding, and must survive every rename.
-
-Compartment was called engRAM until 1.15.0. The strings below are AEAD
-associated data, KDF context labels and file-format tags that were written
-into every vault created before that. They are wire format. Changing one does
-not rename anything - it makes previously written bytes undecryptable.
-
-`engram-keyslot` is the worst of them: it is the associated data used to wrap
-the master key. Alter it and the keyslot no longer unseals, which means the
-vault cannot be opened again by anyone, with any passphrase, ever. Every
-memory in it is gone. `engram-record:`, `engram-record-body:` and
-`engram-payload:` are the same hazard one layer down.
-
-This is not hypothetical. The 1.15.0 rename did a find-and-replace across the
-source and rewrote all sixteen of them. It surfaced only because the vault
-started reporting itself locked; had the session not broken first, the next
-person to run it against a real vault would have found their data unreadable
-and no error explaining why.
-
-So: these constants are frozen. If the product is renamed again, they stay.
-"""
-import pathlib
-import re
-
-import pytest
-
-SRC = pathlib.Path(__file__).resolve().parents[1] / "src" / "compartment"
-
-# module -> the exact literals that must appear in it, verbatim
-FROZEN = {
-    "crypto.py": [
-        'b"engram-keyslot"',            # wraps the master key
-        r'b"\x1f engram-2fa \x1f"',     # separates passphrase from keyfile
-        'b"engram-record:"',            # per-record key wrapping
-    ],
-    "store.py": ['b"engram-record-body:"'],
-    "vaultfile.py": ['b"engram-payload:"', 'b"engram-journal:"'],
-    "packs.py": ['b"engram-pack:"'],
-    "session.py": ['"engram-session-v2"', 'b"engram-session:"'],
-}
-
-
-@pytest.mark.parametrize("module,literals",
-                         sorted((m, ls) for m, ls in FROZEN.items()))
-def test_ondisk_constants_are_frozen(module, literals):
-    text = (SRC / module).read_text(encoding="utf-8")
-    for lit in literals:
-        assert lit in text, (
-            f"{module} no longer contains {lit}. This is on-disk format, not a "
-            f"name. Changing it makes every vault written before now "
-            f"undecryptable - see this module's docstring."
-        )
-
-
-def test_no_format_constant_carries_the_new_name():
-    """The mirror of the above: catch the rewrite, not just the absence."""
-    bad = []
-    pattern = re.compile(r'b?"[^"]*compartment-(keyslot|record|pack|session|'
-                         r'payload|journal|record-body)[^"]*"')
-    for module in FROZEN:
-        for m in pattern.finditer((SRC / module).read_text(encoding="utf-8")):
-            bad.append(f"{module}: {m.group(0)}")
-    assert not bad, (
-        "on-disk constants were renamed to the new product name:\n  "
-        + "\n  ".join(bad))
-
-
-def test_keychain_identity_is_frozen():
-    """The macOS Keychain item is a stored credential, not a label.
-
-    Renaming the service or the account does not migrate the item - it makes
-    the lookup miss, and the vault then reports itself locked with no hint
-    that a perfectly good credential is sitting in the Keychain under the old
-    name. That is what the rename did.
-    """
-    text = (SRC / "vault.py").read_text(encoding="utf-8")
-    assert 'f"engram-vault:{os.path.abspath(path)}"' in text
-    assert '"-a", "engram",' in text
-    assert '"-a", "compartment",' not in text
-    assert "compartment-vault:" not in text
-
-
-def test_keyfile_separator_is_the_value_existing_keyfiles_used():
-    from compartment.crypto import KEYFILE_SEP
-    assert KEYFILE_SEP == b"\x1f engram-2fa \x1f"
-
-
-def test_a_vault_written_now_still_round_trips():
-    """Belt and braces: the constants agree with themselves."""
-    from compartment.crypto import (make_passphrase_slot, open_slot,
-                                    new_key, new_record_key, unwrap_record_key)
-    master = new_key()
-    slot = make_passphrase_slot(master, "correct horse")
-    assert open_slot(slot, "correct horse") == master
-
-    rk, wrapped = new_record_key(master, "rec-1")
-    assert unwrap_record_key(master, "rec-1", wrapped) == rk