From fca9b46691a5961d89fee958dd62be4418e1196f Mon Sep 17 00:00:00 2001 From: Leiter Consulting <152733483+LeiterConsulting@users.noreply.github.com> Date: Sun, 15 Nov 2026 16:33:02 -0500 Subject: [PATCH] Add inactive fixed-source shadow run observation --- docs/release-shadow-run-admission.md | 33 +++++++++++++++ tests/shadow-run-admission.test.cjs | 16 ++++++++ .../shadow-run-admission.mjs | 40 +++++++++++++++++++ 3 files changed, 89 insertions(+) create mode 100644 docs/release-shadow-run-admission.md create mode 100644 tests/shadow-run-admission.test.cjs create mode 100644 tools/release-coordination/shadow-run-admission.mjs diff --git a/docs/release-shadow-run-admission.md b/docs/release-shadow-run-admission.md new file mode 100644 index 0000000..220970e --- /dev/null +++ b/docs/release-shadow-run-admission.md @@ -0,0 +1,33 @@ +# Inactive fixed-source run observation + +Depends on the signed identity inspector. No Worker/workflow import or new route; +no credential or activation change. inspectShadowRun verifies signed claims first, +then reads fixed GitHub REST endpoints for that exact run and attempt. Optionally +reads an explicitly selected publisher evidence artifact by canonical ID. It never +accepts a URL or forwards the OIDC token to GitHub. Trusted transport and clock +options are implementation dependencies, never request input. + +API contracts: https://docs.github.com/en/rest/actions/workflow-runs#get-a-workflow-run-attempt +and https://docs.github.com/en/rest/actions/artifacts#get-an-artifact . The attempt +endpoint was independently exercised through the authorized connector on an actual +historical publisher run, not treated as a live authenticated execution test. + +A bounded one-MiB response reader, fixed origin, manual redirect rejection and ten +second fetch signal keep acquisition constrained. Non200, unreadable data, changed +attempt/head/state or artifact mismatch fail without retries. Run IDs received as +JSON numbers must be safe integers; signed IDs remain exact decimal strings. + +The API artifact contract supplies workflow_run identity, not upload attempt. +Therefore originalBytesVerified and uploadAttemptVerified remain false. Metadata +digest is not a byte inspection. Workflow SHA claims are preserved but workflow +source bytes remain unverified. No validation run, semantic admission, exact-head +CI or deployment result is invented from the publisher run. Even complete success +returns admission held and productionActionAllowed false. + +Tests use ephemeral RSA and service fixtures; public API shape was read separately. +No current issuer token or genuine authorized running executor has qualified this +combined path. Next stages must bind independent candidate validation/export, +semantic coverage, durable intent and remote action authority. Denied workflow +activation remains denied; this module is not a substitute execution route. + +Run states are explicitly schema-checked; unknown enums and inconsistent status/conclusion pairs hold. Sequential reads are not an atomic snapshot or future-action freshness guarantee. Token validity is checked at supplied trusted acquisition time, not a promise it remains valid for later actions. diff --git a/tests/shadow-run-admission.test.cjs b/tests/shadow-run-admission.test.cjs new file mode 100644 index 0000000..c80b548 --- /dev/null +++ b/tests/shadow-run-admission.test.cjs @@ -0,0 +1,16 @@ +const {test}=require('node:test'),assert=require('node:assert/strict'),crypto=require('node:crypto'); +const repo='LeiterConsulting/splunk-version-value-explorer',now=1794777600000; +let signing; +async function fixture(changes={}){signing||=await crypto.webcrypto.subtle.generateKey({name:'RSASSA-PKCS1-v1_5',modulusLength:2048,publicExponent:new Uint8Array([1,0,1]),hash:'SHA-256'},true,['sign','verify']);const seconds=now/1000,claims={iss:'https://token.actions.githubusercontent.com',aud:'https://versioncompass.com',sub:'repo:'+repo+':ref:refs/heads/main',repository:repo,repository_id:'1366223729',repository_owner_id:'152733483',repository_visibility:'public',ref:'refs/heads/main',ref_type:'branch',workflow_ref:repo+'/.github/workflows/publish-content.yml@refs/heads/main',runner_environment:'github-hosted',event_name:'workflow_run',sha:'a'.repeat(40),workflow_sha:'b'.repeat(40),run_id:'43758558524',run_attempt:'2',iat:seconds,nbf:seconds-1,exp:seconds+300,...changes};const b64=x=>Buffer.from(JSON.stringify(x)).toString('base64url'),body=b64({alg:'RS256',typ:'JWT',kid:'fixture'})+'.'+b64(claims),sig=await crypto.webcrypto.subtle.sign('RSASSA-PKCS1-v1_5',signing.privateKey,Buffer.from(body)),jwks={keys:[{...await crypto.webcrypto.subtle.exportKey('jwk',signing.publicKey),kid:'fixture',use:'sig',alg:'RS256'}]};return {token:body+'.'+Buffer.from(sig).toString('base64url'),fetcher:async(url,options)=>{assert.equal(url,'https://token.actions.githubusercontent.com/.well-known/jwks');assert.equal(options.redirect,'manual');return Response.json(jwks)}}} + +const m=import('../tools/release-coordination/shadow-run-admission.mjs'); +function run(){return {id:43758558524,run_attempt:2,head_sha:'a'.repeat(40),head_branch:'main',path:'.github/workflows/publish-content.yml',event:'workflow_run',repository:{full_name:repo,id:1366223729,owner:{id:152733483}},status:'completed',conclusion:'success'}} +function artifact(){return {id:77,expired:false,digest:'sha256:'+'c'.repeat(64),size_in_bytes:10,workflow_run:{id:43758558524,repository_id:1366223729,head_repository_id:1366223729,head_branch:'main',head_sha:'a'.repeat(40)}}} +test('fixed GET acquisition binds run and attempt without artifact byte/attempt authority',async()=>{const f=await fixture(),calls=[],apiFetcher=async(url,opt)=>{calls.push(url);assert.equal(opt.method,'GET');assert.equal(opt.redirect,'manual');assert.equal(opt.headers.Authorization,undefined);assert(!JSON.stringify(opt).includes(f.token));return Response.json(url.includes('/artifacts/')?artifact():run())};const r=await(await m).inspectShadowRun({token:f.token,publisherEvidenceArtifactId:'77'},{issuerFetcher:f.fetcher,apiFetcher,now});assert.deepEqual(calls,['https://api.github.com/repos/'+repo+'/actions/runs/43758558524','https://api.github.com/repos/'+repo+'/actions/runs/43758558524/attempts/2','https://api.github.com/repos/'+repo+'/actions/artifacts/77']);assert(r.serviceRunIdentityObserved);assert.equal(r.artifact.uploadAttemptVerified,false);assert.equal(r.artifact.originalBytesVerified,false);assert.equal(r.productionActionAllowed,false);assert.equal(r.admission,'held')}); +test('retry drift, wrong head, repository, workflow and event reject',async()=>{const f=await fixture();for(const change of [{run_attempt:3},{head_sha:'b'.repeat(40)},{repository:{}},{path:'other'},{event:'push'}])await assert.rejects((await m).inspectShadowRun({token:f.token},{issuerFetcher:f.fetcher,now,apiFetcher:async()=>Response.json({...run(),...change})}),/identity-mismatch/)}); +test('state changes between reads hold rather than reuse earlier success',async()=>{const f=await fixture();let n=0;await assert.rejects((await m).inspectShadowRun({token:f.token},{issuerFetcher:f.fetcher,now,apiFetcher:async()=>Response.json({...run(),status:++n===1?'completed':'in_progress',conclusion:n===1?'success':null})}),/state-changed/)}); +test('HTTP denial, redirect, oversized or invalid JSON never retry',async()=>{const f=await fixture();for(const response of [()=>new Response('',{status:403}),()=>new Response('',{status:302}),()=>new Response('x'.repeat(1048577)),()=>new Response('bad')]){let calls=0;await assert.rejects((await m).inspectShadowRun({token:f.token},{issuerFetcher:f.fetcher,now,apiFetcher:async()=>{calls++;return response()}}),/evidence-/);assert.equal(calls,1)}}); +test('invalid token performs no API acquisition and request URLs cannot be injected',async()=>{let calls=0;await assert.rejects((await m).inspectShadowRun({token:'not-signed'},{now,apiFetcher:()=>{calls++;throw Error()}}));await assert.rejects((await m).inspectShadowRun({token:'not-signed',publisherEvidenceArtifactId:'../x'},{now}));assert.equal(calls,0)}); +test('artifact run association cannot become attempt or original-byte proof',async()=>{const f=await fixture();for(const change of [{expired:true},{digest:'x'},{workflow_run:{id:1}}])await assert.rejects((await m).inspectShadowRun({token:f.token,publisherEvidenceArtifactId:'77'},{issuerFetcher:f.fetcher,now,apiFetcher:async url=>Response.json(url.includes('/artifacts/')?{...artifact(),...change}:run())}),/artifact-run-mismatch/)}); + +test('missing or malformed run states fail closed',async()=>{const f=await fixture();for(const change of [{status:undefined},{conclusion:undefined},{status:{}},{status:'future-enum'},{conclusion:{}},{conclusion:null},{status:'in_progress',conclusion:'success'}])await assert.rejects((await m).inspectShadowRun({token:f.token},{issuerFetcher:f.fetcher,now,apiFetcher:async()=>Response.json({...run(),...change})}),/run-state-invalid/)}); diff --git a/tools/release-coordination/shadow-run-admission.mjs b/tools/release-coordination/shadow-run-admission.mjs new file mode 100644 index 0000000..78765c7 --- /dev/null +++ b/tools/release-coordination/shadow-run-admission.mjs @@ -0,0 +1,40 @@ +/* Inactive read-only acquisition. Never imported by active Worker/workflow. */ +import {inspectPublisherRunIdentity} from './publisher-run-identity.mjs'; +const REPO='LeiterConsulting/splunk-version-value-explorer',BASE='https://api.github.com/repos/'+REPO; +const positive=x=>typeof x==='string'&&/^[1-9][0-9]{0,19}$/.test(x); +const id=x=>Number.isSafeInteger(x)&&x>0?String(x):null; +const fail=reason=>{throw Error(reason)}; +async function get(path,fetcher){ + let response;try{response=await fetcher(BASE+path,{method:'GET',redirect:'manual',headers:{Accept:'application/vnd.github+json','X-GitHub-Api-Version':'2022-11-28'},signal:AbortSignal.timeout(10000)})}catch{fail('evidence-transport-unavailable')} + if(response.status!==200||response.redirected)fail('evidence-http-rejected'); + if(!response.body)fail('evidence-body-unavailable'); + const reader=response.body.getReader();let size=0,timer;const chunks=[];const timeout=new Promise((_,reject)=>{timer=setTimeout(()=>reject(Error('evidence-read-timeout')),10000)}); + try{for(;;){const {done,value}=await Promise.race([reader.read(),timeout]);if(done)break;size+=value.byteLength;if(size>1048576)fail('evidence-byte-limit');chunks.push(value)}}finally{clearTimeout(timer);reader.cancel().catch(()=>{})} + const bytes=new Uint8Array(size);let offset=0;for(const value of chunks){bytes.set(value,offset);offset+=value.length} + try{return JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(bytes))}catch{fail('evidence-json-invalid')} +} +function checkRun(run,identity){ + const statuses=['queued','in_progress','completed','waiting','requested','pending']; + const conclusions=['success','failure','neutral','cancelled','skipped','timed_out','action_required','stale','startup_failure']; + if(!statuses.includes(run.status)||(run.status==='completed'?!conclusions.includes(run.conclusion):run.conclusion!==null))fail('run-state-invalid'); + if(id(run.id)!==identity.runId||id(run.run_attempt)!==identity.runAttempt||run.head_sha!==identity.commit||run.event!==identity.eventName||run.head_branch!=='main'||run.path!=='.github/workflows/publish-content.yml'||run.repository?.full_name!==REPO||id(run.repository?.id)!=='1366223729'||id(run.repository?.owner?.id)!=='152733483')fail('run-identity-mismatch'); +} +// Transport overrides are trusted fixture/runtime dependencies, never caller JSON. +// No GitHub or Sites token is accepted/forwarded by this interface. OIDC is sent +// only to the local verifier; issuer and API requests never contain it. +export async function inspectShadowRun({token,publisherEvidenceArtifactId=null},{issuerFetcher=(...a)=>fetch(...a),apiFetcher=(...a)=>fetch(...a),now=Date.now()}={}){ + if(!Number.isSafeInteger(now)||now<0)fail('invalid-trusted-clock'); + if(publisherEvidenceArtifactId!==null&&!positive(publisherEvidenceArtifactId))fail('invalid-artifact-id'); + const identity=await inspectPublisherRunIdentity(token,{fetcher:issuerFetcher,now}); + const current=await get('/actions/runs/'+identity.runId,apiFetcher); + const attempt=await get('/actions/runs/'+identity.runId+'/attempts/'+identity.runAttempt,apiFetcher); + checkRun(current,identity);checkRun(attempt,identity); + if(current.status!==attempt.status||current.conclusion!==attempt.conclusion)fail('run-state-changed-readback-required'); + let artifact=null; + if(publisherEvidenceArtifactId!==null){ + const a=await get('/actions/artifacts/'+publisherEvidenceArtifactId,apiFetcher); + if(id(a.id)!==publisherEvidenceArtifactId||a.expired!==false||id(a.workflow_run?.id)!==identity.runId||a.workflow_run?.head_sha!==identity.commit||id(a.workflow_run?.repository_id)!=='1366223729'||id(a.workflow_run?.head_repository_id)!=='1366223729'||a.workflow_run?.head_branch!=='main'||typeof a.digest!=='string'||!/^sha256:[a-f0-9]{64}$/.test(a.digest)||!Number.isSafeInteger(a.size_in_bytes)||a.size_in_bytes<1)fail('artifact-run-mismatch'); + artifact={id:publisherEvidenceArtifactId,digest:a.digest,size:a.size_in_bytes,runAssociationObserved:true,originalBytesVerified:false,uploadAttemptVerified:false}; + } + return {mode:'read-only-shadow',identity,serviceRunIdentityObserved:true,status:attempt.status,conclusion:attempt.conclusion,completedSuccessfully:attempt.status==='completed'&&attempt.conclusion==='success',workflowSourceBytesVerified:false,artifact,artifactUploadAttemptVerified:false,admission:'held',productionActionAllowed:false}; +}