@ondewo/s2t-client-typescript 7.4.1 → 7.5.0

package/auth/offlineTokenProvider.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Minimal structural type of the fetch Response fields this helper reads. Keeps the module
+ * self-contained (no DOM lib dependency) while still typing the injectable `fetchImpl`.
+ */
+export interface TokenFetchResponse {
+    /** Whether the HTTP status is in the 2xx success range. */
+    ok: boolean;
+    /** The numeric HTTP status code of the response. */
+    status: number;
+    /**
+     * Read the response body as text.
+     *
+     * @returns A promise resolving to the raw response body string.
+     */
+    text(): Promise<string>;
+}
+/** Init object passed to the injectable fetch when POSTing to the token endpoint. */
+export interface TokenFetchInit {
+    /** HTTP method (always `"POST"` for the token endpoint). */
+    method: string;
+    /** Request headers (Content-Type + Accept) as a plain string map. */
+    headers: Record<string, string>;
+    /** The `application/x-www-form-urlencoded` request body. */
+    body: string;
+    /**
+     * Optional undici dispatcher (Node only). The default transport attaches an insecure
+     * `Agent({ connect: { rejectUnauthorized: false } })` here when `verifySsl` is `false`; the global
+     * WHATWG fetch honours it. Never set on an injected `fetchImpl` and ignored in a browser bundle.
+     */
+    dispatcher?: unknown;
+}
+/**
+ * Injectable fetch signature (a subset of the global `fetch`) used by the token endpoint call.
+ *
+ * @param url - The token endpoint URL to POST to.
+ * @param init - The request method, headers, and form-encoded body.
+ * @returns A promise resolving to the structural {@link TokenFetchResponse}.
+ */
+export type TokenFetch = (url: string, init: TokenFetchInit) => Promise<TokenFetchResponse>;
+/** Options for the D18 headless-SDK offline-token login. */
+export interface OfflineTokenLoginOptions {
+    /** Base Keycloak URL, e.g. "https://auth.example.com/auth" (trailing slash tolerated). */
+    keycloakUrl: string;
+    /** Realm name, e.g. "ondewo-ccai-platform". */
+    realm: string;
+    /** Public SDK client id, e.g. "ondewo-nlu-cai-sdk-public". NO client_secret (Q1). */
+    clientId: string;
+    /** 2FA-exempt technical-user email. */
+    username: string;
+    /** Technical-user password. */
+    password: string;
+    /** Optional cap (seconds) on how long the auto-refresh loop runs after login. */
+    tokenExpirationInS?: number;
+    /** Optional fetch override (tests inject a mock); defaults to the global fetch. */
+    fetchImpl?: TokenFetch;
+    /**
+     * Verify the Keycloak TLS certificate on the token-endpoint call. Default `true` (secure). Set
+     * `false` ONLY for a self-signed local Envoy (e.g. `https://localhost:12001/auth`). Node-only: it is
+     * ignored in a browser bundle (the browser owns TLS) and ignored when a custom `fetchImpl` is
+     * injected. When `false` under Node the default transport attaches an insecure undici dispatcher.
+     */
+    keycloakVerifySsl?: boolean;
+    /** Optional clock override returning epoch ms (tests); defaults to Date.now. */
+    nowInMs?: () => number;
+}
+/** Error raised on any token-endpoint or token-shape failure. */
+export declare class TokenError extends Error {
+    /**
+     * Construct a `TokenError` with a fixed `name` of `"TokenError"`.
+     *
+     * @param message - Human-readable description of the token failure.
+     */
+    constructor(message: string);
+}
+/**
+ * The undici `Agent` options that switch TLS certificate verification OFF for the token request.
+ * Exported so the security-relevant `rejectUnauthorized: false` literal is pinned by a test rather than
+ * living as a bare literal that could be flipped without any test noticing.
+ */
+export declare const INSECURE_AGENT_OPTIONS: {
+    connect: {
+        rejectUnauthorized: boolean;
+    };
+};
+/**
+ * Build the DEFAULT token transport (used only when no `fetchImpl` is injected). It delegates to the
+ * global WHATWG fetch, and -- when `verifySsl` is `false` under Node -- attaches an insecure undici
+ * dispatcher to the request init so the token POST skips certificate verification. With `verifySsl`
+ * `true` (the default) it is a plain pass-through to `globalThis.fetch`, i.e. unchanged behavior.
+ *
+ * @param verifySsl - Whether to verify the Keycloak TLS certificate; `false` opts into the insecure path.
+ * @returns A {@link TokenFetch} that resolves the global fetch at call time (honoring test overrides).
+ */
+export declare function createDefaultTokenFetch(verifySsl: boolean): TokenFetch;
+/**
+ * A live access-token holder backed by a bounded auto-refresh loop. Obtain one from {@link login};
+ * read {@link getAuthorizationHeader} for the gRPC `Authorization` metadata and call {@link stop} when done.
+ */
+export declare class OfflineTokenProvider {
+    /** Pre-built OIDC token endpoint URL the provider POSTs to for both login and refresh. */
+    private readonly tokenEndpoint;
+    /** Public SDK client id sent as `client_id` (no `client_secret` -- Q1). */
+    private readonly clientId;
+    /** Optional cap (seconds) after which the auto-refresh loop stops; `undefined` means unbounded. */
+    private readonly tokenExpirationInS;
+    /** The injectable fetch used for every token request (defaults to the global `fetch`). */
+    private readonly fetchImpl;
+    /** Clock returning epoch milliseconds, used for deadline arithmetic (defaults to `Date.now`). */
+    private readonly nowInMs;
+    /** The current access token, or `null` before bootstrap / after the bounded loop lapses. */
+    private accessToken;
+    /** The newest offline refresh token, or `null` before bootstrap. */
+    private refreshToken;
+    /** Handle of the single armed refresh timer, or `null` when none is pending. */
+    private timer;
+    /** Whether {@link stop} has been called; suppresses any further refresh scheduling. */
+    private stopped;
+    /** Absolute epoch-ms deadline at which the loop stops, or `null` when unbounded. */
+    private deadlineInMs;
+    /** Optional callback invoked with the error of a failed background refresh. */
+    private onRefreshErrorHandler;
+    /**
+     * Initialize the provider from login options without performing any network call. Use {@link login}
+     * (which constructs and then {@link bootstrap}s) for the normal flow.
+     *
+     * @param options - The D18 headless-SDK offline-token login options.
+     */
+    constructor(options: OfflineTokenLoginOptions);
+    /**
+     * Perform the one-time ROPC login and arm the first refresh. Awaited by {@link login}.
+     *
+     * @param username - The 2FA-exempt technical-user email.
+     * @param password - The technical-user password.
+     * @returns A promise that resolves once the access token is stored and the first refresh is scheduled.
+     * @throws {@link TokenError} If the token endpoint fails, or when the response carries no usable
+     *   `refresh_token` -- absent, not a string, or empty (i.e. the SDK client lacks directAccessGrants
+     *   + the `offline_access` scope).
+     */
+    bootstrap(username: string, password: string): Promise<void>;
+    /**
+     * Exchange the offline refresh token for a fresh access token and re-arm the next refresh. No-ops
+     * once {@link stop} has been called or the bounded deadline has elapsed.
+     *
+     * @returns A promise that resolves once the refreshed token is stored and the next refresh is armed.
+     * @throws {@link TokenError} If the refresh token request fails or returns an invalid body; the
+     *   rejection is routed to the {@link onRefreshError} handler by the firing timer.
+     */
+    private refresh;
+    /**
+     * Arm a single timer for the next refresh, clamped to the bounded deadline. Stops silently once
+     * `tokenExpirationInS` has elapsed (no further renewal -> access lapses -> re-login required).
+     *
+     * @param expiresInRaw - The `expires_in` (seconds) from the latest token response, or `undefined`;
+     *   non-positive / missing values fall back to {@link MIN_REFRESH_DELAY_IN_S}.
+     */
+    private scheduleRefresh;
+    /**
+     * Register a callback invoked with the error of a failed background refresh (optional diagnostics).
+     * A later call replaces any previously registered handler.
+     *
+     * @param handler - Receives the rejection value of a failed background refresh.
+     */
+    onRefreshError(handler: (error: unknown) => void): void;
+    /**
+     * Read the current access token.
+     *
+     * @returns The current access token, or `null` before bootstrap / after the bounded loop has lapsed.
+     */
+    getAccessToken(): string | null;
+    /**
+     * Build the value for an `Authorization` gRPC metadata header.
+     *
+     * @returns The header value `Bearer <access_token>`.
+     * @throws {@link TokenError} If no access token is available (login not completed or already lapsed).
+     */
+    getAuthorizationHeader(): string;
+    /**
+     * Stop the auto-refresh loop and clear any pending timer. Idempotent; safe to call from any state.
+     * After this the access token is no longer renewed and will eventually lapse.
+     */
+    stop(): void;
+}
+/**
+ * One-time ROPC + offline_access login against the PUBLIC SDK client, returning a live token provider
+ * whose access token is auto-refreshed in the background until `tokenExpirationInS` elapses.
+ *
+ * @param options - The D18 headless-SDK offline-token login options; the five string fields
+ *   (`keycloakUrl`, `realm`, `clientId`, `username`, `password`) are required and must be non-empty.
+ * @returns A promise resolving to a bootstrapped {@link OfflineTokenProvider} with its first refresh armed.
+ * @throws {@link TokenError} If `options` is missing, a required field is absent/empty, or the
+ *   bootstrap login fails (see {@link OfflineTokenProvider.bootstrap}).
+ */
+export declare function login(options: OfflineTokenLoginOptions): Promise<OfflineTokenProvider>;

