TypeScript API Programming Guide

© Pi Soft, 2018-2026 · Tricryption Engine 8.1

The TypeScript agent is the npm package server-ts-agent (TricryptionSuite/TEAgent/server-ts-agent), for server-side Node.js consumers. It speaks the Key Server's binary protocol over TLS 1.3 in pure TypeScript. Consume it through a file: dependency and import it by package name only — the typed barrel (src/index.ts) is the supported surface, and a subpath into dist/ is not. This page is a guide only: the TypeScript declarations are not part of the generated reference; the barrel's and src/auth-types.ts's comments are the reference. The in-tree samples are under samples/ts.

General procedure

Create an SSLConnection and await conn.open(host, port).
Create an authentication context and await Auth.authenticate(context, conn). A refusal rejects the promise (it never throws synchronously).
Use the connection: for example new Crypto(conn), whose encrypt(buf) resolves an encrypted Buffer carrying its ttag, and decrypt(enc, enc.ttag); or Administration for administrative operations.
await conn.close().

Note: FIPS mode is not offered by this agent. It runs on Node's own bundled OpenSSL, which is outside the product's FIPS boundary by decision; FIPS mode is the native agents' (TEEnableFipsMode() in C, PISOFT::TEAgent::enableFipsMode() in C++) and the key server's (FipsMode="1"). A Key Server in FIPS mode accepts this agent's TLS 1.3 connections on a NIST curve.

Connections

new SSLConnection(options) takes Node TLS options. Peer verification is on by default (rejectUnauthorized: true, TLS 1.3 floor). Name the certificate you trust the Key Server by as ca. getChannelBinding() returns the open connection's RFC 9266 exporter — a secret of the connection, which the contexts read for themselves.

Verify the Key Server. A Key Server's TLS certificate is issued by its own self-signed CA; that CA is the anchor. Obtain it from the Key Server's operator and pass it as ca, with rejectUnauthorized: true. The certificate the Key Server presents names localhost whatever host it is reached by, so pass checkServerIdentity: () => undefined as well: the anchor, not the host name, decides which server is trusted. rejectUnauthorized: false disables verification altogether, so the connection talks to whoever answers on the port; do not use it. A Kerberos login refuses it (below).

const conn = new SSLConnection({
  ca: fs.readFileSync('/etc/te/ks-ca.pem'),   // the Key Server's CA: the anchor
  rejectUnauthorized: true,
  checkServerIdentity: () => undefined,       // the Key Server presents CN=localhost
});

The in-tree sample ts_connect.ts builds these options as ksServerTls(), reading the anchor's path from KS_SERVER_ANCHOR.

Authentication contexts

context	Key Server module	credential
`SRPAuthCtx(user, password)`	`SRPAuthentication`	user name and password; SRP-6a/SHA-384
`TokenAuthCtx(token)`	`TokenAuthentication`	a session token from an authenticated connection
`FileX509AuthCtx()` then `open(certPath, keyPath[, passphrase])`	`X509Authentication`	a PEM certificate and its RSA or EC key; the signature is bound to the connection. `X509AuthCtx` is its base, for a signer kept elsewhere
`SSLMAuthCtx()`	mutual TLS (not a module)	the client certificate the connection presents at the handshake
`DelegatedAuthCtx()` then `setX509Principal(der)` or `setXAuthPrincipal(id)`	`DelegatedAuthentication`	the delegator's client certificate at the handshake, and ONE target
`GSSAPIAuthCtx(options)`	`GSSAPIAuthentication`	a Kerberos ticket the caller already holds — see Kerberos login

SRPAuthCtx keeps the password, and TokenAuthCtx the token, for the life of the context object: do not keep either past authenticate, and do not log them.

Kerberos login

GSSAPIAuthCtx logs in with Kerberos through the Key Server's GSSAPIAuthentication module (AM10). The Key Server must have the module enabled; the operator steps are in the repository's docs/KERBEROS_AM10.md.

Options (GSSAPIAuthOptions; nothing in them is secret):

servicePrincipal — required: the Key Server's acceptor principal, the name its keytab holds, e.g. te/ks.example.com@EXAMPLE.COM.
ccache — the credential cache (FILE:/path, ...); absent, the default cache.
initiatorPath — where the te_gss_initiator helper is (below).
krb5Config — the Kerberos profile the helper reads (its KRB5_CONFIG); absent, the helper inherits this process's environment.
stepTimeoutMs — how long one helper step may take, in milliseconds (default 30000).

