@kreiseck/kasseneck-api 0.6.46 → 0.7.0

package/dist/cjs/partner/typen.d.ts

@@ -0,0 +1,399 @@
+/**
+ * Die Formen, die die Partner-API sendet und zurueckgibt.
+ *
+ * **Die Referenz ist das Backend**, nicht diese Datei: `docs/api/partner.md`
+ * (ausfuehrlich) und `docs/api/partner.llms.txt` (kompakt) beschreiben Felder,
+ * Fehlercodes und Ereignisse. Hier stehen sie als Typen, damit ein Aufrufer
+ * beim Tippen sieht, was es gibt — nicht als zweiter Text daneben.
+ *
+ * **Lesen ist tolerant, Schreiben ist streng.** Antworttypen fuehren `null`
+ * dort, wo das Backend `null` schickt, und lassen unbekannte Statuswerte als
+ * `string` durch (`(string & {})`): eine Fassung, die einen neuen Status
+ * einfuehrt, soll diesen Client nicht zum Absturz bringen, sondern ihn
+ * durchreichen. Eingabetypen sind dagegen eng — ein Tippfehler soll ein
+ * Compilerfehler sein und keine `validation`-Antwort vom Server.
+ */
+import type { KasseneckSecret } from './secret.js';
+/**
+ * Die beiden Umgebungen. Als Liste und nicht nur als Typ, damit ein Aufrufer
+ * sie zur Laufzeit pruefen kann — und damit der Zwilling sie nachhaelt.
+ */
+export declare const PARTNER_ENVS: readonly ["live", "test"];
+/** Umgebung, in der ein Partner-Schluessel bzw. ein Betrieb lebt. */
+export type PartnerEnv = typeof PARTNER_ENVS[number];
+/** Berechtigungen eines Partner-Schluessels. */
+export type PartnerScope = 'partner:read' | 'customers:read' | 'customers:write' | 'webhooks:read' | 'webhooks:write' | 'credentials:read' | (string & {});
+/**
+ * `credentials:read` gehoert **nicht** zum Standardsatz und wird keinem
+ * bestehenden Schluessel nachtraeglich hinzugefuegt: wer ihn hat, kann im Namen
+ * fremder Betriebe Belege signieren. Dafuer wird ein eigener Schluessel
+ * angelegt.
+ */
+export declare const SCOPE_CREDENTIALS: PartnerScope;
+export interface PartnerApp {
+    id: string;
+    name: string;
+    status: string;
+    platform: string | null;
+    distributions: unknown[];
+    platforms: string[];
+    symbol: {
+        url: string;
+    } | null;
+    published: boolean;
+    listingAllowed: boolean;
+}
+export interface PartnerInfo {
+    partner: {
+        id: string;
+        name: string;
+        status: string;
+        /**
+         * Darf dieser Partner fuer seine Betriebe einen Zugang zum Kundenpanel
+         * einrichten lassen? **Vorgabe `false`** — die Freischaltung setzt
+         * Kasseneck je Partner. Ohne sie antworten `access:{invite:true}` und
+         * `resendPartnerCustomerInvite` mit `zugang_nicht_erlaubt`, und es
+         * entsteht nichts, auch kein Betrieb.
+         */
+        canCreateAccess: boolean;
+    };
+    env: PartnerEnv;
+    scopes: PartnerScope[];
+    key: {
+        hint: string | null;
+        label: string | null;
+        createdAt: number | null;
+        scopes: PartnerScope[];
+    };
+    apps: PartnerApp[];
+}
+export type Rechtsform = 'einzel' | 'eu' | 'og' | 'kg' | 'gmbh' | 'gmbhcokg' | 'ag' | 'verein' | 'sonstige';
+export type Bundesland = 'burgenland' | 'kaernten' | 'niederoesterreich' | 'oberoesterreich' | 'salzburg' | 'steiermark' | 'tirol' | 'vorarlberg' | 'wien';
+export type KontaktRolle = 'geschaeftsfuehrung' | 'buchhaltung' | 'technik' | 'kasse';
+export interface BetriebAdresse {
+    street: string;
+    /** Hausnummer, kurz und alphanumerisch: `49`, `12a`, `49/5`. */
+    number?: string;
+    /** Oesterreichische Postleitzahl, vier Ziffern. */
+    zip: string;
+    city: string;
+}
+export interface BetriebSteuer {
+    /** Steuernummer im Format `12-345/6789`; die Pruefziffer wird geprueft. */
+    taxNumber: string;
+    smallBusiness: boolean;
+    /** UID, z. B. `ATU12345675`. */
+    uid?: string;
+    /** GLN, 13 Ziffern. */
+    gln?: string;
+}
+export interface BetriebKontakt {
+    name: string;
+    email: string;
+    phone?: string;
+    roles?: KontaktRolle[];
+}
+export interface BetriebSteuerberater {
+    name: string;
+    email: string;
+    phone: string;
+    mayContact: boolean;
+}
+/**
+ * Die Stammdaten eines Betriebs. Geprueft wird mit denselben Regeln wie in
+ * Kasseneckens eigener Kundenaufnahme (`@kreiseck/validator`); bei einem
+ * Formfehler entsteht **nichts** — die Antwort traegt `code:"validation"` und
+ * `data.errors[{field,message}]`.
+ *
+ * **Genau diese Felder, kein weiteres.** Das Backend weist ein unbekanntes
+ * Feld ab, statt es stillschweigend zu verwerfen, und nennt seinen vollen
+ * Pfad (`address.land`, `contacts.0.rolle`). Deshalb hat dieser Typ dieselbe
+ * Liste wie `partner-core.BETRIEB_FELDER` — ein ueberzaehliges Feld ist hier
+ * ein Compilerfehler und nicht erst eine Antwort vom Server. Fuer Daten, die
+ * nicht durch die Typpruefung kommen (Datenbank, Formular), beantwortet
+ * [unbekannteBetriebsfelder] dieselbe Frage zur Laufzeit.
+ */
+export interface Betrieb {
+    companyName: string;
+    legalForm: Rechtsform;
+    /** Anmeldung des Betriebs im Kasseneck-Panel; darf dort noch keinen Zugang haben. */
+    email: string;
+    address: BetriebAdresse;
+    state: Bundesland;
+    taxDetails: BetriebSteuer;
+    /** Mindestens einer, hoechstens zehn. */
+    contacts: BetriebKontakt[];
+    billingEmail?: string;
+    /** Firmenbuchnummer, z. B. `FN 123456 a`. */
+    companyRegister?: string;
+    /** Gericht: Code (`LG_SALZBURG`), amtlicher Name oder Freitext. */
+    court?: string;
+    web?: string;
+    phone?: string;
+    industry?: string;
+    taxAdvisor?: BetriebSteuerberater;
+}
+export interface CreateCustomerOptions {
+    appId: string;
+    business: Betrieb;
+    /**
+     * Eigener Schluessel gegen Doppelanlage, hoechstens 120 Zeichen. Derselbe
+     * Schluessel liefert die gespeicherte Antwort zurueck — auch bei abweichendem
+     * Rumpf. Die eigene Kundennummer ist der natuerliche Wert dafuer.
+     */
+    idempotencyKey?: string;
+    /**
+     * `invite:true` legt zusaetzlich einen Zugang zum Kundenpanel an und
+     * schickt die Einladung an `betrieb.email`. **Vorgabe ist `false`:** viele
+     * Betriebe arbeiten ausschliesslich in der App des Partners, und ein
+     * stillschweigend erzeugter Login samt Mail waere dort etwas, das niemand
+     * erwartet. Nachholen laesst er sich mit `resendPartnerCustomerInvite`.
+     *
+     * Nur erlaubt, wenn `getPartnerInfo().partner.canCreateAccess` gilt —
+     * sonst `zugang_nicht_erlaubt`, und es entsteht nichts, auch kein Betrieb.
+     */
+    access?: {
+        invite: boolean;
+    };
+    /**
+     * In welcher Umgebung der Betrieb entsteht. Ohne Angabe entscheidet der
+     * Schluessel.
+     *
+     * Ein LIVE-Schluessel darf `env:"test"` verlangen — das ist der vorgesehene
+     * Weg, die ganze Kette zu proben, ohne sich einen zweiten Schluessel zu
+     * holen. Umgekehrt nie: ein Test-Schluessel mit `env:"live"` bekommt
+     * `live_not_allowed`, und es entsteht nichts.
+     *
+     * Ein so angelegter Live-Betrieb ist **sofort freigeschaltet** und traegt das
+     * Modul `registrierkasse`; es wird auf keine Freigabe durch Kasseneck
+     * gewartet.
+     */
+    env?: PartnerEnv;
+}
+export type KundenStatus = 'created' | 'fon_configured' | 'signature_requested' | 'signature_ready' | 'cashregister_created' | 'live' | 'blocked' | (string & {});
+export interface CreateCustomerResult {
+    customerId: string;
+    status: KundenStatus;
+    env: PartnerEnv;
+    companyName: string;
+    appId: string;
+    access: {
+        invited: boolean;
+        sentTo: string | null;
+    };
+    nextSteps: string[];
+    /** `true`, wenn derselbe `idempotencyKey` schon einmal ankam. */
+    replayed: boolean;
+}
+/**
+ * Stand des Auftragsverarbeitungsvertrags eines Betriebs.
+ *
+ * **Vertraege wirken im Partner-Weg nicht mehr** (Stand 2026-08-31): keine
+ * Antwort fuehrt dieses Feld, kein Schritt in `naechsteSchritte` verlangt
+ * einen Vertrag, und eine Kasse geht deswegen nicht weniger live. Der Typ
+ * bleibt, damit eine Antwort, die ihn doch noch traegt, lesbar durchkommt —
+ * **vorausgesetzt wird er nirgends**. Fuer selbst registrierte Kunden gibt es
+ * die Maschinerie weiterhin, aber nicht ueber diese Schnittstelle.
+ */
+export interface AvvStand {
+    status: string;
+    version: string | null;
+    confirmedAt: number | null;
+    mode: string | null;
+}
+export interface KundenZeile {
+    customerId: string;
+    companyName: string;
+    status: KundenStatus;
+    appId: string | null;
+    env: PartnerEnv;
+    createdAt: number | null;
+    /**
+     * Vertragsstand, falls die Antwort ihn ueberhaupt fuehrt — heute tut sie das
+     * nicht, der Wert ist dann `null`. Siehe [AvvStand]: nichts in diesem Client
+     * setzt ihn voraus.
+     */
+    avv: AvvStand | null;
+}
+export interface ListCustomersOptions {
+    status?: KundenStatus;
+    /** 1 bis 200; Vorgabe 50. */
+    limit?: number;
+    cursor?: string;
+}
+export interface KundenListe {
+    customers: KundenZeile[];
+    /** Weiter mit diesem Wert als `cursor`; `null` heisst: das war alles. */
+    cursor: string | null;
+    total: number;
+}
+export interface Kunde extends KundenZeile {
+    statusAt: number | null;
+    liveEnabled: boolean;
+    createdAt: number | null;
+    createdVia: string | null;
+    business: Record<string, unknown>;
+    fon: {
+        configured: boolean;
+        verifiedAt: number | null;
+    };
+    access: {
+        email: string | null;
+        invitedAt: number | null;
+        acceptedAt: number | null;
+    } | null;
+}
+export interface FonLinkResult {
+    customerId: string;
+    /** Empfaenger, maskiert — das Backend gibt die Adresse nie im Klartext aus. */
+    sentTo: string;
+    expiresAt: number;
+}
+/**
+ * `beantragt → zugeteilt → registriert → bereit`. `registriert` heisst: die
+ * Einheit ist FinanzOnline bekannt; `bereit` heisst: sie darf signieren. In der
+ * Testumgebung wird ohne `registriert` direkt `bereit` erreicht.
+ */
+export type SignaturAntragStatus = 'requested' | 'assigned' | 'registered' | 'ready' | 'failed' | 'cancelled' | (string & {});
+export interface SignaturHistorieEintrag {
+    von: string | null;
+    nach: string;
+    at: number;
+    reason: string | null;
+}
+export interface SignaturAntrag {
+    requestId: string;
+    status: SignaturAntragStatus;
+    statusText: string;
+    art: string;
+    vdaId: string | null;
+    signatureId: string | null;
+    error: {
+        code: string | null;
+        message: string | null;
+        rc: string | null;
+    } | null;
+    requestedVia: string | null;
+    createdAt: number | null;
+    updatedAt: number | null;
+    history: SignaturHistorieEintrag[];
+}
+export interface RequestSignatureResult {
+    request: SignaturAntrag;
+    /** `true`, wenn schon ein Antrag lief — dann ist es der laufende. */
+    replayed: boolean;
+    note: string | null;
+}
+export interface SignaturStand {
+    signatur: {
+        ready: boolean;
+        signatureId: string | null;
+        vdaId: string | null;
+    };
+    requests: SignaturAntrag[];
+    fon: {
+        present: boolean;
+        verifiedAt: number | null;
+    };
+}
+/** Die Schritte der Inbetriebnahme, in dieser Reihenfolge. */
+export type KassenSchritt = 'signatur' | 'register_cashregister' | 'start_receipt' | 'transmit_start_receipt' | (string & {});
+export type KassenStatus = 'draft' | 'laeuft' | 'live' | 'failed' | (string & {});
+export interface Kasse {
+    cashregisterId: string;
+    name: string | null;
+    status: KassenStatus;
+    statusText: string;
+    /** `true`: die Kasse geht von selbst live, sobald die Signatur bereit ist. */
+    automatic: boolean;
+    /** Der naechste offene Schritt; `null`, wenn die Kasse live ist. */
+    step: KassenSchritt | null;
+    stepText: string | null;
+    completedSteps: KassenSchritt[];
+    /** Die Schritte, die fuer genau diese Kasse gelten (Testumgebung: weniger). */
+    steps: {
+        key: KassenSchritt;
+        text: string;
+    }[];
+    signatureId: string | null;
+    attempts: number;
+    lastError: {
+        code: string | null;
+        message: string | null;
+        rc: string | null;
+        step: KassenSchritt | null;
+        at: number | null;
+    } | null;
+    createdAt: number | null;
+}
+export interface CreateCashregisterOptions {
+    customerId: string;
+    /** Vorgabe `true`: die Kasse geht von selbst live, sobald die Signatur da ist. */
+    automatic?: boolean;
+    /**
+     * Auf welche Signatur sich die Kasse bezieht. **Jede Kasse bezieht sich auf
+     * eine**; ohne eine einzige entsteht keine (`signature_missing`).
+     *
+     * Hat der Betrieb genau eine, ist sie vorausgewaehlt und dieses Feld
+     * ueberfluessig. Bei mehreren muss es dastehen, sonst `signature_ambiguous`
+     * samt `data.choices[]`; eine fremde Kennung ist `signature_unknown`. Die
+     * Kennungen nennt `getCustomerSignatureStatus`.
+     *
+     * **Einen Namen gibt es hier nicht.** Kassennamen vergibt Kasseneck, sie
+     * sind gleich der `cashregisterId`; ein mitgesendetes `name` waere ein
+     * `validation`-Fehler.
+     */
+    signatureRequestId?: string;
+}
+export interface CreateCashregisterResult {
+    cashregister: Kasse;
+    activation: {
+        started: boolean;
+        ok: boolean | null;
+        step: KassenSchritt | null;
+        /** `signature_not_ready` oder `automatik_aus`, wenn nicht gestartet wurde. */
+        reason: string | null;
+    };
+}
+export interface ActivateCashregisterResult {
+    cashregister: Kasse;
+    /** `true`: die Kasse war schon live, es wurde nichts getan. */
+    unchanged: boolean;
+}
+export interface KassenListe {
+    customerId: string;
+    cashregisters: Kasse[];
+    signatureReady: boolean;
+}
+/**
+ * Eine Kasse samt ihrem Token. **Der Token ist ein Geheimnis des Betriebs** —
+ * deshalb steht er als [KasseneckSecret] und nicht als `string` darin.
+ */
+export interface CustomerCashregisterCredential {
+    cashregisterId: string;
+    name: string | null;
+    live: boolean;
+    /** Kopfzeile `cashregister-token` fuer `createReceipt`. Verschluesselt speichern. */
+    cashregisterToken: KasseneckSecret;
+}
+/**
+ * Die beiden Geheimnisse, die eine App braucht, um im Namen des Betriebs
+ * Belege zu signieren.
+ *
+ * **Nur verschluesselt speichern. Nie protokollieren, nie in eine Mail, nie in
+ * einen Fehlerbericht.** Jeder Abruf wird mitgeschrieben (Partner, Schluessel,
+ * Zeitpunkt) und ist fuer den Betrieb und fuer Kasseneck sichtbar.
+ *
+ * Die Werte stecken in [KasseneckSecret]: `console.log`, `JSON.stringify` und
+ * jede Zeichenketten-Umwandlung zeigen eine Maske. Heraus kommt man nur ueber
+ * `.reveal()` — und genau diese Stellen findet eine Suche.
+ */
+export interface CustomerCredentials {
+    customerId: string;
+    companyName: string;
+    env: PartnerEnv;
+    /** Bearer-Schluessel des Betriebs (`kr_…`). Verschluesselt speichern. */
+    apiKey: KasseneckSecret;
+    cashregisters: CustomerCashregisterCredential[];
+    note: string;
+}

