@harshankur/viewcounter 3.0.0

package/utils/errorUtils.js

@@ -0,0 +1,157 @@
+/**
+ * Centralized error and warning handling.
+ *
+ * Per agent-instructions CODE_STANDARDS.md §3, application code never calls
+ * `new Error("...")` or `console.warn/error` directly. Every failure is
+ * identified by an enum member, its message text lives in exactly one table
+ * here, and callers branch on `err.code` rather than parsing message strings.
+ *
+ * `getError` builds and reports but deliberately does NOT throw — the `throw`
+ * stays visible at the call site and under the caller's control.
+ */
+
+const logger = require('./logger');
+
+/** Fatal conditions. Every thrown error in this project is one of these. */
+const ErrorType = {
+    DATABASE_NOT_INITIALIZED: 'DATABASE_NOT_INITIALIZED',
+    DATABASE_CONNECTION_FAILED: 'DATABASE_CONNECTION_FAILED',
+    DATABASE_QUERY_FAILED: 'DATABASE_QUERY_FAILED',
+    CONFIG_INSECURE_DEFAULT: 'CONFIG_INSECURE_DEFAULT',
+    CONFIG_MISSING_REQUIRED: 'CONFIG_MISSING_REQUIRED',
+    CONFIG_INVALID_VALUE: 'CONFIG_INVALID_VALUE',
+    INVALID_APP_ID: 'INVALID_APP_ID',
+    SECRET_PERSIST_FAILED: 'SECRET_PERSIST_FAILED',
+    SECRET_UNAVAILABLE: 'SECRET_UNAVAILABLE',
+};
+
+/** Non-fatal conditions worth surfacing but not worth stopping for. */
+const WarningType = {
+    CONFIG_FILE_UNREADABLE: 'CONFIG_FILE_UNREADABLE',
+    CONFIG_FIELD_MISSING: 'CONFIG_FIELD_MISSING',
+    PROXY_TRUST_PERMISSIVE: 'PROXY_TRUST_PERMISSIVE',
+    SECRET_GENERATED: 'SECRET_GENERATED',
+    READ_API_UNPROTECTED: 'READ_API_UNPROTECTED',
+    API_KEY_TOO_SHORT: 'API_KEY_TOO_SHORT',
+    API_KEY_EMPTY_SCOPE: 'API_KEY_EMPTY_SCOPE',
+    APP_ALREADY_REGISTERED: 'APP_ALREADY_REGISTERED',
+    FIELD_TRUNCATED: 'FIELD_TRUNCATED',
+};
+
+/**
+ * Message text, in exactly one place. A plain string for a fixed message, a
+ * function where dynamic detail has to be interpolated.
+ * @type {Record<string, string | ((info: any) => string)>}
+ */
+const ERROR_MESSAGES = {
+    [ErrorType.DATABASE_NOT_INITIALIZED]: 'Database not initialized',
+    [ErrorType.DATABASE_CONNECTION_FAILED]: (info) =>
+        `Failed to connect to database '${info?.database}' at ${info?.host}:${info?.port}`,
+    [ErrorType.DATABASE_QUERY_FAILED]: (info) => `Database query failed: ${info?.operation}`,
+    [ErrorType.CONFIG_INSECURE_DEFAULT]: (info) =>
+        `Refusing to start: ${info?.field} is still at its insecure default. ` +
+        'Set it explicitly via dbInfo.json, allowed.json, or the environment.',
+    [ErrorType.CONFIG_MISSING_REQUIRED]: (info) =>
+        `Refusing to start: required configuration '${info?.field}' is missing or empty.`,
+    [ErrorType.CONFIG_INVALID_VALUE]: (info) =>
+        `Invalid configuration for '${info?.field}': ${info?.reason}`,
+    [ErrorType.INVALID_APP_ID]: (info) =>
+        `Invalid appId '${info?.appId}'. Must be 1-64 characters of letters, digits, ` +
+        'underscore, or hyphen, and must not start with an underscore.',
+    [ErrorType.SECRET_PERSIST_FAILED]: (info) =>
+        `Could not persist the visitor-hash secret to ${info?.path}. ` +
+        'Without a stable secret, visitor hashes are not reversible-resistant across restarts.',
+    [ErrorType.SECRET_UNAVAILABLE]: 'Visitor-hash secret has not been initialized',
+};
+
+/** @type {Record<string, string | ((info: any) => string)>} */
+const WARNING_MESSAGES = {
+    [WarningType.CONFIG_FILE_UNREADABLE]: (info) =>
+        `Could not parse ${info?.file}; falling back to environment variables and defaults.`,
+    [WarningType.CONFIG_FIELD_MISSING]: (info) =>
+        `Config field '${info?.field}' absent from ${info?.file}; using ${info?.source}.`,
+    [WarningType.PROXY_TRUST_PERMISSIVE]: (info) =>
+        `TRUST_PROXY is set to '${info?.value}'. Client-supplied forwarding headers will be ` +
+        'trusted, which lets a caller forge their own IP and bypass rate limiting. ' +
+        'Set it to the number of proxy hops or an explicit CIDR list.',
+    [WarningType.SECRET_GENERATED]: (info) =>
+        `Generated a new visitor-hash secret at ${info?.path}. Existing visitor hashes ` +
+        'are now unlinkable from new ones, which is the intended privacy behaviour.',
+    [WarningType.READ_API_UNPROTECTED]: 'No read API keys configured; analytics read endpoints are disabled.',
+    [WarningType.API_KEY_TOO_SHORT]: (info) =>
+        `Ignoring an API key of length ${info?.length}; keys must be at least 32 characters.`,
+    [WarningType.API_KEY_EMPTY_SCOPE]: (info) =>
+        `Ignoring an API key with an unusable scope (${info?.scope}). Use "*" or a non-empty array of app IDs.`,
+    [WarningType.APP_ALREADY_REGISTERED]: (info) =>
+        `App '${info?.appId}' is already registered; leaving it as-is.`,
+    [WarningType.FIELD_TRUNCATED]: (info) =>
+        `Field '${info?.field}' exceeded ${info?.max} characters and was truncated before storage.`,
+};
+
+/**
+ * Resolve a message from its table, whether it is a literal or a builder.
+ * @returns {string}
+ */
+function resolveMessage(table, type, info) {
+    const entry = table[type];
+    if (entry === undefined) return `Unknown issue: ${type}`;
+    return typeof entry === 'function' ? entry(info) : entry;
+}
+
+/**
+ * The one place an issue is reported. Routes through the logger so the project
+ * has a single console sink rather than two competing ones.
+ * @param {{type: 'error'|'warning', code: string, message: string, details?: unknown}} issue
+ */
+function report(issue) {
+    const context = issue.details && typeof issue.details === 'object' ? issue.details : {};
+    const line = `${issue.code}: ${issue.message}`;
+    if (issue.type === 'error') {
+        logger.error(line, context);
+    } else {
+        logger.warn(line, context);
+    }
+}
+
+/**
+ * Build, report, and return an Error. The caller throws it.
+ *
+ * Cancellation carve-out (CODE_STANDARDS.md §3): an AbortError carries an
+ * identity the runtime depends on, so it is passed straight back rather than
+ * being wrapped and stripped of its `name`.
+ *
+ * @param {string} type - an ErrorType member
+ * @param {object} [info] - interpolation detail, also attached as `details`
+ * @returns {Error}
+ */
+function getError(type, info) {
+    if (info instanceof Error && info.name === 'AbortError') return info;
+
+    const message = resolveMessage(ERROR_MESSAGES, type, info);
+    const issue = { type: 'error', code: type, message, details: info };
+    report(issue);
+
+    const err = new Error(message);
+    err.code = type;
+    err.details = info;
+    return err;
+}
+
+/**
+ * Report a non-fatal issue. Never throws, returns nothing.
+ * @param {string} type - a WarningType member
+ * @param {object} [info]
+ */
+function logWarning(type, info) {
+    const message = resolveMessage(WARNING_MESSAGES, type, info);
+    report({ type: 'warning', code: type, message, details: info });
+}
+
+module.exports = {
+    ErrorType,
+    WarningType,
+    ERROR_MESSAGES,
+    WARNING_MESSAGES,
+    getError,
+    logWarning,
+};

