@coderoftime/fints 0.0.0-stage → 0.1.0

package/src/tan/tan-image.ts

@@ -0,0 +1,36 @@
+import { base64Encode, latin1Decode } from '../util/bytes.js';
+
+const imageMimeType = /^image\/[a-zA-Z0-9.+-]+$/;
+
+/** An image challenge (photoTAN, QR-TAN) with its MIME type. */
+export class TanImage {
+  constructor(
+    /** The media type of `bytes`, for example `image/png`. */
+    readonly mimeType: string,
+    /** The encoded image. */
+    readonly bytes: Uint8Array,
+  ) {}
+
+  /**
+   * Reads the bank's image container: a two-byte length and the MIME type, then a two-byte length and the image.
+   *
+   * `undefined` unless the MIME type is an image type and the container holds the whole image.
+   */
+  static tryParse(data: Uint8Array): TanImage | undefined {
+    if (data.length < 4) return undefined;
+    const mimeLength = (data[0]! << 8) | data[1]!;
+    if (mimeLength === 0 || data.length < 2 + mimeLength + 2) return undefined;
+    const mime = latin1Decode(data.subarray(2, 2 + mimeLength));
+    if (!imageMimeType.test(mime)) return undefined;
+    const offset = 2 + mimeLength;
+    const imageLength = (data[offset]! << 8) | data[offset + 1]!;
+    const start = offset + 2;
+    if (start + imageLength > data.length) return undefined;
+    return new TanImage(mime, data.subarray(start, start + imageLength));
+  }
+
+  /** The image as a `data:` URL, ready for the `src` of an `<img>`. */
+  toDataUrl(): string {
+    return `data:${this.mimeType};base64,${base64Encode(this.bytes)}`;
+  }
+}

package/src/tan/tan-models.ts

