create-authenik8-app 2.4.14 → 2.4.15

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

@@ -0,0 +1,109 @@
+import Redis, { type Redis as RedisClient } from "ioredis";
+
+const localRedisUrl = "memory://";
+const redisOptions = {
+  connectTimeout: 5_000,
+  enableReadyCheck: true,
+  maxRetriesPerRequest: 2,
+};
+
+function externalRedisUrl(source: string): string {
+  let url: URL;
+  try {
+    url = new URL(source);
+  } catch {
+    throw new Error("REDIS_URL must be memory://, redis://, or rediss://");
+  }
+
+  if (url.protocol !== "redis:" && url.protocol !== "rediss:") {
+    throw new Error("REDIS_URL must be memory://, redis://, or rediss://");
+  }
+
+  return source;
+}
+
+function redisPort(): number {
+  const port = Number(process.env.REDIS_PORT?.trim() || "6379");
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new Error("REDIS_PORT must be an integer from 1 to 65535");
+  }
+  return port;
+}
+
+function waitForRedis(client: RedisClient): Promise<RedisClient> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let readinessCheckStarted = false;
+    const cleanup = () => {
+      client.off("ready", handleReady);
+      client.off("error", handleError);
+    };
+    const finish = (error?: Error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (error) {
+        client.disconnect();
+        reject(error);
+      } else {
+        resolve(client);
+      }
+    };
+    const handleReady = () => {
+      if (readinessCheckStarted) return;
+      readinessCheckStarted = true;
+      void client.ping().then(() => finish(), (error: Error) => finish(error));
+    };
+    const handleError = (error: Error) => finish(error);
+
+    client.once("ready", handleReady);
+    client.once("error", handleError);
+    if (client.status === "ready") handleReady();
+  });
+}
+
+export async function createRedisClient(): Promise<RedisClient> {
+  const redisUrl = process.env.REDIS_URL?.trim();
+  const nodeEnv = process.env.NODE_ENV?.trim() || "development";
+
+  const hasExternalRedisConfig = Boolean(
+    redisUrl ||
+      process.env.REDIS_HOST?.trim() ||
+      process.env.REDIS_PORT?.trim() ||
+      process.env.REDIS_PASSWORD?.trim(),
+  );
+
+  if (redisUrl === localRedisUrl && nodeEnv === "production") {
+    throw new Error(
+      "REDIS_URL=memory:// is for local development only; use redis:// or rediss:// in production",
+    );
+  }
+
+  const shouldUseMemoryRedis =
+    redisUrl === localRedisUrl ||
+    (!hasExternalRedisConfig && nodeEnv !== "production");
+
+  if (shouldUseMemoryRedis) {
+    const { default: RedisMock } = await import("ioredis-mock");
+    return new RedisMock() as unknown as RedisClient;
+  }
+
+  if (nodeEnv === "production" && !hasExternalRedisConfig) {
+    throw new Error(
+      "REDIS_URL=memory:// is for local development only; use redis:// or rediss:// in production",
+    );
+  }
+
+  if (redisUrl) {
+    return waitForRedis(new Redis(externalRedisUrl(redisUrl), redisOptions));
+  }
+
+  return waitForRedis(new Redis({
+    ...redisOptions,
+    host: process.env.REDIS_HOST?.trim() || "127.0.0.1",
+    port: redisPort(),
+    ...(process.env.REDIS_PASSWORD?.trim()
+      ? { password: process.env.REDIS_PASSWORD.trim() }
+      : {}),
+  }));
+}

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

@@ -13,6 +13,10 @@ export const credentialsSchema = z.strictObject({
   password: passwordSchema,
 });
 
+export const refreshTokenBodySchema = z.strictObject({
+  refreshToken: z.string().trim().min(16, "Refresh token is required").max(4096),
+});
+
 const secretSchema = z.string().trim().min(32);
 const environmentValueSchema = z.string().trim().min(1);
 const portSchema = z.coerce.number().int().min(1).max(65535);
@@ -121,6 +125,14 @@ export function parseCredentials(body: unknown): z.infer<typeof credentialsSchem
   return result.data;
 }
 
