@allorc/a423-sdk 0.2.0 → 0.4.0

package/scripts/deploy-escrow.mjs

@@ -0,0 +1,24 @@
+// Dry-run by default. Explicit --broadcast deploys; --verify submits published sources to Sourcify.
+import fs from 'node:fs/promises';
+import {JsonRpcProvider,Wallet,ContractFactory,getAddress} from 'ethers';
+import escrow from '../src/escrow/index.cjs';
+const args=new Set(process.argv.slice(2));
+const chainId=Number(process.env.A423_CHAIN_ID),token=getAddress(process.env.A423_TOKEN_ADDRESS);
+if(!Number.isSafeInteger(chainId)||chainId<=0)throw Error('Explicit A423_CHAIN_ID required');
+const provider=new JsonRpcProvider(process.env.A423_RPC_URL);if(Number((await provider.getNetwork()).chainId)!==chainId)throw Error('RPC chain mismatch');
+if(await provider.getCode(token)==='0x')throw Error('Token has no code');
+if(!args.has('--broadcast')){console.log(JSON.stringify({dryRun:true,chainId,token,bytecodeBytes:(escrow.ESCROW_BYTECODE.length-2)/2}));process.exit(0);}
+if(!process.env.A423_DEPLOYER_KEY)throw Error('A423_DEPLOYER_KEY required for explicit deployment');
+const signer=new Wallet(process.env.A423_DEPLOYER_KEY,provider),factory=new ContractFactory(escrow.ESCROW_ABI,escrow.ESCROW_BYTECODE,signer);
+const contract=await factory.deploy(token);const receipt=await contract.deploymentTransaction().wait(Number(process.env.A423_CONFIRMATIONS||1));
+const address=await contract.getAddress();const result={chainId,token,address,transaction:receipt.hash,verification:'not_requested'};
+await fs.writeFile(process.env.A423_DEPLOYMENT_FILE||'a423-deployment.json',JSON.stringify(result,null,2)+'\n',{mode:0o600});
+if(args.has('--verify')){
+ const stdJsonInput=JSON.parse(await fs.readFile(new URL('../contracts/standard-input.json',import.meta.url),'utf8'));
+ const artifact=JSON.parse(await fs.readFile(new URL('../src/escrow/artifact.json',import.meta.url),'utf8'));
+ const response=await fetch(`https://sourcify.dev/server/v2/verify/${chainId}/${address}`,{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({stdJsonInput,compilerVersion:artifact.compiler.split('.Emscripten')[0],contractIdentifier:'A423Escrow.sol:A423Escrow',creationTransactionHash:receipt.hash}),redirect:'error',signal:AbortSignal.timeout(30000)});
+ const verification=await response.json();if(!response.ok)throw Error('Deployed, but source verification submission failed: '+response.status);
+ result.verification='submitted';result.verificationRequest=verification;
+ await fs.writeFile(process.env.A423_DEPLOYMENT_FILE||'a423-deployment.json',JSON.stringify(result,null,2)+'\n',{mode:0o600});
+}
+console.log(JSON.stringify(result));

package/scripts/operations-worker.mjs

@@ -0,0 +1,22 @@
+// Opt-in operational loop; application config must explicitly supply signer approvals and execution callbacks.
+import {pathToFileURL} from 'node:url';
+import {setTimeout} from 'node:timers/promises';
+import {watchEvidenceOnce,runMaintenanceOnce,enqueueRunningJobs,runExecutionOnce} from '../src/operations/index.mjs';
+if(!process.env.A423_CONFIG_MODULE)throw Error('A423_CONFIG_MODULE required');
+const {applicationOptions:app,workerOptions:worker}=await import(pathToFileURL(process.env.A423_CONFIG_MODULE).href);
+if(!worker?.actorFor)throw Error('workerOptions.actorFor must explicitly delegate maintenance actors');
+const controller=new AbortController();for(const signal of ['SIGINT','SIGTERM'])process.on(signal,()=>controller.abort());
+while(!controller.signal.aborted){
+ try{
+  await watchEvidenceOnce({store:app.store,revalidate:app.revalidate});
+  if(worker.index)await worker.index();
+  if(worker.replaceFees)await worker.replaceFees();
+  const maintenance=await runMaintenanceOnce({workflow:app.workflow,store:app.store,actorFor:worker.actorFor,allowExecute:worker.allowExecute===true});
+  for(const result of maintenance)if(result.error)console.error('A423 maintenance failed for job',result.id);
+  await enqueueRunningJobs({store:app.store,queue:app.queue});
+  if(worker.execute)await runExecutionOnce({workflow:app.workflow,queue:app.queue,execute:worker.execute,beforeExecute:worker.beforeExecute});
+  if(worker.webhooks){await worker.webhooks.project(app.store);for(let i=0;i<10;i++)if(!await worker.webhooks.deliverOne())break;}
+  if(worker.authority)await worker.authority.pruneChallenges();
+ }catch(error){console.error('A423 worker tick failed:',error.code||error.name);}
+ try{await setTimeout(5000,undefined,{signal:controller.signal});}catch{}
+}

