@crowi/api 2.0.0-alpha.0

package/dist/util/page-response.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pageToResponse = exports.computeRevisionRenderArtifactsAsync = exports.resolveRevisionMeta = exports.toRevisionResponse = exports.isPopulatedRevision = void 0;
+const revision_1 = require("../models/revision");
+const version_1 = require("../renderer/version");
+const ts_rest_helpers_1 = require("./ts-rest-helpers");
+/**
+ * Heuristic: a `revision` field is populated when it has the `_id` + `path`
+ * + `body` triplet. Plain `ObjectId` refs only carry `_id`.
+ */
+const isPopulatedRevision = (value) => {
+    return typeof value === 'object' && value !== null && '_id' in value && 'path' in value && 'body' in value;
+};
+exports.isPopulatedRevision = isPopulatedRevision;
+// Epoch fallback (not "now") so a document missing timestamps doesn't
+// look like it was just created — schema only requires the field be set.
+const EPOCH_ISO = new Date(0).toISOString();
+const toRevisionResponse = (revision, options = {}) => ({
+    _id: revision._id.toString(),
+    path: revision.path,
+    body: revision.body,
+    format: revision.format || 'markdown',
+    author: revision.author ? (0, ts_rest_helpers_1.toPageUser)(revision.author) : null,
+    ...(revision.editVia !== undefined ? { editVia: revision.editVia } : {}),
+    createdAt: (0, ts_rest_helpers_1.toISOStringOrNull)(revision.createdAt) || EPOCH_ISO,
+    // Sync path: only emits stored meta + renderedAst. Detail endpoints
+    // (getPage, getRevision) compose with `computeRevisionRenderArtifactsAsync`
+    // afterwards to fold in the on-the-fly fallback for legacy revisions.
+    meta: (0, exports.resolveRevisionMeta)(revision.meta, options.withMeta),
+    ...(options.withRenderedAst ? { renderedAst: revision.renderedAst, rendererVersion: revision.rendererVersion } : {}),
+});
+exports.toRevisionResponse = toRevisionResponse;
+const resolveRevisionMeta = (stored, emit) => {
+    if (!emit)
+        return undefined;
+    if (!stored)
+        return undefined;
+    const out = pickStoredMeta(stored);
+    return Object.keys(out).length > 0 ? out : undefined;
+};
+exports.resolveRevisionMeta = resolveRevisionMeta;
+// Avoids leaking Mongoose internals (the document carries `$__` etc.)
+// into the response shape.
+function pickStoredMeta(stored) {
+    const out = {};
+    if (stored.toc !== undefined)
+        out.toc = stored.toc;
+    if (stored.wikiLinks !== undefined)
+        out.wikiLinks = stored.wikiLinks;
+    if (stored.mentions !== undefined)
+        out.mentions = stored.mentions;
+    if (stored.codeBlockLanguages !== undefined)
+        out.codeBlockLanguages = stored.codeBlockLanguages;
+    return out;
+}
+/**
+ * Async fallback compute for revision render artifacts (meta +
+ * renderedAst). Detail endpoints (getPage, getRevision) call this AFTER
+ * `pageToResponse` so the projection path stays sync; meta + AST get
+ * attached to the populated revision response in one go.
+ *
+ * Why one call instead of two: legacy revisions (Phase 1: only `toc`
+ * stored / Phase 2: meta but no `renderedAst`) would otherwise trigger
+ * back-to-back `runMetadata` + `runRender` invocations, each running a
+ * full parse+transform+shiki pipeline on the same body. `runRender`
+ * already produces both, so fold the calls into one and pull the
+ * needed pieces out.
+ *
+ * Stored values stay authoritative on merge: Phase 1's `toc` (the
+ * anchor ids the heading stamper aligns against) wins over recomputed
+ * ones, and a stored `renderedAst` is returned verbatim without
+ * re-rendering.
+ */
+const computeRevisionRenderArtifactsAsync = async (crowi, storedMeta, storedAst, body, storedRendererVersion, pageId) => {
+    const fromStored = storedMeta ? pickStoredMeta(storedMeta) : {};
+    // Phase 2-written revisions persist all 4 meta fields (even empty
+    // arrays); the presence of these 3 is the marker that no fallback
+    // is needed for meta.
+    const metaIsComplete = fromStored.wikiLinks !== undefined && fromStored.mentions !== undefined && fromStored.codeBlockLanguages !== undefined;
+    const astIsStored = storedAst !== undefined;
+    // RFC-0002 round 3.1: a stored `rendererVersion` that does NOT match
+    // the running pipeline marks the AST as stale. A missing
+    // `rendererVersion` (revisions saved before this field landed) is
+    // treated as "trust the stored AST" — re-rendering every pre-existing
+    // revision on every read would be unaffordable, and the user-facing
+    // workaround (re-save the page) is already documented. Once
+    // `renderer:rebuild` lands (RFC-0008), operators can backfill.
+    const astIsFresh = astIsStored && (storedRendererVersion === undefined || storedRendererVersion === version_1.RENDERER_PIPELINE_VERSION);
+    if (metaIsComplete && astIsFresh) {
+        return {
+            meta: Object.keys(fromStored).length > 0 ? fromStored : undefined,
+            renderedAst: storedAst,
+        };
+    }
+    if (!body) {
+        return {
+            meta: metaIsComplete && Object.keys(fromStored).length > 0 ? fromStored : undefined,
+            renderedAst: astIsFresh ? storedAst : undefined,
+        };
+    }
+    // `pageId` threads through so the Phase 4+ plugin-dispatch transforms
+    // (embed-tag / url-inline-expand / code-block) can fire on the
+    // fallback path the same way they do at save time. Callers that
+    // genuinely don't know the page (unit tests, orphan revision bodies)
+    // can omit it — dispatch then degrades to no-op and the `code` /
+    // `@[tag](url)` nodes survive as plain text.
+    const { metadata, renderedAst } = await crowi.getRenderer().runRender(body, { mode: 'read', pageId });
+    const mergedMeta = { ...pickStoredMeta((0, revision_1.metadataToRevisionMeta)(metadata)), ...fromStored };
+    return {
+        meta: Object.keys(mergedMeta).length > 0 ? mergedMeta : undefined,
+        renderedAst: astIsFresh ? storedAst : renderedAst,
+    };
+};
+exports.computeRevisionRenderArtifactsAsync = computeRevisionRenderArtifactsAsync;
+/**
+ * Project a populated Page document (or plain `PageLike`) into the contract
+ * Page shape. Unpopulated refs collapse safely:
+ *   - revision: ObjectId-ref → undefined
+ *   - creator / lastUpdateUser: ObjectId-ref → null
+ *
+ * Returns `any` because the runtime shape satisfies either `Page` or
+ * `PageWithRevision` depending on whether revision was populated; ts-rest
+ * contracts pin one or the other and each handler narrows at its return.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: see jsdoc
+const pageToResponse = (page, options = {}) => {
+    const pageObj = typeof page.toObject === 'function' ? page.toObject() : page;
+    // likerCount / seenUsersCount are dynamic properties set by populatePageData
+    // on the Mongoose document; toObject() drops them, so read off the original.
+    const dynamic = page;
+    return {
+        _id: (0, ts_rest_helpers_1.toStringId)(pageObj._id),
+        path: pageObj.path,
+        revision: pageObj.revision && (0, exports.isPopulatedRevision)(pageObj.revision)
+            ? (0, exports.toRevisionResponse)(pageObj.revision, { withMeta: options.withMeta, withRenderedAst: options.withRenderedAst })
+            : undefined,
+        redirectTo: pageObj.redirectTo || null,
+        status: pageObj.status || undefined,
+        grant: pageObj.grant,
+        grantedUsers: pageObj.grantedUsers?.map(ts_rest_helpers_1.toStringId) || [],
+        creator: pageObj.creator && (0, ts_rest_helpers_1.isPopulatedUser)(pageObj.creator) ? (0, ts_rest_helpers_1.toPageUser)(pageObj.creator) : null,
+        lastUpdateUser: pageObj.lastUpdateUser && (0, ts_rest_helpers_1.isPopulatedUser)(pageObj.lastUpdateUser) ? (0, ts_rest_helpers_1.toPageUser)(pageObj.lastUpdateUser) : null,
+        liker: pageObj.liker?.map(ts_rest_helpers_1.toStringId) || [],
+        commentCount: pageObj.commentCount || 0,
+        extended: pageObj.extended,
+        createdAt: (0, ts_rest_helpers_1.toISOStringOrNull)(pageObj.createdAt) || EPOCH_ISO,
+        updatedAt: (0, ts_rest_helpers_1.toISOStringOrNull)(pageObj.updatedAt) || undefined,
+        latestRevision: pageObj.latestRevision ? (0, ts_rest_helpers_1.toStringId)(pageObj.latestRevision) : undefined,
+        likerCount: dynamic.likerCount,
+        seenUsersCount: dynamic.seenUsersCount,
+    };
+};
+exports.pageToResponse = pageToResponse;
+//# sourceMappingURL=page-response.js.map

package/dist/util/page-response.js.map

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

package/dist/util/page-search-index.d.ts

@@ -0,0 +1,19 @@
+import type Crowi from '../crowi';
+import { type PageLike } from './page-response';
+/**
+ * Push a page into the active search driver after a save / rename.
+ * Pages that have become redirects or `status='deleted'` are removed
+ * from the index instead — mirrors `shouldIndex()` in the ES driver's
+ * rebuild path.
+ *
+ * RFC-0004: `status='draft'` pages are likewise kept out of the index
+ * — a draft is visible only to its author, and search results have no
+ * per-viewer draft-author filter. When the author publishes (Phase 3),
+ * the resulting `update` event re-runs this helper with
+ * `status='published'` and the page is indexed normally.
+ *
+ * Fire-and-forget at the call site: the helper logs and swallows
+ * errors so a search-cluster outage never breaks page CRUD.
+ */
+export declare function indexPageInSearch(crowi: Crowi, page: PageLike): Promise<void>;
+export declare function removePageFromSearch(crowi: Crowi, page: PageLike): Promise<void>;

