modelsign 1.0.0__py3-none-any.whl

modelsign/__init__.py

@@ -0,0 +1,21 @@
+"""modelsign — Sign AI models with identity. Verify anywhere."""
+
+__version__ = "1.0.0"
+
+from modelsign.identity.card import ModelCard, validate_card
+from modelsign.identity.canonical import canonical_json
+from modelsign.crypto.keys import generate_keypair, load_private_key, load_public_key, compute_fingerprint
+from modelsign.crypto.sign import sign_bytes, build_file_message, build_dir_message
+from modelsign.crypto.verify import verify_bytes
+from modelsign.formats.single import hash_file
+from modelsign.formats.directory import hash_directory
+from modelsign.sig import SigFile, write_sig, read_sig
+
+__all__ = [
+    "__version__",
+    "ModelCard", "validate_card", "canonical_json",
+    "generate_keypair", "load_private_key", "load_public_key", "compute_fingerprint",
+    "sign_bytes", "build_file_message", "build_dir_message", "verify_bytes",
+    "hash_file", "hash_directory",
+    "SigFile", "write_sig", "read_sig",
+]

modelsign/cli.py

@@ -0,0 +1,402 @@
+"""Click-based CLI for modelsign — sign, verify, inspect AI models."""
+
+import base64
+import json
+import sys
+import time
+from pathlib import Path
+
+import click
+
+import modelsign
+from modelsign.crypto.keys import (
+    generate_keypair,
+    load_private_key,
+    load_public_key,
+    compute_fingerprint,
+    public_key_to_bytes,
+    keyring_add,
+    keyring_list,
+    keyring_remove,
+)
+from modelsign.crypto.sign import sign_bytes, build_file_message, build_dir_message
+from modelsign.crypto.verify import verify_bytes
+from modelsign.formats.single import hash_file
+from modelsign.formats.directory import hash_directory
+from modelsign.identity.card import ModelCard, validate_card
+from modelsign.identity.canonical import canonical_json
+from modelsign.sig import SigFile, write_sig, read_sig
+
+DEFAULT_KEY_DIR = Path.home() / ".modelsign"
+
+
+@click.group()
+def main():
+    """modelsign — Sign AI models with identity. Verify anywhere."""
+
+
+@main.command()
+def version():
+    """Print modelsign version."""
+    click.echo(modelsign.__version__)
+
+
+@main.command()
+@click.option("--out", "out_path", default=None, help="Path for private key PEM file.")
+def keygen(out_path):
+    """Generate an Ed25519 keypair."""
+    if out_path is not None:
+        priv_path = Path(out_path)
+        key_dir = priv_path.parent
+        # generate_keypair always creates private.pem + public.pem in the dir.
+        # We need to handle a custom private key name — generate into a temp subdir
+        # then move, OR: call generate_keypair on the parent dir and rename if needed.
+        # Simplest: generate into parent dir under standard names, then rename to desired.
+        tmp_priv = key_dir / "private.pem"
+        tmp_pub = key_dir / "public.pem"
+
+        # If already exists at out_path, just report fingerprint.
+        if priv_path.exists():
+            pub_path = _find_pubkey_for_private(priv_path)
+            priv_key = load_private_key(priv_path)
+            fp = compute_fingerprint(priv_key.public_key())
+            click.echo(f"Key already exists: {priv_path}")
+            click.echo(f"Fingerprint: {fp}")
+            return
+
+        key_dir.mkdir(parents=True, exist_ok=True)
+
+        if priv_path.name != "private.pem":
+            # Generate with standard names then rename
+            from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+            from cryptography.hazmat.primitives import serialization
+            import os
+
+            private_key = Ed25519PrivateKey.generate()
+            priv_path.write_bytes(private_key.private_bytes(
+                encoding=serialization.Encoding.PEM,
+                format=serialization.PrivateFormat.PKCS8,
+                encryption_algorithm=serialization.NoEncryption(),
+            ))
+            os.chmod(priv_path, 0o600)
+
+            pub_path = priv_path.parent / (priv_path.stem + "_public.pem")
+            # Use sibling public.pem convention
+            pub_path = priv_path.with_name("public.pem")
+            pub_path.write_bytes(private_key.public_key().public_bytes(
+                encoding=serialization.Encoding.PEM,
+                format=serialization.PublicFormat.SubjectPublicKeyInfo,
+            ))
+            fp = compute_fingerprint(private_key.public_key())
+        else:
+            actual_priv, actual_pub = generate_keypair(key_dir)
+            priv_key = load_private_key(actual_priv)
+            fp = compute_fingerprint(priv_key.public_key())
+    else:
+        priv_path, pub_path = generate_keypair(DEFAULT_KEY_DIR)
+        priv_key = load_private_key(priv_path)
+        fp = compute_fingerprint(priv_key.public_key())
+
+    click.echo(f"Private key: {priv_path}")
+    pub_path = _find_pubkey_for_private(priv_path)
+    click.echo(f"Public key:  {pub_path}")
+    click.echo(f"Fingerprint: {fp}")
+
+
+def _find_pubkey_for_private(priv_path: Path) -> Path:
+    """Locate the public key alongside a private key."""
+    # Standard convention: public.pem lives next to private.pem
+    pub = priv_path.parent / "public.pem"
+    if pub.exists():
+        return pub
+    # Fallback: same stem with _public suffix
+    pub2 = priv_path.with_name(priv_path.stem + "_public.pem")
+    if pub2.exists():
+        return pub2
+    return pub  # Return expected path even if missing (for display)
+
+
+@main.command()
+@click.argument("model_path")
+@click.option("--name", default=None, help="Model name (required if --identity not given).")
+@click.option("--identity", "identity_file", default=None, help="Path to JSON identity card file.")
+@click.option("--key", "key_path", default=None, help="Path to private key PEM file.")
+@click.option("--out", "out_path", default=None, help="Output .sig file path (default: MODEL.sig).")
+def sign(model_path, name, identity_file, key_path, out_path):
+    """Sign a model file or directory."""
+    model_path = Path(model_path)
+    if not model_path.exists():
+        click.echo(f"Error: model not found: {model_path}", err=True)
+        sys.exit(1)
+
+    # Resolve private key
+    if key_path is not None:
+        priv_key_path = Path(key_path)
+    else:
+        priv_key_path = DEFAULT_KEY_DIR / "private.pem"
+        if not priv_key_path.exists():
+            click.echo(
+                f"Error: no key found at {priv_key_path}. Run 'modelsign keygen' first.",
+                err=True,
+            )
+            sys.exit(1)
+
+    try:
+        private_key = load_private_key(priv_key_path)
+    except Exception as e:
+        click.echo(f"Error loading private key: {e}", err=True)
+        sys.exit(1)
+
+    pub_key = private_key.public_key()
+    fingerprint = compute_fingerprint(pub_key)
+    pub_key_b64 = base64.b64encode(public_key_to_bytes(pub_key)).decode("ascii")
+
+    # Build identity card
+    if identity_file is not None:
+        try:
+            card_data = json.loads(Path(identity_file).read_text())
+            card = ModelCard.from_dict(card_data)
+        except Exception as e:
+            click.echo(f"Error reading identity file: {e}", err=True)
+            sys.exit(1)
+    elif name is not None:
+        card = ModelCard(name=name)
+    else:
+        click.echo("Error: provide --name or --identity.", err=True)
+        sys.exit(1)
+
+    try:
+        validate_card(card)
+    except ValueError as e:
+        click.echo(f"Error: invalid identity card: {e}", err=True)
+        sys.exit(1)
+
+    identity_dict = card.to_dict()
+    identity_bytes = canonical_json(identity_dict)
+
+    # Hash model and build message
+    manifest = None
+    if model_path.is_dir():
+        manifest, model_hash = hash_directory(model_path)
+        message = build_dir_message(model_hash, identity_bytes)
+        file_label = str(model_path)
+    else:
+        model_hash = hash_file(model_path)
+        message = build_file_message(model_hash, identity_bytes)
+        file_label = model_path.name
+
+    # Sign
+    signature_bytes = sign_bytes(message, private_key)
+    signature_b64 = base64.b64encode(signature_bytes).decode("ascii")
+
+    signed_at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+    sig = SigFile(
+        modelsign_version="1.0",
+        file=file_label,
+        sha256=f"sha256:{model_hash}",
+        signature=signature_b64,
+        algorithm="ed25519",
+        signed_at=signed_at,
+        public_key=pub_key_b64,
+        key_fingerprint=fingerprint,
+        identity=identity_dict,
+        manifest=manifest,
+    )
+
+    sig_path = Path(out_path) if out_path else Path(str(model_path) + ".sig")
+    write_sig(sig, sig_path)
+
+    click.echo(f"Signed:      {model_path}")
+    click.echo(f"Sig file:    {sig_path}")
+    click.echo(f"Fingerprint: {fingerprint}")
+    click.echo(f"SHA-256:     sha256:{model_hash[:16]}...")
+
+
+@main.command()
+@click.argument("model_path")
+@click.option("--sig", "sig_path", default=None, help="Path to .sig file (default: MODEL.sig).")
+@click.option("--pubkey", "pubkey_path", default=None, help="Path to trusted public key PEM.")
+@click.option("--json", "output_json", is_flag=True, default=False, help="Output JSON.")
+@click.option("--quiet", is_flag=True, default=False, help="Suppress output; use exit code only.")
+def verify(model_path, sig_path, pubkey_path, output_json, quiet):
+    """Verify a signed model file or directory."""
+    model_path = Path(model_path)
+
+    # Locate sig file
+    if sig_path is not None:
+        sig_file_path = Path(sig_path)
+    else:
+        sig_file_path = Path(str(model_path) + ".sig")
+
+    if not sig_file_path.exists():
+        if not quiet:
+            click.echo(f"Error: sig file not found: {sig_file_path}", err=True)
+        sys.exit(2)
+
+    if not model_path.exists():
+        if not quiet:
+            click.echo(f"Error: model not found: {model_path}", err=True)
+        sys.exit(2)
+
+    # Read sig
+    try:
+        sig = read_sig(sig_file_path)
+    except Exception as e:
+        if not quiet:
+            click.echo(f"Error reading sig file: {e}", err=True)
+        sys.exit(2)
+
+    # Reconstruct public key for verification
+    try:
+        if pubkey_path is not None:
+            pub_key = load_public_key(Path(pubkey_path))
+        else:
+            # Use embedded public key from sig file
+            raw_pub = base64.b64decode(sig.public_key)
+            from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+            from cryptography.hazmat.primitives import serialization
+            pub_key = Ed25519PublicKey.from_public_bytes(raw_pub)
+    except Exception as e:
+        if not quiet:
+            click.echo(f"Error loading public key: {e}", err=True)
+        sys.exit(2)
+
+    # Hash model
+    try:
+        if model_path.is_dir():
+            _, model_hash = hash_directory(model_path)
+        else:
+            model_hash = hash_file(model_path)
+    except Exception as e:
+        if not quiet:
+            click.echo(f"Error hashing model: {e}", err=True)
+        sys.exit(2)
+
+    # Rebuild message and verify
+    identity_bytes = canonical_json(sig.identity)
+    if model_path.is_dir():
+        message = build_dir_message(model_hash, identity_bytes)
+    else:
+        message = build_file_message(model_hash, identity_bytes)
+
+    try:
+        signature_bytes = base64.b64decode(sig.signature)
+    except Exception as e:
+        if not quiet:
+            click.echo(f"Error decoding signature: {e}", err=True)
+        sys.exit(2)
+
+    ok = verify_bytes(message, signature_bytes, pub_key)
+
+    if output_json:
+        result = {
+            "verified": ok,
+            "model": str(model_path),
+            "sha256": f"sha256:{model_hash}",
+            "fingerprint": sig.key_fingerprint,
+            "signed_at": sig.signed_at,
+            "identity": sig.identity,
+        }
+        click.echo(json.dumps(result))
+        if not ok:
+            sys.exit(1)
+        return
+
+    if quiet:
+        if not ok:
+            sys.exit(1)
+        return
+
+    if ok:
+        click.echo(f"VERIFIED: {model_path}")
+        click.echo(f"  Identity: {sig.identity.get('name', '(unnamed)')}")
+        click.echo(f"  Fingerprint: {sig.key_fingerprint}")
+        click.echo(f"  Signed at: {sig.signed_at} (unverified — no RFC 3161 timestamp)")
+    else:
+        click.echo(f"FAILED: signature verification failed for {model_path}")
+        sys.exit(1)
+
+
+@main.command()
+@click.argument("sig_file")
+@click.option("--json", "output_json", is_flag=True, default=False, help="Output raw JSON.")
+def inspect(sig_file, output_json):
+    """Inspect a .sig file and display identity card."""
+    sig_path = Path(sig_file)
+
+    try:
+        sig = read_sig(sig_path)
+    except FileNotFoundError:
+        click.echo(f"Error: sig file not found: {sig_path}", err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(f"Error reading sig file: {e}", err=True)
+        sys.exit(1)
+
+    if output_json:
+        from dataclasses import asdict
+        click.echo(json.dumps(asdict(sig), indent=2))
+        return
+
+    # Human-readable output
+    click.echo(f"File:        {sig.file}")
+    click.echo(f"SHA-256:     {sig.sha256}")
+    click.echo(f"Algorithm:   {sig.algorithm}")
+    click.echo(f"Fingerprint: {sig.key_fingerprint}")
+    click.echo(f"Signed at:   {sig.signed_at}")
+    click.echo("Identity:")
+    for key, val in sig.identity.items():
+        if isinstance(val, dict):
+            click.echo(f"  {key}:")
+            for k2, v2 in val.items():
+                click.echo(f"    {k2}: {v2}")
+        else:
+            click.echo(f"  {key}: {val}")
+
+
+@main.group()
+def keyring():
+    """Manage trusted public keys."""
+
+
+@keyring.command("add")
+@click.argument("pubkey_path")
+@click.argument("alias")
+@click.option("--keyring-dir", default=None, help="Keyring directory (default: ~/.modelsign/keyring).")
+def keyring_add_cmd(pubkey_path, alias, keyring_dir):
+    """Add a public key to the trusted keyring."""
+    kr_dir = Path(keyring_dir) if keyring_dir else DEFAULT_KEY_DIR / "keyring"
+    try:
+        keyring_add(kr_dir, Path(pubkey_path), alias)
+        click.echo(f"Added key '{alias}' to keyring at {kr_dir}")
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+@keyring.command("list")
+@click.option("--keyring-dir", default=None, help="Keyring directory (default: ~/.modelsign/keyring).")
+def keyring_list_cmd(keyring_dir):
+    """List all trusted public keys."""
+    kr_dir = Path(keyring_dir) if keyring_dir else DEFAULT_KEY_DIR / "keyring"
+    keys = keyring_list(kr_dir)
+    if not keys:
+        click.echo("No keys in keyring.")
+        return
+    for entry in keys:
+        click.echo(f"{entry['alias']:<20} {entry['fingerprint']}  {entry['path']}")
+
+
+@keyring.command("remove")
+@click.argument("alias")
+@click.option("--keyring-dir", default=None, help="Keyring directory (default: ~/.modelsign/keyring).")
+def keyring_remove_cmd(alias, keyring_dir):
+    """Remove a key from the trusted keyring."""
+    kr_dir = Path(keyring_dir) if keyring_dir else DEFAULT_KEY_DIR / "keyring"
+    try:
+        keyring_remove(kr_dir, alias)
+        click.echo(f"Removed key '{alias}' from keyring.")
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)

