@labyrinthe/otp-widget 0.0.0-stage → 1.2.0

package/dist/server.d.cts

@@ -0,0 +1,264 @@
+/**
+ * Protocole JSON entre le widget (navigateur) et le serveur de l'intégrateur
+ * (`@labyrinthe/otp-widget/server`). Le navigateur ne voit jamais la clé API,
+ * ni `otp_id`, ni le code envoyé : seulement ce qui suit.
+ *
+ *     POST {sendUrl}    { "phone": "+243812345678", "locale": "fr", "send_id": "…" }
+ *       200 → SendSuccessBody            erreur → ErrorBody
+ *     POST {verifyUrl}  { "code": "482913" }
+ *       200 → VerifySuccessBody | VerifyFailureBody     erreur → ErrorBody
+ */
+/** Why a code was refused (same values as the Labyrinthe API `reason`). */
+type OtpFailureReason = 'invalid_code' | 'expired' | 'already_used' | 'max_attempts_reached';
+/** Error codes sent by the server helper (stable, lower case). */
+type ServerErrorCode = 
+/** The phone number cannot be used (invalid, blacklisted or opted out). */
+'invalid_phone'
+/** A code was sent to this number too recently: wait `retry_after_seconds`. */
+ | 'resend_too_soon'
+/** Too many requests (per number, per account or per API key). */
+ | 'rate_limited'
+/** No code is pending for this browser (cookie missing, expired or tampered with): send a new one. */
+ | 'no_pending_verification'
+/** Refused by the integrator (`beforeSend`) or by the origin / content-type checks. */
+ | 'forbidden'
+/** Malformed request (missing field, wrong content type…). */
+ | 'invalid_request'
+/**
+ * OTP service unavailable (Labyrinthe unreachable, misconfiguration, no credits…), or temporarily shut down by the
+ * Labyrinthe platform (FEATURE_DISABLED / OTP_SERVICE_DISABLED, maintenance): then `admin_message`, `until` and
+ * `retry_after_seconds` may be present.
+ */
+ | 'service_unavailable'
+/** The integrator's Labyrinthe account is suspended (ACCOUNT_SUSPENDED): nothing the user can do. */
+ | 'account_suspended'
+/**
+ * The send failed unexpectedly on the Labyrinthe side and its outcome is unknown (IDEMPOTENCY_KEY_UNRESOLVED):
+ * a code may have been sent. Never retried automatically; the user may ask for a new code (sent with a new key).
+ */
+ | 'send_failed'
+/** Unexpected server error. */
+ | 'server_error';
+type CodeType = 'numeric' | 'alphanumeric';
+interface SendSuccessBody {
+    sent: true;
+    /** Masked number, for display ("+243 81•••••78"). */
+    phone_masked: string;
+    /** ISO 8601. */
+    expires_at: string;
+    max_attempts: number;
+    /** Seconds before "Resend" is enabled (account's anti-resend delay, returned by the API). */
+    resend_after_seconds: number;
+    /** Code length / alphabet (account's OTP settings, returned by the API 1.2.0, or the server's override). */
+    code_length?: number;
+    code_type?: CodeType;
+    /** ONLY when the integrator enabled `exposeTestCode` in development, with a `lsk_test_` key. */
+    test_code?: string;
+}
+interface VerifySuccessBody {
+    verified: true;
+    /** Whatever the integrator's `onVerified` returned (e.g. `{ redirect: "/dashboard" }`). */
+    data?: unknown;
+}
+interface VerifyFailureBody {
+    verified: false;
+    reason: OtpFailureReason;
+    /** Attempts left for this code (`attempts_remaining` of the API; estimated with an older SDK); null when unknown. */
+    attempts_left: number | null;
+}
+interface ErrorBody {
+    error: {
+        code: ServerErrorCode;
+        message: string;
+        retry_after_seconds?: number;
+        /** Maintenance only: message written by the Labyrinthe platform administrator, meant for end users. */
+        admin_message?: string;
+        /** Maintenance only: scheduled end (ISO 8601). */
+        until?: string;
+    };
+}
+
+/**
+ * État OTP côté serveur et son transport dans un cookie.
+ *
+ * Le cookie est **chiffré et authentifié** (AES-256-GCM, clé dérivée du secret
+ * par HKDF-SHA-256) : le navigateur ne peut ni lire `otp_id` ni modifier l'état.
+ * Avec un `store`, le cookie ne contient qu'un identifiant de session aléatoire
+ * (lui aussi chiffré) et l'état reste dans le store.
+ *
+ * Uniquement Web Crypto : Node ≥ 18, edge, Deno, Bun. Aucun module Node importé
+ * statiquement.
+ */
+/** What the server keeps between `send` and `verify`. Never sent to the browser in clear. */
+interface OtpSessionState {
+    /** Labyrinthe `otp_id`. */
+    otpId: string;
+    /** Normalised phone number the code was sent to. */
+    phone: string;
+    /** Expiry of the code, in milliseconds since the epoch. */
+    expiresAt: number;
+    /** Attempts left, tracked from `max_attempts` and the `invalid_code` answers; null when unknown. */
+    attemptsLeft: number | null;
+}
+/**
+ * Optional server-side store (Redis, database, your framework's session…).
+ * Without it, the state travels in the encrypted cookie.
+ */
+interface OtpSessionStore {
+    get(id: string): OtpSessionState | null | undefined | Promise<OtpSessionState | null | undefined>;
+    set(id: string, state: OtpSessionState, ttlSeconds: number): void | Promise<void>;
+    delete(id: string): void | Promise<void>;
+}
+/** In-memory store, for development and tests (lost on restart, not shared between instances). */
+declare function memoryStore(): OtpSessionStore & {
+    readonly size: number;
+};
+interface CookieOptions {
+    /** Default "labyrinthe_otp". */
+    name?: string;
+    /** Default "/". Restrict it (e.g. "/api/otp") when both endpoints share a prefix. */
+    path?: string;
+    domain?: string;
+    /** Default "Strict". Use "None" (with `secure`) only for endpoints on another site. */
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    /** Default: true on HTTPS requests and when NODE_ENV is "production", false on plain-HTTP development. */
+    secure?: boolean;
+}
+
+/**
+ * The part of the `@labyrinthe/connect` client used here: pass a `Labyrinthe`
+ * instance. (Structural type: no runtime import of the SDK.)
+ */
+interface OtpClient {
+    otp: {
+        send(params: {
+            phone: string;
+            template?: string;
+            locale?: 'fr' | 'en';
+            webOtpDomain?: string;
+            stripAccents?: boolean;
+            idempotencyKey?: string;
+        }): Promise<{
+            otpId: string;
+            expiresAt: Date;
+            maxAttempts: number;
+            /** `@labyrinthe/connect` ≥ 1.1.0 (API 1.2.0); absent or null with an older SDK. */
+            codeLength?: number | null;
+            codeType?: string | null;
+            resendAfterSeconds?: number | null;
+            readonly testCode: string | null;
+        }>;
+        verify(params: {
+            otpId: string;
+            code: string;
+        }): Promise<{
+            verified: boolean;
+            reason: string | null;
+            /** `@labyrinthe/connect` ≥ 1.1.0; absent or null with an older SDK (then estimated). */
+            attemptsRemaining?: number | null;
+        }>;
+    };
+}
+interface BeforeSendContext {
+    /** Normalised phone number (international, no "+"). */
+    phone: string;
+    /** Your framework's request: the Fetch `Request` (Next.js, edge…) or the Express `req` (e.g. `req.session`). */
+    request: Request | ExpressLikeRequest;
+}
+interface VerifiedContext extends BeforeSendContext {
+    /** Headers added to the JSON response. */
+    responseHeaders: Headers;
+    /** Adds a `Set-Cookie` header to the response (e.g. your own session cookie). */
+    setCookie: (cookie: string) => void;
+}
+interface OtpHandlersOptions {
+    /** A `Labyrinthe` client from `@labyrinthe/connect` (or a function returning it, called on first use). */
+    client: OtpClient | (() => OtpClient);
+    /**
+     * Secret used to encrypt the session cookie, at least 32 characters.
+     * Defaults to `process.env.LABYRINTHE_OTP_SECRET`. Not your API key.
+     */
+    secret?: string;
+    /** Keep the state in your own store; the cookie then only holds a random session id. */
+    store?: OtpSessionStore;
+    cookie?: CookieOptions;
+    /** Added to local numbers. Default "243" (DR Congo). */
+    defaultCountryCode?: string;
+    /** SMS template (must contain "{code}"). Default: the account's OTP settings. */
+    template?: string;
+    /** SMS language. Default: the widget's locale, then the account's OTP settings. */
+    locale?: 'fr' | 'en';
+    /**
+     * Web OTP API: host name of YOUR site, as seen in the browser address bar
+     * (e.g. "app.example.com", no scheme, port or path). The API ends the SMS with
+     * the line `@app.example.com #123456`, and Chrome on Android then offers to
+     * fill the code in `<labyrinthe-otp>` (top-level page on that exact host, HTTPS).
+     */
+    webOtpDomain?: string;
+    /** Replace accents in the SMS with ASCII (GSM-7, often half the cost). Default false. */
+    stripAccents?: boolean;
+    /**
+     * Override of the anti-resend delay sent to the widget. Default: the
+     * `resend_after_seconds` returned by the API (account's OTP settings), then 60.
+     * The API still enforces the real delay.
+     */
+    resendAfterSeconds?: number;
+    /**
+     * Override of the code length / alphabet sent to the widget. Default: the
+     * `code_length` / `code_type` returned by the API (account's OTP settings).
+     * Only needed with an API older than 1.2.0.
+     */
+    codeLength?: number;
+    codeType?: CodeType;
+    /**
+     * DEVELOPMENT ONLY: return the `test_code` of a `lsk_test_` key to the
+     * browser. Refused when NODE_ENV is "production". Never available with a live key.
+     */
+    exposeTestCode?: boolean;
+    /** Origins allowed to call the endpoints. Default: the request's own host only. */
+    allowedOrigins?: string[];
+    /**
+     * Your anti-abuse checks before a billed SMS is sent (rate limit per IP or
+     * account, captcha, allow-list…). Return false to refuse (403 `forbidden`).
+     */
+    beforeSend?: (context: BeforeSendContext) => boolean | undefined | Promise<boolean | undefined>;
+    /**
+     * Called once the code is verified: this is where you trust the phone number
+     * (log the user in, mark the number as verified…). Its return value is sent
+     * to the browser as `data` (keep it JSON and non-secret). The browser event
+     * alone must never be trusted.
+     */
+    onVerified: (context: VerifiedContext) => unknown;
+    /** Called with unexpected and upstream errors, for your logs (no key, no code, no otp_id inside). */
+    onError?: (error: unknown, context: {
+        action: 'send' | 'verify';
+    }) => void;
+}
+type FetchHandler = (request: Request) => Promise<Response>;
+interface ExpressLikeRequest extends AsyncIterable<unknown> {
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    originalUrl?: string;
+    url?: string;
+    protocol?: string;
+}
+interface ExpressLikeResponse {
+    statusCode: number;
+    setHeader(name: string, value: string | string[]): unknown;
+    end(body?: string): unknown;
+}
+type ExpressHandler = (req: ExpressLikeRequest, res: ExpressLikeResponse, next: (error?: unknown) => void) => Promise<void>;
+interface OtpHandlers {
+    /** Fetch API handler (Next.js App Router, Hono, Bun, Deno, edge). */
+    send: FetchHandler;
+    verify: FetchHandler;
+    /** Express / Connect / `node:http` handlers (with or without `express.json()`). */
+    express: {
+        send: ExpressHandler;
+        verify: ExpressHandler;
+    };
+}
+declare function createOtpHandlers(options: OtpHandlersOptions): OtpHandlers;
+
+export { type BeforeSendContext, type CookieOptions, type ErrorBody, type ExpressHandler, type ExpressLikeRequest, type ExpressLikeResponse, type FetchHandler, type OtpClient, type OtpHandlers, type OtpHandlersOptions, type OtpSessionState, type OtpSessionStore, type SendSuccessBody, type ServerErrorCode, type VerifiedContext, type VerifyFailureBody, type VerifySuccessBody, createOtpHandlers, memoryStore };

