Server initiated passkey updates and deletions

Author: thobson

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Delete passkey now uses an exchangeable token to synchronize backend and frontend records. This process is similar to that used for passkey registration. The backend initiates the process, returning a token. The frontend uses this token to perform its client-side cleanup.
+
+- Update passkey now uses an exchangeable token to synchronize backend and frontend records. This process is similar to that used for passkey registration. The backend initiates the process, returning a token. The frontend uses this token to update the device passkeys.
+
+### Removed
+
+- Browser-initiated passkey updates and deletions are no longer possible
+
+### Changed
+
+- It is now only possible to update **all** passkeys for a given `userId`. Previous versions of `@passlock/browser` implied it was possible to update a specific passkey, however the WebAuthn specs don't actually permit this.
+
 ## [2.7.0] - 2026-06-12
 
 ### Added

examples/sveltekit/src/lib/client/passkeys.ts

@@ -16,15 +16,14 @@ import * as PasslockBrowser from '@passlock/browser';
 
 import {
 	DeletePasskeySuccess,
-	DeletePasskeyWarning,
 	DeleteUserPasskeysSuccess,
 	Error,
 	PasskeyStatusSuccess,
 	AuthorizedPasskeyAuthentication,
 	AuthorizedPasskeyRegistration,
 	UpdatePasskeysSuccess
 } from '$lib/shared/schemas';
-import { parse, variant } from 'valibot';
+import { parse } from 'valibot';
 import { resolve } from '$app/paths';
 import { fetchData } from './network';
 
