odoro 1.0.9 → 2.1.0

package/templates/react-ts-server/server/src/modules/auth/index.ts

@@ -0,0 +1,238 @@
+/**
+ * Authentication module — register, sign in, sign out, read your profile.
+ *
+ * ## What this demonstration is, and what it is not
+ *
+ * It is a working account system: a password hashed with `scrypt`, a session
+ * in a table, an `httpOnly` cookie. It is the shape to start from, and it is
+ * deliberately small enough to be read in full before being trusted.
+ *
+ * It is not a complete product. There is no email confirmation, no password
+ * reset, no rate limit on login, no second factor. Each one is a deliberate
+ * addition, and naming them here is more honest than implying they are handled.
+ *
+ * ## Why the session is a cookie, and not a token in the page
+ *
+ * A token kept in `localStorage` is readable by any script that manages to run
+ * on the page. An `httpOnly` cookie is not: the browser sends it and never
+ * hands it over. The cost is a `sameSite` policy to think about, which the
+ * kernel sets to `lax` — enough to block the ordinary cross-site form post,
+ * while an ordinary link still arrives signed in.
+ *
+ * ## Why signing in says so little
+ *
+ * A wrong email and a wrong password give the **same** answer. Distinguishing
+ * them turns the login form into a way to ask whether an address has an
+ * account here — which is exactly what someone assembling a list wants.
+ *
+ * @module
+ */
+
+import {
+  ConflictError,
+  UnauthorizedError,
+  defineModule,
+  route,
+} from '@odoro-cli/server'
+import type { Request } from 'express'
+import { z } from 'zod'
+
+import { hashPassword, verifyPassword } from './password.js'
+import { SESSION_TTL, createAuthStore, type Account, type AuthStore } from './store.js'
+
+/** Name of the session cookie. */
+export const SESSION_COOKIE = 'odoro_session'
+
+/** What a profile shows. */
+const profile = z.object({
+  id: z.string(),
+  email: z.string(),
+  name: z.string(),
+  createdAt: z.string(),
+})
+
+/** What registering asks for. */
+const registration = z.object({
+  email: z.string().email().max(320),
+  name: z.string().min(1).max(80),
+  // Length is the only rule that holds: a composition rule pushes people
+  // towards "Password1!" and nothing else.
+  password: z.string().min(12).max(200),
+})
+
+/** What signing in asks for. */
+const credentials = z.object({
+  email: z.string().email().max(320),
+  password: z.string().min(1).max(200),
+})
+
+/** Renders an account as the interface reads it. */
+function render(account: Account): z.infer<typeof profile> {
+  return {
+    id: account.id,
+    email: account.email,
+    name: account.name,
+    createdAt: account.createdAt.toISOString(),
+  }
+}
+
+/** Reads the session cookie of a request, without a parser dependency. */
+export function readSessionCookie(request: Request): string | undefined {
+  const header = request.headers.cookie
+  if (header === undefined) return undefined
+
+  for (const part of header.split(';')) {
+    const cut = part.indexOf('=')
+    if (cut === -1) continue
+    if (part.slice(0, cut).trim() !== SESSION_COOKIE) continue
+    return decodeURIComponent(part.slice(cut + 1).trim())
+  }
+  return undefined
+}
+
+/**
+ * Builds the guard the kernel calls on every request.
+ *
+ * @example
+ * createApp({ authenticate: createAuthenticator(store), … })
+ */
+export function createAuthenticator(store: AuthStore) {
+  return async (request: Request) => {
+    const sessionId = readSessionCookie(request)
+    if (sessionId === undefined) return undefined
+
+    const session = await store.readSession(sessionId)
+    if (session === undefined) return undefined
+
+    return { id: session.userId, sessionId, organizationId: undefined }
+  }
+}
+
+/**
+ * The module, and the store it owns.
+ *
+ * The store comes back out because the guard needs it too, and because whoever
+ * closes the server has to close its connections.
+ *
+ * ## Why the store can be handed in
+ *
+ * By default the module opens its own, on `DATABASE_URL`. A test hands in a
+ * different one and drives the four routes without a database — which is the
+ * only way to check the cookie, the guard and the answers without provisioning
+ * a server for it.
+ *
+ * @param store The store to use. Absent, one is opened on `DATABASE_URL`.
+ *
+ * @example
+ * const auth = createAuthModule(config)
+ * createApp({ modules: [auth.module], authenticate: auth.authenticate, … })
+ */
+export function createAuthModule(
+  config: { DATABASE_URL: string },
+  store: AuthStore = createAuthStore(config.DATABASE_URL),
+) {
+
+  const module = defineModule({
+    name: 'auth',
+    routes: [
+      route({
+        name: 'auth.register',
+        method: 'POST',
+        path: '/api/auth/register',
+        auth: 'public',
+        summary: 'Creates an account and signs it in.',
+        input: registration,
+        output: profile,
+        handler: async ({ input, cookies }) => {
+          const email = input.email.trim().toLowerCase()
+
+          if ((await store.byEmail(email)) !== undefined) {
+            throw new ConflictError('This address already has an account.')
+          }
+
+          const account = await store.create(
+            email,
+            input.name.trim(),
+            await hashPassword(input.password),
+          )
+
+          cookies.set(SESSION_COOKIE, await store.openSession(account.id), {
+            maxAge: SESSION_TTL,
+          })
+
+          return render(account)
+        },
+      }),
+
+      route({
+        name: 'auth.login',
+        method: 'POST',
+        path: '/api/auth/login',
+        auth: 'public',
+        summary: 'Signs in.',
+        input: credentials,
+        output: profile,
+        handler: async ({ input, cookies }) => {
+          const account = await store.byEmail(input.email.trim().toLowerCase())
+
+          // The same answer in both cases, and the hash is computed even when
+          // the account is absent: answering faster for an unknown address
+          // would tell, by the delay alone, which addresses exist.
+          const stored =
+            account?.password ??
+            'scrypt$65536$8$1$00000000000000000000000000000000$00'
+          const matches = await verifyPassword(input.password, stored)
+
+          if (account === undefined || !matches) {
+            throw new UnauthorizedError('Wrong address or password.')
+          }
+
+          cookies.set(SESSION_COOKIE, await store.openSession(account.id), {
+            maxAge: SESSION_TTL,
+          })
+
+          return render(account)
+        },
+      }),
+
+      route({
+        name: 'auth.logout',
+        method: 'POST',
+        path: '/api/auth/logout',
+        auth: 'optional',
+        summary: 'Signs out.',
+        handler: async ({ user, cookies }) => {
+          // The cookie goes in every case: a session already unknown to the
+          // table must not leave a cookie behind that the browser keeps
+          // sending for a month.
+          if (user !== undefined) await store.closeSession(user.sessionId)
+          cookies.clear(SESSION_COOKIE)
+        },
+      }),
+
+      route({
+        name: 'auth.me',
+        method: 'GET',
+        path: '/api/auth/me',
+        auth: 'required',
+        summary: 'The profile of the signed-in account.',
+        output: profile,
+        handler: async ({ user, cookies }) => {
+          const account = await store.byId(user.id)
+
+          // The session names an account that is gone: the cookie is stale,
+          // and keeping it would make every request fail the same way.
+          if (account === undefined) {
+            await store.closeSession(user.sessionId)
+            cookies.clear(SESSION_COOKIE)
+            throw new UnauthorizedError('This account no longer exists.')
+          }
+
+          return render(account)
+        },
+      }),
+    ] as never,
+  })
+
+  return { module, store, authenticate: createAuthenticator(store) }
+}

