peta-auth 0.1.2 → 0.2.0

package/README.md

@@ -157,11 +157,21 @@ Without a generic parameter, session data defaults to `Record<string, unknown>`.
 
 ### `requireSession()` guard
 
-Returns 401 if the session has no user data. Works per-framework:
+Returns 401 if the session has no user data. Optionally checks a specific session key:
 
-- **Hono**: `app.use('/protected/*', requireSession())` — middleware, path-patterned
+```ts
+// Guard on any session data
+app.use('/api/*', requireSession())
+
+// Guard on a specific key (e.g. session.userId must be truthy)
+app.use('/admin/*', requireSession('userId'))
+```
+
+Works per-framework:
+
+- **Hono**: `app.use('/protected/*', requireSession())` — path-patterned middleware
 - **Elysia**: `app.use(requireSession())` — guards all routes defined after it
-- **Nuxt**: `requireSession(event, session)` — throws `createError({ statusCode: 401 })`
+- **Nuxt**: `requireSession(event, session)` or `requireSession(event, session, 'userId')` — throws `createError({ statusCode: 401 })`
 
 ### Session object
 
@@ -354,7 +364,7 @@ Session data is serialized, encrypted with AES-256-CBC, integrity-protected with
 ## Scripts
 
 ```bash
-bun test            # 65 tests across 12 files
+bun test            # 74 tests across 12 files
 bun run build       # tsdown → dist/ (21 files, 30 kB)
 bun run prepublish  # build + publish
 ```

package/dist/crypto-DR-ETdLZ.d.mts

@@ -0,0 +1,35 @@
+//#region src/crypto.d.ts
+/** A password that can be a plain string or a versioned map. */
+type Password = string | Record<string, string>;
+/**
+ * Seal arbitrary data with a password (uses iron-webcrypto).
+ *
+ * @example
+ * ```ts
+ * const sealed = await sealData({ userId: 1 }, { password: "my-secret-key" })
+ * ```
+ */
+declare const sealData: (data: unknown, {
+  password,
+  ttl
+}: {
+  password: Password;
+  ttl?: number;
+}) => Promise<string>;
+/**
+ * Unseal data previously sealed with {@link sealData}.
+ *
+ * @example
+ * ```ts
+ * const data = await unsealData<{ userId: number }>(sealed, { password: "my-secret-key" })
+ * ```
+ */
+declare const unsealData: <T>(seal: string, {
+  password,
+  ttl
+}: {
+  password: Password;
+  ttl?: number;
+}) => Promise<T>;
+//#endregion
+export { sealData as n, unsealData as r, Password as t };

package/dist/crypto-WcFV83Nz.mjs

@@ -0,0 +1,84 @@
+import { defaults, seal, unseal } from "iron-webcrypto";
+//#region src/crypto.ts
+const SEVEN_DAYS = 336 * 3600;
+const CURRENT_MAJOR_VERSION = 2;
+const VERSION_DELIMITER = "~";
+function normalizePassword(password) {
+	return typeof password === "string" ? { 1: password } : password;
+}
+function parseSeal(seal) {
+	const index = seal.lastIndexOf(VERSION_DELIMITER);
+	if (index === -1) return {
+		sealWithoutVersion: seal,
+		tokenVersion: null
+	};
+	return {
+		sealWithoutVersion: seal.slice(0, index),
+		tokenVersion: parseInt(seal.slice(index + 1), 10) || null
+	};
+}
+/**
+* Create a `sealData` function.
+*
+* @internal
+*/
+function createSealData() {
+	return async function sealData(data, { password, ttl = SEVEN_DAYS }) {
+		const map = normalizePassword(password);
+		const id = Math.max(...Object.keys(map).map(Number)).toString();
+		const secret = map[id];
+		return `${await seal(data, {
+			id,
+			secret
+		}, {
+			...defaults,
+			ttl: ttl * 1e3,
+			encode: JSON.stringify,
+			decode: JSON.parse
+		})}${VERSION_DELIMITER}${CURRENT_MAJOR_VERSION}`;
+	};
+}
+/**
+* Create an `unsealData` function.
+*
+* @internal
+*/
+function createUnsealData() {
+	return async function unsealData(seal, { password, ttl = SEVEN_DAYS }) {
+		const map = normalizePassword(password);
+		const { sealWithoutVersion, tokenVersion } = parseSeal(seal);
+		try {
+			const data = await unseal(sealWithoutVersion, map, {
+				...defaults,
+				ttl: ttl * 1e3,
+				encode: JSON.stringify,
+				decode: JSON.parse
+			});
+			if (tokenVersion === 2) return data;
+			return { ...data?.persistent ? { ...data.persistent } : {} };
+		} catch (err) {
+			if (err instanceof Error && /^(Expired seal|Bad hmac value|Cannot find password|Incorrect number of sealed components)/.test(err.message)) return {};
+			throw err;
+		}
+	};
+}
+/**
+* Seal arbitrary data with a password (uses iron-webcrypto).
+*
+* @example
+* ```ts
+* const sealed = await sealData({ userId: 1 }, { password: "my-secret-key" })
+* ```
+*/
+const sealData = createSealData();
+/**
+* Unseal data previously sealed with {@link sealData}.
+*
+* @example
+* ```ts
+* const data = await unsealData<{ userId: number }>(sealed, { password: "my-secret-key" })
+* ```
+*/
+const unsealData = createUnsealData();
+//#endregion
+export { sealData as n, unsealData as r, normalizePassword as t };

