@authyon/server 0.2.0-beta.21 → 0.2.0-beta.22

package/dist/{authorization-Soblu-A5.d.cts → authorization-BLENxur8.d.cts}

@@ -1,4 +1,4 @@
-import { L as JwksTokenVerifier, A as AuthyonServerClient } from './authyonServerClient-COrfN4o_.cjs';
+import { J as JwksTokenVerifier, A as AuthyonServerClient } from './authyonServerClient-CW46xIRD.cjs';
 
 type AbilitySubject = string | Record<string, unknown>;
 type AbilityConditions = Record<string, unknown>;
@@ -54,11 +54,25 @@ 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. */
+/**
+ * Whether a source holds an Authyon permission, by Authyon's own rules: the
+ * values are compared segment by segment, `*` stands for any one segment, and
+ * two values of different lengths never match — except an all-wildcard grant,
+ * which is everything. OAuth scopes count as permissions.
+ *
+ * Not the same question as {@link AuthyonAbility.can}. An ability is CASL, so
+ * the action `manage` there means "every action on this subject", which is a
+ * useful thing to author by hand and a wrong thing to infer from a permission:
+ * `subtenants:tree:manage` and `subtenants:tree:switch` are deliberately
+ * separate grants on the API side — administering a sub-tenant from above and
+ * operating as it are different powers — and reading the first as the second
+ * would have this answer yes to a call the API then refuses. Ask this one
+ * about anything Authyon will be enforcing.
+ */
 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.
+ * Checks a permission group with {@link hasPermission}, so the same rules as
+ * the API. 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. */

package/dist/{authorization-D8tznR96.d.ts → authorization-Clf0Jx-U.d.ts}

@@ -1,4 +1,4 @@
-import { L as JwksTokenVerifier, A as AuthyonServerClient } from './authyonServerClient-COrfN4o_.js';
+import { J as JwksTokenVerifier, A as AuthyonServerClient } from './authyonServerClient-CW46xIRD.js';
 
 type AbilitySubject = string | Record<string, unknown>;
 type AbilityConditions = Record<string, unknown>;
@@ -54,11 +54,25 @@ 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. */
+/**
+ * Whether a source holds an Authyon permission, by Authyon's own rules: the
+ * values are compared segment by segment, `*` stands for any one segment, and
+ * two values of different lengths never match — except an all-wildcard grant,
+ * which is everything. OAuth scopes count as permissions.
+ *
+ * Not the same question as {@link AuthyonAbility.can}. An ability is CASL, so
+ * the action `manage` there means "every action on this subject", which is a
+ * useful thing to author by hand and a wrong thing to infer from a permission:
+ * `subtenants:tree:manage` and `subtenants:tree:switch` are deliberately
+ * separate grants on the API side — administering a sub-tenant from above and
+ * operating as it are different powers — and reading the first as the second
+ * would have this answer yes to a call the API then refuses. Ask this one
+ * about anything Authyon will be enforcing.
+ */
 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.
+ * Checks a permission group with {@link hasPermission}, so the same rules as
+ * the API. 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. */

package/dist/{authyonServerClient-COrfN4o_.d.cts → authyonServerClient-CW46xIRD.d.cts}

