docs(security): document 5-pillar user trust model and sha-256 verification (closes #193)

.github/SECURITY.md

@@ -1,17 +1,61 @@
-# Security Policy
+# Security Policy & User Trust Model
 
 ## Supported Versions
 
 Only the latest release line of **SkillOps (`skillops-cli`)** receives active security updates and CodeQL SAST patches:
 
 | Version | Supported | Notes |
 | :--- | :---: | :--- |
-| **`1.3.x`** | ✅ | 28 AI IDEs & CLIs Transpiler, Lip Gloss TrueColor TUI, SHA-256 Lockfile & Active LTS |
+| **`1.3.x`** | ✅ | 28 AI IDEs & CLIs Transpiler, AST Security Scanner (`INV-SKILL-06`), Lip Gloss TUI, SHA-256 Lockfile & Active LTS |
 | **`1.2.x`** | ⚠️ | Critical security fixes only |
 | **`< 1.2.0`** | ❌ | End of life — upgrade via `npx skillops-cli@latest` |
 
 ---
 
+## 5-Pillar Defense-in-Depth Architecture (Why SkillOps Is Safe to Run)
+
+Because AI coding Skills (`SKILL.md`), Subagents (`SUBAGENT.md`), and bundled helper scripts (`scripts/*.py`) run inside developer workspaces, **SkillOps** combines automated static analysis with mandatory human code review across 5 independent security pillars:
+
+### Pillar 1 — 100% Curated, Maintainer-Reviewed Registry (`CODEOWNERS` Gate)
+- **No Unverified Remote Fetching:** `skillops-cli` never downloads arbitrary third-party URLs or unreviewed Git repositories at runtime. It installs exclusively from the curated, version-pinned `catalog/` bundled inside the audited release.
+- **Mandatory Code Owner Approval:** Every Pull Request targeting `main` is governed by GitHub Ruleset protection (`require_code_owner_review: true` via [`.github/CODEOWNERS`](./CODEOWNERS)). No community PR can be merged without explicit manual line-by-line review from `@OdevMatheus`.
+- **Automatic Stale Review Dismissal:** Pushing any new commit to an open PR automatically invalidates prior approvals (`dismiss_stale_reviews_on_push: true`), preventing post-approval commit tampering.
+
+### Pillar 2 — Deterministic AST Security Scanner & CodeQL SAST (`INV-SKILL-06`)
+Every catalog Skill and script is audited on every PR and push by [`src/auditor/security.ts`](../src/auditor/security.ts), [`.github/workflows/ai-ci.yml`](./workflows/ai-ci.yml), and **GitHub CodeQL SAST** ([`.github/workflows/codeql.yml`](./workflows/codeql.yml)):
+- **Zero Outbound Network Exfiltration (`forbidden-network-import`):** Blocks outbound network clients (`urllib.request`, `urllib2`, `urllib3`, `http.client`, `httplib`, `socket`, `socketserver`, `requests`, `httpx`, `aiohttp`, `ftplib`, `smtplib`, `telnetlib`, `xmlrpc.client`, `paramiko`, `websocket`, `websockets`) and remote shell pipes (`curl | sh`, `wget | bash`, `Invoke-WebRequest | iex`). Safe offline URL parsers (`urllib.parse`) and local preview servers (`http.server`, `webbrowser`) remain allowed.
+- **Zero Dynamic Code Execution & Deserialization (`forbidden-dynamic-exec`):** Blocks `eval()`, `exec()`, `__import__()`, `Function()`, `pickle`, `cPickle`, `marshal`, `shelve`, `ctypes`, `cffi`, and base64-decoded shell execution (`base64 -d | sh`).
+- **Zero Unsafe Shell Execution (`forbidden-shell-execution`):** Blocks `os.system()`, `os.popen()`, `os.spawn*()`, `os.exec*()`, `pty`, reverse-shell primitives (`/dev/tcp/`, `nc -e`), and `subprocess` calls with `shell=True`.
+
+### Pillar 3 — Anti-Trojan Unicode, Symlink & Boundary Containment Guards
+- **Anti-Trojan Source & Invisible Prompt Injection (`forbidden-trojan-unicode`):** Blocks CVE-2021-42574 bidirectional Unicode control characters (`U+202A..U+202E`, `U+2066..U+2069`, `U+200E`, `U+200F`, `U+061C`), LLM invisible Unicode Tag smuggling (`U+E0000..U+E007F`), and zero-width script identifier spoofing (`U+200B`, `U+200C`, `U+2060..U+2064`).
+- **Zero Symlinks & Opaque Binaries (`forbidden-symlink`, `forbidden-binary-file`):** Rejects symbolic links and compiled binary/archive payloads (`.exe`, `.dll`, `.so`, `.dylib`, `.bin`, `.wasm`, `.pyc`, `.zip`, `.tar.gz`, `.7z`, `.jar`) that cannot be inspected in GitHub PR diffs.
+- **Strict Repository Boundary Containment (`resolveSafeRepoTargetPath`):** Every planned file write or removal is verified via `path.resolve` containment in [`src/sync/adapters.ts`](../src/sync/adapters.ts) so no path can escape the target repository or overwrite a symbolic link.
+
+### Pillar 4 — Cryptographic NPM Provenance (`--provenance`)
+- Every official release of `skillops-cli` is built and published on GitHub-hosted runners via [`.github/workflows/release-publish.yml`](./workflows/release-publish.yml) using `npm publish --provenance`, generating a verifiable Sigstore attestation linking the npm tarball to the exact commit and workflow run.
+
+### Pillar 5 — Local Inspection (`--dry-run`) & SHA-256 Lockfile (`.skillops-lock.json`)
+- **Pre-Install Inspection:** Run `npx skillops-cli add <name> --dry-run` to inspect every target path before a single byte is written to disk.
+- **Cryptographic Drift Protection:** `.skillops-lock.json` stores the SHA-256 hash of every installed file. `skillops add` and `skillops remove` refuse to overwrite or delete locally modified files unless `--force` is explicitly provided.
+
+---
+
+## How Users Can Verify Package & Catalog Integrity Locally
+
+```bash
+# 1. Verify npm package Sigstore provenance signatures
+npm audit signatures
+
+# 2. Preview planned file paths without writing to disk
+npx skillops-cli@latest add mcp-architect --dry-run
+
+# 3. Run the deterministic catalog security scanner on a local clone
+node --input-type=module -e 'import { auditCatalogSecurity } from "./dist/index.js"; console.log(auditCatalogSecurity("./catalog"));'
+```
+
+---
+
 ## Reporting a Vulnerability
 
 **Please do NOT open a public GitHub issue for security vulnerabilities.**
@@ -24,12 +68,3 @@ If you discover a security vulnerability in **SkillOps**, please report it priva
 4. Suggested mitigation or fix (if available).
 
 **Response SLA:** Security reports are acknowledged within **48 hours** and triaged with a remediation plan or advisory within **7 days**.
-
----
-
-## Scope & Security Principles
-
-- **Privacy & Local Data Isolation:** Personal user data and local environment variables (`.env*`) must never be committed to the repository.
-- **Deterministic & Safe Skill Execution:** All executable skill scripts (`catalog/**/scripts/*`) must operate strictly in read-only analysis mode unless explicitly documented, and must never execute untrusted shell strings (`shell=True`).
-- **Prompt & Agent Safety:** AI agent instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `catalog/**/SKILL.md`, `catalog/subagents/**/SUBAGENT.md`) must never instruct agents to bypass security boundaries or expose credentials.
-- **Supply Chain & Static Analysis Hygiene:** GitHub Actions, TypeScript (`src/`), and Python (`catalog/**/scripts/*.py`) are continuously audited via **GitHub CodeQL SAST** ([`.github/workflows/codeql.yml`](./workflows/codeql.yml)), Dependabot, and `CODEOWNERS`.

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **5-Pillar User Trust Model & Security Documentation (`#193`):** Documented the 5-Pillar Supply-Chain Security & User Trust Architecture (`CODEOWNERS` curated registry, `INV-SKILL-06` AST + CodeQL SAST script gate, Anti-Trojan Unicode/boundary guards, Sigstore NPM `--provenance`, and `--dry-run` + `.skillops-lock.json` SHA-256 verification) in [`README.md`](./README.md) and [`.github/SECURITY.md`](./.github/SECURITY.md).
 - **`INV-SKILL-06` Security Invariant & Mandatory PR Security Review Checklist (`#192`):** Codified `INV-SKILL-06` (*Zero-Network, Trojan-Free & Boundary-Safe Security Contract*) in [`SKILL_CONTRACT.md`](./SKILL_CONTRACT.md) and added a mandatory supply-chain security review checklist in [`.github/PULL_REQUEST_TEMPLATE.md`](./.github/PULL_REQUEST_TEMPLATE.md) and [`CONTRIBUTING.md`](./CONTRIBUTING.md).
 - **Anti-Trojan Unicode, Symlink, Binary & Path Containment Guards (`#191`):** Extended [`src/auditor/security.ts`](./src/auditor/security.ts), [`src/auditor/parser.ts`](./src/auditor/parser.ts), and [`src/sync/adapters.ts`](./src/sync/adapters.ts) (`resolveSafeRepoTargetPath`) to block Trojan-Source (CVE-2021-42574) bidirectional control characters, LLM invisible Unicode Tag smuggling (`U+E0000..U+E007F`), zero-width script identifier spoofing, symbolic links, opaque compiled binary/archive payloads (`.exe`, `.dll`, `.so`, `.dylib`, `.bin`, `.wasm`, `.pyc`, `.zip`, `.tar.gz`), and repository boundary path traversal.
 - **Catalog Script AST & Lexical Security Scanner (`#190`):** Added [`src/auditor/security.ts`](./src/auditor/security.ts) (`auditSkillSecurity`, `auditCatalogSecurity`) and a Python `ast` security gate in [`.github/workflows/ai-ci.yml`](./.github/workflows/ai-ci.yml) to block outbound network modules (`urllib.request`, `http.client`, `socket`, `requests`, `curl | sh`), dynamic execution/deserialization (`eval`, `exec`, `__import__`, `pickle`, `marshal`, `ctypes`), and unsafe shell execution (`os.system`, `os.popen`, `shell=True`) in catalog Skill scripts with zero false positives on legitimate large skills.