package/utils/ipUtils.js

@@ -0,0 +1,63 @@
+/**
+ * Client IP derivation and validation.
+ *
+ * Split out of middleware/validation.js because it is used by the route layer,
+ * the privacy layer, and the middleware layer (CODE_STANDARDS.md §2).
+ */
+
+const net = require('net');
+
+/**
+ * Validate an IP address.
+ *
+ * Uses Node's built-in parser rather than a hand-written regex. The previous
+ * IPv4 pattern (`^(\d{1,3}\.){3}\d{1,3}$`) had no octet range check, so
+ * `999.999.999.999` validated and was stored as a masked "address" that never
+ * existed. `net.isIP` range-checks properly and cannot backtrack.
+ *
+ * @param {string} ip
+ * @returns {boolean}
+ */
+function isValidIP(ip) {
+    if (!ip || typeof ip !== 'string') return false;
+    return net.isIP(ip) !== 0;
+}
+
+/**
+ * Resolve the client's IP for a request.
+ *
+ * Deliberately reads ONLY `req.ip`, which Express derives according to the
+ * app's `trust proxy` setting. The previous implementation read `x-real-ip`
+ * and `x-forwarded-for` straight off the request, so any caller could name
+ * their own address — forging geolocation, inflating unique-visitor counts,
+ * and rotating the rate-limiter key to bypass it entirely.
+ *
+ * If a reverse proxy in front of this service sets only `X-Real-IP`, configure
+ * it to also set `X-Forwarded-For`; that is the header Express understands.
+ *
+ * @param {import('express').Request} req
+ * @returns {string|undefined}
+ */
+function getClientIp(req) {
+    return req.ip;
+}
+
+/**
+ * Normalize an IPv4-mapped IPv6 address to its IPv4 form.
+ * Express reports `::ffff:1.2.3.4` on a dual-stack socket; geo lookup and
+ * masking both want the plain IPv4.
+ *
+ * @param {string} ip
+ * @returns {string}
+ */
+function normalizeIp(ip) {
+    if (typeof ip !== 'string') return ip;
+    const mapped = ip.match(/^::ffff:((?:\d{1,3}\.){3}\d{1,3})$/i);
+    return mapped && net.isIPv4(mapped[1]) ? mapped[1] : ip;
+}
+
+module.exports = {
+    isValidIP,
+    getClientIp,
+    normalizeIp,
+};

