From af16ad67afdcf0652e66646c5d2115f54ab8b87d Mon Sep 17 00:00:00 2001 From: Coffee Date: Tue, 22 Sep 2026 11:51:58 +0800 Subject: [PATCH 01/10] docs: add inference SDK guides --- cloud/inference-sdk/cloud-gateway.mdx | 86 +++++++++++++++++++++++++++ cloud/inference-sdk/direct.mdx | 86 +++++++++++++++++++++++++++ cloud/inference-sdk/index.mdx | 15 +++++ docs.json | 24 ++++++++ 4 files changed, 211 insertions(+) create mode 100644 cloud/inference-sdk/cloud-gateway.mdx create mode 100644 cloud/inference-sdk/direct.mdx create mode 100644 cloud/inference-sdk/index.mdx diff --git a/cloud/inference-sdk/cloud-gateway.mdx b/cloud/inference-sdk/cloud-gateway.mdx new file mode 100644 index 0000000..5156f17 --- /dev/null +++ b/cloud/inference-sdk/cloud-gateway.mdx @@ -0,0 +1,86 @@ +--- +title: "NEAR AI Cloud Gateway" +description: "Send a verified, end-to-end encrypted Chat Completion through the NEAR AI Cloud Gateway." +--- + +Use `InferenceClient` when your application sends requests through the NEAR AI Cloud Gateway. + +## Install + +The package requires Node.js 24 or later. + +```bash +npm install @nearai/inference-sdk@next +``` + +## Send and verify an E2EE Chat Completion + +Set `baseUrl` to the NEAR AI Cloud Gateway endpoint your application uses. E2EE is enabled by default; it is set explicitly below. + +```ts +import { InferenceClient } from '@nearai/inference-sdk/node'; + +const baseUrl = 'https://cloud-api.near.ai/v1'; +const model = 'z-ai/glm-5.3-flash'; +const apiKey = process.env.NEARAI_API_KEY; +if (!apiKey) throw new Error('NEARAI_API_KEY is required'); + +const client = new InferenceClient({ + baseUrl, + apiKey, + e2ee: true, +}); + +const completion = await client.chat.completions.create({ + model, + messages: [{ role: 'user', content: 'Reply with the word ok.' }], +}); + +console.log(completion.choices[0]?.message.content); + +const receipt = await client.verifyResponse(completion.id); +console.log(`Verified ${receipt.signatureKind} response.`); +``` + +Before sending the completion, the SDK verifies the Gateway and every returned NEAR model-attestation candidate. It encrypts supported Chat fields to a key from the verified model evidence and decrypts the response automatically. `verifyResponse()` verifies the response signature using the request and response bytes captured by the client. + + + `verifyResponse()` is explicit. For a streaming completion, consume the entire stream first, then call it with the completion ID so the SDK can verify the exact response bytes. + + +## Add OHTTP + +Set `ohttp: true` to encapsulate Chat requests and responses with OHTTP. OHTTP requires Ed25519, so set `signingAlgo` explicitly. + +```ts +const client = new InferenceClient({ + baseUrl, + apiKey, + signingAlgo: 'ed25519', + e2ee: true, + ohttp: true, +}); +``` + +The Chat and `verifyResponse()` calls stay the same. The SDK verifies the Gateway's signed OHTTP configuration before sending Chat; a missing or invalid configuration blocks the request. OHTTP encapsulates the exchange to the Gateway, while E2EE encrypts supported Chat fields to the verified model key. + + + OHTTP applies only to Chat. Attestation and signature requests remain regular HTTPS. The configured endpoint or proxy must expose `/ohttp` at the same origin. Authorization and custom headers sent on the outer request, along with the client's network address, are not hidden by OHTTP. + + +## Node, browser, and proxy integrations + +The example uses `@nearai/inference-sdk/node`. In Node, the SDK verifies the Gateway TLS peer and pins later requests to the verified Gateway identity. + +For a browser or an application proxy, import from `@nearai/inference-sdk`. Browser Fetch cannot read the TLS peer certificate, so this entry point does not perform Gateway TLS binding. Configure the same explicit `baseUrl` for the endpoint your application uses. + +## Next steps + + + + Understand the attestation and response-signature checks behind this flow. + + + Learn the protocol when you need to manage encryption yourself. + + diff --git a/cloud/inference-sdk/direct.mdx b/cloud/inference-sdk/direct.mdx new file mode 100644 index 0000000..2ede09d --- /dev/null +++ b/cloud/inference-sdk/direct.mdx @@ -0,0 +1,86 @@ +--- +title: "Direct Model Endpoints" +description: "Send a verified, end-to-end encrypted Chat Completion directly to a model endpoint." +--- + +Use `DirectInferenceClient` when your application sends requests directly to a model endpoint. + +## Install + +The package requires Node.js 24 or later. + +```bash +npm install @nearai/inference-sdk@next +``` + +## Send and verify an E2EE Chat Completion + +Set `baseUrl` to the direct model endpoint, including `/v1`. E2EE is enabled by default; it is set explicitly below. + +```ts +import { DirectInferenceClient } from '@nearai/inference-sdk/node'; + +const baseUrl = 'https://glm-5-3-flash.completions.near.ai/v1'; +const model = 'z-ai/glm-5.3-flash'; +const apiKey = process.env.NEARAI_API_KEY; +if (!apiKey) throw new Error('NEARAI_API_KEY is required'); + +const client = new DirectInferenceClient({ + baseUrl, + apiKey, + e2ee: true, +}); + +const completion = await client.chat.completions.create({ + model, + messages: [{ role: 'user', content: 'Reply with the word ok.' }], +}); + +console.log(completion.choices[0]?.message.content); + +const receipt = await client.verifyResponse(completion.id); +console.log(`Verified ${receipt.signatureKind} response.`); +``` + +Before sending the completion, the SDK verifies the complete model-attestation set reported by that endpoint. It does not request Gateway evidence. It encrypts supported Chat fields to a key from the verified model evidence and decrypts the response automatically. A direct endpoint can require credentials different from your NEAR AI Cloud API key. + + + `verifyResponse()` is explicit. For a streaming completion, consume the entire stream first, then call it with the completion ID so the SDK can verify the exact response bytes. + + +## Add OHTTP + +Set `ohttp: true` to encapsulate Chat requests and responses with OHTTP. OHTTP requires Ed25519, so set `signingAlgo` explicitly. + +```ts +const client = new DirectInferenceClient({ + baseUrl, + apiKey, + signingAlgo: 'ed25519', + e2ee: true, + ohttp: true, +}); +``` + +The Chat and `verifyResponse()` calls stay the same. The SDK verifies the direct endpoint's signed OHTTP configuration before sending Chat; a missing or invalid configuration blocks the request. For a direct endpoint, both OHTTP and E2EE are scoped to the model service. + + + OHTTP applies only to Chat. Attestation and signature requests remain regular HTTPS. The configured endpoint or proxy must expose `/ohttp` at the same origin. Authorization and custom headers sent on the outer request, along with the client's network address, are not hidden by OHTTP. + + +## Node, browser, and proxy integrations + +The example uses `@nearai/inference-sdk/node`. Direct endpoint TLS binding is not currently enabled; normal HTTPS certificate validation still applies. + +For a browser or an application proxy, import from `@nearai/inference-sdk`. Configure the same explicit `baseUrl` for the endpoint your application uses. + +## Next steps + + + + Understand the attestation and response-signature checks behind this flow. + + + Learn the protocol when you need to manage encryption yourself. + + diff --git a/cloud/inference-sdk/index.mdx b/cloud/inference-sdk/index.mdx new file mode 100644 index 0000000..92247ac --- /dev/null +++ b/cloud/inference-sdk/index.mdx @@ -0,0 +1,15 @@ +--- +title: "NEAR AI Inference SDK" +description: "Use the TypeScript SDK for verified, end-to-end encrypted Chat Completions." +--- + +The SDK sends Chat Completions through either the NEAR AI Cloud Gateway or a direct model endpoint. Choose the guide that matches the endpoint your application calls. + + + + Send a verified Chat Completion through `cloud-api.near.ai`. + + + Send a verified Chat Completion directly to a model endpoint. + + diff --git a/docs.json b/docs.json index adeb0d7..e862f00 100644 --- a/docs.json +++ b/docs.json @@ -87,6 +87,14 @@ ] } ] + }, + { + "group": "NEAR AI Inference SDK", + "root": "cloud/inference-sdk/index", + "pages": [ + "cloud/inference-sdk/cloud-gateway", + "cloud/inference-sdk/direct" + ] } ] }, @@ -489,6 +497,22 @@ { "source": "/cloud/verification/provenance", "destination": "/cloud/verification" + }, + { + "source": "/cloud/verification/reference/sdk", + "destination": "/cloud/inference-sdk/cloud-gateway" + }, + { + "source": "/cloud/verification/sdk", + "destination": "/cloud/inference-sdk" + }, + { + "source": "/cloud/verification/sdk/cloud-api", + "destination": "/cloud/inference-sdk/cloud-gateway" + }, + { + "source": "/cloud/verification/sdk/direct", + "destination": "/cloud/inference-sdk/direct" } ] } From 3b4b1f9d969b112a10268896cf481af601d67767 Mon Sep 17 00:00:00 2001 From: Coffee Date: Tue, 22 Sep 2026 12:01:11 +0800 Subject: [PATCH 02/10] docs: add SDK navigation icon --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index e862f00..e19f0aa 100644 --- a/docs.json +++ b/docs.json @@ -90,6 +90,7 @@ }, { "group": "NEAR AI Inference SDK", + "icon": "braces", "root": "cloud/inference-sdk/index", "pages": [ "cloud/inference-sdk/cloud-gateway", From 57707d8bea26561a313ad1b239bbd22ba6337627 Mon Sep 17 00:00:00 2001 From: Coffee Date: Tue, 22 Sep 2026 14:43:59 +0800 Subject: [PATCH 03/10] docs: remove redundant SDK setup copy --- cloud/inference-sdk/cloud-gateway.mdx | 2 -- cloud/inference-sdk/direct.mdx | 2 -- 2 files changed, 4 deletions(-) diff --git a/cloud/inference-sdk/cloud-gateway.mdx b/cloud/inference-sdk/cloud-gateway.mdx index 5156f17..f1047d2 100644 --- a/cloud/inference-sdk/cloud-gateway.mdx +++ b/cloud/inference-sdk/cloud-gateway.mdx @@ -15,8 +15,6 @@ npm install @nearai/inference-sdk@next ## Send and verify an E2EE Chat Completion -Set `baseUrl` to the NEAR AI Cloud Gateway endpoint your application uses. E2EE is enabled by default; it is set explicitly below. - ```ts import { InferenceClient } from '@nearai/inference-sdk/node'; diff --git a/cloud/inference-sdk/direct.mdx b/cloud/inference-sdk/direct.mdx index 2ede09d..387fccd 100644 --- a/cloud/inference-sdk/direct.mdx +++ b/cloud/inference-sdk/direct.mdx @@ -15,8 +15,6 @@ npm install @nearai/inference-sdk@next ## Send and verify an E2EE Chat Completion -Set `baseUrl` to the direct model endpoint, including `/v1`. E2EE is enabled by default; it is set explicitly below. - ```ts import { DirectInferenceClient } from '@nearai/inference-sdk/node'; From bfdfcc4d5d527587d383fe4008ca6d06000c36bd Mon Sep 17 00:00:00 2001 From: Coffee Date: Wed, 23 Sep 2026 13:31:40 +0800 Subject: [PATCH 04/10] docs: mark direct SDK flow experimental --- cloud/inference-sdk/direct.mdx | 14 ++++++++++---- cloud/inference-sdk/index.mdx | 7 ++----- docs.json | 3 +-- 3 files changed, 13 insertions(+), 11 deletions(-) diff --git a/cloud/inference-sdk/direct.mdx b/cloud/inference-sdk/direct.mdx index 387fccd..991a3f3 100644 --- a/cloud/inference-sdk/direct.mdx +++ b/cloud/inference-sdk/direct.mdx @@ -1,9 +1,15 @@ --- -title: "Direct Model Endpoints" -description: "Send a verified, end-to-end encrypted Chat Completion directly to a model endpoint." +title: "Experimental Direct Model Endpoints" +description: "Experimental SDK notes for direct model endpoints." --- -Use `DirectInferenceClient` when your application sends requests directly to a model endpoint. + + Direct model endpoints are experimental and are not recommended for new integrations or production verification workflows. Use the NEAR AI Cloud Gateway instead. + + +Independent requests to the same direct hostname can reach different serving instances. An attestation report does not establish deployment evidence for a later completion, and a later signature lookup can return `404`. Do not use direct response signatures as a production verification gate. + +Use `DirectInferenceClient` only when maintaining an existing direct integration. ## Install @@ -40,7 +46,7 @@ const receipt = await client.verifyResponse(completion.id); console.log(`Verified ${receipt.signatureKind} response.`); ``` -Before sending the completion, the SDK verifies the complete model-attestation set reported by that endpoint. It does not request Gateway evidence. It encrypts supported Chat fields to a key from the verified model evidence and decrypts the response automatically. A direct endpoint can require credentials different from your NEAR AI Cloud API key. +Before sending the completion, the SDK verifies each model-attestation report returned by that endpoint. It does not request Gateway evidence. It encrypts supported Chat fields to a key from the verified model evidence and decrypts the response automatically. A direct endpoint can require credentials different from your NEAR AI Cloud API key. `verifyResponse()` is explicit. For a streaming completion, consume the entire stream first, then call it with the completion ID so the SDK can verify the exact response bytes. diff --git a/cloud/inference-sdk/index.mdx b/cloud/inference-sdk/index.mdx index 92247ac..8cc3b15 100644 --- a/cloud/inference-sdk/index.mdx +++ b/cloud/inference-sdk/index.mdx @@ -3,13 +3,10 @@ title: "NEAR AI Inference SDK" description: "Use the TypeScript SDK for verified, end-to-end encrypted Chat Completions." --- -The SDK sends Chat Completions through either the NEAR AI Cloud Gateway or a direct model endpoint. Choose the guide that matches the endpoint your application calls. +Use the SDK with the NEAR AI Cloud Gateway for verified, end-to-end encrypted Chat Completions. - + Send a verified Chat Completion through `cloud-api.near.ai`. - - Send a verified Chat Completion directly to a model endpoint. - diff --git a/docs.json b/docs.json index e19f0aa..d525f23 100644 --- a/docs.json +++ b/docs.json @@ -93,8 +93,7 @@ "icon": "braces", "root": "cloud/inference-sdk/index", "pages": [ - "cloud/inference-sdk/cloud-gateway", - "cloud/inference-sdk/direct" + "cloud/inference-sdk/cloud-gateway" ] } ] From e4022b1f876fcc181247c03dd06b8fdc68e1f810 Mon Sep 17 00:00:00 2001 From: Coffee Date: Wed, 23 Sep 2026 20:23:19 +0800 Subject: [PATCH 05/10] docs: address SDK review feedback --- cloud/inference-sdk/cloud-gateway.mdx | 16 ++++++++++++++++ cloud/inference-sdk/direct.mdx | 2 +- docs.json | 3 ++- 3 files changed, 19 insertions(+), 2 deletions(-) diff --git a/cloud/inference-sdk/cloud-gateway.mdx b/cloud/inference-sdk/cloud-gateway.mdx index f1047d2..d242ed7 100644 --- a/cloud/inference-sdk/cloud-gateway.mdx +++ b/cloud/inference-sdk/cloud-gateway.mdx @@ -42,6 +42,22 @@ console.log(`Verified ${receipt.signatureKind} response.`); Before sending the completion, the SDK verifies the Gateway and every returned NEAR model-attestation candidate. It encrypts supported Chat fields to a key from the verified model evidence and decrypts the response automatically. `verifyResponse()` verifies the response signature using the request and response bytes captured by the client. +By default, the SDK accepts the Intel TCB statuses `UpToDate` and `OutOfDate`. To require `UpToDate`, apply a policy to both the Gateway and model evidence: + +```ts +const strict = { + policy: { acceptedTcbStatuses: ['UpToDate'] as const }, +}; + +const client = new InferenceClient({ + baseUrl, + apiKey, + e2ee: true, + gatewayVerification: strict, + modelVerification: strict, +}); +``` + `verifyResponse()` is explicit. For a streaming completion, consume the entire stream first, then call it with the completion ID so the SDK can verify the exact response bytes. diff --git a/cloud/inference-sdk/direct.mdx b/cloud/inference-sdk/direct.mdx index 991a3f3..452c78f 100644 --- a/cloud/inference-sdk/direct.mdx +++ b/cloud/inference-sdk/direct.mdx @@ -46,7 +46,7 @@ const receipt = await client.verifyResponse(completion.id); console.log(`Verified ${receipt.signatureKind} response.`); ``` -Before sending the completion, the SDK verifies each model-attestation report returned by that endpoint. It does not request Gateway evidence. It encrypts supported Chat fields to a key from the verified model evidence and decrypts the response automatically. A direct endpoint can require credentials different from your NEAR AI Cloud API key. +Before sending the completion, the SDK verifies each model-attestation report returned by that endpoint. It does not request Gateway evidence. It encrypts supported Chat fields to a key from the verified model evidence and decrypts the response automatically. `verifyResponse()` is explicit. For a streaming completion, consume the entire stream first, then call it with the completion ID so the SDK can verify the exact response bytes. diff --git a/docs.json b/docs.json index d525f23..6189efa 100644 --- a/docs.json +++ b/docs.json @@ -142,7 +142,8 @@ { "group": "Experimental", "pages": [ - "cloud/experimental/direct-completions" + "cloud/experimental/direct-completions", + "cloud/inference-sdk/direct" ] } ] From 1bcec6075950a15378489e02c921fa2842dde71d Mon Sep 17 00:00:00 2001 From: Coffee Date: Thu, 24 Sep 2026 20:11:48 +0800 Subject: [PATCH 06/10] docs: organize SDK guides by capability --- cloud/inference-sdk/cloud-gateway.mdx | 100 -------------------------- cloud/inference-sdk/direct.mdx | 3 +- cloud/inference-sdk/e2ee.mdx | 39 ++++++++++ cloud/inference-sdk/index.mdx | 24 +++++-- cloud/inference-sdk/ohttp.mdx | 32 +++++++++ cloud/inference-sdk/verification.mdx | 39 ++++++++++ docs.json | 14 ++-- 7 files changed, 140 insertions(+), 111 deletions(-) delete mode 100644 cloud/inference-sdk/cloud-gateway.mdx create mode 100644 cloud/inference-sdk/e2ee.mdx create mode 100644 cloud/inference-sdk/ohttp.mdx create mode 100644 cloud/inference-sdk/verification.mdx diff --git a/cloud/inference-sdk/cloud-gateway.mdx b/cloud/inference-sdk/cloud-gateway.mdx deleted file mode 100644 index d242ed7..0000000 --- a/cloud/inference-sdk/cloud-gateway.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: "NEAR AI Cloud Gateway" -description: "Send a verified, end-to-end encrypted Chat Completion through the NEAR AI Cloud Gateway." ---- - -Use `InferenceClient` when your application sends requests through the NEAR AI Cloud Gateway. - -## Install - -The package requires Node.js 24 or later. - -```bash -npm install @nearai/inference-sdk@next -``` - -## Send and verify an E2EE Chat Completion - -```ts -import { InferenceClient } from '@nearai/inference-sdk/node'; - -const baseUrl = 'https://cloud-api.near.ai/v1'; -const model = 'z-ai/glm-5.3-flash'; -const apiKey = process.env.NEARAI_API_KEY; -if (!apiKey) throw new Error('NEARAI_API_KEY is required'); - -const client = new InferenceClient({ - baseUrl, - apiKey, - e2ee: true, -}); - -const completion = await client.chat.completions.create({ - model, - messages: [{ role: 'user', content: 'Reply with the word ok.' }], -}); - -console.log(completion.choices[0]?.message.content); - -const receipt = await client.verifyResponse(completion.id); -console.log(`Verified ${receipt.signatureKind} response.`); -``` - -Before sending the completion, the SDK verifies the Gateway and every returned NEAR model-attestation candidate. It encrypts supported Chat fields to a key from the verified model evidence and decrypts the response automatically. `verifyResponse()` verifies the response signature using the request and response bytes captured by the client. - -By default, the SDK accepts the Intel TCB statuses `UpToDate` and `OutOfDate`. To require `UpToDate`, apply a policy to both the Gateway and model evidence: - -```ts -const strict = { - policy: { acceptedTcbStatuses: ['UpToDate'] as const }, -}; - -const client = new InferenceClient({ - baseUrl, - apiKey, - e2ee: true, - gatewayVerification: strict, - modelVerification: strict, -}); -``` - - - `verifyResponse()` is explicit. For a streaming completion, consume the entire stream first, then call it with the completion ID so the SDK can verify the exact response bytes. - - -## Add OHTTP - -Set `ohttp: true` to encapsulate Chat requests and responses with OHTTP. OHTTP requires Ed25519, so set `signingAlgo` explicitly. - -```ts -const client = new InferenceClient({ - baseUrl, - apiKey, - signingAlgo: 'ed25519', - e2ee: true, - ohttp: true, -}); -``` - -The Chat and `verifyResponse()` calls stay the same. The SDK verifies the Gateway's signed OHTTP configuration before sending Chat; a missing or invalid configuration blocks the request. OHTTP encapsulates the exchange to the Gateway, while E2EE encrypts supported Chat fields to the verified model key. - - - OHTTP applies only to Chat. Attestation and signature requests remain regular HTTPS. The configured endpoint or proxy must expose `/ohttp` at the same origin. Authorization and custom headers sent on the outer request, along with the client's network address, are not hidden by OHTTP. - - -## Node, browser, and proxy integrations - -The example uses `@nearai/inference-sdk/node`. In Node, the SDK verifies the Gateway TLS peer and pins later requests to the verified Gateway identity. - -For a browser or an application proxy, import from `@nearai/inference-sdk`. Browser Fetch cannot read the TLS peer certificate, so this entry point does not perform Gateway TLS binding. Configure the same explicit `baseUrl` for the endpoint your application uses. - -## Next steps - - - - Understand the attestation and response-signature checks behind this flow. - - - Learn the protocol when you need to manage encryption yourself. - - diff --git a/cloud/inference-sdk/direct.mdx b/cloud/inference-sdk/direct.mdx index 452c78f..b706061 100644 --- a/cloud/inference-sdk/direct.mdx +++ b/cloud/inference-sdk/direct.mdx @@ -54,13 +54,12 @@ Before sending the completion, the SDK verifies each model-attestation report re ## Add OHTTP -Set `ohttp: true` to encapsulate Chat requests and responses with OHTTP. OHTTP requires Ed25519, so set `signingAlgo` explicitly. +Set `ohttp: true` to encapsulate Chat requests and responses with OHTTP. OHTTP uses the SDK's default Ed25519 signing algorithm; it is not compatible with `signingAlgo: 'ecdsa'`. ```ts const client = new DirectInferenceClient({ baseUrl, apiKey, - signingAlgo: 'ed25519', e2ee: true, ohttp: true, }); diff --git a/cloud/inference-sdk/e2ee.mdx b/cloud/inference-sdk/e2ee.mdx new file mode 100644 index 0000000..a10a5e3 --- /dev/null +++ b/cloud/inference-sdk/e2ee.mdx @@ -0,0 +1,39 @@ +--- +title: "E2EE" +description: "Send an end-to-end encrypted Chat Completion with the SDK." +--- + +E2EE is enabled by default. The SDK verifies the required attestation evidence, encrypts supported Chat fields to a key from the verified model evidence, and decrypts the response automatically. + +```ts +import { InferenceClient } from '@nearai/inference-sdk/node'; + +const baseUrl = 'https://cloud-api.near.ai/v1'; +const model = 'z-ai/glm-5.3-flash'; +const apiKey = process.env.NEARAI_API_KEY; +if (!apiKey) throw new Error('NEARAI_API_KEY is required'); + +const client = new InferenceClient({ + baseUrl, + apiKey, + e2ee: true, +}); + +const completion = await client.chat.completions.create({ + model, + messages: [{ role: 'user', content: 'Reply with the word ok.' }], +}); + +console.log(completion.choices[0]?.message.content); +``` + +## Next steps + + + + Verify the completion and tune attestation policy. + + + Add OHTTP to Chat requests and responses. + + diff --git a/cloud/inference-sdk/index.mdx b/cloud/inference-sdk/index.mdx index 8cc3b15..20e93dc 100644 --- a/cloud/inference-sdk/index.mdx +++ b/cloud/inference-sdk/index.mdx @@ -1,12 +1,26 @@ --- -title: "NEAR AI Inference SDK" +title: "SDK" description: "Use the TypeScript SDK for verified, end-to-end encrypted Chat Completions." --- -Use the SDK with the NEAR AI Cloud Gateway for verified, end-to-end encrypted Chat Completions. +Use the TypeScript SDK with the NEAR AI Cloud Gateway for verified, end-to-end encrypted Chat Completions. - - - Send a verified Chat Completion through `cloud-api.near.ai`. +## Install + +The package requires Node.js 24 or later. + +```bash +npm install @nearai/inference-sdk@next +``` + + + + Send encrypted Chat Completions. + + + Verify attestation and response signatures. + + + Encapsulate Chat traffic with OHTTP. diff --git a/cloud/inference-sdk/ohttp.mdx b/cloud/inference-sdk/ohttp.mdx new file mode 100644 index 0000000..bd09b06 --- /dev/null +++ b/cloud/inference-sdk/ohttp.mdx @@ -0,0 +1,32 @@ +--- +title: "OHTTP" +description: "Encapsulate SDK Chat traffic with OHTTP." +--- + +Set `ohttp: true` to encapsulate Chat requests and responses with OHTTP. OHTTP uses the SDK's default Ed25519 signing algorithm; it is not compatible with `signingAlgo: 'ecdsa'`. + +```ts +const client = new InferenceClient({ + baseUrl, + apiKey, + e2ee: true, + ohttp: true, +}); +``` + +The Chat and `verifyResponse()` calls stay the same. Before sending Chat, the SDK verifies the Gateway's signed OHTTP configuration; a missing or invalid configuration blocks the request. OHTTP encapsulates the exchange to the Gateway, while E2EE encrypts supported Chat fields to the verified model key. + + + OHTTP applies only to Chat. Attestation and signature requests remain regular HTTPS. The configured endpoint or proxy must expose `/ohttp` at the same origin. Authorization and custom headers sent on the outer request, along with the client's network address, are not hidden by OHTTP. + + +## Next steps + + + + Send encrypted Chat Completions. + + + Verify evidence and response signatures. + + diff --git a/cloud/inference-sdk/verification.mdx b/cloud/inference-sdk/verification.mdx new file mode 100644 index 0000000..e9c3a42 --- /dev/null +++ b/cloud/inference-sdk/verification.mdx @@ -0,0 +1,39 @@ +--- +title: "Verification" +description: "Verify SDK Chat Completions and configure attestation policy." +--- + +`InferenceClient` verifies the Gateway and every returned NEAR model-attestation candidate before sending an E2EE Chat Completion. Call `verifyResponse()` after a completion to verify its response signature with the request and response bytes captured by the client. + +```ts +const receipt = await client.verifyResponse(completion.id); +console.log(`Verified ${receipt.signatureKind} response.`); +``` + + + `verifyResponse()` is explicit. For a streaming completion, consume the entire stream first, then call it with the completion ID so the SDK can verify the exact response bytes. + + +## Set a TCB policy + +By default, the SDK accepts the Intel TCB statuses `UpToDate` and `OutOfDate`. To require `UpToDate`, apply a policy to both the Gateway and model evidence: + +```ts +const strict = { + policy: { acceptedTcbStatuses: ['UpToDate'] as const }, +}; + +const client = new InferenceClient({ + baseUrl, + apiKey, + e2ee: true, + gatewayVerification: strict, + modelVerification: strict, +}); +``` + +## Runtime behavior + +For Node, import from `@nearai/inference-sdk/node`. It verifies the Gateway TLS peer and binds later requests to the verified Gateway identity. For a browser or application proxy, import from `@nearai/inference-sdk`; browser Fetch cannot read the TLS peer certificate, so that entry point does not perform Gateway TLS binding. + +For a manual verification flow or a custom policy, see [Verification](/cloud/verification). diff --git a/docs.json b/docs.json index 6189efa..23f41e8 100644 --- a/docs.json +++ b/docs.json @@ -89,11 +89,13 @@ ] }, { - "group": "NEAR AI Inference SDK", + "group": "SDK", "icon": "braces", "root": "cloud/inference-sdk/index", "pages": [ - "cloud/inference-sdk/cloud-gateway" + "cloud/inference-sdk/e2ee", + "cloud/inference-sdk/verification", + "cloud/inference-sdk/ohttp" ] } ] @@ -501,7 +503,7 @@ }, { "source": "/cloud/verification/reference/sdk", - "destination": "/cloud/inference-sdk/cloud-gateway" + "destination": "/cloud/inference-sdk/e2ee" }, { "source": "/cloud/verification/sdk", @@ -509,11 +511,15 @@ }, { "source": "/cloud/verification/sdk/cloud-api", - "destination": "/cloud/inference-sdk/cloud-gateway" + "destination": "/cloud/inference-sdk/e2ee" }, { "source": "/cloud/verification/sdk/direct", "destination": "/cloud/inference-sdk/direct" + }, + { + "source": "/cloud/inference-sdk/cloud-gateway", + "destination": "/cloud/inference-sdk/e2ee" } ] } From bd265845c15bc65de7178251bd21805750b4b86d Mon Sep 17 00:00:00 2001 From: Robert Yan Date: Thu, 24 Sep 2026 22:14:23 +0800 Subject: [PATCH 07/10] docs: consolidate SDK guides and clarify E2EE defaults --- cloud/inference-sdk/e2ee.mdx | 39 ---------- cloud/inference-sdk/index.mdx | 103 +++++++++++++++++++++++---- cloud/inference-sdk/ohttp.mdx | 32 --------- cloud/inference-sdk/verification.mdx | 39 ---------- docs.json | 29 ++++---- 5 files changed, 106 insertions(+), 136 deletions(-) delete mode 100644 cloud/inference-sdk/e2ee.mdx delete mode 100644 cloud/inference-sdk/ohttp.mdx delete mode 100644 cloud/inference-sdk/verification.mdx diff --git a/cloud/inference-sdk/e2ee.mdx b/cloud/inference-sdk/e2ee.mdx deleted file mode 100644 index a10a5e3..0000000 --- a/cloud/inference-sdk/e2ee.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "E2EE" -description: "Send an end-to-end encrypted Chat Completion with the SDK." ---- - -E2EE is enabled by default. The SDK verifies the required attestation evidence, encrypts supported Chat fields to a key from the verified model evidence, and decrypts the response automatically. - -```ts -import { InferenceClient } from '@nearai/inference-sdk/node'; - -const baseUrl = 'https://cloud-api.near.ai/v1'; -const model = 'z-ai/glm-5.3-flash'; -const apiKey = process.env.NEARAI_API_KEY; -if (!apiKey) throw new Error('NEARAI_API_KEY is required'); - -const client = new InferenceClient({ - baseUrl, - apiKey, - e2ee: true, -}); - -const completion = await client.chat.completions.create({ - model, - messages: [{ role: 'user', content: 'Reply with the word ok.' }], -}); - -console.log(completion.choices[0]?.message.content); -``` - -## Next steps - - - - Verify the completion and tune attestation policy. - - - Add OHTTP to Chat requests and responses. - - diff --git a/cloud/inference-sdk/index.mdx b/cloud/inference-sdk/index.mdx index 20e93dc..eaf31eb 100644 --- a/cloud/inference-sdk/index.mdx +++ b/cloud/inference-sdk/index.mdx @@ -1,10 +1,9 @@ --- title: "SDK" +icon: "braces" description: "Use the TypeScript SDK for verified, end-to-end encrypted Chat Completions." --- -Use the TypeScript SDK with the NEAR AI Cloud Gateway for verified, end-to-end encrypted Chat Completions. - ## Install The package requires Node.js 24 or later. @@ -13,14 +12,92 @@ The package requires Node.js 24 or later. npm install @nearai/inference-sdk@next ``` - - - Send encrypted Chat Completions. - - - Verify attestation and response signatures. - - - Encapsulate Chat traffic with OHTTP. - - +## E2EE + +End-to-end encryption (E2EE) is disabled by default in `InferenceClient`. Set `e2ee: true` to enable it for a model with supported model attestation. When enabled, the SDK verifies the required attestation evidence, encrypts supported Chat fields to a key from the verified model evidence, and decrypts the response automatically. + +```ts +import { InferenceClient } from '@nearai/inference-sdk/node'; + +const baseUrl = 'https://cloud-api.near.ai/v1'; +const model = 'z-ai/glm-5.3-flash'; +const apiKey = process.env.NEARAI_API_KEY; +if (!apiKey) throw new Error('NEARAI_API_KEY is required'); + +const client = new InferenceClient({ + baseUrl, + apiKey, + e2ee: true, +}); + +const completion = await client.chat.completions.create({ + model, + messages: [{ role: 'user', content: 'Reply with the word ok.' }], +}); + +console.log(completion.choices[0]?.message.content); +``` + +## Verification + +`InferenceClient` verifies the Gateway and every returned NEAR model-attestation candidate before sending an E2EE Chat Completion. Call `verifyResponse()` after a completion to verify its response signature with the request and response bytes captured by the client. + +```ts +const receipt = await client.verifyResponse(completion.id); +console.log(`Verified ${receipt.signatureKind} response.`); +``` + + + `verifyResponse()` is explicit. For a streaming completion, consume the entire stream first, then call it with the completion ID so the SDK can verify the exact response bytes. + + +### Set a TCB policy + +By default, the SDK accepts the Intel TCB statuses `UpToDate` and `OutOfDate`. To require `UpToDate`, apply a policy to both the Gateway and model evidence: + +```ts +const strict = { + policy: { acceptedTcbStatuses: ['UpToDate'] as const }, +}; + +const client = new InferenceClient({ + baseUrl, + apiKey, + e2ee: true, + gatewayVerification: strict, + modelVerification: strict, +}); +``` + +### Runtime behavior + +For Node, import from `@nearai/inference-sdk/node`. It verifies the Gateway TLS peer and binds later requests to the verified Gateway identity. For a browser or application proxy, import from `@nearai/inference-sdk`; browser Fetch cannot read the TLS peer certificate, so that entry point does not perform Gateway TLS binding. + +For a manual verification flow or a custom policy, see [Verification](/cloud/verification). + +## OHTTP + +Set `ohttp: true` to encapsulate Chat requests and responses with OHTTP. OHTTP uses the SDK's default Ed25519 signing algorithm; it is not compatible with `signingAlgo: 'ecdsa'`. + +```ts +const client = new InferenceClient({ + baseUrl, + apiKey, + e2ee: true, + ohttp: true, +}); +``` + +The Chat and `verifyResponse()` calls stay the same. Before sending Chat, the SDK verifies the Gateway's signed OHTTP configuration; a missing or invalid configuration blocks the request. OHTTP encapsulates the exchange to the Gateway, while E2EE encrypts supported Chat fields to the verified model key. + + + OHTTP applies only to Chat. Attestation and signature requests remain regular HTTPS. The configured endpoint or proxy must expose `/ohttp` at the same origin. Authorization and custom headers sent on the outer request, along with the client's network address, are not hidden by OHTTP. + + +## Examples + +See the [Inference SDK examples and setup instructions](https://github.com/nearai/inference-sdk/tree/main/examples) for runnable projects. + +- [InferenceClient](https://github.com/nearai/inference-sdk/blob/main/examples/example-js/gateway/client.ts): streaming and non-streaming Chat, response verification, and Gateway image provenance checks. +- [OpenAI SDK integration](https://github.com/nearai/inference-sdk/blob/main/examples/example-js/gateway/client-openai-sdk.ts): use `InferenceClient.fetch` with the OpenAI client. +- [Manual verification and E2EE](https://github.com/nearai/inference-sdk/blob/main/examples/example-js/gateway/bare.ts): work directly with attestation, encryption, and signature-verification helpers. diff --git a/cloud/inference-sdk/ohttp.mdx b/cloud/inference-sdk/ohttp.mdx deleted file mode 100644 index bd09b06..0000000 --- a/cloud/inference-sdk/ohttp.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "OHTTP" -description: "Encapsulate SDK Chat traffic with OHTTP." ---- - -Set `ohttp: true` to encapsulate Chat requests and responses with OHTTP. OHTTP uses the SDK's default Ed25519 signing algorithm; it is not compatible with `signingAlgo: 'ecdsa'`. - -```ts -const client = new InferenceClient({ - baseUrl, - apiKey, - e2ee: true, - ohttp: true, -}); -``` - -The Chat and `verifyResponse()` calls stay the same. Before sending Chat, the SDK verifies the Gateway's signed OHTTP configuration; a missing or invalid configuration blocks the request. OHTTP encapsulates the exchange to the Gateway, while E2EE encrypts supported Chat fields to the verified model key. - - - OHTTP applies only to Chat. Attestation and signature requests remain regular HTTPS. The configured endpoint or proxy must expose `/ohttp` at the same origin. Authorization and custom headers sent on the outer request, along with the client's network address, are not hidden by OHTTP. - - -## Next steps - - - - Send encrypted Chat Completions. - - - Verify evidence and response signatures. - - diff --git a/cloud/inference-sdk/verification.mdx b/cloud/inference-sdk/verification.mdx deleted file mode 100644 index e9c3a42..0000000 --- a/cloud/inference-sdk/verification.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "Verification" -description: "Verify SDK Chat Completions and configure attestation policy." ---- - -`InferenceClient` verifies the Gateway and every returned NEAR model-attestation candidate before sending an E2EE Chat Completion. Call `verifyResponse()` after a completion to verify its response signature with the request and response bytes captured by the client. - -```ts -const receipt = await client.verifyResponse(completion.id); -console.log(`Verified ${receipt.signatureKind} response.`); -``` - - - `verifyResponse()` is explicit. For a streaming completion, consume the entire stream first, then call it with the completion ID so the SDK can verify the exact response bytes. - - -## Set a TCB policy - -By default, the SDK accepts the Intel TCB statuses `UpToDate` and `OutOfDate`. To require `UpToDate`, apply a policy to both the Gateway and model evidence: - -```ts -const strict = { - policy: { acceptedTcbStatuses: ['UpToDate'] as const }, -}; - -const client = new InferenceClient({ - baseUrl, - apiKey, - e2ee: true, - gatewayVerification: strict, - modelVerification: strict, -}); -``` - -## Runtime behavior - -For Node, import from `@nearai/inference-sdk/node`. It verifies the Gateway TLS peer and binds later requests to the verified Gateway identity. For a browser or application proxy, import from `@nearai/inference-sdk`; browser Fetch cannot read the TLS peer certificate, so that entry point does not perform Gateway TLS binding. - -For a manual verification flow or a custom policy, see [Verification](/cloud/verification). diff --git a/docs.json b/docs.json index 23f41e8..7a8aa21 100644 --- a/docs.json +++ b/docs.json @@ -88,16 +88,7 @@ } ] }, - { - "group": "SDK", - "icon": "braces", - "root": "cloud/inference-sdk/index", - "pages": [ - "cloud/inference-sdk/e2ee", - "cloud/inference-sdk/verification", - "cloud/inference-sdk/ohttp" - ] - } + "cloud/inference-sdk/index" ] }, { @@ -503,7 +494,7 @@ }, { "source": "/cloud/verification/reference/sdk", - "destination": "/cloud/inference-sdk/e2ee" + "destination": "/cloud/inference-sdk#e2ee" }, { "source": "/cloud/verification/sdk", @@ -511,7 +502,7 @@ }, { "source": "/cloud/verification/sdk/cloud-api", - "destination": "/cloud/inference-sdk/e2ee" + "destination": "/cloud/inference-sdk#e2ee" }, { "source": "/cloud/verification/sdk/direct", @@ -519,7 +510,19 @@ }, { "source": "/cloud/inference-sdk/cloud-gateway", - "destination": "/cloud/inference-sdk/e2ee" + "destination": "/cloud/inference-sdk#e2ee" + }, + { + "source": "/cloud/inference-sdk/e2ee", + "destination": "/cloud/inference-sdk#e2ee" + }, + { + "source": "/cloud/inference-sdk/verification", + "destination": "/cloud/inference-sdk#verification" + }, + { + "source": "/cloud/inference-sdk/ohttp", + "destination": "/cloud/inference-sdk#ohttp" } ] } From 7e9ff58070beab9cd0c8d62891407031e75958a0 Mon Sep 17 00:00:00 2001 From: Robert Yan Date: Thu, 24 Sep 2026 22:20:00 +0800 Subject: [PATCH 08/10] docs: nest direct SDK guide under Direct Completions --- cloud/inference-sdk/direct.mdx | 3 ++- docs.json | 9 +++++++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/cloud/inference-sdk/direct.mdx b/cloud/inference-sdk/direct.mdx index b706061..2f33d12 100644 --- a/cloud/inference-sdk/direct.mdx +++ b/cloud/inference-sdk/direct.mdx @@ -1,5 +1,6 @@ --- -title: "Experimental Direct Model Endpoints" +title: "SDK" +icon: "braces" description: "Experimental SDK notes for direct model endpoints." --- diff --git a/docs.json b/docs.json index 7a8aa21..e219618 100644 --- a/docs.json +++ b/docs.json @@ -135,8 +135,13 @@ { "group": "Experimental", "pages": [ - "cloud/experimental/direct-completions", - "cloud/inference-sdk/direct" + { + "group": "Direct Completions", + "root": "cloud/experimental/direct-completions", + "pages": [ + "cloud/inference-sdk/direct" + ] + } ] } ] From d30071523b1ec416c0ca4f1a22cf02e711f6c336 Mon Sep 17 00:00:00 2001 From: Robert Yan Date: Thu, 24 Sep 2026 22:21:02 +0800 Subject: [PATCH 09/10] docs: remove redirects for intermediate SDK paths --- docs.json | 32 -------------------------------- 1 file changed, 32 deletions(-) diff --git a/docs.json b/docs.json index e219618..433f920 100644 --- a/docs.json +++ b/docs.json @@ -496,38 +496,6 @@ { "source": "/cloud/verification/provenance", "destination": "/cloud/verification" - }, - { - "source": "/cloud/verification/reference/sdk", - "destination": "/cloud/inference-sdk#e2ee" - }, - { - "source": "/cloud/verification/sdk", - "destination": "/cloud/inference-sdk" - }, - { - "source": "/cloud/verification/sdk/cloud-api", - "destination": "/cloud/inference-sdk#e2ee" - }, - { - "source": "/cloud/verification/sdk/direct", - "destination": "/cloud/inference-sdk/direct" - }, - { - "source": "/cloud/inference-sdk/cloud-gateway", - "destination": "/cloud/inference-sdk#e2ee" - }, - { - "source": "/cloud/inference-sdk/e2ee", - "destination": "/cloud/inference-sdk#e2ee" - }, - { - "source": "/cloud/inference-sdk/verification", - "destination": "/cloud/inference-sdk#verification" - }, - { - "source": "/cloud/inference-sdk/ohttp", - "destination": "/cloud/inference-sdk#ohttp" } ] } From a69c27758d7a861ce06ab7ae45160f0b455d449e Mon Sep 17 00:00:00 2001 From: Robert Yan Date: Thu, 24 Sep 2026 22:22:10 +0800 Subject: [PATCH 10/10] docs: link direct inference SDK examples --- cloud/inference-sdk/direct.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/cloud/inference-sdk/direct.mdx b/cloud/inference-sdk/direct.mdx index 2f33d12..3b9a2c0 100644 --- a/cloud/inference-sdk/direct.mdx +++ b/cloud/inference-sdk/direct.mdx @@ -78,6 +78,14 @@ The example uses `@nearai/inference-sdk/node`. Direct endpoint TLS binding is no For a browser or an application proxy, import from `@nearai/inference-sdk`. Configure the same explicit `baseUrl` for the endpoint your application uses. +## Examples + +See the [Inference SDK examples and setup instructions](https://github.com/nearai/inference-sdk/tree/main/examples#direct-model-endpoints) for runnable direct-endpoint projects. + +- [DirectInferenceClient](https://github.com/nearai/inference-sdk/blob/main/examples/example-js/direct/client.ts): streaming and non-streaming Chat with E2EE and response verification. +- [OpenAI SDK integration](https://github.com/nearai/inference-sdk/blob/main/examples/example-js/direct/client-openai-sdk.ts): use `DirectInferenceClient.fetch` with the OpenAI client. +- [Manual verification](https://github.com/nearai/inference-sdk/blob/main/examples/example-js/direct/bare.ts): verify model attestations and response signatures directly. This example sends plaintext Chat bodies over HTTPS without E2EE. + ## Next steps