@coderoftime/fints 0.0.0-stage → 0.2.0

package/dist/session/user-prompts.js

@@ -0,0 +1,184 @@
+import { clientClosedError } from '../core/errors.js';
+import { TanAnswer } from '../tan/challenge.js';
+import { Deferred } from '../util/async.js';
+import { invalidArgument } from '../util/errors.js';
+/**
+ * Everything a session tells the app, asks of it or waits for: the bank's messages, warnings and log, the TAN callback,
+ * the selectors and the pauses between status requests.
+ *
+ * Once the client is closed nothing is told or asked, and every wait ends with `FinTsStateError`. Errors of the
+ * callbacks that only inform the app wait for `reportingCallbackErrors`, as `FinTsClientOptions` promises.
+ */
+export class UserPrompts {
+    options;
+    closed = false;
+    /** The first error an informing callback threw during the running call. */
+    callbackError;
+    /** Aborts the waits under way; each wait removes its abort when it is over, or when nothing waits for it any more. */
+    aborts = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    /** Ends every wait; the client calls it once. */
+    close() {
+        this.closed = true;
+        for (const abort of [...this.aborts])
+            abort();
+        this.aborts.clear();
+    }
+    /** Throws `FinTsStateError` once `close` was called. */
+    checkOpen() {
+        if (this.closed)
+            throw clientClosedError();
+    }
+    /**
+     * Runs `call` and then fails it with the first error an informing callback threw meanwhile; an error of `call` itself
+     * takes precedence.
+     */
+    async reportingCallbackErrors(call) {
+        this.callbackError = undefined;
+        const result = await call();
+        // Set by a callback while `call` ran, which the compiler cannot see.
+        const failure = this.callbackError;
+        if (failure !== undefined)
+            throw failure.error;
+        return result;
+    }
+    /** The app's logger, whose errors are kept for `reportingCallbackErrors`; `undefined` without one. */
+    get logger() {
+        const logger = this.options.logger;
+        if (logger === undefined)
+            return undefined;
+        return (direction, message) => {
+            this.inform(() => {
+                logger(direction, message);
+            });
+        };
+    }
+    /** Passes the bank's `message` to the app, unless the client is closed. */
+    showBankMessage(message) {
+        const handler = this.options.onBankMessage;
+        if (handler !== undefined && !this.closed) {
+            this.inform(() => {
+                handler(message);
+            });
+        }
+    }
+    /** Passes the bank's `warning` to the app, unless the client is closed. */
+    showWarning(warning) {
+        const handler = this.options.onWarning;
+        if (handler !== undefined && !this.closed) {
+            this.inform(() => {
+                handler(warning);
+            });
+        }
+    }
+    inform(callback) {
+        try {
+            callback();
+        }
+        catch (error) {
+            this.callbackError ??= { error };
+        }
+    }
+    /**
+     * Shows `challenge` through the TAN callback and returns its answer; rejects with `TypeError` for anything but a
+     * `TanAnswer`. Once `TanChallenge.resolved` settles, nothing waits for the answer any more.
+     */
+    askTan(challenge) {
+        return this.unlessClosed(async () => tanAnswerOf(await this.options.tanCallback(challenge)), challenge.resolved);
+    }
+    /** Waits for `delayMs` milliseconds, or until `interrupt` settles. */
+    pause(delayMs, interrupt) {
+        if (this.closed)
+            return Promise.reject(clientClosedError());
+        let timer;
+        const elapsed = new Promise((resolve) => {
+            timer = setTimeout(resolve, Math.max(0, delayMs));
+        });
+        // Neither an interrupted wait nor a closed client may leave a timer behind that keeps the process alive.
+        return this.unlessClosed(() => Promise.race([elapsed, ...(interrupt === undefined ? [] : [interrupt.then(() => undefined)])])).finally(() => {
+            clearTimeout(timer);
+        });
+    }
+    /**
+     * The TAN method to use among `candidates`: the app's choice, or the first without a selector or an answer.
+     *
+     * Throws `TypeError` if the selector returns a method that is not among `candidates`.
+     */
+    async chooseMethod(candidates) {
+        const selector = this.options.tanMethodSelector;
+        if (candidates.length === 1 || selector === undefined)
+            return candidates[0];
+        const chosen = await this.unlessClosed(() => selector(candidates));
+        if (chosen === undefined)
+            return candidates[0];
+        const match = candidates.find((m) => m.securityFunction === chosen.securityFunction);
+        if (match === undefined)
+            throw invalidArgument('Returned a TAN method the bank did not offer', 'tanMethodSelector');
+        return match;
+    }
+    /**
+     * The TAN medium to use among the active `media`: the app's choice, or the first without a selector or an answer.
+     *
+     * Throws `TypeError` if the selector returns a medium that is not among `media`.
+     */
+    async chooseMedium(media) {
+        const selector = this.options.tanMediumSelector;
+        if (media.length === 1 || selector === undefined)
+            return media[0];
+        const chosen = await this.unlessClosed(() => selector(media));
+        if (chosen === undefined)
+            return media[0];
+        const match = media.find((m) => m.name === chosen.name);
+        if (match === undefined)
+            throw invalidArgument('Returned a TAN medium the bank did not list', 'tanMediumSelector');
+        return match;
+    }
+    /**
+     * Starts `wait` and ends it with `FinTsStateError` if `close` is called before it is over. Once `unwanted` settles,
+     * nothing waits for it any more: it is forgotten then, rather than kept until a callback that never answers does.
+     *
+     * Once the client is closed, the returned promise rejects rather than this function throwing: a caller that starts
+     * several waits at once would otherwise leave the failure of those started first unheard.
+     */
+    unlessClosed(wait, unwanted) {
+        if (this.closed)
+            return Promise.reject(clientClosedError());
+        const result = new Deferred();
+        const abort = () => {
+            result.reject(clientClosedError());
+        };
+        const forget = () => {
+            this.aborts.delete(abort);
+        };
+        this.aborts.add(abort);
+        // Runs `wait` at once, as far as its first `await`, and turns an error it throws into a rejection.
+        const started = (async () => wait())();
+        started
+            .then((value) => {
+            result.resolve(value);
+        }, (error) => {
+            result.reject(error);
+        })
+            .finally(forget)
+            .catch(() => undefined);
+        void unwanted?.then(forget, forget);
+        return result.promise;
+    }
+}
+/**
+ * `answer`, a result of the TAN callback, as a `TanAnswer`; throws `TypeError` for anything else, such as the
+ * `undefined` of a callback that returns nothing. The answer is read once, so that what was checked is what counts.
+ */
+function tanAnswerOf(answer) {
+    const { kind, tan } = (typeof answer === 'object' && answer !== null ? answer : {});
+    if (kind === 'tan' && typeof tan === 'string')
+        return TanAnswer.tan(tan);
+    if (kind === 'approved')
+        return TanAnswer.approved;
+    if (kind === 'cancelled')
+        return TanAnswer.cancelled;
+    throw invalidArgument('Returned no TanAnswer', 'tanCallback');
+}
+//# sourceMappingURL=user-prompts.js.map

