✨ 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:
1 parent
24c2d34b3a
commit
2546d05b25
5 files changed
+198
-4
No files matched your search
Vendored
+119
@@ -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
|
||||
|
||||
Generated
+16
-1
@@ -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
@@ -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
@@ -1,6 +1,7 @@
|
||||
{
|
||||
"include": ["demo-api/**/*"],
|
||||
"include": ["demo-api/**/*", "types-test/**/*"],
|
||||
"compilerOptions": {
|
||||
"target": "es2020",
|
||||
"typeRoots": ["."],
|
||||
"module": "commonjs",
|
||||
"noImplicitAny": true,
|
||||
|
||||
@@ -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" } }
|
||||
Reference in new issue
Block a user