npm - @inclavare-containers/tng - Versions diffs - 2.6.0 - Mend

@inclavare-containers/tng 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,354 @@
+# 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. Download from GitHub Packages
+Download the precompiled npm package directly from the GitHub Packages page:
+[https://github.com/inclavare-containers/TNG/pkgs/npm/tng](https://github.com/inclavare-containers/TNG/pkgs/npm/tng)
+### 2. Build from Source
+#### Docker Environment Preparation
+```sh
+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:
+```sh
+yum install -y git make clang protobuf-devel npm
+```
+#### Pull the Source Code
+```sh
+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
+```sh
+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
+```sh
+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
+```bash
+npm install tng-<version>.tgz
+```
+### Integrate the SDK in Your HTML
+Add the following code to your HTML page to use the TNG SDK:
+```html
+<!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:
+1. Add necessary security policy meta tags to the HTML header
+2. Import and initialize the TNG WASM module
+3. Configure the attestation service address and policy ID
+4. 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.
+1. Modify the `background` configuration item in the `manifest.json` file, setting the `type` configuration item to `"module"`.
+```json
+  "background": {
+    "service_worker": "background.js",
+    "type": "module"
+  }
+```
+2. Modify the `content_security_policy` configuration item in the `manifest.json` file to the following content:
+```json
+  "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](https://github.com/svenstaro/dummyhttp), a simple HTTP server program, to simulate our backend service. We need to install and run it.
+Installation
+```sh
+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.
+```sh
+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
+```sh
+make create-tarball
+make rpm-build
+```
+The artifacts will be placed in `~/rpmbuild/RPMS/*/trusted-network-gateway-*.rpm`, which you can install as follows:
+```sh
+yum install ~/rpmbuild/RPMS/*/trusted-network-gateway-*.rpm -y
+```
+If you want to build the container version of TNG:
+```sh
+# 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.
+```sh
+yum install -y attestation-agent
+```
+Run
+```sh
+RUST_LOG=debug attestation-agent --attestation_sock unix:///run/confidential-containers/attestation-agent/attestation-agent.sock
+```
+### 4. Run TNG on the Server Side
+```sh
+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:
+```sh
+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
+```sh
+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](pkg/index.html) as needed:
+URL of the backend service to access:
+```js
+const url = "http://127.0.0.1:30001/foo/bar?baz=qux";
+```
+Attestation Service URL and policy ID for verification:
+```js
+const asAddr = "http://127.0.0.1:8080/";
+const policyIds = ["default"];
+```
+### 8. Run the Frontend Service on the Server Side
+First install miniserve
+```sh
+cargo +nightly-2025-07-07 install miniserve --locked
+```
+Run miniserve
+```sh
+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`](https://github.com/svenstaro/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.

package/package.json ADDED Viewed

@@ -0,0 +1,27 @@
+{
+  "name": "@inclavare-containers/tng",
+  "type": "module",
+  "collaborators": [
+    "Kun Lai <laikun@linux.alibaba.com>"
+  ],
+  "version": "2.6.0",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/inclavare-containers/tng"
+  },
+  "files": [
+    "tng_wasm_bg.wasm",
+    "tng_wasm.js",
+    "tng_wasm.d.ts"
+  ],
+  "main": "tng_wasm.js",
+  "types": "tng_wasm.d.ts",
+  "sideEffects": [
+    "./snippets/*"
+  ],
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com/",
+    "access": "public"
+  }
+}

package/tng_wasm.d.ts ADDED Viewed

@@ -0,0 +1,111 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * The `ReadableStreamType` enum.
+ *
+ * *This API requires the following crate features to be activated: `ReadableStreamType`*
+ */
+type ReadableStreamType = "bytes";
+export class IntoUnderlyingByteSource {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableByteStreamController): Promise<any>;
+    start(controller: ReadableByteStreamController): void;
+    readonly autoAllocateChunkSize: number;
+    readonly type: ReadableStreamType;
+}
+export class IntoUnderlyingSink {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    abort(reason: any): Promise<any>;
+    close(): Promise<any>;
+    write(chunk: any): Promise<any>;
+}
+export class IntoUnderlyingSource {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableStreamDefaultController): Promise<any>;
+}
+declare function fetch2(url: string, init: any, config: any): Promise<Response>;
+export { fetch2 as fetch }
+export function init_tng(): void;
+/**
+ * Entry point invoked by JavaScript in a worker.
+ */
+export function task_worker_entry_point(ptr: number): void;
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+export interface InitOutput {
+    readonly fetch: (a: number, b: number, c: any, d: any) => any;
+    readonly init_tng: () => void;
+    readonly task_worker_entry_point: (a: number) => [number, number];
+    readonly ring_core_0_17_11__bn_mul_mont: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly __wbg_intounderlyingsink_free: (a: number, b: number) => void;
+    readonly intounderlyingsink_write: (a: number, b: any) => any;
+    readonly intounderlyingsink_close: (a: number) => any;
+    readonly intounderlyingsink_abort: (a: number, b: any) => any;
+    readonly __wbg_intounderlyingbytesource_free: (a: number, b: number) => void;
+    readonly intounderlyingbytesource_type: (a: number) => number;
+    readonly intounderlyingbytesource_autoAllocateChunkSize: (a: number) => number;
+    readonly intounderlyingbytesource_start: (a: number, b: any) => void;
+    readonly intounderlyingbytesource_pull: (a: number, b: any) => any;
+    readonly intounderlyingbytesource_cancel: (a: number) => void;
+    readonly __wbg_intounderlyingsource_free: (a: number, b: number) => void;
+    readonly intounderlyingsource_pull: (a: number, b: any) => any;
+    readonly intounderlyingsource_cancel: (a: number) => void;
+    readonly wasm_bindgen__closure__destroy__h608d62b8eccc8f6e: (a: number, b: number) => void;
+    readonly wasm_bindgen__closure__destroy__hbb5960641dfaf99a: (a: number, b: number) => void;
+    readonly wasm_bindgen__closure__destroy__h2925d4d1c19a6d50: (a: number, b: number) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h38253c4a1aa54e27: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h4e91db2f1b7350bd: (a: number, b: number, c: any, d: any) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__hdfdaa0711fe9a60e: (a: number, b: number, c: any) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__hfa390009d5ba6f84: (a: number, b: number, c: any) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h7938576e03ec4167: (a: number, b: number) => void;
+    readonly memory: WebAssembly.Memory;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_thread_destroy: (a?: number, b?: number, c?: number) => void;
+    readonly __wbindgen_start: (a: number) => void;
+}
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput, memory?: WebAssembly.Memory, thread_stack_size?: number }} module - Passing `SyncInitInput` directly is deprecated.
+ * @param {WebAssembly.Memory} memory - Deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput, memory?: WebAssembly.Memory, thread_stack_size?: number } | SyncInitInput, memory?: WebAssembly.Memory): InitOutput;
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput>, memory?: WebAssembly.Memory, thread_stack_size?: number }} module_or_path - Passing `InitInput` directly is deprecated.
+ * @param {WebAssembly.Memory} memory - Deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput>, memory?: WebAssembly.Memory, thread_stack_size?: number } | InitInput | Promise<InitInput>, memory?: WebAssembly.Memory): Promise<InitOutput>;