firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/native/target-auth.js

@@ -0,0 +1,161 @@
+/**
+ * Synthetic target-user identity (Plan20 W10, spec 3.4).
+ *
+ * Supported modes, from the descriptor's `driver.authentication`:
+ *  - `anonymous`         -> nothing is injected.
+ *  - `synthetic-session` -> a granted session token goes into the declared header
+ *                           (HTTP / JSON-lines drivers), and/or the Playwright flow
+ *                           performs the target's real login with the granted
+ *                           synthetic username/password through a login accessor.
+ *
+ * Credentials never enter env, argv, URLs, logs or observation content. The
+ * password is reachable only through `PlaywrightLoginAccessor.revealPassword()`,
+ * and the session token only through `identityHeaders()` at the request
+ * injection point. MFA, passkeys, OAuth/OIDC/SAML issuers and any other mode are
+ * unsupported and refused with `native_auth_unsupported`; nothing falls back to a
+ * real account.
+ */
+import { inspect } from 'node:util';
+import { CliError } from '../http.js';
+import { isValidHeaderName } from './bindings.js';
+export const AUTH_ERRORS = {
+    unsupported: 'native_auth_unsupported',
+    invalid: 'native_identity_invalid',
+};
+function authUnsupported(message) { return new CliError(AUTH_ERRORS.unsupported, message); }
+function identityInvalid(message) { return new CliError(AUTH_ERRORS.invalid, message); }
+/** Grant fields that would indicate an authentication flow this client does not implement. */
+const UNSUPPORTED_GRANT_FIELDS = ['mfa', 'totp', 'otp', 'otp_secret', 'passkey', 'webauthn', 'issuer', 'oauth', 'oidc',
+    'saml', 'sso', 'client_id', 'client_secret', 'refresh_token', 'authorization_url'];
+/**
+ * Check a grant against the descriptor before any drill starts. Returns the grant
+ * (or null for anonymous). Throws:
+ *  - native_auth_unsupported when the descriptor or grant uses a mode or factor
+ *    this client does not implement (MFA, passkeys, external issuers, unknown modes);
+ *  - native_identity_invalid when the grant mode does not match the descriptor,
+ *    a synthetic-session grant is missing, expired, or carries no usable credential.
+ */
+export function validateIdentityGrant(grant, descriptor, options = {}) {
+    const expected = descriptor.driver.authentication;
+    if (expected !== 'anonymous' && expected !== 'synthetic-session') {
+        throw authUnsupported('The target identity was not prepared: the descriptor names an authentication mode this client does not support.');
+    }
+    if (grant && typeof grant === 'object') {
+        const record = grant;
+        if (UNSUPPORTED_GRANT_FIELDS.some((field) => record[field] !== undefined && record[field] !== null)) {
+            throw authUnsupported('The target identity was not prepared: MFA, passkeys and external identity issuers are not supported for native drills.');
+        }
+        if (grant.mode !== 'anonymous' && grant.mode !== 'synthetic-session') {
+            throw authUnsupported('The target identity was not prepared: the grant uses an authentication mode this client does not support.');
+        }
+    }
+    if (expected === 'anonymous') {
+        if (grant && grant.mode !== 'anonymous') {
+            throw identityInvalid('The target identity was not used: the grant mode does not match the descriptor (anonymous).');
+        }
+        return grant ?? null;
+    }
+    if (!grant) {
+        throw identityInvalid('The drill was not started: the descriptor requires a synthetic session and no identity was granted.');
+    }
+    if (grant.mode !== 'synthetic-session') {
+        throw identityInvalid('The target identity was not used: the grant mode does not match the descriptor (synthetic-session).');
+    }
+    const now = options.now ?? Date.now();
+    // A synthetic session must be short-lived: a missing expiry is refused, not treated as unbounded.
+    const at = typeof grant.expires_at === 'string' ? Date.parse(grant.expires_at) : Number.NaN;
+    if (!Number.isFinite(at) || at <= now) {
+        throw identityInvalid('The target identity was not used: the synthetic identity grant has expired or has no valid expiry.');
+    }
+    const hasToken = !!grant.session_token;
+    const hasLogin = typeof grant.username === 'string' && grant.username.length > 0 && !!grant.password;
+    if (!hasToken && !hasLogin) {
+        throw identityInvalid('The target identity was not used: the synthetic identity grant carries neither a session token nor login credentials.');
+    }
+    if (hasToken && (typeof grant.session_header !== 'string' || !isValidHeaderName(grant.session_header))) {
+        throw identityInvalid('The target identity was not used: the session token has no allowed header name.');
+    }
+    if (grant.password && !hasLogin) {
+        throw identityInvalid('The target identity was not used: a synthetic password was granted without a username.');
+    }
+    return grant;
+}
+/**
+ * Environment contribution for the target identity. Always empty for the
+ * supported modes: identity credentials are never placed in env. `secrets`
+ * lists every identity credential so the supervisor and drivers can redact
+ * them from captured output.
+ */
+export function identityEnv(grant) {
+    return { env: {}, secrets: identitySecrets(grant) };
+}
+/** All secret material in a grant, for redaction lists. */
+export function identitySecrets(grant) {
+    if (!grant)
+        return [];
+    return [grant.session_token, grant.password].filter((value) => !!value);
+}
+/**
+ * Request headers carrying the synthetic session for HTTP / JSON-lines drivers.
+ * Reveals the session token: call only when building the outgoing request and
+ * never log the result. Anonymous or login-only grants return `{}`. The token is
+ * sent raw unless the grant's session_scheme is 'bearer'.
+ */
+export function identityHeaders(grant) {
+    if (!grant || grant.mode !== 'synthetic-session' || !grant.session_token)
+        return {};
+    const header = grant.session_header;
+    if (typeof header !== 'string' || !isValidHeaderName(header)) {
+        throw identityInvalid('The target identity was not used: the session token has no allowed header name.');
+    }
+    const value = grant.session_token.reveal();
+    if (!value || value.length > 8192 || /[\u0000-\u001f\u007f]/.test(value)) {
+        throw identityInvalid('The target identity was not used: the session token cannot be sent as a header.');
+    }
+    return { [header]: grant.session_scheme === 'bearer' ? `Bearer ${value}` : value };
+}
+// ---------------------------------------------------------------------------
+// Playwright login accessor. The only path from a granted password to the
+// target, and only inside the approved flow's `login(page, identity)`.
+const accessorPasswords = new WeakMap();
+export class PlaywrightLoginAccessor {
+    /** Synthetic account username (not a production account). */
+    username;
+    subject;
+    roles;
+    constructor(username, password, subject, roles) {
+        this.username = username;
+        this.subject = subject;
+        this.roles = Object.freeze([...roles]);
+        accessorPasswords.set(this, password);
+    }
+    /** Reveal the password for typing into the target's login form. Never log, store or navigate with it. */
+    revealPassword() {
+        const secret = accessorPasswords.get(this);
+        if (!secret)
+            throw identityInvalid('The login was not performed: the synthetic password is no longer available.');
+        return secret.reveal();
+    }
+    /** Drop the password once the login step is finished. */
+    dispose() { accessorPasswords.delete(this); }
+    toJSON() { return { username: '[redacted]', subject: this.subject, roles: [...this.roles] }; }
+    toString() { return '[playwright-login]'; }
+    [inspect.custom]() { return '[playwright-login]'; }
+}
+/**
+ * Login accessor for the Playwright flow, or null when the grant has no
+ * username/password (anonymous, or token-only sessions). The username is kept
+ * out of env/argv too, and redacted from JSON, because it identifies the seeded
+ * synthetic account.
+ */
+export function playwrightLogin(grant) {
+    if (!grant || grant.mode !== 'synthetic-session')
+        return null;
+    if (typeof grant.username !== 'string' || !grant.username || !grant.password)
+        return null;
+    return new PlaywrightLoginAccessor(grant.username, grant.password, grant.subject, grant.roles ?? []);
+}
+/** Explicit refusal for a requested factor or issuer the client does not implement. */
+export function assertAuthSupported(feature) {
+    throw authUnsupported(`The target identity was not prepared: ${feature} authentication is not supported for native drills.`);
+}

