@authyon/auth 0.2.0-beta.2 → 0.2.0-beta.20

package/dist/{ability-g6nBpOQM.d.ts → ability-BTcayvkM.d.ts}

@@ -1,3 +1,79 @@
+/**
+ * Security methods active on the user's account, as returned in the
+ * `security` field of `GET /auth/me` and `POST /auth/validate`.
+ */
+interface SecurityMethods {
+    /** A password is set (false for accounts created only through SSO or magic link). */
+    password: boolean;
+    /** Authenticator app (TOTP one-time codes). */
+    authenticator: boolean;
+    /** One-time codes sent by email. */
+    emailCode: boolean;
+    /** At least one passkey registered. */
+    passkey: boolean;
+    passkeyCount: number;
+    /** Unused recovery codes left. */
+    recoveryCodes: number;
+    /** SSO providers linked to the account, e.g. `["google", "github"]`. */
+    sso: string[];
+    /** Any second factor is active (authenticator, email code or passkey). */
+    twoFactor: boolean;
+}
+/** Lifecycle of an approval. */
+type ApprovalStatus = "pending" | "approved" | "denied" | "consumed" | "expired";
+/**
+ * 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.
+ */
+type ApprovalPayload = Record<string, unknown>;
+/** Evidence of how the customer proved their identity when approving. */
+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"]`. */
+    amr: string[];
+    /** When the second factor was verified (ISO 8601). */
+    authTime: string;
+}
+/** A request for the customer to approve something with a second factor. */
+interface Approval {
+    id: string;
+    status: ApprovalStatus;
+    subjectId: string;
+    tenantId?: string | null;
+    /** 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;
+    /** Present once approved. */
+    assurance?: ApprovalAssurance | null;
+}
+/** Second factor sent with `confirm()`. */
+type ConfirmApprovalInput = {
+    method: "authenticator";
+    /** Six-digit code from the customer's authenticator app. */
+    code: string;
+} | {
+    method: "webauthn";
+    /** Assertion for the options returned by `webauthnOptions()`. */
+    webAuthn: {
+        ceremonyToken: string;
+        /** JSON-serialized `PublicKeyCredential` from `navigator.credentials.get()`. */
+        assertionJson: string;
+    };
+};
+/** Passkey assertion options for approving one approval. */
+interface ApprovalWebAuthnOptions {
+    ceremonyToken: string;
+    /** JSON `PublicKeyCredentialRequestOptions` to pass to `navigator.credentials.get()`. */
+    optionsJson: string;
+}
+
 interface HttpAdapterRequest {
     url: string;
     method: string;
@@ -55,14 +131,53 @@ declare class LoggingHttpAdapter implements HttpAdapter {
     private log;
 }
 
+/** 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 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?: 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 {
+    /**
+     * GET /auth/me — which security methods the signed-in user has active
+     * (password, authenticator, email code, passkeys, recovery codes, SSO).
+     */
+    methods(): Promise<SecurityMethods>;
+    /** Approve or reject what your backend asked the customer to confirm. */
+    readonly approvals: SubjectApprovals;
+}
+
 interface PaginationOptions {
     skip?: number;
     take?: number;
 }
