firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/configuration-intents.js

@@ -0,0 +1,277 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, unlink } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { api } from './auth.js';
+import { privateDirectory } from './credentials.js';
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+const MAX_BYTES = 256 * 1024, VARIABLE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const invalid = () => new CliError('configuration_input_invalid', 'Use the exact configuration metadata. Values and credentials belong in Vault, not this JSON file.', 2);
+export const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const fields = (value, required, optional = []) => required.every(key => Object.hasOwn(value, key))
+    && Object.keys(value).every(key => required.includes(key) || optional.includes(key));
+const revision = (value) => Number.isSafeInteger(value) && Number(value) >= 0;
+const text = (value, maximum) => typeof value === 'string' && value.length <= maximum && !/[\u0000-\u001f\u007f]/.test(value)
+    && Buffer.from(value).toString('utf8') === value;
+const scopedKind = (kind, resource) => (resource !== null) === ['dependency', 'model_remove'].includes(kind);
+function canonical(value) {
+    if (value === null || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (typeof value === 'string' && Buffer.from(value).toString('utf8') === value)
+        return JSON.stringify(value);
+    if (typeof value === 'number' && Number.isSafeInteger(value))
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (record(value))
+        return '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}';
+    throw invalid();
+}
+const fingerprint = (kind, service_id, body) => createHash('sha256').update(canonical({ kind, service_id, body })).digest('hex');
+export function inputSchema(kind) {
+    const variable = { type: 'string', pattern: '^[A-Za-z_][A-Za-z0-9_]{0,127}$' };
+    const version = { type: 'integer', minimum: 0, maximum: Number.MAX_SAFE_INTEGER };
+    const schema = (properties, required, rest = {}) => ({ type: 'object', additionalProperties: false, properties, required, ...rest });
+    if (kind === 'model_remove')
+        return { $schema: 'https://json-schema.org/draft/2020-12/schema',
+            ...schema({ configuration_revision: version }, ['configuration_revision']) };
+    if (kind === 'model')
+        return { $schema: 'https://json-schema.org/draft/2020-12/schema', ...schema({
+                configuration_revision: version, mapping_id: { type: 'string', format: 'uuid' }, provider: { enum: ['anthropic', 'openai'] },
+                base_url_variable: variable, models: { type: 'array', minItems: 1, maxItems: 1000, uniqueItems: true,
+                    items: { type: 'string', pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$' } }, authorize_target_model_usage: { const: true }
+            }, ['configuration_revision', 'mapping_id', 'provider', 'base_url_variable', 'models', 'authorize_target_model_usage']) };
+    if (kind === 'mappings')
+        return { $schema: 'https://json-schema.org/draft/2020-12/schema', ...schema({ revision: version,
+                mappings: { type: 'array', minItems: 1, items: schema({ name: variable, phase: { enum: ['build', 'runtime', 'both'] },
+                        source: { enum: ['unset', 'vault', 'default', 'world', 'local', 'remove'] }, vault_entry_id: { type: ['string', 'null'], format: 'uuid' },
+                        binding_key: { type: 'string', maxLength: 255 }, dependency_key: { type: 'string', maxLength: 255 } }, ['name', 'phase', 'source']) } }, ['revision', 'mappings']) };
+    const versions = { configuration_revision: version, service_revision: { ...version, minimum: 1 } };
+    return { $schema: 'https://json-schema.org/draft/2020-12/schema', oneOf: [schema({ ...versions, mode: { const: 'unselected' } }, ['mode', 'configuration_revision', 'service_revision']), schema({ ...versions, mode: { const: 'simulated' },
+                catalog: schema({ implementation_id: { type: 'string', format: 'uuid' }, package_service_key: { type: 'string', pattern: '^[a-z][a-z0-9_-]{0,79}$' } }, ['implementation_id', 'package_service_key']) }, ['mode', 'configuration_revision', 'service_revision']), schema({ ...versions, mode: { const: 'real' },
+                allowed_hosts: { type: 'array', minItems: 1, items: { type: 'string', minLength: 1, maxLength: 253 } },
+                allow_all_operations: { type: 'boolean' }, operation_names: { type: 'array', items: { type: 'string', minLength: 1, maxLength: 255 } },
+                acknowledge_external_effects: { const: true }, allow_write_effects: { type: 'boolean' },
+                http_binding: schema({ base_url: { type: 'string', format: 'uri', maxLength: 2048 }, endpoint_variable: variable,
+                    authentication: { type: 'array', maxItems: 16, items: schema({ variable, header: { type: 'string', pattern: '^[A-Za-z][A-Za-z0-9-]{0,63}$' },
+                            prefix: { type: 'string', pattern: '^(?:[A-Za-z][A-Za-z0-9_-]{0,31} )?$' } }, ['variable', 'header', 'prefix']) } }, ['base_url', 'endpoint_variable', 'authentication']) }, ['mode', 'configuration_revision', 'service_revision', 'allowed_hosts', 'acknowledge_external_effects', 'http_binding'], { anyOf: [{ required: ['allow_all_operations'], properties: { allow_all_operations: { const: true } } },
+                    { required: ['operation_names'], properties: { operation_names: { minItems: 1 } } }] })] };
+}
+/** Metadata allowlist before any local recovery record is written. */
+export function validateBody(kind, body) {
+    if (kind === 'model_remove') {
+        if (!fields(body, ['configuration_revision']) || !revision(body.configuration_revision))
+            throw invalid();
+        return;
+    }
+    if (kind === 'model') {
+        if (!fields(body, ['configuration_revision', 'mapping_id', 'provider', 'base_url_variable', 'models', 'authorize_target_model_usage'])
+            || !revision(body.configuration_revision) || typeof body.mapping_id !== 'string'
+            || typeof body.provider !== 'string' || !['anthropic', 'openai'].includes(body.provider)
+            || typeof body.base_url_variable !== 'string' || !VARIABLE.test(body.base_url_variable)
+            || !Array.isArray(body.models) || !body.models.length || body.models.length > 1000 || new Set(body.models).size !== body.models.length
+            || body.models.some(one => typeof one !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(one))
+            || body.authorize_target_model_usage !== true)
+            throw invalid();
+        identifier(body.mapping_id);
+        return;
+    }
+    if (kind === 'mappings') {
+        if (!fields(body, ['revision', 'mappings']) || !revision(body.revision) || !Array.isArray(body.mappings) || !body.mappings.length)
+            throw invalid();
+        const seen = new Set();
+        for (const row of body.mappings) {
+            if (!record(row) || !fields(row, ['name', 'phase', 'source'], ['vault_entry_id', 'binding_key', 'dependency_key'])
+                || typeof row.name !== 'string' || !VARIABLE.test(row.name) || typeof row.phase !== 'string' || !['build', 'runtime', 'both'].includes(row.phase)
+                || typeof row.source !== 'string' || !['unset', 'vault', 'default', 'world', 'local', 'remove'].includes(row.source)
+                || ['binding_key', 'dependency_key'].some(key => row[key] !== undefined && !text(row[key], 255)))
+                throw invalid();
+            if (row.vault_entry_id !== undefined && row.vault_entry_id !== null)
+                identifier(String(row.vault_entry_id));
+            if (row.source === 'vault' && typeof row.vault_entry_id !== 'string' || row.source === 'world' && !row.binding_key)
+                throw invalid();
+            if (row.source === 'local')
+                identifier(String(row.binding_key));
+            const key = row.name + ':' + row.phase;
+            if (seen.has(key))
+                throw invalid();
+            seen.add(key);
+        }
+        return;
+    }
+    if (!fields(body, ['mode', 'configuration_revision', 'service_revision'], ['allowed_hosts', 'allow_all_operations', 'operation_names',
+        'acknowledge_external_effects', 'allow_write_effects', 'http_binding', 'catalog']) || !revision(body.configuration_revision)
+        || !Number.isSafeInteger(body.service_revision) || Number(body.service_revision) < 1
+        || typeof body.mode !== 'string' || !['simulated', 'real', 'unselected'].includes(body.mode))
+        throw invalid();
+    if (body.catalog !== undefined) {
+        if (body.mode !== 'simulated' || !record(body.catalog) || !fields(body.catalog, ['implementation_id', 'package_service_key'])
+            || typeof body.catalog.implementation_id !== 'string' || typeof body.catalog.package_service_key !== 'string'
+            || !/^[a-z][a-z0-9_-]{0,79}$/.test(body.catalog.package_service_key))
+            throw invalid();
+        identifier(body.catalog.implementation_id);
+    }
+    for (const key of ['allow_all_operations', 'acknowledge_external_effects', 'allow_write_effects'])
+        if (body[key] !== undefined && typeof body[key] !== 'boolean')
+            throw invalid();
+    if (body.operation_names !== undefined && (!Array.isArray(body.operation_names) || body.operation_names.some(one => !text(one, 255) || !one)))
+        throw invalid();
+    if (body.allowed_hosts !== undefined && (!Array.isArray(body.allowed_hosts) || body.allowed_hosts.some(one => !text(one, 253) || !one || /[\s/:?#@*\\]/.test(String(one)))))
+        throw invalid();
+    if (body.mode === 'real') {
+        const binding = body.http_binding;
+        if (!record(binding) || !fields(binding, ['base_url', 'endpoint_variable', 'authentication']) || !text(binding.base_url, 2048)
+            || typeof binding.endpoint_variable !== 'string' || !VARIABLE.test(binding.endpoint_variable)
+            || !Array.isArray(binding.authentication) || binding.authentication.length > 16
+            || body.acknowledge_external_effects !== true || !Array.isArray(body.allowed_hosts) || !body.allowed_hosts.length
+            || body.allow_all_operations !== true && (!Array.isArray(body.operation_names) || !body.operation_names.length))
+            throw invalid();
+        const url = new URL(String(binding.base_url));
+        if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.port && url.port !== '443'
+            || !body.allowed_hosts.includes(url.hostname) || !/^(?:\/[A-Za-z0-9_~.-]+)*\/?$/.test(url.pathname))
+            throw invalid();
+        const names = new Set([binding.endpoint_variable]), headers = new Set();
+        for (const row of binding.authentication) {
+            if (!record(row) || !fields(row, ['variable', 'header', 'prefix']) || typeof row.variable !== 'string' || !VARIABLE.test(row.variable)
+                || names.has(row.variable) || typeof row.header !== 'string' || !/^[A-Za-z][A-Za-z0-9-]{0,63}$/.test(row.header)
+                || headers.has(row.header.toLowerCase()) || typeof row.prefix !== 'string' || !/^(?:[A-Za-z][A-Za-z0-9_-]{0,31} )?$/.test(row.prefix))
+                throw invalid();
+            names.add(row.variable);
+            headers.add(row.header.toLowerCase());
+        }
+    }
+    else if (body.http_binding !== undefined)
+        throw invalid();
+}
+export async function readMetadata(path, privateFile = false) {
+    const before = await lstat(resolve(path));
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size < 2 || before.size > MAX_BYTES
+        || privateFile && (process.getuid && before.uid !== process.getuid() || process.platform !== 'win32' && !!(before.mode & 0o077)))
+        throw invalid();
+    const file = await open(resolve(path), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const actual = await file.stat();
+        if (!actual.isFile() || actual.ino !== before.ino || actual.dev !== before.dev || actual.size !== before.size || actual.mtimeMs !== before.mtimeMs)
+            throw invalid();
+        const buffer = Buffer.alloc(actual.size);
+        let offset = 0;
+        while (offset < buffer.length) {
+            const part = await file.read(buffer, offset, buffer.length - offset, offset);
+            if (!part.bytesRead)
+                throw invalid();
+            offset += part.bytesRead;
+        }
+        const after = await file.stat();
+        if (after.size !== actual.size || after.mtimeMs !== actual.mtimeMs || after.ctimeMs !== actual.ctimeMs)
+            throw invalid();
+        const value = JSON.parse(new TextDecoder('utf8', { fatal: true }).decode(buffer));
+        if (!record(value))
+            throw invalid();
+        return value;
+    }
+    catch {
+        throw invalid();
+    }
+    finally {
+        await file.close();
+    }
+}
+const location = async (scope, key) => join(await privateDirectory(), `configuration-${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(key)}.json`);
+export async function retained(scope, key) {
+    const value = await readMetadata(await location(scope, key), true);
+    if (!fields(value, ['schema', 'owner', 'workspace', 'world', 'key', 'kind', 'service_id', 'body', 'digest'])
+        || value.schema !== 'firedrill.local-configuration-intent.v1' || value.owner !== scope.owner || value.workspace !== scope.workspace
+        || value.key !== identifier(key) || typeof value.world !== 'string' || !record(value.body)
+        || typeof value.kind !== 'string' || !['mappings', 'dependency', 'model', 'model_remove'].includes(value.kind)
+        || !scopedKind(value.kind, value.service_id))
+        throw invalid();
+    identifier(value.world);
+    if (value.service_id !== null && (typeof value.service_id !== 'string' || identifier(value.service_id) !== value.service_id))
+        throw invalid();
+    validateBody(value.kind, value.body);
+    if (value.digest !== fingerprint(value.kind, value.service_id, value.body))
+        throw invalid();
+    return value;
+}
+function verify(receipt, intent) {
+    if (receipt.schema !== 'firedrill.configuration-command.v1' || receipt.request_key !== intent.key || receipt.world_id !== intent.world
+        || !['not_received', 'accepted', 'withdrawn'].includes(receipt.state)
+        || receipt.state !== 'not_received' && (receipt.request_digest !== intent.digest || receipt.kind !== intent.kind || receipt.service_id !== intent.service_id)
+        || receipt.state === 'accepted' && !revision(receipt.configuration_revision) || typeof receipt.current !== 'boolean')
+        throw invalid();
+}
+function show(receipt, output) {
+    output('result', receipt, receipt.state === 'accepted' ? `Configuration saved at revision ${receipt.configuration_revision}.${receipt.current ? '' : ' The world has changed since this request.'}`
+        : receipt.state === 'withdrawn' ? 'Configuration request withdrawn. It cannot change the world.'
+            : 'No accepted configuration receipt is visible. The original request may still arrive; withdraw it to prevent a late change.');
+}
+export async function submit(intent, context, signal, output) {
+    if (context.world !== intent.world || context.owner !== intent.owner || context.workspace !== intent.workspace)
+        throw invalid();
+    output('configuration_request', { request_key: intent.key, kind: intent.kind, request_digest: intent.digest }, `Request: ${intent.key}\nIf the reply is interrupted: firedrill configuration status --workspace ${intent.workspace} --request-key ${intent.key}`);
+    const resource = intent.kind === 'mappings' ? '/configuration' : intent.kind === 'model' ? '/model-connections'
+        : intent.kind === 'model_remove' ? '/model-connections/' + identifier(intent.service_id) : '/dependencies/' + identifier(intent.service_id);
+    const method = intent.kind === 'mappings' ? 'PATCH' : intent.kind === 'model' ? 'POST' : intent.kind === 'model_remove' ? 'DELETE' : 'PUT';
+    const result = await api(context.prefix + resource, { actor: context.owner, workspace: context.workspace, signal, method, idempotencyKey: intent.key, body: intent.body });
+    verify(result.configuration_receipt, intent);
+    if (result.configuration_receipt.state !== 'accepted')
+        throw invalid();
+    show(result.configuration_receipt, output);
+}
+export async function remember(context, kind, service, body, request, signal, output) {
+    validateBody(kind, body);
+    if (!scopedKind(kind, service))
+        throw invalid();
+    if (service !== null)
+        service = identifier(service);
+    const key = request ? identifier(request) : randomUUID();
+    const intent = { schema: 'firedrill.local-configuration-intent.v1', owner: context.owner, workspace: context.workspace,
+        world: context.world, key, kind, service_id: service, body, digest: fingerprint(kind, service, body) };
+    const encoded = JSON.stringify(intent);
+    if (Buffer.byteLength(encoded) > MAX_BYTES)
+        throw invalid();
+    try {
+        const file = await open(await location(context, key), 'wx', 0o600);
+        try {
+            await file.writeFile(encoded);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'EEXIST')
+            throw error;
+        const prior = await retained(context, key);
+        if (prior.world !== context.world || prior.digest !== intent.digest || prior.kind !== kind || prior.service_id !== service)
+            throw invalid();
+    }
+    return submit(intent, context, signal, output);
+}
+export async function requestAction(context, intent, action, signal, output) {
+    if (context.world !== intent.world || context.owner !== intent.owner || context.workspace !== intent.workspace)
+        throw invalid();
+    if (action === 'forget') {
+        await unlink(await location(context, intent.key));
+        output('result', { request_key: intent.key, local_copy_removed: true }, 'Local recovery copy removed. Any accepted or delayed server request is unchanged.');
+        return;
+    }
+    const receipt = await api(`${context.prefix}/configuration-requests/${identifier(intent.key)}`, { actor: context.owner,
+        workspace: context.workspace, signal, ...(action === 'withdraw' ? { method: 'DELETE', body: {
+                kind: intent.kind, service_id: intent.service_id, request_digest: intent.digest
+            } } : {}) });
+    verify(receipt, intent);
+    if (action === 'withdraw' && receipt.state === 'accepted') {
+        output('result', receipt, `This request was already accepted at configuration revision ${receipt.configuration_revision}. It was not undone.`);
+        return;
+    }
+    if (action !== 'resume' || receipt.state !== 'not_received') {
+        show(receipt, output);
+        return;
+    }
+    // Explicit resume repeats the SAME approved metadata request under the SAME
+    // transaction receipt. It never creates another revision or real operation.
+    return submit(intent, context, signal, output);
+}