@ondewo/s2t-client-typescript 7.5.0 → 7.5.1

package/auth/grpcWebEndpoint.d.ts

@@ -0,0 +1,80 @@
+/**
+ * gRPC-web endpoint helper: turns `host` / `port` / `useSecureChannel` into the `hostname` URL and the
+ * client options every generated `*Client` / `*PromiseClient` constructor takes.
+ *
+ * TLS in a browser belongs to the browser: the server certificate is verified against the browser's /
+ * operating system's trust store, and a client certificate (mutual TLS) can only come from the
+ * browser's own certificate store. So this helper accepts no CA, no client certificate and no private
+ * key -- a config carrying one (e.g. ported from the Python SDK's `grpc_cert` / `grpc_client_cert` /
+ * `grpc_client_key`) is refused instead of silently dropped, and a private key never has to be shipped to
+ * a browser. See the README section "TLS, mutual TLS and certificates".
+ *
+ * @packageDocumentation
+ */
+/** Connection settings of one gRPC-web (Envoy) endpoint. */
+export interface GrpcWebEndpointConfig {
+    /** Bare host name or IP address (IPv6 with or without brackets); no scheme, port or path. */
+    host: string;
+    /** TCP port, 1-65535. */
+    port: number | string;
+    /** `true` (the default) builds an `https://` URL; `false` builds a plaintext `http://` one and warns. */
+    useSecureChannel?: boolean;
+    /**
+     * Send credentials on cross-origin calls (gRPC-web's `withCredentials` client option, default
+     * `false`). Cookies, HTTP auth and the browser's TLS client certificate (mutual TLS) are only sent on
+     * a cross-origin request when this is `true`.
+     */
+    withCredentials?: boolean;
+}
+/** The client options this helper sets; pass them as the third argument of a generated client. */
+export interface GrpcWebClientOptions {
+    /** gRPC-web's `withCredentials` option. */
+    withCredentials: boolean;
+}
+/** What a generated gRPC-web client constructor takes: `new XClient(hostname, null, options)`. */
+export interface GrpcWebEndpoint {
+    /** `https://host:port` (or `http://` for an insecure channel); IPv6 hosts are bracketed. */
+    readonly hostname: string;
+    /** The gRPC-web client options. */
+    readonly options: GrpcWebClientOptions;
+}
+/** Where the insecure-channel warning goes (the global `console` by default). */
+export interface GrpcWebEndpointLogger {
+    /**
+     * Write one warning.
+     *
+     * @param message - The warning text.
+     */
+    warn(message: string): void;
+}
+/**
+ * Config fields of the other ONDEWO SDKs (camelCase and Python's snake_case) that a browser cannot use,
+ * with the reason each is refused. A non-empty value for any of them raises; an empty one is ignored.
+ */
+export declare const REFUSED_TLS_FIELDS: Readonly<Record<string, string>>;
+/**
+ * Render `host:port` for a URL, bracketing a bare IPv6 literal (`::1` -> `[::1]:50051`).
+ *
+ * @param host - A bare host name, IPv4 address, or IPv6 address with or without brackets.
+ * @param port - The port.
+ * @returns `host:port`.
+ * @throws {Error} When the host contains a colon but is neither a bracketed nor a bare IPv6 literal.
+ */
+export declare function hostAndPort(host: string, port: number | string): string;
+/**
+ * Validate a gRPC-web endpoint config and build the `hostname` URL and client options for a generated client.
+ *
+ * ```ts
+ * const endpoint: GrpcWebEndpoint = createGrpcWebEndpoint({ host: 'nlu.example.com', port: 443 });
+ * const agents: AgentsClient = new AgentsClient(endpoint.hostname, null, endpoint.options);
+ * ```
+ *
+ * Error messages name the offending field only, never its value.
+ *
+ * @param config - Host, port and channel settings.
+ * @param logger - Receives the warning for an insecure channel (default: the global `console`).
+ * @returns The endpoint URL and the gRPC-web client options.
+ * @throws {Error} When `host` / `port` / `useSecureChannel` / `withCredentials` is invalid, or the config
+ *   carries a CA, client certificate or private key (see {@link REFUSED_TLS_FIELDS}).
+ */
+export declare function createGrpcWebEndpoint(config: GrpcWebEndpointConfig, logger?: GrpcWebEndpointLogger): GrpcWebEndpoint;

