Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions docs/release-shadow-run-admission.md
Original file line number Diff line number Diff line change
@@ -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.
16 changes: 16 additions & 0 deletions tests/shadow-run-admission.test.cjs
Original file line number Diff line number Diff line change
@@ -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/)});
40 changes: 40 additions & 0 deletions tools/release-coordination/shadow-run-admission.mjs
Original file line number Diff line number Diff line change
@@ -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};
}
Loading