@aria-framework/kit 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# @aria-framework/kit
+
+Aria App Framework — kit module. Five small, dependency-free server utilities
+(Node builtins only, plain CommonJS, no build step).
+
+```js
+const { safeReturnTo, escapeLike, fullName, splitName, fileSniff, trackingId }
+  = require('@aria-framework/kit');
+```
+
+## safeReturnTo — open-redirect guard
+
+Validates a post-login `returnTo` path. Only on-site paths survive (absolute,
+single leading slash, no scheme/host, no `//` protocol-relative trick);
+anything else collapses to the fallback.
+
+```js
+safeReturnTo(req.query.returnTo, { fallback: '/dashboard' });
+safeReturnTo(rt, { fallback: '/', denyPrefix: '/portal' }); // also keep users out of auth pages
+```
+
+## escapeLike — SQL LIKE escaping
+
+Escapes `%`, `_` and `\` so user input can sit inside a LIKE pattern. Pair
+with `ESCAPE '\'` in the query:
+
+```js
+db.prepare("... WHERE name LIKE ? ESCAPE '\\'").all(`%${escapeLike(q)}%`);
+```
+
+## fileSniff — magic-byte upload validation
+
+The client-declared Content-Type is attacker-controlled; this checks the
+file's actual leading bytes against the declared MIME's **container family**
+(docx/xlsx are both ZIP, doc/xls both OLE — exact subtypes can't be told apart
+by magic, so families are the honest granularity).
+
+```js
+if (!fileSniff.matches(file.path, file.mimetype)) reject(file);
+fileSniff.sniff(path); // → 'image/png' | 'zip' | 'ole' | 'isobmff' | 'text' | ... | null
+```
+
+Covers png/jpeg/gif/webp, pdf, text/csv, office (old + OOXML), heic/heif,
+mp4/mov/webm/avi/ogg, mp3/m4a/wav, zip/7z/rar/gzip.
+
+## trackingId — customer-facing reference codes
+
+`AB12-CD34-EF56` — Crockford base32 (no I, L, O, U: these codes get read
+aloud and retyped), `crypto.randomInt` for unbiased unguessable picks,
+60 bits of space.
+
+```js
+trackingId.generate();                       // random, no collision check
+trackingId.generateUnique((id) =>            // guaranteed unique per YOUR storage
+  db.prepare('SELECT 1 FROM tickets WHERE tracking_id = ?').get(id));
+```
+
+`generateUnique` is storage-agnostic — pass any `(id) => truthy-if-exists`
+check (SQL, ORM, HTTP, in-memory). Throws after `maxAttempts` (default 10).
+
+## fullName / splitName — person-name convention helpers
+
+For the first_name + last_name model where `display_name`/`name` is a
+**maintained composite** (never hand-written):
+
+```js
+fullName('Ann', 'Bee');          // 'Ann Bee'   (trims, drops blanks)
+splitName('Johan van der Merwe') // { first_name: 'Johan van der', last_name: 'Merwe' }
+```
+
+`splitName` splits on the **last** space (last word = surname). Compound
+surnames split imperfectly by design. If an app backfills a split in SQL,
+implement the same last-space rule and keep them in step. Also exported
+namespaced as `personName.{fullName,splitName}`.
+
+## Changelog
+
+- **0.1.0** — first release. Extracted from Support101 `lib/` (safeReturnTo,
+  likeEscape, fileSniff, trackingId, personName). One API change vs the app
+  originals: `trackingId.generateUnique` takes an `isTaken(id)` callback
+  instead of a better-sqlite3 handle + hardcoded tickets table.

package/fileSniff.js

