@utaba/deep-memory-storage-cosmosdb 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -32,6 +32,16 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
     private readonly config;
     private readonly compiler;
     constructor(config: CosmosDbProviderConfig);
+    /**
+     * Reject any repositoryId that is not a valid v4 UUID.
+     *
+     * Every partition-scoped query filters on repositoryId. Since repositoryId is
+     * the CosmosDB partition key, a predicate with a different value would target
+     * a different partition. Strict format validation at the provider boundary
+     * prevents injection (e.g. strings containing quotes or Gremlin syntax) from
+     * ever reaching query construction.
+     */
+    private assertValidRepositoryId;
     initialize(): Promise<void>;
     dispose(): Promise<void>;
     ensureSchema(): Promise<EnsureSchemaResult>;
@@ -74,7 +84,28 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
     exportAll(repositoryId: string): AsyncIterable<ExportChunk>;
     importBulk(repositoryId: string, data: ImportChunk[], options?: BulkImportOptions): Promise<BulkImportResult>;
     getCapabilities(): GraphTraversalCapabilities;
-    traverse(repositoryId: string, spec: TraversalSpec, compiledQuery?: string): Promise<TraversalResult>;
+    traverse(repositoryId: string, spec: TraversalSpec): Promise<TraversalResult>;
+    /**
+     * Execute a raw Gremlin query with caller-supplied bindings.
+     *
+     * ⚠️  ELEVATED PRIVILEGE — SYSTEM-LEVEL OPERATION ⚠️
+     *
+     * This method is an unscoped pass-through: it does not filter by repository,
+     * does not inject the partition key, and performs no validation on the query
+     * string. A single call can read or mutate any vertex or edge in the
+     * container regardless of which repository (partition) it belongs to.
+     *
+     * DO NOT expose this method to AI agents, end users, or any untrusted caller.
+     * It is intended for:
+     *   - administrative tooling (migrations, diagnostics, repairs)
+     *   - internal library operations that need cross-partition reach
+     *
+     * `repositoryId` is accepted for interface symmetry but is intentionally
+     * ignored here — the caller is trusted to scope the query themselves.
+     *
+     * For agent-facing graph queries use {@link traverse}, which enforces the
+     * repositoryId partition predicate.
+     */
     executeNativeQuery(_repositoryId: string, query: string, params?: Record<string, unknown>): Promise<TraversalResult>;
 }
 

package/dist/index.d.ts

@@ -32,6 +32,16 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
     private readonly config;
     private readonly compiler;
     constructor(config: CosmosDbProviderConfig);
+    /**
+     * Reject any repositoryId that is not a valid v4 UUID.
+     *
+     * Every partition-scoped query filters on repositoryId. Since repositoryId is
+     * the CosmosDB partition key, a predicate with a different value would target
+     * a different partition. Strict format validation at the provider boundary
+     * prevents injection (e.g. strings containing quotes or Gremlin syntax) from
+     * ever reaching query construction.
+     */
+    private assertValidRepositoryId;
     initialize(): Promise<void>;
     dispose(): Promise<void>;
     ensureSchema(): Promise<EnsureSchemaResult>;
@@ -74,7 +84,28 @@ declare class CosmosDbProvider implements StorageProvider, GraphTraversalProvide
     exportAll(repositoryId: string): AsyncIterable<ExportChunk>;
     importBulk(repositoryId: string, data: ImportChunk[], options?: BulkImportOptions): Promise<BulkImportResult>;
     getCapabilities(): GraphTraversalCapabilities;
-    traverse(repositoryId: string, spec: TraversalSpec, compiledQuery?: string): Promise<TraversalResult>;
+    traverse(repositoryId: string, spec: TraversalSpec): Promise<TraversalResult>;
+    /**
+     * Execute a raw Gremlin query with caller-supplied bindings.
+     *
+     * ⚠️  ELEVATED PRIVILEGE — SYSTEM-LEVEL OPERATION ⚠️
+     *
+     * This method is an unscoped pass-through: it does not filter by repository,
+     * does not inject the partition key, and performs no validation on the query
+     * string. A single call can read or mutate any vertex or edge in the
+     * container regardless of which repository (partition) it belongs to.
+     *
+     * DO NOT expose this method to AI agents, end users, or any untrusted caller.
+     * It is intended for:
+     *   - administrative tooling (migrations, diagnostics, repairs)
+     *   - internal library operations that need cross-partition reach
+     *
+     * `repositoryId` is accepted for interface symmetry but is intentionally
+     * ignored here — the caller is trusted to scope the query themselves.
+     *
+     * For agent-facing graph queries use {@link traverse}, which enforces the
+     * repositoryId partition predicate.
+     */
     executeNativeQuery(_repositoryId: string, query: string, params?: Record<string, unknown>): Promise<TraversalResult>;
 }
 

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/CosmosDbProvider.ts
 import crypto from "crypto";
