// The browser half of WebAuthn: two ceremonies and the byte-shuffling they need. // // Shared by the login page and the account element, which is why it is a file // rather than inline. Both need exactly these conversions, and getting them // subtly wrong in one of two copies is the kind of bug that only shows up on // the device you do not have. // // Not a module, and on `window` rather than exported: the login page is plain // HTML served before any of the app's own scripts, and a classic script is the // one shape both it and the element can load. // // ## Why the conversions exist at all // // WebAuthn's JavaScript API speaks ArrayBuffer; its JSON encoding speaks // base64url. So every challenge and credential id has to be decoded on the way // into `navigator.credentials` and encoded on the way back out. Newer browsers // offer `PublicKeyCredential.parseRequestOptionsFromJSON()` and a `toJSON()` on // the result, which do this for you -- deliberately not used here, because // feature-detecting them means two code paths through the one part of this that // is fiddly, and the ten lines below work everywhere without a branch. // // The server never sees an ArrayBuffer and never sends one: `options_to_json` // on one side and these helpers on the other are the whole contract. const bufFrom = (s) => Uint8Array.from(atob(s.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0)).buffer; const b64From = (b) => btoa(String.fromCharCode(...new Uint8Array(b))) .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); // `supported` is asked before any button is drawn. `isSecureContext` is the // browser's own answer to "will WebAuthn run here at all" -- false on plain // HTTP anywhere but localhost -- and asking it here means the page can say so // rather than letting `credentials.get()` reject with a DOMException that reads // like a bug. const supported = () => Boolean(window.PublicKeyCredential) && window.isSecureContext; async function create(options) { options.challenge = bufFrom(options.challenge); options.user.id = bufFrom(options.user.id); (options.excludeCredentials || []).forEach(c => { c.id = bufFrom(c.id); }); const credential = await navigator.credentials.create({publicKey: options}); return { id: credential.id, rawId: b64From(credential.rawId), type: credential.type, response: { clientDataJSON: b64From(credential.response.clientDataJSON), attestationObject: b64From(credential.response.attestationObject), // Advisory, and absent on older authenticators -- it is what lets the // account screen say "usb, nfc" beside a key instead of just a name. transports: credential.response.getTransports ? credential.response.getTransports() : [], }, clientExtensionResults: {}, }; } async function get(options) { options.challenge = bufFrom(options.challenge); (options.allowCredentials || []).forEach(c => { c.id = bufFrom(c.id); }); const credential = await navigator.credentials.get({publicKey: options}); return { id: credential.id, rawId: b64From(credential.rawId), type: credential.type, response: { clientDataJSON: b64From(credential.response.clientDataJSON), authenticatorData: b64From(credential.response.authenticatorData), signature: b64From(credential.response.signature), userHandle: credential.response.userHandle ? b64From(credential.response.userHandle) : null, }, clientExtensionResults: {}, }; } // What a cancelled ceremony should say. Pressing Escape, unplugging the key, or // letting the prompt time out all arrive as exceptions, and the raw // DOMException text ("The operation either timed out or was not allowed...") // reads as a failure of the application rather than as "you cancelled it". function explain(err) { if (err && (err.name === 'NotAllowedError' || err.name === 'AbortError')) { return 'Cancelled - no passkey was used.'; } if (err && err.name === 'InvalidStateError') { return 'That authenticator already has a passkey for this app.'; } if (err && err.name === 'SecurityError') { return 'This page is not a secure origin, so the browser will not use a passkey here.'; } return String(err && err.message ? err.message : err).replace('Error: ', ''); } window.passkey = {supported, create, get, explain};