@voltro/plugin-auth 0.86.0 → 0.88.0

package/dist/overlayPlugin.js

@@ -0,0 +1,166 @@
+import { sessionSecretsOf as e } from "./session.js";
+import { isSessionCredentialLiveFor as t } from "./sessionFamily.js";
+import { dataStoreSessionRegistry as n } from "./sessionRegistry.js";
+import { validateGuestSecrets as r } from "./guestSecrets.js";
+import { authTokensTable as i, sessionsTable as a } from "./schema.js";
+import { createCipheriv as o, createDecipheriv as s, createHash as c, hkdfSync as l, randomBytes as u } from "node:crypto";
+import { Duration as d, Effect as f } from "effect";
+import { SESSION_COOKIE_NAME as p, SESSION_HEADER_NAME as m, buildSetCookie as h, resolveSessionSecrets as g, verifySessionKeyed as _ } from "@voltro/protocol/session";
+import { definePlugin as v } from "@voltro/protocol";
+// src/overlayPlugin.ts
+var y = "overlay-code", b = "authTokens", x = 60, S = 300, C = (e, t) => ({
+	status: e,
+	body: JSON.stringify(t),
+	contentType: "application/json",
+	headers: { "cache-control": "no-store" }
+}), w = (e) => `ovl_${c("sha256").update(e).digest("hex")}`, T = (e) => Buffer.from(l("sha256", e, "voltro:web-overlay:v1", "overlay-code", 32)), E = (e, t) => {
+	let n = u(12), r = o("aes-256-gcm", T(t), n), i = Buffer.concat([r.update(JSON.stringify({
+		v: e.value,
+		n: e.next,
+		exp: e.exp
+	}), "utf8"), r.final()]);
+	return Buffer.concat([
+		n,
+		r.getAuthTag(),
+		i
+	]).toString("base64url");
+}, D = (e, t, n) => {
+	if (e.length < 40 || e.length > 12e3 || !/^[A-Za-z0-9_-]+$/.test(e)) return null;
+	let r = Buffer.from(e, "base64url");
+	if (r.length < 29) return null;
+	for (let e of t) try {
+		let t = s("aes-256-gcm", T(e), r.subarray(0, 12));
+		t.setAuthTag(r.subarray(12, 28));
+		let i = JSON.parse(Buffer.concat([t.update(r.subarray(28)), t.final()]).toString("utf8"));
+		return typeof i.v != "string" || typeof i.n != "string" || typeof i.exp != "number" || i.exp <= n ? null : {
+			value: i.v,
+			next: i.n,
+			exp: i.exp
+		};
+	} catch {}
+	return null;
+}, O = (e) => !/^\/[A-Za-z0-9/_.~-]*$/.test(e) || e.startsWith("//") || e.split("/").some((e) => e === ".." || e === ".") ? null : e.length > 1 && e.endsWith("/") ? e.slice(0, -1) : e, k = (e, t) => {
+	if (e.length > 512 || /[\u0000-\u001f\\#]/.test(e)) return !1;
+	let n = O(e.split("?")[0] ?? "");
+	return n !== null && t.some((e) => e === "/" || n === e || n.startsWith(e + "/"));
+}, A = async (r, i, a, o) => {
+	let s = _(r, e(i));
+	if (!s || s.subject.type !== "user") return null;
+	let c = s.subject.metadata?.sessionId;
+	if (typeof c != "string") return null;
+	let l = await f.runPromise(n(a).findSession(c));
+	return t(l, c, s.subject.id, o) ? {
+		subjectId: s.subject.id,
+		exp: s.exp
+	} : null;
+}, j = (t) => {
+	let n = t.prefix ?? "/auth/overlay";
+	if (!/^\/[a-zA-Z0-9/_-]+$/.test(n) || n.endsWith("/")) throw Error("Overlay route prefix must be an absolute path without a trailing slash");
+	let o = t.paths.map((e) => O(e));
+	if (o.length === 0 || o.some((e) => e === null)) throw Error("Overlay paths must be absolute same-origin paths without traversal");
+	let s = o, c = d.toSeconds(t.ttl ?? `${x} seconds`);
+	if (!Number.isSafeInteger(c) || c < 1 || c > S) throw Error("Overlay ticket lifetime must be 1 to 300 whole seconds");
+	let l = () => r(t.secret ?? g()), _, T = async (t, r) => {
+		if (t.method !== "POST") return {
+			...C(405, { error: "method_not_allowed" }),
+			headers: {
+				"cache-control": "no-store",
+				allow: "POST"
+			}
+		};
+		if ((t.headers["content-type"] ?? "").split(";")[0]?.trim() !== "application/json") return C(415, { error: "json_required" });
+		if (t.rawBody.byteLength > 1024) return C(413, { error: "body_too_large" });
+		let i = t.headers[m];
+		if (!i) return C(401, { error: "session_header_required" });
+		let a;
+		try {
+			a = JSON.parse(new TextDecoder().decode(t.rawBody));
+		} catch {
+			return C(400, { error: "invalid_input" });
+		}
+		if (typeof a != "object" || !a || Array.isArray(a) || Object.keys(a).some((e) => e !== "next") || typeof a.next != "string") return C(400, { error: "invalid_input" });
+		let o = a.next;
+		if (!k(o, s)) return C(400, { error: "page_not_allowed" });
+		let d = Date.now(), f = await A(i, l(), r, d);
+		if (!f) return C(401, { error: "session_rejected" });
+		let p = Math.min(Math.floor(d / 1e3) + c, f.exp), h = u(32).toString("base64url");
+		await r.insert(b, {
+			id: w(h),
+			tokenHash: w(h).slice(4),
+			userId: f.subjectId,
+			purpose: y,
+			expiresAt: /* @__PURE__ */ new Date(p * 1e3),
+			consumedAt: null
+		});
+		let g = `${h}.${E({
+			value: i,
+			next: o,
+			exp: p
+		}, e(l()).current.secret)}`;
+		return C(200, {
+			url: `${n}/enter?code=${g}`,
+			expiresAt: p
+		});
+	}, j = async (n, r) => {
+		if (n.method !== "GET") return {
+			...C(405, { error: "method_not_allowed" }),
+			headers: {
+				"cache-control": "no-store",
+				allow: "GET"
+			}
+		};
+		let i = new URLSearchParams(n.query).get("code") ?? "", a = i.indexOf("."), o = i.slice(0, a);
+		if (a <= 0 || !/^[A-Za-z0-9_-]{43}$/.test(o)) return C(400, { error: "invalid_code" });
+		let c = e(l()), u = Date.now(), d = D(i.slice(a + 1), [c.current.secret, ...c.previous ? [c.previous.secret] : []], Math.floor(u / 1e3));
+		if (!await r.delete(b, w(o)) || !d || !k(d.next, s)) return C(400, { error: "invalid_code" });
+		if (!await A(d.value, c, r, u)) return C(401, { error: "session_rejected" });
+		let f = h(p, d.value, {
+			httpOnly: !0,
+			sameSite: "lax",
+			secure: t.secure ?? !0,
+			path: "/",
+			...t.domain ? { domain: t.domain } : {}
+		});
+		return {
+			status: 302,
+			body: "",
+			headers: {
+				location: d.next,
+				"set-cookie": f,
+				"cache-control": "no-store",
+				"referrer-policy": "no-referrer"
+			}
+		};
+	};
+	return v({
+		name: "@voltro/plugin-auth#overlay",
+		baseName: "@voltro/plugin-auth",
+		permissions: ["store:write"],
+		extendSchema: { tables: [i, a] },
+		declaredEnv: t.secret === void 0 ? [{
+			name: "VOLTRO_SESSION_SECRET",
+			required: !0,
+			secret: !0,
+			generate: "base64url",
+			description: "Signs this project's sessions and seals web overlay tickets"
+		}] : [],
+		httpRoutes: [{
+			method: "*",
+			path: n,
+			handle: async (e) => {
+				let t = e.store ?? _;
+				return e.path !== n + "/ticket" && e.path !== n + "/enter" ? C(404, { error: "not_found" }) : t ? e.path === n + "/ticket" ? T(e, t) : j(e, t) : C(503, { error: "store_unavailable" });
+			}
+		}],
+		bindDataStore: (e) => {
+			_ = e;
+		},
+		onActivate: () => f.sync(() => {
+			l();
+		}),
+		onDeactivate: () => f.sync(() => {
+			_ = void 0;
+		})
+	});
+};
+export { y as OVERLAY_TOKEN_PURPOSE, k as allowedOverlayPage, j as overlayAuthPlugin };

package/dist/passkeyHandlers.js

@@ -3,7 +3,7 @@ import { newAuthId as t, subjectFromUser as n } from "./userStore.js";
 import { configSessionSecrets as r, guardSubject as i } from "./handlers.js";
 import { generateChallenge as a, verifyAssertion as o, verifyRegistration as s } from "./webauthn.js";
 import { Effect as c } from "effect";
-//#region src/passkeyHandlers.ts
+// src/passkeyHandlers.ts
 var l = (e, t, n = {}) => ({
 	status: e,
 	body: JSON.stringify(t),
@@ -158,5 +158,4 @@ var l = (e, t, n = {}) => ({
 		subject: C
 	}, { setCookie: w.setCookie });
 });
-//#endregion
 export { f as dataStoreChallengeStore, g as handlePasskeyAssertOptions, _ as handlePasskeyAssertVerify, m as handlePasskeyRegisterOptions, h as handlePasskeyRegisterVerify, d as memoryChallengeStore };

package/dist/password.js

@@ -1,6 +1,6 @@
 import { randomBytes as e, scrypt as t, timingSafeEqual as n } from "node:crypto";
 import { Data as r, Effect as i } from "effect";
-//#region src/password.ts
+// src/password.ts
 var a = 32768, o = 8, s = 1, c = 32, l = 16, u = (e, t) => 128 * e * t * 2, d = 268435456, f = class extends r.TaggedError("PasswordEmptyError") {}, p = class extends r.TaggedError("PasswordHashError") {}, m = (e, n, r, a) => i.callback((o) => {
 	t(e, n, r, {
 		...a,
@@ -71,5 +71,4 @@ var a = 32768, o = 8, s = 1, c = 32, l = 16, u = (e, t) => 128 * e * t * 2, d =
 		rehash: n
 	} : { valid: !0 };
 });
-//#endregion
 export { f as PasswordEmptyError, p as PasswordHashError, h as hashPassword, y as needsRehash, v as parseScryptParams, g as verifyPassword, b as verifyPasswordWithRehash };

package/dist/plugin.d.ts

@@ -5,6 +5,7 @@ import { Effect } from 'effect';
 import { SessionSecrets } from '@voltro/protocol/session';
 import { SqlClient } from 'effect/sql/SqlClient';
 import { Subject } from '@voltro/protocol';
+import { SubjectIdentity } from '@voltro/protocol';
 import { VoidIfEmpty } from 'effect/Types';
 import { VoltroPlugin } from '@voltro/protocol';
 import { YieldableError } from 'effect/Cause';
@@ -124,7 +125,7 @@ declare interface AuthConfig {
  * routes use) so the framework's serve pipeline can slot it into the
  * per-app auth chain — the rpc/WS path then rejects revoked sessions
  * exactly like the `/auth/*` routes. Read it via
- * `getAuthSessionStrategy`.
+ * `getAuthSessionStrategies`.
  */
 export declare interface AuthPlugin extends VoltroPlugin {
     readonly auth: {
@@ -174,6 +175,15 @@ export declare interface AuthRoutesPluginOptions extends AuthConfig {
      * otherwise get 500s from a route it never asked for.
      */
     readonly invitations?: InvitationsConfig;
+    /**
+     * Guest → account with email and password. PRESENT mounts `POST /auth/upgrade-guest`
+     * (`{ credential, email, password }`, CSRF): the guest becomes a registered account under its
+     * own subject ID, so what it owns stays its own. Pass the installed guest lifecycle port,
+     * e.g. `{ service: () => guestPlugin.guest.service() }`. ABSENT mounts nothing.
+     */
+    readonly guestUpgrade?: {
+        readonly service: () => GuestAuthService;
+    };
     /**
      * User impersonation ("log in as"). PRESENT mounts `/auth/impersonate/start`
      * + `/stop`, arms the retention bound on `impersonationGrants`, and closes
@@ -242,11 +252,12 @@ declare interface EmailVerificationConfig {
 declare type EmailVerificationPolicy = 'off' | 'soft' | 'strict';
 
 /**
- * Pull the pre-wired session strategy off a plugin list (the framework's
- * serve pipeline calls this when composing the auth chain). Returns the
- * FIRST auth plugin's strategy, or null when no auth plugin is present.
+ * Collect pre-wired session strategies in plugin declaration order. The
+ * framework inserts each original strategy into its shared auth chain, so
+ * prefix ordering, collision diagnostics and boot verification see them all.
+ * Only `skip` advances; rejected credentials never get another attempt.
  */
-export declare const getAuthSessionStrategy: (plugins: ReadonlyArray<VoltroPlugin>) => AuthStrategy | null;
+export declare const getAuthSessionStrategies: (plugins: ReadonlyArray<VoltroPlugin>) => ReadonlyArray<AuthStrategy>;
 
 declare interface GrantRoleContext {
     /** The inviter's role in THIS tenant, as read from `memberships`. */
@@ -256,6 +267,91 @@ declare interface GrantRoleContext {
     readonly tenantId: string;
 }
 
+declare class GuestAuthError extends GuestAuthError_base<{
+    readonly code: 'credential_rejected' | 'store_unavailable' | 'upgrade_conflict';
+}> {
+}
+
+declare const GuestAuthError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "GuestAuthError";
+} & Readonly<A>;
+
+/** Durable guest lifecycle port. Implementations must serialize every write
+ * against the guest identity and commit session rows before returning credentials. */
+declare interface GuestAuthService {
+    readonly create: () => Effect.Effect<GuestSession, GuestAuthError>;
+    readonly resume: (credential: string) => Effect.Effect<GuestSession, GuestAuthError>;
+    /** Propose a fresh server-minted proof without replacing the active proof. */
+    readonly prepareRotation: (credential: string) => Effect.Effect<{
+        readonly deviceCredential: string;
+    }, GuestAuthError>;
+    /** The caller durably journals both proofs before this atomic replacement. */
+    readonly rotate: (credential: string, nextCredential: string) => Effect.Effect<GuestSession, GuestAuthError>;
+    readonly revoke: (credential: string) => Effect.Effect<void, GuestAuthError>;
+    /** Server-side privacy hook: the caller must authorize this subject ID. */
+    readonly erase: (subjectId: string) => Effect.Effect<boolean, GuestAuthError>;
+    /** Server-side privacy hook: excludes credential hashes and credential bytes. */
+    readonly export: (subjectId: string) => Effect.Effect<GuestExport | null, GuestAuthError>;
+    readonly isLive: (subject: SubjectIdentity) => Effect.Effect<boolean, GuestAuthError>;
+    /** Trusted server operation. The writer must use this transaction to create
+     * the registered `users` row with exactly the guest ID and tenant. The guest
+     * fence, writer, device removal and guest-session revocation commit together.
+     * No client-supplied kind/state can authorize an upgrade. */
+    readonly upgrade: <A>(credential: string, writer: GuestUpgradeWriter<A>) => Effect.Effect<A, GuestAuthError>;
+    /** Trusted, separately confirmed merge into an EXISTING registered subject.
+     * The coordinator must prove target ownership and run all data hooks through
+     * this same transaction. A device proof alone never proves target ownership. */
+    readonly mergeInto: <A>(credential: string, targetId: string, writer: GuestMergeWriter<A>) => Effect.Effect<A, GuestAuthError>;
+}
+
+declare interface GuestExport {
+    readonly subject: {
+        readonly id: string;
+        readonly tenantId: string;
+        readonly kind: 'guest';
+        readonly upgradeable: boolean;
+        readonly createdAt: number;
+        readonly expiresAt: number;
+    };
+    readonly devices: ReadonlyArray<{
+        readonly id: string;
+        readonly generation: number;
+        readonly createdAt: number;
+        readonly expiresAt: number;
+    }>;
+    readonly sessions: ReadonlyArray<{
+        readonly id: string;
+        readonly expiresAt: number;
+    }>;
+}
+
+declare type GuestIdentity = Extract<SubjectIdentity, {
+    readonly type: 'user';
+}> & {
+    readonly kind: 'guest';
+};
+
+declare interface GuestMergeContext extends GuestUpgradeContext {
+    readonly targetId: string;
+}
+
+declare type GuestMergeWriter<A> = (context: GuestMergeContext) => Promise<A>;
+
+declare interface GuestSession extends IssuedRegisteredSession {
+    readonly subject: GuestIdentity;
+    /** Opaque proof returned only on creation or explicit credential rotation. */
+    readonly deviceCredential?: string;
+}
+
+declare interface GuestUpgradeContext {
+    readonly store: DataStore;
+    readonly subjectId: string;
+    readonly tenantId: string;
+    readonly createdAt: Date;
+}
+
+declare type GuestUpgradeWriter<A> = (context: GuestUpgradeContext) => Promise<A>;
+
 /** Identity — who a user is. The only role an app with its own identity table has to write itself; everything else composes from the shipped store. */
 declare interface IdentityStore {
     readonly findByEmail: (email: string) => Effect.Effect<UserRecord | null>;
@@ -470,6 +566,18 @@ declare interface InvitationStore {
     readonly supersedePendingInvitations: (tenantId: string, email: string, revokedByUserId: string, now: Date) => Effect.Effect<number>;
 }
 
+declare interface IssuedRegisteredSession extends IssuedSession {
+    /** The row's id — what `revokeSession` takes. */
+    readonly sessionId: string;
+}
+
+declare interface IssuedSession {
+    /** The opaque cookie value — `<payload>.<sig>`. */
+    readonly value: string;
+    /** Ready-to-Set-Cookie header string with sane defaults. */
+    readonly setCookie: string;
+}
+
 /** Someone about to join a tenant. */
 declare interface Joining {
     readonly email: string;
@@ -679,13 +787,14 @@ declare interface SessionRevocationOptions {
 
 /** Server-side sessions — enumeration + revocation. */
 declare interface SessionStore {
-    /** Active sessions for a user (most recent first). */
+    /** Unrotated credentials with an existing canonical root owned by the same user, most recent first. */
     readonly listSessions: (userId: string) => Effect.Effect<ReadonlyArray<SessionRecord>>;
     /** Record a session on sign-in. */
     readonly insertSession: (session: Omit<SessionRecord, 'createdAt' | 'lastSeenAt'>) => Effect.Effect<SessionRecord>;
-    /** Look up one session row by id. The request-time revocation check
-     *  (`makeSessionRevocationChecker`) calls this — a missing row means
-     *  the session was revoked. */
+    /** Look up an unrotated credential only while its canonical family root
+     * exists and belongs to the same user. A rotated root remains an anchor;
+     * its tenant does not replace the credential tenant. Custom stores must
+     * enforce this before returning a row to request-time revocation checks. */
     readonly findSession: (sessionId: string) => Effect.Effect<SessionRecord | null>;
     /** Slide a session row forward: bump `expiresAt` + `lastSeenAt`. Called
      *  when the sliding-window renewal re-issues the cookie, so the row
@@ -777,7 +886,7 @@ declare const UserNotFoundError_base: new <A extends Record<string, any> = {}>(a
 
 declare interface UserRecord {
     readonly id: string;
-    readonly email: string;
+    readonly email: string | null;
     /**
      * The stored scrypt hash — OPTIONAL, because not every identity has a
      * password. An SSO-only, magic-link-only, passkey-only, or provider-PAT