@webstir-io/webstir-backend 0.1.15

package/src/workspace.ts

@@ -0,0 +1,22 @@
+import path from 'node:path';
+
+import type { ResolvedModuleWorkspace } from '@webstir-io/module-contract';
+
+export type BackendBuildMode = 'build' | 'publish' | 'test';
+
+export function resolveWorkspacePaths(workspaceRoot: string): ResolvedModuleWorkspace {
+  return {
+    sourceRoot: path.join(workspaceRoot, 'src', 'backend'),
+    buildRoot: path.join(workspaceRoot, 'build', 'backend'),
+    testsRoot: path.join(workspaceRoot, 'src', 'backend', 'tests')
+  };
+}
+
+export function normalizeMode(rawMode: unknown): BackendBuildMode {
+  if (typeof rawMode !== 'string') {
+    return 'build';
+  }
+
+  const normalized = rawMode.toLowerCase();
+  return normalized === 'publish' || normalized === 'test' ? normalized : 'build';
+}

package/templates/backend/.env.example

@@ -0,0 +1,13 @@
+NODE_ENV=development
+PORT=4000
+API_BASE_URL=http://localhost:4000
+AUTH_JWT_SECRET=change-me
+AUTH_JWT_ISSUER=https://example-idp/
+AUTH_JWT_AUDIENCE=webstir-dev
+AUTH_SERVICE_TOKENS=local-service-token
+LOG_LEVEL=info
+LOG_SERVICE_NAME=backend-template
+METRICS_ENABLED=on
+METRICS_WINDOW=200
+DATABASE_URL=file:./data/dev.sqlite
+DATABASE_MIGRATIONS_TABLE=_webstir_migrations

package/templates/backend/auth/adapter.ts

