relembra 1.0.0-beta.2 → 1.0.0-beta.4

package/README.md

@@ -25,7 +25,7 @@ and storage (an adapter). relembra enforces the rules:
 - **Measured.** An evaluation harness with leak, scope, retrieval and wake-coverage gates, plus
   controls that must fail. Results: [docs/eval/](docs/eval/).
 
-Version: 1.0.0-beta.2, a beta ([changelog](CHANGELOG.md),
+Version: 1.0.0-beta.4, a beta ([changelog](CHANGELOG.md),
 [releases](https://github.com/mneves75/relembra/releases)). Release procedure:
 [docs/RELEASE.md](docs/RELEASE.md).
 Design: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
@@ -226,7 +226,7 @@ On Windows, check the hash with `Get-FileHash` and copy the binary onto `PATH` a
 
 Before replacing an installed executable, retain a backup and its hash. Verify installed bytes
 against the release checksum and export metadata from a disposable store
-(`relembra: "1.0.0-beta.2"`); there is no `--version` flag. The [release procedure](docs/RELEASE.md) covers isolated checks and
+(`relembra: "1.0.0-beta.4"`); there is no `--version` flag. The [release procedure](docs/RELEASE.md) covers isolated checks and
 rollback without opening a live memory store. After verification, `relembra init` prints the
 session hook for your agent.
 

package/dist/sqlite/database.d.ts

@@ -33,9 +33,9 @@ export declare function checkBusyTimeout(busyTimeoutMs: number): number;
 /** Whether file modes say who may read a file: every platform but Windows. */
 export declare const OWNER_MODES: boolean;
 /**
- * Creates missing directories as 0700 and a missing file as 0600, then checks the files with
- * checkOwnerOnly. A symbolic link at the path is refused before anything is created, so no file
- * appears behind it.
+ * Creates POSIX directories as 0700 and files as 0600. On Windows a new store needs an absent
+ * directory, created with a private descriptor, and the empty store file is made in it under the
+ * same lock. Existing files keep their existing checks.
  */
 export declare function createOwnerOnly(path: string): void;
 /**
@@ -50,20 +50,6 @@ export declare function windowsSystem32(systemRoot: string | undefined): string;
  * store's ACL both ask.
  */
 export declare function windowsUserSid(systemRoot: string | undefined): string;
-/**
- * Windows: makes the current user the folder's owner, then replaces its ACL with full control for
- * the user, SYSTEM and the Administrators group only, inherited by everything in it. An owner may
- * always rewrite an ACL, so a folder another account made would otherwise give that account its
- * access back; `/setowner` fails, and no store is created, unless the user may take ownership.
- * `/inheritance:r` with the three `/grant:r` then drops what the folder inherited, in one change
- * that never widens access: another process may already have made the store here (two first
- * opens at once), and a step that restored the parent's grants, as `/reset` does, would let the
- * store inherit them for a moment. An explicit grant to anyone else is refused, not dropped: the
- * ACL is read back and must hold one entry per account in storeFolderAccounts, and no other.
- * Accounts are named by SID, so no account name or system language is involved. Any failure is
- * thrown: a store is never created in a folder others may read.
- */
-export declare function restrictFolderToOwner(dir: string): void;
 /**
  * The accounts a store folder grants full control: the user, SYSTEM and Administrators, each once.
  * A process running as LocalSystem is SYSTEM itself, so its folder holds two entries; counting

package/dist/sqlite/database.js

@@ -7,6 +7,8 @@ import { StoreBusyError } from "../errors.js";
 import { MIGRATIONS, migrate, SchemaTooNewError, schemaVersion } from "./migrations.js";
 export { StoreBusyError };
 import { walImage } from "./wal-image.js";
+import { chainRefusal, storeFolderChain, trustedAccounts } from "./windows-acl.js";
+import { createStoreUnderLock, readWindowsChain } from "./windows-security.js";
 /** Thrown when an existing store file, or its -wal or -shm file, grants group or others access. */
 export class StoreFileModeError extends Error {
     name = "StoreFileModeError";
@@ -56,31 +58,21 @@ export function checkBusyTimeout(busyTimeoutMs) {
 /** Whether file modes say who may read a file: every platform but Windows. */
 export const OWNER_MODES = process.platform !== "win32";
 /**
- * Creates missing directories as 0700 and a missing file as 0600, then checks the files with
- * checkOwnerOnly. A symbolic link at the path is refused before anything is created, so no file
- * appears behind it.
+ * Creates POSIX directories as 0700 and files as 0600. On Windows a new store needs an absent
+ * directory, created with a private descriptor, and the empty store file is made in it under the
+ * same lock. Existing files keep their existing checks.
  */
 export function createOwnerOnly(path) {
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    if (OWNER_MODES)
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     if (isSymbolicLink(path))
         throw new StoreFileTypeError(path);
-    // Windows ignores the modes: before a new store's first byte, its folder gets an ACL of its own,
-    // so the store and the -wal and -shm files SQLite makes beside it inherit owner-only access.
-    if (!OWNER_MODES && !existsSync(path)) {
-        restrictFolderToOwner(dirname(path));
-        // A sidecar without its store was put there by someone: it keeps its own ACL, and Windows
-        // opens a file by its full path whatever the folder grants, so SQLite would write into a file
-        // another account can read. Checked after the ACL, when no other account can add one. A
-        // sidecar beside a store that exists by now belongs to another process that created the
-        // store first (its folder got the same three grants), so it is no plant.
-        for (const sidecar of [`${path}-wal`, `${path}-shm`, `${path}-journal`]) {
-            if (hasEntry(sidecar) && !hasEntry(path)) {
-                throw new Error(`${sidecar} exists without its store; no store is created beside it`);
-            }
-        }
-    }
+    // Windows ignores the modes: the directory must be private from creation, before any file.
+    if (!OWNER_MODES && !existsSync(path))
+        createWindowsStore(path);
     try {
-        // O_EXCL never follows a link, so a link made since the check fails here with EEXIST.
+        // O_EXCL never follows a link, so a link made since the check fails here with EEXIST. On
+        // Windows the file exists by now, made under the store's lock, and this is a no-op.
         closeSync(openSync(path, "wx", 0o600));
     }
     catch (error) {
@@ -131,38 +123,41 @@ export function windowsUserSid(systemRoot) {
     return sid;
 }
 /**
- * Windows: makes the current user the folder's owner, then replaces its ACL with full control for
- * the user, SYSTEM and the Administrators group only, inherited by everything in it. An owner may
- * always rewrite an ACL, so a folder another account made would otherwise give that account its
- * access back; `/setowner` fails, and no store is created, unless the user may take ownership.
- * `/inheritance:r` with the three `/grant:r` then drops what the folder inherited, in one change
- * that never widens access: another process may already have made the store here (two first
- * opens at once), and a step that restored the parent's grants, as `/reset` does, would let the
- * store inherit them for a moment. An explicit grant to anyone else is refused, not dropped: the
- * ACL is read back and must hold one entry per account in storeFolderAccounts, and no other.
- * Accounts are named by SID, so no account name or system language is involved. Any failure is
- * thrown: a store is never created in a folder others may read.
+ * Creates an absent Windows store folder with its private descriptor supplied to mkdir, then the
+ * empty store file in it, under a mutex named for the account and folder: two processes opening
+ * a missing store at once both succeed, the second finding the first's file. Whether an existing
+ * folder is another creator's or a preexisting uninitialized one is decided under that lock, by
+ * the store file's presence: the latter is refused, since changing an ACL cannot revoke old
+ * handles. A sidecar without its store (a file another account could read, since Windows opens
+ * a file by its path whatever the folder grants) is refused there too, before the first byte.
  */
-export function restrictFolderToOwner(dir) {
-    // icacls follows a junction or symbolic link: the owner and ACL of its target would change.
-    if (lstatSync(dir).isSymbolicLink())
-        throw new Error(`${dir} is a link; no store is created in it`);
+function createWindowsStore(path) {
+    const store = win32.resolve(path);
+    const folder = win32.dirname(store);
+    if (!/^[A-Za-z]:\\/.test(store) || store.slice(2).includes(":")) {
+        throw new Error("a Windows store requires a local drive path without alternate streams");
+    }
+    if (hasEntry(folder) && lstatSync(folder).isSymbolicLink())
+        throw new Error(`${folder} is a link`);
     const systemRoot = process.env["SystemRoot"];
     const sid = windowsUserSid(systemRoot);
-    const accounts = storeFolderAccounts(sid);
-    runSystemTool(systemRoot, "icacls.exe", [dir, "/setowner", `*${sid}`]);
-    runSystemTool(systemRoot, "icacls.exe", [
-        dir,
-        "/inheritance:r",
-        ...accounts.flatMap((who) => ["/grant:r", `*${who}:(OI)(CI)F`]),
-    ]);
-    // icacls prints one `name:(flags)` entry per line; the path, on the first, holds no `:(`.
-    const entries = runSystemTool(systemRoot, "icacls.exe", [dir])
-        .split(/\r?\n/)
-        .filter((line) => line.includes(":("));
-    if (entries.length !== accounts.length) {
-        throw new Error(`${dir} grants another account access (${entries.length} entries, not ${accounts.length}); no store is created in it: remove those grants or use another folder`);
+    const executable = win32.join(windowsSystem32(systemRoot), "WindowsPowerShell", "v1.0", "powershell.exe");
+    const ancestors = storeFolderChain(folder);
+    const missing = [folder];
+    const existing = [];
+    for (const ancestor of ancestors) {
+        if (hasEntry(ancestor))
+            existing.push(ancestor);
+        else if (existing.length === 0)
+            missing.push(ancestor);
+        else
+            throw new Error("the Windows store ancestry changed during verification");
     }
+    const chain = readWindowsChain(executable, existing.reverse());
+    const refusal = chainRefusal(chain, trustedAccounts(sid));
+    if (refusal !== undefined)
+        throw new Error(`${refusal}; no store is created under it`);
+    createStoreUnderLock(executable, store, folder, missing.reverse(), chain, sid, storeFolderAccounts(sid));
 }
 /**
  * The accounts a store folder grants full control: the user, SYSTEM and Administrators, each once.

package/dist/sqlite/windows-acl.d.ts

@@ -0,0 +1,45 @@
+/** One access control entry, as the rules need it. */
+export interface Ace {
+    readonly allow: boolean;
+    /** The entry is only inherited: it gives the folder itself nothing. */
+    readonly inheritOnly: boolean;
+    /** Subfolders inherit the entry. */
+    readonly containerInherit: boolean;
+    readonly mask: number;
+    /** A SID, or an SDDL alias this module does not resolve (domain-relative ones: never trusted). */
+    readonly sid: string;
+}
+/** An existing ancestor with its owner SID and DACL read directly from the filesystem. */
+export interface ChainFolder {
+    readonly path: string;
+    readonly dacl: string;
+    readonly ownerSid: string;
+    /** The folder the store folder is made in. */
+    readonly holdsStoreFolder: boolean;
+}
+/**
+ * The accounts whose rights on the chain refuse nothing: the user, SYSTEM, Administrators,
+ * TrustedInstaller, and CREATOR OWNER, which stands for whoever makes the folder, here the user.
+ * SDDL writes the built-in Administrator account (RID 500) as `LA`; it is the user only when the
+ * user is that account.
+ */
+export declare function trustedAccounts(userSid: string): ReadonlySet<string>;
+/**
+ * The entries of an SDDL access list (`D:` and its flags, then one parenthesised entry each), or
+ * null for a null DACL, which grants everyone everything. Anything this parser does not know is
+ * thrown, never skipped: a skipped entry could be the one that grants another account access.
+ */
+export declare function parseDacl(sddl: string): Ace[] | null;
+/**
+ * The folders whose access lists decide whether the store folder's path holds: its parent up to
+ * the drive root, written as given (an 8.3 short name stays short). Never the canonical path: a
+ * folder on this path that another account may swap would go unread, and the ACL steps use this
+ * path. Every folder here is read where it lies, so no other account can rename or replace one
+ * without a right the rules see: DELETE on it, or DELETE_CHILD on the folder above.
+ */
+export declare function storeFolderChain(storeFolder: string): string[];
+/**
+ * Why another account could change the path to the store folder, or undefined when none could.
+ * R1 to R4 are the rules of docs/specs/w-nv1/spec.md; the first folder that breaks one is named.
+ */
+export declare function chainRefusal(chain: readonly ChainFolder[], trusted: ReadonlySet<string>): string | undefined;

package/dist/sqlite/windows-acl.js

@@ -0,0 +1,244 @@
+/**
+ * Current owners and access lists of the existing ancestry of a new Windows store directory.
+ * The filesystem adapter reads SIDs and SDDL directly through .NET; these conservative rules
+ * neither adopt preexisting store directories nor attest to historical ancestor handles.
+ */
+import { win32 } from "node:path";
+const EVERYONE = "S-1-1-0";
+const SYSTEM = "S-1-5-18";
+const ADMINISTRATORS = "S-1-5-32-544";
+const CREATOR_OWNER = "S-1-3-0";
+const TRUSTED_INSTALLER = "S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464";
+/** The well-known SDDL SID aliases whose SID does not depend on a domain. */
+const ALIASES = {
+    AC: "S-1-15-2-1",
+    AN: "S-1-5-7",
+    AO: "S-1-5-32-548",
+    AU: "S-1-5-11",
+    BA: ADMINISTRATORS,
+    BG: "S-1-5-32-546",
+    BO: "S-1-5-32-551",
+    BU: "S-1-5-32-545",
+    CG: "S-1-3-1",
+    CO: CREATOR_OWNER,
+    ED: "S-1-5-9",
+    IU: "S-1-5-4",
+    LS: "S-1-5-19",
+    NO: "S-1-5-32-556",
+    NS: "S-1-5-20",
+    NU: "S-1-5-2",
+    OW: "S-1-3-4",
+    PS: "S-1-5-10",
+    PU: "S-1-5-32-547",
+    RC: "S-1-5-12",
+    RD: "S-1-5-32-555",
+    RU: "S-1-5-32-554",
+    SO: "S-1-5-32-549",
+    SU: "S-1-5-6",
+    SY: SYSTEM,
+    WD: EVERYONE,
+    WR: "S-1-5-33",
+};
+/** SDDL's two-letter access rights. */
+const RIGHTS = {
+    GA: 0x10000000,
+    GX: 0x20000000,
+    GW: 0x40000000,
+    GR: 0x80000000,
+    RC: 0x20000,
+    SD: 0x10000,
+    WD: 0x40000,
+    WO: 0x80000,
+    FA: 0x1f01ff,
+    FR: 0x120089,
+    FW: 0x120116,
+    FX: 0x1200a0,
+    KA: 0xf003f,
+    KR: 0x20019,
+    KW: 0x20006,
+    KX: 0x20019,
+    CC: 0x1,
+    DC: 0x2,
+    LC: 0x4,
+    SW: 0x8,
+    RP: 0x10,
+    WP: 0x20,
+    DT: 0x40,
+    LO: 0x80,
+    CR: 0x100,
+};
+const FLAGS = new Set(["OI", "CI", "NP", "IO", "ID", "SA", "FA", "TP", "CR"]);
+const ALLOW_TYPES = new Set(["A", "XA", "OA", "ZA"]);
+const DENY_TYPES = new Set(["D", "XD", "OD"]);
+/** Entry types that may end in a condition; their allow ones count as unconditional here. */
+const CALLBACK_TYPES = new Set(["XA", "XD", "ZA"]);
+const GUID = /^[0-9a-fA-F]{8}(-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}$/;
+const WRITE_ATTRIBUTES = 0x100;
+const DELETE = 0x10000;
+const WRITE_DAC = 0x40000;
+const WRITE_OWNER = 0x80000;
+const DELETE_CHILD = 0x40;
+const ADD_SUBDIRECTORY = 0x4;
+const GENERIC_ALL = 0x10000000;
+const GENERIC_WRITE = 0x40000000;
+/** Read and execute: list, read attributes and the access list, traverse, synchronize. */
+const READ_EXECUTE = 0x1200a9 | 0x80000000 | 0x20000000;
+/**
+ * The accounts whose rights on the chain refuse nothing: the user, SYSTEM, Administrators,
+ * TrustedInstaller, and CREATOR OWNER, which stands for whoever makes the folder, here the user.
+ * SDDL writes the built-in Administrator account (RID 500) as `LA`; it is the user only when the
+ * user is that account.
+ */
+export function trustedAccounts(userSid) {
+    const trusted = new Set([userSid, SYSTEM, ADMINISTRATORS, TRUSTED_INSTALLER, CREATOR_OWNER]);
+    if (/^S-1-5-21-[0-9-]+-500$/.test(userSid))
+        trusted.add("LA");
+    return trusted;
+}
+/**
+ * The entries of an SDDL access list (`D:` and its flags, then one parenthesised entry each), or
+ * null for a null DACL, which grants everyone everything. Anything this parser does not know is
+ * thrown, never skipped: a skipped entry could be the one that grants another account access.
+ */
+export function parseDacl(sddl) {
+    const body = /^D:((?:P|AI|AR|NO_ACCESS_CONTROL)*)(.*)$/s.exec(sddl.trim());
+    if (body === null)
+        throw new Error(`not an SDDL access list: ${sddl}`);
+    const [, controlFlags = "", rest = ""] = body;
+    if (controlFlags.includes("NO_ACCESS_CONTROL"))
+        return null;
+    const aces = [];
+    let index = 0;
+    while (index < rest.length) {
+        // `icacls /save` writes the SACL, the mandatory label, on the same line: it ends the DACL.
+        if (rest.startsWith("S:", index))
+            break;
+        if (rest[index] !== "(")
+            throw new Error(`unexpected text in access list: ${rest.slice(index)}`);
+        // A conditional entry holds parentheses of its own, so the entry ends where depth returns to 0,
+        // counting none inside a quoted string, which SDDL delimits with `"` and never escapes.
+        let depth = 0;
+        let quoted = false;
+        let end = index;
+        for (; end < rest.length; end++) {
+            const char = rest[end];
+            if (char === '"')
+                quoted = !quoted;
+            else if (quoted)
+                continue;
+            else if (char === "(")
+                depth++;
+            else if (char === ")" && --depth === 0)
+                break;
+        }
+        if (depth !== 0 || quoted) {
+            throw new Error(`unclosed entry in access list: ${rest.slice(index)}`);
+        }
+        aces.push(parseAce(rest.slice(index + 1, end)));
+        index = end + 1;
+    }
+    return aces;
+}
+function parseAce(text) {
+    const fields = text.split(";");
+    const [type = "", flags = "", rights = "", objectGuid = "", inheritGuid = "", sid = ""] = fields;
+    const allow = ALLOW_TYPES.has(type);
+    if (!allow && !DENY_TYPES.has(type))
+        throw new Error(`unknown access entry type: (${text})`);
+    // Only a callback entry may carry a condition, its seventh field; its text may hold `;` and
+    // quotes of its own. Every other field is checked, so no quote can hide in one.
+    const condition = fields.slice(6).join(";");
+    const conditionOk = CALLBACK_TYPES.has(type)
+        ? fields.length === 6 || (condition.startsWith("(") && condition.endsWith(")"))
+        : fields.length === 6;
+    if (fields.length < 6 || !conditionOk)
+        throw new Error(`malformed access entry: (${text})`);
+    if (![objectGuid, inheritGuid].every((guid) => guid === "" || GUID.test(guid))) {
+        throw new Error(`malformed GUID in access entry: (${text})`);
+    }
+    const flagList = flags.match(/../g) ?? [];
+    if (flagList.join("") !== flags || flagList.some((flag) => !FLAGS.has(flag))) {
+        throw new Error(`unknown access entry flags: (${text})`);
+    }
+    if (!/^(S-1-[0-9-]+|[A-Z]{2})$/.test(sid))
+        throw new Error(`unknown SID in access entry: (${text})`);
+    return {
+        allow,
+        inheritOnly: flagList.includes("IO"),
+        containerInherit: flagList.includes("CI"),
+        mask: parseRights(rights, text),
+        sid: ALIASES[sid] ?? sid,
+    };
+}
+function parseRights(rights, text) {
+    if (/^0x[0-9a-fA-F]+$/.test(rights))
+        return Number.parseInt(rights.slice(2), 16);
+    const letters = rights.match(/../g) ?? [];
+    if (letters.length === 0 || letters.join("") !== rights) {
+        throw new Error(`unknown access rights: (${text})`);
+    }
+    let mask = 0;
+    for (const letter of letters) {
+        const right = RIGHTS[letter];
+        if (right === undefined)
+            throw new Error(`unknown access right ${letter}: (${text})`);
+        // Rights above bit 30 make a JavaScript bitwise result negative, so they are added.
+        mask = (mask | right) >>> 0;
+    }
+    return mask;
+}
+/**
+ * The folders whose access lists decide whether the store folder's path holds: its parent up to
+ * the drive root, written as given (an 8.3 short name stays short). Never the canonical path: a
+ * folder on this path that another account may swap would go unread, and the ACL steps use this
+ * path. Every folder here is read where it lies, so no other account can rename or replace one
+ * without a right the rules see: DELETE on it, or DELETE_CHILD on the folder above.
+ */
+export function storeFolderChain(storeFolder) {
+    const chain = [];
+    let folder = win32.resolve(storeFolder);
+    for (let up = win32.dirname(folder); up !== folder; up = win32.dirname(folder)) {
+        chain.push(up);
+        folder = up;
+    }
+    return chain;
+}
+/**
+ * Why another account could change the path to the store folder, or undefined when none could.
+ * R1 to R4 are the rules of docs/specs/w-nv1/spec.md; the first folder that breaks one is named.
+ */
+export function chainRefusal(chain, trusted) {
+    for (const folder of chain) {
+        if (!/^S-1-[0-9]+(?:-[0-9]+)+$/.test(folder.ownerSid) || folder.ownerSid === CREATOR_OWNER) {
+            return `${folder.path} has an unverifiable owner`;
+        }
+        if (!trusted.has(folder.ownerSid)) {
+            return `${folder.path} is owned by another account (${folder.ownerSid})`;
+        }
+        const aces = parseDacl(folder.dacl) ?? [
+            { allow: true, inheritOnly: false, containerInherit: true, mask: 0x1f01ff, sid: EVERYONE },
+        ];
+        for (const ace of aces) {
+            if (!ace.allow || trusted.has(ace.sid))
+                continue;
+            const refuse = (what) => `${folder.path} lets another account (${ace.sid}) ${what}`;
+            const own = ace.inheritOnly ? 0 : ace.mask;
+            if (own & (DELETE | WRITE_DAC | WRITE_OWNER | GENERIC_ALL)) {
+                return refuse("rename, delete or re-permission it");
+            }
+            if (own & (WRITE_ATTRIBUTES | GENERIC_WRITE)) {
+                return refuse("change its attributes or turn it into a reparse point");
+            }
+            if (own & DELETE_CHILD)
+                return refuse("rename or delete the folders in it");
+            if (!folder.holdsStoreFolder)
+                continue;
+            if (own & (ADD_SUBDIRECTORY | GENERIC_WRITE))
+                return refuse("create the store folder first");
+            if (ace.containerInherit && (ace.mask & ~READ_EXECUTE) >>> 0 !== 0) {
+                return refuse("open the new store folder before its ACL is set");
+            }
+        }
+    }
+    return undefined;
+}

package/dist/sqlite/windows-security.d.ts

@@ -0,0 +1,23 @@
+import type { ChainFolder } from "./windows-acl.js";
+/** No Get-Acl provider, compiled helper, or temporary file participates in these reads. */
+export declare function readWindowsChain(executable: string, paths: readonly string[]): ChainFolder[];
+/**
+ * The name of the mutex that serialises the creators of one store: one per account and store
+ * folder, compared as Windows compares paths, without case. A long and a short (8.3) spelling
+ * of one folder take two names, so two such creators refuse each other, never both create.
+ */
+export declare function storeLockName(ownerSid: string, folder: string): string;
+/** The mutex's own descriptor: full control (0x1f0001) for the accounts, nothing else. */
+export declare function storeLockSddl(ownerSid: string, accounts: readonly string[]): string;
+/**
+ * The store folder's descriptor: protected, so nothing is inherited into it, and auto-inherited
+ * (`AI`), so what is made in it carries its grants as inherited entries, as a folder set with
+ * icacls does. Without `AI` Windows copies the grants into new files unmarked.
+ */
+export declare function storeFolderSddl(ownerSid: string, accounts: readonly string[]): string;
+/**
+ * Creates the absent folders with protected inheritable grants before they become visible, then
+ * the empty store file in the last, all under the store's lock. Returns `exists` when another
+ * creator finished the same store under that lock meanwhile.
+ */
+export declare function createStoreUnderLock(executable: string, store: string, folder: string, paths: readonly string[], chain: readonly ChainFolder[], ownerSid: string, accounts: readonly string[]): "created" | "exists";

package/dist/sqlite/windows-security.js

@@ -0,0 +1,256 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+/**
+ * Windows PowerShell uses .NET Framework: this overload supplies the descriptor to mkdir, and a
+ * named mutex serialises the creators of one store, so two first opens both succeed.
+ */
+const PROGRAM = String.raw `
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+[void][Reflection.Assembly]::Load('System.Web.Extensions, Version=4.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35')
+$serializer = [System.Web.Script.Serialization.JavaScriptSerializer]::new()
+function Read-Folder([string] $path) {
+  $attributes = [IO.File]::GetAttributes($path)
+  if (($attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) { throw "$path is a link or reparse point" }
+  if (($attributes -band [IO.FileAttributes]::Directory) -eq 0) { throw "$path is not a directory" }
+  $sections = [Security.AccessControl.AccessControlSections]::Owner -bor [Security.AccessControl.AccessControlSections]::Access
+  $acl = [IO.Directory]::GetAccessControl($path, $sections)
+  @{
+    path = $path
+    ownerSid = $acl.GetOwner([Security.Principal.SecurityIdentifier]).Value
+    dacl = $acl.GetSecurityDescriptorSddlForm([Security.AccessControl.AccessControlSections]::Access)
+  }
+}
+function Test-Entry([string] $path) {
+  [IO.Directory]::Exists($path) -or [IO.File]::Exists($path)
+}
+# Exactly one full-control allow per account, nothing else: a folder's own entries, a file's
+# inherited ones. A folder is owned by the user, whose SID its descriptor names; a file by the
+# token's default owner, which is Administrators for an administrator, so any of the accounts.
+function Confirm-Rules($acl, [string] $what, [string[]] $owners) {
+  $rules = @($acl.GetAccessRules($true, $true, [Security.Principal.SecurityIdentifier]))
+  if ($owners -notcontains $acl.GetOwner([Security.Principal.SecurityIdentifier]).Value -or $rules.Count -ne $request.accounts.Count) {
+    throw "$what is not private"
+  }
+  $seen = @{}
+  foreach ($rule in $rules) {
+    $sid = $rule.IdentityReference.Value
+    if ($request.accounts -notcontains $sid -or $seen.ContainsKey($sid) -or
+        $rule.AccessControlType -ne 'Allow' -or
+        $rule.FileSystemRights -ne [Security.AccessControl.FileSystemRights]::FullControl) {
+      throw "$what has unexpected access rules"
+    }
+    $seen[$sid] = $true
+  }
+  $rules
+}
+# With $model, the folder must also carry the auto-inherit model (AI), under which the files made
+# in it carry its grants as inherited entries.
+function Confirm-Folder([string] $path, [bool] $model) {
+  $folder = Read-Folder $path
+  $acl = [IO.Directory]::GetAccessControl($path)
+  if (-not $acl.AreAccessRulesProtected) { throw "$path was not created private" }
+  foreach ($rule in (Confirm-Rules $acl $path @($request.ownerSid))) {
+    if ($rule.IsInherited -or
+        $rule.InheritanceFlags -ne ([Security.AccessControl.InheritanceFlags]::ContainerInherit -bor [Security.AccessControl.InheritanceFlags]::ObjectInherit) -or
+        $rule.PropagationFlags -ne [Security.AccessControl.PropagationFlags]::None) {
+      throw "$path has unexpected access rules"
+    }
+  }
+  if ($model -and -not $folder.dacl.StartsWith('D:PAI')) { throw "$path did not take the auto-inherit model" }
+}
+function Confirm-File([string] $path) {
+  $attributes = [IO.File]::GetAttributes($path)
+  if (($attributes -band ([IO.FileAttributes]::ReparsePoint -bor [IO.FileAttributes]::Directory)) -ne 0) { throw "$path is not a regular file" }
+  [void](Confirm-Rules ([IO.File]::GetAccessControl($path)) $path $request.accounts)
+}
+# The lock is ours only when its owner and every grant are: a squatted name is refused, never
+# re-permissioned.
+function Confirm-Lock($lock) {
+  $acl = $lock.GetAccessControl()
+  if ($acl.GetOwner([Security.Principal.SecurityIdentifier]).Value -ne $request.ownerSid) { throw 'the store creation lock is owned by another account' }
+  $rules = @($acl.GetAccessRules($true, $true, [Security.Principal.SecurityIdentifier]))
+  if ($rules.Count -ne $request.accounts.Count) { throw 'the store creation lock grants another account access' }
+  foreach ($rule in $rules) {
+    if ($request.accounts -notcontains $rule.IdentityReference.Value -or $rule.AccessControlType -ne 'Allow' -or
+        $rule.MutexRights -ne [System.Security.AccessControl.MutexRights]::FullControl) {
+      throw 'the store creation lock grants another account access'
+    }
+  }
+}
+try {
+  $request = $serializer.DeserializeObject([Console]::In.ReadToEnd())
+  if ($request.mode -eq 'read') {
+    $result = @(foreach ($path in $request.paths) { Read-Folder $path })
+    [Console]::Write($serializer.Serialize([object[]]$result))
+  } elseif ($request.mode -eq 'create') {
+    if ($request.lockName -notmatch '^Global\\relembra-[0-9a-f]{64}$') { throw 'invalid store creation lock name' }
+    $lockSecurity = [System.Security.AccessControl.MutexSecurity]::new()
+    $lockSecurity.SetSecurityDescriptorSddlForm($request.lockSddl)
+    $createdNew = $false
+    $lock = [System.Threading.Mutex]::new($false, $request.lockName, [ref] $createdNew, $lockSecurity)
+    $held = $false
+    try {
+      Confirm-Lock $lock
+      try { $held = $lock.WaitOne(10000) } catch [System.Threading.AbandonedMutexException] { $held = $true }
+      if (-not $held) { throw 'another process is still creating the store folder' }
+      if (Test-Entry $request.store) {
+        # Another creator finished under this lock: its folder must be exactly what this one would
+        # have made, model included. An abandoned lock never adopts an unfinished folder: the
+        # store is absent then.
+        Confirm-File $request.store
+        Confirm-Folder $request.folder $true
+        $result = 'exists'
+      } else {
+        foreach ($expected in $request.chain) {
+          $actual = Read-Folder $expected.path
+          if ($actual.ownerSid -ne $expected.ownerSid -or $actual.dacl -cne $expected.dacl) {
+            throw 'the store folder ancestry changed during verification'
+          }
+        }
+        foreach ($path in $request.paths) {
+          if (Test-Entry $path) { throw "$path already exists; a new Windows store requires a new folder" }
+        }
+        # What this run made is removed when a later step fails, so a retry finds the leaf absent;
+        # nothing that existed before is ever removed.
+        $created = @()
+        $fileCreated = $false
+        try {
+          foreach ($path in $request.paths) {
+            # A fresh descriptor per call: Persist clears what a reused one would apply again.
+            $security = [Security.AccessControl.DirectorySecurity]::new()
+            $security.SetSecurityDescriptorSddlForm($request.sddl)
+            [void][IO.Directory]::CreateDirectory($path, $security)
+            $created += $path
+            Confirm-Folder $path $false
+            # Files made in the folder carry its grants as inherited entries only under the
+            # auto-inherit model (AI). Creation may hand the kernel a descriptor without it; setting
+            # the same descriptor again goes through SetNamedSecurityInfo, which adopts the model.
+            if (-not (Read-Folder $path).dacl.StartsWith('D:PAI')) {
+              $again = [Security.AccessControl.DirectorySecurity]::new()
+              $again.SetSecurityDescriptorSddlForm($request.sddl)
+              [IO.Directory]::SetAccessControl($path, $again)
+            }
+            Confirm-Folder $path $true
+          }
+          foreach ($sidecar in $request.sidecars) {
+            if (Test-Entry $sidecar) { throw "$sidecar exists without its store; no store is created beside it" }
+          }
+          [IO.FileStream]::new($request.store, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None).Dispose()
+          $fileCreated = $true
+          Confirm-File $request.store
+        } catch {
+          $failure = $_.Exception
+          if ($fileCreated) { try { [IO.File]::Delete($request.store) } catch { } }
+          for ($i = $created.Count - 1; $i -ge 0; $i--) { try { [IO.Directory]::Delete($created[$i]) } catch { } }
+          throw $failure
+        }
+        $result = 'created'
+      }
+    } finally {
+      if ($held) { $lock.ReleaseMutex() }
+      $lock.Dispose()
+    }
+    [Console]::Write($serializer.Serialize($result))
+  } else { throw 'unknown security operation' }
+} catch {
+  [Console]::Error.WriteLine($_.Exception.Message)
+  exit 1
+}
+`;
+function run(executable, request) {
+    const child = spawnSync(executable, [
+        "-NoLogo",
+        "-NoProfile",
+        "-NonInteractive",
+        "-EncodedCommand",
+        Buffer.from(PROGRAM, "utf16le").toString("base64"),
+    ], {
+        input: JSON.stringify(request),
+        encoding: "utf8",
+        shell: false,
+        windowsHide: true,
+        timeout: 30_000,
+    });
+    if (child.error !== undefined || child.status !== 0) {
+        throw new Error(`Windows store security failed: ${child.error?.message ?? child.stderr.trim()}; no store is created`);
+    }
+    try {
+        return JSON.parse(child.stdout.replace(/^/, ""));
+    }
+    catch (cause) {
+        throw new Error("Windows store security returned invalid JSON; no store is created", { cause });
+    }
+}
+/** No Get-Acl provider, compiled helper, or temporary file participates in these reads. */
+export function readWindowsChain(executable, paths) {
+    const result = run(executable, { mode: "read", paths });
+    if (!Array.isArray(result) || result.length !== paths.length) {
+        throw new Error("Windows store security did not return the complete folder chain");
+    }
+    return result.map((value, index) => {
+        if (typeof value !== "object" ||
+            value === null ||
+            !("path" in value) ||
+            typeof value.path !== "string" ||
+            value.path !== paths[index] ||
+            !("ownerSid" in value) ||
+            typeof value.ownerSid !== "string" ||
+            !("dacl" in value) ||
+            typeof value.dacl !== "string") {
+            throw new Error("Windows store security returned an invalid folder descriptor");
+        }
+        return {
+            path: value.path,
+            ownerSid: value.ownerSid,
+            dacl: value.dacl,
+            holdsStoreFolder: index === paths.length - 1,
+        };
+    });
+}
+/**
+ * The name of the mutex that serialises the creators of one store: one per account and store
+ * folder, compared as Windows compares paths, without case. A long and a short (8.3) spelling
+ * of one folder take two names, so two such creators refuse each other, never both create.
+ */
+export function storeLockName(ownerSid, folder) {
+    const digest = createHash("sha256").update(`${ownerSid}\n${folder.toLowerCase()}`).digest("hex");
+    return `Global\\relembra-${digest}`;
+}
+/** The mutex's own descriptor: full control (0x1f0001) for the accounts, nothing else. */
+export function storeLockSddl(ownerSid, accounts) {
+    return `O:${ownerSid}D:P${accounts.map((sid) => `(A;;0x1f0001;;;${sid})`).join("")}`;
+}
+/**
+ * The store folder's descriptor: protected, so nothing is inherited into it, and auto-inherited
+ * (`AI`), so what is made in it carries its grants as inherited entries, as a folder set with
+ * icacls does. Without `AI` Windows copies the grants into new files unmarked.
+ */
+export function storeFolderSddl(ownerSid, accounts) {
+    return `O:${ownerSid}D:PAI${accounts.map((sid) => `(A;OICI;FA;;;${sid})`).join("")}`;
+}
+/**
+ * Creates the absent folders with protected inheritable grants before they become visible, then
+ * the empty store file in the last, all under the store's lock. Returns `exists` when another
+ * creator finished the same store under that lock meanwhile.
+ */
+export function createStoreUnderLock(executable, store, folder, paths, chain, ownerSid, accounts) {
+    const result = run(executable, {
+        mode: "create",
+        store,
+        folder,
+        paths,
+        sidecars: [`${store}-wal`, `${store}-shm`, `${store}-journal`],
+        chain,
+        ownerSid,
+        accounts,
+        sddl: storeFolderSddl(ownerSid, accounts),
+        lockName: storeLockName(ownerSid, folder),
+        lockSddl: storeLockSddl(ownerSid, accounts),
+    });
+    if (result !== "created" && result !== "exists") {
+        throw new Error("Windows store security did not confirm private store creation");
+    }
+    return result;
+}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** This relembra's version, as package.json gives it. An export's header carries it. */
-export declare const RELEMBRA_VERSION = "1.0.0-beta.2";
+export declare const RELEMBRA_VERSION = "1.0.0-beta.4";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** This relembra's version, as package.json gives it. An export's header carries it. */
-export const RELEMBRA_VERSION = "1.0.0-beta.2";
+export const RELEMBRA_VERSION = "1.0.0-beta.4";

package/docs/FORMAT.md

@@ -1,6 +1,6 @@
 # relembra storage format
 
-Status: event formats 1 and 2, SQLite schema version 6, Postgres schema version 3. Release 1.0.0-beta.2.
+Status: event formats 1 and 2, SQLite schema version 6, Postgres schema version 3. Release 1.0.0-beta.4.
 
 This document is the contract for what relembra stores. A reader that follows it needs no
 relembra code.
@@ -175,7 +175,7 @@ the events above, so a reader needs only this document.
 |---|---|---|
 | `export` | string | Always `relembra`. What makes the file an export. |
 | `format` | integer | The newest event format of the lines after it: `1` when none is a `promote` line, so a format 1 reader still reads the file, and `2` when one is. |
-| `relembra` | string | The relembra version that wrote the file, such as `1.0.0-beta.2`. Informational: a reader decides by `format` alone. |
+| `relembra` | string | The relembra version that wrote the file, such as `1.0.0-beta.4`. Informational: a reader decides by `format` alone. |
 | `scopes` | array of strings | The scopes exported. Every event's `scope` is one of them. |
 
 ### Events (lines 2 onward)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relembra",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "description": "A curated, scoped, bounded, durable, erasable and measured memory for AI agents.",
   "license": "MIT",
   "author": "mneves75",