magicicapsula 0.1.0__py3-none-any.whl

magicicapsula/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

magicicapsula/__main__.py

@@ -0,0 +1,3 @@
+from magicicapsula.cli import main
+
+main()

magicicapsula/assets/logo.txt

@@ -0,0 +1,27 @@
+              
+           ▓▓▓▓▓▓▓▓▓▓▓░░░░░     
+        ▓▓▓          ▓    ░░    
+      ▓▓            ▓  ░░░  ░░  
+      ▓       ▓    ▓  ░▓▓▓    ░ 
+    ▓▓   ▓   ▓    ▓  ░▓▓░▓▓   ░ 
+    ▓   ▓   ▓   ▓▓    ▓░░░▓    ░
+   ▓   ▓   ▓   ▓█▒    ▓▓░▓▓    ░
+   ▓  ▓       ▓▓█▒     ▓▓▓     ░
+   ▓         ▓█▒█▒             ░
+  ▓   ▓   ▓  ▓█▒█▒    ░░       ░
+  ▓  ▓   ▓  ▓▒█▒█▒     ░░     ░ 
+ ▓  ▓   ▓   ▓▒█▒█▒      ░░░░░░  
+▓  ▓   ▓   ▓█▒█▒█▒          ░   
+▓        ▓▓░░░░░░░░░░░░░░░░░    
+▓      ▓▓    ░▓░ ░▓░ ░▓░        
+ ▓  ▓▓▓      ░▓░ ░▓░ ░▓░        
+  ▓▓        ░▓▓░░▓▓░░▓▓░        
+           ░▓▓░░▓▓░░▓▓░         
+            ░░  ░░  ░░          
+                                
+                                
+                                
+                                
+                                
+                                
+                                

magicicapsula/cli.py

@@ -0,0 +1,38 @@
+import argparse
+import importlib
+import pkgutil
+import sys
+
+from magicicapsula import commands
+from magicicapsula.commands import _style
+from magicicapsula.core.errors import CapsuleError
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="magicicapsula",
+        description="seal files now, open them later",
+    )
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    sub.required = True
+
+    # every non-underscore module in commands/ with a register() becomes a command.
+    # drop in a new file and it shows up, nothing else to wire.
+    for _, name, _ in pkgutil.iter_modules(commands.__path__):
+        if name.startswith("_"):
+            continue
+        mod = importlib.import_module(f"magicicapsula.commands.{name}")
+        if hasattr(mod, "register"):
+            mod.register(sub)
+
+    return parser
+
+
+def main():
+    args = build_parser().parse_args()
+    try:
+        args.func(args)
+    except CapsuleError as exc:
+        sys.exit(_style.red(f"error: {exc}"))
+    except FileNotFoundError as exc:
+        sys.exit(_style.red(f"error: no such file: {exc}"))

magicicapsula/commands/_style.py

@@ -0,0 +1,59 @@
+"""colors and the logo. presentation only, so it stays in the cli layer.
+
+colors switch off automatically when output isn't a terminal, or when
+NO_COLOR is set, so piped/redirected output stays clean.
+"""
+
+import os
+import re
+import sys
+from importlib import resources
+
+_ANSI = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def enabled():
+    return (
+        sys.stdout.isatty()
+        and os.environ.get("NO_COLOR") is None
+        and os.environ.get("TERM") != "dumb"
+    )
+
+
+def paint(text, code):
+    return f"\x1b[{code}m{text}\x1b[0m" if enabled() else text
+
+
+def bold(t):
+    return paint(t, "1")
+
+
+def dim(t):
+    return paint(t, "2")
+
+
+def red(t):
+    return paint(t, "31")
+
+
+def green(t):
+    return paint(t, "32")
+
+
+def yellow(t):
+    return paint(t, "33")
+
+
+def cyan(t):
+    return paint(t, "36")
+
+
+def logo():
+    text = resources.files("magicicapsula").joinpath("assets/logo.txt").read_text(encoding="utf-8")
+    lines = text.splitlines()
+    while lines and not lines[0].strip():
+        lines.pop(0)
+    while lines and not lines[-1].strip():
+        lines.pop()
+    text = "\n".join(lines)
+    return text if enabled() else _ANSI.sub("", text)

magicicapsula/commands/_util.py

