@korajs/auth 0.1.0

package/dist/index.cjs

@@ -0,0 +1,740 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthClient: () => AuthClient,
+  AuthError: () => AuthError,
+  CryptoUnavailableError: () => CryptoUnavailableError,
+  DeviceIdentityError: () => DeviceIdentityError,
+  TokenStore: () => TokenStore,
+  computePublicKeyThumbprint: () => computePublicKeyThumbprint,
+  exportPublicKeyJwk: () => exportPublicKeyJwk,
+  fromBase64Url: () => fromBase64Url,
+  generateDeviceKeyPair: () => generateDeviceKeyPair,
+  signChallenge: () => signChallenge,
+  toBase64Url: () => toBase64Url,
+  verifyChallenge: () => verifyChallenge
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client/auth-client.ts
+var import_core = require("@korajs/core");
+var AuthError = class extends import_core.KoraError {
+  constructor(message, code, context) {
+    super(message, code, context);
+    this.name = "AuthError";
+  }
+};
+var EXPIRY_BUFFER_SECONDS = 30;
+function decodeJwtPayload(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    return null;
+  }
+  try {
+    const base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const json = atob(base64);
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+function isTokenExpired(token) {
+  const payload = decodeJwtPayload(token);
+  if (!payload || typeof payload["exp"] !== "number") {
+    return true;
+  }
+  const nowSeconds = Math.floor(Date.now() / 1e3);
+  return payload["exp"] <= nowSeconds + EXPIRY_BUFFER_SECONDS;
+}
+function getUserIdFromToken(token) {
+  const payload = decodeJwtPayload(token);
+  if (!payload || typeof payload["sub"] !== "string") {
+    return null;
+  }
+  return payload["sub"];
+}
+function createTokenStorage(prefix) {
+  let useLocalStorage = false;
+  try {
+    if (typeof window !== "undefined" && typeof window.localStorage !== "undefined") {
+      const testKey = `${prefix}_test`;
+      window.localStorage.setItem(testKey, "1");
+      window.localStorage.removeItem(testKey);
+      useLocalStorage = true;
+    }
+  } catch {
+  }
+  if (useLocalStorage) {
+    const accessKey = `${prefix}_access_token`;
+    const refreshKey = `${prefix}_refresh_token`;
+    return {
+      getAccessToken() {
+        return window.localStorage.getItem(accessKey);
+      },
+      getRefreshToken() {
+        return window.localStorage.getItem(refreshKey);
+      },
+      setTokens(access, refresh) {
+        window.localStorage.setItem(accessKey, access);
+        window.localStorage.setItem(refreshKey, refresh);
+      },
+      clear() {
+        window.localStorage.removeItem(accessKey);
+        window.localStorage.removeItem(refreshKey);
+      }
+    };
+  }
+  let accessToken = null;
+  let refreshToken = null;
+  return {
+    getAccessToken() {
+      return accessToken;
+    },
+    getRefreshToken() {
+      return refreshToken;
+    },
+    setTokens(access, refresh) {
+      accessToken = access;
+      refreshToken = refresh;
+    },
+    clear() {
+      accessToken = null;
+      refreshToken = null;
+    }
+  };
+}
+var AuthClient = class {
+  serverUrl;
+  storage;
+  listeners = /* @__PURE__ */ new Set();
+  _state = "loading";
+  _user = null;
+  _refreshPromise = null;
+  /**
+   * Creates a new AuthClient.
+   *
+   * @param config - Auth client configuration
+   */
+  constructor(config) {
+    this.serverUrl = config.serverUrl.replace(/\/+$/, "");
+    const prefix = config.storageKey ?? "kora_auth";
+    this.storage = createTokenStorage(prefix);
+  }
+  // -----------------------------------------------------------------------
+  // Public getters
+  // -----------------------------------------------------------------------
+  /** Current authentication state. */
+  get state() {
+    return this._state;
+  }
+  /** Current authenticated user, or null if not signed in. */
+  get currentUser() {
+    return this._user;
+  }
+  /** Whether the user is currently authenticated. */
+  get isAuthenticated() {
+    return this._state === "authenticated";
+  }
+  // -----------------------------------------------------------------------
+  // Initialization
+  // -----------------------------------------------------------------------
+  /**
+   * Initialize the auth client by restoring a session from stored tokens.
+   *
+   * Loads tokens from storage, validates the access token, and attempts a
+   * refresh if the access token is expired but a refresh token is available.
+   * Safe to call multiple times -- subsequent calls are no-ops once initialized.
+   */
+  async initialize() {
+    const accessToken = this.storage.getAccessToken();
+    const refreshToken = this.storage.getRefreshToken();
+    if (!accessToken || !refreshToken) {
+      this.setState("unauthenticated", null);
+      return;
+    }
+    if (!isTokenExpired(accessToken)) {
+      await this.restoreSession(accessToken);
+      return;
+    }
+    try {
+      const newAccessToken = await this.refreshAccessToken(refreshToken);
+      if (newAccessToken) {
+        await this.restoreSession(newAccessToken);
+        return;
+      }
+    } catch {
+    }
+    this.storage.clear();
+    this.setState("unauthenticated", null);
+  }
+  // -----------------------------------------------------------------------
+  // Sign up / Sign in / Sign out
+  // -----------------------------------------------------------------------
+  /**
+   * Register a new user account.
+   *
+   * @param params - Sign-up credentials
+   * @returns The newly created AuthUser
+   * @throws {AuthError} If the request fails or the server returns an error
+   */
+  async signUp(params) {
+    const response = await this.request("/auth/signup", {
+      method: "POST",
+      body: params
+    });
+    this.storage.setTokens(response.accessToken, response.refreshToken);
+    const user = await this.fetchUserProfile(response.accessToken);
+    this.setState("authenticated", user);
+    return user;
+  }
+  /**
+   * Sign in with email and password.
+   *
+   * @param params - Sign-in credentials
+   * @returns The authenticated AuthUser
+   * @throws {AuthError} If the credentials are invalid or the request fails
+   */
+  async signIn(params) {
+    const response = await this.request("/auth/signin", {
+      method: "POST",
+      body: params
+    });
+    this.storage.setTokens(response.accessToken, response.refreshToken);
+    const user = await this.fetchUserProfile(response.accessToken);
+    this.setState("authenticated", user);
+    return user;
+  }
+  /**
+   * Sign out the current user.
+   *
+   * Clears local tokens and state. Does not make a network request to the
+   * server -- tokens are simply discarded locally.
+   */
+  async signOut() {
+    this.storage.clear();
+    this._refreshPromise = null;
+    this.setState("unauthenticated", null);
+  }
+  // -----------------------------------------------------------------------
+  // Token access
+  // -----------------------------------------------------------------------
+  /**
+   * Get a valid access token, automatically refreshing if expired.
+   *
+   * @returns A valid access token string, or null if the user is not
+   *          authenticated and refresh is not possible
+   */
+  async getAccessToken() {
+    const accessToken = this.storage.getAccessToken();
+    if (accessToken && !isTokenExpired(accessToken)) {
+      return accessToken;
+    }
+    const refreshToken = this.storage.getRefreshToken();
+    if (!refreshToken) {
+      return null;
+    }
+    try {
+      const newAccessToken = await this.refreshAccessToken(refreshToken);
+      return newAccessToken;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get a valid token for the sync engine handshake.
+   * Alias for {@link getAccessToken}.
+   *
+   * @returns A valid access token string, or null if unavailable
+   */
+  async getSyncToken() {
+    return this.getAccessToken();
+  }
+  // -----------------------------------------------------------------------
+  // State change subscriptions
+  // -----------------------------------------------------------------------
+  /**
+   * Subscribe to authentication state changes.
+   *
+   * The callback is invoked whenever the auth state transitions (e.g., from
+   * 'unauthenticated' to 'authenticated' on sign-in).
+   *
+   * @param callback - Function called with the new AuthState on each change
+   * @returns An unsubscribe function that removes the listener
+   *
+   * @example
+   * ```typescript
+   * const unsub = auth.onAuthChange((state) => {
+   *   console.log('Auth state changed to:', state)
+   * })
+   * // Later: unsub()
+   * ```
+   */
+  onAuthChange(callback) {
+    this.listeners.add(callback);
+    return () => {
+      this.listeners.delete(callback);
+    };
+  }
+  // -----------------------------------------------------------------------
+  // Internal helpers
+  // -----------------------------------------------------------------------
+  /**
+   * Update internal state and notify all listeners.
+   */
+  setState(state, user) {
+    const changed = this._state !== state || this._user !== user;
+    this._state = state;
+    this._user = user;
+    if (changed) {
+      for (const listener of this.listeners) {
+        try {
+          listener(state);
+        } catch {
+        }
+      }
+    }
+  }
+  /**
+   * Restore a session from a valid access token by fetching the user profile.
+   * Falls back to extracting the user ID from the token payload if the
+   * /auth/me request fails (offline scenario).
+   */
+  async restoreSession(accessToken) {
+    try {
+      const user = await this.fetchUserProfile(accessToken);
+      this.setState("authenticated", user);
+    } catch {
+      const userId = getUserIdFromToken(accessToken);
+      if (userId) {
+        this.setState("authenticated", {
+          id: userId,
+          email: "",
+          name: null
+        });
+      } else {
+        this.storage.clear();
+        this.setState("unauthenticated", null);
+      }
+    }
+  }
+  /**
+   * Fetch the current user profile from the server.
+   */
+  async fetchUserProfile(accessToken) {
+    const profile = await this.request("/auth/me", {
+      method: "GET",
+      token: accessToken
+    });
+    return {
+      id: profile.id,
+      email: profile.email,
+      name: profile.name ?? null
+    };
+  }
+  /**
+   * Refresh the access token using a refresh token.
+   * De-duplicates concurrent refresh calls so only one network request is made.
+   */
+  async refreshAccessToken(refreshToken) {
+    if (this._refreshPromise) {
+      return this._refreshPromise;
+    }
+    this._refreshPromise = this.performRefresh(refreshToken);
+    try {
+      const result = await this._refreshPromise;
+      return result;
+    } finally {
+      this._refreshPromise = null;
+    }
+  }
+  /**
+   * Execute the token refresh network request.
+   */
+  async performRefresh(refreshToken) {
+    try {
+      const response = await this.request("/auth/refresh", {
+        method: "POST",
+        body: { refreshToken }
+      });
+      this.storage.setTokens(response.accessToken, response.refreshToken);
+      return response.accessToken;
+    } catch {
+      this.storage.clear();
+      this.setState("unauthenticated", null);
+      return null;
+    }
+  }
+  /**
+   * Make an HTTP request to the auth server.
+   *
+   * @param path - URL path relative to serverUrl (e.g. '/auth/signin')
+   * @param options - Request options
+   * @returns Parsed JSON response body
+   * @throws {AuthError} On network failure or non-2xx response
+   */
+  async request(path, options) {
+    const url = `${this.serverUrl}${path}`;
+    const headers = {};
+    if (options.body) {
+      headers["Content-Type"] = "application/json";
+    }
+    if (options.token) {
+      headers["Authorization"] = `Bearer ${options.token}`;
+    }
+    let response;
+    try {
+      response = await fetch(url, {
+        method: options.method,
+        headers,
+        body: options.body ? JSON.stringify(options.body) : void 0
+      });
+    } catch (cause) {
+      throw new AuthError(
+        `Network request to ${path} failed. The auth server at ${this.serverUrl} may be unreachable. Check your network connection and serverUrl configuration.`,
+        "AUTH_NETWORK_ERROR",
+        { path, cause: cause instanceof Error ? cause.message : String(cause) }
+      );
+    }
+    if (!response.ok) {
+      let errorMessage = `Auth server returned HTTP ${response.status}`;
+      let serverError;
+      try {
+        const body = await response.json();
+        if (typeof body["error"] === "string") {
+          errorMessage = body["error"];
+          serverError = errorMessage;
+        } else if (typeof body["message"] === "string") {
+          errorMessage = body["message"];
+          serverError = errorMessage;
+        }
+      } catch {
+      }
+      throw new AuthError(
+        errorMessage,
+        "AUTH_SERVER_ERROR",
+        { path, status: response.status, serverError }
+      );
+    }
+    const data = await response.json();
+    return data;
+  }
+};
+
+// src/device/device-identity.ts
+var import_core2 = require("@korajs/core");
+var CryptoUnavailableError = class extends import_core2.KoraError {
+  constructor() {
+    super(
+      "Web Crypto API (crypto.subtle) is not available in this environment. Device identity requires crypto.subtle, which is available in modern browsers and Node.js 20+. If running in SSR, ensure your runtime provides the Web Crypto API.",
+      "CRYPTO_UNAVAILABLE"
+    );
+    this.name = "CryptoUnavailableError";
+  }
+};
+var DeviceIdentityError = class extends import_core2.KoraError {
+  constructor(message, context) {
+    super(message, "DEVICE_IDENTITY_ERROR", context);
+    this.name = "DeviceIdentityError";
+  }
+};
+function toBase64Url(buffer) {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(str) {
+  let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+  const paddingNeeded = (4 - base64.length % 4) % 4;
+  base64 += "=".repeat(paddingNeeded);
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+function assertCryptoAvailable() {
+  if (typeof globalThis.crypto === "undefined" || typeof globalThis.crypto.subtle === "undefined") {
+    throw new CryptoUnavailableError();
+  }
+}
+var ECDSA_ALGORITHM = {
+  name: "ECDSA",
+  namedCurve: "P-256"
+};
+var ECDSA_SIGN_ALGORITHM = {
+  name: "ECDSA",
+  hash: { name: "SHA-256" }
+};
+async function generateDeviceKeyPair() {
+  assertCryptoAvailable();
+  try {
+    const keyPair = await globalThis.crypto.subtle.generateKey(
+      ECDSA_ALGORITHM,
+      // extractable: false makes the private key non-extractable.
+      // The public key is always extractable regardless of this flag.
+      false,
+      ["sign", "verify"]
+    );
+    return keyPair;
+  } catch (cause) {
+    throw new DeviceIdentityError(
+      "Failed to generate ECDSA P-256 device key pair. Ensure the runtime supports the ECDSA algorithm with the P-256 curve.",
+      { cause: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+}
+async function exportPublicKeyJwk(keyPair) {
+  assertCryptoAvailable();
+  try {
+    const jwk = await globalThis.crypto.subtle.exportKey("jwk", keyPair.publicKey);
+    return jwk;
+  } catch (cause) {
+    throw new DeviceIdentityError(
+      "Failed to export public key as JWK. The key pair may be invalid or the public key may not support JWK export.",
+      { cause: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+}
+async function signChallenge(privateKey, challenge) {
+  assertCryptoAvailable();
+  try {
+    const encoded = new TextEncoder().encode(challenge);
+    const signatureBuffer = await globalThis.crypto.subtle.sign(
+      ECDSA_SIGN_ALGORITHM,
+      privateKey,
+      encoded
+    );
+    return toBase64Url(signatureBuffer);
+  } catch (cause) {
+    throw new DeviceIdentityError(
+      'Failed to sign challenge. Ensure the key is a valid ECDSA P-256 private key with "sign" usage.',
+      { cause: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+}
+async function verifyChallenge(publicKeyJwk, challenge, signature) {
+  assertCryptoAvailable();
+  try {
+    const publicKey = await globalThis.crypto.subtle.importKey(
+      "jwk",
+      publicKeyJwk,
+      ECDSA_ALGORITHM,
+      true,
+      ["verify"]
+    );
+    const encoded = new TextEncoder().encode(challenge);
+    const signatureBytes = fromBase64Url(signature);
+    const isValid = await globalThis.crypto.subtle.verify(
+      ECDSA_SIGN_ALGORITHM,
+      publicKey,
+      signatureBytes,
+      encoded
+    );
+    return isValid;
+  } catch (cause) {
+    throw new DeviceIdentityError(
+      "Failed to verify challenge signature. The public key JWK or signature format may be invalid.",
+      {
+        cause: cause instanceof Error ? cause.message : String(cause),
+        publicKeyKty: publicKeyJwk.kty,
+        publicKeyCrv: publicKeyJwk.crv
+      }
+    );
+  }
+}
+async function computePublicKeyThumbprint(publicKeyJwk) {
+  assertCryptoAvailable();
+  if (publicKeyJwk.kty !== "EC") {
+    throw new DeviceIdentityError(
+      `Expected JWK key type "EC" but received "${publicKeyJwk.kty ?? "undefined"}". Only ECDSA public keys are supported for device identity.`,
+      { kty: publicKeyJwk.kty }
+    );
+  }
+  if (!publicKeyJwk.crv || !publicKeyJwk.x || !publicKeyJwk.y) {
+    throw new DeviceIdentityError(
+      'JWK is missing required EC fields. An EC public key JWK must include "crv", "x", and "y" members.',
+      {
+        hasCrv: Boolean(publicKeyJwk.crv),
+        hasX: Boolean(publicKeyJwk.x),
+        hasY: Boolean(publicKeyJwk.y)
+      }
+    );
+  }
+  const canonicalJson = JSON.stringify({
+    crv: publicKeyJwk.crv,
+    kty: publicKeyJwk.kty,
+    x: publicKeyJwk.x,
+    y: publicKeyJwk.y
+  });
+  try {
+    const encoded = new TextEncoder().encode(canonicalJson);
+    const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", encoded);
+    return toBase64Url(hashBuffer);
+  } catch (cause) {
+    throw new DeviceIdentityError(
+      "Failed to compute SHA-256 thumbprint of the public key JWK.",
+      { cause: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+}
+
+// src/tokens/token-store.ts
+var DEFAULT_STORAGE_KEY = "kora_auth_tokens";
+var MemoryStorage = class {
+  store = /* @__PURE__ */ new Map();
+  getItem(key) {
+    return this.store.get(key) ?? null;
+  }
+  setItem(key, value) {
+    this.store.set(key, value);
+  }
+  removeItem(key) {
+    this.store.delete(key);
+  }
+};
+function tryGetLocalStorage() {
+  try {
+    if (typeof globalThis !== "undefined" && "localStorage" in globalThis) {
+      const storage = globalThis.localStorage;
+      const testKey = "__kora_storage_test__";
+      storage.setItem(testKey, "1");
+      storage.removeItem(testKey);
+      return storage;
+    }
+  } catch {
+  }
+  return null;
+}
+var TokenStore = class {
+  storageKey;
+  storage;
+  /**
+   * Creates a new TokenStore instance.
+   *
+   * @param storageKey - The key under which tokens are stored. Defaults to 'kora_auth_tokens'.
+   *   Use different keys if your app runs multiple Kora instances with separate auth.
+   */
+  constructor(storageKey) {
+    this.storageKey = storageKey ?? DEFAULT_STORAGE_KEY;
+    this.storage = tryGetLocalStorage() ?? new MemoryStorage();
+  }
+  /**
+   * Save tokens to persistent storage.
+   *
+   * Overwrites any previously stored tokens. The tokens are serialized
+   * as JSON. Only the `accessToken`, `refreshToken`, and optional
+   * `deviceCredential` fields are persisted.
+   *
+   * @param tokens - The token set to store
+   */
+  saveTokens(tokens) {
+    const serialized = {
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken
+    };
+    if (tokens.deviceCredential !== void 0) {
+      serialized.deviceCredential = tokens.deviceCredential;
+    }
+    this.storage.setItem(this.storageKey, JSON.stringify(serialized));
+  }
+  /**
+   * Load tokens from storage.
+   *
+   * @returns The stored {@link AuthTokens}, or null if no tokens have been saved
+   */
+  loadTokens() {
+    const raw = this.storage.getItem(this.storageKey);
+    if (raw === null) {
+      return null;
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return null;
+      }
+      const record = parsed;
+      if (typeof record["accessToken"] !== "string" || typeof record["refreshToken"] !== "string") {
+        return null;
+      }
+      const tokens = {
+        accessToken: record["accessToken"],
+        refreshToken: record["refreshToken"]
+      };
+      if (typeof record["deviceCredential"] === "string") {
+        tokens.deviceCredential = record["deviceCredential"];
+      }
+      return tokens;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Clear all stored tokens.
+   *
+   * Call this on logout to remove credentials from persistent storage.
+   */
+  clearTokens() {
+    this.storage.removeItem(this.storageKey);
+  }
+  /**
+   * Get the current access token.
+   *
+   * Returns the raw token string without validating expiration.
+   * The caller is responsible for checking whether the token is
+   * still valid and initiating a refresh if needed.
+   *
+   * @returns The access token string, or null if no tokens are stored
+   */
+  getAccessToken() {
+    const tokens = this.loadTokens();
+    return tokens?.accessToken ?? null;
+  }
+  /**
+   * Get the current refresh token.
+   *
+   * @returns The refresh token string, or null if no tokens are stored
+   */
+  getRefreshToken() {
+    const tokens = this.loadTokens();
+    return tokens?.refreshToken ?? null;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthClient,
+  AuthError,
+  CryptoUnavailableError,
+  DeviceIdentityError,
+  TokenStore,
+  computePublicKeyThumbprint,
+  exportPublicKeyJwk,
+  fromBase64Url,
+  generateDeviceKeyPair,
+  signChallenge,
+  toBase64Url,
+  verifyChallenge
+});
+//# sourceMappingURL=index.cjs.map