create-authenik8-app 2.4.3 → 2.4.5

package/README.md

@@ -34,12 +34,13 @@
 
 Create a new project:
 
-```
-bash
+```bash
 npx create-authenik8-app my-app
 
 cd my-app
 
+npm run prisma:migrate
+
 redis-server --daemonize yes
 
 npm run dev
@@ -112,12 +113,24 @@ Generated automatically:
 The CLI generates these automatically:
 
 ```
+DATABASE_URL=file:./dev.db
 JWT_SECRET=your-secret
 REFRESH_SECRET=your-refresh-secret
 REDIS_HOST=127.0.0.1
 REDIS_PORT=6379
 ```
 
+For Full Auth (Password + OAuth), also set:
+
+```bash
+GOOGLE_CLIENT_ID=your-google-client-id
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+GOOGLE_REDIRECT_URI=http://localhost:3000/auth/google/callback
+GITHUB_CLIENT_ID=your-github-client-id
+GITHUB_CLIENT_SECRET=your-github-client-secret
+GITHUB_REDIRECT_URI=http://localhost:3000/auth/github/callback
+```
+
 
 ---
 
@@ -162,7 +175,142 @@ This design makes future additions (MFA, WebAuthn, etc.) much cleaner.
 ---
 ## Powered by
 
-authenik8-core (v1.0.29)  battle-tested identity & token engine
+authenik8-core (v1.0.33)  identity & token engine(beta)
+
+---
+
+## How authenik8-core works in generated apps
+
+Generated projects call:
+
+```ts
+const auth = await createAuthenik8({
+  jwtSecret: requiredSecret("JWT_SECRET"),
+  refreshSecret: requiredSecret("REFRESH_SECRET"),
+  oauth: {
+    google: {
+      clientId: requiredEnv("GOOGLE_CLIENT_ID"),
+      clientSecret: requiredEnv("GOOGLE_CLIENT_SECRET"),
+      redirectUri: requiredEnv("GOOGLE_REDIRECT_URI"),
+    },
+    github: {
+      clientId: requiredEnv("GITHUB_CLIENT_ID"),
+      clientSecret: requiredEnv("GITHUB_CLIENT_SECRET"),
+      redirectUri: requiredEnv("GITHUB_REDIRECT_URI"),
+    },
+  },
+});
+```
+
+That factory returns one auth object used by the generated routes:
+
+• `signToken(payload)` creates access tokens.
+
+• `verifyToken(token)` verifies access tokens.
+
+• `generateRefreshToken(payload)` creates stateful refresh tokens.
+
+• `refreshToken(refreshToken)` rotates refresh tokens and returns a new access/refresh pair.
+
+• `helmet`, `rateLimit`, and `ipWhitelist` are Express middleware.
+
+• `requireAdmin` protects admin-only routes by checking `role: "admin"`.
+
+• `oauth.google` and `oauth.github` provide redirect and callback handlers.
+
+• `issueTokensFromProfile(profile)` turns a verified OAuth profile into app tokens through the Identity Engine.
+
+### Redis-backed token lifecycle
+
+Authenik8-core intentionally makes JWT auth stateful:
+
+1. Access tokens are signed with `JWT_SECRET`.
+2. Refresh tokens are signed with `REFRESH_SECRET` and include a unique `jti`.
+3. The current valid refresh token is stored in Redis under `refresh:<userId>`.
+4. Refresh calls acquire a Redis lock with `lock:<userId>`.
+5. The submitted refresh token must match the Redis value.
+6. A new access token and refresh token are issued.
+7. The new refresh token atomically replaces the old one.
+8. Reusing the old refresh token fails.
+
+This is why Redis is required. It enables refresh-token replay protection, concurrent refresh protection, and server-side session control.
+
+### OAuth identity resolution
+
+OAuth is not handled as separate unrelated Passport-style strategies. Provider callbacks are normalized into this profile shape:
+
+```ts
+{
+  email: "user@example.com",
+  name: "User Name",
+  provider: "google",
+  providerId: "provider-user-id",
+  email_verified: true
+}
+```
+
+The Identity Engine then decides:
+
+• Existing provider login: provider is already linked, so tokens are issued.
+
+• New user creation: no matching identity exists, so a new user identity is created.
+
+• Link required: an email match exists but policy requires explicit account linking.
+
+• Link provider: an authenticated user links Google or GitHub to their existing account.
+
+OAuth state is stored in Redis for five minutes under `oauth:state:<state>`, and Redis-backed identity records use:
+
+```text
+oauth:v1:user:<userId>
+oauth:v1:email:<email>
+oauth:v1:provider:<provider>:<providerId>
+```
+
+### Security middleware
+
+Generated apps use the middleware returned by core:
+
+```ts
+app.use(auth.helmet);
+app.use(auth.rateLimit);
+```
+
+`helmet` applies secure HTTP headers. `rateLimit` is Redis-backed and defaults to 100 requests per 60 seconds with a 300-second block. `ipWhitelist` is available for stricter APIs and allows localhost by default.
+
+### Common core errors
+
+• `MissingTokenError`: no refresh token was sent.
+
+• `InvalidTokenError`: refresh token is invalid, expired, reused, or replaced.
+
+• `Concurrent refresh detected`: two refresh requests tried to rotate the same token at once.
+
+• `OAuthError:Invalid or expired state`: OAuth callback state is missing from Redis.
+
+• `OAuth profile email must be verified before issuing tokens`: provider email was not verified.
+
+• `Provider already linked to another user`: account linking tried to attach an already-owned provider.
+
+---
+
+## Threat Model
+
+Generated apps include a `THREAT_MODEL.md` file. It explains:
+
+• what the generated app protects,
+
+• what `authenik8-core` handles with Redis-backed token state,
+
+• what threats remain your responsibility,
+
+• and what must be configured before production.
+
+Key protections include refresh-token replay detection, concurrent refresh locking, OAuth state validation, verified-email OAuth token issuance, Redis-backed rate limiting, secure headers, session tracking, and admin-route checks.
+
+Key non-goals include frontend XSS protection, CSRF for cookie-based auth, object-level authorization, MFA/WebAuthn, password reset, provider dashboard security, and protection from leaked secrets.
+
+Before production, replace generated secrets, keep Redis private, use HTTPS, review CORS, configure exact OAuth callback URLs, and add business-level authorization checks to your own routes.
 
 ---
 
