create-authenik8-app 2.4.3 → 2.4.5

package/templates/express-auth+/README.md

@@ -0,0 +1,247 @@
+# Authenik8 Express Password + OAuth 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
+AUTHENIK8_OAUTH_PROVIDERS=google,github
+```
+
+OAuth provider config is only required for providers listed in `AUTHENIK8_OAUTH_PROVIDERS`.
+
+```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
+```
+
+## 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>"
+}
+```
+
+OAuth:
+
+```http
+GET /auth/google
+GET /auth/google/callback
+GET /auth/github
+GET /auth/github/callback
+GET /auth/google/link
+GET /auth/github/link
+```
+
+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>"
+```
+
+Test OAuth redirect setup in a browser:
+
+```text
+http://localhost:3000/auth/google
+http://localhost:3000/auth/github
+```
+
+If a provider is not listed in `AUTHENIK8_OAUTH_PROVIDERS`, that provider route returns a clear `404` JSON response.
+
+## 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.
+- `AUTHENIK8_OAUTH_PROVIDERS`: comma-separated enabled providers, for example `google`, `github`, or `google,github`.
+- `GOOGLE_REDIRECT_URI`: must exactly match the callback URL configured in Google Cloud.
+- `GITHUB_REDIRECT_URI`: must exactly match the callback URL configured in GitHub OAuth Apps.
+
+## 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. For OAuth, redirect the browser to `/auth/google` or `/auth/github`.
+
+```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();
+}
+
+export function loginWithGoogle() {
+  window.location.href = "http://localhost:3000/auth/google";
+}
+```
+
+## OAuth Callback Setup
+
+Google callback URL:
+
+```text
+http://localhost:3000/auth/google/callback
+```
+
+GitHub callback URL:
+
+```text
+http://localhost:3000/auth/github/callback
+```
+
+The callback URL in `.env` must match the provider dashboard exactly, including protocol, host, port, and path.
+
+## 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 or OAuth auth template.
+
+`OAuth redirect_uri_mismatch`: copy the callback URL from `.env` into the provider dashboard exactly.
+
+`github OAuth is not configured`: add `github` to `AUTHENIK8_OAUTH_PROVIDERS` and set the GitHub env vars, or use only the enabled provider route.
+
+`google OAuth is not configured`: add `google` to `AUTHENIK8_OAUTH_PROVIDERS` and set the Google env vars, or use only the enabled provider route.
+
+`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,17 +7,19 @@
     "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"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",
-    "@types/node": "^20.0.0",
+    "@types/node": "^25.9.1",
     "ts-node-dev": "^2.0.0",
     "typescript": "^5.0.0",
      "prisma": "5.22.0"

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

@@ -1,30 +1,20 @@
 import { createAuthenik8 } from "authenik8-core";
-import dotenv from "dotenv";
-import { requiredEnv, requiredSecret } from "../utils/security";
+import dotenv  from "dotenv";
+import { requiredSecret } from "../utils/security";
 
 dotenv.config();
 
 let authInstance: any;
 
-
+function oauthConfig() {
+  return {};
+}
 
 export async function initAuth() {
   authInstance= 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"),
-      },
-    },
+    oauth: oauthConfig(),
   });
 
 }

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

@@ -0,0 +1 @@
+export const oauthController = {};

package/templates/express-auth+/src/auth/{password.controller.ts → controllers/password.controller.ts}

@@ -1,8 +1,8 @@
 import { Request, Response } from "express";
