sentri 5.0.0 → 5.0.1

package/dist/cli.js

@@ -13,6 +13,9 @@ export const sentriAuth = createAuthExpress<Role>({
   // -- Roles ------------------------------------------------------------------
   validRoles: ['admin', 'user'],
 
+  // -- Identifiers ------------------------------------------------------------
+  validIdentifiers: ['email', 'username'],
+
   // -- Database ---------------------------------------------------------------
   dialect: new PostgresDialect({
     pool: new Pool({ connectionString: process.env.DATABASE_URL! })
@@ -61,6 +64,9 @@ export const sentriAuth = createAuthFastify<Role>({
   // -- Roles ------------------------------------------------------------------
   validRoles: ['admin', 'user'],
 
+  // -- Identifiers ------------------------------------------------------------
+  validIdentifiers: ['email', 'username'],
+
   // -- Database ---------------------------------------------------------------
   dialect: new PostgresDialect({
     pool: new Pool({ connectionString: process.env.DATABASE_URL! })
@@ -109,6 +115,9 @@ export const sentriAuth = createAuthHono<Role>({
   // -- Roles ------------------------------------------------------------------
   validRoles: ['admin', 'user'],
 
+  // -- Identifiers ------------------------------------------------------------
+  validIdentifiers: ['email', 'username'],
+
   // -- Database ---------------------------------------------------------------
   dialect: new PostgresDialect({
     pool: new Pool({ connectionString: process.env.DATABASE_URL! })
@@ -157,6 +166,9 @@ export const sentriAuth = createAuthElysia<Role>({
   // -- Roles ------------------------------------------------------------------
   validRoles: ['admin', 'user'],
 
+  // -- Identifiers ------------------------------------------------------------
+  validIdentifiers: ['email', 'username'],
+
   // -- Database ---------------------------------------------------------------
   dialect: new PostgresDialect({
     pool: new Pool({ connectionString: process.env.DATABASE_URL! })
@@ -183,6 +195,9 @@ export const sentriAuth = createAuthKoa<Role>({
   // -- Roles ------------------------------------------------------------------
   validRoles: ['admin', 'user'],
 
+  // -- Identifiers ------------------------------------------------------------
+  validIdentifiers: ['email', 'username'],
+
   // -- Database ---------------------------------------------------------------
   dialect: new PostgresDialect({
     pool: new Pool({ connectionString: process.env.DATABASE_URL! })
@@ -511,4 +526,4 @@ Examples:
   npx sentri init client hono         \u2192 client mode, hono adapter
 `);}s(c,"help");async function l(e,o,t){if(existsSync(e)){console.log(`  skip   ${t} (already exists)`);return}await writeFile(e,o,"utf8"),console.log(`  create ${t}`);}s(l,"writeIfNotExists");async function S(e,o){let t=["server","client"],i=["express","fastify","hono","elysia","koa"];t.includes(e)||(console.error(`Unknown mode: "${e}". Valid modes: ${t.join(", ")}`),process.exit(1)),i.includes(o)||(console.error(`Unknown adapter: "${o}". Valid adapters: ${i.join(", ")}`),process.exit(1));let a=process.cwd(),p=join(a,"src","lib");await mkdir(p,{recursive:true});let u=g[e][o],d=e==="server"?A:R,m=E[e][o];console.log(`
 Generating sentri ${e} mode files (${o})...
-`),await l(join(p,"sentri.ts"),u,"src/lib/sentri.ts"),await l(join(a,".env.example"),d,".env.example"),console.log(m);}s(S,"init");var x=process.argv.slice(2),[r,k,_]=x;(!r||r==="--help"||r==="-h")&&(c(),process.exit(0));r==="init"?S(k??"server",_??"express").catch(t=>{console.error(t),process.exit(1);}):(console.error(`Unknown command: ${r}`),c(),process.exit(1));
+`),await l(join(p,"sentri.ts"),u,"src/lib/sentri.ts"),await l(join(a,".env.example"),d,".env.example"),console.log(m);}s(S,"init");var x=process.argv.slice(2),[r,I,k]=x;(!r||r==="--help"||r==="-h")&&(c(),process.exit(0));r==="init"?S(I??"server",k??"express").catch(t=>{console.error(t),process.exit(1);}):(console.error(`Unknown command: ${r}`),c(),process.exit(1));

package/dist/core/index.d.cts

@@ -125,6 +125,10 @@ interface SentriLogger {
     error(data: Record<string, unknown>): void;
 }
 
+/**
+ * Standardized API response format returned by Sentri endpoints.
+ * @template T - The type of the data payload.
+ */
 interface ApiResponse<T = null> {
     error: boolean;
     statusCode: number;
@@ -151,6 +155,7 @@ interface IdentifierInput {
     /** The globally unique identifier value. */
     value: string;
 }
+/** Result returned after a successful or failed registration attempt. */
 type RegisterResult<TRole extends string = string> = {
     success: true;
     user: AuthUser<TRole>;
@@ -158,6 +163,7 @@ type RegisterResult<TRole extends string = string> = {
     success: false;
     error: SentriError;
 };
+/** Result returned after a successful or failed login attempt. */
 type AuthResult<TRole extends string = string> = {
     success: true;
     accessToken: string;
@@ -167,6 +173,7 @@ type AuthResult<TRole extends string = string> = {
     success: false;
     error: SentriError;
 };
+/** Result returned after assigning new roles to a user. */
 type AssignRolesResult<TRole extends string = string> = {
     success: true;
     user: AuthUser<TRole>;
@@ -174,6 +181,7 @@ type AssignRolesResult<TRole extends string = string> = {
     success: false;
     error: SentriError;
 };
+/** Result returned when fetching a specific user's details. */
 type GetUserResult<TRole extends string = string> = {
     success: true;
     user: AuthUser<TRole>;
@@ -181,6 +189,7 @@ type GetUserResult<TRole extends string = string> = {
     success: false;
     error: SentriError;
 };
+/** Result returned after bulk identifier operations (create/update/delete). */
 type BulkIdentifiersResult = {
     success: true;
     identifiers: IdentifierRecord[];
@@ -188,12 +197,14 @@ type BulkIdentifiersResult = {
     success: false;
     error: SentriError;
 };
+/** Result returned after changing a user's password. */
 type ChangePasswordResult = {
     success: true;
 } | {
     success: false;
     error: SentriError;
 };
+/** Result returned after a successful or failed session refresh. */
 type RefreshResult<TRole extends string = string> = {
     success: true;
     accessToken: string;
@@ -203,17 +214,22 @@ type RefreshResult<TRole extends string = string> = {
     success: false;
     error: SentriError;
 };
+/** Input payload required for user registration. */
 interface RegisterInput<TRole extends string = string> {
     /** One or more identifiers for the new user. All values must be globally unique. */
     identifiers: IdentifierInput[];
     password: string;
     roles?: TRole[];
 }
+/** Input payload required for user login. */
 interface LoginInput {
     /** Any of the user's identifier values — Sentri searches all types. */
     identifier: string;
     password: string;
 }
+/**
+ * Configuration options for the HTTP-only Refresh Token cookie.
+ */
 interface CookieConfig {
     name?: string;
     httpOnly?: boolean;
@@ -221,12 +237,19 @@ interface CookieConfig {
     sameSite?: 'strict' | 'lax' | 'none';
     path?: string;
 }
+/**
+ * Configuration options for the Access Token cookie (if used).
+ */
 interface AccessCookieConfig {
     name?: string;
     secure?: boolean;
     sameSite?: 'strict' | 'lax' | 'none';
     path?: string;
 }
+/**
+ * Lifecycle hooks for injecting custom logic during authentication flows.
+ * Helpful for sending welcome emails, tracking analytics, or logging.
+ */
 interface AuthHooks {
     onRegister?: (user: AuthUser) => void | Promise<void>;
     onLoginSuccess?: (user: AuthUser, meta: {
@@ -239,10 +262,15 @@ interface AuthHooks {
     onPasswordChanged?: (userId: string) => void | Promise<void>;
     onLogout?: (userId: string) => void | Promise<void>;
 }
+/** Configuration for rate limiting login and registration endpoints. */
 interface RateLimitOptions {
     maxLoginAttempts?: number;
     maxRegisterAttempts?: number;
 }
+/**
+ * Optional overrides for the core router logic.
+ * Provide custom handler functions to completely replace default endpoints behaviors.
+ */
 interface RouterHandlers {
     register?: (input: RegisterInput, meta: {
         ip: string;
@@ -272,6 +300,7 @@ interface RouterHandlers {
     revokeSession?: (userId: string, sessionId: string) => Promise<void>;
 }
 interface ServerAuthConfig<TRole extends string = string> {
+    /** Indicates this configuration is for a Sentri Server instance. */
     mode: 'server';
     /** Kysely Dialect (e.g. PostgresDialect, MysqlDialect, SqliteDialect). */
     dialect: Dialect;
@@ -287,13 +316,19 @@ interface ServerAuthConfig<TRole extends string = string> {
      * @default 'HS256'
      */
     algorithm?: 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512';
+    /** List of valid roles accepted by the system during registration or role assignment. */
     validRoles: readonly TRole[];
+    /** @default ['email', 'username'] */
+    validIdentifiers?: readonly string[];
     /** @default '15m' */
     accessExpiresIn?: string | number;
     /** @default '7d' */
     refreshExpiresIn?: string | number;
     /** @default 12 */
     saltRounds?: number;
+    /**
+     * Optional API Key required for protected endpoints (like bulk identifier operations).
+     */
     apiKey?: string;
     cookie?: CookieConfig;
     accessCookie?: AccessCookieConfig;

package/dist/core/index.d.ts

@@ -125,6 +125,10 @@ interface SentriLogger {
     error(data: Record<string, unknown>): void;
 }
 
+/**
+ * Standardized API response format returned by Sentri endpoints.
+ * @template T - The type of the data payload.
+ */
 interface ApiResponse<T = null> {
     error: boolean;
     statusCode: number;
@@ -151,6 +155,7 @@ interface IdentifierInput {
     /** The globally unique identifier value. */
     value: string;
 }
+/** Result returned after a successful or failed registration attempt. */
 type RegisterResult<TRole extends string = string> = {
     success: true;
     user: AuthUser<TRole>;
@@ -158,6 +163,7 @@ type RegisterResult<TRole extends string = string> = {
     success: false;
     error: SentriError;
 };
+/** Result returned after a successful or failed login attempt. */
 type AuthResult<TRole extends string = string> = {
     success: true;
     accessToken: string;
@@ -167,6 +173,7 @@ type AuthResult<TRole extends string = string> = {
     success: false;
     error: SentriError;
 };
+/** Result returned after assigning new roles to a user. */
 type AssignRolesResult<TRole extends string = string> = {
     success: true;
     user: AuthUser<TRole>;
@@ -174,6 +181,7 @@ type AssignRolesResult<TRole extends string = string> = {
     success: false;
     error: SentriError;
 };
+/** Result returned when fetching a specific user's details. */
 type GetUserResult<TRole extends string = string> = {
     success: true;
     user: AuthUser<TRole>;
@@ -181,6 +189,7 @@ type GetUserResult<TRole extends string = string> = {
     success: false;
     error: SentriError;
 };
+/** Result returned after bulk identifier operations (create/update/delete). */
 type BulkIdentifiersResult = {
     success: true;
     identifiers: IdentifierRecord[];
@@ -188,12 +197,14 @@ type BulkIdentifiersResult = {
     success: false;
     error: SentriError;
 };
+/** Result returned after changing a user's password. */
 type ChangePasswordResult = {
     success: true;
 } | {
     success: false;
     error: SentriError;
 };
+/** Result returned after a successful or failed session refresh. */
 type RefreshResult<TRole extends string = string> = {
     success: true;
     accessToken: string;
@@ -203,17 +214,22 @@ type RefreshResult<TRole extends string = string> = {
     success: false;
     error: SentriError;
 };
+/** Input payload required for user registration. */
 interface RegisterInput<TRole extends string = string> {
     /** One or more identifiers for the new user. All values must be globally unique. */
     identifiers: IdentifierInput[];
     password: string;
     roles?: TRole[];
 }
+/** Input payload required for user login. */
 interface LoginInput {
     /** Any of the user's identifier values — Sentri searches all types. */
     identifier: string;
     password: string;
 }
+/**
+ * Configuration options for the HTTP-only Refresh Token cookie.
+ */
 interface CookieConfig {
     name?: string;
     httpOnly?: boolean;
@@ -221,12 +237,19 @@ interface CookieConfig {
     sameSite?: 'strict' | 'lax' | 'none';
     path?: string;
 }
+/**
+ * Configuration options for the Access Token cookie (if used).
+ */
 interface AccessCookieConfig {
     name?: string;
     secure?: boolean;
     sameSite?: 'strict' | 'lax' | 'none';
     path?: string;
 }
+/**
+ * Lifecycle hooks for injecting custom logic during authentication flows.
+ * Helpful for sending welcome emails, tracking analytics, or logging.
+ */
 interface AuthHooks {
     onRegister?: (user: AuthUser) => void | Promise<void>;
     onLoginSuccess?: (user: AuthUser, meta: {
@@ -239,10 +262,15 @@ interface AuthHooks {
     onPasswordChanged?: (userId: string) => void | Promise<void>;
     onLogout?: (userId: string) => void | Promise<void>;
 }
+/** Configuration for rate limiting login and registration endpoints. */
 interface RateLimitOptions {
     maxLoginAttempts?: number;
     maxRegisterAttempts?: number;
 }
+/**
+ * Optional overrides for the core router logic.
+ * Provide custom handler functions to completely replace default endpoints behaviors.
+ */
 interface RouterHandlers {
     register?: (input: RegisterInput, meta: {
         ip: string;
@@ -272,6 +300,7 @@ interface RouterHandlers {
     revokeSession?: (userId: string, sessionId: string) => Promise<void>;
 }
 interface ServerAuthConfig<TRole extends string = string> {
+    /** Indicates this configuration is for a Sentri Server instance. */
     mode: 'server';
     /** Kysely Dialect (e.g. PostgresDialect, MysqlDialect, SqliteDialect). */
     dialect: Dialect;
@@ -287,13 +316,19 @@ interface ServerAuthConfig<TRole extends string = string> {
      * @default 'HS256'
      */
     algorithm?: 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512';
+    /** List of valid roles accepted by the system during registration or role assignment. */
     validRoles: readonly TRole[];
+    /** @default ['email', 'username'] */
+    validIdentifiers?: readonly string[];
     /** @default '15m' */
     accessExpiresIn?: string | number;
     /** @default '7d' */
     refreshExpiresIn?: string | number;
     /** @default 12 */
     saltRounds?: number;
+    /**
+     * Optional API Key required for protected endpoints (like bulk identifier operations).
+     */
     apiKey?: string;
     cookie?: CookieConfig;
     accessCookie?: AccessCookieConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentri",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "description": "Auth/authorization library for Express, Fastify, Hono, and Elysia — PostgreSQL + JWT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",