@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/src/workspace.ts

@@ -1,14 +1,51 @@
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import type { ResolvedModuleWorkspace } from '@webstir-io/module-contract';
 
 export type BackendBuildMode = 'build' | 'publish' | 'test';
 
+interface ResolveWorkspaceRootOptions {
+  readonly workspaceRoot?: string;
+  readonly env?: Record<string, string | undefined>;
+  readonly cwd?: string;
+  readonly importMetaUrl?: string;
+}
+
+const WORKSPACE_ROOT_PATTERN = /^(.*)[/\\](?:src|build)[/\\]backend(?:[/\\].*)?$/;
+
+export function resolveWorkspaceRoot(options?: string | ResolveWorkspaceRootOptions): string {
+  if (typeof options === 'string') {
+    return path.resolve(options);
+  }
+
+  const explicitRoot = options?.workspaceRoot?.trim();
+  if (explicitRoot) {
+    return path.resolve(explicitRoot);
+  }
+
+  const env = options?.env ?? process.env;
+  const envRoot = env.WORKSPACE_ROOT?.trim() || env.WEBSTIR_WORKSPACE_ROOT?.trim();
+  if (envRoot) {
+    return path.resolve(envRoot);
+  }
+
+  const inferredRoot = options?.importMetaUrl
+    ? inferWorkspaceRootFromImportMetaUrl(options.importMetaUrl)
+    : undefined;
+  if (inferredRoot) {
+    return inferredRoot;
+  }
+
+  return path.resolve(options?.cwd ?? process.cwd());
+}
+
 export function resolveWorkspacePaths(workspaceRoot: string): ResolvedModuleWorkspace {
+  const resolvedWorkspaceRoot = resolveWorkspaceRoot(workspaceRoot);
   return {
-    sourceRoot: path.join(workspaceRoot, 'src', 'backend'),
-    buildRoot: path.join(workspaceRoot, 'build', 'backend'),
-    testsRoot: path.join(workspaceRoot, 'src', 'backend', 'tests')
+    sourceRoot: path.join(resolvedWorkspaceRoot, 'src', 'backend'),
+    buildRoot: path.join(resolvedWorkspaceRoot, 'build', 'backend'),
+    testsRoot: path.join(resolvedWorkspaceRoot, 'src', 'backend', 'tests'),
   };
 }
 
@@ -20,3 +57,22 @@ export function normalizeMode(rawMode: unknown): BackendBuildMode {
   const normalized = rawMode.toLowerCase();
   return normalized === 'publish' || normalized === 'test' ? normalized : 'build';
 }
+
+function inferWorkspaceRootFromImportMetaUrl(importMetaUrl: string): string | undefined {
+  try {
+    return inferWorkspaceRootFromFilePath(fileURLToPath(importMetaUrl));
+  } catch {
+    return undefined;
+  }
+}
+
+function inferWorkspaceRootFromFilePath(filePath: string): string | undefined {
+  const normalizedFilePath = path.resolve(filePath);
+  const match = normalizedFilePath.match(WORKSPACE_ROOT_PATTERN);
+  if (!match) {
+    return undefined;
+  }
+
+  const inferredRoot = match[1];
+  return inferredRoot || path.parse(normalizedFilePath).root;
+}

package/templates/backend/.env.example

@@ -1,13 +1,28 @@
 NODE_ENV=development
 PORT=4000
 API_BASE_URL=http://localhost:4000
+# Choose one JWT verification mode:
+# - Shared secret: AUTH_JWT_SECRET
+# - RSA public key file: AUTH_JWT_PUBLIC_KEY_FILE
+# - JWKS endpoint: AUTH_JWKS_URL
 AUTH_JWT_SECRET=change-me
+# AUTH_JWT_PUBLIC_KEY_FILE=./config/jwt-public-key.pem
+# AUTH_JWKS_URL=https://example-idp/.well-known/jwks.json
 AUTH_JWT_ISSUER=https://example-idp/
 AUTH_JWT_AUDIENCE=webstir-dev
 AUTH_SERVICE_TOKENS=local-service-token
+SESSION_SECRET=change-me-too
+SESSION_COOKIE_NAME=webstir_session
+SESSION_COOKIE_SECURE=off
+SESSION_MAX_AGE=86400
+# Development defaults to memory; production defaults to sqlite.
+# SESSION_STORE_DRIVER=memory
+SESSION_STORE_URL=file:./data/sessions.sqlite
 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
+REQUEST_BODY_MAX_BYTES=1048576
+WEBSTIR_BACKEND_SERVER_RUNTIME=node

package/templates/backend/auth/adapter.ts

@@ -1,5 +1,4 @@
 import crypto from 'node:crypto';
