blogwright-analytics 0.3.3

package/dist/transform/map-record.js

@@ -0,0 +1,275 @@
+/**
+ * `mapRecord`: one CloudFront standard-logging (v2) record in, one `page_views`
+ * row out - or a droppable result naming the column that could not be filled
+ * and the CloudFront field behind it. This is all five steps of
+ * [§Record transformation](../../../../.specs/changes/merged/2026-07-26-analytics_plugin.md):
+ * rename each selected field to its column, derive `event_time` and the `day`
+ * partition from `timestamp(ms)`, replace the viewer IP with `visitor_key`,
+ * set `is_bot` from the user agent, and drop what the schema cannot accept.
+ *
+ * The viewer IP is an *input* here and never a value. It reaches `visitorKey`
+ * and nothing else: it has no `FIELD_TO_COLUMN` entry to be renamed through,
+ * and `map-record.test.ts` searches every value of every produced row for it.
+ * That search is the standing check that no later field addition puts a raw
+ * address in the warehouse.
+ *
+ * The salt secret is a parameter for the same reason the day is read off the
+ * record: this function has no clock and reads no secret. The caller supplies
+ * the long-lived stored secret - the transform reads it once at cold start, a
+ * backfill reads the same one - and the day's salt is derived here rather than
+ * by the caller, because the day comes from the record's own timestamp. A
+ * batch can straddle midnight, so one salt chosen for a whole batch would be
+ * the wrong day's for the records on the other side of it.
+ *
+ * Why the drop path exists at all: Firehose matches incoming JSON keys to
+ * Iceberg column names **exactly**, and a record it cannot match goes to the
+ * S3 error bucket with no error anywhere an operator will see it - the symptom
+ * is an empty dashboard. So this module never emits a key that is not a column
+ * and never emits a value whose JavaScript type is not the one the column
+ * stores. Where it cannot honour that, it returns the droppable result and the
+ * envelope (task 42) reports `ProcessingFailed` for that one record, which
+ * routes it to the error prefix without failing the batch.
+ *
+ * Every column and field name comes from `schema.ts`: the row is built by
+ * iterating `FIELD_TO_COLUMN`, the required set and the numeric set are
+ * derived from `PAGE_VIEWS_COLUMNS`, and the only names spelled here are the
+ * four derived columns and the one column the two of them read back
+ * (`user_agent`), each checked against `PageViewColumnName` so a typo is a
+ * compile error rather than a column Firehose silently drops.
+ *
+ * Three input decisions the spec left open, settled here:
+ *
+ * - **`-` and the empty string mean absent.** CloudFront writes `-` for a
+ *   field the request had nothing to say for (no referrer, no query string).
+ *   Writing that through would fill `referrer` with a wall of `-`; treating it
+ *   as absent leaves the column null, which is what it means. For a *required*
+ *   column it is a drop, not a null.
+ * - **A number where a string column is expected is rendered, not rejected.**
+ *   `asn` is a string column that a JSON encoder may well emit unquoted;
+ *   `String(64512)` is the same value in the type the column stores. Anything
+ *   that is not a string or a number - an object, an array, a boolean - is a
+ *   drop, because there is no rendering of it that is not a guess.
+ * - **A numeric column that does not parse is a drop, never a coerced value.**
+ *   `Number('abc')` is `NaN` and `Number('')` is `0`; writing either would put
+ *   a wrong number in the table, which is worse than losing the record.
+ *
+ * Nullability governs the *absent* case only. A value that is present but
+ * unusable drops the record whether or not the column is nullable: leaving a
+ * nullable column empty asserts the request had nothing to say for it, which
+ * is a different - and false - fact about that request.
+ *
+ * Pure: no clock (`event_time` comes from the record's own `timestamp(ms)`, in
+ * UTC), no secret read, no vendor SDK, no `fetch`. The one `node:` builtin
+ * this directory uses is `node:crypto`, reached through `visitor-key.ts` and
+ * only for the digests - the same import `packages/core/src/aws/s3.ts` makes.
+ * The record arrives already parsed and is trusted to be an object - JSON
+ * parsing and its failures are the handler's boundary, not this function's.
+ */
+import { FIELD_TO_COLUMN, PAGE_VIEWS_COLUMNS, TIMESTAMP_MS_FIELD, VIEWER_IP_FIELD, } from '../schema.js';
+import { isBotUserAgent } from './bots.js';
+import { dailySalt, visitorKey } from './visitor-key.js';
+/** CloudFront's marker for a field the request had nothing to say for. */
+const CLOUDFRONT_EMPTY_VALUE = '-';
+/** The `YYYY-MM-DD` prefix an ISO-8601 instant opens with, in characters. */
+const ISO_DATE_LENGTH = 10;
+/**
+ * An ISO-8601 instant with a four-digit year, as `toISOString` renders every
+ * year from 0000 to 9999. Outside that range it switches to an expanded year
+ * (`+058632-08-17T19:50:00.000Z`), whose first ten characters are not a date
+ * but would still slice cleanly into `day`. This is the check that stops that.
+ *
+ * Which wrong units it actually catches, taking 1788099825 as the instant:
+ *
+ * - **Microseconds** (`1788099825000000`) land in the year 58632. A `Date`
+ *   holds it, `toISOString` renders it with an expanded year, and this regex
+ *   rejects it. Dropped.
+ * - **Nanoseconds** (`1788099825000000000`) exceed the 8.64e15 ms either side
+ *   of the epoch a `Date` can represent at all, so `eventTimeFrom`'s
+ *   representability guard rejects it before this regex sees it. Dropped.
+ * - **Seconds** (`1788099825`) are *not* detected, and seconds are the
+ *   likeliest wrong unit anyone would actually supply. Read as milliseconds
+ *   the value is an ordinary instant - `1970-01-21T16:41:39.825Z` - so it
+ *   passes both checks and writes a well-formed row under `day=1970-01-21`,
+ *   a partition no query will look at and indistinguishable from a genuine
+ *   1970 record.
+ *
+ * The seconds case is a known hole, not an oversight: catching it needs a
+ * plausibility floor on the value rather than a shape check on the rendering,
+ * which is a different decision (what floor, and what to do at it) than this
+ * transform was scoped to make.
+ */
+const ISO_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+/** Iceberg types the `PageView` row stores as a JavaScript `number`. */
+const NUMERIC_ICEBERG_TYPES = new Set(['int', 'long', 'double']);
+/** Columns Firehose may not write a null to; an absent value drops the record. */
+const REQUIRED_COLUMNS = new Set(PAGE_VIEWS_COLUMNS.filter((column) => column.required).map((column) => column.name));
+/** Columns whose value must be coerced to a number before it is written. */
+const NUMERIC_COLUMNS = new Set(PAGE_VIEWS_COLUMNS.filter((column) => NUMERIC_ICEBERG_TYPES.has(column.icebergType)).map((column) => column.name));
+/** The four columns this transform derives; checked against the table's names. */
+const EVENT_TIME_COLUMN = 'event_time';
+const DAY_COLUMN = 'day';
+const VISITOR_KEY_COLUMN = 'visitor_key';
+const IS_BOT_COLUMN = 'is_bot';
+/** The mapped column both derived columns above read their user agent back from. */
+const USER_AGENT_COLUMN = 'user_agent';
+const ABSENT = { kind: 'absent' };
+function invalid(detail) {
+    return { kind: 'invalid', detail };
+}
+/** The clause a drop reason ends with, for a field that yielded no value. */
+function unfilledDetail(outcome) {
+    return outcome.kind === 'absent' ? 'is absent' : outcome.detail;
+}
+/** A string column's value, with CloudFront's absence markers read as absent. */
+function stringFrom(raw) {
+    if (raw === undefined || raw === null)
+        return ABSENT;
+    if (typeof raw === 'number') {
+        return Number.isFinite(raw)
+            ? { kind: 'value', value: String(raw) }
+            : invalid(`holds ${String(raw)}, which is not a finite number`);
+    }
+    if (typeof raw !== 'string')
+        return invalid(`holds an unsupported ${typeof raw} value, which is not text`);
+    const value = raw.trim();
+    return value === '' || value === CLOUDFRONT_EMPTY_VALUE ? ABSENT : { kind: 'value', value };
+}
+/**
+ * A numeric column's value; anything that does not parse is a drop, not a
+ * `NaN`.
+ *
+ * Known gap: this coerces by JavaScript number, not by the column's Iceberg
+ * type, so an `int` or `long` column accepts a non-integral value as readily
+ * as a `double` does - `sc-status: '200.5'` is written through as `200.5`. No
+ * CloudFront field can produce such a value, so nothing here rounds or rejects
+ * one; a source that could would need an integrality check keyed on
+ * `icebergType`.
+ */
+function numberFrom(raw) {
+    if (raw === undefined || raw === null)
+        return ABSENT;
+    if (typeof raw === 'number') {
+        return Number.isFinite(raw)
+            ? { kind: 'value', value: raw }
+            : invalid(`holds ${String(raw)}, which is not a finite number`);
+    }
+    if (typeof raw !== 'string')
+        return invalid(`holds an unsupported ${typeof raw} value, which is not a number`);
+    const text = raw.trim();
+    if (text === '' || text === CLOUDFRONT_EMPTY_VALUE)
+        return ABSENT;
+    const value = Number(text);
+    return Number.isFinite(value)
+        ? { kind: 'value', value }
+        : invalid(`holds "${raw}", which does not parse as a number`);
+}
+/** Reads one field the way its target column stores it. */
+function columnValueFrom(raw, column) {
+    return NUMERIC_COLUMNS.has(column) ? numberFrom(raw) : stringFrom(raw);
+}
+/** `event_time` as a UTC ISO-8601 instant, from `timestamp(ms)`. */
+function eventTimeFrom(raw) {
+    const milliseconds = numberFrom(raw);
+    if (milliseconds.kind !== 'value')
+        return milliseconds;
+    const instant = new Date(milliseconds.value);
+    if (Number.isNaN(instant.getTime())) {
+        return invalid(`holds ${String(milliseconds.value)}, which is not a representable instant`);
+    }
+    const eventTime = instant.toISOString();
+    return ISO_INSTANT.test(eventTime)
+        ? { kind: 'value', value: eventTime }
+        : invalid(`holds ${String(milliseconds.value)}, which falls outside the years 0000-9999`);
+}
+/** The `day` partition value: the UTC date `event_time` falls on. */
+function dayFrom(eventTime) {
+    return eventTime.slice(0, ISO_DATE_LENGTH);
+}
+/**
+ * The user agent as the row will carry it - trimmed, with CloudFront's absence
+ * markers already read as absent - or `undefined` when the request named none.
+ * Both derived columns read it back from the row rather than from the record,
+ * so the text hashed into `visitor_key` and the text `is_bot` was decided from
+ * are exactly the text stored in `user_agent`. A divergence between the three
+ * would be invisible in the table and unfalsifiable from a query.
+ */
+function userAgentOf(row) {
+    const userAgent = row[USER_AGENT_COLUMN];
+    return typeof userAgent === 'string' ? userAgent : undefined;
+}
+/** A drop naming the column, the field behind it, and what was wrong. */
+function dropped(column, field, detail) {
+    return {
+        mapped: false,
+        column,
+        field,
+        reason: `page_views column "${column}" cannot be filled: CloudFront field "${field}" ${detail}`,
+    };
+}
+/** Both derived columns are lost together, because both read the same field. */
+function droppedTimestamp(detail) {
+    return {
+        mapped: false,
+        column: EVENT_TIME_COLUMN,
+        field: TIMESTAMP_MS_FIELD,
+        reason: `page_views columns "${EVENT_TIME_COLUMN}" and "${DAY_COLUMN}" cannot be filled: CloudFront field "${TIMESTAMP_MS_FIELD}" ${detail}`,
+    };
+}
+/**
+ * Turns one CloudFront access-log record into a `page_views` row, or reports
+ * why it cannot. Never returns a partially populated row: the first column it
+ * cannot fill ends the mapping.
+ *
+ * `saltSecret` is the long-lived stored secret behind `visitor_key`, not the
+ * day's salt - that is derived here from the record's own day. It is required
+ * rather than optional on purpose: a row mapped without it would carry no
+ * visitor at all, or worse an unsalted digest, and either would look like a
+ * normal row in the table. `dailySalt` throws on an empty secret for the same
+ * reason, so a caller whose secret read failed fails its batch instead of
+ * quietly writing unprotected data.
+ */
+export function mapRecord(record, saltSecret) {
+    const eventTime = eventTimeFrom(record[TIMESTAMP_MS_FIELD]);
+    if (eventTime.kind !== 'value')
+        return droppedTimestamp(unfilledDetail(eventTime));
+    const day = dayFrom(eventTime.value);
+    const columns = {
+        [EVENT_TIME_COLUMN]: eventTime.value,
+        [DAY_COLUMN]: day,
+    };
+    for (const [field, column] of Object.entries(FIELD_TO_COLUMN)) {
+        const outcome = columnValueFrom(record[field], column);
+        if (outcome.kind === 'invalid')
+            return dropped(column, field, outcome.detail);
+        if (outcome.kind === 'absent') {
+            if (REQUIRED_COLUMNS.has(column))
+                return dropped(column, field, unfilledDetail(outcome));
+            continue;
+        }
+        columns[column] = outcome.value;
+    }
+    // `is_bot` is set for every record, including the ones that named no agent:
+    // the column answers "did this agent name itself as a bot", and `false` is
+    // that question's answer for a request that named nothing.
+    const userAgent = userAgentOf(columns);
+    columns[IS_BOT_COLUMN] = isBotUserAgent(userAgent);
+    // The viewer IP goes in here and comes out as a digest. An unusable value
+    // drops the record like any other - the same rule the rest of this module
+    // follows - but an *absent* one leaves `visitor_key` empty rather than
+    // hashing the user agent alone, which would collapse every anonymous request
+    // in a day onto one fabricated returning visitor. A null visitor is exactly
+    // what an unknown one is, and `COUNT(DISTINCT visitor_key)` skips it.
+    const viewerIp = stringFrom(record[VIEWER_IP_FIELD]);
+    if (viewerIp.kind === 'invalid') {
+        return dropped(VISITOR_KEY_COLUMN, VIEWER_IP_FIELD, viewerIp.detail);
+    }
+    if (viewerIp.kind === 'value') {
+        columns[VISITOR_KEY_COLUMN] = visitorKey(viewerIp.value, userAgent ?? '', dailySalt(saltSecret, day));
+    }
+    // Every required column is filled above or the record has already dropped:
+    // `event_time` and `day` unconditionally, and the required mapped columns by
+    // the guard in the loop. `map-record.test.ts` pins that correspondence
+    // against `PAGE_VIEWS_COLUMNS` itself, so a column the table makes required
+    // later fails a test here rather than a Firehose write in production.
+    return { mapped: true, row: columns };
+}

