diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml deleted file mode 100644 index b5327f6..0000000 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ /dev/null @@ -1,48 +0,0 @@ -name: Bug report -description: Report a reproducible analyzer or action problem. -body: - - type: input - id: version - attributes: - label: Scope Guard version - description: For example, 0.1.0 or a commit SHA. - validations: - required: true - - type: input - id: node-version - attributes: - label: Node.js version - validations: - required: true - - type: input - id: operating-system - attributes: - label: Operating system - validations: - required: true - - type: textarea - id: reproduction - attributes: - label: Reproduction - description: Include a minimal sanitized repository or fixture. - validations: - required: true - - type: textarea - id: expected - attributes: - label: Expected behavior - validations: - required: true - - type: textarea - id: actual - attributes: - label: Actual behavior - validations: - required: true - - type: textarea - id: output - attributes: - label: Sanitized output - description: Do not include tokens, credentials, private keys, or merchant data. - validations: - required: false diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 423a76e..0000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -name: Bug report -about: Report a reproducible issue in this tool -title: "[Bug]: " ---- - -## Environment - -- Tool version: -- Node.js version: -- Operating system: -- CLI, GitHub Action, or library usage: - -## Description - -## Steps to reproduce - -1. -2. -3. - -## Expected and actual behaviour - -## Minimal sanitised fixture or output - -Use synthetic configuration and remove Shopify credentials, merchant data, private repository URLs, access tokens, and secrets. Do not report suspected security vulnerabilities here; use the private reporting link in the repository's issue menu. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..04043d7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,67 @@ +name: Bug report +description: Report a reproducible Shopify Scope Guard problem +title: "bug: " +body: + - type: markdown + attributes: + value: "Use a minimal sanitised example. Never include credentials, tokens, merchant/customer data, private source, or production secrets. For suspected vulnerabilities, use the private reporting link." + - type: input + id: tool-version + attributes: + label: Tool version + validations: + required: true + - type: input + id: runtime + attributes: + label: Node.js and npm versions + placeholder: Node.js 22.x; npm 10.x + validations: + required: true + - type: dropdown + id: operating-system + attributes: + label: Operating system + options: + - Linux + - macOS + - Windows + - Other + validations: + required: true + - type: dropdown + id: mode + attributes: + label: Execution mode + options: + - CLI + - GitHub Action + - Other + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Minimal sanitised reproduction + description: Use synthetic configuration and source where possible. Remove credentials, merchant data, private URLs, and secrets. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behaviour + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behaviour + validations: + required: true + - type: textarea + id: output + attributes: + label: Sanitised output + description: Optional. Remove private paths and any sensitive values. + validations: + required: false \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/compatibility_report.yml b/.github/ISSUE_TEMPLATE/compatibility_report.yml new file mode 100644 index 0000000..196385a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/compatibility_report.yml @@ -0,0 +1,53 @@ +name: Compatibility report +description: Report a version-specific Shopify or runtime compatibility issue +title: "compatibility: " +body: + - type: markdown + attributes: + value: "Use a minimal sanitised example. Do not include credentials, merchant/customer data, private source, or production secrets." + - type: input + id: tool-version + attributes: + label: Tool version + validations: + required: true + - type: input + id: api-version + attributes: + label: Shopify API version or runtime/framework version + description: Use N/A when this report is not version-specific. + validations: + required: true + - type: input + id: surface + attributes: + label: Affected Shopify surface or integration + validations: + required: true + - type: input + id: evidence + attributes: + label: Official Shopify documentation or release note + description: Link the source that describes the expected behaviour. + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Minimal sanitised reproduction + description: Include only the relevant config/source pattern. + validations: + required: true + - type: textarea + id: expected-observed + attributes: + label: Expected and observed behaviour + validations: + required: true + - type: textarea + id: false-positive + attributes: + label: Similar behaviour that should not be affected + description: Optional, but useful when proposing a static-analysis rule. + validations: + required: false \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 2bf709f..227421c 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -5,4 +5,4 @@ contact_links: about: Do not report suspected vulnerabilities or include secrets in a public issue. - name: Support and usage questions url: https://github.com/RexCode-Digital/shopify-scope-guard/blob/main/SUPPORT.md - about: Review the support guide before opening a usage question. + about: Use the support guide for safe reproductions and usage questions. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index 2f84a57..0000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -name: Feature request -about: Suggest a focused improvement to the tool -title: "[Feature]: " ---- - -## Problem or use case - -## Proposed behaviour - -## Shopify surface or documentation evidence (if applicable) - -Link current official Shopify documentation where the request depends on Shopify semantics. - -## Alternatives considered - -Do not include credentials, merchant/customer data, private source, or production configuration. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index a68e90c..fecd212 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,24 +1,41 @@ name: Feature request -description: Suggest a focused improvement to Scope Guard. +description: Describe a focused improvement and the developer problem it solves +title: "feature: " body: + - type: markdown + attributes: + value: "Do not include credentials, merchant/customer data, private source, or production secrets." - type: textarea id: problem attributes: - label: Problem - description: What developer problem would this solve? + label: Problem and use case + description: What task is difficult today, and who needs the change? validations: required: true - type: textarea - id: proposed-behavior + id: proposal attributes: - label: Proposed behavior - description: Describe the smallest useful change. + label: Proposed behaviour + description: Describe the smallest useful change and an example. validations: required: true + - type: input + id: evidence + attributes: + label: Official Shopify documentation or other evidence + description: Link an official source when the request depends on Shopify behaviour. + validations: + required: false - type: textarea - id: shopify-evidence + id: compatibility attributes: - label: Shopify evidence or source - description: If this concerns a scope or API surface, link the relevant official Shopify documentation. + label: Compatibility considerations + description: Note affected API versions, runtimes, frameworks, or existing workflows. validations: required: false + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + validations: + required: false \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 9cfe052..bc62a99 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,27 +1,30 @@ -## What changed? +## Summary - +## Motivation -## Why? +## Changes - +## Tests performed -## Tests +- [ ] Add the tests and checks actually run below. -- [ ] `npm test` -- [ ] `npm run lint` -- [ ] `npm run typecheck` -- [ ] `npm run build` -- [ ] `git diff --check` +## Compatibility + +## Security and privacy + +Do not include credentials, merchant/customer data, private source, or production secrets. ## Shopify source/evidence - +Link official Shopify documentation for Shopify-specific behaviour, or write N/A. -## Security/privacy impact +## Release impact - +State whether the change affects package behaviour, Action behaviour, documentation, or release version. -## Documentation impact +## Checklist - +- [ ] The change is focused and the docs/examples match the implementation. +- [ ] Relevant regression tests and checks are recorded above. +- [ ] Generated distributions are up to date where required. +- [ ] No sensitive or third-party material was added without permission/licence review. \ No newline at end of file diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8444f34..f51ae3c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,6 +1,7 @@ name: CI on: push: + branches: [main] pull_request: permissions: contents: read diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index c85f66b..5ec1ba7 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -1,6 +1,7 @@ name: CodeQL on: push: + branches: [main] pull_request: workflow_dispatch: schedule: diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 27d7fa1..fca2e4f 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -6,7 +6,7 @@ on: - cron: '17 3 * * 1' push: branches: [main] -permissions: read-all +permissions: {} jobs: analysis: permissions: diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 558c5bc..f9566c9 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,3 +1,5 @@ # Code of Conduct -Contributors are expected to be respectful, constructive, and inclusive. Harassment and discrimination are not tolerated. +Contributors and participants are expected to be respectful, constructive, and inclusive. Harassment, discrimination, doxxing, threats, and deliberate exposure of secrets or private customer data are not acceptable. + +Report conduct concerns privately to the project maintainer using the contact address listed on the [RexCode Digital organisation profile](https://github.com/RexCode-Digital#readme). Maintainers may remove content or restrict participation when necessary to keep the project safe. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a4346d3..1d37c45 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,33 +1,26 @@ -# Contributing +# Contributing to Shopify Scope Guard -Contributions are welcome around evidence-backed scope mappings, official Shopify documentation references, false-positive reduction, parser improvements, scanner hardening, and privacy-safe fixtures. +Contributions are welcome around evidence-backed Shopify scope mappings, API-version boundaries, conservative UNKNOWN handling, and privacy-safe fixtures. -## Contribution terms +This project is MIT licensed. You retain copyright in your contributions and confirm you have the right to submit them. Identify third-party code and assets with their applicable licences. -You retain copyright in your contributions. By submitting a contribution, you agree that it is provided under the same MIT licence that applies to this project. You confirm that you have the right to submit the contribution. Disclose any third-party code or assets and identify their applicable licences before including them. - -## Development setup - -Use Node.js 22 or newer, then install the locked dependencies: +Use Node.js 22 or newer. Install the locked dependencies and run the relevant checks before opening a pull request: ```sh npm ci npm test +npm run coverage npm run lint npm run typecheck npm run build +npm run package:smoke +npm run action:check +npm audit --omit=dev --audit-level=high +git diff --check ``` -Before opening a pull request, also run `npm run coverage`, `npm audit --omit=dev --audit-level=high`, and `git diff --check`. - -## Evidence and regression rules - -- Add a regression test for every bug or rule change. -- Link every new Shopify scope mapping to an official Shopify source. -- Record the evidence version and confidence honestly. -- Keep UNKNOWN distinct from NOT EVIDENCED; static analysis must not claim that a scope is unused. -- Use privacy-safe fixtures with no credentials, tokens, or merchant data. +Add a regression test for each behaviour change. Keep fixtures synthetic and sanitised. Link current official Shopify evidence for Shopify-specific rules or mappings, and include a negative case where static detection could otherwise produce a false positive. Keep output deterministic and preserve the product's uncertainty and privacy boundaries. -See the [open issues](https://github.com/RexCode-Digital/shopify-scope-guard/issues) for current opportunities. +The project follows a solo-maintainer review model. Use a focused pull request and record the checks actually run. Human approval is not a branch-protection requirement; automated checks remain required. Contributors are responsible for reviewing and understanding submitted changes. -These repositories use a solo-maintainer review model. Keep changes in pull requests and merge only after the required automated checks pass. CODEOWNERS may route review requests, but human approval is not a merge requirement. +Read the shared [RexCode Open Source standards](https://github.com/RexCode-Digital/.github/blob/main/docs/oss/standards.md). For security reports, use [SECURITY.md](SECURITY.md); for safe usage questions, use [SUPPORT.md](SUPPORT.md). \ No newline at end of file diff --git a/README.md b/README.md index b18e28d..9ceb536 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,43 @@ # Shopify Scope Guard -**Catch missing, redundant, and unproven Shopify access scopes before they become runtime or review problems.** +Compare requested Shopify app scopes with supported static evidence to review permission changes. + +**RexCode Open Source · Shopify developer tools** [![npm](https://img.shields.io/npm/v/shopify-scope-guard?logo=npm)](https://www.npmjs.com/package/shopify-scope-guard) -[![npm downloads](https://img.shields.io/npm/dm/shopify-scope-guard?logo=npm)](https://www.npmjs.com/package/shopify-scope-guard) [![CI](https://github.com/RexCode-Digital/shopify-scope-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/RexCode-Digital/shopify-scope-guard/actions/workflows/ci.yml) [![CodeQL](https://github.com/RexCode-Digital/shopify-scope-guard/actions/workflows/codeql.yml/badge.svg)](https://github.com/RexCode-Digital/shopify-scope-guard/actions/workflows/codeql.yml) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/RexCode-Digital/shopify-scope-guard/badge)](https://securityscorecards.dev/viewer/?uri=github.com/RexCode-Digital/shopify-scope-guard) -[![license](https://img.shields.io/github/license/RexCode-Digital/shopify-scope-guard)](LICENSE) - -Shopify Scope Guard is an offline, deterministic, read-only static analyzer for Shopify app repositories. It compares declared access scopes with supported static evidence from repository code and configuration, then reports missing, redundant, unproven, and unknown scope usage for review. - -**No Shopify credentials. No telemetry. No source upload. No Shopify API calls. No repository code execution.** +[![Node.js 22+](https://img.shields.io/badge/Node.js-22+-22B8B2?logo=nodedotjs&logoColor=white)](https://nodejs.org/) +[![MIT licence](https://img.shields.io/github/license/RexCode-Digital/shopify-scope-guard)](LICENSE) -> Unofficial open-source developer tooling. Not affiliated with, endorsed by, or certified by Shopify. +Scope Guard compares declared required and optional scopes with supported evidence in local Shopify app code. It reports missing, redundant and uncertain cases while keeping unsupported patterns visibly unknown. -Maintained by RexCode Digital Ltd. +## Features -Part of the **RexCode Shopify developer tools** suite. The CLI requires Node.js 22 or later; the GitHub Action uses Node.js 24. [Releases](https://github.com/RexCode-Digital/shopify-scope-guard/releases) · [npm](https://www.npmjs.com/package/shopify-scope-guard) · [Marketplace](https://github.com/marketplace/actions/shopify-scope-guard) +- Analyses supported Admin GraphQL operations and documented Shopify webhook evidence. +- Keeps classic webhook topics separate from Shopify Events. +- Distinguishes EVIDENCED, NOT EVIDENCED and UNKNOWN; UNKNOWN is not treated as unused. +- Supports human, JSON and SARIF output with versioned offline evidence. -## Quick start +## Install and run -Run a scan without installing anything globally: - -```bash -npx shopify-scope-guard audit -``` - -Or install it in a project: +Requires Node.js 22 or later. ```bash npm install --save-dev shopify-scope-guard -npx shopify-scope-guard audit -``` - -JSON output: - -```bash -npx shopify-scope-guard audit --format json +npx shopify-scope-guard audit --api-version 2026-10 ``` -SARIF output for code-scanning workflows: - -```bash -npx shopify-scope-guard audit --format sarif -``` - -## Why Scope Guard? - -Shopify app permissions can drift away from the code that actually uses Shopify APIs. Scope Guard gives reviewers a deterministic, evidence-backed view of that relationship without requiring store access or Shopify credentials. - -- **Evidence-backed** — maps supported Shopify API operations to documented access-scope requirements. -- **Offline by design** — ordinary scans require no Shopify credentials, store access, or network service. -- **Deterministic** — the same repository, configuration, and bundled evidence produce the same result. -- **Conservative** — UNKNOWN usage is reported for review and is never silently treated as unused. -- **Scope-aware** — detects missing scopes, required/optional mismatches, redundant read scopes, and unproven declarations. -- **CI-ready** — human, JSON, and SARIF output plus a bundled GitHub Action. -- **Privacy-first** — does not upload source or execute repository code. +The bundled evidence pack applies to Admin GraphQL API version 2026-10. Unsupported versions remain unknown. See [supported patterns](docs/supported-patterns.md) and the [CLI guide](docs/cli.md). ## GitHub Action -A minimal pull-request gate: +Pin the released v0.4.0 commit: ```yaml -name: Shopify Scope Guard - -on: - pull_request: - +name: Review Shopify app scopes +on: [pull_request] permissions: contents: read @@ -76,196 +46,66 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - uses: RexCode-Digital/shopify-scope-guard@da4d786f22049e2e96728918ebaaa1f362898d84 # v0.4.0 with: + api-version: 2026-10 + format: human fail-on: high ``` -For high-assurance workflows, pin third-party Actions to reviewed immutable commit SHAs. `v0.4.0` is the current release and the example uses its resolved commit SHA. - -See the [GitHub Action guide](docs/github-action.md). - -### Action inputs - -| Input | Purpose | Default | -| --- | --- | --- | -| `path` | Repository path to scan | `.` | -| `config` | Shopify app TOML path | auto-discovered | -| `api-version` | Admin GraphQL API version used for evidence applicability | `2026-10` | -| `fail-on` | Minimum finding severity that fails the job | `high` | -| `format` | Output format: `human`, `json`, or `sarif` | `human` | -| `show-unmapped` | Show detailed unmapped patterns in human output | `false` | - -### Action outputs - -`outcome`, `finding-count`, `high-count`, `medium-count`, `low-count`, `unknown-count`, `missing-scope-count`, `redundant-scope-count`, `api-version`, `api-version-status`, `evidence-version`, `evidence-applicable`, and `report`. - -The `report` output is a JSON report file in the runner temporary directory. SARIF format also writes `scope-guard.sarif` there. `outcome` reflects the selected `fail-on` policy. - -The pinned v0.4.0 release supports the `api-version` input, version and evidence outputs, and the `--api-version` CLI option. Unsupported API versions, surfaces, and topics remain UNKNOWN. - -The Action is bundled and runs on GitHub's `node24` JavaScript Action runtime. Consumer jobs do not install Scope Guard dependencies separately. - -## What it catches today - -The current evidence pack is intentionally focused on high-confidence Shopify API and app-configuration mappings. - -| Area | Detection | -| --- | --- | -| Missing scopes | Supported operations whose required scope is not declared | -| Required/optional mismatches | Evidence requiring a scope declared as optional | -| Redundant scopes | Read scopes already implied by declared write scopes | -| Unproven declarations | Declared scopes with no supported usage evidenced | -| Unknown usage | Shopify-related code that cannot be safely mapped to supported evidence | -| Admin GraphQL | Supported query and mutation operations matched against documented scope requirements | -| Classic webhooks | `products/update` and `orders/create` topic requirements in `[[webhooks.subscriptions]]` | -| Shopify app configuration | Required and optional scopes plus versioned webhook and 2026-10 Events topic requirements in `shopify.app*.toml` | -| SARIF | SARIF 2.1.0 output for code-scanning workflows | - -Current high-confidence evidence areas include products, collections, orders, customers, inventory, locations, billing fees, markets, themes, files, metaobjects, cart transforms, analytics annotations, reports, ShopifyQL, rollouts, and documented Events topic scopes. - -See the [supported patterns](docs/supported-patterns.md) and [rule reference](docs/rule-reference.md). - -## Evidence model - -Scope Guard deliberately separates evidence from certainty. - -- **EVIDENCED** — a supported operation has strong static evidence for the scope. -- **NOT EVIDENCED** — no supported usage requiring the scope was evidenced. This does **not** prove that the scope is unused. -- **UNKNOWN** — Shopify-related code could not be safely mapped to supported evidence. UNKNOWN is deliberately conservative and is never classified as unused. +Inputs include `path`, `config`, `api-version`, `fail-on`, `format` and `show-unmapped`. Outputs report the policy outcome, finding and uncertainty counts, selected API version, evidence applicability, scope counts and webhook evidence counts. See [action.yml](action.yml). -The bundled high-confidence evidence pack is versioned against Shopify API `2026-10`. For classic webhooks, EVIDENCED means that a required scope alternative is declared (including a documented write-to-read implication); an optional declaration is NOT EVIDENCED because merchants can decline it. Unmapped topics and unsupported webhook API versions remain UNKNOWN. Evidence is based on documented Shopify access-scope relationships and supported static patterns, not live store permissions. - -See the [evidence model](docs/evidence-model.md). - -## CLI +## Example output ```text -shopify-scope-guard audit [--api-version YYYY-MM] [--format human|json|sarif] [--fail-on ...] -shopify-scope-guard rules -shopify-scope-guard explain SG-SCOPE-001 -shopify-scope-guard --version -``` - -Examples: - -```bash -# Human-readable scan -npx shopify-scope-guard audit - -# Machine-readable output -npx shopify-scope-guard audit --format json - -# SARIF for code-scanning workflows -npx shopify-scope-guard audit --format sarif - -# Inspect scope evidence for the current release candidate -npx shopify-scope-guard audit --api-version 2027-01 --format json - -# Fail when medium-or-higher findings are present -npx shopify-scope-guard audit --fail-on medium - -# Inspect the bundled evidence -npx shopify-scope-guard rules -npx shopify-scope-guard explain SG-SCOPE-001 +Shopify Scope Guard +Admin GraphQL target: 2026-10 (stable); bundled evidence: 2026-10 (applicable) +Findings: 1 + +HIGH SG-SCOPE-001 — write_products + The productCreate operation requires one of write_products, and none is declared as required. + Evidence: productCreate mutation + Source: https://shopify.dev/docs/api/admin-graphql/2026-10/mutations/productcreate + Location: app.ts:2 + Recommendation: Declare write_products as required, or make the code path conditional on an optional-scope request. ``` -The `--fail-on` option accepts `none`, `low`, `medium`, or `high`. A scan exits `1` when a finding meets the selected threshold, `0` when policy passes, and `2` for usage or scanner errors. - -Reports identify the selected version's status, latest stable version, current release candidate, and whether the bundled evidence applies. The current pack is verified for `2026-10`; selecting `2027-01` or another version outside that pack leaves Admin operations UNKNOWN rather than applying mismatched rules. - -See the [CLI reference](docs/cli.md). - -## Configuration - -Scope Guard reads Shopify app TOML configuration from the repository. It supports `[access_scopes]` `scopes` and `optional_scopes` values. Classic webhook `topics` are mapped only for the two entries in the offline registry and when `[webhooks].api_version` is `2026-10`; Shopify Events topics are mapped only when `[events].api_version` is `2026-10`. Unsupported topics and API versions remain UNKNOWN. These checks cover topic-level requirements only: they do not infer extra scopes from webhook payload filters or Events triggers and custom queries. Destinations, filters, and query text are never included in findings. - -The CLI supports: - -- `--path` to select the repository root -- `--config` to select a Shopify app TOML path relative to the scan root - -Auto-discovery prefers `shopify.app.toml`, otherwise a single named root configuration. Missing or ambiguous configurations fail explicitly. For nested apps use `audit --path apps/my-app --config shopify.app.production.toml`. Scans are bounded to 2,000 code files and 1 MiB per file; symlinks and bounded-out files appear in `skipped` and require manual review. +This finding comes from the repository's synthetic `examples/02-missing-scope` fixture. -Local fragments, inline fragments, and aliases are supported. Admin, Storefront, and Customer Account operations are classified per GraphQL document when a nearby client signal is clear. Storefront operations stay outside Admin scope evidence; Customer Account and ambiguous operations are reported as UNKNOWN. Standalone `.graphql` documents without client context are UNKNOWN until their API surface can be established. +## Supported capabilities and evidence -This change raises the CLI minimum to Node.js 22; Node.js 20 is no longer supported. The GraphQL parser dependency is GraphQL.js 17.0.2, which supports Node.js 22 and 24. +Scope Guard supports a bounded set of Admin GraphQL operations and versioned evidence for classic webhooks and Shopify Events. Optional scopes are not treated as granted. Unknown topics, unsupported API versions, ambiguous GraphQL clients and unmapped operations remain UNKNOWN. Findings do not include webhook destinations, filters or query text. -## Security and privacy +See the [evidence model](docs/evidence-model.md), [scope model](docs/scope-model.md), and [rules](docs/rule-reference.md). -Scope Guard treats repository content as untrusted input and is intentionally narrow. +## Limitations and privacy -It: +The tool does not inspect merchant grants, staff permissions, protected-customer-data approval, runtime-generated operations or every custom wrapper. NOT EVIDENCED does not prove a scope is unused. It does not call Shopify APIs, execute repository code, require credentials or upload source. Review UNKNOWN and skipped files manually. -- does not execute scanned repository code -- does not call Shopify APIs during ordinary scans -- does not require Shopify credentials -- does not upload source or collect telemetry -- uses bounded, supported static analysis -- keeps analysis offline by default +## Documentation -See [SECURITY.md](SECURITY.md), [SUPPORT.md](SUPPORT.md), and the [security model](docs/security.md). +- [Getting started](docs/cli.md) +- [CLI guide](docs/cli.md) +- [Supported patterns](docs/supported-patterns.md) +- [Evidence model](docs/evidence-model.md) +- [Limitations](docs/limitations.md) -## Non-goals +## Related RexCode OSS tools -Scope Guard does **not**: +- [ChangeGuard](https://github.com/RexCode-Digital/shopify-app-changeguard) reviews app configuration changes. +- [Shopify Upgrade Guard](https://github.com/RexCode-Digital/shopify-upgrade-guard) checks API and platform migration risks. +- [Shopify App Review Guard](https://github.com/RexCode-Digital/shopify-app-review-guard) checks App Store and production-readiness evidence. -- inspect the scopes actually granted to a merchant -- inspect staff permissions or protected-customer-data approval -- see every runtime-generated GraphQL operation -- understand every custom wrapper or external service -- guarantee that a scope is unused -- replace Shopify schema validation or Shopify App Review -- provide complete coverage of every Shopify API surface +See the [combined workflow](https://github.com/RexCode-Digital/shopify-app-changeguard/blob/main/docs/ecosystem-workflow.md) to run all four published Actions. -UNKNOWN findings require manual review. +## Contributing and support -See [Limitations](docs/limitations.md). +Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [RexCode Open Source standards](https://github.com/RexCode-Digital/.github/blob/main/docs/oss/standards.md). For help, use [SUPPORT.md](SUPPORT.md) or the [issue tracker](https://github.com/RexCode-Digital/shopify-scope-guard/issues). -## Related Shopify developer tools +## Security -Building or maintaining Shopify apps? +Use [SECURITY.md](SECURITY.md) for private vulnerability reporting. Never post credentials, private source or merchant data in a public issue. -- **[ChangeGuard](https://github.com/RexCode-Digital/shopify-app-changeguard)** — Review meaningful Shopify app configuration changes before they reach production. -- **[Shopify Upgrade Guard](https://github.com/RexCode-Digital/shopify-upgrade-guard)** — Catch documented Shopify API and platform upgrade risks before production migrations. -- **[Shopify App Review Guard](https://github.com/RexCode-Digital/shopify-app-review-guard)** — Run deterministic preflight checks for Shopify App Store and production readiness. - -See the [coordinated workflow example](https://github.com/RexCode-Digital/shopify-app-changeguard/blob/main/docs/ecosystem-workflow.md) to run all four published Actions in one pull-request workflow. - -These are independent open-source tools and are not affiliated with Shopify. - -## Contributing - -Contributions are welcome, especially around evidence-backed scope mappings, official Shopify documentation references, false-positive reduction, parser improvements, scanner hardening, and privacy-safe fixtures. - -A Shopify-specific rule should include: - -1. an official Shopify evidence source -2. the affected API/version where relevant -3. bounded deterministic detection -4. a positive regression test -5. a false-positive or unchanged case where appropriate -6. honest evidence confidence - -Start with [CONTRIBUTING.md](CONTRIBUTING.md) or browse the [open issues](https://github.com/RexCode-Digital/shopify-scope-guard/issues). - -## Roadmap - -Current priorities include additional verified Shopify scope coverage, additional Admin API surfaces without mixing evidence confidence levels, better alternative-scope modeling, explicit API-version-aware evidence beyond the bundled snapshot, false-positive reduction, improved UNKNOWN handling, and privacy-safe consumer/action fixtures. - -See [ROADMAP.md](ROADMAP.md). - -## License - -MIT — see [LICENSE](LICENSE). - -## Immutable SHA usage - -The Action example pins the reviewed v0.4.0 release commit. Verify the release reference with: - -```bash -git fetch --tags origin && git rev-parse 'v0.4.0^{commit}' -``` +## Licence and affiliation -Published patch tags are retained; existing minor aliases are movable. A reviewed full commit SHA is the immutable execution reference. Scope Guard 0.4.0 includes the webhook evidence described above for the supported API version; unsupported topics and versions remain UNKNOWN. +MIT licensed. Shopify's names and marks belong to Shopify. Scope Guard is independent open-source software, not affiliated with, endorsed by, or certified by Shopify. \ No newline at end of file diff --git a/SECURITY.md b/SECURITY.md index 892178b..6174af0 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,13 +1,17 @@ # Security policy -## Reporting a vulnerability +Shopify Scope Guard is an offline developer tool. An ordinary scan reads repository files; it does not require Shopify credentials, call Shopify APIs, or upload scanned source. -Report suspected vulnerabilities privately through [GitHub private vulnerability reporting](https://github.com/RexCode-Digital/shopify-scope-guard/security/advisories/new). Include the exact version, affected command, and a minimal sanitized reproduction. Do not include Shopify credentials, access tokens, private keys, merchant data, or private source. +## Supported versions -Please coordinate public disclosure with the maintainer while the report is investigated and a fix is prepared. Response time depends on maintainer availability; no response-time guarantee is offered. +The latest published release and the default branch receive security fixes. Upgrade to the latest release before reporting an issue. -## Supported versions and security model +## Report a vulnerability -The latest published package and `main` receive security attention. Upgrade to the latest patch before reporting an issue. +Use [GitHub private vulnerability reporting](https://github.com/RexCode-Digital/shopify-scope-guard/security/advisories/new). Include the affected version, command or Action, impact, and a minimal sanitised reproduction. Do not include credentials, access tokens, private keys, merchant/customer data, private source, or production configuration. -Ordinary scans read local files, do not execute scanned repository code, contact Shopify, or upload source. Static analysis does not certify security or replace runtime testing. Symlink checks and file-size limits do not sandbox a filesystem that changes concurrently during scanning. +Please coordinate public disclosure with the maintainer while the report is assessed and a fix is prepared. Response time depends on maintainer availability; no response-time guarantee is offered. + +## Security boundaries + +Static analysis is bounded and cannot prove runtime behaviour, complete security, Shopify compliance, or App Store approval. Review each product's documentation for its specific evidence limits. \ No newline at end of file diff --git a/SUPPORT.md b/SUPPORT.md index 9d10872..9bdfd6a 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,11 +1,5 @@ # Support -Open a [GitHub issue](https://github.com/RexCode-Digital/shopify-scope-guard/issues) for reproducible bugs, documentation problems, and feature requests. Include: +Use [GitHub Issues](https://github.com/RexCode-Digital/shopify-scope-guard/issues) for reproducible bugs, documentation problems, and focused feature requests. Include the Shopify Scope Guard version, command or Action configuration, Node.js/npm and operating system versions, a minimal sanitised reproduction, and expected and actual behaviour. For scope reports include the configured scopes, selected Admin GraphQL API version, and supported operation or webhook surface. -- Scope Guard version and command -- operating system and Node.js version -- a minimal sanitized reproduction -- expected and actual behaviour -- sanitized human, JSON, or SARIF output - -Never include Shopify tokens, credentials, private keys, customer information, or merchant data. For suspected security vulnerabilities, follow [SECURITY.md](SECURITY.md) instead of opening a public issue. +Remove credentials, tokens, merchant/customer data, private source, private URLs, and production secrets. Do not post suspected vulnerabilities publicly; follow [SECURITY.md](SECURITY.md) for private reporting. \ No newline at end of file diff --git a/assets/social-preview.png b/assets/social-preview.png new file mode 100644 index 0000000..4b08cdb Binary files /dev/null and b/assets/social-preview.png differ diff --git a/assets/social-preview.svg b/assets/social-preview.svg new file mode 100644 index 0000000..4b13d73 --- /dev/null +++ b/assets/social-preview.svg @@ -0,0 +1,19 @@ + +Shopify Scope Guard — RexCode Open SourceStatic evidence for requested Shopify access scopes. + + + + + + + +REXCODE OPEN SOURCE +SHOPIFY DEVELOPER TOOLS +Shopify Scope Guard +Static evidence forrequested Shopify access scopes. + +RexCode Digital Ltd · independent open-source software + + + + \ No newline at end of file diff --git a/package.json b/package.json index 0a54aa6..4a5792e 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,7 @@ ], "scripts": { "test": "node --test", - "coverage": "c8 --include 'src/**' --reporter=text --reporter=json-summary node --test", + "coverage": "c8 --include 'src/**' --reporter=text --reporter=json-summary --check-coverage --lines 90 --statements 90 --functions 90 --branches 80 node --test", "lint": "node scripts/check-source.mjs", "typecheck": "node --check src/analyzer/index.js", "build": "node scripts/build-action.mjs",