tina4-nodejs 3.0.0-rc.2

package/packages/core/src/auth.ts

@@ -0,0 +1,287 @@
+/**
+ * Tina4 Auth — Zero-dependency JWT, password hashing, and auth middleware.
+ *
+ * Uses only Node.js built-in `crypto` module. No external dependencies.
+ *
+ *   import { createToken, validateToken, hashPassword, checkPassword } from "./auth.js";
+ *
+ *   const token = createToken({ userId: 1 }, "my-secret");
+ *   const payload = validateToken(token, "my-secret");
+ *
+ *   const hash = hashPassword("secret123");
+ *   checkPassword("secret123", hash);  // true
+ */
+import { createHmac, createSign, createVerify, pbkdf2Sync, randomBytes, timingSafeEqual } from "node:crypto";
+import type { Middleware, Tina4Request, Tina4Response } from "./types.js";
+
+// ── Base64url helpers (RFC 7515) ──────────────────────────────────
+
+function base64urlEncode(data: Buffer): string {
+  return data.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function base64urlDecode(str: string): Buffer {
+  let s = str.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = 4 - (s.length % 4);
+  if (pad !== 4) s += "=".repeat(pad);
+  return Buffer.from(s, "base64");
+}
+
+// ── JWT ───────────────────────────────────────────────────────────
+
+/**
+ * Create a signed JWT token.
+ *
+ * @param payload  - Claims to encode (e.g. `{ userId: 1, role: "admin" }`)
+ * @param secret   - HMAC secret (HS256) or PEM private key (RS256)
+ * @param expiresIn - Lifetime in seconds (default 3600)
+ * @param algorithm - "HS256" or "RS256" (default "HS256")
+ * @returns Signed JWT string: header.payload.signature
+ */
+export function createToken(
+  payload: Record<string, unknown>,
+  secret: string,
+  expiresIn: number = 3600,
+  algorithm: string = "HS256",
+): string {
+  const header = { alg: algorithm, typ: "JWT" };
+  const now = Math.floor(Date.now() / 1000);
+
+  const claims: Record<string, unknown> = { ...payload, iat: now };
+  if (expiresIn !== 0) {
+    claims.exp = now + expiresIn;
+  }
+
+  const h = base64urlEncode(Buffer.from(JSON.stringify(header)));
+  const p = base64urlEncode(Buffer.from(JSON.stringify(claims)));
+  const signingInput = `${h}.${p}`;
+  const signature = sign(signingInput, secret, algorithm);
+
+  return `${h}.${p}.${signature}`;
+}
+
+/**
+ * Validate a JWT token and return the decoded payload, or null if invalid/expired.
+ */
+export function validateToken(
+  token: string,
+  secret: string,
+  algorithm: string = "HS256",
+): Record<string, unknown> | null {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) return null;
+
+    const [h, p, sig] = parts;
+    const signingInput = `${h}.${p}`;
+
+    if (!verifySignature(signingInput, sig, secret, algorithm)) {
+      return null;
+    }
+
+    const payload = JSON.parse(base64urlDecode(p).toString()) as Record<string, unknown>;
+
+    if (typeof payload.exp === "number" && Date.now() / 1000 > payload.exp) {
+      return null;
+    }
+
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the JWT payload WITHOUT verifying signature or expiration.
+ */
+export function getPayload(token: string): Record<string, unknown> | null {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) return null;
+    return JSON.parse(base64urlDecode(parts[1]).toString()) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+// ── Signing helpers ───────────────────────────────────────────────
+
+function sign(input: string, secret: string, algorithm: string): string {
+  if (algorithm === "HS256") {
+    const sig = createHmac("sha256", secret).update(input).digest();
+    return base64urlEncode(sig);
+  }
+  if (algorithm === "RS256") {
+    const signer = createSign("RSA-SHA256");
+    signer.update(input);
+    const sig = signer.sign(secret);
+    return base64urlEncode(sig);
+  }
+  throw new Error(`Unsupported algorithm: ${algorithm}`);
+}
+
+function verifySignature(input: string, sig: string, secret: string, algorithm: string): boolean {
+  if (algorithm === "HS256") {
+    const expected = sign(input, secret, algorithm);
+    // Constant-time comparison
+    const a = Buffer.from(sig);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length) return false;
+    return timingSafeEqual(a, b);
+  }
+  if (algorithm === "RS256") {
+    const verifier = createVerify("RSA-SHA256");
+    verifier.update(input);
+    return verifier.verify(secret, base64urlDecode(sig));
+  }
+  throw new Error(`Unsupported algorithm: ${algorithm}`);
+}
+
+// ── Password Hashing (PBKDF2) ────────────────────────────────────
+
+/**
+ * Hash a password using PBKDF2-SHA256.
+ *
+ * @param password   - Plaintext password
+ * @param salt       - Hex-encoded salt (auto-generated if omitted)
+ * @param iterations - PBKDF2 iterations (default 100000)
+ * @returns Format: `pbkdf2_sha256:iterations:salt:hash` (all hex-encoded)
+ */
+export function hashPassword(
+  password: string,
+  salt?: string,
+  iterations: number = 100000,
+): string {
+  const actualSalt = salt ?? randomBytes(16).toString("hex");
+  const dk = pbkdf2Sync(password, actualSalt, iterations, 32, "sha256");
+  return `pbkdf2_sha256:${iterations}:${actualSalt}:${dk.toString("hex")}`;
+}
+
+/**
+ * Check a password against a PBKDF2 hash string.
+ */
+export function checkPassword(password: string, hash: string): boolean {
+  try {
+    const parts = hash.split(":");
+    if (parts.length !== 4 || parts[0] !== "pbkdf2_sha256") return false;
+
+    const iterations = parseInt(parts[1], 10);
+    const salt = parts[2];
+    const expected = parts[3];
+
+    const dk = pbkdf2Sync(password, salt, iterations, 32, "sha256");
+    const actual = dk.toString("hex");
+
+    // Constant-time comparison
+    const a = Buffer.from(actual);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length) return false;
+    return timingSafeEqual(a, b);
+  } catch {
+    return false;
+  }
+}
+
+// ── Auth Middleware ───────────────────────────────────────────────
+
+/**
+ * Auth middleware that extracts and verifies a Bearer JWT from the
+ * Authorization header. On success, attaches the decoded payload to
+ * `(request as any).auth`. On failure, sends a 401 JSON response.
+ */
+export function authMiddleware(secret: string, algorithm: string = "HS256"): Middleware {
+  return (req: Tina4Request, res: Tina4Response, next: () => void): void => {
+    const authHeader = req.headers.authorization ?? "";
+
+    if (!authHeader.startsWith("Bearer ")) {
+      res({ error: "Unauthorized" }, 401);
+      return;
+    }
+
+    const token = authHeader.slice(7);
+    const payload = validateToken(token, secret, algorithm);
+
+    if (payload === null) {
+      res({ error: "Unauthorized" }, 401);
+      return;
+    }
+
+    (req as any).auth = payload;
+    next();
+  };
+}
+
+// ── Token Refresh ────────────────────────────────────────────────
+
+/**
+ * Refresh a JWT token — validate the existing token then re-sign
+ * with a fresh expiry.
+ *
+ * @param token     - Existing JWT to refresh
+ * @param secret    - HMAC secret or PEM key
+ * @param expiresIn - New lifetime in seconds (default 3600)
+ * @param algorithm - "HS256" or "RS256" (default "HS256")
+ * @returns New signed JWT string, or null if the input token is invalid/expired
+ */
+export function refreshToken(
+  token: string,
+  secret: string,
+  expiresIn: number = 3600,
+  algorithm: string = "HS256",
+): string | null {
+  const payload = validateToken(token, secret, algorithm);
+  if (payload === null) return null;
+
+  // Strip standard timing claims so createToken sets fresh ones
+  const { iat: _iat, exp: _exp, ...claims } = payload;
+  return createToken(claims, secret, expiresIn, algorithm);
+}
+
+// ── Request Authentication ───────────────────────────────────────
+
+/**
+ * Extract a Bearer token from request headers and validate it.
+ *
+ * @param headers   - Object with header keys (e.g. `{ authorization: "Bearer ..." }`)
+ * @param secret    - HMAC secret or PEM public key
+ * @param algorithm - "HS256" or "RS256" (default "HS256")
+ * @returns Decoded payload, or null if missing/invalid
+ */
+export function authenticateRequest(
+  headers: Record<string, string | string[] | undefined>,
+  secret: string,
+  algorithm: string = "HS256",
+): Record<string, unknown> | null {
+  const authHeader =
+    (headers.authorization ?? headers.Authorization ?? "") as string;
+
+  if (!authHeader.startsWith("Bearer ")) return null;
+
+  const token = authHeader.slice(7);
+  return validateToken(token, secret, algorithm);
+}
+
+// ── API Key Validation ───────────────────────────────────────────
+
+/**
+ * Compare an API key against an expected value.
+ * If `expected` is omitted, falls back to the `TINA4_API_KEY` env var.
+ *
+ * Uses constant-time comparison to prevent timing attacks.
+ *
+ * @param provided - The API key provided by the caller
+ * @param expected - The correct API key (defaults to `process.env.TINA4_API_KEY`)
+ * @returns true if the keys match
+ */
+export function validateApiKey(
+  provided: string,
+  expected?: string,
+): boolean {
+  const key = expected ?? process.env.TINA4_API_KEY;
+  if (!key || !provided) return false;
+
+  const a = Buffer.from(provided);
+  const b = Buffer.from(key);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}

