@striae-org/striae 3.0.4

package/app/utils/SHA256.ts

@@ -0,0 +1,461 @@
+/**
+ * SHA-256 utility functions for data integrity validation
+ * Uses cryptographically secure SHA-256 algorithm for forensic applications
+ * Provides enhanced security compared to CRC32 for tamper detection
+ */
+
+import { verifySignaturePayload } from './signature-utils';
+
+export const FORENSIC_MANIFEST_VERSION = '2.0';
+export const FORENSIC_MANIFEST_SIGNATURE_ALGORITHM = 'RSASSA-PKCS1-v1_5-SHA-256';
+
+export interface ForensicManifestData {
+  dataHash: string;
+  imageHashes: { [filename: string]: string };
+  manifestHash: string;
+  totalFiles: number;
+  createdAt: string;
+}
+
+export interface ForensicManifestSignature {
+  algorithm: string;
+  keyId: string;
+  signedAt: string;
+  value: string;
+}
+
+export interface SignedForensicManifest extends ForensicManifestData {
+  manifestVersion?: string;
+  signature?: ForensicManifestSignature;
+}
+
+export interface ManifestSignatureVerificationResult {
+  isValid: boolean;
+  keyId?: string;
+  error?: string;
+}
+
+const SHA256_HEX_REGEX = /^[a-f0-9]{64}$/i;
+
+function normalizeImageHashes(imageHashes: { [filename: string]: string }): { [filename: string]: string } {
+  const normalized: { [filename: string]: string } = {};
+  const sortedFilenames = Object.keys(imageHashes).sort();
+
+  for (const filename of sortedFilenames) {
+    normalized[filename] = imageHashes[filename].toLowerCase();
+  }
+
+  return normalized;
+}
+
+function isValidManifestData(candidate: Partial<ForensicManifestData>): candidate is ForensicManifestData {
+  if (!candidate) {
+    return false;
+  }
+
+  if (typeof candidate.dataHash !== 'string' || !SHA256_HEX_REGEX.test(candidate.dataHash)) {
+    return false;
+  }
+
+  if (!candidate.imageHashes || typeof candidate.imageHashes !== 'object') {
+    return false;
+  }
+
+  for (const hash of Object.values(candidate.imageHashes)) {
+    if (typeof hash !== 'string' || !SHA256_HEX_REGEX.test(hash)) {
+      return false;
+    }
+  }
+
+  if (typeof candidate.manifestHash !== 'string' || !SHA256_HEX_REGEX.test(candidate.manifestHash)) {
+    return false;
+  }
+
+  if (typeof candidate.totalFiles !== 'number' || candidate.totalFiles <= 0) {
+    return false;
+  }
+
+  if (typeof candidate.createdAt !== 'string' || Number.isNaN(Date.parse(candidate.createdAt))) {
+    return false;
+  }
+
+  return true;
+}
+
+export function extractForensicManifestData(candidate: Partial<SignedForensicManifest>): ForensicManifestData | null {
+  if (!isValidManifestData(candidate)) {
+    return null;
+  }
+
+  return {
+    dataHash: candidate.dataHash.toLowerCase(),
+    imageHashes: normalizeImageHashes(candidate.imageHashes),
+    manifestHash: candidate.manifestHash.toLowerCase(),
+    totalFiles: candidate.totalFiles,
+    createdAt: candidate.createdAt
+  };
+}
+
+/**
+ * Build canonical payload for manifest signatures.
+ * Every signer/verifier must use this exact ordering.
+ */
+export function createManifestSigningPayload(
+  manifest: ForensicManifestData,
+  manifestVersion: string = FORENSIC_MANIFEST_VERSION
+): string {
+  const canonicalPayload = {
+    manifestVersion,
+    dataHash: manifest.dataHash.toLowerCase(),
+    imageHashes: normalizeImageHashes(manifest.imageHashes),
+    manifestHash: manifest.manifestHash.toLowerCase(),
+    totalFiles: manifest.totalFiles,
+    createdAt: manifest.createdAt
+  };
+
+  return JSON.stringify(canonicalPayload);
+}
+
+/**
+ * Verify manifest signature using configured public key(s).
+ */
+export async function verifyForensicManifestSignature(
+  manifest: Partial<SignedForensicManifest>
+): Promise<ManifestSignatureVerificationResult> {
+  if (!manifest.signature) {
+    return {
+      isValid: false,
+      error: 'Missing forensic manifest signature'
+    };
+  }
+
+  if (manifest.manifestVersion !== FORENSIC_MANIFEST_VERSION) {
+    return {
+      isValid: false,
+      keyId: manifest.signature.keyId,
+      error: `Unsupported manifest version: ${manifest.manifestVersion || 'unknown'}`
+    };
+  }
+
+  const manifestData = extractForensicManifestData(manifest);
+  if (!manifestData) {
+    return {
+      isValid: false,
+      keyId: manifest.signature.keyId,
+      error: 'Manifest content is malformed'
+    };
+  }
+
+  const payload = createManifestSigningPayload(manifestData, manifest.manifestVersion);
+
+  return verifySignaturePayload(
+    payload,
+    manifest.signature,
+    FORENSIC_MANIFEST_SIGNATURE_ALGORITHM,
+    {
+      unsupportedAlgorithmPrefix: 'Unsupported signature algorithm',
+      missingKeyOrValueError: 'Missing signature key ID or value',
+      noVerificationKeyPrefix: 'No verification key configured for key ID',
+      invalidPublicKeyError: 'Manifest signature verification failed: invalid public key',
+      verificationFailedError: 'Manifest signature verification failed'
+    }
+  );
+}
+
+/**
+ * Calculate SHA-256 hash for content integrity validation
+ * This implementation uses the Web Crypto API's SHA-256 for cryptographically
+ * secure hash generation used throughout the Striae application for forensic data validation.
+ * 
+ * @param content - The string content to calculate hash for
+ * @returns SHA-256 hash as lowercase hexadecimal string (64 characters)
+ * @throws Error if content is null, undefined, or not a string
+ */
+export async function calculateSHA256(content: string): Promise<string> {
+  // Input validation for forensic integrity
+  if (content === null) {
+    throw new Error('SHA-256 calculation failed: Content cannot be null');
+  }
+  if (content === undefined) {
+    throw new Error('SHA-256 calculation failed: Content cannot be undefined');
+  }
+  if (typeof content !== 'string') {
+    throw new Error(`SHA-256 calculation failed: Content must be a string, received ${typeof content}`);
+  }
+
+  const encoder = new TextEncoder();
+  const data = encoder.encode(content);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = new Uint8Array(hashBuffer);
+
+  return Array.from(hashArray)
+    .map((byte) => byte.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Calculate SHA-256 hash with timing attack mitigation
+ * This version uses constant-time processing to prevent timing-based attacks
+ * on forensically sensitive content. Use this for high-security environments.
+ * 
+ * @param content - The string content to calculate hash for
+ * @returns SHA-256 hash as lowercase hexadecimal string (64 characters)
+ * @throws Error if content is null, undefined, or not a string
+ */
+export async function calculateSHA256Secure(content: string): Promise<string> {
+  // Input validation for forensic integrity
+  if (content === null) {
+    throw new Error('SHA-256 secure calculation failed: Content cannot be null');
+  }
+  if (content === undefined) {
+    throw new Error('SHA-256 secure calculation failed: Content cannot be undefined');
+  }
+  if (typeof content !== 'string') {
+    throw new Error(`SHA-256 secure calculation failed: Content must be a string, received ${typeof content}`);
+  }
+
+  const encoder = new TextEncoder();
+  const originalData = encoder.encode(content);
+
+  // Timing attack mitigation: pad to next 64-byte boundary
+  // This reduces timing variance while maintaining algorithm correctness
+  const BLOCK_SIZE = 64;
+  const paddedLength = Math.ceil(originalData.length / BLOCK_SIZE) * BLOCK_SIZE;
+  const paddedData = new Uint8Array(paddedLength);
+
+  // Copy original data and pad with zeros
+  paddedData.set(originalData);
+
+  // For SHA-256 we hash original content, then add bounded extra work.
+  const hashBuffer = await crypto.subtle.digest('SHA-256', originalData);
+  const hashArray = new Uint8Array(hashBuffer);
+
+  const paddingBytes = paddedLength - originalData.length;
+  if (paddingBytes > 0) {
+    // Compute digest over padded data to reduce timing variance.
+    const paddingDigestBuffer = await crypto.subtle.digest('SHA-256', paddedData);
+    const paddingDigestArray = new Uint8Array(paddingDigestBuffer);
+    let volatile = 0;
+    for (let i = 0; i < paddingDigestArray.length; i += 1) {
+      volatile = (volatile * 31) ^ paddingDigestArray[i];
+    }
+    if (volatile === 0xdeadbeef) {
+      console.debug('');
+    }
+  }
+
+  return Array.from(hashArray)
+    .map((byte) => byte.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Calculate SHA-256 hash for binary data (images, files)
+ * 
+ * @param data - Binary data as Uint8Array, ArrayBuffer, or Blob
+ * @returns SHA-256 hash as lowercase hexadecimal string (64 characters)
+ * @throws Error if data is null, undefined, or unsupported type
+ */
+export async function calculateSHA256Binary(data: Uint8Array | ArrayBuffer | Blob): Promise<string> {
+  // Input validation for forensic integrity
+  if (data === null) {
+    throw new Error('SHA-256 binary calculation failed: Data cannot be null');
+  }
+  if (data === undefined) {
+    throw new Error('SHA-256 binary calculation failed: Data cannot be undefined');
+  }
+  if (!(data instanceof Uint8Array || data instanceof ArrayBuffer || data instanceof Blob)) {
+    throw new Error('SHA-256 binary calculation failed: Data must be Uint8Array, ArrayBuffer, or Blob');
+  }
+
+  let buffer: ArrayBuffer;
+
+  if (data instanceof Blob) {
+    buffer = await data.arrayBuffer();
+  } else if (data instanceof ArrayBuffer) {
+    buffer = data;
+  } else {
+    buffer = data.buffer instanceof ArrayBuffer
+      ? data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength)
+      : new ArrayBuffer(data.length);
+    if (!(data.buffer instanceof ArrayBuffer)) {
+      new Uint8Array(buffer).set(data);
+    }
+  }
+
+  const hashBuffer = await crypto.subtle.digest('SHA-256', buffer);
+  const hashArray = new Uint8Array(hashBuffer);
+
+  return Array.from(hashArray)
+    .map((byte) => byte.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Generate comprehensive file manifest with secure hashes for forensic applications.
+ */
+export async function generateForensicManifestSecure(
+  dataContent: string,
+  imageFiles: { [filename: string]: Blob }
+): Promise<ForensicManifestData> {
+  const dataHash = await calculateSHA256Secure(dataContent);
+
+  const imageHashes: { [filename: string]: string } = {};
+  const sortedFilenames = Object.keys(imageFiles).sort();
+  for (const filename of sortedFilenames) {
+    imageHashes[filename] = await calculateSHA256Binary(imageFiles[filename]);
+  }
+
+  const manifestForHash = {
+    dataHash,
+    imageHashes,
+    totalFiles: Object.keys(imageFiles).length + 1,
+    createdAt: new Date().toISOString()
+  };
+
+  const manifestContent = JSON.stringify(manifestForHash);
+  const manifestHash = await calculateSHA256Secure(manifestContent);
+
+  return {
+    dataHash,
+    imageHashes,
+    manifestHash,
+    totalFiles: manifestForHash.totalFiles,
+    createdAt: manifestForHash.createdAt
+  };
+}
+
+/**
+ * Generate secure forensic manifest with specific timestamp (for validation purposes).
+ */
+export async function generateForensicManifestWithTimestampSecure(
+  dataContent: string,
+  imageFiles: { [filename: string]: Blob },
+  createdAt: string
+): Promise<ForensicManifestData> {
+  const dataHash = await calculateSHA256Secure(dataContent);
+
+  const imageHashes: { [filename: string]: string } = {};
+  const sortedFilenames = Object.keys(imageFiles).sort();
+  for (const filename of sortedFilenames) {
+    imageHashes[filename] = await calculateSHA256Binary(imageFiles[filename]);
+  }
+
+  const manifestForHash = {
+    dataHash,
+    imageHashes,
+    totalFiles: Object.keys(imageFiles).length + 1,
+    createdAt
+  };
+
+  const manifestContent = JSON.stringify(manifestForHash);
+  const manifestHash = await calculateSHA256Secure(manifestContent);
+
+  return {
+    dataHash,
+    imageHashes,
+    manifestHash,
+    totalFiles: manifestForHash.totalFiles,
+    createdAt: manifestForHash.createdAt
+  };
+}
+
+/**
+ * Validate complete case integrity including data and images using secure SHA-256.
+ */
+export async function validateCaseIntegritySecure(
+  dataContent: string,
+  imageFiles: { [filename: string]: Blob },
+  expectedManifest: ForensicManifestData
+): Promise<{
+  isValid: boolean;
+  dataValid: boolean;
+  imageValidation: { [filename: string]: boolean };
+  manifestValid: boolean;
+  errors: string[];
+  summary: string;
+}> {
+  const errors: string[] = [];
+  const imageValidation: { [filename: string]: boolean } = {};
+
+  const actualDataHash = await calculateSHA256Secure(dataContent);
+  const dataValid = actualDataHash === expectedManifest.dataHash.toLowerCase();
+  if (!dataValid) {
+    errors.push(`Data hash mismatch: expected ${expectedManifest.dataHash}, got ${actualDataHash}`);
+  }
+
+  const actualImageFiles = Object.keys(imageFiles).sort();
+  const expectedImageFiles = Object.keys(expectedManifest.imageHashes).sort();
+
+  const missingFiles = expectedImageFiles.filter((f) => !actualImageFiles.includes(f));
+  const extraFiles = actualImageFiles.filter((f) => !expectedImageFiles.includes(f));
+
+  if (missingFiles.length > 0) {
+    errors.push(`Missing image files: ${missingFiles.join(', ')}`);
+  }
+  if (extraFiles.length > 0) {
+    errors.push(`Extra image files not in manifest: ${extraFiles.join(', ')}`);
+  }
+
+  for (const filename of actualImageFiles) {
+    if (expectedManifest.imageHashes[filename]) {
+      const actualHash = await calculateSHA256Binary(imageFiles[filename]);
+      const isValid = actualHash === expectedManifest.imageHashes[filename].toLowerCase();
+      imageValidation[filename] = isValid;
+
+      if (!isValid) {
+        errors.push(`Image hash mismatch for ${filename}: expected ${expectedManifest.imageHashes[filename]}, got ${actualHash}`);
+      }
+    } else {
+      imageValidation[filename] = false;
+    }
+  }
+
+  const recreatedManifest = await generateForensicManifestWithTimestampSecure(
+    dataContent,
+    imageFiles,
+    expectedManifest.createdAt
+  );
+
+  const manifestValid = recreatedManifest.manifestHash === expectedManifest.manifestHash.toLowerCase();
+  if (!manifestValid) {
+    errors.push(`Manifest hash mismatch: expected ${expectedManifest.manifestHash}, got ${recreatedManifest.manifestHash}`);
+
+    if (recreatedManifest.dataHash !== expectedManifest.dataHash.toLowerCase()) {
+      errors.push('Manifest data hash field differs from actual data');
+    }
+
+    for (const filename of Object.keys(imageFiles).sort()) {
+      if (
+        recreatedManifest.imageHashes[filename] &&
+        recreatedManifest.imageHashes[filename] !== expectedManifest.imageHashes[filename]?.toLowerCase()
+      ) {
+        errors.push(`Manifest image hash entry for ${filename} differs from actual file`);
+      }
+    }
+  }
+
+  const allImageFilesValid = Object.values(imageValidation).every((valid) => valid);
+  const isValid = dataValid && allImageFilesValid && manifestValid && errors.length === 0;
+
+  const totalFiles = Object.keys(imageFiles).length;
+  const validFiles = Object.values(imageValidation).filter((valid) => valid).length;
+
+  let summary = `Validation ${isValid ? 'PASSED' : 'FAILED'}: `;
+  summary += `Data ${dataValid ? 'valid' : 'invalid'}, `;
+  summary += `${validFiles}/${totalFiles} images valid, `;
+  summary += `manifest ${manifestValid ? 'valid' : 'invalid'}`;
+
+  if (errors.length > 0) {
+    summary += `. ${errors.length} error(s) detected`;
+  }
+
+  return {
+    isValid,
+    dataValid,
+    imageValidation,
+    manifestValid,
+    errors,
+    summary
+  };
+}

package/app/utils/annotation-timestamp.ts

@@ -0,0 +1,25 @@
+export const resolveEarliestAnnotationTimestamp = (
+  incomingTimestamp?: string,
+  existingTimestamp?: string,
+  fallbackTimestamp: string = new Date().toISOString()
+): string => {
+  const candidates = [incomingTimestamp, existingTimestamp, fallbackTimestamp].filter(
+    (timestamp): timestamp is string => !!timestamp
+  );
+
+  const oldestValid = candidates.reduce<{ value: string; time: number } | null>((oldest, timestamp) => {
+    const parsedTime = Date.parse(timestamp);
+
+    if (Number.isNaN(parsedTime)) {
+      return oldest;
+    }
+
+    if (!oldest || parsedTime < oldest.time) {
+      return { value: timestamp, time: parsedTime };
+    }
+
+    return oldest;
+  }, null);
+
+  return oldestValid?.value || fallbackTimestamp;
+};

package/app/utils/audit-export-signature.ts

@@ -0,0 +1,117 @@
+import {
+  ForensicManifestSignature,
+  FORENSIC_MANIFEST_SIGNATURE_ALGORITHM,
+  ManifestSignatureVerificationResult
+} from './SHA256';
+import { verifySignaturePayload } from './signature-utils';
+
+export const AUDIT_EXPORT_SIGNATURE_VERSION = '1.0';
+
+const SHA256_HEX_REGEX = /^[a-f0-9]{64}$/i;
+
+export type AuditExportFormat = 'csv' | 'json' | 'txt';
+export type AuditExportType = 'entries' | 'trail' | 'report';
+export type AuditExportScopeType = 'case' | 'user';
+
+export interface AuditExportSigningPayload {
+  signatureVersion: string;
+  exportFormat: AuditExportFormat;
+  exportType: AuditExportType;
+  scopeType: AuditExportScopeType;
+  scopeIdentifier: string;
+  generatedAt: string;
+  totalEntries: number;
+  hash: string;
+}
+
+export function isValidAuditExportSigningPayload(
+  payload: Partial<AuditExportSigningPayload>
+): payload is AuditExportSigningPayload {
+  if (!payload) {
+    return false;
+  }
+
+  if (payload.signatureVersion !== AUDIT_EXPORT_SIGNATURE_VERSION) {
+    return false;
+  }
+
+  if (payload.exportFormat !== 'csv' && payload.exportFormat !== 'json' && payload.exportFormat !== 'txt') {
+    return false;
+  }
+
+  if (payload.exportType !== 'entries' && payload.exportType !== 'trail' && payload.exportType !== 'report') {
+    return false;
+  }
+
+  if (payload.scopeType !== 'case' && payload.scopeType !== 'user') {
+    return false;
+  }
+
+  if (typeof payload.scopeIdentifier !== 'string' || payload.scopeIdentifier.trim().length === 0) {
+    return false;
+  }
+
+  if (typeof payload.generatedAt !== 'string' || Number.isNaN(Date.parse(payload.generatedAt))) {
+    return false;
+  }
+
+  if (typeof payload.totalEntries !== 'number' || payload.totalEntries < 0) {
+    return false;
+  }
+
+  if (typeof payload.hash !== 'string' || !SHA256_HEX_REGEX.test(payload.hash)) {
+    return false;
+  }
+
+  return true;
+}
+
+export function createAuditExportSigningPayload(payload: AuditExportSigningPayload): string {
+  const canonicalPayload = {
+    signatureVersion: payload.signatureVersion,
+    exportFormat: payload.exportFormat,
+    exportType: payload.exportType,
+    scopeType: payload.scopeType,
+    scopeIdentifier: payload.scopeIdentifier,
+    generatedAt: payload.generatedAt,
+    totalEntries: payload.totalEntries,
+    hash: payload.hash.toUpperCase()
+  };
+
+  return JSON.stringify(canonicalPayload);
+}
+
+export async function verifyAuditExportSignature(
+  payload: Partial<AuditExportSigningPayload>,
+  signature?: ForensicManifestSignature
+): Promise<ManifestSignatureVerificationResult> {
+  if (!signature) {
+    return {
+      isValid: false,
+      error: 'Missing audit export signature'
+    };
+  }
+
+  if (!isValidAuditExportSigningPayload(payload)) {
+    return {
+      isValid: false,
+      keyId: signature.keyId,
+      error: 'Audit export signature metadata is malformed'
+    };
+  }
+
+  const signingPayload = createAuditExportSigningPayload(payload);
+
+  return verifySignaturePayload(
+    signingPayload,
+    signature,
+    FORENSIC_MANIFEST_SIGNATURE_ALGORITHM,
+    {
+      unsupportedAlgorithmPrefix: 'Unsupported audit export signature algorithm',
+      missingKeyOrValueError: 'Missing audit export signature key ID or value',
+      noVerificationKeyPrefix: 'No verification key configured for key ID',
+      invalidPublicKeyError: 'Audit export signature verification failed: invalid public key',
+      verificationFailedError: 'Audit export signature verification failed'
+    }
+  );
+}

package/app/utils/auth-action-settings.ts

@@ -0,0 +1,48 @@
+import type { ActionCodeSettings } from 'firebase/auth';
+import paths from '~/config/config.json';
+
+const AUTH_ROUTE_PATH = '/';
+const DEFAULT_CONTINUE_PATH = '/';
+
+const normalizedBaseUrl = paths.url.replace(/\/$/, '');
+const appOrigin = new URL(normalizedBaseUrl).origin;
+
+const normalizeContinuePath = (continuePath?: string): string => {
+  if (!continuePath || continuePath.trim().length === 0) {
+    return DEFAULT_CONTINUE_PATH;
+  }
+
+  if (!continuePath.startsWith('/') || continuePath.startsWith('//')) {
+    return DEFAULT_CONTINUE_PATH;
+  }
+
+  return continuePath;
+};
+
+export const buildActionCodeSettings = (continuePath?: string): ActionCodeSettings => {
+  const safeContinuePath = normalizeContinuePath(continuePath);
+
+  return {
+    url: `${normalizedBaseUrl}${safeContinuePath}`,
+  };
+};
+
+export const getSafeContinuePath = (continueUrl: string | null | undefined): string => {
+  if (!continueUrl || continueUrl.trim().length === 0) {
+    return DEFAULT_CONTINUE_PATH;
+  }
+
+  try {
+    const parsedUrl = new URL(continueUrl, appOrigin);
+    if (parsedUrl.origin !== appOrigin) {
+      return DEFAULT_CONTINUE_PATH;
+    }
+
+    const safePath = `${parsedUrl.pathname}${parsedUrl.search}${parsedUrl.hash}`;
+    return safePath.startsWith('/') ? safePath : DEFAULT_CONTINUE_PATH;
+  } catch {
+    return DEFAULT_CONTINUE_PATH;
+  }
+};
+
+export const getAuthActionRoutePath = (): string => AUTH_ROUTE_PATH;

package/app/utils/auth.ts

@@ -0,0 +1,34 @@
+import paths from '~/config/config.json';
+
+const KEYS_URL = paths.keys_url;
+const KEYS_AUTH = paths.keys_auth;
+
+type KeyType = 'USER_DB_AUTH' | 'R2_KEY_SECRET' | 'IMAGES_API_TOKEN' | 'ACCOUNT_HASH';
+
+async function getApiKey(keyType: KeyType): Promise<string> {
+  const keyResponse = await fetch(`${KEYS_URL}/${keyType}`, {
+    headers: {
+      'X-Custom-Auth-Key': KEYS_AUTH
+    }
+  });
+  if (!keyResponse.ok) {
+    throw new Error(`Failed to retrieve ${keyType}`);
+  }
+  return keyResponse.text();
+}
+
+export async function getUserApiKey(): Promise<string> {
+  return getApiKey('USER_DB_AUTH');
+}
+
+export async function getDataApiKey(): Promise<string> {
+  return getApiKey('R2_KEY_SECRET');
+}
+
+export async function getImageApiKey(): Promise<string> {
+  return getApiKey('IMAGES_API_TOKEN');
+}
+
+export async function getAccountHash(): Promise<string> {
+  return getApiKey('ACCOUNT_HASH');
+}