package/utils/logger.js

@@ -0,0 +1,138 @@
+/**
+ * Structured logger.
+ *
+ * Per agent-instructions LOGGING.md this is the ONLY module in the project
+ * permitted to write to the console. Application code calls debug/info/warn/
+ * error/audit; utils/errorUtils.js routes error and warning reporting here so
+ * there is exactly one sink, not two.
+ */
+
+const { APP_SLUG } = require('../constants');
+
+/** LOGGING.md §1. */
+const LogLevel = {
+    DEBUG: 'debug',
+    INFO: 'info',
+    WARN: 'warn',
+    ERROR: 'error',
+    /** Emits nothing except the audit channel. Used by the test suite. */
+    SILENT: 'silent',
+};
+
+const LOG_LEVEL_PRIORITY = {
+    [LogLevel.DEBUG]: 10,
+    [LogLevel.INFO]: 20,
+    [LogLevel.WARN]: 30,
+    [LogLevel.ERROR]: 40,
+    [LogLevel.SILENT]: Number.MAX_SAFE_INTEGER,
+};
+
+/** Sensitive keys redacted from any diagnostic dump (LOGGING.md §5). */
+const REDACTED_KEYS = new Set(['password', 'secret', 'apikey', 'apikeys', 'token', 'authorization']);
+
+const REDACTED_PLACEHOLDER = '[SET]';
+const ABSENT_PLACEHOLDER = '[NOT SET]';
+
+let threshold = LogLevel.INFO;
+
+/**
+ * The single underlying write. Swappable so tests can capture output without
+ * monkey-patching the console.
+ */
+let sink = (line) => process.stdout.write(`${line}\n`);
+
+/**
+ * Configure the logger. Called once from the server bootstrap after config is
+ * resolved, so this module never reads process.env itself (CONFIG.md §0).
+ * @param {{ level?: string, writer?: (line: string) => void }} options
+ */
+function configure({ level, writer } = {}) {
+    if (level && Object.prototype.hasOwnProperty.call(LOG_LEVEL_PRIORITY, level)) {
+        threshold = level;
+    }
+    if (typeof writer === 'function') {
+        sink = writer;
+    }
+}
+
+/** @returns {boolean} whether a message at this level would be emitted. */
+function isEnabled(level) {
+    return LOG_LEVEL_PRIORITY[level] >= LOG_LEVEL_PRIORITY[threshold];
+}
+
+/**
+ * Render the correlation context as fixed-position bracket fields so the
+ * stream stays greppable (LOGGING.md §2). Absent fields render as `-` rather
+ * than being omitted, so column positions never shift.
+ */
+function formatContext(context = {}) {
+    const ip = context.ip || '-';
+    const requestId = context.requestId || '-';
+    return `[${ip}] [${requestId}]`;
+}
+
+/**
+ * LOGGING.md §4: a failing sink degrades logging, it never takes down the
+ * request that triggered it.
+ */
+function write(level, message, context) {
+    try {
+        const timestamp = new Date().toISOString();
+        const line = `[${timestamp}] [${level.toUpperCase()}] ${formatContext(context)} ${message}`;
+        sink(line);
+    } catch {
+        // Intentionally swallowed. There is nowhere left to report to.
+    }
+}
+
+function log(level, message, context) {
+    if (!isEnabled(level)) return;
+    write(level, message, context);
+}
+
+const debug = (message, context) => log(LogLevel.DEBUG, message, context);
+const info = (message, context) => log(LogLevel.INFO, message, context);
+const warn = (message, context) => log(LogLevel.WARN, message, context);
+const error = (message, context) => log(LogLevel.ERROR, message, context);
+
+/**
+ * Audit channel for state-mutating actions (LOGGING.md §3).
+ *
+ * Deliberately bypasses the level threshold: turning operational verbosity
+ * down must never silently discard the record of who changed what. Tagged
+ * distinctly so it can be split to its own destination downstream.
+ */
+function audit(action, context = {}) {
+    const actor = context.actor || context.appId || 'anonymous';
+    write(`audit:${APP_SLUG}`, `action=${action} actor=${actor}`, context);
+}
+
+/**
+ * Redact sensitive values for diagnostics output (LOGGING.md §5).
+ * Allowlist semantics: anything whose key matches a sensitive name is replaced
+ * with a presence marker, never its value.
+ */
+function redact(record = {}) {
+    const safe = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (REDACTED_KEYS.has(key.toLowerCase())) {
+            safe[key] = value ? REDACTED_PLACEHOLDER : ABSENT_PLACEHOLDER;
+        } else {
+            safe[key] = value;
+        }
+    }
+    return safe;
+}
+
+module.exports = {
+    LogLevel,
+    LOG_LEVEL_PRIORITY,
+    configure,
+    isEnabled,
+    debug,
+    info,
+    warn,
+    error,
+    audit,
+    redact,
+};

