@simmalugnt-se/payload-editor-assistant 0.1.0

package/dist/domain/decide.js

@@ -0,0 +1,162 @@
+import { compileOperations } from "../form/compile.js";
+import { hashFormRevision } from "../form/hash.js";
+import { isFormOperation } from "../form/operations.js";
+import { finalizeCompiled } from "../form/shape.js";
+import { DEFAULT_APPROVAL_SLUG } from "../package-name.js";
+import { entityFields } from "../schema/discover.js";
+import { hasCapability, resolveAllowlist } from "./allowlist.js";
+import { writeAudit } from "./audit.js";
+import { localApi } from "./local-api.js";
+import { verifyDocumentRelations } from "./relations.js";
+export async function decideChange(req, options, input) {
+    const actor = String(req.user?.id);
+    const found = await localApi(req).findByID({
+        collection: DEFAULT_APPROVAL_SLUG,
+        id: input.approvalId,
+        req,
+        overrideAccess: false,
+        user: req.user,
+        depth: 0,
+    });
+    const record = found;
+    if (!record || record.actor !== actor || record.nonce !== input.nonce) {
+        return { ok: false, error: "tool_denied", message: "Approval is not valid." };
+    }
+    if (record.status !== "proposed") {
+        return { ok: false, error: "tool_denied", message: "Approval is no longer usable." };
+    }
+    if (new Date(record.expiresAt).getTime() <= Date.now()) {
+        await consume(req, record.id, "expired");
+        return { ok: false, error: "stale_context", message: "Approval expired." };
+    }
+    if (input.action === "reject") {
+        await consume(req, record.id, "rejected");
+        await writeAudit(req, options, {
+            capability: record.capability,
+            risk: "approval",
+            outcome: "rejected",
+            approvalId: String(record.id),
+            nonceId: record.nonce.slice(0, 8),
+            locale: record.locale,
+        });
+        return { ok: true, rejected: true };
+    }
+    const target = {
+        collection: record.targetCollection ?? undefined,
+        global: record.targetGlobal ?? undefined,
+    };
+    const resolved = resolveAllowlist(options, target);
+    if (!resolved || !hasCapability(resolved.allowlist, record.capability)) {
+        await consume(req, record.id, "failed");
+        return { ok: false, error: "tool_denied", message: "Capability is not allowlisted." };
+    }
+    if (record.capability === "form.propose" && identityMismatch(record, input)) {
+        await consume(req, record.id, "failed");
+        return { ok: false, error: "stale_context", message: "The open document changed." };
+    }
+    if (!Array.isArray(record.operations) || !record.operations.every(isFormOperation)) {
+        await consume(req, record.id, "failed");
+        return { ok: false, error: "tool_denied", message: "Stored operations are invalid." };
+    }
+    const operations = record.operations;
+    const current = record.capability === "form.propose" ? (input.formData ?? {}) : {};
+    if (record.capability === "form.propose") {
+        const currentHash = await hashFormRevision(current);
+        if (currentHash !== record.formRevision) {
+            await consume(req, record.id, "failed");
+            return { ok: false, error: "stale_context", message: "The form changed before approval." };
+        }
+    }
+    const compiled = compileOperations(current, operations, {
+        allowlist: resolved.allowlist.fields,
+        denyFields: options.denyFields,
+    });
+    if (!compiled.ok) {
+        await consume(req, record.id, "failed");
+        return { ok: false, error: "tool_denied", message: compiled.error };
+    }
+    const canonicalHash = await hashFormRevision(operations);
+    if (canonicalHash !== record.canonicalHash) {
+        await consume(req, record.id, "failed");
+        return { ok: false, error: "tool_denied", message: "Proposal hash mismatch." };
+    }
+    const fields = entityFields(req, options, {
+        collection: record.targetCollection ?? undefined,
+        global: record.targetGlobal ?? undefined,
+    });
+    const finalized = finalizeCompiled(compiled.data, fields);
+    if (!finalized.ok) {
+        await consume(req, record.id, "failed");
+        return { ok: false, error: "tool_denied", message: finalized.error };
+    }
+    const relations = await verifyDocumentRelations(req, fields, finalized.data);
+    if (!relations.ok) {
+        await consume(req, record.id, "failed");
+        return { ok: false, error: "tool_denied", message: relations.message };
+    }
+    if (record.capability === "draft.create") {
+        if (!record.targetCollection) {
+            await consume(req, record.id, "failed");
+            return { ok: false, error: "tool_denied", message: "Draft create requires a collection." };
+        }
+        const created = await localApi(req).create({
+            collection: record.targetCollection,
+            data: { ...finalized.data, _status: "draft" },
+            draft: true,
+            locale: record.locale,
+            req,
+            user: req.user,
+            overrideAccess: false,
+            overrideLock: false,
+        });
+        await consume(req, record.id, "executed");
+        await writeAudit(req, options, {
+            capability: "draft.create",
+            risk: "approval",
+            outcome: "executed",
+            targetCollection: record.targetCollection,
+            documentId: String(created.id),
+            locale: record.locale,
+            approvalId: String(record.id),
+            nonceId: record.nonce.slice(0, 8),
+            canonicalHash,
+        });
+        return {
+            ok: true,
+            capability: "draft.create",
+            documentId: String(created.id),
+            collection: record.targetCollection,
+        };
+    }
+    await consume(req, record.id, "executed");
+    await writeAudit(req, options, {
+        capability: "form.propose",
+        risk: "approval",
+        outcome: "executed",
+        targetCollection: record.targetCollection ?? undefined,
+        targetGlobal: record.targetGlobal ?? undefined,
+        documentId: record.documentId ?? undefined,
+        locale: record.locale,
+        approvalId: String(record.id),
+        nonceId: record.nonce.slice(0, 8),
+        canonicalHash,
+        baseRevision: record.formRevision ?? undefined,
+    });
+    return { ok: true, capability: "form.propose", patchedData: finalized.data };
+}
+function identityMismatch(record, input) {
+    return ((input.collection ?? "") !== (record.targetCollection ?? "") ||
+        (input.global ?? "") !== (record.targetGlobal ?? "") ||
+        String(input.documentId ?? "") !== (record.documentId ?? "") ||
+        input.locale !== record.locale);
+}
+async function consume(req, id, status) {
+    await localApi(req).update({
+        collection: DEFAULT_APPROVAL_SLUG,
+        id,
+        data: { status },
+        req,
+        user: req.user,
+        overrideAccess: false,
+    });
+}

