@@ -51,13 +51,15 @@ type HardenedIdentity = string;
5151/**
5252 * What a stat can tell us about WHICH OBJECT is at a path.
5353 *
54- * Two fields, deliberately separated, because conflating them shipped a bug:
54+ * Three fields, deliberately separated, because conflating them shipped a bug:
5555 *
5656 * - `object` — `dev:ino`. Answers "is this the same file". Survives an ACL or
5757 * permission change, which is exactly what we need across an icacls call.
5858 * - `freshness` — `ctimeNs`. Answers "has this file's metadata moved since". It
5959 * distinguishes an unlink/recreate that ext4 gave the same inode back for, and
6060 * it MOVES when permissions change.
61+ * - `generation` — `birthtimeNs`. Distinguishes same-`dev:ino` replacement
62+ * across icacls while remaining stable when only the ACL changes.
6163 *
6264 * The first version used `dev:ino:ctimeNs` for both jobs. Since chmod bumps ctime
6365 * — probed, `{ctimeChangedByChmod: true}` — and icacls is a permission change, the
@@ -69,6 +71,8 @@ type HardenedIdentity = string;
6971interface PathObservation {
7072 readonly object : string ;
7173 readonly freshness : string ;
74+ /** Creation time is stable across ACL edits but changes on unlink/recreate. */
75+ readonly generation : string | null ;
7276}
7377
7478/**
@@ -92,25 +96,40 @@ interface PathObservation {
9296 * Darwin nor Linux CI can confirm it and no pinned-Bun Windows probe has run.
9397 * It is defensive code, not a demonstrated platform fact.
9498 */
95- type StatReader = ( path : string ) => { dev : bigint ; ino : bigint ; ctimeNs : bigint } ;
99+ type StatReader = ( path : string ) => {
100+ dev : bigint ;
101+ ino : bigint ;
102+ ctimeNs : bigint ;
103+ birthtimeNs ?: bigint ;
104+ } ;
96105
97106const defaultStatReader : StatReader = path => {
98107 const s = statSync ( path , { bigint : true } ) ;
99- return { dev : s . dev , ino : s . ino , ctimeNs : s . ctimeNs } ;
108+ return { dev : s . dev , ino : s . ino , ctimeNs : s . ctimeNs , birthtimeNs : s . birthtimeNs } ;
100109} ;
101110
102111let statReader : StatReader = defaultStatReader ;
103112
104113/** Test seam: drive dev / ino / ctime independently. */
105114export function setStatForTests ( reader : StatReader | null ) : void {
106- statReader = reader ?? defaultStatReader ;
115+ // Older tests predate the creation-generation check. Give observations that
116+ // omit it one stable, nonzero generation; race tests can vary it explicitly.
117+ statReader = reader === null
118+ ? defaultStatReader
119+ : path => ( { birthtimeNs : 1n , ...reader ( path ) } ) ;
107120}
108121
109122function observe ( targetPath : string ) : PathObservation | null {
110123 try {
111124 const s = statReader ( targetPath ) ;
112125 if ( s . ino === 0n ) return null ;
113- return { object : `${ s . dev } :${ s . ino } ` , freshness : `${ s . ctimeNs } ` } ;
126+ return {
127+ object : `${ s . dev } :${ s . ino } ` ,
128+ freshness : `${ s . ctimeNs } ` ,
129+ generation : s . birthtimeNs === undefined || s . birthtimeNs === 0n
130+ ? null
131+ : `${ s . birthtimeNs } ` ,
132+ } ;
114133 } catch {
115134 return null ;
116135 }
@@ -162,12 +181,10 @@ function memoSatisfied(cache: Map<string, HardenedIdentity>, targetPath: string)
162181 * {identityChangedDuringHarden: true, callsForOriginal: 3, totalCalls: 3,
163182 * replacementWasHardened: false}
164183 *
165- * So the OBJECT is captured before the sequence and compared after it. Only the
166- * object — `dev:ino` — because icacls changes permissions, and `ctimeNs` moves
167- * when permissions change (probed: `{ctimeChangedByChmod: true}`). Comparing the
168- * full identity across the call would have rejected every successful harden and
169- * failed closed on the first harden on Windows: the check would have been
170- * demanding that an operation not do the thing it exists to do.
184+ * So the object and its creation generation are captured before the sequence
185+ * and compared after it. `ctimeNs` cannot be used for that comparison because
186+ * icacls itself changes it. Creation time, unlike ctime, survives an ACL edit;
187+ * it closes the same-dev:ino reuse gap without rejecting successful hardening.
171188 *
172189 * The memo then stores the object plus the freshness read AFTER hardening, which
173190 * is the state a later lookup should match.
@@ -185,7 +202,12 @@ function recordHarden(
185202 before : PathObservation | null ,
186203) : boolean {
187204 const after = observe ( targetPath ) ;
188- if ( before === null || after === null || before . object !== after . object ) {
205+ if (
206+ before === null
207+ || after === null
208+ || before . object !== after . object
209+ || before . generation !== after . generation
210+ ) {
189211 // Never leave a memo behind for a file we cannot vouch for, including one
190212 // written by an earlier successful harden of a now-replaced file.
191213 cache . delete ( targetPath ) ;
0 commit comments