@@ -0,0 +1,247 @@
+import { maskedId } from '../util/text.js';
+
+/** Whether a TAN method needs the name of a TAN medium. */
+export type TanMediumRequirement =
+  /** The method takes no medium name. */
+  | 'notAllowed'
+  /** The method takes a medium name but works without one. */
+  | 'optional'
+  /** The method needs the name of the medium. */
+  | 'required';
+
+/** Reads the FinTS code: `0` not allowed, `1` optional, `2` required. */
+export function tanMediumRequirementOf(code: string | undefined): TanMediumRequirement {
+  return code === '1' ? 'optional' : code === '2' ? 'required' : 'notAllowed';
+}
+
+/** What `TanMethod` takes; the bank states the details it knows. */
+export interface TanMethodInit {
+  securityFunction: string;
+  name: string;
+  technicalId?: string | undefined;
+  dkMethod?: string | undefined;
+  dkVersion?: string | undefined;
+  maxTanLength?: number | undefined;
+  numericTan?: boolean;
+  returnValueText?: string | undefined;
+  maxChallengeLength?: number | undefined;
+  mediumRequirement?: TanMediumRequirement;
+  activeMediaCount?: number | undefined;
+  structuredChallenge?: boolean;
+  decoupled?: boolean;
+  decoupledMaxPolls?: number | undefined;
+  decoupledFirstPollDelaySeconds?: number | undefined;
+  decoupledPollIntervalSeconds?: number | undefined;
+  decoupledManualConfirmation?: boolean;
+  decoupledAutomaticPolling?: boolean;
+}
+
+/** A TAN procedure offered by the bank (FinTS "Sicherheitsfunktion"). */
+export class TanMethod {
+  /** Bank-specific code of the procedure, for example `942`; `999` is the one-step procedure. */
+  readonly securityFunction: string;
+
+  /** The name the bank gives the procedure, for example `pushTAN`. */
+  readonly name: string;
+
+  /** The bank's technical identification of the procedure. */
+  readonly technicalId: string | undefined;
+
+  /** DK procedure family such as `HHD1.4`, `mobileTAN` or `Decoupled`. */
+  readonly dkMethod: string | undefined;
+
+  /** Version of the `dkMethod`. */
+  readonly dkVersion: string | undefined;
+
+  /** Longest TAN the user may enter. */
+  readonly maxTanLength: number | undefined;
+
+  /** Whether the TAN consists of digits only. */
+  readonly numericTan: boolean;
+
+  /** The bank's label for the value the user sends back, for example `TAN`. */
+  readonly returnValueText: string | undefined;
+
+  /** Longest challenge text the bank sends for this procedure. */
+  readonly maxChallengeLength: number | undefined;
+
+  /** Whether a TAN medium name goes with this procedure. */
+  readonly mediumRequirement: TanMediumRequirement;
+
+  /**
+   * Most TAN media a user can have active at once for this procedure, as the bank's parameters state it ("Anzahl
+   * unterstützter aktiver TAN-Medien"); not how many the user has.
+   *
+   * Where it is above 1 and `needsMediumName`, each message names the medium, since the user may have several.
+   */
+  readonly activeMediaCount: number | undefined;
+
+  /** Whether the challenge text is structured (marked up) rather than plain. */
+  readonly structuredChallenge: boolean;
+
+  /** Whether approval happens in a separate app instead of entering a TAN. */
+  readonly decoupled: boolean;
+
+  /** Most status requests the bank allows for a decoupled approval; 0 allows any number. */
+  readonly decoupledMaxPolls: number | undefined;
+
+  /** How long to wait before the first status request of a decoupled approval, in seconds. */
+  readonly decoupledFirstPollDelaySeconds: number | undefined;
+
+  /** How long to wait between two status requests of a decoupled approval, in seconds. */
+  readonly decoupledPollIntervalSeconds: number | undefined;
+
+  /** Whether the user may report the approval, rather than the client asking the bank by itself. */
+  readonly decoupledManualConfirmation: boolean;
+
+  /** Whether the bank allows the client to ask for the approval by itself. */
+  readonly decoupledAutomaticPolling: boolean;
+
+  constructor(init: TanMethodInit) {
+    this.securityFunction = init.securityFunction;
+    this.name = init.name;
+    this.technicalId = init.technicalId;
+    this.dkMethod = init.dkMethod;
+    this.dkVersion = init.dkVersion;
+    this.maxTanLength = init.maxTanLength;
+    this.numericTan = init.numericTan ?? true;
+    this.returnValueText = init.returnValueText;
+    this.maxChallengeLength = init.maxChallengeLength;
+    this.mediumRequirement = init.mediumRequirement ?? 'notAllowed';
+    this.activeMediaCount = init.activeMediaCount;
+    this.structuredChallenge = init.structuredChallenge ?? false;
+    this.decoupled = init.decoupled ?? false;
+    this.decoupledMaxPolls = init.decoupledMaxPolls;
+    this.decoupledFirstPollDelaySeconds = init.decoupledFirstPollDelaySeconds;
+    this.decoupledPollIntervalSeconds = init.decoupledPollIntervalSeconds;
+    this.decoupledManualConfirmation = init.decoupledManualConfirmation ?? true;
+    this.decoupledAutomaticPolling = init.decoupledAutomaticPolling ?? true;
+  }
+
+  /** The one-step procedure (PIN only, no TAN). */
+  static readonly oneStep = new TanMethod({ securityFunction: '999', name: 'One-step (PIN only)' });
+
+  /** Whether this is the one-step procedure. */
+  get isOneStep(): boolean {
+    return this.securityFunction === TanMethod.oneStep.securityFunction;
+  }
+
+  /** Whether the bank needs the name of a TAN medium for this procedure. */
+  get needsMediumName(): boolean {
+    return this.mediumRequirement === 'required';
+  }
+
+  toString(): string {
+    return `TanMethod(${this.securityFunction}, ${this.name})`;
+  }
+}
+
+/** State of a TAN medium as reported by the bank. */
+export type TanMediumStatus =
+  /** The medium is in use. */
+  | 'active'
+  /** The medium can be used but is not the active one. */
+  | 'available'
+  /** The medium is the active follow-up card. */
+  | 'activeFollowUpCard'
+  /** The medium is an available follow-up card. */
+  | 'availableFollowUpCard'
+  /** The bank states no status, or one that is not known. */
+  | 'unknown';
+
+/** Reads the FinTS code `1` to `4`. */
+export function tanMediumStatusOf(code: string | undefined): TanMediumStatus {
+  switch (code) {
+    case '1':
+      return 'active';
+    case '2':
+      return 'available';
+    case '3':
+      return 'activeFollowUpCard';
+    case '4':
+      return 'availableFollowUpCard';
+    default:
+      return 'unknown';
+  }
+}
+
+/** What `TanMedium` takes; the bank states the details it knows. */
+export interface TanMediumInit {
+  mediumClass: string;
+  status: TanMediumStatus;
+  name?: string | undefined;
+  securityFunction?: string | undefined;
+  cardNumber?: string | undefined;
+  cardSequenceNumber?: string | undefined;
+  mobileNumber?: string | undefined;
+  mobileNumberMasked?: string | undefined;
+  validFrom?: Date | undefined;
+  validUntil?: Date | undefined;
+  lastUsed?: Date | undefined;
+  activatedOn?: Date | undefined;
+}
+
+/** A TAN device registered for the user, such as a phone or TAN generator. */
+export class TanMedium {
+  /** `G` TAN generator, `M` mobile phone, `L` TAN list, `S` secoder, `B` bilateral. */
+  readonly mediumClass: string;
+
+  /** Whether the medium is in use. */
+  readonly status: TanMediumStatus;
+
+  /** The name the medium is registered under; this is what the bank wants back to pick the medium. */
+  readonly name: string | undefined;
+
+  /** The TAN procedure the medium belongs to (HITAB version 5). */
+  readonly securityFunction: string | undefined;
+
+  /** Card number of a TAN generator. */
+  readonly cardNumber: string | undefined;
+
+  /** Sequence number of the card of a TAN generator. */
+  readonly cardSequenceNumber: string | undefined;
+
+  /** Phone number of a mobile phone medium, if the bank states it in full. */
+  readonly mobileNumber: string | undefined;
+
+  /** Phone number with the middle digits hidden. */
+  readonly mobileNumberMasked: string | undefined;
+
+  /** The medium is valid from this date. */
+  readonly validFrom: Date | undefined;
+
+  /** The medium is valid until this date. */
+  readonly validUntil: Date | undefined;
+
+  /** When the medium was used last. */
+  readonly lastUsed: Date | undefined;
+
+  /** When the medium was activated. */
+  readonly activatedOn: Date | undefined;
+
+  constructor(init: TanMediumInit) {
+    this.mediumClass = init.mediumClass;
+    this.status = init.status;
+    this.name = init.name;
+    this.securityFunction = init.securityFunction;
+    this.cardNumber = init.cardNumber;
+    this.cardSequenceNumber = init.cardSequenceNumber;
+    this.mobileNumber = init.mobileNumber;
+    this.mobileNumberMasked = init.mobileNumberMasked;
+    this.validFrom = init.validFrom;
+    this.validUntil = init.validUntil;
+    this.lastUsed = init.lastUsed;
+    this.activatedOn = init.activatedOn;
+  }
+
+  /** Whether the medium is the one in use. */
+  get isActive(): boolean {
+    return this.status === 'active' || this.status === 'activeFollowUpCard';
+  }
+
+  /** The name, or the last digits of the card number, so that logs and crash reports do not collect the number. */
+  toString(): string {
+    const label = this.name ?? (this.cardNumber === undefined ? this.mediumClass : maskedId(this.cardNumber));
+    return `TanMedium(${label}, ${this.status})`;
+  }
+}