package/utils/privacyUtils.js

@@ -0,0 +1,107 @@
+const crypto = require('crypto');
+
+const { SERVER } = require('../constants');
+const { getError, ErrorType } = require('./errorUtils');
+
+/** Rotation never runs slower than this, even if dedup is disabled. */
+const MIN_ROTATION_HOURS = 1;
+
+const MS_PER_HOUR = 60 * 60 * 1000;
+
+class PrivacyUtils {
+    /**
+     * Masks the IP address to be non-identifiable.
+     * IPv4: Masks the last octet (e.g. 1.2.3.4 -> 1.2.3.0)
+     * IPv6: Masks the last 64 bits (interface identifier)
+     * @param {string} ip The raw IP address
+     * @returns {string} The masked IP
+     */
+    static maskIP(ip) {
+        if (!ip) return '0.0.0.0';
+
+        // Handle IPv4-mapped IPv6 (::ffff:127.0.0.1)
+        if (ip.startsWith('::ffff:')) {
+            const ipv4 = ip.split(':').pop();
+            return `::ffff:${this.maskIPv4(ipv4)}`;
+        }
+
+        if (ip.includes(':')) {
+            return this.maskIPv6(ip);
+        }
+
+        return this.maskIPv4(ip);
+    }
+
+    static maskIPv4(ip) {
+        const parts = ip.split('.');
+        if (parts.length === 4) {
+            return `${parts[0]}.${parts[1]}.${parts[2]}.0`;
+        }
+        return ip;
+    }
+
+    static maskIPv6(ip) {
+        const parts = ip.split(':');
+        // Mask the last 4 groups (64 bits)
+        if (parts.length >= 4) {
+            return parts.slice(0, 4).join(':') + ':0:0:0:0';
+        }
+        return ip;
+    }
+
+    /**
+     * Identifier for the current rotation window.
+     *
+     * Including this in the hash input means a visitor's hash changes on every
+     * window boundary, so two records from different windows cannot be linked
+     * back to the same person even by whoever holds the secret.
+     *
+     * @param {number} rotationHours
+     * @param {number} [now] epoch millis, injectable for tests
+     * @returns {number}
+     */
+    static currentWindowId(rotationHours, now = Date.now()) {
+        const hours = Math.max(Number(rotationHours) || 0, MIN_ROTATION_HOURS);
+        return Math.floor(now / (hours * MS_PER_HOUR));
+    }
+
+    /**
+     * Generate the transient visitor identifier.
+     *
+     * This is a keyed HMAC, not a bare digest. Every non-secret input is
+     * public or guessable — the date is known, user agents come from a small
+     * population, and IPv4 is only 2^32 — so an unkeyed SHA-256 of them is
+     * reversible by exhaustive search in about an hour on one CPU core. The
+     * server secret is what makes that search infeasible; the window id is
+     * what stops hashes being linkable over time.
+     *
+     * @param {string} ip Raw IP address
+     * @param {string} userAgent Raw User-Agent string
+     * @param {string} secret Server secret from utils/secretStore.js
+     * @param {number} [rotationHours] Window length, defaults to the unique-visitor window
+     * @param {number} [now] epoch millis, injectable for tests
+     * @returns {string} HMAC-SHA-256 hex digest
+     * @throws {Error} ErrorType.SECRET_UNAVAILABLE when no secret is supplied
+     */
+    static generateVisitorHash(
+        ip,
+        userAgent,
+        secret,
+        rotationHours = SERVER.DEFAULT_UNIQUE_VISITOR_WINDOW_HOURS,
+        now = Date.now(),
+    ) {
+        if (!secret) {
+            // Failing closed is deliberate: silently hashing without the key
+            // would produce reversible identifiers that look indistinguishable
+            // from safe ones.
+            throw getError(ErrorType.SECRET_UNAVAILABLE);
+        }
+
+        const windowId = this.currentWindowId(rotationHours, now);
+        const input = `${ip}|${userAgent}|${windowId}`;
+
+        return crypto.createHmac('sha256', secret).update(input).digest('hex');
+    }
+}
+
+module.exports = PrivacyUtils;