package/dist/cjs/partner/typen.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Die Formen, die die Partner-API sendet und zurueckgibt.
+ *
+ * **Die Referenz ist das Backend**, nicht diese Datei: `docs/api/partner.md`
+ * (ausfuehrlich) und `docs/api/partner.llms.txt` (kompakt) beschreiben Felder,
+ * Fehlercodes und Ereignisse. Hier stehen sie als Typen, damit ein Aufrufer
+ * beim Tippen sieht, was es gibt — nicht als zweiter Text daneben.
+ *
+ * **Lesen ist tolerant, Schreiben ist streng.** Antworttypen fuehren `null`
+ * dort, wo das Backend `null` schickt, und lassen unbekannte Statuswerte als
+ * `string` durch (`(string & {})`): eine Fassung, die einen neuen Status
+ * einfuehrt, soll diesen Client nicht zum Absturz bringen, sondern ihn
+ * durchreichen. Eingabetypen sind dagegen eng — ein Tippfehler soll ein
+ * Compilerfehler sein und keine `validation`-Antwort vom Server.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCOPE_CREDENTIALS = exports.PARTNER_ENVS = void 0;
+// ---------------------------------------------------------------------------
+// Partner und Schluessel
+// ---------------------------------------------------------------------------
+/**
+ * Die beiden Umgebungen. Als Liste und nicht nur als Typ, damit ein Aufrufer
+ * sie zur Laufzeit pruefen kann — und damit der Zwilling sie nachhaelt.
+ */
+exports.PARTNER_ENVS = ['live', 'test'];
+/**
+ * `credentials:read` gehoert **nicht** zum Standardsatz und wird keinem
+ * bestehenden Schluessel nachtraeglich hinzugefuegt: wer ihn hat, kann im Namen
+ * fremder Betriebe Belege signieren. Dafuer wird ein eigener Schluessel
+ * angelegt.
+ */
+exports.SCOPE_CREDENTIALS = 'credentials:read';

