ai-saas-guard 0.23.0 → 0.25.0

package/.bestpractices.json

@@ -0,0 +1,138 @@
+{
+  "name": "ai-saas-guard",
+  "description": "Local-first launch preflight for AI-built SaaS repositories, focused on review-worthy auth, billing, data access, secrets, MCP, deploy, and pull request risks.",
+  "homepage_url": "https://github.com/zr9959/ai-saas-guard#readme",
+  "repo_url": "https://github.com/zr9959/ai-saas-guard",
+  "license": "MIT",
+  "implementation_languages": "TypeScript, JavaScript",
+  "description_good_status": "Met",
+  "description_good_justification": "The README opens with the problem ai-saas-guard solves for AI-built SaaS launch review: https://github.com/zr9959/ai-saas-guard#the-problem-it-solves",
+  "interact_status": "Met",
+  "interact_justification": "The README explains how to obtain and use the CLI, and GitHub issue templates plus CONTRIBUTING.md explain feedback and contribution paths: https://github.com/zr9959/ai-saas-guard#quick-start and https://github.com/zr9959/ai-saas-guard/blob/main/CONTRIBUTING.md",
+  "contribution_status": "Met",
+  "contribution_justification": "CONTRIBUTING.md documents the pull request process, tests, docs, release gate, and safety requirements: https://github.com/zr9959/ai-saas-guard/blob/main/CONTRIBUTING.md",
+  "contribution_requirements_status": "Met",
+  "contribution_requirements_justification": "CONTRIBUTING.md documents acceptable contribution requirements, including focused PRs, tests, fixtures, docs, release gate evidence, and public-safety constraints: https://github.com/zr9959/ai-saas-guard/blob/main/CONTRIBUTING.md",
+  "floss_license_status": "Met",
+  "floss_license_justification": "The project is released under the MIT license: https://github.com/zr9959/ai-saas-guard/blob/main/LICENSE",
+  "floss_license_osi_status": "Met",
+  "floss_license_osi_justification": "MIT is an OSI-approved open source license, and the repository declares MIT in LICENSE and package.json: https://github.com/zr9959/ai-saas-guard/blob/main/LICENSE",
+  "license_location_status": "Met",
+  "license_location_justification": "The license is in the top-level LICENSE file: https://github.com/zr9959/ai-saas-guard/blob/main/LICENSE",
+  "documentation_basics_status": "Met",
+  "documentation_basics_justification": "README.md and docs/ explain installation, commands, release quality, rules, GitHub Action use, and hosted design boundaries: https://github.com/zr9959/ai-saas-guard#quick-start",
+  "documentation_interface_status": "Met",
+  "documentation_interface_justification": "README.md documents CLI commands and outputs, while docs/github-action.md documents the GitHub Action interface: https://github.com/zr9959/ai-saas-guard#commands and https://github.com/zr9959/ai-saas-guard/blob/main/docs/github-action.md",
+  "sites_https_status": "Met",
+  "sites_https_justification": "The public repository, release assets, issue tracker, and npm package are served over HTTPS: https://github.com/zr9959/ai-saas-guard and https://www.npmjs.com/package/ai-saas-guard",
+  "discussion_status": "Met",
+  "discussion_justification": "The project uses GitHub Issues and pull requests for public discussion: https://github.com/zr9959/ai-saas-guard/issues",
+  "english_status": "Met",
+  "english_justification": "The default README, docs, issue templates, pull request template, and contribution guide are in English, and the repository also provides a Chinese README for Chinese users: https://github.com/zr9959/ai-saas-guard",
+  "maintained_status": "Met",
+  "maintained_justification": "The project is actively maintained with recent commits, releases, issue closure, and CI on main: https://github.com/zr9959/ai-saas-guard/commits/main",
+  "repo_public_status": "Met",
+  "repo_public_justification": "The source repository is public on GitHub: https://github.com/zr9959/ai-saas-guard",
+  "repo_track_status": "Met",
+  "repo_track_justification": "The repository uses git on GitHub, preserving source history, authorship, and timestamps: https://github.com/zr9959/ai-saas-guard/commits/main",
+  "repo_interim_status": "Met",
+  "repo_interim_justification": "Interim source history is public through normal git commits on main, not only final release snapshots: https://github.com/zr9959/ai-saas-guard/commits/main",
+  "repo_distributed_status": "Met",
+  "repo_distributed_justification": "The project uses git, a distributed version control system: https://github.com/zr9959/ai-saas-guard",
+  "version_unique_status": "Met",
+  "version_unique_justification": "Releases use unique npm versions and GitHub tags such as v0.24.0: https://github.com/zr9959/ai-saas-guard/releases and https://www.npmjs.com/package/ai-saas-guard",
+  "version_semver_status": "Met",
+  "version_semver_justification": "The npm package and GitHub tags use semantic versioning with vMAJOR.MINOR.PATCH tags: https://github.com/zr9959/ai-saas-guard/tags",
+  "version_tags_status": "Met",
+  "version_tags_justification": "GitHub release tags are used for versioned releases and Action consumption: https://github.com/zr9959/ai-saas-guard/tags",
+  "release_notes_status": "Met",
+  "release_notes_justification": "GitHub Releases provide release notes for published versions: https://github.com/zr9959/ai-saas-guard/releases",
+  "release_notes_vulns_status": "Met",
+  "release_notes_vulns_justification": "No public vulnerability fix releases are currently known; the release gate requires release notes and security impact notes for releases: https://github.com/zr9959/ai-saas-guard/blob/main/docs/release-quality-knowledge-base.md",
+  "report_process_status": "Met",
+  "report_process_justification": "GitHub issue templates and SECURITY.md explain how to report bugs, false positives, false negatives, rule requests, and security-sensitive issues: https://github.com/zr9959/ai-saas-guard/issues/new/choose and https://github.com/zr9959/ai-saas-guard/blob/main/SECURITY.md",
+  "report_tracker_status": "Met",
+  "report_tracker_justification": "The project uses GitHub Issues as the public issue tracker: https://github.com/zr9959/ai-saas-guard/issues",
+  "report_responses_status": "Met",
+  "report_responses_justification": "The current public issue set is closed or handled, and issue templates define the response channels: https://github.com/zr9959/ai-saas-guard/issues",
+  "enhancement_responses_status": "Met",
+  "enhancement_responses_justification": "Enhancement and roadmap issues are tracked and closed through GitHub Issues: https://github.com/zr9959/ai-saas-guard/issues?q=is%3Aissue+label%3Aenhancement",
+  "report_archive_status": "Met",
+  "report_archive_justification": "GitHub Issues preserves the public issue archive: https://github.com/zr9959/ai-saas-guard/issues?q=is%3Aissue",
+  "vulnerability_report_process_status": "Met",
+  "vulnerability_report_process_justification": "SECURITY.md describes when to use private vulnerability reporting and what public issues must not contain: https://github.com/zr9959/ai-saas-guard/blob/main/SECURITY.md",
+  "vulnerability_report_private_status": "Met",
+  "vulnerability_report_private_justification": "SECURITY.md points security-sensitive reports to GitHub private vulnerability reporting: https://github.com/zr9959/ai-saas-guard/blob/main/SECURITY.md",
+  "vulnerability_report_response_status": "N/A",
+  "vulnerability_report_response_justification": "No public vulnerability reports are currently known for this project; future security-sensitive reports are routed through GitHub private vulnerability reporting: https://github.com/zr9959/ai-saas-guard/blob/main/SECURITY.md",
+  "build_status": "Met",
+  "build_justification": "The project has a one-step build through npm scripts: npm run build: https://github.com/zr9959/ai-saas-guard/blob/main/package.json",
+  "build_common_tools_status": "Met",
+  "build_common_tools_justification": "The project uses common Node.js, npm, and TypeScript tooling: https://github.com/zr9959/ai-saas-guard/blob/main/package.json",
+  "build_floss_tools_status": "Met",
+  "build_floss_tools_justification": "The build uses FLOSS Node.js, npm, and TypeScript tooling declared in package.json: https://github.com/zr9959/ai-saas-guard/blob/main/package.json",
+  "test_status": "Met",
+  "test_justification": "The automated test suite is run by npm test: https://github.com/zr9959/ai-saas-guard/blob/main/package.json",
+  "test_invocation_status": "Met",
+  "test_invocation_justification": "npm test builds the project and runs Node tests, and npm run test:fuzz runs the fast-check fuzz/property suite: https://github.com/zr9959/ai-saas-guard/blob/main/package.json",
+  "test_continuous_integration_status": "Met",
+  "test_continuous_integration_justification": "GitHub Actions runs CI on pull requests and pushes to main: https://github.com/zr9959/ai-saas-guard/blob/main/.github/workflows/ci.yml",
+  "test_policy_status": "Met",
+  "test_policy_justification": "CONTRIBUTING.md requires tests for behavior changes and vulnerable plus safe fixtures for scanner rules: https://github.com/zr9959/ai-saas-guard/blob/main/CONTRIBUTING.md",
+  "tests_are_added_status": "Met",
+  "tests_are_added_justification": "The repository contains tests for scanner behavior, hosted contracts, GitHub Action behavior, docs guards, and fuzz/property checks: https://github.com/zr9959/ai-saas-guard/tree/main/tests",
+  "tests_documented_added_status": "Met",
+  "tests_documented_added_justification": "CONTRIBUTING.md documents when tests and fixtures must be added: https://github.com/zr9959/ai-saas-guard/blob/main/CONTRIBUTING.md",
+  "warnings_status": "Met",
+  "warnings_justification": "TypeScript strict mode is enabled and CI runs workflow static checks through actionlint and zizmor: https://github.com/zr9959/ai-saas-guard/blob/main/tsconfig.json and https://github.com/zr9959/ai-saas-guard/blob/main/.github/workflows/ci.yml",
+  "warnings_fixed_status": "Met",
+  "warnings_fixed_justification": "The release gate requires a clean build, test suite, workflow checks, self-scan, dependency audit, and package inspection before public release: https://github.com/zr9959/ai-saas-guard/blob/main/docs/release-quality-knowledge-base.md",
+  "warnings_strict_status": "Met",
+  "warnings_strict_justification": "TypeScript strict mode is enabled in tsconfig.json, and CI includes actionlint plus zizmor for workflow quality and security checks: https://github.com/zr9959/ai-saas-guard/blob/main/tsconfig.json",
+  "know_secure_design_status": "Met",
+  "know_secure_design_justification": "The docs and rule catalog document secure design concerns for auth, billing, data access, secrets, MCP, hosted privacy, webhook verification, and release gating: https://github.com/zr9959/ai-saas-guard/blob/main/docs/rules.md and https://github.com/zr9959/ai-saas-guard/blob/main/docs/github-app-design.md",
+  "know_common_errors_status": "Met",
+  "know_common_errors_justification": "The project focuses on common SaaS launch errors such as missing ownership checks, unsafe Stripe webhooks, broad Supabase policies, secret exposure, unsafe MCP tools, and risky deploy settings: https://github.com/zr9959/ai-saas-guard/blob/main/docs/rules.md",
+  "crypto_published_status": "Met",
+  "crypto_published_justification": "Hosted helper code uses documented GitHub App RS256 JWT signing and HMAC SHA-256 webhook verification patterns rather than custom cryptography: https://github.com/zr9959/ai-saas-guard/blob/main/src/hosted/production-adapters.ts and https://github.com/zr9959/ai-saas-guard/blob/main/src/hosted/contracts.ts",
+  "crypto_call_status": "Met",
+  "crypto_call_justification": "Cryptographic operations use Node.js standard crypto APIs and GitHub-documented algorithms for GitHub App JWTs and webhook verification: https://github.com/zr9959/ai-saas-guard/blob/main/src/hosted/production-adapters.ts and https://github.com/zr9959/ai-saas-guard/blob/main/src/hosted/contracts.ts",
+  "crypto_floss_status": "Met",
+  "crypto_floss_justification": "The project uses FLOSS Node.js runtime cryptography through standard APIs: https://github.com/zr9959/ai-saas-guard/blob/main/package.json",
+  "crypto_keylength_status": "Met",
+  "crypto_keylength_justification": "The hosted design relies on GitHub App private-key material generated and managed for GitHub App authentication and does not define custom key sizes or algorithms: https://github.com/zr9959/ai-saas-guard/blob/main/docs/github-app-design.md",
+  "crypto_working_status": "Met",
+  "crypto_working_justification": "The project uses current GitHub App RS256 JWT signing and HMAC SHA-256 webhook verification mechanisms, not obsolete custom algorithms: https://github.com/zr9959/ai-saas-guard/blob/main/docs/github-app-design.md",
+  "crypto_weaknesses_status": "Met",
+  "crypto_weaknesses_justification": "The project does not use intentionally weak algorithms such as MD5 or SHA-1 for security decisions; hosted verification uses HMAC SHA-256 and JWT signing uses RS256: https://github.com/zr9959/ai-saas-guard/blob/main/src/hosted/contracts.ts",
+  "crypto_pfs_status": "N/A",
+  "crypto_pfs_justification": "The local CLI does not implement TLS transport; public distribution is through HTTPS GitHub and npm endpoints: https://github.com/zr9959/ai-saas-guard",
+  "crypto_password_storage_status": "N/A",
+  "crypto_password_storage_justification": "The local CLI and hosted helper contracts do not store user passwords: https://github.com/zr9959/ai-saas-guard#privacy-model",
+  "crypto_random_status": "N/A",
+  "crypto_random_justification": "The project does not generate cryptographic random values for security decisions in the local CLI: https://github.com/zr9959/ai-saas-guard",
+  "delivery_mitm_status": "Met",
+  "delivery_mitm_justification": "Source, releases, and npm package distribution use HTTPS endpoints: https://github.com/zr9959/ai-saas-guard/releases and https://www.npmjs.com/package/ai-saas-guard",
+  "delivery_unsigned_status": "Met",
+  "delivery_unsigned_justification": "GitHub releases attach npm provenance-backed tarballs plus sigstore and in-toto provenance assets, and npm trusted publishing provides provenance: https://github.com/zr9959/ai-saas-guard/releases and https://github.com/zr9959/ai-saas-guard/blob/main/docs/repository-trust-hardening.md",
+  "vulnerabilities_fixed_60_days_status": "Met",
+  "vulnerabilities_fixed_60_days_justification": "No unresolved high or critical production dependency vulnerabilities are currently known; the release gate requires npm audit at high severity or above: https://github.com/zr9959/ai-saas-guard/blob/main/docs/release-quality-knowledge-base.md",
+  "vulnerabilities_critical_fixed_status": "Met",
+  "vulnerabilities_critical_fixed_justification": "No unresolved critical vulnerabilities are currently known; SECURITY.md and the release gate define the response and release evidence path: https://github.com/zr9959/ai-saas-guard/blob/main/SECURITY.md",
+  "no_leaked_credentials_status": "Met",
+  "no_leaked_credentials_justification": "The repository has secret scanning and push protection enabled, uses inert fixtures, and the release gate forbids real credentials: https://github.com/zr9959/ai-saas-guard/blob/main/docs/repository-trust-hardening.md",
+  "static_analysis_status": "Met",
+  "static_analysis_justification": "The repository runs CodeQL SAST and workflow static checks with actionlint and zizmor: https://github.com/zr9959/ai-saas-guard/blob/main/.github/workflows/codeql.yml and https://github.com/zr9959/ai-saas-guard/blob/main/.github/workflows/ci.yml",
+  "static_analysis_common_vulnerabilities_status": "Met",
+  "static_analysis_common_vulnerabilities_justification": "CodeQL analyzes JavaScript and TypeScript for common vulnerability patterns, and ai-saas-guard self-scan checks SaaS launch-specific risks: https://github.com/zr9959/ai-saas-guard/blob/main/.github/workflows/codeql.yml",
+  "static_analysis_fixed_status": "Met",
+  "static_analysis_fixed_justification": "The release gate requires CI, CodeQL, actionlint, zizmor, self-scan, dependency audit, and issue tracking for findings before release: https://github.com/zr9959/ai-saas-guard/blob/main/docs/release-quality-knowledge-base.md",
+  "static_analysis_often_status": "Met",
+  "static_analysis_often_justification": "CodeQL runs on pull requests, pushes to main, and a weekly schedule; CI workflow checks run on pull requests and pushes to main: https://github.com/zr9959/ai-saas-guard/blob/main/.github/workflows/codeql.yml",
+  "dynamic_analysis_status": "Met",
+  "dynamic_analysis_justification": "The project uses fast-check fuzz/property tests for attacker-controlled markdown, SARIF, and redaction paths: https://github.com/zr9959/ai-saas-guard/blob/main/tests/fuzz.test.js",
+  "dynamic_analysis_unsafe_status": "N/A",
+  "dynamic_analysis_unsafe_justification": "The project is implemented in TypeScript and JavaScript rather than memory-unsafe C or C++: https://github.com/zr9959/ai-saas-guard/blob/main/package.json",
+  "dynamic_analysis_fixed_status": "Met",
+  "dynamic_analysis_fixed_justification": "The fuzz/property tests are part of CI and the release gate requires tests to pass before release: https://github.com/zr9959/ai-saas-guard/blob/main/.github/workflows/ci.yml"
+}

