firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/native/drivers/signed-event.js

@@ -0,0 +1,244 @@
+/**
+ * signed-http-event.v1 driver (Plan20 spec 3.3).
+ *
+ * Delivers `event` steps to the approved loopback receiver (service handle URL)
+ * under the plan's `path_prefix`:
+ *  - URL path = path_prefix + payload.path (no `..`/`.` segments, no fragment,
+ *    same loopback origin);
+ *  - body bytes are exactly base64-decoded `body_base64` (never re-encoded);
+ *  - payload headers are passed through after validation (hop-by-hop, Host,
+ *    Content-Length and driver-owned names refused);
+ *  - delivery id (root's action id) in DELIVERY_ID_HEADER;
+ *  - root names the signature header (`x-firedrill-signature`) but never the key:
+ *    the key is the receiver's secret from the variable the approved plan names
+ *    (`signing_secret_env`, required because every event names the header).
+ *    HMAC-SHA256 over the exact body bytes is sent as `sha256=<lowercase hex>`.
+ *    An event that asks for a signature with no secret fails without being sent,
+ *    and is never recorded as the target's result.
+ *
+ * Retries: only when the connection is refused before it is established (no
+ * byte sent), at most `maxEventRetries` times with short backoff. Once a
+ * connection is established, a timeout, cancel or dropped connection is
+ * `unknown` (for every event step, idempotent or not) and never retried.
+ * Signature values, header values and the key never enter observations.
+ */
+import { createHmac } from 'node:crypto';
+import { CliError } from '../../http.js';
+import { NATIVE_ID, SecretValue } from '../contracts.js';
+import { sha256Hex } from '../canonical.js';
+import { LoopbackFailure, bodyPreview, failureCause, loopbackRequest } from './http.js';
+import { DRIVER_ERRORS, OwnDigest, StepRecorder, abortableDelay, driverBounds, driverPlanFor, emit, loopbackBase, planError, precheck, serviceHandle, stepAbort, stepTimeoutMs, unattested, validHeaderName, validHeaderValue, } from './types.js';
+/** Header carrying the cloud delivery id (pending root W11 freeze). */
+export const DELIVERY_ID_HEADER = 'firedrill-delivery-id';
+const FORBIDDEN_HEADERS = new Set([
+    'host', 'content-length', 'transfer-encoding', 'connection', 'keep-alive', 'upgrade', 'te', 'trailer', 'expect',
+    'proxy-authorization', 'proxy-authenticate', 'proxy-connection', DELIVERY_ID_HEADER,
+]);
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+const MAX_EVENT_HEADERS = 64;
+function validPrefix(prefix) {
+    if (!prefix.startsWith('/') || prefix.startsWith('//') || /[\\?#\r\n\0%]/.test(prefix))
+        return false;
+    return !prefix.split('/').some((segment) => segment === '..' || segment === '.');
+}
+/** Compose the delivery URL or return null when the path is not acceptable. */
+function deliveryUrl(prepared, eventPath) {
+    if (typeof eventPath !== 'string' || !eventPath.startsWith('/') || eventPath.startsWith('//') || eventPath.length > 2048)
+        return null;
+    if (/[\\#\r\n\0\s]/.test(eventPath))
+        return null;
+    const query = eventPath.indexOf('?');
+    const pathname = query === -1 ? eventPath : eventPath.slice(0, query);
+    if (pathname.split('/').some((segment) => segment === '..' || segment === '.' || /^%2e/i.test(segment) || /%2f|%5c/i.test(segment)))
+        return null;
+    let url;
+    try {
+        url = new URL(`${prepared.prefix}${eventPath}`, prepared.base);
+    }
+    catch {
+        return null;
+    }
+    if (url.origin !== prepared.base.origin)
+        return null;
+    if (url.pathname !== prepared.prefix && !url.pathname.startsWith(prepared.prefix.endsWith('/') ? prepared.prefix : `${prepared.prefix}/`))
+        return null;
+    return url;
+}
+function decodeBody(encoded) {
+    if (typeof encoded !== 'string' || !BASE64.test(encoded))
+        return null;
+    return Buffer.from(encoded, 'base64');
+}
+export class SignedEventDriver {
+    profile = 'signed-http-event.v1';
+    prepared = null;
+    sessions = new Set();
+    async describe() {
+        return { available: true, reason: null };
+    }
+    async prepare(ctx) {
+        const plan = driverPlanFor(ctx, 'signed-http-event.v1');
+        if (!validPrefix(plan.path_prefix))
+            throw planError('The approved event path prefix is not a plain absolute path, so the event driver was not prepared.');
+        const handle = serviceHandle(ctx, plan.service_alias);
+        const base = loopbackBase(handle.url, plan.service_alias);
+        const prefix = plan.path_prefix.length > 1 ? plan.path_prefix.replace(/\/+$/, '') : '';
+        const signingKey = ctx.eventSigningKey instanceof SecretValue ? ctx.eventSigningKey : null;
+        if ((plan.signing_secret_env !== undefined) !== (signingKey !== null))
+            throw planError('The approved event signing secret is not available, so the event driver was not prepared.');
+        this.prepared = { plan, base, prefix, signingKey };
+    }
+    async openSession(ctx, sessionKey) {
+        if (!this.prepared)
+            throw new CliError(DRIVER_ERRORS.session_failed, 'The event driver was not prepared, so no session was opened.');
+        const session = new SignedEventSession(ctx, this.prepared, sessionKey, () => this.sessions.delete(session));
+        this.sessions.add(session);
+        emit(ctx, 'action.observed', { type: 'session.opened', profile: this.profile, session_key: sessionKey });
+        return session;
+    }
+    /** SHA-256 of the body the entry service returned to its approved HTTP readiness check. */
+    async readinessProbe(ctx) {
+        const plan = driverPlanFor(ctx, 'signed-http-event.v1');
+        const ready = serviceHandle(ctx, plan.service_alias).ready();
+        if (ready?.kind !== 'http' || ready.body_sha256 === null) {
+            throw unattested(`The event target "${plan.service_alias}" needs an approved HTTP readiness check whose response body is at most 64 KiB before the service can admit the drill. Nothing was claimed.`);
+        }
+        return { kind: 'signed_event_handshake', response_sha256: ready.body_sha256 };
+    }
+    async dispose() {
+        for (const session of [...this.sessions])
+            await session.close();
+        this.prepared = null;
+    }
+}
+class SignedEventSession {
+    sessionKey;
+    ctx;
+    prepared;
+    onClose;
+    closed = false;
+    constructor(ctx, prepared, sessionKey, onClose) {
+        this.ctx = ctx;
+        this.prepared = prepared;
+        this.sessionKey = sessionKey;
+        this.onClose = onClose;
+    }
+    async invoke(step, signal) {
+        const { ctx, prepared } = this;
+        const bounds = driverBounds(ctx);
+        const payload = step.payload;
+        // Only the locally approved secret signs; the cloud names the header, never the key.
+        const signingKey = prepared.signingKey;
+        const recorder = new StepRecorder(ctx, step, signingKey ? [signingKey] : []);
+        if (this.closed)
+            return recorder.finish('failed', null, DRIVER_ERRORS.session_closed);
+        const refused = precheck(step, this.sessionKey, ['event']);
+        if (refused)
+            return recorder.finish('failed', null, refused);
+        if (payload.kind !== 'event')
+            return recorder.finish('failed', null, DRIVER_ERRORS.step_unsupported);
+        const invalid = (reason) => {
+            recorder.record('action.observed', { type: 'event.refused', delivery_id: payload.delivery_id, reason });
+            return recorder.finish('failed', null, DRIVER_ERRORS.event_invalid);
+        };
+        if (typeof payload.delivery_id !== 'string' || !NATIVE_ID.test(payload.delivery_id))
+            return invalid('delivery id is not a valid identifier');
+        if (payload.method !== 'POST' && payload.method !== 'PUT' && payload.method !== 'PATCH')
+            return invalid('method is not POST, PUT or PATCH');
+        const url = deliveryUrl(prepared, payload.path);
+        if (!url)
+            return invalid('path is not a plain path under the approved prefix');
+        const body = decodeBody(payload.body_base64);
+        if (!body)
+            return invalid('body is not valid base64');
+        const headers = {};
+        const seen = new Set();
+        const entries = Object.entries(payload.headers ?? {});
+        if (entries.length > MAX_EVENT_HEADERS)
+            return invalid('too many headers');
+        const signatureHeader = payload.signature_header;
+        // Never sent unsigned when a signature is asked for; with no header named, nothing is signed.
+        if (signatureHeader && signingKey === null)
+            return invalid('the event asks for a signature but the approved plan names no signing secret');
+        if (signatureHeader && (!validHeaderName(signatureHeader) || FORBIDDEN_HEADERS.has(signatureHeader.toLowerCase())))
+            return invalid('signature header name is not allowed');
+        for (const [name, value] of entries) {
+            const lower = name.toLowerCase();
+            if (!validHeaderName(name) || typeof value !== 'string' || !validHeaderValue(value))
+                return invalid('a header name or value is not allowed');
+            if (FORBIDDEN_HEADERS.has(lower) || lower.startsWith('proxy-') || seen.has(lower))
+                return invalid('a header is reserved or duplicated');
+            if (signatureHeader && lower === signatureHeader.toLowerCase())
+                return invalid('a header collides with the signature header');
+            seen.add(lower);
+            headers[name] = value;
+        }
+        headers[DELIVERY_ID_HEADER] = payload.delivery_id;
+        if (signingKey && signatureHeader)
+            headers[signatureHeader] = `sha256=${createHmac('sha256', signingKey.reveal()).update(body).digest('hex')}`;
+        recorder.record('action.observed', {
+            type: 'event.delivery', delivery_id: payload.delivery_id, method: payload.method, path: `${url.pathname}${url.search}`,
+            body_bytes: body.byteLength, body_sha256: new OwnDigest(sha256Hex(body)), body_preview: bodyPreview(body, ctx.secrets),
+            header_names: Object.keys(headers).filter((name) => name !== signatureHeader), signed: !!signingKey,
+        });
+        const abort = stepAbort(ctx, signal, stepTimeoutMs(step, bounds));
+        let attempts = 0;
+        try {
+            for (;;) {
+                attempts += 1;
+                try {
+                    const response = await loopbackRequest({
+                        url, method: payload.method, headers, body, signal: abort.signal, maxBytes: bounds.maxResponseBytes,
+                    });
+                    const ok = response.status >= 200 && response.status < 300;
+                    const text = bodyPreview(response.body, ctx.secrets, bounds.maxResponseBytes);
+                    let parsed = text;
+                    try {
+                        parsed = text ? JSON.parse(text) : null;
+                    }
+                    catch {
+                        parsed = text;
+                    }
+                    const output = { status: response.status, delivery_id: payload.delivery_id, body: parsed };
+                    recorder.record('action.observed', { type: 'event.response', delivery_id: payload.delivery_id, status: response.status, attempts, body: parsed });
+                    const result = recorder.finish(ok ? 'completed' : 'failed', output, ok ? null : DRIVER_ERRORS.target_status);
+                    // bodyPreview can already redact or clip before StepRecorder sees it.
+                    // Carry that producer fact without retaining the original body.
+                    if (text !== response.body.toString('utf8'))
+                        result.output_coverage = 'redacted';
+                    return result;
+                }
+                catch (error) {
+                    if (error instanceof LoopbackFailure && error.kind === 'refused' && !error.written && attempts <= bounds.maxEventRetries) {
+                        try {
+                            await abortableDelay(100 * 2 ** (attempts - 1), abort.signal);
+                            continue;
+                        }
+                        catch {
+                            return recorder.interrupted(abort.cause() ?? 'cancelled', false, { unknownAfterWrite: true });
+                        }
+                    }
+                    throw error;
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof LoopbackFailure) {
+                recorder.record('action.observed', { type: 'event.interrupted', delivery_id: payload.delivery_id, attempts, cause: error.kind });
+                return recorder.interrupted(failureCause(error, abort.cause()), error.written, { unknownAfterWrite: true });
+            }
+            if (error instanceof CliError)
+                return recorder.finish('failed', null, error.code);
+            return recorder.interrupted('thrown', true, { unknownAfterWrite: true });
+        }
+        finally {
+            abort.dispose();
+        }
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.onClose();
+    }
+}