@crowi/api 2.0.0-alpha.0

package/dist/util/boot-reporter.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * TTY-aware boot reporter (feature-boot-progress-ui, Part 1).
+ *
+ * Wraps the existing `step()` boot sequence in `crowi/index.ts` and groups
+ * the 13 init steps + the server start steps into four layers
+ * (core / config / services / server). Each layer is shown as:
+ *
+ *   - TTY:     a live spinner that resolves to `✓ <layer>  (Nms)` and a final
+ *              `🚀 API ready <url>` banner.
+ *   - non-TTY: a structured, grep-able one-line log per layer
+ *              (`[boot] core ok (412ms)`), no cursor control / re-draw.
+ *
+ * In both modes a machine-readable marker is emitted on exactly one line at
+ * the end of boot: `@@crowi:ready api <url>` on success, or
+ * `@@crowi:fail api <reason>` when boot aborts (e.g. the database is
+ * unreachable). These two markers are the only contract `scripts/dev.mjs`
+ * depends on — kept separate from the human-facing banner so wording can
+ * change freely. On the fail marker the dev launcher tears the whole tree
+ * (api · web · deps) down instead of leaving web up against a dead api.
+ *
+ * The reporter is intentionally `debug`-independent: it writes to stdout
+ * directly so operators see boot progress without `DEBUG=crowi:*`. When
+ * `DEBUG` is set we degrade to plain mode (see {@link createBootReporter}) so
+ * spinner re-draws never interleave with debug output.
+ *
+ * Pure helpers (marker formatting/parsing, plain-line formatting, duration
+ * formatting, spinner frame, ANSI escapes) are exported so they can be
+ * unit-tested without a real TTY.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAIL_MARKER_PREFIX = exports.ANSI = exports.READY_MARKER_PREFIX = void 0;
+exports.formatDuration = formatDuration;
+exports.spinnerFrame = spinnerFrame;
+exports.formatReadyMarker = formatReadyMarker;
+exports.parseReadyMarker = parseReadyMarker;
+exports.formatFailMarker = formatFailMarker;
+exports.parseFailMarker = parseFailMarker;
+exports.formatPlainLayerLine = formatPlainLayerLine;
+exports.formatPlainReadyLine = formatPlainReadyLine;
+exports.createBootReporter = createBootReporter;
+/** Stable, machine-readable readiness marker prefix. Shared contract with `scripts/dev.mjs`. */
+exports.READY_MARKER_PREFIX = '@@crowi:ready';
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const SPINNER_INTERVAL_MS = 80;
+const LAYER_LABELS = {
+    core: 'core      (encryption · database · models · redis)',
+    config: 'config    (load · migrations · oauth seed)',
+    services: 'services  (renderer · plugins · mailer · slack)',
+    server: 'server    (build · attach · listen)',
+};
+// ── pure helpers (unit-tested) ──────────────────────────────────────────────
+/** ANSI escape fragments — bundled so tests can assert on exact bytes. */
+exports.ANSI = {
+    hideCursor: '\x1b[?25l',
+    showCursor: '\x1b[?25h',
+    clearLine: '\x1b[2K',
+    cursorStart: '\r',
+    dim: '\x1b[2m',
+    green: '\x1b[32m',
+    cyan: '\x1b[36m',
+    bold: '\x1b[1m',
+    reset: '\x1b[0m',
+};
+/** Format a duration as a compact `(Nms)` / `(N.Ns)` token. */
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+/** Spinner frame for a given tick (wraps around the frame list). */
+function spinnerFrame(tick) {
+    return SPINNER_FRAMES[tick % SPINNER_FRAMES.length];
+}
+/** Build the `@@crowi:ready <service> <url>` marker line (no trailing newline). */
+function formatReadyMarker(service, url) {
+    return `${exports.READY_MARKER_PREFIX} ${service} ${url}`;
+}
+/**
+ * Parse a `@@crowi:ready <service> <url>` marker out of an arbitrary output
+ * line (it may be prefixed by turbo's `api:dev: ` etc.). Returns null when the
+ * line carries no marker. Shared logic mirrored in `scripts/dev.mjs`.
+ */
+function parseReadyMarker(line) {
+    const idx = line.indexOf(exports.READY_MARKER_PREFIX);
+    if (idx === -1)
+        return null;
+    const rest = line.slice(idx + exports.READY_MARKER_PREFIX.length).trim();
+    const [service, url] = rest.split(/\s+/);
+    if (!service || !url)
+        return null;
+    return { service, url };
+}
+/** Stable, machine-readable boot-failure marker prefix. Shared contract with `scripts/dev.mjs`. */
+exports.FAIL_MARKER_PREFIX = '@@crowi:fail';
+/**
+ * Build the `@@crowi:fail <service> <reason>` marker line (no trailing newline).
+ * The reason is collapsed to a single line so the marker is always parseable
+ * off one output line.
+ */
+function formatFailMarker(service, reason) {
+    return `${exports.FAIL_MARKER_PREFIX} ${service} ${reason.replace(/\s+/g, ' ').trim()}`;
+}
+/**
+ * Parse a `@@crowi:fail <service> <reason…>` marker out of an arbitrary output
+ * line (it may be prefixed by turbo's `api:dev: `). `service` is the first
+ * token; `reason` is the remainder (may be empty). Returns null when the line
+ * carries no marker. Mirrored in `scripts/dev.mjs` so the dev launcher can tear
+ * the whole tree down instead of leaving web up against a dead api.
+ */
+function parseFailMarker(line) {
+    const idx = line.indexOf(exports.FAIL_MARKER_PREFIX);
+    if (idx === -1)
+        return null;
+    const rest = line.slice(idx + exports.FAIL_MARKER_PREFIX.length).trim();
+    if (!rest)
+        return null;
+    const sp = rest.indexOf(' ');
+    if (sp === -1)
+        return { service: rest, reason: '' };
+    return { service: rest.slice(0, sp), reason: rest.slice(sp + 1).trim() };
+}
+/** Non-TTY structured layer line: `[boot] core ok (412ms)`. */
+function formatPlainLayerLine(layer, ms) {
+    return `[boot] ${layer} ok (${formatDuration(ms)})`;
+}
+/** Non-TTY final line: `[boot] ready in 1.2s` (total boot time). */
+function formatPlainReadyLine(totalMs) {
+    return `[boot] ready in ${formatDuration(totalMs)}`;
+}
+/**
+ * Construct the boot reporter. In TTY mode it animates a spinner per layer; in
+ * plain mode (non-TTY, or `DEBUG` set) it emits one structured line per layer.
+ */
+function createBootReporter(options = {}) {
+    const stream = options.stream ?? process.stdout;
+    const quiet = options.quiet ?? false;
+    const debugEnabled = options.debugEnabled ?? Boolean(process.env.DEBUG);
+    // Graceful degrade: spinner only when we own a real TTY *and* DEBUG isn't
+    // flooding the same stream. In quiet mode force plain (no spinner timer) —
+    // `write` is a no-op anyway, this just avoids arming a useless interval.
+    const tty = !quiet && (options.isTTY ?? Boolean(stream.isTTY)) && !debugEnabled;
+    const bootStart = Date.now();
+    let layerStart = 0;
+    let activeLayer = null;
+    let tick = 0;
+    let timer = null;
+    const write = (s) => {
+        if (quiet)
+            return;
+        stream.write(s);
+    };
+    const drawSpinner = () => {
+        if (!activeLayer)
+            return;
+        write(`${exports.ANSI.cursorStart}${exports.ANSI.clearLine}${exports.ANSI.cyan}${spinnerFrame(tick)}${exports.ANSI.reset} ${LAYER_LABELS[activeLayer]}`);
+        tick += 1;
+    };
+    const stopSpinner = () => {
+        if (timer) {
+            clearInterval(timer);
+            timer = null;
+        }
+    };
+    // Hide the cursor, draw the first frame, and arm the redraw interval for the
+    // current `activeLayer`. Shared by `beginLayer` (initial) and `note` (re-arm
+    // after temporarily clearing the line to print a message).
+    const startSpinner = () => {
+        write(exports.ANSI.hideCursor);
+        drawSpinner();
+        timer = setInterval(drawSpinner, SPINNER_INTERVAL_MS);
+    };
+    const beginLayer = (layer) => {
+        activeLayer = layer;
+        layerStart = Date.now();
+        tick = 0;
+        if (tty)
+            startSpinner();
+    };
+    const endLayer = () => {
+        if (!activeLayer)
+            return;
+        const elapsed = Date.now() - layerStart;
+        if (tty) {
+            stopSpinner();
+            write(`${exports.ANSI.cursorStart}${exports.ANSI.clearLine}${exports.ANSI.green}✓${exports.ANSI.reset} ${LAYER_LABELS[activeLayer]} ${exports.ANSI.dim}(${formatDuration(elapsed)})${exports.ANSI.reset}\n`);
+            write(exports.ANSI.showCursor);
+        }
+        else {
+            write(`${formatPlainLayerLine(activeLayer, elapsed)}\n`);
+        }
+        activeLayer = null;
+    };
+    const note = (writeFn) => {
+        if (tty && timer) {
+            stopSpinner();
+            write(`${exports.ANSI.cursorStart}${exports.ANSI.clearLine}`);
+            write(exports.ANSI.showCursor);
+            writeFn();
+            // Re-arm the spinner for the still-running layer.
+            startSpinner();
+        }
+        else {
+            writeFn();
+        }
+    };
+    const finish = (service, url) => {
+        // Defensive: make sure no spinner is left running.
+        if (activeLayer)
+            endLayer();
+        stopSpinner();
+        const total = Date.now() - bootStart;
+        if (tty) {
+            write(`${exports.ANSI.bold}${exports.ANSI.green}🚀 API ready${exports.ANSI.reset}  ${exports.ANSI.cyan}${url}${exports.ANSI.reset}  ${exports.ANSI.dim}(${formatDuration(total)})${exports.ANSI.reset}\n`);
+        }
+        else {
+            write(`${formatPlainReadyLine(total)}\n`);
+        }
+        // Machine-readable marker — always on its own line, TTY or not.
+        write(`${formatReadyMarker(service, url)}\n`);
+    };
+    let disposed = false;
+    const dispose = () => {
+        // Idempotent: a try/finally around the boot steps *and* `exitOnError` may
+        // both call this. After the first run there's no spinner/cursor state left
+        // to clean up, so subsequent calls are no-ops (and never re-emit ANSI).
+        if (disposed)
+            return;
+        disposed = true;
+        const spinning = timer !== null;
+        stopSpinner();
+        if (tty && spinning) {
+            // Wipe the half-drawn spinner line so a following console.error stack
+            // starts clean, and restore the cursor we hid in startSpinner().
+            write(`${exports.ANSI.cursorStart}${exports.ANSI.clearLine}`);
+            write(exports.ANSI.showCursor);
+        }
+        activeLayer = null;
+    };
+    return { beginLayer, endLayer, note, finish, dispose };
+}
+//# sourceMappingURL=boot-reporter.js.map

