permitio 3.0.0: fix SDK bugs, migrate tests to Vitest, and harden CI

.github/CONTRIBUTING.md

@@ -1,3 +1,111 @@
-# Example Contributing Guidelines
+# Contributing
 
-This is an example of GitHub's contributing guidelines file. Check out GitHub's [CONTRIBUTING.md help center article](https://help.github.com/articles/setting-guidelines-for-repository-contributors/) for more information.
+Install the Node version from `.nvmrc` and pnpm 12.8.1. From the repository root:
+
+```sh
+pnpm audit --audit-level=moderate
+pnpm install --frozen-lockfile --ignore-scripts
+pnpm hooks:install
+pnpm verify
+```
+
+`verify` runs the frozen dependency check, Oxlint, Oxfmt, strict TypeScript, both module builds,
+all local unit, module-import, and tooling tests, and the reviewed API contract inventory. It requires no Permit credentials or Java.
+CI uses the same verification command. Use `pnpm fix` for lint fixes and formatting, then rerun
+`pnpm verify`. Hooks check files without rewriting them.
+
+The hook installer enables Git's per-worktree configuration and installs prek into the current
+checkout's own Git directory. It leaves the shared hook path and sibling worktrees unchanged.
+Tool versions are pinned in the pnpm lockfile; Dependabot groups updates with a seven-day delay.
+For any future remote prek hooks, use frozen commit hashes and `pnpm exec prek update
+--cooldown-days 7 --freeze` when reviewing updates.
+
+## Builds and imports
+
+Authored source is ESM under `src/package.json`. Use `#src/` imports, including type-only imports
+where appropriate. The root package keeps its CommonJS metadata because it publishes both
+`build/index.js` and `build/index.mjs`. TypeScript emits declarations; a checked AST pass replaces
+source aliases with paths that resolve inside the packed package. Do not publish source aliases
+or change public entry points as an incidental tooling fix.
+
+TypeScript 7 is the SDK checker and emitter. TypeDoc and the generation guard need a JavaScript
+compiler API, so the private `tools/compiler` workspace explicitly owns maintained TypeScript 6
+and TypeDoc. The SDK has no runtime dependency on that workspace.
+
+## Tests
+
+Use `pnpm test:unit` for focused unit work and `pnpm test:module-imports` for the built entry points.
+Add new source tests beside the code as `*.test.ts`; existing grouped `src/tests` suites can be
+extended in place. Mock external boundaries and test malformed input and failures. Demonstrate
+that a representative regression fails when its fix is removed.
+
+`pnpm test:codegen` tests the generator guard and local tooling without Java. Regeneration requires
+Java 17: `pnpm generate-openapi-client` reads the reviewed committed snapshot and shared configuration,
+then validates and normalizes the generated output before replacing it. `pnpm check:openapi` compares
+two clean generations with each other and the committed output. The separate `pnpm check:codegen`
+guard regenerates the historical fixture using the same pinned generator and configuration.
+See [the generation guide](../openapi/README.md) before refreshing the snapshot. Never replace the
+historical fixture or change API shapes merely to make a tooling check pass.
+
+`test:integration` and `test:e2e` use a Permit backend. Run them locally only with explicit
+authorization. The standard verification command uses local fixtures only.
+
+## API operation and shape evidence
+
+`pnpm check:api-contracts` verifies the local AST inventory, source provenance and exact operation
+omission decisions. `pnpm check:api-drift` also compares current public schema documentation with
+the pinned snapshots; it makes no backend operation calls. Reports distinguish local integrity,
+coverage gaps, the unavailable shared parity target and unmeasured backend behavior. See
+[the evidence guide](../api-coverage/README.md) before changing a baseline or exclusion.
+
+## Documentation and changes
+
+Run `pnpm run docs` to generate API documentation, or `pnpm run docs:watch` while editing TSDoc.
+Use `pnpm run docs -- --out /absolute/output/path` to inspect output without replacing tracked docs.
+Keep generated documentation out of unrelated changes.
+
+Keep changes focused, preserve supported runtime behavior, and describe validation and remaining
+limitations in the PR. Check [AGENTS.md](../AGENTS.md) for repository development rules.
+
+## Dependency security
+
+Install [Trivy 0.74.0](https://github.com/aquasecurity/trivy/releases/tag/v0.74.0) for the same
+scanner used in CI. The audit runner uses Node built-ins and runs before SDK dependencies install:
+
+```sh
+node scripts/audit-dependencies.mjs --locked-only --out security-preinstall
+pnpm install --frozen-lockfile --ignore-scripts
+pnpm build
+pnpm pack --out candidate.tgz --ignore-scripts
+pnpm audit:dependencies --artifact candidate.tgz --out security-report
+```
+
+The report covers the locked SDK runtime graph, the complete development/tooling workspace,
+and two independently resolved consumers of the actual tarball. Runtime dependencies are exact
+pins, so the minimum and newest supported direct versions are identical. Both consumer lanes
+resolve current compatible transitive versions; neither claims to test the lowest transitive
+versions. Adding dependency ranges or peer dependencies requires explicit supported-range lanes.
+
+The pinned pnpm resolver uses a 24-hour release delay and disables scripts. It resolves a consumer
+lockfile, audits it, then performs a frozen installation only after that lane passes. Trivy's
+runtime dependency graph must match an independent pnpm lock inventory. Empty results, incomplete
+inventory, malformed output, process failures and unresolved consumer installs are INVALID.
+
+Exit codes are 0 (PASS), 1 (FAIL: fixable HIGH/CRITICAL findings) and 2 (INVALID: not completed).
+All other advisories and registry severity totals remain visible in JSON and Markdown, including
+findings without available fixes. Raw scanner output and each consumer lockfile are retained.
+Do not add ignored advisory IDs, dependency overrides or scanner suppression files.
+
+CI requires these checks on Node 22.13 and 24.0. The weekly Monday workflow and manual dispatch
+publish GitHub summaries and downloadable evidence; repository maintainers review failed runs.
+Slack delivery requires a separately authorized destination and is not configured here.
+The release job also scans its final tarball immediately before publication with scripts disabled;
+it cannot publish if either scanner or consumer lane fails. npm Trusted Publishing requires
+Node >=22.14.0 and npm >=11.5.1; the release job validates the npm bundled with its Node 24 runner.
+The supported SDK Node floor remains 22.13.0.
+
+Dependabot groups runtime and tooling minor/patch updates, uses `increase`, and waits seven days
+(fourteen for majors). Its published support matrix currently lists pnpm through version 10;
+pnpm 12 lock updates are not yet verified. Maintainers must review dependency update failures and
+apply compatible pinned updates manually until the bot supports this lockfile. The scheduled
+security gate does not depend on Dependabot and continues to scan all four trees.

.github/dependabot.yml

@@ -0,0 +1,34 @@
+version: 2
+updates:
+  # Keeps the SHA-pinned actions in .github/workflows current. The PDP image in
+  # ci.yaml is started with docker run, which Dependabot does not track, so its
+  # version and digest are bumped by hand.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      github-actions:
+        patterns:
+          - '*'
+  - package-ecosystem: npm
+    versioning-strategy: increase
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+      semver-major-days: 14
+    groups:
+      runtime-dependencies:
+        dependency-type: production
+        update-types: [minor, patch]
+        patterns:
+          - '*'
+      development-dependencies:
+        dependency-type: development
+        update-types: [minor, patch]
+        patterns:
+          - '*'

.github/workflows/api-contract-drift.yaml

@@ -0,0 +1,65 @@
+name: Published API contract drift
+
+on:
+  schedule:
+    - cron: '17 7 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: api-contract-drift-${{ github.ref }}
+  cancel-in-progress: false
+
+defaults:
+  run:
+    shell: bash --noprofile --norc -euo pipefail {0}
+
+jobs:
+  published-contracts:
+    name: Compare published API contracts
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - name: Checkout reviewed SDK
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Setup pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+        env:
+          npm_config_ignore_scripts: 'true'
+        with:
+          run_install: false
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '22.13.0'
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+      - name: Audit dependency metadata before installation
+        timeout-minutes: 3
+        run: pnpm audit --audit-level=moderate
+      - name: Install locked tools
+        timeout-minutes: 5
+        run: pnpm install --frozen-lockfile --ignore-scripts
+      - name: Inspect published source drift
+        timeout-minutes: 3
+        run: pnpm check:api-drift
+      - name: Summarize evidence
+        if: always()
+        run: |
+          if [[ -f coverage/api-contracts/report.md ]]; then
+            cat coverage/api-contracts/report.md >> "$GITHUB_STEP_SUMMARY"
+          else
+            printf '%s\n' 'API contract inspection did not complete. Inspect the failed setup step.' >> "$GITHUB_STEP_SUMMARY"
+          fi
+      - name: Retain drift evidence
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: api-contract-evidence
+          path: coverage/api-contracts/
+          if-no-files-found: error
+          retention-days: 30