package/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing
+
+`ai-saas-guard` is a local-first launch preflight CLI for AI-built SaaS repositories. Contributions should keep that promise narrow: find review-worthy launch risks, show evidence, and avoid broad security claims.
+
+## Pull Request Process
+
+1. Open an issue or comment on an existing issue before large feature work.
+2. Keep pull requests focused. Separate scanner behavior, docs, workflow changes, and release work when practical.
+3. Include tests for behavior changes. New scanner rules need a vulnerable fixture, a safe fixture, and assertions for both.
+4. Update documentation when behavior, commands, outputs, or release expectations change. If `README.md` changes, review and update `README.zh-CN.md` in the same pull request.
+5. Fill out the pull request template with release gate evidence and known limitations.
+
+## Local Development
+
+```bash
+npm ci
+npm test
+npm run build
+node dist/cli.js --help
+node dist/cli.js scan --root . --json
+```
+
+For release candidates or public repository changes, follow [docs/release-quality-knowledge-base.md](docs/release-quality-knowledge-base.md). The release gate is the source of truth for required checks, packaging inspection, dependency audit, self-scan evidence, and rollback notes.
+
+## Testing Expectations
+
+- Run `npm test` before sending a pull request.
+- Run `npm run test:fuzz` when changing markdown rendering, SARIF rendering, secret redaction, parser behavior, or other attacker-controlled text handling.
+- Keep fixtures public-safe and minimal.
+- Prefer deterministic tests over live external services.
+- Do not remove or weaken tests without explaining the review and replacement coverage.
+
+## Rule Design
+
+Scanner rules should be evidence-first:
+
+- stable rule ID
+- severity
+- file/path evidence
+- why the issue matters for a SaaS launch
+- suggested manual verification
+- practical fix direction
+- vulnerable fixture
+- safe fixture
+- public rule documentation
+
+Avoid turning the project into a generic SAST platform. The useful surface is AI-SaaS launch readiness: auth, billing, data access, secrets, MCP tools, deploy configuration, and risky pull request diffs.
+
+## Security And Public Safety
+
+- No real API keys, tokens, cookies, webhook signing secrets, database URLs, customer data, private source code, or private URLs.
+- Use inert fake values in fixtures and examples.
+- Do not add network calls to local scan commands unless a future feature is explicitly designed, documented, and tested as opt-in.
+- Do not add shell execution to scan commands unless it is explicit, narrow, and separately reviewed.
+- Public issues must stay safe to read. Use GitHub private vulnerability reporting for sensitive vulnerability details.
+
+## Coding Standards
+
+- Keep TypeScript strict and readable.
+- Prefer small, focused helpers over broad abstractions.
+- Keep CLI output useful for human reviewers and machine output parseable.
+- Redact secret-like evidence.
+- Bound resource use for repository scanning.
+- Keep GitHub Actions permissions minimal and avoid untrusted input interpolation in shell scripts.
+
+## Feedback Channels
+
+Use GitHub issues for bugs, false positives, false negatives, and rule requests:
+
+https://github.com/zr9959/ai-saas-guard/issues
+
+Use private vulnerability reporting for security-sensitive reports:
+
+https://github.com/zr9959/ai-saas-guard/security/advisories/new

