@aphexcms/cms-core 9.3.0 → 9.5.0

package/dist/plugins/types.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Plugin type system — the public authoring surface.
+ *
+ * A plugin is a manifest of typed "parts", each implementing a named extension
+ * point. The kinds are split into two planes (see PLUGIN_SYSTEM_PLAN.md §Constraint):
+ *
+ *  - SERVER / serializable plane — schemas, server routes, capabilities. Collected
+ *    by the engine at boot; safe to reason about without loading any component.
+ *  - COMPONENT plane — document actions, admin tools, field components. These carry
+ *    Svelte components and are only ever imported into admin module code, never
+ *    passed through SvelteKit `load` (load data must stay serializable).
+ *
+ * All imports here are type-only, so this module is safe on both planes.
+ */
+import type { Component } from 'svelte';
+import type { Context, Hono } from 'hono';
+import type { AphexEnv } from '../server/api/index.js';
+import type { Field, SettingsField, SchemaType } from '../types/schemas.js';
+import type { AdminArea } from '../admin/types.js';
+import type { CapabilityDefinition } from '../types/capabilities.js';
+/** Known extension points. Plugins may also register custom string kinds. */
+export type PartKind = 'aphex/schema' | 'aphex/schema/transform' | 'aphex/server/route' | 'aphex/capabilities' | 'aphex/settings' | 'aphex/document/action' | 'aphex/admin/tool' | 'aphex/field/component';
+/** Contributes content schemas, merged into the app's `schemaTypes`. */
+export interface SchemaPart {
+    implements: 'aphex/schema';
+    schemas: SchemaType[];
+}
+/**
+ * Transforms the resolved schema list — decorate existing types, not just add new
+ * ones (e.g. inject an SEO field group into a set of collections). Runs after all
+ * `aphex/schema` parts merge, on both the server engine and the admin, so the
+ * transform must be pure and deterministic. This is what lets a plugin "enable"
+ * itself on chosen document types the way Payload's `collections: [...]` does.
+ */
+export interface SchemaTransformPart {
+    implements: 'aphex/schema/transform';
+    transform: (schemas: SchemaType[]) => SchemaType[];
+}
+/**
+ * Contributes an HTTP endpoint under `/api`. `path: '/bookings'` + `method: 'POST'`
+ * becomes `POST /api/bookings`. The handler gets the same Hono context as built-ins
+ * (`c.var.aphexCMS`, `c.var.auth`).
+ */
+export interface ServerRoutePart {
+    implements: 'aphex/server/route';
+    /** Unique across all plugins — collisions are a startup error. */
+    id: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    handler: (c: Context<AphexEnv>) => Response | Promise<Response>;
+    /**
+     * Who may call this route. Mandatory and with no default: a plugin route is an
+     * ordinary internet-facing endpoint, and "I forgot" must not be spellable as
+     * "anyone may call this". Say which of the three you mean:
+     *
+     * - `['forms.export']` — must be authenticated AND hold every listed capability.
+     *   The usual answer. The CMS gates the route before the handler runs (401 with no
+     *   session/api-key, 403 when capabilities are missing), so the check can't be
+     *   forgotten in the handler.
+     * - `[]` — must be authenticated, but any role will do. Use when membership of the
+     *   organization is itself the authorization.
+     * - `'public'` — no gate; anyone on the internet can call it. For webhook receivers
+     *   and the like, where the handler does its own verification (a signature, a shared
+     *   secret). Opting out is deliberate and greppable.
+     */
+    requiredCapabilities: string[] | 'public';
+}
+/**
+ * Declares custom capabilities this plugin introduces — surfaced (and assignable) in
+ * the roles UI. Pass `defineCapability(id, { title, description, group })` for full
+ * metadata, or a bare id string (labelled from its last segment). Merged with the
+ * built-in catalog by the part resolver (`capabilityCatalog()`); a plugin can't
+ * redefine a core capability.
+ */
+export interface CapabilitiesPart {
+    implements: 'aphex/capabilities';
+    capabilities: (string | CapabilityDefinition)[];
+}
+/**
+ * Declares a plugin's **settings surface** — configuration a user edits in the
+ * admin UI (connection details, toggles, and — in phase 2 — secrets), stored
+ * per-`(organization, plugin)` and injected back into the plugin's server code.
+ *
+ * This is CONFIG, not content: settings are deliberately NOT content schema types.
+ * They never enter document lists, draft/published perspectives, versioning, the
+ * content REST/GraphQL API, MCP tools, or generated types. Only the field *renderer*
+ * is reused (the same UI that draws a document field), never the type registry,
+ * content storage, or content API. See references/plugin-settings-and-secrets-scope.md.
+ *
+ * Declaration only, like every other serializable part — the host owns rendering,
+ * storage, encryption, gating, and injection. A plugin only says what its settings
+ * look like.
+ */
+export interface SettingsPart {
+    implements: 'aphex/settings';
+    /**
+     * Which plugin these settings belong to — the storage key alongside the org.
+     * Use the plugin's package name (e.g. `@aphexcms/forms`) so it's stable and unique.
+     */
+    pluginId: string;
+    /** Human label for the settings section in the admin UI. */
+    title: string;
+    /** Optional one-line description shown under the title. */
+    description?: string;
+    /**
+     * The settings fields. `SettingsField` is a deliberately narrow subset — `string`,
+     * `text`, `number`, `boolean`, plus the settings-only `secret` (write-only,
+     * encrypted at rest) — so every declared field is one the panel really renders and
+     * the service really validates. No content-schema features (references, portable
+     * text, assets) and no custom `input` widgets. Values are type-checked against
+     * these declarations on save.
+     */
+    fields: SettingsField[];
+    /**
+     * Capabilities required to view/edit this settings section. Defaults to the
+     * built-in `plugin.settings.manage` when omitted — set a narrower capability to
+     * gate a specific plugin's settings more tightly.
+     */
+    requiredCapabilities?: string[];
+}
+/**
+ * A minimal, stable context handed to a document-action component. Deliberately
+ * decoupled from editor internals — actions get exactly this and nothing more, so
+ * the editor can be refactored without breaking plugins.
+ */
+export interface DocumentActionProps {
+    /** Null while the document is new and unsaved. */
+    documentId: string | null;
+    schema: SchemaType;
+    /** The live edited draft data. */
+    data: Record<string, unknown>;
+    status: 'new' | 'draft' | 'published' | 'unpublished';
+    /** Shallow-merge a patch into the document's data. */
+    updateData: (patch: Record<string, unknown>) => void;
+    save: () => Promise<void>;
+    publish: () => Promise<void>;
+}
+/** Adds a button/action to the document editor toolbar. */
+export interface DocumentActionPart {
+    implements: 'aphex/document/action';
+    /** Unique across all plugins. */
+    id: string;
+    title: string;
+    icon?: Component;
+    component: Component<{
+        action: DocumentActionProps;
+    }>;
+    /** Document type names this applies to. Omit for all types. */
+    appliesTo?: string[];
+    requiredCapabilities?: string[];
+    order?: number;
+}
+/**
+ * The stable context handed to an admin-tool component — enough to read the
+ * environment, gate on capabilities, and navigate, without touching AdminApp
+ * internals. For document data, tools use the REST client (session-authenticated).
+ */
+export interface AdminToolProps {
+    organizationId: string | null;
+    capabilities: readonly string[];
+    role: string | null;
+    /** True if the session has the capability (privileged roles bypass). */
+    can: (capability: string) => boolean;
+    /** All content schemas (read-only), for listing document types etc. */
+    schemas: SchemaType[];
+    /** Switch the active admin area/tab (e.g. back to `'structure'`). */
+    navigate: (area: AdminArea) => void;
+    /** Open a document in the editor. */
+    openDocument: (documentType: string, documentId: string) => void;
+}
+/** Adds a top-level admin section (its own tool). */
+export interface AdminToolPart {
+    implements: 'aphex/admin/tool';
+    /** Unique across all plugins; also the tool's route key. */
+    id: string;
+    title: string;
+    icon?: Component;
+    component: Component<{
+        tool: AdminToolProps;
+    }>;
+    requiredCapabilities?: string[];
+    order?: number;
+    /**
+     * Where the tool's trigger renders. `'tab'` (default) puts it in the top tab
+     * strip alongside Content/Media/Vision; `'sidebar'` puts it in the left sidebar
+     * nav instead — better once several plugins are installed and the tab strip
+     * would overflow. Either way the tool opens the same `plugin:<id>` area.
+     */
+    placement?: 'tab' | 'sidebar';
+}
+/**
+ * The stable props a field-input widget receives — the same shape the built-in
+ * field renderers use, so a plugin widget is a drop-in replacement.
+ */
+export interface FieldComponentProps {
+    field: Field;
+    value: unknown;
+    onUpdate: (value: unknown) => void;
+    readonly?: boolean;
+    /** Validation-state CSS classes to spread onto the control (optional). */
+    validationClasses?: string;
+    /** The whole document's data — for widgets that read sibling fields (e.g. an SEO preview). */
+    documentData?: Record<string, unknown>;
+    /** The document's type name (e.g. `'author'`) — for widgets that vary by type. */
+    schemaType?: string;
+}
+/**
+ * Provides a custom input widget, selected by a field's `input` key in the schema
+ * (e.g. `{ type: 'string', input: 'color' }`).
+ */
+export interface FieldComponentPart {
+    implements: 'aphex/field/component';
+    /** Matched against a field's `input` property. */
+    input: string;
+    component: Component<FieldComponentProps>;
+}
+export type PluginPart = SchemaPart | SchemaTransformPart | ServerRoutePart | CapabilitiesPart | SettingsPart | DocumentActionPart | AdminToolPart | FieldComponentPart;
+/** A plugin manifest. Returned by `definePlugin`. */
+export interface CMSPlugin {
+    /** Package-style name, e.g. `@acme/aphex-plugin-seo`. Used in error messages. */
+    name: string;
+    version?: string;
+    parts?: PluginPart[];
+}
+/** Registration hook available to server-route parts (kept for the api-mount seam). */
+export type RegisterRoutes = (app: Hono<AphexEnv>) => void;
+/**
+ * Identity helper that pins the `CMSPlugin` type for authoring. Kept a pure
+ * pass-through so bundlers can tree-shake unused plugins; validation (duplicate
+ * ids/names) happens in the part resolver at boot, where it can see all plugins.
+ */
+export declare function definePlugin(plugin: CMSPlugin): CMSPlugin;
+//# sourceMappingURL=types.d.ts.map

