docs: add SECURITY.md, CONTRIBUTING.md, VERIFY.md

AUDIT.md

@@ -166,7 +166,7 @@ Settings import/export is a local trust boundary (user-supplied JSON parsed by `
 | System clock trust for `packagedAt` | Operator responsibility; no independent time source available |
 | OP Stack/Linea envelope forgery by compromised RPC | Explicitly labeled as partial trust; cannot reach fully-verifiable |
 | Contract signatures (v=0) not verified offline | Require on-chain call; flagged as warning in verification report |
-| Beacon API responses not Zod-validated (generation only) | Malformed beacon data causes runtime errors during generation, not during verification. Verification uses the Rust Helios path which has its own SSZ validation. Fixing requires defining schemas for all beacon light-client API response shapes |
+| Beacon API responses not Zod-validated (generation only) | **Fixed** (PR #173): `FinalityUpdateSchema`, `HeaderResponseSchema`, and `BootstrapSchema` now validate all beacon API consumption sites. `fetchBeaconJson` returns `Promise<unknown>` instead of `Promise<any>`. |
 
 ### Open Issues
 

CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing to SafeLens
+
+## Development Setup
+
+Requires [Bun](https://bun.sh) (v1.3.9+) and [Rust](https://rustup.rs/) (1.93.1+).
+
+```bash
+bun install
+```
+
+## Project Structure
+
+| Path | Description |
+|------|-------------|
+| `packages/core` | Shared crypto verification library (TypeScript) |
+| `packages/cli` | CLI wrapper over core logic |
+| `apps/generator` | Next.js web app — creates evidence packages |
+| `apps/desktop` | Tauri + Vite desktop app — airgapped verification |
+
+## Running Locally
+
+```bash
+bun run dev          # generator at localhost:3000
+bun run dev:tauri    # desktop app (full Tauri shell)
+```
+
+## Testing
+
+```bash
+bun run test         # all unit tests (vitest)
+bun run type-check   # TypeScript type-check across all packages
+bun run rust:test    # Rust tests (desktop verifier)
+bun run rust:clippy  # Rust lints
+bun run verify:ci    # full CI parity check (lint + type-check + test + build)
+```
+
+Always run `bun run verify:ci` before submitting a PR. CI runs the same command.
+
+## Pull Request Expectations
+
+1. **One concern per PR.** Keep changes focused. A bug fix and a refactor are two PRs.
+2. **Tests required.** New logic needs tests. Bug fixes need a regression test.
+3. **CI must pass.** The `verify-ci` job runs lint, type-check, JS tests, Rust fmt/clippy/tests, and a full build.
+4. **Commit messages.** Use conventional commits: `fix(core):`, `feat(desktop):`, `refactor(core):`, `docs:`, `test:`.
+
+## Security Considerations
+
+SafeLens is a security tool. Changes to these areas require extra scrutiny:
+
+- **Verification path** (`packages/core/src/lib/verify/`, `packages/core/src/lib/proof/`, `apps/desktop/src-tauri/src/consensus.rs`): Any change to trust decisions, hash recomputation, or signature recovery.
+- **Zod schemas** (`packages/core/src/lib/types.ts`): Schema changes affect the trust boundary between evidence packages and the verifier.
+- **CSP / Tauri config** (`apps/desktop/src-tauri/tauri.conf.json`): The desktop app's airgap is enforced here. Changes are validated by `tests/airgap-config.test.ts`.
+- **Cryptographic dependencies** (`Cargo.toml`): Helios, alloy, revm. Pin updates need justification.
+
+## Architecture
+
+- [`TRUST_ASSUMPTIONS.md`](TRUST_ASSUMPTIONS.md) — full trust model
+- [`AUDIT.md`](AUDIT.md) — security architecture and attack surface
+- [`docs/`](docs/) — architecture contracts and runbooks

README.md

@@ -29,6 +29,12 @@ SafeLens generates and verifies evidence packages for Gnosis Safe multisig trans
 
 The desktop verifier ships with a CSP that restricts `connect-src` to Tauri IPC only (`ipc: http://ipc.localhost`) — no external network origins — and no shell-open capability. It cannot make network requests during verification. All crypto runs locally using bundled libraries. See [`TRUST_ASSUMPTIONS.md`](TRUST_ASSUMPTIONS.md) for the full model.
 
+## Project docs
+
+- Security policy: [`SECURITY.md`](SECURITY.md)
+- Contributing guidelines: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- Build verification: [`VERIFY.md`](VERIFY.md)
+
 ## Architecture and runbooks
 
 - Docs index: [`docs/README.md`](docs/README.md)

SECURITY.md

@@ -0,0 +1,53 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.4.x   | Yes       |
+| < 0.4   | No        |
+
+Only the latest release receives security fixes. Previous versions are not backported.
+
+## Reporting a Vulnerability
+
+**Do not open a public issue.**
+
+Use [GitHub Private Vulnerability Reporting](https://github.com/Th0rgal/SafeLens/security/advisories/new) to submit findings. This keeps details confidential until a fix is available.
+
+Include:
+
+- Description of the vulnerability
+- Steps to reproduce
+- Affected component (`packages/core`, `apps/desktop`, `apps/generator`, `packages/cli`)
+- Impact assessment (what can an attacker achieve?)
+
+## Response Timeline
+
+| Step | Target |
+|------|--------|
+| Acknowledgment | 48 hours |
+| Triage and severity assessment | 7 days |
+| Fix or mitigation | 30 days (critical: 14 days) |
+
+## Scope
+
+In scope:
+
+- Hash substitution or signature bypass in the verification path
+- CSP or airgap escapes in the desktop app
+- Zod schema bypasses that allow malformed evidence packages
+- BLS or MPT verification logic errors
+- Information leaks from the desktop verifier (network, filesystem)
+- Dependency vulnerabilities in the verification path
+
+Out of scope:
+
+- Bugs in third-party RPC providers or the Safe Transaction Service
+- Social engineering of multisig signers
+- Denial of service against the generator web app (hosted, not self-hosted)
+- Issues requiring physical access to the user's machine
+
+## Trust Model
+
+See [`TRUST_ASSUMPTIONS.md`](TRUST_ASSUMPTIONS.md) for the full trust model and [`AUDIT.md`](AUDIT.md) for the security architecture.

VERIFY.md

@@ -0,0 +1,83 @@
+# Verifying SafeLens Builds
+
+How to confirm that a released binary matches the source code.
+
+## Checksum Verification
+
+Every [GitHub release](https://github.com/Th0rgal/SafeLens/releases) includes a `SHA256SUMS.txt` file listing the SHA-256 hash of each artifact.
+
+After downloading a release binary:
+
+```bash
+# macOS / Linux
+sha256sum SafeLens_0.4.0_aarch64.dmg
+# Compare the output against the corresponding line in SHA256SUMS.txt
+
+# Windows (PowerShell)
+Get-FileHash SafeLens_0.4.0_x64-setup.exe -Algorithm SHA256
+```
+
+## Building from Source
+
+To reproduce a release build locally and compare against the published artifact:
+
+### Prerequisites
+
+- [Bun](https://bun.sh) v1.3.9+
+- [Rust](https://rustup.rs/) 1.93.1 (match the exact toolchain used in CI)
+- Platform-specific dependencies:
+  - **Linux**: `libwebkit2gtk-4.1-dev librsvg2-dev patchelf libssl-dev`
+  - **macOS**: Xcode Command Line Tools
+  - **Windows**: Visual Studio Build Tools (C++ workload), WebView2
+
+### Steps
+
+```bash
+# 1. Clone at the release tag
+git clone https://github.com/Th0rgal/SafeLens.git
+cd SafeLens
+git checkout v0.4.0  # replace with the release tag
+
+# 2. Install dependencies
+bun install --frozen-lockfile
+
+# 3. Run the full CI check (optional but recommended)
+bun run verify:ci
+
+# 4. Build the desktop app
+bun run build:tauri
+```
+
+Build artifacts appear in `apps/desktop/src-tauri/target/release/bundle/`.
+
+### Platform-Specific Bundles
+
+| Platform | Bundle location |
+|----------|----------------|
+| macOS | `target/release/bundle/dmg/SafeLens_*.dmg` |
+| Windows | `target/release/bundle/msi/SafeLens_*.msi` |
+| Linux | `target/release/bundle/deb/safe-lens_*.deb`, `target/release/bundle/appimage/safe-lens_*.AppImage` |
+
+## CI Build Pipeline
+
+Release builds run in GitHub Actions ([`release.yml`](.github/workflows/release.yml)):
+
+1. **verify-ci**: Full lint + type-check + test + Rust checks
+2. **build**: Matrix build on macOS (ARM64), Windows (x64), Linux (x64) using `tauri-apps/tauri-action`
+3. **release**: Collects artifacts, generates `SHA256SUMS.txt`, creates a draft GitHub release
+
+All CI runners use the same pinned toolchain versions (Bun 1.3.9, Rust 1.93.1) and `--frozen-lockfile` to ensure deterministic dependency resolution.
+
+## Reproducibility Limitations
+
+Tauri/Rust builds are not yet fully bit-for-bit reproducible across environments due to:
+
+- **Code signing**: macOS and Windows builds may include platform-specific signatures
+- **Timestamps**: Some build tools embed timestamps in binaries
+- **System libraries**: Linked system libraries (WebKit, OpenSSL) differ across OS versions
+
+The `SHA256SUMS.txt` file in each release is the canonical reference. If you build locally and get a different hash, the above factors are the likely cause — not a supply-chain compromise. The source code itself can always be audited directly.
+
+## Reporting Discrepancies
+
+If you suspect a mismatch that cannot be explained by the above factors, report it via the [security policy](SECURITY.md).