@fin.cx/skr 1.1.0 → 1.2.1

package/ts/skr.postingkeys.ts

@@ -0,0 +1,252 @@
+/**
+ * DATEV Posting Keys (Buchungsschlüssel) for German Accounting
+ *
+ * Posting keys control automatic VAT booking and are automatically checked
+ * in German tax audits (Betriebsprüfungen). Using incorrect posting keys
+ * can have serious tax consequences.
+ *
+ * Reference: DATEV Buchungsschlüssel-Verzeichnis
+ */
+
+import type { TPostingKey, IPostingKeyRule } from './skr.types.js';
+
+/**
+ * Posting key definitions with validation rules
+ */
+export const POSTING_KEY_RULES: Record<TPostingKey, IPostingKeyRule> = {
+  3: {
+    key: 3,
+    description: 'Zahlungseingang mit 19% Umsatzsteuer',
+    vatRate: 19,
+    requiresVAT: true,
+    disablesVATAutomatism: false,
+    allowedScenarios: ['domestic_taxed']
+  },
+  8: {
+    key: 8,
+    description: '7% Vorsteuer',
+    vatRate: 7,
+    requiresVAT: true,
+    disablesVATAutomatism: false,
+    allowedScenarios: ['domestic_taxed']
+  },
+  9: {
+    key: 9,
+    description: '19% Vorsteuer',
+    vatRate: 19,
+    requiresVAT: true,
+    disablesVATAutomatism: false,
+    allowedScenarios: ['domestic_taxed']
+  },
+  19: {
+    key: 19,
+    description: '19% Vorsteuer bei innergemeinschaftlichen Lieferungen',
+    vatRate: 19,
+    requiresVAT: true,
+    disablesVATAutomatism: false,
+    allowedScenarios: ['intra_eu']
+  },
+  40: {
+    key: 40,
+    description: 'Steuerfrei / Aufhebung der Automatik',
+    vatRate: 0,
+    requiresVAT: false,
+    disablesVATAutomatism: true,
+    allowedScenarios: ['tax_free', 'export', 'reverse_charge']
+  },
+  94: {
+    key: 94,
+    description: '19% Vorsteuer/Umsatzsteuer bei Erwerb aus EU oder Drittland (Reverse Charge)',
+    vatRate: 19,
+    requiresVAT: true,
+    disablesVATAutomatism: false,
+    allowedScenarios: ['reverse_charge', 'intra_eu', 'third_country']
+  }
+};
+
+/**
+ * Validate posting key for a journal entry line
+ */
+export function validatePostingKey(
+  postingKey: TPostingKey,
+  accountNumber: string,
+  amount: number,
+  vatAmount?: number,
+  taxScenario?: string
+): { isValid: boolean; errors: string[]; warnings: string[] } {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Get posting key rule
+  const rule = POSTING_KEY_RULES[postingKey];
+  if (!rule) {
+    errors.push(`Invalid posting key: ${postingKey}`);
+    return { isValid: false, errors, warnings };
+  }
+
+  // Validate VAT requirement
+  // Skip VAT amount requirement if:
+  // 1. Posting TO a VAT account (the line itself IS the VAT)
+  // 2. Posting TO a debtor/creditor account (receivable/payable settlement - VAT was already recorded)
+  const isVATAccount = accountNumber === '1571' || accountNumber === '1771' || accountNumber === '1576';
+  const accountNum = parseInt(accountNumber);
+  const isDebtorCreditorAccount = (accountNum >= 10000 && accountNum <= 69999) || (accountNum >= 70000 && accountNum <= 99999);
+
+  if (rule.requiresVAT && !vatAmount && !isVATAccount && !isDebtorCreditorAccount) {
+    errors.push(
+      `Posting key ${postingKey} requires VAT amount, but none provided. ` +
+      `Description: ${rule.description}`
+    );
+  }
+
+  // Validate VAT rate if specified
+  if (rule.vatRate && vatAmount && rule.vatRate > 0) {
+    const expectedVAT = Math.round(amount * rule.vatRate) / 100;
+    const tolerance = 0.02; // 2 cent tolerance for rounding
+
+    if (Math.abs(vatAmount - expectedVAT) > tolerance) {
+      warnings.push(
+        `VAT amount ${vatAmount} does not match expected ${expectedVAT.toFixed(2)} ` +
+        `for posting key ${postingKey} (${rule.vatRate}%)`
+      );
+    }
+  }
+
+  // Validate tax scenario
+  if (rule.allowedScenarios && taxScenario) {
+    if (!rule.allowedScenarios.includes(taxScenario)) {
+      errors.push(
+        `Posting key ${postingKey} is not valid for tax scenario '${taxScenario}'. ` +
+        `Allowed scenarios: ${rule.allowedScenarios.join(', ')}`
+      );
+    }
+  }
+
+  // Validate automatism disabling
+  if (rule.disablesVATAutomatism && vatAmount && vatAmount > 0) {
+    warnings.push(
+      `Posting key ${postingKey} disables VAT automatism but VAT amount is provided. ` +
+      `This may cause incorrect tax reporting.`
+    );
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+
+/**
+ * Get posting key description
+ */
+export function getPostingKeyDescription(postingKey: TPostingKey): string {
+  const rule = POSTING_KEY_RULES[postingKey];
+  return rule ? rule.description : `Unknown posting key: ${postingKey}`;
+}
+
+/**
+ * Get appropriate posting key for a transaction
+ */
+export function suggestPostingKey(params: {
+  vatRate: number;
+  taxScenario?: string;
+  isPayment?: boolean;
+}): TPostingKey {
+  const { vatRate, taxScenario, isPayment } = params;
+
+  // Tax-free or reverse charge scenarios
+  if (taxScenario === 'tax_free' || taxScenario === 'export') {
+    return 40;
+  }
+
+  // Reverse charge
+  if (taxScenario === 'reverse_charge' || taxScenario === 'third_country') {
+    return 94;
+  }
+
+  // Intra-EU with VAT
+  if (taxScenario === 'intra_eu' && vatRate === 19) {
+    return 19;
+  }
+
+  // Payment with 19% VAT
+  if (isPayment && vatRate === 19) {
+    return 3;
+  }
+
+  // Input VAT based on rate
+  if (vatRate === 19) {
+    return 9;
+  }
+
+  if (vatRate === 7) {
+    return 8;
+  }
+
+  // Default to tax-free if no VAT
+  if (vatRate === 0) {
+    return 40;
+  }
+
+  // Fallback to 19% input VAT
+  return 9;
+}
+
+/**
+ * Validate all posting keys for consistency
+ */
+export function validatePostingKeyConsistency(lines: Array<{
+  postingKey: TPostingKey;
+  accountNumber: string;
+  debit?: number;
+  credit?: number;
+  vatAmount?: number;
+}>): { isValid: boolean; errors: string[]; warnings: string[] } {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Check for mixing tax-free and taxed transactions
+  const hasTaxFree = lines.some(line => line.postingKey === 40);
+  const hasTaxed = lines.some(line => [3, 8, 9, 19, 94].includes(line.postingKey));
+
+  if (hasTaxFree && hasTaxed) {
+    warnings.push(
+      'Journal entry mixes tax-free (key 40) and taxed transactions. ' +
+      'Verify this is intentional.'
+    );
+  }
+
+  // Check for reverse charge consistency
+  const hasReverseCharge = lines.some(line => line.postingKey === 94);
+  if (hasReverseCharge) {
+    const reverseChargeLines = lines.filter(line => line.postingKey === 94);
+    if (reverseChargeLines.length % 2 !== 0) {
+      errors.push(
+        'Reverse charge (posting key 94) requires both input and output VAT entries. ' +
+        'Found odd number of reverse charge lines.'
+      );
+    }
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+
+/**
+ * Check if posting key requires automatic VAT booking
+ */
+export function requiresAutomaticVAT(postingKey: TPostingKey): boolean {
+  const rule = POSTING_KEY_RULES[postingKey];
+  return rule ? !rule.disablesVATAutomatism : false;
+}
+
+/**
+ * Get all valid posting keys
+ */
+export function getAllPostingKeys(): TPostingKey[] {
+  return Object.keys(POSTING_KEY_RULES).map(k => Number(k) as TPostingKey);
+}

package/ts/skr.security.ts

@@ -0,0 +1,405 @@
+import * as plugins from './plugins.js';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import * as https from 'https';
+
+export interface ISigningOptions {
+  certificatePem?: string;
+  privateKeyPem?: string;
+  privateKeyPassphrase?: string;
+  timestampServerUrl?: string;
+  includeTimestamp?: boolean;
+}
+
+export interface ISignatureResult {
+  signature: string;
+  signatureFormat: 'CAdES-B' | 'CAdES-T' | 'CAdES-LT';
+  signingTime: string;
+  certificateChain?: string[];
+  timestampToken?: string;
+  timestampTime?: string;
+}
+
+export interface ITimestampResponse {
+  token: string;
+  time: string;
+  serverUrl: string;
+  hashAlgorithm: string;
+}
+
+export class SecurityManager {
+  private options: ISigningOptions;
+  private logger: plugins.smartlog.ConsoleLog;
+  
+  constructor(options: ISigningOptions = {}) {
+    this.options = {
+      timestampServerUrl: options.timestampServerUrl || 'http://timestamp.digicert.com',
+      includeTimestamp: options.includeTimestamp !== false,
+      ...options
+    };
+    this.logger = new plugins.smartlog.ConsoleLog();
+  }
+
+  /**
+   * Creates a CAdES-B (Basic) signature for data
+   */
+  public async createCadesSignature(
+    data: Buffer | string,
+    certificatePem?: string,
+    privateKeyPem?: string
+  ): Promise<ISignatureResult> {
+    const cert = certificatePem || this.options.certificatePem;
+    const key = privateKeyPem || this.options.privateKeyPem;
+    
+    if (!cert || !key) {
+      throw new Error('Certificate and private key are required for signing');
+    }
+
+    try {
+      // Parse certificate and key
+      const certificate = plugins.nodeForge.pki.certificateFromPem(cert);
+      const privateKey = this.options.privateKeyPassphrase 
+        ? plugins.nodeForge.pki.decryptRsaPrivateKey(key, this.options.privateKeyPassphrase)
+        : plugins.nodeForge.pki.privateKeyFromPem(key);
+
+      // Create PKCS#7 signed data (CMS)
+      const p7 = plugins.nodeForge.pkcs7.createSignedData();
+      
+      // Add content
+      if (typeof data === 'string') {
+        p7.content = plugins.nodeForge.util.createBuffer(data, 'utf8');
+      } else {
+        p7.content = plugins.nodeForge.util.createBuffer(data.toString('latin1'));
+      }
+
+      // Add certificate
+      p7.addCertificate(certificate);
+
+      // Add signer
+      p7.addSigner({
+        key: privateKey,
+        certificate: certificate,
+        digestAlgorithm: plugins.nodeForge.pki.oids.sha256,
+        authenticatedAttributes: [
+          {
+            type: plugins.nodeForge.pki.oids.contentType,
+            value: plugins.nodeForge.pki.oids.data
+          },
+          {
+            type: plugins.nodeForge.pki.oids.messageDigest
+          },
+          {
+            type: plugins.nodeForge.pki.oids.signingTime,
+            value: new Date().toISOString()
+          }
+        ]
+      });
+
+      // Sign the data
+      p7.sign({ detached: true });
+
+      // Convert to PEM
+      const pem = plugins.nodeForge.pkcs7.messageToPem(p7);
+      
+      // Extract base64 signature
+      const signature = pem
+        .replace(/-----BEGIN PKCS7-----/, '')
+        .replace(/-----END PKCS7-----/, '')
+        .replace(/\r?\n/g, '');
+
+      const result: ISignatureResult = {
+        signature: signature,
+        signatureFormat: 'CAdES-B',
+        signingTime: new Date().toISOString(),
+        certificateChain: [cert]
+      };
+
+      // Add timestamp if requested
+      if (this.options.includeTimestamp && this.options.timestampServerUrl) {
+        try {
+          const timestampResponse = await this.requestTimestamp(signature);
+          result.timestampToken = timestampResponse.token;
+          result.timestampTime = timestampResponse.time;
+          result.signatureFormat = 'CAdES-T';
+        } catch (error) {
+          this.logger.log('warn', `Failed to obtain timestamp: ${error}`);
+        }
+      }
+
+      return result;
+    } catch (error) {
+      throw new Error(`Failed to create CAdES signature: ${error}`);
+    }
+  }
+
+  /**
+   * Requests an RFC 3161 timestamp from a TSA
+   */
+  public async requestTimestamp(dataHash: string | Buffer): Promise<ITimestampResponse> {
+    try {
+      // Create hash of the data
+      let hash: Buffer;
+      if (typeof dataHash === 'string') {
+        hash = crypto.createHash('sha256').update(dataHash).digest();
+      } else {
+        hash = crypto.createHash('sha256').update(dataHash).digest();
+      }
+
+      // Create timestamp request (simplified - in production use proper ASN.1 encoding)
+      const tsRequest = this.createTimestampRequest(hash);
+      
+      // Send request to TSA
+      const response = await this.sendTimestampRequest(tsRequest);
+      
+      return {
+        token: response.toString('base64'),
+        time: new Date().toISOString(),
+        serverUrl: this.options.timestampServerUrl!,
+        hashAlgorithm: 'sha256'
+      };
+    } catch (error) {
+      throw new Error(`Failed to obtain timestamp: ${error}`);
+    }
+  }
+
+  /**
+   * Creates a timestamp request (simplified version)
+   */
+  private createTimestampRequest(hash: Buffer): Buffer {
+    // In production, use proper ASN.1 encoding library
+    // This is a simplified placeholder
+    const request = {
+      version: 1,
+      messageImprint: {
+        hashAlgorithm: { algorithm: '2.16.840.1.101.3.4.2.1' }, // SHA-256 OID
+        hashedMessage: hash
+      },
+      reqPolicy: null,
+      nonce: crypto.randomBytes(8),
+      certReq: true
+    };
+    
+    // Convert to DER-encoded ASN.1 (simplified)
+    return Buffer.from(JSON.stringify(request));
+  }
+
+  /**
+   * Sends timestamp request to TSA server
+   */
+  private async sendTimestampRequest(request: Buffer): Promise<Buffer> {
+    return new Promise((resolve, reject) => {
+      const url = new URL(this.options.timestampServerUrl!);
+      
+      const options = {
+        hostname: url.hostname,
+        port: url.port || 443,
+        path: url.pathname,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/timestamp-query',
+          'Content-Length': request.length
+        }
+      };
+
+      const req = https.request(options, (res) => {
+        const chunks: Buffer[] = [];
+        
+        res.on('data', (chunk) => chunks.push(chunk));
+        res.on('end', () => {
+          const response = Buffer.concat(chunks);
+          if (res.statusCode === 200) {
+            resolve(response);
+          } else {
+            reject(new Error(`TSA server returned status ${res.statusCode}`));
+          }
+        });
+      });
+
+      req.on('error', reject);
+      req.write(request);
+      req.end();
+    });
+  }
+
+  /**
+   * Verifies a CAdES signature
+   */
+  public async verifyCadesSignature(
+    data: Buffer | string,
+    signature: string,
+    certificatePem?: string
+  ): Promise<boolean> {
+    try {
+      // Add PEM headers if not present
+      let pemSignature = signature;
+      if (!signature.includes('BEGIN PKCS7')) {
+        pemSignature = `-----BEGIN PKCS7-----\n${signature}\n-----END PKCS7-----`;
+      }
+
+      // Parse the PKCS#7 message
+      const p7 = plugins.nodeForge.pkcs7.messageFromPem(pemSignature);
+      
+      // Prepare content for verification
+      let content: plugins.nodeForge.util.ByteStringBuffer;
+      if (typeof data === 'string') {
+        content = plugins.nodeForge.util.createBuffer(data, 'utf8');
+      } else {
+        content = plugins.nodeForge.util.createBuffer(data.toString('latin1'));
+      }
+
+      // Verify the signature
+      const verified = (p7 as any).verify({ 
+        content: content,
+        detached: true 
+      });
+
+      return verified;
+    } catch (error) {
+      this.logger.log('error', `Signature verification failed: ${error}`);
+      return false;
+    }
+  }
+
+  /**
+   * Generates a self-signed certificate for testing
+   */
+  public async generateSelfSignedCertificate(
+    commonName: string = 'SKR Export System',
+    validDays: number = 365
+  ): Promise<{ certificate: string; privateKey: string }> {
+    const keys = plugins.nodeForge.pki.rsa.generateKeyPair(2048);
+    const cert = plugins.nodeForge.pki.createCertificate();
+    
+    cert.publicKey = keys.publicKey;
+    cert.serialNumber = '01';
+    cert.validity.notBefore = new Date();
+    cert.validity.notAfter = new Date();
+    cert.validity.notAfter.setDate(cert.validity.notAfter.getDate() + validDays);
+    
+    const attrs = [
+      { name: 'commonName', value: commonName },
+      { name: 'countryName', value: 'DE' },
+      { name: 'organizationName', value: 'SKR Export System' },
+      { shortName: 'OU', value: 'Accounting' }
+    ];
+    
+    cert.setSubject(attrs);
+    cert.setIssuer(attrs);
+    
+    cert.setExtensions([
+      {
+        name: 'basicConstraints',
+        cA: true
+      },
+      {
+        name: 'keyUsage',
+        keyCertSign: true,
+        digitalSignature: true,
+        nonRepudiation: true,
+        keyEncipherment: true,
+        dataEncipherment: true
+      },
+      {
+        name: 'extKeyUsage',
+        serverAuth: true,
+        clientAuth: true,
+        codeSigning: true,
+        emailProtection: true,
+        timeStamping: true
+      },
+      {
+        name: 'nsCertType',
+        client: true,
+        server: true,
+        email: true,
+        objsign: true,
+        sslCA: true,
+        emailCA: true,
+        objCA: true
+      },
+      {
+        name: 'subjectAltName',
+        altNames: [
+          { type: 2, value: commonName }
+        ]
+      }
+    ]);
+    
+    // Self-sign certificate
+    cert.sign(keys.privateKey, plugins.nodeForge.md.sha256.create());
+    
+    // Convert to PEM
+    const certificatePem = plugins.nodeForge.pki.certificateToPem(cert);
+    const privateKeyPem = plugins.nodeForge.pki.privateKeyToPem(keys.privateKey);
+    
+    return {
+      certificate: certificatePem,
+      privateKey: privateKeyPem
+    };
+  }
+
+  /**
+   * Creates a detached signature file
+   */
+  public async createDetachedSignature(
+    dataPath: string,
+    outputPath: string
+  ): Promise<void> {
+    const data = await plugins.smartfile.fs.toBuffer(dataPath);
+    const signature = await this.createCadesSignature(data);
+    
+    const signatureData = {
+      signature: signature.signature,
+      format: signature.signatureFormat,
+      signingTime: signature.signingTime,
+      timestamp: signature.timestampToken,
+      timestampTime: signature.timestampTime,
+      algorithm: 'SHA256withRSA',
+      signedFile: path.basename(dataPath)
+    };
+    
+    await plugins.smartfile.memory.toFs(
+      JSON.stringify(signatureData, null, 2),
+      outputPath
+    );
+  }
+
+  /**
+   * Verifies a detached signature file
+   */
+  public async verifyDetachedSignature(
+    dataPath: string,
+    signaturePath: string
+  ): Promise<boolean> {
+    try {
+      const data = await plugins.smartfile.fs.toBuffer(dataPath);
+      const signatureJson = await plugins.smartfile.fs.toStringSync(signaturePath);
+      const signatureData = JSON.parse(signatureJson);
+      
+      return await this.verifyCadesSignature(data, signatureData.signature);
+    } catch (error) {
+      this.logger.log('error', `Failed to verify detached signature: ${error}`);
+      return false;
+    }
+  }
+
+  /**
+   * Adds Long-Term Validation (LTV) information
+   */
+  public async addLtvInformation(
+    signature: ISignatureResult,
+    ocspResponse?: Buffer,
+    crlData?: Buffer
+  ): Promise<ISignatureResult> {
+    // Add OCSP response and CRL data for long-term validation
+    const ltv = {
+      ...signature,
+      signatureFormat: 'CAdES-LT' as const,
+      ocsp: ocspResponse?.toString('base64'),
+      crl: crlData?.toString('base64'),
+      ltvTime: new Date().toISOString()
+    };
+    
+    return ltv;
+  }
+}

package/ts/skr.types.ts

@@ -9,6 +9,18 @@ export type TSKRType = 'SKR03' | 'SKR04';
 
 export type TTransactionStatus = 'pending' | 'posted' | 'reversed';
 
+/**
+ * DATEV posting keys (Buchungsschlüssel) for German accounting
+ * These keys control automatic VAT booking and are checked in tax audits
+ */
+export type TPostingKey =
+  | 3   // Payment with 19% VAT
+  | 8   // 7% input VAT
+  | 9   // 19% input VAT
+  | 19  // 19% input VAT (intra-EU)
+  | 40  // Tax-free (disables VAT automatism)
+  | 94; // 19% input/output VAT (reverse charge)
+
 export type TReportType =
   | 'trial_balance'
   | 'income_statement'
@@ -16,6 +28,18 @@ export type TReportType =
   | 'general_ledger'
   | 'cash_flow';
 
+/**
+ * Posting key validation rule
+ */
+export interface IPostingKeyRule {
+  key: TPostingKey;
+  description: string;
+  vatRate?: number;              // Expected VAT rate (if applicable)
+  requiresVAT: boolean;           // Whether VAT entry is required
+  disablesVATAutomatism: boolean; // Whether this key disables automatic VAT
+  allowedScenarios?: string[];    // Allowed tax scenarios (e.g., 'reverse_charge')
+}
+
 export interface IAccountData {
   accountNumber: string;
   accountName: string;
@@ -25,6 +49,7 @@ export interface IAccountData {
   description?: string;
   vatRate?: number;
   isActive?: boolean;
+  isAutomaticAccount?: boolean; // Automatikkonto (e.g., 1400, 1600) - cannot be posted to directly
 }
 
 export interface ITransactionData {
@@ -53,6 +78,7 @@ export interface IJournalEntryLine {
   credit?: number;
   description?: string;
   costCenter?: string;
+  postingKey: TPostingKey; // REQUIRED: DATEV posting key for VAT automation control
 }
 
 export interface ITrialBalanceEntry {
@@ -136,6 +162,7 @@ export interface ITransactionFilter {
 export interface IDatabaseConfig {
   mongoDbUrl: string;
   dbName?: string;
+  invoiceExportPath?: string; // Optional path for invoice storage
 }
 
 export interface IReportParams {