package/src/authority/index.cjs

@@ -0,0 +1,81 @@
+'use strict';
+const {createPublicKey,sign,verify,randomBytes,createHash}=require('node:crypto');
+const encode=x=>Buffer.from(JSON.stringify(x)).toString('base64url');
+const fingerprint=key=>createHash('sha256').update(createPublicKey(key).export({type:'spki',format:'der'})).digest('hex');
+function requireValue(ok,message){if(!ok)throw Error(message);}
+function publicKey(pem){const key=createPublicKey(pem);requireValue(key.asymmetricKeyType==='ed25519','Ed25519 public key required');return key;}
+function createAuthority({issuer,audience,privateKey,kv,credentialTtlSeconds=3600,challengeTtlSeconds=120,now=()=>Date.now()}={}){
+ requireValue(issuer&&audience&&privateKey&&kv,'Authority configuration required');publicKey(createPublicKey(privateKey).export({type:'spki',format:'pem'}));
+ requireValue(Number.isInteger(credentialTtlSeconds)&&credentialTtlSeconds>0&&credentialTtlSeconds<=86400,'Credential TTL must be 1..86400 seconds');
+ requireValue(Number.isInteger(challengeTtlSeconds)&&challengeTtlSeconds>0&&challengeTtlSeconds<=600,'Challenge TTL must be 1..600 seconds');
+ const ns='authority:'+issuer+':'+audience;
+ const read=(kind,id)=>kv.get(ns+':'+kind,id),put=(kind,id,v)=>kv.put(ns+':'+kind,id,v);
+ const safe=x=>requireValue(typeof x==='string'&&/^[A-Za-z0-9:_-]{1,256}$/.test(x),'Invalid identity');
+ async function records(agentId){const agent=await read('agents',agentId);requireValue(agent&&!agent.revoked,'Unknown/revoked agent');const org=await read('organizations',agent.organization);requireValue(org&&!org.revoked,'Unknown/revoked organization');return {agent,org};}
+ const registration=({organization,agentId,publicKey: key,scopes})=>({version:'a423.enrollment.v1',issuer,audience,organization,agent_id:agentId,key_fingerprint:fingerprint(key),scopes:[...scopes].sort()});
+ return {
+  publicKey:createPublicKey(privateKey).export({type:'spki',format:'pem'}),
+  registration,
+  async isActive(agentId){try{await records(agentId);return true;}catch{return false;}},
+  /** Administrative capability: perform real-world approval outside this module before calling. */
+  async registerOrganization({id,name,publicKey:key}){safe(id);requireValue(typeof name==='string'&&name.trim()&&name.length<=256,'Organization name required');publicKey(key);requireValue(await kv.create(ns+':organizations',id,{id,name,publicKey:key,revoked:false}),'Organization already registered');},
+  async revokeOrganization(id){const org=await read('organizations',id);requireValue(org,'Unknown organization');await put('organizations',id,{...org,revoked:true});},
+  async registerAgent({organization,agentId,publicKey:key,scopes=['workflow'],organizationSignature}){
+   safe(agentId);const org=await read('organizations',organization);requireValue(org&&!org.revoked,'Organization not approved');publicKey(key);
+   requireValue(Array.isArray(scopes)&&scopes.length>0&&scopes.length<=64&&scopes.every(s=>typeof s==='string'&&/^[a-z0-9:_-]{1,128}$/.test(s)),'Invalid scopes');
+   const statement=registration({organization,agentId,publicKey:key,scopes});
+   requireValue(verify(null,Buffer.from(JSON.stringify(statement)),publicKey(org.publicKey),Buffer.from(organizationSignature,'base64url')),'Invalid organization enrollment signature');
+   requireValue(await kv.create(ns+':agents',agentId,{id:agentId,organization,publicKey:key,scopes:[...new Set(scopes)],revoked:false}),'Agent already registered');
+  },
+  async revokeAgent(agentId){const agent=await read('agents',agentId);requireValue(agent,'Unknown agent');await put('agents',agentId,{...agent,revoked:true});},
+  async challenge(agentId){const {agent}=await records(agentId);const id=randomBytes(32).toString('base64url');const statement={version:'a423.challenge.v1',issuer,audience,id,agent_id:agentId,key_fingerprint:fingerprint(agent.publicKey),expires_at:Math.floor(now()/1000)+challengeTtlSeconds};await kv.create(ns+':challenges',id,statement);return statement;},
+  async exchange({challengeId,signature}){
+   safe(challengeId);const challenge=await kv.take(ns+':challenges',challengeId);requireValue(challenge&&challenge.expires_at>Math.floor(now()/1000),'Challenge expired, consumed or unknown');const {agent}=await records(challenge.agent_id);
+   requireValue(verify(null,Buffer.from(JSON.stringify(challenge)),publicKey(agent.publicKey),Buffer.from(signature,'base64url')),'Invalid challenge signature');
+   const issued=Math.floor(now()/1000);const payload={version:'a423.credential.v1',iss:issuer,aud:audience,sub:agent.id,org:agent.organization,key_fingerprint:fingerprint(agent.publicKey),scopes:agent.scopes,iat:issued,exp:issued+credentialTtlSeconds,jti:randomBytes(24).toString('base64url')};const content=encode(payload);return {credential:content+'.'+sign(null,Buffer.from(content),privateKey).toString('base64url'),expires_at:payload.exp};
+  },
+  async verifyCredential(credential,{scope='workflow'}={}){
+   requireValue(typeof credential==='string'&&credential.length<=16000,'Invalid credential');const parts=credential.split('.');requireValue(parts.length===2,'Invalid credential encoding');
+   requireValue(verify(null,Buffer.from(parts[0]),createPublicKey(privateKey),Buffer.from(parts[1],'base64url')),'Invalid authority signature');
+   const p=JSON.parse(Buffer.from(parts[0],'base64url').toString('utf8'));const time=Math.floor(now()/1000);
+   requireValue(p.version==='a423.credential.v1'&&p.iss===issuer&&p.aud===audience&&Number.isSafeInteger(p.exp)&&Number.isSafeInteger(p.iat)&&p.iat<=time&&p.exp>time&&p.exp-p.iat<=credentialTtlSeconds,'Expired or invalid credential');
+   const {agent}=await records(p.sub);requireValue(p.org===agent.organization&&p.key_fingerprint===fingerprint(agent.publicKey)&&p.scopes.includes(scope)&&agent.scopes.includes(scope),'Credential binding/scope mismatch');return p;
+  },
+  async pruneChallenges(){let removed=0;for(const r of await kv.list(ns+':challenges'))if(r.value.expires_at<=Math.floor(now()/1000)){await kv.take(ns+':challenges',r.id);removed++;}return removed;}
+ };
+}
+function createCredentialAuthenticator({authority,scope='workflow'}={}){return async request=>{const h=request.headers.get('authorization')||'';if(!h.startsWith('Bearer '))return null;try{return (await authority.verifyCredential(h.slice(7),{scope})).sub;}catch{return null;}};}
+/** Renew using a fresh proof of possession. Never prolong a credential from a bearer token alone. */
+function createCredentialProvider({agentId,challenge,exchange,signChallenge,refreshBeforeSeconds=60,now=()=>Date.now()}={}){
+ let current=null,inflight=null;
+ return async()=>{
+  if(current&&current.expires_at-Math.floor(now()/1000)>refreshBeforeSeconds)return current.credential;
+  if(!inflight)inflight=(async()=>{const c=await challenge(agentId);const signature=await signChallenge(Buffer.from(JSON.stringify(c)));current=await exchange({challengeId:c.id,signature});return current.credential;})().finally(()=>{inflight=null;});
+  return inflight;
+ };
+}
+module.exports={createAuthority,createCredentialAuthenticator,createCredentialProvider};
+/** Public proof endpoints only. Administrative enrollment is deliberately not exposed. */
+function createAuthorityHandler({authority,basePath='/api/a423-auth',allowRequest=async()=>false}={}){
+ return async request=>{
+  const path=new URL(request.url).pathname;
+  if(request.method!=='POST'||![basePath+'/challenge',basePath+'/exchange'].includes(path))return Response.json({error:'not found'},{status:404});
+  if(await allowRequest(request)!==true)return Response.json({error:'rate limit or policy denied'},{status:429});
+  try{if(!request.body||!(request.headers.get('content-type')||'').startsWith('application/json'))throw Error('JSON required');const reader=request.body.getReader();let size=0;const chunks=[];try{while(true){const {done,value}=await reader.read();if(done)break;size+=value.byteLength;if(size>16384){await reader.cancel();throw Error('Body too large');}chunks.push(Buffer.from(value));}}finally{reader.releaseLock();}const body=JSON.parse(Buffer.concat(chunks).toString('utf8'));
+   const result=path.endsWith('/challenge')?await authority.challenge(body.agent_id):await authority.exchange(body);
+   return Response.json(result,{headers:{'cache-control':'no-store'}});
+  }catch{return Response.json({error:'invalid proof or request'},{status:400});}
+ };
+}
+module.exports.createAuthorityHandler=createAuthorityHandler;
+/** Receiver-side verification uses public trust roots and a revocation/status lookup, never the authority private key. */
+function createCredentialVerifier({issuer,audience,publicKey:trustedKey,isActive,maxTtlSeconds=86400,now=()=>Date.now()}={}){
+ const key=publicKey(trustedKey);requireValue(typeof isActive==='function','Explicit revocation/status lookup required');
+ return async(credential,{scope='workflow'}={})=>{
+  requireValue(typeof credential==='string'&&credential.length<=16000,'Invalid credential');const parts=credential.split('.');requireValue(parts.length===2&&verify(null,Buffer.from(parts[0]),key,Buffer.from(parts[1],'base64url')),'Invalid authority signature');
+  const p=JSON.parse(Buffer.from(parts[0],'base64url').toString('utf8')),time=Math.floor(now()/1000);
+  requireValue(p.version==='a423.credential.v1'&&p.iss===issuer&&p.aud===audience&&Number.isSafeInteger(p.exp)&&Number.isSafeInteger(p.iat)&&p.iat<=time&&p.exp>time&&p.exp-p.iat<=maxTtlSeconds&&Array.isArray(p.scopes)&&p.scopes.includes(scope),'Expired or invalid credential');
+  requireValue(await isActive(p)===true,'Agent/organization revoked or unavailable');return p;
+ };
+}
+module.exports.createCredentialVerifier=createCredentialVerifier;

