mirror of
https://github.com/teamhanko/hanko.git
synced 2025-10-31 08:35:47 +08:00
415 lines
15 KiB
HTML
415 lines
15 KiB
HTML
|
|
|
|
<!DOCTYPE html>
|
|
<html lang="en">
|
|
|
|
<head>
|
|
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title> lib/client/WebauthnClient.ts</title>
|
|
|
|
<script src="https://cdn.jsdelivr.net/gh/google/code-prettify@master/loader/run_prettify.js"></script>
|
|
<script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
|
|
<script src="./build/entry.js"></script>
|
|
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
|
|
<!--[if lt IE 9]>
|
|
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
|
|
<![endif]-->
|
|
<link href="https://fonts.googleapis.com/css?family=Roboto:100,400,700|Inconsolata,700" rel="stylesheet">
|
|
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.6.3/css/all.css" integrity="sha384-UHRtZLI+pbxtHCWp1t77Bi1L4ZtiqrqD80Kn4Z8NTSRyMA2Fd33n5dQ8lWUE00s/" crossorigin="anonymous">
|
|
<link type="text/css" rel="stylesheet" href="https://jmblog.github.io/color-themes-for-google-code-prettify/themes/tomorrow-night.min.css">
|
|
<link type="text/css" rel="stylesheet" href="styles/app.min.css">
|
|
<link type="text/css" rel="stylesheet" href="styles/iframe.css">
|
|
<link type="text/css" rel="stylesheet" href="">
|
|
<script async defer src="https://buttons.github.io/buttons.js"></script>
|
|
|
|
|
|
</head>
|
|
|
|
|
|
|
|
<body class="layout small-header">
|
|
<div id="stickyNavbarOverlay"></div>
|
|
|
|
|
|
<div class="top-nav">
|
|
<div class="inner">
|
|
<a id="hamburger" role="button" class="navbar-burger" aria-label="menu" aria-expanded="false">
|
|
<span aria-hidden="true"></span>
|
|
<span aria-hidden="true"></span>
|
|
<span aria-hidden="true"></span>
|
|
</a>
|
|
<div class="logo">
|
|
|
|
|
|
</div>
|
|
<div class="menu">
|
|
|
|
<div class="navigation">
|
|
<a
|
|
href="index.html"
|
|
class="link"
|
|
>
|
|
Documentation
|
|
</a>
|
|
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="main">
|
|
<div
|
|
class="sidebar "
|
|
id="sidebarNav"
|
|
>
|
|
|
|
<nav>
|
|
|
|
<h2><a href="index.html">Documentation</a></h2><div class="category"><h3>Classes</h3><ul><li><a href="Hanko.html">Hanko</a></li></ul></div><div class="category"><h2>SDK</h2><h3>Classes / Internal</h3><ul><li><a href="Client.html">Client</a></li><li><a href="Headers.html">Headers</a></li><li><a href="HttpClient.html">HttpClient</a></li><li><a href="PasscodeState.html">PasscodeState</a></li><li><a href="PasswordState.html">PasswordState</a></li><li><a href="Response.html">Response</a></li><li><a href="State.html">State</a></li><li><a href="UserState.html">UserState</a></li><li><a href="WebauthnState.html">WebauthnState</a></li></ul><h3>Classes / Clients</h3><ul><li><a href="ConfigClient.html">ConfigClient</a></li><li><a href="EmailClient.html">EmailClient</a></li><li><a href="PasscodeClient.html">PasscodeClient</a></li><li><a href="PasswordClient.html">PasswordClient</a></li><li><a href="UserClient.html">UserClient</a></li><li><a href="WebauthnClient.html">WebauthnClient</a></li></ul><h3>Classes / Errors</h3><ul><li><a href="ConflictError.html">ConflictError</a></li><li><a href="EmailAddressAlreadyExistsError.html">EmailAddressAlreadyExistsError</a></li><li><a href="HankoError.html">HankoError</a></li><li><a href="InvalidPasscodeError.html">InvalidPasscodeError</a></li><li><a href="InvalidPasswordError.html">InvalidPasswordError</a></li><li><a href="InvalidWebauthnCredentialError.html">InvalidWebauthnCredentialError</a></li><li><a href="MaxNumOfEmailAddressesReachedError.html">MaxNumOfEmailAddressesReachedError</a></li><li><a href="MaxNumOfPasscodeAttemptsReachedError.html">MaxNumOfPasscodeAttemptsReachedError</a></li><li><a href="NotFoundError.html">NotFoundError</a></li><li><a href="PasscodeExpiredError.html">PasscodeExpiredError</a></li><li><a href="RequestTimeoutError.html">RequestTimeoutError</a></li><li><a href="TechnicalError.html">TechnicalError</a></li><li><a href="TooManyRequestsError.html">TooManyRequestsError</a></li><li><a href="UnauthorizedError.html">UnauthorizedError</a></li><li><a href="UserVerificationError.html">UserVerificationError</a></li><li><a href="WebauthnRequestCancelledError.html">WebauthnRequestCancelledError</a></li></ul><h3>Classes / Utilities</h3><ul><li><a href="WebauthnSupport.html">WebauthnSupport</a></li></ul><h3>Interfaces / DTO</h3><ul><li><a href="Config.html">Config</a></li><li><a href="Credential.html">Credential</a></li><li><a href="Email.html">Email</a></li><li><a href="EmailConfig.html">EmailConfig</a></li><li><a href="Emails.html">Emails</a></li><li><a href="Passcode.html">Passcode</a></li><li><a href="PasswordConfig.html">PasswordConfig</a></li><li><a href="User.html">User</a></li><li><a href="UserInfo.html">UserInfo</a></li><li><a href="WebauthnCredential.html">WebauthnCredential</a></li><li><a href="WebauthnCredentials.html">WebauthnCredentials</a></li><li><a href="WebauthnFinalized.html">WebauthnFinalized</a></li><li><a href="WebauthnTransports.html">WebauthnTransports</a></li></ul><h3>Interfaces / Internal</h3><ul><li><a href="LocalStorage.html">LocalStorage</a></li><li><a href="LocalStoragePasscode.html">LocalStoragePasscode</a></li><li><a href="LocalStoragePassword.html">LocalStoragePassword</a></li><li><a href="LocalStorageUser.html">LocalStorageUser</a></li><li><a href="LocalStorageUsers.html">LocalStorageUsers</a></li><li><a href="LocalStorageWebauthn.html">LocalStorageWebauthn</a></li></ul></div>
|
|
|
|
</nav>
|
|
</div>
|
|
<div class="core" id="main-content-wrapper">
|
|
<div class="content">
|
|
<header class="page-title">
|
|
<p>Source</p>
|
|
<h1>lib/client/WebauthnClient.ts</h1>
|
|
</header>
|
|
|
|
|
|
|
|
|
|
|
|
<section>
|
|
<article>
|
|
<pre class="prettyprint source linenums"><code>import {
|
|
create as createWebauthnCredential,
|
|
get as getWebauthnCredential,
|
|
} from "@github/webauthn-json";
|
|
|
|
import { WebauthnSupport } from "../WebauthnSupport";
|
|
import { Client } from "./Client";
|
|
import { PasscodeState } from "../state/PasscodeState";
|
|
|
|
import { WebauthnState } from "../state/WebauthnState";
|
|
|
|
import {
|
|
InvalidWebauthnCredentialError,
|
|
TechnicalError,
|
|
UnauthorizedError,
|
|
WebauthnRequestCancelledError,
|
|
UserVerificationError,
|
|
} from "../Errors";
|
|
|
|
import {
|
|
Attestation,
|
|
User,
|
|
WebauthnFinalized,
|
|
WebauthnCredentials,
|
|
} from "../Dto";
|
|
|
|
/**
|
|
* A class that handles WebAuthn authentication and registration.
|
|
*
|
|
* @constructor
|
|
* @category SDK
|
|
* @subcategory Clients
|
|
* @extends {Client}
|
|
*/
|
|
class WebauthnClient extends Client {
|
|
webauthnState: WebauthnState;
|
|
passcodeState: PasscodeState;
|
|
controller: AbortController;
|
|
|
|
_getCredential = getWebauthnCredential;
|
|
_createCredential = createWebauthnCredential;
|
|
|
|
// eslint-disable-next-line require-jsdoc
|
|
constructor(api: string, timeout = 13000) {
|
|
super(api, timeout);
|
|
/**
|
|
* @public
|
|
* @type {WebauthnState}
|
|
*/
|
|
this.webauthnState = new WebauthnState();
|
|
/**
|
|
* @public
|
|
* @type {PasscodeState}
|
|
*/
|
|
this.passcodeState = new PasscodeState();
|
|
}
|
|
|
|
/**
|
|
* Performs a WebAuthn authentication ceremony. When 'userID' is specified, the API provides a list of
|
|
* allowed credentials and the browser is able to present a list of suitable credentials to the user.
|
|
*
|
|
* @param {string=} userID - The user's UUID.
|
|
* @param {boolean=} useConditionalMediation - Enables autofill assisted login.
|
|
* @return {Promise<void>}
|
|
* @throws {WebauthnRequestCancelledError}
|
|
* @throws {InvalidWebauthnCredentialError}
|
|
* @throws {RequestTimeoutError}
|
|
* @throws {TechnicalError}
|
|
* @see https://docs.hanko.io/api/public#tag/WebAuthn/operation/webauthnLoginInit
|
|
* @see https://docs.hanko.io/api/public#tag/WebAuthn/operation/webauthnLoginFinal
|
|
* @see https://www.w3.org/TR/webauthn-2/#authentication-ceremony
|
|
*/
|
|
async login(
|
|
userID?: string,
|
|
useConditionalMediation?: boolean
|
|
): Promise<void> {
|
|
const challengeResponse = await this.client.post(
|
|
"/webauthn/login/initialize",
|
|
{ user_id: userID }
|
|
);
|
|
|
|
if (!challengeResponse.ok) {
|
|
throw new TechnicalError();
|
|
}
|
|
|
|
const challenge = challengeResponse.json();
|
|
challenge.signal = this._createAbortSignal();
|
|
|
|
if (useConditionalMediation) {
|
|
// `CredentialMediationRequirement` doesn't support "conditional" in the current typescript version.
|
|
challenge.mediation = "conditional" as CredentialMediationRequirement;
|
|
}
|
|
|
|
let assertion;
|
|
try {
|
|
assertion = await this._getCredential(challenge);
|
|
} catch (e) {
|
|
throw new WebauthnRequestCancelledError(e);
|
|
}
|
|
|
|
const assertionResponse = await this.client.post(
|
|
"/webauthn/login/finalize",
|
|
assertion
|
|
);
|
|
|
|
if (assertionResponse.status === 400 || assertionResponse.status === 401) {
|
|
throw new InvalidWebauthnCredentialError();
|
|
} else if (!assertionResponse.ok) {
|
|
throw new TechnicalError();
|
|
}
|
|
|
|
const finalizeResponse: WebauthnFinalized = assertionResponse.json();
|
|
|
|
this.webauthnState
|
|
.read()
|
|
.addCredential(finalizeResponse.user_id, finalizeResponse.credential_id)
|
|
.write();
|
|
|
|
this.passcodeState.read().reset(userID).write();
|
|
|
|
return;
|
|
}
|
|
|
|
/**
|
|
* Performs a WebAuthn registration ceremony.
|
|
*
|
|
* @return {Promise<void>}
|
|
* @throws {WebauthnRequestCancelledError}
|
|
* @throws {RequestTimeoutError}
|
|
* @throws {UnauthorizedError}
|
|
* @throws {TechnicalError}
|
|
* @throws {UserVerificationError}
|
|
* @see https://docs.hanko.io/api/public#tag/WebAuthn/operation/webauthnRegInit
|
|
* @see https://docs.hanko.io/api/public#tag/WebAuthn/operation/webauthnRegFinal
|
|
* @see https://www.w3.org/TR/webauthn-2/#sctn-registering-a-new-credential
|
|
*/
|
|
async register(): Promise<void> {
|
|
const challengeResponse = await this.client.post(
|
|
"/webauthn/registration/initialize"
|
|
);
|
|
|
|
if (challengeResponse.status >= 400 && challengeResponse.status <= 499) {
|
|
throw new UnauthorizedError();
|
|
} else if (!challengeResponse.ok) {
|
|
throw new TechnicalError();
|
|
}
|
|
|
|
const challenge = challengeResponse.json();
|
|
challenge.signal = this._createAbortSignal();
|
|
|
|
let attestation;
|
|
try {
|
|
attestation = (await this._createCredential(challenge)) as Attestation;
|
|
} catch (e) {
|
|
throw new WebauthnRequestCancelledError(e);
|
|
}
|
|
|
|
// The generated PublicKeyCredentialWithAttestationJSON object does not align with the API. The list of
|
|
// supported transports must be available under a different path.
|
|
attestation.transports = attestation.response.transports;
|
|
|
|
const attestationResponse = await this.client.post(
|
|
"/webauthn/registration/finalize",
|
|
attestation
|
|
);
|
|
|
|
if (
|
|
attestationResponse.status >= 400 &&
|
|
attestationResponse.status <= 499
|
|
) {
|
|
if (attestationResponse.status === 422) {
|
|
throw new UserVerificationError();
|
|
}
|
|
throw new UnauthorizedError();
|
|
}
|
|
if (!attestationResponse.ok) {
|
|
throw new TechnicalError();
|
|
}
|
|
|
|
const finalizeResponse: WebauthnFinalized = attestationResponse.json();
|
|
this.webauthnState
|
|
.read()
|
|
.addCredential(finalizeResponse.user_id, finalizeResponse.credential_id)
|
|
.write();
|
|
|
|
return;
|
|
}
|
|
|
|
/**
|
|
* Returns a list of all WebAuthn credentials assigned to the current user.
|
|
*
|
|
* @return {Promise<WebauthnCredentials>}
|
|
* @throws {UnauthorizedError}
|
|
* @throws {RequestTimeoutError}
|
|
* @throws {TechnicalError}
|
|
* @see https://docs.hanko.io/api/public#tag/WebAuthn/operation/listCredentials
|
|
*/
|
|
async listCredentials(): Promise<WebauthnCredentials> {
|
|
const response = await this.client.get("/webauthn/credentials");
|
|
|
|
if (response.status === 401) {
|
|
throw new UnauthorizedError();
|
|
} else if (!response.ok) {
|
|
throw new TechnicalError();
|
|
}
|
|
|
|
return response.json();
|
|
}
|
|
|
|
/**
|
|
* Updates the WebAuthn credential.
|
|
*
|
|
* @param {string=} credentialID - The credential's UUID.
|
|
* @param {string} name - The new credential name.
|
|
* @return {Promise<void>}
|
|
* @throws {NotFoundError}
|
|
* @throws {UnauthorizedError}
|
|
* @throws {RequestTimeoutError}
|
|
* @throws {TechnicalError}
|
|
* @see https://docs.hanko.io/api/public#tag/WebAuthn/operation/updateCredential
|
|
*/
|
|
async updateCredential(credentialID: string, name: string): Promise<void> {
|
|
const response = await this.client.patch(
|
|
`/webauthn/credentials/${credentialID}`,
|
|
{
|
|
name,
|
|
}
|
|
);
|
|
|
|
if (response.status === 401) {
|
|
throw new UnauthorizedError();
|
|
} else if (!response.ok) {
|
|
throw new TechnicalError();
|
|
}
|
|
|
|
return;
|
|
}
|
|
|
|
/**
|
|
* Deletes the WebAuthn credential.
|
|
*
|
|
* @param {string=} credentialID - The credential's UUID.
|
|
* @return {Promise<void>}
|
|
* @throws {NotFoundError}
|
|
* @throws {UnauthorizedError}
|
|
* @throws {RequestTimeoutError}
|
|
* @throws {TechnicalError}
|
|
* @see https://docs.hanko.io/api/public#tag/WebAuthn/operation/deleteCredential
|
|
*/
|
|
async deleteCredential(credentialID: string): Promise<void> {
|
|
const response = await this.client.delete(
|
|
`/webauthn/credentials/${credentialID}`
|
|
);
|
|
|
|
if (response.status === 401) {
|
|
throw new UnauthorizedError();
|
|
} else if (!response.ok) {
|
|
throw new TechnicalError();
|
|
}
|
|
|
|
return;
|
|
}
|
|
|
|
/**
|
|
* Determines whether a credential registration ceremony should be performed. Returns 'true' when WebAuthn
|
|
* is supported and the user's credentials do not intersect with the credentials already known on the
|
|
* current browser/device.
|
|
*
|
|
* @param {User} user - The user object.
|
|
* @return {Promise<boolean>}
|
|
*/
|
|
async shouldRegister(user: User): Promise<boolean> {
|
|
const supported = WebauthnSupport.supported();
|
|
|
|
if (!user.webauthn_credentials || !user.webauthn_credentials.length) {
|
|
return supported;
|
|
}
|
|
|
|
const matches = this.webauthnState
|
|
.read()
|
|
.matchCredentials(user.id, user.webauthn_credentials);
|
|
|
|
return supported && !matches.length;
|
|
}
|
|
|
|
// eslint-disable-next-line require-jsdoc
|
|
_createAbortSignal() {
|
|
if (this.controller) {
|
|
this.controller.abort();
|
|
}
|
|
|
|
this.controller = new AbortController();
|
|
return this.controller.signal;
|
|
}
|
|
}
|
|
|
|
export { WebauthnClient };
|
|
</code></pre>
|
|
</article>
|
|
</section>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
<footer class="footer">
|
|
<div class="content has-text-centered">
|
|
<p>Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.11</a></p>
|
|
<p class="sidebar-created-by">
|
|
<a href="https://github.com/SoftwareBrothers/better-docs" target="_blank">BetterDocs theme</a> provided with <i class="fas fa-heart"></i> by
|
|
<a href="http://softwarebrothers.co" target="_blank">SoftwareBrothers - JavaScript Development Agency</a>
|
|
</p>
|
|
</div>
|
|
</footer>
|
|
|
|
</div>
|
|
<div id="side-nav" class="side-nav">
|
|
</div>
|
|
</div>
|
|
<script src="scripts/app.min.js"></script>
|
|
<script>PR.prettyPrint();</script>
|
|
<script src="scripts/linenumber.js"> </script>
|
|
|
|
|
|
</body>
|
|
</html>
|