From ed1bad206910ab625e7f8b419a8c6b1e9dcb2134 Mon Sep 17 00:00:00 2001 From: pilcrowOnPaper Date: Fri, 26 Apr 2024 23:35:34 +0900 Subject: [PATCH] rename webauthn to passkey --- README.md | 2 +- docs/malta.config.json | 2 +- docs/pages/index.md | 2 +- .../passkey/PasskeyController/index.md | 22 +++++++++++ .../validateAssertionResponse.md | 16 ++++---- .../validateAttestationResponse.md | 38 ++++++++++++++++++ .../WebAuthnAssertionResponse.md} | 6 +-- .../WebAuthnAttestationResponse.md} | 6 +-- docs/pages/reference/passkey/index.md | 16 ++++++++ .../webauthn/WebAuthnController/index.md | 22 ----------- .../validateAttestationResponse.md | 39 ------------------- docs/pages/reference/webauthn/index.md | 16 -------- package.json | 11 ++---- src/{webauthn => passkey}/index.ts | 10 ++--- 14 files changed, 102 insertions(+), 106 deletions(-) create mode 100644 docs/pages/reference/passkey/PasskeyController/index.md rename docs/pages/reference/{webauthn/WebAuthnController => passkey/PasskeyController}/validateAssertionResponse.md (57%) create mode 100644 docs/pages/reference/passkey/PasskeyController/validateAttestationResponse.md rename docs/pages/reference/{webauthn/AssertionResponse.md => passkey/WebAuthnAssertionResponse.md} (69%) rename docs/pages/reference/{webauthn/AttestationResponse.md => passkey/WebAuthnAttestationResponse.md} (64%) create mode 100644 docs/pages/reference/passkey/index.md delete mode 100644 docs/pages/reference/webauthn/WebAuthnController/index.md delete mode 100644 docs/pages/reference/webauthn/WebAuthnController/validateAttestationResponse.md delete mode 100644 docs/pages/reference/webauthn/index.md rename src/{webauthn => passkey}/index.ts (95%) diff --git a/README.md b/README.md index ab0e6e7..2f712ab 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ A collection of auth-related utilities, including: - `oslo/jwt`: Create and verify JWTs - `oslo/oauth2`: OAuth2 helpers - `oslo/otp`: HOTP, TOTP -- `oslo/webauthn`: Verify Web Authentication API attestations and assertions +- `oslo/passkey`: Verify Web Authentication API attestations and assertions for passkeys It's lightweight, runtime-agnostic, and fully typed. diff --git a/docs/malta.config.json b/docs/malta.config.json index b3220dd..6b947f0 100644 --- a/docs/malta.config.json +++ b/docs/malta.config.json @@ -15,7 +15,7 @@ ["oslo/jwt", "/reference/jwt"], ["oslo/oauth2", "/reference/oauth2"], ["oslo/otp", "/reference/otp"], - ["oslo/webauthn", "/reference/webauthn"] + ["oslo/passkey", "/reference/passkey"] ] }, { diff --git a/docs/pages/index.md b/docs/pages/index.md index 9651f64..890e8ae 100644 --- a/docs/pages/index.md +++ b/docs/pages/index.md @@ -13,7 +13,7 @@ A collection of auth-related utilities, including: - `oslo/jwt`: Create and verify JWTs - `oslo/oauth2`: OAuth2 helpers - `oslo/otp`: HOTP, TOTP -- `oslo/webauthn`: Verify Web Authentication API attestations and assertions +- `oslo/passkey`: Verify Web Authentication API attestations and assertions for passkeys It's lightweight, runtime-agnostic, and fully typed. diff --git a/docs/pages/reference/passkey/PasskeyController/index.md b/docs/pages/reference/passkey/PasskeyController/index.md new file mode 100644 index 0000000..da9011f --- /dev/null +++ b/docs/pages/reference/passkey/PasskeyController/index.md @@ -0,0 +1,22 @@ +--- +title: "PasskeyController" +--- + +# `PasskeyController` + +Provides methods for validating WebAuthn attestation and assertion responses for passkeys. Supports ES256 (algorithm id `-7`) and RS256 (algorithm id `-257`). + +## Constructor + +```ts +function constructor(origin: string): this; +``` + +### Parameters + +- `origin`: Where the frontend is hosted (full url) + +## Methods + +- [`validateAssertionResponse()`](/reference/passkey/PasskeyController/validateAssertionResponse) +- [`validateAttestationResponse()`](/reference/passkey/PasskeyController/validateAttestationResponse) diff --git a/docs/pages/reference/webauthn/WebAuthnController/validateAssertionResponse.md b/docs/pages/reference/passkey/PasskeyController/validateAssertionResponse.md similarity index 57% rename from docs/pages/reference/webauthn/WebAuthnController/validateAssertionResponse.md rename to docs/pages/reference/passkey/PasskeyController/validateAssertionResponse.md index 108b255..cbd2b64 100644 --- a/docs/pages/reference/webauthn/WebAuthnController/validateAssertionResponse.md +++ b/docs/pages/reference/passkey/PasskeyController/validateAssertionResponse.md @@ -1,19 +1,19 @@ --- -title: "WebAuthnController.validateAssertionResponse()" +title: "PasskeyController.validateAssertionResponse()" --- -# `WebAuthnController.validateAssertionResponse()` +# `PasskeyController.validateAssertionResponse()` Validates a WebAuthn assertion response, including the signature. Supports ES256 (algorithm id `-7`) and RS256 (algorithm id `-257`). Throws an error on invalid response. ## Definition ```ts -//$ AssertionResponse=/reference/webauthn/AssertionResponse +//$ WebAuthnAssertionResponse=/reference/passkey/WebAuthnAssertionResponse function validateAssertionResponse( algorithm: "ES256" | "RS256", publicKey: Uint8Array, - response: $$AssertionResponse, + response: $$WebAuthnAssertionResponse, challenge: Uint8Array ): Promise; ``` @@ -28,15 +28,15 @@ function validateAssertionResponse( ## Example ```ts -//$ AssertionResponse=/reference/webauthn/AssertionResponse -//$ webAuthnController=/reference/webauthn/WebAuthnController +//$ WebAuthnAssertionResponse=/reference/passkey/WebAuthnAssertionResponse +//$ passkeyController=/reference/passkey/PasskeyController try { - const response: $$AssertionResponse = { + const response: $$WebAuthnAssertionResponse = { clientDataJSON, authenticatorData, signature }; - await $$webAuthnController.validateAssertionResponse("ES256", publicKey, response, challenge); + await $$passkeyController.validateAssertionResponse("ES256", publicKey, response, challenge); } catch { // failed to validate } diff --git a/docs/pages/reference/passkey/PasskeyController/validateAttestationResponse.md b/docs/pages/reference/passkey/PasskeyController/validateAttestationResponse.md new file mode 100644 index 0000000..e2e8bf7 --- /dev/null +++ b/docs/pages/reference/passkey/PasskeyController/validateAttestationResponse.md @@ -0,0 +1,38 @@ +--- +title: "PasskeyController.validateAssertionResponse()" +--- + +# `PasskeyController.validateAttestationResponse()` + +Validates a WebAuthn attestation response, including the signature, but not the attestation certificate. Throws an error on invalid response. + +## Definition + +```ts +//$ WebAuthnAttestationResponse=/reference/passkey/WebAuthnAttestationResponse +function validateAttestationResponse( + response: $$WebAuthnAttestationResponse, + challenge: Uint8Array +): Promise; +``` + +### Parameters + +- `response`: Attestation response +- `challenge`: Challenge used for creating the signature + +## Example + +```ts +//$ WebAuthnAttestationResponse=/reference/passkey/WebAuthnAttestationResponse +//$ passkeyController=/reference/passkey/PasskeyController +try { + const response: $$WebAuthnAttestationResponse = { + clientDataJSON, + authenticatorData + }; + await $$passkeyController.validateAttestationResponse(response, challenge); +} catch { + // failed to validate +} +``` diff --git a/docs/pages/reference/webauthn/AssertionResponse.md b/docs/pages/reference/passkey/WebAuthnAssertionResponse.md similarity index 69% rename from docs/pages/reference/webauthn/AssertionResponse.md rename to docs/pages/reference/passkey/WebAuthnAssertionResponse.md index 0496248..2c945f2 100644 --- a/docs/pages/reference/webauthn/AssertionResponse.md +++ b/docs/pages/reference/passkey/WebAuthnAssertionResponse.md @@ -1,15 +1,15 @@ --- -title: "AssertionResponse" +title: "WebAuthnAssertionResponse" --- -# `AssertionResponse` +# `WebAuthnAssertionResponse` Represents a WebAuthn assertion response. ## Definition ```ts -interface AssertionResponse { +interface WebAuthnAssertionResponse { clientDataJSON: Uint8Array; authenticatorData: Uint8Array; signature: Uint8Array; diff --git a/docs/pages/reference/webauthn/AttestationResponse.md b/docs/pages/reference/passkey/WebAuthnAttestationResponse.md similarity index 64% rename from docs/pages/reference/webauthn/AttestationResponse.md rename to docs/pages/reference/passkey/WebAuthnAttestationResponse.md index 0d20c13..bf0a14a 100644 --- a/docs/pages/reference/webauthn/AttestationResponse.md +++ b/docs/pages/reference/passkey/WebAuthnAttestationResponse.md @@ -1,15 +1,15 @@ --- -title: "AttestationResponse" +title: "WebAuthnAttestationResponse" --- -# `AttestationResponse` +# `WebAuthnAttestationResponse` Represents a WebAuthn attestation response. ## Definition ```ts -interface AttestationResponse { +interface WebAuthnAttestationResponse { clientDataJSON: Uint8Array; authenticatorData: Uint8Array; } diff --git a/docs/pages/reference/passkey/index.md b/docs/pages/reference/passkey/index.md new file mode 100644 index 0000000..7c49c20 --- /dev/null +++ b/docs/pages/reference/passkey/index.md @@ -0,0 +1,16 @@ +--- +title: "oslo/passkey" +--- + +# `oslo/passkey` + +Provides utilities for working with passkeys using the Web Authentication API. + +## Classes + +- [`PasskeyController`](/reference/passkey/PasskeyController) + +## Interfaces + +- [`WebAuthnAssertionResponse`](/reference/passkey/WebAuthnAssertionResponse) +- [`WebAuthnAttestationResponse`](/reference/passkey/WebAuthnAttestationResponse) diff --git a/docs/pages/reference/webauthn/WebAuthnController/index.md b/docs/pages/reference/webauthn/WebAuthnController/index.md deleted file mode 100644 index 0f6d16f..0000000 --- a/docs/pages/reference/webauthn/WebAuthnController/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: "WebAuthnController" ---- - -# `WebAuthnController` - -Provides methods for validating WebAuthn attestation and assertion responses. Supports ES256 (algorithm id `-7`) and RS256 (algorithm id `-257`). - -## Constructor - -```ts -function constructor(origin: string): this; -``` - -### Parameters - -- `origin`: Where the frontend is hosted (full url) - -## Methods - -- [`validateAssertionResponse()`](/reference/webauthn/WebAuthnController/validateAssertionResponse) -- [`validateAttestationResponse()`](/reference/webauthn/WebAuthnController/validateAttestationResponse) diff --git a/docs/pages/reference/webauthn/WebAuthnController/validateAttestationResponse.md b/docs/pages/reference/webauthn/WebAuthnController/validateAttestationResponse.md deleted file mode 100644 index 13cf4f5..0000000 --- a/docs/pages/reference/webauthn/WebAuthnController/validateAttestationResponse.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "WebAuthnController.validateAssertionResponse()" ---- - -# `WebAuthnController.validateAttestationResponse()` - -Validates a WebAuthn attestation response, including the signature, but not the attestation certificate. Throws an error on invalid response. - -## Definition - -```ts -//$ AttestationResponse=/reference/webauthn/AttestationResponse -function validateAttestationResponse( - response: $$AttestationResponse, - challenge: Uint8Array -): Promise; -``` - -### Parameters - -- `response`: Attestation response -- `challenge`: Challenge used for creating the signature - -## Example - -```ts -//$ AttestationResponse=/reference/webauthn/AttestationResponse -//$ webAuthnController=/reference/webauthn/WebAuthnController -try { - const response: $$AttestationResponse = { - // all `Uint8Array` type (`Uint8Array`, `Uint8Array` etc) - clientDataJSON, - authenticatorData - }; - await $$webAuthnController.validateAttestationResponse(response, challenge); -} catch { - // failed to validate -} -``` diff --git a/docs/pages/reference/webauthn/index.md b/docs/pages/reference/webauthn/index.md deleted file mode 100644 index e40d03a..0000000 --- a/docs/pages/reference/webauthn/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "oslo/webauthn" ---- - -# `oslo/webauthn` - -Provides utilities for working with Web Authentication, including Passkeys. - -## Classes - -- [`WebAuthnController`](/reference/webauthn/WebAuthnController) - -## Interfaces - -- [`AssertionResponse`](/reference/webauthn/AssertionResponse) -- [`AttestationResponse`](/reference/webauthn/AttestationResponse) diff --git a/package.json b/package.json index bebe0c9..986d129 100644 --- a/package.json +++ b/package.json @@ -24,7 +24,7 @@ "./jwt": "./dist/jwt/index.js", "./oauth2": "./dist/oauth2/index.js", "./otp": "./dist/otp/index.js", - "./webauthn": "./dist/webauthn/index.js" + "./passkey": "./dist/passkey/index.js" }, "typesVersions": { "*": { @@ -52,8 +52,8 @@ "otp": [ "dist/otp/index.d.ts" ], - "webauthn": [ - "dist/webauthn/index.d.ts" + "passkey": [ + "dist/passkey/index.d.ts" ] } }, @@ -63,6 +63,7 @@ "jwt", "crypto", "webauthn", + "passkey", "otp", "encoding", "auth", @@ -84,9 +85,5 @@ "prettier": "^3.0.3", "typescript": "^5.2.2", "vitest": "^0.34.6" - }, - "dependencies": { - "@node-rs/argon2": "1.7.0", - "@node-rs/bcrypt": "1.9.0" } } diff --git a/src/webauthn/index.ts b/src/passkey/index.ts similarity index 95% rename from src/webauthn/index.ts rename to src/passkey/index.ts index 8ba3ff5..a1921ab 100644 --- a/src/webauthn/index.ts +++ b/src/passkey/index.ts @@ -2,25 +2,25 @@ import { base64url } from "../encoding/index.js"; import { compareBytes, concatenateBytes } from "../binary/index.js"; import { ECDSA, RSASSAPKCS1v1_5, sha256 } from "../crypto/index.js"; -export interface AttestationResponse { +export interface WebAuthnAttestationResponse { clientDataJSON: Uint8Array; authenticatorData: Uint8Array; } -export interface AssertionResponse { +export interface WebAuthnAssertionResponse { clientDataJSON: Uint8Array; authenticatorData: Uint8Array; signature: Uint8Array; } -export class WebAuthnController { +export class PasskeyController { private originURL: URL; constructor(origin: string) { this.originURL = new URL(origin); } public async validateAttestationResponse( - response: AttestationResponse, + response: WebAuthnAttestationResponse, challenge: Uint8Array ): Promise { const validClientDataJSON = this.verifyClientDataJSON( @@ -41,7 +41,7 @@ export class WebAuthnController { public async validateAssertionResponse( algorithm: "ES256" | "RS256", publicKey: Uint8Array, - response: AssertionResponse, + response: WebAuthnAssertionResponse, challenge: Uint8Array ): Promise { const validClientDataJSON = this.verifyClientDataJSON(