@@ -0,0 +1,26 @@
+"""small helpers shared by the commands. underscore name so it isn't a command."""
+
+import getpass
+from datetime import timedelta
+
+
+def read_capsule(path):
+    with open(path, "rb") as fh:
+        return fh.read()
+
+
+def ask_password(confirm=False):
+    pw = getpass.getpass("password: ")
+    if not pw:
+        raise SystemExit("error: empty password")
+    if confirm and pw != getpass.getpass("confirm password: "):
+        raise SystemExit("error: passwords do not match")
+    return pw
+
+
+def fmt_remaining(delta: timedelta) -> str:
+    secs = max(int(delta.total_seconds()), 0)
+    days, secs = divmod(secs, 86400)
+    hours, secs = divmod(secs, 3600)
+    mins = secs // 60
+    return f"{days}d {hours}h {mins}m"

magicicapsula/commands/add.py

@@ -0,0 +1,18 @@
+from magicicapsula.core import draft
+
+
+def register(sub):
+    p = sub.add_parser("add", help="stage files or folders to put in the capsule")
+    p.add_argument("paths", nargs="+", help="files or folders to stage")
+    p.set_defaults(func=run)
+
+
+def run(args):
+    d = draft.load()
+    added = draft.add(d, args.paths)
+    if not added:
+        print("nothing new to stage")
+        return
+    for p in added:
+        print(f"  staged {p}")
+    print(f"{len(d.staged)} item(s) staged in total")

magicicapsula/commands/info.py

@@ -0,0 +1,27 @@
+from datetime import datetime, timezone
+
+from magicicapsula.core import capsule
+from magicicapsula.commands import _style
+from magicicapsula.commands._util import fmt_remaining, read_capsule
+
+
+def register(sub):
+    p = sub.add_parser("info", help="show a capsule's dates and status (no password needed)")
+    p.add_argument("file", help="capsule file")
+    p.set_defaults(func=run)
+
+
+def run(args):
+    info = capsule.inspect(read_capsule(args.file))
+    now = datetime.now(timezone.utc)
+    print(f"created:  {info.created_at.astimezone().isoformat()}")
+    print(f"unlocks:  {info.unlock_at.astimezone().isoformat()}")
+    print(f"cipher:   {info.cipher}")
+    if info.cipher == "none":
+        print(_style.dim("          no password, opens for anyone after the unlock date"))
+    if info.note:
+        print(f"note:     {info.note}")
+    if info.is_open(now):
+        print(f"status:   {_style.green('open')}, the unlock date has passed")
+    else:
+        print(f"status:   {_style.yellow('locked')}, {fmt_remaining(info.unlock_at - now)} remaining")

magicicapsula/commands/init.py

@@ -0,0 +1,31 @@
+from datetime import datetime
+
+from magicicapsula.core import draft
+
+
+def register(sub):
+    p = sub.add_parser("init", help="start a new capsule draft in the current directory")
+    p.add_argument("-u", "--unlock", metavar="DATE", help="unlock date, can also be set at seal")
+    p.add_argument("-n", "--note", default="", help="plaintext note shown by info")
+    p.add_argument("-o", "--out", default="capsule.mcap", help="output file name")
+    p.set_defaults(func=run)
+
+
+def run(args):
+    try:
+        d = draft.init()
+    except FileExistsError:
+        raise SystemExit("error: a capsule draft already exists here (.capsule/)")
+
+    if args.unlock:
+        try:
+            datetime.fromisoformat(args.unlock)
+        except ValueError:
+            raise SystemExit(f"error: bad date {args.unlock!r} (use YYYY-MM-DD or YYYY-MM-DDTHH:MM)")
+        d.unlock_at = args.unlock
+    d.note = args.note
+    d.out = args.out
+    draft.save(d)
+
+    print(f"new capsule draft in {d.dir}")
+    print("next: magicicapsula add <files...>")

magicicapsula/commands/open.py

@@ -0,0 +1,29 @@
+from datetime import datetime, timezone
+
+from magicicapsula.core import capsule
+from magicicapsula.commands import _style
+from magicicapsula.commands._util import ask_password, fmt_remaining, read_capsule
+
+
+def register(sub):
+    p = sub.add_parser("open", help="open a capsule and extract it once the unlock date has passed")
+    p.add_argument("file", help="capsule file")
+    p.add_argument("-d", "--dest", default=".", help="directory to extract into")
+    p.set_defaults(func=run)
+
+
+def run(args):
+    blob = read_capsule(args.file)
+    info = capsule.inspect(blob)
+    now = datetime.now(timezone.utc)
+    if not info.is_open(now):
+        raise SystemExit(
+            f"error: locked until {info.unlock_at.astimezone().isoformat()} "
+            f"({fmt_remaining(info.unlock_at - now)} remaining)"
+        )
+
+    pw = None if info.cipher == "none" else ask_password()
+    names = capsule.open_capsule(blob, pw, args.dest)
+    print(_style.green(f"opened into {args.dest}/"))
+    for name in names:
+        print(f"  {_style.dim(name)}")