package/auth/offlineTokenProvider.js

@@ -0,0 +1,374 @@
+"use strict";
+// Copyright 2021-2026 ONDEWO GmbH
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfflineTokenProvider = exports.INSECURE_AGENT_OPTIONS = exports.TokenError = void 0;
+exports.createDefaultTokenFetch = createDefaultTokenFetch;
+exports.login = login;
+/**
+ * D18 headless-SDK auth helper (keycloak-migration-plan §7.8 + D18).
+ *
+ * One-time ROPC login (`grant_type=password`, `scope=offline_access`) against the PUBLIC SDK client
+ * `ondewo-nlu-cai-sdk-public` (no client_secret -- Q1), then a bounded background loop that refreshes
+ * the short-lived access token from the offline refresh token before it expires. The current access
+ * token is exposed for an `Authorization: Bearer <token>` gRPC metadata header. The refresh loop stops
+ * after `tokenExpirationInS` (if given) has elapsed since login.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Seconds of head-room subtracted from a token's `expires_in` so the refresh fires before the access
+ * token actually lapses (covers clock skew + the round-trip to Keycloak).
+ */
+const REFRESH_SKEW_IN_S = 30;
+/** Lower bound (seconds) for the scheduled refresh delay so a tiny/zero `expires_in` cannot spin a hot loop. */
+const MIN_REFRESH_DELAY_IN_S = 1;
+/** Error raised on any token-endpoint or token-shape failure. */
+class TokenError extends Error {
+    /**
+     * Construct a `TokenError` with a fixed `name` of `"TokenError"`.
+     *
+     * @param message - Human-readable description of the token failure.
+     */
+    constructor(message) {
+        super(message);
+        this.name = 'TokenError';
+    }
+}
+exports.TokenError = TokenError;
+/**
+ * Build the OIDC token endpoint URL for a realm, tolerating a trailing slash on `keycloakUrl` and an
+ * optional `/auth` relative path already baked into it.
+ *
+ * @param keycloakUrl - Base Keycloak URL (trailing slash tolerated).
+ * @param realm - Realm name; URL-encoded into the path.
+ * @returns The fully-qualified `.../realms/<realm>/protocol/openid-connect/token` endpoint URL.
+ */
+function buildTokenEndpoint(keycloakUrl, realm) {
+    const base = keycloakUrl.replace(/\/+$/, '');
+    return `${base}/realms/${encodeURIComponent(realm)}/protocol/openid-connect/token`;
+}
+/**
+ * POST an `application/x-www-form-urlencoded` body to the token endpoint and return the parsed JSON.
+ *
+ * @param tokenEndpoint - The OIDC token endpoint URL (see {@link buildTokenEndpoint}).
+ * @param params - Form fields to URL-encode into the request body (grant type, client id, credentials).
+ * @param fetchImpl - The injectable fetch used to perform the request.
+ * @returns A promise resolving to the parsed {@link KeycloakTokenResponse}.
+ * @throws {@link TokenError} On a non-2xx response, an unparseable body, or a missing `access_token`.
+ */
+async function postTokenRequest(tokenEndpoint, params, fetchImpl) {
+    const body = new URLSearchParams(params).toString();
+    const response = await fetchImpl(tokenEndpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Accept: 'application/json'
+        },
+        body
+    });
+    const text = await response.text();
+    if (!response.ok) {
+        throw new TokenError(`Keycloak token endpoint returned HTTP ${response.status}: ${text}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new TokenError(`Keycloak token endpoint returned a non-JSON body: ${text}`);
+    }
+    if (typeof parsed.access_token !== 'string' || parsed.access_token.length === 0) {
+        throw new TokenError('Keycloak token response did not contain an access_token');
+    }
+    return parsed;
+}
+/**
+ * The undici `Agent` options that switch TLS certificate verification OFF for the token request.
+ * Exported so the security-relevant `rejectUnauthorized: false` literal is pinned by a test rather than
+ * living as a bare literal that could be flipped without any test noticing.
+ */
+exports.INSECURE_AGENT_OPTIONS = {
+    connect: { rejectUnauthorized: false }
+};
+/** Cached insecure undici dispatcher (built once, reused) so `verifySsl:false` costs one Agent. */
+let insecureNodeDispatcher;
+/**
+ * Lazily build a cached undici `Agent` that skips TLS certificate verification -- the Node analog of
+ * Python's `requests.post(..., verify=False)`. Node-guarded and loaded via a dynamic `import("undici")`
+ * so a browser bundle never pulls in `undici` and the flag stays a hard no-op outside Node.
+ *
+ * @returns The insecure dispatcher under Node, or `undefined` in a browser (TLS is owned by the browser).
+ */
+async function getInsecureNodeDispatcher() {
+    const nodeProcess = globalThis.process;
+    /* c8 ignore next 3 -- browser guard: not exercised under the Node test runner */
+    if (nodeProcess === undefined || nodeProcess.versions === undefined || nodeProcess.versions.node === undefined) {
+        return undefined;
+    }
+    if (insecureNodeDispatcher === undefined) {
+        const undiciModuleName = 'undici';
+        const undici = (await Promise.resolve(`${undiciModuleName}`).then(s => __importStar(require(s))));
+        insecureNodeDispatcher = new undici.Agent(exports.INSECURE_AGENT_OPTIONS);
+    }
+    return insecureNodeDispatcher;
+}
+/**
+ * Build the DEFAULT token transport (used only when no `fetchImpl` is injected). It delegates to the
+ * global WHATWG fetch, and -- when `verifySsl` is `false` under Node -- attaches an insecure undici
+ * dispatcher to the request init so the token POST skips certificate verification. With `verifySsl`
+ * `true` (the default) it is a plain pass-through to `globalThis.fetch`, i.e. unchanged behavior.
+ *
+ * @param verifySsl - Whether to verify the Keycloak TLS certificate; `false` opts into the insecure path.
+ * @returns A {@link TokenFetch} that resolves the global fetch at call time (honoring test overrides).
+ */
+function createDefaultTokenFetch(verifySsl) {
+    return async (url, init) => {
+        const dispatcher = verifySsl ? undefined : await getInsecureNodeDispatcher();
+        const effectiveInit = dispatcher !== undefined ? { ...init, dispatcher } : init;
+        const globalFetch = globalThis.fetch;
+        return globalFetch(url, effectiveInit);
+    };
+}
+/**
+ * A live access-token holder backed by a bounded auto-refresh loop. Obtain one from {@link login};
+ * read {@link getAuthorizationHeader} for the gRPC `Authorization` metadata and call {@link stop} when done.
+ */
+class OfflineTokenProvider {
+    /**
+     * Initialize the provider from login options without performing any network call. Use {@link login}
+     * (which constructs and then {@link bootstrap}s) for the normal flow.
+     *
+     * @param options - The D18 headless-SDK offline-token login options.
+     */
+    constructor(options) {
+        this.tokenEndpoint = buildTokenEndpoint(options.keycloakUrl, options.realm);
+        this.clientId = options.clientId;
+        this.tokenExpirationInS = options.tokenExpirationInS;
+        // A custom fetchImpl always wins (the verifySsl flag is ignored for injected transports); only the
+        // DEFAULT transport honors verifySsl, and only under Node. Absent/undefined verifySsl => secure (true).
+        const verifySsl = options.keycloakVerifySsl !== false;
+        this.fetchImpl = options.fetchImpl !== undefined ? options.fetchImpl : createDefaultTokenFetch(verifySsl);
+        this.nowInMs = options.nowInMs !== undefined ? options.nowInMs : Date.now;
+        this.accessToken = null;
+        this.refreshToken = null;
+        this.timer = null;
+        this.stopped = false;
+        this.deadlineInMs = null;
+        this.onRefreshErrorHandler = null;
+    }
+    /**
+     * Perform the one-time ROPC login and arm the first refresh. Awaited by {@link login}.
+     *
+     * @param username - The 2FA-exempt technical-user email.
+     * @param password - The technical-user password.
+     * @returns A promise that resolves once the access token is stored and the first refresh is scheduled.
+     * @throws {@link TokenError} If the token endpoint fails, or when the response carries no usable
+     *   `refresh_token` -- absent, not a string, or empty (i.e. the SDK client lacks directAccessGrants
+     *   + the `offline_access` scope).
+     */
+    async bootstrap(username, password) {
+        const tokenResponse = await postTokenRequest(this.tokenEndpoint, {
+            grant_type: 'password',
+            client_id: this.clientId,
+            username,
+            password,
+            scope: 'offline_access'
+        }, this.fetchImpl);
+        this.accessToken = tokenResponse.access_token;
+        // An empty string is rejected exactly like a missing token, mirroring the rotation guard in
+        // refresh(): a blank offline token would otherwise bootstrap a provider whose every renewal POSTs
+        // `refresh_token=` and fails, turning a clear login error into a silent expiry ~5 minutes later.
+        this.refreshToken =
+            typeof tokenResponse.refresh_token === 'string' && tokenResponse.refresh_token.length > 0
+                ? tokenResponse.refresh_token
+                : null;
+        if (this.refreshToken === null) {
+            throw new TokenError('Keycloak token response did not contain a refresh_token; the SDK client must have ' +
+                'directAccessGrants + the offline_access scope (ondewo-nlu-cai-sdk-public)');
+        }
+        if (this.tokenExpirationInS !== undefined) {
+            const expirationInMs = this.tokenExpirationInS * 1000;
+            this.deadlineInMs = this.nowInMs() + expirationInMs;
+        }
+        this.scheduleRefresh(tokenResponse.expires_in);
+    }
+    /**
+     * Exchange the offline refresh token for a fresh access token and re-arm the next refresh. No-ops
+     * once {@link stop} has been called or the bounded deadline has elapsed.
+     *
+     * @returns A promise that resolves once the refreshed token is stored and the next refresh is armed.
+     * @throws {@link TokenError} If the refresh token request fails or returns an invalid body; the
+     *   rejection is routed to the {@link onRefreshError} handler by the firing timer.
+     */
+    async refresh() {
+        /* c8 ignore next 3 -- unreachable: stop() always clears the only timer that calls refresh() */
+        if (this.stopped) {
+            return;
+        }
+        // Re-check the bounded deadline at fire time (not just at schedule time): once it has elapsed the
+        // loop stops with no further renewal -> the access token lapses -> re-login is required.
+        if (this.deadlineInMs !== null && this.nowInMs() >= this.deadlineInMs) {
+            this.stop();
+            return;
+        }
+        const tokenResponse = await postTokenRequest(this.tokenEndpoint, {
+            grant_type: 'refresh_token',
+            client_id: this.clientId,
+            refresh_token: this.refreshToken
+        }, this.fetchImpl);
+        this.accessToken = tokenResponse.access_token;
+        // Keycloak may rotate the offline refresh token; keep the newest one when present.
+        if (typeof tokenResponse.refresh_token === 'string' && tokenResponse.refresh_token.length > 0) {
+            this.refreshToken = tokenResponse.refresh_token;
+        }
+        this.scheduleRefresh(tokenResponse.expires_in);
+    }
+    /**
+     * Arm a single timer for the next refresh, clamped to the bounded deadline. Stops silently once
+     * `tokenExpirationInS` has elapsed (no further renewal -> access lapses -> re-login required).
+     *
+     * @param expiresInRaw - The `expires_in` (seconds) from the latest token response, or `undefined`;
+     *   non-positive / missing values fall back to {@link MIN_REFRESH_DELAY_IN_S}.
+     */
+    scheduleRefresh(expiresInRaw) {
+        if (this.stopped) {
+            return;
+        }
+        const expiresInS = typeof expiresInRaw === 'number' && expiresInRaw > 0 ? expiresInRaw : MIN_REFRESH_DELAY_IN_S;
+        let delayInS = Math.max(expiresInS - REFRESH_SKEW_IN_S, MIN_REFRESH_DELAY_IN_S);
+        if (this.deadlineInMs !== null) {
+            const remainingInMs = this.deadlineInMs - this.nowInMs();
+            if (remainingInMs <= 0) {
+                this.stop();
+                return;
+            }
+            delayInS = Math.min(delayInS, remainingInMs / 1000);
+        }
+        this.timer = setTimeout(() => {
+            this.refresh().catch((refreshError) => {
+                // Swallow a transient refresh failure but surface it so the caller can react; the next
+                // gRPC call gets the stale (possibly expired) token and re-logs in on UNAUTHENTICATED.
+                if (this.onRefreshErrorHandler !== null) {
+                    this.onRefreshErrorHandler(refreshError);
+                }
+            });
+        }, delayInS * 1000);
+        // Do not keep the event loop alive solely for the refresh timer.
+        /* c8 ignore next 3 -- the else branch is unreachable: Node's Timeout always exposes unref() */
+        if (typeof this.timer.unref === 'function') {
+            this.timer.unref();
+        }
+    }
+    /**
+     * Register a callback invoked with the error of a failed background refresh (optional diagnostics).
+     * A later call replaces any previously registered handler.
+     *
+     * @param handler - Receives the rejection value of a failed background refresh.
+     */
+    onRefreshError(handler) {
+        this.onRefreshErrorHandler = handler;
+    }
+    /**
+     * Read the current access token.
+     *
+     * @returns The current access token, or `null` before bootstrap / after the bounded loop has lapsed.
+     */
+    getAccessToken() {
+        return this.accessToken;
+    }
+    /**
+     * Build the value for an `Authorization` gRPC metadata header.
+     *
+     * @returns The header value `Bearer <access_token>`.
+     * @throws {@link TokenError} If no access token is available (login not completed or already lapsed).
+     */
+    getAuthorizationHeader() {
+        if (this.accessToken === null) {
+            throw new TokenError('No access token available; login() has not completed or has lapsed');
+        }
+        return `Bearer ${this.accessToken}`;
+    }
+    /**
+     * Stop the auto-refresh loop and clear any pending timer. Idempotent; safe to call from any state.
+     * After this the access token is no longer renewed and will eventually lapse.
+     */
+    stop() {
+        this.stopped = true;
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+}
+exports.OfflineTokenProvider = OfflineTokenProvider;
+/**
+ * One-time ROPC + offline_access login against the PUBLIC SDK client, returning a live token provider
+ * whose access token is auto-refreshed in the background until `tokenExpirationInS` elapses.
+ *
+ * @param options - The D18 headless-SDK offline-token login options; the five string fields
+ *   (`keycloakUrl`, `realm`, `clientId`, `username`, `password`) are required and must be non-empty.
+ * @returns A promise resolving to a bootstrapped {@link OfflineTokenProvider} with its first refresh armed.
+ * @throws {@link TokenError} If `options` is missing, a required field is absent/empty, or the
+ *   bootstrap login fails (see {@link OfflineTokenProvider.bootstrap}).
+ */
+async function login(options) {
+    if (options === undefined || options === null) {
+        throw new TokenError('login() requires an options object');
+    }
+    const requiredKeys = ['keycloakUrl', 'realm', 'clientId', 'username', 'password'];
+    for (const key of requiredKeys) {
+        const value = options[key];
+        if (typeof value !== 'string' || value.length === 0) {
+            throw new TokenError(`login() option "${key}" is required and must be a non-empty string`);
+        }
+    }
+    const provider = new OfflineTokenProvider(options);
+    await provider.bootstrap(options.username, options.password);
+    return provider;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ondewo/s2t-client-typescript",
-  "version": "7.4.1",
+  "version": "7.5.0",
   "description": "ONDEWO Speech to Text (S2T) Client library for Typescript",
   "author": "ONDEWO GmbH <office@ondewo.com>",
   "homepage": "https://ondewo.com",

package/public-api.d.ts

@@ -1,4 +1,5 @@
+export * from './api/google/protobuf/struct_pb.d';
+export * from './api/google/protobuf/empty_pb.d';
 export * from './api/ondewo/s2t/speech-to-text_pb.d';
 export * from './api/ondewo/s2t/speech-to-text_grpc_web_pb.d';
-export * from './api/google/protobuf/empty_pb.d';
-export * from './api/google/protobuf/struct_pb.d';
+export * from './auth/offlineTokenProvider';

package/public-api.js

@@ -1,4 +1,5 @@
-export * from './api/ondewo/s2t/speech-to-text_pb';
-export * from './api/ondewo/s2t/speech-to-text_grpc_web_pb';
-export * from './api/google/protobuf/empty_pb';
 export * from './api/google/protobuf/struct_pb';
+export * from './api/google/protobuf/empty_pb';
+export * from './api/ondewo/s2t/speech-to-text_grpc_web_pb';
+export * from './api/ondewo/s2t/speech-to-text_pb';
+export * from './auth/offlineTokenProvider';