create-authenik8-app 2.4.12 → 2.4.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-authenik8-app",
-  "version": "2.4.12",
+  "version": "2.4.14",
   "description": " Fast Express + TypeScript auth starter with secure JWT, refresh rotation, Redis, RBAC, OAuth & Prisma.\nPowered by the Authenik8 Identity Engine.",
   "bin": {
     "create-authenik8-app": "dist/src/bin/index.js"
@@ -28,27 +28,31 @@
   "license": "MIT",
   "author": "Karabo Seeisa",
   "type": "module",
+  "engines": {
+    "node": "^20.19 || ^22.12 || >=24"
+  },
   "dependencies": {
-    "authenik8-core": "^1.0.38",
-    "bun": "^1.3.12",
+    "@inquirer/core": "^10.3.2",
     "chalk": "^5.6.2",
     "fs-extra": "^11.3.4",
-    "inquirer": "^13.3.2",
-    "ora": "^9.3.0",
-    "tsx": "^4.22.4",
-    "typescript": "^6.0.3"
+    "inquirer": "^12.11.1",
+    "ora": "^8.2.0",
+    "zod": "^4.4.3"
   },
   "files": [
+    "assets/logo.svg",
     "dist/",
     "templates/"
   ],
   "scripts": {
-    "build": "tsc && cp -r ./templates/express-auth/package.json ./templates/THREAT_MODEL.md dist/templates",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "test:templates": "node --import tsx --test tests/template-servers.test.mjs"
+    "test:templates": "node --import tsx --test tests/template-servers.test.mjs",
+    "test:fresh": "node scripts/verify-fresh-project.mjs"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",
@@ -56,8 +60,12 @@
     "@types/node": "^25.9.3",
     "@types/supertest": "^7.2.0",
     "@vitest/coverage-v8": "^4.1.8",
+    "authenik8-core": "2.0.3",
     "fast-check": "^4.8.0",
+    "jose": "6.2.3",
     "supertest": "^7.2.2",
+    "tsx": "^4.23.1",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.8"
   },
   "repository": {

package/templates/AGENT_IDENTITY.md

@@ -0,0 +1,112 @@
+# Agent and service identity
+
+Authenik8 separates human access tokens from AI agents, workers, bots, and
+machine-to-machine callers. Agent tokens use a distinct token type, exact
+`resource:action` scopes, an actor chain, and Redis-backed sessions.
+
+## Enable a development registry
+
+Agent identity is disabled when `AUTHENIK8_AGENTS` is empty or `{}`. For local
+development, map each agent ID to its maximum grant:
+
+```dotenv
+AUTHENIK8_AGENTS='{"build-worker":["tasks:read","tasks:write"]}'
+```
+
+The generated configuration validates the IDs and scopes before startup. For
+production, replace this static environment registry with a database-backed
+`resolveAgent` callback so deactivation and scope removal take effect without a
+deployment.
+
+## Issue an M2M token from a trusted exchange
+
+`issueToken` is a privileged SDK operation, not an authentication endpoint.
+Call it only after authenticating the workload using a mechanism appropriate to
+your infrastructure, such as mTLS, a cloud workload identity, or a signed client
+assertion. Do not expose it as an unauthenticated HTTP route.
+
+```ts
+const agent = auth.agent;
+if (!agent) throw new Error("Agent identity is not configured");
+
+const token = await agent.issueToken({
+  agentId: "build-worker",
+  scopes: ["tasks:read"],
+  label: "production queue worker",
+  ip: request.ip,
+});
+```
+
+Requested scopes must be an exact subset of the registry grant. Tokens are
+short-lived and stored under a separate `agent-sessions:<agentId>` namespace.
+Human middleware rejects them.
+
+## Protect an agent route
+
+```ts
+import type { AgentAuthenticatedRequest } from "authenik8-core";
+
+router.post(
+  "/internal/tasks",
+  auth.agent!.requireScopes("tasks:write"),
+  (req, res) => {
+    const actor = (req as AgentAuthenticatedRequest).agent;
+    res.json({ accepted: true, actor: actor.agentId });
+  },
+);
+```
+
+Every required scope must be present. Scope matching is exact; wildcard scope
+expansion is intentionally not inferred.
+
+## Delegate a human action to an agent
+
+Delegation is disabled unless the application supplies `authorizeDelegation`.
+The callback should check the user, tenant, requested operation, consent, and
+any application permission model.
+
+```ts
+const auth = await createAuthenik8({
+  // jwt, Redis, and refresh configuration omitted
+  agent: {
+    resolveAgent: async (agentId) => agentRepository.findActive(agentId),
+    authorizeDelegation: async ({ user, agent, requestedScopes }) =>
+      user.role === "admin" &&
+      agent.agentId === "build-worker" &&
+      requestedScopes.every((scope) => scope === "tasks:read"),
+  },
+});
+
+const delegated = await auth.agent!.issueDelegatedToken({
+  agentId: "build-worker",
+  userAccessToken,
+  scopes: ["tasks:read"],
+});
+```
+
+The token identifies the user as the subject and the agent as the acting party.
+Its `actorChain` records both actors. Revoking the originating human session
+immediately invalidates the delegated token.
+
+## Revoke agent access
+
+```ts
+await auth.agent!.revokeSession("build-worker", sessionId); // one workload session
+await auth.agent!.revokeAgent("build-worker");              // all sessions + issuance block
+await auth.agent!.activateAgent("build-worker");            // clear the core revocation block
+```
+
+The external registry must still report the agent as active. Removing an agent
+or reducing its scopes in that registry also invalidates existing tokens during
+verification.
+
+## Security boundaries
+
+- Agent tokens are bearer credentials; protect them in memory and transport.
+- Never place agent tokens in browser storage, URLs, logs, or source control.
+- Keep token lifetimes short and re-authenticate the workload to obtain another.
+- Public JWKS verification proves the signature but cannot by itself observe
+  Redis revocation. Security-sensitive APIs should use the session-aware SDK
+  middleware or a trusted introspection boundary.
+- A delegated token never outlives the authority of its originating human
+  session.

package/templates/THREAT_MODEL.md

@@ -13,6 +13,7 @@ A generated app includes:
 - Optional Google/GitHub OAuth.
 - Authenik8 security middleware: Helmet, rate limiting, and optional IP whitelist.
 - Optional PM2 production process config.
+- Optional scoped identities for agents, workers, bots, and M2M callers.
 
 External systems are outside the generated app boundary:
 
@@ -33,26 +34,28 @@ External systems are outside the generated app boundary:
 - User IDs, emails, roles, and provider links.
 - Redis-backed session state.
 - Admin-only routes.
+- Agent registry grants, delegated actor chains, and M2M sessions.
 
 ## Trust Assumptions
 
-- `JWT_SECRET` and `REFRESH_SECRET` are long, random, private values.
+- The active ES256 private JWK and `REFRESH_SECRET` are random, private, and stored outside source control.
 - Redis is private to the app and not exposed to the public internet.
 - Database credentials are private.
 - OAuth callback URLs match provider dashboard settings exactly.
 - Production traffic uses HTTPS.
 - Reverse proxy headers are trusted only when you control the proxy.
 - Developers validate and authorize their own business-domain routes.
+- Applications authenticate workloads before calling privileged agent-token issuance and explicitly authorize every user delegation.
 
 ## Threats Addressed
 
 ### Refresh-token replay
 
-Refresh tokens are stateful. The currently valid refresh token is stored in Redis under `refresh:<userId>`. When a refresh succeeds, Authenik8-core rotates the refresh token and replaces the Redis value. Reusing an old refresh token fails.
+Refresh tokens are stateful. The currently valid token for each session is stored under `refresh:<userId>:<sessionId>`. When a refresh succeeds, Authenik8-core atomically replaces it. Reusing an old refresh token fails and revokes that refresh family.
 
 ### Concurrent refresh abuse
 
-Refresh requests acquire a Redis lock under `lock:<userId>`. Two simultaneous refresh attempts for the same user should not both rotate successfully.
+Refresh requests acquire a Redis lock under `lock:<userId>:<sessionId>`. Two simultaneous refresh attempts for the same session cannot both rotate successfully.
 
 ### Stateless JWT logout limitations
 
@@ -76,12 +79,21 @@ OAuth profiles are normalized into provider, provider ID, email, name, and email
 
 ### Unverified OAuth email token issuance
 
-`issueTokensFromProfile` rejects OAuth profiles whose email is not verified.
+Provider callbacks verify the provider email before the Identity Engine issues an application session.
 
 ### Admin-route access
 
 `auth.requireAdmin` checks for a valid JWT with `role: "admin"`.
 
+### Agent identity and revocation
+
+Human and agent tokens have distinct purposes and middleware. Agent scopes must
+be an exact subset of the live registry grant. M2M sessions are stored under
+`agent-sessions:<agentId>`, and removing a grant, revoking one session, or
+revoking the whole agent invalidates its tokens. Delegated tokens record the
+human and agent actor chain and become invalid when the originating human
+session is revoked.
+
 ## Threats Not Fully Addressed
 
 ### XSS in your frontend
@@ -94,7 +106,7 @@ Generated examples use bearer tokens. If you move tokens into cookies, add CSRF
 
 ### Weak or leaked secrets
 
-Authenik8 cannot protect tokens if `JWT_SECRET` or `REFRESH_SECRET` is short, reused, committed, logged, or leaked.
+Authenik8 cannot protect tokens if the private signing JWK or `REFRESH_SECRET` is committed, logged, reused, or leaked. Public keys from `/.well-known/jwks.json` are safe to distribute.
 
 ### Public Redis exposure
 
@@ -120,6 +132,15 @@ Global rate limiting is included. Add stricter per-email or per-account login th
 
 Short-lived access tokens reduce exposure, but a stolen access token can be used until it expires or is rejected by your session policy.
 
+### Workload authentication and offline agent verification
+
+The SDK issues agent tokens only after trusted application code calls it; your
+application must authenticate the workload using mTLS, cloud workload identity,
+a signed assertion, or another suitable credential. Never expose issuance as an
+unauthenticated route. Agent tokens remain bearer credentials. Public JWKS
+verification cannot observe Redis revocation without a trusted introspection or
+session-aware middleware boundary.
+
 ## Production Checklist
 
 - Replace generated development secrets with long random values.
@@ -131,6 +152,7 @@ Short-lived access tokens reduce exposure, but a stolen access token can be used
 - Review CORS policy before connecting a frontend.
 - Add business-level authorization checks to every protected resource route.
 - Add logging and alerting for refresh failures, OAuth failures, and admin actions.
+- Keep `AUTHENIK8_AGENTS={}` unless agent identity is intentionally configured; review every agent grant and delegation policy.
 - Keep `authenik8-core` and generated dependencies updated.
 
 ## Security Reporting

package/templates/express-auth/README.md

@@ -15,14 +15,18 @@ For SQLite, Postgres in `docker-compose.yml` is optional. Redis is required for
 
 ## Environment
 
-Review `.env` before running. The generated secrets are development placeholders and must be replaced before deployment.
+The generator writes a unique signing key and refresh secret to git-ignored `.env`. Move them into your deployment secret manager and never commit the private JWK.
 
 Required:
 
 ```bash
 DATABASE_URL=file:./dev.db
-JWT_SECRET=dev-jwt-secret-change-before-production-123456
-REFRESH_SECRET=dev-refresh-secret-change-before-production-123456
+AUTHENIK8_SIGNING_JWKS='[{"kty":"EC","crv":"P-256","kid":"<generated>","x":"...","y":"...","d":"...","alg":"ES256"}]'
+AUTHENIK8_ACTIVE_KID=<generated>
+AUTHENIK8_ISSUER=http://localhost:3000
+AUTHENIK8_AUDIENCE=your-app-api
+AUTHENIK8_AGENTS={}
+REFRESH_SECRET=<generated-random-secret>
 REDIS_HOST=127.0.0.1
 REDIS_PORT=6379
 ```
@@ -101,10 +105,6 @@ Expected shape:
 
 ```json
 {
-  "user": {
-    "id": "user-id",
-    "email": "dev@example.com"
-  },
   "accessToken": "access-token",
   "refreshToken": "refresh-token"
 }
@@ -128,7 +128,10 @@ curl -s -X POST http://localhost:3000/auth/refresh \
 ## Environment Variables
 
 - `DATABASE_URL`: Prisma database connection. SQLite uses `file:./dev.db`; Postgres uses a `postgresql://...` URL.
-- `JWT_SECRET`: signs short-lived access tokens. Use a long random value in production.
+- `AUTHENIK8_SIGNING_JWKS`: JSON array containing the active private ES256 key and any previous public verification keys.
+- `AUTHENIK8_ACTIVE_KID`: selects the private key used to sign new access tokens.
+- `AUTHENIK8_ISSUER` / `AUTHENIK8_AUDIENCE`: required claims checked during verification.
+- `AUTHENIK8_AGENTS`: optional JSON map of agent IDs to exact `resource:action` scopes; keep `{}` to disable agent identity. See `AGENT_IDENTITY.md`.
 - `REFRESH_SECRET`: signs refresh tokens. Use a different long random value in production.
 - `REDIS_HOST`: Redis host for refresh-token/session security.
 - `REDIS_PORT`: Redis port, usually `6379` locally.
@@ -177,13 +180,13 @@ export async function getProtected() {
 
 `Prisma Client did not initialize`: run `npm run prisma:migrate`, then restart `npm run dev`.
 
-`JWT_SECRET must be set to at least 32 characters`: check `.env`; both token secrets must be long strings.
+`AUTHENIK8_SIGNING_JWKS must be a valid JSON array`: restore the generated `.env` value or provide an ES256 P-256 key ring and matching `AUTHENIK8_ACTIVE_KID`.
 
 `Cannot POST /auth/login`: confirm the server is running and you generated the password auth template, not the JWT-only base template.
 
 `Invalid email or password`: register the user first, then login with the same email/password.
 
-`Port 3000 already in use`: stop the other process or change the `app.listen(3000)` port in `src/server.ts`.
+`Port 3000 already in use`: stop the other process or set `PORT` in `.env`.
 
 `DATABASE_URL is wrong`: for SQLite use `file:./dev.db`; for local Docker Postgres use `postgresql://postgres:postgres@localhost:5432/authenik8?schema=public`.
 

package/templates/express-auth/docker-compose.yml

@@ -6,6 +6,11 @@ services:
     command: ["redis-server", "--appendonly", "yes"]
     volumes:
       - redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
 
   postgres:
     image: postgres:16-alpine
@@ -17,6 +22,11 @@ services:
       POSTGRES_DB: authenik8
     volumes:
       - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d authenik8"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
 
 volumes:
   redis-data:

package/templates/express-auth/gitignore.template

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.env
+*.log
+coverage/
+.DS_Store

package/templates/express-auth/package.json

@@ -3,25 +3,32 @@
   "description": "Authenik8 generated Express auth app",
   "main": "dist/server.js",
   "type": "commonjs",
+  "engines": {
+    "node": "^20.19 || ^22.12 || >=24"
+  },
   "scripts": {
     "dev": "ts-node-dev --respawn --transpile-only src/server.ts",
     "build": "tsc",
     "start": "node dist/server.js",
-    "prisma:migrate": "prisma migrate dev",
-    "docker:up": "docker compose up -d",
+    "prisma:migrate": "prisma migrate dev && prisma generate",
+    "docker:up": "docker compose up -d --wait",
     "docker:down": "docker compose down"
   },
   "dependencies": {
-    "authenik8-core": "^1.0.38",
+    "authenik8-core": "2.0.3",
     "dotenv": "^16.0.0",
     "express": "^4.19.2",
-    "@prisma/client": "5.22.0"
+    "@prisma/client": "7.8.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",
     "@types/node": "^26.0.1",
     "ts-node-dev": "^2.0.0",
     "typescript": "^5.0.0",
-     "prisma": "5.22.0"
+     "prisma": "7.8.0"
+  },
+  "overrides": {
+    "@hono/node-server": "1.19.13"
   }
 }

package/templates/express-auth/src/app.ts

@@ -10,6 +10,8 @@ export const createApp = (auth: any) => {
   app.use(auth.helmet);
   app.use(auth.rateLimit);
 
+  app.get("/.well-known/jwks.json", (_req, res) => res.json(auth.getJwks()));
+
   app.use("/auth", createAuthRoutes(auth));
   app.use("/", createProtectedRoutes(auth));
 

package/templates/express-auth/src/controllers/auth.controller.ts

@@ -21,14 +21,10 @@ export const createAuthController = (auth: any) => ({
 
       const user = await AuthService.login(email, password);
 
-      const accessToken = auth.signToken({
-        userId: user.id,
-        email: user.email,
-      });
-
-      const refreshToken = await auth.generateRefreshToken({
+      const { accessToken, refreshToken } = await auth.issueTokens({
         userId: user.id,
         email: user.email,
+        role: String(user.role).toLowerCase(),
       });
 
       res.json({ accessToken, refreshToken });

package/templates/express-auth/src/controllers/protected.controller.ts

@@ -1,5 +1,16 @@
 import { Request, Response } from "express";
-import { sanitizeSessionResponse } from "../utils/security";
+import {
+  InputValidationError,
+  parseIdentifier,
+  sanitizeSessionResponse,
+} from "../utils/security";
+
+function sessionError(res: Response, error: unknown, fallback: string) {
+  if (error instanceof InputValidationError) {
+    return res.status(400).json({ success: false, message: error.message });
+  }
+  return res.status(500).json({ success: false, message: fallback });
+}
 
 export const createProtectedController = () => ({
   protected(req: Request, res: Response) {
@@ -13,10 +24,11 @@ export const createProtectedController = () => ({
         return res.status(503).json({ success: false, message: "Session management unavailable" });
       }
 
-      const sessions = await actions.listSessions(req.params.userId);
+      const userId = parseIdentifier(req.params.userId, "User ID");
+      const sessions = await actions.listSessions(userId);
       res.json({ sessions: sanitizeSessionResponse(sessions) });
-    } catch {
-      res.status(500).json({ success: false, message: "Failed to retrieve sessions" });
+    } catch (error) {
+      sessionError(res, error, "Failed to retrieve sessions");
     }
   },
 
@@ -27,10 +39,12 @@ export const createProtectedController = () => ({
         return res.status(503).json({ success: false, message: "Session management unavailable" });
       }
 
-      await actions.revokeSession(req.params.userId, req.params.sessionId);
+      const userId = parseIdentifier(req.params.userId, "User ID");
+      const sessionId = parseIdentifier(req.params.sessionId, "Session ID");
+      await actions.revokeSession(userId, sessionId);
       res.json({ success: true, message: "Session revoked" });
-    } catch {
-      res.status(500).json({ success: false, message: "Failed to revoke session" });
+    } catch (error) {
+      sessionError(res, error, "Failed to revoke session");
     }
   },
 
@@ -41,10 +55,11 @@ export const createProtectedController = () => ({
         return res.status(503).json({ success: false, message: "Session management unavailable" });
       }
 
-      await actions.revokeAllSessions(req.params.userId);
+      const userId = parseIdentifier(req.params.userId, "User ID");
+      await actions.revokeAllSessions(userId);
       res.json({ success: true, message: "All sessions revoked" });
-    } catch {
-      res.status(500).json({ success: false, message: "Failed to revoke sessions" });
+    } catch (error) {
+      sessionError(res, error, "Failed to revoke sessions");
     }
   },
 });

package/templates/express-auth/src/middleware/auth.middleware.ts

@@ -0,0 +1 @@
+export const createAuthMiddleware = (auth: any) => auth.requireAuth;

package/templates/express-auth/src/routes/protected.routes.ts

@@ -1,11 +1,13 @@
 import { Router } from "express";
 import { createProtectedController } from "../controllers/protected.controller";
+import { createAuthMiddleware } from "../middleware/auth.middleware";
 
 export const createProtectedRoutes = (auth: any) => {
   const router = Router();
   const controller = createProtectedController();
+  const requireAuth = createAuthMiddleware(auth);
 
-  router.get("/protected", auth.requireAdmin, controller.protected);
+  router.get("/protected", requireAuth, controller.protected);
   router.get("/admin/sessions/:userId", auth.requireAdmin, controller.listSessions);
   router.delete("/admin/sessions/:userId/:sessionId", auth.requireAdmin, controller.revokeSession);
   router.delete("/admin/sessions/:userId", auth.requireAdmin, controller.revokeAllSessions);

package/templates/express-auth/src/server.ts

@@ -1,20 +1,22 @@
 import  dotenv  from "dotenv";
 import { createAuthenik8 } from "authenik8-core";
 import { createApp } from "./app";
-import { requiredSecret } from "./utils/security";
+import { agentIdentityConfig, authJwkConfig, requiredPort, requiredSecret } from "./utils/security";
 
 dotenv.config();
 
 async function start() {
   const auth = await createAuthenik8({
-    jwtSecret: requiredSecret("JWT_SECRET"),
+    jwt: authJwkConfig(),
     refreshSecret: requiredSecret("REFRESH_SECRET"),
+    agent: agentIdentityConfig(),
   });
 
   const app = createApp(auth);
 
-  app.listen(3000, () => {
-    console.log(" Server running on http://localhost:3000");
+  const port = requiredPort();
+  app.listen(port, () => {
+    console.log(` Server running on http://localhost:${port}`);
   });
 }
 process.on("uncaughtException", (err) => {
@@ -27,12 +29,4 @@ process.on("unhandledRejection", (err) => {
   process.exit(1);
 
 });
-setInterval(() => {
-  const used = process.memoryUsage().heapUsed / 1024 / 1024;
-
-  if (used > 300) {
-    console.error(`Memory exceeded: ${used.toFixed(2)} MB`);
-    process.exit(1);
-  }
-}, 10000);
 start();