@andamio/core 0.1.0

package/dist/utils/hashing/index.d.mts

@@ -0,0 +1,276 @@
+/**
+ * SLT Hash Utility
+ *
+ * Computes the module token name (hash) from a list of Student Learning Targets (SLTs).
+ * This hash is used as the token name when minting module tokens on-chain.
+ *
+ * The algorithm matches the on-chain Plutus validator:
+ * ```haskell
+ * sltsToBbs MintModuleV2{slts} = blake2b_256 $ serialiseData $ toBuiltinData $ map stringToBuiltinByteString slts
+ * ```
+ *
+ * Serialization format:
+ * 1. Convert each SLT string to UTF-8 bytes
+ * 2. Encode as CBOR indefinite-length array of byte strings
+ * 3. Hash with Blake2b-256 (32 bytes / 256 bits)
+ *
+ * @module @andamio/core/hashing
+ */
+/**
+ * Compute the module hash matching Plutus on-chain encoding.
+ *
+ * Plutus's `stringToBuiltinByteString` chunks byte strings at 64 bytes.
+ * This function replicates that behavior:
+ * - Strings <= 64 bytes: encoded as regular CBOR byte strings
+ * - Strings > 64 bytes: encoded as indefinite-length chunked byte strings
+ *
+ * @param slts - Array of Student Learning Target strings
+ * @returns 64-character hex string (256-bit Blake2b hash)
+ *
+ * @example
+ * ```typescript
+ * import { computeSltHash } from "@andamio/core/hashing";
+ *
+ * const slts = [
+ *   "I can mint an access token.",
+ *   "I can complete an assignment to earn a credential."
+ * ];
+ *
+ * const moduleHash = computeSltHash(slts);
+ * // Returns: "8dcbe1b925d87e6c547bbd8071c23a712db4c32751454b0948f8c846e9246b5c"
+ * ```
+ */
+declare function computeSltHash(slts: string[]): string;
+/**
+ * @deprecated Use `computeSltHash` instead. This alias is kept for backwards compatibility.
+ */
+declare const computeSltHashDefinite: typeof computeSltHash;
+/**
+ * Verify that a given hash matches the computed hash for SLTs.
+ *
+ * @param slts - Array of Student Learning Target strings
+ * @param expectedHash - The hash to verify (64-character hex string)
+ * @returns true if the computed hash matches the expected hash
+ */
+declare function verifySltHash(slts: string[], expectedHash: string): boolean;
+/**
+ * Validate that a string is a valid SLT hash format.
+ *
+ * SLT hashes are 64-character hexadecimal strings (256-bit Blake2b hash).
+ *
+ * @param hash - String to validate
+ * @returns true if the string is a valid SLT hash format
+ */
+declare function isValidSltHash(hash: string): boolean;
+
+/**
+ * Task Hash Utility
+ *
+ * Computes the task token name (hash) from task data.
+ * This hash is used as the task_hash on-chain (content-addressed identifier).
+ *
+ * The algorithm matches the on-chain Plutus validator serialization.
+ *
+ * @module @andamio/core/hashing
+ */
+/**
+ * Native asset in ListValue format: [policyId.tokenName, quantity]
+ */
+type NativeAsset = [string, number];
+/**
+ * Task data structure matching the Atlas TX API ManageTasksTxRequest
+ *
+ * Fields must be arranged in this specific order for hashing:
+ * 1. project_content (string, max 140 chars)
+ * 2. expiration_time (number, Unix timestamp in milliseconds)
+ * 3. lovelace_amount (number)
+ * 4. native_assets (array of [asset_class, quantity] tuples)
+ */
+interface TaskData {
+    project_content: string;
+    expiration_time: number;
+    lovelace_amount: number;
+    native_assets: NativeAsset[];
+}
+/**
+ * Compute the task hash (token name / task_hash) from task data.
+ *
+ * This produces the same hash as the on-chain Plutus validator, allowing
+ * clients to pre-compute or verify task hashes.
+ *
+ * @param task - Task data object
+ * @returns 64-character hex string (256-bit Blake2b hash)
+ *
+ * @example
+ * ```typescript
+ * import { computeTaskHash } from "@andamio/core/hashing";
+ *
+ * const task = {
+ *   project_content: "Open Task #1",
+ *   expiration_time: 1769027280000,
+ *   lovelace_amount: 15000000,
+ *   native_assets: []
+ * };
+ *
+ * const taskHash = computeTaskHash(task);
+ * // Returns the on-chain task_hash
+ * ```
+ */
+declare function computeTaskHash(task: TaskData): string;
+/**
+ * Verify that a given hash matches the computed hash for a task.
+ *
+ * @param task - Task data object
+ * @param expectedHash - The hash to verify (64-character hex string)
+ * @returns true if the computed hash matches the expected hash
+ */
+declare function verifyTaskHash(task: TaskData, expectedHash: string): boolean;
+/**
+ * Validate that a string is a valid task hash format.
+ *
+ * Task hashes are 64-character hexadecimal strings (256-bit Blake2b hash).
+ */
+declare function isValidTaskHash(hash: string): boolean;
+/**
+ * Debug function to show the CBOR encoding of a task.
+ * Useful for comparing against on-chain data.
+ *
+ * @param task - Task data object
+ * @returns Hex string of the CBOR-encoded data (before hashing)
+ */
+declare function debugTaskCBOR(task: TaskData): string;
+
+/**
+ * Commitment Hash Utility
+ *
+ * Functions for computing and verifying hashes of commitment evidence.
+ * The hash is stored on-chain as `commitment_hash` in the course state datum,
+ * while the full evidence (Tiptap JSON document) is stored in the database.
+ *
+ * This provides:
+ * - Compact on-chain storage (64-char hex hash vs full JSON)
+ * - Tamper-evidence (can verify DB content matches on-chain commitment)
+ * - Privacy (evidence details not exposed on-chain)
+ *
+ * @module @andamio/core/hashing
+ */
+/**
+ * Tiptap document structure (simplified)
+ * The actual structure can be more complex with nested content
+ */
+type TiptapDoc = {
+    type: "doc";
+    content?: TiptapNode[];
+    [key: string]: unknown;
+};
+type TiptapNode = {
+    type: string;
+    content?: TiptapNode[];
+    text?: string;
+    marks?: TiptapMark[];
+    attrs?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+type TiptapMark = {
+    type: string;
+    attrs?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+/**
+ * Normalizes a value for consistent hashing.
+ *
+ * Normalization rules:
+ * - Objects: Sort keys alphabetically, recursively normalize values
+ * - Arrays: Preserve order, recursively normalize items
+ * - Strings: Trim whitespace
+ * - Numbers/Booleans/null: Keep as-is
+ * - undefined: Convert to null
+ *
+ * @param value - Any JSON-serializable value
+ * @returns Normalized value
+ */
+declare function normalizeForHashing(value: unknown): unknown;
+/**
+ * Computes the commitment hash from evidence content.
+ *
+ * The hash is computed as:
+ * 1. Normalize the evidence (sort keys, trim strings, etc.)
+ * 2. Serialize to JSON string (deterministic due to normalization)
+ * 3. Apply Blake2b-256 hash
+ *
+ * @param evidence - The evidence content (Tiptap JSON document or any JSON-serializable data)
+ * @returns 64-character lowercase hex string (Blake2b-256 hash)
+ *
+ * @example
+ * ```typescript
+ * import { computeCommitmentHash } from "@andamio/core/hashing";
+ *
+ * const evidence = {
+ *   type: "doc",
+ *   content: [
+ *     { type: "paragraph", content: [{ type: "text", text: "My submission" }] }
+ *   ]
+ * };
+ *
+ * const hash = computeCommitmentHash(evidence);
+ * // Use this hash as commitment_hash in the transaction
+ * ```
+ */
+declare function computeCommitmentHash(evidence: unknown): string;
+/**
+ * Verifies that evidence content matches an expected hash.
+ *
+ * Use this to verify that database evidence matches the on-chain commitment.
+ *
+ * @param evidence - The evidence content to verify
+ * @param expectedHash - The expected hash (from on-chain data)
+ * @returns True if the evidence produces the expected hash
+ */
+declare function verifyCommitmentHash(evidence: unknown, expectedHash: string): boolean;
+/**
+ * Validates that a string is a valid commitment hash format.
+ *
+ * A valid hash is a 64-character hexadecimal string (Blake2b-256 output).
+ *
+ * @param hash - The string to validate
+ * @returns True if the string is a valid hash format
+ */
+declare function isValidCommitmentHash(hash: string): boolean;
+/**
+ * Result of comparing evidence with an on-chain hash
+ */
+type EvidenceVerificationResult = {
+    /** Whether the evidence matches the on-chain hash */
+    isValid: boolean;
+    /** The hash computed from the evidence */
+    computedHash: string;
+    /** The expected hash (from on-chain) */
+    expectedHash: string;
+    /** Human-readable status message */
+    message: string;
+};
+/**
+ * Performs a detailed verification of evidence against an on-chain hash.
+ *
+ * Returns a detailed result object with both hashes and a status message,
+ * useful for debugging and user feedback.
+ *
+ * @param evidence - The evidence content to verify
+ * @param onChainHash - The hash from on-chain data
+ * @returns Detailed verification result
+ */
+declare function verifyEvidenceDetailed(evidence: unknown, onChainHash: string): EvidenceVerificationResult;
+/**
+ * @deprecated Use `computeCommitmentHash` instead.
+ */
+declare const computeAssignmentInfoHash: typeof computeCommitmentHash;
+/**
+ * @deprecated Use `verifyCommitmentHash` instead.
+ */
+declare const verifyAssignmentInfoHash: typeof verifyCommitmentHash;
+/**
+ * @deprecated Use `isValidCommitmentHash` instead.
+ */
+declare const isValidAssignmentInfoHash: typeof isValidCommitmentHash;
+
+export { type EvidenceVerificationResult, type TaskData, type TiptapDoc, type TiptapMark, type TiptapNode, computeAssignmentInfoHash, computeCommitmentHash, computeSltHash, computeSltHashDefinite, computeTaskHash, debugTaskCBOR, isValidAssignmentInfoHash, isValidCommitmentHash, isValidSltHash, isValidTaskHash, normalizeForHashing, verifyAssignmentInfoHash, verifyCommitmentHash, verifyEvidenceDetailed, verifySltHash, verifyTaskHash };

package/dist/utils/hashing/index.d.ts

@@ -0,0 +1,276 @@
+/**
+ * SLT Hash Utility
+ *
+ * Computes the module token name (hash) from a list of Student Learning Targets (SLTs).
+ * This hash is used as the token name when minting module tokens on-chain.
+ *
+ * The algorithm matches the on-chain Plutus validator:
+ * ```haskell
+ * sltsToBbs MintModuleV2{slts} = blake2b_256 $ serialiseData $ toBuiltinData $ map stringToBuiltinByteString slts
+ * ```
+ *
+ * Serialization format:
+ * 1. Convert each SLT string to UTF-8 bytes
+ * 2. Encode as CBOR indefinite-length array of byte strings
+ * 3. Hash with Blake2b-256 (32 bytes / 256 bits)
+ *
+ * @module @andamio/core/hashing
+ */
+/**
+ * Compute the module hash matching Plutus on-chain encoding.
+ *
+ * Plutus's `stringToBuiltinByteString` chunks byte strings at 64 bytes.
+ * This function replicates that behavior:
+ * - Strings <= 64 bytes: encoded as regular CBOR byte strings
+ * - Strings > 64 bytes: encoded as indefinite-length chunked byte strings
+ *
+ * @param slts - Array of Student Learning Target strings
+ * @returns 64-character hex string (256-bit Blake2b hash)
+ *
+ * @example
+ * ```typescript
+ * import { computeSltHash } from "@andamio/core/hashing";
+ *
+ * const slts = [
+ *   "I can mint an access token.",
+ *   "I can complete an assignment to earn a credential."
+ * ];
+ *
+ * const moduleHash = computeSltHash(slts);
+ * // Returns: "8dcbe1b925d87e6c547bbd8071c23a712db4c32751454b0948f8c846e9246b5c"
+ * ```
+ */
+declare function computeSltHash(slts: string[]): string;
+/**
+ * @deprecated Use `computeSltHash` instead. This alias is kept for backwards compatibility.
+ */
+declare const computeSltHashDefinite: typeof computeSltHash;
+/**
+ * Verify that a given hash matches the computed hash for SLTs.
+ *
+ * @param slts - Array of Student Learning Target strings
+ * @param expectedHash - The hash to verify (64-character hex string)
+ * @returns true if the computed hash matches the expected hash
+ */
+declare function verifySltHash(slts: string[], expectedHash: string): boolean;
+/**
+ * Validate that a string is a valid SLT hash format.
+ *
+ * SLT hashes are 64-character hexadecimal strings (256-bit Blake2b hash).
+ *
+ * @param hash - String to validate
+ * @returns true if the string is a valid SLT hash format
+ */
+declare function isValidSltHash(hash: string): boolean;
+
+/**
+ * Task Hash Utility
+ *
+ * Computes the task token name (hash) from task data.
+ * This hash is used as the task_hash on-chain (content-addressed identifier).
+ *
+ * The algorithm matches the on-chain Plutus validator serialization.
+ *
+ * @module @andamio/core/hashing
+ */
+/**
+ * Native asset in ListValue format: [policyId.tokenName, quantity]
+ */
+type NativeAsset = [string, number];
+/**
+ * Task data structure matching the Atlas TX API ManageTasksTxRequest
+ *
+ * Fields must be arranged in this specific order for hashing:
+ * 1. project_content (string, max 140 chars)
+ * 2. expiration_time (number, Unix timestamp in milliseconds)
+ * 3. lovelace_amount (number)
+ * 4. native_assets (array of [asset_class, quantity] tuples)
+ */
+interface TaskData {
+    project_content: string;
+    expiration_time: number;
+    lovelace_amount: number;
+    native_assets: NativeAsset[];
+}
+/**
+ * Compute the task hash (token name / task_hash) from task data.
+ *
+ * This produces the same hash as the on-chain Plutus validator, allowing
+ * clients to pre-compute or verify task hashes.
+ *
+ * @param task - Task data object
+ * @returns 64-character hex string (256-bit Blake2b hash)
+ *
+ * @example
+ * ```typescript
+ * import { computeTaskHash } from "@andamio/core/hashing";
+ *
+ * const task = {
+ *   project_content: "Open Task #1",
+ *   expiration_time: 1769027280000,
+ *   lovelace_amount: 15000000,
+ *   native_assets: []
+ * };
+ *
+ * const taskHash = computeTaskHash(task);
+ * // Returns the on-chain task_hash
+ * ```
+ */
+declare function computeTaskHash(task: TaskData): string;
+/**
+ * Verify that a given hash matches the computed hash for a task.
+ *
+ * @param task - Task data object
+ * @param expectedHash - The hash to verify (64-character hex string)
+ * @returns true if the computed hash matches the expected hash
+ */
+declare function verifyTaskHash(task: TaskData, expectedHash: string): boolean;
+/**
+ * Validate that a string is a valid task hash format.
+ *
+ * Task hashes are 64-character hexadecimal strings (256-bit Blake2b hash).
+ */
+declare function isValidTaskHash(hash: string): boolean;
+/**
+ * Debug function to show the CBOR encoding of a task.
+ * Useful for comparing against on-chain data.
+ *
+ * @param task - Task data object
+ * @returns Hex string of the CBOR-encoded data (before hashing)
+ */
+declare function debugTaskCBOR(task: TaskData): string;
+
+/**
+ * Commitment Hash Utility
+ *
+ * Functions for computing and verifying hashes of commitment evidence.
+ * The hash is stored on-chain as `commitment_hash` in the course state datum,
+ * while the full evidence (Tiptap JSON document) is stored in the database.
+ *
+ * This provides:
+ * - Compact on-chain storage (64-char hex hash vs full JSON)
+ * - Tamper-evidence (can verify DB content matches on-chain commitment)
+ * - Privacy (evidence details not exposed on-chain)
+ *
+ * @module @andamio/core/hashing
+ */
+/**
+ * Tiptap document structure (simplified)
+ * The actual structure can be more complex with nested content
+ */
+type TiptapDoc = {
+    type: "doc";
+    content?: TiptapNode[];
+    [key: string]: unknown;
+};
+type TiptapNode = {
+    type: string;
+    content?: TiptapNode[];
+    text?: string;
+    marks?: TiptapMark[];
+    attrs?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+type TiptapMark = {
+    type: string;
+    attrs?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+/**
+ * Normalizes a value for consistent hashing.
+ *
+ * Normalization rules:
+ * - Objects: Sort keys alphabetically, recursively normalize values
+ * - Arrays: Preserve order, recursively normalize items
+ * - Strings: Trim whitespace
+ * - Numbers/Booleans/null: Keep as-is
+ * - undefined: Convert to null
+ *
+ * @param value - Any JSON-serializable value
+ * @returns Normalized value
+ */
+declare function normalizeForHashing(value: unknown): unknown;
+/**
+ * Computes the commitment hash from evidence content.
+ *
+ * The hash is computed as:
+ * 1. Normalize the evidence (sort keys, trim strings, etc.)
+ * 2. Serialize to JSON string (deterministic due to normalization)
+ * 3. Apply Blake2b-256 hash
+ *
+ * @param evidence - The evidence content (Tiptap JSON document or any JSON-serializable data)
+ * @returns 64-character lowercase hex string (Blake2b-256 hash)
+ *
+ * @example
+ * ```typescript
+ * import { computeCommitmentHash } from "@andamio/core/hashing";
+ *
+ * const evidence = {
+ *   type: "doc",
+ *   content: [
+ *     { type: "paragraph", content: [{ type: "text", text: "My submission" }] }
+ *   ]
+ * };
+ *
+ * const hash = computeCommitmentHash(evidence);
+ * // Use this hash as commitment_hash in the transaction
+ * ```
+ */
+declare function computeCommitmentHash(evidence: unknown): string;
+/**
+ * Verifies that evidence content matches an expected hash.
+ *
+ * Use this to verify that database evidence matches the on-chain commitment.
+ *
+ * @param evidence - The evidence content to verify
+ * @param expectedHash - The expected hash (from on-chain data)
+ * @returns True if the evidence produces the expected hash
+ */
+declare function verifyCommitmentHash(evidence: unknown, expectedHash: string): boolean;
+/**
+ * Validates that a string is a valid commitment hash format.
+ *
+ * A valid hash is a 64-character hexadecimal string (Blake2b-256 output).
+ *
+ * @param hash - The string to validate
+ * @returns True if the string is a valid hash format
+ */
+declare function isValidCommitmentHash(hash: string): boolean;
+/**
+ * Result of comparing evidence with an on-chain hash
+ */
+type EvidenceVerificationResult = {
+    /** Whether the evidence matches the on-chain hash */
+    isValid: boolean;
+    /** The hash computed from the evidence */
+    computedHash: string;
+    /** The expected hash (from on-chain) */
+    expectedHash: string;
+    /** Human-readable status message */
+    message: string;
+};
+/**
+ * Performs a detailed verification of evidence against an on-chain hash.
+ *
+ * Returns a detailed result object with both hashes and a status message,
+ * useful for debugging and user feedback.
+ *
+ * @param evidence - The evidence content to verify
+ * @param onChainHash - The hash from on-chain data
+ * @returns Detailed verification result
+ */
+declare function verifyEvidenceDetailed(evidence: unknown, onChainHash: string): EvidenceVerificationResult;
+/**
+ * @deprecated Use `computeCommitmentHash` instead.
+ */
+declare const computeAssignmentInfoHash: typeof computeCommitmentHash;
+/**
+ * @deprecated Use `verifyCommitmentHash` instead.
+ */
+declare const verifyAssignmentInfoHash: typeof verifyCommitmentHash;
+/**
+ * @deprecated Use `isValidCommitmentHash` instead.
+ */
+declare const isValidAssignmentInfoHash: typeof isValidCommitmentHash;
+
+export { type EvidenceVerificationResult, type TaskData, type TiptapDoc, type TiptapMark, type TiptapNode, computeAssignmentInfoHash, computeCommitmentHash, computeSltHash, computeSltHashDefinite, computeTaskHash, debugTaskCBOR, isValidAssignmentInfoHash, isValidCommitmentHash, isValidSltHash, isValidTaskHash, normalizeForHashing, verifyAssignmentInfoHash, verifyCommitmentHash, verifyEvidenceDetailed, verifySltHash, verifyTaskHash };