@bloomneo/appkit 1.5.1 → 1.5.2

package/examples/auth.ts

@@ -0,0 +1,228 @@
+/**
+ * CANONICAL PATTERN — JWT auth with role-based middleware.
+ *
+ * Verified against src/auth/README.md (lines 426-479: API Reference)
+ * and src/auth/auth.ts (real public method signatures).
+ *
+ * Two token types: LOGIN tokens for users, API tokens for services.
+ * Middleware chains: `requireLoginToken()` FIRST, then `requireUserRoles()`
+ * — never the reverse, never standalone, never with API tokens.
+ *
+ * Required env: BLOOM_AUTH_SECRET (min 32 chars)
+ */
+
+import { authClass } from '@bloomneo/appkit/auth';
+import type {
+  ExpressRequest,
+  ExpressResponse,
+  ExpressMiddleware,
+} from '@bloomneo/appkit/auth';
+
+const auth = authClass.get();
+
+// ── Token generation ────────────────────────────────────────────────
+
+// Login token: for human users (web/mobile login). 7-day expiry typical.
+const loginToken: string = auth.generateLoginToken(
+  {
+    userId: 123,
+    role: 'user',
+    level: 'basic',
+  },
+  '7d',
+);
+
+// API token: for services / webhooks / integrations. 1-year expiry typical.
+//
+// IMPORTANT: the role.level you pass MUST exist in the configured role
+// hierarchy or generateApiToken throws "Invalid role.level". The default
+// hierarchy ships with `user.basic` → `admin.system` (9 user roles, no
+// service roles). For service tokens you have two options:
+//
+//   1. Use one of the default roles (e.g. `admin.system`) — what we do here.
+//   2. Register custom service roles via the BLOOM_AUTH_ROLES env var, e.g.
+//      BLOOM_AUTH_ROLES=user.basic:1,...,service.webhook:10
+//      and then pass `role: 'service', level: 'webhook'` here.
+//
+// Option 1 is simpler when the API token holder needs full system access.
+// Option 2 is correct when you want narrower scopes for different services.
+const apiToken: string = auth.generateApiToken(
+  {
+    keyId: 'webhook_payment_service',
+    role: 'admin',
+    level: 'system',
+  },
+  '1y',
+);
+
+// ── Middleware (use these in route definitions) ─────────────────────
+
+// 1. Authenticate ANY logged-in user
+const protectAuthenticated: ExpressMiddleware = auth.requireLoginToken();
+
+// 2. Require specific user role (chained AFTER requireLoginToken)
+const requireAdmin: ExpressMiddleware = auth.requireUserRoles(['admin.tenant']);
+
+// 3. Require any of multiple roles (OR semantics)
+const requireAdminOrOrg: ExpressMiddleware = auth.requireUserRoles([
+  'admin.tenant',
+  'admin.org',
+]);
+
+// 4. Require specific permissions (AND semantics across the array)
+const requireUserManagement: ExpressMiddleware = auth.requireUserPermissions([
+  'manage:users',
+  'edit:tenant',
+]);
+
+// 5. API token authentication (services only — DO NOT chain with requireUserRoles)
+const protectApi: ExpressMiddleware = auth.requireApiToken();
+
+// ── Route handlers (called by Express after middleware passes) ──────
+
+// Login handler: bcrypt check + token issue
+async function loginHandler(req: ExpressRequest, res: ExpressResponse) {
+  const { email, password } = (req.body ?? {}) as { email?: string; password?: string };
+
+  // Look up the user from your database. Placeholder.
+  const user = {
+    id: 1,
+    email,
+    passwordHash: '$2b$10$placeholder',
+    role: 'user',
+    level: 'basic',
+  };
+
+  const valid = await auth.comparePassword(password ?? '', user.passwordHash);
+  if (!valid) {
+    res.status?.(401).json?.({ error: 'Invalid credentials' });
+    return;
+  }
+
+  const token = auth.generateLoginToken({
+    userId: user.id,
+    role: user.role,
+    level: user.level,
+  });
+
+  res.json?.({ token });
+}
+
+// Registration handler: bcrypt hash + token issue
+async function registerHandler(req: ExpressRequest, res: ExpressResponse) {
+  const { email, password } = (req.body ?? {}) as { email?: string; password?: string };
+  const hashedPassword = await auth.hashPassword(password ?? '');
+  // Save { email, password: hashedPassword } to your database. Placeholder.
+  void hashedPassword;
+  void email;
+  const newUserId = 42;
+
+  const token = auth.generateLoginToken({
+    userId: newUserId,
+    role: 'user',
+    level: 'basic',
+  });
+
+  res.json?.({ token });
+}
+
+// Authenticated handler: extract user safely from req
+function profileHandler(req: ExpressRequest, res: ExpressResponse) {
+  const user = auth.user(req);  // null-safe; non-null after requireLoginToken
+  if (!user) {
+    res.status?.(401).json?.({ error: 'Not authenticated' });
+    return;
+  }
+  res.json?.({ user });
+}
+
+// ── Programmatic role hierarchy check (outside middleware) ──────────
+
+const orgIncludesTenant: boolean = auth.hasRole('admin.org', 'admin.tenant');  // true
+const userIsAdmin: boolean = auth.hasRole('user.basic', 'admin.tenant');       // false
+
+// ── Verify a token manually (outside middleware) ────────────────────
+//
+// `verifyToken` is what the middleware uses internally. You normally don't
+// call it yourself — `requireLoginToken()` and `requireApiToken()` handle
+// it for you. Use this only when you need to validate a token in a
+// non-Express context (e.g. WebSocket auth, queue worker auth, scheduled
+// task auth). Throws on bad token; never returns null.
+function verifyTokenManually(rawToken: string) {
+  try {
+    const payload = auth.verifyToken(rawToken);
+    // payload.userId is set for login tokens; payload.keyId is set for API tokens.
+    // payload.type tells you which: 'login' or 'api_key'.
+    return payload;
+  } catch (e) {
+    // Possible messages: 'Token has expired', 'Invalid token',
+    // 'Token must be a string', 'Token verification failed: ...'
+    return null;
+  }
+}
+
+// ── Permission check with inheritance (auth.can) ────────────────────
+//
+// `can` checks fine-grained permissions on a user payload. Permission format
+// is `action:scope` (e.g. 'edit:tenant', 'manage:users'). Inheritance rule:
+// `manage:scope` automatically grants `view:scope`, `edit:scope`,
+// `delete:scope`, etc. for the same scope.
+//
+// Use this inside a route handler AFTER `requireLoginToken()` middleware
+// has validated the user and attached the payload.
+function permissionCheckHandler(req: ExpressRequest, res: ExpressResponse) {
+  const user = auth.user(req);
+  if (!user) {
+    res.status?.(401).json?.({ error: 'Not authenticated' });
+    return;
+  }
+
+  // Check if the user can edit their tenant. Returns true if the user has
+  // 'edit:tenant' OR 'manage:tenant' (manage inherits all actions).
+  const canEdit: boolean = auth.can(user, 'edit:tenant');
+  if (!canEdit) {
+    res.status?.(403).json?.({ error: 'Cannot edit tenant' });
+    return;
+  }
+
+  res.json?.({ allowed: true });
+}
+
+// ── Express wiring (commented — uncomment in your app) ──────────────
+//
+//   import express from 'express';
+//   const app = express();
+//
+//   app.post('/login', loginHandler);
+//   app.post('/register', registerHandler);
+//
+//   // User route: login + role required
+//   app.get(
+//     '/admin/users',
+//     auth.requireLoginToken(),
+//     auth.requireUserRoles(['admin.tenant']),
+//     profileHandler,
+//   );
+//
+//   // API route: API token only (no user roles)
+//   app.post('/webhook/payment', auth.requireApiToken(), (req, res) => {
+//     res.json({ ok: true });
+//   });
+
+export {
+  auth,
+  loginToken,
+  apiToken,
+  protectAuthenticated,
+  requireAdmin,
+  requireAdminOrOrg,
+  requireUserManagement,
+  protectApi,
+  verifyTokenManually,
+  permissionCheckHandler,
+  loginHandler,
+  registerHandler,
+  profileHandler,
+  orgIncludesTenant,
+  userIsAdmin,
+};