package/dist/util/page-search-index.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.indexPageInSearch = indexPageInSearch;
+exports.removePageFromSearch = removePageFromSearch;
+const page_1 = require("../models/page");
+const debug_1 = __importDefault(require("debug"));
+const ts_rest_helpers_1 = require("./ts-rest-helpers");
+const page_response_1 = require("./page-response");
+const debug = (0, debug_1.default)('crowi:util:page-search-index');
+/**
+ * Push a page into the active search driver after a save / rename.
+ * Pages that have become redirects or `status='deleted'` are removed
+ * from the index instead — mirrors `shouldIndex()` in the ES driver's
+ * rebuild path.
+ *
+ * RFC-0004: `status='draft'` pages are likewise kept out of the index
+ * — a draft is visible only to its author, and search results have no
+ * per-viewer draft-author filter. When the author publishes (Phase 3),
+ * the resulting `update` event re-runs this helper with
+ * `status='published'` and the page is indexed normally.
+ *
+ * Fire-and-forget at the call site: the helper logs and swallows
+ * errors so a search-cluster outage never breaks page CRUD.
+ */
+async function indexPageInSearch(crowi, page) {
+    const searcher = crowi.getSearcher();
+    if (!searcher)
+        return;
+    const id = (0, ts_rest_helpers_1.toStringId)(page._id);
+    try {
+        if (page.redirectTo || page.status === page_1.STATUS_DELETED || page.status === page_1.STATUS_DRAFT) {
+            await searcher.remove(id);
+            return;
+        }
+        // The rename path emits 'update' with revision still as an
+        // ObjectId ref, so refetch when the payload isn't already
+        // carrying a populated revision body.
+        const target = (0, page_response_1.isPopulatedRevision)(page.revision) ? page : await refetchPopulated(crowi, id);
+        if (!target) {
+            await searcher.remove(id);
+            return;
+        }
+        if (target.redirectTo || target.status === page_1.STATUS_DELETED || target.status === page_1.STATUS_DRAFT) {
+            await searcher.remove(id);
+            return;
+        }
+        if (!(0, page_response_1.isPopulatedRevision)(target.revision) || !target.revision.body) {
+            debug('skip: no revision body for page %s', id);
+            return;
+        }
+        const creator = (0, ts_rest_helpers_1.isPopulatedUser)(target.creator) ? target.creator : null;
+        const doc = {
+            id,
+            path: target.path,
+            body: target.revision.body,
+            meta: {
+                username: creator?.username,
+                grant: target.grant,
+                granted_users: (target.grantedUsers ?? []).map(ts_rest_helpers_1.toStringId),
+                comment_count: target.commentCount ?? 0,
+                like_count: target.liker?.length ?? 0,
+                created_at: target.createdAt,
+                updated_at: target.updatedAt,
+            },
+        };
+        await searcher.index(doc);
+    }
+    catch (err) {
+        debug('search index failed for page %s: %s', id, err.message);
+    }
+}
+async function removePageFromSearch(crowi, page) {
+    const searcher = crowi.getSearcher();
+    if (!searcher)
+        return;
+    const id = (0, ts_rest_helpers_1.toStringId)(page._id);
+    try {
+        await searcher.remove(id);
+    }
+    catch (err) {
+        debug('search remove failed for page %s: %s', id, err.message);
+    }
+}
+async function refetchPopulated(crowi, id) {
+    const Page = crowi.model('Page');
+    return (await Page.findById(id).populate('revision').populate('creator'));
+}
+//# sourceMappingURL=page-search-index.js.map