modelsign/crypto/__init__.py

@@ -0,0 +1,23 @@
+"""Cryptographic signing and verification."""
+
+from modelsign.crypto.sign import sign_bytes, build_file_message, build_dir_message
+from modelsign.crypto.verify import verify_bytes
+from modelsign.crypto.keys import (
+    generate_keypair,
+    load_private_key,
+    load_public_key,
+    compute_fingerprint,
+    public_key_to_bytes,
+)
+
+__all__ = [
+    "sign_bytes",
+    "build_file_message",
+    "build_dir_message",
+    "verify_bytes",
+    "generate_keypair",
+    "load_private_key",
+    "load_public_key",
+    "compute_fingerprint",
+    "public_key_to_bytes",
+]

modelsign/crypto/keys.py

@@ -0,0 +1,111 @@
+"""Ed25519 key generation, loading, fingerprints, and keyring management."""
+
+import hashlib
+import os
+import shutil
+from pathlib import Path
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from cryptography.hazmat.primitives import serialization
+
+# Display-only fingerprint length. 8 hex chars = 32 bits.
+# NOT collision-resistant. Use full public key bytes for registry lookups (v2).
+FINGERPRINT_HEX_CHARS = 8
+
+
+def generate_keypair(key_dir: Path) -> tuple[Path, Path]:
+    """Generate Ed25519 keypair. Returns (priv_path, pub_path).
+
+    If keys already exist, returns existing paths without overwriting.
+    """
+    key_dir = Path(key_dir)
+    key_dir.mkdir(parents=True, exist_ok=True)
+    priv_path = key_dir / "private.pem"
+    pub_path = key_dir / "public.pem"
+
+    if priv_path.exists() and pub_path.exists():
+        return priv_path, pub_path
+
+    private_key = Ed25519PrivateKey.generate()
+
+    priv_path.write_bytes(private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    ))
+    os.chmod(priv_path, 0o600)
+
+    pub_path.write_bytes(private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    ))
+
+    return priv_path, pub_path
+
+
+def load_private_key(path: Path) -> Ed25519PrivateKey:
+    """Load Ed25519 private key from PEM file."""
+    key = serialization.load_pem_private_key(Path(path).read_bytes(), password=None)
+    if not isinstance(key, Ed25519PrivateKey):
+        raise ValueError(f"Expected Ed25519 private key, got {type(key).__name__}")
+    return key
+
+
+def load_public_key(path: Path) -> Ed25519PublicKey:
+    """Load Ed25519 public key from PEM file."""
+    key = serialization.load_pem_public_key(Path(path).read_bytes())
+    if not isinstance(key, Ed25519PublicKey):
+        raise ValueError(f"Expected Ed25519 public key, got {type(key).__name__}")
+    return key
+
+
+def public_key_to_bytes(key: Ed25519PublicKey) -> bytes:
+    """Extract raw 32-byte public key."""
+    return key.public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+
+
+def compute_fingerprint(key: Ed25519PublicKey) -> str:
+    """Compute display fingerprint: ed25519:<first 8 hex of SHA-256(raw_pubkey)>.
+
+    This is display-only (32 bits), NOT collision-resistant.
+    """
+    raw = public_key_to_bytes(key)
+    digest = hashlib.sha256(raw).hexdigest()
+    return f"ed25519:{digest[:FINGERPRINT_HEX_CHARS]}"
+
+
+def keyring_add(keyring_dir: Path, pubkey_path: Path, alias: str) -> None:
+    """Add a public key to the trusted keyring."""
+    keyring_dir = Path(keyring_dir)
+    keyring_dir.mkdir(parents=True, exist_ok=True)
+    dest = keyring_dir / f"{alias}.pem"
+    shutil.copy2(pubkey_path, dest)
+
+
+def keyring_list(keyring_dir: Path) -> list[dict]:
+    """List all trusted keys with alias and fingerprint."""
+    keyring_dir = Path(keyring_dir)
+    if not keyring_dir.exists():
+        return []
+    result = []
+    for pem_file in sorted(keyring_dir.glob("*.pem")):
+        key = load_public_key(pem_file)
+        result.append({
+            "alias": pem_file.stem,
+            "fingerprint": compute_fingerprint(key),
+            "path": str(pem_file),
+        })
+    return result
+
+
+def keyring_remove(keyring_dir: Path, alias: str) -> None:
+    """Remove a key from the trusted keyring by alias."""
+    target = Path(keyring_dir) / f"{alias}.pem"
+    if target.exists():
+        target.unlink()

