webflow-mcp 0.3.0

package/dist/src/security/flow-approvals.js

@@ -0,0 +1,324 @@
+import { chmod, mkdir, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { WebFlowError } from '../shared/errors.js';
+import { getFlowApprovalsPath, getFlowPendingApprovalsPath, getFlowReleaseStatePath } from '../shared/paths.js';
+import { isVerifiedRemoteFlow, parseStrictJson } from './flow-release.js';
+let writeQueue = Promise.resolve();
+function serialized(operation) {
+    const result = writeQueue.then(() => withInterprocessLock(operation), () => withInterprocessLock(operation));
+    writeQueue = result.then(() => undefined, () => undefined);
+    return result;
+}
+async function withInterprocessLock(operation) {
+    const lockPath = `${getFlowApprovalsPath()}.lock`;
+    const lockToken = `${process.pid}:${randomUUID()}`;
+    await mkdir(dirname(lockPath), { recursive: true });
+    let handle;
+    for (let attempt = 0; attempt < 200; attempt++) {
+        try {
+            handle = await open(lockPath, 'wx', 0o600);
+            await handle.writeFile(`${lockToken}\n`, 'utf8');
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            await new Promise((resolveDelay) => setTimeout(resolveDelay, 25));
+        }
+    }
+    if (!handle)
+        fail('FLOW_APPROVAL_LOCK_TIMEOUT', `Timed out waiting for the local flow approval lock. If no worker or approval process is running, remove ${lockPath} manually.`);
+    try {
+        return await operation();
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+        const currentOwner = await readFile(lockPath, 'utf8').catch(() => '');
+        if (currentOwner.trim() === lockToken)
+            await rm(lockPath, { force: true }).catch(() => undefined);
+    }
+}
+function fail(code, message, details) {
+    throw new WebFlowError(code, message, details);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function exactKeys(value, expected) {
+    const keys = Object.keys(value);
+    return keys.length === expected.length && expected.every((key) => Object.hasOwn(value, key));
+}
+function isBoundedString(value, max = 256) {
+    return typeof value === 'string' && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+}
+function isDigest(value) {
+    return typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+}
+function isTimestamp(value) {
+    return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+function parseApproval(value) {
+    if (!isRecord(value) || !exactKeys(value, ['trustDomain', 'flowName', 'flowDigest', 'sequence', 'version', 'releaseId', 'keyId', 'approvedAt', 'updatedAt']))
+        return undefined;
+    if (!isBoundedString(value.trustDomain) || !isBoundedString(value.flowName, 128) || !isDigest(value.flowDigest)
+        || !Number.isSafeInteger(value.sequence) || value.sequence <= 0 || !isBoundedString(value.version)
+        || !isDigest(value.releaseId) || !isBoundedString(value.keyId, 128) || !isTimestamp(value.approvedAt) || !isTimestamp(value.updatedAt))
+        return undefined;
+    return value;
+}
+function parsePending(value) {
+    if (!isRecord(value) || !exactKeys(value, ['trustDomain', 'flowName', 'flowDigest', 'sequence', 'version', 'releaseId', 'keyId', 'receivedAt']))
+        return undefined;
+    if (!isBoundedString(value.trustDomain) || !isBoundedString(value.flowName, 128) || !isDigest(value.flowDigest)
+        || !Number.isSafeInteger(value.sequence) || value.sequence <= 0 || !isBoundedString(value.version)
+        || !isDigest(value.releaseId) || !isBoundedString(value.keyId, 128) || !isTimestamp(value.receivedAt))
+        return undefined;
+    return value;
+}
+function parseReleaseWatermark(value) {
+    if (!isRecord(value) || !exactKeys(value, ['trustDomain', 'highestSequence', 'releaseIdAtHighestSequence']))
+        return undefined;
+    if (!isBoundedString(value.trustDomain) || !Number.isSafeInteger(value.highestSequence)
+        || value.highestSequence <= 0 || !isDigest(value.releaseIdAtHighestSequence))
+        return undefined;
+    return value;
+}
+async function readStore(path, parse, empty, corruptCode = 'FLOW_APPROVAL_STORE_CORRUPT', stateName = 'flow approval state') {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return empty;
+        throw error;
+    }
+    try {
+        const result = parse(parseStrictJson(raw));
+        if (result !== undefined)
+            return result;
+    }
+    catch (error) {
+        if (error instanceof WebFlowError && error.code !== 'INVALID_FLOW_RELEASE_JSON')
+            throw error;
+    }
+    fail(corruptCode, `Refusing to use corrupt ${stateName} at ${path}.`, { path });
+}
+function parseApprovalStore(value) {
+    if (!isRecord(value) || !exactKeys(value, ['format', 'formatVersion', 'approvals'])
+        || value.format !== 'webflowmcp-flow-approvals' || value.formatVersion !== 1 || !Array.isArray(value.approvals))
+        return undefined;
+    const approvals = value.approvals.map(parseApproval);
+    if (approvals.some((entry) => entry === undefined))
+        return undefined;
+    const typed = approvals;
+    if (new Set(typed.map(keyOf)).size !== typed.length)
+        return undefined;
+    return { format: 'webflowmcp-flow-approvals', formatVersion: 1, approvals: typed };
+}
+function parsePendingStore(value) {
+    if (!isRecord(value) || !exactKeys(value, ['format', 'formatVersion', 'pending'])
+        || value.format !== 'webflowmcp-flow-pending-approvals' || value.formatVersion !== 1 || !Array.isArray(value.pending))
+        return undefined;
+    const pending = value.pending.map(parsePending);
+    if (pending.some((entry) => entry === undefined))
+        return undefined;
+    const typed = pending;
+    if (new Set(typed.map(keyOf)).size !== typed.length)
+        return undefined;
+    return { format: 'webflowmcp-flow-pending-approvals', formatVersion: 1, pending: typed };
+}
+function parseFlowReleaseStateStore(value) {
+    if (!isRecord(value) || !exactKeys(value, ['format', 'formatVersion', 'trustDomains'])
+        || value.format !== 'webflowmcp-flow-release-state' || value.formatVersion !== 1 || !Array.isArray(value.trustDomains))
+        return undefined;
+    const trustDomains = value.trustDomains.map(parseReleaseWatermark);
+    if (trustDomains.some((entry) => entry === undefined))
+        return undefined;
+    const typed = trustDomains;
+    if (new Set(typed.map((entry) => entry.trustDomain)).size !== typed.length)
+        return undefined;
+    return { format: 'webflowmcp-flow-release-state', formatVersion: 1, trustDomains: typed };
+}
+async function loadApprovals() {
+    return readStore(getFlowApprovalsPath(), parseApprovalStore, { format: 'webflowmcp-flow-approvals', formatVersion: 1, approvals: [] });
+}
+async function loadPending() {
+    return readStore(getFlowPendingApprovalsPath(), parsePendingStore, { format: 'webflowmcp-flow-pending-approvals', formatVersion: 1, pending: [] });
+}
+async function loadFlowReleaseState() {
+    return readStore(getFlowReleaseStatePath(), parseFlowReleaseStateStore, { format: 'webflowmcp-flow-release-state', formatVersion: 1, trustDomains: [] }, 'FLOW_RELEASE_STATE_CORRUPT', 'flow release state');
+}
+async function atomicWrite(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        await chmod(temporary, 0o600);
+        await rename(temporary, path);
+        await chmod(path, 0o600);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+function keyOf(value) {
+    return `${value.trustDomain}\0${value.flowName}`;
+}
+function pendingFrom(verified, receivedAt = new Date().toISOString()) {
+    return {
+        trustDomain: verified.trustDomain,
+        flowName: verified.flowName,
+        flowDigest: verified.flowDigest,
+        sequence: verified.sequence,
+        version: verified.version,
+        releaseId: verified.releaseId,
+        keyId: verified.keyId,
+        receivedAt
+    };
+}
+export async function assessAndRecordPending(verified) {
+    if (!isVerifiedRemoteFlow(verified))
+        fail('UNVERIFIED_REMOTE_FLOW', 'Only a cryptographically verified remote flow can affect approval state.');
+    return serialized(async () => {
+        const [approvals, pendingStore, releaseState] = await Promise.all([loadApprovals(), loadPending(), loadFlowReleaseState()]);
+        const watermark = releaseState.trustDomains.find((entry) => entry.trustDomain === verified.trustDomain);
+        if (watermark && verified.sequence < watermark.highestSequence) {
+            fail('FLOW_RELEASE_ROLLBACK', 'Flow release sequence is lower than the highest verified sequence for this trust domain.');
+        }
+        if (watermark && verified.sequence === watermark.highestSequence && verified.releaseId !== watermark.releaseIdAtHighestSequence) {
+            fail('FLOW_RELEASE_EQUIVOCATION', 'A different release was presented at the highest verified sequence for this trust domain.');
+        }
+        if (!watermark || verified.sequence > watermark.highestSequence) {
+            const advanced = {
+                trustDomain: verified.trustDomain,
+                highestSequence: verified.sequence,
+                releaseIdAtHighestSequence: verified.releaseId
+            };
+            if (watermark)
+                releaseState.trustDomains[releaseState.trustDomains.indexOf(watermark)] = advanced;
+            else
+                releaseState.trustDomains.push(advanced);
+            releaseState.trustDomains.sort((a, b) => a.trustDomain.localeCompare(b.trustDomain));
+            await atomicWrite(getFlowReleaseStatePath(), releaseState);
+        }
+        const key = keyOf(verified);
+        const approval = approvals.approvals.find((entry) => keyOf(entry) === key);
+        const existingPending = pendingStore.pending.find((entry) => keyOf(entry) === key);
+        if (approval) {
+            if (verified.sequence < approval.sequence)
+                fail('FLOW_RELEASE_ROLLBACK', 'Flow release sequence is lower than the locally approved sequence.');
+            if (verified.sequence === approval.sequence && verified.flowDigest !== approval.flowDigest) {
+                fail('FLOW_RELEASE_EQUIVOCATION', 'A different flow digest was presented at the approved sequence.');
+            }
+            if (verified.flowDigest === approval.flowDigest) {
+                if (existingPending && verified.sequence === existingPending.sequence && verified.flowDigest !== existingPending.flowDigest) {
+                    fail('FLOW_RELEASE_EQUIVOCATION', 'Different flow digests were presented at the same sequence.');
+                }
+                if (verified.sequence > approval.sequence) {
+                    const advanced = { ...approval, sequence: verified.sequence, version: verified.version, releaseId: verified.releaseId, keyId: verified.keyId, updatedAt: new Date().toISOString() };
+                    approvals.approvals[approvals.approvals.indexOf(approval)] = advanced;
+                    const clearPending = existingPending !== undefined && existingPending.sequence <= verified.sequence;
+                    if (clearPending)
+                        pendingStore.pending = pendingStore.pending.filter((entry) => keyOf(entry) !== key);
+                    await atomicWrite(getFlowApprovalsPath(), approvals);
+                    if (clearPending)
+                        await atomicWrite(getFlowPendingApprovalsPath(), pendingStore);
+                    return { status: 'approved', approval: advanced };
+                }
+                if (existingPending && existingPending.sequence === verified.sequence && existingPending.flowDigest === verified.flowDigest) {
+                    pendingStore.pending = pendingStore.pending.filter((entry) => keyOf(entry) !== key);
+                    await atomicWrite(getFlowPendingApprovalsPath(), pendingStore);
+                }
+                return { status: 'approved', approval };
+            }
+        }
+        if (existingPending) {
+            if (verified.sequence < existingPending.sequence)
+                fail('FLOW_RELEASE_ROLLBACK', 'Flow release sequence is lower than the latest pending sequence.');
+            if (verified.sequence === existingPending.sequence && verified.flowDigest !== existingPending.flowDigest) {
+                fail('FLOW_RELEASE_EQUIVOCATION', 'Different flow digests were presented at the same sequence.');
+            }
+            if (verified.sequence === existingPending.sequence)
+                return { status: 'pending', pending: existingPending };
+        }
+        const pending = pendingFrom(verified);
+        const index = pendingStore.pending.findIndex((entry) => keyOf(entry) === key);
+        if (index === -1)
+            pendingStore.pending.push(pending);
+        else
+            pendingStore.pending[index] = pending;
+        pendingStore.pending.sort((a, b) => keyOf(a).localeCompare(keyOf(b)));
+        await atomicWrite(getFlowPendingApprovalsPath(), pendingStore);
+        return { status: 'pending', pending };
+    });
+}
+export async function listPending() {
+    return (await loadPending()).pending.map((entry) => ({ ...entry }));
+}
+export async function approvePending(flowName, trustDomain, expected) {
+    return serialized(async () => {
+        const [approvals, pendingStore] = await Promise.all([loadApprovals(), loadPending()]);
+        const matches = pendingStore.pending.filter((entry) => entry.flowName === flowName && (trustDomain === undefined || entry.trustDomain === trustDomain));
+        if (matches.length === 0)
+            fail('FLOW_APPROVAL_NOT_FOUND', `No pending approval found for flow ${flowName}.`);
+        if (matches.length > 1)
+            fail('FLOW_APPROVAL_AMBIGUOUS', `Flow ${flowName} is pending in more than one trust domain; specify trustDomain.`);
+        const pending = matches[0];
+        if (expected && (pending.flowDigest !== expected.flowDigest || pending.releaseId !== expected.releaseId || pending.sequence !== expected.sequence)) {
+            fail('FLOW_APPROVAL_CHANGED', 'The pending signed update changed during confirmation; inspect and approve it again.');
+        }
+        const key = keyOf(pending);
+        const current = approvals.approvals.find((entry) => keyOf(entry) === key);
+        if (current && pending.sequence < current.sequence)
+            fail('FLOW_RELEASE_ROLLBACK', 'Pending sequence is lower than the approved sequence.');
+        if (current && pending.sequence === current.sequence && pending.flowDigest !== current.flowDigest) {
+            fail('FLOW_RELEASE_EQUIVOCATION', 'Pending flow conflicts with the approved digest at the same sequence.');
+        }
+        const now = new Date().toISOString();
+        const approval = {
+            trustDomain: pending.trustDomain,
+            flowName: pending.flowName,
+            flowDigest: pending.flowDigest,
+            sequence: pending.sequence,
+            version: pending.version,
+            releaseId: pending.releaseId,
+            keyId: pending.keyId,
+            approvedAt: current?.approvedAt ?? now,
+            updatedAt: now
+        };
+        const index = approvals.approvals.findIndex((entry) => keyOf(entry) === key);
+        if (index === -1)
+            approvals.approvals.push(approval);
+        else
+            approvals.approvals[index] = approval;
+        approvals.approvals.sort((a, b) => keyOf(a).localeCompare(keyOf(b)));
+        pendingStore.pending = pendingStore.pending.filter((entry) => keyOf(entry) !== key);
+        await atomicWrite(getFlowApprovalsPath(), approvals);
+        await atomicWrite(getFlowPendingApprovalsPath(), pendingStore);
+        return { ...approval };
+    });
+}
+export async function revokeApproval(flowName, trustDomain, expected) {
+    return serialized(async () => {
+        const approvals = await loadApprovals();
+        const matches = approvals.approvals.filter((entry) => entry.flowName === flowName && (trustDomain === undefined || entry.trustDomain === trustDomain));
+        if (matches.length > 1)
+            fail('FLOW_APPROVAL_AMBIGUOUS', `Flow ${flowName} is approved in more than one trust domain; specify trustDomain.`);
+        if (matches.length === 0)
+            return false;
+        const approval = matches[0];
+        if (expected && (approval.flowDigest !== expected.flowDigest || approval.releaseId !== expected.releaseId || approval.sequence !== expected.sequence)) {
+            fail('FLOW_APPROVAL_CHANGED', 'The approved signed flow changed during confirmation; inspect it again before revoking.');
+        }
+        const key = keyOf(approval);
+        approvals.approvals = approvals.approvals.filter((entry) => keyOf(entry) !== key);
+        await atomicWrite(getFlowApprovalsPath(), approvals);
+        return true;
+    });
+}
+export async function listApprovals() {
+    return (await loadApprovals()).approvals.map((entry) => ({ ...entry }));
+}

package/dist/src/security/flow-release.d.ts

@@ -0,0 +1,82 @@
+export declare const FLOW_RELEASE_FORMAT: "webflowmcp-flow-release";
+export declare const FLOW_RELEASE_FORMAT_VERSION: 1;
+export declare const FLOW_RUNTIME_API_VERSION: 1;
+export declare const FLOW_RELEASE_RUNTIME_API_VERSION: 1;
+export declare const FLOW_RELEASE_SIGNATURE_PREFIX = "webflowmcp-flow-release/v1\0";
+export declare const FLOW_DIGEST_PREFIX = "webflowmcp-flow-digest/v1\0";
+export declare const FLOW_RELEASE_LIMITS: Readonly<{
+    manifestBytes: number;
+    codeBytes: number;
+    schemaBytes: number;
+    capabilitiesBytes: number;
+    flows: 4096;
+    signatures: 32;
+}>;
+export interface FlowArtifactDescriptor {
+    sha256: string;
+    size: number;
+}
+export interface FlowReleaseManifestEntry {
+    name: string;
+    code: FlowArtifactDescriptor;
+    schema: FlowArtifactDescriptor;
+    capabilities: FlowArtifactDescriptor;
+}
+export interface FlowReleaseManifest {
+    format: typeof FLOW_RELEASE_FORMAT;
+    formatVersion: typeof FLOW_RELEASE_FORMAT_VERSION;
+    runtimeApiVersion: typeof FLOW_RUNTIME_API_VERSION;
+    trustDomain: string;
+    sequence: number;
+    version: string;
+    sourceDigest: string;
+    taxonomy: FlowArtifactDescriptor;
+    flows: FlowReleaseManifestEntry[];
+}
+export interface FlowReleaseSignature {
+    algorithm: 'Ed25519';
+    keyId: string;
+    value: string;
+}
+export interface SignedFlowRelease {
+    manifest: string;
+    signatures: FlowReleaseSignature[];
+    flowName: string;
+    code: string;
+    schema: string;
+    capabilities: string;
+}
+export interface FlowTrustPolicyEntry {
+    relayUrl: string;
+    trustDomain: string;
+    keyId: string;
+    publicKeySpkiPem: string;
+    minSequence?: number;
+    maxSequence?: number;
+}
+export interface VerifyFlowReleaseOptions {
+    expectedRelayUrl: string;
+    expectedTrustDomain: string;
+    trustPolicy: readonly FlowTrustPolicyEntry[];
+}
+declare const verifiedRemoteFlowBrand: unique symbol;
+export interface VerifiedRemoteFlow {
+    readonly [verifiedRemoteFlowBrand]: true;
+    readonly flowName: string;
+    readonly code: string;
+    readonly schema: Readonly<Record<string, unknown>>;
+    readonly capabilities: Readonly<Record<string, unknown>>;
+    readonly releaseId: string;
+    readonly sequence: number;
+    readonly version: string;
+    readonly keyId: string;
+    readonly trustDomain: string;
+    readonly flowDigest: string;
+}
+/** JSON parser that also rejects duplicate object keys, avoiding cross-parser ambiguity. */
+export declare function parseStrictJson(raw: string): unknown;
+export declare function parseFlowReleaseManifest(raw: string): FlowReleaseManifest;
+export declare function deriveFlowReleaseKeyId(publicKeySpkiPem: string): string;
+export declare function verifyFlowRelease(value: unknown, options: VerifyFlowReleaseOptions): VerifiedRemoteFlow;
+export declare function isVerifiedRemoteFlow(value: unknown): value is VerifiedRemoteFlow;
+export {};