Skip to content

Commit 4deeccd

Browse files
MasterKaleMasterKale
authored
Merge pull request #761 from MasterKale/feat/browser-supports-passkeys
Add new browserSupportsPasskeys helper
2 parents 9c63b8f + d9b1682 commit 4deeccd

11 files changed

Lines changed: 411 additions & 3 deletions

File tree

‎.github/workflows/ciChecks.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@ on:
77
push:
88
branches: [master, beta]
99
pull_request:
10-
branches: [master, beta]
1110

1211
jobs:
1312
unit_tests:

‎.vscode/settings.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
{
2-
"typescript.tsdk": "node_modules/typescript/lib",
2+
"js/ts.tsdk.path": "node_modules/typescript/lib",
33
"editor.formatOnSave": true,
44
"deno.path": "/Users/matt/.dvm/bin/deno",
55
"deno.enable": true,
66
"deno.config": "./deno.json",
77
"deno.disablePaths": [
88
"./scratchenv",
9-
"./example"
9+
"./example",
10+
"./cov_profile"
1011
],
1112
"editor.rulers": [
1213
100

‎packages/browser/src/helpers/browserSupportsPasskeys.test.ts‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
/// <reference lib="DOM" />
2+
import { assert, assertFalse } from '@std/assert';
3+
import { returnsNext, stub } from '@std/testing/mock';
4+
import { browserSupportsPasskeys } from './browserSupportsPasskeys.ts';
5+
import { _getBrowserCapabilitiesInternals } from './getBrowserCapabilities.ts';
6+
7+
Deno.test('Returns true when passkeyPlatformAuthenticator capability is supported', async () => {
8+
// @ts-ignore: Setting up global state
9+
globalThis.PublicKeyCredential = () => {};
10+
11+
const mockGetBrowserCapabilities = stub(
12+
_getBrowserCapabilitiesInternals,
13+
'stubThis',
14+
// @ts-ignore: Keeping tests lean
15+
returnsNext([{ passkeyPlatformAuthenticator: 'supported' }]),
16+
);
17+
18+
const supported = await browserSupportsPasskeys();
19+
20+
assert(supported);
21+
22+
mockGetBrowserCapabilities.restore();
23+
});
24+
25+
Deno.test('Returns true when userVerifyingPlatformAuthenticator capability is supported', async () => {
26+
// @ts-ignore: Setting up global state
27+
globalThis.PublicKeyCredential = () => {};
28+
29+
const mockGetBrowserCapabilities = stub(
30+
_getBrowserCapabilitiesInternals,
31+
'stubThis',
32+
// @ts-ignore: Keeping tests lean
33+
returnsNext([{ userVerifyingPlatformAuthenticator: 'supported' }]),
34+
);
35+
36+
const supported = await browserSupportsPasskeys();
37+
38+
assert(supported);
39+
40+
mockGetBrowserCapabilities.restore();
41+
});
42+
43+
Deno.test('Returns true when hybridTransport capability is supported', async () => {
44+
// @ts-ignore: Setting up global state
45+
globalThis.PublicKeyCredential = () => {};
46+
47+
const mockGetBrowserCapabilities = stub(
48+
_getBrowserCapabilitiesInternals,
49+
'stubThis',
50+
// @ts-ignore: Keeping tests lean
51+
returnsNext([{ hybridTransport: 'supported' }]),
52+
);
53+
54+
const supported = await browserSupportsPasskeys();
55+
56+
assert(supported);
57+
58+
mockGetBrowserCapabilities.restore();
59+
});
60+
61+
Deno.test('Returns false when no relevant capabilities are supported', async () => {
62+
// @ts-ignore: Setting up global state
63+
globalThis.PublicKeyCredential = () => {};
64+
65+
const mockGetBrowserCapabilities = stub(
66+
_getBrowserCapabilitiesInternals,
67+
'stubThis',
68+
// @ts-ignore: Keeping tests lean
69+
returnsNext([{}]),
70+
);
71+
72+
const supported = await browserSupportsPasskeys();
73+
74+
assertFalse(supported);
75+
76+
mockGetBrowserCapabilities.restore();
77+
});

‎packages/browser/src/helpers/browserSupportsPasskeys.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import { browserSupportsWebAuthn } from './browserSupportsWebAuthn.ts';
2+
import { getBrowserCapabilities } from './getBrowserCapabilities.ts';
3+
4+
/**
5+
* Determine if the browser is capable of facilitating use of synced passkeys for **authentication**
6+
* via local platform authenticator or via the hybrid transport. This method does NOT know if the
7+
* user actually has a passkey available to use.
8+
*/
9+
export async function browserSupportsPasskeys(): Promise<boolean> {
10+
if (!browserSupportsWebAuthn()) {
11+
return new Promise((resolve) => resolve(false));
12+
}
13+
14+
const capabilities = await getBrowserCapabilities();
15+
const {
16+
passkeyPlatformAuthenticator,
17+
userVerifyingPlatformAuthenticator,
18+
hybridTransport,
19+
} = capabilities;
20+
21+
return passkeyPlatformAuthenticator === 'supported' ||
22+
hybridTransport === 'supported' ||
23+
userVerifyingPlatformAuthenticator === 'supported';
24+
}

‎packages/browser/src/helpers/getBrowserCapabilities.test.ts‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
/// <reference lib="DOM" />
2+
import { assertEquals } from '@std/assert';
3+
import { getBrowserCapabilities } from './getBrowserCapabilities.ts';
4+
5+
Deno.test('Maps raw capabilities to string values', async () => {
6+
// @ts-ignore: Set up PublicKeyCredential
7+
globalThis.PublicKeyCredential = () => {};
8+
globalThis.PublicKeyCredential.getClientCapabilities = () =>
9+
new Promise((resolve) => {
10+
resolve({
11+
conditionalCreate: true,
12+
conditionalGet: true,
13+
hybridTransport: true,
14+
passkeyPlatformAuthenticator: false,
15+
userVerifyingPlatformAuthenticator: false,
16+
relatedOrigins: false,
17+
// These values are missing
18+
// signalAllAcceptedCredentials: undefined,
19+
// signalCurrentUserDetails: undefined,
20+
// signalUnknownCredential: undefined,
21+
});
22+
});
23+
24+
const capabilities = await getBrowserCapabilities();
25+
26+
assertEquals(
27+
capabilities,
28+
{
29+
conditionalCreate: 'supported',
30+
conditionalGet: 'supported',
31+
hybridTransport: 'supported',
32+
passkeyPlatformAuthenticator: 'unsupported',
33+
userVerifyingPlatformAuthenticator: 'unsupported',
34+
relatedOrigins: 'unsupported',
35+
signalAllAcceptedCredentials: 'unknown',
36+
signalCurrentUserDetails: 'unknown',
37+
signalUnknownCredential: 'unknown',
38+
},
39+
);
40+
});
41+
42+
Deno.test('Works even when getClientCapabilities is missing', async () => {
43+
// @ts-ignore: Pretend the method doesn't exist
44+
globalThis.PublicKeyCredential = () => {};
45+
46+
const capabilities = await getBrowserCapabilities();
47+
48+
for (const [key, value] of Object.entries(capabilities)) {
49+
assertEquals(value, 'unknown', `capability "${key}" was not "unknown"`);
50+
}
51+
});
52+
53+
Deno.test('Determines userVerifyingPlatformAuthenticator support via alternative means', async () => {
54+
// @ts-ignore: Pretend the method doesn't exist
55+
globalThis.PublicKeyCredential = () => {};
56+
globalThis.PublicKeyCredential.getClientCapabilities = () =>
57+
new Promise((resolve) => {
58+
// Equivalent to all features being `undefined`
59+
resolve({});
60+
});
61+
globalThis.PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable = async () => true;
62+
63+
const capabilities = await getBrowserCapabilities();
64+
65+
assertEquals(capabilities.userVerifyingPlatformAuthenticator, 'supported');
66+
});
67+
68+
Deno.test('Determines conditionalGet support via alternative means', async () => {
69+
// @ts-ignore: Pretend the method doesn't exist
70+
globalThis.PublicKeyCredential = () => {};
71+
globalThis.PublicKeyCredential.getClientCapabilities = () =>
72+
new Promise((resolve) => {
73+
// Equivalent to all features being `undefined`
74+
resolve({});
75+
});
76+
globalThis.PublicKeyCredential.isConditionalMediationAvailable = async () => true;
77+
78+
const capabilities = await getBrowserCapabilities();
79+
80+
assertEquals(capabilities.conditionalGet, 'supported');
81+
});

‎packages/browser/src/helpers/getBrowserCapabilities.ts‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
import type { PublicKeyCredentialClientCapabilities } from '../types/index.ts';
2+
3+
/**
4+
* A helper method that wraps WebAuthn's
5+
* [`PublicKeyCredential.getClientCapabilities()`](https://w3c.github.io/webauthn/#sctn-getClientCapabilities)
6+
* feature detection method. This method includes efforts to determine a feature's availability if a
7+
* browser reports an "unknown" level of support for it but there exists an alternative WebAuthn API
8+
* that reports the feature's availability.
9+
*
10+
* Capabilities are mapped to one of the following values:
11+
*
12+
* - **supported**: The browser supports the capability
13+
* - **unsupported**: The browser does not support the capability
14+
* - **unknown**: The browser may or may not support the capability, try it and see
15+
*
16+
* **Note:** If a WebAuthn client other than the browser is handling WebAuthn API calls (e.g. a
17+
* password manager's browser extension) then this method will report that client's capabilities
18+
* instead (assuming that client has implemented `PublicKeyCredential.getClientCapabilities()`.)
19+
*/
20+
export async function getBrowserCapabilities(): Promise<BrowserCapabilities> {
21+
if (typeof PublicKeyCredential.getClientCapabilities === 'function') {
22+
const capabilities = await PublicKeyCredential
23+
.getClientCapabilities() as PublicKeyCredentialClientCapabilities;
24+
25+
/**
26+
* The `userVerifyingPlatformAuthenticator` capability and `isUVPAA()` return value are
27+
* equivalent, so we can fall back to the value of the latter when the capability is unknown.
28+
*
29+
* https://w3c.github.io/webauthn/#dom-clientcapability-userverifyingplatformauthenticator
30+
*/
31+
let _userVerifyingPlatformAuthenticator = mapCapabilityToEnum(
32+
capabilities.userVerifyingPlatformAuthenticator,
33+
);
34+
35+
if (
36+
_userVerifyingPlatformAuthenticator === 'unknown' &&
37+
typeof PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable === 'function'
38+
) {
39+
const isUVPAA = await PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable();
40+
if (isUVPAA) {
41+
_userVerifyingPlatformAuthenticator = 'supported';
42+
} else {
43+
_userVerifyingPlatformAuthenticator = 'unsupported';
44+
}
45+
}
46+
47+
/**
48+
* The `conditionalGet` capability and `isConditionalMediationAvailable()` return value are
49+
* equivalent, so we can fall back to the value of the latter when the capability is unknown.
50+
*
51+
* https://w3c.github.io/webauthn/#dom-clientcapability-conditionalget
52+
*/
53+
let _conditionalGet = mapCapabilityToEnum(capabilities.conditionalGet);
54+
if (
55+
_conditionalGet === 'unknown' &&
56+
typeof PublicKeyCredential.isConditionalMediationAvailable === 'function'
57+
) {
58+
const isCMA = await PublicKeyCredential.isConditionalMediationAvailable();
59+
if (isCMA) {
60+
_conditionalGet = 'supported';
61+
} else {
62+
_conditionalGet = 'unsupported';
63+
}
64+
}
65+
66+
return _getBrowserCapabilitiesInternals.stubThis({
67+
conditionalCreate: mapCapabilityToEnum(capabilities.conditionalCreate),
68+
conditionalGet: _conditionalGet,
69+
hybridTransport: mapCapabilityToEnum(capabilities.hybridTransport),
70+
passkeyPlatformAuthenticator: mapCapabilityToEnum(capabilities.passkeyPlatformAuthenticator),
71+
userVerifyingPlatformAuthenticator: _userVerifyingPlatformAuthenticator,
72+
relatedOrigins: mapCapabilityToEnum(capabilities.relatedOrigins),
73+
signalAllAcceptedCredentials: mapCapabilityToEnum(capabilities.signalAllAcceptedCredentials),
74+
signalCurrentUserDetails: mapCapabilityToEnum(capabilities.signalCurrentUserDetails),
75+
signalUnknownCredential: mapCapabilityToEnum(capabilities.signalUnknownCredential),
76+
});
77+
}
78+
79+
return _getBrowserCapabilitiesInternals.stubThis({
80+
conditionalCreate: 'unknown',
81+
conditionalGet: 'unknown',
82+
hybridTransport: 'unknown',
83+
passkeyPlatformAuthenticator: 'unknown',
84+
userVerifyingPlatformAuthenticator: 'unknown',
85+
relatedOrigins: 'unknown',
86+
signalAllAcceptedCredentials: 'unknown',
87+
signalCurrentUserDetails: 'unknown',
88+
signalUnknownCredential: 'unknown',
89+
});
90+
}
91+
92+
/**
93+
* One of the following values:
94+
*
95+
* - **supported**: The browser supports the corresponding capability
96+
* - **unsupported**: The browser does not support the corresponding capability
97+
* - **unknown**: The browser may or may not support the capability, try it and see
98+
*/
99+
export type BrowserCapabilitySupport = 'supported' | 'unsupported' | 'unknown';
100+
101+
/**
102+
* Various WebAuthn features the browser may support. See each property's description for more info.
103+
*/
104+
export type BrowserCapabilities = {
105+
/** The browser can facilitate silent passkey registration after a successful auth */
106+
conditionalCreate: BrowserCapabilitySupport;
107+
/** The browser supports autofill UI to present available passkeys */
108+
conditionalGet: BrowserCapabilitySupport;
109+
/** The browser can communicate with another device via the hybrid transport to use a passkey */
110+
hybridTransport: BrowserCapabilitySupport;
111+
/** The browser can use a local platform authenticator, or a platform authenticator available on another device via the hybrid transport */
112+
passkeyPlatformAuthenticator: BrowserCapabilitySupport;
113+
/** The browser can use a locally available user-verifying platform authenticator */
114+
userVerifyingPlatformAuthenticator: BrowserCapabilitySupport;
115+
/** The browser can facilitate use of a passkey, bound to one RP ID, across different origins */
116+
relatedOrigins: BrowserCapabilitySupport;
117+
/** The browser supports the signal API that communicates the user's current allowed passkeys for this site */
118+
signalAllAcceptedCredentials: BrowserCapabilitySupport;
119+
/** The browser supports the signal API that communicates the user's current metadata */
120+
signalCurrentUserDetails: BrowserCapabilitySupport;
121+
/** The browser supports the signal API that communicates an invalid credential ID */
122+
signalUnknownCredential: BrowserCapabilitySupport;
123+
};
124+
125+
/**
126+
* Map the tri-state booleans in `PublicKeyCredential.getClientCapablities()` to more descriptive
127+
* values instead.
128+
*/
129+
function mapCapabilityToEnum(value?: boolean): BrowserCapabilitySupport {
130+
if (value === true) {
131+
return 'supported';
132+
} else if (value === false) {
133+
return 'unsupported';
134+
} else if (typeof value === 'undefined') {
135+
return 'unknown';
136+
} else {
137+
throw new Error('Unexpected capability value:', value);
138+
}
139+
}
140+
141+
// Make it possible to stub the return value during testing
142+
export const _getBrowserCapabilitiesInternals = {
143+
stubThis: (value: BrowserCapabilities) => value,
144+
};

‎packages/browser/src/index.test.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,3 +34,11 @@ Deno.test('should export method `bufferToBase64URLString`', () => {
3434
Deno.test('should export singleton `WebAuthnAbortService`', () => {
3535
assert(index.WebAuthnAbortService);
3636
});
37+
38+
Deno.test('should export method `getBrowserCapabilities`', () => {
39+
assert(index.getBrowserCapabilities);
40+
});
41+
42+
Deno.test('should export method `browserSupportsPasskeys`', () => {
43+
assert(index.browserSupportsPasskeys);
44+
});

‎packages/browser/src/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
export * from './methods/startRegistration.ts';
22
export * from './methods/startAuthentication.ts';
33
export * from './helpers/browserSupportsWebAuthn.ts';
4+
export * from './helpers/browserSupportsPasskeys.ts';
45
export * from './helpers/platformAuthenticatorIsAvailable.ts';
56
export * from './helpers/browserSupportsWebAuthnAutofill.ts';
67
export * from './helpers/base64URLStringToBuffer.ts';
78
export * from './helpers/bufferToBase64URLString.ts';
9+
export * from './helpers/getBrowserCapabilities.ts';
810
export * from './helpers/webAuthnAbortService.ts';
911
export * from './helpers/webAuthnError.ts';
1012
export * from './types/index.ts';

0 commit comments

Comments
 (0)