package/dist/cli/src/native/target-state.js

@@ -0,0 +1,330 @@
+/**
+ * Per-drill target state handling (Plan20 W10, spec 3.4).
+ *
+ * For every declared state domain the descriptor names a reset policy. This
+ * module turns those into per-drill actions, runs approved reset hooks, records
+ * what the supervisor and driver report, and produces
+ * `AssignmentCompletion.state_coverage`.
+ *
+ *  - fresh-process  -> needs a per-drill launch service copy; `applied` only when
+ *                      the supervisor reports it started a fresh process for this drill.
+ *  - fresh-session  -> a new driver session / browser context per drill; `applied`
+ *                      when the driver reports the new session. Only `session` and
+ *                      `browser` domains can be reset this way: a new browser context
+ *                      does not reset backend storage (database, files, cache, queue,
+ *                      vector, scheduler, process), so those report `unavailable`.
+ *  - approved-hook  -> re-hash the hook file from disk, compare to the descriptor
+ *                      and plan digests, run it with the plan runtime argv (shell:false,
+ *                      minimal env, bounded time/output). Exit 0 is reported evidence
+ *                      (`applied`), not proof the state was reset; anything else is `failed`.
+ *  - unavailable, or location `observation-only` -> `unavailable`, and drills run serially.
+ *  - location `cloud-disposable` -> reset is cloud-owned; reported `not-applicable` locally.
+ *
+ * Results are client-reported evidence; the cloud remains authoritative.
+ */
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { nativeError } from './contracts.js';
+import { sha256Hex } from './canonical.js';
+import { insideRoot } from './roots.js';
+import { ownGroup, sweepGroup } from './owned-groups.js';
+const SESSION_RESETTABLE = new Set(['session', 'browser']);
+function planDomain(domain, plan) {
+    const base = {
+        alias: domain.alias, service_alias: domain.service_alias, kind: domain.kind, reset: domain.reset,
+        hook: null, descriptor_hook_sha256: domain.hook_sha256,
+    };
+    const declaredSerial = domain.concurrency === 'serial';
+    if (domain.location === 'observation-only') {
+        return { ...base, action: 'unavailable', serial: true, reason: 'The domain is observation-only; it is not reset locally.' };
+    }
+    if (domain.location === 'cloud-disposable') {
+        return { ...base, action: 'not-applicable', serial: declaredSerial, reason: 'The domain is cloud-disposable; its reset is cloud-owned.' };
+    }
+    switch (domain.reset) {
+        case 'unavailable':
+            return { ...base, action: 'unavailable', serial: true, reason: 'The descriptor declares no reset for this domain.' };
+        case 'fresh-session':
+            if (!SESSION_RESETTABLE.has(domain.kind)) {
+                return { ...base, action: 'unavailable', serial: true,
+                    reason: `A fresh driver session does not reset ${domain.kind} state, so this domain is not reset.` };
+            }
+            return { ...base, action: 'fresh-session', serial: declaredSerial, reason: null };
+        case 'fresh-process': {
+            const service = plan.services.find((entry) => entry.alias === domain.service_alias);
+            if (!service || service.mode !== 'launch' || !service.per_drill) {
+                throw nativeError('state_unsupported', `State domain "${domain.alias}" cannot be reset: fresh-process needs its service launched as a per-drill copy in the approved plan. No drill was started.`);
+            }
+            return { ...base, action: 'fresh-process', serial: declaredSerial, reason: null };
+        }
+        case 'approved-hook': {
+            const hooks = plan.state_hooks.filter((entry) => entry.domain_alias === domain.alias);
+            if (hooks.length !== 1) {
+                throw nativeError('state_unsupported', `State domain "${domain.alias}" cannot be reset: the approved plan must name exactly one hook for it. No drill was started.`);
+            }
+            const hook = hooks[0];
+            if (!domain.hook_sha256 || hook.sha256 !== domain.hook_sha256) {
+                throw nativeError('plan_changed', `State domain "${domain.alias}" was not reset: the plan hook digest does not match the descriptor. Approve the plan again.`);
+            }
+            return { ...base, action: 'approved-hook', serial: declaredSerial, reason: null, hook };
+        }
+        default:
+            throw nativeError('state_unsupported', `State domain "${domain.alias}" cannot be reset: its reset policy is not supported by this client.`);
+    }
+}
+/** Resolve every declared state domain to a per-drill action. Throws before any drill when the plan cannot honour a policy. */
+export function planStateActions(descriptor, plan) {
+    const actions = descriptor.state_domains.map((domain) => planDomain(domain, plan));
+    return { actions, serial: actions.some((action) => action.serial) };
+}
+/**
+ * 1 when the descriptor declares no state domains (isolation unknown, matching
+ * normalizeDescriptor's requires_serial_execution and the approval text) or any
+ * domain is serial (declared serial, unavailable or observation-only);
+ * otherwise the plan limit (at least 1).
+ */
+export function effectiveParallelism(descriptor, plan) {
+    if (descriptor.state_domains.length === 0 || planStateActions(descriptor, plan).serial)
+        return 1;
+    const limit = Math.floor(plan.max_parallel_drills);
+    return Number.isFinite(limit) && limit > 1 ? limit : 1;
+}
+const DEFAULT_HOOK_TIMEOUT_MS = 60_000;
+const MAX_HOOK_TIMEOUT_MS = 600_000;
+const DEFAULT_OUTPUT_BYTES = 16 * 1024;
+const MAX_OUTPUT_BYTES = 256 * 1024;
+/** After the hook exits, how long its output may still drain before the pipes are released. */
+const EXIT_DRAIN_MS = 500;
+/** After a timeout or cancel kill, how long to wait for the hook to exit before reporting the stop anyway. */
+const KILL_GRACE_MS = 5_000;
+function hookEnv(domainAlias, drillKey) {
+    const names = process.platform === 'win32'
+        ? ['PATH', 'SystemRoot', 'TEMP', 'TMP', 'USERPROFILE', 'PATHEXT', 'ComSpec', 'LANG']
+        : ['PATH', 'HOME', 'LANG', 'TMPDIR'];
+    const env = {};
+    for (const name of names) {
+        const value = process.env[name];
+        if (typeof value === 'string')
+            env[name] = value;
+    }
+    env.FIREDRILL_STATE_DOMAIN = domainAlias;
+    if (drillKey)
+        env.FIREDRILL_DRILL_KEY = drillKey;
+    return env;
+}
+function failedRun(domainAlias, code, started) {
+    return { domain_alias: domainAlias, result: 'failed', error_code: code, exit_code: null, signal: null,
+        duration_ms: Date.now() - started, output_tail_unredacted: '', output_truncated: false };
+}
+/**
+ * Re-hash and run one approved hook. Never throws for hook failure; returns a
+ * `failed` run with a stable code instead. The hook file is hashed immediately
+ * before launch; the runtime then reads the same path (a change in between is a
+ * local trust boundary this client cannot close without an OS sandbox).
+ */
+export async function runApprovedHook(action, ctx) {
+    const started = Date.now();
+    const hook = action.hook;
+    if (action.action !== 'approved-hook' || !hook)
+        return failedRun(action.alias, 'native_state_unsupported', started);
+    if (ctx.signal.aborted)
+        return failedRun(action.alias, 'native_hook_cancelled', started);
+    const root = ctx.plan.roots.find((entry) => entry.alias === hook.root_alias);
+    if (!root)
+        return failedRun(action.alias, 'native_root_outside', started);
+    let hookPath;
+    try {
+        hookPath = await insideRoot(root.path, hook.path);
+    }
+    catch {
+        return failedRun(action.alias, 'native_root_outside', started);
+    }
+    let digest;
+    try {
+        digest = sha256Hex(await readFile(hookPath));
+    }
+    catch {
+        return failedRun(action.alias, 'native_hook_unavailable', started);
+    }
+    if (digest !== hook.sha256 || digest !== action.descriptor_hook_sha256)
+        return failedRun(action.alias, 'native_plan_changed', started);
+    // The hook runs in place (not from a copy) so its own relative imports keep
+    // working. A same-user process could swap the file between this hash check and
+    // the runtime reading it; that is outside the native trust model (the user's
+    // own code is trusted), and the hash still detects ordinary edits.
+    if (typeof hook.runtime?.executable !== 'string' || !hook.runtime.executable || !Array.isArray(hook.runtime.args)) {
+        return failedRun(action.alias, 'native_hook_unavailable', started);
+    }
+    const timeoutMs = Number.isSafeInteger(hook.timeout_ms) && hook.timeout_ms > 0
+        ? Math.min(hook.timeout_ms, MAX_HOOK_TIMEOUT_MS) : DEFAULT_HOOK_TIMEOUT_MS;
+    const cap = Math.min(Math.max(ctx.outputBytes ?? DEFAULT_OUTPUT_BYTES, 1024), MAX_OUTPUT_BYTES);
+    const posix = process.platform !== 'win32';
+    // Cancellation can arrive while resolving or reading the approved hook.
+    // No asynchronous preparation remains between this check and spawn.
+    if (ctx.signal.aborted)
+        return failedRun(action.alias, 'native_hook_cancelled', started);
+    return await new Promise((resolve) => {
+        let tail = Buffer.alloc(0);
+        let truncated = false;
+        let settled = false;
+        let stopCode = null;
+        let drain;
+        let grace;
+        const child = spawn(hook.runtime.executable, [...hook.runtime.args, hookPath], {
+            shell: false, cwd: root.path, env: hookEnv(action.alias, ctx.drillKey),
+            stdio: ['ignore', 'pipe', 'pipe'], detached: posix, windowsHide: true,
+        });
+        if (posix)
+            child.once('spawn', () => ownGroup(child.pid));
+        const kill = (code) => {
+            // Once the hook exited its result is decided, and its group was swept and released: that id is never signalled again.
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            if (stopCode === null)
+                stopCode = code;
+            try {
+                if (posix && typeof child.pid === 'number')
+                    process.kill(-child.pid, 'SIGKILL');
+                else
+                    child.kill('SIGKILL');
+            }
+            catch { /* already exited */ }
+            // A hook that does not exit even then must not hold the drill: the stop is reported without its exit.
+            grace ??= setTimeout(() => finish(result(null, null)), KILL_GRACE_MS);
+        };
+        const capture = (chunk) => {
+            tail = Buffer.concat([tail, chunk]);
+            if (tail.length > cap) {
+                truncated = true;
+                tail = tail.subarray(tail.length - cap);
+            }
+        };
+        child.stdout?.on('data', capture);
+        child.stderr?.on('data', capture);
+        const timer = setTimeout(() => kill('native_hook_timeout'), timeoutMs);
+        const onAbort = () => kill('native_hook_cancelled');
+        ctx.signal.addEventListener('abort', onAbort, { once: true });
+        const result = (code, signal) => {
+            const ok = stopCode === null && code === 0;
+            return {
+                domain_alias: action.alias, result: ok ? 'applied' : 'failed',
+                error_code: ok ? null : (stopCode ?? 'native_hook_exit'),
+                exit_code: typeof code === 'number' ? code : null, signal: signal ?? null,
+                duration_ms: Date.now() - started, output_tail_unredacted: tail.toString('utf8'), output_truncated: truncated,
+            };
+        };
+        const finish = (run) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            clearTimeout(drain);
+            clearTimeout(grace);
+            ctx.signal.removeEventListener('abort', onAbort);
+            // A descendant that left the hook's group may still hold the pipes; it must not keep the companion waiting.
+            for (const stream of [child.stdout, child.stderr])
+                stream?.destroy();
+            resolve(run);
+        };
+        child.once('error', () => finish(failedRun(action.alias, stopCode ?? 'native_hook_unavailable', started)));
+        child.once('exit', (code, signal) => {
+            // Processes the hook left running are ours, not part of its result: end them with it.
+            if (posix)
+                sweepGroup(child.pid);
+            clearTimeout(grace);
+            // 'close' also waits for every holder of the pipes, and a descendant that escaped the group (a new session)
+            // can hold them for good: the output drains briefly, then the result is the exit.
+            drain = setTimeout(() => finish(result(code, signal)), EXIT_DRAIN_MS);
+        });
+        child.once('close', (code, signal) => finish(result(code, signal)));
+        if (ctx.signal.aborted)
+            onAbort();
+    });
+}
+/**
+ * Per-drill record of state handling. Hooks are applied by applyDrillState; the
+ * supervisor calls `markFreshProcess` after starting a per-drill copy, and the
+ * driver path calls `markFreshSession` after opening a new session/context.
+ * Anything still pending at `coverage()` is reported `failed` (not confirmed).
+ */
+export class DrillStateTracker {
+    hookRuns = [];
+    #domains = new Map();
+    constructor(statePlan) {
+        for (const action of statePlan.actions) {
+            const result = action.action === 'unavailable' ? 'unavailable'
+                : action.action === 'not-applicable' ? 'not-applicable' : 'pending';
+            this.#domains.set(action.alias, { action, result, error_code: null });
+        }
+    }
+    /** The supervisor started a fresh process (new per-drill copy) of `serviceAlias` for this drill. */
+    markFreshProcess(serviceAlias) {
+        for (const state of this.#domains.values()) {
+            if (state.action.action === 'fresh-process' && state.action.service_alias === serviceAlias)
+                state.result = 'applied';
+        }
+    }
+    /** The driver opened a new session (new browser context for playwright) for this drill. */
+    markFreshSession() {
+        for (const state of this.#domains.values()) {
+            if (state.action.action === 'fresh-session')
+                state.result = 'applied';
+        }
+    }
+    /** Record a failure the supervisor or driver observed for a domain's reset. */
+    markFailed(alias, errorCode) {
+        const state = this.#domains.get(alias);
+        if (state && state.action.action !== 'unavailable' && state.action.action !== 'not-applicable') {
+            state.result = 'failed';
+            state.error_code = errorCode;
+        }
+    }
+    recordHook(run) {
+        this.hookRuns.push(run);
+        const state = this.#domains.get(run.domain_alias);
+        if (state) {
+            state.result = run.result;
+            state.error_code = run.error_code;
+        }
+    }
+    /** Domains whose reset failed, with stable codes. */
+    failures() {
+        return [...this.#domains.values()].filter((state) => state.result === 'failed')
+            .map((state) => ({ alias: state.action.alias, error_code: state.error_code }));
+    }
+    /** True when a hook digest no longer matches: the approval is void and the drill must stop. */
+    planChanged() {
+        return this.hookRuns.some((run) => run.error_code === 'native_plan_changed');
+    }
+    coverage() {
+        return [...this.#domains.values()].map((state) => ({
+            alias: state.action.alias, reset: state.action.reset,
+            result: state.result === 'pending' ? 'failed' : state.result,
+        }));
+    }
+}
+/**
+ * Begin state handling for one drill: run every approved hook (sequentially, in
+ * descriptor order) and return the tracker the supervisor and driver report to.
+ * Hook failures are recorded, not thrown; callers decide whether to proceed and
+ * must stop when `tracker.planChanged()` is true.
+ */
+export async function applyDrillState(statePlan, ctx) {
+    const tracker = new DrillStateTracker(statePlan);
+    for (const action of statePlan.actions) {
+        if (action.action !== 'approved-hook')
+            continue;
+        if (ctx.signal.aborted) {
+            tracker.recordHook(failedRun(action.alias, 'native_hook_cancelled', Date.now()));
+            continue;
+        }
+        tracker.recordHook(await runApprovedHook(action, ctx));
+    }
+    return tracker;
+}
+/** Convenience guard for callers: throw when a tracker shows the plan changed under a running session. */
+export function assertPlanUnchanged(tracker) {
+    if (tracker.planChanged()) {
+        throw nativeError('plan_changed', 'The drill was not continued: an approved reset hook changed on disk. Approve the plan again.');
+    }
+}