feat(security): add deepfake_guard — air-gapped media & document authenticity guard (#48)

[rosspeili]

Description

Implements security/deepfake_guard (v0.1.0), an air-gapped, zero-cloud forensic engine protecting autonomous agents and KYC pipelines against synthetic media, digital tampering, and forged identity documents without external API calls or biometric data leakage.

Key Capabilities

1. ICAO 9303 Check Digit Validation: Computes cyclic (7, 3, 1) check digits across TD1 (ID cards/residence permits), TD2, and TD3 (passports) with composite verification and expiration auditing.
2. Deterministic Forensic Signals: Error Level Analysis (ELA) JPEG compression hotspots, high-pass Laplacian noise residual variance with Median Absolute Deviation (MAD), and 16×16 spatial copy-move cloning detection.
3. Synthetic Origin & Provenance: Parses C2PA JUMBF manifests, Adobe Content Credentials, generative AI tags (trainedAlgorithmicMedia, Midjourney, ComfyUI, DALL-E), and diffusion radial power spectrum slope decay.
4. Recapture & Geometry: 2D FFT moiré screen-recapture detection (screens photographed during KYC) and ISO 7810 ID-1 aspect ratio verification.
5. Flexible Entry Points: Accepts local file paths (image_path), in-memory base64 (image_base64), SSRF-guarded URLs (url), or raw MRZ text (mrz_string).

Acceptance Criteria Mapping

• ICAO 9303 & ISO 7810: document.py, test_skill.py
• Forensic Signal Processing: forensics.py, test_deepfake_guard_simulations.py
• C2PA & Provenance: provenance.py
• Chaining & Demos: examples/deepfake_guard_demo.py, examples/kyc_authenticity_chain_demo.py, docs/usage/skill_chaining.md
• Catalog & Extras: docs/skills/security/deepfake_guard.md, pyproject.toml

Type of Change

• New Skill — new registry bundle under skills/
• Skill Upgrade — changes to an existing skill under skills/
• Bug Fix — incorrect runtime or framework behavior
• Documentation — docs, README, CONTRIBUTING only
• Framework Feature — skillware/core/ loader, env, adapters
• CLI — skillware/cli.py, docs/usage/cli.md
• Examples — examples/*.py, agent loops, examples/README.md
• Packaging — PyPI wheel, pyproject.toml, MANIFEST.in
• RFC / meta — templates, labels, CI, or large design doc

Checklist (all PRs)

• Linked GitHub issue (Fixes #48)
• Scope matches the issue — no unrelated refactors
• Contribution complies with Legal notice and code ownership (original work, MIT license grant, no malicious logic)
• python -m black --check ., flake8, and ruff check . pass locally (or CI-equivalent subset)
• pytest skills/ and pytest tests/ pass locally when relevant
• CHANGELOG.md updated under [Unreleased] when user-visible behavior changes
• examples/README.md updated if this PR adds, renames, or removes a runnable script
• Ran pytest tests/test_registry_docs.py when skills, examples index, or agent-loops matrix changed
• Ran pytest tests/test_skill_docs.py when catalog Usage Examples or provider snippets changed

New or updated skill

Bundle and metadata

• Skill at skills/security/deepfake_guard/
• manifest.yaml: name (security/deepfake_guard), version, description, parameters, constitution, real issuer
• Optional: short_description, issuer.github, issuer.org, requirements

Effect, Directive, Assurance

• Deterministic skill.py (Effect; no ad-hoc LLM-generated execution paths)
• instructions.md (Directive) explains when and how to use the skill
• card.json (Presentation) issuer matches manifest when present
• test_skill.py (Assurance) covers execution and schema expectations
• SkillLoader.load_skill("security/deepfake_guard") succeeds

Documentation and catalog

• docs/skills/security/deepfake_guard.md, category hub row, row in docs/skills/README.md, and docs/sitemap.md
• Usage Examples for Gemini, Claude, OpenAI, DeepSeek, Ollama per skill usage template

Constitution and safety (skills only)

• Air-Gapped Privacy: Strict offline local execution; zero outbound telemetry, no third-party biometric cloud API calls, and no data harvesting.
• SSRF Protection: Optional URL fetching enforces strict network guards against loopback, link-local, private RFC 1918 subnets, and cloud instance metadata services (AWS/GCP/Azure).
• Forensic Boundaries: Outputs deterministic risk signals, anomaly tags, and explicit limitations rather than courtroom or legal certitude.

Related Issues

Fixes #48

[rosspeili]

Pushed some follow ups addressing the gh's advanced security / CodeQL bot feedback (py/clear-text-logging-sensitive-data).

While the values printed were purely synthetic mock data for offline demonstrations (no real PII involved), CodeQL’s taint analysis flagged printing dictionary keys named after document/identity fields directly to stdout.

Patched both examples/deepfake_guard_demo.py and examples/kyc_authenticity_chain_demo.py to keep all parsed applicant and document fields strictly in-memory while reporting validation status and field counts to the console. This satisfies CodeQL's logger taint checks without altering demo functionality or smoke test coverage.