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

package/dist/index.cjs

@@ -20,39 +20,142 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AuthyonAbility: () => AuthyonAbility,
+  AuthyonAbilityBuilder: () => AuthyonAbilityBuilder,
   AuthyonClient: () => AuthyonClient,
+  AuthyonClientBuilder: () => AuthyonClientBuilder,
   AuthyonError: () => AuthyonError,
+  AuthyonSessionController: () => AuthyonSessionController,
   ErrorCodes: () => ErrorCodes,
+  FetchHttpAdapter: () => FetchHttpAdapter,
+  LoggingHttpAdapter: () => LoggingHttpAdapter,
+  createAuthyonAbility: () => createAuthyonAbility,
+  createAuthyonRules: () => createAuthyonRules,
   createClient: () => createClient,
-  defaultStorage: () => defaultStorage,
-  localStorageAdapter: () => localStorageAdapter,
-  memoryStorage: () => memoryStorage
+  createDefaultStorage: () => createDefaultStorage,
+  createLocalStorage: () => createLocalStorage,
+  createMemoryStorage: () => createMemoryStorage,
+  hasPermission: () => hasPermission,
+  hasPermissionGroup: () => hasPermissionGroup
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/errors.ts
+// ../../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,
@@ -64,12 +167,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;
       }
@@ -88,22 +195,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."
     });
