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

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

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

@@ -609,7 +609,9 @@ 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;
 /** 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 { 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, hasPermission as a1, 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 };

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

@@ -609,7 +609,9 @@ 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;
 /** 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 { 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, hasPermission as a1, 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 };

package/dist/{chunk-OKPSF4LZ.js → chunk-EHZEUM47.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,17 @@ 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 isPermissionList(source) {
+  return Array.isArray(source);
+}
 function createAuthyonRules(source = {}, options = {}) {
   const permissions = /* @__PURE__ */ new Set([
     ...source.permissions ?? [],
@@ -219,9 +233,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 +318,6 @@ export {
   AuthyonAbility,
   AuthyonAbilityBuilder,
   createAuthyonAbility,
+  hasPermission,
   createAuthyonRules
 };

package/dist/index.cjs

@@ -34,7 +34,8 @@ __export(index_exports, {
   createClient: () => createClient,
   createDefaultStorage: () => createDefaultStorage,
   createLocalStorage: () => createLocalStorage,
-  createMemoryStorage: () => createMemoryStorage
+  createMemoryStorage: () => createMemoryStorage,
+  hasPermission: () => hasPermission
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -222,7 +223,8 @@ var FetchHttpAdapter = class {
       method: request.method,
       headers: request.headers,
       body: request.body,
-      signal: request.signal
+      signal: request.signal,
+      redirect: "error"
     });
   }
 };
@@ -274,6 +276,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("&") : "";
@@ -907,7 +913,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 +1106,17 @@ 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 isPermissionList(source) {
+  return Array.isArray(source);
+}
 function createAuthyonRules(source = {}, options = {}) {
   const permissions = /* @__PURE__ */ new Set([
     ...source.permissions ?? [],
@@ -1126,9 +1146,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 +1241,6 @@ function isAbilityRule(value) {
   createClient,
   createDefaultStorage,
   createLocalStorage,
-  createMemoryStorage
+  createMemoryStorage,
+  hasPermission
 });

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-g6nBpOQM.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, a1 as hasPermission } from './ability-g6nBpOQM.cjs';
 
 /** Builds an Authyon browser client through explicit, progressive configuration. */
 declare class AuthyonClientBuilder {

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-g6nBpOQM.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, a1 as hasPermission } from './ability-g6nBpOQM.js';
 
 /** Builds an Authyon browser client through explicit, progressive configuration. */
 declare class AuthyonClientBuilder {

package/dist/index.js

@@ -3,8 +3,9 @@ import {
   AuthyonAbilityBuilder,
   AuthyonSessionController,
   createAuthyonAbility,
-  createAuthyonRules
-} from "./chunk-OKPSF4LZ.js";
+  createAuthyonRules,
+  hasPermission
+} from "./chunk-EHZEUM47.js";
 
 // ../../internal/core/errors/authyonError.ts
 var ErrorCodes = {
@@ -190,7 +191,8 @@ var FetchHttpAdapter = class {
       method: request.method,
       headers: request.headers,
       body: request.body,
-      signal: request.signal
+      signal: request.signal,
+      redirect: "error"
     });
   }
 };
@@ -242,6 +244,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("&") : "";
@@ -887,5 +893,6 @@ export {
   createClient,
   createDefaultStorage,
   createLocalStorage,
-  createMemoryStorage
+  createMemoryStorage,
+  hasPermission
 };

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 { U as User, B as SessionControllerOptions, A as AuthyonClient, E as SessionSnapshot, S as Session, f as AbilitySubject, n as AuthyonAbilityOptions, l as AuthyonAbility } from '../ability-g6nBpOQM.cjs';
+export { q as AuthyonSessionController, G as SessionSnapshotListener, J as SessionStatus } from '../ability-g6nBpOQM.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 { U as User, B as SessionControllerOptions, A as AuthyonClient, E as SessionSnapshot, S as Session, f as AbilitySubject, n as AuthyonAbilityOptions, l as AuthyonAbility } from '../ability-g6nBpOQM.js';
+export { q as AuthyonSessionController, G as SessionSnapshotListener, J as SessionStatus } from '../ability-g6nBpOQM.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-EHZEUM47.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.4",
   "description": "Authyon SDK for browsers — auth, sessions, multi-tenant and 2FA for vanilla JS/TS.",
   "license": "MIT",
   "type": "module",