modelsign/crypto/sign.py

@@ -0,0 +1,28 @@
+"""Ed25519 signing operations with domain-prefixed messages."""
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+
+def sign_bytes(message: bytes, private_key: Ed25519PrivateKey) -> bytes:
+    """Sign a message with Ed25519. Returns 64-byte signature."""
+    return private_key.sign(message)
+
+
+def build_file_message(file_hash: str, identity_bytes: bytes) -> bytes:
+    """Build the message to sign for a single file.
+
+    Format: b"modelsign-v1:" + file_hash + b":" + identity_bytes
+
+    file_hash is always 64 hex chars (SHA-256), so the colon separator
+    is unambiguous. Do not change this invariant without updating the
+    domain prefix version.
+    """
+    return b"modelsign-v1:" + file_hash.encode("utf-8") + b":" + identity_bytes
+
+
+def build_dir_message(manifest_hash: str, identity_bytes: bytes) -> bytes:
+    """Build the message to sign for a directory.
+
+    Format: b"modelsign-v1:dir:" + manifest_hash + b":" + identity_bytes
+    """
+    return b"modelsign-v1:dir:" + manifest_hash.encode("utf-8") + b":" + identity_bytes

modelsign/crypto/verify.py

@@ -0,0 +1,13 @@
+"""Ed25519 verification operations."""
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+
+def verify_bytes(message: bytes, signature: bytes, public_key: Ed25519PublicKey) -> bool:
+    """Verify an Ed25519 signature. Returns True if valid, False otherwise."""
+    try:
+        public_key.verify(signature, message)
+        return True
+    except InvalidSignature:
+        return False

