From be5f369f35a0a886aefc489b41100fe5413e61fe Mon Sep 17 00:00:00 2001
From: Volodymyr Vreshch <vreshch@gmail.com>
Date: Mon, 1 Dec 2025 23:21:37 +0100
Subject: [PATCH] feat: add SHA256 content hashing to agent registry

Add contentHash (SHA256) to agent versions to support agent.lock.json on the CLI side.

Changes:
- Add latestContentHash to AgentDocument and agents collection schema
- Add contentHash to AgentVersionDocument and agent_versions collection schema
- Add computeContentHash helper function using Node.js crypto module
- Compute and store SHA256 hash when publishing agents
- Include contentHash in API responses:
  - POST /api/agents returns contentHash in publish response
  - GET /api/agents/:owner/:name returns latestContentHash
  - GET /api/agents/:owner/:name versions array includes contentHash
  - GET /api/agents/:owner/:name/versions/:version returns contentHash

This enables:
- Integrity verification: Verify installed agents match registry content
- Lock file support: Track exact versions with cryptographic hashes
- Reproducible installs: Guarantee identical agent content across environments
---
 .../src/collections/agent-versions.collection.ts |  1 +
 .../backend/src/collections/agents.collection.ts |  1 +
 packages/backend/src/routes/agents/get-agent.ts  |  1 +
 packages/backend/src/routes/agents/publish.ts    |  1 +
 packages/backend/src/services/agent.service.ts   | 16 +++++++++++++++-
 .../backend/src/utils/agent-response.mapper.ts   |  2 ++
 packages/shared/src/types/agent.types.ts         |  5 +++++
 7 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/packages/backend/src/collections/agent-versions.collection.ts b/packages/backend/src/collections/agent-versions.collection.ts