package/dist/util/boot-reporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot-reporter.js","sourceRoot":"","sources":["../../src/util/boot-reporter.ts"],"names":[],"mappings":"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"}

package/dist/util/collab-cap.d.ts

@@ -0,0 +1,39 @@
+import type Crowi from '../crowi';
+import { type EditorCapCounter } from './editor-cap-counter';
+/**
+ * Resolve (and cache) the process-wide editor cap counter. Lazy so
+ * the api process can boot without an immediate Redis round-trip;
+ * the counter materialises on the first call (= first yjs-token
+ * issuance or first WebSocket attach, whichever comes first).
+ *
+ * Concurrent-first-caller dedup: the cache stores the in-flight
+ * `Promise<EditorCapCounter>`, not the resolved counter. Any
+ * concurrent caller observes the cached promise and races onto the
+ * same counter rather than each opening their own.
+ *
+ * Exported so the embedded Hocuspocus engine (`collab/attach.ts`)
+ * and the wsToken HTTP handler share **one** counter instance — same
+ * Redis keys, same in-process cache, same future Lua-atomic upgrade
+ * path.
+ */
+export declare function getEditorCapCounter(crowi: Crowi): Promise<EditorCapCounter>;
+/**
+ * Probe the editor cap for the given page. Returns `{ readonly: true }`
+ * when the current Redis-tracked editor count is at or above the cap.
+ *
+ * Phase 9 signature change: now takes a `Crowi` instance so the
+ * counter can be built against the shared `crowi.redis` client. The
+ * collab attach helper builds its own counter independently with
+ * the same client, but both wrappers eventually flow through the
+ * same Redis keys.
+ */
+export declare const checkEditorCap: (crowi: Crowi, pageId: string) => Promise<{
+    readonly: boolean;
+}>;
+/**
+ * Test helper — set the cached counter or reset to lazy. Pass a
+ * pre-built fake to exercise the cap-reached path without Redis; pass
+ * `null` to clear the cache so a fresh env is honoured on the next
+ * call.
+ */
+export declare const _setEditorCapCounterForTesting: (counter: EditorCapCounter | null) => void;

