fix: clean mongo errors, null-meta list crash, empty-friendly revoke, key passphrase, storage path env expansion (v0.1.5)

envauth-2: catch PyMongoError in cli.py (guarded import) so an unreachable
mongo backend fails fast with a clean [x] line instead of an uncaught
traceback after the driver's server-selection timeout.

envauth-3: coerce a non-dict meta block to {} before rendering `list`, so a
"meta": null doc no longer crashes the table mid-render.

envauth-4: revoke checks args.friendly is not None instead of truthiness, so
--friendly "" correctly routes to the friendly-name lookup instead of
misrouting to the fingerprint branch.

envauth-5: add an optional [keys].password config field and thread it through
boot_local's decrypt_aes_key_with_rsa and verify's self_test, so an encrypted
local private key can be unwrapped.

envauth-6: add Config.storage_path (routed through the existing _expand
helper) so the JSON storage path expands $ENV_VARS the same way the key
paths already do, not just ~.

envauth-7: verified CLAUDE.md and README already correctly describe
authorize's re-run-is-refused behavior (fixed under envauth-1); no doc
change needed.

Also compresses several essay-length docstrings/comments (init's TOCTOU
note, authorize's replace-guard note, mongo_store's module docstring,
json_store's _write docstring, list_keys' _can_authorize docstring) with no
behavior change; re-verified the full CLI flow (JSON + live mongod) after.

Signed-off-by: disqualifier <dev@disqualifier.me>

.gitignore

@@ -5,4 +5,4 @@ dist/
 build/
 .venv/
 .pytest_cache/
-CLAUDE.md
+.claude/

README.md

@@ -13,25 +13,27 @@ authorization system and the key-document schema; the crypto primitives live in
 ## Install
 
 ```
-envelope_authorizer @ git+ssh://git@git.rethinkstudios.io/rethink-public/envelope_authorizer.git@v0.1.1
+envelope_authorizer @ git+ssh://git@git.rethinkstudios.io/rethink-public/envelope_authorizer.git@v0.1.5
 ```
 
 Direct:
 
 ```bash
-pip install "envelope_authorizer @ git+ssh://git@git.rethinkstudios.io/rethink-public/envelope_authorizer.git@v0.1.1"
+pip install "envelope_authorizer @ git+ssh://git@git.rethinkstudios.io/rethink-public/envelope_authorizer.git@v0.1.5"
 ```
 
 The base install uses a local JSON file for storage (stdlib only). For shared
 dev→server storage, install the mongo extra:
 
 ```bash
-pip install "envelope_authorizer[mongo] @ git+ssh://git@git.rethinkstudios.io/rethink-public/envelope_authorizer.git@v0.1.1"
+pip install "envelope_authorizer[mongo] @ git+ssh://git@git.rethinkstudios.io/rethink-public/envelope_authorizer.git@v0.1.5"
 ```
 
 Installing pulls `envelope_crypto` (and `mongo` with the extra). After install,
 the `authorizer` command is on your PATH; `python -m envelope_authorizer` also works.
 
+Drop the `@v0.1.5` suffix from the line above to install the latest unpinned.
+
 ## Trust model (read this)
 
 There is one shared **AES data-encryption key (DEK)** per project. Each key doc
@@ -127,7 +129,11 @@ initialized or the friendly name is taken.
 Boots the local DEK, verifies the local key is itself an authorizer, then wraps
 the same DEK to the target public key and stores a new key doc. Omit
 `--can-authorize` for servers (`allowed: False`); pass it only for trusted
