feat(interfaces): add comprehensive TypeScript interface modules, demo data, docs, and publish metadata

ts_interfaces/legal.ts

@@ -0,0 +1,369 @@
+/**
+ * @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,
+    },
+  };
+}