package/dist/cjs/partner/webhook-signatur.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Pruefung der Signatur eingehender Kasseneck-Webhooks.
+ *
+ * **Das ist der Teil, den Integratoren am haeufigsten falsch bauen** — und der
+ * einzige, bei dem ein Fehler nicht auffaellt: eine zu lasche Pruefung laesst
+ * jeden durch, der die Adresse kennt, und meldet dabei nie etwas. Deshalb
+ * liegt sie fertig im Paket und nicht als Beispielschnipsel in der Doku.
+ *
+ * Vier Dinge muessen stimmen, und jedes einzelne fehlt in der Praxis regelmaessig:
+ *
+ * 1. **Der ROHE Rumpf.** Signiert werden die Bytes, die ankommen — nicht das
+ *    Ergebnis von `JSON.parse` und erneutem `JSON.stringify`. Schluesselreihen-
+ *    folge, Zahlenschreibweise und Leerraum aendern sich dabei, und die
+ *    Signatur passt nicht mehr. In Express heisst das `express.raw({type:'*​/*'})`
+ *    **vor** jedem JSON-Parser fuer diesen Pfad.
+ * 2. **Das Zeitfenster.** Ohne Pruefung von `t` ist eine einmal mitgeschnittene,
+ *    gueltig signierte Zustellung fuer immer wiederverwendbar. 300 Sekunden in
+ *    beide Richtungen — auch in die Zukunft, sonst hilft eine falsch gestellte
+ *    Uhr auf der Gegenseite dem Angreifer.
+ * 3. **Der zeitkonstante Vergleich.** Ein `===` auf Hex-Zeichenketten bricht
+ *    beim ersten abweichenden Zeichen ab. Wer messen kann, wie lange die
+ *    Ablehnung dauert, raet die Signatur Zeichen fuer Zeichen.
+ * 4. **Jede Ausnahme ist eine Ablehnung.** Ein `catch`, das weiterlaufen laesst,
+ *    macht aus einem Formfehler ein Ja.
+ *
+ * Der Kopf lautet `X-Kasseneck-Signature: t=<unix-sekunden>,v1=<hex>` mit
+ * `v1 = HMAC-SHA256(secret, "<t>.<roher Rumpf>")`. **Mehrere `v1=`-Anteile sind
+ * erlaubt** — so laeuft ein Schluesselwechsel ohne Zustellungsluecke; es reicht,
+ * wenn einer passt.
+ *
+ * Umgesetzt mit WebCrypto (`crypto.subtle`) statt `node:crypto`: dieses Paket
+ * haengt an keiner Laufzeit-Abhaengigkeit und wird auch fuer den Browser
+ * gebuendelt. Deshalb ist die Pruefung **asynchron**.
+ */
+/** Der Kopf, in dem die Signatur steht. */
+export declare const WEBHOOK_SIGNATURE_HEADER = "X-Kasseneck-Signature";
+/** Der Kopf mit dem Ereignisnamen (dasselbe wie `body.type`). */
+export declare const WEBHOOK_EVENT_HEADER = "X-Kasseneck-Event";
+/** Der Kopf mit der Zustell-Kennung — bei Wiederholungen **dieselbe**. */
+export declare const WEBHOOK_DELIVERY_HEADER = "X-Kasseneck-Delivery";
+/** Erlaubte Abweichung des Zeitstempels, in Sekunden (in beide Richtungen). */
+export declare const WEBHOOK_TOLERANCE_SEC = 300;
+/** Wartezeiten zwischen den Zustellversuchen, in Sekunden. */
+export declare const WEBHOOK_RETRY_PLAN_SEC: readonly number[];
+/** Erstversuch plus je eine Wiederholung pro Planeintrag. */
+export declare const WEBHOOK_MAX_ATTEMPTS: number;
+/** So lange wartet Kasseneck auf eine 2xx-Antwort. */
+export declare const WEBHOOK_TIMEOUT_MS = 10000;
+/** Hoechstzahl der Webhook-Endpunkte je Partner. */
+export declare const WEBHOOK_LIMIT = 10;
+/** Warum eine Zustellung abgelehnt wurde. Jeder Grund ist ein Nein. */
+export type WebhookVerifyReason = 'secret-missing' | 'header-missing' | 'header-malformed' | 'body-missing' | 'timestamp-outside-window' | 'signature-mismatch';
+export type WebhookVerifyResult = {
+    ok: true;
+    timestampSec: number;
+} | {
+    ok: false;
+    reason: WebhookVerifyReason;
+};
+export interface VerifyWebhookOptions {
+    /**
+     * Das Secret aus `createPartnerWebhook` — es verlaesst den Server genau
+     * einmal. Eine Liste erlaubt den Schluesselwechsel: es reicht, wenn einer
+     * passt.
+     */
+    secret: string | readonly string[];
+    /** Der Wert des Kopfes `X-Kasseneck-Signature`, unveraendert. */
+    signatureHeader: string | null | undefined;
+    /**
+     * Der **rohe** Rumpf — Bytes oder die daraus gelesene Zeichenkette. Nicht
+     * das Ergebnis von `JSON.parse`, und nichts, was danach wieder
+     * zusammengesetzt wurde.
+     */
+    body: string | Uint8Array;
+    /** Jetzt, in Unix-Sekunden. Vorgabe: die Systemuhr. Fuer Tests setzbar. */
+    nowSec?: number;
+    /** Abweichender Toleranzrahmen in Sekunden; Vorgabe [WEBHOOK_TOLERANCE_SEC]. */
+    toleranceSec?: number;
+}
+/**
+ * Prueft die Signatur einer eingehenden Zustellung.
+ *
+ * Antwortet **nie** mit einem geworfenen Fehler auf schlechte Eingaben: jede
+ * Ausnahme im Inneren wird zur Ablehnung. Ein Aufrufer, der nur `ok` abfragt,
+ * kann damit nichts falsch machen.
+ */
+export declare function verifyWebhookSignature(optionen: VerifyWebhookOptions): Promise<WebhookVerifyResult>;
+/**
+ * Zerlegt den Signaturkopf. `null`, wenn kein brauchbarer Zeitstempel oder gar
+ * kein `v1=`-Anteil darin steht.
+ */
+export declare function parseSignatureHeader(kopf: string): {
+    t: number;
+    v1: string[];
+} | null;

