actas 0.0.0-stage → 0.4.1

package/client/browser/runner.mjs

@@ -0,0 +1,272 @@
+import {createHash, randomBytes, randomUUID} from 'node:crypto';
+import {mkdir, open, readFile, rename, unlink, chmod, rm, mkdtemp} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join, resolve} from 'node:path';
+import {targetUrl} from '../accounts.mjs';
+
+const digest = value => createHash('sha256').update(value).digest('hex');
+const reasons = new Set(['captcha', 'mfa', 'phone', 'provider_policy', 'human_credential_entry']);
+const instructions = {
+  captcha: ['complete the human check', 'requires a human check'],
+  mfa: ['complete the authentication challenge', 'requires multi-factor authentication'],
+  phone: ['complete the phone verification', 'requires phone verification'],
+  provider_policy: ['review and complete the approval shown', 'requires your approval'],
+  human_credential_entry: ['enter your account credentials and submit', 'requires your credentials'],
+};
+async function writePrivate(path, value) {
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  const file = await open(tmp, 'wx', 0o600);
+  try { await file.writeFile(JSON.stringify(value)); } finally { await file.close(); }
+  await rename(tmp, path);
+}
+function scope(account) {
+  for (const key of ['workspace', 'product', 'platform', 'accountRef']) {
+    if (key === 'product' && account?.product === null) continue;
+    if (typeof account?.[key] !== 'string' || !account[key] || account[key].length > 256) throw Error('Invalid browser account scope.');
+  }
+  return Object.fromEntries(['workspace', 'product', 'platform', 'accountRef'].map(k => [k, account[k]]));
+}
+
+/** Local long-lived service; adapters are trusted code, never supplied by model input.
+ * authorize must check current grants AND revocation on every call. Vault adapters
+ * enforce the same scope server-side. Raw state is passed only to vault adapters.
+ */
+export class BrowserHandoffRunner {
+  constructor({stateDir, authorize, vault, providers, launch, notifier = async () => {}, inbox,
+    now = Date.now, pollMs = 1000, humanTimeoutMs = 86400000}) {
+    if (!stateDir || !authorize || !vault?.save || !vault?.load || !providers) throw Error('Browser adapters are required.');
+    if (!Number.isFinite(pollMs) || pollMs < 1 || !Number.isFinite(humanTimeoutMs) || humanTimeoutMs < 1 || humanTimeoutMs > 86400000) throw Error('Invalid browser deadlines.');
+    Object.assign(this, {stateDir: resolve(stateDir), authorize, vault, providers, launch, notifier, inbox, now, pollMs, humanTimeoutMs});
+    this.jobs = new Map();
+  }
+  async allowed(account, action = 'account:manage') {
+    if (await this.authorize(scope(account), action) !== true) throw Error('Browser account access denied.');
+  }
+  key(account) { return digest(JSON.stringify(scope(account))); }
+  path(account) { return join(this.stateDir, this.key(account)); }
+  async read(account) {
+    try { return JSON.parse(await readFile(join(this.path(account), 'operation.json'), 'utf8')); }
+    catch (e) { if (e.code === 'ENOENT') return undefined; throw Error('Browser progress unreadable; reconcile before retrying.'); }
+  }
+  async persist(job) { await writePrivate(join(this.path(job.account), 'operation.json'), job.state); }
+  receipt(state, token) {
+    return {version: 1, flowId: state.flowId, action: state.action, origin: state.origin,
+      accountRef: state.accountRef, status: state.status, step: state.step,
+      ...(state.reason ? {reason: state.reason} : {}),
+      ...(state.humanRequest ? {humanRequest: state.humanRequest} : {}),
+      ...(token ? {resumeToken: token} : {}),
+      ...(state.lastVerifiedAt ? {lastVerifiedAt: state.lastVerifiedAt} : {})};
+  }
+  async status(account) {
+    await this.allowed(account, 'account:use');
+    const state = await this.read(account);
+    return state ? this.receipt(state) : {status: 'pending', step: 'not_started'};
+  }
+  async start({account, action, url, flowId = randomUUID()}) {
+    await this.allowed(account);
+    if (!['signup', 'login'].includes(action)) throw Error('Invalid browser action.');
+    const current = this.jobs.get(this.key(account));
+    if (current?.flight) await current.flight;
+    if (current && this.jobs.has(this.key(account))) return this.receipt(current.state);
+    const target = targetUrl(url), provider = this.providers[account.platform];
+    if (!provider || !provider.origins.includes(target.origin)) throw Error('Unsupported browser target.');
+    await mkdir(this.stateDir, {recursive: true, mode: 0o700});
+
+    await mkdir(this.path(account), {recursive: true, mode: 0o700});
+    await chmod(this.path(account), 0o700);
+    const lock = await this.lock(account);
+    let job;
+    try {
+      const previous = await this.read(account);
+      // Never repeat uncertain signup/submit operations, including after a crash.
+      if (previous && (previous.flowId === flowId || !['complete', 'revoked'].includes(previous.status))) {
+        await this.unlock(account, lock);
+        return this.receipt(previous);
+      }
+      if (previous?.status === 'revoked') throw Error('Account revoked; reconnect through account management.');
+      const state = {version: 1, ...scope(account), flowId, action, origin: target.origin,
+        url: target.href, status: 'step', step: 'inspect_form', acted: [], notified: [], createdAt: new Date(this.now()).toISOString()};
+      job = {account: {...account}, provider, state, lock};
+      await this.persist(job);
+      await this.open(job);
+      this.jobs.set(this.key(account), job);
+      const result = await this.tick(job);
+      this.schedule(job);
+      return result;
+    } catch {
+      if (job) { job.state.status = 'failed'; job.state.reason = 'browser_failed'; await this.persist(job); await this.close(job); }
+      else await this.unlock(account, lock);
+      throw Error('Browser could not start; inspect saved progress before retrying.');
+    }
+  }
+  async lock(account) {
+    try { return await open(join(this.path(account), 'runner.lock'), 'wx', 0o600); }
+    catch { throw Error('Browser operation locked; reconcile the existing runner before retrying.'); }
+  }
+  async unlock(account, lock) {
+    if (!lock) return;
+    await lock.close();
+    await unlink(join(this.path(account), 'runner.lock'));
+  }
+  async open(job) {
+    await rm(join(this.path(job.account),'profile'),{recursive:true,force:true});
+    const profile = await mkdtemp(join(tmpdir(),'actas-browser-'));
+    job.profile = profile;
+    await chmod(profile, 0o700);
+    const launch = this.launch || (async path => {
+      const {chromium} = await import('playwright');
+      const browser=await chromium.launch({headless:false,chromiumSandbox:true,ignoreDefaultArgs:['--use-mock-keychain']});
+      const context=await browser.newContext({acceptDownloads:false});
+      const close=context.close.bind(context);context.close=async()=>{try{await close();}finally{await browser.close();}};
+      return context;
+    });
+    job.context = await launch(profile);
+    const saved = await this.vault.load(scope(job.account));
+    // Vault restore is only for a fresh operation, never overwrites a human's
+    // in-progress profile when continuing a challenge.
+    if (saved && job.state.step === 'inspect_form') await job.context.setStorageState(saved);
+    job.page = job.context.pages()[0] || await job.context.newPage();
+    let url = job.state.url;
+    if (job.state.humanRequest && this.vault.loadProgress) {
+      const progress = await this.vault.loadProgress(scope(job.account));
+      if (progress?.flowId === job.state.flowId && job.provider.origins.includes(new URL(progress.url).origin)) {
+        await job.context.setStorageState(progress.storage); url = progress.url;
+      }
+    }
+    await job.page.goto(url);
+    await job.page.bringToFront();
+  }
+  schedule(job) {
+    if (!this.jobs.has(this.key(job.account)) || job.timer || ['complete', 'failed', 'revoked'].includes(job.state.status)) return;
+    if (job.state.humanRequest && this.now() >= Date.parse(job.state.humanRequest.expiresAt)) return;
+    job.timer = setTimeout(async () => {
+      job.timer = undefined;
+      try { await this.tick(job); }
+      catch { job.state.status = 'failed'; job.state.reason = 'browser_failed'; await this.persist(job).catch(() => {}); await this.close(job); }
+      this.schedule(job);
+    }, this.pollMs);
+    job.timer.unref?.();
+  }
+  async tick(job) {
+    // Single flight prevents a timer and explicit resume from submitting twice.
+    if (job.flight) return job.flight;
+    job.flight = this.advance(job);
+    try { return await job.flight; } finally { job.flight = undefined; }
+  }
+  async advance(job) {
+    await this.allowed(job.account);
+    const s = job.state;
+    if (s.humanRequest && this.now() >= Date.parse(s.humanRequest.expiresAt)) return this.receipt(s);
+    const observation = await job.provider.observe(job.page, job.account, s.action);
+    if (observation.kind === 'authenticated') {
+      // A provider verifier must establish the expected account at an allowed
+      // origin. Disappearing CAPTCHA or changed URL alone is never completion.
+      if (!job.provider.origins.includes(new URL(job.page.url()).origin) ||
+        await job.provider.verify(job.page, job.account) !== true) throw Error('Unverified browser account.');
+      await this.allowed(job.account);
+      await this.vault.save(scope(job.account), await job.context.storageState({indexedDB: true}));
+      s.status = 'complete'; s.step = 'verify_session'; s.lastVerifiedAt = new Date(this.now()).toISOString();
+      delete s.reason; delete s.humanRequest; delete s.resumeDigest;
+      await this.persist(job);
+      await this.close(job);
+      return this.receipt(s);
+    }
+    if (observation.kind === 'human') {
+      const reason = reasons.has(observation.reason) ? observation.reason : 'provider_policy';
+      const id = `${reason}:${observation.id || reason}`;
+      if (s.humanId !== id) {
+        s.humanId = id; delete s.humanRequest; delete s.resumeDigest;
+      }
+      if (!s.humanRequest) {
+        const token = randomBytes(32).toString('base64url');
+        const [instruction, why] = instructions[reason];
+        s.status = 'needs_human'; s.step = 'human'; s.reason = reason;
+        s.resumeDigest = digest(token);
+        const requestedAt=this.now();
+        s.humanRequest = {text: `In the ActAs browser window at ${s.origin}, ${instruction}. This service ${why}.`,
+          openedUrl: s.origin, createdAt: new Date(requestedAt).toISOString(), expiresAt: new Date(requestedAt + this.humanTimeoutMs).toISOString()};
+        // Persist deduplication BEFORE delivery. Uncertain delivery is never retried.
+        const notify = !s.notified.includes(id);
+        if (notify) s.notified.push(id);
+        if (this.vault.saveProgress) await this.vault.saveProgress(scope(job.account), {flowId: s.flowId, url: job.page.url(), storage: await job.context.storageState({indexedDB: true})});
+        await this.persist(job);
+        await job.page.bringToFront();
+        if (notify) { try { await this.notifier(this.receipt(s)); } catch { /* Caller receives the same request. */ } }
+        return this.receipt(s, token);
+      }
+      return this.receipt(s);
+    }
+    delete s.humanRequest; delete s.reason; delete s.resumeDigest; delete s.humanId;
+    s.status = 'step'; if (s.step === 'human') s.step = 'inspect_form';
+    if (observation.kind === 'email') {
+      if (!this.inbox || !job.provider.verifyEmail) throw Error('Product inbox adapter required.');
+      const id = `email:${observation.id}`;
+      if (!s.acted.includes(id)) {
+        s.status = 'step'; s.step = 'verify_email'; await this.persist(job);
+        // The inbox adapter validates product scope, sender, subject and since;
+        // the message/code stays entirely inside tool code, never a receipt.
+        await this.allowed(job.account);
+        const message = await this.inbox.waitFor(scope(job.account), observation.match);
+        if (message === undefined) return this.receipt(s);
+        await this.allowed(job.account);
+        s.acted.push(id); await this.persist(job);
+        await job.provider.verifyEmail(job.page, message, job.account);
+      }
+    } else if (observation.kind === 'step' && typeof observation.id === 'string') {
+      if (!s.acted.includes(observation.id)) {
+        s.acted.push(observation.id); s.status = 'step'; s.step = observation.id;
+        await this.persist(job); // Write-ahead: no automatic submission retry on crash.
+        await job.provider.advance(job.page, observation.id, job.account, s.action);
+      }
+    } else if (observation.kind !== 'waiting') throw Error('Unknown browser observation.');
+    await this.persist(job);
+    return this.receipt(s);
+  }
+  async resume({account, flowId, resumeToken}) {
+    await this.allowed(account);
+    let job = this.jobs.get(this.key(account));
+    const s = job?.state || await this.read(account);
+    if (!s || s.flowId !== flowId || typeof resumeToken !== 'string' || s.resumeDigest !== digest(resumeToken) ||
+      !s.humanRequest || this.now() >= Date.parse(s.humanRequest.expiresAt)) throw Error('Invalid or expired browser continuation.');
+    // Consume before any awaited browser work, including concurrent resumes.
+    delete s.resumeDigest;
+    if (!job) {
+      const lock = await this.lock(account);
+      job = {account: {...account}, provider: this.providers[account.platform], state: s, lock};
+      await this.persist(job);
+      try { await this.open(job); } catch { await this.close(job); throw Error('Browser continuation could not open.'); }
+      this.jobs.set(this.key(account), job);
+    } else await this.persist(job);
+    const result = await this.tick(job); this.schedule(job); return result;
+  }
+  // Only the trusted core calls this after its server-side resume token check.
+  async continueTrusted({account, flowId}) {
+    await this.allowed(account);
+    let job = this.jobs.get(this.key(account));
+    const state = job?.state || await this.read(account);
+    if (!state || state.flowId !== flowId) throw Error('Browser flow mismatch.');
+    if (['complete', 'failed', 'revoked'].includes(state.status)) return this.receipt(state);
+    if (!job) {
+      const lock = await this.lock(account);
+      job = {account: {...account}, provider: this.providers[account.platform], state, lock};
+      try { await this.open(job); } catch { await this.close(job); throw Error('Browser continuation could not open.'); }
+      this.jobs.set(this.key(account), job);
+    }
+    const result = await this.tick(job); this.schedule(job); return result;
+  }
+  async close(job) {
+    clearTimeout(job.timer); job.timer = undefined;
+    try { await job.context?.close(); } finally {
+      const lock = job.lock; job.lock = undefined;
+      await rm(job.profile || join(this.path(job.account),'profile'),{recursive:true,force:true});
+      await this.unlock(job.account, lock); this.jobs.delete(this.key(job.account));
+    }
+  }
+  async revoke(account) {
+    const job=this.jobs.get(this.key(account));if(job){if(job.flight)await job.flight.catch(()=>{});await this.close(job);}
+    await rm(this.path(account),{recursive:true,force:true});
+  }
+  async shutdown() {
+    for (const job of [...this.jobs.values()]) { if (job.flight) await job.flight.catch(() => {}); await this.close(job); }
+  }
+}

