✨ 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:
1 parent
b80af7ae58
commit
24c2d34b3a
1 file changed
+143
Vendored
+143
@@ -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
|
||||
|
||||
Reference in new issue
Block a user