+export function parseRefreshToken(body: unknown): string {
+  const result = refreshTokenBodySchema.safeParse(body);
+  if (!result.success) {
+    throw new InputValidationError(validationMessage(result.error, "Refresh token is required"));
+  }
+  return result.data.refreshToken;
+}
+
 export function parseIdentifier(value: unknown, label: string): string {
   const result = identifierSchema.safeParse(value);
   if (!result.success) throw new InputValidationError(`${label} is invalid`);

package/templates/express-base/README.md

@@ -6,12 +6,21 @@ Generated by `create-authenik8-app`.
 
 ```bash
 npm install
-npm run docker:up
-npm run prisma:migrate
+npm run db:migrate
 npm run dev
 ```
 
-For SQLite, Postgres in `docker-compose.yml` is optional. Redis is required for refresh-token security features.
+The generated local environment uses an in-process Redis-compatible store, so Redis and Docker are optional during development. If you selected PostgreSQL, start it with `npm run docker:up` or point `DATABASE_URL` to an existing instance before migrating.
+
+Validate the generated auth configuration and Redis connection at any time:
+
+```bash
+npx create-authenik8-app@latest doctor
+```
+
+`authenik8.json` records the generated architecture and Authenik8 engine version. It contains no secrets and should be committed with the project.
+
+After committing the package-manager lockfile, run `npx create-authenik8-app@latest add ci-github` to add the pinned Doctor and upgrade-policy workflow. Preview it first with `--dry-run`.
 
 ## Environment
 
@@ -27,8 +36,7 @@ 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
+REDIS_URL=memory://
 ```
 
 ## Routes
@@ -51,8 +59,7 @@ Authorization: Bearer <accessToken>
 Start the API in one terminal:
 
 ```bash
-npm run docker:up
-npm run prisma:migrate
+npm run db:migrate
 npm run dev
 ```
 
@@ -78,8 +85,8 @@ Expected result: the route should reject the request because no access token was
 - `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.
+- `REDIS_URL`: use `memory://` for local development or `redis://` / `rediss://` for an external service. Production rejects `memory://`.
+- `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD`: optional external Redis settings used when `REDIS_URL` is omitted.
 
 ## Frontend Fetch Example
 
@@ -101,9 +108,11 @@ export async function getProtected(accessToken: string) {
 
 ## Troubleshooting
 
-`Redis connection refused`: run `npm run docker:up` or start Redis locally with `redis-server --daemonize yes`.
+`Redis connection refused`: verify `REDIS_URL`, or omit it and check `REDIS_HOST`, `REDIS_PORT`, and `REDIS_PASSWORD`.
+
+`Prisma Client did not initialize`: run `npm run db:migrate`, then restart `npm run dev`.
 
-`Prisma Client did not initialize`: run `npm run prisma:migrate`, then restart `npm run dev`.
+`REDIS_URL=memory:// is for local development only`: configure a `redis://` or `rediss://` endpoint before running in production.
 
 `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`.
 
@@ -117,4 +126,4 @@ Read `THREAT_MODEL.md` before deploying. It explains what Authenik8 protects, wh
 
 ## 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.
+Use `npm run build`, run `npx prisma migrate deploy` for production databases, set `NODE_ENV=production`, store real secrets in your host, and point Redis/Postgres environment variables at managed services.

package/templates/express-base/package.json

@@ -1,10 +1,11 @@
 {
   "name": "authenik8-app",
   "scripts": {
-    "dev": "ts-node-dev --respawn --transpile-only ./src/server.ts",
+    "dev": "tsx watch ./src/server.ts",
     "build": "tsc",
     "start": "node dist/src/server.js",
-    "prisma:migrate": "prisma migrate",
+    "db:migrate": "prisma db push && prisma generate",
+    "prisma:migrate": "prisma db push && prisma generate",
     "docker:up": "docker compose up -d --wait",
     "docker:down": "docker compose down"
   },
@@ -12,19 +13,21 @@
     "authenik8-core": "2.0.3",
     "dotenv": "^16.0.0",
     "express": "^4.18.2",
-    "@prisma/client": "7.8.0",
+    "@prisma/client": "7.9.0",
+    "ioredis": "^5.8.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",
     "@types/node": "^22.10.2",
-    "ts-node-dev": "^2.0.0",
-    "typescript": "^5.0.0",
-     "prisma": "7.8.0"
-
+    "ioredis-mock": "8.13.1",
+    "prisma": "7.9.0",
+    "tsx": "^4.22.4",
+    "typescript": "^5.0.0"
   },
   "overrides": {
-    "@hono/node-server": "1.19.13"
+    "find-my-way": "9.7.0",
+    "valibot": "1.4.2"
   },
   "type": "commonjs"
 }

package/templates/express-base/src/.env.example

@@ -5,4 +5,4 @@ AUTHENIK8_AUDIENCE=authenik8-app-api
 AUTHENIK8_AGENTS={}
 REFRESH_SECRET=replace-with-at-least-32-random-characters
 PORT=3000
-REDIS_URL=redis://localhost:6379
+REDIS_URL=memory://

package/templates/express-base/src/config/redis.ts

@@ -0,0 +1,109 @@
+import Redis, { type Redis as RedisClient } from "ioredis";
+
+const localRedisUrl = "memory://";
+const redisOptions = {
+  connectTimeout: 5_000,
+  enableReadyCheck: true,
+  maxRetriesPerRequest: 2,
+};
+
+function externalRedisUrl(source: string): string {
+  let url: URL;
+  try {
+    url = new URL(source);
+  } catch {
+    throw new Error("REDIS_URL must be memory://, redis://, or rediss://");
+  }
+
+  if (url.protocol !== "redis:" && url.protocol !== "rediss:") {
+    throw new Error("REDIS_URL must be memory://, redis://, or rediss://");
+  }
+
+  return source;
+}
+
+function redisPort(): number {
+  const port = Number(process.env.REDIS_PORT?.trim() || "6379");
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new Error("REDIS_PORT must be an integer from 1 to 65535");
+  }
+  return port;
+}
+
+function waitForRedis(client: RedisClient): Promise<RedisClient> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let readinessCheckStarted = false;
+    const cleanup = () => {
+      client.off("ready", handleReady);
+      client.off("error", handleError);
+    };
+    const finish = (error?: Error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (error) {
+        client.disconnect();
+        reject(error);
+      } else {
+        resolve(client);
+      }
+    };
+    const handleReady = () => {
+      if (readinessCheckStarted) return;
+      readinessCheckStarted = true;
+      void client.ping().then(() => finish(), (error: Error) => finish(error));
+    };
+    const handleError = (error: Error) => finish(error);
+
+    client.once("ready", handleReady);
+    client.once("error", handleError);
+    if (client.status === "ready") handleReady();
+  });
+}
+
+export async function createRedisClient(): Promise<RedisClient> {
+  const redisUrl = process.env.REDIS_URL?.trim();
+  const nodeEnv = process.env.NODE_ENV?.trim() || "development";
+
+  const hasExternalRedisConfig = Boolean(
+    redisUrl ||
+      process.env.REDIS_HOST?.trim() ||
+      process.env.REDIS_PORT?.trim() ||
+      process.env.REDIS_PASSWORD?.trim(),
+  );
+
+  if (redisUrl === localRedisUrl && nodeEnv === "production") {
+    throw new Error(
+      "REDIS_URL=memory:// is for local development only; use redis:// or rediss:// in production",
+    );
+  }
+
+  const shouldUseMemoryRedis =
+    redisUrl === localRedisUrl ||
+    (!hasExternalRedisConfig && nodeEnv !== "production");
+
+  if (shouldUseMemoryRedis) {
+    const { default: RedisMock } = await import("ioredis-mock");
+    return new RedisMock() as unknown as RedisClient;
+  }
+
+  if (nodeEnv === "production" && !hasExternalRedisConfig) {
+    throw new Error(
+      "REDIS_URL=memory:// is for local development only; use redis:// or rediss:// in production",
+    );
+  }
+
+  if (redisUrl) {
+    return waitForRedis(new Redis(externalRedisUrl(redisUrl), redisOptions));
+  }
+
+  return waitForRedis(new Redis({
+    ...redisOptions,
+    host: process.env.REDIS_HOST?.trim() || "127.0.0.1",
+    port: redisPort(),
+    ...(process.env.REDIS_PASSWORD?.trim()
+      ? { password: process.env.REDIS_PASSWORD.trim() }
+      : {}),
+  }));
+}

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