package/client/browser-adapter.mjs

@@ -0,0 +1,108 @@
+import {homedir} from 'node:os';
+import {join} from 'node:path';
+import {BrowserHandoffRunner} from './browser/runner.mjs';
+import {createBrowserProviders} from './browser/providers.mjs';
+
+/** Accounts MCP v1 boundary. All API bodies are scoped by trusted core options. */
+export function createBrowserAdapter(options) {
+  const {request, scope, waitForInbox, consumePrivateValue, saveReport} = options;
+  if (!request || !scope?.ownerId || typeof saveReport !== 'function') throw Error('Scoped browser API connection required.');
+  const body = data => ({...data, ownerId: scope.ownerId, productId: scope.productId ?? null});
+  const path = (account, suffix) => `/accounts_browser/${account.accountRef}_${suffix}`;
+  async function load(account, suffix) {
+    try {
+      const result = await request('/account-tools/flow/store', 'POST', body({accountRef:account.accountRef,flowId:activeFlows.get(account.accountRef)?.flowId,...(activeFlows.get(account.accountRef)?.resumeToken?{resumeToken:activeFlows.get(account.accountRef).resumeToken}:{}),store:suffix}));
+      return JSON.parse(result.value);
+    } catch { return undefined; } // Missing state requires verification, never success.
+  }
+  async function save(account, suffix, value) {
+    await request('/account-tools/flow/store', 'POST', body({accountRef:account.accountRef,flowId:activeFlows.get(account.accountRef)?.flowId,...(activeFlows.get(account.accountRef)?.resumeToken?{resumeToken:activeFlows.get(account.accountRef).resumeToken}:{}),store:suffix,value:JSON.stringify(value)}));
+    return path(account, suffix);
+  }
+  const reports = new Map();
+  const activeFlows = new Map();
+  const toReport = state => {
+    const account = reports.get(state.flowId)?.account;
+    return {flowId: state.flowId, accountRef: state.accountRef, origin: state.origin,
+      step: state.status === 'complete' ? 'complete' : state.step === 'human' || state.step.startsWith('enter_credentials') ? 'enter_credentials' : state.step.startsWith('submit') ? 'submit' : state.step,
+      ...(state.humanRequest ? {handoff: state.reason === 'phone' ? 'mfa' : state.reason, humanRequest: state.humanRequest} : {}),
+      ...(state.status === 'complete' ? {authenticated: true, principal: account.handle, observedUrl: state.origin,
+        observedAt: state.lastVerifiedAt, browserState: path(account, 'state')} : {})};
+  };
+  async function persistReport(report) {
+    const metadata = reports.get(report.flowId);
+    if (JSON.stringify(metadata.report) === JSON.stringify(report)) return;
+    if (metadata.uncertain) throw Error('Browser report delivery uncertain; reconcile before retrying.');
+    metadata.uncertain = true; // Never repeat a possibly accepted core mutation.
+    const result=await saveReport(report);
+    metadata.resumeToken=result?.resumeToken;
+    metadata.report = report; delete metadata.uncertain;
+  }
+  const runner = new BrowserHandoffRunner({
+    stateDir: options.stateDir || join(homedir(), '.local', 'state', 'actas', 'browser'),
+    launch: options.launch, pollMs: options.pollMs,
+    providers: options.providers || createBrowserProviders({emailRules: options.emailRules, async credentials(account) {
+      const ref = account.secretRefs?.password;
+      if (typeof ref !== 'string' || !/^\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+$/.test(ref)) throw Error('Invalid credential reference.');
+      const result = await request('/vault/read', 'POST', body({path: ref, action: 'reveal'}));
+      return {password: result.value};
+    }}),
+    async authorize(account, action) {
+      if (account.workspace !== scope.ownerId || account.product !== (scope.productId ?? null)) return false;
+      const current = await request('/account-tools/status', 'POST', body({accountRef: account.accountRef}));
+      const record = current.account || current;
+      if (record.status === 'revoked' || record.workspace !== account.workspace || record.product !== account.product) return false;
+      if (action === 'account:manage') {
+        const metadata = activeFlows.get(account.accountRef);
+        if (!metadata) return false;
+        await request('/account-tools/flow/check', 'POST', body({accountRef: account.accountRef, flowId: metadata.flowId}));
+      }
+      return true;
+    },
+    vault: {load: a => load(a, 'state'), save: (a, value) => save(a, 'state', value),
+      loadProgress: a => load(a, 'progress'), saveProgress: (a, value) => save(a, 'progress', value)},
+    notifier: async state => {
+      const report = toReport(state);
+      await persistReport(report);
+      await options.notifier?.(report);
+    },
+    inbox: waitForInbox && consumePrivateValue ? {async waitFor(account, match) {
+      const result = await waitForInbox(match);
+      if (result.status === 'pending') return undefined;
+      if (result.status !== 'matched' || !result.valueHandle) throw Error('Invalid verification email result.');
+      return consumePrivateValue(result.valueHandle);
+    }} : undefined,
+  });
+  // Background completion must reach the server without another MCP invocation.
+  const advance = runner.advance.bind(runner);
+  runner.advance = async job => {
+    const result = await advance(job), report = toReport(result);
+    const metadata = reports.get(result.flowId);
+    if (metadata && JSON.stringify(metadata.report) !== JSON.stringify(report)) {
+      await persistReport(report);
+    }
+    return result;
+  };
+  return {
+    async run(input) {
+      if (input.version !== 1 || !/^[A-Za-z0-9_-]{1,80}$/.test(input.account?.accountRef) ||
+        input.account.workspace !== scope.ownerId || input.account.product !== (scope.productId ?? null) ||
+        typeof input.flowId !== 'string' || !input.flowId) throw Error('Invalid scoped browser request.');
+      const provider = runner.providers[input.account.platform];
+      if (!provider?.origins.includes(input.origin)) throw Error('Unsupported browser origin.');
+      const metadata = {account: input.account, flowId: input.flowId, report: undefined};
+      reports.set(input.flowId, metadata); activeFlows.set(input.account.accountRef, metadata);
+      const state = await runner.read(input.account);
+      if (state && state.flowId !== input.flowId && !['complete','revoked'].includes(state.status)) throw Error('Existing browser flow requires reconciliation.');
+      if (state?.status === 'failed') throw Error('Browser flow failed; reconcile saved progress before continuing.');
+      const result = state?.flowId === input.flowId
+        ? await runner.continueTrusted({account: input.account, flowId: input.flowId})
+        : await runner.start({account: input.account, action: input.action, flowId: input.flowId, url: provider.entry[input.action]});
+      const report = toReport(result);
+      await persistReport(report); // Every dispatched invocation must settle core dispatch, even unchanged resume.
+      return report;
+    },
+    async revoke(account){if(account.workspace!==scope.ownerId||account.product!==(scope.productId??null))throw Error('Browser account scope denied.');await runner.revoke(account);activeFlows.delete(account.accountRef);},
+    close: () => runner.shutdown(),
+  };
+}

