@crowi/api 2.0.0-alpha.0

package/dist/util/mailer.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const debug_1 = __importDefault(require("debug"));
+const nodemailer_1 = __importDefault(require("nodemailer"));
+const nodemailer_ses_transport_1 = __importDefault(require("nodemailer-ses-transport"));
+const debug = (0, debug_1.default)('crowi:lib:mailer');
+exports.default = (crowi) => {
+    'use strict';
+    const config = crowi.getConfig();
+    const mailConfig = {};
+    let mailer = {};
+    function createSMTPClient(option) {
+        debug('createSMTPClient option', option);
+        if (!option) {
+            option = {
+                host: config.crowi['mail:smtpHost'],
+                port: config.crowi['mail:smtpPort'],
+            };
+            if (config.crowi['mail:smtpUser'] && config.crowi['mail:smtpPassword']) {
+                option.auth = {
+                    user: config.crowi['mail:smtpUser'],
+                    pass: config.crowi['mail:smtpPassword'],
+                };
+            }
+            if (option.port === 465) {
+                option.secure = true;
+            }
+        }
+        option.tls = { rejectUnauthorized: false };
+        const client = nodemailer_1.default.createTransport(option);
+        debug('mailer set up for SMTP', client);
+        return client;
+    }
+    function createSESClient(option) {
+        if (!option) {
+            option = {
+                accessKeyId: config.crowi['mail:aws:accessKeyId'],
+                secretAccessKey: config.crowi['mail:aws:secretAccessKey'],
+            };
+        }
+        const client = nodemailer_1.default.createTransport((0, nodemailer_ses_transport_1.default)(option));
+        debug('mailer set up for SES', client);
+        return client;
+    }
+    function initialize() {
+        if (!config.crowi || !config.crowi['mail:from']) {
+            mailer = undefined;
+            return;
+        }
+        if (config.crowi['mail:smtpHost'] && config.crowi['mail:smtpPort']) {
+            // SMTP 設定がある場合はそれを優先
+            mailer = createSMTPClient();
+        }
+        else if (config.crowi['mail:aws:accessKeyId'] && config.crowi['mail:aws:secretAccessKey']) {
+            // AWS 設定がある場合はSESを設定
+            mailer = createSESClient();
+        }
+        else {
+            mailer = undefined;
+        }
+        mailConfig.from = config.crowi['mail:from'];
+        mailConfig.subject = config.crowi['app:title'] + 'からのメール';
+        debug('mailer initialized');
+    }
+    function setupMailConfig(overrideConfig) {
+        const c = overrideConfig;
+        let mc = {};
+        mc = mailConfig;
+        mc.to = c.to;
+        mc.from = c.from || mailConfig.from;
+        mc.text = c.text;
+        mc.subject = c.subject || mailConfig.subject;
+        return mc;
+    }
+    function send(config, callback) {
+        if (mailer) {
+            // テンプレート処理をシンプルなテキスト代入に変更
+            // 将来的には別のメールテンプレートエンジンに置き換える必要があります
+            config.text = config.vars ? JSON.stringify(config.vars) : 'メール本文（テンプレートエンジン削除のため詳細は表示できません）';
+            return mailer.sendMail(setupMailConfig(config), callback);
+        }
+        else {
+            debug('Mailer is not completed to set up. Please set up SMTP or AWS setting.');
+            return callback(new Error('Mailer is not completed to set up. Please set up SMTP or AWS setting.'), null);
+        }
+    }
+    initialize();
+    return {
+        createSMTPClient: createSMTPClient,
+        createSESClient: createSESClient,
+        mailer: mailer,
+        send: send,
+    };
+};
+//# sourceMappingURL=mailer.js.map

package/dist/util/mailer.js.map

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

package/dist/util/map-duplicate-key-error.d.ts

