webflow-mcp 0.3.0

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

@@ -0,0 +1,392 @@
+import { createHash, createPublicKey, verify as verifySignature } from 'node:crypto';
+import { WebFlowError } from '../shared/errors.js';
+export const FLOW_RELEASE_FORMAT = 'webflowmcp-flow-release';
+export const FLOW_RELEASE_FORMAT_VERSION = 1;
+export const FLOW_RUNTIME_API_VERSION = 1;
+export const FLOW_RELEASE_RUNTIME_API_VERSION = FLOW_RUNTIME_API_VERSION;
+export const FLOW_RELEASE_SIGNATURE_PREFIX = 'webflowmcp-flow-release/v1\0';
+export const FLOW_DIGEST_PREFIX = 'webflowmcp-flow-digest/v1\0';
+export const FLOW_RELEASE_LIMITS = Object.freeze({
+    manifestBytes: 1024 * 1024,
+    codeBytes: 4 * 1024 * 1024,
+    schemaBytes: 256 * 1024,
+    capabilitiesBytes: 256 * 1024,
+    flows: 4096,
+    signatures: 32
+});
+const verifiedValues = new WeakSet();
+function fail(code, message, details) {
+    throw new WebFlowError(code, message, details);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertExactKeys(value, required, optional = []) {
+    const allowed = new Set([...required, ...optional]);
+    const keys = Object.keys(value);
+    if (required.some((key) => !Object.hasOwn(value, key)) || keys.some((key) => !allowed.has(key))) {
+        fail('INVALID_FLOW_RELEASE', 'Flow release contains missing or unknown fields.');
+    }
+}
+/** JSON parser that also rejects duplicate object keys, avoiding cross-parser ambiguity. */
+export function parseStrictJson(raw) {
+    let offset = 0;
+    const skipWhitespace = () => {
+        while (offset < raw.length && /[\x20\x09\x0a\x0d]/.test(raw[offset]))
+            offset += 1;
+    };
+    const parseString = () => {
+        const start = offset;
+        offset += 1;
+        while (offset < raw.length) {
+            const char = raw[offset];
+            if (char === '"') {
+                offset += 1;
+                try {
+                    return JSON.parse(raw.slice(start, offset));
+                }
+                catch {
+                    fail('INVALID_FLOW_RELEASE_JSON', 'Invalid JSON string in flow release.');
+                }
+            }
+            if (char === '\\') {
+                offset += 2;
+            }
+            else {
+                offset += 1;
+            }
+        }
+        fail('INVALID_FLOW_RELEASE_JSON', 'Unterminated JSON string in flow release.');
+    };
+    const parseValue = () => {
+        skipWhitespace();
+        const char = raw[offset];
+        if (char === '"')
+            return parseString();
+        if (char === '{') {
+            offset += 1;
+            skipWhitespace();
+            const result = {};
+            const keys = new Set();
+            if (raw[offset] === '}') {
+                offset += 1;
+                return result;
+            }
+            while (offset < raw.length) {
+                if (raw[offset] !== '"')
+                    fail('INVALID_FLOW_RELEASE_JSON', 'JSON object key must be a string.');
+                const key = parseString();
+                if (keys.has(key))
+                    fail('INVALID_FLOW_RELEASE_JSON', `Duplicate JSON object key: ${key}`);
+                keys.add(key);
+                skipWhitespace();
+                if (raw[offset] !== ':')
+                    fail('INVALID_FLOW_RELEASE_JSON', 'Missing colon after JSON object key.');
+                offset += 1;
+                Object.defineProperty(result, key, { value: parseValue(), enumerable: true, configurable: true, writable: true });
+                skipWhitespace();
+                if (raw[offset] === '}') {
+                    offset += 1;
+                    return result;
+                }
+                if (raw[offset] !== ',')
+                    fail('INVALID_FLOW_RELEASE_JSON', 'Missing comma in JSON object.');
+                offset += 1;
+                skipWhitespace();
+            }
+            fail('INVALID_FLOW_RELEASE_JSON', 'Unterminated JSON object.');
+        }
+        if (char === '[') {
+            offset += 1;
+            skipWhitespace();
+            const result = [];
+            if (raw[offset] === ']') {
+                offset += 1;
+                return result;
+            }
+            while (offset < raw.length) {
+                result.push(parseValue());
+                skipWhitespace();
+                if (raw[offset] === ']') {
+                    offset += 1;
+                    return result;
+                }
+                if (raw[offset] !== ',')
+                    fail('INVALID_FLOW_RELEASE_JSON', 'Missing comma in JSON array.');
+                offset += 1;
+            }
+            fail('INVALID_FLOW_RELEASE_JSON', 'Unterminated JSON array.');
+        }
+        const start = offset;
+        while (offset < raw.length && !/[\x20\x09\x0a\x0d,\]}]/.test(raw[offset]))
+            offset += 1;
+        if (start === offset)
+            fail('INVALID_FLOW_RELEASE_JSON', 'Invalid JSON value.');
+        try {
+            return JSON.parse(raw.slice(start, offset));
+        }
+        catch {
+            fail('INVALID_FLOW_RELEASE_JSON', 'Invalid JSON value.');
+        }
+    };
+    const parsed = parseValue();
+    skipWhitespace();
+    if (offset !== raw.length)
+        fail('INVALID_FLOW_RELEASE_JSON', 'Unexpected data after JSON value.');
+    return parsed;
+}
+function nonEmptyString(value, label, max = 256) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > max || /[\u0000-\u001f\u007f]/.test(value)) {
+        fail('INVALID_FLOW_RELEASE', `${label} must be a non-empty bounded string without control characters.`);
+    }
+    return value;
+}
+function positiveSafeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        fail('INVALID_FLOW_RELEASE', `${label} must be a positive safe integer.`);
+    }
+    return value;
+}
+function parseArtifact(value, label, maxBytes) {
+    if (!isRecord(value))
+        fail('INVALID_FLOW_RELEASE', `${label} descriptor must be an object.`);
+    assertExactKeys(value, ['sha256', 'size']);
+    if (typeof value.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(value.sha256)) {
+        fail('INVALID_FLOW_RELEASE', `${label}.sha256 must be a lowercase SHA-256 digest.`);
+    }
+    if (!Number.isSafeInteger(value.size) || value.size < 0 || value.size > maxBytes) {
+        fail('FLOW_RELEASE_TOO_LARGE', `${label}.size exceeds the allowed artifact size.`);
+    }
+    return { sha256: value.sha256, size: value.size };
+}
+export function parseFlowReleaseManifest(raw) {
+    if (typeof raw !== 'string' || Buffer.byteLength(raw, 'utf8') > FLOW_RELEASE_LIMITS.manifestBytes) {
+        fail('FLOW_RELEASE_TOO_LARGE', 'Flow release manifest exceeds the allowed size.');
+    }
+    const value = parseStrictJson(raw);
+    if (!isRecord(value))
+        fail('INVALID_FLOW_RELEASE', 'Flow release manifest must be an object.');
+    assertExactKeys(value, ['format', 'formatVersion', 'runtimeApiVersion', 'trustDomain', 'sequence', 'version', 'sourceDigest', 'taxonomy', 'flows']);
+    if (value.format !== FLOW_RELEASE_FORMAT || value.formatVersion !== FLOW_RELEASE_FORMAT_VERSION || value.runtimeApiVersion !== FLOW_RUNTIME_API_VERSION) {
+        fail('UNSUPPORTED_FLOW_RELEASE', 'Unsupported flow release format or runtime API version.');
+    }
+    const trustDomain = nonEmptyString(value.trustDomain, 'trustDomain');
+    const sequence = positiveSafeInteger(value.sequence, 'sequence');
+    const version = nonEmptyString(value.version, 'version');
+    if (typeof value.sourceDigest !== 'string' || !/^[a-f0-9]{64}$/.test(value.sourceDigest)) {
+        fail('INVALID_FLOW_RELEASE', 'sourceDigest must be a lowercase SHA-256 digest.');
+    }
+    const taxonomy = parseArtifact(value.taxonomy, 'taxonomy', FLOW_RELEASE_LIMITS.schemaBytes);
+    if (!Array.isArray(value.flows) || value.flows.length > FLOW_RELEASE_LIMITS.flows) {
+        fail('INVALID_FLOW_RELEASE', 'flows must be a bounded array.');
+    }
+    const flows = [];
+    let previousName;
+    for (const rawFlow of value.flows) {
+        if (!isRecord(rawFlow))
+            fail('INVALID_FLOW_RELEASE', 'Each flow manifest entry must be an object.');
+        assertExactKeys(rawFlow, ['name', 'code', 'schema', 'capabilities']);
+        const name = nonEmptyString(rawFlow.name, 'flow name', 128);
+        if (previousName !== undefined && name <= previousName) {
+            fail('INVALID_FLOW_RELEASE', 'Flow manifest entries must have unique names sorted in ascending byte order.');
+        }
+        previousName = name;
+        flows.push({
+            name,
+            code: parseArtifact(rawFlow.code, `${name}.code`, FLOW_RELEASE_LIMITS.codeBytes),
+            schema: parseArtifact(rawFlow.schema, `${name}.schema`, FLOW_RELEASE_LIMITS.schemaBytes),
+            capabilities: parseArtifact(rawFlow.capabilities, `${name}.capabilities`, FLOW_RELEASE_LIMITS.capabilitiesBytes)
+        });
+    }
+    return {
+        format: FLOW_RELEASE_FORMAT,
+        formatVersion: 1,
+        runtimeApiVersion: 1,
+        trustDomain,
+        sequence,
+        version,
+        sourceDigest: value.sourceDigest,
+        taxonomy,
+        flows
+    };
+}
+function parseSignedRelease(value) {
+    if (!isRecord(value))
+        fail('INVALID_FLOW_RELEASE', 'Signed flow release must be an object.');
+    assertExactKeys(value, ['manifest', 'signatures', 'flowName', 'code', 'schema', 'capabilities']);
+    if (typeof value.manifest !== 'string' || typeof value.code !== 'string' || typeof value.schema !== 'string' || typeof value.capabilities !== 'string') {
+        fail('INVALID_FLOW_RELEASE', 'Selected flow artifacts and manifest must be exact strings.');
+    }
+    if (Buffer.byteLength(value.manifest, 'utf8') > FLOW_RELEASE_LIMITS.manifestBytes
+        || Buffer.byteLength(value.code, 'utf8') > FLOW_RELEASE_LIMITS.codeBytes
+        || Buffer.byteLength(value.schema, 'utf8') > FLOW_RELEASE_LIMITS.schemaBytes
+        || Buffer.byteLength(value.capabilities, 'utf8') > FLOW_RELEASE_LIMITS.capabilitiesBytes) {
+        fail('FLOW_RELEASE_TOO_LARGE', 'Signed flow release exceeds an artifact size limit.');
+    }
+    const flowName = nonEmptyString(value.flowName, 'flowName', 128);
+    if (!Array.isArray(value.signatures) || value.signatures.length === 0 || value.signatures.length > FLOW_RELEASE_LIMITS.signatures) {
+        fail('INVALID_FLOW_RELEASE', 'signatures must be a non-empty bounded array.');
+    }
+    const seen = new Set();
+    const signatures = value.signatures.map((rawSignature) => {
+        if (!isRecord(rawSignature))
+            fail('INVALID_FLOW_RELEASE', 'Each signature must be an object.');
+        assertExactKeys(rawSignature, ['algorithm', 'keyId', 'value']);
+        if (rawSignature.algorithm !== 'Ed25519')
+            fail('UNSUPPORTED_FLOW_RELEASE_SIGNATURE', 'Only Ed25519 flow release signatures are accepted.');
+        const keyId = nonEmptyString(rawSignature.keyId, 'signature keyId', 128);
+        if (seen.has(keyId))
+            fail('INVALID_FLOW_RELEASE', `Duplicate signature keyId: ${keyId}`);
+        seen.add(keyId);
+        if (typeof rawSignature.value !== 'string' || !/^[A-Za-z0-9+/]{86}==$/.test(rawSignature.value)) {
+            fail('INVALID_FLOW_RELEASE_SIGNATURE', 'Ed25519 signature must be canonical base64.');
+        }
+        const bytes = Buffer.from(rawSignature.value, 'base64');
+        if (bytes.length !== 64 || bytes.toString('base64') !== rawSignature.value) {
+            fail('INVALID_FLOW_RELEASE_SIGNATURE', 'Ed25519 signature must be 64 canonical base64 bytes.');
+        }
+        return { algorithm: 'Ed25519', keyId, value: rawSignature.value };
+    });
+    return { manifest: value.manifest, signatures, flowName, code: value.code, schema: value.schema, capabilities: value.capabilities };
+}
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+export function deriveFlowReleaseKeyId(publicKeySpkiPem) {
+    try {
+        const key = createPublicKey({ key: publicKeySpkiPem, format: 'pem', type: 'spki' });
+        if (key.asymmetricKeyType !== 'ed25519')
+            fail('INVALID_FLOW_TRUST_POLICY', 'Trusted flow release key must be Ed25519.');
+        return sha256(key.export({ format: 'der', type: 'spki' }));
+    }
+    catch (error) {
+        if (error instanceof WebFlowError)
+            throw error;
+        fail('INVALID_FLOW_TRUST_POLICY', 'Trusted flow release key is not a valid SPKI PEM Ed25519 key.');
+    }
+}
+function verifyArtifact(value, descriptor, maxBytes, label) {
+    const size = Buffer.byteLength(value, 'utf8');
+    if (size > maxBytes)
+        fail('FLOW_RELEASE_TOO_LARGE', `${label} exceeds the allowed artifact size.`);
+    if (size !== descriptor.size || sha256(value) !== descriptor.sha256) {
+        fail('FLOW_RELEASE_ARTIFACT_MISMATCH', `${label} does not match its signed size and SHA-256 digest.`);
+    }
+}
+function parseJsonObject(raw, label) {
+    const parsed = parseStrictJson(raw);
+    if (!isRecord(parsed))
+        fail('INVALID_FLOW_RELEASE_ARTIFACT', `${label} must contain a JSON object.`);
+    return deepFreeze(parsed);
+}
+function deepFreeze(value) {
+    if (typeof value === 'object' && value !== null) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+function validatePolicy(entry) {
+    if (typeof entry.relayUrl !== 'string' || entry.relayUrl.length === 0 || typeof entry.trustDomain !== 'string' || entry.trustDomain.length === 0
+        || typeof entry.keyId !== 'string' || entry.keyId.length === 0 || typeof entry.publicKeySpkiPem !== 'string' || entry.publicKeySpkiPem.length === 0) {
+        fail('INVALID_FLOW_TRUST_POLICY', 'Trust policy relay URL, domain, key ID, and SPKI PEM must be non-empty strings.');
+    }
+    if (entry.minSequence !== undefined && (!Number.isSafeInteger(entry.minSequence) || entry.minSequence <= 0)) {
+        fail('INVALID_FLOW_TRUST_POLICY', 'Trust policy minSequence must be a positive safe integer.');
+    }
+    if (entry.maxSequence !== undefined && (!Number.isSafeInteger(entry.maxSequence) || entry.maxSequence <= 0)) {
+        fail('INVALID_FLOW_TRUST_POLICY', 'Trust policy maxSequence must be a positive safe integer.');
+    }
+    if (entry.minSequence !== undefined && entry.maxSequence !== undefined && entry.minSequence > entry.maxSequence) {
+        fail('INVALID_FLOW_TRUST_POLICY', 'Trust policy sequence range is empty.');
+    }
+    if (deriveFlowReleaseKeyId(entry.publicKeySpkiPem) !== entry.keyId) {
+        fail('INVALID_FLOW_TRUST_POLICY', 'Trust policy keyId must equal the SHA-256 digest of its public SPKI DER bytes.');
+    }
+}
+function sequenceAllowed(entry, sequence) {
+    return (entry.minSequence === undefined || sequence >= entry.minSequence)
+        && (entry.maxSequence === undefined || sequence <= entry.maxSequence);
+}
+export function verifyFlowRelease(value, options) {
+    const release = parseSignedRelease(value);
+    const manifest = parseFlowReleaseManifest(release.manifest);
+    if (manifest.trustDomain !== options.expectedTrustDomain) {
+        fail('FLOW_RELEASE_TRUST_DOMAIN_MISMATCH', 'Flow release trust domain does not match the expected worker trust domain.');
+    }
+    const policies = options.trustPolicy.filter((entry) => entry.relayUrl === options.expectedRelayUrl && entry.trustDomain === options.expectedTrustDomain);
+    if (policies.length === 0)
+        fail('UNTRUSTED_FLOW_RELEASE', 'No trust policy matches the exact relay URL and trust domain.');
+    for (const policy of policies)
+        validatePolicy(policy);
+    const policyKeys = new Set();
+    for (const policy of policies) {
+        if (policyKeys.has(policy.keyId))
+            fail('INVALID_FLOW_TRUST_POLICY', `Multiple trust policies match keyId ${policy.keyId}.`);
+        policyKeys.add(policy.keyId);
+    }
+    const message = Buffer.concat([Buffer.from(FLOW_RELEASE_SIGNATURE_PREFIX, 'utf8'), Buffer.from(release.manifest, 'utf8')]);
+    let verifiedKeyId;
+    let matchingKeyOutsideSequenceRange = false;
+    for (const signature of release.signatures) {
+        const policy = policies.find((entry) => entry.keyId === signature.keyId);
+        if (!policy)
+            continue;
+        if (!sequenceAllowed(policy, manifest.sequence)) {
+            matchingKeyOutsideSequenceRange = true;
+            continue;
+        }
+        try {
+            const key = createPublicKey({ key: policy.publicKeySpkiPem, format: 'pem', type: 'spki' });
+            if (key.asymmetricKeyType !== 'ed25519')
+                fail('INVALID_FLOW_TRUST_POLICY', `Trusted key ${policy.keyId} is not Ed25519.`);
+            if (verifySignature(null, message, key, Buffer.from(signature.value, 'base64'))) {
+                verifiedKeyId = signature.keyId;
+                break;
+            }
+        }
+        catch (error) {
+            if (error instanceof WebFlowError)
+                throw error;
+            fail('INVALID_FLOW_TRUST_POLICY', `Trusted key ${policy.keyId} is not a valid SPKI PEM Ed25519 key.`);
+        }
+    }
+    if (!verifiedKeyId && matchingKeyOutsideSequenceRange) {
+        fail('FLOW_RELEASE_SEQUENCE_OUT_OF_POLICY', 'Flow release sequence is outside the trusted key policy range.');
+    }
+    if (!verifiedKeyId)
+        fail('INVALID_FLOW_RELEASE_SIGNATURE', 'No trusted Ed25519 signature verifies this flow release.');
+    const selected = manifest.flows.find((flow) => flow.name === release.flowName);
+    if (!selected)
+        fail('FLOW_NOT_IN_RELEASE', `Flow ${release.flowName} is not present in the signed manifest.`);
+    verifyArtifact(release.code, selected.code, FLOW_RELEASE_LIMITS.codeBytes, 'code');
+    verifyArtifact(release.schema, selected.schema, FLOW_RELEASE_LIMITS.schemaBytes, 'schema');
+    verifyArtifact(release.capabilities, selected.capabilities, FLOW_RELEASE_LIMITS.capabilitiesBytes, 'capabilities');
+    // Parsing happens only after all three byte strings match their signed descriptors.
+    const schema = parseJsonObject(release.schema, 'schema');
+    const capabilities = parseJsonObject(release.capabilities, 'capabilities');
+    const flowDigest = sha256(`${FLOW_DIGEST_PREFIX}${JSON.stringify([
+        selected.name,
+        selected.code.sha256,
+        selected.schema.sha256,
+        selected.capabilities.sha256
+    ])}`);
+    const result = Object.freeze({
+        flowName: selected.name,
+        code: release.code,
+        schema,
+        capabilities,
+        releaseId: sha256(release.manifest),
+        sequence: manifest.sequence,
+        version: manifest.version,
+        keyId: verifiedKeyId,
+        trustDomain: manifest.trustDomain,
+        flowDigest
+    });
+    verifiedValues.add(result);
+    return result;
+}
+export function isVerifiedRemoteFlow(value) {
+    return typeof value === 'object' && value !== null && verifiedValues.has(value);
+}

package/dist/src/security/official-flow-trust.d.ts

@@ -0,0 +1,2 @@
+import type { FlowTrustPolicyEntry } from './flow-release.js';
+export declare const OFFICIAL_FLOW_TRUST_POLICY: readonly FlowTrustPolicyEntry[];

package/dist/src/security/official-flow-trust.js

@@ -0,0 +1,16 @@
+export const OFFICIAL_FLOW_TRUST_POLICY = Object.freeze([
+    {
+        "relayUrl": "wss://int-relay.webflowmcp.es/worker",
+        "trustDomain": "webflowmcp-staging",
+        "keyId": "6bdcc7f3845bfef4c45c0c36b66a08cda60db74f2f16770941027c5e9d0593af",
+        "publicKeySpkiPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAdF8bnAlyGF65lQT/YPlQJfKkn5BgFICmw3mfpC3cD+8=\n-----END PUBLIC KEY-----\n",
+        "minSequence": 1
+    },
+    {
+        "relayUrl": "wss://relay.webflowmcp.es/worker",
+        "trustDomain": "webflowmcp-production",
+        "keyId": "6518d0ca28e1b758b6446fb551c6966edc015c3f0043c50cfad10a9390de9932",
+        "publicKeySpkiPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAV1bKXnrbI1SLky01lsl0FRSsLC/fYTzDBifla3bqb8s=\n-----END PUBLIC KEY-----\n",
+        "minSequence": 1
+    }
+].map((entry) => Object.freeze(entry)));

package/dist/src/security/trusted-flow-keys.d.ts

@@ -0,0 +1,8 @@
+import { type FlowTrustPolicyEntry } from './flow-release.js';
+export { OFFICIAL_FLOW_TRUST_POLICY } from './official-flow-trust.js';
+export declare const FLOW_TRUST_POLICY_PATH_ENV = "WEBFLOW_FLOW_TRUST_POLICY_PATH";
+/**
+ * Loads an explicit worker-local trust root for a custom/dev relay. The relay
+ * cannot provide this path or any key material over WebSocket.
+ */
+export declare function loadFlowTrustPolicy(relayUrl: string, policyPath?: string | undefined): readonly FlowTrustPolicyEntry[];

package/dist/src/security/trusted-flow-keys.js

@@ -0,0 +1,132 @@
+import { createPublicKey } from 'node:crypto';
+import { closeSync, constants, fstatSync, openSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { WebFlowError } from '../shared/errors.js';
+import { deriveFlowReleaseKeyId, parseStrictJson } from './flow-release.js';
+import { OFFICIAL_FLOW_TRUST_POLICY } from './official-flow-trust.js';
+export { OFFICIAL_FLOW_TRUST_POLICY } from './official-flow-trust.js';
+export const FLOW_TRUST_POLICY_PATH_ENV = 'WEBFLOW_FLOW_TRUST_POLICY_PATH';
+const OFFICIAL_RELAY_HOSTS = new Set(['relay.webflowmcp.es', 'int-relay.webflowmcp.es']);
+const MAX_POLICY_BYTES = 64 * 1024;
+function fail(message, details) {
+    throw new WebFlowError('INVALID_FLOW_TRUST_POLICY', message, details);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, required, optional = []) {
+    const allowed = new Set([...required, ...optional]);
+    const keys = Object.keys(value);
+    return required.every((key) => Object.hasOwn(value, key)) && keys.every((key) => allowed.has(key));
+}
+function boundedString(value, max = 256) {
+    return typeof value === 'string' && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+}
+function parsePolicyEntry(value, relayUrl) {
+    if (!isRecord(value) || !hasExactKeys(value, ['relayUrl', 'trustDomain', 'keyId', 'publicKeySpkiPem'], ['minSequence', 'maxSequence'])) {
+        fail('Local trust policy entries contain missing or unknown fields.');
+    }
+    if (value.relayUrl !== relayUrl) {
+        fail(`Every local trust policy entry must match the exact configured relay URL ${relayUrl}.`);
+    }
+    if (!boundedString(value.trustDomain) || !boundedString(value.keyId, 128)
+        || typeof value.publicKeySpkiPem !== 'string' || value.publicKeySpkiPem.length === 0
+        || value.publicKeySpkiPem.length > 16 * 1024 || /[\u0000\u007f]/.test(value.publicKeySpkiPem)) {
+        fail('Trust domain, key ID, and public SPKI PEM must be non-empty bounded strings.');
+    }
+    if (!value.publicKeySpkiPem.includes('-----BEGIN PUBLIC KEY-----') || value.publicKeySpkiPem.includes('PRIVATE KEY')) {
+        fail('Local trust policy accepts only public SPKI PEM keys, never private keys.');
+    }
+    for (const field of ['minSequence', 'maxSequence']) {
+        const sequence = value[field];
+        if (sequence !== undefined && (!Number.isSafeInteger(sequence) || sequence <= 0)) {
+            fail(`${field} must be a positive safe integer.`);
+        }
+    }
+    if (typeof value.minSequence === 'number' && typeof value.maxSequence === 'number' && value.minSequence > value.maxSequence) {
+        fail('Trust policy sequence range is empty.');
+    }
+    try {
+        const key = createPublicKey({ key: value.publicKeySpkiPem, format: 'pem', type: 'spki' });
+        if (key.asymmetricKeyType !== 'ed25519')
+            fail(`Trusted key ${value.keyId} is not Ed25519.`);
+        if (deriveFlowReleaseKeyId(value.publicKeySpkiPem) !== value.keyId) {
+            fail(`Trusted keyId ${value.keyId} does not match its public SPKI SHA-256 digest.`);
+        }
+    }
+    catch (error) {
+        if (error instanceof WebFlowError)
+            throw error;
+        fail(`Trusted key ${value.keyId} is not a valid public SPKI PEM key.`);
+    }
+    return Object.freeze({
+        relayUrl,
+        trustDomain: value.trustDomain,
+        keyId: value.keyId,
+        publicKeySpkiPem: value.publicKeySpkiPem,
+        minSequence: value.minSequence,
+        maxSequence: value.maxSequence
+    });
+}
+function parsePolicyFile(raw, relayUrl) {
+    let value;
+    try {
+        value = parseStrictJson(raw);
+    }
+    catch (error) {
+        fail(`Local flow trust policy is not strict JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(value) || !hasExactKeys(value, ['format', 'formatVersion', 'entries'])
+        || value.format !== 'webflowmcp-flow-trust-policy' || value.formatVersion !== 1 || !Array.isArray(value.entries)) {
+        fail('Local flow trust policy must use format webflowmcp-flow-trust-policy version 1.');
+    }
+    const entries = value.entries.map((entry) => parsePolicyEntry(entry, relayUrl));
+    const identities = entries.map((entry) => `${entry.trustDomain}\0${entry.keyId}`);
+    if (new Set(identities).size !== identities.length)
+        fail('Local trust policy contains duplicate trust-domain/key identities.');
+    return { format: 'webflowmcp-flow-trust-policy', formatVersion: 1, entries };
+}
+/**
+ * Loads an explicit worker-local trust root for a custom/dev relay. The relay
+ * cannot provide this path or any key material over WebSocket.
+ */
+export function loadFlowTrustPolicy(relayUrl, policyPath = process.env[FLOW_TRUST_POLICY_PATH_ENV]) {
+    if (!policyPath?.trim())
+        return OFFICIAL_FLOW_TRUST_POLICY;
+    let hostname;
+    try {
+        hostname = new URL(relayUrl).hostname.toLowerCase();
+    }
+    catch {
+        fail(`Cannot bind a local trust policy to invalid relay URL ${relayUrl}.`);
+    }
+    if (OFFICIAL_RELAY_HOSTS.has(hostname)) {
+        fail(`Local trust-policy overrides are disabled for official relay ${hostname}; its public keys must ship with the worker.`);
+    }
+    const path = resolve(policyPath.trim());
+    let raw;
+    let descriptor;
+    try {
+        const noFollow = process.platform === 'win32' ? 0 : constants.O_NOFOLLOW;
+        descriptor = openSync(path, constants.O_RDONLY | noFollow);
+        const metadata = fstatSync(descriptor);
+        if (!metadata.isFile())
+            fail(`Local trust policy path must be a regular file: ${path}`);
+        if (process.platform !== 'win32' && (metadata.mode & 0o022) !== 0) {
+            fail(`Local trust policy must not be group- or world-writable: ${path}`);
+        }
+        if (metadata.size > MAX_POLICY_BYTES)
+            fail(`Local trust policy exceeds ${MAX_POLICY_BYTES} bytes.`);
+        raw = readFileSync(descriptor, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof WebFlowError)
+            throw error;
+        fail(`Unable to read local flow trust policy at ${path}: ${error instanceof Error ? error.message : String(error)}`, { path });
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+    return Object.freeze(parsePolicyFile(raw, relayUrl).entries);
+}

package/dist/src/shared/credentials.d.ts

@@ -0,0 +1,21 @@
+export interface WorkerCredentials {
+    version: 2;
+    appUrl: string;
+    relayUrl: string;
+    deviceId: string;
+    workerId: string;
+    credentialId: string;
+    secret: string;
+}
+export interface DeviceIdentity {
+    deviceId: string;
+    workerId: string;
+}
+export declare function assertSecureRelayUrl(relayUrl: string): void;
+export declare function loadCredentials(): Promise<WorkerCredentials | undefined>;
+export declare function loadOrCreateDeviceIdentity(): Promise<DeviceIdentity>;
+export declare function getWireCredential(credentials: WorkerCredentials): string;
+/** Owner-only permissions (0600): this file holds the worker's live secret. */
+export declare function saveCredentials(credentials: WorkerCredentials): Promise<void>;
+/** Returns false when there was nothing to remove, so callers can tell "already logged out". */
+export declare function clearCredentials(): Promise<boolean>;

package/dist/src/shared/credentials.js

@@ -0,0 +1,99 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, rm } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { ensureDir, pathExists, readJsonFile, writeJsonFile } from './fs.js';
+import { WebFlowError } from './errors.js';
+import { getCredentialsPath, getDeviceIdentityPath } from './paths.js';
+export function assertSecureRelayUrl(relayUrl) {
+    let parsed;
+    try {
+        parsed = new URL(relayUrl);
+    }
+    catch {
+        throw new WebFlowError('INVALID_RELAY_URL', `Invalid relay URL: ${relayUrl}`);
+    }
+    if (parsed.protocol !== 'wss:') {
+        throw new WebFlowError('INSECURE_RELAY_URL', 'The relay URL must use wss://. Refusing to expose worker credentials or accept commands over an insecure connection.');
+    }
+}
+function isWorkerCredentials(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return record.version === 2
+        && typeof record.appUrl === 'string'
+        && typeof record.relayUrl === 'string'
+        && typeof record.deviceId === 'string'
+        && typeof record.workerId === 'string'
+        && typeof record.credentialId === 'string'
+        && typeof record.secret === 'string'
+        && /^[a-f0-9]{64}$/.test(record.secret);
+}
+export async function loadCredentials() {
+    try {
+        const raw = await readJsonFile(getCredentialsPath());
+        if (isWorkerCredentials(raw))
+            return raw;
+        if (typeof raw === 'object' && raw !== null && ('token' in raw || raw.version === 1)) {
+            throw new WebFlowError('CREDENTIALS_REPAIR_REQUIRED', 'Saved credentials use the unsupported v1 format. Run "webflow login" to pair this device again.');
+        }
+        return undefined;
+    }
+    catch (error) {
+        if (error instanceof WebFlowError)
+            throw error;
+        return undefined;
+    }
+}
+function isDeviceIdentity(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return typeof record.deviceId === 'string' && record.deviceId.length > 0
+        && typeof record.workerId === 'string' && record.workerId.length > 0;
+}
+export async function loadOrCreateDeviceIdentity() {
+    const path = getDeviceIdentityPath();
+    try {
+        const raw = await readJsonFile(path);
+        if (isDeviceIdentity(raw))
+            return raw;
+    }
+    catch {
+        // Missing or malformed identity: replace it with a fresh stable identity.
+    }
+    let credentials;
+    try {
+        credentials = await loadCredentials();
+    }
+    catch (error) {
+        if (!(error instanceof WebFlowError) || error.code !== 'CREDENTIALS_REPAIR_REQUIRED')
+            throw error;
+        // `webflow login` is the repair path, so a legacy credential must not block it.
+    }
+    const identity = credentials
+        ? { deviceId: credentials.deviceId, workerId: credentials.workerId }
+        : { deviceId: randomUUID(), workerId: randomUUID() };
+    await ensureDir(dirname(path));
+    await writeJsonFile(path, identity);
+    await chmod(path, 0o600);
+    return identity;
+}
+export function getWireCredential(credentials) {
+    return `wkr_${credentials.credentialId}.${credentials.secret}`;
+}
+/** Owner-only permissions (0600): this file holds the worker's live secret. */
+export async function saveCredentials(credentials) {
+    const path = getCredentialsPath();
+    await ensureDir(dirname(path));
+    await writeJsonFile(path, credentials);
+    await chmod(path, 0o600);
+}
+/** Returns false when there was nothing to remove, so callers can tell "already logged out". */
+export async function clearCredentials() {
+    const path = getCredentialsPath();
+    if (!(await pathExists(path)))
+        return false;
+    await rm(path, { force: true });
+    return true;
+}