@synqauth/plugin-passkey 0.0.0-stage → 0.0.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,28 @@
-# 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 { signInUrl, addUrl, list, remove } = usePlugin(passkey)
+location.assign(signInUrl({ returnTo: '/account' }))
+```
+
+`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,50 @@
+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>;
+/** What the passkey plugin does from the page: where to send the person, and their passkeys. */
+export interface PasskeyActions {
+  /** 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,80 @@
+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()}`;
+	};
+	return {
+		id: PASSKEY_PLUGIN_ID,
+		actions: (request) => ({
+			signInUrl: ({ returnTo, loginHint } = {}) => signInPath({
+				method: "passkey",
+				returnTo,
+				login_hint: loginHint
+			}),
+			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() }
+				});
+			}
+		})
+	};
+}
+/** 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.0.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.0.0"
+  },
+  "devDependencies": {
+    "vitest": "5.0.2"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc",
+    "test": "vitest run"
+  }
 }