payload-mcp-toolkit 0.3.4 → 0.7.4

package/dist/api-keys.js

@@ -0,0 +1,308 @@
+export const API_KEYS_DEFAULT_SLUG = 'payload-mcp-api-keys';
+const PRESET_OPTIONS = [
+    {
+        label: 'Read-only',
+        value: 'read-only'
+    },
+    {
+        label: 'Editor (read + create + update)',
+        value: 'editor'
+    },
+    {
+        label: 'Admin (all actions)',
+        value: 'admin'
+    },
+    {
+        label: 'Custom (use overrides below)',
+        value: 'custom'
+    }
+];
+const isCustomPreset = (data)=>!!data && typeof data === 'object' && data.preset === 'custom';
+/**
+ * Builds the `payload-mcp-api-keys` collection used by the v0.4 standalone
+ * plugin. Reuses Payload's built-in `useAPIKey: true` so the underlying
+ * `apiKey` / `apiKeyIndex` columns match what `@payloadcms/plugin-mcp`
+ * v0.3.x wrote — existing rows authenticate without re-issue.
+ *
+ * Layout:
+ *   - Main column: name, description, preset, scopes matrix (custom only),
+ *     tools collapsible (custom only).
+ *   - Sidebar: user relationship, key prefix, expiresAt, revokedAt,
+ *     lastUsedAt — identity + lifecycle metadata kept out of the
+ *     scope-editing flow.
+ */ export function createApiKeysCollection(options) {
+    if (!options || !options.userCollection) {
+        throw new Error('createApiKeysCollection: `userCollection` is required (slug of the user collection that owns API keys).');
+    }
+    if (!Array.isArray(options.availableCollections)) {
+        throw new Error('createApiKeysCollection: `availableCollections` is required (slugs of collections that scope overrides may target).');
+    }
+    if (!Array.isArray(options.availableTools)) {
+        throw new Error('createApiKeysCollection: `availableTools` is required (names of registered MCP tools).');
+    }
+    const slug = options.slug ?? API_KEYS_DEFAULT_SLUG;
+    const toolOptions = options.availableTools.map((t)=>({
+            label: t,
+            value: t
+        }));
+    const availableGlobals = Array.isArray(options.availableGlobals) ? options.availableGlobals : [];
+    const presetField = {
+        name: 'preset',
+        type: 'select',
+        required: true,
+        defaultValue: 'custom',
+        options: PRESET_OPTIONS,
+        admin: {
+            description: 'Role preset. "Custom" unlocks the per-collection matrix and the tool overrides below. ' + 'Switching away from Custom CLEARS every override on save (collectionScopes, globalScopes, ' + 'toolAllow, toolDeny); switching back to Custom starts from a fresh deny-all baseline, so ' + 'reconfigure the matrices and tool lists before saving.'
+        }
+    };
+    // Stored shape: Array<{ slug: string; actions: ('read'|'create'|'update'|'delete')[] }>
+    // The default Payload UI for an `array` would force users to add rows
+    // one at a time; the custom matrix component renders all available
+    // collections at once with a checkbox grid (rows × actions).
+    //
+    // `availableCollections` is forwarded via `clientProps` — Payload v3's
+    // sanctioned escape hatch for serializable static data that the client
+    // component needs at render time.
+    const collectionScopesField = {
+        name: 'collectionScopes',
+        type: 'json',
+        admin: {
+            condition: isCustomPreset,
+            components: {
+                Field: {
+                    path: 'payload-mcp-toolkit/client',
+                    exportName: 'CollectionScopesMatrix',
+                    clientProps: {
+                        availableCollections: options.availableCollections
+                    }
+                }
+            }
+        }
+    };
+    // Mirrors `collectionScopes` exactly — one additive JSONB column with a
+    // default of `'[]'`, default-rendered by `GlobalScopesMatrix`. Hidden
+    // under non-custom presets. Stored shape:
+    //   Array<{ slug: string; actions: ('read'|'update')[] }>
+    // No `availableGlobals.length > 0` gate: `ScopesTable` renders its own
+    // empty-state message when zero items are passed, so the field surfaces
+    // under Custom regardless of host config, matching the collection variant.
+    const globalScopesField = {
+        name: 'globalScopes',
+        type: 'json',
+        admin: {
+            condition: isCustomPreset,
+            components: {
+                Field: {
+                    path: 'payload-mcp-toolkit/client',
+                    exportName: 'GlobalScopesMatrix',
+                    clientProps: {
+                        availableGlobals
+                    }
+                }
+            }
+        }
+    };
+    const toolsCollapsible = {
+        type: 'collapsible',
+        label: 'Tool overrides',
+        admin: {
+            condition: isCustomPreset,
+            description: 'Per-tool whitelist / blacklist. Layered on top of preset and collection scopes.',
+            initCollapsed: true
+        },
+        fields: [
+            {
+                name: 'toolAllow',
+                type: 'select',
+                hasMany: true,
+                options: toolOptions,
+                admin: {
+                    description: 'If set, only these tools are callable with this key. Leave empty to allow any tool ' + 'the collection or global scopes permit. Under the Custom preset, an empty list is ' + 'treated as deny-all ONLY when no collection or global scopes are set (the fresh- ' + 'Custom-key sentinel); when collection or global scopes are populated, an empty list ' + 'collapses to "no tool restriction" so the resource scopes alone determine what is ' + 'callable — to deny every tool while keeping resource scopes, enumerate them in ' + 'toolDeny instead. Preset-mode keys created via the REST API with an empty list are ' + 'coerced to "no restriction".'
+                }
+            },
+            {
+                name: 'toolDeny',
+                type: 'select',
+                hasMany: true,
+                options: toolOptions,
+                admin: {
+                    description: 'These tools are blocked regardless of any other scope.'
+                }
+            }
+        ]
+    };
+    return {
+        slug,
+        admin: {
+            group: 'MCP',
+            useAsTitle: 'name',
+            description: 'API keys for MCP clients. Scopes control which collections and tools each key can access.',
+            defaultColumns: [
+                'name',
+                'user',
+                'keyPrefix',
+                'preset',
+                'lastUsedAt',
+                'expiresAt',
+                'revokedAt'
+            ]
+        },
+        auth: {
+            disableLocalStrategy: true,
+            useAPIKey: true
+        },
+        hooks: {
+            beforeValidate: [
+                ({ data, originalDoc })=>{
+                    // The override fields (collectionScopes, globalScopes, toolAllow,
+                    // toolDeny) are conditionally rendered only under the Custom preset
+                    // (`condition: isCustomPreset`). Under any other preset they are
+                    // hidden in the admin UI, which means two things:
+                    //
+                    //   1. The admin form omits hidden fields from its payload on save,
+                    //      so `data` only carries the visible fields — we can't
+                    //      "collapse the empty array we see in `data`" because we never
+                    //      see it at all. The stale value lives on `originalDoc`.
+                    //   2. A Custom→Admin switch silently keeps the prior
+                    //      `toolAllow:[...]` / `collectionScopes:[...]`, and
+                    //      `composeScopes` then emits a scope gate that rejects calls
+                    //      the user clearly intended to allow.
+                    //
+                    // Fix: when the preset is non-Custom, explicitly write `null` into
+                    // `data` for every override axis (regardless of what `data` carries
+                    // or what originalDoc holds). Payload persists nulls, so the stale
+                    // values are erased on every save. The Custom-preset branch below
+                    // keeps the explicit-empty-means-deny semantic intact.
+                    if (!data) return data;
+                    const d = data;
+                    const orig = originalDoc ?? {};
+                    const preset = d.preset ?? orig.preset;
+                    // `readField` falls through to originalDoc when `data` omits the
+                    // key entirely (admin form skipping hidden fields), but honours
+                    // an explicit null/empty in `data` over originalDoc.
+                    const readField = (key)=>key in d ? d[key] : orig[key];
+                    const isNonEmptyArray = (v)=>Array.isArray(v) && v.length > 0;
+                    const isEmptyArray = (v)=>Array.isArray(v) && v.length === 0;
+                    const OVERRIDE_AXES = [
+                        'collectionScopes',
+                        'globalScopes',
+                        'toolAllow',
+                        'toolDeny'
+                    ];
+                    if (preset !== 'custom') {
+                        for (const axis of OVERRIDE_AXES)d[axis] = null;
+                        return data;
+                    }
+                    // Custom preset: the Tools collapsible is labelled as an *override*
+                    // layered on top of collection / global scopes, and its description
+                    // says "Leave empty to allow any tool the collection scopes permit."
+                    // Payload's hasMany-select default of `[]` would otherwise turn the
+                    // Tools section into a mandatory whitelist — a user who configures
+                    // collection scopes and never opens the collapsible would silently
+                    // store `toolAllow:[]`, which `composeScopes` honours as deny-all on
+                    // the tools axis and rejects every call.
+                    //
+                    // Resolve the mismatch by coercing an empty `toolAllow` to null
+                    // whenever the key carries any concrete resource scope (collection
+                    // or global entries). The fresh-Custom-key sentinel in
+                    // `composeScopes` still covers the "no scopes at all" case
+                    // (everything null → deny-all), so users who genuinely want
+                    // deny-all do not regress.
+                    const hasResourceScope = isNonEmptyArray(readField('collectionScopes')) || isNonEmptyArray(readField('globalScopes'));
+                    if (hasResourceScope && isEmptyArray(readField('toolAllow'))) {
+                        d.toolAllow = null;
+                    }
+                    return data;
+                }
+            ]
+        },
+        labels: {
+            plural: 'API Keys',
+            singular: 'API Key'
+        },
+        fields: [
+            // Main column.
+            {
+                name: 'name',
+                type: 'text',
+                required: true,
+                admin: {
+                    description: 'Human label for this key (e.g. "Editorial team — Claude Desktop").'
+                }
+            },
+            {
+                name: 'description',
+                type: 'textarea',
+                admin: {
+                    description: 'Optional notes about the purpose of this key.'
+                }
+            },
+            presetField,
+            collectionScopesField,
+            globalScopesField,
+            toolsCollapsible,
+            // Sidebar — identity + lifecycle.
+            {
+                name: 'user',
+                type: 'relationship',
+                relationTo: options.userCollection,
+                required: true,
+                admin: {
+                    position: 'sidebar',
+                    description: 'The user this key authenticates as. Tool calls use this user for access checks on target collections.'
+                }
+            },
+            {
+                name: 'keyPrefix',
+                type: 'text',
+                index: true,
+                admin: {
+                    position: 'sidebar',
+                    readOnly: true,
+                    description: 'First 8 characters of the API key — used in audit logs to identify the key without exposing the full secret.'
+                },
+                hooks: {
+                    beforeChange: [
+                        ({ data, originalDoc, value })=>{
+                            if (typeof value === 'string' && value.length > 0) return value;
+                            const incomingKey = data?.apiKey;
+                            if (typeof incomingKey === 'string' && incomingKey.length >= 8) {
+                                return incomingKey.slice(0, 8);
+                            }
+                            const existing = originalDoc?.keyPrefix;
+                            return typeof existing === 'string' ? existing : undefined;
+                        }
+                    ]
+                }
+            },
+            {
+                name: 'expiresAt',
+                type: 'date',
+                admin: {
+                    position: 'sidebar',
+                    description: 'Optional expiry. Requests authenticated with an expired key are rejected.'
+                }
+            },
+            {
+                name: 'revokedAt',
+                type: 'date',
+                admin: {
+                    position: 'sidebar',
+                    description: 'Set to revoke a key. Revoked keys are rejected at auth time.'
+                }
+            },
+            {
+                name: 'lastUsedAt',
+                type: 'date',
+                admin: {
+                    position: 'sidebar',
+                    readOnly: true,
+                    description: 'Updated on each successful authentication. Fire-and-forget; not on the request hot path.'
+                }
+            }
+        ]
+    };
+}
+
+//# sourceMappingURL=api-keys.js.map

