@shieldaai/agent-map 0.1.0-alpha.3 → 1.1.0

package/dist/assets.js

@@ -1,39 +1,29 @@
 import { constants } from 'node:fs';
-import { open } from 'node:fs/promises';
 import { isAbsolute, join } from 'node:path';
-import { fail, trustedHostFile } from './boundary.js';
+import { fail } from './common.js';
+import { readHostFile } from './boundary.js';
+/** Viewer assets run in authenticated browsers: this user's or root's regular files, never a link. */
+const ASSET_FILE = { noFollow: true, owner: 'service-or-root', singleLink: false, private: false };
 /** Load the fixed public assets once; never follow a replaced leaf or read beyond the cap. */
 export async function loadMapAssets(directory) {
     const assets = new Map();
     if (directory === undefined)
         return assets;
-    if (typeof directory !== 'string' || !isAbsolute(directory) ||
-        typeof constants.O_NONBLOCK !== 'number' || typeof constants.O_NOFOLLOW !== 'number')
+    if (typeof directory !== 'string' ||
+        !isAbsolute(directory) ||
+        typeof constants.O_NONBLOCK !== 'number' ||
+        typeof constants.O_NOFOLLOW !== 'number')
         fail('MAP_CONFIG_INVALID');
     const maximum = 4 * 1024 * 1024;
-    for (const [name, mime] of [['index.html', 'text/html; charset=utf-8'], ['app.js', 'text/javascript; charset=utf-8'], ['app.css', 'text/css; charset=utf-8']]) {
+    for (const [name, mime] of [
+        ['index.html', 'text/html; charset=utf-8'],
+        ['app.js', 'text/javascript; charset=utf-8'],
+        // The synthetic demo, which app.js imports only when a reader opens it.
+        ['demo.js', 'text/javascript; charset=utf-8'],
+        ['app.css', 'text/css; charset=utf-8'],
+    ]) {
         try {
-            const file = await open(join(directory, name), constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
-            try {
-                const info = await file.stat();
-                if (!trustedHostFile(info) || info.size > maximum)
-                    fail('MAP_CONFIG_INVALID');
-                const data = Buffer.alloc(maximum + 1);
-                let bytes = 0;
-                while (bytes < data.length) {
-                    const read = await file.read(data, bytes, data.length - bytes, null);
-                    if (!read.bytesRead)
-                        break;
-                    bytes += read.bytesRead;
-                }
-                if (bytes > maximum)
-                    fail('MAP_CONFIG_INVALID');
-                // Do not retain the full maximum-sized allocation for a small asset.
-                assets.set(`/${name}`, { body: Buffer.from(data.subarray(0, bytes)), mime });
-            }
-            finally {
-                await file.close();
-            }
+            assets.set(`/${name}`, { body: await readHostFile(join(directory, name), maximum, ASSET_FILE), mime });
         }
         catch {
             fail('MAP_CONFIG_INVALID');

package/dist/boundary-flags.d.ts

@@ -0,0 +1,73 @@
+import type { GuardRelation, MapNode } from './types.js';
+/**
+ * "Dangerous three": a live task of an agent that can read private data, read outside
+ * content and send data out. Declared evidence only; a flag is never a permission decision,
+ * and missing or old data reads as `unknown`, never as safe.
+ */
+export type Leg = 'present' | 'absent' | 'unknown';
+export type DangerousThreeStatus = 'exposed' | 'mitigated' | 'unknown' | 'absent';
+/** The read-only graph access the computation needs; the service supplies its bounded index. */
+export interface FlagGraph {
+    linked(node: MapNode, kind: GuardRelation, reverse?: boolean): MapNode[];
+    /** In-scope bindings of a tool marked confidential or restricted (at most five), for `*` grants. */
+    sensitiveBindings(tool: string): readonly {
+        readonly id: string;
+        readonly sensitivity: string;
+    }[];
+    step(amount?: number): void;
+}
+export interface FlagEvidence {
+    readonly leg: 'privateData' | 'outsideContent' | 'externalSend' | 'mitigation';
+    readonly taskId: string;
+    readonly reason: string;
+    readonly tool?: string;
+    readonly resourceBindingId?: string;
+}
+export interface DangerousThree {
+    readonly kind: 'dangerous_three';
+    readonly status: DangerousThreeStatus;
+    /** The task that decides the status; legs and evidence both describe this task. */
+    readonly taskId: string | null;
+    readonly legs: {
+        readonly privateData: Leg;
+        readonly outsideContent: Leg;
+        readonly externalSend: Leg;
+    };
+    readonly evidence: readonly FlagEvidence[];
+    readonly evidenceTruncated: boolean;
+    readonly notes: readonly string[];
+    readonly liveTasks: number;
+    readonly evidenceKind: 'declared';
+    readonly assessment: 'unknown';
+    readonly limitations: readonly string[];
+}
+export declare const DANGEROUS_THREE_LIMITATIONS: readonly string[];
+/** Follows one link kind from a task to the tasks it names (delegation parent, handoff source). */
+export type TaskLinks = (node: MapNode, kind: 'G_DELEGATED_FROM' | 'G_DERIVED_FROM') => MapNode[];
+export interface TaskLiveness {
+    readonly live: boolean;
+    /** A linked task exists but this read cannot see it. */
+    readonly hidden: boolean;
+    readonly depthExceeded: boolean;
+    /** An older import never recorded whether the task has a parent or a source. */
+    readonly unrecorded: boolean;
+    /** More than one parent or source: malformed, so the chain says nothing. */
+    readonly ambiguous: boolean;
+    /**
+     * A task on the chain lacks a boolean `revoked`, or one on the delegation chain lacks a
+     * numeric `deadline`: it is treated as live, but that was not established.
+     */
+    readonly unverified: boolean;
+}
+/**
+ * The executor refuses a task when it or any task it descends from (delegation parents and
+ * handoff sources, transitively) is revoked, and when it or a delegation ancestor has expired;
+ * a handoff source's deadline does not bind the task. Walk up to MAX_DEPTH hops, the same reach
+ * as the store's ancestor read, so the one-agent and team-wide reads stop at the same place. A
+ * link that leaves the read makes liveness incomplete; the caller treats that as unknown.
+ */
+export declare function taskLiveness(links: TaskLinks, task: MapNode, observedAt: number, step: () => void): TaskLiveness;
+/** One status per agent: the worst of its live tasks. Legs and evidence describe that task. */
+export declare function dangerousThree(graph: FlagGraph, agent: MapNode, observedAt: number, allTeams: boolean, 
+/** The read had no room for delegation ancestors: missing parents are not a scope matter. */
+ancestorsNotLoaded?: boolean): DangerousThree;

package/dist/boundary-flags.js

@@ -0,0 +1,352 @@
+// An unknown task may be exposed, so it outranks a mitigated one: amber never hides grey.
+const RANK = { absent: 0, mitigated: 1, unknown: 2, exposed: 3 };
+const SENSITIVE = new Set(['confidential', 'restricted']);
+const MITIGATING = new Set(['require_approval', 'deny']);
+/** Evidence items kept per leg (and for mitigation), so no present leg loses all of its evidence. */
+const MAX_EVIDENCE_PER_LEG = 8;
+function cappedEvidence(evidence) {
+    const kept = new Map();
+    const items = evidence.filter(item => {
+        const count = (kept.get(item.leg) ?? 0) + 1;
+        kept.set(item.leg, count);
+        return count <= MAX_EVIDENCE_PER_LEG;
+    });
+    return { items, truncated: items.length < evidence.length };
+}
+const MAX_DEPTH = 16;
+export const DANGEROUS_THREE_LIMITATIONS = Object.freeze([
+    'Declared grants and labels; not proof that data can leave.',
+    'Only sends that the resolver marks external are checked; a tool that does not declare sendsExternal is unknown.',
+]);
+const text = (node, key) => typeof node.properties[key] === 'string' ? node.properties[key] : null;
+const list = (node, key) => {
+    const value = node.properties[key];
+    return Array.isArray(value) && value.every(item => typeof item === 'string') ? value : null;
+};
+/** present beats unknown beats absent; an empty set of contributions is absent. */
+function combine(legs) {
+    return legs.includes('present') ? 'present' : legs.includes('unknown') ? 'unknown' : 'absent';
+}
+const LINEAGE = {
+    live: true,
+    recipients: null,
+    hidden: false,
+    depthExceeded: false,
+    unrecorded: false,
+    ambiguous: false,
+    unverified: false,
+};
+/**
+ * The executor refuses a task when it or any task it descends from (delegation parents and
+ * handoff sources, transitively) is revoked, and when it or a delegation ancestor has expired;
+ * a handoff source's deadline does not bind the task. Walk up to MAX_DEPTH hops, the same reach
+ * as the store's ancestor read, so the one-agent and team-wide reads stop at the same place. A
+ * link that leaves the read makes liveness incomplete; the caller treats that as unknown.
+ */
+export function taskLiveness(links, task, observedAt, step) {
+    const result = {
+        live: true,
+        hidden: false,
+        depthExceeded: false,
+        unrecorded: false,
+        ambiguous: false,
+        unverified: false,
+    };
+    let dead = false;
+    // The task's own state needs no chain: malformed links cannot make it live again.
+    const own = task.properties.revoked === true ||
+        (typeof task.properties.deadline === 'number' && task.properties.deadline <= observedAt);
+    // Deadlines: the task and its delegation parents only.
+    for (let current = task, depth = 0;; depth++) {
+        step();
+        const deadline = current.properties.deadline;
+        if (typeof deadline !== 'number')
+            result.unverified = true;
+        else if (deadline <= observedAt)
+            dead = true;
+        const parents = links(current, 'G_DELEGATED_FROM').filter(item => item.label === 'GuardTask');
+        if (parents.length !== 1 || depth >= MAX_DEPTH)
+            break;
+        current = parents[0];
+    }
+    // Revocation, and whether the chain is complete: every task reachable through both links.
+    const seen = new Set([task.id]);
+    let frontier = [task];
+    for (let depth = 0; frontier.length; depth++) {
+        const next = [];
+        for (const node of frontier) {
+            step();
+            if (node.properties.revoked === true)
+                dead = true;
+            else if (node.properties.revoked !== false)
+                result.unverified = true;
+            for (const [kind, recorded] of [
+                ['G_DELEGATED_FROM', node.properties.delegated],
+                ['G_DERIVED_FROM', node.properties.derived],
+            ]) {
+                if (recorded !== true && recorded !== false)
+                    result.unrecorded = true;
+                // Past MAX_DEPTH hops nothing new is read, in either read, so a recorded link is a cut
+                // unless it leads back to a task already read within reach.
+                if (depth >= MAX_DEPTH) {
+                    const known = links(node, kind).filter(item => item.label === 'GuardTask');
+                    if (recorded === true && !(known.length === 1 && seen.has(known[0].id)))
+                        result.depthExceeded = true;
+                    continue;
+                }
+                const linked = links(node, kind).filter(item => item.label === 'GuardTask');
+                // Two visible links of one kind are malformed. (A second one outside a team reader's
+                // read is not seen; the collector writes one parent and one source per task.)
+                if (linked.length > 1)
+                    result.ambiguous = true;
+                if (!linked.length && recorded === true)
+                    result.hidden = true;
+                for (const item of linked) {
+                    if (seen.has(item.id))
+                        continue;
+                    seen.add(item.id);
+                    next.push(item);
+                }
+            }
+        }
+        frontier = next;
+    }
+    // A revoked or expired task on a malformed chain proves nothing about this task: unknown.
+    return own || (dead && !result.ambiguous) ? { ...result, live: false } : result;
+}
+/**
+ * Liveness over delegation parents and handoff sources, and the effective recipient set: the
+ * core checks recipients against every delegation ancestor, so any gap leaves it unknown.
+ */
+function lineage(graph, task, observedAt) {
+    const life = taskLiveness((node, kind) => graph.linked(node, kind), task, observedAt, () => graph.step());
+    if (!life.live)
+        return { ...LINEAGE, live: false };
+    const complete = !life.hidden && !life.unrecorded && !life.depthExceeded && !life.ambiguous;
+    let recipients = complete ? new Set(list(task, 'allowed_recipients') ?? []) : null;
+    if (list(task, 'allowed_recipients') === null)
+        recipients = null;
+    for (let current = task, depth = 0; recipients !== null && depth <= MAX_DEPTH; depth++) {
+        const parent = graph.linked(current, 'G_DELEGATED_FROM').find(node => node.label === 'GuardTask');
+        if (!parent)
+            break;
+        const allowed = list(parent, 'allowed_recipients');
+        recipients = allowed === null ? null : new Set([...recipients].filter(item => allowed.includes(item)));
+        current = parent;
+    }
+    return {
+        live: true,
+        recipients: recipients === null ? null : [...recipients].sort(),
+        hidden: life.hidden,
+        depthExceeded: life.depthExceeded,
+        unrecorded: life.unrecorded,
+        ambiguous: life.ambiguous,
+        // Without a snapshot time expiry cannot be judged at all.
+        unverified: life.unverified || Number.isNaN(observedAt),
+    };
+}
+function evaluateTask(graph, task, observedAt) {
+    const chain = lineage(graph, task, observedAt);
+    if (!chain.live)
+        return null;
+    const taskId = task.entityId;
+    const evidence = [];
+    const grants = graph.linked(task, 'G_HAS_GRANT').filter(node => node.label === 'GuardGrant');
+    const privateLegs = [], outsideLegs = [], sendLegs = [];
+    // Private data: the task is already sensitive, or a granted binding is marked sensitive.
+    const sensitiveTask = task.properties.sensitive === true;
+    // A missing or malformed `sensitive` may hide private data and a send block alike.
+    const sensitiveKnown = typeof task.properties.sensitive === 'boolean';
+    if (sensitiveTask) {
+        privateLegs.push('present');
+        evidence.push({ leg: 'privateData', taskId, reason: 'task_sensitive' });
+    }
+    else if (!sensitiveKnown)
+        privateLegs.push('unknown');
+    const binding = (node, tool) => {
+        const sensitivity = text(node, 'sensitivity');
+        if (sensitivity !== null && SENSITIVE.has(sensitivity)) {
+            privateLegs.push('present');
+            evidence.push({
+                leg: 'privateData',
+                taskId,
+                reason: `binding_${sensitivity}`,
+                tool,
+                resourceBindingId: node.entityId,
+            });
+        }
+        else
+            privateLegs.push(sensitivity === 'public' || sensitivity === 'internal' ? 'absent' : 'unknown');
+    };
+    const tools = new Map();
+    for (const grant of grants) {
+        const tool = text(grant, 'tool');
+        const resources = list(grant, 'resources');
+        if (tool === null || resources === null) {
+            // A malformed grant says nothing about any leg.
+            privateLegs.push('unknown');
+            outsideLegs.push('unknown');
+            sendLegs.push('unknown');
+            continue;
+        }
+        const toolNodes = graph
+            .linked(grant, 'G_FOR_TOOL')
+            .filter(node => node.label === 'GuardTool' && text(node, 'name') === tool);
+        if (!tools.has(tool) || toolNodes.length === 1)
+            tools.set(tool, toolNodes.length === 1 ? toolNodes[0] : null);
+        if (resources.includes('*')) {
+            // `*` covers every resource of the tool, including ones the host never described: present
+            // when an in-scope binding of the tool is sensitive, otherwise unknown.
+            const matches = graph.sensitiveBindings(tool);
+            graph.step(matches.length + 1);
+            for (const match of matches) {
+                privateLegs.push('present');
+                evidence.push({
+                    leg: 'privateData',
+                    taskId,
+                    reason: `binding_${match.sensitivity}`,
+                    tool,
+                    resourceBindingId: match.id,
+                });
+            }
+            if (!matches.length)
+                privateLegs.push('unknown');
+        }
+        const reached = new Set();
+        for (const selector of graph.linked(grant, 'G_TARGETS').filter(node => node.label === 'GuardResource')) {
+            const selected = text(selector, 'resource_id');
+            if (selected === '*' || selected === null || !resources.includes(selected))
+                continue;
+            reached.add(selected);
+            const bindings = graph
+                .linked(selector, 'G_BINDS_SELECTOR', true)
+                .filter(node => node.label === 'GuardResourceBinding' && text(node, 'tool') === tool);
+            // A granted resource the host never described has unknown sensitivity.
+            if (!bindings.length)
+                privateLegs.push('unknown');
+            for (const node of bindings)
+                binding(node, tool);
+        }
+        // A granted resource with no selector in the read says nothing about its data.
+        if (resources.some(resource => resource !== '*' && !reached.has(resource)))
+            privateLegs.push('unknown');
+    }
+    // Outside content and sending, per granted tool. A resolver can mark any call untrusted, so
+    // only an explicit `readsUntrusted: false` rules a tool out; undeclared stays unknown.
+    if (task.properties.untrusted === true) {
+        outsideLegs.push('present');
+        evidence.push({ leg: 'outsideContent', taskId, reason: 'task_untrusted' });
+    }
+    // The core refuses every external send from a sensitive family, and from a task whose
+    // effective recipient set is empty. Both stop only sends a resolver marks external, which
+    // is what `sendsExternal: true` promises; an undeclared tool may send unmarked.
+    const noRecipients = chain.recipients !== null && chain.recipients.length === 0;
+    const senders = [];
+    for (const [tool, node] of tools) {
+        graph.step();
+        const registered = node !== null && node.properties.registered === true && node.properties.known_metadata !== false;
+        if (!registered) {
+            outsideLegs.push('unknown');
+            sendLegs.push('unknown');
+            senders.push({ tool, declared: false, mode: null });
+            continue;
+        }
+        const reads = node.properties.reads_untrusted;
+        if (reads === true) {
+            outsideLegs.push('present');
+            evidence.push({ leg: 'outsideContent', taskId, reason: 'tool_reads_untrusted', tool });
+        }
+        else
+            outsideLegs.push(reads === false ? 'absent' : 'unknown');
+        const mode = (text(node, 'untrusted_context') ?? text(node, 'untrusted_context_default'));
+        const sends = node.properties.sends_external;
+        if (sends === false)
+            sendLegs.push('absent');
+        else if (sends === true) {
+            const blocked = sensitiveTask ? 'sensitive_egress_denied' : noRecipients ? 'no_effective_recipients' : null;
+            if (blocked) {
+                sendLegs.push('absent');
+                evidence.push({ leg: 'externalSend', taskId, reason: blocked, tool });
+                continue;
+            }
+            sendLegs.push(chain.recipients === null || !sensitiveKnown ? 'unknown' : 'present');
+            senders.push({ tool, declared: true, mode });
+            evidence.push({ leg: 'externalSend', taskId, reason: 'tool_sends_external', tool });
+        }
+        else {
+            sendLegs.push('unknown');
+            senders.push({ tool, declared: false, mode });
+        }
+    }
+    const legs = {
+        privateData: combine(privateLegs),
+        outsideContent: combine(outsideLegs),
+        externalSend: combine(sendLegs),
+    };
+    const values = Object.values(legs);
+    let status;
+    if (values.includes('absent'))
+        status = 'absent';
+    else if (values.includes('unknown'))
+        status = 'unknown';
+    else if (senders.some(sender => sender.declared && sender.mode === 'allow'))
+        status = 'exposed';
+    else if (senders.every(sender => MITIGATING.has(sender.mode))) {
+        status = 'mitigated';
+        for (const sender of senders)
+            evidence.push({ leg: 'mitigation', taskId, reason: `untrusted_context_${sender.mode}`, tool: sender.tool });
+    }
+    else
+        status = 'unknown';
+    // A chain read only in part (an ancestor hidden, not loaded, unrecorded or too deep), or
+    // one whose revocation or expiry facts are missing, may hold a revoked or expired ancestor,
+    // so the task may not be live: never call it absent.
+    if (status === 'absent' &&
+        (chain.hidden || chain.unrecorded || chain.depthExceeded || chain.ambiguous || chain.unverified))
+        status = 'unknown';
+    return { taskId, status, legs, evidence, chain };
+}
+/** One status per agent: the worst of its live tasks. Legs and evidence describe that task. */
+export function dangerousThree(graph, agent, observedAt, allTeams, 
+/** The read had no room for delegation ancestors: missing parents are not a scope matter. */
+ancestorsNotLoaded = false) {
+    const deployments = graph.linked(agent, 'G_INSTANCE_OF', true).filter(node => node.label === 'GuardDeployment');
+    const tasks = deployments.flatMap(deployment => graph.linked(deployment, 'G_ASSIGNED_TO', true).filter(node => node.label === 'GuardTask'));
+    const results = tasks
+        .map(task => evaluateTask(graph, task, observedAt))
+        .filter((item) => item !== null)
+        // A stable choice among equally bad tasks, independent of read order.
+        .sort((a, b) => RANK[b.status] - RANK[a.status] || (a.taskId < b.taskId ? -1 : a.taskId > b.taskId ? 1 : 0));
+    const notes = [];
+    if (!results.length)
+        notes.push('no_live_tasks');
+    if (results.some(item => item.chain.hidden)) {
+        if (ancestorsNotLoaded)
+            notes.push('delegation_ancestors_not_loaded');
+        else
+            notes.push(allTeams ? 'delegation_parent_missing' : 'ancestor_evidence_outside_visible_scope');
+    }
+    if (results.some(item => item.chain.ambiguous))
+        notes.push('delegation_evidence_ambiguous');
+    if (results.some(item => item.chain.unverified))
+        notes.push('task_liveness_unverified');
+    if (results.some(item => item.chain.unrecorded))
+        notes.push('delegation_not_recorded');
+    if (results.some(item => item.chain.depthExceeded))
+        notes.push('delegation_depth_exceeded');
+    const worst = results[0] ?? null;
+    const listed = cappedEvidence(worst?.evidence ?? []);
+    return {
+        kind: 'dangerous_three',
+        status: worst?.status ?? 'unknown',
+        taskId: worst?.taskId ?? null,
+        legs: worst?.legs ?? { privateData: 'unknown', outsideContent: 'unknown', externalSend: 'unknown' },
+        evidence: listed.items,
+        evidenceTruncated: listed.truncated,
+        notes,
+        liveTasks: results.length,
+        evidenceKind: 'declared',
+        assessment: 'unknown',
+        limitations: DANGEROUS_THREE_LIMITATIONS,
+    };
+}

package/dist/boundary.d.ts

@@ -1,7 +1,22 @@
-import type { Stats } from 'node:fs';
-export declare function fail(code: string): never;
+import { type Stats } from 'node:fs';
 export declare function trustedHostFile(info: Stats): boolean;
+/** Which files a launcher accepts. The rules differ by what the file is for, and each caller states its own. */
+export interface HostFileRule {
+    /** Refuse a symbolic link at the path itself. */
+    readonly noFollow: boolean;
+    /** `service`: owned by this user. `service-or-root`: owned by the effective user or by root. */
+    readonly owner: 'service' | 'service-or-root';
+    /** Refuse a file with more than one hard link. */
+    readonly singleLink: boolean;
+    /** Refuse any group or other access, as for a key or a file that names secrets. */
+    readonly private: boolean;
+}
+/**
+ * Reads at most `maximum` bytes of a regular file that is not writable by group or others.
+ * The checks and the read use one non-blocking descriptor, so they apply to the bytes that
+ * are used, and a file that grows after the check is refused rather than read without bound.
+ */
+export declare function readHostFile(path: string, maximum: number, rule: HostFileRule): Promise<Buffer>;
 export declare function fields(value: unknown, allowed: readonly string[], required?: readonly string[]): Record<string, unknown>;
-export declare function integer(value: unknown, fallback: number, min: number, max: number): number;
 /** Bounded strict JSON, including duplicate decoded keys that JSON.parse would discard. */
 export declare function parseRequest(bytes: Uint8Array, maximum?: number): unknown;

package/dist/boundary.js

@@ -1,19 +1,68 @@
-import { MapQueryError } from './types.js';
-export function fail(code) { throw new MapQueryError(code); }
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { fail } from './common.js';
 // Configuration selects credential destinations. Viewer assets run in authenticated browsers.
 // Check the descriptor after open so the test applies to the bytes that will be used.
 export function trustedHostFile(info) {
-    return typeof process.geteuid === 'function' && info.isFile() &&
-        (info.uid === 0 || info.uid === process.geteuid()) && (info.mode & 0o022) === 0;
+    return (typeof process.geteuid === 'function' &&
+        info.isFile() &&
+        (info.uid === 0 || info.uid === process.geteuid()) &&
+        (info.mode & 0o022) === 0);
+}
+/**
+ * Reads at most `maximum` bytes of a regular file that is not writable by group or others.
+ * The checks and the read use one non-blocking descriptor, so they apply to the bytes that
+ * are used, and a file that grows after the check is refused rather than read without bound.
+ */
+export async function readHostFile(path, maximum, rule) {
+    if (typeof constants.O_NONBLOCK !== 'number' ||
+        (rule.noFollow && !constants.O_NOFOLLOW) ||
+        (rule.owner === 'service' && typeof process.getuid !== 'function'))
+        fail('MAP_CONFIG_INVALID');
+    const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK | (rule.noFollow ? constants.O_NOFOLLOW : 0));
+    try {
+        const info = await file.stat();
+        const owned = rule.owner === 'service'
+            ? info.isFile() && info.uid === process.getuid() && (info.mode & 0o022) === 0
+            : trustedHostFile(info);
+        if (!owned ||
+            info.size > maximum ||
+            (rule.singleLink && info.nlink !== 1) ||
+            (rule.private && (info.mode & 0o077) !== 0))
+            fail('MAP_CONFIG_INVALID');
+        const data = Buffer.alloc(maximum + 1);
+        let bytes = 0;
+        while (bytes < data.length) {
+            const read = await file.read(data, bytes, data.length - bytes, null);
+            if (!read.bytesRead)
+                break;
+            bytes += read.bytesRead;
+        }
+        if (bytes > maximum)
+            fail('MAP_CONFIG_INVALID');
+        // Do not retain the full maximum-sized allocation for a small file.
+        return Buffer.from(data.subarray(0, bytes));
+    }
+    finally {
+        await file.close();
+    }
 }
 export function fields(value, allowed, required = []) {
-    if (!value || typeof value !== 'object' || Array.isArray(value) ||
-        ![null, Object.prototype].includes(Object.getPrototypeOf(value)) || Object.getOwnPropertySymbols(value).length)
+    if (!value ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        ![null, Object.prototype].includes(Object.getPrototypeOf(value)) ||
+        Object.getOwnPropertySymbols(value).length)
         fail('MAP_CONFIG_INVALID');
+    if (Object.getOwnPropertyNames(value).some(key => !allowed.includes(key)))
+        fail('MAP_CONFIG_INVALID');
+    // Copy by the allowed names, never by a name the input supplied.
     const result = Object.create(null);
-    for (const key of Object.getOwnPropertyNames(value)) {
+    for (const key of allowed) {
         const descriptor = Object.getOwnPropertyDescriptor(value, key);
-        if (!allowed.includes(key) || !descriptor.enumerable || !('value' in descriptor))
+        if (!descriptor)
+            continue;
+        if (!descriptor.enumerable || !('value' in descriptor))
             fail('MAP_CONFIG_INVALID');
         result[key] = descriptor.value;
     }
@@ -21,12 +70,6 @@ export function fields(value, allowed, required = []) {
         fail('MAP_CONFIG_INVALID');
     return result;
 }
-export function integer(value, fallback, min, max) {
-    const result = value === undefined ? fallback : value;
-    if (typeof result !== 'number' || !Number.isSafeInteger(result) || result < min || result > max)
-        fail('MAP_CONFIG_INVALID');
-    return result;
-}
 /** Bounded strict JSON, including duplicate decoded keys that JSON.parse would discard. */
 export function parseRequest(bytes, maximum = 65_536) {
     if (bytes.byteLength > maximum)
@@ -35,8 +78,10 @@ export function parseRequest(bytes, maximum = 65_536) {
         const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
         let offset = 0;
         let nodes = 0;
-        const space = () => { while (/[\t\n\r ]/.test(text[offset] ?? '\0'))
-            offset++; };
+        const space = () => {
+            while (/[\t\n\r ]/.test(text[offset] ?? '\0'))
+                offset++;
+        };
         const string = () => {
             const start = offset++;
             while (offset < text.length) {
@@ -58,26 +103,31 @@ export function parseRequest(bytes, maximum = 65_536) {
             if (char === '{') {
                 offset++;
                 space();
-                const object = Object.create(null);
+                // Members are collected first and become own data properties of a null-prototype
+                // object in one step, so a name from the text is never used as a write target.
+                const members = [];
+                const names = new Set();
+                const object = () => Object.assign(Object.create(null), Object.fromEntries(members));
                 if (text[offset] === '}') {
                     offset++;
-                    return object;
+                    return object();
                 }
                 while (true) {
                     space();
                     if (text[offset] !== '"')
                         throw new Error();
                     const key = string();
-                    if (Object.hasOwn(object, key))
+                    if (names.has(key))
                         throw new Error();
+                    names.add(key);
                     space();
                     if (text[offset++] !== ':')
                         throw new Error();
-                    object[key] = value(depth + 1);
+                    members.push([key, value(depth + 1)]);
                     space();
                     if (text[offset] === '}') {
                         offset++;
-                        return object;
+                        return object();
                     }
                     if (text[offset++] !== ',')
                         throw new Error();

package/dist/cli-entry.d.ts

@@ -1,2 +1,13 @@
+/** Optional `neo4j` configuration keys passed to the store as its per-read limits. */
+export declare const STORE_LIMITS: readonly ['maxNodes', 'maxEdges', 'maxBytes'];
+export declare const PACKAGE_VERSION: string;
 /** npm's POSIX executable is a symlink. Node resolves it when loading the module. */
 export declare function isCliEntry(meta: ImportMeta): boolean;
+/** The specific safe code for a startup failure, and whether the usage line helps. */
+export declare function startupFailure(error: unknown): {
+    code: string;
+    hint: string;
+    usage: boolean;
+};
+/** Prints `MAP_START_FAILED <code>: <hint>` (and the usage for an argument error) and sets the exit code. */
+export declare function reportStartupFailure(error: unknown, usage: string): void;