package/auth/grpcWebEndpoint.js

@@ -0,0 +1,121 @@
+"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.
+//
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REFUSED_TLS_FIELDS = void 0;
+exports.hostAndPort = hostAndPort;
+exports.createGrpcWebEndpoint = createGrpcWebEndpoint;
+/** Why a browser cannot use a CA certificate given in code. */
+const CA_REASON = 'a browser verifies the server certificate against its own trust store; install the CA there or use a publicly trusted certificate';
+/** Why a browser cannot use a client certificate given in code. */
+const CLIENT_CERT_REASON = 'a browser presents a TLS client certificate only from its own certificate store; install the client certificate there';
+/** Why a private key is refused. */
+const CLIENT_KEY_REASON = 'a private key must never be shipped to a browser; install the client certificate in its certificate store';
+/**
+ * Config fields of the other ONDEWO SDKs (camelCase and Python's snake_case) that a browser cannot use,
+ * with the reason each is refused. A non-empty value for any of them raises; an empty one is ignored.
+ */
+exports.REFUSED_TLS_FIELDS = {
+    grpcCert: CA_REASON,
+    grpc_cert: CA_REASON,
+    grpcClientCert: CLIENT_CERT_REASON,
+    grpc_client_cert: CLIENT_CERT_REASON,
+    grpcClientKey: CLIENT_KEY_REASON,
+    grpc_client_key: CLIENT_KEY_REASON
+};
+/** A bare IPv6 literal: hex groups, colons and an optional embedded IPv4 tail, at least two colons. */
+const BARE_IPV6_PATTERN = /^(?=(?:[^:]*:){2})[0-9A-Fa-f:.]+$/;
+/**
+ * Render `host:port` for a URL, bracketing a bare IPv6 literal (`::1` -> `[::1]:50051`).
+ *
+ * @param host - A bare host name, IPv4 address, or IPv6 address with or without brackets.
+ * @param port - The port.
+ * @returns `host:port`.
+ * @throws {Error} When the host contains a colon but is neither a bracketed nor a bare IPv6 literal.
+ */
+function hostAndPort(host, port) {
+    if (host.startsWith('[') && host.endsWith(']')) {
+        return `${host}:${port}`;
+    }
+    if (BARE_IPV6_PATTERN.test(host)) {
+        return `[${host}]:${port}`;
+    }
+    if (host.includes(':')) {
+        throw new Error('GrpcWebEndpointConfig.host must not contain a port; pass the port in GrpcWebEndpointConfig.port');
+    }
+    return `${host}:${port}`;
+}
+/**
+ * Validate a gRPC-web endpoint config and build the `hostname` URL and client options for a generated client.
+ *
+ * ```ts
+ * const endpoint: GrpcWebEndpoint = createGrpcWebEndpoint({ host: 'nlu.example.com', port: 443 });
+ * const agents: AgentsClient = new AgentsClient(endpoint.hostname, null, endpoint.options);
+ * ```
+ *
+ * Error messages name the offending field only, never its value.
+ *
+ * @param config - Host, port and channel settings.
+ * @param logger - Receives the warning for an insecure channel (default: the global `console`).
+ * @returns The endpoint URL and the gRPC-web client options.
+ * @throws {Error} When `host` / `port` / `useSecureChannel` / `withCredentials` is invalid, or the config
+ *   carries a CA, client certificate or private key (see {@link REFUSED_TLS_FIELDS}).
+ */
+function createGrpcWebEndpoint(config, logger = console) {
+    const fields = config;
+    for (const [name, reason] of Object.entries(exports.REFUSED_TLS_FIELDS)) {
+        const value = fields[name];
+        if (value !== undefined && value !== null && value !== '') {
+            throw new Error(`GrpcWebEndpointConfig.${name} is not supported by a gRPC-web client: ${reason}`);
+        }
+    }
+    const host = config.host;
+    if (typeof host !== 'string' || host.trim() === '' || host.trim() !== host) {
+        throw new Error('GrpcWebEndpointConfig.host must be a non-empty host name or IP address without whitespace');
+    }
+    if (host.includes('/') || host.includes('@')) {
+        throw new Error('GrpcWebEndpointConfig.host must be a bare host name or IP address without scheme, credentials or path; ' +
+            'the scheme comes from GrpcWebEndpointConfig.useSecureChannel');
+    }
+    const port = config.port;
+    let portNumber = Number.NaN;
+    if (typeof port === 'number') {
+        portNumber = port;
+    }
+    else if (typeof port === 'string' && /^[0-9]{1,5}$/.test(port)) {
+        portNumber = Number(port);
+    }
+    if (!Number.isInteger(portNumber) || portNumber < 1 || portNumber > 65535) {
+        throw new Error('GrpcWebEndpointConfig.port must be an integer between 1 and 65535');
+    }
+    const useSecureChannel = config.useSecureChannel ?? true;
+    if (typeof useSecureChannel !== 'boolean') {
+        throw new Error('GrpcWebEndpointConfig.useSecureChannel must be a boolean');
+    }
+    const withCredentials = config.withCredentials ?? false;
+    if (typeof withCredentials !== 'boolean') {
+        throw new Error('GrpcWebEndpointConfig.withCredentials must be a boolean');
+    }
+    const target = hostAndPort(host, portNumber);
+    let scheme = 'https';
+    if (!useSecureChannel) {
+        scheme = 'http';
+        logger.warn(`ONDEWO gRPC-web: the channel to ${target} is NOT encrypted (useSecureChannel=false); use it only for local development`);
+    }
+    return {
+        hostname: `${scheme}://${target}`,
+        options: { withCredentials }
+    };
+}