package/dist/api-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api-keys.ts"],"sourcesContent":["import type { CollectionBeforeValidateHook, CollectionConfig, Field } from 'payload'\r\n\r\nexport const API_KEYS_DEFAULT_SLUG = 'payload-mcp-api-keys'\r\n\r\nexport interface CreateApiKeysCollectionOptions {\r\n  /**\r\n   * Collection slug. Defaults to `payload-mcp-api-keys` for zero-touch\r\n   * compatibility with rows created by `@payloadcms/plugin-mcp` v0.3.x.\r\n   */\r\n  slug?: string\r\n  /**\r\n   * Slug of the user collection that API keys link to. Required.\r\n   */\r\n  userCollection: string\r\n  /**\r\n   * Collection slugs offered to the collection-scopes matrix component.\r\n   * Snapshotted at plugin-init time from the host Payload config; adding a\r\n   * collection requires a dev-server restart for it to surface in the\r\n   * admin UI.\r\n   */\r\n  availableCollections: string[]\r\n  /**\r\n   * Tool names offered as options for the `toolAllow` / `toolDeny` selects.\r\n   * Sourced from the toolkit's registered tools at plugin init.\r\n   */\r\n  availableTools: string[]\r\n  /**\r\n   * Global slugs offered to the global-scopes matrix component. Optional —\r\n   * direct callers of the factory that pre-date globals support continue\r\n   * to work; sites with no globals get an empty array and the second\r\n   * matrix table is not rendered.\r\n   */\r\n  availableGlobals?: string[]\r\n}\r\n\r\nconst PRESET_OPTIONS = [\r\n  { label: 'Read-only', value: 'read-only' },\r\n  { label: 'Editor (read + create + update)', value: 'editor' },\r\n  { label: 'Admin (all actions)', value: 'admin' },\r\n  { label: 'Custom (use overrides below)', value: 'custom' },\r\n] as const\r\n\r\nconst isCustomPreset = (data: unknown): boolean =>\r\n  !!data && typeof data === 'object' && (data as { preset?: unknown }).preset === 'custom'\r\n\r\n/**\r\n * Builds the `payload-mcp-api-keys` collection used by the v0.4 standalone\r\n * plugin. Reuses Payload's built-in `useAPIKey: true` so the underlying\r\n * `apiKey` / `apiKeyIndex` columns match what `@payloadcms/plugin-mcp`\r\n * v0.3.x wrote — existing rows authenticate without re-issue.\r\n *\r\n * Layout:\r\n *   - Main column: name, description, preset, scopes matrix (custom only),\r\n *     tools collapsible (custom only).\r\n *   - Sidebar: user relationship, key prefix, expiresAt, revokedAt,\r\n *     lastUsedAt — identity + lifecycle metadata kept out of the\r\n *     scope-editing flow.\r\n */\r\nexport function createApiKeysCollection(\r\n  options: CreateApiKeysCollectionOptions,\r\n): CollectionConfig {\r\n  if (!options || !options.userCollection) {\r\n    throw new Error(\r\n      'createApiKeysCollection: `userCollection` is required (slug of the user collection that owns API keys).',\r\n    )\r\n  }\r\n  if (!Array.isArray(options.availableCollections)) {\r\n    throw new Error(\r\n      'createApiKeysCollection: `availableCollections` is required (slugs of collections that scope overrides may target).',\r\n    )\r\n  }\r\n  if (!Array.isArray(options.availableTools)) {\r\n    throw new Error(\r\n      'createApiKeysCollection: `availableTools` is required (names of registered MCP tools).',\r\n    )\r\n  }\r\n\r\n  const slug = options.slug ?? API_KEYS_DEFAULT_SLUG\r\n  const toolOptions = options.availableTools.map((t) => ({ label: t, value: t }))\r\n  const availableGlobals = Array.isArray(options.availableGlobals)\r\n    ? options.availableGlobals\r\n    : []\r\n\r\n  const presetField: Field = {\r\n    name: 'preset',\r\n    type: 'select',\r\n    required: true,\r\n    defaultValue: 'custom',\r\n    options: PRESET_OPTIONS as unknown as { label: string; value: string }[],\r\n    admin: {\r\n      description:\r\n        'Role preset. \"Custom\" unlocks the per-collection matrix and the tool overrides below. ' +\r\n        'Switching away from Custom CLEARS every override on save (collectionScopes, globalScopes, ' +\r\n        'toolAllow, toolDeny); switching back to Custom starts from a fresh deny-all baseline, so ' +\r\n        'reconfigure the matrices and tool lists before saving.',\r\n    },\r\n  }\r\n\r\n  // Stored shape: Array<{ slug: string; actions: ('read'|'create'|'update'|'delete')[] }>\r\n  // The default Payload UI for an `array` would force users to add rows\r\n  // one at a time; the custom matrix component renders all available\r\n  // collections at once with a checkbox grid (rows × actions).\r\n  //\r\n  // `availableCollections` is forwarded via `clientProps` — Payload v3's\r\n  // sanctioned escape hatch for serializable static data that the client\r\n  // component needs at render time.\r\n  const collectionScopesField: Field = {\r\n    name: 'collectionScopes',\r\n    type: 'json',\r\n    admin: {\r\n      condition: isCustomPreset,\r\n      components: {\r\n        Field: {\r\n          path: 'payload-mcp-toolkit/client',\r\n          exportName: 'CollectionScopesMatrix',\r\n          clientProps: {\r\n            availableCollections: options.availableCollections,\r\n          },\r\n        },\r\n      },\r\n    },\r\n  }\r\n\r\n  // Mirrors `collectionScopes` exactly — one additive JSONB column with a\r\n  // default of `'[]'`, default-rendered by `GlobalScopesMatrix`. Hidden\r\n  // under non-custom presets. Stored shape:\r\n  //   Array<{ slug: string; actions: ('read'|'update')[] }>\r\n  // No `availableGlobals.length > 0` gate: `ScopesTable` renders its own\r\n  // empty-state message when zero items are passed, so the field surfaces\r\n  // under Custom regardless of host config, matching the collection variant.\r\n  const globalScopesField: Field = {\r\n    name: 'globalScopes',\r\n    type: 'json',\r\n    admin: {\r\n      condition: isCustomPreset,\r\n      components: {\r\n        Field: {\r\n          path: 'payload-mcp-toolkit/client',\r\n          exportName: 'GlobalScopesMatrix',\r\n          clientProps: {\r\n            availableGlobals,\r\n          },\r\n        },\r\n      },\r\n    },\r\n  }\r\n\r\n  const toolsCollapsible: Field = {\r\n    type: 'collapsible',\r\n    label: 'Tool overrides',\r\n    admin: {\r\n      condition: isCustomPreset,\r\n      description:\r\n        'Per-tool whitelist / blacklist. Layered on top of preset and collection scopes.',\r\n      initCollapsed: true,\r\n    },\r\n    fields: [\r\n      {\r\n        name: 'toolAllow',\r\n        type: 'select',\r\n        hasMany: true,\r\n        options: toolOptions,\r\n        admin: {\r\n          description:\r\n            'If set, only these tools are callable with this key. Leave empty to allow any tool ' +\r\n            'the collection or global scopes permit. Under the Custom preset, an empty list is ' +\r\n            'treated as deny-all ONLY when no collection or global scopes are set (the fresh- ' +\r\n            'Custom-key sentinel); when collection or global scopes are populated, an empty list ' +\r\n            'collapses to \"no tool restriction\" so the resource scopes alone determine what is ' +\r\n            'callable — to deny every tool while keeping resource scopes, enumerate them in ' +\r\n            'toolDeny instead. Preset-mode keys created via the REST API with an empty list are ' +\r\n            'coerced to \"no restriction\".',\r\n        },\r\n      },\r\n      {\r\n        name: 'toolDeny',\r\n        type: 'select',\r\n        hasMany: true,\r\n        options: toolOptions,\r\n        admin: {\r\n          description: 'These tools are blocked regardless of any other scope.',\r\n        },\r\n      },\r\n    ],\r\n  }\r\n\r\n  return {\r\n    slug,\r\n    admin: {\r\n      group: 'MCP',\r\n      useAsTitle: 'name',\r\n      description:\r\n        'API keys for MCP clients. Scopes control which collections and tools each key can access.',\r\n      defaultColumns: ['name', 'user', 'keyPrefix', 'preset', 'lastUsedAt', 'expiresAt', 'revokedAt'],\r\n    },\r\n    auth: {\r\n      disableLocalStrategy: true,\r\n      useAPIKey: true,\r\n    },\r\n    hooks: {\r\n      beforeValidate: [\r\n        (({ data, originalDoc }) => {\r\n          // The override fields (collectionScopes, globalScopes, toolAllow,\r\n          // toolDeny) are conditionally rendered only under the Custom preset\r\n          // (`condition: isCustomPreset`). Under any other preset they are\r\n          // hidden in the admin UI, which means two things:\r\n          //\r\n          //   1. The admin form omits hidden fields from its payload on save,\r\n          //      so `data` only carries the visible fields — we can't\r\n          //      \"collapse the empty array we see in `data`\" because we never\r\n          //      see it at all. The stale value lives on `originalDoc`.\r\n          //   2. A Custom→Admin switch silently keeps the prior\r\n          //      `toolAllow:[...]` / `collectionScopes:[...]`, and\r\n          //      `composeScopes` then emits a scope gate that rejects calls\r\n          //      the user clearly intended to allow.\r\n          //\r\n          // Fix: when the preset is non-Custom, explicitly write `null` into\r\n          // `data` for every override axis (regardless of what `data` carries\r\n          // or what originalDoc holds). Payload persists nulls, so the stale\r\n          // values are erased on every save. The Custom-preset branch below\r\n          // keeps the explicit-empty-means-deny semantic intact.\r\n          if (!data) return data\r\n          const d = data as Record<string, unknown>\r\n          const orig = (originalDoc ?? {}) as Record<string, unknown>\r\n          const preset = d.preset ?? orig.preset\r\n\r\n          // `readField` falls through to originalDoc when `data` omits the\r\n          // key entirely (admin form skipping hidden fields), but honours\r\n          // an explicit null/empty in `data` over originalDoc.\r\n          const readField = (key: string): unknown =>\r\n            key in d ? d[key] : orig[key]\r\n          const isNonEmptyArray = (v: unknown): boolean =>\r\n            Array.isArray(v) && v.length > 0\r\n          const isEmptyArray = (v: unknown): boolean =>\r\n            Array.isArray(v) && v.length === 0\r\n\r\n          const OVERRIDE_AXES = [\r\n            'collectionScopes',\r\n            'globalScopes',\r\n            'toolAllow',\r\n            'toolDeny',\r\n          ] as const\r\n\r\n          if (preset !== 'custom') {\r\n            for (const axis of OVERRIDE_AXES) d[axis] = null\r\n            return data\r\n          }\r\n\r\n          // Custom preset: the Tools collapsible is labelled as an *override*\r\n          // layered on top of collection / global scopes, and its description\r\n          // says \"Leave empty to allow any tool the collection scopes permit.\"\r\n          // Payload's hasMany-select default of `[]` would otherwise turn the\r\n          // Tools section into a mandatory whitelist — a user who configures\r\n          // collection scopes and never opens the collapsible would silently\r\n          // store `toolAllow:[]`, which `composeScopes` honours as deny-all on\r\n          // the tools axis and rejects every call.\r\n          //\r\n          // Resolve the mismatch by coercing an empty `toolAllow` to null\r\n          // whenever the key carries any concrete resource scope (collection\r\n          // or global entries). The fresh-Custom-key sentinel in\r\n          // `composeScopes` still covers the \"no scopes at all\" case\r\n          // (everything null → deny-all), so users who genuinely want\r\n          // deny-all do not regress.\r\n          const hasResourceScope =\r\n            isNonEmptyArray(readField('collectionScopes')) ||\r\n            isNonEmptyArray(readField('globalScopes'))\r\n          if (hasResourceScope && isEmptyArray(readField('toolAllow'))) {\r\n            d.toolAllow = null\r\n          }\r\n          return data\r\n        }) as CollectionBeforeValidateHook,\r\n      ],\r\n    },\r\n    labels: {\r\n      plural: 'API Keys',\r\n      singular: 'API Key',\r\n    },\r\n    fields: [\r\n      // Main column.\r\n      {\r\n        name: 'name',\r\n        type: 'text',\r\n        required: true,\r\n        admin: { description: 'Human label for this key (e.g. \"Editorial team — Claude Desktop\").' },\r\n      },\r\n      {\r\n        name: 'description',\r\n        type: 'textarea',\r\n        admin: { description: 'Optional notes about the purpose of this key.' },\r\n      },\r\n      presetField,\r\n      collectionScopesField,\r\n      globalScopesField,\r\n      toolsCollapsible,\r\n\r\n      // Sidebar — identity + lifecycle.\r\n      {\r\n        name: 'user',\r\n        type: 'relationship',\r\n        relationTo: options.userCollection,\r\n        required: true,\r\n        admin: {\r\n          position: 'sidebar',\r\n          description:\r\n            'The user this key authenticates as. Tool calls use this user for access checks on target collections.',\r\n        },\r\n      },\r\n      {\r\n        name: 'keyPrefix',\r\n        type: 'text',\r\n        index: true,\r\n        admin: {\r\n          position: 'sidebar',\r\n          readOnly: true,\r\n          description:\r\n            'First 8 characters of the API key — used in audit logs to identify the key without exposing the full secret.',\r\n        },\r\n        hooks: {\r\n          beforeChange: [\r\n            ({ data, originalDoc, value }) => {\r\n              if (typeof value === 'string' && value.length > 0) return value\r\n              const incomingKey = (data as { apiKey?: unknown } | undefined)?.apiKey\r\n              if (typeof incomingKey === 'string' && incomingKey.length >= 8) {\r\n                return incomingKey.slice(0, 8)\r\n              }\r\n              const existing = (originalDoc as { keyPrefix?: unknown } | undefined)?.keyPrefix\r\n              return typeof existing === 'string' ? existing : undefined\r\n            },\r\n          ],\r\n        },\r\n      },\r\n      {\r\n        name: 'expiresAt',\r\n        type: 'date',\r\n        admin: {\r\n          position: 'sidebar',\r\n          description: 'Optional expiry. Requests authenticated with an expired key are rejected.',\r\n        },\r\n      },\r\n      {\r\n        name: 'revokedAt',\r\n        type: 'date',\r\n        admin: {\r\n          position: 'sidebar',\r\n          description: 'Set to revoke a key. Revoked keys are rejected at auth time.',\r\n        },\r\n      },\r\n      {\r\n        name: 'lastUsedAt',\r\n        type: 'date',\r\n        admin: {\r\n          position: 'sidebar',\r\n          readOnly: true,\r\n          description:\r\n            'Updated on each successful authentication. Fire-and-forget; not on the request hot path.',\r\n        },\r\n      },\r\n    ],\r\n  }\r\n}\r\n"],"names":["API_KEYS_DEFAULT_SLUG","PRESET_OPTIONS","label","value","isCustomPreset","data","preset","createApiKeysCollection","options","userCollection","Error","Array","isArray","availableCollections","availableTools","slug","toolOptions","map","t","availableGlobals","presetField","name","type","required","defaultValue","admin","description","collectionScopesField","condition","components","Field","path","exportName","clientProps","globalScopesField","toolsCollapsible","initCollapsed","fields","hasMany","group","useAsTitle","defaultColumns","auth","disableLocalStrategy","useAPIKey","hooks","beforeValidate","originalDoc","d","orig","readField","key","isNonEmptyArray","v","length","isEmptyArray","OVERRIDE_AXES","axis","hasResourceScope","toolAllow","labels","plural","singular","relationTo","position","index","readOnly","beforeChange","incomingKey","apiKey","slice","existing","keyPrefix","undefined"],"mappings":"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"}

package/dist/auth-strategy.d.ts

@@ -0,0 +1,96 @@
+import type { AuthStrategy, PayloadRequest } from 'payload';
+import type { KeyScopes, ScopePreset } from './types';
+export type { CollectionAction, GlobalAction, KeyScopes, ScopePreset } from './types';
+export declare const AUTH_STRATEGY_NAME = "mcp-toolkit-bearer";
+export interface CreateBearerStrategyOptions {
+    /** Slug of the API-keys collection (defaults to `payload-mcp-api-keys`). */
+    collectionSlug: string;
+    /** Slug of the user collection that API keys link to. */
+    userCollection: string;
+}
+/**
+ * Stored shape for a row in `collectionScopes` / `globalScopes` (v0.6+).
+ * The parent field name encodes the axis — collection-vs-global is not
+ * repeated in the row payload. Legacy `collection` / `global` keys from
+ * pre-0.6 rows are tolerated by `composeScopes` for one release; v0.7
+ * drops the fallback (see CHANGELOG).
+ */
+interface ScopeRow {
+    slug?: unknown;
+    /** @deprecated pre-0.6 collectionScopes shape — read via fallback only. */
+    collection?: unknown;
+    /** @deprecated pre-0.6 globalScopes shape — read via fallback only. */
+    global?: unknown;
+    actions?: unknown;
+}
+interface ApiKeyRow {
+    id: string | number;
+    user: unknown;
+    preset?: ScopePreset | 'custom' | null;
+    collectionScopes?: ScopeRow[] | null;
+    globalScopes?: ScopeRow[] | null;
+    toolAllow?: string[] | null;
+    toolDeny?: string[] | null;
+    expiresAt?: string | Date | null;
+    revokedAt?: string | Date | null;
+    apiKey?: string | null;
+    keyPrefix?: string | null;
+}
+/** @internal test-only: reset the one-time legacy warns. */
+export declare function _resetLegacyWarnsForTests(): void;
+/**
+ * Builds the runtime `KeyScopes` shape consumed by `registry.assertScopeAllows`
+ * from the typed scope fields on the api-key row.
+ *
+ * Returns null when no typed fields are populated AND no preset is set
+ * (= full access — back-compat for pre-0.5 rows that pre-date scoped authz).
+ *
+ * Two complementary fail-closed rules:
+ *
+ * 1. **`'custom'` deny-all sentinel.** `'custom'` is a UI sentinel meaning
+ *    "use my override fields"; it never becomes `KeyScopes.preset` itself.
+ *    Payload persists unset JSON / select fields as `null`, so a fresh
+ *    Custom key with no overrides arrives as `{preset:'custom',
+ *    collectionScopes:null, globalScopes:null, toolAllow:null,
+ *    toolDeny:null}`. That row must deny everything (not fall through to
+ *    full access). The sentinel emits `{collections:{}, globals:{},
+ *    tools:{allow:[]}}`.
+ *
+ * 2. **Per-axis explicit-empty, Custom-only.** Under the Custom preset, an
+ *    empty array on any axis (even `[]`) is honoured as written — an empty
+ *    `toolAllow:[]` means "deny all tools on this axis", not "no opinion".
+ *    Under non-Custom presets, empty arrays are IGNORED because Payload's
+ *    hasMany / unpopulated-JSON reads return `[]` for fields the user
+ *    never touched (the override matrices are hidden in the admin UI under
+ *    non-Custom presets via `condition: isCustomPreset`). The on-write
+ *    counterpart of this rule lives in `createApiKeysCollection`'s
+ *    `beforeValidate` hook, which proactively nulls the override axes on
+ *    save when the preset is non-Custom — both layers must stay in sync.
+ *    Non-empty arrays still apply as layered narrowing under any preset.
+ *    `toolDeny` is a deny-list, so an empty array carries no entries — it
+ *    is dropped rather than emitted. NOTE: legacy non-Custom rows persisted
+ *    BEFORE v0.7.1 with populated stale override arrays continue to narrow
+ *    on read until each row is manually re-saved; the on-write fix only
+ *    applies to fresh writes.
+ */
+export declare function composeScopes(row: ApiKeyRow, logger?: {
+    warn?: (...args: unknown[]) => void;
+}): KeyScopes | null;
+/**
+ * Builds the Payload `auth.strategies` entry that authenticates MCP requests.
+ *
+ * Authenticates `Authorization: Bearer <plaintext>` by computing the
+ * upstream-compatible `apiKeyIndex` HMAC and looking up the row. On match,
+ * it fires a non-blocking `lastUsedAt` write and hydrates `req.user` with
+ * the linked user record + key context for downstream scope checks.
+ */
+export declare function createBearerStrategy(options: CreateBearerStrategyOptions): AuthStrategy;
+/**
+ * Reads the per-request API-key context populated by the bearer strategy.
+ * Returns null for non-MCP requests (e.g. cookie-authenticated admin users).
+ */
+export declare function getApiKeyContext(req: PayloadRequest): {
+    keyId: string | number;
+    keyPrefix: string | null;
+    scopes: KeyScopes | null;
+} | null;