package/src/util/async.ts

@@ -0,0 +1,53 @@
+/** A promise with its resolve and reject functions, which tells whether it has settled. */
+export class Deferred<T> {
+  readonly promise: Promise<T>;
+  private resolveFn!: (value: T) => void;
+  private rejectFn!: (error: unknown) => void;
+  private settled = false;
+
+  constructor() {
+    this.promise = new Promise<T>((resolve, reject) => {
+      this.resolveFn = resolve;
+      this.rejectFn = reject;
+    });
+    // A rejection nobody waits for is not an unhandled one: whoever awaits the promise still gets it.
+    this.promise.catch(() => undefined);
+  }
+
+  get isCompleted(): boolean {
+    return this.settled;
+  }
+
+  resolve(value: T): void {
+    if (this.settled) return;
+    this.settled = true;
+    this.resolveFn(value);
+  }
+
+  reject(error: unknown): void {
+    if (this.settled) return;
+    this.settled = true;
+    this.rejectFn(error);
+  }
+}
+
+/**
+ * Runs asynchronous actions one after another, in the order they were submitted.
+ *
+ * A failing action does not stop the ones queued after it.
+ */
+export class SerialExecutor {
+  private last: Promise<unknown> = Promise.resolve();
+
+  /** Runs `action` once the actions submitted before have finished; the result is that of `action`. */
+  run<T>(action: () => Promise<T>): Promise<T> {
+    const result = this.last.then(action);
+    this.last = result.catch(() => undefined);
+    return result;
+  }
+}
+
+/** Waits for `promise` and ignores its result, so that neither a value nor an error goes unhandled. */
+export function ignoreOutcome(promise: Promise<unknown>): void {
+  promise.catch(() => undefined);
+}

