@capawesome/capacitor-passkeys 0.0.1 → 0.1.0

package/README.md

@@ -1,4 +1,4 @@
-# @capawesome/capacitor-passkeys
+# Capacitor Passkeys Plugin
 
 Capacitor plugin to create and authenticate with [passkeys](https://fidoalliance.org/passkeys/) based on the [WebAuthn](https://www.w3.org/TR/webauthn-2/) standard.
 
@@ -10,22 +10,27 @@ Capacitor plugin to create and authenticate with [passkeys](https://fidoalliance
 
 ## Features
 
-We are proud to offer one of the most complete and feature-rich Capacitor plugins for passkeys. Here are some of the key features:
+The Capacitor Passkeys plugin is one of the most complete passkey authentication solutions for Capacitor apps. Here are some of the key features:
 
 - 🔐 **Passkey creation**: Register new passkeys with the platform authenticator.
 - 🔑 **Passkey authentication**: Authenticate users with their existing passkeys.
 - 🌐 **WebAuthn standard**: Uses the WebAuthn JSON serialization so any WebAuthn server library works unchanged.
 - 📱 **Availability check**: Check if passkeys are available on the device.
 - 🖥️ **Web support**: Full web support via the native WebAuthn browser API.
-- 🔗 **Compatibility**: Works alongside the [Biometrics](https://capawesome.io/plugins/biometrics/) and [OAuth](https://capawesome.io/plugins/oauth/) plugins.
+- 🤝 **Compatibility**: Works alongside the [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/) and [OAuth](https://capawesome.io/docs/sdks/capacitor/oauth/) plugins.
 - 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
 - 🔁 **Up-to-date**: Always supports the latest Capacitor version.
 
 Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!
 
-## Newsletter
+## Use Cases
 
-Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+The Passkeys plugin is typically used to modernize the authentication of an app, for example:
+
+- **Passwordless sign-in**: Let users authenticate with a passkey instead of typing a password.
+- **Passkey enrollment**: Let existing users register a passkey for their account after they signed in with their current credentials.
+- **Progressive enhancement**: Check with `isAvailable()` whether passkeys are supported on the device and offer them as an alternative to your existing login.
+- **Server integration**: Pass the options and results of any WebAuthn server library through unchanged, thanks to the WebAuthn JSON serialization.
 
 ## Compatibility
 
@@ -122,6 +127,12 @@ No configuration required for this plugin.
 
 ## Usage
 
+The following examples show how to create a new passkey, authenticate with an existing passkey, and check whether passkeys are available on the device.
+
+### Create a new passkey
+
+Register a new passkey for a user account. In a real app, the options must be provided by your WebAuthn server, and the result must be passed back to it for verification:
+
 ```typescript
 import { Passkeys } from '@capawesome/capacitor-passkeys';
 
@@ -150,6 +161,14 @@ const createPasskey = async () => {
   // e.g. via `verifyRegistrationResponse()` from SimpleWebAuthn.
   return result;
 };
+```
+
+### Authenticate with an existing passkey
+
+Sign a user in with a passkey that was previously created for your relying party. Again, the options come from your WebAuthn server and the result is verified by it:
+
+```typescript
+import { Passkeys } from '@capawesome/capacitor-passkeys';
 
 const getPasskey = async () => {
   // In a real app, the options must be provided by your WebAuthn server,
@@ -163,6 +182,14 @@ const getPasskey = async () => {
   // e.g. via `verifyAuthenticationResponse()` from SimpleWebAuthn.
   return result;
 };
+```
+
+### Check if passkeys are available
+
+Check whether passkeys are available on the device before offering them in your login UI. On Android, this returns `true` if the device runs Android 9 (API level 28) or higher. On iOS, this always returns `true`. On Web, this returns `true` if the browser supports WebAuthn and a user-verifying platform authenticator is available:
+
+```typescript
+import { Passkeys } from '@capawesome/capacitor-passkeys';
 
 const isAvailable = async () => {
   const { available } = await Passkeys.isAvailable();
@@ -463,6 +490,47 @@ Keep the following in mind when testing your passkey integration:
 
 Conditional UI (passkey autofill) is not supported by this plugin. The operating system autofill integrations target native text fields, not HTML inputs in a web view.
 
+## FAQ
+
+### How is this plugin different from other similar plugins?
+
+It implements the full WebAuthn standard using the JSON serialization, so the options and results from any WebAuthn server library pass through unchanged on Android, iOS, and the Web. Passkey creation, authentication, and an `isAvailable()` capability check are all covered through a fully typed, actively maintained API. If you only need a local face or fingerprint check, a simpler biometric setup is enough; if you want to replace passwords with server-verified passkeys across every platform, this plugin is designed for exactly that.
+
+### Why do the plugin methods reject with the `DOMAIN_NOT_ASSOCIATED` error code?
+
+This error means that your app is not associated with the domain of the relying party (`rp.id` / `rpId`). On Android, you must host a Digital Asset Links file at `https://<your-domain>/.well-known/assetlinks.json` that delegates the `common.get_login_creds` permission to your app. On iOS, you must add the Associated Domains capability with the `webcredentials` service type and host a matching `apple-app-site-association` file. See the [Installation](#installation) section for the details. Also keep in mind that changes to these files can take some time to propagate, as they are cached by Apple and Google.
+
+### Do I need my own WebAuthn server to use this plugin?
+
+Yes. The challenges shown in the examples are only placeholders. In production, the options for `createPasskey(...)` and `getPasskey(...)` must be generated by a WebAuthn server, and the results must be verified by it, for example with a library such as [SimpleWebAuthn](https://simplewebauthn.dev/). Since the plugin uses the WebAuthn JSON serialization, any WebAuthn server library works unchanged.
+
+### Which devices support passkeys?
+
+On Android, passkeys are supported on Android 9 (API level 28) and higher with an available credential provider such as Google Password Manager. On iOS, passkeys are supported on iOS 15 and higher. On the web, passkeys are supported in browsers that implement WebAuthn with a user-verifying platform authenticator. Use the `isAvailable()` method to check the availability at runtime.
+
+### Does this plugin support passkey autofill (Conditional UI)?
+
+No, Conditional UI is not supported. The operating system autofill integrations target native text fields, not HTML inputs in a web view. See the [Limitations](#limitations) section for more details.
+
+### What is the difference between this plugin and the Biometrics plugin?
+
+The [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/) plugin performs a local biometric check (e.g. face or fingerprint recognition) on the device, for example to protect a screen inside your app. The Passkeys plugin implements the WebAuthn standard, where the authentication is cryptographically verified by your server, making it suitable to replace password-based sign-in entirely.
+
+### Can I use this plugin with Ionic, React, Vue or Angular?
+
+Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.
+
+## Related Plugins
+
+- [Biometrics](https://capawesome.io/docs/sdks/capacitor/biometrics/): Request biometric authentication, such as face or fingerprint recognition.
+- [OAuth](https://capawesome.io/docs/sdks/capacitor/oauth/): Communicate with OAuth 2.0 and OpenID Connect providers.
+- [Secure Preferences](https://capawesome.io/docs/sdks/capacitor/secure-preferences/): Securely store key/value pairs such as passwords or tokens.
+- [Password Autofill](https://capawesome.io/docs/sdks/capacitor/password-autofill/): Save passwords to the platform credential store.
+
+## Newsletter
+
+Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+
 ## Changelog
 
 See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/passkeys/CHANGELOG.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@capawesome/capacitor-passkeys",
-  "version": "0.0.1",
-  "description": "Capacitor plugin to create and authenticate with passkeys (WebAuthn).",
+  "version": "0.1.0",
+  "description": "Capacitor plugin to create and authenticate with passkeys (WebAuthn) on Android, iOS, and Web.",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",
   "types": "dist/esm/index.d.ts",
@@ -33,11 +33,19 @@
       "url": "https://opencollective.com/capawesome"
     }
   ],
-  "homepage": "https://capawesome.io/docs/plugins/passkeys/",
+  "homepage": "https://capawesome.io/docs/sdks/capacitor/passkeys/",
   "keywords": [
     "capacitor",
     "plugin",
-    "native"
+    "native",
+    "capacitor-plugin",
+    "passkeys",
+    "passkey",
+    "webauthn",
+    "fido2",
+    "passwordless",
+    "authentication",
+    "credential manager"
   ],
   "scripts": {
     "verify": "npm run verify:ios && npm run verify:android && npm run verify:web",