@blamejs/core 0.8.42 → 0.8.49

package/lib/session.js

@@ -1,39 +1,50 @@
 "use strict";
 /**
- * Session store — DB-backed, vault-sealed, sid-hashed-at-rest.
+ * @module b.session
+ * @featured true
+ * @nav    Data
+ * @title  Session
  *
- * Single-node: stored in the framework's main DB under `_blamejs_sessions`
- * (baked into db.js's FRAMEWORK_SCHEMA — apps cannot opt out).
- * Cluster mode: stored in external-db under the same name (via
- * frameworkSchema.ensureSchema). cluster-storage.execute routes the SQL
- * to the right place based on cluster.isClusterMode(); session.js itself
- * doesn't branch on mode.
+ * @intro
+ *   Server-side session store with idle + absolute timeouts, encrypted
+ *   at rest, sealed columns, audit on every login / logout, and
+ *   cluster-aware leader gating.
  *
- * Token discipline:
- *   - The session id (sid) is a 32-byte random value returned to the caller
- *     once. The caller stores it in a cookie / authorization header / etc.
- *   - The DB primary key is sha3('bj-session:' || sid) — the sid itself
- *     never lands in the database. DB exfiltration alone cannot impersonate
- *     a session: the attacker would also need the original sid (which only
- *     the user has).
- *   - data is vault-sealed JSON; userId is sealed; userIdHash indexes for
- *     destroyAllForUser without unsealing every row.
+ *   The session id (sid) is a 32-byte random value returned to the
+ *   caller once and stored client-side (cookie / authorization header).
+ *   The DB primary key is `sha3('bj-session:' || sid)` — the plaintext
+ *   sid never lands in the database. DB exfiltration alone cannot
+ *   impersonate a session: the attacker would also need the original
+ *   sid the user holds. The `data` column is vault-sealed JSON;
+ *   `userId` is sealed; `userIdHash` indexes for destroyAllForUser
+ *   without unsealing every row.
  *
- * Public API:
+ *   Idle + absolute timeout enforcement follows OWASP ASVS 5.0 §3.3
+ *   and NIST SP 800-63B-4. Defaults: idle 30 minutes, absolute 12
+ *   hours. Both shorten the effective lifetime even when the operator
+ *   picked a long ttlMs; repeated `touch({ extendBy })` cannot push
+ *   `expiresAt` past the absolute ceiling.
  *
- *   session.create({ userId, data?, ttlMs? })  → { token, expiresAt }
- *   session.verify(token)                      → { userId, data, createdAt, expiresAt, lastActivity } or null
- *   session.destroy(token)                     → boolean
- *   session.destroyAllForUser(userId)          → number deleted
- *   session.touch(token, { extendBy? })        → boolean (updates lastActivity, optionally extends expiresAt)
- *   session.purgeExpired()                     → number deleted
- *   session.count()                            → number of active (non-expired) sessions
+ *   Storage placement is mode-driven: single-node lives in the
+ *   framework's main DB under `_blamejs_sessions` (baked into db.js's
+ *   schema — apps cannot opt out); cluster mode lives in external-db
+ *   under the same name. `clusterStorage.execute` routes by
+ *   `cluster.isClusterMode()`; this module does not branch on mode.
  *
- * Cluster posture per blamejs-cluster-spec.md:
- *   create / destroy / destroyAllForUser / touch / purgeExpired
- *     — leader-only (cluster.requireLeader gate at call entry)
- *   verify / count
- *     — anywhere (any node can read shared session state)
+ *   Cluster posture per blamejs-cluster-spec.md:
+ *   `create` / `destroy` / `destroyAllForUser` / `touch` / `rotate` /
+ *   `purgeExpired` are leader-only (gated by `cluster.requireLeader`
+ *   at call entry); `verify` and `count` run anywhere.
+ *
+ *   Optional fingerprint binding: pass `{ req, fingerprintFields }` to
+ *   `create` and `verify` to bind a session to a stable hash of
+ *   client-IP / user-agent / accept-language. Drift produces an audit
+ *   event and surfaces as `fingerprintDrift: true`; strict operators
+ *   pass `requireFingerprintMatch: true` (or a `maxAnomalyScore`
+ *   threshold with a `scorer`) to refuse the session on drift.
+ *
+ * @card
+ *   Server-side session store with idle + absolute timeouts, encrypted at rest, sealed columns, audit on every login / logout, and cluster-aware leader gating.
  */
 var audit = require("./audit");
 var canonicalJson = require("./canonical-json");