@@ -1,6 +1,7 @@
 import  dotenv  from "dotenv";
 import { createAuthenik8 } from "authenik8-core";
 import { createApp } from "../app";
+import { createRedisClient } from "./config/redis";
 import { agentIdentityConfig, authJwkConfig, requiredPort, requiredSecret } from "../utils/security";
 
 dotenv.config();
@@ -10,6 +11,7 @@ async function start() {
     jwt: authJwkConfig(),
     refreshSecret: requiredSecret("REFRESH_SECRET"),
     agent: agentIdentityConfig(),
+    redis: await createRedisClient(),
   });
 
   const app = createApp(auth);

package/templates/fullstack/.env.example

@@ -1,8 +1,9 @@
 NODE_ENV=development
 PORT=3000
 WEB_ORIGIN=http://localhost:5173
-DATABASE_URL=postgresql://postgres:postgres@localhost:5432/authenik8?schema=public
-REDIS_URL=redis://localhost:6379
+DATABASE_URL=postgresql://postgres:postgres@localhost:55432/authenik8?schema=public
+REDIS_URL=memory://
+AUTHENIK8_LOCAL_DATABASE=embedded
 AUTHENIK8_SIGNING_JWKS=
 AUTHENIK8_ACTIVE_KID=
 AUTHENIK8_ISSUER=http://localhost:3000

