armasec-lite 0.1.3__tar.gz

armasec_lite-0.1.3/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  UV_VERSION: "0.10.3"
+
+jobs:
+  check:
+    name: lint · test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: '3.12'
+          enable-cache: true
+
+      # The runner image ships no `just`. The official installer needs no marketplace
+      # action or version pin beyond the script's own TLS pin.
+      - name: Install just
+        run: curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
+
+      - name: Install workspace
+        run: uv sync --all-groups
+
+      - name: Lint
+        run: just lint
+
+      - name: Test
+        run: just test

armasec_lite-0.1.3/.github/workflows/deploy-docs.yml

@@ -0,0 +1,140 @@
+# Deploy the armasec-lite docs as a spoke site under /developer/armasec-lite/ on
+# docs.vantagecompute.ai (S3 + CloudFront).
+#
+# Auth is handled at the edge by the Lambda@Edge Keycloak gateway on all of /developer/*,
+# so there is no per-spoke auth configuration here and the site carries no login of its
+# own.
+#
+# Required repo variables:
+#   DOCS_BUCKET               S3 bucket name (shared with vantage-docs)
+#   DOCS_CF_DISTRIBUTION_ID   CloudFront distribution ID
+#
+# Required repo secrets:
+#   DOCS_SPOKE_ROLE_ARN       vantage-docs-spoke-armasec-lite, scoped to
+#                             developer/armasec-lite/*. Created by the vantage-docs hub
+#                             stack from its own spokes list, so there is no infrastructure
+#                             to deploy from here -- adding this repo to that list is what
+#                             brings the role into existence.
+
+name: Deploy docs (spoke)
+
+on:
+  push:
+    tags:
+      # Only a plain vX.Y.Z release publishes the docs. `v*` also matched a
+      # pre-release like v1.2.3rc1 and anything else beginning with v, so a release
+      # candidate silently replaced the published site. GitHub filter patterns are
+      # glob-like rather than regular expressions: `.` is literal and `+` means one
+      # or more of the preceding character, so this matches v1.2.3 and v10.20.30 and
+      # rejects v1.2.3rc1, v1.2 and vfoo.
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: read
+
+concurrency:
+  group: docs-spoke
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      # The pydoc plugin comes from npm, so there is no submodule to check out and no
+      # transport rewriting to do. It used to be vendored as a git submodule whose
+      # .gitmodules recorded an SSH URL that a runner has no key for.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      # The API reference is generated from docstrings by the pydoc plugin, which parses
+      # the source with `ast` and never imports it. So this needs an interpreter able to
+      # parse the project's syntax, but deliberately not its dependencies or its
+      # virtualenv -- which is why there is no `uv sync` here. armasec-lite requires
+      # Python 3.12+, so 3.12 is enough.
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: docusaurus/package-lock.json
+
+      - name: Install docs dependencies
+        working-directory: docusaurus
+        run: npm ci
+
+      - name: Build docs
+        working-directory: docusaurus
+        run: npm run build
+
+      # The plugin fails the build when introspection fails outright, and when every
+      # requested module documents nothing. This catches the case neither covers: a partial
+      # generation, where some modules landed and others silently did not.
+      #
+      # Counts against the module list in the config rather than a list repeated here, so
+      # a module added to the site cannot be forgotten in the check. This site has a
+      # single plugin instance, so `instances` is always 1 and accounts for the one
+      # generated index.md that is not itself a module page.
+      - name: Verify the API reference is complete
+        working-directory: docusaurus
+        run: |
+          declared=$(grep -cE "^\s+\{module: " docusaurus.config.ts)
+          instances=$(grep -cE "^\s+id: '" docusaurus.config.ts)
+          generated=$(( $(find docs/api-reference -mindepth 1 -name '*.md' | wc -l) - instances ))
+
+          if [ "$generated" -ne "$declared" ]; then
+            echo "API reference is incomplete: $declared modules declared, $generated pages generated."
+            echo "Likely cause: a module was renamed or moved without updating the plugin's"
+            echo "module list in docusaurus/docusaurus.config.ts."
+            exit 1
+          fi
+
+          echo "API reference OK: $generated pages for $declared declared modules"
+
+      # The benchmark pages are generated by npm's prebuild hook from the committed result
+      # files, one page per run plus a summary, and are not committed. The generator raises
+      # on a missing or malformed result file, so a partial results tree already fails the
+      # build. This catches the remaining case: a run directory that produced no page.
+      #
+      # Counted against the results tree rather than a number repeated here, so committing
+      # a new run cannot be forgotten in the check.
+      - name: Verify the benchmark pages are complete
+        working-directory: docusaurus
+        run: |
+          committed=$(find ../legacy_comparison_compose/results -mindepth 2 -maxdepth 2 -type d | wc -l)
+          pages=$(find docs/benchmarks -name '*.mdx' | wc -l)
+
+          if [ "$pages" -ne "$(( committed + 1 ))" ]; then
+            echo "Benchmark pages are incomplete: $committed runs committed, $pages pages generated."
+            echo "Expected one page per committed run, plus one summary page."
+            exit 1
+          fi
+
+          echo "Benchmark pages OK: $pages pages for $committed committed runs"
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@cbe3b392738ccf3f987d68400dafcf4b0624a56c # v6.2.4
+        with:
+          role-to-assume: ${{ secrets.DOCS_SPOKE_ROLE_ARN }}
+          aws-region: us-east-1
+
+      # --delete is safe here and only here: the hub excludes every spoke listed in
+      # .developer-subsites from its own sync, so this subtree is owned by this repo alone.
+      - name: Sync to S3
+        run: |
+          aws s3 sync docusaurus/build/ "s3://${{ vars.DOCS_BUCKET }}/developer/armasec-lite/" --delete
+
+      - name: Invalidate CloudFront
+        env:
+          DOCS_CF_DISTRIBUTION_ID: ${{ vars.DOCS_CF_DISTRIBUTION_ID }}
+        run: |
+          if [ -z "${DOCS_CF_DISTRIBUTION_ID}" ]; then
+            echo "DOCS_CF_DISTRIBUTION_ID is not set; skipping CloudFront invalidation."
+            exit 0
+          fi
+          aws cloudfront create-invalidation \
+            --distribution-id "${DOCS_CF_DISTRIBUTION_ID}" \
+            --paths "/developer/armasec-lite/*"

