tturn 0.1.0 → 0.1.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -1,108 +1,8 @@
 # Tturn (English)
 
-[English](./README.en.md) | [中文](./README.zh-CN.md)
+[English (default)](./README.md) | [中文](./README.zh-CN.md)
 
-`tturn` is a high-performance TURN server package for Node.js.
-It uses an embedded native core (Rust + N-API), so you can install and run it directly from npm without Docker and without an external `turnserver.exe` runtime dependency.
+The primary English documentation is now in `README.md`.
 
-## 1) What this project is
-
-- Embedded TURN server for Node.js applications.
-- Native data plane implemented in Rust for better throughput and lower overhead than pure JavaScript TURN implementations.
-- Programmatic API and CLI are both provided.
-- Time-limited TURN credentials are generated with HMAC-SHA1 (standard TURN REST style).
-
-## 2) Current capabilities
-
-- Start / stop TURN service from Node.
-- Issue short-lived credentials.
-- Return WebRTC ICE `urls/username/credential` directly.
-- Health check (`running: boolean`).
-
-## 3) Install
-
-```bash
-npm i tturn
-```
-
-## 4) Quick start (Node API)
-
-```ts
-import { Tturn } from "tturn";
-
-const turn = new Tturn({
-  realm: "turn.example.com",
-  authSecret: "replace-with-your-secret",
-  publicIp: "1.2.3.4",
-  listenPort: 3478
-});
-
-await turn.start();
-
-const ice = turn.issueCredential({ ttlSec: 600, userId: "user-1001" });
-console.log(ice);
-
-// stop when exiting process
-await turn.stop();
-```
-
-## 5) CLI usage
-
-```bash
-# Start embedded TURN service
-TURN_REALM=turn.example.com TURN_SECRET=replace-with-your-secret tturn start
-
-# Print one ICE credential payload
-TURN_REALM=turn.example.com TURN_SECRET=replace-with-your-secret tturn credential
-```
-
-## 6) API options
-
-- `realm` (required): TURN realm/domain.
-- `authSecret` (required): shared secret for dynamic credentials.
-- `listenPort` (default `3478`): TURN listening port.
-- `publicIp` (optional, recommended): public relay IP exposed to clients.
-- `listeningIp` (default `0.0.0.0`): bind address.
-- `minPort` / `maxPort`: reserved for relay port range control in next iterations.
-
-## 7) Build from source
-
-Requirements:
-
-- Node.js >= 18
-- Rust toolchain (stable)
-
-Commands:
-
-```bash
-npm install
-npm run build:native
-./node_modules/.bin/tsc -p tsconfig.json
-```
-
-Then run demo app:
-
-```bash
-node dist/app.js
-```
-
-Edit fixed config in `src/app.ts` before running.
-
-## 8) Verify with Google WebRTC tool
-
-1. Start service (`node dist/app.js`).
-2. Copy printed `urls`, `username`, `credential`.
-3. Open Google Trickle ICE tool and paste the ICE server config.
-4. Gather candidates and confirm relay candidates are returned.
-
-## 9) Publish to npm
-
-```bash
-npm login
-npm publish --access public
-```
-
-Notes:
-
-- npm package names must be lowercase, so publish as `tturn`.
-- For production users across multiple platforms, publish prebuilt `.node` artifacts for each target platform/arch.
+- Main English doc: `README.md`
+- Chinese doc: `README.zh-CN.md`

package/README.md

@@ -1,14 +1,144 @@
 # Tturn
 
-[English](./README.en.md) | [中文](./README.zh-CN.md)
+[English (default)](./README.md) | [中文](./README.zh-CN.md)
 
-`tturn` is a high-performance TURN server package for Node.js with an embedded native core (Rust + N-API).
+`tturn` is a high-performance TURN server package for Node.js.
+It embeds a native Rust core via N-API, so you can install from npm and run directly.
 
 - No Docker runtime required.
 - No external `turnserver.exe` runtime dependency.
-- Programmatic API and CLI included.
+- Programmatic API and CLI are both included.
 
-Please read full docs:
+## What this project provides
 