package/dist/plugins/types.d.ts.map

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

package/dist/plugins/types.js

@@ -0,0 +1,8 @@
+/**
+ * Identity helper that pins the `CMSPlugin` type for authoring. Kept a pure
+ * pass-through so bundlers can tree-shake unused plugins; validation (duplicate
+ * ids/names) happens in the part resolver at boot, where it can see all plugins.
+ */
+export function definePlugin(plugin) {
+    return plugin;
+}

package/dist/schema-utils/desugar.d.ts

@@ -0,0 +1,27 @@
+import type { Field, SchemaType } from '../types/schemas.js';
+export interface DesugarOptions {
+    /** The authored `type` keyword to replace, e.g. `'color'`. */
+    type: string;
+    /**
+     * Build the replacement from the authored field. Own the *shape* only — `type`,
+     * `fields`, and the default `input`/`inputOptions`. Anything you copy off the
+     * authored field here is redundant: it is layered back on afterwards.
+     */
+    build: (authored: Field) => Field;
+    /**
+     * Keys that exist only on the sugar type and must not survive onto the expanded
+     * field (e.g. color's `alpha`, which becomes `inputOptions.alpha`). Everything
+     * else the author wrote is preserved.
+     */
+    sugarKeys?: readonly string[];
+}
+/**
+ * Desugar every `{ type: <options.type> }` field across a schema list, recursing into
+ * nested objects and array members, preserving everything the author declared.
+ *
+ * Intended as the body of an `aphex/schema/transform` part, so it runs identically in
+ * the engine, the admin, and the type generator — nothing downstream ever sees the
+ * sugar keyword.
+ */
+export declare function desugarFieldType(schemas: SchemaType[], options: DesugarOptions): SchemaType[];
+//# sourceMappingURL=desugar.d.ts.map

