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

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 ShieldaAI contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,308 @@
-# Temporary Holding Version
+# Agent Guard reference map
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+[React/Cytoscape viewer](../../apps/agent-map/README.md). It never prepares or
+executes an action. Declared grants and cloud associations are not effective
+permission decisions.
+
+Install the service with `npm install @shieldaai/agent-map@alpha`. It includes the
+`agent-guard-map` and `agent-guard-map-identity` commands. Viewer assets and the
+Python collector are separate repository components and are not bundled in this
+npm package. The commands require host-owned configuration and credentials.
+
+## Run the loopback bearer service
+
+```sh
+npm ci --ignore-scripts
+npm run build
+node packages/agent-map/dist/cli.js --config deployment/cartography/reference.example.json
+```
+
+Review the example's company, tenant and team identifiers, Neo4j address and
+username before use. Provide `AGENT_MAP_NEO4J_PASSWORD` and
+`AGENT_MAP_READER_TOKEN` through your host's secret environment. Generate the
+reader token with `createMapToken()` and provision it through your trusted host;
+do not commit it or include it in a URL. The launcher prints only its loopback URL
+and mode. Open that URL and enter the reference token. The viewer keeps it in
+memory until disconnect/reload and never sends it to a different origin. The
+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
+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).
+
+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;
+later path replacements do not change the served assets. Starting an API without
+`viewerDirectory` does not require these file-open capabilities.
+
+`agm_v1` reference credentials are independent of executor/task and observer
+credentials. Each credential is mapped to an immutable `ReadScope` by the host:
+`subject`, `companyId`, `tenantIds`, `teamIds`, `allTeams`. Neither HTTP nor MCP
+arguments can override this scope. A team reader can see only agents explicitly
+assigned to an allowed team and their attached evidence. `allTeams: true` is a
+separate explicit grant, including unassigned/core inventory. It must not be
+inferred from an empty team list. Restart with a revised credential registry to
+rotate or revoke these bearer credentials.
+
+The server binds `127.0.0.1` only and requires an exact Host header. Browser
+requests must use its same origin. It provides no CORS, arbitrary Cypher,
+database credentials, execution tools or administration routes. For company
+browser access, use the separate HTTPS identity endpoint below. Do not expose
+the loopback listener directly through an unchecked proxy.
+
+Use a dedicated Neo4j reader account where database privileges are available.
+The driver's READ session mode is not a privilege boundary. Neo4j Community
+does not establish database-level team isolation; the service's fixed queries
+and scope checks enforce its reference interface. The database remains a
+trusted service accessible only to collector and query hosts. Remote database
+connections require verified TLS (`neo4j+s` or `bolt+s`). Unencrypted connections
+are accepted only with direct `bolt://` and a literal loopback address. Plaintext
+`neo4j://` routing is rejected because advertised peers can leave loopback.
+
+## Run the company HTTPS viewer
+
+The separate `agent-guard-map-identity` launcher serves the viewer and scoped
+queries over HTTPS with confidential OIDC sign-in. Follow the
+[identity deployment guide](../../deployment/cartography/IDENTITY.md) to register
+the provider, provision private configuration/TLS files and environment secrets,
+and adapt [identity.example.json](../../deployment/cartography/identity.example.json).
+After building and provisioning the private config:
+
+```sh
+node packages/agent-map/dist/identity-cli.js --config /absolute/private/identity.json
+```
+
+The installed package exposes the equivalent `agent-guard-map-identity` command.
+The provider must support authorization code flow with S256 PKCE and RS256 ID
+tokens. Each exact issuer `sub` has an explicit host-owned scope; provider groups
+and browser arguments cannot grant access. The endpoint owns TLS, requires exact
+Host/Origin, rejects forwarded identity/authorization headers and provides no
+CORS. It does not wrap or reconfigure the loopback service.
+
+The browser uses opaque Secure/HttpOnly cookies and CSRF-protected same-origin
+POSTs. It receives no provider tokens or scope claims. Sessions last at most 15
+minutes, capped by ID token expiry, and are not refreshed. Sign out ends the
+local session only; the IdP SSO session may remain active. Bindings, secrets and
+TLS files reload on restart, which invalidates all sessions. There is no
+distributed session store or HA mode. A registered live company IdP and a
+trusted-browser end-to-end check remain rollout gates; see the guide for their
+status and the complete configuration/operational limits.
+
+## Shared operations
+
+On the loopback service, POST `/v1/query` with `Authorization: Bearer <reference-token>`, content type
+`application/json` and `{ "operation": "list_agents", "args": {} }`.
+Results contain `operation`, `observedAt`, `data` and an optional focused `graph`.
+Source IDs are the graph source IDs returned by the service, not native source
+names. Native agent/task IDs and returned stable entity IDs are accepted where
+documented by the schemas. No pagination cursor exposes a broader scope.
+
+| Operation | Arguments | Evidence |
+| --- | --- | --- |
+| `list_agents` | optional `sourceId`, `search`, `ownerId`, `environment`, `limit` | Scoped inventory for choosing an agent. |
+| `get_agent_access` | `sourceId`, `agentId` | Focused deployments, tasks, grants, tools, bindings, MCP and cloud observations. |
+| `explain_access` | `sourceId`, `taskId`, `tool`, `resourceId` | Visible delegation, declared matches, known blockers and explicit unknown checks. |
+| `find_agents_with_access` | `resourceRef`, `action`; optional `sourceId`, `limit` | Potential candidates from exact host resource/action bindings; no wildcard or prefix expansion. |
+| `get_changes` | `sourceId`; optional `since` | Net current/previous changes to currently authorized agents; explicit gaps. |
+| `get_inventory_health` | optional `sourceId` | Visible capture times and independently stale or unavailable components. |
+
+Snapshot generation time and component observation times are separate. Tasks and
+tools retain their original capture times after host/MCP recomposition. MCP age
+uses the oldest capture or observation among visible connections; recomposing a
+cached observation does not refresh it. Missing observation times remain unknown
+and stale for observed connections. Unavailable connections use the time their
+failure was captured. Historical projections retain their own capture times.
+
+On the loopback service, POST `/mcp` uses the official MCP SDK's stateless HTTP transport. The six tools
+have the same arguments and use the same service as HTTP. Supply the reference
+bearer in the client's HTTP headers. The host-only `createMapMcpServer(service,
+scope)` factory also supports embedding; only trusted host code chooses scope.
+There are no subscriptions, arbitrary resources or mutation methods. MCP tool
+results contain the common JSON envelope as text; clients should treat all
+imported names and identifiers as data, never instructions.
+
+The company endpoint exposes the same `/v1/query` envelope with session cookies
+and `X-CSRF-Token`, and deliberately has no `/mcp` route. Bearer/MCP credentials
+and company browser sessions are separate authentication boundaries.
+
+## Host API
+
+### Current IAM policy evidence
+
+The existing HTTP/MCP operations also expose the collector's optional IAM policy
+candidate layer. `get_agent_access.data.policyEvidence` lists evidence for the
+selected agent. `explain_access.data.externalEvidence.policyEvidence` selects the
+exact task/tool/resource bindings; potential-access lookup further selects the
+requested action. Each result identifies its task, deployment, execution binding,
+resource binding and external endpoints by stable entity ID, with an independent
+policy observation time, status, reason and `assessment: unknown`.
+
+Only the three collected S3 mappings are supported. A complete record contains
+zero or one candidate with mapping name, condition flag/key names and
+`resourceScope: bucket_summary`. Empty candidates never prove denial. The original
+host resource ARN, kind and scope remain on the binding graph; a bucket summary
+does not authorize an exact object or prefix. Boundaries, unsupported policies,
+missing collection, opt-out and stale/changed evidence remain explicit gaps.
+
+The Neo4j reader derives pairs through a visible task's own deployment, declared
+grant, resource binding and execution tool. It validates the exact provider
+links, account ownership, scoped collection, membership and candidate provenance.
+It rechecks the bounded raw evidence and source pointers before returning;
+concurrent changes fail with a stable error instead of mixing observations.
+The reader returns no raw policies, condition values, collection-wide hashes,
+counts or unrelated provider neighbors. Generic Cartography `CAN_*` edges do not
+fill missing owned evidence.
+
+Policy age uses the tighter of the snapshot's enrolled cloud `maxAgeSeconds` and
+the host's `Neo4jMapStoreOptions.policyMaxAgeSeconds` (default 7,200; maximum
+86,400). A newer AWS capture makes old Guard provider joins unavailable until the
+next successful Guard collection. `get_inventory_health` reports policy coverage
+separately. `get_changes` returns `policyHistory: not_collected`: live candidates
+are not attached to historical inventory snapshots or used to invent policy diffs.
+
+The reader caps each request at 512 task/binding/action pairs and fails overflow
+without returning partial evidence. Fixed read queries, row/byte limits, the
+five-second transaction deadline and the existing response limits still apply.
+Custom `MapStore` implementations may omit `MapProjection.policyEvidence`; supplied
+records receive closed-shape and binding-path validation at the service boundary.
+Complete evidence requires one owning agent and unambiguous tool/identity/binding
+links, including unique task/grant and grant/selector pairs. Distinct valid grants
+and resource selectors remain supported; ambiguous evidence may be reported as
+unavailable with no candidates.
+This metadata never changes executor admission.
+
+Sources superseded through the host's [lifecycle command](../../deployment/cartography/SOURCE-LIFECYCLE.md)
+are excluded from normal reads, including explicit source requests and history.
+A read spanning supersession fails rather than returning its old view. The new
+enrollment generation has its own source identity; supersession does not rewrite
+the executor ledger or change agent permissions.
+
+This self-contained example demonstrates the public contract without requiring
+a database. For real inventory, replace the store with `createNeo4jMapStore` and
+close it when the host shuts down.
+
+```ts
+import { MapService, validateReadScope, type MapStore } from '@shieldaai/agent-map';
+
+const store: MapStore = { async read() { return { sources: [] }; } };
+const service = new MapService(store);
+const scope = validateReadScope({ subject: 'reader', companyId: 'example',
+  tenantIds: ['engineering'], teamIds: ['platform'], allTeams: false });
+const response = await service.query(scope, 'list_agents', {});
+console.log(response.data);
+```
+
+To embed the company endpoint, load TLS material and secrets in trusted host
+code. This self-contained function uses an empty store and is not invoked by the
+example. Replace its paths, registered issuer/client and subject binding before
+calling it; the host API requires an absolute viewer directory and loaded PEM
+strings. The CLI adds the private-file checks described in the deployment guide.
+
+```ts
+import { readFile } from 'node:fs/promises';
+import { MapService, startMapIdentityServer,
+  type MapIdentityServer, type MapStore } from '@shieldaai/agent-map';
+
+export async function startCompanyReference(clientSecret: string): Promise<MapIdentityServer> {
+  const store: MapStore = { async read() { return { sources: [] }; } };
+  return startMapIdentityServer({
+    service: new MapService(store),
+    publicOrigin: 'https://localhost:8788', listenHost: '127.0.0.1', port: 8788,
+    tls: {
+      key: await readFile('/absolute/private/tls/server-key.pem', 'utf8'),
+      cert: await readFile('/absolute/private/tls/server-chain.pem', 'utf8'),
+    },
+    oidc: {
+      issuer: 'https://login.example.invalid',
+      clientId: 'replace-with-registered-client-id', clientSecret,
+    },
+    companyId: 'example-company',
+    bindings: [{
+      subject: 'replace-with-exact-idp-sub',
+      scope: { subject: 'platform-reader', companyId: 'example-company',
+        tenantIds: ['engineering'], teamIds: ['platform'], allTeams: false },
+    }],
+    viewerDirectory: '/absolute/path/to/agent-guard/apps/agent-map/dist',
+  });
+}
+```
+
+`bindings[].subject` is the exact IdP `sub`; `scope.subject` is a local alias and
+can differ. The returned server exposes `replaceBindings`, `revokeSubject` and
+`invalidateSessions` only to host code. Each invalidates all current sessions
+and login transactions; revocation also removes that binding. Persist policy
+changes in the host before restarting. Call `close()` during shutdown and close
+any real Neo4j store. No HTTP administration endpoints are exposed.
+
+Custom `MapStore` implementations are trusted adapters and must implement the
+same visibility boundary as `Neo4jMapStore`; the service does not turn an
+unscoped store into a scoped one. The included store filters all node/edge
+queries before limits or materialization. Shared tools, principals, resources
+and MCP connections do not reveal other teams' attached entities. Historical
+membership is intersected with current authorized agent ownership, including
+task ownership, so moving an agent/task between teams cannot expose its old
+team's evidence. Hidden and nonexistent IDs return the same `MAP_NOT_FOUND`.
+Team responses omit source-wide revision counters and hidden ancestor/family
+identifiers. Explanations always retain a generic ancestor-scope uncertainty.
+
+## Limits and semantics
+
+Loopback defaults: 32 KiB HTTP request, 1 MiB service result (2 MiB transport ceiling),
+500 focused nodes/1,000 edges, 64 sources and 2,000 nodes/5,000 edges per store
+read, 5-second graph/service deadline, 10-second HTTP deadline, four concurrent
+HTTP requests and 120 requests/minute per credential plus a global quota.
+Streaming graph reads cap materialized nodes/edges at 4 MiB. Synchronous service
+processing shares the query deadline and has a 200,000-unit work budget; potential
+access evidence is limited to 1,000 entries and the cumulative response-byte
+budget. Configuration has hard upper bounds. Oversized authorized inventories fail
+closed instead of returning a misleading partial map. List operations return
+up to 100 rows and explicitly indicate truncation.
+
+The company endpoint has separate browser/provider limits, including a default
+600 requests/minute per session and globally. Its complete defaults and hard
+ceilings are in the [identity guide](../../deployment/cartography/IDENTITY.md).
+The MapService/store limits and evidence semantics below apply to both endpoints.
+
+The store uses fixed parameterized read-only templates in one transaction,
+allowlisted properties and relationships, bounded graph paths, and a publication
+pointer recheck. It never traverses into arbitrary provider policy data. A
+pointer change fails the query for retry rather than mixing generations.
+Current/previous comparisons are net differences, not an audit history; missing
+or retired previous evidence is explicit. Collection times and global revision
+changes alone are not entity changes. Health describes published inventory,
+not collector process health. Source-wide publication timing is visible to
+authorized readers of that source.
+
+Blockers describe exported gates at capture/evaluation time. A result without
+blockers remains `unknown`: live budgets, arguments, custom policy, approvals,
+delegation outside scope and backend authorization still require evaluation.
+Potential-access matches retain exact/prefix, static/dynamic, cloud freshness
+and MCP lifecycle limitations. The graph is never used in executor admission.
+
+## Validation
+
+```sh
+npm test
+npm run test:pack
+cd integrations/cartography
+.venv/bin/python scripts/test-disposable-neo4j.py -- -q
+```
+
+JavaScript checks cover schemas, immutable scope, query bounds, safe HTTP,
+official SDK HTTP/MCP equivalence, disposable HTTPS/OIDC exchange, cookie/CSRF
+and revocation boundaries, private launcher files and viewer lifecycle behavior.
+The packed-package check compiles both Host API examples and exercises the
+installed identity boundary. Disposable Neo4j checks
+exercise actual published graphs, cross-company/tenant/team isolation, shared
+MCP metadata, moved ownership, hidden IDs, current/previous visibility and
+absence of database mutations. Never run the integration suite against a
+shared or production database.

package/dist/assets.d.ts

@@ -0,0 +1,5 @@
+/** Load the fixed public assets once; never follow a replaced leaf or read beyond the cap. */
+export declare function loadMapAssets(directory: unknown): Promise<Map<string, {
+    body: Buffer;
+    mime: string;
+}>>;

package/dist/assets.js

@@ -0,0 +1,43 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { fail } 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();
+    if (directory === undefined)
+        return assets;
+    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']]) {
+        try {
+            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)
+                    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();
+            }
+        }
+        catch {
+            fail('MAP_CONFIG_INVALID');
+        }
+    }
+    return assets;
+}

package/dist/boundary.d.ts

@@ -0,0 +1,5 @@
+export declare function fail(code: string): never;
+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;