pre-commit

Wire OAuthLint into the pre-commit framework so every commit is scanned for OAuth / OIDC / JWT anti-patterns, but only across the files that commit actually touches, not your whole tree.

Quick usage

Add OAuthLint to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/Auspeo/oauthlint
    rev: oauthlint@0.7.0
    hooks:
      - id: oauthlint

Pin rev to a published release tag (the hook installs that exact version); point it at main only to track unreleased changes.

Then install the hook and you’re done:

pre-commit install

From now on git commit runs OAuthLint against the staged source files. The hook reports every finding but does not block the commit by default. Add gating yourself (see Fail the commit below) when you’re ready to enforce.

Prerequisites

The hook needs one thing on the machine running the commit:

Node.js (≥ 20). OAuthLint is published as the oauthlint npm package. The hook is declared language: node, so pre-commit creates an isolated Node environment, installs the pinned oauthlint package into it (via additional_dependencies), and runs its oauthlint bin. You don’t add oauthlint to your project’s package.json. But pre-commit still needs a Node toolchain available to build that environment.

The scan engine takes care of itself: on the first commit the CLI downloads and checksum-verifies a small pinned scan engine (~41 MB, one time, cached), reusing an installed opengrep or semgrep if one is already on PATH. If the engine cannot be obtained (offline on the very first run with nothing installed), the scan exits 127 and your commit fails with a clear message rather than passing silently.

If your team can’t guarantee Node on every contributor’s machine, gate in CI with the GitHub Action instead. It’s Docker-based and needs no local toolchain.

How it runs only on staged files

pre-commit passes the staged files to the hook as positional arguments, and the hook runs oauthlint scan <file> <file> … against exactly that list. So a commit that only touches src/auth.ts scans src/auth.ts, not the rest of the repository. That keeps the hook fast enough to sit in the commit path.

The hook is scoped via types_or to the source extensions OAuthLint understands (.js, .jsx, .ts, .tsx, .py, .go, .java, .rs), so a commit that only changes Markdown, lockfiles or images skips the scan entirely. When no staged file matches, pre-commit doesn’t run the hook at all.

Fail the commit on real issues

By default the hook reports findings but stays out of your way. To block commits on findings at or above a severity, pass --fail-on through args:

repos:
  - repo: https://github.com/Auspeo/oauthlint
    rev: oauthlint@0.7.0
    hooks:
      - id: oauthlint
        args: [--fail-on, HIGH]

Any flag the CLI accepts can go in args the same way. For example, [--severity, MEDIUM, --fail-on, HIGH] surfaces MEDIUM+ in the output but only blocks on HIGH+. See the CLI reference for the full list and the exit codes the hook honours.

Run it on demand

The hook only fires on staged files during a commit. To scan everything once, which is handy right after you add the hook, run:

pre-commit run oauthlint --all-files

Keeping it current

rev pins the OAuthLint release the hook installs. Bump it with:

pre-commit autoupdate --repo https://github.com/Auspeo/oauthlint