@ondewo/s2t-client-typescript 7.5.0 → 7.5.1

package/README.md

@@ -106,3 +106,132 @@ 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) {