@@ -0,0 +1,117 @@
+/**
+ * Magic-byte file-type validation for uploads.
+ *
+ * multer's `file.mimetype` is the client-declared Content-Type — attacker
+ * controlled. This module reads the actual leading bytes and checks they are
+ * consistent with the declared MIME's container family, so an HTML file
+ * labelled `image/png` is rejected. Office formats can't be distinguished from
+ * each other by magic alone (docx/xlsx are both ZIP; doc/xls are both OLE), so
+ * we validate the container family, not the exact subtype.
+ */
+
+const fs = require('fs');
+
+/** Sniff the container/type from the first bytes. Returns a coarse tag or null. */
+function sniff(filePath) {
+  let fd;
+  try {
+    fd = fs.openSync(filePath, 'r');
+    const buf = Buffer.alloc(16);
+    const n = fs.readSync(fd, buf, 0, 16, 0);
+    const b = buf.subarray(0, n);
+    const hex = b.toString('hex').toUpperCase();
+
+    if (hex.startsWith('89504E47')) return 'image/png';
+    if (hex.startsWith('FFD8FF')) return 'image/jpeg';
+    if (hex.startsWith('47494638')) return 'image/gif';
+    if (hex.startsWith('25504446')) return 'application/pdf';
+
+    // RIFF container — disambiguate by the form-type at bytes 8–12.
+    if (hex.startsWith('52494646') && n >= 12) {
+      const form = b.subarray(8, 12).toString('ascii');
+      if (form === 'WEBP') return 'image/webp';
+      if (form === 'WAVE') return 'riff-wave';
+      if (form === 'AVI ') return 'riff-avi';
+    }
+
+    // ISO-BMFF (MP4/MOV/M4A/HEIC): 'ftyp' box at bytes 4–8. We don't split the
+    // brand — validate the container family, like we do for zip-based formats.
+    if (n >= 8 && b.subarray(4, 8).toString('ascii') === 'ftyp') return 'isobmff';
+    // Matroska/WebM (EBML)
+    if (hex.startsWith('1A45DFA3')) return 'ebml';
+    // Ogg (audio/video)
+    if (hex.startsWith('4F676753')) return 'ogg';
+    // MP3: ID3 tag, or an MPEG audio frame sync (0xFFEx).
+    if (hex.startsWith('494433') || (n >= 2 && b[0] === 0xFF && (b[1] & 0xE0) === 0xE0)) return 'mp3';
+
+    // ZIP container (docx/xlsx and plain zip): PK\x03\x04 / PK\x05\x06 / PK\x07\x08
+    if (hex.startsWith('504B0304') || hex.startsWith('504B0506') || hex.startsWith('504B0708')) return 'zip';
+    // OLE compound file (legacy doc/xls)
+    if (hex.startsWith('D0CF11E0A1B11AE1')) return 'ole';
+    // Other archives
+    if (hex.startsWith('377ABCAF271C')) return '7z';
+    if (hex.startsWith('526172211A07')) return 'rar';   // 'Rar!\x1A\x07'
+    if (hex.startsWith('1F8B')) return 'gzip';
+    // No binary signature: treat as text only if there are no NUL bytes.
+    if (n > 0 && !b.includes(0)) return 'text';
+    return null;
+  } catch (_) {
+    return null;
+  } finally {
+    if (fd !== undefined) { try { fs.closeSync(fd); } catch (_) {} }
+  }
+}
+
+// Declared MIME → the sniffed tags that are acceptable for it.
+const FAMILY = {
+  'image/png': ['image/png'],
+  'image/jpeg': ['image/jpeg'],
+  'image/gif': ['image/gif'],
+  'image/webp': ['image/webp'],
+  'application/pdf': ['application/pdf'],
+  'text/plain': ['text'],
+  'text/csv': ['text'],
+  'application/msword': ['ole'],
+  'application/vnd.ms-excel': ['ole'],
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': ['zip'],
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': ['zip'],
+  // images (HEIC/HEIF are ISO-BMFF)
+  'image/heic': ['isobmff'],
+  'image/heif': ['isobmff'],
+  // video
+  'video/mp4': ['isobmff'],
+  'video/quicktime': ['isobmff'],
+  'video/webm': ['ebml'],
+  'video/x-msvideo': ['riff-avi'],
+  'video/ogg': ['ogg'],
+  // audio
+  'audio/mpeg': ['mp3'],
+  'audio/mp4': ['isobmff'],
+  'audio/x-m4a': ['isobmff'],
+  'audio/wav': ['riff-wave'],
+  'audio/x-wav': ['riff-wave'],
+  'audio/ogg': ['ogg'],
+  'audio/webm': ['ebml'],
+  // archives
+  'application/zip': ['zip'],
+  'application/x-zip-compressed': ['zip'],
+  'application/x-7z-compressed': ['7z'],
+  'application/x-rar-compressed': ['rar'],
+  'application/vnd.rar': ['rar'],
+  'application/gzip': ['gzip']
+};
+
+/**
+ * True if the file's actual content is consistent with the declared MIME.
+ * @param {string} filePath
+ * @param {string} declaredMime
+ * @returns {boolean}
+ */
+function matches(filePath, declaredMime) {
+  const allowed = FAMILY[declaredMime];
+  if (!allowed) return false;
+  const sniffed = sniff(filePath);
+  return !!sniffed && allowed.includes(sniffed);
+}
+
+module.exports = { sniff, matches };