modelsign/formats/__init__.py

@@ -0,0 +1,6 @@
+"""File and directory hashing for modelsign."""
+
+from modelsign.formats.single import hash_file
+from modelsign.formats.directory import hash_directory
+
+__all__ = ["hash_file", "hash_directory"]

modelsign/formats/directory.py

@@ -0,0 +1,33 @@
+"""Directory manifest hashing for multi-file models."""
+
+import hashlib
+from pathlib import Path
+
+from modelsign.formats.single import hash_file
+from modelsign.identity.canonical import canonical_json
+
+
+def hash_directory(path: Path) -> tuple[dict, str]:
+    """Hash all files in a directory, return (manifest_dict, manifest_hash).
+
+    Files are sorted by UTF-8 byte order (NOT locale-aware) for
+    deterministic results across Linux/macOS/Windows.
+    """
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Directory not found: {path}")
+
+    all_files = [f for f in path.rglob("*") if f.is_file()]
+    all_files.sort(key=lambda f: str(f.relative_to(path)).encode("utf-8"))
+
+    files_dict = {}
+    for file_path in all_files:
+        rel_path = str(file_path.relative_to(path))
+        file_hash = hash_file(file_path)
+        files_dict[rel_path] = f"sha256:{file_hash}"
+
+    manifest = {"files": files_dict}
+    manifest_bytes = canonical_json(manifest)
+    manifest_hash = hashlib.sha256(manifest_bytes).hexdigest()
+
+    return manifest, manifest_hash

