@nexusrt/nexus-auth 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,466 @@
+interface AuthUser {
+    email: string;
+    avatar_url?: string;
+    [key: string]: unknown;
+}
+interface JwtPayload {
+    email: string;
+    avatar_url?: string;
+    [key: string]: unknown;
+}
+interface RefreshTokenResponse {
+    access_token: string;
+}
+interface SignInResponse {
+    access_token?: string;
+    status?: SignInStatus;
+    mfa?: string;
+}
+interface MagicLinkResponse {
+    status: "MAGIC_LINK";
+    mfa: string;
+}
+interface ForgotPasswordResponse {
+    status: "RESET_PASSWORD";
+    mfa: string;
+}
+interface TotpSetupResponse {
+    totp: string;
+}
+interface SsoStartResponse {
+    auth_url: string;
+}
+interface GenericSuccessResponse {
+    [key: string]: unknown;
+}
+declare const SignInStatus: {
+    /** Standard email+password sign-in succeeded — no MFA required */
+    readonly SUCCESS: "SUCCESS";
+    /** Server requires the user to complete an Email MFA challenge */
+    readonly MFA_REQUIRED: "MFA_REQUIRED";
+    /** Server requires the user to complete a TOTP challenge */
+    readonly TOTP_REQUIRED: "TOTP_REQUIRED";
+    /** Server sent a magic link/code to the user's email */
+    readonly MAGIC_LINK: "MAGIC_LINK";
+    /** Server sent a password-reset code to the user's email */
+    readonly RESET_PASSWORD: "RESET_PASSWORD";
+};
+type SignInStatus = (typeof SignInStatus)[keyof typeof SignInStatus];
+interface AuthClientConfig {
+    /**
+     * Base URL of your auth server.
+     * @default "https://auth.jobtrk.com"
+     */
+    baseUrl?: string;
+}
+interface EmailPasswordCredentials {
+    email: string;
+    password: string;
+    userName?: string;
+    firstName?: string;
+    lastName?: string;
+}
+interface MfaVerifyInput {
+    /** The session ID returned from the initial sign-in / magic-link call */
+    sessionId: string;
+    /** The one-time code entered by the user */
+    code: string;
+}
+interface ResetPasswordInput {
+    oldPassword: string;
+    newPassword: string;
+}
+interface ForgotPasswordConfirmInput {
+    /** The session ID returned from forgotPassword() */
+    sessionId: string;
+    /** The code emailed to the user */
+    code: string;
+    /** The new password to set */
+    password: string;
+}
+interface SsoRegisterInput {
+    providerName: string;
+    providerEndEmail: string;
+    clientId: string;
+    clientSecret: string;
+    issuer: string;
+    callbackUrl: string;
+}
+
+/**
+ * Manages the in-memory access token and exposes token-based auth helpers.
+ *
+ * Storage strategy:
+ *   - Access tokens are kept in memory only (never localStorage) for security.
+ *   - Refresh tokens are stored in an HttpOnly cookie by the server.
+ */
+declare class TokenManager {
+    private accessToken;
+    getAccessToken(): string | null;
+    setAccessToken(token: string): void;
+    clearAccessToken(): void;
+    /**
+     * Decodes the JWT payload without verifying the signature.
+     * Useful for reading user info (email, avatar) on the client side.
+     */
+    decodeToken(token: string): JwtPayload | null;
+    /**
+     * Reads user info directly from the stored access token.
+     * Returns null if no token is set or it cannot be decoded.
+     */
+    getUserFromToken(): Pick<AuthUser, "email" | "avatar_url"> | null;
+    /**
+     * Attempts to get a new access token using the HttpOnly refresh-token cookie.
+     * Call this once on app startup to restore an existing session.
+     *
+     * @returns The decoded user info on success, or null if no refresh token exists.
+     */
+    refresh(baseUrl: string): Promise<Pick<AuthUser, "email" | "avatar_url"> | null>;
+}
+
+/**
+ * Session-based auth helpers.
+ *
+ * When the developer chooses sessions over JWTs, the server sets an
+ * HttpOnly session cookie.  These methods let you read and verify
+ * that session without managing tokens yourself.
+ *
+ * Note: An access token is still returned by the server even in session
+ * mode, so you can use it to authenticate with downstream services if needed.
+ */
+declare class SessionManager {
+    /**
+     * Fetches the currently authenticated user from the server.
+     * Relies on the session cookie being present in the browser.
+     *
+     * Use this instead of decoding the JWT when you want the
+     * authoritative user object from your database.
+     */
+    getUser(baseUrl: string): Promise<AuthUser>;
+    /**
+     * Verifies that a session is still valid for a given email address.
+     * Useful for server-side checks or sensitive operations.
+     */
+    verifySession(baseUrl: string, email: string): Promise<void>;
+}
+
+/**
+ * Email + Password authentication methods.
+ *
+ * Sign-in has three possible outcomes depending on what the user has enabled:
+ *
+ *   1. Plain sign-in     → status is undefined / SUCCESS  (no MFA)
+ *   2. Email MFA         → status === SignInStatus.MFA_REQUIRED
+ *   3. TOTP              → status === SignInStatus.TOTP_REQUIRED
+ *
+ * In cases 2 & 3 the response includes a `mfa` session ID that you must
+ * pass to the corresponding verify method.
+ *
+ * Import `SignInStatus` to compare against the status value:
+ *   import { SignInStatus } from "jobtrk-auth-sdk";
+ */
+declare class EmailPasswordAuth {
+    /**
+     * Creates a new account with an email address and password.
+     */
+    signUp(baseUrl: string, credentials: EmailPasswordCredentials): Promise<GenericSuccessResponse>;
+    /**
+     * Signs in with email + password.
+     *
+     * Check `response.status` to determine the next step:
+     *
+     * ```ts
+     * const result = await auth.email.signIn({ email, password });
+     *
+     * if (result.status === SignInStatus.MFA_REQUIRED) {
+     *   // prompt for email OTP, then call auth.email.verifyMfa()
+     * } else if (result.status === SignInStatus.TOTP_REQUIRED) {
+     *   // prompt for TOTP code, then call auth.totp.verifySignIn()
+     * } else {
+     *   // user is signed in — store result.access_token if using JWT mode
+     * }
+     * ```
+     */
+    signIn(baseUrl: string, credentials: EmailPasswordCredentials): Promise<SignInResponse>;
+    /**
+     * Confirms the one-time code sent to the user's email after a sign-in
+     * that returned `status === SignInStatus.MFA_REQUIRED`.
+     */
+    verifyMfa(baseUrl: string, input: MfaVerifyInput): Promise<GenericSuccessResponse>;
+    /**
+     * Looks up the username associated with an email address.
+     */
+    getUsername(baseUrl: string, email: string): Promise<GenericSuccessResponse>;
+}
+
+/**
+ * Email Magic Link authentication.
+ *
+ * Flow:
+ *   1. Call `send(email)` → server emails a one-time code to the user.
+ *   2. Response contains a `mfa` session ID.
+ *   3. User enters the code; call `verify({ sessionId, code })` to complete sign-in.
+ */
+declare class MagicLinkAuth {
+    /**
+     * Sends a magic-link code to the provided email address.
+     *
+     * @returns A session ID (`mfa` field) that you must pass to `verify()`.
+     *
+     * ```ts
+     * const { mfa: sessionId } = await auth.magicLink.send(email);
+     * // store sessionId, prompt user for code
+     * ```
+     */
+    send(baseUrl: string, email: string): Promise<MagicLinkResponse>;
+    /**
+     * Verifies the code the user received and completes sign-in.
+     */
+    verify(baseUrl: string, input: MfaVerifyInput): Promise<GenericSuccessResponse>;
+}
+
+/**
+ * TOTP (Time-based One-Time Password) MFA management.
+ *
+ * Setup flow:
+ *   1. Call `setup()` → server returns a QR code / TOTP secret.
+ *   2. User scans with their authenticator app.
+ *   3. Call `confirmSetup(code)` with the first code to activate TOTP.
+ *
+ * Sign-in flow (when signIn returns `status === SignInStatus.TOTP_REQUIRED`):
+ *   1. Prompt user for their TOTP code.
+ *   2. Call `verifySignIn({ sessionId: data.mfa, code })` to complete sign-in.
+ */
+declare class TotpAuth {
+    /**
+     * Starts TOTP registration — returns the secret / QR code to display.
+     */
+    setup(baseUrl: string): Promise<TotpSetupResponse>;
+    /**
+     * Confirms the TOTP setup by verifying the first code from the
+     * authenticator app.
+     */
+    confirmSetup(baseUrl: string, code: string): Promise<GenericSuccessResponse>;
+    /**
+     * Completes a TOTP sign-in challenge.
+     * Use the `mfa` session ID returned by `emailPassword.signIn()` as `sessionId`.
+     */
+    verifySignIn(baseUrl: string, input: MfaVerifyInput): Promise<GenericSuccessResponse>;
+    /**
+     * Removes TOTP from the currently authenticated user's account.
+     */
+    delete(baseUrl: string): Promise<void>;
+}
+
+/**
+ * Password management methods.
+ *
+ * ── Reset password (authenticated user) ──────────────────────────────
+ *   The user knows their current password and wants to change it.
+ *   Call `reset({ oldPassword, newPassword })`.
+ *
+ * ── Forgot password (unauthenticated) ────────────────────────────────
+ *   1. Call `forgot(email)` → server emails a code and returns a session ID.
+ *   2. User enters the code from their email.
+ *   3. Call `confirmForgot({ sessionId, code, password })` to set the new password.
+ */
+declare class PasswordAuth {
+    /**
+     * Changes the password for an already authenticated user.
+     */
+    reset(baseUrl: string, input: ResetPasswordInput): Promise<GenericSuccessResponse>;
+    /**
+     * Initiates the forgot-password flow by sending a reset code to the
+     * user's email address.
+     *
+     * @returns A session ID (`mfa` field) required by `confirmForgot()`.
+     *
+     * ```ts
+     * const { mfa: sessionId } = await auth.password.forgot(email);
+     * // prompt user for code
+     * ```
+     */
+    forgot(baseUrl: string, email: string): Promise<ForgotPasswordResponse>;
+    /**
+     * Completes the forgot-password flow by verifying the emailed code
+     * and setting the new password.
+     */
+    confirmForgot(baseUrl: string, input: ForgotPasswordConfirmInput): Promise<GenericSuccessResponse>;
+}
+
+/**
+ * Multi-tenant SSO (Single Sign-On) methods.
+ *
+ * Two roles exist:
+ *
+ *   Organization Admin  → registers their company IDP via `registerProvider()`.
+ *   End User            → signs in through their company's IDP via `signIn()`.
+ *
+ * Sign-in flow:
+ *   1. Call `signIn(email)` → server resolves the org and returns a redirect URL.
+ *   2. Redirect the user to `auth_url` to complete sign-in with their IDP.
+ *
+ * ```ts
+ * const { auth_url } = await auth.sso.signIn(email);
+ * window.location.href = auth_url;
+ * ```
+ */
+declare class SsoAuth {
+    /**
+     * Registers an organisation's Identity Provider (IDP) with the auth system.
+     * This is typically called once by an organisation admin during onboarding.
+     */
+    registerProvider(baseUrl: string, input: SsoRegisterInput): Promise<GenericSuccessResponse>;
+    /**
+     * Starts the SSO sign-in flow for an end user.
+     *
+     * The server resolves the correct IDP from the user's email domain
+     * and returns a redirect URL.  Redirect the user to that URL to
+     * complete sign-in with their organisation's IDP.
+     */
+    signIn(baseUrl: string, email: string): Promise<SsoStartResponse>;
+}
+
+/**
+ * Email MFA management.
+ *
+ * These methods manage whether a user has Email MFA enabled on their account.
+ * They are separate from the sign-in verify step (see EmailPasswordAuth.verifyMfa).
+ */
+declare class EmailMfaManager {
+    /**
+     * Enables Email MFA for the currently authenticated user.
+     * Once enabled, future sign-ins will require a one-time code sent to email.
+     */
+    create(baseUrl: string): Promise<void>;
+    /**
+     * Disables Email MFA for the currently authenticated user.
+     */
+    delete(baseUrl: string): Promise<void>;
+}
+
+/**
+ * Social / OAuth provider sign-in methods.
+ *
+ * Each method redirects the browser to the provider's OAuth flow.
+ * After successful authentication the server will redirect back to
+ * your application with a session cookie (or access token, depending
+ * on your server configuration).
+ *
+ * These are simple redirects — no async call is needed.
+ */
+declare class SocialAuth {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    /** Redirects to Google OAuth sign-in. */
+    signInWithGoogle(): void;
+    /** Redirects to GitHub OAuth sign-in. */
+    signInWithGithub(): void;
+    /** Redirects to LinkedIn OAuth sign-in. */
+    signInWithLinkedIn(): void;
+    /** Redirects to Okta OAuth sign-in. */
+    signInWithOkta(): void;
+}
+
+/**
+ * AuthClient
+ *
+ * The single entry point for the JobTrk auth SDK.
+ * Framework-agnostic — works in React, Vue, Svelte, vanilla JS, etc.
+ *
+ * ── Quick start ──────────────────────────────────────────────────────
+ *
+ * ```ts
+ * import { AuthClient, SignInStatus } from "jobtrk-auth-sdk";
+ *
+ * const auth = new AuthClient({ baseUrl: "https://auth.yourapp.com" });
+ *
+ * // Restore session on app startup
+ * const user = await auth.token.refresh();
+ *
+ * // Social sign-in
+ * auth.social.signInWithGoogle();
+ *
+ * // Email + password sign-in (with MFA branching)
+ * const result = await auth.email.signIn({ email, password });
+ * if (result.status === SignInStatus.MFA_REQUIRED) { ... }
+ * if (result.status === SignInStatus.TOTP_REQUIRED) { ... }
+ *
+ * // Magic link
+ * const { mfa: sessionId } = await auth.magicLink.send(email);
+ * await auth.magicLink.verify({ sessionId, code });
+ *
+ * // SSO
+ * const { auth_url } = await auth.sso.signIn(email);
+ * window.location.href = auth_url;
+ * ```
+ */
+declare class AuthClient {
+    private readonly baseUrl;
+    /** JWT access token management and refresh */
+    readonly token: TokenManager;
+    /** Session-based auth helpers (getUser, verifySession) */
+    readonly session: SessionManager;
+    /** Social / OAuth redirects (Google, GitHub, LinkedIn, Okta) */
+    readonly social: SocialAuth;
+    /** Email + password sign-up, sign-in, and MFA verify */
+    readonly email: EmailPasswordAuth;
+    /** Email magic-link send and verify */
+    readonly magicLink: MagicLinkAuth;
+    /** TOTP setup, confirm, sign-in verify, and delete */
+    readonly totp: TotpAuth;
+    /** Email MFA enable / disable */
+    readonly emailMfa: EmailMfaManager;
+    /** Password reset (authenticated) and forgot-password flow */
+    readonly password: PasswordAuth;
+    /** Multi-tenant SSO provider registration and sign-in */
+    readonly sso: SsoAuth;
+    constructor(config?: AuthClientConfig);
+    /**
+     * Signs the user out of the current session/device.
+     * Clears the in-memory access token after a successful server response.
+     */
+    logout(): Promise<void>;
+    /**
+     * Signs the user out of ALL active sessions / devices.
+     * Clears the in-memory access token after a successful server response.
+     */
+    logoutAllSessions(): Promise<void>;
+}
+type BoundModule<T extends object> = {
+    [K in keyof T]: T[K] extends (baseUrl: string, ...args: infer A) => infer R ? (...args: A) => R : T[K];
+};
+/**
+ * Creates an `AuthClient` where all sub-module methods have the `baseUrl`
+ * argument pre-bound.  This is the recommended way to instantiate the SDK.
+ *
+ * ```ts
+ * const auth = createAuthClient({ baseUrl: "https://auth.yourapp.com" });
+ *
+ * // No need to pass baseUrl to individual methods:
+ * await auth.email.signIn({ email, password });
+ * await auth.token.refresh();
+ * ```
+ */
+declare function createAuthClient(config?: AuthClientConfig): {
+    token: BoundModule<TokenManager>;
+    session: BoundModule<SessionManager>;
+    email: BoundModule<EmailPasswordAuth>;
+    magicLink: BoundModule<MagicLinkAuth>;
+    totp: BoundModule<TotpAuth>;
+    emailMfa: BoundModule<EmailMfaManager>;
+    password: BoundModule<PasswordAuth>;
+    sso: BoundModule<SsoAuth>;
+    social: SocialAuth;
+    logout: () => Promise<void>;
+    logoutAllSessions: () => Promise<void>;
+};
+type BoundAuthClient = ReturnType<typeof createAuthClient>;
+
+declare class AuthError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+
+export { AuthClient, type AuthClientConfig, AuthError, type AuthUser, type BoundAuthClient, type EmailPasswordCredentials, type ForgotPasswordConfirmInput, type ForgotPasswordResponse, type GenericSuccessResponse, type JwtPayload, type MagicLinkResponse, type MfaVerifyInput, type RefreshTokenResponse, type ResetPasswordInput, type SignInResponse, SignInStatus, type SsoRegisterInput, type SsoStartResponse, type TotpSetupResponse, createAuthClient };

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { AuthClient, createAuthClient } from "./client";
+export type { BoundAuthClient } from "./client";
+export { AuthError } from "./http";
+export type { AuthUser, JwtPayload, AuthClientConfig, EmailPasswordCredentials, MfaVerifyInput, ResetPasswordInput, ForgotPasswordConfirmInput, SsoRegisterInput, SignInResponse, MagicLinkResponse, ForgotPasswordResponse, TotpSetupResponse, SsoStartResponse, RefreshTokenResponse, GenericSuccessResponse, } from "./types";
+export { SignInStatus } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAGhD,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAGnC,YAAY,EACV,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,wBAAwB,EACxB,cAAc,EACd,kBAAkB,EAClB,0BAA0B,EAC1B,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC"}