@nightowlsdev/auth-auth0 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Night Owls contributors
+
+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,87 @@
+# @nightowlsdev/auth-auth0
+
+An Auth0 `AuthProvider` for `@nightowlsdev/core`. It verifies an Auth0-issued access token with
+`jose` against Auth0's **public JWKS** and maps it into a Night Owls `AuthContext`
+(`{ tenantId, userId, capabilities }`). It is a stateless, offline-capable verifier — no
+Auth0 Management API, no secrets — wired into a runner so identity is resolved server-side
+at the request boundary, never from the body (CONTRACTS §2).
+
+## Install
+
+```bash
+pnpm add @nightowlsdev/auth-auth0 @nightowlsdev/core
+```
+
+`jose` (^6) is a direct dependency. There are no other peers besides `@nightowlsdev/core`.
+
+## How it verifies (public JWKS only)
+
+- `createRemoteJWKSet(new URL(issuer + ".well-known/jwks.json"))` is built **once at
+  factory scope** — `jose` caches the keys, so repeated requests don't re-fetch.
+- Each request: parse `Authorization: Bearer <jwt>` (the `Bearer` prefix is matched
+  case-insensitively; a missing token returns `null`), then
+  `jwtVerify(token, JWKS, { issuer, audience })`. Any verification failure (bad
+  signature, expired, wrong issuer/audience) returns `null` ⇒ the runner answers `401`.
+- Only **public** signing keys are used. No client secret, no service credential.
+
+### Auth0 issuer needs the trailing slash
+
+Auth0 stamps the `iss` claim as `https://<tenant>.auth0.com/` **with** a trailing slash,
+and the JWKS lives at `<issuer>.well-known/jwks.json`. Pass `issuerBaseUrl` either way —
+the provider normalizes it to end in `/` once at construction, so both
+`https://tenant.auth0.com` and `https://tenant.auth0.com/` work and `jwtVerify`'s
+`issuer` check matches the token exactly.
+
+## Claim mapping
+
+| `AuthContext` | Source | Default |
+|---|---|---|
+| `userId` | `sub` (must be a string) | — (required; non-string ⇒ `null`) |
+| `tenantId` | `payload[orgClaim]` (default `org_id`, if a string) | `'default'` |
+| `capabilities` | `payload[rolesClaim]` (default `permissions`, if an array) | `undefined` |
+
+### `allowedOrgs` fails closed
+
+When `allowedOrgs` is configured, a token is admitted **only** if its org claim is a
+string **and** is in the list. A token with **no** org claim (or a non-string org claim)
+is **rejected** when `allowedOrgs` is set — it is **not** silently dropped into the
+`'default'` tenant. (Without `allowedOrgs`, an org-less token maps to `tenantId:
+'default'` as a single-tenant convenience.)
+
+## Usage
+
+```ts
+import { auth0Auth } from "@nightowlsdev/auth-auth0";
+
+const auth = auth0Auth({
+  issuerBaseUrl: process.env.AUTH0_ISSUER_BASE_URL!, // https://<tenant>.auth0.com/
+  audience: process.env.AUTH0_AUDIENCE!,             // your API identifier
+  // orgClaim: "org_id",        // claim mapped to tenantId
+  // rolesClaim: "permissions", // claim mapped to capabilities (if an array)
+  // allowedOrgs: ["org-123"],  // optional allow-list (fails closed)
+});
+```
+
+Then hand it to a runner:
+
+```ts
+import { createNextjsRunner } from "@nightowlsdev/runner-nextjs";
+const runner = createNextjsRunner({ engine, auth, storage });
+```
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `issuerBaseUrl` | — | Auth0 issuer; trailing slash auto-normalized |
+| `audience` | — | API identifier checked against the `aud` claim |
+| `orgClaim` | `"org_id"` | token claim mapped to `tenantId` |
+| `rolesClaim` | `"permissions"` | token claim mapped to `capabilities` (if an array) |
+| `allowedOrgs` | `undefined` | optional org allow-list; when set, fails closed |
+| `jwks` | remote JWKS | test/advanced override for the key resolver (inject a local JWKS) |
+
+## Testing
+
+The provider accepts an injectable `jwks` resolver, so tests sign a token with a generated
+keypair and verify against a local JWKS (`createLocalJWKSet`) — real RS256 verification,
+fully hermetic, no network and no Auth0 tenant.