package/examples/cache.ts

@@ -0,0 +1,36 @@
+/**
+ * CANONICAL PATTERN — cache.getOrSet for "fetch once, cache the result".
+ *
+ * Copy this file when you need to cache anything. The getOrSet pattern is
+ * the right answer 90% of the time — never write the cache-check-then-fetch
+ * pattern manually.
+ *
+ * Set REDIS_URL in .env to upgrade from in-process memory to distributed
+ * Redis cache. Same code works for both — no changes needed.
+ */
+
+import { cacheClass, databaseClass, errorClass } from '@bloomneo/appkit';
+
+const error = errorClass.get();
+const database = await databaseClass.get();
+
+// Custom namespace isolates this cache from others (default is 'app').
+const cache = cacheClass.get('users');
+
+// ── Cached database query ─────────────────────────────────────────────
+export const listProductsRoute = error.asyncRoute(async (req, res) => {
+  const products = await cache.getOrSet(
+    'products:list',
+    () => database.product.findMany({ where: { published: true } }),
+    300, // 5 minutes
+  );
+  res.json({ products });
+});
+
+// ── Manual operations (use sparingly — getOrSet is preferred) ────────
+export async function manualCacheExample() {
+  await cache.set('foo', 'bar', 60);                       // 1 minute TTL
+  const v = await cache.get('foo');                        // → 'bar'
+  const exists = v !== null;                               // presence check: get() returns null on miss
+  await cache.delete('foo');                               // delete() — not del()
+}

