@authyon/auth 0.2.0-beta.0 → 0.2.0-beta.11

package/dist/index.js

@@ -1,26 +1,129 @@
-// src/errors.ts
+import {
+  AuthyonAbility,
+  AuthyonAbilityBuilder,
+  AuthyonSessionController,
+  createAuthyonAbility,
+  createAuthyonRules,
+  hasPermission,
+  hasPermissionGroup
+} from "./chunk-3XJY6BCI.js";
+
+// ../../internal/core/errors/authyonError.ts
+var ErrorCodes = {
+  Unknown: "unknown",
+  NetworkError: "request.network_error",
+  Timeout: "request.timeout",
+  SessionMalformed: "session.malformed",
+  NotAuthenticated: "auth.not_authenticated",
+  InvalidToken: "auth.invalid_token",
+  MissingToken: "auth.missing_token",
+  EmailTaken: "user.email_taken",
+  PasswordWeak: "user.password_weak",
+  PasswordPwned: "user.password_pwned",
+  RateLimited: "rate_limited"
+};
 var AuthyonError = class extends Error {
-  constructor(status, body) {
+  constructor(status, body, options = {}) {
     super(body.detail ?? body.title ?? `Authyon request failed with status ${status}`);
     this.name = "AuthyonError";
     this.status = status;
     this.code = body.code ?? "unknown";
     this.title = body.title ?? "Error";
     this.detail = body.detail;
+    this.requestId = options.requestId;
+    this.retryAfter = options.retryAfter;
+    this.cause = options.cause;
   }
   is(code) {
     return this.code === code;
   }
+  isAny(...codes) {
+    return codes.includes(this.code);
+  }
+  hasPrefix(prefix) {
+    return this.code.startsWith(prefix);
+  }
+  isStatus(...statuses) {
+    return statuses.includes(this.status);
+  }
+  /** Stable interpretation for UI decisions, retries, telemetry and support flows. */
+  interpret() {
+    const category = classifyError(this.status, this.code);
+    return {
+      category,
+      action: actionFor(category),
+      retryable: isRetryable(category),
+      ...this.retryAfter !== void 0 ? { retryAfter: this.retryAfter } : {},
+      ...this.requestId !== void 0 ? { requestId: this.requestId } : {}
+    };
+  }
+  get category() {
+    return this.interpret().category;
+  }
+  get retryable() {
+    return this.interpret().retryable;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      status: this.status,
+      code: this.code,
+      title: this.title,
+      detail: this.detail,
+      requestId: this.requestId,
+      retryAfter: this.retryAfter,
+      ...this.interpret()
+    };
+  }
 };
-var ErrorCodes = {
-  EmailTaken: "user.email_taken",
-  PasswordWeak: "user.password_weak",
-  PasswordPwned: "user.password_pwned"
-};
+function classifyError(status, code) {
+  if (code === ErrorCodes.NetworkError) return "network";
+  if (code === ErrorCodes.Timeout || status === 408) return "timeout";
+  if (code === ErrorCodes.RateLimited || status === 429) return "rate_limit";
+  if (code === ErrorCodes.EmailTaken || status === 409) return "conflict";
+  if (code === ErrorCodes.PasswordWeak || code === ErrorCodes.PasswordPwned) return "validation";
+  if (code === ErrorCodes.SessionMalformed) return "server";
+  if (code.startsWith("auth.") || status === 401) return "authentication";
+  if (status === 403) return "authorization";
+  if (status === 404) return "not_found";
+  if (status === 400 || status === 422) return "validation";
+  if (status >= 500) return "server";
+  return "unknown";
+}
+function actionFor(category) {
+  switch (category) {
+    case "network":
+    case "timeout":
+    case "rate_limit":
+    case "server":
+      return "retry";
+    case "authentication":
+      return "reauthenticate";
+    case "authorization":
+      return "request_access";
+    case "validation":
+      return "fix_input";
+    case "not_found":
+      return "not_found";
+    case "conflict":
+      return "resolve_conflict";
+    case "unknown":
+      return "contact_support";
+  }
+}
+function isRetryable(category) {
+  return category === "network" || category === "timeout" || category === "rate_limit" || category === "server";
+}
 
