feat: implement envelope operation logging with cursor pagination (#764)

* feat: logs

* fix: coderabbit suggestions

* fix testests

* docs: add log docs

Author: coodos

docs/docs/Infrastructure/eVault.md

@@ -282,8 +282,63 @@ X-ENAME: @user-a.w3id
 }
 ```
 
+**Example**:
+```bash
+curl -X GET http://localhost:4000/whois \
+  -H "X-ENAME: @user-a.w3id"
+```
+
 **Use Case**: Platforms use this endpoint to retrieve public keys for signature verification.
 
+### /logs
+
+Get paginated envelope operation logs for an eName. Each log entry describes a create, update, delete, or update_envelope_value operation (metaEnvelope id, hash, operation type, platform, timestamp).
+
+**Request**:
+```http
+GET /logs HTTP/1.1
+Host: evault.example.com
+X-ENAME: @user-a.w3id
+```
+
+Optional query parameters:
+
+- `limit` — Page size (default 20, max 100).
+- `cursor` — Opaque cursor for the next page (returned as `nextCursor` in the response).
+
+**Response**:
+```json
+{
+    "logs": [
+        {
+            "id": "log-entry-id",
+            "eName": "@user-a.w3id",
+            "metaEnvelopeId": "meta-envelope-id",
+            "envelopeHash": "sha256-hex",
+            "operation": "create",
+            "platform": "https://platform.example.com",
+            "timestamp": "2025-02-04T12:00:00.000Z",
+            "ontology": "550e8400-e29b-41d4-a716-446655440001"
+        }
+    ],
+    "nextCursor": "2025-02-04T12:00:00.000Z|log-entry-id",
+    "hasMore": true
+}
+```
+
+**Example — first page**:
+```bash
+curl -X GET "http://localhost:4000/logs?limit=20" \
+  -H "X-ENAME: @user-a.w3id"
+```
+
+**Example — next page (using cursor)**:
+```bash
+curl -X GET "http://localhost:4000/logs?limit=20&cursor=2025-02-04T12:00:00.000Z%7Clog-entry-id" \
+  -H "X-ENAME: @user-a.w3id"
+```
+
+(Use the `nextCursor` value from the previous response; URL-encode the cursor if it contains special characters such as `|`.)
 
 ## Access Control
 

infrastructure/evault-core/src/core/db/db.service.spec.ts

@@ -562,4 +562,78 @@ describe("DbService (integration)", () => {
             ).rejects.toThrow("eName is required");
         });
     });
+
+    describe("Envelope operation logs", () => {
+        it("should append and retrieve envelope operation logs with pagination", async () => {
+            const result = await service.storeMetaEnvelope(
+                { ontology: "LogTest", payload: { x: 1 }, acl: ["*"] },
+                ["*"],
+                TEST_ENAME,
+            );
+            const metaId = result.metaEnvelope.id;
+            await service.appendEnvelopeOperationLog({
+                eName: TEST_ENAME,
+                metaEnvelopeId: metaId,
+                envelopeHash: "abc123",
+                operation: "create",
+                platform: "test-platform",
+                timestamp: new Date().toISOString(),
+                ontology: "LogTest",
+            });
+            const page1 = await service.getEnvelopeOperationLogs(TEST_ENAME, {
+                limit: 10,
+            });
+            expect(page1.logs.length).toBeGreaterThanOrEqual(1);
+            const log = page1.logs.find((l) => l.metaEnvelopeId === metaId);
+            expect(log).toBeDefined();
+            expect(log?.operation).toBe("create");
+            expect(log?.platform).toBe("test-platform");
+            expect(log?.envelopeHash).toBe("abc123");
+            expect(log?.ontology).toBe("LogTest");
+        });
+
+        it("should return getMetaEnvelopeIdByEnvelopeId for an envelope", async () => {
+            const result = await service.storeMetaEnvelope(
+                { ontology: "ResolveTest", payload: { key: "v" }, acl: ["*"] },
+                ["*"],
+                TEST_ENAME,
+            );
+            const envelopeId = result.envelopes[0].id;
+            const metaInfo = await service.getMetaEnvelopeIdByEnvelopeId(
+                envelopeId,
+                TEST_ENAME,
+            );
+            expect(metaInfo).not.toBeNull();
+            expect(metaInfo?.metaEnvelopeId).toBe(result.metaEnvelope.id);
+            expect(metaInfo?.ontology).toBe("ResolveTest");
+        });
+
+        it("should return null from getMetaEnvelopeIdByEnvelopeId for unknown envelope", async () => {
+            const metaInfo = await service.getMetaEnvelopeIdByEnvelopeId(
+                "nonexistent-id",
+                TEST_ENAME,
+            );
+            expect(metaInfo).toBeNull();
+        });
+
+        it("should support cursor-based pagination for logs", async () => {
+            const page1 = await service.getEnvelopeOperationLogs(TEST_ENAME, {
+                limit: 2,
+            });
+            if (page1.logs.length < 2 && !page1.hasMore) return;
+            if (page1.nextCursor) {
+                const page2 = await service.getEnvelopeOperationLogs(
+                    TEST_ENAME,
+                    { limit: 2, cursor: page1.nextCursor },
+                );
+                expect(page2.logs.length).toBeLessThanOrEqual(2);
+                expect(
+                    page2.logs.every(
+                        (l) =>
+                            !page1.logs.some((p) => p.id === l.id),
+                    ),
+                ).toBe(true);
+            }
+        });
+    });
 });

infrastructure/evault-core/src/core/db/db.service.ts

@@ -1,9 +1,12 @@
-import type { Driver } from "neo4j-driver";
+import neo4j, { type Driver } from "neo4j-driver";
 import { W3IDBuilder } from "w3id";
 import { deserializeValue, serializeValue } from "./schema";
 import type {
+    AppendEnvelopeOperationLogParams,
     Envelope,
+    EnvelopeOperationLogEntry,
     GetAllEnvelopesResult,
+    GetEnvelopeOperationLogsResult,
     MetaEnvelope,
     MetaEnvelopeResult,
     SearchMetaEnvelopesResult,
@@ -888,6 +891,155 @@ export class DbService {
         return count;
     }
 
+    /**
+     * Gets the metaEnvelope id and ontology for an envelope by envelope id.
+     * Used when logging updateEnvelopeValue (resolver only has envelopeId).
+     */
+    async getMetaEnvelopeIdByEnvelopeId(
+        envelopeId: string,
+        eName: string,
+    ): Promise<{ metaEnvelopeId: string; ontology: string } | null> {
+        if (!eName) {
+            throw new Error("eName is required");
+        }
+        const result = await this.runQueryInternal(
+            `
+            MATCH (m:MetaEnvelope { eName: $eName })-[:LINKS_TO]->(e:Envelope { id: $envelopeId })
+            RETURN m.id AS metaEnvelopeId, m.ontology AS ontology
+            `,
+            { envelopeId, eName },
+        );
+        const record = result.records[0];
+        if (!record) return null;
+        return {
+            metaEnvelopeId: record.get("metaEnvelopeId"),
+            ontology: record.get("ontology"),
+        };
+    }
+
+    /**
+     * Appends an envelope operation log entry (create, update, delete, update_envelope_value).
+     */
+    async appendEnvelopeOperationLog(
+        params: AppendEnvelopeOperationLogParams,
+    ): Promise<void> {
+        if (!params.eName) {
+            throw new Error("eName is required for envelope operation logs");
+        }
+        const logId = (await new W3IDBuilder().build()).id;
+        const platformValue =
+            params.platform !== null && params.platform !== undefined
+                ? params.platform
+                : null;
+        await this.runQueryInternal(
+            `
+            CREATE (l:EnvelopeOperationLog {
+                id: $id,
+                eName: $eName,
+                metaEnvelopeId: $metaEnvelopeId,
+                envelopeHash: $envelopeHash,
+                operation: $operation,
+                platform: $platform,
+                timestamp: $timestamp,
+                ontology: $ontology
+            })
+            `,
+            {
+                id: logId,
+                eName: params.eName,
+                metaEnvelopeId: params.metaEnvelopeId,
+                envelopeHash: params.envelopeHash,
+                operation: params.operation,
+                platform: platformValue,
+                timestamp: params.timestamp,
+                ontology: params.ontology ?? null,
+            },
+        );
+    }
+
+    /**
+     * Returns paginated envelope operation logs for an eName.
+     * Ordered by timestamp DESC, then id ASC for stable cursor pagination.
+     */
+    async getEnvelopeOperationLogs(
+        eName: string,
+        options: { limit: number; cursor?: string | null },
+    ): Promise<GetEnvelopeOperationLogsResult> {
+        if (!eName) {
+            throw new Error("eName is required for getting envelope operation logs");
+        }
+        const limit = Math.min(Math.max(1, options.limit || 20), 100);
+        const cursor = options.cursor ?? null;
+
+        // Fetch limit+1 to know if there's a next page. Cursor format: "timestamp|id" (| avoids colons in ISO timestamp).
+        const [cursorTs = "", cursorId = ""] = cursor
+            ? cursor.split("|")
+            : [];
+        const result = await this.runQueryInternal(
+            cursor
+                ? `
+            MATCH (l:EnvelopeOperationLog { eName: $eName })
+            WHERE (l.timestamp < $cursorTs) OR (l.timestamp = $cursorTs AND l.id > $cursorId)
+            WITH l
+            ORDER BY l.timestamp DESC, l.id ASC
+            LIMIT $limitPlusOne
+            RETURN l.id AS id, l.eName AS eName, l.metaEnvelopeId AS metaEnvelopeId,
+                   l.envelopeHash AS envelopeHash, l.operation AS operation,
+                   l.platform AS platform, l.timestamp AS timestamp, l.ontology AS ontology
+            `
+                : `
+            MATCH (l:EnvelopeOperationLog { eName: $eName })
+            WITH l
+            ORDER BY l.timestamp DESC, l.id ASC
+            LIMIT $limitPlusOne
+            RETURN l.id AS id, l.eName AS eName, l.metaEnvelopeId AS metaEnvelopeId,
+                   l.envelopeHash AS envelopeHash, l.operation AS operation,
+                   l.platform AS platform, l.timestamp AS timestamp, l.ontology AS ontology
+            `,
+            cursor
+                ? {
+                      eName,
+                      limitPlusOne: neo4j.int(limit + 1),
+                      cursorTs,
+                      cursorId,
+                  }
+                : { eName, limitPlusOne: neo4j.int(limit + 1) },
+        );
+
+        const rows = result.records.map((r) => ({
+            id: r.get("id"),
+            eName: r.get("eName"),
+            metaEnvelopeId: r.get("metaEnvelopeId"),
+            envelopeHash: r.get("envelopeHash"),
+            operation: r.get("operation"),
+            platform: r.get("platform"),
+            timestamp: r.get("timestamp"),
+            ontology: r.get("ontology"),
+        }));
+
+        const hasMore = rows.length > limit;
+        const logs = (hasMore ? rows.slice(0, limit) : rows).map(
+            (r): EnvelopeOperationLogEntry => ({
+                id: r.id,
+                eName: r.eName,
+                metaEnvelopeId: r.metaEnvelopeId,
+                envelopeHash: r.envelopeHash,
+                operation: r.operation,
+                platform: r.platform,
+                timestamp: r.timestamp,
+                ...(r.ontology != null && { ontology: r.ontology }),
+            }),
+        );
+
+        const last = logs[logs.length - 1];
+        const nextCursor =
+            hasMore && last
+                ? `${last.timestamp}|${last.id}`
+                : null;
+
+        return { logs, nextCursor, hasMore };
+    }
+
     /**
      * Closes the database connection.
      */

infrastructure/evault-core/src/core/db/envelope-hash.ts

@@ -0,0 +1,29 @@
+import * as crypto from "crypto";
+
+/**
+ * Computes a deterministic SHA-256 hash of envelope content for logging.
+ * Used for create/update (id + ontology + payload); for delete, pass only id.
+ */
+export function computeEnvelopeHash(payload: {
+    id?: string;
+    ontology: string;
+    payload?: Record<string, unknown>;
+}): string {
+    const obj = {
+        id: payload.id ?? "",
+        ontology: payload.ontology,
+        payload: payload.payload ?? {},
+    };
+    const canonical = JSON.stringify(obj);
+    return crypto.createHash("sha256").update(canonical).digest("hex");
+}
+
+/**
+ * Computes hash for delete operation (metaEnvelopeId only).
+ */
+export function computeEnvelopeHashForDelete(metaEnvelopeId: string): string {
+    return crypto
+        .createHash("sha256")
+        .update(JSON.stringify({ id: metaEnvelopeId }))
+        .digest("hex");
+}

infrastructure/evault-core/src/core/db/migrations/add-envelope-operation-log-index.ts

@@ -0,0 +1,34 @@
+/**
+ * Neo4j Migration: Add indexes for EnvelopeOperationLog
+ *
+ * Creates indexes on eName and timestamp for paginated log queries.
+ */
+
+import { Driver } from "neo4j-driver";
+
+export async function createEnvelopeOperationLogIndexes(
+    driver: Driver,
+): Promise<void> {
+    const session = driver.session();
+    try {
+        await session.run(
+            `CREATE INDEX envelope_operation_log_ename_index IF NOT EXISTS
+             FOR (l:EnvelopeOperationLog) ON (l.eName)`,
+        );
+        console.log("Created eName index on EnvelopeOperationLog nodes");
+        await session.run(
+            `CREATE INDEX envelope_operation_log_timestamp_index IF NOT EXISTS
+             FOR (l:EnvelopeOperationLog) ON (l.timestamp)`,
+        );
+        console.log("Created timestamp index on EnvelopeOperationLog nodes");
+    } catch (error) {
+        if (error instanceof Error && error.message.includes("already exists")) {
+            console.log("EnvelopeOperationLog indexes already exist");
+        } else {
+            console.error("Error creating EnvelopeOperationLog indexes:", error);
+            throw error;
+        }
+    } finally {
+        await session.close();
+    }
+}