package/examples/config.ts

@@ -0,0 +1,45 @@
+/**
+ * CANONICAL PATTERN — type-safe environment variable access.
+ *
+ * Copy this file when you need to read configuration. Always go through
+ * configClass.get() instead of touching process.env directly — config
+ * validates types, provides defaults, and supports the BLOOM_* prefix
+ * convention.
+ *
+ * Read AGENTS.md for the full env var reference.
+ */
+
+import { configClass } from '@bloomneo/appkit';
+
+const config = configClass.get();
+
+// ── Read string config (with default) ───────────────────────────────
+const apiHost = config.get('api.host', 'localhost');
+const dbUrl = config.get('database.url');                  // throws if not set
+
+// ── Read typed config ───────────────────────────────────────────────
+// config.get() returns the value as-is. Cast to number/boolean yourself.
+const port = Number(config.get('api.port') ?? 3000);
+const debugMode = config.get('app.debug') === 'true';
+
+// ── Environment detection ───────────────────────────────────────────
+// isDevelopment() / isProduction() / isTest() live on configClass, NOT on the
+// instance returned by configClass.get(). Always call them via configClass.*.
+if (configClass.isDevelopment()) {
+  console.log('Running in dev mode');
+}
+if (configClass.isProduction()) {
+  // tighter security defaults, etc.
+}
+
+// ── Validate required env vars at startup ───────────────────────────
+// Call this once in your server bootstrap. Throws with a clear error message
+// listing every missing variable.
+config.validateRequired([
+  'BLOOM_AUTH_SECRET',
+  'DATABASE_URL',
+  'BLOOM_SECURITY_CSRF_SECRET',
+  'BLOOM_SECURITY_ENCRYPTION_KEY',
+]);
+
+export { config, apiHost, dbUrl, port, debugMode };

package/examples/database.ts

@@ -0,0 +1,69 @@
+/**
+ * CANONICAL PATTERN — multi-tenant database access.
+ *
+ * Verified against src/database/README.md (Core API + LLM Guidelines sections)
+ * and src/database/index.ts.
+ *
+ * Three core methods:
+ *   • databaseClass.get()         → tenant-aware client (single user mode)
+ *   • databaseClass.getTenants()  → unfiltered client (admin / cross-tenant)
+ *   • databaseClass.org('name').get() / .getTenants() → per-org databases
+ *
+ * Required env: DATABASE_URL
+ * Optional env: BLOOM_DB_TENANT=auto (enables multi-tenant filtering)
+ */
+
+import { databaseClass } from '@bloomneo/appkit/database';
+
+// ── Normal user access (auto-filtered by tenant when BLOOM_DB_TENANT=auto) ──
+async function listUsers() {
+  const database = await databaseClass.get();
+  // Returns only rows belonging to the current tenant.
+  // The shape of `database.user` matches your Prisma / Mongoose model.
+  // Placeholder query — replace with your actual model.
+  const users = await (database as any).user?.findMany?.() ?? [];
+  return users;
+}
+
+// ── Admin: cross-tenant query (unfiltered) ──────────────────────────
+async function listAllUsersAcrossTenants() {
+  const dbTenants = await databaseClass.getTenants();
+  const allUsers = await (dbTenants as any).user?.findMany?.() ?? [];
+  return allUsers;
+}
+
+// ── Admin: per-tenant analytics ─────────────────────────────────────
+async function tenantAnalytics() {
+  const dbTenants = await databaseClass.getTenants();
+  const stats = await (dbTenants as any).user?.groupBy?.({
+    by: ['tenant_id'],
+    _count: { _all: true },
+  }) ?? [];
+  return stats;
+}
+
+// ── Multi-org: per-organization database ────────────────────────────
+// Set ORG_ACME=postgresql://acme.aws.com/prod in .env, then:
+async function listAcmeUsers() {
+  const acmedatabase = await databaseClass.org('acme').get();
+  const users = await (acmedatabase as any).user?.findMany?.() ?? [];
+  return users;
+}
+
+// ── Multi-org admin: all tenants in a single org ────────────────────
+async function acmeTenantStats() {
+  const acmeDbTenants = await databaseClass.org('acme').getTenants();
+  const stats = await (acmeDbTenants as any).user?.groupBy?.({
+    by: ['tenant_id'],
+    _count: { _all: true },
+  }) ?? [];
+  return stats;
+}
+
+export {
+  listUsers,
+  listAllUsersAcrossTenants,
+  tenantAnalytics,
+  listAcmeUsers,
+  acmeTenantStats,
+};