-import { GremlinCompiler, ProviderError } from "@utaba/deep-memory";
+import { GremlinCompiler, ProviderError, InvalidInputError, isValidUuid, projectEntity } from "@utaba/deep-memory";
 
 // src/CosmosDbConnection.ts
 import gremlin from "gremlin";
@@ -1282,6 +1282,23 @@ var CosmosDbProvider = class {
       rejectUnauthorized: config.rejectUnauthorized
     });
   }
+  /**
+   * Reject any repositoryId that is not a valid v4 UUID.
+   *
+   * Every partition-scoped query filters on repositoryId. Since repositoryId is
+   * the CosmosDB partition key, a predicate with a different value would target
+   * a different partition. Strict format validation at the provider boundary
+   * prevents injection (e.g. strings containing quotes or Gremlin syntax) from
+   * ever reaching query construction.
+   */
+  assertValidRepositoryId(repositoryId) {
+    if (!isValidUuid(repositoryId)) {
+      throw new InvalidInputError(
+        "repositoryId",
+        `repositoryId must be a valid v4 UUID; got '${repositoryId}'`
+      );
+    }
+  }
   // ─── Lifecycle ─────────────────────────────────────────────────────
   async initialize() {
     await this.conn.connect();
@@ -1367,93 +1384,120 @@ var CosmosDbProvider = class {
   }
   // ─── Repository ────────────────────────────────────────────────────
   async createRepository(config) {
+    this.assertValidRepositoryId(config.repositoryId);
     return createRepository(this.conn, config);
   }
   async getRepository(repositoryId) {
+    this.assertValidRepositoryId(repositoryId);
     return getRepository(this.conn, repositoryId);
   }
   async listRepositories(filter) {
     return listRepositories(this.conn, filter);
   }
   async updateRepository(repositoryId, updates) {
+    this.assertValidRepositoryId(repositoryId);
     return updateRepository(this.conn, repositoryId, updates);
   }
   async deleteRepository(repositoryId, onProgress) {
+    this.assertValidRepositoryId(repositoryId);
     return deleteRepository(this.conn, repositoryId, onProgress);
   }
   async deleteAllContents(repositoryId, onProgress) {
+    this.assertValidRepositoryId(repositoryId);
     return deleteAllContents(this.conn, repositoryId, onProgress);
   }
   async getRepositoryStats(repositoryId) {
+    this.assertValidRepositoryId(repositoryId);
     return getRepositoryStats(this.conn, repositoryId);
   }
   // ─── Vocabulary ────────────────────────────────────────────────────
   async getVocabulary(repositoryId) {
+    this.assertValidRepositoryId(repositoryId);
     return getVocabulary(this.conn, repositoryId);
   }
   async saveVocabulary(repositoryId, vocabulary) {
+    this.assertValidRepositoryId(repositoryId);
     return saveVocabulary(this.conn, repositoryId, vocabulary);
   }
   async getVocabularyChangeLog(repositoryId, options) {
+    this.assertValidRepositoryId(repositoryId);
     return getVocabularyChangeLog(this.conn, repositoryId, options);
   }
   // ─── Entities ──────────────────────────────────────────────────────
   async createEntity(repositoryId, entity) {
+    this.assertValidRepositoryId(repositoryId);
     return createEntity(this.conn, repositoryId, entity);
   }
   async getEntity(repositoryId, entityId) {
+    this.assertValidRepositoryId(repositoryId);
     return getEntity(this.conn, repositoryId, entityId);
   }
   async getEntityBySlug(repositoryId, slug) {
+    this.assertValidRepositoryId(repositoryId);
     return getEntityBySlug(this.conn, repositoryId, slug);
   }
   async getEntities(repositoryId, entityIds) {
+    this.assertValidRepositoryId(repositoryId);
     return getEntities(this.conn, repositoryId, entityIds);
   }
   async updateEntity(repositoryId, entityId, updates) {
+    this.assertValidRepositoryId(repositoryId);
     return updateEntity(this.conn, repositoryId, entityId, updates);
   }
   async deleteEntity(repositoryId, entityId) {
+    this.assertValidRepositoryId(repositoryId);
     return deleteEntity(this.conn, repositoryId, entityId);
   }
   async deleteEntitiesByType(repositoryId, entityType) {
+    this.assertValidRepositoryId(repositoryId);
     return deleteEntitiesByType(this.conn, repositoryId, entityType);
   }
   async findEntities(repositoryId, query) {
+    this.assertValidRepositoryId(repositoryId);
     return findEntities(this.conn, repositoryId, query);
   }
   // ─── Relationships ─────────────────────────────────────────────────
   async createRelationship(repositoryId, relationship) {
+    this.assertValidRepositoryId(repositoryId);
     return createRelationship(this.conn, repositoryId, relationship);
   }
   async getRelationship(repositoryId, relationshipId) {
+    this.assertValidRepositoryId(repositoryId);
     return getRelationship(this.conn, repositoryId, relationshipId);
   }
   async getEntityRelationships(repositoryId, entityId, options) {
+    this.assertValidRepositoryId(repositoryId);
     return getEntityRelationships(this.conn, repositoryId, entityId, options);
   }
   async deleteRelationship(repositoryId, relationshipId) {
+    this.assertValidRepositoryId(repositoryId);
     return deleteRelationship(this.conn, repositoryId, relationshipId);
   }
   async deleteRelationshipsByType(repositoryId, relationshipType) {
+    this.assertValidRepositoryId(repositoryId);
     return deleteRelationshipsByType(this.conn, repositoryId, relationshipType);
   }
   // ─── Graph Traversal (StorageProvider) ─────────────────────────────
   async exploreNeighborhood(repositoryId, entityId, options) {
+    this.assertValidRepositoryId(repositoryId);
     return exploreNeighborhood(this.conn, repositoryId, entityId, options);
   }
   async findPaths(repositoryId, sourceId, targetId, options) {
+    this.assertValidRepositoryId(repositoryId);
     return findPaths(this.conn, repositoryId, sourceId, targetId, options);
   }
   // ─── Timeline ──────────────────────────────────────────────────────
   async getTimeline(repositoryId, entityId, options) {
+    this.assertValidRepositoryId(repositoryId);
     return getTimeline(this.conn, repositoryId, entityId, options);
   }
   // ─── Bulk Operations ───────────────────────────────────────────────
   exportAll(repositoryId) {
+    this.assertValidRepositoryId(repositoryId);
     return exportAll(this.conn, repositoryId);
   }
   async importBulk(repositoryId, data, options) {
+    this.assertValidRepositoryId(repositoryId);
     return importBulk(this.conn, repositoryId, data, options);
   }
   // ─── GraphTraversalProvider ────────────────────────────────────────
@@ -1470,17 +1514,20 @@ var CosmosDbProvider = class {
       supportsRelationshipSummary: false
     };
   }
