@forumone/throughline-core 0.0.1 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @forumone/throughline-core
+
+## 0.2.1
+
+### Patch Changes
+
+- a4b5108: Initial release of the forms package. Wraps Payload's Form Builder plugin with the Throughline policy layer: mandatory privacy notice, consent enforcement (server-side), honeypot spam protection, Postgres-backed per-IP rate limiting, a destination allowlist (the security perimeter), and submitter confirmations. Six MCP tools (`list_allowed_destinations`, `validate_form`, `create_form`, `update_form_fields`, `update_form_destinations`, `get_form_submissions`) and four Inngest functions (`form-fan-out`, `form-email-destination`, `form-webhook-destination`, `form-submitter-confirmation`) drive the conversational flow and the async destination delivery. Includes `FormSubmissionEmail` and `SubmitterConfirmationEmail` React Email templates. Allowlist enforcement runs at three layers (MCP tool, collection beforeChange hook, fan-out worker) so prompt injection or admin direct-API writes can't bypass it. IPs are HMAC-hashed; raw IPs are never persisted. Adds `form.updated` to the core audit-action taxonomy used by the two update tools.
+
+## 0.2.0
+
+### Minor Changes
+
+- [#14](https://github.com/forumone/throughline/pull/14) [`5329d97`](https://github.com/forumone/throughline/commit/5329d97363099a54bcae2516a8aa9eff8cd735fc) Thanks [@briangraves](https://github.com/briangraves)! - Initial release. Provides the audit log (collection + fire-and-forget writer + plugin), MCP authentication (bearer-token authenticator + API-keys collection with SHA-256 hashed keys), event taxonomy and Inngest client factory, MCP handler infrastructure (JSON-RPC over HTTP) with the `_meta` helper for prompt/reasoning capture, standard env-var conventions, a default logger, and shared utilities. Every server package in the framework depends on this.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forum One Communications Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,121 @@
 # @forumone/throughline-core
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+The shared plumbing every Throughline server package depends on. Drop it into a Payload + Next.js app and you get the audit log, MCP authentication and request handling, the framework event taxonomy + Inngest client factory, env-var conventions, a logger, and a handful of small utilities.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+## What's inside
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+| Subsystem | Subpath | Role |
+|---|---|---|
+| Audit | `./audit` | `auditPlugin`, `createAuditCollection`, `createAuditWriter`, `getAuditWriter`, `AUDIT_ACTIONS`, `AUDIT_MCP_SERVERS` |
+| Auth | `./auth` | `createApiKeysCollection`, `createBearerTokenAuthenticator`, `generateApiKey`, `sha256Hex` |
+| Events | `./events` | `createInngestClient`, `CoreEvents`, `FrameworkEvents` (module-augmentation seam) |
+| MCP | `./mcp` | `createMcpHandler`, `McpMetaSchema`, `withMeta` |
+| Env | `./env` | `ENV_VARS`, `validateBaseEnv`, `requireEnv`, `optionalEnv` |
+| Logger | (main) | `defaultLogger`, `createNamedLogger` |
+| Utils | (main) | `shallowDiff`, `generateId` |
 
-## Purpose
+The main entry re-exports everything; the subpath exports keep bundles smaller for consumers who only need one slice.
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@forumone/throughline-core`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Installation
 
-## What is OIDC Trusted Publishing?
+```bash
+pnpm add @forumone/throughline-core
+```
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+Peers: `payload@^3.0.0` and `inngest@^4.0.0`.
 
-## Setup Instructions
+## The audit log
 
-To properly configure OIDC trusted publishing for this package:
+Every consequential action in the framework writes to a single immutable Payload collection. Plugins do not write directly — they call the writer attached to the Payload instance by `auditPlugin`.
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+```ts
+import { auditPlugin, createInngestClient } from '@forumone/throughline-core'
+import { buildConfig } from 'payload'
 
-## DO NOT USE THIS PACKAGE
+const inngest = createInngestClient({ id: 'my-site' })
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+export default buildConfig({
+  // collections, db, secret...
+  plugins: [
+    auditPlugin({ inngest }),
+    // your other Throughline plugins
+  ],
+})
+```
 
-## More Information
+In a downstream plugin's `onInit`:
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```ts
+import { getAuditWriter } from '@forumone/throughline-core'
 
----
+onInit: async (payload) => {
+  const writer = getAuditWriter(payload)
+  await writer({
+    actor: { type: 'user', userId: 'u1' },
+    action: 'publishing.publish',
+    mcpServer: 'publishing',
+    mcpTool: 'publishing.publish',
+    targetCollection: 'pages',
+    targetId: 'p1',
+    targetTitle: 'Homepage',
+  })
+}
+```
 
-**Maintained for OIDC setup purposes only**
+The writer is **fire-and-forget**: failures log but never throw. Audit failures must never break the originating action.
+
+## MCP authentication
+
+`createApiKeysCollection` adds a Payload collection that stores SHA-256 hashes of bearer tokens (the raw key is shown to the operator once on create, then never persisted). `createBearerTokenAuthenticator` validates incoming requests against that collection.
+
+```ts
+import { createApiKeysCollection, createBearerTokenAuthenticator, createMcpHandler } from '@forumone/throughline-core'
+import type { Payload } from 'payload'
+
+// In your Payload config:
+collections: [createApiKeysCollection({ usersSlug: 'users' })],
+
+// In your MCP route:
+const authenticator = createBearerTokenAuthenticator({ payload })
+const handleMcp = createMcpHandler({
+  payload,
+  serverName: 'publishing',
+  tools: [/* McpToolDefinition[] */],
+  authenticator,
+})
+
+// Next.js app router:
+export const POST = (req: Request) => handleMcp(req)
+```
+
+## Events
+
+`CoreEvents` enumerates the events the framework fires today. Server packages add their own via TypeScript module augmentation:
+
+```ts
+declare module '@forumone/throughline-core/events' {
+  interface FrameworkEvents {
+    'approval/decided': {
+      data: { approvalId: string; decision: 'granted' | 'declined' }
+    }
+  }
+}
+```
+
+After augmentation, `inngest.send({ name: 'approval/decided', data: { ... } })` is type-checked everywhere.
+
+## Env vars
+
+`ENV_VARS` is the canonical list of names the framework reads. Plugins reach into `process.env` through these constants rather than hard-coded strings:
+
+```ts
+import { ENV_VARS, requireEnv, validateBaseEnv } from '@forumone/throughline-core'
+
+validateBaseEnv() // throws on missing PAYLOAD_SECRET / DATABASE_URI / NEXT_PUBLIC_SERVER_URL
+
+const apiKey = requireEnv(ENV_VARS.PUBLISHING_SERVER_API_KEY)
+```
+
+## Why all of this lives in one package
+
+Server packages (Component, Publishing, Approvals, Audit Query, Forms, Integrations) all depend on the same audit log, the same authentication pattern, and the same event taxonomy. Splitting these across packages would create circular dependencies — every server package would need the audit writer, and an audit-only package would need to know about every server. Consolidating the plumbing here keeps the dependency graph one-way: core → server packages → client app.

package/dist/audit/collection.d.ts

@@ -0,0 +1,19 @@
+import type { Access, CollectionConfig } from 'payload';
+export interface AuditCollectionOptions {
+    /** Override the collection slug. Default: `'audit-events'`. */
+    slug?: string;
+    /**
+     * Read access function. Receives the standard Payload access args.
+     * Defaults to admin/editor roles.
+     */
+    readAccess?: Access;
+}
+export declare const DEFAULT_AUDIT_SLUG = "audit-events";
+/**
+ * Builds the audit-events collection config. The collection is read-only
+ * from outside the writer: `create`, `update`, and `delete` are denied
+ * for all callers; the writer uses Payload's local API which bypasses
+ * these checks.
+ */
+export declare function createAuditCollection(options?: AuditCollectionOptions): CollectionConfig;
+//# sourceMappingURL=collection.d.ts.map

package/dist/audit/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../../src/audit/collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAGvD,MAAM,WAAW,sBAAsB;IACrC,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,eAAO,MAAM,kBAAkB,iBAAiB,CAAA;AAOhD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,sBAA2B,GAAG,gBAAgB,CA+F5F"}

package/dist/audit/collection.js

@@ -0,0 +1,107 @@
+import { AUDIT_ACTIONS, AUDIT_MCP_SERVERS } from './types.js';
+export const DEFAULT_AUDIT_SLUG = 'audit-events';
+const defaultReadAccess = ({ req }) => {
+    const roles = req.user?.['roles'] ?? [];
+    return roles.includes('admin') || roles.includes('editor');
+};
+/**
+ * Builds the audit-events collection config. The collection is read-only
+ * from outside the writer: `create`, `update`, and `delete` are denied
+ * for all callers; the writer uses Payload's local API which bypasses
+ * these checks.
+ */
+export function createAuditCollection(options = {}) {
+    const slug = options.slug ?? DEFAULT_AUDIT_SLUG;
+    return {
+        slug,
+        admin: {
+            useAsTitle: 'summary',
+            defaultColumns: ['createdAt', 'actor', 'action', 'targetCollection', 'targetId'],
+            description: 'Immutable record of every consequential action in the system. Read-only through the admin.',
+        },
+        access: {
+            read: options.readAccess ?? defaultReadAccess,
+            create: () => false,
+            update: () => false,
+            delete: () => false,
+        },
+        fields: [
+            {
+                name: 'createdAt',
+                type: 'date',
+                required: true,
+                defaultValue: () => new Date().toISOString(),
+                admin: { position: 'sidebar', readOnly: true },
+            },
+            {
+                name: 'actor',
+                type: 'group',
+                fields: [
+                    {
+                        name: 'type',
+                        type: 'select',
+                        required: true,
+                        options: [
+                            { label: 'User', value: 'user' },
+                            { label: 'System', value: 'system' },
+                            { label: 'Integration', value: 'integration' },
+                        ],
+                    },
+                    { name: 'userId', type: 'text' },
+                    { name: 'userName', type: 'text' },
+                    { name: 'apiKeyName', type: 'text' },
+                    { name: 'apiKeyId', type: 'text' },
+                    { name: 'sessionId', type: 'text' },
+                ],
+            },
+            {
+                name: 'action',
+                type: 'select',
+                required: true,
+                options: AUDIT_ACTIONS.map((value) => ({ label: value, value })),
+            },
+            {
+                name: 'mcpServer',
+                type: 'select',
+                required: true,
+                options: AUDIT_MCP_SERVERS.map((value) => ({ label: value, value })),
+            },
+            { name: 'mcpTool', type: 'text', required: true },
+            { name: 'targetCollection', type: 'text' },
+            { name: 'targetId', type: 'text' },
+            { name: 'targetTitle', type: 'text' },
+            {
+                name: 'prompt',
+                type: 'textarea',
+                admin: { description: "The user's natural-language prompt, if surfaced via _meta." },
+            },
+            {
+                name: 'reasoning',
+                type: 'textarea',
+                admin: { description: "Claude's reasoning, if surfaced via _meta." },
+            },
+            { name: 'changesSummary', type: 'textarea' },
+            { name: 'summary', type: 'text', required: true },
+            {
+                name: 'diff',
+                type: 'json',
+                admin: {
+                    description: 'Before/after fields for update operations; null for reads.',
+                },
+            },
+            { name: 'success', type: 'checkbox', defaultValue: true },
+            { name: 'errorMessage', type: 'text' },
+            { name: 'approvalRequestId', type: 'text' },
+            { name: 'integrationId', type: 'text' },
+        ],
+        indexes: [
+            { fields: ['createdAt'] },
+            { fields: ['actor.userId', 'createdAt'] },
+            { fields: ['targetCollection', 'targetId', 'createdAt'] },
+            { fields: ['action', 'createdAt'] },
+            { fields: ['mcpServer', 'createdAt'] },
+        ],
+        timestamps: false,
+    };
+}
+//# sourceMappingURL=collection.js.map

package/dist/audit/collection.js.map

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

package/dist/audit/index.d.ts

@@ -0,0 +1,9 @@
+export { auditPlugin, getAuditWriter } from './plugin.js';
+export type { AuditPluginOptions } from './plugin.js';
+export { createAuditCollection, DEFAULT_AUDIT_SLUG } from './collection.js';
+export type { AuditCollectionOptions } from './collection.js';
+export { createAuditWriter } from './writer.js';
+export type { AuditWriter, AuditWriterOptions, AuditEventInput, AuditActor } from './writer.js';
+export { AUDIT_ACTIONS, AUDIT_MCP_SERVERS } from './types.js';
+export type { AuditAction, AuditMcpServer } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACzD,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAErD,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAC3E,YAAY,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAE7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC/C,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE/F,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC7D,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}

package/dist/audit/index.js

@@ -0,0 +1,5 @@
+export { auditPlugin, getAuditWriter } from './plugin.js';
+export { createAuditCollection, DEFAULT_AUDIT_SLUG } from './collection.js';
+export { createAuditWriter } from './writer.js';
+export { AUDIT_ACTIONS, AUDIT_MCP_SERVERS } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/audit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAGzD,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAG3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAG/C,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA"}

package/dist/audit/plugin.d.ts

@@ -0,0 +1,20 @@
+import type { Inngest } from 'inngest';
+import { type BaseCorePluginOptions, type CorePlugin } from '@forumone/throughline-plugin-contract';
+import { type AuditCollectionOptions } from './collection.js';
+import { type AuditWriter } from './writer.js';
+export interface AuditPluginOptions extends BaseCorePluginOptions, AuditCollectionOptions {
+    /**
+     * Inngest client used to fire `audit/event.recorded` events. If omitted,
+     * audit writes still persist; downstream subscribers simply won't receive
+     * events.
+     */
+    inngest?: Inngest;
+}
+export declare const auditPlugin: CorePlugin<AuditPluginOptions>;
+/**
+ * Retrieves the audit writer attached to a Payload instance by `auditPlugin`.
+ * Plugins that depend on auditing call this in their own `onInit` to record
+ * events without importing this package's writer factory directly.
+ */
+export declare function getAuditWriter(payload: object): AuditWriter;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/audit/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/audit/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EAEhB,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EAAyB,KAAK,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AACpF,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAA;AAOjE,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB,EAAE,sBAAsB;IACvF;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,eAAO,MAAM,WAAW,EAAE,UAAU,CAAC,kBAAkB,CA8BtD,CAAA;AAWD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAQ3D"}

package/dist/audit/plugin.js

@@ -0,0 +1,55 @@
+import { getPluginRegistry, } from '@forumone/throughline-plugin-contract';
+import { createAuditCollection } from './collection.js';
+import { createAuditWriter } from './writer.js';
+import { defaultLogger } from '../logger/index.js';
+const AUDIT_PLUGIN_ID = '@forumone/throughline-core/audit';
+const AUDIT_PLUGIN_VERSION = '0.1.0';
+const AUDIT_WRITER_SYMBOL = Symbol.for('@forumone/throughline/audit-writer');
+export const auditPlugin = (options) => (incomingConfig) => {
+    if (options.enabled === false)
+        return incomingConfig;
+    const auditCollection = createAuditCollection(options);
+    return {
+        ...incomingConfig,
+        collections: [...(incomingConfig.collections ?? []), auditCollection],
+        onInit: async (payload) => {
+            if (incomingConfig.onInit) {
+                await incomingConfig.onInit(payload);
+            }
+            const writer = createAuditWriter({
+                payload,
+                inngest: options.inngest,
+                collectionSlug: options.slug,
+                logger: options.logger ?? defaultLogger,
+            });
+            attachAuditWriter(payload, writer);
+            const registry = getPluginRegistry(payload);
+            registry.register({
+                id: AUDIT_PLUGIN_ID,
+                version: AUDIT_PLUGIN_VERSION,
+                capabilities: ['audit-log', 'audit-write'],
+            });
+        },
+    };
+};
+function attachAuditWriter(target, writer) {
+    Object.defineProperty(target, AUDIT_WRITER_SYMBOL, {
+        value: writer,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+}
+/**
+ * Retrieves the audit writer attached to a Payload instance by `auditPlugin`.
+ * Plugins that depend on auditing call this in their own `onInit` to record
+ * events without importing this package's writer factory directly.
+ */
+export function getAuditWriter(payload) {
+    const writer = payload[AUDIT_WRITER_SYMBOL];
+    if (!writer) {
+        throw new Error('Audit writer not found. Ensure `auditPlugin` is registered in your Payload config before any plugin that depends on it.');
+    }
+    return writer;
+}
+//# sourceMappingURL=plugin.js.map

package/dist/audit/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/audit/plugin.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,iBAAiB,GAClB,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EAAE,qBAAqB,EAA+B,MAAM,iBAAiB,CAAA;AACpF,OAAO,EAAE,iBAAiB,EAAoB,MAAM,aAAa,CAAA;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,MAAM,eAAe,GAAG,kCAAkC,CAAA;AAC1D,MAAM,oBAAoB,GAAG,OAAO,CAAA;AACpC,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAA;AAW5E,MAAM,CAAC,MAAM,WAAW,GAAmC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,cAAc,EAAE,EAAE;IACzF,IAAI,OAAO,CAAC,OAAO,KAAK,KAAK;QAAE,OAAO,cAAc,CAAA;IAEpD,MAAM,eAAe,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAA;IAEtD,OAAO;QACL,GAAG,cAAc;QACjB,WAAW,EAAE,CAAC,GAAG,CAAC,cAAc,CAAC,WAAW,IAAI,EAAE,CAAC,EAAE,eAAe,CAAC;QACrE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACxB,IAAI,cAAc,CAAC,MAAM,EAAE,CAAC;gBAC1B,MAAM,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;YACtC,CAAC;YAED,MAAM,MAAM,GAAG,iBAAiB,CAAC;gBAC/B,OAAO;gBACP,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,cAAc,EAAE,OAAO,CAAC,IAAI;gBAC5B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,aAAa;aACxC,CAAC,CAAA;YAEF,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;YAElC,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAA;YAC3C,QAAQ,CAAC,QAAQ,CAAC;gBAChB,EAAE,EAAE,eAAe;gBACnB,OAAO,EAAE,oBAAoB;gBAC7B,YAAY,EAAE,CAAC,WAAW,EAAE,aAAa,CAAC;aAC3C,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC,CAAA;AAED,SAAS,iBAAiB,CAAC,MAAc,EAAE,MAAmB;IAC5D,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,mBAAmB,EAAE;QACjD,KAAK,EAAE,MAAM;QACb,UAAU,EAAE,KAAK;QACjB,QAAQ,EAAE,KAAK;QACf,YAAY,EAAE,KAAK;KACpB,CAAC,CAAA;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,MAAM,MAAM,GAAI,OAAmC,CAAC,mBAAmB,CAAC,CAAA;IACxE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,yHAAyH,CAC1H,CAAA;IACH,CAAC;IACD,OAAO,MAAqB,CAAA;AAC9B,CAAC"}

package/dist/audit/types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Canonical action names for the audit log. Every server package picks
+ * actions from this list rather than introducing free-form strings, so
+ * audit queries (C8) can build on a known taxonomy.
+ */
+export declare const AUDIT_ACTIONS: readonly ["content.find", "content.create", "content.update", "content.delete", "design.list", "design.suggest", "design.validate", "design.get_contract", "design.find_anti_pattern", "publishing.draft", "publishing.publish", "publishing.unpublish", "publishing.schedule", "publishing.rollback", "approval.requested", "approval.granted", "approval.declined", "approval.changes_requested", "approval.expired", "approval.discussed", "form.created", "form.updated", "form.submission_received", "integration.synced", "integration.failed", "system.error", "system.healthcheck"];
+export type AuditAction = (typeof AUDIT_ACTIONS)[number];
+/** MCP server identifiers. Keep in sync with the planned server packages. */
+export declare const AUDIT_MCP_SERVERS: readonly ["payload", "component", "publishing", "approvals", "audit", "forms", "integrations"];
+export type AuditMcpServer = (typeof AUDIT_MCP_SERVERS)[number];
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/audit/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,aAAa,6jBA4BhB,CAAA;AAEV,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AAExD,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,gGAQpB,CAAA;AAEV,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAA"}

package/dist/audit/types.js

@@ -0,0 +1,45 @@
+/**
+ * Canonical action names for the audit log. Every server package picks
+ * actions from this list rather than introducing free-form strings, so
+ * audit queries (C8) can build on a known taxonomy.
+ */
+export const AUDIT_ACTIONS = [
+    'content.find',
+    'content.create',
+    'content.update',
+    'content.delete',
+    'design.list',
+    'design.suggest',
+    'design.validate',
+    'design.get_contract',
+    'design.find_anti_pattern',
+    'publishing.draft',
+    'publishing.publish',
+    'publishing.unpublish',
+    'publishing.schedule',
+    'publishing.rollback',
+    'approval.requested',
+    'approval.granted',
+    'approval.declined',
+    'approval.changes_requested',
+    'approval.expired',
+    'approval.discussed',
+    'form.created',
+    'form.updated',
+    'form.submission_received',
+    'integration.synced',
+    'integration.failed',
+    'system.error',
+    'system.healthcheck',
+];
+/** MCP server identifiers. Keep in sync with the planned server packages. */
+export const AUDIT_MCP_SERVERS = [
+    'payload',
+    'component',
+    'publishing',
+    'approvals',
+    'audit',
+    'forms',
+    'integrations',
+];
+//# sourceMappingURL=types.js.map

package/dist/audit/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/audit/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,cAAc;IACd,gBAAgB;IAChB,gBAAgB;IAChB,gBAAgB;IAChB,aAAa;IACb,gBAAgB;IAChB,iBAAiB;IACjB,qBAAqB;IACrB,0BAA0B;IAC1B,kBAAkB;IAClB,oBAAoB;IACpB,sBAAsB;IACtB,qBAAqB;IACrB,qBAAqB;IACrB,oBAAoB;IACpB,kBAAkB;IAClB,mBAAmB;IACnB,4BAA4B;IAC5B,kBAAkB;IAClB,oBAAoB;IACpB,cAAc;IACd,cAAc;IACd,0BAA0B;IAC1B,oBAAoB;IACpB,oBAAoB;IACpB,cAAc;IACd,oBAAoB;CACZ,CAAA;AAIV,6EAA6E;AAC7E,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,SAAS;IACT,WAAW;IACX,YAAY;IACZ,WAAW;IACX,OAAO;IACP,OAAO;IACP,cAAc;CACN,CAAA"}

package/dist/audit/writer.d.ts

@@ -0,0 +1,50 @@
+import type { Inngest } from 'inngest';
+import type { Payload } from 'payload';
+import type { Logger } from '@forumone/throughline-plugin-contract';
+import type { AuditAction, AuditMcpServer } from './types.js';
+export interface AuditActor {
+    type: 'user' | 'system' | 'integration';
+    userId?: string | undefined;
+    userName?: string | undefined;
+    apiKeyName?: string | undefined;
+    apiKeyId?: string | undefined;
+    sessionId?: string | undefined;
+}
+export interface AuditEventInput {
+    actor: AuditActor;
+    action: AuditAction;
+    mcpServer: AuditMcpServer;
+    mcpTool: string;
+    targetCollection?: string | undefined;
+    targetId?: string | undefined;
+    targetTitle?: string | undefined;
+    prompt?: string | undefined;
+    reasoning?: string | undefined;
+    changesSummary?: string | undefined;
+    summary?: string | undefined;
+    diff?: Record<string, {
+        before: unknown;
+        after: unknown;
+    }> | null | undefined;
+    success?: boolean | undefined;
+    errorMessage?: string | undefined;
+    approvalRequestId?: string | undefined;
+    integrationId?: string | undefined;
+}
+export interface AuditWriterOptions {
+    payload: Payload;
+    inngest?: Inngest | undefined;
+    collectionSlug?: string | undefined;
+    logger?: Logger | undefined;
+}
+export type AuditWriter = (event: AuditEventInput) => Promise<void>;
+/**
+ * Returns a fire-and-forget audit writer. The writer never throws — failures
+ * log via `options.logger` (or `console`). Audit failures must not break
+ * the originating action.
+ *
+ * If `inngest` is provided the writer also fires an `audit/event.recorded`
+ * event so subscribers (email, integrations, healthchecks) can react.
+ */
+export declare function createAuditWriter(options: AuditWriterOptions): AuditWriter;
+//# sourceMappingURL=writer.d.ts.map

package/dist/audit/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../src/audit/writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uCAAuC,CAAA;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE7D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,aAAa,CAAA;IACvC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,CAAA;IACjB,MAAM,EAAE,WAAW,CAAA;IACnB,SAAS,EAAE,cAAc,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,GAAG,IAAI,GAAG,SAAS,CAAA;IAC7E,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACnC;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAEnE;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CA0D1E"}