✨ 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
+16 -1
View File
@@ -12,7 +12,8 @@
"ajv": "^8.20.0",
"ajv-formats": "^3.0.1",
"glob": "^11.1.0",
"js-yaml": "^4.1.1"
"js-yaml": "^4.1.1",
"typescript": "^5.9.3"
}
},
"node_modules/@isaacs/cliui": {
@@ -330,6 +331,20 @@
"url": "https://github.com/sponsors/isaacs"
}
},
"node_modules/typescript": {
"version": "5.9.3",
"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
"integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
"dev": true,
"license": "Apache-2.0",
"bin": {
"tsc": "bin/tsc",
"tsserver": "bin/tsserver"
},
"engines": {
"node": ">=14.17"
}
},
"node_modules/which": {
"version": "2.0.2",
"resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+4 -2
View File
@@ -5,13 +5,15 @@
"types": "index.d.ts",
"scripts": {
"validate:schemas": "node scripts/validate-schemas.mjs",
"test": "npm run validate:schemas"
"typecheck": "tsc -p tsconfig.json",
"test": "npm run validate:schemas && npm run typecheck"
},
"devDependencies": {
"ajv": "^8.20.0",
"ajv-formats": "^3.0.1",
"glob": "^11.1.0",
"js-yaml": "^4.1.1"
"js-yaml": "^4.1.1",
"typescript": "^5.9.3"
},
"repository": {
"type": "git",
+2 -1
View File
@@ -1,6 +1,7 @@
{
"include": ["demo-api/**/*"],
"include": ["demo-api/**/*", "types-test/**/*"],
"compilerOptions": {
"target": "es2020",
"typeRoots": ["."],
"module": "commonjs",
"noImplicitAny": true,
+57
View File
@@ -0,0 +1,57 @@
// Compile-time contract tests for the admin auth types. `tsc --noEmit` is the
// runner: every Expect<...> must resolve to true, and the @ts-expect-error
// lines must actually fail without the directive.
type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false
type Expect<T extends true> = T
const challenge: AdminMfaChallenge = {
mfaRequired: true,
pendingToken: "pending",
expiresIn: 300,
methods: ["webauthn", "totp", "recovery"],
}
type _ChallengeFlag = Expect<Equal<typeof challenge.mfaRequired, true>>
type _ChallengeMethods = Expect<Equal<typeof challenge.methods, AdminMfaMethod[]>>
type _AuthMethodIncludesPassword = Expect<Equal<AdminMfaMethod extends AdminAuthMethod ? true : false, true>>
declare const response: AdminLoginResponse<{ id: string }>
if (response.mfaRequired) {
const pending: string = response.pendingToken
const methods: AdminMfaMethod[] = response.methods
// @ts-expect-error a challenge carries no session token
response.token
} else {
const token: string = response.token
const user: { id: string } = response.user
const amr: AdminAuthMethod[] | undefined = response.amr
}
const descriptor: AdminWebAuthnDescriptor = { type: "public-key", id: "abc" }
const requestOptions: AdminWebAuthnRequestOptions = {
challenge: "abc",
rpId: "admin.example.com",
allowCredentials: [descriptor],
timeout: 60000,
userVerification: "preferred",
}
const credential: AdminWebAuthnCredentialJSON = {
id: "abc",
rawId: "abc",
type: "public-key",
response: { clientDataJSON: "e30", signature: "sig" },
}
type _AssertionSignature = Expect<Equal<typeof credential.response.signature, string | undefined>>
const view: AdminWebAuthnCredentialView = {
id: "1",
label: "YubiKey",
createdAt: "2026-01-01T00:00:00Z",
backupEligible: false,
backupState: false,
}
// The session branch must stay assignable without a factor.
const session: AdminLoginSession<{ id: string }> = { token: "t", user: { id: "1" } }