-  async traverse(repositoryId, spec, compiledQuery) {
+  async traverse(repositoryId, spec) {
+    this.assertValidRepositoryId(repositoryId);
     const startTime = Date.now();
     const vocabulary = await this.getVocabulary(repositoryId);
-    const compiled = compiledQuery ? { query: compiledQuery, params: {}, estimatedFanOut: 100 } : this.compiler.compile(spec, vocabulary);
+    const compiled = this.compiler.compile(spec, vocabulary);
     const scopedQuery = compiled.query.replace(
       "g.V()",
-      `g.V().has('repositoryId', '${repositoryId}')`
+      "g.V().has('repositoryId', pRid)"
     );
+    const scopedParams = { ...compiled.params, pRid: repositoryId };
     try {
-      const result = await this.conn.submit(scopedQuery, compiled.params);
+      const result = await this.conn.submit(scopedQuery, scopedParams);
       const executionTimeMs = Date.now() - startTime;
+      const detailLevel = spec.detailLevel ?? "summary";
       const entities = [];
       const relationships = [];
       const paths = [];
@@ -1492,7 +1539,8 @@ var CosmosDbProvider = class {
             for (const obj of pathData.objects) {
               const props = obj;
               if (props["entityType"]) {
-                pathEntities.push(entityFromGremlin(props));
+                const stored = entityFromGremlin(props);
+                pathEntities.push(projectEntity(stored, detailLevel));
               }
             }
             if (pathEntities.length > 0) {
@@ -1506,8 +1554,8 @@ var CosmosDbProvider = class {
         }
       } else {
         for (const item of result.items) {
-          const entity = entityFromGremlin(item);
-          entities.push(entity);
+          const stored = entityFromGremlin(item);
+          entities.push(projectEntity(stored, detailLevel));
         }
       }
       const limit = spec.limit ?? 50;
@@ -1539,6 +1587,27 @@ var CosmosDbProvider = class {
       );
     }
   }
+  /**
+   * Execute a raw Gremlin query with caller-supplied bindings.
+   *
+   * ⚠️  ELEVATED PRIVILEGE — SYSTEM-LEVEL OPERATION ⚠️
+   *
+   * This method is an unscoped pass-through: it does not filter by repository,
+   * does not inject the partition key, and performs no validation on the query
+   * string. A single call can read or mutate any vertex or edge in the
+   * container regardless of which repository (partition) it belongs to.
+   *
+   * DO NOT expose this method to AI agents, end users, or any untrusted caller.
+   * It is intended for:
+   *   - administrative tooling (migrations, diagnostics, repairs)
+   *   - internal library operations that need cross-partition reach
+   *
+   * `repositoryId` is accepted for interface symmetry but is intentionally
+   * ignored here — the caller is trusted to scope the query themselves.
+   *
+   * For agent-facing graph queries use {@link traverse}, which enforces the
+   * repositoryId partition predicate.
+   */
   async executeNativeQuery(_repositoryId, query, params) {
     const startTime = Date.now();
     try {