magicicapsula/commands/rm.py

@@ -0,0 +1,17 @@
+from magicicapsula.core import draft
+
+
+def register(sub):
+    p = sub.add_parser("rm", help="unstage files (does not delete them from disk)")
+    p.add_argument("paths", nargs="+", help="staged paths to drop from the capsule")
+    p.set_defaults(func=run)
+
+
+def run(args):
+    d = draft.load()
+    removed = draft.remove(d, args.paths)
+    if not removed:
+        print("none of those were staged")
+        return
+    for p in removed:
+        print(f"  unstaged {p}")

magicicapsula/commands/seal.py

@@ -0,0 +1,66 @@
+import os
+import sys
+from datetime import datetime, timezone
+
+from magicicapsula.core import capsule, draft
+from magicicapsula.commands import _style
+from magicicapsula.commands._util import ask_password
+
+
+def register(sub):
+    p = sub.add_parser("seal", help="seal everything staged into a capsule file")
+    p.add_argument("-u", "--unlock", metavar="DATE", help="unlock date, overrides the draft's")
+    p.add_argument("-o", "--out", metavar="FILE", help="output capsule file, overrides the draft's")
+    p.add_argument("-n", "--note", help="plaintext note, overrides the draft's")
+    p.add_argument("-f", "--force", action="store_true", help="overwrite the output if it exists")
+    p.add_argument("-P", "--no-password", action="store_true",
+                   help="seal without a password (anyone can open it after the date)")
+    p.set_defaults(func=run)
+
+
+def _parse_date(s):
+    try:
+        dt = datetime.fromisoformat(s)
+    except ValueError:
+        raise SystemExit(f"error: bad date {s!r} (use YYYY-MM-DD or YYYY-MM-DDTHH:MM)")
+    return dt.astimezone() if dt.tzinfo is None else dt  # naive means local time
+
+
+def run(args):
+    d = draft.load()
+
+    # flags override the draft and stick, so status keeps showing the right thing
+    if args.unlock is not None:
+        d.unlock_at = args.unlock
+    if args.note is not None:
+        d.note = args.note
+    if args.out is not None:
+        d.out = args.out
+    draft.save(d)
+
+    if not d.unlock_at:
+        raise SystemExit("error: no unlock date set (use --unlock, or set one at init)")
+    if not d.staged:
+        raise SystemExit("error: nothing staged (use: magicicapsula add <files>)")
+    gone = draft.missing(d)
+    if gone:
+        raise SystemExit("error: staged files no longer exist:\n  " + "\n  ".join(gone))
+
+    unlock_at = _parse_date(d.unlock_at)
+    if unlock_at <= datetime.now(timezone.utc):
+        print("warning: unlock date is not in the future", file=sys.stderr)
+
+    out = d.out if os.path.isabs(d.out) else os.path.join(d.root, d.out)
+    if os.path.exists(out) and not args.force:
+        raise SystemExit(f"error: {out} already exists (use --force to overwrite)")
+
+    pw = None if args.no_password else ask_password(confirm=True)
+    blob = capsule.seal(d.staged, pw, unlock_at, note=d.note)
+    with open(out, "wb") as fh:
+        fh.write(blob)
+
+    print(_style.logo())
+    print(_style.green(f"sealed {len(d.staged)} item(s) into {out}"))
+    print(f"unlocks: {unlock_at.astimezone().isoformat()}")
+    if pw is None:
+        print(_style.dim("no password set, so anyone can open it after that date"))

magicicapsula/commands/status.py

@@ -0,0 +1,37 @@
+from datetime import datetime
+
+from magicicapsula.core import draft
+from magicicapsula.commands import _style
+
+
+def register(sub):
+    p = sub.add_parser("status", help="show the draft: unlock date and staged files")
+    p.set_defaults(func=run)
+
+
+def run(args):
+    d = draft.load()
+    print(_style.bold(f"draft at {d.dir}"))
+
+    if d.unlock_at:
+        dt = datetime.fromisoformat(d.unlock_at)
+        dt = dt.astimezone() if dt.tzinfo is None else dt
+        print(f"unlocks: {dt.isoformat()}")
+    else:
+        print("unlocks: not set (pass --unlock at init or seal)")
+    if d.note:
+        print(f"note:    {d.note}")
+    print(f"output:  {d.out}")
+    print()
+
+    if not d.staged:
+        print("nothing staged. use: magicicapsula add <files>")
+        return
+
+    gone = set(draft.missing(d))
+    print("staged:")
+    for p in d.staged:
+        print(f"  {p}{_style.red('  (missing)') if p in gone else ''}")
+    print(f"\n{len(d.staged)} item(s) staged")
+    if gone:
+        print(_style.yellow("warning: some staged files no longer exist; fix before sealing"))