modelsign/formats/single.py

@@ -0,0 +1,26 @@
+"""Streaming SHA-256 hash for single model files."""
+
+import hashlib
+from pathlib import Path
+
+CHUNK_SIZE = 1024 * 1024  # 1 MB
+
+
+def hash_file(path: Path) -> str:
+    """Compute SHA-256 hash of a file using streaming reads.
+
+    Returns hex digest string (64 chars).
+    Raises FileNotFoundError if path doesn't exist.
+    """
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while True:
+            chunk = f.read(CHUNK_SIZE)
+            if not chunk:
+                break
+            h.update(chunk)
+    return h.hexdigest()

modelsign/identity/__init__.py

@@ -0,0 +1,6 @@
+"""Model identity card and canonical JSON."""
+
+from modelsign.identity.canonical import canonical_json
+from modelsign.identity.card import ModelCard, validate_card
+
+__all__ = ["canonical_json", "ModelCard", "validate_card"]

modelsign/identity/canonical.py

@@ -0,0 +1,20 @@
+"""Deterministic JSON serialization using RFC 8785 (JCS).
+
+This module is the SINGLE SOURCE OF TRUTH for JSON canonicalization
+in modelsign. All signing and verification MUST use canonical_json()
+from this module to produce deterministic bytes.
+"""
+
+import rfc8785
+
+
+def canonical_json(obj: dict) -> bytes:
+    """Serialize a dict to canonical JSON bytes (RFC 8785 JCS).
+
+    Returns UTF-8 bytes with:
+    - Keys sorted lexicographically at all nesting levels
+    - No extra whitespace
+    - ECMAScript number serialization
+    - Minimal string escaping
+    """
+    return rfc8785.dumps(obj)

modelsign/identity/card.py

