@crowi/plugin-api 0.1.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,1159 @@
+import { z } from 'zod/v3';
+import { Readable } from 'node:stream';
+
+/**
+ * The context object passed to every plugin callback. It is the only
+ * conduit through which a plugin reads core state (config, models,
+ * crypto helpers, logging) — plugins must NOT import from
+ * `@crowi/server` directly to keep the contract surface thin.
+ */
+interface PluginContext {
+    /**
+     * Read this plugin's typed config. The runtime parses
+     * `plugin:<plugin-name>:*` rows from the Mongo Config collection
+     * through the plugin's `configSchema` and returns the result.
+     *
+     * Throws if `configSchema` is not declared on the plugin.
+     */
+    config<T>(): T;
+    /**
+     * Read a typed dependency plugin's config. The target plugin must
+     * be listed in this plugin's `requires` array — reading another
+     * plugin's config without declaring the dependency is a contract
+     * violation and throws.
+     *
+     * Useful for shared-credential plugins like `@crowi/plugin-aws`:
+     * the base plugin owns `region` / `accessKeyId` / `secretAccessKey`,
+     * and dependents (`@crowi/plugin-storage-aws-s3`,
+     * `@crowi/plugin-mail-aws-ses`) read them through this method
+     * instead of duplicating the fields in their own configSchema.
+     */
+    dependencyConfig<T>(dependencyName: string): T;
+    /** Write a single config field, persisting to Mongo. */
+    setConfig(key: string, value: unknown): Promise<void>;
+    /** Per-Page metadata accessor for this plugin's namespace. */
+    pageMetadata: PageMetadataAccessor;
+    /**
+     * Mongoose model accessor. Returns the named core model. Plugins
+     * touch core collections (Page, User, Comment, ...) through this
+     * accessor rather than importing model files directly.
+     *
+     * Typed loosely (`unknown`) at this layer because the core model
+     * types live in `@crowi/server`; plugins narrow the return type at
+     * the call site.
+     */
+    model(name: string): unknown;
+    /** Symmetric encrypt / decrypt against the configured KeyProvider. */
+    crypto: PluginCrypto;
+    /** Structured logger scoped to this plugin (auto-prefixed with name). */
+    log: PluginLogger;
+}
+/**
+ * Per-Page metadata read / write helper. Each plugin gets a private
+ * namespace at `page.metadata['<plugin-name>']`; this accessor scopes
+ * reads and writes to just that slot so plugins cannot accidentally
+ * trample on each other.
+ */
+interface PageMetadataAccessor {
+    /** Read this plugin's metadata for a specific page. Returns null when unset. */
+    get<T>(pageId: string): Promise<T | null>;
+    /** Replace this plugin's metadata for a specific page. */
+    set<T>(pageId: string, value: T): Promise<void>;
+    /** Remove this plugin's metadata for a specific page. */
+    remove(pageId: string): Promise<void>;
+}
+interface PluginCrypto {
+    encrypt(plaintext: string): string;
+    decrypt(ciphertext: string): string;
+}
+interface PluginLogger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+
+/**
+ * Metadata accompanying a `put`. The runtime always provides
+ * `contentType`; drivers are free to store additional fields under
+ * implementation-specific custom metadata.
+ */
+interface StoragePutMeta {
+    contentType: string;
+}
+/** Result of a successful `put`. The driver echoes back the stored key. */
+interface StoragePutResult {
+    key: string;
+}
+/**
+ * Storage driver — the file-system abstraction every uploader plugin
+ * implements. The runtime resolves the active driver at boot from
+ * `crowi.config.json:storage.driver`.
+ *
+ * Object keys are opaque strings owned by the *caller* (core's
+ * file-uploader service), e.g. `attachment/<pageId>/<filename>`.
+ * Drivers must round-trip them verbatim to preserve compatibility
+ * with files uploaded under v1.x.
+ */
+interface StorageDriver {
+    /** Write a blob and return its (round-tripped) key. */
+    put(key: string, body: Buffer | Readable, meta: StoragePutMeta): Promise<StoragePutResult>;
+    /**
+     * Stream a blob back. Throws if the key does not exist (drivers must
+     * use a recognisable error code; e.g. `NoSuchKey` for S3 / `ENOENT`
+     * for local).
+     */
+    get(key: string): Promise<Readable>;
+    /** Delete a blob. Idempotent — no-op if the key is already absent. */
+    delete(key: string): Promise<void>;
+    /**
+     * Optional: produce a time-limited signed URL the browser can fetch
+     * directly. When the active driver does not implement this, core
+     * falls back to streaming via `get()` through the API.
+     */
+    signedUrl?(key: string, expiresInSec: number): Promise<string>;
+}
+/**
+ * Storage registry passed to `registerStorage`. A plugin contributes
+ * one or more drivers under string keys; the active driver is selected
+ * by `crowi.config.json:storage.driver`.
+ */
+interface StorageRegistry {
+    /**
+     * Register a driver under a stable name (e.g. `'s3'`, `'local'`).
+     * Names must be unique across all plugins; the PluginManager fails
+     * boot on collision.
+     */
+    register(driverName: string, driver: StorageDriver): void;
+}
+
+/**
+ * Document shape passed to `index()`. Mirrors the fields the legacy
+ * search service indexes (path / body / title / tags / metadata).
+ * Drivers may project a subset; `id` and `body` are required.
+ */
+interface SearchableDoc {
+    id: string;
+    path: string;
+    body: string;
+    /** Optional human-friendly title (often derived from the first heading). */
+    title?: string;
+    tags?: string[];
+    /**
+     * Free-form metadata for driver-specific use. Not searchable through
+     * the contract; drivers that want to surface custom fields should
+     * declare them in their own configSchema.
+     */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Page-type filter. Mirrors the legacy ES Searcher's portal/public/user
+ * filter, generalised so future drivers (Mongo, Meilisearch, Algolia)
+ * can implement them with their own backend semantics.
+ *
+ * - `portal`: directory-style pages (path ends with `/`), excluding `/user/*`
+ * - `public`: leaf pages (path does not end with `/`), excluding `/user/*`
+ * - `user`:   `/user/*` pages
+ */
+type SearchPageType = 'portal' | 'public' | 'user';
+/**
+ * The viewer running the search. Drivers consult this to apply
+ * grant-aware filtering: pages with `GRANT_OWNER` / `GRANT_RESTRICTED`
+ * / `GRANT_SPECIFIED` are only visible to listed users; the driver
+ * builds the filter so callers can stay grant-agnostic.
+ */
+interface SearchQueryViewer {
+    /** Mongo ObjectId string of the user. */
+    id: string;
+    username: string;
+    isAdmin?: boolean;
+}
+interface SearchQueryGrants {
+    /** Restrict results to one or more page types. */
+    types?: SearchPageType[];
+}
+/**
+ * Search request. Intentionally minimal in v2.0 — query string + paging
+ * + optional filters. Richer queries (faceting, highlighting, custom
+ * scoring) are deferred to a future RFC.
+ */
+interface SearchQuery {
+    q: string;
+    /** 1-based page number. Defaults to 1. */
+    page?: number;
+    /** Items per page. Defaults to 50, capped at 200. */
+    limit?: number;
+    /** Optional path-prefix filter (e.g. `/team/eng/`). */
+    pathPrefix?: string;
+    /**
+     * Identity of the user running the search. When set, drivers apply
+     * grant-aware filtering so private pages (owner-only / restricted)
+     * are hidden from non-authorised viewers. When omitted, drivers
+     * return only public pages (anonymous behaviour).
+     */
+    viewer?: SearchQueryViewer;
+    /** Page-type / metadata filters. */
+    grants?: SearchQueryGrants;
+}
+interface SearchHit {
+    id: string;
+    path: string;
+    /**
+     * Optional ranked snippet around the match. Drivers may return raw
+     * text or HTML with the matched terms wrapped in `<mark>`; consumers
+     * must sanitise for HTML render.
+     */
+    snippet?: string;
+    /** Driver-specific relevance score; higher is better. */
+    score?: number;
+}
+interface SearchHits {
+    total: number;
+    hits: SearchHit[];
+    /**
+     * Optional driver-reported elapsed time in milliseconds. Backends that
+     * surface their own timing (e.g. Elasticsearch's `took`) populate this;
+     * drivers without a meaningful measurement (regex / Mongo `$text`) may
+     * omit it. Surfaced under `meta.took` on the API response.
+     */
+    took?: number;
+}
+/**
+ * Search backend driver. Active driver is selected by
+ * `crowi.config.json:search.driver`. The default is `'mongo'` (Mongo
+ * `$regex` over path / title / body), provided by `@crowi/plugin-search-mongo`.
+ */
+interface SearchDriver {
+    /**
+     * Index or update a document. Called from the page-saved event hook;
+     * implementations must be idempotent on the same `doc.id`.
+     */
+    index(doc: SearchableDoc): Promise<void>;
+    /** Remove a document from the index. Idempotent. */
+    remove(id: string): Promise<void>;
+    /** Run a search query and return hits ordered by relevance. */
+    query(q: SearchQuery): Promise<SearchHits>;
+    /**
+     * Optional: rebuild the full index from scratch. Triggered by the
+     * admin "Rebuild index" maintenance op. Drivers without a persistent
+     * index (e.g. Mongo regex) can omit this.
+     */
+    rebuild?(): Promise<void>;
+}
+interface SearchRegistry {
+    register(driverName: string, driver: SearchDriver): void;
+}
+
+/**
+ * Auth provider profile, normalised across providers (Google / GitHub /
+ * future SAML / OIDC). Plugins map the upstream token / profile into
+ * this shape; core looks up or provisions a User by `providerUserId`.
+ */
+interface AuthProfile {
+    /**
+     * Stable identifier for this user *within the provider's namespace*.
+     * Google: the `sub` claim. GitHub: the numeric account id as string.
+     * Plugins must NEVER use email / username for this — those rotate.
+     */
+    providerUserId: string;
+    /** Email address from the provider. May be empty if not granted. */
+    email?: string;
+    /** Display name from the provider. */
+    name?: string;
+    /** Avatar URL from the provider. */
+    imageUrl?: string;
+    /**
+     * Free-form additional fields the plugin wants to persist on the
+     * user document (e.g. github org membership). Stored under the
+     * plugin's pageMetadata-style namespace on User.
+     */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Result of `verify` — either a normalised profile (success) or an
+ * error reason the login UI surfaces.
+ */
+type AuthVerifyResult = {
+    ok: true;
+    profile: AuthProfile;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Auth provider driver. The login screen asks core for the list of
+ * registered drivers and renders one button per driver
+ * (`Sign in with Google`). Clicking redirects through the plugin's
+ * registered routes (`/api/v2/plugins/<name>/oauth/start`); the
+ * provider redirects back to `/api/v2/plugins/<name>/oauth/callback`,
+ * which the plugin's contract handles.
+ *
+ * `verify` is the bridge: given whatever the plugin pulled out of the
+ * callback (token / code / SAML response), produce a normalised
+ * `AuthProfile` or a failure reason.
+ */
+interface AuthDriver {
+    /**
+     * Human-readable label for the login button (e.g. `'Google'`).
+     * Localisation is the plugin's responsibility — i18n keys can be
+     * resolved by the plugin before registration.
+     */
+    buttonLabel: string;
+    /** Optional icon URL for the login button. */
+    iconUrl?: string;
+    /**
+     * Map provider-specific verification data into a normalised profile.
+     * Called from inside the plugin's own callback route, with whatever
+     * shape that route extracted. Typed as `unknown` here because the
+     * shape is plugin-private.
+     */
+    verify(verificationData: unknown): Promise<AuthVerifyResult>;
+}
+interface AuthRegistry {
+    register(driverName: string, driver: AuthDriver): void;
+}
+
+/**
+ * Notification payload — the runtime-neutral shape passed to every
+ * notifier driver. Drivers translate it into provider-specific
+ * messages (Slack: `chat.postMessage`; Webhook: HTTP POST; etc.).
+ */
+interface NotificationPayload {
+    /** Plain-text title (e.g. "Page updated: /team/eng/foo"). */
+    title: string;
+    /** Optional plain-text body / details. */
+    body?: string;
+    /**
+     * Absolute URL the notification should link to. Drivers that render
+     * clickable text use this; otherwise it appears in the body.
+     */
+    url?: string;
+    /**
+     * Originating event kind, opaque to drivers but useful for debug logs
+     * and for plugins that filter (e.g. only forward 'page:updated').
+     */
+    event: string;
+    /**
+     * Provider-routing hint pulled from the source page's plugin metadata
+     * (e.g. `{ channel: '#eng' }` for slack). Drivers cast this to their
+     * own typed shape.
+     */
+    routing?: Record<string, unknown>;
+}
+/**
+ * Notifier driver. Active driver is selected at registration time and
+ * called for every event the core opts to forward. Multiple drivers
+ * can be registered simultaneously (a single page-save can fan out to
+ * Slack and Webhook); the runtime calls each registered driver in
+ * parallel.
+ */
+interface NotifierDriver {
+    /**
+     * Send the notification. Implementations should swallow transient
+     * provider errors (log + continue) — a flaky Slack must not break
+     * the page-save handler. Persistent misconfiguration should throw
+     * so the admin sees it.
+     */
+    send(payload: NotificationPayload): Promise<void>;
+}
+interface NotifierRegistry {
+    register(driverName: string, driver: NotifierDriver): void;
+}
+
+/**
+ * Mail transport abstraction.
+ *
+ * The core MailService owns *what* an email says — the from address,
+ * subject, and rendered body are resolved before a driver is ever
+ * called — so every sender produces an identical message. A mail
+ * sender driver is a pure transport: it takes a fully-assembled
+ * `EmailMessage` and physically delivers it (SMTP, Resend HTTP API,
+ * AWS SES, …).
+ *
+ * Unlike `NotifierDriver` (a fan-out sink that may have several active
+ * drivers at once), exactly one mail sender is active, selected by
+ * `crowi.config.json:mail.driver` — the same single-active-driver model
+ * as storage and search.
+ */
+/**
+ * Runtime-neutral, fully-assembled email. The core builds this; drivers
+ * translate it into their provider's request shape (nodemailer
+ * `Mail.Options`, SES `SendEmailCommand`, Resend `emails.send`, …).
+ *
+ * Recipient fields are always arrays — the core normalises them once so
+ * every driver receives the same shape and none has to branch on
+ * `string | string[]`. This is otherwise a subset of nodemailer's
+ * `Mail.Options`, which accepts string arrays directly.
+ */
+interface EmailMessage {
+    /** Recipient(s), normalised to an array by the core. */
+    to: string[];
+    /** Sender address, already resolved from `mail:from` by the core. */
+    from: string;
+    /** Subject line, already resolved by the core. */
+    subject: string;
+    /** Plain-text body, already rendered by the core. */
+    text: string;
+    /** Optional HTML body. */
+    html?: string;
+    /** Optional Reply-To address. */
+    replyTo?: string;
+    /** Optional CC recipient(s). */
+    cc?: string[];
+    /** Optional BCC recipient(s). */
+    bcc?: string[];
+}
+/**
+ * Mail sender driver — the transport every mail plugin implements. The
+ * runtime resolves the single active driver at boot from
+ * `crowi.config.json:mail.driver`.
+ */
+interface MailSender {
+    /**
+     * Deliver a fully-assembled message. Should throw on persistent
+     * misconfiguration (missing host / API key) so the admin sees it via
+     * the test-mail endpoint; the core decides whether a send failure is
+     * fatal to the surrounding operation.
+     */
+    send(message: EmailMessage): Promise<void>;
+}
+/**
+ * Mail sender registry passed to `registerMailSender`. A plugin
+ * contributes one or more drivers under string keys (e.g. `'smtp'`,
+ * `'resend'`, `'ses'`); the active driver is selected by
+ * `crowi.config.json:mail.driver`.
+ */
+interface MailSenderRegistry {
+    /**
+     * Register a driver under a stable name. Names must be unique across
+     * all plugins; the PluginManager fails boot on collision.
+     */
+    register(driverName: string, driver: MailSender): void;
+}
+
+/**
+ * Domain events emitted by core. The full event payload shapes live in
+ * `@crowi/server`; this contract publishes only the event names so the
+ * type signature of `EventBus.on` stays type-safe at the plugin layer.
+ *
+ * `pluginHooks` are the v2.0 internal-use-only events. Community
+ * plugins should NOT subscribe — the surface is reserved while we
+ * stabilise it.
+ */
+interface PluginEvents {
+    'page:created': {
+        pageId: string;
+        path: string;
+    };
+    'page:updated': {
+        pageId: string;
+        path: string;
+    };
+    'page:deleted': {
+        pageId: string;
+        path: string;
+    };
+    'page:renamed': {
+        pageId: string;
+        oldPath: string;
+        newPath: string;
+    };
+    'comment:added': {
+        pageId: string;
+        commentId: string;
+    };
+    'comment:removed': {
+        pageId: string;
+        commentId: string;
+    };
+    'user:registered': {
+        userId: string;
+    };
+    'user:activated': {
+        userId: string;
+    };
+}
+interface EventBus {
+    on<K extends keyof PluginEvents>(event: K, listener: (payload: PluginEvents[K]) => void | Promise<void>): void;
+}
+
+/**
+ * Renderer extension contract — type-only. Plugins contribute parse /
+ * transform behaviour to the server-side markdown pipeline through
+ * `registerRenderer(scope, ctx)`. The runtime owns the unified.js
+ * pipeline; plugins push unified plugins, node renderers, code-block
+ * renderers, embed renderers, and URL inline-expansion rules into the
+ * passed `RendererRegistry`.
+ *
+ * Phase 4 of RFC-0002 implements the I/O surface for plugins:
+ *   - `CacheStorage` (MongoDB-backed) with stale-while-revalidate
+ *     and error-cache TTLs.
+ *   - `Reservation` API: plugins declare the shape of their placeholder
+ *     so the core renders a stable layout while the embed loads.
+ *   - `AuthContext`: shape confirmed here; Phase 7 wires the encrypted-
+ *     config lookup. **Phase 6 no-I/O plugins (PlantUML / KaTeX /
+ *     Mermaid / emoji) must NOT touch `AuthContext`** — the registry
+ *     impl will throw at the call site until Phase 7 lands.
+ *   - `addEmbedTag` / `addUrlInlineExpander`: registered renderers are
+ *     dispatched against the `@[tag](url)` mdast parser and the URL
+ *     inline-expansion walker respectively.
+ *
+ * Phase 2 covered `addUnifiedPlugin` + `addNodeRenderer`; Phase 3 added
+ * SSR HTML generation + bundled shiki. Phase 4 promotes the warn-noop
+ * `addEmbedTag` / `addUrlInlineExpander` to live registrations.
+ */
+/**
+ * Identifier for the unified pipeline phase a plugin wants to attach a
+ * `unified` transformer to. Phase 2 only honours `'transform'`; `'pre'`
+ * is reserved for Phase 3 (parse-time tweaks before remark-gfm) and
+ * `'post'` for the future hydrate phase.
+ */
+type RenderPhase = 'pre' | 'transform' | 'post';
+/**
+ * mdast node type → custom AST visitor. Plugins use this when they want
+ * to mutate a specific node type (e.g. rewrite `code` blocks, swap
+ * `link` targets) without writing a full unified transformer. The
+ * runtime invokes the renderer once per matching node, depth-first.
+ *
+ * The `node` parameter is intentionally typed loosely (`unknown`) at
+ * this contract layer; plugins narrow at the call site against the
+ * mdast type they registered for.
+ */
+interface NodeRenderer {
+    (node: unknown, ctx: RenderContext): void | Promise<void>;
+}
+/**
+ * Code-block renderer — invoked for fenced code blocks whose `lang`
+ * matches the registered language tag (e.g. `mermaid`, `plantuml`,
+ * `katex`). Phase 6 lights this up.
+ *
+ * Shape mirrors `EmbedRenderer`: a required `cacheVersion` so the core
+ * can route renders through the same SWR + error-cache wrapper, an
+ * optional `reservation` for layout-stable placeholders, and an
+ * optional `computeEmbedKey` override (the default hashes
+ * `{lang, source}`).
+ *
+ * Phase 4 declared a bare callable; Phase 6 expands the shape to an
+ * object so plugins can declare cacheVersion / reservation alongside
+ * `render`. This is non-breaking because the Phase 4 stub discarded all
+ * registrations — there is no production implementer to migrate.
+ */
+interface CodeBlockRenderer {
+    /**
+     * Bumped by the plugin whenever the rendered HTML shape changes.
+     * Read-side cache hits ignore entries with a stale version, so
+     * version bumps are an instant "invalidate all my cached output"
+     * without operator action.
+     */
+    cacheVersion: number;
+    /**
+     * Optional placeholder declaration. Used in the same two cases as
+     * `EmbedRenderer.reservation`: layout placeholder while rendering,
+     * and fall-back when cache rejects on size limit or `render` errors.
+     */
+    reservation?: Reservation;
+    /**
+     * Optional custom cache-key computer. Default = sha256(JSON.stringify({
+     * lang, source})). Plugins can override to canonicalise whitespace,
+     * strip comments, etc.
+     */
+    computeEmbedKey?(info: CodeBlockInfo): string;
+    /** Render a single code block. */
+    render(info: CodeBlockInfo, ctx: RenderContext): EmbedFragment | RenderResult | Promise<EmbedFragment | RenderResult>;
+}
+interface CodeBlockInfo {
+    /** The language tag from the fence (the `ts` in ```` ```ts ````). */
+    lang: string;
+    /** Raw fenced source (no surrounding backticks). */
+    source: string;
+}
+/**
+ * Embed-tag renderer — invoked for `@[tag](url)` embeds whose `tag`
+ * matches a registered name. The plugin receives the parsed `EmbedInput`
+ * and returns a `RenderResult` containing pre-sanitised HTML plus
+ * optional cache + reservation metadata. Phase 4 dispatches via the
+ * cache wrapper; the result is persisted into MongoDB
+ * `PluginRenderCache` keyed by `(pluginName, pluginCacheVersion, pageId,
+ * embedKey)`.
+ *
+ * The renderer is responsible for HTML sanitisation. The core does NOT
+ * escape `RenderResult.html` and trusts the plugin's output.
+ */
+interface EmbedRenderer {
+    /**
+     * Bumped by the plugin whenever the rendered HTML shape changes.
+     * Read-side cache hits ignore entries with a stale version, so
+     * version bumps are an instant "invalidate all my cached output"
+     * without operator action.
+     */
+    cacheVersion: number;
+    /**
+     * Optional placeholder declaration. Used in two cases:
+     *   1. While rendering for the first time (mode: 'edit' or cache
+     *      stampede protection), the core renders this reservation so
+     *      page layout doesn't shift when the real HTML lands.
+     *   2. When `render()` rejects or the cached entry exceeds size
+     *      limits, the core falls back to a reservation-shaped
+     *      placeholder.
+     */
+    reservation?: Reservation;
+    /**
+     * Optional custom cache-key computer. Phase 4 defaults to
+     * `sha256(JSON.stringify(input))` when omitted — that covers
+     * arg-only inputs. Plugins can override to (a) ignore query-string
+     * volatility (`?utm_*`) or (b) include external state (Accept-Language).
+     */
+    computeEmbedKey?(input: EmbedInput): string;
+    /** Render a single embed. */
+    render(input: EmbedInput, ctx: RenderContext): RenderResult | Promise<RenderResult>;
+    /**
+     * Optional batched render for plugins that can amortise a single
+     * upstream call across N inputs (Phase 7+ GitHub GraphQL).
+     * Phase 4 registry impl calls `render` 1 input at a time; this
+     * field is reserved for the Phase 7 batching path.
+     */
+    renderBatch?(inputs: EmbedInput[], ctx: RenderContext): Promise<RenderResult[]>;
+}
+/**
+ * What an `EmbedRenderer` receives. Phase 4 plumbs `tag` + `url` from
+ * `@[tag](url)`; plugins are free to pull additional state via
+ * `RenderContext.auth.config<S>()` (Phase 7) or
+ * `RenderContext.pageMetadata`.
+ */
+interface EmbedInput {
+    /** The bracketed tag — `[A-Za-z0-9_-]{1,64}`. */
+    tag: string;
+    /** The parenthesised URL. Free-form; plugins validate per-renderer. */
+    url: string;
+    /** Page id the embed is being rendered for; cache key includes this. */
+    pageId: string;
+}
+/**
+ * What an `EmbedRenderer` returns. Phase 4 caches the whole `RenderResult`
+ * (html + error meta + ttl) so a subsequent read can short-circuit.
+ * Stale-while-revalidate uses `ttlSec * DEFAULT_STALE_MULTIPLIER` as the
+ * background-refresh window (see
+ * `packages/api/src/renderer/cache/index.ts:cachedRender`).
+ */
+interface RenderResult {
+    /** Already-sanitised HTML the core will inline. */
+    html: string;
+    /**
+     * Optional `<head>`-bound assets — Phase 4 records them on the
+     * cache entry but the SSR layer does not yet inject them. Phase 7
+     * will close that loop together with `hydrate` script wiring.
+     */
+    assets?: {
+        css?: string[];
+        js?: string[];
+    };
+    /**
+     * How long the entry stays fresh. After this, reads still get the
+     * cached html but a background re-render is scheduled.
+     *
+     * Default 300s (5 minutes) when omitted. Error responses ignore
+     * `ttlSec` and use the per-code defaults from `RENDER_ERROR_TTL`.
+     */
+    ttlSec?: number;
+    /**
+     * When the render failed (network / auth / not_found / rate_limit /
+     * timeout / unknown), plugins should set `error` instead of building
+     * an html error frame. The core caches the error using `RENDER_ERROR_TTL`
+     * and substitutes a fixed placeholder when re-rendering the page.
+     */
+    error?: RenderError;
+}
+/**
+ * Error categories cached with their own per-code TTLs. See
+ * `packages/api/src/renderer/cache/index.ts:RENDER_ERROR_TTL` for the
+ * concrete numbers.
+ */
+interface RenderError {
+    code: 'auth' | 'rate_limit' | 'not_found' | 'network' | 'timeout' | 'unknown';
+    /** Free-form text for log/debug — NOT inlined into the user-facing placeholder. */
+    message?: string;
+    /**
+     * Server-supplied retry-after hint in seconds. When set on a
+     * `rate_limit` error, it overrides the default 5min TTL.
+     */
+    retryAfterSec?: number;
+}
+/**
+ * Placeholder shape declaration. Three variants align with the typical
+ * embed shapes we anticipate:
+ *
+ *   - `fixed`: pixel-precise (e.g. exact-size avatar / icon)
+ *   - `aspect`: responsive width with a locked aspect ratio
+ *     (e.g. video thumbnail)
+ *   - `card`: small / medium / large card style for link-preview-y
+ *     embeds where the exact size flexes with available width
+ *
+ * Numbers are plugin-declared and treated as trusted — they are
+ * interpolated into the placeholder HTML's inline style. User-supplied
+ * tag args never reach style values.
+ */
+type Reservation = {
+    variant: 'fixed';
+    widthPx?: number;
+    heightPx: number;
+} | {
+    variant: 'aspect';
+    aspectRatio: number;
+} | {
+    variant: 'card';
+    size: 'small' | 'medium' | 'large';
+};
+/**
+ * URL inline-expansion rule — when an inline link target matches the
+ * registered host / pattern, the plugin can inline-expand the link to
+ * a richer fragment (e.g. GitHub issue card). Phase 4 lights this up
+ * through the `core/url-inline-expand.ts` transform; plugins return
+ * either `'replaced'` (HTML to substitute) or `'unchanged'` (let the
+ * next expander try, falling through to plain autolink).
+ */
+interface UrlInlineExpansionRule {
+    /** Bumped to invalidate cached expansions, same semantics as `EmbedRenderer.cacheVersion`. */
+    cacheVersion: number;
+    /** Pattern the URL must match. RegExp or substring matcher. */
+    match: RegExp | ((url: string) => boolean);
+    /** Produce the expanded fragment OR signal "no opinion, fall through". */
+    expand: (url: string, ctx: RenderContext) => InlineExpansion | Promise<InlineExpansion>;
+}
+/** Result of an `UrlInlineExpansionRule.expand` call. */
+type InlineExpansion = {
+    kind: 'unchanged';
+} | ({
+    kind: 'replaced';
+} & RenderResult);
+/**
+ * The fragment a code-block renderer produces (Phase 6). Kept in the
+ * contract so Phase 6 plugins type-check against the final shape.
+ */
+interface EmbedFragment {
+    /** Pre-sanitised HTML fragment to inline at the source position. */
+    html: string;
+    /** Optional `<head>`-bound assets (CSS / JS) keyed by URL. */
+    assets?: {
+        css?: string[];
+        js?: string[];
+    };
+}
+/**
+ * Shared key shape for `CacheStorage.get` / `set`. The 4-tuple
+ * `(pluginName, pluginCacheVersion, pageId, embedKey)` is the unique
+ * compound index on `PluginRenderCache`. `pluginCacheVersion` lives in
+ * the key (not just on the document) so reads can early-out without a
+ * second roundtrip when the plugin bumped its version.
+ */
+interface CacheKey {
+    pluginName: string;
+    pluginCacheVersion: number;
+    pageId: string;
+    embedKey: string;
+}
+/**
+ * What `CacheStorage.get` returns on a hit. `fetchedAt` lets the SWR
+ * wrapper decide fresh / stale / expired without doing a second `now()`
+ * roundtrip; `expiresAt` is the TTL deadline written when the entry
+ * was last set.
+ */
+interface CacheEntry {
+    html: string;
+    result: RenderResult;
+    fetchedAt: Date;
+    expiresAt: Date;
+}
+/**
+ * MongoDB-backed cache surface. Phase 4 ships exactly one
+ * implementation (`packages/api/src/renderer/cache/mongodb-cache.ts`);
+ * the interface is abstracted so a future Redis hot tier can plug in
+ * without contract changes.
+ *
+ * Plugins access a **per-plugin scoped** view of this interface
+ * (`RenderContext.cache`): the runtime auto-stamps `pluginName` on
+ * every `get` / `set` so a plugin cannot read / write another plugin's
+ * cache.
+ */
+interface CacheStorage {
+    get(key: CacheKey): Promise<CacheEntry | null>;
+    set(key: CacheKey, entry: CacheEntry): Promise<void>;
+    /** Drop every entry for a page; returns the number of deleted rows. */
+    invalidatePage(pageId: string): Promise<number>;
+    /** Drop every entry written by a plugin; returns the number of deleted rows. */
+    invalidatePlugin(pluginName: string): Promise<number>;
+    /** Drop every cached entry; returns the number of deleted rows. */
+    invalidateAll(): Promise<number>;
+}
+/**
+ * Per-plugin scoped cache surface handed to a plugin via
+ * `RenderContext.cache`. Same shape as `CacheStorage` minus the
+ * `pluginName` requirement on key — the runtime stamps it.
+ */
+interface ScopedCacheStorage {
+    get(key: Omit<CacheKey, 'pluginName'>): Promise<CacheEntry | null>;
+    set(key: Omit<CacheKey, 'pluginName'>, entry: CacheEntry): Promise<void>;
+    /** Convenience for plugin-driven invalidation. Always scoped to this plugin. Returns deleted count. */
+    invalidatePage(pageId: string): Promise<number>;
+}
+/**
+ * Authentication context for plugins that need to look up their own
+ * (encrypted) config / per-user tokens.
+ *
+ * **Phase 4 ships the interface only.** The registry impl in
+ * `packages/api/src/renderer/registry.ts` throws
+ * `Error('AuthContext not yet implemented — Phase 7')` from the
+ * `config()` callsite. Phase 7 will wire this against RFC-0001's
+ * encrypted-config lookup and a per-plugin namespace.
+ *
+ * Phase 6 no-I/O plugins (PlantUML / KaTeX / Mermaid / emoji) must NOT
+ * call `AuthContext.config()` — they are no-I/O by definition. The
+ * thrown-error stub will surface accidental coupling immediately.
+ */
+interface AuthContext {
+    /**
+     * Parse this plugin's encrypted config row through the supplied
+     * Zod schema and return the typed values. Throws on Phase 4 (stub).
+     */
+    config<S extends z.ZodTypeAny>(schema: S): z.infer<S>;
+}
+/**
+ * Context passed to every renderer callback. Phase 2 exposed `mode` +
+ * `log`; Phase 4 adds `cache` (per-plugin scoped) and `auth` (interface
+ * only; throws on access). Existing core plugins (headings / wikilinks
+ * / mentions / code-blocks / syntax-highlight) do not read `cache` or
+ * `auth` so the addition is non-breaking.
+ */
+interface RenderContext {
+    /**
+     * What the pipeline is being run for. `'save'` = persisting a new
+     * revision (cache writes are appropriate); `'read'` = on-the-fly
+     * fallback for an old revision; `'view'` = view-mode page render
+     * (cache reads + writes); `'edit'` = edit-mode draft (Phase 7 will
+     * special-case this to return placeholder only).
+     *
+     * Phase 4 treats `'view'` and `'edit'` identically — both run the
+     * cached render path. The branching is reserved for Phase 7 where
+     * the edit-mode Yjs integration lands.
+     */
+    mode: 'save' | 'read' | 'view' | 'edit';
+    /** Structured logger scoped to the registering plugin. */
+    log: PluginLogger;
+    /**
+     * Per-plugin scoped cache. Provided to `EmbedRenderer.render` /
+     * `UrlInlineExpansionRule.expand` callsites by the dispatch layer.
+     * Absent on the core-transform path (headings / wikilinks / mentions /
+     * code-blocks / syntax-highlight never consult the cache), so the
+     * field is optional and consumers that do need it can rely on the
+     * dispatch layer always providing it.
+     */
+    cache?: ScopedCacheStorage;
+    /**
+     * Auth surface. Phase 4 stub: `config()` throws when called. Absent on
+     * the core-transform path; provided by the dispatch layer to embed
+     * renderer / inline-expander callsites. Phase 7 will wire the real
+     * encrypted-config-backed implementation.
+     */
+    auth?: AuthContext;
+}
+/**
+ * The registry handed to every plugin's `registerRenderer(scope, ctx)`.
+ * Each method tags the registration with the registering plugin so the
+ * runtime can attribute warnings ("plugin X tried to register
+ * something the runtime doesn't support yet").
+ *
+ * Phase 4 honours:
+ *   - `addUnifiedPlugin(plugin, { phase: 'transform' })`
+ *   - `addNodeRenderer(type, renderer)`
+ *   - `addEmbedTag(name, renderer)` — last-wins + boot warn on collision
+ *   - `addUrlInlineExpander(rule)` — registration-order list
+ *
+ * Phase 4 stubs (warn-noop):
+ *   - `addCodeBlockRenderer` (Phase 6 lights this up)
+ */
+interface RendererRegistry {
+    /**
+     * Append a `unified` transformer plugin. `options.phase` controls
+     * whether it runs before the parser tweaks (`'pre'`), after the core
+     * 4 transforms (`'transform'`), or in the hydrate phase (`'post'`).
+     * Phase 2: only `'transform'` is honoured; other phases warn-noop.
+     *
+     * The plugin signature follows unified.js conventions
+     * (`() => (tree, file) => void`). Typed loosely here so plugins can
+     * pull `unified` themselves without the contract dragging in the
+     * dep.
+     */
+    addUnifiedPlugin(plugin: unknown, options?: {
+        phase?: RenderPhase;
+    }): void;
+    /**
+     * Register a per-mdast-node-type renderer. The runtime walks the
+     * tree once and dispatches each node to every renderer registered
+     * for its `type`, in registration order.
+     */
+    addNodeRenderer(type: string, renderer: NodeRenderer): void;
+    /**
+     * Register a code-block renderer for a language tag. Phase 4 warns
+     * and discards. Phase 6 lights this up.
+     */
+    addCodeBlockRenderer(lang: string, renderer: CodeBlockRenderer): void;
+    /**
+     * Register an embed-tag renderer for `@[name](url)`. Collisions are
+     * resolved last-wins with a boot-time warn (see RFC §"Plugin tag
+     * collision").
+     */
+    addEmbedTag(name: string, renderer: EmbedRenderer): void;
+    /**
+     * Register a URL inline-expansion rule. Order of registration is
+     * preserved; the first match that returns `'replaced'` wins.
+     */
+    addUrlInlineExpander(rule: UrlInlineExpansionRule): void;
+}
+
+/**
+ * Scope passed to `registerRoutes`. The HTTP route contribution surface
+ * for plugins is **not currently wired** to the runtime — it has never
+ * been invoked end-to-end. RFC-0006 Phase 6 removed the framework
+ * dependency that previously typed the contract argument; the API
+ * surface is therefore a deliberate no-op stub until a follow-up RFC
+ * redesigns plugin HTTP contribution on top of Hono.
+ *
+ * Plugins that declare a `registerRoutes` callback today see it
+ * receive this scope and call `scope.register(...)` with arbitrary
+ * arguments — both arguments are accepted as `unknown` and the call
+ * is silently dropped. The type fixture exists so the public surface
+ * of `@crowi/plugin-api` keeps compiling against existing plugin
+ * sources (including the in-tree `__fixtures__/example-plugin.ts`)
+ * without forcing every plugin to be updated in lockstep with Phase 6.
+ */
+interface PluginRouterScope {
+    /**
+     * No-op register. Both arguments are typed as `unknown` because the
+     * runtime never reads them; concrete shapes are reserved for the
+     * follow-up RFC that wires plugin HTTP contribution onto Hono.
+     */
+    register(contract: unknown, implementation: unknown): void;
+}
+
+/**
+ * The contract every Crowi plugin satisfies. Plugins export their
+ * `CrowiPlugin` object as the package's default export; the runtime
+ * imports it via `await import('<plugin-name>')` at boot.
+ *
+ * Every `register*` callback is optional — implement only the
+ * extension points your plugin actually contributes to. A storage-only
+ * plugin needs only `registerStorage`; an auth provider that also
+ * exposes admin "Test connection" needs `registerAuth` plus
+ * `registerRoutes`.
+ */
+interface CrowiPlugin {
+    /**
+     * Stable npm package name. Doubles as the namespace prefix for this
+     * plugin's config rows (`plugin:<name>:*`) and per-Page metadata
+     * (`page.metadata['<name>']`). Must match the `name` field in the
+     * package's `package.json`.
+     */
+    name: string;
+    /**
+     * The plugin's own version (matches the npm package's semver).
+     * Surfaced in `crowi plugin list` and emitted in boot logs.
+     */
+    version: string;
+    /**
+     * Other plugins this plugin needs at runtime, by npm name (e.g.
+     * `['@crowi/plugin-aws']`). The PluginManager resolves the dependency graph
+     * at boot and loads `requires` first; cycles fail boot.
+     */
+    requires?: string[];
+    /**
+     * Zod schema describing this plugin's *global* configurable values.
+     * The admin UI generates a config form by walking this schema.
+     *
+     * Mark sensitive fields with the `@sensitive` description marker
+     * (see `SENSITIVE_FIELD_MARKER`); they are encrypted at rest via the
+     * same KeyProvider used by core's sensitive Config.
+     *
+     * Mark fields that need a "Test connection" / "Authorise" button
+     * with `@action <button-label> <verb> <path>` (see
+     * `ACTION_FIELD_MARKER`); the form renders an extra button next to
+     * the field that calls the plugin's contributed REST endpoint.
+     */
+    configSchema?: z.ZodObject<Record<string, z.ZodTypeAny>>;
+    /**
+     * Per-Page metadata schema. When set, every Page document has a
+     * `metadata['<plugin-name>']` slot whose shape matches this schema,
+     * and the page-edit UI renders a section for the plugin where the
+     * operator can fill in those values per-page.
+     *
+     * Use case: Slack channel mapping per page (`{ channel: '#eng' }`),
+     * custom page metadata for downstream integrations.
+     */
+    pageMetadataSchema?: z.ZodObject<Record<string, z.ZodTypeAny>>;
+    /**
+     * How this plugin appears in the admin sidebar. Optional — when
+     * omitted, the runtime derives the section from the plugin's
+     * `register*` hooks (registerStorage → 'storage', registerAuth →
+     * 'auth', etc.). Plugins with no register* hooks (config-only
+     * "base plugins" like `@crowi/plugin-aws`) MUST declare `section: 'shared'`
+     * to appear in the sidebar at all.
+     *
+     * `label` overrides the default sidebar text (which would otherwise
+     * be the plugin's npm name). `icon` is the lucide-react icon name
+     * (e.g. `'cloud'`, `'database'`); admin sidebar only renders icons
+     * from a fixed allow-list to keep the bundle small.
+     */
+    adminPlacement?: {
+        section?: 'settings' | 'shared' | 'storage' | 'mail' | 'notification' | 'auth' | 'search' | 'renderer';
+        label?: string;
+        icon?: string;
+    };
+    /**
+     * Optional localized overrides for the admin config-form field labels and
+     * descriptions, keyed by locale then by `configSchema` field name. The
+     * admin API overlays the entry matching the requesting admin's locale on
+     * top of the schema-derived field; the Zod `.describe()` text stays the
+     * (English) default when a locale or field is missing. Lets a plugin ship
+     * its own translations without the host app knowing about them.
+     *
+     * @example
+     * configI18n: {
+     *   ja: { serverUrl: { description: 'PlantUML サーバーのベース URL。' } },
+     * }
+     */
+    configI18n?: Record<string, Record<string, {
+        label?: string;
+        description?: string;
+    }>>;
+    /** Storage driver registration. Called once at boot. */
+    registerStorage?: (registry: StorageRegistry, ctx: PluginContext) => void;
+    /** Search backend registration. Called once at boot. */
+    registerSearch?: (registry: SearchRegistry, ctx: PluginContext) => void;
+    /** Auth provider registration. Called once at boot. */
+    registerAuth?: (registry: AuthRegistry, ctx: PluginContext) => void;
+    /** Notification sink registration. Called once at boot. */
+    registerNotifier?: (registry: NotifierRegistry, ctx: PluginContext) => void;
+    /**
+     * Mail sender (transport) registration. Called once at boot. Exactly
+     * one registered driver is active, selected by
+     * `crowi.config.json:mail.driver` (default `'smtp'`). The core
+     * assembles the message; the driver only delivers it.
+     */
+    registerMailSender?: (registry: MailSenderRegistry, ctx: PluginContext) => void;
+    /**
+     * Renderer extension registration. Called once at boot, AFTER the
+     * core bundled renderer (TOC / wikilinks / mentions / code-block
+     * languages) has already populated the registry. Phase 2 honours
+     * `addUnifiedPlugin({ phase: 'transform' })` and `addNodeRenderer`;
+     * other registrations warn-noop until Phase 3. See RFC-0002.
+     */
+    registerRenderer?: (registry: RendererRegistry, ctx: PluginContext) => void;
+    /**
+     * Event subscription registration. Reserved for v2.0 internal use;
+     * not yet a stable extension point for community plugins.
+     */
+    registerHooks?: (events: EventBus, ctx: PluginContext) => void;
+    /**
+     * ts-rest contract that the plugin contributes. Mounted at
+     * `/api/v2/plugins/<name>/*` (the `<name>` path segment guarantees
+     * that core endpoints and other plugins cannot collide). Used for
+     * "Test connection" buttons, OAuth callbacks, custom admin views,
+     * etc. The contract surface uses ts-rest so the admin UI can call
+     * plugin endpoints with the same `apiClient.<plugin>.<method>` shape
+     * it uses for core endpoints.
+     */
+    registerRoutes?: (scope: PluginRouterScope, ctx: PluginContext) => void;
+    /**
+     * Run-once setup when this plugin is first activated. Typically used
+     * for legacy v1.x → v2.0 config migration: copy `upload:aws:*` rows
+     * into `plugin:<name>:*`, etc. Idempotent — the runtime tracks which
+     * plugins have already had `onInstall` invoked and skips on subsequent
+     * boots.
+     */
+    onInstall?: (ctx: PluginContext) => Promise<void>;
+    /**
+     * Symmetric to `onInstall`; called when the plugin is removed via
+     * `crowi plugin remove`. Note: by default config rows are *kept*
+     * (the operator may reinstall later) — `onUninstall` runs only when
+     * `--purge` is passed.
+     */
+    onUninstall?: (ctx: PluginContext) => Promise<void>;
+    /**
+     * Called when this plugin's own config (`plugin:<name>:*`) or any of
+     * its `requires` dependency configs change via the admin UI / API.
+     * Implementations should refresh any cached state — clients,
+     * connection pools, derived values — so subsequent driver method
+     * calls see the new values.
+     *
+     * Optional. If omitted, the plugin is treated as "config changes
+     * require a server restart" (back-compat for the existing
+     * register-once / closure-captured driver pattern).
+     *
+     * Best-effort: a thrown error is logged and reported to the admin
+     * UI but does NOT crash the server — that would lock operators out
+     * of the very UI they need to fix the misconfiguration.
+     */
+    reconfigure?: (ctx: PluginContext) => void | Promise<void>;
+}
+
+/**
+ * `configSchema` description-string markers.
+ *
+ * The admin UI walks the schema and looks at each field's
+ * `description` (set via `z.string().describe('@sensitive ...')`). A
+ * description starting with one of these marker tokens unlocks special
+ * UI behaviour without forcing every field to declare a custom Zod
+ * type.
+ */
+/**
+ * Marker that flags a config field as sensitive (encrypted at rest).
+ * Usage:
+ *
+ *   z.string().describe('@sensitive AWS secret access key')
+ *
+ * The runtime auto-encrypts on write and decrypts on read, using the
+ * same KeyProvider as core sensitive Config. The admin UI renders the
+ * field via `<SecretField>` (saved badge / clear pending / undo).
+ */
+declare const SENSITIVE_FIELD_MARKER = "@sensitive";
+/**
+ * Marker that adds an action button next to a config field. Usage:
+ *
+ *   z.string().describe('@action "Test connection" POST /test')
+ *
+ * The admin form renders a button with the given label that calls the
+ * plugin's contributed endpoint at the given verb / path (relative to
+ * `/api/v2/plugins/<name>/`). Useful for "Test connection",
+ * "Authorise with Google", etc. without forcing every plugin to ship
+ * its own React component.
+ */
+declare const ACTION_FIELD_MARKER = "@action";
+/**
+ * True if the schema field is marked `@sensitive`.
+ *
+ * `field` is `z.ZodTypeAny` (intentionally loose); call sites pass the
+ * value type from `configSchema.shape[key]`.
+ */
+declare function isSensitiveField(field: z.ZodTypeAny): boolean;
+/**
+ * Parsed `@action` annotation extracted from a field's `description`.
+ */
+interface ActionAnnotation {
+    /** Visible button label, e.g. "Test connection". */
+    label: string;
+    /** HTTP verb of the plugin endpoint to call. */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** Path relative to `/api/v2/plugins/<name>/`, with leading slash. */
+    path: string;
+}
+/**
+ * Parse an `@action` annotation off a field, or return null if absent.
+ *
+ * Format: `@action "<label>" <METHOD> <path>`
+ *   e.g. `@action "Test connection" POST /test`
+ *
+ * The label may include spaces when wrapped in double quotes; the
+ * method is one of `GET` / `POST` / `PUT` / `DELETE`; the path begins
+ * with `/`.
+ */
+declare function getActionAnnotation(field: z.ZodTypeAny): ActionAnnotation | null;
+
+export { ACTION_FIELD_MARKER, type AuthContext, type AuthDriver, type AuthProfile, type AuthRegistry, type AuthVerifyResult, type CacheEntry, type CacheKey, type CacheStorage, type CodeBlockInfo, type CodeBlockRenderer, type CrowiPlugin, type EmailMessage, type EmbedFragment, type EmbedInput, type EmbedRenderer, type EventBus, type InlineExpansion, type MailSender, type MailSenderRegistry, type NodeRenderer, type NotificationPayload, type NotifierDriver, type NotifierRegistry, type PageMetadataAccessor, type PluginContext, type PluginCrypto, type PluginEvents, type PluginLogger, type PluginRouterScope, type RenderContext, type RenderError, type RenderPhase, type RenderResult, type RendererRegistry, type Reservation, SENSITIVE_FIELD_MARKER, type ScopedCacheStorage, type SearchDriver, type SearchHit, type SearchHits, type SearchPageType, type SearchQuery, type SearchQueryGrants, type SearchQueryViewer, type SearchRegistry, type SearchableDoc, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type UrlInlineExpansionRule, getActionAnnotation, isSensitiveField };