tools/ts_interfaces/legal.ts

/**
 * @file legal.ts
 * @description Legal compliance interfaces
 * TSA (RFC 3161) timestamps, blockchain anchoring, eIDAS qualified signatures
 */

import type {
  TTimestampMethod,
  TBlockchainNetwork,
  THashAlgorithm,
  TSignatureLegalLevel,
  TComplianceAction,
  TQualificationStatus,
  TValidationStatus,
  TIdentityVerificationMethod,
} from './types.js';

// ============================================================================
// TSA TIMESTAMP (RFC 3161)
// ============================================================================

/**
 * Time Stamp Authority information
 */
export interface ITsaAuthority {
  name: string;
  url: string;
  certificateFingerprint: string;
  isQualified: boolean;
  country?: string;
}

/**
 * Timestamp token data
 */
export interface ITsaToken {
  tokenBase64: string;
  serialNumber: string;
  time: number;
  hashAlgorithm: string;
  hashedMessage: string;
  nonce?: string;
}

/**
 * TSA verification status
 */
export interface ITsaVerification {
  verified: boolean;
  verifiedAt: number;
  certificateChainValid: boolean;
  signatureValid: boolean;
}

/**
 * Qualified TSA information (eIDAS)
 */
export interface IQualifiedTsaInfo {
  trustedListReference: string;
  serviceId: string;
  qualificationStatus: TQualificationStatus;
}

/**
 * RFC 3161 Time Stamp Token
 */
export interface ITsaTimestamp {
  id: string;
  authority: ITsaAuthority;
  token: ITsaToken;
  verification: ITsaVerification;
  qualifiedInfo?: IQualifiedTsaInfo;
}

// ============================================================================
// BLOCKCHAIN TIMESTAMP
// ============================================================================

/**
 * Blockchain transaction information
 */
export interface IBlockchainTransaction {
  txHash: string;
  blockNumber: number;
  blockHash: string;
  blockTimestamp: number;
  txIndex: number;
}

/**
 * Merkle proof for aggregated timestamps
 */
export interface IMerkleProof {
  root: string;
  proof: string[];
  leaf: string;
  positions: ('left' | 'right')[];
}

/**
 * Timestamped data information
 */
export interface ITimestampedData {
  dataHash: string;
  hashAlgorithm: THashAlgorithm;
  dataReference?: string;
}

/**
 * Blockchain verification status
 */
export interface IBlockchainVerification {
  verified: boolean;
  verifiedAt: number;
  blockConfirmations: number;
  explorerUrl?: string;
}

/**
 * Blockchain timestamping provider
 */
export interface IBlockchainProvider {
  name: string;
  serviceId?: string;
  proofUrl?: string;
}

/**
 * Blockchain timestamp anchor
 */
export interface IBlockchainTimestamp {
  id: string;
  network: TBlockchainNetwork;
  chainId?: number;
  transaction: IBlockchainTransaction;
  merkleProof?: IMerkleProof;
  timestampedData: ITimestampedData;
  verification: IBlockchainVerification;
  provider?: IBlockchainProvider;
}

// ============================================================================
// LONG-TERM VALIDATION (LTV)
// ============================================================================

/**
 * Long-term validation data (for PAdES-LTV equivalent)
 */
export interface ILongTermValidation {
  certificateChains: string[];
  ocspResponses: string[];
  crlData: string[];
  archiveTimestamp?: ITsaTimestamp;
}

/**
 * Document hash information
 */
export interface IDocumentHashInfo {
  algorithm: THashAlgorithm;
  value: string;
  scope: 'content_only' | 'content_and_signatures' | 'full_envelope';
}

/**
 * Signature validation details
 */
export interface ISignatureValidationDetails {
  cryptographicCheck: boolean;
  certificateChainValid: boolean;
  timestampValid: boolean;
  signerIdentityVerified: boolean;
}

/**
 * Signature validation result
 */
export interface ISignatureValidation {
  validatedAt: number;
  status: TValidationStatus;
  details: ISignatureValidationDetails;
}

// ============================================================================
// COMPLIANCE AUDIT
// ============================================================================

/**
 * Compliance audit entry
 */