package/dist/session/user-prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-prompts.js","sourceRoot":"","sources":["../../src/session/user-prompts.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAqB,MAAM,qBAAqB,CAAC;AAEnE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,OAAO,WAAW;IASO;IARrB,MAAM,GAAG,KAAK,CAAC;IAEvB,2EAA2E;IACnE,aAAa,CAAiC;IAEtD,sHAAsH;IACrG,MAAM,GAAG,IAAI,GAAG,EAAc,CAAC;IAEhD,YAA6B,OAA2B;QAA3B,YAAO,GAAP,OAAO,CAAoB;IAAG,CAAC;IAE5D,iDAAiD;IACjD,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;YAAE,KAAK,EAAE,CAAC;QAC9C,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,wDAAwD;IACxD,SAAS;QACP,IAAI,IAAI,CAAC,MAAM;YAAE,MAAM,iBAAiB,EAAE,CAAC;IAC7C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,uBAAuB,CAAI,IAAsB;QACrD,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;QAC/B,MAAM,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;QAC5B,qEAAqE;QACrE,MAAM,OAAO,GAAG,IAAI,CAAC,aAA+C,CAAC;QACrE,IAAI,OAAO,KAAK,SAAS;YAAE,MAAM,OAAO,CAAC,KAAK,CAAC;QAC/C,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,sGAAsG;IACtG,IAAI,MAAM;QACR,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;QACnC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC3C,OAAO,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE;YAC5B,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE;gBACf,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YAC7B,CAAC,CAAC,CAAC;QACL,CAAC,CAAC;IACJ,CAAC;IAED,2EAA2E;IAC3E,eAAe,CAAC,OAAoB;QAClC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC;QAC3C,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YAC1C,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE;gBACf,OAAO,CAAC,OAAO,CAAC,CAAC;YACnB,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,WAAW,CAAC,OAAsB;QAChC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;QACvC,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YAC1C,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE;gBACf,OAAO,CAAC,OAAO,CAAC,CAAC;YACnB,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAEO,MAAM,CAAC,QAAoB;QACjC,IAAI,CAAC;YACH,QAAQ,EAAE,CAAC;QACb,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,aAAa,KAAK,EAAE,KAAK,EAAE,CAAC;QACnC,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,SAAuB;QAC5B,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IACnH,CAAC;IAED,sEAAsE;IACtE,KAAK,CAAC,OAAe,EAAE,SAA4B;QACjD,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC,CAAC;QAC5D,IAAI,KAAgD,CAAC;QACrD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC5C,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACpD,CAAC,CAAC,CAAC;QACH,yGAAyG;QACzG,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,CAC5B,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAC/F,CAAC,OAAO,CAAC,GAAG,EAAE;YACb,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY,CAAC,UAAgC;QACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC;QAChD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,UAAU,CAAC,CAAC,CAAE,CAAC;QAC7E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC;QACnE,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,UAAU,CAAC,CAAC,CAAE,CAAC;QAChD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,gBAAgB,KAAK,MAAM,CAAC,gBAAgB,CAAC,CAAC;QACrF,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,eAAe,CAAC,8CAA8C,EAAE,mBAAmB,CAAC,CAAC;QACpH,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY,CAAC,KAA2B;QAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC;QAChD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC,CAAC,CAAE,CAAC;QACnE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9D,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC,CAAC,CAAE,CAAC;QAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC;QACxD,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,eAAe,CAAC,6CAA6C,EAAE,mBAAmB,CAAC,CAAC;QACnH,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;OAMG;IACK,YAAY,CAAI,IAA0B,EAAE,QAA2B;QAC7E,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC,CAAC;QAC5D,MAAM,MAAM,GAAG,IAAI,QAAQ,EAAK,CAAC;QACjC,MAAM,KAAK,GAAG,GAAS,EAAE;YACvB,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC,CAAC;QACrC,CAAC,CAAC;QACF,MAAM,MAAM,GAAG,GAAS,EAAE;YACxB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvB,mGAAmG;QACnG,MAAM,OAAO,GAAG,CAAC,KAAK,IAAgB,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QACnD,OAAO;aACJ,IAAI,CACH,CAAC,KAAK,EAAE,EAAE;YACR,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACjB,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC,CACF;aACA,OAAO,CAAC,MAAM,CAAC;aACf,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC1B,KAAK,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACpC,OAAO,MAAM,CAAC,OAAO,CAAC;IACxB,CAAC;CACF;AAED;;;GAGG;AACH,SAAS,WAAW,CAAC,MAAe;IAClC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAGjF,CAAC;IACF,IAAI,IAAI,KAAK,KAAK,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzE,IAAI,IAAI,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC,QAAQ,CAAC;IACnD,IAAI,IAAI,KAAK,WAAW;QAAE,OAAO,SAAS,CAAC,SAAS,CAAC;IACrD,MAAM,eAAe,CAAC,uBAAuB,EAAE,aAAa,CAAC,CAAC;AAChE,CAAC"}

