@voltro/plugin-auth 0.86.0 → 0.87.0

package/dist/native/guestStorage.js

@@ -0,0 +1,41 @@
+import { GuestClientError as e } from "../guestClient.js";
+//#region src/native/guestStorage.ts
+var t = /* @__PURE__ */ new Set([
+	"keychain",
+	"keystore",
+	"credential-manager",
+	"stronghold"
+]), n = () => new e("storage_unavailable"), r = (r) => {
+	let i;
+	try {
+		if (!r.namespace.trim() || !t.has(r.store.kind) || typeof r.exclusive != "function" || typeof r.store.get != "function" || typeof r.store.set != "function" || typeof r.store.delete != "function") throw n();
+		i = "voltro:guest:" + encodeURIComponent(r.namespace);
+	} catch {
+		throw n();
+	}
+	let a = async (e) => {
+		try {
+			return await e();
+		} catch {
+			throw n();
+		}
+	};
+	return {
+		exclusive: async (t) => {
+			try {
+				return await r.exclusive(i, t);
+			} catch (t) {
+				throw t instanceof e ? t : n();
+			}
+		},
+		read: () => a(async () => {
+			let e = await r.store.get(i);
+			if (e !== null && typeof e != "string") throw n();
+			return e;
+		}),
+		write: (e) => a(() => r.store.set(i, e)),
+		remove: () => a(() => r.store.delete(i))
+	};
+};
+//#endregion
+export { r as nativeGuestStore };

package/dist/native.d.ts

@@ -1,4 +1,5 @@
 import { Subject } from '@voltro/protocol';
+import { SubjectIdentity } from '@voltro/protocol';
 
 /**
  * Mint the verifier + state and build the authorize URL. Nothing is sent yet;
@@ -6,6 +7,40 @@ import { Subject } from '@voltro/protocol';
  */
 export declare const beginNativeLogin: (options: NativeLoginOptions) => Promise<NativeLoginHandoff>;
 