magicicapsula/commands/verify.py

@@ -0,0 +1,18 @@
+from magicicapsula.core import capsule
+from magicicapsula.commands import _style
+from magicicapsula.commands._util import ask_password, read_capsule
+
+
+def register(sub):
+    p = sub.add_parser("verify", help="check a capsule's integrity with the password, without opening")
+    p.add_argument("file", help="capsule file")
+    p.set_defaults(func=run)
+
+
+def run(args):
+    blob = read_capsule(args.file)
+    info = capsule.inspect(blob)
+    pw = None if info.cipher == "none" else ask_password()
+    capsule.verify(blob, pw)
+    tail = "" if pw is None else " and the password is correct"
+    print(_style.green(f"ok, capsule is intact{tail}"))

magicicapsula/commands/version.py

@@ -0,0 +1,14 @@
+from magicicapsula import __version__
+from magicicapsula.commands import _style
+
+
+def register(sub):
+    p = sub.add_parser("version", help="show the version and logo")
+    p.set_defaults(func=run)
+
+
+def run(args):
+    print(_style.logo())
+    print()
+    print(f"  {_style.bold('magicicapsula')} {__version__}")
+    print(f"  {_style.dim('seal files now, open them later')}")

magicicapsula/core/__init__.py

@@ -0,0 +1,5 @@
+"""the pure library: encryption, capsule format, and the staging area.
+
+no cli code and no printing here. the commands package is a thin layer
+on top, so the same logic can be reused from other frontends later.
+"""

magicicapsula/core/capsule.py

