@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/passkeys/passkey-conditional-create.md

@@ -0,0 +1,134 @@
+# Passkey Conditional Create (Post-Login Promotion)
+
+This guide details how to automatically and silently register a passkey for a user immediately after a successful password-based sign-in, minimizing friction and boosting passkey adoption.
+
+## The Right Trigger Moment
+
+Automatic passkey creation (also known as Conditional Create or silent post-login promotion) MUST only be triggered **immediately after a successful, full sign-in that involved a password**. 
+* Do not attempt conditional creation for passwordless flows (e.g., magic links, SMS OTP, or identity federation).
+* If multi-factor authentication is required, you MUST wait until all factors have succeeded before initiating conditional creation.
+* Ensure a valid, authenticated user session is active before making requests to creation endpoints.
+
+## Implementation Steps
+
+### 1. Abort Prior Autofill Actions
+If the sign-in page utilizes form autofill (Conditional UI/Get), the active credential get call must be aborted to prevent browser conflicts.
+* Call `abortController.abort()` on the `AbortController` attached to the pending `navigator.credentials.get()` autofill request before calling `navigator.credentials.create()`.
+
+### 2. Feature Detection
+Determine whether Conditional Create is available by checking `conditionalCreate` with `PublicKeyCredential.getClientCapabilities()`.
+
+```javascript
+const capabilities = await PublicKeyCredential.getClientCapabilities();
+if (capabilities.conditionalCreate) {
+  // Conditional create is available
+}
+```
+
+### 3. Create a passkey with Conditional Create
+* Pass `mediation: 'conditional'` within the `navigator.credentials.create()` options. This signals the browser to handle the passkey creation flow silently in the background or contextually without throwing obtrusive modal dialogs.
+* Populate `excludeCredentials` with the user's existing passkey credential IDs to avoid registering duplicate keys.
+
+### 4. Silent Error Handling
+* Wrap the passkey creation prompt (`navigator.credentials.create`) in a try/catch block. You MUST catch and silently ignore typical user-facing exceptions (`InvalidStateError`, `NotAllowedError`, `AbortError`) without rendering any error UI to the user.
+
+### 5. Server-Side User Presence Verification
+* The server-side verification endpoint MUST relax the User Presence (UP) requirement (`requireUserPresence: false`) **ONLY** when verifying credentials produced by a conditional-create trigger. Strict presence verification must remain active for standard explicit creations.
+
+### 6. Handle Failed Server Verification gracefully
+* If `navigator.credentials.create()` succeeds but the server verification fetch returns a bad response (e.g., signature verification fails), invoke `PublicKeyCredential.signalUnknownCredential()` to prevent orphaned credentials from lingering in the passkey provider.
+
+## Code Example
+
+```javascript
+// optionsFetch and registerVerifyFetch are app-defined server endpoint requests
+import { optionsFetch, registerVerifyFetch } from './api.js';
+
+async function triggerConditionalCreate(loginAbortController) {
+  const capabilities = await PublicKeyCredential.getClientCapabilities();
+  if (capabilities.conditionalCreate !== true) {
+    return; // Platform does not support conditional creation
+  }
+
+  // 1. Abort any active autofill conditional-get controllers to clear the WebAuthn pipeline
+  loginAbortController.abort();
+
+  // 2. Fetch creation options signaling the backend that this is a conditional request
+  const creationOptionsJSON = await optionsFetch({ conditional: true });
+  const publicKey = PublicKeyCredential.parseCreationOptionsFromJSON(creationOptionsJSON);
+
+  let credential;
+  try {
+    // 3. Invoke silent credentials creation prompt
+    credential = await navigator.credentials.create({ 
+      publicKey,
+      mediation: 'conditional' // Silent background creation mediation
+    });
+  } catch (e) {
+    // 4. Silently swallow common WebAuthn browser exceptions
+    if (['InvalidStateError', 'NotAllowedError', 'AbortError'].includes(e.name)) {
+      return; 
+    }
+    console.error('Unexpected conditional create error:', e);
+    return;
+  }
+
+  // 5. Server verification step using dedicated Try/Catch block
+  let encodedResponse = credential.toJSON();
+  try {
+    const response = await registerVerifyFetch(encodedResponse);
+    if (!response.ok) {
+      // If the server verification fails, clean up using Signal API
+      if (PublicKeyCredential.signalUnknownCredential) {
+        await PublicKeyCredential.signalUnknownCredential({
+          rpId, // RP ID must match the one defined on the server
+          credentialId: encodedResponse.id
+        });
+      }
+    }
+  } catch (serverErr) {
+    console.error('Verification network failure:', serverErr);
+    if (PublicKeyCredential.signalUnknownCredential) {
+      await PublicKeyCredential.signalUnknownCredential({
+        rpId, // RP ID must match the one defined on the server
+        credentialId: encodedResponse.id
+      });
+    }
+  }
+}
+```
+
+## Fallback Strategies
+
+### Passkey feature detection fallback
+
+Baseline status for the api.PublicKeyCredential.getClientCapabilities_static capability: Newly available. It's been Baseline since 2025-02-06.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), Firefox 135 (Feb 2025), and Safari 17.4 (Mar 2024).
+
+Always install 'webauthn-polyfills' and import it in the context.
+Consider as long as  `PublicKeyCredential` is supported, `PublicKeyCredential.getClientCapabilities` is also supported. 
+
+```js 
+import 'webauthn-polyfills';
+``` 
+
+### Signal API Synchronization Fallback
+
+Web authentication signal methods has limited availability.
+Supported by: Chrome 132 (Jan 2025), Edge 132 (Jan 2025), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.
+
+The WebAuthn Signal API (`webauthn-signals`) is a progressive optimization used to keep password managers in sync with the server credential state.
+*   **Fallback Experience**: Gated via `if (PublicKeyCredential.signalUnknownCredential)`. If unsupported, the background verification sync is bypassed gracefully without throwing browser exceptions.
+
+### Easy JSON Serialization Fallback
+
+Baseline status for the api.PublicKeyCredential.parseCreationOptionsFromJSON_static capability: Newly available. It's been Baseline since 2025-03-31.
+Supported by: Chrome 129 (Sep 2024), Edge 129 (Sep 2024), Firefox 119 (Oct 2023), and Safari 18.4 (Mar 2025).
+
+Always install 'webauthn-polyfills' and import it in the context.
+Consider as long as  `PublicKeyCredential` is supported, `PublicKeyCredential.parseCreationOptionsFromJSON` and `PublicKeyCredential.prototype.toJSON` are also supported. 
+
+```js 
+import 'webauthn-polyfills';
+``` 

