payload-mcp-toolkit 0.8.0 → 0.9.0

package/dist/oauth-permissions.d.ts

@@ -0,0 +1,52 @@
+import { type ResourceKind } from './scope/policy';
+import type { CollectionAction, GlobalAction, KeyScopes } from './types';
+/** OAuth grants top out at editor: delete and global writes need an API key. */
+export type Level = 'read-only' | 'editor';
+export interface CatalogTool {
+    name: string;
+    kind: ResourceKind;
+    action: CollectionAction;
+}
+/** What the consent screen can offer: exposed collections, globals and registered tools. */
+export interface Catalog {
+    collections: string[];
+    globals: string[];
+    tools: CatalogTool[];
+}
+/**
+ * What the consent form submits. An omitted list means "all of them" (the form sends only the lists
+ * the user changed); anything outside the catalog or the level is dropped.
+ */
+export interface Choice {
+    level?: Level;
+    collections?: Record<string, string[]>;
+    globals?: Record<string, string[]>;
+    tools?: string[];
+}
+export declare const collectionActions: (level: Level) => CollectionAction[];
+export declare const globalActions: (level: Level) => GlobalAction[];
+/** Tools a grant at this level could ever run. The rest are hidden, not offered. */
+export declare function toolsFor(catalog: Catalog, level: Level): CatalogTool[];
+/** Full access at a level, in the shape the consent form submits. The consent screen's default. */
+export declare function fullChoice(catalog: Catalog, level: Level): Required<Choice>;
+/** Turns a submitted choice into the scopes stored on the grant, capped at `max`. */
+export declare function permissionsFrom(choice: Choice, catalog: Catalog, max: Level): {
+    level: Level;
+    permissions: KeyScopes;
+};
+/**
+ * Re-caps a grant's stored scopes on every request. The site's access level or the token's scope may have
+ * shrunk since consent, and the scope checker honours a collection/global list over the preset, so the
+ * lists themselves must lose the actions the current level no longer allows.
+ */
+export declare function clampScopes(stored: KeyScopes, max: Level): KeyScopes;
+/** One line for the connections page, e.g. "Read, create and update · 3 of 12 collections · all tools". */
+type Lists = {
+    collections?: Record<string, unknown[]>;
+    globals?: Record<string, unknown[]>;
+    tools?: {
+        allow?: string[];
+    };
+};
+export declare function summarize(permissions: Lists | undefined, level: Level, catalog: Catalog): string;
+export {};

package/dist/oauth-permissions.js