-dev/home machines.
+dev/home machines. Refuses a target key whose fingerprint already has a record
+(most importantly the local key itself) — `save` upserts by `_id`, so
+authorizing an already-known key would silently replace its existing doc
+(capability flag and friendly name) under a success banner instead of adding a
+new key. Revoke the existing record first if you intend to re-authorize it.
 
 ```
 [✔] Authorized Jy7k2ey7... | friendly: server1 [can_authorize=False]
@@ -168,9 +174,10 @@ rotation.
 
 ## Config reference
 
-TOML, searched cwd-first then `~`: `.authorizer.toml`. Paths expand `~`. No
-defaults are baked in — a missing required field raises an error naming the field
-and the config path.
+TOML, searched cwd-first then `~`: `.authorizer.toml`. Paths (`keys.public`,
+`keys.private`, `storage.path`) expand both `~` and `$ENV_VARS`. No defaults are
+baked in — a missing required field raises an error naming the field and the
+config path.
 
 ### JSON backend (default, stdlib only)
 
@@ -179,6 +186,7 @@ and the config path.
 public   = "~/.ssh/id_rsa.pub"
 private  = "~/.ssh/id_rsa"
 identity = "user@hostname"          # stamped as created_by on every key doc
+# password = "..."                  # only if the private key above is encrypted
 
 [storage]
 backend = "json"
@@ -222,5 +230,4 @@ Owned by this lib (not `envelope_crypto`):
 
 ## Versioning
 
-Tagged `vX.Y.Z`. Pin the tag. `envelope_crypto` is pinned at `v0.1.0` in
-`pyproject.toml`; to change it, edit the pin and re-test.
+Releases are tagged `vX.Y.Z`. The install line above pins a release; drop the `@vX.Y.Z` suffix to install the latest unpinned. Pin deliberately for reproducible installs.

pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "envelope_authorizer"
-version = "0.1.1"
+version = "0.1.5"
 description = "CLI key-authorization manager for envelope_crypto"
 requires-python = ">=3.10"
 dependencies = [
-    "envelope_crypto @ git+ssh://git@git.rethinkstudios.io/rethink-public/envelope_crypto.git@v0.1.0",
+    "envelope_crypto @ git+ssh://git@git.rethinkstudios.io/rethink-public/envelope_crypto.git",
     "tomli>=2.0; python_version<'3.11'",
 ]
 

src/envelope_authorizer/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.1"
+__version__ = "0.1.5"

src/envelope_authorizer/cli.py

@@ -16,6 +16,12 @@ from .config import ConfigError, load_config
 from .commands import CommandError, authorize, config_init, init, list_keys, revoke, verify
 from .storage import resolve
 
+try:
+    from pymongo.errors import PyMongoError
+except ImportError:
+    class PyMongoError(Exception):
+        """stand-in when the [mongo] extra is not installed; never actually raised"""
+
 
 def _build_parser() -> argparse.ArgumentParser:
     """construct the argument parser with all subcommands"""
@@ -72,7 +78,9 @@ def main() -> int:
             try:
                 config_init.run(None, None, args)
                 return 0
-            except CommandError as error:
+            except (CommandError, OSError) as error:
+                # config_init writes a file (cwd may be read-only, full, or gone) — an
+                # OSError must print a clean [✘] line, not a raw traceback
                 return _fail(str(error))
         parser.parse_args(["config", "--help"])
         return 0
@@ -92,7 +100,12 @@ def main() -> int:
         return 0
     except InvalidTag:
         return _fail("capability flag failed authentication — tampered or wrong DEK")
-    except (ConfigError, CommandError, RuntimeError, ValueError, FileNotFoundError) as error:
+    except PyMongoError as error:
+        return _fail(f"storage backend error: {error}")
+    except (ConfigError, CommandError, RuntimeError, ValueError, OSError, KeyError, TypeError) as error:
+        # OSError covers the FileNotFoundError/PermissionError/IsADirectoryError family;
+        # KeyError/TypeError cover a structurally-malformed flag/doc (unguarded indexing
+        # of ['iv']/['meta']['authorizer']/['key']) — all print a clean [✘] line, not a traceback
         return _fail(str(error))
 
 

src/envelope_authorizer/commands/__init__.py

@@ -22,7 +22,11 @@ def make_flag(crypto: EnvelopeCrypto, allowed: bool) -> dict:
 
 
 def read_flag(crypto: EnvelopeCrypto, blob: dict) -> bool:
-    """decrypt a capability flag; return the `allowed` bool"""
+    """decrypt a capability flag; return the `allowed` bool
+
+    fails closed: a non-dict / unexpected plaintext reads as not-allowed rather than
+    raising — a privilege gate must default to deny on a malformed flag.
+    """
     data = crypto.decrypt_data(blob)
     return bool(data.get("allowed", False)) if isinstance(data, dict) else False
 
@@ -59,7 +63,9 @@ def boot_local(config, storage) -> Tuple[EnvelopeCrypto, dict]:
         raise CommandError(
             "not initialized on this machine (no key doc for the local public key)"
         )
-    aes_key = crypto.decrypt_aes_key_with_rsa(doc["key"], config.private_key)
+    aes_key = crypto.decrypt_aes_key_with_rsa(
+        doc["key"], config.private_key, password=config.private_key_password
+    )
     crypto.initialize(aes_key)
     return crypto, doc
 

src/envelope_authorizer/commands/authorize.py

@@ -2,7 +2,10 @@
 
 boots the local DEK, verifies the local key is itself an authorizer, then wraps
 the same DEK to the target public key and stores a new key doc. `--can-authorize`
-decides whether the new key may authorize others (omit it for servers).
+decides whether the new key may authorize others (omit it for servers). Refuses
+a target key that already has a record — `save` upserts by `_id`, so re-authorizing
+a known key (most dangerously the local key itself) would silently overwrite its
+flag/friendly under a success banner instead of adding a new key.
 """
 
 from . import (
@@ -10,6 +13,7 @@ from . import (
     boot_local,
     build_doc,
     find_by_friendly,
+    local_fingerprint,
     make_flag,
     read_flag,
 )
@@ -25,9 +29,23 @@ def run(config, storage, args) -> None:
     if not read_flag(crypto, local_doc["meta"]["authorizer"]):
         raise CommandError("this key is not permitted to authorize others")
 
-    new_fp, new_wrapped = crypto.encrypt_aes_key_with_rsa(
-        crypto.master_key, args.key
-    )
+    new_fp = crypto.get_rsa_key_fingerprint(args.key)
+    if new_fp == local_fingerprint(crypto, config):
+        raise CommandError(
+            "target key is the local key; authorize would silently replace the "
+            "local authorizer record — use a different keypair, or `authorizer "
+            "list` if you meant to check its status"
+        )
+    existing = storage.get(new_fp)
+    if existing:
+        existing_friendly = existing.get("meta", {}).get("friendly", "?")
+        raise CommandError(
+            f"target key is already authorized as '{existing_friendly}'; "
+            f"authorize would silently replace that record — revoke it first "
+            f"if you intend to re-authorize it"
+        )
+
+    _, new_wrapped = crypto.encrypt_aes_key_with_rsa(crypto.master_key, args.key)
     flag = make_flag(crypto, args.can_authorize)
     doc = build_doc(new_fp, new_wrapped, flag, config.identity, args.friendly)
     storage.save(doc)

