Add sendSignal() helper

packages/browser/deno.json

@@ -44,5 +44,12 @@
       "./src/**/__jest__",
       "./npm"
     ]
+  },
+  "lint": {
+    "rules": {
+      "exclude": [
+        "require-await"
+      ]
+    }
   }
 }

packages/browser/src/helpers/__jest__/generateCustomError.ts

@@ -8,6 +8,7 @@ type WebAuthnErrorName =
   | 'NotAllowedError'
   | 'NotSupportedError'
   | 'SecurityError'
+  | 'TypeError'
   | 'UnknownError';
 
 export function generateCustomError(

packages/browser/src/helpers/identifySignalError.ts

@@ -0,0 +1,81 @@
+import { isValidDomain } from './isValidDomain.ts';
+import { WebAuthnError } from './webAuthnError.ts';
+import type {
+  SendSignalAllAcceptedCredentialsOpts,
+  SendSignalCurrentUserDetailsOpts,
+  SendSignalUnknownCredentialOpts,
+} from '../methods/sendSignal.ts';
+
+/**
+ * Attempt to intuit _why_ an error was raised after calling one of the WebAuthn Signal APIs
+ */
+export function identifySignalError({ error, options }: {
+  error: Error;
+  options:
+    | SendSignalUnknownCredentialOpts
+    | SendSignalAllAcceptedCredentialsOpts
+    | SendSignalCurrentUserDetailsOpts;
+}): WebAuthnError {
+  /**
+   * General Signal API error conditions
+   */
+  if (error.name === 'SecurityError') {
+    const effectiveDomain = globalThis.location.hostname;
+    if (!isValidDomain(effectiveDomain)) {
+      // https://w3c.github.io/webauthn/#sctn-signal-methods-async-rp-id-validation (Step 1)
+      return new WebAuthnError({
+        message: `"${globalThis.location.hostname}" is an invalid domain`,
+        code: 'ERROR_INVALID_DOMAIN',
+        cause: error,
+      });
+    }
+
+    // https://w3c.github.io/webauthn/#sctn-signal-methods-async-rp-id-validation (Step 3)
+    return new WebAuthnError({
+      message:
+        `The browser does not support Related Origins to enable signals for RP ID "${options.rpID}" on domain "${globalThis.location.hostname}"`,
+      code: 'ERROR_INVALID_RP_ID',
+      cause: error,
+    });
+  }
+
+  /**
+   * Signal-specific error conditions
+   */
+  if (options.signalName === 'unknownCredential') {
+    if (error.name === 'TypeError') {
+      // https://w3c.github.io/webauthn/#sctn-signalUnknownCredential (Step 1)
+      return new WebAuthnError({
+        message: 'credentialID is an invalid base64url string',
+        code: 'ERROR_SIGNAL_INVALID_ARGUMENT',
+        cause: error,
+      });
+    }
+  } else if (options.signalName === 'allAcceptedCredentials') {
+    if (error.name === 'TypeError') {
+      // https://w3c.github.io/webauthn/#sctn-signalAllAcceptedCredentials (Step 1)
+      // https://w3c.github.io/webauthn/#sctn-signalAllAcceptedCredentials (Step 2)
+      return new WebAuthnError({
+        message: 'userID, or an entry in allAcceptedCredentialIDs, is an invalid base64url string',
+        code: 'ERROR_SIGNAL_INVALID_ARGUMENT',
+        cause: error,
+      });
+    }
+  } else if (options.signalName === 'currentUserDetails') {
+    if (error.name === 'TypeError') {
+      // https://w3c.github.io/webauthn/#sctn-signalCurrentUserDetails
+      return new WebAuthnError({
+        message: 'userID is an invalid base64url string',
+        code: 'ERROR_SIGNAL_INVALID_ARGUMENT',
+        cause: error,
+      });
+    }
+  }
+
+  // Consistently return a WebAuthnError, but point to the original error for more info
+  return new WebAuthnError({
+    message: error.message,
+    code: 'ERROR_PASSTHROUGH_SEE_CAUSE_PROPERTY',
+    cause: error,
+  });
+}

packages/browser/src/helpers/webAuthnError.ts

@@ -48,4 +48,5 @@ export type WebAuthnErrorCode =
   | 'ERROR_AUTHENTICATOR_PREVIOUSLY_REGISTERED'
   | 'ERROR_AUTHENTICATOR_NO_SUPPORTED_PUBKEYCREDPARAMS_ALG'
   | 'ERROR_AUTO_REGISTER_USER_VERIFICATION_FAILURE'
+  | 'ERROR_SIGNAL_INVALID_ARGUMENT'
   | 'ERROR_PASSTHROUGH_SEE_CAUSE_PROPERTY';

packages/browser/src/index.test.ts

@@ -42,3 +42,7 @@ Deno.test('should export method `getBrowserCapabilities`', () => {
 Deno.test('should export method `browserSupportsPasskeys`', () => {
   assert(index.browserSupportsPasskeys);
 });
+
+Deno.test('should export method `sendSignal`', () => {
+  assert(index.sendSignal);
+});

packages/browser/src/index.ts

@@ -1,5 +1,6 @@
 export * from './methods/startRegistration.ts';
 export * from './methods/startAuthentication.ts';
+export * from './methods/sendSignal.ts';
 export * from './helpers/browserSupportsWebAuthn.ts';
 export * from './helpers/browserSupportsPasskeys.ts';
 export * from './helpers/platformAuthenticatorIsAvailable.ts';