@authyon/server 0.2.0-beta.3 → 0.2.0-beta.4

package/dist/authorization-Cwl7YFEZ.d.ts

@@ -0,0 +1,976 @@
+import { JSONWebKeySet, JWTPayload, JWSHeaderParameters } from 'jose';
+
+interface HttpAdapterRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: BodyInit | null;
+    signal: AbortSignal;
+}
+/** Transport contract accepted by both Authyon clients. */
+interface HttpAdapter {
+    request(request: HttpAdapterRequest): Promise<Response>;
+}
+type HttpLogEvent = {
+    type: "request";
+    method: string;
+    url: string;
+    timestamp: number;
+} | {
+    type: "response";
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+    requestId?: string;
+    timestamp: number;
+} | {
+    type: "error";
+    method: string;
+    url: string;
+    errorName: string;
+    durationMs: number;
+    timestamp: number;
+};
+/** Receives sanitized HTTP lifecycle events. Headers, bodies and query values are never exposed. */
+type HttpLogger = (event: HttpLogEvent) => void;
+/**
+ * Mutable logging configuration. Change `enabled` at runtime to enable or disable logging
+ * without recreating the Authyon client.
+ */
+interface HttpLoggerOptions {
+    enabled: boolean;
+    logger?: HttpLogger;
+}
+/** Default adapter backed by the platform's Fetch API. */
+declare class FetchHttpAdapter implements HttpAdapter {
+    private readonly fetchImpl;
+    constructor(fetchImpl?: typeof fetch);
+    request(request: HttpAdapterRequest): Promise<Response>;
+}
+/** Adds safe, configurable lifecycle logging to any HTTP adapter. */
+declare class LoggingHttpAdapter implements HttpAdapter {
+    private readonly adapter;
+    private readonly options;
+    constructor(adapter: HttpAdapter, options: HttpLoggerOptions);
+    request(request: HttpAdapterRequest): Promise<Response>;
+    private log;
+}
+
+interface PaginationOptions {
+    skip?: number;
+    take?: number;
+}
+interface Paged<T> {
+    data: T[];
+    perPage?: number;
+    pageSize: number;
+    total: number;
+    pages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+interface IntrospectResult {
+    active: boolean;
+    sub?: string;
+    username?: string | null;
+    email?: string | null;
+    roles?: string[] | null;
+    permissions?: string[];
+    client_id?: string;
+    scope?: string;
+    exp?: number;
+    iat?: number;
+    jti?: string;
+    token_type?: string;
+}
+
+/** GET/POST /env/tenants — confirmed against the live API. */
+interface Organization {
+    id: string;
+    slug: string;
+    name?: string;
+    description?: string | null;
+    environmentId?: string;
+    workspaceId?: string;
+    isDisabled?: boolean;
+    memberCount?: number;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** One of a user's tenant memberships, as embedded in `EnvironmentUser.tenantMemberships`. */
+interface TenantMembership {
+    tenantId: string;
+    tenantSlug: string;
+    tenantName: string;
+    tenantDisabled: boolean;
+    roles: string[];
+}
+/** Lightweight user shape returned by `introspect()`/`validate()`. */
+interface User {
+    id: string;
+    email: string;
+    username?: string;
+    /** Environment-level roles from the database-validated user profile. */
+    roles?: string[];
+    permissions?: string[];
+}
+interface RoleGrant {
+    role: string;
+    expiresAt?: string | null;
+}
+/**
+ * Full user record from the EnvironmentManagement plane
+ * (`environment.users.get()` / `.list()`), confirmed against the live API.
+ * `get()` returns every field below; `list()` returns a subset (no
+ * `failedLoginAttempts`, `lockedOutUntil`, `roleGrants`,
+ * `directPermissions`, `effectivePermissions`, `refreshTokens`,
+ * `tenantMemberships`, `totpConfirmedAt`, `emailOtpEnabledAt`,
+ * `remainingRecoveryCodes`, `disableReason`, `suspension`, `deleteReason`,
+ * `customFields` — and `suspendedUntil` instead of `suspension`).
+ */
+interface EnvironmentUser {
+    id: string;
+    email: string;
+    username?: string;
+    firstName?: string | null;
+    lastName?: string | null;
+    emailConfirmed: boolean;
+    isDisabled: boolean;
+    createdAt: string;
+    lastLoginAt?: string | null;
+    failedLoginAttempts?: number;
+    lockedOutUntil?: string | null;
+    roles: string[];
+    roleGrants?: RoleGrant[];
+    directPermissions?: string[];
+    effectivePermissions?: string[];
+    /** Confirmed shape unknown — empty in every response seen so far. */
+    refreshTokens?: unknown[];
+    tenantIds: string[];
+    tenantMemberships?: TenantMembership[];
+    /** Flattened role names across all tenant memberships (list() only). */
+    tenantRoles?: string[];
+    twoFactorMethods: string[];
+    totpConfirmedAt?: string | null;
+    emailOtpEnabledAt?: string | null;
+    remainingRecoveryCodes?: number;
+    disableReason?: string | null;
+    suspension?: unknown | null;
+    suspendedUntil?: string | null;
+    deletedAt?: string | null;
+    deleteReason?: string | null;
+    /** JSON-encoded string. */
+    customFields?: string;
+}
+/**
+ * POST /auth/validate — confirmed against the live API. The wire shape is
+ * `{ valid, reason, profile }`, not `{ user, organization }` as the
+ * OpenAPI schema (which didn't document response bodies) suggested.
+ * `profile` is `null` for machine tokens (there's no user behind them) and
+ * for tokens that fail validation.
+ */
+interface ValidateResult {
+    valid: boolean;
+    reason?: string | null;
+    user: User | null;
+}
+/**
+ * A role available within an environment or one of its tenants. Confirmed
+ * live: system roles carry no `id`/`description` (only `name` +
+ * `permissions`) — both are only populated for custom roles you create.
+ */
+interface Role {
+    id?: string | null;
+    name: string;
+    description?: string | null;
+    permissions: string[];
+}
+interface RoleInput {
+    name: string;
+    description?: string;
+    permissions?: string[];
+}
+/**
+ * GET /env/roles and GET /tenant/roles group results by origin instead of
+ * returning a flat array — confirmed live for the environment endpoint.
+ */
+interface RoleList {
+    custom: Role[];
+    system: Role[];
+}
+/** A permission entry as it appears nested under a role in `PermissionsByRole`. */
+interface Permission {
+    value: string;
+    description?: string | null;
+    /** Confirmed live: `null` for the built-in catalog: no separate id per entry. */
+    catalogId?: string | null;
+}
+/** A role entry as returned by GET /env/permissions, with its permissions nested. */
+interface RolePermissions {
+    roleId: string | null;
+    name: string;
+    description?: string | null;
+    isSystem: boolean;
+    permissions: Permission[];
+}
+/** GET /env/permissions — confirmed live: grouped by role, plus any orphaned entries. */
+interface PermissionsByRole {
+    roles: RolePermissions[];
+    orphans: Permission[];
+}
+/** GET /permissions/reserved — confirmed live: wrapped, not a bare string array. */
+interface ReservedPermissions {
+    namespace: string;
+    items: string[];
+}
+interface CreatePermissionInput {
+    value: string;
+    description?: string;
+    /** Attach the new permission to this role immediately. */
+    attachToRoleId?: string;
+}
+interface CreateOrganizationInput {
+    name: string;
+    slug: string;
+    description?: string;
+}
+interface UpdateOrganizationInput {
+    name: string;
+    description?: string;
+}
+interface CreateUserInput {
+    email: string;
+    username: string;
+    password: string;
+    emailConfirmed?: boolean;
+    roles?: string[];
+    /** Tenants (organizations) to add the user to on creation. */
+    tenantIds?: string[];
+}
+/** GET /env/audit — one audit-trail entry, confirmed against the live API. */
+interface AuditEvent {
+    id: string;
+    occurredAt: string;
+    eventType: string;
+    /** JSON-encoded string — `JSON.parse` it for the event-specific payload. */
+    payloadJson?: string;
+    workspaceId?: string;
+    environmentId?: string;
+    actorUserId?: string | null;
+    actorType?: string;
+    actorIp?: string;
+    userAgent?: string;
+    tenantId?: string | null;
+}
+/**
+ * GET /env/audit/login-activity. Not confirmed with a populated example
+ * live (the test environment had none) — assumed to share `AuditEvent`'s
+ * shape, since login activity is the same underlying audit-event stream
+ * filtered to sign-in events.
+ */
+type LoginActivity = AuditEvent;
+/**
+ * Envelope every `skip`/`take`-paginated list endpoint returns, confirmed
+ * live for `/env/users`, `/env/audit` and `/env/audit/login-activity`.
+ * Endpoints without `skip`/`take` params return a bare array instead.
+ */
+/** Tenant credential metadata. Listing never returns the secret. */
+interface TenantCredentialSummary {
+    id: string;
+    clientId: string;
+    description: string | null;
+    createdAt: string;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+    expiresAt: string | null;
+    isActive: boolean;
+    permissions: string[];
+}
+/** Input for a tenant machine credential. Requires at least one explicit permission. */
+interface CreateTenantCredentialInput {
+    description: string;
+    /** Number of days until the tenant credential expires. Omit for no automatic expiration. */
+    lifetimeDays?: number | null;
+    permissions: string[];
+}
+/** The plaintext secret is returned only when the credential is issued. */
+interface TenantCredentialIssued {
+    credentialId: string;
+    clientId: string;
+    clientSecret: string;
+    createdAt: string;
+    expiresAt: string | null;
+    permissions: string[];
+}
+/** OAuth 2.0 client-credentials pair minted in the Authyon console. */
+interface ClientCredentials {
+    clientId: string;
+    clientSecret: string;
+}
+/** Standard OAuth 2.0 client-credentials token response. */
+interface TokenResult {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    scope?: string;
+}
+interface JsonWebKeySet {
+    keys: Record<string, unknown>[];
+}
+interface OpenIdConfiguration {
+    issuer: string;
+    jwks_uri: string;
+    authorization_endpoint?: string;
+    token_endpoint?: string;
+    [key: string]: unknown;
+}
+interface AuthyonServerClientOptions {
+    /**
+     * Publishable environment key (`pk_live_...` / `pk_test_...`), sent as
+     * `X-Authyon-Environment`. Required on **every** call — it selects the
+     * environment (Test / Live) that a request applies to, independently of
+     * whichever bearer token authenticates it.
+     */
+    envKey?: string;
+    /**
+     * Environment-level OAuth client credentials (`ec_...` / secret), minted
+     * in the console. Required for everything under `environment.*` and
+     * `permissions.*` — the SDK exchanges them for a short-lived access token
+     * via `POST /env/oauth/token` and refreshes it transparently.
+     */
+    clientId?: string;
+    clientSecret?: string;
+    /** API origin. Defaults to `https://api.authyon.com`. */
+    baseUrl?: string;
+    /** Allow an HTTP `baseUrl`. Intended only for explicitly trusted local development. */
+    allowInsecureHttp?: boolean;
+    /** Maximum duration of each HTTP request. Defaults to 15 seconds; set to `0` to disable. */
+    timeoutMs?: number;
+    /** Custom HTTP adapter for tracing, mocks or an alternative HTTP stack. */
+    httpAdapter?: HttpAdapter;
+    /** Safe HTTP lifecycle logging. Disabled unless this option is provided with `enabled: true`. */
+    httpLogger?: HttpLoggerOptions;
+    /** @deprecated Prefer `httpAdapter: new FetchHttpAdapter(customFetch)`. */
+    fetch?: typeof fetch;
+}
+
+/** A token of the requested authentication plane, or a provider called for each request. */
+type AccessTokenSource = string | (() => string | Promise<string>);
+interface CredentialListOptions extends PaginationOptions {
+    search?: string;
+}
+/** scopes is an alias for permissions. Always supply an explicit, nonempty set. */
+type CredentialPermissionsInput = {
+    permissions: readonly string[];
+    scopes?: never;
+} | {
+    scopes: readonly string[];
+    permissions?: never;
+};
+type CreateCredentialInput = CredentialPermissionsInput & {
+    description?: string;
+    lifetimeDays?: number | null;
+};
+interface CredentialScope {
+    workspaceId: string;
+    environmentId: string;
+    tenantId?: string;
+}
+interface TenantManagementScope extends CredentialScope {
+    tenantId: string;
+}
+interface CredentialCreator {
+    id: string | null;
+    type: string;
+    displayName: string | null;
+}
+interface CredentialDetail extends TenantCredentialSummary {
+    createdBy: CredentialCreator | null;
+    updatedAt: string | null;
+    secretRotatedAt: string | null;
+    expiresAt: string | null;
+    ageSeconds: number;
+    /** Null while active; elapsed lifetime at revocation otherwise. */
+    lifetimeSeconds: number | null;
+    accessTokenLifetimeSeconds: number;
+}
+type WorkspaceRole = "admin" | "auditor";
+interface WorkspaceMember {
+    memberId: string | null;
+    userId: string;
+    email: string;
+    name: string;
+    role: string;
+    isOwner: boolean;
+    isSelf: boolean;
+    invitedByName: string | null;
+    joinedAt: string;
+    lastLoginAt: string | null;
+}
+interface WorkspaceInvite {
+    id: string;
+    email: string;
+    role: string;
+    invitedByName: string | null;
+    createdAt: string;
+    expiresAt: string;
+}
+interface WorkspaceTeam {
+    workspaceId: string;
+    workspaceName: string;
+    callerRole: string;
+    canManage: boolean;
+    members: WorkspaceMember[];
+    pendingInvites: WorkspaceInvite[];
+}
+interface InviteWorkspaceMemberInput {
+    email: string;
+    role: WorkspaceRole;
+}
+interface WorkspaceInviteIssued {
+    inviteId: string;
+    email: string;
+    role: string;
+    /** Sensitive bearer link returned at issuance. Do not log or persist in public storage. */
+    acceptUrl: string;
+    expiresAt: string;
+}
+interface WorkspaceInvitePreview {
+    workspaceName: string;
+    email: string;
+    role: string;
+    expiresAt: string;
+    requiresRegistration: boolean;
+}
+interface WorkspaceInviteAccepted {
+    workspaceId: string;
+    workspaceName: string;
+    role: string;
+    accountCreated: boolean;
+}
+interface AcceptWorkspaceInviteInput {
+    name?: string;
+    password?: string;
+}
+interface InviteTenantMemberInput {
+    email: string;
+    roles?: string[];
+}
+interface TenantMember {
+    userId: string;
+    email: string;
+    username: string;
+    roles: string[];
+    createdAt: string;
+    lastLoginAt: string | null;
+}
+type TenantMemberPage = Paged<TenantMember>;
+
+type QueryParams = object;
+
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+interface JsonRequestOptions {
+    method?: HttpMethod;
+    body?: unknown;
+    query?: QueryParams;
+    headers?: Record<string, string>;
+}
+
+type ManagementRequest = <T>(path: string, options?: JsonRequestOptions) => Promise<T>;
+
+/** Platform user administration. Never falls back to an environment machine token. */
+declare class PlatformScopedClient {
+    #private;
+    /** @hidden */
+    constructor(request: ManagementRequest, token: AccessTokenSource);
+    readonly credentials: {
+        list: (scope: CredentialScope, options?: CredentialListOptions) => Promise<Paged<TenantCredentialSummary>>;
+        get: (scope: CredentialScope, credentialId: string) => Promise<CredentialDetail>;
+        create: (scope: CredentialScope, input: CreateCredentialInput) => Promise<TenantCredentialIssued>;
+        updatePermissions: (scope: CredentialScope, credentialId: string, input: CredentialPermissionsInput) => Promise<void>;
+        updateScopes: (scope: CredentialScope, credentialId: string, scopes: readonly string[]) => Promise<void>;
+        /** Returns a new secret once. API may require an explicit step-up first. */
+        rotate: (scope: CredentialScope, credentialId: string) => Promise<TenantCredentialIssued>;
+        revoke: (scope: CredentialScope, credentialId: string) => Promise<void>;
+    };
+    readonly workspaces: {
+        team: (workspaceId: string) => Promise<WorkspaceTeam>;
+        members: {
+            invite: (workspaceId: string, input: InviteWorkspaceMemberInput) => Promise<WorkspaceInviteIssued>;
+            /** memberId comes from team.members; it is not the platform userId. */
+            remove: (workspaceId: string, memberId: string) => Promise<void>;
+            changeRole: (workspaceId: string, memberId: string, role: WorkspaceRole) => Promise<void>;
+        };
+        invites: {
+            create: (workspaceId: string, input: InviteWorkspaceMemberInput) => Promise<WorkspaceInviteIssued>;
+            revoke: (workspaceId: string, inviteId: string) => Promise<void>;
+        };
+    };
+    readonly tenants: {
+        members: {
+            list: (scope: TenantManagementScope, options?: PaginationOptions) => Promise<EnvironmentUser[]>;
+            add: (scope: TenantManagementScope, userId: string, roles?: string[]) => Promise<void>;
+            remove: (scope: TenantManagementScope, userId: string) => Promise<void>;
+        };
+    };
+    readonly auth: {
+        /** Explicitly confirms the current platform session; passwords are not retained. */
+        stepUp: (currentPassword: string) => Promise<void>;
+    };
+}
+/** End-user operations require a user token and the environment publishable key. */
+declare class UserScopedClient {
+    #private;
+    /** @hidden */
+    constructor(request: ManagementRequest, token: AccessTokenSource);
+    readonly tenants: {
+        members: {
+            list: (tenantId: string, options?: PaginationOptions) => Promise<TenantMemberPage>;
+            /** Adds an existing environment user by email; does not send an invitation email. */
+            invite: (tenantId: string, input: InviteTenantMemberInput) => Promise<TenantMember>;
+            remove: (tenantId: string, userId: string) => Promise<void>;
+        };
+    };
+}
+/** Anonymous invite endpoints: the invitation token itself authorizes these requests. */
+declare class WorkspaceInvitesClient {
+    #private;
+    /** @hidden */
+    constructor(request: ManagementRequest);
+    preview(token: string): Promise<WorkspaceInvitePreview>;
+    accept(token: string, input?: AcceptWorkspaceInviteInput): Promise<WorkspaceInviteAccepted>;
+}
+
+interface ClientRequestContext {
+    /** Real end-user IP, resolved only from infrastructure trusted by the application. */
+    clientIp?: string;
+}
+/** 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";
+interface AuthyonJwtClaims extends JWTPayload {
+    sub: string;
+    iss: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+    email?: string;
+    username?: string;
+    roles?: string[];
+    permissions?: string[];
+    scope?: string;
+}
+interface VerifiedAccessToken {
+    claims: AuthyonJwtClaims;
+    protectedHeader: JWSHeaderParameters;
+}
+interface JwksTokenVerifierOptions {
+    /** Exact trusted issuer from Authyon OpenID discovery. */
+    issuer: string;
+    /** Audience assigned to the API consuming this token. */
+    audience: string | string[];
+    /** Trusted HTTPS JWKS endpoint. Never derive this value from the token header. */
+    jwksUri?: string;
+    /** Static trusted keys for pinned or offline verification. */
+    jwks?: JSONWebKeySet;
+    algorithms?: readonly SafeJwtAlgorithm[];
+    acceptedTokenTypes?: readonly string[];
+    clockToleranceSeconds?: number;
+    maxTokenAgeSeconds?: number;
+    jwksTimeoutMs?: number;
+    jwksCacheMs?: number;
+    jwksCooldownMs?: number;
+}
+interface AuthyonJwksDiscoveryOptions extends Omit<JwksTokenVerifierOptions, "issuer" | "jwksUri" | "jwks"> {
+    /** Optional pin; discovery fails if Authyon advertises a different issuer. */
+    issuer?: string;
+    /** Override the client environment key used by the discovery endpoint. */
+    publishableKey?: string;
+}
+type TokenVerificationErrorCode = "token.invalid" | "token.expired" | "token.not_active" | "token.invalid_claims" | "token.invalid_signature" | "token.key_unavailable";
+declare class TokenVerificationError extends Error {
+    readonly code: TokenVerificationErrorCode;
+    constructor(code: TokenVerificationErrorCode, options?: {
+        cause?: unknown;
+    });
+}
+/** Secure, cached JWT signature and claims verifier backed by a trusted remote JWKS. */
+declare class JwksTokenVerifier {
+    private readonly options;
+    private readonly verifyKey;
+    private readonly algorithms;
+    private readonly acceptedTokenTypes;
+    constructor(options: JwksTokenVerifierOptions);
+    verifyAccessToken(token: string): Promise<VerifiedAccessToken>;
+}
+
+/**
+ * Server-side Authyon client: environment/tenant administration (OAuth
+ * client-credentials) plus access-token verification (publishable key).
+ * Never import this in browser code — client secrets must stay on your
+ * server.
+ */
+declare class AuthyonServerClient {
+    #private;
+    private readonly envKey?;
+    private readonly clientId?;
+    private readonly transport;
+    private readonly http;
+    private readonly environmentTokenProvider;
+    constructor(options?: AuthyonServerClientOptions);
+    private request;
+    /** Mints (and caches) an environment access token from `clientId`/`clientSecret`. */
+    private getEnvironmentAccessToken;
+    readonly discovery: {
+        /** GET /.well-known/jwks.json — the environment's public signing keys. */
+        jwks: (publishableKey?: string) => Promise<JsonWebKeySet>;
+        /** GET /.well-known/openid-configuration — OIDC discovery document. */
+        openidConfiguration: (publishableKey?: string) => Promise<OpenIdConfiguration>;
+    };
+    /** Discovers Authyon's trusted issuer/JWKS and creates a cached local access-token verifier. */
+    createJwksTokenVerifier(options: AuthyonJwksDiscoveryOptions): Promise<JwksTokenVerifier>;
+    /** POST /auth/introspect — lightweight token introspection (RFC 7662). */
+    introspect(token: string, context?: ClientRequestContext): Promise<IntrospectResult>;
+    /** POST /auth/validate — recommended: cross-checks DB state, catches revocation immediately. */
+    validate(token: string, context?: ClientRequestContext): Promise<ValidateResult>;
+    readonly environmentAuth: {
+        /** POST /env/oauth/token — exchanges environment client credentials for an access token. */
+        token: (credentials: ClientCredentials) => Promise<TokenResult>;
+    };
+    readonly tenantAuth: {
+        /** POST /tenant/oauth/token — exchanges a tenant's client credentials for a scoped access token. */
+        token: (credentials: ClientCredentials) => Promise<TokenResult>;
+    };
+    /**
+     * Scopes a client to a single tenant's OAuth credentials — mints and
+     * caches its access token independently of the environment plane. Use
+     * this for the `TenantManagement` endpoints (`/tenant/...`), which act on
+     * "the token's tenant" rather than one you pass by id.
+     */
+    tenant(credentials: ClientCredentials): TenantScopedClient;
+    /** Uses only the supplied platform-user access token. */
+    platform(token: AccessTokenSource): PlatformScopedClient;
+    /** Uses an end-user token; the configured environment key selects the environment. */
+    user(token: AccessTokenSource): UserScopedClient;
+    readonly workspaceInvites: WorkspaceInvitesClient;
+    readonly environment: {
+        users: {
+            /** GET /env/users — paginated list of users in the environment. */
+            list: (params?: {
+                search?: string;
+            } & PaginationOptions) => Promise<Paged<EnvironmentUser>>;
+            /** POST /env/users — create a user in the environment; returns only the new id. */
+            create: (input: CreateUserInput) => Promise<{
+                id: string;
+            }>;
+            /** GET /env/users/{userId} — fetch an environment user by id. */
+            get: (userId: string) => Promise<EnvironmentUser>;
+            /** POST /env/users/{userId}/roles — grant a role to an environment user. */
+            assignRole: (userId: string, role: string) => Promise<void>;
+            /** DELETE /env/users/{userId}/roles/{role} — revoke a role from an environment user. */
+            removeRole: (userId: string, role: string) => Promise<void>;
+            /** POST /env/users/{userId}/permissions — grant a direct permission to an environment user. */
+            grantPermission: (userId: string, permission: string) => Promise<void>;
+            /** DELETE /env/users/{userId}/permissions/{permission} — revoke a direct permission. */
+            revokePermission: (userId: string, permission: string) => Promise<void>;
+            /** POST /env/users/{userId}/unlock — clears an environment user's lockout. */
+            unlock: (userId: string, reason?: string) => Promise<void>;
+            /** POST /env/users/{userId}/password — sets a new password for the user. */
+            setPassword: (userId: string, newPassword: string, reason?: string) => Promise<void>;
+            /** POST /env/users/{userId}/sessions/revoke-all — revokes every session the user has. */
+            revokeSessions: (userId: string, reason?: string) => Promise<void>;
+            /** DELETE /env/users/{userId}/sessions/{sessionId} — revokes a single session. */
+            revokeSession: (userId: string, sessionId: string, reason?: string) => Promise<void>;
+            /** POST /env/users/{userId}/disable — bans the user indefinitely; revokes live sessions. */
+            disable: (userId: string, reason?: string) => Promise<void>;
+            /** POST /env/users/{userId}/enable — lifts a ban. */
+            enable: (userId: string, reason?: string) => Promise<void>;
+            /** POST /env/users/{userId}/suspend — blocks the user temporarily; clears itself after `durationMinutes`. */
+            suspend: (userId: string, durationMinutes: number, reason?: string) => Promise<void>;
+            /** POST /env/users/{userId}/unsuspend — lifts a suspension early. */
+            unsuspend: (userId: string, reason?: string) => Promise<void>;
+            /** POST /env/users/{userId}/tenants — adds an environment user to a tenant. */
+            assignTenant: (userId: string, tenantId: string, roles?: string[]) => Promise<void>;
+            /** DELETE /env/users/{userId}/tenants/{tenantId} — removes an environment user from a tenant. */
+            removeTenant: (userId: string, tenantId: string) => Promise<void>;
+        };
+        tenants: {
+            credentials: {
+                /** GET /env/tenants/{tenantId}/credentials. Returns metadata only, including revoked credentials. */
+                list: (tenantId: string) => Promise<TenantCredentialSummary[]>;
+                /** Paginated searchable listing. Prefer this over loading every credential. */
+                listPage: (tenantId: string, options?: CredentialListOptions) => Promise<Paged<TenantCredentialSummary>>;
+                get: (tenantId: string, credentialId: string) => Promise<CredentialDetail>;
+                /** Explicit scopes/permissions; only issuance returns the client secret. */
+                create: (tenantId: string, input: CreateTenantCredentialInput | CreateCredentialInput) => Promise<TenantCredentialIssued>;
+                /** Returns a new secret once while keeping the same client id. */
+                rotate: (tenantId: string, credentialId: string) => Promise<TenantCredentialIssued>;
+                updatePermissions: (tenantId: string, credentialId: string, input: CredentialPermissionsInput) => Promise<void>;
+                updateScopes: (tenantId: string, credentialId: string, scopes: readonly string[]) => Promise<void>;
+                revoke: (tenantId: string, credentialId: string) => Promise<void>;
+            };
+            /** GET /env/tenants — paginated, searchable list of tenants in the environment. */
+            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: (tenantId: string) => Promise<Organization>;
+            /** PUT /env/tenants/{tenantId} — update a tenant. */
+            update: (tenantId: string, input: UpdateOrganizationInput) => Promise<Organization>;
+            /** DELETE /env/tenants/{tenantId} — delete a tenant. */
+            delete: (tenantId: string) => Promise<void>;
+            members: {
+                /**
+                 * GET /env/tenants/{tenantId}/members — a tenant's members as full
+                 * user records. Confirmed live: a bare array (unlike
+                 * `environment.users.list()`, this one does NOT paginate despite
+                 * accepting `skip`/`take`), with the same shape
+                 * `environment.users.list()` items have.
+                 */
+                list: (tenantId: string, params?: PaginationOptions) => Promise<EnvironmentUser[]>;
+                /** POST /env/tenants/{tenantId}/members — add a member to a tenant. */
+                add: (tenantId: string, userId: string, roles?: string[]) => Promise<void>;
+                /** DELETE /env/tenants/{tenantId}/members/{userId} — remove a member from a tenant. */
+                remove: (tenantId: string, userId: string) => Promise<void>;
+                /** POST /env/tenants/{tenantId}/members/{userId}/roles — grant a tenant role to a member. */
+                assignRole: (tenantId: string, userId: string, role: string) => Promise<void>;
+                /** DELETE .../members/{userId}/roles/{role} — revoke a tenant role from a member. */
+                removeRole: (tenantId: string, userId: string, role: string) => Promise<void>;
+                /** POST .../members/{userId}/permissions — grant a permission to a tenant member. */
+                grantPermission: (tenantId: string, userId: string, permission: string) => Promise<void>;
+                /** DELETE .../members/{userId}/permissions/{permission} — revoke a permission from a tenant member. */
+                revokePermission: (tenantId: string, userId: string, permission: string) => Promise<void>;
+            };
+            roles: {
+                /** GET /env/tenants/{tenantId}/roles — list a tenant's roles. */
+                list: (tenantId: string) => Promise<Role[]>;
+                /** POST /env/tenants/{tenantId}/roles — create a tenant role. */
+                create: (tenantId: string, input: RoleInput) => Promise<Role>;
+                /** GET /env/tenants/{tenantId}/roles/{roleId} — fetch a tenant role by id. */
+                get: (tenantId: string, roleId: string) => Promise<Role>;
+                /** PUT /env/tenants/{tenantId}/roles/{roleId} — update a tenant role. */
+                update: (tenantId: string, roleId: string, input: RoleInput) => Promise<Role>;
+                /** DELETE /env/tenants/{tenantId}/roles/{roleId} — delete a tenant role. */
+                delete: (tenantId: string, roleId: string) => Promise<void>;
+            };
+        };
+        roles: {
+            /** GET /env/roles — environment-level roles, grouped into custom and system-defined. */
+            list: () => Promise<RoleList>;
+            /** POST /env/roles — create an environment-level role. */
+            create: (input: RoleInput) => Promise<Role>;
+            /** PUT /env/roles/{roleId} — update an environment-level role. */
+            update: (roleId: string, input: RoleInput) => Promise<Role>;
+            /** DELETE /env/roles/{roleId} — delete an environment-level role. */
+            delete: (roleId: string) => Promise<void>;
+        };
+        permissions: {
+            /** GET /env/permissions — environment-level permissions, grouped by the role they're attached to. */
+            list: () => Promise<PermissionsByRole>;
+            /** POST /env/permissions — create an environment-level permission. */
+            create: (input: CreatePermissionInput) => Promise<Permission>;
+            /** PUT /env/permissions/{permissionId} — update an environment-level permission. */
+            update: (permissionId: string, description?: string) => Promise<Permission>;
+            /** DELETE /env/permissions/{permissionId} — delete an environment-level permission. */
+            delete: (permissionId: string) => Promise<void>;
+            /** GET /permissions/reserved — reserved permission names you can't redefine. */
+            reserved: () => Promise<ReservedPermissions>;
+        };
+        audit: {
+            /** GET /env/audit — paginated list of the environment's audit events. */
+            list: (params?: PaginationOptions) => Promise<Paged<AuditEvent>>;
+            /** GET /env/audit/login-activity — paginated login activity in the environment. */
+            loginActivity: (params?: PaginationOptions) => Promise<Paged<LoginActivity>>;
+        };
+    };
+    readonly permissions: {
+        /** POST /users/{userId}/permissions — grant a permission directly to a user. */
+        grant: (userId: string, permission: string) => Promise<void>;
+        /** DELETE /users/{userId}/permissions/{permission} — revoke a permission from a user. */
+        revoke: (userId: string, permission: string) => Promise<void>;
+    };
+    /** @internal used by {@link TenantScopedClient} to share the base URL/fetch/error handling. */
+    _requestAsTenant<T>(accessToken: string, path: string, options?: {
+        method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+        body?: unknown;
+        query?: object;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+}
+/**
+ * Client scoped to a single tenant's OAuth credentials — every call acts on
+ * "the token's tenant" (`TenantManagement` endpoints), so there's no
+ * `tenantId` parameter to pass.
+ */
+declare class TenantScopedClient {
+    private readonly server;
+    private readonly tokenProvider;
+    constructor(server: AuthyonServerClient, credentials: ClientCredentials);
+    private getAccessToken;
+    private request;
+    readonly members: {
+        /**
+         * GET /tenant/members — members of the token's tenant.
+         *
+         * ⚠️ Inferred, not confirmed live (no tenant client credentials
+         * available to exchange for a scoped token) — assumed to share
+         * `/env/tenants/{id}/members`'s confirmed shape (bare array of full
+         * user records), since both are the "admin" member listing as opposed
+         * to `/auth/tenants/{id}/members`'s paginated, lightweight one.
+         */
+        list: (params?: PaginationOptions) => Promise<EnvironmentUser[]>;
+        /** POST /tenant/members — add a member to the token's tenant. */
+        add: (userId: string, roles?: string[]) => Promise<void>;
+        /** DELETE /tenant/members/{userId} — remove a member from the token's tenant. */
+        remove: (userId: string) => Promise<void>;
+        /** POST /tenant/members/{userId}/roles — grant a role to a member of the tenant. */
+        assignRole: (userId: string, role: string) => Promise<void>;
+        /** DELETE /tenant/members/{userId}/roles/{role} — revoke a role from a member of the tenant. */
+        removeRole: (userId: string, role: string) => Promise<void>;
+        /** POST /tenant/members/{userId}/permissions — grant a permission to a member of the tenant. */
+        grantPermission: (userId: string, permission: string) => Promise<void>;
+        /** DELETE .../permissions/{permission} — revoke a permission from a member of the tenant. */
+        revokePermission: (userId: string, permission: string) => Promise<void>;
+    };
+    readonly roles: {
+        /**
+         * GET /tenant/roles — roles in the token's tenant, grouped into custom
+         * and system-defined.
+         *
+         * ⚠️ Inferred, not confirmed live (the test environment had no tenants
+         * to exchange a scoped token for) — assumed to share `/env/roles`'
+         * grouped shape, since both operate on the same underlying role model.
+         */
+        list: () => Promise<RoleList>;
+        /** POST /tenant/roles — create a role in the tenant. */
+        create: (input: RoleInput) => Promise<Role>;
+        /** GET /tenant/roles/{roleId} — fetch a tenant role by id. */
+        get: (roleId: string) => Promise<Role>;
+        /** PUT /tenant/roles/{roleId} — update a role in the tenant. */
+        update: (roleId: string, input: RoleInput) => Promise<Role>;
+        /** DELETE /tenant/roles/{roleId} — delete a role in the tenant. */
+        delete: (roleId: string) => Promise<void>;
+    };
+}
+/** Convenience factory: `const authyon = createClient({ clientId, clientSecret })`. */
+declare function createClient(options?: AuthyonServerClientOptions): AuthyonServerClient;
+
+type AbilitySubject = string | Record<string, unknown>;
+type AbilityConditions = Record<string, unknown>;
+interface AbilityRule {
+    action: string | string[];
+    subject: string | string[];
+    inverted?: boolean;
+    conditions?: AbilityConditions;
+    fields?: string[];
+    reason?: string;
+}
+interface AuthyonPermissionSource {
+    permissions?: readonly string[] | null;
+    roles?: readonly string[] | null;
+    /** OAuth scopes are also accepted and interpreted as Authyon permissions. */
+    scope?: string | null;
+}
+interface AuthyonAbilityOptions {
+    rules?: readonly AbilityRule[];
+    /** Rules added when the source contains a matching Authyon role. */
+    roleRules?: Readonly<Record<string, readonly AbilityRule[]>>;
+    roles?: readonly string[] | null;
+    detectSubjectType?: (subject: Record<string, unknown>) => string;
+}
+type AbilityEvent = "updated";
+type AbilityListener = (rules: readonly AbilityRule[]) => void;
+/** Isomorphic, deny-by-default authorization engine backed by Authyon permissions. */
+declare class AuthyonAbility {
+    private readonly detectSubjectType;
+    private currentRules;
+    private readonly listeners;
+    constructor(rules?: readonly AbilityRule[], detectSubjectType?: (subject: Record<string, unknown>) => string);
+    get rules(): readonly AbilityRule[];
+    can(action: string, subject: AbilitySubject, field?: string): boolean;
+    cannot(action: string, subject: AbilitySubject, field?: string): boolean;
+    rulesFor(action: string, subject: string): readonly AbilityRule[];
+    update(rules: readonly AbilityRule[]): void;
+    on(event: AbilityEvent, listener: AbilityListener): () => void;
+}
+/** Fluent rule builder with CASL-like `can` and `cannot` methods. */
+declare class AuthyonAbilityBuilder {
+    readonly rules: AbilityRule[];
+    can(action: string | string[], subject: string | string[], conditions?: AbilityConditions, fields?: string[]): this;
+    cannot(action: string | string[], subject: string | string[], conditions?: AbilityConditions, fields?: string[], reason?: string): this;
+    build(options?: Pick<AuthyonAbilityOptions, "detectSubjectType">): AuthyonAbility;
+}
+/** Creates an ability from Authyon permissions, OAuth scope and optional role rules. */
+declare function createAuthyonAbility(source?: AuthyonPermissionSource, options?: AuthyonAbilityOptions): AuthyonAbility;
+/** Checks an Authyon permission string using the same wildcard rules as an ability. */
+declare function hasPermission(source: AuthyonPermissionSource | readonly string[], requiredPermission: string): boolean;
+/** Converts Authyon's `subject:action` permission strings to authorization rules. */
+declare function createAuthyonRules(source?: AuthyonPermissionSource, options?: AuthyonAbilityOptions): AbilityRule[];
+
+interface AbilityRequirement {
+    action: string;
+    subject: AbilitySubject;
+    field?: string;
+}
+interface AuthorizationContext {
+    token: string;
+    userId?: string;
+    ability: AuthyonAbility;
+    permissions: readonly string[];
+    roles: readonly string[];
+}
+interface AuthorizationOptions extends AuthyonAbilityOptions {
+    requirement?: AbilityRequirement;
+    /** Uses database-backed validation by default; introspection can be selected when desired. */
+    verification?: "validate" | "introspect" | "jwks";
+    /** Required for local JWKS verification. Create once and reuse its key cache. */
+    jwksVerifier?: JwksTokenVerifier;
+    /** Real end-user IP, obtained from trusted application infrastructure. */
+    clientIp?: string;
+}
+declare class AuthorizationError extends Error {
+    readonly status: 401 | 403 | 503;
+    readonly code: "authorization.unauthenticated" | "authorization.forbidden" | "authorization.unavailable";
+    constructor(status: 401 | 403 | 503, code: "authorization.unauthenticated" | "authorization.forbidden" | "authorization.unavailable", message: string);
+}
+/** Validates a bearer token and creates an Authyon-backed ability for server runtimes. */
+declare function authorizeToken(client: AuthyonServerClient, token: string, options?: AuthorizationOptions): Promise<AuthorizationContext>;
+/** Works with Web Request objects used by Next.js Route Handlers and other Fetch runtimes. */
+declare function authorizeRequest(client: AuthyonServerClient, request: Pick<Request, "headers">, options?: RequestAuthorizationOptions): Promise<AuthorizationContext>;
+interface RequestAuthorizationOptions extends AuthorizationOptions {
+    /** Platform-aware resolver. Only read headers that your trusted proxy overwrites. */
+    resolveClientIp?: (request: Pick<Request, "headers">) => string | undefined;
+}
+interface ExpressRequestLike {
+    headers: Record<string, string | string[] | undefined>;
+    ip?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+    authyon?: AuthorizationContext;
+}
+interface ExpressResponseLike {
+    status(code: number): ExpressResponseLike;
+    json(body: unknown): unknown;
+}
+type ExpressNext = (error?: unknown) => void;
+interface ExpressAuthorizationMiddlewareOptions extends AuthorizationOptions {
+    /** Property assigned to the request. Defaults to `authyon`. */
+    requestProperty?: string;
+    /** Pass authorization errors to Express error middleware instead of writing a JSON response. */
+    passErrorsToNext?: boolean;
+    /** Trust Express's proxy-aware `request.ip`. Disabled by default. */
+    trustProxy?: boolean;
+    /** Overrides all built-in IP resolution; return only a trusted, single client IP. */
+    resolveClientIp?: (request: ExpressRequestLike) => string | undefined;
+}
+/** Dependency-free middleware compatible with Express and similar Connect frameworks. */
+declare function createExpressAuthorizationMiddleware(client: AuthyonServerClient, options?: ExpressAuthorizationMiddlewareOptions): (request: ExpressRequestLike & Record<string, unknown>, response: ExpressResponseLike, next: ExpressNext) => Promise<void>;
+/** Converts an authorization error into a Fetch Response suitable for Next.js. */
+declare function createAuthorizationErrorResponse(error: unknown): Response;
+
+export { type Organization as $, AuthyonServerClient as A, type CredentialCreator as B, type ClientCredentials as C, type CredentialDetail as D, type CredentialListOptions as E, type CredentialPermissionsInput as F, type CredentialScope as G, type HttpAdapter as H, type EnvironmentUser as I, type ExpressAuthorizationMiddlewareOptions as J, type ExpressNext as K, type ExpressRequestLike as L, type ExpressResponseLike as M, FetchHttpAdapter as N, type HttpAdapterRequest as O, type HttpLogEvent as P, type HttpLogger as Q, type RequestAuthorizationOptions as R, type IntrospectResult as S, type InviteTenantMemberInput as T, type InviteWorkspaceMemberInput as U, type JsonWebKeySet as V, JwksTokenVerifier as W, type JwksTokenVerifierOptions as X, LoggingHttpAdapter as Y, type LoginActivity as Z, type OpenIdConfiguration as _, type AbilitySubject as a, type Paged as a0, type PaginationOptions as a1, type Permission as a2, type PermissionsByRole as a3, PlatformScopedClient as a4, type ReservedPermissions as a5, type Role as a6, type RoleGrant as a7, type RoleInput as a8, type RoleList as a9, authorizeToken as aA, createAuthorizationErrorResponse as aB, createAuthyonAbility as aC, createAuthyonRules as aD, createClient as aE, createExpressAuthorizationMiddleware as aF, hasPermission as aG, normalizeClientIp as aH, type RolePermissions as aa, type SafeJwtAlgorithm as ab, type TenantCredentialIssued as ac, type TenantCredentialSummary as ad, type TenantManagementScope as ae, type TenantMember as af, type TenantMemberPage as ag, type TenantMembership as ah, TenantScopedClient as ai, type TokenResult as aj, TokenVerificationError as ak, type TokenVerificationErrorCode as al, type UpdateOrganizationInput as am, type User as an, UserScopedClient as ao, type ValidateResult as ap, type VerifiedAccessToken as aq, type WorkspaceInvite as ar, type WorkspaceInviteAccepted as as, type WorkspaceInviteIssued as at, type WorkspaceInvitePreview as au, WorkspaceInvitesClient as av, type WorkspaceMember as aw, type WorkspaceRole as ax, type WorkspaceTeam as ay, authorizeRequest as az, AuthorizationError as b, type HttpLoggerOptions as c, type AbilityConditions as d, type AbilityEvent as e, type AbilityListener as f, type AbilityRequirement as g, type AbilityRule as h, type AcceptWorkspaceInviteInput as i, type AccessTokenSource as j, type AuditEvent as k, type AuthorizationContext as l, type AuthorizationOptions as m, AuthyonAbility as n, AuthyonAbilityBuilder as o, type AuthyonAbilityOptions as p, type AuthyonJwksDiscoveryOptions as q, type AuthyonJwtClaims as r, type AuthyonPermissionSource as s, type AuthyonServerClientOptions as t, type ClientRequestContext as u, type CreateCredentialInput as v, type CreateOrganizationInput as w, type CreatePermissionInput as x, type CreateTenantCredentialInput as y, type CreateUserInput as z };