@@ -0,0 +1,26 @@
+/**
+ * feature-user-identity-uniqueness §d — map a MongoDB duplicate-key error
+ * (E11000) raised by the `users.username` / `users.email` unique indexes to a
+ * caller-facing error code.
+ *
+ * The unique indexes are the final defence: the write paths pre-check with a
+ * `findOne`, but a race between that check and the `save()` can still land two
+ * concurrent inserts/updates, in which case the second one fails with E11000.
+ * Without this mapping it would surface as a generic 500; with it the handler
+ * returns the same `USERNAME_TAKEN` / `EMAIL_TAKEN` it would have returned from
+ * the pre-check.
+ *
+ * Detection prefers `err.keyPattern` (the driver populates it with the index's
+ * key spec, e.g. `{ email: 1 }`), falling back to scanning the message for the
+ * index/key name when an older driver omits `keyPattern`.
+ */
+import type { ErrorCode } from '@crowi/api-contract';
+/** True iff `err` is a MongoDB duplicate-key (E11000) error. */
+export declare function isDuplicateKeyError(err: unknown): boolean;
+/**
+ * Map a duplicate-key error on the user identity indexes to `USERNAME_TAKEN` /
+ * `EMAIL_TAKEN`. Returns `null` when `err` is not an E11000 error, or is on a
+ * field this util doesn't own (so the caller can fall through to its generic
+ * 500 handling rather than mislabel an unrelated conflict).
+ */
+export declare function mapDuplicateKeyError(err: unknown): ErrorCode | null;

package/dist/util/map-duplicate-key-error.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDuplicateKeyError = isDuplicateKeyError;
+exports.mapDuplicateKeyError = mapDuplicateKeyError;
+/** Mongo duplicate-key errors carry `code === 11000`. */
+const DUPLICATE_KEY_CODE = 11000;
+const asMongoError = (err) => {
+    if (typeof err !== 'object' || err === null)
+        return null;
+    return err;
+};
+/** True iff `err` is a MongoDB duplicate-key (E11000) error. */
+function isDuplicateKeyError(err) {
+    return asMongoError(err)?.code === DUPLICATE_KEY_CODE;
+}
+/**
+ * Map a duplicate-key error on the user identity indexes to `USERNAME_TAKEN` /
+ * `EMAIL_TAKEN`. Returns `null` when `err` is not an E11000 error, or is on a
+ * field this util doesn't own (so the caller can fall through to its generic
+ * 500 handling rather than mislabel an unrelated conflict).
+ */
+function mapDuplicateKeyError(err) {
+    const mongoErr = asMongoError(err);
+    if (!mongoErr || mongoErr.code !== DUPLICATE_KEY_CODE)
+        return null;
+    // Preferred: the driver's structured key spec (`{ email: 1 }` etc.).
+    const keys = mongoErr.keyPattern ? Object.keys(mongoErr.keyPattern) : Object.keys(mongoErr.keyValue ?? {});
+    if (keys.includes('email'))
+        return 'EMAIL_TAKEN';
+    if (keys.includes('username'))
+        return 'USERNAME_TAKEN';
+    // Fallback: parse the index name out of the message
+    // (`... index: email_1 dup key: ...`).
+    const message = mongoErr.message ?? '';
+    if (/index:\s*email/i.test(message))
+        return 'EMAIL_TAKEN';
+    if (/index:\s*username/i.test(message))
+        return 'USERNAME_TAKEN';
+    return null;
+}
+//# sourceMappingURL=map-duplicate-key-error.js.map

package/dist/util/map-duplicate-key-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-duplicate-key-error.js","sourceRoot":"","sources":["../../src/util/map-duplicate-key-error.ts"],"names":[],"mappings":";;AAkCA,kDAEC;AAQD,oDAgBC;AA1CD,yDAAyD;AACzD,MAAM,kBAAkB,GAAG,KAAK,CAAC;AASjC,MAAM,YAAY,GAAG,CAAC,GAAY,EAAiC,EAAE;IACnE,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACzD,OAAO,GAA6B,CAAC;AACvC,CAAC,CAAC;AAEF,gEAAgE;AAChE,SAAgB,mBAAmB,CAAC,GAAY;IAC9C,OAAO,YAAY,CAAC,GAAG,CAAC,EAAE,IAAI,KAAK,kBAAkB,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,oBAAoB,CAAC,GAAY;IAC/C,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,KAAK,kBAAkB;QAAE,OAAO,IAAI,CAAC;IAEnE,qEAAqE;IACrE,MAAM,IAAI,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IAC3G,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,aAAa,CAAC;IACjD,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,gBAAgB,CAAC;IAEvD,oDAAoD;IACpD,uCAAuC;IACvC,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAC;IACvC,IAAI,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,aAAa,CAAC;IAC1D,IAAI,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,gBAAgB,CAAC;IAEhE,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/util/mongoose-paginate.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Apply the `mongoose-paginate-v2` plugin to a schema.
+ *
+ * mongoose-paginate-v2 types its default export as `(schema: Schema) => void`,
+ * which mongoose 8's generic `Schema.plugin()` does not accept directly; the
+ * plugin only augments the schema with `paginate`, so apply it against the
+ * schema's loosened base type. Centralized here so the cast + rationale live
+ * in one place rather than being repeated per model.
+ */
+export declare function applyPaginatePlugin<TSchema>(schema: TSchema): void;