@@ -209,38 +208,36 @@ export type UpdatePasskeysInput = {
  * - the user's device or password manager, which shows the username and
  *   display name during sign-in
  *
- * The server updates the first two; the browser then uses the credential list
- * returned by the server to request the local update.
+ * The server updates the first two and returns a short-lived token. The browser
+ * exchanges that token to request the local update.
  */
-export const updateUserPasskeys = async (input: UpdatePasskeysInput) => {
+export const updateUserPasskeys = async (
+	input: UpdatePasskeysInput,
+	config: PasslockClientConfig
+) => {
 	const ERROR_TAG = '@error/UpdatePasskeyError';
 	const { username, givenName, familyName } = input;
 	const displayName = `${givenName} ${familyName}`.trim();
 
-	// `PATCH /passkeys` updates the Passlock vault and the local SQLite record.
+	// `PATCH /passkeys` updates the Passlock vault and the local SQLite record,
+	// then returns a prepared token for browser-side signal instructions.
 	const serverResult = await fetchData({
 		url: resolve('/passkeys'),
 		method: 'PATCH',
 		body: { username, displayName },
-		on2xx: (jsonResponse) => {
-			const { credentials } = parse(UpdatePasskeysSuccess, jsonResponse);
-			return credentials.length === 0
-				? ({ _tag: ERROR_TAG, message: 'No passkeys found' } as const)
-				: ({ _tag: 'Credentials', credentials } as const);
-		},
+		on2xx: (jsonResponse) => parse(UpdatePasskeysSuccess, jsonResponse),
 		orElse: (jsonResponse) => {
 			const { message } = parse(Error, jsonResponse);
 			return { _tag: ERROR_TAG, message } as const;
 		}
 	});
 
-	// Only the credential payload contains enough information for the browser to
-	// request a local device update.
-	if (serverResult._tag !== 'Credentials') return serverResult;
+	if (serverResult._tag === ERROR_TAG) return serverResult;
 
-	// This step is purely local to the browser/device, so no tenancy config is
-	// required.
-	const clientResult = await PasslockBrowser.updatePasskeyUsernames(serverResult.credentials);
+	const clientResult = await PasslockBrowser.updatePasskeys(
+		{ updatePasskeysToken: serverResult.updatePasskeysToken },
+		config
+	);
 
 	if (clientResult.success) return { _tag: 'UpdatePasskeySuccess' } as const;
 
@@ -258,20 +255,17 @@ export type DeletePasskeyInput = {
  * best-effort browser-side part. The account should stop trusting the passkey
  * even if the browser cannot remove it from the local password manager.
  */
-export const deletePasskey = async (input: DeletePasskeyInput) => {
+export const deletePasskey = async (input: DeletePasskeyInput, config: PasslockClientConfig) => {
 	const ERROR_TAG = '@error/DeletePasskeyError';
 	const PAUSED_TAG = '@warning/PasskeyDeletePaused';
 
-	// The endpoint can return either a successful deletion payload or a warning
-	// that the server-side record was already gone.
-	const EndpointResponse = variant('_tag', [DeletePasskeySuccess, DeletePasskeyWarning]);
-
-	// `DELETE /passkeys/[id]` removes the server-side association first.
+	// `DELETE /passkeys/[id]` removes the server-side association first and
+	// returns a prepared token for browser-side cleanup.
 	const serverResult = await fetchData({
 		url: resolve(`/passkeys/${encodeURIComponent(input.passkeyId)}`),
 		method: 'DELETE',
 		body: {},
-		on2xx: (jsonResponse) => parse(EndpointResponse, jsonResponse),
+		on2xx: (jsonResponse) => parse(DeletePasskeySuccess, jsonResponse),
 		orElse: (jsonResponse) => {
 			const { message } = parse(Error, jsonResponse);
 			return { _tag: ERROR_TAG, message } as const;
@@ -281,14 +275,23 @@ export const deletePasskey = async (input: DeletePasskeyInput) => {
 	// If the server still trusts the credential, we must stop here.
 	if (serverResult._tag === '@error/DeletePasskeyError') return serverResult;
 
-	// The local device is already in the desired state from the server's point
-	// of view, so the caller can treat this as a warning rather than a failure.
-	if (serverResult._tag === '@warning/PasskeyNotFound') return serverResult;
-
 	// Local device deletion is best-effort and browser-dependent.
-	const clientResult = await PasslockBrowser.deletePasskey(serverResult.deleted);
+	const clientResult = await PasslockBrowser.deletePasskeys(
+		{ deletePasskeysToken: serverResult.deletePasskeysToken },
+		config
+	);
+
+	if (clientResult.success && clientResult.warnings.length === 0) {
+		return { _tag: 'DeleteSuccess' } as const;
+	}
 
-	if (clientResult.success) return { _tag: 'DeleteSuccess' } as const;
+	if (clientResult.success) {
+		const message =
+			'The passkey was removed from your account, but browser cleanup returned a warning. ' +
+			'Check your device password manager if the passkey still appears.';
+
+		return { _tag: PAUSED_TAG, message } as const;
+	}
 
 	if (clientResult.code === 'PASSKEY_DELETION_UNSUPPORTED') {
 		const message =
@@ -306,12 +309,11 @@ export const deletePasskey = async (input: DeletePasskeyInput) => {
 /**
  * Delete every passkey associated with the current account.
  *
- * `DELETE /passkeys` removes the trusted server-side records and returns the
- * deleted credentials for the current user. The browser then tries to remove
- * those credentials from the device. Browser limitations are reported as
- * warnings so account deletion can continue.
+ * `DELETE /passkeys` removes the trusted server-side records and returns a
+ * short-lived token. The browser exchanges that token to request local cleanup.
+ * Browser limitations are reported as warnings so account deletion can continue.
  */
-export const deleteAccountPasskeys = async () => {
+export const deleteAccountPasskeys = async (config: PasslockClientConfig) => {
 	const ERROR_TAG = '@error/DeletePasskeyError';
 	const PAUSED_TAG = '@warning/PasskeyDeletePaused';
 
@@ -327,13 +329,28 @@ export const deleteAccountPasskeys = async () => {
 	});
 
 	// If this fails, the account would still trust one or more passkeys.
-	if (serverResult._tag !== 'DeleteUserPasskeysSuccess') {
+	if (serverResult._tag === ERROR_TAG) {
 		return serverResult;
 	}
 
-	const clientResult = await PasslockBrowser.deleteUserPasskeys(serverResult.deleted);
+	const clientResult = await PasslockBrowser.deletePasskeys(
+		{ deletePasskeysToken: serverResult.deletePasskeysToken },
+		config
+	);
+
+	if (clientResult.success && clientResult.warnings.length === 0) {
+		return { _tag: 'DeleteSuccess' } as const;
+	}
 
-	if (clientResult.success) return { _tag: 'DeleteSuccess' } as const;
+	if (clientResult.success) {
+		return {
+			_tag: PAUSED_TAG,
+			message:
+				'Passkeys were removed from your account, but browser cleanup returned warnings. ' +
+				'Remove any remaining passkeys manually from your device password manager after ' +
+				'the account is deleted.'
+		} as const;
+	}
 
 	if (clientResult.code === 'PASSKEY_DELETION_UNSUPPORTED') {
 		return {

examples/sveltekit/src/lib/server/passkeys.ts

@@ -6,15 +6,15 @@ import * as PasslockServer from '@passlock/server';
  * Update the passkey username/display name in both trusted server-side stores:
  * the Passlock vault and this sample's local SQLite database.
  *
- * The browser still needs to perform a separate local-device update
- * afterwards.
+ * The browser still needs to exchange the returned token and perform a
+ * separate local-device update afterwards.
  */
-export const updatePasskeyUsernames = async (input: {
+export const updatePasskeys = async (input: {
 	userId: number;
 	username: string;
 	displayName?: string | undefined;
 }) => {
-	const vaultResult = await PasslockServer.updatePasskeyUsernames(
+	const vaultResult = await PasslockServer.updatePasskeys(
 		{
 			userId: String(input.userId),
 			username: input.username,

examples/sveltekit/src/lib/shared/schemas.ts

@@ -22,41 +22,37 @@ export const AuthorizedPasskeyAuthentication = v.object({
 	authenticationToken: v.string()
 });
 
-/**
- * Credential payload returned by the server when the browser should update the
- * username/display name shown for a passkey.
- */
-export const UpdatedCredential = v.object({
-	rpId: v.string(),
-	userId: v.string(),
-	username: v.string(),
-	displayName: v.string()
-});
-
-export const DeletedCredential = v.object({
-	credentialId: v.string(),
-	userId: v.string(),
-	rpId: v.string()
+export const PasskeyManagementWarning = v.object({
+	code: v.picklist([
+		'PASSKEY_NOT_FOUND',
+		'NO_PASSKEYS_FOUND',
+		'BROWSER_SIGNAL_UNSUPPORTED',
+		'BROWSER_SIGNAL_FAILED',
+		'EMPTY_SIGNAL_PAYLOAD'
+	]),
+	message: v.string(),
+	passkeyId: v.optional(v.string())
 });
 
 export const UpdatePasskeysSuccess = v.object({
-	_tag: v.literal('UpdatePasskeySuccess'),
-	credentials: v.pipe(v.array(UpdatedCredential), v.readonly())
-});
-
-export const DeletePasskeyWarning = v.object({
-	_tag: v.literal('@warning/PasskeyNotFound'),
-	message: v.string()
+	_tag: v.literal('PreparedPasskeyUpdate'),
+	updatePasskeysToken: v.string(),
+	expiresAt: v.number(),
+	warnings: v.pipe(v.array(PasskeyManagementWarning), v.readonly())
 });
 
 export const DeletePasskeySuccess = v.object({
-	_tag: v.literal('DeletePasskeySuccess'),
-	deleted: DeletedCredential
+	_tag: v.literal('PreparedPasskeyDeletion'),
+	deletePasskeysToken: v.string(),
+	expiresAt: v.number(),
+	warnings: v.pipe(v.array(PasskeyManagementWarning), v.readonly())
 });
 
 export const DeleteUserPasskeysSuccess = v.object({
-	_tag: v.literal('DeleteUserPasskeysSuccess'),
-	deleted: v.pipe(v.array(DeletedCredential), v.readonly())
+	_tag: v.literal('PreparedPasskeyDeletion'),
+	deletePasskeysToken: v.string(),
+	expiresAt: v.number(),
+	warnings: v.pipe(v.array(PasskeyManagementWarning), v.readonly())
 });
 
 export const PasskeyStatusSuccess = v.object({

examples/sveltekit/src/reset.ts

@@ -13,11 +13,18 @@ const findAllPasskeys = async () => {
 };
 
 const deletePasskeys = async (passkeyIds: Array<string>) => {
-	for (const passkeyId of passkeyIds) {
-		const result = await PasslockServer.deletePasskey({ passkeyId }, getPasslockConfig());
-		if (!result.success) {
-			log.warn('Warning: passkey no longer exists in Passlock vault');
+	if (passkeyIds.length === 0) return;
+
+	const result = await PasslockServer.deletePasskeys({ passkeyIds }, getPasslockConfig());
+	if (!result.success) {
+		log.warn('Warning: unable to delete passkeys from Passlock vault');
+	} else {
+		for (const warning of result.warnings) {
+			log.warn(warning.message);
 		}
+	}
+
+	for (const passkeyId of passkeyIds) {
 		await db.delete(passkeysTable).where(eq(passkeysTable.passkeyId, passkeyId));
 		console.log(`Deleted passkey ${passkeyId}`);
 	}

examples/sveltekit/src/routes/account/+page.svelte

@@ -40,11 +40,17 @@
 		syncingUpdatedEmailPasskeys = true;
 		clearFormErrors(accountEmailErrors);
 
-		const result = await updateUserPasskeys({
-			username: data.currentEmail,
-			givenName: data.user?.givenName,
-			familyName: data.user?.familyName
-		});
+		const result = await updateUserPasskeys(
+			{
+				username: data.currentEmail,
+				givenName: data.user?.givenName,
+				familyName: data.user?.familyName
+			},
+			{
+				tenancyId: data.tenancyId,
+				endpoint: data.endpoint
+			}
+		);
 
 		if (result._tag === '@error/UpdatePasskeyError') {
 			setFormError(
@@ -121,11 +127,17 @@
 
 			// Once the server update succeeds, ask the browser to refresh the
 			// locally stored display name as well.
-			const result = await updateUserPasskeys({
-				username: data.currentEmail,
-				givenName: form.data.givenName,
-				familyName: form.data.familyName
-			});
+			const result = await updateUserPasskeys(
+				{
+					username: data.currentEmail,
+					givenName: form.data.givenName,
+					familyName: form.data.familyName
+				},
+				{
+					tenancyId: data.tenancyId,
+					endpoint: data.endpoint
+				}
+			);
 
 			if (result._tag === '@error/UpdatePasskeyError') {
 				setFormError(profileErrors, result.message);

examples/sveltekit/src/routes/account/delete/+page.svelte

@@ -55,7 +55,7 @@
 
 			// Clear trusted passkeys before the account record itself is deleted.
 			deletingPasskeys = true;
-			const result = await deleteAccountPasskeys();
+			const result = await deleteAccountPasskeys(config);
 			deletingPasskeys = false;
 
 			if (result._tag === '@error/DeletePasskeyError') {

examples/sveltekit/src/routes/passkeys/+page.svelte

@@ -43,18 +43,15 @@
 
 		// Deletion is split across server-side trust removal and best-effort
 		// browser/device cleanup.
-		const result = await deletePasskey({ passkeyId });
+		const result = await deletePasskey({ passkeyId }, data);
 
-		if (
-			result._tag === '@error/DeletePasskeyError' ||
-			result._tag === '@warning/PasskeyDeletePaused'
-		) {
+		if (result._tag === '@error/DeletePasskeyError') {
 			deletingPasskeyId = null;
 			error = result.message;
 			return;
 		}
 
-		if (result._tag === '@warning/PasskeyNotFound') {
+		if (result._tag === '@warning/PasskeyDeletePaused') {
 			warning = result.message;
 		} else {
 			info = 'Passkey deleted from your account';
@@ -90,7 +87,7 @@
 			{/if}
 
 			{#if warning}
-				<p class="mt-4 text-sm text-warning">{info}</p>
+				<p class="mt-4 text-sm text-warning">{warning}</p>
 			{/if}
 
 			{#if error}