package/dist/util/page-search-index.js.map

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

package/dist/util/page-status-migration.d.ts

@@ -0,0 +1,23 @@
+import type Crowi from '../crowi';
+/**
+ * RFC-0004 backfill: stamp `status: 'published'` onto every legacy
+ * `Page` row that has no `status` (the field is missing, or stored as
+ * `null`).
+ *
+ * Why this is needed: RFC-0004 introduces a first-class `draft` state
+ * and the listing / search / backlink queries now branch on
+ * `Page.status`. Pages created before the `status` field existed read
+ * back as `null`; `Page.isPublished()` already treats `null` as
+ * published for back-compat, but the query-level `$or` filters and the
+ * collab draft gate are clearer — and future-proof against a stricter
+ * `required: true` — when every row carries an explicit value.
+ *
+ * Idempotent: the filter only matches rows that are still unset, so a
+ * second run touches nothing. Pages already `published` / `draft` /
+ * `deleted` / `deprecated` / `wip` are left exactly as they are — in
+ * particular this never rewrites a `draft` back to `published`, which
+ * would violate the one-way transition rule.
+ *
+ * Returns the number of rows updated, so the boot log can report it.
+ */
+export declare function runPageStatusMigration(crowi: Crowi): Promise<number>;

package/dist/util/page-status-migration.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPageStatusMigration = runPageStatusMigration;
+const debug_1 = __importDefault(require("debug"));
+const page_1 = require("../models/page");
+const debug = (0, debug_1.default)('crowi:util:page-status-migration');
+/**
+ * RFC-0004 backfill: stamp `status: 'published'` onto every legacy
+ * `Page` row that has no `status` (the field is missing, or stored as
+ * `null`).
+ *
+ * Why this is needed: RFC-0004 introduces a first-class `draft` state
+ * and the listing / search / backlink queries now branch on
+ * `Page.status`. Pages created before the `status` field existed read
+ * back as `null`; `Page.isPublished()` already treats `null` as
+ * published for back-compat, but the query-level `$or` filters and the
+ * collab draft gate are clearer — and future-proof against a stricter
+ * `required: true` — when every row carries an explicit value.
+ *
+ * Idempotent: the filter only matches rows that are still unset, so a
+ * second run touches nothing. Pages already `published` / `draft` /
+ * `deleted` / `deprecated` / `wip` are left exactly as they are — in
+ * particular this never rewrites a `draft` back to `published`, which
+ * would violate the one-way transition rule.
+ *
+ * Returns the number of rows updated, so the boot log can report it.
+ */
+async function runPageStatusMigration(crowi) {
+    const Page = crowi.model('Page');
+    // `status: null` matches both an explicit null and a missing field
+    // in MongoDB query semantics, so a single condition covers every
+    // legacy shape.
+    const result = await Page.updateMany({ status: null }, { $set: { status: page_1.STATUS_PUBLISHED } });
+    // Mongoose's UpdateResult exposes `modifiedCount`; fall back to 0 for
+    // any driver shape that omits it.
+    const modified = result.modifiedCount ?? 0;
+    if (modified > 0) {
+        console.log(`[crowi] Backfilled status='published' on ${modified} legacy page row(s).`);
+    }
+    else {
+        debug('no legacy pages without status — nothing to migrate');
+    }
+    return modified;
+}
+//# sourceMappingURL=page-status-migration.js.map

