@nexusrt/nexus-auth 1.0.0

package/README.md

@@ -0,0 +1,277 @@
+# JobTrk Auth SDK
+
+A universal, framework-agnostic TypeScript SDK for the JobTrk authentication system.  
+Works in React, Vue, Svelte, Angular, vanilla JS — anywhere that runs in a browser.
+
+---
+
+## Installation
+
+```bash
+npm install jobtrk-auth-sdk
+```
+
+---
+
+## Quick Start
+
+```ts
+import { createAuthClient, SignInStatus } from "jobtrk-auth-sdk";
+
+const auth = createAuthClient({
+  baseUrl: "https://auth.yourapp.com", // defaults to https://auth.jobtrk.com
+});
+```
+
+> **`createAuthClient` is the recommended way to use the SDK.**  
+> It pre-binds `baseUrl` to every method so you never need to pass it manually.
+
+---
+
+## Session Modes
+
+The SDK supports two ways to persist a login:
+
+| Mode | How it works | When to use |
+|---|---|---|
+| **JWT** | Server returns an `access_token` + sets an HttpOnly refresh-token cookie | Stateless APIs, microservices |
+| **Session** | Server sets an HttpOnly session cookie | Traditional server-rendered apps |
+
+In both modes an **access token** is available so you can authenticate with downstream services.
+
+### Restore session on app startup
+
+```ts
+// JWT mode — uses the HttpOnly refresh-token cookie to get a new access token
+const user = await auth.token.refresh();
+if (user) {
+  console.log("Logged in as", user.email);
+}
+
+// Session mode — read the current user from the server
+const user = await auth.session.getUser();
+```
+
+---
+
+## Social Sign-In
+
+Redirects the browser to the provider's OAuth flow.
+
+```ts
+auth.social.signInWithGoogle();
+auth.social.signInWithGithub();
+auth.social.signInWithLinkedIn();
+auth.social.signInWithOkta();
+```
+
+---
+
+## Email + Password
+
+### Sign up
+
+```ts
+await auth.email.signUp({ email, password });
+```
+
+### Sign in (no MFA)
+
+```ts
+const result = await auth.email.signIn({ email, password });
+// result.access_token is set — user is signed in
+```
+
+### Sign in with Email MFA
+
+```ts
+const result = await auth.email.signIn({ email, password });
+
+if (result.status === SignInStatus.MFA_REQUIRED) {
+  const sessionId = result.mfa!;
+
+  // Prompt the user for the code emailed to them
+  await auth.email.verifyMfa({ sessionId, code: userEnteredCode });
+}
+```
+
+### Sign in with TOTP
+
+```ts
+const result = await auth.email.signIn({ email, password });
+
+if (result.status === SignInStatus.TOTP_REQUIRED) {
+  const sessionId = result.mfa!;
+
+  // Prompt the user for their authenticator app code
+  await auth.totp.verifySignIn({ sessionId, code: userEnteredCode });
+}
+```
+
+---
+
+## Email Magic Link
+
+```ts
+// 1. Send the magic link
+const { mfa: sessionId } = await auth.magicLink.send(email);
+
+// 2. User receives an email with a code — verify it
+await auth.magicLink.verify({ sessionId, code: userEnteredCode });
+```
+
+---
+
+## SSO (Multi-Tenant)
+
+### Organisation admin — register your IDP once
+
+```ts
+await auth.sso.registerProvider({
+  providerName:     "Acme Corp",
+  providerEndEmail: "acme.com",
+  clientId:         "...",
+  clientSecret:     "...",
+  issuer:           "https://idp.acme.com",
+  callbackUrl:      "https://yourapp.com/auth/callback",
+});
+```
+
+### End user — sign in via their org's IDP
+
+```ts
+const { auth_url } = await auth.sso.signIn(email);
+window.location.href = auth_url; // redirect to org's IDP
+```
+
+---
+
+## Password Management
+
+### Reset password (authenticated user)
+
+```ts
+await auth.password.reset({
+  oldPassword: "current-password",
+  newPassword: "new-password",
+});
+```
+
+### Forgot password
+
+```ts
+// 1. Send reset code to email
+const { mfa: sessionId } = await auth.password.forgot(email);
+
+// 2. User enters code from email
+await auth.password.confirmForgot({
+  sessionId,
+  code:     userEnteredCode,
+  password: newPassword,
+});
+```
+
+---
+
+## TOTP Setup
+
+```ts
+// 1. Start registration — display the QR code / secret to the user
+const { totp } = await auth.totp.setup();
+// totp = QR code data or secret string — render as a QR code
+
+// 2. User scans with their authenticator app and enters the first code
+await auth.totp.confirmSetup(userEnteredCode);
+
+// Remove TOTP from account
+await auth.totp.delete();
+```
+
+---
+
+## Email MFA Management
+
+```ts
+await auth.emailMfa.create(); // enable email MFA
+await auth.emailMfa.delete(); // disable email MFA
+```
+
+---
+
+## Logout
+
+```ts
+await auth.logout();             // sign out of current session
+await auth.logoutAllSessions();  // sign out of all devices
+```
+
+---
+
+## Status Codes
+
+Import `SignInStatus` to compare against sign-in responses:
+
+```ts
+import { SignInStatus } from "jobtrk-auth-sdk";
+
+SignInStatus.MFA_REQUIRED   // Email OTP challenge required
+SignInStatus.TOTP_REQUIRED  // TOTP challenge required
+SignInStatus.MAGIC_LINK     // Magic link sent
+SignInStatus.RESET_PASSWORD // Password reset code sent
+SignInStatus.SUCCESS        // No MFA — user is signed in
+```
+
+---
+
+## Error Handling
+
+All methods throw an `AuthError` on failure:
+
+```ts
+import { AuthError } from "jobtrk-auth-sdk";
+
+try {
+  await auth.email.signIn({ email, password });
+} catch (err) {
+  if (err instanceof AuthError) {
+    console.error(err.message); // human-readable message
+    console.error(err.status);  // HTTP status code
+    console.error(err.body);    // raw response body
+  }
+}
+```
+
+---
+
+## React Example
+
+```tsx
+import { createAuthClient, SignInStatus, AuthError } from "jobtrk-auth-sdk";
+import { useEffect, useState } from "react";
+
+const auth = createAuthClient({ baseUrl: "https://auth.yourapp.com" });
+
+export function useAuth() {
+  const [user, setUser] = useState(null);
+
+  // Restore session on mount
+  useEffect(() => {
+    auth.token.refresh().then(setUser);
+  }, []);
+
+  const signIn = async (email: string, password: string) => {
+    const result = await auth.email.signIn({ email, password });
+    if (!result.status) {
+      setUser(auth.token.getUserFromToken());
+    }
+    return result; // caller handles MFA branching
+  };
+
+  const logout = async () => {
+    await auth.logout();
+    setUser(null);
+  };
+
+  return { user, signIn, logout, auth };
+}
+```