package/src/authority/index.d.ts

@@ -0,0 +1,24 @@
+import type { KeyObject } from 'node:crypto';
+import type { KeyValueStore } from '../storage/index.js';
+export interface Challenge {version: string;issuer: string;audience: string;id: string;agent_id: string;key_fingerprint: string;expires_at: number}
+export interface Credential {credential: string;expires_at: number}
+export interface Enrollment {organization: string;agentId: string;publicKey: string;scopes: string[]}
+export interface Authority {
+ publicKey: string;
+ isActive(agentId: string): Promise<boolean>;
+ registration(input: Enrollment): object;
+ registerOrganization(input: {id: string;name: string;publicKey: string}): Promise<void>;
+ revokeOrganization(id: string): Promise<void>;
+ registerAgent(input: Enrollment & {organizationSignature: string}): Promise<void>;
+ revokeAgent(id: string): Promise<void>;
+ challenge(agentId: string): Promise<Challenge>;
+ exchange(input: {challengeId: string;signature: string}): Promise<Credential>;
+ verifyCredential(token: string, options?: {scope?: string}): Promise<{sub: string;org: string;scopes: string[];exp: number;[key: string]: unknown}>;
+ pruneChallenges(): Promise<number>;
+}
+export function createAuthority(options: {issuer: string;audience: string;privateKey: string | KeyObject;kv: KeyValueStore;credentialTtlSeconds?: number;challengeTtlSeconds?: number;now?(): number}): Authority;
+export function createCredentialAuthenticator(options: {authority: Pick<Authority,'verifyCredential'>;scope?: string}): (request: Request) => Promise<string | null>;
+export function createCredentialProvider(options: {agentId: string;challenge(id: string): Promise<Challenge>;exchange(input: {challengeId: string;signature: string}): Promise<Credential>;signChallenge(bytes: Buffer): Promise<string>;refreshBeforeSeconds?: number;now?(): number}): () => Promise<string>;
+export function createAuthorityHandler(options: {authority: Authority;basePath?: string;allowRequest?(request: Request): Promise<boolean>}): (request: Request) => Promise<Response>;
+
+export function createCredentialVerifier(options: {issuer: string;audience: string;publicKey: string;isActive(payload: any): Promise<boolean>;maxTtlSeconds?: number;now?(): number}): Authority['verifyCredential'];

package/src/authority/index.mjs

@@ -0,0 +1,2 @@
+import api from './index.cjs';
+export const { createAuthority, createCredentialAuthenticator, createCredentialProvider, createAuthorityHandler, createCredentialVerifier } = api;