package/dist/transform/visitor-key.d.ts

@@ -0,0 +1,83 @@
+/**
+ * `visitor_key`: how a page view is attributed to a visitor without the table
+ * ever holding a value that identifies one. This is step 3 of
+ * [§Record transformation](../../../../.specs/changes/merged/2026-07-26-analytics_plugin.md):
+ * the viewer IP is replaced by a SHA-256 digest over the IP, the user agent
+ * and a secret daily salt, and the raw address is written to no column.
+ *
+ * ## The salt decision (settled 2026-07-26)
+ *
+ * ONE long-lived random secret lives in Secrets Manager, and the per-day salt
+ * is **derived** from it: `dailySalt(secret, day) = HMAC-SHA256(secret, day)`.
+ * The secret is created once and never rewritten; nothing rotates in Secrets
+ * Manager. Both alternatives were considered and rejected:
+ *
+ * - **A salt derived from the date alone** is computable by anyone holding the
+ *   table, and IPv4 is a 2^32 space - so every row brute-forces back to its
+ *   source address in seconds of GPU time. The digest would look like
+ *   pseudonymisation while providing none of it.
+ * - **Managed rotation of the stored secret** would add a rotation Lambda, a
+ *   schedule and a second execution role - more moving parts than the thing
+ *   they protect - to buy exactly the daily turnover that deriving already
+ *   gives for the price of one HMAC per record.
+ *
+ * The consequence to know before touching the stored secret: replacing it
+ * after rows exist makes `visitor_key` incomparable across that boundary, and
+ * no reprocessing can repair it because the old salt is gone. That is why the
+ * node that provisions the secret creates it when absent and never rewrites
+ * it.
+ *
+ * Daily turnover is deliberate and has a query consequence: a unique-visitor
+ * figure is a per-day distinct count, and a range figure is the sum of those
+ * daily counts - never a `COUNT(DISTINCT visitor_key)` spanning days, which
+ * two salts make meaningless. One day is also the bound on what anyone holding
+ * the table and one brute-forced day of salt could ever correlate.
+ *
+ * ## Purity
+ *
+ * Both functions take every input as an argument: no Secrets Manager read, no
+ * environment variable, no clock, no wall-clock date anywhere. The secret
+ * arrives from the transform's cold-start read and the day from the record's
+ * own `timestamp(ms)` - which is what lets a backfill re-derive a historical
+ * day's salt and produce a byte-identical row for a record either path could
+ * have carried.
+ */
+/**
+ * The salt for one UTC day: `HMAC-SHA256(secret, day)` over the long-lived
+ * stored secret and the `day` the record already carries (`YYYY-MM-DD`).
+ *
+ * The secret is the key and the day the message, not the other way round: the
+ * day is public, and only a secret key gives the output a value an attacker
+ * cannot compute.
+ *
+ * Throws rather than deriving from an empty secret or an empty day. An empty
+ * secret yields a salt anyone can recompute, and an empty day yields one salt
+ * for all time - both produce a `visitor_key` that looks protected and is not,
+ * which is worse than a failed batch that says so.
+ */
+export declare function dailySalt(secret: string, day: string): string;
+/**
+ * The pseudonymous visitor identifier: a SHA-256 digest over the viewer IP,
+ * the user agent and that day's salt, as lowercase hex.
+ *
+ * Why this construction is enough for what it is asked to do. The key must be
+ * stable within a day (so a visitor counts once), unguessable from the table
+ * (which stores `user_agent` in the clear beside it), and irreversible. A hash
+ * alone would satisfy none of the last two: an IPv4 address is a 32-bit space,
+ * so an unsalted digest is a lookup table. The secret salt is what removes
+ * that, and the daily salt is what bounds the correlation window to a day. The
+ * salt is hashed last, so no length-extension property of Merkle-Damgård
+ * applies to a secret prefix.
+ *
+ * An empty `userAgent` is a legitimate input, not an error: a request that
+ * sent no `User-Agent` header still has a viewer IP, and its visitor is still
+ * countable. An absent user agent and an empty one are deliberately the same
+ * input, because they are the same fact about the request.
+ *
+ * Throws when the IP or the salt is empty. Without a salt the digest is
+ * brute-forceable; without an IP the key would be a digest of the user agent
+ * alone, which would collapse every anonymous request in a day onto one
+ * fabricated "returning visitor". The caller leaves the column empty instead -
+ * an unknown visitor is what a null says.
+ */
+export declare function visitorKey(ip: string, userAgent: string, salt: string): string;