package/index.js

@@ -0,0 +1,25 @@
+/**
+ * @aria-framework/kit — public API.
+ *
+ * Single-function modules are exported flat; multi-function modules keep a
+ * namespace (matching how call sites naturally read):
+ *
+ *   safeReturnTo(returnTo, {fallback, denyPrefix})  — open-redirect guard
+ *   escapeLike(s)                                   — SQL LIKE escaping
+ *   fullName(first, last) / splitName(full)         — person-name helpers
+ *   fileSniff.sniff(path) / fileSniff.matches(path, mime)
+ *   trackingId.generate() / trackingId.generateUnique(isTaken, maxAttempts)
+ */
+
+const { escapeLike } = require('./likeEscape');
+const { fullName, splitName } = require('./personName');
+
+module.exports = {
+  safeReturnTo: require('./safeReturnTo'),
+  escapeLike,
+  fullName,
+  splitName,
+  fileSniff: require('./fileSniff'),
+  trackingId: require('./trackingId'),
+  personName: { fullName, splitName }
+};

package/likeEscape.js

@@ -0,0 +1,13 @@
+/**
+ * Escape a user-supplied string for safe use inside a SQL LIKE pattern.
+ * Without this, a search for "100%" or "_" would match far more than intended
+ * (a full-table scan / wrong results). Pair with `ESCAPE '\'` in the query.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+function escapeLike(s) {
+  return String(s == null ? '' : s).replace(/[%_\\]/g, '\\$&');
+}
+
+module.exports = { escapeLike };

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@aria-framework/kit",
+  "version": "0.1.0",
+  "description": "Aria App Framework — kit module. Small dependency-free server utilities: open-redirect guard (safeReturnTo), SQL LIKE escaping, magic-byte upload validation (fileSniff), Crockford base32 tracking IDs, and person-name compose/split helpers.",
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "safeReturnTo.js",
+    "likeEscape.js",
+    "fileSniff.js",
+    "trackingId.js",
+    "personName.js"
+  ]
+}

package/personName.js

@@ -0,0 +1,32 @@
+/**
+ * Canonical person-name helpers — one source of truth for composing a full
+ * display name from first + last, and for splitting a full name back into the
+ * two parts. Use these everywhere a first_name/last_name pair meets a
+ * display_name/full-name field, so the composite convention can't drift.
+ *
+ * If an app backfills a split in SQL (one-time migration), implement the SAME
+ * last-space split there and keep it in step with splitName(). Separate
+ * runtime bundles (e.g. a React Native app) need their own copy — keep those
+ * in step too.
+ */
+'use strict';
+
+/** Compose a full/display name from first + last (trimmed; blank parts dropped). */
+function fullName(first, last) {
+  return [first, last].map(v => String(v || '').trim()).filter(Boolean).join(' ');
+}
+
+/**
+ * Split a full name on the LAST space: the last word is the surname, everything
+ * before it is the first name(s). No space → the whole value is the first name.
+ * Compound surnames split imperfectly by design ("Johan van der Merwe"
+ * → first "Johan van der" / last "Merwe").
+ */
+function splitName(full) {
+  const s = String(full || '').trim();
+  const i = s.lastIndexOf(' ');
+  if (i === -1) return { first_name: s, last_name: '' };
+  return { first_name: s.slice(0, i).trim(), last_name: s.slice(i + 1).trim() };
+}
+
+module.exports = { fullName, splitName };