package/dist/domain/guard.d.ts

@@ -0,0 +1,13 @@
+import type { PayloadRequest } from "payload";
+import type { ValidatedEditorAssistantOptions } from "../config/validate.ts";
+export type GuardFailure = {
+    ok: false;
+    status: number;
+    error: "unauthorized" | "unavailable" | "rate_limited";
+};
+export type GuardSuccess = {
+    ok: true;
+    actor: string;
+};
+export declare function guardMutationRequest(req: PayloadRequest, options: ValidatedEditorAssistantOptions): Promise<GuardFailure | GuardSuccess>;
+export declare function readJsonBody<T>(req: PayloadRequest): Promise<T | null>;

package/dist/domain/guard.js

@@ -0,0 +1,29 @@
+import { verifyCsrf, verifyOrigin } from "../endpoints/csrf.js";
+import { consumeRateLimit } from "../runtime/rate-limit.js";
+export async function guardMutationRequest(req, options) {
+    if (!req.user) {
+        return { ok: false, status: 401, error: "unauthorized" };
+    }
+    if (!verifyOrigin(req, options.trustedOrigins) || !verifyCsrf(req)) {
+        return { ok: false, status: 403, error: "unauthorized" };
+    }
+    if (options.enabled && !(await options.enabled({ userId: req.user.id }))) {
+        return { ok: false, status: 403, error: "unavailable" };
+    }
+    const actor = String(req.user.id);
+    if (!consumeRateLimit(actor)) {
+        return { ok: false, status: 429, error: "rate_limited" };
+    }
+    return { ok: true, actor };
+}
+export async function readJsonBody(req) {
+    if (typeof req.json !== "function") {
+        return null;
+    }
+    try {
+        return (await req.json());
+    }
+    catch {
+        return null;
+    }
+}