package/dist/transform/visitor-key.js

@@ -0,0 +1,120 @@
+/**
+ * `visitor_key`: how a page view is attributed to a visitor without the table
+ * ever holding a value that identifies one. This is step 3 of
+ * [§Record transformation](../../../../.specs/changes/merged/2026-07-26-analytics_plugin.md):
+ * the viewer IP is replaced by a SHA-256 digest over the IP, the user agent
+ * and a secret daily salt, and the raw address is written to no column.
+ *
+ * ## The salt decision (settled 2026-07-26)
+ *
+ * ONE long-lived random secret lives in Secrets Manager, and the per-day salt
+ * is **derived** from it: `dailySalt(secret, day) = HMAC-SHA256(secret, day)`.
+ * The secret is created once and never rewritten; nothing rotates in Secrets
+ * Manager. Both alternatives were considered and rejected:
+ *
+ * - **A salt derived from the date alone** is computable by anyone holding the
+ *   table, and IPv4 is a 2^32 space - so every row brute-forces back to its
+ *   source address in seconds of GPU time. The digest would look like
+ *   pseudonymisation while providing none of it.
+ * - **Managed rotation of the stored secret** would add a rotation Lambda, a
+ *   schedule and a second execution role - more moving parts than the thing
+ *   they protect - to buy exactly the daily turnover that deriving already
+ *   gives for the price of one HMAC per record.
+ *
+ * The consequence to know before touching the stored secret: replacing it
+ * after rows exist makes `visitor_key` incomparable across that boundary, and
+ * no reprocessing can repair it because the old salt is gone. That is why the
+ * node that provisions the secret creates it when absent and never rewrites
+ * it.
+ *
+ * Daily turnover is deliberate and has a query consequence: a unique-visitor
+ * figure is a per-day distinct count, and a range figure is the sum of those
+ * daily counts - never a `COUNT(DISTINCT visitor_key)` spanning days, which
+ * two salts make meaningless. One day is also the bound on what anyone holding
+ * the table and one brute-forced day of salt could ever correlate.
+ *
+ * ## Purity
+ *
+ * Both functions take every input as an argument: no Secrets Manager read, no
+ * environment variable, no clock, no wall-clock date anywhere. The secret
+ * arrives from the transform's cold-start read and the day from the record's
+ * own `timestamp(ms)` - which is what lets a backfill re-derive a historical
+ * day's salt and produce a byte-identical row for a record either path could
+ * have carried.
+ */
+import { createHash, createHmac } from 'node:crypto';
+/** The one digest algorithm both derivations use. */
+const DIGEST_ALGORITHM = 'sha256';
+/** Digests are lowercase hex: 64 characters, safe in a `string` column. */
+const DIGEST_ENCODING = 'hex';
+/**
+ * One input, length-prefixed, so a concatenation of several is unambiguous:
+ * `("1.2.3", "45")` and `("1.2.34", "5")` both concatenate to `1.2.345` and
+ * would collide, while they frame to `5:1.2.32:45` and `6:1.2.341:5`, which do
+ * not. A plain separator character could not promise as much: a user agent is
+ * attacker-supplied text and may contain whatever separator was chosen, which
+ * would let two different visitors collide onto one key by construction.
+ *
+ * The count is in UTF-8 bytes because that is the encoding `update` applies to
+ * a string, so the frame describes the bytes actually hashed.
+ */
+function framed(value) {
+    return `${Buffer.byteLength(value)}:${value}`;
+}
+/**
+ * The salt for one UTC day: `HMAC-SHA256(secret, day)` over the long-lived
+ * stored secret and the `day` the record already carries (`YYYY-MM-DD`).
+ *
+ * The secret is the key and the day the message, not the other way round: the
+ * day is public, and only a secret key gives the output a value an attacker
+ * cannot compute.
+ *
+ * Throws rather than deriving from an empty secret or an empty day. An empty
+ * secret yields a salt anyone can recompute, and an empty day yields one salt
+ * for all time - both produce a `visitor_key` that looks protected and is not,
+ * which is worse than a failed batch that says so.
+ */
+export function dailySalt(secret, day) {
+    if (secret.trim() === '') {
+        throw new Error('dailySalt was given no salt secret: an empty secret makes every visitor_key recomputable by anyone holding the table');
+    }
+    if (day.trim() === '') {
+        throw new Error('dailySalt was given no day: an empty day gives every record the same salt, so the daily turnover visitor_key depends on never happens');
+    }
+    return createHmac(DIGEST_ALGORITHM, secret).update(day).digest(DIGEST_ENCODING);
+}
+/**
+ * The pseudonymous visitor identifier: a SHA-256 digest over the viewer IP,
+ * the user agent and that day's salt, as lowercase hex.
+ *
+ * Why this construction is enough for what it is asked to do. The key must be
+ * stable within a day (so a visitor counts once), unguessable from the table
+ * (which stores `user_agent` in the clear beside it), and irreversible. A hash
+ * alone would satisfy none of the last two: an IPv4 address is a 32-bit space,
+ * so an unsalted digest is a lookup table. The secret salt is what removes
+ * that, and the daily salt is what bounds the correlation window to a day. The
+ * salt is hashed last, so no length-extension property of Merkle-Damgård
+ * applies to a secret prefix.
+ *
+ * An empty `userAgent` is a legitimate input, not an error: a request that
+ * sent no `User-Agent` header still has a viewer IP, and its visitor is still
+ * countable. An absent user agent and an empty one are deliberately the same
+ * input, because they are the same fact about the request.
+ *
+ * Throws when the IP or the salt is empty. Without a salt the digest is
+ * brute-forceable; without an IP the key would be a digest of the user agent
+ * alone, which would collapse every anonymous request in a day onto one
+ * fabricated "returning visitor". The caller leaves the column empty instead -
+ * an unknown visitor is what a null says.
+ */
+export function visitorKey(ip, userAgent, salt) {
+    if (ip.trim() === '') {
+        throw new Error('visitorKey was given no viewer IP: a key over the user agent alone would count every anonymous request in a day as one returning visitor');
+    }
+    if (salt.trim() === '') {
+        throw new Error('visitorKey was given no salt: an unsalted digest of an IPv4 address brute-forces in seconds, so the key would identify the visitor it exists to hide');
+    }
+    return createHash(DIGEST_ALGORITHM)
+        .update(framed(ip) + framed(userAgent) + framed(salt))
+        .digest(DIGEST_ENCODING);
+}