package/dist/tan/challenge.d.ts

@@ -0,0 +1,135 @@
+import { FlickerCode } from './flicker.js';
+import { TanImage } from './tan-image.js';
+import type { TanMedium, TanMethod } from './tan-models.js';
+/** `message`, or `undefined` where it is empty or the filler banks send when there is nothing to show. */
+export declare function challengeText(message: string | undefined): string | undefined;
+/** What `TanChallenge` takes. */
+export interface TanChallengeInit {
+    method: TanMethod;
+    reference: string;
+    message?: string | undefined;
+    hhdUc?: Uint8Array | undefined;
+    flickerCode?: FlickerCode | undefined;
+    image?: TanImage | undefined;
+    isDecoupled?: boolean;
+    validUntil?: Date | undefined;
+    tanMediumName?: string | undefined;
+    attempt?: number;
+    resolved?: Promise<void> | undefined;
+}
+/** A request from the bank to authorize an action with a TAN or an app approval. */
+export declare class TanChallenge {
+    /** The TAN method the challenge is for. */
+    readonly method: TanMethod;
+    /** Bank reference of the pending action, one character per byte the bank sent (ISO 8859-1). */
+    readonly reference: string;
+    /**
+     * Challenge text as the bank sent it, including the formatting tags of a structured challenge
+     * (`TanMethod.structuredChallenge`); `plainMessage` is the text to show. Show either as text only, never as HTML
+     * (`innerHTML`, `v-html`): it is the bank's text, not markup to trust.
+     */
+    readonly message: string | undefined;
+    /** Raw challenge data for TAN generators (HHD_UC). */
+    readonly hhdUc: Uint8Array | undefined;
+    /** chipTAN optical flicker code, if the challenge contains one. */
+    readonly flickerCode: FlickerCode | undefined;
+    /** photoTAN / QR-TAN image, if the challenge contains one. */
+    readonly image: TanImage | undefined;
+    /** Approval happens in a separate app; see `TanCallback` for what to answer. */
+    readonly isDecoupled: boolean;
+    /** The exact moment until which the bank accepts the TAN or the approval, where it states date and time of day. */
+    readonly validUntil: Date | undefined;
+    /** Name of the TAN medium the bank sent the challenge to. */
+    readonly tanMediumName: string | undefined;
+    /** Counts repeated prompts for the same decoupled approval. */
+    readonly attempt: number;
+    /**
+     * Settles when the client needs no more answer to this challenge: a later prompt for the approval replaces it, or the
+     * bank confirmed the approval, or the approval failed, timed out or was cancelled. Set where the client asks the bank
+     * by itself while the callback shows the challenge (`TanCallback`), `undefined` otherwise. It never rejects.
+     */
+    readonly resolved: Promise<void> | undefined;
+    /**
+     * A challenge as the bank sent it, with a copy of `validUntil`, which no other challenge shares. Use
+     * `TanChallenge.create` to have a flicker code or image detected in the data.
+     */
+    constructor(init: TanChallengeInit);
+    /** Builds a challenge and detects a photoTAN image or chipTAN flicker code in `hhdUc` or `message`. */
+    static create(init: Omit<TanChallengeInit, 'flickerCode' | 'image' | 'resolved'>): TanChallenge;
+    /**
+     * Whether the user can report the approval in the banking app; `false` where only the bank's confirmation completes
+     * it, which `TanCallback` tells how to handle.
+     */
+    get manualConfirmation(): boolean;
+    /**
+     * `message` as the user reads it.
+     *
+     * A method with structured challenges (`TanMethod.structuredChallenge`) may use the formatting tags the specification
+     * defines. Line breaks, paragraphs and list items become new lines. Bold, italics, underlining and list tags are
+     * removed, and the entity references of such markup are resolved. Any other challenge stays as the bank sent it,
+     * which is how the specification wants it shown.
+     *
+     * Show it as text, such as with `textContent`, or `{{ }}` in Vue, and `white-space: pre-line` for its line breaks;
+     * never as HTML (`innerHTML`, `v-html`). It keeps the tags the specification does not define, and `&lt;` becomes
+     * `<`, so that as HTML the bank's text could run scripts in the app.
+     */
+    get plainMessage(): string | undefined;
+}
+/** `challenge` again, counted as the next prompt for the same approval, with the bank's new instructions `message`. */
+export declare function nextAttempt(challenge: TanChallenge, message?: string): TanChallenge;
+/** `challenge` with `TanChallenge.resolved` set to `resolved`. */
+export declare function withResolved(challenge: TanChallenge, resolved: Promise<void>): TanChallenge;
+/** The user's answer to a `TanChallenge`: `TanAnswer.tan(…)`, `TanAnswer.approved` or `TanAnswer.cancelled`. */
+export type TanAnswer = 
+/**
+ * The TAN the user entered; an empty one cancels a TAN challenge. Blanks around it do not count, and digits of
+ * another width, such as full-width ones, count as the digits they are (Unicode NFKC).
+ */
+{
+    readonly kind: 'tan';
+    readonly tan: string;
+}
+/** The user reports the approval in the banking app (`TanChallenge.isDecoupled`); the client then asks the bank. */
+ | {
+    readonly kind: 'approved';
+}
+/** The user cancels: the client ends the bank dialog, and the call fails with `FinTsTanCancelledError`. */
+ | {
+    readonly kind: 'cancelled';
+};
+/** The answers a `TanCallback` returns. */
+export declare const TanAnswer: Readonly<{
+    /** The TAN the user entered; an empty one cancels a TAN challenge (`TanAnswer`). */
+    tan: (tan: string) => TanAnswer;
+    /** The user reports the approval in the banking app (`TanChallenge.isDecoupled`); the client then asks the bank. */
+    approved: {
+        readonly kind: "approved";
+    };
+    /** The user cancels: the client ends the bank dialog, and the call fails with `FinTsTanCancelledError`. */
+    cancelled: {
+        readonly kind: "cancelled";
+    };
+}>;
+/**
+ * Shows the `TanChallenge` to the user and returns the `TanAnswer`: `TanAnswer.tan(…)` for a TAN, `TanAnswer.approved`
+ * once the user reports an approval in the banking app (`TanChallenge.isDecoupled`), `TanAnswer.cancelled` to cancel
+ * either.
+ *
+ * The call fails with a `TypeError`, without reaching the bank, for anything but a `TanAnswer`, for `approved` to a TAN
+ * challenge, for a TAN to an app approval the user can report, and for a TAN that the method rules out: longer than
+ * `TanMethod.maxTanLength`, with anything but the digits 0 to 9 where `TanMethod.numericTan`, or that FinTS 3.0 cannot
+ * send (ISO 8859-1 only). Where the user cannot report the approval (`TanChallenge.manualConfirmation` is `false`),
+ * offer no confirm button: any `TanAnswer` but `cancelled` is ignored.
+ *
+ * If the bank has not confirmed a reported approval yet, the callback is called again with the next
+ * `TanChallenge.attempt` and the bank's latest instructions. Where the client polls the bank by itself, it sets
+ * `TanChallenge.resolved`: close the prompt when it settles, the callback's result is no longer waited for then. New
+ * instructions of the bank then replace the open prompt with the next attempt, which the callback gets after the
+ * handlers of the earlier prompt's `resolved` have run.
+ */
+export type TanCallback = (challenge: TanChallenge) => TanAnswer | Promise<TanAnswer>;
+/** Picks one of several allowed TAN methods; the first is used when this returns `undefined`. */
+export type TanMethodSelector = (methods: readonly TanMethod[]) => TanMethod | undefined | Promise<TanMethod | undefined>;
+/** Picks one of several active TAN media; the first is used when this returns `undefined`. */
+export type TanMediumSelector = (media: readonly TanMedium[]) => TanMedium | undefined | Promise<TanMedium | undefined>;
+//# sourceMappingURL=challenge.d.ts.map

