oauthlint-rules 0.1.0

package/LICENSE

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

@@ -0,0 +1,96 @@
+# oauthlint-rules
+
+A focused Semgrep rule library targeting the OAuth/OIDC/JWT anti-patterns that
+AI coding tools (Cursor, Claude Code, Copilot, Gemini Code Assist) produce on a
+recurring basis.
+
+This package contains:
+
+- the YAML rules (Semgrep format) in `rules/`
+- the loader + Zod validation schema in `src/`
+- the test fixtures (vulnerable + safe) in `tests/fixtures/`
+
+## Usage
+
+```ts
+import { loadAllRules, buildManifest } from 'oauthlint-rules';
+
+const rules = await loadAllRules();      // validates everything on load
+const manifest = await buildManifest();  // summary for the CLI
+```
+
+To scan code, use the [`oauthlint`](../cli) binary, which invokes Semgrep under
+the hood, passing this package as the `--config` argument.
+
+## Rule catalogue (30 rules)
+
+`LLM` = how often AI coding tools introduce the anti-pattern (prevalence).
+
+### JWT — RFC 7519 / 7515 / 7518
+
+| ID | Severity | LLM | CWE | Description |
+|----|----------|-----|-----|-------------|
+| `auth.jwt.alg-none` | ERROR | HIGH | CWE-327 | `alg: none` accepted in the verifier's allow-list |
+| `auth.jwt.weak-secret` | ERROR | HIGH | CWE-798 | Hard-coded or trivial JWT signing secret |
+| `auth.jwt.algorithm-confusion` | ERROR | MEDIUM | CWE-327 | HS256 verification against an asymmetric (RS/ES) key |
+| `auth.jwt.in-url` | ERROR | MEDIUM | CWE-598 | JWT (`eyJ…`) passed in a URL query string |
+| `auth.jwt.no-expiration` | WARNING | HIGH | CWE-613 | JWT signed/verified without an `exp` / `expiresIn` claim |
+| `auth.jwt.no-audience` | WARNING | MEDIUM | CWE-345 | JWT verified without checking the `aud` (audience) claim |
+| `auth.jwt.localstorage` | WARNING | HIGH | CWE-922 | Auth token written to `localStorage` |
+| `auth.jwt.no-issuer` | INFO | LOW | CWE-345 | JWT verified without checking the `iss` (issuer) claim |
+
+### OAuth 2.0 — RFC 6749 / 7636 / 8252 / 9700
+
+| ID | Severity | LLM | CWE | Description |
+|----|----------|-----|-----|-------------|
+| `auth.oauth.no-state` | ERROR | HIGH | CWE-352 | Authorization request built without a `state` parameter |
+| `auth.oauth.wildcard-redirect` | ERROR | MEDIUM | CWE-601 | `redirect_uri` allow-list with a wildcard / `http://` URL |
+| `auth.oauth.hardcoded-secret` | ERROR | HIGH | CWE-798 | `client_secret` hard-coded in source |
+| `auth.oauth.implicit-flow` | ERROR | MEDIUM | CWE-1004 | OAuth implicit flow (deprecated) |
+| `auth.oauth.open-redirect-callback` | ERROR | HIGH | CWE-601 | Callback redirects to a user-controlled URL |
+| `auth.oauth.no-pkce` | WARNING | HIGH | CWE-345 | Public client without PKCE |
+| `auth.oauth.no-state-validation` | WARNING | HIGH | CWE-352 | `state` received but never validated |
+| `auth.oauth.long-token-lifetime` | WARNING | MEDIUM | CWE-613 | Over-long `expires_in` / token lifetime |
+| `auth.oauth.broad-scope` | INFO | HIGH | CWE-272 | Over-broad scope requested (`admin`, `*`) |
+
+### Cookies — RFC 6265
+
+| ID | Severity | LLM | CWE | Description |
+|----|----------|-----|-----|-------------|
+| `auth.cookie.no-secure` | WARNING | HIGH | CWE-614 | Auth cookie set without the `Secure` flag |
+| `auth.cookie.no-httponly` | WARNING | HIGH | CWE-1004 | Auth cookie set without the `HttpOnly` flag |
+| `auth.cookie.no-samesite` | INFO | MEDIUM | CWE-1275 | Auth cookie set without `SameSite` |
+| `auth.cookie.long-lived` | INFO | MEDIUM | CWE-613 | Auth cookie with an excessively long `maxAge` |
+
+### Sessions
+
+| ID | Severity | LLM | CWE | Description |
+|----|----------|-----|-----|-------------|
+| `auth.session.id-in-url` | ERROR | MEDIUM | CWE-598 | Session id / token in a URL query string |
+| `auth.session.no-regeneration` | WARNING | MEDIUM | CWE-384 | Session not regenerated on login (fixation) |
+
+### CORS
+
+| ID | Severity | LLM | CWE | Description |
+|----|----------|-----|-----|-------------|
+| `auth.cors.wildcard-with-credentials` | ERROR | HIGH | CWE-942 | `Allow-Origin: *` combined with credentials |
+
+### Secrets
+
+| ID | Severity | LLM | CWE | Description |
+|----|----------|-----|-----|-------------|
+| `auth.secret.provider-key` | ERROR | HIGH | CWE-798 | Hard-coded key matching a known provider's format |
+
+### Auth flow
+
+| ID | Severity | LLM | CWE | Description |
+|----|----------|-----|-----|-------------|
+| `auth.flow.password-plaintext` | ERROR | MEDIUM | CWE-256 | Password persisted without hashing |
+| `auth.flow.insecure-random` | ERROR | HIGH | CWE-338 | `Math.random()` used for a security-sensitive value |
+| `auth.flow.timing-unsafe-compare` | WARNING | MEDIUM | CWE-208 | Secret compared with `===` (non-constant-time) |
+| `auth.flow.password-min-length` | WARNING | MEDIUM | CWE-521 | Password policy enforces too short a minimum length |
+| `auth.flow.no-rate-limit` | INFO | HIGH | CWE-307 | Auth endpoint (`/login`, etc.) without rate limiting |
+
+## License
+
+MIT — see [LICENSE](../LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { OAuthLintMetadataSchema, type OAuthLintMetadata, RuleFileSchema, type RuleFile, RuleSchema, type Rule, SeveritySchema, type Severity, } from './schema.js';
+export { buildManifest, loadAllRules, type LoadedRule, type RuleManifestEntry, RULES_ROOT, } from './loader.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,cAAc,EACd,KAAK,QAAQ,EACb,UAAU,EACV,KAAK,IAAI,EACT,cAAc,EACd,KAAK,QAAQ,GACd,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,aAAa,EACb,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,UAAU,GACX,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { OAuthLintMetadataSchema, RuleFileSchema, RuleSchema, SeveritySchema, } from './schema.js';
+export { buildManifest, loadAllRules, RULES_ROOT, } from './loader.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EAEvB,cAAc,EAEd,UAAU,EAEV,cAAc,GAEf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,aAAa,EACb,YAAY,EAGZ,UAAU,GACX,MAAM,aAAa,CAAC"}

package/dist/loader.d.ts

@@ -0,0 +1,35 @@
+import { type Rule } from './schema.js';
+/**
+ * Root directory containing the bundled rule YAML files.
+ * When the package is published, the rules/ folder ships next to dist/.
+ * In development, we walk up to the package root.
+ */
+export declare const RULES_ROOT: string;
+export interface LoadedRule {
+    rule: Rule;
+    sourceFile: string;
+}
+/**
+ * Recursively load every rule shipped with this package.
+ * Throws a descriptive error if any rule fails schema validation —
+ * we'd rather fail loud at import time than silently ship a broken rule.
+ */
+export declare function loadAllRules(root?: string): Promise<LoadedRule[]>;
+/**
+ * Build a manifest summarising every shipped rule.
+ * Useful for the CLI's `oauthlint list` command and for the docs site.
+ */
+export declare function buildManifest(root?: string): Promise<{
+    id: string;
+    severity: "INFO" | "WARNING" | "ERROR";
+    languages: string[];
+    oauthlintId: string;
+    docUrl: string;
+    llmPrevalence: "HIGH" | "MEDIUM" | "LOW";
+    cwe: string | undefined;
+    owasp: string | undefined;
+    description: string;
+    sourceFile: string;
+}[]>;
+export type RuleManifestEntry = Awaited<ReturnType<typeof buildManifest>>[number];
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,IAAI,EAAkB,MAAM,aAAa,CAAC;AAIxD;;;;GAIG;AACH,eAAO,MAAM,UAAU,QAA+B,CAAC;AAEvD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,IAAI,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,GAAE,MAAmB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAuCnF;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,IAAI,GAAE,MAAmB;;;;;;;;;;;KAc5D;AAED,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/loader.js

@@ -0,0 +1,72 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import fastGlob from 'fast-glob';
+import { parse as parseYaml } from 'yaml';
+import { RuleFileSchema } from './schema.js';
+const HERE = dirname(fileURLToPath(import.meta.url));
+/**
+ * Root directory containing the bundled rule YAML files.
+ * When the package is published, the rules/ folder ships next to dist/.
+ * In development, we walk up to the package root.
+ */
+export const RULES_ROOT = resolve(HERE, '..', 'rules');
+/**
+ * Recursively load every rule shipped with this package.
+ * Throws a descriptive error if any rule fails schema validation —
+ * we'd rather fail loud at import time than silently ship a broken rule.
+ */
+export async function loadAllRules(root = RULES_ROOT) {
+    const files = await fastGlob(['**/*.yml', '**/*.yaml'], {
+        cwd: root,
+        absolute: true,
+        ignore: ['**/node_modules/**'],
+    });
+    const loaded = [];
+    const seenIds = new Set();
+    for (const file of files) {
+        const content = await readFile(file, 'utf8');
+        let parsed;
+        try {
+            parsed = parseYaml(content);
+        }
+        catch (err) {
+            throw new Error(`Invalid YAML in ${file}: ${err.message}`);
+        }
+        const result = RuleFileSchema.safeParse(parsed);
+        if (!result.success) {
+            throw new Error(`Schema validation failed for ${file}:\n${result.error.issues
+                .map((i) => `  - ${i.path.join('.')}: ${i.message}`)
+                .join('\n')}`);
+        }
+        for (const rule of result.data.rules) {
+            if (seenIds.has(rule.id)) {
+                throw new Error(`Duplicate rule id ${rule.id} (also found in ${file})`);
+            }
+            seenIds.add(rule.id);
+            loaded.push({ rule, sourceFile: file });
+        }
+    }
+    loaded.sort((a, b) => a.rule.id.localeCompare(b.rule.id));
+    return loaded;
+}
+/**
+ * Build a manifest summarising every shipped rule.
+ * Useful for the CLI's `oauthlint list` command and for the docs site.
+ */
+export async function buildManifest(root = RULES_ROOT) {
+    const loaded = await loadAllRules(root);
+    return loaded.map(({ rule, sourceFile }) => ({
+        id: rule.id,
+        severity: rule.severity,
+        languages: rule.languages,
+        oauthlintId: rule.metadata['oauthlint-rule-id'],
+        docUrl: rule.metadata['oauthlint-doc-url'],
+        llmPrevalence: rule.metadata['llm-prevalence'],
+        cwe: rule.metadata.cwe,
+        owasp: rule.metadata.owasp,
+        description: rule.message.split('\n')[0]?.trim() ?? '',
+        sourceFile,
+    }));
+}
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"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"}

package/dist/manifest.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Pre-computed manifest entry-point used by consumers that want
+ * the rule list without filesystem access (e.g. browser docs site).
+ *
+ * The actual manifest is generated at build time by `scripts/generate-manifest.ts`
+ * (added in Sprint 1.2). For now, consumers should call `buildManifest()`
+ * directly from `./loader.js`.
+ */
+export { buildManifest, type RuleManifestEntry } from './loader.js';
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,10 @@
+/**
+ * Pre-computed manifest entry-point used by consumers that want
+ * the rule list without filesystem access (e.g. browser docs site).
+ *
+ * The actual manifest is generated at build time by `scripts/generate-manifest.ts`
+ * (added in Sprint 1.2). For now, consumers should call `buildManifest()`
+ * directly from `./loader.js`.
+ */
+export { buildManifest } from './loader.js';
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,aAAa,EAA0B,MAAM,aAAa,CAAC"}