package/dist/schema-utils/desugar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desugar.d.ts","sourceRoot":"","sources":["../../src/lib/schema-utils/desugar.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAiB,MAAM,kBAAkB,CAAC;AAEzE,MAAM,WAAW,cAAc;IAC9B,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,EAAE,CAAC,QAAQ,EAAE,KAAK,KAAK,KAAK,CAAC;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AA6ED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,UAAU,EAAE,CAM7F"}

package/dist/schema-utils/desugar.js

@@ -0,0 +1,101 @@
+// schema-utils/desugar.ts
+//
+// Shared machinery for `aphex/schema/transform` parts that desugar a custom field
+// keyword into a real field — e.g. `{ type: 'color' }` → the color `object`, or
+// `{ type: 'seo' }` → the SEO `object`.
+//
+// Every such transform has the same two jobs, and the second is easy to get wrong:
+//
+//   1. Walk the whole schema list — fields, nested object fields, and array members.
+//   2. Replace the sugar field WITHOUT losing what the author wrote on it.
+//
+// Hand-rolled transforms tended to rebuild the field from a hand-picked subset
+// (`name`/`title`/`description`/`group`), which silently dropped `access` — turning a
+// restricted field unrestricted — along with `validation` and every group after the
+// first. Preservation is the default here so a plugin author can't forget it: the
+// builder supplies only the shape, and the authored field is layered back on top.
+/**
+ * Layer the authored field back over the built one.
+ *
+ * The builder owns structure (`type`, `fields`); the author owns intent (`group`,
+ * `validation`, `access`, and any property added to BaseField later — hence a
+ * spread rather than an allowlist, which would silently go stale).
+ */
+function preserveAuthored(authored, built, sugarKeys) {
+    const rest = { ...authored };
+    delete rest.type;
+    for (const key of sugarKeys)
+        delete rest[key];
+    const builtRecord = built;
+    const merged = {
+        ...builtRecord,
+        ...rest,
+        // Re-assert what the desugaring defines: the author wrote `type: 'color'`,
+        // not the object it expands to.
+        type: builtRecord.type,
+        // An author who explicitly asked for a different widget still wins; otherwise
+        // the builder's widget is the whole point of the field type.
+        input: rest.input ?? builtRecord.input,
+        // Merged, not replaced: the builder derives options from the sugar keys
+        // (color's `alpha` → `inputOptions.alpha`), so letting an authored
+        // `inputOptions` win wholesale would silently drop them. Authored keys still
+        // win individually.
+        inputOptions: mergeInputOptions(builtRecord.inputOptions, rest.inputOptions)
+    };
+    if ('fields' in builtRecord)
+        merged.fields = builtRecord.fields;
+    return merged;
+}
+/** Combine the builder's derived widget options with any the author declared. */
+function mergeInputOptions(built, authored) {
+    const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+    if (!isRecord(built))
+        return isRecord(authored) ? authored : undefined;
+    if (!isRecord(authored))
+        return built;
+    return { ...built, ...authored };
+}
+function expandFields(fields, options) {
+    const sugarKeys = options.sugarKeys ?? [];
+    return fields.map((field) => {
+        if (field.type === options.type) {
+            return preserveAuthored(field, options.build(field), sugarKeys);
+        }
+        if (field.type === 'object' && Array.isArray(field.fields)) {
+            return { ...field, fields: expandFields(field.fields, options) };
+        }
+        if (field.type === 'array' && Array.isArray(field.of)) {
+            return { ...field, of: field.of.map((member) => expandMember(member, options)) };
+        }
+        return field;
+    });
+}
+/** Array `of` members are `TypeReference`s, not `Field`s — expand them the same way. */
+function expandMember(member, options) {
+    if (member.type === options.type) {
+        // A member names a *type*, so `name` is often absent — but builders take a
+        // named field. Fall back to the sugar keyword so the expansion keeps its
+        // identity (`{ of: [{ type: 'color' }] }` stays a recognisable color member
+        // instead of becoming an anonymous object).
+        const authored = { ...member, name: member.name ?? options.type };
+        const built = options.build(authored);
+        return preserveAuthored(authored, built, options.sugarKeys ?? []);
+    }
+    if (Array.isArray(member.fields)) {
+        return { ...member, fields: expandFields(member.fields, options) };
+    }
+    return member;
+}
+/**
+ * Desugar every `{ type: <options.type> }` field across a schema list, recursing into
+ * nested objects and array members, preserving everything the author declared.
+ *
+ * Intended as the body of an `aphex/schema/transform` part, so it runs identically in
+ * the engine, the admin, and the type generator — nothing downstream ever sees the
+ * sugar keyword.
+ */
+export function desugarFieldType(schemas, options) {
+    return schemas.map((schema) => 'fields' in schema && Array.isArray(schema.fields)
+        ? { ...schema, fields: expandFields(schema.fields, options) }
+        : schema);
+}

