sentri 1.0.0

package/dist/types/auth.d.ts

@@ -0,0 +1,234 @@
+import type { AuthError } from '../errors/AuthError.js';
+export type { AuthError };
+/** Shape of a user row returned by the adapter — used internally by the library. */
+export interface UserRecord {
+    id: string;
+    /**
+     * The credential identifier for this user (email, username, phone number, etc.).
+     * The adapter decides which column(s) this maps to.
+     */
+    identifier: string;
+    passwordHash: string;
+    /** Role names currently assigned to the user. */
+    roles: string[];
+}
+/** Shape of a session row returned by the adapter. */
+export interface SessionRecord {
+    id: string;
+    userId: string;
+    expiresAt: Date;
+    createdAt: Date;
+}
+/** Data the library passes to the adapter when creating a new user. */
+export interface CreateUserData {
+    /**
+     * The credential identifier supplied at signup (email, username, phone, etc.).
+     * Store this in whichever column(s) your schema uses for login lookup.
+     */
+    identifier: string;
+    passwordHash: string;
+    /** Validated role names to assign at creation. */
+    roles: string[];
+}
+/**
+ * The database adapter interface the library depends on.
+ *
+ * Implement this to connect the library to any ORM or data layer.
+ *
+ * The library uses a single `identifier` string for credentials — your adapter
+ * decides what that means: email column, username column, phone column, or a
+ * query across multiple columns.
+ */
+export interface AuthAdapter {
+    user: {
+        /**
+         * Find a user by their login identifier.
+         *
+         * The adapter decides which column(s) to query — email, username, phone,
+         * or a combined lookup (`WHERE email = $1 OR username = $1`).
+         * Returns `null` if not found.
+         */
+        findByIdentifier(identifier: string): Promise<UserRecord | null>;
+        /** Find a user by their primary key. Returns `null` if not found. */
+        findById(id: string): Promise<UserRecord | null>;
+        /**
+         * Persist a new user with the given identifier, hashed password, and roles.
+         * The adapter maps `identifier` to the appropriate column(s) in your schema.
+         */
+        create(data: CreateUserData): Promise<{
+            id: string;
+        }>;
+    };
+    session: {
+        /**
+         * Persist a new session and return its generated ID.
+         * `expiresAt` is computed from `refreshExpiresIn` in config.
+         */
+        create(data: {
+            userId: string;
+            expiresAt: Date;
+        }): Promise<{
+            id: string;
+        }>;
+        /**
+         * Find a session by its ID, including the associated user.
+         * Returns `null` if the session does not exist (i.e. has been revoked).
+         */
+        findById(sessionId: string): Promise<(SessionRecord & {
+            user: UserRecord;
+        }) | null>;
+        /** Delete a single session. Used during logout and token rotation. */
+        delete(sessionId: string): Promise<void>;
+        /** Delete all sessions belonging to a user. Used for "logout from all devices". */
+        deleteAllForUser(userId: string): Promise<void>;
+    };
+}
+/**
+ * Configuration passed to {@link createAuth}.
+ *
+ * Only `secret`, `validRoles`, and `adapter` are required.
+ * All other fields have sensible defaults.
+ *
+ * @example
+ * createAuth({
+ *   secret: process.env.JWT_SECRET!,
+ *   validRoles: ['user', 'admin'] as const,
+ *   adapter: myAdapter,
+ * });
+ */
+export interface AuthConfig<TRole extends string = string> {
+    /** Secret used to sign JWT tokens. Must not be empty. Keep this in an env variable. */
+    secret: string;
+    /**
+     * How long access tokens are valid.
+     * Accepts a duration string (`'15m'`, `'1h'`) or seconds as a number.
+     * @default '15m'
+     */
+    accessExpiresIn?: string | number;
+    /**
+     * How long refresh tokens / sessions are valid.
+     * Accepts a duration string (`'7d'`, `'30d'`) or seconds as a number.
+     * @default '7d'
+     */
+    refreshExpiresIn?: string | number;
+    /**
+     * HMAC signing algorithm used for JWTs.
+     * @default 'HS256'
+     */
+    algorithm?: 'HS256' | 'HS384' | 'HS512';
+    /**
+     * bcrypt cost factor. Higher = slower hashing but more secure.
+     * @default 12
+     */
+    saltRounds?: number;
+    /**
+     * Exhaustive list of role names your application uses.
+     * Signup will be rejected with `INVALID_ROLE` if a role outside this list is requested.
+     * Use `as const` to get TypeScript union-type safety on `authorize()`.
+     *
+     * @example
+     * validRoles: ['user', 'admin', 'moderator'] as const
+     */
+    validRoles: readonly TRole[];
+    /** ORM adapter that connects the library to your database. */
+    adapter: AuthAdapter;
+    /**
+     * When set, the built-in router (`auth.router()`) stores the refresh token
+     * in an httpOnly cookie instead of returning it in the response body.
+     *
+     * The `refreshToken` field is omitted from `/login`, `/signup`, and `/refresh`
+     * responses. The `/logout` and `/logout-all` routes automatically clear the cookie.
+     *
+     * No extra middleware (e.g. `cookie-parser`) is required.
+     *
+     * @example
+     * createAuth({
+     *   // ...
+     *   cookie: { secure: process.env.NODE_ENV === 'production' },
+     * });
+     */
+    cookie?: CookieConfig;
+}
+/**
+ * Cookie settings for storing the refresh token in an httpOnly cookie.
+ * All fields are optional — defaults are chosen for security.
+ */
+export interface CookieConfig {
+    /**
+     * Name of the cookie.
+     * @default 'refresh_token'
+     */
+    name?: string;
+    /**
+     * Prevents JavaScript from reading the cookie (`document.cookie`).
+     * @default true
+     */
+    httpOnly?: boolean;
+    /**
+     * Restricts the cookie to HTTPS connections.
+     * Set to `true` in production.
+     * @default false
+     */
+    secure?: boolean;
+    /**
+     * Controls cross-site request behaviour.
+     * @default 'strict'
+     */
+    sameSite?: 'strict' | 'lax' | 'none';
+    /**
+     * URL path the cookie is scoped to.
+     * @default '/'
+     */
+    path?: string;
+}
+/** The user payload embedded in the access token and injected as `req.user`. */
+export interface AuthUser<TRole extends string = string> {
+    id: string;
+    /**
+     * The credential identifier for this user (email, username, phone, etc.).
+     * Reflects whatever value was passed as `identifier` at signup or login.
+     */
+    identifier: string;
+    roles: TRole[];
+}
+/** Return type of `signup` and `login`. */
+export type AuthResult<TRole extends string = string> = {
+    success: true;
+    accessToken: string;
+    refreshToken: string;
+    user: AuthUser<TRole>;
+} | {
+    success: false;
+    error: AuthError;
+};
+/** Return type of `refresh`. */
+export type RefreshResult<TRole extends string = string> = {
+    success: true;
+    accessToken: string;
+    refreshToken: string;
+    user: AuthUser<TRole>;
+} | {
+    success: false;
+    error: AuthError;
+};
+/** Input for `signup`. */
+export interface SignupInput<TRole extends string = string> {
+    /**
+     * The user's login credential — email, username, phone number, or any unique string.
+     * The adapter maps this to the appropriate column in your database.
+     */
+    identifier: string;
+    password: string;
+    /** Roles to assign at creation. Must be a subset of `validRoles`. */
+    roles?: TRole[];
+}
+/** Input for `login`. */
+export interface LoginInput {
+    /**
+     * The user's login credential — email, username, phone number, or any unique string.
+     * The adapter's `findByIdentifier` handles the lookup.
+     */
+    identifier: string;
+    password: string;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/types/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/types/auth.ts"],"names":[],"mappings":"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"}

package/dist/types/auth.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auth.js.map

package/dist/types/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/types/auth.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "sentri",
+  "version": "1.0.0",
+  "description": "Personal auth/authorization library for Express + Postgres",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": ["auth", "authentication", "authorization", "express", "jwt", "bcrypt"],
+  "author": "rizzzdev",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/bcrypt": "^6.0.0",
+    "@types/express": "^5.0.6",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/node": "^22.20.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "bcrypt": "^6.0.0",
+    "jsonwebtoken": "^9.0.3"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  }
+}