-- English: `README.en.md`
-- 中文：`README.zh-CN.md`
+- Embedded TURN service for Node.js applications.
+- Native data plane implemented in Rust.
+- Dynamic TURN credentials using HMAC-SHA1 (TURN REST style).
+- Direct ICE payload output (`urls`, `username`, `credential`).
+
+## Install
+
+```bash
+npm i tturn
+```
+
+## Quick start (Node API)
+
+```ts
+import { Tturn } from "tturn";
+
+const turn = new Tturn({
+  realm: "turn.example.com",
+  password: "replace-with-your-password",
+  publicIp: "1.2.3.4",
+  listenPort: 3478,
+  username: "user-1001",
+  disableCredentialExpiry: true
+});
+
+const ice = await turn.start();
+
+console.log(ice);
+await turn.stop();
+```
+
+`start()` now returns one ICE payload directly, so bootstrap can be only `new Tturn(...)` + `start()`.
+
+For long-running sessions, set `disableCredentialExpiry: true` to issue non-expiring credentials.
+
+With static password mode (`password` + `username`), what you set is what clients use:
+
+- output `username` is exactly your configured username
+- output `credential` is exactly your configured password
+
+## Credential options
+
+`issueCredential(options)` supports:
+
+- `ttlSec` (optional, default `3600`, minimum `60`)
+- `username` (optional): pass a custom TURN username
+- `userId` (optional): legacy prefix mode (`userId:expiresAt`)
+
+Username behavior:
+
+- If `username` already ends with a future unix timestamp (for example `alice:1730000000`), it is used as-is.
+- Otherwise, `tturn` appends `:<expiresAt>` automatically so TURN auth remains valid.
+- If both `username` and `userId` are provided, `username` takes priority.
+
+## CLI usage
+
+```bash
+# Start embedded TURN service
+TURN_REALM=turn.example.com TURN_SECRET=replace-with-your-secret tturn start
+
+# Print one ICE credential payload
+TURN_REALM=turn.example.com TURN_SECRET=replace-with-your-secret tturn credential
+
+# Optional: provide custom username
+TURN_REALM=turn.example.com TURN_SECRET=replace-with-your-secret TTURN_USERNAME=alice tturn credential
+
+# Optional: disable credential expiry (long-lived credentials)
+TURN_REALM=turn.example.com TURN_SECRET=replace-with-your-secret TTURN_USERNAME=alice TTURN_DISABLE_CREDENTIAL_EXPIRY=1 tturn credential
+
+# Static account/password (exact value, no rewrite)
+TURN_REALM=turn.example.com TURN_USERNAME=alice TURN_PASSWORD=alice-pass TTURN_DISABLE_CREDENTIAL_EXPIRY=1 tturn start
+```
+
+Required env:
+
+- `TURN_REALM`
+- `TURN_SECRET` or `TURN_PASSWORD`
+
+Optional env:
+
+- `TURN_PUBLIC_IP`
+- `TURN_PORT`
+- `TTURN_TTL_SEC`
+- `TTURN_USER_ID`
+- `TTURN_USERNAME` (or `TURN_USERNAME`)
+- `TTURN_DISABLE_CREDENTIAL_EXPIRY` (`1` or `true`)
+
+## API options
+
+- `realm` (required): TURN realm/domain.
+- `authSecret` (optional): shared secret for dynamic credentials.
+- `password` (optional): static TURN password (when set, returned credential stays fixed).
+- `listenPort` (default `3478`): TURN listening port.
+- `publicIp` (optional, recommended): public relay IP exposed to clients.
+- `listeningIp` (default `0.0.0.0`): bind address.
+- `username` / `userId` (optional): default credential username seed. `username` has higher priority.
+- `ttlSec` (optional): default credential TTL used by `start()` and `issueCredential()`.
+- `disableCredentialExpiry` (optional): disable timestamp expiry check and issue non-expiring credentials.
+- `minPort` / `maxPort`: reserved for relay port range control in next iterations.
+
+At least one of `authSecret` or `password` must be provided.
+
+## Quick verify
+
+```bash
+npm install
+npm run build
+
+TURN_REALM=turn.example.com TURN_PUBLIC_IP=1.2.3.4 TURN_USERNAME=alice TURN_PASSWORD=alice-pass TTURN_DISABLE_CREDENTIAL_EXPIRY=1 node dist/cli.js credential
+```
+
+The returned JSON should keep `username = "alice"` and `credential = "alice-pass"`.
+
+## Build from source
+
+Requirements:
+
+- Node.js >= 18
+- Rust toolchain (stable)
+
+```bash
+npm install
+npm run build:native
+npm run build:ts
+```
+
+Run demo:
+
+```bash
+node dist/app.js
+```