@@ -289,4 +437,3 @@ The Identity Engine is what makes Authenik8 feel like a coherent **authenticatio
 • MFA
 
 • Production presets
-

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "create-authenik8-app",
-  "version": "2.4.3",
-  "description": "⚡ Fast Express + TypeScript auth starter with secure JWT, refresh rotation, Redis, RBAC, OAuth & Prisma.\nPowered by the Authenik8 Identity Engine.",
+  "version": "2.4.5",
+  "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/index.js"
+    "create-authenik8-app": "dist/src/bin/index.js"
   },
   "keywords": [
     "cli",
@@ -35,7 +35,8 @@
     "fs-extra": "^11.3.4",
     "inquirer": "^13.3.2",
     "ora": "^9.3.0",
-    "tsx": "^4.21.0"
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
   },
   "files": [
     "dist",
@@ -45,22 +46,23 @@
     "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",
+    "build": "tsc && cp -r ./templates/express-auth/package.json ./templates/THREAT_MODEL.md dist/templates"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^25.5.2",
     "@types/supertest": "^7.2.0",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/coverage-v8": "^4.1.8",
     "supertest": "^7.2.2",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.8"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/COD434/create-authenik8-app.git"
   },
   "overrides": {
-    "brace-expansion": "3.0.2"
+    "brace-expansion": "2.0.2"
   }
 }

package/templates/THREAT_MODEL.md