package/dist/index.cjs

@@ -0,0 +1,101 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  auth0Auth: () => auth0Auth,
+  nightOwlsPlugin: () => nightOwlsPlugin
+});
+module.exports = __toCommonJS(index_exports);
+var import_jose = require("jose");
+
+// src/plugin.ts
+var nightOwlsPlugin = {
+  name: "auth-auth0",
+  version: "0.0.0",
+  kind: "auth",
+  pkg: "@nightowlsdev/auth-auth0",
+  description: "Auth0 \u2014 verify the access token (RS256/JWKS), map the org claim \u2192 tenant. Install ONE auth provider.",
+  env: [
+    {
+      key: "AUTH0_ISSUER_BASE_URL",
+      example: "https://YOUR_TENANT.us.auth0.com",
+      comment: "Auth0 issuer (the trailing slash is normalized; JWKS resolved from /.well-known/jwks.json)"
+    },
+    { key: "AUTH0_AUDIENCE", example: "", comment: "API identifier the access token is issued for" }
+  ],
+  config: {
+    import: "import { auth0Auth } from '@nightowlsdev/auth-auth0';",
+    snippet: "auth = auth0Auth({ issuerBaseUrl: env.AUTH0_ISSUER_BASE_URL, audience: env.AUTH0_AUDIENCE });",
+    marker: "auth"
+  },
+  // Print-only (idempotent) — runs on init/install + `owl init auth-auth0`. NEVER connects anywhere.
+  init: (ctx) => {
+    ctx.log(
+      "Auth0 auth wired \u2014 set AUTH0_ISSUER_BASE_URL + AUTH0_AUDIENCE. Install ONE auth provider (reconcile a duplicate auth = \u2026 if you installed two)."
+    );
+  },
+  commands: [
+    {
+      name: "info",
+      description: "Show the env + config this auth adapter contributes.",
+      // PURE — no network. Reads only the static manifest data.
+      run: (ctx) => {
+        ctx.log("env: AUTH0_ISSUER_BASE_URL, AUTH0_AUDIENCE");
+        ctx.log("config: auth = auth0Auth({ issuerBaseUrl, audience })");
+      }
+    }
+  ]
+};
+
+// src/index.ts
+function auth0Auth(o) {
+  const orgClaim = o.orgClaim ?? "org_id";
+  const rolesClaim = o.rolesClaim ?? "permissions";
+  const issuer = o.issuerBaseUrl.endsWith("/") ? o.issuerBaseUrl : `${o.issuerBaseUrl}/`;
+  const JWKS = o.jwks ?? (0, import_jose.createRemoteJWKSet)(new URL(`${issuer}.well-known/jwks.json`));
+  return {
+    async authenticate(req) {
+      const jwt = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "");
+      if (!jwt) return null;
+      let payload;
+      try {
+        ({ payload } = await (0, import_jose.jwtVerify)(jwt, JWKS, { issuer, audience: o.audience }));
+      } catch {
+        return null;
+      }
+      const userId = typeof payload.sub === "string" ? payload.sub : null;
+      if (!userId) return null;
+      const org = payload[orgClaim];
+      if (o.allowedOrgs && !(typeof org === "string" && o.allowedOrgs.includes(org))) return null;
+      const roles = payload[rolesClaim];
+      return {
+        tenantId: typeof org === "string" ? org : "default",
+        userId,
+        capabilities: Array.isArray(roles) ? roles : void 0
+      };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  auth0Auth,
+  nightOwlsPlugin
+});

