@minionry/minion 0.7.36

package/dist/server/services/sdk/browser.js

@@ -0,0 +1,605 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { randomUUID } from 'node:crypto';
+import { ENGINE_IDS, engineForModel, isEngineId } from '../../engines/EngineEvent.js';
+import { e2eeRequiredSdkMessage, mustRefuseSdkMethodWhenCleartext } from '../browser-frame-policy.js';
+import { getEngine, getModel, resolveEnabledEngineId } from '../settings.js';
+import { logAppAudit } from './audit.js';
+import { getGrant } from './grant-store.js';
+import { deregisterLiveSubscription, listLiveSubscriptions, registerLiveSubscription, } from './live-registry.js';
+import { SdkMethodError } from './registry.js';
+let browserHost = null;
+export function setSdkBrowserHost(host) {
+    browserHost = host;
+}
+export function resetSdkBrowserHost() {
+    browserHost = null;
+    automations.clear();
+    views.clear();
+}
+let contentGate = null;
+export function setSdkBrowserContentGate(gate) {
+    contentGate = gate;
+}
+function contentAllowed(method) {
+    if (!mustRefuseSdkMethodWhenCleartext(method))
+        return true;
+    return contentGate === null || contentGate();
+}
+function requireSealedContent(method) {
+    if (!contentAllowed(method)) {
+        throw new SdkMethodError('SECURITY_BLOCKED', e2eeRequiredSdkMessage(method));
+    }
+}
+function gatedEmit(method, emit) {
+    if (!mustRefuseSdkMethodWhenCleartext(method))
+        return emit;
+    let refused = false;
+    return (event, payload) => {
+        if (contentAllowed(method)) {
+            refused = false;
+            emit(event, payload);
+            return;
+        }
+        if (refused)
+            return;
+        refused = true;
+        emit('error', { code: 'SECURITY_BLOCKED', message: e2eeRequiredSdkMessage(method) });
+    };
+}
+function requireHost(method) {
+    if (!browserHost) {
+        throw new SdkMethodError('INTERNAL', `${method}: the browser host is not attached — start the Browser view first`);
+    }
+    return browserHost;
+}
+function paramsObject(params) {
+    return typeof params === 'object' && params !== null && !Array.isArray(params)
+        ? params
+        : {};
+}
+function requireStringParam(raw, name, method) {
+    const value = raw[name];
+    if (typeof value !== 'string' || value === '') {
+        throw new SdkMethodError('BAD_REQUEST', `${method} requires params { ${name} } — a non-empty string`);
+    }
+    return value;
+}
+const APP_NAVIGABLE_PROTOCOLS = new Set(['http:', 'https:']);
+function requireWebUrlParam(raw, name, method) {
+    const url = requireStringParam(raw, name, method);
+    if (url === 'about:blank')
+        return url;
+    let protocol;
+    try {
+        protocol = new URL(url).protocol;
+    }
+    catch {
+        throw new SdkMethodError('BAD_REQUEST', `${method} requires params { ${name} } — an absolute http(s) URL`);
+    }
+    if (!APP_NAVIGABLE_PROTOCOLS.has(protocol)) {
+        throw new SdkMethodError('SECURITY_BLOCKED', `${method} refuses ${protocol} URLs — an app may navigate the browser to http(s) pages only`);
+    }
+    return url;
+}
+function optionalStringParam(raw, name) {
+    const value = raw[name];
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+export function browserTabsListHandler(args) {
+    requireSealedContent(args?.method ?? 'browser.tabs.list');
+    if (!browserHost)
+        return { tabs: [], currentTabId: null };
+    return browserHost.getTabsSnapshot();
+}
+export function browserTabsSubscribeHandler(args) {
+    if (listLiveSubscriptions().some((sub) => sub.requestId === args.requestId)) {
+        throw new SdkMethodError('BAD_REQUEST', `requestId '${args.requestId}' already holds a live subscription`);
+    }
+    requireSealedContent(args.method);
+    const host = requireHost(args.method);
+    let active = true;
+    const emit = gatedEmit(args.method, args.emit);
+    const unsubscribe = host.subscribeTabs((payload) => {
+        if (!active)
+            return;
+        emit('tabsChanged', payload);
+    });
+    registerLiveSubscription({
+        requestId: args.requestId,
+        appId: args.appId,
+        origin: args.origin,
+        spaceKey: args.spaceKey,
+        kind: 'browser.tabs.subscribe',
+        viewerId: getGrant(args.appId, args.spaceKey) ? undefined : args.viewerId,
+        teardown: () => {
+            active = false;
+            unsubscribe();
+        },
+    });
+    return { subscribed: true };
+}
+export async function browserNavigateHandler(args) {
+    const raw = paramsObject(args.params);
+    const url = requireWebUrlParam(raw, 'url', args.method);
+    const tabId = optionalStringParam(raw, 'tabId');
+    await requireHost(args.method).navigate({ url, ...(tabId ? { tabId } : {}) });
+    return null;
+}
+export async function browserOpenHandler(args) {
+    const raw = paramsObject(args.params);
+    const url = requireWebUrlParam(raw, 'url', args.method);
+    const pinnedApp = raw.pinnedApp === true;
+    return requireHost(args.method).open({ url, ...(pinnedApp ? { reuseOrigin: args.origin } : {}) });
+}
+export async function browserCloseHandler(args) {
+    const raw = paramsObject(args.params);
+    const tabId = requireStringParam(raw, 'tabId', args.method);
+    await requireHost(args.method).close({ tabId });
+    return null;
+}
+export async function browserSelectHandler(args) {
+    const raw = paramsObject(args.params);
+    const tabId = requireStringParam(raw, 'tabId', args.method);
+    await requireHost(args.method).select({ tabId });
+    return null;
+}
+export async function browserSnapshotHandler(args) {
+    requireSealedContent(args.method);
+    const raw = paramsObject(args.params);
+    const tabId = requireStringParam(raw, 'tabId', args.method);
+    return requireHost(args.method).snapshot({ tabId });
+}
+export async function browserScreenshotHandler(args) {
+    requireSealedContent(args.method);
+    const raw = paramsObject(args.params);
+    const tabId = requireStringParam(raw, 'tabId', args.method);
+    const fullPage = raw.fullPage === true;
+    const format = raw.format === 'jpeg' ? 'jpeg' : raw.format === 'png' ? 'png' : undefined;
+    const quality = typeof raw.quality === 'number' ? raw.quality : undefined;
+    return requireHost(args.method).screenshot({
+        tabId,
+        ...(fullPage ? { fullPage: true } : {}),
+        ...(format ? { format } : {}),
+        ...(quality !== undefined ? { quality } : {}),
+    });
+}
+export async function browserEvaluateHandler(args) {
+    requireSealedContent(args.method);
+    const raw = paramsObject(args.params);
+    const tabId = requireStringParam(raw, 'tabId', args.method);
+    const expr = requireStringParam(raw, 'expr', args.method);
+    const world = raw.world === 'main' ? 'main' : 'isolated';
+    const timeoutMs = typeof raw.timeoutMs === 'number' ? raw.timeoutMs : undefined;
+    return requireHost(args.method).evaluate({
+        tabId,
+        expr,
+        world,
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    });
+}
+export async function browserBackHandler(args) {
+    await requireHost(args.method).back(historyArgs(args));
+    return null;
+}
+export async function browserForwardHandler(args) {
+    await requireHost(args.method).forward(historyArgs(args));
+    return null;
+}
+export async function browserReloadHandler(args) {
+    await requireHost(args.method).reload(historyArgs(args));
+    return null;
+}
+export async function browserStopHandler(args) {
+    await requireHost(args.method).stop(historyArgs(args));
+    return null;
+}
+function historyArgs(args) {
+    const tabId = optionalStringParam(paramsObject(args.params), 'tabId');
+    return tabId ? { tabId } : {};
+}
+export async function browserPreflightHandler(args) {
+    return requireHost(args.method).preflight();
+}
+export async function browserResumeDriverHandler(args) {
+    const raw = paramsObject(args.params);
+    const tabId = requireStringParam(raw, 'tabId', args.method);
+    await requireHost(args.method).resumeDriver({ tabId });
+    return null;
+}
+export async function browserSetDeviceProfileHandler(args) {
+    const raw = paramsObject(args.params);
+    const tabId = requireStringParam(raw, 'tabId', args.method);
+    if (raw.formFactor !== 'desktop' && raw.formFactor !== 'mobile') {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method} requires params { formFactor } — 'desktop' or 'mobile'`);
+    }
+    await requireHost(args.method).setDeviceProfile({ tabId, formFactor: raw.formFactor });
+    return null;
+}
+export const SDK_BROWSER_INPUT_BATCH_MAX = 64;
+const views = new Map();
+function retireView(record, outcome) {
+    if (!record.active)
+        return;
+    record.active = false;
+    views.delete(record.sessionId);
+    deregisterLiveSubscription(record.requestId);
+    record.handle.detach();
+    logAppAudit({
+        appId: record.appId,
+        origin: record.origin,
+        method: 'browser.view.end',
+        decision: 'allow',
+        requestId: record.requestId,
+        spaceKey: record.spaceKey,
+        reason: `view ${record.sessionId} ${outcome}`,
+    });
+}
+function forwardViewEvent(record, event) {
+    if (!record.active)
+        return;
+    switch (event.kind) {
+        case 'offer':
+            record.emit('offer', {
+                sdp: event.sdp,
+                ...(event.iceServers ? { iceServers: event.iceServers } : {}),
+            });
+            return;
+        case 'ice':
+            record.emit('ice', { candidate: event.candidate });
+            return;
+        case 'connectionState':
+            record.emit('connectionState', {
+                state: event.state,
+                ...(event.reason !== undefined ? { reason: event.reason } : {}),
+            });
+            return;
+        case 'navigationState':
+            record.emit('navigationState', {
+                tabId: event.tabId,
+                url: event.url,
+                title: event.title,
+                isLoading: event.isLoading,
+                canGoBack: event.canGoBack,
+                canGoForward: event.canGoForward,
+            });
+            return;
+        case 'driverState':
+            record.emit('driverState', event.snapshot);
+            return;
+        case 'inputFocus':
+            record.emit('inputFocus', { focused: event.focused });
+            return;
+        case 'inputRejected':
+            record.emit('inputRejected', {
+                kind: event.inputKind,
+                reason: event.reason,
+                ...(event.message !== undefined ? { message: event.message } : {}),
+            });
+            return;
+        default:
+            record.emit('connectionState', { state: 'closed', reason: event.reason });
+            retireView(record, event.reason);
+    }
+}
+function requireViewRecord(args, raw) {
+    const sessionId = requireStringParam(raw, 'sessionId', args.method);
+    const record = views.get(sessionId);
+    if (!record?.active || record.appId !== args.appId || record.spaceKey !== args.spaceKey) {
+        throw new SdkMethodError('BAD_REQUEST', `no live view session '${sessionId}' attached by this app in this Space`);
+    }
+    return record;
+}
+function extractViewBounds(raw, method) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    const obj = paramsObject(raw);
+    const width = obj.width;
+    const height = obj.height;
+    if (typeof width !== 'number' || typeof height !== 'number' || !Number.isFinite(width) || !Number.isFinite(height)) {
+        throw new SdkMethodError('BAD_REQUEST', `${method}: bounds requires numeric { width, height }`);
+    }
+    const bounds = { width, height };
+    if (typeof obj.x === 'number')
+        bounds.x = obj.x;
+    if (typeof obj.y === 'number')
+        bounds.y = obj.y;
+    if (obj.mobile === true)
+        bounds.mobile = true;
+    if (typeof obj.deviceScaleFactor === 'number')
+        bounds.deviceScaleFactor = obj.deviceScaleFactor;
+    return bounds;
+}
+export async function browserViewAttachHandler(args) {
+    if (listLiveSubscriptions().some((sub) => sub.requestId === args.requestId)) {
+        throw new SdkMethodError('BAD_REQUEST', `requestId '${args.requestId}' already holds a live subscription`);
+    }
+    requireSealedContent(args.method);
+    const raw = paramsObject(args.params);
+    const tabId = optionalStringParam(raw, 'tabId');
+    const bounds = extractViewBounds(raw.bounds, args.method);
+    const host = requireHost(args.method);
+    const viewerKey = `sdk:${args.appId}:${args.requestId}`;
+    let record = null;
+    const pending = [];
+    const handle = await host.attachView({
+        viewerKey,
+        ...(tabId ? { tabId } : {}),
+        ...(bounds ? { bounds } : {}),
+        ...(getGrant(args.appId, args.spaceKey) ? {} : args.viewerId ? { ownerViewerId: args.viewerId } : {}),
+        onEvent: (event) => {
+            if (!record) {
+                pending.push(event);
+                return;
+            }
+            forwardViewEvent(record, event);
+        },
+    });
+    record = {
+        requestId: args.requestId,
+        appId: args.appId,
+        origin: args.origin,
+        spaceKey: args.spaceKey,
+        sessionId: handle.sessionId,
+        tabId: handle.tabId,
+        handle,
+        emit: gatedEmit(args.method, args.emit),
+        active: true,
+    };
+    views.set(handle.sessionId, record);
+    registerLiveSubscription({
+        requestId: args.requestId,
+        appId: args.appId,
+        origin: args.origin,
+        spaceKey: args.spaceKey,
+        kind: 'browser.view.attach',
+        viewerId: getGrant(args.appId, args.spaceKey) ? undefined : args.viewerId,
+        teardown: () => {
+            const live = views.get(handle.sessionId);
+            if (!live) {
+                handle.detach();
+                return;
+            }
+            live.active = false;
+            views.delete(handle.sessionId);
+            handle.detach();
+        },
+    });
+    for (const event of pending)
+        forwardViewEvent(record, event);
+    return { sessionId: handle.sessionId, tabId: handle.tabId };
+}
+export async function browserViewAnswerHandler(args) {
+    requireSealedContent(args.method);
+    const raw = paramsObject(args.params);
+    const record = requireViewRecord(args, raw);
+    const sdp = requireStringParam(raw, 'sdp', args.method);
+    await record.handle.answer(sdp);
+    return null;
+}
+export async function browserViewIceHandler(args) {
+    requireSealedContent(args.method);
+    const raw = paramsObject(args.params);
+    const record = requireViewRecord(args, raw);
+    const candidate = raw.candidate;
+    if (candidate !== null && (typeof candidate !== 'object' || candidate === undefined || Array.isArray(candidate))) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: candidate must be an object or null`);
+    }
+    await record.handle.ice(candidate);
+    return null;
+}
+export async function browserViewStateHandler(args) {
+    requireSealedContent(args.method);
+    const raw = paramsObject(args.params);
+    const record = requireViewRecord(args, raw);
+    const state = requireStringParam(raw, 'state', args.method);
+    if (state !== 'negotiating' && state !== 'connected' && state !== 'failed' && state !== 'closed') {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: state must be 'negotiating', 'connected', 'failed' or 'closed'`);
+    }
+    const reason = optionalStringParam(raw, 'reason');
+    await record.handle.state(state, reason);
+    if (state === 'closed')
+        retireView(record, 'closed by app');
+    return null;
+}
+export async function browserViewInputHandler(args) {
+    requireSealedContent(args.method);
+    const raw = paramsObject(args.params);
+    const record = requireViewRecord(args, raw);
+    const value = raw.input;
+    const batch = Array.isArray(value) ? value : [value];
+    if (batch.length === 0 || batch.length > SDK_BROWSER_INPUT_BATCH_MAX) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: input must be 1–${SDK_BROWSER_INPUT_BATCH_MAX} input envelopes`);
+    }
+    const result = await record.handle.input(batch);
+    if (!result.delivered) {
+        forwardViewEvent(record, {
+            kind: 'inputRejected',
+            inputKind: result.inputKind,
+            reason: result.reason,
+            ...(result.message !== undefined ? { message: result.message } : {}),
+        });
+    }
+    return result;
+}
+export async function browserViewBoundsHandler(args) {
+    const raw = paramsObject(args.params);
+    const record = requireViewRecord(args, raw);
+    const bounds = extractViewBounds(raw.bounds, args.method);
+    if (!bounds) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method} requires params { bounds: { width, height } }`);
+    }
+    await record.handle.bounds(bounds);
+    return null;
+}
+const automations = new Map();
+export function resolveAutomationTarget(rawEngine, rawModel, method) {
+    if (rawEngine !== undefined && rawEngine !== null && !isEngineId(rawEngine)) {
+        throw new SdkMethodError('BAD_REQUEST', `${method}: unknown engine '${String(rawEngine)}' — expected one of ${ENGINE_IDS.join(', ')}`);
+    }
+    if (rawModel !== undefined && rawModel !== null && (typeof rawModel !== 'string' || rawModel === '')) {
+        throw new SdkMethodError('BAD_REQUEST', `${method}: model must be a non-empty string when present`);
+    }
+    const suppliedEngine = isEngineId(rawEngine) ? rawEngine : undefined;
+    const suppliedModel = typeof rawModel === 'string' && rawModel !== '' ? rawModel : undefined;
+    const engine = resolveEnabledEngineId(suppliedEngine ?? (suppliedModel ? engineForModel(suppliedModel) : undefined) ?? getEngine());
+    if (suppliedModel) {
+        if (engineForModel(suppliedModel) !== engine) {
+            throw new SdkMethodError('BAD_REQUEST', `${method}: model '${suppliedModel}' is not a ${engine} model — it belongs to ${engineForModel(suppliedModel)}`);
+        }
+        return { engine, model: suppliedModel };
+    }
+    const machineDefault = getModel();
+    return engineForModel(machineDefault) === engine ? { engine, model: machineDefault } : { engine };
+}
+export function resolveAutomationEngine(raw, method) {
+    return resolveAutomationTarget(raw, undefined, method).engine;
+}
+function retireAutomation(record, outcome) {
+    record.active = false;
+    record.pendingProposalId = undefined;
+    automations.delete(record.requestId);
+    deregisterLiveSubscription(record.requestId);
+    logAppAudit({
+        appId: record.appId,
+        origin: record.origin,
+        method: 'browser.automate.end',
+        decision: 'allow',
+        requestId: record.requestId,
+        spaceKey: record.spaceKey,
+        reason: `automation ${record.taskId} ${outcome}`,
+    });
+}
+function forwardAutomationStep(record, event, emit) {
+    if (event.proposalId && event.proposalId === record.pendingProposalId) {
+        record.pendingProposalId = undefined;
+    }
+    emit('step', {
+        phase: event.phase,
+        detail: event.detail,
+        ...(event.proposalId ? { proposalId: event.proposalId } : {}),
+        ...(event.engine ? { engine: event.engine } : {}),
+        ...(event.model ? { model: event.model } : {}),
+        ...(record.sessionId ? { sessionId: record.sessionId } : {}),
+    });
+}
+function forwardAutomationEvent(record, event, emit) {
+    if (!record.active)
+        return;
+    if (event.kind === 'session') {
+        record.sessionId = event.sessionId;
+        record.sessionName = event.name;
+        emit('session', { sessionId: event.sessionId, name: event.name });
+        return;
+    }
+    if (event.kind === 'proposed') {
+        record.pendingProposalId = event.proposalId;
+        emit('proposed', { proposalId: event.proposalId, summary: event.summary });
+        return;
+    }
+    if (event.kind === 'step') {
+        forwardAutomationStep(record, event, emit);
+        return;
+    }
+    emit('done', {
+        status: event.status,
+        ...(event.result !== undefined ? { result: event.result } : {}),
+        ...(event.error !== undefined ? { error: event.error } : {}),
+    });
+    retireAutomation(record, event.status);
+}
+function flushPendingAutomationEvents(record, session, emit) {
+    const pending = record.pendingEvents ?? [];
+    record.pendingEvents = undefined;
+    forwardAutomationEvent(record, { kind: 'session', ...session }, emit);
+    for (const event of pending)
+        forwardAutomationEvent(record, event, emit);
+}
+export async function browserAutomateHandler(args) {
+    if (listLiveSubscriptions().some((sub) => sub.requestId === args.requestId)) {
+        throw new SdkMethodError('BAD_REQUEST', `requestId '${args.requestId}' already holds a live subscription`);
+    }
+    requireSealedContent(args.method);
+    const raw = paramsObject(args.params);
+    const prompt = requireStringParam(raw, 'prompt', args.method);
+    const { engine, model } = resolveAutomationTarget(raw.engine, raw.model, args.method);
+    const tabId = optionalStringParam(raw, 'tabId');
+    const host = requireHost(args.method);
+    const emit = gatedEmit(args.method, args.emit);
+    const taskId = `browser-automation-${randomUUID()}`;
+    const record = {
+        requestId: args.requestId,
+        appId: args.appId,
+        origin: args.origin,
+        spaceKey: args.spaceKey,
+        taskId,
+        handle: null,
+        active: true,
+    };
+    automations.set(args.requestId, record);
+    const handle = await host
+        .automate({
+        task: prompt,
+        taskId,
+        engine,
+        ...(model ? { model } : {}),
+        ...(tabId ? { tabId } : {}),
+        workingDir: args.workingDir,
+        initiator: { appId: args.appId, origin: args.origin, grantScopes: args.grant?.scopes ?? [] },
+        onSession: (info) => {
+            record.sessionId = info.sessionId;
+            record.sessionName = info.name;
+            record.pendingEvents = [];
+            setImmediate(() => flushPendingAutomationEvents(record, info, emit));
+        },
+        onEvent: (event) => {
+            if (record.pendingEvents) {
+                record.pendingEvents.push(event);
+                return;
+            }
+            forwardAutomationEvent(record, event, emit);
+        },
+    })
+        .catch((error) => {
+        automations.delete(args.requestId);
+        throw error;
+    });
+    record.handle = handle;
+    if (!record.active)
+        return { taskId };
+    registerLiveSubscription({
+        requestId: args.requestId,
+        appId: args.appId,
+        origin: args.origin,
+        spaceKey: args.spaceKey,
+        kind: 'browser.automate',
+        viewerId: getGrant(args.appId, args.spaceKey) ? undefined : args.viewerId,
+        teardown: () => {
+            record.active = false;
+            record.pendingProposalId = undefined;
+            automations.delete(record.requestId);
+            handle.cancel();
+        },
+    });
+    return { taskId };
+}
+export function browserAutomateApproveHandler(args) {
+    const raw = paramsObject(args.params);
+    const proposalId = requireStringParam(raw, 'proposalId', args.method);
+    const verdict = raw.verdict === undefined ? 'approve' : raw.verdict;
+    if (verdict !== 'approve' && verdict !== 'edit' && verdict !== 'deny') {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: verdict must be 'approve', 'edit' or 'deny' when present`);
+    }
+    const editedText = typeof raw.editedText === 'string' ? raw.editedText : undefined;
+    const record = [...automations.values()].find((candidate) => candidate.appId === args.appId &&
+        candidate.spaceKey === args.spaceKey &&
+        candidate.pendingProposalId === proposalId);
+    if (!record?.handle) {
+        throw new SdkMethodError('BAD_REQUEST', `no proposal '${proposalId}' is awaiting a verdict on an automation this app started in this Space`);
+    }
+    record.pendingProposalId = undefined;
+    if (!record.handle.approve({ proposalId, verdict, ...(editedText !== undefined ? { editedText } : {}) })) {
+        throw new SdkMethodError('BAD_REQUEST', `proposal '${proposalId}' is no longer awaiting a verdict`);
+    }
+    return null;
+}