@authyon/server 0.2.0-beta.0 → 0.2.0-beta.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MutualPay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,6 +2,67 @@
 
 SDK server-side para o [Authyon](https://authyon.com) — administração de ambiente/tenants (OAuth client-credentials) e verificação de access token (publishable key). Nunca importe este pacote em código de browser.
 
+## Instalação da beta
+
+```bash
+npm install --save-exact @authyon/server@0.2.0-beta.4
+```
+
+Durante a beta, `npm install @authyon/server@beta` acompanha o prerelease mais recente. Fixar a versão exata é recomendado para builds reproduzíveis.
+
+O pacote possui uma condição de exportação `browser` que falha imediatamente se um bundler tentar incluí-lo no frontend. URLs remotas exigem HTTPS e cada request tem timeout padrão de 15 segundos, configurável por `timeoutMs`.
+
+O client aceita o mesmo contrato `HttpAdapter` de `@authyon/auth`, útil para tracing, mocks e stacks HTTP próprias:
+
+```ts
+import { createClient, FetchHttpAdapter } from "@authyon/server";
+
+const authyon = createClient({
+  envKey: process.env.AUTHYON_ENV_KEY,
+  httpAdapter: new FetchHttpAdapter(globalThis.fetch),
+});
+```
+
+Quando houver credenciais, adapter e observabilidade, o builder mantém cada etapa explícita:
+
+```ts
+const authyon = new AuthyonServerClientBuilder()
+  .withEnvironmentKey(process.env.AUTHYON_ENV_KEY)
+  .withEnvironmentCredentials(process.env.AUTHYON_CLIENT_ID, process.env.AUTHYON_CLIENT_SECRET)
+  .withHttpLogger(httpLogger)
+  .build();
+```
+
+O client também aceita `httpLogger: { enabled, logger? }`. A configuração é mutável, portanto `enabled` pode ser alterado em runtime. Os eventos não incluem headers, bodies nem valores de query string, e erros do logger nunca interrompem requests.
+
+`AuthyonError`, `ErrorCodes` e `error.interpret()` também são exportados por este pacote. Use `category`, `action`, `retryable`, `retryAfter` e `requestId` para implementar middleware e observabilidade sem comparar mensagens humanas.
+
+## Sessão web no BFF (código ainda não publicado)
+
+O novo entrypoint `@authyon/server/bff` oferece login, 2FA, sessão HttpOnly,
+renovação sob demanda, logout e troca de organização. Os tokens ficam no servidor,
+com adaptador Redis cifrado e compare-and-swap para concorrência entre instâncias.
+Reutiliza os endpoints existentes e o cliente de validação server-side.
+
+Veja [contrato e integração](../../docs/bff.md) e [análise/plano](../../docs/bff-session-plan.md).
+O entrypoint padrão e `@authyon/server/next` mantêm seu comportamento anterior;
+a adoção do transporte BFF pelo consumidor é explícita.
+
+## Validação local com JWKS
+
+Para APIs de alto volume, crie uma vez um verificador com discovery automático:
+
+```ts
+const verifier = await authyon.createJwksTokenVerifier({
+  audience: process.env.AUTHYON_AUDIENCE,
+  algorithms: ["RS256"],
+});
+
+const { claims } = await verifier.verifyAccessToken(token);
+```
+
+Ele valida assinatura, algoritmo, issuer, audience, tipo e claims temporais, com cache e rotação de chaves. Use `verification: "jwks"` em `authorizeRequest()` ou `createExpressAuthorizationMiddleware()`. Para ações sensíveis que precisam detectar revogação imediatamente, mantenha o padrão `validate`.
+
 ## Instalação
 
 ```bash
@@ -35,7 +96,7 @@ const { active, sub } = await authyon.introspect(token); // leve
 const { user, organization } = await authyon.validate(token); // recomendado — cross-checa revogação
 ```
 
-Veja [`examples/token-verification.ts`](./examples/token-verification.ts) para um middleware completo.
+Veja [`examples/tokenVerification.ts`](./examples/tokenVerification.ts) para um middleware completo.
 
 ## Administração de ambiente (`environment.*`)
 
@@ -43,6 +104,11 @@ Usa as credenciais de ambiente (`clientId`/`clientSecret`) automaticamente — o
 
 ```ts
 const org = await authyon.environment.tenants.create({ name: "Acme", slug: "acme" });
+const tenants = await authyon.environment.tenants.list({
+  search: "acme",
+  skip: 0,
+  take: 20,
+});
 await authyon.environment.tenants.members.add(org.id, userId, ["owner"]);
 await authyon.environment.tenants.members.assignRole(org.id, userId, "billing-admin");
 await authyon.environment.tenants.members.remove(org.id, userId);
@@ -52,10 +118,79 @@ await authyon.environment.roles.create({ name: "support", permissions: ["tickets
 await authyon.environment.audit.list({ take: 50 });
 ```
 
-Veja [`examples/organization-membership.ts`](./examples/organization-membership.ts) para o fluxo completo, incluindo as rotas de backend que o `@authyon/auth` chamaria.
+Veja [`examples/organizationMembership.ts`](./examples/organizationMembership.ts) para o fluxo completo, incluindo as rotas de backend que o `@authyon/auth` chamaria.
 
 Namespaces disponíveis: `environment.users`, `environment.tenants` (com `.members` e `.roles` aninhados), `environment.roles`, `environment.permissions`, `environment.audit`.
 
+## Autorização local
+
+`createAuthyonAbility()` transforma o resultado de `validate()`, `introspect()` ou qualquer objeto com `permissions`, `roles` e `scope` em verificações locais no estilo CASL:
+
+```ts
+import { createAuthyonAbility } from "@authyon/server";
+
+const identity = await authyon.validate(token);
+const ability = createAuthyonAbility(identity);
+
+if (!ability.can("read", "reports")) {
+  throw new Error("Forbidden");
+}
+```
+
+Regras condicionais e de domínio podem ser acrescentadas no segundo argumento. O mecanismo é deny-by-default e não substitui a validação do token nem a autorização aplicada pela API.
+
+### Next.js Server Side
+
+Em Route Handlers, Server Actions ou SSR, mantenha `@authyon/server` em um módulo marcado com `server-only`:
+
+```ts
+import "server-only";
+import { createAuthorizationErrorResponse, authorizeRequest, createClient } from "@authyon/server";
+
+const authyon = createClient({
+  envKey: process.env.AUTHYON_ENV_KEY,
+  clientId: process.env.AUTHYON_CLIENT_ID,
+  clientSecret: process.env.AUTHYON_CLIENT_SECRET,
+});
+
+export async function GET(request: Request) {
+  try {
+    const auth = await authorizeRequest(authyon, request, {
+      requirement: { action: "read", subject: "reports" },
+    });
+    return Response.json({ userId: auth.userId });
+  } catch (error) {
+    return createAuthorizationErrorResponse(error);
+  }
+}
+```
+
+### Express e frameworks Connect
+
+O middleware não adiciona Express como dependência e disponibiliza `request.authyon`:
+
+```ts
+import { createExpressAuthorizationMiddleware } from "@authyon/server";
+
+app.get(
+  "/reports",
+  createExpressAuthorizationMiddleware(authyon, {
+    requirement: { action: "read", subject: "reports" },
+  }),
+  (request, response) => response.json({ userId: request.authyon.userId }),
+);
+```
+
+Use `authorizeToken()` em NestJS, Fastify, Hono, tRPC ou integrações próprias. `passErrorsToNext: true` encaminha erros ao middleware de erros do Express.
+
+### IP real do cliente
+
+Chamadas server-side propagam `clientIp` em `X-Forwarded-For`. O middleware Express usa o IP do socket por padrão; atrás de um proxy confiável, configure o próprio Express e use `trustProxy: true`. Para Next.js, passe `resolveClientIp` ao `authorizeRequest()` lendo somente headers que sua infraestrutura sobrescreve. Não confie cegamente em `X-Forwarded-For` recebido da internet.
+
+```ts
+await authyon.validate(token, { clientIp: "203.0.113.10" });
+```
+
 ## Administração por tenant (`tenant()`)
 
 As credenciais de um tenant são próprias dele — use `authyon.tenant(credentials)` para obter um cliente escopado, que minta e cacheia seu próprio token via `POST /tenant/oauth/token`:
@@ -63,11 +198,30 @@ As credenciais de um tenant são próprias dele — use `authyon.tenant(credenti
 ```ts
 const acme = authyon.tenant({ clientId: acmeClientId, clientSecret: acmeClientSecret });
 
+const identity = await acme.validate(); // POST /tenant/auth/validate
 await acme.members.list();
 await acme.members.add(userId, ["member"]);
 await acme.roles.create({ name: "viewer", permissions: ["reports:read"] });
 ```
 
+`validate()` confirma o bearer tenant-client atual e devolve `tenantId`,
+`credentialId`, `clientId` e as permissões vigentes da credencial. A resposta
+vem do backend depois da checagem de revogação, rotação de secret e tenant
+desabilitado; não confie só na claim `scope` quando precisar do estado atual.
+
+Em middleware, quando você já recebeu o bearer tenant-client na requisição, não
+use `clientId`/`clientSecret`; valide o token diretamente:
+
+```ts
+const validation = await authyon.tenantAuth.validate(tenantBearerToken, {
+  clientIp: "203.0.113.10",
+});
+
+if (!validation.valid) {
+  // responda 401
+}
+```
+
 ## Descoberta
 
 ```ts
@@ -82,3 +236,168 @@ npm install
 npm run build      # dist/ (ESM + CJS + .d.ts via tsup)
 npm run typecheck
 ```
+
+### Emitir uma credencial de integração do tenant
+
+Requer o endpoint `POST /env/tenants/{tenantId}/credentials` no backend Authyon
+e uma credencial de ambiente com `authyon:credentials:manage`.
+
+```ts
+const credential = await authyon.environment.tenants.credentials.create(tenantId, {
+  description: "ERP financeiro",
+  permissions: ["monkeypay:transactions:read"],
+});
+// Entregue clientId e clientSecret ao operador: o segredo só é retornado uma vez.
+```
+
+As permissões são explícitas e pertencem à integração; não há concessão automática de acesso total.
+
+## Credenciais: paginação, busca e detalhe
+
+```ts
+const page = await authyon.environment.tenants.credentials.listPage(tenantId, {
+  search: "transactions",
+  skip: 0,
+  take: 25,
+});
+const detail = await authyon.environment.tenants.credentials.get(tenantId, credentialId);
+```
+
+`page` contém `data`, `perPage` (número da página, começando em 1), `pageSize`,
+`total`, `pages`, `hasNext` e `hasPrev`. `take` aceita 1–100 (padrão da API: 25),
+`skip` é um deslocamento a partir de zero e `search` aceita até 200 caracteres.
+A API pesquisa clientId, descrição e permissões antes de paginar.
+
+O método existente `credentials.list(tenantId)` continua retornando um array:
+aceita a resposta antiga e percorre todas as páginas da API atual. Prefira
+`listPage` para tabelas ou grandes volumes. A leitura completa detecta páginas
+sobrepostas/sem progresso e tem limite de 1.000 páginas; alterações concorrentes
+podem exigir reiniciar a leitura, pois a API usa paginação por deslocamento.
+
+O detalhe contém `permissions`, `createdBy` (`id`, `type`, `displayName`),
+`createdAt`, `updatedAt`, `lastUsedAt`, `secretRotatedAt`, `revokedAt`, `isActive`,
+`expiresAt`, `ageSeconds`, `lifetimeSeconds` e `accessTokenLifetimeSeconds`.
+Listagem e detalhe projetam somente campos permitidos, sem segredo ou hash.
+Registros antigos podem ter autor e atualização nulos. A credencial atual não
+expira automaticamente: `expiresAt` é nulo; `lifetimeSeconds` é nulo enquanto
+ativa e representa sua duração até a revogação quando revogada. A validade do
+access token é separada (atualmente 1.800 segundos).
+
+## Scopes e ciclo de vida das credenciais
+
+`scopes` é um alias de `permissions` na criação/atualização. Use somente um dos
+campos, com uma lista explícita no formato `namespace:resource:action`. O SDK
+normaliza espaços, caixa e duplicatas; não concede permissões automaticamente.
+A API continua responsável pela autorização. O contrato antigo
+`CreateTenantCredentialInput` e chamadas usando `permissions` são preservados.
+
+```ts
+const issued = await authyon.environment.tenants.credentials.create(tenantId, {
+  description: "ERP financeiro",
+  scopes: ["monkeypay:transactions:read"],
+});
+// Armazene issued.clientSecret no gerenciador de segredos. Não registre a resposta.
+
+// Token de um usuário da plataforma. Pode ser um callback assíncrono que
+// consulta a sessão atual a cada operação, sem compartilhar tokens entre usuários.
+const platform = authyon.platform(() => getCurrentPlatformAccessToken());
+const scope = { workspaceId, environmentId, tenantId };
+await platform.credentials.list(scope, { search: "ERP", skip: 0, take: 25 });
+await platform.credentials.get(scope, credentialId);
+await platform.credentials.create(scope, {
+  description: "Leitura",
+  permissions: ["monkeypay:transactions:read"],
+});
+await platform.credentials.updateScopes(scope, credentialId, ["monkeypay:transactions:read"]);
+await platform.credentials.updatePermissions(scope, credentialId, {
+  permissions: ["monkeypay:transactions:read"],
+});
+const rotated = await platform.credentials.rotate(scope, credentialId);
+await platform.credentials.revoke(scope, credentialId);
+```
+
+Omita `tenantId` de `scope` para gerenciar credenciais do ambiente. Criação e
+rotação retornam o segredo uma única vez. Alterar permissões substitui a lista
+completa. A concessão OAuth continua recebendo apenas `clientId`/`clientSecret`;
+`scopes` não é um parâmetro de redução de acesso na troca de token.
+
+Os endpoints `/env` oferecem criação, listagem e detalhe de credenciais do
+tenant. Atualização, rotação e revogação usam os endpoints `/platform` com
+**token de usuário da plataforma**, sem fallback para credenciais de máquina.
+Se a API exigir `auth.step_up_required`, solicite confirmação de senha na sua
+aplicação e chame explicitamente `platform.auth.stepUp(currentPassword)` antes
+de tentar a operação novamente. O SDK não repete mutações automaticamente.
+
+## Convites e remoção de acesso
+
+### Workspace
+
+```ts
+const team = await platform.workspaces.team(workspaceId);
+const invite = await platform.workspaces.members.invite(workspaceId, {
+  email: "pessoa@example.com",
+  role: "auditor", // ou "admin", sempre explícito
+});
+// invite.acceptUrl é sensível: entregue somente à pessoa convidada.
+await platform.workspaces.invites.revoke(workspaceId, invite.inviteId);
+await platform.workspaces.members.changeRole(workspaceId, memberId, "auditor");
+await platform.workspaces.members.remove(workspaceId, memberId);
+```
+
+`memberId` vem de `team.members`, e não é `userId`. O proprietário tem
+`memberId: null`; a API protege proprietário, acesso próprio e permissões de
+administração. `workspaces.invites.create` é um alias para `members.invite`.
+Convites pendentes ficam em `team.pendingInvites`; revogar o convite invalida o
+link. Para retirar acesso após aceite, remova o membro.
+
+A pessoa convidada pode consultar/aceitar o convite por uma rota server-side:
+
+```ts
+const preview = await authyon.workspaceInvites.preview(invitationToken);
+await authyon.workspaceInvites.accept(invitationToken, {
+  name: "Pessoa",
+  password: registrationPassword,
+});
+```
+
+Esses métodos não enviam token de usuário nem credenciais de ambiente. Nome e
+senha são necessários quando `preview.requiresRegistration` for verdadeiro;
+para uma conta existente, use `accept(invitationToken)`.
+
+### Tenant
+
+```ts
+const user = authyon.user(() => getCurrentUserAccessToken());
+await user.tenants.members.invite(tenantId, {
+  email: "pessoa@example.com",
+  roles: ["reader"],
+});
+await user.tenants.members.list(tenantId, { skip: 0, take: 25 });
+await user.tenants.members.remove(tenantId, userId);
+
+// Administração por máquina: adicione uma conta existente por ID.
+await authyon.environment.tenants.members.add(tenantId, userId, ["reader"]);
+await authyon.environment.tenants.members.remove(tenantId, userId);
+// Os métodos tenant(credentials).members.add/remove existentes continuam disponíveis.
+// Administração com sessão da plataforma:
+await platform.tenants.members.add(scope, userId, ["reader"]);
+await platform.tenants.members.remove(scope, userId);
+```
+
+Configure `envKey` para `user()`. O convite de tenant associa um usuário já
+cadastrado no ambiente pelo e-mail; não cria conta e não envia link por e-mail.
+A API exige associação/permissões do usuário chamador. No browser, os métodos
+existentes `@authyon/auth` → `organization.members.invite/remove` continuam
+atendendo esse fluxo. Nunca importe `@authyon/server` no browser.
+
+## Compatibilidade e segurança do transporte
+
+Os métodos anteriores permanecem disponíveis. As novas chamadas exigem os
+endpoints atuais da API e a migração `ClientCredentialMetadata` para metadados
+persistidos. O SDK não altera o banco nem publica uma versão automaticamente.
+
+O adaptador Fetch agora rejeita redirects para evitar reenviar tokens/segredos;
+configure a URL final HTTPS da API. Adaptadores HTTP personalizados devem manter
+essa política. Os logs internos omitem corpos/headers e ocultam tokens de
+convite presentes no caminho. A auditoria de operações permanece na API; o SDK
+não gera eventos duplicados ao consultar listagens de auditoria.

package/dist/authorization-CeP_GqT7.d.cts

@@ -0,0 +1,129 @@
+import { x as JwksTokenVerifier, A as AuthyonServerClient } from './authyonServerClient-D-DxoL30.cjs';
+
+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;
+}
+/** A declarative group of permissions evaluated against an Authyon permission source. */
+interface PermissionGroup {
+    /** Permissions that must all be granted. */
+    allOf?: readonly string[];
+    /** Permissions where at least one must be granted. */
+    anyOf?: readonly string[];
+}
+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;
+/**
+ * Checks a permission group using Authyon's standard permission and wildcard rules.
+ * 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. */
+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 AbilitySubject as A, type ExpressAuthorizationMiddlewareOptions as E, type PermissionGroup as P, type RequestAuthorizationOptions as R, AuthorizationError as a, type AbilityConditions as b, type AbilityEvent as c, type AbilityListener as d, type AbilityRequirement as e, type AbilityRule as f, type AuthorizationContext as g, type AuthorizationOptions as h, AuthyonAbility as i, AuthyonAbilityBuilder as j, type AuthyonAbilityOptions as k, type AuthyonPermissionSource as l, type ExpressNext as m, type ExpressRequestLike as n, type ExpressResponseLike as o, authorizeRequest as p, authorizeToken as q, createAuthorizationErrorResponse as r, createAuthyonAbility as s, createAuthyonRules as t, createExpressAuthorizationMiddleware as u, hasPermission as v, hasPermissionGroup as w };

package/dist/authorization-D_A6L9Ie.d.ts

@@ -0,0 +1,129 @@
+import { x as JwksTokenVerifier, A as AuthyonServerClient } from './authyonServerClient-D-DxoL30.js';
+
+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;
+}
+/** A declarative group of permissions evaluated against an Authyon permission source. */
+interface PermissionGroup {
+    /** Permissions that must all be granted. */
+    allOf?: readonly string[];
+    /** Permissions where at least one must be granted. */
+    anyOf?: readonly string[];
+}
+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;
+/**
+ * Checks a permission group using Authyon's standard permission and wildcard rules.
+ * 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. */
+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 AbilitySubject as A, type ExpressAuthorizationMiddlewareOptions as E, type PermissionGroup as P, type RequestAuthorizationOptions as R, AuthorizationError as a, type AbilityConditions as b, type AbilityEvent as c, type AbilityListener as d, type AbilityRequirement as e, type AbilityRule as f, type AuthorizationContext as g, type AuthorizationOptions as h, AuthyonAbility as i, AuthyonAbilityBuilder as j, type AuthyonAbilityOptions as k, type AuthyonPermissionSource as l, type ExpressNext as m, type ExpressRequestLike as n, type ExpressResponseLike as o, authorizeRequest as p, authorizeToken as q, createAuthorizationErrorResponse as r, createAuthyonAbility as s, createAuthyonRules as t, createExpressAuthorizationMiddleware as u, hasPermission as v, hasPermissionGroup as w };