package/README.zh-CN.md

@@ -1,107 +1,150 @@
-# Tturn（中文）
-
-[English](./README.en.md) | [中文](./README.zh-CN.md)
-
-`tturn` 是一个高性能的 Node.js TURN 服务包。
-它使用内嵌原生核心（Rust + N-API），可以直接通过 npm 安装并运行，不依赖 Docker，也不需要额外安装 `turnserver.exe` 作为运行时。
-
-## 1）项目介绍
-
-- `tturn` 是一个可直接在 Node.js 中运行的 TURN 服务包。
-- 底层是 Rust + N-API 原生实现，性能和资源效率优于纯 JS TURN 实现。
-- 不依赖 Docker，也不需要额外安装 `turnserver.exe` 作为运行时。
-- 同时提供 Node API 和 CLI 两种使用方式。
-
-## 2）当前功能
-
-- 在 Node 中启动 / 停止 TURN 服务。
-- 生成短时效 TURN 凭证（HMAC-SHA1）。
-- 直接输出 WebRTC 所需的 ICE 参数（`urls/username/credential`）。
-- 基础健康状态检查（`running: boolean`）。
-
-## 3）安装
-
-```bash
-npm i tturn
-```
-
-## 4）Node API 快速使用
-
-```ts
-import { Tturn } from "tturn";
-
+# Tturn（中文）
+
+[English（主文档）](./README.md) | [中文](./README.zh-CN.md)
+
+`tturn` 是一个高性能的 Node.js TURN 服务包。
+它使用内嵌原生核心（Rust + N-API），可以直接通过 npm 安装并运行，不依赖 Docker，也不需要额外安装 `turnserver.exe` 作为运行时。
+
+## 1）项目介绍
+
+- `tturn` 是一个可直接在 Node.js 中运行的 TURN 服务包。
+- 底层是 Rust + N-API 原生实现，性能和资源效率优于纯 JS TURN 实现。
+- 不依赖 Docker，也不需要额外安装 `turnserver.exe` 作为运行时。
+- 同时提供 Node API 和 CLI 两种使用方式。
+
+## 2）当前功能
+
+- 在 Node 中启动 / 停止 TURN 服务。
+- 生成短时效 TURN 凭证（HMAC-SHA1）。
+- 直接输出 WebRTC 所需的 ICE 参数（`urls/username/credential`）。
+- 基础健康状态检查（`running: boolean`）。
+
+## 3）安装
+
+```bash
+npm i tturn
+```
+
+## 4）Node API 快速使用
+
+```ts
+import { Tturn } from "tturn";
+
 const turn = new Tturn({
   realm: "turn.example.com",
-  authSecret: "replace-with-your-secret",
+  password: "replace-with-your-password",
   publicIp: "1.2.3.4",
-  listenPort: 3478
+  listenPort: 3478,
+  username: "user-1001",
+  disableCredentialExpiry: true
 });
 
-await turn.start();
-
-const ice = turn.issueCredential({ ttlSec: 600, userId: "user-1001" });
+const ice = await turn.start();
 console.log(ice);
 
 await turn.stop();
 ```
 
-## 5）CLI 用法
+`start()` 会直接返回一组 ICE，因此最简流程只需要 `new Tturn(...)` 和 `start()`。
 
-```bash
-# 启动内置 TURN 服务
-TURN_REALM=turn.example.com TURN_SECRET=replace-with-your-secret tturn start
+如果你需要长时间持续连接，可设置 `disableCredentialExpiry: true`，生成不过期凭证。
 