@@ -0,0 +1,138 @@
+# Authenik8 Generated App Threat Model
+
+This document describes what a generated Authenik8 app is designed to help with, what it does not solve for you, and what you must configure before production use.
+
+## System Boundary
+
+A generated app includes:
+
+- Express API routes.
+- JWT access tokens.
+- Redis-backed refresh-token rotation.
+- Prisma database schema.
+- Optional Google/GitHub OAuth.
+- Authenik8 security middleware: Helmet, rate limiting, and optional IP whitelist.
+- Optional PM2 production process config.
+
+External systems are outside the generated app boundary:
+
+- Browser or mobile frontend.
+- OAuth provider dashboards.
+- Redis hosting.
+- SQL database hosting.
+- TLS termination and reverse proxy.
+- Secret management.
+- Email delivery, MFA, and password reset flows unless you add them.
+
+## Assets Protected
+
+- Access tokens.
+- Refresh tokens.
+- OAuth authorization state.
+- OAuth identity records.
+- User IDs, emails, roles, and provider links.
+- Redis-backed session state.
+- Admin-only routes.
+
+## Trust Assumptions
+
+- `JWT_SECRET` and `REFRESH_SECRET` are long, random, private values.
+- 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.
+
+## 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.
+
+### 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.
+
+### Stateless JWT logout limitations
+
+Access-token sessions are persisted in Redis under `sessions:<userId>`. Admin helpers can list sessions and revoke one or all sessions for a user.
+
+### Basic request flooding
+
+`auth.rateLimit` uses Redis-backed rate limiting. Generated apps apply it globally by default.
+
+### Common HTTP header risks
+
+`auth.helmet` applies secure HTTP headers through Helmet.
+
+### OAuth CSRF/state tampering
+
+OAuth redirects generate random state and store it in Redis for five minutes under `oauth:state:<state>`. Callback handlers reject missing, invalid, or expired state.
+
+### Duplicate OAuth identities
+
+OAuth profiles are normalized into provider, provider ID, email, name, and email verification status. The Identity Engine checks provider and email records before creating a new identity.
+
+### Unverified OAuth email token issuance
+
+`issueTokensFromProfile` rejects OAuth profiles whose email is not verified.
+
+### Admin-route access
+
+`auth.requireAdmin` checks for a valid JWT with `role: "admin"`.
+
+## Threats Not Fully Addressed
+
+### XSS in your frontend
+
+If frontend JavaScript is compromised, tokens stored in memory or browser storage can be stolen. Use a strong frontend CSP, avoid unsafe HTML rendering, and choose token storage deliberately.
+
+### CSRF for cookie-based auth
+
+Generated examples use bearer tokens. If you move tokens into cookies, add CSRF protection and strict cookie settings.
+
+### Weak or leaked secrets
+
+Authenik8 cannot protect tokens if `JWT_SECRET` or `REFRESH_SECRET` is short, reused, committed, logged, or leaked.
+
+### Public Redis exposure
+
+Redis must not be reachable from the public internet. Use private networking, authentication, TLS where available, and provider-level access controls.
+
+### Database authorization bugs
+
+Authenik8 authenticates users and provides route middleware. Your application must still enforce object-level authorization, ownership checks, and tenant isolation.
+
+### Password reset, email verification, MFA, and WebAuthn
+
+These are not included unless you add them.
+
+### OAuth provider compromise or misconfiguration
+
+Provider dashboard settings, app approval screens, callback URLs, and provider secrets must be managed outside the generated app.
+
+### Brute-force protection per credential
+
+Global rate limiting is included. Add stricter per-email or per-account login throttling for high-risk apps.
+
+### Token theft before expiry
+
+Short-lived access tokens reduce exposure, but a stolen access token can be used until it expires or is rejected by your session policy.
+
+## Production Checklist
+
+- Replace generated development secrets with long random values.
+- Run Redis on private networking.
+- Run Postgres or your database on private networking.
+- Use HTTPS only.
+- Set exact OAuth callback URLs in Google/GitHub dashboards.
+- Use `npx prisma migrate deploy` in production.
+- 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-core` and generated dependencies updated.
+
+## Security Reporting
+
+If you find a vulnerability in the generated app or Authenik8-core integration, do not publish exploit details publicly first. Open a private security report or contact the maintainer through the repository security policy.

package/templates/express-auth/README.md

@@ -0,0 +1,196 @@
+# Authenik8 Express Password API
+
+Generated by `create-authenik8-app`.
+
+## Start
+
+```bash
+npm install
+npm run docker:up
+npm run prisma:migrate
+npm run dev
+```
+
+For SQLite, Postgres in `docker-compose.yml` is optional. Redis is required for refresh-token rotation and replay protection.
+
+## Environment
+
+Review `.env` before running. The generated secrets are development placeholders and must be replaced before deployment.
+
+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
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+```
+
+## API Contract
+
+Register:
+
+```http
+POST /auth/register
+Content-Type: application/json
+
+{
+  "email": "dev@example.com",
+  "password": "password123"
+}
+```
+
+Login:
+
+```http
+POST /auth/login
+Content-Type: application/json
+
+{
+  "email": "dev@example.com",
+  "password": "password123"
+}
+```
+
+Refresh:
+
+```http
+POST /auth/refresh
+Content-Type: application/json
+
+{
+  "refreshToken": "<refreshToken>"
+}
+```
+
+Protected:
+
+```http
+GET /protected
+Authorization: Bearer <accessToken>
+```
+
+## 3-Minute Verification
+
+Start the API in one terminal:
+
+```bash
+npm run docker:up
+npm run prisma:migrate
+npm run dev
+```
+
+Register a user:
+
+```bash
+curl -s -X POST http://localhost:3000/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"email":"dev@example.com","password":"password123"}'
+```
+
+Login and save the response:
+
+```bash
+curl -s -X POST http://localhost:3000/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"dev@example.com","password":"password123"}'
+```
+
+Expected shape:
+
+```json
+{
+  "user": {
+    "id": "user-id",
+    "email": "dev@example.com"
+  },
+  "accessToken": "access-token",
+  "refreshToken": "refresh-token"
+}
+```
+
+Call a protected route:
+
+```bash
+curl http://localhost:3000/protected \
+  -H "Authorization: Bearer <accessToken>"
+```
+
+Refresh an access token:
+
+```bash
+curl -s -X POST http://localhost:3000/auth/refresh \
+  -H "Content-Type: application/json" \
+  -d '{"refreshToken":"<refreshToken>"}'
+```
+
+## 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.
+- `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.
+
+## Frontend Use
+
+Store the access token in memory and use the refresh token only through your chosen secure storage strategy. Add the access token to API requests with the `Authorization` header.
+
+```ts
+let accessToken = "";
+let refreshToken = "";
+
+export async function login(email: string, password: string) {
+  const response = await fetch("http://localhost:3000/auth/login", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ email, password }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Login failed: ${response.status}`);
+  }
+
+  const session = await response.json();
+  accessToken = session.accessToken;
+  refreshToken = session.refreshToken;
+  return session;
+}
+
+export async function getProtected() {
+  const response = await fetch("http://localhost:3000/protected", {
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Protected request failed: ${response.status}`);
+  }
+
+  return response.json();
+}
+```
+
+## Troubleshooting
+
+`Redis connection refused`: run `npm run docker:up` or start Redis locally with `redis-server --daemonize yes`.
+
+`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.
+
+`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`.
+
+`DATABASE_URL is wrong`: for SQLite use `file:./dev.db`; for local Docker Postgres use `postgresql://postgres:postgres@localhost:5432/authenik8?schema=public`.
+
+## Threat Model
+
+Read `THREAT_MODEL.md` before deploying. It explains what Authenik8 protects, what Redis-backed token state handles, and what remains your responsibility.
+
+## Deploy
+
+Use `npm run build`, run `npx prisma migrate deploy` for production databases, set real secrets in your host, and point Redis/Postgres env vars at managed services.

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