package/dist/tan/challenge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"challenge.d.ts","sourceRoot":"","sources":["../../src/tan/challenge.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwB,WAAW,EAA0B,MAAM,cAAc,CAAC;AACzF,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAK5D,0GAA0G;AAC1G,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAE7E;AAoCD,iCAAiC;AACjC,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAC/B,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACtC,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;CACtC;AAED,oFAAoF;AACpF,qBAAa,YAAY;IACvB,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAE3B,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAErC,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC;IAEvC,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,SAAS,CAAC;IAE9C,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;IAErC,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B,mHAAmH;IACnH,QAAQ,CAAC,UAAU,EAAE,IAAI,GAAG,SAAS,CAAC;IAEtC,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAE3C,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;IAE7C;;;OAGG;gBACS,IAAI,EAAE,gBAAgB;IAclC,uGAAuG;IACvG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,aAAa,GAAG,OAAO,GAAG,UAAU,CAAC,GAAG,YAAY;IAmB/F;;;OAGG;IACH,IAAI,kBAAkB,IAAI,OAAO,CAEhC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAYrC;CACF;AAKD,uHAAuH;AACvH,wBAAgB,WAAW,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,CAEnF;AAED,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,YAAY,CAE3F;AAmBD,gHAAgH;AAChH,MAAM,MAAM,SAAS;AACnB;;;GAGG;AACD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AAChD,oHAAoH;GAClH;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE;AAC/B,2GAA2G;GACzG;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC;AAKnC,2CAA2C;AAC3C,eAAO,MAAM,SAAS;IACpB,oFAAoF;eACzE,MAAM,KAAG,SAAS;IAC7B,oHAAoH;;uBAXjG,UAAU;;IAa7B,2GAA2G;;uBAXxF,WAAW;;EAa9B,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,SAAS,EAAE,YAAY,KAAK,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;AAEtF,iGAAiG;AACjG,MAAM,MAAM,iBAAiB,GAAG,CAC9B,OAAO,EAAE,SAAS,SAAS,EAAE,KAC1B,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;AAE5D,8FAA8F;AAC9F,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,KAAK,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC"}