package/packages/core/src/cache.ts

@@ -0,0 +1,121 @@
+/**
+ * In-memory response cache for GET requests.
+ * Caches serialized responses by URL + query string.
+ *
+ * Usage:
+ *   import { responseCache } from "./cache.js";
+ *
+ *   // As middleware — caches GET responses for ttl seconds
+ *   middleware.use(responseCache({ ttl: 60 }));
+ *
+ *   // Per-route cache via meta
+ *   export const meta = { cache: 30 }; // cache 30 seconds
+ *
+ * Environment:
+ *   TINA4_CACHE_TTL — default TTL in seconds (default: 0 = disabled)
+ */
+
+import type { Middleware } from "./types.js";
+
+interface CacheEntry {
+  body: string;
+  contentType: string;
+  statusCode: number;
+  expiresAt: number;
+}
+
+export interface ResponseCacheConfig {
+  /** Default TTL in seconds. 0 = disabled. Default: 60 */
+  ttl?: number;
+  /** Maximum cache entries. Default: 1000 */
+  maxEntries?: number;
+  /** Only cache these status codes. Default: [200] */
+  statusCodes?: number[];
+}
+
+const store = new Map<string, CacheEntry>();
+
+/**
+ * Response cache middleware for GET requests.
+ * Caches the full response body, content-type, and status code.
+ * Cache key is method + url (including query string).
+ */
+export function responseCache(config?: ResponseCacheConfig): Middleware {
+  const ttl = config?.ttl
+    ?? (process.env.TINA4_CACHE_TTL ? parseInt(process.env.TINA4_CACHE_TTL, 10) : 60);
+  const maxEntries = config?.maxEntries ?? 1000;
+  const allowedCodes = new Set(config?.statusCodes ?? [200]);
+
+  if (ttl <= 0) {
+    // Cache disabled — pass through
+    return (_req, _res, next) => next();
+  }
+
+  // Periodic cleanup
+  const cleanupTimer = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of store) {
+      if (now > entry.expiresAt) store.delete(key);
+    }
+  }, 30_000);
+  if (cleanupTimer.unref) cleanupTimer.unref();
+
+  return (req, res, next) => {
+    // Only cache GET requests
+    if (req.method !== "GET") {
+      next();
+      return;
+    }
+
+    const cacheKey = `GET:${req.url}`;
+    const cached = store.get(cacheKey);
+
+    if (cached && Date.now() < cached.expiresAt) {
+      // Cache HIT
+      res.header("X-Cache", "HIT");
+      res.header("Content-Type", cached.contentType);
+      res(cached.body, cached.statusCode, cached.contentType);
+      return;
+    }
+
+    // Cache MISS — intercept the response to capture it
+    const originalEnd = res.raw.end.bind(res.raw);
+    let captured = false;
+
+    res.raw.end = function (chunk?: any, ...args: any[]) {
+      if (!captured && allowedCodes.has(res.raw.statusCode)) {
+        captured = true;
+        const body = typeof chunk === "string" ? chunk : chunk?.toString() ?? "";
+        const contentType = String(res.raw.getHeader("Content-Type") ?? "application/octet-stream");
+
+        // Evict oldest if at capacity
+        if (store.size >= maxEntries) {
+          const firstKey = store.keys().next().value;
+          if (firstKey) store.delete(firstKey);
+        }
+
+        store.set(cacheKey, {
+          body,
+          contentType,
+          statusCode: res.raw.statusCode,
+          expiresAt: Date.now() + ttl * 1000,
+        });
+      }
+
+      res.header("X-Cache", "MISS");
+      return originalEnd(chunk, ...args);
+    } as any;
+
+    next();
+  };
+}
+
+/** Clear all cached responses */
+export function clearCache(): void {
+  store.clear();
+}
+
+/** Get cache stats */
+export function cacheStats(): { size: number; keys: string[] } {
+  return { size: store.size, keys: [...store.keys()] };
+}

