@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.
- package/README.md +79 -0
- package/dist/index.cjs +398 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +367 -0
- package/dist/index.d.ts +367 -0
- package/dist/index.js +383 -0
- package/dist/index.js.map +1 -0
- package/package.json +61 -0
- package/src/admin.ts +77 -0
- package/src/base64url.ts +44 -0
- package/src/ceremonies.ts +231 -0
- package/src/http.ts +81 -0
- package/src/index.ts +57 -0
- package/src/refresh.ts +98 -0
- package/src/results.ts +36 -0
- package/src/types.ts +192 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,367 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Base64url (RFC 4648 §5) without padding — matches pk-auth's wire format.
|
|
3
|
+
* The server's Jackson module emits unpadded base64url; browsers can mix
|
|
4
|
+
* Uint8Array, ArrayBuffer, or already-base64url strings, so encode handles
|
|
5
|
+
* all three.
|
|
6
|
+
*/
|
|
7
|
+
type Base64Url = string;
|
|
8
|
+
declare function encode(input: ArrayBuffer | Uint8Array | ArrayBufferView): Base64Url;
|
|
9
|
+
declare function decode(input: Base64Url): Uint8Array;
|
|
10
|
+
declare function decodeToArrayBuffer(input: Base64Url): ArrayBuffer;
|
|
11
|
+
|
|
12
|
+
type base64url_Base64Url = Base64Url;
|
|
13
|
+
declare const base64url_decode: typeof decode;
|
|
14
|
+
declare const base64url_decodeToArrayBuffer: typeof decodeToArrayBuffer;
|
|
15
|
+
declare const base64url_encode: typeof encode;
|
|
16
|
+
declare namespace base64url {
|
|
17
|
+
export { type base64url_Base64Url as Base64Url, base64url_decode as decode, base64url_decodeToArrayBuffer as decodeToArrayBuffer, base64url_encode as encode };
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** Caller-supplied bearer-token accessor. Returns null when there's no session yet. */
|
|
21
|
+
type TokenAccessor = () => string | null;
|
|
22
|
+
/** Construction options shared by the ceremony and admin clients. */
|
|
23
|
+
interface ClientOptions {
|
|
24
|
+
/** Base URL for all pk-auth endpoints. Trailing slash is tolerated. */
|
|
25
|
+
apiBase: string;
|
|
26
|
+
/**
|
|
27
|
+
* Returns the current bearer token (null when unauthenticated). Required for admin operations;
|
|
28
|
+
* ceremony operations are anonymous and will not call it.
|
|
29
|
+
*/
|
|
30
|
+
getToken?: TokenAccessor;
|
|
31
|
+
/** Override the global fetch (handy for tests). */
|
|
32
|
+
fetch?: typeof fetch;
|
|
33
|
+
}
|
|
34
|
+
interface RpEntity {
|
|
35
|
+
id: string;
|
|
36
|
+
name: string;
|
|
37
|
+
}
|
|
38
|
+
interface PublicKeyCredentialUserEntityJson {
|
|
39
|
+
id: Base64Url;
|
|
40
|
+
name: string;
|
|
41
|
+
displayName: string;
|
|
42
|
+
}
|
|
43
|
+
interface PublicKeyCredentialDescriptorJson {
|
|
44
|
+
id: Base64Url;
|
|
45
|
+
type: "public-key";
|
|
46
|
+
transports?: string[];
|
|
47
|
+
}
|
|
48
|
+
interface PublicKeyCredentialCreationOptionsJson {
|
|
49
|
+
rp: RpEntity;
|
|
50
|
+
user: PublicKeyCredentialUserEntityJson;
|
|
51
|
+
challenge: Base64Url;
|
|
52
|
+
pubKeyCredParams: {
|
|
53
|
+
type: "public-key";
|
|
54
|
+
alg: number;
|
|
55
|
+
}[];
|
|
56
|
+
timeout?: number;
|
|
57
|
+
excludeCredentials?: PublicKeyCredentialDescriptorJson[];
|
|
58
|
+
authenticatorSelection?: {
|
|
59
|
+
authenticatorAttachment?: "platform" | "cross-platform";
|
|
60
|
+
residentKey?: "discouraged" | "preferred" | "required";
|
|
61
|
+
requireResidentKey?: boolean;
|
|
62
|
+
userVerification?: "discouraged" | "preferred" | "required";
|
|
63
|
+
};
|
|
64
|
+
attestation?: "none" | "indirect" | "direct" | "enterprise";
|
|
65
|
+
}
|
|
66
|
+
interface PublicKeyCredentialRequestOptionsJson {
|
|
67
|
+
challenge: Base64Url;
|
|
68
|
+
timeout?: number;
|
|
69
|
+
rpId?: string;
|
|
70
|
+
allowCredentials?: PublicKeyCredentialDescriptorJson[];
|
|
71
|
+
userVerification?: "discouraged" | "preferred" | "required";
|
|
72
|
+
}
|
|
73
|
+
interface StartRegistrationRequest {
|
|
74
|
+
username: string;
|
|
75
|
+
displayName?: string | null;
|
|
76
|
+
label?: string | null;
|
|
77
|
+
challenge?: Base64Url | null;
|
|
78
|
+
}
|
|
79
|
+
interface StartRegistrationResponse {
|
|
80
|
+
challengeId: string;
|
|
81
|
+
publicKey: PublicKeyCredentialCreationOptionsJson;
|
|
82
|
+
}
|
|
83
|
+
interface StartAuthenticationRequest {
|
|
84
|
+
username?: string | null;
|
|
85
|
+
challenge?: Base64Url | null;
|
|
86
|
+
}
|
|
87
|
+
interface StartAuthenticationResponse {
|
|
88
|
+
challengeId: string;
|
|
89
|
+
publicKey: PublicKeyCredentialRequestOptionsJson;
|
|
90
|
+
}
|
|
91
|
+
interface RegistrationResponseJson {
|
|
92
|
+
id: Base64Url;
|
|
93
|
+
rawId: Base64Url;
|
|
94
|
+
type: "public-key";
|
|
95
|
+
response: {
|
|
96
|
+
clientDataJSON: Base64Url;
|
|
97
|
+
attestationObject: Base64Url;
|
|
98
|
+
transports?: string[];
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
interface AuthenticationResponseJson {
|
|
102
|
+
id: Base64Url;
|
|
103
|
+
rawId: Base64Url;
|
|
104
|
+
type: "public-key";
|
|
105
|
+
response: {
|
|
106
|
+
clientDataJSON: Base64Url;
|
|
107
|
+
authenticatorData: Base64Url;
|
|
108
|
+
signature: Base64Url;
|
|
109
|
+
userHandle: Base64Url | null;
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
interface FinishRegistrationRequest {
|
|
113
|
+
challengeId: string;
|
|
114
|
+
username: string;
|
|
115
|
+
label?: string | null;
|
|
116
|
+
response: RegistrationResponseJson;
|
|
117
|
+
}
|
|
118
|
+
interface FinishAuthenticationRequest {
|
|
119
|
+
challengeId: string;
|
|
120
|
+
response: AuthenticationResponseJson;
|
|
121
|
+
}
|
|
122
|
+
/** Server returns the wrapped RegistrationResult; relevant fields are surfaced here. */
|
|
123
|
+
interface FinishRegistrationResponse {
|
|
124
|
+
credential: {
|
|
125
|
+
credentialId: Base64Url;
|
|
126
|
+
userHandle: Base64Url;
|
|
127
|
+
label: string;
|
|
128
|
+
transports: string[];
|
|
129
|
+
counter: number;
|
|
130
|
+
backupEligible: boolean;
|
|
131
|
+
backupState: boolean;
|
|
132
|
+
aaguid?: string | null;
|
|
133
|
+
authenticatorData: Base64Url;
|
|
134
|
+
};
|
|
135
|
+
}
|
|
136
|
+
interface FinishAuthenticationResponse {
|
|
137
|
+
token: string;
|
|
138
|
+
}
|
|
139
|
+
interface CredentialSummary {
|
|
140
|
+
credentialId: Base64Url;
|
|
141
|
+
label: string;
|
|
142
|
+
createdAt: string;
|
|
143
|
+
lastUsedAt?: string | null;
|
|
144
|
+
counter: number;
|
|
145
|
+
backupEligible: boolean;
|
|
146
|
+
backupState: boolean;
|
|
147
|
+
transports: string[];
|
|
148
|
+
}
|
|
149
|
+
interface AccountSummary {
|
|
150
|
+
userHandle: Base64Url;
|
|
151
|
+
username: string;
|
|
152
|
+
displayName: string;
|
|
153
|
+
emailVerified: boolean;
|
|
154
|
+
phoneVerified: boolean;
|
|
155
|
+
credentialCount: number;
|
|
156
|
+
backupCodesRemaining: number;
|
|
157
|
+
}
|
|
158
|
+
interface BackupCodeBatch {
|
|
159
|
+
codes: string[];
|
|
160
|
+
}
|
|
161
|
+
interface BackupCodeCount {
|
|
162
|
+
remaining: number;
|
|
163
|
+
}
|
|
164
|
+
interface EmailDispatchResult {
|
|
165
|
+
/** Implementation-defined token / link reference returned by the dispatcher. */
|
|
166
|
+
dispatchId?: string;
|
|
167
|
+
/** Magic-link token (testkit / dev only — real dispatchers send it out of band). */
|
|
168
|
+
token?: string;
|
|
169
|
+
}
|
|
170
|
+
interface PhoneDispatchResult {
|
|
171
|
+
dispatchId?: string;
|
|
172
|
+
/** OTP code (testkit / dev only — real dispatchers send it via SMS). */
|
|
173
|
+
code?: string;
|
|
174
|
+
}
|
|
175
|
+
interface EmailVerificationResult {
|
|
176
|
+
email: string;
|
|
177
|
+
verified: boolean;
|
|
178
|
+
}
|
|
179
|
+
interface PhoneVerificationResult {
|
|
180
|
+
phone: string;
|
|
181
|
+
verified: boolean;
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
declare class PkAuthHttpError extends Error {
|
|
185
|
+
readonly status: number;
|
|
186
|
+
readonly body: string;
|
|
187
|
+
readonly data: Record<string, unknown> | undefined;
|
|
188
|
+
constructor(status: number, body: string);
|
|
189
|
+
/** The `error` field from the parsed response body, if present. */
|
|
190
|
+
get error(): string | undefined;
|
|
191
|
+
/** The `detail` field from the parsed response body, if present. */
|
|
192
|
+
get detail(): string | undefined;
|
|
193
|
+
/** The `outcome` field from the parsed response body, if present. */
|
|
194
|
+
get outcome(): string | undefined;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* Discriminated union mirroring the Java sealed result hierarchies
|
|
199
|
+
* (AuthenticationResult / RegistrationResult) as returned by the pk-auth HTTP adapters.
|
|
200
|
+
*
|
|
201
|
+
* Authentication outcomes: success | challenge_invalid | origin_mismatch |
|
|
202
|
+
* signature_invalid | unknown_credential | failed
|
|
203
|
+
*
|
|
204
|
+
* Registration outcomes: success | challenge_invalid | origin_mismatch |
|
|
205
|
+
* attestation_rejected | duplicate_credential | invalid_payload | failed
|
|
206
|
+
*/
|
|
207
|
+
type CeremonyResult = {
|
|
208
|
+
outcome: 'success';
|
|
209
|
+
token: string;
|
|
210
|
+
credentialId?: string;
|
|
211
|
+
} | {
|
|
212
|
+
outcome: 'challenge_invalid';
|
|
213
|
+
detail?: string;
|
|
214
|
+
} | {
|
|
215
|
+
outcome: 'origin_mismatch';
|
|
216
|
+
detail?: string;
|
|
217
|
+
} | {
|
|
218
|
+
outcome: 'signature_invalid';
|
|
219
|
+
detail?: string;
|
|
220
|
+
} | {
|
|
221
|
+
outcome: 'unknown_credential';
|
|
222
|
+
detail?: string;
|
|
223
|
+
} | {
|
|
224
|
+
outcome: 'attestation_rejected';
|
|
225
|
+
detail?: string;
|
|
226
|
+
} | {
|
|
227
|
+
outcome: 'duplicate_credential';
|
|
228
|
+
detail?: string;
|
|
229
|
+
} | {
|
|
230
|
+
outcome: 'invalid_payload';
|
|
231
|
+
detail?: string;
|
|
232
|
+
} | {
|
|
233
|
+
outcome: 'failed';
|
|
234
|
+
detail?: string;
|
|
235
|
+
};
|
|
236
|
+
/** Type guard: narrows a CeremonyResult to the success variant. */
|
|
237
|
+
declare function isCeremonySuccess(result: CeremonyResult): result is {
|
|
238
|
+
outcome: 'success';
|
|
239
|
+
token: string;
|
|
240
|
+
credentialId?: string;
|
|
241
|
+
};
|
|
242
|
+
/** Type guard: narrows a CeremonyResult to any failure variant. */
|
|
243
|
+
declare function isCeremonyFailure(result: CeremonyResult): result is Exclude<CeremonyResult, {
|
|
244
|
+
outcome: 'success';
|
|
245
|
+
}>;
|
|
246
|
+
|
|
247
|
+
declare const PATHS: {
|
|
248
|
+
readonly startReg: "/auth/passkeys/registration/start";
|
|
249
|
+
readonly finishReg: "/auth/passkeys/registration/finish";
|
|
250
|
+
readonly startAuth: "/auth/passkeys/authentication/start";
|
|
251
|
+
readonly finishAuth: "/auth/passkeys/authentication/finish";
|
|
252
|
+
};
|
|
253
|
+
interface CeremonyOptions {
|
|
254
|
+
/** Path overrides — kept as an escape hatch for hosts that remap pk-auth's default routes. */
|
|
255
|
+
paths?: Partial<typeof PATHS>;
|
|
256
|
+
/** Optional override for navigator.credentials (tests / non-browser callers). */
|
|
257
|
+
credentials?: CredentialsContainer;
|
|
258
|
+
}
|
|
259
|
+
interface StartRegistrationParams {
|
|
260
|
+
username: string;
|
|
261
|
+
displayName?: string;
|
|
262
|
+
label?: string;
|
|
263
|
+
}
|
|
264
|
+
interface FinishRegistrationParams extends StartRegistrationResponse {
|
|
265
|
+
username: string;
|
|
266
|
+
label?: string;
|
|
267
|
+
}
|
|
268
|
+
interface StartAuthenticationParams {
|
|
269
|
+
username?: string;
|
|
270
|
+
/** When true, hands the call to `navigator.credentials.get` with `mediation: "conditional"`. */
|
|
271
|
+
conditional?: boolean;
|
|
272
|
+
}
|
|
273
|
+
declare class PkAuthCeremonyClient {
|
|
274
|
+
private readonly client;
|
|
275
|
+
private readonly paths;
|
|
276
|
+
private readonly credentials?;
|
|
277
|
+
constructor(client: ClientOptions, options?: CeremonyOptions);
|
|
278
|
+
/**
|
|
279
|
+
* Runs the full registration ceremony: server-start → `navigator.credentials.create` →
|
|
280
|
+
* server-finish. Returns the finish payload (registered credential metadata).
|
|
281
|
+
*/
|
|
282
|
+
register(params: StartRegistrationParams): Promise<FinishRegistrationResponse>;
|
|
283
|
+
/**
|
|
284
|
+
* Runs the full sign-in ceremony: server-start → `navigator.credentials.get` →
|
|
285
|
+
* server-finish. Returns the JWT (consumer is responsible for storage).
|
|
286
|
+
*/
|
|
287
|
+
authenticate(params?: StartAuthenticationParams): Promise<FinishAuthenticationResponse>;
|
|
288
|
+
startRegistration(body: StartRegistrationRequest): Promise<StartRegistrationResponse>;
|
|
289
|
+
finishRegistration(body: FinishRegistrationRequest): Promise<FinishRegistrationResponse>;
|
|
290
|
+
startAuthentication(body: StartAuthenticationRequest): Promise<StartAuthenticationResponse>;
|
|
291
|
+
finishAuthentication(body: FinishAuthenticationRequest): Promise<FinishAuthenticationResponse>;
|
|
292
|
+
private get credentialsImpl();
|
|
293
|
+
private createCredential;
|
|
294
|
+
private getCredential;
|
|
295
|
+
}
|
|
296
|
+
declare function decodeCreationOptions(options: PublicKeyCredentialCreationOptionsJson): PublicKeyCredentialCreationOptions;
|
|
297
|
+
declare function decodeRequestOptions(options: PublicKeyCredentialRequestOptionsJson): PublicKeyCredentialRequestOptions;
|
|
298
|
+
declare function encodeRegistrationResponse(credential: PublicKeyCredential): RegistrationResponseJson;
|
|
299
|
+
declare function encodeAuthenticationResponse(credential: PublicKeyCredential): AuthenticationResponseJson;
|
|
300
|
+
|
|
301
|
+
declare class PkAuthAdminClient {
|
|
302
|
+
private readonly client;
|
|
303
|
+
constructor(client: ClientOptions);
|
|
304
|
+
getAccount(): Promise<AccountSummary>;
|
|
305
|
+
listCredentials(): Promise<CredentialSummary[]>;
|
|
306
|
+
renameCredential(credentialId: string, label: string): Promise<CredentialSummary>;
|
|
307
|
+
removeCredential(credentialId: string): Promise<void>;
|
|
308
|
+
regenerateBackupCodes(): Promise<BackupCodeBatch>;
|
|
309
|
+
remainingBackupCodes(): Promise<BackupCodeCount>;
|
|
310
|
+
startEmailVerification(email: string): Promise<EmailDispatchResult>;
|
|
311
|
+
completeEmailVerification(token: string): Promise<EmailVerificationResult>;
|
|
312
|
+
startPhoneVerification(phone: string): Promise<PhoneDispatchResult>;
|
|
313
|
+
completePhoneVerification(phone: string, code: string): Promise<PhoneVerificationResult>;
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
/** Typed success: a fresh refresh + access token pair to swap in. */
|
|
317
|
+
interface RefreshSuccess {
|
|
318
|
+
readonly kind: "success";
|
|
319
|
+
readonly accessToken: string;
|
|
320
|
+
readonly refreshToken: string;
|
|
321
|
+
readonly expiresAt: string;
|
|
322
|
+
}
|
|
323
|
+
/** Typed failure mirroring the {@code detail} field on the server's 401 body. */
|
|
324
|
+
type RefreshFailureReason = "expired" | "unknown" | "replayed" | "revoked";
|
|
325
|
+
interface RefreshFailure {
|
|
326
|
+
readonly kind: "failure";
|
|
327
|
+
readonly reason: RefreshFailureReason;
|
|
328
|
+
/** Categorical revoke reason when `reason === "revoked"`. */
|
|
329
|
+
readonly revokeReason?: string;
|
|
330
|
+
}
|
|
331
|
+
/** Sealed sum of refresh outcomes. */
|
|
332
|
+
type RefreshResult = RefreshSuccess | RefreshFailure;
|
|
333
|
+
/** Type guard for {@link RefreshSuccess}. */
|
|
334
|
+
declare function isRefreshSuccess(r: RefreshResult): r is RefreshSuccess;
|
|
335
|
+
/** Type guard for {@link RefreshFailure}. */
|
|
336
|
+
declare function isRefreshFailure(r: RefreshResult): r is RefreshFailure;
|
|
337
|
+
/**
|
|
338
|
+
* Client for the {@code POST /auth/refresh} endpoint shipped by every pk-auth adapter. Returns
|
|
339
|
+
* a typed {@link RefreshResult} rather than throwing on 401 — the bearer's expected response to
|
|
340
|
+
* an Unknown / Expired / Replayed / Revoked outcome is to redirect to login, not to handle an
|
|
341
|
+
* exception.
|
|
342
|
+
*
|
|
343
|
+
* @since 1.1.0
|
|
344
|
+
*/
|
|
345
|
+
declare class PkAuthRefreshClient {
|
|
346
|
+
private readonly options;
|
|
347
|
+
private readonly path;
|
|
348
|
+
constructor(options: ClientOptions, path?: string);
|
|
349
|
+
refresh(refreshToken: string): Promise<RefreshResult>;
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/** Convenience facade: a single object exposing ceremony, admin, and refresh clients. */
|
|
353
|
+
declare class PkAuthClient {
|
|
354
|
+
readonly ceremonies: PkAuthCeremonyClient;
|
|
355
|
+
readonly admin: PkAuthAdminClient;
|
|
356
|
+
readonly refreshClient: PkAuthRefreshClient;
|
|
357
|
+
constructor(options: ClientOptions, ceremonyOptions?: CeremonyOptions);
|
|
358
|
+
/**
|
|
359
|
+
* Convenience shortcut to {@link PkAuthRefreshClient#refresh}. Returns a typed
|
|
360
|
+
* {@link RefreshResult} sum — does not throw on 401.
|
|
361
|
+
*
|
|
362
|
+
* @since 1.1.0
|
|
363
|
+
*/
|
|
364
|
+
refresh(refreshToken: string): Promise<RefreshResult>;
|
|
365
|
+
}
|
|
366
|
+
|
|
367
|
+
export { type AccountSummary, type AuthenticationResponseJson, type BackupCodeBatch, type BackupCodeCount, type CeremonyOptions, type CeremonyResult, type ClientOptions, type CredentialSummary, type EmailDispatchResult, type EmailVerificationResult, type FinishAuthenticationRequest, type FinishAuthenticationResponse, type FinishRegistrationParams, type FinishRegistrationRequest, type FinishRegistrationResponse, type PhoneDispatchResult, type PhoneVerificationResult, PkAuthAdminClient, PkAuthCeremonyClient, PkAuthClient, PkAuthHttpError, PkAuthRefreshClient, type PublicKeyCredentialCreationOptionsJson, type PublicKeyCredentialDescriptorJson, type PublicKeyCredentialRequestOptionsJson, type PublicKeyCredentialUserEntityJson, type RefreshFailure, type RefreshFailureReason, type RefreshResult, type RefreshSuccess, type RegistrationResponseJson, type RpEntity, type StartAuthenticationParams, type StartAuthenticationRequest, type StartAuthenticationResponse, type StartRegistrationParams, type StartRegistrationRequest, type StartRegistrationResponse, type TokenAccessor, base64url, decodeCreationOptions, decodeRequestOptions, encodeAuthenticationResponse, encodeRegistrationResponse, isCeremonyFailure, isCeremonySuccess, isRefreshFailure, isRefreshSuccess };
|