@pk-auth/passkeys-browser 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,231 @@
1
+ // SPDX-License-Identifier: MIT
2
+
3
+ import * as b64u from "./base64url";
4
+ import { request } from "./http";
5
+ import type {
6
+ ClientOptions,
7
+ FinishAuthenticationRequest,
8
+ FinishAuthenticationResponse,
9
+ FinishRegistrationRequest,
10
+ FinishRegistrationResponse,
11
+ PublicKeyCredentialCreationOptionsJson,
12
+ PublicKeyCredentialRequestOptionsJson,
13
+ RegistrationResponseJson,
14
+ AuthenticationResponseJson,
15
+ StartAuthenticationRequest,
16
+ StartAuthenticationResponse,
17
+ StartRegistrationRequest,
18
+ StartRegistrationResponse,
19
+ } from "./types";
20
+
21
+ const PATHS = {
22
+ startReg: "/auth/passkeys/registration/start",
23
+ finishReg: "/auth/passkeys/registration/finish",
24
+ startAuth: "/auth/passkeys/authentication/start",
25
+ finishAuth: "/auth/passkeys/authentication/finish",
26
+ } as const;
27
+
28
+ // All three adapters (Spring, Dropwizard, Micronaut) now mount ceremony endpoints at
29
+ // /auth/passkeys/<phase>/<step>. The `paths` override remains an escape hatch for hosts that
30
+ // remap the routes but is no longer needed for any pk-auth-provided adapter.
31
+
32
+ export interface CeremonyOptions {
33
+ /** Path overrides — kept as an escape hatch for hosts that remap pk-auth's default routes. */
34
+ paths?: Partial<typeof PATHS>;
35
+ /** Optional override for navigator.credentials (tests / non-browser callers). */
36
+ credentials?: CredentialsContainer;
37
+ }
38
+
39
+ export interface StartRegistrationParams {
40
+ username: string;
41
+ displayName?: string;
42
+ label?: string;
43
+ }
44
+
45
+ export interface FinishRegistrationParams extends StartRegistrationResponse {
46
+ username: string;
47
+ label?: string;
48
+ }
49
+
50
+ export interface StartAuthenticationParams {
51
+ username?: string;
52
+ /** When true, hands the call to `navigator.credentials.get` with `mediation: "conditional"`. */
53
+ conditional?: boolean;
54
+ }
55
+
56
+ export class PkAuthCeremonyClient {
57
+ private readonly client: ClientOptions;
58
+ private readonly paths: typeof PATHS;
59
+ private readonly credentials?: CredentialsContainer;
60
+
61
+ constructor(client: ClientOptions, options: CeremonyOptions = {}) {
62
+ this.client = client;
63
+ this.paths = { ...PATHS, ...options.paths };
64
+ this.credentials = options.credentials;
65
+ }
66
+
67
+ /**
68
+ * Runs the full registration ceremony: server-start → `navigator.credentials.create` →
69
+ * server-finish. Returns the finish payload (registered credential metadata).
70
+ */
71
+ async register(params: StartRegistrationParams): Promise<FinishRegistrationResponse> {
72
+ const start = await this.startRegistration({
73
+ username: params.username,
74
+ displayName: params.displayName ?? params.username,
75
+ label: params.label ?? null,
76
+ challenge: null,
77
+ });
78
+ const created = await this.createCredential(start.publicKey);
79
+ return this.finishRegistration({
80
+ challengeId: start.challengeId,
81
+ username: params.username,
82
+ label: params.label ?? null,
83
+ response: encodeRegistrationResponse(created),
84
+ });
85
+ }
86
+
87
+ /**
88
+ * Runs the full sign-in ceremony: server-start → `navigator.credentials.get` →
89
+ * server-finish. Returns the JWT (consumer is responsible for storage).
90
+ */
91
+ async authenticate(params: StartAuthenticationParams = {}): Promise<FinishAuthenticationResponse> {
92
+ const start = await this.startAuthentication({
93
+ username: params.username ?? null,
94
+ challenge: null,
95
+ });
96
+ const got = await this.getCredential(start.publicKey, params.conditional ?? false);
97
+ return this.finishAuthentication({
98
+ challengeId: start.challengeId,
99
+ response: encodeAuthenticationResponse(got),
100
+ });
101
+ }
102
+
103
+ startRegistration(body: StartRegistrationRequest): Promise<StartRegistrationResponse> {
104
+ return request(this.client, "POST", this.paths.startReg, body, false);
105
+ }
106
+
107
+ finishRegistration(body: FinishRegistrationRequest): Promise<FinishRegistrationResponse> {
108
+ return request(this.client, "POST", this.paths.finishReg, body, false);
109
+ }
110
+
111
+ startAuthentication(body: StartAuthenticationRequest): Promise<StartAuthenticationResponse> {
112
+ return request(this.client, "POST", this.paths.startAuth, body, false);
113
+ }
114
+
115
+ finishAuthentication(body: FinishAuthenticationRequest): Promise<FinishAuthenticationResponse> {
116
+ return request(this.client, "POST", this.paths.finishAuth, body, false);
117
+ }
118
+
119
+ private get credentialsImpl(): CredentialsContainer {
120
+ if (this.credentials) return this.credentials;
121
+ if (typeof navigator === "undefined" || !navigator.credentials) {
122
+ throw new Error("pk-auth: navigator.credentials is not available in this environment");
123
+ }
124
+ return navigator.credentials;
125
+ }
126
+
127
+ private async createCredential(
128
+ options: PublicKeyCredentialCreationOptionsJson,
129
+ ): Promise<PublicKeyCredential> {
130
+ const publicKey = decodeCreationOptions(options);
131
+ const credential = (await this.credentialsImpl.create({ publicKey })) as PublicKeyCredential | null;
132
+ if (!credential) {
133
+ throw new Error("pk-auth: credential creation was cancelled");
134
+ }
135
+ return credential;
136
+ }
137
+
138
+ private async getCredential(
139
+ options: PublicKeyCredentialRequestOptionsJson,
140
+ conditional: boolean,
141
+ ): Promise<PublicKeyCredential> {
142
+ const publicKey = decodeRequestOptions(options);
143
+ const request: CredentialRequestOptions = { publicKey };
144
+ if (conditional) {
145
+ (request as CredentialRequestOptions & { mediation?: string }).mediation = "conditional";
146
+ }
147
+ const credential = (await this.credentialsImpl.get(request)) as PublicKeyCredential | null;
148
+ if (!credential) {
149
+ throw new Error("pk-auth: authentication was cancelled");
150
+ }
151
+ return credential;
152
+ }
153
+ }
154
+
155
+ export function decodeCreationOptions(
156
+ options: PublicKeyCredentialCreationOptionsJson,
157
+ ): PublicKeyCredentialCreationOptions {
158
+ return {
159
+ rp: options.rp,
160
+ user: {
161
+ id: b64u.decodeToArrayBuffer(options.user.id),
162
+ name: options.user.name,
163
+ displayName: options.user.displayName,
164
+ },
165
+ challenge: b64u.decodeToArrayBuffer(options.challenge),
166
+ pubKeyCredParams: options.pubKeyCredParams,
167
+ timeout: options.timeout,
168
+ attestation: options.attestation,
169
+ authenticatorSelection: options.authenticatorSelection,
170
+ excludeCredentials: (options.excludeCredentials ?? []).map((c) => ({
171
+ id: b64u.decodeToArrayBuffer(c.id),
172
+ type: c.type,
173
+ transports: c.transports as AuthenticatorTransport[] | undefined,
174
+ })),
175
+ };
176
+ }
177
+
178
+ export function decodeRequestOptions(
179
+ options: PublicKeyCredentialRequestOptionsJson,
180
+ ): PublicKeyCredentialRequestOptions {
181
+ return {
182
+ challenge: b64u.decodeToArrayBuffer(options.challenge),
183
+ timeout: options.timeout,
184
+ rpId: options.rpId,
185
+ userVerification: options.userVerification,
186
+ allowCredentials: (options.allowCredentials ?? []).map((c) => ({
187
+ id: b64u.decodeToArrayBuffer(c.id),
188
+ type: c.type,
189
+ transports: c.transports as AuthenticatorTransport[] | undefined,
190
+ })),
191
+ };
192
+ }
193
+
194
+ export function encodeRegistrationResponse(credential: PublicKeyCredential): RegistrationResponseJson {
195
+ const response = credential.response as AuthenticatorAttestationResponse;
196
+ const transports =
197
+ typeof (response as AuthenticatorAttestationResponse & {
198
+ getTransports?: () => string[];
199
+ }).getTransports === "function"
200
+ ? (response as AuthenticatorAttestationResponse & {
201
+ getTransports: () => string[];
202
+ }).getTransports()
203
+ : [];
204
+ return {
205
+ id: b64u.encode(credential.rawId),
206
+ rawId: b64u.encode(credential.rawId),
207
+ type: "public-key",
208
+ response: {
209
+ clientDataJSON: b64u.encode(response.clientDataJSON),
210
+ attestationObject: b64u.encode(response.attestationObject),
211
+ transports,
212
+ },
213
+ };
214
+ }
215
+
216
+ export function encodeAuthenticationResponse(
217
+ credential: PublicKeyCredential,
218
+ ): AuthenticationResponseJson {
219
+ const response = credential.response as AuthenticatorAssertionResponse;
220
+ return {
221
+ id: b64u.encode(credential.rawId),
222
+ rawId: b64u.encode(credential.rawId),
223
+ type: "public-key",
224
+ response: {
225
+ clientDataJSON: b64u.encode(response.clientDataJSON),
226
+ authenticatorData: b64u.encode(response.authenticatorData),
227
+ signature: b64u.encode(response.signature),
228
+ userHandle: response.userHandle ? b64u.encode(response.userHandle) : null,
229
+ },
230
+ };
231
+ }
package/src/http.ts ADDED
@@ -0,0 +1,81 @@
1
+ // SPDX-License-Identifier: MIT
2
+
3
+ import type { ClientOptions } from "./types";
4
+
5
+ export class PkAuthHttpError extends Error {
6
+ readonly status: number;
7
+ readonly body: string;
8
+ readonly data: Record<string, unknown> | undefined;
9
+
10
+ constructor(status: number, body: string) {
11
+ super(`HTTP ${status}: ${body}`);
12
+ this.name = "PkAuthHttpError";
13
+ this.status = status;
14
+ this.body = body;
15
+ try {
16
+ const parsed = JSON.parse(body);
17
+ this.data = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
18
+ ? (parsed as Record<string, unknown>)
19
+ : undefined;
20
+ } catch {
21
+ this.data = undefined;
22
+ }
23
+ }
24
+
25
+ /** The `error` field from the parsed response body, if present. */
26
+ get error(): string | undefined {
27
+ return typeof this.data?.["error"] === "string" ? (this.data["error"] as string) : undefined;
28
+ }
29
+
30
+ /** The `detail` field from the parsed response body, if present. */
31
+ get detail(): string | undefined {
32
+ return typeof this.data?.["detail"] === "string" ? (this.data["detail"] as string) : undefined;
33
+ }
34
+
35
+ /** The `outcome` field from the parsed response body, if present. */
36
+ get outcome(): string | undefined {
37
+ return typeof this.data?.["outcome"] === "string" ? (this.data["outcome"] as string) : undefined;
38
+ }
39
+ }
40
+
41
+ /** Internal request wrapper. `authenticated: true` adds the bearer header from `getToken`. */
42
+ export async function request<T>(
43
+ options: ClientOptions,
44
+ method: string,
45
+ path: string,
46
+ body: unknown,
47
+ authenticated: boolean,
48
+ ): Promise<T> {
49
+ const fetchImpl = options.fetch ?? globalThis.fetch;
50
+ const base = options.apiBase.endsWith("/")
51
+ ? options.apiBase.slice(0, -1)
52
+ : options.apiBase;
53
+ const url = `${base}${path}`;
54
+
55
+ const headers: Record<string, string> = { accept: "application/json" };
56
+ let payload: BodyInit | undefined;
57
+ if (body !== undefined) {
58
+ headers["content-type"] = "application/json";
59
+ payload = JSON.stringify(body);
60
+ }
61
+ if (authenticated) {
62
+ const token = options.getToken?.();
63
+ if (!token) {
64
+ throw new Error("pk-auth: authenticated request requires getToken() to return a bearer token");
65
+ }
66
+ headers["authorization"] = `Bearer ${token}`;
67
+ }
68
+
69
+ const init: RequestInit = { method, headers };
70
+ if (payload !== undefined) init.body = payload;
71
+ const response = await fetchImpl(url, init);
72
+
73
+ const text = await response.text();
74
+ if (!response.ok) {
75
+ throw new PkAuthHttpError(response.status, text);
76
+ }
77
+ if (!text.length) {
78
+ return undefined as unknown as T;
79
+ }
80
+ return JSON.parse(text) as T;
81
+ }
package/src/index.ts ADDED
@@ -0,0 +1,57 @@
1
+ // SPDX-License-Identifier: MIT
2
+
3
+ export * as base64url from "./base64url";
4
+ export { PkAuthHttpError } from "./http";
5
+ export type { CeremonyResult } from "./results";
6
+ export { isCeremonySuccess, isCeremonyFailure } from "./results";
7
+ export {
8
+ PkAuthCeremonyClient,
9
+ decodeCreationOptions,
10
+ decodeRequestOptions,
11
+ encodeAuthenticationResponse,
12
+ encodeRegistrationResponse,
13
+ } from "./ceremonies";
14
+ export type {
15
+ CeremonyOptions,
16
+ FinishRegistrationParams,
17
+ StartAuthenticationParams,
18
+ StartRegistrationParams,
19
+ } from "./ceremonies";
20
+ export { PkAuthAdminClient } from "./admin";
21
+ export { PkAuthRefreshClient, isRefreshSuccess, isRefreshFailure } from "./refresh";
22
+ export type {
23
+ RefreshResult,
24
+ RefreshSuccess,
25
+ RefreshFailure,
26
+ RefreshFailureReason,
27
+ } from "./refresh";
28
+ export type * from "./types";
29
+
30
+ import { PkAuthAdminClient } from "./admin";
31
+ import { PkAuthCeremonyClient } from "./ceremonies";
32
+ import type { CeremonyOptions } from "./ceremonies";
33
+ import { PkAuthRefreshClient, type RefreshResult } from "./refresh";
34
+ import type { ClientOptions } from "./types";
35
+
36
+ /** Convenience facade: a single object exposing ceremony, admin, and refresh clients. */
37
+ export class PkAuthClient {
38
+ readonly ceremonies: PkAuthCeremonyClient;
39
+ readonly admin: PkAuthAdminClient;
40
+ readonly refreshClient: PkAuthRefreshClient;
41
+
42
+ constructor(options: ClientOptions, ceremonyOptions: CeremonyOptions = {}) {
43
+ this.ceremonies = new PkAuthCeremonyClient(options, ceremonyOptions);
44
+ this.admin = new PkAuthAdminClient(options);
45
+ this.refreshClient = new PkAuthRefreshClient(options);
46
+ }
47
+
48
+ /**
49
+ * Convenience shortcut to {@link PkAuthRefreshClient#refresh}. Returns a typed
50
+ * {@link RefreshResult} sum — does not throw on 401.
51
+ *
52
+ * @since 1.1.0
53
+ */
54
+ refresh(refreshToken: string): Promise<RefreshResult> {
55
+ return this.refreshClient.refresh(refreshToken);
56
+ }
57
+ }
package/src/refresh.ts ADDED
@@ -0,0 +1,98 @@
1
+ // SPDX-License-Identifier: MIT
2
+
3
+ import { PkAuthHttpError, request } from "./http";
4
+ import type { ClientOptions } from "./types";
5
+
6
+ /** Typed success: a fresh refresh + access token pair to swap in. */
7
+ export interface RefreshSuccess {
8
+ readonly kind: "success";
9
+ readonly accessToken: string;
10
+ readonly refreshToken: string;
11
+ readonly expiresAt: string;
12
+ }
13
+
14
+ /** Typed failure mirroring the {@code detail} field on the server's 401 body. */
15
+ export type RefreshFailureReason = "expired" | "unknown" | "replayed" | "revoked";
16
+
17
+ export interface RefreshFailure {
18
+ readonly kind: "failure";
19
+ readonly reason: RefreshFailureReason;
20
+ /** Categorical revoke reason when `reason === "revoked"`. */
21
+ readonly revokeReason?: string;
22
+ }
23
+
24
+ /** Sealed sum of refresh outcomes. */
25
+ export type RefreshResult = RefreshSuccess | RefreshFailure;
26
+
27
+ /** Type guard for {@link RefreshSuccess}. */
28
+ export function isRefreshSuccess(r: RefreshResult): r is RefreshSuccess {
29
+ return r.kind === "success";
30
+ }
31
+
32
+ /** Type guard for {@link RefreshFailure}. */
33
+ export function isRefreshFailure(r: RefreshResult): r is RefreshFailure {
34
+ return r.kind === "failure";
35
+ }
36
+
37
+ interface RawRefreshResponse {
38
+ refreshToken: string;
39
+ accessToken: string;
40
+ expiresAt: string;
41
+ }
42
+
43
+ interface RawErrorResponse {
44
+ detail?: string;
45
+ reason?: string;
46
+ }
47
+
48
+ /**
49
+ * Client for the {@code POST /auth/refresh} endpoint shipped by every pk-auth adapter. Returns
50
+ * a typed {@link RefreshResult} rather than throwing on 401 — the bearer's expected response to
51
+ * an Unknown / Expired / Replayed / Revoked outcome is to redirect to login, not to handle an
52
+ * exception.
53
+ *
54
+ * @since 1.1.0
55
+ */
56
+ export class PkAuthRefreshClient {
57
+ private readonly options: ClientOptions;
58
+ private readonly path: string;
59
+
60
+ constructor(options: ClientOptions, path: string = "/auth/refresh") {
61
+ this.options = options;
62
+ this.path = path;
63
+ }
64
+
65
+ async refresh(refreshToken: string): Promise<RefreshResult> {
66
+ try {
67
+ const response = await request<RawRefreshResponse>(
68
+ this.options,
69
+ "POST",
70
+ this.path,
71
+ { refreshToken },
72
+ false,
73
+ );
74
+ return {
75
+ kind: "success",
76
+ accessToken: response.accessToken,
77
+ refreshToken: response.refreshToken,
78
+ expiresAt: response.expiresAt,
79
+ };
80
+ } catch (e: unknown) {
81
+ if (e instanceof PkAuthHttpError && e.status === 401) {
82
+ const data = e.data as RawErrorResponse | undefined;
83
+ const detail = data?.detail;
84
+ if (
85
+ detail === "expired" ||
86
+ detail === "unknown" ||
87
+ detail === "replayed" ||
88
+ detail === "revoked"
89
+ ) {
90
+ return { kind: "failure", reason: detail, revokeReason: data?.reason };
91
+ }
92
+ // Server returned a 401 we don't recognise — surface it as the most conservative failure.
93
+ return { kind: "failure", reason: "unknown" };
94
+ }
95
+ throw e;
96
+ }
97
+ }
98
+ }
package/src/results.ts ADDED
@@ -0,0 +1,36 @@
1
+ // SPDX-License-Identifier: MIT
2
+
3
+ /**
4
+ * Discriminated union mirroring the Java sealed result hierarchies
5
+ * (AuthenticationResult / RegistrationResult) as returned by the pk-auth HTTP adapters.
6
+ *
7
+ * Authentication outcomes: success | challenge_invalid | origin_mismatch |
8
+ * signature_invalid | unknown_credential | failed
9
+ *
10
+ * Registration outcomes: success | challenge_invalid | origin_mismatch |
11
+ * attestation_rejected | duplicate_credential | invalid_payload | failed
12
+ */
13
+ export type CeremonyResult =
14
+ | { outcome: 'success'; token: string; credentialId?: string }
15
+ | { outcome: 'challenge_invalid'; detail?: string }
16
+ | { outcome: 'origin_mismatch'; detail?: string }
17
+ | { outcome: 'signature_invalid'; detail?: string }
18
+ | { outcome: 'unknown_credential'; detail?: string }
19
+ | { outcome: 'attestation_rejected'; detail?: string }
20
+ | { outcome: 'duplicate_credential'; detail?: string }
21
+ | { outcome: 'invalid_payload'; detail?: string }
22
+ | { outcome: 'failed'; detail?: string };
23
+
24
+ /** Type guard: narrows a CeremonyResult to the success variant. */
25
+ export function isCeremonySuccess(
26
+ result: CeremonyResult,
27
+ ): result is { outcome: 'success'; token: string; credentialId?: string } {
28
+ return result.outcome === 'success';
29
+ }
30
+
31
+ /** Type guard: narrows a CeremonyResult to any failure variant. */
32
+ export function isCeremonyFailure(
33
+ result: CeremonyResult,
34
+ ): result is Exclude<CeremonyResult, { outcome: 'success' }> {
35
+ return result.outcome !== 'success';
36
+ }
package/src/types.ts ADDED
@@ -0,0 +1,192 @@
1
+ // SPDX-License-Identifier: MIT
2
+
3
+ import type { Base64Url } from "./base64url";
4
+
5
+ /** Caller-supplied bearer-token accessor. Returns null when there's no session yet. */
6
+ export type TokenAccessor = () => string | null;
7
+
8
+ /** Construction options shared by the ceremony and admin clients. */
9
+ export interface ClientOptions {
10
+ /** Base URL for all pk-auth endpoints. Trailing slash is tolerated. */
11
+ apiBase: string;
12
+ /**
13
+ * Returns the current bearer token (null when unauthenticated). Required for admin operations;
14
+ * ceremony operations are anonymous and will not call it.
15
+ */
16
+ getToken?: TokenAccessor;
17
+ /** Override the global fetch (handy for tests). */
18
+ fetch?: typeof fetch;
19
+ }
20
+
21
+ // -- Ceremony wire shapes ----------------------------------------------------
22
+
23
+ export interface RpEntity {
24
+ id: string;
25
+ name: string;
26
+ }
27
+
28
+ export interface PublicKeyCredentialUserEntityJson {
29
+ id: Base64Url;
30
+ name: string;
31
+ displayName: string;
32
+ }
33
+
34
+ export interface PublicKeyCredentialDescriptorJson {
35
+ id: Base64Url;
36
+ type: "public-key";
37
+ transports?: string[];
38
+ }
39
+
40
+ export interface PublicKeyCredentialCreationOptionsJson {
41
+ rp: RpEntity;
42
+ user: PublicKeyCredentialUserEntityJson;
43
+ challenge: Base64Url;
44
+ pubKeyCredParams: { type: "public-key"; alg: number }[];
45
+ timeout?: number;
46
+ excludeCredentials?: PublicKeyCredentialDescriptorJson[];
47
+ authenticatorSelection?: {
48
+ authenticatorAttachment?: "platform" | "cross-platform";
49
+ residentKey?: "discouraged" | "preferred" | "required";
50
+ requireResidentKey?: boolean;
51
+ userVerification?: "discouraged" | "preferred" | "required";
52
+ };
53
+ attestation?: "none" | "indirect" | "direct" | "enterprise";
54
+ }
55
+
56
+ export interface PublicKeyCredentialRequestOptionsJson {
57
+ challenge: Base64Url;
58
+ timeout?: number;
59
+ rpId?: string;
60
+ allowCredentials?: PublicKeyCredentialDescriptorJson[];
61
+ userVerification?: "discouraged" | "preferred" | "required";
62
+ }
63
+
64
+ export interface StartRegistrationRequest {
65
+ username: string;
66
+ displayName?: string | null;
67
+ label?: string | null;
68
+ challenge?: Base64Url | null;
69
+ }
70
+
71
+ export interface StartRegistrationResponse {
72
+ challengeId: string;
73
+ publicKey: PublicKeyCredentialCreationOptionsJson;
74
+ }
75
+
76
+ export interface StartAuthenticationRequest {
77
+ username?: string | null;
78
+ challenge?: Base64Url | null;
79
+ }
80
+
81
+ export interface StartAuthenticationResponse {
82
+ challengeId: string;
83
+ publicKey: PublicKeyCredentialRequestOptionsJson;
84
+ }
85
+
86
+ export interface RegistrationResponseJson {
87
+ id: Base64Url;
88
+ rawId: Base64Url;
89
+ type: "public-key";
90
+ response: {
91
+ clientDataJSON: Base64Url;
92
+ attestationObject: Base64Url;
93
+ transports?: string[];
94
+ };
95
+ }
96
+
97
+ export interface AuthenticationResponseJson {
98
+ id: Base64Url;
99
+ rawId: Base64Url;
100
+ type: "public-key";
101
+ response: {
102
+ clientDataJSON: Base64Url;
103
+ authenticatorData: Base64Url;
104
+ signature: Base64Url;
105
+ userHandle: Base64Url | null;
106
+ };
107
+ }
108
+
109
+ export interface FinishRegistrationRequest {
110
+ challengeId: string;
111
+ username: string;
112
+ label?: string | null;
113
+ response: RegistrationResponseJson;
114
+ }
115
+
116
+ export interface FinishAuthenticationRequest {
117
+ challengeId: string;
118
+ response: AuthenticationResponseJson;
119
+ }
120
+
121
+ /** Server returns the wrapped RegistrationResult; relevant fields are surfaced here. */
122
+ export interface FinishRegistrationResponse {
123
+ credential: {
124
+ credentialId: Base64Url;
125
+ userHandle: Base64Url;
126
+ label: string;
127
+ transports: string[];
128
+ counter: number;
129
+ backupEligible: boolean;
130
+ backupState: boolean;
131
+ aaguid?: string | null;
132
+ authenticatorData: Base64Url;
133
+ };
134
+ }
135
+
136
+ export interface FinishAuthenticationResponse {
137
+ token: string;
138
+ }
139
+
140
+ // -- Admin wire shapes --------------------------------------------------------
141
+
142
+ export interface CredentialSummary {
143
+ credentialId: Base64Url;
144
+ label: string;
145
+ createdAt: string;
146
+ lastUsedAt?: string | null;
147
+ counter: number;
148
+ backupEligible: boolean;
149
+ backupState: boolean;
150
+ transports: string[];
151
+ }
152
+
153
+ export interface AccountSummary {
154
+ userHandle: Base64Url;
155
+ username: string;
156
+ displayName: string;
157
+ emailVerified: boolean;
158
+ phoneVerified: boolean;
159
+ credentialCount: number;
160
+ backupCodesRemaining: number;
161
+ }
162
+
163
+ export interface BackupCodeBatch {
164
+ codes: string[];
165
+ }
166
+
167
+ export interface BackupCodeCount {
168
+ remaining: number;
169
+ }
170
+
171
+ export interface EmailDispatchResult {
172
+ /** Implementation-defined token / link reference returned by the dispatcher. */
173
+ dispatchId?: string;
174
+ /** Magic-link token (testkit / dev only — real dispatchers send it out of band). */
175
+ token?: string;
176
+ }
177
+
178
+ export interface PhoneDispatchResult {
179
+ dispatchId?: string;
180
+ /** OTP code (testkit / dev only — real dispatchers send it via SMS). */
181
+ code?: string;
182
+ }
183
+
184
+ export interface EmailVerificationResult {
185
+ email: string;
186
+ verified: boolean;
187
+ }
188
+
189
+ export interface PhoneVerificationResult {
190
+ phone: string;
191
+ verified: boolean;
192
+ }