@authn-sh/sdk-node 0.4.0-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,728 @@
+export { AuthnApiError, AuthnConfigError, AuthnHttpError, AuthnTokenInvalidError, AuthnWebhookSignatureInvalidError } from './errors.js';
+
+/**
+ * Pagination + ordering parameters shared by every `list*` BAPI call.
+ * Resource-specific filter params extend this with their own fields.
+ */
+declare class ListParams {
+    limit?: number | undefined;
+    offset?: number | undefined;
+    orderBy?: string | undefined;
+    constructor(limit?: number | undefined, offset?: number | undefined, orderBy?: string | undefined);
+    toQuery(): Record<string, unknown>;
+}
+
+interface TransportOptions {
+    /** API base URL — typically `https://api.authn.sh/v1`. Trailing `/v1` is required. */
+    apiUrl: string;
+    /** Workspace-scoped secret key (`sk_test_…` / `sk_live_…`). */
+    secretKey: string;
+    /** Override the global fetch (e.g. for testing / proxying). */
+    fetch?: typeof fetch;
+    /** Default request timeout in milliseconds. Default 10_000. */
+    timeoutMs?: number;
+    /** User-Agent suffix, appended after `@authn-sh/sdk-node@<version>`. */
+    userAgentSuffix?: string;
+}
+interface RequestOptions {
+    /** Query parameters appended to the URL. Falsy values dropped. */
+    query?: Record<string, unknown>;
+    /** Body to send as JSON. */
+    body?: unknown;
+    /** Idempotency-Key header. */
+    idempotencyKey?: string;
+    /** Per-request timeout override. */
+    timeoutMs?: number;
+    /** Extra headers. Don't override Authorization / Content-Type. */
+    headers?: Record<string, string>;
+}
+/**
+ * Tiny fetch-based BAPI client. Bearer-authenticates with the workspace
+ * secret key, raises `AuthnHttpError` on non-2xx, returns parsed JSON
+ * on 2xx (or `null` on 204).
+ *
+ * Designed to run anywhere `fetch` exists: Node 18+, Edge runtimes,
+ * Cloudflare Workers, Vercel Edge, Bun, Deno.
+ */
+declare class Transport {
+    private readonly apiUrl;
+    private readonly secretKey;
+    private readonly fetcher;
+    private readonly defaultTimeoutMs;
+    private readonly userAgent;
+    constructor(opts: TransportOptions);
+    /**
+     * Send a request and parse the response as JSON. For 204 returns `null`.
+     * Throws AuthnHttpError on non-2xx.
+     */
+    send<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+    private buildUrl;
+    private extractApiErrors;
+}
+
+/**
+ * Base class for BAPI resource managers. Holds the shared Transport so
+ * subclasses can `.send()` without juggling auth themselves.
+ */
+declare abstract class Manager {
+    protected readonly transport: Transport;
+    constructor(transport: Transport);
+}
+
+/**
+ * Generic paginated-list envelope returned by every `list*` BAPI endpoint.
+ */
+interface PaginatedList<T> {
+    data: T[];
+    totalCount: number;
+}
+
+interface ExternalAccount {
+    id: string;
+    object: 'external_account';
+    provider: string;
+    providerKey: string;
+    providerUserId: string;
+    emailAddress?: string | null;
+    scopes: string[];
+    publicMetadata: Record<string, unknown>;
+    verified: boolean;
+    linkedAt?: number | null;
+    lastSignedInAt?: number | null;
+    raw: Record<string, unknown>;
+}
+declare class ExternalAccountsListParams extends ListParams {
+    userId?: string | undefined;
+    oauthProviderId?: string | undefined;
+    constructor(userId?: string | undefined, oauthProviderId?: string | undefined, limit?: number, offset?: number, orderBy?: string);
+    toQuery(): Record<string, unknown>;
+}
+declare class ExternalAccountsManager extends Manager {
+    list(params?: ExternalAccountsListParams): Promise<PaginatedList<ExternalAccount>>;
+    get(externalAccountId: string): Promise<ExternalAccount>;
+    delete(externalAccountId: string): Promise<void>;
+}
+declare function hydrateExternalAccount(raw: unknown): ExternalAccount;
+
+interface InstanceSettings {
+    id: string;
+    object: 'instance';
+    attributes: Record<string, unknown>;
+    multiFactor: Record<string, unknown>;
+    signUpMode?: string;
+    raw: Record<string, unknown>;
+}
+declare class InstanceManager extends Manager {
+    get(): Promise<InstanceSettings>;
+    update(patch: Record<string, unknown>): Promise<InstanceSettings>;
+    updateRestrictions(patch: Record<string, unknown>): Promise<InstanceSettings>;
+    updateOrganizationSettings(patch: Record<string, unknown>): Promise<InstanceSettings>;
+}
+declare function hydrateInstance(raw: unknown): InstanceSettings;
+
+interface Invitation {
+    id: string;
+    object: 'invitation';
+    emailAddress: string;
+    status: string;
+    redirectUrl?: string | null;
+    publicMetadata: Record<string, unknown>;
+    expiresAt?: number | null;
+    url?: string | null;
+    createdAt: number;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+declare class InvitationsListParams extends ListParams {
+    status?: string[] | undefined;
+    emailAddress?: string | undefined;
+    constructor(status?: string[] | undefined, emailAddress?: string | undefined, limit?: number, offset?: number, orderBy?: string);
+    toQuery(): Record<string, unknown>;
+}
+declare class InvitationsManager extends Manager {
+    list(params?: InvitationsListParams): Promise<PaginatedList<Invitation>>;
+    create(data: Record<string, unknown>, idempotencyKey?: string): Promise<Invitation>;
+    bulkCreate(invitations: Array<Record<string, unknown>>, idempotencyKey?: string): Promise<Invitation[]>;
+    revoke(invitationId: string): Promise<Invitation>;
+}
+declare function hydrateInvitation(raw: unknown): Invitation;
+
+interface AllowlistIdentifier {
+    id: string;
+    object: 'allowlist_identifier';
+    identifier: string;
+    createdAt: number;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+interface BlocklistIdentifier {
+    id: string;
+    object: 'blocklist_identifier';
+    identifier: string;
+    createdAt: number;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+declare class AllowlistIdentifiersManager extends Manager {
+    list(params?: ListParams): Promise<PaginatedList<AllowlistIdentifier>>;
+    create(data: {
+        identifier: string;
+    }): Promise<AllowlistIdentifier>;
+    delete(id: string): Promise<void>;
+}
+declare class BlocklistIdentifiersManager extends Manager {
+    list(params?: ListParams): Promise<PaginatedList<BlocklistIdentifier>>;
+    create(data: {
+        identifier: string;
+    }): Promise<BlocklistIdentifier>;
+    delete(id: string): Promise<void>;
+}
+declare function hydrateAllowlistIdentifier(raw: unknown): AllowlistIdentifier;
+declare function hydrateBlocklistIdentifier(raw: unknown): BlocklistIdentifier;
+
+interface OauthProvider {
+    id: string;
+    object: 'oauth_provider';
+    providerKind: 'preset' | 'custom_oidc' | 'custom_oauth2';
+    providerKey: string;
+    name: string;
+    enabled: boolean;
+    allowSignIn: boolean;
+    allowSignUp: boolean;
+    blockEmailSubaddresses: boolean;
+    clientId: string;
+    scopes: string[];
+    additionalAuthorizationParams: Record<string, unknown>;
+    attributeMapping: Record<string, string>;
+    redirectUri: string;
+    issuer?: string | null;
+    discoveryEndpoint?: string | null;
+    authorizationEndpoint?: string | null;
+    tokenEndpoint?: string | null;
+    userinfoEndpoint?: string | null;
+    jwksUri?: string | null;
+    idTokenSigningAlgs: string[];
+    userinfoMethod?: 'GET' | 'POST' | null;
+    userinfoAuth?: 'bearer' | 'basic' | 'query' | null;
+    createdAt: number;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+interface OauthProviderTestResult {
+    authorizeUrl: string;
+    userinfoStatus: number | null;
+    errors: Array<{
+        code: string;
+        message: string;
+    }>;
+}
+declare class OauthProvidersManager extends Manager {
+    list(params?: ListParams): Promise<PaginatedList<OauthProvider>>;
+    create(data: Record<string, unknown>, idempotencyKey?: string): Promise<OauthProvider>;
+    get(oauthProviderId: string): Promise<OauthProvider>;
+    update(oauthProviderId: string, data: Record<string, unknown>, idempotencyKey?: string): Promise<OauthProvider>;
+    delete(oauthProviderId: string): Promise<void>;
+    test(oauthProviderId: string): Promise<OauthProviderTestResult>;
+}
+declare function hydrateOauthProvider(raw: unknown): OauthProvider;
+
+interface Organization {
+    id: string;
+    object: 'organization';
+    name: string;
+    slug?: string | null;
+    imageUrl?: string | null;
+    membersCount: number;
+    pendingInvitationsCount: number;
+    maxAllowedMemberships?: number | null;
+    adminDeleteEnabled: boolean;
+    publicMetadata: Record<string, unknown>;
+    privateMetadata: Record<string, unknown>;
+    createdBy?: string | null;
+    createdAt: number;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+interface OrganizationMembership {
+    id: string;
+    object: 'organization_membership';
+    organizationId: string;
+    userId: string;
+    role: string;
+    permissions: string[];
+    publicMetadata: Record<string, unknown>;
+    privateMetadata: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+interface OrganizationInvitation {
+    id: string;
+    object: 'organization_invitation';
+    organizationId: string;
+    emailAddress: string;
+    role: string;
+    status: string;
+    inviterUserId?: string | null;
+    redirectUrl?: string | null;
+    publicMetadata: Record<string, unknown>;
+    expiresAt?: number | null;
+    url?: string | null;
+    createdAt: number;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+interface OrganizationDomain {
+    id: string;
+    object: 'organization_domain';
+    organizationId: string;
+    name: string;
+    verified: boolean;
+    enrollmentMode: string;
+    currentChallengeId?: string | null;
+    createdAt: number;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+declare class OrganizationsManager extends Manager {
+    list(params?: ListParams): Promise<PaginatedList<Organization>>;
+    create(data: Record<string, unknown>, idempotencyKey?: string): Promise<Organization>;
+    get(orgId: string): Promise<Organization>;
+    update(orgId: string, data: Record<string, unknown>, idempotencyKey?: string): Promise<Organization>;
+    delete(orgId: string): Promise<void>;
+    members(orgId: string): OrganizationMembershipsManager;
+    invitations(orgId: string): OrganizationInvitationsManager;
+    domains(orgId: string): OrganizationDomainsManager;
+}
+declare class OrganizationMembershipsManager {
+    private readonly transport;
+    private readonly orgId;
+    constructor(transport: Transport, orgId: string);
+    list(params?: ListParams): Promise<PaginatedList<OrganizationMembership>>;
+    create(data: {
+        userId: string;
+        role: string;
+    }, idempotencyKey?: string): Promise<OrganizationMembership>;
+    update(userId: string, role: string, idempotencyKey?: string): Promise<OrganizationMembership>;
+    delete(userId: string): Promise<void>;
+}
+declare class OrganizationInvitationsManager {
+    private readonly transport;
+    private readonly orgId;
+    constructor(transport: Transport, orgId: string);
+    list(params?: ListParams): Promise<PaginatedList<OrganizationInvitation>>;
+    create(data: Record<string, unknown>, idempotencyKey?: string): Promise<OrganizationInvitation>;
+    bulkCreate(invitations: Array<Record<string, unknown>>, idempotencyKey?: string): Promise<OrganizationInvitation[]>;
+    revoke(invitationId: string): Promise<OrganizationInvitation>;
+}
+declare class OrganizationDomainsManager {
+    private readonly transport;
+    private readonly orgId;
+    constructor(transport: Transport, orgId: string);
+    list(): Promise<PaginatedList<OrganizationDomain>>;
+    create(name: string, enrollmentMode?: string): Promise<OrganizationDomain>;
+    get(domainId: string): Promise<OrganizationDomain>;
+    update(domainId: string, patch: Record<string, unknown>): Promise<OrganizationDomain>;
+    delete(domainId: string): Promise<void>;
+}
+declare function hydrateOrganization(raw: unknown): Organization;
+declare function hydrateOrganizationMembership(raw: unknown): OrganizationMembership;
+declare function hydrateOrganizationInvitation(raw: unknown): OrganizationInvitation;
+declare function hydrateOrganizationDomain(raw: unknown): OrganizationDomain;
+
+interface PhoneNumber {
+    id: string;
+    object: 'phone_number';
+    phoneNumber: string;
+    verified: boolean;
+    currentChallengeId?: string | null;
+    isPrimary: boolean;
+    reservedForSecondFactor: boolean;
+    defaultSecondFactor: boolean;
+    linkedToExternalAccountId?: string | null;
+    createdAt: number;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+declare class PhoneNumbersListParams extends ListParams {
+    userId?: string | undefined;
+    constructor(userId?: string | undefined, limit?: number, offset?: number, orderBy?: string);
+    toQuery(): Record<string, unknown>;
+}
+declare class PhoneNumbersManager extends Manager {
+    list(params?: PhoneNumbersListParams): Promise<PaginatedList<PhoneNumber>>;
+    create(data: Record<string, unknown>, idempotencyKey?: string): Promise<PhoneNumber>;
+    get(phoneNumberId: string): Promise<PhoneNumber>;
+    update(phoneNumberId: string, data: Record<string, unknown>, idempotencyKey?: string): Promise<PhoneNumber>;
+    delete(phoneNumberId: string): Promise<void>;
+}
+declare function hydratePhoneNumber(raw: unknown): PhoneNumber;
+
+interface RedirectUrl {
+    id: string;
+    object: 'redirect_url';
+    url: string;
+    createdAt: number;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+declare class RedirectUrlsManager extends Manager {
+    list(params?: ListParams): Promise<PaginatedList<RedirectUrl>>;
+    create(url: string): Promise<RedirectUrl>;
+    get(id: string): Promise<RedirectUrl>;
+    delete(id: string): Promise<void>;
+}
+declare function hydrateRedirectUrl(raw: unknown): RedirectUrl;
+
+interface Role {
+    id: string;
+    object: 'role';
+    key: string;
+    name: string;
+    description?: string | null;
+    isCreatorEligible: boolean;
+    isDefault: boolean;
+    permissions: string[];
+    createdAt: number;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+interface Permission {
+    id: string;
+    object: 'permission';
+    key: string;
+    name: string;
+    description?: string | null;
+    isSystem: boolean;
+    createdAt: number;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+declare class RolesManager extends Manager {
+    list(params?: ListParams): Promise<PaginatedList<Role>>;
+    create(data: Record<string, unknown>, idempotencyKey?: string): Promise<Role>;
+    get(roleId: string): Promise<Role>;
+    update(roleId: string, data: Record<string, unknown>, idempotencyKey?: string): Promise<Role>;
+    delete(roleId: string): Promise<void>;
+    setPermissions(roleId: string, permissionKeys: string[]): Promise<Role>;
+}
+declare class PermissionsManager extends Manager {
+    list(params?: ListParams): Promise<PaginatedList<Permission>>;
+}
+declare function hydrateRole(raw: unknown): Role;
+declare function hydratePermission(raw: unknown): Permission;
+
+interface Session {
+    id: string;
+    object: 'session';
+    clientId: string;
+    userId: string;
+    status: string;
+    lastActiveAt?: number | null;
+    expireAt?: number | null;
+    abandonAt?: number | null;
+    lastActiveOrganizationId?: string | null;
+    createdAt: number;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+declare class SessionsListParams extends ListParams {
+    userId?: string | undefined;
+    clientId?: string | undefined;
+    status?: string[] | undefined;
+    constructor(userId?: string | undefined, clientId?: string | undefined, status?: string[] | undefined, limit?: number, offset?: number, orderBy?: string);
+    toQuery(): Record<string, unknown>;
+}
+declare class SessionsManager extends Manager {
+    list(params?: SessionsListParams): Promise<PaginatedList<Session>>;
+    get(sessionId: string): Promise<Session>;
+    revoke(sessionId: string): Promise<Session>;
+    getToken(sessionId: string, template?: string): Promise<string>;
+}
+declare function hydrateSession(raw: unknown): Session;
+
+type SmsTemplateSlug = 'verification_code' | 'reset_password_code' | 'invitation';
+interface SmsTemplate {
+    id: string;
+    object: 'sms_template';
+    slug: SmsTemplateSlug | string;
+    body: string;
+    deliveredByUs: boolean;
+    fromNumberOverride?: string | null;
+    createdAt: number;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+declare class SmsTemplatesManager extends Manager {
+    list(): Promise<SmsTemplate[]>;
+    get(slug: string): Promise<SmsTemplate>;
+    update(slug: string, data: Record<string, unknown>, idempotencyKey?: string): Promise<SmsTemplate>;
+    revert(slug: string, idempotencyKey?: string): Promise<SmsTemplate>;
+}
+declare function hydrateSmsTemplate(raw: unknown): SmsTemplate;
+
+interface User {
+    id: string;
+    object: 'user';
+    externalId?: string | null;
+    username?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+    imageUrl?: string | null;
+    primaryEmailAddressId?: string | null;
+    primaryPhoneNumberId?: string | null;
+    emailAddresses: Array<Record<string, unknown>>;
+    phoneNumbers: Array<Record<string, unknown>>;
+    externalAccounts: Array<Record<string, unknown>>;
+    passwordEnabled: boolean;
+    totpEnabled: boolean;
+    backupCodesEnabled: boolean;
+    twoFactorEnabled: boolean;
+    banned: boolean;
+    locked: boolean;
+    lastSignInAt?: number | null;
+    lastActiveAt?: number | null;
+    publicMetadata: Record<string, unknown>;
+    privateMetadata: Record<string, unknown>;
+    unsafeMetadata: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+interface TotpVerificationResult {
+    verified: boolean;
+    reason?: string | null;
+}
+declare class UsersListParams extends ListParams {
+    emailAddress?: string[] | undefined;
+    phoneNumber?: string[] | undefined;
+    username?: string[] | undefined;
+    externalId?: string[] | undefined;
+    query?: string | undefined;
+    constructor(emailAddress?: string[] | undefined, phoneNumber?: string[] | undefined, username?: string[] | undefined, externalId?: string[] | undefined, query?: string | undefined, limit?: number, offset?: number, orderBy?: string);
+    toQuery(): Record<string, unknown>;
+}
+declare class UsersManager extends Manager {
+    list(params?: UsersListParams): Promise<PaginatedList<User>>;
+    count(params?: UsersListParams): Promise<number>;
+    create(data: Record<string, unknown>, idempotencyKey?: string): Promise<User>;
+    get(userId: string): Promise<User>;
+    update(userId: string, data: Record<string, unknown>, idempotencyKey?: string): Promise<User>;
+    delete(userId: string): Promise<void>;
+    ban(userId: string): Promise<User>;
+    unban(userId: string): Promise<User>;
+    lock(userId: string): Promise<User>;
+    unlock(userId: string): Promise<User>;
+    updateMetadata(userId: string, patch: Record<string, unknown>): Promise<User>;
+    verifyPassword(userId: string, password: string): Promise<boolean>;
+    verifyTotp(userId: string, code: string): Promise<TotpVerificationResult>;
+    disableMfa(userId: string): Promise<User>;
+    uploadProfileImage(userId: string, bytes: Uint8Array, mime: string): Promise<User>;
+    deleteProfileImage(userId: string): Promise<void>;
+}
+declare function hydrateUser(raw: unknown): User;
+
+interface AuthnOptions {
+    /** Workspace-scoped secret key — `sk_test_…` / `sk_live_…`. */
+    secretKey: string;
+    /** BAPI base URL (host only, no `/v1` — manager paths include it). Default `https://api.authn.sh`. */
+    apiUrl?: string;
+    /** Override the global fetch (testing / proxying). */
+    fetch?: typeof fetch;
+    /** Request timeout in milliseconds. Default 10_000. */
+    timeoutMs?: number;
+    /** User-Agent suffix, appended after `@authn-sh/sdk-node`. */
+    userAgentSuffix?: string;
+}
+/**
+ * BAPI client for authn.sh. Single entry point — instantiate once,
+ * reuse across requests.
+ *
+ * @example
+ *   const authn = new Authn({ secretKey: process.env.AUTHN_SECRET_KEY! });
+ *   const user = await authn.users.get('user_01HXYZ...');
+ *   const session = await authn.sessions.get(req.cookies.authnSessionId);
+ */
+declare class Authn {
+    /** Underlying HTTP transport — exposed for advanced use cases. */
+    readonly transport: Transport;
+    readonly users: UsersManager;
+    readonly sessions: SessionsManager;
+    readonly organizations: OrganizationsManager;
+    readonly oauthProviders: OauthProvidersManager;
+    readonly phoneNumbers: PhoneNumbersManager;
+    readonly externalAccounts: ExternalAccountsManager;
+    readonly smsTemplates: SmsTemplatesManager;
+    readonly invitations: InvitationsManager;
+    readonly allowlistIdentifiers: AllowlistIdentifiersManager;
+    readonly blocklistIdentifiers: BlocklistIdentifiersManager;
+    readonly redirectUrls: RedirectUrlsManager;
+    readonly roles: RolesManager;
+    readonly permissions: PermissionsManager;
+    readonly instance: InstanceManager;
+    constructor(opts: AuthnOptions);
+}
+
+interface VerifiedOrganization {
+    id: string;
+    slug?: string;
+    role?: string;
+    permissions: string[];
+}
+interface VerifiedActor {
+    iss: string;
+    sub: string;
+    sid: string;
+}
+/**
+ * Strongly-typed view of a verified session-JWT's claims.
+ *
+ * Use the helper methods (`hasRole`, `hasPermission`,
+ * `hasVerifiedPhoneNumber`, `preferredSecondFactor`) rather than poking
+ * into `raw` directly — the helpers are the stable surface, raw fields
+ * may change shape.
+ */
+declare class VerifiedClaims {
+    readonly sub: string;
+    readonly sid: string;
+    readonly iss: string;
+    readonly azp: string | null;
+    readonly exp: number;
+    readonly iat: number;
+    readonly nbf: number | null;
+    readonly actor: VerifiedActor | null;
+    readonly organization: VerifiedOrganization | null;
+    readonly wasTest: boolean;
+    readonly twoFactorVerified: boolean;
+    readonly secondFactorAgeSeconds: number | null;
+    readonly firstFactorAgeSeconds: number | null;
+    readonly phoneNumberVerified: boolean;
+    readonly defaultSecondFactor: 'totp' | 'phone_code' | 'backup_code' | null;
+    readonly raw: Record<string, unknown>;
+    constructor(sub: string, sid: string, iss: string, azp: string | null, exp: number, iat: number, nbf: number | null, actor: VerifiedActor | null, organization: VerifiedOrganization | null, wasTest: boolean, twoFactorVerified: boolean, secondFactorAgeSeconds: number | null, firstFactorAgeSeconds: number | null, phoneNumberVerified: boolean, defaultSecondFactor: 'totp' | 'phone_code' | 'backup_code' | null, raw: Record<string, unknown>);
+    hasRole(roleKey: string): boolean;
+    hasPermission(permissionKey: string): boolean;
+    hasVerifiedPhoneNumber(): boolean;
+    preferredSecondFactor(): VerifiedClaims['defaultSecondFactor'];
+}
+/**
+ * Build a VerifiedClaims from a JWT claims-bag (post-signature-verify).
+ */
+declare function buildVerifiedClaims(claims: Record<string, unknown>): VerifiedClaims;
+
+interface TokenVerifierOptions {
+    /**
+     * Workspace publishable key (`pk_test_…` / `pk_live_…`). The verifier
+     * decodes the FAPI host from the key, e.g. `pk_test_<env_slug>` →
+     * `https://<env_slug>.authn.sh`.
+     */
+    publishableKey?: string;
+    /**
+     * Explicit FAPI base URL (`https://<env_slug>.authn.sh`). Use this
+     * when self-hosting on a custom domain — overrides `publishableKey`
+     * decoding.
+     */
+    frontendApiUrl?: string;
+    /** JWKS cache TTL in seconds. Default 600. */
+    jwksCacheTtlSeconds?: number;
+    /** Allowed clock skew on exp/nbf validation in seconds. Default 5. */
+    allowedClockSkewSeconds?: number;
+    /** Override the global fetch (testing). */
+    fetch?: typeof fetch;
+}
+/**
+ * Verifies session JWTs minted by an authn.sh Frontend API.
+ *
+ * Resolves the FAPI's JWKS URL from `publishableKey` or `frontendApiUrl`,
+ * caches it in memory, and validates the signature + expiry + issuer.
+ *
+ * @example
+ *   const verifier = new TokenVerifier({ publishableKey: process.env.AUTHN_PUBLISHABLE_KEY! });
+ *   const claims = await verifier.verify(req.cookies.__session);
+ *   console.log(claims.sub);                  // user_…
+ *   console.log(claims.hasPermission('org:billing:read'));
+ *   console.log(claims.preferredSecondFactor());  // 'totp' | 'phone_code' | 'backup_code' | null
+ */
+declare class TokenVerifier {
+    private readonly frontendApiUrl;
+    private readonly jwks;
+    private readonly allowedClockSkew;
+    constructor(opts?: TokenVerifierOptions);
+    /**
+     * Verify a JWT and return its claims. Throws AuthnTokenInvalidError on failure.
+     *
+     * @param expectedAzp If provided, the token's `azp` must match one of these.
+     */
+    verify(jwt: string, expectedAzp?: string[]): Promise<VerifiedClaims>;
+    /**
+     * Same as `verify` but returns `null` on failure instead of throwing.
+     * Useful for "best-effort" auth that falls back to unauthenticated.
+     */
+    tryVerify(jwt: string, expectedAzp?: string[]): Promise<VerifiedClaims | null>;
+}
+/**
+ * Decode the FAPI URL embedded in a publishable key.
+ *
+ * Publishable keys look like `pk_(test|live)_<base64url-encoded-host>$`.
+ * The host segment is `<env_slug>.authn.sh` (no scheme). We always
+ * emit `https://`.
+ */
+declare function decodeFrontendApiUrl(publishableKey: string): string;
+
+interface WebhookEvent {
+    /** Event type (`user.created`, `phoneNumber.verified`, etc.). */
+    type: string;
+    /** Event payload. Resource shape — depends on `type`. */
+    data: Record<string, unknown>;
+    /** Unix timestamp (seconds) when the event was emitted. */
+    timestamp: number;
+    /** Instance ID the event was emitted from. */
+    instanceId: string;
+    /** Whether the event was generated during a test-mode flow. */
+    wasTest: boolean;
+    /** Message ID (the `svix-id` header value). */
+    messageId: string;
+}
+
+interface WebhookSignatureVerifierOptions {
+    /**
+     * `whsec_…` signing secret. Pass an array to tolerate key rotation —
+     * a request is accepted if any provided signature matches any secret.
+     */
+    signingSecret: string | string[];
+    /** Acceptable clock skew window in seconds. Default 300 (5 min). */
+    toleranceSeconds?: number;
+    /** Override the clock (testing). Returns unix seconds. */
+    now?: () => number;
+}
+/**
+ * Verifies authn.sh webhook signatures (svix-compatible scheme).
+ *
+ * The transport signs `{svix-id}.{svix-timestamp}.{rawBody}` with
+ * HMAC-SHA256 keyed by `whsec_…`. Multiple secrets can be supplied to
+ * tolerate rotation — a request is accepted if any provided signature
+ * matches any configured secret.
+ *
+ * @example
+ *   app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
+ *     const verifier = new WebhookSignatureVerifier({ signingSecret: process.env.AUTHN_WEBHOOK_SECRET! });
+ *     try {
+ *       const event = verifier.verify(req.body.toString('utf8'), req.headers);
+ *       // event.type === 'user.created' | 'phoneNumber.verified' | ...
+ *     } catch (e) {
+ *       return res.status(400).end();
+ *     }
+ *     res.status(204).end();
+ *   });
+ */
+declare class WebhookSignatureVerifier {
+    private readonly secrets;
+    private readonly tolerance;
+    private readonly now;
+    constructor(opts: WebhookSignatureVerifierOptions);
+    verify(rawBody: string, headers: Record<string, string | string[] | undefined>): WebhookEvent;
+    tryVerify(rawBody: string, headers: Record<string, string | string[] | undefined>): WebhookEvent | null;
+    private matchesAny;
+}
+
+export { type AllowlistIdentifier, AllowlistIdentifiersManager, Authn, type AuthnOptions, type BlocklistIdentifier, BlocklistIdentifiersManager, type ExternalAccount, ExternalAccountsListParams, ExternalAccountsManager, InstanceManager, type InstanceSettings, type Invitation, InvitationsListParams, InvitationsManager, ListParams, type OauthProvider, type OauthProviderTestResult, OauthProvidersManager, type Organization, type OrganizationDomain, OrganizationDomainsManager, type OrganizationInvitation, OrganizationInvitationsManager, type OrganizationMembership, OrganizationMembershipsManager, OrganizationsManager, type PaginatedList, type Permission, PermissionsManager, type PhoneNumber, PhoneNumbersListParams, PhoneNumbersManager, type RedirectUrl, RedirectUrlsManager, type RequestOptions, type Role, RolesManager, type Session, SessionsListParams, SessionsManager, type SmsTemplate, type SmsTemplateSlug, SmsTemplatesManager, TokenVerifier, type TokenVerifierOptions, type TotpVerificationResult, Transport, type TransportOptions, type User, UsersListParams, UsersManager, type VerifiedActor, VerifiedClaims, type VerifiedOrganization, type WebhookEvent, WebhookSignatureVerifier, type WebhookSignatureVerifierOptions, buildVerifiedClaims, decodeFrontendApiUrl, hydrateAllowlistIdentifier, hydrateBlocklistIdentifier, hydrateExternalAccount, hydrateInstance, hydrateInvitation, hydrateOauthProvider, hydrateOrganization, hydrateOrganizationDomain, hydrateOrganizationInvitation, hydrateOrganizationMembership, hydratePermission, hydratePhoneNumber, hydrateRedirectUrl, hydrateRole, hydrateSession, hydrateSmsTemplate, hydrateUser };