package/dist/server.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Protocole JSON entre le widget (navigateur) et le serveur de l'intégrateur
+ * (`@labyrinthe/otp-widget/server`). Le navigateur ne voit jamais la clé API,
+ * ni `otp_id`, ni le code envoyé : seulement ce qui suit.
+ *
+ *     POST {sendUrl}    { "phone": "+243812345678", "locale": "fr", "send_id": "…" }
+ *       200 → SendSuccessBody            erreur → ErrorBody
+ *     POST {verifyUrl}  { "code": "482913" }
+ *       200 → VerifySuccessBody | VerifyFailureBody     erreur → ErrorBody
+ */
+/** Why a code was refused (same values as the Labyrinthe API `reason`). */
+type OtpFailureReason = 'invalid_code' | 'expired' | 'already_used' | 'max_attempts_reached';
+/** Error codes sent by the server helper (stable, lower case). */
+type ServerErrorCode = 
+/** The phone number cannot be used (invalid, blacklisted or opted out). */
+'invalid_phone'
+/** A code was sent to this number too recently: wait `retry_after_seconds`. */
+ | 'resend_too_soon'
+/** Too many requests (per number, per account or per API key). */
+ | 'rate_limited'
+/** No code is pending for this browser (cookie missing, expired or tampered with): send a new one. */
+ | 'no_pending_verification'
+/** Refused by the integrator (`beforeSend`) or by the origin / content-type checks. */
+ | 'forbidden'
+/** Malformed request (missing field, wrong content type…). */
+ | 'invalid_request'
+/**
+ * OTP service unavailable (Labyrinthe unreachable, misconfiguration, no credits…), or temporarily shut down by the
+ * Labyrinthe platform (FEATURE_DISABLED / OTP_SERVICE_DISABLED, maintenance): then `admin_message`, `until` and
+ * `retry_after_seconds` may be present.
+ */
+ | 'service_unavailable'
+/** The integrator's Labyrinthe account is suspended (ACCOUNT_SUSPENDED): nothing the user can do. */
+ | 'account_suspended'
+/**
+ * The send failed unexpectedly on the Labyrinthe side and its outcome is unknown (IDEMPOTENCY_KEY_UNRESOLVED):
+ * a code may have been sent. Never retried automatically; the user may ask for a new code (sent with a new key).
+ */
+ | 'send_failed'
+/** Unexpected server error. */
+ | 'server_error';
+type CodeType = 'numeric' | 'alphanumeric';
+interface SendSuccessBody {
+    sent: true;
+    /** Masked number, for display ("+243 81•••••78"). */
+    phone_masked: string;
+    /** ISO 8601. */
+    expires_at: string;
+    max_attempts: number;
+    /** Seconds before "Resend" is enabled (account's anti-resend delay, returned by the API). */
+    resend_after_seconds: number;
+    /** Code length / alphabet (account's OTP settings, returned by the API 1.2.0, or the server's override). */
+    code_length?: number;
+    code_type?: CodeType;
+    /** ONLY when the integrator enabled `exposeTestCode` in development, with a `lsk_test_` key. */
+    test_code?: string;
+}
+interface VerifySuccessBody {
+    verified: true;
+    /** Whatever the integrator's `onVerified` returned (e.g. `{ redirect: "/dashboard" }`). */
+    data?: unknown;
+}
+interface VerifyFailureBody {
+    verified: false;
+    reason: OtpFailureReason;
+    /** Attempts left for this code (`attempts_remaining` of the API; estimated with an older SDK); null when unknown. */
+    attempts_left: number | null;
+}
+interface ErrorBody {
+    error: {
+        code: ServerErrorCode;
+        message: string;
+        retry_after_seconds?: number;
+        /** Maintenance only: message written by the Labyrinthe platform administrator, meant for end users. */
+        admin_message?: string;
+        /** Maintenance only: scheduled end (ISO 8601). */
+        until?: string;
+    };
+}
+
+/**
+ * État OTP côté serveur et son transport dans un cookie.
+ *
+ * Le cookie est **chiffré et authentifié** (AES-256-GCM, clé dérivée du secret
+ * par HKDF-SHA-256) : le navigateur ne peut ni lire `otp_id` ni modifier l'état.
+ * Avec un `store`, le cookie ne contient qu'un identifiant de session aléatoire
+ * (lui aussi chiffré) et l'état reste dans le store.
+ *
+ * Uniquement Web Crypto : Node ≥ 18, edge, Deno, Bun. Aucun module Node importé
+ * statiquement.
+ */
+/** What the server keeps between `send` and `verify`. Never sent to the browser in clear. */
+interface OtpSessionState {
+    /** Labyrinthe `otp_id`. */
+    otpId: string;
+    /** Normalised phone number the code was sent to. */
+    phone: string;
+    /** Expiry of the code, in milliseconds since the epoch. */
+    expiresAt: number;
+    /** Attempts left, tracked from `max_attempts` and the `invalid_code` answers; null when unknown. */
+    attemptsLeft: number | null;
+}
+/**
+ * Optional server-side store (Redis, database, your framework's session…).
+ * Without it, the state travels in the encrypted cookie.
+ */
+interface OtpSessionStore {
+    get(id: string): OtpSessionState | null | undefined | Promise<OtpSessionState | null | undefined>;
+    set(id: string, state: OtpSessionState, ttlSeconds: number): void | Promise<void>;
+    delete(id: string): void | Promise<void>;
+}
+/** In-memory store, for development and tests (lost on restart, not shared between instances). */
+declare function memoryStore(): OtpSessionStore & {
+    readonly size: number;
+};
+interface CookieOptions {
+    /** Default "labyrinthe_otp". */
+    name?: string;
+    /** Default "/". Restrict it (e.g. "/api/otp") when both endpoints share a prefix. */
+    path?: string;
+    domain?: string;
+    /** Default "Strict". Use "None" (with `secure`) only for endpoints on another site. */
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    /** Default: true on HTTPS requests and when NODE_ENV is "production", false on plain-HTTP development. */
+    secure?: boolean;
+}
+
+/**
+ * The part of the `@labyrinthe/connect` client used here: pass a `Labyrinthe`
+ * instance. (Structural type: no runtime import of the SDK.)
+ */
+interface OtpClient {
+    otp: {
+        send(params: {
+            phone: string;
+            template?: string;
+            locale?: 'fr' | 'en';
+            webOtpDomain?: string;
+            stripAccents?: boolean;
+            idempotencyKey?: string;
+        }): Promise<{
+            otpId: string;
+            expiresAt: Date;
+            maxAttempts: number;
+            /** `@labyrinthe/connect` ≥ 1.1.0 (API 1.2.0); absent or null with an older SDK. */
+            codeLength?: number | null;
+            codeType?: string | null;
+            resendAfterSeconds?: number | null;
+            readonly testCode: string | null;
+        }>;
+        verify(params: {
+            otpId: string;
+            code: string;
+        }): Promise<{
+            verified: boolean;
+            reason: string | null;
+            /** `@labyrinthe/connect` ≥ 1.1.0; absent or null with an older SDK (then estimated). */
+            attemptsRemaining?: number | null;
+        }>;
+    };
+}
+interface BeforeSendContext {
+    /** Normalised phone number (international, no "+"). */
+    phone: string;
+    /** Your framework's request: the Fetch `Request` (Next.js, edge…) or the Express `req` (e.g. `req.session`). */
+    request: Request | ExpressLikeRequest;
+}
+interface VerifiedContext extends BeforeSendContext {
+    /** Headers added to the JSON response. */
+    responseHeaders: Headers;
+    /** Adds a `Set-Cookie` header to the response (e.g. your own session cookie). */
+    setCookie: (cookie: string) => void;
+}
+interface OtpHandlersOptions {
+    /** A `Labyrinthe` client from `@labyrinthe/connect` (or a function returning it, called on first use). */
+    client: OtpClient | (() => OtpClient);
+    /**
+     * Secret used to encrypt the session cookie, at least 32 characters.
+     * Defaults to `process.env.LABYRINTHE_OTP_SECRET`. Not your API key.
+     */
+    secret?: string;
+    /** Keep the state in your own store; the cookie then only holds a random session id. */
+    store?: OtpSessionStore;
+    cookie?: CookieOptions;
+    /** Added to local numbers. Default "243" (DR Congo). */
+    defaultCountryCode?: string;
+    /** SMS template (must contain "{code}"). Default: the account's OTP settings. */
+    template?: string;
+    /** SMS language. Default: the widget's locale, then the account's OTP settings. */
+    locale?: 'fr' | 'en';
+    /**
+     * Web OTP API: host name of YOUR site, as seen in the browser address bar
+     * (e.g. "app.example.com", no scheme, port or path). The API ends the SMS with
+     * the line `@app.example.com #123456`, and Chrome on Android then offers to
+     * fill the code in `<labyrinthe-otp>` (top-level page on that exact host, HTTPS).
+     */
+    webOtpDomain?: string;
+    /** Replace accents in the SMS with ASCII (GSM-7, often half the cost). Default false. */
+    stripAccents?: boolean;
+    /**
+     * Override of the anti-resend delay sent to the widget. Default: the
+     * `resend_after_seconds` returned by the API (account's OTP settings), then 60.
+     * The API still enforces the real delay.
+     */
+    resendAfterSeconds?: number;
+    /**
+     * Override of the code length / alphabet sent to the widget. Default: the
+     * `code_length` / `code_type` returned by the API (account's OTP settings).
+     * Only needed with an API older than 1.2.0.
+     */
+    codeLength?: number;
+    codeType?: CodeType;
+    /**
+     * DEVELOPMENT ONLY: return the `test_code` of a `lsk_test_` key to the
+     * browser. Refused when NODE_ENV is "production". Never available with a live key.
+     */
+    exposeTestCode?: boolean;
+    /** Origins allowed to call the endpoints. Default: the request's own host only. */
+    allowedOrigins?: string[];
+    /**
+     * Your anti-abuse checks before a billed SMS is sent (rate limit per IP or
+     * account, captcha, allow-list…). Return false to refuse (403 `forbidden`).
+     */
+    beforeSend?: (context: BeforeSendContext) => boolean | undefined | Promise<boolean | undefined>;
+    /**
+     * Called once the code is verified: this is where you trust the phone number
+     * (log the user in, mark the number as verified…). Its return value is sent
+     * to the browser as `data` (keep it JSON and non-secret). The browser event
+     * alone must never be trusted.
+     */
+    onVerified: (context: VerifiedContext) => unknown;
+    /** Called with unexpected and upstream errors, for your logs (no key, no code, no otp_id inside). */
+    onError?: (error: unknown, context: {
+        action: 'send' | 'verify';
+    }) => void;
+}
+type FetchHandler = (request: Request) => Promise<Response>;
+interface ExpressLikeRequest extends AsyncIterable<unknown> {
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    originalUrl?: string;
+    url?: string;
+    protocol?: string;
+}
+interface ExpressLikeResponse {
+    statusCode: number;
+    setHeader(name: string, value: string | string[]): unknown;
+    end(body?: string): unknown;
+}
+type ExpressHandler = (req: ExpressLikeRequest, res: ExpressLikeResponse, next: (error?: unknown) => void) => Promise<void>;
+interface OtpHandlers {
+    /** Fetch API handler (Next.js App Router, Hono, Bun, Deno, edge). */
+    send: FetchHandler;
+    verify: FetchHandler;
+    /** Express / Connect / `node:http` handlers (with or without `express.json()`). */
+    express: {
+        send: ExpressHandler;
+        verify: ExpressHandler;
+    };
+}
+declare function createOtpHandlers(options: OtpHandlersOptions): OtpHandlers;
+
+export { type BeforeSendContext, type CookieOptions, type ErrorBody, type ExpressHandler, type ExpressLikeRequest, type ExpressLikeResponse, type FetchHandler, type OtpClient, type OtpHandlers, type OtpHandlersOptions, type OtpSessionState, type OtpSessionStore, type SendSuccessBody, type ServerErrorCode, type VerifiedContext, type VerifyFailureBody, type VerifySuccessBody, createOtpHandlers, memoryStore };