package/dist/tan/challenge.js

@@ -0,0 +1,184 @@
+import { latin1Decode } from '../util/bytes.js';
+import { copyDate } from '../util/dates.js';
+import { characterReference } from '../util/text.js';
+import { challengeInstruction, FlickerCode, hasEmbeddedFlickerCode } from './flicker.js';
+import { TanImage } from './tan-image.js';
+/** Challenge text banks send when there is nothing to show. */
+const noChallenge = 'nochallenge';
+/** `message`, or `undefined` where it is empty or the filler banks send when there is nothing to show. */
+export function challengeText(message) {
+    return message === undefined || message === '' || message === noChallenge ? undefined : message;
+}
+const lineBreak = /<br\b[^<>]*>/gi;
+const blockTag = /<\/?(?:p|li)\b[^<>]*>/gi;
+/**
+ * The formatting tags a structured challenge may carry besides line breaks, paragraphs and list items (PIN/TAN, Data
+ * Dictionary "Challenge"). Angle brackets around anything else, such as `<50 EUR>`, are part of the text the user
+ * approves, so they stay. Excluding `<` and `>` from the tag keeps the search linear.
+ */
+const formattingTag = /<\/?(?:b|i|u|ul|ol)\b[^<>]*>/gi;
+const entityReference = /&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g;
+const blankLines = /\n{3,}/g;
+const namedEntities = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    nbsp: ' ',
+    auml: 'ä',
+    ouml: 'ö',
+    uuml: 'ü',
+    Auml: 'Ä',
+    Ouml: 'Ö',
+    Uuml: 'Ü',
+    szlig: 'ß',
+    euro: '€',
+};
+/** The character `name` refers to; `undefined` for an unknown name and for a number that is not a character. */
+function decodeEntity(name) {
+    return characterReference(name) ?? (Object.hasOwn(namedEntities, name) ? namedEntities[name] : undefined);
+}
+/** A request from the bank to authorize an action with a TAN or an app approval. */
+export class TanChallenge {
+    /** The TAN method the challenge is for. */
+    method;
+    /** Bank reference of the pending action, one character per byte the bank sent (ISO 8859-1). */
+    reference;
+    /**
+     * Challenge text as the bank sent it, including the formatting tags of a structured challenge
+     * (`TanMethod.structuredChallenge`); `plainMessage` is the text to show. Show either as text only, never as HTML
+     * (`innerHTML`, `v-html`): it is the bank's text, not markup to trust.
+     */
+    message;
+    /** Raw challenge data for TAN generators (HHD_UC). */
+    hhdUc;
+    /** chipTAN optical flicker code, if the challenge contains one. */
+    flickerCode;
+    /** photoTAN / QR-TAN image, if the challenge contains one. */
+    image;
+    /** Approval happens in a separate app; see `TanCallback` for what to answer. */
+    isDecoupled;
+    /** The exact moment until which the bank accepts the TAN or the approval, where it states date and time of day. */
+    validUntil;
+    /** Name of the TAN medium the bank sent the challenge to. */
+    tanMediumName;
+    /** Counts repeated prompts for the same decoupled approval. */
+    attempt;
+    /**
+     * Settles when the client needs no more answer to this challenge: a later prompt for the approval replaces it, or the
+     * bank confirmed the approval, or the approval failed, timed out or was cancelled. Set where the client asks the bank
+     * by itself while the callback shows the challenge (`TanCallback`), `undefined` otherwise. It never rejects.
+     */
+    resolved;
+    /**
+     * A challenge as the bank sent it, with a copy of `validUntil`, which no other challenge shares. Use
+     * `TanChallenge.create` to have a flicker code or image detected in the data.
+     */
+    constructor(init) {
+        this.method = init.method;
+        this.reference = init.reference;
+        this.message = init.message;
+        this.hhdUc = init.hhdUc;
+        this.flickerCode = init.flickerCode;
+        this.image = init.image;
+        this.isDecoupled = init.isDecoupled ?? false;
+        this.validUntil = copyDate(init.validUntil);
+        this.tanMediumName = init.tanMediumName;
+        this.attempt = init.attempt ?? 1;
+        this.resolved = init.resolved;
+    }
+    /** Builds a challenge and detects a photoTAN image or chipTAN flicker code in `hhdUc` or `message`. */
+    static create(init) {
+        let image;
+        let flicker;
+        const data = init.hhdUc !== undefined && init.hhdUc.length > 0 ? init.hhdUc : undefined;
+        if (data !== undefined) {
+            image = TanImage.tryParse(data);
+            if (image === undefined)
+                flicker = FlickerCode.tryParse(latin1Decode(data));
+        }
+        else if (init.message !== undefined && hasEmbeddedFlickerCode(init.message)) {
+            flicker = FlickerCode.tryParse(init.message);
+        }
+        return new TanChallenge({
+            ...init,
+            message: challengeText(init.message),
+            hhdUc: data,
+            flickerCode: flicker,
+            image,
+        });
+    }
+    /**
+     * Whether the user can report the approval in the banking app; `false` where only the bank's confirmation completes
+     * it, which `TanCallback` tells how to handle.
+     */
+    get manualConfirmation() {
+        return !this.isDecoupled || this.method.decoupledManualConfirmation;
+    }
+    /**
+     * `message` as the user reads it.
+     *
+     * A method with structured challenges (`TanMethod.structuredChallenge`) may use the formatting tags the specification
+     * defines. Line breaks, paragraphs and list items become new lines. Bold, italics, underlining and list tags are
+     * removed, and the entity references of such markup are resolved. Any other challenge stays as the bank sent it,
+     * which is how the specification wants it shown.
+     *
+     * Show it as text, such as with `textContent`, or `{{ }}` in Vue, and `white-space: pre-line` for its line breaks;
+     * never as HTML (`innerHTML`, `v-html`). It keeps the tags the specification does not define, and `&lt;` becomes
+     * `<`, so that as HTML the bank's text could run scripts in the app.
+     */
+    get plainMessage() {
+        const text = this.message;
+        if (text === undefined)
+            return undefined;
+        const instruction = challengeInstruction(text);
+        if (!this.method.structuredChallenge)
+            return instruction;
+        return instruction
+            .replace(lineBreak, '\n')
+            .replace(blockTag, '\n')
+            .replace(formattingTag, '')
+            .replace(entityReference, (match, name) => decodeEntity(name) ?? match)
+            .replace(blankLines, '\n\n')
+            .trim();
+    }
+}
+// Copies of a challenge for the prompts of one approval. Not methods of `TanChallenge`, so that they are not part of its
+// API; they stand beside the class, so that a field added to it is added here as well.
+/** `challenge` again, counted as the next prompt for the same approval, with the bank's new instructions `message`. */
+export function nextAttempt(challenge, message) {
+    return copyChallenge(challenge, { attempt: challenge.attempt + 1, message: message ?? challenge.message });
+}
+/** `challenge` with `TanChallenge.resolved` set to `resolved`. */
+export function withResolved(challenge, resolved) {
+    return copyChallenge(challenge, { resolved });
+}
+function copyChallenge(challenge, changes) {
+    return new TanChallenge({
+        method: challenge.method,
+        reference: challenge.reference,
+        message: challenge.message,
+        hhdUc: challenge.hhdUc,
+        flickerCode: challenge.flickerCode,
+        image: challenge.image,
+        isDecoupled: challenge.isDecoupled,
+        validUntil: challenge.validUntil,
+        tanMediumName: challenge.tanMediumName,
+        attempt: challenge.attempt,
+        resolved: challenge.resolved,
+        ...changes,
+    });
+}
+const approvedAnswer = Object.freeze({ kind: 'approved' });
+const cancelledAnswer = Object.freeze({ kind: 'cancelled' });
+/** The answers a `TanCallback` returns. */
+export const TanAnswer = Object.freeze({
+    /** The TAN the user entered; an empty one cancels a TAN challenge (`TanAnswer`). */
+    tan: (tan) => Object.freeze({ kind: 'tan', tan }),
+    /** The user reports the approval in the banking app (`TanChallenge.isDecoupled`); the client then asks the bank. */
+    approved: approvedAnswer,
+    /** The user cancels: the client ends the bank dialog, and the call fails with `FinTsTanCancelledError`. */
+    cancelled: cancelledAnswer,
+});
+//# sourceMappingURL=challenge.js.map