package/dist/util/collab-cap.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._setEditorCapCounterForTesting = exports.checkEditorCap = void 0;
+exports.getEditorCapCounter = getEditorCapCounter;
+const editor_cap_counter_1 = require("./editor-cap-counter");
+/**
+ * Editor cap check used by the wsToken issuance endpoint
+ * (`GET /api/v2/pages/:id/yjs-token`, Phase 2). RFC-0003 Phase 6
+ * promotes the Phase 2 stub to a Redis-backed check via the shared
+ * `editor-cap-counter` util.
+ *
+ * Why a thin wrapper here instead of using the counter directly in
+ * the route handler? The wsToken handler shouldn't know about Redis
+ * — it asks a domain-shaped question ("is this connection at cap?")
+ * and gets a boolean back. Keeping the swap-point isolated in this
+ * file means the Phase 9 same-process attach work touches:
+ *
+ *   - `util/editor-cap-counter.ts` (signature: `redisOpts` → `redisClient`)
+ *   - `util/collab-cap.ts`         (this — reads `crowi.redis`)
+ *
+ * The route handler (`routes/ts-rest/page-collab.ts`) is unchanged
+ * apart from passing `crowi` into the call.
+ *
+ * `peek` (read-only) is used here on purpose: a `tryAcquire` would
+ * SADD a token-issuance attempt that may never actually connect
+ * (browser tab closed before the WebSocket handshake), inflating the
+ * count. The real acquire happens later in `onAuthenticate` (Phase 6
+ * defence-in-depth on the embedded Hocuspocus side; see
+ * `src/collab/attach.ts`), where the WebSocket has already opened
+ * and we have a real `socketId` to scope the SADD entry to.
+ *
+ * Fail-open posture: if `crowi.redis` is null (REDIS_URL unset) the
+ * underlying counter returns 0 from `peek` and this helper falls
+ * through to `{ readonly: false }`. The cap is a soft limit by
+ * design (spec §Phase 6); a Redis outage must not lock out *all*
+ * editors.
+ */
+let cachedCounter = null;
+/**
+ * Resolve (and cache) the process-wide editor cap counter. Lazy so
+ * the api process can boot without an immediate Redis round-trip;
+ * the counter materialises on the first call (= first yjs-token
+ * issuance or first WebSocket attach, whichever comes first).
+ *
+ * Concurrent-first-caller dedup: the cache stores the in-flight
+ * `Promise<EditorCapCounter>`, not the resolved counter. Any
+ * concurrent caller observes the cached promise and races onto the
+ * same counter rather than each opening their own.
+ *
+ * Exported so the embedded Hocuspocus engine (`collab/attach.ts`)
+ * and the wsToken HTTP handler share **one** counter instance — same
+ * Redis keys, same in-process cache, same future Lua-atomic upgrade
+ * path.
+ */
+function getEditorCapCounter(crowi) {
+    if (cachedCounter)
+        return cachedCounter;
+    cachedCounter = (0, editor_cap_counter_1.createEditorCapCounter)({
+        redisClient: crowi.redis ?? null,
+        maxEditorsPerPage: (0, editor_cap_counter_1.parseCapEnv)(process.env.COLLAB_MAX_EDITORS_PER_PAGE),
+    });
+    return cachedCounter;
+}
+/**
+ * Probe the editor cap for the given page. Returns `{ readonly: true }`
+ * when the current Redis-tracked editor count is at or above the cap.
+ *
+ * Phase 9 signature change: now takes a `Crowi` instance so the
+ * counter can be built against the shared `crowi.redis` client. The
+ * collab attach helper builds its own counter independently with
+ * the same client, but both wrappers eventually flow through the
+ * same Redis keys.
+ */
+const checkEditorCap = async (crowi, pageId) => {
+    const counter = await getEditorCapCounter(crowi);
+    const { count, cap } = await counter.peek(pageId);
+    return { readonly: count >= cap };
+};
+exports.checkEditorCap = checkEditorCap;
+/**
+ * Test helper — set the cached counter or reset to lazy. Pass a
+ * pre-built fake to exercise the cap-reached path without Redis; pass
+ * `null` to clear the cache so a fresh env is honoured on the next
+ * call.
+ */
+const _setEditorCapCounterForTesting = (counter) => {
+    cachedCounter = counter == null ? null : Promise.resolve(counter);
+};
+exports._setEditorCapCounterForTesting = _setEditorCapCounterForTesting;
+//# sourceMappingURL=collab-cap.js.map

