diff --git a/index.d.ts b/index.d.ts index a2c6a9e..6b41b1c 100644 --- a/index.d.ts +++ b/index.d.ts @@ -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 + + /** 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 { + mfaRequired?: false + token: string + user: U + amr?: AdminAuthMethod[] + /** Inside the grace period: enrollment is recommended, not enforced. */ + mfaEnrollmentRecommended?: boolean + } + + export type AdminLoginResponse = AdminLoginSession | 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 diff --git a/package-lock.json b/package-lock.json index a64aa3c..0da095b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -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", diff --git a/package.json b/package.json index 9511c79..117bdf5 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/tsconfig.json b/tsconfig.json index 645493f..fb8ed3d 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,6 +1,7 @@ { - "include": ["demo-api/**/*"], + "include": ["demo-api/**/*", "types-test/**/*"], "compilerOptions": { + "target": "es2020", "typeRoots": ["."], "module": "commonjs", "noImplicitAny": true, diff --git a/types-test/admin-auth.ts b/types-test/admin-auth.ts new file mode 100644 index 0000000..7d4c72e --- /dev/null +++ b/types-test/admin-auth.ts @@ -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 = (() => T extends A ? 1 : 2) extends () => T extends B ? 1 : 2 ? true : false +type Expect = T + +const challenge: AdminMfaChallenge = { + mfaRequired: true, + pendingToken: "pending", + expiresIn: 300, + methods: ["webauthn", "totp", "recovery"], +} +type _ChallengeFlag = Expect> +type _ChallengeMethods = Expect> +type _AuthMethodIncludesPassword = Expect> + +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> + +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" } }