@crowi/plugin-api 0.1.0-alpha.1 → 1.0.0-alpha.10

package/dist/index.d.ts

@@ -1,11 +1,41 @@
 import { z } from 'zod/v3';
 import { Readable } from 'node:stream';
+import { Configuration } from 'openid-client';
+import { Context } from 'hono';
 
 /**
  * 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.
+ * logging) — plugins must NOT import from `@crowi/server` directly to
+ * keep the contract surface thin.
+ *
+ * Trust boundary: a plugin only reaches what it explicitly declares, and
+ * a plugin cannot reach another plugin's or core's secrets through
+ * `PluginContext`:
+ *
+ * - `model(name)` is gated by the plugin's own `CrowiPlugin.modelAccess`
+ *   allow-list (see `model()` below) — there is no ambient "any core
+ *   model" access. Credential-vault models (`Config`,
+ *   `PersonalAccessToken`, OAuth client/token/grant models, `Share`,
+ *   `ShareAccess`) can never be granted at all: declaring one in
+ *   `modelAccess` fails boot, and `model()` refuses to return one at
+ *   call time even if that check were somehow bypassed.
+ * - There is intentionally no symmetric encrypt/decrypt capability on
+ *   this context: the only legitimate secret-reading path is
+ *   `config<T>()`, which already hands back `@sensitive` fields
+ *   transparently decrypted for *this* plugin's own config.
+ * - `dependencyConfig<T>(name)` only returns another plugin's config —
+ *   `@sensitive` fields included — when that plugin has explicitly
+ *   opted in via `CrowiPlugin.exposesConfigToDependents: true`. Listing
+ *   a plugin in `requires` is not, by itself, enough to read its config.
+ *
+ * One caveat remains, intentionally out of scope for this trust
+ * boundary: a plugin granted `modelAccess: ['User']` gets the raw
+ * Mongoose document, password hash included — there is no field
+ * projection today. Field-level read/write proxying for `User` (and any
+ * other model) is deferred to a post-2.0 repository/HTTP layer
+ * separation; until then, only grant `User` `modelAccess` to plugins you
+ * trust with that document as a whole.
  */
 interface PluginContext {
     /**
@@ -20,33 +50,141 @@ interface PluginContext {
      * 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.
+     * violation and throws. In addition, the target plugin must have
+     * opted in with `CrowiPlugin.exposesConfigToDependents: true` —
+     * `requires` alone is only this plugin's side of the contract, not
+     * permission granted by the dependency. Throws when the dependency
+     * has not opted in.
      *
-     * 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.
+     * Useful for shared-credential plugins like `@crowi/plugin-aws`,
+     * which sets `exposesConfigToDependents: true` because sharing
+     * `region` / `accessKeyId` / `secretAccessKey` with dependents
+     * (`@crowi/plugin-storage-aws-s3`, `@crowi/plugin-mail-aws-ses`) is
+     * its entire purpose — they read them through this method instead of
+     * duplicating the fields in their own configSchema. Most plugins do
+     * not opt in, so most `dependencyConfig` calls against them throw.
      */
     dependencyConfig<T>(dependencyName: string): T;
+    /**
+     * Read core application info (the wiki name, …) — settings that live
+     * outside this plugin's own config namespace but that an integration
+     * may need (e.g. to brand an outbound manifest). Read live at call
+     * time, so it reflects admin edits made after boot.
+     */
+    appInfo(): AppInfo;
     /** 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.
+     * Mongoose model accessor, gated by this plugin's declared
+     * `CrowiPlugin.modelAccess` allow-list. Plugins touch core
+     * collections (Page, User, Comment, ...) through this accessor
+     * rather than importing model files directly.
+     *
+     * Throws when `name` is not listed in the plugin's `modelAccess` —
+     * a plugin must declare every core model it touches. A model name
+     * listed in `modelAccess` is returned with full (unrestricted)
+     * read/write access; there is no read-only proxying. Credential-vault
+     * models (`Config`, `PersonalAccessToken`, OAuth client/token/grant
+     * models, `Share`, `ShareAccess`) can never be listed in `modelAccess`
+     * at all — declaring one fails boot, and this method also refuses to
+     * return one at call time.
+     *
+     * Caveat: `modelAccess: ['User']` hands back the raw document,
+     * password hash included — there is no field projection today (see
+     * the trust-boundary note on this interface).
      *
      * 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;
+    /**
+     * Hot-reload state primitive. Returns a {@link StateCell} that holds a
+     * mutable value — the driver-owned resource (an S3 client, an SMTP
+     * transport, a search client, ...) that `reconfigure` rebuilds when
+     * admin saves new config. Every call across every `PluginContext`
+     * instance for this plugin (the activation-time `ctx` passed to
+     * `registerStorage`/`registerSearch`/`registerMailSender` etc., and
+     * every later `reconfigure(ctx)` call) returns the **same** cell — the
+     * runtime keys it by plugin name, not by `ctx` instance. `initial` is
+     * only used the first time this plugin ever calls `state()`; later
+     * calls ignore it and just return the existing cell.
+     *
+     * Use this instead of a module-scope `let`/`const` — it protects
+     * in-flight `withValue()` callers from a concurrent `set()` swapping
+     * the value out from under them, and gives `set()`'s `dispose` option
+     * a correct place to tear down the previous value (close a client,
+     * end a connection pool, ...) once nothing is still using it.
+     */
+    state<T>(initial: T): StateCell<T>;
+}
+/**
+ * A hot-reload-safe mutable cell, returned by `PluginContext.state()`.
+ * Designed for driver plugins (storage / search / mail / ...) that
+ * `reconfigure()` rebuilds a stateful resource for: `withValue()` marks
+ * the current value "in use" for the duration of the callback so a
+ * concurrent `set()` cannot tear it down mid-call, and `set()`'s
+ * `dispose` option only runs once every such in-flight caller has
+ * settled.
+ */
+interface StateCell<T> {
+    /**
+     * Atomic snapshot of the current value. Safe to read once and reuse
+     * across `await`s in the caller — but prefer {@link withValue} when the
+     * value may be disposed (e.g. an SDK client that `dispose` closes),
+     * since `get()` gives no in-flight protection.
+     */
+    get(): T;
+    /**
+     * Run `fn` against the current value while marking it "in use", so a
+     * concurrent `set()`'s `dispose` waits for `fn` to settle (resolve or
+     * reject) before tearing down the value `fn` captured. This is the
+     * primary way driver methods should read the cell.
+     */
+    withValue<R>(fn: (value: T) => R | Promise<R>): Promise<R>;
+    /**
+     * Swap in `next`. If `opts.dispose` is given, it runs — asynchronously,
+     * never inline — once every `withValue()` call that was in flight
+     * against the previous value at the moment of the swap has settled
+     * (immediately, on the next microtask, if none were in flight).
+     *
+     * `dispose` must handle (and log, if relevant) its own errors — a
+     * rejected `dispose` is swallowed by the runtime rather than
+     * surfaced anywhere, since there is no caller left waiting on it by
+     * the time it runs. Wrap the teardown in its own `try`/`catch` (or
+     * `.catch()`) instead of letting it throw.
+     */
+    set(next: T, opts?: {
+        dispose?: (prev: T) => void | Promise<void>;
+    }): void;
+}
+/**
+ * Read-only view of core application settings exposed to plugins via
+ * `ctx.appInfo()`. Intentionally a small, curated surface (not a generic
+ * "read any core config" escape hatch) — add fields here as concrete
+ * plugin needs appear.
+ */
+interface AppInfo {
+    /**
+     * The configured wiki name (core `app:title`), trimmed. Always a
+     * non-empty string: when the operator has not set a custom title it
+     * defaults to `'Crowi'` (the seed value), so consumers never have to
+     * handle an absent name.
+     */
+    title: string;
+    /**
+     * The wiki's public base origin (core `CLIENT_URL` / `getBaseUrl()`),
+     * e.g. `https://wiki.example.com`. An **empty string** when no public
+     * origin is configured — unlike `title` there is no sensible default,
+     * so a plugin that needs an absolute URL (outbound webhook / manifest)
+     * must handle the empty case. Plugins read this instead of
+     * `process.env.CLIENT_URL` directly.
+     */
+    baseUrl: string;
 }
 /**
  * Per-Page metadata read / write helper. Each plugin gets a private
@@ -62,10 +200,6 @@ interface PageMetadataAccessor {
     /** 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;
@@ -73,6 +207,161 @@ interface PluginLogger {
     error(message: string, ...args: unknown[]): void;
 }
 
+/**
+ * Contract for `CrowiPlugin.verifyConfig` — a non-blocking, post-save
+ * connectivity/permission probe (feature-plugin-config-live-verification).
+ * Deliberately its own module, separate from `context.ts`'s live
+ * `PluginContext`: a verification hook runs AFTER the admin save has
+ * already persisted (and after `reconfigure` has already rebuilt the live
+ * driver), against the EXACT values that request saved — not whatever the
+ * config cache holds by the time the hook actually runs. Handing a hook
+ * `PluginContext` would let it call `ctx.setConfig()` / read a
+ * concurrently-updated cache / touch models, none of which a read-only,
+ * best-effort probe should be able to do.
+ */
+/**
+ * Recursively read-only view of `T`. Used for both `config()` and
+ * `dependencyConfig()` on {@link PluginConfigVerificationSnapshot} — a
+ * verification hook must not be able to mutate the plan's materialized
+ * values (they are shared across the plan and, for a dependency, may be
+ * read by more than one hook).
+ */
+type ReadonlyDeep<T> = T extends readonly (infer U)[] ? readonly ReadonlyDeep<U>[] : T extends object ? {
+    readonly [K in keyof T]: ReadonlyDeep<T[K]>;
+} : T;
+/**
+ * Immutable facade a `verifyConfig` hook reads its plugin's (and its
+ * declared dependencies') config through. NOT `PluginContext`: this
+ * snapshot is materialized once, before the save that triggered
+ * verification, and never changes for the lifetime of the hook call — a
+ * concurrent save of another plugin's config (or of this plugin's config,
+ * from a second in-flight admin request) cannot change what an
+ * already-running hook sees. See `PluginManager.createVerificationPlan()`.
+ */
+interface PluginConfigVerificationSnapshot {
+    /**
+     * This plugin's own config, as it was — or will be, for the plugin whose
+     * save triggered this verification — immediately after the save. Throws
+     * if the plugin does not declare a `configSchema` (mirrors
+     * `PluginContext.config()`).
+     */
+    config<T>(): ReadonlyDeep<T>;
+    /**
+     * A declared dependency's config. Same capability check as
+     * `PluginContext.dependencyConfig()`: `dependencyName` must be listed in
+     * this plugin's `requires`, AND the dependency must declare
+     * `exposesConfigToDependents: true`. Throws otherwise.
+     */
+    dependencyConfig<T>(dependencyName: string): ReadonlyDeep<T>;
+}
+/**
+ * Passed alongside the snapshot to every `verifyConfig` call.
+ *
+ * `timeoutMs` is a NOTICE, not a cancellation mechanism: the caller
+ * (`PluginManager`) stops waiting on the hook's returned promise after
+ * this many milliseconds and normalizes the result to
+ * `{ status: 'failed', reason: 'unreachable' }`, but it never aborts the
+ * hook itself — there is no `AbortSignal` here, and none is passed down to
+ * any `StorageDriver` call a storage hook makes (the driver's public `put`
+ * / `get` / `delete` contract takes no such option; see
+ * `@crowi/plugin-api`'s `registries/storage.ts`). A hook whose underlying
+ * I/O is still in flight when the caller gives up keeps running in the
+ * background; hooks that touch external resources they created (e.g. a
+ * storage probe object) should not rely on ever being told to stop, and
+ * should clean up opportunistically rather than assume they'll get to run
+ * to completion before anyone stops watching.
+ */
+interface PluginConfigVerificationOptions {
+    timeoutMs: number;
+}
+/** The closed set of reasons a verification probe can fail for. Anything a driver can't confidently place in one of these falls into `'unknown'` — a wrong specific reason would mislead an operator more than an honest "couldn't tell". */
+type VerificationFailureReason = 'unreachable' | 'auth-failed' | 'resource-missing' | 'write-denied' | 'unknown';
+/**
+ * What a `verifyConfig` hook resolves to. Deliberately a closed,
+ * allow-listed shape — the caller projects whatever a hook returns onto
+ * this union (an invalid shape normalizes to `{ status: 'failed', reason:
+ * 'unknown' }`), so a hook can never smuggle raw SDK error text, a stack
+ * trace, an endpoint, or credential material into the admin response or
+ * logs by returning it as an extra field.
+ */
+type PluginConfigVerificationResult = {
+    status: 'ok';
+} | {
+    status: 'failed';
+    reason: VerificationFailureReason;
+};
+/**
+ * Key namespace every storage `verifyConfig` probe writes its round-trip
+ * object under — deliberately disjoint from `attachment/*` (core's
+ * uploaded-file namespace) so a probe object can never collide with,
+ * shadow, or get mistaken for a real attachment. A storage hook builds its
+ * probe key as `` `${CONFIG_VERIFICATION_KEY_PREFIX}<random>` ``; because
+ * cleanup after a probe is best-effort (see the `timeoutMs` note on
+ * {@link PluginConfigVerificationOptions}), an operator who finds a
+ * leftover object can safely delete anything under this prefix.
+ */
+declare const CONFIG_VERIFICATION_KEY_PREFIX = "__crowi_config_verification__/";
+
+/**
+ * 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;
+}
+
+/**
+ * HTML-emitting helper for renderer plugins.
+ *
+ * A renderer plugin that builds HTML from author-controlled or external
+ * strings (an OGP title, a math error message, …) must escape them, and
+ * that escape is a security primitive — a hardening change has to reach
+ * every plugin at once, not whichever local copies someone remembers.
+ * This is the SDK's single copy (`@crowi/plugin-renderer-katex` and
+ * `@crowi/plugin-renderer-link-card` each carried an identical local one
+ * before it was hoisted here).
+ */
+/** Escape `&` `<` `>` `"` `'` for interpolation into HTML text or double/single-quoted attribute values. */
+declare function escapeHtml(s: string): string;
+
 /**
  * Metadata accompanying a `put`. The runtime always provides
  * `contentType`; drivers are free to store additional fields under
@@ -270,8 +559,8 @@ interface AuthProfile {
     extra?: Record<string, unknown>;
 }
 /**
- * Result of `verify` — either a normalised profile (success) or an
- * error reason the login UI surfaces.
+ * Result of `verify` / `fetchProfile` — either a normalised profile
+ * (success) or an error reason the login UI surfaces.
  */
 type AuthVerifyResult = {
     ok: true;
@@ -280,38 +569,166 @@ type AuthVerifyResult = {
     ok: false;
     reason: string;
 };
+/** One field to render on a `credential` driver's sign-in form. */
+interface CredentialField {
+    /** Form field name, e.g. `'username'` / `'password'`. */
+    name: string;
+    /** Human-readable label rendered next to the field. */
+    label: string;
+    /** Input type. Defaults to `'text'` when omitted. */
+    type?: 'text' | 'email' | 'password';
+    required?: boolean;
+}
 /**
- * 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.
+ * Direct-credential auth: the user submits credentials to Crowi itself
+ * (LDAP, local password). No redirect, no external IdP round-trip.
  */
-interface AuthDriver {
+interface CredentialAuthDriver {
+    kind: 'credential';
+    /** Usually omitted — credential drivers render as the sign-in form. */
+    buttonLabel?: string;
+    /** Fields to render on the sign-in form (e.g. [username, password]). */
+    fields: CredentialField[];
+    verify(credentials: Record<string, string>): Promise<AuthVerifyResult>;
+}
+/**
+ * OAuth 2.0 / OIDC client credentials, read lazily at request time (see
+ * `getClientConfig()` below) rather than captured at registration.
+ */
+interface OAuthClientConfig {
+    clientId: string;
+    clientSecret: string;
+}
+/** Token response from an OAuth 2.0 / OIDC token endpoint. */
+interface OAuthTokens {
+    accessToken: string;
+    tokenType?: string;
+    expiresIn?: number;
+    refreshToken?: string;
+    scope?: string;
+    /** Present for an OIDC token response — the raw, still-unverified id_token JWT. */
+    idToken?: string;
+}
+/**
+ * Redirect/federated auth: the browser bounces to an external IdP using
+ * the plain OAuth 2.0 authorization-code flow (no id_token).
+ */
+interface OAuth2AuthDriver {
+    kind: 'oauth2';
+    buttonLabel: string;
+    iconUrl?: string;
+    authorizeUrl: string;
+    tokenUrl: string;
+    scopes: string[];
+    /** Declare when the IdP supports PKCE (S256). */
+    pkce?: boolean;
     /**
-     * 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.
+     * Lazy accessor, evaluated per request — NOT captured at registration.
+     * Returns null while the plugin is unconfigured; core then hides the
+     * provider from the provider list (enablement) and rejects `/start`.
+     * Lazy evaluation is also what makes admin config changes take effect
+     * without re-registering the driver.
      */
+    getClientConfig(): OAuthClientConfig | null;
+    /**
+     * Exchange completed; fetch the provider profile and map it. Returns
+     * `AuthVerifyResult` so the driver can REJECT after a successful
+     * exchange (e.g. an org-membership gate) — a successful exchange does
+     * not by itself guarantee a successful sign-in.
+     */
+    fetchProfile(tokens: OAuthTokens): Promise<AuthVerifyResult>;
+}
+/** OIDC = OAuth 2.0 + standardised discovery + id_token claims. */
+interface OidcAuthDriver {
+    kind: 'oidc';
     buttonLabel: string;
-    /** Optional icon URL for the login button. */
     iconUrl?: string;
+    /** `…/.well-known/openid-configuration` */
+    discoveryUrl: string;
+    /** Default `['openid', 'email', 'profile']`. */
+    scopes: string[];
+    /** OIDC always uses PKCE. */
+    pkce: true;
+    /** Same lazy contract as `OAuth2AuthDriver.getClientConfig()`. */
+    getClientConfig(): OAuthClientConfig | null;
+    /**
+     * Resolve (and cache) the `openid-client` `Configuration` for this
+     * driver's current credentials. Returns `null` without performing any
+     * network I/O while `getClientConfig()` is unconfigured. See the
+     * discovery-cache doc comment below for the caching contract.
+     */
+    getConfiguration(): Promise<Configuration | null>;
     /**
-     * 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.
+     * Optional policy gate, called after core validates the id_token and
+     * before `mapClaims` — the OIDC analogue of `fetchProfile`'s
+     * rejection (e.g. a Google Workspace `hd` domain restriction).
      */
-    verify(verificationData: unknown): Promise<AuthVerifyResult>;
+    authorize?(claims: Record<string, unknown>): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /** Optional claim → AuthProfile override; default maps sub/email/name. */
+    mapClaims?(claims: Record<string, unknown>): Partial<AuthProfile>;
 }
+/**
+ * `'saml'` is reserved (RFC-0014 §9) for a future `SamlAuthDriver` — it is
+ * a valid `AuthDriverKind` so downstream code can already discriminate on
+ * it, but no `SamlAuthDriver` interface exists yet and `AuthDriver` below
+ * does not include it as a member. SAML's required attributes and
+ * callback shape are still undecided; adding a member type ahead of that
+ * design would let a plugin construct a value with no real runtime.
+ */
+type AuthDriverKind = 'credential' | 'oauth2' | 'oidc' | 'saml';
+/**
+ * Auth provider driver. The login screen asks core for the list of
+ * registered drivers and renders one button per `oauth2`/`oidc` driver
+ * (`Sign in with Google`) or one sign-in form per `credential` driver.
+ * See RFC-0014 §3 for the full design rationale.
+ */
+type AuthDriver = CredentialAuthDriver | OAuth2AuthDriver | OidcAuthDriver;
 interface AuthRegistry {
     register(driverName: string, driver: AuthDriver): void;
 }
+interface CreateOAuth2DriverOptions {
+    buttonLabel: string;
+    iconUrl?: string;
+    authorizeUrl: string;
+    tokenUrl: string;
+    /** Defaults to `[]` when omitted. */
+    scopes?: string[];
+    pkce?: boolean;
+    getClientConfig(): OAuthClientConfig | null;
+    fetchProfile(tokens: OAuthTokens): Promise<AuthVerifyResult>;
+}
+/**
+ * Build a plain OAuth 2.0 authorization-code driver. Synchronous, I/O-free
+ * — see the module doc comment above.
+ */
+declare function createOAuth2Driver(options: CreateOAuth2DriverOptions): OAuth2AuthDriver;
+interface CreateOidcDriverOptions {
+    buttonLabel: string;
+    iconUrl?: string;
+    discoveryUrl: string;
+    /** Defaults to `['openid', 'email', 'profile']` when omitted. */
+    scopes?: string[];
+    getClientConfig(): OAuthClientConfig | null;
+    authorize?(claims: Record<string, unknown>): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    mapClaims?(claims: Record<string, unknown>): Partial<AuthProfile>;
+}
+/**
+ * Build an OIDC driver. Synchronous, I/O-free at call time — see the
+ * module doc comment above. `getConfiguration()` on the returned driver
+ * is the only entry point that performs discovery, and only on first use
+ * (see `resolveOidcConfiguration` below).
+ */
+declare function createOidcDriver(options: CreateOidcDriverOptions): OidcAuthDriver;
 
 /**
  * Notification payload — the runtime-neutral shape passed to every
@@ -431,52 +848,6 @@ interface MailSenderRegistry {
     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
@@ -558,9 +929,64 @@ interface CodeBlockRenderer {
      * strip comments, etc.
      */
     computeEmbedKey?(info: CodeBlockInfo): string;
+    /**
+     * Opt into a CPU-bounded admission control pool (`render-admission.ts`,
+     * `packages/api/src/renderer/core/render-admission.ts`). When present,
+     * `cachedRenderOrPending` (`packages/api/src/renderer/cache/index.ts`)
+     * and `renderCodeBlockForPreview` acquire a ticket from the named pool
+     * (keyed per `pluginName`) immediately around the `render()` call and
+     * release it on completion; when absent (the default — PlantUML /
+     * KaTeX / emoji and existing embed/URL-expansion plugins), `render()`
+     * is called directly with no admission gate, matching today's
+     * behaviour. See spec §6 for the full design (global / per-user
+     * concurrency caps + priority queue).
+     */
+    admissionControl?: AdmissionControlConfig;
+    /**
+     * Opt into server-rendering during editor live preview
+     * (`POST /pages/preview`, which runs with no `pageId`). Default
+     * `'source'` (omitted) leaves the fenced block untouched in preview —
+     * today's behaviour for every existing `CodeBlockRenderer`. Plugins
+     * that declare `'server-render'` MUST be no-I/O and deterministic:
+     * `makePreviewCodeBlockDispatch` calls them outside the persisted-
+     * cache path (`packages/api/src/renderer/core/code-block-dispatch.ts`).
+     */
+    previewPolicy?: 'source' | 'server-render';
     /** Render a single code block. */
     render(info: CodeBlockInfo, ctx: RenderContext): EmbedFragment | RenderResult | Promise<EmbedFragment | RenderResult>;
 }
+/**
+ * Per-`pluginName` admission-control pool declaration (§6). Shared by
+ * `CodeBlockRenderer` and `EmbedRenderer` — `EmbedRenderer` carries it so
+ * `code-block-dispatch.ts`'s `codeBlockAsEmbedRenderer` adaptor can copy
+ * `CodeBlockRenderer.admissionControl` straight through to the
+ * `EmbedRenderer` shape `cachedRenderOrPending` actually consumes.
+ */
+interface AdmissionControlConfig {
+    /** Process-wide concurrent `render()` calls in flight for this plugin. */
+    maxConcurrentGlobal: number;
+    /** Concurrent `render()` calls in flight for a single `actor` (kind:'user' only). */
+    maxConcurrentPerUser: number;
+    /** Max jobs allowed to wait for a slot before new requests are rejected outright. */
+    queueDepth: number;
+}
+/**
+ * Who is driving this render call. Threaded through `RenderContext` so
+ * admission control (§6) can apply a per-user concurrency cap. Today
+ * every real call site is authenticated (`createJwtAuth` has no
+ * anonymous fallback), so `'user'` is the only variant actually
+ * produced — `'anonymous'` / `'system'` are reserved for future
+ * unauthenticated-read and offline-tooling call sites and must not be
+ * synthesised speculatively.
+ */
+type RenderActor = {
+    kind: 'user';
+    userId: string;
+} | {
+    kind: 'anonymous';
+} | {
+    kind: 'system';
+};
 interface CodeBlockInfo {
     /** The language tag from the fence (the `ts` in ```` ```ts ````). */
     lang: string;
@@ -604,6 +1030,41 @@ interface EmbedRenderer {
      * volatility (`?utm_*`) or (b) include external state (Accept-Language).
      */
     computeEmbedKey?(input: EmbedInput): string;
+    /**
+     * Opt into admission control (§6). See `CodeBlockRenderer.admissionControl`
+     * for the full rationale — declared here too because `cachedRenderOrPending`
+     * (`packages/api/src/renderer/cache/index.ts`) is written against the
+     * `EmbedRenderer` shape (`code-block-dispatch.ts`'s
+     * `codeBlockAsEmbedRenderer` adaptor copies a `CodeBlockRenderer`'s
+     * declaration through unchanged). Native `EmbedRenderer` plugins
+     * (embed-tags / URL-inline-expansion) can also opt in if a future one
+     * turns out to be CPU-bound.
+     */
+    admissionControl?: AdmissionControlConfig;
+    /**
+     * Optional per-dispatch cache-bypass predicate
+     * (feature-renderer-plugin-boundary Phase 3). Checked by the generic
+     * embed-tag dispatcher (`packages/api/src/renderer/core/embed-tags.ts`)
+     * BEFORE it touches `CacheStorage` at all for this dispatch — no
+     * `get`, no `set`. When it returns `true`, the dispatcher calls
+     * `render()` directly (via the same `normalizeRenderResult` error
+     * normalisation the preview path uses) and never persists the
+     * result.
+     *
+     * This exists because a renderer whose behaviour is gated by a
+     * runtime policy toggle (e.g. link-card's admin
+     * `security:linkCardEnabled` switch) cannot enforce a literal
+     * zero-cache-access guarantee by checking the toggle only inside
+     * `render()` — a cache HIT from before the toggle flipped would
+     * short-circuit `render()` entirely and keep serving pre-toggle
+     * output (and, symmetrically, writing a toggled-off result to the
+     * cache would keep serving it for up to that entry's TTL after the
+     * toggle flips back). Declaring the check here instead makes the
+     * dispatcher skip the cache outright for that one call. Absent (the
+     * default) or returning `false` goes through the normal cached path
+     * unchanged.
+     */
+    shouldBypassCache?(input: EmbedInput): boolean;
     /** Render a single embed. */
     render(input: EmbedInput, ctx: RenderContext): RenderResult | Promise<RenderResult>;
     /**
@@ -635,9 +1096,36 @@ interface EmbedInput {
  * background-refresh window (see
  * `packages/api/src/renderer/cache/index.ts:cachedRender`).
  */
+/**
+ * RFC-0023 (design doc §12) — the structured (typed) counterpart of a
+ * producer's `html` output. Additive and optional everywhere: a plugin
+ * that never sets it keeps today's behaviour byte-for-byte.
+ *
+ * `node` is the producer-shaped typed node (`type` selects the sidecar
+ * kind — `'crowiDiagram'` / `'crowiLinkCard'` / `'crowiPlaceholder'`).
+ * Deliberately loose (`Record<string, unknown>`) at this SDK layer:
+ * `@crowi/plugin-api` does not depend on `@crowi/api-contract`, so the
+ * authoritative shape lives in the api-contract sidecar schemas and the
+ * api-side dispatch mapper validates against them before stamping a
+ * sidecar onto the persisted AST (invalid payloads degrade to a plain
+ * `html` node, never poisoning what the web reads).
+ */
+interface StructuredRenderPayload {
+    node: Record<string, unknown>;
+}
 interface RenderResult {
-    /** Already-sanitised HTML the core will inline. */
+    /** Already-sanitised HTML the core will inline. Unchanged — the one and only web/legacy representation. */
     html: string;
+    /**
+     * RFC-0023 — optional structured payload paired with `html`. Both
+     * must describe the SAME render outcome: the dispatch layer stamps
+     * this (schema-validated) as a sidecar on the `html` node it splices,
+     * and the `X-Crowi-Ast-Version: 1` projection turns it into a typed
+     * node. On an `error` result, pair it with `errorHtml` when the
+     * error display carries real content (e.g. link-card's fallback
+     * card); leave it unset to get the generic structured placeholder.
+     */
+    structured?: StructuredRenderPayload;
     /**
      * Optional `<head>`-bound assets — Phase 4 records them on the
      * cache entry but the SSR layer does not yet inject them. Phase 7
@@ -657,19 +1145,43 @@ interface RenderResult {
     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.
+     * timeout / unknown / blocked), plugins should set `error` instead of
+     * building an html error frame. The core caches the error using
+     * `RENDER_ERROR_TTL` and, absent `errorHtml`, substitutes a fixed
+     * placeholder when re-rendering the page.
      */
     error?: RenderError;
+    /**
+     * Optional failure-display HTML, paired with `error`. When `error` is
+     * set and `errorHtml` is present, the core shows `errorHtml` instead of
+     * the generic `errorPlaceholder()` — e.g. a link-card plugin can keep
+     * its URL clickable even when the OGP fetch failed. Same trust
+     * contract as `html`: **pre-sanitised, the core does not re-escape it**.
+     *
+     * Deliberately a separate field rather than "non-empty `html` + `error`
+     * means show `html`" — that shape makes a plugin's stray/forgotten
+     * `html` leak into the error display by accident. An explicit opt-in
+     * field means a plugin that hasn't been updated for `errorHtml` keeps
+     * the current safe-by-default behaviour (placeholder).
+     *
+     * Ignored when `error` is unset.
+     */
+    errorHtml?: string;
 }
 /**
  * Error categories cached with their own per-code TTLs. See
  * `packages/api/src/renderer/cache/index.ts:RENDER_ERROR_TTL` for the
- * concrete numbers.
+ * concrete numbers. `blocked` is a policy-level permanent rejection
+ * (SSRF block, disallowed scheme, disallowed content-type) — distinct
+ * from `not_found` semantically but sharing its 1h persistent-failure
+ * TTL. `busy` is a transient renderer-admission rejection (e.g. a
+ * shared fetch/render concurrency semaphore's wait queue was full, or a
+ * queued request's wait deadline elapsed) — never a property of the
+ * embed's target, so it shares a short transient TTL with
+ * `network`/`timeout` rather than `blocked`'s persistent one.
  */
 interface RenderError {
-    code: 'auth' | 'rate_limit' | 'not_found' | 'network' | 'timeout' | 'unknown';
+    code: 'auth' | 'rate_limit' | 'not_found' | 'network' | 'timeout' | 'unknown' | 'blocked' | 'busy';
     /** Free-form text for log/debug — NOT inlined into the user-facing placeholder. */
     message?: string;
     /**
@@ -732,6 +1244,8 @@ type InlineExpansion = {
 interface EmbedFragment {
     /** Pre-sanitised HTML fragment to inline at the source position. */
     html: string;
+    /** RFC-0023 — optional structured payload paired with `html` (see `RenderResult.structured`). */
+    structured?: StructuredRenderPayload;
     /** Optional `<head>`-bound assets (CSS / JS) keyed by URL. */
     assets?: {
         css?: string[];
@@ -762,6 +1276,17 @@ interface CacheEntry {
     result: RenderResult;
     fetchedAt: Date;
     expiresAt: Date;
+    /**
+     * Present ⇔ this is a stale-if-error entry keeping a prior success on
+     * screen (see `packages/api/src/renderer/cache/index.ts:
+     * STALE_IF_ERROR_MAX_AGE_SEC`): the value is that ORIGINAL success's
+     * timestamp, carried forward unchanged across consecutive failed
+     * retries — never the failed attempt's `fetchedAt`. Success entries do
+     * not carry it (their `fetchedAt` IS the last-good time; readers use
+     * that directly, which also covers, value-identically, entries written
+     * while this field was still being set on success).
+     */
+    lastGoodFetchedAt?: Date;
 }
 /**
  * MongoDB-backed cache surface. Phase 4 ships exactly one
@@ -854,6 +1379,25 @@ interface RenderContext {
      * encrypted-config-backed implementation.
      */
     auth?: AuthContext;
+    /**
+     * Who is driving this render. Required so admission control (§6) can
+     * apply its per-user concurrency cap end-to-end — every entry point
+     * (`Renderer.run`/`runMetadata`/`runRender`, `packages/api/src/renderer/
+     * index.ts`) requires callers to supply this. See `RenderActor`'s doc
+     * comment for which variant real call sites actually produce today.
+     */
+    actor: RenderActor;
+    /**
+     * Optional cancellation signal, propagated from the originating HTTP
+     * request (`c.req.raw.signal` on `POST /pages/preview`). A waiting
+     * (not-yet-running) admission-control job is removed from its queue
+     * the instant this fires; an already-running child-process render is
+     * NOT force-killed (§6 — the cost of killing/respawning a worker
+     * outweighs letting an already-cheap render finish and discarding the
+     * result). Absent on the save / read call sites, which have no
+     * request to cancel against.
+     */
+    signal?: AbortSignal;
 }
 /**
  * The registry handed to every plugin's `registerRenderer(scope, ctx)`.
@@ -869,6 +1413,10 @@ interface RenderContext {
  *
  * Phase 4 stubs (warn-noop):
  *   - `addCodeBlockRenderer` (Phase 6 lights this up)
+ *
+ * feature-renderer-plugin-boundary Phase 1 adds `addStylesheet(path)` —
+ * the boot-time CSS-manifest extension point (see that method's own doc
+ * comment).
  */
 interface RendererRegistry {
     /**
@@ -907,33 +1455,144 @@ interface RendererRegistry {
      * preserved; the first match that returns `'replaced'` wins.
      */
     addUrlInlineExpander(rule: UrlInlineExpansionRule): void;
+    /**
+     * Declare a static CSS asset the plugin needs the browser to load
+     * (e.g. KaTeX's ~30KB math stylesheet). `path` MUST be an
+     * API-relative absolute path confined to the plugin's own
+     * `registerRoutes` namespace — `/api/plugins/<this plugin's
+     * name>/<…>` — the same prefix `PluginRouterScope.route(...)` mounts
+     * that plugin's HTTP routes under. A URL scheme, protocol-relative
+     * `//host`, backslash, `..` traversal segment, or a path outside the
+     * plugin's own namespace all throw synchronously (boot-time reject —
+     * this is not an operator-configurable external URL; see spec
+     * §2.1's "不採用案"). During the `feature-api-v2-path-removal`
+     * migration period the legacy `/api/v2/plugins/<name>/<…>` prefix is
+     * also accepted and silently normalised to the canonical `/api/plugins/`
+     * form before publication — a plugin package that hasn't bumped its own
+     * `addStylesheet(...)` call site yet still gets a working manifest
+     * entry; this dual-accept is transitional, not a permanent alias.
+     *
+     * The call only stages the path in a per-plugin pending set: it is
+     * published to the public `GET /api/app/info` `rendererStylesheets`
+     * manifest ONLY after this plugin's OWN `registerRoutes(scope, ctx)`
+     * completes without throwing (so the manifest never advertises a path
+     * whose route failed to mount). A plugin with no `registerRoutes` at
+     * all, or whose `registerRoutes` throws, never gets its pending
+     * stylesheets committed — dropped wholesale, not partially. Query /
+     * fragment are allowed; duplicate calls with the same path are a
+     * no-op. Call this from `registerRenderer`, not `registerRoutes` —
+     * commit timing depends on this method having already run.
+     */
+    addStylesheet(path: string): 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.
+ * HTTP method a plugin route can be mounted on. Kept to the verbs the
+ * inbound-webhook + admin-action surface actually needs (RFC-0013 §4):
+ * `POST` for Slack events / slash / interactivity + `@action` targets,
+ * `GET` for OAuth callbacks + simple status endpoints.
+ */
+type PluginRouteMethod = 'GET' | 'POST';
+/**
+ * A plugin route handler. It receives the raw Hono `Context` and returns
+ * a `Response` (or a promise of one), exactly like a hand-written Hono
+ * handler — the scope does **not** wrap it in a typed-route/validator
+ * layer.
+ *
+ * **Raw body invariant** (RFC-0013 §8, a Slack hard requirement): the
+ * route is a plain Hono route, NOT a `@hono/zod-openapi` route, so no
+ * body-consuming validator runs ahead of the handler. `c.req.text()` /
+ * `c.req.raw` therefore yield the *exact* bytes the client sent, which
+ * the Slack signature check (`HMAC-SHA256` over `v0:{ts}:{rawBody}`)
+ * depends on. `createJwtAuth` (installed on non-public routes) never
+ * reads the body, so the invariant holds for authed routes too.
+ */
+type PluginRouteHandler = (c: Context) => Response | Promise<Response>;
+/** Per-route options passed alongside the handler. */
+interface PluginRouteOptions {
+    /**
+     * Authorization tier this route requires.
+     * - `'public'`: no auth (self-authenticating webhooks — Slack signature
+     *   check etc.).
+     * - `'user'` (default): any authenticated Crowi user (`createJwtAuth`).
+     * - `'admin'`: `user.admin === true` (`createJwtAdminRequired`) — use for
+     *   Test-connection / `@action` targets reached only from the admin
+     *   config form.
+     */
+    auth?: 'public' | 'user' | 'admin';
+}
+/**
+ * Scope passed to `registerRoutes(scope, ctx)`. Lets a plugin contribute
+ * HTTP routes that the runtime mounts at
+ * `/api/plugins/<plugin-name>/<path>` — the `<plugin-name>` path
+ * segment guarantees that core endpoints and other plugins cannot
+ * collide (RFC-0013 §4).
  *
- * 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.
+ * The scope is built per-plugin inside `buildHonoApp` (the Hono app does
+ * not exist yet when plugins activate at boot), so `<plugin-name>` is
+ * already closed over — plugins only supply the sub-path.
  */
 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.
+     * Mount `handler` for `method` at `<path>` under this plugin's
+     * namespace. `path` is relative to `/api/plugins/<plugin-name>` and
+     * should start with `/` (e.g. `route('POST', '/events', handler, {
+     * auth: 'public' })` → `POST /api/plugins/<name>/events`).
+     *
+     * Pass `{ auth: 'public' }` to bypass Crowi auth entirely for self-
+     * authenticating inbound webhooks, `{ auth: 'admin' }` to require
+     * `user.admin === true`, or omit `opts` for the `'user'` default (any
+     * authenticated Crowi user).
      */
-    register(contract: unknown, implementation: unknown): void;
+    route(method: PluginRouteMethod, path: string, handler: PluginRouteHandler, opts?: PluginRouteOptions): void;
 }
 
+/**
+ * Declares that, when a specific driver from a specific registry is
+ * selected (`crowi.config.json:<registry>.driver === driver`), this
+ * plugin's own config becomes required to actually work at runtime —
+ * even though the `configSchema` field itself is optional / defaults to
+ * `''` so `configSchema.parse()` alone can't detect "present but
+ * unusable" (see `@crowi/plugin-storage-aws-s3`'s `bucket` and
+ * `@crowi/plugin-search-elasticsearch` / `@crowi/plugin-search-opensearch`'s
+ * `url`, both `z.string().default('')`).
+ *
+ * This is metadata only — it never carries an actual config value.
+ * `registry` / `driver` / every name in `requiredConfigFields` must be
+ * non-empty. The runtime (`PluginManager.getReadinessIssues()`) reads
+ * this once per admin readiness check, cross-references it against the
+ * currently selected driver and the plugin's current config namespace,
+ * and reports which declared fields are still empty — never the values
+ * themselves. See RFC-none / feature-plugin-config-readiness.
+ */
+interface PluginReadinessDeclaration {
+    /** Which driver registry this declaration is scoped to. */
+    registry: 'storage' | 'search' | 'mail';
+    /** The driver name (as registered via `registry.register(name, …)`) this declaration applies to. */
+    driver: string;
+    /** `configSchema` field names that must be non-empty for `driver` to actually work once selected. */
+    requiredConfigFields: string[];
+}
+/**
+ * One all-or-nothing group of `configSchema` fields — see
+ * `CrowiPlugin.configAtomicGroups`.
+ */
+interface PluginConfigAtomicGroup {
+    /**
+     * Stable identifier, part of the physical storage key
+     * (`plugin:<plugin>:__atomic:<name>`). Renaming it orphans the stored
+     * document, so treat it like a migration.
+     */
+    name: string;
+    /** The `configSchema` field names stored together. Non-empty, no duplicates, and each field may belong to only one group. */
+    keys: readonly string[];
+    /**
+     * Encrypt the whole stored group at rest. Set this when ANY member is
+     * secret: the group is one value, so it is either all encrypted or all
+     * not — there is no per-field choice left once they share a document.
+     */
+    sensitive?: boolean;
+}
 /**
  * The contract every Crowi plugin satisfies. Plugins export their
  * `CrowiPlugin` object as the package's default export; the runtime
@@ -964,10 +1623,55 @@ interface CrowiPlugin {
      * at boot and loads `requires` first; cycles fail boot.
      */
     requires?: string[];
+    /**
+     * Core Mongoose model names (e.g. `['Page', 'Bookmark']`) this plugin
+     * is allowed to reach via `ctx.model(name)`. The PluginManager
+     * validates every entry against the set of registered core model
+     * names at boot — an unknown name fails boot with a descriptive
+     * error. `ctx.model(name)` throws at call time for any `name` not
+     * listed here.
+     *
+     * A model listed here is granted full (unrestricted) read/write
+     * access — there is no read-only mode. Omit or leave empty for a
+     * plugin that never calls `ctx.model()`.
+     *
+     * Credential-bearing core models (`Config`, `PersonalAccessToken`,
+     * OAuth client/token/grant models, `Share`, `ShareAccess`) can never
+     * be listed here — declaring one fails boot, and `ctx.model()` also
+     * refuses to return one at call time as defense-in-depth. There is no
+     * legitimate plugin use case for touching those collections directly.
+     */
+    modelAccess?: string[];
+    /**
+     * Opt in to letting *other* plugins read this plugin's config through
+     * their `ctx.dependencyConfig<T>(this.name)` (they must also list this
+     * plugin in their own `requires`). Defaults to `false` — a plugin's
+     * config, including `@sensitive` fields, is private to itself unless
+     * it explicitly declares this flag.
+     *
+     * Set this on a plugin that exists specifically to hold credentials
+     * shared by other plugins — e.g. `@crowi/plugin-aws` sets it so
+     * `@crowi/plugin-storage-aws-s3` and `@crowi/plugin-mail-aws-ses` can
+     * read its `region` / `accessKeyId` / `secretAccessKey` without
+     * duplicating them in their own `configSchema`. Most plugins should
+     * leave this unset.
+     */
+    exposesConfigToDependents?: boolean;
     /**
      * Zod schema describing this plugin's *global* configurable values.
      * The admin UI generates a config form by walking this schema.
      *
+     * Build this with `import { z } from 'zod/v3'` — NOT the top-level
+     * `import { z } from 'zod'` (v4). `peerDependencies: { zod: "^4" }`
+     * only says which npm package to install; the v4 package ships a
+     * `zod/v3` compat subpath, and that subpath's runtime shape is what
+     * every introspection helper here (`schema-serializer.ts`,
+     * `schema-markers.ts`, `PluginManager.listSensitiveKeys()`) actually
+     * walks. A schema built from the top-level v4 API fails boot with an
+     * explicit error (`PluginManager.activate()`'s config-schema guard —
+     * see this package's README) rather than silently losing
+     * `@sensitive` detection.
+     *
      * 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.
@@ -978,6 +1682,24 @@ interface CrowiPlugin {
      * the field that calls the plugin's contributed REST endpoint.
      */
     configSchema?: z.ZodObject<Record<string, z.ZodTypeAny>>;
+    /**
+     * RFC-0014 phase 4 — `configSchema` fields that must never be visible
+     * to anyone in a half-written state, declared as groups that are stored
+     * as ONE Config document instead of one row per field.
+     *
+     * The motivating case is an OAuth client id + secret. Written as
+     * separate rows, a failure between them leaves the instance advertising
+     * a new client id paired with the previous secret — a configuration
+     * that never existed and cannot authenticate, visible to every replica
+     * until an operator notices. As a single document there is no
+     * in-between: readers see the whole previous pair or the whole new one.
+     *
+     * This is a STORAGE contract, not a general escape hatch for making
+     * arbitrary keys atomic — the fields still appear to the plugin (and to
+     * the admin form) as ordinary flat config, and are only reassembled at
+     * the persistence boundary.
+     */
+    configAtomicGroups?: readonly PluginConfigAtomicGroup[];
     /**
      * Per-Page metadata schema. When set, every Page document has a
      * `metadata['<plugin-name>']` slot whose shape matches this schema,
@@ -1002,7 +1724,7 @@ interface CrowiPlugin {
      * from a fixed allow-list to keep the bundle small.
      */
     adminPlacement?: {
-        section?: 'settings' | 'shared' | 'storage' | 'mail' | 'notification' | 'auth' | 'search' | 'renderer';
+        section?: 'settings' | 'shared' | 'storage' | 'mail' | 'notification' | 'auth' | 'search' | 'renderer' | 'platform';
         label?: string;
         icon?: string;
     };
@@ -1023,6 +1745,14 @@ interface CrowiPlugin {
         label?: string;
         description?: string;
     }>>;
+    /**
+     * Declares which of this plugin's own `configSchema` fields must be
+     * non-empty for a specific driver selection to actually work at
+     * runtime (see {@link PluginReadinessDeclaration}). Optional — a
+     * plugin with no readiness declaration is never surfaced by the
+     * admin readiness check, same as before this field existed.
+     */
+    readiness?: PluginReadinessDeclaration;
     /** Storage driver registration. Called once at boot. */
     registerStorage?: (registry: StorageRegistry, ctx: PluginContext) => void;
     /** Search backend registration. Called once at boot. */
@@ -1052,13 +1782,25 @@ interface CrowiPlugin {
      */
     registerHooks?: (events: EventBus, ctx: PluginContext) => void;
     /**
-     * ts-rest contract that the plugin contributes. Mounted at
-     * `/api/v2/plugins/<name>/*` (the `<name>` path segment guarantees
+     * HTTP routes the plugin contributes, mounted at
+     * `/api/plugins/<name>/<path>` (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.
+     * inbound webhooks (Slack events / slash / interactivity), "Test
+     * connection" buttons, `@action` targets, OAuth callbacks, etc.
+     *
+     * Each route is a plain Hono handler — `scope.route(method, path,
+     * (c) => Response, opts?)`. The handler receives the raw `Context`, so
+     * `c.req.text()` / `c.req.raw` give the exact request bytes (no
+     * validator consumes the body ahead of it — the Slack signature check
+     * relies on this). Pass `{ auth: 'public' }` to bypass Crowi auth for
+     * self-authenticating webhooks, `{ auth: 'admin' }` for routes that
+     * require `user.admin === true`, or omit `opts` for the `'user'`
+     * default (any authenticated Crowi user).
+     *
+     * Called once at boot — but unlike the other `register*` hooks, this
+     * runs inside `buildHonoApp` (the Hono app does not exist yet when
+     * plugins activate), so a plugin's `registerRoutes` fires slightly
+     * later than its `registerStorage` / `registerNotifier` / etc.
      */
     registerRoutes?: (scope: PluginRouterScope, ctx: PluginContext) => void;
     /**
@@ -1092,6 +1834,39 @@ interface CrowiPlugin {
      * of the very UI they need to fix the misconfiguration.
      */
     reconfigure?: (ctx: PluginContext) => void | Promise<void>;
+    /**
+     * Non-blocking connectivity/permission probe run once, after a save that
+     * touched this plugin's own config OR a dependency's config (any plugin
+     * that has this one in `requires`) has already persisted AND already
+     * run `reconfigure` — feature-plugin-config-live-verification. Never
+     * gates the save: whatever this returns is reported alongside a save
+     * that already succeeded, never rolled back.
+     *
+     * Receives a {@link PluginConfigVerificationSnapshot}, NOT the live
+     * `PluginContext` — do not close over or otherwise reach for `ctx` from
+     * inside this hook. The snapshot is a read-only, point-in-time view
+     * materialized from the exact values the triggering save just wrote (own
+     * config) plus any declared, `exposesConfigToDependents`-opted-in
+     * dependency config — it never reflects a LATER save by a different
+     * admin request, even one that lands while this hook is still running.
+     * `snapshot.config()` / `snapshot.dependencyConfig()` can throw if the
+     * runtime couldn't materialize a value (e.g. an existing, currently
+     * invalid dependency config); the runtime skips calling this hook
+     * entirely in that case rather than invoking it with a broken snapshot.
+     *
+     * `options.timeoutMs` is a notice, not a cancellation signal — see its
+     * doc. Must resolve within that budget or the caller treats it as
+     * `{ status: 'failed', reason: 'unreachable' }`; a promise that keeps
+     * running past that point should still clean up after itself when it
+     * eventually settles, but must never throw out of that cleanup in a way
+     * that becomes an unhandled rejection.
+     *
+     * The returned result (and anything it internally logs) must never
+     * include raw SDK/driver error text, stack traces, endpoints, or
+     * credential material — only the closed `reason` enum. See
+     * `PluginConfigVerificationResult`.
+     */
+    verifyConfig?: (snapshot: PluginConfigVerificationSnapshot, options: PluginConfigVerificationOptions) => Promise<PluginConfigVerificationResult>;
 }
 
 /**
@@ -1121,7 +1896,7 @@ declare const SENSITIVE_FIELD_MARKER = "@sensitive";
  *
  * 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",
+ * `/api/plugins/<name>/`). Useful for "Test connection",
  * "Authorise with Google", etc. without forcing every plugin to ship
  * its own React component.
  */
@@ -1140,8 +1915,8 @@ 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. */
+    method: PluginRouteMethod;
+    /** Path relative to `/api/plugins/<name>/`, with leading slash. */
     path: string;
 }
 /**
@@ -1150,10 +1925,137 @@ interface ActionAnnotation {
  * 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 `/`.
+ * The label may include spaces when wrapped in double quotes; the method
+ * must be one of `PluginRouteMethod` (`GET` / `POST` — the only verbs a
+ * plugin route can actually be mounted on, see `routes.ts`); the path
+ * begins with `/`. A description that starts with the `@action` marker
+ * but declares an unsupported verb (e.g. `PUT` / `DELETE`) fails to match
+ * and returns `null` here — callers that walk a plugin's `configSchema`
+ * (e.g. `PluginManager.activate()`) are expected to warn on that case at
+ * boot, since it would otherwise be a silent dead button.
  */
 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 };
+/**
+ * Parses a root `<svg>` element's `viewBox` (`minX minY width height`) to
+ * derive intrinsic pixel dimensions. Shared by
+ * `@crowi/plugin-renderer-mermaid` (its original home — the `<img>`
+ * `width`/`height` intrinsic-size fix) and, since RFC-0023,
+ * `@crowi/plugin-renderer-plantuml`'s SVG sidecar path — both need the
+ * same derivation and both already bundle this package, so it lives
+ * here rather than being copied per plugin.
+ *
+ * Reads attributes off the sanitized SVG source string only — never
+ * decodes any `data:` payload.
+ */
+declare function extractSvgDimensions(svg: string): {
+    width: number;
+    height: number;
+} | null;
+
+/**
+ * Renderer-specific knobs for `sanitizeSvg`. The sanitizer itself is a
+ * single shared implementation (`sanitize.ts`) — per-renderer differences
+ * are expressed as parameters here, never as a second copy of the DOM
+ * walk (spec §9: "実装自体をrenderer間で複製しない").
+ */
+interface SanitizeSvgPolicy {
+    /**
+     * When `true`, `href` / `xlink:href` values pointing at an `https:`
+     * URL are preserved (PlantUML's existing "preserves href to a safe
+     * URL" behaviour, consumed starting Phase 3). When `false`, every
+     * `href` / `xlink:href` is stripped unless it is a local fragment
+     * reference (`#id`) — Mermaid's strict policy (spec §1 layer 1 already
+     * disables Mermaid's own click callbacks, so no link should survive
+     * either).
+     *
+     * Regardless of this flag, `javascript:`, `data:`, and
+     * protocol-relative (`//host/...`) URLs are ALWAYS stripped — no
+     * policy may re-allow those.
+     */
+    allowSafeHref: boolean;
+}
+
+type SanitizeSvgResult = {
+    ok: true;
+    svg: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * DOM-based SVG sanitizer shared by `@crowi/plugin-renderer-mermaid` and
+ * (from Phase 3) `@crowi/plugin-renderer-plantuml`. Spec §2 layer 2 / §9.
+ *
+ * Design: allowlist-first for elements (unknown/unexpected element names
+ * are dropped with their whole subtree — safer than trying to enumerate
+ * every dangerous tag), then a small set of attribute-level rules that
+ * apply uniformly to every surviving element. This is a from-scratch DOM
+ * walk, not a regex pass (`packages/plugin-renderer-plantuml/src/
+ * sanitize.ts`'s existing implementation is explicitly documented there
+ * as "not a substitute for DOMPurify" — this package is the replacement
+ * both renderers converge on, PlantUML starting Phase 3).
+ *
+ * What gets removed:
+ *   - Any element not in `ALLOWED_ELEMENTS` (`script`, `foreignObject`,
+ *     `iframe`, `object`, `embed`, SMIL `animate*`/`set`/`discard`, ...) —
+ *     dropped together with its entire subtree.
+ *   - `on*` event-handler attributes (any casing).
+ *   - The `style` attribute (inline styles). Mermaid/PlantUML's real
+ *     styling lives in the `<style>` *element* (class-based), which is
+ *     sanitized separately below rather than dropped — dropping inline
+ *     `style=""` is a deliberate hardening tradeoff (removes a CSS-value
+ *     injection vector) the regression tests confirm does not break
+ *     either renderer's *structural* output.
+ *   - `@import` at-rules and non-local-fragment `url(...)` function
+ *     values inside `<style>` element text content (external stylesheet
+ *     / font / image loads) — see `sanitizeStyleText` below for why the
+ *     element itself is not dropped wholesale.
+ *   - `xmlns` / `xmlns:*` declarations on any non-root element (namespace
+ *     declarations only ever legitimately live on the root `<svg>`).
+ *   - Any root-level `xmlns:*` declaration other than a correctly-bound
+ *     `xmlns:xlink` (see `isEssentialRootNamespaceDeclaration`). These are
+ *     already functionally inert under the strict unprefixed-SVG-element
+ *     invariant enforced elsewhere in this file, but are dropped anyway
+ *     as defence-in-depth against relying on that invariant alone.
+ *   - `xml:base` on any element (root or descendant). Left in place, it
+ *     would silently change the base URI every *local-fragment* `href` /
+ *     `xlink:href` / `url(#id)` reference in its subtree resolves
+ *     against — turning an in-document `#id` reference into an external
+ *     `https://evil.example/#id` fetch some SVG consumers follow,
+ *     defeating the local-fragment-only guarantees above even though
+ *     every individual `href`/`url()` value still looks safe in
+ *     isolation.
+ *   - `ProcessingInstruction` nodes anywhere in the tree
+ *     (`<?xml-stylesheet ...?>` etc).
+ *   - `href` / `xlink:href` values that are not a local fragment
+ *     reference (`#id`) and not allowed by `policy.allowSafeHref`.
+ *     `javascript:`, `data:`, and protocol-relative (`//...`) values are
+ *     ALWAYS stripped regardless of policy.
+ *   - `url(...)` references inside SVG *presentation attributes* that
+ *     accept a `<FuncIRI>` (`fill`, `stroke`, `filter`, `clip-path`,
+ *     `mask`, `cursor`, `marker-start`, `marker-mid`, `marker-end`) when
+ *     the reference target is not a local fragment (`#id`) — e.g.
+ *     `fill="url(https://evil.example/paint.svg)"` or
+ *     `filter="url(data:image/svg+xml;base64,...)"`. These are the same
+ *     class of external-resource load as `href`/`style` but reachable via
+ *     a different attribute name, so they get the same href-style
+ *     drop-the-attribute treatment. `url(#localId)` references (the
+ *     normal way Mermaid/PlantUML wire arrowhead markers and gradients)
+ *     are always preserved.
+ *
+ * What is explicitly preserved:
+ *   - `href` / `xlink:href` local fragment references (`#id`) — legitimate
+ *     internal `<use>` / gradient / clip-path wiring.
+ *   - `https:` `href` values when `policy.allowSafeHref` is `true`.
+ *   - `url(#id)` local fragment references in presentation attributes
+ *     (`fill="url(#gradient)"`, `marker-end="url(#arrowhead)"`, ...).
+ *
+ * A parse failure (malformed XML) or a sanitized result whose root is not
+ * a single `<svg>` element both return `{ ok: false }` — callers must
+ * treat that as "invalid output" (spec §2 layer 2), never fall back to
+ * the unsanitized input.
+ */
+declare function sanitizeSvg(input: string, policy: SanitizeSvgPolicy): SanitizeSvgResult;
+
+export { ACTION_FIELD_MARKER, type AdmissionControlConfig, type AppInfo, type AuthContext, type AuthDriver, type AuthDriverKind, type AuthProfile, type AuthRegistry, type AuthVerifyResult, CONFIG_VERIFICATION_KEY_PREFIX, type CacheEntry, type CacheKey, type CacheStorage, type CodeBlockInfo, type CodeBlockRenderer, type CreateOAuth2DriverOptions, type CreateOidcDriverOptions, type CredentialAuthDriver, type CredentialField, 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 OAuth2AuthDriver, type OAuthClientConfig, type OAuthTokens, type OidcAuthDriver, type PageMetadataAccessor, type PluginConfigAtomicGroup, type PluginConfigVerificationOptions, type PluginConfigVerificationResult, type PluginConfigVerificationSnapshot, type PluginContext, type PluginEvents, type PluginLogger, type PluginReadinessDeclaration, type PluginRouteHandler, type PluginRouteMethod, type PluginRouteOptions, type PluginRouterScope, type ReadonlyDeep, type RenderActor, type RenderContext, type RenderError, type RenderPhase, type RenderResult, type RendererRegistry, type Reservation, SENSITIVE_FIELD_MARKER, type SanitizeSvgPolicy, type SanitizeSvgResult, type ScopedCacheStorage, type SearchDriver, type SearchHit, type SearchHits, type SearchPageType, type SearchQuery, type SearchQueryGrants, type SearchQueryViewer, type SearchRegistry, type SearchableDoc, type StateCell, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type StructuredRenderPayload, type UrlInlineExpansionRule, type VerificationFailureReason, createOAuth2Driver, createOidcDriver, escapeHtml, extractSvgDimensions, getActionAnnotation, isSensitiveField, sanitizeSvg };