package/packages/core/src/constants.ts

@@ -0,0 +1,48 @@
+/**
+ * Tina4 Constants — HTTP status codes and content types.
+ *
+ * Standard constants for use in route handlers across all Tina4 frameworks.
+ *
+ *   import { HTTP_OK, HTTP_CREATED, APPLICATION_JSON } from "@tina4/core";
+ *
+ *   get("/api/users", async (request, response) => {
+ *       return response(users, HTTP_OK);
+ *   });
+ */
+
+// ── HTTP Status Codes ──
+
+export const HTTP_OK = 200;
+export const HTTP_CREATED = 201;
+export const HTTP_ACCEPTED = 202;
+export const HTTP_NO_CONTENT = 204;
+
+export const HTTP_MOVED = 301;
+export const HTTP_REDIRECT = 302;
+export const HTTP_NOT_MODIFIED = 304;
+
+export const HTTP_BAD_REQUEST = 400;
+export const HTTP_UNAUTHORIZED = 401;
+export const HTTP_FORBIDDEN = 403;
+export const HTTP_NOT_FOUND = 404;
+export const HTTP_METHOD_NOT_ALLOWED = 405;
+export const HTTP_CONFLICT = 409;
+export const HTTP_GONE = 410;
+export const HTTP_UNPROCESSABLE = 422;
+export const HTTP_TOO_MANY = 429;
+
+export const HTTP_SERVER_ERROR = 500;
+export const HTTP_BAD_GATEWAY = 502;
+export const HTTP_UNAVAILABLE = 503;
+
+// ── Content Types ──
+
+export const APPLICATION_JSON = "application/json";
+export const APPLICATION_XML = "application/xml";
+export const APPLICATION_FORM = "application/x-www-form-urlencoded";
+export const APPLICATION_OCTET = "application/octet-stream";
+
+export const TEXT_HTML = "text/html; charset=utf-8";
+export const TEXT_PLAIN = "text/plain; charset=utf-8";
+export const TEXT_CSV = "text/csv";
+export const TEXT_XML = "text/xml";