package/dist/util/collab-cap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collab-cap.js","sourceRoot":"","sources":["../../src/util/collab-cap.ts"],"names":[],"mappings":";;;AAsDA,kDAOC;AA5DD,6DAAkG;AAElG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,IAAI,aAAa,GAAqC,IAAI,CAAC;AAE3D;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,mBAAmB,CAAC,KAAY;IAC9C,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IACxC,aAAa,GAAG,IAAA,2CAAsB,EAAC;QACrC,WAAW,EAAE,KAAK,CAAC,KAAK,IAAI,IAAI;QAChC,iBAAiB,EAAE,IAAA,gCAAW,EAAC,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC;KACxE,CAAC,CAAC;IACH,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;;;;;;;GASG;AACI,MAAM,cAAc,GAAG,KAAK,EAAE,KAAY,EAAE,MAAc,EAAkC,EAAE;IACnG,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACjD,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClD,OAAO,EAAE,QAAQ,EAAE,KAAK,IAAI,GAAG,EAAE,CAAC;AACpC,CAAC,CAAC;AAJW,QAAA,cAAc,kBAIzB;AAEF;;;;;GAKG;AACI,MAAM,8BAA8B,GAAG,CAAC,OAAgC,EAAQ,EAAE;IACvF,aAAa,GAAG,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AACpE,CAAC,CAAC;AAFW,QAAA,8BAA8B,kCAEzC"}