package/examples/email.ts

@@ -0,0 +1,53 @@
+/**
+ * CANONICAL PATTERN — send email with auto-scaling provider.
+ *
+ * Copy this file when you need to send email. Default is console (logs to
+ * terminal — perfect for development). Set SMTP_HOST + SMTP_USER + SMTP_PASS
+ * to use SMTP. Set RESEND_API_KEY to use Resend.
+ *
+ * Same code works for all three providers — no changes needed.
+ */
+
+import { emailClass, errorClass } from '@bloomneo/appkit';
+
+const email = emailClass.get();
+const error = errorClass.get();
+
+// ── Plain text email ────────────────────────────────────────────────
+export async function sendWelcomeEmail(toAddress: string, userName: string) {
+  await email.send({
+    to: toAddress,
+    subject: 'Welcome to MyApp',
+    text: `Hi ${userName},\n\nThanks for signing up!\n\n— The Team`,
+  });
+}
+
+// ── HTML email with plain-text fallback ─────────────────────────────
+export async function sendInvoiceEmail(toAddress: string, invoiceUrl: string) {
+  await email.send({
+    to: toAddress,
+    subject: 'Your invoice is ready',
+    text: `Your invoice: ${invoiceUrl}`,
+    html: `<p>Your invoice: <a href="${invoiceUrl}">${invoiceUrl}</a></p>`,
+  });
+}
+
+// ── Templated email ─────────────────────────────────────────────────
+// EmailData (used by email.send()) only accepts: to, from, subject, text,
+// html, attachments, replyTo, cc, bcc — it has no template/data fields.
+// Use email.sendTemplate() for template-driven emails.
+export async function sendPasswordResetEmail(toAddress: string, resetLink: string) {
+  await email.sendTemplate('password-reset', {
+    to: toAddress,
+    resetLink,
+    expiresIn: '1 hour',
+  });
+}
+
+// ── Inside a route handler ──────────────────────────────────────────
+export const sendNotificationRoute = error.asyncRoute(async (req, res) => {
+  const { to, message } = req.body;
+  if (!to || !message) throw error.badRequest('to and message required');
+  await email.send({ to, subject: 'Notification', text: message });
+  res.json({ sent: true });
+});

package/examples/error.ts

