@syndew/oluso-sdk 0.0.0-stage → 1.30.1

package/dist/auth/index.d.mts

@@ -0,0 +1,535 @@
+/**
+ * Field definition from a journey policy
+ */
+interface JourneyField {
+    name: string;
+    type: 'text' | 'email' | 'password' | 'number' | 'date' | 'tel' | 'url' | 'textarea' | 'select' | 'radio' | 'checkbox';
+    label: string;
+    placeholder?: string;
+    description?: string;
+    required: boolean;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    validation?: {
+        minLength?: number;
+        maxLength?: number;
+        pattern?: string;
+        min?: number;
+        max?: number;
+    };
+}
+/**
+ * A journey running step by step through the headless API (start, step, session).
+ * Every headless call returns the session as it stands after the call.
+ */
+interface JourneySession {
+    sessionId: string;
+    /** The journey's slug */
+    slug: string;
+    status: 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'expired';
+    success: boolean;
+    completed: boolean;
+    /** The step waiting for input, while in progress */
+    currentStep?: string;
+    /** Same as currentStep: set while there is a step to complete */
+    nextStep?: string;
+    completedSteps: string[];
+    expiresAt?: string;
+    /** What to render for the current step */
+    step?: JourneyStepView;
+    /** The step continues elsewhere (e.g. an external identity provider) */
+    redirectUrl?: string;
+    /** Authentication journeys: the authorization code to redeem with the PKCE verifier */
+    code?: string;
+    /** Data-collection journeys: the success message once completed */
+    message?: string;
+    error?: string;
+    errorDescription?: string;
+}
+/** A step to render: its definition and the model the server renders it from */
+interface JourneyStepView {
+    id: string;
+    /** Step type, e.g. local_login, mfa, dynamic_form */
+    type: string;
+    displayName?: string;
+    /** The server view the step renders as */
+    view?: string;
+    /** Fields, options, messages and errors for the step */
+    model?: Record<string, unknown>;
+    /** The step as a form any client can draw (see JourneyStepForm) */
+    form?: JourneyStepForm;
+    /** The hosted view's markup, for a step that has no form description (custom pages, plugin views) */
+    html?: string;
+    actions: JourneyStepAction[];
+}
+/**
+ * A step as a form. Posting its fields with the clicked action's name and value is exactly what the hosted page
+ * posts, so any journey step can be drawn by any client.
+ */
+interface JourneyStepForm {
+    title?: string;
+    description?: string;
+    /** What went wrong with the last submission */
+    error?: string;
+    /** Something to tell the person that isn't an error */
+    notice?: string;
+    fields: JourneyFormField[];
+    /** The buttons, in order; each posts the fields with its own name and value */
+    actions: JourneyFormAction[];
+    links: JourneyFormLink[];
+    /** Browser work for the step: passkey, captcha, QR code, recovery codes or waiting */
+    widget?: JourneyFormWidget;
+}
+type JourneyFormFieldType = 'text' | 'email' | 'password' | 'number' | 'date' | 'tel' | 'url' | 'textarea' | 'select' | 'radio' | 'checkbox' | 'file' | 'hidden' | 'otp' | 'content';
+interface JourneyFormField {
+    name: string;
+    type: JourneyFormFieldType | string;
+    label?: string;
+    placeholder?: string;
+    description?: string;
+    /** Guidance under the input, e.g. upload limits */
+    hint?: string;
+    required: boolean;
+    readOnly: boolean;
+    value?: string;
+    error?: string;
+    options?: JourneyFormOption[];
+    pattern?: string;
+    patternError?: string;
+    minLength?: number;
+    maxLength?: number;
+    min?: string;
+    max?: string;
+    rows?: number;
+    autocomplete?: string;
+    autofocus: boolean;
+    accept?: string;
+    maxFiles?: number;
+    maxFileSizeMb?: number;
+    capture?: string;
+    /** Phone: countries to pick from; the country is posted as `${name}__country` */
+    countries?: JourneyFormCountry[];
+    country?: string;
+    showWhen?: JourneyFormCondition;
+    /** Shown only while every one of these is met too */
+    showWhenAll?: JourneyFormCondition[];
+    group?: string;
+}
+interface JourneyFormOption {
+    value: string;
+    label: string;
+    description?: string;
+    disabled: boolean;
+}
+interface JourneyFormCountry {
+    code: string;
+    name: string;
+    dialCode: string;
+    flag?: string;
+}
+interface JourneyFormCondition {
+    field: string;
+    operator: string;
+    value?: string;
+}
+interface JourneyFormAction {
+    /** The posted name; absent for a button that posts no name of its own */
+    name?: string;
+    value?: string;
+    label: string;
+    /** Text shown with the button, e.g. "Didn't get the code?" before a resend link */
+    description?: string;
+    /** A question to confirm before the button posts; the renderer asks inline */
+    confirm?: string;
+    /** More values the button posts */
+    values?: Record<string, string>;
+    /** False: the button posts only its own name, value and values, none of the step's fields */
+    postsFields: boolean;
+    kind: 'primary' | 'secondary' | 'link' | 'cancel' | string;
+    skipValidation: boolean;
+}
+interface JourneyFormLink {
+    label: string;
+    url: string;
+}
+interface JourneyFormWidget {
+    type: 'webauthn_get' | 'webauthn_create' | 'captcha' | 'qr' | 'codes' | 'poll' | string;
+    data?: Record<string, unknown>;
+    /** Where the widget's result is posted */
+    resultField?: string;
+    /** The action posted with the result */
+    submit?: JourneyFormAction;
+}
+interface JourneyStepAction {
+    id: string;
+    label: string;
+    isPrimary: boolean;
+    isCancel: boolean;
+}
+
+/** Text the renderer shows itself; everything about a step comes from the server in the person's language. */
+interface JourneyLabels {
+    loading: string;
+    completed: string;
+    failed: string;
+    expired: string;
+    restart: string;
+    takePhoto: string;
+    copy: string;
+    copied: string;
+    passkey: string;
+    retry: string;
+    waiting: string;
+    unavailable: string;
+}
+interface JourneyMount {
+    /** The session as it stands. */
+    readonly session: JourneySession | undefined;
+    /** Start again from the first step (only for journeys started by slug or `start`). */
+    restart(): Promise<void>;
+    destroy(): void;
+}
+
+interface OidcEndpoints {
+    /** Authorization endpoint */
+    authorization?: string;
+    /** Token endpoint */
+    token?: string;
+    /** UserInfo endpoint */
+    userinfo?: string;
+    /** End session / logout endpoint */
+    endSession?: string;
+    /** JWKS URI */
+    jwks?: string;
+}
+interface OlusoAuthConfig {
+    /** Base URL of the Oluso server */
+    serverUrl: string;
+    /** Tenant identifier */
+    tenant: string;
+    /** OAuth2 client ID (public client) */
+    clientId: string;
+    /** Redirect URI for OIDC code flow (optional if using inline/modal auth) */
+    redirectUri?: string;
+    /** Scopes to request (default: "openid profile email") */
+    scopes?: string;
+    /**
+     * Manual OIDC endpoint overrides. If not provided, endpoints are
+     * discovered from the server's .well-known/openid-configuration document.
+     */
+    endpoints?: OidcEndpoints;
+    /** Slug of the sign-in journey (default: "signin") */
+    signInJourney?: string;
+    /** Slug of the sign-up journey (default: "signup") */
+    signUpJourney?: string;
+    /** Slug of the password-reset journey (default: "password-reset") */
+    passwordResetJourney?: string;
+    /** Token storage strategy */
+    storage?: 'memory' | 'localStorage' | 'sessionStorage';
+    /** Public API key for journey endpoints */
+    apiKey?: string;
+    /** Callback when auth state changes */
+    onAuthStateChange?: (user: OlusoUser | null) => void;
+}
+interface OlusoUser {
+    /** Subject (user ID) */
+    sub: string;
+    /** Display name */
+    name?: string;
+    /** Email address */
+    email?: string;
+    /** Whether email is verified */
+    emailVerified?: boolean;
+    /** User roles */
+    roles: string[];
+    /** User permissions */
+    permissions: string[];
+    /** Tenant ID */
+    tenantId?: string;
+    /** Raw ID token claims */
+    claims: Record<string, unknown>;
+}
+interface TokenSet {
+    accessToken: string;
+    idToken?: string;
+    refreshToken?: string;
+    expiresAt: number;
+    tokenType: string;
+    scope?: string;
+}
+interface AuthResult {
+    success: boolean;
+    user?: OlusoUser;
+    tokens?: TokenSet;
+    error?: string;
+    code?: string;
+    /** The journey needs another step (e.g. "mfa"): continue it with continueStep(sessionId, ...) */
+    requiresStep?: string;
+    sessionId?: string;
+    /** What to render for that step */
+    step?: JourneyStepView;
+    /** The step continues at an external identity provider */
+    redirectUrl?: string;
+}
+interface JourneyStepData {
+    /** Current step identifier */
+    step: string;
+    /** Fields to display for this step */
+    fields: JourneyField[];
+    /** Step title */
+    title?: string;
+    /** Step description */
+    description?: string;
+}
+/** Options for signInWithPasskey */
+interface PasskeyOptions {
+    /** Username for username-based flow. Omit for discoverable credential (usernameless) flow. */
+    username?: string;
+    /** Whether to use conditional mediation (passkey autofill in input fields) */
+    conditional?: boolean;
+    /** Abort signal to cancel the passkey prompt */
+    signal?: AbortSignal;
+}
+/** Options for signInWithFedCM */
+interface FedCmOptions {
+    /** Whether to use auto-reauthentication (silent sign-in if user previously approved) */
+    autoReauth?: boolean;
+    /** Nonce for token binding */
+    nonce?: string;
+    /** Login hint (email or username) to pre-select an account */
+    loginHint?: string;
+}
+/** WebAuthn assertion options returned by the server */
+interface WebAuthnAssertionOptions {
+    assertionId: string;
+    challenge: string;
+    timeout: number;
+    rpId?: string;
+    allowCredentials?: Array<{
+        type: string;
+        id: string;
+        transports?: string[];
+    }>;
+    userVerification: string;
+}
+/** Options for OlusoAuth.mountSignIn. */
+interface MountSignInOptions {
+    /** Slug of the journey to run (default: the configured sign-in journey) */
+    journey?: string;
+    /** Called with the outcome once the journey completes and the code is redeemed */
+    onSignedIn?: (result: AuthResult) => void;
+    onError?: (error: Error) => void;
+    /** A step continues at an external identity provider; defaults to navigating there */
+    onRedirect?: (url: string) => void;
+    theme?: 'light' | 'dark' | 'auto';
+    unstyled?: boolean;
+    labels?: Partial<JourneyLabels>;
+}
+
+/**
+ * Oluso Auth Client
+ *
+ * Handles authentication via OIDC (redirect), the hosted journey in a modal, or the
+ * journey run step by step from your own UI (inline). Inline journeys complete with an
+ * authorization code bound to this client's PKCE verifier, redeemed for tokens here.
+ *
+ * @example
+ * ```typescript
+ * const auth = new OlusoAuth({
+ *   serverUrl: 'https://auth.yoursite.com',
+ *   tenant: 'acme',
+ *   clientId: 'my-spa-client',
+ * });
+ *
+ * // Inline auth (no redirect)
+ * const result = await auth.signIn({ username: 'user@example.com', password: '...' });
+ * if (result.success) {
+ *   console.log('Logged in as', result.user.name);
+ * }
+ *
+ * // Check roles
+ * if (auth.hasRole('admin')) { ... }
+ * ```
+ */
+declare class OlusoAuth {
+    private config;
+    private storage;
+    private user;
+    private resolvedEndpoints;
+    private discoveryPromise;
+    /** PKCE verifiers of inline journeys still in progress, by session */
+    private readonly journeyVerifiers;
+    constructor(config: OlusoAuthConfig);
+    /**
+     * Sign in.
+     * - With data: run the sign-in journey inline with these inputs (programmatic, first-party
+     *   only). If another step follows (e.g. MFA), the result has requiresStep, sessionId and
+     *   the step to render; continue with continueStep().
+     * - Without data: open the hosted journey in a secure iframe modal (safe for any site)
+     */
+    signIn(data?: Record<string, unknown>): Promise<AuthResult>;
+    /**
+     * Sign up.
+     * - With data: run the sign-up journey inline (programmatic, first-party only)
+     * - Without data: open the hosted journey in a secure iframe modal
+     */
+    signUp(data?: Record<string, unknown>): Promise<AuthResult>;
+    /**
+     * Sign in with a passkey (WebAuthn).
+     * No form or iframe needed — the browser shows a native biometric/key prompt.
+     * Works with discoverable credentials (usernameless) or username-based flow.
+     *
+     * @example
+     * ```typescript
+     * // Discoverable credential (passkey autofill or prompt)
+     * const result = await auth.signInWithPasskey();
+     *
+     * // Username-based (shows credentials for specific user)
+     * const result = await auth.signInWithPasskey({ username: 'user@example.com' });
+     *
+     * // Conditional mediation (passkey suggestions in input fields)
+     * const result = await auth.signInWithPasskey({ conditional: true });
+     * ```
+     */
+    signInWithPasskey(options?: PasskeyOptions): Promise<AuthResult>;
+    /**
+     * Sign in with FedCM (Federated Credential Management).
+     * Opens a browser-native account picker — no redirect or popup needed.
+     * Requires the user to be already authenticated on the Oluso server (has session cookie).
+     *
+     * Browser support: Chrome/Edge 132+ (the provider `params` that carry the PKCE challenge).
+     * The page origin must be registered for the client (CORS origin or redirect URI).
+     *
+     * @example
+     * ```typescript
+     * const result = await auth.signInWithFedCM();
+     * if (result.success) {
+     *   console.log('Signed in as', result.user.name);
+     * }
+     * ```
+     */
+    signInWithFedCM(options?: FedCmOptions): Promise<AuthResult>;
+    /**
+     * Render the sign-in journey into `container` and sign in without leaving the page, e.g. in a modal when the
+     * session has expired. Every step the journey has (password, MFA, passkey, consent) is shown; when it completes,
+     * the code is redeemed and `onSignedIn` gets the result.
+     */
+    mountSignIn(container: HTMLElement, options?: MountSignInOptions): JourneyMount;
+    /**
+     * Continue an inline journey with the input for its current step (e.g. an MFA code)
+     */
+    continueStep(sessionId: string, data: Record<string, unknown>): Promise<AuthResult>;
+    /**
+     * Get the fields/config of a data-collection journey (for rendering in UI)
+     */
+    getJourneyStep(journeySlug: string): Promise<JourneyStepData | null>;
+    /**
+     * Redirect to the Oluso login page (standard OIDC Authorization Code + PKCE)
+     */
+    loginWithRedirect(options?: {
+        prompt?: 'login' | 'consent' | 'none';
+        state?: string;
+    }): Promise<void>;
+    /**
+     * Handle the OIDC callback (exchange code for tokens)
+     */
+    handleCallback(callbackUrl?: string): Promise<AuthResult>;
+    /**
+     * Get the current user (null if not authenticated)
+     */
+    getUser(): OlusoUser | null;
+    /**
+     * Check if user is authenticated (has valid tokens)
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get the current access token (for API calls)
+     */
+    getAccessToken(): string | null;
+    /**
+     * Check if user has a specific role
+     */
+    hasRole(role: string): boolean;
+    /**
+     * Check if user has any of the specified roles
+     */
+    hasAnyRole(...roles: string[]): boolean;
+    /**
+     * Check if user has a specific permission
+     */
+    hasPermission(permission: string): boolean;
+    /**
+     * Refresh the access token using the refresh token
+     */
+    refreshToken(): Promise<boolean>;
+    /**
+     * Log out — clear tokens and optionally redirect to end session.
+     * If redirect is true, uses discovered or configured end_session_endpoint.
+     */
+    logout(options?: {
+        redirect?: boolean;
+        postLogoutRedirectUri?: string;
+    }): void;
+    /**
+     * Fetch the user's profile from the userinfo endpoint
+     */
+    fetchUserInfo(): Promise<OlusoUser | null>;
+    /**
+     * Opens a secure iframe modal for authentication.
+     * Credentials are entered inside the iframe (auth server origin).
+     * Returns tokens via postMessage + PKCE code exchange.
+     */
+    private openAuthModal;
+    /**
+     * Get OIDC endpoints — uses manual overrides, falls back to discovery.
+     */
+    private getEndpoints;
+    private discoverEndpoints;
+    private defaultEndpoints;
+    private executeJourney;
+    /**
+     * Completed: redeem the code with the journey's verifier. In progress: hand back the step
+     * to render (an error from the step's last input, e.g. a wrong password, rides along).
+     */
+    private handleJourneyResult;
+    private processTokenResponse;
+    private parseIdToken;
+    private claimsToUser;
+    private parseArrayClaim;
+    private buildHeaders;
+    private generatePkce;
+    private base64UrlEncode;
+    private base64UrlDecode;
+    /**
+     * Exchange an authorization code for tokens via the token endpoint.
+     * Used by passkey, FedCM, and modal auth flows.
+     */
+    private exchangeCodeForTokens;
+}
+
+/**
+ * Token storage abstraction
+ */
+interface TokenStorage {
+    getTokens(): TokenSet | null;
+    setTokens(tokens: TokenSet): void;
+    clear(): void;
+}
+declare class MemoryStorage implements TokenStorage {
+    private tokens;
+    getTokens(): TokenSet | null;
+    setTokens(tokens: TokenSet): void;
+    clear(): void;
+}
+declare class BrowserStorage implements TokenStorage {
+    private store;
+    constructor(type: 'localStorage' | 'sessionStorage');
+    getTokens(): TokenSet | null;
+    setTokens(tokens: TokenSet): void;
+    clear(): void;
+}
+declare function createStorage(type: 'memory' | 'localStorage' | 'sessionStorage'): TokenStorage;
+
+export { type AuthResult, BrowserStorage, type FedCmOptions, type JourneyStepData, MemoryStorage, type OidcEndpoints, OlusoAuth, type OlusoAuthConfig, type OlusoUser, type PasskeyOptions, type TokenSet, type TokenStorage, type WebAuthnAssertionOptions, createStorage };