README.md

@@ -4,7 +4,8 @@
 
 <p>
   <a href="https://www.npmjs.com/package/skillops-cli"><img src="https://img.shields.io/badge/npm-v1.3.10-dafa9c?style=flat-square&logo=npm&logoColor=0f0f0f&labelColor=0f0f0f" alt="npm version"></a>
-  <a href="https://github.com/OdevMatheus/SkillOps/actions/workflows/ai-ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/OdevMatheus/SkillOps/ai-ci.yml?branch=master&style=flat-square&logo=githubactions&logoColor=dafa9c&labelColor=0f0f0f&color=1a1a1a&label=CI" alt="CI"></a>
+  <a href="https://github.com/OdevMatheus/SkillOps/actions/workflows/ai-ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/OdevMatheus/SkillOps/ai-ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=dafa9c&labelColor=0f0f0f&color=1a1a1a&label=CI" alt="CI"></a>
+  <a href="https://github.com/OdevMatheus/SkillOps/actions/workflows/codeql.yml"><img src="https://img.shields.io/github/actions/workflow/status/OdevMatheus/SkillOps/codeql.yml?branch=main&style=flat-square&logo=github&logoColor=dafa9c&labelColor=0f0f0f&color=1a1a1a&label=CodeQL%20SAST" alt="CodeQL SAST"></a>
   <a href="#supported-ai-ides--clis-28"><img src="https://img.shields.io/badge/AI%20IDEs%20%26%20CLIs-28-dafa9c?style=flat-square&labelColor=0f0f0f" alt="28 AI IDEs & CLIs"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-ffffff?style=flat-square&labelColor=0f0f0f" alt="License: MIT"></a>
 </p>