@@ -0,0 +1,50 @@
+/**
+ * CANONICAL PATTERN — semantic HTTP errors + centralized middleware.
+ *
+ * Copy this file when you need error handling in routes. The pattern:
+ *   1. Wrap async route handlers in error.asyncRoute(...)
+ *   2. Throw semantic errors (badRequest, unauthorized, notFound, etc.)
+ *      — never `throw new Error(...)` in route handlers
+ *   3. Mount error.handleErrors() as the LAST middleware in the Express stack
+ *
+ * The asyncRoute wrapper catches the throw, and handleErrors() converts
+ * the semantic error into the right HTTP status + JSON response.
+ */
+
+import express from 'express';
+import { errorClass, databaseClass } from '@bloomneo/appkit';
+
+const error = errorClass.get();
+const database = await databaseClass.get();
+const app = express();
+
+// ── Routes use asyncRoute + semantic error throws ───────────────────
+app.get('/api/users/:id', error.asyncRoute(async (req, res) => {
+  const id = Number(req.params.id);
+  if (!Number.isFinite(id)) throw error.badRequest('id must be a number');
+
+  const user = await database.user.findUnique({ where: { id } });
+  if (!user) throw error.notFound('User not found');
+
+  res.json({ user });
+}));
+
+app.post('/api/admin', error.asyncRoute(async (req, res) => {
+  if (req.body.role !== 'admin') throw error.forbidden('Admin role required');
+  // ...
+}));
+
+// ── Available semantic error throwers ───────────────────────────────
+//
+//   throw error.badRequest('message')        → 400
+//   throw error.unauthorized('message')      → 401
+//   throw error.forbidden('message')         → 403
+//   throw error.notFound('message')          → 404
+//   throw error.conflict('message')          → 409
+//   throw error.tooMany('message')           → 429  (rate limiting)
+//   throw error.serverError('message')       → 500
+//   throw error.internal('message')          → 500  (alias for serverError)
+//   throw error.createError(503, 'message')  → any code
+
+// ── MOUNT error.handleErrors() LAST in the middleware stack ─────────
+app.use(error.handleErrors());

package/examples/event.ts

@@ -0,0 +1,42 @@
+/**
+ * CANONICAL PATTERN — pub/sub events with auto-scaling backend.
+ *
+ * Copy this file when you need events. Default is in-process memory (single
+ * Node process). Set REDIS_URL to distribute events across processes / servers
+ * — same code works in both modes.
+ *
+ * Use namespaces (eventClass.get('users')) to isolate event streams.
+ */
+
+import { eventClass, loggerClass } from '@bloomneo/appkit';
+
+const events = eventClass.get('users');  // namespaced
+const logger = loggerClass.get('events');
+
+// ── Subscribe to a single event ─────────────────────────────────────
+events.on('user.created', async (data) => {
+  logger.info('New user', { userId: data.userId });
+  // ...trigger welcome email, analytics, etc.
+});
+
+// ── Subscribe to a wildcard pattern ─────────────────────────────────
+events.on('user.*', async (eventName, data) => {
+  logger.debug(`User event: ${eventName}`, data);
+});
+
+// ── Emit an event from a route handler ──────────────────────────────
+import { errorClass } from '@bloomneo/appkit';
+const error = errorClass.get();
+
+export const createUserRoute = error.asyncRoute(async (req, res) => {
+  // ...create the user in the database
+  const newUser = { id: 123, email: req.body.email };
+
+  await events.emit('user.created', {
+    userId: newUser.id,
+    email: newUser.email,
+    timestamp: new Date(),
+  });
+
+  res.json({ user: newUser });
+});

package/examples/logger.ts

@@ -0,0 +1,41 @@
+/**
+ * CANONICAL PATTERN — structured logging with component tagging.
+ *
+ * Copy this file when you need logging. The pattern: get a component-tagged
+ * logger at module scope, then call .info() / .warn() / .error() with a
+ * message + meta object. Logs are structured JSON in production, pretty
+ * console output in development.
+ *
+ * Set BLOOM_LOGGER_FILE_PATH to also write to a file.
+ * Set BLOOM_LOGGER_HTTP_URL to ship to a centralized log collector.
+ * Same code works in all three modes.
+ */
+
+import { loggerClass } from '@bloomneo/appkit';
+
+// Component-tagged logger — use one per file or per logical area.
+const logger = loggerClass.get('users');
+
+export function exampleLogging() {
+  logger.debug('Lookup started', { userId: 42 });          // dev only
+  logger.info('User created', { userId: 42, email: 'a@b' });
+  logger.warn('Slow query', { ms: 3200, table: 'users' });
+  logger.error('Database connection lost', { host: 'db1' });
+  logger.fatal('OOM, exiting', { rss: process.memoryUsage().rss });
+}
+
+// ── Inside a route handler ──────────────────────────────────────────
+import { errorClass } from '@bloomneo/appkit';
+const error = errorClass.get();
+
+export const createUserRoute = error.asyncRoute(async (req, res) => {
+  logger.info('Creating user', { ip: req.ip, email: req.body.email });
+  try {
+    // ...create logic
+    logger.info('User created successfully', { userId: 123 });
+    res.json({ ok: true });
+  } catch (e) {
+    logger.error('User creation failed', { error: (e as Error).message });
+    throw e;
+  }
+});

package/examples/queue.ts