package/dist/tan/challenge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"challenge.js","sourceRoot":"","sources":["../../src/tan/challenge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACzF,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG1C,+DAA+D;AAC/D,MAAM,WAAW,GAAG,aAAa,CAAC;AAElC,0GAA0G;AAC1G,MAAM,UAAU,aAAa,CAAC,OAA2B;IACvD,OAAO,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AAClG,CAAC;AAED,MAAM,SAAS,GAAG,gBAAgB,CAAC;AACnC,MAAM,QAAQ,GAAG,yBAAyB,CAAC;AAE3C;;;;GAIG;AACH,MAAM,aAAa,GAAG,gCAAgC,CAAC;AACvD,MAAM,eAAe,GAAG,gCAAgC,CAAC;AACzD,MAAM,UAAU,GAAG,SAAS,CAAC;AAE7B,MAAM,aAAa,GAA2B;IAC5C,GAAG,EAAE,GAAG;IACR,EAAE,EAAE,GAAG;IACP,EAAE,EAAE,GAAG;IACP,IAAI,EAAE,GAAG;IACT,IAAI,EAAE,GAAG;IACT,IAAI,EAAE,GAAG;IACT,IAAI,EAAE,GAAG;IACT,IAAI,EAAE,GAAG;IACT,IAAI,EAAE,GAAG;IACT,IAAI,EAAE,GAAG;IACT,IAAI,EAAE,GAAG;IACT,IAAI,EAAE,GAAG;IACT,KAAK,EAAE,GAAG;IACV,IAAI,EAAE,GAAG;CACV,CAAC;AAEF,gHAAgH;AAChH,SAAS,YAAY,CAAC,IAAY;IAChC,OAAO,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAC5G,CAAC;AAiBD,oFAAoF;AACpF,MAAM,OAAO,YAAY;IACvB,2CAA2C;IAClC,MAAM,CAAY;IAE3B,+FAA+F;IACtF,SAAS,CAAS;IAE3B;;;;OAIG;IACM,OAAO,CAAqB;IAErC,sDAAsD;IAC7C,KAAK,CAAyB;IAEvC,mEAAmE;IAC1D,WAAW,CAA0B;IAE9C,8DAA8D;IACrD,KAAK,CAAuB;IAErC,gFAAgF;IACvE,WAAW,CAAU;IAE9B,mHAAmH;IAC1G,UAAU,CAAmB;IAEtC,6DAA6D;IACpD,aAAa,CAAqB;IAE3C,+DAA+D;IACtD,OAAO,CAAS;IAEzB;;;;OAIG;IACM,QAAQ,CAA4B;IAE7C;;;OAGG;IACH,YAAY,IAAsB;QAChC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,KAAK,CAAC;QAC7C,IAAI,CAAC,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5C,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QACxC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAChC,CAAC;IAED,uGAAuG;IACvG,MAAM,CAAC,MAAM,CAAC,IAAkE;QAC9E,IAAI,KAA2B,CAAC;QAChC,IAAI,OAAgC,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACxF,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,GAAG,WAAW,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9E,CAAC;aAAM,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,sBAAsB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9E,OAAO,GAAG,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO,IAAI,YAAY,CAAC;YACtB,GAAG,IAAI;YACP,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;YACpC,KAAK,EAAE,IAAI;YACX,WAAW,EAAE,OAAO;YACpB,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,IAAI,kBAAkB;QACpB,OAAO,CAAC,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,MAAM,CAAC,2BAA2B,CAAC;IACtE,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,YAAY;QACd,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC;QAC1B,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACzC,MAAM,WAAW,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,mBAAmB;YAAE,OAAO,WAAW,CAAC;QACzD,OAAO,WAAW;aACf,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC;aACxB,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC;aACvB,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC;aAC1B,OAAO,CAAC,eAAe,EAAE,CAAC,KAAK,EAAE,IAAY,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC;aAC9E,OAAO,CAAC,UAAU,EAAE,MAAM,CAAC;aAC3B,IAAI,EAAE,CAAC;IACZ,CAAC;CACF;AAED,yHAAyH;AACzH,uFAAuF;AAEvF,uHAAuH;AACvH,MAAM,UAAU,WAAW,CAAC,SAAuB,EAAE,OAAgB;IACnE,OAAO,aAAa,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC;AAC7G,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,YAAY,CAAC,SAAuB,EAAE,QAAuB;IAC3E,OAAO,aAAa,CAAC,SAAS,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,aAAa,CAAC,SAAuB,EAAE,OAAkC;IAChF,OAAO,IAAI,YAAY,CAAC;QACtB,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,SAAS,EAAE,SAAS,CAAC,SAAS;QAC9B,OAAO,EAAE,SAAS,CAAC,OAAO;QAC1B,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,UAAU,EAAE,SAAS,CAAC,UAAU;QAChC,aAAa,EAAE,SAAS,CAAC,aAAa;QACtC,OAAO,EAAE,SAAS,CAAC,OAAO;QAC1B,QAAQ,EAAE,SAAS,CAAC,QAAQ;QAC5B,GAAG,OAAO;KACX,CAAC,CAAC;AACL,CAAC;AAcD,MAAM,cAAc,GAAc,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;AACtE,MAAM,eAAe,GAAc,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;AAExE,2CAA2C;AAC3C,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC;IACrC,oFAAoF;IACpF,GAAG,EAAE,CAAC,GAAW,EAAa,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IACpE,oHAAoH;IACpH,QAAQ,EAAE,cAAc;IACxB,2GAA2G;IAC3G,SAAS,EAAE,eAAe;CAC3B,CAAC,CAAC"}

