magicicapsula 0.1.0__tar.gz

magicicapsula-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,141 @@
+# 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/magicicapsula/__init__.py

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

magicicapsula-0.1.0/magicicapsula/__main__.py

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

magicicapsula-0.1.0/magicicapsula/assets/logo.txt

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

magicicapsula-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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}")