package/README.md

@@ -18,6 +18,7 @@
 
 <p align="center">
   <a href="https://github.com/zr9959/ai-saas-guard/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/zr9959/ai-saas-guard/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://www.bestpractices.dev/projects/12955"><img alt="OpenSSF Best Practices" src="https://www.bestpractices.dev/projects/12955/badge"></a>
   <a href="https://www.npmjs.com/package/ai-saas-guard"><img alt="npm" src="https://img.shields.io/npm/v/ai-saas-guard.svg"></a>
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
   <a href="package.json"><img alt="Node.js >=20" src="https://img.shields.io/badge/node-%3E%3D20-339933.svg"></a>
@@ -73,14 +74,18 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | JSON and SARIF output | Available |
 | Composite GitHub Action | Available |
 | Project config | `.ai-saas-guard.json` rule toggles, severity overrides, and fail thresholds |
-| Versioned Action tags | `v0.23.0`, `v0` |
-| npm package | `ai-saas-guard@0.23.0` |
+| Versioned Action tags | `v0.25.0`, `v0` |
+| npm package | `ai-saas-guard@0.25.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
-| Runtime hardening | Per-file and total text scan caps, escaped markdown evidence, stricter hosted deployment blockers |
+| Repository trust hardening | Strict branch protection, Dependabot, CodeQL, fast-check fuzzing, signed release provenance assets, private vulnerability reporting, secret scanning, and push protection |
+| Runtime hardening | Per-file and total text scan caps, escaped markdown evidence, 1 MiB hosted webhook payload cap, stricter hosted deployment blockers |
 | Hosted production adapters | GitHub App JWT signing, installation-token request planning, bounded worker execution, and terminal-state cleanup planning |
 | Hosted app skeleton | Node/container HTTP ingress, health route, worker tick, in-memory provider adapters, and deployment plan validation |
 | Hosted staging deployment planner | Provider binding, staging release-gate evidence, Node/container deployment composition, and GitHub App promotion gating |
 | Hosted staging harness | File-backed webhook replay, queue/report/Check Run artifacts, worker cleanup verification, and local release-gate evidence fixtures |
+| Cloudflare hosted ingress | Deployed at `https://ai-saas-guard-hosted.zr9959.workers.dev` for signed GitHub webhook intake and KV queueing; scan workers and Check Runs are still gated |
+| Hosted GitHub App staging | Private App `ai-saas-guard-hosted` (`3834787`) installed on `zr9959/ai-saas-guard` with contents read, pull requests read, metadata read, and checks write |
+| OpenSSF Best Practices | Passing badge, project `12955`; `.bestpractices.json` remains the conservative evidence record |
 
 ## Quick Start
 
@@ -201,6 +206,16 @@ If `--base` cannot be resolved, `pr-risk` emits `pr-risk.diff-unavailable` inste
 
 Use [docs/launch-readiness-checklist.md](docs/launch-readiness-checklist.md) when an app is close to inviting real users. It explains how to combine `ai-saas-guard` output with manual two-account authorization testing, Stripe webhook verification, MCP config review, Supabase policy review, deploy checks, rollback planning, and a clear reminder that this is not a full security audit.
 