src/envelope_authorizer/commands/config_init.py

@@ -10,6 +10,7 @@ _TEMPLATE = """[keys]
 public   = "~/.ssh/id_rsa.pub"
 private  = "~/.ssh/id_rsa"
 identity = "user@hostname"
+# password = "..."          # only if the private key above is encrypted
 
 [storage]
 backend = "json"

src/envelope_authorizer/commands/init.py

@@ -11,7 +11,12 @@ from . import CommandError, build_doc, find_by_friendly, make_flag
 
 
 def run(config, storage, args) -> None:
-    """initialize the key system on this machine as the first authorizer"""
+    """initialize the key system on this machine as the first authorizer
+
+    the already-initialized / duplicate-friendly checks are non-atomic (TOCTOU under two
+    concurrent CLIs) by design — one-shot admin tool, `save` upserts by `_id`, so the
+    worst case is a cosmetic double-init with no security consequence.
+    """
     if storage.get_all():
         raise CommandError(
             "already initialized; use `authorizer list` to see existing keys"

src/envelope_authorizer/commands/list_keys.py

@@ -11,16 +11,26 @@ from . import boot_local, read_flag
 
 
 def _can_authorize(crypto, doc) -> str:
-    """decrypted authority of a doc as Yes/No, or `?` if not readable here"""
+    """decrypted authority of a doc as Yes/No, or `?` if unreadable here
+
+    `?` covers any failure (unwrap mismatch, missing/malformed doc) so the table
+    always renders instead of crashing on one bad row.
+    """
     try:
         return "Yes" if read_flag(crypto, doc["meta"]["authorizer"]) else "No"
     except Exception:
         return "?"
 
 
-def _created(doc) -> str:
+def _meta(doc) -> dict:
+    """the doc's meta block as a dict, coercing a missing/null/malformed one to {}"""
+    meta = doc.get("meta")
+    return meta if isinstance(meta, dict) else {}
+
+
+def _created(meta: dict) -> str:
     """format created_at as a UTC timestamp string, or '-' if absent/unparseable"""