package/dist/domain/local-api.d.ts

@@ -0,0 +1,16 @@
+import type { PayloadRequest } from "payload";
+export type LooseDoc = Record<string, unknown> & {
+    id?: string | number;
+};
+type LoosePayload = {
+    config: PayloadRequest["payload"]["config"];
+    find: (args: Record<string, unknown>) => Promise<{
+        docs: LooseDoc[];
+    }>;
+    findByID: (args: Record<string, unknown>) => Promise<LooseDoc>;
+    findGlobal: (args: Record<string, unknown>) => Promise<LooseDoc>;
+    create: (args: Record<string, unknown>) => Promise<LooseDoc>;
+    update: (args: Record<string, unknown>) => Promise<LooseDoc>;
+};
+export declare function localApi(req: PayloadRequest): LoosePayload;
+export {};

package/dist/domain/local-api.js

@@ -0,0 +1,3 @@
+export function localApi(req) {
+    return req.payload;
+}

package/dist/domain/navigate.d.ts

@@ -0,0 +1,25 @@
+import type { PayloadRequest } from "payload";
+import type { ValidatedEditorAssistantOptions } from "../config/validate.ts";
+export type NavigateResult = {
+    ok: true;
+    href: string;
+    label: string;
+} | {
+    ok: true;
+    candidates: Array<{
+        href: string;
+        label: string;
+    }>;
+} | {
+    ok: false;
+    error: string;
+    message: string;
+};
+export declare function navigateAdmin(req: PayloadRequest, options: ValidatedEditorAssistantOptions, input: {
+    collection?: string;
+    global?: string;
+    documentId?: string | number;
+    query?: string;
+    locale: string;
+}): Promise<NavigateResult>;
+export declare function canNavigate(options: ValidatedEditorAssistantOptions): boolean;

package/dist/domain/navigate.js

@@ -0,0 +1,85 @@
+import { findCollectionConfig, findGlobalConfig } from "../schema/discover.js";
+import { resolveAllowlist } from "./allowlist.js";
+import { findContent } from "./content.js";
+import { localApi } from "./local-api.js";
+export async function navigateAdmin(req, options, input) {
+    if (Object.keys(options.collections).length + Object.keys(options.globals).length === 0) {
+        return { ok: false, error: "tool_denied", message: "Nothing is allowlisted." };
+    }
+    const admin = req.payload.config.routes?.admin ?? "/admin";
+    if (input.global) {
+        if (!options.globals[input.global] || !findGlobalConfig(req, input.global)) {
+            return { ok: false, error: "tool_denied", message: "Global is not allowlisted." };
+        }
+        return {
+            ok: true,
+            href: `${admin}/globals/${input.global}`,
+            label: input.global,
+        };
+    }
+    if (input.collection && input.documentId !== undefined) {
+        const resolved = resolveAllowlist(options, { collection: input.collection });
+        if (!resolved) {
+            return { ok: false, error: "tool_denied", message: "Collection is not allowlisted." };
+        }
+        try {
+            const doc = await localApi(req).findByID({
+                collection: input.collection,
+                id: input.documentId,
+                depth: 0,
+                locale: input.locale,
+                draft: true,
+                req,
+                user: req.user,
+                overrideAccess: false,
+            });
+            return {
+                ok: true,
+                href: `${admin}/collections/${input.collection}/${input.documentId}`,
+                label: String(doc.title ?? doc.slug ?? input.documentId),
+            };
+        }
+        catch {
+            return { ok: false, error: "tool_denied", message: "Document is not accessible." };
+        }
+    }
+    if (input.collection && !input.query) {
+        if (!options.collections[input.collection] || !findCollectionConfig(req, input.collection)) {
+            return { ok: false, error: "tool_denied", message: "Collection is not allowlisted." };
+        }
+        return {
+            ok: true,
+            href: `${admin}/collections/${input.collection}`,
+            label: input.collection,
+        };
+    }
+    if (input.query) {
+        const found = await findContent(req, options, {
+            collection: input.collection,
+            query: input.query,
+            locale: input.locale,
+        });
+        if (!found.ok) {
+            return found;
+        }
+        const candidates = found.results.map((result) => ({
+            href: `${admin}/collections/${String(result.collection)}/${String(result.id)}`,
+            label: String(result.title ?? result.slug ?? result.id),
+        }));
+        if (candidates.length === 1) {
+            return { ok: true, href: candidates[0].href, label: candidates[0].label };
+        }
+        if (candidates.length === 0) {
+            return { ok: false, error: "tool_denied", message: "No matching documents." };
+        }
+        return { ok: true, candidates };
+    }
+    return {
+        ok: false,
+        error: "tool_denied",
+        message: "A collection, global, or search query is required.",
+    };
+}
+export function canNavigate(options) {
+    return Object.keys(options.collections).length + Object.keys(options.globals).length > 0;
+}