@@ -0,0 +1,58 @@
+/**
+ * CANONICAL PATTERN — background job queue with auto-scaling backend.
+ *
+ * Copy this file when you need background jobs. Default backend is in-process
+ * memory (good for dev). Set REDIS_URL to upgrade to distributed Redis.
+ *
+ * Same code works for all backends — no changes needed.
+ *
+ * queue.add(jobType, data, options)   — enqueue immediately or with a fixed delay
+ * queue.schedule(jobType, data, delayMs) — alias: enqueue with a delay in ms
+ * queue.process(jobType, handler)     — register a worker for that job type
+ *
+ * For cron-style recurring jobs: use a cron library (node-cron, etc.) to call
+ * queue.add() at the right interval — there is no built-in cron scheduler.
+ */
+
+import { queueClass, loggerClass, errorClass } from '@bloomneo/appkit';
+
+const queue = queueClass.get();
+const logger = loggerClass.get('queue');
+const error = errorClass.get();
+
+// ── Producer: enqueue jobs from a route ─────────────────────────────
+export const enqueueEmailRoute = error.asyncRoute(async (req, res) => {
+  const { to, subject, body } = req.body;
+
+  await queue.add(
+    'send-email',
+    { to, subject, body },
+    {
+      delay: 0,       // run immediately (ms)
+      attempts: 3,    // retry up to 3 times on failure (not "retries")
+      priority: 1,    // lower number = higher priority
+    },
+  );
+
+  res.json({ queued: true });
+});
+
+// ── Consumer: process jobs (run in a worker process or main app) ────
+queue.process('send-email', async (data) => {
+  const { to, subject, body } = data as { to: string; subject: string; body: string };
+  logger.info('Email sent', { to, subject });
+  return { sent: true };
+});
+
+// ── Delayed job (run once after N ms, not cron-style) ───────────────
+// To run cleanup every day at 03:00, use node-cron to call queue.add() at the
+// right time — queue.schedule() accepts a delay in milliseconds, not a cron expression.
+await queue.schedule(
+  'cleanup-expired-tokens',
+  {},
+  8 * 60 * 60 * 1000,   // run once, 8 hours from now
+);
+
+queue.process('cleanup-expired-tokens', async () => {
+  logger.info('Token cleanup ran');
+});

package/examples/security.ts

@@ -0,0 +1,46 @@
+/**
+ * CANONICAL PATTERN — rate limiting, CSRF, encryption, input sanitization.
+ *
+ * Copy this file when you need security middleware. AppKit's security module
+ * covers four common needs from one xxxClass.get() instance.
+ *
+ * Required env: BLOOM_SECURITY_CSRF_SECRET, BLOOM_SECURITY_ENCRYPTION_KEY
+ */
+
+import { securityClass, errorClass } from '@bloomneo/appkit';
+
+const security = securityClass.get();
+const error = errorClass.get();
+
+// ── Rate limiting middleware ────────────────────────────────────────
+// 100 requests per 15-minute window per IP
+export const apiRateLimit = security.requests(100, 15 * 60 * 1000);
+
+// 5 requests per minute (e.g. for a login endpoint)
+export const loginRateLimit = security.requests(5, 60 * 1000);
+
+// ── CSRF protection ─────────────────────────────────────────────────
+// security.forms() is a single middleware that handles BOTH:
+//   - Injecting a CSRF token into the response (GET requests)
+//   - Validating the token on state-changing requests (POST/PUT/DELETE)
+// Mount it once globally — no separate "require" middleware needed.
+export const csrfMiddleware = security.forms();
+
+// ── Encryption (AES-256-GCM) ────────────────────────────────────────
+export function encryptApiKey(plaintext: string): string {
+  return security.encrypt(plaintext);  // → opaque ciphertext string
+}
+
+export function decryptApiKey(ciphertext: string): string {
+  return security.decrypt(ciphertext);
+}
+
+// ── Input sanitization ──────────────────────────────────────────────
+// security.input() strips XSS payloads and control characters from free-form text.
+// For email/URL validation, use a dedicated validation library (e.g. zod, validator.js).
+export const submitRoute = error.asyncRoute(async (req, res) => {
+  const safeMessage = security.input(req.body.message);  // strip XSS
+  const safeHtml = security.html(req.body.bio);          // allow safe HTML tags only
+
+  res.json({ ok: true, sanitized: { message: safeMessage, bio: safeHtml } });
+});