package/dist/csrf.d.mts

@@ -1,10 +1,39 @@
-import { t as IronSession } from "./session-z20gaFVT.mjs";
+import { t as IronSession } from "./session-0bF8_7Ui.mjs";
 
 //#region src/csrf.d.ts
+/** Options for CSRF token generation / validation. */
 interface CSRFOptions {
+  /** Key used to store the token in the session (default `"_csrfToken"`). */
   key?: string;
 }
+/**
+ * Constant-time string comparison to prevent timing side-channel attacks.
+ * Always iterates over the full length of the input, regardless of where
+ * the first difference occurs.
+ */
+declare function constantTimeEqual(a: string, b: string): boolean;
+/**
+ * Generate a CSRF token and store it in the session.
+ *
+ * @example
+ * ```ts
+ * const token = await generateCsrf(session)
+ * // send `token` to the client via form field or header
+ * ```
+ */
 declare function generateCsrf(session: IronSession, options?: CSRFOptions): Promise<string>;
+/**
+ * Validate a CSRF token against the value stored in the session.
+ *
+ * Uses constant-time comparison to prevent timing side-channel attacks.
+ *
+ * @example
+ * ```ts
+ * if (!validateCsrf(session, submittedToken)) {
+ *   // reject request
+ * }
+ * ```
+ */
 declare function validateCsrf(session: IronSession, token: string, options?: CSRFOptions): boolean;
 //#endregion
-export { CSRFOptions, generateCsrf, validateCsrf };
+export { CSRFOptions, constantTimeEqual, generateCsrf, validateCsrf };

package/dist/csrf.mjs

@@ -1,13 +1,45 @@
 //#region src/csrf.ts
+/**
+* Constant-time string comparison to prevent timing side-channel attacks.
+* Always iterates over the full length of the input, regardless of where
+* the first difference occurs.
+*/
+function constantTimeEqual(a, b) {
+	if (a.length !== b.length) return false;
+	let result = 0;
+	for (let i = 0; i < a.length; i++) result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return result === 0;
+}
+/**
+* Generate a CSRF token and store it in the session.
+*
+* @example
+* ```ts
+* const token = await generateCsrf(session)
+* // send `token` to the client via form field or header
+* ```
+*/
 async function generateCsrf(session, options) {
 	const key = options?.key ?? "_csrfToken";
 	const token = crypto.randomUUID();
 	session[key] = token;
 	return token;
 }
+/**
+* Validate a CSRF token against the value stored in the session.
+*
+* Uses constant-time comparison to prevent timing side-channel attacks.
+*
+* @example
+* ```ts
+* if (!validateCsrf(session, submittedToken)) {
+*   // reject request
+* }
+* ```
+*/
 function validateCsrf(session, token, options) {
 	const stored = session[options?.key ?? "_csrfToken"];
-	return typeof stored === "string" && stored === token;
+	return typeof stored === "string" && constantTimeEqual(stored, token);
 }
 //#endregion