package/safeReturnTo.js

@@ -0,0 +1,35 @@
+/**
+ * Validate a post-login returnTo path against open-redirect abuse.
+ *
+ * A safe path is absolute, single-slash, and on-site (no scheme/host, no `//`
+ * protocol-relative prefix). Anything else collapses to `fallback`. Keep the
+ * parsing/normalisation in ONE place — a hardening fix here covers every login
+ * flow. Typical usage divergence is just data:
+ *   - staff login:   safeReturnTo(rt, { fallback: '/dashboard' })
+ *   - portal login:  safeReturnTo(rt, { fallback: '/', denyPrefix: '/portal' })
+ *
+ * @param {string} returnTo
+ * @param {{fallback?: string, denyPrefix?: string}} [opts]
+ * @returns {string} a safe on-site path, or the fallback
+ */
+
+// Sentinel base host for relative-URL parsing; any input that resolves to a
+// DIFFERENT host smuggled in its own authority and is rejected.
+const SENTINEL = '_aria_kit_local';
+
+function safeReturnTo(returnTo, opts = {}) {
+  const fallback = opts.fallback || '/';
+  if (typeof returnTo !== 'string' || !returnTo) return fallback;
+  try {
+    const url = new URL(returnTo, `http://${SENTINEL}`);
+    if (url.host !== SENTINEL) return fallback;
+    if (!url.pathname.startsWith('/') || url.pathname.startsWith('//')) return fallback;
+    // Never bounce a freshly-logged-in user back into the auth pages.
+    if (opts.denyPrefix && url.pathname.startsWith(opts.denyPrefix)) return fallback;
+    return url.pathname + url.search;
+  } catch {
+    return fallback;
+  }
+}
+
+module.exports = safeReturnTo;

package/trackingId.js

@@ -0,0 +1,52 @@
+/**
+ * Public tracking-ID generator (tickets, orders, quotes — any customer-facing
+ * reference).
+ *
+ * Format: three groups of 4 Crockford base32 characters, e.g. "AB12-CD34-EF56".
+ * Crockford base32 omits I, L, O, U to avoid visual/voice ambiguity — these
+ * IDs get read aloud and retyped by customers. crypto.randomInt gives an
+ * unbiased pick from the 32-char alphabet.
+ *
+ * 12 chars × 5 bits = 60 bits of space, so collisions are astronomically rare;
+ * generateUnique still checks on insert to make uniqueness a guarantee, not a
+ * probability.
+ */
+
+const crypto = require('crypto');
+
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'; // Crockford base32 (no I L O U)
+
+function group() {
+  let s = '';
+  for (let i = 0; i < 4; i++) s += ALPHABET[crypto.randomInt(ALPHABET.length)];
+  return s;
+}
+
+/** Generate a random tracking ID (no collision check). */
+function generate() {
+  return `${group()}-${group()}-${group()}`;
+}
+
+/**
+ * Generate a tracking ID guaranteed unique per the caller's own storage.
+ * Storage-agnostic: the caller supplies the existence check.
+ *
+ *   trackingId.generateUnique((id) =>
+ *     db.prepare('SELECT 1 FROM tickets WHERE tracking_id = ?').get(id));
+ *
+ * @param {(id: string) => any} isTaken - truthy if the ID already exists
+ * @param {number} [maxAttempts=10]
+ * @returns {string}
+ */
+function generateUnique(isTaken, maxAttempts = 10) {
+  if (typeof isTaken !== 'function') {
+    throw new Error('generateUnique(isTaken): isTaken must be a function (id) => truthy-if-exists');
+  }
+  for (let i = 0; i < maxAttempts; i++) {
+    const id = generate();
+    if (!isTaken(id)) return id;
+  }
+  throw new Error('Could not generate a unique tracking ID');
+}
+
+module.exports = { generate, generateUnique };