actas 0.5.1 → 0.7.0

package/README.md

@@ -11,7 +11,7 @@ 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 21 stdio tool schemas and applies the same API
+The remote endpoint shares the 26 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.

package/client/accounts-inbox.mjs

@@ -27,16 +27,18 @@ export function verificationValue(message,args,now=Date.now()){
  if(args.codePattern){const re=new RegExp(`(?:^|[^A-Za-z0-9])(${args.codePattern})(?=$|[^A-Za-z0-9])`),match=re.exec(body);return match?.[1];}
  for(const candidate of body.match(/https:\/\/[^\s<>"']+/g)??[]){try{const url=new URL(candidate);if(url.origin===args.linkOrigin&&url.pathname===args.linkPath&&!url.username&&!url.password&&!url.hash)return url.href;}catch{}}
 }
-export async function waitForInbox(args,request,values,{now=Date.now,sleep=ms=>new Promise(r=>setTimeout(r,ms))}={}){
- validateInboxArgs(args);const deadline=now()+(args.timeoutMs??0);
- do{
-  const listing=await request('/emails/'+encodeURIComponent(args.emailId)+'/messages?limit=20','GET');
-  for(const item of listing.messages??listing){
-   if(!item.labels?.includes('received'))continue;const id=item.message_id??item.id;if(typeof id!=='string')continue;
-   const detail=await request('/emails/'+encodeURIComponent(args.emailId)+'/messages/'+encodeURIComponent(id),'GET');
-   const value=verificationValue(detail,args,now());if(value!==undefined)return {status:'matched',...values.put(value)};
-  }
-  if(now()>=deadline)return {status:'pending'};await sleep(Math.min(1000,deadline-now()));
- }while(now()<=deadline);
- return {status:'pending'};
+export async function waitForInbox(args,request,values){
+ validateInboxArgs(args);
+ const query={sender:args.sender,subject:args.subject,after:args.after,timeoutMs:args.timeoutMs??0};
+ const route='/emails/'+encodeURIComponent(args.emailId)+(args.codePattern?'/code':'/link');
+ if(args.codePattern)query.codePattern=args.codePattern;
+ else{query.urlHost=new URL(args.linkOrigin).hostname;query.urlPathPrefix=args.linkPath;}
+ // Server waits on push and checks authenticated sender/exact subject/scope. No
+ // message list/detail or body retrieval occurs in the local runtime.
+ const result=await request(route,'POST',query);
+ if(result.status!=='matched')return {status:'pending',...(result.reason?{reason:result.reason}:{})};
+ const value=args.codePattern?result.code:result.url;
+ if(typeof value!=='string')throw Error('Invalid verification result.');
+ if(!args.codePattern){const u=new URL(value);if(u.origin!==args.linkOrigin||u.pathname!==args.linkPath||u.username||u.password||u.hash)throw Error('Verification link outside scope.');}
+ return {status:'matched',...values.put(value)};
 }

package/client/accounts-mcp-core.mjs

@@ -54,7 +54,7 @@ export async function vaultLogin(request,scope,path){
 }
 export function createAccountsRuntime({request,codesRequest=request,scope,identityId,browserAdapter,spawnChild,runConsumer,values=new PrivateValues()}){
  const call=(route,body={})=>request('/account-tools'+route,'POST',{...body,...scope});
- const inbox=args=>waitForInbox(args,request,values);
+ const inbox=args=>waitForInbox(args,args.codePattern?codesRequest:request,values);
  const flows=new Map();
  async function saveReport(report){
   const state=flows.get(report.flowId);if(!state||state.accountRef!==report.accountRef||state.uncertain)throw Error('Flow must be reconciled before reporting.');
@@ -94,6 +94,13 @@ export function createAccountsRuntime({request,codesRequest=request,scope,identi
     const result=await codesRequest('/emails/'+encodeURIComponent(args.inboxId)+'/code','POST',{sender:args.sender,subject:args.subject,after:args.after,codePattern:args.pattern??'\\d{6}',timeoutMs:args.timeoutMs??30000});
     return result.status==='matched'?{status:'matched',code:result.code,receivedAt:result.receivedAt}:{status:'pending'};
    }
+   case 'actas_attachment_list':return request('/emails/'+encodeURIComponent(args.inboxId)+'/messages/'+encodeURIComponent(args.messageId)+'/attachments');
+   case 'actas_attachment_download':return request('/emails/'+encodeURIComponent(args.inboxId)+'/messages/'+encodeURIComponent(args.messageId)+'/attachments/'+encodeURIComponent(args.attachmentId)+'/download?encoding=base64&maxBytes=262144');
+   case 'actas_events_wait_for':return request('/resources/'+encodeURIComponent(args.resourceId)+'/events/wait','POST',{...(args.cursor===undefined?{}:{cursor:args.cursor}),timeoutMs:args.timeoutMs??30000});
+   case 'actas_webhook_create':return request('/resources/'+encodeURIComponent(args.resourceId)+'/webhooks','POST',{endpoint:args.endpoint});
+   case 'actas_webhook_list':return request('/resources/'+encodeURIComponent(args.resourceId)+'/webhooks','GET');
+   case 'actas_webhook_revoke':return request('/resources/'+encodeURIComponent(args.resourceId)+'/webhooks/'+encodeURIComponent(args.webhookId),'DELETE');
+   case 'actas_webhook_deliveries':return request('/resources/'+encodeURIComponent(args.resourceId)+'/webhooks/'+encodeURIComponent(args.webhookId)+'/deliveries','GET');
    case 'actas_passkey_register':return request('/vault/passkeys/register','POST',{...args,...scope});
    case 'actas_passkey_sign':return request('/vault/passkeys/sign','POST',{...args,...scope});
    case 'actas_vault_login':return vaultLogin(request,scope,args.path);

package/client/accounts-server.mjs

@@ -7,6 +7,13 @@ export function createAccountsMcp(runtime){
  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()}],
+  ['actas_attachment_list','List attachment metadata only, marked as outside email data. Requires emails:read. Never fetches attachment bytes or mail bodies.',{inboxId:z.string().min(1).max(160),messageId:z.string().min(1).max(160)}],
+  ['actas_attachment_download','Explicitly download one selected attachment as base64 outside data, never instructions. Requires emails:read. Maximum 256 KiB here; use API/SDK for up to 5 MiB.',{inboxId:z.string().min(1).max(160),messageId:z.string().min(1).max(160),attachmentId:z.string().regex(/^att_[a-f0-9]{64}$/)}],
+  ['actas_events_wait_for','Wait on push for new mail/SMS events. IDs and timestamps only; no bodies/codes/links. Persist cursor for reconnect.',{resourceId:z.string().min(1).max(160),cursor:z.number().int().nonnegative().optional(),timeoutMs:z.number().int().min(0).max(55000).optional()}],
+  ['actas_webhook_create','Subscribe a public HTTPS endpoint to IDs-only mail/SMS events. Returns a signing secret once. Requires read plus resources:write.',{resourceId:z.string().min(1).max(160),endpoint:z.string().url().max(2048)}],
+  ['actas_webhook_list','List your webhook metadata, never signing secrets.',{resourceId:z.string().min(1).max(160)}],
+  ['actas_webhook_revoke','Revoke your webhook and stop pending delivery.',{resourceId:z.string().min(1).max(160),webhookId:z.string().uuid()}],
+  ['actas_webhook_deliveries','Read delivery status, attempts and HTTP status only, never response bodies.',{resourceId:z.string().min(1).max(160),webhookId:z.string().uuid()}],
   ['actas_inbox_wait_for_code','Wait up to 60s for one sign-in code from an authenticated sender (emails:codes). Returns only the code.',{inboxId:z.string().min(1).max(160),sender:z.string().email().max(254),subject:z.string().min(1).max(200),after:z.string().datetime(),pattern:z.string().regex(/^(?:\\d|\[A-Z0-9\])\{(?:[4-9]|1[0-2])\}$/).optional(),timeoutMs:z.number().int().min(0).max(60000).optional()}],
   ['actas_passkey_register','Create an ES256 passkey for a granted login; private key stays encrypted in hosted ActAs. Requires read, reveal and write grants.',{path,rpId:z.string().min(3).max(253),origin:z.string().url(),challenge:z.string().max(1368),userHandle:z.string().max(86),userVerification:z.enum(['required','preferred','discouraged']).optional()}],
   ['actas_passkey_sign','Sign a WebAuthn assertion for a granted login; private key never leaves hosted ActAs. Requires read and reveal grants.',{path,rpId:z.string().min(3).max(253),origin:z.string().url(),challenge:z.string().max(1368),credentialId:z.string().max(128).optional(),allowCredentials:z.array(z.string().max(128)).max(64).optional(),userVerification:z.enum(['required','preferred','discouraged']).optional()}],

package/client/identity.mjs

@@ -21,7 +21,7 @@ async function readConnection(file){
 export async function readIdentityConnection(file=path()){return readConnection(file);}
 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(15000),...(body===undefined?{}:{body:JSON.stringify(body)})});}catch{throw Error('ActAs could not be reached. No automatic retry was made.');}
+ 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}).`);
  try{return (await response.json()).data;}catch{throw Error('Invalid ActAs response.');}
 }

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "actas",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "mcpName": "dev.actas/accounts",
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./sdk/index.d.mts",
+      "default": "./sdk/index.mjs"
+    },
+    "./client/*": "./client/*",
+    "./package.json": "./package.json"
+  },
   "description": "Persistent identity, email, saved accounts and scoped credentials for AI agents",
   "homepage": "https://actas.dev",
   "keywords": [

package/sdk/index.d.mts

@@ -0,0 +1,95 @@
+export type State = 'pending' | 'failed';
+export declare class ActAsError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly state: State;
+}
+/** Not finished yet: the code hasn't arrived, or a mailbox/domain is still pending. Safe to wait and retry. */
+export declare class ActAsPendingError extends ActAsError { readonly state: 'pending'; }
+/** Refused or broken. Don't retry blindly. */
+export declare class ActAsFailedError extends ActAsError { readonly state: 'failed'; }
+export declare class AuthError extends ActAsFailedError {}
+export declare class PermissionError extends ActAsFailedError {}
+export declare class NotFoundError extends ActAsFailedError {}
+export declare class CodePendingError extends ActAsPendingError {}
+export declare class InboxNotVerifiedError extends ActAsPendingError {}
+
+export type Connection = {
+  version?: 1;
+  kind?: 'management';
+  apiUrl: string;
+  token: string;
+  ownerId?: string;
+  identityId?: string;
+  /** Present on connections issued by identity.connect; used to route calls. */
+  scopes?: string[];
+  resourceIds?: string[];
+};
+export type Identity = {
+  id: string; name: string; ownerId: string; productId: string | null; status: string;
+  localPart: string | null; domain: string; createdAt: string; updatedAt: string;
+};
+/** status is 'verified' when create() returns; anything else throws InboxNotVerifiedError. */
+export type Inbox = { id: string; address: string; status: 'verified' | 'pending' | 'failed' };
+export type SignInMethod = 'password'|'google'|'github'|'apple';
+export type LoginItem = {
+  signInMethod?: SignInMethod; ssoAccountId?: string | null;
+  title: string; url?: string; username?: string; email?: string; password?: string;
+  /** otpauth URI or base32 seed. Stored encrypted; never returned. */
+  totp?: string; backupCodes?: string[]; notes?: string; phoneId?: string;
+};
+export type Login = {
+  path: string; signInMethod: SignInMethod; ssoAccountId: string | null;
+  username: string | null;
+  email: string | null;
+  password: string | null;
+  /** A current code only. The seed never leaves ActAs. */
+  totp: { code: string; secondsRemaining: number } | null;
+};
+export type VaultAction = 'read' | 'write' | 'reveal' | 'run' | 'totp:code';
+
+export type PasskeyOptions = {rpId:string;origin:string;challenge:string;userVerification?:'required'|'preferred'|'discouraged'};
+export type PasskeyCredential = {id:string;rawId:string;type:'public-key';response:Record<string,unknown>;clientExtensionResults:Record<string,unknown>};
+export type DeliveryResource={resourceId:string;kind?:'email'|'sms'};
+export type MessageEvent={id:string;type:'email.received'|'sms.received';resourceId:string;messageId:string;occurredAt:string};
+export declare class ActAs {
+  attachments:{
+    /** Metadata only, with outside-content markings. Requires emails:read. */
+    list(options:{inboxId:string;messageId:string}):Promise<{messageId:string;indexing:string;omitted?:number;untrusted:true;attachments:{id:string;size:number;status:string;untrusted:true;text:string}[]}>;
+    /** Explicit download only; decoded bytes are untrusted data. Default maximum 5 MiB. */
+    download(options:{inboxId:string;messageId:string;attachmentId:string;maxBytes?:number}):Promise<{attachmentId:string;untrusted:true;warning:string;encoding:'base64';data:string}>;
+  };
+  delivery:{
+    waitFor(options:DeliveryResource & {cursor?:number;timeoutMs?:number}):Promise<{status:'matched'|'pending';cursor:number;events:MessageEvent[]}>;
+    subscribe(options:DeliveryResource & {endpoint:string}):Promise<{id:string;secret:string;expiresAt:number}>;
+    list(options:DeliveryResource):Promise<unknown[]>;
+    revoke(options:DeliveryResource & {webhookId:string}):Promise<{revoked:boolean}>;
+    deliveries(options:DeliveryResource & {webhookId:string}):Promise<unknown[]>;
+  };
+  passkeys: {
+    register(path:string, options:PasskeyOptions & {userHandle:string}):Promise<PasskeyCredential>;
+    sign(path:string, options:PasskeyOptions & {credentialId?:string;allowCredentials?:string[]}):Promise<PasskeyCredential>;
+  };
+  constructor(connections: Connection | Connection[], options?: { fetch?: typeof fetch });
+  static fromFile(...files: string[]): Promise<ActAs>;
+  identity: {
+    /** Management. Creates the identity and (by default) its verified inbox. */
+    create(options: { name: string; localPart?: string; domain?: string; inbox?: boolean }): Promise<Identity & { inbox: Inbox | null }>;
+    get(id: string): Promise<Identity>;
+    /** Management. Least-privilege connections for the agent: codes for one inbox, vault reads for listed login paths. */
+    connect(identityId: string, options: { inbox?: string; logins?: string[]; name?: string }): Promise<Connection[]>;
+  };
+  inbox: {
+    /** Needs emails:codes on the inbox. Throws CodePendingError if nothing matches before timeoutMs. */
+    waitForCode(options: { inboxId: string; sender: string; subject: string; after: string | Date; pattern?: string; timeoutMs?: number }): Promise<{ code: string; receivedAt: string }>;
+  };
+  vault: {
+    /** Needs secrets:reveal plus vault grants read, reveal and totp:code on the path. */
+    login(path: string): Promise<Login>;
+    saveLogin(path: string, item: LoginItem, options?: { replace?: boolean }): Promise<{ id: string; path: string; kind: 'login' }>;
+    grant(options: { path: string; principalKind: 'client' | 'identity'; principalId: string; actions: VaultAction[]; folder?: boolean }): Promise<unknown>;
+  };
+}
+export default ActAs;
+
+export declare function verifyWebhook(secret:string,headers:Headers|Record<string,string>,rawBody:string,options?:{now?:number;toleranceMs?:number}):Promise<boolean>;

package/sdk/index.mjs

@@ -0,0 +1,153 @@
+// ActAs SDK: identity, inbox codes and vault logins for agents.
+// Every call goes to the ActAs API; the server enforces scopes and grants.
+import {readFile} from 'node:fs/promises';
+
+export class ActAsError extends Error {
+ constructor(message,{status=0,code='actas_error',state='failed'}={}){super(message);this.name=new.target.name;this.status=status;this.code=code;this.state=state;}
+}
+// state 'pending': not finished yet (code not arrived, mailbox or domain still pending). Safe to wait and retry.
+export class ActAsPendingError extends ActAsError {constructor(message,opts={}){super(message,{...opts,state:'pending'});}}
+// state 'failed': the request was refused or broke. Do not retry blindly.
+export class ActAsFailedError extends ActAsError {constructor(message,opts={}){super(message,{...opts,state:'failed'});}}
+export class AuthError extends ActAsFailedError {}
+export class PermissionError extends ActAsFailedError {}
+export class NotFoundError extends ActAsFailedError {}
+export class CodePendingError extends ActAsPendingError {}
+export class InboxNotVerifiedError extends ActAsPendingError {}
+
+const PENDING_CODES=new Set(['mail_not_ready','domain_not_ready','email_not_live']);
+function errorFor(status,code,message){
+ if(PENDING_CODES.has(code))return code==='email_not_live'?new InboxNotVerifiedError(message,{status,code}):new ActAsPendingError(message,{status,code});
+ if(status===401)return new AuthError(message,{status,code});
+ if(status===403)return new PermissionError(message,{status,code});
+ if(status===404)return new NotFoundError(message,{status,code});
+ return new ActAsFailedError(message,{status,code});
+}
+function connectionFrom(value){
+ if(!value||typeof value!=='object'||typeof value.token!=='string'||!value.token)throw new ActAsFailedError('An ActAs connection needs apiUrl and token.',{code:'invalid_connection'});
+ const url=new URL(value.apiUrl);
+ if(url.username||url.password||url.search||url.hash||url.pathname!=='/'||(url.protocol!=='https:'&&!(url.protocol==='http:'&&['localhost','127.0.0.1','[::1]'].includes(url.hostname))))throw new ActAsFailedError('ActAs connections need HTTPS (or localhost for the sandbox).',{code:'invalid_connection'});
+ return {...value,apiUrl:url.origin};
+}
+const sleep=ms=>new Promise(r=>setTimeout(r,ms));
+
+export class ActAs {
+ #connections;#scopes=new Map();#fetch;
+ /** One connection, or several (e.g. an inbox-codes connection plus a vault connection). */
+ constructor(connections,{fetch:fetchImpl=globalThis.fetch}={}){
+  this.#connections=(Array.isArray(connections)?connections:[connections]).map(connectionFrom);
+  if(!this.#connections.length)throw new ActAsFailedError('Pass at least one connection.',{code:'invalid_connection'});
+  this.#fetch=fetchImpl;
+  this.identity={create:o=>this.#createIdentity(o),get:id=>this.#request(this.#pick(),'/identities/'+encodeURIComponent(id)),connect:(id,o)=>this.#connectIdentity(id,o)};
+  this.inbox={waitForCode:o=>this.#waitForCode(o)};
+  this.attachments={list:({inboxId,messageId})=>this.#request(this.#pick('emails:read',inboxId),'/emails/'+encodeURIComponent(inboxId)+'/messages/'+encodeURIComponent(messageId)+'/attachments'),
+   download:({inboxId,messageId,attachmentId,maxBytes=5242880})=>this.#request(this.#pick('emails:read',inboxId),'/emails/'+encodeURIComponent(inboxId)+'/messages/'+encodeURIComponent(messageId)+'/attachments/'+encodeURIComponent(attachmentId)+'/download?encoding=base64&maxBytes='+encodeURIComponent(maxBytes))};
+  this.delivery={waitFor:({resourceId,cursor,timeoutMs=30000,kind='email'})=>this.#request(this.#deliveryConnection(resourceId,kind),'/resources/'+encodeURIComponent(resourceId)+'/events/wait','POST',{...(cursor===undefined?{}:{cursor}),timeoutMs},{timeoutMs:timeoutMs+15000}),
+   subscribe:({resourceId,endpoint,kind='email'})=>this.#request(this.#deliveryConnection(resourceId,kind),'/resources/'+encodeURIComponent(resourceId)+'/webhooks','POST',{endpoint}),
+   list:({resourceId,kind='email'})=>this.#request(this.#deliveryConnection(resourceId,kind),'/resources/'+encodeURIComponent(resourceId)+'/webhooks'),
+   revoke:({resourceId,webhookId,kind='email'})=>this.#request(this.#deliveryConnection(resourceId,kind),'/resources/'+encodeURIComponent(resourceId)+'/webhooks/'+encodeURIComponent(webhookId),'DELETE'),
+   deliveries:({resourceId,webhookId,kind='email'})=>this.#request(this.#deliveryConnection(resourceId,kind),'/resources/'+encodeURIComponent(resourceId)+'/webhooks/'+encodeURIComponent(webhookId)+'/deliveries')};
+  this.passkeys={register:(path,options)=>this.#passkey('register',path,options),sign:(path,options)=>this.#passkey('sign',path,options)};
+  this.vault={login:p=>this.#login(p),saveLogin:(p,item,o)=>this.#saveLogin(p,item,o),grant:o=>this.#grant(o)};
+ }
+ /** Read connection file(s) such as the ones the dashboard or sandbox writes. */
+ static async fromFile(...files){
+  const list=files.length?files:[process.env.ACTAS_CONNECTION_FILE];
+  if(list.some(f=>!f))throw new ActAsFailedError('Set ACTAS_CONNECTION_FILE or pass a connection file path.',{code:'invalid_connection'});
+  return new ActAs(await Promise.all(list.map(async f=>JSON.parse(await readFile(f,'utf8')))));
+ }
+ // Prefer the connection issued for this scope/resource; otherwise the first.
+ #pick(scope,resourceId){
+  return this.#connections.find(c=>scope&&c.scopes?.includes(scope)&&(!resourceId||c.resourceIds?.includes(resourceId)||c.resourceIds?.includes('*')))??this.#connections.find(c=>!c.scopes||!scope)??this.#connections[0];
+ }
+ async #request(connection,route,method='GET',body,{timeoutMs=15000}={}){
+  let response;
+  try{response=await this.#fetch(connection.apiUrl+'/api/v1'+route,{method,redirect:'error',headers:{Origin:connection.apiUrl,Authorization:'Bearer '+connection.token,'Content-Type':'application/json'},signal:AbortSignal.timeout(timeoutMs),...(body===undefined?{}:{body:JSON.stringify(body)})});}
+  catch{throw new ActAsFailedError('ActAs could not be reached. No automatic retry was made.',{code:'network_error'});}
+  let json;try{json=await response.json();}catch{json=null;}
+  if(!response.ok)throw errorFor(response.status,json?.error?.code??'http_'+response.status,json?.error?.message??`ActAs request failed (${response.status}).`);
+  if(!json||!('data' in json))throw new ActAsFailedError('Invalid ActAs response.',{status:response.status,code:'invalid_response'});
+  return json.data;
+ }
+ async #scope(connection){
+  if(this.#scopes.has(connection))return this.#scopes.get(connection);
+  let scope;
+  if(connection.kind==='management')scope={ownerId:connection.ownerId,productId:null};
+  else if(connection.identityId){const id=await this.#request(connection,'/identities/'+encodeURIComponent(connection.identityId));scope={ownerId:id.ownerId,productId:id.productId};}
+  else{const me=await this.#request(connection,'/me');scope={ownerId:me.owners?.[0]?.id,productId:null};}
+  this.#scopes.set(connection,scope);return scope;
+ }
+ async #createIdentity({name,localPart,domain,inbox=true}={}){
+  const c=this.#pick('identities:manage'),scope=await this.#scope(c);
+  const identity=await this.#request(c,'/identities','POST',{name,...scope,...(localPart?{localPart}:{}),...(domain?{domain}:{})});
+  if(!inbox)return {...identity,inbox:null};
+  const mailbox=await this.#request(c,'/identities/'+encodeURIComponent(identity.id)+'/email','POST',{});
+  const result={...identity,inbox:{id:mailbox.id,address:mailbox.metadata?.address,status:mailbox.status}};
+  if(mailbox.status!=='verified')throw new InboxNotVerifiedError(`Inbox ${mailbox.id} is ${mailbox.status}, not verified.`,{code:'inbox_'+mailbox.status});
+  return result;
+ }
+ // Issues the least-privilege connections an agent needs: codes for one inbox, and vault reads for listed paths.
+ async #connectIdentity(identityId,{inbox,logins=[],name='Agent'}={}){
+  const c=this.#pick('connections:manage'),scope=await this.#scope(c),out=[];
+  if(inbox){
+   const issued=await this.#request(c,'/clients','POST',{...scope,identityId,name:name+' codes',scopes:['emails:codes'],resourceIds:[inbox],identityFields:[]});
+   out.push({version:1,apiUrl:c.apiUrl,identityId,token:issued.token,scopes:['emails:codes'],resourceIds:[inbox]});
+  }
+  if(logins.length){
+   for(const path of logins)await this.#grant({path,principalKind:'identity',principalId:identityId,actions:['read','reveal','totp:code']},c);
+   const issued=await this.#request(c,'/clients','POST',{...scope,identityId,name:name+' vault',scopes:['resources:read','secrets:reveal'],resourceIds:['*'],identityFields:[]});
+   out.push({version:1,apiUrl:c.apiUrl,identityId,token:issued.token,scopes:['resources:read','secrets:reveal'],resourceIds:['*']});
+  }
+  return out;
+ }
+ #deliveryConnection(resource,kind){
+  const scopes=kind==='sms'?['phones:read','phones:codes']:['emails:read','emails:codes','emails:links'];
+  return this.#connections.find(c=>c.scopes?.some(s=>scopes.includes(s))&&(!c.resourceIds||c.resourceIds.includes('*')||c.resourceIds.includes(resource)))??this.#pick();
+ }
+ async #waitForCode({inboxId,sender,subject,after,pattern='\\d{6}',timeoutMs=60000}={}){
+  if(!inboxId||!sender||!subject||!after)throw new ActAsFailedError('waitForCode needs inboxId, sender, subject and after.',{code:'invalid_request'});
+  const c=this.#pick('emails:codes',inboxId),afterIso=after instanceof Date?after.toISOString():after,deadline=Date.now()+timeoutMs;
+  for(;;){
+   const wait=Math.max(0,Math.min(60000,deadline-Date.now()));
+   const result=await this.#request(c,'/emails/'+encodeURIComponent(inboxId)+'/code','POST',{sender,subject,after:afterIso,codePattern:pattern,timeoutMs:wait},{timeoutMs:wait+15000});
+   if(result.status==='matched')return {code:result.code,receivedAt:result.receivedAt};
+   if(Date.now()>=deadline)throw new CodePendingError(`No code from ${sender} yet.`,{code:'code_pending'});
+
+  }
+ }
+ async #passkey(operation,path,options){
+  const c=this.#pick('secrets:reveal'),scope=await this.#scope(c);
+  return this.#request(c,'/vault/passkeys/'+operation,'POST',{...options,...scope,path});
+ }
+ async #saveLogin(path,item,{replace=false}={}){
+  const c=this.#pick('resources:write'),scope=await this.#scope(c);
+  return this.#request(c,'/vault/set','POST',{...scope,path,kind:'login',value:item,replace});
+ }
+ async #grant({path,principalKind,principalId,actions,folder=false},connection=this.#pick('vault:manage')){
+  const scope=await this.#scope(connection);
+  return this.#request(connection,'/vault/grants','POST',{...scope,path,principalKind,principalId,actions,folder});
+ }
+ // Returns username/email, password and a fresh TOTP code. The TOTP seed never leaves ActAs.
+ async #login(path){
+  const c=this.#pick('secrets:reveal'),scope=await this.#scope(c);
+  const read=body=>this.#request(c,'/vault/read','POST',{...scope,path,...body});
+  const entry=await read({action:'read'});
+  if(entry.kind!=='login')throw new ActAsFailedError(`${path} is not a login item.`,{code:'not_a_login'});
+  const signInMethod=entry.login?.signInMethod??'password',ssoAccountId=entry.login?.ssoAccountId??null;
+  if(!['password','google','github','apple'].includes(signInMethod))throw new ActAsFailedError('Invalid login sign-in metadata.',{code:'invalid_login_metadata'});
+  const field=async name=>(await read({action:'reveal',field:name})).value||null;
+  const [username,email,password]=await Promise.all([field('username'),field('email'),signInMethod==='password'&&entry.login?.hasPassword?field('password'):null]);
+  const totp=entry.login?.hasTotp?await read({action:'totp:code'}):null;
+  return {path,signInMethod,ssoAccountId,username,email,password,totp:totp?{code:totp.code,secondsRemaining:totp.secondsRemaining}:null};
+ }
+}
+export default ActAs;
+
+/** Verify before parsing. Deduplicate event IDs separately after acceptance. */
+export async function verifyWebhook(secret,headers,rawBody,{now=Date.now(),toleranceMs=300000}={}){
+ const get=name=>headers instanceof Headers?headers.get(name):headers[name]??headers[name.toLowerCase()];
+ const ts=get('X-ActAs-Timestamp'),sig=get('X-ActAs-Signature');
+ if(typeof ts!=='string'||!/^\d{1,12}$/.test(ts)||Math.abs(now-Number(ts)*1000)>toleranceMs||typeof sig!=='string'||!/^v1=[0-9a-f]{64}$/.test(sig)||typeof rawBody!=='string'||typeof secret!=='string')return false;
+ const key=await crypto.subtle.importKey('raw',new TextEncoder().encode(secret),{name:'HMAC',hash:'SHA-256'},false,['verify']);
+ return crypto.subtle.verify('HMAC',key,Uint8Array.from(sig.slice(3).match(/../g),x=>parseInt(x,16)),new TextEncoder().encode(ts+'.'+rawBody));
+}