payload-mcp-toolkit 0.3.4 → 0.7.0

package/dist/api-keys.js

@@ -0,0 +1,272 @@
+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.'
+        }
+    };
+    // 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 scopes permit. Under the Custom preset, an explicit empty list is treated as deny-all on this axis; 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 })=>{
+                    // REST clients that create a key with a preset (e.g. admin) but
+                    // omit toolAllow / toolDeny would hit Payload's hasMany-select
+                    // default of `[]`, which composeScopes correctly interprets as
+                    // "deny-all on this axis" (v0.6 Track A). That is the right
+                    // semantic for explicit-Custom configurations but a UX trap for
+                    // preset-mode keys created via the REST API. Collapse empty
+                    // arrays to null when the key is NOT on the Custom preset, so
+                    // preset-driven access flows through unimpeded. Custom-preset
+                    // keys keep the explicit-empty-means-deny semantic intact.
+                    if (!data) return data;
+                    const preset = data.preset;
+                    if (preset === 'custom') return data;
+                    for (const axis of [
+                        'toolAllow',
+                        'toolDeny'
+                    ]){
+                        const v = data[axis];
+                        if (Array.isArray(v) && v.length === 0) {
+                            ;
+                            data[axis] = 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 { 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    },\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 the collection scopes permit. Under the Custom preset, an explicit empty list is treated as deny-all on this axis; preset-mode keys created via the REST API with an empty list are 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 }) => {\r\n          // REST clients that create a key with a preset (e.g. admin) but\r\n          // omit toolAllow / toolDeny would hit Payload's hasMany-select\r\n          // default of `[]`, which composeScopes correctly interprets as\r\n          // \"deny-all on this axis\" (v0.6 Track A). That is the right\r\n          // semantic for explicit-Custom configurations but a UX trap for\r\n          // preset-mode keys created via the REST API. Collapse empty\r\n          // arrays to null when the key is NOT on the Custom preset, so\r\n          // preset-driven access flows through unimpeded. Custom-preset\r\n          // keys keep the explicit-empty-means-deny semantic intact.\r\n          if (!data) return data\r\n          const preset = (data as { preset?: unknown }).preset\r\n          if (preset === 'custom') return data\r\n          for (const axis of ['toolAllow', 'toolDeny'] as const) {\r\n            const v = (data as Record<string, unknown>)[axis]\r\n            if (Array.isArray(v) && v.length === 0) {\r\n              ;(data as Record<string, unknown>)[axis] = null\r\n            }\r\n          }\r\n          return data\r\n        },\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","axis","v","length","labels","plural","singular","relationTo","position","index","readOnly","beforeChange","originalDoc","incomingKey","apiKey","slice","existing","keyPrefix","undefined"],"mappings":"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"}

package/dist/auth-strategy.d.ts

@@ -0,0 +1,85 @@
+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;
+}
+/**
+ * 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.** When a row carries an array value on any
+ *    axis (even `[]`), that axis is honoured as written — an empty
+ *    `toolAllow:[]` means "deny all tools", not "no opinion". This closes a
+ *    gap where a Custom key with `collectionScopes` populated AND
+ *    `toolAllow:[]` previously emitted no `tools.allow` gate (the empty
+ *    array was treated as absent). `toolDeny` is a deny-list, so an empty
+ *    array carries no entries — it is dropped rather than emitted.
+ */
+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;

package/dist/auth-strategy.js

