@forumone/throughline 0.0.0 → 1.0.0-next.0

package/dist/jobs/workflow-types.d.ts

@@ -0,0 +1,280 @@
+import type { Payload } from 'payload';
+import type { CacheTags } from '../cache-tags.js';
+/**
+ * Common dependencies for the platform's jobs. None takes a runner: the
+ * adapter is the runner (`inngestJobs(inngest, …)` or `payloadJobs()`), and
+ * Payload comes from the job's options or from the adapter.
+ */
+export type WorkflowFailureHandler = (args: {
+    /** The error that exhausted the retries. */
+    error: Error;
+    /** Inngest's `function.failed` payload, which names the run. */
+    event: {
+        data?: {
+            function_id?: string;
+            run_id?: string;
+            event?: {
+                name?: string;
+            };
+        };
+    };
+}) => Promise<void> | void;
+export interface BaseWorkflowOptions {
+    payload: Payload;
+    /**
+     * Called once when a run has exhausted its retries.
+     *
+     * Named `onTerminalFailure` rather than `onFailure`, and the collision that
+     * forced it is worth keeping in view: `HealthcheckOptions.onFailure` already
+     * exists and is a different thing — it fires once per run with the list of
+     * checks that failed, on the *first* bad run, because a probe has no retries
+     * to exhaust. Both are useful and a function can take both. One name for two
+     * moments would have made every call site ambiguous about which it wired.
+     *
+     * Optional, and absent means the previous behaviour: the failure reaches
+     * whatever Inngest's dashboard shows and nothing else. A host that passes one
+     * gets the only signal that does not require somebody to go and look.
+     */
+    onTerminalFailure?: WorkflowFailureHandler;
+    /**
+     * Maximum simultaneous runs of this function.
+     *
+     * Two of the crons here default to 1 because they read a set of due rows and
+     * then act on them, which is a lost-update race between overlapping runs —
+     * see each one's own note. Passing a value overrides that; passing one for a
+     * workflow with no default adds a cap where there was none.
+     */
+    concurrency?: number;
+}
+/**
+ * The failure and concurrency half of a function config, built once.
+ *
+ * Spread into each `createFunction` config so the five workflows cannot
+ * disagree about the shape — the same reason `collect-component-tokens.ts` was
+ * extracted, where the writer and the checker being separate implementations
+ * left 61 of 74 contracts drifted.
+ *
+ * `defaultConcurrency` is the factory's own answer, used when the host passes
+ * none. Omitting both keys rather than passing `undefined` matters:
+ * `exactOptionalPropertyTypes` is on, and Inngest reads the presence of the key.
+ */
+export declare function failureOptions(options: FailureAwareOptions, defaultConcurrency?: number): {
+    onFailure?: WorkflowFailureHandler;
+    concurrency?: number;
+};
+/**
+ * The two fields `failureOptions` reads, and nothing else.
+ *
+ * Narrower than `BaseWorkflowOptions` on purpose: `AuditEventEchoOptions` takes
+ * no `payload`, so it is not a `BaseWorkflowOptions` and asking
+ * for one would have excluded it from failure handling for a reason that has
+ * nothing to do with failure handling.
+ */
+export interface FailureAwareOptions {
+    onTerminalFailure?: WorkflowFailureHandler;
+    concurrency?: number;
+}
+export interface RevalidatePathsInput {
+    /** A page path (`/about`, `/blog/post-1`, or `''` for layout-level only). */
+    path: string;
+    /** Tag list passed through to Next.js's `revalidateTag`. */
+    tags: string[];
+}
+export type RevalidateFn = (input: RevalidatePathsInput) => Promise<void>;
+export interface RevalidateOnPublishOptions extends BaseWorkflowOptions {
+    /**
+     * Custom revalidation function. Defaults to Next.js `revalidatePath` +
+     * `revalidateTag` (loaded via dynamic import so non-Next.js consumers
+     * don't fail to import the package). Supply your own for non-Next.js
+     * frontends or richer cache invalidation.
+     */
+    revalidate?: RevalidateFn;
+    /**
+     * Per-collection URL builders: where a document of each collection is
+     * served, given its slug. Required, and there are no built-in entries —
+     * only the site knows its routes. A collection with no entry has its tags
+     * dropped and no path revalidated, and the run logs a warning.
+     *
+     * ```ts
+     * urlBuilders: {
+     *   pages: (slug) => (slug === 'home' ? '/' : `/${slug}`),
+     *   posts: (slug) => `/news/${slug}`,
+     * }
+     * ```
+     */
+    urlBuilders: Record<string, (slug: string) => string>;
+    /**
+     * The tag scheme, shared with readers and with
+     * `createTagRevalidationHooks`. A collection with no `collectionTags` entry
+     * drops `[cacheTags.collection(<collection>)]`. Default: `defaultCacheTags`,
+     * whose collection tag is the bare slug.
+     */
+    cacheTags?: CacheTags;
+    /**
+     * Per-collection cache tags, overriding the scheme for that collection.
+     * Multiple tags supported for collections that participate in shared
+     * listings (e.g. `programs` → `['programs', 'sitemap']`).
+     */
+    collectionTags?: Record<string, string[]>;
+    /**
+     * Override the function id. Default: `revalidate-on-publish`.
+     * Useful if multiple instances of the workflow run in the same Inngest
+     * deployment (rare).
+     */
+    id?: string;
+}
+export interface ScheduledCollectionConfig {
+    slug: string;
+    /**
+     * Field name carrying the publish status. Default: `_status`.
+     * Override only if the collection uses a non-default status field.
+     */
+    statusField?: string;
+    /**
+     * Field name carrying the scheduled-publish timestamp. Default: `scheduledPublishAt`.
+     */
+    scheduledField?: string;
+}
+/** One document the cron found due, handed to `publish`. */
+export interface ScheduledPublishRequest {
+    collection: string;
+    id: string;
+    /** Recorded on the audit event, so a scheduled publish is distinguishable. */
+    reasoning: string;
+}
+/**
+ * What `publish` reports back. `published: false` is a policy refusal — a
+ * composition error, a missing approval — and is expected traffic, not a fault.
+ */
+export interface ScheduledPublishResult {
+    published: boolean;
+    reason?: string | undefined;
+}
+export interface ExecuteScheduledPublishesOptions extends BaseWorkflowOptions {
+    /** Collections that participate in scheduled publishing. */
+    collections: ScheduledCollectionConfig[];
+    /** Cron schedule. Default: `*\/5 * * * *` (every 5 minutes). */
+    schedule?: string;
+    /**
+     * How to publish one document. **Wire this to the publishing service**, not to
+     * `payload.update` — the service is the seven-stage pipeline, and a direct
+     * write skips composition, accessibility and approval gating:
+     *
+     * ```ts
+     * import { getPublishingService } from '@forumone/throughline/publishing'
+     *
+     * publish: async ({ collection, id, reasoning }) => {
+     *   const outcome = await getPublishingService(payload).publish({
+     *     collection,
+     *     id,
+     *     actor: { apiKeyName: 'scheduled-publish', channel: 'mcp' },
+     *     meta: { reasoning },
+     *   })
+     *   return { published: outcome.published, reason: outcome.reason }
+     * }
+     * ```
+     *
+     * Injected rather than built in because this package is a leaf — it depends on
+     * `core` alone, and reaching the publishing service means depending on the
+     * publishing package or duplicating its symbol string.
+     *
+     * It used to be a `fetch` to `POST /api/publishing/mcp` with a bearer key, and
+     * that endpoint no longer exists. The self-call was also the wrong shape: it
+     * cost a function invocation per document, needed a key and a base URL to be
+     * right, and returned 401 rather than publishing anything if the deployment
+     * URL sat behind access protection.
+     */
+    publish: (request: ScheduledPublishRequest, 
+    /** The Payload the job runs against, for a callback declared before Payload exists. */
+    context: {
+        payload: Payload;
+    }) => Promise<ScheduledPublishResult>;
+    /**
+     * Leave a document alone until it is this many milliseconds past its time.
+     * Default: 0.
+     *
+     * For a host that also runs `publishAtScheduledTimeJob`, which
+     * publishes on time and makes this poll a backstop for an event that never
+     * arrived. Without a grace period the two can reach the same due document in
+     * the same moment and publish it twice.
+     */
+    overdueByMs?: number;
+    /** Override the function id. Default: `execute-scheduled-publishes`. */
+    id?: string;
+}
+export interface PublishAtScheduledTimeOptions extends BaseWorkflowOptions {
+    /**
+     * Collections that participate in scheduled publishing. An event naming any
+     * other collection is ignored.
+     */
+    collections: ScheduledCollectionConfig[];
+    /** How to publish one document. The same contract, and the same warning, as `ExecuteScheduledPublishesOptions.publish`. */
+    publish: (request: ScheduledPublishRequest, 
+    /** The Payload the job runs against, for a callback declared before Payload exists. */
+    context: {
+        payload: Payload;
+    }) => Promise<ScheduledPublishResult>;
+    /**
+     * The longest single sleep, in milliseconds. A schedule further out is
+     * reached by relaying the event. Default: six days — Inngest's free plan caps
+     * a sleep at seven.
+     */
+    maxSleepMs?: number;
+    /** Override the function id. Default: `publish-at-scheduled-time`. */
+    id?: string;
+}
+export interface ExpireStaleApprovalsOptions extends BaseWorkflowOptions {
+    /** Approvals collection slug. Default: 'approvals'. */
+    collectionSlug?: string;
+    /** Cron schedule. Default: `0 2 * * *` (daily at 2am UTC). */
+    schedule?: string;
+    /** Override the function id. Default: `expire-stale-approvals`. */
+    id?: string;
+}
+export interface AuditEchoEvent {
+    action: string;
+    data: Record<string, unknown>;
+}
+export interface AuditEchoHandler {
+    /** Predicate. Return true to run `handle`. */
+    match: (event: {
+        action: string;
+    }) => boolean;
+    /** Side-effects (e.g. fire a follow-on Inngest event). */
+    handle: (event: AuditEchoEvent) => Promise<void>;
+}
+export interface AuditEventEchoOptions extends FailureAwareOptions {
+    /**
+     * Additional handlers run after the built-in approval fan-out. Each
+     * handler is wrapped in its own `step.run` so failures retry independently.
+     */
+    handlers?: AuditEchoHandler[];
+    /** Override the function id. Default: `audit-event-echo`. */
+    id?: string;
+}
+export interface HealthcheckResult {
+    ok: boolean;
+    details?: string;
+}
+export interface HealthcheckDefinition {
+    name: string;
+    run: (ctx: {
+        payload: Payload;
+    }) => Promise<HealthcheckResult>;
+}
+export interface HealthcheckOptions extends BaseWorkflowOptions {
+    checks: HealthcheckDefinition[];
+    /** Cron schedule. Default: `*\/15 * * * *`. */
+    schedule?: string;
+    /**
+     * Called once per run when at least one check fails. Defaults to
+     * `console.error`; production deployments route this to monitoring.
+     */
+    onFailure?: (failures: Array<{
+        name: string;
+        details?: string;
+    }>) => Promise<void>;
+    /** Override the function id. Default: `healthcheck`. */
+    id?: string;
+}
+//# sourceMappingURL=workflow-types.d.ts.map