package/dist/domain/propose.d.ts

@@ -0,0 +1,26 @@
+import type { PayloadRequest } from "payload";
+import type { ValidatedEditorAssistantOptions } from "../config/validate.ts";
+export type ProposeInput = {
+    capability: "form.propose" | "draft.create";
+    collection?: string;
+    global?: string;
+    documentId?: string | number;
+    locale: string;
+    /** Editor's chat language for the approval summary. */
+    language?: "sv" | "en";
+    operations: unknown;
+    formData?: Record<string, unknown>;
+};
+export type ProposeResult = {
+    ok: true;
+    approvalId: string;
+    nonce: string;
+    expiresAt: string;
+    summary: string;
+    title: string;
+} | {
+    ok: false;
+    error: "tool_denied" | "stale_context";
+    message: string;
+};
+export declare function proposeChange(req: PayloadRequest, options: ValidatedEditorAssistantOptions, input: ProposeInput): Promise<ProposeResult>;

package/dist/domain/propose.js

@@ -0,0 +1,150 @@
+import { compileOperations } from "../form/compile.js";
+import { humanDiff } from "../form/diff.js";
+import { hashFormRevision } from "../form/hash.js";
+import { isFormOperation, normalizeOperations } from "../form/operations.js";
+import { finalizeCompiled } from "../form/shape.js";
+import { DEFAULT_APPROVAL_SLUG } from "../package-name.js";
+import { entityFields, findCollectionConfig, hasDrafts } from "../schema/discover.js";
+import { hasCapability, resolveAllowlist } from "./allowlist.js";
+import { writeAudit } from "./audit.js";
+import { findContentById } from "./content.js";
+import { localApi } from "./local-api.js";
+import { verifyDocumentRelations } from "./relations.js";
+const TTL_MS = 120_000;
+export async function proposeChange(req, options, input) {
+    const resolved = resolveAllowlist(options, input);
+    if (!resolved || !hasCapability(resolved.allowlist, input.capability)) {
+        return { ok: false, error: "tool_denied", message: "Capability is not allowlisted." };
+    }
+    const operations = normalizeOperations(input.operations);
+    if (operations.length === 0 || !operations.every(isFormOperation)) {
+        return { ok: false, error: "tool_denied", message: "Operations are invalid." };
+    }
+    const typedOperations = operations;
+    const current = await resolveCurrentForm(req, options, input);
+    const compiled = compileOperations(current, typedOperations, {
+        allowlist: resolved.allowlist.fields,
+        denyFields: options.denyFields,
+    });
+    if (!compiled.ok) {
+        return { ok: false, error: "tool_denied", message: compiled.error };
+    }
+    if (options.validateProposal) {
+        const extra = await options.validateProposal({
+            operations: typedOperations,
+            data: compiled.data,
+        });
+        if (!extra.ok) {
+            return { ok: false, error: "tool_denied", message: extra.errors.join(" ") };
+        }
+    }
+    if (input.capability === "draft.create") {
+        const blocked = draftCreateDenied(req, input.collection);
+        if (blocked) {
+            return { ok: false, error: "tool_denied", message: blocked };
+        }
+    }
+    const fields = entityFields(req, options, {
+        collection: input.collection,
+        global: input.global,
+    });
+    const finalized = finalizeCompiled(compiled.data, fields);
+    if (!finalized.ok) {
+        return { ok: false, error: "tool_denied", message: finalized.error };
+    }
+    const relations = await verifyDocumentRelations(req, fields, finalized.data);
+    if (!relations.ok) {
+        return { ok: false, error: "tool_denied", message: relations.message };
+    }
+    const formRevision = input.capability === "form.propose" ? await hashFormRevision(current) : undefined;
+    const canonicalHash = await hashFormRevision(typedOperations);
+    const nonce = crypto.randomUUID();
+    const expiresAt = new Date(Date.now() + TTL_MS).toISOString();
+    const diff = humanDiff(current, typedOperations, input.language);
+    let created;
+    try {
+        created = await localApi(req).create({
+            collection: DEFAULT_APPROVAL_SLUG,
+            data: {
+                actor: String(req.user?.id),
+                capability: input.capability,
+                targetCollection: input.collection,
+                targetGlobal: input.global,
+                documentId: input.documentId === undefined ? undefined : String(input.documentId),
+                locale: input.locale,
+                canonicalHash,
+                formRevision,
+                nonce,
+                expiresAt,
+                status: "proposed",
+                operations: typedOperations,
+            },
+            req,
+            overrideAccess: false,
+            user: req.user,
+        });
+    }
+    catch {
+        return { ok: false, error: "tool_denied", message: "The proposal could not be stored." };
+    }
+    await writeAudit(req, options, {
+        capability: input.capability,
+        risk: "approval",
+        outcome: "proposed",
+        targetCollection: input.collection,
+        targetGlobal: input.global,
+        documentId: input.documentId === undefined ? undefined : String(input.documentId),
+        locale: input.locale,
+        fieldPaths: typedOperations.map((operation) => ("path" in operation ? operation.path : "")),
+        approvalId: String(created.id),
+        nonceId: nonce.slice(0, 8),
+        canonicalHash,
+        baseRevision: formRevision,
+    });
+    return {
+        ok: true,
+        approvalId: String(created.id),
+        nonce,
+        expiresAt,
+        title: approvalTitle(input.capability, input.language),
+        summary: diff.map((line) => line.text).join("\n"),
+    };
+}
+function approvalTitle(capability, language) {
+    if (language === "sv") {
+        return capability === "form.propose" ? "Ändring att godkänna" : "Nytt utkast att godkänna";
+    }
+    return capability === "form.propose" ? "Pending form change" : "Pending draft create";
+}
+async function resolveCurrentForm(req, options, input) {
+    const snapshot = input.formData && typeof input.formData === "object" ? input.formData : {};
+    if (input.capability !== "form.propose") {
+        return {};
+    }
+    const saved = await findContentById(req, options, {
+        collection: input.collection,
+        global: input.global,
+        documentId: input.documentId,
+        locale: input.locale,
+    });
+    if (!saved.ok) {
+        return snapshot;
+    }
+    return { ...saved.data, ...snapshot };
+}
+function draftCreateDenied(req, collection) {
+    if (!collection) {
+        return "Draft create requires a collection.";
+    }
+    const config = findCollectionConfig(req, collection);
+    if (!config) {
+        return "Collection was not found.";
+    }
+    if (!hasDrafts(config.versions)) {
+        return "Collection does not enable drafts.";
+    }
+    if (config.upload) {
+        return "Collections that require file upload cannot be created by the assistant.";
+    }
+    return null;
+}

