relembra 1.0.0-beta.2 → 1.0.0-beta.3

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.3, 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.3"`); 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.js

@@ -1,12 +1,15 @@
 import { spawnSync } from "node:child_process";
-import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync } from "node:fs";
-import { dirname, win32 } from "node:path";
+import { randomBytes } from "node:crypto";
+import { closeSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, rmSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, win32 } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { pathToFileURL } from "node:url";
 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";
 /** Thrown when an existing store file, or its -wal or -shm file, grants group or others access. */
 export class StoreFileModeError extends Error {
     name = "StoreFileModeError";
@@ -149,6 +152,7 @@ export function restrictFolderToOwner(dir) {
         throw new Error(`${dir} is a link; no store is created in it`);
     const systemRoot = process.env["SystemRoot"];
     const sid = windowsUserSid(systemRoot);
+    checkFolderChain(systemRoot, dir, sid);
     const accounts = storeFolderAccounts(sid);
     runSystemTool(systemRoot, "icacls.exe", [dir, "/setowner", `*${sid}`]);
     runSystemTool(systemRoot, "icacls.exe", [
@@ -164,6 +168,101 @@ export function restrictFolderToOwner(dir) {
         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`);
     }
 }
+/**
+ * Windows: refuses a store folder whose path another account could change (docs/specs/w-nv1/spec.md).
+ * The ACL steps work on the folder's path, so they hold only while no other account can rename,
+ * delete or re-permission a folder above it, make the store folder first, or open it before its
+ * ACL is set. Every folder from the store folder's parent up to the drive root, on the path as
+ * given (storeFolderChain), is read as SDDL with `icacls /save`, which names accounts by SID, and
+ * judged by chainRefusal. A link on the path is refused: icacls would read its target, and whoever
+ * may change the link may point it elsewhere. Owners are not read, since no stock tool prints one
+ * as a SID: an ancestor another account owns, whose access list does not name that account, is
+ * not detected.
+ */
+function checkFolderChain(systemRoot, dir, sid) {
+    const folders = storeFolderChain(dir);
+    for (const folder of folders) {
+        if (lstatSync(folder).isSymbolicLink()) {
+            throw new Error(`${folder} is a link; no store is created under it: use a path without links`);
+        }
+    }
+    if (folders.length === 0)
+        return;
+    const chain = [];
+    const scratch = privateScratch(systemRoot, sid);
+    try {
+        for (const [index, folder] of folders.entries()) {
+            chain.push({
+                path: folder,
+                dacl: savedDacl(systemRoot, folder, scratch),
+                holdsStoreFolder: index === 0,
+            });
+        }
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+    const refusal = chainRefusal(chain, trustedAccounts(sid));
+    if (refusal !== undefined) {
+        throw new Error(`${refusal}; no store is created under it: remove that grant or keep the store in a folder only you can change, such as your profile`);
+    }
+}
+/**
+ * A folder under TEMP for the `icacls /save` files the chain check trusts, with the store
+ * folder's own ACL: owned by the user, and full control for the user, SYSTEM and Administrators
+ * only, read back on stdout. Bun's mkdtemp already gives it those three entries, explicit; Node's
+ * gives it TEMP's inherited ACL until these steps. Each file gets a random name, so no account can
+ * make one first. The steps act on the folder's path after it exists, so TEMP is trusted for what
+ * they cannot see (docs/specs/w-nv1/spec.md): it must give other accounts no inherited access to
+ * folders made in it (a handle opened before these steps keeps its access, and could turn the
+ * folder into a junction), must not let them delete or rename its entries, and must not be theirs.
+ * The default, under the user's profile, meets that.
+ */
+function privateScratch(systemRoot, sid) {
+    const scratch = mkdtempSync(join(tmpdir(), "relembra-acl-"));
+    try {
+        const accounts = storeFolderAccounts(sid);
+        runSystemTool(systemRoot, "icacls.exe", [scratch, "/setowner", `*${sid}`]);
+        runSystemTool(systemRoot, "icacls.exe", [
+            scratch,
+            "/inheritance:r",
+            ...accounts.flatMap((who) => ["/grant:r", `*${who}:(OI)(CI)F`]),
+        ]);
+        const entries = runSystemTool(systemRoot, "icacls.exe", [scratch])
+            .split(/\r?\n/)
+            .filter((line) => line.includes(":("));
+        if (entries.length !== accounts.length) {
+            throw new Error(`${scratch} grants another account access (${entries.length} entries, not ${accounts.length}); no store is created: point TEMP at a folder only you can change`);
+        }
+        return scratch;
+    }
+    catch (error) {
+        rmSync(scratch, { recursive: true, force: true });
+        throw error;
+    }
+}
+/**
+ * A folder's access list as SDDL. `icacls <folder> /save <file>` writes the folder's name on one
+ * line (none for a drive root) and its access list on the next, in UTF-16 or the console's
+ * encoding; parseDacl drops the SACL that follows it on that line.
+ */
+function savedDacl(systemRoot, folder, scratch) {
+    // A fresh random name for each save, so no account can make the file first.
+    const file = join(scratch, randomBytes(16).toString("hex"));
+    runSystemTool(systemRoot, "icacls.exe", [folder, "/save", file]);
+    const bytes = readFileSync(file);
+    const utf16 = (bytes[0] === 0xff && bytes[1] === 0xfe) || bytes[1] === 0;
+    const lines = (utf16 ? bytes.toString("utf16le") : bytes.toString("utf8"))
+        .replace(/^\uFEFF/, "")
+        .split(/\r?\n/)
+        .filter((line) => line.trim() !== "");
+    // A drive root has no name, so its file holds the access list alone.
+    const dacl = lines.at(-1);
+    if (lines.length > 2 || dacl === undefined || !dacl.startsWith("D:")) {
+        throw new Error(`icacls /save did not write one access list for ${folder}: ${lines.join(" | ")}`);
+    }
+    return dacl.trim();
+}
 /**
  * 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/windows-acl.d.ts

@@ -0,0 +1,44 @@
+/** 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;
+}
+/** A folder on the path to the store folder, with its access list as `icacls /save` writes it. */
+export interface ChainFolder {
+    readonly path: string;
+    readonly dacl: 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,236 @@
+/**
+ * Whether another account could change the folders that hold a Windows store folder, read from
+ * their access lists as SDDL (docs/specs/w-nv1/spec.md). relembra secures a new store's folder by
+ * its path, which holds only while no other account can rename, delete, re-permission or pre-create
+ * a folder on that path, or open the new folder before its ACL is set. Pure: the caller reads the
+ * access lists with icacls.
+ */
+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 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) {
+        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 & 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/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.3";

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.3";

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.3.
 
 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.3`. 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.3",
   "description": "A curated, scoped, bounded, durable, erasable and measured memory for AI agents.",
   "license": "MIT",
   "author": "mneves75",