actas 0.8.0 → 0.9.0

package/README.md

@@ -11,10 +11,11 @@ the token from your scoped ActAs connection in the Authorization bearer header,
 saved through your client's protected credential settings. Do not put the token
 in the endpoint URL, a prompt, or source control. OAuth is not offered.
 
-The remote endpoint shares the 26 stdio tool schemas and applies the same API
+The remote endpoint shares the stdio tool schemas and applies the same API
 permissions and revocation checks on every call. Browser flows still need a
-local browser adapter. Private verification handles and registered executable
-consumers return `needs_local_runtime` remotely; use the local client below.
+local browser adapter. Private verification handles (`actas_inbox_wait_for`) and
+registered executable consumers (`actas_account_use`) are not listed remotely;
+use the local client below.
 
 Stored passwords and TOTP codes are withheld by default. To return them remotely,
 explicitly configure `ActAs-MCP-Secret-Output: allow` as an additional header.

package/client/accounts-server.mjs

@@ -3,7 +3,7 @@ import {z} from 'zod';
 
 const ref=z.string().regex(/^[A-Za-z0-9_-]{1,80}$/),path=z.string().regex(/^\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+$/).max(512);
 const select={accountRef:ref};
-export function createAccountsMcp(runtime){
+export function createAccountsMcp(runtime,{omit=[]}={}){
  const server=new McpServer({name:'actas-accounts',version:'0.1.0'},{maxToolInputElements:300});
  const definitions=[
   ['actas_identity_create','Create an identity with a permanently reserved chosen email name (management). inbox:true also allocates its inbox.',{name:z.string().min(1).max(80),localPart:z.string().min(3).max(40).optional(),domain:z.string().min(3).max(253).optional(),inbox:z.boolean().optional()}],
@@ -38,9 +38,9 @@ export function createAccountsMcp(runtime){
   ['actas_account_revoke','Revoke future ActAs account use and pending handles (owner/management).',select],
   ['actas_inbox_wait_for','Wait for a received verification message. Returns a private value handle; never the code/link.',{emailId:z.string().min(1).max(160),sender:z.string().email().max(254),subject:z.string().min(1).max(200),after:z.string().datetime(),linkOrigin:z.string().url().optional(),linkPath:z.string().max(1024).optional(),codePattern:z.string().max(30).optional(),timeoutMs:z.number().int().min(0).max(30000).optional()}]
  ];
- for(const [name,description,shape] of definitions)server.registerTool(name,{description,inputSchema:z.object(shape).strict()},async args=>{
+ for(const [name,description,shape] of definitions.filter(([name])=>!omit.includes(name)))server.registerTool(name,{description,inputSchema:z.object(shape).strict()},async args=>{
   try{const result=await runtime.invoke(name,args);return {content:[{type:'text',text:JSON.stringify(result)}]};}
-  catch{return {isError:true,content:[{type:'text',text:'ActAs account operation failed. Check account status and permissions before retrying; no automatic retry was made.'}]};}
+  catch(error){return {isError:true,content:[{type:'text',text:typeof error?.actasRefusal==='string'?error.actasRefusal+' No automatic retry was made.':'ActAs account operation failed. Check account status and permissions before retrying; no automatic retry was made.'}]};}
  });
  return server;
 }

package/client/identity.mjs

@@ -22,7 +22,11 @@ export async function readIdentityConnection(file=path()){return readConnection(
 export async function identityRequest(connection,route,method='GET',body,extraHeaders={}){
  let response;
  try{response=await fetch(connection.apiUrl+'/api/v1'+route,{method,redirect:'error',headers:{Origin:connection.apiUrl,Authorization:'Bearer '+connection.token,'Content-Type':'application/json',...extraHeaders},signal:AbortSignal.timeout(Math.max(15000,Math.min(75000,(body?.timeoutMs??0)+15000))),...(body===undefined?{}:{body:JSON.stringify(body)})});}catch{throw Error('ActAs could not be reached. No automatic retry was made.');}
- if(!response.ok)throw Error(response.status===401?'Access expired or was revoked. Reconnect through your workspace.':response.status===403?'This connection does not permit that action.':`ActAs request failed (${response.status}).`);
+ if(!response.ok){
+  const error=Error(response.status===401?'Access expired or was revoked. Reconnect through your workspace.':response.status===403?'This connection does not permit that action.':`ActAs request failed (${response.status}).`);
+  if(response.status===403){const message=(await response.json().catch(()=>null))?.error?.message;if(typeof message==='string'){error.message=message;error.actasRefusal=message;}}
+  throw error;
+ }
  try{return (await response.json()).data;}catch{throw Error('Invalid ActAs response.');}
 }
 export async function connectIdentity(file){

package/client/phone.mjs

@@ -0,0 +1,86 @@
+import {identityRequest,readIdentityConnection} from './identity.mjs';
+
+// Phones this connection may use and the texts each has passed on. Shows only what GET /phones and
+// GET /phones/:id/messages already return to the credential. The number is the one on record: a person
+// typed it when the phone was added, and the phone app does not report its own.
+export const phoneHelp=`Phones
+  actas phone                                      Phones this connection may use: number on record, connected or not, last heard from
+  actas phone texts [<phone-id>] [--since <time>]  Latest texts: sender, time sent, time ActAs got it, code
+  actas phone check [<phone-id>] < number.txt      Does a number match the number on record? Answers match or no match
+The number on record is what a person typed when the phone was added; the phone does
+not report its own number. A text that arrives is the proof that the number is right.
+Connected means the ActAs Phone app is paired with that phone. The phone id may be left
+out when the connection has one phone. Texts are kept 7 days. Listing phones needs the
+"See names" permission. Reading texts needs "Read SMS codes"; without "See names", name
+the phone id. A text's words appear only with "Read forwarded SMS".
+`;
+const DOCS='https://actas.dev/docs#phone-forwarding';
+const PAIR=`A person signed in to the workspace opens Phones, chooses Pair phone and scans the code with the ActAs Phone app on a dedicated Android phone, then turns forwarding on in the app. Guide: ${DOCS}`;
+const NUMBER_NOTE='The number on record is what a person typed when the phone was added; the phone does not report its own number. A text that arrives is the proof that it is right.';
+// Country calling codes are prefix-free: 1 and 7 stand alone, these have two digits, the rest three.
+const TWO=new Set('20 27 30 31 32 33 34 36 39 40 41 43 44 45 46 47 48 49 51 52 53 54 55 56 57 58 60 61 62 63 64 65 66 81 82 84 86 90 91 92 93 94 95 98'.split(' '));
+export const callingCode=number=>/^\+[1-9]\d{6,14}$/.test(number??'')?'+'+(number[1]==='1'||number[1]==='7'?number[1]:TWO.has(number.slice(1,3))?number.slice(1,3):number.slice(1,4)):null;
+const iso=ms=>Number.isFinite(ms)&&ms>0?new Date(ms).toISOString():null;
+const show=phone=>({id:phone.id,label:phone.label,numberOnRecord:phone.number||null,countryCode:callingCode(phone.number),country:phone.country||null,
+ connected:Boolean(phone.forwarding),device:phone.forwarding?.deviceName??null,pairedAt:iso(phone.forwarding?.pairedAt),lastHeardAt:iso(phone.forwarding?.lastSeenAt),
+ ...(phone.forwarding?{}:{note:'No phone app is paired with this phone, so no text can arrive. '+PAIR})});
+// Listing phones needs "See names" (resources:read). A connection with only "Read SMS codes" can still read
+// a phone's texts by its id, which is all the texts route asks for.
+const NO_LIST='This connection may not list phones: it lacks the "See names" permission (resources:read). If it holds "Read SMS codes" for a phone it can still read that phone\'s texts by id: actas phone texts <phone-id>. The workspace owner can find the id on the Phones page, or add "See names" to this connection.';
+async function list(connection){
+ let phones;
+ try{phones=await identityRequest(connection,'/phones');}
+ catch(error){if(/resources:read/.test(error.actasRefusal??''))throw Object.assign(Error(NO_LIST),{noList:true});throw error;}
+ if(!Array.isArray(phones))throw Error('Invalid ActAs response.');
+ return phones;
+}
+async function pick(connection,id,texts=false){
+ let phones;
+ try{phones=await list(connection);}
+ catch(error){if(texts&&id&&error.noList)return {id,unlisted:true};throw error;}
+ if(id)return phones.find(p=>p.id===id)??{id,unlisted:true};
+ if(!phones.length)throw Error('This connection can see no phone. If the workspace has one, ask its owner to give this connection access to it. To add one: '+PAIR);
+ if(phones.length>1)throw Error('This connection can see '+phones.length+' phones. Name one: run actas phone for their ids.');
+ return phones[0];
+}
+async function stdin(){let input='';for await(const chunk of process.stdin){input+=chunk;if(input.length>200)throw Error('Send one phone number on stdin.');}return input;}
+
+export async function runPhoneCommand(args){
+ const [command,action,...rest]=args;
+ if(command!=='phone')return false;
+ try{
+  const connection=await readIdentityConnection();
+  let result;
+  if(action===undefined){
+   const phones=await list(connection);
+   result=phones.length?{phones:phones.map(show),note:NUMBER_NOTE}
+    :{phones:[],message:'This connection can see no phone. If the workspace has one, ask its owner to give this connection access to it. To add one: '+PAIR};
+  }else if(action==='texts'){
+   const id=rest[0]&&!rest[0].startsWith('--')?rest.shift():null;
+   if(rest.length&&(rest.length!==2||rest[0]!=='--since'))throw Error('Use actas phone texts [<phone-id>] [--since <time>].');
+   const since=rest.length?Date.parse(rest[1]):0;
+   if(!Number.isFinite(since)||since<0)throw Error('Give --since a time such as 2026-11-12T05:00:00Z.');
+   const phone=await pick(connection,id,true);
+   const texts=await identityRequest(connection,'/phones/'+encodeURIComponent(phone.id)+'/messages'+(since?'?since='+since:''));
+   if(!Array.isArray(texts))throw Error('Invalid ActAs response.');
+   const connected=phone.forwarding===undefined?undefined:Boolean(phone.forwarding);
+   result={phone:{id:phone.id,...(phone.label?{label:phone.label}:{}),...(connected===undefined?{}:{connected,lastHeardAt:iso(phone.forwarding?.lastSeenAt)})},
+    // sentAt is the text's own time as the phone reports it; reachedActasAt is when ActAs stored it.
+    texts:texts.map(t=>({from:t.from,sentAt:iso(t.receivedAt),reachedActasAt:iso(t.storedAt),secondsToReachActas:Number.isFinite(t.storedAt)&&Number.isFinite(t.receivedAt)?Math.round((t.storedAt-t.receivedAt)/100)/10:null,code:t.code??null,...('body' in t?{body:t.body,untrusted:true}:{})})),
+    ...(texts.length?{}:{message:connected===false?'No phone app is paired with this phone, so no text can arrive. '+PAIR
+     :'No text from this phone '+(since?'since '+new Date(since).toISOString():'in the last 7 days')+'. A text that reaches the phone reaches ActAs within seconds. If one was expected, it was not sent to this phone: check the number and country code on the sender\'s form against the number on record (actas phone).'})};
+  }else if(action==='check'&&rest.length<=1){
+   const phone=await pick(connection,rest[0]);
+   if(phone.unlisted)throw Error('This connection cannot see that phone. Run actas phone for the ones it can.');
+   if(!phone.number)throw Error('No number is on record for this phone.');
+   const raw=(await stdin()).trim().replace(/[\s().-]/g,'');
+   if(!/^\+?\d{4,15}$/.test(raw))throw Error('Send one phone number on stdin, digits with an optional leading +.');
+   const given=raw.replace('+',''),record=phone.number.replace('+',''),match=given===record;
+   // Never echoes either number: the answer is match or no match, plus the record's country code.
+   result={phone:{id:phone.id,label:phone.label},match,countryCodeOnRecord:callingCode(phone.number),
+    ...(!match&&!raw.startsWith('+')&&record.endsWith(given)&&record.length-given.length<=3?{note:'The digits match the number on record without its country code.'}:{})};
+  }else throw Error('Use actas phone, actas phone texts [<phone-id>] [--since <time>] or actas phone check [<phone-id>].');
+  process.stdout.write(JSON.stringify(result,null,2)+'\n');
+ }catch(error){process.stderr.write(JSON.stringify({status:'failed',message:error.message})+'\n');process.exitCode=1;}
+ return true;
+}

package/client/public-cli.mjs

@@ -5,6 +5,8 @@ import {runManagementCommand,managementHelp} from './management.mjs';
 if(await runManagementCommand(process.argv.slice(2)))process.exit(process.exitCode||0);
 import {runVaultCommand,vaultHelp} from './vault.mjs';
 if(await runVaultCommand(process.argv.slice(2)))process.exit(process.exitCode||0);
+import {runPhoneCommand,phoneHelp} from './phone.mjs';
+if(await runPhoneCommand(process.argv.slice(2)))process.exit(process.exitCode||0);
 import {runIdentityCommand,identityHelp} from './identity.mjs';
 if(await runIdentityCommand(process.argv.slice(2)))process.exit(process.exitCode||0);
 import {configureAccount} from './configure.mjs';
@@ -17,7 +19,7 @@ import {externalExecutor} from './external-caller.mjs';
 const [action,url,...args]=process.argv.slice(2);
 if(action==='configure'){try{if(!url||args.length)throw new Error('Use actas configure <connection.json>.');console.log(JSON.stringify(await configureAccount(url)));}catch(e){console.error(JSON.stringify({status:'failed',message:e.message}));process.exitCode=1;}process.exit(process.exitCode||0);}
 if(!action||['help','--help','-h'].includes(action)){
- console.log(registryHelp+"\n"+managementHelp+"\n"+identityHelp+"\n"+vaultHelp);
+ console.log(registryHelp+"\n"+managementHelp+"\n"+identityHelp+"\n"+phoneHelp+"\n"+vaultHelp);
 }else try{
  if(!['signup','login'].includes(action)||!url||args.length%2)throw new Error('Use actas signup <url> or actas login <url>.');
  const flags={};for(let i=0;i<args.length;i+=2){if(!['--account','--continue'].includes(args[i])||flags[args[i]]||!args[i+1])throw new Error('Unknown or repeated option.');flags[args[i]]=args[i+1];}

package/client/vault.mjs

@@ -21,7 +21,7 @@ export const vaultHelp=`Workspace vault (exact and folder grants; no values in c
   actas script add /path/script
   actas script check /path/script
   actas grant list
-  actas grant add <client|identity>:ID /path <read|write|reveal|run|totp:code> [--folder]
+  actas grant add <client|identity>:ID /path <read|write|reveal|run|totp:code|session:use> [--folder]
   actas grant revoke ID
 Connected agents and management automation use ACTAS_CONNECTION_FILE. Paths default to ACTAS_VAULT_PATH
 or /shared for run and env sync. For owner grant management use a
@@ -120,7 +120,7 @@ export async function runVaultCommand(args){
    else if(cmd==='card'&&sub==='status'||cmd==='script'&&sub==='check'){if(rest.length!==1)fail();result=await requestVault(ctx,'/read',{path:validPath(rest[0]),action:cmd==='script'?'run':'read'});}
    else if(cmd==='script'&&sub==='add'){if(rest.length!==1)fail();result=await requestVault(ctx,'/set',{path:validPath(rest[0]),kind:'script'});}
    else if(cmd==='grant'&&sub==='list'){if(rest.length)fail();const query=new URLSearchParams({ownerId:ctx.scope.ownerId,...(ctx.scope.productId?{productId:ctx.scope.productId}:{})});result=await requestVault(ctx,'/grants?'+query,undefined,'GET');}
-   else if(cmd==='grant'&&sub==='add'){if(rest.length!==3&&!(rest.length===4&&rest[3]==='--folder'))fail();const m=/^(client|identity):(.+)$/.exec(rest[0]);if(!m||!['read','write','reveal','run','totp:code'].includes(rest[2]))fail();result=await requestVault(ctx,'/grants',{principalKind:m[1],principalId:m[2],path:validPath(rest[1]),action:rest[2],folder:rest[3]==='--folder'});}
+   else if(cmd==='grant'&&sub==='add'){if(rest.length!==3&&!(rest.length===4&&rest[3]==='--folder'))fail();const m=/^(client|identity):(.+)$/.exec(rest[0]);if(!m||!['read','write','reveal','run','totp:code','session:use'].includes(rest[2]))fail();result=await requestVault(ctx,'/grants',{principalKind:m[1],principalId:m[2],path:validPath(rest[1]),action:rest[2],folder:rest[3]==='--folder'});}
    else if(cmd==='grant'&&sub==='revoke'){if(rest.length!==1)fail();result=await requestVault(ctx,'/grants/'+encodeURIComponent(rest[0]),undefined,'DELETE');}
    else fail();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "actas",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "mcpName": "dev.actas/accounts",
   "type": "module",
   "exports": {