package/dist/util/crypto.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Provides the master key used to encrypt / decrypt sensitive values at rest.
+ * Default implementation reads `CROWI_ENCRYPTION_KEY` (base64-encoded 32 bytes).
+ * Phase 3 will add KMS-backed providers (AWS / GCP) using the same interface.
+ */
+export interface KeyProvider {
+    /** Throws when the key is not configured or malformed. */
+    getKey(): Buffer;
+}
+/** Swap the active key provider. Test-only or for Phase 3 KMS plumbing. */
+export declare function setKeyProvider(provider: KeyProvider): void;
+/** Reset to the default env-based provider. Test helper. */
+export declare function resetKeyProvider(): void;
+/**
+ * Whether the current provider can produce a usable key. Service-layer code
+ * should treat encryption as best-effort: if false, fall back to plaintext
+ * (= legacy behaviour) so a missing key never crashes the app.
+ */
+export declare function isEncryptionConfigured(): boolean;
+/** True when the value carries our envelope prefix. */
+export declare function isEncrypted(value: unknown): value is string;
+/**
+ * Encrypt a UTF-8 string with AES-256-GCM. Format:
+ *   enc:v1:<base64(iv)>:<base64(authTag)>:<base64(ciphertext)>
+ * IV is regenerated per call so the same plaintext yields different ciphertexts
+ * (= non-deterministic, not suitable for equality lookups).
+ */
+export declare function encrypt(plain: string): string;
+/**
+ * Decrypt a value produced by `encrypt()`. Values without the `enc:v1:` prefix
+ * are returned untouched so legacy plaintext rows keep working until they are
+ * migrated by the admin re-encryption flow.
+ *
+ * Throws on tag/IV mismatch (= tampering or wrong key) so callers can distinguish
+ * a real auth failure from a legacy passthrough.
+ */
+export declare function decrypt(value: string): string;
+/** Generate a fresh 32-byte master key, base64-encoded. CLI helper. */
+export declare function generateKey(): string;

package/dist/util/crypto.js