@@ -0,0 +1,100 @@
+// Pure helpers shared by the OAuth server (src/oauth.ts) and the consent screen
+// (src/components/OAuthView.tsx). No Node or Payload runtime imports: the admin bundle loads this file.
+import { PRESET_ACTIONS, PRESET_GLOBAL_ACTIONS, PRESET_TOOL_DENY } from './scope/policy';
+export const collectionActions = (level)=>PRESET_ACTIONS[level];
+export const globalActions = (level)=>PRESET_GLOBAL_ACTIONS[level];
+/** Tools a grant at this level could ever run. The rest are hidden, not offered. */ export function toolsFor(catalog, level) {
+    return catalog.tools.filter((t)=>!PRESET_TOOL_DENY[level].includes(t.name) && (t.kind === 'global' ? globalActions(level) : collectionActions(level)).includes(t.action));
+}
+/** Full access at a level, in the shape the consent form submits. The consent screen's default. */ export function fullChoice(catalog, level) {
+    return {
+        level,
+        collections: Object.fromEntries(catalog.collections.map((slug)=>[
+                slug,
+                collectionActions(level)
+            ])),
+        globals: Object.fromEntries(catalog.globals.map((slug)=>[
+                slug,
+                globalActions(level)
+            ])),
+        tools: toolsFor(catalog, level).map((t)=>t.name)
+    };
+}
+// A whitelist equal to "everything" is left out, so account-wide tools (search, upload) keep working
+// and collections added later are included. The scope checker denies account tools once a whitelist is set.
+function pick(slugs, chosen, allowed) {
+    if (chosen === undefined) return undefined;
+    const map = {};
+    let full = true;
+    for (const slug of slugs){
+        const picked = chosen && typeof chosen === 'object' && Object.hasOwn(chosen, slug) && Array.isArray(chosen[slug]) ? chosen[slug] : [];
+        const actions = allowed.filter((a)=>picked.includes(a));
+        if (actions.length) map[slug] = actions;
+        if (actions.length !== allowed.length) full = false;
+    }
+    return full ? undefined : map;
+}
+/** Turns a submitted choice into the scopes stored on the grant, capped at `max`. */ export function permissionsFrom(choice, catalog, max) {
+    const level = choice.level === 'editor' && max === 'editor' ? 'editor' : 'read-only';
+    const offered = toolsFor(catalog, level).map((t)=>t.name);
+    const tools = choice.tools === undefined ? offered : Array.isArray(choice.tools) ? offered.filter((name)=>choice.tools.includes(name)) : [];
+    const collections = pick(catalog.collections, choice.collections, collectionActions(level));
+    const globals = pick(catalog.globals, choice.globals, globalActions(level));
+    return {
+        level,
+        permissions: {
+            preset: level,
+            ...collections && {
+                collections
+            },
+            ...globals && {
+                globals
+            },
+            ...tools.length !== offered.length && {
+                tools: {
+                    allow: tools
+                }
+            }
+        }
+    };
+}
+/**
+ * Re-caps a grant's stored scopes on every request. The site's access level or the token's scope may have
+ * shrunk since consent, and the scope checker honours a collection/global list over the preset, so the
+ * lists themselves must lose the actions the current level no longer allows.
+ */ export function clampScopes(stored, max) {
+    const level = stored.preset === 'editor' && max === 'editor' ? 'editor' : 'read-only';
+    const within = (map, allowed)=>Object.fromEntries(Object.entries(map).map(([slug, actions])=>[
+                slug,
+                actions.filter((a)=>allowed.includes(a))
+            ]));
+    return {
+        preset: level,
+        ...stored.collections && {
+            collections: within(stored.collections, collectionActions(level))
+        },
+        ...stored.globals && {
+            globals: within(stored.globals, globalActions(level))
+        },
+        ...stored.tools && {
+            tools: stored.tools
+        }
+    };
+}
+export function summarize(permissions, level, catalog) {
+    const count = (map, total, noun)=>!map ? `all ${noun}` : `${Object.keys(map).length} of ${total} ${noun}`;
+    // Counts tools that will actually run: limited collections or globals switch account-wide tools off.
+    const offered = toolsFor(catalog, level);
+    const limited = Boolean(permissions?.collections || permissions?.globals);
+    const usable = offered.filter((t)=>(permissions?.tools?.allow?.includes(t.name) ?? true) && !(limited && t.kind === 'account'));
+    return [
+        level === 'editor' ? 'Read, create and update' : 'Read only',
+        count(permissions?.collections, catalog.collections.length, 'collections'),
+        ...catalog.globals.length ? [
+            count(permissions?.globals, catalog.globals.length, 'globals')
+        ] : [],
+        usable.length === offered.length ? 'all tools' : `${usable.length} of ${offered.length} tools`
+    ].join(' · ');
+}
+
+//# sourceMappingURL=oauth-permissions.js.map