package/client/caller.mjs

@@ -0,0 +1,39 @@
+import {readFile} from 'node:fs/promises';
+import {targetUrl} from './accounts.mjs';
+
+export async function loadMappings(accountsPath) {
+ let mappings=[];try{if(accountsPath)mappings=JSON.parse(await readFile(accountsPath,'utf8'));}catch{throw new Error('Account mappings could not be read.');}
+ if(!Array.isArray(mappings)||mappings.some(m=>targetUrl(m.origin).origin!==m.origin||!Array.isArray(m.actions)||m.actions.some(a=>!['signup','login'].includes(a))||typeof m.accountRef!=='string'||typeof m.principal!=='string'||!m.principal||typeof m.custodian!=='string'||typeof m.authenticatedPath!=='string'||!m.authenticatedPath.startsWith('/')))throw new Error('Invalid authorised account mappings.');
+ if(new Set(mappings.map(m=>JSON.stringify([m.origin,m.accountRef]))).size!==mappings.length)throw new Error('Duplicate origin/account mapping.');
+ return mappings;
+}
+export function selectMapping(mappings,origin,accountRef) {
+ const candidates=mappings.filter(m=>m.origin===origin);
+ if(accountRef!==undefined){const selected=candidates.find(m=>m.accountRef===accountRef);if(!selected)throw new Error('The requested account is not assigned to this origin.');return selected;}
+ if(candidates.length>1)throw new Error('Multiple accounts are assigned to this origin. Choose --account: '+candidates.map(m=>m.accountRef).join(', '));
+ return candidates[0];
+}
+// Authority comes from owner configuration, never browser content or reports.
+export async function callerExecutor({accountsPath,reportPath,brokerHandler}={}) {
+ const mappings=await loadMappings(accountsPath);
+ let report;try{if(reportPath)report=JSON.parse(await readFile(reportPath,'utf8'));}catch{throw new Error('Browser continuation could not be read.');}
+ return async state=>{
+  const selected=selectMapping(mappings,state.origin,state.accountRef);
+  if(selected?.broker){if(!brokerHandler||selected.broker.kind!=='chief-infisical-caller')return {status:'blocked',reason:'broker_scope_denied'};return brokerHandler(state,selected,report);}
+  const mapping=selected?.actions.includes(state.action)?selected:undefined;
+  const browser={url:state.url,flowId:state.flowId,step:state.browser?.step||(state.progress?.step==='authorize_account'?undefined:state.progress?.step)||(mapping?'inspect_form':'assess_site'),credentialCustody:'external',...(mapping?{accountRef:mapping.accountRef,custodian:mapping.custodian,principal:mapping.principal,...(mapping.organization?{organization:mapping.organization}:{})}:{})};
+  if(!report&&state.progress?.step&&['mfa','captcha','provider_policy','human_credential_entry'].includes(state.progress.step))return {status:'needs_human',reason:state.progress.step,progress:state.progress};
+  if(!report)return {status:'needs_browser',reason:'browser_action_required',browser};
+  if(report.flowId!==state.flowId||report.origin!==state.origin)return {status:'failed',reason:'unverified'};
+  if(!mapping)return {status:'needs_human',reason:'authorization_required',progress:{step:'authorize_account'}};
+  if(['mfa','captcha','provider_policy','human_credential_entry'].includes(report.handoff))return {status:'needs_human',reason:report.handoff,progress:{step:report.handoff}};
+  const steps=['inspect_form','enter_credentials','submit','verify_email','verify_session'];
+  if(steps.includes(report.step))return {status:'needs_browser',reason:'browser_action_required',browser:{...browser,step:report.step}};
+  if(report.authenticated===true&&report.step==='complete'&&typeof report.observedUrl==='string'){
+   let observed;try{observed=targetUrl(report.observedUrl)}catch{return {status:'failed',reason:'unverified'}}
+   if(observed.origin!==mapping.origin||typeof mapping.authenticatedPath!=='string'||observed.pathname!==mapping.authenticatedPath||report.accountRef!==mapping.accountRef||report.principal!==mapping.principal||(mapping.organization&&report.organization!==mapping.organization)||!Number.isFinite(Date.parse(report.observedAt))||Date.parse(report.observedAt)>Date.now()||Date.now()-Date.parse(report.observedAt)>300000)return {status:'failed',reason:'unverified'};
+   return {status:'succeeded',verification:{origin:state.origin,authenticated:true,method:'authenticated_page',source:'authorised_caller_observation'}};
+  }
+  return {status:'failed',reason:'unverified'};
+ };
+}

