@luckystack/login 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,565 @@
+import { BaseSessionLayout } from '@luckystack/core';
+export { AuthProps, BaseSessionLayout, SessionLocation } from '@luckystack/core';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { Socket } from 'socket.io';
+
+/**
+ * Module augmentation: extends `@luckystack/core`'s `HookPayloads` interface
+ * with auth and session lifecycle hooks owned by this package.
+ *
+ * This file is picked up by the TypeScript compiler because it is in the
+ * tsconfig `include` path. A side-effect `import './hookPayloads';` in
+ * `index.ts` makes the dependency explicit for readers even though TS would
+ * merge the declaration regardless.
+ */
+
+interface PreLoginPayload {
+    email: string;
+    provider: string;
+}
+interface PostLoginPayload {
+    userId: string;
+    provider: string;
+    isNewUser: boolean;
+    token: string;
+}
+interface PreRegisterPayload {
+    email: string;
+    provider: string;
+    name?: string;
+}
+interface PostRegisterPayload {
+    userId: string;
+    provider: string;
+}
+interface PreLogoutPayload {
+    userId: string | null;
+    token: string | null;
+}
+interface PostLogoutPayload {
+    userId: string | null;
+    token: string | null;
+}
+interface PreSessionCreatePayload {
+    token: string;
+    user: BaseSessionLayout;
+    persistent: boolean;
+}
+interface PostSessionCreatePayload {
+    token: string;
+    user: BaseSessionLayout;
+    persistent: boolean;
+}
+interface PreSessionDeletePayload {
+    token: string;
+    userId: string | null;
+}
+interface PostSessionDeletePayload {
+    token: string;
+    userId: string | null;
+}
+interface PasswordResetRequestedPayload {
+    /** Email the user typed in the reset form. May or may not match a real user. */
+    email: string;
+    /** True when a matching user was found and an email is being sent. */
+    matched: boolean;
+    /** The userId, when matched. */
+    userId?: string;
+    /** The reset token (for audit; do not log). */
+    token?: string;
+    /** Token TTL in seconds. */
+    ttlSeconds?: number;
+}
+interface PasswordResetCompletedPayload {
+    /** User whose password was reset via the forgot-password flow. */
+    userId: string;
+    /** Whether the framework auto-revoked all other active sessions. */
+    revokedOtherSessions: boolean;
+}
+interface PasswordChangedPayload {
+    /** User whose password was changed via the in-session change flow. */
+    userId: string;
+    /** True if the user verified their current password successfully. */
+    verifiedCurrent: boolean;
+    /** Whether sessions other than the current one were revoked. */
+    revokedOtherSessions: boolean;
+}
+interface PrePasswordResetCompletedPayload {
+    /** User whose password is about to be reset via the forgot-password flow. */
+    userId: string;
+}
+interface PrePasswordChangedPayload {
+    /** User whose password is about to be changed via the in-session flow. */
+    userId: string;
+    /** True if the user verified their current password successfully. */
+    verifiedCurrent: boolean;
+}
+interface PreEmailChangePayload {
+    userId: string;
+    currentEmail: string;
+    newEmail: string;
+}
+interface PostEmailChangeRequestedPayload {
+    userId: string;
+    newEmail: string;
+}
+interface PostEmailChangedPayload {
+    userId: string;
+    oldEmail: string;
+    newEmail: string;
+}
+declare module '@luckystack/core' {
+    interface HookPayloads {
+        preLogin: PreLoginPayload;
+        postLogin: PostLoginPayload;
+        preRegister: PreRegisterPayload;
+        postRegister: PostRegisterPayload;
+        preLogout: PreLogoutPayload;
+        postLogout: PostLogoutPayload;
+        preSessionCreate: PreSessionCreatePayload;
+        postSessionCreate: PostSessionCreatePayload;
+        preSessionDelete: PreSessionDeletePayload;
+        postSessionDelete: PostSessionDeletePayload;
+        passwordResetRequested: PasswordResetRequestedPayload;
+        prePasswordResetCompleted: PrePasswordResetCompletedPayload;
+        passwordResetCompleted: PasswordResetCompletedPayload;
+        prePasswordChanged: PrePasswordChangedPayload;
+        passwordChanged: PasswordChangedPayload;
+        preEmailChange: PreEmailChangePayload;
+        postEmailChangeRequested: PostEmailChangeRequestedPayload;
+        postEmailChanged: PostEmailChangedPayload;
+    }
+}
+
+/**
+ * Save or update a user session through the active session adapter.
+ *
+ * @param token - The session token (unique identifier)
+ * @param data - The session data to store
+ * @param newUser - If true, this is a new login (triggers single-session enforcement)
+ */
+declare const saveSession: (token: string, data: BaseSessionLayout, newUser?: boolean) => Promise<void>;
+/**
+ * Retrieve a user session through the active session adapter.
+ *
+ * @param token - The session token
+ * @returns The session data or null if not found
+ */
+declare const getSession: (token: string | null) => Promise<BaseSessionLayout | null>;
+/**
+ * Delete a user session through the active adapter and notify connected
+ * clients.
+ *
+ * @param token - The session token to delete
+ * @returns true if successful
+ */
+declare const deleteSession: (token: string) => Promise<boolean>;
+/**
+ * Get all active sessions (admin utility). Returns empty when the active
+ * adapter doesn't implement enumeration (signed-JWT-stateless, log-only).
+ *
+ * @returns Array of all session data
+ */
+declare const getAllSessions: () => Promise<BaseSessionLayout[]>;
+/**
+ * Revoke every active session for a user, optionally keeping one alive.
+ *
+ * @param userId - The user whose sessions to revoke
+ * @param exceptToken - If provided, this session is left untouched. Pass the
+ *   caller's own token when revoking after a password change so the user
+ *   isn't logged out of the device they just changed it from. Pass null/omit
+ *   to revoke everything (account deletion, "sign out everywhere", etc.).
+ *
+ * Each revocation goes through `deleteSession`, so connected sockets are
+ * told to log out via the same flow as a normal logout. Returns the number
+ * of sessions actually revoked.
+ */
+declare const revokeUserSessions: (userId: string, exceptToken?: string | null) => Promise<number>;
+declare const sessionKeyFor: (token: string) => string;
+declare const activeUsersKeyFor: (userId: string) => string;
+
+interface SessionAdapter {
+    /** Human-readable identifier (used in logs/diagnostics). */
+    name: string;
+    /** Read the raw stored session string for `token`. Null when missing. */
+    getRaw(token: string): Promise<string | null>;
+    /**
+     * Write the raw session string for `token` with a TTL. Implementations
+     * MUST honour the TTL — sessions without one would never expire.
+     */
+    setRaw(token: string, value: string, ttlSeconds: number): Promise<void>;
+    /** Delete the session record for `token`. Idempotent. */
+    delete(token: string): Promise<void>;
+    /**
+     * Refresh the TTL on an existing session record (sliding-window
+     * expiration). Returns true when the underlying record existed and the
+     * TTL was applied, false otherwise. Implementations must not create a
+     * record on miss.
+     */
+    expire(token: string, ttlSeconds: number): Promise<boolean>;
+    /** Remaining TTL in seconds (or null when the record is missing). */
+    ttl(token: string): Promise<number | null>;
+    trackActive(userId: string, token: string, ttlSeconds: number): Promise<void>;
+    untrackActive(userId: string, token: string): Promise<void>;
+    listActive(userId: string): Promise<string[]>;
+    /**
+     * Admin walk: yield every active session record. Optional because
+     * non-scannable backends (signed-JWT-stateless, log-only) cannot
+     * enumerate. Callers fall back to a per-user listActive when omitted.
+     */
+    listAll?(): Promise<{
+        token: string;
+        raw: string;
+    }[]>;
+}
+declare const redisSessionAdapter: SessionAdapter;
+/**
+ * Replace the active session storage backend. Call once at boot from
+ * `luckystack/server/index.ts`, BEFORE the first login request. Common
+ * use cases:
+ *
+ *  - DynamoDB / Cosmos DB for serverless / edge deployments
+ *  - Postgres `sessions` table when you already operate Postgres
+ *  - signed-JWT-stateless (the adapter writes nothing, reads from the
+ *    JWT, and stores activeUsers per token in a small Redis hash)
+ *  - in-memory mock for integration tests
+ *
+ * Last-write-wins: subsequent calls overwrite the active adapter.
+ */
+declare const registerSessionAdapter: (adapter: SessionAdapter) => void;
+/** Read the currently-active session adapter (defaults to Redis). */
+declare const getSessionAdapter: () => SessionAdapter;
+
+interface UserAdapterCreateInput {
+    email: string;
+    provider: string;
+    name?: string | null;
+    password?: string | null;
+    avatar?: string | null;
+    avatarFallback?: string | null;
+    language?: string | null;
+}
+interface UserRecord extends BaseSessionLayout {
+    password?: string | null;
+    provider?: string | null;
+    /** Most recent successful login. Mirrors the optional `lastLogin` column on User. */
+    lastLogin?: Date | null;
+}
+interface UserAdapter {
+    findByEmail: (params: {
+        email: string;
+        provider: string;
+    }) => Promise<UserRecord | null>;
+    findById: (id: string) => Promise<UserRecord | null>;
+    create: (input: UserAdapterCreateInput) => Promise<UserRecord>;
+    update: (id: string, patch: Partial<UserRecord>) => Promise<UserRecord>;
+}
+declare const registerUserAdapter: (adapter: UserAdapter) => UserAdapter;
+declare const isUserAdapterRegistered: () => boolean;
+declare const defaultPrismaUserAdapter: () => UserAdapter;
+declare const getUserAdapter: () => UserAdapter;
+
+interface paramsType {
+    email?: string;
+    password?: string;
+    name?: string;
+    confirmPassword?: string;
+}
+declare const createOAuthState: (providerName: string) => Promise<string | null>;
+declare const registerWithCredentials: ({ email, password, name, confirmPassword, }: {
+    email: string;
+    password: string;
+    name: string;
+    confirmPassword: string;
+}) => Promise<{
+    status: boolean;
+    reason: string;
+    session?: undefined;
+} | {
+    status: boolean;
+    reason: string;
+    session: Omit<UserRecord, "password">;
+}>;
+declare const loginWithCredentialsCore: ({ email, password }: {
+    email: string;
+    password: string;
+}) => Promise<{
+    status: boolean;
+    reason: string;
+    newToken?: undefined;
+    session?: undefined;
+} | {
+    status: boolean;
+    reason: Error;
+    newToken?: undefined;
+    session?: undefined;
+} | {
+    status: boolean;
+    reason: string;
+    newToken: string;
+    session: BaseSessionLayout;
+}>;
+declare const loginWithCredentials: (params: paramsType) => Promise<{
+    status: false;
+    reason: string;
+} | {
+    status: boolean;
+    reason: string;
+    session?: undefined;
+} | {
+    status: boolean;
+    reason: string;
+    session: Omit<UserRecord, "password">;
+} | {
+    status: boolean;
+    reason: Error;
+    newToken?: undefined;
+    session?: undefined;
+} | {
+    status: boolean;
+    reason: string;
+    newToken: string;
+    session: BaseSessionLayout;
+}>;
+interface OAuthCallbackResult {
+    token: string;
+    redirectUrl: string;
+    userId: string;
+    provider: string;
+    isNewUser: boolean;
+}
+declare const loginCallback: (pathname: string, req: IncomingMessage, _res: ServerResponse, options?: {
+    defaultRedirectUrl?: string;
+}) => Promise<OAuthCallbackResult | false>;
+
+declare const logout: ({ token, socket, userId, skipSessionDelete }: {
+    token: string | null;
+    socket: Socket | undefined;
+    userId: string | null;
+    skipSessionDelete?: boolean;
+}) => Promise<void>;
+
+/**
+ * Create a one-time password-reset token bound to a user id. Stored in Redis
+ * with the configured TTL. Returns the token string — caller emails it to
+ * the user (typically embedded in a URL).
+ */
+declare const createPasswordResetToken: (userId: string) => Promise<string>;
+/**
+ * Validate and consume a password-reset token. Returns the bound userId on
+ * success and removes the token (one-time use). Returns null when the token
+ * is missing, expired, or malformed.
+ */
+declare const consumePasswordResetToken: (token: string) => Promise<string | null>;
+/**
+ * Bcrypt-hash a plaintext password and write it to the user record via the
+ * registered user adapter. Used by the reset flow and by the settings
+ * password-change flow. Validates against the active password policy
+ * (`projectConfig.auth.passwordPolicy`) before hashing — throws a `PasswordPolicyError`
+ * when the plaintext fails policy. Catch and surface the error code to the
+ * client; framework-mode reset/change flows already do this.
+ */
+declare const updatePasswordHash: (userId: string, plaintext: string) => Promise<void>;
+/**
+ * Thrown by `updatePasswordHash` when the supplied plaintext violates the
+ * active password policy. `errorCode` matches the i18n reason key the rest
+ * of the login flow uses (e.g. `login.passwordRequiresUppercase`).
+ */
+declare class PasswordPolicyError extends Error {
+    readonly errorCode: string;
+    constructor(errorCode: string);
+}
+/** Verify a plaintext password against a stored bcrypt hash. */
+declare const verifyPassword: (plaintext: string, hash: string) => Promise<boolean>;
+
+/**
+ * Validate `password` against the active project's password policy.
+ * Returns null on success, a string reason-key on the first failure.
+ *
+ * The policy lives in `projectConfig.auth.passwordPolicy` and is read at
+ * call time, so consumers can override defaults via `registerProjectConfig`.
+ */
+declare const validatePassword: (password: string) => string | null;
+
+interface SendResetEmailArgs {
+    email: string;
+    /**
+     * App-facing display name used in the email greeting + subject. If omitted,
+     * falls back to `projectConfig.auth.passwordResetBrand`, then to `'LuckyStack'`
+     * as the absolute fallback. Real consumers should set this on either the
+     * call site OR via `projectConfig.auth.passwordResetBrand`.
+     */
+    brand?: string;
+}
+/**
+ * Look up the user by credentials-provider email, generate a reset token,
+ * and email them a reset link. Always resolves successfully regardless of
+ * whether the email matched a user (anti-enumeration). Returns the result
+ * of the email send for diagnostics.
+ */
+declare const sendPasswordResetEmail: ({ email, brand }: SendResetEmailArgs) => Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+
+interface EmailChangePayload {
+    userId: string;
+    newEmail: string;
+}
+/**
+ * Create a one-time email-change token bound to a user id + the new email
+ * address. Stored in Redis with the configured TTL. Returns the token string
+ * — caller emails the token (embedded in a URL) to the NEW address so the
+ * confirmation click proves ownership of the new mailbox.
+ */
+declare const createEmailChangeToken: (userId: string, newEmail: string) => Promise<string>;
+/**
+ * Validate and consume an email-change token. Returns the bound
+ * `{ userId, newEmail }` on success and removes the token (one-time use).
+ * Returns null when the token is missing, expired, or malformed.
+ */
+declare const consumeEmailChangeToken: (token: string) => Promise<EmailChangePayload | null>;
+
+interface SendEmailChangeArgs {
+    userId: string;
+    newEmail: string;
+    /** Optional display name used in the email greeting (falls back to "there"). */
+    userName?: string | null;
+    /**
+     * App-facing display name used in the email greeting + subject. Falls back
+     * to `projectConfig.auth.passwordResetBrand` (the shared brand label), then
+     * to `'LuckyStack'` as the absolute fallback.
+     */
+    brand?: string;
+}
+/**
+ * Mint a one-shot email-change token and send a confirmation email to the
+ * NEW address with the tokenized URL. Returns the send result for diagnostics
+ * + the token itself (callers can audit-log it through the
+ * `postEmailChangeRequested` hook).
+ */
+declare const sendEmailChangeConfirmation: ({ userId, newEmail, userName, brand }: SendEmailChangeArgs) => Promise<{
+    ok: boolean;
+    reason?: string;
+    token: string;
+}>;
+
+type OAuthUserData = Record<string, unknown>;
+interface CredentialsProvider {
+    name: 'credentials';
+}
+interface FullOAuthProvider {
+    name: string;
+    clientID: string;
+    clientSecret: string;
+    callbackURL: string;
+    authorizationURL: string;
+    tokenExchangeURL: string;
+    tokenExchangeMethod: 'json' | 'form';
+    userInfoURL: string;
+    /**
+     * OAuth scopes requested at the authorization step. Consumers can extend
+     * a built-in provider's defaults to request additional permissions:
+     *
+     *   ```ts
+     *   const customGoogle = googleProvider({...});
+     *   customGoogle.scope.push('https://www.googleapis.com/auth/calendar.readonly');
+     *   ```
+     *
+     * Or pass `extraScopes` to the built-in factory (see `OAuthHelperInput`).
+     */
+    scope: string[];
+    nameKey: string;
+    emailKey: string;
+    avatarKey?: string;
+    avatarCodeKey: string;
+    getEmail?: (accessToken: string) => Promise<string | false | undefined>;
+    getAvatar?: (params: {
+        userData: OAuthUserData;
+        avatarId?: string;
+        accessToken: string;
+    }) => string | undefined | Promise<string | undefined>;
+    /**
+     * Optional per-provider hook to attach extra runtime-only data to the
+     * session (NOT to the User row). Return key/value pairs that get merged
+     * into `BaseSessionLayout` before `saveSession`. To get strict typing
+     * downstream, extend `BaseSessionLayout` via module augmentation:
+     *
+     *   ```ts
+     *   declare module '@luckystack/core' {
+     *     interface BaseSessionLayout {
+     *       googleCalendarToken?: string;
+     *     }
+     *   }
+     *   ```
+     *
+     * Data lives on the session in Redis and disappears on logout — no Prisma
+     * schema change required. Don't store secrets you wouldn't want surfaced
+     * to a user inspecting their own session.
+     */
+    extraSessionFields?: (params: {
+        userData: OAuthUserData;
+        accessToken: string;
+    }) => Promise<Record<string, unknown>> | Record<string, unknown>;
+}
+type OAuthProvider = CredentialsProvider | FullOAuthProvider;
+declare const isFullOAuthProvider: (provider: OAuthProvider) => provider is FullOAuthProvider;
+interface OAuthEndpointOverrides {
+    /** Override the provider's authorization URL (e.g. GitHub Enterprise host, Microsoft custom tenant). */
+    authorizationURL?: string;
+    /** Override the token exchange URL. */
+    tokenExchangeURL?: string;
+    /** Override the userInfo URL. */
+    userInfoURL?: string;
+}
+interface OAuthHelperInput {
+    clientId: string | undefined;
+    clientSecret: string | undefined;
+    callbackUrl: string;
+    /** Optional URL overrides for self-hosted / custom-tenant deployments. */
+    endpoints?: OAuthEndpointOverrides;
+    /**
+     * Additional OAuth scopes to request alongside the built-in defaults. Use
+     * for "give me access to the user's calendar / drive / repos" flows.
+     * Merged with the helper's default scopes; duplicates are deduplicated.
+     */
+    extraScopes?: string[];
+    /**
+     * Per-provider hook for attaching runtime-only fields to the session.
+     * See `FullOAuthProvider.extraSessionFields` for usage + module-augmentation
+     * pattern.
+     */
+    extraSessionFields?: FullOAuthProvider['extraSessionFields'];
+}
+declare const credentialsProvider: () => CredentialsProvider;
+declare const googleProvider: (input: OAuthHelperInput) => FullOAuthProvider;
+declare const githubProvider: (input: OAuthHelperInput) => FullOAuthProvider;
+declare const discordProvider: (input: OAuthHelperInput) => FullOAuthProvider;
+interface FacebookProviderInput extends OAuthHelperInput {
+    /** Graph API version segment used in the URLs. Default `'v18.0'` (current as of 2026 — bump as Meta deprecates older versions). */
+    apiVersion?: string;
+}
+declare const facebookProvider: (input: FacebookProviderInput) => FullOAuthProvider;
+interface MicrosoftProviderInput extends OAuthHelperInput {
+    /** Tenant id segment in the authorize/token URLs. Default `'common'`. */
+    tenant?: string;
+    /** OAuth API version segment. Default `'v2.0'`. */
+    apiVersion?: string;
+    /** Graph API version segment for /me. Default `'v1.0'`. */
+    graphApiVersion?: string;
+}
+declare const microsoftProvider: (input: MicrosoftProviderInput) => FullOAuthProvider;
+declare const getOAuthProviders: () => OAuthProvider[];
+declare const registerOAuthProviders: (providers: OAuthProvider[]) => OAuthProvider[];
+
+interface PostLoginRedirectInput {
+    userId: string;
+    provider: string;
+    isNewUser: boolean;
+    defaultUrl: string;
+}
+type PostLoginRedirectResolver = (input: PostLoginRedirectInput) => string | Promise<string>;
+declare const registerPostLoginRedirect: (resolver: PostLoginRedirectResolver) => PostLoginRedirectResolver;
+declare const getPostLoginRedirect: () => PostLoginRedirectResolver | null;
+
+export { type CredentialsProvider, type EmailChangePayload, type FullOAuthProvider, type OAuthProvider, PasswordPolicyError, type PostEmailChangeRequestedPayload, type PostEmailChangedPayload, type PostLoginPayload, type PostLoginRedirectInput, type PostLoginRedirectResolver, type PostLogoutPayload, type PostRegisterPayload, type PostSessionCreatePayload, type PostSessionDeletePayload, type PreEmailChangePayload, type PreLoginPayload, type PreLogoutPayload, type PreRegisterPayload, type PreSessionCreatePayload, type PreSessionDeletePayload, type SessionAdapter, type UserAdapter, type UserAdapterCreateInput, type UserRecord, activeUsersKeyFor, consumeEmailChangeToken, consumePasswordResetToken, createEmailChangeToken, createOAuthState, createPasswordResetToken, credentialsProvider, defaultPrismaUserAdapter, deleteSession, discordProvider, facebookProvider, getAllSessions, getOAuthProviders, getPostLoginRedirect, getSession, getSessionAdapter, getUserAdapter, githubProvider, googleProvider, isFullOAuthProvider, isUserAdapterRegistered, loginCallback, loginWithCredentials, loginWithCredentialsCore, logout, microsoftProvider, redisSessionAdapter, registerOAuthProviders, registerPostLoginRedirect, registerSessionAdapter, registerUserAdapter, registerWithCredentials, revokeUserSessions, saveSession, sendEmailChangeConfirmation, sendPasswordResetEmail, sessionKeyFor, updatePasswordHash, validatePassword, verifyPassword };