package/templates/react-ts-server/server/src/modules/auth/password.ts

@@ -0,0 +1,122 @@
+/**
+ * Hashing and verifying a password.
+ *
+ * ## Why there is no dependency here
+ *
+ * `scrypt` is in the Node standard library, and it is a password hash designed
+ * for the job: slow on purpose, and costly in memory, which is what makes a
+ * rented GPU farm a bad deal for whoever steals the table.
+ *
+ * Argon2 and bcrypt are fine choices too. They are native modules: a compiler
+ * on every machine, a rebuild on every Node upgrade, and a binary in the image.
+ * For the same guarantee, that is a price worth not paying.
+ *
+ * ## What is stored
+ *
+ * `scrypt$N$r$p$salt$hash`, everything in hexadecimal. The parameters travel
+ * with the hash: the day they are raised, the passwords already stored keep
+ * verifying with their own, and each one migrates at its owner's next login.
+ * A hash that does not carry its parameters cannot be migrated without asking
+ * everyone to reset.
+ *
+ * @module
+ */
+
+import { randomBytes, scrypt, timingSafeEqual, type ScryptOptions } from 'node:crypto'
+import { promisify } from 'node:util'
+
+/**
+ * `scrypt`, promised.
+ *
+ * The signature is written out: `promisify` keeps only the first overload of
+ * `scrypt`, the one without options — and the options are exactly what carries
+ * the cost here.
+ */
+const derive = promisify(scrypt) as (
+  password: string,
+  salt: Buffer,
+  keyLength: number,
+  options: ScryptOptions,
+) => Promise<Buffer>
+
+/**
+ * Cost of the derivation.
+ *
+ * `N = 2^16` takes about a hundred milliseconds on an ordinary server, and
+ * asks for 64 MB of memory. That is the knob to turn as machines get faster —
+ * the stored hashes will follow on their own.
+ */
+const COST = { N: 65_536, r: 8, p: 1, keyLength: 32 } as const
+
+/** Length of the salt, in bytes. */
+const SALT = 16
+
+/**
+ * Hashes a password.
+ *
+ * @example
+ * const stored = await hashPassword('correct horse battery staple')
+ */
+export async function hashPassword(password: string): Promise<string> {
+  const salt = randomBytes(SALT)
+  const key = await derive(password, salt, COST.keyLength, {
+    N: COST.N,
+    r: COST.r,
+    p: COST.p,
+    // `scrypt` refuses beyond a default ceiling well below what N = 2^16 asks
+    // for. Raising it is not a weakening: it is the memory the cost demands.
+    maxmem: 256 * COST.N * COST.r,
+  })
+
+  return ['scrypt', COST.N, COST.r, COST.p, salt.toString('hex'), key.toString('hex')].join(
+    '$',
+  )
+}
+
+/**
+ * Verifies a password against a stored hash.
+ *
+ * ## Why it never throws
+ *
+ * A malformed hash — a truncated row, a migration half done — is a failed
+ * verification, not a crash. Throwing here would turn a corrupt row into a
+ * 500 on a login page, which tells an attacker that this account is special.
+ *
+ * @returns `true` if the password matches.
+ *
+ * @example
+ * await verifyPassword('correct horse battery staple', stored) // true
+ */
+export async function verifyPassword(password: string, stored: string): Promise<boolean> {
+  const parts = stored.split('$')
+  if (parts.length !== 6 || parts[0] !== 'scrypt') return false
+
+  const [, rawN, rawR, rawP, rawSalt, rawKey] = parts
+  const N = Number(rawN)
+  const r = Number(rawR)
+  const p = Number(rawP)
+  if (!Number.isInteger(N) || !Number.isInteger(r) || !Number.isInteger(p)) return false
+
+  let expected: Buffer
+  try {
+    expected = Buffer.from(rawKey ?? '', 'hex')
+    if (expected.length === 0) return false
+  } catch {
+    return false
+  }
+
+  try {
+    const key = await derive(password, Buffer.from(rawSalt ?? '', 'hex'), expected.length, {
+      N,
+      r,
+      p,
+      maxmem: 256 * N * r,
+    })
+
+    // Constant time: a comparison that stops at the first differing byte tells,
+    // by how long it took, how many bytes were right.
+    return timingSafeEqual(key, expected)
+  } catch {
+    return false
+  }
+}