@@ -0,0 +1,23 @@
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    command: ["redis-server", "--appendonly", "yes"]
+    volumes:
+      - redis-data:/data
+
+  postgres:
+    image: postgres:16-alpine
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: authenik8
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+volumes:
+  redis-data:
+  postgres-data:

package/templates/express-auth/package.json

@@ -7,10 +7,12 @@
     "dev": "ts-node-dev --respawn --transpile-only src/server.ts",
     "build": "tsc",
     "start": "node dist/server.js",
-    "prisma:migrate": "prisma migrate dev"
+    "prisma:migrate": "prisma migrate dev",
+    "docker:up": "docker compose up -d",
+    "docker:down": "docker compose down"
   },
   "dependencies": {
-    "authenik8-core": "^1.0.3",
+    "authenik8-core": "^1.0.33",
     "dotenv": "^16.0.0",
     "express": "^4.19.2",
     "@prisma/client": "5.22.0"

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

@@ -1,4 +1,4 @@
-import express from "express";
+import  express from "express";
 import { createAuthRoutes } from "./routes/auth.routes";
 import { createProtectedRoutes } from "./routes/protected.routes";
 

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

@@ -1,4 +1,4 @@
-import dotenv from "dotenv";
+import  dotenv  from "dotenv";
 import { createAuthenik8 } from "authenik8-core";
 import { createApp } from "./app";
 import { requiredSecret } from "./utils/security";