package/utils/referrerParser.js

@@ -0,0 +1,137 @@
+const URL = require('url-parse');
+
+const { FIELD_MAX_LENGTH, QUERY_LIMITS, SOURCE_TYPE } = require('../constants');
+const { truncate } = require('./stringUtils');
+
+/**
+ * Parse referrer URLs to extract domain and source type
+ */
+class ReferrerParser {
+    /**
+     * Parse referrer URL
+     * @param {string} referrer - Referrer URL from request headers
+     * @returns {object} Parsed referrer data
+     */
+    static parse(referrer) {
+        if (!referrer || referrer === '') {
+            return {
+                referrer: null,
+                referrerDomain: null,
+                sourceType: SOURCE_TYPE.DIRECT
+            };
+        }
+
+        try {
+            const url = new URL(referrer);
+            const domain = url.hostname || null;
+            const sourceType = this.getSourceType(domain, referrer);
+
+            return {
+                referrer: truncate(referrer, FIELD_MAX_LENGTH.REFERRER),
+                referrerDomain: truncate(domain, FIELD_MAX_LENGTH.REFERRER_DOMAIN),
+                sourceType
+            };
+        } catch (error) {
+            return {
+                referrer: truncate(referrer, FIELD_MAX_LENGTH.REFERRER),
+                referrerDomain: null,
+                sourceType: SOURCE_TYPE.UNKNOWN
+            };
+        }
+    }
+
+    /**
+     * Determine source type based on referrer domain
+     * @param {string} domain - Referrer domain
+     * @param {string} fullUrl - Full referrer URL
+     * @returns {string} Source type
+     */
+    static getSourceType(domain, fullUrl) {
+        if (!domain) return SOURCE_TYPE.DIRECT;
+
+        const lowerDomain = domain.toLowerCase();
+
+        // Search engines
+        if (this.isSearchEngine(lowerDomain)) return SOURCE_TYPE.SEARCH;
+
+        // Social media
+        if (this.isSocialMedia(lowerDomain)) return SOURCE_TYPE.SOCIAL;
+
+        // Email clients
+        if (this.isEmail(lowerDomain)) return SOURCE_TYPE.EMAIL;
+
+        // Ads/campaigns (check for utm parameters)
+        if (fullUrl.includes('utm_source') || fullUrl.includes('utm_medium')) {
+            return SOURCE_TYPE.CAMPAIGN;
+        }
+
+        // Everything else is referral
+        return SOURCE_TYPE.REFERRAL;
+    }
+
+    /**
+     * Check if domain is a search engine
+     */
+    static isSearchEngine(domain) {
+        const searchEngines = [
+            'google', 'bing', 'yahoo', 'duckduckgo', 'baidu',
+            'yandex', 'ask', 'aol', 'ecosia', 'qwant'
+        ];
+        return searchEngines.some(engine => domain.includes(engine));
+    }
+
+    /**
+     * Check if domain is social media
+     */
+    static isSocialMedia(domain) {
+        const socialMedia = [
+            'facebook', 'twitter', 'x.com', 'instagram', 'linkedin',
+            'reddit', 'pinterest', 'tiktok', 'youtube', 'snapchat',
+            'whatsapp', 'telegram', 'discord', 'tumblr', 'vk.com',
+            'weibo', 'line.me', 'mastodon'
+        ];
+        return socialMedia.some(social => domain.includes(social));
+    }
+
+    /**
+     * Check if domain is email client
+     */
+    static isEmail(domain) {
+        const emailClients = [
+            'mail.google', 'outlook', 'yahoo.com/mail',
+            'mail.yahoo', 'protonmail', 'mail.aol'
+        ];
+        return emailClients.some(email => domain.includes(email));
+    }
+
+    /**
+     * Get top referrers summary
+     * @param {Array} referrers - Array of referrer objects from DB
+     * @returns {object} Summarized referrer stats
+     */
+    static summarizeReferrers(referrers) {
+        const bySource = {};
+        const byDomain = {};
+
+        referrers.forEach(ref => {
+            const sourceType = ref.sourceType || SOURCE_TYPE.UNKNOWN;
+            bySource[sourceType] = (bySource[sourceType] || 0) + 1;
+
+            if (ref.referrerDomain) {
+                byDomain[ref.referrerDomain] = (byDomain[ref.referrerDomain] || 0) + 1;
+            }
+        });
+
+        return {
+            bySource: Object.entries(bySource)
+                .map(([source, count]) => ({ source, count }))
+                .sort((a, b) => b.count - a.count),
+            byDomain: Object.entries(byDomain)
+                .map(([domain, count]) => ({ domain, count }))
+                .sort((a, b) => b.count - a.count)
+                .slice(0, QUERY_LIMITS.LIST_LIMIT_DEFAULT)
+        };
+    }
+}
+
+module.exports = ReferrerParser;

