@crowi/plugin-api 0.1.0-alpha.2 → 1.0.0-alpha.3

package/README.md

@@ -0,0 +1,117 @@
+# @crowi/plugin-api
+
+Type-only contract for Crowi 2.0 plugins. A Crowi plugin is an ordinary
+npm package that default-exports an object satisfying the `CrowiPlugin`
+type from this package; the runtime loads it via `await
+import('<plugin-name>')` at boot and calls each `register*` callback it
+implements. See
+[RFC-0001](https://github.com/crowi/crowi/blob/main/docs/rfcs/0001-plugin-architecture.md)
+for the full design and the
+[plugin development guide](https://crowi.wiki/docs/plugins/developing)
+for a walkthrough.
+
+> **Alpha notice**: Crowi v2 is under active alpha development and this
+> package is at `0.x`. The API stability guarantee (working across every
+> v2 minor) takes effect once it reaches `2.x`; the contract may still
+> change during the alpha period.
+
+## Minimal plugin
+
+```ts
+import type { CrowiPlugin } from '@crowi/plugin-api';
+
+const myPlugin: CrowiPlugin = {
+  name: '@example/crowi-plugin-mystorage',
+  version: '0.1.0',
+
+  registerStorage: (registry, ctx) => {
+    registry.register('mystorage', {
+      put: async (key, body, meta) => ({ key }),
+      get: async (key) => { throw new Error('not implemented'); },
+      delete: async (key) => {},
+    });
+  },
+};
+
+export default myPlugin;
+```
+
+`name` must match the npm package name — it doubles as the namespace
+prefix for this plugin's config rows (`plugin:<name>:*`) and per-page
+metadata (`page.metadata['<name>']`).
+
+## Authoring a config schema
+
+A plugin declares its configurable values with `configSchema`, a Zod
+object schema. The admin UI at `/admin/plugins` walks this schema to
+auto-generate a config form, encrypt `@sensitive`-marked fields at
+rest, and render `@action`-marked fields with a button.
+
+This package's `peerDependencies` declares `zod: "^4"` — that is the
+correct **npm package** to install, because the zod v4 package is the
+one that ships a `zod/v3` compat subpath. What `peerDependencies`
+cannot express is *which entry point* to import from, and that part
+matters:
+
+```ts
+// Correct — the v3 compat shim that the v4 package ships.
+import { z } from 'zod/v3';
+
+// Wrong — compiles and type-checks, but fails at plugin boot.
+import { z } from 'zod';
+```
+
+`CrowiPlugin.configSchema` is typed against `zod/v3`'s `z.ZodObject`,
+and every runtime helper that reads a plugin's config schema
+(`@sensitive` / `@action` marker detection, the admin form field
+serializer, `listSensitiveKeys()`) introspects the `zod/v3` internal
+shape (`_def.typeName`, `_def.values`, `.description`, …). A schema
+built from the top-level `zod` (v4) API has a different internal shape
+and none of that introspection can see through it — most importantly,
+`@sensitive` fields stop being detected, and the value they guard would
+be written to and read from storage as plaintext.
+
+To turn that silent failure mode into a loud one, `PluginManager`
+validates every plugin's `configSchema` at boot and throws if it wasn't
+built from `zod/v3`:
+
+```
+Plugin '<name>' declares configSchema built with the top-level 'zod' (v4) API.
+Import from 'zod/v3' instead — @crowi/plugin-api's config-schema introspection
+requires the zod v3 compat shape (see @crowi/plugin-api README).
+```
+
+If you hit this error, the fix is always the same: change the `zod`
+import for the file that builds `configSchema` (and `pageMetadataSchema`,
+if you use it) to `import { z } from 'zod/v3'`. No other code needs to
+change — `zod/v3`'s `z.object()` / `z.string()` / etc. API surface is
+what every first-party Crowi plugin already uses.
+
+```ts
+import { z } from 'zod/v3';
+import type { CrowiPlugin } from '@crowi/plugin-api';
+
+const myPlugin: CrowiPlugin = {
+  name: '@example/crowi-plugin-mystorage',
+  version: '0.1.0',
+
+  configSchema: z.object({
+    endpoint: z.string().url().describe('Storage endpoint URL'),
+    accessKey: z.string().describe('@sensitive Access key'),
+  }),
+
+  registerStorage: (registry, ctx) => {
+    const config = ctx.config<{ endpoint: string; accessKey: string }>();
+    // ... build the driver using config
+  },
+};
+
+export default myPlugin;
+```
+
+## See also
+
+- [Plugin development guide](https://crowi.wiki/docs/plugins/developing) —
+  the full walkthrough (markers, `adminPlacement`, `configI18n`,
+  `PluginContext`, dependency plugins, renderer plugins).
+- [RFC-0001: Plugin architecture](https://github.com/crowi/crowi/blob/main/docs/rfcs/0001-plugin-architecture.md)

package/dist/index.d.mts

@@ -5,8 +5,36 @@ 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 {
     /**
@@ -21,13 +49,19 @@ 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;
     /**
@@ -42,19 +76,90 @@ interface PluginContext {
     /** 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
@@ -94,10 +199,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;
@@ -966,17 +1067,15 @@ type PluginRouteHandler = (c: Context) => Response | Promise<Response>;
 /** Per-route options passed alongside the handler. */
 interface PluginRouteOptions {
     /**
-     * When `true`, the route is mounted **without** `createJwtAuth`, so it
-     * is reachable by unauthenticated requests (Crowi-auth public). Use for
-     * inbound webhooks that authenticate themselves out-of-band — e.g. the
-     * Slack Events API endpoint, which is gated by Slack's request-signature
-     * check rather than a Crowi session (RFC-0013 §8).
-     *
-     * Omitted / `false` mounts the route under `createJwtAuth`, so it
-     * requires a valid Crowi JWT just like a core authenticated endpoint
-     * (admin "Test connection" / `@action` targets, OAuth callbacks).
+     * 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.
      */
-    public?: boolean;
+    auth?: 'public' | 'user' | 'admin';
 }
 /**
  * Scope passed to `registerRoutes(scope, ctx)`. Lets a plugin contribute
@@ -994,11 +1093,12 @@ interface PluginRouterScope {
      * Mount `handler` for `method` at `<path>` under this plugin's
      * namespace. `path` is relative to `/api/v2/plugins/<plugin-name>` and
      * should start with `/` (e.g. `route('POST', '/events', handler, {
-     * public: true })` → `POST /api/v2/plugins/<name>/events`).
+     * auth: 'public' })` → `POST /api/v2/plugins/<name>/events`).
      *
-     * Pass `{ public: true }` to bypass `createJwtAuth` for self-
-     * authenticating inbound webhooks; omit it for routes that require a
-     * Crowi session.
+     * 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).
      */
     route(method: PluginRouteMethod, path: string, handler: PluginRouteHandler, opts?: PluginRouteOptions): void;
 }
@@ -1033,10 +1133,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.
@@ -1131,9 +1276,10 @@ interface CrowiPlugin {
      * (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 `{ public: true }` to bypass `createJwtAuth`
-     * for self-authenticating webhooks; omit it for Crowi-session-gated
-     * routes.
+     * 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
@@ -1220,7 +1366,7 @@ interface ActionAnnotation {
     /** Visible button label, e.g. "Test connection". */
     label: string;
     /** HTTP verb of the plugin endpoint to call. */
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    method: PluginRouteMethod;
     /** Path relative to `/api/v2/plugins/<name>/`, with leading slash. */
     path: string;
 }
@@ -1230,10 +1376,15 @@ 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 AppInfo, 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 PluginRouteHandler, type PluginRouteMethod, type PluginRouteOptions, 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 };
+export { ACTION_FIELD_MARKER, type AppInfo, 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 PluginEvents, type PluginLogger, type PluginRouteHandler, type PluginRouteMethod, type PluginRouteOptions, 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 StateCell, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type UrlInlineExpansionRule, getActionAnnotation, isSensitiveField };

package/dist/index.d.ts

@@ -5,8 +5,36 @@ 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 {
     /**
@@ -21,13 +49,19 @@ 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;
     /**
@@ -42,19 +76,90 @@ interface PluginContext {
     /** 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
@@ -94,10 +199,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;
@@ -966,17 +1067,15 @@ type PluginRouteHandler = (c: Context) => Response | Promise<Response>;
 /** Per-route options passed alongside the handler. */
 interface PluginRouteOptions {
     /**
-     * When `true`, the route is mounted **without** `createJwtAuth`, so it
-     * is reachable by unauthenticated requests (Crowi-auth public). Use for
-     * inbound webhooks that authenticate themselves out-of-band — e.g. the
-     * Slack Events API endpoint, which is gated by Slack's request-signature
-     * check rather than a Crowi session (RFC-0013 §8).
-     *
-     * Omitted / `false` mounts the route under `createJwtAuth`, so it
-     * requires a valid Crowi JWT just like a core authenticated endpoint
-     * (admin "Test connection" / `@action` targets, OAuth callbacks).
+     * 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.
      */
-    public?: boolean;
+    auth?: 'public' | 'user' | 'admin';
 }
 /**
  * Scope passed to `registerRoutes(scope, ctx)`. Lets a plugin contribute
@@ -994,11 +1093,12 @@ interface PluginRouterScope {
      * Mount `handler` for `method` at `<path>` under this plugin's
      * namespace. `path` is relative to `/api/v2/plugins/<plugin-name>` and
      * should start with `/` (e.g. `route('POST', '/events', handler, {
-     * public: true })` → `POST /api/v2/plugins/<name>/events`).
+     * auth: 'public' })` → `POST /api/v2/plugins/<name>/events`).
      *
-     * Pass `{ public: true }` to bypass `createJwtAuth` for self-
-     * authenticating inbound webhooks; omit it for routes that require a
-     * Crowi session.
+     * 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).
      */
     route(method: PluginRouteMethod, path: string, handler: PluginRouteHandler, opts?: PluginRouteOptions): void;
 }
@@ -1033,10 +1133,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.
@@ -1131,9 +1276,10 @@ interface CrowiPlugin {
      * (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 `{ public: true }` to bypass `createJwtAuth`
-     * for self-authenticating webhooks; omit it for Crowi-session-gated
-     * routes.
+     * 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
@@ -1220,7 +1366,7 @@ interface ActionAnnotation {
     /** Visible button label, e.g. "Test connection". */
     label: string;
     /** HTTP verb of the plugin endpoint to call. */
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    method: PluginRouteMethod;
     /** Path relative to `/api/v2/plugins/<name>/`, with leading slash. */
     path: string;
 }
@@ -1230,10 +1376,15 @@ 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 AppInfo, 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 PluginRouteHandler, type PluginRouteMethod, type PluginRouteOptions, 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 };
+export { ACTION_FIELD_MARKER, type AppInfo, 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 PluginEvents, type PluginLogger, type PluginRouteHandler, type PluginRouteMethod, type PluginRouteOptions, 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 StateCell, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type UrlInlineExpansionRule, getActionAnnotation, isSensitiveField };

package/dist/index.js

@@ -40,7 +40,7 @@ function getActionAnnotation(field) {
   const trimmed = description.trimStart();
   if (!trimmed.startsWith(ACTION_FIELD_MARKER)) return null;
   const rest = trimmed.slice(ACTION_FIELD_MARKER.length).trimStart();
-  const match = rest.match(/^"([^"]+)"\s+(GET|POST|PUT|DELETE)\s+(\/\S*)/);
+  const match = rest.match(/^"([^"]+)"\s+(GET|POST)\s+(\/\S*)/);
   if (!match) return null;
   const [, label, method, path] = match;
   return { label, method, path };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/schema-markers.ts"],"sourcesContent":["/**\n * @crowi/plugin-api — type-only contract for Crowi 2.0 plugins.\n *\n * Plugins author against this package. The runtime (@crowi/server) loads\n * plugins listed in `crowi.config.json`, calls each plugin's\n * `register*` callbacks, and routes all the side effects (storage,\n * search, auth, notifications) through the typed registries declared\n * here.\n *\n * For the design rationale see `docs/rfcs/0001-plugin-architecture.md`\n * in the Crowi monorepo.\n */\n\nexport type { CrowiPlugin } from './plugin';\n\nexport type { PluginContext, AppInfo, PageMetadataAccessor, PluginCrypto, PluginLogger } from './context';\n\nexport type { StorageDriver, StorageRegistry, StoragePutMeta, StoragePutResult } from './registries/storage';\n\nexport type {\n  SearchDriver,\n  SearchRegistry,\n  SearchableDoc,\n  SearchQuery,\n  SearchQueryViewer,\n  SearchQueryGrants,\n  SearchPageType,\n  SearchHits,\n  SearchHit,\n} from './registries/search';\n\nexport type { AuthDriver, AuthRegistry, AuthProfile, AuthVerifyResult } from './registries/auth';\n\nexport type { NotifierDriver, NotifierRegistry, NotificationPayload } from './registries/notifier';\n\nexport type { MailSender, MailSenderRegistry, EmailMessage } from './registries/mail';\n\nexport type {\n  RendererRegistry,\n  NodeRenderer,\n  CodeBlockRenderer,\n  CodeBlockInfo,\n  EmbedRenderer,\n  EmbedInput,\n  EmbedFragment,\n  UrlInlineExpansionRule,\n  InlineExpansion,\n  RenderContext,\n  RenderPhase,\n  RenderResult,\n  RenderError,\n  Reservation,\n  CacheStorage,\n  ScopedCacheStorage,\n  CacheKey,\n  CacheEntry,\n  AuthContext,\n} from './renderer';\n\nexport type { EventBus, PluginEvents } from './events';\n\nexport type { PluginRouterScope, PluginRouteHandler, PluginRouteMethod, PluginRouteOptions } from './routes';\n\nexport { SENSITIVE_FIELD_MARKER, ACTION_FIELD_MARKER, isSensitiveField, getActionAnnotation } from './schema-markers';\n","import type { z } from 'zod/v3';\n\n/**\n * `configSchema` description-string markers.\n *\n * The admin UI walks the schema and looks at each field's\n * `description` (set via `z.string().describe('@sensitive ...')`). A\n * description starting with one of these marker tokens unlocks special\n * UI behaviour without forcing every field to declare a custom Zod\n * type.\n */\n\n/**\n * Marker that flags a config field as sensitive (encrypted at rest).\n * Usage:\n *\n *   z.string().describe('@sensitive AWS secret access key')\n *\n * The runtime auto-encrypts on write and decrypts on read, using the\n * same KeyProvider as core sensitive Config. The admin UI renders the\n * field via `<SecretField>` (saved badge / clear pending / undo).\n */\nexport const SENSITIVE_FIELD_MARKER = '@sensitive';\n\n/**\n * Marker that adds an action button next to a config field. Usage:\n *\n *   z.string().describe('@action \"Test connection\" POST /test')\n *\n * The admin form renders a button with the given label that calls the\n * plugin's contributed endpoint at the given verb / path (relative to\n * `/api/v2/plugins/<name>/`). Useful for \"Test connection\",\n * \"Authorise with Google\", etc. without forcing every plugin to ship\n * its own React component.\n */\nexport const ACTION_FIELD_MARKER = '@action';\n\n/**\n * True if the schema field is marked `@sensitive`.\n *\n * `field` is `z.ZodTypeAny` (intentionally loose); call sites pass the\n * value type from `configSchema.shape[key]`.\n */\nexport function isSensitiveField(field: z.ZodTypeAny): boolean {\n  const description = field.description;\n  return typeof description === 'string' && description.trimStart().startsWith(SENSITIVE_FIELD_MARKER);\n}\n\n/**\n * Parsed `@action` annotation extracted from a field's `description`.\n */\nexport interface ActionAnnotation {\n  /** Visible button label, e.g. \"Test connection\". */\n  label: string;\n  /** HTTP verb of the plugin endpoint to call. */\n  method: 'GET' | 'POST' | 'PUT' | 'DELETE';\n  /** Path relative to `/api/v2/plugins/<name>/`, with leading slash. */\n  path: string;\n}\n\n/**\n * Parse an `@action` annotation off a field, or return null if absent.\n *\n * Format: `@action \"<label>\" <METHOD> <path>`\n *   e.g. `@action \"Test connection\" POST /test`\n *\n * The label may include spaces when wrapped in double quotes; the\n * method is one of `GET` / `POST` / `PUT` / `DELETE`; the path begins\n * with `/`.\n */\nexport function getActionAnnotation(field: z.ZodTypeAny): ActionAnnotation | null {\n  const description = field.description;\n  if (typeof description !== 'string') return null;\n  const trimmed = description.trimStart();\n  if (!trimmed.startsWith(ACTION_FIELD_MARKER)) return null;\n\n  const rest = trimmed.slice(ACTION_FIELD_MARKER.length).trimStart();\n  // `\"<label>\" <METHOD> <path>`\n  const match = rest.match(/^\"([^\"]+)\"\\s+(GET|POST|PUT|DELETE)\\s+(\\/\\S*)/);\n  if (!match) return null;\n\n  const [, label, method, path] = match;\n  return { label, method: method as ActionAnnotation['method'], path };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACsBO,IAAM,yBAAyB;AAa/B,IAAM,sBAAsB;AAQ5B,SAAS,iBAAiB,OAA8B;AAC7D,QAAM,cAAc,MAAM;AAC1B,SAAO,OAAO,gBAAgB,YAAY,YAAY,UAAU,EAAE,WAAW,sBAAsB;AACrG;AAwBO,SAAS,oBAAoB,OAA8C;AAChF,QAAM,cAAc,MAAM;AAC1B,MAAI,OAAO,gBAAgB,SAAU,QAAO;AAC5C,QAAM,UAAU,YAAY,UAAU;AACtC,MAAI,CAAC,QAAQ,WAAW,mBAAmB,EAAG,QAAO;AAErD,QAAM,OAAO,QAAQ,MAAM,oBAAoB,MAAM,EAAE,UAAU;AAEjE,QAAM,QAAQ,KAAK,MAAM,8CAA8C;AACvE,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,CAAC,EAAE,OAAO,QAAQ,IAAI,IAAI;AAChC,SAAO,EAAE,OAAO,QAA8C,KAAK;AACrE;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/schema-markers.ts"],"sourcesContent":["/**\n * @crowi/plugin-api — type-only contract for Crowi 2.0 plugins.\n *\n * Plugins author against this package. The runtime (@crowi/server) loads\n * plugins listed in `crowi.config.json`, calls each plugin's\n * `register*` callbacks, and routes all the side effects (storage,\n * search, auth, notifications) through the typed registries declared\n * here.\n *\n * For the design rationale see `docs/rfcs/0001-plugin-architecture.md`\n * in the Crowi monorepo.\n */\n\nexport type { CrowiPlugin } from './plugin';\n\nexport type { PluginContext, AppInfo, PageMetadataAccessor, PluginLogger, StateCell } from './context';\n\nexport type { StorageDriver, StorageRegistry, StoragePutMeta, StoragePutResult } from './registries/storage';\n\nexport type {\n  SearchDriver,\n  SearchRegistry,\n  SearchableDoc,\n  SearchQuery,\n  SearchQueryViewer,\n  SearchQueryGrants,\n  SearchPageType,\n  SearchHits,\n  SearchHit,\n} from './registries/search';\n\nexport type { AuthDriver, AuthRegistry, AuthProfile, AuthVerifyResult } from './registries/auth';\n\nexport type { NotifierDriver, NotifierRegistry, NotificationPayload } from './registries/notifier';\n\nexport type { MailSender, MailSenderRegistry, EmailMessage } from './registries/mail';\n\nexport type {\n  RendererRegistry,\n  NodeRenderer,\n  CodeBlockRenderer,\n  CodeBlockInfo,\n  EmbedRenderer,\n  EmbedInput,\n  EmbedFragment,\n  UrlInlineExpansionRule,\n  InlineExpansion,\n  RenderContext,\n  RenderPhase,\n  RenderResult,\n  RenderError,\n  Reservation,\n  CacheStorage,\n  ScopedCacheStorage,\n  CacheKey,\n  CacheEntry,\n  AuthContext,\n} from './renderer';\n\nexport type { EventBus, PluginEvents } from './events';\n\nexport type { PluginRouterScope, PluginRouteHandler, PluginRouteMethod, PluginRouteOptions } from './routes';\n\nexport { SENSITIVE_FIELD_MARKER, ACTION_FIELD_MARKER, isSensitiveField, getActionAnnotation } from './schema-markers';\n","import type { z } from 'zod/v3';\n\nimport type { PluginRouteMethod } from './routes';\n\n/**\n * `configSchema` description-string markers.\n *\n * The admin UI walks the schema and looks at each field's\n * `description` (set via `z.string().describe('@sensitive ...')`). A\n * description starting with one of these marker tokens unlocks special\n * UI behaviour without forcing every field to declare a custom Zod\n * type.\n */\n\n/**\n * Marker that flags a config field as sensitive (encrypted at rest).\n * Usage:\n *\n *   z.string().describe('@sensitive AWS secret access key')\n *\n * The runtime auto-encrypts on write and decrypts on read, using the\n * same KeyProvider as core sensitive Config. The admin UI renders the\n * field via `<SecretField>` (saved badge / clear pending / undo).\n */\nexport const SENSITIVE_FIELD_MARKER = '@sensitive';\n\n/**\n * Marker that adds an action button next to a config field. Usage:\n *\n *   z.string().describe('@action \"Test connection\" POST /test')\n *\n * The admin form renders a button with the given label that calls the\n * plugin's contributed endpoint at the given verb / path (relative to\n * `/api/v2/plugins/<name>/`). Useful for \"Test connection\",\n * \"Authorise with Google\", etc. without forcing every plugin to ship\n * its own React component.\n */\nexport const ACTION_FIELD_MARKER = '@action';\n\n/**\n * True if the schema field is marked `@sensitive`.\n *\n * `field` is `z.ZodTypeAny` (intentionally loose); call sites pass the\n * value type from `configSchema.shape[key]`.\n */\nexport function isSensitiveField(field: z.ZodTypeAny): boolean {\n  const description = field.description;\n  return typeof description === 'string' && description.trimStart().startsWith(SENSITIVE_FIELD_MARKER);\n}\n\n/**\n * Parsed `@action` annotation extracted from a field's `description`.\n */\nexport interface ActionAnnotation {\n  /** Visible button label, e.g. \"Test connection\". */\n  label: string;\n  /** HTTP verb of the plugin endpoint to call. */\n  method: PluginRouteMethod;\n  /** Path relative to `/api/v2/plugins/<name>/`, with leading slash. */\n  path: string;\n}\n\n/**\n * Parse an `@action` annotation off a field, or return null if absent.\n *\n * Format: `@action \"<label>\" <METHOD> <path>`\n *   e.g. `@action \"Test connection\" POST /test`\n *\n * The label may include spaces when wrapped in double quotes; the method\n * must be one of `PluginRouteMethod` (`GET` / `POST` — the only verbs a\n * plugin route can actually be mounted on, see `routes.ts`); the path\n * begins with `/`. A description that starts with the `@action` marker\n * but declares an unsupported verb (e.g. `PUT` / `DELETE`) fails to match\n * and returns `null` here — callers that walk a plugin's `configSchema`\n * (e.g. `PluginManager.activate()`) are expected to warn on that case at\n * boot, since it would otherwise be a silent dead button.\n */\nexport function getActionAnnotation(field: z.ZodTypeAny): ActionAnnotation | null {\n  const description = field.description;\n  if (typeof description !== 'string') return null;\n  const trimmed = description.trimStart();\n  if (!trimmed.startsWith(ACTION_FIELD_MARKER)) return null;\n\n  const rest = trimmed.slice(ACTION_FIELD_MARKER.length).trimStart();\n  // `\"<label>\" <METHOD> <path>`\n  const match = rest.match(/^\"([^\"]+)\"\\s+(GET|POST)\\s+(\\/\\S*)/);\n  if (!match) return null;\n\n  const [, label, method, path] = match;\n  return { label, method: method as ActionAnnotation['method'], path };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACwBO,IAAM,yBAAyB;AAa/B,IAAM,sBAAsB;AAQ5B,SAAS,iBAAiB,OAA8B;AAC7D,QAAM,cAAc,MAAM;AAC1B,SAAO,OAAO,gBAAgB,YAAY,YAAY,UAAU,EAAE,WAAW,sBAAsB;AACrG;AA6BO,SAAS,oBAAoB,OAA8C;AAChF,QAAM,cAAc,MAAM;AAC1B,MAAI,OAAO,gBAAgB,SAAU,QAAO;AAC5C,QAAM,UAAU,YAAY,UAAU;AACtC,MAAI,CAAC,QAAQ,WAAW,mBAAmB,EAAG,QAAO;AAErD,QAAM,OAAO,QAAQ,MAAM,oBAAoB,MAAM,EAAE,UAAU;AAEjE,QAAM,QAAQ,KAAK,MAAM,mCAAmC;AAC5D,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,CAAC,EAAE,OAAO,QAAQ,IAAI,IAAI;AAChC,SAAO,EAAE,OAAO,QAA8C,KAAK;AACrE;","names":[]}

package/dist/index.mjs

@@ -11,7 +11,7 @@ function getActionAnnotation(field) {
   const trimmed = description.trimStart();
   if (!trimmed.startsWith(ACTION_FIELD_MARKER)) return null;
   const rest = trimmed.slice(ACTION_FIELD_MARKER.length).trimStart();
-  const match = rest.match(/^"([^"]+)"\s+(GET|POST|PUT|DELETE)\s+(\/\S*)/);
+  const match = rest.match(/^"([^"]+)"\s+(GET|POST)\s+(\/\S*)/);
   if (!match) return null;
   const [, label, method, path] = match;
   return { label, method, path };

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/schema-markers.ts"],"sourcesContent":["import type { z } from 'zod/v3';\n\n/**\n * `configSchema` description-string markers.\n *\n * The admin UI walks the schema and looks at each field's\n * `description` (set via `z.string().describe('@sensitive ...')`). A\n * description starting with one of these marker tokens unlocks special\n * UI behaviour without forcing every field to declare a custom Zod\n * type.\n */\n\n/**\n * Marker that flags a config field as sensitive (encrypted at rest).\n * Usage:\n *\n *   z.string().describe('@sensitive AWS secret access key')\n *\n * The runtime auto-encrypts on write and decrypts on read, using the\n * same KeyProvider as core sensitive Config. The admin UI renders the\n * field via `<SecretField>` (saved badge / clear pending / undo).\n */\nexport const SENSITIVE_FIELD_MARKER = '@sensitive';\n\n/**\n * Marker that adds an action button next to a config field. Usage:\n *\n *   z.string().describe('@action \"Test connection\" POST /test')\n *\n * The admin form renders a button with the given label that calls the\n * plugin's contributed endpoint at the given verb / path (relative to\n * `/api/v2/plugins/<name>/`). Useful for \"Test connection\",\n * \"Authorise with Google\", etc. without forcing every plugin to ship\n * its own React component.\n */\nexport const ACTION_FIELD_MARKER = '@action';\n\n/**\n * True if the schema field is marked `@sensitive`.\n *\n * `field` is `z.ZodTypeAny` (intentionally loose); call sites pass the\n * value type from `configSchema.shape[key]`.\n */\nexport function isSensitiveField(field: z.ZodTypeAny): boolean {\n  const description = field.description;\n  return typeof description === 'string' && description.trimStart().startsWith(SENSITIVE_FIELD_MARKER);\n}\n\n/**\n * Parsed `@action` annotation extracted from a field's `description`.\n */\nexport interface ActionAnnotation {\n  /** Visible button label, e.g. \"Test connection\". */\n  label: string;\n  /** HTTP verb of the plugin endpoint to call. */\n  method: 'GET' | 'POST' | 'PUT' | 'DELETE';\n  /** Path relative to `/api/v2/plugins/<name>/`, with leading slash. */\n  path: string;\n}\n\n/**\n * Parse an `@action` annotation off a field, or return null if absent.\n *\n * Format: `@action \"<label>\" <METHOD> <path>`\n *   e.g. `@action \"Test connection\" POST /test`\n *\n * The label may include spaces when wrapped in double quotes; the\n * method is one of `GET` / `POST` / `PUT` / `DELETE`; the path begins\n * with `/`.\n */\nexport function getActionAnnotation(field: z.ZodTypeAny): ActionAnnotation | null {\n  const description = field.description;\n  if (typeof description !== 'string') return null;\n  const trimmed = description.trimStart();\n  if (!trimmed.startsWith(ACTION_FIELD_MARKER)) return null;\n\n  const rest = trimmed.slice(ACTION_FIELD_MARKER.length).trimStart();\n  // `\"<label>\" <METHOD> <path>`\n  const match = rest.match(/^\"([^\"]+)\"\\s+(GET|POST|PUT|DELETE)\\s+(\\/\\S*)/);\n  if (!match) return null;\n\n  const [, label, method, path] = match;\n  return { label, method: method as ActionAnnotation['method'], path };\n}\n"],"mappings":";AAsBO,IAAM,yBAAyB;AAa/B,IAAM,sBAAsB;AAQ5B,SAAS,iBAAiB,OAA8B;AAC7D,QAAM,cAAc,MAAM;AAC1B,SAAO,OAAO,gBAAgB,YAAY,YAAY,UAAU,EAAE,WAAW,sBAAsB;AACrG;AAwBO,SAAS,oBAAoB,OAA8C;AAChF,QAAM,cAAc,MAAM;AAC1B,MAAI,OAAO,gBAAgB,SAAU,QAAO;AAC5C,QAAM,UAAU,YAAY,UAAU;AACtC,MAAI,CAAC,QAAQ,WAAW,mBAAmB,EAAG,QAAO;AAErD,QAAM,OAAO,QAAQ,MAAM,oBAAoB,MAAM,EAAE,UAAU;AAEjE,QAAM,QAAQ,KAAK,MAAM,8CAA8C;AACvE,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,CAAC,EAAE,OAAO,QAAQ,IAAI,IAAI;AAChC,SAAO,EAAE,OAAO,QAA8C,KAAK;AACrE;","names":[]}
+{"version":3,"sources":["../src/schema-markers.ts"],"sourcesContent":["import type { z } from 'zod/v3';\n\nimport type { PluginRouteMethod } from './routes';\n\n/**\n * `configSchema` description-string markers.\n *\n * The admin UI walks the schema and looks at each field's\n * `description` (set via `z.string().describe('@sensitive ...')`). A\n * description starting with one of these marker tokens unlocks special\n * UI behaviour without forcing every field to declare a custom Zod\n * type.\n */\n\n/**\n * Marker that flags a config field as sensitive (encrypted at rest).\n * Usage:\n *\n *   z.string().describe('@sensitive AWS secret access key')\n *\n * The runtime auto-encrypts on write and decrypts on read, using the\n * same KeyProvider as core sensitive Config. The admin UI renders the\n * field via `<SecretField>` (saved badge / clear pending / undo).\n */\nexport const SENSITIVE_FIELD_MARKER = '@sensitive';\n\n/**\n * Marker that adds an action button next to a config field. Usage:\n *\n *   z.string().describe('@action \"Test connection\" POST /test')\n *\n * The admin form renders a button with the given label that calls the\n * plugin's contributed endpoint at the given verb / path (relative to\n * `/api/v2/plugins/<name>/`). Useful for \"Test connection\",\n * \"Authorise with Google\", etc. without forcing every plugin to ship\n * its own React component.\n */\nexport const ACTION_FIELD_MARKER = '@action';\n\n/**\n * True if the schema field is marked `@sensitive`.\n *\n * `field` is `z.ZodTypeAny` (intentionally loose); call sites pass the\n * value type from `configSchema.shape[key]`.\n */\nexport function isSensitiveField(field: z.ZodTypeAny): boolean {\n  const description = field.description;\n  return typeof description === 'string' && description.trimStart().startsWith(SENSITIVE_FIELD_MARKER);\n}\n\n/**\n * Parsed `@action` annotation extracted from a field's `description`.\n */\nexport interface ActionAnnotation {\n  /** Visible button label, e.g. \"Test connection\". */\n  label: string;\n  /** HTTP verb of the plugin endpoint to call. */\n  method: PluginRouteMethod;\n  /** Path relative to `/api/v2/plugins/<name>/`, with leading slash. */\n  path: string;\n}\n\n/**\n * Parse an `@action` annotation off a field, or return null if absent.\n *\n * Format: `@action \"<label>\" <METHOD> <path>`\n *   e.g. `@action \"Test connection\" POST /test`\n *\n * The label may include spaces when wrapped in double quotes; the method\n * must be one of `PluginRouteMethod` (`GET` / `POST` — the only verbs a\n * plugin route can actually be mounted on, see `routes.ts`); the path\n * begins with `/`. A description that starts with the `@action` marker\n * but declares an unsupported verb (e.g. `PUT` / `DELETE`) fails to match\n * and returns `null` here — callers that walk a plugin's `configSchema`\n * (e.g. `PluginManager.activate()`) are expected to warn on that case at\n * boot, since it would otherwise be a silent dead button.\n */\nexport function getActionAnnotation(field: z.ZodTypeAny): ActionAnnotation | null {\n  const description = field.description;\n  if (typeof description !== 'string') return null;\n  const trimmed = description.trimStart();\n  if (!trimmed.startsWith(ACTION_FIELD_MARKER)) return null;\n\n  const rest = trimmed.slice(ACTION_FIELD_MARKER.length).trimStart();\n  // `\"<label>\" <METHOD> <path>`\n  const match = rest.match(/^\"([^\"]+)\"\\s+(GET|POST)\\s+(\\/\\S*)/);\n  if (!match) return null;\n\n  const [, label, method, path] = match;\n  return { label, method: method as ActionAnnotation['method'], path };\n}\n"],"mappings":";AAwBO,IAAM,yBAAyB;AAa/B,IAAM,sBAAsB;AAQ5B,SAAS,iBAAiB,OAA8B;AAC7D,QAAM,cAAc,MAAM;AAC1B,SAAO,OAAO,gBAAgB,YAAY,YAAY,UAAU,EAAE,WAAW,sBAAsB;AACrG;AA6BO,SAAS,oBAAoB,OAA8C;AAChF,QAAM,cAAc,MAAM;AAC1B,MAAI,OAAO,gBAAgB,SAAU,QAAO;AAC5C,QAAM,UAAU,YAAY,UAAU;AACtC,MAAI,CAAC,QAAQ,WAAW,mBAAmB,EAAG,QAAO;AAErD,QAAM,OAAO,QAAQ,MAAM,oBAAoB,MAAM,EAAE,UAAU;AAEjE,QAAM,QAAQ,KAAK,MAAM,mCAAmC;AAC5D,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,CAAC,EAAE,OAAO,QAAQ,IAAI,IAAI;AAChC,SAAO,EAAE,OAAO,QAA8C,KAAK;AACrE;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowi/plugin-api",
-  "version": "0.1.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "description": "Type-only contract for Crowi 2.0 plugins. See docs/rfcs/0001-plugin-architecture.md.",
   "repository": {
     "type": "git",
@@ -29,8 +29,11 @@
     "zod": "^4"
   },
   "devDependencies": {
+    "@types/jest": "^29.5.14",
     "@types/node": "^24",
     "hono": "^4.12.25",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.3.4",
     "tsup": "^8.3.5",
     "typescript": "^5.8.3",
     "zod": "^4.4.3",
@@ -39,6 +42,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch --no-clean",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "test": "jest --passWithNoTests"
   }
 }