-    raw = doc.get("meta", {}).get("created_at")
+    raw = meta.get("created_at")
     if not raw:
         return "-"
     try:
@@ -40,12 +50,12 @@ def run(config, storage, args) -> None:
     print(header)
     print("-" * len(header))
     for doc in docs:
-        meta = doc.get("meta", {})
+        meta = _meta(doc)
         print(
             f"{doc.get('_id', '')[:16]:<18} "
             f"{str(meta.get('friendly', '-')):<16} "
             f"{str(meta.get('created_by', '-')):<18} "
-            f"{_created(doc):<21} "
+            f"{_created(meta):<21} "
             f"{_can_authorize(crypto, doc):<8}"
         )
     print(f"\n{len(docs)} key(s) authorized")

src/envelope_authorizer/commands/revoke.py

@@ -18,16 +18,23 @@ _WARNING = (
 
 
 def _find_by_fingerprint(storage, prefix: str):
-    """return the doc whose `_id` starts with the given prefix, or None"""
-    for doc in storage.get_all():
-        if doc.get("_id", "").startswith(prefix):
-            return doc
-    return None
+    """return the single doc whose `_id` starts with the given prefix, or None
+
+    rejects an empty prefix (matches everything) and an ambiguous one (matches
+    more than one key) instead of silently revoking the first hit.
+    """
+    if not prefix:
+        raise CommandError("fingerprint prefix must not be empty")
+    matches = [doc for doc in storage.get_all() if doc.get("_id", "").startswith(prefix)]
+    if len(matches) > 1:
+        ids = ", ".join(d["_id"][:16] for d in matches)
+        raise CommandError(f"fingerprint prefix '{prefix}' is ambiguous; matches: {ids}")
+    return matches[0] if matches else None
 
 
 def run(config, storage, args) -> None:
     """delete a key record by friendly or fingerprint, guarding the local key"""
-    if args.friendly:
+    if args.friendly is not None:
         doc = find_by_friendly(storage, args.friendly)
         label = args.friendly
     else:

src/envelope_authorizer/commands/verify.py

@@ -13,7 +13,7 @@ def run(config, storage, args) -> None:
     crypto, _ = boot_local(config, storage)
 
     if hasattr(crypto, "self_test"):
-        crypto.self_test(config.public_key, config.private_key)
+        crypto.self_test(config.public_key, config.private_key, password=config.private_key_password)
     else:
         sample = {"_authorizer_verify": "ok", "n": 12345}
         if crypto.decrypt_data(crypto.encrypt_data(sample)) != sample:

src/envelope_authorizer/config.py

@@ -1,16 +1,17 @@
 """TOML config loader for the authorizer CLI
 
-resolves a `.authorizer.toml` (cwd first, then ~), expands user paths, and
-exposes typed accessors. no defaults are baked in: a missing required field
-raises a clear error naming the field and the config path that was searched.
-the loaded config is the only place key paths, identity, and storage live —
-this lib never imports a host `config` module.
+resolves a `.authorizer.toml` (cwd first, then ~), expands `~` and `$ENV_VARS` in
+every path field (key paths and the JSON storage path alike), and exposes typed
+accessors. no defaults are baked in: a missing required field raises a clear
+error naming the field and the config path that was searched. the loaded config
+is the only place key paths, identity, and storage live — this lib never imports
+a host `config` module.
 """
 
 import os
 import sys
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
 
 if sys.version_info >= (3, 11):
     import tomllib
@@ -72,6 +73,11 @@ class Config:
         """path to the local RSA private key (expanded)"""
         return _expand(self.require("keys", "private"))
 
+    @property
+    def private_key_password(self) -> Optional[str]:
+        """passphrase for an encrypted local private key, or None if unset"""
+        return self.optional("keys", "password")
+
     @property
     def identity(self) -> str:
         """human identity stamped as created_by on every key doc"""
@@ -82,6 +88,11 @@ class Config:
         """selected storage backend name ("json" or "mongo")"""
         return self.require("storage", "backend")
 
+    @property
+    def storage_path(self) -> str:
+        """path to the JSON storage file (expanded, same as the key paths)"""
+        return _expand(self.require("storage", "path"))
+
 
 def load_config() -> Config:
     """find and parse the authorizer config, or raise with guidance

src/envelope_authorizer/storage/__init__.py

@@ -13,8 +13,7 @@ def resolve(config) -> StorageBackend:
     """build the storage backend named by the config, or raise on unknown"""
     backend = config.storage_backend
     if backend == "json":
-        path = config.require("storage", "path")
-        return JsonStore(path)
+        return JsonStore(config.storage_path)
     if backend == "mongo":
         from .mongo_store import MongoStore
         return MongoStore(

src/envelope_authorizer/storage/json_store.py

@@ -35,22 +35,30 @@ class JsonStore(StorageBackend):
         return data
 
     def _write(self, docs: List[dict]) -> None:
-        """atomically write the docs list (unique temp file then replace)
+        """atomically write the docs list (unique temp file then os.replace)
 
-        the temp name is unique per write (tempfile.mkstemp in the same dir) so two
-        concurrent writers can't clobber a shared `.tmp`; os.replace is atomic on the
-        same filesystem. the temp is cleaned up if the write fails before replace.
+        a unique temp per write (tempfile.mkstemp) keeps concurrent writers from
+        clobbering a shared `.tmp`; the temp is cleaned up if the write fails
+        before replace.
         """
         self.path.parent.mkdir(parents=True, exist_ok=True)
         fd, tmp = tempfile.mkstemp(
             dir=self.path.parent, prefix=self.path.name + ".", suffix=".tmp"
         )
+        wrapped = False
         try:
             with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                wrapped = True  # fdopen owns fd now; its close() handles it
                 json.dump(docs, handle, indent=2)
                 handle.write("\n")
             os.replace(tmp, self.path)
         except BaseException:
+            if not wrapped:
+                # fdopen raised before taking ownership — close the raw fd ourselves
+                try:
+                    os.close(fd)
+                except OSError:
+                    pass
             try:
                 os.unlink(tmp)
             except OSError:

src/envelope_authorizer/storage/mongo_store.py

@@ -1,19 +1,16 @@
 """mongo storage backend (behind the [mongo] extra)
 
-bridges the async rethink-public `mongo` lib to the sync StorageBackend by
-wrapping each operation in its own asyncio.run: connect -> op -> close, fully
-self-contained per call. no module-level client and no shared event loop, so it
-never collides with a running loop. a per-call connect is an accepted tradeoff
-for a one-shot admin CLI. requires envelope_authorizer[mongo]; without it every
-method raises a clear RuntimeError.
+bridges the async rethink-public `mongo` lib to the sync StorageBackend: each op
+gets its own asyncio.run (connect -> op -> close), no module-level client or
+shared loop, so it never collides with a running loop. per-call connect is an
+accepted tradeoff for a one-shot admin CLI. requires envelope_authorizer[mongo];
+without it every method raises a clear RuntimeError.
 
-fail-loud: operations go through the mongo lib's RAW collection escape hatch
-(`db.collection(name)`, the motor collection — which raises) rather than the
-swallow-and-return-default wrapped methods. this is an auth backend; conflating
-a backend error with "no document / not initialized" in the thing that gates
-authority is the worst place for the swallow anti-pattern, so a driver error
-propagates and a no-op upsert raises instead of silently reporting success.
-`close()` is synchronous on the mongo lib (motor's close is sync) — not awaited.
+fail-loud: ops go through the mongo lib's raw collection escape hatch (the motor
+collection, which raises), not the swallow-and-default wrapped methods — this is
+an auth backend, so a driver error must never read as "not initialized," and a
+no-op upsert raises instead of silently reporting success. `close()` is
+synchronous on the mongo lib — not awaited.
 """
 
 import asyncio