-import { getAuth } from "./auth";
-import { prisma } from "../prisma/client";
-import { hashPassword, comparePassword } from "../utils/hash";
-import { parseCredentials } from "../utils/security";
+import { getAuth } from "../auth";
+import { prisma } from "../../prisma/client";
+import { hashPassword, comparePassword } from "../../utils/hash";
+import { parseCredentials } from "../../utils/security";
 
 export const passwordController = {
   async register(req: Request, res: Response) {

package/templates/express-auth+/src/auth/{protected.controller.ts → controllers/protected.controller.ts}

@@ -1,8 +1,8 @@
 import { Request, Response } from "express";
-import { sanitizeSessionResponse } from "../utils/security";
+import { sanitizeSessionResponse } from "../../utils/security";
 
 export const protectedController = {
-  protected(req: Request, res: Response) {
+  protected( res: Response) {
     res.json({ message: "Protected route" });
   },
 

package/templates/express-auth+/src/auth/{auth.middleware.ts → middleware/auth.middleware.ts}

@@ -1,5 +1,5 @@
 import { Request, Response, NextFunction } from "express";
-import { getAuth } from "./auth";
+import { getAuth } from "../auth";
 
 export const adminMiddleware = (req: Request, res: Response, next: NextFunction) => {
   getAuth().requireAdmin(req, res, next);

package/templates/express-auth+/src/auth/routes/oauth.routes.ts

@@ -0,0 +1,5 @@
+import express from "express";
+
+const router = express.Router();
+
+export default router;

package/templates/express-auth+/src/auth/{password.route.ts → routes/password.route.ts}

@@ -1,5 +1,5 @@
 import express from "express";
-import { passwordController } from "./password.controller";
+import { passwordController } from "../controllers/password.controller";
 
 const router = express.Router();
 

package/templates/express-auth+/src/auth/{protected.routes.ts → routes/protected.routes.ts}

@@ -1,6 +1,6 @@
 import express from "express";
-import { adminMiddleware } from "./auth.middleware";
-import { protectedController } from "./protected.controller";
+import { adminMiddleware } from "../middleware/auth.middleware";
+import { protectedController } from "../controllers/protected.controller";
 
 const router = express.Router();
 

package/templates/express-auth+/src/oauth-providers/github/src/auth/auth.ts

@@ -0,0 +1,42 @@
+import { createAuthenik8 } from "authenik8-core";
+import dotenv  from "dotenv";
+import { requiredEnv, requiredSecret } from "../../../../src/utils/security";
+
+dotenv.config();
+
+let authInstance: any;
+
+function oauthConfig() {
+  return {
+    github: {
+        clientId: requiredEnv("GITHUB_CLIENT_ID"),
+        clientSecret: requiredEnv("GITHUB_CLIENT_SECRET"),
+        redirectUri: requiredEnv("GITHUB_REDIRECT_URI"),
+      },
+  };
+}
+
+export async function initAuth() {
+  authInstance= await createAuthenik8({
+    jwtSecret: requiredSecret("JWT_SECRET"),
+    refreshSecret: requiredSecret("REFRESH_SECRET"),
+    oauth: oauthConfig(),
+  });
+
+}
+export function getAuth() {
+  if (!authInstance) {
+    throw new Error("Auth not initialized. Call initAuth() first.");
+  }
+
+  return authInstance;
+}
+
+export const auth = new Proxy(
+  {},
+  {
+    get(_target, property) {
+      return getAuth()[property as keyof ReturnType<typeof getAuth>];
+    },
+  },
+) as any;

package/templates/express-auth+/src/oauth-providers/github/src/auth/oauth.controller.ts

@@ -0,0 +1,37 @@
+import { Request, Response } from "express";
+import { getAuth } from "./auth";
+
+type OAuthProvider = "github";
+
+function requireProvider(provider: OAuthProvider, res: Response) {
+  const oauthProvider = getAuth().oauth?.[provider];
+
+  if (!oauthProvider) {
+    res.status(404).json({ error: `${provider} OAuth is not configured` });
+    return undefined;
+  }
+
+  return oauthProvider;
+}
+
+export const oauthController = {
+  githubRedirect(req: Request, res: Response) {
+    requireProvider("github", res)?.redirect(req, res);
+  },
+
+  async githubCallback(req: Request, res: Response) {
+    const provider = requireProvider("github", res);
+    if (!provider) return;
+
+    const result = await provider.handleCallback(req);
+
+    res.json({
+      provider: "github",
+      ...result,
+    });
+  },
+
+  githubLink(req: Request, res: Response) {
+    requireProvider("github", res)?.redirect(req, res, "link");
+  },
+};

package/templates/express-auth+/src/oauth-providers/github/src/auth/oauth.routes.ts

@@ -0,0 +1,11 @@
+import express from "express";
+import { authMiddleware } from "./auth.middleware";
+import { oauthController } from "./oauth.controller";
+
+const router = express.Router();
+
+router.get("/github", oauthController.githubRedirect);
+router.get("/github/callback", oauthController.githubCallback);
+router.get("/github/link", authMiddleware, oauthController.githubLink);
+
+export default router;

package/templates/express-auth+/src/oauth-providers/google/src/auth/auth.ts

@@ -0,0 +1,42 @@
+import { createAuthenik8 } from "authenik8-core";
+import dotenv  from "dotenv";
+import { requiredEnv, requiredSecret } from "../../../../src/utils/security";
+
+dotenv.config();
+
+let authInstance: any;
+
+function oauthConfig() {
+  return {
+    google: {
+        clientId: requiredEnv("GOOGLE_CLIENT_ID"),
+        clientSecret: requiredEnv("GOOGLE_CLIENT_SECRET"),
+        redirectUri: requiredEnv("GOOGLE_REDIRECT_URI"),
+      },
+  };
+}
+
+export async function initAuth() {
+  authInstance= await createAuthenik8({
+    jwtSecret: requiredSecret("JWT_SECRET"),
+    refreshSecret: requiredSecret("REFRESH_SECRET"),
+    oauth: oauthConfig(),
+  });
+
+}
+export function getAuth() {
+  if (!authInstance) {
+    throw new Error("Auth not initialized. Call initAuth() first.");
+  }
+
+  return authInstance;
+}
+
+export const auth = new Proxy(
+  {},
+  {
+    get(_target, property) {
+      return getAuth()[property as keyof ReturnType<typeof getAuth>];
+    },
+  },
+) as any;

package/templates/express-auth+/src/oauth-providers/google/src/auth/oauth.controller.ts

@@ -0,0 +1,37 @@
+import { Request, Response } from "express";
+import { getAuth } from "./auth";
+
+type OAuthProvider = "google";
+
+function requireProvider(provider: OAuthProvider, res: Response) {
+  const oauthProvider = getAuth().oauth?.[provider];
+
+  if (!oauthProvider) {
+    res.status(404).json({ error: `${provider} OAuth is not configured` });
+    return undefined;
+  }
+
+  return oauthProvider;
+}
+
+export const oauthController = {
+  googleRedirect(req: Request, res: Response) {
+    requireProvider("google", res)?.redirect(req, res);
+  },
+
+  async googleCallback(req: Request, res: Response) {
+    const provider = requireProvider("google", res);
+    if (!provider) return;
+
+    const result = await provider.handleCallback(req);
+
+    res.json({
+      provider: "google",
+      ...result,
+    });
+  },
+
+  googleLink(req: Request, res: Response) {
+    requireProvider("google", res)?.redirect(req, res, "link");
+  },
+};

package/templates/express-auth+/src/oauth-providers/google/src/auth/oauth.routes.ts

@@ -0,0 +1,11 @@
+import express from "express";
+import { authMiddleware } from "./auth.middleware";
+import { oauthController } from "./oauth.controller";
+
+const router = express.Router();
+
+router.get("/google", oauthController.googleRedirect);
+router.get("/google/callback", oauthController.googleCallback);
+router.get("/google/link", authMiddleware, oauthController.googleLink);
+
+export default router;

package/templates/express-auth+/src/oauth-providers/google-github/src/auth/auth.ts

@@ -0,0 +1,47 @@
+import { createAuthenik8 } from "authenik8-core";
+import dotenv  from "dotenv";
+import { requiredEnv, requiredSecret } from "../utils/security";
+
+dotenv.config();
+
+let authInstance: any;
+
+function oauthConfig() {
+  return {
+    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"),
+      },
+  };
+}
+
+export async function initAuth() {
+  authInstance= await createAuthenik8({
+    jwtSecret: requiredSecret("JWT_SECRET"),
+    refreshSecret: requiredSecret("REFRESH_SECRET"),
+    oauth: oauthConfig(),
+  });
+
+}
+export function getAuth() {
+  if (!authInstance) {
+    throw new Error("Auth not initialized. Call initAuth() first.");
+  }
+
+  return authInstance;
+}
+
+export const auth = new Proxy(
+  {},
+  {
+    get(_target, property) {
+      return getAuth()[property as keyof ReturnType<typeof getAuth>];
+    },
+  },
+) as any;

package/templates/express-auth+/src/oauth-providers/google-github/src/auth/oauth.controller.ts

@@ -0,0 +1,57 @@
+import { Request, Response } from "express";
+import { getAuth } from "./auth";
+
+type OAuthProvider = "google" | "github";
+
+function requireProvider(provider: OAuthProvider, res: Response) {
+  const oauthProvider = getAuth().oauth?.[provider];
+
+  if (!oauthProvider) {
+    res.status(404).json({ error: `${provider} OAuth is not configured` });
+    return undefined;
+  }
+
+  return oauthProvider;
+}
+
+export const oauthController = {
+  googleRedirect(req: Request, res: Response) {
+    requireProvider("google", res)?.redirect(req, res);
+  },
+
+  async googleCallback(req: Request, res: Response) {
+    const provider = requireProvider("google", res);
+    if (!provider) return;
+
+    const result = await provider.handleCallback(req);
+
+    res.json({
+      provider: "google",
+      ...result,
+    });
+  },
+
+  googleLink(req: Request, res: Response) {
+    requireProvider("google", res)?.redirect(req, res, "link");
+  },
+
+  githubRedirect(req: Request, res: Response) {
+    requireProvider("github", res)?.redirect(req, res);
+  },
+
+  async githubCallback(req: Request, res: Response) {
+    const provider = requireProvider("github", res);
+    if (!provider) return;
+
+    const result = await provider.handleCallback(req);
+
+    res.json({
+      provider: "github",
+      ...result,
+    });
+  },
+
+  githubLink(req: Request, res: Response) {
+    requireProvider("github", res)?.redirect(req, res, "link");
+  },
+};