@@ -226,6 +226,35 @@ interface Organization {
     publicMetadata?: string;
     /** JSON-encoded metadata available only through administrative APIs. */
     privateMetadata?: string;
+    /**
+     * The tenant this one sits under, or `null` for a root tenant. With `depth`
+     * it is what lets a flat page be rendered as the tree it describes.
+     *
+     * Absent on an API older than 2026-10-31, where every tenant was a root.
+     */
+    parentTenantId?: string | null;
+    /** Distance from the root: `0` for a root tenant. */
+    depth?: number;
+    /**
+     * Direct sub-tenants. A tree view expands only where this is above zero,
+     * instead of fetching every node to find out it has no children.
+     */
+    childCount?: number;
+    /** Custom roles defined inside the tenant. Only `get()` returns it. */
+    roleCount?: number;
+    /**
+     * The chain above this tenant, root first, excluding itself — a breadcrumb
+     * without a request per level. Empty for a root tenant, and only `get()`
+     * returns it.
+     */
+    ancestors?: TenantAncestor[];
+}
+/** One step of the chain above a tenant, as `Organization.ancestors` carries it. */
+interface TenantAncestor {
+    id: string;
+    name: string;
+    slug: string;
+    isDisabled: boolean;
 }
 /**
  * What `environment.tenants.list()` accepts. `search` is the free-text half
@@ -236,6 +265,16 @@ interface Organization {
 interface TenantListOptions extends PaginationOptions {
     search?: string;
     filter?: TenantFilterExpression[];
+    /**
+     * Narrows the page to one level of the tree: a tenant id lists that tenant's
+     * direct sub-tenants, and `null` lists the roots. Omitted lists the
+     * environment's tenants regardless of depth — the behaviour from before the
+     * hierarchy existed, and still the right one for a flat picker.
+     *
+     * `search` and `filter` keep applying inside the level, so the envelope goes
+     * on describing what you asked for.
+     */
+    parentId?: string | null;
 }
 /** One of a user's tenant memberships, as embedded in `EnvironmentUser.tenantMemberships`. */
 interface TenantMembership {
@@ -383,6 +422,17 @@ interface CreateOrganizationInput {
     customFields?: Record<string, unknown>;
     publicMetadata?: Record<string, unknown>;
     privateMetadata?: Record<string, unknown>;
+    /**
+     * Creates the tenant underneath an existing one in the same environment.
+     * Omitted creates a root tenant.
+     *
+     * The environment's `maxTenantDepth` has to allow the level — it is `1` by
+     * default, which means roots only and refuses this with
+     * `tenant.depth.not_allowed` until an operator raises it. The new node counts
+     * against the plan's tenant cap like any other, so nesting cannot be used to
+     * get around it.
+     */
+    parentTenantId?: string;
 }
 interface UpdateOrganizationInput {
     name: string;
@@ -418,6 +468,12 @@ interface AuditEvent {
     environmentId?: string;
     actorUserId?: string | null;
     actorType?: string;
+    /**
+     * The address the event is recorded against — the vouched one when a machine
+     * credential named it. Where that differs from the socket peer, the peer is
+     * kept inside `payloadJson` as `peerIp`: which backend made the call is its
+     * own question, and the answer is not the caller's to choose.
+     */
     actorIp?: string;
     userAgent?: string;
     tenantId?: string | null;
@@ -512,8 +568,17 @@ interface AuthyonServerClientOptions {
     clientId?: string;
     clientSecret?: string;
     /**
-     * Originating end-user IP to forward on every API call as `X-Forwarded-For`.
-     * Only set this from infrastructure you trust; the SDK rejects comma-separated
+     * The end user's address, forwarded on every API call as
+     * `X-Authyon-Client-Ip` (and `X-Forwarded-For`, for your own proxies).
+     *
+     * Worth setting: a call from your backend has no browser in it, so without
+     * this every audit row Authyon writes for your integration names the
+     * container gateway, which identifies nobody. The API believes the header
+     * from a machine credential and records the address beside the event, where
+     * the console's IP filter can find it. It only ever changes the trail — no
+     * IP-keyed gate reads a vouched address.
+     *
+     * Only set it from infrastructure you trust; the SDK rejects comma-separated
      * or whitespace-containing values to avoid forwarded-header injection.
      */
     clientIp?: string;
@@ -834,10 +899,58 @@ interface ClientRequestContext {
     /** Real end-user IP, resolved only from infrastructure trusted by the application. */
     clientIp?: string;
 }
+/**
+ * The header Authyon reads the real caller address from. `X-Forwarded-For` is
+ * not it: the API rewrites the socket peer from the edge proxy's chain and then
+ * resolves the client address from this header alone, so an address sent only
+ * in XFF is dropped before anything reads it.
+ */
+declare const CLIENT_IP_HEADER = "X-Authyon-Client-Ip";
 /** Rejects header injection and values that are not a single IPv4 or IPv6 address. */
 declare function normalizeClientIp(value: string): string;
 
 type SafeJwtAlgorithm = "RS256" | "PS256" | "ES256" | "EdDSA";
+/**
+ * The active tenant, as the `tenant` claim carries it. Present only on a
+ * session scoped to one — a token minted before any tenant switch has no
+ * tenant and no claim.
+ *
+ * Snake_case because these are wire names, not SDK ones: the claim is signed,
+ * and renaming its fields on the way in would hide what was actually asserted.
+ */
+interface AuthyonTenantClaim {
+    id: string;
+    slug: string;
+    name: string;
+    /** The tenant above this one, or `null` at a root. */
+    parent_id?: string | null;
+    /**
+     * The materialised chain from the root down to this tenant. Signed, so a
+     * consumer can answer "is that tenant under mine?" with a prefix comparison
+     * and no round trip — which is the whole reason it is in the token.
+     */
+    path?: string;
+    /** Distance from the root: `0` at a root tenant. */
+    depth?: number;
+    /**
+     * Version of `path`. A tenant that gets moved bumps it, which is what makes
+     * the signed path safe to trust: a token minted before the move no longer
+     * matches and the API refuses it with `tenant.path_stale`, instead of
+     * letting a stale prefix keep answering yes.
+     */
+    pv?: number;
+    roles?: string[];
+    /** Effective permissions AT this tenant. */
+    permissions?: string[];
+    /**
+     * Set only when the session descended into this tenant from an ancestor,
+     * naming the node the permissions came from — the user holds no membership
+     * here. Treat it as borrowed authority if that matters to you (a banner, a
+     * tighter trail, a refusal); ignore it and you have a session scoped to a
+     * tenant, which is what it is. Absent on any other session.
+     */
+    via?: string | null;
+}
 interface AuthyonJwtClaims extends JWTPayload {
     sub: string;
     iss: string;
@@ -849,6 +962,8 @@ interface AuthyonJwtClaims extends JWTPayload {
     roles?: string[];
     permissions?: string[];
     scope?: string;
+    /** The active tenant and the grants held inside it. Absent until a switch. */
+    tenant?: AuthyonTenantClaim;
 }
 interface VerifiedAccessToken {
     claims: AuthyonJwtClaims;
@@ -1048,23 +1163,66 @@ declare class AuthyonServerClient {
              * });
              * ```
              *
+             * `parentId` narrows the page to one level of the tree — `children()`
+             * and `roots()` below are the same call with that one option set.
+             *
              * Against an Authyon API older than 2026-10-21 this route ignored
              * skip/take/search and answered with a bare array; one older than
-             * 2026-10-22 ignores `filter`, which reads as a page that is too wide
-             * rather than an error.
+             * 2026-10-22 ignores `filter` and one older than 2026-10-31 ignores
+             * `parentId`, which read as a page that is too wide rather than an error.
              */
             list: (params?: TenantListOptions) => Promise<Paged<Organization>>;
-            /** POST /env/tenants — create a tenant in the environment. */
+            /**
+             * One page of a tenant's direct sub-tenants — `list()` with `parentId`.
+             *
+             * Only one level: a node's own children carry `childCount`, so a tree
+             * view asks again where that is above zero instead of reading the whole
+             * subtree to draw the first level of it.
+             */
+            children: (parentTenantId: string, params?: Omit<TenantListOptions, "parentId">) => Promise<Paged<Organization>>;
+            /**
+             * One page of the environment's root tenants — `list()` with no parent.
+             *
+             * This is the first level of the tree, and the difference from `list()`
+             * is worth keeping straight: `list()` returns every tenant at every
+             * depth, which is what a flat picker wants and what a tree view must not
+             * start from.
+             */
+            roots: (params?: Omit<TenantListOptions, "parentId">) => Promise<Paged<Organization>>;
+            /**
+             * POST /env/tenants — create a tenant in the environment.
+             *
+             * `parentTenantId` nests it under an existing tenant. The environment's
+             * `maxTenantDepth` has to allow the level — it ships as `1`, roots only,
+             * so this answers `tenant.depth.not_allowed` until an operator raises it
+             * in the console.
+             */
             create: (input: CreateOrganizationInput) => Promise<Organization>;
-            /** GET /env/tenants/{tenantId} — fetch a tenant by id. */
+            /**
+             * GET /env/tenants/{tenantId} — fetch a tenant by id.
+             *
+             * Returns `ancestors` as well, the chain above it root first, so a
+             * breadcrumb costs this one call rather than one per level.
+             */
             get: (tenantId: string) => Promise<Organization>;
             /** PUT /env/tenants/{tenantId} — update a tenant. */
             update: (tenantId: string, input: UpdateOrganizationInput) => Promise<Organization>;
             /** PUT /env/tenants/{tenantId}/metadata - replace public and private metadata. */
             updateMetadata: (tenantId: string, input: Pick<CreateOrganizationInput, "publicMetadata" | "privateMetadata">) => Promise<void>;
-            /** POST /env/tenants/{tenantId}/disable — disable without removing tenant data. */
+            /**
+             * POST /env/tenants/{tenantId}/disable — disable without removing tenant
+             * data.
+             *
+             * Disables the branch below it too. A sub-tenant left live under a
+             * disabled parent would go on authenticating its users, which is the one
+             * thing switching a tenant off is there to stop — so check `childCount`
+             * before calling this on a node with children.
+             */
             disable: (tenantId: string) => Promise<void>;
-            /** DELETE /env/tenants/{tenantId} — logically delete (disable) a tenant. */
+            /**
+             * DELETE /env/tenants/{tenantId} — logically delete (disable) a tenant,
+             * and the branch below it. Same handler as `disable()`.
+             */
             delete: (tenantId: string) => Promise<void>;
             members: {
                 /**
@@ -1293,4 +1451,4 @@ declare class TenantScopedClient {
 /** Convenience factory: `const authyon = createClient({ clientId, clientSecret })`. */
 declare function createClient(options?: AuthyonServerClientOptions): AuthyonServerClient;
 
-export { type RoleGrant as $, AuthyonServerClient as A, type HttpLogEvent as B, type ClientCredentials as C, type HttpLogger as D, type EnvironmentUser as E, FetchHttpAdapter as F, type InviteTenantMemberInput as G, type HttpAdapter as H, type IntrospectResult as I, type IssuePasswordResetInput as J, type JsonWebKeySet as K, JwksTokenVerifier as L, type JwksTokenVerifierOptions as M, LoggingHttpAdapter as N, type LoginActivity as O, type OpenIdConfiguration as P, type Organization as Q, type OtpCheckResult as R, type Paged as S, type PaginationOptions as T, type PasswordResetCompleted as U, type PasswordResetIssued as V, type PasswordResetPreview as W, type Permission as X, type PermissionsByRole as Y, type ReservedPermissions as Z, type Role as _, type HttpLoggerOptions as a, type RoleInput as a0, type RoleList as a1, type RolePermissions as a2, type SafeJwtAlgorithm as a3, type SecurityMethods as a4, type SubjectApprovals as a5, type SubjectSecurity as a6, TENANT_FILTER_MAX_DEPTH as a7, TENANT_FILTER_MAX_VALUES as a8, TENANT_FILTER_MAX_VALUE_LENGTH as a9, tenantFilter as aA, type TenantClientValidationResult as aa, type TenantCredentialIssued as ab, type TenantCredentialSummary as ac, type TenantFilterExpression as ad, type TenantFilterValue as ae, type TenantInvite as af, type TenantInviteAccepted as ag, type TenantInviteInput as ah, type TenantInviteIssued as ai, type TenantInvitePreview as aj, type TenantInviteStatus as ak, type TenantListOptions as al, type TenantMember as am, type TenantMemberPage as an, type TenantMembership as ao, TenantScopedClient as ap, type TokenResult as aq, TokenVerificationError as ar, type TokenVerificationErrorCode as as, type UpdateOrganizationInput as at, type User as au, UserScopedClient as av, type ValidateResult as aw, type VerifiedAccessToken as ax, createClient as ay, normalizeClientIp as az, type AcceptTenantInviteInput as b, type AccessTokenSource as c, type Approval as d, type ApprovalAssurance as e, type ApprovalPayload as f, type ApprovalStatus as g, type ApprovalWebAuthnOptions as h, type AuditEvent as i, type AuthyonJwksDiscoveryOptions as j, type AuthyonJwtClaims as k, type AuthyonServerClientOptions as l, type ClientRequestContext as m, type ConfirmApprovalInput as n, type ConsumedApproval as o, type CreateApprovalInput as p, type CreateCredentialInput as q, type CreateOrganizationInput as r, type CreatePermissionInput as s, type CreateTenantCredentialInput as t, type CreateUserInput as u, type CredentialCreator as v, type CredentialDetail as w, type CredentialListOptions as x, type CredentialPermissionsInput as y, type HttpAdapterRequest as z };
+export { type ReservedPermissions as $, AuthyonServerClient as A, type CredentialPermissionsInput as B, CLIENT_IP_HEADER as C, type HttpAdapterRequest as D, type EnvironmentUser as E, FetchHttpAdapter as F, type HttpLogEvent as G, type HttpAdapter as H, type HttpLogger as I, JwksTokenVerifier as J, type IntrospectResult as K, type InviteTenantMemberInput as L, type IssuePasswordResetInput as M, type JsonWebKeySet as N, type JwksTokenVerifierOptions as O, LoggingHttpAdapter as P, type LoginActivity as Q, type OpenIdConfiguration as R, type Organization as S, type OtpCheckResult as T, type Paged as U, type PaginationOptions as V, type PasswordResetCompleted as W, type PasswordResetIssued as X, type PasswordResetPreview as Y, type Permission as Z, type PermissionsByRole as _, type HttpLoggerOptions as a, type Role as a0, type RoleGrant as a1, type RoleInput as a2, type RoleList as a3, type RolePermissions as a4, type SafeJwtAlgorithm as a5, type SecurityMethods as a6, type SubjectApprovals as a7, type SubjectSecurity as a8, TENANT_FILTER_MAX_DEPTH as a9, type VerifiedAccessToken as aA, createClient as aB, normalizeClientIp as aC, tenantFilter as aD, TENANT_FILTER_MAX_VALUES as aa, TENANT_FILTER_MAX_VALUE_LENGTH as ab, type TenantAncestor as ac, type TenantClientValidationResult as ad, type TenantCredentialIssued as ae, type TenantCredentialSummary as af, type TenantFilterExpression as ag, type TenantFilterValue as ah, type TenantInvite as ai, type TenantInviteAccepted as aj, type TenantInviteInput as ak, type TenantInviteIssued as al, type TenantInvitePreview as am, type TenantInviteStatus as an, type TenantListOptions as ao, type TenantMember as ap, type TenantMemberPage as aq, type TenantMembership as ar, TenantScopedClient as as, type TokenResult as at, TokenVerificationError as au, type TokenVerificationErrorCode as av, type UpdateOrganizationInput as aw, type User as ax, UserScopedClient as ay, type ValidateResult as az, type AcceptTenantInviteInput as b, type AccessTokenSource as c, type Approval as d, type ApprovalAssurance as e, type ApprovalPayload as f, type ApprovalStatus as g, type ApprovalWebAuthnOptions as h, type AuditEvent as i, type AuthyonJwksDiscoveryOptions as j, type AuthyonJwtClaims as k, type AuthyonServerClientOptions as l, type AuthyonTenantClaim as m, type ClientCredentials as n, type ClientRequestContext as o, type ConfirmApprovalInput as p, type ConsumedApproval as q, type CreateApprovalInput as r, type CreateCredentialInput as s, type CreateOrganizationInput as t, type CreatePermissionInput as u, type CreateTenantCredentialInput as v, type CreateUserInput as w, type CredentialCreator as x, type CredentialDetail as y, type CredentialListOptions as z };

package/dist/{authyonServerClient-COrfN4o_.d.ts → authyonServerClient-CW46xIRD.d.ts}

@@ -226,6 +226,35 @@ interface Organization {
     publicMetadata?: string;
     /** JSON-encoded metadata available only through administrative APIs. */
     privateMetadata?: string;
+    /**
+     * The tenant this one sits under, or `null` for a root tenant. With `depth`
+     * it is what lets a flat page be rendered as the tree it describes.
+     *
+     * Absent on an API older than 2026-10-31, where every tenant was a root.
+     */
+    parentTenantId?: string | null;
+    /** Distance from the root: `0` for a root tenant. */
+    depth?: number;
+    /**
+     * Direct sub-tenants. A tree view expands only where this is above zero,
+     * instead of fetching every node to find out it has no children.
+     */
+    childCount?: number;
+    /** Custom roles defined inside the tenant. Only `get()` returns it. */
+    roleCount?: number;
+    /**
+     * The chain above this tenant, root first, excluding itself — a breadcrumb
+     * without a request per level. Empty for a root tenant, and only `get()`
+     * returns it.
+     */
+    ancestors?: TenantAncestor[];
+}
+/** One step of the chain above a tenant, as `Organization.ancestors` carries it. */
+interface TenantAncestor {
+    id: string;
+    name: string;
+    slug: string;
+    isDisabled: boolean;
 }
 /**
  * What `environment.tenants.list()` accepts. `search` is the free-text half
@@ -236,6 +265,16 @@ interface Organization {
 interface TenantListOptions extends PaginationOptions {
     search?: string;
     filter?: TenantFilterExpression[];
+    /**
+     * Narrows the page to one level of the tree: a tenant id lists that tenant's
+     * direct sub-tenants, and `null` lists the roots. Omitted lists the
+     * environment's tenants regardless of depth — the behaviour from before the
+     * hierarchy existed, and still the right one for a flat picker.
+     *
+     * `search` and `filter` keep applying inside the level, so the envelope goes
+     * on describing what you asked for.
+     */
+    parentId?: string | null;
 }
 /** One of a user's tenant memberships, as embedded in `EnvironmentUser.tenantMemberships`. */
 interface TenantMembership {
@@ -383,6 +422,17 @@ interface CreateOrganizationInput {
     customFields?: Record<string, unknown>;
     publicMetadata?: Record<string, unknown>;
     privateMetadata?: Record<string, unknown>;
+    /**
+     * Creates the tenant underneath an existing one in the same environment.
+     * Omitted creates a root tenant.
+     *
+     * The environment's `maxTenantDepth` has to allow the level — it is `1` by
+     * default, which means roots only and refuses this with
+     * `tenant.depth.not_allowed` until an operator raises it. The new node counts
+     * against the plan's tenant cap like any other, so nesting cannot be used to
+     * get around it.
+     */
+    parentTenantId?: string;
 }
 interface UpdateOrganizationInput {
     name: string;
@@ -418,6 +468,12 @@ interface AuditEvent {
     environmentId?: string;
     actorUserId?: string | null;
     actorType?: string;
+    /**
+     * The address the event is recorded against — the vouched one when a machine
+     * credential named it. Where that differs from the socket peer, the peer is
+     * kept inside `payloadJson` as `peerIp`: which backend made the call is its
+     * own question, and the answer is not the caller's to choose.
+     */
     actorIp?: string;
     userAgent?: string;
     tenantId?: string | null;
@@ -512,8 +568,17 @@ interface AuthyonServerClientOptions {
     clientId?: string;
     clientSecret?: string;
     /**
-     * Originating end-user IP to forward on every API call as `X-Forwarded-For`.
-     * Only set this from infrastructure you trust; the SDK rejects comma-separated
+     * The end user's address, forwarded on every API call as
+     * `X-Authyon-Client-Ip` (and `X-Forwarded-For`, for your own proxies).
+     *
+     * Worth setting: a call from your backend has no browser in it, so without
+     * this every audit row Authyon writes for your integration names the
+     * container gateway, which identifies nobody. The API believes the header
+     * from a machine credential and records the address beside the event, where
+     * the console's IP filter can find it. It only ever changes the trail — no
+     * IP-keyed gate reads a vouched address.
+     *
+     * Only set it from infrastructure you trust; the SDK rejects comma-separated
      * or whitespace-containing values to avoid forwarded-header injection.
      */
     clientIp?: string;
@@ -834,10 +899,58 @@ interface ClientRequestContext {
     /** Real end-user IP, resolved only from infrastructure trusted by the application. */
     clientIp?: string;
 }
+/**
+ * The header Authyon reads the real caller address from. `X-Forwarded-For` is
+ * not it: the API rewrites the socket peer from the edge proxy's chain and then
+ * resolves the client address from this header alone, so an address sent only
+ * in XFF is dropped before anything reads it.
+ */
+declare const CLIENT_IP_HEADER = "X-Authyon-Client-Ip";
 /** Rejects header injection and values that are not a single IPv4 or IPv6 address. */
 declare function normalizeClientIp(value: string): string;
 
 type SafeJwtAlgorithm = "RS256" | "PS256" | "ES256" | "EdDSA";
+/**
+ * The active tenant, as the `tenant` claim carries it. Present only on a
+ * session scoped to one — a token minted before any tenant switch has no
+ * tenant and no claim.
+ *
+ * Snake_case because these are wire names, not SDK ones: the claim is signed,
+ * and renaming its fields on the way in would hide what was actually asserted.
+ */
+interface AuthyonTenantClaim {
+    id: string;
+    slug: string;
+    name: string;
+    /** The tenant above this one, or `null` at a root. */
+    parent_id?: string | null;
+    /**
+     * The materialised chain from the root down to this tenant. Signed, so a
+     * consumer can answer "is that tenant under mine?" with a prefix comparison
+     * and no round trip — which is the whole reason it is in the token.
+     */
+    path?: string;
+    /** Distance from the root: `0` at a root tenant. */
+    depth?: number;
+    /**
+     * Version of `path`. A tenant that gets moved bumps it, which is what makes
+     * the signed path safe to trust: a token minted before the move no longer
+     * matches and the API refuses it with `tenant.path_stale`, instead of
+     * letting a stale prefix keep answering yes.
+     */
+    pv?: number;
+    roles?: string[];
+    /** Effective permissions AT this tenant. */
+    permissions?: string[];
+    /**
+     * Set only when the session descended into this tenant from an ancestor,
+     * naming the node the permissions came from — the user holds no membership
+     * here. Treat it as borrowed authority if that matters to you (a banner, a
+     * tighter trail, a refusal); ignore it and you have a session scoped to a
+     * tenant, which is what it is. Absent on any other session.
+     */
+    via?: string | null;
+}
 interface AuthyonJwtClaims extends JWTPayload {
     sub: string;
     iss: string;
@@ -849,6 +962,8 @@ interface AuthyonJwtClaims extends JWTPayload {
     roles?: string[];
     permissions?: string[];
     scope?: string;
+    /** The active tenant and the grants held inside it. Absent until a switch. */
+    tenant?: AuthyonTenantClaim;
 }
 interface VerifiedAccessToken {
     claims: AuthyonJwtClaims;
@@ -1048,23 +1163,66 @@ declare class AuthyonServerClient {
              * });
              * ```
              *
+             * `parentId` narrows the page to one level of the tree — `children()`
+             * and `roots()` below are the same call with that one option set.
+             *
              * Against an Authyon API older than 2026-10-21 this route ignored
              * skip/take/search and answered with a bare array; one older than
-             * 2026-10-22 ignores `filter`, which reads as a page that is too wide
-             * rather than an error.
+             * 2026-10-22 ignores `filter` and one older than 2026-10-31 ignores
+             * `parentId`, which read as a page that is too wide rather than an error.
              */
             list: (params?: TenantListOptions) => Promise<Paged<Organization>>;
-            /** POST /env/tenants — create a tenant in the environment. */
+            /**
+             * One page of a tenant's direct sub-tenants — `list()` with `parentId`.
+             *
+             * Only one level: a node's own children carry `childCount`, so a tree
+             * view asks again where that is above zero instead of reading the whole
+             * subtree to draw the first level of it.
+             */
+            children: (parentTenantId: string, params?: Omit<TenantListOptions, "parentId">) => Promise<Paged<Organization>>;
+            /**
+             * One page of the environment's root tenants — `list()` with no parent.
+             *
+             * This is the first level of the tree, and the difference from `list()`
+             * is worth keeping straight: `list()` returns every tenant at every
+             * depth, which is what a flat picker wants and what a tree view must not
+             * start from.
+             */
+            roots: (params?: Omit<TenantListOptions, "parentId">) => Promise<Paged<Organization>>;
+            /**
+             * POST /env/tenants — create a tenant in the environment.
+             *
+             * `parentTenantId` nests it under an existing tenant. The environment's
+             * `maxTenantDepth` has to allow the level — it ships as `1`, roots only,
+             * so this answers `tenant.depth.not_allowed` until an operator raises it
+             * in the console.
+             */
             create: (input: CreateOrganizationInput) => Promise<Organization>;
-            /** GET /env/tenants/{tenantId} — fetch a tenant by id. */
+            /**
+             * GET /env/tenants/{tenantId} — fetch a tenant by id.
+             *
+             * Returns `ancestors` as well, the chain above it root first, so a
+             * breadcrumb costs this one call rather than one per level.
+             */
             get: (tenantId: string) => Promise<Organization>;
             /** PUT /env/tenants/{tenantId} — update a tenant. */
             update: (tenantId: string, input: UpdateOrganizationInput) => Promise<Organization>;
             /** PUT /env/tenants/{tenantId}/metadata - replace public and private metadata. */
             updateMetadata: (tenantId: string, input: Pick<CreateOrganizationInput, "publicMetadata" | "privateMetadata">) => Promise<void>;
-            /** POST /env/tenants/{tenantId}/disable — disable without removing tenant data. */
+            /**
+             * POST /env/tenants/{tenantId}/disable — disable without removing tenant
+             * data.
+             *
+             * Disables the branch below it too. A sub-tenant left live under a
+             * disabled parent would go on authenticating its users, which is the one
+             * thing switching a tenant off is there to stop — so check `childCount`
+             * before calling this on a node with children.
+             */
             disable: (tenantId: string) => Promise<void>;
-            /** DELETE /env/tenants/{tenantId} — logically delete (disable) a tenant. */
+            /**
+             * DELETE /env/tenants/{tenantId} — logically delete (disable) a tenant,
+             * and the branch below it. Same handler as `disable()`.
+             */
             delete: (tenantId: string) => Promise<void>;
             members: {
                 /**
@@ -1293,4 +1451,4 @@ declare class TenantScopedClient {
 /** Convenience factory: `const authyon = createClient({ clientId, clientSecret })`. */
 declare function createClient(options?: AuthyonServerClientOptions): AuthyonServerClient;
 
-export { type RoleGrant as $, AuthyonServerClient as A, type HttpLogEvent as B, type ClientCredentials as C, type HttpLogger as D, type EnvironmentUser as E, FetchHttpAdapter as F, type InviteTenantMemberInput as G, type HttpAdapter as H, type IntrospectResult as I, type IssuePasswordResetInput as J, type JsonWebKeySet as K, JwksTokenVerifier as L, type JwksTokenVerifierOptions as M, LoggingHttpAdapter as N, type LoginActivity as O, type OpenIdConfiguration as P, type Organization as Q, type OtpCheckResult as R, type Paged as S, type PaginationOptions as T, type PasswordResetCompleted as U, type PasswordResetIssued as V, type PasswordResetPreview as W, type Permission as X, type PermissionsByRole as Y, type ReservedPermissions as Z, type Role as _, type HttpLoggerOptions as a, type RoleInput as a0, type RoleList as a1, type RolePermissions as a2, type SafeJwtAlgorithm as a3, type SecurityMethods as a4, type SubjectApprovals as a5, type SubjectSecurity as a6, TENANT_FILTER_MAX_DEPTH as a7, TENANT_FILTER_MAX_VALUES as a8, TENANT_FILTER_MAX_VALUE_LENGTH as a9, tenantFilter as aA, type TenantClientValidationResult as aa, type TenantCredentialIssued as ab, type TenantCredentialSummary as ac, type TenantFilterExpression as ad, type TenantFilterValue as ae, type TenantInvite as af, type TenantInviteAccepted as ag, type TenantInviteInput as ah, type TenantInviteIssued as ai, type TenantInvitePreview as aj, type TenantInviteStatus as ak, type TenantListOptions as al, type TenantMember as am, type TenantMemberPage as an, type TenantMembership as ao, TenantScopedClient as ap, type TokenResult as aq, TokenVerificationError as ar, type TokenVerificationErrorCode as as, type UpdateOrganizationInput as at, type User as au, UserScopedClient as av, type ValidateResult as aw, type VerifiedAccessToken as ax, createClient as ay, normalizeClientIp as az, type AcceptTenantInviteInput as b, type AccessTokenSource as c, type Approval as d, type ApprovalAssurance as e, type ApprovalPayload as f, type ApprovalStatus as g, type ApprovalWebAuthnOptions as h, type AuditEvent as i, type AuthyonJwksDiscoveryOptions as j, type AuthyonJwtClaims as k, type AuthyonServerClientOptions as l, type ClientRequestContext as m, type ConfirmApprovalInput as n, type ConsumedApproval as o, type CreateApprovalInput as p, type CreateCredentialInput as q, type CreateOrganizationInput as r, type CreatePermissionInput as s, type CreateTenantCredentialInput as t, type CreateUserInput as u, type CredentialCreator as v, type CredentialDetail as w, type CredentialListOptions as x, type CredentialPermissionsInput as y, type HttpAdapterRequest as z };
+export { type ReservedPermissions as $, AuthyonServerClient as A, type CredentialPermissionsInput as B, CLIENT_IP_HEADER as C, type HttpAdapterRequest as D, type EnvironmentUser as E, FetchHttpAdapter as F, type HttpLogEvent as G, type HttpAdapter as H, type HttpLogger as I, JwksTokenVerifier as J, type IntrospectResult as K, type InviteTenantMemberInput as L, type IssuePasswordResetInput as M, type JsonWebKeySet as N, type JwksTokenVerifierOptions as O, LoggingHttpAdapter as P, type LoginActivity as Q, type OpenIdConfiguration as R, type Organization as S, type OtpCheckResult as T, type Paged as U, type PaginationOptions as V, type PasswordResetCompleted as W, type PasswordResetIssued as X, type PasswordResetPreview as Y, type Permission as Z, type PermissionsByRole as _, type HttpLoggerOptions as a, type Role as a0, type RoleGrant as a1, type RoleInput as a2, type RoleList as a3, type RolePermissions as a4, type SafeJwtAlgorithm as a5, type SecurityMethods as a6, type SubjectApprovals as a7, type SubjectSecurity as a8, TENANT_FILTER_MAX_DEPTH as a9, type VerifiedAccessToken as aA, createClient as aB, normalizeClientIp as aC, tenantFilter as aD, TENANT_FILTER_MAX_VALUES as aa, TENANT_FILTER_MAX_VALUE_LENGTH as ab, type TenantAncestor as ac, type TenantClientValidationResult as ad, type TenantCredentialIssued as ae, type TenantCredentialSummary as af, type TenantFilterExpression as ag, type TenantFilterValue as ah, type TenantInvite as ai, type TenantInviteAccepted as aj, type TenantInviteInput as ak, type TenantInviteIssued as al, type TenantInvitePreview as am, type TenantInviteStatus as an, type TenantListOptions as ao, type TenantMember as ap, type TenantMemberPage as aq, type TenantMembership as ar, TenantScopedClient as as, type TokenResult as at, TokenVerificationError as au, type TokenVerificationErrorCode as av, type UpdateOrganizationInput as aw, type User as ax, UserScopedClient as ay, type ValidateResult as az, type AcceptTenantInviteInput as b, type AccessTokenSource as c, type Approval as d, type ApprovalAssurance as e, type ApprovalPayload as f, type ApprovalStatus as g, type ApprovalWebAuthnOptions as h, type AuditEvent as i, type AuthyonJwksDiscoveryOptions as j, type AuthyonJwtClaims as k, type AuthyonServerClientOptions as l, type AuthyonTenantClaim as m, type ClientCredentials as n, type ClientRequestContext as o, type ConfirmApprovalInput as p, type ConsumedApproval as q, type CreateApprovalInput as r, type CreateCredentialInput as s, type CreateOrganizationInput as t, type CreatePermissionInput as u, type CreateTenantCredentialInput as v, type CreateUserInput as w, type CredentialCreator as x, type CredentialDetail as y, type CredentialListOptions as z };

package/dist/bff.d.cts

@@ -1,4 +1,4 @@
-import { H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonServerClient } from './authyonServerClient-COrfN4o_.cjs';
+import { H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonServerClient } from './authyonServerClient-CW46xIRD.cjs';
 import 'jose';
 
 interface BffLoginInput {

package/dist/bff.d.ts

@@ -1,4 +1,4 @@
-import { H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonServerClient } from './authyonServerClient-COrfN4o_.js';
+import { H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonServerClient } from './authyonServerClient-CW46xIRD.js';
 import 'jose';
 
 interface BffLoginInput {