@authyon/server 0.2.0-beta.14 → 0.2.0-beta.15

package/README.md

@@ -120,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`, `environment.financialAuthorizations`.
+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
 
@@ -191,34 +191,36 @@ Chamadas server-side propagam `clientIp` em `X-Forwarded-For`. O middleware Expr
 await authyon.validate(token, { clientIp: "203.0.113.10" });
 ```
 
-## Confirmação de transações financeiras
+## Segurança (`security.*`)
 
-Exige uma credencial de ambiente com o escopo `authyon:financial:authorize`. Guia
-completo, incluindo o lado do cliente: [`docs/financialStepUp.md`](../../docs/financialStepUp.md).
+OTP e aprovações ficam agrupados em `authyon.security`. Exige uma credencial de ambiente
+com o escopo `authyon:financial:authorize`. Guia completo:
+[`docs/security-otp-approvals.md`](../../docs/security-otp-approvals.md).
 
 ```ts
-const transaction = {
-  action: "pix.transfer",
-  amount: 150.5,
-  currency: "BRL",
-  beneficiary: "Maria Silva",
-};
-
-// 1. Antes de executar, peça a aprovação do cliente.
-const { id } = await authyon.environment.financialAuthorizations.create({
-  ...transaction,
+// 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,
-  idempotencyKey: orderId,
+  payload: { type: "pix", amount: 150.5, to: "maria@example.com" },
 });
-
-// 2. O cliente confirma com o código (@authyon/auth → financialAuthorizations.confirm).
-
-// 3. Consuma com a mesma transação e só então execute.
-const { assurance } = await authyon.environment.financialAuthorizations.consume(id, transaction);
+// ...cliente confirma com @authyon/auth → security.approvals.confirm
+const { payload } = await authyon.security.approvals.consume(id);
 ```
 
