@ondewo/s2t-client-typescript 7.4.1 → 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

@@ -0,0 +1,218 @@
+/**
+ * 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;
+/** 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.
+ */
+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;
+    /**
+     * 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.
+     */
+    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>;
+export * from './grpcWebEndpoint';