package/dist/tan/flicker.d.ts

@@ -0,0 +1,42 @@
+/** Version of the chipTAN HHD specification a flicker code follows: 1.3, or 1.4, which adds control bytes. */
+export type HhdVersion = 'hhd13' | 'hhd14';
+/** Whether `message` is a combined challenge with an embedded flicker code. */
+export declare function hasEmbeddedFlickerCode(message: string): boolean;
+/** The instruction text of a combined challenge; `message` itself if it is none. */
+export declare function challengeInstruction(message: string): string;
+/** A chipTAN optical challenge (flicker code) in HHD 1.3 or 1.4 format. */
+export declare class FlickerCode {
+    /** The HHD version the code follows, told by the control bytes of its start code. */
+    readonly version: HhdVersion;
+    /** Length of the challenge (LC) as stated at the start of the code. */
+    readonly lc: number;
+    private readonly startCode;
+    private readonly dataElements;
+    private constructor();
+    /**
+     * Parses the challenge data sent by the bank; throws `FormatError` if it is not a flicker code a TAN generator can
+     * take: one with characters after the length it states, an empty data element, data other than printable ASCII, or
+     * more data than its length fields can state, such as more than 15 bytes in an element in HHD 1.3 or 255 bytes in all.
+     */
+    static parse(code: string): FlickerCode;
+    /** Parses `code`, or returns `undefined` if it is not a flicker code. */
+    static tryParse(code: string): FlickerCode | undefined;
+    private static parseLayout;
+    /** Whether the code renders as the bank sent it: its data printable ASCII, every length within its field. */
+    private get fitsTanGenerator();
+    /** The data of the start code, which opens the challenge. */
+    get startCodeData(): string;
+    /** The first data element of the challenge; `undefined` if the code leaves it out. */
+    get dataElement1(): string | undefined;
+    /** The second data element of the challenge; `undefined` if the code leaves it out. */
+    get dataElement2(): string | undefined;
+    /** The third data element of the challenge; `undefined` if the code leaves it out. */
+    get dataElement3(): string | undefined;
+    /** The hex string transmitted to the TAN generator, including checksums. */
+    render(): string;
+    private payload;
+    private luhnChecksum;
+    /** Frames to animate: each is `[clock, bit0, bit1, bit2, bit3]` for the five bars. */
+    frames(): boolean[][];
+}
+//# sourceMappingURL=flicker.d.ts.map

package/dist/tan/flicker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flicker.d.ts","sourceRoot":"","sources":["../../src/tan/flicker.ts"],"names":[],"mappings":"AAGA,8GAA8G;AAC9G,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;AAQ3C,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAK5D;AA2BD,2EAA2E;AAC3E,qBAAa,WAAW;IAEpB,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,UAAU;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAN/B,OAAO;IASP;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW;IAavC,yEAAyE;IACzE,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAStD,OAAO,CAAC,MAAM,CAAC,WAAW;IA0B1B,6GAA6G;IAC7G,OAAO,KAAK,gBAAgB,GAG3B;IAED,6DAA6D;IAC7D,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,sFAAsF;IACtF,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAErC;IAED,uFAAuF;IACvF,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAErC;IAED,sFAAsF;IACtF,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAErC;IAED,4EAA4E;IAC5E,MAAM,IAAI,MAAM;IAKhB,OAAO,CAAC,OAAO;IAWf,OAAO,CAAC,YAAY;IAapB,sFAAsF;IACtF,MAAM,IAAI,OAAO,EAAE,EAAE;CAatB"}