package/dist/index.d.cts

@@ -0,0 +1,68 @@
+import { JWTVerifyGetKey } from 'jose';
+import { AuthProvider } from '@nightowlsdev/core';
+
+/**
+ * The Night Owls adapter plugin manifest for Auth0. `@nightowlsdev/cli` discovers this from the host's installed
+ * `@nightowlsdev/*` deps, dynamic-imports it, and acts on it declaratively:
+ *  - `env`     → merged into `.env.example` (idempotent, only if the KEY is absent),
+ *  - `config`  → the `import` + wiring `snippet` inserted at the `// nightowls:auth` marker (assigns `auth`),
+ *  - `init`    → a print-only hook run after the wiring (it NEVER connects to a DB/network),
+ *  - `commands`→ `owl auth-auth0 <cmd>` subcommands (e.g. `info` — pure, no network).
+ *
+ * Auth providers are MUTUALLY EXCLUSIVE — install ONE (`auth-auth0` OR `auth-supabase`). If you install
+ * both, reconcile the duplicate `auth = …` assignment in `nightowls.config.ts` (keep one).
+ *
+ * This object STRUCTURALLY matches the CLI's `NightOwlsPlugin` type but does NOT import it (no dependency
+ * cycle): all codegen lives in `@nightowlsdev/cli`; this adapter stays data-only. The `init`/command handler
+ * contexts are typed STRUCTURALLY (local `Ctx`/inline shapes) — never importing `@nightowlsdev/cli`.
+ */
+/** Structural context for this adapter's pure command handlers — matches the CLI's PluginCommandContext. */
+type Ctx = {
+    cwd: string;
+    log: (m: string) => void;
+    args: string[];
+    options: Record<string, unknown>;
+};
+declare const nightOwlsPlugin: {
+    readonly name: "auth-auth0";
+    readonly version: "0.0.0";
+    readonly kind: "auth";
+    readonly pkg: "@nightowlsdev/auth-auth0";
+    readonly description: "Auth0 — verify the access token (RS256/JWKS), map the org claim → tenant. Install ONE auth provider.";
+    readonly env: readonly [{
+        readonly key: "AUTH0_ISSUER_BASE_URL";
+        readonly example: "https://YOUR_TENANT.us.auth0.com";
+        readonly comment: "Auth0 issuer (the trailing slash is normalized; JWKS resolved from /.well-known/jwks.json)";
+    }, {
+        readonly key: "AUTH0_AUDIENCE";
+        readonly example: "";
+        readonly comment: "API identifier the access token is issued for";
+    }];
+    readonly config: {
+        readonly import: "import { auth0Auth } from '@nightowlsdev/auth-auth0';";
+        readonly snippet: "auth = auth0Auth({ issuerBaseUrl: env.AUTH0_ISSUER_BASE_URL, audience: env.AUTH0_AUDIENCE });";
+        readonly marker: "auth";
+    };
+    readonly init: (ctx: {
+        cwd: string;
+        log: (m: string) => void;
+    }) => void;
+    readonly commands: readonly [{
+        readonly name: "info";
+        readonly description: "Show the env + config this auth adapter contributes.";
+        readonly run: (ctx: Ctx) => void;
+    }];
+};
+
+interface Auth0AuthOpts {
+    issuerBaseUrl: string;
+    audience: string;
+    orgClaim?: string;
+    rolesClaim?: string;
+    allowedOrgs?: string[];
+    /** Test/advanced override for the JWKS resolver. Defaults to createRemoteJWKSet(issuer + .well-known/jwks.json). */
+    jwks?: JWTVerifyGetKey;
+}
+declare function auth0Auth(o: Auth0AuthOpts): AuthProvider;
+
+export { type Auth0AuthOpts, auth0Auth, nightOwlsPlugin };

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import { JWTVerifyGetKey } from 'jose';
+import { AuthProvider } from '@nightowlsdev/core';
+
+/**
+ * The Night Owls adapter plugin manifest for Auth0. `@nightowlsdev/cli` discovers this from the host's installed
+ * `@nightowlsdev/*` deps, dynamic-imports it, and acts on it declaratively:
+ *  - `env`     → merged into `.env.example` (idempotent, only if the KEY is absent),
+ *  - `config`  → the `import` + wiring `snippet` inserted at the `// nightowls:auth` marker (assigns `auth`),
+ *  - `init`    → a print-only hook run after the wiring (it NEVER connects to a DB/network),
+ *  - `commands`→ `owl auth-auth0 <cmd>` subcommands (e.g. `info` — pure, no network).
+ *
+ * Auth providers are MUTUALLY EXCLUSIVE — install ONE (`auth-auth0` OR `auth-supabase`). If you install
+ * both, reconcile the duplicate `auth = …` assignment in `nightowls.config.ts` (keep one).
+ *
+ * This object STRUCTURALLY matches the CLI's `NightOwlsPlugin` type but does NOT import it (no dependency
+ * cycle): all codegen lives in `@nightowlsdev/cli`; this adapter stays data-only. The `init`/command handler
+ * contexts are typed STRUCTURALLY (local `Ctx`/inline shapes) — never importing `@nightowlsdev/cli`.
+ */
+/** Structural context for this adapter's pure command handlers — matches the CLI's PluginCommandContext. */
+type Ctx = {
+    cwd: string;
+    log: (m: string) => void;
+    args: string[];
+    options: Record<string, unknown>;
+};
+declare const nightOwlsPlugin: {
+    readonly name: "auth-auth0";
+    readonly version: "0.0.0";
+    readonly kind: "auth";
+    readonly pkg: "@nightowlsdev/auth-auth0";
+    readonly description: "Auth0 — verify the access token (RS256/JWKS), map the org claim → tenant. Install ONE auth provider.";
+    readonly env: readonly [{
+        readonly key: "AUTH0_ISSUER_BASE_URL";
+        readonly example: "https://YOUR_TENANT.us.auth0.com";
+        readonly comment: "Auth0 issuer (the trailing slash is normalized; JWKS resolved from /.well-known/jwks.json)";
+    }, {
+        readonly key: "AUTH0_AUDIENCE";
+        readonly example: "";
+        readonly comment: "API identifier the access token is issued for";
+    }];
+    readonly config: {
+        readonly import: "import { auth0Auth } from '@nightowlsdev/auth-auth0';";
+        readonly snippet: "auth = auth0Auth({ issuerBaseUrl: env.AUTH0_ISSUER_BASE_URL, audience: env.AUTH0_AUDIENCE });";
+        readonly marker: "auth";
+    };
+    readonly init: (ctx: {
+        cwd: string;
+        log: (m: string) => void;
+    }) => void;
+    readonly commands: readonly [{
+        readonly name: "info";
+        readonly description: "Show the env + config this auth adapter contributes.";
+        readonly run: (ctx: Ctx) => void;
+    }];
+};
+
+interface Auth0AuthOpts {
+    issuerBaseUrl: string;
+    audience: string;
+    orgClaim?: string;
+    rolesClaim?: string;
+    allowedOrgs?: string[];
+    /** Test/advanced override for the JWKS resolver. Defaults to createRemoteJWKSet(issuer + .well-known/jwks.json). */
+    jwks?: JWTVerifyGetKey;
+}
+declare function auth0Auth(o: Auth0AuthOpts): AuthProvider;
+
+export { type Auth0AuthOpts, auth0Auth, nightOwlsPlugin };