package/dist/util/mongoose-paginate.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyPaginatePlugin = applyPaginatePlugin;
+const mongoose_paginate_v2_1 = __importDefault(require("mongoose-paginate-v2"));
+/**
+ * Apply the `mongoose-paginate-v2` plugin to a schema.
+ *
+ * mongoose-paginate-v2 types its default export as `(schema: Schema) => void`,
+ * which mongoose 8's generic `Schema.plugin()` does not accept directly; the
+ * plugin only augments the schema with `paginate`, so apply it against the
+ * schema's loosened base type. Centralized here so the cast + rationale live
+ * in one place rather than being repeated per model.
+ */
+function applyPaginatePlugin(schema) {
+    // Widen the model's concrete schema to the base `Schema` so mongoose 8's
+    // generic `plugin()` accepts mongoose-paginate-v2's loosely-typed export.
+    // (Centralizes the cast that each model previously repeated inline.)
+    schema.plugin(mongoose_paginate_v2_1.default);
+}
+//# sourceMappingURL=mongoose-paginate.js.map

package/dist/util/mongoose-paginate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongoose-paginate.js","sourceRoot":"","sources":["../../src/util/mongoose-paginate.ts"],"names":[],"mappings":";;;;;AAYA,kDAKC;AAhBD,gFAAoD;AAEpD;;;;;;;;GAQG;AACH,SAAgB,mBAAmB,CAAU,MAAe;IAC1D,yEAAyE;IACzE,0EAA0E;IAC1E,qEAAqE;IACpE,MAA4B,CAAC,MAAM,CAAC,8BAAgB,CAAC,CAAC;AACzD,CAAC"}

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

@@ -0,0 +1,35 @@
+import { type NotificationsTokenPayload } from '@crowi/api-contract';
+/** Claims signed into a notifications token. */
+export interface NotificationsTokenClaims {
+    /**
+     * The requesting user's `_id`. The `/notifications/<userId>` WS
+     * handshake rejects a token whose `selfUserId` does not match the
+     * URL path segment so one user can never subscribe to another's
+     * channel even with a valid token.
+     */
+    selfUserId: string;
+}
+export interface SignNotificationsTokenResult {
+    /** Compact JWT string presented by the browser on the WebSocket connect. */
+    token: string;
+    /** Absolute expiry timestamp; mirrors `exp * 1000` as a Date. */
+    expiresAt: Date;
+}
+/**
+ * Build a sign / verify pair bound to a freshly resolved secret. Each
+ * `createNotificationsTokenUtil()` call returns a new instance — the
+ * util's surface (sign / verify) is cheap (a single jsonwebtoken call)
+ * so memoising is unnecessary, and the previous cached-singleton
+ * implementation pinned the secret to whatever env state existed at the
+ * first call (a problem for test / boot ordering: a `WS_TOKEN_SECRET`
+ * set after first util construction would be ignored).
+ */
+declare function buildNotificationsTokenUtil(): {
+    signNotificationsToken: (claims: NotificationsTokenClaims) => SignNotificationsTokenResult;
+    verifyNotificationsToken: (token: string) => NotificationsTokenPayload | null;
+    ttlSeconds: number;
+    issuer: string;
+};
+export type NotificationsTokenUtil = ReturnType<typeof buildNotificationsTokenUtil>;
+export declare function createNotificationsTokenUtil(): NotificationsTokenUtil;
+export {};

package/dist/util/notifications-token.js

