@synqauth/plugin-passkey 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aerosol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @synqauth/plugin-passkey
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Synq plugin for passkeys from your own UI.
+
+Synq is customer identity for businesses: an OpenID Connect issuer for each of your brands, with Solana wallet, social, email and passkey sign-in. The documentation is at [docs.synq.build](https://docs.synq.build).
+
+This package is at 0.x and hasn't been published yet: its API can change in any release until Synq's first customer depends on it.
+
+## Usage
+
+Passkeys from your own UI, with every ceremony at your brand's Synq issuer, which verifies them. Nothing is verified on your server.
+
+```tsx
+import { passkeyPlugin } from '@synqauth/plugin-passkey'
+import { SynqProvider, usePlugin } from '@synqauth/react'
+
+const passkey = passkeyPlugin()
+
+// <SynqProvider plugins={[passkey]}> ... then, in a component:
+const { signIn, signInUrl, addUrl, list, remove } = usePlugin(passkey)
+
+const { data, error } = await signIn({ returnTo: '/account' })
+if (data) location.assign(data.signedIn ? data.returnTo : data.url)
+```
+
+`signIn()` asks for the passkey right on your page when the app has own-UI sign-in on and the browser can use the brand's passkeys there. Otherwise it answers the URL of the hosted page's passkey step, the same URL `signInUrl()` gives.
+
+`list()` and `remove(id)` go through your `@synqauth/nextjs` route mount's account API and answer `{ data, error }`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+import { AccountComponents, SynqError } from "@synqauth/js";
+//#region src/index.d.ts
+/** The plugin's id: its actions are under it in `usePlugin` and the mount's plugin list. */
+export declare const PASSKEY_PLUGIN_ID = "passkey";
+/** A passkey of the signed-in person's, as the account API lists it. */
+export type Passkey = AccountComponents['schemas']['Passkey'];
+/** A call's outcome: its data, or the `SynqError` it failed with. */
+export type PasskeyResult<T> = {
+  readonly data: T;
+  readonly error: null;
+} | {
+  readonly data: null;
+  readonly error: SynqError;
+};
+/** Calls the app's route mount, from its own page: what @synqauth/react and @synqauth/nextjs/client hand a plugin. */
+export type MountRequest = (path: string, init?: RequestInit) => Promise<Response>;
+/** How `signIn()` went: signed in on the page, or the hosted page to go to. */
+export type PasskeySignIn =
+/** Signed in: go to `returnTo` (or refresh the page's session). */
+{
+  readonly signedIn: true;
+  readonly returnTo: string;
+} |
+/** Go to `url`: the brand's page at its passkey step, which takes them in this browser. */
+{
+  readonly signedIn: false;
+  readonly url: string;
+};
+/** What the passkey plugin does from the page: where to send the person, and their passkeys. */
+export interface PasskeyActions {
+  /**
+   * Signs in with a passkey on the app's own page where the app has
+   * own-UI sign-in on and the browser takes the issuer's passkeys here;
+   * anywhere else, answers the hosted page's passkey step to go to. A
+   * prompt the person closed is the error `passkey_cancelled`; a passkey
+   * Synq didn't take is its problem (`passkey_unknown`, `passkey_failed`…).
+   */
+  signIn: (options?: {
+    returnTo?: string;
+    loginHint?: string;
+  }) => Promise<PasskeyResult<PasskeySignIn>>;
+  /** Where to send someone to sign in with a passkey: the brand's page, at its passkey step. */
+  signInUrl: (options?: {
+    returnTo?: string;
+    loginHint?: string;
+  }) => string;
+  /**
+   * Where to send the signed-in person to add a passkey: a fresh sign-in,
+   * then the brand's page offers a new passkey (`synq_intent=add-passkey`).
+   */
+  addUrl: (options?: {
+    returnTo?: string;
+  }) => string;
+  /** Their passkeys. */
+  list: () => Promise<PasskeyResult<readonly Passkey[]>>;
+  /** Removes one; a passkey that is their last way to sign in can't go (`last_sign_in_method`). */
+  remove: (id: string) => Promise<PasskeyResult<null>>;
+}
+/** The passkey plugin, in `SynqClientPlugin`'s shape: for `<SynqProvider plugins>` or `@synqauth/nextjs/client`. */
+export interface PasskeyPlugin {
+  readonly id: typeof PASSKEY_PLUGIN_ID;
+  actions: (request: MountRequest) => PasskeyActions;
+}
+/** What `passkeyPlugin()` takes. */
+export interface PasskeyPluginOptions {
+  /** The route mount's path, as the app's `synqAuth()` has it: `/api/auth` by default. */
+  basePath?: string;
+}
+/** The passkey plugin: sign-in and adding a passkey at the brand's issuer, and the person's passkeys through the route mount. */
+export declare function passkeyPlugin(options?: PasskeyPluginOptions): PasskeyPlugin;
+/** Calls the mount and reads its JSON; a problem it answers, or no answer, is the result's `error`. */
+export declare function call<T>(request: MountRequest, path: string, init?: RequestInit): Promise<PasskeyResult<T>>;
+//#endregion

package/dist/index.js

@@ -0,0 +1,157 @@
+import { SynqError, problemError } from "@synqauth/js";
+//#region src/index.ts
+/** The plugin's id: its actions are under it in `usePlugin` and the mount's plugin list. */
+const PASSKEY_PLUGIN_ID = "passkey";
+/** The passkey plugin: sign-in and adding a passkey at the brand's issuer, and the person's passkeys through the route mount. */
+function passkeyPlugin(options = {}) {
+	const base = `/${(options.basePath ?? "/api/auth").replace(/^\/+|\/+$/g, "")}`;
+	const signInPath = (params) => {
+		const query = new URLSearchParams();
+		for (const [name, value] of Object.entries(params)) if (value) query.set(name, value);
+		return `${base}/sign-in?${query.toString()}`;
+	};
+	const signInUrl = ({ returnTo, loginHint } = {}) => signInPath({
+		method: "passkey",
+		returnTo,
+		login_hint: loginHint
+	});
+	return {
+		id: PASSKEY_PLUGIN_ID,
+		actions: (request) => ({
+			signIn: (signInOptions = {}) => signInOnPage(request, signInOptions, signInUrl),
+			signInUrl,
+			addUrl: ({ returnTo } = {}) => signInPath({
+				intent: "add-passkey",
+				returnTo
+			}),
+			list: async () => {
+				const result = await call(request, "account/v1/passkeys");
+				if (result.error) return {
+					data: null,
+					error: result.error
+				};
+				return {
+					data: result.data.data,
+					error: null
+				};
+			},
+			remove: (id) => {
+				if (!id || /^\.+$/.test(id)) return Promise.resolve({
+					data: null,
+					error: new SynqError("invalid_options", "A passkey id is needed")
+				});
+				return call(request, `account/v1/passkeys/${encodeURIComponent(id)}`, {
+					method: "DELETE",
+					headers: { "idempotency-key": crypto.randomUUID() }
+				});
+			}
+		})
+	};
+}
+/** A passkey on the page through the mount's `sign-in/flow`, or the hosted page's passkey step. */
+async function signInOnPage(request, options, signInUrl) {
+	const hosted = () => ({
+		data: {
+			signedIn: false,
+			url: signInUrl(options)
+		},
+		error: null
+	});
+	const browser = globalThis;
+	const statics = browser.PublicKeyCredential;
+	const credentials = browser.navigator?.credentials;
+	if (!statics?.getClientCapabilities || !statics.parseRequestOptionsFromJSON || !credentials) return hosted();
+	try {
+		if ((await statics.getClientCapabilities()).relatedOrigins !== true) return hosted();
+	} catch {
+		return hosted();
+	}
+	const step = (body) => call(request, "sign-in/flow", {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({
+			...body,
+			...options.returnTo ? { returnTo: options.returnTo } : {}
+		})
+	});
+	const asked = await step({ step: "passkey-options" });
+	if (asked.error) return asked.error.status === 404 ? hosted() : {
+		data: null,
+		error: asked.error
+	};
+	if (asked.data.status !== "passkey") return answered(asked.data, hosted);
+	let credential;
+	try {
+		credential = await credentials.get({ publicKey: statics.parseRequestOptionsFromJSON(asked.data.passkey.options) });
+	} catch {
+		credential = null;
+	}
+	if (!credential) return {
+		data: null,
+		error: new SynqError("passkey_cancelled", "No passkey was used")
+	};
+	const taken = await step({
+		step: "passkey",
+		credential: credential.toJSON()
+	});
+	if (taken.error) return {
+		data: null,
+		error: taken.error
+	};
+	return answered(taken.data, hosted);
+}
+/** What the mount answered, as `signIn()` answers it. */
+function answered(answer, hosted) {
+	switch (answer.status) {
+		case "signed-in": return {
+			data: {
+				signedIn: true,
+				returnTo: answer.returnTo
+			},
+			error: null
+		};
+		case "passkey":
+		case "retry":
+		case "refused":
+		case "expired": {
+			const code = answer.status === "passkey" ? answer.problem ?? "passkey_failed" : answer.status === "retry" ? answer.problem : answer.status === "refused" ? answer.reason : "invalid_session";
+			return {
+				data: null,
+				error: new SynqError(code, answer.message ?? code, { ...answer.status === "retry" && answer.retryAfter !== void 0 ? { retryAfter: answer.retryAfter } : {} })
+			};
+		}
+		default: return hosted();
+	}
+}
+/** Calls the mount and reads its JSON; a problem it answers, or no answer, is the result's `error`. */
+async function call(request, path, init) {
+	let response;
+	try {
+		response = await request(path, init);
+	} catch (error) {
+		return {
+			data: null,
+			error: new SynqError("network_error", `The app couldn't be reached: ${String(error)}`, { cause: error })
+		};
+	}
+	const text = await response.text();
+	let json;
+	try {
+		json = text ? JSON.parse(text) : void 0;
+	} catch {
+		json = void 0;
+	}
+	if (!response.ok) {
+		const problem = json !== null && typeof json === "object" ? json : {};
+		return {
+			data: null,
+			error: problemError(response.status, problem)
+		};
+	}
+	return {
+		data: json ?? null,
+		error: null
+	};
+}
+//#endregion
+export { PASSKEY_PLUGIN_ID, call, passkeyPlugin };

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@synqauth/plugin-passkey",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "A Synq plugin for passkeys from your own UI.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aerosol-build/synq.git",
+    "directory": "packages/plugin-passkey"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@synqauth/js": "0.2.0"
+  },
+  "devDependencies": {
+    "vitest": "5.0.2"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc",
+    "test": "vitest run"
+  }
 }