package/dist/schema-utils/index.d.ts

@@ -1,4 +1,6 @@
 export * from './cleanup.js';
+export * from './desugar.js';
+export * from './settings.js';
 export * from './utils.js';
 export * from './validator.js';
 export * from './singleton.js';

package/dist/schema-utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/schema-utils/index.ts"],"names":[],"mappings":"AACA,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/schema-utils/index.ts"],"names":[],"mappings":"AACA,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/schema-utils/index.js

@@ -1,5 +1,7 @@
 // Schema utilities - all schema-related helper functions
 export * from './cleanup.js';
+export * from './desugar.js';
+export * from './settings.js';
 export * from './utils.js';
 export * from './validator.js';
 export * from './singleton.js';

package/dist/schema-utils/settings.d.ts

@@ -0,0 +1,17 @@
+import type { SettingsField } from '../types/schemas.js';
+/** A normalized select option: what the user sees, and what gets stored. */
+export interface SettingsListItem {
+    title: string;
+    value: string;
+}
+/**
+ * The select options for a settings field, normalized from `StringField.list`'s
+ * loose shape (bare strings, or `{title, value}` objects) — empty when the field
+ * isn't a select.
+ *
+ * A `DependentList` yields no options: its valid values are a function of another
+ * field's value, which settings doesn't resolve. The panel renders such a field as a
+ * free-text input, so the validator must not treat it as a closed set either.
+ */
+export declare function settingsListItems(field: SettingsField): SettingsListItem[];
+//# sourceMappingURL=settings.d.ts.map

