@rashidee/co2 1.2.5

package/plugin/skills/specgen-node-cli-web/references/auth-patterns.md

@@ -0,0 +1,293 @@
+# Authentication & User Lifecycle Patterns — specgen-node-cli-web
+
+Canonical patterns for first-run bootstrap (root spec Section 8), authentication
+(Section 9), and the mandatory `user-management/SPEC.md`. These are security invariants:
+PRD phrasing never weakens them — flag conflicts to the user instead of complying.
+
+Tier-2 hand-rolled sessions, `node:crypto` only. The spec MUST NOT include: email flows
+of any kind, self-serve registration, OAuth/social login, JWTs, or password recovery
+other than `reset-admin` (CLI) and admin-reset (UI).
+
+## 1. Schema
+
+```
+users:    id, username (unique, case-insensitive), password_hash,
+          role ('admin' | 'user'), must_change_password (bool),
+          created_at, updated_at
+sessions: id, token_hash (SHA-256 of 32-byte random token),
+          user_id FK (cascade delete), expires_at, created_at
+```
+
+Drizzle definition:
+
+```ts
+import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
+
+export const users = sqliteTable('users', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  username: text('username').notNull().unique(), // stored lowercased; compare lowercased
+  passwordHash: text('password_hash').notNull(), // "salt:hash", hex
+  role: text('role', { enum: ['admin', 'user'] }).notNull(),
+  mustChangePassword: integer('must_change_password', { mode: 'boolean' })
+    .notNull()
+    .default(false),
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull(),
+})
+
+export const sessions = sqliteTable('sessions', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  tokenHash: text('token_hash').notNull().unique(),
+  userId: integer('user_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' }),
+  expiresAt: integer('expires_at', { mode: 'timestamp' }).notNull(),
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
+})
+```
+
+## 2. Password hashing (scrypt)
+
+scrypt via `node:crypto` — N=2^15, r=8, p=1, 32-byte key, 16-byte random salt; stored as
+`salt:hash`. Verify with `timingSafeEqual`:
+
+```ts
+import { scryptSync, randomBytes, timingSafeEqual } from 'node:crypto'
+
+const SCRYPT_PARAMS = { N: 2 ** 15, r: 8, p: 1, maxmem: 64 * 1024 * 1024 }
+const KEY_LENGTH = 32
+
+export function hashPassword(password: string): string {
+  const salt = randomBytes(16)
+  const hash = scryptSync(password, salt, KEY_LENGTH, SCRYPT_PARAMS)
+  return `${salt.toString('hex')}:${hash.toString('hex')}`
+}
+
+export function verifyPassword(password: string, stored: string): boolean {
+  const [saltHex, hashHex] = stored.split(':')
+  if (!saltHex || !hashHex) return false
+  const candidate = scryptSync(password, Buffer.from(saltHex, 'hex'), KEY_LENGTH, SCRYPT_PARAMS)
+  return timingSafeEqual(candidate, Buffer.from(hashHex, 'hex'))
+}
+```
+
+## 3. Password policy (shared Zod schema in core/)
+
+NIST 800-63B posture: minimum 10 characters, reject the username as password, NO
+composition-class rules. One schema in `core/`, consumed by both the SPA form and the API
+route:
+
+```ts
+import { z } from 'zod'
+
+export const passwordSchema = z.string().min(10, 'At least 10 characters')
+
+export const changePasswordSchema = z
+  .object({
+    currentPassword: z.string().min(1),
+    newPassword: passwordSchema,
+    username: z.string(), // injected server-side for the check below
+  })
+  .refine((v) => v.newPassword.toLowerCase() !== v.username.toLowerCase(), {
+    message: 'Password must not be your username',
+    path: ['newPassword'],
+  })
+```
+
+Changing a password revokes all OTHER sessions for that user (delete rows), keeping only
+the current session.
+
+## 4. First-run bootstrap
+
+On `start`, after migrations, check whether `users` is empty. If so:
+
+1. Create user `admin`, role `admin`, `must_change_password = true`, with a
+   cryptographically random 16-character password — `randomBytes` mapped onto a
+   base58/alphanumeric alphabet with no ambiguous characters (no `0OIl1`).
+2. Return the credentials so `start` prints them **once** inside the status block, with a
+   warning that they will not be shown again.
+3. Never write the plaintext to any file or log; only the scrypt hash is stored.
+
+```ts
+import { randomBytes } from 'node:crypto'
+
+const ALPHABET = '23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+
+export function generatePassword(length = 16): string {
+  const bytes = randomBytes(length)
+  let out = ''
+  for (const b of bytes) out += ALPHABET[b % ALPHABET.length]
+  return out
+}
+
+export function bootstrapAdmin(db: Db): { username: string; password: string } | null {
+  const existing = db.select({ id: users.id }).from(users).limit(1).all()
+  if (existing.length > 0) return null // no-op once any user exists
+  const password = generatePassword()
+  const now = new Date()
+  db.insert(users)
+    .values({
+      username: 'admin',
+      passwordHash: hashPassword(password),
+      role: 'admin',
+      mustChangePassword: true,
+      createdAt: now,
+      updatedAt: now,
+    })
+    .run()
+  return { username: 'admin', password }
+}
+```
+
+The empty-table guard runs on every start — the no-op on second start is a mandatory test.
+
+## 5. Sessions
+
+- Raw 32-byte random token goes to the client; only its SHA-256 hash is stored.
+- Cookie: `httpOnly`, `SameSite=Lax`, `Path=/`. `Secure` is set only when the request
+  arrived over HTTPS — local HTTP on a LAN must still work; document that TLS termination
+  is a reverse-proxy concern.
+- Sliding expiry on use; absolute cap 30 days. Logout deletes the row.
+
+```ts
+import { randomBytes, createHash } from 'node:crypto'
+
+const SLIDING_TTL_MS = 7 * 24 * 60 * 60 * 1000
+const ABSOLUTE_CAP_MS = 30 * 24 * 60 * 60 * 1000
+
+export function issueSession(db: Db, userId: number): { token: string; expiresAt: Date } {
+  const token = randomBytes(32).toString('base64url')
+  const expiresAt = new Date(Date.now() + SLIDING_TTL_MS)
+  db.insert(sessions)
+    .values({ tokenHash: sha256(token), userId, expiresAt, createdAt: new Date() })
+    .run()
+  return { token, expiresAt }
+}
+
+export function resolveSession(db: Db, token: string): SessionUser | null {
+  const row = db
+    .select()
+    .from(sessions)
+    .innerJoin(users, eq(sessions.userId, users.id))
+    .where(eq(sessions.tokenHash, sha256(token)))
+    .get()
+  if (!row || row.sessions.expiresAt < new Date()) return null
+  const cap = new Date(row.sessions.createdAt.getTime() + ABSOLUTE_CAP_MS)
+  const slid = new Date(Date.now() + SLIDING_TTL_MS)
+  db.update(sessions)
+    .set({ expiresAt: slid < cap ? slid : cap })
+    .where(eq(sessions.id, row.sessions.id))
+    .run()
+  return { id: row.users.id, username: row.users.username, role: row.users.role,
+           mustChangePassword: row.users.mustChangePassword, sessionId: row.sessions.id }
+}
+
+function sha256(value: string): string {
+  return createHash('sha256').update(value).digest('hex')
+}
+```
+
+## 6. Login rate limiting
+
+In-memory fixed window per `username+IP` — e.g. 10 attempts / 15 min. No external store:
+
+```ts
+const WINDOW_MS = 15 * 60 * 1000
+const MAX_ATTEMPTS = 10
+const attempts = new Map<string, { count: number; windowStart: number }>()
+
+export function checkRateLimit(username: string, ip: string): boolean {
+  const key = `${username.toLowerCase()}|${ip}`
+  const now = Date.now()
+  const entry = attempts.get(key)
+  if (!entry || now - entry.windowStart > WINDOW_MS) {
+    attempts.set(key, { count: 1, windowStart: now })
+    return true
+  }
+  entry.count += 1
+  return entry.count <= MAX_ATTEMPTS
+}
+```
+
+## 7. Forced-change middleware
+
+While `must_change_password` is true, every API route EXCEPT `POST /api/auth/login`,
+`POST /api/auth/change-password`, and `POST /api/auth/logout` returns
+`403 PASSWORD_CHANGE_REQUIRED`. Enforced **server-side in middleware** — the SPA redirect
+is convenience, not the control:
+
+```ts
+const EXEMPT = new Set(['/api/auth/login', '/api/auth/change-password', '/api/auth/logout'])
+
+export function forcedChangeGuard() {
+  return async (c: HonoContext, next: () => Promise<void>) => {
+    const user = c.var.user
+    if (user?.mustChangePassword && !EXEMPT.has(c.req.path)) {
+      return c.json({ code: 'PASSWORD_CHANGE_REQUIRED' }, 403)
+    }
+    await next()
+  }
+}
+```
+
+The SPA's fetch wrapper intercepts this code and hard-redirects to
+`/force-change-password` (see `server-patterns.md` §5).
+
+## 8. User management flows
+
+| Flow | Rule |
+|---|---|
+| Create user | **Admin role only.** Admin sets username + initial password; the new row gets `must_change_password = true`. |
+| First login (forced change) | Middleware gate above; SPA hard-redirects on the 403 code. |
+| Change password (anytime) | Any authenticated user, own password only; requires current password. Clears `must_change_password`; revokes all other sessions, keeping the current one. |
+| Admin reset of a user | Admin sets a new temporary password for any user; sets `must_change_password = true`; revokes that user's sessions. |
+| Delete/disable user | Admin only; **cannot delete the last remaining admin** — a server-side invariant with a test. |
+
+Last-admin invariant in the service layer:
+
+```ts
+export function deleteUser(db: Db, targetId: number): void {
+  const target = db.select().from(users).where(eq(users.id, targetId)).get()
+  if (!target) throw new NotFoundError('User not found')
+  if (target.role === 'admin') {
+    const adminCount = db
+      .select({ n: count() })
+      .from(users)
+      .where(eq(users.role, 'admin'))
+      .get()
+    if ((adminCount?.n ?? 0) <= 1) {
+      throw new InvariantError('Cannot delete the last remaining admin')
+    }
+  }
+  db.delete(users).where(eq(users.id, targetId)).run() // sessions cascade
+}
+```
+
+## 9. Route surface (user-management module)
+
+| Method | Path | Guard | Purpose |
+|---|---|---|---|
+| POST | /api/auth/login | rate-limited, public | Issue session cookie |
+| POST | /api/auth/logout | session | Delete session row, clear cookie |
+| POST | /api/auth/change-password | session (exempt from forced-change gate) | Own password; clears flag; revokes other sessions |
+| GET | /api/auth/me | session | Current user + mustChangePassword |
+| GET | /api/users | admin | List users |
+| POST | /api/users | admin | Create user (temp password, flag set) |
+| POST | /api/users/:id/reset-password | admin | Temp password, flag set, sessions revoked |
+| PATCH | /api/users/:id | admin | Update role/username |
+| DELETE | /api/users/:id | admin | Delete (last-admin invariant) |
+
+SPA pages: `/login`, `/force-change-password`, `/users` (admin only), `/settings`
+(own password change).
+
+## 10. Mandatory test coverage
+
+Every generated spec lists these as required tests (Vitest over `:memory:` with real
+migrations):
+
+1. Forced-change middleware gating — the 403 on every guarded route, and the three
+   exemptions passing
+2. Last-admin deletion invariant
+3. Session revocation on password change (other sessions die, current survives)
+4. Login rate limiting (11th attempt in the window rejected)
+5. First-run bootstrap no-op on second start

