@ondewo/s2t-client-typescript 7.4.1 → 7.5.1

package/README.md

@@ -52,13 +52,18 @@ npm
 │   ├── google
 │   │   └── protobuf
 │   │       ├── empty_pb.d.ts
-│   │       └── empty_pb.js
+│   │       ├── empty_pb.js
+│   │       ├── struct_pb.d.ts
+│   │       └── struct_pb.js
 │   └── ondewo
 │       └── s2t
 │           ├── speech-to-text_grpc_web_pb.d.ts
 │           ├── speech-to-text_grpc_web_pb.js
 │           ├── speech-to-text_pb.d.ts
 │           └── speech-to-text_pb.js
+├── auth
+│   ├── offlineTokenProvider.d.ts
+│   └── offlineTokenProvider.js
 ├── LICENSE
 ├── package.json
 ├── public-api.d.ts
@@ -66,3 +71,167 @@ npm
 └── README.md
 ```
 
+`api/` and `public-api.*` are generated from `ondewo/s2t/speech-to-text.proto` by the
+[ONDEWO PROTO COMPILER](https://github.com/ondewo/ondewo-proto-compiler); `auth/` is hand-written and compiled into
+the package by `make create_npm_package`.
+
+## Authentication
+
+The service expects a Keycloak bearer token in the `authorization` gRPC metadata header. `auth/offlineTokenProvider`
+performs the headless (2FA-exempt) ROPC + `offline_access` login against the public SDK client and keeps the
+short-lived access token fresh in the background until `tokenExpirationInS` elapses:
+
+```typescript
+import { login, OfflineTokenProvider } from '@ondewo/s2t-client-typescript/auth/offlineTokenProvider';
+import { Speech2TextPromiseClient } from '@ondewo/s2t-client-typescript/api/ondewo/s2t/speech-to-text_grpc_web_pb';
+import { ListS2tPipelinesRequest } from '@ondewo/s2t-client-typescript/api/ondewo/s2t/speech-to-text_pb';
+
+const provider: OfflineTokenProvider = await login({
+  keycloakUrl: 'https://auth.ondewo.com/auth',
+  realm: 'ondewo-ccai-platform',
+  clientId: 'ondewo-nlu-cai-sdk-public',
+  username: process.env.KEYCLOAK_USER_NAME ?? '',
+  password: process.env.KEYCLOAK_PASSWORD ?? ''
+  // keycloakVerifySsl: false  // ONLY for a self-signed local Envoy; Node-only, ignored in a browser
+});
+
+const client = new Speech2TextPromiseClient('http://localhost:8080');
+const request = new ListS2tPipelinesRequest();
+request.setLanguagesList(['en-US']);
+const response = await client.listS2tPipelines(request, { Authorization: provider.getAuthorizationHeader() });
+
+provider.stop(); // stops the background refresh loop so the process can exit
+```
+
+A runnable version of exactly this flow, configured from `examples/environment.env`, lives in
+`examples/ts-client.ts`.
+
+## TLS, mutual TLS and certificates
+
+This package is a **gRPC-web** client. Its generated clients send every call through the browser's `XMLHttpRequest`
+to a gRPC-web proxy (Envoy) in front of the ONDEWO service, so TLS is the browser's TLS: the browser verifies the
+server certificate against its own (operating system / browser) trust store, and a client certificate for mutual TLS
+can only come from the browser's own certificate store. Page code cannot hand a CA certificate, a client certificate
+or a private key to the browser, so this SDK takes none of them; never ship a private key to a browser.
+
+`createGrpcWebEndpoint` turns `host` / `port` / `useSecureChannel` into the `hostname` URL and the client options
+every generated `*Client` / `*PromiseClient` takes:
+
+| Mode                           | `createGrpcWebEndpoint` config                                      | Where the certificates live                                                                                                                                      |
+|--------------------------------|---------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Plaintext (not for production) | `useSecureChannel: false`                                           | none; builds `http://host:port` and logs a warning naming `host:port`                                                                                            |
+| TLS, publicly trusted server   | `useSecureChannel: true` (the default)                              | the server certificate chains to a CA the browser already trusts                                                                                                 |
+| TLS, private CA                | `useSecureChannel: true`                                            | install the CA (`ca.pem`) in the operating system or browser trust store                                                                                         |
+| Mutual TLS                     | `useSecureChannel: true`, plus `withCredentials: true` cross-origin | install the client certificate and key (`client.p12`) in the operating system or browser certificate store; the proxy requests it and verifies it against its CA |
+
+Rules the code enforces:
+
+- A config carrying `grpcCert`, `grpcClientCert` or `grpcClientKey` (or the Python spellings `grpc_cert`,
+  `grpc_client_cert`, `grpc_client_key`) with a non-empty value throws an `Error` naming the field, instead of
+  silently ignoring a certificate you meant to use. Empty values are ignored, so a config ported from another ONDEWO
+  SDK with blank TLS fields still works.
+- `host` is a bare host name or IP address (no scheme, credentials, path or port); a bare IPv6 literal is bracketed
+  (`::1` becomes `https://[::1]:50051`). `port` is an integer 1-65535 (number or numeric string).
+- `useSecureChannel` and `withCredentials` must be booleans: parse environment strings yourself (`'false'` is refused,
+  not read as `true`).
+- `useSecureChannel: false` logs a warning naming `host:port` through `console.warn`, or through the logger passed as
+  the second argument. No error message renders a value of a refused field or the host of a refused URL.
+- `withCredentials: true` is gRPC-web's option for cross-origin calls: only then does the browser send cookies, HTTP
+  authentication **and its TLS client certificate** to a proxy on another origin. A same-origin proxy does not need it.
+
+```ts
+import { createGrpcWebEndpoint } from '@ondewo/s2t-client-typescript/auth/offlineTokenProvider';
+import { Speech2TextPromiseClient } from '@ondewo/s2t-client-typescript/api/ondewo/s2t/speech-to-text_grpc_web_pb';
+
+const endpoint = createGrpcWebEndpoint({
+ host: 's2t.example.com',
+ port: 443,
+ withCredentials: true // only for mutual TLS against a proxy on another origin
+});
+const client = new Speech2TextPromiseClient(endpoint.hostname, null, endpoint.options);
+```
+
+**Node.js.** The generated clients need `XMLHttpRequest`, which Node.js does not provide (a call fails with
+`XMLHttpRequest is not defined`), so this package's gRPC calls run in browsers only; in Node.js only the Keycloak
+`login` helper is usable. There is therefore no Node.js path for a custom CA or a client certificate in this SDK: for
+a server-side client use the ONDEWO Python SDK, or generate a native `@grpc/grpc-js` client from the
+[API protos](https://github.com/ondewo/ondewo-s2t-api) and pass your PEM files to `credentials.createSsl(ca, clientKey, clientCert)`.
+
+### The proxy side of mutual TLS
+
+The browser only offers a client certificate when the TLS server asks for one. With Envoy as the gRPC-web proxy:
+
+```yaml
+transport_socket:
+  name: envoy.transport_sockets.tls
+  typed_config:
+    '@type': type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
+    require_client_certificate: true
+    common_tls_context:
+      tls_certificates:
+        - certificate_chain: { filename: /etc/envoy/certs/server.pem }
+          private_key: { filename: /etc/envoy/certs/server.key }
+      validation_context:
+        trusted_ca: { filename: /etc/envoy/certs/ca.pem }
+```
+
+For a cross-origin page the CORS policy must allow credentials with an explicit origin (`allow_credentials: true`;
+`Access-Control-Allow-Origin: *` is rejected by the browser for a credentialed request). Envoy may in turn connect to
+the ONDEWO service over TLS or mutual TLS with its own (upstream) certificate.
+
+### A test PKI with openssl
+
+A CA, a server certificate with SANs, and a client certificate with the `clientAuth` extended key usage, bundled as
+PKCS#12 for import into a browser or operating system certificate store. For tests only: the keys are unencrypted.
+
+```bash
+openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes -days 365 \
+  -subj "/CN=Test CA" -keyout ca.key -out ca.pem
+
+printf 'subjectAltName=DNS:localhost,IP:127.0.0.1\nextendedKeyUsage=serverAuth\n' > server.ext
+openssl req -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \
+  -subj "/CN=localhost" -keyout server.key -out server.csr
+openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key -CAcreateserial -days 365 \
+  -extfile server.ext -out server.pem
+
+printf 'extendedKeyUsage=clientAuth\n' > client.ext
+openssl req -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \
+  -subj "/CN=my-client" -keyout client.key -out client.csr
+openssl x509 -req -in client.csr -CA ca.pem -CAkey ca.key -CAcreateserial -days 365 \
+  -extfile client.ext -out client.pem
+openssl pkcs12 -export -in client.pem -inkey client.key -certfile ca.pem -name my-client -out client.p12
+
+chmod 600 *.key client.p12
+openssl verify -CAfile ca.pem server.pem client.pem
+```
+
+Envoy uses `server.pem` / `server.key` and trusts `ca.pem` for its clients; the browser trusts `ca.pem` and imports
+`client.p12`.
+
+### TLS security notes
+
+- The private key of a client certificate belongs in the operating system / browser certificate store, never in page
+  code, a bundle, `localStorage` or a config file served to the browser. This SDK refuses one rather than carry it.
+- `createGrpcWebEndpoint` returns only the URL and `{ withCredentials }`; logging it reveals no secret.
+- The Keycloak tokens are secrets too: `JSON.stringify(provider)`, `console.log(provider)` and `util.inspect(provider)`
+  of the `OfflineTokenProvider` (also nested in another object) render the access and refresh tokens as
+  `***REDACTED***` (`getAuthorizationHeader()` still returns the real one). Do not log the `Authorization` header
+  yourself.
+- `withCredentials: true` also sends the page's cookies for the proxy's origin; restrict the proxy's allowed origins.
+
+### TLS troubleshooting
+
+grpc-web reports a failed TLS connection only as a generic error (the browser hides the TLS cause from JavaScript);
+the cause is in the browser's developer tools (Console / Network tab):
+
+- **`net::ERR_CERT_AUTHORITY_INVALID`**: the server certificate does not chain to a CA the browser trusts. Install
+  the CA in the trust store, or use a publicly trusted certificate.
+- **`net::ERR_CERT_COMMON_NAME_INVALID`**: the host you connect to is not among the certificate's subject alternative
+  names. Connect by a name in the SAN, or reissue the certificate (an IP needs an `IP:` SAN).
+- **`net::ERR_BAD_SSL_CLIENT_AUTH_CERT`** / **`net::ERR_SSL_CLIENT_AUTH_CERT_NEEDED`**: the proxy requires a client
+  certificate and the browser offered none, or one not signed by the proxy's `trusted_ca`. Import `client.p12`, pick
+  it when the browser asks, and check `openssl verify -CAfile ca.pem client.pem`.
+- **Mixed content blocked**: an `https://` page cannot call an `http://` endpoint; use `useSecureChannel: true`.
+- **CORS error only with `withCredentials: true`**: the proxy answers with `Access-Control-Allow-Origin: *` or
+  without `Access-Control-Allow-Credentials: true`.
+

package/api/google/protobuf/empty_pb.js

@@ -13,13 +13,7 @@
 
 var jspb = require('google-protobuf');
 var goog = jspb;
-var global =
-    (typeof globalThis !== 'undefined' && globalThis) ||
-    (typeof window !== 'undefined' && window) ||
-    (typeof global !== 'undefined' && global) ||
-    (typeof self !== 'undefined' && self) ||
-    (function () { return this; }).call(null) ||
-    Function('return this')();
+var global = globalThis;
 
 goog.exportSymbol('proto.google.protobuf.Empty', null, global);
 /**
@@ -88,7 +82,7 @@ proto.google.protobuf.Empty.toObject = function(includeInstance, msg) {
 
 /**
  * Deserializes binary data (in protobuf wire format).
- * @param {jspb.ByteSource} bytes The bytes to deserialize.
+ * @param {jspb.binary.bytesource.ByteSource} bytes The bytes to deserialize.
  * @return {!proto.google.protobuf.Empty}
  */
 proto.google.protobuf.Empty.deserializeBinary = function(bytes) {

package/api/google/protobuf/struct_pb.js

@@ -13,13 +13,7 @@
 
 var jspb = require('google-protobuf');
 var goog = jspb;
-var global =
-    (typeof globalThis !== 'undefined' && globalThis) ||
-    (typeof window !== 'undefined' && window) ||
-    (typeof global !== 'undefined' && global) ||
-    (typeof self !== 'undefined' && self) ||
-    (function () { return this; }).call(null) ||
-    Function('return this')();
+var global = globalThis;
 
 goog.exportSymbol('proto.google.protobuf.ListValue', null, global);
 goog.exportSymbol('proto.google.protobuf.NullValue', null, global);
@@ -134,7 +128,7 @@ fieldsMap: (f = msg.getFieldsMap()) ? f.toObject(includeInstance, proto.google.p
 
 /**
  * Deserializes binary data (in protobuf wire format).
- * @param {jspb.ByteSource} bytes The bytes to deserialize.
+ * @param {jspb.binary.bytesource.ByteSource} bytes The bytes to deserialize.
  * @return {!proto.google.protobuf.Struct}
  */
 proto.google.protobuf.Struct.deserializeBinary = function(bytes) {
@@ -161,7 +155,7 @@ proto.google.protobuf.Struct.deserializeBinaryFromReader = function(msg, reader)
     case 1:
       var value = msg.getFieldsMap();
       reader.readMessage(value, function(message, reader) {
-        jspb.Map.deserializeBinary(message, reader, jspb.BinaryReader.prototype.readString, jspb.BinaryReader.prototype.readMessage, proto.google.protobuf.Value.deserializeBinaryFromReader, "", new proto.google.protobuf.Value());
+        jspb.Map.deserializeBinary(message, reader, jspb.BinaryReader.prototype.readStringRequireUtf8, jspb.BinaryReader.prototype.readMessage, proto.google.protobuf.Value.deserializeBinaryFromReader, "", new proto.google.protobuf.Value());
          });
       break;
     default:
@@ -195,7 +189,13 @@ proto.google.protobuf.Struct.serializeBinaryToWriter = function(message, writer)
   var f = undefined;
   f = message.getFieldsMap(true);
   if (f && f.getLength() > 0) {
-    f.serializeBinary(1, writer, jspb.BinaryWriter.prototype.writeString, jspb.BinaryWriter.prototype.writeMessage, proto.google.protobuf.Value.serializeBinaryToWriter);
+jspb.internal.public_for_gencode.serializeMapToBinary(
+    message.getFieldsMap(true),
+    1,
+    writer,
+    jspb.BinaryWriter.prototype.writeString,
+    jspb.BinaryWriter.prototype.writeMessage,
+    proto.google.protobuf.Value.serializeBinaryToWriter);
   }
 };
 
@@ -303,7 +303,7 @@ listValue: (f = msg.getListValue()) && proto.google.protobuf.ListValue.toObject(
 
 /**
  * Deserializes binary data (in protobuf wire format).
- * @param {jspb.ByteSource} bytes The bytes to deserialize.
+ * @param {jspb.binary.bytesource.ByteSource} bytes The bytes to deserialize.
  * @return {!proto.google.protobuf.Value}
  */
 proto.google.protobuf.Value.deserializeBinary = function(bytes) {
@@ -336,7 +336,7 @@ proto.google.protobuf.Value.deserializeBinaryFromReader = function(msg, reader)
       msg.setNumberValue(value);
       break;
     case 3:
-      var value = /** @type {string} */ (reader.readString());
+      var value = /** @type {string} */ (reader.readStringRequireUtf8());
       msg.setStringValue(value);
       break;
     case 4:
@@ -700,7 +700,7 @@ valuesList: jspb.Message.toObjectList(msg.getValuesList(),
 
 /**
  * Deserializes binary data (in protobuf wire format).
- * @param {jspb.ByteSource} bytes The bytes to deserialize.
+ * @param {jspb.binary.bytesource.ByteSource} bytes The bytes to deserialize.
  * @return {!proto.google.protobuf.ListValue}
  */
 proto.google.protobuf.ListValue.deserializeBinary = function(bytes) {

package/api/ondewo/s2t/speech-to-text_pb.d.ts

@@ -2091,6 +2091,22 @@ export class VoiceActivityDetection extends jspb.Message {
   hasPyannote(): boolean;
   clearPyannote(): VoiceActivityDetection;
 
+  getSilero(): Silero | undefined;
+  setSilero(value?: Silero): VoiceActivityDetection;
+  hasSilero(): boolean;
+  clearSilero(): VoiceActivityDetection;
+
+  getWespeakerTsd(): WespeakerTsd | undefined;
+  setWespeakerTsd(value?: WespeakerTsd): VoiceActivityDetection;
+  hasWespeakerTsd(): boolean;
+  clearWespeakerTsd(): VoiceActivityDetection;
+
+  getVadMethod(): VadMethod;
+  setVadMethod(value: VadMethod): VoiceActivityDetection;
+
+  getTsdMethod(): TsdMethod;
+  setTsdMethod(value: TsdMethod): VoiceActivityDetection;
+
   serializeBinary(): Uint8Array;
   toObject(includeInstance?: boolean): VoiceActivityDetection.AsObject;
   static toObject(includeInstance: boolean, msg: VoiceActivityDetection): VoiceActivityDetection.AsObject;
@@ -2104,6 +2120,10 @@ export namespace VoiceActivityDetection {
     active: string,
     samplingRate: number,
     pyannote?: Pyannote.AsObject,
+    silero?: Silero.AsObject,
+    wespeakerTsd?: WespeakerTsd.AsObject,
+    vadMethod: VadMethod,
+    tsdMethod: TsdMethod,
   }
 }
 
@@ -2145,6 +2165,136 @@ export namespace Pyannote {
   }
 }
 
+export class Silero extends jspb.Message {
+  getModelName(): string;
+  setModelName(value: string): Silero;
+
+  getMinAudioSize(): number;
+  setMinAudioSize(value: number): Silero;
+
+  getThreshold(): number;
+  setThreshold(value: number): Silero;
+  hasThreshold(): boolean;
+  clearThreshold(): Silero;
+
+  getMinSpeechDurationMs(): number;
+  setMinSpeechDurationMs(value: number): Silero;
+  hasMinSpeechDurationMs(): boolean;
+  clearMinSpeechDurationMs(): Silero;
+
+  getMinSilenceDurationMs(): number;
+  setMinSilenceDurationMs(value: number): Silero;
+  hasMinSilenceDurationMs(): boolean;
+  clearMinSilenceDurationMs(): Silero;
+
+  getSpeechPadMs(): number;
+  setSpeechPadMs(value: number): Silero;
+  hasSpeechPadMs(): boolean;
+  clearSpeechPadMs(): Silero;
+
+  getTritonServerHost(): string;
+  setTritonServerHost(value: string): Silero;
+
+  getTritonServerPort(): number;
+  setTritonServerPort(value: number): Silero;
+
+  serializeBinary(): Uint8Array;
+  toObject(includeInstance?: boolean): Silero.AsObject;
+  static toObject(includeInstance: boolean, msg: Silero): Silero.AsObject;
+  static serializeBinaryToWriter(message: Silero, writer: jspb.BinaryWriter): void;
+  static deserializeBinary(bytes: Uint8Array): Silero;
+  static deserializeBinaryFromReader(message: Silero, reader: jspb.BinaryReader): Silero;
+}
+
+export namespace Silero {
+  export type AsObject = {
+    modelName: string,
+    minAudioSize: number,
+    threshold?: number,
+    minSpeechDurationMs?: number,
+    minSilenceDurationMs?: number,
+    speechPadMs?: number,
+    tritonServerHost: string,
+    tritonServerPort: number,
+  }
+
+  export enum ThresholdCase { 
+    _THRESHOLD_NOT_SET = 0,
+    THRESHOLD = 3,
+  }
+
+  export enum MinSpeechDurationMsCase { 
+    _MIN_SPEECH_DURATION_MS_NOT_SET = 0,
+    MIN_SPEECH_DURATION_MS = 4,
+  }
+
+  export enum MinSilenceDurationMsCase { 
+    _MIN_SILENCE_DURATION_MS_NOT_SET = 0,
+    MIN_SILENCE_DURATION_MS = 5,
+  }
+
+  export enum SpeechPadMsCase { 
+    _SPEECH_PAD_MS_NOT_SET = 0,
+    SPEECH_PAD_MS = 6,
+  }
+}
+
+export class WespeakerTsd extends jspb.Message {
+  getActive(): boolean;
+  setActive(value: boolean): WespeakerTsd;
+
+  getModelName(): string;
+  setModelName(value: string): WespeakerTsd;
+
+  getTritonServerHost(): string;
+  setTritonServerHost(value: string): WespeakerTsd;
+
+  getTritonServerPort(): number;
+  setTritonServerPort(value: number): WespeakerTsd;
+
+  getSimilarityThreshold(): number;
+  setSimilarityThreshold(value: number): WespeakerTsd;
+  hasSimilarityThreshold(): boolean;
+  clearSimilarityThreshold(): WespeakerTsd;
+
+  getMinAudioLength(): number;
+  setMinAudioLength(value: number): WespeakerTsd;
+  hasMinAudioLength(): boolean;
+  clearMinAudioLength(): WespeakerTsd;
+
+  getReferenceMaxLength(): number;
+  setReferenceMaxLength(value: number): WespeakerTsd;
+
+  serializeBinary(): Uint8Array;
+  toObject(includeInstance?: boolean): WespeakerTsd.AsObject;
+  static toObject(includeInstance: boolean, msg: WespeakerTsd): WespeakerTsd.AsObject;
+  static serializeBinaryToWriter(message: WespeakerTsd, writer: jspb.BinaryWriter): void;
+  static deserializeBinary(bytes: Uint8Array): WespeakerTsd;
+  static deserializeBinaryFromReader(message: WespeakerTsd, reader: jspb.BinaryReader): WespeakerTsd;
+}
+
+export namespace WespeakerTsd {
+  export type AsObject = {
+    active: boolean,
+    modelName: string,
+    tritonServerHost: string,
+    tritonServerPort: number,
+    similarityThreshold?: number,
+    minAudioLength?: number,
+    referenceMaxLength: number,
+  }
+
+  export enum SimilarityThresholdCase { 
+    _SIMILARITY_THRESHOLD_NOT_SET = 0,
+    SIMILARITY_THRESHOLD = 5,
+  }
+
+  export enum MinAudioLengthCase { 
+    _MIN_AUDIO_LENGTH_NOT_SET = 0,
+    MIN_AUDIO_LENGTH = 6,
+  }
+}
+
 export class PostProcessing extends jspb.Message {
   getPipelineList(): Array<string>;
   setPipelineList(value: Array<string>): PostProcessing;
@@ -2964,3 +3114,14 @@ export enum ReasoningEffort {
   REASONING_EFFORT_MEDIUM = 3,
   REASONING_EFFORT_HIGH = 4,
 }
+export enum VadMethod { 
+  VAD_METHOD_UNSPECIFIED = 0,
+  VAD_METHOD_PYANNOTE = 1,
+  VAD_METHOD_SILERO = 2,
+}
+export enum TsdMethod { 
+  TSD_METHOD_UNSPECIFIED = 0,
+  TSD_METHOD_NONE = 1,
+  TSD_METHOD_PYANNOTE = 2,
+  TSD_METHOD_WESPEAKER = 3,
+}