package/dist/oauth-permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/oauth-permissions.ts"],"sourcesContent":["// Pure helpers shared by the OAuth server (src/oauth.ts) and the consent screen\n// (src/components/OAuthView.tsx). No Node or Payload runtime imports: the admin bundle loads this file.\nimport { PRESET_ACTIONS, PRESET_GLOBAL_ACTIONS, PRESET_TOOL_DENY, type ResourceKind } from './scope/policy'\nimport type { CollectionAction, GlobalAction, KeyScopes } from './types'\n\n/** OAuth grants top out at editor: delete and global writes need an API key. */\nexport type Level = 'read-only' | 'editor'\n\nexport interface CatalogTool { name: string; kind: ResourceKind; action: CollectionAction }\n/** What the consent screen can offer: exposed collections, globals and registered tools. */\nexport interface Catalog { collections: string[]; globals: string[]; tools: CatalogTool[] }\n\n/**\n * What the consent form submits. An omitted list means \"all of them\" (the form sends only the lists\n * the user changed); anything outside the catalog or the level is dropped.\n */\nexport interface Choice {\n  level?: Level\n  collections?: Record<string, string[]>\n  globals?: Record<string, string[]>\n  tools?: string[]\n}\n\nexport const collectionActions = (level: Level): CollectionAction[] => PRESET_ACTIONS[level]\nexport const globalActions = (level: Level): GlobalAction[] => PRESET_GLOBAL_ACTIONS[level]\n\n/** Tools a grant at this level could ever run. The rest are hidden, not offered. */\nexport function toolsFor(catalog: Catalog, level: Level): CatalogTool[] {\n  return catalog.tools.filter(t => !PRESET_TOOL_DENY[level].includes(t.name) &&\n    (t.kind === 'global' ? globalActions(level) : collectionActions(level)).includes(t.action as never))\n}\n\n/** Full access at a level, in the shape the consent form submits. The consent screen's default. */\nexport function fullChoice(catalog: Catalog, level: Level): Required<Choice> {\n  return {\n    level,\n    collections: Object.fromEntries(catalog.collections.map(slug => [slug, collectionActions(level)])),\n    globals: Object.fromEntries(catalog.globals.map(slug => [slug, globalActions(level)])),\n    tools: toolsFor(catalog, level).map(t => t.name),\n  }\n}\n\n// A whitelist equal to \"everything\" is left out, so account-wide tools (search, upload) keep working\n// and collections added later are included. The scope checker denies account tools once a whitelist is set.\nfunction pick<A extends string>(slugs: string[], chosen: Record<string, string[]> | undefined, allowed: A[]): Record<string, A[]> | undefined {\n  if (chosen === undefined) return undefined\n  const map: Record<string, A[]> = {}\n  let full = true\n  for (const slug of slugs) {\n    const picked = chosen && typeof chosen === 'object' && Object.hasOwn(chosen, slug) && Array.isArray(chosen[slug]) ? chosen[slug] : []\n    const actions = allowed.filter(a => picked.includes(a))\n    if (actions.length) map[slug] = actions\n    if (actions.length !== allowed.length) full = false\n  }\n  return full ? undefined : map\n}\n\n/** Turns a submitted choice into the scopes stored on the grant, capped at `max`. */\nexport function permissionsFrom(choice: Choice, catalog: Catalog, max: Level): { level: Level; permissions: KeyScopes } {\n  const level: Level = choice.level === 'editor' && max === 'editor' ? 'editor' : 'read-only'\n  const offered = toolsFor(catalog, level).map(t => t.name)\n  const tools = choice.tools === undefined ? offered : Array.isArray(choice.tools) ? offered.filter(name => choice.tools!.includes(name)) : []\n  const collections = pick(catalog.collections, choice.collections, collectionActions(level))\n  const globals = pick(catalog.globals, choice.globals, globalActions(level))\n  return { level, permissions: {\n    preset: level,\n    ...(collections && { collections }),\n    ...(globals && { globals }),\n    ...(tools.length !== offered.length && { tools: { allow: tools } }),\n  } }\n}\n\n/**\n * Re-caps a grant's stored scopes on every request. The site's access level or the token's scope may have\n * shrunk since consent, and the scope checker honours a collection/global list over the preset, so the\n * lists themselves must lose the actions the current level no longer allows.\n */\nexport function clampScopes(stored: KeyScopes, max: Level): KeyScopes {\n  const level: Level = stored.preset === 'editor' && max === 'editor' ? 'editor' : 'read-only'\n  const within = <A extends string>(map: Record<string, A[]>, allowed: A[]) =>\n    Object.fromEntries(Object.entries(map).map(([slug, actions]) => [slug, actions.filter(a => allowed.includes(a))]))\n  return {\n    preset: level,\n    ...(stored.collections && { collections: within(stored.collections, collectionActions(level)) }),\n    ...(stored.globals && { globals: within(stored.globals, globalActions(level)) }),\n    ...(stored.tools && { tools: stored.tools }),\n  }\n}\n\n/** One line for the connections page, e.g. \"Read, create and update · 3 of 12 collections · all tools\". */\ntype Lists = { collections?: Record<string, unknown[]>; globals?: Record<string, unknown[]>; tools?: { allow?: string[] } }\nexport function summarize(permissions: Lists | undefined, level: Level, catalog: Catalog): string {\n  const count = (map: Record<string, unknown[]> | undefined, total: number, noun: string) =>\n    !map ? `all ${noun}` : `${Object.keys(map).length} of ${total} ${noun}`\n  // Counts tools that will actually run: limited collections or globals switch account-wide tools off.\n  const offered = toolsFor(catalog, level)\n  const limited = Boolean(permissions?.collections || permissions?.globals)\n  const usable = offered.filter(t => (permissions?.tools?.allow?.includes(t.name) ?? true) && !(limited && t.kind === 'account'))\n  return [\n    level === 'editor' ? 'Read, create and update' : 'Read only',\n    count(permissions?.collections, catalog.collections.length, 'collections'),\n    ...(catalog.globals.length ? [count(permissions?.globals, catalog.globals.length, 'globals')] : []),\n    usable.length === offered.length ? 'all tools' : `${usable.length} of ${offered.length} tools`,\n  ].join(' · ')\n}\n"],"names":["PRESET_ACTIONS","PRESET_GLOBAL_ACTIONS","PRESET_TOOL_DENY","collectionActions","level","globalActions","toolsFor","catalog","tools","filter","t","includes","name","kind","action","fullChoice","collections","Object","fromEntries","map","slug","globals","pick","slugs","chosen","allowed","undefined","full","picked","hasOwn","Array","isArray","actions","a","length","permissionsFrom","choice","max","offered","permissions","preset","allow","clampScopes","stored","within","entries","summarize","count","total","noun","keys","limited","Boolean","usable","join"],"mappings":"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"}