@@ -0,0 +1,165 @@
+"""the .mcap capsule format: pack files, seal, inspect, open.
+
+one portable binary file you can store anywhere:
+
+    b"MCAP"            4 bytes   magic
+    version           1 byte
+    header length     4 bytes   uint32, big-endian
+    header            N bytes   json, utf-8 (dates, kdf params, salt, note)
+    ciphertext        rest      fernet token of a .tar.gz of the contents
+
+the header is plaintext so inspect() can show dates without a password.
+the contents, file names included, live only inside the ciphertext.
+"""
+
+import base64
+import io
+import json
+import os
+import struct
+import tarfile
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+from . import crypto
+from .errors import CapsuleLocked, InvalidCapsule, WrongPasswordOrCorrupt
+
+MAGIC = b"MCAP"
+VERSION = 1
+
+
+@dataclass
+class CapsuleInfo:
+    """Non-secret metadata readable without the password."""
+
+    created_at: datetime
+    unlock_at: datetime
+    cipher: str
+    note: str
+
+    def is_open(self, now: datetime | None = None) -> bool:
+        now = now or datetime.now(timezone.utc)
+        return now >= self.unlock_at
+
+    def remaining(self, now: datetime | None = None) -> timedelta:
+        now = now or datetime.now(timezone.utc)
+        return max(self.unlock_at - now, timedelta(0))
+
+
+def _iso(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).isoformat()
+
+
+def _parse_iso(s: str) -> datetime:
+    dt = datetime.fromisoformat(s)
+    return dt.replace(tzinfo=timezone.utc) if dt.tzinfo is None else dt
+
+
+def _pack(paths) -> bytes:
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tar:
+        for path in paths:
+            path = os.path.normpath(path)
+            if not os.path.exists(path):
+                raise FileNotFoundError(path)
+            tar.add(path, arcname=os.path.basename(path))
+    return buf.getvalue()
+
+
+def _unpack(blob: bytes, dest: str) -> list[str]:
+    os.makedirs(dest, exist_ok=True)
+    try:
+        with tarfile.open(fileobj=io.BytesIO(blob), mode="r:gz") as tar:
+            names = tar.getnames()
+            tar.extractall(dest, filter="data")  # filter blocks path traversal
+    except tarfile.TarError as exc:
+        raise WrongPasswordOrCorrupt("the capsule is corrupted") from exc
+    return names
+
+
+def list_names(blob: bytes) -> list[str]:
+    try:
+        with tarfile.open(fileobj=io.BytesIO(blob), mode="r:gz") as tar:
+            return tar.getnames()
+    except tarfile.TarError as exc:
+        raise WrongPasswordOrCorrupt("the capsule is corrupted") from exc
+
+
+def seal(paths, password, unlock_at: datetime, note: str = "") -> bytes:
+    if unlock_at.tzinfo is None:
+        unlock_at = unlock_at.replace(tzinfo=timezone.utc)
+    payload = _pack(paths)
+    header = {
+        "v": VERSION,
+        "created_at": _iso(datetime.now(timezone.utc)),
+        "unlock_at": _iso(unlock_at),
+        "note": note,
+    }
+    if password:
+        salt = os.urandom(16)
+        params = crypto.KdfParams()
+        payload = crypto.encrypt(payload, password, salt, params)
+        header["cipher"] = "fernet"
+        header["kdf"] = {**params.to_dict(), "salt": base64.b64encode(salt).decode()}
+    else:
+        header["cipher"] = "none"
+    hb = json.dumps(header).encode("utf-8")
+    return MAGIC + bytes([VERSION]) + struct.pack(">I", len(hb)) + hb + payload
+
+
+def _split(blob: bytes):
+    if blob[:4] != MAGIC:
+        raise InvalidCapsule("not a magicicapsula capsule (bad magic bytes)")
+    version = blob[4]
+    if version != VERSION:
+        raise InvalidCapsule(f"unsupported capsule version: {version}")
+    (hlen,) = struct.unpack(">I", blob[5:9])
+    try:
+        header = json.loads(blob[9:9 + hlen])
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise InvalidCapsule("corrupt header") from exc
+    return header, blob[9 + hlen:]
+
+
+def inspect(blob: bytes) -> CapsuleInfo:
+    header, _ = _split(blob)
+    return CapsuleInfo(
+        created_at=_parse_iso(header["created_at"]),
+        unlock_at=_parse_iso(header["unlock_at"]),
+        cipher=header.get("cipher", "fernet"),
+        note=header.get("note", ""),
+    )
+
+
+def _payload(blob: bytes, password) -> bytes:
+    header, token = _split(blob)
+    cipher = header.get("cipher", "fernet")
+    if cipher == "none":
+        return token
+    if cipher != "fernet":
+        raise InvalidCapsule(f"unknown cipher: {cipher}")
+    if not password:
+        raise WrongPasswordOrCorrupt("this capsule needs a password")
+    kdf = header["kdf"]
+    salt = base64.b64decode(kdf["salt"])
+    return crypto.decrypt(token, password, salt, crypto.KdfParams.from_dict(kdf))
+
+
+def verify(blob: bytes, password) -> bool:
+    """Unpack the payload in memory without extracting. Raises on a bad password or corruption."""
+    list_names(_payload(blob, password))  # opening the tar catches a corrupt payload too
+    return True
+
+
+def open_capsule(
+    blob: bytes,
+    password,
+    dest: str,
+    *,
+    now: datetime | None = None,
+    allow_locked: bool = False,
+) -> list[str]:
+    info = inspect(blob)
+    if not allow_locked and not info.is_open(now):
+        raise CapsuleLocked(info.unlock_at)
+    return _unpack(_payload(blob, password), dest)

magicicapsula/core/crypto.py

@@ -0,0 +1,69 @@
+"""password-based authenticated encryption for capsule payloads.
+
+kept separate from the capsule format and the cli, so swapping the
+cipher later only touches this file. wraps the cryptography package
+instead of hand-rolling anything.
+
+password -> scrypt -> 32-byte key -> base64 -> fernet key.
+fernet is aes-128-cbc + hmac-sha256, so it detects tampering.
+"""
+
+import base64
+import hashlib
+from dataclasses import dataclass
+
+from cryptography.fernet import Fernet, InvalidToken
+
+from .errors import WrongPasswordOrCorrupt
+
+# scrypt cost parameters. Memory cost ~= 128 * r * n bytes (~32 MB here).
+SCRYPT_N = 2 ** 15
+SCRYPT_R = 8
+SCRYPT_P = 1
+KEY_LEN = 32
+_MAXMEM = 128 * SCRYPT_R * SCRYPT_N * 2  # headroom for hashlib.scrypt
+
+
+@dataclass(frozen=True)
+class KdfParams:
+    """Key-derivation parameters, stored (minus the salt) in the header."""
+
+    algo: str = "scrypt"
+    n: int = SCRYPT_N
+    r: int = SCRYPT_R
+    p: int = SCRYPT_P
+
+    def to_dict(self) -> dict:
+        return {"algo": self.algo, "n": self.n, "r": self.r, "p": self.p}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "KdfParams":
+        return cls(d.get("algo", "scrypt"), d["n"], d["r"], d["p"])
+
+
+def derive_key(password: str, salt: bytes, params: KdfParams = KdfParams()) -> bytes:
+    if params.algo != "scrypt":
+        raise ValueError(f"unsupported KDF: {params.algo}")
+    raw = hashlib.scrypt(
+        password.encode("utf-8"),
+        salt=salt,
+        n=params.n,
+        r=params.r,
+        p=params.p,
+        dklen=KEY_LEN,
+        maxmem=_MAXMEM,
+    )
+    return base64.urlsafe_b64encode(raw)
+
+
+def encrypt(data: bytes, password: str, salt: bytes, params: KdfParams = KdfParams()) -> bytes:
+    return Fernet(derive_key(password, salt, params)).encrypt(data)
+
+
+def decrypt(token: bytes, password: str, salt: bytes, params: KdfParams = KdfParams()) -> bytes:
+    try:
+        return Fernet(derive_key(password, salt, params)).decrypt(token)
+    except InvalidToken as exc:
+        raise WrongPasswordOrCorrupt(
+            "wrong password, or the capsule has been altered/corrupted"
+        ) from exc