package/plugin/skills/specgen-node-cli-web/references/cli-packaging-patterns.md

@@ -0,0 +1,250 @@
+# CLI & Packaging Patterns — specgen-node-cli-web
+
+Canonical patterns for the CLI contract (root spec Section 4) and the published package /
+build pipeline (root spec Section 3). Substitute `{{PACKAGE_NAME}}` etc. with real values
+and adapt samples to the actual application — but keep every rule stated here intact.
+
+## 1. Published package manifest
+
+`packages/cli/package.json` — the ONLY published artifact:
+
+```json
+{
+  "name": "{{PACKAGE_NAME}}",
+  "version": "{{VERSION}}",
+  "description": "{{APP_DESCRIPTION}}",
+  "type": "module",
+  "license": "MIT",
+  "engines": { "node": ">=22" },
+  "bin": { "{{PACKAGE_NAME}}": "./dist/index.js" },
+  "files": ["dist", "static", "drizzle"],
+  "scripts": {
+    "build": "tsup && pnpm run build:web && pnpm run build:migrations",
+    "build:web": "pnpm --filter web build && rm -rf static && cp -r ../web/dist static",
+    "build:migrations": "rm -rf drizzle && cp -r ../server/drizzle drizzle",
+    "prepublishOnly": "pnpm -w verify"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0"
+  }
+}
+```
+
+Rules:
+- `better-sqlite3` is the only runtime dependency: it is a **native module** — never
+  bundled, never a devDependency. Everything else (commander, hono, drizzle-orm, zod,
+  picocolors, the whole `server` and `core` source) is bundled by tsup into `dist/`.
+- End users must not need pnpm or the workspace — the tarball is self-contained:
+  bundle + static UI + migrations.
+- Tarball budget: SHOULD stay under 5 MB excluding better-sqlite3. Any new runtime
+  dependency requires explicit human approval.
+
+## 2. tsup configuration
+
+`packages/cli/tsup.config.ts`:
+
+```ts
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  platform: 'node',
+  target: 'node22',
+  clean: true,
+  minify: false,
+  sourcemap: false,
+  external: ['better-sqlite3'],
+  banner: { js: '' },
+})
+```
+
+The shebang lives in `src/index.ts` itself (`#!/usr/bin/env node` as line 1); tsup
+preserves it. Verify post-build in the smoke stage — shebang and bundling failures only
+surface against the built artifact.
+
+## 3. Commander program
+
+`packages/cli/src/index.ts`:
+
+```ts
+#!/usr/bin/env node
+import { createRequire } from 'node:module'
+import { Command } from 'commander'
+import { registerStart } from './commands/start.js'
+import { registerStatus } from './commands/status.js'
+import { registerResetAdmin } from './commands/reset-admin.js'
+
+const require = createRequire(import.meta.url)
+const pkg = require('../package.json') as { version: string; description: string }
+
+const program = new Command('{{PACKAGE_NAME}}')
+  .description(pkg.description)
+  .version(pkg.version)
+
+registerStart(program)
+registerStatus(program)
+registerResetAdmin(program)
+
+await program.parseAsync(process.argv)
+```
+
+All handlers are thin: parse flags with commander → validate with Zod → delegate to
+functions imported from `server`/`core`. No business logic in `packages/cli`.
+
+## 4. `start` command
+
+Resolution order for EVERY option: CLI flag → environment variable → config file →
+default. Defaults: port `3000`, host `0.0.0.0` (the requirement is LAN access via
+`IP:PORT`).
+
+```ts
+import { Command } from 'commander'
+import { networkInterfaces } from 'node:os'
+import { serve } from '@hono/node-server'
+import { z } from 'zod'
+import pc from 'picocolors'
+import { resolveDataDir, loadConfig } from '@{{PACKAGE_NAME}}/server/lib/config'
+import { openDatabase, runMigrations, bootstrapAdmin } from '@{{PACKAGE_NAME}}/server/db'
+import { createApp } from '@{{PACKAGE_NAME}}/server/app'
+
+const startOptionsSchema = z.object({
+  port: z.coerce.number().int().min(1).max(65535),
+  host: z.string().min(1),
+  dataDir: z.string().min(1),
+})
+
+export function registerStart(program: Command): void {
+  program
+    .command('start')
+    .description('Start the {{APPLICATION_NAME}} web application (foreground)')
+    .option('--port <n>', 'HTTP port')
+    .option('--host <addr>', 'Bind address')
+    .option('--data-dir <path>', 'Data directory')
+    .action(async (flags: Record<string, string | undefined>) => {
+      const dataDir = resolveDataDir(flags.dataDir ?? process.env.APP_DATA_DIR)
+      const config = loadConfig(dataDir)
+      const options = startOptionsSchema.parse({
+        port: flags.port ?? process.env.APP_PORT ?? config.port ?? 3000,
+        host: flags.host ?? process.env.APP_HOST ?? config.host ?? '0.0.0.0',
+        dataDir,
+      })
+
+      const db = openDatabase(options.dataDir)
+      runMigrations(db)
+      const bootstrap = bootstrapAdmin(db)
+
+      const app = createApp({ db, dataDir: options.dataDir })
+      const server = serve(
+        { fetch: app.fetch, port: options.port, hostname: options.host },
+        () => printStatusBlock(options, bootstrap),
+      )
+      server.on('error', (error: NodeJS.ErrnoException) => {
+        if (error.code === 'EADDRINUSE') {
+          console.error(
+            pc.red(`Port ${options.port} is already in use. `) +
+              `Choose another with ${pc.bold('--port <n>')} (or APP_PORT).`,
+          )
+          process.exit(1)
+        }
+        throw error
+      })
+
+      const shutdown = () => {
+        server.close(() => {
+          db.close()
+          process.exit(0)
+        })
+      }
+      process.on('SIGINT', shutdown)
+      process.on('SIGTERM', shutdown)
+    })
+}
+
+function detectLanIp(): string | undefined {
+  for (const addrs of Object.values(networkInterfaces())) {
+    for (const addr of addrs ?? []) {
+      if (addr.family === 'IPv4' && !addr.internal) return addr.address
+    }
+  }
+  return undefined
+}
+```
+
+The status block prints exactly once on successful start — local URL, network URL
+(detected LAN IP), data directory, version, and (first run only) the admin credentials
+with a will-not-be-shown-again warning. Structured logs after that:
+
+```
+  {{APPLICATION_NAME}} v1.0.0
+
+  Local:     http://localhost:3000
+  Network:   http://192.168.1.23:3000
+  Data dir:  /home/alice/.local/share/{{PACKAGE_NAME}}
+
+  First-run admin account created:
+    username: admin
+    password: h7Kp2mXw9RtBqZ4c        ← shown ONCE, will not be displayed again
+
+  Press Ctrl-C to stop.
+```
+
+Hard rules:
+- Port taken → fail with a clear message naming `--port`; never auto-increment silently.
+- Foreground only; Ctrl-C triggers graceful shutdown that closes the SQLite handle.
+  Daemonization is the OS's job (`systemd`, `pm2`) — the spec MUST NOT include forking or
+  daemon logic.
+
+## 5. `status` command
+
+Reads config the same way `start` does, then GETs `http://127.0.0.1:<port>/api/health`
+with native `fetch` and a short timeout. Prints running/not-running plus version and
+uptime from the health payload; exit code 0 when reachable, 1 when not.
+
+## 6. `reset-admin` command
+
+The recovery path when credentials are lost — filesystem access is the root of trust; no
+email reset flow exists.
+
+```ts
+export function registerResetAdmin(program: Command): void {
+  program
+    .command('reset-admin')
+    .description('Regenerate the admin password (offline, direct DB access)')
+    .option('--data-dir <path>', 'Data directory')
+    .action(async (flags: { dataDir?: string }) => {
+      const dataDir = resolveDataDir(flags.dataDir ?? process.env.APP_DATA_DIR)
+      const db = openDatabase(dataDir)
+      runMigrations(db)
+      const password = resetAdminPassword(db) // core service: new random password,
+                                              // must_change_password = true,
+                                              // revoke all admin sessions
+      db.close()
+      console.log(`New admin password: ${password}`)
+      console.log('Shown once — it will not be displayed again.')
+    })
+}
+```
+
+Opens the DB directly (works while the server is stopped; WAL + busy_timeout make it safe
+either way), sets `must_change_password = true`, revokes the admin's sessions, prints the
+password once. Never writes the plaintext anywhere.
+
+## 7. Pre-publish check
+
+Before publishing, always run the local install check against the real artifact:
+
+```
+pnpm verify
+npm pack ./packages/cli
+npm i -g ./{{PACKAGE_NAME}}-{{VERSION}}.tgz
+{{PACKAGE_NAME}} --version
+node scripts/smoke-start.mjs --command {{PACKAGE_NAME}}
+```
+
+This is the only place shebang, `files` whitelist, native-module resolution, and
+static-asset path bugs surface. `prepublishOnly` additionally runs `pnpm -w verify` as a
+safety net.