/** External enrollment extension sharing the original canonical claim/node MAC domains. * No production host wiring or signed extension catalog pin is provided. No * default pool, source, signing key, enrollment or native dispatch is supplied. * Genuine observations are inspected by the fixed same-reader composition. * The original node key survives aliases, credential epochs and tombstones. */ import { randomUUID } from "node:crypto" import { isDeepStrictEqual } from "node:util" import { performance } from "node:perf_hooks" import { z } from "zod" import { bandwidthRegistrySnapshotSql, parseBandwidthRegistrySnapshot, bandwidthRegistrySnapshotProofs, bandwidthRegistryEnrollmentSql, type BandwidthRegistrySnapshot } from "./bandwidth-node-registry-batch.js" import type { ProbeStorageConnection } from "./server-probe-journal-maintenance.js" import type { BandwidthScope } from "./bandwidth-admission.js" import type { BandwidthNodeProofInput } from "./bandwidth-node-source.js" import type { BandwidthPeerObservationEvidence } from "./bandwidth-peer-observation.js" const hash=z.string().regex(/^[a-f0-9]{64}$/),uuid=z.string().uuid() const authoritySchema=z.object({installationId:uuid,issuerKeySha256:hash,quiescenceProof:hash, authorityProof:hash,authorityGeneration:z.string().min(1).max(200),expiresAt:z.number().int().positive()}).strict() type Authority=z.infer export type BandwidthExternalNodeRegistryAction="register"|"resolve"|"tombstone"|"quarantine" export interface BandwidthExternalNodeRegistryDependencies { now():number /** Bounded owned lease; query results must preserve the actual PG command. * Rows alone never establish a physical BEGIN/COMMIT acknowledgement. */ connect(scope:BandwidthScope):Promise /** Fixed private provenance verifier, not a JSON/native-response parser. */ inspect(observation:unknown,scope:BandwidthScope):Promise /** Must independently authenticate original human enrollment/quiescence or * current execution/retirement authority, issuer key and installation. A SQL * row, model flag or generic read permission cannot issue this authority. */ authorize(action:BandwidthExternalNodeRegistryAction,enrollmentId:string,scope:BandwidthScope,evidence:Readonly|undefined):Promise /** Trusted constructor-only fixed path. ONE fresh provenance/authority read; * both projections must be synchronous after that read. Never request JSON. */ inspectAndAuthorize?(action:BandwidthExternalNodeRegistryAction,observation:unknown,requestedId:string|undefined,scope:BandwidthScope):Promise> /** Stable separate externally provisioned issuer key; never endpoint/epoch, * credentials, per-operation generation or an automatically generated key. */ keyedProof(purpose:string,value:unknown,scope:BandwidthScope):Promise /** Fixed optional source capability: local MACs share one freshly checked key. * No caller supplies a callback; scalar fallback retains all original guards. */ keyedProofs?(inputs:readonly BandwidthNodeProofInput[],scope:BandwidthScope):Promise } export interface BandwidthExternalNodeRegistryReceipt { readonly enrollmentId:string;readonly canonicalNodeId:string;readonly incarnation:string readonly status:"active"|"tombstoned"|"quarantined";readonly outcome:"new"|"existing" } export class BandwidthExternalNodeRegistryError extends Error { readonly code:string="BANDWIDTH_EXTERNAL_NODE_REGISTRY_REFUSED" readonly automaticReplay=false constructor(){super("Постоянная привязка bandwidth-узла не подтверждена")} } /** COMMIT may have persisted. Reconcile by fresh read under original authority; * never replay the enrollment/retirement automatically. */ export class BandwidthExternalNodeRegistryUnknown extends BandwidthExternalNodeRegistryError { override readonly code="BANDWIDTH_EXTERNAL_NODE_REGISTRY_UNKNOWN" } const refuse=():never=>{throw new BandwidthExternalNodeRegistryError()} const evidenceSchema=z.object({version:z.literal(2),peerRef:z.object({kind:z.literal("external"),enrollmentId:uuid}).strict(), sourceProof:hash,authorityGeneration:z.string().min(1).max(200),routingEndpointEpoch:uuid, observedAt:z.number().int().nonnegative(),expiresAt:z.number().int().positive(), claims:z.array(z.object({kind:z.enum(["system-id","software-id"]),value:z.string().min(1).max(256)}).strict()).min(1).max(2), physicalUniquenessVerified:z.literal(false),cloneResistanceVerified:z.literal(false)}).strict() type Evidence=z.infer type Sql={query(text:string,values?:unknown[]):Promise<{rows:Record[];command?:unknown}>} type Alias={enrollment_id:unknown;incarnation:unknown;node_id:unknown;status:unknown;record_mac:unknown} export function createBandwidthExternalNodeRegistry(dependencies:BandwidthExternalNodeRegistryDependencies){ // Capture server-owned methods once. No request accepts a source, SQL facade, // signing callback, chosen UUID or caller-asserted license evidence. const deps=Object.freeze({now:dependencies.now.bind(dependencies),connect:dependencies.connect.bind(dependencies), inspect:dependencies.inspect.bind(dependencies),authorize:dependencies.authorize.bind(dependencies),keyedProof:dependencies.keyedProof.bind(dependencies), keyedProofs:dependencies.keyedProofs?.bind(dependencies),inspectAndAuthorize:dependencies.inspectAndAuthorize?.bind(dependencies)}) const captureEvidence=(raw:unknown)=>{ const value=evidenceSchema.parse(raw) if(value.claims.some((claim,index)=>index>0&&value.claims[index-1].kind!=="system-id"||index===1&&claim.kind!=="software-id") ||value.claims.length===2&&value.claims[0].kind===value.claims[1].kind)refuse() Object.freeze(value.peerRef);value.claims.forEach(Object.freeze);Object.freeze(value.claims) return Object.freeze(value) } const inspect=async(observation:unknown,scope:BandwidthScope)=>captureEvidence(await deps.inspect(observation,scope)) const frames=new WeakSet() const combined=async(action:BandwidthExternalNodeRegistryAction,observation:unknown,requestedId:string|undefined,scope:BandwidthScope)=>{ const raw=await deps.inspectAndAuthorize!(action,observation,requestedId,scope) if(!raw||Object.getPrototypeOf(raw)!==Object.prototype||!Object.isFrozen(raw)||frames.has(raw))refuse() const fields=Object.getOwnPropertyDescriptors(raw),keys=["action","observation","scope","enrollmentId","evidence","authority"] if(Reflect.ownKeys(raw).length!==keys.length||keys.some(key=>!fields[key]||!("value"in fields[key])||!fields[key].enumerable) ||fields.action.value!==action||fields.observation.value!==observation||fields.scope.value!==scope)refuse() frames.add(raw) let budget=1000 const data=(value:unknown,depth=0):void=>{ if(--budget<0||depth>8)refuse() if(!value||typeof value!=="object")return const array=Array.isArray(value),descriptors=Object.getOwnPropertyDescriptors(value) if(Object.getPrototypeOf(value)!==(array?Array.prototype:Object.prototype))refuse() for(const key of Reflect.ownKeys(value)){ if(array&&key==="length")continue if(typeof key!=="string")return refuse() const field=descriptors[key] if(!field||!("value"in field)||!field.enumerable)return refuse() data(field.value,depth+1) } } data(fields.evidence.value);data(fields.authority.value) const evidence=fields.evidence.value===undefined?undefined:captureEvidence(fields.evidence.value) const enrollmentId=fields.enrollmentId.value if(!uuid.safeParse(enrollmentId).success||requestedId!==undefined&&enrollmentId!==requestedId ||requestedId===undefined&&!evidence||evidence&&evidence.peerRef.enrollmentId!==enrollmentId)refuse() return Object.freeze({enrollmentId:enrollmentId as string,evidence,authority:Object.freeze(authoritySchema.parse(fields.authority.value))}) } async function transaction(action:BandwidthExternalNodeRegistryAction,observation:unknown,requestedId:string|undefined,input:BandwidthScope, work:(sql:Sql,authority:Authority,evidence:Evidence|undefined,proof:(purpose:string,value:unknown)=>Promise,proofs:(inputs:readonly BandwidthNodeProofInput[])=>Promise)=>Promise):Promise{ if(!input||!Number.isSafeInteger(input.deadlineAt)||input.signal!==undefined&&!(input.signal instanceof AbortSignal))throw new BandwidthExternalNodeRegistryError() let connection:ProbeStorageConnection|undefined,commitStarted=false,transactionStarted=false,active=true,released=false,originalExpiry=Infinity const startedAt=deps.now(),monotonicStart=performance.now() const scope=Object.freeze({deadlineAt:Math.min(input.deadlineAt,startedAt+10000),signal:input.signal}) const remaining=()=>Math.min(scope.deadlineAt,originalExpiry)-startedAt-(performance.now()-monotonicStart) const release=()=>{if(connection&&!released){released=true;try{connection.release(true)}catch{/* No unsafe pool reuse. */}}} const live=()=>{if(!active||scope.signal?.aborted||remaining()<=0||deps.now()>=Math.min(scope.deadlineAt,originalExpiry))refuse()} let rejectStopped!:(error:BandwidthExternalNodeRegistryError)=>void,timer:ReturnType const stopped=new Promise((_resolve,reject)=>{rejectStopped=reject}) const stop=()=>{active=false;release();rejectStopped(commitStarted?new BandwidthExternalNodeRegistryUnknown():new BandwidthExternalNodeRegistryError())} const schedule=()=>{clearTimeout(timer);timer=setTimeout(stop,Math.max(1,Math.min(10000,remaining(),scope.deadlineAt-deps.now(),originalExpiry-deps.now())))} schedule();scope.signal?.addEventListener("abort",stop,{once:true}) const run=async()=>{ try{ live();const first=deps.inspectAndAuthorize?await combined(action,observation,requestedId,scope):undefined;live() const evidence=first?first.evidence:requestedId===undefined?await inspect(observation,scope):undefined;live() if(evidence){originalExpiry=evidence.expiresAt;schedule();live()} const enrollmentId=evidence?.peerRef.enrollmentId??requestedId! if(!uuid.safeParse(enrollmentId).success)refuse() const authority=first?first.authority:authoritySchema.parse(await deps.authorize(action,enrollmentId,scope,evidence));live() originalExpiry=Math.min(originalExpiry,authority.expiresAt);schedule();live() if(authority.expiresAt<=deps.now()||evidence&&evidence.expiresAt<=deps.now())refuse() const guard=async()=>{ live();if(deps.now()>=authority.expiresAt||evidence&&deps.now()>=evidence.expiresAt)refuse() if(deps.inspectAndAuthorize){ const current=await combined(action,observation,enrollmentId,scope);live() if(!isDeepStrictEqual(current.evidence,evidence)||!isDeepStrictEqual(current.authority,authority))refuse() return } if(evidence&&!isDeepStrictEqual(await inspect(observation,scope),evidence))refuse() // The original enrollment/execution grant is the LAST asynchronous // check before SQL/COMMIT. Native provenance may itself await source IO; // a revocation during that IO must not authorize a subsequent write. const current=authoritySchema.parse(await deps.authorize(action,enrollmentId,scope,evidence));live() if(!isDeepStrictEqual(current,authority))refuse() live() } const freeze=(value:unknown):unknown=>{if(value&&typeof value==="object"){Object.values(value).forEach(freeze);Object.freeze(value)}return value} const proof=async(purpose:string,value:unknown)=>{const snapshot=freeze(JSON.parse(JSON.stringify(value)));await guard();const result=await deps.keyedProof(purpose,snapshot,scope);await guard();if(!hash.safeParse(result).success)refuse();return result} const proofs=async(inputs:readonly BandwidthNodeProofInput[])=>{ if(!deps.keyedProofs){const values:string[]=[];for(const entry of inputs)values.push(await proof(entry.purpose,entry.value));return Object.freeze(values)} const snapshot=freeze(JSON.parse(JSON.stringify(inputs))) as readonly BandwidthNodeProofInput[] await guard() const values=await deps.keyedProofs(snapshot,scope) if(!Array.isArray(values)||Object.getPrototypeOf(values)!==Array.prototype||values.length!==snapshot.length||Reflect.ownKeys(values).length!==values.length+1)refuse() const descriptors=Object.getOwnPropertyDescriptors(values) const captured=Object.freeze(Array.from({length:values.length},(_,index)=>{ const field=descriptors[String(index)] if(!field||!("value"in field)||!field.enumerable||!hash.safeParse(field.value).success)refuse() return field.value as string })) await guard() return captured } connection=await deps.connect(scope);live() const sql:Sql={query:async(text,values)=>{await guard();const result=await connection!.query(text,values,{signal:scope.signal,timeoutMs:Math.max(1,Math.min(5000,scope.deadlineAt-deps.now()))});await guard();return result}} const started=await sql.query("BEGIN");transactionStarted=true;if(started.command!=="BEGIN")refuse() await sql.query("SELECT pg_catalog.set_config('search_path','pg_catalog',true),pg_catalog.set_config('statement_timeout','5000',true),pg_catalog.set_config('lock_timeout','2000',true),pg_catalog.set_config('synchronous_commit','on',true)") const checkAuthority=async()=>{ const rows=(await sql.query("SELECT installation_id::pg_catalog.text,issuer_key_sha256,quiescence_proof,status FROM mmapp_control.bandwidth_node_authority WHERE id=1")).rows if(rows.length!==1||rows[0].installation_id!==authority.installationId||rows[0].issuer_key_sha256!==authority.issuerKeySha256||rows[0].quiescence_proof!==authority.quiescenceProof||rows[0].status!=="active")refuse() } await checkAuthority() // All state changes, including unrelated alias enrollment, serialize on // this registry-only lock. It never releases or alters bandwidth owners. if(action!=="resolve")await sql.query("SELECT pg_catalog.pg_advisory_xact_lock(8723116)") const result=await work(sql,authority,evidence,proof,proofs) await checkAuthority();await guard();commitStarted=true;const committed=await sql.query("COMMIT");if(committed.command!=="COMMIT")refuse();transactionStarted=false;await checkAuthority();await guard() return result }catch{ if(active&&connection&&!released&&transactionStarted&&!commitStarted)try{await connection.query("ROLLBACK",undefined,{signal:scope.signal,timeoutMs:1000})}catch{/* Destroy the owned lease below. */} throw commitStarted?new BandwidthExternalNodeRegistryUnknown():new BandwidthExternalNodeRegistryError() }finally{release()} } try{return await Promise.race([run(),stopped])} finally{active=false;clearTimeout(timer!);scope.signal?.removeEventListener("abort",stop);release()} } const root=(a:Authority)=>({installationId:a.installationId,issuerKeySha256:a.issuerKeySha256,quiescenceProof:a.quiescenceProof}) const aliasMaterial=(a:Authority,row:Alias)=>({...root(a),enrollmentId:String(row.enrollment_id),incarnation:row.incarnation,nodeId:row.node_id,status:row.status}) const receipt=(row:Alias,outcome:"new"|"existing"):Readonly=>{ if(!uuid.safeParse(row.enrollment_id).success||!uuid.safeParse(row.incarnation).success||!uuid.safeParse(row.node_id).success||!["active","tombstoned","quarantined"].includes(String(row.status)))refuse() return Object.freeze({enrollmentId:String(row.enrollment_id),canonicalNodeId:String(row.node_id),incarnation:String(row.incarnation),status:row.status as BandwidthExternalNodeRegistryReceipt["status"],outcome}) } const snapshot=async(sql:Sql,enrollmentId:string,claimProof:string|null,lock:boolean)=>{ const result=await sql.query(bandwidthRegistrySnapshotSql("external",lock),[enrollmentId,claimProof]) if(result.command!=="SELECT")refuse() return parseBandwidthRegistrySnapshot(result.rows,"external",enrollmentId,claimProof) } const snapshotAlias=(value:BandwidthRegistrySnapshot):Alias=>{ const row=value.aliases[0];if(!row)refuse() return {enrollment_id:String(row.subject),incarnation:row.incarnation,node_id:row.node_id,status:row.status,record_mac:row.record_mac} } const checkedAlias=async(a:Authority,value:BandwidthRegistrySnapshot,proofs:(inputs:readonly BandwidthNodeProofInput[])=>Promise)=>{ const row=snapshotAlias(value);receipt(row,"existing") const items=bandwidthRegistrySnapshotProofs("external",value,root(a)) const signed=await proofs(items.map(({purpose,value})=>({purpose,value}))) if(items.some((item,index)=>item.expected!==signed[index]))refuse() return value.nodes[0].claim_proof } const event=async(sql:Sql,a:Authority,row:Alias,kind:"enroll"|"tombstone"|"quarantine",proof:(purpose:string,value:unknown)=>Promise)=>{ const id=randomUUID(),old=kind==="enroll"?null:"active" const mac=await proof("external-event",{...root(a),eventId:id,enrollmentId:String(row.enrollment_id),incarnation:row.incarnation,nodeId:row.node_id,kind,oldStatus:old,newStatus:row.status,authorityProof:a.authorityProof}) const result=await sql.query("INSERT INTO mmapp_control.bandwidth_external_node_events(event_id,enrollment_id,incarnation,node_id,kind,old_status,new_status,authority_proof,event_mac) VALUES($1,$2,$3,$4,$5,$6,$7,$8,$9) RETURNING event_id",[id,String(row.enrollment_id),row.incarnation,row.node_id,kind,old,row.status,a.authorityProof,mac]) if(result.rows.length!==1||result.rows[0].event_id!==id)refuse() } return Object.freeze({ register:(observation:unknown,scope:BandwidthScope)=>transaction("register",observation,undefined,scope,async(sql,a,e,proof,proofs)=>{ const claim=await proof("claim",e!.claims),value=await snapshot(sql,e!.peerRef.enrollmentId,claim,true) if(value.aliases.length){const row=snapshotAlias(value);if(row.status!=="active"||await checkedAlias(a,value,proofs)!==claim)refuse();return receipt(row,"existing")} const candidate=value.claim_nodes[0],nodeId=candidate?.node_id??randomUUID() const row:Alias={enrollment_id:e!.peerRef.enrollmentId,incarnation:randomUUID(),node_id:nodeId,status:"active",record_mac:""} const eventId=randomUUID() const [nodeMac,aliasMac,eventMac]=await proofs([ {purpose:"node",value:{...root(a),nodeId,claimProof:claim}}, {purpose:"external-alias",value:aliasMaterial(a,row)}, {purpose:"external-event",value:{...root(a),eventId,enrollmentId:e!.peerRef.enrollmentId,incarnation:row.incarnation,nodeId,kind:"enroll",oldStatus:null,newStatus:"active",authorityProof:a.authorityProof}}, ]) if(candidate&&candidate.enrollment_mac!==nodeMac)refuse() row.record_mac=aliasMac const written=await sql.query(bandwidthRegistryEnrollmentSql({kind:"external",subject:e!.peerRef.enrollmentId,insertNode:!candidate,nodeId,claimProof:claim,nodeMac,incarnation:String(row.incarnation),aliasMac:String(row.record_mac),eventId,authorityProof:a.authorityProof,eventMac})) if(written.command!=="DO")refuse() return receipt(row,"new") }), resolve:(observation:unknown,scope:BandwidthScope)=>transaction("resolve",observation,undefined,scope,async(sql,a,e,proof,proofs)=>{ const value=await snapshot(sql,e!.peerRef.enrollmentId,null,false),row=snapshotAlias(value) if(row.status!=="active"||await checkedAlias(a,value,proofs)!==await proof("claim",e!.claims))refuse() return receipt(row,"existing") }), retire:(enrollmentId:string,kind:"tombstone"|"quarantine",scope:BandwidthScope)=>{ if(kind!=="tombstone"&&kind!=="quarantine")return Promise.reject(new BandwidthExternalNodeRegistryError()) return transaction(kind,undefined,enrollmentId,scope,async(sql,a,_e,proof,proofs)=>{ const value=await snapshot(sql,enrollmentId,null,true),row=snapshotAlias(value);await checkedAlias(a,value,proofs) const next=kind==="tombstone"?"tombstoned":"quarantined" if(row.status===next)return receipt(row,"existing") if(row.status!=="active")refuse() const updated:Alias={...row,status:next};updated.record_mac=await proof("external-alias",aliasMaterial(a,updated)) const changed=await sql.query("UPDATE mmapp_control.bandwidth_external_node_aliases SET status=$2,record_mac=$3 WHERE enrollment_id=$1 AND status='active' AND record_mac=$4 RETURNING enrollment_id",[enrollmentId,next,updated.record_mac,row.record_mac]);if(changed.rows.length!==1||String(changed.rows[0].enrollment_id)!==enrollmentId)refuse() await event(sql,a,updated,kind,proof);return receipt(updated,"new") }) }, }) }