Files
MikrotikManager/backend/src/services/bandwidth-external-node-registry.ts
T

255 lines
21 KiB
TypeScript

/** 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<typeof authoritySchema>
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<ProbeStorageConnection>
/** Fixed private provenance verifier, not a JSON/native-response parser. */
inspect(observation:unknown,scope:BandwidthScope):Promise<BandwidthPeerObservationEvidence>
/** 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<BandwidthPeerObservationEvidence>|undefined):Promise<Authority>
/** 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<Readonly<{
action:BandwidthExternalNodeRegistryAction;observation:unknown;scope:BandwidthScope;enrollmentId:string;evidence:BandwidthPeerObservationEvidence|undefined;authority:Authority
}>>
/** 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<string>
/** 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<readonly string[]>
}
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<typeof evidenceSchema>
type Sql={query(text:string,values?:unknown[]):Promise<{rows:Record<string,unknown>[];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<object>()
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<T>(action:BandwidthExternalNodeRegistryAction,observation:unknown,requestedId:string|undefined,input:BandwidthScope,
work:(sql:Sql,authority:Authority,evidence:Evidence|undefined,proof:(purpose:string,value:unknown)=>Promise<string>,proofs:(inputs:readonly BandwidthNodeProofInput[])=>Promise<readonly string[]>)=>Promise<T>):Promise<T>{
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<typeof setTimeout>
const stopped=new Promise<never>((_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<BandwidthExternalNodeRegistryReceipt>=>{
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<readonly string[]>)=>{
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<string>)=>{
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")
})
},
})
}