limen-auth 0.0.0 → 0.0.2-beta.0

package/dist/plugins/index.mjs

@@ -1,7 +1,8 @@
-import { i as resolveDefaultStorage, n as localStorageBearerStorage, r as memoryBearerStorage, t as bearerPlugin } from "../bearer-Cqmrmjjf.mjs";
+import { localStorageBearerStorage, memoryBearerStorage, resolveDefaultStorage } from "./bearer/storage.mjs";
+import { bearerPlugin } from "./bearer/index.mjs";
 import { credentialPasswordPlugin } from "./credential/index.mjs";
 import { magicLinkPlugin } from "./magic-link/index.mjs";
 import { oauthClientPlugin } from "./oauth/index.mjs";
-import { t as sessionJwtPlugin } from "../session-jwt-DgLdMQxP.mjs";
+import { sessionJwtPlugin } from "./session-jwt/index.mjs";
 import { twoFactorPlugin } from "./two-factor/index.mjs";
 export { bearerPlugin, credentialPasswordPlugin, localStorageBearerStorage, magicLinkPlugin, memoryBearerStorage, oauthClientPlugin, resolveDefaultStorage, sessionJwtPlugin, twoFactorPlugin };

package/dist/plugins/magic-link/index.d.mts

@@ -1,2 +1,18 @@
-import { n as RequestMagicLinkInput, r as VerifyMagicLinkInput, t as magicLinkPlugin } from "../../index-dEksIImj.mjs";
+import { RouteDescriptor } from "../../route.mjs";
+import { Session } from "../../types.mjs";
+import { ClientPlugin } from "../../define-plugin.mjs";
+import { RequestMagicLinkInput, VerifyMagicLinkInput } from "./types.mjs";
+
+//#region src/plugins/magic-link/index.d.ts
+declare function magicLinkPlugin<TFields = unknown>(): ClientPlugin<"magic-link", "/magic-link", [RouteDescriptor<RequestMagicLinkInput, {
+  message: string;
+}, {
+  readonly method: "POST";
+  readonly path: "/signin";
+}>, RouteDescriptor<VerifyMagicLinkInput, Session<TFields>, {
+  readonly method: "GET";
+  readonly path: "/verify";
+  readonly parseSession: true;
+}>], Record<never, never>>;
+//#endregion
 export { type RequestMagicLinkInput, type VerifyMagicLinkInput, magicLinkPlugin };

package/dist/plugins/magic-link/index.mjs