+/**
+ * The envelope every paged endpoint answers with.
+ *
+ * `page` is the 1-based current page and `perPage` is how many items a page
+ * holds — the same sense `take` has on the way in. Up to Authyon API
+ * 2026-10-21 the two were named `perPage` (holding the page number) and
+ * `pageSize` (holding the limit), so reading them by their names gave the
+ * wrong value without failing. Clients on the older API see `page` undefined
+ * and `perPage` holding a page number.
+ */
 interface Paged<T> {
     data: T[];
-    perPage?: number;
-    pageSize: number;
+    page: number;
+    perPage: number;
     total: number;
     pages: number;
     hasNext: boolean;
@@ -93,12 +208,17 @@ interface Organization {
     name?: string;
     description?: string;
     roles?: string[];
+    /** JSON-encoded values for the organization's configured custom fields. */
+    customFields?: string;
+    /** JSON-encoded metadata visible to members of the organization. */
+    publicMetadata?: string;
 }
 /** POST /auth/tenants — creates an organization owned by the signed-in user. */
 interface CreateOrganizationInput {
     name?: string;
     slug?: string;
     description?: string;
+    customFields?: Record<string, unknown>;
 }
 /** GET /auth/tenants/{organizationId}/members — confirmed against the live API. */
 interface OrganizationMember {
@@ -114,6 +234,109 @@ interface InviteMemberInput {
     email: string;
     roles: string[];
 }
+/**
+ * POST /auth/tenants/{organizationId}/invites — invite an address that may not
+ * have an account yet; accepting creates it. `sendEmail` defaults to `true`;
+ * `false` only returns the link, for delivery through your own channel.
+ */
+interface OrganizationInviteInput {
+    email: string;
+    roles?: string[];
+    sendEmail?: boolean;
+    /**
+     * Where to send the invitee after they accept. Must be registered exactly in
+     * the environment's redirect URIs (the same list SSO and magic link use);
+     * otherwise the API rejects the invite. Comes back on `preview` and `accept`.
+     */
+    redirectUri?: string;
+}
+/** Returned when an invite is created or re-issued. `acceptUrl` is only ever
+ *  readable here — the API keeps a hash of the token, not the token. */
+interface OrganizationInviteIssued {
+    id: string;
+    tenantId: string;
+    email: string;
+    roles: string[];
+    acceptUrl: string;
+    expiresAt: string;
+    emailSent: boolean;
+    redirectUri: string | null;
+}
+type OrganizationInviteStatus = "pending" | "accepted" | "revoked" | "expired";
+interface OrganizationInvite {
+    id: string;
+    tenantId: string;
+    email: string;
+    roles: string[];
+    status: OrganizationInviteStatus;
+    createdAt: string;
+    expiresAt: string;
+    emailSentAt: string | null;
+    acceptedAt: string | null;
+    acceptedByUserId: string | null;
+    revokedAt: string | null;
+    invitedByUserId: string | null;
+    redirectUri: string | null;
+}
+/** POST /auth/tenant-invites/preview — what an accept page shows before the invitee commits. */
+interface OrganizationInvitePreview {
+    tenantId: string;
+    tenantName: string;
+    email: string;
+    roles: string[];
+    expiresAt: string;
+    /** True: accepting only needs the token. False: send a password (and a username when `usernameRequired`). */
+    accountExists: boolean;
+    usernameRequired: boolean;
+    /** Where the issuer asked to send the invitee after accepting, or `null`. */
+    redirectUri: string | null;
+}
+/** Options for POST /auth/password-reset/request. */
+interface PasswordResetRequestOptions {
+    /**
+     * Where to send the person after they change the password. Must be
+     * registered exactly in the environment's redirect URIs (the same list SSO
+     * and magic link use); otherwise the request fails with
+     * `user.password_reset.redirect_uri.not_allowed`. Comes back on
+     * `validatePasswordReset` and `confirmPasswordReset`.
+     */
+    redirectUri?: string;
+}
+/** POST /auth/password-reset/validate — what a live reset token is for. */
+interface PasswordResetPreview {
+    email: string;
+    expiresAt: string;
+    /** Where the reset was asked to end, or `null`. */
+    redirectUri: string | null;
+}
+/** POST /auth/password-reset/confirm — the password is changed. */
+interface PasswordResetCompleted {
+    /** Where the reset was asked to end, or `null`. Navigating there is up to you. */
+    redirectUri: string | null;
+}
+/** POST /auth/tenant-invites/accept — everything but `token` is ignored when the address already has an account. */
+interface AcceptOrganizationInviteInput {
+    token: string;
+    username?: string;
+    password?: string;
+    firstName?: string;
+    lastName?: string;
+    /**
+     * @deprecated Use `publicMetadata` / `privateMetadata` through
+     * `@authyon/server` (`environment.tenants.invites.accept`), which runs on
+     * your backend with the environment credential. Still accepted for now.
+     */
+    customFields?: Record<string, unknown>;
+}
+interface OrganizationInviteAccepted {
+    tenantId: string;
+    tenantName: string;
+    userId: string;
+    /** True when accepting created the account (email already confirmed). The invitee still signs in normally. */
+    accountCreated: boolean;
+    /** Where the issuer asked to send the invitee, or `null`. Redirecting is up to the accept page. */
+    redirectUri: string | null;
+}
 /** Authenticated user profile. */
 interface User {
     id: string;
@@ -130,6 +353,8 @@ interface User {
     activeOrganization?: Organization | null;
     /** Actions the user must complete before continuing (e.g. confirm e-mail). */
     pendencies?: string[];
+    /** Security methods active on the account (authenticator, email code, passkey, SSO…). */
+    security?: SecurityMethods;
 }
 /** Token pair issued by login / refresh / tenant switch. */
 interface Session {
@@ -157,6 +382,8 @@ interface RegisterInput {
     email: string;
     username?: string;
     password: string;
+    /** Values for custom user fields configured in the environment. */
+    customFields?: Record<string, unknown>;
 }
 interface LoginInput {
     /** Provide `email` or `username`. */
@@ -289,6 +516,12 @@ type AuthState = "signed_out" | "authenticated" | "expired";
 interface AuthyonClientOptions {
     /** Publishable environment key (`pk_live_...` / `pk_test_...`). */
     envKey: string;
+    /**
+     * Originating client IP to forward on every API call as `X-Forwarded-For`.
+     * Browsers cannot reliably discover their public IP by themselves; set this
+     * only when your application receives it from trusted infrastructure.
+     */
+    clientIp?: string;
     /** API origin. Defaults to `https://api.authyon.com`; HTTPS is required outside loopback. */
     baseUrl?: string;
     /** Allow an HTTP `baseUrl`. Intended only for explicitly trusted local development. */
@@ -312,6 +545,7 @@ interface AuthyonClientOptions {
 
 declare class AuthyonClient {
     private readonly envKey;
+    private readonly clientIp?;
     private readonly baseUrl;
     private readonly storage;
     private readonly autoRefresh;
@@ -415,14 +649,33 @@ declare class AuthyonClient {
          * the endpoint differs, override via a raw call to your own backend.
          */
         revokeSession: (sessionId: string) => Promise<void>;
-        /** POST /auth/password-reset/request — always resolves (no account enumeration). */
-        requestPasswordReset: (email: string) => Promise<void>;
-        /** POST /auth/password-reset/confirm — sets a new password and revokes all refresh tokens. */
-        confirmPasswordReset: (token: string, newPassword: string) => Promise<void>;
+        /**
+         * POST /auth/password-reset/request — resolves whether or not the address
+         * has an account (no account enumeration). `redirectUri` is where the
+         * person lands after changing the password; it must be one of the
+         * environment's registered redirect URIs, or the call rejects with
+         * `user.password_reset.redirect_uri.not_allowed`.
+         */
+        requestPasswordReset: (email: string, options?: PasswordResetRequestOptions) => Promise<void>;
+        /**
+         * POST /auth/password-reset/validate — checks a reset token without
+         * spending it, so the reset page can refuse a dead link before asking for
+         * a password. Rejects with `user.password_reset.invalid` (401) when the
+         * token is unknown, used or expired.
+         */
+        validatePasswordReset: (token: string) => Promise<PasswordResetPreview>;
+        /**
+         * POST /auth/password-reset/confirm — sets a new password and revokes all
+         * refresh tokens. Resolves with the `redirectUri` the reset was requested
+         * with (`null` when there was none); following it is up to the caller.
+         */
+        confirmPasswordReset: (token: string, newPassword: string) => Promise<PasswordResetCompleted>;
     };
     readonly organization: {
-        /** GET /auth/tenants — all organization memberships. */
-        list: () => Promise<Organization[]>;
+        /** GET /auth/tenants — filterable list of organization memberships. */
+        list: (params?: {
+            search?: string;
+        } & PaginationOptions) => Promise<Organization[]>;
         /**
          * POST /auth/tenants — creates an organization owned by the signed-in
          * user (only available when self-service organization creation is
@@ -448,11 +701,53 @@ declare class AuthyonClient {
              * (`user.activities()`, `@authyon/server`'s `environment.users.list()`).
              */
             list: (organizationId: string, params?: PaginationOptions) => Promise<Paged<OrganizationMember>>;
-            /** POST /auth/tenants/{organizationId}/members — invite a member by e-mail. */
+            /**
+             * POST /auth/tenants/{organizationId}/members — add an existing
+             * environment user by e-mail (no e-mail is sent). To invite an address
+             * that may not have an account yet, use `organization.invites.create`.
+             */
             invite: (organizationId: string, params: InviteMemberInput) => Promise<void>;
             /** DELETE /auth/tenants/{organizationId}/members/{userId} — remove a member. */
             remove: (organizationId: string, userId: string) => Promise<void>;
         };
+        /**
+         * Invites by e-mail or by link. Managing them requires the
+         * `tenants:members:invite` permission on the organization; `preview` and
+         * `accept` are public — the token in the link is the credential.
+         */
+        invites: {
+            /** GET /auth/tenants/{organizationId}/invites — every invite with its status, newest first. */
+            list: (organizationId: string) => Promise<OrganizationInvite[]>;
+            /**
+             * POST /auth/tenants/{organizationId}/invites — invite an address.
+             * Always returns `acceptUrl`; with `sendEmail: false` Authyon does not
+             * mail it and you deliver the link yourself. The link is valid for 7
+             * days, once, and can't be read again later.
+             */
+            create: (organizationId: string, params: OrganizationInviteInput) => Promise<OrganizationInviteIssued>;
+            /**
+             * POST /auth/tenants/{organizationId}/invites/{inviteId}/resend — issue
+             * a new link (the previous one stops working), mailing it unless
+             * `sendEmail` is `false`.
+             */
+            resend: (organizationId: string, inviteId: string, params?: {
+                sendEmail?: boolean;
+            }) => Promise<OrganizationInviteIssued>;
+            /** DELETE /auth/tenants/{organizationId}/invites/{inviteId} — revoke a pending invite. */
+            revoke: (organizationId: string, inviteId: string) => Promise<void>;
+            /**
+             * POST /auth/tenant-invites/preview — public. Read the `token` query
+             * parameter of the invite link and pick the form: one click when
+             * `accountExists`, sign-up otherwise.
+             */
+            preview: (token: string) => Promise<OrganizationInvitePreview>;
+            /**
+             * POST /auth/tenant-invites/accept — public. Joins the organization; for
+             * an address with no account, also creates it (password required) with
+             * the e-mail already confirmed. Does not sign the user in.
+             */
+            accept: (params: AcceptOrganizationInviteInput) => Promise<OrganizationInviteAccepted>;
+        };
         roles: {
             /** GET /auth/tenants/{organizationId}/roles — roles available in the organization. */
             list: (organizationId: string) => Promise<Role[]>;
@@ -502,6 +797,13 @@ declare class AuthyonClient {
             assertionStart: (challengeToken: string) => Promise<WebAuthnCeremonyStart>;
         };
     };
+    /**
+     * `security.approvals`: approve or reject what your backend asked the
+     * customer to confirm (`@authyon/server` → `security.approvals.create`).
+     * Show the payload with `get()`, then `confirm()` with the customer's
+     * authenticator code or passkey, or `reject()`.
+     */
+    readonly security: SubjectSecurity;
     /**
      * POST /auth/introspect — lightweight token introspection (RFC 7662).
      *
@@ -578,6 +880,13 @@ interface AuthyonPermissionSource {
     /** 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. */
@@ -611,7 +920,12 @@ declare class AuthyonAbilityBuilder {
 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[];
 
-export { createAuthyonRules as $, AuthyonClient as A, type SessionControllerOptions as B, type CreateOrganizationInput as C, type SessionInfo as D, type SessionSnapshot as E, FetchHttpAdapter as F, type SessionSnapshotListener as G, type HttpAdapter as H, type IntrospectResult as I, type SessionStatus as J, type SsoProvider as K, LoggingHttpAdapter as L, type TwoFactorChallenge as M, type TwoFactorMethod as N, type Organization as O, type Paged as P, type TwoFactorStatus as Q, type RegisterInput as R, type Session as S, type TokenStorage as T, type User as U, type ValidateResult as V, type VerifyTwoFactorInput as W, type WebAuthnAssertion as X, type WebAuthnCeremonyStart as Y, type WebAuthnCredential as Z, createAuthyonAbility as _, type HttpLoggerOptions as a, createClient as a0, hasPermission as a1, type AbilityConditions as b, type AbilityEvent as c, type AbilityListener as d, type AbilityRule as e, type AbilitySubject as f, type Activity as g, type AuthEvent as h, type AuthState as i, type AuthStateListener as j, type AuthenticatorSetup as k, AuthyonAbility as l, AuthyonAbilityBuilder as m, type AuthyonAbilityOptions as n, type AuthyonClientOptions as o, type AuthyonPermissionSource as p, AuthyonSessionController as q, type HttpAdapterRequest as r, type HttpLogEvent as s, type HttpLogger as t, type InviteMemberInput as u, type LoginInput as v, type LoginResult as w, type OrganizationMember as x, type PaginationOptions as y, type Role as z };
+export { type SecurityMethods as $, AuthyonClient as A, type HttpLogger as B, type ConfirmApprovalInput as C, type InviteMemberInput as D, type LoginInput as E, FetchHttpAdapter as F, type LoginResult as G, type HttpAdapter as H, type IntrospectResult as I, type OrganizationInvite as J, type OrganizationInviteAccepted as K, LoggingHttpAdapter as L, type OrganizationInviteInput as M, type OrganizationInviteIssued as N, type Organization as O, type OrganizationInvitePreview as P, type OrganizationInviteStatus as Q, type OrganizationMember as R, type Paged as S, type TokenStorage as T, type PaginationOptions as U, type PasswordResetCompleted as V, type PasswordResetPreview as W, type PasswordResetRequestOptions as X, type PermissionGroup as Y, type RegisterInput as Z, type Role as _, type HttpLoggerOptions as a, type Session as a0, type SessionControllerOptions as a1, type SessionInfo as a2, type SessionSnapshot as a3, type SessionSnapshotListener as a4, type SessionStatus as a5, type SsoProvider as a6, type SubjectApprovals as a7, type SubjectSecurity as a8, type TwoFactorChallenge as a9, type TwoFactorMethod as aa, type TwoFactorStatus as ab, type User as ac, type ValidateResult as ad, type VerifyTwoFactorInput as ae, type WebAuthnAssertion as af, type WebAuthnCeremonyStart as ag, type WebAuthnCredential as ah, createAuthyonAbility as ai, createAuthyonRules as aj, createClient as ak, hasPermission as al, hasPermissionGroup as am, type AbilityConditions as b, type AbilityEvent as c, type AbilityListener as d, type AbilityRule as e, type AbilitySubject as f, type AcceptOrganizationInviteInput as g, type Activity as h, type Approval as i, type ApprovalAssurance as j, type ApprovalPayload as k, type ApprovalStatus as l, type ApprovalWebAuthnOptions as m, type AuthEvent as n, type AuthState as o, type AuthStateListener as p, type AuthenticatorSetup as q, AuthyonAbility as r, AuthyonAbilityBuilder as s, type AuthyonAbilityOptions as t, type AuthyonClientOptions as u, type AuthyonPermissionSource as v, AuthyonSessionController as w, type CreateOrganizationInput as x, type HttpAdapterRequest as y, type HttpLogEvent as z };

package/dist/{chunk-EHZEUM47.js → chunk-3XJY6BCI.js}

@@ -201,6 +201,11 @@ function hasPermission(source, requiredPermission) {
   const permissionSource = isPermissionList(source) ? { permissions: source } : source;
   return createAuthyonAbility(permissionSource).can(requirement.action, requirement.subject);
 }
+function hasPermissionGroup(source, group) {
+  const hasAll = (group.allOf ?? []).every((permission) => hasPermission(source, permission));
+  const hasAny = !group.anyOf?.length || group.anyOf.some((permission) => hasPermission(source, permission));
+  return hasAll && hasAny;
+}
 function isPermissionList(source) {
   return Array.isArray(source);
 }
@@ -319,5 +324,6 @@ export {
   AuthyonAbilityBuilder,
   createAuthyonAbility,
   hasPermission,
+  hasPermissionGroup,
   createAuthyonRules
 };