magicicapsula/core/draft.py

@@ -0,0 +1,108 @@
+"""the staging area ("draft") for building a capsule.
+
+state lives in a .capsule/ directory, found by walking up from the cwd.
+init creates it, add stages paths, status reports, and seal packs the
+staged paths into a .mcap file.
+
+staged entries are absolute paths to the current files on disk; their
+contents are read at seal time, not copied when you add them.
+
+no argparse, no printing here.
+"""
+
+import json
+import os
+from dataclasses import dataclass, field
+
+from .errors import NoDraft
+
+DRAFT_DIR = ".capsule"
+CONFIG = "config.json"
+VERSION = 1
+
+
+@dataclass
+class Draft:
+    root: str                       # directory containing .capsule/
+    unlock_at: str | None = None    # ISO date/datetime as typed by the user
+    note: str = ""
+    out: str = "capsule.mcap"
+    staged: list[str] = field(default_factory=list)  # absolute paths
+
+    @property
+    def dir(self) -> str:
+        return os.path.join(self.root, DRAFT_DIR)
+
+    @property
+    def config_path(self) -> str:
+        return os.path.join(self.dir, CONFIG)
+
+
+def find_root(start: str | None = None) -> str:
+    path = os.path.abspath(start or os.getcwd())
+    while True:
+        if os.path.isdir(os.path.join(path, DRAFT_DIR)):
+            return path
+        parent = os.path.dirname(path)
+        if parent == path:
+            raise NoDraft("no capsule here (run `magicicapsula init` first)")
+        path = parent
+
+
+def init(root: str | None = None) -> Draft:
+    root = os.path.abspath(root or os.getcwd())
+    draft = Draft(root=root)
+    if os.path.exists(draft.dir):
+        raise FileExistsError(draft.dir)
+    os.makedirs(draft.dir)
+    save(draft)
+    return draft
+
+
+def load(root: str | None = None) -> Draft:
+    root = root or find_root()
+    draft = Draft(root=root)
+    with open(draft.config_path, encoding="utf-8") as fh:
+        data = json.load(fh)
+    draft.unlock_at = data.get("unlock_at")
+    draft.note = data.get("note", "")
+    draft.out = data.get("out", "capsule.mcap")
+    draft.staged = data.get("staged", [])
+    return draft
+
+
+def save(draft: Draft) -> None:
+    data = {
+        "v": VERSION,
+        "unlock_at": draft.unlock_at,
+        "note": draft.note,
+        "out": draft.out,
+        "staged": draft.staged,
+    }
+    with open(draft.config_path, "w", encoding="utf-8") as fh:
+        json.dump(data, fh, indent=2)
+
+
+def add(draft: Draft, paths) -> list[str]:
+    added = []
+    for p in paths:
+        ap = os.path.abspath(p)
+        if not os.path.exists(ap):
+            raise FileNotFoundError(p)
+        if ap not in draft.staged:
+            draft.staged.append(ap)
+            added.append(ap)
+    save(draft)
+    return added
+
+
+def remove(draft: Draft, paths) -> list[str]:
+    targets = {os.path.abspath(p) for p in paths}
+    removed = [s for s in draft.staged if s in targets]
+    draft.staged = [s for s in draft.staged if s not in targets]
+    save(draft)
+    return removed
+
+
+def missing(draft: Draft) -> list[str]:
+    return [p for p in draft.staged if not os.path.exists(p)]

magicicapsula/core/errors.py