package/dist/schema-utils/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/lib/schema-utils/settings.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,EAAE,CAK1E"}

package/dist/schema-utils/settings.js

@@ -0,0 +1,22 @@
+// Helpers for plugin settings declarations (`aphex/settings`).
+//
+// Shared by the settings panel (which renders the options) and PluginSettingsService
+// (which validates a submitted value against them). They must agree: if they drift,
+// the panel offers a choice the server rejects. So the normalization lives here once.
+/**
+ * The select options for a settings field, normalized from `StringField.list`'s
+ * loose shape (bare strings, or `{title, value}` objects) — empty when the field
+ * isn't a select.
+ *
+ * A `DependentList` yields no options: its valid values are a function of another
+ * field's value, which settings doesn't resolve. The panel renders such a field as a
+ * free-text input, so the validator must not treat it as a closed set either.
+ */
+export function settingsListItems(field) {
+    if (field.type !== 'string')
+        return [];
+    const list = field.list;
+    if (!Array.isArray(list))
+        return [];
+    return list.map((item) => (typeof item === 'string' ? { title: item, value: item } : item));
+}

package/dist/schema-utils/validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/lib/schema-utils/validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAS,MAAM,kBAAkB,CAAC;AAmB1D;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,sFAAsF;AACtF,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAyB,CAAC;AAEvE,wEAAwE;AACxE,eAAO,MAAM,qBAAqB,EAAE,MAAM,EAYzC,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAAkD,CAAC;AAEzF;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,IAAI,CAsNpE"}
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/lib/schema-utils/validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAS,MAAM,kBAAkB,CAAC;AAmB1D;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,sFAAsF;AACtF,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAyB,CAAC;AAEvE,wEAAwE;AACxE,eAAO,MAAM,qBAAqB,EAAE,MAAM,EAYzC,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAAkD,CAAC;AAEzF;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,IAAI,CAmOpE"}

package/dist/schema-utils/validator.js