package/dist/oauth-store.d.ts

@@ -0,0 +1,19 @@
+import type { CollectionConfig, Payload } from 'payload';
+export declare const OAUTH_COLLECTION = "payload-mcp-oauth";
+export interface OAuthRecord {
+    id: string | number;
+    key: string;
+    kind: 'grant' | 'code' | 'access' | 'refresh' | 'used';
+    expiresAt: string;
+    owner?: string;
+    data: Record<string, unknown>;
+}
+export declare function createOAuthCollection(): CollectionConfig;
+export declare function tokenKey(payload: Payload, token: string): string;
+export declare function readRecord(payload: Payload, key: string): Promise<OAuthRecord | undefined>;
+export declare function writeRecord(payload: Payload, record: Omit<OAuthRecord, 'id'>): Promise<void>;
+export declare function isLive(record: OAuthRecord | undefined): record is OAuthRecord;
+export declare function consumeRecord(payload: Payload, record: OAuthRecord): Promise<boolean>;
+export declare function revokeGrant(payload: Payload, grant: OAuthRecord): Promise<void>;
+/** Run periodically in the host's existing scheduler. Never remove unexpired consumption claims. */
+export declare function pruneOAuthRecords(payload: Payload): Promise<void>;

package/dist/oauth-store.js

@@ -0,0 +1,122 @@
+import { hashKey } from './hash';
+export const OAUTH_COLLECTION = 'payload-mcp-oauth';
+export function createOAuthCollection() {
+    return {
+        slug: OAUTH_COLLECTION,
+        admin: {
+            hidden: true
+        },
+        access: {
+            create: ()=>false,
+            read: ()=>false,
+            update: ()=>false,
+            delete: ()=>false
+        },
+        fields: [
+            {
+                name: 'key',
+                type: 'text',
+                required: true,
+                unique: true
+            },
+            {
+                name: 'kind',
+                type: 'select',
+                required: true,
+                options: [
+                    'grant',
+                    'code',
+                    'access',
+                    'refresh',
+                    'used'
+                ]
+            },
+            {
+                name: 'expiresAt',
+                type: 'date',
+                required: true,
+                index: true
+            },
+            {
+                name: 'owner',
+                type: 'text',
+                index: true
+            },
+            {
+                name: 'data',
+                type: 'json',
+                required: true
+            }
+        ]
+    };
+}
+export function tokenKey(payload, token) {
+    return hashKey(`oauth:${token}`, payload.secret);
+}
+export async function readRecord(payload, key) {
+    const result = await payload.find({
+        collection: OAUTH_COLLECTION,
+        where: {
+            key: {
+                equals: key
+            }
+        },
+        limit: 1,
+        depth: 0,
+        pagination: false,
+        overrideAccess: true
+    });
+    return result.docs[0];
+}
+export async function writeRecord(payload, record) {
+    await payload.create({
+        collection: OAUTH_COLLECTION,
+        data: record,
+        overrideAccess: true
+    });
+}
+export function isLive(record) {
+    return !!record && Date.parse(record.expiresAt) > Date.now();
+}
+export async function consumeRecord(payload, record) {
+    const key = `used:${record.key}`;
+    // A unique INSERT elects one winner across processes. Payload's update(where) is not a CAS.
+    try {
+        await writeRecord(payload, {
+            key,
+            kind: 'used',
+            expiresAt: record.expiresAt,
+            data: {}
+        });
+        return true;
+    } catch (error) {
+        const validation = error;
+        // Payload normalizes adapter uniqueness errors to a field ValidationError.
+        if (validation?.name !== 'ValidationError' || validation.data?.collection !== OAUTH_COLLECTION || validation.data.errors?.length !== 1 || validation.data.errors[0].path !== 'key') throw error;
+        if (await readRecord(payload, key)) return false;
+        throw error;
+    }
+}
+export async function revokeGrant(payload, grant) {
+    await payload.update({
+        collection: OAUTH_COLLECTION,
+        id: grant.id,
+        data: {
+            expiresAt: new Date(0).toISOString()
+        },
+        overrideAccess: true
+    });
+}
+/** Run periodically in the host's existing scheduler. Never remove unexpired consumption claims. */ export async function pruneOAuthRecords(payload) {
+    await payload.delete({
+        collection: OAUTH_COLLECTION,
+        where: {
+            expiresAt: {
+                less_than: new Date().toISOString()
+            }
+        },
+        overrideAccess: true
+    });
+}
+
+//# sourceMappingURL=oauth-store.js.map

