From 24c2d34b3ac998939909a41186f60d8a2a7e0858 Mon Sep 17 00:00:00 2001 From: Sebastian Frank Date: Fri, 6 Nov 2026 14:58:24 +0000 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20types(hooks):=20webauthn-Paket=20(P?= =?UTF-8?q?asskeys/WebAuthn=20Level=202)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - `WebAuthnPackage` mit `verifyRegistration` und `verifyAssertion`, verdrahtet in `HookContext`. - `WebAuthnRegistrationOptions`/`WebAuthnAssertionOptions`, `WebAuthnCredentialJSON` (Binärfelder base64url oder Byte-Array). - Diskriminierte Ergebnistypen: `verified: true` mit Credential-Daten bzw. `verified: false` mit `WebAuthnErrorCode` und optionalem Detail. - `attestationTrusted` als explizite Warnung: heute immer `false`, die AAGUID ist damit nicht authentisiert. --- index.d.ts | 143 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) diff --git a/index.d.ts b/index.d.ts index dd2d48b..a2c6a9e 100644 --- a/index.d.ts +++ b/index.d.ts @@ -2019,6 +2019,148 @@ declare global { t?: number } + /** + * WebAuthn Level 2 (passkeys and security keys), server side. + * + * The browser talks to the authenticator; these functions verify the + * response. Stateless: challenge handling, storage, rate limiting and + * replay protection are the hook's responsibility. + */ + interface WebAuthnPackage { + /** + * Verify an attestation and return the credential to store. + * + * Attestation `none` (browser default) and packed self-attestation are + * verified; `packed` with an x5c certificate chain is rejected as + * `unsupported_attestation` instead of being trusted. + */ + verifyRegistration(options: WebAuthnRegistrationOptions): WebAuthnRegistrationResult + + /** + * Verify a login assertion against the stored COSE public key. + * + * The signature covers `authenticatorData || SHA256(clientDataJSON)`. + */ + verifyAssertion(options: WebAuthnAssertionOptions): WebAuthnAssertionResult + } + + export interface WebAuthnRegistrationOptions { + /** JSON from `navigator.credentials.create()`. */ + credential: WebAuthnCredentialJSON + /** base64url of the challenge the server issued. */ + challenge: string + /** relying party id, e.g. `shop.example.com`. */ + rpId: string + /** accepted origin, exact match. */ + origin?: string + /** accepted origins; wins over `origin` when set. */ + origins?: string[] + /** demand the UV flag (biometric/PIN). Default false. */ + requireUserVerification?: boolean + } + + export interface WebAuthnAssertionOptions { + /** JSON from `navigator.credentials.get()`. */ + credential: WebAuthnCredentialJSON + /** base64url of the challenge the server issued. */ + challenge: string + /** relying party id, e.g. `shop.example.com`. */ + rpId: string + origin?: string + origins?: string[] + /** stored COSE key, as returned by `verifyRegistration`. */ + publicKey: string | Int8Array + /** stored counter. Default 0. */ + signCount?: number + requireUserVerification?: boolean + /** + * Accept credentials without a counter (synced passkeys report 0/0). + * Default true; false demands a real counter. + */ + allowSignCountZero?: boolean + } + + /** PublicKeyCredential JSON. Binary fields are base64url or byte arrays. */ + export interface WebAuthnCredentialJSON { + id: string + rawId?: string | Int8Array + type: string + transports?: string[] + response: { + clientDataJSON: string | Int8Array + attestationObject?: string | Int8Array + authenticatorData?: string | Int8Array + signature?: string | Int8Array + userHandle?: string | Int8Array | null + } + } + + export type WebAuthnErrorCode = + | "malformed_credential" + | "unsupported_type" + | "malformed_client_data" + | "type_mismatch" + | "challenge_mismatch" + | "origin_mismatch" + | "cross_origin_not_allowed" + | "rp_id_mismatch" + | "malformed_authenticator_data" + | "user_not_present" + | "user_verification_required" + | "credential_id_mismatch" + | "unsupported_attestation" + | "unsupported_algorithm" + | "malformed_public_key" + | "signature_invalid" + | "sign_count_regression" + + export type WebAuthnRegistrationResult = + | { + verified: true + /** base64url credential id. */ + credentialId: string + /** COSE public key, base64url. Persist it for `verifyAssertion`. */ + publicKey: string + signCount: number + /** Authenticator model as UUID; nil UUID for many platform passkeys. */ + aaguid: string + /** `none`, `packed`, … */ + attestationFormat: string + /** + * Always `false` today: `none` carries no attestation and packed + * self-attestation proves possession, not identity. An untrusted + * AAGUID is spoofable and must not drive policy. + */ + attestationTrusted: boolean + /** From `response.getTransports()`, unverified. */ + transports: string[] + backupEligible: boolean + backupState: boolean + } + | { + verified: false + error: WebAuthnErrorCode + detail?: string + } + + export type WebAuthnAssertionResult = + | { + verified: true + /** Persist this instead of the stored counter. */ + newSignCount: number + userPresent: boolean + userVerified: boolean + backupEligible: boolean + backupState: boolean + /** base64url user handle, "" for non-discoverable credentials. */ + userHandle: string + } + | { + verified: false + error: WebAuthnErrorCode + detail?: string + } + interface JsonPackage { /** * parse json string to json @@ -2330,6 +2472,7 @@ declare global { pdf: PdfPackage crypto: CryptoPackage totp: TotpPackage + webauthn: WebAuthnPackage json: JsonPackage exec: ExecPackage base64: Base64Package