@@ -0,0 +1,160 @@
+import crypto from 'node:crypto';
+import type http from 'node:http';
+
+import type { AuthSecrets } from '../env.js';
+
+export interface AuthContext {
+  source: 'jwt' | 'service-token';
+  token: string;
+  userId?: string;
+  email?: string;
+  name?: string;
+  scopes: readonly string[];
+  roles: readonly string[];
+  claims: Record<string, unknown>;
+}
+
+export function resolveRequestAuth(
+  req: http.IncomingMessage,
+  secrets: AuthSecrets,
+  logger?: { warn?(message: string, metadata?: Record<string, unknown>): void }
+): AuthContext | undefined {
+  const bearer = getHeader(req, 'authorization');
+  if (bearer?.startsWith('Bearer ')) {
+    if (!secrets.jwtSecret) {
+      logger?.warn?.('Authorization header provided but AUTH_JWT_SECRET is not configured.');
+    } else {
+      const token = bearer.slice(7).trim();
+      const context = verifyJwtToken(token, secrets);
+      if (context) {
+        return context;
+      }
+      logger?.warn?.('Bearer token validation failed', { reason: 'invalid_token' });
+    }
+  }
+
+  const serviceToken = getHeader(req, 'x-service-token') ?? getHeader(req, 'x-api-key');
+  if (serviceToken && secrets.serviceTokens.length > 0) {
+    if (secrets.serviceTokens.includes(serviceToken)) {
+      return {
+        source: 'service-token',
+        token: serviceToken,
+        scopes: ['service'],
+        roles: ['service'],
+        claims: {},
+        userId: undefined,
+        email: undefined,
+        name: undefined
+      };
+    }
+    logger?.warn?.('Service token did not match any allowed AUTH_SERVICE_TOKENS entry');
+  }
+
+  return undefined;
+}
+
+function verifyJwtToken(token: string, secrets: AuthSecrets): AuthContext | undefined {
+  if (!secrets.jwtSecret) return undefined;
+  const parts = token.split('.');
+  if (parts.length !== 3) return undefined;
+  const [encodedHeader, encodedPayload, signature] = parts;
+
+  const header = decodeSegment(encodedHeader);
+  if (!header || header.alg !== 'HS256') {
+    return undefined;
+  }
+
+  const payload = decodeSegment(encodedPayload);
+  if (!payload) {
+    return undefined;
+  }
+
+  const signedContent = `${encodedHeader}.${encodedPayload}`;
+  const expectedSignature = crypto.createHmac('sha256', secrets.jwtSecret).update(signedContent).digest('base64url');
+  if (!timingSafeEqual(signature, expectedSignature)) {
+    return undefined;
+  }
+
+  if (secrets.jwtIssuer && payload.iss !== secrets.jwtIssuer) {
+    return undefined;
+  }
+
+  if (secrets.jwtAudience && !audienceMatches(payload.aud, secrets.jwtAudience)) {
+    return undefined;
+  }
+
+  const scopes = normalizeScopes(payload.scope);
+  const roles = normalizeRoles(payload.roles ?? payload.role ?? payload['https://schemas.webstir.dev/roles']);
+
+  return {
+    source: 'jwt',
+    token,
+    userId: typeof payload.sub === 'string' ? payload.sub : undefined,
+    email: typeof payload.email === 'string' ? payload.email : undefined,
+    name: typeof payload.name === 'string' ? payload.name : undefined,
+    scopes,
+    roles,
+    claims: payload as Record<string, unknown>
+  };
+}
+
+function decodeSegment(segment: string): Record<string, any> | undefined {
+  try {
+    const json = Buffer.from(segment, 'base64url').toString('utf8');
+    return JSON.parse(json) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+function timingSafeEqual(left: string, right: string): boolean {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  if (leftBuffer.length !== rightBuffer.length) {
+    return false;
+  }
+  return crypto.timingSafeEqual(leftBuffer, rightBuffer);
+}
+
+function audienceMatches(value: unknown, expected: string): boolean {
+  if (Array.isArray(value)) {
+    return value.includes(expected);
+  }
+  if (typeof value === 'string') {
+    return value === expected;
+  }
+  return false;
+}
+
+function normalizeScopes(value: unknown): string[] {
+  if (!value) return [];
+  if (Array.isArray(value)) {
+    return value.map((scope) => String(scope));
+  }
+  if (typeof value === 'string') {
+    return value.split(' ').map((scope) => scope.trim()).filter((scope) => scope.length > 0);
+  }
+  return [];
+}
+
+function normalizeRoles(value: unknown): string[] {
+  if (!value) return [];
+  if (Array.isArray(value)) {
+    return value.map((role) => String(role));
+  }
+  if (typeof value === 'string') {
+    return value.split(',').map((role) => role.trim()).filter((role) => role.length > 0);
+  }
+  return [];
+}
+
+function getHeader(req: http.IncomingMessage, name: string): string | undefined {
+  const value = req.headers[name] ?? req.headers[name.toLowerCase()];
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value[0];
+  }
+  return undefined;
+}

package/templates/backend/db/connection.ts

@@ -0,0 +1,99 @@
+import path from 'node:path';
+import { mkdirSync } from 'node:fs';
+
+export interface DatabaseClient {
+  query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+  execute(sql: string, params?: unknown[]): Promise<void>;
+  close(): Promise<void>;
+}
+
+export async function createDatabaseClient(url = process.env.DATABASE_URL ?? 'file:./data/dev.sqlite'): Promise<DatabaseClient> {
+  if (isSqlite(url)) {
+    return createSqliteClient(url);
+  }
+  if (isPostgres(url)) {
+    return createPostgresClient(url);
+  }
+  throw new Error(
+    `[db] Unsupported DATABASE_URL '${url}'. Use file:./path/to.sqlite or postgres://...`
+  );
+}
+
+function isSqlite(url: string): boolean {
+  return url.startsWith('file:') || url.endsWith('.sqlite') || url.endsWith('.db');
+}
+
+function isPostgres(url: string): boolean {
+  return url.startsWith('postgres://') || url.startsWith('postgresql://');
+}
+
+async function createSqliteClient(url: string): Promise<DatabaseClient> {
+  let Database: typeof import('better-sqlite3');
+  try {
+    const sqliteModule = await import('better-sqlite3');
+    Database = sqliteModule.default ?? (sqliteModule as unknown as typeof import('better-sqlite3'));
+  } catch (error) {
+    throw new Error(
+      `[db] Failed to load better-sqlite3. Install it in your workspace with "npm install better-sqlite3". (${(error as Error).message})`
+    );
+  }
+
+  const target = normalizeSqlitePath(url);
+  mkdirSync(path.dirname(target), { recursive: true });
+  const db = new Database(target);
+
+  return {
+    async query(sql, params) {
+      const statement = db.prepare(sql);
+      return statement.all(params ?? []);
+    },
+    async execute(sql, params) {
+      const statement = db.prepare(sql);
+      statement.run(params ?? []);
+    },
+    async close() {
+      db.close();
+    }
+  };
+}
+
+async function createPostgresClient(url: string): Promise<DatabaseClient> {
+  type PgClientCtor = new (...args: any[]) => {
+    query: (text: string, params?: unknown[]) => Promise<{ rows: any[] }>;
+    connect: () => Promise<void>;
+    end: () => Promise<void>;
+  };
+
+  let ClientCtor: PgClientCtor;
+  try {
+    const pgModule = await import('pg');
+    ClientCtor = (pgModule as unknown as { Client: PgClientCtor }).Client;
+  } catch (error) {
+    throw new Error(
+      `[db] Failed to load pg. Install it in your workspace with "npm install pg". (${(error as Error).message})`
+    );
+  }
+
+  const client = new ClientCtor({ connectionString: url });
+  await client.connect();
+
+  return {
+    async query(sql, params) {
+      const result = await client.query(sql, params);
+      return result.rows;
+    },
+    async execute(sql, params) {
+      await client.query(sql, params);
+    },
+    async close() {
+      await client.end();
+    }
+  };
+}
+
+function normalizeSqlitePath(url: string): string {
+  if (url.startsWith('file:')) {
+    return path.resolve(url.slice('file:'.length));
+  }
+  return path.resolve(url);
+}

package/templates/backend/db/migrate.ts

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { createDatabaseClient } from './connection.js';
+import type { DatabaseClient } from './connection.js';
+
+const args = process.argv.slice(2);
+const MIGRATIONS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'migrations');
+
+export type MigrationFn = (ctx: MigrationContext) => Promise<void> | void;
+
+interface MigrationModule {
+  id: string;
+  up: MigrationFn;
+  down?: MigrationFn;
+}
+
+export interface MigrationContext {
+  sql(query: string, params?: unknown[]): Promise<void>;
+  query<T = unknown>(query: string, params?: unknown[]): Promise<T[]>;
+}
+
+async function main() {
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return;
+  }
+
+  const migrations = await loadMigrations();
+  if (args.includes('--list')) {
+    printMigrations(migrations);
+    return;
+  }
+
+  if (migrations.length === 0) {
+    console.warn('[migrate] No migrations found under src/backend/db/migrations');
+    return;
+  }
+
+  const direction: 'up' | 'down' = args.includes('--down') ? 'down' : 'up';
+  const steps = parseSteps();
+
+  const client = await createDatabaseClient();
+  try {
+    await ensureMigrationsTable(client);
+    if (direction === 'down') {
+      await runDown(client, migrations, steps);
+    } else {
+      await runUp(client, migrations, steps);
+    }
+  } finally {
+    await client.close();
+  }
+}
+
+async function runUp(client: DatabaseClient, migrations: MigrationModule[], steps: number | undefined) {
+  const applied = await getAppliedMigrations(client);
+  const pending = migrations.filter((migration) => !applied.includes(migration.id));
+  if (pending.length === 0) {
+    console.info('[migrate] Database is up to date.');
+    return;
+  }
+
+  const toRun = typeof steps === 'number' ? pending.slice(0, steps) : pending;
+  for (const migration of toRun) {
+    console.info(`[migrate] Applying ${migration.id}`);
+    await migration.up(createMigrationContext(client));
+    await recordMigration(client, migration.id);
+  }
+}
+
+async function runDown(client: DatabaseClient, migrations: MigrationModule[], steps: number | undefined) {
+  const applied = await getAppliedMigrations(client);
+  if (applied.length === 0) {
+    console.info('[migrate] No applied migrations to roll back.');
+    return;
+  }
+
+  const toRollback = typeof steps === 'number' ? applied.slice(-steps) : applied;
+  const migrationMap = new Map(migrations.map((migration) => [migration.id, migration]));
+
+  for (const id of toRollback.reverse()) {
+    const migration = migrationMap.get(id);
+    if (!migration?.down) {
+      console.warn(`[migrate] Skipping ${id} (no down() function exported).`);
+      continue;
+    }
+    console.info(`[migrate] Reverting ${id}`);
+    await migration.down(createMigrationContext(client));
+    await deleteMigrationRecord(client, id);
+  }
+}
+
+async function ensureMigrationsTable(client: DatabaseClient) {
+  const table = process.env.DATABASE_MIGRATIONS_TABLE ?? '_webstir_migrations';
+  await client.execute(
+    `CREATE TABLE IF NOT EXISTS ${table} (
+      id TEXT PRIMARY KEY,
+      applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    )`
+  );
+}
+
+async function getAppliedMigrations(client: DatabaseClient): Promise<string[]> {
+  const table = process.env.DATABASE_MIGRATIONS_TABLE ?? '_webstir_migrations';
+  const rows = await client.query<{ id: string }>(`SELECT id FROM ${table} ORDER BY applied_at`);
+  return rows.map((row) => row.id);
+}
+
+async function recordMigration(client: DatabaseClient, id: string) {
+  const table = process.env.DATABASE_MIGRATIONS_TABLE ?? '_webstir_migrations';
+  await client.execute(`INSERT INTO ${table} (id) VALUES (?)`, [id]);
+}
+
+async function deleteMigrationRecord(client: DatabaseClient, id: string) {
+  const table = process.env.DATABASE_MIGRATIONS_TABLE ?? '_webstir_migrations';
+  await client.execute(`DELETE FROM ${table} WHERE id = ?`, [id]);
+}
+
+function createMigrationContext(client: DatabaseClient): MigrationContext {
+  return {
+    sql: (query, params) => client.execute(query, params),
+    query: (query, params) => client.query(query, params)
+  };
+}
+
+async function loadMigrations(): Promise<MigrationModule[]> {
+  try {
+    const files = await fs.readdir(MIGRATIONS_DIR);
+    const scriptFiles = files
+      .filter((file) => /\.[cm]?[jt]s$/.test(file))
+      .sort();
+    const modules: MigrationModule[] = [];
+    for (const file of scriptFiles) {
+      const moduleUrl = pathToFileURL(path.join(MIGRATIONS_DIR, file)).href + `?t=${Date.now()}`;
+      const imported = (await import(moduleUrl)) as Record<string, unknown>;
+      const migration = normalizeMigrationModule(imported, file);
+      if (migration) {
+        modules.push(migration);
+      }
+    }
+    return modules;
+  } catch (error) {
+    console.error('[migrate] Failed to load migrations:', (error as Error).message);
+    return [];
+  }
+}
+
+function normalizeMigrationModule(exports: Record<string, unknown>, file: string): MigrationModule | undefined {
+  const id =
+    typeof exports.id === 'string'
+      ? exports.id
+      : typeof exports.default === 'object' && exports.default && typeof (exports.default as any).id === 'string'
+        ? (exports.default as any).id
+        : path.basename(file).replace(/\.[cm]?[jt]s$/, '');
+  const up: MigrationFn | undefined =
+    typeof exports.up === 'function'
+      ? (exports.up as MigrationFn)
+      : exports.default && typeof (exports.default as any).up === 'function'
+        ? ((exports.default as any).up as MigrationFn)
+        : undefined;
+  if (!up) {
+    console.warn(`[migrate] ${file} does not export an up() function. Skipping.`);
+    return undefined;
+  }
+  const down: MigrationFn | undefined =
+    typeof exports.down === 'function'
+      ? (exports.down as MigrationFn)
+      : exports.default && typeof (exports.default as any).down === 'function'
+        ? ((exports.default as any).down as MigrationFn)
+        : undefined;
+  return { id, up, down };
+}
+
+function parseSteps(): number | undefined {
+  const value = parseOption('--steps');
+  if (!value) return undefined;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`--steps must be a positive integer (received "${value}")`);
+  }
+  return Math.floor(parsed);
+}
+
+function parseOption(flag: string): string | undefined {
+  const index = args.indexOf(flag);
+  if (index !== -1 && args[index + 1] && !args[index + 1].startsWith('-')) {
+    return args[index + 1];
+  }
+  const prefix = `${flag}=`;
+  const inline = args.find((arg) => arg.startsWith(prefix));
+  if (inline) {
+    return inline.slice(prefix.length);
+  }
+  return undefined;
+}
+
+function printMigrations(migrations: MigrationModule[]) {
+  if (migrations.length === 0) {
+    console.info('[migrate] No migrations found.');
+    return;
+  }
+  console.info('[migrate] Available migrations:');
+  for (const migration of migrations) {
+    console.info(`- ${migration.id}${migration.down ? '' : ' (no down)'}`);
+  }
+}
+
+function printHelp() {
+  console.info(`Usage:
+  npx tsx src/backend/db/migrate.ts [--list]
+  npx tsx src/backend/db/migrate.ts --down [--steps 1]
+
+Options:
+  --list        Show migrations and exit
+  --down        Roll back migrations instead of applying new ones
+  --steps <n>   Limit how many migrations to run in the current direction
+  --help        Show this message
+
+Notes:
+  - Defaults to reading migration files from src/backend/db/migrations.
+  - DATABASE_URL controls the target database (file:./dev.sqlite by default).
+  - Install 'better-sqlite3' for SQLite or 'pg' for Postgres before running.`);
+}
+
+main().catch((error) => {
+  console.error('[migrate] Failed:', error);
+  process.exitCode = 1;
+});

package/templates/backend/db/migrations/0001-example.ts

@@ -0,0 +1,17 @@
+import type { MigrationContext } from '../migrate.js';
+
+export const id = '0001_init';
+
+export async function up(ctx: MigrationContext): Promise<void> {
+  await ctx.sql(`
+    CREATE TABLE IF NOT EXISTS example_records (
+      id TEXT PRIMARY KEY,
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      payload TEXT NOT NULL
+    )
+  `);
+}
+
+export async function down(ctx: MigrationContext): Promise<void> {
+  await ctx.sql(`DROP TABLE IF EXISTS example_records`);
+}

package/templates/backend/db/types.d.ts

@@ -0,0 +1,2 @@
+declare module 'better-sqlite3';
+declare module 'pg';