package/dist/domain/relations.d.ts

@@ -0,0 +1,12 @@
+import type { PayloadRequest } from "payload";
+import type { FieldNode } from "../schema/fields.ts";
+export type RelationRef = {
+    collection: string;
+    id: string;
+};
+export declare function verifyDocumentRelations(req: PayloadRequest, fields: FieldNode[], data: Record<string, unknown>): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+}>;

package/dist/domain/relations.js

@@ -0,0 +1,103 @@
+import { localApi } from "./local-api.js";
+export async function verifyDocumentRelations(req, fields, data) {
+    const refs = collectRefs(fields, data);
+    for (const ref of refs) {
+        try {
+            await localApi(req).findByID({
+                collection: ref.collection,
+                id: ref.id,
+                depth: 0,
+                req,
+                user: req.user,
+                overrideAccess: false,
+            });
+        }
+        catch {
+            return {
+                ok: false,
+                message: "A relation or upload ID is missing, inaccessible, or invented.",
+            };
+        }
+    }
+    return { ok: true };
+}
+function collectRefs(fields, data) {
+    if (!data || typeof data !== "object") {
+        return [];
+    }
+    const refs = [];
+    if (Array.isArray(data)) {
+        for (const item of data) {
+            refs.push(...collectRefs(fields, item));
+        }
+        return refs;
+    }
+    const record = data;
+    for (const field of fields) {
+        const value = record[field.name];
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (field.type === "relationship" || field.type === "upload") {
+            refs.push(...refsFromValue(value, field.relationTo ?? []));
+            continue;
+        }
+        if (field.type === "group") {
+            refs.push(...collectRefs(field.fields ?? [], value));
+            continue;
+        }
+        if (field.type === "array" && Array.isArray(value)) {
+            for (const item of value) {
+                refs.push(...collectRefs(field.fields ?? [], item));
+            }
+            continue;
+        }
+        if (field.type === "blocks" && Array.isArray(value)) {
+            for (const item of value) {
+                if (!item || typeof item !== "object") {
+                    continue;
+                }
+                const blockType = item.blockType;
+                const block = field.blocks?.find((entry) => entry.slug === blockType);
+                refs.push(...collectRefs(block?.fields ?? [], item));
+            }
+        }
+    }
+    return refs;
+}
+function refsFromValue(value, relationTo) {
+    if (Array.isArray(value)) {
+        return value.flatMap((entry) => refsFromValue(entry, relationTo));
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        if (relationTo.length !== 1) {
+            return [];
+        }
+        return [{ collection: relationTo[0], id: String(value) }];
+    }
+    if (!value || typeof value !== "object") {
+        return [];
+    }
+    const record = value;
+    if (typeof record.relationTo === "string") {
+        const id = idOf(record.value ?? record.id);
+        return id ? [{ collection: record.relationTo, id }] : [];
+    }
+    const id = idOf(record.id ?? record.value);
+    if (!id || relationTo.length !== 1) {
+        return [];
+    }
+    return [{ collection: relationTo[0], id }];
+}
+function idOf(value) {
+    if (typeof value === "string" || typeof value === "number") {
+        return String(value);
+    }
+    if (value && typeof value === "object" && "id" in value) {
+        const id = value.id;
+        if (typeof id === "string" || typeof id === "number") {
+            return String(id);
+        }
+    }
+    return undefined;
+}

package/dist/endpoints/chat.d.ts

@@ -0,0 +1,3 @@
+import type { Endpoint } from "payload";
+import type { ValidatedEditorAssistantOptions } from "../config/validate.ts";
+export declare function createChatEndpoint(options: ValidatedEditorAssistantOptions): Endpoint;