✨ types(hooks): webauthn-Paket (Passkeys/WebAuthn Level 2)

- `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.
This commit is contained in:
apairon committed 2026-11-06 14:58:24 +00:00
1 parent b80af7ae58
commit 24c2d34b3a
1 file changed
+143
Vendored
+143
View File
@@ -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