+在静态账号密码模式（`password` + `username`）下：
+
+- 输出的 `username` 就是你配置的账号
+- 输出的 `credential` 就是你配置的密码
+
+## 5）CLI 用法
+
+```bash
+# 启动内置 TURN 服务
+TURN_REALM=turn.example.com TURN_SECRET=replace-with-your-secret tturn start
+
 # 生成一组 ICE 凭证
 TURN_REALM=turn.example.com TURN_SECRET=replace-with-your-secret tturn credential
+
+# 可选：传入自定义 username
+TURN_REALM=turn.example.com TURN_SECRET=replace-with-your-secret TTURN_USERNAME=alice tturn credential
+
+# 可选：禁用凭证过期（长期凭证）
+TURN_REALM=turn.example.com TURN_SECRET=replace-with-your-secret TTURN_USERNAME=alice TTURN_DISABLE_CREDENTIAL_EXPIRY=1 tturn credential
+
+# 静态账号密码（原样输出，不改写）
+TURN_REALM=turn.example.com TURN_USERNAME=alice TURN_PASSWORD=alice-pass TTURN_DISABLE_CREDENTIAL_EXPIRY=1 tturn start
 ```
 
-## 6）配置参数说明
+## 5.1）凭证参数补充（username）
 
+`issueCredential(options)` 额外支持 `username`（可选）。
+
+- 如果 `username` 已经以未来时间戳结尾（例如 `alice:1730000000`），会原样使用。
+- 否则会自动补上 `:<expiresAt>`，保证 TURN 鉴权可用。
+- 同时传 `username` 和 `userId` 时，优先使用 `username`。
+
+## 6）配置参数说明
+
 - `realm`（必填）：TURN realm / 域名。
-- `authSecret`（必填）：动态凭证签名密钥。
+- `authSecret`（可选）：动态凭证签名密钥。
+- `password`（可选）：静态 TURN 密码（设置后返回值保持固定）。
 - `listenPort`（默认 `3478`）：TURN 监听端口。
 - `publicIp`（建议配置）：客户端访问的公网 IP。
 - `listeningIp`（默认 `0.0.0.0`）：本地绑定地址。
+- `username` / `userId`（可选）：默认凭证用户名种子，`username` 优先级更高。
+- `ttlSec`（可选）：`start()` 与 `issueCredential()` 的默认凭证时效。
+- `disableCredentialExpiry`（可选）：禁用时间戳过期校验，生成不过期凭证。
 - `minPort` / `maxPort`：预留给后续中继端口范围控制。
 
-## 7）源码构建
-
-环境要求：
+`authSecret` 和 `password` 至少需要提供一个。
 
-- Node.js >= 18
-- Rust 稳定版工具链
-
-构建命令：
+## 6.1）快速验证
 
 ```bash
 npm install
-npm run build:native
-./node_modules/.bin/tsc -p tsconfig.json
-```
-
-运行示例：
-
-```bash
-node dist/app.js
-```
-
-运行前请先修改 `src/app.ts` 中的固定配置项。
-
-## 8）使用 Google WebRTC 工具验证
+npm run build
 
-1. 启动服务：`node dist/app.js`
-2. 复制控制台打印的 `urls`、`username`、`credential`
-3. 打开 Google Trickle ICE 页面，填入 ICE Server
-4. 执行采集并确认出现 relay candidate
-
-## 9）发布到 npm
-
-```bash
-npm login
-npm publish --access public
+TURN_REALM=turn.example.com TURN_PUBLIC_IP=1.2.3.4 TURN_USERNAME=alice TURN_PASSWORD=alice-pass TTURN_DISABLE_CREDENTIAL_EXPIRY=1 node dist/cli.js credential
 ```
 
-说明：
-
-- npm 包名必须小写，所以发布名为 `tturn`。
-- 生产环境建议按平台预编译并发布对应 `.node` 二进制文件。
+返回 JSON 中应保持 `username = "alice"`、`credential = "alice-pass"`。
+
+## 7）源码构建
+
+环境要求：
+
+- Node.js >= 18
+- Rust 稳定版工具链
+
+构建命令：
+
+```bash
+npm install
+npm run build:native
+./node_modules/.bin/tsc -p tsconfig.json
+```
+
+运行示例：
+
+```bash
+node dist/app.js
+```
+
+运行前请先修改 `src/app.ts` 中的固定配置项。
+
+## 8）使用 Google WebRTC 工具验证
+
+1. 启动服务：`node dist/app.js`
+2. 复制控制台打印的 `urls`、`username`、`credential`
+3. 打开 Google Trickle ICE 页面，填入 ICE Server
+4. 执行采集并确认出现 relay candidate
+
+## 9）发布到 npm
+
+```bash
+npm login
+npm publish --access public
+```
+
+说明：
+
+- npm 包名必须小写，所以发布名为 `tturn`。
+- 生产环境建议按平台预编译并发布对应 `.node` 二进制文件。

