server-action-audit 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Del Prudence
+
+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.

package/README.fr.md

@@ -0,0 +1,55 @@
+# server-action-audit
+
+**Trouvez les Server Actions Next.js que n'importe qui peut appeler.**
+
+Chaque fonction `"use server"` est un point d'accès HTTP public. N'importe qui peut l'appeler avec une requête POST, hors de votre interface, avec les arguments de son choix. La [documentation Next.js](https://nextjs.org/docs/app/guides/data-security) est claire : vérifier la connexion au niveau de la page ne protège pas les Server Actions qu'elle contient. Chaque action doit vérifier la session elle-même.
+
+Cette vérification s'oublie facilement, et rien ne vous le rappelle. `server-action-audit` liste toutes les Server Actions de votre application et signale celles qui ne vérifient pas qui les appelle : dans le terminal, en CI, et dans votre éditeur grâce à ESLint.
+
+```sh
+npx server-action-audit
+```
+
+![server-action-audit liste chaque Server Action et signale celles qui ne sont pas protégées](docs/demo.svg)
+
+Aucune configuration nécessaire. L'outil lit votre code, il ne l'exécute jamais. Testé sur cinq grosses applications Next.js open source : 456 Server Actions, environ une seconde par application.
+
+## Ce qu'il reconnaît
+
+- **Les actions** : les exports des fichiers `"use server"`, et les actions déclarées dans un composant (`<form action={async () => { "use server" … }}>`).
+- **Les bibliothèques d'authentification** : Auth.js / NextAuth, Clerk, Supabase, Better Auth, Lucia, Kinde, iron-session, Firebase Admin, WorkOS AuthKit.
+- **Vos propres fonctions** (`getCurrentUser()`, `requireUser()`…) : il les suit d'un fichier à l'autre, à travers les alias `@/` du tsconfig, les ré-exports et `cache()` de React.
+- **Les clients d'actions** : next-safe-action et zsa. L'outil lit leur middleware, y compris celui d'un client dérivé d'un autre client.
+- **Seuls les contrôles du chemin principal comptent** : une vérification placée dans une branche `if` ou dans une fonction de rappel ne protège pas l'action.
+- **La validation des entrées** : il prévient quand une action utilise ses arguments sans les valider (Zod, Valibot, Yup, ou un schéma next-safe-action / zsa).
+
+## Actions publiques
+
+Login, inscription, newsletter : certaines actions sont publiques exprès. Indiquez-le avec un commentaire juste avant l'action, ou en haut de son corps :
+
+```ts
+// Tout le monde peut s'abonner. @public-action
+export async function subscribe(email: string) {}
+```
+
+## Configuration, ESLint et CI
+
+Tout est décrit dans le [README en anglais](README.md#configuration) :
+- le fichier `server-action-audit.config.json` ;
+- le plugin ESLint (`server-action-audit/eslint`) ;
+- les options `--fail-on`, `--json` et `--quiet` ;
+- l'Action GitHub, qui annote les pull requests et peut aussi y poster le rapport en commentaire (`comment: true`).
+
+## Limites
+
+C'est une analyse statique, fondée sur les noms. Un rapport sans erreur veut dire « rien d'évident ne manque », pas « l'application est sûre ».
+
+- **Elle ne vérifie pas ce que vous faites de la session.**
+- **Elle ne vérifie pas l'appartenance** : être connecté ne veut pas dire avoir le droit de supprimer *ce* contenu.
+- **Elle ne compte pas le middleware**, car la documentation de Next.js recommande de vérifier dans chaque action.
+
+Un faux positif, ou une action protégée qui n'est pas reconnue ? [Ouvrez une issue](https://github.com/i6moons/server-action-audit/issues).
+
+## Licence
+
+[MIT](LICENSE) © Del Prudence ([@i6moons](https://github.com/i6moons))

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# server-action-audit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Find the Next.js Server Actions that anyone can call.**
+
+[![CI](https://github.com/i6moons/server-action-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/i6moons/server-action-audit/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/server-action-audit?color=cb3837)](https://www.npmjs.com/package/server-action-audit)
+[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-Server%20Action%20Audit-2088FF?logo=githubactions&logoColor=white)](https://github.com/marketplace/actions/server-action-audit)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Every `"use server"` function is a public HTTP endpoint. Anyone can call it with a POST request, from outside your UI, with any arguments. The [Next.js docs](https://nextjs.org/docs/app/guides/data-security) put it plainly: an auth check on the page does not protect the Server Actions defined in it, so each action has to check the session itself.
+
+That check is easy to forget, and nothing reminds you. `server-action-audit` lists every Server Action in your app and flags the ones without an authorization check. It runs in your terminal, in CI, and in your editor through ESLint.
+
+```sh
+npx server-action-audit
+```
+
+![server-action-audit lists every Server Action and flags the unprotected ones](docs/demo.svg)
+
+No config needed. It reads your code; it never runs it. Tested on five large open-source Next.js apps: 456 Server Actions, about a second per app.
+
+## What it understands
+
+| | |
+| --- | --- |
+| **Actions** | Exports of `"use server"` files (functions, arrow functions, `export { a as b }`, default exports) and inline actions (`<form action={async () => { "use server" … }}>`) |
+| **Auth libraries** | Auth.js / NextAuth v5 (`auth()`), NextAuth v4 (`getServerSession`), Clerk (`auth()`, `currentUser()`, `auth.protect()`), Supabase (`supabase.auth.getUser()`, `getClaims()`), Better Auth (`auth.api.getSession()`), Lucia (`validateRequest()`), Kinde, iron-session, Firebase Admin (`verifyIdToken`, `verifySessionCookie`), WorkOS AuthKit (`withAuth()`) |
+| **Your own helpers** | `getCurrentUser()`, `requireUser()`, `verifySession()`… and any helper that calls one of the above. It follows them across files (relative imports and tsconfig `paths` like `@/lib/dal`), through re-exports and React `cache()`, up to 4 levels deep. Only checks on the main path count: a check inside an `if` branch or a callback does not |
+| **Inline actions** | An action declared in a component that uses the component's session (`const session = await auth()` in the page, `if (!session) return` in the action) |
+| **Action clients** | [next-safe-action](https://next-safe-action.dev) and [zsa](https://github.com/IdoPesok/zsa). It reads the client's middleware, so `actionClient.action(…)` is protected when `actionClient` checks the session, and so is a client derived from it (`actionClient.use(…)`). Guards that keep logged-in users out (`throwIfAuthenticated`) do not count |
+| **Wrappers** | `withAuth(async () => …)`, `validatedActionWithUser(schema, …)`: wrappers whose name says auth, or that you list in the config |
+| **Input validation** | Warns when an action takes arguments and nothing parses them (Zod, Valibot, Yup, or a next-safe-action / zsa schema) |
+
+## Public actions
+
+Some actions are public on purpose: login, sign-up, newsletter. Say so with a comment, right before the action or at the top of its body:
+
+```ts
+// Anyone can subscribe. @public-action
+export async function subscribe(email: string) {
+  const { email: valid } = SubscribeSchema.parse({ email })
+  // …
+}
+```
+
+They show up as `○ public` and never fail the audit. A real auth check always wins over the marker.
+
+## Configuration
+
+Teach it your own names in `server-action-audit.config.json`, or under `"serverActionAudit"` in package.json:
+
+```json
+{
+  "authFunctions": ["getMe", "session.require"],
+  "authWrappers": ["withTeam"],
+  "authClients": ["teamActionClient"],
+  "publicActions": ["subscribe"],
+  "ignore": ["app/legacy/**"]
+}
+```
+
+- **`authFunctions`**: a plain name matches the end of the call (`getMe` matches `getMe()` and `lib.getMe()`). A dotted name matches the end of the path (`session.require` matches `ctx.session.require()`).
+- **`authWrappers`**: functions that wrap an action with an auth check.
+- **`authClients`**: next-safe-action or zsa clients with auth middleware.
+- **`publicActions`**: action names to treat as public.
+- **`ignore`**: globs, relative to the project root.
+
+When an action isn't recognized, the report tells you which name to add.
+
+## ESLint
+
+The same analysis, in your editor. ESLint 9 or 10, flat config:
+
+```js
+// eslint.config.mjs
+import serverActionAudit from 'server-action-audit/eslint'
+
+export default [
+  // …your config
+  serverActionAudit.configs.recommended,
+]
+```
+
+| Rule | Default | |
+| --- | --- | --- |
+| `server-action-audit/require-auth` | error | Server Action without an authorization check |
+| `server-action-audit/require-input-validation` | warn | Server Action that uses its arguments without validating them |
+
+Options go in `settings.serverActionAudit` (shared by both rules) or on each rule. They use the same format as the config file, without `ignore`.
+
+## CI
+
+The CLI exits with code 1 when it finds an unprotected action, so any CI can run it:
+
+```sh
+npx server-action-audit
+```
+
+### GitHub Actions
+
+Problems show up as annotations on the pull request, right on the line of the action:
+
+```yaml
+# .github/workflows/security.yml
+name: Security
+on: [pull_request]
+jobs:
+  server-actions:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: i6moons/server-action-audit@v0
+        with:
+          path: .            # where your Next.js app is
+          fail-on: unprotected
+```
+
+To also get the report as a comment on the pull request, set `comment: true` and let the job write to pull requests. The action keeps a single comment and updates it on every push. It only comments once there is something to fix. If the job can't comment (pull requests from forks only get a read-only token), it shows a warning and the audit result stays the same.
+
+```yaml
+jobs:
+  server-actions:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: i6moons/server-action-audit@v0
+        with:
+          comment: true
+```
+
+For GitHub code scanning (the Security tab), upload the SARIF output:
+
+```yaml
+      - run: npx server-action-audit --format sarif > server-actions.sarif || true
+      - uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: server-actions.sarif
+```
+
+### Options
+
+| Option | |
+| --- | --- |
+| `--fail-on unprotected` | Default. Fail on actions without an auth check |
+| `--fail-on unvalidated` | Also fail on unvalidated input |
+| `--fail-on never` | Report only |
+| `--format pretty` | Default. Human-readable report |
+| `--format json` | Machine-readable output (`--json` works too) |
+| `--format github` | GitHub Actions annotations |
+| `--format sarif` | SARIF 2.1.0, for code scanning |
+| `--format markdown` | Markdown, e.g. `>> "$GITHUB_STEP_SUMMARY"` |
+| `--pr-comment` | In GitHub Actions, also post the report on the pull request (needs `GITHUB_TOKEN` with `pull-requests: write`) |
+| `--quiet` | Show problems only |
+| `--config <file>` | Another config file |
+
+## What it does not check
+
+This is a static check that works on names. Treat a green report as "nothing obviously missing", not as proof that your app is secure.
+
+- **It does not check what you do with the session.** `await auth()` counts as a check even if you then ignore the result. Make sure you stop when there is no user.
+- **It does not check ownership.** Being logged in is not the same as being allowed to delete *this* post. Check that the resource belongs to the user.
+- **Middleware is not counted.** The Next.js docs recommend checking inside each action, and middleware-only protection has been bypassed before ([CVE-2025-29927](https://nextjs.org/blog/cve-2025-29927)). If you rely on it anyway, mark those actions with `@public-action` or list your middleware helper in `authFunctions`.
+- **Unusual patterns can slip through.** Dynamic imports, auth checks hidden in packages from `node_modules`, or a helper whose name contains `auth` without doing any check.
+
+Found a false positive or a false negative? [Open an issue](https://github.com/i6moons/server-action-audit/issues) with the smallest snippet that reproduces it.
+
+## API
+
+```ts
+import { scanProject, formatPretty } from 'server-action-audit'
+
+const report = scanProject(process.cwd(), { authFunctions: ['getMe'] })
+console.log(report.summary) // { actions, protected, unprotected, public, unvalidated }
+```
+
+## License
+
+[MIT](LICENSE) © Del Prudence ([@i6moons](https://github.com/i6moons))
+
+[Lire en français](README.fr.md)