feat(sdk-core): implement deterministic rKey generation for activity claims

Author: s-adamantine

.changeset/wise-papayas-sing.md

@@ -0,0 +1,5 @@
+---
+"@hypercerts-org/sdk-core": minor
+---
+
+feat: implement pre-generation of rKeys for activity claims using deterministic content hashing (SHA-256).

packages/sdk-core/src/lib/crypto.ts

@@ -0,0 +1,69 @@
+/**
+ * Crypto utilities for the SDK.
+ */
+
+import { NetworkError } from "../core/errors.js";
+
+/**
+ * Deterministically stringifies an object by sorting keys recursively.
+ * Handles deeply nested objects and null values correctly.
+ */
+function stableStringify(obj: unknown): string | undefined {
+    if (obj === undefined || typeof obj === "function" || typeof obj === "symbol") {
+        return undefined;
+    }
+    if (obj === null || typeof obj !== "object") {
+        return JSON.stringify(obj);
+    }
+
+    if (Array.isArray(obj)) {
+        return JSON.stringify(obj.map((item) => {
+            const val = stableStringify(item);
+            return val === undefined ? null : JSON.parse(val);
+        }));
+    }
+
+    const sortedKeys = Object.keys(obj as object).sort();
+    const sortedObj: Record<string, unknown> = {};
+
+    for (const key of sortedKeys) {
+        const value = (obj as Record<string, unknown>)[key];
+        const str = stableStringify(value);
+        // Skip undefined or non-serializable values
+        if (str === undefined) continue;
+        sortedObj[key] = JSON.parse(str);
+    }
+
+    return JSON.stringify(sortedObj);
+}
+
+/**
+ * Computes the SHA-256 hash of a JSON-serializable object.
+ * Returns the hash as a hexadecimal string.
+ *
+ * @param content - The content to hash (will be JSON serialized)
+ * @returns The SHA-256 hash of the content
+ */
+export async function sha256Hash(content: unknown): Promise<string> {
+    // Use stable stringification to ensure deterministic output
+    const jsonString = stableStringify(content) ?? "";
+    const msgBuffer = new TextEncoder().encode(jsonString);
+
+    if (typeof crypto !== "undefined" && crypto.subtle) {
+        // Browser / Modern Node.js
+        const hashBuffer = await crypto.subtle.digest("SHA-256", msgBuffer);
+        const hashArray = Array.from(new Uint8Array(hashBuffer));
+        return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+    } else {
+        // Fallback for older environments or specific setups if global crypto isn't available
+        try {
+            // Dynamic import to avoid breaking browser builds if bundler doesn't handle it
+             
+            const { createHash } = await import("node:crypto");
+            const hash = createHash("sha256").update(jsonString).digest("hex");
+            return hash;
+        } catch (e) {
+            throw new NetworkError("SHA-256 hashing not supported in this environment", e);
+        }
+    }
+}

packages/sdk-core/src/repository/HypercertOperationsImpl.ts

@@ -44,6 +44,7 @@ import type {
 } from "./interfaces.js";
 import type { CreateResult, ListParams, PaginatedList, ProgressStep, UpdateResult } from "./types.js";
 import { $Typed } from "@atproto/api";
+import { sha256Hash } from "../lib/crypto.js";
 
 /**
  * Implementation of high-level hypercert operations.
@@ -288,10 +289,29 @@ export class HypercertOperationsImpl extends EventEmitter<HypercertEvents> imple
       throw new ValidationError(`Invalid hypercert record: ${hypercertValidation.error?.message}`);
     }
 
+    // Generate rKey from stable content hash (idempotency)
+    // We hash the user's intent (params + rights definition), not the volatile outputs (like new rights CID or createdAt)
+
+    // Destructure to remove non-hashable/redundant fields (image, onProgress)
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { image, onProgress: _onProgress, ...paramsForHash } = params;
+
+    const hashInput = {
+      ...paramsForHash,
+      // Use the full image blob reference for identity (handled by stable stringify)
+      imageRecord: imageBlobRef,
+      // Ensure rights definition is part of identity, but not the new CID
+      rightsData: typeof params.rights === "object" ? params.rights : undefined,
+    };
+
+    const contentHash = await sha256Hash(hashInput);
+    const rkey = `hc2:${contentHash}`;
+
     const hypercertResult = await this.agent.com.atproto.repo.createRecord({
       repo: this.repoDid,
       collection: HYPERCERT_COLLECTIONS.CLAIM,
       record: hypercertRecord,
+      rkey,
     });
 
     if (!hypercertResult.success) {