package/dist/jobs/workflow-types.d.ts.map

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

package/dist/jobs/workflow-types.js

@@ -0,0 +1,22 @@
+/**
+ * The failure and concurrency half of a function config, built once.
+ *
+ * Spread into each `createFunction` config so the five workflows cannot
+ * disagree about the shape — the same reason `collect-component-tokens.ts` was
+ * extracted, where the writer and the checker being separate implementations
+ * left 61 of 74 contracts drifted.
+ *
+ * `defaultConcurrency` is the factory's own answer, used when the host passes
+ * none. Omitting both keys rather than passing `undefined` matters:
+ * `exactOptionalPropertyTypes` is on, and Inngest reads the presence of the key.
+ */
+export function failureOptions(options, defaultConcurrency) {
+    const concurrency = options.concurrency ?? defaultConcurrency;
+    return {
+        // `onFailure` is Inngest's key; `onTerminalFailure` is ours. The rename
+        // happens here, once, which is the other reason this is a function.
+        ...(options.onTerminalFailure ? { onFailure: options.onTerminalFailure } : {}),
+        ...(concurrency !== undefined ? { concurrency } : {}),
+    };
+}
+//# sourceMappingURL=workflow-types.js.map

package/dist/jobs/workflow-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-types.js","sourceRoot":"","sources":["../../src/jobs/workflow-types.ts"],"names":[],"mappings":"AAkEA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAC5B,OAA4B,EAC5B,kBAA2B;IAE3B,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,kBAAkB,CAAA;IAE7D,OAAO;QACL,wEAAwE;QACxE,oEAAoE;QACpE,GAAG,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9E,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtD,CAAA;AACH,CAAC"}