package/.agents/skills/modern-web-guidance/guides/passkeys/passkey-management.md

@@ -0,0 +1,211 @@
+# Passkey Management Guide
+
+This guide details how to enable users to view, rename, and delete their registered passkeys while keeping saved credentials perfectly synchronized between the server and the user's password managers using the Signal API.
+
+## Server-Side Operations
+
+Your backend database layer and endpoints MUST support common CRUD actions for registered credentials. Decoupled from framework-specific libraries, the server exposes endpoints to:
+
+1.  **List all user credentials**: Fetch all `StoredPasskeyCredential` records matching the signed-in user's ID.
+2.  **Update credential names**: Accept a new custom string name for a specific credential ID and persist the update.
+3.  **Delete credentials**: Remove a specific credential ID from the database.
+
+```javascript
+// Node.js routing example for credential CRUD
+router.get('/api/credentials', checkUserAuthenticated, async (req, res) => {
+  const list = await db.findCredentialsByUserId(req.user.id);
+  return res.json(list);
+});
+
+router.put('/api/credential/:id', checkUserAuthenticated, async (req, res) => {
+  const { id } = req.params;
+  const { name } = req.body;
+  const cred = await db.findCredentialById(id);
+  if (!cred || cred.passkeyUserId !== req.user.id) {
+    return res.status(404).json({ error: 'Credential not found.' });
+  }
+  cred.name = name;
+  await db.saveCredential(cred);
+  return res.json(cred);
+});
+
+router.delete('/api/credential/:id', checkUserAuthenticated, async (req, res) => {
+  const { id } = req.params;
+  const cred = await db.findCredentialById(id);
+  if (!cred || cred.passkeyUserId !== req.user.id) {
+    return res.status(404).json({ error: 'Credential not found.' });
+  }
+  await db.deleteCredential(id);
+  return res.json({ success: true });
+});
+```
+
+## Client-Side Management UI
+
+Render a dedicated settings panel allowing users to easily audit and manage their registered authentication options:
+
+1.  **Display saved list**: Fetch list from your endpoint and render individual credential rows. If the response is empty, render a helpful empty-state message (e.g., "No passkeys found").
+2.  **Map AAGUID Metadata**: For each passkey, lookup its `aaguid` property against your local registry to render its provider details. See [Determine the passkey provider from AAGUID](#aaguid) section for more details.
+3.  **Per-Item UI Requirements**: Every row inside the list container MUST render:
+    *   **Provider Icon**: AAGUID-derived image or data URI.
+    *   **Provider/Custom Name**: AAGUID-derived name or user-renamed string.
+    *   **Registration Date**: The database-persisted raw epoch timestamp `registeredAt` formatted to a human-readable date for client display.
+    *   **Last Used Date**: The database-persisted raw epoch timestamp `lastUsedAt` formatted to a human-readable date (if present) for client display.
+    *   **Rename Button**: Triggers a rename text input modal.
+    *   **Delete Button**: Triggers deletion.
+4.  **Conditional "Create Passkey" Button**:
+    *  Offer a prominent "Create passkey" registration trigger button on the management page. Before rendering this UI element, the page MUST feature-detect capabilities using `PublicKeyCredential.getClientCapabilities()` to verify platform authenticator is supported. If passkeys are unsupported, hide this button and gracefully encourage standard MFA enrollments instead.
+    *  Allow registering a security key by omitting `authenticatorSelection.authenticatorAttachment` on `navigator.credentials.create()` call.
+
+## Signal API Synchronization
+
+The Signal API lets the application communicate credential states to password managers, keeping the user's synced vaults and your backend database in lockstep.
+
+*   **Parameter Encoding Rule**:
+    *  All `userId` and credential ID parameters passed to Signal API methods (`signalAllAcceptedCredentials`, `signalCurrentUserDetails`) MUST be **Base64URL-encoded strings**.
+*   **Initiating Page Load Sync**:
+    *  The application MUST invoke `signalAllAcceptedCredentials()` automatically in a `DOMContentLoaded` page load event listener.
+*   **Management Updates Sync**:
+    *  The application MUST invoke `signalAllAcceptedCredentials()` immediately within your delete credential click handler post-fetch.
+    *  The application MUST invoke `signalCurrentUserDetails()` immediately within your username or display name rename click handler post-fetch.
+
+```javascript
+// Client-side management synchronization ES module
+import { listFetch, renameFetch, deleteFetch } from './api.js';
+
+// Base64URL-encoded User ID string (illustration only)
+const base64UrlUserId = "M2YPl-KGnA8";
+
+async function syncAcceptedCredentials(currentCredentialsList) {
+  try {
+    const credentialIds = currentCredentialsList.map(c => c.id); // Map of Base64URL credential ID strings
+    
+    await PublicKeyCredential.signalAllAcceptedCredentials({
+      rpId, // RP ID must match the one defined on the server
+      userId: base64UrlUserId, // User ID Base64URL-encoded string
+      allAcceptedCredentialIds: credentialIds
+    });
+  } catch (e) {
+    console.error('SignalAllAcceptedCredentials sync failure:', e);
+  }
+}
+
+async function loadManagementPanel() {
+  const response = await listFetch();
+  const list = await response.json();
+  
+  renderUI(list);
+  // Sync on page load
+  await syncAcceptedCredentials(list);
+}
+
+async function performDelete(credentialId) {
+  const response = await deleteFetch(credentialId);
+  if (response.ok) {
+    const updatedResponse = await listFetch();
+    const updatedList = await updatedResponse.json();
+    
+    renderUI(updatedList);
+    // Sync after deletion
+    await syncAcceptedCredentials(updatedList);
+  }
+}
+
+async function performRename(rpId, userId, updatedName, updatedDisplayName) {
+  const response = await renameFetch({ name: updatedName, displayName: updatedDisplayName });
+  if (response.ok) {
+    try {
+      await PublicKeyCredential.signalCurrentUserDetails({
+        rpId, // RP ID must match the one defined on the server
+        userId, // Base64URL-encoded user ID
+        name: updatedName, // Updated username
+        displayName: updatedDisplayName // Updated display name
+      });
+    } catch (e) {
+      console.error('SignalCurrentUserDetails sync failure:', e);
+    }
+  }
+}
+```
+
+## Determine the passkey provider from AAGUID {: #aaguid }
+
+An AAGUID (Authenticator Attestation Globally Unique Identifier) is a 128-bit identifier that represents the model of the authenticator, not a specific instance. It is included in the authenticator data during passkey registration and can be used to determine which passkey provider (e.g. Google Password Manager, iCloud Keychain, 1Password) created a credential.
+
+AAGUID should only be used to help users with passkey management. It can be modified unless cryptographically attested, which platform passkeys currently don't support.
+
+### 1. AAGUID Registry
+
+A community-maintained JSON mapping of AAGUIDs to provider names and icons is available at:
+
+```
+https://raw.githubusercontent.com/passkeydeveloper/passkey-authenticator-aaguids/refs/heads/main/combined_aaguid.json
+```
+
+Each entry has the following schema:
+
+```json
+{
+  "<aaguid-uuid>": {
+    "name": "Provider Name",
+    "icon_light": "data:image/png;base64,...",
+    "icon_dark": "data:image/png;base64,..."
+  }
+}
+```
+
+### 2. Using AAGUID After Registration
+
+After verifying a registration response, read the `aaguid` from the registration result and look it up against the registry to populate the credential's `name` and `providerIcon`:
+
+Before looking up the AAGUID in the registry, check if it equals `'00000000-0000-0000-0000-000000000000'`. If so, skip the registry lookup and set `name` to a fallback (e.g. device name from user-agent, or "Unknown passkey provider") and `providerIcon` to `undefined`. Only look up the registry for non-zeroed AAGUIDs.
+
+```javascript
+import aaguids from './aaguids.json' with { type: 'json' };
+
+const { aaguid } = registrationInfo;
+if (aaguid === '00000000-0000-0000-0000-000000000000') {
+  // use the device name as the passkey provider based on
+  // the information derived from the user agent string,
+  // or just say "Unknown passkey provider"
+} else {
+  const provider = aaguids[aaguid];
+  const credential = {
+    // ...other fields
+    aaguid,
+    name: provider?.name || 'Unknown passkey provider',
+    providerIcon: provider?.icon_light,
+  };
+}
+```
+
+## Fallback Strategies
+
+### Passkey feature detection fallback
+
+Baseline status for the api.PublicKeyCredential.getClientCapabilities_static capability: Newly available. It's been Baseline since 2025-02-06.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), Firefox 135 (Feb 2025), and Safari 17.4 (Mar 2024).
+
+Always install 'webauthn-polyfills' and import it in the context.
+Consider as long as  `PublicKeyCredential` is supported, `PublicKeyCredential.getClientCapabilities` is also supported. 
+
+```js 
+import 'webauthn-polyfills';
+``` 
+
+### Signal API Synchronization Fallback
+
+Web authentication signal methods has limited availability.
+Supported by: Chrome 132 (Jan 2025), Edge 132 (Jan 2025), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.
+If the browser does not support `PublicKeyCredential.parseRequestOptionsFromJSON`, use the 'webauthn-polyfills': 
+  
+```html 
+<script type="module"> 
+  if (!PublicKeyCredential.parseRequestOptionsFromJSON) { 
+     await import('https://unpkg.com/webauthn-polyfills'); 
+   } 
+ </script> 
+ ``` 
+
+This will also add support for `PublicKeyCredential.prototype.toJSON`.

package/.agents/skills/modern-web-guidance/guides/passkeys/passkey-reauthentication.md

@@ -0,0 +1,128 @@
+# Passkey Reauthentication Guide
+
+This delta-focused guide details how to implement step-up authentication or re-verification for a signed-in user before they perform sensitive account changes (e.g. passwords updates, financial transfers).
+
+## Delta Flow Architecture
+
+Unlike regular authentication, passkey reauthentication constrains passkey dialog prompts strictly to the logged-in user's pre-registered credentials to prevent account-mixing or passkey spoofing during active sessions.
+
+## Server-Side
+
+### Options Generation Delta
+
+Create an endpoint that populates the allowed credentials parameters specifically for the active, known user:
+
+**Constrain Credentials**: Populate the `allowCredentials` options array with specific `PublicKeyCredentialDescriptor` records mapping all registered credential IDs for the signed-in user. Leaving this empty or omitting it regresses to discoverable credentials, violating session safety.
+
+```javascript
+// Node.js step-up options generation example
+router.post("/api/reauth/options", enforceActiveSession, async (req, res) => {
+  const userPasskeys = await db.findCredentialsByUserId(req.user.id);
+
+  const options = {
+    challenge: serverGeneratedBase64UrlChallenge, // Random challenge stored in user session
+    rpId: "example.com",
+    // Enforce allowance strictly limited to the user's credentials list
+    allowCredentials: userPasskeys.map((cred) => ({
+      type: "public-key",
+      id: cred.id,
+      transports: cred.transports, // Speeds up resolution by indicating platform transports
+    })),
+  };
+  return res.json(options);
+});
+```
+
+### Verification Endpoint Delta
+
+Verify the assertion returned by the client:
+
+**Verify Account Ownership**: The verification endpoint MUST explicitly verify that the resulting authenticated credential ID returned by the client resolves to a stored credential record whose associated user ID strictly matches the active signed-in user (`storedCredential.passkeyUserId === req.user.id`). If a valid passkey of a _different_ user is returned, authentication MUST be rejected immediately.
+
+## Client-Side Flow Deltas
+
+Applications choose from two reauthentication interfaces depending on the transaction UI:
+
+### A. Button Flow (No Input Fields)
+
+Trigger reauthentication when a user presses a "Verify Identity" or "Proceed with Transaction" button.
+
+```html
+<button id="reauth-btn" data-testid="reauth-button">Confirm Transaction</button>
+```
+
+```javascript
+let reauthAbortController = new AbortController();
+
+async function triggerButtonReauth() {
+  // Abort any background suggestion flows to avoid passkey prompt collisions
+  reauthAbortController.abort();
+  reauthAbortController = new AbortController();
+
+  const optionsResponse = await fetch("/api/reauth/options", {
+    method: "POST",
+  });
+  const optionsJSON = await optionsResponse.json();
+  const publicKey =
+    PublicKeyCredential.parseRequestOptionsFromJSON(optionsJSON);
+
+  try {
+    const credential = await navigator.credentials.get({
+      publicKey,
+      signal: reauthAbortController.signal,
+    });
+
+    if (credential) {
+      const encodedCredential = credential.toJSON();
+      const verifyResponse = await fetch("/api/reauth/verify", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(encodedCredential),
+      });
+
+      if (verifyResponse.ok) {
+        showTransactionSuccessUI();
+      } else if (verifyResponse.status === 404 && PublicKeyCredential.signalUnknownCredential) {
+        await PublicKeyCredential.signalUnknownCredential({
+          rpId, // RP ID must match the one defined on the server
+          credentialId: encodedCredential.id
+        });
+      }
+    }
+  } catch (err) {
+    if (err.name === "NotAllowedError") {
+      console.log("User cancelled reauthentication.");
+    }
+  }
+}
+
+document
+  .getElementById("reauth-btn")
+  .addEventListener("click", triggerButtonReauth);
+```
+
+## Fallback Strategies
+
+### Passkey feature detection fallback
+
+Baseline status for the api.PublicKeyCredential.getClientCapabilities_static capability: Newly available. It's been Baseline since 2025-02-06.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), Firefox 135 (Feb 2025), and Safari 17.4 (Mar 2024).
+
+Always install 'webauthn-polyfills' and import it in the context.
+Consider as long as  `PublicKeyCredential` is supported, `PublicKeyCredential.getClientCapabilities` is also supported. 
+
+```js 
+import 'webauthn-polyfills';
+``` 
+
+### Easy JSON Serialization Fallback
+
+Baseline status for the api.PublicKeyCredential.parseRequestOptionsFromJSON_static capability: Newly available. It's been Baseline since 2025-03-31.
+Supported by: Chrome 129 (Sep 2024), Edge 129 (Sep 2024), Firefox 119 (Oct 2023), and Safari 18.4 (Mar 2025).
+
+Always install 'webauthn-polyfills' and import it in the context.
+Consider as long as  `PublicKeyCredential` is supported, `PublicKeyCredential.parseRequestOptionsFromJSON` and `PublicKeyCredential.prototype.toJSON` are also supported. 
+
+```js 
+import 'webauthn-polyfills';
+``` 

package/.agents/skills/modern-web-guidance/guides/passkeys/passkey-registration.md

@@ -0,0 +1,181 @@
+# Passkey Registration Guide
+
+This guide details how to enable users to register a passkey for their account, providing a highly secure, phishing-resistant passwordless sign-in alternative.
+
+## Database Requirements
+
+To support passkey registrations, your database credential table must store the following fields:
+
+```typescript
+export interface StoredPasskeyCredential {
+  id: string; // Base64URL-encoded credential ID (unique lookup key)
+  passkeyUserId: string; // Associated application user ID
+  credentialPublicKey: string; // Base64URL-encoded public key used to verify assertion signatures
+  credentialType: "public-key";
+  credentialDeviceType: "singleDevice" | "multiDevice"; // Helps distinguish device-bound vs cloud-synced passkeys
+  credentialBackedUp: boolean; // Boolean backup state reported by the authenticator
+  aaguid: string; // Authenticator Attestation GUID
+  providerIcon?: string; // Provider icon derived from the AAGUID registry (dark or light theme URLs)
+  name: string; // Provider name derived from AAGUID registry
+  transports: string[]; // Array of transport names (e.g. 'internal', 'hybrid') necessary for exclusion options
+  lastUsedAt?: number; // Optional epoch timestamp of last sign-in
+  registeredAt: number; // Registration epoch timestamp
+  counter: number; // Authenticator sign-in signature counter used to prevent replay attacks
+}
+```
+
+## Server-Side
+
+### Options Generation
+
+Create an endpoint that generates WebAuthn creation parameters. Rely on a vetted library per category standards instead of hand-rolling cryptography.
+
+1.  **Use the predefined RP ID**: Use the predefined proper RP ID as a constant string.
+2.  **Create a secure Challenge**: Generate a high-entropy, cryptographically secure random buffer on the server, store it securely in the user's session, and encode it as Base64URL for options delivery.
+3.  **Avoid Duplicate Passkeys**: Map the user's existing pre-registered credential IDs to the `excludeCredentials` options array. This prevents the authenticator from registering duplicate credentials on the same passkey provider account.
+4.  **Enforce Discoverable Credentials**: Set `requireResidentKey: true` and `residentKey: "required"` in the `authenticatorSelection` options to request a discoverable credential, which is necessary for discoverable sign-ins.
+5.  **Configure User Verification**: Specify `userVerification: "preferred"` or `userVerification: "required"`. Many compliance use cases (e.g., finance, healthcare) require `'required'` to enforce user verification on creation.
+6.  **Determine Attachment Scope**:
+    - **Promotion Flow**: When proposing passkey creation right after standard password sign-ins or post-signup promotions, set `authenticatorAttachment: "platform"` to enforce platform authenticator and bypass external security key prompts.
+    - **Management Flow**: When called from a dedicated settings or security panel where external security keys are supported in addition to platform authenticator, omit the `authenticatorAttachment` property entirely.
+    - _Tip_: Accept a `promotion: boolean` request flag to conditionally handle both flows with a single endpoint.
+
+```javascript
+// Options generation example
+const options = {
+  challenge: serverGeneratedBase64UrlChallenge, // Cryptographically random challenge
+  rp: { id: "example.com", name: "Secure Application" },
+  user: {
+    id: userBase64UrlId, // Unique base64url string identifying the account
+    name: "user@example.com",
+    displayName: "Jane Doe",
+  },
+  pubKeyCredParams: [
+    {
+      type: "public-key",
+      alg: -7,
+    },
+    {
+      type: "public-key",
+      alg: -257,
+    },
+  ],
+  excludeCredentials: userExistingCredentials.map((cred) => ({
+    type: "public-key",
+    id: cred.id,
+    transports: cred.transports,
+  })),
+  authenticatorSelection: {
+    residentKey: "required",
+    requireResidentKey: true,
+    userVerification: "preferred",
+    ...(isPromotionFlow && { authenticatorAttachment: "platform" }),
+  },
+};
+```
+
+### Verification
+
+1.  **Challenge Verification**: Securely verify the challenge against the expected session bound challenge.
+2.  **Verify User Presence**:
+    - Ensure that the User Present (UP) flag returned in the parsed authenticator data is `true` to confirm physical user presence at the time of creation.
+3.  **Relaxing Verification for 'preferred'**:
+    - When the creation options specified `userVerification: "preferred"`, the server-side verification call MUST be configured with `requireUserVerification: false`. Otherwise, authenticators that register without user verification (e.g., screen locks disabled) will trigger spurious server verification failures.
+
+## Client-Side Logic
+
+1.  **Gate the UI on page load**:
+    - On page load, call `PublicKeyCredential.getClientCapabilities()` and **disable the "Create passkey" button** if `conditionalGet` or `passkeyPlatformAuthenticator` is not available.
+2.  **Invoke creation & Serialize**: Decode server options with `PublicKeyCredential.parseCreationOptionsFromJSON()` and pass the resulting configuration to `navigator.credentials.create()`.
+    - Call `credential.toJSON()` to encode the `AuthenticatorAttestationResponse` into a valid, JSON-serializable object before fetching the verification endpoint.
+3.  **Handle WebAuthn Exceptions**:
+    - `InvalidStateError`: A matching passkey already exists (matched by `excludeCredentials`).
+    - `NotAllowedError`: The user cancelled or timed out the authentication passkey dialog.
+    - `AbortError`: The operation has been aborted.
+    - `SecurityError`: Secure origins (HTTPS) or RP ID mismatch errors (configuration issues).
+4.  **Try/Catch Segregation for Signal API**:
+    - Wrap server verification `fetch()` call in a try/catch block. Call `signalUnknownCredential()` when the server verification fetch fails (any status `response.ok === false` or network throws).
+
+```javascript
+// optionsFetch and registerVerifyFetch are app-defined HTTP methods
+import { optionsFetch, registerVerifyFetch } from "./api.js";
+
+async function registerPasskey(isPromotion = false) {
+  // Verify passkey capability and conditional UI are available
+  const capabilities = await PublicKeyCredential.getClientCapabilities();
+  if (
+    !capabilities.passkeyPlatformAuthenticator ||
+    !capabilities.conditionalGet
+  ) {
+    // Hide "Create passkey" buttons and fall back to password flows instead
+    showStandardPasswordFallbackUI();
+    return;
+  }
+
+  const creationOptionsJSON = await optionsFetch({ promotion: isPromotion });
+  const publicKey =
+    PublicKeyCredential.parseCreationOptionsFromJSON(creationOptionsJSON);
+
+  let credential;
+  try {
+    // passkey prompt execution
+    credential = await navigator.credentials.create({ publicKey });
+  } catch (err) {
+    if (err.name === "InvalidStateError") {
+      console.log("A passkey already exists for this account.");
+      alert("A passkey already exists for this account.");
+    } else if (err.name === "SecurityError") {
+      console.error("Configuration RP ID or Secure Context error.");
+      alert("Configuration RP ID or Secure Context error.");
+    } else if (err.name === "NotAllowedError") {
+      console.log("User cancelled the passkey dialog.");
+    } else if (err.name === "AbortError") {
+      console.log("The creation operation has been aborted.");
+    }
+    return; // Safe API exit, do not signal unknown for standard WebAuthn cancels
+  }
+
+  // Server Verification phase (Segregated Try/Catch)
+  let encodedResponse = credential.toJSON();
+  try {
+    const response = await registerVerifyFetch(encodedResponse);
+    if (!response.ok) {
+      // Server verification failed to verify/authenticate the credential (orphaned)
+      await PublicKeyCredential.signalUnknownCredential({
+        rpId, // RP ID must match the one defined on the server
+        credentialId: encodedResponse.id, // Base64URL-encoded credential ID
+      });
+    }
+  } catch (serverErr) {
+    console.error("Server verification network failure:", serverErr);
+    await publickeycredential.signalunknowncredential({
+      rpId, // RP ID must match the one defined on the server
+      credentialid: encodedresponse.id, // base64url-encoded credential id
+    });
+  }
+}
+```
+
+## Fallback Strategies
+
+### Signal API Synchronization Fallback
+
+Web authentication signal methods has limited availability.
+Supported by: Chrome 132 (Jan 2025), Edge 132 (Jan 2025), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.
+
+The WebAuthn Signal API (`webauthn-signals`) is a progressive optimization used to keep password managers in sync with the server credential state.
+
+- **Fallback Experience**: If `PublicKeyCredential.signalUnknownCredential` is unsupported by the browser, the call MUST be bypassed safely via feature detection gating (`if (PublicKeyCredential.signalUnknownCredential)`), and the server-side verification simply logs the failure without triggering manager updates.
+
+### Easy JSON Serialization Fallback
+
+Baseline status for the api.PublicKeyCredential.parseCreationOptionsFromJSON_static capability: Newly available. It's been Baseline since 2025-03-31.
+Supported by: Chrome 129 (Sep 2024), Edge 129 (Sep 2024), Firefox 119 (Oct 2023), and Safari 18.4 (Mar 2025).
+
+Always install 'webauthn-polyfills' and import it in the context.
+Consider as long as  `PublicKeyCredential` is supported, `PublicKeyCredential.parseCreationOptionsFromJSON` and `PublicKeyCredential.prototype.toJSON` are also supported. 
+
+```js 
+import 'webauthn-polyfills';
+```