package/dist/util/page-status-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-status-migration.js","sourceRoot":"","sources":["../../src/util/page-status-migration.ts"],"names":[],"mappings":";;;;;AA2BA,wDAiBC;AA5CD,kDAA0B;AAE1B,0CAAmD;AAEnD,MAAM,KAAK,GAAG,IAAA,eAAK,EAAC,kCAAkC,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;GAoBG;AACI,KAAK,UAAU,sBAAsB,CAAC,KAAY;IACvD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAEjC,mEAAmE;IACnE,iEAAiE;IACjE,gBAAgB;IAChB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,uBAAgB,EAAE,EAAE,CAAC,CAAC;IAE/F,sEAAsE;IACtE,kCAAkC;IAClC,MAAM,QAAQ,GAAI,MAAqC,CAAC,aAAa,IAAI,CAAC,CAAC;IAC3E,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,OAAO,CAAC,GAAG,CAAC,4CAA4C,QAAQ,sBAAsB,CAAC,CAAC;IAC1F,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,qDAAqD,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/util/path.d.ts

@@ -0,0 +1,2 @@
+export declare const encodeSpace: (s: any) => any;
+export declare const decodeSpace: (s: any) => any;

package/dist/util/path.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeSpace = exports.encodeSpace = void 0;
+const encodeSpace = (s) => {
+    return s.replace(/ /g, '+');
+};
+exports.encodeSpace = encodeSpace;
+const decodeSpace = (s) => {
+    return s.replace(/\+/g, ' ');
+};
+exports.decodeSpace = decodeSpace;
+//# sourceMappingURL=path.js.map

