ncr-cipher 1.0.0__tar.gz

ncr_cipher-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ncr-cipher contributors
+
+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.

ncr_cipher-1.0.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: ncr-cipher
+Version: 1.0.0
+Summary: Production-grade NCR3 encryption tool — encrypt, decrypt, and verify files from any terminal.
+Author: ncr-cipher contributors
+License: MIT
+Keywords: encryption,cipher,cli,security
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ncr-cipher
+
+**Production-grade NCR3 encryption tool** — a single `ncr` command available everywhere in the terminal after installation, on Windows, macOS, and Linux.
+
+## Installation
+
+```bash
+pip install ncr-cipher
+```
+
+Or install from source:
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+# Generate a key file
+ncr --keygen mykey.key
+
+# Encrypt a file
+ncr --lock secret.txt --key mykey.key
+
+# Decrypt a file
+ncr --unlock secret.txt.ncr3 --key mykey.key
+
+# Verify integrity without decrypting
+ncr --verify secret.txt.ncr3 --key mykey.key
+
+# Show file info (no password needed)
+ncr --info secret.txt.ncr3
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `ncr --keygen <keyfile>` | Generate a new key file |
+| `ncr --lock <file> --key <k>` | Encrypt a file |
+| `ncr --unlock <file> --key <k>` | Decrypt a file |
+| `ncr --verify <file> --key <k>` | Check HMAC without decrypting |
+| `ncr --info <file>` | Show NCR version, IV, block count, file size |
+| `ncr --bench` | Benchmark KDF time + encrypt speed |
+| `ncr --test` | Run internal self-tests |
+| `ncr --version` | Print version |
+
+## Flags
+
+| Flag | Description |
+|---|---|
+| `--out, -o <path>` | Output path override |
+| `--inplace, -i` | Overwrite the original file |
+| `--silent, -s` | No output except errors |
+| `--force, -f` | Overwrite output without confirmation |
+| `--strength <1-5>` | KDF strength preset (keygen only) |
+
+## Cipher: NCR3
+
+- **KDF**: scrypt with configurable strength (5 presets)
+- **Per-byte key mixing**: BLAKE2b-derived per-position keys
+- **CBC chaining**: HMAC-SHA3-256 stream + ciphertext feedback
+- **Authentication**: HMAC-SHA3-256 over full ciphertext
+- **Math core**: nCr (binomial coefficient) based encryption mod 2¹²⁷−1
+
+Backwards compatible: can read NCR2 files (read-only).
+
+## Requirements
+
+- Python 3.9+
+- **Zero external dependencies** — stdlib only
+
+## License
+
+MIT

ncr_cipher-1.0.0/README.md

@@ -0,0 +1,76 @@
+# ncr-cipher
+
+**Production-grade NCR3 encryption tool** — a single `ncr` command available everywhere in the terminal after installation, on Windows, macOS, and Linux.
+
+## Installation
+
+```bash
+pip install ncr-cipher
+```
+
+Or install from source:
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+# Generate a key file
+ncr --keygen mykey.key
+
+# Encrypt a file
+ncr --lock secret.txt --key mykey.key
+
+# Decrypt a file
+ncr --unlock secret.txt.ncr3 --key mykey.key
+
+# Verify integrity without decrypting
+ncr --verify secret.txt.ncr3 --key mykey.key
+
+# Show file info (no password needed)
+ncr --info secret.txt.ncr3
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `ncr --keygen <keyfile>` | Generate a new key file |
+| `ncr --lock <file> --key <k>` | Encrypt a file |
+| `ncr --unlock <file> --key <k>` | Decrypt a file |
+| `ncr --verify <file> --key <k>` | Check HMAC without decrypting |
+| `ncr --info <file>` | Show NCR version, IV, block count, file size |
+| `ncr --bench` | Benchmark KDF time + encrypt speed |
+| `ncr --test` | Run internal self-tests |
+| `ncr --version` | Print version |
+
+## Flags
+
+| Flag | Description |
+|---|---|
+| `--out, -o <path>` | Output path override |
+| `--inplace, -i` | Overwrite the original file |
+| `--silent, -s` | No output except errors |
+| `--force, -f` | Overwrite output without confirmation |
+| `--strength <1-5>` | KDF strength preset (keygen only) |
+
+## Cipher: NCR3
+
+- **KDF**: scrypt with configurable strength (5 presets)
+- **Per-byte key mixing**: BLAKE2b-derived per-position keys
+- **CBC chaining**: HMAC-SHA3-256 stream + ciphertext feedback
+- **Authentication**: HMAC-SHA3-256 over full ciphertext
+- **Math core**: nCr (binomial coefficient) based encryption mod 2¹²⁷−1
+
+Backwards compatible: can read NCR2 files (read-only).
+
+## Requirements
+
+- Python 3.9+
+- **Zero external dependencies** — stdlib only
+
+## License
+
+MIT