+## Repository Trust Hardening
+
+See [docs/repository-trust-hardening.md](docs/repository-trust-hardening.md) for the public repository controls behind this release line: strict branch protection, required CI checks, Dependabot for npm and GitHub Actions, CodeQL SAST, fast-check fuzz/property tests, signed GitHub release assets backed by npm trusted publishing provenance, private vulnerability reporting, secret scanning, and push protection.
+
+The latest GitHub releases mirror the npm package tarball and attach `*.tgz.sigstore.json` plus `*.tgz.intoto.jsonl` provenance assets. These assets are generated from npm provenance, with the tarball digest checked against the npm registry metadata before upload.
+
+The current Scorecard improvement track focuses on real controls, not cosmetic score gaming: stricter review gates, detectable fuzzing, and the OpenSSF Best Practices Badge process. Some Scorecard items, such as repository age, contributor diversity, and reviewed PR history, improve only through time and normal public maintenance.
+
+The repository now has an [OpenSSF Best Practices passing badge](https://www.bestpractices.dev/projects/12955). [.bestpractices.json](.bestpractices.json) remains the conservative evidence record for the public project entry. `dynamic_analysis_enable_assertions` is still intentionally marked unmet until runtime assertion coverage is broader than the current test, property, and fuzz assertions.
+
 ## Stripe Webhook Replay
 
 Use [docs/stripe-webhook-replay.md](docs/stripe-webhook-replay.md) after `check-stripe` flags missing signature verification, idempotency, lifecycle handlers, or entitlement updates. The cookbook maps findings to concrete `stripe listen` and `stripe trigger` commands for checkout success, failed renewal, subscription update, cancellation, refund, duplicate delivery, and out-of-order event review.
@@ -225,6 +240,8 @@ The hosted staging deployment planner is documented in [docs/hosted-staging-depl
 
 The hosted staging harness is documented in [docs/hosted-staging-harness.md](docs/hosted-staging-harness.md). It exports `createFileBackedHostedStagingHarness` and `createHostedStagingHarnessEvidence` from `ai-saas-guard/hosted/staging-harness`. It runs signed webhook replay through the provider-independent hosted runtime with local file-backed queue, compact report, and Check Run adapters, then verifies worker sandbox cleanup. It is a staging rehearsal tool only; it does not call cloud providers, create a GitHub App, publish live Check Runs, or expose a public hosted service.
 
+The first live hosted ingress is deployed on Cloudflare Workers at `https://ai-saas-guard-hosted.zr9959.workers.dev` and documented in [hosted/cloudflare-worker/README.md](hosted/cloudflare-worker/README.md). It exposes `/healthz`, `/github/app/manifest-callback`, and signed `/github/webhook` intake backed by Cloudflare KV. A private staging GitHub App, `ai-saas-guard-hosted`, is installed on `zr9959/ai-saas-guard` with selected-repository access and the first-slice permission contract. The deployed ingress has the required Cloudflare credential bindings configured. It deliberately queues compact pull request identity records only; scan worker execution, GitHub installation-token exchange, PR diff fetching, and Check Run publishing remain blocked until their deployed evidence passes the hosted operational release gate.
+
 The hosted operational release gate is documented in [docs/hosted-operational-release-gate.md](docs/hosted-operational-release-gate.md). It defines the hosted-specific CI, replay, queue, worker cleanup, privacy, monitoring, rollback, and incident-response evidence required before any hosted environment is exposed to users. The pure gate evaluator exported from `ai-saas-guard/hosted/contracts` blocks hosted exposure unless every P0 evidence item is fresh, a container digest is recorded, and release notes avoid pentest, certification, and full-audit claims.
 
 Hosted uninstall and data deletion behavior is documented in [docs/hosted-uninstall-data-deletion.md](docs/hosted-uninstall-data-deletion.md). It defines repository removal, full app uninstall, compact report deletion, queue cancellation, audit record retention, repeated cleanup, and user-facing deletion wording.
@@ -271,7 +288,7 @@ Use `suppressions` for narrower false-positive handling when one rule is noisy o
 
 ## GitHub Action
 
-The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.23.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
+The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.25.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard
@@ -388,6 +405,8 @@ node dist/cli.js scan --root .
 
 Before publishing a CLI update, GitHub Action update, npm package, plugin, or public repository change, follow [docs/release-quality-knowledge-base.md](docs/release-quality-knowledge-base.md).
 
+Contribution expectations are documented in [CONTRIBUTING.md](CONTRIBUTING.md), including pull request process, tests, rule-design requirements, release gate evidence, and public-safety constraints.
+
 ## Roadmap
 
 Open-source core:

package/README.zh-CN.md

@@ -16,6 +16,14 @@
   <a href="README.md">English README</a> | 中文
 </p>
 
+<p align="center">
+  <a href="https://github.com/zr9959/ai-saas-guard/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/zr9959/ai-saas-guard/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://www.bestpractices.dev/projects/12955"><img alt="OpenSSF Best Practices" src="https://www.bestpractices.dev/projects/12955/badge"></a>
+  <a href="https://www.npmjs.com/package/ai-saas-guard"><img alt="npm" src="https://img.shields.io/npm/v/ai-saas-guard.svg"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  <a href="package.json"><img alt="Node.js >=20" src="https://img.shields.io/badge/node-%3E%3D20-339933.svg"></a>
+</p>
+
 ---
 
 ## 它解决什么问题
@@ -55,7 +63,7 @@ AI 能很快把一个 SaaS 从想法做成可运行的产品。真正难的是
 
 这个仓库是公开 GitHub 仓库。
 
-CLI 已发布到 npm：`ai-saas-guard@0.23.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.23.0`。
+CLI 已发布到 npm：`ai-saas-guard@0.25.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.25.0`。
 
 | 模块 | 状态 |
 | --- | --- |
@@ -66,14 +74,18 @@ CLI 已发布到 npm：`ai-saas-guard@0.23.0`。GitHub Action 支持 `v0` 浮动
 | Markdown PR summary | 已可用 |
 | GitHub Action | 已可用 |
 | 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖和 fail threshold |
-| 当前版本 | `0.23.0` |
-| Action 标签 | `v0.23.0`、`v0` |
+| 当前版本 | `0.25.0` |
+| Action 标签 | `v0.25.0`、`v0` |
 | npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
-| 运行时加固 | 单文件和总扫描文本预算、markdown evidence 转义、更严格的 hosted deployment 阻断 |
+| 仓库可信度加固 | 严格 branch protection、Dependabot、CodeQL、fast-check fuzzing、signed release provenance assets、private vulnerability reporting、secret scanning 和 push protection |
+| 运行时加固 | 单文件和总扫描文本预算、markdown evidence 转义、1 MiB hosted webhook payload 上限、更严格的 hosted deployment 阻断 |
 | Hosted production adapters | GitHub App JWT 签名、installation-token 请求规划、有边界的 worker 执行和终态 cleanup 规划 |
 | Hosted app skeleton | Node/container HTTP ingress、health route、worker tick、in-memory provider adapters 和 deployment plan 校验 |
 | Hosted staging deployment planner | provider binding、staging release-gate evidence、Node/container deployment 组合和 GitHub App promotion gating |
 | Hosted staging harness | 本地 file-backed webhook replay、queue/report/Check Run artifact、worker cleanup 校验和 release-gate evidence fixture |
+| Cloudflare hosted ingress | 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`，用于签名 GitHub webhook intake 和 KV 排队；scan worker 和 Check Run 仍然受 release gate 阻断 |
+| Hosted GitHub App staging | 私有 App `ai-saas-guard-hosted`（`3834787`）已安装到 `zr9959/ai-saas-guard`，权限为 contents read、pull requests read、metadata read、checks write |
+| OpenSSF Best Practices | 已获得 passing badge，项目 `12955`；`.bestpractices.json` 继续作为保守证据记录 |
 
 ## 快速开始
 
@@ -134,6 +146,16 @@ node dist/cli.js scan --root /path/to/your-saas
 
 完整规则请看 [docs/rules.md](docs/rules.md)。
 
+## 仓库可信度加固
+
+公开仓库的维护和发布控制见 [docs/repository-trust-hardening.md](docs/repository-trust-hardening.md)。当前已经配置严格 branch protection、required CI checks、Dependabot npm/GitHub Actions 更新、CodeQL SAST、fast-check fuzz/property tests、基于 npm trusted publishing provenance 的 signed GitHub release assets、private vulnerability reporting、secret scanning 和 push protection。
+
+最新 GitHub releases 会镜像 npm package tarball，并附带 `*.tgz.sigstore.json` 和 `*.tgz.intoto.jsonl` provenance assets。上传前会用 npm registry metadata 校验 tarball digest，并使用 npm provenance 作为来源。
+
+当前 Scorecard 提升路线优先做真实控制，不做表面刷分：更严格的 review gate、可被检测到的 fuzzing、以及 OpenSSF Best Practices Badge 流程。仓库年龄、贡献者多样性、已 review 的 PR 历史这些分数只能随着真实维护逐步提升。
+
+仓库现在已经获得 [OpenSSF Best Practices passing badge](https://www.bestpractices.dev/projects/12955)。[.bestpractices.json](.bestpractices.json) 继续作为公开项目条目的保守证据记录。`dynamic_analysis_enable_assertions` 仍然谨慎标为 unmet，直到运行时断言覆盖面超过当前测试、property 和 fuzz assertions。
+
 ## PR 风险分流
 
 `scan` 可以扫整个仓库，但这个项目更锋利的入口是 PR review。
@@ -244,7 +266,7 @@ jobs:
 
 ## Hosted GitHub App 设计
 
-当前仓库已经包含未来 Hosted GitHub App 的设计文档和纯契约测试，但还没有部署真实 hosted 服务。
+当前仓库已经包含未来 Hosted GitHub App 的设计文档、纯契约测试，以及第一个真实 Cloudflare hosted ingress。私有 staging GitHub App `ai-saas-guard-hosted` 已安装到 `zr9959/ai-saas-guard`，Cloudflare 已配置所需的云端凭据绑定。这个 ingress 已经能接收签名 webhook 并写入 KV 队列，但还不是完整自动扫描服务。
 
 相关文档：
 
@@ -273,6 +295,7 @@ jobs:
 - Hosted Node/container app skeleton：`ai-saas-guard/hosted/app` 导出 `createHostedHttpApp`、`createInMemoryHostedAppPlatform` 和 `planHostedNodeContainerDeployment`，提供安全 `/healthz`、签名 `/github/webhook` ingress、单 job worker tick、测试用 in-memory provider adapters，以及 secret manager、queue、compact report store、worker sandbox、GitHub Checks publisher 的部署引用校验；它本身仍然不部署或暴露公开 hosted 服务
 - Hosted staging deployment planner：`ai-saas-guard/hosted/staging` 导出 `planHostedProviderBinding`、`planHostedStagingDeployment` 和 `planHostedGitHubAppPromotion`，把真实 provider 引用、Node/container deployment plan、hosted operational release-gate evidence 和 GitHub App deployment planning 组合起来；缺少 queue、store、worker sandbox、Check Run publisher、logs、metrics、rollback 或 incident-response 引用时，会阻止 staging exposure 和 production promotion；它本身仍然不会调用云平台、创建 GitHub App 或暴露公开 hosted 服务
 - Hosted staging harness：`ai-saas-guard/hosted/staging-harness` 导出 `createFileBackedHostedStagingHarness` 和 `createHostedStagingHarnessEvidence`，可以在本地用 file-backed queue、compact report、Check Run request 和 worker sandbox 跑通签名 webhook replay、worker tick 和 cleanup 校验；它只是 staging 演练工具，不会调用云平台、创建 GitHub App、写真实 Check Run 或暴露公开 hosted 服务
+- Cloudflare hosted ingress：`hosted/cloudflare-worker` 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`，提供 `/healthz`、`/github/app/manifest-callback` 和签名 `/github/webhook` intake，并只把 compact pull request identity 写入 Cloudflare KV；staging GitHub App ID 为 `3834787`，installation ID 为 `135085075`；GitHub installation-token exchange、PR diff fetching、scan worker 和 Check Run publishing 仍然需要通过 hosted operational release gate
 - webhook event parser
 - check-run summary renderer
 - Check Run publication planner：要求 repository `checks: write`，只从 compact report 生成有长度上限的 Check Run payload，包含 review categories、优先 review 文件、verification steps 和本地 CLI 复现命令；MVP 不发 PR comment
@@ -311,6 +334,8 @@ node dist/cli.js scan --root .
 
 以后更新英文 `README.md` 时，也要同步检查并更新本中文 `README.zh-CN.md`。
 
+贡献要求见 [CONTRIBUTING.md](CONTRIBUTING.md)，里面说明了 PR 流程、测试要求、规则设计、release gate evidence 和公开安全边界。
+
 ## 安全报告
 
 报告漏洞前请阅读 [SECURITY.md](SECURITY.md)。不要在公开 issue 中发布真实 API key、客户数据、私有源码或生产 URL。

package/docs/github-action.md

@@ -2,7 +2,7 @@
 
 `ai-saas-guard` ships as a composite GitHub Action for pull request and code scanning workflows.
 
-Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a specific tag such as `v0.23.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
+Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a specific tag such as `v0.25.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
 
 ## PR Summary
 

package/docs/github-app-deployment.md

@@ -78,6 +78,15 @@ When `readyToCreateGitHubApp` is true:
 
 ## Current Status
 
-The repository can now produce and validate the deployment plan, but it cannot honestly create a live GitHub App until a public hosted webhook URL, container image digest, and secret manager references exist.
+The repository can now produce and validate the deployment plan, and a private staging GitHub App exists for the first live hosted ingress:
+
+- App slug: `ai-saas-guard-hosted`
+- App ID: `3834787`
+- Installation ID: `135085075`
+- Installed repository: `zr9959/ai-saas-guard`
+- Webhook URL: `https://ai-saas-guard-hosted.zr9959.workers.dev/github/webhook`
+- Secret storage: Cloudflare Worker secrets for `WEBHOOK_SECRET` and `GITHUB_APP_PRIVATE_KEY`
+
+This is still an ingress-only staging deployment. It verifies signatures and queues compact pull request identity records, but it does not fetch PR diffs, exchange installation tokens for worker access, run scans, or publish Check Runs yet.
 
 The next deployment stage should wire the hosted service runtime, production adapters, [Node/container app skeleton](hosted-node-container-app.md), and [staging deployment planner](hosted-staging-deployment.md) to a real platform queue, compact report store, GitHub installation authentication, worker isolation layer, Checks API publisher, logs, metrics, rollback, and incident-response evidence.

package/docs/npm-publishing.md

@@ -5,10 +5,10 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.23.0`
+- Current version: `0.25.0`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.23.0`
+- GitHub Release: `v0.25.0`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions, `zr9959/ai-saas-guard`, workflow `npm-publish.yml`, allowed action `npm publish`
 - Long-lived npm publish token: not required
@@ -17,7 +17,7 @@
 
 Use GitHub Actions with npm Trusted Publisher/OIDC:
 
-1. Create and review a release tag such as `v0.23.0`.
+1. Create and review a release tag such as `v0.25.0`.
 2. Publish from the GitHub Release or run the `Publish npm` workflow manually with `ref` set to that tag.
 3. Keep `permissions.id-token: write` in the workflow so npm can exchange the GitHub Actions OIDC identity for a short-lived publish credential.
 4. Run `npm publish --access public` from the workflow. Trusted publishing automatically generates provenance for this public package from this public repository.

package/docs/project-handoff.md

@@ -63,12 +63,15 @@ Implemented surfaces:
 - hosted Node/container app skeleton document and helpers for safe health and webhook HTTP ingress, one-job worker ticks, in-memory provider adapters, provider reference validation, and the chosen `node_container` roles `webhook-ingress` and `scan-worker`
 - hosted staging deployment planner document and helpers for provider binding, staging release-gate evidence, Node/container deployment composition, and production GitHub App promotion gating
 - hosted staging harness document and helpers for local signed webhook replay, file-backed queue/report/Check Run artifacts, worker sandbox cleanup verification, and release-gate evidence fixtures without cloud calls
+- live Cloudflare hosted ingress at `https://ai-saas-guard-hosted.zr9959.workers.dev` with `/healthz`, `/github/app/manifest-callback`, signed `/github/webhook` intake, Cloudflare KV storage, private staging GitHub App `ai-saas-guard-hosted` (`3834787`) installed on `zr9959/ai-saas-guard`, and explicit `shouldCreateCheckRun: false` until scan worker and Check Run publishing are wired
 - resource caps for repository text collection, including per-file, total-file, and total-byte scan budgets to reduce worst-case memory use
 - hosted pre-implementation contracts document, hosted compact report fixture, and pure helpers for pull request webhook intake planning, durable scan queue upsert planning, worker read-only scan planning, Check Run publication planning, queue-safe pull request event parsing from trusted GitHub event fields, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, retention/deletion cleanup planning, and operational release gate evaluation
 - implementation-ready hosted GitHub App permission contract for required permissions, optional PR comment permissions, selected repository installation, and out-of-scope broad permissions
 - hosted GitHub App contract helpers and tests for webhook intake order, webhook verification, installation token scoping, durable scan queue idempotency, compact reports, retention limits, uninstall cleanup, repeated cleanup idempotency, scoped deletion planning, operational release gate blocking, provider-independent service runtime orchestration, GitHub App deployment planning, hosted production adapter planning, Node/container app skeleton planning, hosted staging deployment planning, and local staging harness replay
 - GitHub issue templates for bug reports, false positives, false negatives, rule requests, and public-safe security reports
 - CODEOWNERS for source, tests, docs, workflows, Action, and package metadata
+- repository trust hardening with strict `main` branch protection, required CI status checks, fast-check fuzzing, signed GitHub release assets backed by npm trusted publishing provenance, Dependabot for npm and GitHub Actions, CodeQL, private vulnerability reporting, secret scanning, and push protection
+- OpenSSF Best Practices passing badge at https://www.bestpractices.dev/projects/12955, with `.bestpractices.json` for conservative repository-backed answer proposals and `CONTRIBUTING.md` for pull request process, tests, rule-design requirements, release gate evidence, and public-safety constraints
 - JSON output
 - SARIF output
 - composite GitHub Action wrapper
@@ -132,12 +135,32 @@ CI:
 - Workflow: `.github/workflows/ci.yml`
 - Runs on pull requests and pushes to `main`
 - Uses `permissions: contents: read`
-- Latest verified run for the hosted Check Run publication release succeeded
+- Static workflow checks: `actionlint` and `zizmor`
+- Code scanning workflow: `.github/workflows/codeql.yml`
+- Fuzz/property tests: `npm run test:fuzz` with `fast-check`
+- Dependabot config: `.github/dependabot.yml` with weekly schedules, bounded PR volume, and cooldown windows
+- Latest verified run for the repository trust hardening release must succeed before publishing
+
+Hosted staging:
+
+- Cloudflare Worker URL: https://ai-saas-guard-hosted.zr9959.workers.dev
+- Cloudflare KV binding: `HOSTED_EVENTS`
+- GitHub App: `ai-saas-guard-hosted`
+- GitHub App ID: `3834787`
+- GitHub App installation ID: `135085075`
+- Installed repository: `zr9959/ai-saas-guard`
+- Current hosted mode: signed webhook ingress and compact queueing only
+- Not yet complete: GitHub App installation-token exchange, PR diff fetching, scan worker execution, Check Run publishing, monitoring evidence, rollback evidence, and incident-response evidence
+
+OpenSSF Best Practices:
+
+- Project: https://www.bestpractices.dev/projects/12955
+- Badge level: passing
 
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.23.0`
+- Current release line: `v0.25.0`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions for `zr9959/ai-saas-guard`, workflow `npm-publish.yml`
 - Long-lived npm publish tokens should not be required.

package/docs/release-quality-knowledge-base.md

@@ -170,7 +170,7 @@ P2:
 
 - Use GitHub Projects for a public roadmap.
 - Add OpenSSF Scorecard badge once score is acceptable.
-- Add OpenSSF Best Practices Badge process once project stabilizes.
+- Keep the OpenSSF Best Practices Badge evidence current after public process, README, or release-gate changes.
 
 ## GitHub Actions Security
 

package/docs/repository-trust-hardening.md

@@ -0,0 +1,128 @@
+# Repository Trust Hardening
+
+This document records the public repository controls used to keep `ai-saas-guard` releases reviewable and safer to consume.
+
+These controls do not prove the project is secure. They reduce supply-chain and maintenance risk around the public CLI, GitHub Action, npm package, and future hosted service work.
+
+## Branch Protection
+
+The `main` branch uses branch protection with:
+
+- required status checks before merge
+- strict status check freshness
+- administrator enforcement
+- stale review dismissal
+- CODEOWNERS review
+- last-push approval
+- two approving reviews
+- linear history
+- force pushes disabled
+- branch deletion disabled
+
+Required status checks:
+
+- `test`
+- `fuzz`
+- `actionlint`
+- `zizmor`
+- `codeql`
+
+Maintainer admin bypass is enforced for normal branch updates. Repository administrators can still update protection settings through GitHub admin APIs if emergency recovery is needed.
+
+## Dependency Updates
+
+Dependabot is configured in `.github/dependabot.yml`.
+
+It covers:
+
+- npm dependencies
+- GitHub Actions
+
+The schedule is weekly with cooldown windows and a small open pull request limit. This keeps update noise low while still surfacing security and maintenance updates.
+
+Dependabot security updates and vulnerability alerts are enabled in repository settings.
+
+## CodeQL
+
+CodeQL is configured in `.github/workflows/codeql.yml`.
+
+The workflow:
+
+- runs on pull requests
+- runs on pushes to `main`
+- runs on a weekly schedule
+- analyzes JavaScript and TypeScript
+- uses `build-mode: none`
+- uses least-privilege permissions: repository contents read, Actions metadata read, and security event upload
+- pins the CodeQL Action by commit SHA
+
+CodeQL is an additional SAST signal. It does not replace `ai-saas-guard`'s release gate, local tests, workflow checks, self-scan, dependency audit, package inspection, or human review.
+
+## Fuzzing
+
+The repository runs Scorecard-detectable fuzzing with `fast-check`.
+
+The fuzz tests cover:
+
+- markdown report escaping for attacker-controlled evidence
+- SARIF serialization for arbitrary finding text
+- generated secret redaction paths
+
+The dedicated `fuzz` CI job runs `npm run test:fuzz`. The regular `test` job also includes `tests/fuzz.test.js` because it runs the full Node test suite.
+
+## Signed Release Assets
+
+GitHub releases mirror the published npm package tarball and attach the npm trusted publishing provenance used for that release.
+
+Each release should include:
+
+- `ai-saas-guard-<version>.tgz`
+- `ai-saas-guard-<version>.tgz.sigstore.json`
+- `ai-saas-guard-<version>.tgz.intoto.jsonl`
+
+Before upload, the tarball SHA-512 digest must match npm registry metadata, and the SLSA subject digest in the npm provenance must match the same tarball digest. The `sigstore.json` asset keeps the npm Sigstore bundle for independent verification. The `intoto.jsonl` asset keeps the DSSE in-toto envelope that OpenSSF Scorecard and other release-integrity tooling can detect.
+
+## Vulnerability Intake
+
+The repository has:
+
+- `SECURITY.md`
+- private vulnerability reporting enabled
+- secret scanning enabled
+- push protection enabled
+
+Public issues should not include real credentials, customer data, private source code, or production URLs.
+
+## Release Impact
+
+Every public release should keep these controls intact. If a release changes workflows, package metadata, Action behavior, or hosted service boundaries, the release notes should include fresh evidence for:
+
+- local tests
+- GitHub CI
+- `actionlint`
+- `zizmor`
+- self-scan JSON and SARIF
+- dependency audit
+- fuzz/property tests
+- signed release asset digest and npm provenance checks
+- npm package inspection
+- packaged CLI smoke test
+
+## OpenSSF Best Practices Badge
+
+The OpenSSF Best Practices Badge is tracked as a separate public trust signal. The badge must be earned through the OpenSSF Best Practices web application and API; it cannot be truthfully completed by repository files alone.
+
+The repository has earned the OpenSSF Best Practices passing badge:
+
+- Project page: https://www.bestpractices.dev/projects/12955
+- Badge API: https://www.bestpractices.dev/projects/12955/badge.json
+- Passing achieved on 2026-05-24.
+
+The repository also includes `.bestpractices.json` with conservative proposed answers backed by public repository evidence. The file remains the evidence record for future maintainer review, but the public badge state is the OpenSSF project record above.
+
+Current badge evidence:
+
+- `CONTRIBUTING.md` documents the pull request process, test expectations, rule-design requirements, release gate evidence, and public-safety constraints.
+- `README.md` and `README.zh-CN.md` document the problem, install path, CLI commands, privacy model, GitHub Action use, hosted boundaries, and trust-hardening controls.
+- `.bestpractices.json` records only repository-backed OpenSSF Best Practices proposed answers; unknown or future claims should stay out until they can be supported by public evidence.
+- `dynamic_analysis_enable_assertions` is intentionally still marked unmet because the production CLI does not yet have broad runtime assertion coverage beyond tests, property tests, and fuzzing.

package/hosted/cloudflare-worker/README.md

@@ -0,0 +1,51 @@
+# Cloudflare Hosted Ingress
+
+This directory contains the first live hosted ingress for `ai-saas-guard`.
+
+It is intentionally narrow:
+
+- `GET /healthz` returns public-safe service health.
+- `GET /github/app/manifest-callback` acknowledges the GitHub App manifest redirect without storing the one-time code.
+- `POST /github/webhook` verifies GitHub `sha256` webhook signatures before JSON parsing or storage.
+- Requests over 1 MiB are rejected before JSON parsing or KV writes.
+- Signed `pull_request` events are reduced to trusted GitHub identity fields and stored in Cloudflare KV.
+- Duplicate GitHub delivery IDs are accepted idempotently.
+- Responses and KV records do not include raw webhook payloads, PR title/body text, source code, diffs, secrets, customer payloads, checkout paths, or installation tokens.
+
+This Worker is a real hosted ingress, not yet the complete scan worker. `shouldCreateCheckRun` stays `false` until GitHub App installation-token exchange, PR diff fetching, PR-risk classification, and Check Run publishing are wired and verified against deployed infrastructure.
+
+## Required Cloudflare Bindings
+
+- `HOSTED_EVENTS`: Cloudflare KV namespace for compact delivery and queued scan records.
+- `WEBHOOK_SECRET`: Worker secret matching the GitHub App webhook secret.
+- `GITHUB_APP_PRIVATE_KEY`: Worker secret for the staging GitHub App private key. It is stored for the next Check Run publishing slice and is not used by this ingress-only Worker yet.
+- `SCANNER_VERSION`: public version string, currently `0.25.0`.
+- `GITHUB_APP_ID`, `GITHUB_APP_SLUG`, `GITHUB_APP_INSTALLATION_ID`: public staging identifiers for the private GitHub App installation.
+
+## Deployment
+
+Use `wrangler` from this directory:
+
+```bash
+npx wrangler kv namespace create HOSTED_EVENTS
+npx wrangler secret put WEBHOOK_SECRET
+npx wrangler secret put GITHUB_APP_PRIVATE_KEY
+npx wrangler deploy
+```
+
+After creating the KV namespace, replace the placeholder namespace ID in `wrangler.jsonc`.
+
+Current public staging endpoint:
+
+- Worker URL: `https://ai-saas-guard-hosted.zr9959.workers.dev`
+- KV namespace binding: `HOSTED_EVENTS`
+- KV namespace ID: `fa5344fbd7944de6a776bf8731d58460`
+- GitHub App slug: `ai-saas-guard-hosted`
+- GitHub App ID: `3834787`
+- GitHub App installation ID: `135085075`
+- Installed repository: `zr9959/ai-saas-guard`
+- Mode: signed webhook ingress and compact queueing only
+
+## Release Boundary
+
+Do not expose this as the full product. The hosted operational release gate still requires deployed evidence for Check Run publication, worker cleanup, monitoring, rollback, incident response, dependency and deployment artifact scanning, and GitHub App installation behavior.

package/hosted/cloudflare-worker/src/index.js

@@ -0,0 +1,341 @@
+export const HOSTED_WORKER_PRIVACY = {
+  includesRawWebhookPayload: false,
+  includesUntrustedPrText: false,
+  includesRawSource: false,
+  includesRawDiffs: false,
+  includesSecrets: false,
+  includesCustomerPayloads: false,
+  includesPrivateCheckoutPath: false,
+  includesInstallationToken: false
+};
+
+const ALLOWED_PULL_REQUEST_ACTIONS = new Set(["opened", "reopened", "synchronize", "ready_for_review"]);
+const JSON_HEADERS = {
+  "content-type": "application/json; charset=utf-8"
+};
+const EVENT_TTL_SECONDS = 60 * 60 * 24 * 30;
+export const MAX_WEBHOOK_PAYLOAD_BYTES = 1024 * 1024;
+
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+
+    if (request.method === "GET" && (url.pathname === "/" || url.pathname === "/healthz")) {
+      return jsonResponse(200, createHostedWorkerHealth());
+    }
+
+    if (request.method === "GET" && url.pathname === "/github/app/manifest-callback") {
+      return jsonResponse(200, createGitHubAppManifestCallback(url));
+    }
+
+    if (url.pathname !== "/github/webhook") {
+      return jsonResponse(404, {
+        accepted: false,
+        reason: "not_found",
+        privacy: HOSTED_WORKER_PRIVACY
+      });
+    }
+
+    if (request.method !== "POST") {
+      return jsonResponse(405, {
+        accepted: false,
+        reason: "method_not_allowed",
+        allowedMethods: ["POST"],
+        privacy: HOSTED_WORKER_PRIVACY
+      });
+    }
+
+    if (!env?.WEBHOOK_SECRET || !env?.HOSTED_EVENTS) {
+      return jsonResponse(503, {
+        accepted: false,
+        stage: "configuration",
+        reason: "missing_worker_binding",
+        privacy: HOSTED_WORKER_PRIVACY
+      });
+    }
+
+    if (isPayloadTooLarge(request.headers.get("content-length"))) {
+      return jsonResponse(413, {
+        accepted: false,
+        stage: "payload",
+        reason: "payload_too_large",
+        maxBytes: MAX_WEBHOOK_PAYLOAD_BYTES,
+        privacy: HOSTED_WORKER_PRIVACY
+      });
+    }
+
+    const payload = await request.text();
+    if (new TextEncoder().encode(payload).byteLength > MAX_WEBHOOK_PAYLOAD_BYTES) {
+      return jsonResponse(413, {
+        accepted: false,
+        stage: "payload",
+        reason: "payload_too_large",
+        maxBytes: MAX_WEBHOOK_PAYLOAD_BYTES,
+        privacy: HOSTED_WORKER_PRIVACY
+      });
+    }
+
+    const signatureHeader = request.headers.get("x-hub-signature-256") ?? "";
+    const deliveryId = request.headers.get("x-github-delivery") ?? "";
+    const eventName = request.headers.get("x-github-event") ?? "";
+
+    const signatureAccepted = await verifyGitHubWebhookSignature({
+      payload,
+      signatureHeader,
+      secret: env.WEBHOOK_SECRET
+    });
+    if (!signatureAccepted) {
+      return jsonResponse(400, {
+        accepted: false,
+        stage: "signature",
+        reason: "invalid_signature",
+        deliveryId: deliveryId || undefined,
+        privacy: HOSTED_WORKER_PRIVACY
+      });
+    }
+
+    if (!deliveryId) {
+      return jsonResponse(400, {
+        accepted: false,
+        stage: "event",
+        reason: "missing_delivery_id",
+        privacy: HOSTED_WORKER_PRIVACY
+      });
+    }
+
+    const deliveryKey = `delivery:${deliveryId}`;
+    const existingDelivery = await env.HOSTED_EVENTS.get(deliveryKey);
+    if (existingDelivery) {
+      return jsonResponse(202, {
+        accepted: true,
+        stage: "duplicate_delivery",
+        deliveryId,
+        shouldCreateCheckRun: false,
+        privacy: HOSTED_WORKER_PRIVACY
+      });
+    }
+
+    if (eventName !== "pull_request") {
+      await storeJson(env.HOSTED_EVENTS, deliveryKey, {
+        deliveryId,
+        eventName,
+        accepted: false,
+        reason: "unsupported_event",
+        receivedAt: new Date().toISOString()
+      });
+      return jsonResponse(202, {
+        accepted: true,
+        stage: "ignored",
+        reason: "unsupported_event",
+        deliveryId,
+        shouldCreateCheckRun: false,
+        privacy: HOSTED_WORKER_PRIVACY
+      });
+    }
+
+    let parsedPayload;
+    try {
+      parsedPayload = JSON.parse(payload);
+    } catch {
+      return jsonResponse(400, {
+        accepted: false,
+        stage: "payload",
+        reason: "invalid_json",
+        deliveryId,
+        privacy: HOSTED_WORKER_PRIVACY
+      });
+    }
+
+    const identity = parsePullRequestWebhookIdentity(parsedPayload);
+    if (!identity) {
+      return jsonResponse(400, {
+        accepted: false,
+        stage: "event",
+        reason: "missing_required_identity",
+        deliveryId,
+        privacy: HOSTED_WORKER_PRIVACY
+      });
+    }
+
+    if (identity.draft || !ALLOWED_PULL_REQUEST_ACTIONS.has(identity.action)) {
+      await storeJson(env.HOSTED_EVENTS, deliveryKey, {
+        deliveryId,
+        eventName,
+        accepted: false,
+        reason: identity.draft ? "draft_pull_request" : "unsupported_pull_request_action",
+        identity,
+        receivedAt: new Date().toISOString()
+      });
+      return jsonResponse(202, {
+        accepted: true,
+        stage: "ignored",
+        reason: identity.draft ? "draft_pull_request" : "unsupported_pull_request_action",
+        deliveryId,
+        shouldCreateCheckRun: false,
+        privacy: HOSTED_WORKER_PRIVACY
+      });
+    }
+
+    const scannerVersion = env.SCANNER_VERSION || "unknown";
+    const scanKey = [
+      "scan",
+      identity.installationId,
+      identity.repositoryId,
+      identity.pullRequestNumber,
+      identity.headSha,
+      scannerVersion
+    ].join(":");
+
+    await storeJson(env.HOSTED_EVENTS, deliveryKey, {
+      deliveryId,
+      eventName,
+      accepted: true,
+      scanKey,
+      identity,
+      receivedAt: new Date().toISOString()
+    });
+    await storeJson(env.HOSTED_EVENTS, scanKey, {
+      key: scanKey,
+      status: "queued",
+      identity,
+      scannerVersion,
+      deliveryIds: [deliveryId],
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      privacy: HOSTED_WORKER_PRIVACY
+    });
+
+    return jsonResponse(202, {
+      accepted: true,
+      stage: "queued",
+      deliveryId,
+      scanKey,
+      shouldCreateCheckRun: false,
+      worker: "not_configured",
+      privacy: HOSTED_WORKER_PRIVACY
+    });
+  }
+};
+
+export function createHostedWorkerHealth() {
+  return {
+    ok: true,
+    service: "ai-saas-guard-hosted",
+    mode: "webhook-ingress",
+    routes: ["/healthz", "/github/app/manifest-callback", "/github/webhook"],
+    storage: "cloudflare_kv",
+    checkRunPublisher: "not_configured",
+    privacy: HOSTED_WORKER_PRIVACY
+  };
+}
+
+export function createGitHubAppManifestCallback(url) {
+  return {
+    ok: true,
+    service: "ai-saas-guard-hosted",
+    stage: "github_app_manifest_callback",
+    manifestCodeReceived: url.searchParams.has("code"),
+    storesManifestCode: false,
+    nextStep: "exchange_code_server_side",
+    privacy: HOSTED_WORKER_PRIVACY
+  };
+}
+
+export async function verifyGitHubWebhookSignature({ payload, signatureHeader, secret }) {
+  if (!payload || !signatureHeader || !secret || !signatureHeader.startsWith("sha256=")) {
+    return false;
+  }
+
+  const expected = await hmacSha256Header(payload, secret);
+  return constantTimeEqual(expected, signatureHeader);
+}
+
+export function parsePullRequestWebhookIdentity(payload) {
+  const installationId = integerValue(payload?.installation?.id);
+  const repositoryId = integerValue(payload?.repository?.id);
+  const repositoryFullName = stringValue(payload?.repository?.full_name);
+  const pullRequestNumber = integerValue(payload?.pull_request?.number);
+  const baseSha = shaValue(payload?.pull_request?.base?.sha);
+  const headSha = shaValue(payload?.pull_request?.head?.sha);
+  const action = stringValue(payload?.action);
+
+  if (
+    installationId === undefined ||
+    repositoryId === undefined ||
+    repositoryFullName === undefined ||
+    pullRequestNumber === undefined ||
+    baseSha === undefined ||
+    headSha === undefined ||
+    action === undefined
+  ) {
+    return null;
+  }
+
+  return {
+    action,
+    installationId,
+    repositoryId,
+    repositoryFullName,
+    repositoryPrivate: Boolean(payload?.repository?.private),
+    pullRequestNumber,
+    baseSha,
+    headSha,
+    draft: Boolean(payload?.pull_request?.draft)
+  };
+}
+
+async function hmacSha256Header(payload, secret) {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+  return `sha256=${bufferToHex(signature)}`;
+}
+
+function constantTimeEqual(left, right) {
+  if (left.length !== right.length) return false;
+
+  let mismatch = 0;
+  for (let index = 0; index < left.length; index += 1) {
+    mismatch |= left.charCodeAt(index) ^ right.charCodeAt(index);
+  }
+  return mismatch === 0;
+}
+
+function bufferToHex(buffer) {
+  return [...new Uint8Array(buffer)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function integerValue(value) {
+  return Number.isSafeInteger(value) ? value : undefined;
+}
+
+function stringValue(value) {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function shaValue(value) {
+  return typeof value === "string" && /^[a-f0-9]{40}$/i.test(value) ? value : undefined;
+}
+
+function isPayloadTooLarge(contentLength) {
+  if (contentLength === null) return false;
+  const parsed = Number(contentLength);
+  return Number.isFinite(parsed) && parsed > MAX_WEBHOOK_PAYLOAD_BYTES;
+}
+
+async function storeJson(kv, key, value) {
+  await kv.put(key, JSON.stringify(value), { expirationTtl: EVENT_TTL_SECONDS });
+}
+
+function jsonResponse(status, body) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: JSON_HEADERS
+  });
+}

