@inclavare-containers/tng

v2.7.3

Published

9 days ago

The TNG Client JavaScript SDK provides client functionality for use in browser environments, built with wasm-pack.

0High
0Medium
0Low

imlk

TNG Client JavaScript SDK

Description

The TNG Client JavaScript SDK provides client functionality for use in browser environments, built with wasm-pack.

Getting the SDK

You can obtain the TNG SDK in two ways:

1. Install a pre-built package

Install directly from npm:

npm install @inclavare-containers/tng

Alternatively, download from GitHub Packages.

2. Build from Source

Docker Environment Preparation

docker run -it --name tng-dev --privileged --network=host alibaba-cloud-linux-3-registry.cn-hangzhou.cr.aliyuncs.com/alinux3/alinux3:latest bash

The above command will create a container named tng-dev based on the Alibaba Cloud Linux distribution, which will serve as the TNG development environment. We will continue the following steps in this container.

Install dependencies:

yum install -y git make clang protobuf-devel npm

Pull the Source Code

cd /
git clone https://github.com/inclavare-containers/tng.git
cd tng
git submodule update --init

Now you have the tng repository source code in the /tng directory.

Install the Rust Toolchain

cat <<EOF >> ~/.bashrc
export RUSTUP_DIST_SERVER=https://mirrors.ustc.edu.cn/rust-static
export RUSTUP_UPDATE_ROOT=https://mirrors.ustc.edu.cn/rust-static/rustup
EOF

. ~/.bashrc

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

mkdir -p ~/.cargo/
cat <<EOF > ~/.cargo/config.toml
[source.crates-io]
replace-with = 'ustc'

[source.ustc]
registry = "git://mirrors.ustc.edu.cn/crates.io-index"
EOF

. "$HOME/.cargo/env"

Build the TNG SDK npm Package

make wasm-pack-debug

[!NOTE] If you want to build the final production version, please use make wasm-pack-release

The resulting tar.gz file will be placed in the ./tng-wasm/pkg/ directory, which you can install into your web project using npm install.

Using the SDK in Your Project

Install the SDK to Your Project

npm install @inclavare-containers/tng

Integrate the SDK in Your HTML

Add the following code to your HTML page to use the TNG SDK:

<!DOCTYPE html>
<html>
  <head> </head>
  <body>
    <!-- Your page content -->

    <script type="module">
      import tng_init, { fetch as tng_fetch } from "tng_wasm.js";

      // Initialize the TNG WASM module
      await tng_init();

      // Configure attestation parameters
      const asAddr = "http://127.0.0.1:8080/";
      const policyIds = ["default"];

      // Create a wrapped fetch function
      const attested_fetch = (input, init) => {
        const tng_config = {
          ohttp: {},
          verify: {
            model: "background_check",
            as_type: "restful",
            as_addr: asAddr,
            policy_ids: policyIds,
          },
        };
        return tng_fetch(input, init, tng_config);
      };

      // Send a request using the wrapped fetch function
      attested_fetch("http://127.0.0.1:30001/foo/bar?baz=qux", {
        method: "GET",
        headers: {},
      })
        .then((response) => {
          const attest_info = response?.attest_info
            ? response.attest_info
            : null;
          console.log("Attest Info:", attest_info);
          // Access remote attestation report information

          console.log("Got response:", response);
          // Process response
        })
        .catch((error) => {
          console.error("Error:", error);
          // Handle errors
        });
    </script>
  </body>
</html>

The main steps include:

Add necessary security policy meta tags to the HTML header
Import and initialize the TNG WASM module
Configure the attestation service address and policy ID
Use the wrapped tng_fetch function to send encrypted requests

Deployment Configuration

Using in Web Pages

Since the TNG SDK uses Web Workers, in production deployment, you need to add the Cross-Origin-Opener-Policy:same-origin and Cross-Origin-Embedder-Policy:require-corp HTTP headers to the web page's HTTP response, otherwise it will not work properly.

[!NOTE] Since the .wasm file generated by the build is usually quite large, we recommend enabling gzip compression during deployment to reduce transfer size, which can reduce the volume by approximately 50%.

Using in Chrome Extensions

If you want to integrate in a Chrome extension, due to manifest v3 restrictions, you need to add some additional content to the manifest.

Modify the background configuration item in the manifest.json file, setting the type configuration item to "module".

  "background": {
    "service_worker": "background.js",
    "type": "module"
  }