-export { generateCsrf, validateCsrf };
+export { constantTimeEqual, generateCsrf, validateCsrf };

package/dist/elysia.d.mts

@@ -1,7 +1,16 @@
-import { r as SessionOptions, t as IronSession } from "./session-z20gaFVT.mjs";
+import { r as SessionOptions, t as IronSession } from "./session-0bF8_7Ui.mjs";
 import { Elysia } from "elysia";
 
 //#region src/elysia.d.ts
+/**
+ * Elysia plugin that provides a session via the `session` store property.
+ *
+ * @example
+ * ```ts
+ * app.use(session({ password: "...", cookieName: "my-session" }))
+ * app.get("/me", ({ session }) => session)
+ * ```
+ */
 declare function session<T extends Record<string, unknown> = Record<string, unknown>>(options: SessionOptions): Elysia<"", {
   decorator: {};
   store: {};
@@ -34,35 +43,19 @@ declare function session<T extends Record<string, unknown> = Record<string, unkn
   standaloneSchema: {};
   response: {};
 }>;
-declare function requireSession(): (app: Elysia) => Elysia<"", {
-  decorator: {};
-  store: {};
-  derive: {};
-  resolve: {};
-}, {
-  typebox: {};
-  error: {};
-}, {
-  schema: {};
-  standaloneSchema: {};
-  macro: {};
-  macroFn: {};
-  parser: {};
-  response: {};
-}, {}, {
-  derive: {};
-  resolve: {};
-  schema: {};
-  standaloneSchema: {};
-  response: {};
-}, {
-  derive: {};
-  resolve: {};
-  schema: {};
-  standaloneSchema: {};
-  response: {
-    200: Response;
-  };
-}>;
+/**
+ * Elysia guard (onBeforeHandle) that requires session data.
+ *
+ * Returns 401 when the session is empty.
+ *
+ * @example
+ * ```ts
+ * app.guard({ beforeHandle: requireSession() }, (app) =>
+ *   app.get("/admin", () => "ok")
+ * )
+ * ```
+ */
+declare function requireSession(): (app: Elysia) => Elysia;
+declare function requireSession<K extends string>(key: K): (app: Elysia) => Elysia;
 //#endregion
 export { requireSession, session };

package/dist/elysia.mjs

@@ -1,22 +1,31 @@
-import { t as createSessionFromAdapter } from "./session-DSwf3XPH.mjs";
+import { n as sessionHasData, t as createSessionFromAdapter } from "./session-BGCQ1Z1Q.mjs";
 import { parse } from "cookie";
 import { Elysia } from "elysia";
 //#region src/elysia.ts
