@serafort/core 0.1.0

package/dist/index.js

@@ -0,0 +1,634 @@
+// src/errors.ts
+var SerafortError = class extends Error {
+  code;
+  status;
+  details;
+  constructor(message, code = "SERAFORT_ERROR", status = 500, details = []) {
+    super(message);
+    this.name = "SerafortError";
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthenticationError = class extends SerafortError {
+  constructor(message = "Authentication failed or session is invalid.", code = "AUTHENTICATION_ERROR", details = []) {
+    super(message, code, 401, details);
+    this.name = "AuthenticationError";
+  }
+};
+var MfaRequiredError = class extends SerafortError {
+  challengeId;
+  supportedMethods;
+  constructor(message = "Multi-factor authentication required.", challengeId, supportedMethods, details = []) {
+    super(message, "MFA_REQUIRED", 403, details);
+    this.name = "MfaRequiredError";
+    this.challengeId = challengeId;
+    this.supportedMethods = supportedMethods;
+  }
+};
+var ValidationError = class extends SerafortError {
+  constructor(message = "Validation failed on input parameters.", details = []) {
+    super(message, "VALIDATION_ERROR", 422, details);
+    this.name = "ValidationError";
+  }
+};
+var RateLimitError = class extends SerafortError {
+  retryAfterSeconds;
+  constructor(message = "Rate limit exceeded. Please slow down requests.", retryAfterSeconds, details = []) {
+    super(message, "RATE_LIMIT_EXCEEDED", 429, details);
+    this.name = "RateLimitError";
+    this.retryAfterSeconds = retryAfterSeconds;
+  }
+};
+var NotFoundError = class extends SerafortError {
+  constructor(message = "Resource not found.", code = "NOT_FOUND", details = []) {
+    super(message, code, 404, details);
+    this.name = "NotFoundError";
+  }
+};
+var NetworkError = class extends SerafortError {
+  constructor(message = "Failed to connect to Serafort IAM service.", cause) {
+    super(message, "NETWORK_ERROR", 0);
+    this.name = "NetworkError";
+    if (cause) {
+      this.cause = cause;
+    }
+  }
+};
+
+// src/utils/jwt.ts
+function base64UrlToBytes(str) {
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(str, "base64url"));
+  }
+  let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = base64.length % 4;
+  if (pad === 2) {
+    base64 += "==";
+  } else if (pad === 3) {
+    base64 += "=";
+  }
+  const binaryStr = atob(base64);
+  const bytes = new Uint8Array(binaryStr.length);
+  for (let i = 0; i < binaryStr.length; i++) {
+    bytes[i] = binaryStr.charCodeAt(i);
+  }
+  return bytes;
+}
+function base64UrlDecode(str) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(str, "base64url").toString("utf8");
+  }
+  const bytes = base64UrlToBytes(str);
+  return new TextDecoder().decode(bytes);
+}
+function parseJwt(token) {
+  if (!token || typeof token !== "string") {
+    throw new AuthenticationError("JWT token must be a non-empty string.");
+  }
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    throw new AuthenticationError("Invalid JWT format: token must contain exactly 3 dot-separated parts.");
+  }
+  const [headerB64, payloadB64, signatureB64] = parts;
+  try {
+    const headerJson = base64UrlDecode(headerB64);
+    const header = JSON.parse(headerJson);
+    const payloadJson = base64UrlDecode(payloadB64);
+    const payload = JSON.parse(payloadJson);
+    const signature = base64UrlToBytes(signatureB64);
+    const signingInput = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+    return {
+      header,
+      payload,
+      signature,
+      signingInput
+    };
+  } catch (err) {
+    if (err instanceof AuthenticationError) throw err;
+    throw new AuthenticationError(`Failed to parse JWT token: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+// src/b2b/jwks.ts
+var JwksClient = class {
+  jwksUrl;
+  fetchImpl;
+  cachedKeys = /* @__PURE__ */ new Map();
+  lastFetchedAt = 0;
+  cacheTtlMs;
+  constructor(config, cacheTtlMs = 36e5) {
+    const baseUrl = (config.endpoint || config.baseUrl || "https://api.serafort.com").replace(/\/+$/, "");
+    this.jwksUrl = `${baseUrl}/.well-known/jwks.json`;
+    this.fetchImpl = config.fetch || globalThis.fetch.bind(globalThis);
+    this.cacheTtlMs = cacheTtlMs;
+  }
+  /**
+   * Retrieves the CryptoKey matching the key ID (kid) from cache, or fetches from the JWKS endpoint.
+   */
+  async getVerificationKey(kid, alg = "RS256") {
+    const now = Date.now();
+    const isCacheExpired = now - this.lastFetchedAt > this.cacheTtlMs;
+    if (this.cachedKeys.size > 0 && !isCacheExpired) {
+      if (kid && this.cachedKeys.has(kid)) {
+        return this.cachedKeys.get(kid);
+      }
+      if (!kid && this.cachedKeys.size === 1) {
+        return Array.from(this.cachedKeys.values())[0];
+      }
+    }
+    await this.refreshJwks();
+    if (kid && this.cachedKeys.has(kid)) {
+      return this.cachedKeys.get(kid);
+    }
+    if (!kid && this.cachedKeys.size > 0) {
+      return Array.from(this.cachedKeys.values())[0];
+    }
+    throw new AuthenticationError(
+      `No matching public key found in JWKS for kid "${kid || "unspecified"}" and alg "${alg}".`,
+      "KEY_NOT_FOUND"
+    );
+  }
+  /**
+   * Refreshes public keys from the JWKS endpoint and imports them as CryptoKeys.
+   */
+  async refreshJwks() {
+    let response;
+    try {
+      response = await this.fetchImpl(this.jwksUrl, {
+        headers: { Accept: "application/json" }
+      });
+    } catch (err) {
+      throw new NetworkError(`Failed to fetch JWKS from ${this.jwksUrl}`, err);
+    }
+    if (!response.ok) {
+      throw new AuthenticationError(`Failed to fetch JWKS (status ${response.status})`, "JWKS_FETCH_FAILED");
+    }
+    const jwks = await response.json();
+    if (!jwks.keys || !Array.isArray(jwks.keys)) {
+      throw new AuthenticationError('Invalid JWKS response format: "keys" array missing', "INVALID_JWKS");
+    }
+    const newKeys = /* @__PURE__ */ new Map();
+    for (const key of jwks.keys) {
+      if (!key.kid) continue;
+      try {
+        const cryptoKey = await this.importJwk(key);
+        newKeys.set(key.kid, cryptoKey);
+      } catch {
+      }
+    }
+    this.cachedKeys = newKeys;
+    this.lastFetchedAt = Date.now();
+  }
+  /**
+   * Imports a raw JWK into a Web Crypto CryptoKey.
+   */
+  async importJwk(key) {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+      throw new AuthenticationError("Web Crypto API (crypto.subtle) is not available in this environment.");
+    }
+    const alg = key.alg || (key.kty === "RSA" ? "RS256" : "ES256");
+    let importAlgorithm;
+    if (alg.startsWith("RS")) {
+      const hashName = alg === "RS384" ? "SHA-384" : alg === "RS512" ? "SHA-512" : "SHA-256";
+      importAlgorithm = {
+        name: "RSASSA-PKCS1-v1_5",
+        hash: { name: hashName }
+      };
+    } else if (alg.startsWith("ES")) {
+      const namedCurve = alg === "ES384" ? "P-384" : alg === "ES512" ? "P-521" : "P-256";
+      importAlgorithm = {
+        name: "ECDSA",
+        namedCurve
+      };
+    } else {
+      throw new AuthenticationError(`Unsupported key algorithm: ${alg}`);
+    }
+    return subtle.importKey(
+      "jwk",
+      key,
+      importAlgorithm,
+      false,
+      // non-extractable
+      ["verify"]
+    );
+  }
+};
+
+// src/b2b/b2b.ts
+var B2BModule = class {
+  config;
+  jwksClient;
+  baseUrl;
+  constructor(config, jwksClient) {
+    this.config = config;
+    this.jwksClient = jwksClient ?? new JwksClient(config);
+    this.baseUrl = (config.endpoint || config.baseUrl || "https://api.serafort.com").replace(/\/+$/, "");
+  }
+  /**
+   * Validates a JWT token locally: checks signature against cached JWKS, verifies expiration,
+   * issuer, and audience, and decodes claims into a strongly-typed UserContext.
+   */
+  async validateToken(token, options = {}) {
+    const decoded = parseJwt(token);
+    const now = Math.floor(Date.now() / 1e3);
+    const clockTolerance = options.clockToleranceSeconds ?? 60;
+    const payload = decoded.payload;
+    if (typeof payload["exp"] === "number") {
+      if (payload["exp"] + clockTolerance < now) {
+        throw new AuthenticationError("Token has expired.", "TOKEN_EXPIRED");
+      }
+    }
+    if (typeof payload["nbf"] === "number") {
+      if (payload["nbf"] - clockTolerance > now) {
+        throw new AuthenticationError("Token not yet valid.", "TOKEN_NOT_YET_VALID");
+      }
+    }
+    const expectedIssuer = options.expectedIssuer || this.baseUrl;
+    if (expectedIssuer && typeof payload["iss"] === "string") {
+      if (payload["iss"] !== expectedIssuer) {
+        throw new AuthenticationError(
+          `Invalid token issuer. Expected "${expectedIssuer}", received "${payload["iss"]}".`,
+          "INVALID_ISSUER"
+        );
+      }
+    }
+    if (options.expectedAudience && payload["aud"]) {
+      const aud = Array.isArray(payload["aud"]) ? payload["aud"] : [payload["aud"]];
+      if (!aud.includes(options.expectedAudience)) {
+        throw new AuthenticationError(
+          `Invalid token audience. Expected "${options.expectedAudience}".`,
+          "INVALID_AUDIENCE"
+        );
+      }
+    }
+    if (!options.skipSignatureCheck) {
+      const subtle = globalThis.crypto?.subtle;
+      if (!subtle) {
+        throw new AuthenticationError("Web Crypto API (crypto.subtle) is not available to verify JWT signature.");
+      }
+      const kid = decoded.header.kid;
+      const alg = decoded.header.alg || "RS256";
+      const cryptoKey = await this.jwksClient.getVerificationKey(kid, alg);
+      let verifyAlgorithm;
+      if (alg.startsWith("RS")) {
+        verifyAlgorithm = { name: "RSASSA-PKCS1-v1_5" };
+      } else if (alg.startsWith("ES")) {
+        verifyAlgorithm = { name: "ECDSA", hash: { name: alg === "ES384" ? "SHA-384" : alg === "ES512" ? "SHA-512" : "SHA-256" } };
+      } else {
+        throw new AuthenticationError(`Unsupported JWT algorithm for signature verification: ${alg}`);
+      }
+      const isValid = await subtle.verify(
+        verifyAlgorithm,
+        cryptoKey,
+        decoded.signature,
+        decoded.signingInput
+      );
+      if (!isValid) {
+        throw new AuthenticationError("JWT signature verification failed.", "INVALID_SIGNATURE");
+      }
+    }
+    return this.mapClaimsToUserContext(payload);
+  }
+  /**
+   * Checks if the user context contains a specific granular permission.
+   * Supports wildcard matching (e.g. "org:*" matches "org:read").
+   */
+  hasPermission(userContext, requiredPermission) {
+    if (!userContext.permissions || userContext.permissions.length === 0) {
+      return false;
+    }
+    if (userContext.permissions.includes("*") || userContext.permissions.includes(requiredPermission)) {
+      return true;
+    }
+    return userContext.permissions.some((perm) => {
+      if (perm.endsWith(":*")) {
+        const prefix = perm.slice(0, -2);
+        return requiredPermission.startsWith(prefix);
+      }
+      return false;
+    });
+  }
+  /**
+   * Checks if the user context contains a specific role.
+   */
+  hasRole(userContext, requiredRole) {
+    return Array.isArray(userContext.roles) && userContext.roles.includes(requiredRole);
+  }
+  /**
+   * Constructs the Enterprise SSO Login URL for a specific tenant/organization.
+   */
+  getLoginUrl(tenantId, redirectUri, options = {}) {
+    const url = new URL(`${this.baseUrl}/api/auth/sso/login`);
+    url.searchParams.set("tenant_id", tenantId);
+    url.searchParams.set("redirect_uri", redirectUri);
+    if (options.state) {
+      url.searchParams.set("state", options.state);
+    }
+    if (options.connection) {
+      url.searchParams.set("connection", options.connection);
+    }
+    return url.toString();
+  }
+  /**
+   * Maps un-enveloped JWT claims to standard UserContext.
+   */
+  mapClaimsToUserContext(claims) {
+    const userId = String(claims["sub"] || claims["id"] || claims["user_id"] || "");
+    const tenantId = String(
+      claims["tenant_id"] || claims["org_id"] || claims["tid"] || claims["app_metadata"]?.["tenant_id"] || ""
+    );
+    const email = claims["email"] ? String(claims["email"]) : void 0;
+    let roles = [];
+    if (Array.isArray(claims["roles"])) {
+      roles = claims["roles"].map(String);
+    } else if (typeof claims["role"] === "string") {
+      roles = [claims["role"]];
+    } else if (typeof claims["roles"] === "string") {
+      roles = claims["roles"].split(",").map((r) => r.trim());
+    }
+    let permissions = [];
+    if (Array.isArray(claims["permissions"])) {
+      permissions = claims["permissions"].map(String);
+    } else if (typeof claims["scope"] === "string") {
+      permissions = claims["scope"].split(" ").map((s) => s.trim()).filter(Boolean);
+    }
+    return {
+      userId,
+      tenantId,
+      email,
+      roles,
+      permissions,
+      claims
+    };
+  }
+};
+
+// src/utils/retry.ts
+async function executeWithRetry(fn, options = {}) {
+  const maxRetries = options.retryConfig?.maxRetries ?? 3;
+  const initialDelay = options.retryConfig?.initialDelayMs ?? 500;
+  const maxDelay = options.retryConfig?.maxDelayMs ?? 5e3;
+  let attempt = 0;
+  while (true) {
+    try {
+      return await fn();
+    } catch (err) {
+      attempt++;
+      if (attempt > maxRetries) {
+        throw err;
+      }
+      const isRetryable = isErrorRetryable(err);
+      if (!isRetryable) {
+        throw err;
+      }
+      if (options.signal?.aborted) {
+        throw new NetworkError("Request aborted by caller", options.signal.reason);
+      }
+      let delay = initialDelay * Math.pow(2, attempt - 1);
+      if (err instanceof RateLimitError && err.retryAfterSeconds) {
+        delay = Math.max(delay, err.retryAfterSeconds * 1e3);
+      }
+      const jitter = delay * (0.8 + Math.random() * 0.4);
+      const cappedDelay = Math.min(jitter, maxDelay);
+      await sleep(cappedDelay, options.signal);
+    }
+  }
+}
+function isErrorRetryable(err) {
+  if (err instanceof RateLimitError) {
+    return true;
+  }
+  if (err instanceof NetworkError) {
+    return true;
+  }
+  if (err instanceof Error) {
+    const msg = err.message.toLowerCase();
+    if (msg.includes("network") || msg.includes("fetch failed") || msg.includes("econnreset") || msg.includes("econnrefused") || msg.includes("etimedout")) {
+      return true;
+    }
+  }
+  return false;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      return reject(new NetworkError("Request aborted while sleeping", signal.reason));
+    }
+    const timer = setTimeout(() => {
+      resolve();
+    }, ms);
+    if (signal) {
+      signal.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timer);
+          reject(new NetworkError("Request aborted", signal.reason));
+        },
+        { once: true }
+      );
+    }
+  });
+}
+
+// src/m2m/cache.ts
+var M2MTokenCache = class {
+  cache = /* @__PURE__ */ new Map();
+  inFlightRequests = /* @__PURE__ */ new Map();
+  /**
+   * Refresh window buffer in seconds (default: 300s = 5 minutes).
+   * A token expiring within this window will be refreshed proactively.
+   */
+  refreshBufferSeconds;
+  constructor(refreshBufferSeconds = 300) {
+    this.refreshBufferSeconds = refreshBufferSeconds;
+  }
+  /**
+   * Retrieves a cached token if valid, or invokes the refresher function.
+   * If a fetch is already in flight for the given cache key, coalesces into that existing promise.
+   */
+  async getOrFetch(cacheKey, refresher, force = false) {
+    const now = Math.floor(Date.now() / 1e3);
+    if (!force) {
+      const cached = this.cache.get(cacheKey);
+      if (cached && cached.expiresAt - this.refreshBufferSeconds > now) {
+        return cached.accessToken;
+      }
+    }
+    const existingInFlight = this.inFlightRequests.get(cacheKey);
+    if (existingInFlight) {
+      return existingInFlight;
+    }
+    const fetchPromise = (async () => {
+      try {
+        const response = await refresher();
+        const expiresAt = now + response.expiresIn;
+        this.cache.set(cacheKey, {
+          accessToken: response.accessToken,
+          expiresAt,
+          scope: response.scope
+        });
+        return response.accessToken;
+      } finally {
+        this.inFlightRequests.delete(cacheKey);
+      }
+    })();
+    this.inFlightRequests.set(cacheKey, fetchPromise);
+    return fetchPromise;
+  }
+  /**
+   * Invalidates cached token for a specific cache key or clears all.
+   */
+  invalidate(cacheKey) {
+    if (cacheKey) {
+      this.cache.delete(cacheKey);
+    } else {
+      this.cache.clear();
+    }
+  }
+  /**
+   * Returns current cached item metadata (for diagnostics and testing).
+   */
+  get(cacheKey) {
+    return this.cache.get(cacheKey);
+  }
+};
+
+// src/m2m/m2m.ts
+var M2MModule = class {
+  config;
+  cache;
+  baseUrl;
+  fetchImpl;
+  constructor(config, cache) {
+    this.config = config;
+    this.cache = cache ?? new M2MTokenCache();
+    this.baseUrl = (config.endpoint || config.baseUrl || "https://api.serafort.com").replace(/\/+$/, "");
+    this.fetchImpl = config.fetch || globalThis.fetch.bind(globalThis);
+  }
+  /**
+   * Retrieves a valid M2M access token.
+   * Pulls from memory cache if valid and outside the refresh buffer.
+   * If nearing expiration or missing, transparently requests a new token.
+   */
+  async getAccessToken(scopes) {
+    const scopeStr = scopes && scopes.length > 0 ? scopes.sort().join(" ") : "";
+    const cacheKey = `m2m:${this.config.clientId || "default"}:${scopeStr}`;
+    return this.cache.getOrFetch(cacheKey, () => this.fetchTokenNetwork(scopeStr), false);
+  }
+  /**
+   * Forces a refresh of the access token, bypassing the cache.
+   * Useful when an API endpoint returns 401 due to early revocation.
+   */
+  async forceRefreshToken(scopes) {
+    const scopeStr = scopes && scopes.length > 0 ? scopes.sort().join(" ") : "";
+    const cacheKey = `m2m:${this.config.clientId || "default"}:${scopeStr}`;
+    return this.cache.getOrFetch(cacheKey, () => this.fetchTokenNetwork(scopeStr), true);
+  }
+  /**
+   * Clears the in-memory token cache.
+   */
+  clearCache() {
+    this.cache.invalidate();
+  }
+  /**
+   * Performs the HTTP request to the OAuth2 token endpoint using Client Credentials grant.
+   */
+  async fetchTokenNetwork(scope) {
+    if (!this.config.clientId || !this.config.clientSecret) {
+      throw new AuthenticationError("M2M authentication requires clientId and clientSecret to be configured.");
+    }
+    const tokenUrl = `${this.baseUrl}/oauth/token`;
+    const bodyParams = new URLSearchParams({
+      grant_type: "client_credentials",
+      client_id: this.config.clientId,
+      client_secret: this.config.clientSecret
+    });
+    if (scope) {
+      bodyParams.set("scope", scope);
+    }
+    return executeWithRetry(
+      async () => {
+        let response;
+        try {
+          const controller = new AbortController();
+          const timeoutId = setTimeout(() => controller.abort(), this.config.timeout ?? 1e4);
+          response = await this.fetchImpl(tokenUrl, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/x-www-form-urlencoded",
+              Accept: "application/json"
+            },
+            body: bodyParams.toString(),
+            signal: controller.signal
+          });
+          clearTimeout(timeoutId);
+        } catch (err) {
+          throw new NetworkError(`Failed to connect to token endpoint at ${tokenUrl}`, err);
+        }
+        if (response.status === 429) {
+          const retryAfterHeader = response.headers.get("Retry-After");
+          const retryAfterSec = retryAfterHeader ? parseInt(retryAfterHeader, 10) : void 0;
+          throw new RateLimitError("Rate limit exceeded on token endpoint", isNaN(retryAfterSec) ? void 0 : retryAfterSec);
+        }
+        if (!response.ok) {
+          let errorPayload;
+          try {
+            errorPayload = await response.json();
+          } catch {
+          }
+          const errorMessage = errorPayload?.error?.message || `OAuth token request failed with status ${response.status}`;
+          const errorCode = errorPayload?.error?.code || "TOKEN_REQUEST_FAILED";
+          if (response.status === 401 || response.status === 400) {
+            throw new AuthenticationError(errorMessage, errorCode);
+          }
+          throw new SerafortError(errorMessage, errorCode, response.status);
+        }
+        const data = await response.json();
+        if (!data.access_token) {
+          throw new SerafortError("OAuth token endpoint response did not contain access_token", "INVALID_RESPONSE");
+        }
+        return {
+          accessToken: data.access_token,
+          expiresIn: data.expires_in || 3600,
+          scope: data.scope
+        };
+      },
+      { retryConfig: this.config.retryPolicy }
+    );
+  }
+};
+
+// src/client.ts
+var SerafortClient = class {
+  config;
+  m2m;
+  b2b;
+  constructor(config) {
+    this.config = {
+      endpoint: config.endpoint || config.baseUrl || "https://api.serafort.com",
+      ...config
+    };
+    this.m2m = new M2MModule(this.config);
+    this.b2b = new B2BModule(this.config);
+  }
+  /**
+   * Helper shortcut to retrieve an M2M access token.
+   */
+  async getAccessToken(scopes) {
+    return this.m2m.getAccessToken(scopes);
+  }
+  /**
+   * Helper shortcut to validate a JWT token and decode its UserContext.
+   */
+  async validateToken(token) {
+    return this.b2b.validateToken(token);
+  }
+};
+
+export { AuthenticationError, B2BModule, JwksClient, M2MModule, M2MTokenCache, MfaRequiredError, NetworkError, NotFoundError, RateLimitError, SerafortClient, SerafortError, ValidationError, base64UrlDecode, base64UrlToBytes, executeWithRetry, parseJwt };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map