ncr_cipher-1.0.0/ncr_cipher/__init__.py

@@ -0,0 +1,3 @@
+"""NCR Cipher — production-grade NCR3 encryption tool."""
+
+__version__ = "1.0.0"

ncr_cipher-1.0.0/ncr_cipher/cli.py

@@ -0,0 +1,381 @@
+# pyre-ignore-all-errors
+"""CLI entry point for the ``ncr`` command."""
+from __future__ import annotations
+
+import argparse
+import getpass
+import os
+import signal
+import sys
+import tempfile
+import time
+
+from ncr_cipher import __version__  # type: ignore
+from ncr_cipher import core  # type: ignore
+from ncr_cipher import ui  # type: ignore
+
+# ── Signal handling ─────────────────────────────────────────────────
+
+def _handle_sigint(*_: object) -> None:  # noqa: ANN401
+    sys.exit(130)
+
+if os.name != "nt":
+    signal.signal(signal.SIGINT, _handle_sigint)
+
+# ── Helpers ─────────────────────────────────────────────────────────
+
+def _prompt_password(confirm: bool = False) -> bytes:
+    """Prompt for password via getpass; optionally confirm."""
+    pw = getpass.getpass("Password: ")
+    if confirm:
+        pw2 = getpass.getpass("Confirm password: ")
+        if pw != pw2:
+            ui.error("Passwords do not match")
+            sys.exit(1)
+    return pw.encode("utf-8")
+
+
+def _resolve_password(args: argparse.Namespace, confirm: bool = False) -> bytes:
+    """If --key is given, load the key file; otherwise prompt password."""
+    if args.key:
+        kf_path = args.key
+        if not os.path.isfile(kf_path):
+            ui.error(f"Key file not found: {kf_path}")
+            sys.exit(1)
+        kf_pw = getpass.getpass("Key-file password: ").encode("utf-8")
+        with ui.Spinner("Unlocking key file…", silent=getattr(args, "silent", False)):
+            try:
+                content = _read_text(kf_path)
+                passphrase = core.load_keyfile(content, kf_pw)
+            except ValueError as exc:
+                ui.error(str(exc))
+                sys.exit(1)
+        return passphrase
+    return _prompt_password(confirm=confirm)
+
+
+def _read_text(path: str) -> str:
+    with open(path, "r", encoding="utf-8") as fh:
+        return fh.read()
+
+
+def _atomic_write(path: str, content: str) -> None:
+    """Write to a temp file then atomically rename."""
+    dirname = os.path.dirname(os.path.abspath(path))
+    fd, tmp = tempfile.mkstemp(dir=dirname, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(content)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _check_output(path: str, force: bool) -> None:
+    """If *path* exists and not --force, ask for confirmation."""
+    if os.path.exists(path):
+        if not force:
+            if not ui.confirm(f"Output file already exists: {path}\nOverwrite?"):
+                ui.error("Aborted")
+                sys.exit(1)
+
+
+def _human_size(n: int) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024:
+            return f"{n:.1f} {unit}" if isinstance(n, float) else f"{n} {unit}"
+        n /= 1024  # type: ignore[assignment]
+    return f"{n:.1f} TB"
+
+# ── Commands ────────────────────────────────────────────────────────
+
+def cmd_keygen(args: argparse.Namespace) -> None:
+    path = args.keygen
+    _check_output(path, args.force)
+    pow_level = args.pow
+    pw = _prompt_password(confirm=True)
+
+    with ui.Spinner(f"Generating key file (pow {pow_level})…", silent=args.silent):
+        content = core.generate_keyfile(pw, pow_level)
+
+    _atomic_write(path, content)
+    ui.ok(f"Key file written → {path}", silent=args.silent)
+    print(path)  # stdout – machine-readable
+
+
+def cmd_lock(args: argparse.Namespace) -> None:
+    src = args.lock
+    if not os.path.isfile(src):
+        ui.error(f"File not found: {src}")
+        sys.exit(1)
+
+    # Determine output path
+    if args.inplace:
+        dst = src
+    elif args.out:
+        dst = args.out
+    else:
+        dst = src + ".ncr3"
+
+    if not args.inplace:
+        _check_output(dst, args.force)
+
+    pw = _resolve_password(args)
+    pow_level = args.pow
+
+    data = open(src, "rb").read()
+    ui.info(f"Encrypting {_human_size(len(data))}…", silent=args.silent)
+
+    with ui.Spinner("Deriving key (scrypt)…", silent=args.silent):
+        raw_iv = os.urandom(32)
+        n1, n2, n3, sk, hk, pepper = core.derive_key_v3(pw, raw_iv, pow_level)
+
+    with ui.Spinner("Encrypting…", silent=args.silent):
+        ct = core.encrypt_raw(data, n1, n2, n3, sk, hk, pepper, raw_iv, pow_level)
+
+    _atomic_write(dst, ct)
+    ui.ok(f"Encrypted → {dst}", silent=args.silent)
+    print(dst)
+
+
+def cmd_unlock(args: argparse.Namespace) -> None:
+    src = args.unlock
+    if not os.path.isfile(src):
+        ui.error(f"File not found: {src}")
+        sys.exit(1)
+
+    content = _read_text(src)
+    version, file_strength = core.detect_version(content)
+
+    # Determine output path
+    if args.inplace:
+        dst = src
+    elif args.out:
+        dst = args.out
+    else:
+        # strip .ncr3 / .ncr2 extension
+        base, ext = os.path.splitext(src)
+        if ext.lower() in (".ncr3", ".ncr2"):
+            dst = base
+        else:
+            dst = src + ".dec"
+
+    if not args.inplace:
+        _check_output(dst, args.force)
+
+    pw = _resolve_password(args)
+
+    if args.pow != 3:
+        ui.info("Note: --pow flag is ignored during unlock (auto-detected from file)", silent=args.silent)
+
+    iv_hex = content.split("\n", 2)[1]
+    raw_iv = bytes.fromhex(iv_hex)
+
+    n3 = 0
+    pepper = b""
+    with ui.Spinner("Deriving key…", silent=args.silent):
+        if version == core.VERSION_3:
+            n1, n2, n3, sk, hk, pepper = core.derive_key_v3(pw, raw_iv, file_strength)
+        else:
+            n1, n2, sk, hk = core.derive_key_v2(pw, raw_iv)
+
+    with ui.Spinner("Decrypting…", silent=args.silent):
+        try:
+            if version == core.VERSION_3:
+                pt = core.decrypt_raw_v3(content, n1, n2, n3, sk, hk, pepper)
+            else:
+                pt = core.decrypt_raw_v2(content, n1, n2, sk, hk)
+        except ValueError as exc:
+            ui.error(str(exc))
+            sys.exit(1)
+
+    # Write as binary
+    dirname = os.path.dirname(os.path.abspath(dst))
+    fd, tmp = tempfile.mkstemp(dir=dirname, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(pt)
+        os.replace(tmp, dst)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+    ui.ok(f"Decrypted → {dst}  ({_human_size(len(pt))})", silent=args.silent)
+    print(dst)
+
+
+def cmd_verify(args: argparse.Namespace) -> None:
+    src = args.verify
+    if not os.path.isfile(src):
+        ui.error(f"File not found: {src}")
+        sys.exit(1)
+
+    content = _read_text(src)
+    pw = _resolve_password(args)
+
+    if args.pow != 3:
+        ui.info("Note: --pow flag is ignored during verify (auto-detected from file)", silent=args.silent)
+
+    with ui.Spinner("Verifying HMAC…", silent=args.silent):
+        ok = core.verify_hmac(content, pw)
+
+    if ok:
+        ui.ok("OK — HMAC valid", silent=args.silent)
+        print("OK")
+        sys.exit(0)
+    else:
+        ui.error("TAMPERED — HMAC mismatch")
+        print("TAMPERED")
+        sys.exit(1)
+
+
+def cmd_info(args: argparse.Namespace) -> None:
+    src = args.info
+    if not os.path.isfile(src):
+        ui.error(f"File not found: {src}")
+        sys.exit(1)
+
+    content = _read_text(src)
+    try:
+        hdr = core.parse_header(content)
+    except ValueError as exc:
+        ui.error(str(exc))
+        sys.exit(1)
+
+    file_size = os.path.getsize(src)
+    sys.stderr.write(
+        f"  Version:     {ui.bold(hdr['version'])}\n"
+        f"  Pow:         {hdr['strength']}\n"
+        f"  IV:          {hdr['iv'][:32]}{'…' if len(hdr['iv']) > 32 else ''}\n"
+        f"  HMAC:        {hdr['hmac'][:32]}…\n"
+        f"  Blocks:      {hdr['block_count']}\n"
+        f"  File size:   {_human_size(file_size)}\n"
+    )
+
+
+def cmd_bench(args: argparse.Namespace) -> None:
+    pw = b"benchmark-password-1234"
+    salt = os.urandom(32)
+
+    sys.stderr.write(ui.bold("\n  KDF Benchmark (scrypt, pow=3)\n"))
+    t0 = time.perf_counter()
+    core.derive_key_v3(pw, salt, 3)
+    kdf_time = time.perf_counter() - t0
+    sys.stderr.write(f"  Time: {kdf_time:.2f}s\n")
+
+    # Pre-derive keys at strength=1 for encrypt speed tests
+    n1, n2, n3, sk, hk, pepper = core.derive_key_v3(pw, salt, 1)
+
+    sizes = [256, 1024, 4096, 16384, 65536]
+    sys.stderr.write(ui.bold("\n  Encrypt Speed\n"))
+    sys.stderr.write(f"  {'Size':>6s}  {'Time':>8s}  {'Speed':>10s}\n")
+    sys.stderr.write(f"  {'─' * 6}  {'─' * 8}  {'─' * 10}\n")
+
+    for sz in sizes:
+        data = os.urandom(sz)
+        raw_iv = os.urandom(32)
+        t0 = time.perf_counter()
+        core.encrypt_raw(data, n1, n2, n3, sk, hk, pepper, raw_iv)
+        elapsed = time.perf_counter() - t0
+        label = f"{sz}B" if sz < 1024 else f"{sz // 1024}KB"
+        speed = sz / elapsed if elapsed > 0 else float("inf")
+        sys.stderr.write(f"  {label:>6s}  {elapsed:>7.3f}s  {speed:>8.0f} B/s\n")
+
+    sys.stderr.write("\n")
+
+
+def cmd_test(args: argparse.Namespace) -> None:
+    passed: int = 0
+    failed: int = 0
+
+    sys.stderr.write(ui.bold("\n  NCR Self-Tests\n\n"))
+    for name, fn in core.SELF_TESTS:
+        try:
+            fn()
+            sys.stderr.write(f"  {ui.green('PASS')}  {name}\n")
+            passed = passed + 1
+        except Exception as exc:
+            sys.stderr.write(f"  {ui.red('FAIL')}  {name}: {exc}\n")
+            failed = failed + 1
+
+    sys.stderr.write(f"\n  {passed} passed, {failed} failed\n\n")
+    sys.exit(1 if failed else 0)
+
+
+def cmd_version() -> None:
+    print(f"ncr {__version__}")
+
+# ── Argument parser ─────────────────────────────────────────────────
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="ncr",
+        description="NCR3 encryption tool — encrypt, decrypt, and verify files.",
+    )
+
+    # Commands (mutually exclusive at the top level)
+    cmd = p.add_mutually_exclusive_group()
+    cmd.add_argument("--keygen", metavar="KEYFILE", help="Generate a new key file")
+    cmd.add_argument("--lock",   metavar="FILE",    help="Encrypt a file")
+    cmd.add_argument("--unlock", metavar="FILE",    help="Decrypt a file")
+    cmd.add_argument("--verify", metavar="FILE",    help="Verify HMAC without decrypting")
+    cmd.add_argument("--info",   metavar="FILE",    help="Show file info (no password needed)")
+    cmd.add_argument("--bench",  action="store_true", help="Run benchmarks")
+    cmd.add_argument("--test",   action="store_true", help="Run internal self-tests")
+    cmd.add_argument("--version", action="store_true", help="Print version")
+
+    # Shared options
+    p.add_argument("--key",     "-k", metavar="KEYFILE", help="Key file for lock/unlock/verify")
+    p.add_argument("--out",     "-o", metavar="PATH",    help="Output path override")
+    p.add_argument("--inplace", "-i", action="store_true", help="Overwrite original file")
+    p.add_argument("--silent",  "-s", action="store_true", help="Suppress non-error output")
+    p.add_argument("--force",   "-f", action="store_true", help="Overwrite without confirmation")
+    p.add_argument("--pow", type=int, choices=range(1, 6), default=3,
+                   metavar="1-5", help="KDF strength (pow) level (1=fast, 3=default, 5=strong). Ignored during unlock.")
+
+    return p
+
+# ── Main ────────────────────────────────────────────────────────────
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    try:
+        if args.keygen:
+            cmd_keygen(args)
+        elif args.lock:
+            cmd_lock(args)
+        elif args.unlock:
+            cmd_unlock(args)
+        elif args.verify:
+            cmd_verify(args)
+        elif args.info:
+            cmd_info(args)
+        elif args.bench:
+            cmd_bench(args)
+        elif args.test:
+            cmd_test(args)
+        elif args.version:
+            cmd_version()
+        else:
+            parser.print_help(sys.stderr)
+            sys.exit(2)
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except SystemExit:
+        raise
+    except Exception as exc:
+        ui.error(str(exc))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()