package/src/util/bytes.ts

@@ -0,0 +1,135 @@
+import { FormatError } from './errors.js';
+
+/** The `parts` joined into one array. */
+export function concatBytes(parts: readonly Uint8Array[]): Uint8Array {
+  let length = 0;
+  for (const part of parts) length += part.length;
+  const result = new Uint8Array(length);
+  let offset = 0;
+  for (const part of parts) {
+    result.set(part, offset);
+    offset += part.length;
+  }
+  return result;
+}
+
+/** Collects bytes, like a growing buffer. */
+export class BytesBuilder {
+  private readonly parts: Uint8Array[] = [];
+  private size = 0;
+
+  get length(): number {
+    return this.size;
+  }
+
+  add(bytes: Uint8Array | readonly number[]): void {
+    const part = bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes);
+    this.parts.push(part);
+    this.size += part.length;
+  }
+
+  addByte(byte: number): void {
+    this.add(Uint8Array.of(byte));
+  }
+
+  takeBytes(): Uint8Array {
+    const result = concatBytes(this.parts);
+    this.parts.length = 0;
+    this.size = 0;
+    return result;
+  }
+}
+
+/** ISO 8859-1 bytes of `text`, which must contain no character beyond U+00FF. */
+export function latin1Encode(text: string): Uint8Array {
+  const bytes = new Uint8Array(text.length);
+  for (let i = 0; i < text.length; i++) bytes[i] = text.charCodeAt(i) & 0xff;
+  return bytes;
+}
+
+/** The text of ISO 8859-1 `bytes`. */
+export function latin1Decode(bytes: Uint8Array): string {
+  let text = '';
+  // In chunks, since a spread of a large array exceeds the argument limit of some engines.
+  for (let i = 0; i < bytes.length; i += 0x8000) {
+    text += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  }
+  return text;
+}
+
+const utf8Encoder = new TextEncoder();
+
+export function utf8Encode(text: string): Uint8Array {
+  return utf8Encoder.encode(text);
+}
+
+/** Decodes UTF-8; throws `FormatError` for malformed data unless `allowMalformed`. */
+export function utf8Decode(bytes: Uint8Array, allowMalformed = false): string {
+  try {
+    return new TextDecoder('utf-8', { fatal: !allowMalformed, ignoreBOM: true }).decode(bytes);
+  } catch {
+    throw new FormatError('Invalid UTF-8');
+  }
+}
+
+const base64Alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const base64Values = (() => {
+  const values = new Int16Array(128).fill(-1);
+  for (let i = 0; i < base64Alphabet.length; i++) values[base64Alphabet.charCodeAt(i)] = i;
+  // The URL-safe alphabet as well.
+  values['-'.charCodeAt(0)] = 62;
+  values['_'.charCodeAt(0)] = 63;
+  return values;
+})();
+
+export function base64Encode(bytes: Uint8Array): string {
+  let out = '';
+  let i = 0;
+  for (; i + 2 < bytes.length; i += 3) {
+    const n = (bytes[i]! << 16) | (bytes[i + 1]! << 8) | bytes[i + 2]!;
+    out +=
+      base64Alphabet[n >> 18]! +
+      base64Alphabet[(n >> 12) & 63]! +
+      base64Alphabet[(n >> 6) & 63]! +
+      base64Alphabet[n & 63]!;
+  }
+  const rest = bytes.length - i;
+  if (rest === 1) {
+    const n = bytes[i]! << 16;
+    out += base64Alphabet[n >> 18]! + base64Alphabet[(n >> 12) & 63]! + '==';
+  } else if (rest === 2) {
+    const n = (bytes[i]! << 16) | (bytes[i + 1]! << 8);
+    out += base64Alphabet[n >> 18]! + base64Alphabet[(n >> 12) & 63]! + base64Alphabet[(n >> 6) & 63]! + '=';
+  }
+  return out;
+}
+
+/** Decodes base64, in the standard or the URL-safe alphabet; throws `FormatError` if `text` is not base64. */
+export function base64Decode(text: string): Uint8Array {
+  if (text.length % 4 !== 0) throw new FormatError('Invalid base64 length, must be a multiple of four');
+  let padding = 0;
+  if (text.endsWith('==')) padding = 2;
+  else if (text.endsWith('=')) padding = 1;
+  const out = new Uint8Array((text.length / 4) * 3 - padding);
+  let o = 0;
+  for (let i = 0; i < text.length; i += 4) {
+    let n = 0;
+    for (let j = 0; j < 4; j++) {
+      const c = text.charCodeAt(i + j);
+      const isPadding = c === 0x3d && i + 4 === text.length && j >= 4 - padding;
+      const value = isPadding ? 0 : c < 128 ? base64Values[c]! : -1;
+      if (value < 0) throw new FormatError('Invalid base64 character', text.charAt(i + j));
+      n = (n << 6) | value;
+    }
+    if (o < out.length) out[o++] = n >> 16;
+    if (o < out.length) out[o++] = (n >> 8) & 0xff;
+    if (o < out.length) out[o++] = n & 0xff;
+  }
+  return out;
+}
+
+export function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}