package/utils/secretStore.js

@@ -0,0 +1,57 @@
+/**
+ * Persisted server secret for visitor hashing.
+ *
+ * agent-instructions SECURITY.md §1: never fall back to a weak, guessable
+ * default for a security-relevant value — generate one cryptographically and
+ * persist it. This module is that generator.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const { PRIVACY } = require('../constants');
+const { getError, logWarning, ErrorType, WarningType } = require('./errorUtils');
+
+/** Matches a hex string of exactly the expected entropy. */
+const SECRET_PATTERN = new RegExp(`^[0-9a-f]{${PRIVACY.SECRET_BYTES * 2}}$`);
+
+/**
+ * Load the visitor-hash secret, generating and persisting it on first run.
+ *
+ * The file is written with mode 0600 (owner read/write only): this secret is
+ * the sole reason a stored visitor hash cannot be brute-forced back to the raw
+ * IP that produced it, so it is as sensitive as a database password.
+ *
+ * @param {string} filePath - absolute path to the secret file
+ * @returns {string} hex-encoded secret
+ * @throws {Error} ErrorType.SECRET_PERSIST_FAILED if it cannot be written
+ */
+function loadOrCreate(filePath) {
+    if (fs.existsSync(filePath)) {
+        const existing = fs.readFileSync(filePath, 'utf8').trim();
+        if (SECRET_PATTERN.test(existing)) {
+            return existing;
+        }
+        // A malformed file is treated as absent and replaced. Keeping a short
+        // or corrupted secret would silently weaken every hash derived from it.
+        logWarning(WarningType.CONFIG_FILE_UNREADABLE, { file: filePath });
+    }
+
+    const secret = crypto.randomBytes(PRIVACY.SECRET_BYTES).toString('hex');
+
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, `${secret}\n`, { mode: PRIVACY.SECRET_FILE_MODE });
+        // writeFileSync only applies `mode` when creating the file, so an
+        // existing file with looser permissions keeps them. Force it.
+        fs.chmodSync(filePath, PRIVACY.SECRET_FILE_MODE);
+    } catch (cause) {
+        throw getError(ErrorType.SECRET_PERSIST_FAILED, { path: filePath, cause: cause.message });
+    }
+
+    logWarning(WarningType.SECRET_GENERATED, { path: filePath });
+    return secret;
+}
+
+module.exports = { loadOrCreate, SECRET_PATTERN };

