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

package/dist/{ability-BTcayvkM.d.cts → ability-DjEMCVjx.d.cts}

@@ -212,6 +212,17 @@ interface Organization {
     customFields?: string;
     /** JSON-encoded metadata visible to members of the organization. */
     publicMetadata?: string;
+    /**
+     * `false` for an organization the user belongs to. `true` for one they may
+     * switch into from an ancestor without being a member — show it as borrowed
+     * rather than owned. Only `organization.list()` fills it.
+     *
+     * Ignoring the field still leaves you with a switchable organization, which
+     * is what it is. Absent on an API older than 2026-10-31.
+     */
+    inherited?: boolean;
+    /** Distance from the root: `0` at a root organization. Indent the switcher by it. */
+    depth?: number;
 }
 /** POST /auth/tenants — creates an organization owned by the signed-in user. */
 interface CreateOrganizationInput {
@@ -219,6 +230,16 @@ interface CreateOrganizationInput {
     slug?: string;
     description?: string;
     customFields?: Record<string, unknown>;
+    /**
+     * Creates the organization underneath an existing one. Omitted creates a
+     * root organization, which is all this endpoint could do before the
+     * hierarchy existed.
+     *
+     * The caller has to belong to the parent (or to an organization above it)
+     * and hold `subtenants:tree:create` there, and the environment's
+     * `maxTenantDepth` has to allow the level — it ships as `1`, roots only.
+     */
+    parentTenantId?: string;
 }
 /** GET /auth/tenants/{organizationId}/members — confirmed against the live API. */
 interface OrganizationMember {
@@ -517,7 +538,13 @@ interface AuthyonClientOptions {
     /** Publishable environment key (`pk_live_...` / `pk_test_...`). */
     envKey: string;
     /**
-     * Originating client IP to forward on every API call as `X-Forwarded-For`.
+     * Originating client IP to forward on every API call as
+     * `X-Authyon-Client-Ip` (and `X-Forwarded-For`, for your own proxies).
+     *
+     * Authyon honours it only from a trusted BFF — a socket peer in the API's
+     * `TRUSTED_BFF_IPS`, or a request carrying `TRUSTED_BFF_SECRET`, which this
+     * SDK does not send. Never set it in the browser: the connection already
+     * carries the address.
      * Browsers cannot reliably discover their public IP by themselves; set this
      * only when your application receives it from trusted infrastructure.
      */
@@ -583,7 +610,21 @@ declare class AuthyonClient {
      */
     private hydrateUser;
     private request;
-    /** POST /auth/register — creates a new user (rate-limited to 20/hour per IP). */
+    /**
+     * POST /auth/register — creates a new user (rate-limited to 20/hour per IP).
+     *
+     * An environment may close public sign-up, and then this route answers as
+     * though it were not mapped: **404 with no body**, so the error carries
+     * status 404 and the code `unknown`. The SDK does not relabel it, because a
+     * wrong `baseUrl` looks exactly the same from here and guessing would send
+     * you after the wrong bug — check the environment's setting in the console
+     * and the URL you configured. Accounts in a closed environment are created
+     * by your backend instead, through `environment.users.create()` in
+     * `@authyon/server`, which already needs the `users:write` scope.
+     *
+     * It gates creation only. Everyone who already has an account signs in as
+     * before, and magic link and social sign-up keep their own switches.
+     */
     register(params: RegisterInput): Promise<{
         id: string;
     }>;
@@ -672,7 +713,15 @@ declare class AuthyonClient {
         confirmPasswordReset: (token: string, newPassword: string) => Promise<PasswordResetCompleted>;
     };
     readonly organization: {
-        /** GET /auth/tenants — filterable list of organization memberships. */
+        /**
+         * GET /auth/tenants — filterable list of organization memberships.
+         *
+         * Also lists the organizations below them that the user may switch into
+         * without being a member, marked `inherited` — only the ones that actually
+         * carry `subtenants:tree:switch`, so the switcher never offers an
+         * organization the switch would then refuse. `depth` indents the list into
+         * the tree it describes.
+         */
         list: (params?: {
             search?: string;
         } & PaginationOptions) => Promise<Organization[]>;
@@ -680,16 +729,41 @@ declare class AuthyonClient {
          * POST /auth/tenants — creates an organization owned by the signed-in
          * user (only available when self-service organization creation is
          * enabled for the environment).
+         *
+         * `parentTenantId` nests it under one the user already belongs to, which
+         * needs `subtenants:tree:create` there. The creator lands as the effective
+         * owner either way, with `tenants:settings:manage`,
+         * `tenants:members:invite` and `tenants:members:remove` granted directly
+         * inside the new organization.
          */
         create: (params?: CreateOrganizationInput) => Promise<Organization>;
         /** GET /auth/tenants/{organizationId} — fetch one of the user's organizations by id. */
         get: (organizationId: string) => Promise<Organization>;
         /**
          * PATCH /auth/tenants/{organizationId} — renames the organization.
-         * Requires the `tenants:manage` custom permission on it.
+         *
+         * Requires the `tenants:settings:manage` custom permission on it, or
+         * `subtenants:tree:manage` on an organization above it. The value was
+         * spelled `tenants:manage` before 2026-10-31 — two segments, which the API
+         * could not store, so the endpoint refused everyone who had been granted
+         * it.
          */
         rename: (organizationId: string, name: string) => Promise<Organization>;
-        /** POST /auth/switch-tenant — issues a fresh token scoped to the new organization. */
+        /**
+         * POST /auth/switch-tenant — issues a fresh token scoped to the new
+         * organization.
+         *
+         * Membership is enough for one of the user's own organizations. Descending
+         * into one below it takes `subtenants:tree:switch` at the organization they
+         * belong to — deliberately not the same permission as administering a
+         * sub-organization from the outside, since operating AS it is the larger of
+         * the two powers. The grants then travel from the node the user belongs to,
+         * and the token says so in its `tenant.via`.
+         *
+         * Refusals: `tenant.outside_scope` (no path down to it),
+         * `tenant.ancestor_disabled`, and `tenant.path_stale` when the tree moved
+         * under a session — sign-in again rather than retrying.
+         */
         switch: (organizationSlug: string) => Promise<Session>;
         /** The organization the current session is scoped to, from the cached session — no network call. */
         current: () => Organization | null;
@@ -918,11 +992,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/{ability-BTcayvkM.d.ts → ability-DjEMCVjx.d.ts}

@@ -212,6 +212,17 @@ interface Organization {
     customFields?: string;
     /** JSON-encoded metadata visible to members of the organization. */
     publicMetadata?: string;
+    /**
+     * `false` for an organization the user belongs to. `true` for one they may
+     * switch into from an ancestor without being a member — show it as borrowed
+     * rather than owned. Only `organization.list()` fills it.
+     *
+     * Ignoring the field still leaves you with a switchable organization, which
+     * is what it is. Absent on an API older than 2026-10-31.
+     */
+    inherited?: boolean;
+    /** Distance from the root: `0` at a root organization. Indent the switcher by it. */
+    depth?: number;
 }
 /** POST /auth/tenants — creates an organization owned by the signed-in user. */
 interface CreateOrganizationInput {
@@ -219,6 +230,16 @@ interface CreateOrganizationInput {
     slug?: string;
     description?: string;
     customFields?: Record<string, unknown>;
+    /**
+     * Creates the organization underneath an existing one. Omitted creates a
+     * root organization, which is all this endpoint could do before the
+     * hierarchy existed.
+     *
+     * The caller has to belong to the parent (or to an organization above it)
+     * and hold `subtenants:tree:create` there, and the environment's
+     * `maxTenantDepth` has to allow the level — it ships as `1`, roots only.
+     */
+    parentTenantId?: string;
 }
 /** GET /auth/tenants/{organizationId}/members — confirmed against the live API. */
 interface OrganizationMember {
@@ -517,7 +538,13 @@ interface AuthyonClientOptions {
     /** Publishable environment key (`pk_live_...` / `pk_test_...`). */
     envKey: string;
     /**
-     * Originating client IP to forward on every API call as `X-Forwarded-For`.
+     * Originating client IP to forward on every API call as
+     * `X-Authyon-Client-Ip` (and `X-Forwarded-For`, for your own proxies).
+     *
+     * Authyon honours it only from a trusted BFF — a socket peer in the API's
+     * `TRUSTED_BFF_IPS`, or a request carrying `TRUSTED_BFF_SECRET`, which this
+     * SDK does not send. Never set it in the browser: the connection already
+     * carries the address.
      * Browsers cannot reliably discover their public IP by themselves; set this
      * only when your application receives it from trusted infrastructure.
      */
@@ -583,7 +610,21 @@ declare class AuthyonClient {
      */
     private hydrateUser;
     private request;
-    /** POST /auth/register — creates a new user (rate-limited to 20/hour per IP). */
+    /**
+     * POST /auth/register — creates a new user (rate-limited to 20/hour per IP).
+     *
+     * An environment may close public sign-up, and then this route answers as
+     * though it were not mapped: **404 with no body**, so the error carries
+     * status 404 and the code `unknown`. The SDK does not relabel it, because a
+     * wrong `baseUrl` looks exactly the same from here and guessing would send
+     * you after the wrong bug — check the environment's setting in the console
+     * and the URL you configured. Accounts in a closed environment are created
+     * by your backend instead, through `environment.users.create()` in
+     * `@authyon/server`, which already needs the `users:write` scope.
+     *
+     * It gates creation only. Everyone who already has an account signs in as
+     * before, and magic link and social sign-up keep their own switches.
+     */
     register(params: RegisterInput): Promise<{
         id: string;
     }>;
@@ -672,7 +713,15 @@ declare class AuthyonClient {
         confirmPasswordReset: (token: string, newPassword: string) => Promise<PasswordResetCompleted>;
     };
     readonly organization: {
-        /** GET /auth/tenants — filterable list of organization memberships. */
+        /**
+         * GET /auth/tenants — filterable list of organization memberships.
+         *
+         * Also lists the organizations below them that the user may switch into
+         * without being a member, marked `inherited` — only the ones that actually
+         * carry `subtenants:tree:switch`, so the switcher never offers an
+         * organization the switch would then refuse. `depth` indents the list into
+         * the tree it describes.
+         */
         list: (params?: {
             search?: string;
         } & PaginationOptions) => Promise<Organization[]>;
@@ -680,16 +729,41 @@ declare class AuthyonClient {
          * POST /auth/tenants — creates an organization owned by the signed-in
          * user (only available when self-service organization creation is
          * enabled for the environment).
+         *
+         * `parentTenantId` nests it under one the user already belongs to, which
+         * needs `subtenants:tree:create` there. The creator lands as the effective
+         * owner either way, with `tenants:settings:manage`,
+         * `tenants:members:invite` and `tenants:members:remove` granted directly
+         * inside the new organization.
          */
         create: (params?: CreateOrganizationInput) => Promise<Organization>;
         /** GET /auth/tenants/{organizationId} — fetch one of the user's organizations by id. */
         get: (organizationId: string) => Promise<Organization>;
         /**
          * PATCH /auth/tenants/{organizationId} — renames the organization.
-         * Requires the `tenants:manage` custom permission on it.
+         *
+         * Requires the `tenants:settings:manage` custom permission on it, or
+         * `subtenants:tree:manage` on an organization above it. The value was
+         * spelled `tenants:manage` before 2026-10-31 — two segments, which the API
+         * could not store, so the endpoint refused everyone who had been granted
+         * it.
          */
         rename: (organizationId: string, name: string) => Promise<Organization>;
-        /** POST /auth/switch-tenant — issues a fresh token scoped to the new organization. */
+        /**
+         * POST /auth/switch-tenant — issues a fresh token scoped to the new
+         * organization.
+         *
+         * Membership is enough for one of the user's own organizations. Descending
+         * into one below it takes `subtenants:tree:switch` at the organization they
+         * belong to — deliberately not the same permission as administering a
+         * sub-organization from the outside, since operating AS it is the larger of
+         * the two powers. The grants then travel from the node the user belongs to,
+         * and the token says so in its `tenant.via`.
+         *
+         * Refusals: `tenant.outside_scope` (no path down to it),
+         * `tenant.ancestor_disabled`, and `tenant.path_stale` when the tree moved
+         * under a session — sign-in again rather than retrying.
+         */
         switch: (organizationSlug: string) => Promise<Session>;
         /** The organization the current session is scoped to, from the cached session — no network call. */
         current: () => Organization | null;
@@ -918,11 +992,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/{chunk-3XJY6BCI.js → chunk-IX6U6A72.js}

@@ -194,12 +194,29 @@ 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 required = requiredPermission?.trim() ?? "";
+  if (!isWellFormedPermission(required)) return false;
   const permissionSource = isPermissionList(source) ? { permissions: source } : source;
-  return createAuthyonAbility(permissionSource).can(requirement.action, requirement.subject);
+  const granted = [
+    ...permissionSource.permissions ?? [],
+    ...permissionSource.scope?.split(/\s+/).filter(Boolean) ?? []
+  ];
+  return granted.some((permission) => grants(permission.trim(), required));
+}
+function grants(granted, required) {
+  if (!isWellFormedPermission(granted)) return false;
+  if (isFullWildcard(granted)) return true;
+  const grantedSegments = granted.split(":");
+  const requiredSegments = required.split(":");
+  if (grantedSegments.length !== requiredSegments.length) return false;
+  return grantedSegments.every(
+    (segment, index) => segment === "*" || segment === requiredSegments[index]
+  );
+}
+function isWellFormedPermission(permission) {
+  if (!permission) return false;
+  const segments = permission.split(":");
+  return segments.length >= 2 && segments.every((segment) => segment.length > 0);
 }
 function hasPermissionGroup(source, group) {
   const hasAll = (group.allOf ?? []).every((permission) => hasPermission(source, permission));
@@ -214,13 +231,23 @@ function createAuthyonRules(source = {}, options = {}) {
     ...source.permissions ?? [],
     ...source.scope?.split(/\s+/).filter(Boolean) ?? []
   ]);
-  const rules = [...permissions].map(permissionToRule).filter(isAbilityRule);
+  const rules = [...permissions].map(grantToRule).filter(isAbilityRule);
   for (const role of /* @__PURE__ */ new Set([...source.roles ?? [], ...options.roles ?? []])) {
     rules.push(...(options.roleRules?.[role] ?? []).map(cloneRule));
   }
   rules.push(...(options.rules ?? []).map(cloneRule));
   return rules;
 }
+function grantToRule(permission) {
+  const normalized = permission.trim();
+  if (normalized && isFullWildcard(normalized)) {
+    return { action: "manage", subject: "all" };
+  }
+  return permissionToRule(normalized);
+}
+function isFullWildcard(permission) {
+  return permission.split(":").every((segment) => segment === "*");
+}
 function permissionToRule(permission) {
   const normalized = permission.trim();
   if (!normalized) return null;

package/dist/index.cjs

@@ -29,6 +29,8 @@ __export(index_exports, {
   ErrorCodes: () => ErrorCodes,
   FetchHttpAdapter: () => FetchHttpAdapter,
   LoggingHttpAdapter: () => LoggingHttpAdapter,
+  SubtenantPermissions: () => SubtenantPermissions,
+  TenantPermissions: () => TenantPermissions,
   createAuthyonAbility: () => createAuthyonAbility,
   createAuthyonRules: () => createAuthyonRules,
   createClient: () => createClient,
@@ -474,9 +476,11 @@ var JsonHttpClient = class {
 };
 
 // ../../internal/core/http/clientIp.ts
+var CLIENT_IP_HEADER = "X-Authyon-Client-Ip";
 function clientIpHeaders(context) {
   if (!context?.clientIp) return {};
-  return { "X-Forwarded-For": normalizeClientIp(context.clientIp) };
+  const ip = normalizeClientIp(context.clientIp);
+  return { "X-Forwarded-For": ip, [CLIENT_IP_HEADER]: ip };
 }
 function normalizeClientIp(value) {
   let ip = value.trim();
@@ -605,26 +609,59 @@ var AuthyonClient = class {
     };
     // ── Organization ─────────────────────────────────────────────────────────
     this.organization = {
-      /** GET /auth/tenants — filterable list of organization memberships. */
+      /**
+       * GET /auth/tenants — filterable list of organization memberships.
+       *
+       * Also lists the organizations below them that the user may switch into
+       * without being a member, marked `inherited` — only the ones that actually
+       * carry `subtenants:tree:switch`, so the switcher never offers an
+       * organization the switch would then refuse. `depth` indents the list into
+       * the tree it describes.
+       */
       list: (params = {}) => this.request(appendQuery("/auth/tenants", params), { bearer: true }),
       /**
        * POST /auth/tenants — creates an organization owned by the signed-in
        * user (only available when self-service organization creation is
        * enabled for the environment).
+       *
+       * `parentTenantId` nests it under one the user already belongs to, which
+       * needs `subtenants:tree:create` there. The creator lands as the effective
+       * owner either way, with `tenants:settings:manage`,
+       * `tenants:members:invite` and `tenants:members:remove` granted directly
+       * inside the new organization.
        */
       create: (params = {}) => this.request("/auth/tenants", { method: "POST", bearer: true, body: params }),
       /** GET /auth/tenants/{organizationId} — fetch one of the user's organizations by id. */
       get: (organizationId) => this.request(`/auth/tenants/${encodeURIComponent(organizationId)}`, { bearer: true }),
       /**
        * PATCH /auth/tenants/{organizationId} — renames the organization.
-       * Requires the `tenants:manage` custom permission on it.
+       *
+       * Requires the `tenants:settings:manage` custom permission on it, or
+       * `subtenants:tree:manage` on an organization above it. The value was
+       * spelled `tenants:manage` before 2026-10-31 — two segments, which the API
+       * could not store, so the endpoint refused everyone who had been granted
+       * it.
        */
       rename: (organizationId, name) => this.request(`/auth/tenants/${encodeURIComponent(organizationId)}`, {
         method: "PATCH",
         bearer: true,
         body: { name }
       }),
-      /** POST /auth/switch-tenant — issues a fresh token scoped to the new organization. */
+      /**
+       * POST /auth/switch-tenant — issues a fresh token scoped to the new
+       * organization.
+       *
+       * Membership is enough for one of the user's own organizations. Descending
+       * into one below it takes `subtenants:tree:switch` at the organization they
+       * belong to — deliberately not the same permission as administering a
+       * sub-organization from the outside, since operating AS it is the larger of
+       * the two powers. The grants then travel from the node the user belongs to,
+       * and the token says so in its `tenant.via`.
+       *
+       * Refusals: `tenant.outside_scope` (no path down to it),
+       * `tenant.ancestor_disabled`, and `tenant.path_stale` when the tree moved
+       * under a session — sign-in again rather than retrying.
+       */
       switch: (organizationSlug) => this.request("/auth/switch-tenant", {
         method: "POST",
         bearer: true,
@@ -938,7 +975,21 @@ var AuthyonClient = class {
     return this.http.parse(response);
   }
   // ── Auth flows ───────────────────────────────────────────────────────────
-  /** POST /auth/register — creates a new user (rate-limited to 20/hour per IP). */
+  /**
+   * POST /auth/register — creates a new user (rate-limited to 20/hour per IP).
+   *
+   * An environment may close public sign-up, and then this route answers as
+   * though it were not mapped: **404 with no body**, so the error carries
+   * status 404 and the code `unknown`. The SDK does not relabel it, because a
+   * wrong `baseUrl` looks exactly the same from here and guessing would send
+   * you after the wrong bug — check the environment's setting in the console
+   * and the URL you configured. Accounts in a closed environment are created
+   * by your backend instead, through `environment.users.create()` in
+   * `@authyon/server`, which already needs the `users:write` scope.
+   *
+   * It gates creation only. Everyone who already has an account signs in as
+   * before, and magic link and social sign-up keep their own switches.
+   */
   async register(params) {
     return this.request("/auth/register", { method: "POST", body: params });
   }
@@ -1295,12 +1346,29 @@ 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 required = requiredPermission?.trim() ?? "";
+  if (!isWellFormedPermission(required)) return false;
   const permissionSource = isPermissionList(source) ? { permissions: source } : source;
-  return createAuthyonAbility(permissionSource).can(requirement.action, requirement.subject);
+  const granted = [
+    ...permissionSource.permissions ?? [],
+    ...permissionSource.scope?.split(/\s+/).filter(Boolean) ?? []
+  ];
+  return granted.some((permission) => grants(permission.trim(), required));
+}
+function grants(granted, required) {
+  if (!isWellFormedPermission(granted)) return false;
+  if (isFullWildcard(granted)) return true;
+  const grantedSegments = granted.split(":");
+  const requiredSegments = required.split(":");
+  if (grantedSegments.length !== requiredSegments.length) return false;
+  return grantedSegments.every(
+    (segment, index) => segment === "*" || segment === requiredSegments[index]
+  );
+}
+function isWellFormedPermission(permission) {
+  if (!permission) return false;
+  const segments = permission.split(":");
+  return segments.length >= 2 && segments.every((segment) => segment.length > 0);
 }
 function hasPermissionGroup(source, group) {
   const hasAll = (group.allOf ?? []).every((permission) => hasPermission(source, permission));
@@ -1315,13 +1383,23 @@ function createAuthyonRules(source = {}, options = {}) {
     ...source.permissions ?? [],
     ...source.scope?.split(/\s+/).filter(Boolean) ?? []
   ]);
-  const rules = [...permissions].map(permissionToRule).filter(isAbilityRule);
+  const rules = [...permissions].map(grantToRule).filter(isAbilityRule);
   for (const role of /* @__PURE__ */ new Set([...source.roles ?? [], ...options.roles ?? []])) {
     rules.push(...(options.roleRules?.[role] ?? []).map(cloneRule));
   }
   rules.push(...(options.rules ?? []).map(cloneRule));
   return rules;
 }
+function grantToRule(permission) {
+  const normalized = permission.trim();
+  if (normalized && isFullWildcard(normalized)) {
+    return { action: "manage", subject: "all" };
+  }
+  return permissionToRule(normalized);
+}
+function isFullWildcard(permission) {
+  return permission.split(":").every((segment) => segment === "*");
+}
 function permissionToRule(permission) {
   const normalized = permission.trim();
   if (!normalized) return null;
@@ -1418,6 +1496,32 @@ function isRecord(value) {
 function isAbilityRule(value) {
   return value !== null;
 }
+
+// ../../internal/core/authorization/tenantPermissions.ts
+var TenantPermissions = {
+  /** Rename the tenant and change its settings. */
+  SettingsManage: "tenants:settings:manage",
+  /** Invite an address to the tenant. */
+  MembersInvite: "tenants:members:invite",
+  /** Remove a member from the tenant. */
+  MembersRemove: "tenants:members:remove"
+};
+var SubtenantPermissions = {
+  /** Read any tenant below one you belong to. */
+  TreeRead: "subtenants:tree:read",
+  /** Rename a tenant below yours, and add or remove its members. */
+  TreeManage: "subtenants:tree:manage",
+  /** Create a tenant underneath one you belong to. */
+  TreeCreate: "subtenants:tree:create",
+  /**
+   * Make a tenant below yours the ACTIVE tenant of the session — acting inside
+   * it rather than on it from outside. Deliberately not the same permission as
+   * {@link SubtenantPermissions.TreeManage}: administering a sub-tenant through
+   * the management endpoints and operating as that sub-tenant are different
+   * powers, and granting the first should not hand over the second.
+   */
+  TreeSwitch: "subtenants:tree:switch"
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthyonAbility,
@@ -1429,6 +1533,8 @@ function isAbilityRule(value) {
   ErrorCodes,
   FetchHttpAdapter,
   LoggingHttpAdapter,
+  SubtenantPermissions,
+  TenantPermissions,
   createAuthyonAbility,
   createAuthyonRules,
   createClient,

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { T as TokenStorage, H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonClient } from './ability-BTcayvkM.cjs';
-export { b as AbilityConditions, c as AbilityEvent, d as AbilityListener, e as AbilityRule, f as AbilitySubject, g as AcceptOrganizationInviteInput, h as Activity, i as Approval, j as ApprovalAssurance, k as ApprovalPayload, l as ApprovalStatus, m as ApprovalWebAuthnOptions, n as AuthEvent, o as AuthState, p as AuthStateListener, q as AuthenticatorSetup, r as AuthyonAbility, s as AuthyonAbilityBuilder, t as AuthyonAbilityOptions, u as AuthyonClientOptions, v as AuthyonPermissionSource, w as AuthyonSessionController, C as ConfirmApprovalInput, x as CreateOrganizationInput, F as FetchHttpAdapter, y as HttpAdapterRequest, z as HttpLogEvent, B as HttpLogger, I as IntrospectResult, D as InviteMemberInput, L as LoggingHttpAdapter, E as LoginInput, G as LoginResult, O as Organization, J as OrganizationInvite, K as OrganizationInviteAccepted, M as OrganizationInviteInput, N as OrganizationInviteIssued, P as OrganizationInvitePreview, Q as OrganizationInviteStatus, R as OrganizationMember, S as Paged, U as PaginationOptions, V as PasswordResetCompleted, W as PasswordResetPreview, X as PasswordResetRequestOptions, Y as PermissionGroup, Z as RegisterInput, _ as Role, $ as SecurityMethods, a0 as Session, a1 as SessionControllerOptions, a2 as SessionInfo, a3 as SessionSnapshot, a4 as SessionSnapshotListener, a5 as SessionStatus, a6 as SsoProvider, a7 as SubjectApprovals, a8 as SubjectSecurity, a9 as TwoFactorChallenge, aa as TwoFactorMethod, ab as TwoFactorStatus, ac as User, ad as ValidateResult, ae as VerifyTwoFactorInput, af as WebAuthnAssertion, ag as WebAuthnCeremonyStart, ah as WebAuthnCredential, ai as createAuthyonAbility, aj as createAuthyonRules, ak as createClient, al as hasPermission, am as hasPermissionGroup } from './ability-BTcayvkM.cjs';
+import { T as TokenStorage, H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonClient } from './ability-DjEMCVjx.cjs';
+export { b as AbilityConditions, c as AbilityEvent, d as AbilityListener, e as AbilityRule, f as AbilitySubject, g as AcceptOrganizationInviteInput, h as Activity, i as Approval, j as ApprovalAssurance, k as ApprovalPayload, l as ApprovalStatus, m as ApprovalWebAuthnOptions, n as AuthEvent, o as AuthState, p as AuthStateListener, q as AuthenticatorSetup, r as AuthyonAbility, s as AuthyonAbilityBuilder, t as AuthyonAbilityOptions, u as AuthyonClientOptions, v as AuthyonPermissionSource, w as AuthyonSessionController, C as ConfirmApprovalInput, x as CreateOrganizationInput, F as FetchHttpAdapter, y as HttpAdapterRequest, z as HttpLogEvent, B as HttpLogger, I as IntrospectResult, D as InviteMemberInput, L as LoggingHttpAdapter, E as LoginInput, G as LoginResult, O as Organization, J as OrganizationInvite, K as OrganizationInviteAccepted, M as OrganizationInviteInput, N as OrganizationInviteIssued, P as OrganizationInvitePreview, Q as OrganizationInviteStatus, R as OrganizationMember, S as Paged, U as PaginationOptions, V as PasswordResetCompleted, W as PasswordResetPreview, X as PasswordResetRequestOptions, Y as PermissionGroup, Z as RegisterInput, _ as Role, $ as SecurityMethods, a0 as Session, a1 as SessionControllerOptions, a2 as SessionInfo, a3 as SessionSnapshot, a4 as SessionSnapshotListener, a5 as SessionStatus, a6 as SsoProvider, a7 as SubjectApprovals, a8 as SubjectSecurity, a9 as TwoFactorChallenge, aa as TwoFactorMethod, ab as TwoFactorStatus, ac as User, ad as ValidateResult, ae as VerifyTwoFactorInput, af as WebAuthnAssertion, ag as WebAuthnCeremonyStart, ah as WebAuthnCredential, ai as createAuthyonAbility, aj as createAuthyonRules, ak as createClient, al as hasPermission, am as hasPermissionGroup } from './ability-DjEMCVjx.cjs';
 
 declare const ErrorCodes: {
     readonly Unknown: "unknown";
@@ -99,4 +99,54 @@ declare function createMemoryStorage(): TokenStorage;
 declare function createLocalStorage(key?: string): TokenStorage;
 declare function createDefaultStorage(): TokenStorage;
 
-export { AuthyonClient, AuthyonClientBuilder, AuthyonError, type AuthyonErrorAction, type AuthyonErrorBody, type AuthyonErrorCategory, type AuthyonErrorInterpretation, ErrorCodes, HttpAdapter, HttpLoggerOptions, type KnownErrorCode, TokenStorage, createDefaultStorage, createLocalStorage, createMemoryStorage };
+/**
+ * The permission values the tenant surface checks, as constants.
+ *
+ * They are strings on the wire and nothing forces you through here — the point
+ * is that a rename shows up as a type error instead of as a 403 nobody can
+ * explain. `tenants:settings:manage` is exactly that case: it used to be
+ * written `tenants:manage`, a two-segment value the API could not even store,
+ * so the endpoint requiring it refused every caller.
+ */
+declare const TenantPermissions: {
+    /** Rename the tenant and change its settings. */
+    readonly SettingsManage: "tenants:settings:manage";
+    /** Invite an address to the tenant. */
+    readonly MembersInvite: "tenants:members:invite";
+    /** Remove a member from the tenant. */
+    readonly MembersRemove: "tenants:members:remove";
+};
+/**
+ * What lets a member of one tenant reach the tenants beneath it.
+ *
+ * A separate domain, not a suffix on `tenants:…`, and the reason is worth
+ * knowing before you grant one: permissions match per segment, so naming these
+ * `tenants:tree:manage` would have handed every role already holding
+ * `tenants:*:*` power over the whole subtree the day the hierarchy shipped — a
+ * widening that appears in no diff. `subtenants:…` is only covered by `*:*:*`,
+ * which is explicit superuser.
+ *
+ * Reaching down is opt-in at every level: holding `tenants:settings:manage` on
+ * a parent grants nothing below it, and each of these is granted at the node
+ * the caller belongs to, never at the target.
+ */
+declare const SubtenantPermissions: {
+    /** Read any tenant below one you belong to. */
+    readonly TreeRead: "subtenants:tree:read";
+    /** Rename a tenant below yours, and add or remove its members. */
+    readonly TreeManage: "subtenants:tree:manage";
+    /** Create a tenant underneath one you belong to. */
+    readonly TreeCreate: "subtenants:tree:create";
+    /**
+     * Make a tenant below yours the ACTIVE tenant of the session — acting inside
+     * it rather than on it from outside. Deliberately not the same permission as
+     * {@link SubtenantPermissions.TreeManage}: administering a sub-tenant through
+     * the management endpoints and operating as that sub-tenant are different
+     * powers, and granting the first should not hand over the second.
+     */
+    readonly TreeSwitch: "subtenants:tree:switch";
+};
+type TenantPermission = (typeof TenantPermissions)[keyof typeof TenantPermissions];
+type SubtenantPermission = (typeof SubtenantPermissions)[keyof typeof SubtenantPermissions];
+
+export { AuthyonClient, AuthyonClientBuilder, AuthyonError, type AuthyonErrorAction, type AuthyonErrorBody, type AuthyonErrorCategory, type AuthyonErrorInterpretation, ErrorCodes, HttpAdapter, HttpLoggerOptions, type KnownErrorCode, type SubtenantPermission, SubtenantPermissions, type TenantPermission, TenantPermissions, TokenStorage, createDefaultStorage, createLocalStorage, createMemoryStorage };