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

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

@@ -171,6 +171,43 @@ interface IntrospectResult {
     token_type?: string;
 }
 
+/**
+ * Builders for the tenant list's structured filters.
+ *
+ * The wire form of one filter is `<scope>.<key>:<op>[:<value>]`, repeated once
+ * per condition: `?filter=public.kind:in:reseller,partner&filter=custom.cnpj:eq:000`.
+ * Repeating the parameter ANDs the conditions and the comma inside `in` is the
+ * OR, which is the whole reason to filter server-side — the conditions are part
+ * of the SQL statement, so `total`, `pages` and `hasNext` describe the filtered
+ * set. A filter applied to a page after it arrives cannot do that.
+ *
+ * Scopes map to the three JSON documents a tenant carries: `public` →
+ * `publicMetadata`, `private` → `privateMetadata`, `custom` → `customFields`
+ * (the one the free-text `search` never covered).
+ *
+ * The rules below mirror the server's parser, so a typo raises `RangeError`
+ * here instead of coming back as a 400 `tenant.filter.invalid`.
+ */
+/** One `filter` parameter, ready to send. */
+type TenantFilterExpression = string;
+/** Values the filters accept; numbers and booleans are compared as text, the
+ *  way `jsonb ->> key` returns them. */
+type TenantFilterValue = string | number | boolean;
+declare const TENANT_FILTER_MAX_VALUES = 25;
+declare const TENANT_FILTER_MAX_VALUE_LENGTH = 200;
+declare const TENANT_FILTER_MAX_DEPTH = 3;
+declare const tenantFilter: {
+    /** `public.kind:eq:reseller` — the key equals this value. */
+    eq(path: string, value: TenantFilterValue): TenantFilterExpression;
+    /** `public.kind:in:reseller,partner` — the key equals any of these (SQL IN). */
+    in(path: string, values: readonly TenantFilterValue[]): TenantFilterExpression;
+    /** `public.notes:like:nacional` — the key contains this text, case-insensitive.
+     *  The server escapes the LIKE metacharacters, so `100%` means `100%`. */
+    like(path: string, text: string): TenantFilterExpression;
+    /** `custom.cnpj:exists` — the key is present, whatever its value. */
+    exists(path: string): TenantFilterExpression;
+};
+
 /** GET/POST /env/tenants — confirmed against the live API. */
 interface Organization {
     id: string;
@@ -189,6 +226,55 @@ 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
+ * (one substring, ORed across name, slug, description and both metadata
+ * documents); `filter` is the structured half, ANDed, one entry per condition
+ * — see `tenantFilter` for the builders and the wire format.
+ */
+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 {
@@ -336,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;
@@ -371,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;
@@ -465,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;
@@ -787,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;
@@ -802,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;
@@ -984,23 +1146,83 @@ declare class AuthyonServerClient {
              * is found by the number, and `cnpj` alone finds every tenant carrying
              * that key. `take` defaults to 25 and is capped at 100.
              *
+             * `filter` is the structured half, and the one to reach for when more
+             * than one condition has to hold: each entry is a condition on a JSON
+             * document, they are ANDed with each other and with `search`, and they
+             * run inside the statement — so the envelope keeps describing the
+             * filtered set and you can page through it. Build them with
+             * `tenantFilter`:
+             *
+             * ```ts
+             * const page = await authyon.environment.tenants.list({
+             *   filter: [
+             *     tenantFilter.in("public.kind", ["reseller", "partner"]),
+             *     tenantFilter.in("custom.cnpj", [a, b]),
+             *   ],
+             *   take: 100,
+             * });
+             * ```
+             *
+             * `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.
+             * skip/take/search and answered with a bare array; one older than
+             * 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>>;
+            /**
+             * 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.
              */
-            list: (params?: {
-                search?: string;
-            } & PaginationOptions) => Promise<Paged<Organization>>;
-            /** POST /env/tenants — create a tenant in the environment. */
             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: {
                 /**
@@ -1229,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, type TenantClientValidationResult as a7, type TenantCredentialIssued as a8, type TenantCredentialSummary as a9, type TenantInvite as aa, type TenantInviteAccepted as ab, type TenantInviteInput as ac, type TenantInviteIssued as ad, type TenantInvitePreview as ae, type TenantInviteStatus as af, type TenantMember as ag, type TenantMemberPage as ah, type TenantMembership as ai, TenantScopedClient as aj, type TokenResult as ak, TokenVerificationError as al, type TokenVerificationErrorCode as am, type UpdateOrganizationInput as an, type User as ao, UserScopedClient as ap, type ValidateResult as aq, type VerifiedAccessToken as ar, createClient as as, normalizeClientIp as at, 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.cjs

@@ -746,7 +746,14 @@ function appendQuery(path, params) {
   if (!params) return path;
   const query = new URLSearchParams();
   for (const [key, value2] of Object.entries(params)) {
-    if (value2 !== void 0) query.set(key, String(value2));
+    if (value2 === void 0) continue;
+    if (Array.isArray(value2)) {
+      for (const item of value2) {
+        if (item !== void 0) query.append(key, String(item));
+      }
+      continue;
+    }
+    query.set(key, String(value2));
   }
   const value = query.toString();
   return value ? `${path}${path.includes("?") ? "&" : "?"}${value}` : path;

package/dist/bff.d.cts

@@ -1,4 +1,4 @@
-import { H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonServerClient } from './authyonServerClient-UA7HdjtD.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-UA7HdjtD.js';
+import { H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonServerClient } from './authyonServerClient-CW46xIRD.js';
 import 'jose';
 
 interface BffLoginInput {

package/dist/bff.js

@@ -3,7 +3,7 @@ import {
   DEFAULT_BASE_URL,
   JsonHttpClient,
   createSharedTransport
-} from "./chunk-TDJNBD3Z.js";
+} from "./chunk-SUL2HLRR.js";
 import "./chunk-77J4NURK.js";
 
 // src/bff/contracts.ts

package/dist/{chunk-TDJNBD3Z.js → chunk-SUL2HLRR.js}

@@ -298,7 +298,14 @@ function appendQuery(path, params) {
   if (!params) return path;
   const query = new URLSearchParams();
   for (const [key, value2] of Object.entries(params)) {
-    if (value2 !== void 0) query.set(key, String(value2));
+    if (value2 === void 0) continue;
+    if (Array.isArray(value2)) {
+      for (const item of value2) {
+        if (item !== void 0) query.append(key, String(item));
+      }
+      continue;
+    }
+    query.set(key, String(value2));
   }
   const value = query.toString();
   return value ? `${path}${path.includes("?") ? "&" : "?"}${value}` : path;

package/dist/{chunk-NKWQMYB3.js → chunk-WF26WYSX.js}

@@ -1,7 +1,9 @@
 // ../../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();
@@ -222,12 +224,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));
@@ -242,13 +261,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;
@@ -467,6 +496,7 @@ function unauthenticated() {
 }
 
 export {
+  CLIENT_IP_HEADER,
   clientIpHeaders,
   normalizeClientIp,
   TokenVerificationError,