✨ types(hooks): totp-Paket (#63)

TotpPackage mit generate/verify/uri, TotpOptions (digits, period,
algorithm, t) und window beim Verify; totp im HookContext registriert.
Kommentare nennen Defaults, die State-Losigkeit und dass t nicht aus
Nutzereingaben kommen darf.

Refs cms/tibi-server#63
This commit is contained in:
apairon committed 2026-11-04 19:42:25 +00:00
1 parent b5a6c3657d
commit 081a87c492
1 file changed
+62
Vendored
+62
View File
@@ -1858,6 +1858,67 @@ declare global {
): boolean
}
/**
* Time-based one-time passwords (RFC 6238 / RFC 4226).
*
* All functions accept the secret as a base32 string (lowercase and
* grouping whitespace allowed, as authenticator apps display it) or as
* bytes. Stateless: replay protection, rate limiting and lockout are the
* hook's responsibility.
*/
interface TotpPackage {
/**
* Current code for the given time step.
*
* @param secret base32 string or bytes
* @param options.digits 6 (default), 7 or 8
* @param options.period time step in seconds (default 30)
* @param options.algorithm `sha1` (default) | `sha256` | `sha512`
* @param options.t unix seconds to generate for (default: now)
*/
generate(secret: string | Int8Array, options?: TotpOptions): string
/**
* Verify a user-supplied code in constant time.
*
* Returns `false` for wrong-length or non-numeric codes (user input),
* never throws for them. The default window is ±1 step (clock skew).
*
* @param secret base32 string or bytes
* @param code the entered digits
* @param options.window accepted steps before/after (0–10, default 1)
*/
verify(
secret: string | Int8Array,
code: string,
options?: TotpOptions & { window?: number }
): boolean
/**
* `otpauth://totp/...` URI for enrollment (QR code / manual entry).
*
* @param options.secret base32 string or bytes (required)
* @param options.account account label, e.g. the user's mail (required)
* @param options.issuer issuer name shown by the app (recommended)
*/
uri(options: TotpOptions & {
secret: string | Int8Array
account: string
issuer?: string
}): string
}
export interface TotpOptions {
/** 6 (default), 7 or 8 */
digits?: number
/** time step in seconds (1–3600, default 30) */
period?: number
/** `sha1` (default) | `sha256` | `sha512` */
algorithm?: "sha1" | "sha256" | "sha512"
/** unix seconds to generate/verify for (default: now) */
t?: number
}
interface JsonPackage {
/**
* parse json string to json
@@ -2168,6 +2229,7 @@ declare global {
cookie: CookiePackage
pdf: PdfPackage
crypto: CryptoPackage
totp: TotpPackage
json: JsonPackage
exec: ExecPackage
base64: Base64Package