@shieldaai/agent-map 0.0.0-stage → 0.1.0-alpha.3

package/dist/boundary.js

@@ -0,0 +1,123 @@
+import { MapQueryError } from './types.js';
+export function fail(code) { throw new MapQueryError(code); }
+// 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;
+}
+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)
+        fail('MAP_CONFIG_INVALID');
+    const result = Object.create(null);
+    for (const key of Object.getOwnPropertyNames(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!allowed.includes(key) || !descriptor.enumerable || !('value' in descriptor))
+            fail('MAP_CONFIG_INVALID');
+        result[key] = descriptor.value;
+    }
+    if (required.some(key => !Object.hasOwn(result, key)))
+        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)
+        fail('MAP_REQUEST_TOO_LARGE');
+    try {
+        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 string = () => {
+            const start = offset++;
+            while (offset < text.length) {
+                const char = text[offset++];
+                if (char === '\\')
+                    offset++;
+                else if (char === '"')
+                    return JSON.parse(text.slice(start, offset));
+            }
+            throw new Error();
+        };
+        const value = (depth) => {
+            if (++nodes > 2048 || depth > 12)
+                throw new Error();
+            space();
+            const char = text[offset];
+            if (char === '"')
+                return string();
+            if (char === '{') {
+                offset++;
+                space();
+                const object = Object.create(null);
+                if (text[offset] === '}') {
+                    offset++;
+                    return object;
+                }
+                while (true) {
+                    space();
+                    if (text[offset] !== '"')
+                        throw new Error();
+                    const key = string();
+                    if (Object.hasOwn(object, key))
+                        throw new Error();
+                    space();
+                    if (text[offset++] !== ':')
+                        throw new Error();
+                    object[key] = value(depth + 1);
+                    space();
+                    if (text[offset] === '}') {
+                        offset++;
+                        return object;
+                    }
+                    if (text[offset++] !== ',')
+                        throw new Error();
+                }
+            }
+            if (char === '[') {
+                offset++;
+                space();
+                const array = [];
+                if (text[offset] === ']') {
+                    offset++;
+                    return array;
+                }
+                while (true) {
+                    array.push(value(depth + 1));
+                    space();
+                    if (text[offset] === ']') {
+                        offset++;
+                        return array;
+                    }
+                    if (text[offset++] !== ',')
+                        throw new Error();
+                }
+            }
+            const token = /^(?:null|true|false|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)/.exec(text.slice(offset))?.[0];
+            if (token === undefined)
+                throw new Error();
+            offset += token.length;
+            const parsed = JSON.parse(token);
+            if (typeof parsed === 'number' && !Number.isFinite(parsed))
+                throw new Error();
+            return parsed;
+        };
+        const parsed = value(0);
+        space();
+        if (offset !== text.length)
+            throw new Error();
+        return parsed;
+    }
+    catch {
+        return fail('MAP_REQUEST_INVALID');
+    }
+}

package/dist/cli-entry.d.ts

@@ -0,0 +1,2 @@
+/** npm's POSIX executable is a symlink. Node resolves it when loading the module. */
+export declare function isCliEntry(meta: ImportMeta): boolean;

package/dist/cli-entry.js