-// src/storage.ts
+// src/session/storage.ts
 var STORAGE_KEY = "authyon.session";
-function memoryStorage() {
+function isSession(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return typeof candidate.accessToken === "string" && candidate.accessToken.length > 0 && typeof candidate.refreshToken === "string" && candidate.refreshToken.length > 0 && typeof candidate.expiresIn === "number" && Number.isFinite(candidate.expiresIn) && candidate.expiresIn > 0 && typeof candidate.expiresAt === "number" && Number.isFinite(candidate.expiresAt);
+}
+function createMemoryStorage() {
   let session = null;
   return {
     get: () => session,
@@ -32,12 +135,16 @@ function memoryStorage() {
     }
   };
 }
-function localStorageAdapter(key = STORAGE_KEY) {
+function createLocalStorage(key = STORAGE_KEY) {
   return {
     get() {
       try {
         const raw = window.localStorage.getItem(key);
-        return raw ? JSON.parse(raw) : null;
+        if (!raw) return null;
+        const parsed = JSON.parse(raw);
+        if (isSession(parsed)) return parsed;
+        window.localStorage.removeItem(key);
+        return null;
       } catch {
         return null;
       }
@@ -56,22 +163,244 @@ function localStorageAdapter(key = STORAGE_KEY) {
     }
   };
 }
-function defaultStorage() {
-  if (typeof window !== "undefined" && typeof window.localStorage !== "undefined") {
-    return localStorageAdapter();
-  }
-  return memoryStorage();
+function createDefaultStorage() {
+  return createMemoryStorage();
 }
 
-// src/client.ts
+// ../../internal/core/config/defaults.ts
 var DEFAULT_BASE_URL = "https://api.authyon.com";
-var EXPIRY_SKEW_MS = 3e4;
+var DEFAULT_EXPIRY_SKEW_MS = 3e4;
+
+// ../../internal/core/http/query.ts
+function appendQuery(path, params) {
+  if (!params) return path;
+  const query = new URLSearchParams();
+  for (const [key, value2] of Object.entries(params)) {
+    if (value2 !== void 0) query.set(key, String(value2));
+  }
+  const value = query.toString();
+  return value ? `${path}${path.includes("?") ? "&" : "?"}${value}` : path;
+}
+
+// ../../internal/core/http/httpAdapter.ts
+var FetchHttpAdapter = class {
+  constructor(fetchImpl = fetch.bind(globalThis)) {
+    this.fetchImpl = fetchImpl;
+  }
+  request(request) {
+    return this.fetchImpl(request.url, {
+      method: request.method,
+      headers: request.headers,
+      body: request.body,
+      signal: request.signal,
+      redirect: "error"
+    });
+  }
+};
+var LoggingHttpAdapter = class {
+  constructor(adapter, options) {
+    this.adapter = adapter;
+    this.options = options;
+  }
+  async request(request) {
+    const startedAt = Date.now();
+    const eventBase = {
+      method: request.method,
+      url: sanitizeUrl(request.url)
+    };
+    this.log({ type: "request", ...eventBase, timestamp: startedAt });
+    try {
+      const response = await this.adapter.request(request);
+      this.log({
+        type: "response",
+        ...eventBase,
+        status: response.status,
+        durationMs: Date.now() - startedAt,
+        requestId: response.headers.get("x-request-id") ?? response.headers.get("trace-id") ?? void 0,
+        timestamp: Date.now()
+      });
+      return response;
+    } catch (error) {
+      this.log({
+        type: "error",
+        ...eventBase,
+        errorName: error instanceof Error ? error.name : "UnknownError",
+        durationMs: Date.now() - startedAt,
+        timestamp: Date.now()
+      });
+      throw error;
+    }
+  }
+  log(event) {
+    if (!this.options.enabled) return;
+    const logger = this.options.logger ?? defaultHttpLogger;
+    try {
+      logger(event);
+    } catch {
+    }
+  }
+};
+function defaultHttpLogger(event) {
+  console.debug("[Authyon HTTP]", event);
+}
+function sanitizeUrl(value) {
+  const url = new URL(value);
+  url.username = "";
+  url.password = "";
+  url.hash = "";
+  url.pathname = url.pathname.replace(/(\/platform\/workspace-invites\/)[^/]+/u, "$1REDACTED");
+  const queryKeys = /* @__PURE__ */ new Set();
+  url.searchParams.forEach((_value, key) => queryKeys.add(key));
+  url.search = queryKeys.size > 0 ? [...queryKeys].map((key) => `${encodeURIComponent(key)}=REDACTED`).join("&") : "";
+  return url.toString();
+}
+
+// ../../internal/core/http/transport.ts
+var DEFAULT_TIMEOUT_MS = 15e3;
+var SharedTransportError = class extends Error {
+  constructor(code, cause) {
+    super(code === "request.timeout" ? "Request timed out" : "Network request failed");
+    this.name = "SharedTransportError";
+    this.code = code;
+    this.cause = cause;
+  }
+};
+function createSharedTransport(options) {
+  const baseUrl = normalizeBaseUrl(options.baseUrl, options.allowInsecureHttp ?? false);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+    throw new Error("Authyon: `timeoutMs` must be a non-negative finite number");
+  }
+  if (options.httpAdapter && options.fetch) {
+    throw new Error("Authyon: use either `httpAdapter` or `fetch`, not both");
+  }
+  const baseAdapter = options.httpAdapter ?? new FetchHttpAdapter(options.fetch);
+  const httpAdapter = options.httpLogger ? new LoggingHttpAdapter(baseAdapter, options.httpLogger) : baseAdapter;
+  return {
+    baseUrl,
+    async request(path, init) {
+      const controller = new AbortController();
+      const timeout = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
+      try {
+        return await httpAdapter.request({
+          url: `${baseUrl}${path}`,
+          method: init.method ?? "GET",
+          headers: normalizeHeaders(init.headers),
+          body: init.body,
+          signal: controller.signal
+        });
+      } catch (cause) {
+        throw new SharedTransportError(
+          controller.signal.aborted ? ErrorCodes.Timeout : ErrorCodes.NetworkError,
+          cause
+        );
+      } finally {
+        if (timeout !== void 0) clearTimeout(timeout);
+      }
+    }
+  };
+}
+function normalizeHeaders(headers) {
+  const normalized = {};
+  new Headers(headers).forEach((value, key) => {
+    normalized[key] = value;
+  });
+  return normalized;
+}
+function responseMetadata(response) {
+  const retryAfterHeader = response.headers.get("retry-after");
+  const retryAfter = retryAfterHeader ? Number(retryAfterHeader) : void 0;
+  return {
+    requestId: response.headers.get("x-request-id") ?? response.headers.get("trace-id") ?? void 0,
+    retryAfter: Number.isFinite(retryAfter) ? retryAfter : void 0
+  };
+}
+function normalizeBaseUrl(value, allowInsecureHttp) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Authyon: `baseUrl` must be an absolute URL");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && (loopback || allowInsecureHttp))) {
+    throw new Error(
+      "Authyon: `baseUrl` must use HTTPS (HTTP is allowed only for loopback or with `allowInsecureHttp`)"
+    );
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error(
+      "Authyon: `baseUrl` cannot contain credentials, query parameters, or fragments"
+    );
+  }
+  return url.toString().replace(/\/+$/, "");
+}
+
+// ../../internal/core/http/jsonHttpClient.ts
+var JsonHttpClient = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async send(path, options = {}) {
+    const headers = { ...options.headers };
+    if (options.body !== void 0) headers["Content-Type"] = "application/json";
+    try {
+      return await this.transport.request(appendQuery(path, options.query), {
+        method: options.method ?? "GET",
+        headers,
+        body: options.body !== void 0 ? JSON.stringify(options.body) : void 0
+      });
+    } catch (cause) {
+      if (!(cause instanceof SharedTransportError)) throw cause;
+      throw new AuthyonError(0, { code: cause.code, title: cause.message }, { cause: cause.cause });
+    }
+  }
+  async parse(response) {
+    if (!response.ok) {
+      let body = {};
+      try {
+        body = await response.json();
+      } catch {
+      }
+      throw new AuthyonError(response.status, body, responseMetadata(response));
+    }
+    if (response.status === 204) return void 0;
+    return await response.json();
+  }
+  async request(path, options = {}) {
+    return this.parse(await this.send(path, options));
+  }
+};
+
+// ../../internal/core/http/clientIp.ts
+function clientIpHeaders(context) {
+  if (!context?.clientIp) return {};
+  return { "X-Forwarded-For": normalizeClientIp(context.clientIp) };
+}
+function normalizeClientIp(value) {
+  let ip = value.trim();
+  if (ip.startsWith("[") && ip.endsWith("]")) ip = ip.slice(1, -1);
+  if (!ip || ip.length > 45 || ip.includes(",") || /[\r\n\s]/.test(ip) || !/^[0-9a-f:.]+$/i.test(ip) || !ip.includes(".") && !ip.includes(":")) {
+    throw invalidClientIp();
+  }
+  try {
+    new URL(ip.includes(":") ? `http://[${ip}]` : `http://${ip}`);
+  } catch {
+    throw invalidClientIp();
+  }
+  return ip;
+}
+function invalidClientIp() {
+  return new Error("Authyon: `clientIp` must be a single valid IPv4 or IPv6 address");
+}
+
+// src/client/authyonClient.ts
 var FALLBACK_EXPIRES_IN = 1800;
 function readTokens(raw) {
   const tokens = raw.tokens ?? raw;
   if (!tokens.accessToken || !tokens.refreshToken) {
     throw new AuthyonError(502, {
-      code: "session.malformed",
+      code: ErrorCodes.SessionMalformed,
       title: "Malformed session response",
       detail: "The session response carried no access/refresh token pair."
     });
@@ -127,7 +456,7 @@ var AuthyonClient = class {
       /** GET /auth/sessions — active refresh-token sessions with device/IP data. */
       sessions: () => this.request("/auth/sessions", { bearer: true }),
       /** GET /auth/me/activities — paginated recent account activity for the current user. */
-      activities: (params = {}) => this.request(`/auth/me/activities?${toQuery(params)}`, { bearer: true }),
+      activities: (params = {}) => this.request(appendQuery("/auth/me/activities", params), { bearer: true }),
       /**
        * Revokes a single session by id (e.g. one entry from `sessions()`),
        * signing that device out without affecting the current one.
@@ -152,8 +481,8 @@ var AuthyonClient = class {
     };
     // ── Organization ─────────────────────────────────────────────────────────
     this.organization = {
-      /** GET /auth/tenants — all organization memberships. */
-      list: () => this.request("/auth/tenants", { bearer: true }),
+      /** GET /auth/tenants — filterable list of organization memberships. */
+      list: (params = {}) => this.request(appendQuery("/auth/tenants", params), { bearer: true }),
       /**
        * POST /auth/tenants — creates an organization owned by the signed-in
        * user (only available when self-service organization creation is
@@ -183,11 +512,11 @@ var AuthyonClient = class {
         /**
          * GET /auth/tenants/{organizationId}/members — paginated list of an
          * organization's members. Consistent with the confirmed-live
-         * `Page<T>` envelope every other `skip`/`take` endpoint returns
+         * `Paged<T>` envelope every other `skip`/`take` endpoint returns
          * (`user.activities()`, `@authyon/server`'s `environment.users.list()`).
          */
         list: (organizationId, params = {}) => this.request(
-          `/auth/tenants/${encodeURIComponent(organizationId)}/members?${toQuery(params)}`,
+          appendQuery(`/auth/tenants/${encodeURIComponent(organizationId)}/members`, params),
           { bearer: true }
         ),
         /** POST /auth/tenants/{organizationId}/members — invite a member by e-mail. */
@@ -280,10 +609,19 @@ var AuthyonClient = class {
     if (!options.envKey)
       throw new Error("Authyon: `envKey` is required (pk_live_... / pk_test_...)");
     this.envKey = options.envKey;
-    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-    this.storage = options.storage ?? defaultStorage();
+    this.clientIp = options.clientIp;
+    this.transport = createSharedTransport({
+      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+      allowInsecureHttp: options.allowInsecureHttp,
+      timeoutMs: options.timeoutMs,
+      httpAdapter: options.httpAdapter,
+      httpLogger: options.httpLogger,
+      fetch: options.fetch
+    });
+    this.baseUrl = this.transport.baseUrl;
+    this.http = new JsonHttpClient(this.transport);
+    this.storage = options.storage ?? createDefaultStorage();
     this.autoRefresh = options.autoRefresh ?? true;
-    this.fetchImpl = options.fetch ?? fetch.bind(globalThis);
   }
   // ── Session state ────────────────────────────────────────────────────────
   /** Current persisted session, or null when signed out. */
@@ -291,7 +629,13 @@ var AuthyonClient = class {
     return this.storage.get();
   }
   isAuthenticated() {
-    return this.getSession() !== null;
+    return this.getAuthState() === "authenticated";
+  }
+  /** Synchronous snapshot of the locally available authentication state. */
+  getAuthState() {
+    const session = this.getSession();
+    if (!session) return "signed_out";
+    return Date.now() < session.expiresAt ? "authenticated" : "expired";
   }
   /**
    * Returns a valid access token, refreshing it transparently when it is
@@ -300,15 +644,41 @@ var AuthyonClient = class {
   async getAccessToken() {
     const session = this.getSession();
     if (!session) return null;
-    if (this.autoRefresh && Date.now() >= session.expiresAt - EXPIRY_SKEW_MS) {
+    if (this.autoRefresh && Date.now() >= session.expiresAt - DEFAULT_EXPIRY_SKEW_MS) {
       try {
         return (await this.refresh()).accessToken;
-      } catch {
-        return null;
+      } catch (error) {
+        if (error instanceof AuthyonError && (error.status === 401 || error.status === 403)) {
+          return null;
+        }
+        throw error;
       }
     }
     return session.accessToken;
   }
+  /**
+   * Refreshes when needed, validates the server-side session through `GET /auth/me`,
+   * and stores the fresh user profile. Returns null when the session is no longer valid.
+   */
+  async validateSession() {
+    const accessToken = await this.getAccessToken();
+    if (!accessToken) return null;
+    try {
+      const user = await this.user.me();
+      const current = this.getSession();
+      if (!current) return null;
+      const session = { ...current, user };
+      this.storage.set(session);
+      this.emit({ type: "session_validated", session });
+      return session;
+    } catch (error) {
+      if (error instanceof AuthyonError && (error.status === 401 || error.status === 403)) {
+        this.clearSession();
+        return null;
+      }
+      throw error;
+    }
+  }
   /** Subscribe to sign-in / refresh / sign-out events. Returns an unsubscribe fn. */
   onAuthStateChange(listener) {
     this.listeners.add(listener);
@@ -352,40 +722,29 @@ var AuthyonClient = class {
   async request(path, options = {}, isRetry = false) {
     const headers = {
       "X-Authyon-Environment": this.envKey,
+      ...clientIpHeaders({ clientIp: this.clientIp }),
       ...options.headers
     };
-    if (options.body !== void 0) headers["Content-Type"] = "application/json";
     if (options.bearer) {
       const token = await this.getAccessToken();
       if (!token)
-        throw new AuthyonError(401, { code: "auth.not_authenticated", title: "Not authenticated" });
+        throw new AuthyonError(401, {
+          code: ErrorCodes.NotAuthenticated,
+          title: "Not authenticated"
+        });
       headers.Authorization = `Bearer ${token}`;
     }
-    const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
-      method: options.method ?? "GET",
-      headers,
-      body: options.body !== void 0 ? JSON.stringify(options.body) : void 0
-    });
+    const response = await this.http.send(path, { ...options, headers });
     if (response.status === 401 && options.bearer && this.autoRefresh && !isRetry && this.getSession()) {
       try {
         await this.refresh();
       } catch {
         this.clearSession();
-        throw await this.toError(response);
+        return this.http.parse(response);
       }
       return this.request(path, options, true);
     }
-    if (!response.ok) throw await this.toError(response);
-    if (response.status === 204) return void 0;
-    return await response.json();
-  }
-  async toError(response) {
-    let body = {};
-    try {
-      body = await response.json();
-    } catch {
-    }
-    return new AuthyonError(response.status, body);
+    return this.http.parse(response);
   }
   // ── Auth flows ───────────────────────────────────────────────────────────
   /** POST /auth/register — creates a new user (rate-limited to 20/hour per IP). */
@@ -421,7 +780,10 @@ var AuthyonClient = class {
     if (this.refreshInFlight) return this.refreshInFlight;
     const current = this.getSession();
     if (!current)
-      throw new AuthyonError(401, { code: "auth.not_authenticated", title: "Not authenticated" });
+      throw new AuthyonError(401, {
+        code: ErrorCodes.NotAuthenticated,
+        title: "Not authenticated"
+      });
     this.refreshInFlight = this.request("/auth/refresh", {
       method: "POST",
       body: { refreshToken: current.refreshToken }
@@ -471,6 +833,8 @@ var AuthyonClient = class {
    * A browser app has no client secret to present, so this will fail from
    * `@authyon/auth` in practice; call it from your backend via
    * `@authyon/server` instead.
+   *
+   * @deprecated Use `@authyon/server.introspect()` from a trusted backend.
    */
   async introspect(token) {
     const accessToken = token ?? await this.getAccessToken();
@@ -480,6 +844,8 @@ var AuthyonClient = class {
    * POST /auth/validate — recommended: cross-checks DB state, catches
    * revocation immediately. Same caller-authentication requirement (and
    * the same practical limitation from the browser) as `introspect()`.
+   *
+   * @deprecated Use `@authyon/server.validate()` from a trusted backend.
    */
   async validate(token) {
     const accessToken = token ?? await this.getAccessToken();
@@ -502,19 +868,61 @@ function normalizeUser(raw) {
 function createClient(options) {
   return new AuthyonClient(options);
 }
-function toQuery(params) {
-  const query = new URLSearchParams();
-  for (const [key, value] of Object.entries(params)) {
-    if (value !== void 0) query.set(key, String(value));
+
+// src/client/authyonClientBuilder.ts
+var AuthyonClientBuilder = class {
+  constructor(envKey) {
+    this.options = { envKey };
   }
-  return query.toString();
-}
+  withBaseUrl(baseUrl, allowInsecureHttp = false) {
+    this.options.baseUrl = baseUrl;
+    this.options.allowInsecureHttp = allowInsecureHttp;
+    return this;
+  }
+  withStorage(storage) {
+    this.options.storage = storage;
+    return this;
+  }
+  withAutomaticRefresh(enabled = true) {
+    this.options.autoRefresh = enabled;
+    return this;
+  }
+  withClientIp(clientIp) {
+    this.options.clientIp = clientIp;
+    return this;
+  }
+  withTimeout(timeoutMs) {
+    this.options.timeoutMs = timeoutMs;
+    return this;
+  }
+  withHttpAdapter(httpAdapter) {
+    this.options.httpAdapter = httpAdapter;
+    return this;
+  }
+  withHttpLogger(httpLogger) {
+    this.options.httpLogger = httpLogger;
+    return this;
+  }
+  build() {
+    return new AuthyonClient({ ...this.options });
+  }
+};
 export {
+  AuthyonAbility,
+  AuthyonAbilityBuilder,
   AuthyonClient,
+  AuthyonClientBuilder,
   AuthyonError,
+  AuthyonSessionController,
   ErrorCodes,
+  FetchHttpAdapter,
+  LoggingHttpAdapter,
+  createAuthyonAbility,
+  createAuthyonRules,
   createClient,
-  defaultStorage,
-  localStorageAdapter,
-  memoryStorage
+  createDefaultStorage,
+  createLocalStorage,
+  createMemoryStorage,
+  hasPermission,
+  hasPermissionGroup
 };