package/dist/util/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/util/path.ts"],"names":[],"mappings":";;;AAAO,MAAM,WAAW,GAAG,CAAC,CAAC,EAAE,EAAE;IAC/B,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAC9B,CAAC,CAAC;AAFW,QAAA,WAAW,eAEtB;AAEK,MAAM,WAAW,GAAG,CAAC,CAAC,EAAE,EAAE;IAC/B,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAC/B,CAAC,CAAC;AAFW,QAAA,WAAW,eAEtB"}

package/dist/util/pkce.d.ts

@@ -0,0 +1,13 @@
+/**
+ * RFC 7636 PKCE — S256 code-challenge verification.
+ *
+ * The client sends `code_challenge = base64url(sha256(code_verifier))` at
+ * authorize time and the raw `code_verifier` at token time. We recompute
+ * the challenge from the verifier and compare. Only S256 is supported
+ * (RFC-0010 §Security — the `plain` method is rejected upstream so it is
+ * not handled here).
+ *
+ * The comparison is constant-time (`crypto.timingSafeEqual`) to avoid
+ * leaking how many leading bytes matched.
+ */
+export declare function verifyPkceS256(codeVerifier: string, codeChallenge: string): boolean;

package/dist/util/pkce.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyPkceS256 = verifyPkceS256;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+/**
+ * RFC 7636 PKCE — S256 code-challenge verification.
+ *
+ * The client sends `code_challenge = base64url(sha256(code_verifier))` at
+ * authorize time and the raw `code_verifier` at token time. We recompute
+ * the challenge from the verifier and compare. Only S256 is supported
+ * (RFC-0010 §Security — the `plain` method is rejected upstream so it is
+ * not handled here).
+ *
+ * The comparison is constant-time (`crypto.timingSafeEqual`) to avoid
+ * leaking how many leading bytes matched.
+ */
+function verifyPkceS256(codeVerifier, codeChallenge) {
+    const computed = node_crypto_1.default.createHash('sha256').update(codeVerifier).digest('base64url');
+    const a = Buffer.from(computed);
+    const b = Buffer.from(codeChallenge);
+    // timingSafeEqual throws on length mismatch — a length difference is
+    // already a definitive non-match, so short-circuit.
+    if (a.length !== b.length)
+        return false;
+    return node_crypto_1.default.timingSafeEqual(a, b);
+}
+//# sourceMappingURL=pkce.js.map

