modmanifest 0.1.0__tar.gz

modmanifest-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

modmanifest-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- `inspect`, `validate` and `audit-ai` commands with stable JSON output (schema version 1).
+- Archive and folder safety checks with configurable limits.
+- The Sims 4: DBPF 2.1 structure and `.ts4script` archive checks.
+- inZOI: candidate-package manifest inspection and observation-based checks.
+- AI metadata audit: manifests, PNG text chunks, XMP, EXIF; C2PA detection only.

modmanifest-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+1. Fork, branch, and keep changes focused.
+2. `pip install -e ".[dev]"`
+3. `ruff check . && ruff format --check . && pytest` must pass.
+
+Guidelines:
+
+- Tests use synthetic fixtures built in code. Never commit real mod content.
+- Every emitted diagnostic code must be registered in `src/modmanifest/codes.py` with a
+  basis. Keep observed conventions separate from verified format rules.
+- The tool is read-only: no extraction, execution, network access or file modification.
+- Do not guess unknown formats or checksum algorithms; report `NOT CHECKED`.

modmanifest-0.1.0/LICENSE

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

modmanifest-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: modmanifest
+Version: 0.1.0
+Summary: Read-only inspection, validation and metadata auditing for game mod packages (The Sims 4, inZOI).
+Project-URL: Homepage, https://github.com/CyberStudiosTM/ModManifest
+Project-URL: Issues, https://github.com/CyberStudiosTM/ModManifest/issues
+Project-URL: Changelog, https://github.com/CyberStudiosTM/ModManifest/blob/main/CHANGELOG.md
+Author: CyberStudios
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audit,cli,inzoi,metadata,mods,sims4
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ModManifest
+
+Read-only inspection, validation and metadata auditing for game mod packages.
+Supports **The Sims 4** and **inZOI**. Part of [CyberStudios](https://github.com/CyberStudiosTM).
+
+ModManifest never extracts, executes, modifies or uploads anything. It reports what it can
+verify, what it only observed, and what it did not check.
+
+## Install
+
+```powershell
+pip install modmanifest
+```
+
+Requires Python 3.11+. From source: `pip install .`
+
+## Usage
+
+```text
+modmanifest inspect PATH [--json]
+modmanifest validate PATH --game sims4|inzoi [--json]
+modmanifest audit-ai PATH [--json]
+modmanifest --version
+```
+
+`PATH` is a folder, `.zip`, `.ts4script` or `.package`.
+
+| Command | Runs |
+|---|---|
+| `inspect` | archive safety, game recognition and validation, AI metadata audit |
+| `validate` | archive safety and the selected game's validation |
+| `audit-ai` | archive safety and the AI metadata audit |
+
+Options: `--json`, `--verbose`, `--timeout`, `--max-entries`, `--max-total-mb`, `--max-entry-mb`.
+
+### Statuses
+
+`PASS`, `WARNING`, `ERROR`, `UNSUPPORTED`, `NOT CHECKED` (`NOT_CHECKED` in JSON).
+Every finding carries a stable code (`MM-ARC-*`, `MM-SCN-*`, `MM-S4-*`, `MM-INZ-*`) and a
+basis: `format-rule`, `observed-convention`, `safety-limit` or `scan-coverage`.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | scan complete, no `ERROR` findings |
+| 1 | one or more `ERROR` findings |
+| 2 | invalid arguments or missing path |
+| 3 | incomplete scan (limit, timeout, read failure), or `validate` recognized nothing |
+
+AI indicators never change the exit code.
+
+## Example
+
+```text
+$ modmanifest validate SampleMod --game inzoi
+ModManifest validate  SampleMod
+target: folder  scan: complete
+game selected: inzoi  recognized: inzoi
+Status       Code        Finding
+NOT_CHECKED  MM-INZ-015  no official inZOI package specification was used; ...
+NOT_CHECKED  MM-INZ-013  declared dependencies are reported as written; ...
+NOT_CHECKED  MM-INZ-017  game version metadata is reported as written; ...
+NOT_CHECKED  MM-INZ-009  checksum digests were not verified: the algorithm ...
+PASS 2  WARNING 0  ERROR 0  UNSUPPORTED 0  NOT_CHECKED 5
+```
+
+## Validation coverage
+
+### The Sims 4
+
+- `.package` (DBPF 2.1): signature, header, index bounds and size, resource ranges,
+  duplicate keys. Resource contents are **not** decoded.
+- `.ts4script`: opened as a ZIP, `.py`/`.pyc` entries listed, compiled-code header checked.
+  Script contents are **not** analyzed or executed.
+- No standard Sims 4 manifest is assumed, so dependencies and versions are not extracted.
+
+### inZOI
+
+A root `mod_manifest.json` marks a **candidate** mod, not a valid package. There is no
+official specification behind these checks.
+
+- JSON syntax and field types, compared with sample packages. Observed fields are never required.
+- Identity, author, version, description, declared dependencies and game-version metadata are
+  reported as written. Dependencies and compatibility are **not** verified.
+- `ProjectName` versus folder name is informational.
+- `FileChecksums`: shape, path safety and listed-file existence are checked. Digests are
+  **NOT CHECKED**: in sample packages the algorithm and path semantics could not be
+  established, and none is guessed. A matching digest would show consistency with the
+  manifest only, not that a mod is safe or authentic.
+- `.pak`, `.ucas`, `.utoc`: recognized as Unreal content containers and inventoried;
+  internals are not inspected. A lone `.ucas` or `.utoc` is reported as a warning.
+- Unrelated folders (mod-manager state, hosted content) are unrecognized, not invalid.
+  Point ModManifest at one mod folder at a time.
+
+### Archive and folder safety (all targets)
+
+Traversal and absolute paths, drive letters and alternate streams, backslashes, duplicates,
+case collisions, symlinks and special files, entry count, total and per-entry size,
+compression ratio, signature mismatch, encrypted entries (`UNSUPPORTED`), and nested
+archives (listed, not opened). Limits are configurable.
+
+## AI metadata audit
+
+Reports indicators found in metadata, in three categories: explicit declaration, tool
+reference, ambiguous indicator. Confidence refers to the interpretation of the metadata
+only.
+
+Supported sources: JSON, TOML, YAML and XML manifests; text and Markdown notes; PNG text
+chunks; XMP; EXIF `Software`/`ImageDescription`. C2PA is **detection only**: possible
+structures are reported, never parsed or signature-validated.
+
+When nothing is found, the result is:
+
+> No supported AI metadata indicators found.
+
+Metadata may be absent, incomplete or removed. That result is not evidence about how a
+package was made. Prompt text is never copied into reports. Name tables used for matching
+live in `src/modmanifest/metadata/ai_signatures.py` and are detection data only.
+
+## JSON output
+
+Stable schema, `schema_version: 1`. Top-level keys: `tool`, `version`, `command`, `target`,
+`game`, `scan`, `recognized_files`, `capabilities_exercised`, `package`, `findings`,
+`summary`, `unsupported`, `inspection_errors`, `ai_metadata`. The target is a base name,
+never an absolute path. Untrusted text has control and bidirectional characters escaped.
+
+## Limitations
+
+- Format checks reflect observed samples and public format knowledge, not vendor specs.
+- Only listed metadata containers are audited; scripts and binary game data are not.
+- 7z, RAR and other archive formats are listed, not opened.
+- Package validity here does not mean a mod is safe, compatible or working in game.
+
+## Development
+
+```powershell
+pip install -e ".[dev]"
+ruff check . ; ruff format --check .
+pytest
+```
+
+## License
+
+MIT. Copyright (c) CyberStudios.

modmanifest-0.1.0/README.md

@@ -0,0 +1,145 @@
+# ModManifest
+
+Read-only inspection, validation and metadata auditing for game mod packages.
+Supports **The Sims 4** and **inZOI**. Part of [CyberStudios](https://github.com/CyberStudiosTM).
+
+ModManifest never extracts, executes, modifies or uploads anything. It reports what it can
+verify, what it only observed, and what it did not check.
+
+## Install
+
+```powershell
+pip install modmanifest
+```
+
+Requires Python 3.11+. From source: `pip install .`
+
+## Usage
+
+```text
+modmanifest inspect PATH [--json]
+modmanifest validate PATH --game sims4|inzoi [--json]
+modmanifest audit-ai PATH [--json]
+modmanifest --version
+```
+
+`PATH` is a folder, `.zip`, `.ts4script` or `.package`.
+
+| Command | Runs |
+|---|---|
+| `inspect` | archive safety, game recognition and validation, AI metadata audit |
+| `validate` | archive safety and the selected game's validation |
+| `audit-ai` | archive safety and the AI metadata audit |
+
+Options: `--json`, `--verbose`, `--timeout`, `--max-entries`, `--max-total-mb`, `--max-entry-mb`.
+
+### Statuses
+
+`PASS`, `WARNING`, `ERROR`, `UNSUPPORTED`, `NOT CHECKED` (`NOT_CHECKED` in JSON).
+Every finding carries a stable code (`MM-ARC-*`, `MM-SCN-*`, `MM-S4-*`, `MM-INZ-*`) and a
+basis: `format-rule`, `observed-convention`, `safety-limit` or `scan-coverage`.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | scan complete, no `ERROR` findings |
+| 1 | one or more `ERROR` findings |
+| 2 | invalid arguments or missing path |
+| 3 | incomplete scan (limit, timeout, read failure), or `validate` recognized nothing |
+
+AI indicators never change the exit code.
+
+## Example
+
+```text
+$ modmanifest validate SampleMod --game inzoi
+ModManifest validate  SampleMod
+target: folder  scan: complete
+game selected: inzoi  recognized: inzoi
+Status       Code        Finding
+NOT_CHECKED  MM-INZ-015  no official inZOI package specification was used; ...
+NOT_CHECKED  MM-INZ-013  declared dependencies are reported as written; ...
+NOT_CHECKED  MM-INZ-017  game version metadata is reported as written; ...
+NOT_CHECKED  MM-INZ-009  checksum digests were not verified: the algorithm ...
+PASS 2  WARNING 0  ERROR 0  UNSUPPORTED 0  NOT_CHECKED 5
+```
+
+## Validation coverage
+
+### The Sims 4
+
+- `.package` (DBPF 2.1): signature, header, index bounds and size, resource ranges,
+  duplicate keys. Resource contents are **not** decoded.
+- `.ts4script`: opened as a ZIP, `.py`/`.pyc` entries listed, compiled-code header checked.
+  Script contents are **not** analyzed or executed.
+- No standard Sims 4 manifest is assumed, so dependencies and versions are not extracted.
+
+### inZOI
+
+A root `mod_manifest.json` marks a **candidate** mod, not a valid package. There is no
+official specification behind these checks.
+
+- JSON syntax and field types, compared with sample packages. Observed fields are never required.
+- Identity, author, version, description, declared dependencies and game-version metadata are
+  reported as written. Dependencies and compatibility are **not** verified.
+- `ProjectName` versus folder name is informational.
+- `FileChecksums`: shape, path safety and listed-file existence are checked. Digests are
+  **NOT CHECKED**: in sample packages the algorithm and path semantics could not be
+  established, and none is guessed. A matching digest would show consistency with the
+  manifest only, not that a mod is safe or authentic.
+- `.pak`, `.ucas`, `.utoc`: recognized as Unreal content containers and inventoried;
+  internals are not inspected. A lone `.ucas` or `.utoc` is reported as a warning.
+- Unrelated folders (mod-manager state, hosted content) are unrecognized, not invalid.
+  Point ModManifest at one mod folder at a time.
+
+### Archive and folder safety (all targets)
+
+Traversal and absolute paths, drive letters and alternate streams, backslashes, duplicates,
+case collisions, symlinks and special files, entry count, total and per-entry size,
+compression ratio, signature mismatch, encrypted entries (`UNSUPPORTED`), and nested
+archives (listed, not opened). Limits are configurable.
+
+## AI metadata audit
+
+Reports indicators found in metadata, in three categories: explicit declaration, tool
+reference, ambiguous indicator. Confidence refers to the interpretation of the metadata
+only.
+
+Supported sources: JSON, TOML, YAML and XML manifests; text and Markdown notes; PNG text
+chunks; XMP; EXIF `Software`/`ImageDescription`. C2PA is **detection only**: possible
+structures are reported, never parsed or signature-validated.
+
+When nothing is found, the result is:
+
+> No supported AI metadata indicators found.
+
+Metadata may be absent, incomplete or removed. That result is not evidence about how a
+package was made. Prompt text is never copied into reports. Name tables used for matching
+live in `src/modmanifest/metadata/ai_signatures.py` and are detection data only.
+
+## JSON output
+
+Stable schema, `schema_version: 1`. Top-level keys: `tool`, `version`, `command`, `target`,
+`game`, `scan`, `recognized_files`, `capabilities_exercised`, `package`, `findings`,
+`summary`, `unsupported`, `inspection_errors`, `ai_metadata`. The target is a base name,
+never an absolute path. Untrusted text has control and bidirectional characters escaped.
+
+## Limitations
+
+- Format checks reflect observed samples and public format knowledge, not vendor specs.
+- Only listed metadata containers are audited; scripts and binary game data are not.
+- 7z, RAR and other archive formats are listed, not opened.
+- Package validity here does not mean a mod is safe, compatible or working in game.
+
+## Development
+
+```powershell
+pip install -e ".[dev]"
+ruff check . ; ruff format --check .
+pytest
+```
+
+## License
+
+MIT. Copyright (c) CyberStudios.

modmanifest-0.1.0/SECURITY.md

@@ -0,0 +1,16 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Use GitHub private vulnerability reporting on this repository (Security tab, "Report a
+vulnerability"). Do not open a public issue for security problems.
+
+## Scope
+
+ModManifest parses untrusted archives and files. In scope: crashes, resource exhaustion,
+path handling, or any behavior that writes, executes or transmits data. Out of scope:
+whether a mod is safe to install; ModManifest makes no such claim.
+
+## Supported versions
+
+The latest release.

modmanifest-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "modmanifest"
+dynamic = ["version"]
+description = "Read-only inspection, validation and metadata auditing for game mod packages (The Sims 4, inZOI)."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "CyberStudios" }]
+keywords = ["mods", "sims4", "inzoi", "audit", "metadata", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.7",
+    "PyYAML>=6.0",
+    "defusedxml>=0.7.1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[project.scripts]
+modmanifest = "modmanifest.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/CyberStudiosTM/ModManifest"
+Issues = "https://github.com/CyberStudiosTM/ModManifest/issues"
+Changelog = "https://github.com/CyberStudiosTM/ModManifest/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/modmanifest/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/modmanifest"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "CHANGELOG.md", "SECURITY.md", "CONTRIBUTING.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "ANN", "PT"]
+ignore = ["ANN401"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["ANN", "PT018", "E501"]

modmanifest-0.1.0/src/modmanifest/__init__.py

@@ -0,0 +1,4 @@
+"""ModManifest: read-only inspection, validation and metadata auditing for mod packages."""
+
+__version__ = "0.1.0"
+SCHEMA_VERSION = 1

modmanifest-0.1.0/src/modmanifest/__main__.py

@@ -0,0 +1,4 @@
+from modmanifest.cli import main
+
+if __name__ == "__main__":
+    main()

modmanifest-0.1.0/src/modmanifest/archive/__init__.py

@@ -0,0 +1 @@
+"""Package marker."""

modmanifest-0.1.0/src/modmanifest/archive/limits.py

@@ -0,0 +1,36 @@
+"""Configurable scan limits and the scan deadline."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+MB = 1024 * 1024
+
+
+@dataclass(frozen=True, slots=True)
+class ScanLimits:
+    max_entries: int = 20_000
+    max_archive_bytes: int = 1024 * MB
+    max_total_bytes: int = 500 * MB
+    max_entry_bytes: int = 50 * MB
+    max_ratio: float = 100.0
+    max_metadata_bytes: int = 1 * MB
+    max_image_bytes: int = 20 * MB
+    timeout_s: float = 30.0
+    # Ratio warnings are skipped for tiny entries, which compress extremely well legitimately.
+    ratio_min_bytes: int = 64 * 1024
+
+
+class ScanTimeout(Exception):
+    """Raised when the scan deadline passes."""
+
+
+class Deadline:
+    def __init__(self, seconds: float) -> None:
+        self._end = time.monotonic() + seconds
+        self.seconds = seconds
+
+    def check(self) -> None:
+        if time.monotonic() > self._end:
+            raise ScanTimeout(f"scan exceeded the {self.seconds:g}s time limit")

modmanifest-0.1.0/src/modmanifest/archive/signatures.py

@@ -0,0 +1,47 @@
+"""Structural file-signature checks for extensions where a signature is well defined."""
+
+from __future__ import annotations
+
+from modmanifest.context import ScanContext
+from modmanifest.models import Finding, Status
+
+_ZIP = (b"PK\x03\x04", b"PK\x05\x06")
+SIGNATURES: dict[str, tuple[bytes, ...]] = {
+    ".png": (b"\x89PNG\r\n\x1a\n",),
+    ".jpg": (b"\xff\xd8\xff",),
+    ".jpeg": (b"\xff\xd8\xff",),
+    ".zip": _ZIP,
+    ".ts4script": _ZIP,
+}
+# .package signatures are verified by the Sims 4 DBPF parser, not here.
+
+
+def check_signatures(ctx: ScanContext) -> None:
+    checked = 0
+    for entry in ctx.source.files():
+        ext = "." + entry.path.rsplit(".", 1)[-1].lower() if "." in entry.path else ""
+        sigs = SIGNATURES.get(ext)
+        is_webp = ext == ".webp"
+        if sigs is None and not is_webp:
+            continue
+        ctx.deadline.check()
+        head = ctx.head(entry.path, 12)
+        if head is None:
+            continue
+        checked += 1
+        ok = (
+            head[:4] == b"RIFF" and head[8:12] == b"WEBP"
+            if is_webp
+            else any(head.startswith(s) for s in sigs or ())
+        )
+        if not ok:
+            ctx.report.add(
+                Finding(
+                    "MM-ARC-013",
+                    Status.WARNING,
+                    f"extension '{ext}' does not match the file signature",
+                    source=entry.path,
+                )
+            )
+    if checked:
+        ctx.report.capability("archive.signature_check")