Modify the content_security_policy configuration item in the manifest.json file to the following content:

  "content_security_policy": {
    "extension_pages": "script-src 'self' 'wasm-unsafe-eval'; object-src 'self';"
  }

Running the Example Code

The pkg directory contains an example program that uses the TNG SDK to send encrypted requests. The example requires a confidential computing server instance and a local computer. The following describes how to run the example.

1. Prepare the Server-side Service

Use dummyhttp, a simple HTTP server program, to simulate our backend service. We need to install and run it.

Installation

cargo install dummyhttp --locked

Run this HTTP server and make it listen on port 30001. Now we have a backend HTTP service listening on port 30001.

dummyhttp -p 30001 -vvvv

[!NOTE] You can use the curl command on the local computer to test direct access to this HTTP server to check network connectivity.

2. Compile and Install TNG on the Server Side

Build the RPM package

make create-tarball
make rpm-build

The artifacts will be placed in ~/rpmbuild/RPMS/*/trusted-network-gateway-*.rpm, which you can install as follows:

yum install ~/rpmbuild/RPMS/*/trusted-network-gateway-*.rpm -y

If you want to build the container version of TNG:

# First install podman
yum install podman podman-docker -y
# Build the container image
docker build -t tng:test .

This will produce a container image named tng:test.

3. Run Attestation-Agent on the Server Side

You can choose to install attestation-agent from the yum repository or compile and deploy your own attestation-agent.

yum install -y attestation-agent

Run

RUST_LOG=debug attestation-agent --attestation_sock unix:///run/confidential-containers/attestation-agent/attestation-agent.sock

4. Run TNG on the Server Side

tng launch --config-content='
    {
        "add_egress": [
            {
                "netfilter": {
                    "capture_dst": {
                        "port": 30001
                    },
                    "capture_local_traffic": true
                },
                "ohttp": {},
                "attest": {
                    "aa_addr": "unix:///run/confidential-containers/attestation-agent/attestation-agent.sock"
                }
            }
        ]
    }'

[!NOTE]
Currently, the TNG SDK only supports server-side verification, so you must provide the "attest" option
As shown above, you need to add an "ohttp": {} entry in the TNG configuration to enable using OHTTP as the encryption protocol (instead of rats-tls) for bidirectional encrypted traffic transmission.

5. Run the Attestation Service Instance

You need to prepare an Attestation Service instance that exposes a RESTful HTTP interface. This can be achieved by installing the trustee package from the yum repository or compiling and deploying your own restful-as.

A reference run command is as follows:

cat <<EOF > /tmp/config_with_cert.json
{
    "work_dir": "/var/lib/attestation-service/",
    "rvps_config": {
        "type": "BuiltIn",
        "storage": {
            "type": "LocalFs"
        }
    },
    "attestation_token_broker": {
        "type": "Simple",
        "duration_min": 5
    }
}
EOF

RUST_LOG=debug restful-as --socket 0.0.0.0:9080 --config-file /tmp/config_with_cert.json

# Since restful-as natively does not support CORS configuration, here we run a CORS proxy service (https://github.com/bulletmark/corsproxy) that forwards requests from port 8080 to the real Attestation Service.
podman run -it --rm --net=host docker.io/bulletmark/corsproxy:latest 8080=http://127.0.0.1:9080

The above will expose an Attestation Service on port 8080.

[!NOTE] Since the TNG SDK needs to initiate requests to the Attestation Service instance in the browser, please ensure you handle the CORS rules properly.

Here is an example:

6. Compile the TNG SDK

make wasm-build-debug

This will produce the corresponding .wasm and .js files in the tng-wasm/pkg/ directory.

7. Modify the Frontend Page Code

Please modify the following content in index.html as needed:

URL of the backend service to access:

const url = "http://127.0.0.1:30001/foo/bar?baz=qux";

Attestation Service URL and policy ID for verification:

const asAddr = "http://127.0.0.1:8080/";
const policyIds = ["default"];

8. Run the Frontend Service on the Server Side

First install miniserve

cargo +nightly-2025-07-07 install miniserve --locked

Run miniserve

miniserve ./tng-wasm/pkg --index index.html --header "Cross-Origin-Opener-Policy:same-origin" --header "Cross-Origin-Embedder-Policy:require-corp" --port 8082

[!NOTE]
miniserve is a pure static resource server. It's no different from Nginx or Python's http.server, and you can use other components as alternatives.

9. Access in the Browser

Open a browser on the local computer and visit http://<confidential computing service instance ip>:8082/. You can view the request response logs in F12.