package/dist/util/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../../src/util/pkce.ts"],"names":[],"mappings":";;;;;AAcA,wCAQC;AAtBD,8DAAiC;AAEjC;;;;;;;;;;;GAWG;AACH,SAAgB,cAAc,CAAC,YAAoB,EAAE,aAAqB;IACxE,MAAM,QAAQ,GAAG,qBAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACtF,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACrC,qEAAqE;IACrE,oDAAoD;IACpD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,qBAAM,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACtC,CAAC"}

package/dist/util/presence-token.d.ts

@@ -0,0 +1,21 @@
+import { type PresenceTokenPayload } from '@crowi/api-contract';
+/** Claims signed into a presence token. */
+export interface PresenceTokenClaims {
+    userId: string;
+    pageId: string;
+}
+export interface SignPresenceTokenResult {
+    /** Compact JWT string presented by the browser on the WebSocket connect. */
+    token: string;
+    /** ISO 8601 expiry timestamp, mirrors `exp * 1000` as a Date. */
+    expiresAt: Date;
+}
+declare function buildPresenceTokenUtil(): {
+    signPresenceToken: (claims: PresenceTokenClaims) => SignPresenceTokenResult;
+    verifyPresenceToken: (token: string) => PresenceTokenPayload | null;
+    ttlSeconds: number;
+    issuer: string;
+};
+export type PresenceTokenUtil = ReturnType<typeof buildPresenceTokenUtil>;
+export declare function createPresenceTokenUtil(): PresenceTokenUtil;
+export {};

package/dist/util/presence-token.js