index 848c3a6..8e79bba 100644
--- a/packages/backend/src/collections/agent-versions.collection.ts
+++ b/packages/backend/src/collections/agent-versions.collection.ts
@@ -22,6 +22,7 @@ export const agentVersionsCollectionSchema = z.object({
   agentId: z.string(),
   version: z.string().regex(/^\d+\.\d+\.\d+$/),
   content: z.string().max(100000),
+  contentHash: z.string().length(64), // SHA256 hex = 64 chars
   changelog: z.string().max(1000).optional(),
   isLatest: z.boolean(),
   downloads: z.number().int().min(0),
diff --git a/packages/backend/src/collections/agents.collection.ts b/packages/backend/src/collections/agents.collection.ts
index 89db8c4..21c652b 100644
--- a/packages/backend/src/collections/agents.collection.ts
+++ b/packages/backend/src/collections/agents.collection.ts
@@ -44,6 +44,7 @@ export const agentsCollectionSchema = z.object({
   readme: z.string().max(50000).optional(),
   latestVersion: z.string().regex(/^\d+\.\d+\.\d+$/),
   latestContent: z.string().max(100000),
+  latestContentHash: z.string().length(64), // SHA256 hex = 64 chars
   totalDownloads: z.number().int().min(0),
   stars: z.number().int().min(0),
   forks: z.number().int().min(0),
diff --git a/packages/backend/src/routes/agents/get-agent.ts b/packages/backend/src/routes/agents/get-agent.ts
index f34c4d3..d882432 100644
--- a/packages/backend/src/routes/agents/get-agent.ts
+++ b/packages/backend/src/routes/agents/get-agent.ts
@@ -40,6 +40,7 @@ export const getAgentHandler = (serviceProvider: ServiceProvider<AppServiceMap>)
       mappedAgent.versions = versions.map((v) => ({
         version: v.version,
         agentVersion: v.agentVersion,
+        contentHash: v.contentHash,
         publishedAt: v.publishedAt.toISOString(),
         downloads: v.downloads,
         isLatest: v.isLatest,
diff --git a/packages/backend/src/routes/agents/publish.ts b/packages/backend/src/routes/agents/publish.ts
index 604c217..a71a4dc 100644
--- a/packages/backend/src/routes/agents/publish.ts
+++ b/packages/backend/src/routes/agents/publish.ts
@@ -41,6 +41,7 @@ export const publishAgentHandler = (serviceProvider: ServiceProvider<AppServiceM
           name: agent.name,
           owner: agent.ownerUsername,
           version: agent.latestVersion,
+          contentHash: agent.latestContentHash,
           visibility: agent.visibility,
           publishedAt: agent.updatedAt.toISOString(),
         },
diff --git a/packages/backend/src/services/agent.service.ts b/packages/backend/src/services/agent.service.ts
index 715caab..018cb20 100644
--- a/packages/backend/src/services/agent.service.ts
+++ b/packages/backend/src/services/agent.service.ts
@@ -7,11 +7,18 @@ import type {
   UpdateAgentMetadataRequest,
 } from '@agentage/shared';
 import { isMarkdownWithFrontmatter, parseAgentMarkdown } from '@agentage/shared';
-import { randomUUID } from 'crypto';
+import { createHash, randomUUID } from 'crypto';
 import * as semver from 'semver';
 import type { LoggerService, Service } from './app.services';
 import type { TypedDb } from './typed-db';
 
+/**
+ * Compute SHA256 hash of content
+ */
+function computeContentHash(content: string): string {
+  return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
 export interface ListAgentsFilter {
   page: number;
   limit: number;
@@ -140,6 +147,9 @@ export function createAgentService(db: TypedDb, logger: LoggerService): AgentSer
         owner: user._id,
       });
 
+      // Compute content hash
+      const contentHash = computeContentHash(data.content);
+
       if (existingAgent) {
         // Publishing new version - verify version is greater
         if (!semver.gt(data.version, existingAgent.latestVersion)) {
@@ -170,6 +180,7 @@ export function createAgentService(db: TypedDb, logger: LoggerService): AgentSer
           agentId: existingAgent._id,
           version: data.version,
           content: data.content,
+          contentHash,
           contentType,
           agentVersion,
           tools,
@@ -188,6 +199,7 @@ export function createAgentService(db: TypedDb, logger: LoggerService): AgentSer
             $set: {
               latestVersion: data.version,
               latestContent: data.content,
+              latestContentHash: contentHash,
               contentType,
               agentVersion,
               tools,
@@ -228,6 +240,7 @@ export function createAgentService(db: TypedDb, logger: LoggerService): AgentSer
           readme: data.readme,
           latestVersion: data.version,
           latestContent: data.content,
+          latestContentHash: contentHash,
           totalDownloads: 0,
           stars: 0,
           forks: 0,
@@ -243,6 +256,7 @@ export function createAgentService(db: TypedDb, logger: LoggerService): AgentSer
           agentId: agentId,
           version: data.version,
           content: data.content,
+          contentHash,
           contentType,
           agentVersion,
           tools,
diff --git a/packages/backend/src/utils/agent-response.mapper.ts b/packages/backend/src/utils/agent-response.mapper.ts
index f0a9910..a278f50 100644
--- a/packages/backend/src/utils/agent-response.mapper.ts
+++ b/packages/backend/src/utils/agent-response.mapper.ts
@@ -31,6 +31,7 @@ export function mapAgentToDetailResponse(agent: AgentDocument): AgentDetailUiRes
     ...mapAgentToListResponse(agent),
     readme: agent.readme,
     latestContent: agent.latestContent,
+    latestContentHash: agent.latestContentHash,
     mcpServers: agent.mcpServers,
     sections: agent.sections,
     versions: [], // Populated separately
@@ -43,6 +44,7 @@ export function mapAgentVersionToResponse(version: AgentVersionDocument): AgentV
     agentVersion: version.agentVersion,
     contentType: version.contentType,
     content: version.content,
+    contentHash: version.contentHash,
     tools: version.tools,
     mcpServers: version.mcpServers,
     sections: version.sections,
diff --git a/packages/shared/src/types/agent.types.ts b/packages/shared/src/types/agent.types.ts
index 3cf14a4..5bf0b40 100644
--- a/packages/shared/src/types/agent.types.ts
+++ b/packages/shared/src/types/agent.types.ts
@@ -76,6 +76,7 @@ export interface AgentDocument {
   // Latest version (denormalized for performance)
   latestVersion: string;
   latestContent: string;
+  latestContentHash: string; // SHA256 hash of latestContent
 
   // Statistics
   totalDownloads: number;
@@ -94,6 +95,7 @@ export interface AgentVersionDocument {
   version: string;
   contentType: 'markdown' | 'plain';
   content: string;
+  contentHash: string; // SHA256 hash of content
   changelog?: string;
 
   // Frontmatter data
@@ -232,11 +234,13 @@ export interface AgentUiResponse {
 export interface AgentDetailUiResponse extends AgentUiResponse {
   readme?: string;
   latestContent: string;
+  latestContentHash: string;
   mcpServers?: AgentMcpServers;
   sections?: AgentSection[];
   versions: {
     version: string;
     agentVersion?: string;
+    contentHash: string;
     publishedAt: string;
     downloads: number;
     isLatest: boolean;
@@ -248,6 +252,7 @@ export interface AgentVersionUiResponse {
   agentVersion?: string;
   contentType: 'markdown' | 'plain';
   content: string;
+  contentHash: string;
   tools?: string[];
   mcpServers?: AgentMcpServers;
   sections?: AgentSection[];