-import type http from 'node:http';
 
 import type { AuthSecrets } from '../env.js';
 
@@ -14,18 +13,40 @@ export interface AuthContext {
   claims: Record<string, unknown>;
 }
 
-export function resolveRequestAuth(
-  req: http.IncomingMessage,
+interface JwtHeader extends Record<string, unknown> {
+  alg?: string;
+  kid?: string;
+  typ?: string;
+}
+
+interface CachedJwkKey {
+  kid?: string;
+  key: crypto.KeyObject;
+}
+
+interface CachedJwksEntry {
+  keys: readonly CachedJwkKey[];
+  expiresAt: number;
+}
+
+const DEFAULT_JWKS_CACHE_MS = 5 * 60 * 1000;
+const JWKS_FETCH_TIMEOUT_MS = 5_000;
+const jwksCache = new Map<string, CachedJwksEntry>();
+const jwksFetches = new Map<string, Promise<readonly CachedJwkKey[]>>();
+const publicKeyCache = new Map<string, crypto.KeyObject>();
+
+export async function resolveRequestAuth(
+  request: Request,
   secrets: AuthSecrets,
-  logger?: { warn?(message: string, metadata?: Record<string, unknown>): void }
-): AuthContext | undefined {
-  const bearer = getHeader(req, 'authorization');
+  logger?: { warn?(message: string, metadata?: Record<string, unknown>): void },
+): Promise<AuthContext | undefined> {
+  const bearer = getHeader(request, 'authorization');
   if (bearer?.startsWith('Bearer ')) {
-    if (!secrets.jwtSecret) {
-      logger?.warn?.('Authorization header provided but AUTH_JWT_SECRET is not configured.');
+    if (!hasJwtVerificationSecrets(secrets)) {
+      logger?.warn?.('Authorization header provided but no JWT verification config is set.');
     } else {
       const token = bearer.slice(7).trim();
-      const context = verifyJwtToken(token, secrets);
+      const context = await verifyJwtToken(token, secrets);
       if (context) {
         return context;
       }
@@ -33,7 +54,7 @@ export function resolveRequestAuth(
     }
   }
 
-  const serviceToken = getHeader(req, 'x-service-token') ?? getHeader(req, 'x-api-key');
+  const serviceToken = getHeader(request, 'x-service-token') ?? getHeader(request, 'x-api-key');
   if (serviceToken && secrets.serviceTokens.length > 0) {
     if (secrets.serviceTokens.includes(serviceToken)) {
       return {
@@ -44,7 +65,7 @@ export function resolveRequestAuth(
         claims: {},
         userId: undefined,
         email: undefined,
-        name: undefined
+        name: undefined,
       };
     }
     logger?.warn?.('Service token did not match any allowed AUTH_SERVICE_TOKENS entry');
@@ -53,25 +74,44 @@ export function resolveRequestAuth(
   return undefined;
 }
 
-function verifyJwtToken(token: string, secrets: AuthSecrets): AuthContext | undefined {
-  if (!secrets.jwtSecret) return undefined;
+function hasJwtVerificationSecrets(secrets: AuthSecrets): boolean {
+  return Boolean(secrets.jwtSecret || secrets.jwtPublicKey || secrets.jwksUrl);
+}
+
+async function verifyJwtToken(
+  token: string,
+  secrets: AuthSecrets,
+): Promise<AuthContext | undefined> {
   const parts = token.split('.');
-  if (parts.length !== 3) return undefined;
-  const [encodedHeader, encodedPayload, signature] = parts;
+  if (parts.length !== 3) {
+    return undefined;
+  }
 
-  const header = decodeSegment(encodedHeader);
-  if (!header || header.alg !== 'HS256') {
+  const [encodedHeader, encodedPayload, signature] = parts;
+  const header = decodeSegment<JwtHeader>(encodedHeader);
+  if (!header?.alg) {
     return undefined;
   }
 
-  const payload = decodeSegment(encodedPayload);
+  const payload = decodeSegment<Record<string, unknown>>(encodedPayload);
   if (!payload) {
     return undefined;
   }
 
   const signedContent = `${encodedHeader}.${encodedPayload}`;
-  const expectedSignature = crypto.createHmac('sha256', secrets.jwtSecret).update(signedContent).digest('base64url');
-  if (!timingSafeEqual(signature, expectedSignature)) {
+  const signatureBuffer = decodeBase64Url(signature);
+  if (!signatureBuffer) {
+    return undefined;
+  }
+
+  const verified =
+    header.alg === 'HS256'
+      ? verifyHmacSignature(signedContent, signature, secrets.jwtSecret)
+      : header.alg === 'RS256'
+        ? await verifyRsaSignature(signedContent, signatureBuffer, header, secrets)
+        : false;
+
+  if (!verified) {
     return undefined;
   }
 
@@ -83,8 +123,15 @@ function verifyJwtToken(token: string, secrets: AuthSecrets): AuthContext | unde
     return undefined;
   }
 
+  const now = Date.now() / 1000;
+  if (!isValidTimeClaims(payload, now)) {
+    return undefined;
+  }
+
   const scopes = normalizeScopes(payload.scope);
-  const roles = normalizeRoles(payload.roles ?? payload.role ?? payload['https://schemas.webstir.dev/roles']);
+  const roles = normalizeRoles(
+    payload.roles ?? payload.role ?? payload['https://schemas.webstir.dev/roles'],
+  );
 
   return {
     source: 'jwt',
@@ -94,14 +141,235 @@ function verifyJwtToken(token: string, secrets: AuthSecrets): AuthContext | unde
     name: typeof payload.name === 'string' ? payload.name : undefined,
     scopes,
     roles,
-    claims: payload as Record<string, unknown>
+    claims: payload,
   };
 }
 
-function decodeSegment(segment: string): Record<string, any> | undefined {
+function verifyHmacSignature(signedContent: string, signature: string, secret?: string): boolean {
+  if (!secret) {
+    return false;
+  }
+
+  const expectedSignature = crypto
+    .createHmac('sha256', secret)
+    .update(signedContent)
+    .digest('base64url');
+  return timingSafeEqual(signature, expectedSignature);
+}
+
+async function verifyRsaSignature(
+  signedContent: string,
+  signature: Buffer,
+  header: JwtHeader,
+  secrets: AuthSecrets,
+): Promise<boolean> {
+  if (secrets.jwtPublicKey) {
+    const publicKey = getConfiguredPublicKey(secrets.jwtPublicKey);
+    if (publicKey && verifyWithPublicKey(signedContent, signature, publicKey)) {
+      return true;
+    }
+  }
+
+  if (!secrets.jwksUrl) {
+    return false;
+  }
+
+  const jwksKeys = await getJwksKeys(secrets.jwksUrl);
+  const initialCandidates = selectJwksCandidates(jwksKeys, header);
+  for (const candidate of initialCandidates) {
+    if (verifyWithPublicKey(signedContent, signature, candidate.key)) {
+      return true;
+    }
+  }
+
+  if (!header.kid) {
+    return false;
+  }
+
+  const refreshedKeys = await getJwksKeys(secrets.jwksUrl, { forceRefresh: true });
+  for (const candidate of selectJwksCandidates(refreshedKeys, header)) {
+    if (verifyWithPublicKey(signedContent, signature, candidate.key)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function verifyWithPublicKey(
+  signedContent: string,
+  signature: Buffer,
+  publicKey: crypto.KeyObject,
+): boolean {
+  try {
+    return crypto.verify('RSA-SHA256', Buffer.from(signedContent), publicKey, signature);
+  } catch {
+    return false;
+  }
+}
+
+function getConfiguredPublicKey(value: string): crypto.KeyObject | undefined {
+  const cached = publicKeyCache.get(value);
+  if (cached) {
+    return cached;
+  }
+
   try {
-    const json = Buffer.from(segment, 'base64url').toString('utf8');
-    return JSON.parse(json) as Record<string, unknown>;
+    const trimmed = value.trim();
+    const key = trimmed.startsWith('{')
+      ? crypto.createPublicKey({ key: JSON.parse(trimmed) as crypto.JsonWebKey, format: 'jwk' })
+      : crypto.createPublicKey(trimmed);
+    publicKeyCache.set(value, key);
+    return key;
+  } catch {
+    return undefined;
+  }
+}
+
+function selectJwksCandidates(
+  keys: readonly CachedJwkKey[],
+  header: JwtHeader,
+): readonly CachedJwkKey[] {
+  if (header.kid) {
+    return keys.filter((key) => key.kid === header.kid);
+  }
+
+  return keys;
+}
+
+async function getJwksKeys(
+  url: string,
+  options: { forceRefresh?: boolean } = {},
+): Promise<readonly CachedJwkKey[]> {
+  if (options.forceRefresh) {
+    jwksCache.delete(url);
+  }
+
+  const cached = jwksCache.get(url);
+  const now = Date.now();
+  if (cached && cached.expiresAt > now) {
+    return cached.keys;
+  }
+
+  const pending = jwksFetches.get(url);
+  if (pending) {
+    return await pending;
+  }
+
+  const fetchPromise = fetchJwksKeys(url, cached?.keys ?? []).finally(() => {
+    jwksFetches.delete(url);
+  });
+  jwksFetches.set(url, fetchPromise);
+  return await fetchPromise;
+}
+
+async function fetchJwksKeys(
+  url: string,
+  fallbackKeys: readonly CachedJwkKey[],
+): Promise<readonly CachedJwkKey[]> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), JWKS_FETCH_TIMEOUT_MS);
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    if (!response.ok) {
+      throw new Error(`JWKS request failed with status ${response.status}`);
+    }
+
+    const body = (await response.json()) as { keys?: unknown };
+    const keys = Array.isArray(body.keys) ? body.keys : [];
+    const resolvedKeys = keys
+      .map((key) => jwkToCachedKey(key))
+      .filter((key): key is CachedJwkKey => key !== undefined);
+
+    const ttlMs = resolveJwksCacheTtl(response.headers);
+    jwksCache.set(url, {
+      keys: resolvedKeys,
+      expiresAt: Date.now() + ttlMs,
+    });
+
+    return resolvedKeys;
+  } catch {
+    if (fallbackKeys.length > 0) {
+      jwksCache.set(url, {
+        keys: fallbackKeys,
+        expiresAt: Date.now() + DEFAULT_JWKS_CACHE_MS,
+      });
+      return fallbackKeys;
+    }
+    jwksCache.delete(url);
+    return [];
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function jwkToCachedKey(value: unknown): CachedJwkKey | undefined {
+  if (!value || typeof value !== 'object') {
+    return undefined;
+  }
+
+  try {
+    const jwk = value as crypto.JsonWebKey;
+    const key = crypto.createPublicKey({ key: jwk, format: 'jwk' });
+    return {
+      kid: typeof jwk.kid === 'string' ? jwk.kid : undefined,
+      key,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveJwksCacheTtl(headers: Headers): number {
+  const cacheControl = headers.get('cache-control');
+  if (cacheControl) {
+    const maxAgeMatch = cacheControl.match(/max-age=(\d+)/i);
+    if (maxAgeMatch) {
+      const maxAgeSeconds = Number(maxAgeMatch[1]);
+      if (Number.isFinite(maxAgeSeconds) && maxAgeSeconds > 0) {
+        return maxAgeSeconds * 1000;
+      }
+    }
+    if (/\bno-store\b/i.test(cacheControl)) {
+      return 0;
+    }
+  }
+
+  const expires = headers.get('expires');
+  if (expires) {
+    const expiresAt = Date.parse(expires);
+    if (Number.isFinite(expiresAt)) {
+      const ttl = expiresAt - Date.now();
+      if (ttl > 0) {
+        return ttl;
+      }
+    }
+  }
+
+  return DEFAULT_JWKS_CACHE_MS;
+}
+
+function decodeSegment<T extends Record<string, unknown>>(segment: string): T | undefined {
+  const decoded = decodeBase64Url(segment);
+  if (!decoded) {
+    return undefined;
+  }
+
+  try {
+    const json = decoded.toString('utf8');
+    return JSON.parse(json) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+function decodeBase64Url(value: string): Buffer | undefined {
+  if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+    return undefined;
+  }
+
+  try {
+    return Buffer.from(value, 'base64url');
   } catch {
     return undefined;
   }
@@ -126,13 +394,47 @@ function audienceMatches(value: unknown, expected: string): boolean {
   return false;
 }
 
+function isValidTimeClaims(payload: Record<string, unknown>, now: number): boolean {
+  if (payload.iat !== undefined && parseNumericDateClaim(payload.iat) === undefined) {
+    return false;
+  }
+
+  const notBefore = parseNumericDateClaim(payload.nbf);
+  if (payload.nbf !== undefined && notBefore === undefined) {
+    return false;
+  }
+  if (notBefore !== undefined && now < notBefore) {
+    return false;
+  }
+
+  const expiresAt = parseNumericDateClaim(payload.exp);
+  if (payload.exp !== undefined && expiresAt === undefined) {
+    return false;
+  }
+  if (expiresAt !== undefined && now >= expiresAt) {
+    return false;
+  }
+
+  return true;
+}
+
+function parseNumericDateClaim(value: unknown): number | undefined {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return undefined;
+  }
+  return value;
+}
+
 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 value
+      .split(' ')
+      .map((scope) => scope.trim())
+      .filter((scope) => scope.length > 0);
   }
   return [];
 }
@@ -143,18 +445,15 @@ function normalizeRoles(value: unknown): string[] {
     return value.map((role) => String(role));
   }
   if (typeof value === 'string') {
-    return value.split(',').map((role) => role.trim()).filter((role) => role.length > 0);
+    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;
+function getHeader(request: Pick<Request, 'headers'>, name: string): string | undefined {
+  const normalized = request.headers.get(name) ?? request.headers.get(name.toLowerCase());
+  return normalized ?? undefined;
 }