@distrohelena/canton-typescript-sdk 0.1.17 → 0.1.19

package/README.md

@@ -127,6 +127,49 @@ already be a Ledger API user with the appropriate rights on each participant.
 Extra participants use the existing shared-secret onboarding flow; the current
 OAuth2-plus-extras limitation still applies.
 
+### Optional localnet TLS
+
+Set `LOCALNET_TLS=1` to enable TLS on every participant Ledger API and Admin API
+listener, including generated extra participants. TLS is disabled by default,
+so `LOCALNET_TLS=0` preserves the existing Quickstart behavior. The launcher
+uses direct Compose mode when TLS is enabled so it can apply the generated
+configuration overlay.
+
+By default, development-only material is generated in
+`.generated/localnet-tls`: `ca.crt`, `server.crt`, and `server.key`. Set
+`LOCALNET_TLS_ROTATE=1` to replace it. To provide your own material, set all
+three variables together:
+
+```bash
+LOCALNET_TLS=1 \
+LOCALNET_TLS_CERT_CHAIN_PATH=/path/to/server-chain.pem \
+LOCALNET_TLS_PRIVATE_KEY_PATH=/path/to/server-key.pem \
+LOCALNET_TLS_CA_CERT_PATH=/path/to/root-ca.pem \
+canton-localnet-start
+```
+
+The server certificate must cover the hostname used by the client, normally
+`localhost` for host-side SDK calls. Client certificate authentication is not
+enabled; authentication remains controlled by the existing Quickstart
+`AUTH_MODE` and optional ES256 settings.
+
+The SDK gRPC channels remain TLS by default. For generated localnet material,
+pass the generated CA to the client:
+
+```ts
+import { readFileSync } from "node:fs";
+
+const client = new CantonClient(new CantonClientOptions({
+    transportKind: TransportKind.grpc,
+    ledgerEndpoint: "localhost:3901",
+    ledgerAdminEndpoint: "localhost:3902",
+    participantAdminEndpoint: "localhost:3902",
+    grpcTlsRootCertificates: readFileSync(
+        ".generated/localnet-tls/ca.crt",
+    ),
+}));
+```
+
 The live suite runs single-worker with an extended timeout because it mutates and reads a shared localnet.
 
 Prerequisites:

package/dist/client/canton-client-options.d.ts