@@ -119,6 +120,20 @@ Every generated file is tracked in `.skillops-lock.json` with a cryptographic di
 
 ---
 
+## Security & Trust Model (5-Pillar Defense-in-Depth)
+
+Installing AI Skills and executable helper scripts into your IDE requires strict supply-chain guarantees. **SkillOps** enforces a **5-Pillar Security Architecture** ([`.github/SECURITY.md`](./.github/SECURITY.md) & `INV-SKILL-06` in [`SKILL_CONTRACT.md`](./SKILL_CONTRACT.md)) so no unreviewed or malicious skill can enter the catalog:
+
+| Pillar | Guarantee | How It Is Enforced |
+| :--- | :--- | :--- |
+| **1. 100% Curated & Maintainer-Reviewed Catalog** | Zero arbitrary remote URL fetching; every Skill and Subagent is reviewed line-by-line by a human maintainer before merge. | Protected `main` ruleset + [`.github/CODEOWNERS`](./.github/CODEOWNERS) (`require_code_owner_review: true` & automatic stale-review dismissal on new commits). |
+| **2. Deterministic AST & CodeQL Script Gate (`INV-SKILL-06`)** | Bundled scripts run offline using the standard library—never exfiltrating data or executing arbitrary shell strings. | [`src/auditor/security.ts`](./src/auditor/security.ts) + [`.github/workflows/ai-ci.yml`](./.github/workflows/ai-ci.yml) + **GitHub CodeQL SAST** block outbound network clients (`urllib.request`, `http.client`, `socket`, `requests`, `curl \| sh`), `eval()`/`exec()`/`pickle`, and `os.system()`/`shell=True`. |
+| **3. Anti-Trojan Unicode & Boundary Guards** | Protects PR reviewers and LLMs from invisible prompt injection, binary droppers, and path traversal. | Blocks CVE-2021-42574 bidirectional Unicode (`U+202A..U+202E`), LLM invisible Unicode Tags (`U+E0000..U+E007F`), symlinks, opaque binaries/archives (`.exe`, `.dll`, `.so`, `.pyc`, `.zip`), and `..` path escapes (`resolveSafeRepoTargetPath`). |
+| **4. Cryptographic NPM Provenance** | Every published `skillops-cli` release is cryptographically linked to its exact GitHub commit and CI build. | Published via GitHub Actions with `npm publish --provenance` (verifiable via `npm audit signatures`). |
+| **5. Local `--dry-run` & SHA-256 Lockfile** | Preview every planned file before writing to disk and detect unauthorized local modifications. | `npx skillops-cli add <name> --dry-run` + cryptographic SHA-256 digests in `.skillops-lock.json`. |
+
+---
+
 ## Contributing (Two-Track Open Source)
 
 SkillOps uses a two-track contribution workflow so the community can add new **Skills** and **Subagents** with zero friction:
@@ -128,6 +143,7 @@ SkillOps uses a two-track contribution workflow so the community can add new **S
 | **Track A — Library (`catalog/`)** | New or improved **Skills (`SKILL.md`)** and **Subagents (`SUBAGENT.md`)** | **No — Direct PR** | Add your folder under `catalog/<track>/<slug>/` or `catalog/subagents/<slug>/` and open a PR directly |
 | **Track B — Core CLI (`src/`)** | CLI commands, TUI components, 28-IDE transpiler, or schemas | **Yes — Issue First** | Open an Issue to align scope before submitting a Pull Request |
 
+- 🛡️ [**Security Policy & Trust Model (`.github/SECURITY.md`)**](./.github/SECURITY.md)
 - 📖 [**Contribution Guide (`CONTRIBUTING.md`)**](./CONTRIBUTING.md)
 - 📜 [**Skill & Subagent Contract (`SKILL_CONTRACT.md`)**](./SKILL_CONTRACT.md)
 - ⚖️ Licensed under the [**MIT License**](./LICENSE) — Built by [**@OdevMatheus**](https://github.com/OdevMatheus)