diff --git a/docs/release-d1-journal.md b/docs/release-d1-journal.md new file mode 100644 index 0000000..496fc9b --- /dev/null +++ b/docs/release-d1-journal.md @@ -0,0 +1,52 @@ +# Inactive D1 journal storage adapter + +This is a capability qualification slice, not a publisher or operational service. +No production schema migration, Worker route, workflow, secret, permission, or +activation is added. The module is outside the production Worker build. It statically imports the portable semantic replay validator, with differential +tests against the existing reviewed local replay. Callers cannot replace it. No flag in supplied JSON grants authentication or release authority. + +## Actual D1 API path + +The adapter uses `withSession('first-primary')` for sequential read/write readback. +It reads and hashes the bounded chain, validates transitions, then appends with a +single `INSERT ... SELECT ... WHERE` statement checking sequence and expected +tail in the database. A stale observation cannot become an unconditional write. +The schema scopes sequence and digest uniqueness by project. No lease expiry, +unlock, retry or remote publication is implemented. A thrown write call is unknown; +a zero-change conditional write is a conflict; a missing readback is unverified. + +Cloudflare documents prepared statements, transactional batch rollback and +sequentially consistent sessions at: +https://developers.cloudflare.com/d1/worker-api/d1-database/ + +The adapter only needs one statement per append, avoiding JavaScript-interleaved +transactions unsupported by a D1 binding. Successful CAS only fences cooperating +journal writers, not Sites or existing publication mutations. This is not a lock +around the live site. The reference schema is deliberately outside active +`drizzle` migrations. + +## Qualification and limitations + +Normal Node tests cover contract failures with synthetic bindings. Separately, +`qualify-d1-journal.cjs` exercises the actual D1 binding in official Miniflare, +including a concurrent single-winner append, wrong-project/stale inputs, sticky +denial, runtime restart, a real committed write followed by an injected transport +failure, tampered-chain rejection, and execution of portable replay and a journal append inside actual local +workerd. Eleven additional differential cases cover valid and invalid transitions. Synthetic binding tests are not emulator +checks; emulator checks are not remote production verification. + +Use an isolated scratch installation of pinned `miniflare@4.20260730.0`, then run: + + NODE_PATH=/absolute/path/to/scratch/node_modules node tools/release-coordination/qualify-d1-journal.cjs + +The harness creates temporary local storage and removes only its own fixture. +The production repository dependency set is unchanged. The experiment's explicit +output keeps productionD1Verified, authenticationVerified, remoteFencing and +productionActionAllowed false. It does not claim cross-region consistency testing, +power-loss guarantees or production privilege isolation. + +A deployable adapter still requires a supported isolated hosted test, authenticated +request admission, bounded schema +migration approval, and independent full live readback. Existing denied operations +must not be retried or bypassed to supply these capabilities. Current bundled +service and publication holds remain unchanged. diff --git a/tests/release-d1-journal.test.cjs b/tests/release-d1-journal.test.cjs new file mode 100644 index 0000000..6d22407 --- /dev/null +++ b/tests/release-d1-journal.test.cjs @@ -0,0 +1,11 @@ +const test=require('node:test'),assert=require('node:assert/strict'); +const {replay}=require('../scripts/lib/release-journal.cjs'); +const modulePromise=import('../tools/release-coordination/d1-journal.mjs'); +const intent={kind:'intent',operationId:'op',releaseId:'release',target:{projectId:'project',versionId:'version',sourceCommit:'a'.repeat(40),archiveSha256:'b'.repeat(64),environmentRevision:12,controls:{VC_ACTIVE_DELIVERY:'0',VC_PUBLISHER_ACTIVATION:'0',VC_PUBLISHER_OIDC:'1'}},beforeDeploymentId:'old'}; +function empty(onRun){return {withSession(mode){assert.equal(mode,'first-primary');return {prepare(){return {bind(){return {all:async()=>({success:true,results:[]}),run:onRun}}}}}}}} +test('D1 reference requires explicit session and statically binds validator',async()=>{const {readD1Journal}=await modulePromise;await assert.rejects(()=>readD1Journal({db:{},project:'project',validate:replay}),/invalid-context/);const r=await readD1Journal({db:empty(),project:'project',validate:()=>{throw Error('must not run')}});assert.equal(r.state.sequence,0)}); +test('D1 empty read preserves authority limits',async()=>{const {readD1Journal}=await modulePromise;const r=await readD1Journal({db:empty(),project:'project',validate:replay});assert.equal(r.state.sequence,0);assert.equal(r.authenticationVerified,false);assert.equal(r.productionActionAllowed,false)}); +test('D1 wrong-project intent is rejected before any write',async()=>{let wrote=false;const {appendD1Journal}=await modulePromise;await assert.rejects(()=>appendD1Journal({db:empty(async()=>{wrote=true}),project:'other',validate:replay,event:intent,expectedTail:null}),/project-target-mismatch/);assert.equal(wrote,false)}); +test('D1 network failure holds unknown, without retry',async()=>{let calls=0;const {appendD1Journal}=await modulePromise;await assert.rejects(()=>appendD1Journal({db:empty(async()=>{calls++;throw Error('network')}),project:'project',validate:replay,event:intent,expectedTail:null}),/outcome-unknown/);assert.equal(calls,1)}); +test('D1 zero-change CAS cannot claim success',async()=>{const {appendD1Journal}=await modulePromise;await assert.rejects(()=>appendD1Journal({db:empty(async()=>({success:true,meta:{changes:0}})),project:'project',validate:replay,event:intent,expectedTail:null}),/tail-moved/)}); +test('D1 reported write without matching readback stays unverified',async()=>{const {appendD1Journal}=await modulePromise;await assert.rejects(()=>appendD1Journal({db:empty(async()=>({success:true,meta:{changes:1}})),project:'project',validate:replay,event:intent,expectedTail:null}),/readback-unverified/)}); diff --git a/tests/release-portable-replay.test.cjs b/tests/release-portable-replay.test.cjs new file mode 100644 index 0000000..0f7eddd --- /dev/null +++ b/tests/release-portable-replay.test.cjs @@ -0,0 +1,13 @@ +const test=require('node:test'),assert=require('node:assert/strict'); +const {replay}=require('../scripts/lib/release-journal.cjs'); +const {hash,canonical}=require('../scripts/lib/release-receipts.cjs'); +const portable=import('../tools/release-coordination/portable-replay.mjs'); +const target={projectId:'project',versionId:'version',sourceCommit:'a'.repeat(40),archiveSha256:'b'.repeat(64),environmentRevision:12,controls:{VC_ACTIVE_DELIVERY:'0',VC_PUBLISHER_ACTIVATION:'0',VC_PUBLISHER_OIDC:'1'}}; +const intent={kind:'intent',operationId:'op-1',releaseId:'release-1',target,beforeDeploymentId:'old'}; +function records(events){let prior=null;return events.map((event,i)=>{const body={sequence:i+1,previousSha256:prior,event},record={...body,sha256:hash(canonical(body))};prior=record.sha256;return record})} +function inspection(){const body={kind:'deployment-byte-inspection',...target,deploymentId:'new'};return {...body,receiptSha256:hash(canonical(body)),transportOrigin:'caller-retained-service-response',authenticatedByThisModule:false,claimedDelivered:false}} +const result=status=>({kind:'result',operationId:'op-1',status,deploymentId:status==='reported-success'?'new':null}); +for(const [name,events] of Object.entries({empty:[],intent:[intent],denied:[intent,result('denied')],uncertain:[intent,result('uncertain')],unattributed:[intent,result('uncertain'),{kind:'readback',operationId:'op-1',inspection:inspection()}],matched:[intent,result('reported-success'),{kind:'readback',operationId:'op-1',inspection:inspection()}]}))test('portable replay parity: '+name,async()=>{const r=records(events);assert.deepEqual(await (await portable).replayPortable(r),replay(r))}); +for(const [name,events] of Object.entries({secondIntent:[intent,{...intent,operationId:'op-2'}],deniedReadback:[intent,result('denied'),{kind:'readback',operationId:'op-1',inspection:inspection()}],wrongOperation:[intent,{...result('uncertain'),operationId:'other'}],wrongControl:[intent,result('reported-success'),{kind:'readback',operationId:'op-1',inspection:{...inspection(),controls:{...target.controls,VC_ACTIVE_DELIVERY:'1'}}}]}))test('portable replay rejects same invalid transition: '+name,async()=>{const r=records(events);let message;try{replay(r)}catch(e){message=e.message}assert(message);await assert.rejects(()=>(awaitable(r)),e=>e.message===message)}); +async function awaitable(r){return (await portable).replayPortable(r)} +test('portable rejects tampered chain',async()=>{const r=records([intent]);r[0].event={...intent,releaseId:'different'};await assert.rejects(()=>awaitable(r),/chain-mismatch/)}); diff --git a/tools/release-coordination/d1-journal-reference.sql b/tools/release-coordination/d1-journal-reference.sql new file mode 100644 index 0000000..e952a85 --- /dev/null +++ b/tools/release-coordination/d1-journal-reference.sql @@ -0,0 +1,10 @@ +-- Isolated test schema only. Not an active migration or production table. +CREATE TABLE release_journal_reference ( + project_id TEXT NOT NULL, + sequence INTEGER NOT NULL CHECK(sequence > 0 AND sequence <= 500), + previous_hash TEXT, + event_hash TEXT NOT NULL, + record_json TEXT NOT NULL, + PRIMARY KEY(project_id, sequence), + UNIQUE(project_id, event_hash) +); diff --git a/tools/release-coordination/d1-journal.mjs b/tools/release-coordination/d1-journal.mjs new file mode 100644 index 0000000..bcbc1ca --- /dev/null +++ b/tools/release-coordination/d1-journal.mjs @@ -0,0 +1,48 @@ +/* Inactive D1-binding storage adapter. No route, migration, identity or authority. */ +import {replayPortable as validate} from './portable-replay.mjs'; +const MAX_EVENTS=500,MAX_BYTES=1048576,MAX_EVENT=16384; +const fail=reason=>{throw Object.assign(new Error(reason),{reason})}; +const plain=x=>x&&typeof x==='object'&&!Array.isArray(x)&&Object.getPrototypeOf(x)===Object.prototype; +function canonical(x){if(Array.isArray(x))return '['+x.map(canonical).join(',')+']';if(plain(x))return '{'+Object.keys(x).sort().map(k=>JSON.stringify(k)+':'+canonical(x[k])).join(',')+'}';return JSON.stringify(x)} +async function digest(x){return [...new Uint8Array(await crypto.subtle.digest('SHA-256',new TextEncoder().encode(canonical(x))))].map(v=>v.toString(16).padStart(2,'0')).join('')} +const bytes=x=>new TextEncoder().encode(x).byteLength; +const tag=x=>typeof x==='string'&&/^[A-Za-z0-9_-]{1,128}$/.test(x); +function context(db,project){if(!tag(project)||!db||typeof db.withSession!=='function')fail('invalid-context');return db.withSession('first-primary')} +async function read(session,project){ + const r=await session.prepare('SELECT sequence,previous_hash,event_hash,record_json FROM release_journal_reference WHERE project_id=? ORDER BY sequence LIMIT 501').bind(project).all(); + if(r.success!==true||!Array.isArray(r.results)||r.results.length>MAX_EVENTS)fail('journal-read-unverified'); + let count=0,tail=null,size=0;const records=[]; + for(const row of r.results){ + if(typeof row.record_json!=='string'||(size+=bytes(row.record_json)+1)>MAX_BYTES||bytes(row.record_json)>MAX_EVENT)fail('journal-limit'); + const record=JSON.parse(row.record_json),{sha256,...body}=record; + if(Object.keys(record).sort().join(',')!=='event,previousSha256,sequence,sha256'||record.sequence!==++count||record.previousSha256!==tail||row.sequence!==count||row.previous_hash!==tail||row.event_hash!==sha256||sha256!==await digest(body))fail('journal-chain-mismatch'); + if(record.event?.kind==='intent'&&record.event.target?.projectId!==project)fail('project-target-mismatch'); + records.push(record);tail=sha256; + } + // Statically bound portable validator; callers cannot substitute transition + // code. This still does not authenticate a service actor or grant admission. + const state=await validate(structuredClone(records)); + if(!plain(state)||state.sequence!==count||state.tail!==tail||state.productionActionAllowed!==false)fail('transition-validation-required'); + return {records,state,size}; +} +export async function readD1Journal({db,project}){const s=context(db,project);const r=await read(s,project);return {...r,storage:'d1-binding-reference',productionActionAllowed:false,authenticationVerified:false,remoteFencing:false}} +export async function appendD1Journal({db,project,event,expectedTail}){ + const session=context(db,project),prior=await read(session,project); + if(prior.state.tail!==expectedTail)fail('journal-tail-moved'); + if(event?.kind==='intent'&&event.target?.projectId!==project)fail('project-target-mismatch'); + const body={sequence:prior.records.length+1,previousSha256:expectedTail,event:structuredClone(event)}; + const record={...body,sha256:await digest(body)},encoded=JSON.stringify(record); + if(prior.records.length>=MAX_EVENTS||bytes(encoded)>MAX_EVENT||prior.size+bytes(encoded)+1>MAX_BYTES)fail('journal-limit'); + const next=await validate([...structuredClone(prior.records),structuredClone(record)]); + if(!plain(next)||next.sequence!==record.sequence||next.tail!==record.sha256||next.productionActionAllowed!==false)fail('transition-validation-required'); + // All conditional predicates and append are one SQL statement. A stale read + // cannot become an unconditional write, even with two independent sessions. + let result; + try{result=await session.prepare('INSERT INTO release_journal_reference(project_id,sequence,previous_hash,event_hash,record_json) SELECT ?,?,?,?,? WHERE ?=(SELECT COUNT(*)+1 FROM release_journal_reference WHERE project_id=?) AND ? IS (SELECT event_hash FROM release_journal_reference WHERE project_id=? ORDER BY sequence DESC LIMIT 1)').bind(project,record.sequence,expectedTail,record.sha256,encoded,record.sequence,project,expectedTail,project).run();} + catch{fail('append-outcome-unknown-readback-required')} + if(result?.success!==true||![0,1].includes(result.meta?.changes))fail('append-outcome-unknown-readback-required'); + if(result.meta.changes===0)fail('journal-tail-moved'); + let observed;try{observed=await read(session,project)}catch{fail('append-readback-unverified')} + if(observed.records[record.sequence-1]?.sha256!==record.sha256)fail('append-readback-unverified'); + return {recordSha256:record.sha256,state:next,observedState:observed.state,storage:'d1-binding-reference',authenticationVerified:false,remoteFencing:false,productionActionAllowed:false}; +} diff --git a/tools/release-coordination/portable-replay.mjs b/tools/release-coordination/portable-replay.mjs new file mode 100644 index 0000000..83ea480 --- /dev/null +++ b/tools/release-coordination/portable-replay.mjs @@ -0,0 +1,43 @@ +/* Portable counterpart of the local journal replay. No I/O or authority. */ +const hash=async value=>[...new Uint8Array(await crypto.subtle.digest('SHA-256',new TextEncoder().encode(value)))].map(v=>v.toString(16).padStart(2,'0')).join(''); +function canonical(v){if(Array.isArray(v))return '['+v.map(canonical).join(',')+']';if(v&&typeof v==='object')return '{'+Object.keys(v).sort().map(k=>JSON.stringify(k)+':'+canonical(v[k])).join(',')+'}';return JSON.stringify(v);} +const fail=m=>{throw Error(m);}; +const plain=x=>x&&typeof x==='object'&&!Array.isArray(x)&&Object.getPrototypeOf(x)===Object.prototype; +const keys=(x,want)=>{if(!plain(x)||Reflect.ownKeys(x).some(k=>typeof k!=='string'||!Object.hasOwn(Object.getOwnPropertyDescriptor(x,k),'value'))||Object.keys(x).sort().join(',')!==want.sort().join(','))fail('invalid-fields');}; +const token=x=>typeof x==='string'&&/^[A-Za-z0-9_-]{1,128}$/.test(x); +function controls(x){keys(x,['VC_ACTIVE_DELIVERY','VC_PUBLISHER_ACTIVATION','VC_PUBLISHER_OIDC']);if(Object.values(x).some(v=>!['0','1'].includes(v)))fail('invalid-controls');} +function target(x){keys(x,['projectId','versionId','sourceCommit','archiveSha256','environmentRevision','controls']);controls(x.controls);if(!token(x.projectId)||typeof x.versionId!=='string'||x.versionId.length>256||!/^[a-f0-9]{40}$/.test(x.sourceCommit)||!/^[a-f0-9]{64}$/.test(x.archiveSha256)||!Number.isSafeInteger(x.environmentRevision)||x.environmentRevision<1)fail('invalid-target');} +async function inspectEvidence(x){ + if(!plain(x)||x.kind!=='deployment-byte-inspection'||x.authenticatedByThisModule!==false||x.claimedDelivered!==false)fail('invalid-inspection'); + const {receiptSha256,transportOrigin,authenticatedByThisModule,claimedDelivered,...body}=x; + if(transportOrigin!=='caller-retained-service-response'||receiptSha256!==await hash(canonical(body)))fail('inspection-digest-mismatch'); + return x; +} +export async function replayPortable(records){ + let tail=null,pending=null,status='empty',sequence=0;const operations=new Set(); + for(const record of records){ + keys(record,['sequence','previousSha256','event','sha256']);const {sha256,...body}=record; + if(record.sequence!==++sequence||record.previousSha256!==tail||sha256!==await hash(canonical(body)))fail('journal-chain-mismatch'); + const e=record.event;if(!plain(e)||!token(e.operationId))fail('invalid-event'); + if(e.kind==='intent'){ + keys(e,['kind','operationId','releaseId','target','beforeDeploymentId']);target(e.target); + if(!token(e.releaseId)||typeof e.beforeDeploymentId!=='string'||!e.beforeDeploymentId||operations.has(e.operationId)||pending)fail('intent-blocked'); + operations.add(e.operationId);pending=structuredClone(e);pending.result=null;status='intent-recorded'; + }else if(e.kind==='result'){ + keys(e,['kind','operationId','status','deploymentId']); + if(!pending||pending.operationId!==e.operationId||pending.result||!['reported-success','uncertain','denied'].includes(e.status))fail('result-blocked'); + if(e.deploymentId!==null&&(typeof e.deploymentId!=='string'||!e.deploymentId||e.deploymentId===pending.beforeDeploymentId))fail('invalid-deployment-id'); + if(e.status==='reported-success'&&e.deploymentId===null)fail('missing-deployment-id'); + pending.result=structuredClone(e);status=e.status==='denied'?'denied-terminal':'awaiting-readback'; + }else if(e.kind==='readback'){ + keys(e,['kind','operationId','inspection']);if(!pending||pending.operationId!==e.operationId||pending.result?.status==='denied')fail('readback-blocked'); + const v=await inspectEvidence(e.inspection),t=pending.target; + if(v.projectId!==t.projectId||v.versionId!==t.versionId||v.sourceCommit!==t.sourceCommit||v.archiveSha256!==t.archiveSha256||v.environmentRevision!==t.environmentRevision||canonical(v.controls)!==canonical(t.controls))fail('readback-target-mismatch'); + if(!pending.result?.deploymentId){status='uncertain-unattributed';} + else if(v.deploymentId!==pending.result.deploymentId)fail('readback-operation-mismatch'); + else{status='matched-readback-review-required';pending=null;} + }else fail('unsupported-event'); + tail=record.sha256; + } + return {sequence,tail,status,pending,authority:'unverified',transportOrigin:'externally-retained-receipts-required',claimedDelivered:false,productionActionAllowed:false}; +} diff --git a/tools/release-coordination/qualify-d1-journal.cjs b/tools/release-coordination/qualify-d1-journal.cjs new file mode 100644 index 0000000..01d4011 --- /dev/null +++ b/tools/release-coordination/qualify-d1-journal.cjs @@ -0,0 +1,24 @@ +/* Explicit local-only emulator experiment; requires pinned Miniflare installed separately. */ +const {Miniflare}=require('miniflare'),assert=require('node:assert/strict'),fs=require('node:fs'),os=require('node:os'),path=require('node:path'),{pathToFileURL}=require('node:url'); + +const intent={kind:'intent',operationId:'op-1',releaseId:'release-1',target:{projectId:'project',versionId:'version',sourceCommit:'a'.repeat(40),archiveSha256:'b'.repeat(64),environmentRevision:12,controls:{VC_ACTIVE_DELIVERY:'0',VC_PUBLISHER_ACTIVATION:'0',VC_PUBLISHER_OIDC:'1'}},beforeDeploymentId:'old'}; +(async()=>{const dir=fs.mkdtempSync(path.join(os.tmpdir(),'vc-d1-reference-')),cwd=process.cwd();process.chdir(dir);for(const file of ['portable-replay.mjs','d1-journal.mjs'])fs.copyFileSync(path.join(__dirname,file),path.join(dir,file));const make=()=>new Miniflare({rootPath:dir,modules:true,scriptPath:path.join(dir,'local-test-entry.mjs'),script:'import {replayPortable} from "./portable-replay.mjs"; import {appendD1Journal} from "./d1-journal.mjs"; export default {async fetch(request,env){const input=await request.json();return Response.json(Array.isArray(input)?await replayPortable(input):await appendD1Journal({...input,db:env.DB}))}}',compatibilityDate:'2026-06-01',d1Databases:{DB:'local-reference'},d1Persist:dir});let mf=make();let passed=0; + try{const {appendD1Journal:append,readD1Journal:read}=await import(pathToFileURL(path.join(__dirname,'d1-journal.mjs')));let db=await mf.getD1Database('DB');await db.prepare(fs.readFileSync(path.join(__dirname,'d1-journal-reference.sql'),'utf8')).run();let ctx={db,project:'project'}; + const race=await Promise.allSettled([append({...ctx,event:intent,expectedTail:null}),append({...ctx,event:intent,expectedTail:null})]);assert.equal(race.filter(r=>r.status==='fulfilled').length,1);passed++; + const snapshot=await read(ctx);const native=await mf.dispatchFetch('http://localhost/',{method:'POST',body:JSON.stringify(snapshot.records)});assert.equal(native.status,200);assert.deepEqual(await native.json(),snapshot.state);passed++; + const workerIntent={...intent,target:{...intent.target,projectId:'worker'}};const nativeWrite=await mf.dispatchFetch('http://localhost/',{method:'POST',body:JSON.stringify({project:'worker',event:workerIntent,expectedTail:null})});assert.equal(nativeWrite.status,200);assert.equal((await nativeWrite.json()).state.status,'intent-recorded');assert.equal((await read({db,project:'worker'})).state.sequence,1);passed++; + let state=snapshot.state;assert.equal(state.sequence,1);assert.equal(state.pending.operationId,'op-1');passed++; + await assert.rejects(()=>append({...ctx,event:{...intent,target:{...intent.target,projectId:'other'}},expectedTail:state.tail}),/project-target-mismatch/);passed++; + await assert.rejects(()=>append({...ctx,event:{...intent,operationId:'op-2'},expectedTail:null}),/tail-moved/);passed++; + await append({...ctx,event:{kind:'result',operationId:'op-1',status:'denied',deploymentId:null},expectedTail:state.tail}); + state=(await read(ctx)).state;assert.equal(state.status,'denied-terminal');await assert.rejects(()=>append({...ctx,event:{...intent,operationId:'op-2'},expectedTail:state.tail}),/intent-blocked/);passed++; + await mf.dispose();mf=make();db=await mf.getD1Database('DB');ctx={...ctx,db};assert.equal((await read(ctx)).state.status,'denied-terminal');passed++; + // Simulate remote commit followed by transport response loss. The actual D1 + // statement commits first; the injected boundary throws instead of returning. + const lostDb={withSession(){const s=db.withSession('first-primary');return {prepare(sql){const p=s.prepare(sql);return {bind(...v){const b=p.bind(...v);return {all:()=>b.all(),run:async()=>{await b.run();throw Error('lost response')}}}}}}}}; + const other={...intent,target:{...intent.target,projectId:'lost'}};await assert.rejects(()=>append({db:lostDb,project:'lost',event:other,expectedTail:null}),/outcome-unknown/); + assert.equal((await read({db,project:'lost'})).state.sequence,1);await assert.rejects(()=>append({db,project:'lost',event:other,expectedTail:null}),/tail-moved/);passed++; + await db.prepare("UPDATE release_journal_reference SET event_hash='tampered' WHERE project_id='lost'").run();await assert.rejects(()=>read({db,project:'lost'}),/chain-mismatch/);passed++; + console.log(JSON.stringify({kind:'local-miniflare-adapter-qualification',passed,productionD1Verified:false,authenticationVerified:false,remoteFencing:false,productionActionAllowed:false},null,2)); + }finally{await mf.dispose();process.chdir(cwd);fs.rmSync(dir,{recursive:true,force:true})} +})().catch(e=>{console.error(e);process.exitCode=1});