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

package/README.md

@@ -5,7 +5,7 @@ SDK server-side para o [Authyon](https://authyon.com) — administração de amb
 ## Instalação da beta
 
 ```bash
-npm install --save-exact @authyon/server@0.2.0-beta.2
+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.
@@ -37,6 +37,17 @@ O client também aceita `httpLogger: { enabled, logger? }`. A configuração é
 
 `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:
@@ -109,7 +120,7 @@ await authyon.environment.audit.list({ take: 50 });
 
 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`.
+Namespaces disponíveis: `environment.users`, `environment.tenants` (com `.members` e `.roles` aninhados), `environment.roles`, `environment.permissions`, `environment.audit`. OTP e aprovações ficam em `security` (veja abaixo).
 
 ## Autorização local
 
@@ -180,6 +191,38 @@ Chamadas server-side propagam `clientIp` em `X-Forwarded-For`. O middleware Expr
 await authyon.validate(token, { clientIp: "203.0.113.10" });
 ```
 
+## Segurança (`security.*`)
+
+OTP e aprovações ficam agrupados em `authyon.security`. Exige uma credencial de ambiente
+com o escopo `authyon:otp:verify` (para `security.otp`) e/ou `authyon:financial:authorize`
+(para `security.approvals`). Guia completo:
+[`docs/security-otp-approvals.md`](../../docs/security-otp-approvals.md).
+
+```ts
+// security.otp — só validar o código do app autenticador
+const result = await authyon.security.otp.check(customerId, code);
+if (!result.valid) console.log(result.attemptsRemaining, result.sessionsRevoked);
+
+// security.approvals — aprovação presa a um payload livre e de uso único
+const { id } = await authyon.security.approvals.create({
+  subjectId: customerId,
+  payload: { type: "pix", amount: 150.5, to: "maria@example.com" },
+});
+// ...cliente confirma com @authyon/auth → security.approvals.confirm
+const { payload } = await authyon.security.approvals.consume(id);
+```
+
+| Método                               | Endpoint                                |
+| ------------------------------------ | --------------------------------------- |
+| `security.otp.check(userId, code)`   | `POST /env/users/{userId}/otp/verify`   |
+| `security.approvals.create(input)`   | `POST /env/authorizations`              |
+| `security.approvals.get(id)`         | `GET /env/authorizations/{id}`          |
+| `security.approvals.consume(id, p?)` | `POST /env/authorizations/{id}/consume` |
+
+Cada código vale uma vez; 3 erros seguidos deslogam o usuário de todos os dispositivos e
+5 bloqueiam a verificação por 15 minutos. Se o seu servidor guarda o token do cliente
+(BFF), o lado do cliente está em `authyon.user(accessToken).security.approvals`.
+
 ## 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`:
@@ -187,11 +230,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
@@ -206,3 +268,239 @@ 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`, `page` (a página atual, começando em 1), `perPage` (o
+limite por página), `total`, `pages`, `hasNext` e `hasPrev`. Até a API de
+2026-10-21 os dois campos se chamavam `perPage` (página) e `pageSize`
+(limite), nessa ordem trocada. `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.
+
+await authyon.environment.tenants.credentials.listPage(tenantId, {
+  search: "ERP",
+  skip: 0,
+  take: 25,
+});
+await authyon.environment.tenants.credentials.get(tenantId, credentialId);
+await authyon.environment.tenants.credentials.create(tenantId, {
+  description: "Leitura",
+  permissions: ["monkeypay:transactions:read"],
+});
+await authyon.environment.tenants.credentials.updateScopes(tenantId, credentialId, [
+  "monkeypay:transactions:read",
+]);
+await authyon.environment.tenants.credentials.updatePermissions(tenantId, credentialId, {
+  permissions: ["monkeypay:transactions:read"],
+});
+const rotated = await authyon.environment.tenants.credentials.rotate(tenantId, credentialId);
+await authyon.environment.tenants.credentials.revoke(tenantId, credentialId);
+```
+
+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.
+
+Todas as operações usam os endpoints externos `/env` com a credencial de
+ambiente configurada no cliente. O SDK não repete mutações automaticamente.
+
+## Filtros do tenant
+
+`search` é um substring só, ORado entre nome, slug, descrição e os dois metadata.
+Quando mais de uma condição precisa valer — `kind IN (...) AND cnpj IN (...)` — use
+`filter`, que roda dentro da consulta e por isso continua paginando:
+
+```ts
+import { tenantFilter } from "@authyon/server";
+
+const page = await authyon.environment.tenants.list({
+  filter: [
+    tenantFilter.in("public.kind", ["reseller", "partner"]),
+    tenantFilter.in("custom.cnpj", ["00000000000100", "11111111000199"]),
+  ],
+  take: 100,
+});
+
+page.total; // quantos casam com o filtro, não quantos existem no ambiente
+```
+
+Cada entrada é uma condição; várias são ANDadas entre si e com o `search`, e a
+vírgula dentro de um `in` é o OR. Os escopos são `public` (publicMetadata),
+`private` (privateMetadata) e `custom` (customFields — este o `search` nunca
+cobriu). Operadores: `eq`, `in`, `like` (ILIKE, com os metacaracteres escapados)
+e `exists`. Caminho aninhado vale até três níveis: `private.billing.plan`.
+
+O construtor valida antes de sair: escopo desconhecido, chave com espaço, mais de
+25 valores num `in` ou vírgula dentro de um valor levantam `RangeError` em vez de
+virarem `400 tenant.filter.invalid`. No máximo 10 filtros por requisição.
+
+Precisa da API Authyon de 2026-10-22 ou mais nova; contra uma anterior o `filter`
+é ignorado, o que aparece como página larga demais e não como erro.
+
+## Membros do 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);
+
+// Pelo plano administrativo, a listagem vem no envelope paginado de sempre
+// (`data`, `total`, `hasNext`), com `take` 50 por padrão e teto 100.
+const { data: membros, total } = await authyon.environment.tenants.members.list(tenantId);
+
+// 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.
+```
+
+Configure `envKey` para `user()`. `members.invite` associa um usuário já
+cadastrado no ambiente pelo e-mail; não cria conta e não envia link por e-mail.
+Para isso, use os convites abaixo.
+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.
+
+## Convites de tenant (e-mail ou link)
+
+Convide um e-mail que talvez ainda não tenha conta — aceitar cria a conta, já com o
+e-mail confirmado. A resposta sempre traz o `acceptUrl` completo; `sendEmail: false`
+só gera o link para você enviar pelo seu canal.
+
+```ts
+// Pelo ambiente (escopo authyon:users:write; listar exige authyon:tenants:read).
+const invite = await authyon.environment.tenants.invites.create(tenantId, {
+  email: "pessoa@example.com",
+  roles: ["reader"],
+  sendEmail: false, // padrão: true
+  // Opcional: para onde mandar a pessoa depois de aceitar. Precisa estar
+  // cadastrado (match exato) nos redirect URIs do ambiente.
+  redirectUri: "https://app.example.com/bem-vindo",
+});
+invite.acceptUrl; // só aparece aqui — a API guarda apenas o hash do token
+
+await authyon.environment.tenants.invites.list(tenantId);
+await authyon.environment.tenants.invites.resend(tenantId, invite.id, { sendEmail: true });
+await authyon.environment.tenants.invites.revoke(tenantId, invite.id);
+
+// Pela credencial do tenant, ou agindo como o usuário (permissão tenants:members:invite).
+await authyon.tenant(credentials).invites.create({ email: "pessoa@example.com" });
+await authyon.user(token).tenants.invites.create(tenantId, { email: "pessoa@example.com" });
+
+// Página de aceite no seu backend: públicas, usam só o envKey.
+const preview = await authyon.environment.tenants.invites.preview(token);
+const accepted = await authyon.environment.tenants.invites.accept({
+  token,
+  password: preview.accountExists ? undefined : password,
+  // Opcional. Com metadata, a chamada vai para /env/tenant-invites/accept usando
+  // clientId/clientSecret (escopo authyon:users:write) — só o backend pode definir.
+  publicMetadata: { plano: "pro" },
+  privateMetadata: { crmId: "42" },
+  // customFields: { ... } — obsoleto, prefira os metadata acima.
+});
+if (accepted.redirectUri) redirect(accepted.redirectUri); // o redirect fica por sua conta
+```
+
+O link vale 7 dias e uma única vez. `resend` gera um link novo e invalida o anterior.
+Por padrão o link aponta para a página do Authyon; configure a _URL do convite para
+tenant_ nas configurações do ambiente para usar a sua (ela recebe `token` e `env`).
+Aceitar não faz login.
+
+## Redefinição de senha pelo seu próprio e-mail
+
+Para a sua aplicação disparar o e-mail de redefinição em vez do Authyon, emita o token no
+backend (escopo `authyon:users:password`) e entregue você mesmo:
+
+```ts
+const reset = await authyon.environment.users.issuePasswordReset({
+  email: "pessoa@example.com",
+  // Opcional: para onde mandar a pessoa depois de trocar a senha. Precisa estar
+  // cadastrado (match exato) nos redirect URIs do ambiente.
+  redirectUri: "https://app.example.com/login",
+  // sendEmail: true faria o Authyon enviar também; o padrão é false.
+});
+reset.token; // só aparece aqui — a API guarda apenas o hash
+reset.resetUrl; // o link que o e-mail do Authyon levaria
+reset.expiresAt; // 30 minutos
+
+// Página de redefinição no seu backend: públicas, usam só o envKey.
+const preview = await authyon.environment.users.validatePasswordReset(token); // não gasta o token
+const done = await authyon.environment.users.confirmPasswordReset(token, newPassword);
+if (done.redirectUri) redirect(done.redirectUri); // o redirect fica por sua conta
+```
+
+Quem tem o token consegue definir a senha: envie somente para o endereço da própria conta e
+não registre em log. Emitir um token novo invalida o anterior da mesma conta. Um endereço
+sem conta responde `404 user.not_found`; token desconhecido, usado ou expirado responde
+`401 user.password_reset.invalid`.
+
+## Compatibilidade e segurança do transporte
+
+As chamadas exigem os endpoints externos 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-D8tznR96.d.ts

@@ -0,0 +1,129 @@
+import { L as JwksTokenVerifier, A as AuthyonServerClient } from './authyonServerClient-COrfN4o_.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 };

package/dist/authorization-Soblu-A5.d.cts

@@ -0,0 +1,129 @@
+import { L as JwksTokenVerifier, A as AuthyonServerClient } from './authyonServerClient-COrfN4o_.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 };