The anchor is the connection's, and it is required. Open the connection verified, as Connections shows: new SSLConnection({ ca: <the Key Server's CA>, rejectUnauthorized: true, checkServerIdentity: () => undefined }). Before anything is sent the context refuses a connection whose options carry no ca, and a connection whose socket did not verify the Key Server — whatever options opened it.

The helper. Node has no GSS-API, and no Node module is used. The Kerberos half of the login runs in te_gss_initiator, a native executable built with the product (target te_gss_initiator, the same pinned MIT Kerberos as the C and C++ agents, and the helper the Java agent drives too). The context finds it, in order, at initiatorPath, in the environment variable TE_GSS_INITIATOR (the Java agent's), beside the agent's own dist/ modules (te_gss_initiator, on Windows te_gss_initiator.exe, in the directory holding the compiled auth_ctx_gssapi.js), and finally on PATH. The agent's own build (npm run build, through scripts/copy-assets.js) stages it beside dist/ from the CMake build when that build has one (TE_CMAKE_BUILD, else the shipping preset's build directory); elsewhere, copy it from the build directory and name it or put it on PATH. A missing helper is refused as GSSAPI initiator: no te_gss_initiator at <path> (name it with initiatorPath or TE_GSS_INITIATOR, or put it on PATH).

The binding is carried for you. The context reads the connection's own RFC 9266 channel binding, hands it to the helper (and zeroes its copy), and relays each Kerberos token; mutual authentication is requested and confirmed. The Kerberos profile the helper reads must declare client_aware_channel_bindings = true under [libdefaults], or the Key Server refuses the login as unbound.

import * as fs from 'fs';
import { SSLConnection, Auth, GSSAPIAuthCtx, Crypto } from 'server-ts-agent';

async function main(): Promise<void> {
  const conn = new SSLConnection({
    ca: fs.readFileSync('/etc/te/ks-ca.pem'),   // required
    rejectUnauthorized: true,
    checkServerIdentity: () => undefined,       // the Key Server presents CN=localhost
  });
  await conn.open('ks.example.com', 8888);
  try {
    await Auth.authenticate(
      new GSSAPIAuthCtx({
        servicePrincipal: 'te/ks.example.com@EXAMPLE.COM',
        initiatorPath: '/opt/te/bin/te_gss_initiator',
        // no ccache: the default credential cache
      }),
      conn,
    );
    const crypto = new Crypto(conn);
    const enc = await crypto.encrypt(Buffer.from('hello'));
    const plain = await crypto.decrypt(enc, enc.ttag);
  } finally {
    await conn.close();
  }
}

main().catch((e: unknown) => {
  console.error(e instanceof Error ? e.message : String(e));
  process.exit(1);
});

Refusals reject Auth.authenticate with an Error whose message names the check:

before anything is sent — Kerberos: no key server anchor set (ca on the SSLConnection) -- a Kerberos login names the key server it trusts, or the key server's certificate did not verify: <reason>;
at the handshake, with rejectUnauthorized: true and the wrong ca — Node's own verification error (self-signed certificate in certificate chain);
from the Key Server — an ERROR_PACKAGE whose text names the check, for example GSSAPI: the exchange is not bound to this connection (GSS_C_CHANNEL_BOUND_FLAG not set) (the profile setting above), GSSAPI: channel binding mismatch (GSS_S_BAD_BINDINGS) -- the exchange was not bound to this connection (a relay in the path) or GSSAPI: the security context was not established (a ticket for another service, or none). The operator guide lists every one and its fix;
from the helper — a message beginning GSSAPI initiator: (the helper reported an error of its own, exited without a verdict, or did not answer within stepTimeoutMs).

Windows. te_gss_initiator.exe needs the MIT Kerberos package's gssapi64.dll, krb5_64.dll, comerr64.dll and k5sprt64.dll, and the product's libcrypto-3-x64.dll, on its PATH.

General procedure​

Connections​

Authentication contexts​

Kerberos login​

General procedure

Connections

Authentication contexts

Kerberos login