@@ -0,0 +1,219 @@
+import { extractBearerToken, hashKey } from './hash';
+export const AUTH_STRATEGY_NAME = 'mcp-toolkit-bearer';
+/**
+ * Reads the row's slug, tolerating the pre-0.6 `collection` / `global`
+ * keys for one release. Logs a one-line warn when the legacy fallback
+ * fires so operators can spot keys that need re-saving. The fallback is
+ * scheduled for removal in v0.7.
+ */ let warnedLegacyShape = false;
+function readScopeSlug(entry, legacyKey, logger) {
+    if (typeof entry?.slug === 'string') return entry.slug;
+    const legacy = entry?.[legacyKey];
+    if (typeof legacy === 'string') {
+        if (!warnedLegacyShape) {
+            warnedLegacyShape = true;
+            logger?.warn?.({
+                event: 'mcp.auth.legacy_scope_shape',
+                legacyKey
+            }, `[payload-mcp-toolkit] composeScopes read a pre-0.6 row using \`${legacyKey}\`; resave the API key to migrate to {slug, actions}. The fallback is removed in v0.7.`);
+        }
+        return legacy;
+    }
+    return null;
+}
+const VALID_ACTIONS = new Set([
+    'read',
+    'create',
+    'update',
+    'delete'
+]);
+const VALID_GLOBAL_ACTIONS = new Set([
+    'read',
+    'update'
+]);
+/**
+ * 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.** When a row carries an array value on any
+ *    axis (even `[]`), that axis is honoured as written — an empty
+ *    `toolAllow:[]` means "deny all tools", not "no opinion". This closes a
+ *    gap where a Custom key with `collectionScopes` populated AND
+ *    `toolAllow:[]` previously emitted no `tools.allow` gate (the empty
+ *    array was treated as absent). `toolDeny` is a deny-list, so an empty
+ *    array carries no entries — it is dropped rather than emitted.
+ */ export function composeScopes(row, logger) {
+    const presetRaw = row.preset;
+    const hasPreset = typeof presetRaw === 'string' && presetRaw.length > 0;
+    const hasCollectionScopesField = Array.isArray(row.collectionScopes);
+    const hasGlobalScopesField = Array.isArray(row.globalScopes);
+    const hasToolAllowField = Array.isArray(row.toolAllow);
+    const hasToolDenyField = Array.isArray(row.toolDeny);
+    // Pre-0.5 back-compat: row has no preset and no typed scope fields at
+    // all (all null/undefined). Treat as full access.
+    if (!hasPreset && !hasCollectionScopesField && !hasGlobalScopesField && !hasToolAllowField && !hasToolDenyField) {
+        return null;
+    }
+    // Sentinel: Custom preset with every axis null/undefined (no array
+    // committed) denies everything. Payload-persisted unset JSON / select
+    // fields arrive as null; this is the fresh-Custom-key case.
+    if (presetRaw === 'custom' && !hasCollectionScopesField && !hasGlobalScopesField && !hasToolAllowField && !hasToolDenyField) {
+        return {
+            collections: {},
+            globals: {},
+            tools: {
+                allow: []
+            }
+        };
+    }
+    const out = {};
+    if (hasPreset && presetRaw !== 'custom') {
+        out.preset = presetRaw;
+    }
+    if (hasCollectionScopesField) {
+        const collections = {};
+        for (const entry of row.collectionScopes){
+            const slug = readScopeSlug(entry, 'collection', logger);
+            if (!slug) continue;
+            const rawActions = Array.isArray(entry?.actions) ? entry.actions : [];
+            const actions = rawActions.filter((a)=>typeof a === 'string' && VALID_ACTIONS.has(a));
+            collections[slug] = actions;
+        }
+        out.collections = collections;
+    }
+    if (hasGlobalScopesField) {
+        const globals = {};
+        for (const entry of row.globalScopes){
+            const slug = readScopeSlug(entry, 'global', logger);
+            if (!slug) continue;
+            const rawActions = Array.isArray(entry?.actions) ? entry.actions : [];
+            const actions = rawActions.filter((a)=>typeof a === 'string' && VALID_GLOBAL_ACTIONS.has(a));
+            globals[slug] = actions;
+        }
+        out.globals = globals;
+    }
+    const toolDeny = hasToolDenyField ? row.toolDeny.filter((t)=>typeof t === 'string') : [];
+    const emitDeny = toolDeny.length > 0;
+    if (hasToolAllowField || emitDeny) {
+        out.tools = {};
+        if (hasToolAllowField) {
+            const toolAllow = row.toolAllow.filter((t)=>typeof t === 'string');
+            out.tools.allow = toolAllow;
+        }
+        if (emitDeny) out.tools.deny = toolDeny;
+    }
+    return out;
+}
+/**
+ * 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 function createBearerStrategy(options) {
+    const { collectionSlug, userCollection } = options;
+    return {
+        name: AUTH_STRATEGY_NAME,
+        authenticate: async ({ headers, payload })=>{
+            const headersAny = headers;
+            const headerValue = typeof headersAny.get === 'function' ? headersAny.get('authorization') : headersAny.authorization;
+            const token = extractBearerToken(headerValue ?? null);
+            if (!token) return {
+                user: null
+            };
+            const keyHash = hashKey(token, payload.secret);
+            const where = {
+                apiKeyIndex: {
+                    equals: keyHash
+                }
+            };
+            let docs = [];
+            try {
+                const result = await payload.find({
+                    collection: collectionSlug,
+                    where,
+                    depth: 1,
+                    limit: 1,
+                    pagination: false,
+                    overrideAccess: true
+                });
+                docs = result.docs ?? [];
+            } catch (err) {
+                payload.logger.error({
+                    err,
+                    event: 'mcp.auth.lookup_failed'
+                }, '[payload-mcp-toolkit] API-key lookup failed');
+                return {
+                    user: null
+                };
+            }
+            const row = docs[0];
+            if (!row) return {
+                user: null
+            };
+            const now = Date.now();
+            if (row.revokedAt) return {
+                user: null
+            };
+            if (row.expiresAt) {
+                const expiry = new Date(row.expiresAt).getTime();
+                if (Number.isFinite(expiry) && expiry < now) return {
+                    user: null
+                };
+            }
+            const linkedUser = row.user;
+            if (!linkedUser || typeof linkedUser !== 'object') return {
+                user: null
+            };
+            const effectiveScopes = composeScopes(row, payload.logger);
+            // Fire-and-forget: do not block the request on this write.
+            void payload.update({
+                collection: collectionSlug,
+                id: row.id,
+                data: {
+                    lastUsedAt: new Date().toISOString()
+                },
+                overrideAccess: true
+            }).catch(()=>{
+            // Intentionally swallow: lastUsedAt drift is acceptable.
+            });
+            const user = linkedUser;
+            return {
+                user: {
+                    ...user,
+                    collection: userCollection,
+                    _strategy: AUTH_STRATEGY_NAME,
+                    _mcpKey: {
+                        keyId: row.id,
+                        keyPrefix: typeof row.keyPrefix === 'string' ? row.keyPrefix : null,
+                        scopes: effectiveScopes
+                    }
+                }
+            };
+        }
+    };
+}
+/**
+ * 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 function getApiKeyContext(req) {
+    const user = req.user;
+    return user?._mcpKey ?? null;
+}
+
+//# sourceMappingURL=auth-strategy.js.map

package/dist/auth-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/auth-strategy.ts"],"sourcesContent":["import type { AuthStrategy, PayloadRequest, Where } from 'payload'\r\nimport { extractBearerToken, hashKey } from './hash'\r\nimport type { CollectionAction, GlobalAction, KeyScopes, ScopePreset } from './types'\r\n\r\nexport type { CollectionAction, GlobalAction, KeyScopes, ScopePreset } from './types'\r\n\r\nexport const AUTH_STRATEGY_NAME = 'mcp-toolkit-bearer'\r\n\r\nexport interface CreateBearerStrategyOptions {\r\n  /** Slug of the API-keys collection (defaults to `payload-mcp-api-keys`). */\r\n  collectionSlug: string\r\n  /** Slug of the user collection that API keys link to. */\r\n  userCollection: string\r\n}\r\n\r\n/**\r\n * Stored shape for a row in `collectionScopes` / `globalScopes` (v0.6+).\r\n * The parent field name encodes the axis — collection-vs-global is not\r\n * repeated in the row payload. Legacy `collection` / `global` keys from\r\n * pre-0.6 rows are tolerated by `composeScopes` for one release; v0.7\r\n * drops the fallback (see CHANGELOG).\r\n */\r\ninterface ScopeRow {\r\n  slug?: unknown\r\n  /** @deprecated pre-0.6 collectionScopes shape — read via fallback only. */\r\n  collection?: unknown\r\n  /** @deprecated pre-0.6 globalScopes shape — read via fallback only. */\r\n  global?: unknown\r\n  actions?: unknown\r\n}\r\n\r\ninterface ApiKeyRow {\r\n  id: string | number\r\n  user: unknown\r\n  preset?: ScopePreset | 'custom' | null\r\n  collectionScopes?: ScopeRow[] | null\r\n  globalScopes?: ScopeRow[] | null\r\n  toolAllow?: string[] | null\r\n  toolDeny?: string[] | null\r\n  expiresAt?: string | Date | null\r\n  revokedAt?: string | Date | null\r\n  apiKey?: string | null\r\n  keyPrefix?: string | null\r\n}\r\n\r\n/**\r\n * Reads the row's slug, tolerating the pre-0.6 `collection` / `global`\r\n * keys for one release. Logs a one-line warn when the legacy fallback\r\n * fires so operators can spot keys that need re-saving. The fallback is\r\n * scheduled for removal in v0.7.\r\n */\r\nlet warnedLegacyShape = false\r\nfunction readScopeSlug(\r\n  entry: ScopeRow,\r\n  legacyKey: 'collection' | 'global',\r\n  logger?: { warn?: (...args: unknown[]) => void } | undefined,\r\n): string | null {\r\n  if (typeof entry?.slug === 'string') return entry.slug\r\n  const legacy = entry?.[legacyKey]\r\n  if (typeof legacy === 'string') {\r\n    if (!warnedLegacyShape) {\r\n      warnedLegacyShape = true\r\n      logger?.warn?.(\r\n        { event: 'mcp.auth.legacy_scope_shape', legacyKey },\r\n        `[payload-mcp-toolkit] composeScopes read a pre-0.6 row using \\`${legacyKey}\\`; resave the API key to migrate to {slug, actions}. The fallback is removed in v0.7.`,\r\n      )\r\n    }\r\n    return legacy\r\n  }\r\n  return null\r\n}\r\n\r\nconst VALID_ACTIONS: ReadonlySet<CollectionAction> = new Set(['read', 'create', 'update', 'delete'])\r\nconst VALID_GLOBAL_ACTIONS: ReadonlySet<GlobalAction> = new Set(['read', 'update'])\r\n\r\n/**\r\n * Builds the runtime `KeyScopes` shape consumed by `registry.assertScopeAllows`\r\n * from the typed scope fields on the api-key row.\r\n *\r\n * Returns null when no typed fields are populated AND no preset is set\r\n * (= full access — back-compat for pre-0.5 rows that pre-date scoped authz).\r\n *\r\n * Two complementary fail-closed rules:\r\n *\r\n * 1. **`'custom'` deny-all sentinel.** `'custom'` is a UI sentinel meaning\r\n *    \"use my override fields\"; it never becomes `KeyScopes.preset` itself.\r\n *    Payload persists unset JSON / select fields as `null`, so a fresh\r\n *    Custom key with no overrides arrives as `{preset:'custom',\r\n *    collectionScopes:null, globalScopes:null, toolAllow:null,\r\n *    toolDeny:null}`. That row must deny everything (not fall through to\r\n *    full access). The sentinel emits `{collections:{}, globals:{},\r\n *    tools:{allow:[]}}`.\r\n *\r\n * 2. **Per-axis explicit-empty.** When a row carries an array value on any\r\n *    axis (even `[]`), that axis is honoured as written — an empty\r\n *    `toolAllow:[]` means \"deny all tools\", not \"no opinion\". This closes a\r\n *    gap where a Custom key with `collectionScopes` populated AND\r\n *    `toolAllow:[]` previously emitted no `tools.allow` gate (the empty\r\n *    array was treated as absent). `toolDeny` is a deny-list, so an empty\r\n *    array carries no entries — it is dropped rather than emitted.\r\n */\r\nexport function composeScopes(\r\n  row: ApiKeyRow,\r\n  logger?: { warn?: (...args: unknown[]) => void },\r\n): KeyScopes | null {\r\n  const presetRaw = row.preset\r\n  const hasPreset = typeof presetRaw === 'string' && presetRaw.length > 0\r\n  const hasCollectionScopesField = Array.isArray(row.collectionScopes)\r\n  const hasGlobalScopesField = Array.isArray(row.globalScopes)\r\n  const hasToolAllowField = Array.isArray(row.toolAllow)\r\n  const hasToolDenyField = Array.isArray(row.toolDeny)\r\n\r\n  // Pre-0.5 back-compat: row has no preset and no typed scope fields at\r\n  // all (all null/undefined). Treat as full access.\r\n  if (\r\n    !hasPreset &&\r\n    !hasCollectionScopesField &&\r\n    !hasGlobalScopesField &&\r\n    !hasToolAllowField &&\r\n    !hasToolDenyField\r\n  ) {\r\n    return null\r\n  }\r\n\r\n  // Sentinel: Custom preset with every axis null/undefined (no array\r\n  // committed) denies everything. Payload-persisted unset JSON / select\r\n  // fields arrive as null; this is the fresh-Custom-key case.\r\n  if (\r\n    presetRaw === 'custom' &&\r\n    !hasCollectionScopesField &&\r\n    !hasGlobalScopesField &&\r\n    !hasToolAllowField &&\r\n    !hasToolDenyField\r\n  ) {\r\n    return { collections: {}, globals: {}, tools: { allow: [] } }\r\n  }\r\n\r\n  const out: KeyScopes = {}\r\n  if (hasPreset && presetRaw !== 'custom') {\r\n    out.preset = presetRaw as ScopePreset\r\n  }\r\n\r\n  if (hasCollectionScopesField) {\r\n    const collections: Record<string, CollectionAction[]> = {}\r\n    for (const entry of row.collectionScopes as ScopeRow[]) {\r\n      const slug = readScopeSlug(entry, 'collection', logger)\r\n      if (!slug) continue\r\n      const rawActions = Array.isArray(entry?.actions) ? entry.actions : []\r\n      const actions = rawActions.filter(\r\n        (a): a is CollectionAction => typeof a === 'string' && VALID_ACTIONS.has(a as CollectionAction),\r\n      )\r\n      collections[slug] = actions\r\n    }\r\n    out.collections = collections\r\n  }\r\n\r\n  if (hasGlobalScopesField) {\r\n    const globals: Record<string, GlobalAction[]> = {}\r\n    for (const entry of row.globalScopes as ScopeRow[]) {\r\n      const slug = readScopeSlug(entry, 'global', logger)\r\n      if (!slug) continue\r\n      const rawActions = Array.isArray(entry?.actions) ? entry.actions : []\r\n      const actions = rawActions.filter(\r\n        (a): a is GlobalAction => typeof a === 'string' && VALID_GLOBAL_ACTIONS.has(a as GlobalAction),\r\n      )\r\n      globals[slug] = actions\r\n    }\r\n    out.globals = globals\r\n  }\r\n\r\n  const toolDeny = hasToolDenyField\r\n    ? (row.toolDeny as unknown[]).filter((t): t is string => typeof t === 'string')\r\n    : []\r\n  const emitDeny = toolDeny.length > 0\r\n\r\n  if (hasToolAllowField || emitDeny) {\r\n    out.tools = {}\r\n    if (hasToolAllowField) {\r\n      const toolAllow = (row.toolAllow as unknown[]).filter((t): t is string => typeof t === 'string')\r\n      out.tools.allow = toolAllow\r\n    }\r\n    if (emitDeny) out.tools.deny = toolDeny\r\n  }\r\n\r\n  return out\r\n}\r\n\r\n/**\r\n * Builds the Payload `auth.strategies` entry that authenticates MCP requests.\r\n *\r\n * Authenticates `Authorization: Bearer <plaintext>` by computing the\r\n * upstream-compatible `apiKeyIndex` HMAC and looking up the row. On match,\r\n * it fires a non-blocking `lastUsedAt` write and hydrates `req.user` with\r\n * the linked user record + key context for downstream scope checks.\r\n */\r\nexport function createBearerStrategy(options: CreateBearerStrategyOptions): AuthStrategy {\r\n  const { collectionSlug, userCollection } = options\r\n\r\n  return {\r\n    name: AUTH_STRATEGY_NAME,\r\n    authenticate: async ({ headers, payload }) => {\r\n      const headersAny = headers as unknown as\r\n        | { get?: (name: string) => string | null }\r\n        | Record<string, string | undefined>\r\n      const headerValue =\r\n        typeof (headersAny as { get?: (name: string) => string | null }).get === 'function'\r\n          ? (headersAny as { get: (name: string) => string | null }).get('authorization')\r\n          : (headersAny as Record<string, string | undefined>).authorization\r\n      const token = extractBearerToken(headerValue ?? null)\r\n      if (!token) return { user: null }\r\n\r\n      const keyHash = hashKey(token, payload.secret)\r\n      const where: Where = { apiKeyIndex: { equals: keyHash } }\r\n\r\n      let docs: ApiKeyRow[] = []\r\n      try {\r\n        const result = (await payload.find({\r\n          collection: collectionSlug,\r\n          where,\r\n          depth: 1,\r\n          limit: 1,\r\n          pagination: false,\r\n          overrideAccess: true,\r\n        })) as unknown as { docs: ApiKeyRow[] }\r\n        docs = result.docs ?? []\r\n      } catch (err) {\r\n        payload.logger.error(\r\n          { err, event: 'mcp.auth.lookup_failed' },\r\n          '[payload-mcp-toolkit] API-key lookup failed',\r\n        )\r\n        return { user: null }\r\n      }\r\n\r\n      const row = docs[0]\r\n      if (!row) return { user: null }\r\n\r\n      const now = Date.now()\r\n      if (row.revokedAt) return { user: null }\r\n      if (row.expiresAt) {\r\n        const expiry = new Date(row.expiresAt).getTime()\r\n        if (Number.isFinite(expiry) && expiry < now) return { user: null }\r\n      }\r\n\r\n      const linkedUser = row.user\r\n      if (!linkedUser || typeof linkedUser !== 'object') return { user: null }\r\n\r\n      const effectiveScopes: KeyScopes | null = composeScopes(row, payload.logger)\r\n\r\n      // Fire-and-forget: do not block the request on this write.\r\n      void payload\r\n        .update({\r\n          collection: collectionSlug,\r\n          id: row.id,\r\n          data: { lastUsedAt: new Date().toISOString() } as Record<string, unknown>,\r\n          overrideAccess: true,\r\n        })\r\n        .catch(() => {\r\n          // Intentionally swallow: lastUsedAt drift is acceptable.\r\n        })\r\n\r\n      const user = linkedUser as Record<string, unknown>\r\n      return {\r\n        user: {\r\n          ...user,\r\n          collection: userCollection,\r\n          _strategy: AUTH_STRATEGY_NAME,\r\n          _mcpKey: {\r\n            keyId: row.id,\r\n            keyPrefix: typeof row.keyPrefix === 'string' ? row.keyPrefix : null,\r\n            scopes: effectiveScopes,\r\n          },\r\n        } as unknown as PayloadRequest['user'],\r\n      }\r\n    },\r\n  }\r\n}\r\n\r\n/**\r\n * Reads the per-request API-key context populated by the bearer strategy.\r\n * Returns null for non-MCP requests (e.g. cookie-authenticated admin users).\r\n */\r\nexport function getApiKeyContext(req: PayloadRequest): {\r\n  keyId: string | number\r\n  keyPrefix: string | null\r\n  scopes: KeyScopes | null\r\n} | null {\r\n  const user = req.user as\r\n    | (Record<string, unknown> & {\r\n        _mcpKey?: { keyId: string | number; keyPrefix: string | null; scopes: KeyScopes | null }\r\n      })\r\n    | null\r\n    | undefined\r\n  return user?._mcpKey ?? null\r\n}\r\n"],"names":["extractBearerToken","hashKey","AUTH_STRATEGY_NAME","warnedLegacyShape","readScopeSlug","entry","legacyKey","logger","slug","legacy","warn","event","VALID_ACTIONS","Set","VALID_GLOBAL_ACTIONS","composeScopes","row","presetRaw","preset","hasPreset","length","hasCollectionScopesField","Array","isArray","collectionScopes","hasGlobalScopesField","globalScopes","hasToolAllowField","toolAllow","hasToolDenyField","toolDeny","collections","globals","tools","allow","out","rawActions","actions","filter","a","has","t","emitDeny","deny","createBearerStrategy","options","collectionSlug","userCollection","name","authenticate","headers","payload","headersAny","headerValue","get","authorization","token","user","keyHash","secret","where","apiKeyIndex","equals","docs","result","find","collection","depth","limit","pagination","overrideAccess","err","error","now","Date","revokedAt","expiresAt","expiry","getTime","Number","isFinite","linkedUser","effectiveScopes","update","id","data","lastUsedAt","toISOString","catch","_strategy","_mcpKey","keyId","keyPrefix","scopes","getApiKeyContext","req"],"mappings":"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"}

package/dist/components/CollectionScopesMatrix.d.ts

@@ -0,0 +1,8 @@
+import * as React from 'react';
+export interface CollectionScopesMatrixProps {
+    path: string;
+    /** Forwarded via `clientProps` from `api-keys.ts`. */
+    availableCollections?: string[];
+}
+declare function CollectionScopesMatrix(props: CollectionScopesMatrixProps): React.ReactElement;
+export default CollectionScopesMatrix;