@@ -0,0 +1,71 @@
+"""Model Identity Card — structured, signed metadata about a model."""
+
+import re
+from dataclasses import dataclass, field, fields
+from typing import Optional
+
+_HASH_PATTERN = re.compile(r"^sha256:[0-9a-fA-F]+$")
+
+
+@dataclass
+class ModelCard:
+    """Structured identity metadata for a signed model.
+
+    Only `name` is required. All other fields are optional.
+    Unknown fields from JSON are preserved in `extra` for forward compatibility.
+    """
+
+    name: str = ""
+    architecture: Optional[str] = None
+    base_model: Optional[str] = None
+    parent_signature: Optional[str] = None
+    version: Optional[str] = None
+    creator: Optional[str] = None
+    contact: Optional[str] = None
+    license: Optional[str] = None
+    intended_use: Optional[str] = None
+    restrictions: Optional[str] = None
+    training: Optional[dict] = None
+    quantization: Optional[str] = None
+    eval_metrics: Optional[dict] = None
+    merge_details: Optional[str] = None
+    extra: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        """Convert to dict, excluding None values and empty extra."""
+        result = {}
+        for f in fields(self):
+            val = getattr(self, f.name)
+            if f.name == "extra":
+                if val:
+                    result.update(val)
+            elif val is not None:
+                result[f.name] = val
+        return result
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ModelCard":
+        """Create from dict, preserving unknown fields in extra."""
+        known = {f.name for f in fields(cls)} - {"extra"}
+        known_data = {k: v for k, v in data.items() if k in known}
+        unknown_data = {k: v for k, v in data.items() if k not in known}
+        return cls(**known_data, extra=unknown_data)
+
+
+def validate_card(card: ModelCard) -> None:
+    """Validate a ModelCard. Raises ValueError on invalid fields."""
+    if not isinstance(card.name, str) or not card.name.strip():
+        raise ValueError("name must be a non-empty string")
+
+    if card.parent_signature is not None:
+        if not _HASH_PATTERN.match(card.parent_signature):
+            raise ValueError(
+                f"parent_signature must match 'sha256:<hex>', got: {card.parent_signature}"
+            )
+
+    if card.training and "dataset_hash" in card.training:
+        dh = card.training["dataset_hash"]
+        if not _HASH_PATTERN.match(dh):
+            raise ValueError(
+                f"training.dataset_hash must match 'sha256:<hex>', got: {dh}"
+            )

modelsign/middleware/__init__.py

@@ -0,0 +1,5 @@
+"""Optional response signing middleware for API endpoints."""
+
+from modelsign.middleware.response import ResponseSigner
+
+__all__ = ["ResponseSigner"]

modelsign/middleware/response.py

@@ -0,0 +1,42 @@
+"""Ed25519 response signing for API authenticity."""
+
+import base64
+import hashlib
+from datetime import datetime, timezone
+from pathlib import Path
+
+from cryptography.hazmat.primitives import serialization
+
+from modelsign.crypto.keys import load_private_key
+from modelsign.identity.canonical import canonical_json
+
+
+class ResponseSigner:
+    """Signs API responses with Ed25519 for authenticity verification."""
+
+    def __init__(self, key_path: str | Path):
+        self._private_key = load_private_key(Path(key_path).expanduser())
+        self._public_key = self._private_key.public_key()
+
+    def sign(self, data: dict) -> dict:
+        """Sign response data. Returns envelope with data, signature, timestamp, fingerprint."""
+        timestamp = datetime.now(timezone.utc).isoformat()
+        canonical = canonical_json(data)
+        fingerprint = hashlib.sha256(canonical).hexdigest()[:16]
+
+        message = b"modelsign-v1:response:" + canonical + b":" + timestamp.encode("utf-8")
+        signature = self._private_key.sign(message)
+
+        return {
+            "data": data,
+            "signature": base64.b64encode(signature).decode(),
+            "timestamp": timestamp,
+            "fingerprint": fingerprint,
+        }
+
+    def get_public_key_pem(self) -> str:
+        """Export public key PEM for verification by clients."""
+        return self._public_key.public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        ).decode()

modelsign/sig.py