package/dist/app.js

@@ -3,20 +3,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const index_1 = require("./index");
 const APP_CONFIG = {
     realm: "turn.example.com",
-    authSecret: "replace-with-your-secret",
-    publicIp: "1.2.3.4",
-    listenPort: 3478,
-    ttlSec: 600
+    publicIp: "192.168.3.66",
+    listenPort: 22224,
+    username: "metadigiee",
+    password: "22222",
+    ttlSec: 600,
+    disableCredentialExpiry: true
 };
 async function main() {
     const service = new index_1.Tturn({
         realm: APP_CONFIG.realm,
         authSecret: APP_CONFIG.authSecret,
+        password: APP_CONFIG.password,
         publicIp: APP_CONFIG.publicIp,
-        listenPort: APP_CONFIG.listenPort
+        listenPort: APP_CONFIG.listenPort,
+        username: APP_CONFIG.username,
+        ttlSec: APP_CONFIG.ttlSec,
+        disableCredentialExpiry: APP_CONFIG.disableCredentialExpiry
     });
-    await service.start();
-    const ice = service.issueCredential({ ttlSec: APP_CONFIG.ttlSec, userId: "google-test" });
+    const ice = await service.start();
     console.log("[tturn] started.");
     console.log("[tturn] use this ICE server in Google WebRTC tool:");
     console.log(JSON.stringify(ice, null, 2));

package/dist/cli.js

@@ -5,27 +5,40 @@ const index_1 = require("./index");
 async function run() {
     const command = process.argv[2];
     if (command === "credential") {
-        const secret = mustGetEnv("TURN_SECRET");
         const realm = mustGetEnv("TURN_REALM");
-        const service = (0, index_1.createTurnService)({ realm, authSecret: secret, publicIp: process.env.TURN_PUBLIC_IP });
+        const authOptions = resolveAuthOptions();
+        const service = (0, index_1.createTurnService)({
+            realm,
+            authSecret: authOptions.authSecret,
+            password: authOptions.password,
+            publicIp: process.env.TURN_PUBLIC_IP,
+            disableCredentialExpiry: readBoolEnv("TTURN_DISABLE_CREDENTIAL_EXPIRY") ?? Boolean(authOptions.password)
+        });
         const ice = service.issueCredential({
             ttlSec: process.env.TTURN_TTL_SEC ? Number(process.env.TTURN_TTL_SEC) : 3600,
-            userId: process.env.TTURN_USER_ID
+            userId: process.env.TTURN_USER_ID,
+            username: readUsernameEnv()
         });
         process.stdout.write(`${JSON.stringify(ice, null, 2)}\n`);
         return;
     }
     if (command === "start") {
-        const secret = mustGetEnv("TURN_SECRET");
         const realm = mustGetEnv("TURN_REALM");
+        const authOptions = resolveAuthOptions();
         const service = (0, index_1.createTurnService)({
             realm,
-            authSecret: secret,
+            authSecret: authOptions.authSecret,
+            password: authOptions.password,
             publicIp: process.env.TURN_PUBLIC_IP,
-            listenPort: process.env.TURN_PORT ? Number(process.env.TURN_PORT) : 3478
+            listenPort: process.env.TURN_PORT ? Number(process.env.TURN_PORT) : 3478,
+            ttlSec: process.env.TTURN_TTL_SEC ? Number(process.env.TTURN_TTL_SEC) : 3600,
+            username: readUsernameEnv(),
+            userId: process.env.TTURN_USER_ID,
+            disableCredentialExpiry: readBoolEnv("TTURN_DISABLE_CREDENTIAL_EXPIRY") ?? Boolean(authOptions.password)
         });
-        await service.start();
+        const ice = await service.start();
         process.stdout.write("tturn started\n");
+        process.stdout.write(`${JSON.stringify(ice, null, 2)}\n`);
         await waitForSignal();
         await service.stop();
         process.stdout.write("tturn stopped\n");
@@ -48,11 +61,33 @@ function printUsage() {
         "  tturn credential  # prints one ICE server credential JSON",
         "",
         "required env:",
-        "  TURN_REALM, TURN_SECRET",
+        "  TURN_REALM",
+        "  TURN_SECRET or TURN_PASSWORD",
         "optional env:",
-        "  TURN_PUBLIC_IP, TURN_PORT, TTURN_TTL_SEC, TTURN_USER_ID"
+        "  TURN_PUBLIC_IP, TURN_PORT, TTURN_TTL_SEC, TTURN_USER_ID, TTURN_USERNAME (or TURN_USERNAME), TTURN_DISABLE_CREDENTIAL_EXPIRY"
     ].join("\n") + "\n");
 }
+function readUsernameEnv() {
+    return process.env.TTURN_USERNAME ?? process.env.TURN_USERNAME;
+}
+function resolveAuthOptions() {
+    const authSecret = process.env.TURN_SECRET;
+    const password = process.env.TURN_PASSWORD;
+    if (!authSecret && !password) {
+        throw new Error("Missing required env: TURN_SECRET or TURN_PASSWORD");
+    }
+    return {
+        authSecret: authSecret ?? "",
+        password
+    };
+}
+function readBoolEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        return undefined;
+    }
+    return value === "1" || value.toLowerCase() === "true";
+}
 function waitForSignal() {
     return new Promise((resolve) => {
         const keepAlive = setInterval(() => {

package/dist/credentials.js

@@ -6,8 +6,18 @@ const DEFAULT_TTL_SEC = 3600;
 function createTurnCredential(authSecret, options = {}) {
     const ttlSec = Math.max(60, options.ttlSec ?? DEFAULT_TTL_SEC);
     const expiresAt = Math.floor(Date.now() / 1000) + ttlSec;
-    const userPrefix = options.userId ? `${options.userId}:` : "";
-    const username = `${userPrefix}${expiresAt}`;
+    const username = resolveUsername(options, expiresAt);
     const password = (0, node_crypto_1.createHmac)("sha1", authSecret).update(username).digest("base64");
     return { username, password, ttlSec, expiresAt };
 }
+function resolveUsername(options, expiresAt) {
+    if (options.username) {
+        const tail = options.username.split(":").pop();
+        if (tail && /^\d+$/.test(tail) && Number(tail) > Math.floor(Date.now() / 1000)) {
+            return options.username;
+        }
+        return `${options.username}:${expiresAt}`;
+    }
+    const userPrefix = options.userId ? `${options.userId}:` : "";
+    return `${userPrefix}${expiresAt}`;
+}

package/dist/native-binding.d.ts

@@ -8,7 +8,7 @@ interface NativeCredential {
 interface NativeTurnService {
     start(detached?: boolean): void;
     stop(): void;
-    issueCredential(ttlSec?: number, userId?: string): NativeCredential;
+    issueCredential(ttlSec?: number, userId?: string, username?: string): NativeCredential;
     getIceUrls(): string[];
     health(): {
         running: boolean;

package/dist/native-binding.js

@@ -6,9 +6,9 @@ const node_path_1 = require("node:path");
 function loadNativeBinding() {
     const root = (0, node_path_1.join)(__dirname, "..");
     const candidates = [
+        (0, node_path_1.join)(root, binaryName()),
         (0, node_path_1.join)(root, "index.node"),
-        (0, node_path_1.join)(root, "native", "index.node"),
-        (0, node_path_1.join)(root, binaryName())
+        (0, node_path_1.join)(root, "native", "index.node")
     ];
     for (const filePath of candidates) {
         if (!(0, node_fs_1.existsSync)(filePath)) {

package/dist/service.d.ts

@@ -1,8 +1,9 @@
 import { IceServer, IssueCredentialOptions, StartOptions, TurnServiceOptions } from "./types";
 export declare class TurnService {
     private readonly native;
+    private readonly defaultIssueOptions;
     constructor(options: TurnServiceOptions);
-    start(startOptions?: StartOptions): Promise<void>;
+    start(startOptions?: StartOptions): Promise<IceServer>;
     stop(): Promise<void>;
     issueCredential(issueOptions?: IssueCredentialOptions): IceServer;
     getIceUrls(): string[];

package/dist/service.js

@@ -4,23 +4,36 @@ exports.TurnService = void 0;
 const native_binding_1 = require("./native-binding");
 class TurnService {
     constructor(options) {
+        const { username, password, userId, ttlSec, ...nativeOptions } = options;
+        const disableCredentialExpiry = options.disableCredentialExpiry ?? Boolean(password);
         this.native = new native_binding_1.binding.NativeTurnService({
-            ...options,
-            listenPort: options.listenPort ?? 3478,
-            minPort: options.minPort ?? 49152,
-            maxPort: options.maxPort ?? 65535,
-            publicIp: options.publicIp ?? options.realm,
-            listeningIp: options.listeningIp ?? "0.0.0.0"
+            ...nativeOptions,
+            authSecret: nativeOptions.authSecret ?? "",
+            listenPort: nativeOptions.listenPort ?? 3478,
+            minPort: nativeOptions.minPort ?? 49152,
+            maxPort: nativeOptions.maxPort ?? 65535,
+            publicIp: nativeOptions.publicIp ?? nativeOptions.realm,
+            listeningIp: nativeOptions.listeningIp ?? "0.0.0.0",
+            username,
+            password,
+            disableCredentialExpiry
         });
+        this.defaultIssueOptions = {
+            ttlSec,
+            username,
+            userId
+        };
     }
     async start(startOptions = {}) {
         this.native.start(Boolean(startOptions.detached));
+        return this.issueCredential();
     }
     async stop() {
         this.native.stop();
     }
     issueCredential(issueOptions = {}) {
-        const out = this.native.issueCredential(issueOptions.ttlSec, issueOptions.userId);
+        const merged = { ...this.defaultIssueOptions, ...issueOptions };
+        const out = this.native.issueCredential(merged.ttlSec, merged.userId, merged.username);
         return {
             urls: this.native.getIceUrls(),
             username: out.username,

package/dist/types.d.ts

@@ -11,16 +11,22 @@ export interface IceServer {
 }
 export interface IssueCredentialOptions {
     ttlSec?: number;
+    username?: string;
     userId?: string;
 }
 export interface TurnServiceOptions {
     realm: string;
-    authSecret: string;
+    authSecret?: string;
     listenPort?: number;
     minPort?: number;
     maxPort?: number;
     publicIp?: string;
     listeningIp?: string;
+    username?: string;
+    password?: string;
+    userId?: string;
+    ttlSec?: number;
+    disableCredentialExpiry?: boolean;
 }
 export interface StartOptions {
     detached?: boolean;

package/package.json

@@ -1,50 +1,50 @@
-{
-  "name": "tturn",
-  "version": "0.1.0",
-  "description": "High-performance TURN server for Node.js with embedded native core",
-  "keywords": [
-    "turn",
-    "webrtc",
-    "napi",
-    "rust",
-    "stun",
-    "relay"
-  ],
-  "license": "MIT",
-  "author": "",
-  "homepage": "https://github.com/txzh007/ttrun",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/txzh007/ttrun.git"
-  },
-  "bugs": {
-    "url": "https://github.com/txzh007/ttrun/issues"
-  },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "tturn": "dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "index.node",
-    "tturn.*.node",
-    "README.md",
-    "README.en.md",
-    "README.zh-CN.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "build:native": "node scripts/build-native.js",
-    "build": "npm run build:native && tsc -p tsconfig.json",
-    "build:ts": "tsc -p tsconfig.json"
-  },
-  "dependencies": {},
-  "devDependencies": {
-    "@types/node": "^22.13.10",
-    "typescript": "^5.8.2"
-  }
-}
+{
+  "name": "tturn",
+  "version": "0.1.2",
+  "description": "High-performance TURN server for Node.js with embedded native core",
+  "keywords": [
+    "turn",
+    "webrtc",
+    "napi",
+    "rust",
+    "stun",
+    "relay"
+  ],
+  "license": "MIT",
+  "author": "",
+  "homepage": "https://github.com/txzh007/ttrun",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/txzh007/ttrun.git"
+  },
+  "bugs": {
+    "url": "https://github.com/txzh007/ttrun/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "tturn": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "index.node",
+    "tturn.*.node",
+    "README.md",
+    "README.en.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build:native": "node scripts/build-native.js",
+    "build": "npm run build:native && tsc -p tsconfig.json",
+    "build:ts": "tsc -p tsconfig.json"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2"
+  }
+}