+/** Serializes operations in one client. A rejected existing credential never
+ * creates a replacement identity. Storage failures never enable memory fallback. */
+export declare const createGuestClient: (options: GuestClientOptions) => {
+    connect: () => Promise<GuestClientSession>;
+    /** Prepare without replacing the active proof, persist both proofs, then
+     * commit. A later connect recovers the same identity after a lost response. */
+    rotate: () => Promise<GuestClientSession>;
+    /** Revoke on the server first. Keep the durable proof on transport failure
+     * so the caller can retry; erase locally only after confirmed revocation. */
+    revoke: () => Promise<void>;
+    /** Turn this guest into an email/password account under the same subject ID
+     * (`authRoutesPlugin({ guestUpgrade })`). The device proof is erased only after the
+     * server confirmed the account; on any refusal or transport failure it stays. */
+    upgrade: (input: {
+        readonly email: string;
+        readonly password: string;
+    }) => Promise<{
+        readonly subject: unknown;
+    }>;
+    /** The registered account signed in on this device (cookie clients), or null. */
+    account: () => Promise<GuestClientAccount | null>;
+    /** The signed-in account if there is one, else this device's guest (resumed or created once).
+     * The usual entry for a game that offers accounts: a reload after `upgrade` or `signIn` stays the account. */
+    start: () => Promise<GuestClientPlayer>;
+    /** Sign in to an existing account with email and password (`authRoutesPlugin`), e.g. on a second
+     * device. This device's guest proof stays: after `signOut`, `start` resumes that guest. */
+    signIn: (input: {
+        readonly email: string;
+        readonly password: string;
+    }) => Promise<GuestClientAccount>;
+    /** End the account session on the server and clear its cookie. */
+    signOut: () => Promise<void>;
+};
+
 /** Trade the code + verifier for the session value. */
 export declare const exchangeNativeCode: (input: {
     readonly code: string;
@@ -14,6 +49,61 @@ export declare const exchangeNativeCode: (input: {
     readonly fetch?: typeof fetch;
 }) => Promise<NativeSession>;
 
+/** A registered account signed in on this device (by upgrade or sign-in), through the session cookie. */
+declare interface GuestClientAccount {
+    readonly subject: Extract<SubjectIdentity, {
+        readonly type: 'user';
+    }>;
+}
+
+export declare class GuestClientError extends Error {
+    readonly code: 'storage_unavailable' | 'credential_rejected' | 'upgrade_conflict' | 'account_signed_in' | 'transport_failed' | 'invalid_response';
+    readonly status?: number | undefined;
+    constructor(code: 'storage_unavailable' | 'credential_rejected' | 'upgrade_conflict' | 'account_signed_in' | 'transport_failed' | 'invalid_response', status?: number | undefined);
+}
+
+export declare interface GuestClientOptions {
+    readonly apiBaseUrl: string;
+    readonly storage: GuestCredentialStore;
+    readonly prefix?: string;
+    readonly fetch?: typeof globalThis.fetch;
+    /** Web clients include cookies and obtain a signed CSRF token for each post. */
+    readonly cookies?: boolean;
+    /** Prefix of the app's auth routes, for `upgrade`, `account`, `signIn` and `signOut` (default `/auth`). */
+    readonly accountPrefix?: string;
+}
+
+/** What `start` found: the signed-in account, else this device's guest. */
+declare type GuestClientPlayer = {
+    readonly kind: 'account';
+    readonly subject: GuestClientAccount['subject'];
+} | {
+    readonly kind: 'guest';
+    readonly subject: GuestClientSession['subject'];
+    readonly session: string;
+};
+
+export declare interface GuestClientSession {
+    readonly subject: Extract<SubjectIdentity, {
+        readonly type: 'user';
+    }> & {
+        readonly kind: 'guest';
+    };
+    readonly session: string;
+}
+
+/** Platform-backed durable secret storage. Native implementations use the
+ * operating system's secure store; writes resolve only after persistence. */
+export declare interface GuestCredentialStore {
+    /** Serialize the whole read/create/write operation across users of this
+     * namespace, including other browser tabs or native client instances. */
+    readonly exclusive: <A>(work: () => Promise<A>) => Promise<A>;
+    readonly read: () => Promise<string | null>;
+    /** Persist the opaque value, including an in-progress rotation journal. */
+    readonly write: (value: string) => Promise<void>;
+    readonly remove: () => Promise<void>;
+}
+
 export declare type NativeCallback = {
     readonly kind: 'code';
     readonly code: string;
@@ -40,6 +130,26 @@ export declare class NativeExchangeError extends Error {
     constructor(status: number, code: string);
 }
 
+/** Adapt an explicitly supplied durable native store and host-wide lock.
+ * Refuse memory/unwired stores; never select a fallback or initialize a store. */
+export declare const nativeGuestStore: (options: NativeGuestStoreOptions) => GuestCredentialStore;
+
+/** Structurally accepts a platform TokenStore without importing a UI runtime. */
+export declare interface NativeGuestStoreOptions {
+    /** App/tenant namespace; storage and the host lock use the same exact key. */
+    readonly namespace: string;
+    readonly store: {
+        readonly kind: string;
+        readonly get: (key: string) => Promise<string | null>;
+        readonly set: (key: string, value: string) => Promise<void>;
+        readonly delete: (key: string) => Promise<void>;
+    };
+    /** The host must serialize all client instances, including other processes.
+     * Release the lock after both success and failure; writes must be durable
+     * before resolving. A process-local Promise queue does not meet this contract. */
+    readonly exclusive: <A>(key: string, work: () => Promise<A>) => Promise<A>;
+}
+
 export declare interface NativeLoginHandoff {
     /** Open this in the SYSTEM browser (not an in-app webview): the user's
      *  existing browser session and password manager are the point. */

package/dist/native.js

@@ -1,42 +1,44 @@
-import { SESSION_HEADER_NAME as e } from "@voltro/protocol";
+import { GuestClientError as e, createGuestClient as t } from "./guestClient.js";
+import { nativeGuestStore as n } from "./native/guestStorage.js";
+import { SESSION_HEADER_NAME as r } from "@voltro/protocol";
 //#region src/native/index.ts
-var t = (e) => {
+var i = (e) => {
 	let t = "";
 	for (let n of e) t += String.fromCharCode(n);
 	return (typeof btoa == "function" ? btoa(t) : globalThis.Buffer.from(t, "binary").toString("base64")).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}, n = (e) => {
+}, a = (e) => {
 	let t = new Uint8Array(e.length);
 	for (let n = 0; n < e.length; n++) t[n] = e.charCodeAt(n) & 127;
 	return t;
-}, r = (e) => e.replace(/\/+$/, ""), i = async (e, r) => t(await r.sha256(n(e))), a = async (e) => {
-	let n = t(e.crypto.randomBytes(32)), a = t(e.crypto.randomBytes(16)), o = await i(n, e.crypto), s = new URLSearchParams({
+}, o = (e) => e.replace(/\/+$/, ""), s = async (e, t) => i(await t.sha256(a(e))), c = async (e) => {
+	let t = i(e.crypto.randomBytes(32)), n = i(e.crypto.randomBytes(16)), r = await s(t, e.crypto), a = new URLSearchParams({
 		redirect_uri: e.redirectUri,
-		code_challenge: o,
+		code_challenge: r,
 		code_challenge_method: "S256",
-		state: a
+		state: n
 	}), c = e.prefix ?? "/auth";
 	return {
-		url: `${r(e.apiBaseUrl)}${c}/native/authorize?${s.toString()}`,
-		codeVerifier: n,
-		state: a
+		url: `${o(e.apiBaseUrl)}${c}/native/authorize?${a.toString()}`,
+		codeVerifier: t,
+		state: n
 	};
-}, o = (e, t, n) => {
-	let i = e.indexOf("?");
-	if (r(i === -1 ? e : e.slice(0, i)) !== r(n)) return {
+}, l = (e, t, n) => {
+	let r = e.indexOf("?");
+	if (o(r === -1 ? e : e.slice(0, r)) !== o(n)) return {
 		kind: "ignored",
 		reason: "not-the-callback"
 	};
-	let a = new URLSearchParams(i === -1 ? "" : e.slice(i + 1));
-	if (a.get("state") !== t.state) return {
+	let i = new URLSearchParams(r === -1 ? "" : e.slice(r + 1));
+	if (i.get("state") !== t.state) return {
 		kind: "ignored",
 		reason: "state-mismatch"
 	};
-	let o = a.get("error");
-	if (o) return {
+	let a = i.get("error");
+	if (a) return {
 		kind: "error",
-		error: o
+		error: a
 	};
-	let s = a.get("code");
+	let s = i.get("code");
 	return s ? {
 		kind: "code",
 		code: s
@@ -44,43 +46,43 @@ var t = (e) => {
 		kind: "ignored",
 		reason: "no-code"
 	};
-}, s = class extends Error {
+}, u = class extends Error {
 	status;
 	code;
 	constructor(e, t) {
 		super(`native login exchange failed: ${t} (${e})`), this.name = "NativeExchangeError", this.status = e, this.code = t;
 	}
-}, c = async (e, t) => {
-	let n = t.fetch ?? fetch, i = t.prefix ?? "/auth", a = await n(`${r(t.apiBaseUrl)}${i}/native/exchange`, {
+}, d = async (e, t) => {
+	let n = t.fetch ?? fetch, r = t.prefix ?? "/auth", i = await n(`${o(t.apiBaseUrl)}${r}/native/exchange`, {
 		method: "POST",
 		headers: { "content-type": "application/json" },
 		body: JSON.stringify(e)
-	}), o = await a.json().catch(() => ({}));
-	if (!a.ok || typeof o.session != "string" || typeof o.expiresAt != "number" || !o.subject) throw new s(a.status, o.error ?? "invalid_response");
+	}), a = await i.json().catch(() => ({}));
+	if (!i.ok || typeof a.session != "string" || typeof a.expiresAt != "number" || !a.subject) throw new u(i.status, a.error ?? "invalid_response");
 	return {
-		session: o.session,
-		expiresAt: o.expiresAt,
-		subject: o.subject
+		session: a.session,
+		expiresAt: a.expiresAt,
+		subject: a.subject
 	};
-}, l = (t) => ({ [e]: t }), u = async (e, t) => {
-	let n = t.fetch ?? fetch, i = t.prefix ?? "/auth", a = await n(`${r(t.apiBaseUrl)}${i}/session`, {
+}, f = (e) => ({ [r]: e }), p = async (e, t) => {
+	let n = t.fetch ?? fetch, r = t.prefix ?? "/auth", i = await n(`${o(t.apiBaseUrl)}${r}/session`, {
 		method: "GET",
-		headers: l(e)
+		headers: f(e)
 	});
-	if (a.status === 401) return null;
-	let o = await a.json().catch(() => ({}));
-	return !a.ok || o.ok !== !0 || !o.subject || typeof o.expiresAt != "number" ? null : {
-		session: o.session ?? e,
-		expiresAt: o.expiresAt,
-		subject: o.subject
+	if (i.status === 401) return null;
+	let a = await i.json().catch(() => ({}));
+	return !i.ok || a.ok !== !0 || !a.subject || typeof a.expiresAt != "number" ? null : {
+		session: a.session ?? e,
+		expiresAt: a.expiresAt,
+		subject: a.subject
 	};
-}, d = async (e) => {
-	let t = await a(e);
+}, m = async (e) => {
+	let t = await c(e);
 	await e.open(t.url);
-	let n = await e.awaitCallback((n) => o(n, t, e.redirectUri));
-	if (n.kind === "error") throw new s(0, n.error);
-	if (n.kind !== "code") throw new s(0, n.reason);
-	return c({
+	let n = await e.awaitCallback((n) => l(n, t, e.redirectUri));
+	if (n.kind === "error") throw new u(0, n.error);
+	if (n.kind !== "code") throw new u(0, n.reason);
+	return d({
 		code: n.code,
 		codeVerifier: t.codeVerifier
 	}, {
@@ -90,4 +92,4 @@ var t = (e) => {
 	});
 };
 //#endregion
-export { s as NativeExchangeError, a as beginNativeLogin, c as exchangeNativeCode, i as nativeCodeChallenge, o as parseNativeCallback, u as probeNativeSession, d as runNativeLogin, l as sessionHeaders };
+export { e as GuestClientError, u as NativeExchangeError, c as beginNativeLogin, t as createGuestClient, d as exchangeNativeCode, s as nativeCodeChallenge, n as nativeGuestStore, l as parseNativeCallback, p as probeNativeSession, m as runNativeLogin, f as sessionHeaders };

package/dist/nativeRoutes.js

@@ -1,37 +1,23 @@
 import { hashToken as e, mintToken as t } from "./tokens.js";
-import { configSigningKey as n, issueUserSession as r } from "./handlers.js";
-import { createHash as i, createHmac as a, randomBytes as o, timingSafeEqual as s } from "node:crypto";
+import { configSessionSecrets as n, issueUserSession as r } from "./handlers.js";
+import { signAuthClaims as i, verifyAuthClaims as a } from "./signedClaims.js";
+import { createHash as o, randomBytes as s } from "node:crypto";
 import { Effect as c } from "effect";
 import { buildSetCookie as l, readCookie as u } from "@voltro/protocol/session";
 //#region src/nativeRoutes.ts
-var d = "voltro:native", f = 600, p = "/login", m = (e) => e.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""), h = (e) => Buffer.from(e.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - e.length % 4) % 4), "base64"), g = (e) => m(i("sha256").update(e, "ascii").digest()), _ = (e, t) => {
-	let n = m(Buffer.from(JSON.stringify(e), "utf8"));
-	return `${n}.${m(a("sha256", t).update(n).digest())}`;
-}, v = (e, t, n = Date.now) => {
-	if (!e) return null;
-	let r = e.indexOf(".");
-	if (r <= 0 || r === e.length - 1) return null;
-	let i = e.slice(0, r), o = h(e.slice(r + 1)), c = a("sha256", t).update(i).digest();
-	if (o.length !== c.length || !s(o, c)) return null;
-	try {
-		let e = JSON.parse(h(i).toString("utf8"));
-		return typeof e.exp != "number" || e.exp * 1e3 < n() ? null : e;
-	} catch {
-		return null;
-	}
-}, y = (e, t) => t.includes(e), b = (e, t) => {
+var d = "voltro:native", f = 600, p = "/login", m = (e) => e.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""), h = (e) => m(o("sha256").update(e, "ascii").digest()), g = (e, t) => t.includes(e), _ = (e, t) => {
 	let n = new URLSearchParams(t).toString();
 	return `${e}${e.includes("?") ? "&" : "?"}${n}`;
-}, x = (e, t) => ({
+}, v = (e, t) => ({
 	status: e,
 	body: JSON.stringify(t),
 	contentType: "application/json; charset=utf-8"
-}), S = (e, t) => ({
+}), y = (e, t) => ({
 	status: 302,
 	body: "",
 	location: e,
 	...t === void 0 ? {} : { setCookie: t }
-}), C = (e) => {
+}), b = (e) => {
 	if (!e) return null;
 	let { ch: t, r: n, s: r, exp: i } = e;
 	return typeof t != "string" || typeof n != "string" || typeof r != "string" || typeof i != "number" ? null : {
@@ -40,81 +26,84 @@ var d = "voltro:native", f = 600, p = "/login", m = (e) => e.toString("base64").
 		s: r,
 		exp: i
 	};
-}, w = (e, t, n) => l(e.native.pendingCookieName ?? "voltro:native", t, {
+}, x = (e, t, r) => {
+	let i = n(r.config);
+	return [i.current, i.previous].filter((e) => e !== void 0).map((n) => a(e, n.secret, t, r.now)).find((e) => e !== null) ?? null;
+}, S = (e, t, n) => l(e.native.pendingCookieName ?? "voltro:native", t, {
 	maxAgeSeconds: n,
 	httpOnly: !0,
 	sameSite: "lax",
 	secure: e.config.cookieSecure ?? !0,
 	path: `${e.prefix}/native`
-}), T = (e) => `${e.native.loginPath ?? p}?next=${encodeURIComponent(`${e.prefix}/native/complete`)}`, E = (e, t, r, i) => c.gen(function* () {
-	let a = e.get("redirect_uri") ?? "", o = e.get("code_challenge") ?? "", s = e.get("code_challenge_method") ?? "S256", c = e.get("state") ?? "";
-	if (!y(a, i.native.redirectUris)) return x(400, { error: "redirect_uri_not_allowed" });
-	if (s !== "S256" || o.length < 43 || o.length > 128) return S(b(a, {
+}), C = (e) => `${e.native.loginPath ?? p}?next=${encodeURIComponent(`${e.prefix}/native/complete`)}`, w = (e, t, r, a) => c.gen(function* () {
+	let o = e.get("redirect_uri") ?? "", s = e.get("code_challenge") ?? "", c = e.get("code_challenge_method") ?? "S256", l = e.get("state") ?? "";
+	if (!g(o, a.native.redirectUris)) return v(400, { error: "redirect_uri_not_allowed" });
+	if (c !== "S256" || s.length < 43 || s.length > 128) return y(_(o, {
 		error: "invalid_request",
-		state: c
+		state: l
 	}));
-	if (c.length === 0) return S(b(a, { error: "invalid_request" }));
-	let l = i.now ?? Date.now, u = i.native.pendingTtlSeconds ?? f, d = {
-		ch: o,
-		r: a,
-		s: c,
-		exp: Math.floor(l() / 1e3) + u
-	}, p = w(i, _({ ...d }, n(i.config)), u);
+	if (l.length === 0) return y(_(o, { error: "invalid_request" }));
+	let u = a.now ?? Date.now, d = a.native.pendingTtlSeconds ?? f, p = {
+		ch: s,
+		r: o,
+		s: l,
+		exp: Math.floor(u() / 1e3) + d
+	}, m = S(a, i({ ...p }, n(a.config).current.secret, "native-pending"), d);
 	return t && t.subject.type === "user" && t.sessionId ? {
-		...yield* D(d, {
+		...yield* T(p, {
 			userId: t.subject.id,
 			sessionId: t.sessionId
-		}, r, i),
-		setCookie: w(i, "", 0)
-	} : S(T(i), p);
-}), D = (e, r, i, a) => c.gen(function* () {
-	let s = t("native-code", 300);
-	yield* i.insertToken({
-		id: `tok_${m(o(12))}`,
-		tokenHash: s.tokenHash,
+		}, r, a),
+		setCookie: S(a, "", 0)
+	} : y(C(a), m);
+}), T = (e, r, a, o) => c.gen(function* () {
+	let c = t("native-code", 300);
+	yield* a.insertToken({
+		id: `tok_${m(s(12))}`,
+		tokenHash: c.tokenHash,
 		userId: r.userId,
 		purpose: "native-code",
-		expiresAt: s.expiresAt
+		expiresAt: c.expiresAt
 	});
-	let c = _({
+	let l = i({
 		sid: r.sessionId,
 		uid: r.userId,
 		ch: e.ch,
-		exp: Math.floor(s.expiresAt.getTime() / 1e3)
-	}, n(a.config));
-	return S(b(e.r, {
-		code: `${s.token}.${c}`,
+		exp: Math.floor(c.expiresAt.getTime() / 1e3)
+	}, n(o.config).current.secret, "native-code");
+	return y(_(e.r, {
+		code: `${c.token}.${l}`,
 		state: e.s
 	}));
-}), O = (e, t, r, i) => c.gen(function* () {
-	let a = C(v(u(e, i.native.pendingCookieName ?? "voltro:native"), n(i.config), i.now));
-	return a ? !t || t.subject.type !== "user" || !t.sessionId ? S(T(i)) : {
-		...yield* D(a, {
+}), E = (e, t, n, r) => c.gen(function* () {
+	let i = b(x(u(e, r.native.pendingCookieName ?? "voltro:native"), "native-pending", r));
+	return i ? !t || t.subject.type !== "user" || !t.sessionId ? y(C(r)) : {
+		...yield* T(i, {
 			userId: t.subject.id,
 			sessionId: t.sessionId
-		}, r, i),
-		setCookie: w(i, "", 0)
-	} : x(400, { error: "no_pending_native_login" });
-}), k = (t, i, a) => c.gen(function* () {
-	let o = t.code.indexOf(".");
-	if (o <= 0) return x(400, { error: "invalid_code" });
-	let s = t.code.slice(0, o), c = v(t.code.slice(o + 1), n(a.config), a.now), l = c?.sid, u = c?.uid, d = c?.ch;
-	if (typeof l != "string" || typeof u != "string" || typeof d != "string") return x(400, { error: "invalid_code" });
-	let f = yield* i.consumeToken(e(s), "native-code");
-	if (!f || f.userId !== u || t.codeVerifier.length < 43 || g(t.codeVerifier) !== d) return x(400, { error: "invalid_code" });
-	let p = yield* i.findById(u);
-	if (!p) return x(400, { error: "invalid_code" });
-	let m = yield* r(p, i, a.config, {
-		sessionId: l,
+		}, n, r),
+		setCookie: S(r, "", 0)
+	} : v(400, { error: "no_pending_native_login" });
+}), D = (t, n, i) => c.gen(function* () {
+	let a = t.code.indexOf(".");
+	if (a <= 0) return v(400, { error: "invalid_code" });
+	let o = t.code.slice(0, a), s = x(t.code.slice(a + 1), "native-code", i), c = s?.sid, l = s?.uid, u = s?.ch;
+	if (typeof c != "string" || typeof l != "string" || typeof u != "string") return v(400, { error: "invalid_code" });
+	let d = yield* n.consumeToken(e(o), "native-code");
+	if (!d || d.userId !== l || t.codeVerifier.length < 43 || h(t.codeVerifier) !== u) return v(400, { error: "invalid_code" });
+	let f = yield* n.findById(l);
+	if (!f) return v(400, { error: "invalid_code" });
+	let p = yield* r(f, n, i.config, {
+		sessionId: c,
 		sessionRow: "existing",
 		clearLoginFailures: !1
 	});
-	return x(200, {
+	return v(200, {
 		ok: !0,
-		session: m.value,
-		expiresAt: m.expiresAt,
-		subject: m.subject
+		session: p.value,
+		expiresAt: p.expiresAt,
+		subject: p.subject
 	});
 });
 //#endregion
-export { d as NATIVE_PENDING_COOKIE, E as handleNativeAuthorize, O as handleNativeComplete, k as handleNativeExchange, y as isAllowedRedirectUri, T as nativeLoginRedirect, g as s256, _ as signClaims, v as verifyClaims };
+export { d as NATIVE_PENDING_COOKIE, w as handleNativeAuthorize, E as handleNativeComplete, D as handleNativeExchange, g as isAllowedRedirectUri, C as nativeLoginRedirect, h as s256 };