@@ -0,0 +1,118 @@
+"""Sig file I/O — reading, writing, and version management for .sig files."""
+
+import json
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Optional
+
+
+CURRENT_VERSION = "1.0"
+SUPPORTED_MAJOR = 1
+
+
+class SigVersionError(Exception):
+    """Raised when .sig file version is incompatible."""
+    pass
+
+
+@dataclass
+class SigFile:
+    """In-memory representation of a .sig file."""
+
+    modelsign_version: str
+    file: str
+    sha256: str
+    signature: str
+    algorithm: str
+    signed_at: str
+    public_key: str
+    key_fingerprint: str
+    identity: dict
+    manifest: Optional[dict] = None
+
+
+def write_sig(sig: SigFile, path: Path) -> None:
+    """Write a SigFile to disk as human-readable JSON."""
+    path = Path(path)
+    data = asdict(sig)
+    data = {k: v for k, v in data.items() if v is not None}
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+
+
+def read_sig(path: Path, validate_fingerprint: bool = False) -> SigFile:
+    """Read a .sig file and validate version.
+
+    Version policy:
+    - Known version (1.0): load normally
+    - Higher minor (1.x): warn to stderr, load
+    - Higher major (2+): raise SigVersionError
+    - Missing/malformed: raise SigVersionError
+    """
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Signature file not found: {path}")
+
+    data = json.loads(path.read_text())
+
+    version = data.get("modelsign_version")
+    if not version or not isinstance(version, str):
+        raise SigVersionError("invalid sig file: missing or malformed modelsign_version")
+
+    try:
+        parts = version.split(".")
+        major = int(parts[0])
+        minor = int(parts[1]) if len(parts) > 1 else 0
+    except (ValueError, IndexError):
+        raise SigVersionError(f"invalid sig file: cannot parse version '{version}'")
+
+    if major > SUPPORTED_MAJOR:
+        raise SigVersionError(
+            f"this sig requires modelsign v{major}+, please upgrade "
+            f"(current: v{CURRENT_VERSION})"
+        )
+
+    if major == SUPPORTED_MAJOR and minor > 0:
+        print(
+            f"Warning: sig created with newer modelsign {version}, "
+            f"some fields may be unrecognized",
+            file=sys.stderr,
+        )
+
+    sig = SigFile(
+        modelsign_version=data["modelsign_version"],
+        file=data["file"],
+        sha256=data["sha256"],
+        signature=data["signature"],
+        algorithm=data["algorithm"],
+        signed_at=data["signed_at"],
+        public_key=data["public_key"],
+        key_fingerprint=data["key_fingerprint"],
+        identity=data["identity"],
+        manifest=data.get("manifest"),
+    )
+
+    if validate_fingerprint:
+        _check_fingerprint(sig)
+
+    return sig
+
+
+def _check_fingerprint(sig: SigFile) -> None:
+    """Validate that key_fingerprint matches public_key."""
+    import base64
+    import hashlib
+    from modelsign.crypto.keys import FINGERPRINT_HEX_CHARS
+
+    try:
+        raw_key = base64.b64decode(sig.public_key)
+        expected_fp = "ed25519:" + hashlib.sha256(raw_key).hexdigest()[:FINGERPRINT_HEX_CHARS]
+        if sig.key_fingerprint != expected_fp:
+            raise ValueError(
+                f"fingerprint mismatch: sig says {sig.key_fingerprint}, "
+                f"computed {expected_fp} from embedded public key"
+            )
+    except Exception as e:
+        if "fingerprint mismatch" in str(e):
+            raise
+        raise ValueError(f"fingerprint validation failed: {e}")

