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

package/dist/types.d.ts

@@ -0,0 +1,94 @@
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+export declare class MapQueryError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export interface ReadScope {
+    readonly subject: string;
+    readonly companyId: string;
+    readonly tenantIds: readonly string[];
+    readonly teamIds: readonly string[];
+    readonly allTeams: boolean;
+}
+export declare const MAP_LABELS: readonly ['GuardAgent', 'GuardDeployment', 'GuardTask', 'GuardPrincipal', 'GuardGrant', 'GuardTool', 'GuardResource', 'GuardResourceBinding', 'GuardExecutionBinding', 'GuardExternalResource', 'GuardExternalIdentity', 'GuardMcpConnection', 'GuardMcpOperation'];
+export type GuardLabel = typeof MAP_LABELS[number];
+export declare const MAP_RELATIONSHIPS: readonly ['G_INSTANCE_OF', 'G_ASSIGNED_TO', 'G_ACTS_AS', 'G_DELEGATED_FROM', 'G_DERIVED_FROM', 'G_HAS_GRANT', 'G_FOR_TOOL', 'G_TARGETS', 'G_BINDS_SELECTOR', 'G_MAPS_TO', 'G_EXECUTES_FOR', 'G_EXECUTES_TOOL', 'G_USES_IDENTITY', 'G_VIA_CONNECTION', 'G_EXPOSES_OPERATION', 'G_OPERATION_TOOL'];
+export type GuardRelation = typeof MAP_RELATIONSHIPS[number];
+export interface MapNode {
+    readonly id: string;
+    readonly entityId: string;
+    readonly label: GuardLabel;
+    readonly sourceId: string;
+    readonly projectionId: string;
+    readonly properties: JsonObject;
+}
+export interface MapEdge {
+    readonly source: string;
+    readonly target: string;
+    readonly kind: GuardRelation;
+}
+export interface MapCoverage {
+    readonly [component: string]: {
+        readonly status: string;
+        readonly observedAt?: string;
+    };
+}
+export interface MapPolicyCandidate {
+    readonly relationship: 'CAN_READ' | 'CAN_WRITE' | 'CAN_LIST';
+    readonly hasCondition: boolean;
+    readonly conditionKeys: readonly string[];
+    readonly resourceScope: 'bucket_summary';
+}
+export interface MapPolicyEvidence {
+    readonly taskId: string;
+    readonly deploymentId: string;
+    readonly executionBindingId: string;
+    readonly resourceBindingId: string;
+    readonly identityId: string | null;
+    readonly resourceId: string | null;
+    readonly action: string;
+    readonly status: 'complete' | 'unavailable' | 'not_collected';
+    readonly reason: 'no_candidate' | 'binding_ambiguous' | 'cloud_unresolved' | 'provider_missing' | 'collection_invalid' | 'stale' | 'changed' | 'boundary_unresolved' | 'unsupported_policy' | 'evidence_invalid' | 'unsupported_action' | 'identity_not_static' | 'unsupported_binding' | 'cloud_not_collected' | 'collection_missing' | 'disabled' | null;
+    readonly observedAt: string | null;
+    readonly assessment: 'unknown';
+    readonly candidates: readonly MapPolicyCandidate[];
+}
+export interface MapProjection {
+    readonly id: string;
+    readonly snapshotId: string;
+    readonly generatedAt: string;
+    readonly status: 'published';
+    readonly nodes: readonly MapNode[];
+    readonly edges: readonly MapEdge[];
+    readonly coverage: MapCoverage;
+    /** Current, independently checked policy evidence; omitted for summaries/history. */
+    readonly policyEvidence?: readonly MapPolicyEvidence[];
+}
+export interface MapSource {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly sourceId: string;
+    readonly profile: 'core' | 'host' | 'host-mcp';
+    readonly current: MapProjection;
+    readonly previous: MapProjection | null;
+}
+export interface MapView {
+    readonly sources: readonly MapSource[];
+}
+export interface MapReadRequest {
+    readonly sourceId?: string;
+    readonly agentId?: string;
+    readonly history?: boolean;
+    /** Agent/deployment index only; avoids loading task neighborhoods before selecting an agent. */
+    readonly summary?: boolean;
+}
+export interface MapStore {
+    read(scope: ReadScope, request?: MapReadRequest): Promise<MapView>;
+}
+export declare function mapIdentifier(value: unknown, code?: string): string;
+export declare function validateReadScope(value: unknown): ReadScope;

package/dist/types.js

@@ -0,0 +1,47 @@
+import { immutableJson } from '@shieldaai/agent-guard';
+export class MapQueryError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'MapQueryError';
+    }
+}
+export const MAP_LABELS = ['GuardAgent', 'GuardDeployment', 'GuardTask', 'GuardPrincipal', 'GuardGrant',
+    'GuardTool', 'GuardResource', 'GuardResourceBinding', 'GuardExecutionBinding', 'GuardExternalResource',
+    'GuardExternalIdentity', 'GuardMcpConnection', 'GuardMcpOperation'];
+export const MAP_RELATIONSHIPS = ['G_INSTANCE_OF', 'G_ASSIGNED_TO', 'G_ACTS_AS', 'G_DELEGATED_FROM',
+    'G_DERIVED_FROM', 'G_HAS_GRANT', 'G_FOR_TOOL', 'G_TARGETS', 'G_BINDS_SELECTOR', 'G_MAPS_TO',
+    'G_EXECUTES_FOR', 'G_EXECUTES_TOOL', 'G_USES_IDENTITY', 'G_VIA_CONNECTION', 'G_EXPOSES_OPERATION',
+    'G_OPERATION_TOOL'];
+export function mapIdentifier(value, code = 'MAP_REQUEST_INVALID') {
+    if (typeof value !== 'string' || !value.trim() || [...value].length > 4096 || value.includes('\0') ||
+        /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(value))
+        throw new MapQueryError(code);
+    return value;
+}
+export function validateReadScope(value) {
+    try {
+        const copied = immutableJson(value, 4, 1024, 64 * 1024);
+        if (!copied || Array.isArray(copied) || typeof copied !== 'object' ||
+            Object.keys(copied).sort().join(',') !== 'allTeams,companyId,subject,teamIds,tenantIds')
+            throw new Error();
+        mapIdentifier(copied.subject);
+        mapIdentifier(copied.companyId);
+        if (typeof copied.allTeams !== 'boolean')
+            throw new Error();
+        for (const key of ['tenantIds', 'teamIds']) {
+            const items = copied[key];
+            if (!Array.isArray(items) || items.length > 128 || (key === 'tenantIds' && items.length === 0) ||
+                new Set(items).size !== items.length)
+                throw new Error();
+            items.forEach(item => mapIdentifier(item));
+        }
+        if (!copied.allTeams && copied.teamIds.length === 0)
+            throw new Error();
+        return copied;
+    }
+    catch {
+        throw new MapQueryError('MAP_SCOPE_INVALID');
+    }
+}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@shieldaai/agent-map",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "agent-guard-map": "./dist/cli.js",
+    "agent-guard-map-identity": "./dist/identity-cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.4.0",
+    "@shieldaai/agent-guard": "0.1.0-alpha.3",
+    "neo4j-driver": "6.3.0",
+    "openid-client": "6.8.8"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShieldaAI/agent-guard.git",
+    "directory": "packages/agent-map"
+  },
+  "scripts": {
+    "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"
+  ]
+}