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

package/README.md

@@ -9,7 +9,7 @@ Para gestão de organização/membros (secret key) e verificação de token no b
 ## Instalação
 
 ```bash
-npm install --save-exact @authyon/auth@0.2.0-beta.1
+npm install --save-exact @authyon/auth@0.2.0-beta.4
 ```
 
 Durante a beta, `npm install @authyon/auth@beta` acompanha o prerelease mais recente. Fixar a versão exata é recomendado para builds reproduzíveis.
@@ -57,6 +57,26 @@ Use o entrypoint dedicado `@authyon/auth/react`:
 
 O provider faz refresh automático, valida a sessão por `GET /auth/me`, atualiza usuário e permissions, revalida quando a aba volta ao foco e não libera guards enquanto a validação inicial estiver pendente. Use `useAuthyon()`, `useAuthyonAbility()` e `useCan()` para fluxos programáticos.
 
+Use `transformUser` para expor campos derivados sem alterar a sessão mantida pela lib:
+
+```tsx
+type ApplicationUser = User & { fullName: string };
+
+<AuthyonProvider<ApplicationUser>
+  client={authyon}
+  transformUser={(user) => ({
+    ...user,
+    fullName: [user.firstName, user.lastName].filter(Boolean).join(" "),
+  })}
+>
+  <App />
+</AuthyonProvider>;
+
+const { user, session } = useAuthyon<ApplicationUser>();
+```
+
+O usuário transformado é retornado em `user` e em `session.user` após validação, refresh, login e troca de organização. O transformador deve ser puro e só derivar dados do perfil do Authyon; dados externos pertencem ao contexto da aplicação.
+
 Para configuração progressiva, use o builder:
 
 ```ts
@@ -209,7 +229,7 @@ Métodos de sessão/auth ficam soltos no client; os que giram em torno de um rec
 
 | Método                                                | Endpoint                                       |
 | ----------------------------------------------------- | ---------------------------------------------- |
-| `organization.list()`                                 | `GET /auth/tenants`                            |
+| `organization.list({ search?, skip?, take? })`        | `GET /auth/tenants`                            |
 | `organization.create(params?)`                        | `POST /auth/tenants`                           |
 | `organization.get(organizationId)`                    | `GET /auth/tenants/{id}`                       |
 | `organization.rename(organizationId, name)`           | `PATCH /auth/tenants/{id}`                     |

package/dist/{ability-CVplsuzO.d.cts → ability-DhtyQ5wv.d.cts}

@@ -93,12 +93,17 @@ interface Organization {
     name?: string;
     description?: string;
     roles?: string[];
+    /** JSON-encoded values for the organization's configured custom fields. */
+    customFields?: string;
+    /** JSON-encoded metadata visible to members of the organization. */
+    publicMetadata?: string;
 }
 /** POST /auth/tenants — creates an organization owned by the signed-in user. */
 interface CreateOrganizationInput {
     name?: string;
     slug?: string;
     description?: string;
+    customFields?: Record<string, unknown>;
 }
 /** GET /auth/tenants/{organizationId}/members — confirmed against the live API. */
 interface OrganizationMember {
@@ -289,6 +294,12 @@ type AuthState = "signed_out" | "authenticated" | "expired";
 interface AuthyonClientOptions {
     /** Publishable environment key (`pk_live_...` / `pk_test_...`). */
     envKey: string;
+    /**
+     * Originating client IP to forward on every API call as `X-Forwarded-For`.
+     * Browsers cannot reliably discover their public IP by themselves; set this
+     * only when your application receives it from trusted infrastructure.
+     */
+    clientIp?: string;
     /** API origin. Defaults to `https://api.authyon.com`; HTTPS is required outside loopback. */
     baseUrl?: string;
     /** Allow an HTTP `baseUrl`. Intended only for explicitly trusted local development. */