modelsign-1.0.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: modelsign
+Version: 1.0.0
+Summary: Sign AI models with identity. Verify anywhere.
+Author-email: QJ <qj@constantone.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/ConstantQJ/modelsign
+Project-URL: Issues, https://github.com/ConstantQJ/modelsign/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41.0
+Requires-Dist: click>=8.0
+Requires-Dist: rfc8785>=0.1.2
+Provides-Extra: middleware
+Requires-Dist: fastapi>=0.100; extra == "middleware"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# modelsign
+
+[![CI](https://github.com/QuantQJ/modelsign/actions/workflows/ci.yml/badge.svg)](https://github.com/QuantQJ/modelsign/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+Sign AI models with identity. Verify anywhere.
+
+`modelsign` cryptographically binds model files to a signed identity card -- who made this model, what it's based on, what it claims to be. Ed25519 signatures, zero ML dependencies, works with any model format.
+
+## Install
+
+```bash
+pip install modelsign
+```
+
+## Quick Start
+
+```bash
+# Generate your signing key
+modelsign keygen
+
+# Sign a model with a name
+modelsign sign model.safetensors --name "My-Llama-8B-v1"
+
+# Verify it
+modelsign verify model.safetensors
+
+# Inspect the identity card
+modelsign inspect model.safetensors.sig
+```
+
+## Rich Identity Cards
+
+Sign with full provenance:
+
+```bash
+# Create an identity card
+cat > card.json << 'EOF'
+{
+  "name": "Llama-3.1-8B-Chat-QJ",
+  "architecture": "LlamaForCausalLM",
+  "base_model": "meta-llama/Llama-3.1-8B-Instruct",
+  "version": "1.0.0",
+  "creator": "ConstantQJ",
+  "license": "Llama 3.1 Community",
+  "intended_use": "Chat assistant",
+  "training": {
+    "dataset": "custom-chat-v2",
+    "epochs": 3,
+    "hardware": "DGX Spark GB10"
+  },
+  "eval_metrics": {
+    "mmlu": 0.68,
+    "humaneval": 0.53
+  }
+}
+EOF
+
+modelsign sign model.safetensors --identity card.json
+```
+
+## Python SDK
+
+```python
+from modelsign import (
+    ModelCard, validate_card, canonical_json,
+    generate_keypair, load_private_key, load_public_key,
+    sign_bytes, build_file_message, verify_bytes,
+    hash_file, SigFile, write_sig, read_sig,
+)
+```
+
+## What It Protects Against
+
+- Post-signing **tampering** of model weights
+- **Substitution** of one model for another
+- **Metadata swap** (changing identity claims invalidates signature)
+
+## What It Does NOT Cover
+
+- Key compromise (your key, your responsibility)
+- Model safety, fairness, or legal compliance
+- Cryptographic timestamping (timestamps are metadata, not proofs)
+
+## How It Compares
+
+| | modelsign | OpenSSF Model Signing (OMS) |
+|---|---|---|
+| **Focus** | Simple signing + rich identity | Supply-chain integrity via Sigstore |
+| **Identity card** | Embedded (architecture, training, eval metrics) | Minimal (being expanded) |
+| **Setup** | `pip install modelsign` | Sigstore toolchain + transparency log |
+| **Signing** | Offline, Ed25519, one command | Keyless via OIDC + Rekor transparency |
+| **Best for** | Individual fine-tunes, HF uploads, quick sharing | Enterprise supply-chain, NGC publishing |
+| **Network required** | No | Yes (Sigstore/Rekor) |
+
+modelsign and OMS are **complementary**. Use modelsign for fast, offline, identity-rich signing. Use OMS when you need transparency logs and keyless verification at enterprise scale.
+
+## Identity Card Schema
+
+| Field | Required | Description |
+|---|---|---|
+| `name` | Yes | Model name |
+| `architecture` | No | Model class (e.g., `LlamaForCausalLM`) |
+| `base_model` | No | Parent model name/path |
+| `parent_signature` | No | Hash of parent's `.sig` (provenance chain) |
+| `version` | No | Semantic version |
+| `creator` | No | Person or organization |
+| `license` | No | SPDX identifier or name |
+| `intended_use` | No | What the model is for |
+| `restrictions` | No | What it should NOT be used for |
+| `training` | No | `{dataset, dataset_hash, epochs, hardware}` |
+| `quantization` | No | Method (e.g., `GPTQ-4bit`) |
+| `eval_metrics` | No | Benchmark results (`{mmlu: 0.68}`) |
+| `extra` | No | Any additional metadata |
+
+## License
+
+MIT — QJ / ConstantOne (CIP1 LLC)

modelsign-1.0.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+modelsign/__init__.py,sha256=jSvBH6lBMV7k-hAXd29D-fpQWWdJKIuboHN6PW5GzKg,929
+modelsign/cli.py,sha256=VlOMelyokIPABGS56mRqCsrZxdykn1QUGl_yLrHK9YA,14109
+modelsign/sig.py,sha256=KZadRhHfZGPPwM8KOka3xkJVshYIBFCzWGw7DyRudT8,3502
+modelsign/crypto/__init__.py,sha256=adsLupeY9RyFE1S4bP6G31YIibr6J_9HZGCOMh2V6yI,562
+modelsign/crypto/keys.py,sha256=xCIGI7j0MRSkWPjNThdN1XJTMmwKJqkBS-kCnb9ZECM,3646
+modelsign/crypto/sign.py,sha256=BAFLYGaes0r7tyxL7P4Gt98STiJ6xKTlT1t3SRfT4z8,1069
+modelsign/crypto/verify.py,sha256=kED1WtLgmC9YYgexzx_Hvsiy0ELo7qL7RVV49ktG3P0,468
+modelsign/formats/__init__.py,sha256=rFtQInPdEPs1cmga42PAPaeZMuxZgw09TteqWQgIuLU,194
+modelsign/formats/directory.py,sha256=D0NEq9aYYPKZkLP7Hl00whprhYHHIEuiuPxRYFgAcyg,1089
+modelsign/formats/single.py,sha256=oC5rbxkSQ_tfeoo4nZxajJjPPxK-2XYwC-HT17Hxj0U,653
+modelsign/identity/__init__.py,sha256=c-4fAeDgkU6dJ5MttNbFNvTuvbP5EmJ1MZRJLV7mNc4,224
+modelsign/identity/canonical.py,sha256=RmIHdMQvlRji4W3WPlUA54NUF4jZHSbVwYvwAfe2Giw,592
+modelsign/identity/card.py,sha256=LaqhiFgjGlkk9_qxezP2AaRxhYtwmvQ-PYgpI81mBPg,2517
+modelsign/middleware/__init__.py,sha256=XD3Byets2Vy9T-n7VMLmC5M8tZgviCMptlryy-qsS6g,150
+modelsign/middleware/response.py,sha256=Qev4HfKschg3FUuP06TBAAQ6NOzcvoocxRmlN1Awt6I,1520
+modelsign-1.0.0.dist-info/licenses/LICENSE,sha256=-PMOmGZ5tmf1McGSjuTS9uyjotvzAnYdFPpj4dJjUA0,1084
+modelsign-1.0.0.dist-info/METADATA,sha256=5mG51Dl3xV39qbyDReRTH4juDpoopxLMMLDj59I5dvo,4762
+modelsign-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+modelsign-1.0.0.dist-info/entry_points.txt,sha256=MJy_HDR6EQgT4zIwbeysQ74LoYeoHeX2WJYJRlPuhIU,49
+modelsign-1.0.0.dist-info/top_level.txt,sha256=9QzBz3DtzpjLVlf4Af6izqC11Fgu-b5GCjvz5jrJrUQ,10
+modelsign-1.0.0.dist-info/RECORD,,

modelsign-1.0.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
+

modelsign-1.0.0.dist-info/entry_points.txt

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

modelsign-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QJ / ConstantOne (CIP1 LLC)
+
+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.

modelsign-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+modelsign