@@ -0,0 +1,29 @@
+"""errors raised by the core library.
+
+the cli catches CapsuleError and prints a short message, so callers
+never have to know the internals.
+"""
+
+
+class CapsuleError(Exception):
+    """base class for anything that can go wrong with a capsule."""
+
+
+class InvalidCapsule(CapsuleError):
+    """the bytes are not a valid capsule (bad magic, version, or header)."""
+
+
+class WrongPasswordOrCorrupt(CapsuleError):
+    """decryption failed: wrong password, or the data was altered."""
+
+
+class NoDraft(CapsuleError):
+    """no capsule draft found here (run init first)."""
+
+
+class CapsuleLocked(CapsuleError):
+    """the unlock date has not arrived yet."""
+
+    def __init__(self, unlock_at):
+        self.unlock_at = unlock_at
+        super().__init__(f"capsule is locked until {unlock_at.isoformat()}")

magicicapsula-0.1.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: magicicapsula
+Version: 0.1.0
+Summary: seal files now, open them later
+Author-email: iDavi <odavi20527@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/iDavi/magicicapsula
+Project-URL: Repository, https://github.com/iDavi/magicicapsula
+Project-URL: Issues, https://github.com/iDavi/magicicapsula/issues
+Keywords: time-capsule,encryption,cli,archive,vault
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42
+Dynamic: license-file
+
+# magicicapsula
+
+## install
+
+```
+pip install -e .
+```
+
+needs python 3.10+. one dependency: `cryptography`.
+
+## how it works
+
+the workflow is staged, so you don't have to add everything at once:
+
+```
+magicicapsula init -u 2030-01-01     # start a draft here
+magicicapsula add letter.txt photos/ # stage files/folders
+magicicapsula add diary.txt          # add more later
+magicicapsula status                 # see what's staged
+magicicapsula seal                   # pack it all into capsule.mcap
+```
+
+the draft lives in a `.capsule/` directory (found by walking up from the
+current dir). `seal` reads everything staged and writes the `.mcap` file.
+
+later, when the date has passed:
+
+```
+magicicapsula open capsule.mcap -d ./out
+```
+
+`.mcap` is one portable binary file. store it anywhere, copy it around. it
+holds any file type (images, pdfs, binaries) byte for byte, not just text.
+
+## passwords
+
+- with a password (default): contents are encrypted (aes-128 via `cryptography`),
+  unreadable without the password. `open` and `verify` prompt for it.
+- without a password (`seal --no-password`): no encryption. the unlock date is
+  the only gate, so anyone with the file can open it after that date. don't put
+  anything private in a no-password capsule.
+
+note: the unlock date is enforced by the tool, not by cryptography. if you hold
+the password you could decrypt early with other means. the date stops casual
+early opening, not a determined holder.
+
+## commands
+
+### init
+start a new capsule draft in the current directory.
+
+```
+magicicapsula init [-u DATE] [-n NOTE] [-o OUT]
+
+  -u, --unlock DATE  unlock date, can also be set at seal
+  -n, --note NOTE    plaintext note shown by info
+  -o, --out OUT      output file name (default: capsule.mcap)
+```
+
+### add
+stage files or folders to put in the capsule.
+
+```
+magicicapsula add <paths...>
+```
+
+### status
+show the draft: unlock date and staged files.
+
+```
+magicicapsula status
+```
+
+### rm
+unstage files. does not delete them from disk.
+
+```
+magicicapsula rm <paths...>
+```
+
+### seal
+seal everything staged into a capsule file. flags override the draft's
+settings and stick.
+
+```
+magicicapsula seal [-u DATE] [-o FILE] [-n NOTE] [-f] [-P]
+
+  -u, --unlock DATE  unlock date, overrides the draft's
+  -o, --out FILE     output capsule file, overrides the draft's
+  -n, --note NOTE    plaintext note, overrides the draft's
+  -f, --force        overwrite the output if it exists
+  -P, --no-password  seal without a password (anyone can open it after the date)
+```
+
+### info
+show a capsule's dates and status. no password needed.
+
+```
+magicicapsula info <file>
+```
+
+### open
+open a capsule and extract it, once the unlock date has passed.
+
+```
+magicicapsula open [-d DEST] <file>
+
+  -d, --dest DEST  directory to extract into (default: current dir)
+```
+
+### verify
+check a capsule's integrity (and the password, if any) without opening it.
+
+```
+magicicapsula verify <file>
+```
+
+### version
+show the version and logo.
+
+```
+magicicapsula version
+```
+
+## date format
+
+`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM`, read as local time. examples:
+`2030-01-01`, `2030-01-01T08:00`.
+
+## colors
+
+output is colored in a terminal and plain when piped or redirected. set
+`NO_COLOR=1` to turn colors off.
+
+## dates and gotchas
+
+- staged entries are paths, read at seal time, not copied when you add them.
+  if a staged file is moved or deleted before sealing, `status` marks it
+  `(missing)` and `seal` refuses until it's fixed.
+- files are stored under their base name, so two staged files with the same
+  name would collide.