@@ -0,0 +1,120 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPresenceTokenUtil = createPresenceTokenUtil;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const api_contract_1 = require("@crowi/api-contract");
+const debug_1 = __importDefault(require("debug"));
+const debug = (0, debug_1.default)('crowi:util:presence-token');
+/**
+ * Issuer claim used to sign / verify presence tokens (RFC-0005).
+ *
+ * Deliberately distinct from the collab wsToken issuer
+ * (`'crowi-collab'`, see `util/ws-token.ts`) and the HTTP access/refresh
+ * token issuer (`'crowi'`). A leaked presence token must never be
+ * replayable against the collab WebSocket — `/collab` carries write
+ * access to the Y.Doc, `/presence` is read-only viewer tracking — so
+ * the two channels verify against different `iss` claims even though
+ * they share the same `WS_TOKEN_SECRET` key material.
+ */
+const PRESENCE_TOKEN_ISSUER = 'crowi-presence';
+/**
+ * Lifetime of an issued presence token. Five minutes mirrors the
+ * collab wsToken TTL: short enough that a leaked token has limited
+ * blast radius, long enough to cover reconnect storms. The browser
+ * uses `expiresAt` to proactively re-fetch before the WebSocket would
+ * otherwise be dropped.
+ */
+const PRESENCE_TOKEN_TTL_SECONDS = 300;
+/**
+ * Resolve the signing secret once per util instance.
+ *
+ * Presence reuses `WS_TOKEN_SECRET` rather than introducing a new env:
+ * the two token kinds are isolated by their `iss` claim, so sharing the
+ * key material is safe and keeps operators from having to distribute a
+ * second secret. When `WS_TOKEN_SECRET` is unset we generate a random
+ * in-memory secret and warn — single-instance dev still works, but
+ * process restarts invalidate outstanding tokens and multi-instance
+ * deployments cannot cross-verify.
+ */
+const resolvePresenceTokenSecret = () => {
+    const fromEnv = process.env.WS_TOKEN_SECRET;
+    if (fromEnv && fromEnv.length > 0) {
+        debug('presence token secret resolved from WS_TOKEN_SECRET');
+        return fromEnv;
+    }
+    const generated = node_crypto_1.default.randomBytes(32).toString('base64');
+    console.warn('[crowi] WS_TOKEN_SECRET is not set — generated a random in-memory secret for presence tokens. ' +
+        'Process restarts will invalidate outstanding presence tokens, and multi-instance deployments ' +
+        'will not be able to cross-verify them. Set WS_TOKEN_SECRET to a stable base64-encoded 32-byte ' +
+        'value (`openssl rand -base64 32`) in production.');
+    return generated;
+};
+/**
+ * Build a sign / verify pair bound to a single resolved secret.
+ *
+ * Memoised for the same reason `createWsTokenUtil` is: when
+ * `WS_TOKEN_SECRET` is unset, `resolvePresenceTokenSecret` mints a
+ * fresh random secret per call. Two `createPresenceTokenUtil()` calls
+ * would otherwise close over different secrets and the HTTP-sign /
+ * WebSocket-verify pair would silently break in dev.
+ */
+let cachedUtil = null;
+function buildPresenceTokenUtil() {
+    const secret = resolvePresenceTokenSecret();
+    /**
+     * Sign a presence token for the given claims. Returns the compact
+     * JWT plus the absolute ISO expiry; the route serialises the
+     * timestamp into `PresenceTokenResponseSchema.expiresAt`.
+     */
+    function signPresenceToken(claims) {
+        // Pin `iat` ourselves so the response's `expiresAt` is exactly the
+        // same instant as the JWT's `exp` claim.
+        const iat = Math.floor(Date.now() / 1000);
+        const exp = iat + PRESENCE_TOKEN_TTL_SECONDS;
+        const token = jsonwebtoken_1.default.sign({ ...claims, iat, exp }, secret, {
+            issuer: PRESENCE_TOKEN_ISSUER,
+            algorithm: 'HS256',
+        });
+        return { token, expiresAt: new Date(exp * 1000) };
+    }
+    /**
+     * Verify a presence token. Returns the validated payload, or `null`
+     * for any failure (expired, bad signature, wrong issuer, malformed
+     * claims). Callers must treat `null` as "reject the connection".
+     */
+    function verifyPresenceToken(token) {
+        try {
+            const decoded = jsonwebtoken_1.default.verify(token, secret, {
+                issuer: PRESENCE_TOKEN_ISSUER,
+                algorithms: ['HS256'],
+            });
+            const parsed = api_contract_1.PresenceTokenPayloadSchema.safeParse(decoded);
+            if (!parsed.success) {
+                debug('presence token payload failed schema validation:', parsed.error.issues);
+                return null;
+            }
+            return parsed.data;
+        }
+        catch (err) {
+            debug('presence token verification failed:', err.message);
+            return null;
+        }
+    }
+    return {
+        signPresenceToken,
+        verifyPresenceToken,
+        ttlSeconds: PRESENCE_TOKEN_TTL_SECONDS,
+        issuer: PRESENCE_TOKEN_ISSUER,
+    };
+}
+function createPresenceTokenUtil() {
+    if (cachedUtil === null) {
+        cachedUtil = buildPresenceTokenUtil();
+    }
+    return cachedUtil;
+}
+//# sourceMappingURL=presence-token.js.map

package/dist/util/presence-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence-token.js","sourceRoot":"","sources":["../../src/util/presence-token.ts"],"names":[],"mappings":";;;;;AAqIA,0DAKC;AA1ID,8DAAiC;AACjC,gEAA+B;AAC/B,sDAA4F;AAC5F,kDAA0B;AAE1B,MAAM,KAAK,GAAG,IAAA,eAAK,EAAC,2BAA2B,CAAC,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,qBAAqB,GAAG,gBAAgB,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAevC;;;;;;;;;;GAUG;AACH,MAAM,0BAA0B,GAAG,GAAW,EAAE;IAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAC5C,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,KAAK,CAAC,qDAAqD,CAAC,CAAC;QAC7D,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,SAAS,GAAG,qBAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC5D,OAAO,CAAC,IAAI,CACV,gGAAgG;QAC9F,+FAA+F;QAC/F,gGAAgG;QAChG,kDAAkD,CACrD,CAAC;IACF,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,IAAI,UAAU,GAAqD,IAAI,CAAC;AAExE,SAAS,sBAAsB;IAC7B,MAAM,MAAM,GAAG,0BAA0B,EAAE,CAAC;IAE5C;;;;OAIG;IACH,SAAS,iBAAiB,CAAC,MAA2B;QACpD,mEAAmE;QACnE,yCAAyC;QACzC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC1C,MAAM,GAAG,GAAG,GAAG,GAAG,0BAA0B,CAAC;QAC7C,MAAM,KAAK,GAAG,sBAAG,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE;YACtD,MAAM,EAAE,qBAAqB;YAC7B,SAAS,EAAE,OAAO;SACnB,CAAC,CAAC;QACH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC;IACpD,CAAC;IAED;;;;OAIG;IACH,SAAS,mBAAmB,CAAC,KAAa;QACxC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,sBAAG,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE;gBACxC,MAAM,EAAE,qBAAqB;gBAC7B,UAAU,EAAE,CAAC,OAAO,CAAC;aACtB,CAAC,CAAC;YACH,MAAM,MAAM,GAAG,yCAA0B,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YAC7D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpB,KAAK,CAAC,kDAAkD,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBAC/E,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO,MAAM,CAAC,IAAI,CAAC;QACrB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,KAAK,CAAC,qCAAqC,EAAG,GAAa,CAAC,OAAO,CAAC,CAAC;YACrE,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO;QACL,iBAAiB;QACjB,mBAAmB;QACnB,UAAU,EAAE,0BAA0B;QACtC,MAAM,EAAE,qBAAqB;KAC9B,CAAC;AACJ,CAAC;AAID,SAAgB,uBAAuB;IACrC,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,UAAU,GAAG,sBAAsB,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/util/rate-limit.d.ts