package/src/util/call-context.ts

@@ -0,0 +1,40 @@
+/** The part of Node.js's `AsyncLocalStorage` this package uses. */
+interface AsyncStorage<T> {
+  getStore(): T | undefined;
+  run<R>(store: T, callback: () => R): R;
+}
+
+type AsyncStorageConstructor = new <T>() => AsyncStorage<T>;
+
+/**
+ * `AsyncLocalStorage` where the runtime has it (Node.js, Deno, Bun), found without importing `node:async_hooks`, so that
+ * bundlers for the browser have nothing to resolve.
+ */
+const AsyncStorageClass: AsyncStorageConstructor | undefined = (() => {
+  const runtime = globalThis as {
+    process?: { getBuiltinModule?: (id: string) => { AsyncLocalStorage?: AsyncStorageConstructor } | undefined };
+  };
+  try {
+    return runtime.process?.getBuiltinModule?.('node:async_hooks')?.AsyncLocalStorage;
+  } catch {
+    return undefined;
+  }
+})();
+
+/**
+ * Tells which asynchronous call an operation runs in, through every `await` and callback it starts. Where the runtime
+ * cannot track that, as in browsers, `current` is always `undefined`.
+ */
+export class CallContext<T extends object> {
+  private readonly storage: AsyncStorage<T> | undefined = AsyncStorageClass ? new AsyncStorageClass<T>() : undefined;
+
+  /** The value of the call that runs now, if the runtime can tell. */
+  get current(): T | undefined {
+    return this.storage?.getStore();
+  }
+
+  /** Runs `action` as the call `value`. */
+  run<R>(value: T, action: () => R): R {
+    return this.storage ? this.storage.run(value, action) : action();
+  }
+}