Create an https.Agent that establishes aTLS-verified connections. Use this with https.request, axios, or other HTTP clients that accept an Agent.
Function signature
function createAtlsAgent(options: AtlsAgentOptions): Agent
Parameters
Configuration object for the aTLS agent
Target host with optional port (e.g., "enclave.example.com" or "enclave.example.com:8443")
SNI (Server Name Indication) override. Defaults to the host portion of target.
onAttestation
(attestation: AtlsAttestation, socket: Socket) => void
Callback invoked after successful attestation verification. Receives the attestation object and the underlying socket.
Additional options passed to the underlying https.Agent. Common options include keepAlive, keepAliveMsecs, maxSockets, maxFreeSockets, and timeout.
Return value
An https.Agent instance that creates aTLS connections. The agent automatically manages connection pooling and keep-alive.
Usage examples
With https.request
import { createAtlsAgent } from "@concrete-security/atlas-node"
import https from "https"
const agent = createAtlsAgent({
target: "enclave.example.com",
policy: {
type: "dstack_tdx",
allowed_tcb_status: ["UpToDate", "SWHardeningNeeded"]
},
onAttestation: (att) => console.log("Verified:", att.teeType)
})
https.get("https://enclave.example.com/api/data", { agent }, (res) => {
// Access attestation data on the socket
console.log(res.socket.atlsAttestation)
let data = ""
res.on("data", (chunk) => data += chunk)
res.on("end", () => console.log(data))
})
With axios
import { createAtlsAgent } from "@concrete-security/atlas-node"
import axios from "axios"
const agent = createAtlsAgent({
target: "enclave.example.com",
policy: productionPolicy,
onAttestation: (att) => {
if (!att.trusted) {
throw new Error("Attestation failed")
}
}
})
const client = axios.create({
httpsAgent: agent,
baseURL: "https://enclave.example.com"
})
const response = await client.get("/api/data")
console.log(response.data)
With custom agent options
const agent = createAtlsAgent({
target: "enclave.example.com",
policy: productionPolicy,
keepAlive: true,
keepAliveMsecs: 30000,
maxSockets: 50,
maxFreeSockets: 10,
timeout: 60000
})
Production usage with full verification
import { createAtlsAgent, mergeWithDefaultAppCompose } from "@concrete-security/atlas-node"
const agent = createAtlsAgent({
target: "enclave.example.com:8443",
policy: {
type: "dstack_tdx",
expected_bootchain: {
mrtd: "b24d3b24...",
rtmr0: "24c15e08...",
rtmr1: "6e1afb74...",
rtmr2: "89e73ced..."
},
os_image_hash: "86b18137...",
app_compose: mergeWithDefaultAppCompose({
docker_compose_file: "services:\n app:\n image: myapp",
allowed_envs: ["API_KEY"]
}),
allowed_tcb_status: ["UpToDate", "SWHardeningNeeded"]
},
onAttestation: (attestation, socket) => {
console.log("TEE Type:", attestation.teeType)
console.log("TCB Status:", attestation.tcbStatus)
console.log("Measurement:", attestation.measurement)
}
})
Accessing attestation data
Attestation data is available on the socket:
const agent = createAtlsAgent({ target, policy })
https.get("https://enclave.example.com/api/data", { agent }, (res) => {
const attestation = res.socket.atlsAttestation
console.log(attestation.trusted) // true
console.log(attestation.teeType) // "tdx"
console.log(attestation.measurement) // "b24d3b24..."
console.log(attestation.tcbStatus) // "UpToDate"
console.log(attestation.advisoryIds) // []
})
Connection pooling
The agent automatically manages connection pooling with keep-alive enabled by default:
const agent = createAtlsAgent({
target: "enclave.example.com",
policy: productionPolicy,
keepAlive: true, // Default: true
keepAliveMsecs: 30000, // Default: 1000
maxSockets: 50, // Default: Infinity
maxFreeSockets: 10 // Default: 256
})
// Make multiple requests - connections are reused
for (let i = 0; i < 100; i++) {
https.get("https://enclave.example.com/api/data", { agent }, handler)
}
Error handling
const agent = createAtlsAgent({
target: "enclave.example.com",
policy: productionPolicy,
onAttestation: (attestation, socket) => {
if (!attestation.trusted) {
throw new Error(`Attestation failed: ${attestation.teeType}`)
}
}
})
https.get("https://enclave.example.com/api/data", { agent }, (res) => {
// Handle response
}).on("error", (err) => {
if (err.message.includes("Attestation failed")) {
console.error("TEE verification failed")
} else if (err.message.includes("BootchainMismatch")) {
console.error("Bootchain mismatch")
} else {
console.error("Request failed:", err.message)
}
})
Graceful shutdown
For long-running processes, close all sockets before exit:
import { closeAllSockets } from "@concrete-security/atlas-node/binding"
const agent = createAtlsAgent({ target, policy })
// ... use agent ...
// Before process exit
process.on("SIGTERM", async () => {
await closeAllSockets()
process.exit(0)
})