✨ types(auth): Admin-Login-, MFA- und WebAuthn-Verträge

Eine Quelle für Server und Admin-UI:
- `AdminLoginResponse`: Union aus `AdminMfaChallenge` (`mfaRequired: true`)
  und `AdminLoginSession` (`token`, `user`, `amr`, `mfaEnrollmentRecommended`).
  Die Diskriminante ist `mfaRequired`, damit Clients sauber narrowen.
- `AdminAuthMethod` (`pwd|totp|recovery|webauthn`) vs. `AdminMfaMethod`
  (ohne `pwd`) — Go schreibt `pwd` immer in `amr`, bietet es aber nie als
  Faktor an.
- `AdminMfaStatus`, `AdminMfaTotpEnrollment`, `AdminMfaConfirmResult`,
  `AdminStepUpResult`.
- WebAuthn: `AdminWebAuthnCreationOptions`,
  `AdminWebAuthnRequestOptions`, `AdminWebAuthnCredentialJSON`,
  `AdminWebAuthnCredentialView`, `AdminAuthenticatorTransport`.

Type-Tests in `types-test/admin-auth.ts`: `Expect<Equal<…>>`-Assertions und
`@ts-expect-error` für die nicht möglichen Felder der Challenge. `npm test`
führt jetzt Schemas **und** `tsc` aus (TypeScript als devDependency).
This commit is contained in:
apairon committed 2026-11-06 19:09:14 +00:00
1 parent 24c2d34b3a
commit 2546d05b25
5 files changed
+198 -4

No files matched your search

Vendored
+119
View File
@@ -2481,6 +2481,125 @@ declare global {
ratelimit: RatelimitPackage
}
// ── Admin API: login, second factor, WebAuthn ────────────────────
// These describe the wire shapes of /api/v1/login and /api/v1/mfa, so the
// admin UI and any client use the same contract as the server.
/** Every method that can appear in the `amr` claim, including the password. */
export type AdminAuthMethod = "pwd" | "totp" | "recovery" | "webauthn"
/** Factors the login offer can contain (no password). */
export type AdminMfaMethod = Exclude<AdminAuthMethod, "pwd">
/** Step-1 answer when a second factor is required. */
export interface AdminMfaChallenge {
mfaRequired: true
pendingToken: string
expiresIn: number
/** Policy requires a factor and the grace period is over. */
enrollmentRequired?: boolean
methods: AdminMfaMethod[]
}
/** Step-1 answer for an account without an active factor. */
export interface AdminLoginSession<U = unknown> {
mfaRequired?: false
token: string
user: U
amr?: AdminAuthMethod[]
/** Inside the grace period: enrollment is recommended, not enforced. */
mfaEnrollmentRecommended?: boolean
}
export type AdminLoginResponse<U = unknown> = AdminLoginSession<U> | AdminMfaChallenge
export interface AdminMfaStatus {
totpEnabled: boolean
webauthnCredentials: number
recoveryCodesRemaining: number
enforced: boolean
policy: "off" | "optional" | "required"
}
export interface AdminMfaTotpEnrollment {
secret: string
otpauthUri: string
}
export interface AdminMfaConfirmResult {
enabled: boolean
recoveryCodes: string[]
}
export interface AdminStepUpResult {
stepUpToken: string
expiresIn: number
}
export type AdminAuthenticatorTransport =
| "usb"
| "nfc"
| "ble"
| "internal"
| "hybrid"
| "smart-card"
export interface AdminWebAuthnDescriptor {
type: "public-key"
id: string
transports?: AdminAuthenticatorTransport[]
}
/** PublicKeyCredentialCreationOptions with base64url strings. */
export interface AdminWebAuthnCreationOptions {
challenge: string
rp: { id: string; name: string }
user: { id: string; name: string; displayName: string }
pubKeyCredParams: { type: "public-key"; alg: number }[]
timeout: number
excludeCredentials?: AdminWebAuthnDescriptor[]
authenticatorSelection?: {
residentKey?: "required" | "preferred" | "discouraged"
userVerification?: "required" | "preferred" | "discouraged"
}
attestation?: "none" | "indirect" | "direct" | "enterprise"
}
/** PublicKeyCredentialRequestOptions with base64url strings. */
export interface AdminWebAuthnRequestOptions {
challenge: string
rpId: string
allowCredentials: AdminWebAuthnDescriptor[]
timeout: number
userVerification?: "required" | "preferred" | "discouraged"
}
/** Serialised PublicKeyCredential as the server expects it. */
export interface AdminWebAuthnCredentialJSON {
id: string
rawId: string
type: "public-key"
transports?: AdminAuthenticatorTransport[]
response: {
clientDataJSON: string
attestationObject?: string
authenticatorData?: string
signature?: string
userHandle?: string
}
}
export interface AdminWebAuthnCredentialView {
id: string
label: string
transports?: AdminAuthenticatorTransport[]
aaguid?: string
createdAt: string
lastUsedAt?: string
backupEligible: boolean
backupState: boolean
}
export interface HookException {
status?: number
html?: string