@@ -9,6 +9,7 @@ export declare class CantonClientOptions {
     readonly ledgerAdminEndpoint?: string;
     readonly participantAdminEndpoint?: string;
     readonly grpcChannelSecurity: GrpcChannelSecurity;
+    readonly grpcTlsRootCertificates?: Uint8Array;
     readonly ledgerGrpcChannelSecurity?: GrpcChannelSecurity;
     readonly ledgerAdminGrpcChannelSecurity?: GrpcChannelSecurity;
     readonly participantAdminGrpcChannelSecurity?: GrpcChannelSecurity;
@@ -25,6 +26,7 @@ export declare class CantonClientOptions {
         ledgerAdminEndpoint?: string;
         participantAdminEndpoint?: string;
         grpcChannelSecurity?: GrpcChannelSecurity;
+        grpcTlsRootCertificates?: Uint8Array;
         ledgerGrpcChannelSecurity?: GrpcChannelSecurity;
         ledgerAdminGrpcChannelSecurity?: GrpcChannelSecurity;
         participantAdminGrpcChannelSecurity?: GrpcChannelSecurity;

package/dist/client/canton-client-options.js

@@ -5,6 +5,7 @@ export class CantonClientOptions {
     ledgerAdminEndpoint;
     participantAdminEndpoint;
     grpcChannelSecurity;
+    grpcTlsRootCertificates;
     ledgerGrpcChannelSecurity;
     ledgerAdminGrpcChannelSecurity;
     participantAdminGrpcChannelSecurity;
@@ -22,6 +23,7 @@ export class CantonClientOptions {
         this.participantAdminEndpoint = init.participantAdminEndpoint;
         this.grpcChannelSecurity =
             init.grpcChannelSecurity ?? GrpcChannelSecurity.tls;
+        this.grpcTlsRootCertificates = init.grpcTlsRootCertificates;
         this.ledgerGrpcChannelSecurity = init.ledgerGrpcChannelSecurity;
         this.ledgerAdminGrpcChannelSecurity =
             init.ledgerAdminGrpcChannelSecurity;

package/dist/transports/grpc/grpc-call-options-factory.d.ts

@@ -1,7 +1,7 @@
 import { IAuthProvider } from "../../core/auth/auth-provider.interface.js";
 import { RequestOptions } from "../../core/types/request-options.js";
 import { GrpcChannelSecurity } from "../../core/types/grpc-channel-security.js";
-export declare function createGrpcChannelCredentials(security: GrpcChannelSecurity): import("@grpc/grpc-js").ChannelCredentials;
+export declare function createGrpcChannelCredentials(security: GrpcChannelSecurity, tlsRootCertificates?: Uint8Array): import("@grpc/grpc-js").ChannelCredentials;
 export declare function buildGrpcCallOptionsAsync(authProvider?: IAuthProvider, defaultTimeoutMs?: number, options?: RequestOptions): Promise<{
     meta: Record<string, string>;
     timeout?: number;

package/dist/transports/grpc/grpc-call-options-factory.js

@@ -1,10 +1,14 @@
 import { credentials } from "@grpc/grpc-js";
+import { Buffer } from "node:buffer";
 import { resolveRequestTimeoutMs } from "../../core/types/request-timeout.js";
 import { GrpcChannelSecurity } from "../../core/types/grpc-channel-security.js";
-export function createGrpcChannelCredentials(security) {
-    return security === GrpcChannelSecurity.insecure
-        ? credentials.createInsecure()
-        : credentials.createSsl();
+export function createGrpcChannelCredentials(security, tlsRootCertificates) {
+    if (security === GrpcChannelSecurity.insecure) {
+        return credentials.createInsecure();
+    }
+    return tlsRootCertificates === undefined
+        ? credentials.createSsl()
+        : credentials.createSsl(Buffer.from(tlsRootCertificates));
 }
 export async function buildGrpcCallOptionsAsync(authProvider, defaultTimeoutMs, options) {
     const timeout = resolveRequestTimeoutMs(defaultTimeoutMs, options);

package/dist/transports/grpc/grpc-channel-factory.js

@@ -32,7 +32,7 @@ import { buildGrpcCallOptionsAsync, createGrpcChannelCredentials, } from "./grpc
 export function createGrpcOperations(options, endpoint, grpcChannelSecurity, dependencies = {}) {
     const rpcTransport = new ProtobufGrpcTransport({
         host: normalizeGrpcHost(endpoint),
-        channelCredentials: createGrpcChannelCredentials(grpcChannelSecurity),
+        channelCredentials: createGrpcChannelCredentials(grpcChannelSecurity, options.grpcTlsRootCertificates),
         clientOptions: options.grpcConnectTimeoutMs === undefined
             ? undefined
             : {

package/node/start-local.sh

@@ -98,6 +98,158 @@ es256_runtime_dir() {
   printf '%s\n' "${START_LOCAL_ES256_RUNTIME_DIR:-$REPO_ROOT/.generated/localnet-es256}"
 }
 
+resolve_tls_enabled() {
+  local value="${LOCALNET_TLS:-0}"
+  if [[ "$value" != "0" && "$value" != "1" ]]; then
+    echo "LOCALNET_TLS must be 0 or 1." >&2
+    return 1
+  fi
+  printf '%s\n' "$value"
+}
+
+resolve_tls_rotate() {
+  local value="${LOCALNET_TLS_ROTATE:-0}"
+  if [[ "$value" != "0" && "$value" != "1" ]]; then
+    echo "LOCALNET_TLS_ROTATE must be 0 or 1." >&2
+    return 1
+  fi
+  printf '%s\n' "$value"
+}
+
+tls_runtime_dir() {
+  printf '%s\n' "${START_LOCAL_TLS_RUNTIME_DIR:-$REPO_ROOT/.generated/localnet-tls}"
+}
+
+prepare_tls_runtime_files() {
+  local enabled
+  enabled="$(resolve_tls_enabled)"
+  if [[ "$enabled" != "1" ]]; then
+    return 0
+  fi
+
+  local runtime_dir
+  runtime_dir="$(tls_runtime_dir)"
+  local ca_key_path="$runtime_dir/ca.key"
+  local ca_certificate_path="$runtime_dir/ca.crt"
+  local server_key_path="$runtime_dir/server.key"
+  local server_certificate_path="$runtime_dir/server.crt"
+  local compose_file="$runtime_dir/compose-localnet.yaml"
+  local tls_fragment_file="$runtime_dir/canton-tls.conf"
+  local canton_config_file="$runtime_dir/canton-localnet.conf"
+  local supplied_count=0
+
+  [[ -n "${LOCALNET_TLS_CERT_CHAIN_PATH:-}" ]] && ((supplied_count += 1))
+  [[ -n "${LOCALNET_TLS_PRIVATE_KEY_PATH:-}" ]] && ((supplied_count += 1))
+  [[ -n "${LOCALNET_TLS_CA_CERT_PATH:-}" ]] && ((supplied_count += 1))
+
+  mkdir -p "$runtime_dir"
+  if (( supplied_count > 0 )); then
+    if (( supplied_count != 3 )); then
+      echo "LOCALNET_TLS_CERT_CHAIN_PATH, LOCALNET_TLS_PRIVATE_KEY_PATH, and LOCALNET_TLS_CA_CERT_PATH must be set together." >&2
+      return 1
+    fi
+    server_certificate_path="$LOCALNET_TLS_CERT_CHAIN_PATH"
+    server_key_path="$LOCALNET_TLS_PRIVATE_KEY_PATH"
+    ca_certificate_path="$LOCALNET_TLS_CA_CERT_PATH"
+    if [[ ! -r "$server_certificate_path" || ! -r "$server_key_path" || ! -r "$ca_certificate_path" ]]; then
+      echo "Supplied TLS certificate, private key, or CA certificate is not readable." >&2
+      return 1
+    fi
+    if ! openssl x509 -in "$server_certificate_path" -noout >/dev/null 2>&1 \
+      || ! openssl pkey -in "$server_key_path" -noout >/dev/null 2>&1 \
+      || ! openssl x509 -in "$ca_certificate_path" -noout >/dev/null 2>&1 \
+      || ! openssl verify -CAfile "$ca_certificate_path" "$server_certificate_path" >/dev/null 2>&1; then
+      echo "Supplied TLS material is not valid PEM certificate/key material." >&2
+      return 1
+    fi
+    local certificate_public_key private_public_key
+    if ! certificate_public_key="$(openssl x509 -in "$server_certificate_path" -pubkey -noout | openssl pkey -pubin -outform DER | sha256sum | awk '{print $1}')" \
+      || ! private_public_key="$(openssl pkey -in "$server_key_path" -pubout | openssl pkey -pubin -outform DER | sha256sum | awk '{print $1}')" \
+      || [[ "$certificate_public_key" != "$private_public_key" ]]; then
+      echo "Supplied TLS private key does not match the server certificate." >&2
+      return 1
+    fi
+  else
+    if [[ "$(resolve_tls_rotate)" == "1" ]]; then
+      rm -f "$ca_key_path" "$ca_certificate_path" "$server_key_path" "$server_certificate_path"
+    fi
+    if [[ ! -e "$ca_key_path" || ! -e "$ca_certificate_path" ]]; then
+      rm -f "$ca_key_path" "$ca_certificate_path"
+      openssl genrsa -out "$ca_key_path" 2048 >/dev/null 2>&1
+      chmod 600 "$ca_key_path"
+      openssl req -x509 -new -sha256 -days 3650 -key "$ca_key_path" \
+        -subj "/CN=localnet-tls-ca" -out "$ca_certificate_path" >/dev/null 2>&1
+    fi
+    if [[ ! -e "$server_key_path" || ! -e "$server_certificate_path" ]]; then
+      rm -f "$server_key_path" "$server_certificate_path"
+      local csr_path="$runtime_dir/server.csr"
+      local extensions_path="$runtime_dir/server-extensions.cnf"
+      openssl genrsa -out "$server_key_path" 2048 >/dev/null 2>&1
+      chmod 600 "$server_key_path"
+      openssl req -new -sha256 -key "$server_key_path" -subj "/CN=localhost" -out "$csr_path" >/dev/null 2>&1
+      cat > "$extensions_path" <<'EOF'
+[server_ext]
+basicConstraints = CA:FALSE
+keyUsage = digitalSignature, keyEncipherment
+extendedKeyUsage = serverAuth
+subjectAltName = DNS:localhost, DNS:canton, IP:127.0.0.1
+EOF
+      openssl x509 -req -sha256 -days 3650 -in "$csr_path" \
+        -CA "$ca_certificate_path" -CAkey "$ca_key_path" -CAcreateserial \
+        -out "$server_certificate_path" -extfile "$extensions_path" -extensions server_ext >/dev/null 2>&1
+      rm -f "$csr_path" "$extensions_path" "$ca_certificate_path.srl"
+    fi
+    if ! openssl x509 -in "$server_certificate_path" -noout >/dev/null 2>&1 \
+      || ! openssl pkey -in "$server_key_path" -noout >/dev/null 2>&1 \
+      || ! openssl x509 -in "$ca_certificate_path" -noout >/dev/null 2>&1; then
+      echo "Generated TLS material is invalid." >&2
+      return 1
+    fi
+  fi
+
+  : > "$tls_fragment_file"
+  local participant profile
+  for participant in app-provider app-user sv; do
+    case "$participant" in
+      app-provider) profile="$APP_PROVIDER_PROFILE" ;;
+      app-user) profile="$APP_USER_PROFILE" ;;
+      sv) profile="$SV_PROFILE" ;;
+    esac
+    if [[ "$profile" != "off" ]]; then
+      cat >> "$tls_fragment_file" <<EOF
+canton.participants.${participant}.ledger-api.tls {
+  cert-chain-file = "/app/localnet-tls/server.crt"
+  private-key-file = "/app/localnet-tls/server.key"
+  trust-collection-file = "/app/localnet-tls/ca.crt"
+}
+canton.participants.${participant}.admin-api.tls {
+  cert-chain-file = "/app/localnet-tls/server.crt"
+  private-key-file = "/app/localnet-tls/server.key"
+  trust-collection-file = "/app/localnet-tls/ca.crt"
+}
+EOF
+    fi
+  done
+  cat > "$canton_config_file" <<'EOF'
+include file("/app/base-app.conf")
+include file("/app/localnet-tls.conf")
+EOF
+  cat > "$compose_file" <<EOF
+services:
+  canton:
+    volumes:
+      - "${LOCALNET_DIR}/conf/canton/app.conf:/app/base-app.conf:ro"
+      - "$canton_config_file:/app/app.conf:ro"
+      - "$tls_fragment_file:/app/localnet-tls.conf:ro"
+      - "$server_certificate_path:/app/localnet-tls/server.crt:ro"
+      - "$server_key_path:/app/localnet-tls/server.key:ro"
+      - "$ca_certificate_path:/app/localnet-tls/ca.crt:ro"
+EOF
+  export LOCALNET_TLS_COMPOSE_FILE="$compose_file"
+  export LOCALNET_TLS_FRAGMENT_FILE="$tls_fragment_file"
+  export LOCALNET_TLS_CA_CERT_PATH="$ca_certificate_path"
+}
+
 prepare_es256_runtime_files() {
   local runtime_dir
   runtime_dir="$(es256_runtime_dir)"
@@ -150,6 +302,8 @@ prepare_es256_runtime_files() {
   cat > "$canton_config_file" <<EOF
 include file("/app/base-app.conf")
 
+$(if [[ "$(resolve_tls_enabled)" == "1" ]]; then printf 'include file("/app/localnet-tls.conf")\n'; fi)
+
 EOF
   local participant profile
   for participant in app-provider app-user sv; do
@@ -195,6 +349,13 @@ append_es256_args() {
   fi
 }
 
+append_tls_args() {
+  local -n compose_args_ref="$1"
+  if [[ "$(resolve_tls_enabled)" == "1" ]]; then
+    compose_args_ref+=( -f "$LOCALNET_TLS_COMPOSE_FILE" )
+  fi
+}
+
 resolve_docker_compose_cmd() {
   if (( ${#DOCKER_COMPOSE_CMD[@]} > 0 )); then
     return 0
@@ -414,6 +575,25 @@ canton.participants.extra-${index}.ledger-api.auth-services = [
   }
 ]
 
+EOF
+    done
+  fi
+
+  if [[ "$(resolve_tls_enabled)" == "1" ]]; then
+    local index
+    for ((index = 1; index <= count; index++)); do
+      cat >> "$canton_config_file" <<EOF
+canton.participants.extra-${index}.ledger-api.tls {
+  cert-chain-file = "/app/localnet-tls/server.crt"
+  private-key-file = "/app/localnet-tls/server.key"
+  trust-collection-file = "/app/localnet-tls/ca.crt"
+}
+canton.participants.extra-${index}.admin-api.tls {
+  cert-chain-file = "/app/localnet-tls/server.crt"
+  private-key-file = "/app/localnet-tls/server.key"
+  trust-collection-file = "/app/localnet-tls/ca.crt"
+}
+
 EOF
     done
   fi
@@ -795,6 +975,7 @@ grant_localnet_validator_read_rights() {
 
 start_ledger_stack() {
   local auth_mode="${1:-shared-secret}"
+  export AUTH_MODE="$auth_mode"
   local modules_dir="$QUICKSTART_DIR/docker/modules"
   local localnet_dir="$modules_dir/localnet"
   local splice_version
@@ -808,6 +989,7 @@ start_ledger_stack() {
   export SV_PROFILE=on
   export PQS_SV_PROFILE=on
   load_localnet_common_env "$localnet_dir/env/common.env"
+  prepare_tls_runtime_files
   prepare_es256_runtime_files
   local extra_participants
   extra_participants="$(resolve_extra_participants)"
@@ -841,6 +1023,7 @@ start_ledger_stack() {
   fi
 
   append_extra_participant_args "$extra_participants" "$auth_mode" compose_args
+  append_tls_args compose_args
   append_es256_args compose_args
   docker_compose "${compose_args[@]}" down -v --remove-orphans
   mapfile -t startup_services < <(prerequisite_services "$auth_mode")
@@ -873,12 +1056,16 @@ if [[ ! -f .env.local ]]; then
   make setup
 fi
 
-if [[ "$(resolve_es256_enabled)" != "1" ]] && make_target_exists start-local-ledger; then
+if [[ "$(resolve_es256_enabled)" != "1" && "$(resolve_tls_enabled)" != "1" ]] && make_target_exists start-local-ledger; then
   make start-local-ledger
 else
   auth_mode="$(read_env_value AUTH_MODE || true)"
   auth_mode="${auth_mode:-shared-secret}"
-  echo "start-local-ledger target not found. Starting ledger-only compose stack directly."
+  if [[ "$(resolve_es256_enabled)" == "1" || "$(resolve_tls_enabled)" == "1" ]]; then
+    echo "Generated localnet transport overlay enabled. Starting ledger-only compose stack directly."
+  else
+    echo "start-local-ledger target not found. Starting ledger-only compose stack directly."
+  fi
   start_ledger_stack "$auth_mode"
   if [[ "$(resolve_es256_enabled)" == "1" ]]; then
     echo "ES256 bearer token written to $LOCALNET_ES256_TOKEN_PATH"

package/node/stop-local.sh

@@ -92,6 +92,19 @@ es256_runtime_dir() {
   printf '%s\n' "${START_LOCAL_ES256_RUNTIME_DIR:-$REPO_ROOT/.generated/localnet-es256}"
 }
 
+resolve_tls_enabled() {
+  local value="${LOCALNET_TLS:-0}"
+  if [[ "$value" != "0" && "$value" != "1" ]]; then
+    echo "LOCALNET_TLS must be 0 or 1." >&2
+    return 1
+  fi
+  printf '%s\n' "$value"
+}
+
+tls_runtime_dir() {
+  printf '%s\n' "${START_LOCAL_TLS_RUNTIME_DIR:-$REPO_ROOT/.generated/localnet-tls}"
+}
+
 append_es256_args() {
   local -n compose_args_ref="$1"
   if [[ "$(resolve_es256_enabled)" == "1" ]]; then
@@ -102,6 +115,16 @@ append_es256_args() {
   fi
 }
 
+append_tls_args() {
+  local -n compose_args_ref="$1"
+  if [[ "$(resolve_tls_enabled)" == "1" ]]; then
+    local compose_file="$(tls_runtime_dir)/compose-localnet.yaml"
+    if [[ -f "$compose_file" ]]; then
+      compose_args_ref+=( -f "$compose_file" )
+    fi
+  fi
+}
+
 resolve_docker_compose_cmd() {
   if (( ${#DOCKER_COMPOSE_CMD[@]} > 0 )); then
     return 0
@@ -141,6 +164,7 @@ append_existing_extra_participant_args() {
 
 stop_ledger_stack() {
   local auth_mode="${1:-shared-secret}"
+  export AUTH_MODE="$auth_mode"
   local modules_dir="$QUICKSTART_DIR/docker/modules"
   local localnet_dir="$modules_dir/localnet"
   local splice_version
@@ -177,6 +201,7 @@ stop_ledger_stack() {
   fi
 
   append_existing_extra_participant_args compose_args
+  append_tls_args compose_args
   append_es256_args compose_args
   docker_compose "${compose_args[@]}" down -v --remove-orphans
 }
@@ -190,7 +215,7 @@ if [[ ! -f .env.local ]]; then
   exit 0
 fi
 
-if [[ "$(resolve_es256_enabled)" != "1" ]] && make_target_exists stop-local-ledger; then
+if [[ "$(resolve_es256_enabled)" != "1" && "$(resolve_tls_enabled)" != "1" ]] && make_target_exists stop-local-ledger; then
   make stop-local-ledger
 else
   auth_mode="$(read_env_value AUTH_MODE || true)"

package/node/test-start-local.sh

@@ -32,12 +32,17 @@ run_case() {
   local cn_quickstart_dir_override="${6:-}"
   local repo_root_env_contents="${7:-}"
   local es256_enabled="${8:-0}"
+  local tls_enabled="${9:-0}"
+  local tls_cert_chain_path="${10:-}"
+  local tls_private_key_path="${11:-}"
+  local tls_ca_cert_path="${12:-}"
+  local expected_status="${13:-0}"
   local quickstart_dir="$tmpdir/quickstart"
   local quickstart_root_dir="$tmpdir/cn-quickstart"
   local stubbin="$tmpdir/bin"
   local generated_dir="$tmpdir/generated"
 
-  rm -rf "$quickstart_dir" "$quickstart_root_dir" "$stubbin" "$generated_dir"
+  rm -rf "$quickstart_dir" "$quickstart_root_dir" "$stubbin" "$generated_dir" "$tmpdir/tls"
   mkdir -p \
     "$quickstart_root_dir" \
     "$quickstart_dir/docker/modules/localnet/env" \
@@ -84,6 +89,7 @@ printf 'stub env APP_PROVIDER_PROFILE=%s\n' "${APP_PROVIDER_PROFILE:-}"
 printf 'stub env APP_USER_PROFILE=%s\n' "${APP_USER_PROFILE:-}"
 printf 'stub env SV_PROFILE=%s\n' "${SV_PROFILE:-}"
 printf 'stub env PQS_SV_PROFILE=%s\n' "${PQS_SV_PROFILE:-}"
+printf 'stub env AUTH_MODE=%s\n' "${AUTH_MODE:-}"
 if [[ "${1:-}" == "inspect" ]]; then
   printf 'healthy\n'
   exit 0
@@ -145,6 +151,7 @@ EOF
   chmod +x "$stubbin/docker-compose"
 
   local output
+  local status=0
   output="$(
     if [[ -n "$repo_root_env_contents" ]]; then
       printf '%s\n' "$repo_root_env_contents" > "$REPO_ENV_FILE"
@@ -158,20 +165,39 @@ EOF
         TERM="${TERM:-dumb}" \
         START_LOCAL_GENERATED_DIR="$generated_dir" \
         START_LOCAL_ES256_RUNTIME_DIR="$tmpdir/es256" \
+        START_LOCAL_TLS_RUNTIME_DIR="$tmpdir/tls" \
         LOCALNET_ES256_JWT="$es256_enabled" \
+        LOCALNET_TLS="$tls_enabled" \
+        LOCALNET_TLS_CERT_CHAIN_PATH="$tls_cert_chain_path" \
+        LOCALNET_TLS_PRIVATE_KEY_PATH="$tls_private_key_path" \
+        LOCALNET_TLS_CA_CERT_PATH="$tls_ca_cert_path" \
         EXTRA_PARTICIPANTS="$extra_participants" \
         PATH="$stubbin:$PATH" \
-        bash ./start-local.sh
+        bash ./start-local.sh 2>&1
     else
       CN_QUICKSTART_DIR="${cn_quickstart_dir_override:-$quickstart_dir}" \
         START_LOCAL_GENERATED_DIR="$generated_dir" \
         START_LOCAL_ES256_RUNTIME_DIR="$tmpdir/es256" \
+        START_LOCAL_TLS_RUNTIME_DIR="$tmpdir/tls" \
         LOCALNET_ES256_JWT="$es256_enabled" \
+        LOCALNET_TLS="$tls_enabled" \
+        LOCALNET_TLS_CERT_CHAIN_PATH="$tls_cert_chain_path" \
+        LOCALNET_TLS_PRIVATE_KEY_PATH="$tls_private_key_path" \
+        LOCALNET_TLS_CA_CERT_PATH="$tls_ca_cert_path" \
         EXTRA_PARTICIPANTS="$extra_participants" \
         PATH="$stubbin:$PATH" \
-        bash ./start-local.sh
+        bash ./start-local.sh 2>&1
     fi
-  )"
+  )" || status=$?
+
+  if [[ "$expected_status" == "0" && "$status" != "0" ]]; then
+    printf 'expected successful start-local case, got status %s and output:\n%s\n' "$status" "$output" >&2
+    exit 1
+  fi
+  if [[ "$expected_status" != "0" && "$status" == "0" ]]; then
+    printf 'expected failing start-local case, got success and output:\n%s\n' "$output" >&2
+    exit 1
+  fi
 
   if ! grep -Fxq "$expected_output" <<<"$output"; then
     printf 'expected output line %q, got:\n%s\n' "$expected_output" "$output" >&2
@@ -190,6 +216,28 @@ assert_file_contains() {
   fi
 }
 
+assert_file_contains_text() {
+  local path="$1"
+  local expected="$2"
+
+  if ! grep -Fq "$expected" "$path"; then
+    printf 'expected file %s to contain text %q, got:\n' "$path" "$expected" >&2
+    cat "$path" >&2
+    exit 1
+  fi
+}
+
+assert_file_mode() {
+  local path="$1"
+  local expected="$2"
+  local actual
+  actual="$(stat -c '%a' "$path")"
+  if [[ "$actual" != "$expected" ]]; then
+    printf 'expected file %s mode %s, got %s\n' "$path" "$expected" "$actual" >&2
+    exit 1
+  fi
+}
+
 run_repo_root_env_case() {
   local quickstart_dir="$tmpdir/quickstart"
   local quickstart_root_dir="$tmpdir/custom-quickstart-root"
@@ -247,6 +295,7 @@ printf 'stub env APP_PROVIDER_PROFILE=%s\n' "${APP_PROVIDER_PROFILE:-}"
 printf 'stub env APP_USER_PROFILE=%s\n' "${APP_USER_PROFILE:-}"
 printf 'stub env SV_PROFILE=%s\n' "${SV_PROFILE:-}"
 printf 'stub env PQS_SV_PROFILE=%s\n' "${PQS_SV_PROFILE:-}"
+printf 'stub env AUTH_MODE=%s\n' "${AUTH_MODE:-}"
 if [[ "${1:-}" == "inspect" ]]; then
   printf 'healthy\n'
   exit 0
@@ -284,6 +333,7 @@ run_case $'.PHONY: start\nstart:\n' 'stub env IMAGE_TAG=0.6.5'
 run_case $'.PHONY: start\nstart:\n' 'stub env APP_USER_PROFILE=off'
 run_case $'.PHONY: start\nstart:\n' 'stub env SV_PROFILE=on'
 run_case $'.PHONY: start\nstart:\n' 'stub env PQS_SV_PROFILE=on'
+run_case $'.PHONY: start\nstart:\n' 'stub env AUTH_MODE=oauth2' oauth2
 run_case $'.PHONY: start\nstart:\n' 'stub docker compose -f compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/localnet/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/splice-onboarding/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/pqs/compose.yaml --env-file .env --env-file .env.local --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/compose.env --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/env/common.env --env-file '"$tmpdir"'/quickstart/docker/modules/pqs/compose.env --profile app-provider --profile pqs-app-provider --profile pqs-sv down -v --remove-orphans'
 run_case $'.PHONY: start\nstart:\n' 'stub docker compose -f compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/localnet/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/splice-onboarding/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/pqs/compose.yaml --env-file .env --env-file .env.local --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/compose.env --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/env/common.env --env-file '"$tmpdir"'/quickstart/docker/modules/pqs/compose.env --profile app-provider --profile pqs-app-provider --profile pqs-sv up -d --no-recreate postgres canton'
 run_case $'.PHONY: start\nstart:\n' 'stub docker compose -f compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/localnet/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/splice-onboarding/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/pqs/compose.yaml --env-file .env --env-file .env.local --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/compose.env --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/env/common.env --env-file '"$tmpdir"'/quickstart/docker/modules/pqs/compose.env --profile app-provider --profile pqs-app-provider --profile pqs-sv -f '"$tmpdir"'/quickstart/docker/modules/keycloak/compose.yaml --env-file '"$tmpdir"'/quickstart/docker/modules/keycloak/compose.env --profile keycloak down -v --remove-orphans' oauth2
@@ -351,4 +401,58 @@ assert_file_contains "$tmpdir/generated/additional-config.extra-validators.conf"
 assert_file_contains "$tmpdir/generated/additional-config.extra-validators.conf" '  validator-party-hint = "${EXTRA_VALIDATOR_1_PARTY_HINT}"'
 assert_file_contains "$tmpdir/generated/additional-config.extra-validators.conf" '  domains.global.buy-extra-traffic {'
 assert_file_contains "$tmpdir/generated/additional-config.extra-validators.conf" 'canton.sv-apps.sv.expected-validator-onboardings += { secret = "${EXTRA_VALIDATOR_3_ONBOARDING_SECRET}" }'
+run_case $'.PHONY: start-local-ledger\nstart-local-ledger:\n' 'stub docker compose -f compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/localnet/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/splice-onboarding/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/pqs/compose.yaml --env-file .env --env-file .env.local --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/compose.env --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/env/common.env --env-file '"$tmpdir"'/quickstart/docker/modules/pqs/compose.env --profile app-provider --profile pqs-app-provider --profile pqs-sv -f '"$tmpdir"'/tls/compose-localnet.yaml down -v --remove-orphans' shared-secret default 0 '' '' 0 1
+assert_file_contains_text "$tmpdir/tls/canton-tls.conf" 'canton.participants.app-provider.ledger-api.tls {'
+assert_file_contains_text "$tmpdir/tls/canton-tls.conf" 'canton.participants.app-provider.admin-api.tls {'
+assert_file_contains_text "$tmpdir/tls/canton-tls.conf" 'canton.participants.sv.admin-api.tls {'
+if grep -Fq 'canton.participants.app-user.ledger-api.tls {' "$tmpdir/tls/canton-tls.conf" \
+  || grep -Fq 'canton.participants.app-user.admin-api.tls {' "$tmpdir/tls/canton-tls.conf"; then
+  echo "unexpected TLS configuration for inactive app-user participant" >&2
+  exit 1
+fi
+assert_file_contains_text "$tmpdir/tls/compose-localnet.yaml" '/app/localnet-tls/server.key:ro'
+assert_file_contains_text "$tmpdir/tls/compose-localnet.yaml" '/app/localnet-tls/ca.crt:ro'
+assert_file_mode "$tmpdir/tls/server.key" 600
+assert_file_mode "$tmpdir/tls/ca.key" 600
+run_case $'.PHONY: start\nstart:\n' 'stub docker compose -f compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/localnet/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/splice-onboarding/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/pqs/compose.yaml --env-file .env --env-file .env.local --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/compose.env --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/env/common.env --env-file '"$tmpdir"'/quickstart/docker/modules/pqs/compose.env --profile app-provider --profile pqs-app-provider --profile pqs-sv -f '"$tmpdir"'/generated/compose-extra-participants.yaml --env-file '"$tmpdir"'/generated/extra-participants.env -f '"$tmpdir"'/tls/compose-localnet.yaml down -v --remove-orphans' shared-secret default 2 '' '' 0 1
+assert_file_contains_text "$tmpdir/generated/additional-config.extra-participants.conf" 'canton.participants.extra-1.ledger-api.tls {'
+assert_file_contains_text "$tmpdir/generated/additional-config.extra-participants.conf" 'canton.participants.extra-2.admin-api.tls {'
+
+mkdir -p "$tmpdir/supplied"
+openssl genrsa -out "$tmpdir/supplied/ca.key" 2048 >/dev/null 2>&1
+openssl req -x509 -new -sha256 -days 3650 \
+  -key "$tmpdir/supplied/ca.key" \
+  -subj '/CN=supplied-localnet-ca' \
+  -addext 'basicConstraints=critical,CA:TRUE' \
+  -addext 'keyUsage=critical,keyCertSign,cRLSign' \
+  -out "$tmpdir/supplied/ca.crt" >/dev/null 2>&1
+openssl genrsa -out "$tmpdir/supplied/server.key" 2048 >/dev/null 2>&1
+openssl req -new -sha256 -key "$tmpdir/supplied/server.key" \
+  -subj '/CN=localhost' -out "$tmpdir/supplied/server.csr" >/dev/null 2>&1
+printf '%s\n' \
+  '[server_ext]' \
+  'basicConstraints = CA:FALSE' \
+  'keyUsage = digitalSignature, keyEncipherment' \
+  'extendedKeyUsage = serverAuth' \
+  'subjectAltName = DNS:localhost, DNS:canton, IP:127.0.0.1' \
+  > "$tmpdir/supplied/server-extensions.cnf"
+openssl x509 -req -sha256 -days 3650 \
+  -in "$tmpdir/supplied/server.csr" \
+  -CA "$tmpdir/supplied/ca.crt" -CAkey "$tmpdir/supplied/ca.key" -CAcreateserial \
+  -out "$tmpdir/supplied/server.crt" \
+  -extfile "$tmpdir/supplied/server-extensions.cnf" -extensions server_ext >/dev/null 2>&1
+run_case $'.PHONY: start\nstart:\n' 'stub docker compose -f compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/localnet/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/splice-onboarding/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/pqs/compose.yaml --env-file .env --env-file .env.local --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/compose.env --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/env/common.env --env-file '"$tmpdir"'/quickstart/docker/modules/pqs/compose.env --profile app-provider --profile pqs-app-provider --profile pqs-sv -f '"$tmpdir"'/tls/compose-localnet.yaml down -v --remove-orphans' shared-secret default 0 '' '' 0 1 "$tmpdir/supplied/server.crt" "$tmpdir/supplied/server.key" "$tmpdir/supplied/ca.crt"
+if [[ -e "$tmpdir/tls/server.key" || -e "$tmpdir/tls/ca.key" ]]; then
+  echo 'supplied TLS mode unexpectedly generated private material' >&2
+  exit 1
+fi
+assert_file_contains_text "$tmpdir/tls/compose-localnet.yaml" "$tmpdir/supplied/server.key:/app/localnet-tls/server.key:ro"
+openssl genrsa -out "$tmpdir/supplied/mismatch.key" 2048 >/dev/null 2>&1
+run_case $'.PHONY: start\nstart:\n' 'Supplied TLS private key does not match the server certificate.' shared-secret default 0 '' '' 0 1 "$tmpdir/supplied/server.crt" "$tmpdir/supplied/mismatch.key" "$tmpdir/supplied/ca.crt" 1
+run_case $'.PHONY: start\nstart:\n' 'LOCALNET_TLS_CERT_CHAIN_PATH, LOCALNET_TLS_PRIVATE_KEY_PATH, and LOCALNET_TLS_CA_CERT_PATH must be set together.' shared-secret default 0 '' '' 0 1 "$tmpdir/supplied/server.crt" '' '' 1
+run_case $'.PHONY: start\nstart:\n' 'LOCALNET_TLS must be 0 or 1.' shared-secret default 0 '' '' 0 invalid '' '' '' 1
+run_case $'.PHONY: start\nstart:\n' 'ES256 bearer token written to '"$tmpdir"'/es256/ledger-api-user.token' shared-secret default 0 '' '' 1 1
+assert_file_contains_text "$tmpdir/es256/canton-es256.conf" 'include file("/app/localnet-tls.conf")'
+assert_file_contains_text "$tmpdir/es256/compose-es256.yaml" '/app/es256-certificate.pem:ro'
+assert_file_contains_text "$tmpdir/tls/compose-localnet.yaml" '/app/localnet-tls/server.crt:ro'
 run_repo_root_env_case

package/node/test-stop-local.sh

@@ -14,6 +14,7 @@ run_case() {
   local expected_output="$2"
   local auth_mode="${3:-shared-secret}"
   local docker_mode="${4:-compose-v2}"
+  local tls_enabled="${5:-0}"
   local quickstart_dir="$tmpdir/quickstart"
   local stubbin="$tmpdir/bin"
   local generated_dir="$tmpdir/generated-stop"
@@ -26,6 +27,10 @@ run_case() {
     "$quickstart_dir/docker/modules/keycloak" \
     "$stubbin" \
     "$generated_dir"
+  if [[ "$tls_enabled" == "1" ]]; then
+    mkdir -p "$tmpdir/tls"
+    printf 'services:\n' > "$tmpdir/tls/compose-localnet.yaml"
+  fi
 
   printf '%s\n' "$makefile_targets" > "$quickstart_dir/Makefile"
   printf 'DOCKER_NETWORK=quickstart\nSPLICE_VERSION=0.6.5\n' > "$quickstart_dir/.env"
@@ -64,6 +69,7 @@ printf 'stub env APP_PROVIDER_PROFILE=%s\n' "${APP_PROVIDER_PROFILE:-}"
 printf 'stub env APP_USER_PROFILE=%s\n' "${APP_USER_PROFILE:-}"
 printf 'stub env SV_PROFILE=%s\n' "${SV_PROFILE:-}"
 printf 'stub env PQS_SV_PROFILE=%s\n' "${PQS_SV_PROFILE:-}"
+printf 'stub env AUTH_MODE=%s\n' "${AUTH_MODE:-}"
 if [[ "${1:-}" == "compose" && "${2:-}" == "version" ]]; then
   if [[ "$docker_mode" == "compose-v2" ]]; then
     exit 0
@@ -95,6 +101,8 @@ EOF
     cd "$SCRIPT_DIR"
     CN_QUICKSTART_DIR="$quickstart_dir" \
       START_LOCAL_GENERATED_DIR="$generated_dir" \
+      START_LOCAL_TLS_RUNTIME_DIR="$tmpdir/tls" \
+      LOCALNET_TLS="$tls_enabled" \
       PATH="$stubbin:$PATH" \
       bash ./stop-local.sh
   )"
@@ -108,5 +116,6 @@ EOF
 run_case $'.PHONY: stop-local-ledger\nstop-local-ledger:\n' 'stub make stop-local-ledger'
 run_case $'.PHONY: stop\nstop:\n' 'stub docker compose -f compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/localnet/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/splice-onboarding/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/pqs/compose.yaml --env-file .env --env-file .env.local --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/compose.env --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/env/common.env --env-file '"$tmpdir"'/quickstart/docker/modules/pqs/compose.env --profile app-provider --profile pqs-app-provider --profile pqs-sv down -v --remove-orphans'
 run_case $'.PHONY: stop\nstop:\n' 'stub docker compose -f compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/localnet/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/splice-onboarding/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/pqs/compose.yaml --env-file .env --env-file .env.local --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/compose.env --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/env/common.env --env-file '"$tmpdir"'/quickstart/docker/modules/pqs/compose.env --profile app-provider --profile pqs-app-provider --profile pqs-sv -f '"$tmpdir"'/quickstart/docker/modules/keycloak/compose.yaml --env-file '"$tmpdir"'/quickstart/docker/modules/keycloak/compose.env --profile keycloak down -v --remove-orphans' oauth2
+run_case $'.PHONY: stop\nstop:\n' 'stub env AUTH_MODE=oauth2' oauth2
 run_case $'.PHONY: stop\nstop:\n' 'stub docker-compose -f compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/localnet/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/splice-onboarding/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/pqs/compose.yaml --env-file .env --env-file .env.local --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/compose.env --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/env/common.env --env-file '"$tmpdir"'/quickstart/docker/modules/pqs/compose.env --profile app-provider --profile pqs-app-provider --profile pqs-sv down -v --remove-orphans' shared-secret compose-v1
-
+run_case $'.PHONY: stop-local-ledger\nstop-local-ledger:\n' 'stub docker compose -f compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/localnet/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/splice-onboarding/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/pqs/compose.yaml --env-file .env --env-file .env.local --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/compose.env --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/env/common.env --env-file '"$tmpdir"'/quickstart/docker/modules/pqs/compose.env --profile app-provider --profile pqs-app-provider --profile pqs-sv -f '"$tmpdir"'/tls/compose-localnet.yaml down -v --remove-orphans' shared-secret compose-v2 1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@distrohelena/canton-typescript-sdk",
-    "version": "0.1.17",
+    "version": "0.1.19",
     "license": "Apache-2.0",
     "type": "module",
     "main": "./dist/index.js",