@fin.cx/skr 1.3.0 → 2.0.0

package/ts/skr.security.ts

@@ -1,8 +1,9 @@
 import * as plugins from './plugins.js';
 import * as path from 'path';
 import * as crypto from 'crypto';
-import * as https from 'https';
+
 import * as nodeForge from 'node-forge';
+import { NotImplementedError } from './skr.errors.js';
 
 export interface ISigningOptions {
   certificatePem?: string;
@@ -115,16 +116,13 @@ export class SecurityManager {
         certificateChain: [cert]
       };
 
-      // Add timestamp if requested
+      // Add timestamp if requested — no silent downgrade: if a timestamp was
+      // asked for and cannot be produced, the signing call fails loudly.
       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}`);
-        }
+        const timestampResponse = await this.requestTimestamp(signature);
+        result.timestampToken = timestampResponse.token;
+        result.timestampTime = timestampResponse.time;
+        result.signatureFormat = 'CAdES-T';
       }
 
       return result;
@@ -134,93 +132,20 @@ export class SecurityManager {
   }
 
   /**
-   * Requests an RFC 3161 timestamp from a TSA
+   * RFC 3161 timestamping — NOT implemented.
+   *
+   * The previous implementation posted a JSON blob pretending to be an ASN.1
+   * TimeStampReq — every real TSA rejects that, and failures were silently
+   * swallowed (fake CAdES-T). Until a real RFC 3161 client (DER-encoded TSQ)
+   * exists, this fails loudly; use CAdES-B (includeTimestamp: false).
    */
   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));
+    void dataHash;
+    throw new NotImplementedError(
+      'RFC 3161 timestamping is not implemented — CAdES-T/LT unavailable, use CAdES-B (includeTimestamp: false)',
+    );
   }
 
-  /**
-   * 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

package/ts/skr.sequence.ts

@@ -0,0 +1,89 @@
+/**
+ * Gapless ledger sequences + hash-chain heads, one document per
+ * (skrType, fiscalYear). This is the only module that touches the raw
+ * MongoDB driver for sequence allocation — everything runs inside the
+ * caller's transaction session, so an aborted posting rolls the $inc back
+ * and gaplessness holds.
+ */
+import { getDbSync, type TDbSession } from './skr.database.js';
+import { genesisHash } from './core/core.hash.js';
+import { SequenceConflictError } from './skr.errors.js';
+import type { TSKRType } from './skr.types.js';
+
+export const LEDGER_SEQUENCE_COLLECTION = 'LedgerSequence';
+
+export interface ILedgerSequenceAllocation {
+  sequenceNumber: number;
+  prevHash: string;
+}
+
+export interface ILedgerSequenceState {
+  skrType: TSKRType;
+  fiscalYear: number;
+  value: number;
+  headHash: string;
+}
+
+function sequenceCollection() {
+  return getDbSync().mongoDb.collection(LEDGER_SEQUENCE_COLLECTION);
+}
+
+export async function ensureSequenceIndexes(): Promise<void> {
+  await sequenceCollection().createIndex({ skrType: 1, fiscalYear: 1 }, { unique: true });
+}
+
+/**
+ * Allocate the next sequence number and return the current chain head.
+ * Must run inside a transaction — the $inc participates in the rollback.
+ */
+export async function allocateSequence(
+  skrType: TSKRType,
+  fiscalYear: number,
+  session: TDbSession,
+): Promise<ILedgerSequenceAllocation> {
+  const genesis = genesisHash(skrType, fiscalYear);
+  const doc = await sequenceCollection().findOneAndUpdate(
+    { skrType, fiscalYear },
+    { $inc: { value: 1 }, $setOnInsert: { headHash: genesis } },
+    { upsert: true, returnDocument: 'after', session },
+  );
+  if (!doc) {
+    throw new Error(`Sequence allocation failed for ${skrType}/${fiscalYear}`);
+  }
+  return { sequenceNumber: doc.value as number, prevHash: doc.headHash as string };
+}
+
+/**
+ * Compare-and-swap the chain head. The filter on the old head serializes
+ * concurrent posters — a lost race aborts the surrounding transaction.
+ */
+export async function advanceHead(
+  skrType: TSKRType,
+  fiscalYear: number,
+  prevHash: string,
+  newHash: string,
+  session: TDbSession,
+): Promise<void> {
+  const result = await sequenceCollection().updateOne(
+    { skrType, fiscalYear, headHash: prevHash },
+    { $set: { headHash: newHash } },
+    { session },
+  );
+  if (result.matchedCount !== 1) {
+    throw new SequenceConflictError(skrType, fiscalYear);
+  }
+}
+
+export async function getSequenceState(
+  skrType: TSKRType,
+  fiscalYear: number,
+): Promise<ILedgerSequenceState | null> {
+  const doc = await sequenceCollection().findOne({ skrType, fiscalYear });
+  if (!doc) return null;
+  return {
+    skrType,
+    fiscalYear,
+    value: doc.value as number,
+    headHash: doc.headHash as string,
+  };
+}

package/ts/skr.txview.ts

@@ -0,0 +1,268 @@
+/**
+ * Bridges between the legacy v1 shapes (float euros, numeric posting keys,
+ * debit/credit account pairs) and the v2 ledger (cents, string BU keys,
+ * per-line Gegenkonto):
+ *
+ * - input converters: ITransactionData / IJournalEntry  ->  core.IJournalDraft
+ * - output projections: v2 JournalEntry (lines)  ->  transaction-shaped views
+ *
+ * The Transaction collection is FROZEN in v2 — these projections are what
+ * keeps transaction-style reads working.
+ */
+import * as plugins from './plugins.js';
+import * as core from './core/index.js';
+import { getDbSync } from './skr.database.js';
+import { JOURNAL_ENTRY_COLLECTION } from './skr.period.js';
+import type {
+  IJournalEntry,
+  IJournalEntryLine,
+  ITransactionData,
+  ITransactionView,
+  IReportParams,
+  TSKRType,
+} from './skr.types.js';
+
+const { centsFromFloat } = plugins.calculation;
+
+/** v1 numeric posting keys that map 1:1 onto the v2 string BU keys */
+const NUMERIC_KEY_MAP: Record<number, core.TBuKey> = {
+  1: '1',
+  2: '2',
+  3: '3',
+  8: '8',
+  9: '9',
+  18: '18',
+  19: '19',
+  40: '40',
+  91: '91',
+  94: '94',
+};
+
+export function mapNumericPostingKey(postingKey?: number): core.TBuKey {
+  if (postingKey === undefined || postingKey === null) return '';
+  return NUMERIC_KEY_MAP[postingKey] ?? '';
+}
+
+/**
+ * v1 postTransaction input -> two-line v2 draft. The amount is NOT split into
+ * net/VAT (v1 semantics: vatAmount was informational) so ledger figures stay
+ * identical across the migration.
+ */
+export function transactionDataToDraft(data: ITransactionData): core.IJournalDraft {
+  const amountCents = centsFromFloat(data.amount);
+  const vatCents = data.vatAmount ? centsFromFloat(data.vatAmount) : 0;
+  const lines: core.IJournalLineDraft[] = [
+    {
+      accountNumber: data.debitAccount,
+      counterAccount: data.creditAccount,
+      side: 'debit',
+      amountCents,
+      buKey: '',
+      buchungstext: data.description,
+      belegfeld1: data.reference,
+      costCenter1: data.costCenter,
+    },
+    {
+      accountNumber: data.creditAccount,
+      counterAccount: data.debitAccount,
+      side: 'credit',
+      amountCents,
+      buKey: '',
+      buchungstext: data.description,
+      belegfeld1: data.reference,
+      costCenter1: data.costCenter,
+    },
+  ];
+  lines[0].vatAmountCents = vatCents;
+  return {
+    date: data.date,
+    description: data.description,
+    reference: data.reference,
+    skrType: data.skrType,
+    currency: 'EUR',
+    lines,
+  };
+}
+
+/**
+ * v1 postJournalEntry input -> v2 draft. Gegenkonto derivation: when one side
+ * of the entry has exactly one line, it is the counter account for every line
+ * of the other side (the dominant v1 usage); otherwise the first line of the
+ * opposite side is used (documented heuristic — v1 stored no Gegenkonto).
+ */
+export function journalInputToDraft(entry: IJournalEntry): core.IJournalDraft {
+  const debitLines = entry.lines.filter((line) => (line.debit ?? 0) > 0);
+  const creditLines = entry.lines.filter((line) => (line.credit ?? 0) > 0);
+  const counterFor = (side: 'debit' | 'credit'): string => {
+    const opposite = side === 'debit' ? creditLines : debitLines;
+    return opposite[0]?.accountNumber ?? '';
+  };
+  const lines: core.IJournalLineDraft[] = entry.lines.map((line) => {
+    const isDebit = (line.debit ?? 0) > 0;
+    return {
+      accountNumber: line.accountNumber,
+      counterAccount: counterFor(isDebit ? 'debit' : 'credit'),
+      side: isDebit ? 'debit' : 'credit',
+      amountCents: centsFromFloat(isDebit ? line.debit! : line.credit!),
+      buKey: mapNumericPostingKey(line.postingKey),
+      buchungstext: line.description ?? entry.description,
+      costCenter1: line.costCenter,
+    };
+  });
+  return {
+    date: entry.date,
+    description: entry.description,
+    reference: entry.reference,
+    skrType: entry.skrType,
+    currency: 'EUR',
+    lines,
+  };
+}
+
+interface IEntryDocLike {
+  id: string;
+  journalNumber?: string;
+  date: Date;
+  description: string;
+  reference?: string;
+  skrType: TSKRType;
+  status: string;
+  period?: string;
+  fiscalYear?: number;
+  postedAt?: Date | null;
+  reversalOf?: string;
+  lines: IJournalEntryLine[];
+}
+
+/**
+ * Project a two-line v2 entry back into the classic transaction shape.
+ * Returns null for entries with more than two lines (journal-only view).
+ */
+export function entryToTransactionView(entry: IEntryDocLike): ITransactionView | null {
+  const debitLine = entry.lines.find((line) => line.side === 'debit');
+  const creditLine = entry.lines.find((line) => line.side === 'credit');
+  if (!debitLine || !creditLine || entry.lines.length !== 2) return null;
+  return {
+    id: entry.id,
+    transactionNumber: entry.journalNumber ?? entry.id,
+    date: entry.date,
+    debitAccount: debitLine.accountNumber,
+    creditAccount: creditLine.accountNumber,
+    amount: (debitLine.amountCents ?? 0) / 100,
+    vatAmount: (debitLine.vatAmountCents ?? 0) / 100,
+    description: entry.description,
+    reference: entry.reference ?? '',
+    skrType: entry.skrType,
+    status: entry.status,
+    period: entry.period ?? '',
+    fiscalYear: entry.fiscalYear ?? entry.date.getUTCFullYear(),
+    costCenter: debitLine.costCenter1 ?? creditLine.costCenter1,
+    reversalOf: entry.reversalOf,
+  };
+}
+
+function dayRange(params?: IReportParams): { from: Date | null; to: Date | null } {
+  const from = params?.dateFrom ? new Date(params.dateFrom) : null;
+  const to = params?.dateTo ? new Date(params.dateTo) : null;
+  if (from) from.setHours(0, 0, 0, 0);
+  if (to) to.setHours(23, 59, 59, 999);
+  return { from, to };
+}
+
+/**
+ * Load v2 entries of a date range as core drafts (for DATEV export).
+ */
+export async function loadDraftsForExport(
+  skrType: TSKRType,
+  dateFrom: Date,
+  dateTo: Date,
+): Promise<core.IJournalDraft[]> {
+  const docs = await getDbSync()
+    .mongoDb.collection(JOURNAL_ENTRY_COLLECTION)
+    .find({
+      skrType,
+      schemaVersion: 2,
+      status: { $in: ['posted', 'finalized'] },
+      date: { $gte: dateFrom, $lte: dateTo },
+    })
+    .sort({ sequenceNumber: 1 })
+    .toArray();
+  return docs.map((doc) => {
+    const entry = doc as unknown as IEntryDocLike;
+    return {
+      date: entry.date,
+      description: entry.description,
+      reference: entry.reference,
+      skrType: entry.skrType,
+      currency: 'EUR' as const,
+      lines: entry.lines.map((line) => ({
+        accountNumber: line.accountNumber,
+        counterAccount: line.counterAccount ?? '',
+        side: (line.side ?? 'debit') as 'debit' | 'credit',
+        amountCents: line.amountCents ?? 0,
+        buKey: (line.buKey ?? '') as core.TBuKey,
+        buchungstext: line.buchungstext ?? entry.description,
+        belegfeld1: line.belegfeld1,
+        costCenter1: line.costCenter1,
+        docLink: line.docLink,
+      })),
+    };
+  });
+}
+
+/**
+ * Per-account activity as transaction-shaped line views from v2 entries —
+ * the data source for reports (trial balance, general ledger, cash flow).
+ * Each view carries the line's own side and its Gegenkonto.
+ */
+export async function accountLineViews(
+  accountNumber: string,
+  skrType: TSKRType,
+  params?: IReportParams,
+): Promise<ITransactionView[]> {
+  const { from, to } = dayRange(params);
+  const match: Record<string, unknown> = {
+    skrType,
+    schemaVersion: 2,
+    status: { $in: ['posted', 'finalized'] },
+    'lines.accountNumber': accountNumber,
+  };
+  if (from || to) {
+    const range: Record<string, Date> = {};
+    if (from) range.$gte = from;
+    if (to) range.$lte = to;
+    match.date = range;
+  }
+  const docs = await getDbSync()
+    .mongoDb.collection(JOURNAL_ENTRY_COLLECTION)
+    .find(match)
+    .sort({ date: 1, sequenceNumber: 1 })
+    .toArray();
+
+  const views: ITransactionView[] = [];
+  for (const doc of docs) {
+    const entry = doc as unknown as IEntryDocLike;
+    for (const line of entry.lines) {
+      if (line.accountNumber !== accountNumber) continue;
+      const isDebit = line.side === 'debit';
+      views.push({
+        id: entry.id,
+        transactionNumber: entry.journalNumber ?? entry.id,
+        date: entry.date,
+        debitAccount: isDebit ? accountNumber : line.counterAccount ?? '',
+        creditAccount: isDebit ? line.counterAccount ?? '' : accountNumber,
+        amount: (line.amountCents ?? 0) / 100,
+        vatAmount: (line.vatAmountCents ?? 0) / 100,
+        description: line.buchungstext ?? entry.description,
+        reference: entry.reference ?? '',
+        skrType: entry.skrType,
+        status: entry.status,
+        period: entry.period ?? '',
+        fiscalYear: entry.fiscalYear ?? entry.date.getUTCFullYear(),
+        costCenter: line.costCenter1,
+        reversalOf: entry.reversalOf,
+      });
+    }
+  }
+  return views;
+}

package/ts/skr.types.ts

@@ -78,7 +78,43 @@ export interface IJournalEntryLine {
   credit?: number;
   description?: string;
   costCenter?: string;
-  postingKey: TPostingKey; // REQUIRED: DATEV posting key for VAT automation control
+  /** v1 numeric DATEV posting key; optional since schemaVersion 2 (see buKey) */
+  postingKey?: TPostingKey;
+  // --- schemaVersion 2 fields (exact cents, explicit side and Gegenkonto) ---
+  side?: 'debit' | 'credit';
+  amountCents?: number;
+  counterAccount?: string;
+  /** string-typed DATEV BU-Schlüssel ('' = none) */
+  buKey?: string;
+  buchungstext?: string;
+  belegfeld1?: string;
+  costCenter1?: string;
+  docLink?: string;
+  /** informational VAT share carried on the line (v1 compatibility) */
+  vatAmountCents?: number;
+}
+
+/**
+ * Transaction-shaped projection of a v2 journal entry (or one of its lines).
+ * The Transaction collection is frozen in v2 — reads go through these views.
+ */
+export interface ITransactionView {
+  id: string;
+  transactionNumber: string;
+  date: Date;
+  debitAccount: string;
+  creditAccount: string;
+  amount: number;
+  vatAmount: number;
+  description: string;
+  reference: string;
+  skrType: TSKRType;
+  status: string;
+  period: string;
+  fiscalYear: number;
+  costCenter?: string;
+  /** id of the entry this one reverses (Storno linkage) */
+  reversalOf?: string;
 }
 
 export interface ITrialBalanceEntry {

package/ts/skr.verify.ts

@@ -0,0 +1,99 @@
+/**
+ * Cryptographic audit-trail verification. Prevention of tampering is
+ * best-effort (doc-level guards); detection is this module: recompute the
+ * whole hash chain from the persisted entries and compare against the stored
+ * chain head.
+ */
+import * as core from './core/index.js';
+import { getDbSync } from './skr.database.js';
+import { JOURNAL_ENTRY_COLLECTION } from './skr.period.js';
+import { getSequenceState } from './skr.sequence.js';
+import { buildHashPayload } from './skr.posting.js';
+import type { TSKRType } from './skr.types.js';
+
+export interface IChainVerificationResult {
+  valid: boolean;
+  entriesChecked: number;
+  issues: string[];
+  headHash: string | null;
+}
+
+/**
+ * Walk sequence 1..N for (skrType, fiscalYear): check gaplessness, recompute
+ * every entry hash from the persisted payload, verify the chain links, and
+ * compare the final hash against the stored chain head.
+ */
+export async function verifyHashChain(
+  skrType: TSKRType,
+  fiscalYear: number,
+): Promise<IChainVerificationResult> {
+  const issues: string[] = [];
+  const collection = getDbSync().mongoDb.collection(JOURNAL_ENTRY_COLLECTION);
+  const docs = await collection
+    .find({ skrType, fiscalYear, schemaVersion: 2 })
+    .sort({ sequenceNumber: 1 })
+    .toArray();
+
+  const state = await getSequenceState(skrType, fiscalYear);
+  if (docs.length === 0) {
+    return {
+      valid: !state || state.value === 0,
+      entriesChecked: 0,
+      issues: state && state.value !== 0 ? [`sequence counter is ${state.value} but no entries exist`] : [],
+      headHash: state?.headHash ?? null,
+    };
+  }
+
+  // gaplessness
+  docs.forEach((doc, index) => {
+    const expected = index + 1;
+    if (doc.sequenceNumber !== expected) {
+      issues.push(`sequence gap: expected ${expected}, found ${doc.sequenceNumber}`);
+    }
+  });
+
+  // chain
+  const genesis = core.genesisHash(skrType, fiscalYear);
+  const chain = docs.map((doc) => ({
+    sequenceNumber: doc.sequenceNumber as number,
+    prevHash: doc.prevHash as string,
+    entryHash: doc.entryHash as string,
+    payload: buildHashPayload({
+      sequenceNumber: doc.sequenceNumber as number,
+      skrType: doc.skrType as string,
+      fiscalYear: doc.fiscalYear as number,
+      date: doc.date as Date,
+      postedAt: doc.postedAt as Date,
+      description: doc.description as string,
+      reference: doc.reference as string,
+      taxScenario: doc.taxScenario as string,
+      currency: doc.currency as string,
+      reversalOf: doc.reversalOf as string,
+      lines: (doc.lines ?? []) as never[],
+    }),
+  }));
+  const failure = core.verifyChain(chain, genesis);
+  if (failure) {
+    issues.push(failure.reason);
+  }
+
+  // head comparison
+  const lastHash = chain[chain.length - 1].entryHash;
+  if (!state) {
+    issues.push('no sequence state document found');
+  } else {
+    if (state.headHash !== lastHash) {
+      issues.push(`stored chain head ${state.headHash} !== last entry hash ${lastHash}`);
+    }
+    if (state.value !== docs.length) {
+      issues.push(`sequence counter ${state.value} !== entry count ${docs.length}`);
+    }
+  }
+
+  return {
+    valid: issues.length === 0,
+    entriesChecked: docs.length,
+    issues,
+    headHash: state?.headHash ?? null,
+  };
+}