@synqauth/plugin-siws 0.2.0 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@ A Synq plugin for Sign In With Solana 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.
+This package is at 0.x, so a minor release can change its API: see its CHANGELOG.md.
 
 ## Usage
 
@@ -26,9 +26,14 @@ import { useSolanaWallets } from '@synqauth/solana/react'
 
 const siws = siwsPlugin().actions(mountRequest())
 const wallets = useSolanaWallets()
+// When the sign-in comes into view: the issuer's request, before the tap.
+useEffect(() => void siws.prepare(), [])
+// On the tap: straight to the wallet.
 const { error } = await siws.signIn(wallets[0], { returnTo: '/account' })
 ```
 
+`prepare()` asks for the request the wallet signs before the tap and keeps it fresh, so the tap reaches the wallet with nothing fetched first: Safari blocks a wallet's prompt that opens after a network wait.
+
 The wallet signs the issuer's own request on your page, and your server pushes the signature to Synq, which checks it. Your server verifies nothing.
 
 ## License

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { SynqError } from "@synqauth/js";
-import { Wallet, WalletAccount } from "@synqauth/solana";
+import { SignInRequest, Wallet, WalletAccount } from "@synqauth/solana";
 //#region src/index.d.ts
 /** The plugin's id: its server half's routes are under it, and its actions under it in `usePlugin`. */
 export declare const SIWS_PLUGIN_ID = "siws";
@@ -15,20 +15,56 @@ export type SiwsResult<T> = {
 export type MountRequest = (path: string, init?: RequestInit) => Promise<Response>;
 /** What `signIn` takes besides the wallet. */
 export interface SiwsSignInOptions {
-  /** Where on the app the person lands afterwards. */
+  /**
+   * Where on the app the person lands afterwards: the browser goes there
+   * once signed in. Left out, a sign-in that finishes in place stays on the
+   * page.
+   */
   returnTo?: string;
   /** The account to sign with; the wallet's choice when left out. */
   account?: WalletAccount;
+  /**
+   * The issuer's request to sign, from `prepare()`. Left out, the one
+   * `prepare()` keeps is used when it is fresh. Either way, a fresh request
+   * means nothing is fetched between the tap and the wallet; a missing or
+   * stale one is asked for first, and the wallet is asked once.
+   */
+  request?: SignInRequest | null;
+}
+/** How a wallet's sign-in went. */
+export interface SiwsSignedIn {
+  /**
+   * True when it finished in place, with no page (AERO-2681): the session
+   * is there, and the page refreshes what it shows of it
+   * (`useSession().refresh()`, `router.refresh()`). False when the browser
+   * is on its way through Synq, the redirect way.
+   */
+  readonly inPlace: boolean;
+  /** Where the sign-in was to land, on the app. */
+  readonly returnTo: string | null;
 }
 /** The browser half's actions. */
 export interface SiwsActions {
   /**
    * Signs in with `wallet`: the issuer's request, the wallet's signature,
-   * then off to Synq and back to `returnTo`. Answers `{ data, error }`
-   * instead of navigating when something fails: `wallet_rejected` when the
-   * person declines.
+   * then the session, in place where the app can sign in on its own
+   * screens, else through Synq and back to `returnTo`. Answers
+   * `{ data, error }` and never navigates when something fails:
+   * `wallet_rejected` when the person declines, `wallet_failed` or
+   * `wallet_expired` when the signature didn't count, `access_denied` when
+   * this person can't sign in here, `redirect_to_web` (its `cause` says
+   * why) when only the hosted page can go on: a token gate, a step-up.
+   */
+  signIn: (wallet: Wallet, options?: SiwsSignInOptions) => Promise<SiwsResult<SiwsSignedIn>>;
+  /**
+   * Asks the issuer for the request `signIn` signs, before the tap, and
+   * answers it (AERO-2679): Safari lets a wallet's popup open only while the
+   * tap's user activation lasts, and drops it after a short network wait,
+   * so call this when the sign-in comes into view. The request is kept
+   * fresh, asked for again about a minute before it expires, until a
+   * sign-in goes through or ten minutes pass with no other `prepare()`.
    */
-  signIn: (wallet: Wallet, options?: SiwsSignInOptions) => Promise<SiwsResult<null>>;
+  prepare: () => Promise<SiwsResult<SignInRequest>>;
 }
 /** The SIWS plugin's browser half, in `SynqClientPlugin`'s shape: for `<SynqProvider plugins>` or `@synqauth/nextjs/client`. */
 export interface SiwsPlugin {
@@ -42,6 +78,8 @@ export interface SiwsPluginOptions {
   /** The `fetch` the page asks the issuer with: the global one by default. */
   fetch?: typeof fetch;
 }
+/** How long `prepare()` keeps a request fresh with no sign-in and no other `prepare()`. */
+export declare const PREPARED_FOR_MS: number;
 /** The SIWS plugin's browser half: a wallet's sign-in from the app's own page, through the route mount. */
 export declare function siwsPlugin(options?: SiwsPluginOptions): SiwsPlugin;
 //#endregion

package/dist/index.js

@@ -1,5 +1,5 @@
 import { SynqError, problemError } from "@synqauth/js";
-import { encodeSiws, requestSignIn, signWithWallet } from "@synqauth/solana";
+import { encodeSiws, isFreshRequest, prepareSignIn, requestSignIn, signWithWallet } from "@synqauth/solana";
 //#region src/index.ts
 /** The plugin's id: its server half's routes are under it, and its actions under it in `usePlugin`. */
 const SIWS_PLUGIN_ID = "siws";
@@ -14,43 +14,156 @@ async function mountJson(request, path, init) {
 	if (!response.ok) throw problemError(response.status, json !== null && typeof json === "object" ? json : {});
 	return json;
 }
+/** The issuer and app to ask for a request: the mount's own route, else an older mount's server half. */
+async function requestTarget(request) {
+	try {
+		return await mountJson(request, "sign-in/wallet");
+	} catch (error) {
+		if (!(error instanceof SynqError) || error.status !== 404) throw error;
+		return mountJson(request, `${SIWS_PLUGIN_ID}/config`);
+	}
+}
+/**
+* Why only the hosted page goes on, where the wallet's step never ran and
+* its signature is unspent: the redirect way takes the same one.
+*/
+const NOT_RUN = /* @__PURE__ */ new Set(["own_ui_off", "paused"]);
+/**
+* Whether `sign-in/flow` failed where the wallet's step provably never
+* reached the issuer, so the signature is unspent and the redirect way can
+* take it: a mount with no such route (404), an older mount that refused
+* the wallet step before asking anything (400 `invalid_request`), a mount
+* that can't sign in on the app's own screens (`invalid_options`: no client
+* secret), or an issuer that refused the app before any method ran
+* (`unauthorized_client`: not a confidential first-party web app). Anything
+* else, the issuer may have spent the signature: answered, never navigated.
+*/
+function neverRan(error) {
+	if (error.status === 404) return true;
+	if (error.status === 400 && error.code === "invalid_request") return true;
+	return error.code === "invalid_options" || error.code === "unauthorized_client";
+}
+/** How long `prepare()` keeps a request fresh with no sign-in and no other `prepare()`. */
+const PREPARED_FOR_MS = 6e5;
+/** Any failure as a `SynqError`. */
+function asSynqError(error) {
+	return error instanceof SynqError ? error : new SynqError("network_error", String(error), { cause: error });
+}
 /** The SIWS plugin's browser half: a wallet's sign-in from the app's own page, through the route mount. */
 function siwsPlugin(options = {}) {
 	const navigate = options.navigate ?? ((url) => {
 		globalThis.location?.assign(url);
 	});
+	let mount = null;
+	const prepared = prepareSignIn(async () => {
+		if (!mount) throw new SynqError("invalid_options", "The SIWS plugin has no route mount yet");
+		const { issuer, clientId } = await requestTarget(mount);
+		return requestSignIn({
+			issuer,
+			clientId,
+			fetch: options.fetch
+		});
+	});
+	let release = null;
+	let letGo;
+	const stopKeeping = () => {
+		clearTimeout(letGo);
+		release?.();
+		release = null;
+	};
 	return {
 		id: SIWS_PLUGIN_ID,
-		actions: (request) => ({ signIn: async (wallet, signInOptions = {}) => {
-			try {
-				const { issuer, clientId } = await mountJson(request, `${SIWS_PLUGIN_ID}/config`);
-				const signInRequest = await requestSignIn({
-					issuer,
-					clientId,
-					fetch: options.fetch
-				});
-				const signed = await signWithWallet(wallet, signInRequest, signInOptions.account);
-				const { redirect } = await mountJson(request, "sign-in", {
-					method: "POST",
-					headers: { "content-type": "application/json" },
-					body: JSON.stringify({
-						siws: encodeSiws(signed),
-						returnTo: signInOptions.returnTo
-					})
-				});
-				navigate(redirect);
-				return {
-					data: null,
-					error: null
-				};
-			} catch (error) {
-				return {
-					data: null,
-					error: error instanceof SynqError ? error : new SynqError("network_error", String(error), { cause: error })
+		actions: (request) => ({
+			prepare: async () => {
+				mount = request;
+				release ??= prepared.hold();
+				clearTimeout(letGo);
+				letGo = setTimeout(stopKeeping, PREPARED_FOR_MS);
+				try {
+					return {
+						data: await prepared.ready(),
+						error: null
+					};
+				} catch (error) {
+					return {
+						data: null,
+						error: asSynqError(error)
+					};
+				}
+			},
+			signIn: async (wallet, signInOptions = {}) => {
+				mount = request;
+				const { returnTo } = signInOptions;
+				/** The redirect way: pushed to Synq by the mount, the browser following. */
+				const redirectWay = async (siws) => {
+					const { redirect } = await mountJson(request, "sign-in", {
+						method: "POST",
+						headers: { "content-type": "application/json" },
+						body: JSON.stringify({
+							siws,
+							returnTo
+						})
+					});
+					stopKeeping();
+					navigate(redirect);
+					return {
+						data: {
+							inPlace: false,
+							returnTo: returnTo ?? null
+						},
+						error: null
+					};
 				};
+				try {
+					const passed = signInOptions.request;
+					const signInRequest = passed && passed === prepared.peek() ? prepared.take() ?? passed : isFreshRequest(passed) ? passed : prepared.take() ?? await prepared.next();
+					const signed = await signWithWallet(wallet, signInRequest, signInOptions.account);
+					const siws = encodeSiws(signed);
+					let answer;
+					try {
+						answer = await mountJson(request, "sign-in/flow", {
+							method: "POST",
+							headers: { "content-type": "application/json" },
+							body: JSON.stringify({
+								step: "wallet",
+								siws,
+								returnTo
+							})
+						});
+					} catch (error) {
+						if (error instanceof SynqError && neverRan(error)) return await redirectWay(siws);
+						throw error;
+					}
+					switch (answer.status) {
+						case "signed-in":
+							stopKeeping();
+							if (returnTo) navigate(answer.returnTo);
+							return {
+								data: {
+									inPlace: true,
+									returnTo: answer.returnTo
+								},
+								error: null
+							};
+						case "hosted":
+							if (NOT_RUN.has(answer.hosted.reason)) return await redirectWay(siws);
+							throw new SynqError("redirect_to_web", "Only the hosted page can go on with this sign-in", { cause: answer.hosted });
+						case "retry": throw new SynqError(answer.problem, answer.message, {
+							description: answer.message,
+							...answer.retryAfter === void 0 ? {} : { retryAfter: answer.retryAfter }
+						});
+						case "refused": throw new SynqError("access_denied", answer.message, { cause: { reason: answer.reason } });
+						case "expired": throw new SynqError("invalid_session", answer.message);
+					}
+				} catch (error) {
+					return {
+						data: null,
+						error: asSynqError(error)
+					};
+				}
 			}
-		} })
+		})
 	};
 }
 //#endregion
-export { SIWS_PLUGIN_ID, siwsPlugin };
+export { PREPARED_FOR_MS, SIWS_PLUGIN_ID, siwsPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synqauth/plugin-siws",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A Synq plugin for Sign In With Solana from your own UI.",
   "license": "MIT",
   "repository": {
@@ -31,8 +31,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@synqauth/js": "0.2.0",
-    "@synqauth/solana": "0.2.0"
+    "@synqauth/js": "0.3.0",
+    "@synqauth/solana": "0.3.0"
   },
   "devDependencies": {
     "vitest": "5.0.2"