package/client/configure.mjs

@@ -0,0 +1,45 @@
+import {readFile,mkdir,open,rename,unlink} from 'node:fs/promises';
+import {homedir} from 'node:os';
+import {join,dirname,resolve} from 'node:path';
+import {createHash,randomUUID} from 'node:crypto';
+import {targetUrl} from './accounts.mjs';
+import {loadMappings} from './caller.mjs';
+function verificationRule(rule) {
+ if(rule===undefined)return undefined;
+ if(!rule||!Array.isArray(rule.senders)||!rule.senders.length||rule.senders.length>20||rule.senders.some(s=>typeof s!=='string'||!/^[-a-zA-Z0-9_.+]+@[-a-zA-Z0-9.]+$/.test(s)))throw Error();
+ const senders=[...new Set(rule.senders)];
+ if(rule.kind==='code'){
+  if(typeof rule.label!=='string'||!rule.label||rule.label.length>200||/[\r\n]/.test(rule.label)||!Number.isInteger(rule.digits)||rule.digits<4||rule.digits>10)throw Error();
+  return {kind:'code',senders,label:rule.label,digits:rule.digits};
+ }
+ if(rule.kind!=='link'||!Array.isArray(rule.links)||!rule.links.length||rule.links.length>20)throw Error();
+ const links=rule.links.map(r=>{
+  if(!r||targetUrl(r.origin).origin!==r.origin||typeof r.path!=='string'||!r.path.startsWith('/')||r.path.startsWith('//')||/[?#]/.test(r.path)||new URL(r.path,r.origin).pathname!==r.path)throw Error();
+  return {origin:r.origin,path:r.path};
+ });
+ return {kind:'link',senders,links};
+}
+export async function configureAccount(bundlePath,{accountsPath=process.env.ACTAS_ACCOUNTS_FILE||join(homedir(),'.config','actas','accounts.json')}={}){
+ let bundle;try{const raw=await readFile(bundlePath,'utf8');if(raw.length>65536)throw Error();bundle=JSON.parse(raw);}catch{throw new Error('Could not read account connection file.');}
+ const m=bundle?.mapping;let verification;
+ try{
+ if(bundle.version!==1||typeof bundle.token!=='string'||!/^actas_[\w-]+\.[\w-]+$/.test(bundle.token)||!m||targetUrl(m.origin).origin!==m.origin||typeof m.accountRef!=='string'||!m.accountRef||typeof m.principal!=='string'||!m.principal||!Array.isArray(m.actions)||!m.actions.length||m.actions.some(a=>!['signup','login'].includes(a))||typeof m.authenticatedPath!=='string'||!m.authenticatedPath.startsWith('/')||m.authenticatedPath.startsWith('//')||/[?#]/.test(m.authenticatedPath)||m.credentials?.kind!=='actas-external'||targetUrl(m.credentials.url).origin!==m.credentials.url||typeof m.credentials.secretId!=='string'||!m.credentials.secretId||typeof m.mailbox?.emailId!=='string'||!m.mailbox.emailId)throw Error();
+ verification=verificationRule(m.mailbox.verification);
+ }catch{throw new Error('Invalid account connection. No configuration was changed.');}
+ const file=resolve(accountsPath),dir=dirname(file);await mkdir(dir,{recursive:true,mode:0o700});
+ let lock;try{lock=await open(file+'.lock','wx',0o600);}catch{throw new Error('Account configuration is busy. Retry after the other operation finishes.');}
+ try{
+ let mappings;try{mappings=await loadMappings(file);}catch(error){try{await readFile(file);throw error;}catch(e){if(e.code!=='ENOENT')throw error;mappings=[];}}
+ const id=createHash('sha256').update(JSON.stringify([m.origin,m.accountRef])).digest('hex');
+ const tokenPath=join(dir,'tokens',id+'.token');
+ // Construct an allowlisted mapping; imported paths, drivers and brokers are ignored.
+ const mapping={origin:m.origin,accountRef:m.accountRef,principal:m.principal,custodian:'ActAs',actions:m.actions,authenticatedPath:m.authenticatedPath,credentials:{kind:'actas-external',url:m.credentials.url,secretId:m.credentials.secretId,tokenPath},mailbox:{emailId:m.mailbox.emailId,...(verification?{verification}:{})}};
+ const prior=mappings.find(x=>x.origin===m.origin&&x.accountRef===m.accountRef);
+ if(prior&&JSON.stringify(prior)!==JSON.stringify(mapping))throw new Error('An existing account mapping differs. It was preserved.');
+ await mkdir(dirname(tokenPath),{recursive:true,mode:0o700});
+ async function save(path,value){const tmp=path+'.'+randomUUID();const out=await open(tmp,'wx',0o600);try{await out.writeFile(value);}finally{await out.close();}await rename(tmp,path);}
+ await save(tokenPath,bundle.token);
+ if(!prior)await save(file,JSON.stringify([...mappings,mapping],null,2)+'\n');
+ return {status:'configured',origin:m.origin,accountRef:m.accountRef};
+ }finally{await lock.close();await unlink(file+'.lock');}
+}

package/client/credential-helper.mjs

@@ -0,0 +1,24 @@
+// Ephemeral loopback delivery UI used by the calling agent's documented browser.
+import {createServer} from 'node:http';
+import {randomBytes,timingSafeEqual} from 'node:crypto';
+process.once('message',({values})=>{
+ const token=randomBytes(32).toString('hex');let origin;
+ const page=`<!doctype html><html><head><title>ActAs local credential delivery</title><meta name="viewport" content="width=device-width"></head><body><h1>ActAs credential delivery</h1><p>Assigned account. Load each field for transfer into its authorised signup, verification or login form. Values are masked. Use Copy loaded value to transfer through your authorised browser clipboard, then clear the helper and clipboard.</p><button data-field="code">Load verification code</button><button data-field="username">Load username</button><button data-field="verificationUrl">Load verification link</button><button data-field="email">Load email</button><button data-field="password">Load password</button><button data-field="operator">Load operator key</button><label>Credential delivery<input id="delivery" type="password" readonly autocomplete="off" spellcheck="false"></label><button id="copy">Copy loaded value</button><button id="clear">Clear loaded value</button><button id="clear-clipboard">Clear clipboard</button><p id="status"></p><script>document.querySelectorAll('button[data-field]').forEach(b=>b.addEventListener('click',async()=>{const r=await fetch('/copy/'+b.dataset.field,{method:'POST'});if(!r.ok){document.getElementById('status').textContent='Delivery unavailable';return}document.getElementById('delivery').value=await r.text();document.getElementById('status').textContent=b.textContent.replace('Load','Loaded')}));document.getElementById('copy').onclick=async()=>{try{await navigator.clipboard.writeText(document.getElementById('delivery').value);document.getElementById('status').textContent='Copied loaded value'}catch{document.getElementById('status').textContent='Clipboard unavailable'}};document.getElementById('clear-clipboard').onclick=async()=>{try{await navigator.clipboard.writeText('');document.getElementById('status').textContent='Clipboard cleared'}catch{document.getElementById('status').textContent='Clipboard unavailable'}};document.getElementById('clear').onclick=()=>{document.getElementById('delivery').value='';document.getElementById('status').textContent='Cleared'};</script></body></html>`;
+ const server=createServer((req,res)=>{
+  res.setHeader('Cache-Control','no-store');res.setHeader('Referrer-Policy','no-referrer');res.setHeader('X-Frame-Options','DENY');res.setHeader('X-Content-Type-Options','nosniff');
+  if(req.headers.host!==new URL(origin).host){res.writeHead(403);return res.end();}
+  if(req.method==='GET'&&req.url==='/health'){res.writeHead(200);return res.end('ready-v3');}
+  if(req.method==='GET'&&req.url==='/'){
+   res.setHeader('Content-Type','text/html');res.setHeader('Set-Cookie',`delivery=${token}; HttpOnly; SameSite=Strict; Path=/`);
+   res.setHeader('Content-Security-Policy',"default-src 'none'; script-src 'unsafe-inline'; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'");
+   return res.end(page);
+  }
+  const cookie=(req.headers.cookie||'').split('; ').find(x=>x.startsWith('delivery='))?.slice(9)||'';
+  if(req.method!=='POST'||req.headers.origin!==origin||Buffer.byteLength(cookie)!==Buffer.byteLength(token)||!timingSafeEqual(Buffer.from(cookie),Buffer.from(token))){res.writeHead(403);return res.end();}
+  const field=req.url?.slice('/copy/'.length);
+  if(!req.url?.startsWith('/copy/')||!['email','password','operator','code','username','verificationUrl'].includes(field)||typeof values[field]!=='string'){res.writeHead(404);return res.end();}
+  res.setHeader('Content-Type','text/plain');res.end(values[field]);
+ });
+ server.listen(0,'127.0.0.1',()=>{origin=`http://127.0.0.1:${server.address().port}`;process.send({url:origin+'/'});process.disconnect();});
+ setTimeout(()=>{server.close();process.exit(0)},300000).unref();
+});

package/client/external-caller.mjs

@@ -0,0 +1,79 @@
+import {readFile} from 'node:fs/promises';
+import {ActAs} from '../scripts/proof-client.mjs';
+import {loadMappings,selectMapping,callerExecutor} from './caller.mjs';
+import {helper} from './helper.mjs';
+
+// Provider messages are untrusted. Only exact owner-assigned senders, recipients,
+// verification paths and recent received messages can supply a challenge.
+export function emailChallenge(message,config,principal,since,now=Date.now()) {
+ const timestamp=Date.parse(message.timestamp);
+ if(!Number.isFinite(since)||since>now||!Number.isFinite(timestamp)||timestamp<since||timestamp>now||now-timestamp>900000||!message.labels?.includes('received'))return;
+ const address=value=>typeof value==='string'?value.match(/<([^<>]+)>$/)?.[1]||value:undefined;
+ if(!config.senders?.includes(address(message.from))||!Array.isArray(message.to)||!message.to.some(v=>address(v)===principal)||typeof message.text!=='string')return;
+ if(config.kind==='code'){
+  // A fixed label avoids arbitrary regex execution and ambiguous numbers in mail.
+  if(typeof config.label!=='string'||!config.label||!Number.isInteger(config.digits)||config.digits<4||config.digits>10)return;
+  const candidates=message.text.split(/\r?\n/).filter(line=>line.startsWith(config.label)).map(line=>line.slice(config.label.length).trim()).filter(v=>/^\d+$/.test(v)&&v.length===config.digits);
+  return candidates.length===1?{code:candidates[0]}:undefined;
+ }
+ if(config.kind==='link'){
+  const candidates=[...new Set(message.text.match(/https:\/\/[^\s<>"']+/g)||[])].filter(value=>{
+   try{const url=new URL(value);return !url.username&&!url.password&&config.links?.some(rule=>rule.origin===url.origin&&rule.path===url.pathname);}catch{return false;}
+  });
+  return candidates.length===1?{verificationUrl:candidates[0]}:undefined;
+ }
+}
+
+export async function externalExecutor({accountsPath,reportPath,clientFactory=options=>new ActAs(options),deliver=helper}={}) {
+ const mappings=await loadMappings(accountsPath);
+ const caller=await callerExecutor({accountsPath,reportPath});
+ let report;if(reportPath)report=JSON.parse(await readFile(reportPath,'utf8'));
+ return async state=>{
+  const mapping=selectMapping(mappings,state.origin,state.accountRef);
+  if(mapping?.credentials?.kind!=='actas-external')return null;
+  if(!mapping.actions.includes(state.action))return {status:'blocked',reason:'authorization_required'};
+  const continuation=await caller(state);
+  if(continuation.status==='failed'||continuation.status==='needs_browser'&&continuation.browser.step==='inspect_form')return continuation;
+  try{
+   const token=(await readFile(mapping.credentials.tokenPath,'utf8')).trim();
+   const client=clientFactory({url:mapping.credentials.url,token});
+   await client.request('/accounts/'+encodeURIComponent(mapping.accountRef)+'/registry-observe',{method:'POST',body:{action:state.action,completed:continuation.status==='succeeded'}});
+  }catch{return {status:'blocked',reason:'registry_unavailable'};}
+  if(continuation.status!=='needs_browser')return continuation;
+  const step=continuation.browser.step;
+  if(!['enter_credentials','verify_email'].includes(step))return continuation;
+  // The continuation report is account-bound before any secret or mail access.
+  if(report&&(report.accountRef!==mapping.accountRef||report.principal!==mapping.principal))return {status:'failed',reason:'unverified'};
+  try{
+   const token=(await readFile(mapping.credentials.tokenPath,'utf8')).trim();
+   const client=clientFactory({url:mapping.credentials.url,token});
+   const [account,email]=await Promise.all([client.get(mapping.accountRef),client.get(mapping.mailbox.emailId)]);
+   if(account.metadata.emailId!==email.id||!account.metadata.secretIds?.includes(mapping.credentials.secretId)||email.metadata.address!==mapping.principal)throw new Error('scope');
+   let values;
+   if(step==='enter_credentials'){
+    const credential=JSON.parse((await client.reveal(mapping.credentials.secretId)).value);
+    if(credential.origin!==state.origin||credential.email!==mapping.principal||typeof credential.password!=='string'||!credential.password)throw new Error('scope');
+    values={email:credential.email,password:credential.password,...(typeof credential.username==='string'?{username:credential.username}:{})};
+   }else{
+    if(!mapping.mailbox.verification)return {...continuation,browser:{...continuation.browser,step:'verify_email',mailboxUrl:mapping.credentials.url+'/app/inboxes/'+encodeURIComponent(email.id),nextStep:'Open the assigned inbox, use the matching verification message in the website, then report verify_session. No automatic extraction rule is configured.'}};
+    const since=Date.parse(state.progress?.verificationRequestedAt||report?.verificationRequestedAt);
+    if(!Number.isFinite(since)||since<Date.parse(state.createdAt)||since>Date.now())return {status:'failed',reason:'unverified'};
+    const progress={step:'verify_email',verificationRequestedAt:new Date(since).toISOString()};
+    const listing=await client.request('/emails/'+encodeURIComponent(email.id)+'/messages?limit=20');
+    const matches=[];
+    for(const item of listing.messages||listing){
+     if(!item.labels?.includes('received'))continue;
+     const detail=await client.message(email.id,item.message_id||item.id);
+     const candidate=emailChallenge({...detail,labels:item.labels,timestamp:item.timestamp},mapping.mailbox.verification,mapping.principal,since);
+     if(candidate)matches.push(candidate);
+    }
+    // Never guess between concurrent challenges on a shared mailbox.
+    if(matches.length!==1)return {status:'blocked',reason:'verification_pending',progress};
+    values=matches[0];
+    continuation.progress=progress;
+   }
+   continuation.browser={...continuation.browser,credentialCustody:'actas',credentialHelperUrl:await deliver(values)};
+   return continuation;
+  }catch{return {status:'blocked',reason:'vault_unavailable'};}
+ };
+}

package/client/helper.mjs

@@ -0,0 +1,12 @@
+import {fork} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+export async function helper(values){
+ return new Promise((resolve,reject)=>{
+  const env=Object.fromEntries(['PATH','HOME','TMPDIR','SYSTEMROOT'].filter(k=>process.env[k]).map(k=>[k,process.env[k]]));
+  const child=fork(fileURLToPath(new URL('./credential-helper.mjs',import.meta.url)),[],{env,detached:true,stdio:['ignore','ignore','ignore','ipc']});
+  const timer=setTimeout(()=>{child.kill();reject(new Error('helper'))},10000);
+  child.once('error',()=>{clearTimeout(timer);reject(new Error('helper'))});
+  child.once('message',data=>{clearTimeout(timer);child.unref();resolve(data.url)});
+  child.send({values});
+ });
+}