@authyon/auth 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,403 @@
+/**
+ * Organization membership (the Authyon API calls this a "tenant" on the
+ * wire — the SDK exposes it as "organization").
+ */
+interface Organization {
+    id: string;
+    slug: string;
+    name?: string;
+    description?: string;
+    roles?: string[];
+}
+/** POST /auth/tenants — creates an organization owned by the signed-in user. */
+interface CreateOrganizationParams {
+    name?: string;
+    slug?: string;
+    description?: string;
+}
+interface OrganizationMember {
+    userId: string;
+    email?: string;
+    roles?: string[];
+}
+/** POST /auth/tenants/{tenantId}/members — invites a member by e-mail. */
+interface InviteMemberParams {
+    email: string;
+    roles: string[];
+}
+/** Pagination options accepted by list endpoints. */
+interface PageParams {
+    skip?: number;
+    take?: number;
+}
+/** Authenticated user profile. */
+interface User {
+    id: string;
+    email: string;
+    username?: string;
+    organizations?: Organization[];
+    activeOrganization?: Organization | null;
+    permissions?: string[];
+}
+/** Token pair issued by login / refresh / tenant switch. */
+interface Session {
+    accessToken: string;
+    refreshToken: string;
+    /** Access-token lifetime in seconds (typically 1800). */
+    expiresIn: number;
+    /** Epoch ms when the access token expires (computed client-side). */
+    expiresAt: number;
+    user?: User;
+}
+type TwoFactorMethod = "authenticator" | "email" | "webauthn" | string;
+/** Returned by `login()` when the account has 2FA enabled. */
+interface TwoFactorChallenge {
+    twoFactorRequired: true;
+    challengeToken: string;
+    methods: TwoFactorMethod[];
+    emailHint?: string;
+}
+type LoginResult = {
+    twoFactorRequired: false;
+    session: Session;
+} | TwoFactorChallenge;
+interface RegisterParams {
+    email: string;
+    username?: string;
+    password: string;
+}
+interface LoginParams {
+    /** Provide `email` or `username`. */
+    email?: string;
+    username?: string;
+    password: string;
+    /** Optional organization to scope the session to (sent as `tenantSlug`). */
+    organizationSlug?: string;
+}
+/** A completed WebAuthn ceremony, handed back to the server to finish login/registration. */
+interface WebAuthnAssertion {
+    ceremonyToken: string;
+    /** JSON-serialized `PublicKeyCredential` returned by `navigator.credentials.get()`. */
+    assertionJson: string;
+}
+/** POST /auth/2fa/verify — redeems a challenge from `login()`. */
+interface TwoFactorVerifyParams {
+    challengeToken: string;
+    method: TwoFactorMethod;
+    /** TOTP / email / recovery code. Omit when `method` is `"webauthn"`. */
+    code?: string;
+    /** Required when `method` is `"webauthn"`. */
+    webAuthnAssertion?: WebAuthnAssertion;
+}
+interface TwoFactorStatus {
+    methods: TwoFactorMethod[];
+    recoveryCodesRemaining?: number;
+}
+interface AuthenticatorSetup {
+    secret: string;
+    qrSvg: string;
+    otpauthUri: string;
+}
+/**
+ * Options handed back by a WebAuthn "start" endpoint: a ceremony token to
+ * correlate the "finish" call, plus the WebAuthn options object to pass into
+ * `navigator.credentials.get()` / `.create()` (after `JSON.parse`, per the
+ * WebAuthn spec — challenge/user.id are base64url strings on the wire).
+ *
+ * ⚠️ The exact shape of `options` is not published in the OpenAPI schema (no
+ * response bodies are documented for any endpoint at the time this SDK was
+ * written) — treat it as opaque input to the WebAuthn API.
+ */
+interface WebAuthnCeremonyStart {
+    ceremonyToken: string;
+    options: unknown;
+}
+interface WebAuthnCredential {
+    id: string;
+    nickname?: string;
+    createdAt?: string;
+}
+interface SsoProvider {
+    name: string;
+    slug: string;
+    /** URL to redirect the browser to in order to start this provider's flow. */
+    startUrl: string;
+}
+interface Activity {
+    id: string;
+    type: string;
+    createdAt: string;
+    ip?: string;
+    device?: string;
+}
+/** A role available within an organization (tenant). */
+interface Role {
+    id: string;
+    name: string;
+    description?: string;
+    permissions?: string[];
+}
+interface SessionInfo {
+    id: string;
+    createdAt?: string;
+    lastUsedAt?: string;
+    ip?: string;
+    device?: string;
+    current?: boolean;
+}
+interface IntrospectResult {
+    active: boolean;
+    sub?: string;
+    client_id?: string;
+    scope?: string;
+    exp?: number;
+    token_type?: string;
+}
+interface ValidateResult {
+    user: User;
+    organization?: Organization | null;
+}
+type AuthEvent = {
+    type: "signed_in";
+    session: Session;
+} | {
+    type: "refreshed";
+    session: Session;
+} | {
+    type: "signed_out";
+};
+type AuthStateListener = (event: AuthEvent) => void;
+/** Pluggable persistence for the token pair. */
+interface TokenStorage {
+    get(): Session | null;
+    set(session: Session): void;
+    clear(): void;
+}
+interface AuthyonClientOptions {
+    /** Publishable environment key (`pk_live_...` / `pk_test_...`). */
+    envKey: string;
+    /** API origin. Defaults to `https://api.authyon.com`. */
+    baseUrl?: string;
+    /** Where tokens are persisted. Defaults to localStorage when available, memory otherwise. */
+    storage?: TokenStorage;
+    /**
+     * Automatically refresh the access token shortly before it expires and
+     * retry once on 401. Defaults to `true`.
+     */
+    autoRefresh?: boolean;
+    /** Custom fetch implementation (useful for tests / non-browser runtimes). */
+    fetch?: typeof fetch;
+}
+
+declare class AuthyonClient {
+    private readonly envKey;
+    private readonly baseUrl;
+    private readonly storage;
+    private readonly autoRefresh;
+    private readonly fetchImpl;
+    private readonly listeners;
+    private refreshInFlight;
+    constructor(options: AuthyonClientOptions);
+    /** Current persisted session, or null when signed out. */
+    getSession(): Session | null;
+    isAuthenticated(): boolean;
+    /**
+     * Returns a valid access token, refreshing it transparently when it is
+     * expired or about to expire. Returns null when signed out.
+     */
+    getAccessToken(): Promise<string | null>;
+    /** Subscribe to sign-in / refresh / sign-out events. Returns an unsubscribe fn. */
+    onAuthStateChange(listener: AuthStateListener): () => void;
+    private emit;
+    private setSession;
+    private clearSession;
+    private request;
+    private toError;
+    /** POST /auth/register — creates a new user (rate-limited to 20/hour per IP). */
+    register(params: RegisterParams): Promise<{
+        id: string;
+    }>;
+    /**
+     * POST /auth/login — authenticates and stores the session, or returns a
+     * 2FA challenge to complete via `verifyTwoFactor()`.
+     */
+    login(params: LoginParams): Promise<LoginResult>;
+    /** POST /auth/2fa/verify — redeems a 2FA challenge from `login()` and stores the session. */
+    verifyTwoFactor(params: TwoFactorVerifyParams): Promise<Session>;
+    /** POST /auth/refresh — rotates the single-use refresh token (single-flight). */
+    refresh(): Promise<Session>;
+    /**
+     * POST /auth/logout — revokes the current refresh token and clears local
+     * state. Pass `{ everywhere: true }` to revoke every session for the user.
+     */
+    logout(options?: {
+        everywhere?: boolean;
+    }): Promise<void>;
+    readonly webauthn: {
+        /** POST /auth/webauthn/login/start — begins a passkey sign-in. */
+        loginStart: (email?: string) => Promise<WebAuthnCeremonyStart>;
+        /**
+         * POST /auth/webauthn/login/finish — completes the passkey ceremony and
+         * stores the session.
+         */
+        loginFinish: (assertion: WebAuthnAssertion) => Promise<Session>;
+    };
+    readonly sso: {
+        /** GET /auth/sso/providers — providers enabled for this environment. */
+        providers: () => Promise<SsoProvider[]>;
+        /**
+         * Builds the URL to redirect the browser to in order to start a
+         * provider's sign-in flow (`GET /auth/sso/{provider}/start`). Navigate
+         * to it directly — e.g. `window.location.href = client.sso.startUrl(...)`.
+         */
+        startUrl: (provider: string, params: {
+            redirectUri: string;
+            state?: string;
+            mode?: string;
+        }) => string;
+        /**
+         * POST /auth/sso/exchange — swaps the one-time code from the provider
+         * callback for tokens and stores the session.
+         */
+        exchange: (code: string) => Promise<Session>;
+    };
+    readonly user: {
+        /** GET /auth/me — fresh profile of the current user. */
+        me: () => Promise<User>;
+        /** GET /auth/sessions — active refresh-token sessions with device/IP data. */
+        sessions: () => Promise<SessionInfo[]>;
+        /** GET /auth/me/activities — recent account activity for the current user. */
+        activities: (params?: PageParams) => Promise<Activity[]>;
+        /**
+         * Revokes a single session by id (e.g. one entry from `sessions()`),
+         * signing that device out without affecting the current one.
+         *
+         * ⚠️ Not directly confirmed against the published API reference at the
+         * time this SDK was written — `DELETE /auth/sessions/{id}` follows the
+         * REST convention the rest of the documented API uses, but verify it
+         * against the Authyon dashboard/API reference before relying on it. If
+         * 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>;
+    };
+    readonly organization: {
+        /** GET /auth/tenants — all organization memberships. */
+        list: () => Promise<Organization[]>;
+        /**
+         * POST /auth/tenants — creates an organization owned by the signed-in
+         * user (only available when self-service organization creation is
+         * enabled for the environment).
+         */
+        create: (params?: CreateOrganizationParams) => Promise<Organization>;
+        /** GET /auth/tenants/{organizationId} — fetch one of the user's organizations by id. */
+        get: (organizationId: string) => Promise<Organization>;
+        /**
+         * PATCH /auth/tenants/{organizationId} — renames the organization.
+         * Requires the `tenants:manage` custom permission on it.
+         */
+        rename: (organizationId: string, name: string) => Promise<Organization>;
+        /** POST /auth/switch-tenant — issues a fresh token scoped to the new organization. */
+        switch: (organizationSlug: string) => Promise<Session>;
+        /** The organization the current session is scoped to, from the cached session — no network call. */
+        current: () => Organization | null;
+        members: {
+            /** GET /auth/tenants/{organizationId}/members — list an organization's members. */
+            list: (organizationId: string, params?: PageParams) => Promise<OrganizationMember[]>;
+            /** POST /auth/tenants/{organizationId}/members — invite a member by e-mail. */
+            invite: (organizationId: string, params: InviteMemberParams) => Promise<void>;
+            /** DELETE /auth/tenants/{organizationId}/members/{userId} — remove a member. */
+            remove: (organizationId: string, userId: string) => Promise<void>;
+        };
+        roles: {
+            /** GET /auth/tenants/{organizationId}/roles — roles available in the organization. */
+            list: (organizationId: string) => Promise<Role[]>;
+        };
+    };
+    readonly twoFactor: {
+        /** GET /auth/2fa/status — enrolled methods and recovery code count. */
+        status: () => Promise<TwoFactorStatus>;
+        /** POST /auth/2fa/resend-email — resends the code for an in-flight login challenge. */
+        resendEmail: (challengeToken: string) => Promise<void>;
+        /** POST /auth/2fa/authenticator/setup — returns secret, QR SVG and otpauth URI. */
+        setupAuthenticator: () => Promise<AuthenticatorSetup>;
+        /** POST /auth/2fa/authenticator/confirm — returns 10 single-use recovery codes. */
+        confirmAuthenticator: (code: string) => Promise<{
+            recoveryCodes: string[];
+        }>;
+        /**
+         * POST /auth/2fa/email/enable — two-step opt-in for email-based OTP.
+         * Call without `code` to receive one by e-mail, then call again with
+         * that code to confirm enrolment.
+         */
+        enableEmail: (code?: string) => Promise<void>;
+        /** POST /auth/2fa/disable — turns off a specific 2FA method (requires current password). */
+        disable: (method: TwoFactorMethod, currentPassword: string) => Promise<void>;
+        /**
+         * POST /auth/2fa/recovery-codes/regenerate — rotates the 10 single-use
+         * recovery codes (requires current password).
+         */
+        regenerateRecoveryCodes: (currentPassword: string) => Promise<{
+            recoveryCodes: string[];
+        }>;
+        webauthn: {
+            /** POST /auth/2fa/webauthn/register/start — begins passkey enrolment for 2FA. */
+            registerStart: () => Promise<WebAuthnCeremonyStart>;
+            /** POST /auth/2fa/webauthn/register/finish — finishes passkey enrolment. */
+            registerFinish: (ceremonyToken: string, attestationJson: string, nickname?: string) => Promise<WebAuthnCredential>;
+            /** GET /auth/2fa/webauthn/credentials — the caller's registered passkeys. */
+            credentials: () => Promise<WebAuthnCredential[]>;
+            /** PATCH /auth/2fa/webauthn/credentials/{id} — renames a passkey. */
+            renameCredential: (id: string, nickname: string) => Promise<WebAuthnCredential>;
+            /** DELETE /auth/2fa/webauthn/credentials/{id} — removes a passkey (requires current password). */
+            removeCredential: (id: string, currentPassword: string) => Promise<void>;
+            /**
+             * POST /auth/2fa/webauthn/assertion/start — fetches WebAuthn assertion
+             * options for an in-flight login challenge (2FA method `"webauthn"`).
+             */
+            assertionStart: (challengeToken: string) => Promise<WebAuthnCeremonyStart>;
+        };
+    };
+    /** POST /auth/introspect — lightweight token introspection. */
+    introspect(token?: string): Promise<IntrospectResult>;
+    /** POST /auth/validate — recommended: cross-checks DB state, returns user + organization. */
+    validate(token?: string): Promise<ValidateResult>;
+}
+/** Convenience factory: `const authyon = createClient({ envKey: "pk_live_..." })`. */
+declare function createClient(options: AuthyonClientOptions): AuthyonClient;
+
+/**
+ * Error thrown for any non-2xx Authyon API response.
+ *
+ * The API uses RFC 7807 problem+json: `{ title, status, detail, code }`.
+ * Match on the machine-readable `code` (e.g. `user.email_taken`), never on `title`.
+ */
+declare class AuthyonError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly title: string;
+    readonly detail?: string;
+    constructor(status: number, body: Partial<{
+        title: string;
+        detail: string;
+        code: string;
+    }>);
+    is(code: string): boolean;
+}
+/** Well-known error codes documented by Authyon. */
+declare const ErrorCodes: {
+    readonly EmailTaken: "user.email_taken";
+    readonly PasswordWeak: "user.password_weak";
+    readonly PasswordPwned: "user.password_pwned";
+};
+
+/** Keeps the session in memory only (lost on page reload). */
+declare function memoryStorage(): TokenStorage;
+/** Persists the session in `localStorage` under a namespaced key. */
+declare function localStorageAdapter(key?: string): TokenStorage;
+declare function defaultStorage(): TokenStorage;
+
+export { type Activity, type AuthEvent, type AuthStateListener, type AuthenticatorSetup, AuthyonClient, type AuthyonClientOptions, AuthyonError, type CreateOrganizationParams, ErrorCodes, type IntrospectResult, type InviteMemberParams, type LoginParams, type LoginResult, type Organization, type OrganizationMember, type PageParams, type RegisterParams, type Role, type Session, type SessionInfo, type SsoProvider, type TokenStorage, type TwoFactorChallenge, type TwoFactorMethod, type TwoFactorStatus, type TwoFactorVerifyParams, type User, type ValidateResult, type WebAuthnAssertion, type WebAuthnCeremonyStart, type WebAuthnCredential, createClient, defaultStorage, localStorageAdapter, memoryStorage };