peta-auth 0.1.3 → 0.2.1

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,6 +43,18 @@ declare function session<T extends Record<string, unknown> = Record<string, unkn
   standaloneSchema: {};
   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

package/dist/elysia.mjs

@@ -1,14 +1,23 @@
-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) };
 	});
@@ -16,7 +25,7 @@ function session(options) {
 function requireSession(key) {
 	return (app) => app.onBeforeHandle((context) => {
 		const session = context.session;
-		if (!(key ? !!session[key] : 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,33 @@
-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

package/dist/hono.mjs

@@ -1,12 +1,22 @@
-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();
 	});
@@ -14,7 +24,7 @@ function session(options) {
 function requireSession(key) {
 	return createMiddleware(async (c, next) => {
 		const s = c.var.session;
-		if (!(key ? !!s[key] : 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 };

package/dist/jwt.mjs

@@ -1,28 +1,48 @@
+import { t as normalizePassword } from "./crypto-WcFV83Nz.mjs";
+import { t as PetaAuthError } from "./errors-DxJ-WUJL.mjs";
 import * as jose from "jose";
 //#region src/jwt.ts
-function toPasswordMap(password) {
-	return typeof password === "string" ? { 1: password } : password;
-}
 function toKey(secret) {
 	return new TextEncoder().encode(secret);
 }
+/**
+* Sign a JWT payload.
+*
+* @example
+* ```ts
+* const token = await signJWT({ userId: "abc" }, { password: "my-32-char-secret...", expiresIn: 3600 })
+* ```
+*/
 async function signJWT(payload, options) {
-	const map = toPasswordMap(options.password);
+	const map = normalizePassword(options.password);
 	const secret = map[Math.max(...Object.keys(map).map(Number)).toString()];
-	if (!secret || secret.length < 32) throw new Error("peta-auth/jwt: password must be at least 32 characters");
+	if (!secret || secret.length < 32) throw new PetaAuthError("JWT_PASSWORD_TOO_SHORT", "peta-auth/jwt: password must be at least 32 characters");
 	const jwt = new jose.SignJWT(payload).setProtectedHeader({ alg: "HS256" }).setIssuedAt();
-	if (options.exp !== void 0) jwt.setExpirationTime(Math.floor(Date.now() / 1e3) + options.exp);
+	const ttl = options.expiresIn ?? 86400;
+	jwt.setExpirationTime(Math.floor(Date.now() / 1e3) + ttl);
 	return jwt.sign(toKey(secret));
 }
+/**
+* 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..." })
+* ```
+*/
 async function verifyJWT(token, options) {
-	for (const secret of Object.values(toPasswordMap(options.password))) {
+	let result = null;
+	const passwords = normalizePassword(options.password);
+	for (const secret of Object.values(passwords)) {
 		if (!secret) continue;
 		try {
 			const { payload } = await jose.jwtVerify(token, toKey(secret));
-			return payload;
+			if (!result) result = payload;
 		} catch {}
 	}
-	return null;
+	return result;
 }
 //#endregion
 export { signJWT, verifyJWT };

package/dist/nuxt.d.mts

@@ -1,9 +1,32 @@
-import { r as SessionOptions, t as IronSession } from "./session-z20gaFVT.mjs";
+import { r as SessionOptions, t as IronSession } from "./session-0bF8_7Ui.mjs";
 import { H3Event } from "h3";
 
 //#region src/nuxt.d.ts
+/**
+ * Create a session from an h3 event (Nuxt / h3).
+ *
+ * @example
+ * ```ts
+ * // In a Nuxt server handler:
+ * const session = await useSession(event, { password: process.env.NUXT_SESSION_PASSWORD })
+ * session.userId = 42
+ * await session.save()
+ * ```
+ */
 declare function useSession<T extends Record<string, unknown> = Record<string, unknown>>(event: H3Event, options: SessionOptions): Promise<T & IronSession>;
-declare function requireSession(_event: H3Event, session: IronSession): void;
-declare function requireSession<K extends string>(_event: H3Event, session: IronSession, key: K): void;
+/**
+ * Guard that requires session data.
+ *
+ * Throws a 401 h3 error when the session is empty.
+ *
+ * @example
+ * ```ts
+ * const session = await useSession(event, options)
+ * requireSession(event, session)
+ * requireSession(event, session, "role") // require specific key
+ * ```
+ */
+declare function requireSession(event: H3Event, session: IronSession): void;
+declare function requireSession<K extends string>(event: H3Event, session: IronSession, key: K): void;
 //#endregion
 export { requireSession, useSession };

package/dist/nuxt.mjs

@@ -1,21 +1,33 @@
-import { t as createSessionFromAdapter } from "./session-DSwf3XPH.mjs";
+import { t as PetaAuthError } from "./errors-DxJ-WUJL.mjs";
+import { n as sessionHasData, t as createSessionFromAdapter } from "./session-BGCQ1Z1Q.mjs";
 import { appendHeader, createError, getCookie } from "h3";
 //#region src/nuxt.ts
+/**
+* Create a session from an h3 event (Nuxt / h3).
+*
+* @example
+* ```ts
+* // In a Nuxt server handler:
+* const session = await useSession(event, { password: process.env.NUXT_SESSION_PASSWORD })
+* session.userId = 42
+* await session.save()
+* ```
+*/
 function useSession(event, options) {
 	const password = options.password ?? process.env.NUXT_SESSION_PASSWORD;
-	if (!password) throw new Error("peta-auth/nuxt: NUXT_SESSION_PASSWORD is required");
+	if (!password) throw new PetaAuthError("MISSING_PASSWORD", "peta-auth/nuxt: NUXT_SESSION_PASSWORD is required");
 	return createSessionFromAdapter({
 		getCookie: (name) => getCookie(event, name),
 		setCookie: (value) => appendHeader(event, "Set-Cookie", value)
 	}, {
 		password,
-		cookieName: options?.cookieName ?? "nuxt-session",
-		ttl: options?.ttl,
-		cookieOptions: options?.cookieOptions
+		cookieName: options.cookieName ?? "nuxt-session",
+		timeToLive: options.timeToLive,
+		cookieOptions: options.cookieOptions
 	});
 }
 function requireSession(_event, session, key) {
-	if (!(key ? !!session[key] : Object.keys(session).some((k) => k !== "save" && k !== "destroy" && k !== "updateConfig"))) throw createError({
+	if (!sessionHasData(session, key)) throw createError({
 		statusCode: 401,
 		statusMessage: "unauthorized"
 	});

package/dist/oauth/github.d.mts

@@ -1,4 +1,5 @@
 //#region src/oauth/github.d.ts
+/** Configuration for GitHub OAuth. */
 interface OAuthGitHubConfig {
   clientId?: string;
   clientSecret?: string;
@@ -10,6 +11,11 @@ interface OAuthGitHubConfig {
   authorizationParams?: Record<string, string>;
   redirectURL?: string;
 }
+interface GitHubTokens {
+  access_token: string;
+  scope: string;
+  token_type: string;
+}
 interface GitHubUser {
   login: string;
   id: number;
@@ -19,11 +25,18 @@ interface GitHubUser {
   email: string | null;
   email_verified?: boolean;
 }
-interface GitHubTokens {
-  access_token: string;
-  scope: string;
-  token_type: string;
-}
+/**
+ * Define a GitHub OAuth event handler.
+ *
+ * @example
+ * ```ts
+ * const handle = defineOAuthGitHubEventHandler({
+ *   onSuccess: async ({ user, tokens }) =>
+ *     new Response(`Welcome ${user.login}!`),
+ * })
+ * serve(handle)
+ * ```
+ */
 declare function defineOAuthGitHubEventHandler(options: {
   config?: OAuthGitHubConfig;
   onSuccess: (event: {