export interface IComplianceAuditEntry {
  timestamp: number;
  action: TComplianceAction;
  details: Record<string, unknown>;
  actor: {
    type: 'system' | 'service' | 'user';
    id: string;
  };
}

// ============================================================================
// LEGAL COMPLIANCE PROOF
// ============================================================================

/**
 * Complete legal compliance proof for a signature
 */
export interface ILegalComplianceProof {
  id: string;
  schemaVersion: '1.0.0';
  eidasLevel?: TSignatureLegalLevel;
  jurisdictions: string[];
  tsaTimestamps: ITsaTimestamp[];
  blockchainTimestamps: IBlockchainTimestamp[];
  longTermValidation?: ILongTermValidation;
  documentHash: IDocumentHashInfo;
  signatureValidation?: ISignatureValidation;
  auditTrail: IComplianceAuditEntry[];
  createdAt: number;
  updatedAt: number;
}

// ============================================================================
// SIGNATURE VALIDATION REQUEST/RESULT
// ============================================================================

/**
 * Request to validate a signature
 */
export interface ISignatureValidationRequest {
  signatureId: string;
  documentHash: string;
  validationLevel: 'basic' | 'timestamp' | 'long_term';
  checkRevocation: boolean;
  validationTime?: number;
}

/**
 * Detailed validation result for signature integrity
 */
export interface ISignatureIntegrityResult {
  status: 'valid' | 'invalid';
  message?: string;
}

/**
 * Certificate chain validation result
 */
export interface ICertificateChainResult {
  status: 'valid' | 'invalid' | 'unknown';
  chainLength: number;
  rootTrusted: boolean;
  message?: string;
}

/**
 * Timestamp validation result
 */
export interface ITimestampValidationResult {
  status: 'valid' | 'invalid' | 'not_present';
  timestampTime?: number;
  tsaName?: string;
}

/**
 * Revocation check result
 */
export interface IRevocationResult {
  status: 'good' | 'revoked' | 'unknown';
  checkedAt: number;
  method: 'ocsp' | 'crl' | 'none';
  revocationTime?: number;
}

/**
 * Identity verification validation result
 */
export interface IIdentityValidationResult {
  status: 'verified' | 'not_verified' | 'expired';
  method?: TIdentityVerificationMethod;
  verifiedAt?: number;
}

/**
 * Signature validation result
 */
export interface ISignatureValidationResult {
  requestId: string;
  status: TValidationStatus;
  details: {
    signatureIntegrity: ISignatureIntegrityResult;
    certificateChain?: ICertificateChainResult;
    timestamp?: ITimestampValidationResult;
    revocation?: IRevocationResult;
    identityVerification?: IIdentityValidationResult;
  };
  warnings: string[];
  validatedAt: number;
  reportReference?: string;
}

// ============================================================================
// FACTORY FUNCTIONS
// ============================================================================

/**
 * Create empty legal compliance proof
 */
export function createEmptyLegalComplianceProof(): ILegalComplianceProof {
  const now = Date.now();
  return {
    id: crypto.randomUUID(),
    schemaVersion: '1.0.0',
    jurisdictions: [],
    tsaTimestamps: [],
    blockchainTimestamps: [],
    documentHash: {
      algorithm: 'SHA-256',
      value: '',
      scope: 'full_envelope',
    },
    auditTrail: [],
    createdAt: now,
    updatedAt: now,
  };
}

/**
 * Create a TSA timestamp request result placeholder
 */
export function createPendingTsaTimestamp(authorityUrl: string): Partial<ITsaTimestamp> {
  return {
    id: crypto.randomUUID(),
    authority: {
      name: '',
      url: authorityUrl,
      certificateFingerprint: '',
      isQualified: false,
    },
    verification: {
      verified: false,
      verifiedAt: 0,
      certificateChainValid: false,
      signatureValid: false,
    },
  };
}

/**
 * Create a blockchain timestamp placeholder
 */
export function createPendingBlockchainTimestamp(
  network: TBlockchainNetwork,
  dataHash: string
): Partial<IBlockchainTimestamp> {
  return {
    id: crypto.randomUUID(),
    network,
    timestampedData: {
      dataHash,
      hashAlgorithm: 'SHA-256',
    },
    verification: {
      verified: false,
      verifiedAt: 0,
      blockConfirmations: 0,
    },
  };
}