@@ -1,5 +1,5 @@
-import { n as defineRoutes, t as defineClientPlugin } from "../../define-plugin-C7WOGU4b.mjs";
-import { t as route } from "../../route-DGxvFqWl.mjs";
+import { defineClientPlugin, defineRoutes } from "../../define-plugin.mjs";
+import { route } from "../../route.mjs";
 //#region src/plugins/magic-link/index.ts
 function magicLinkPlugin() {
 	return defineClientPlugin({
@@ -17,5 +17,3 @@ function magicLinkPlugin() {
 }
 //#endregion
 export { magicLinkPlugin };
-
-//# sourceMappingURL=index.mjs.map

package/dist/plugins/magic-link/types.d.mts

@@ -0,0 +1,13 @@
+//#region src/plugins/magic-link/types.d.ts
+type RequestMagicLinkInput = {
+  email: string;
+  redirectUri?: string;
+  newUserRedirectUri?: string;
+  errorRedirectUri?: string;
+  meta?: Record<string, unknown>;
+};
+type VerifyMagicLinkInput = {
+  token: string;
+};
+//#endregion
+export { RequestMagicLinkInput, VerifyMagicLinkInput };

package/dist/plugins/oauth/index.d.mts

@@ -1,2 +1,48 @@
-import { a as OAuthAuthorizeResult, i as OAuthAuthorizeQuery, n as LinkOAuthInput, o as OAuthTokens, r as OAuthAccount, s as SignInOAuthInput, t as oauthClientPlugin } from "../../index-DV6YcNSu.mjs";
+import { RouteDescriptor, RouteHandler } from "../../route.mjs";
+import { ClientPlugin } from "../../define-plugin.mjs";
+import { camelizeKeys } from "../../helpers.mjs";
+import { LinkOAuthInput, OAuthAccount, OAuthAuthorizeQuery, OAuthAuthorizeResult, OAuthTokens, SignInOAuthInput } from "./types.mjs";
+
+//#region src/plugins/oauth/index.d.ts
+declare function oauthClientPlugin(): ClientPlugin<"oauth", "/oauth", [RouteDescriptor<SignInOAuthInput, OAuthAuthorizeResult, {
+  readonly method: "GET";
+  readonly path: "/:provider/authorize";
+  readonly as: "signIn.social";
+  readonly params: readonly ["provider"];
+  readonly handler: RouteHandler<SignInOAuthInput, OAuthAuthorizeResult>;
+}>, RouteDescriptor<SignInOAuthInput, OAuthAuthorizeResult, {
+  readonly method: "GET";
+  readonly path: "/:provider/link";
+  readonly as: "social.link";
+  readonly params: readonly ["provider"];
+  readonly handler: RouteHandler<SignInOAuthInput, OAuthAuthorizeResult>;
+}>, RouteDescriptor<{
+  provider: string;
+}, void, {
+  readonly method: "DELETE";
+  readonly path: "/:provider/unlink";
+  readonly as: "social.unlink";
+  readonly params: readonly ["provider"];
+}>, RouteDescriptor<void, OAuthAccount[], {
+  readonly method: "GET";
+  readonly path: "/accounts";
+  readonly as: "social.accounts";
+}>, RouteDescriptor<{
+  provider: string;
+}, OAuthTokens, {
+  readonly method: "GET";
+  readonly path: "/:provider/tokens";
+  readonly as: "social.tokens";
+  readonly params: readonly ["provider"];
+  readonly parse: typeof camelizeKeys;
+}>, RouteDescriptor<{
+  provider: string;
+}, OAuthTokens, {
+  readonly method: "POST";
+  readonly path: "/:provider/tokens/refresh";
+  readonly as: "social.refreshTokens";
+  readonly params: readonly ["provider"];
+  readonly parse: typeof camelizeKeys;
+}>], Record<never, never>>;
+//#endregion
 export { type LinkOAuthInput, type OAuthAccount, type OAuthAuthorizeQuery, type OAuthAuthorizeResult, type OAuthTokens, type SignInOAuthInput, oauthClientPlugin };

package/dist/plugins/oauth/index.mjs

@@ -1,6 +1,6 @@
-import { r as camelizeKeys } from "../../helpers-Cs3VtXdv.mjs";
-import { n as defineRoutes, t as defineClientPlugin } from "../../define-plugin-C7WOGU4b.mjs";
-import { t as route } from "../../route-DGxvFqWl.mjs";
+import { camelizeKeys } from "../../helpers.mjs";
+import { defineClientPlugin, defineRoutes } from "../../define-plugin.mjs";
+import { route } from "../../route.mjs";
 //#region src/plugins/oauth/index.ts
 const fetchThenRedirect = async (ctx, input, http) => {
 	const { disableRedirect, ...rest } = input;
@@ -52,5 +52,3 @@ function oauthClientPlugin() {
 }
 //#endregion
 export { oauthClientPlugin };
-
-//# sourceMappingURL=index.mjs.map

package/dist/plugins/oauth/types.d.mts

@@ -0,0 +1,35 @@
+//#region src/plugins/oauth/types.d.ts
+type OAuthAuthorizeQuery = {
+  /** Where the server redirects the browser after a successful callback. */redirectUri?: string; /** Where the server redirects on a failed callback. Falls back to `redirectUri`. */
+  errorRedirectUri?: string;
+};
+type SignInOAuthInput = OAuthAuthorizeQuery & {
+  /** Provider id, e.g. `"google"` or `"github"`. */provider: string;
+  /**
+   * When true, skip auto-navigation and only resolve with the authorization
+   * URL — the caller is responsible for navigating the browser.
+   */
+  disableRedirect?: boolean;
+};
+type LinkOAuthInput = SignInOAuthInput;
+type OAuthAuthorizeResult = {
+  /** Provider authorization URL. */url: string; /** Whether the SDK navigated to `url`. */
+  redirect: boolean;
+};
+type OAuthAccount = {
+  provider: string;
+  providerAccountId: string;
+  scopes: string[];
+  accessTokenExpiresAt?: string;
+  createdAt: string;
+  updatedAt: string;
+};
+type OAuthTokens = {
+  accessToken: string;
+  refreshToken?: string;
+  idToken?: string;
+  accessTokenExpiresAt?: string;
+  scope?: string;
+};
+//#endregion
+export { LinkOAuthInput, OAuthAccount, OAuthAuthorizeQuery, OAuthAuthorizeResult, OAuthTokens, SignInOAuthInput };

package/dist/plugins/session-jwt/index.d.mts

@@ -1,2 +1,25 @@
-import { n as SessionJwtPluginConfig, r as SessionJwtTokens, t as sessionJwtPlugin } from "../../index-C9EuA9UZ.mjs";
+import { RouteDescriptor } from "../../route.mjs";
+import { Session } from "../../types.mjs";
+import { ClientPlugin } from "../../define-plugin.mjs";
+import { BearerTokens } from "../bearer/types.mjs";
+import { RefreshInput, SessionJwtPluginConfig, SessionJwtTokens } from "./types.mjs";
+//#region src/plugins/session-jwt/index.d.ts
+declare function sessionJwtPlugin<TFields = unknown>(config?: SessionJwtPluginConfig): ClientPlugin<"session-jwt", "", [RouteDescriptor<RefreshInput, Session<TFields>, {
+  readonly method: "POST";
+  readonly path: "/refresh";
+  readonly parseSession: true;
+  readonly expose: false;
+}>], {
+  sessionJwt: {
+    /**
+     * Get the current access token. If the token is expiring, refresh it.
+     * @returns The current access token or null if no token is found.
+     */
+    getAccessToken: () => Promise<string | null>;
+    refresh: () => Promise<SessionJwtTokens>;
+    getTokens: () => BearerTokens | null;
+    clear: () => void;
+  };
+}>;
+//#endregion
 export { type SessionJwtPluginConfig, type SessionJwtTokens, sessionJwtPlugin };

package/dist/plugins/session-jwt/index.mjs

@@ -1,2 +1,96 @@
-import { t as sessionJwtPlugin } from "../../session-jwt-DgLdMQxP.mjs";
+import "../../constants.mjs";
+import { LimenError } from "../../errors.mjs";
+import { defineClientPlugin, defineRoutes } from "../../define-plugin.mjs";
+import { route } from "../../route.mjs";
+import { resolveDefaultStorage } from "../bearer/storage.mjs";
+import { isExpiring, tokensFromHeaders } from "./jwt.mjs";
+//#region src/plugins/session-jwt/index.ts
+function sessionJwtPlugin(config = {}) {
+	const store = config.storage ?? resolveDefaultStorage(config.storageKey ?? "limen.tokens");
+	const skewMs = (config.expirySkewSeconds ?? 30) * 1e3;
+	const refreshRoute = route()({
+		method: "POST",
+		path: "/refresh",
+		parseSession: true,
+		expose: false
+	});
+	let ctx;
+	let run;
+	let inFlight = null;
+	const runRefresh = async () => {
+		const current = store.get();
+		if (!current?.refreshToken) throw new LimenError("No refresh token found", 401, "unauthorized");
+		try {
+			await run(refreshRoute, { refreshToken: current.refreshToken });
+			const tokens = store.get();
+			if (!tokens?.accessToken) throw new LimenError("Refresh did not return a valid access token", 500, "unknown");
+			return tokens;
+		} catch (err) {
+			store.clear();
+			ctx.setSession(null);
+			throw err;
+		}
+	};
+	const refresh = () => {
+		if (!inFlight) inFlight = runRefresh().finally(() => {
+			inFlight = null;
+		});
+		return inFlight;
+	};
+	const getAccessToken = async () => {
+		const current = store.get();
+		if (!current?.accessToken) return null;
+		if (!isExpiring(current.accessToken, skewMs)) return current.accessToken;
+		if (!current.refreshToken) return null;
+		return (await refresh()).accessToken;
+	};
+	const applyAuthHeader = async (req) => {
+		if (req.headers.has("Authorization")) return;
+		const token = await getAccessToken().catch(() => null);
+		if (token) req.headers.set("Authorization", `Bearer ${token}`);
+	};
+	return defineClientPlugin({
+		id: "session-jwt",
+		routes: defineRoutes(refreshRoute),
+		actions: (pluginCtx, pluginRun) => {
+			ctx = pluginCtx;
+			run = pluginRun;
+			return { sessionJwt: {
+				/**
+				* Get the current access token. If the token is expiring, refresh it.
+				* @returns The current access token or null if no token is found.
+				*/
+				getAccessToken,
+				refresh,
+				getTokens: () => store.get(),
+				clear: () => store.clear()
+			} };
+		},
+		hooks: {
+			beforeRequest: [{
+				match: (route) => route.path !== "/refresh",
+				run: async (req) => {
+					await applyAuthHeader(req);
+					return req;
+				}
+			}],
+			afterResponse: [{
+				allowOnFailure: true,
+				run: (res) => {
+					const tokens = tokensFromHeaders(res.headers);
+					if (tokens) store.set(tokens);
+					return res;
+				}
+			}, {
+				match: ["/signout", "/revoke-sessions"],
+				allowOnFailure: true,
+				run: (res) => {
+					store.clear();
+					return res;
+				}
+			}]
+		}
+	});
+}
+//#endregion
 export { sessionJwtPlugin };

package/dist/plugins/session-jwt/jwt.mjs

@@ -0,0 +1,34 @@
+import { SET_AUTH_TOKEN_HEADER, SET_REFRESH_TOKEN_HEADER } from "../../constants.mjs";
+//#region src/plugins/session-jwt/jwt.ts
+/**
+* Read the `exp` (seconds since epoch) from a JWT without verifying its
+* signature — the server is the source of truth; the client only needs expiry
+* to decide when to refresh. Returns `null` for anything malformed.
+*/
+function decodeJwtExp(token) {
+	const payload = token.split(".")[1];
+	if (!payload) return null;
+	try {
+		const b64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+		const padded = b64 + "=".repeat((4 - b64.length % 4) % 4);
+		const claims = JSON.parse(atob(padded));
+		return typeof claims.exp === "number" ? claims.exp : null;
+	} catch {
+		return null;
+	}
+}
+function isExpiring(token, skewMs) {
+	const exp = decodeJwtExp(token);
+	if (exp === null) return true;
+	return exp * 1e3 - skewMs <= Date.now();
+}
+function tokensFromHeaders(headers) {
+	const accessToken = headers.get(SET_AUTH_TOKEN_HEADER);
+	if (!accessToken) return null;
+	const tokens = { accessToken };
+	const refreshToken = headers.get(SET_REFRESH_TOKEN_HEADER);
+	if (refreshToken) tokens.refreshToken = refreshToken;
+	return tokens;
+}
+//#endregion
+export { isExpiring, tokensFromHeaders };

package/dist/plugins/session-jwt/types.d.mts

@@ -0,0 +1,11 @@
+import { BearerPluginConfig, BearerTokens } from "../bearer/types.mjs";
+//#region src/plugins/session-jwt/types.d.ts
+type SessionJwtTokens = BearerTokens;
+type SessionJwtPluginConfig = BearerPluginConfig & {
+  /** Refresh once the access token is within this many seconds of expiry. Default 30. */expirySkewSeconds?: number;
+};
+type RefreshInput = {
+  refreshToken: string;
+};
+//#endregion
+export { RefreshInput, SessionJwtPluginConfig, SessionJwtTokens };

package/dist/plugins/two-factor/index.d.mts

@@ -1,2 +1,42 @@
-import { a as SendOTPInput, c as TwoFactorSetupURI, i as InitiateSetupInput, l as VerifyInput, n as DisableTwoFactorInput, o as TwoFactorConfig, r as FinalizeSetupInput, s as TwoFactorMethod, t as twoFactorPlugin } from "../../index-C6atwjEq.mjs";
+import { RouteDescriptor } from "../../route.mjs";
+import { Session } from "../../types.mjs";
+import { ClientPlugin } from "../../define-plugin.mjs";
+import { DisableTwoFactorInput, FinalizeSetupInput, InitiateSetupInput, SendOTPInput, TwoFactorConfig, TwoFactorMethod, TwoFactorSetupURI, VerifyInput } from "./types.mjs";
+
+//#region src/plugins/two-factor/index.d.ts
+declare function twoFactorPlugin<TFields = unknown>(config: TwoFactorConfig): ClientPlugin<"two-factor", "/two-factor", [RouteDescriptor<InitiateSetupInput, TwoFactorSetupURI, {
+  readonly method: "POST";
+  readonly path: "/initiate-setup";
+}>, RouteDescriptor<FinalizeSetupInput, Session<TFields>, {
+  readonly method: "POST";
+  readonly path: "/finalize-setup";
+  readonly parseSession: true;
+}>, RouteDescriptor<DisableTwoFactorInput, Session<TFields>, {
+  readonly method: "POST";
+  readonly path: "/disable";
+  readonly parseSession: true;
+}>, RouteDescriptor<VerifyInput, Session<TFields>, {
+  readonly method: "POST";
+  readonly path: "/verify";
+  readonly parseSession: true;
+}>, RouteDescriptor<void, TwoFactorSetupURI, {
+  readonly method: "GET";
+  readonly path: "/totp/uri";
+  readonly as: "twoFactor.getTotpUri";
+}>, RouteDescriptor<void, string[], {
+  readonly method: "GET";
+  readonly path: "/backup-codes";
+  readonly as: "twoFactor.getBackupCodes";
+}>, RouteDescriptor<void, string[], {
+  readonly method: "PUT";
+  readonly path: "/backup-codes";
+  readonly as: "twoFactor.regenerateBackupCodes";
+}>, RouteDescriptor<SendOTPInput, {
+  message: string;
+}, {
+  readonly method: "POST";
+  readonly path: "/otp/send";
+  readonly as: "twoFactor.sendOTP";
+}>], Record<never, never>>;
+//#endregion
 export { type DisableTwoFactorInput, type FinalizeSetupInput, type InitiateSetupInput, type SendOTPInput, type TwoFactorConfig, type TwoFactorMethod, type TwoFactorSetupURI, type VerifyInput, twoFactorPlugin };

package/dist/plugins/two-factor/index.mjs

@@ -1,5 +1,5 @@
-import { n as defineRoutes, t as defineClientPlugin } from "../../define-plugin-C7WOGU4b.mjs";
-import { t as route } from "../../route-DGxvFqWl.mjs";
+import { defineClientPlugin, defineRoutes } from "../../define-plugin.mjs";
+import { route } from "../../route.mjs";
 //#region src/plugins/two-factor/index.ts
 function twoFactorPlugin(config) {
 	return defineClientPlugin({
@@ -48,5 +48,3 @@ function twoFactorPlugin(config) {
 }
 //#endregion
 export { twoFactorPlugin };
-
-//# sourceMappingURL=index.mjs.map

package/dist/plugins/two-factor/types.d.mts

@@ -0,0 +1,26 @@
+//#region src/plugins/two-factor/types.d.ts
+type TwoFactorConfig = {
+  /** Called when sign-in requires a two-factor challenge. */onTwoFactorRedirect: () => void;
+};
+type VerifyInput = {
+  code: string;
+  method?: TwoFactorMethod;
+};
+type InitiateSetupInput = {
+  password: string;
+};
+type FinalizeSetupInput = {
+  code: string;
+};
+type DisableTwoFactorInput = {
+  password: string;
+};
+type SendOTPInput = {
+  email: string;
+};
+type TwoFactorSetupURI = {
+  uri: string;
+};
+type TwoFactorMethod = "totp" | "otp";
+//#endregion
+export { DisableTwoFactorInput, FinalizeSetupInput, InitiateSetupInput, SendOTPInput, TwoFactorConfig, TwoFactorMethod, TwoFactorSetupURI, VerifyInput };

package/dist/react/index.d.mts

@@ -1,9 +1,9 @@
-import { D as User, E as Session, O as SessionState, V as Prettify, _ as AuthClient, k as SessionStore, t as AnyClientPlugin, y as CreateAuthClientOptions } from "../define-plugin-Dv0xXIaH.mjs";
-import { Store, StoreValue } from "nanostores";
+import { Prettify } from "../type-utils.mjs";
+import { SessionState, SessionStore } from "../session-store.mjs";
+import { AuthClient, CreateAuthClientOptions, Session, User } from "../types.mjs";
+import { AnyClientPlugin } from "../define-plugin.mjs";
+import { useStore } from "./react-store.mjs";
 
-//#region src/react/react-store.d.ts
-declare function useStore<SomeStore extends Store>(store: SomeStore): StoreValue<SomeStore>;
-//#endregion
 //#region src/react/index.d.ts
 /**
  * An {@link AuthClient} augmented with React hooks.
@@ -20,5 +20,4 @@ type ReactAuthClient<Plugins extends readonly AnyClientPlugin[], TFields = unkno
  */
 declare function createAuthClient<const Plugins extends readonly AnyClientPlugin[] = readonly [], TFields = unknown>(opts: CreateAuthClientOptions<Plugins, TFields>): ReactAuthClient<Plugins, TFields>;
 //#endregion
-export { type AuthClient, type CreateAuthClientOptions, ReactAuthClient, type Session, type SessionState, type SessionStore, type User, createAuthClient, useStore };
-//# sourceMappingURL=index.d.mts.map
+export { type AuthClient, type CreateAuthClientOptions, ReactAuthClient, type Session, type SessionState, type SessionStore, type User, createAuthClient, useStore };

package/dist/react/index.mjs

@@ -1,21 +1,5 @@
-import { t as createAuthClient$1 } from "../client-Er91De-z.mjs";
-import { useCallback, useRef, useSyncExternalStore } from "react";
-//#region src/react/react-store.ts
-function useStore(store) {
-	const snapshotRef = useRef(store.get());
-	const subscribe = useCallback((onChange) => {
-		const emitValue = (value) => {
-			if (snapshotRef.current === value) return;
-			snapshotRef.current = value;
-			onChange();
-		};
-		emitValue(store.value);
-		return store.listen(emitValue);
-	}, [store]);
-	const get = () => snapshotRef.current;
-	return useSyncExternalStore(subscribe, get, get);
-}
-//#endregion
+import { createAuthClient as createAuthClient$1 } from "../client.mjs";
+import { useStore } from "./react-store.mjs";
 //#region src/react/index.ts
 /**
 * Create a Limen auth client with React hooks attached.
@@ -27,5 +11,3 @@ function createAuthClient(opts) {
 }
 //#endregion
 export { createAuthClient, useStore };
-
-//# sourceMappingURL=index.mjs.map

package/dist/react/react-store.d.mts

@@ -0,0 +1,6 @@
+import { Store, StoreValue } from "nanostores";
+
+//#region src/react/react-store.d.ts
+declare function useStore<SomeStore extends Store>(store: SomeStore): StoreValue<SomeStore>;
+//#endregion
+export { useStore };

package/dist/react/react-store.mjs

@@ -0,0 +1,18 @@
+import { useCallback, useRef, useSyncExternalStore } from "react";
+//#region src/react/react-store.ts
+function useStore(store) {
+	const snapshotRef = useRef(store.get());
+	const subscribe = useCallback((onChange) => {
+		const emitValue = (value) => {
+			if (snapshotRef.current === value) return;
+			snapshotRef.current = value;
+			onChange();
+		};
+		emitValue(store.value);
+		return store.listen(emitValue);
+	}, [store]);
+	const get = () => snapshotRef.current;
+	return useSyncExternalStore(subscribe, get, get);
+}
+//#endregion
+export { useStore };

package/dist/route.d.mts

@@ -0,0 +1,80 @@
+import { LimenError } from "./errors.mjs";
+import { HTTPMethod } from "./types.mjs";
+import { RouteContext } from "./context.mjs";
+
+//#region src/route.d.ts
+declare const INPUT: unique symbol;
+declare const OUTPUT: unique symbol;
+/**
+ * Runs the route's default HTTP request and parser without session effects.
+ * Pass an input override when a handler needs to omit client-only fields.
+ */
+type HttpRunner<I> = <R = unknown>(input?: I) => Promise<R>;
+/**
+ * Custom route behavior for flows that need more than the default request
+ * pipeline.
+ */
+type RouteHandler<I, O, TFields = unknown> = (ctx: RouteContext<TFields>, input: I, http: HttpRunner<I>) => Promise<O>;
+/**
+ * Per-call options accepted as the final argument of every generated route
+ * method.
+ */
+type RouteCallOptions<O = unknown> = {
+  /** Invoked with the resolved value after the call succeeds. */onSuccess?: (data: O) => void; /** Invoked with the error just before it is re-thrown. */
+  onError?: (error: LimenError) => void;
+};
+/**
+ * Declarative client route definition. The public client chain is derived from
+ * `path` unless `as` is provided.
+ */
+type RouteDef<I, O> = {
+  method: HTTPMethod;
+  path: `/${string}`; /** Dotted client chain override, e.g. `"twoFactor.getTotpUri"`. */
+  as?: string; /** Merged under the caller's input before serialization. */
+  defaults?: Partial<I>; /** SDK input → wire body/query. Defaults to shallow camelCase → snake_case. */
+  serialize?: (input: I) => unknown; /** Raw response → typed output. Ignored when `parseSession` is set. */
+  parse?: (raw: unknown) => O;
+  /**
+   * Parse the response as a session and store it when it contains a `user`.
+   * Set `skipStore` to return the parsed session without writing it.
+   */
+  parseSession?: boolean; /** Resolve `path` from the client base path instead of the plugin base path. */
+  absolute?: boolean; /** Input keys used as `:param` path values. */
+  params?: readonly (keyof I & string)[]; /** For `parseSession` routes, skip the session-store write. */
+  skipStore?: boolean; /** Clear the session store on success. */
+  clearSession?: boolean; /** Revalidate the session after success. */
+  refetchSession?: boolean; /** Set `false` to keep the route out of the public client API. */
+  expose?: boolean; /** Override the default route call behavior. */
+  handler?: RouteHandler<I, O>;
+};
+/**
+ * A route definition carrying its input and output types for inference.
+ */
+type RouteDescriptor<I, O, D extends RouteDef<I, O> = RouteDef<I, O>> = D & {
+  readonly [INPUT]: I;
+  readonly [OUTPUT]: O;
+};
+/**
+ * Loose route-descriptor constraint for route tuples and plugin definitions.
+ */
+type AnyRouteDescriptor = RouteDescriptor<any, any, any>;
+type InputOf<R> = R extends {
+  readonly [INPUT]: infer I;
+} ? I : never;
+type OutputOf<R> = R extends {
+  readonly [OUTPUT]: infer O;
+} ? O : never;
+/**
+ * Define an HTTP-backed client method for a plugin. The input/output types
+ * become the generated method's argument and resolved value.
+ *
+ * @example
+ *   route<VerifyInput, Session<TFields>>()({
+ *     method: "POST",
+ *     path: "/verify",
+ *     parseSession: true,
+ *   })
+ */
+declare function route<I = void, O = unknown>(): <const D extends RouteDef<I, O>>(def: D) => RouteDescriptor<I, O, D>;
+//#endregion
+export { AnyRouteDescriptor, InputOf, OutputOf, RouteCallOptions, RouteDescriptor, RouteHandler, route };

package/dist/{route-DGxvFqWl.mjs → route.mjs}

@@ -14,6 +14,4 @@ function route() {
 	return (def) => def;
 }
 //#endregion
-export { route as t };
-
-//# sourceMappingURL=route-DGxvFqWl.mjs.map
+export { route };

package/dist/routes.d.mts

@@ -0,0 +1,53 @@
+import { RouteDescriptor } from "./route.mjs";
+import { Session } from "./types.mjs";
+import { ClientPlugin, InferPluginContribution } from "./define-plugin.mjs";
+
+//#region src/routes.d.ts
+type VerifyEmailInput = {
+  token: string;
+};
+type ActiveSession = {
+  id: string | number;
+  token: string;
+  userId: unknown;
+  createdAt: string;
+  expiresAt: string;
+  lastAccess: string;
+  metadata?: Record<string, unknown>;
+};
+/**
+ * Core routes available on every client.
+ */
+declare function coreClientPlugin<TFields = unknown>(): ClientPlugin<"core", "/", [RouteDescriptor<void, ActiveSession[], {
+  readonly method: "GET";
+  readonly path: "/sessions";
+}>, RouteDescriptor<void, void, {
+  readonly method: "POST";
+  readonly path: "/signout";
+  readonly clearSession: true;
+}>, RouteDescriptor<void, void, {
+  readonly method: "POST";
+  readonly path: "/revoke-sessions";
+  readonly clearSession: true;
+}>, RouteDescriptor<VerifyEmailInput, string, {
+  readonly method: "POST";
+  readonly path: "/verify-email";
+  readonly refetchSession: true;
+}>, RouteDescriptor<void, string, {
+  readonly method: "POST";
+  readonly path: "/email-verifications";
+  readonly as: "requestEmailVerification";
+}>], {
+  /**
+   * Revalidate session state with `GET /me`, update `$session`, and return the
+   * resolved value (`null` when signed out).
+   *
+   * Prefer subscribing to `$session` for reactive UI state (`data`, `isPending`,
+   * `error`). Use `getSession()` when you need an awaited server re-check, such
+   * as route guards or SSR revalidation after `initialSession`.
+   */
+  getSession: () => Promise<Session<TFields> | null>;
+}>;
+type CoreContribution<TFields = unknown> = InferPluginContribution<ReturnType<typeof coreClientPlugin<TFields>>>;
+//#endregion
+export { ActiveSession, CoreContribution, VerifyEmailInput, coreClientPlugin };