package/dist/cjs/partner/webhook-signatur.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * Pruefung der Signatur eingehender Kasseneck-Webhooks.
+ *
+ * **Das ist der Teil, den Integratoren am haeufigsten falsch bauen** — und der
+ * einzige, bei dem ein Fehler nicht auffaellt: eine zu lasche Pruefung laesst
+ * jeden durch, der die Adresse kennt, und meldet dabei nie etwas. Deshalb
+ * liegt sie fertig im Paket und nicht als Beispielschnipsel in der Doku.
+ *
+ * Vier Dinge muessen stimmen, und jedes einzelne fehlt in der Praxis regelmaessig:
+ *
+ * 1. **Der ROHE Rumpf.** Signiert werden die Bytes, die ankommen — nicht das
+ *    Ergebnis von `JSON.parse` und erneutem `JSON.stringify`. Schluesselreihen-
+ *    folge, Zahlenschreibweise und Leerraum aendern sich dabei, und die
+ *    Signatur passt nicht mehr. In Express heisst das `express.raw({type:'*​/*'})`
+ *    **vor** jedem JSON-Parser fuer diesen Pfad.
+ * 2. **Das Zeitfenster.** Ohne Pruefung von `t` ist eine einmal mitgeschnittene,
+ *    gueltig signierte Zustellung fuer immer wiederverwendbar. 300 Sekunden in
+ *    beide Richtungen — auch in die Zukunft, sonst hilft eine falsch gestellte
+ *    Uhr auf der Gegenseite dem Angreifer.
+ * 3. **Der zeitkonstante Vergleich.** Ein `===` auf Hex-Zeichenketten bricht
+ *    beim ersten abweichenden Zeichen ab. Wer messen kann, wie lange die
+ *    Ablehnung dauert, raet die Signatur Zeichen fuer Zeichen.
+ * 4. **Jede Ausnahme ist eine Ablehnung.** Ein `catch`, das weiterlaufen laesst,
+ *    macht aus einem Formfehler ein Ja.
+ *
+ * Der Kopf lautet `X-Kasseneck-Signature: t=<unix-sekunden>,v1=<hex>` mit
+ * `v1 = HMAC-SHA256(secret, "<t>.<roher Rumpf>")`. **Mehrere `v1=`-Anteile sind
+ * erlaubt** — so laeuft ein Schluesselwechsel ohne Zustellungsluecke; es reicht,
+ * wenn einer passt.
+ *
+ * Umgesetzt mit WebCrypto (`crypto.subtle`) statt `node:crypto`: dieses Paket
+ * haengt an keiner Laufzeit-Abhaengigkeit und wird auch fuer den Browser
+ * gebuendelt. Deshalb ist die Pruefung **asynchron**.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOK_LIMIT = exports.WEBHOOK_TIMEOUT_MS = exports.WEBHOOK_MAX_ATTEMPTS = exports.WEBHOOK_RETRY_PLAN_SEC = exports.WEBHOOK_TOLERANCE_SEC = exports.WEBHOOK_DELIVERY_HEADER = exports.WEBHOOK_EVENT_HEADER = exports.WEBHOOK_SIGNATURE_HEADER = void 0;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+exports.parseSignatureHeader = parseSignatureHeader;
+/** Der Kopf, in dem die Signatur steht. */
+exports.WEBHOOK_SIGNATURE_HEADER = 'X-Kasseneck-Signature';
+/** Der Kopf mit dem Ereignisnamen (dasselbe wie `body.type`). */
+exports.WEBHOOK_EVENT_HEADER = 'X-Kasseneck-Event';
+/** Der Kopf mit der Zustell-Kennung — bei Wiederholungen **dieselbe**. */
+exports.WEBHOOK_DELIVERY_HEADER = 'X-Kasseneck-Delivery';
+/** Erlaubte Abweichung des Zeitstempels, in Sekunden (in beide Richtungen). */
+exports.WEBHOOK_TOLERANCE_SEC = 300;
+/** Wartezeiten zwischen den Zustellversuchen, in Sekunden. */
+exports.WEBHOOK_RETRY_PLAN_SEC = [60, 300, 1800, 7200, 43200];
+/** Erstversuch plus je eine Wiederholung pro Planeintrag. */
+exports.WEBHOOK_MAX_ATTEMPTS = exports.WEBHOOK_RETRY_PLAN_SEC.length + 1;
+/** So lange wartet Kasseneck auf eine 2xx-Antwort. */
+exports.WEBHOOK_TIMEOUT_MS = 10_000;
+/** Hoechstzahl der Webhook-Endpunkte je Partner. */
+exports.WEBHOOK_LIMIT = 10;
+/**
+ * Prueft die Signatur einer eingehenden Zustellung.
+ *
+ * Antwortet **nie** mit einem geworfenen Fehler auf schlechte Eingaben: jede
+ * Ausnahme im Inneren wird zur Ablehnung. Ein Aufrufer, der nur `ok` abfragt,
+ * kann damit nichts falsch machen.
+ */
+async function verifyWebhookSignature(optionen) {
+    try {
+        const secrets = (Array.isArray(optionen.secret) ? optionen.secret : [optionen.secret]).filter((s) => typeof s === 'string' && s.length > 0);
+        if (!secrets.length)
+            return { ok: false, reason: 'secret-missing' };
+        if (typeof optionen.signatureHeader !== 'string' || !optionen.signatureHeader.trim()) {
+            return { ok: false, reason: 'header-missing' };
+        }
+        const kopf = parseSignatureHeader(optionen.signatureHeader);
+        if (kopf === null)
+            return { ok: false, reason: 'header-malformed' };
+        if (optionen.body === undefined || optionen.body === null)
+            return { ok: false, reason: 'body-missing' };
+        const jetzt = typeof optionen.nowSec === 'number' && Number.isFinite(optionen.nowSec)
+            ? optionen.nowSec
+            : Math.floor(Date.now() / 1000);
+        const toleranz = typeof optionen.toleranceSec === 'number' && Number.isFinite(optionen.toleranceSec)
+            ? optionen.toleranceSec
+            : exports.WEBHOOK_TOLERANCE_SEC;
+        // In BEIDE Richtungen: eine vorgehende Uhr auf der Gegenseite darf ein
+        // altes Ereignis nicht wieder gueltig machen.
+        if (Math.abs(jetzt - kopf.t) > toleranz)
+            return { ok: false, reason: 'timestamp-outside-window' };
+        const nachricht = signierteBytes(kopf.t, optionen.body);
+        for (const secret of secrets) {
+            const soll = await hmacSha256(secret, nachricht);
+            for (const v1 of kopf.v1) {
+                const ist = hexZuBytes(v1);
+                if (ist !== null && gleichZeitkonstant(ist, soll))
+                    return { ok: true, timestampSec: kopf.t };
+            }
+        }
+        return { ok: false, reason: 'signature-mismatch' };
+    }
+    catch {
+        // Punkt 4 im Modulkommentar: eine Ausnahme ist eine Ablehnung, nie ein Ja.
+        return { ok: false, reason: 'signature-mismatch' };
+    }
+}
+/**
+ * Zerlegt den Signaturkopf. `null`, wenn kein brauchbarer Zeitstempel oder gar
+ * kein `v1=`-Anteil darin steht.
+ */
+function parseSignatureHeader(kopf) {
+    const teile = String(kopf).split(',').map((x) => x.trim());
+    const tTeil = teile.find((x) => x.startsWith('t='));
+    const v1 = teile.filter((x) => x.startsWith('v1=')).map((x) => x.slice(3));
+    if (!tTeil || !v1.length)
+        return null;
+    const roh = tTeil.slice(2);
+    // Nur ganze Zahlen: `Number('1e9')` und `Number(' 12 ')` waeren sonst gueltige
+    // Zeitstempel, und `parseInt('12abc')` ebenfalls.
+    if (!/^\d{1,15}$/.test(roh))
+        return null;
+    return { t: Number(roh), v1 };
+}
+/** `<t>.<roher Rumpf>` als Bytes — genau das, was das Backend signiert. */
+function signierteBytes(t, body) {
+    const praefix = new TextEncoder().encode(`${t}.`);
+    const rumpf = typeof body === 'string' ? new TextEncoder().encode(body) : body;
+    const zusammen = new Uint8Array(praefix.length + rumpf.length);
+    zusammen.set(praefix, 0);
+    zusammen.set(rumpf, praefix.length);
+    return zusammen;
+}
+async function hmacSha256(secret, nachricht) {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error('verifyWebhookSignature: kein WebCrypto vorhanden — Node >= 20.18 verwenden (globalThis.crypto.subtle)');
+    }
+    const key = await subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signatur = await subtle.sign('HMAC', key, nachricht);
+    return new Uint8Array(signatur);
+}
+/** Hex zu Bytes; `null` bei ungerader Laenge oder Nicht-Hex. */
+function hexZuBytes(hex) {
+    if (hex.length === 0 || hex.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(hex))
+        return null;
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++)
+        bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return bytes;
+}
+/**
+ * Vergleich ohne frueh Abbrechen. Die Laengenpruefung davor verraet nur die
+ * Laenge des Hashs, und die ist bekannt (SHA-256, 32 Bytes); der Inhalt wird
+ * immer vollstaendig durchlaufen.
+ */
+function gleichZeitkonstant(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let unterschied = 0;
+    for (let i = 0; i < a.length; i++)
+        unterschied |= a[i] ^ b[i];
+    return unterschied === 0;
+}