create-soda 0.2.1 → 0.2.2

package/dist/index.js

@@ -1230,17 +1230,18 @@ import { stdin as stdin2, stdout as stdout2 } from "node:process";
 import { fileURLToPath } from "node:url";
 import { styleText as styleText3 } from "node:util";
 // ../core/package.json
-var version = "0.2.1";
+var version = "0.2.2";
 // package.json
-var version2 = "0.2.1";
+var version2 = "0.2.2";
 
 // src/project.ts
+import { randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
 import { cp, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
 var TEMPLATES = [
   { name: "minimal", label: "Minimal", hint: "a module, a controller, a service and a test" },
-  { name: "demo", label: "Demo", hint: "users with validation, a guard, logging and CORS" }
+  { name: "demo", label: "Demo", hint: "JWT sign-in with cookies, typed config, users with validation, CORS" }
 ];
 var RENAMED = { _gitignore: ".gitignore", "_oxlintrc.json": ".oxlintrc.json" };
 var formatTargetDir = (dir) => dir.trim().replace(/[<>:"\\|?*]/g, "").replace(/\/+$/, "");
@@ -1260,6 +1261,15 @@ var emptyDir = async (dir) => {
     }
   }
 };
+var writeEnv = async (root) => {
+  const example = join(root, ".env.example");
+  const env = join(root, ".env");
+  if (!existsSync(example) || existsSync(env)) {
+    return;
+  }
+  const content = await readFile(example, "utf8");
+  await writeFile(env, content.replace(/^(\w+_SECRET)=$/gm, (_, key) => `${key}=${randomBytes(32).toString("base64url")}`));
+};
 var createProject = async (options) => {
   const root = resolve(options.dir);
   await cp(options.template, root, { recursive: true });
@@ -1268,6 +1278,7 @@ var createProject = async (options) => {
       await rename(join(root, from), join(root, to));
     }
   }
+  await writeEnv(root);
   const manifestPath = join(root, "package.json");
   const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
   manifest.name = options.name ?? toValidPackageName(basename(root));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-soda",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Create a Soda project: bun create soda my-app",
   "keywords": [
     "soda",

package/templates/demo/.env.example

@@ -0,0 +1,5 @@
+# Copied to .env by create-soda, with a random secret. Bun loads .env by itself.
+PORT=3000
+CORS_ORIGIN=*
+# Signs access tokens: random, 32 bytes or more (openssl rand -base64 32).
+JWT_SECRET=

package/templates/demo/README.md

@@ -13,13 +13,17 @@ bun run build    # bundles src/main.ts into dist/
 bun start:prod   # runs the bundle
 ```
 
-- `src/main.ts`: creates the application, CORS, graceful shutdown.
-- `src/users`: a module with a service, a controller and a test.
-- `src/auth/auth.guard.ts`: a guard passing the current user to handlers.
+- `src/config.ts`: the configuration, read from `.env` and checked at startup.
+- `src/auth`: sign-in with JWT, returned as a token and set as an httpOnly cookie.
+- `src/users`: a module with a service and a controller; writes need a token.
+- `src/app.test.ts`: tests over HTTP, with the configuration replaced.
+
+`.env` was created from `.env.example` with a random `JWT_SECRET`; it is not committed.
 
 Try it:
 
 ```bash
-curl -X POST localhost:3000/users -H 'authorization: Bearer ann' -H 'content-type: application/json' -d '{"name":"Bo"}'
+TOKEN=$(curl -s localhost:3000/auth/login -H 'content-type: application/json' -d '{"name":"ann"}' | jq -r .token)
+curl -X POST localhost:3000/users -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"name":"Bo"}'
 curl localhost:3000/users/1
 ```

package/templates/demo/src/app.module.ts

@@ -1,5 +1,7 @@
-import { Module } from '@getsoda/core'
+import { ConfigModule, Module } from '@getsoda/core'
+import { AuthModule } from './auth/auth.module.ts'
+import { AppConfig } from './config.ts'
 import { UsersModule } from './users/users.module.ts'
 
-@Module({ imports: [UsersModule] })
+@Module({ imports: [ConfigModule.forRoot({ load: [AppConfig], global: true }), AuthModule, UsersModule] })
 export class AppModule {}

package/templates/demo/src/app.test.ts

@@ -0,0 +1,73 @@
+import { afterAll, describe, expect, test } from 'bun:test'
+import { createApp, provide } from '@getsoda/core'
+import { AppModule } from './app.module.ts'
+import { AppConfig } from './config.ts'
+
+// Tests do not depend on .env: the configuration is replaced.
+const app = await createApp(AppModule, {
+  logger: false,
+  overrides: [provide(AppConfig, { useValue: { PORT: 0, CORS_ORIGIN: '*', JWT_SECRET: 'a-test-secret-of-at-least-32-characters' } })],
+})
+const server = await app.listen(0)
+const url = (path: string) => new URL(path, server.url)
+
+afterAll(() => app.close())
+
+const login = async (name: string) => {
+  const response = await fetch(url('/auth/login'), {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ name }),
+  })
+
+  return { response, token: ((await response.json()) as { token: string }).token }
+}
+
+describe('auth', () => {
+  test('signs in with a token in the body and an httpOnly cookie', async () => {
+    const { response, token } = await login('ann')
+    const cookie = response.headers.getSetCookie()[0]!
+
+    expect(response.status).toBe(201)
+    expect(cookie).toStartWith(`token=${token};`)
+    expect(cookie).toContain('HttpOnly')
+    expect(await (await fetch(url('/auth/me'), { headers: { authorization: `Bearer ${token}` } })).json()).toEqual({ name: 'ann' })
+    expect(await (await fetch(url('/auth/me'), { headers: { cookie: `token=${token}` } })).json()).toEqual({ name: 'ann' })
+  })
+
+  test('refuses requests without a valid token', async () => {
+    const anonymous = await fetch(url('/auth/me'))
+    const forged = await fetch(url('/auth/me'), { headers: { authorization: 'Bearer a.b.c' } })
+
+    expect([anonymous.status, forged.status]).toEqual([401, 401])
+  })
+})
+
+describe('users', () => {
+  test('are created by signed-in users, and read by anyone', async () => {
+    const { token } = await login('ann')
+    const created = await fetch(url('/users'), {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ name: 'Bo' }),
+    })
+
+    expect(created.status).toBe(201)
+    expect(await created.json()).toEqual({ id: 1, name: 'Bo', createdBy: 'ann' })
+    expect(await (await fetch(url('/users/1'))).json()).toEqual({ id: 1, name: 'Bo', createdBy: 'ann' })
+  })
+
+  test('refuses anonymous writes, invalid bodies and unknown users', async () => {
+    const { token } = await login('ann')
+    const anonymous = await fetch(url('/users'), { method: 'POST', body: '{}' })
+    const invalid = await fetch(url('/users'), {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ name: '' }),
+    })
+
+    expect(anonymous.status).toBe(401)
+    expect(invalid.status).toBe(400)
+    expect((await fetch(url('/users/999'))).status).toBe(404)
+  })
+})

package/templates/demo/src/auth/auth.controller.ts

@@ -0,0 +1,39 @@
+import { body, Controller, context, Get, HttpCode, inject, Post, UseGuards, value } from '@getsoda/core'
+import type { Context } from '@getsoda/core'
+import { JWT_PAYLOAD, JwtGuard, JwtService } from '@getsoda/core/jwt'
+import type { JwtPayload } from '@getsoda/core/jwt'
+import { z } from 'zod'
+import { TOKEN_COOKIE, TOKEN_LIFETIME } from './token.ts'
+
+const Login = z.object({ name: z.string().trim().min(1) })
+
+@Controller('auth')
+export class AuthController {
+  readonly #jwt = inject(JwtService)
+
+  /**
+   * Signs anyone in by name: check a password or another credential here.
+   * The token is returned for API clients and set as a cookie for browsers,
+   * where scripts cannot read it.
+   */
+  @Post('login', [body(Login), context()])
+  async login(input: z.infer<typeof Login>, ctx: Context): Promise<{ token: string }> {
+    const token = await this.#jwt.sign({ sub: input.name })
+
+    ctx.cookies.set(TOKEN_COOKIE, token, { httpOnly: true, secure: true, sameSite: 'strict', maxAge: TOKEN_LIFETIME })
+
+    return { token }
+  }
+
+  @Post('logout', [context()])
+  @HttpCode(204)
+  logout(ctx: Context): void {
+    ctx.cookies.delete(TOKEN_COOKIE)
+  }
+
+  @Get('me', [value(JWT_PAYLOAD)])
+  @UseGuards(JwtGuard)
+  me(payload: JwtPayload): { name: string | undefined } {
+    return { name: payload.sub }
+  }
+}

package/templates/demo/src/auth/auth.module.ts

@@ -0,0 +1,17 @@
+import { Module } from '@getsoda/core'
+import { JwtModule } from '@getsoda/core/jwt'
+import { AppConfig } from '../config.ts'
+import { AuthController } from './auth.controller.ts'
+import { TOKEN_COOKIE, TOKEN_LIFETIME } from './token.ts'
+
+@Module({
+  imports: [
+    JwtModule.registerAsync({
+      inject: [AppConfig],
+      useFactory: (config) => ({ secret: config.JWT_SECRET, expiresIn: TOKEN_LIFETIME, cookie: TOKEN_COOKIE }),
+      global: true,
+    }),
+  ],
+  controllers: [AuthController],
+})
+export class AuthModule {}

package/templates/demo/src/auth/token.ts

@@ -0,0 +1,5 @@
+/** Cookie holding the token for browsers; `JwtGuard` reads it when there is no `Authorization` header. */
+export const TOKEN_COOKIE = 'token'
+
+/** Lifetime of a token, in seconds. */
+export const TOKEN_LIFETIME = 60 * 60

package/templates/demo/src/config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from '@getsoda/core'
+import { z } from 'zod'
+
+/** Read from the environment and checked at startup: an invalid value stops the application. */
+export const AppConfig = defineConfig(
+  'app',
+  z.object({
+    PORT: z.coerce.number().int().default(3000),
+    CORS_ORIGIN: z.string().default('*'),
+    JWT_SECRET: z.string().min(32, 'must be at least 32 characters: openssl rand -base64 32'),
+  })
+)

package/templates/demo/src/main.ts

@@ -1,9 +1,10 @@
 import { cors, createApp } from '@getsoda/core'
 import { AppModule } from './app.module.ts'
+import { AppConfig } from './config.ts'
 
-const app = await createApp(AppModule, {
-  middleware: [cors({ origin: process.env.CORS_ORIGIN ?? '*' })],
-})
+// Loaded first for what the application needs before it exists; services inject it.
+const config = await AppConfig.load()
+const app = await createApp(AppModule, { middleware: [cors({ origin: config.CORS_ORIGIN })] })
 
 app.enableShutdownSignals()
-await app.listen(Number(process.env.PORT ?? 3000))
+await app.listen(config.PORT)

package/templates/demo/src/users/users.controller.ts

@@ -1,7 +1,7 @@
 import { body, Controller, Get, inject, int, NotFoundException, param, Post, UseGuards, value } from '@getsoda/core'
+import { JWT_PAYLOAD, JwtGuard } from '@getsoda/core/jwt'
+import type { JwtPayload } from '@getsoda/core/jwt'
 import { z } from 'zod'
-import { AuthGuard, CURRENT_USER } from '../auth/auth.guard.ts'
-import type { CurrentUser } from '../auth/auth.guard.ts'
 import { UsersService } from './users.service.ts'
 import type { User } from './users.service.ts'
 
@@ -27,9 +27,9 @@ export class UsersController {
     return user
   }
 
-  @Post([body(CreateUser), value(CURRENT_USER)])
-  @UseGuards(AuthGuard)
-  create(input: z.infer<typeof CreateUser>, currentUser: CurrentUser): User {
-    return this.#users.create(input.name, currentUser.name)
+  @Post([body(CreateUser), value(JWT_PAYLOAD)])
+  @UseGuards(JwtGuard)
+  create(input: z.infer<typeof CreateUser>, author: JwtPayload): User {
+    return this.#users.create(input.name, author.sub ?? 'unknown')
   }
 }

package/templates/demo/src/auth/auth.guard.ts

@@ -1,26 +0,0 @@
-import { ContextKey } from '@getsoda/core'
-import type { CanActivate, Context } from '@getsoda/core'
-
-export interface CurrentUser {
-  readonly name: string
-}
-
-/** The user the guard found; handlers read it with `ctx.get(CURRENT_USER)` or `value(CURRENT_USER)`. */
-export const CURRENT_USER = new ContextKey<CurrentUser>('currentUser')
-
-/**
- * Accepts `Authorization: Bearer <name>`. A placeholder: verify real tokens here.
- */
-export class AuthGuard implements CanActivate {
-  canActivate(ctx: Context): boolean {
-    const header = ctx.header('authorization')
-
-    if (header === undefined || !header.startsWith('Bearer ')) {
-      return false
-    }
-
-    ctx.set(CURRENT_USER, { name: header.slice('Bearer '.length) })
-
-    return true
-  }
-}

package/templates/demo/src/users/users.test.ts

@@ -1,34 +0,0 @@
-import { afterAll, expect, test } from 'bun:test'
-import { createApp } from '@getsoda/core'
-import { AppModule } from '../app.module.ts'
-
-const app = await createApp(AppModule, { logger: false })
-const server = await app.listen(0)
-const url = (path: string) => new URL(path, server.url)
-
-afterAll(() => app.close())
-
-test('creates a user when authenticated', async () => {
-  const response = await fetch(url('/users'), {
-    method: 'POST',
-    headers: { authorization: 'Bearer ann', 'content-type': 'application/json' },
-    body: JSON.stringify({ name: 'Bo' }),
-  })
-
-  expect(response.status).toBe(201)
-  expect(await response.json()).toEqual({ id: 1, name: 'Bo', createdBy: 'ann' })
-  expect(await (await fetch(url('/users/1'))).json()).toEqual({ id: 1, name: 'Bo', createdBy: 'ann' })
-})
-
-test('refuses anonymous writes, invalid bodies and unknown users', async () => {
-  const anonymous = await fetch(url('/users'), { method: 'POST', body: '{}' })
-  const invalid = await fetch(url('/users'), {
-    method: 'POST',
-    headers: { authorization: 'Bearer ann', 'content-type': 'application/json' },
-    body: JSON.stringify({ name: '' }),
-  })
-
-  expect(anonymous.status).toBe(403)
-  expect(invalid.status).toBe(400)
-  expect((await fetch(url('/users/999'))).status).toBe(404)
-})