@ondewo/s2t-client-typescript 7.4.1 → 7.5.1

package/auth/offlineTokenProvider.js

@@ -0,0 +1,422 @@
+"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;
+    };
+})();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfflineTokenProvider = exports.REDACTED = 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);
+    };
+}
+/** What {@link OfflineTokenProvider.toJSON} renders in place of a non-empty token. */
+exports.REDACTED = '***REDACTED***';
+/**
+ * Redact a token for logging: `null` and `''` render as is, anything else as {@link REDACTED}.
+ *
+ * @param token - The token to render.
+ * @returns The logging-safe rendering.
+ */
+function redactToken(token) {
+    if (token === null || token === '') {
+        return token;
+    }
+    return exports.REDACTED;
+}
+/**
+ * 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}`;
+    }
+    /**
+     * A logging-safe view of this provider: the access and refresh tokens render as `***REDACTED***`
+     * (`null` before login and an empty token stay as they are). `JSON.stringify(provider)` uses it, and so
+     * do Node's `console.log(provider)` / `util.inspect(provider)` through the hook below, so none of them
+     * prints a token. {@link OfflineTokenProvider.getAuthorizationHeader} still returns the real one.
+     *
+     * @returns The endpoint, client id and stop flag, with both tokens redacted.
+     */
+    toJSON() {
+        return {
+            tokenEndpoint: this.tokenEndpoint,
+            clientId: this.clientId,
+            accessToken: redactToken(this.accessToken),
+            refreshToken: redactToken(this.refreshToken),
+            stopped: this.stopped
+        };
+    }
+    /**
+     * Node's `util.inspect` hook (used by `console.log`): renders {@link OfflineTokenProvider.toJSON}, so
+     * logging the provider never prints a token. Looked up via `Symbol.for`, so no `util` import is needed
+     * and the module stays usable in a browser bundle.
+     *
+     * @returns The redacted view.
+     */
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return this.toJSON();
+    }
+    /**
+     * 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;
+}
+// The gRPC-web endpoint / TLS helper ships through this module: `make create_npm_package` compiles this
+// file (tsc follows the import), so `@ondewo/s2t-client-typescript/auth/offlineTokenProvider` exports both
+// hand-written helpers and a proto-compiler regeneration cannot drop it.
+__exportStar(require("./grpcWebEndpoint"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ondewo/s2t-client-typescript",
-  "version": "7.4.1",
+  "version": "7.5.1",
   "description": "ONDEWO Speech to Text (S2T) Client library for Typescript",
   "author": "ONDEWO GmbH <office@ondewo.com>",
   "homepage": "https://ondewo.com",
@@ -20,7 +20,7 @@
     "directory": "https://github.com/ondewo/ondewo-s2t-client-typescript"
   },
   "dependencies": {
-    "google-protobuf": "3.21.4",
+    "google-protobuf": "4.0.2",
     "grpc-web": "^1.5.0",
     "tslib": "^2.8.1",
     "undici": "^6.27.0"

package/public-api.d.ts

@@ -1,4 +1,6 @@
+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/grpcWebEndpoint';
+export * from './auth/offlineTokenProvider';

package/public-api.js

@@ -1,4 +1,6 @@
-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/grpcWebEndpoint';
+export * from './auth/offlineTokenProvider';