package/dist/oauth-store.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/oauth-store.ts"],"sourcesContent":["import type { CollectionConfig, Payload } from 'payload'\nimport { hashKey } from './hash'\n\nexport const OAUTH_COLLECTION = 'payload-mcp-oauth'\n\nexport interface OAuthRecord {\n  id: string | number\n  key: string\n  kind: 'grant' | 'code' | 'access' | 'refresh' | 'used'\n  expiresAt: string\n  owner?: string\n  data: Record<string, unknown>\n}\n\nexport function createOAuthCollection(): CollectionConfig {\n  return {\n    slug: OAUTH_COLLECTION,\n    admin: { hidden: true },\n    access: { create: () => false, read: () => false, update: () => false, delete: () => false },\n    fields: [\n      { name: 'key', type: 'text', required: true, unique: true },\n      { name: 'kind', type: 'select', required: true, options: ['grant', 'code', 'access', 'refresh', 'used'] },\n      { name: 'expiresAt', type: 'date', required: true, index: true },\n      { name: 'owner', type: 'text', index: true },\n      { name: 'data', type: 'json', required: true },\n    ],\n  }\n}\n\nexport function tokenKey(payload: Payload, token: string): string {\n  return hashKey(`oauth:${token}`, payload.secret)\n}\n\nexport async function readRecord(payload: Payload, key: string): Promise<OAuthRecord | undefined> {\n  const result = await payload.find({\n    collection: OAUTH_COLLECTION, where: { key: { equals: key } },\n    limit: 1, depth: 0, pagination: false, overrideAccess: true,\n  })\n  return result.docs[0] as unknown as OAuthRecord | undefined\n}\n\nexport async function writeRecord(payload: Payload, record: Omit<OAuthRecord, 'id'>): Promise<void> {\n  await payload.create({ collection: OAUTH_COLLECTION, data: record, overrideAccess: true })\n}\n\nexport function isLive(record: OAuthRecord | undefined): record is OAuthRecord {\n  return !!record && Date.parse(record.expiresAt) > Date.now()\n}\n\nexport async function consumeRecord(payload: Payload, record: OAuthRecord): Promise<boolean> {\n  const key = `used:${record.key}`\n  // A unique INSERT elects one winner across processes. Payload's update(where) is not a CAS.\n  try {\n    await writeRecord(payload, { key, kind: 'used', expiresAt: record.expiresAt, data: {} })\n    return true\n  } catch (error) {\n    const validation = error as { name?: string; data?: { collection?: string; errors?: { path?: string }[] } }\n    // Payload normalizes adapter uniqueness errors to a field ValidationError.\n    if (validation?.name !== 'ValidationError' || validation.data?.collection !== OAUTH_COLLECTION ||\n      validation.data.errors?.length !== 1 || validation.data.errors[0].path !== 'key') throw error\n    if (await readRecord(payload, key)) return false\n    throw error\n  }\n}\n\nexport async function revokeGrant(payload: Payload, grant: OAuthRecord): Promise<void> {\n  await payload.update({ collection: OAUTH_COLLECTION, id: grant.id,\n    data: { expiresAt: new Date(0).toISOString() }, overrideAccess: true })\n}\n\n/** Run periodically in the host's existing scheduler. Never remove unexpired consumption claims. */\nexport async function pruneOAuthRecords(payload: Payload): Promise<void> {\n  await payload.delete({ collection: OAUTH_COLLECTION,\n    where: { expiresAt: { less_than: new Date().toISOString() } }, overrideAccess: true })\n}\n"],"names":["hashKey","OAUTH_COLLECTION","createOAuthCollection","slug","admin","hidden","access","create","read","update","delete","fields","name","type","required","unique","options","index","tokenKey","payload","token","secret","readRecord","key","result","find","collection","where","equals","limit","depth","pagination","overrideAccess","docs","writeRecord","record","data","isLive","Date","parse","expiresAt","now","consumeRecord","kind","error","validation","errors","length","path","revokeGrant","grant","id","toISOString","pruneOAuthRecords","less_than"],"mappings":"AACA,SAASA,OAAO,QAAQ,SAAQ;AAEhC,OAAO,MAAMC,mBAAmB,oBAAmB;AAWnD,OAAO,SAASC;IACd,OAAO;QACLC,MAAMF;QACNG,OAAO;YAAEC,QAAQ;QAAK;QACtBC,QAAQ;YAAEC,QAAQ,IAAM;YAAOC,MAAM,IAAM;YAAOC,QAAQ,IAAM;YAAOC,QAAQ,IAAM;QAAM;QAC3FC,QAAQ;YACN;gBAAEC,MAAM;gBAAOC,MAAM;gBAAQC,UAAU;gBAAMC,QAAQ;YAAK;YAC1D;gBAAEH,MAAM;gBAAQC,MAAM;gBAAUC,UAAU;gBAAME,SAAS;oBAAC;oBAAS;oBAAQ;oBAAU;oBAAW;iBAAO;YAAC;YACxG;gBAAEJ,MAAM;gBAAaC,MAAM;gBAAQC,UAAU;gBAAMG,OAAO;YAAK;YAC/D;gBAAEL,MAAM;gBAASC,MAAM;gBAAQI,OAAO;YAAK;YAC3C;gBAAEL,MAAM;gBAAQC,MAAM;gBAAQC,UAAU;YAAK;SAC9C;IACH;AACF;AAEA,OAAO,SAASI,SAASC,OAAgB,EAAEC,KAAa;IACtD,OAAOpB,QAAQ,CAAC,MAAM,EAAEoB,OAAO,EAAED,QAAQE,MAAM;AACjD;AAEA,OAAO,eAAeC,WAAWH,OAAgB,EAAEI,GAAW;IAC5D,MAAMC,SAAS,MAAML,QAAQM,IAAI,CAAC;QAChCC,YAAYzB;QAAkB0B,OAAO;YAAEJ,KAAK;gBAAEK,QAAQL;YAAI;QAAE;QAC5DM,OAAO;QAAGC,OAAO;QAAGC,YAAY;QAAOC,gBAAgB;IACzD;IACA,OAAOR,OAAOS,IAAI,CAAC,EAAE;AACvB;AAEA,OAAO,eAAeC,YAAYf,OAAgB,EAAEgB,MAA+B;IACjF,MAAMhB,QAAQZ,MAAM,CAAC;QAAEmB,YAAYzB;QAAkBmC,MAAMD;QAAQH,gBAAgB;IAAK;AAC1F;AAEA,OAAO,SAASK,OAAOF,MAA+B;IACpD,OAAO,CAAC,CAACA,UAAUG,KAAKC,KAAK,CAACJ,OAAOK,SAAS,IAAIF,KAAKG,GAAG;AAC5D;AAEA,OAAO,eAAeC,cAAcvB,OAAgB,EAAEgB,MAAmB;IACvE,MAAMZ,MAAM,CAAC,KAAK,EAAEY,OAAOZ,GAAG,EAAE;IAChC,4FAA4F;IAC5F,IAAI;QACF,MAAMW,YAAYf,SAAS;YAAEI;YAAKoB,MAAM;YAAQH,WAAWL,OAAOK,SAAS;YAAEJ,MAAM,CAAC;QAAE;QACtF,OAAO;IACT,EAAE,OAAOQ,OAAO;QACd,MAAMC,aAAaD;QACnB,2EAA2E;QAC3E,IAAIC,YAAYjC,SAAS,qBAAqBiC,WAAWT,IAAI,EAAEV,eAAezB,oBAC5E4C,WAAWT,IAAI,CAACU,MAAM,EAAEC,WAAW,KAAKF,WAAWT,IAAI,CAACU,MAAM,CAAC,EAAE,CAACE,IAAI,KAAK,OAAO,MAAMJ;QAC1F,IAAI,MAAMtB,WAAWH,SAASI,MAAM,OAAO;QAC3C,MAAMqB;IACR;AACF;AAEA,OAAO,eAAeK,YAAY9B,OAAgB,EAAE+B,KAAkB;IACpE,MAAM/B,QAAQV,MAAM,CAAC;QAAEiB,YAAYzB;QAAkBkD,IAAID,MAAMC,EAAE;QAC/Df,MAAM;YAAEI,WAAW,IAAIF,KAAK,GAAGc,WAAW;QAAG;QAAGpB,gBAAgB;IAAK;AACzE;AAEA,kGAAkG,GAClG,OAAO,eAAeqB,kBAAkBlC,OAAgB;IACtD,MAAMA,QAAQT,MAAM,CAAC;QAAEgB,YAAYzB;QACjC0B,OAAO;YAAEa,WAAW;gBAAEc,WAAW,IAAIhB,OAAOc,WAAW;YAAG;QAAE;QAAGpB,gBAAgB;IAAK;AACxF"}

package/dist/oauth.d.ts

@@ -0,0 +1,19 @@
+import type { Config, Endpoint, PayloadRequest } from 'payload';
+import { type Catalog } from './oauth-permissions';
+export interface OAuthOptions {
+    /** Required site policy. Rechecked at consent, refresh and every MCP request. */
+    canAuthorize: (req: PayloadRequest) => boolean | Promise<boolean>;
+    /** Defaults to Payload admin login. Return a same-origin login URL that returns to returnTo. */
+    loginURL?: (returnTo: string) => string;
+    /** Exact trusted callbacks; defaults to the Claude (web/Desktop) and ChatGPT remote connector callbacks. */
+    redirectURIs?: string[];
+    /** Read-only by default. Editor enables create/update, still subject to Payload access controls. */
+    access?: 'read-only' | 'editor';
+}
+/** `catalog` is what the consent screen offers: exposed collections, globals and registered tools. */
+export declare function createOAuth(options: OAuthOptions, config: Config, userCollection: string, catalog: Catalog): {
+    endpoints: Endpoint[];
+    authenticate: (req: PayloadRequest) => Promise<boolean>;
+    metadataURL: string;
+    scope: string;
+};