@@ -0,0 +1,18 @@
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+/** npm's POSIX executable is a symlink. Node resolves it when loading the module. */
+export function isCliEntry(meta) {
+    if (typeof meta.main === 'boolean')
+        return meta.main;
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        // Older supported Node versions do not expose import.meta.main.
+        return pathToFileURL(realpathSync(entry)).href === meta.url;
+    }
+    catch {
+        // Imports from eval/stdin can supply an argv value that is not a file.
+        return false;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+/** Credential values stay in the environment and are never printed by this launcher. */
+export declare function runMapCli(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { isCliEntry } from './cli-entry.js';
+import { createNeo4jMapStore } from './store.js';
+import { MapService } from './service.js';
+import { startMapServer } from './http.js';
+import { validateReadScope } from './types.js';
+import { fields, fail, integer, parseRequest, trustedHostFile } from './boundary.js';
+function environmentName(value) {
+    if (typeof value !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(value))
+        fail('MAP_CONFIG_INVALID');
+    return value;
+}
+/** Keep the type check and bounded read on one nonblocking descriptor. */
+async function configBytes(path) {
+    if (typeof constants.O_NONBLOCK !== 'number')
+        fail('MAP_CONFIG_INVALID');
+    const maximum = 128 * 1024;
+    const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    try {
+        const info = await file.stat();
+        if (!trustedHostFile(info) || info.size > maximum)
+            fail('MAP_CONFIG_INVALID');
+        // The file may grow after stat; never use an unbounded readFile here.
+        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');
+        return data.subarray(0, bytes);
+    }
+    finally {
+        await file.close();
+    }
+}
+/** Credential values stay in the environment and are never printed by this launcher. */
+export async function runMapCli(argv = process.argv.slice(2)) {
+    const { values } = parseArgs({ args: argv, options: { config: { type: 'string' }, help: { type: 'boolean' } }, strict: true });
+    if (values.help) {
+        process.stdout.write('agent-guard-map --config HOST_CONFIG.json\n');
+        return;
+    }
+    if (!values.config)
+        fail('MAP_CONFIG_INVALID');
+    const path = resolve(values.config);
+    const config = fields(parseRequest(await configBytes(path), 128 * 1024), ['neo4j', 'credentials', 'port', 'viewerDirectory'], ['neo4j', 'credentials']);
+    const database = fields(config.neo4j, ['uri', 'username', 'passwordEnv', 'database'], ['uri', 'username', 'passwordEnv']);
+    if (typeof database.uri !== 'string' || typeof database.username !== 'string' ||
+        (database.database !== undefined && typeof database.database !== 'string'))
+        fail('MAP_CONFIG_INVALID');
+    const password = process.env[environmentName(database.passwordEnv)];
+    if (!password)
+        fail('MAP_CREDENTIAL_REQUIRED');
+    if (!Array.isArray(config.credentials) || config.credentials.length < 1 || config.credentials.length > 128)
+        fail('MAP_CONFIG_INVALID');
+    const credentials = config.credentials.map(value => {
+        const entry = fields(value, ['tokenEnv', 'scope'], ['tokenEnv', 'scope']);
+        const token = process.env[environmentName(entry.tokenEnv)];
+        if (!token)
+            fail('MAP_CREDENTIAL_REQUIRED');
+        return { token, scope: validateReadScope(entry.scope) };
+    });
+    if (config.viewerDirectory !== undefined && typeof config.viewerDirectory !== 'string')
+        fail('MAP_CONFIG_INVALID');
+    const store = createNeo4jMapStore({ uri: database.uri, username: database.username, password,
+        ...(database.database === undefined ? {} : { database: database.database }) });
+    try {
+        const server = await startMapServer({ service: new MapService(store), credentials,
+            port: integer(config.port, 8789, 0, 65535),
+            ...(config.viewerDirectory === undefined ? {} : { viewerDirectory: resolve(config.viewerDirectory) }) });
+        process.stdout.write(`${JSON.stringify({ url: server.url, mode: 'read-only' })}\n`);
+        await new Promise(done => {
+            const stop = () => { process.off('SIGINT', stop); process.off('SIGTERM', stop); done(); };
+            process.once('SIGINT', stop);
+            process.once('SIGTERM', stop);
+        });
+        await server.close();
+    }
+    finally {
+        await store.close();
+    }
+}
+if (isCliEntry(import.meta)) {
+    void runMapCli().catch(() => { process.stderr.write('MAP_START_FAILED\n'); process.exitCode = 1; });
+}

package/dist/http.d.ts

@@ -0,0 +1,28 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { MapService } from './service.js';
+import { type ReadScope } from './types.js';
+export interface MapCredential {
+    readonly token: string;
+    readonly scope: ReadScope;
+}
+export interface MapServerOptions {
+    service: MapService;
+    credentials: readonly MapCredential[];
+    viewerDirectory?: string;
+    port?: number;
+    maxRequestBytes?: number;
+    maxResponseBytes?: number;
+    requestTimeoutMs?: number;
+    maxConcurrentRequests?: number;
+    rateLimit?: {
+        maxRequests: number;
+        windowMs: number;
+    };
+}
+export declare function createMapToken(): string;
+/** Loopback pilot server. Remote serving requires a trusted, verified TLS reverse proxy. */
+export declare function startMapServer(options: MapServerOptions): Promise<{
+    server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
+    url: string;
+    close(): Promise<void>;
+}>;

package/dist/http.js

@@ -0,0 +1,233 @@
+import { createServer } from 'node:http';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { immutableJson } from '@shieldaai/agent-guard';
+import { MapService } from './service.js';
+import { validateReadScope } from './types.js';
+import { createMapMcpHandler } from './mcp.js';
+import { fail, fields, integer, parseRequest } from './boundary.js';
+import { headers, errorResponse, safeError, count, consume, readBody } from './transport.js';
+import { loadMapAssets } from './assets.js';
+const TOKEN = /^agm_v1\.[A-Za-z0-9_-]{43}$/;
+const hash = (text) => createHash('sha256').update(text).digest();
+export function createMapToken() { return `agm_v1.${randomBytes(32).toString('base64url')}`; }
+/** Loopback pilot server. Remote serving requires a trusted, verified TLS reverse proxy. */
+export async function startMapServer(options) {
+    const config = fields(options, ['service', 'credentials', 'viewerDirectory', 'port', 'maxRequestBytes',
+        'maxResponseBytes', 'requestTimeoutMs', 'maxConcurrentRequests', 'rateLimit'], ['service', 'credentials']);
+    if (!(config.service instanceof MapService))
+        fail('MAP_CONFIG_INVALID');
+    const service = config.service;
+    const port = integer(config.port, 0, 0, 65535);
+    const requestLimit = integer(config.maxRequestBytes, 32_768, 128, 65_536);
+    const responseLimit = integer(config.maxResponseBytes, 2 * 1024 * 1024, 128, 2 * 1024 * 1024);
+    const timeout = integer(config.requestTimeoutMs, 10_000, 10, 30_000);
+    const concurrency = integer(config.maxConcurrentRequests, 4, 1, 32);
+    const rate = config.rateLimit === undefined ? {} : fields(config.rateLimit, ['maxRequests', 'windowMs'], ['maxRequests', 'windowMs']);
+    const maxRequests = integer(rate.maxRequests, 120, 1, 10_000), windowMs = integer(rate.windowMs, 60_000, 10, 60_000);
+    let copied;
+    try {
+        copied = immutableJson(config.credentials, 8, 100_000, 1024 * 1024);
+    }
+    catch {
+        fail('MAP_CONFIG_INVALID');
+    }
+    if (!Array.isArray(copied) || copied.length === 0 || copied.length > 128)
+        fail('MAP_CONFIG_INVALID');
+    const seen = new Set();
+    const credentials = copied.map(value => {
+        const entry = fields(value, ['token', 'scope'], ['token', 'scope']);
+        if (typeof entry.token !== 'string' || !TOKEN.test(entry.token) || seen.has(entry.token))
+            fail('MAP_CONFIG_INVALID');
+        seen.add(entry.token);
+        const scope = validateReadScope(entry.scope);
+        return { digest: hash(entry.token), scope, bucket: { since: performance.now(), count: 0 } };
+    });
+    seen.clear();
+    const assets = await loadMapAssets(config.viewerDirectory);
+    const sockets = new Set();
+    const aborts = new Set();
+    const socketTimers = new WeakMap();
+    let active = 0, closing = false, host = '';
+    const globalBucket = { since: performance.now(), count: 0 };
+    const server = createServer({ maxHeaderSize: 8192, headersTimeout: timeout, requestTimeout: timeout, keepAliveTimeout: 1 }, (request, response) => { void handle(request, response); });
+    server.maxConnections = 64;
+    server.maxHeadersCount = 0;
+    async function handle(request, response) {
+        request.on('error', () => { });
+        response.on('error', () => { });
+        // Once headers arrive, leave a short bounded flush window after the request
+        // deadline. A connection timer at the same instant would erase the 408.
+        clearTimeout(socketTimers.get(request.socket));
+        const socketTimer = setTimeout(() => request.socket.destroy(), timeout + 250);
+        socketTimer.unref();
+        socketTimers.set(request.socket, socketTimer);
+        const started = performance.now();
+        const abort = new AbortController();
+        let admitted = false;
+        let timer;
+        const check = () => { if (abort.signal.aborted || performance.now() - started > timeout)
+            fail('MAP_TIMEOUT'); };
+        try {
+            consume(globalBucket, Math.min(maxRequests * credentials.length, 10_000), windowMs);
+            if (closing || active >= concurrency)
+                fail('MAP_BUSY');
+            active++;
+            admitted = true;
+            aborts.add(abort);
+            timer = setTimeout(() => { abort.abort(); errorResponse(response, 'MAP_TIMEOUT'); }, timeout);
+            timer.unref();
+            if (count(request, 'host') !== 1 || request.headers.host !== host || request.headers['proxy-authorization'] !== undefined)
+                fail('MAP_REQUEST_DENIED');
+            const origin = request.headers.origin;
+            if (count(request, 'origin') > 1 || (origin !== undefined && origin !== `http://${host}`) ||
+                (request.headers['sec-fetch-site'] !== undefined && !['same-origin', 'none'].includes(request.headers['sec-fetch-site'])))
+                fail('MAP_REQUEST_DENIED');
+            const path = request.url === '/' ? '/index.html' : request.url ?? '';
+            if (request.method === 'GET' && path === '/auth/session') {
+                const body = Buffer.from(JSON.stringify({ mode: 'bearer' }));
+                headers(response, body.length);
+                response.writeHead(200);
+                response.end(body);
+                return;
+            }
+            const asset = assets.get(path);
+            if (request.method === 'GET' && asset) {
+                headers(response, asset.body.length, asset.mime);
+                response.writeHead(200);
+                response.end(asset.body);
+                return;
+            }
+            if (request.method !== 'POST' || !['/v1/query', '/mcp'].includes(path))
+                fail('MAP_REQUEST_DENIED');
+            if (count(request, 'authorization') !== 1)
+                fail('MAP_UNAUTHENTICATED');
+            const authorization = request.headers.authorization;
+            if (!authorization?.startsWith('Bearer ') || !TOKEN.test(authorization.slice(7)))
+                fail('MAP_UNAUTHENTICATED');
+            const digest = hash(authorization.slice(7));
+            let credential;
+            for (const item of credentials)
+                if (timingSafeEqual(item.digest, digest))
+                    credential = item;
+            digest.fill(0);
+            if (!credential)
+                fail('MAP_UNAUTHENTICATED');
+            consume(credential.bucket, maxRequests, windowMs);
+            if (count(request, 'content-type') !== 1 || !/^application\/json(?:\s*;\s*charset=utf-8)?$/i.test(request.headers['content-type'] ?? '') ||
+                count(request, 'content-length') > 1 || count(request, 'transfer-encoding') > 1 || request.headers['content-encoding'] !== undefined)
+                fail('MAP_REQUEST_INVALID');
+            const length = request.headers['content-length'];
+            if (length !== undefined && (!/^\d+$/.test(length) || !Number.isSafeInteger(Number(length))))
+                fail('MAP_REQUEST_INVALID');
+            if (length !== undefined && Number(length) > requestLimit)
+                fail('MAP_REQUEST_TOO_LARGE');
+            const bytes = await readBody(request, requestLimit, abort.signal);
+            check();
+            const parsed = parseRequest(bytes, requestLimit);
+            let output;
+            let status = 200;
+            let mime = 'application/json';
+            if (path === '/v1/query') {
+                let envelope;
+                try {
+                    envelope = fields(parsed, ['operation', 'args'], ['operation', 'args']);
+                }
+                catch {
+                    fail('MAP_REQUEST_INVALID');
+                }
+                const result = await service.query(credential.scope, envelope.operation, envelope.args);
+                check();
+                output = Buffer.from(JSON.stringify(result));
+            }
+            else {
+                if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                    fail('MAP_REQUEST_INVALID');
+                const method = parsed.method;
+                if (typeof method !== 'string' || !['initialize', 'notifications/initialized', 'server/discover', 'tools/list', 'tools/call', 'ping'].includes(method))
+                    fail('MAP_REQUEST_DENIED');
+                const handler = createMapMcpHandler(service, credential.scope);
+                try {
+                    const forwarded = new Headers({ 'content-type': 'application/json', accept: 'application/json, text/event-stream' });
+                    for (const name of ['mcp-protocol-version', 'mcp-session-id']) {
+                        if (count(request, name) > 1)
+                            fail('MAP_REQUEST_INVALID');
+                        const value = request.headers[name];
+                        if (typeof value === 'string')
+                            forwarded.set(name, value);
+                    }
+                    const result = await handler.fetch(new Request(`http://${host}/mcp`, { method: 'POST', headers: forwarded,
+                        body: JSON.stringify(parsed), signal: abort.signal }), { parsedBody: parsed });
+                    const reader = result.body?.getReader();
+                    const chunks = [];
+                    let size = 0;
+                    if (reader) {
+                        try {
+                            while (true) {
+                                const { value, done } = await reader.read();
+                                check();
+                                if (done)
+                                    break;
+                                size += value.byteLength;
+                                if (size > responseLimit)
+                                    fail('MAP_RESPONSE_TOO_LARGE');
+                                chunks.push(value);
+                            }
+                        }
+                        finally {
+                            await reader.cancel().catch(() => { });
+                        }
+                    }
+                    output = Buffer.concat(chunks);
+                    status = result.status;
+                    mime = result.headers.get('content-type') ?? 'application/json';
+                }
+                finally {
+                    await handler.close();
+                }
+            }
+            check();
+            if (output.length > responseLimit)
+                fail('MAP_RESPONSE_TOO_LARGE');
+            headers(response, output.length, mime);
+            response.writeHead(status);
+            response.end(output);
+        }
+        catch (error) {
+            errorResponse(response, safeError(error));
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            aborts.delete(abort);
+            if (admitted)
+                active--;
+        }
+    }
+    server.on('connection', socket => {
+        sockets.add(socket);
+        const timer = setTimeout(() => socket.destroy(), timeout);
+        timer.unref();
+        socketTimers.set(socket, timer);
+        socket.once('close', () => { sockets.delete(socket); clearTimeout(socketTimers.get(socket)); });
+    });
+    server.on('checkContinue', (request, response) => { void handle(request, response); });
+    server.on('checkExpectation', (_request, response) => errorResponse(response, 'MAP_REQUEST_DENIED'));
+    server.on('connect', (_request, socket) => socket.destroy());
+    server.on('upgrade', (_request, socket) => socket.destroy());
+    server.on('clientError', (_error, socket) => socket.destroy());
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', () => { server.off('error', reject); resolve(); }); });
+    const address = server.address();
+    if (!address || typeof address === 'string')
+        fail('MAP_UNAVAILABLE');
+    host = `127.0.0.1:${address.port}`;
+    return { server, url: `http://${host}`, async close() {
+            if (closing)
+                return;
+            closing = true;
+            for (const abort of aborts)
+                abort.abort();
+            for (const socket of sockets)
+                socket.destroy();
+            await new Promise(resolve => server.close(() => resolve()));
+        } };
+}

package/dist/identity-cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { createNeo4jMapStore } from './store.js';
+import { type MapIdentityServerOptions } from './identity-http.js';
+export declare function loadMapIdentityConfig(filename: string): Promise<{
+    server: Omit<MapIdentityServerOptions, 'service'>;
+    database: Parameters<typeof createNeo4jMapStore>[0];
+}>;
+/** Restart reloads policy/secrets and invalidates sessions; credentials are never printed. */
+export declare function runMapIdentityCli(argv?: string[]): Promise<void>;

package/dist/identity-cli.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { isCliEntry } from './cli-entry.js';
+import { createNeo4jMapStore } from './store.js';
+import { MapService } from './service.js';
+import { startMapIdentityServer } from './identity-http.js';
+import { fields, fail, parseRequest } from './boundary.js';
+function environment(value) {
+    if (typeof value !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(value))
+        fail('MAP_CONFIG_INVALID');
+    const secret = process.env[value];
+    if (!secret || Buffer.byteLength(secret) > 65_536)
+        fail('MAP_CREDENTIAL_REQUIRED');
+    return secret;
+}
+/** POSIX launcher: owned regular files only; private inputs exclude group/other access. */
+async function boundedFile(path, maximum, privateFile) {
+    if (typeof process.getuid !== 'function' || !constants.O_NOFOLLOW)
+        fail('MAP_CONFIG_INVALID');
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const info = await file.stat();
+        if (!info.isFile() || info.nlink !== 1 || info.uid !== process.getuid() || info.size > maximum ||
+            (privateFile && (info.mode & 0o077) !== 0) || (info.mode & 0o022) !== 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');
+        return new TextDecoder('utf-8', { fatal: true }).decode(data.subarray(0, bytes));
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function loadMapIdentityConfig(filename) {
+    const path = resolve(filename), directory = dirname(path);
+    const config = fields(parseRequest(Buffer.from(await boundedFile(path, 128 * 1024, true)), 128 * 1024), ['neo4j', 'publicOrigin', 'tls', 'oidc', 'companyId', 'bindings', 'listenHost', 'port', 'viewerDirectory',
+        'sessionTtlMs', 'loginTtlMs', 'maxSessions', 'maxLoginTransactions', 'requestTimeoutMs', 'maxRequestBytes',
+        'maxResponseBytes', 'maxConcurrentRequests', 'rateLimit'], ['neo4j', 'publicOrigin', 'tls', 'oidc', 'companyId', 'bindings']);
+    const db = fields(config.neo4j, ['uri', 'username', 'passwordEnv', 'database'], ['uri', 'username', 'passwordEnv']);
+    if (typeof db.uri !== 'string' || typeof db.username !== 'string' || (db.database !== undefined && typeof db.database !== 'string'))
+        fail('MAP_CONFIG_INVALID');
+    const database = { uri: db.uri, username: db.username, password: environment(db.passwordEnv), ...(db.database === undefined ? {} : { database: db.database }) };
+    const tls = fields(config.tls, ['keyFile', 'certFile'], ['keyFile', 'certFile']);
+    const oidc = fields(config.oidc, ['issuer', 'clientId', 'clientSecretEnv', 'clientAuthMethod', 'endpointOrigins', 'caFile', 'requestTimeoutMs', 'maxResponseBytes'], ['issuer', 'clientId', 'clientSecretEnv']);
+    for (const value of [tls.keyFile, tls.certFile])
+        if (typeof value !== 'string' || !value)
+            fail('MAP_CONFIG_INVALID');
+    if (oidc.caFile !== undefined && (typeof oidc.caFile !== 'string' || !oidc.caFile))
+        fail('MAP_CONFIG_INVALID');
+    if (config.viewerDirectory !== undefined && typeof config.viewerDirectory !== 'string')
+        fail('MAP_CONFIG_INVALID');
+    const { neo4j: _database, tls: _tls, oidc: _oidc, ...server } = config;
+    const { clientSecretEnv: _secret, caFile: _ca, ...provider } = oidc;
+    return { database, server: { ...server,
+            tls: { key: await boundedFile(resolve(directory, tls.keyFile), 256 * 1024, true),
+                cert: await boundedFile(resolve(directory, tls.certFile), 256 * 1024, false) },
+            oidc: { ...provider, clientSecret: environment(oidc.clientSecretEnv),
+                ...(oidc.caFile === undefined ? {} : { ca: await boundedFile(resolve(directory, oidc.caFile), 256 * 1024, false) }) },
+            ...(config.viewerDirectory === undefined ? {} : { viewerDirectory: resolve(directory, config.viewerDirectory) }), } };
+}
+/** Restart reloads policy/secrets and invalidates sessions; credentials are never printed. */
+export async function runMapIdentityCli(argv = process.argv.slice(2)) {
+    const { values } = parseArgs({ args: argv, options: { config: { type: 'string' }, help: { type: 'boolean' } }, strict: true });
+    if (values.help) {
+        process.stdout.write('agent-guard-map-identity --config PRIVATE_HOST_CONFIG.json\n');
+        return;
+    }
+    if (!values.config)
+        fail('MAP_CONFIG_INVALID');
+    const config = await loadMapIdentityConfig(values.config);
+    const store = createNeo4jMapStore(config.database);
+    try {
+        const server = await startMapIdentityServer({ ...config.server, service: new MapService(store) });
+        try {
+            process.stdout.write(`${JSON.stringify({ url: server.url, mode: 'oidc-read-only' })}\n`);
+            await new Promise(done => {
+                const stop = () => { process.off('SIGINT', stop); process.off('SIGTERM', stop); done(); };
+                process.once('SIGINT', stop);
+                process.once('SIGTERM', stop);
+            });
+        }
+        finally {
+            await server.close();
+        }
+    }
+    finally {
+        await store.close();
+    }
+}
+if (isCliEntry(import.meta)) {
+    void runMapIdentityCli().catch(() => { process.stderr.write('MAP_START_FAILED\n'); process.exitCode = 1; });
+}

package/dist/identity-http.d.ts

@@ -0,0 +1,44 @@
+import { type Server } from 'node:https';
+import { MapService } from './service.js';
+import { type ReadScope } from './types.js';
+import { type MapOidcOptions } from './oidc.js';
+export interface MapIdentityBinding {
+    readonly subject: string;
+    readonly scope: ReadScope;
+}
+export interface MapIdentityServerOptions {
+    service: MapService;
+    publicOrigin: string;
+    tls: {
+        readonly key: string;
+        readonly cert: string;
+    };
+    oidc: Omit<MapOidcOptions, 'redirectUri'>;
+    companyId: string;
+    bindings: readonly MapIdentityBinding[];
+    listenHost?: string;
+    port?: number;
+    viewerDirectory?: string;
+    sessionTtlMs?: number;
+    loginTtlMs?: number;
+    maxSessions?: number;
+    maxLoginTransactions?: number;
+    requestTimeoutMs?: number;
+    maxRequestBytes?: number;
+    maxResponseBytes?: number;
+    maxConcurrentRequests?: number;
+    rateLimit?: {
+        maxRequests: number;
+        windowMs: number;
+    };
+}
+export interface MapIdentityServer {
+    readonly server: Server;
+    readonly url: string;
+    close(): Promise<void>;
+    replaceBindings(bindings: readonly MapIdentityBinding[]): void;
+    revokeSubject(subject: string): void;
+    invalidateSessions(): void;
+}
+/** Dedicated HTTPS browser boundary. It calls the scoped service directly and trusts no proxy identity headers. */
+export declare function startMapIdentityServer(options: MapIdentityServerOptions): Promise<MapIdentityServer>;