@authyon/auth 0.1.3 → 0.1.5

package/dist/index.cjs

@@ -98,6 +98,22 @@ function defaultStorage() {
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.authyon.com";
 var EXPIRY_SKEW_MS = 3e4;
+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",
+      title: "Malformed session response",
+      detail: "The session response carried no access/refresh token pair."
+    });
+  }
+  return {
+    accessToken: tokens.accessToken,
+    refreshToken: tokens.refreshToken,
+    expiresIn: tokens.expiresIn ?? FALLBACK_EXPIRES_IN
+  };
+}
 var AuthyonClient = class {
   constructor(options) {
     this.listeners = /* @__PURE__ */ new Set();
@@ -113,7 +129,7 @@ var AuthyonClient = class {
       loginFinish: (assertion) => this.request("/auth/webauthn/login/finish", {
         method: "POST",
         body: assertion
-      }).then((data) => this.setSession(data, "signed_in"))
+      }).then((data) => this.setSession({ tokens: readTokens(data) }, "signed_in")).then((session) => this.hydrateUser(session))
     };
     // ── Social sign-in (SSO) ─────────────────────────────────────────────────
     this.sso = {
@@ -134,9 +150,7 @@ var AuthyonClient = class {
        * POST /auth/sso/exchange — swaps the one-time code from the provider
        * callback for tokens and stores the session.
        */
-      exchange: (code) => this.request("/auth/sso/exchange", { method: "POST", body: { code } }).then(
-        (data) => this.setSession(data, "signed_in")
-      )
+      exchange: (code) => this.request("/auth/sso/exchange", { method: "POST", body: { code } }).then((data) => this.setSession({ tokens: readTokens(data) }, "signed_in")).then((session) => this.hydrateUser(session))
     };
     // ── User ─────────────────────────────────────────────────────────────────
     this.user = {
@@ -144,7 +158,7 @@ var AuthyonClient = class {
       me: () => this.request("/auth/me", { bearer: true }).then(normalizeUser),
       /** GET /auth/sessions — active refresh-token sessions with device/IP data. */
       sessions: () => this.request("/auth/sessions", { bearer: true }),
-      /** GET /auth/me/activities — recent account activity for the current user. */
+      /** GET /auth/me/activities — paginated recent account activity for the current user. */
       activities: (params = {}) => this.request(`/auth/me/activities?${toQuery(params)}`, { bearer: true }),
       /**
        * Revokes a single session by id (e.g. one entry from `sessions()`),
@@ -194,11 +208,16 @@ var AuthyonClient = class {
         method: "POST",
         bearer: true,
         body: { tenantSlug: organizationSlug }
-      }).then((data) => this.setSession(data, "refreshed")),
+      }).then((data) => this.setSession({ tokens: readTokens(data) }, "refreshed")).then((session) => this.hydrateUser(session)),
       /** The organization the current session is scoped to, from the cached session — no network call. */
       current: () => this.getSession()?.user?.activeOrganization ?? null,
       members: {
-        /** GET /auth/tenants/{organizationId}/members — list an organization's members. */
+        /**
+         * 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
+         * (`user.activities()`, `@authyon/server`'s `environment.users.list()`).
+         */
         list: (organizationId, params = {}) => this.request(
           `/auth/tenants/${encodeURIComponent(organizationId)}/members?${toQuery(params)}`,
           { bearer: true }
@@ -332,9 +351,9 @@ var AuthyonClient = class {
   }
   setSession(raw, event) {
     const session = {
-      ...raw,
+      ...raw.tokens,
       user: raw.user ? normalizeUser(raw.user) : void 0,
-      expiresAt: Date.now() + raw.expiresIn * 1e3
+      expiresAt: Date.now() + raw.tokens.expiresIn * 1e3
     };
     this.storage.set(session);
     this.emit(event === "signed_out" ? { type: "signed_out" } : { type: event, session });
@@ -344,6 +363,23 @@ var AuthyonClient = class {
     this.storage.clear();
     this.emit({ type: "signed_out" });
   }
+  /**
+   * `/auth/login` and the other endpoints that mint a session don't return
+   * a `user` object on the wire — only `tokens` (plus `twoFactor`, when a
+   * challenge is required). Fetch the profile right after so callers get a
+   * fully-populated `session.user` without an extra manual round trip.
+   * Best-effort: keeps the session usable even if this fetch fails.
+   */
+  async hydrateUser(session) {
+    try {
+      const user = await this.user.me();
+      const hydrated = { ...session, user };
+      this.storage.set(hydrated);
+      return hydrated;
+    } catch {
+      return session;
+    }
+  }
   // ── HTTP core ────────────────────────────────────────────────────────────
   async request(path, options = {}, isRetry = false) {
     const headers = {
@@ -395,20 +431,22 @@ var AuthyonClient = class {
   async login(params) {
     const { organizationSlug, ...rest } = params;
     const body = organizationSlug ? { ...rest, tenantSlug: organizationSlug } : rest;
-    const data = await this.request("/auth/login", {
-      method: "POST",
-      body
-    });
-    if (data.twoFactorRequired) {
-      return data;
+    const data = await this.request("/auth/login", { method: "POST", body });
+    if (data.twoFactor) {
+      return { twoFactorRequired: true, ...data.twoFactor };
     }
-    const session = this.setSession(data, "signed_in");
+    const session = await this.hydrateUser(
+      this.setSession({ tokens: readTokens(data) }, "signed_in")
+    );
     return { twoFactorRequired: false, session };
   }
   /** POST /auth/2fa/verify — redeems a 2FA challenge from `login()` and stores the session. */
   async verifyTwoFactor(params) {
-    const data = await this.request("/auth/2fa/verify", { method: "POST", body: params });
-    return this.setSession(data, "signed_in");
+    const data = await this.request("/auth/2fa/verify", {
+      method: "POST",
+      body: params
+    });
+    return this.hydrateUser(this.setSession({ tokens: readTokens(data) }, "signed_in"));
   }
   /** POST /auth/refresh — rotates the single-use refresh token (single-flight). */
   async refresh() {
@@ -420,7 +458,10 @@ var AuthyonClient = class {
       method: "POST",
       body: { refreshToken: current.refreshToken }
     }).then(
-      (data) => this.setSession({ user: current.user, ...data }, "refreshed")
+      (data) => this.setSession(
+        { tokens: readTokens(data), user: current.user },
+        "refreshed"
+      )
     ).catch((error) => {
       if (error instanceof AuthyonError && (error.status === 401 || error.status === 403)) {
         this.clearSession();
@@ -453,30 +494,41 @@ var AuthyonClient = class {
     this.clearSession();
   }
   // ── Token verification ───────────────────────────────────────────────────
-  /** POST /auth/introspect — lightweight token introspection. */
+  /**
+   * POST /auth/introspect — lightweight token introspection (RFC 7662).
+   *
+   * ⚠️ Confirmed live: this endpoint requires the CALLER to also
+   * authenticate, with an environment or tenant client-credentials bearer
+   * token — the end user's own access token doesn't satisfy that (401).
+   * 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.
+   */
   async introspect(token) {
     const accessToken = token ?? await this.getAccessToken();
     return this.request("/auth/introspect", { method: "POST", body: { token: accessToken } });
   }
-  /** POST /auth/validate — recommended: cross-checks DB state, returns user + organization. */
+  /**
+   * 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()`.
+   */
   async validate(token) {
     const accessToken = token ?? await this.getAccessToken();
-    const raw = await this.request("/auth/validate", {
-      method: "POST",
-      headers: accessToken ? { Authorization: `Bearer ${accessToken}` } : void 0
-    });
+    const raw = await this.request("/auth/validate", { method: "POST", body: { token: accessToken } });
     return {
-      user: normalizeUser(raw.user),
-      organization: raw.organization ?? raw.tenant ?? null
+      valid: raw.valid,
+      reason: raw.reason ?? null,
+      user: raw.profile ? normalizeUser(raw.profile) : null
     };
   }
 };
 function normalizeUser(raw) {
-  const { tenants, activeTenant, ...rest } = raw;
+  const { tenant, tenants, activeTenant, ...rest } = raw;
   return {
     ...rest,
     organizations: raw.organizations ?? tenants,
-    activeOrganization: raw.activeOrganization ?? activeTenant ?? null
+    activeOrganization: tenant ?? raw.activeOrganization ?? activeTenant ?? null
   };
 }
 function createClient(options) {

package/dist/index.d.cts

@@ -15,10 +15,14 @@ interface CreateOrganizationParams {
     slug?: string;
     description?: string;
 }
+/** GET /auth/tenants/{organizationId}/members — confirmed against the live API. */
 interface OrganizationMember {
     userId: string;
     email?: string;
+    username?: string;
     roles?: string[];
+    createdAt?: string;
+    lastLoginAt?: string | null;
 }
 /** POST /auth/tenants/{tenantId}/members — invites a member by e-mail. */
 interface InviteMemberParams {
@@ -35,9 +39,17 @@ interface User {
     id: string;
     email: string;
     username?: string;
+    emailConfirmed?: boolean;
+    firstName?: string | null;
+    lastName?: string | null;
+    roles?: string[];
+    permissions?: string[];
+    createdAt?: string;
+    lastLoginAt?: string;
     organizations?: Organization[];
     activeOrganization?: Organization | null;
-    permissions?: string[];
+    /** Actions the user must complete before continuing (e.g. confirm e-mail). */
+    pendencies?: string[];
 }
 /** Token pair issued by login / refresh / tenant switch. */
 interface Session {
@@ -89,9 +101,18 @@ interface TwoFactorVerifyParams {
     /** Required when `method` is `"webauthn"`. */
     webAuthnAssertion?: WebAuthnAssertion;
 }
+/** GET /auth/2fa/status — per-method enrolment flags, confirmed against the live API. */
 interface TwoFactorStatus {
-    methods: TwoFactorMethod[];
-    recoveryCodesRemaining?: number;
+    authenticatorEnabled: boolean;
+    authenticatorConfirmedAt?: string | null;
+    emailEnabled: boolean;
+    emailEnabledAt?: string | null;
+    /** Partially redacted (e.g. `"n**********@h***.com"`). */
+    emailHint?: string | null;
+    webAuthnEnabled: boolean;
+    webAuthnCredentialCount: number;
+    webAuthnCredentials: WebAuthnCredential[];
+    remainingRecoveryCodes: number;
 }
 interface AuthenticatorSetup {
     secret: string;
@@ -123,12 +144,27 @@ interface SsoProvider {
     /** URL to redirect the browser to in order to start this provider's flow. */
     startUrl: string;
 }
+/** GET /auth/me/activities — one audit-trail entry, confirmed against the live API. */
 interface Activity {
     id: string;
-    type: string;
-    createdAt: string;
+    eventType: string;
+    occurredAt: string;
+    environmentId?: string;
     ip?: string;
-    device?: string;
+    userAgent?: string;
+    /** JSON-encoded string — `JSON.parse` it for the event-specific payload. */
+    payloadJson?: string;
+}
+/** Paginated list envelope returned by `user.activities()`. */
+interface Page<T> {
+    data: T[];
+    /** Item count actually returned for this page. */
+    perPage?: number;
+    pageSize: number;
+    total: number;
+    pages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
 }
 /** A role available within an organization (tenant). */
 interface Role {
@@ -137,25 +173,44 @@ interface Role {
     description?: string;
     permissions?: string[];
 }
+/** GET /auth/sessions — confirmed against the live API. */
 interface SessionInfo {
     id: string;
-    createdAt?: string;
-    lastUsedAt?: string;
-    ip?: string;
-    device?: string;
-    current?: boolean;
+    createdAt: string;
+    expiresAt: string;
+    revokedAt?: string | null;
+    createdFromIp?: string;
+    isActive: boolean;
+    userAgent?: string;
+    lastUsedAt?: string | null;
+    lastUsedFromIp?: string | null;
 }
+/** POST /auth/introspect (RFC 7662) — confirmed against the live API. */
 interface IntrospectResult {
     active: boolean;
     sub?: string;
+    username?: string | null;
+    email?: string | null;
+    roles?: string[] | null;
+    permissions?: string[];
     client_id?: string;
     scope?: string;
     exp?: number;
+    iat?: number;
+    jti?: string;
     token_type?: string;
 }
+/**
+ * POST /auth/validate — confirmed against the live API. The wire shape is
+ * `{ valid, reason, profile }`, not `{ user, organization }` as the
+ * OpenAPI schema (which didn't document response bodies) suggested.
+ * `profile` is `null` for machine tokens (there's no user behind them) and
+ * for tokens that fail validation.
+ */
 interface ValidateResult {
-    user: User;
-    organization?: Organization | null;
+    valid: boolean;
+    reason?: string | null;
+    user: User | null;
 }
 type AuthEvent = {
     type: "signed_in";
@@ -211,6 +266,14 @@ declare class AuthyonClient {
     private emit;
     private setSession;
     private clearSession;
+    /**
+     * `/auth/login` and the other endpoints that mint a session don't return
+     * a `user` object on the wire — only `tokens` (plus `twoFactor`, when a
+     * challenge is required). Fetch the profile right after so callers get a
+     * fully-populated `session.user` without an extra manual round trip.
+     * Best-effort: keeps the session usable even if this fetch fails.
+     */
+    private hydrateUser;
     private request;
     private toError;
     /** POST /auth/register — creates a new user (rate-limited to 20/hour per IP). */
@@ -266,8 +329,8 @@ declare class AuthyonClient {
         me: () => Promise<User>;
         /** GET /auth/sessions — active refresh-token sessions with device/IP data. */
         sessions: () => Promise<SessionInfo[]>;
-        /** GET /auth/me/activities — recent account activity for the current user. */
-        activities: (params?: PageParams) => Promise<Activity[]>;
+        /** GET /auth/me/activities — paginated recent account activity for the current user. */
+        activities: (params?: PageParams) => Promise<Page<Activity>>;
         /**
          * Revokes a single session by id (e.g. one entry from `sessions()`),
          * signing that device out without affecting the current one.
@@ -305,8 +368,13 @@ declare class AuthyonClient {
         /** The organization the current session is scoped to, from the cached session — no network call. */
         current: () => Organization | null;
         members: {
-            /** GET /auth/tenants/{organizationId}/members — list an organization's members. */
-            list: (organizationId: string, params?: PageParams) => Promise<OrganizationMember[]>;
+            /**
+             * 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
+             * (`user.activities()`, `@authyon/server`'s `environment.users.list()`).
+             */
+            list: (organizationId: string, params?: PageParams) => Promise<Page<OrganizationMember>>;
             /** POST /auth/tenants/{organizationId}/members — invite a member by e-mail. */
             invite: (organizationId: string, params: InviteMemberParams) => Promise<void>;
             /** DELETE /auth/tenants/{organizationId}/members/{userId} — remove a member. */
@@ -361,9 +429,22 @@ declare class AuthyonClient {
             assertionStart: (challengeToken: string) => Promise<WebAuthnCeremonyStart>;
         };
     };
-    /** POST /auth/introspect — lightweight token introspection. */
+    /**
+     * POST /auth/introspect — lightweight token introspection (RFC 7662).
+     *
+     * ⚠️ Confirmed live: this endpoint requires the CALLER to also
+     * authenticate, with an environment or tenant client-credentials bearer
+     * token — the end user's own access token doesn't satisfy that (401).
+     * 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.
+     */
     introspect(token?: string): Promise<IntrospectResult>;
-    /** POST /auth/validate — recommended: cross-checks DB state, returns user + organization. */
+    /**
+     * 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()`.
+     */
     validate(token?: string): Promise<ValidateResult>;
 }
 /** Convenience factory: `const authyon = createClient({ envKey: "pk_live_..." })`. */
@@ -400,4 +481,4 @@ declare function memoryStorage(): TokenStorage;
 declare function localStorageAdapter(key?: string): TokenStorage;
 declare function defaultStorage(): TokenStorage;
 
-export { type Activity, type AuthEvent, type AuthStateListener, type AuthenticatorSetup, AuthyonClient, type AuthyonClientOptions, AuthyonError, type CreateOrganizationParams, ErrorCodes, type IntrospectResult, type InviteMemberParams, type LoginParams, type LoginResult, type Organization, type OrganizationMember, type PageParams, type RegisterParams, type Role, type Session, type SessionInfo, type SsoProvider, type TokenStorage, type TwoFactorChallenge, type TwoFactorMethod, type TwoFactorStatus, type TwoFactorVerifyParams, type User, type ValidateResult, type WebAuthnAssertion, type WebAuthnCeremonyStart, type WebAuthnCredential, createClient, defaultStorage, localStorageAdapter, memoryStorage };
+export { type Activity, type AuthEvent, type AuthStateListener, type AuthenticatorSetup, AuthyonClient, type AuthyonClientOptions, AuthyonError, type CreateOrganizationParams, ErrorCodes, type IntrospectResult, type InviteMemberParams, type LoginParams, type LoginResult, type Organization, type OrganizationMember, type Page, type PageParams, type RegisterParams, type Role, type Session, type SessionInfo, type SsoProvider, type TokenStorage, type TwoFactorChallenge, type TwoFactorMethod, type TwoFactorStatus, type TwoFactorVerifyParams, type User, type ValidateResult, type WebAuthnAssertion, type WebAuthnCeremonyStart, type WebAuthnCredential, createClient, defaultStorage, localStorageAdapter, memoryStorage };

package/dist/index.d.ts

@@ -15,10 +15,14 @@ interface CreateOrganizationParams {
     slug?: string;
     description?: string;
 }
+/** GET /auth/tenants/{organizationId}/members — confirmed against the live API. */
 interface OrganizationMember {
     userId: string;
     email?: string;
+    username?: string;
     roles?: string[];
+    createdAt?: string;
+    lastLoginAt?: string | null;
 }
 /** POST /auth/tenants/{tenantId}/members — invites a member by e-mail. */
 interface InviteMemberParams {
@@ -35,9 +39,17 @@ interface User {
     id: string;
     email: string;
     username?: string;
+    emailConfirmed?: boolean;
+    firstName?: string | null;
+    lastName?: string | null;
+    roles?: string[];
+    permissions?: string[];
+    createdAt?: string;
+    lastLoginAt?: string;
     organizations?: Organization[];
     activeOrganization?: Organization | null;
-    permissions?: string[];
+    /** Actions the user must complete before continuing (e.g. confirm e-mail). */
+    pendencies?: string[];
 }
 /** Token pair issued by login / refresh / tenant switch. */
 interface Session {
@@ -89,9 +101,18 @@ interface TwoFactorVerifyParams {
     /** Required when `method` is `"webauthn"`. */
     webAuthnAssertion?: WebAuthnAssertion;
 }
+/** GET /auth/2fa/status — per-method enrolment flags, confirmed against the live API. */
 interface TwoFactorStatus {
-    methods: TwoFactorMethod[];
-    recoveryCodesRemaining?: number;
+    authenticatorEnabled: boolean;
+    authenticatorConfirmedAt?: string | null;
+    emailEnabled: boolean;
+    emailEnabledAt?: string | null;
+    /** Partially redacted (e.g. `"n**********@h***.com"`). */
+    emailHint?: string | null;
+    webAuthnEnabled: boolean;
+    webAuthnCredentialCount: number;
+    webAuthnCredentials: WebAuthnCredential[];
+    remainingRecoveryCodes: number;
 }
 interface AuthenticatorSetup {
     secret: string;
@@ -123,12 +144,27 @@ interface SsoProvider {
     /** URL to redirect the browser to in order to start this provider's flow. */
     startUrl: string;
 }
+/** GET /auth/me/activities — one audit-trail entry, confirmed against the live API. */
 interface Activity {
     id: string;
-    type: string;
-    createdAt: string;
+    eventType: string;
+    occurredAt: string;
+    environmentId?: string;
     ip?: string;
-    device?: string;
+    userAgent?: string;
+    /** JSON-encoded string — `JSON.parse` it for the event-specific payload. */
+    payloadJson?: string;
+}
+/** Paginated list envelope returned by `user.activities()`. */
+interface Page<T> {
+    data: T[];
+    /** Item count actually returned for this page. */
+    perPage?: number;
+    pageSize: number;
+    total: number;
+    pages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
 }
 /** A role available within an organization (tenant). */
 interface Role {
@@ -137,25 +173,44 @@ interface Role {
     description?: string;
     permissions?: string[];
 }
+/** GET /auth/sessions — confirmed against the live API. */
 interface SessionInfo {
     id: string;
-    createdAt?: string;
-    lastUsedAt?: string;
-    ip?: string;
-    device?: string;
-    current?: boolean;
+    createdAt: string;
+    expiresAt: string;
+    revokedAt?: string | null;
+    createdFromIp?: string;
+    isActive: boolean;
+    userAgent?: string;
+    lastUsedAt?: string | null;
+    lastUsedFromIp?: string | null;
 }
+/** POST /auth/introspect (RFC 7662) — confirmed against the live API. */
 interface IntrospectResult {
     active: boolean;
     sub?: string;
+    username?: string | null;
+    email?: string | null;
+    roles?: string[] | null;
+    permissions?: string[];
     client_id?: string;
     scope?: string;
     exp?: number;
+    iat?: number;
+    jti?: string;
     token_type?: string;
 }
+/**
+ * POST /auth/validate — confirmed against the live API. The wire shape is
+ * `{ valid, reason, profile }`, not `{ user, organization }` as the
+ * OpenAPI schema (which didn't document response bodies) suggested.
+ * `profile` is `null` for machine tokens (there's no user behind them) and
+ * for tokens that fail validation.
+ */
 interface ValidateResult {
-    user: User;
-    organization?: Organization | null;
+    valid: boolean;
+    reason?: string | null;
+    user: User | null;
 }
 type AuthEvent = {
     type: "signed_in";
@@ -211,6 +266,14 @@ declare class AuthyonClient {
     private emit;
     private setSession;
     private clearSession;
+    /**
+     * `/auth/login` and the other endpoints that mint a session don't return
+     * a `user` object on the wire — only `tokens` (plus `twoFactor`, when a
+     * challenge is required). Fetch the profile right after so callers get a
+     * fully-populated `session.user` without an extra manual round trip.
+     * Best-effort: keeps the session usable even if this fetch fails.
+     */
+    private hydrateUser;
     private request;
     private toError;
     /** POST /auth/register — creates a new user (rate-limited to 20/hour per IP). */
@@ -266,8 +329,8 @@ declare class AuthyonClient {
         me: () => Promise<User>;
         /** GET /auth/sessions — active refresh-token sessions with device/IP data. */
         sessions: () => Promise<SessionInfo[]>;
-        /** GET /auth/me/activities — recent account activity for the current user. */
-        activities: (params?: PageParams) => Promise<Activity[]>;
+        /** GET /auth/me/activities — paginated recent account activity for the current user. */
+        activities: (params?: PageParams) => Promise<Page<Activity>>;
         /**
          * Revokes a single session by id (e.g. one entry from `sessions()`),
          * signing that device out without affecting the current one.
@@ -305,8 +368,13 @@ declare class AuthyonClient {
         /** The organization the current session is scoped to, from the cached session — no network call. */
         current: () => Organization | null;
         members: {
-            /** GET /auth/tenants/{organizationId}/members — list an organization's members. */
-            list: (organizationId: string, params?: PageParams) => Promise<OrganizationMember[]>;
+            /**
+             * 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
+             * (`user.activities()`, `@authyon/server`'s `environment.users.list()`).
+             */
+            list: (organizationId: string, params?: PageParams) => Promise<Page<OrganizationMember>>;
             /** POST /auth/tenants/{organizationId}/members — invite a member by e-mail. */
             invite: (organizationId: string, params: InviteMemberParams) => Promise<void>;
             /** DELETE /auth/tenants/{organizationId}/members/{userId} — remove a member. */
@@ -361,9 +429,22 @@ declare class AuthyonClient {
             assertionStart: (challengeToken: string) => Promise<WebAuthnCeremonyStart>;
         };
     };
-    /** POST /auth/introspect — lightweight token introspection. */
+    /**
+     * POST /auth/introspect — lightweight token introspection (RFC 7662).
+     *
+     * ⚠️ Confirmed live: this endpoint requires the CALLER to also
+     * authenticate, with an environment or tenant client-credentials bearer
+     * token — the end user's own access token doesn't satisfy that (401).
+     * 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.
+     */
     introspect(token?: string): Promise<IntrospectResult>;
-    /** POST /auth/validate — recommended: cross-checks DB state, returns user + organization. */
+    /**
+     * 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()`.
+     */
     validate(token?: string): Promise<ValidateResult>;
 }
 /** Convenience factory: `const authyon = createClient({ envKey: "pk_live_..." })`. */
@@ -400,4 +481,4 @@ declare function memoryStorage(): TokenStorage;
 declare function localStorageAdapter(key?: string): TokenStorage;
 declare function defaultStorage(): TokenStorage;
 
-export { type Activity, type AuthEvent, type AuthStateListener, type AuthenticatorSetup, AuthyonClient, type AuthyonClientOptions, AuthyonError, type CreateOrganizationParams, ErrorCodes, type IntrospectResult, type InviteMemberParams, type LoginParams, type LoginResult, type Organization, type OrganizationMember, type PageParams, type RegisterParams, type Role, type Session, type SessionInfo, type SsoProvider, type TokenStorage, type TwoFactorChallenge, type TwoFactorMethod, type TwoFactorStatus, type TwoFactorVerifyParams, type User, type ValidateResult, type WebAuthnAssertion, type WebAuthnCeremonyStart, type WebAuthnCredential, createClient, defaultStorage, localStorageAdapter, memoryStorage };
+export { type Activity, type AuthEvent, type AuthStateListener, type AuthenticatorSetup, AuthyonClient, type AuthyonClientOptions, AuthyonError, type CreateOrganizationParams, ErrorCodes, type IntrospectResult, type InviteMemberParams, type LoginParams, type LoginResult, type Organization, type OrganizationMember, type Page, type PageParams, type RegisterParams, type Role, type Session, type SessionInfo, type SsoProvider, type TokenStorage, type TwoFactorChallenge, type TwoFactorMethod, type TwoFactorStatus, type TwoFactorVerifyParams, type User, type ValidateResult, type WebAuthnAssertion, type WebAuthnCeremonyStart, type WebAuthnCredential, createClient, defaultStorage, localStorageAdapter, memoryStorage };

package/dist/index.js

@@ -66,6 +66,22 @@ function defaultStorage() {
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.authyon.com";
 var EXPIRY_SKEW_MS = 3e4;
+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",
+      title: "Malformed session response",
+      detail: "The session response carried no access/refresh token pair."
+    });
+  }
+  return {
+    accessToken: tokens.accessToken,
+    refreshToken: tokens.refreshToken,
+    expiresIn: tokens.expiresIn ?? FALLBACK_EXPIRES_IN
+  };
+}
 var AuthyonClient = class {
   constructor(options) {
     this.listeners = /* @__PURE__ */ new Set();
@@ -81,7 +97,7 @@ var AuthyonClient = class {
       loginFinish: (assertion) => this.request("/auth/webauthn/login/finish", {
         method: "POST",
         body: assertion
-      }).then((data) => this.setSession(data, "signed_in"))
+      }).then((data) => this.setSession({ tokens: readTokens(data) }, "signed_in")).then((session) => this.hydrateUser(session))
     };
     // ── Social sign-in (SSO) ─────────────────────────────────────────────────
     this.sso = {
@@ -102,9 +118,7 @@ var AuthyonClient = class {
        * POST /auth/sso/exchange — swaps the one-time code from the provider
        * callback for tokens and stores the session.
        */
-      exchange: (code) => this.request("/auth/sso/exchange", { method: "POST", body: { code } }).then(
-        (data) => this.setSession(data, "signed_in")
-      )
+      exchange: (code) => this.request("/auth/sso/exchange", { method: "POST", body: { code } }).then((data) => this.setSession({ tokens: readTokens(data) }, "signed_in")).then((session) => this.hydrateUser(session))
     };
     // ── User ─────────────────────────────────────────────────────────────────
     this.user = {
@@ -112,7 +126,7 @@ var AuthyonClient = class {
       me: () => this.request("/auth/me", { bearer: true }).then(normalizeUser),
       /** GET /auth/sessions — active refresh-token sessions with device/IP data. */
       sessions: () => this.request("/auth/sessions", { bearer: true }),
-      /** GET /auth/me/activities — recent account activity for the current user. */
+      /** GET /auth/me/activities — paginated recent account activity for the current user. */
       activities: (params = {}) => this.request(`/auth/me/activities?${toQuery(params)}`, { bearer: true }),
       /**
        * Revokes a single session by id (e.g. one entry from `sessions()`),
@@ -162,11 +176,16 @@ var AuthyonClient = class {
         method: "POST",
         bearer: true,
         body: { tenantSlug: organizationSlug }
-      }).then((data) => this.setSession(data, "refreshed")),
+      }).then((data) => this.setSession({ tokens: readTokens(data) }, "refreshed")).then((session) => this.hydrateUser(session)),
       /** The organization the current session is scoped to, from the cached session — no network call. */
       current: () => this.getSession()?.user?.activeOrganization ?? null,
       members: {
-        /** GET /auth/tenants/{organizationId}/members — list an organization's members. */
+        /**
+         * 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
+         * (`user.activities()`, `@authyon/server`'s `environment.users.list()`).
+         */
         list: (organizationId, params = {}) => this.request(
           `/auth/tenants/${encodeURIComponent(organizationId)}/members?${toQuery(params)}`,
           { bearer: true }
@@ -300,9 +319,9 @@ var AuthyonClient = class {
   }
   setSession(raw, event) {
     const session = {
-      ...raw,
+      ...raw.tokens,
       user: raw.user ? normalizeUser(raw.user) : void 0,
-      expiresAt: Date.now() + raw.expiresIn * 1e3
+      expiresAt: Date.now() + raw.tokens.expiresIn * 1e3
     };
     this.storage.set(session);
     this.emit(event === "signed_out" ? { type: "signed_out" } : { type: event, session });
@@ -312,6 +331,23 @@ var AuthyonClient = class {
     this.storage.clear();
     this.emit({ type: "signed_out" });
   }
+  /**
+   * `/auth/login` and the other endpoints that mint a session don't return
+   * a `user` object on the wire — only `tokens` (plus `twoFactor`, when a
+   * challenge is required). Fetch the profile right after so callers get a
+   * fully-populated `session.user` without an extra manual round trip.
+   * Best-effort: keeps the session usable even if this fetch fails.
+   */
+  async hydrateUser(session) {
+    try {
+      const user = await this.user.me();
+      const hydrated = { ...session, user };
+      this.storage.set(hydrated);
+      return hydrated;
+    } catch {
+      return session;
+    }
+  }
   // ── HTTP core ────────────────────────────────────────────────────────────
   async request(path, options = {}, isRetry = false) {
     const headers = {
@@ -363,20 +399,22 @@ var AuthyonClient = class {
   async login(params) {
     const { organizationSlug, ...rest } = params;
     const body = organizationSlug ? { ...rest, tenantSlug: organizationSlug } : rest;
-    const data = await this.request("/auth/login", {
-      method: "POST",
-      body
-    });
-    if (data.twoFactorRequired) {
-      return data;
+    const data = await this.request("/auth/login", { method: "POST", body });
+    if (data.twoFactor) {
+      return { twoFactorRequired: true, ...data.twoFactor };
     }
-    const session = this.setSession(data, "signed_in");
+    const session = await this.hydrateUser(
+      this.setSession({ tokens: readTokens(data) }, "signed_in")
+    );
     return { twoFactorRequired: false, session };
   }
   /** POST /auth/2fa/verify — redeems a 2FA challenge from `login()` and stores the session. */
   async verifyTwoFactor(params) {
-    const data = await this.request("/auth/2fa/verify", { method: "POST", body: params });
-    return this.setSession(data, "signed_in");
+    const data = await this.request("/auth/2fa/verify", {
+      method: "POST",
+      body: params
+    });
+    return this.hydrateUser(this.setSession({ tokens: readTokens(data) }, "signed_in"));
   }
   /** POST /auth/refresh — rotates the single-use refresh token (single-flight). */
   async refresh() {
@@ -388,7 +426,10 @@ var AuthyonClient = class {
       method: "POST",
       body: { refreshToken: current.refreshToken }
     }).then(
-      (data) => this.setSession({ user: current.user, ...data }, "refreshed")
+      (data) => this.setSession(
+        { tokens: readTokens(data), user: current.user },
+        "refreshed"
+      )
     ).catch((error) => {
       if (error instanceof AuthyonError && (error.status === 401 || error.status === 403)) {
         this.clearSession();
@@ -421,30 +462,41 @@ var AuthyonClient = class {
     this.clearSession();
   }
   // ── Token verification ───────────────────────────────────────────────────
-  /** POST /auth/introspect — lightweight token introspection. */
+  /**
+   * POST /auth/introspect — lightweight token introspection (RFC 7662).
+   *
+   * ⚠️ Confirmed live: this endpoint requires the CALLER to also
+   * authenticate, with an environment or tenant client-credentials bearer
+   * token — the end user's own access token doesn't satisfy that (401).
+   * 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.
+   */
   async introspect(token) {
     const accessToken = token ?? await this.getAccessToken();
     return this.request("/auth/introspect", { method: "POST", body: { token: accessToken } });
   }
-  /** POST /auth/validate — recommended: cross-checks DB state, returns user + organization. */
+  /**
+   * 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()`.
+   */
   async validate(token) {
     const accessToken = token ?? await this.getAccessToken();
-    const raw = await this.request("/auth/validate", {
-      method: "POST",
-      headers: accessToken ? { Authorization: `Bearer ${accessToken}` } : void 0
-    });
+    const raw = await this.request("/auth/validate", { method: "POST", body: { token: accessToken } });
     return {
-      user: normalizeUser(raw.user),
-      organization: raw.organization ?? raw.tenant ?? null
+      valid: raw.valid,
+      reason: raw.reason ?? null,
+      user: raw.profile ? normalizeUser(raw.profile) : null
     };
   }
 };
 function normalizeUser(raw) {
-  const { tenants, activeTenant, ...rest } = raw;
+  const { tenant, tenants, activeTenant, ...rest } = raw;
   return {
     ...rest,
     organizations: raw.organizations ?? tenants,
-    activeOrganization: raw.activeOrganization ?? activeTenant ?? null
+    activeOrganization: tenant ?? raw.activeOrganization ?? activeTenant ?? null
   };
 }
 function createClient(options) {

package/package.json

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