firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/administration.js

@@ -0,0 +1,295 @@
+import { APP_ORIGIN } from './http.js';
+import { randomUUID } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { api, openBrowser } from './auth.js';
+import { privateDirectory } from './credentials.js';
+import { auth, choosePaged, interactive, line, query } from './configuration.js';
+import { readMetadata, record } from './configuration-intents.js';
+import { CliError } from './http.js';
+import { selectMany, selectOne, terminalText } from './prompts.js';
+import { selectedWorkspace } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { workspaceTeamRead, workspaceSettingsMatch, workspaceTeamMatch, workspaceInvitationsMatch, workspaceMemberDetailMatch, workspaceMemberChangeMatch, workspaceInvitationMatch, workspaceInvitationRequestMatch } from './workspace-team-contracts.js';
+const roles = ['owner', 'admin', 'member', 'viewer'];
+const email = (value) => typeof value === 'string' && value.length <= 254 && /^[^\s@]+@[^\s@]+$/.test(value);
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+const invalid = () => new CliError('administration_input_invalid', 'Use the exact workspace, invitation or teammate details. No replacement request was submitted.', 2);
+const inviteStates = { pending: 'Queued', sending: 'Sending', sent: 'Sent', uncertain: 'Delivery not confirmed',
+    revoked: 'Revoked', withdrawn: 'Request discarded', revoking: 'Revocation requested', revocation_uncertain: 'Revocation not confirmed',
+    accepted: 'Accepted', expired: 'Expired' };
+const inviteState = (value) => inviteStates[value] ?? 'Status unavailable';
+const invitationRecoveryHint = (state, workspace) => ['uncertain', 'revocation_uncertain'].includes(state)
+    ? `An organization owner can resolve the original invitation in team settings. No replacement email is sent.\nOpen: firedrill team open --workspace ${workspace}` : '';
+function settingsData(value, scope) {
+    if (!workspaceSettingsMatch(value, scope.workspace, scope.owner))
+        throw invalid();
+    return value;
+}
+async function approve(options, title) {
+    if (options.approve)
+        return;
+    if (!interactive(options))
+        throw new CliError('approval_required', 'Review this change and pass --approve-change for automation. Nothing was submitted.', 2);
+    if (!await selectOne(title, [{ value: false, label: 'Cancel' }, { value: true, label: 'Confirm change' }], options.signal))
+        throw new CliError('canceled', 'No change was submitted.', 130);
+}
+async function settingsLink(scope, section, options, output) {
+    if (!['workspace', 'team', 'billing', 'account', 'operations'].includes(section))
+        throw invalid();
+    // Financial administration is browser-owned. Its route performs fresh
+    // operator authorization; a native bearer preflight is deliberately forbidden.
+    const url = new URL(`/settings/${section}`, APP_ORIGIN);
+    url.searchParams.set('workspace', scope.workspace);
+    output({ browser_url: url.href, workspace_id: scope.workspace }, `Open ${url.href}`);
+    if (interactive(options) && options.openBrowser)
+        await openBrowser(url.href);
+}
+export async function settingsCommand(args, options, output) {
+    if (args.length > 2 || options.request !== undefined || options.page !== undefined || options.search !== undefined
+        || args[0] !== 'update' && (options.file !== undefined || options.approve))
+        throw new CliError('arguments_invalid', 'Use settings show, update [--file <settings.json>] or open [workspace|team|billing|account|operations].', 2);
+    const scope = await selectedWorkspace({ ...options, interactive: interactive(options) });
+    const action = args[0] ?? (interactive(options) ? await selectOne('Settings', [
+        { value: 'show', label: 'View workspace settings' }, { value: 'update', label: 'Change workspace settings' },
+        { value: 'open', label: 'Open account and settings in the browser' }
+    ], options.signal) : 'show');
+    if (action === 'open') {
+        const section = args[1] ?? (interactive(options) ? await selectOne('Settings page', [
+            { value: 'workspace', label: 'Workspace and privacy' }, { value: 'team', label: 'Team and invitations' },
+            { value: 'billing', label: 'Billing' }, { value: 'account', label: 'Account, terminal access and preferences' }
+        ], options.signal) : 'workspace');
+        await settingsLink(scope, section, options, output);
+        return;
+    }
+    if (!['show', 'update'].includes(action) || args[1])
+        throw invalid();
+    const path = `/api/workspaces/${scope.workspace}/settings`, current = settingsData(await api(path, auth(scope, options)), scope);
+    if (action === 'show') {
+        output(current, [current.name, current.description, ...(current.simulation_context ? [`Simulation context:\n${current.simulation_context}`] : []), `Evidence retention: ${current.retention_days} days`,
+            `Mask browser form values in new plans: ${current.mask_sensitive_data ? 'Yes' : 'No'}`, current.can_manage ? 'Workspace administrator access' : 'Read-only settings'].filter(Boolean).map(terminalText).join('\n'));
+        return;
+    }
+    if (!current.can_manage)
+        throw new CliError('workspace_permission_required', 'A workspace administrator can change these settings.', 2);
+    let body;
+    if (options.file !== undefined) {
+        if (!options.file)
+            throw invalid();
+        body = await readMetadata(options.file);
+    }
+    else {
+        if (!interactive(options))
+            throw new CliError('file_required', 'Pass --file <settings.json> with name, description, simulation_context, retention_days or mask_sensitive_data and --approve-change.', 2);
+        const selected = await selectMany('Settings to change', [{ value: 'name', label: 'Workspace name' }, { value: 'description', label: 'Description' },
+            { value: 'simulation_context', label: 'Shared simulation background' },
+            { value: 'retention_days', label: 'Evidence retention' }, { value: 'mask_sensitive_data', label: 'Browser form-value masking' }], options.signal);
+        body = {};
+        if (selected.includes('name'))
+            body.name = await line('Workspace name', 120, options.signal);
+        if (selected.includes('description'))
+            body.description = await line('Description (blank clears it)', 2000, options.signal);
+        if (selected.includes('simulation_context'))
+            body.simulation_context = await line('Simulation background, not credentials, permissions or scoring rules (blank clears it)', 8000, options.signal);
+        if (selected.includes('retention_days')) {
+            body.retention_days = await selectOne('Retain evidence for', current.retention_options.map(value => ({ value, label: `${value} days` })), options.signal);
+        }
+        if (selected.includes('mask_sensitive_data'))
+            body.mask_sensitive_data = await selectOne('Browser form values in new simulation plans', [
+                { value: true, label: 'Mask form values', detail: 'Saved plans keep their policy. Other visible text may still appear.' },
+                { value: false, label: 'Allow visible form values', detail: 'Passwords, marked-private fields and embedded content stay masked.' }
+            ], options.signal);
+    }
+    if (!Object.keys(body).length || Object.keys(body).some(key => !['name', 'description', 'simulation_context', 'retention_days', 'mask_sensitive_data'].includes(key))
+        || body.name !== undefined && (typeof body.name !== 'string' || !body.name.trim() || body.name.length > 120)
+        || body.description !== undefined && (typeof body.description !== 'string' || body.description.length > 2000)
+        || body.simulation_context !== undefined && (typeof body.simulation_context !== 'string' || body.simulation_context.length > 8000)
+        || body.retention_days !== undefined && (!Number.isSafeInteger(body.retention_days) || !current.retention_options.includes(Number(body.retention_days)))
+        || body.mask_sensitive_data !== undefined && typeof body.mask_sensitive_data !== 'boolean')
+        throw invalid();
+    if (interactive(options))
+        process.stderr.write(JSON.stringify({ ...body,
+            ...(body.simulation_context !== undefined ? { simulation_context: `Provided simulation background (${String(body.simulation_context).length} characters; blank clears it)` } : {}) }, null, 2).split('\n').map(terminalText).join('\n') + '\n');
+    await approve(options, typeof body.retention_days === 'number' && body.retention_days < current.retention_days
+        ? 'Save shorter retention? Expired evidence may be permanently removed.' : 'Save these reviewed settings?');
+    const value = settingsData(await api(path, { ...auth(scope, options), method: 'PATCH', body: { ...body,
+            ...(body.simulation_context !== undefined ? { simulation_context_revision: current.simulation_context_revision } : {}) } }), scope);
+    if (Object.entries(body).some(([name, selected]) => value[name] !== (name === 'name' ? String(selected).trim() : selected)))
+        throw new CliError('settings_change_unconfirmed', 'The returned settings differ from this request. Read settings before retrying.');
+    const readback = settingsData(await api(path, auth(scope, options)), scope);
+    if (Object.entries(body).some(([name, selected]) => readback[name] !== (name === 'name' ? String(selected).trim() : selected)))
+        throw new CliError('settings_change_unconfirmed', 'Saved settings changed before readback. Read the current settings before retrying.');
+    output(readback, 'Workspace settings saved.');
+}
+const invitePath = async (scope, key) => join(await privateDirectory(), `invitation-${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(key)}.json`);
+async function retainedInvite(scope, key) {
+    const value = await readMetadata(await invitePath(scope, key), true);
+    if (Object.keys(value).sort().join(',') !== 'actor,email,key,role,schema,workspace' || value.schema !== 'firedrill.invitation-intent.v1'
+        || value.actor !== scope.owner || value.workspace !== scope.workspace || value.key !== identifier(key)
+        || typeof value.email !== 'string' || !email(value.email) || value.email !== value.email.trim().toLowerCase()
+        || typeof value.role !== 'string' || !['admin', 'member', 'viewer'].includes(value.role))
+        throw invalid();
+    return value;
+}
+async function rememberInvite(value, scope) {
+    try {
+        const file = await open(await invitePath(scope, value.key), 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(value));
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (problem) {
+        if (!record(problem) || problem.code !== 'EEXIST')
+            throw problem;
+        const previous = await retainedInvite(scope, value.key);
+        if (previous.email !== value.email || previous.role !== value.role)
+            throw invalid();
+    }
+}
+function receipt(value, scope, key) {
+    if (!workspaceInvitationRequestMatch(value, scope.workspace, scope.owner, key))
+        throw invalid();
+    return value;
+}
+function showReceipt(value, output) {
+    output(value, [value.request_key, value.state === 'not_received' ? 'Not confirmed. The original request may still arrive.'
+            : value.state === 'withdrawn' ? 'Unsent invitation discarded. This key cannot send an invitation.'
+                : `${value.invitation.email} · ${value.invitation.role} · ${inviteState(value.invitation.state)}`,
+        ...(value.invitation ? [invitationRecoveryHint(value.invitation.state, value.workspace_id)] : [])].filter(Boolean).map(terminalText).join('\n'));
+}
+async function submitInvite(value, scope, options, output) {
+    const prefix = `/api/workspaces/${scope.workspace}/invitations`;
+    const original = receipt(await api(`${prefix}/requests/${value.key}`, auth(scope, options)), scope, value.key);
+    if (original.invitation && (original.invitation.email !== value.email || original.invitation.role !== value.role))
+        throw invalid();
+    if (original.state !== 'not_received') {
+        showReceipt(original, output);
+        return;
+    }
+    output({ phase: 'request_prepared', request_key: value.key, workspace_id: scope.workspace }, `Request: ${value.key}\nRecovery: firedrill team request ${value.key} --workspace ${scope.workspace}\nContinue: firedrill team resume ${value.key} --workspace ${scope.workspace} --approve-change`);
+    const saved = await api(prefix, { ...auth(scope, options), method: 'POST', idempotencyKey: value.key,
+        body: { email: value.email, role: value.role } });
+    if (!workspaceInvitationMatch(saved, scope.workspace, { actor: scope.owner, key: value.key, email: value.email, role: value.role }))
+        throw invalid();
+    const readback = receipt(await api(`${prefix}/requests/${value.key}`, auth(scope, options)), scope, value.key);
+    if (!workspaceInvitationRequestMatch(readback, scope.workspace, scope.owner, value.key, { id: saved.id, email: value.email, role: value.role }))
+        throw invalid();
+    showReceipt(readback, output);
+}
+export async function teamCommand(args, options, output) {
+    const isInteractive = interactive(options);
+    let action = args[0] ?? (isInteractive ? '' : 'list');
+    if (options.file !== undefined)
+        throw new CliError('arguments_invalid', 'Team commands take an email, role or saved ID, not a file.', 2);
+    const scope = await selectedWorkspace({ ...options, interactive: isInteractive });
+    if (!action)
+        action = await selectOne('Team', [{ value: 'list', label: 'View teammates' }, { value: 'invite', label: 'Invite a teammate' },
+            { value: 'invitations', label: 'View invitation history' }, { value: 'role', label: 'Change a role' }, { value: 'remove', label: 'Remove a teammate' },
+            { value: 'open', label: 'Open team settings in the browser' }], options.signal);
+    if (!['list', 'show', 'invite', 'invitations', 'request', 'resume', 'withdraw', 'revoke', 'role', 'remove', 'open'].includes(action)
+        || options.request !== undefined && action !== 'invite' || (options.page !== undefined || options.search !== undefined) && !['list', 'invitations'].includes(action)
+        || options.approve && !['invite', 'resume', 'withdraw', 'revoke', 'role', 'remove'].includes(action)
+        || args.length > (action === 'invite' || action === 'role' ? 3 : ['list', 'invitations', 'open'].includes(action) ? 1 : 2))
+        throw invalid();
+    const base = `/api/workspaces/${scope.workspace}`, access = auth(scope, options);
+    if (action === 'open') {
+        await settingsLink(scope, 'team', options, output);
+        return;
+    }
+    if (action === 'list' || action === 'invitations') {
+        const value = action === 'list' ? await api(`${base}/team?${query(options)}`, access)
+            : await api(`${base}/invitations?${query(options)}`, access);
+        workspaceTeamRead(value, 'can_manage' in value ? workspaceTeamMatch(value, scope.workspace, scope.owner, options.search ?? '', Number(options.page ?? 1))
+            : workspaceInvitationsMatch(value, scope.workspace, scope.owner, options.search ?? '', Number(options.page ?? 1)));
+        output(value, [...value.results.map(row => 'request_key' in row ? `${row.email} · ${row.role} · ${inviteState(row.state)}\n${row.id}\nRequest: ${row.request_key}`
+                : `${row.name || row.email} · ${row.email} · ${row.role}${row.is_self ? ' (you)' : ''}\n${row.id}`),
+            ...(!value.count ? ['No matching entries.'] : []), `Page ${value.page}; ${value.count.toLocaleString()} entries.`,
+            ...(value.results.some(row => 'request_key' in row && ['uncertain', 'revocation_uncertain'].includes(row.state))
+                ? [invitationRecoveryHint('uncertain', scope.workspace)] : []),
+            ...(value.next ? [`Continue: firedrill team ${action} --workspace ${scope.workspace} --page ${value.page + 1}${options.search ? ' --search ' + quote(options.search) : ''}${options.json ? ' --json' : ''}`] : [])].map(terminalText).join('\n\n'));
+        return;
+    }
+    if (['request', 'resume', 'withdraw'].includes(action)) {
+        const key = identifier(args[1] ?? '');
+        const path = `${base}/invitations/requests/${key}`, original = receipt(await api(path, access), scope, key);
+        if (action === 'request' || action === 'resume' && original.state !== 'not_received') {
+            showReceipt(original, output);
+            return;
+        }
+        const value = action === 'resume' || original.invitation === null ? await retainedInvite(scope, key) : null;
+        await approve(options, action === 'resume' ? 'Continue this exact original invitation request?' : 'Discard the unsent original request? An invitation already dispatched will not be canceled.');
+        if (action === 'resume')
+            await submitInvite(value, scope, options, output);
+        else
+            showReceipt(receipt(await api(path, { ...access, method: 'DELETE', body: {
+                    email: value?.email ?? original.invitation.email, role: value?.role ?? original.invitation.role
+                } }), scope, key), output);
+        return;
+    }
+    if (action === 'invite') {
+        const team = await api(`${base}/team?page=1`, access);
+        workspaceTeamRead(team, workspaceTeamMatch(team, scope.workspace, scope.owner));
+        if (!team.can_manage)
+            throw new CliError('workspace_permission_required', 'A workspace administrator can invite teammates.', 2);
+        const recipient = (args[1] ?? (isInteractive ? await line('Email', 254, options.signal) : '')).trim().toLowerCase();
+        if (!email(recipient))
+            throw new CliError('email_required', 'Pass a valid invitation email, or run team invite in an interactive terminal.', 2);
+        const available = team.actor_role === 15 ? ['member', 'viewer', 'admin'] : ['member', 'viewer'];
+        const role = args[2] ?? (isInteractive ? await selectOne('Role', available.map(value => ({ value, label: value })), options.signal) : 'member');
+        if (!available.includes(role))
+            throw invalid();
+        const value = { schema: 'firedrill.invitation-intent.v1', actor: scope.owner, workspace: scope.workspace,
+            key: options.request !== undefined ? identifier(options.request) : randomUUID(), email: recipient, role };
+        await approve(options, `Invite ${terminalText(recipient)} as ${role}?`);
+        await rememberInvite(value, scope);
+        await submitInvite(value, scope, options, output);
+        return;
+    }
+    if (action === 'revoke') {
+        if (!args[1])
+            throw invalid();
+        const path = `${base}/invitations/${identifier(args[1])}`, current = await api(path, access);
+        workspaceTeamRead(current, workspaceInvitationMatch(current, scope.workspace, { id: args[1] }));
+        if (['withdrawn', 'revoked', 'accepted', 'expired'].includes(current.state)) {
+            output(current, `${current.email} · ${inviteState(current.state)}`);
+            return;
+        }
+        await approve(options, `Revoke the invitation for ${terminalText(current.email)} as ${current.role}? An accepted membership is not removed.`);
+        const value = await api(path, { ...access, method: 'DELETE' });
+        workspaceTeamRead(value, workspaceInvitationMatch(value, scope.workspace, { id: current.id, actor: current.actor_id, key: current.request_key, email: current.email, role: current.role }));
+        const readback = await api(path, access);
+        workspaceTeamRead(readback, workspaceInvitationMatch(readback, scope.workspace, { id: current.id, actor: current.actor_id, key: current.request_key, email: current.email, role: current.role }));
+        output(readback, [`${readback.email} · ${inviteState(readback.state)}`, invitationRecoveryHint(readback.state, scope.workspace)].filter(Boolean).map(terminalText).join('\n'));
+        return;
+    }
+    let member = args[1] ? identifier(args[1]) : undefined;
+    if (!member && isInteractive)
+        member = (await choosePaged('Teammate', `${base}/team`, scope, options, row => ({ label: row.name || row.email, detail: `${row.email} · ${row.role}` })))?.id;
+    if (!member)
+        throw new CliError('member_required', 'Choose a teammate ID with firedrill team list.', 2);
+    const current = await api(`${base}/team/${identifier(member)}`, access);
+    workspaceTeamRead(current, workspaceMemberDetailMatch(current, scope.workspace, scope.owner, member));
+    if (action === 'show') {
+        const state = { not_requested: '', searching: 'Checking organization owners. No change has been made.', witness: 'Owner check finished. Submit the reviewed change to apply it.',
+            no_owner: 'Add another owner before changing this owner.', attention_required: 'Owner access could not be confirmed. Repeat the reviewed request to check again.' }[current.owner_check];
+        output(current, [`${current.name || current.email}`, `${current.email} · ${current.role}`, state].filter(Boolean).map(terminalText).join('\n'));
+        return;
+    }
+    if (!current.can_manage || current.actor_role !== 15 && ['owner', 'admin'].includes(current.role))
+        throw new CliError('workspace_permission_required', 'An owner is required for this team change.', 2);
+    const available = current.actor_role === 15 ? roles : ['member', 'viewer'];
+    const role = action === 'role' ? args[2] ?? (isInteractive ? await selectOne('New role', available.map(value => ({ value, label: value })), options.signal) : '') : null;
+    if (action === 'role' && !available.includes(role))
+        throw new CliError('role_required', 'Pass an available role: owner, admin, member or viewer. The server checks grant permissions.', 2);
+    await approve(options, `${action === 'remove' ? 'Remove' : 'Change role for'} ${terminalText(current.email)}${role ? ' to ' + role : ''}? This affects the organization, not only this workspace.`);
+    const value = await api(`${base}/team/${identifier(member)}`, { ...access,
+        method: action === 'remove' ? 'DELETE' : 'PATCH', ...(role ? { body: { role } } : {}) });
+    workspaceTeamRead(value, workspaceMemberChangeMatch(value, scope.workspace, scope.owner, member));
+    output(value, value.state === 'completed' ? 'Team updated.' : value.state === 'checking_owners'
+        ? `Checking organization owners. No change has been made. Use firedrill team show ${member}, then repeat the reviewed change when the check finishes.`
+        : value.message ?? 'The change is being confirmed. Read the team list before retrying.');
+}