package/templates/react-ts-server/server/src/modules/auth/store.ts

@@ -0,0 +1,193 @@
+/**
+ * Where the accounts and the sessions live.
+ *
+ * ## PostgreSQL, and nothing else
+ *
+ * There is no local database in this stack: `DATABASE_URL` points at a hosted
+ * one. So this module refuses clearly when it is missing, rather than falling
+ * back to memory — a demo that works without a database teaches a shape that
+ * stops working the day it is deployed, and does so silently.
+ *
+ * ## The schema creates itself, once
+ *
+ * Two tables, created on first use. That is enough for a demo and for a first
+ * deployment; it is not a migration tool. The day the schema changes shape,
+ * the project needs a real one — and that day, this file is the one to delete.
+ *
+ * ## What is stored of a session
+ *
+ * Its **fingerprint**, not the session itself. Whoever reads the table — a
+ * backup, a support query, a leak — holds hashes, and a hash does not open a
+ * session. The identifier itself only ever exists in the cookie.
+ *
+ * @module
+ */
+
+import { createHash, randomBytes } from 'node:crypto'
+
+import { ServiceUnavailableError } from '@odoro-cli/server'
+import pg from 'pg'
+
+/** An account, as the rest of the module reads it. */
+export interface Account {
+  readonly id: string
+  readonly email: string
+  readonly name: string
+  readonly createdAt: Date
+}
+
+/** An account and the hash that guards it. */
+interface AccountRow extends Account {
+  readonly password: string
+}
+
+/** How long a session lives, in seconds. */
+export const SESSION_TTL = 60 * 60 * 24 * 30
+
+/** The schema, created on first use. */
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS app_user (
+    id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    email       text NOT NULL UNIQUE,
+    name        text NOT NULL,
+    password    text NOT NULL,
+    created_at  timestamptz NOT NULL DEFAULT now()
+  );
+
+  CREATE TABLE IF NOT EXISTS app_session (
+    id          text PRIMARY KEY,
+    user_id     uuid NOT NULL REFERENCES app_user(id) ON DELETE CASCADE,
+    expires_at  timestamptz NOT NULL,
+    created_at  timestamptz NOT NULL DEFAULT now()
+  );
+
+  CREATE INDEX IF NOT EXISTS app_session_user ON app_session(user_id);
+`
+
+/** The fingerprint under which a session identifier is stored. */
+function fingerprint(id: string): string {
+  return createHash('sha256').update(id).digest('hex')
+}
+
+/** What the rest of the module calls. */
+export interface AuthStore {
+  create(email: string, name: string, password: string): Promise<Account>
+  byEmail(email: string): Promise<AccountRow | undefined>
+  byId(id: string): Promise<Account | undefined>
+  openSession(userId: string): Promise<string>
+  readSession(sessionId: string): Promise<{ userId: string } | undefined>
+  closeSession(sessionId: string): Promise<void>
+  dispose(): Promise<void>
+}
+
+/**
+ * Opens the store.
+ *
+ * @param url The `DATABASE_URL`. Empty, every call refuses with a 503 that
+ *   names what is missing — the interface still starts, and says so.
+ *
+ * @example
+ * const store = createAuthStore(config.DATABASE_URL)
+ * await store.create('a@b.c', 'Ada', 'correct horse battery staple')
+ */
+export function createAuthStore(url: string): AuthStore {
+  const configured = url.trim().length > 0
+
+  const absent = (): never => {
+    throw new ServiceUnavailableError(
+      'DATABASE_URL missing: the accounts have nowhere to live. ' +
+        'See .env.example, or run `odoro db:create`.',
+    )
+  }
+
+  const pool = configured
+    ? new pg.Pool({
+        connectionString: url,
+        // A demo does not need twenty connections, and a hosted database
+        // counts them.
+        max: 5,
+      })
+    : undefined
+
+  let ready: Promise<void> | undefined
+
+  /** Creates the schema, once per process. */
+  const ensure = async (): Promise<pg.Pool> => {
+    if (pool === undefined) return absent()
+    ready ??= pool.query(SCHEMA).then(() => undefined)
+    await ready
+    return pool
+  }
+
+  return {
+    async create(email, name, password) {
+      const db = await ensure()
+      const { rows } = await db.query<Account>(
+        `INSERT INTO app_user (email, name, password)
+         VALUES ($1, $2, $3)
+         RETURNING id, email, name, created_at AS "createdAt"`,
+        [email, name, password],
+      )
+      // The row is there: `INSERT ... RETURNING` either returns it or throws.
+      return rows[0] as Account
+    },
+
+    async byEmail(email) {
+      const db = await ensure()
+      const { rows } = await db.query<AccountRow>(
+        `SELECT id, email, name, password, created_at AS "createdAt"
+         FROM app_user WHERE email = $1`,
+        [email],
+      )
+      return rows[0]
+    },
+
+    async byId(id) {
+      const db = await ensure()
+      const { rows } = await db.query<Account>(
+        `SELECT id, email, name, created_at AS "createdAt"
+         FROM app_user WHERE id = $1`,
+        [id],
+      )
+      return rows[0]
+    },
+
+    async openSession(userId) {
+      const db = await ensure()
+
+      // Expired sessions go now, on a query that has nothing else to do. A
+      // scheduled job would be better; this is enough not to keep them
+      // forever, and it costs one index scan per login.
+      await db.query(`DELETE FROM app_session WHERE expires_at <= now()`)
+
+      // 256 bits drawn from the system source. This value never lands in the
+      // table: only its fingerprint does.
+      const id = randomBytes(32).toString('base64url')
+      await db.query(
+        `INSERT INTO app_session (id, user_id, expires_at)
+         VALUES ($1, $2, now() + make_interval(secs => $3))`,
+        [fingerprint(id), userId, SESSION_TTL],
+      )
+      return id
+    },
+
+    async readSession(sessionId) {
+      const db = await ensure()
+      const { rows } = await db.query<{ userId: string }>(
+        `SELECT user_id AS "userId" FROM app_session
+         WHERE id = $1 AND expires_at > now()`,
+        [fingerprint(sessionId)],
+      )
+      return rows[0]
+    },
+
+    async closeSession(sessionId) {
+      const db = await ensure()
+      await db.query(`DELETE FROM app_session WHERE id = $1`, [fingerprint(sessionId)])
+    },
+
+    async dispose() {
+      await pool?.end()
+    },
+  }
+}