@@ -312,6 +323,7 @@ interface AuthyonClientOptions {
 
 declare class AuthyonClient {
     private readonly envKey;
+    private readonly clientIp?;
     private readonly baseUrl;
     private readonly storage;
     private readonly autoRefresh;
@@ -421,8 +433,10 @@ declare class AuthyonClient {
         confirmPasswordReset: (token: string, newPassword: string) => Promise<void>;
     };
     readonly organization: {
-        /** GET /auth/tenants — all organization memberships. */
-        list: () => Promise<Organization[]>;
+        /** GET /auth/tenants — filterable list of organization memberships. */
+        list: (params?: {
+            search?: string;
+        } & PaginationOptions) => Promise<Organization[]>;
         /**
          * POST /auth/tenants — creates an organization owned by the signed-in
          * user (only available when self-service organization creation is
@@ -578,6 +592,13 @@ interface AuthyonPermissionSource {
     /** OAuth scopes are also accepted and interpreted as Authyon permissions. */
     scope?: string | null;
 }
+/** A declarative group of permissions evaluated against an Authyon permission source. */
+interface PermissionGroup {
+    /** Permissions that must all be granted. */
+    allOf?: readonly string[];
+    /** Permissions where at least one must be granted. */
+    anyOf?: readonly string[];
+}
 interface AuthyonAbilityOptions {
     rules?: readonly AbilityRule[];
     /** Rules added when the source contains a matching Authyon role. */
@@ -609,7 +630,14 @@ declare class AuthyonAbilityBuilder {
 }
 /** Creates an ability from Authyon permissions, OAuth scope and optional role rules. */
 declare function createAuthyonAbility(source?: AuthyonPermissionSource, options?: AuthyonAbilityOptions): AuthyonAbility;
+/** Checks an Authyon permission string using the same wildcard rules as an ability. */
+declare function hasPermission(source: AuthyonPermissionSource | readonly string[], requiredPermission: string): boolean;
+/**
+ * Checks a permission group using Authyon's standard permission and wildcard rules.
+ * Empty or omitted groups do not add authorization requirements.
+ */
+declare function hasPermissionGroup(source: AuthyonPermissionSource | readonly string[], group: PermissionGroup): boolean;
 /** Converts Authyon's `subject:action` permission strings to authorization rules. */
 declare function createAuthyonRules(source?: AuthyonPermissionSource, options?: AuthyonAbilityOptions): AbilityRule[];
 
-export { createAuthyonRules as $, AuthyonClient as A, type SessionControllerOptions as B, type CreateOrganizationInput as C, type SessionInfo as D, type SessionSnapshot as E, FetchHttpAdapter as F, type SessionSnapshotListener as G, type HttpAdapter as H, type IntrospectResult as I, type SessionStatus as J, type SsoProvider as K, LoggingHttpAdapter as L, type TwoFactorChallenge as M, type TwoFactorMethod as N, type Organization as O, type Paged as P, type TwoFactorStatus as Q, type RegisterInput as R, type Session as S, type TokenStorage as T, type User as U, type ValidateResult as V, type VerifyTwoFactorInput as W, type WebAuthnAssertion as X, type WebAuthnCeremonyStart as Y, type WebAuthnCredential as Z, createAuthyonAbility as _, type HttpLoggerOptions as a, createClient as a0, type AbilityConditions as b, type AbilityEvent as c, type AbilityListener as d, type AbilityRule as e, type AbilitySubject as f, type Activity as g, type AuthEvent as h, type AuthState as i, type AuthStateListener as j, type AuthenticatorSetup as k, AuthyonAbility as l, AuthyonAbilityBuilder as m, type AuthyonAbilityOptions as n, type AuthyonClientOptions as o, type AuthyonPermissionSource as p, AuthyonSessionController as q, type HttpAdapterRequest as r, type HttpLogEvent as s, type HttpLogger as t, type InviteMemberInput as u, type LoginInput as v, type LoginResult as w, type OrganizationMember as x, type PaginationOptions as y, type Role as z };
+export { createAuthyonAbility as $, AuthyonClient as A, type Role as B, type CreateOrganizationInput as C, type SessionControllerOptions as D, type SessionInfo as E, FetchHttpAdapter as F, type SessionSnapshot as G, type HttpAdapter as H, type IntrospectResult as I, type SessionSnapshotListener as J, type SessionStatus as K, LoggingHttpAdapter as L, type SsoProvider as M, type TwoFactorChallenge as N, type Organization as O, type Paged as P, type TwoFactorMethod as Q, type RegisterInput as R, type Session as S, type TokenStorage as T, type TwoFactorStatus as U, type User as V, type ValidateResult as W, type VerifyTwoFactorInput as X, type WebAuthnAssertion as Y, type WebAuthnCeremonyStart as Z, type WebAuthnCredential as _, type HttpLoggerOptions as a, createAuthyonRules as a0, createClient as a1, hasPermission as a2, hasPermissionGroup as a3, type AbilityConditions as b, type AbilityEvent as c, type AbilityListener as d, type AbilityRule as e, type AbilitySubject as f, type Activity as g, type AuthEvent as h, type AuthState as i, type AuthStateListener as j, type AuthenticatorSetup as k, AuthyonAbility as l, AuthyonAbilityBuilder as m, type AuthyonAbilityOptions as n, type AuthyonClientOptions as o, type AuthyonPermissionSource as p, AuthyonSessionController as q, type HttpAdapterRequest as r, type HttpLogEvent as s, type HttpLogger as t, type InviteMemberInput as u, type LoginInput as v, type LoginResult as w, type OrganizationMember as x, type PaginationOptions as y, type PermissionGroup as z };

package/dist/{ability-CVplsuzO.d.ts → ability-DhtyQ5wv.d.ts}

@@ -93,12 +93,17 @@ interface Organization {
     name?: string;
     description?: string;
     roles?: string[];
+    /** JSON-encoded values for the organization's configured custom fields. */
+    customFields?: string;
+    /** JSON-encoded metadata visible to members of the organization. */
+    publicMetadata?: string;
 }
 /** POST /auth/tenants — creates an organization owned by the signed-in user. */
 interface CreateOrganizationInput {
     name?: string;
     slug?: string;
     description?: string;
+    customFields?: Record<string, unknown>;
 }
 /** GET /auth/tenants/{organizationId}/members — confirmed against the live API. */
 interface OrganizationMember {
@@ -289,6 +294,12 @@ type AuthState = "signed_out" | "authenticated" | "expired";
 interface AuthyonClientOptions {
     /** Publishable environment key (`pk_live_...` / `pk_test_...`). */
     envKey: string;
+    /**
+     * Originating client IP to forward on every API call as `X-Forwarded-For`.
+     * Browsers cannot reliably discover their public IP by themselves; set this
+     * only when your application receives it from trusted infrastructure.
+     */
+    clientIp?: string;
     /** API origin. Defaults to `https://api.authyon.com`; HTTPS is required outside loopback. */
     baseUrl?: string;
     /** Allow an HTTP `baseUrl`. Intended only for explicitly trusted local development. */
@@ -312,6 +323,7 @@ interface AuthyonClientOptions {
 
 declare class AuthyonClient {
     private readonly envKey;
+    private readonly clientIp?;
     private readonly baseUrl;
     private readonly storage;
     private readonly autoRefresh;
@@ -421,8 +433,10 @@ declare class AuthyonClient {
         confirmPasswordReset: (token: string, newPassword: string) => Promise<void>;
     };
     readonly organization: {
-        /** GET /auth/tenants — all organization memberships. */
-        list: () => Promise<Organization[]>;
+        /** GET /auth/tenants — filterable list of organization memberships. */
+        list: (params?: {
+            search?: string;
+        } & PaginationOptions) => Promise<Organization[]>;
         /**
          * POST /auth/tenants — creates an organization owned by the signed-in
          * user (only available when self-service organization creation is
@@ -578,6 +592,13 @@ interface AuthyonPermissionSource {
     /** OAuth scopes are also accepted and interpreted as Authyon permissions. */
     scope?: string | null;
 }
+/** A declarative group of permissions evaluated against an Authyon permission source. */
+interface PermissionGroup {
+    /** Permissions that must all be granted. */
+    allOf?: readonly string[];
+    /** Permissions where at least one must be granted. */
+    anyOf?: readonly string[];
+}
 interface AuthyonAbilityOptions {
     rules?: readonly AbilityRule[];
     /** Rules added when the source contains a matching Authyon role. */
@@ -609,7 +630,14 @@ declare class AuthyonAbilityBuilder {
 }
 /** Creates an ability from Authyon permissions, OAuth scope and optional role rules. */
 declare function createAuthyonAbility(source?: AuthyonPermissionSource, options?: AuthyonAbilityOptions): AuthyonAbility;
+/** Checks an Authyon permission string using the same wildcard rules as an ability. */
+declare function hasPermission(source: AuthyonPermissionSource | readonly string[], requiredPermission: string): boolean;
+/**
+ * Checks a permission group using Authyon's standard permission and wildcard rules.
+ * Empty or omitted groups do not add authorization requirements.
+ */
+declare function hasPermissionGroup(source: AuthyonPermissionSource | readonly string[], group: PermissionGroup): boolean;
 /** Converts Authyon's `subject:action` permission strings to authorization rules. */
 declare function createAuthyonRules(source?: AuthyonPermissionSource, options?: AuthyonAbilityOptions): AbilityRule[];
 
-export { createAuthyonRules as $, AuthyonClient as A, type SessionControllerOptions as B, type CreateOrganizationInput as C, type SessionInfo as D, type SessionSnapshot as E, FetchHttpAdapter as F, type SessionSnapshotListener as G, type HttpAdapter as H, type IntrospectResult as I, type SessionStatus as J, type SsoProvider as K, LoggingHttpAdapter as L, type TwoFactorChallenge as M, type TwoFactorMethod as N, type Organization as O, type Paged as P, type TwoFactorStatus as Q, type RegisterInput as R, type Session as S, type TokenStorage as T, type User as U, type ValidateResult as V, type VerifyTwoFactorInput as W, type WebAuthnAssertion as X, type WebAuthnCeremonyStart as Y, type WebAuthnCredential as Z, createAuthyonAbility as _, type HttpLoggerOptions as a, createClient as a0, type AbilityConditions as b, type AbilityEvent as c, type AbilityListener as d, type AbilityRule as e, type AbilitySubject as f, type Activity as g, type AuthEvent as h, type AuthState as i, type AuthStateListener as j, type AuthenticatorSetup as k, AuthyonAbility as l, AuthyonAbilityBuilder as m, type AuthyonAbilityOptions as n, type AuthyonClientOptions as o, type AuthyonPermissionSource as p, AuthyonSessionController as q, type HttpAdapterRequest as r, type HttpLogEvent as s, type HttpLogger as t, type InviteMemberInput as u, type LoginInput as v, type LoginResult as w, type OrganizationMember as x, type PaginationOptions as y, type Role as z };
+export { createAuthyonAbility as $, AuthyonClient as A, type Role as B, type CreateOrganizationInput as C, type SessionControllerOptions as D, type SessionInfo as E, FetchHttpAdapter as F, type SessionSnapshot as G, type HttpAdapter as H, type IntrospectResult as I, type SessionSnapshotListener as J, type SessionStatus as K, LoggingHttpAdapter as L, type SsoProvider as M, type TwoFactorChallenge as N, type Organization as O, type Paged as P, type TwoFactorMethod as Q, type RegisterInput as R, type Session as S, type TokenStorage as T, type TwoFactorStatus as U, type User as V, type ValidateResult as W, type VerifyTwoFactorInput as X, type WebAuthnAssertion as Y, type WebAuthnCeremonyStart as Z, type WebAuthnCredential as _, type HttpLoggerOptions as a, createAuthyonRules as a0, createClient as a1, hasPermission as a2, hasPermissionGroup as a3, type AbilityConditions as b, type AbilityEvent as c, type AbilityListener as d, type AbilityRule as e, type AbilitySubject as f, type Activity as g, type AuthEvent as h, type AuthState as i, type AuthStateListener as j, type AuthenticatorSetup as k, AuthyonAbility as l, AuthyonAbilityBuilder as m, type AuthyonAbilityOptions as n, type AuthyonClientOptions as o, type AuthyonPermissionSource as p, AuthyonSessionController as q, type HttpAdapterRequest as r, type HttpLogEvent as s, type HttpLogger as t, type InviteMemberInput as u, type LoginInput as v, type LoginResult as w, type OrganizationMember as x, type PaginationOptions as y, type PermissionGroup as z };

package/dist/{chunk-OKPSF4LZ.js → chunk-3XJY6BCI.js}

@@ -1,6 +1,9 @@
 // src/session/sessionController.ts
 var SERVER_SNAPSHOT = {
-  status: "unauthenticated",
+  // 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
@@ -190,6 +193,22 @@ var AuthyonAbilityBuilder = class {
 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 ?? [],
@@ -219,9 +238,14 @@ function permissionToRule(permission) {
 }
 function matchesToken(value, expected, wildcard) {
   return (Array.isArray(value) ? value : [value]).some(
-    (candidate) => candidate === expected || candidate === wildcard || candidate === "*"
+    (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));
@@ -299,5 +323,7 @@ export {
   AuthyonAbility,
   AuthyonAbilityBuilder,
   createAuthyonAbility,
+  hasPermission,
+  hasPermissionGroup,
   createAuthyonRules
 };

package/dist/index.cjs

@@ -34,7 +34,9 @@ __export(index_exports, {
   createClient: () => createClient,
   createDefaultStorage: () => createDefaultStorage,
   createLocalStorage: () => createLocalStorage,
-  createMemoryStorage: () => createMemoryStorage
+  createMemoryStorage: () => createMemoryStorage,
+  hasPermission: () => hasPermission,
+  hasPermissionGroup: () => hasPermissionGroup
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -222,7 +224,8 @@ var FetchHttpAdapter = class {
       method: request.method,
       headers: request.headers,
       body: request.body,
-      signal: request.signal
+      signal: request.signal,
+      redirect: "error"
     });
   }
 };
@@ -274,6 +277,10 @@ function defaultHttpLogger(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("&") : "";
@@ -397,6 +404,28 @@ var JsonHttpClient = class {
   }
 };
 
+// ../../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) {
@@ -484,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
@@ -612,6 +641,7 @@ var AuthyonClient = class {
     if (!options.envKey)
       throw new Error("Authyon: `envKey` is required (pk_live_... / pk_test_...)");
     this.envKey = options.envKey;
+    this.clientIp = options.clientIp;
     this.transport = createSharedTransport({
       baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
       allowInsecureHttp: options.allowInsecureHttp,
@@ -724,6 +754,7 @@ var AuthyonClient = class {
   async request(path, options = {}, isRetry = false) {
     const headers = {
       "X-Authyon-Environment": this.envKey,
+      ...clientIpHeaders({ clientIp: this.clientIp }),
       ...options.headers
     };
     if (options.bearer) {
@@ -888,6 +919,10 @@ var AuthyonClientBuilder = class {
     this.options.autoRefresh = enabled;
     return this;
   }
+  withClientIp(clientIp) {
+    this.options.clientIp = clientIp;
+    return this;
+  }
   withTimeout(timeoutMs) {
     this.options.timeoutMs = timeoutMs;
     return this;
@@ -907,7 +942,10 @@ var AuthyonClientBuilder = class {
 
 // src/session/sessionController.ts
 var SERVER_SNAPSHOT = {
-  status: "unauthenticated",
+  // 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
@@ -1097,6 +1135,22 @@ var AuthyonAbilityBuilder = class {
 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 ?? [],
@@ -1126,9 +1180,14 @@ function permissionToRule(permission) {
 }
 function matchesToken(value, expected, wildcard) {
   return (Array.isArray(value) ? value : [value]).some(
-    (candidate) => candidate === expected || candidate === wildcard || candidate === "*"
+    (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));
@@ -1216,5 +1275,7 @@ function isAbilityRule(value) {
   createClient,
   createDefaultStorage,
   createLocalStorage,
-  createMemoryStorage
+  createMemoryStorage,
+  hasPermission,
+  hasPermissionGroup
 });

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { T as TokenStorage, H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonClient } from './ability-CVplsuzO.cjs';
-export { b as AbilityConditions, c as AbilityEvent, d as AbilityListener, e as AbilityRule, f as AbilitySubject, g as Activity, h as AuthEvent, i as AuthState, j as AuthStateListener, k as AuthenticatorSetup, l as AuthyonAbility, m as AuthyonAbilityBuilder, n as AuthyonAbilityOptions, o as AuthyonClientOptions, p as AuthyonPermissionSource, q as AuthyonSessionController, C as CreateOrganizationInput, F as FetchHttpAdapter, r as HttpAdapterRequest, s as HttpLogEvent, t as HttpLogger, I as IntrospectResult, u as InviteMemberInput, L as LoggingHttpAdapter, v as LoginInput, w as LoginResult, O as Organization, x as OrganizationMember, P as Paged, y as PaginationOptions, R as RegisterInput, z as Role, S as Session, B as SessionControllerOptions, D as SessionInfo, E as SessionSnapshot, G as SessionSnapshotListener, J as SessionStatus, K as SsoProvider, M as TwoFactorChallenge, N as TwoFactorMethod, Q as TwoFactorStatus, U as User, V as ValidateResult, W as VerifyTwoFactorInput, X as WebAuthnAssertion, Y as WebAuthnCeremonyStart, Z as WebAuthnCredential, _ as createAuthyonAbility, $ as createAuthyonRules, a0 as createClient } from './ability-CVplsuzO.cjs';
+import { T as TokenStorage, H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonClient } from './ability-DhtyQ5wv.cjs';
+export { b as AbilityConditions, c as AbilityEvent, d as AbilityListener, e as AbilityRule, f as AbilitySubject, g as Activity, h as AuthEvent, i as AuthState, j as AuthStateListener, k as AuthenticatorSetup, l as AuthyonAbility, m as AuthyonAbilityBuilder, n as AuthyonAbilityOptions, o as AuthyonClientOptions, p as AuthyonPermissionSource, q as AuthyonSessionController, C as CreateOrganizationInput, F as FetchHttpAdapter, r as HttpAdapterRequest, s as HttpLogEvent, t as HttpLogger, I as IntrospectResult, u as InviteMemberInput, L as LoggingHttpAdapter, v as LoginInput, w as LoginResult, O as Organization, x as OrganizationMember, P as Paged, y as PaginationOptions, z as PermissionGroup, R as RegisterInput, B as Role, S as Session, D as SessionControllerOptions, E as SessionInfo, G as SessionSnapshot, J as SessionSnapshotListener, K as SessionStatus, M as SsoProvider, N as TwoFactorChallenge, Q as TwoFactorMethod, U as TwoFactorStatus, V as User, W as ValidateResult, X as VerifyTwoFactorInput, Y as WebAuthnAssertion, Z as WebAuthnCeremonyStart, _ as WebAuthnCredential, $ as createAuthyonAbility, a0 as createAuthyonRules, a1 as createClient, a2 as hasPermission, a3 as hasPermissionGroup } from './ability-DhtyQ5wv.cjs';
 
 /** Builds an Authyon browser client through explicit, progressive configuration. */
 declare class AuthyonClientBuilder {
@@ -8,6 +8,7 @@ declare class AuthyonClientBuilder {
     withBaseUrl(baseUrl: string, allowInsecureHttp?: boolean): this;
     withStorage(storage: TokenStorage): this;
     withAutomaticRefresh(enabled?: boolean): this;
+    withClientIp(clientIp: string): this;
     withTimeout(timeoutMs: number): this;
     withHttpAdapter(httpAdapter: HttpAdapter): this;
     withHttpLogger(httpLogger: HttpLoggerOptions): this;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { T as TokenStorage, H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonClient } from './ability-CVplsuzO.js';
-export { b as AbilityConditions, c as AbilityEvent, d as AbilityListener, e as AbilityRule, f as AbilitySubject, g as Activity, h as AuthEvent, i as AuthState, j as AuthStateListener, k as AuthenticatorSetup, l as AuthyonAbility, m as AuthyonAbilityBuilder, n as AuthyonAbilityOptions, o as AuthyonClientOptions, p as AuthyonPermissionSource, q as AuthyonSessionController, C as CreateOrganizationInput, F as FetchHttpAdapter, r as HttpAdapterRequest, s as HttpLogEvent, t as HttpLogger, I as IntrospectResult, u as InviteMemberInput, L as LoggingHttpAdapter, v as LoginInput, w as LoginResult, O as Organization, x as OrganizationMember, P as Paged, y as PaginationOptions, R as RegisterInput, z as Role, S as Session, B as SessionControllerOptions, D as SessionInfo, E as SessionSnapshot, G as SessionSnapshotListener, J as SessionStatus, K as SsoProvider, M as TwoFactorChallenge, N as TwoFactorMethod, Q as TwoFactorStatus, U as User, V as ValidateResult, W as VerifyTwoFactorInput, X as WebAuthnAssertion, Y as WebAuthnCeremonyStart, Z as WebAuthnCredential, _ as createAuthyonAbility, $ as createAuthyonRules, a0 as createClient } from './ability-CVplsuzO.js';
+import { T as TokenStorage, H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonClient } from './ability-DhtyQ5wv.js';
+export { b as AbilityConditions, c as AbilityEvent, d as AbilityListener, e as AbilityRule, f as AbilitySubject, g as Activity, h as AuthEvent, i as AuthState, j as AuthStateListener, k as AuthenticatorSetup, l as AuthyonAbility, m as AuthyonAbilityBuilder, n as AuthyonAbilityOptions, o as AuthyonClientOptions, p as AuthyonPermissionSource, q as AuthyonSessionController, C as CreateOrganizationInput, F as FetchHttpAdapter, r as HttpAdapterRequest, s as HttpLogEvent, t as HttpLogger, I as IntrospectResult, u as InviteMemberInput, L as LoggingHttpAdapter, v as LoginInput, w as LoginResult, O as Organization, x as OrganizationMember, P as Paged, y as PaginationOptions, z as PermissionGroup, R as RegisterInput, B as Role, S as Session, D as SessionControllerOptions, E as SessionInfo, G as SessionSnapshot, J as SessionSnapshotListener, K as SessionStatus, M as SsoProvider, N as TwoFactorChallenge, Q as TwoFactorMethod, U as TwoFactorStatus, V as User, W as ValidateResult, X as VerifyTwoFactorInput, Y as WebAuthnAssertion, Z as WebAuthnCeremonyStart, _ as WebAuthnCredential, $ as createAuthyonAbility, a0 as createAuthyonRules, a1 as createClient, a2 as hasPermission, a3 as hasPermissionGroup } from './ability-DhtyQ5wv.js';
 
 /** Builds an Authyon browser client through explicit, progressive configuration. */
 declare class AuthyonClientBuilder {
@@ -8,6 +8,7 @@ declare class AuthyonClientBuilder {
     withBaseUrl(baseUrl: string, allowInsecureHttp?: boolean): this;
     withStorage(storage: TokenStorage): this;
     withAutomaticRefresh(enabled?: boolean): this;
+    withClientIp(clientIp: string): this;
     withTimeout(timeoutMs: number): this;
     withHttpAdapter(httpAdapter: HttpAdapter): this;
     withHttpLogger(httpLogger: HttpLoggerOptions): this;

package/dist/index.js

@@ -3,8 +3,10 @@ import {
   AuthyonAbilityBuilder,
   AuthyonSessionController,
   createAuthyonAbility,
-  createAuthyonRules
-} from "./chunk-OKPSF4LZ.js";
+  createAuthyonRules,
+  hasPermission,
+  hasPermissionGroup
+} from "./chunk-3XJY6BCI.js";
 
 // ../../internal/core/errors/authyonError.ts
 var ErrorCodes = {
@@ -190,7 +192,8 @@ var FetchHttpAdapter = class {
       method: request.method,
       headers: request.headers,
       body: request.body,
-      signal: request.signal
+      signal: request.signal,
+      redirect: "error"
     });
   }
 };
@@ -242,6 +245,10 @@ function defaultHttpLogger(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("&") : "";
@@ -365,6 +372,28 @@ var JsonHttpClient = class {
   }
 };
 
+// ../../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) {
@@ -452,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
@@ -580,6 +609,7 @@ var AuthyonClient = class {
     if (!options.envKey)
       throw new Error("Authyon: `envKey` is required (pk_live_... / pk_test_...)");
     this.envKey = options.envKey;
+    this.clientIp = options.clientIp;
     this.transport = createSharedTransport({
       baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
       allowInsecureHttp: options.allowInsecureHttp,
@@ -692,6 +722,7 @@ var AuthyonClient = class {
   async request(path, options = {}, isRetry = false) {
     const headers = {
       "X-Authyon-Environment": this.envKey,
+      ...clientIpHeaders({ clientIp: this.clientIp }),
       ...options.headers
     };
     if (options.bearer) {
@@ -856,6 +887,10 @@ var AuthyonClientBuilder = class {
     this.options.autoRefresh = enabled;
     return this;
   }
+  withClientIp(clientIp) {
+    this.options.clientIp = clientIp;
+    return this;
+  }
   withTimeout(timeoutMs) {
     this.options.timeoutMs = timeoutMs;
     return this;
@@ -887,5 +922,7 @@ export {
   createClient,
   createDefaultStorage,
   createLocalStorage,
-  createMemoryStorage
+  createMemoryStorage,
+  hasPermission,
+  hasPermissionGroup
 };

package/dist/react/index.cjs

@@ -107,9 +107,14 @@ function permissionToRule(permission) {
 }
 function matchesToken(value, expected, wildcard) {
   return (Array.isArray(value) ? value : [value]).some(
-    (candidate) => candidate === expected || candidate === wildcard || candidate === "*"
+    (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));
@@ -184,7 +189,10 @@ function isAbilityRule(value) {
 
 // src/session/sessionController.ts
 var SERVER_SNAPSHOT = {
-  status: "unauthenticated",
+  // 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
@@ -318,7 +326,8 @@ function AuthyonProvider({
   client,
   children,
   refreshAheadMs,
-  validateOnFocus = true
+  validateOnFocus = true,
+  transformUser
 }) {
   const controllerRef = (0, import_react.useRef)(null);
   if (!controllerRef.current || controllerRef.current.client !== client) {
@@ -339,14 +348,18 @@ function AuthyonProvider({
     document.addEventListener("visibilitychange", validateWhenVisible);
     return () => document.removeEventListener("visibilitychange", validateWhenVisible);
   }, [controller, validateOnFocus]);
+  const exposedSnapshot = (0, import_react.useMemo)(
+    () => transformSnapshot(snapshot, transformUser),
+    [snapshot, transformUser]
+  );
   const value = (0, import_react.useMemo)(
     () => ({
-      ...snapshot,
+      ...exposedSnapshot,
       client,
-      validateSession: () => controller.validate(),
-      refreshSession: () => controller.refreshNow()
+      validateSession: async () => transformSnapshot(await controller.validate(), transformUser),
+      refreshSession: async () => transformSnapshot(await controller.refreshNow(), transformUser)
     }),
-    [client, controller, snapshot]
+    [client, controller, exposedSnapshot, transformUser]
   );
   return (0, import_react.createElement)(AuthyonReactContext.Provider, { value }, children);
 }
@@ -355,6 +368,15 @@ function useAuthyon() {
   if (!context) throw new Error("Authyon: `useAuthyon` must be used inside `AuthyonProvider`");
   return context;
 }
+function transformSnapshot(snapshot, transformUser) {
+  const mapUser = (user2) => transformUser ? transformUser(user2) : user2;
+  const user = snapshot.user ? mapUser(snapshot.user) : null;
+  const session = snapshot.session ? {
+    ...snapshot.session,
+    user: snapshot.session.user ? snapshot.session.user === snapshot.user && user ? user : mapUser(snapshot.session.user) : void 0
+  } : null;
+  return { ...snapshot, session, user };
+}
 function useAuthyonAbility(options = {}) {
   const { user } = useAuthyon();
   return (0, import_react.useMemo)(() => createAuthyonAbility(user ?? {}, options), [user, options]);

package/dist/react/index.d.cts

@@ -1,21 +1,30 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { B as SessionControllerOptions, A as AuthyonClient, E as SessionSnapshot, f as AbilitySubject, n as AuthyonAbilityOptions, l as AuthyonAbility } from '../ability-CVplsuzO.cjs';
-export { q as AuthyonSessionController, G as SessionSnapshotListener, J as SessionStatus } from '../ability-CVplsuzO.cjs';
+import { V as User, D as SessionControllerOptions, A as AuthyonClient, G as SessionSnapshot, S as Session, f as AbilitySubject, n as AuthyonAbilityOptions, l as AuthyonAbility } from '../ability-DhtyQ5wv.cjs';
+export { q as AuthyonSessionController, J as SessionSnapshotListener, K as SessionStatus } from '../ability-DhtyQ5wv.cjs';
 
-interface AuthyonProviderProps extends SessionControllerOptions {
+interface AuthyonProviderProps<TUser extends User = User> extends SessionControllerOptions {
     client: AuthyonClient;
     children: ReactNode;
     /** Revalidate with `/auth/me` when the tab becomes visible. Defaults to true. */
     validateOnFocus?: boolean;
+    /** Derives the user exposed by `useAuthyon` without mutating the stored Authyon session. */
+    transformUser?: (user: User) => TUser;
 }
-interface AuthyonReactContextValue extends SessionSnapshot {
+type AuthyonSession<TUser extends User = User> = Omit<Session, "user"> & {
+    user?: TUser;
+};
+type AuthyonSessionSnapshot<TUser extends User = User> = Omit<SessionSnapshot, "session" | "user"> & {
+    session: AuthyonSession<TUser> | null;
+    user: TUser | null;
+};
+interface AuthyonReactContextValue<TUser extends User = User> extends AuthyonSessionSnapshot<TUser> {
     client: AuthyonClient;
-    validateSession(): Promise<SessionSnapshot>;
-    refreshSession(): Promise<SessionSnapshot>;
+    validateSession(): Promise<AuthyonSessionSnapshot<TUser>>;
+    refreshSession(): Promise<AuthyonSessionSnapshot<TUser>>;
 }
-declare function AuthyonProvider({ client, children, refreshAheadMs, validateOnFocus, }: AuthyonProviderProps): react.FunctionComponentElement<react.ProviderProps<AuthyonReactContextValue | null>>;
-declare function useAuthyon(): AuthyonReactContextValue;
+declare function AuthyonProvider<TUser extends User = User>({ client, children, refreshAheadMs, validateOnFocus, transformUser, }: AuthyonProviderProps<TUser>): react.FunctionComponentElement<react.ProviderProps<AuthyonReactContextValue<User> | null>>;
+declare function useAuthyon<TUser extends User = User>(): AuthyonReactContextValue<TUser>;
 declare function useAuthyonAbility(options?: AuthyonAbilityOptions): AuthyonAbility;
 declare function useCan(action: string, subject: AbilitySubject, field?: string, options?: AuthyonAbilityOptions): boolean;
 interface SessionGuardProps {
@@ -35,4 +44,4 @@ interface PermissionGuardProps extends SessionGuardProps {
 }
 declare function PermissionGuard({ action, subject, field, forbiddenFallback, abilityOptions, children, ...sessionProps }: PermissionGuardProps): react.FunctionComponentElement<SessionGuardProps>;
 
-export { AuthyonProvider, type AuthyonProviderProps, PermissionGuard, type PermissionGuardProps, SessionControllerOptions, SessionGuard, type SessionGuardProps, SessionSnapshot, useAuthyon, useAuthyonAbility, useCan };
+export { AuthyonProvider, type AuthyonProviderProps, type AuthyonReactContextValue, type AuthyonSession, type AuthyonSessionSnapshot, PermissionGuard, type PermissionGuardProps, SessionControllerOptions, SessionGuard, type SessionGuardProps, SessionSnapshot, useAuthyon, useAuthyonAbility, useCan };

package/dist/react/index.d.ts

@@ -1,21 +1,30 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { B as SessionControllerOptions, A as AuthyonClient, E as SessionSnapshot, f as AbilitySubject, n as AuthyonAbilityOptions, l as AuthyonAbility } from '../ability-CVplsuzO.js';
-export { q as AuthyonSessionController, G as SessionSnapshotListener, J as SessionStatus } from '../ability-CVplsuzO.js';
+import { V as User, D as SessionControllerOptions, A as AuthyonClient, G as SessionSnapshot, S as Session, f as AbilitySubject, n as AuthyonAbilityOptions, l as AuthyonAbility } from '../ability-DhtyQ5wv.js';
+export { q as AuthyonSessionController, J as SessionSnapshotListener, K as SessionStatus } from '../ability-DhtyQ5wv.js';
 
-interface AuthyonProviderProps extends SessionControllerOptions {
+interface AuthyonProviderProps<TUser extends User = User> extends SessionControllerOptions {
     client: AuthyonClient;
     children: ReactNode;
     /** Revalidate with `/auth/me` when the tab becomes visible. Defaults to true. */
     validateOnFocus?: boolean;
+    /** Derives the user exposed by `useAuthyon` without mutating the stored Authyon session. */
+    transformUser?: (user: User) => TUser;
 }
-interface AuthyonReactContextValue extends SessionSnapshot {
+type AuthyonSession<TUser extends User = User> = Omit<Session, "user"> & {
+    user?: TUser;
+};
+type AuthyonSessionSnapshot<TUser extends User = User> = Omit<SessionSnapshot, "session" | "user"> & {
+    session: AuthyonSession<TUser> | null;
+    user: TUser | null;
+};
+interface AuthyonReactContextValue<TUser extends User = User> extends AuthyonSessionSnapshot<TUser> {
     client: AuthyonClient;
-    validateSession(): Promise<SessionSnapshot>;
-    refreshSession(): Promise<SessionSnapshot>;
+    validateSession(): Promise<AuthyonSessionSnapshot<TUser>>;
+    refreshSession(): Promise<AuthyonSessionSnapshot<TUser>>;
 }
-declare function AuthyonProvider({ client, children, refreshAheadMs, validateOnFocus, }: AuthyonProviderProps): react.FunctionComponentElement<react.ProviderProps<AuthyonReactContextValue | null>>;
-declare function useAuthyon(): AuthyonReactContextValue;
+declare function AuthyonProvider<TUser extends User = User>({ client, children, refreshAheadMs, validateOnFocus, transformUser, }: AuthyonProviderProps<TUser>): react.FunctionComponentElement<react.ProviderProps<AuthyonReactContextValue<User> | null>>;
+declare function useAuthyon<TUser extends User = User>(): AuthyonReactContextValue<TUser>;
 declare function useAuthyonAbility(options?: AuthyonAbilityOptions): AuthyonAbility;
 declare function useCan(action: string, subject: AbilitySubject, field?: string, options?: AuthyonAbilityOptions): boolean;
 interface SessionGuardProps {
@@ -35,4 +44,4 @@ interface PermissionGuardProps extends SessionGuardProps {
 }
 declare function PermissionGuard({ action, subject, field, forbiddenFallback, abilityOptions, children, ...sessionProps }: PermissionGuardProps): react.FunctionComponentElement<SessionGuardProps>;
 
-export { AuthyonProvider, type AuthyonProviderProps, PermissionGuard, type PermissionGuardProps, SessionControllerOptions, SessionGuard, type SessionGuardProps, SessionSnapshot, useAuthyon, useAuthyonAbility, useCan };
+export { AuthyonProvider, type AuthyonProviderProps, type AuthyonReactContextValue, type AuthyonSession, type AuthyonSessionSnapshot, PermissionGuard, type PermissionGuardProps, SessionControllerOptions, SessionGuard, type SessionGuardProps, SessionSnapshot, useAuthyon, useAuthyonAbility, useCan };

package/dist/react/index.js

@@ -2,7 +2,7 @@
 import {
   AuthyonSessionController,
   createAuthyonAbility
-} from "../chunk-OKPSF4LZ.js";
+} from "../chunk-3XJY6BCI.js";
 
 // src/react/index.tsx
 import {
@@ -19,7 +19,8 @@ function AuthyonProvider({
   client,
   children,
   refreshAheadMs,
-  validateOnFocus = true
+  validateOnFocus = true,
+  transformUser
 }) {
   const controllerRef = useRef(null);
   if (!controllerRef.current || controllerRef.current.client !== client) {
@@ -40,14 +41,18 @@ function AuthyonProvider({
     document.addEventListener("visibilitychange", validateWhenVisible);
     return () => document.removeEventListener("visibilitychange", validateWhenVisible);
   }, [controller, validateOnFocus]);
+  const exposedSnapshot = useMemo(
+    () => transformSnapshot(snapshot, transformUser),
+    [snapshot, transformUser]
+  );
   const value = useMemo(
     () => ({
-      ...snapshot,
+      ...exposedSnapshot,
       client,
-      validateSession: () => controller.validate(),
-      refreshSession: () => controller.refreshNow()
+      validateSession: async () => transformSnapshot(await controller.validate(), transformUser),
+      refreshSession: async () => transformSnapshot(await controller.refreshNow(), transformUser)
     }),
-    [client, controller, snapshot]
+    [client, controller, exposedSnapshot, transformUser]
   );
   return createElement(AuthyonReactContext.Provider, { value }, children);
 }
@@ -56,6 +61,15 @@ function useAuthyon() {
   if (!context) throw new Error("Authyon: `useAuthyon` must be used inside `AuthyonProvider`");
   return context;
 }
+function transformSnapshot(snapshot, transformUser) {
+  const mapUser = (user2) => transformUser ? transformUser(user2) : user2;
+  const user = snapshot.user ? mapUser(snapshot.user) : null;
+  const session = snapshot.session ? {
+    ...snapshot.session,
+    user: snapshot.session.user ? snapshot.session.user === snapshot.user && user ? user : mapUser(snapshot.session.user) : void 0
+  } : null;
+  return { ...snapshot, session, user };
+}
 function useAuthyonAbility(options = {}) {
   const { user } = useAuthyon();
   return useMemo(() => createAuthyonAbility(user ?? {}, options), [user, options]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@authyon/auth",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.11",
   "description": "Authyon SDK for browsers — auth, sessions, multi-tenant and 2FA for vanilla JS/TS.",
   "license": "MIT",
   "type": "module",