package/hosted/cloudflare-worker/wrangler.jsonc

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://developers.cloudflare.com/workers/wrangler/config-schema.json",
+  "name": "ai-saas-guard-hosted",
+  "main": "src/index.js",
+  "compatibility_date": "2026-05-24",
+  "observability": {
+    "enabled": true
+  },
+  "vars": {
+    "SCANNER_VERSION": "0.25.0",
+    "GITHUB_APP_ID": "3834787",
+    "GITHUB_APP_SLUG": "ai-saas-guard-hosted",
+    "GITHUB_APP_INSTALLATION_ID": "135085075"
+  },
+  "kv_namespaces": [
+    {
+      "binding": "HOSTED_EVENTS",
+      "id": "fa5344fbd7944de6a776bf8731d58460"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "type": "module",
   "homepage": "https://github.com/zr9959/ai-saas-guard#readme",
@@ -65,7 +65,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test tests/*.test.mjs",
+    "test": "npm run build && node --test tests/*.test.mjs tests/*.test.js",
+    "test:fuzz": "npm run build && node --test tests/fuzz.test.js",
     "check": "npm run test"
   },
   "engines": {
@@ -73,15 +74,19 @@
   },
   "files": [
     "action.yml",
+    ".bestpractices.json",
+    "CONTRIBUTING.md",
     "docs",
     "dist",
     "examples",
+    "hosted",
     "README.md",
     "README.zh-CN.md"
   ],
   "license": "MIT",
   "devDependencies": {
     "@types/node": "^20",
+    "fast-check": "^4.8.0",
     "typescript": "^5"
   }
 }