magicicapsula-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+magicicapsula/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+magicicapsula/__main__.py,sha256=5TF6ulwui2K43AE-kesBxy_ANaenWnN1b2KfI9f6bmM,43
+magicicapsula/cli.py,sha256=Z0fOuyWGp_QOira_so7CIDLppzfdnuQ_1TFzuQGupxs,1117
+magicicapsula/assets/logo.txt,sha256=YsfYYo2fXXJq2wPaEMjInOfD4xZnadss0SWc9XTsiEY,5855
+magicicapsula/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+magicicapsula/commands/_style.py,sha256=wrJS-pWQJSAE29rC-KAXGMmGM7sFT9o58rwdelV4AwM,1149
+magicicapsula/commands/_util.py,sha256=vmAX4ugX29dT4JsWz3ReMe-rYujuT4M7JgHUcD8_mBs,716
+magicicapsula/commands/add.py,sha256=11rjRa_W2hD5dMNRf1DqW4yESc7yTNCsXFCUbBEjtd8,494
+magicicapsula/commands/info.py,sha256=uth9VGtcucXTh8rrd77OsYmqdzyB5d556RxK-3psaag,1057
+magicicapsula/commands/init.py,sha256=k6k9pavKe7bOlsFECiMYrIm6HJFspx5Ipal-OIdbm6w,1034
+magicicapsula/commands/open.py,sha256=tCxzGrOjCy6U3WYNWNa2X0Yu5ebKMjiIfsxWpgN-C4g,1046
+magicicapsula/commands/rm.py,sha256=8bJO74Y2deNQ4c8R89kd1o0rO8wE3nRGewiFZ5qsi2I,469
+magicicapsula/commands/seal.py,sha256=bR2N7DFn0SozR0RK_A8xKAg6fTFpFeZ3jAmKKgwwpow,2604
+magicicapsula/commands/status.py,sha256=J0ytVAfuXkUOZZ0_nsDmI9gb886Cd50ajpLDzQE5iZM,1076
+magicicapsula/commands/verify.py,sha256=zU78B3bolpcBKp_a_dvE64M4RLKS1ji-RafOjTCpEAc,644
+magicicapsula/commands/version.py,sha256=uTB3w8GK-MdNY45VwXLFiAZtrfG64wKhNUpBwShPCLs,377
+magicicapsula/core/__init__.py,sha256=3TK4lBrmpPmUHcwIBwyXTDVLsuhrylHOjVD-tgPlhZ0,215
+magicicapsula/core/capsule.py,sha256=gCi_87dXJKHIVOLiuL-9x_qSDkM0LmD-BcP9_vkuAco,5219
+magicicapsula/core/crypto.py,sha256=CwEzGQ47XtkibupaFwFfb6U_3Wxwti-Z2Yckzm152Tk,2099
+magicicapsula/core/draft.py,sha256=wHGw0Ala4kKJ0ECF-TSjNUCh45yLPVhBPBaFnSvYZRc,3006
+magicicapsula/core/errors.py,sha256=prq68jMBsNTE_-iaNQ6T14Qm4Du25sdrHw74gCcWCfY,796
+magicicapsula-0.1.0.dist-info/licenses/LICENSE,sha256=1Z_qjZrSzXhIxveg1iheXdP2IYCT0QeHaem3w0ErlVU,1062
+magicicapsula-0.1.0.dist-info/METADATA,sha256=pfqw_bgnFolEek6hX1FH3ilwNZFsM58PzvnFU1KRgC8,4664
+magicicapsula-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+magicicapsula-0.1.0.dist-info/entry_points.txt,sha256=UywzEU4YIceH-NEUN5Xkx3khqj62ti5D7n0Pa5TRNMs,57
+magicicapsula-0.1.0.dist-info/top_level.txt,sha256=oa2-Jq66XjBmMuIvQbFRLEO-jXc5xOL4cj4LPlPYejg,14
+magicicapsula-0.1.0.dist-info/RECORD,,

magicicapsula-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

magicicapsula-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+magicicapsula = magicicapsula.cli:main

magicicapsula-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iDavi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

magicicapsula-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+magicicapsula