@@ -0,0 +1,105 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setKeyProvider = setKeyProvider;
+exports.resetKeyProvider = resetKeyProvider;
+exports.isEncryptionConfigured = isEncryptionConfigured;
+exports.isEncrypted = isEncrypted;
+exports.encrypt = encrypt;
+exports.decrypt = decrypt;
+exports.generateKey = generateKey;
+const crypto_1 = __importDefault(require("crypto"));
+const ALGORITHM = 'aes-256-gcm';
+const PREFIX = 'enc:v1:';
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+class EnvKeyProvider {
+    cachedKey = null;
+    getKey() {
+        if (this.cachedKey)
+            return this.cachedKey;
+        const raw = process.env.CROWI_ENCRYPTION_KEY;
+        if (!raw) {
+            throw new Error('CROWI_ENCRYPTION_KEY is not configured. Generate one with `openssl rand -base64 32`.');
+        }
+        const buf = Buffer.from(raw, 'base64');
+        if (buf.length !== KEY_BYTES) {
+            throw new Error(`CROWI_ENCRYPTION_KEY must decode to ${KEY_BYTES} bytes (got ${buf.length})`);
+        }
+        this.cachedKey = buf;
+        return buf;
+    }
+}
+let keyProvider = new EnvKeyProvider();
+/** Swap the active key provider. Test-only or for Phase 3 KMS plumbing. */
+function setKeyProvider(provider) {
+    keyProvider = provider;
+}
+/** Reset to the default env-based provider. Test helper. */
+function resetKeyProvider() {
+    keyProvider = new EnvKeyProvider();
+}
+/**
+ * Whether the current provider can produce a usable key. Service-layer code
+ * should treat encryption as best-effort: if false, fall back to plaintext
+ * (= legacy behaviour) so a missing key never crashes the app.
+ */
+function isEncryptionConfigured() {
+    try {
+        keyProvider.getKey();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** True when the value carries our envelope prefix. */
+function isEncrypted(value) {
+    return typeof value === 'string' && value.startsWith(PREFIX);
+}
+/**
+ * Encrypt a UTF-8 string with AES-256-GCM. Format:
+ *   enc:v1:<base64(iv)>:<base64(authTag)>:<base64(ciphertext)>
+ * IV is regenerated per call so the same plaintext yields different ciphertexts
+ * (= non-deterministic, not suitable for equality lookups).
+ */
+function encrypt(plain) {
+    if (typeof plain !== 'string') {
+        throw new TypeError('encrypt() expects a string');
+    }
+    const iv = crypto_1.default.randomBytes(IV_BYTES);
+    const cipher = crypto_1.default.createCipheriv(ALGORITHM, keyProvider.getKey(), iv);
+    const ct = Buffer.concat([cipher.update(plain, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return `${PREFIX}${iv.toString('base64')}:${tag.toString('base64')}:${ct.toString('base64')}`;
+}
+/**
+ * Decrypt a value produced by `encrypt()`. Values without the `enc:v1:` prefix
+ * are returned untouched so legacy plaintext rows keep working until they are
+ * migrated by the admin re-encryption flow.
+ *
+ * Throws on tag/IV mismatch (= tampering or wrong key) so callers can distinguish
+ * a real auth failure from a legacy passthrough.
+ */
+function decrypt(value) {
+    if (!isEncrypted(value)) {
+        return value;
+    }
+    const body = value.slice(PREFIX.length);
+    const parts = body.split(':');
+    if (parts.length !== 3) {
+        throw new Error('Malformed encrypted value: expected enc:v1:<iv>:<tag>:<ct>');
+    }
+    const [ivB64, tagB64, ctB64] = parts;
+    const decipher = crypto_1.default.createDecipheriv(ALGORITHM, keyProvider.getKey(), Buffer.from(ivB64, 'base64'));
+    decipher.setAuthTag(Buffer.from(tagB64, 'base64'));
+    const pt = Buffer.concat([decipher.update(Buffer.from(ctB64, 'base64')), decipher.final()]);
+    return pt.toString('utf8');
+}
+/** Generate a fresh 32-byte master key, base64-encoded. CLI helper. */
+function generateKey() {
+    return crypto_1.default.randomBytes(KEY_BYTES).toString('base64');
+}
+//# sourceMappingURL=crypto.js.map

package/dist/util/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../../src/util/crypto.ts"],"names":[],"mappings":"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"}

package/dist/util/dedup-users.d.ts

@@ -0,0 +1,96 @@
+/**
+ * feature-user-identity-uniqueness §c / §e — minimal user merge + reference
+ * reassign, used by the `user-unique-prepare` preflight migration to resolve
+ * existing duplicate users before the plain unique indexes are built.
+ *
+ * This is the *minimal* merge (uniqueness spec §2 "案2A"): just enough to
+ * reassign every ownership reference from a losing duplicate onto the surviving
+ * one and delete the loser. The full operator-facing `crowi-admin user merge`
+ * tool (uniqueness spec §e) is a separate task and not built here, but the
+ * reference-reassign set is the same so this routine is the shared core.
+ *
+ * The reassign set is the full collection/field set that had to be fixed by
+ * hand during the 2026-05 incident (uniqueness spec §c):
+ *
+ *   pages.creator, pages.lastUpdateUser                       (scalar)
+ *   pages.grantedUsers[], pages.liker[], pages.seenUsers[]    (array)
+ *   revisions.author, revisions.savedBy                       (scalar)
+ *   revisions.contributors[]                                  (array)
+ *   comments.creator, bookmarks.user, attachments.creator,
+ *   shares.creator, watchers.user, activities.user,
+ *   notifications.user, updateposts.creator                  (scalar)
+ *
+ * Array fields use `$addToSet(to)` then `$pull(from)` so the surviving id
+ * appears at most once. `bookmarks` carries a unique `{ page, user }` index, so
+ * a losing user's bookmark of a page the survivor already bookmarked would
+ * collide on reassign — those losing rows are deleted first.
+ *
+ * Operations run on the raw mongo driver (`db.collection(...)`) rather than
+ * Mongoose models so this works uniformly across every collection (some of
+ * which aren't registered as models in every context) and stays close to the
+ * shape a future PostgreSQL port would take.
+ */
+import type { mongo } from 'mongoose';
+import type { MigrationLogger } from '../migration/types';
+type Db = mongo.Db;
+type ObjectId = mongo.ObjectId;
+/** A scalar (`$set`) reference: one field on one collection holding a single user id. */
+interface ScalarRef {
+    collection: string;
+    field: string;
+}
+/** An array (`$addToSet`/`$pull`) reference: a field holding a list of user ids. */
+interface ArrayRef {
+    collection: string;
+    field: string;
+}
+/**
+ * The full scalar reference set (uniqueness spec §c). `from` is matched by
+ * exact equality; reassigned to `to` via `$set`.
+ */
+export declare const SCALAR_USER_REFS: readonly ScalarRef[];
+/** The full array reference set (uniqueness spec §c). */
+export declare const ARRAY_USER_REFS: readonly ArrayRef[];
+export interface ReassignResult {
+    /** Per-collection.field count of documents updated (scalar + array). */
+    reassigned: Record<string, number>;
+    /** Rows deleted to avoid a compound-unique collision (e.g. duplicate bookmarks). */
+    deletedConflicting: number;
+}
+/**
+ * Reassign every ownership reference from `from` to `to`. Does not touch the
+ * `users` collection itself (the caller deletes/keeps the user docs). Pure data
+ * movement — safe to call repeatedly (idempotent: a second run finds no `from`
+ * references left).
+ */
+export declare function reassignUserReferences(db: Db, from: ObjectId, to: ObjectId, logger?: MigrationLogger): Promise<ReassignResult>;
+/** A single duplicate group: the user kept plus the users merged away. */
+export interface MergeGroup {
+    keep: ObjectId;
+    remove: ObjectId[];
+}
+export interface DedupResult {
+    groupsMerged: number;
+    usersRemoved: number;
+    reassigned: Record<string, number>;
+    deletedConflicting: number;
+}
+/**
+ * Merge each group: reassign every removed user's references onto `keep`, then
+ * delete the removed user docs. `dryRun` reports the would-be effect without
+ * writing.
+ */
+export declare function mergeUserGroups(db: Db, groups: readonly MergeGroup[], opts: {
+    dryRun: boolean;
+    logger?: MigrationLogger;
+}): Promise<DedupResult>;
+/**
+ * The policy for choosing which user in a duplicate group survives
+ * (uniqueness spec §c): keep the one with the most content, breaking ties by
+ * oldest `createdAt`. "Content" is approximated by the number of pages the user
+ * created — the dominant signal in the incident and cheap to count.
+ *
+ * Returns the group with `keep` set to the winner and `remove` to the rest.
+ */
+export declare function chooseSurvivor(db: Db, candidateIds: readonly ObjectId[]): Promise<MergeGroup>;
+export {};