feat: Initial release

.github/workflows/actions_release.yml

@@ -0,0 +1,22 @@
+name: Release GitHub Actions
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag for the release"
+        required: true
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    permissions:
+      actions: read
+      id-token: write
+      contents: write
+
+    uses: step-security/reusable-workflows/.github/workflows/actions_release.yaml@v1
+    with:
+      tag: "${{ github.event.inputs.tag }}"

.github/workflows/auto_cherry_pick.yml

@@ -0,0 +1,32 @@
+name: Auto Cherry-Pick from Upstream
+
+on:
+  workflow_dispatch:
+    inputs:
+      base_branch:
+        description: "Base branch to create the PR against"
+        required: true
+        default: "main"
+      mode:
+        description: "Run mode: cherry-pick or verify"
+        required: false
+        default: "cherry-pick"
+
+  pull_request:
+    types: [opened, synchronize, labeled]
+
+permissions:
+  contents: write
+  pull-requests: write
+  packages: read
+  issues: write
+
+jobs:
+  cherry-pick:
+    if: github.event_name == 'workflow_dispatch' || contains(fromJson(toJson(github.event.pull_request.labels)).*.name, 'review-required')
+    uses: step-security/reusable-workflows/.github/workflows/auto_cherry_pick.yaml@v1
+    with:
+      original-owner: "anishathalye"
+      repo-name: "proof-html"
+      base_branch: ${{ inputs.base_branch }}
+      mode: ${{ github.event_name == 'pull_request' && 'verify' || inputs.mode }}

.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+  pull_request:
+
+jobs:
+  fmt:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+      - run: gem install rufo
+      - run: rufo -c .

.github/workflows/docker.yml

@@ -0,0 +1,55 @@
+name: Publish docker image
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: 'Tag to release'
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        if: startsWith(github.event.inputs.release_tag, 'v')
+        steps:
+        - name: Harden the runner (Audit all outbound calls)
+          uses: step-security/harden-runner@v2
+          with:
+            egress-policy: audit
+
+        - name: Checkout
+          uses: actions/checkout@v5
+        - name: Validate tag format
+          run: |
+            TAG=${{ github.event.inputs.release_tag }}
+            if ! echo "$TAG" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
+              echo "❌ Invalid tag format: $TAG"
+              exit 1
+            fi
+            echo "✅ Valid semver tag: $TAG"
+        - name: Log in to GitHub Container Registry
+          uses: docker/login-action@v3
+          with:
+            registry: ghcr.io
+            username: ${{ github.actor }}
+            password: ${{ secrets.GITHUB_TOKEN }}
+
+        - name: Set up QEMU for ARM builds
+          uses: docker/setup-qemu-action@v3
+
+        - name: Set up Docker Buildx
+          uses: docker/setup-buildx-action@v3
+
+        - name: Build and push Docker image
+          uses: docker/build-push-action@v6
+          with:
+            context: .
+            push: true
+            platforms: linux/amd64,linux/arm64
+            tags: |
+              ghcr.io/${{ github.repository }}:${{ github.event.inputs.release_tag }}

Dockerfile

@@ -0,0 +1,26 @@
+FROM alpine:3.22 AS base
+
+RUN apk --no-cache add openjdk21
+
+FROM base AS build-vnu
+
+RUN apk add git python3
+
+RUN git clone -n https://github.com/validator/validator.git \
+    && cd validator \
+    && git checkout 84a1b28ff4cc28b7e9a31784688dbee6366b3467 \
+    && JAVA_HOME=/usr/lib/jvm/java-21-openjdk python checker.py update-shallow dldeps build jar
+
+FROM base
+
+RUN apk --no-cache add build-base linux-headers ruby-dev
+RUN apk --no-cache add curl
+RUN gem install html-proofer -v 5.0.10
+
+RUN apk --no-cache add bash
+
+COPY --from=build-vnu /validator/build/dist/vnu.jar /bin/vnu.jar
+
+COPY entrypoint.sh proof-html.rb /
+
+ENTRYPOINT ["/entrypoint.sh"]

LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) Anish Athalye ([email protected])
+Copyright (c) 2025 StepSecurity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1 +1,172 @@
-# proof-html
+# proof-html
+
+proof-html is a [GitHub Action](https://github.com/features/actions) to validate HTML and CSS using the [Nu HTML Validator](https://github.com/validator/validator) and check links, images, and more using [HTMLProofer](https://github.com/gjtorikian/html-proofer).
+
+## Usage
+
+```yaml
+- uses: step-security/proof-html@v2
+  with:
+    directory: ./site
+```
+
+See below for a [full example](#full-example).
+
+## Options
+
+| Name | Description | Default |
+| --- | --- | --- |
+| `directory` | The directory to scan | (required) |
+| `check_html` | Validate HTML | true |
+| `check_css` | Validate CSS | true |
+| `validator_ignore` | Regex of HTML/CSS validator errors to ignore | (empty) |
+| `check_external_hash` | Check whether external anchors exist | true |
+| `check_favicon` | Check whether favicons are valid | true |
+| `check_opengraph` | Check images and URLs in Open Graph metadata | true |
+| `ignore_empty_alt` | Allow images with empty alt tags | false |
+| `ignore_missing_alt` | Allow images with missing alt tags | false |
+| `allow_missing_href` | Allow anchors with missing href tags | false |
+| `enforce_https` | Require that links use HTTPS | true |
+| `swap_urls` | JSON-encoded map of URL rewrite rules | (empty) |
+| `disable_external` | Disables the external link checker | false |
+| `ignore_url` | Newline-separated list of URLs to ignore | (empty) |
+| `ignore_url_re` | Newline-separated list of URL regexes to ignore | (empty) |
+| `connect_timeout` | HTTP connection timeout | 30 |
+| `tokens` | JSON-encoded map of domains to authorization tokens | (empty) |
+| `max_concurrency` | Maximum number of concurrent requests | 50 |
+| `timeout` | HTTP request timeout | 120 |
+| `retries` | Number of times to retry checking links | 3 |
+
+Most of the options correspond directly to [configuration options for
+HTMLProofer](https://github.com/gjtorikian/html-proofer#configuration).
+
+**validator_ignore**
+
+`validator_ignore` is a _regex pattern_ of HTML/CSS validation errors to
+ignore, corresponding to the [`--filterpattern`
+option](https://github.com/validator/validator?tab=readme-ov-file#--filterpattern-regexp)
+of the Nu validator.
+
+For example, you might see the following errors:
+
+```
+"file:/build/index.html":0.1-0.6: error: Start tag seen without seeing a doctype first. Expected “<!DOCTYPE html>”.
+"file:/build/index.html":1.9-1.15: error: Element “head” is missing a required instance of child element “title”.
+"file:/build/style.css":2.8-2.8: error: CSS: “foo”: Property “foo” doesn't exist.
+```
+
+If you wanted to ignore the first error, and you wanted to ignore all
+non-existent properties in CSS, you could set the `validator_ignore` argument
+to:
+
+```
+Start tag seen without seeing a doctype first.*|CSS: “.*”: Property “.*” doesn't exist.
+```
+
+**tokens**
+
+`tokens` is a _JSON-encoded_ map of domains to authorization tokens. So it's
+"doubly encoded": the workflow file is written in YAML and `tokens` is a string
+(not a map!), a JSON encoding of the data. This option can be used to provide
+bearer tokens to use in certain scenarios, which is useful for e.g. avoiding
+rate limiting. Tokens are only sent to the specified websites. Note that
+domains must not have a trailing slash. Here is an example of an encoding of
+tokens:
+
+```yaml
+tokens: |
+  {"https://github.com": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+   "https://twitter.com": "yyyyyyyyyyyyyyyyyyyyyyy"}
+```
+
+You can also see the full example below for how to pass on the `GITHUB_TOKEN`
+supplied by the workflow runner.
+
+**swap_urls**
+
+`swap_urls` is a _JSON-encoded_ map, mapping regexes to strings. This can be
+useful to strip a base path for an internal domain. For example:
+
+```yaml
+swap_urls: |
+  {"^https:\\/\\/example\\.com\\/": "/"}
+```
+
+You can also use capture groups and back-references here. For example, to
+ignore checking hashes for GitHub URLs (like
+`https://github.com/step-security/proof-html#options`), you can use:
+
+```yaml
+swap_urls: |
+  {"^(https:\\/\\/github\\.com\\/.*)#.*$": "\\1"}
+```
+
+## Full Example
+
+This is the entire `.github/workflows/build.yml` file for a GitHub Pages /
+[Jekyll](https://jekyllrb.com/docs/github-pages/) site.
+
+```yaml
+name: CI
+on:
+  push:
+  schedule:
+    - cron: '0 8 * * 6'
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-ruby@v1
+        with:
+          ruby-version: 2.7.x
+      - uses: actions/cache@v4
+        with:
+          path: vendor/bundle
+          key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-gems-
+      - run: |
+          bundle config path vendor/bundle
+          bundle install --jobs 4 --retry 3
+      - run: bundle exec jekyll build
+      - uses: step-security/proof-html@v2
+        with:
+          directory: ./_site
+          enforce_https: false
+          tokens: |
+            {"https://github.com": "${{ secrets.GITHUB_TOKEN }}"}
+          ignore_url: |
+            http://www.example.com/
+            https://en.wikipedia.org/wiki/Main_Page
+          ignore_url_re: |
+            ^https://twitter.com/
+```
+
+## Running locally
+
+You can build the Docker container locally with `docker build . -t proof-html`.
+
+The GitHub Action is set up to pass arguments as strings through environment
+variables, where an argument like `ignore_url` is passed as `INPUT_IGNORE_URL`
+(capitalize and prepend `INPUT_`) to the Docker container, so you will need to
+do this translation yourself if you're running the Docker container locally.
+You can mount a local directory in the Docker container with the `-v` argument
+and pass the directory name as the `INPUT_DIRECTORY` argument. For example, if
+you compiled a site into the `build` directory, you can run:
+
+```bash
+docker run --rm \
+    -e INPUT_DIRECTORY=build \
+    -v "${PWD}/build:/build" \
+    proof-html:latest
+```
+
+You can pass additional arguments as additional environment variables, e.g.
+`-e INPUT_FORCE_HTTPS=0` or
+`-e INPUT_TOKENS='{"https://github.com": "your-token-here"}'`.
+
+## License
+
+Copyright (c) Anish Athalye. Copyright (c) StepSecurity. Released under the MIT License. See
+[LICENSE](LICENSE) for details.

SECURITY.md

@@ -0,0 +1,5 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please report security vulnerabilities to [email protected]