armasec_lite-0.1.3/.github/workflows/release.yml

@@ -0,0 +1,202 @@
+# Build and publish armasec-lite to PyPI.
+#
+# A tag publishes. A workflow_dispatch run builds, smoke tests and uploads the artifacts
+# without publishing anything, so the packaging can be exercised without burning a version
+# number: every publishing job is gated on the ref being a tag.
+#
+# Publishing uses PyPI trusted publishing (OIDC), so there is no API token to store or
+# rotate. It requires a one-time setup on PyPI: add a trusted publisher for the project
+# pointing at vantagecompute/armasec-lite, workflow `release.yml`, environment `pypi`.
+#
+# This is a pure Python package with no compiled extensions, so one universal
+# `py3-none-any` wheel covers every platform. There is no build matrix and no
+# architecture-specific retagging.
+
+name: Build and Publish armasec-lite
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+env:
+  PYTHON_VERSION: '3.12'
+
+jobs:
+  build:
+    name: Build and smoke test
+    runs-on: ubuntu-24.04
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Determine version
+        id: version
+        run: |
+          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
+            VERSION="${GITHUB_REF#refs/tags/v}"
+          else
+            VERSION="0.0.0.dev0+${GITHUB_SHA::8}"
+          fi
+
+          # Practical subset of the PEP 440 grammar, not the full spec: covers a plain
+          # release, one pre-release segment (a/b/c/rc, with a '.', '-', or no separator),
+          # an optional .postN, an optional .devN, and an optional +local segment. If a
+          # legitimate exotic version is ever rejected here, relax this regex rather than
+          # fight it.
+          PEP440_RE='^[0-9]+\.[0-9]+\.[0-9]+([.-]?(a|b|c|rc)[0-9]+)?(\.post[0-9]+)?(\.dev[0-9]+)?(\+[A-Za-z0-9]+)?$'
+          if [[ ! "${VERSION}" =~ ${PEP440_RE} ]]; then
+            echo "::error::Version '${VERSION}' is not a valid PEP 440 version. Push a tag shaped like 'vX.Y.Z' or 'vX.Y.Zrc1'." >&2
+            exit 1
+          fi
+
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+          echo "Building version ${VERSION}"
+
+      - name: Set the package version
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          # armasec_lite.__version__ reads importlib.metadata at import time, so the
+          # version lives in exactly one place and only pyproject.toml needs rewriting.
+          sed -i "0,/^version = \".*\"/s//version = \"${VERSION}\"/" pyproject.toml
+          grep '^version' pyproject.toml
+
+      - name: Run the test suite
+        run: |
+          uv sync --all-groups
+          uv run pytest tests/unit -q
+
+      - name: Lint and type check
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+          uv run mypy armasec_lite
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Smoke test the built wheel
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          # Install the artifact itself into a clean environment, not the source tree.
+          # A package can pass its own test suite and still be unusable once built, if a
+          # module is missing from the wheel or an entry point does not resolve.
+          uv venv /tmp/smoke
+          VIRTUAL_ENV=/tmp/smoke uv pip install dist/*.whl
+          /tmp/smoke/bin/python - <<'PY'
+          import os
+          import armasec_lite
+          from armasec_lite import Armasec, TokenPayload, TokenSecurity
+
+          expected = os.environ["VERSION"]
+          assert armasec_lite.__version__ == expected, (
+              f"wheel reports {armasec_lite.__version__}, expected {expected}"
+          )
+          for name in armasec_lite.__all__:
+              assert hasattr(armasec_lite, name), f"{name} missing from the built wheel"
+          print(f"armasec-lite {armasec_lite.__version__} imports cleanly from the wheel")
+          PY
+
+      - name: Verify the pytest plugin entry point resolves
+        run: |
+          # The pytest11 entry point is resolved by pytest at startup, so a broken one
+          # breaks every consumer's test run rather than failing quietly.
+          VIRTUAL_ENV=/tmp/smoke uv pip install pytest
+          /tmp/smoke/bin/python -c "
+          from importlib.metadata import entry_points
+          names = [e.value for e in entry_points(group='pytest11')]
+          assert 'armasec_lite.pytest_extension' in names, names
+          print('pytest11 entry point resolves')
+          "
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/*
+          retention-days: 30
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-24.04
+    needs: build
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist
+
+      - name: List distributions
+        run: ls -lh dist/
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/
+
+  create-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-24.04
+    needs: [build, publish-pypi]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist
+
+      - name: Create Release
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
+        with:
+          tag_name: v${{ needs.build.outputs.version }}
+          name: armasec-lite ${{ needs.build.outputs.version }}
+          body: |
+            ## armasec-lite ${{ needs.build.outputs.version }}
+
+            Injectable FastAPI authentication against OIDC providers, with three runtime
+            dependencies instead of upstream armasec's ten.
+
+            ### Install
+
+            ```bash
+            uv add armasec-lite==${{ needs.build.outputs.version }}
+            ```
+
+            ```bash
+            pip install armasec-lite==${{ needs.build.outputs.version }}
+            ```
+
+            The pytest fixtures ship in an extra, so they stay out of production installs:
+
+            ```bash
+            uv add "armasec-lite[test]==${{ needs.build.outputs.version }}"
+            ```
+
+            ### Documentation
+
+            https://docs.vantagecompute.ai/developer/armasec-lite/
+          files: dist/*
+          fail_on_unmatched_files: true

armasec_lite-0.1.3/.gitignore

@@ -0,0 +1,14 @@
+.worktrees/
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+coverage.xml
+junit.xml
+

armasec_lite-0.1.3/CLAUDE.md

@@ -0,0 +1,229 @@
+# armasec-lite
+
+Injectable FastAPI authentication against OIDC providers. A dependency-minimal
+reimplementation of [armasec](https://github.com/omnivector-solutions/armasec) 3.x with the
+same public API.
+
+Import package `armasec_lite`, distribution `armasec-lite`, Python 3.12+.
+
+Runtime dependencies are exactly three: `fastapi`, `cryptography`, `pydantic`. Adding a
+fourth is a design change, not a routine edit. `tests/unit/test_packaging.py` enforces both
+the count and the absence of `jose`, `buzz`, `snick`, `auto_name_enum`, `pluggy`, `respx`
+and `httpx` by walking the AST of every module.
+
+`armasec_lite/jwt.py` is the only security-critical module. A defect there is an
+authentication bypass, not a bug. Read its module docstring before changing it.
+
+## Writing docstrings
+
+**The docstrings in `armasec_lite/` are the API reference.** There is no hand-written
+reference page. `@vantagecompute/docusaurus-plugin-pydoc` parses each module with `ast`
+at build time and generates the entire reference section from what it finds. A docstring
+you skip is a page section that does not exist.
+
+The generator never imports the code, so it sees only what is literally written in the
+source: docstrings, signatures, annotations, decorators and class-level assignments.
+
+### What the generator renders, and what that forces
+
+Read `docusaurus/node_modules/@vantagecompute/docusaurus-plugin-pydoc/src/renderer.js` if
+you need the detail.
+The four consequences that change how you write:
+
+**1. The module docstring becomes the page's `## Overview`, and its FIRST LINE becomes the
+Description column of the reference index, truncated to 80 characters.**
+
+Write a first line that is a complete sentence, self-contained, and comfortably under 80
+characters so the truncation never bites. It sits in a table beside every sibling module, so
+it should distinguish this module from the others at a glance.
+
+```python
+# Good: 56 characters, says what the module is
+"""A minimal JWS/JWT implementation, replacing python-jose."""
+
+# Bad: truncated mid-word in the index table
+"""Exception types and the small assertion helpers armasec uses in place of py-buzz."""
+
+# Bad: burns the budget before saying anything
+"""This module provides functionality for handling exceptions."""
+```
+
+**2. Module-level constants render bare, as `NAME: annotation = value`, with no
+description. `#:` comments above them are NOT captured.**
+
+If a reader needs to understand a constant, explain it in the module docstring prose.
+Nowhere else will reach the page. `JWKS_REFRESH_INTERVAL`, `MAX_BODY_BYTES`,
+`DEFAULT_TIMEOUT`, `MAX_REDIRECTS` and `SUPPORTED_ALGORITHMS` all need this. Keep the `#:`
+comments anyway; they serve someone reading the source.
+
+**3. Class attributes render as a table with columns Attribute, Type and Default, and no
+description column.**
+
+The class docstring's `Attributes:` section is the only place a reader learns what a field
+means. Every class with public attributes needs one, and it must cover every attribute.
+
+**4. `__init__` and `__call__` are always rendered. Everything else beginning with an
+underscore is private and never rendered.**
+
+An earlier version of this file said these two render only when they carry a docstring.
+That is wrong, and the difference matters: an undocumented `__init__` produces an **empty
+section** on the page rather than being omitted. So a missing docstring there is visible to
+readers as a gap, not hidden.
+
+`TokenSecurity.__call__` is the most important method in the library. Methods like it earn
+a substantial docstring, not a one-liner.
+
+**5. Use `###` and below for any heading inside a docstring, never `##`.**
+
+The generator emits docstrings verbatim into the page beneath its own `## Overview`
+heading. An `##` in your prose escapes that section and collides with the generator's own
+`## Constants` and `## Classes` headings, producing duplicate anchors and a broken table of
+contents. This was a real defect found by building the site and reading the output.
+
+### Module docstrings
+
+Two to five short paragraphs. Cover: what this module is for, where it sits in the request
+path, its constants, and anything non-obvious a reader would otherwise have to reconstruct
+from the source.
+
+Non-obvious is the operative word. Prefer the thing that is surprising, deliberate, or
+load-bearing over a restatement of the module's name:
+
+- `http.py`: `urllib.request.build_opener()` installs `FileHandler`, so an opener will
+  happily read `file://` URLs. The scheme guard in `get_json` is therefore load-bearing and
+  not redundant with the URL validation in `schemas.py`.
+- `openid_config_loader.py`: the lock is a `threading.Lock` and not an `asyncio.Lock`
+  because an `asyncio.Lock` binds to the loop that first awaits it and goes stale across
+  test loops.
+- `schemas.py`: `OpenidConfig.issuer` is a plain `str` and deliberately not `AnyHttpUrl`,
+  because it is compared against a token's `iss` claim by exact string equality and
+  normalization would reject valid tokens from providers publishing a bare-host issuer.
+- `exceptions.py`: `handle_errors` deliberately does not re-wrap `ArmasecError` subclasses,
+  unlike py-buzz, so a specific 401 is not flattened into a generic 500.
+
+If you find yourself writing a comment in the source that explains why something is the way
+it is, ask whether it belongs in the module docstring instead, where readers of the
+reference will see it.
+
+### Class and function docstrings
+
+Google style, which is what the codebase already uses.
+
+Every public function and method needs `Args:` covering every parameter. Add `Returns:`
+when the return value is not obvious from the name and annotation.
+
+**`Raises:` matters more here than in most projects.** This is an authentication library:
+the exception type a call raises determines the HTTP status a client sees. A caller needs to
+know that `TokenDecoder.decode` can raise `ExpiredSignatureError` (401) or
+`PayloadMappingError` (500), and what the difference means. Document it.
+
+```python
+def decode(self, token: str, **claims: Any) -> TokenPayload:
+    """
+    Decode a JWT into a TokenPayload, checking signatures and claims.
+
+    Args:
+        token:  The token to decode.
+        claims: Additional constraints, such as `audience` or `issuer`. May include an
+                `options` dict merged over `decode_options_override`.
+
+    Returns:
+        The verified payload, with `original_token` set to the input token.
+
+    Raises:
+        AuthenticationError: The token is malformed, its signature does not verify, or a
+            claim check failed. Subclasses carry the specific reason and all map to 401.
+        PayloadMappingError: The configured `permission_extractor` did not match a path in
+            the decoded token. Maps to 500, because that is a server misconfiguration
+            rather than a bad request.
+    """
+```
+
+### Style
+
+Explain why, not what. The signature already says what. A docstring reading
+"Initializes the TokenSecurity instance" is worse than no docstring, because it occupies the
+space where the useful sentence would go.
+
+Say when something is deliberate. Several choices in this codebase look wrong until you know
+the reason, and a reader who does not know will "fix" them.
+
+Do not pad to fill a template. If a function has no failure modes, omit `Raises:`.
+
+**Never use the em-dash (U+2014) or en-dash (U+2013) character.** Use commas, colons,
+parentheses, or separate sentences. Hyphens in compound words are fine. This applies to
+every file in the repository, not only docstrings.
+
+### Adding a new module
+
+The plugin's module list in `docusaurus/docusaurus.config.ts` is explicit. A new module
+under `armasec_lite/` generates no reference page until you add it there, with a label.
+
+`.github/workflows/deploy-docs.yml` fails the docs build when the number of generated pages
+does not match the number of declared modules, so a module that is declared but fails to
+introspect breaks the build rather than silently vanishing. It derives both counts
+dynamically, so it needs no update when you add a module.
+
+Do not add `armasec_lite/__init__.py`: it is re-exports, and its page would duplicate the
+others.
+
+### Checking your work
+
+```bash
+# Every module's first docstring line, with its length. Keep them under 80.
+for f in armasec_lite/*.py armasec_lite/pluggable/*.py; do
+  python3 -c "
+import ast
+d = ast.get_docstring(ast.parse(open('$f').read()))
+line = (d or '').strip().split(chr(10))[0] if d else '<NO MODULE DOCSTRING>'
+print(f'{len(line):3d}  $f  {line}')
+"
+done
+
+# Generate and read the reference. It is the actual deliverable, and building it is the
+# only way to catch heading collisions and layout problems.
+cd docusaurus && npm ci && npm run build && ls docs/api-reference/
+```
+
+**Read the built output, do not just check that the build passed.** Two defects in this
+repository's docs were found only by reading generated pages: three module descriptions
+silently truncated in the index table, and `##` headings in docstrings colliding with the
+generator's own section headings.
+
+### Renderer notes
+
+`Args:`, `Returns:` and `Raises:` blocks render as single run-on paragraphs, because the
+renderer emits docstring bodies verbatim into Markdown and Markdown collapses the newlines.
+The content is correct; the formatting is poor, and it is worst on long `Raises:` sections.
+
+This was fixed upstream in `@vantagecompute/docusaurus-plugin-pydoc` v0.1.1, which this
+project depends on. Recognized Google-style sections now render as Markdown lists.
+
+The general rule still holds: do not work around a rendering problem by reformatting
+docstrings into Markdown. They would then read badly in an editor, in `help()`, and in every
+IDE tooltip, which is where most people actually meet them. Fix the renderer in
+`vantagecompute/docusaurus-plugin-pydoc` instead, which improves every Vantage project using
+the plugin.
+
+## Testing
+
+`just test` runs the unit suite. `just lint` runs `ruff check`, `ruff format --check` and
+`mypy` in strict mode. Both must pass before a commit.
+
+Test-driven: write the failing test, run it, watch it fail for the reason you expect, then
+implement. For a security defense, go further and confirm the test fails when the defense is
+removed. A passing test proves nothing if it would also pass against undefended code, and
+that has already happened once in this codebase: the algorithm-confusion test passed for the
+wrong reason until someone checked, because the fixture it used happened to lack the field
+that would have made the forgery succeed.
+
+`tests/unit/test_jwt_attacks.py` is the attack suite. Its test names are consumed by a
+benchmark that publishes a security-posture chart, so a name there is a public claim about
+what is defended. Do not rename one casually, and do not let a name outlive what its test
+actually checks.
+
+## The justfile
+
+`justfile` is a verbatim copy of `vantage-mcp-infra`'s, kept deliberately so it can be
+pruned by hand later. Most of its recipes reference infrastructure this repository does not
+have. `test`, `test-cov`, `lint`, `fmt` and the `docs-*` recipes work. Leave the rest alone.