@@ -0,0 +1,67 @@
+/**
+ * RFC-0004 Phase 5 — generic per-user fixed-window rate limiter.
+ *
+ * Used by the autocomplete endpoints (60 req/min/user) and, from
+ * Phase 6, the attachment-upload endpoint (20 req/min/user). There was
+ * no shared rate-limit utility before RFC-0004, so this is new.
+ *
+ * Storage strategy:
+ *   - When a Redis client is supplied (multi-instance api deployment),
+ *     counters live in Redis so the limit is shared across replicas.
+ *     A fixed window keyed by `floor(now / windowMs)` keeps the logic
+ *     to one `INCR` + one `EXPIRE` — no Lua, no sorted sets.
+ *   - When no Redis client is supplied (single-instance dev), an
+ *     in-memory `Map` fallback applies the same fixed-window logic
+ *     within the process. Stale windows are pruned lazily on access
+ *     plus by a low-frequency sweep so the map cannot grow unbounded.
+ *
+ * Fail-open posture: if the Redis round-trip throws, the request is
+ * allowed. A rate limiter that hard-fails closed would turn a Redis
+ * blip into a full feature outage, which is worse than briefly losing
+ * the limit. The same posture is used by `editor-cap-counter.ts`.
+ */
+/**
+ * Minimum surface of a node-redis v4 client this limiter leans on.
+ * Structurally compatible with `crowi.redis`; kept narrow so tests can
+ * supply a tiny fake.
+ */
+export interface RateLimitRedisClient {
+    incr(key: string): Promise<number>;
+    pExpire(key: string, ms: number): Promise<unknown>;
+}
+export interface RateLimitOptions {
+    /** Logical bucket name, e.g. `'autocomplete'`. Namespaces the keys. */
+    name: string;
+    /** Max allowed requests per window. */
+    limit: number;
+    /** Window length in milliseconds. */
+    windowMs: number;
+    /** Shared Redis client; omit / pass `null` to use the in-memory fallback. */
+    redisClient?: RateLimitRedisClient | null;
+}
+export interface RateLimitResult {
+    /** Whether this request is within budget (and should proceed). */
+    allowed: boolean;
+    /** Requests already counted in the current window (including this one). */
+    count: number;
+    /** Configured limit, echoed for response headers. */
+    limit: number;
+    /**
+     * Seconds until the current window resets. Surfaced as `Retry-After`
+     * on a 429. Always ≥ 1.
+     */
+    retryAfterSeconds: number;
+}
+export interface RateLimiter {
+    /**
+     * Count one request for `userId` and report whether it is allowed.
+     * `userId` should be the stable user id; the limiter namespaces it
+     * with `name` and the window index internally.
+     */
+    hit(userId: string): Promise<RateLimitResult>;
+}
+/**
+ * Build a per-user rate limiter. Same API whether it is Redis-backed or
+ * in-memory, so callers never branch.
+ */
+export declare function createRateLimiter(options: RateLimitOptions): RateLimiter;