package/utils/stringUtils.js

@@ -0,0 +1,36 @@
+/**
+ * String helpers shared by the persistence and parsing layers.
+ */
+
+/**
+ * Truncate a value to a maximum length before it reaches a fixed-width column.
+ *
+ * Defence in depth behind boundary validation: validation rejects over-length
+ * input at the edge, but derived values (a browser version parsed out of a
+ * hostile User-Agent, for example) are produced internally and never pass
+ * through a validator. Under MySQL strict mode an over-long value is error
+ * 1406 and a 500; under non-strict mode it is a silent truncation.
+ *
+ * @param {unknown} value
+ * @param {number} max
+ * @returns {string|null} null for absent input, so callers can bind it directly
+ */
+function truncate(value, max) {
+    if (value === undefined || value === null || value === '') return null;
+    const str = String(value);
+    return str.length > max ? str.slice(0, max) : str;
+}
+
+/**
+ * Byte length of a value once serialized as JSON.
+ * Used to bound `eventData` before it is persisted.
+ *
+ * @param {unknown} value
+ * @returns {number}
+ */
+function jsonByteLength(value) {
+    if (value === undefined || value === null) return 0;
+    return Buffer.byteLength(JSON.stringify(value), 'utf8');
+}
+
+module.exports = { truncate, jsonByteLength };