@@ -0,0 +1,140 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNotificationsTokenUtil = createNotificationsTokenUtil;
+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:notifications-token');
+/**
+ * Issuer claim used to sign / verify notifications tokens.
+ *
+ * Distinct from the collab wsToken issuer (`'crowi-collab'`, see
+ * `util/ws-token.ts`), the presence token issuer (`'crowi-presence'`,
+ * see `util/presence-token.ts`), and the HTTP access/refresh token
+ * issuer (`'crowi'`). The three WebSocket issuers all share the same
+ * `WS_TOKEN_SECRET` key material but verify against different `iss`
+ * claims, so a leaked token for one channel is never replayable
+ * against the others — `/collab` carries write access to the Y.Doc,
+ * `/presence` is per-page viewer tracking, `/notifications` is the
+ * per-user invalidation channel.
+ */
+const NOTIFICATIONS_TOKEN_ISSUER = 'crowi-notifications';
+/**
+ * Lifetime of an issued notifications token. 60 seconds — short enough
+ * that a leaked token has minimal blast radius (the notifications
+ * channel only carries `{type:'changed'}` ticks, no notification data,
+ * so a hijacked subscription is a low-value target but the principle
+ * of least privilege still applies). The browser uses `expiresAt` to
+ * proactively re-fetch ~30s before expiry; the realistic refresh
+ * cadence becomes ~30s rather than the 5-minute presence cadence.
+ */
+const NOTIFICATIONS_TOKEN_TTL_SECONDS = 60;
+/**
+ * Tracks whether the "secret missing" warning has already been emitted,
+ * so it fires at most once per process regardless of how many
+ * `createNotificationsTokenUtil()` calls the handler / model layer makes.
+ */
+let warnedMissingSecret = false;
+/**
+ * Resolve the signing secret. Reads `WS_TOKEN_SECRET` per call so a test
+ * that mutates the env between imports / util constructions still picks
+ * up the latest value.
+ *
+ * The "secret missing" warning is emitted here (lazily, on first
+ * resolution) rather than at module-load time: this module is imported
+ * transitively before `app.ts` runs `dotenv.config()`, so a load-time
+ * `process.env` read fires a false warning even when `.env` defines
+ * `WS_TOKEN_SECRET`. `warnedMissingSecret` keeps it to once per process.
+ * Silenced under tests.
+ */
+const resolveNotificationsTokenSecret = () => {
+    const fromEnv = process.env.WS_TOKEN_SECRET;
+    if (fromEnv && fromEnv.length > 0) {
+        debug('notifications token secret resolved from WS_TOKEN_SECRET');
+        return fromEnv;
+    }
+    if (!warnedMissingSecret && process.env.NODE_ENV !== 'test') {
+        warnedMissingSecret = true;
+        console.warn('[crowi] WS_TOKEN_SECRET is not set — notifications tokens will be signed with a random in-memory secret. ' +
+            'Process restarts will invalidate outstanding notifications 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 node_crypto_1.default.randomBytes(32).toString('base64');
+};
+/**
+ * Build a sign / verify pair bound to a freshly resolved secret. Each
+ * `createNotificationsTokenUtil()` call returns a new instance — the
+ * util's surface (sign / verify) is cheap (a single jsonwebtoken call)
+ * so memoising is unnecessary, and the previous cached-singleton
+ * implementation pinned the secret to whatever env state existed at the
+ * first call (a problem for test / boot ordering: a `WS_TOKEN_SECRET`
+ * set after first util construction would be ignored).
+ */
+function buildNotificationsTokenUtil() {
+    const secret = resolveNotificationsTokenSecret();
+    /**
+     * Sign a notifications token for the given claims. Returns the
+     * compact JWT plus the absolute expiry; the handler serialises the
+     * timestamp into `NotificationsTokenResponseSchema.expiresAt`.
+     *
+     * A fresh `jti` (random UUID) is mixed into the payload so two
+     * tokens minted within the same second are byte-different. The
+     * browser uses the token string as a react `useEffect` dependency
+     * (it dials the WebSocket whenever the token changes) — without a
+     * `jti`, the iat/exp pair is identical and the dep stays stable, so
+     * a re-mint at the same second does not trigger the effect. The
+     * verifier ignores `jti`, keeping the token stateless.
+     */
+    function signNotificationsToken(claims) {
+        // Pin `iat` ourselves so the response's `expiresAt` is exactly the
+        // same instant as the JWT's `exp` claim (same rationale as the
+        // collab / presence token utils).
+        const iat = Math.floor(Date.now() / 1000);
+        const exp = iat + NOTIFICATIONS_TOKEN_TTL_SECONDS;
+        const jti = node_crypto_1.default.randomUUID();
+        const token = jsonwebtoken_1.default.sign({ ...claims, jti, iat, exp }, secret, {
+            issuer: NOTIFICATIONS_TOKEN_ISSUER,
+            algorithm: 'HS256',
+        });
+        return { token, expiresAt: new Date(exp * 1000) };
+    }
+    /**
+     * Verify a notifications 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 verifyNotificationsToken(token) {
+        try {
+            const decoded = jsonwebtoken_1.default.verify(token, secret, {
+                issuer: NOTIFICATIONS_TOKEN_ISSUER,
+                algorithms: ['HS256'],
+            });
+            const parsed = api_contract_1.NotificationsTokenPayloadSchema.safeParse(decoded);
+            if (!parsed.success) {
+                debug('notifications token payload failed schema validation:', parsed.error.issues);
+                return null;
+            }
+            return parsed.data;
+        }
+        catch (err) {
+            debug('notifications token verification failed:', err.message);
+            return null;
+        }
+    }
+    return {
+        signNotificationsToken,
+        verifyNotificationsToken,
+        ttlSeconds: NOTIFICATIONS_TOKEN_TTL_SECONDS,
+        issuer: NOTIFICATIONS_TOKEN_ISSUER,
+    };
+}
+function createNotificationsTokenUtil() {
+    return buildNotificationsTokenUtil();
+}
+//# sourceMappingURL=notifications-token.js.map

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

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

package/dist/util/oauth-client-seed.d.ts

@@ -0,0 +1,2 @@
+import type Crowi from '../crowi';
+export declare function runOAuthClientSeed(crowi: Crowi): Promise<void>;

package/dist/util/oauth-client-seed.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.runOAuthClientSeed = runOAuthClientSeed;
+const api_contract_1 = require("@crowi/api-contract");
+const debug_1 = __importDefault(require("debug"));
+const debug = (0, debug_1.default)('crowi:util:oauth-client-seed');
+/**
+ * RFC-0010 Phase 3 — seed the first-party `crowi-cli` OAuth client.
+ *
+ * Idempotent boot step (PHASE3-Q2): `$setOnInsert` only writes on the very
+ * first run, so re-running boot — or upgrading an instance that already
+ * has the row — never clobbers an operator's later edits to the client.
+ * Modelled on the other boot-time init steps (it runs alongside the
+ * migration framework's `runBootMigrations`, but stays framework-external
+ * per RFC-0008 §12.6 — OAuth client seeding is a seed, not a migration).
+ *
+ * `crowi-cli` is a **public** client (no secret, PKCE-only). Its
+ * `redirectUris` list the loopback hosts; the per-login ephemeral port is
+ * matched at request time by `util/oauth-redirect-uri.ts`. It may request
+ * any issuable scope (catalog minus `admin:*`).
+ */
+const CROWI_CLI_CLIENT_ID = 'crowi-cli';
+async function runOAuthClientSeed(crowi) {
+    const OAuthClient = crowi.model('OAuthClient');
+    const result = await OAuthClient.updateOne({ clientId: CROWI_CLI_CLIENT_ID }, {
+        $setOnInsert: {
+            clientId: CROWI_CLI_CLIENT_ID,
+            name: 'Crowi CLI',
+            type: 'public',
+            secretHash: null,
+            redirectUris: ['http://127.0.0.1', 'http://localhost'],
+            allowedScopes: [...api_contract_1.ISSUABLE_SCOPES],
+            firstParty: true,
+            trusted: false,
+            createdAt: new Date(),
+        },
+    }, { upsert: true });
+    if (result.upsertedCount) {
+        console.log(`[crowi] Seeded first-party OAuth client '${CROWI_CLI_CLIENT_ID}'.`);
+    }
+    else {
+        debug('crowi-cli client already present — nothing to seed');
+    }
+}
+//# sourceMappingURL=oauth-client-seed.js.map

package/dist/util/oauth-client-seed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-client-seed.js","sourceRoot":"","sources":["../../src/util/oauth-client-seed.ts"],"names":[],"mappings":";;;;;AAwBA,gDA0BC;AAlDD,sDAAsD;AACtD,kDAA0B;AAI1B,MAAM,KAAK,GAAG,IAAA,eAAK,EAAC,8BAA8B,CAAC,CAAC;AAEpD;;;;;;;;;;;;;;GAcG;AACH,MAAM,mBAAmB,GAAG,WAAW,CAAC;AAEjC,KAAK,UAAU,kBAAkB,CAAC,KAAY;IACnD,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAE/C,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,SAAS,CACxC,EAAE,QAAQ,EAAE,mBAAmB,EAAE,EACjC;QACE,YAAY,EAAE;YACZ,QAAQ,EAAE,mBAAmB;YAC7B,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;YACtD,aAAa,EAAE,CAAC,GAAG,8BAAe,CAAC;YACnC,UAAU,EAAE,IAAI;YAChB,OAAO,EAAE,KAAK;YACd,SAAS,EAAE,IAAI,IAAI,EAAE;SACtB;KACF,EACD,EAAE,MAAM,EAAE,IAAI,EAAE,CACjB,CAAC;IAEF,IAAK,MAAqC,CAAC,aAAa,EAAE,CAAC;QACzD,OAAO,CAAC,GAAG,CAAC,4CAA4C,mBAAmB,IAAI,CAAC,CAAC;IACnF,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,oDAAoD,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC"}

package/dist/util/oauth-redirect-uri.d.ts

@@ -0,0 +1,2 @@
+import type { OAuthClientDocument } from '../models/oauth-client';
+export declare function isRedirectUriAllowed(client: Pick<OAuthClientDocument, 'redirectUris'>, requestedUri: string): boolean;

package/dist/util/oauth-redirect-uri.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRedirectUriAllowed = isRedirectUriAllowed;
+/**
+ * RFC-0010 §Security — redirect_uri validation for the Auth Code flow.
+ *
+ * Two rules:
+ *
+ *  - **Loopback** (`127.0.0.1` / `localhost`, http): allowed if the client
+ *    registered a matching loopback host, *regardless of port*. Native /
+ *    CLI clients bind an ephemeral loopback port per login (RFC 8252
+ *    §7.3), so the port cannot be pre-registered; the host match is the
+ *    security boundary.
+ *  - **Everything else**: must match one of the client's `redirectUris`
+ *    exactly (string equality), preventing open-redirect to an attacker
+ *    origin.
+ *
+ * Anything that does not parse as a URL, or uses a non-http(s) scheme, is
+ * rejected.
+ */
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]', '::1']);
+function isLoopbackHost(hostname) {
+    return LOOPBACK_HOSTS.has(hostname);
+}
+function isRedirectUriAllowed(client, requestedUri) {
+    let requested;
+    try {
+        requested = new URL(requestedUri);
+    }
+    catch {
+        return false;
+    }
+    // Only http(s) callbacks. (Loopback CLI callbacks are http.)
+    if (requested.protocol !== 'http:' && requested.protocol !== 'https:') {
+        return false;
+    }
+    if (isLoopbackHost(requested.hostname)) {
+        // Loopback: any registered loopback host of the same hostname matches,
+        // ignoring the (ephemeral) port. Path must still match if registered,
+        // but the seeded crowi-cli registers bare hosts so any path on the
+        // loopback host is accepted.
+        return client.redirectUris.some((registered) => {
+            try {
+                const reg = new URL(registered);
+                return isLoopbackHost(reg.hostname) && reg.hostname === requested.hostname && reg.protocol === requested.protocol;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    // Non-loopback: exact string match against a registered URI.
+    return client.redirectUris.includes(requestedUri);
+}
+//# sourceMappingURL=oauth-redirect-uri.js.map

package/dist/util/oauth-redirect-uri.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-redirect-uri.js","sourceRoot":"","sources":["../../src/util/oauth-redirect-uri.ts"],"names":[],"mappings":";;AA0BA,oDA8BC;AAtDD;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;AAE3E,SAAS,cAAc,CAAC,QAAgB;IACtC,OAAO,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AACtC,CAAC;AAED,SAAgB,oBAAoB,CAAC,MAAiD,EAAE,YAAoB;IAC1G,IAAI,SAAc,CAAC;IACnB,IAAI,CAAC;QACH,SAAS,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IAED,6DAA6D;IAC7D,IAAI,SAAS,CAAC,QAAQ,KAAK,OAAO,IAAI,SAAS,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACtE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,cAAc,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvC,uEAAuE;QACvE,sEAAsE;QACtE,mEAAmE;QACnE,6BAA6B;QAC7B,OAAO,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE;YAC7C,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;gBAChC,OAAO,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,QAAQ,CAAC;YACpH,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,6DAA6D;IAC7D,OAAO,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;AACpD,CAAC"}

package/dist/util/page-response.d.ts

@@ -0,0 +1,113 @@
+import type { Revision, RevisionMetaShape } from '@crowi/api-contract';
+import { Types } from 'mongoose';
+import type Crowi from '../crowi';
+import type { PageDocument } from '../models/page';
+import { type RevisionMetaContent } from '../models/revision';
+import { type PopulatedUser } from './ts-rest-helpers';
+/**
+ * Shape of a populated `revision` field as it appears on Mongoose documents
+ * after `.populate('revision', ...)`. `path` mirrors `Page.path` and `body`
+ * is the markdown source. `author` may itself be populated (full user) or
+ * remain an `ObjectId` ref — we narrow with `isPopulatedUser` at the call
+ * site.
+ */
+export interface PopulatedRevision {
+    _id: Types.ObjectId;
+    path: string;
+    body: string;
+    format?: string;
+    author?: PopulatedUser | null;
+    createdAt?: Date;
+    meta?: RevisionMetaContent;
+    /** RFC-0002 Phase 3 — transformed mdast persisted verbatim. */
+    renderedAst?: unknown;
+    /** RFC-0002 round 3.1 — semver of the pipeline that produced `renderedAst`. */
+    rendererVersion?: string;
+    /** RFC-0010 — edit channel ('web' | 'oauth' | 'pat'); absent = web. */
+    editVia?: 'web' | 'oauth' | 'pat';
+}
+/**
+ * Looser shape than `PageDocument`: covers both Mongoose documents and the
+ * plain objects produced by `.toObject()` / `.lean()`. Every field is
+ * optional except `_id` + `path` so populated and unpopulated views (e.g.
+ * search hit pre-populate) both fit.
+ */
+export interface PageLike {
+    _id: Types.ObjectId | string;
+    path: string;
+    revision?: PopulatedRevision | Types.ObjectId | null;
+    redirectTo?: string | null;
+    status?: string | null;
+    grant?: number;
+    grantedUsers?: (Types.ObjectId | string)[];
+    creator?: PopulatedUser | Types.ObjectId | null;
+    lastUpdateUser?: PopulatedUser | Types.ObjectId | null;
+    liker?: (Types.ObjectId | string)[];
+    commentCount?: number;
+    extended?: Record<string, unknown>;
+    createdAt?: Date;
+    updatedAt?: Date;
+    latestRevision?: Types.ObjectId | string;
+    likerCount?: number;
+    seenUsersCount?: number;
+    toObject?: () => PageLike;
+}
+/**
+ * Heuristic: a `revision` field is populated when it has the `_id` + `path`
+ * + `body` triplet. Plain `ObjectId` refs only carry `_id`.
+ */
+export declare const isPopulatedRevision: (value: unknown) => value is PopulatedRevision;
+export interface RevisionResponseOptions {
+    /**
+     * Emit `revision.meta` (currently just `meta.toc`). Off by default —
+     * only single-revision read paths (getPage, getRevision) consume it.
+     * List endpoints (listPages, search hits, recently-viewed, bookmarks,
+     * me) skip it: the TOC adds payload weight without being rendered.
+     */
+    withMeta?: boolean;
+    /**
+     * RFC-0002 Phase 3: emit `revision.renderedAst` (transformed mdast
+     * the web client renders directly). Off by default — list endpoints
+     * skip it because the AST is 5-10x the body size in JSON form.
+     * Only single-page detail (getPage) and single-revision detail
+     * (getRevision) opt in. Legacy revisions without a stored
+     * `renderedAst` are filled in by `computeRevisionRenderedAstAsync`.
+     */
+    withRenderedAst?: boolean;
+}
+export declare const toRevisionResponse: (revision: PopulatedRevision, options?: RevisionResponseOptions) => Revision;
+export declare const resolveRevisionMeta: (stored: RevisionMetaContent | undefined, emit: boolean | undefined) => RevisionMetaShape | undefined;
+/**
+ * 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.
+ */
+export declare const computeRevisionRenderArtifactsAsync: (crowi: Crowi, storedMeta: RevisionMetaContent | undefined, storedAst: unknown, body: string, storedRendererVersion?: string, pageId?: string) => Promise<{
+    meta?: RevisionMetaShape;
+    renderedAst?: unknown;
+}>;
+export type PageToResponseOptions = RevisionResponseOptions;
+/**
+ * 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.
+ */
+export declare const pageToResponse: (page: PageDocument | PageLike, options?: PageToResponseOptions) => any;