@@ -159,6 +170,42 @@ function _hashFingerprint(sid, inputs) {
   return sha3Hash("bj-session-fingerprint:" + sid + ":" + canonical);
 }
 
+/**
+ * @primitive b.session.create
+ * @signature b.session.create(opts)
+ * @since     0.1.0
+ * @related   b.session.verify, b.session.rotate, b.session.destroy
+ *
+ * Mint a fresh session for a known userId and return the plaintext sid
+ * the caller stores client-side (cookie / authorization header). The
+ * sid is 32 random bytes (256-bit entropy floor); the DB stores
+ * `sha3('bj-session:' || sid)` so DB exfiltration alone cannot
+ * impersonate the session. `data` is vault-sealed JSON; `userId` is
+ * sealed; a derived `userIdHash` indexes for fast `destroyAllForUser`.
+ * Leader-only — followers raise NotLeaderError.
+ *
+ * Pass `{ req, fingerprintFields }` to bind the session to a stable
+ * hash of client-IP / user-agent / accept-language; the binding is
+ * checked on every `verify` call.
+ *
+ * @opts
+ *   {
+ *     userId:              string,                // required — opaque user id (sealed at rest)
+ *     data?:               object,                // optional sealed JSON payload
+ *     ttlMs?:              number,                // session lifetime; default 7d, max ~10y
+ *     req?:                IncomingMessage,       // bind fingerprint to this request's signals
+ *     fingerprintFields?:  Array<string|fn>,      // default ["clientIp","userAgent","acceptLanguage"]
+ *   }
+ *
+ * @example
+ *   var s = await b.session.create({
+ *     userId: "user-42",
+ *     data:   { roles: ["admin"] },
+ *     ttlMs:  b.constants.TIME.hours(8),
+ *   });
+ *   res.setHeader("Set-Cookie", "sid=" + s.token + "; HttpOnly; Secure; SameSite=Strict");
+ *   // → { token: "9f2c…", expiresAt: 1735689600000 }
+ */
 async function create(opts) {
   cluster.requireLeader();
   if (!opts || !opts.userId) {
@@ -203,6 +250,48 @@ async function create(opts) {
   return { token: sid, expiresAt: expiresAt };
 }
 
+/**
+ * @primitive b.session.verify
+ * @signature b.session.verify(token, opts?)
+ * @since     0.1.0
+ * @related   b.session.create, b.session.touch, b.session.rotate
+ *
+ * Look up a session by its plaintext sid, enforce TTL + idle +
+ * absolute timeouts, optionally check fingerprint drift, and return
+ * the unsealed payload. Returns `null` for unknown / expired / idle-
+ * expired / absolute-expired sessions; runs anywhere (leader or
+ * follower). On expiry, leader nodes best-effort delete the row;
+ * followers skip cleanup.
+ *
+ * `idleTimeoutMs` defaults to 30 minutes, `absoluteTimeoutMs` to 12
+ * hours; pass 0 to disable either floor. Pass `{ req }` to evaluate
+ * the bound fingerprint — the result carries `fingerprintDrift: true`
+ * on mismatch (audit event always fires). `requireFingerprintMatch:
+ * true` or a `maxAnomalyScore` threshold (with a `scorer` callback)
+ * makes drift refuse the session by returning `null`.
+ *
+ * @opts
+ *   {
+ *     idleTimeoutMs?:            number,          // default 30m; 0 disables
+ *     absoluteTimeoutMs?:        number,          // default 12h; 0 disables
+ *     req?:                      IncomingMessage, // for fingerprint check
+ *     fingerprintFields?:        Array<string|fn>,
+ *     requireFingerprintMatch?:  boolean,         // strict — drift kills the session
+ *     maxAnomalyScore?:          number,          // 0..1; drift above kills
+ *     scorer?:                   function,        // ({storedHash,currentInputs,currentHash,sessionAge}) -> 0..1
+ *   }
+ *
+ * @example
+ *   var info = await b.session.verify(req.cookies.sid, { req: req });
+ *   if (!info) {
+ *     res.statusCode = 401;
+ *     res.end("login required");
+ *     return;
+ *   }
+ *   var userId = info.userId;
+ *   var roles  = (info.data && info.data.roles) || [];
+ *   // → { userId: "user-42", data: { roles: ["admin"] }, createdAt: ..., expiresAt: ..., lastActivity: ..., fingerprintDrift: false, fingerprintAnomalyScore: null }
+ */
 async function verify(token, verifyOpts) {
   if (typeof token !== "string" || token.length === 0) return null;
   verifyOpts = verifyOpts || {};
@@ -364,6 +453,24 @@ async function verify(token, verifyOpts) {
   };
 }
 
+/**
+ * @primitive b.session.destroy
+ * @signature b.session.destroy(token)
+ * @since     0.1.0
+ * @related   b.session.destroyAllForUser, b.session.create
+ *
+ * Revoke a single session by sid. Returns `true` when a row was
+ * deleted, `false` when the sid is unknown / already gone / empty.
+ * Standard logout flow: clear the client's cookie AND call
+ * `destroy(sid)` so the row vanishes from the DB and verify(sid)
+ * starts returning null cluster-wide. Leader-only.
+ *
+ * @example
+ *   await b.session.destroy(req.cookies.sid);
+ *   res.setHeader("Set-Cookie", "sid=; HttpOnly; Max-Age=0");
+ *   res.end("logged out");
+ *   // → true
+ */
 async function destroy(token) {
   cluster.requireLeader();
   if (typeof token !== "string" || token.length === 0) return false;
@@ -378,6 +485,24 @@ async function _deleteBySidHash(sidHash) {
   return (result.rowCount || 0) > 0;
 }
 
+/**
+ * @primitive b.session.destroyAllForUser
+ * @signature b.session.destroyAllForUser(userId)
+ * @since     0.1.0
+ * @related   b.session.destroy, b.session.rotate
+ *
+ * Revoke every active session for a userId at once. Returns the count
+ * of rows deleted. Use after password change, role revocation,
+ * compromised-account reports, or "log me out everywhere" UI flows.
+ * Lookup goes through the derived `userIdHash` — no row needs
+ * unsealing to find matches. Leader-only.
+ *
+ * @example
+ *   var revoked = await b.session.destroyAllForUser("user-42");
+ *   b.audit.emit({ action: "auth.session.revoke_all", outcome: "success",
+ *     metadata: { userId: "user-42", count: revoked } });
+ *   // → 3
+ */
 async function destroyAllForUser(userId) {
   cluster.requireLeader();
   if (!userId) throw _err("INVALID_ARG", "session.destroyAllForUser requires a userId", true);
@@ -395,6 +520,33 @@ async function destroyAllForUser(userId) {
   return result.rowCount || 0;
 }
 
+/**
+ * @primitive b.session.touch
+ * @signature b.session.touch(token, opts)
+ * @since     0.1.0
+ * @related   b.session.verify, b.session.rotate
+ *
+ * Refresh `lastActivity` (resets the idle-timeout countdown) and
+ * optionally extend `expiresAt`. Returns `true` when a non-expired
+ * row was updated, `false` when the sid is unknown or the row is
+ * already past its TTL. Pass `extendBy` to push `expiresAt` forward
+ * relative to NOW (not the existing expiry — soaked sessions with
+ * continuous traffic don't accumulate unbounded expiry); the
+ * framework's MAX_TTL_MS bound applies. Leader-only.
+ *
+ * @opts
+ *   {
+ *     extendBy?: number,   // ms to set new expiresAt = now + extendBy
+ *   }
+ *
+ * @example
+ *   // Bump idle clock on every request:
+ *   await b.session.touch(req.cookies.sid);
+ *
+ *   // Sliding-window: extend by another 8 hours when activity continues.
+ *   await b.session.touch(req.cookies.sid, { extendBy: b.constants.TIME.hours(8) });
+ *   // → true
+ */
 async function touch(token, opts) {
   cluster.requireLeader();
   opts = opts || {};
@@ -426,26 +578,42 @@ async function touch(token, opts) {
   return (result2.rowCount || 0) > 0;
 }
 
-// rotate(oldToken, opts?) — session fixation defense. Generates a fresh
-// sid for the same userId + data, atomically replacing the old sid in
-// the row. Standard pattern: call after auth state changes (login from
-// anonymous, MFA verified, role escalation) so any sid an attacker
-// might have planted pre-login becomes invalid.
-//
-//   opts:
-//     data:   optional replacement session data (re-sealed)
-//     ttlMs:  optional new TTL; if absent, expiresAt is preserved
-//     reason: free-form audit metadata ('login', 'mfa', etc.)
-//
-// Returns { token, expiresAt } on success, or null when the old token
-// doesn't exist / has expired (operator distinguishes by checking
-// for null).
-//
-// Atomicity: single UPDATE swaps sidHash. The old + new tokens never
-// coexist — the moment the UPDATE commits, only the new token verifies.
-// Backends that can't do the WHERE-guarded UPDATE atomically (none of
-// the framework's supported backends fall in that bucket) would need
-// a transactional shim.
+/**
+ * @primitive b.session.rotate
+ * @signature b.session.rotate(oldToken, opts)
+ * @since     0.1.0
+ * @related   b.session.create, b.session.verify, b.session.destroy
+ *
+ * Session-fixation defense: generate a fresh sid for the same userId +
+ * data, atomically replacing the old sid in the row. Call after every
+ * auth state change (login from anonymous, multifactor verified, role
+ * escalation) so any sid an attacker planted pre-login becomes invalid.
+ * Returns `{ token, expiresAt }` on success, `null` when the old token
+ * is unknown / expired (operator distinguishes by checking for null).
+ * Leader-only.
+ *
+ * Atomicity: a single WHERE-guarded UPDATE swaps `sidHash`. The old
+ * and new tokens never coexist — the moment the UPDATE commits, only
+ * the new token verifies. Audit event `auth.session.rotate` fires
+ * best-effort with `metadata.reason`.
+ *
+ * @opts
+ *   {
+ *     data?:   object,     // replacement session data (re-sealed)
+ *     ttlMs?:  number,     // new TTL; if absent, existing expiresAt preserved
+ *     reason?: string,     // audit metadata ("login", "mfa", "role-change")
+ *   }
+ *
+ * @example
+ *   var rotated = await b.session.rotate(req.cookies.sid, {
+ *     ttlMs:  b.constants.TIME.hours(8),
+ *     reason: "mfa",
+ *   });
+ *   if (rotated) {
+ *     res.setHeader("Set-Cookie", "sid=" + rotated.token + "; HttpOnly; Secure; SameSite=Strict");
+ *   }
+ *   // → { token: "7a1e…", expiresAt: 1735689600000 }
+ */
 async function rotate(oldToken, opts) {
   cluster.requireLeader();
   if (typeof oldToken !== "string" || oldToken.length === 0) return null;
@@ -502,6 +670,30 @@ async function rotate(oldToken, opts) {
   return { token: newSid, expiresAt: expiresAt };
 }
 
+/**
+ * @primitive b.session.purgeExpired
+ * @signature b.session.purgeExpired()
+ * @since     0.1.0
+ * @related   b.session.count, b.session.destroy
+ *
+ * Bulk-delete every row whose `expiresAt` is in the past. Returns the
+ * count of rows removed. The framework purges opportunistically on
+ * `verify` (leader-side), but a periodic sweep keeps the table from
+ * accumulating dead rows when verify traffic is sparse. Safe to schedule
+ * on a recurring timer (the framework's scheduler primitive is the
+ * intended caller). Leader-only.
+ *
+ * @example
+ *   // Hourly purge from a scheduler:
+ *   b.scheduler.every(b.constants.TIME.hours(1), async function () {
+ *     var dropped = await b.session.purgeExpired();
+ *     b.audit.emit({
+ *       action: "auth.session.purge_expired", outcome: "success",
+ *       metadata: { dropped: dropped },
+ *     });
+ *   });
+ *   // → 17
+ */
 async function purgeExpired() {
   cluster.requireLeader();
   var result = await clusterStorage.execute(
@@ -511,6 +703,24 @@ async function purgeExpired() {
   return result.rowCount || 0;
 }
 
+/**
+ * @primitive b.session.count
+ * @signature b.session.count()
+ * @since     0.1.0
+ * @related   b.session.purgeExpired, b.session.destroyAllForUser
+ *
+ * Return the number of currently-live sessions (rows whose `expiresAt`
+ * is in the future). Useful for ops dashboards, capacity tracking, and
+ * "active users" metrics. Runs anywhere — leader or follower — because
+ * it only reads. Note that idle-timeout-eligible rows are still counted
+ * until a `verify` or `purgeExpired` removes them; the value is an
+ * upper bound on truly-active sessions.
+ *
+ * @example
+ *   var live = await b.session.count();
+ *   b.observability.event({ name: "session.live", value: live });
+ *   // → 482
+ */
 async function count() {
   var row = await clusterStorage.executeOne(
     "SELECT COUNT(*) AS c FROM _blamejs_sessions WHERE expiresAt >= ?",

package/lib/slug.js

@@ -1,37 +1,37 @@
 "use strict";
 /**
- * b.slug — URL-safe slug generation.
+ * @module b.slug
+ * @nav    Tools
+ * @title  Slug
  *
- *   b.slug("Hello, World!")                           // "hello-world"
- *   b.slug("café", { preserveUnicode: false })        // "cafe"
- *   b.slug("Привет мир", { preserveUnicode: true })   // "привет-мир"
+ * @intro
+ *   URL-safe slug generation with two normalization paths and a uniqueness
+ *   helper.
  *
- *   var slug = b.slug.create({ maxLength: 60 });
- *   slug("Title");
+ *   The default ASCII path uses Unicode NFKD decomposition + combining-mark
+ *   strip (`café` → `cafe`) and drops anything outside `[a-zA-Z0-9]`. The
+ *   `preserveUnicode: true` path uses NFC and only drops Unicode
+ *   punctuation, symbols, and separators — Cyrillic, Greek, CJK, and other
+ *   scripts pass through. Operators with non-Latin user content opt into
+ *   preserveUnicode.
  *
- *   var s = await b.slug.unique("Hello, World!", function (cand) {
- *     return db.bundles.exists({ slug: cand });
- *   });
- *   // → "hello-world", or "hello-world-2", "hello-world-3", ...
- *
- * The default ASCII path uses Unicode NFKD decomposition + combining-mark
- * strip (`café` → `cafe`) and drops anything outside `[a-zA-Z0-9]`. The
- * `preserveUnicode: true` path uses NFC and only drops Unicode punctuation,
- * symbols, and separators — Cyrillic, Greek, CJK, and other scripts pass
- * through. Operators with non-Latin user content opt into preserveUnicode.
+ *   `b.slug` is a callable function with the rest of the API hung off it
+ *   (callable-namespace pattern): `b.slug.create` builds a bound slugger
+ *   pre-configured with operator opts, and `b.slug.unique` resolves the
+ *   first un-taken candidate against an operator-supplied `isUsed`
+ *   predicate (numeric suffixes `-2`, `-3`, … on collision).
  *
- * Validation policy:
+ *   Validation policy: opts and `title` are validated at the call site
+ *   (throw on bad input). Titles that normalize to empty are tolerant —
+ *   `opts.fallback` is returned instead of throwing. `unique()` exhausting
+ *   `maxAttempts` throws `SlugError`.
  *
- *   - Opts at first call (every public fn) → throw at call site
- *   - title not a string                   → throw at call site
- *   - title normalizes to empty            → return opts.fallback (tolerant)
- *   - unique() exhausts maxAttempts        → throw SlugError at call site
+ *   Reserved web slugs (admin, api, login, …) live on `b.slug.RESERVED`
+ *   as a mutable Set; operators extend it once at boot and pass it into
+ *   their `isUsed` predicate.
  *
- * Out of scope (v1):
- *   - Word-by-word transliteration tables (Russian → English, Chinese →
- *     Pinyin). Use preserveUnicode: true as the v1 escape hatch.
- *   - Stemming / lemmatization / stopword removal.
- *   - HTML-tag stripping (sanitize textually before slugging).
+ * @card
+ *   URL-safe slug generation with two normalization paths and a uniqueness helper.
  */
 
 var numericChecks = require("./numeric-checks");
@@ -180,12 +180,83 @@ function _truncateAtSeparator(s, maxLength, sep) {
 
 // ---- Public surface ----
 
+/**
+ * @primitive b.slug
+ * @signature b.slug(title, callOpts)
+ * @since     0.1.0
+ * @related   b.slug.create, b.slug.unique
+ *
+ * Slugify a title. The default path produces lowercase ASCII separated by
+ * `-`: accents fold (`café` → `cafe`), runs of non-alphanumerics collapse
+ * to a single separator, and the result is trimmed of leading/trailing
+ * separators and capped at `maxLength` (truncating at a separator
+ * boundary when possible). Empty results return `opts.fallback`.
+ *
+ * `preserveUnicode: true` keeps letters and digits in any script and
+ * only drops punctuation/symbols/separators — the right choice for
+ * non-Latin user content.
+ *
+ * @opts
+ *   separator:       string,   // single-char join between tokens (default "-")
+ *   lowercase:       boolean,  // lowercase output (default true, locale-independent)
+ *   maxLength:       number,   // hard cap on output length, or null for none (default 80)
+ *   preserveUnicode: boolean,  // keep non-ASCII letters/digits (default false)
+ *   fallback:        string,   // returned when title normalizes to empty (default "")
+ *
+ * @example
+ *   b.slug("Hello, World!");
+ *   // → "hello-world"
+ *
+ *   b.slug("café résumé");
+ *   // → "cafe-resume"
+ *
+ *   b.slug("Привет мир", { preserveUnicode: true });
+ *   // → "привет-мир"
+ *
+ *   b.slug("a".repeat(200), { maxLength: 10 });
+ *   // → "aaaaaaaaaa"
+ *
+ *   b.slug("---", { fallback: "untitled" });
+ *   // → "untitled"
+ */
 function slug(title, callOpts) {
   var opts = Object.assign({}, DEFAULTS, callOpts || {});
   _validateOpts("slug", opts);
   return _slugify(title, opts);
 }
 
+/**
+ * @primitive b.slug.create
+ * @signature b.slug.create(creatorOpts)
+ * @since     0.1.0
+ * @related   b.slug, b.slug.unique
+ *
+ * Build a bound slugger pre-configured with operator opts. Returns a
+ * function with the same signature as `b.slug` — per-call opts merge
+ * over the bound opts, so the operator picks defaults once at boot and
+ * call sites stay short. Useful when one section of the app slugs with
+ * non-default settings (longer maxLength, Unicode-preserving, custom
+ * separator).
+ *
+ * @opts
+ *   separator:       string,   // single-char join between tokens (default "-")
+ *   lowercase:       boolean,  // lowercase output (default true)
+ *   maxLength:       number,   // hard cap on output length, or null for none (default 80)
+ *   preserveUnicode: boolean,  // keep non-ASCII letters/digits (default false)
+ *   fallback:        string,   // returned when title normalizes to empty (default "")
+ *
+ * @example
+ *   var titleSlug = b.slug.create({ maxLength: 60, preserveUnicode: true });
+ *   titleSlug("Привет мир");
+ *   // → "привет-мир"
+ *
+ *   titleSlug("Hello, World!");
+ *   // → "hello-world"
+ *
+ *   // Per-call opts override creator opts:
+ *   titleSlug("Hello, World!", { separator: "_" });
+ *   // → "hello_world"
+ */
 function create(creatorOpts) {
   var merged = Object.assign({}, DEFAULTS, creatorOpts || {});
   _validateOpts("slug.create", merged);
@@ -197,6 +268,47 @@ function create(creatorOpts) {
   };
 }
 
+/**
+ * @primitive b.slug.unique
+ * @signature b.slug.unique(title, isUsed, callOpts)
+ * @since     0.1.0
+ * @related   b.slug, b.slug.create
+ *
+ * Resolve the first un-taken slug for `title` against an operator-supplied
+ * `isUsed(candidate)` predicate (sync or async). The bare slug is tried
+ * first; on collision the function appends a numeric suffix (`-2`, `-3`,
+ * …) and re-checks until `isUsed` returns falsy or `maxAttempts` is
+ * exhausted. When the suffix would push past `maxLength`, the base is
+ * truncated at a separator boundary so the final candidate fits. Throws
+ * `SlugError` on exhaustion.
+ *
+ * @opts
+ *   separator:       string,   // single-char join between tokens (default "-")
+ *   lowercase:       boolean,  // lowercase output (default true)
+ *   maxLength:       number,   // hard cap on output length, or null for none (default 80)
+ *   preserveUnicode: boolean,  // keep non-ASCII letters/digits (default false)
+ *   fallback:        string,   // returned when title normalizes to empty (default "")
+ *   maxAttempts:     number,   // total tries including bare base (default 100)
+ *   start:           number,   // first numeric suffix (default 2)
+ *   suffixSeparator: string,   // separator between base and suffix (default opts.separator)
+ *
+ * @example
+ *   var taken = new Set(["hello-world", "hello-world-2"]);
+ *   async function isUsed(cand) { return taken.has(cand); }
+ *
+ *   var s1 = await b.slug.unique("Hello, World!", isUsed);
+ *   // → "hello-world-3"
+ *
+ *   var s2 = await b.slug.unique("Brand New Title", isUsed);
+ *   // → "brand-new-title"
+ *
+ *   // Custom suffix separator + start index:
+ *   var s3 = await b.slug.unique("Hello, World!", isUsed, {
+ *     suffixSeparator: "_",
+ *     start: 10,
+ *   });
+ *   // → "hello-world_10"
+ */
 async function unique(title, isUsed, callOpts) {
   if (typeof isUsed !== "function") {
     throw _err("BAD_ISUSED", "slug.unique: isUsed must be a function, got " + typeof isUsed, true);