@@ -44,6 +44,17 @@ export const VALID_FIELD_TYPES = [...PRIMITIVE_FIELD_TYPES, 'array', 'object'];
 export function validateSchemaReferences(schemas) {
     const schemaNames = new Set(schemas.map((schema) => schema.name));
     const errors = [];
+    // Duplicate schema names are a hard error — no silent overrides. This matters
+    // most once plugins merge their schemas into the app's: a collision would
+    // otherwise let one type shadow another. Report every duplicate name once.
+    const nameCounts = new Map();
+    for (const schema of schemas)
+        nameCounts.set(schema.name, (nameCounts.get(schema.name) ?? 0) + 1);
+    for (const [name, count] of nameCounts) {
+        if (count > 1) {
+            errors.push(`Duplicate schema name "${name}" (defined ${count} times). Schema names must be unique across app and plugin schemas.`);
+        }
+    }
     // Field-type lists live at module scope (shared source of truth).
     const primitiveTypes = PRIMITIVE_FIELD_TYPES;
     const validFieldTypes = VALID_FIELD_TYPES;

package/dist/security/secret-crypto.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Encrypt a plaintext string into a self-describing envelope
+ * `v1:<iv>:<authTag>:<ciphertext>` (base64 segments). Safe to store as an ordinary
+ * string in the settings blob.
+ */
+export declare function encryptSecret(plaintext: string, secret: string): string;
+/**
+ * Decrypt an envelope produced by {@link encryptSecret}. Throws if the envelope is
+ * malformed, the version is unknown, or authentication fails (wrong key / tampering).
+ */
+export declare function decryptSecret(envelope: string, secret: string): string;
+/**
+ * Whether a stored value looks like one of our encryption envelopes. Lets the service
+ * tell "already-encrypted ciphertext" from "a value that still needs encrypting"
+ * without trying to decrypt.
+ */
+export declare function isEncryptedSecret(value: unknown): value is string;
+//# sourceMappingURL=secret-crypto.d.ts.map

package/dist/security/secret-crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-crypto.d.ts","sourceRoot":"","sources":["../../src/lib/security/secret-crypto.ts"],"names":[],"mappings":"AA6BA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAYvE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CActE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEjE"}

package/dist/security/secret-crypto.js

@@ -0,0 +1,70 @@
+// security/secret-crypto.ts
+//
+// Authenticated symmetric encryption for plugin secrets (the one genuinely-new
+// brick of the settings/secrets feature — see references/plugin-settings-and-secrets-scope.md).
+//
+// SERVER ONLY: imports `node:crypto`. Never import this from client/admin code — a
+// decrypted secret must never reach the browser. It's kept out of the cms-core client
+// barrel deliberately.
+//
+// Design (mirrors the good ideas from Better Auth's `symmetricEncrypt`, without the
+// dependency — cms-core stays auth-provider-agnostic):
+//   - AES-256-GCM: authenticated (AEAD), so tampering is detected on decrypt.
+//   - Random 96-bit IV per encryption (never reused).
+//   - Versioned envelope `v1:<iv>:<tag>:<ciphertext>` (all base64). The version prefix
+//     is what makes key rotation possible later: add `v2`, decrypt either, re-encrypt
+//     on next write — no data migration.
+//   - Key derived via SHA-256 so any-length configured secret becomes a valid 32-byte key.
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+const VERSION = 'v1';
+const ALGORITHM = 'aes-256-gcm';
+const IV_BYTES = 12; // 96-bit nonce, the GCM standard.
+/** Derive a 32-byte AES key from an arbitrary-length configured secret. */
+function deriveKey(secret) {
+    return createHash('sha256').update(secret, 'utf8').digest();
+}
+/**
+ * Encrypt a plaintext string into a self-describing envelope
+ * `v1:<iv>:<authTag>:<ciphertext>` (base64 segments). Safe to store as an ordinary
+ * string in the settings blob.
+ */
+export function encryptSecret(plaintext, secret) {
+    const key = deriveKey(secret);
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv(ALGORITHM, key, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    return [
+        VERSION,
+        iv.toString('base64'),
+        authTag.toString('base64'),
+        ciphertext.toString('base64')
+    ].join(':');
+}
+/**
+ * Decrypt an envelope produced by {@link encryptSecret}. Throws if the envelope is
+ * malformed, the version is unknown, or authentication fails (wrong key / tampering).
+ */
+export function decryptSecret(envelope, secret) {
+    const parts = envelope.split(':');
+    const [version, ivB64, tagB64, ctB64] = parts;
+    if (parts.length !== 4 || version !== VERSION || !ivB64 || !tagB64 || !ctB64) {
+        throw new Error('Malformed or unsupported secret envelope');
+    }
+    const key = deriveKey(secret);
+    const decipher = createDecipheriv(ALGORITHM, key, Buffer.from(ivB64, 'base64'));
+    decipher.setAuthTag(Buffer.from(tagB64, 'base64'));
+    const plaintext = Buffer.concat([
+        decipher.update(Buffer.from(ctB64, 'base64')),
+        decipher.final()
+    ]);
+    return plaintext.toString('utf8');
+}
+/**
+ * Whether a stored value looks like one of our encryption envelopes. Lets the service
+ * tell "already-encrypted ciphertext" from "a value that still needs encrypting"
+ * without trying to decrypt.
+ */
+export function isEncryptedSecret(value) {
+    return typeof value === 'string' && value.startsWith(`${VERSION}:`);
+}

package/dist/server/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/server/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAoB7C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG;IACtB,SAAS,EAAE;QACV,QAAQ,EAAE,YAAY,CAAC;QACvB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;KAClB,CAAC;IACF,QAAQ,EAAE;QACT,QAAQ,EAAE,YAAY,CAAC;QACvB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;KAClB,CAAC;CACF,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,cAAc,kGAqB7B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,QAkDrD;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,IACtE,GAAG,OAAO,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,uBAejD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/server/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAqB7C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG;IACtB,SAAS,EAAE;QACV,QAAQ,EAAE,YAAY,CAAC;QACvB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;KAClB,CAAC;IACF,QAAQ,EAAE;QACT,QAAQ,EAAE,YAAY,CAAC;QACvB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;KAClB,CAAC;CACF,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,cAAc,kGAqB7B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,QAqDrD;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,IACtE,GAAG,OAAO,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,uBAejD"}

package/dist/server/api/index.js

@@ -16,6 +16,7 @@ import { organizationsInvitationsRouter } from './routes/organizations-invitatio
 import { organizationsMembersRouter } from './routes/organizations-members.js';
 import { organizationsSwitchRouter } from './routes/organizations-switch.js';
 import { rolesRouter } from './routes/roles.js';
+import { pluginSettingsRouter } from './routes/plugin-settings.js';
 import { userPreferencesRouter } from './routes/user-preferences.js';
 import { userRouter } from './routes/user.js';
 /**
@@ -77,6 +78,8 @@ export function mountAphexBuiltins(app) {
     app.route('/organizations', organizationsRouter);
     // Roles — combined router covers /, /:name, no precedence concern.
     app.route('/roles', rolesRouter);
+    // Plugin settings — the config plane. `/`, `/:pluginId`, no precedence concern.
+    app.route('/plugin-settings', pluginSettingsRouter);
     // User account routes — register specifics first.
     // `/user/cms-preference`, `/user/request-password-reset`,
     // `/user/reset-password` need to win over `/user` PATCH otherwise

package/dist/server/api/routes/assets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/assets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAM5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,eAAO,MAAM,YAAY,EAAE,IAAI,CAAC,QAAQ,CA8JrC,CAAC"}
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/assets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAM5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,eAAO,MAAM,YAAY,EAAE,IAAI,CAAC,QAAQ,CAoKrC,CAAC"}

package/dist/server/api/routes/assets.js

@@ -25,6 +25,7 @@ export const assetsRouter = new Hono()
             assetType: q.assetType,
             mimeType: q.mimeType,
             search: q.search,
+            includeSystem: q.includeSystem ?? false,
             limit: q.limit ?? 20,
             offset: q.offset ?? 0
         };
@@ -34,7 +35,8 @@ export const assetsRouter = new Hono()
             databaseAdapter.countAssets(auth.organizationId, {
                 assetType: filters.assetType,
                 mimeType: filters.mimeType,
-                search: filters.search
+                search: filters.search,
+                includeSystem: filters.includeSystem
             })
         ]);
         const pageSize = filters.limit || 20;
@@ -101,6 +103,8 @@ export const assetsRouter = new Hono()
         const creditLine = formData.get('creditLine') || undefined;
         const schemaType = formData.get('schemaType') || undefined;
         const fieldPath = formData.get('fieldPath') || undefined;
+        const system = formData.get('system') === 'true' || undefined;
+        const usage = formData.get('usage') || undefined;
         const targetOrganizationId = auth.organizationId;
         const uploadData = {
             organizationId: targetOrganizationId,
@@ -115,7 +119,9 @@ export const assetsRouter = new Hono()
             createdBy: auth.type === 'session' ? auth.user.id : undefined,
             metadata: {
                 schemaType,
-                fieldPath
+                fieldPath,
+                system,
+                usage
             }
         };
         const asset = await assetService.uploadAsset(targetOrganizationId, uploadData);

package/dist/server/api/routes/organizations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"organizations.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/organizations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAI5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,eAAO,MAAM,mBAAmB,EAAE,IAAI,CAAC,QAAQ,CA8H7C,CAAC"}
+{"version":3,"file":"organizations.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/organizations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAI5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,eAAO,MAAM,mBAAmB,EAAE,IAAI,CAAC,QAAQ,CAoI7C,CAAC"}