@@ -159,7 +488,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.
@@ -184,8 +513,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
@@ -215,11 +544,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. */
@@ -312,10 +641,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. */
@@ -323,7 +661,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
@@ -332,15 +676,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);
@@ -384,40 +754,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). */
@@ -453,7 +812,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 }
@@ -503,6 +865,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();
@@ -512,6 +876,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();
@@ -534,20 +900,382 @@ 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 };
+  }
+  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 });
+  }
+};
+
+// src/session/sessionController.ts
+var SERVER_SNAPSHOT = {
+  // The server cannot inspect browser storage. Reporting unauthenticated here
+  // makes guards redirect during hydration before a persisted session can be
+  // restored and validated on the client.
+  status: "validating",
+  session: null,
+  user: null,
+  error: null
+};
+var AuthyonSessionController = class {
+  constructor(client, options = {}) {
+    this.client = client;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.getSnapshot = () => this.snapshot;
+    this.getServerSnapshot = () => SERVER_SNAPSHOT;
+    this.subscribe = (listener) => {
+      this.listeners.add(listener);
+      return () => this.listeners.delete(listener);
+    };
+    this.refreshAheadMs = options.refreshAheadMs ?? 3e4;
+    if (!Number.isFinite(this.refreshAheadMs) || this.refreshAheadMs < 0) {
+      throw new Error("Authyon: `refreshAheadMs` must be a non-negative finite number");
+    }
+    const session = client.getSession();
+    this.snapshot = {
+      status: session ? "validating" : "unauthenticated",
+      session,
+      user: session?.user ?? null,
+      error: null
+    };
+  }
+  start() {
+    if (!this.unsubscribeAuth) {
+      this.unsubscribeAuth = this.client.onAuthStateChange((event) => {
+        if (event.type === "signed_out") {
+          this.cancelRefresh();
+          this.setSnapshot({
+            status: "unauthenticated",
+            session: null,
+            user: null,
+            error: null
+          });
+          return;
+        }
+        if (event.type === "session_validated") {
+          this.acceptSession(event.session);
+          return;
+        }
+        this.setSnapshot({
+          status: "validating",
+          session: event.session,
+          user: event.session.user ?? null,
+          error: null
+        });
+        void this.validate();
+      });
+    }
+    void this.validate();
+    return () => this.stop();
+  }
+  stop() {
+    this.unsubscribeAuth?.();
+    this.unsubscribeAuth = void 0;
+    this.cancelRefresh();
+  }
+  validate() {
+    if (this.validation) return this.validation;
+    const localSession = this.client.getSession();
+    if (!localSession) {
+      this.setSnapshot({
+        status: "unauthenticated",
+        session: null,
+        user: null,
+        error: null
+      });
+      return Promise.resolve(this.snapshot);
+    }
+    this.setSnapshot({ ...this.snapshot, status: "validating", error: null });
+    this.validation = this.client.validateSession().then((session) => {
+      if (session) this.acceptSession(session);
+      else {
+        this.setSnapshot({
+          status: "unauthenticated",
+          session: null,
+          user: null,
+          error: null
+        });
+      }
+      return this.snapshot;
+    }).catch((error) => {
+      this.setSnapshot({ ...this.snapshot, status: "error", error });
+      return this.snapshot;
+    }).finally(() => {
+      this.validation = void 0;
+    });
+    return this.validation;
+  }
+  async refreshNow() {
+    if (!this.client.getSession()) return this.validate();
+    try {
+      await this.client.refresh();
+    } catch (error) {
+      if (!this.client.getSession()) return this.validate();
+      this.setSnapshot({ ...this.snapshot, status: "error", error });
+      return this.snapshot;
+    }
+    return this.validate();
+  }
+  acceptSession(session) {
+    this.setSnapshot({
+      status: "authenticated",
+      session,
+      user: session.user ?? null,
+      error: null
+    });
+    this.scheduleRefresh(session);
+  }
+  scheduleRefresh(session) {
+    this.cancelRefresh();
+    const delay = Math.max(1e3, session.expiresAt - Date.now() - this.refreshAheadMs);
+    this.refreshTimer = setTimeout(() => void this.refreshNow(), delay);
+  }
+  cancelRefresh() {
+    if (this.refreshTimer !== void 0) clearTimeout(this.refreshTimer);
+    this.refreshTimer = void 0;
+  }
+  setSnapshot(snapshot) {
+    this.snapshot = snapshot;
+    for (const listener of this.listeners) listener();
+  }
+};
+
+// ../../internal/core/authorization/ability.ts
+var AuthyonAbility = class {
+  constructor(rules = [], detectSubjectType = defaultSubjectType) {
+    this.detectSubjectType = detectSubjectType;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.currentRules = rules.map(cloneRule);
+  }
+  get rules() {
+    return this.currentRules;
+  }
+  can(action, subject, field) {
+    const subjectType = typeof subject === "string" ? subject : this.detectSubjectType(subject);
+    for (let index = this.currentRules.length - 1; index >= 0; index -= 1) {
+      const rule = this.currentRules[index];
+      if (!matchesToken(rule.action, action, "manage")) continue;
+      if (!matchesToken(rule.subject, subjectType, "all")) continue;
+      if (field && rule.fields && !rule.fields.some((value) => matchesField(value, field)))
+        continue;
+      if (rule.conditions) {
+        if (typeof subject === "string" || !matchesConditions(subject, rule.conditions)) continue;
+      }
+      return !rule.inverted;
+    }
+    return false;
+  }
+  cannot(action, subject, field) {
+    return !this.can(action, subject, field);
   }
-  return query.toString();
+  rulesFor(action, subject) {
+    return this.currentRules.filter(
+      (rule) => matchesToken(rule.action, action, "manage") && matchesToken(rule.subject, subject, "all")
+    );
+  }
+  update(rules) {
+    this.currentRules = rules.map(cloneRule);
+    for (const listener of this.listeners) listener(this.rules);
+  }
+  on(event, listener) {
+    if (event !== "updated") return () => void 0;
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+};
+var AuthyonAbilityBuilder = class {
+  constructor() {
+    this.rules = [];
+  }
+  can(action, subject, conditions, fields) {
+    this.rules.push({ action, subject, conditions, fields });
+    return this;
+  }
+  cannot(action, subject, conditions, fields, reason) {
+    this.rules.push({ action, subject, conditions, fields, reason, inverted: true });
+    return this;
+  }
+  build(options = {}) {
+    return new AuthyonAbility(this.rules, options.detectSubjectType);
+  }
+};
+function createAuthyonAbility(source = {}, options = {}) {
+  return new AuthyonAbility(createAuthyonRules(source, options), options.detectSubjectType);
+}
+function hasPermission(source, requiredPermission) {
+  const requirement = permissionToRule(requiredPermission);
+  if (!requirement || typeof requirement.action !== "string" || typeof requirement.subject !== "string") {
+    return false;
+  }
+  const permissionSource = isPermissionList(source) ? { permissions: source } : source;
+  return createAuthyonAbility(permissionSource).can(requirement.action, requirement.subject);
+}
+function hasPermissionGroup(source, group) {
+  const hasAll = (group.allOf ?? []).every((permission) => hasPermission(source, permission));
+  const hasAny = !group.anyOf?.length || group.anyOf.some((permission) => hasPermission(source, permission));
+  return hasAll && hasAny;
+}
+function isPermissionList(source) {
+  return Array.isArray(source);
+}
+function createAuthyonRules(source = {}, options = {}) {
+  const permissions = /* @__PURE__ */ new Set([
+    ...source.permissions ?? [],
+    ...source.scope?.split(/\s+/).filter(Boolean) ?? []
+  ]);
+  const rules = [...permissions].map(permissionToRule).filter(isAbilityRule);
+  for (const role of /* @__PURE__ */ new Set([...source.roles ?? [], ...options.roles ?? []])) {
+    rules.push(...(options.roleRules?.[role] ?? []).map(cloneRule));
+  }
+  rules.push(...(options.rules ?? []).map(cloneRule));
+  return rules;
+}
+function permissionToRule(permission) {
+  const normalized = permission.trim();
+  if (!normalized) return null;
+  if (normalized === "*" || normalized === "*:*" || normalized === "all:manage") {
+    return { action: "manage", subject: "all" };
+  }
+  const separator = normalized.lastIndexOf(":");
+  if (separator <= 0 || separator === normalized.length - 1) return null;
+  const subject = normalized.slice(0, separator);
+  const action = normalized.slice(separator + 1);
+  return {
+    action: action === "*" ? "manage" : action,
+    subject: subject === "*" ? "all" : subject
+  };
+}
+function matchesToken(value, expected, wildcard) {
+  return (Array.isArray(value) ? value : [value]).some(
+    (candidate) => candidate === expected || candidate === wildcard || candidate === "*" || matchesSegments(candidate, expected)
+  );
+}
+function matchesSegments(pattern, value) {
+  const patternSegments = pattern.split(":");
+  const valueSegments = value.split(":");
+  return patternSegments.length === valueSegments.length && patternSegments.every((segment, index) => segment === "*" || segment === valueSegments[index]);
+}
+function matchesField(pattern, field) {
+  if (pattern === "*" || pattern === field) return true;
+  return pattern.endsWith(".*") && field.startsWith(pattern.slice(0, -1));
+}
+function matchesConditions(subject, conditions) {
+  return Object.entries(conditions).every(([path, expected]) => {
+    if (path === "$and" && Array.isArray(expected)) {
+      return expected.every(
+        (condition) => matchesConditions(subject, condition)
+      );
+    }
+    if (path === "$or" && Array.isArray(expected)) {
+      return expected.some(
+        (condition) => matchesConditions(subject, condition)
+      );
+    }
+    return matchesValue(readPath(subject, path), expected);
+  });
+}
+function matchesValue(actual, expected) {
+  if (!isRecord(expected) || !Object.keys(expected).some((key) => key.startsWith("$"))) {
+    return isRecord(expected) && isRecord(actual) ? matchesConditions(actual, expected) : Object.is(actual, expected);
+  }
+  return Object.entries(expected).every(([operator, operand]) => {
+    switch (operator) {
+      case "$eq":
+        return Object.is(actual, operand);
+      case "$ne":
+        return !Object.is(actual, operand);
+      case "$in":
+        return Array.isArray(operand) && operand.some((value) => Object.is(actual, value));
+      case "$nin":
+        return Array.isArray(operand) && !operand.some((value) => Object.is(actual, value));
+      case "$gt":
+        return typeof actual === "number" && typeof operand === "number" && actual > operand;
+      case "$gte":
+        return typeof actual === "number" && typeof operand === "number" && actual >= operand;
+      case "$lt":
+        return typeof actual === "number" && typeof operand === "number" && actual < operand;
+      case "$lte":
+        return typeof actual === "number" && typeof operand === "number" && actual <= operand;
+      case "$exists":
+        return operand ? actual !== void 0 : actual === void 0;
+      default:
+        return false;
+    }
+  });
+}
+function readPath(value, path) {
+  return path.split(".").reduce((current, part) => isRecord(current) ? current[part] : void 0, value);
+}
+function defaultSubjectType(subject) {
+  const explicit = subject.__type ?? subject.type ?? subject.kind;
+  if (typeof explicit === "string") return explicit;
+  const constructorName = subject.constructor?.name;
+  return typeof constructorName === "string" ? constructorName : "Object";
+}
+function cloneRule(rule) {
+  return {
+    ...rule,
+    action: Array.isArray(rule.action) ? [...rule.action] : rule.action,
+    subject: Array.isArray(rule.subject) ? [...rule.subject] : rule.subject,
+    fields: rule.fields ? [...rule.fields] : void 0
+  };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isAbilityRule(value) {
+  return value !== null;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AuthyonAbility,
+  AuthyonAbilityBuilder,
   AuthyonClient,
+  AuthyonClientBuilder,
   AuthyonError,
+  AuthyonSessionController,
   ErrorCodes,
+  FetchHttpAdapter,
+  LoggingHttpAdapter,
+  createAuthyonAbility,
+  createAuthyonRules,
   createClient,
-  defaultStorage,
-  localStorageAdapter,
-  memoryStorage
+  createDefaultStorage,
+  createLocalStorage,
+  createMemoryStorage,
+  hasPermission,
+  hasPermissionGroup
 });