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

package/README.md

@@ -1,5 +1,10 @@
 # Agent Guard reference map
 
+Query AI agent and MCP inventory, snapshot changes and access explanations over
+scoped HTTP and MCP interfaces. See the
+[package selection guide](https://github.com/ShieldaAI/agent-guard/blob/main/docs/package-guide.md)
+for tool authorization and model response validation.
+
 Optional read-only reference service for the immutable Agent Guard projections
 published by the [Cartography collector](../../integrations/cartography/README.md).
 It supplies the same evidence to HTTP, MCP clients and the
@@ -31,7 +36,7 @@ clearly labeled synthetic demo uses only browser-local fixture data.
 
 The launcher requires nonblocking file-open support, as provided by the pilot's
 POSIX hosts. Its configuration must resolve to a regular file of at most 128 KiB;
-symlinks to regular files remain supported. It checks the opened descriptor and
+symlinks to regular files remain supported. The file must belong to the service user or root, with group and other write access disabled. Protect the configuration path and its parent directories from replacement. It checks the opened descriptor and
 limits bytes read even if the file grows. Named pipes and other nonregular inputs
 fail startup with the same safe diagnostic. Native Windows is outside the
 [pilot's supported host profile](../../deployment/cartography/RUNBOOK.md#prerequisites-and-layout).
@@ -40,7 +45,7 @@ Viewer asset hosting on both HTTP and HTTPS also requires nonblocking and
 no-follow file-open support, as provided by the POSIX pilot hosts. The fixed
 `index.html`, `app.js` and `app.css` entries must each be regular files of at most
 4 MiB. The loader checks each opened descriptor, rejects a symlink replacing an
-asset, and bounds reads even if the file grows. It captures the bytes at startup;
+asset, and bounds reads even if the file grows. Assets must belong to the service user or root, with group and other write access disabled. Keep the entire asset path in trusted directories. It captures the bytes at startup;
 later path replacements do not change the served assets. Starting an API without
 `viewerDirectory` does not require these file-open capabilities.
 

package/dist/assets.js

@@ -1,7 +1,7 @@
 import { constants } from 'node:fs';
 import { open } from 'node:fs/promises';
 import { isAbsolute, join } from 'node:path';
-import { fail } from './boundary.js';
+import { fail, trustedHostFile } from './boundary.js';
 /** 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();
@@ -16,7 +16,7 @@ export async function loadMapAssets(directory) {
             const file = await open(join(directory, name), constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
             try {
                 const info = await file.stat();
-                if (!info.isFile() || info.size > maximum)
+                if (!trustedHostFile(info) || info.size > maximum)
                     fail('MAP_CONFIG_INVALID');
                 const data = Buffer.alloc(maximum + 1);
                 let bytes = 0;

package/dist/boundary.d.ts

@@ -1,4 +1,6 @@
+import type { Stats } from 'node:fs';
 export declare function fail(code: string): never;
+export declare function trustedHostFile(info: Stats): boolean;
 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. */

package/dist/boundary.js

@@ -1,5 +1,11 @@
 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)

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.js

@@ -3,12 +3,12 @@ import { constants } from 'node:fs';
 import { open } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { parseArgs } from 'node:util';
-import { pathToFileURL } from 'node:url';
+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 } from './boundary.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');
@@ -22,7 +22,7 @@ async function configBytes(path) {
     const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
     try {
         const info = await file.stat();
-        if (!info.isFile() || info.size > maximum)
+        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);
@@ -88,6 +88,6 @@ export async function runMapCli(argv = process.argv.slice(2)) {
         await store.close();
     }
 }
-if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+if (isCliEntry(import.meta)) {
     void runMapCli().catch(() => { process.stderr.write('MAP_START_FAILED\n'); process.exitCode = 1; });
 }

package/dist/identity-cli.js

@@ -3,7 +3,7 @@ import { constants } from 'node:fs';
 import { open } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
-import { pathToFileURL } from 'node:url';
+import { isCliEntry } from './cli-entry.js';
 import { createNeo4jMapStore } from './store.js';
 import { MapService } from './service.js';
 import { startMapIdentityServer } from './identity-http.js';
@@ -98,6 +98,6 @@ export async function runMapIdentityCli(argv = process.argv.slice(2)) {
         await store.close();
     }
 }
-if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+if (isCliEntry(import.meta)) {
     void runMapIdentityCli().catch(() => { process.stderr.write('MAP_START_FAILED\n'); process.exitCode = 1; });
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shieldaai/agent-map",
-  "version": "0.1.0-alpha.2",
-  "description": "Scoped read-only Agent Guard reference queries, HTTP and MCP service.",
+  "version": "0.1.0-alpha.3",
+  "description": "Read-only AI agent and MCP inventory queries over HTTP and MCP, with scoped access to Cartography projections.",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.4.0",
-    "@shieldaai/agent-guard": "0.1.0-alpha.2",
+    "@shieldaai/agent-guard": "0.1.0-alpha.3",
     "neo4j-driver": "6.3.0",
     "openid-client": "6.8.8"
   },
@@ -43,5 +43,19 @@
     "build": "tsc -p tsconfig.json",
     "prepack": "node ../../scripts/build.mjs",
     "prepublishOnly": "node ../../scripts/release-check.mjs"
-  }
+  },
+  "homepage": "https://github.com/ShieldaAI/agent-guard/tree/main/packages/agent-map#readme",
+  "bugs": {
+    "url": "https://github.com/ShieldaAI/agent-guard/issues"
+  },
+  "keywords": [
+    "ai-agents",
+    "agent-inventory",
+    "mcp",
+    "model-context-protocol",
+    "cartography",
+    "neo4j",
+    "typescript",
+    "access-explanations"
+  ]
 }