package/dist/client.d.ts

@@ -0,0 +1,106 @@
+import { TokenManager } from "./methods/token";
+import { SessionManager } from "./methods/session";
+import { EmailPasswordAuth } from "./methods/emailPassword";
+import { MagicLinkAuth } from "./methods/magicLink";
+import { TotpAuth } from "./methods/totp";
+import { PasswordAuth } from "./methods/password";
+import { SsoAuth } from "./methods/sso";
+import { EmailMfaManager } from "./methods/emailMfa";
+import { SocialAuth } from "./providers/social";
+import type { AuthClientConfig } from "./types";
+/**
+ * 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;
+ * ```
+ */
+export 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();
+ * ```
+ */
+export 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>;
+};
+export type BoundAuthClient = ReturnType<typeof createAuthClient>;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAIjC,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAE7B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAE5B,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAElC,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAElC,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAExB,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IAEnC,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAEhC,yDAAyD;IACzD,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;gBAEV,MAAM,GAAE,gBAAqB;IAgBzC;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAK7B;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;CAazC;AAWD,KAAK,WAAW,CAAC,CAAC,SAAS,MAAM,IAAI;KAClC,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,GACvE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,GACjB,CAAC,CAAC,CAAC,CAAC;CACT,CAAC;AAoBF;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,gBAAqB;;;;;;;;;;;;EAkB7D;AAED,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Lightweight fetch wrapper used internally by the SDK.
+ * All requests automatically include credentials (cookies) for session support.
+ */
+export declare function request<T>(url: string, options?: RequestInit): Promise<T>;
+export declare class AuthError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,CAAC,CAAC,CAoBZ;AAMD,qBAAa,SAAU,SAAQ,KAAK;aAGhB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,OAAO;gBAF7B,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,OAAc;CAKvC"}