package/templates/fullstack/PRESET_CONTRACT.md

@@ -15,7 +15,8 @@ This document is the testable contract for the `fullstack` preset.
 
 | Command | Guarantee |
 | --- | --- |
-| `npm run dev` | Builds shared packages and starts API and web together. |
+| `npm run dev` | Starts project-local PostgreSQL, prepares data, then starts API and web together. |
+| `npm run setup` | Starts project-local PostgreSQL for the command, applies migrations, and creates idempotent seed data. |
 | `npm run build` | Produces the API and frontend production bundles. |
 | `npm start` | Starts Express, which serves `/api` and the built SPA. |
 | `npm run db:migrate` | Applies the Prisma PostgreSQL development migration. |
@@ -26,8 +27,11 @@ This document is the testable contract for the `fullstack` preset.
 
 - Vite: `http://localhost:5173`, proxying `/api` to Express.
 - Express: `http://localhost:3000`.
-- PostgreSQL: `localhost:5432` in local Docker Compose.
-- Redis: `localhost:6379` in local Docker Compose.
+- PostgreSQL: project-local PGlite, bound to loopback only while local commands run.
+- Redis: an in-process Redis-compatible store for local development.
+- Docker Compose is optional and explicit through `npm run docker:up`.
+- Set `AUTHENIK8_LOCAL_DATABASE=external` to use `DATABASE_URL` directly.
+- Production requires external PostgreSQL and Redis services.
 - Production uses one origin. Express serves `apps/web/dist` after `npm run build`.
 
 ## Environment contract

package/templates/fullstack/README.md

@@ -8,18 +8,56 @@ agent access without exposing an unsafe public token-minting route.
 
 ## Local development
 
-Requirements: Node.js 20.19+, 22.12+, or 24+, npm, and Docker with Compose.
+Requirements: Node.js 20.19+, 22.12+, or 24+ and npm. Docker is optional.
 
 ```bash
-docker compose up -d
-npm run db:migrate
-npm run db:seed
 npm run dev
 ```
 
-Open `http://localhost:5173`. The API runs on `http://localhost:3000/api`. The generated `.env` contains development values; replace every secret before deploying.
+That one command starts project-local PostgreSQL, applies the shipped migration,
+creates the seed administrator, and starts every development watcher.
+Redis-compatible auth state runs inside the API process during local
+development. Setup is idempotent, so subsequent runs reuse the same database. Open
+`http://localhost:5173`. The API runs on `http://localhost:3000/api`.
 