package/dist/logger/index.d.ts

@@ -0,0 +1,9 @@
+import type { Logger } from '../plugin-contract/index.js';
+/** Default logger that delegates to `console`. Plugins fall back to this when no logger is supplied. */
+export declare const defaultLogger: Logger;
+/**
+ * Wraps a logger so every message is prefixed with a `[name]` tag. Useful
+ * for request-scoped or plugin-scoped logging.
+ */
+export declare function createNamedLogger(name: string, base?: Logger): Logger;
+//# sourceMappingURL=index.d.ts.map

package/dist/logger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAA;AAEzD,wGAAwG;AACxG,eAAO,MAAM,aAAa,EAAE,MAiB3B,CAAA;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAsB,GAAG,MAAM,CAQpF"}

package/dist/logger/index.js

@@ -0,0 +1,41 @@
+/** Default logger that delegates to `console`. Plugins fall back to this when no logger is supplied. */
+export const defaultLogger = {
+    debug: (message, context) => {
+        if (context)
+            console.debug(message, context);
+        else
+            console.debug(message);
+    },
+    info: (message, context) => {
+        if (context)
+            console.log(message, context);
+        else
+            console.log(message);
+    },
+    warn: (message, context) => {
+        if (context)
+            console.warn(message, context);
+        else
+            console.warn(message);
+    },
+    error: (message, context) => {
+        if (context)
+            console.error(message, context);
+        else
+            console.error(message);
+    },
+};
+/**
+ * Wraps a logger so every message is prefixed with a `[name]` tag. Useful
+ * for request-scoped or plugin-scoped logging.
+ */
+export function createNamedLogger(name, base = defaultLogger) {
+    const tag = `[${name}]`;
+    return {
+        debug: (message, context) => base.debug(`${tag} ${message}`, context),
+        info: (message, context) => base.info(`${tag} ${message}`, context),
+        warn: (message, context) => base.warn(`${tag} ${message}`, context),
+        error: (message, context) => base.error(`${tag} ${message}`, context),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/logger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AAGA,wGAAwG;AACxG,MAAM,CAAC,MAAM,aAAa,GAAW;IACnC,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE;QAC1B,IAAI,OAAO;YAAE,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;;YACvC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IAC7B,CAAC;IACD,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE;QACzB,IAAI,OAAO;YAAE,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;;YACrC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAC3B,CAAC;IACD,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE;QACzB,IAAI,OAAO;YAAE,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;;YACtC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAC5B,CAAC;IACD,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE;QAC1B,IAAI,OAAO;YAAE,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;;YACvC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IAC7B,CAAC;CACF,CAAA;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,OAAe,aAAa;IAC1E,MAAM,GAAG,GAAG,IAAI,IAAI,GAAG,CAAA;IACvB,OAAO;QACL,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,OAAO,EAAE,EAAE,OAAO,CAAC;QACrE,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,OAAO,EAAE,EAAE,OAAO,CAAC;QACnE,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,OAAO,EAAE,EAAE,OAAO,CAAC;QACnE,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,OAAO,EAAE,EAAE,OAAO,CAAC;KACtE,CAAA;AACH,CAAC"}

package/dist/mcp/api-key-access.d.ts

@@ -0,0 +1,50 @@
+import type { Access, CollectionConfig } from 'payload';
+/** The slug `@payloadcms/plugin-mcp` gives its key collection. */
+export declare const MCP_API_KEYS_SLUG = "payload-mcp-api-keys";
+/** What Payload puts on `req.user`. */
+export type AccessUser = Parameters<Access>[0]['req']['user'];
+/**
+ * True when `req.user` is an MCP key document rather than a person.
+ *
+ * Only a request authenticated by Payload's REST API-key strategy against the
+ * key collection carries this principal — which Payload 3.89.0 and later no
+ * longer register. A tool call through `/api/mcp` arrives as the key's user.
+ */
+export declare function isMcpApiKeyPrincipal(user: AccessUser | undefined): boolean;
+/**
+ * A principal a site should treat as a signed-in person.
+ *
+ * Use this wherever an access rule would otherwise say `Boolean(req.user)` —
+ * which is the rule Payload's own `defaultAccess` uses. A bearer credential
+ * presented over REST is a `req.user` and is not somebody signed in.
+ */
+export declare function isSignedIn(user: AccessUser | undefined): user is NonNullable<AccessUser>;
+/** `isSignedIn` as a Payload `Access` function. */
+export declare const signedIn: Access;
+/**
+ * An `overrideApiKeyCollection` for `mcpPlugin` that makes the key collection
+ * admin-only: read, create, update, delete and unlock all answer to `isAdmin`.
+ *
+ * `isAdmin` is the site's own rule, since only the site knows what an
+ * administrator is. Whatever it says, an MCP key principal is refused first, so
+ * a key can never manage keys.
+ *
+ * It touches `access` and nothing else, so it composes with other overrides:
+ *
+ * ```ts
+ * const keysAdminOnly = mcpApiKeyAccess(isAdmin)
+ *
+ * mcpPlugin({
+ *   mcp: { tools: mcpTools.tools },
+ *   overrideApiKeyCollection: collection => {
+ *     const hardened = keysAdminOnly(collection)
+ *     return { ...hardened, admin: { ...hardened.admin, group: 'Throughline' } }
+ *   },
+ * })
+ * ```
+ *
+ * The plugin's field-level rules on the key's `user` relationship are left as
+ * shipped: a new key is bound to whoever creates it.
+ */
+export declare function mcpApiKeyAccess(isAdmin: Access): (collection: CollectionConfig) => CollectionConfig;
+//# sourceMappingURL=api-key-access.d.ts.map

package/dist/mcp/api-key-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-access.d.ts","sourceRoot":"","sources":["../../src/mcp/api-key-access.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAiCvD,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,yBAAyB,CAAA;AAEvD,uCAAuC;AACvC,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAA;AAE7D;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,CAE1E;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,IAAI,IAAI,WAAW,CAAC,UAAU,CAAC,CAExF;AAED,mDAAmD;AACnD,eAAO,MAAM,QAAQ,EAAE,MAA0C,CAAA;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,GACd,CAAC,UAAU,EAAE,gBAAgB,KAAK,gBAAgB,CAcpD"}

package/dist/mcp/api-key-access.js

@@ -0,0 +1,94 @@
+/*
+Who may manage MCP keys, and who counts as signed in. Issue #157.
+
+**The key collection.** `@payloadcms/plugin-mcp` brings `payload-mcp-api-keys`.
+Older releases declared it with no `access` block, so every operation fell
+through to Payload's `defaultAccess` — anybody signed in. Current ones scope each
+person to their own keys. Neither is the right rule for a collection of
+credentials: a key runs every tool as the person it is bound to, so who may mint,
+read, rotate and revoke one is an administrator's decision. `mcpApiKeyAccess`
+makes it one, through the plugin's `overrideApiKeyCollection`.
+
+**The principal.** The collection sets `auth.useAPIKey: true`. Before Payload
+3.89.0 that registered Payload's API-key strategy globally, so
+`Authorization: payload-mcp-api-keys API-Key <key>` was accepted on every REST
+route and put the *key document* on `req.user`, tagged
+`collection: 'payload-mcp-api-keys'`. It has no roles, so role checks denied it;
+`Boolean(req.user)` did not. On a site whose draft rule was "published, or
+anybody signed in", that served every draft to anyone holding a key, with no MCP
+involved.
+
+3.89.0 excludes that slug from the strategy loop, and the suite's peer floor is
+`^3.89.0` because of it. But one conditional in a dependency is not a control
+anybody here would notice losing, so `isSignedIn` refuses the key principal
+itself. Two things then have to fail for the hole to reopen.
+
+**This cannot affect `/api/mcp`.** That endpoint resolves a presented key on its
+own and runs the tool as the *user* the key points at, on the users collection,
+with that person's roles. Only the REST strategy's principal carries the key
+collection's slug, and that is the only principal refused here.
+*/
+/** The slug `@payloadcms/plugin-mcp` gives its key collection. */
+export const MCP_API_KEYS_SLUG = 'payload-mcp-api-keys';
+/**
+ * True when `req.user` is an MCP key document rather than a person.
+ *
+ * Only a request authenticated by Payload's REST API-key strategy against the
+ * key collection carries this principal — which Payload 3.89.0 and later no
+ * longer register. A tool call through `/api/mcp` arrives as the key's user.
+ */
+export function isMcpApiKeyPrincipal(user) {
+    return user?.collection === MCP_API_KEYS_SLUG;
+}
+/**
+ * A principal a site should treat as a signed-in person.
+ *
+ * Use this wherever an access rule would otherwise say `Boolean(req.user)` —
+ * which is the rule Payload's own `defaultAccess` uses. A bearer credential
+ * presented over REST is a `req.user` and is not somebody signed in.
+ */
+export function isSignedIn(user) {
+    return Boolean(user) && !isMcpApiKeyPrincipal(user);
+}
+/** `isSignedIn` as a Payload `Access` function. */
+export const signedIn = ({ req }) => isSignedIn(req.user);
+/**
+ * An `overrideApiKeyCollection` for `mcpPlugin` that makes the key collection
+ * admin-only: read, create, update, delete and unlock all answer to `isAdmin`.
+ *
+ * `isAdmin` is the site's own rule, since only the site knows what an
+ * administrator is. Whatever it says, an MCP key principal is refused first, so
+ * a key can never manage keys.
+ *
+ * It touches `access` and nothing else, so it composes with other overrides:
+ *
+ * ```ts
+ * const keysAdminOnly = mcpApiKeyAccess(isAdmin)
+ *
+ * mcpPlugin({
+ *   mcp: { tools: mcpTools.tools },
+ *   overrideApiKeyCollection: collection => {
+ *     const hardened = keysAdminOnly(collection)
+ *     return { ...hardened, admin: { ...hardened.admin, group: 'Throughline' } }
+ *   },
+ * })
+ * ```
+ *
+ * The plugin's field-level rules on the key's `user` relationship are left as
+ * shipped: a new key is bound to whoever creates it.
+ */
+export function mcpApiKeyAccess(isAdmin) {
+    const adminOnly = args => (isMcpApiKeyPrincipal(args.req.user) ? false : isAdmin(args));
+    return collection => ({
+        ...collection,
+        access: {
+            ...collection.access,
+            read: adminOnly,
+            create: adminOnly,
+            update: adminOnly,
+            delete: adminOnly,
+            unlock: adminOnly,
+        },
+    });
+}
+//# sourceMappingURL=api-key-access.js.map

package/dist/mcp/api-key-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-access.js","sourceRoot":"","sources":["../../src/mcp/api-key-access.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BE;AAEF,kEAAkE;AAClE,MAAM,CAAC,MAAM,iBAAiB,GAAG,sBAAsB,CAAA;AAKvD;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAA4B;IAC/D,OAAQ,IAAoD,EAAE,UAAU,KAAK,iBAAiB,CAAA;AAChG,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,IAA4B;IACrD,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAA;AACrD,CAAC;AAED,mDAAmD;AACnD,MAAM,CAAC,MAAM,QAAQ,GAAW,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAe;IAEf,MAAM,SAAS,GAAW,IAAI,CAAC,EAAE,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;IAE/F,OAAO,UAAU,CAAC,EAAE,CAAC,CAAC;QACpB,GAAG,UAAU;QACb,MAAM,EAAE;YACN,GAAG,UAAU,CAAC,MAAM;YACpB,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,SAAS;SAClB;KACF,CAAC,CAAA;AACJ,CAAC"}

package/dist/mcp/audit-context.d.ts

@@ -0,0 +1,39 @@
+import type { McpToolContext } from '../plugin-contract/index.js';
+import type { AuditActor } from '../audit/writer.js';
+import type { McpMeta } from './meta.js';
+/**
+ * The audit fields every tool derives from its request rather than from its
+ * arguments: who called, and whatever narrative context the client attached.
+ *
+ * Spread into an `AuditEventInput` alongside the fields the tool itself knows —
+ * `action`, `mcpServer`, `mcpTool`, the target.
+ */
+export interface AuditContextFields {
+    actor: AuditActor;
+    prompt?: string | undefined;
+    reasoning?: string | undefined;
+    changesSummary?: string | undefined;
+}
+/**
+ * One answer to "who did this", for every tool in every server.
+ *
+ * Ten tools built this block by hand and four of them disagreed. Three variants
+ * were only untidy — a dropped `userName`, conditional spreads, an assumption
+ * that `ctx.user` is non-null. The fourth was wrong: the component tools wrote
+ * `type: 'user'` unconditionally, so a call made with an API key and no linked
+ * user was recorded as a person. An audit log that cannot tell an agent from an
+ * editor is not an audit log, and this is the log the MCP pilot will be judged
+ * on.
+ *
+ * `type` follows the rule `publishing`'s service already used: a call carrying a
+ * user is that user's, and one without is the system's. `apiKeyName` rides along
+ * either way, because a key acting on behalf of a linked user is still worth
+ * naming.
+ *
+ * `sessionId` is passed through for the first time. The column has existed on
+ * the audit collection since it was written and nothing ever filled it; it is
+ * what lets somebody reading the log group a whole conversation's writes rather
+ * than reading them one at a time.
+ */
+export declare function auditContext(ctx: McpToolContext, meta?: McpMeta): AuditContextFields;
+//# sourceMappingURL=audit-context.d.ts.map

package/dist/mcp/audit-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-context.d.ts","sourceRoot":"","sources":["../../src/mcp/audit-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAIpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAExC;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,UAAU,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACpC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAapF"}

package/dist/mcp/audit-context.js

@@ -0,0 +1,36 @@
+/**
+ * One answer to "who did this", for every tool in every server.
+ *
+ * Ten tools built this block by hand and four of them disagreed. Three variants
+ * were only untidy — a dropped `userName`, conditional spreads, an assumption
+ * that `ctx.user` is non-null. The fourth was wrong: the component tools wrote
+ * `type: 'user'` unconditionally, so a call made with an API key and no linked
+ * user was recorded as a person. An audit log that cannot tell an agent from an
+ * editor is not an audit log, and this is the log the MCP pilot will be judged
+ * on.
+ *
+ * `type` follows the rule `publishing`'s service already used: a call carrying a
+ * user is that user's, and one without is the system's. `apiKeyName` rides along
+ * either way, because a key acting on behalf of a linked user is still worth
+ * naming.
+ *
+ * `sessionId` is passed through for the first time. The column has existed on
+ * the audit collection since it was written and nothing ever filled it; it is
+ * what lets somebody reading the log group a whole conversation's writes rather
+ * than reading them one at a time.
+ */
+export function auditContext(ctx, meta) {
+    return {
+        actor: {
+            type: ctx.user ? 'user' : 'system',
+            userId: ctx.user?.id,
+            userName: ctx.user?.name,
+            apiKeyName: ctx.apiKeyName,
+            sessionId: ctx.sessionId,
+        },
+        prompt: meta?.userPrompt,
+        reasoning: meta?.reasoning,
+        changesSummary: meta?.changesSummary,
+    };
+}
+//# sourceMappingURL=audit-context.js.map

package/dist/mcp/audit-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-context.js","sourceRoot":"","sources":["../../src/mcp/audit-context.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,YAAY,CAAC,GAAmB,EAAE,IAAc;IAC9D,OAAO;QACL,KAAK,EAAE;YACL,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ;YAClC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE;YACpB,QAAQ,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI;YACxB,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,SAAS,EAAE,GAAG,CAAC,SAAS;SACzB;QACD,MAAM,EAAE,IAAI,EAAE,UAAU;QACxB,SAAS,EAAE,IAAI,EAAE,SAAS;QAC1B,cAAc,EAAE,IAAI,EAAE,cAAc;KACrC,CAAA;AACH,CAAC"}

package/dist/mcp/audit-server.d.ts

@@ -0,0 +1,13 @@
+import { type AuditMcpServer } from '../audit/types.js';
+/**
+ * The audit log's name for a collector server name, or `undefined` if there
+ * isn't one.
+ *
+ * `undefined` rather than a fallback: a row attributed to the wrong server is
+ * worse than a boot that stops and says which two lists to reconcile. The
+ * caller is `collector.add`, which throws — see `mcpServerRefusal`.
+ */
+export declare function auditServerFor(serverName: string): AuditMcpServer | undefined;
+/** The message `collector.add` throws with when a server has no audit name. */
+export declare function mcpServerRefusal(serverName: string): string;
+//# sourceMappingURL=audit-server.d.ts.map

package/dist/mcp/audit-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-server.d.ts","sourceRoot":"","sources":["../../src/mcp/audit-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAwC1E;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAW7E;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAS3D"}