+/**
+* Elysia plugin that provides a session via the `session` store property.
+*
+* @example
+* ```ts
+* app.use(session({ password: "...", cookieName: "my-session" }))
+* app.get("/me", ({ session }) => session)
+* ```
+*/
 function session(options) {
-	return new Elysia({ name: "peta-auth" }).derive({ as: "scoped" }, async ({ headers: reqHeaders, set }) => {
-		const cookieStr = reqHeaders instanceof Headers ? reqHeaders.get("cookie") ?? "" : reqHeaders.cookie ?? "";
+	return new Elysia({ name: "peta-auth" }).derive({ as: "scoped" }, async ({ headers, set }) => {
+		const cookieString = headers instanceof Headers ? headers.get("cookie") ?? "" : headers.cookie ?? "";
 		return { session: await createSessionFromAdapter({
-			getCookie: (name) => parse(cookieStr)[name],
-			setCookie: (v) => {
-				set.headers["Set-Cookie"] = v;
+			getCookie: (name) => parse(cookieString)[name],
+			setCookie: (value) => {
+				set.headers["Set-Cookie"] = value;
 			}
 		}, options) };
 	});
 }
-function requireSession() {
+function requireSession(key) {
 	return (app) => app.onBeforeHandle((context) => {
 		const session = context.session;
-		if (!Object.keys(session).some((k) => k !== "save" && k !== "destroy" && k !== "updateConfig")) return new Response(JSON.stringify({ error: "unauthorized" }), {
+		if (!sessionHasData(session, key)) return new Response(JSON.stringify({ error: "unauthorized" }), {
 			status: 401,
 			headers: { "Content-Type": "application/json" }
 		});

package/dist/errors-DxJ-WUJL.mjs

@@ -0,0 +1,17 @@
+//#region src/errors.ts
+/**
+* Typed error for peta-auth.
+*
+* Carries a machine-readable `code` and a human-readable `message`.
+* Thrown instead of raw `new Error(...)` throughout the library.
+*/
+var PetaAuthError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "PetaAuthError";
+		this.code = code;
+	}
+};
+//#endregion
+export { PetaAuthError as t };

package/dist/hono.d.mts

@@ -1,12 +1,34 @@
-import { r as SessionOptions, t as IronSession } from "./session-z20gaFVT.mjs";
+import { r as SessionOptions, t as IronSession } from "./session-0bF8_7Ui.mjs";
 import { MiddlewareHandler } from "hono";
 
 //#region src/hono.d.ts
+/**
+ * Hono middleware that creates a session and makes it available
+ * via `c.var.session`.
+ *
+ * @example
+ * ```ts
+ * app.use("*", session({ password: "...", cookieName: "my-session" }))
+ * app.get("/me", (c) => c.json(c.var.session))
+ * ```
+ */
 declare function session<T extends Record<string, unknown> = Record<string, unknown>>(options: SessionOptions): MiddlewareHandler<{
   Variables: {
     session: T & IronSession;
   };
 }>;
+/**
+ * Hono middleware that guards a route by requiring session data.
+ *
+ * Returns 401 when the session is empty.
+ *
+ * @example
+ * ```ts
+ * app.use("/admin", requireSession())
+ * app.use("/admin", requireSession("role"))
+ * ```
+ */
 declare function requireSession(): MiddlewareHandler;
+declare function requireSession<K extends string>(key: K): MiddlewareHandler;
 //#endregion
 export { requireSession, session };

package/dist/hono.mjs

@@ -1,20 +1,30 @@
-import { t as createSessionFromAdapter } from "./session-DSwf3XPH.mjs";
+import { n as sessionHasData, t as createSessionFromAdapter } from "./session-BGCQ1Z1Q.mjs";
 import { parse } from "cookie";
 import { createMiddleware } from "hono/factory";
 //#region src/hono.ts
+/**
+* Hono middleware that creates a session and makes it available
+* via `c.var.session`.
+*
+* @example
+* ```ts
+* app.use("*", session({ password: "...", cookieName: "my-session" }))
+* app.get("/me", (c) => c.json(c.var.session))
+* ```
+*/
 function session(options) {
 	return createMiddleware(async (c, next) => {
 		c.set("session", await createSessionFromAdapter({
 			getCookie: (name) => parse(c.req.header("cookie") ?? "")[name],
-			setCookie: (v) => c.res.headers.append("Set-Cookie", v)
+			setCookie: (value) => c.res.headers.append("Set-Cookie", value)
 		}, options));
 		await next();
 	});
 }
-function requireSession() {
+function requireSession(key) {
 	return createMiddleware(async (c, next) => {
 		const s = c.var.session;
-		if (!Object.keys(s).some((k) => k !== "save" && k !== "destroy" && k !== "updateConfig")) return c.json({ error: "unauthorized" }, 401);
+		if (!sessionHasData(s, key)) return c.json({ error: "unauthorized" }, 401);
 		await next();
 	});
 }

package/dist/index.d.mts

@@ -1,27 +1,81 @@
-import { n as sealData, r as unsealData, t as Password } from "./crypto-Ln_Mj_zp.mjs";
-import { i as createSessionFromAdapter, n as SessionAdapter, r as SessionOptions, t as IronSession } from "./session-z20gaFVT.mjs";
+import { n as sealData, r as unsealData, t as Password } from "./crypto-DR-ETdLZ.mjs";
+import { i as createSessionFromAdapter, n as SessionAdapter, r as SessionOptions, t as IronSession } from "./session-0bF8_7Ui.mjs";
 import { CSRFOptions, generateCsrf, validateCsrf } from "./csrf.mjs";
 import { JWTOptions, signJWT, verifyJWT } from "./jwt.mjs";
 
+//#region src/errors.d.ts
+/**
+ * Typed error for peta-auth.
+ *
+ * Carries a machine-readable `code` and a human-readable `message`.
+ * Thrown instead of raw `new Error(...)` throughout the library.
+ */
+declare class PetaAuthError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string);
+}
+//#endregion
 //#region src/password.d.ts
 interface HashOptions {
-  cost?: number;
+  /** Memory cost in KiB (default: 19456 = 19 MiB). */
+  memoryCost?: number;
+  /** Time cost (iterations) (default: 2). */
+  timeCost?: number;
+  /** Parallelism (default: 1). */
+  parallelism?: number;
 }
+/**
+ * Hash a password with argon2id.
+ *
+ * @example
+ * ```ts
+ * const hash = await hashPassword("my-password")
+ * ```
+ */
 declare function hashPassword(password: string, options?: HashOptions): Promise<string>;
+/**
+ * Verify a password against an argon2id hash.
+ *
+ * @example
+ * ```ts
+ * const ok = await verifyPassword(hash, "my-password")
+ * ```
+ */
 declare function verifyPassword(hash: string, password: string): Promise<boolean>;
 //#endregion
 //#region src/reset-password.d.ts
+/** Options for password reset token generation. */
 interface PasswordResetOptions {
+  /** Password(s) used to sign the reset token. */
   password: Password;
-  exp?: number;
+  /** Token lifetime in seconds (default 1 hour). */
+  expiresIn?: number;
 }
+/**
+ * Create a password-reset token for a user.
+ *
+ * @example
+ * ```ts
+ * const token = await createPasswordResetToken(userId, { password: "..." })
+ * ```
+ */
 declare function createPasswordResetToken(userId: string, options: PasswordResetOptions): Promise<string>;
+/**
+ * Verify a password-reset token.
+ *
+ * Returns the user ID when the token is valid, or `null` if expired/invalid.
+ */
 declare function verifyPasswordResetToken(token: string, password: Password): Promise<{
   userId: string;
 } | null>;
+/**
+ * Verify a password-reset token and apply the new password.
+ *
+ * Returns `{ userId, hash }` on success, or `null` if the token is invalid.
+ */
 declare function resetPassword(token: string, newPassword: string, password: Password): Promise<{
   userId: string;
   hash: string;
 } | null>;
 //#endregion
-export { type CSRFOptions, type IronSession, type JWTOptions, type Password, type PasswordResetOptions, type SessionAdapter, type SessionOptions, createPasswordResetToken, createSessionFromAdapter, generateCsrf, hashPassword, resetPassword, sealData, signJWT, unsealData, validateCsrf, verifyJWT, verifyPassword, verifyPasswordResetToken };
+export { type CSRFOptions, type IronSession, type JWTOptions, type Password, type PasswordResetOptions, PetaAuthError, type SessionAdapter, type SessionOptions, createPasswordResetToken, createSessionFromAdapter, generateCsrf, hashPassword, resetPassword, sealData, signJWT, unsealData, validateCsrf, verifyJWT, verifyPassword, verifyPasswordResetToken };

package/dist/index.mjs

@@ -1,31 +1,79 @@
-import { n as sealData, r as unsealData, t as createSessionFromAdapter } from "./session-DSwf3XPH.mjs";
+import { n as sealData, r as unsealData } from "./crypto-WcFV83Nz.mjs";
 import { generateCsrf, validateCsrf } from "./csrf.mjs";
+import { t as PetaAuthError } from "./errors-DxJ-WUJL.mjs";
 import { signJWT, verifyJWT } from "./jwt.mjs";
-import { compareSync, genSaltSync, hashSync } from "bcryptjs";
+import { t as createSessionFromAdapter } from "./session-BGCQ1Z1Q.mjs";
+import { hash, verify } from "@node-rs/argon2";
 //#region src/password.ts
+const ARGON2_MEMORY_COST = 19456;
+const ARGON2_TIME_COST = 2;
+const ARGON2_PARALLELISM = 1;
+/**
+* Hash a password with argon2id.
+*
+* @example
+* ```ts
+* const hash = await hashPassword("my-password")
+* ```
+*/
 async function hashPassword(password, options = {}) {
-	return hashSync(password, genSaltSync(options.cost ?? 10));
+	return hash(password, {
+		algorithm: 2,
+		memoryCost: options.memoryCost ?? ARGON2_MEMORY_COST,
+		timeCost: options.timeCost ?? ARGON2_TIME_COST,
+		parallelism: options.parallelism ?? ARGON2_PARALLELISM
+	});
 }
+/**
+* Verify a password against an argon2id hash.
+*
+* @example
+* ```ts
+* const ok = await verifyPassword(hash, "my-password")
+* ```
+*/
 async function verifyPassword(hash, password) {
-	return compareSync(password, hash);
+	try {
+		return await verify(hash, password);
+	} catch {
+		return false;
+	}
 }
 //#endregion
 //#region src/reset-password.ts
-const DEFAULT_EXPIRY = 3600;
+const DEFAULT_EXPIRES_IN = 3600;
+/**
+* Create a password-reset token for a user.
+*
+* @example
+* ```ts
+* const token = await createPasswordResetToken(userId, { password: "..." })
+* ```
+*/
 async function createPasswordResetToken(userId, options) {
 	return signJWT({
 		userId,
 		purpose: "password-reset"
 	}, {
 		password: options.password,
-		exp: options.exp ?? DEFAULT_EXPIRY
+		expiresIn: options.expiresIn ?? DEFAULT_EXPIRES_IN
 	});
 }
+/**
+* Verify a password-reset token.
+*
+* Returns the user ID when the token is valid, or `null` if expired/invalid.
+*/
 async function verifyPasswordResetToken(token, password) {
 	const payload = await verifyJWT(token, { password });
-	if (!payload || payload.purpose !== "password-reset") return null;
+	if (payload?.purpose !== "password-reset") return null;
 	return { userId: payload.userId };
 }
+/**
+* Verify a password-reset token and apply the new password.
+*
+* Returns `{ userId, hash }` on success, or `null` if the token is invalid.
+*/
 async function resetPassword(token, newPassword, password) {
 	const payload = await verifyPasswordResetToken(token, password);
 	if (!payload) return null;
@@ -35,4 +83,4 @@ async function resetPassword(token, newPassword, password) {
 	};
 }
 //#endregion
-export { createPasswordResetToken, createSessionFromAdapter, generateCsrf, hashPassword, resetPassword, sealData, signJWT, unsealData, validateCsrf, verifyJWT, verifyPassword, verifyPasswordResetToken };
+export { PetaAuthError, createPasswordResetToken, createSessionFromAdapter, generateCsrf, hashPassword, resetPassword, sealData, signJWT, unsealData, validateCsrf, verifyJWT, verifyPassword, verifyPasswordResetToken };

package/dist/jwt.d.mts

@@ -1,11 +1,32 @@
-import { t as Password } from "./crypto-Ln_Mj_zp.mjs";
+import { t as Password } from "./crypto-DR-ETdLZ.mjs";
 
 //#region src/jwt.d.ts
+/** Options for JWT sign / verify operations. */
 interface JWTOptions {
+  /** Password used to sign the JWT. */
   password: Password;
-  exp?: number;
+  /** Time-to-live in seconds from now. */
+  expiresIn?: number;
 }
+/**
+ * Sign a JWT payload.
+ *
+ * @example
+ * ```ts
+ * const token = await signJWT({ userId: "abc" }, { password: "my-32-char-secret...", expiresIn: 3600 })
+ * ```
+ */
 declare function signJWT(payload: Record<string, unknown>, options: JWTOptions): Promise<string>;
+/**
+ * Verify and decode a JWT.
+ *
+ * Returns `null` when the token is invalid or expired.
+ *
+ * @example
+ * ```ts
+ * const payload = await verifyJWT<{ userId: string }>(token, { password: "my-32-char-secret..." })
+ * ```
+ */
 declare function verifyJWT<T = Record<string, unknown>>(token: string, options: JWTOptions): Promise<T | null>;
 //#endregion
 export { JWTOptions, signJWT, verifyJWT };