package/auth/offlineTokenProvider.d.ts

@@ -92,6 +92,21 @@ export declare const INSECURE_AGENT_OPTIONS: {
  * @returns A {@link TokenFetch} that resolves the global fetch at call time (honoring test overrides).
  */
 export declare function createDefaultTokenFetch(verifySsl: boolean): TokenFetch;
+/** What {@link OfflineTokenProvider.toJSON} renders in place of a non-empty token. */
+export declare const REDACTED: string;
+/** The logging-safe view of an {@link OfflineTokenProvider}: both tokens redacted. */
+export interface OfflineTokenProviderLogView {
+    /** The OIDC token endpoint. */
+    tokenEndpoint: string;
+    /** The Keycloak client id. */
+    clientId: string;
+    /** `***REDACTED***`, or the token as is when it is `null` (before login) or empty. */
+    accessToken: string | null;
+    /** `***REDACTED***`, or the token as is when it is `null` (before login) or empty. */
+    refreshToken: string | null;
+    /** Whether {@link OfflineTokenProvider.stop} was called. */
+    stopped: boolean;
+}
 /**
  * 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.
@@ -174,6 +189,15 @@ export declare class OfflineTokenProvider {
      * @throws {@link TokenError} If no access token is available (login not completed or already lapsed).
      */
     getAuthorizationHeader(): string;
+    /**
+     * 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(): OfflineTokenProviderLogView;
     /**
      * 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.
@@ -191,3 +215,4 @@ export declare class OfflineTokenProvider {
  *   bootstrap login fails (see {@link OfflineTokenProvider.bootstrap}).
  */
 export declare function login(options: OfflineTokenLoginOptions): Promise<OfflineTokenProvider>;
+export * from './grpcWebEndpoint';

package/auth/offlineTokenProvider.js

@@ -46,8 +46,11 @@ var __importStar = (this && this.__importStar) || (function () {
         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.INSECURE_AGENT_OPTIONS = exports.TokenError = void 0;
+exports.OfflineTokenProvider = exports.REDACTED = exports.INSECURE_AGENT_OPTIONS = exports.TokenError = void 0;
 exports.createDefaultTokenFetch = createDefaultTokenFetch;
 exports.login = login;
 /**
@@ -175,6 +178,20 @@ function createDefaultTokenFetch(verifySsl) {
         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.
@@ -334,6 +351,33 @@ class OfflineTokenProvider {
         }
         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.
@@ -372,3 +416,7 @@ async function login(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.5.0",
+  "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

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

package/public-api.js

@@ -2,4 +2,5 @@ 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';