package/dist/index.js

@@ -0,0 +1,75 @@
+// src/index.ts
+import { createRemoteJWKSet, jwtVerify } from "jose";
+
+// src/plugin.ts
+var nightOwlsPlugin = {
+  name: "auth-auth0",
+  version: "0.0.0",
+  kind: "auth",
+  pkg: "@nightowlsdev/auth-auth0",
+  description: "Auth0 \u2014 verify the access token (RS256/JWKS), map the org claim \u2192 tenant. Install ONE auth provider.",
+  env: [
+    {
+      key: "AUTH0_ISSUER_BASE_URL",
+      example: "https://YOUR_TENANT.us.auth0.com",
+      comment: "Auth0 issuer (the trailing slash is normalized; JWKS resolved from /.well-known/jwks.json)"
+    },
+    { key: "AUTH0_AUDIENCE", example: "", comment: "API identifier the access token is issued for" }
+  ],
+  config: {
+    import: "import { auth0Auth } from '@nightowlsdev/auth-auth0';",
+    snippet: "auth = auth0Auth({ issuerBaseUrl: env.AUTH0_ISSUER_BASE_URL, audience: env.AUTH0_AUDIENCE });",
+    marker: "auth"
+  },
+  // Print-only (idempotent) — runs on init/install + `owl init auth-auth0`. NEVER connects anywhere.
+  init: (ctx) => {
+    ctx.log(
+      "Auth0 auth wired \u2014 set AUTH0_ISSUER_BASE_URL + AUTH0_AUDIENCE. Install ONE auth provider (reconcile a duplicate auth = \u2026 if you installed two)."
+    );
+  },
+  commands: [
+    {
+      name: "info",
+      description: "Show the env + config this auth adapter contributes.",
+      // PURE — no network. Reads only the static manifest data.
+      run: (ctx) => {
+        ctx.log("env: AUTH0_ISSUER_BASE_URL, AUTH0_AUDIENCE");
+        ctx.log("config: auth = auth0Auth({ issuerBaseUrl, audience })");
+      }
+    }
+  ]
+};
+
+// src/index.ts
+function auth0Auth(o) {
+  const orgClaim = o.orgClaim ?? "org_id";
+  const rolesClaim = o.rolesClaim ?? "permissions";
+  const issuer = o.issuerBaseUrl.endsWith("/") ? o.issuerBaseUrl : `${o.issuerBaseUrl}/`;
+  const JWKS = o.jwks ?? createRemoteJWKSet(new URL(`${issuer}.well-known/jwks.json`));
+  return {
+    async authenticate(req) {
+      const jwt = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "");
+      if (!jwt) return null;
+      let payload;
+      try {
+        ({ payload } = await jwtVerify(jwt, JWKS, { issuer, audience: o.audience }));
+      } catch {
+        return null;
+      }
+      const userId = typeof payload.sub === "string" ? payload.sub : null;
+      if (!userId) return null;
+      const org = payload[orgClaim];
+      if (o.allowedOrgs && !(typeof org === "string" && o.allowedOrgs.includes(org))) return null;
+      const roles = payload[rolesClaim];
+      return {
+        tenantId: typeof org === "string" ? org : "default",
+        userId,
+        capabilities: Array.isArray(roles) ? roles : void 0
+      };
+    }
+  };
+}
+export {
+  auth0Auth,
+  nightOwlsPlugin
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@nightowlsdev/auth-auth0",
+  "version": "0.1.1",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cueplusplus/corale.git",
+    "directory": "packages/auth-auth0"
+  },
+  "homepage": "https://github.com/cueplusplus/corale#readme",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "jose": "^6.2.3"
+  },
+  "peerDependencies": {
+    "@nightowlsdev/core": "0.3.0"
+  },
+  "devDependencies": {
+    "tsup": "8.5.1",
+    "typescript": "6.0.3",
+    "vitest": "^3.2.0",
+    "@nightowlsdev/eslint-config": "0.0.0",
+    "@nightowlsdev/tsconfig": "0.0.0",
+    "@nightowlsdev/core": "0.3.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
+}