-The seeded administrator uses `SEED_ADMIN_EMAIL` and `SEED_ADMIN_PASSWORD`. Change the default password immediately, including for local environments shared by multiple people.
+Run setup without starting the watchers when needed:
+
+```bash
+npm run setup
+```
+
+The embedded PostgreSQL server listens only on loopback while a local command is
+running and stores data under `.authenik8/`. No global PostgreSQL, Redis, or
+Docker installation is required. If you provide your own PostgreSQL, set
+`AUTHENIK8_LOCAL_DATABASE=external` and update `DATABASE_URL`.
+
+Docker Compose remains available as an explicit option:
+
+```bash
+npm run docker:up
+```
+
+When using the containers, set `AUTHENIK8_LOCAL_DATABASE=external` and
+`REDIS_URL=redis://localhost:56379`. Production must always use external
+PostgreSQL and a real `redis://` or `rediss://` service. The API rejects the
+in-process Redis setting in production.
+
+The generated `.env` contains development values; replace every secret before deploying.
+
+Validate the workspace auth configuration and selected Redis mode at any time:
+
+```bash
+npx create-authenik8-app@latest doctor
+```
+
+`authenik8.json` records the generated architecture and Authenik8 engine version. It contains no secrets and should be committed with the workspace.
+
+After committing `package-lock.json`, run `npx create-authenik8-app@latest add ci-github` to add the pinned Doctor and upgrade-policy workflow. Preview it first with `--dry-run`.
+
+With an unchanged generated `.env`, sign in with `admin@example.com` and
+`ChangeMe123!`. These values come from `SEED_ADMIN_EMAIL` and
+`SEED_ADMIN_PASSWORD`. Change the password immediately, including for local
+environments shared by multiple people.
 
 ## Application map
 
@@ -62,4 +100,4 @@ Read [docs/PRODUCTION.md](docs/PRODUCTION.md) and [THREAT_MODEL.md](THREAT_MODEL
 - `GET /api/health/ready` checks PostgreSQL and Redis.
 - `GET /api/docs/openapi.json` returns the generated OpenAPI 3.1 contract.
 - `npm test` covers ownership/admin policies, encrypted cookies, origin and CSRF defenses, and the browser storage rule.
-- `npm run typecheck` checks each workspace.
+- `npm run typecheck` builds internal packages, generates Prisma Client, and checks each workspace from a clean checkout.

package/templates/fullstack/apps/api/package.json

@@ -11,16 +11,17 @@
     "build": "tsc -p tsconfig.json",
     "start": "node dist/server.js",
     "test": "vitest run",
+    "pretypecheck": "prisma generate",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prisma:generate": "prisma generate",
-    "prisma:migrate": "prisma migrate dev && prisma generate",
+    "prisma:migrate": "prisma migrate deploy && prisma generate",
     "prisma:seed": "prisma generate && prisma db seed",
     "prisma:studio": "prisma studio"
   },
   "dependencies": {
     "@authenik8/contracts": "0.1.0",
-    "@prisma/adapter-pg": "7.8.0",
-    "@prisma/client": "7.8.0",
+    "@prisma/adapter-pg": "7.9.0",
+    "@prisma/client": "7.9.0",
     "authenik8-core": "2.0.3",
     "bcryptjs": "^2.4.3",
     "cookie-parser": "^1.4.7",
@@ -28,6 +29,7 @@
     "dotenv": "^17.3.1",
     "express": "^5.2.1",
     "ioredis": "^5.10.0",
+    "ioredis-mock": "8.13.1",
     "pino": "^9.7.0",
     "pino-http": "^10.4.0",
     "zod": "^4.4.3"
@@ -39,7 +41,7 @@
     "@types/express": "^5.0.6",
     "@types/node": "^25.0.0",
     "@types/supertest": "^7.2.0",
-    "prisma": "7.8.0",
+    "prisma": "7.9.0",
     "supertest": "^7.2.2",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",