@songsid/agend 2.3.5-alpha.4 → 2.3.5-alpha.5

package/dist/hub/db.js

@@ -0,0 +1,188 @@
+/**
+ * S5b (S-51; docs/design/hub-composition.md §3–§4): the Hub's private databases. Opening with private modes from the
+ * first byte, the per-slice migration registry, the "created together" set check, the Hub-instance binding, and the
+ * unit of work (HubUnitOfWork) with `hubTxDatabase` for slices that run their own statements inside it.
+ * Nothing here runs on import; only composition calls it, and only while a Hub switch is on.
+ */
+import Database from "better-sqlite3";
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, lstatSync, openSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ensurePrivateDirectory, privatePath } from "./private-files.js";
+/** Composition's closed set of hold reasons (hub-composition.md §2). Each has fleet text (locale "hub.hold.<code>"). */
+export const HUB_HOLD_CODES = [
+    "hub-incomplete",
+    "hub-unsealed",
+    "hub-state-newer",
+    "hub-state-mismatch",
+    "hub-storage",
+    "hub-directory-secret",
+    "hub-member-pairing",
+    "hub-provider-unavailable",
+    "service-unavailable",
+];
+export class HubStateError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "HubStateError";
+    }
+}
+/** "new" when no member of the set exists, "complete" when all do; anything else is hub-state-mismatch. */
+export function inspectStateSet(home, set) {
+    const members = [set.database, ...set.floors, ...set.keys];
+    const present = members.filter((rel) => {
+        try {
+            lstatSync(join(home, rel));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (present.length === 0)
+        return "new";
+    if (present.length === members.length)
+        return "complete";
+    const missing = members.filter((m) => !present.includes(m));
+    throw new HubStateError("hub-state-mismatch", `Hub state is partial (missing: ${missing.join(", ")}); nothing is recreated`);
+}
+const COMPONENT = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/**
+ * Transaction callbacks are synchronous. A thenable result is refused (inside the transaction, so it rolls back), and
+ * its eventual settlement is observed so a late rejection is never an unhandled rejection.
+ */
+function requireSynchronous(result, what) {
+    if (result && (typeof result === "object" || typeof result === "function") && typeof result.then === "function") {
+        try {
+            result.then(undefined, () => undefined);
+        }
+        catch {
+            /* a hostile thenable: refused below either way */
+        }
+        throw new Error(`Hub ${what} must be synchronous: no awaits inside it`);
+    }
+    return result;
+}
+/**
+ * Open (or, with `create`, first create) a private SQLite database at `rel` under `home`. The file is created 0600
+ * before SQLite touches it; its directory is a private, owned, non-symlink chain (S1's privatePath). WAL/SHM files are
+ * checked to be private after the journal mode is set.
+ */
+export function openHubDatabase(home, rel, options) {
+    let db;
+    try {
+        ensurePrivateDirectory(home, dirname(rel).replaceAll("\\", "/"));
+        const path = join(home, rel);
+        if (options.create) {
+            closeSync(openSync(path, "wx", 0o600));
+        }
+        else if (!existsSync(path)) {
+            throw new HubStateError("hub-state-mismatch", "the Hub database is missing");
+        }
+        privatePath(home, rel);
+        db = new Database(path, { fileMustExist: true });
+        db.pragma("journal_mode = WAL");
+        db.pragma("foreign_keys = ON");
+        db.pragma("busy_timeout = 5000");
+        db.pragma("secure_delete = ON");
+        db.pragma("synchronous = FULL");
+        for (const suffix of ["-wal", "-shm"]) {
+            if (existsSync(path + suffix))
+                privatePath(home, rel + suffix);
+        }
+        return db;
+    }
+    catch (err) {
+        db?.close();
+        if (err instanceof HubStateError)
+            throw err;
+        throw new HubStateError("hub-storage", `the Hub database could not be opened privately: ${err.message}`);
+    }
+}
+/**
+ * Apply every slice's migrations in one immediate transaction. A component stored with a higher version than this
+ * build knows, or a component this build does not know at all, means a newer build wrote the database: refuse.
+ */
+export function applyHubMigrations(db, migrations) {
+    const seen = new Set();
+    for (const m of migrations) {
+        if (!COMPONENT.test(m.component) || !Number.isSafeInteger(m.version) || m.version < 1 || typeof m.up !== "function") {
+            throw new HubStateError("hub-storage", `invalid Hub migration ${String(m.component)}`);
+        }
+        if (seen.has(m.component))
+            throw new HubStateError("hub-storage", `duplicate Hub migration ${m.component}`);
+        seen.add(m.component);
+    }
+    db.transaction(() => {
+        db.exec("CREATE TABLE IF NOT EXISTS hub_schema (component TEXT PRIMARY KEY, version INTEGER NOT NULL)");
+        const stored = new Map(db.prepare("SELECT component, version FROM hub_schema").all().map((r) => [r.component, r.version]));
+        for (const [component, version] of stored) {
+            if (!seen.has(component))
+                throw new HubStateError("hub-state-newer", `the Hub database has "${component}" (v${version}), which this version does not know`);
+        }
+        for (const m of migrations) {
+            const current = stored.get(m.component);
+            if (current !== undefined && current > m.version) {
+                throw new HubStateError("hub-state-newer", `the Hub database has ${m.component} v${current}; this version knows v${m.version}`);
+            }
+            if (current === m.version)
+                continue;
+            requireSynchronous(m.up(db), `migration ${m.component}`);
+            db.prepare("INSERT INTO hub_schema(component, version) VALUES(?, ?) ON CONFLICT(component) DO UPDATE SET version = excluded.version").run(m.component, m.version);
+        }
+    }).immediate();
+}
+/** The database's Hub (or member's Hub) id: written once at creation, compared on every open. */
+export const HUB_INSTANCE_MIGRATION = Object.freeze({
+    component: "s5-instance",
+    version: 1,
+    up(db) {
+        db.exec("CREATE TABLE IF NOT EXISTS hub_instance (singleton INTEGER PRIMARY KEY CHECK(singleton = 1), hub_id TEXT NOT NULL, created_at INTEGER NOT NULL)");
+    },
+});
+export function bindHubInstance(db, hubId, mode, now) {
+    const row = db.prepare("SELECT hub_id FROM hub_instance WHERE singleton = 1").get();
+    if (mode === "new") {
+        if (row)
+            throw new HubStateError("hub-state-mismatch", "a new Hub database already has an owner");
+        db.prepare("INSERT INTO hub_instance(singleton, hub_id, created_at) VALUES(1, ?, ?)").run(hubId, now);
+        return;
+    }
+    if (!row)
+        throw new HubStateError("hub-state-mismatch", "the Hub database does not say which Hub it belongs to");
+    if (row.hub_id !== hubId)
+        throw new HubStateError("hub-state-mismatch", "the Hub database belongs to another Hub");
+}
+/** Live transactions: a token maps to its database only while its `atomic` callback runs. */
+const liveTx = new WeakMap();
+/**
+ * The database behind a live transaction, for a slice's own statements (S3's repositories). Throws once the
+ * transaction has committed or rolled back, so a leaked handle cannot write outside a transaction.
+ */
+export function hubTxDatabase(tx) {
+    const db = liveTx.get(tx);
+    if (!db || !db.inTransaction)
+        throw new Error("Hub transaction is not active");
+    return db;
+}
+/** HubUnitOfWork over one database: immediate transactions; nested calls are savepoints; async work is refused. */
+export function createHubUnitOfWork(db) {
+    return {
+        atomic(work) {
+            const run = db.transaction(() => {
+                const tx = Object.freeze({ id: randomUUID() });
+                liveTx.set(tx, db);
+                try {
+                    return requireSynchronous(work(tx), "transaction (atomic)");
+                }
+                finally {
+                    liveTx.delete(tx);
+                }
+            });
+            return db.inTransaction ? run() : run.immediate();
+        },
+    };
+}
+//# sourceMappingURL=db.js.map

package/dist/hub/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/hub/db.ts"],"names":[],"mappings":"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"}

package/dist/hub/directory/config.d.ts

@@ -0,0 +1,39 @@
+export type DirectoryProfile = "ad" | "openldap";
+export interface HubDirectoryConfig {
+    /** A short, stable name for this directory; it is the first half of every person key. */
+    realm: string;
+    /** ldaps://host[:port]. Nothing else: ldap:// (even with StartTLS) is refused. */
+    url: string;
+    /** PEM text of the CA(s) that issued the directory's certificate. Omitted: Node's built-in roots. */
+    caPem?: string;
+    /** Where people are searched for. */
+    baseDn: string;
+    /** The read-only service account the Hub searches with. Its password is passed separately as a secret. */
+    bindDn: string;
+    /** A reference to the service account's password in the Hub's secret store; resolved by the caller (S5), never here. */
+    bindPasswordRef?: string;
+    profile: DirectoryProfile;
+    /** Defaults per profile: sAMAccountName (ad), uid (openldap). */
+    loginAttribute?: string;
+    /** An extra RFC 4515 filter ANDed with the login match, e.g. "(objectClass=person)". */
+    userFilter?: string;
+    /** Per-operation and connect timeout, 500–30000 ms (default 5000). */
+    timeoutMs?: number;
+}
+export interface ResolvedDirectoryConfig {
+    readonly realm: string;
+    readonly host: string;
+    readonly port: number;
+    readonly url: string;
+    readonly caPem?: string;
+    readonly baseDn: string;
+    readonly bindDn: string;
+    readonly profile: DirectoryProfile;
+    readonly loginAttribute: string;
+    readonly userFilter: string;
+    readonly timeoutMs: number;
+}
+export declare class HubDirectoryConfigError extends Error {
+    constructor(message: string);
+}
+export declare function resolveDirectoryConfig(input: unknown): ResolvedDirectoryConfig;

package/dist/hub/directory/config.js

@@ -0,0 +1,108 @@
+/**
+ * Hub directory configuration (`hub.directory`), validated before any connection is made. The checks are the security
+ * contract of S-43: credentials only ever travel over verified LDAPS (decision 7e5b8a8f: LDAPS only, so ldap:// and
+ * StartTLS are refused), there is no switch to turn certificate verification off, and unknown keys are refused so one
+ * cannot be smuggled in.
+ */
+import { isIP } from "node:net";
+export class HubDirectoryConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HubDirectoryConfigError";
+    }
+}
+const KNOWN_KEYS = new Set(["realm", "url", "caPem", "bindPasswordRef", "baseDn", "bindDn", "profile", "loginAttribute", "userFilter", "timeoutMs"]);
+// A stable configured id (never a display name), no slash: it is the first half of "<realm>/<objectId>".
+const REALM = /^[a-z][a-z0-9_-]{0,63}$/;
+const ATTRIBUTE = /^[A-Za-z][A-Za-z0-9-]{0,63}$/;
+// Printable, no NUL/newlines; a DN is checked for shape only, the directory judges the rest.
+const DN = /^[^\u0000-\u001f\u007f]{1,1024}$/;
+const DEFAULT_FILTER = {
+    ad: "(&(objectClass=person)(!(objectClass=computer)))",
+    openldap: "(objectClass=person)",
+};
+const DEFAULT_LOGIN = { ad: "sAMAccountName", openldap: "uid" };
+function fail(message) {
+    throw new HubDirectoryConfigError(message);
+}
+export function resolveDirectoryConfig(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        fail("hub directory: the configuration must be an object");
+    const raw = input;
+    for (const key of Object.keys(raw)) {
+        if (!KNOWN_KEYS.has(key))
+            fail(`hub directory: unknown setting "${key}" (certificate verification cannot be turned off)`);
+    }
+    const str = (key, required) => {
+        const v = raw[key];
+        if (v === undefined && !required)
+            return undefined;
+        if (typeof v !== "string" || v.length === 0)
+            fail(`hub directory: "${key}" must be a non-empty string`);
+        return v;
+    };
+    const realm = str("realm", true);
+    if (!REALM.test(realm))
+        fail('hub directory: "realm" must be a lowercase id: a letter, then letters, digits, "_" or "-" (64 at most)');
+    const profile = str("profile", true);
+    if (profile !== "ad" && profile !== "openldap")
+        fail('hub directory: "profile" must be "ad" or "openldap"');
+    const urlText = str("url", true);
+    let url;
+    try {
+        url = new URL(urlText);
+    }
+    catch {
+        fail('hub directory: "url" is not a URL');
+    }
+    if (url.username || url.password)
+        fail('hub directory: "url" must not carry credentials');
+    if ((url.pathname && url.pathname !== "/") || url.search || url.hash)
+        fail('hub directory: "url" must be scheme://host[:port] only');
+    const host = url.hostname.replace(/^\[(.*)\]$/, "$1");
+    if (!host)
+        fail('hub directory: "url" has no host');
+    // LDAPS only (decision 7e5b8a8f). ldap:// is plaintext until upgraded, and StartTLS is not offered as a mode in P1.
+    if (url.protocol === "ldap:")
+        fail("hub directory: ldap:// is plaintext and is not supported; use ldaps://");
+    if (url.protocol !== "ldaps:")
+        fail('hub directory: "url" must start with ldaps://');
+    const port = url.port ? Number(url.port) : 636;
+    const caPem = str("caPem", false);
+    if (caPem !== undefined && !/-----BEGIN CERTIFICATE-----/.test(caPem))
+        fail('hub directory: "caPem" must hold PEM certificate text');
+    if (raw.bindPasswordRef !== undefined)
+        str("bindPasswordRef", false);
+    const baseDn = str("baseDn", true);
+    const bindDn = str("bindDn", true);
+    if (!DN.test(baseDn))
+        fail('hub directory: "baseDn" has control characters or is too long');
+    if (!DN.test(bindDn))
+        fail('hub directory: "bindDn" has control characters or is too long');
+    const loginAttribute = str("loginAttribute", false) ?? DEFAULT_LOGIN[profile];
+    if (!ATTRIBUTE.test(loginAttribute))
+        fail('hub directory: "loginAttribute" must be an attribute name');
+    const extra = str("userFilter", false);
+    if (extra !== undefined && !/^\(.*\)$/s.test(extra))
+        fail('hub directory: "userFilter" must be a parenthesised LDAP filter');
+    const userFilter = extra ?? DEFAULT_FILTER[profile];
+    const timeoutRaw = raw.timeoutMs;
+    if (timeoutRaw !== undefined && (typeof timeoutRaw !== "number" || !Number.isInteger(timeoutRaw) || timeoutRaw < 500 || timeoutRaw > 30_000)) {
+        fail('hub directory: "timeoutMs" must be a whole number from 500 to 30000');
+    }
+    const timeoutMs = timeoutRaw ?? 5000;
+    return Object.freeze({
+        realm,
+        host,
+        port,
+        url: `ldaps://${isIP(host) === 6 ? `[${host}]` : host}:${port}`,
+        ...(caPem !== undefined ? { caPem } : {}),
+        baseDn,
+        bindDn,
+        profile,
+        loginAttribute,
+        userFilter,
+        timeoutMs,
+    });
+}
+//# sourceMappingURL=config.js.map

package/dist/hub/directory/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/hub/directory/config.ts"],"names":[],"mappings":"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"}

package/dist/hub/directory/directory.d.ts

@@ -0,0 +1,18 @@
+import type { HubDirectory } from "./types.js";
+export interface HubDirectorySecrets {
+    /** The service account's password (resolved by the caller from the Hub's secret store). */
+    readonly bindPassword: string;
+}
+export interface HubDirectoryDiagnostic {
+    readonly op: "sign-in" | "eligibility" | "initialization-lookup";
+    readonly outcome: string;
+    /** The underlying error's message, for the technical log. Never contains a password. */
+    readonly error?: string;
+}
+export interface HubDirectoryOptions {
+    /** Called once per refused or failed operation. */
+    readonly onDiagnostic?: (event: HubDirectoryDiagnostic) => void;
+    /** Test seam for expiry checks. */
+    readonly now?: () => number;
+}
+export declare function createHubDirectory(config: unknown, secrets: HubDirectorySecrets, options?: HubDirectoryOptions): HubDirectory;