package/packages/core/src/container.ts

@@ -0,0 +1,90 @@
+/**
+ * Lightweight dependency injection container.
+ *
+ * Matches the Python tina4_python.container.Container API.
+ *
+ *   import { Container, container } from "@tina4/core";
+ *
+ *   container.register("mailer", () => new MailService());
+ *   container.singleton("db", () => new Database("sqlite:///app.db"));
+ *
+ *   const mailer = container.get<MailService>("mailer"); // new instance each call
+ *   const db     = container.get<Database>("db");        // same instance every call
+ *
+ * Node.js is single-threaded so no locking is needed.
+ */
+
+export class Container {
+  private transients = new Map<string, () => unknown>();
+  private singletons = new Map<string, () => unknown>();
+  private instances = new Map<string, unknown>();
+
+  /**
+   * Register a transient factory — a new instance is created on every `get()` call.
+   */
+  register(name: string, factory: () => unknown): void {
+    if (typeof factory !== "function") {
+      throw new TypeError(`factory for '${name}' must be callable`);
+    }
+    // Remove from singletons/instances if previously registered there
+    this.singletons.delete(name);
+    this.instances.delete(name);
+    this.transients.set(name, factory);
+  }
+
+  /**
+   * Register a singleton factory — created once on first `get()`, then memoised.
+   */
+  singleton(name: string, factory: () => unknown): void {
+    if (typeof factory !== "function") {
+      throw new TypeError(`factory for '${name}' must be callable`);
+    }
+    // Remove from transients if previously registered there
+    this.transients.delete(name);
+    this.instances.delete(name);
+    this.singletons.set(name, factory);
+  }
+
+  /**
+   * Resolve a dependency by name.
+   *
+   * Throws an `Error` if the name has not been registered.
+   */
+  get<T = unknown>(name: string): T {
+    // Check transient first
+    const transientFactory = this.transients.get(name);
+    if (transientFactory) {
+      return transientFactory() as T;
+    }
+
+    // Check singleton
+    const singletonFactory = this.singletons.get(name);
+    if (singletonFactory) {
+      if (!this.instances.has(name)) {
+        this.instances.set(name, singletonFactory());
+      }
+      return this.instances.get(name) as T;
+    }
+
+    throw new Error(`service not registered: ${name}`);
+  }
+
+  /**
+   * Return `true` if *name* has been registered (transient or singleton).
+   */
+  has(name: string): boolean {
+    return this.transients.has(name) || this.singletons.has(name);
+  }
+
+  /**
+   * Clear all registrations and cached instances.
+   */
+  reset(): void {
+    this.transients.clear();
+    this.singletons.clear();
+    this.instances.clear();
+  }
+}
+
+/** Default container instance. */
+export const container = new Container();