-Se o seu servidor guarda o token do cliente (BFF), o lado do cliente também está em
-`authyon.user(accessToken).financialAuthorizations`.
+| 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()`)
 

package/dist/{authorization-B7ynKAud.d.cts → authorization-B82XXf3B.d.cts}

@@ -1,4 +1,4 @@
-import { G as JwksTokenVerifier, A as AuthyonServerClient } from './authyonServerClient-DmNnjw4z.cjs';
+import { G as JwksTokenVerifier, A as AuthyonServerClient } from './authyonServerClient-DQzhfaja.cjs';
 
 type AbilitySubject = string | Record<string, unknown>;
 type AbilityConditions = Record<string, unknown>;

package/dist/{authorization-BF015NDJ.d.ts → authorization-WlwcTBwG.d.ts}

@@ -1,4 +1,4 @@
-import { G as JwksTokenVerifier, A as AuthyonServerClient } from './authyonServerClient-DmNnjw4z.js';
+import { G as JwksTokenVerifier, A as AuthyonServerClient } from './authyonServerClient-DQzhfaja.js';
 
 type AbilitySubject = string | Record<string, unknown>;
 type AbilityConditions = Record<string, unknown>;

package/dist/{authyonServerClient-DmNnjw4z.d.cts → authyonServerClient-DQzhfaja.d.cts}

@@ -442,27 +442,16 @@ interface JsonRequestOptions {
 
 type ManagementRequest = <T>(path: string, options?: JsonRequestOptions) => Promise<T>;
 
-/** Lifecycle of a transaction-bound financial authorization. */
-type FinancialAuthorizationStatus = "pending" | "approved" | "denied" | "consumed" | "expired";
+/** Lifecycle of an approval. */
+type ApprovalStatus = "pending" | "approved" | "denied" | "consumed" | "expired";
 /**
- * The transaction the customer approves. The API hashes a canonical form of
- * these fields; `consume()` must resend exactly the same values (amount is
- * normalized to four decimal places, metadata keys are sorted).
+ * Free-form JSON object describing what the customer approves (up to 16 KiB).
+ * The API stores it, shows it back to the customer and binds its canonical
+ * hash (keys sorted) to the approval.
  */
-interface FinancialTransaction {
-    /** Business action, e.g. `"pix.transfer"`. Max 100 characters. */
-    action: string;
-    /** Positive amount, up to 15 integer digits and 4 decimal places. */
-    amount: number;
-    /** ISO 4217 currency code, e.g. `"BRL"`. */
-    currency: string;
-    /** Human-readable beneficiary shown to the customer. Max 256 characters. */
-    beneficiary: string;
-    /** Optional JSON object bound into the hash (max 16 KiB). */
-    metadata?: Record<string, unknown>;
-}
+type ApprovalPayload = Record<string, unknown>;
 /** Evidence of how the customer proved their identity when approving. */
-interface FinancialAssurance {
+interface ApprovalAssurance {
     /** `urn:authyon:loa:3` (passkey) or `urn:authyon:loa:2` (authenticator code). */
     acr: string;
     /** Authentication methods, e.g. `["pwd", "otp"]` or `["pwd", "webauthn"]`. */
@@ -470,28 +459,25 @@ interface FinancialAssurance {
     /** When the second factor was verified (ISO 8601). */
     authTime: string;
 }
-interface FinancialAuthorization {
+/** A request for the customer to approve something with a second factor. */
+interface Approval {
     id: string;
-    status: FinancialAuthorizationStatus;
+    status: ApprovalStatus;
     subjectId: string;
     tenantId?: string | null;
-    action: string;
-    amount: number;
-    currency: string;
-    beneficiary: string;
-    /** SHA-256 (hex) of the canonical transaction. */
-    transactionHash: string;
+    /** The payload given to `create()`, with keys in canonical order. */
+    payload: ApprovalPayload;
+    /** SHA-256 (hex) of the canonical payload. */
+    payloadHash: string;
     createdAt: string;
     expiresAt: string;
     decidedAt?: string | null;
     consumedAt?: string | null;
-    /** Full canonical transaction — returned only to the customer (subject) view. */
-    transaction?: FinancialTransaction | null;
     /** Present once approved. */
-    assurance?: FinancialAssurance | null;
+    assurance?: ApprovalAssurance | null;
 }
-/** Inline second factor sent with `confirm()`. */
-type ConfirmFinancialAuthorizationInput = {
+/** Second factor sent with `confirm()`. */
+type ConfirmApprovalInput = {
     method: "authenticator";
     /** Six-digit code from the customer's authenticator app. */
     code: string;
@@ -504,33 +490,36 @@ type ConfirmFinancialAuthorizationInput = {
         assertionJson: string;
     };
 };
-/** Passkey assertion options for approving one authorization. */
-interface FinancialWebAuthnOptions {
+/** Passkey assertion options for approving one approval. */
+interface ApprovalWebAuthnOptions {
     ceremonyToken: string;
     /** JSON `PublicKeyCredentialRequestOptions` to pass to `navigator.credentials.get()`. */
     optionsJson: string;
 }
 
-/** Sends a request already authenticated as the customer (end-user bearer). */
-type SubjectRequest = <T>(path: string, options?: JsonRequestOptions) => Promise<T>;
-/** Customer-side operations on a financial authorization (`/auth/authorizations`). */
-declare function subjectFinancialAuthorizations(request: SubjectRequest): {
-    /** GET /auth/authorizations/{id} — the pending transaction, to show before asking for the code. */
-    get: (id: string) => Promise<FinancialAuthorization>;
-    /** POST /auth/authorizations/{id}/webauthn/options — passkey options for approving this authorization. */
-    webauthnOptions: (id: string) => Promise<FinancialWebAuthnOptions>;
+/** Customer-side operations on an approval (`/auth/authorizations`). */
+interface SubjectApprovals {
+    /** GET /auth/authorizations/{id} — the pending payload, to show before asking for the code. */
+    get(id: string): Promise<Approval>;
+    /** POST /auth/authorizations/{id}/webauthn/options — passkey options for approving it. */
+    webauthnOptions(id: string): Promise<ApprovalWebAuthnOptions>;
     /**
-     * POST /auth/authorizations/{id}/confirm — approves the transaction.
+     * POST /auth/authorizations/{id}/confirm — approves it.
      *
      * Pass the authenticator code or passkey assertion to verify the second
      * factor inline (recommended). Without `input`, the session itself must
      * have used a passkey or authenticator code within the last 5 minutes,
      * otherwise the API answers `step_up_required`.
      */
-    confirm: (id: string, input?: ConfirmFinancialAuthorizationInput) => Promise<FinancialAuthorization>;
-    /** POST /auth/authorizations/{id}/reject — the customer declines the transaction. */
-    reject: (id: string) => Promise<FinancialAuthorization>;
-};
+    confirm(id: string, input?: ConfirmApprovalInput): Promise<Approval>;
+    /** POST /auth/authorizations/{id}/reject — the customer declines it. */
+    reject(id: string): Promise<Approval>;
+}
+/** The `security` namespace an end-user client exposes. */
+interface SubjectSecurity {
+    /** Approve or reject what your backend asked the customer to confirm. */
+    readonly approvals: SubjectApprovals;
+}
 
 /** End-user operations require a user token and the environment publishable key. */
 declare class UserScopedClient {
@@ -538,11 +527,10 @@ declare class UserScopedClient {
     /** @hidden */
     constructor(request: ManagementRequest, token: AccessTokenSource);
     /**
-     * Customer-side approval of a financial authorization, for backends (BFF)
-     * that hold the customer's access token: `get`, `webauthnOptions`,
-     * `confirm`, `reject`.
+     * The customer's side of `security.approvals`, for backends (BFF) that hold
+     * the customer's access token: `get`, `webauthnOptions`, `confirm`, `reject`.
      */
-    readonly financialAuthorizations: ReturnType<typeof subjectFinancialAuthorizations>;
+    readonly security: SubjectSecurity;
     readonly tenants: {
         members: {
             list: (tenantId: string, options?: PaginationOptions) => Promise<TenantMemberPage>;
@@ -553,29 +541,54 @@ declare class UserScopedClient {
     };
 }
 
-/** POST /env/authorizations — a transaction awaiting the customer's approval. */
-interface CreateFinancialAuthorizationInput extends FinancialTransaction {
+/** `security.approvals.create()` — something awaiting the customer's approval. */
+interface CreateApprovalInput {
     /** Environment user who must approve. */
     subjectId: string;
+    /** Any JSON object (up to 16 KiB) describing what is being approved. Default `{}`. */
+    payload?: ApprovalPayload;
     /** Restrict approval to a session in this tenant. */
     tenantId?: string;
     /** Lifetime in seconds, clamped to 60–600. Default 300. */
     expiresInSeconds?: number;
     /**
-     * Sent as the `Idempotency-Key` header (max 128 chars). Retrying with the
-     * same key and transaction returns the same authorization; the same key
-     * with a different transaction fails with `idempotency_conflict`.
+     * Optional. Sent as the `Idempotency-Key` header (max 128 chars): retrying
+     * with the same key and payload returns the same approval; the same key
+     * with a different payload fails with `idempotency_conflict`.
      */
-    idempotencyKey: string;
+    idempotencyKey?: string;
 }
-/** POST /env/authorizations/{id}/consume — single-use redemption result. */
-interface ConsumedFinancialAuthorization {
+/** `security.approvals.consume()` — single-use redemption result. */
+interface ConsumedApproval {
     id: string;
     status: "consumed";
     consumedAt: string;
-    transactionHash: string;
-    assurance: FinancialAssurance | null;
-}
+    /** The approved payload — execute exactly this. */
+    payload: ApprovalPayload;
+    payloadHash: string;
+    assurance: ApprovalAssurance | null;
+}
+/** `security.otp.check()` result. */
+type OtpCheckResult = {
+    valid: true;
+    userId: string;
+    /** Always `"otp"` (authenticator app). */
+    method: string;
+    verifiedAt: string;
+} | {
+    valid: false;
+    /**
+     * Wrong codes left before the first consequence: the sign-out (3 in a
+     * row) or the 15-minute lock (5). `0` when the user was just signed out.
+     */
+    attemptsRemaining: number;
+    /**
+     * True when this was the 3rd wrong code in a row (counted across login
+     * 2FA, `security.otp.check` and `security.approvals.confirm`): every
+     * session of the user was ended and they must sign in again.
+     */
+    sessionsRevoked?: boolean;
+};
 
 interface ClientRequestContext {
     /** Real end-user IP, resolved only from infrastructure trusted by the application. */
@@ -819,32 +832,43 @@ declare class AuthyonServerClient {
             /** 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 security: {
+        otp: {
+            /**
+             * POST /env/users/{userId}/otp/verify — checks the user's authenticator
+             * app (TOTP) code. A wrong code returns `{ valid: false }` instead of
+             * throwing. Each code is accepted once; 3 wrong codes in a row sign the
+             * user out everywhere (`sessionsRevoked: true`); 5 lock the check for 15
+             * minutes (`rate_limited`).
+             */
+            check: (userId: string, code: string) => Promise<OtpCheckResult>;
+        };
         /**
-         * Transaction-bound step-up for financial operations. The environment
-         * credential needs the `authyon:financial:authorize` scope.
+         * The customer approves a payload with their authenticator code or
+         * passkey, once.
          *
-         * 1. `create()` the authorization for the transaction and the customer.
-         * 2. The customer approves it with their authenticator code or passkey
-         *    (`@authyon/auth` → `financialAuthorizations.confirm`).
-         * 3. `consume()` it with the same transaction right before executing it.
+         * 1. `create()` the approval with the payload and the customer.
+         * 2. The customer confirms it (`@authyon/auth` → `security.approvals.confirm`).
+         * 3. `consume()` it right before executing, and execute the returned payload.
          */
-        financialAuthorizations: {
-            /** POST /env/authorizations — registers a transaction awaiting the customer's approval. */
-            create: (input: CreateFinancialAuthorizationInput) => Promise<FinancialAuthorization>;
+        approvals: {
+            /** POST /env/authorizations — registers a payload awaiting the customer's approval. */
+            create: (input: CreateApprovalInput) => Promise<Approval>;
             /** GET /env/authorizations/{id} — current status and, once approved, the assurance evidence. */
-            get: (id: string) => Promise<FinancialAuthorization>;
+            get: (id: string) => Promise<Approval>;
             /**
-             * POST /env/authorizations/{id}/consume — redeems an approved
-             * authorization exactly once. Resend the same transaction given to
-             * `create()`; any difference fails with `transaction_mismatch`.
+             * POST /env/authorizations/{id}/consume — redeems an approved approval
+             * exactly once and returns the approved payload. Pass `payload` to have
+             * the API check it matches (`payload_mismatch` otherwise).
              */
-            consume: (id: string, transaction: FinancialTransaction) => Promise<ConsumedFinancialAuthorization>;
-        };
-        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>>;
+            consume: (id: string, payload?: ApprovalPayload) => Promise<ConsumedApproval>;
         };
     };
     readonly permissions: {
@@ -921,4 +945,4 @@ declare class TenantScopedClient {
 /** Convenience factory: `const authyon = createClient({ clientId, clientSecret })`. */
 declare function createClient(options?: AuthyonServerClientOptions): AuthyonServerClient;
 
-export { type TenantCredentialIssued as $, AuthyonServerClient as A, type HttpLogger as B, type ClientCredentials as C, type InviteTenantMemberInput as D, type EnvironmentUser as E, FetchHttpAdapter as F, JwksTokenVerifier as G, type HttpAdapter as H, type IntrospectResult as I, type JsonWebKeySet as J, type JwksTokenVerifierOptions as K, LoggingHttpAdapter as L, type LoginActivity as M, type Organization as N, type OpenIdConfiguration as O, type Paged as P, type PaginationOptions as Q, type Permission as R, type PermissionsByRole as S, type ReservedPermissions as T, type Role as U, type RoleGrant as V, type RoleInput as W, type RoleList as X, type RolePermissions as Y, type SafeJwtAlgorithm as Z, type TenantClientValidationResult as _, type HttpLoggerOptions as a, type TenantCredentialSummary as a0, type TenantMember as a1, type TenantMemberPage as a2, type TenantMembership as a3, TenantScopedClient as a4, type TokenResult as a5, TokenVerificationError as a6, type TokenVerificationErrorCode as a7, type UpdateOrganizationInput as a8, type User as a9, UserScopedClient as aa, type ValidateResult as ab, type VerifiedAccessToken as ac, createClient as ad, normalizeClientIp as ae, type AccessTokenSource as b, type AuditEvent as c, type AuthyonJwksDiscoveryOptions as d, type AuthyonJwtClaims as e, type AuthyonServerClientOptions as f, type ClientRequestContext as g, type ConfirmFinancialAuthorizationInput as h, type ConsumedFinancialAuthorization as i, type CreateCredentialInput as j, type CreateFinancialAuthorizationInput as k, type CreateOrganizationInput as l, type CreatePermissionInput as m, type CreateTenantCredentialInput as n, type CreateUserInput as o, type CredentialCreator as p, type CredentialDetail as q, type CredentialListOptions as r, type CredentialPermissionsInput as s, type FinancialAssurance as t, type FinancialAuthorization as u, type FinancialAuthorizationStatus as v, type FinancialTransaction as w, type FinancialWebAuthnOptions as x, type HttpAdapterRequest as y, type HttpLogEvent as z };
+export { type SubjectApprovals as $, AuthyonServerClient as A, type HttpLogger as B, type ClientCredentials as C, type InviteTenantMemberInput as D, type EnvironmentUser as E, FetchHttpAdapter as F, JwksTokenVerifier as G, type HttpAdapter as H, type IntrospectResult as I, type JsonWebKeySet as J, type JwksTokenVerifierOptions as K, LoggingHttpAdapter as L, type LoginActivity as M, type Organization as N, type OpenIdConfiguration as O, type OtpCheckResult as P, type Paged as Q, type PaginationOptions as R, type Permission as S, type PermissionsByRole as T, type ReservedPermissions as U, type Role as V, type RoleGrant as W, type RoleInput as X, type RoleList as Y, type RolePermissions as Z, type SafeJwtAlgorithm as _, type HttpLoggerOptions as a, type SubjectSecurity as a0, type TenantClientValidationResult as a1, type TenantCredentialIssued as a2, type TenantCredentialSummary as a3, type TenantMember as a4, type TenantMemberPage as a5, type TenantMembership as a6, TenantScopedClient as a7, type TokenResult as a8, TokenVerificationError as a9, type TokenVerificationErrorCode as aa, type UpdateOrganizationInput as ab, type User as ac, UserScopedClient as ad, type ValidateResult as ae, type VerifiedAccessToken as af, createClient as ag, normalizeClientIp as ah, type AccessTokenSource as b, type Approval as c, type ApprovalAssurance as d, type ApprovalPayload as e, type ApprovalStatus as f, type ApprovalWebAuthnOptions as g, type AuditEvent as h, type AuthyonJwksDiscoveryOptions as i, type AuthyonJwtClaims as j, type AuthyonServerClientOptions as k, type ClientRequestContext as l, type ConfirmApprovalInput as m, type ConsumedApproval as n, type CreateApprovalInput as o, type CreateCredentialInput as p, type CreateOrganizationInput as q, type CreatePermissionInput as r, type CreateTenantCredentialInput as s, type CreateUserInput as t, type CredentialCreator as u, type CredentialDetail as v, type CredentialListOptions as w, type CredentialPermissionsInput as x, type HttpAdapterRequest as y, type HttpLogEvent as z };

package/dist/{authyonServerClient-DmNnjw4z.d.ts → authyonServerClient-DQzhfaja.d.ts}

@@ -442,27 +442,16 @@ interface JsonRequestOptions {
 
 type ManagementRequest = <T>(path: string, options?: JsonRequestOptions) => Promise<T>;
 
-/** Lifecycle of a transaction-bound financial authorization. */
-type FinancialAuthorizationStatus = "pending" | "approved" | "denied" | "consumed" | "expired";
+/** Lifecycle of an approval. */
+type ApprovalStatus = "pending" | "approved" | "denied" | "consumed" | "expired";
 /**
- * The transaction the customer approves. The API hashes a canonical form of
- * these fields; `consume()` must resend exactly the same values (amount is
- * normalized to four decimal places, metadata keys are sorted).
+ * Free-form JSON object describing what the customer approves (up to 16 KiB).
+ * The API stores it, shows it back to the customer and binds its canonical
+ * hash (keys sorted) to the approval.
  */
-interface FinancialTransaction {
-    /** Business action, e.g. `"pix.transfer"`. Max 100 characters. */
-    action: string;
-    /** Positive amount, up to 15 integer digits and 4 decimal places. */
-    amount: number;
-    /** ISO 4217 currency code, e.g. `"BRL"`. */
-    currency: string;
-    /** Human-readable beneficiary shown to the customer. Max 256 characters. */
-    beneficiary: string;
-    /** Optional JSON object bound into the hash (max 16 KiB). */
-    metadata?: Record<string, unknown>;
-}
+type ApprovalPayload = Record<string, unknown>;
 /** Evidence of how the customer proved their identity when approving. */
-interface FinancialAssurance {
+interface ApprovalAssurance {
     /** `urn:authyon:loa:3` (passkey) or `urn:authyon:loa:2` (authenticator code). */
     acr: string;
     /** Authentication methods, e.g. `["pwd", "otp"]` or `["pwd", "webauthn"]`. */
@@ -470,28 +459,25 @@ interface FinancialAssurance {
     /** When the second factor was verified (ISO 8601). */
     authTime: string;
 }
-interface FinancialAuthorization {
+/** A request for the customer to approve something with a second factor. */
+interface Approval {
     id: string;
-    status: FinancialAuthorizationStatus;
+    status: ApprovalStatus;
     subjectId: string;
     tenantId?: string | null;
-    action: string;
-    amount: number;
-    currency: string;
-    beneficiary: string;
-    /** SHA-256 (hex) of the canonical transaction. */
-    transactionHash: string;
+    /** The payload given to `create()`, with keys in canonical order. */
+    payload: ApprovalPayload;
+    /** SHA-256 (hex) of the canonical payload. */
+    payloadHash: string;
     createdAt: string;
     expiresAt: string;
     decidedAt?: string | null;
     consumedAt?: string | null;
-    /** Full canonical transaction — returned only to the customer (subject) view. */
-    transaction?: FinancialTransaction | null;
     /** Present once approved. */
-    assurance?: FinancialAssurance | null;
+    assurance?: ApprovalAssurance | null;
 }
-/** Inline second factor sent with `confirm()`. */
-type ConfirmFinancialAuthorizationInput = {
+/** Second factor sent with `confirm()`. */
+type ConfirmApprovalInput = {
     method: "authenticator";
     /** Six-digit code from the customer's authenticator app. */
     code: string;
@@ -504,33 +490,36 @@ type ConfirmFinancialAuthorizationInput = {
         assertionJson: string;
     };
 };
-/** Passkey assertion options for approving one authorization. */
-interface FinancialWebAuthnOptions {
+/** Passkey assertion options for approving one approval. */
+interface ApprovalWebAuthnOptions {
     ceremonyToken: string;
     /** JSON `PublicKeyCredentialRequestOptions` to pass to `navigator.credentials.get()`. */
     optionsJson: string;
 }
 
-/** Sends a request already authenticated as the customer (end-user bearer). */
-type SubjectRequest = <T>(path: string, options?: JsonRequestOptions) => Promise<T>;
-/** Customer-side operations on a financial authorization (`/auth/authorizations`). */
-declare function subjectFinancialAuthorizations(request: SubjectRequest): {
-    /** GET /auth/authorizations/{id} — the pending transaction, to show before asking for the code. */
-    get: (id: string) => Promise<FinancialAuthorization>;
-    /** POST /auth/authorizations/{id}/webauthn/options — passkey options for approving this authorization. */
-    webauthnOptions: (id: string) => Promise<FinancialWebAuthnOptions>;
+/** Customer-side operations on an approval (`/auth/authorizations`). */
+interface SubjectApprovals {
+    /** GET /auth/authorizations/{id} — the pending payload, to show before asking for the code. */
+    get(id: string): Promise<Approval>;
+    /** POST /auth/authorizations/{id}/webauthn/options — passkey options for approving it. */
+    webauthnOptions(id: string): Promise<ApprovalWebAuthnOptions>;
     /**
-     * POST /auth/authorizations/{id}/confirm — approves the transaction.
+     * POST /auth/authorizations/{id}/confirm — approves it.
      *
      * Pass the authenticator code or passkey assertion to verify the second
      * factor inline (recommended). Without `input`, the session itself must
      * have used a passkey or authenticator code within the last 5 minutes,
      * otherwise the API answers `step_up_required`.
      */
-    confirm: (id: string, input?: ConfirmFinancialAuthorizationInput) => Promise<FinancialAuthorization>;
-    /** POST /auth/authorizations/{id}/reject — the customer declines the transaction. */
-    reject: (id: string) => Promise<FinancialAuthorization>;
-};
+    confirm(id: string, input?: ConfirmApprovalInput): Promise<Approval>;
+    /** POST /auth/authorizations/{id}/reject — the customer declines it. */
+    reject(id: string): Promise<Approval>;
+}
+/** The `security` namespace an end-user client exposes. */
+interface SubjectSecurity {
+    /** Approve or reject what your backend asked the customer to confirm. */
+    readonly approvals: SubjectApprovals;
+}
 
 /** End-user operations require a user token and the environment publishable key. */
 declare class UserScopedClient {
@@ -538,11 +527,10 @@ declare class UserScopedClient {
     /** @hidden */
     constructor(request: ManagementRequest, token: AccessTokenSource);
     /**
-     * Customer-side approval of a financial authorization, for backends (BFF)
-     * that hold the customer's access token: `get`, `webauthnOptions`,
-     * `confirm`, `reject`.
+     * The customer's side of `security.approvals`, for backends (BFF) that hold
+     * the customer's access token: `get`, `webauthnOptions`, `confirm`, `reject`.
      */
-    readonly financialAuthorizations: ReturnType<typeof subjectFinancialAuthorizations>;
+    readonly security: SubjectSecurity;
     readonly tenants: {
         members: {
             list: (tenantId: string, options?: PaginationOptions) => Promise<TenantMemberPage>;
@@ -553,29 +541,54 @@ declare class UserScopedClient {
     };
 }
 
-/** POST /env/authorizations — a transaction awaiting the customer's approval. */
-interface CreateFinancialAuthorizationInput extends FinancialTransaction {
+/** `security.approvals.create()` — something awaiting the customer's approval. */
+interface CreateApprovalInput {
     /** Environment user who must approve. */
     subjectId: string;
+    /** Any JSON object (up to 16 KiB) describing what is being approved. Default `{}`. */
+    payload?: ApprovalPayload;
     /** Restrict approval to a session in this tenant. */
     tenantId?: string;
     /** Lifetime in seconds, clamped to 60–600. Default 300. */
     expiresInSeconds?: number;
     /**
-     * Sent as the `Idempotency-Key` header (max 128 chars). Retrying with the
-     * same key and transaction returns the same authorization; the same key
-     * with a different transaction fails with `idempotency_conflict`.
+     * Optional. Sent as the `Idempotency-Key` header (max 128 chars): retrying
+     * with the same key and payload returns the same approval; the same key
+     * with a different payload fails with `idempotency_conflict`.
      */
-    idempotencyKey: string;
+    idempotencyKey?: string;
 }
-/** POST /env/authorizations/{id}/consume — single-use redemption result. */
-interface ConsumedFinancialAuthorization {
+/** `security.approvals.consume()` — single-use redemption result. */
+interface ConsumedApproval {
     id: string;
     status: "consumed";
     consumedAt: string;
-    transactionHash: string;
-    assurance: FinancialAssurance | null;
-}
+    /** The approved payload — execute exactly this. */
+    payload: ApprovalPayload;
+    payloadHash: string;
+    assurance: ApprovalAssurance | null;
+}
+/** `security.otp.check()` result. */
+type OtpCheckResult = {
+    valid: true;
+    userId: string;
+    /** Always `"otp"` (authenticator app). */
+    method: string;
+    verifiedAt: string;
+} | {
+    valid: false;
+    /**
+     * Wrong codes left before the first consequence: the sign-out (3 in a
+     * row) or the 15-minute lock (5). `0` when the user was just signed out.
+     */
+    attemptsRemaining: number;
+    /**
+     * True when this was the 3rd wrong code in a row (counted across login
+     * 2FA, `security.otp.check` and `security.approvals.confirm`): every
+     * session of the user was ended and they must sign in again.
+     */
+    sessionsRevoked?: boolean;
+};
 
 interface ClientRequestContext {
     /** Real end-user IP, resolved only from infrastructure trusted by the application. */
@@ -819,32 +832,43 @@ declare class AuthyonServerClient {
             /** 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 security: {
+        otp: {
+            /**
+             * POST /env/users/{userId}/otp/verify — checks the user's authenticator
+             * app (TOTP) code. A wrong code returns `{ valid: false }` instead of
+             * throwing. Each code is accepted once; 3 wrong codes in a row sign the
+             * user out everywhere (`sessionsRevoked: true`); 5 lock the check for 15
+             * minutes (`rate_limited`).
+             */
+            check: (userId: string, code: string) => Promise<OtpCheckResult>;
+        };
         /**
-         * Transaction-bound step-up for financial operations. The environment
-         * credential needs the `authyon:financial:authorize` scope.
+         * The customer approves a payload with their authenticator code or
+         * passkey, once.
          *
-         * 1. `create()` the authorization for the transaction and the customer.
-         * 2. The customer approves it with their authenticator code or passkey
-         *    (`@authyon/auth` → `financialAuthorizations.confirm`).
-         * 3. `consume()` it with the same transaction right before executing it.
+         * 1. `create()` the approval with the payload and the customer.
+         * 2. The customer confirms it (`@authyon/auth` → `security.approvals.confirm`).
+         * 3. `consume()` it right before executing, and execute the returned payload.
          */
-        financialAuthorizations: {
-            /** POST /env/authorizations — registers a transaction awaiting the customer's approval. */
-            create: (input: CreateFinancialAuthorizationInput) => Promise<FinancialAuthorization>;
+        approvals: {
+            /** POST /env/authorizations — registers a payload awaiting the customer's approval. */
+            create: (input: CreateApprovalInput) => Promise<Approval>;
             /** GET /env/authorizations/{id} — current status and, once approved, the assurance evidence. */
-            get: (id: string) => Promise<FinancialAuthorization>;
+            get: (id: string) => Promise<Approval>;
             /**
-             * POST /env/authorizations/{id}/consume — redeems an approved
-             * authorization exactly once. Resend the same transaction given to
-             * `create()`; any difference fails with `transaction_mismatch`.
+             * POST /env/authorizations/{id}/consume — redeems an approved approval
+             * exactly once and returns the approved payload. Pass `payload` to have
+             * the API check it matches (`payload_mismatch` otherwise).
              */
-            consume: (id: string, transaction: FinancialTransaction) => Promise<ConsumedFinancialAuthorization>;
-        };
-        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>>;
+            consume: (id: string, payload?: ApprovalPayload) => Promise<ConsumedApproval>;
         };
     };
     readonly permissions: {
@@ -921,4 +945,4 @@ declare class TenantScopedClient {
 /** Convenience factory: `const authyon = createClient({ clientId, clientSecret })`. */
 declare function createClient(options?: AuthyonServerClientOptions): AuthyonServerClient;
 
-export { type TenantCredentialIssued as $, AuthyonServerClient as A, type HttpLogger as B, type ClientCredentials as C, type InviteTenantMemberInput as D, type EnvironmentUser as E, FetchHttpAdapter as F, JwksTokenVerifier as G, type HttpAdapter as H, type IntrospectResult as I, type JsonWebKeySet as J, type JwksTokenVerifierOptions as K, LoggingHttpAdapter as L, type LoginActivity as M, type Organization as N, type OpenIdConfiguration as O, type Paged as P, type PaginationOptions as Q, type Permission as R, type PermissionsByRole as S, type ReservedPermissions as T, type Role as U, type RoleGrant as V, type RoleInput as W, type RoleList as X, type RolePermissions as Y, type SafeJwtAlgorithm as Z, type TenantClientValidationResult as _, type HttpLoggerOptions as a, type TenantCredentialSummary as a0, type TenantMember as a1, type TenantMemberPage as a2, type TenantMembership as a3, TenantScopedClient as a4, type TokenResult as a5, TokenVerificationError as a6, type TokenVerificationErrorCode as a7, type UpdateOrganizationInput as a8, type User as a9, UserScopedClient as aa, type ValidateResult as ab, type VerifiedAccessToken as ac, createClient as ad, normalizeClientIp as ae, type AccessTokenSource as b, type AuditEvent as c, type AuthyonJwksDiscoveryOptions as d, type AuthyonJwtClaims as e, type AuthyonServerClientOptions as f, type ClientRequestContext as g, type ConfirmFinancialAuthorizationInput as h, type ConsumedFinancialAuthorization as i, type CreateCredentialInput as j, type CreateFinancialAuthorizationInput as k, type CreateOrganizationInput as l, type CreatePermissionInput as m, type CreateTenantCredentialInput as n, type CreateUserInput as o, type CredentialCreator as p, type CredentialDetail as q, type CredentialListOptions as r, type CredentialPermissionsInput as s, type FinancialAssurance as t, type FinancialAuthorization as u, type FinancialAuthorizationStatus as v, type FinancialTransaction as w, type FinancialWebAuthnOptions as x, type HttpAdapterRequest as y, type HttpLogEvent as z };
+export { type SubjectApprovals as $, AuthyonServerClient as A, type HttpLogger as B, type ClientCredentials as C, type InviteTenantMemberInput as D, type EnvironmentUser as E, FetchHttpAdapter as F, JwksTokenVerifier as G, type HttpAdapter as H, type IntrospectResult as I, type JsonWebKeySet as J, type JwksTokenVerifierOptions as K, LoggingHttpAdapter as L, type LoginActivity as M, type Organization as N, type OpenIdConfiguration as O, type OtpCheckResult as P, type Paged as Q, type PaginationOptions as R, type Permission as S, type PermissionsByRole as T, type ReservedPermissions as U, type Role as V, type RoleGrant as W, type RoleInput as X, type RoleList as Y, type RolePermissions as Z, type SafeJwtAlgorithm as _, type HttpLoggerOptions as a, type SubjectSecurity as a0, type TenantClientValidationResult as a1, type TenantCredentialIssued as a2, type TenantCredentialSummary as a3, type TenantMember as a4, type TenantMemberPage as a5, type TenantMembership as a6, TenantScopedClient as a7, type TokenResult as a8, TokenVerificationError as a9, type TokenVerificationErrorCode as aa, type UpdateOrganizationInput as ab, type User as ac, UserScopedClient as ad, type ValidateResult as ae, type VerifiedAccessToken as af, createClient as ag, normalizeClientIp as ah, type AccessTokenSource as b, type Approval as c, type ApprovalAssurance as d, type ApprovalPayload as e, type ApprovalStatus as f, type ApprovalWebAuthnOptions as g, type AuditEvent as h, type AuthyonJwksDiscoveryOptions as i, type AuthyonJwtClaims as j, type AuthyonServerClientOptions as k, type ClientRequestContext as l, type ConfirmApprovalInput as m, type ConsumedApproval as n, type CreateApprovalInput as o, type CreateCredentialInput as p, type CreateOrganizationInput as q, type CreatePermissionInput as r, type CreateTenantCredentialInput as s, type CreateUserInput as t, type CredentialCreator as u, type CredentialDetail as v, type CredentialListOptions as w, type CredentialPermissionsInput as x, type HttpAdapterRequest as y, type HttpLogEvent as z };

package/dist/bff.cjs

@@ -56,10 +56,17 @@ var ErrorCodes = {
   InvalidSecondFactorCode: "invalid_code",
   VerificationAttemptsExhausted: "verification_attempts_exhausted",
   MethodNotEnrolled: "method_not_enrolled",
-  InvalidAuthorizationState: "invalid_authorization_state",
-  TransactionMismatch: "transaction_mismatch",
-  AuthorizationNotConsumable: "authorization_not_consumable",
-  IdempotencyConflict: "idempotency_conflict"
+  InvalidApprovalState: "invalid_authorization_state",
+  PayloadMismatch: "payload_mismatch",
+  ApprovalNotConsumable: "authorization_not_consumable",
+  IdempotencyConflict: "idempotency_conflict",
+  UserDisabled: "user_disabled",
+  UserNotFound: "user_not_found",
+  TemporarilyUnavailable: "temporarily_unavailable",
+  InsufficientScope: "insufficient_scope",
+  ApprovalNotFound: "authorization_not_found",
+  SessionRevoked: "session_revoked",
+  TwoFactorTooManyFailures: "user.2fa.too_many_failures"
 };
 var STANDARD_ERROR_FIELDS = /* @__PURE__ */ new Set([
   "type",

package/dist/bff.d.cts

@@ -1,4 +1,4 @@
-import { H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonServerClient } from './authyonServerClient-DmNnjw4z.cjs';
+import { H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonServerClient } from './authyonServerClient-DQzhfaja.cjs';
 import 'jose';
 
 interface BffLoginInput {

package/dist/bff.d.ts

@@ -1,4 +1,4 @@
-import { H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonServerClient } from './authyonServerClient-DmNnjw4z.js';
+import { H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonServerClient } from './authyonServerClient-DQzhfaja.js';
 import 'jose';
 
 interface BffLoginInput {

package/dist/bff.js

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

package/dist/{chunk-TWUVXZOT.js → chunk-WPPEV5BA.js}

@@ -15,10 +15,17 @@ var ErrorCodes = {
   InvalidSecondFactorCode: "invalid_code",
   VerificationAttemptsExhausted: "verification_attempts_exhausted",
   MethodNotEnrolled: "method_not_enrolled",
-  InvalidAuthorizationState: "invalid_authorization_state",
-  TransactionMismatch: "transaction_mismatch",
-  AuthorizationNotConsumable: "authorization_not_consumable",
-  IdempotencyConflict: "idempotency_conflict"
+  InvalidApprovalState: "invalid_authorization_state",
+  PayloadMismatch: "payload_mismatch",
+  ApprovalNotConsumable: "authorization_not_consumable",
+  IdempotencyConflict: "idempotency_conflict",
+  UserDisabled: "user_disabled",
+  UserNotFound: "user_not_found",
+  TemporarilyUnavailable: "temporarily_unavailable",
+  InsufficientScope: "insufficient_scope",
+  ApprovalNotFound: "authorization_not_found",
+  SessionRevoked: "session_revoked",
+  TwoFactorTooManyFailures: "user.2fa.too_many_failures"
 };
 var STANDARD_ERROR_FIELDS = /* @__PURE__ */ new Set([
   "type",

package/dist/index.cjs

@@ -168,29 +168,20 @@ async function allCredentials(request, path2) {
   throw new Error("Authyon: use listPage for more than 1000 credential pages.");
 }
 
-// ../../internal/core/financial/subjectFinancialAuthorizations.ts
+// ../../internal/core/security/approvals.ts
 function path(id, suffix = "") {
   if (typeof id !== "string" || !id.trim())
-    throw new TypeError("Authyon: a financial authorization id is required.");
+    throw new TypeError("Authyon: an approval id is required.");
   return `/auth/authorizations/${encodeURIComponent(id)}${suffix}`;
 }
-function subjectFinancialAuthorizations(request) {
+function subjectSecurity(request) {
   return {
-    /** GET /auth/authorizations/{id} — the pending transaction, to show before asking for the code. */
-    get: (id) => request(path(id)),
-    /** POST /auth/authorizations/{id}/webauthn/options — passkey options for approving this authorization. */
-    webauthnOptions: (id) => request(path(id, "/webauthn/options"), { method: "POST" }),
-    /**
-     * POST /auth/authorizations/{id}/confirm — approves the transaction.
-     *
-     * Pass the authenticator code or passkey assertion to verify the second
-     * factor inline (recommended). Without `input`, the session itself must
-     * have used a passkey or authenticator code within the last 5 minutes,
-     * otherwise the API answers `step_up_required`.
-     */
-    confirm: (id, input) => request(path(id, "/confirm"), { method: "POST", body: input }),
-    /** POST /auth/authorizations/{id}/reject — the customer declines the transaction. */
-    reject: (id) => request(path(id, "/reject"), { method: "POST" })
+    approvals: {
+      get: (id) => request(path(id)),
+      webauthnOptions: (id) => request(path(id, "/webauthn/options"), { method: "POST" }),
+      confirm: (id, input) => request(path(id, "/confirm"), { method: "POST", body: input }),
+      reject: (id) => request(path(id, "/reject"), { method: "POST" })
+    }
   };
 }
 
@@ -225,7 +216,7 @@ var UserScopedClient = class {
       }
     };
     __privateSet(this, _request, scopedRequest(request, token));
-    this.financialAuthorizations = subjectFinancialAuthorizations(__privateGet(this, _request));
+    this.security = subjectSecurity(__privateGet(this, _request));
   }
 };
 _request = new WeakMap();
@@ -280,10 +271,17 @@ var ErrorCodes = {
   InvalidSecondFactorCode: "invalid_code",
   VerificationAttemptsExhausted: "verification_attempts_exhausted",
   MethodNotEnrolled: "method_not_enrolled",
-  InvalidAuthorizationState: "invalid_authorization_state",
-  TransactionMismatch: "transaction_mismatch",
-  AuthorizationNotConsumable: "authorization_not_consumable",
-  IdempotencyConflict: "idempotency_conflict"
+  InvalidApprovalState: "invalid_authorization_state",
+  PayloadMismatch: "payload_mismatch",
+  ApprovalNotConsumable: "authorization_not_consumable",
+  IdempotencyConflict: "idempotency_conflict",
+  UserDisabled: "user_disabled",
+  UserNotFound: "user_not_found",
+  TemporarilyUnavailable: "temporarily_unavailable",
+  InsufficientScope: "insufficient_scope",
+  ApprovalNotFound: "authorization_not_found",
+  SessionRevoked: "session_revoked",
+  TwoFactorTooManyFailures: "user.2fa.too_many_failures"
 };
 var STANDARD_ERROR_FIELDS = /* @__PURE__ */ new Set([
   "type",
@@ -1070,46 +1068,63 @@ var AuthyonServerClient = class {
         /** GET /permissions/reserved — reserved permission names you can't redefine. */
         reserved: () => this.request("/permissions/reserved", { envBearer: true })
       },
+      audit: {
+        /** GET /env/audit — paginated list of the environment's audit events. */
+        list: (params = {}) => this.request("/env/audit", { envBearer: true, query: params }),
+        /** GET /env/audit/login-activity — paginated login activity in the environment. */
+        loginActivity: (params = {}) => this.request("/env/audit/login-activity", { envBearer: true, query: params })
+      }
+    };
+    // ── Security: one-time codes and approvals ───────────────────────────────
+    //
+    // Everything here runs with the environment credential, which needs the
+    // `authyon:financial:authorize` scope. Keep that credential on the server.
+    this.security = {
+      otp: {
+        /**
+         * POST /env/users/{userId}/otp/verify — checks the user's authenticator
+         * app (TOTP) code. A wrong code returns `{ valid: false }` instead of
+         * throwing. Each code is accepted once; 3 wrong codes in a row sign the
+         * user out everywhere (`sessionsRevoked: true`); 5 lock the check for 15
+         * minutes (`rate_limited`).
+         */
+        check: (userId, code) => this.request(`/env/users/${segment(userId)}/otp/verify`, {
+          method: "POST",
+          envBearer: true,
+          body: { code }
+        })
+      },
       /**
-       * Transaction-bound step-up for financial operations. The environment
-       * credential needs the `authyon:financial:authorize` scope.
+       * The customer approves a payload with their authenticator code or
+       * passkey, once.
        *
-       * 1. `create()` the authorization for the transaction and the customer.
-       * 2. The customer approves it with their authenticator code or passkey
-       *    (`@authyon/auth` → `financialAuthorizations.confirm`).
-       * 3. `consume()` it with the same transaction right before executing it.
+       * 1. `create()` the approval with the payload and the customer.
+       * 2. The customer confirms it (`@authyon/auth` → `security.approvals.confirm`).
+       * 3. `consume()` it right before executing, and execute the returned payload.
        */
-      financialAuthorizations: {
-        /** POST /env/authorizations — registers a transaction awaiting the customer's approval. */
+      approvals: {
+        /** POST /env/authorizations — registers a payload awaiting the customer's approval. */
         create: (input) => {
           const { idempotencyKey, ...body } = input;
-          if (typeof idempotencyKey !== "string" || !idempotencyKey.trim())
-            throw new TypeError("Authyon: `idempotencyKey` is required.");
           return this.request("/env/authorizations", {
             method: "POST",
             envBearer: true,
-            headers: { "Idempotency-Key": idempotencyKey },
+            headers: idempotencyKey ? { "Idempotency-Key": idempotencyKey } : void 0,
             body
           });
         },
         /** GET /env/authorizations/{id} — current status and, once approved, the assurance evidence. */
         get: (id) => this.request(`/env/authorizations/${segment(id)}`, { envBearer: true }),
         /**
-         * POST /env/authorizations/{id}/consume — redeems an approved
-         * authorization exactly once. Resend the same transaction given to
-         * `create()`; any difference fails with `transaction_mismatch`.
+         * POST /env/authorizations/{id}/consume — redeems an approved approval
+         * exactly once and returns the approved payload. Pass `payload` to have
+         * the API check it matches (`payload_mismatch` otherwise).
          */
-        consume: (id, transaction) => this.request(`/env/authorizations/${segment(id)}/consume`, {
+        consume: (id, payload) => this.request(`/env/authorizations/${segment(id)}/consume`, {
           method: "POST",
           envBearer: true,
-          body: transaction
+          body: payload === void 0 ? void 0 : { payload }
         })
-      },
-      audit: {
-        /** GET /env/audit — paginated list of the environment's audit events. */
-        list: (params = {}) => this.request("/env/audit", { envBearer: true, query: params }),
-        /** GET /env/audit/login-activity — paginated login activity in the environment. */
-        loginActivity: (params = {}) => this.request("/env/audit/login-activity", { envBearer: true, query: params })
       }
     };
     // ── Generic permission grants ─────────────────────────────────────────────

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonServerClient } from './authyonServerClient-DmNnjw4z.cjs';
-export { b as AccessTokenSource, c as AuditEvent, d as AuthyonJwksDiscoveryOptions, e as AuthyonJwtClaims, f as AuthyonServerClientOptions, C as ClientCredentials, g as ClientRequestContext, h as ConfirmFinancialAuthorizationInput, i as ConsumedFinancialAuthorization, j as CreateCredentialInput, k as CreateFinancialAuthorizationInput, l as CreateOrganizationInput, m as CreatePermissionInput, n as CreateTenantCredentialInput, o as CreateUserInput, p as CredentialCreator, q as CredentialDetail, r as CredentialListOptions, s as CredentialPermissionsInput, E as EnvironmentUser, F as FetchHttpAdapter, t as FinancialAssurance, u as FinancialAuthorization, v as FinancialAuthorizationStatus, w as FinancialTransaction, x as FinancialWebAuthnOptions, y as HttpAdapterRequest, z as HttpLogEvent, B as HttpLogger, I as IntrospectResult, D as InviteTenantMemberInput, J as JsonWebKeySet, G as JwksTokenVerifier, K as JwksTokenVerifierOptions, L as LoggingHttpAdapter, M as LoginActivity, O as OpenIdConfiguration, N as Organization, P as Paged, Q as PaginationOptions, R as Permission, S as PermissionsByRole, T as ReservedPermissions, U as Role, V as RoleGrant, W as RoleInput, X as RoleList, Y as RolePermissions, Z as SafeJwtAlgorithm, _ as TenantClientValidationResult, $ as TenantCredentialIssued, a0 as TenantCredentialSummary, a1 as TenantMember, a2 as TenantMemberPage, a3 as TenantMembership, a4 as TenantScopedClient, a5 as TokenResult, a6 as TokenVerificationError, a7 as TokenVerificationErrorCode, a8 as UpdateOrganizationInput, a9 as User, aa as UserScopedClient, ab as ValidateResult, ac as VerifiedAccessToken, ad as createClient, ae as normalizeClientIp } from './authyonServerClient-DmNnjw4z.cjs';
-export { b as AbilityConditions, c as AbilityEvent, d as AbilityListener, e as AbilityRequirement, f as AbilityRule, A as AbilitySubject, g as AuthorizationContext, a as AuthorizationError, h as AuthorizationOptions, i as AuthyonAbility, j as AuthyonAbilityBuilder, k as AuthyonAbilityOptions, l as AuthyonPermissionSource, E as ExpressAuthorizationMiddlewareOptions, m as ExpressNext, n as ExpressRequestLike, o as ExpressResponseLike, P as PermissionGroup, R as RequestAuthorizationOptions, p as authorizeRequest, q as authorizeToken, r as createAuthorizationErrorResponse, s as createAuthyonAbility, t as createAuthyonRules, u as createExpressAuthorizationMiddleware, v as hasPermission, w as hasPermissionGroup } from './authorization-B7ynKAud.cjs';
+import { H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonServerClient } from './authyonServerClient-DQzhfaja.cjs';
+export { b as AccessTokenSource, c as Approval, d as ApprovalAssurance, e as ApprovalPayload, f as ApprovalStatus, g as ApprovalWebAuthnOptions, h as AuditEvent, i as AuthyonJwksDiscoveryOptions, j as AuthyonJwtClaims, k as AuthyonServerClientOptions, C as ClientCredentials, l as ClientRequestContext, m as ConfirmApprovalInput, n as ConsumedApproval, o as CreateApprovalInput, p as CreateCredentialInput, q as CreateOrganizationInput, r as CreatePermissionInput, s as CreateTenantCredentialInput, t as CreateUserInput, u as CredentialCreator, v as CredentialDetail, w as CredentialListOptions, x as CredentialPermissionsInput, E as EnvironmentUser, F as FetchHttpAdapter, y as HttpAdapterRequest, z as HttpLogEvent, B as HttpLogger, I as IntrospectResult, D as InviteTenantMemberInput, J as JsonWebKeySet, G as JwksTokenVerifier, K as JwksTokenVerifierOptions, L as LoggingHttpAdapter, M as LoginActivity, O as OpenIdConfiguration, N as Organization, P as OtpCheckResult, Q as Paged, R as PaginationOptions, S as Permission, T as PermissionsByRole, U as ReservedPermissions, V as Role, W as RoleGrant, X as RoleInput, Y as RoleList, Z as RolePermissions, _ as SafeJwtAlgorithm, $ as SubjectApprovals, a0 as SubjectSecurity, a1 as TenantClientValidationResult, a2 as TenantCredentialIssued, a3 as TenantCredentialSummary, a4 as TenantMember, a5 as TenantMemberPage, a6 as TenantMembership, a7 as TenantScopedClient, a8 as TokenResult, a9 as TokenVerificationError, aa as TokenVerificationErrorCode, ab as UpdateOrganizationInput, ac as User, ad as UserScopedClient, ae as ValidateResult, af as VerifiedAccessToken, ag as createClient, ah as normalizeClientIp } from './authyonServerClient-DQzhfaja.cjs';
+export { b as AbilityConditions, c as AbilityEvent, d as AbilityListener, e as AbilityRequirement, f as AbilityRule, A as AbilitySubject, g as AuthorizationContext, a as AuthorizationError, h as AuthorizationOptions, i as AuthyonAbility, j as AuthyonAbilityBuilder, k as AuthyonAbilityOptions, l as AuthyonPermissionSource, E as ExpressAuthorizationMiddlewareOptions, m as ExpressNext, n as ExpressRequestLike, o as ExpressResponseLike, P as PermissionGroup, R as RequestAuthorizationOptions, p as authorizeRequest, q as authorizeToken, r as createAuthorizationErrorResponse, s as createAuthyonAbility, t as createAuthyonRules, u as createExpressAuthorizationMiddleware, v as hasPermission, w as hasPermissionGroup } from './authorization-B82XXf3B.cjs';
 import 'jose';
 
 declare const ErrorCodes: {
@@ -19,10 +19,17 @@ declare const ErrorCodes: {
     readonly InvalidSecondFactorCode: "invalid_code";
     readonly VerificationAttemptsExhausted: "verification_attempts_exhausted";
     readonly MethodNotEnrolled: "method_not_enrolled";
-    readonly InvalidAuthorizationState: "invalid_authorization_state";
-    readonly TransactionMismatch: "transaction_mismatch";
-    readonly AuthorizationNotConsumable: "authorization_not_consumable";
+    readonly InvalidApprovalState: "invalid_authorization_state";
+    readonly PayloadMismatch: "payload_mismatch";
+    readonly ApprovalNotConsumable: "authorization_not_consumable";
     readonly IdempotencyConflict: "idempotency_conflict";
+    readonly UserDisabled: "user_disabled";
+    readonly UserNotFound: "user_not_found";
+    readonly TemporarilyUnavailable: "temporarily_unavailable";
+    readonly InsufficientScope: "insufficient_scope";
+    readonly ApprovalNotFound: "authorization_not_found";
+    readonly SessionRevoked: "session_revoked";
+    readonly TwoFactorTooManyFailures: "user.2fa.too_many_failures";
 };
 type KnownErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
 type AuthyonErrorCategory = "network" | "timeout" | "authentication" | "authorization" | "validation" | "not_found" | "conflict" | "rate_limit" | "server" | "unknown";

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonServerClient } from './authyonServerClient-DmNnjw4z.js';
-export { b as AccessTokenSource, c as AuditEvent, d as AuthyonJwksDiscoveryOptions, e as AuthyonJwtClaims, f as AuthyonServerClientOptions, C as ClientCredentials, g as ClientRequestContext, h as ConfirmFinancialAuthorizationInput, i as ConsumedFinancialAuthorization, j as CreateCredentialInput, k as CreateFinancialAuthorizationInput, l as CreateOrganizationInput, m as CreatePermissionInput, n as CreateTenantCredentialInput, o as CreateUserInput, p as CredentialCreator, q as CredentialDetail, r as CredentialListOptions, s as CredentialPermissionsInput, E as EnvironmentUser, F as FetchHttpAdapter, t as FinancialAssurance, u as FinancialAuthorization, v as FinancialAuthorizationStatus, w as FinancialTransaction, x as FinancialWebAuthnOptions, y as HttpAdapterRequest, z as HttpLogEvent, B as HttpLogger, I as IntrospectResult, D as InviteTenantMemberInput, J as JsonWebKeySet, G as JwksTokenVerifier, K as JwksTokenVerifierOptions, L as LoggingHttpAdapter, M as LoginActivity, O as OpenIdConfiguration, N as Organization, P as Paged, Q as PaginationOptions, R as Permission, S as PermissionsByRole, T as ReservedPermissions, U as Role, V as RoleGrant, W as RoleInput, X as RoleList, Y as RolePermissions, Z as SafeJwtAlgorithm, _ as TenantClientValidationResult, $ as TenantCredentialIssued, a0 as TenantCredentialSummary, a1 as TenantMember, a2 as TenantMemberPage, a3 as TenantMembership, a4 as TenantScopedClient, a5 as TokenResult, a6 as TokenVerificationError, a7 as TokenVerificationErrorCode, a8 as UpdateOrganizationInput, a9 as User, aa as UserScopedClient, ab as ValidateResult, ac as VerifiedAccessToken, ad as createClient, ae as normalizeClientIp } from './authyonServerClient-DmNnjw4z.js';
-export { b as AbilityConditions, c as AbilityEvent, d as AbilityListener, e as AbilityRequirement, f as AbilityRule, A as AbilitySubject, g as AuthorizationContext, a as AuthorizationError, h as AuthorizationOptions, i as AuthyonAbility, j as AuthyonAbilityBuilder, k as AuthyonAbilityOptions, l as AuthyonPermissionSource, E as ExpressAuthorizationMiddlewareOptions, m as ExpressNext, n as ExpressRequestLike, o as ExpressResponseLike, P as PermissionGroup, R as RequestAuthorizationOptions, p as authorizeRequest, q as authorizeToken, r as createAuthorizationErrorResponse, s as createAuthyonAbility, t as createAuthyonRules, u as createExpressAuthorizationMiddleware, v as hasPermission, w as hasPermissionGroup } from './authorization-BF015NDJ.js';
+import { H as HttpAdapter, a as HttpLoggerOptions, A as AuthyonServerClient } from './authyonServerClient-DQzhfaja.js';
+export { b as AccessTokenSource, c as Approval, d as ApprovalAssurance, e as ApprovalPayload, f as ApprovalStatus, g as ApprovalWebAuthnOptions, h as AuditEvent, i as AuthyonJwksDiscoveryOptions, j as AuthyonJwtClaims, k as AuthyonServerClientOptions, C as ClientCredentials, l as ClientRequestContext, m as ConfirmApprovalInput, n as ConsumedApproval, o as CreateApprovalInput, p as CreateCredentialInput, q as CreateOrganizationInput, r as CreatePermissionInput, s as CreateTenantCredentialInput, t as CreateUserInput, u as CredentialCreator, v as CredentialDetail, w as CredentialListOptions, x as CredentialPermissionsInput, E as EnvironmentUser, F as FetchHttpAdapter, y as HttpAdapterRequest, z as HttpLogEvent, B as HttpLogger, I as IntrospectResult, D as InviteTenantMemberInput, J as JsonWebKeySet, G as JwksTokenVerifier, K as JwksTokenVerifierOptions, L as LoggingHttpAdapter, M as LoginActivity, O as OpenIdConfiguration, N as Organization, P as OtpCheckResult, Q as Paged, R as PaginationOptions, S as Permission, T as PermissionsByRole, U as ReservedPermissions, V as Role, W as RoleGrant, X as RoleInput, Y as RoleList, Z as RolePermissions, _ as SafeJwtAlgorithm, $ as SubjectApprovals, a0 as SubjectSecurity, a1 as TenantClientValidationResult, a2 as TenantCredentialIssued, a3 as TenantCredentialSummary, a4 as TenantMember, a5 as TenantMemberPage, a6 as TenantMembership, a7 as TenantScopedClient, a8 as TokenResult, a9 as TokenVerificationError, aa as TokenVerificationErrorCode, ab as UpdateOrganizationInput, ac as User, ad as UserScopedClient, ae as ValidateResult, af as VerifiedAccessToken, ag as createClient, ah as normalizeClientIp } from './authyonServerClient-DQzhfaja.js';
+export { b as AbilityConditions, c as AbilityEvent, d as AbilityListener, e as AbilityRequirement, f as AbilityRule, A as AbilitySubject, g as AuthorizationContext, a as AuthorizationError, h as AuthorizationOptions, i as AuthyonAbility, j as AuthyonAbilityBuilder, k as AuthyonAbilityOptions, l as AuthyonPermissionSource, E as ExpressAuthorizationMiddlewareOptions, m as ExpressNext, n as ExpressRequestLike, o as ExpressResponseLike, P as PermissionGroup, R as RequestAuthorizationOptions, p as authorizeRequest, q as authorizeToken, r as createAuthorizationErrorResponse, s as createAuthyonAbility, t as createAuthyonRules, u as createExpressAuthorizationMiddleware, v as hasPermission, w as hasPermissionGroup } from './authorization-WlwcTBwG.js';
 import 'jose';
 
 declare const ErrorCodes: {
@@ -19,10 +19,17 @@ declare const ErrorCodes: {
     readonly InvalidSecondFactorCode: "invalid_code";
     readonly VerificationAttemptsExhausted: "verification_attempts_exhausted";
     readonly MethodNotEnrolled: "method_not_enrolled";
-    readonly InvalidAuthorizationState: "invalid_authorization_state";
-    readonly TransactionMismatch: "transaction_mismatch";
-    readonly AuthorizationNotConsumable: "authorization_not_consumable";
+    readonly InvalidApprovalState: "invalid_authorization_state";
+    readonly PayloadMismatch: "payload_mismatch";
+    readonly ApprovalNotConsumable: "authorization_not_consumable";
     readonly IdempotencyConflict: "idempotency_conflict";
+    readonly UserDisabled: "user_disabled";
+    readonly UserNotFound: "user_not_found";
+    readonly TemporarilyUnavailable: "temporarily_unavailable";
+    readonly InsufficientScope: "insufficient_scope";
+    readonly ApprovalNotFound: "authorization_not_found";
+    readonly SessionRevoked: "session_revoked";
+    readonly TwoFactorTooManyFailures: "user.2fa.too_many_failures";
 };
 type KnownErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
 type AuthyonErrorCategory = "network" | "timeout" | "authentication" | "authorization" | "validation" | "not_found" | "conflict" | "rate_limit" | "server" | "unknown";

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   JsonHttpClient,
   LoggingHttpAdapter,
   createSharedTransport
-} from "./chunk-TWUVXZOT.js";
+} from "./chunk-WPPEV5BA.js";
 import {
   AuthorizationError,
   AuthyonAbility,
@@ -146,29 +146,20 @@ async function allCredentials(request, path2) {
   throw new Error("Authyon: use listPage for more than 1000 credential pages.");
 }
 
-// ../../internal/core/financial/subjectFinancialAuthorizations.ts
+// ../../internal/core/security/approvals.ts
 function path(id, suffix = "") {
   if (typeof id !== "string" || !id.trim())
-    throw new TypeError("Authyon: a financial authorization id is required.");
+    throw new TypeError("Authyon: an approval id is required.");
   return `/auth/authorizations/${encodeURIComponent(id)}${suffix}`;
 }
-function subjectFinancialAuthorizations(request) {
+function subjectSecurity(request) {
   return {
-    /** GET /auth/authorizations/{id} — the pending transaction, to show before asking for the code. */
-    get: (id) => request(path(id)),
-    /** POST /auth/authorizations/{id}/webauthn/options — passkey options for approving this authorization. */
-    webauthnOptions: (id) => request(path(id, "/webauthn/options"), { method: "POST" }),
-    /**
-     * POST /auth/authorizations/{id}/confirm — approves the transaction.
-     *
-     * Pass the authenticator code or passkey assertion to verify the second
-     * factor inline (recommended). Without `input`, the session itself must
-     * have used a passkey or authenticator code within the last 5 minutes,
-     * otherwise the API answers `step_up_required`.
-     */
-    confirm: (id, input) => request(path(id, "/confirm"), { method: "POST", body: input }),
-    /** POST /auth/authorizations/{id}/reject — the customer declines the transaction. */
-    reject: (id) => request(path(id, "/reject"), { method: "POST" })
+    approvals: {
+      get: (id) => request(path(id)),
+      webauthnOptions: (id) => request(path(id, "/webauthn/options"), { method: "POST" }),
+      confirm: (id, input) => request(path(id, "/confirm"), { method: "POST", body: input }),
+      reject: (id) => request(path(id, "/reject"), { method: "POST" })
+    }
   };
 }
 
@@ -203,7 +194,7 @@ var UserScopedClient = class {
       }
     };
     __privateSet(this, _request, scopedRequest(request, token));
-    this.financialAuthorizations = subjectFinancialAuthorizations(__privateGet(this, _request));
+    this.security = subjectSecurity(__privateGet(this, _request));
   }
 };
 _request = new WeakMap();
@@ -555,46 +546,63 @@ var AuthyonServerClient = class {
         /** GET /permissions/reserved — reserved permission names you can't redefine. */
         reserved: () => this.request("/permissions/reserved", { envBearer: true })
       },
+      audit: {
+        /** GET /env/audit — paginated list of the environment's audit events. */
+        list: (params = {}) => this.request("/env/audit", { envBearer: true, query: params }),
+        /** GET /env/audit/login-activity — paginated login activity in the environment. */
+        loginActivity: (params = {}) => this.request("/env/audit/login-activity", { envBearer: true, query: params })
+      }
+    };
+    // ── Security: one-time codes and approvals ───────────────────────────────
+    //
+    // Everything here runs with the environment credential, which needs the
+    // `authyon:financial:authorize` scope. Keep that credential on the server.
+    this.security = {
+      otp: {
+        /**
+         * POST /env/users/{userId}/otp/verify — checks the user's authenticator
+         * app (TOTP) code. A wrong code returns `{ valid: false }` instead of
+         * throwing. Each code is accepted once; 3 wrong codes in a row sign the
+         * user out everywhere (`sessionsRevoked: true`); 5 lock the check for 15
+         * minutes (`rate_limited`).
+         */
+        check: (userId, code) => this.request(`/env/users/${segment(userId)}/otp/verify`, {
+          method: "POST",
+          envBearer: true,
+          body: { code }
+        })
+      },
       /**
-       * Transaction-bound step-up for financial operations. The environment
-       * credential needs the `authyon:financial:authorize` scope.
+       * The customer approves a payload with their authenticator code or
+       * passkey, once.
        *
-       * 1. `create()` the authorization for the transaction and the customer.
-       * 2. The customer approves it with their authenticator code or passkey
-       *    (`@authyon/auth` → `financialAuthorizations.confirm`).
-       * 3. `consume()` it with the same transaction right before executing it.
+       * 1. `create()` the approval with the payload and the customer.
+       * 2. The customer confirms it (`@authyon/auth` → `security.approvals.confirm`).
+       * 3. `consume()` it right before executing, and execute the returned payload.
        */
-      financialAuthorizations: {
-        /** POST /env/authorizations — registers a transaction awaiting the customer's approval. */
+      approvals: {
+        /** POST /env/authorizations — registers a payload awaiting the customer's approval. */
         create: (input) => {
           const { idempotencyKey, ...body } = input;
-          if (typeof idempotencyKey !== "string" || !idempotencyKey.trim())
-            throw new TypeError("Authyon: `idempotencyKey` is required.");
           return this.request("/env/authorizations", {
             method: "POST",
             envBearer: true,
-            headers: { "Idempotency-Key": idempotencyKey },
+            headers: idempotencyKey ? { "Idempotency-Key": idempotencyKey } : void 0,
             body
           });
         },
         /** GET /env/authorizations/{id} — current status and, once approved, the assurance evidence. */
         get: (id) => this.request(`/env/authorizations/${segment(id)}`, { envBearer: true }),
         /**
-         * POST /env/authorizations/{id}/consume — redeems an approved
-         * authorization exactly once. Resend the same transaction given to
-         * `create()`; any difference fails with `transaction_mismatch`.
+         * POST /env/authorizations/{id}/consume — redeems an approved approval
+         * exactly once and returns the approved payload. Pass `payload` to have
+         * the API check it matches (`payload_mismatch` otherwise).
          */
-        consume: (id, transaction) => this.request(`/env/authorizations/${segment(id)}/consume`, {
+        consume: (id, payload) => this.request(`/env/authorizations/${segment(id)}/consume`, {
           method: "POST",
           envBearer: true,
-          body: transaction
+          body: payload === void 0 ? void 0 : { payload }
         })
-      },
-      audit: {
-        /** GET /env/audit — paginated list of the environment's audit events. */
-        list: (params = {}) => this.request("/env/audit", { envBearer: true, query: params }),
-        /** GET /env/audit/login-activity — paginated login activity in the environment. */
-        loginActivity: (params = {}) => this.request("/env/audit/login-activity", { envBearer: true, query: params })
       }
     };
     // ── Generic permission grants ─────────────────────────────────────────────

package/dist/next.d.cts

@@ -1,6 +1,6 @@
 import { ReactNode } from 'react';
-import { R as RequestAuthorizationOptions, A as AbilitySubject, a as AuthorizationError } from './authorization-B7ynKAud.cjs';
-import { A as AuthyonServerClient } from './authyonServerClient-DmNnjw4z.cjs';
+import { R as RequestAuthorizationOptions, A as AbilitySubject, a as AuthorizationError } from './authorization-B82XXf3B.cjs';
+import { A as AuthyonServerClient } from './authyonServerClient-DQzhfaja.cjs';
 import 'jose';
 
 interface ServerPermissionGuardFallbackContext {

package/dist/next.d.ts

@@ -1,6 +1,6 @@
 import { ReactNode } from 'react';
-import { R as RequestAuthorizationOptions, A as AbilitySubject, a as AuthorizationError } from './authorization-BF015NDJ.js';
-import { A as AuthyonServerClient } from './authyonServerClient-DmNnjw4z.js';
+import { R as RequestAuthorizationOptions, A as AbilitySubject, a as AuthorizationError } from './authorization-WlwcTBwG.js';
+import { A as AuthyonServerClient } from './authyonServerClient-DQzhfaja.js';
 import 'jose';
 
 interface ServerPermissionGuardFallbackContext {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@authyon/server",
-  "version": "0.2.0-beta.14",
+  "version": "0.2.0-beta.15",
   "description": "Authyon SDK for backends — server-to-server organization/member management and access-token verification.",
   "license": "MIT",
   "type": "module",