nexus
适配器Node IPC

认证

为 Node IPC 连接配置共享密钥预认证。

Node IPC 提供适配器专属的共享密钥预认证。所有适配器通用的 Core 授权策略另见授权。

共享密钥预认证的作用

共享密钥预认证在套接字交给 Nexus Core 之前执行。

客户端发送认证消息,守护进程验证其中的认证令牌。令牌正确时,双方继续进行 Nexus 握手。

消息格式:

{ "type": "nexus-ipc-auth", "version": 1, "token": "..." }

成功响应:

{ "type": "nexus-ipc-auth-ok" }

认证消息使用以换行符分隔的 JSON 格式。收到不完整的套接字数据块时,实现会先缓存,直到收到换行符再解析。

适配器会先校验请求和响应的结构。请求必须包含上面的精确 type、version 和字符串 token;允许附加字段。结构合法但 token 不匹配属于认证失败,不属于协议格式错误。

配置认证令牌

守护进程:

usingNodeIpcDaemon({
  appId: "example-app",
  authToken: process.env.NEXUS_IPC_TOKEN,
});

客户端:

usingNodeIpcClient({
  appId: "example-app",
  authToken: process.env.NEXUS_IPC_TOKEN,
});

认证令牌不能为空。如果守护进程要求认证,而客户端发送了错误的令牌,连接会失败并返回 E_IPC_AUTH_FAILED。

超时和限制

认证交互有超时限制,对端一直不响应时不会无限等待。

单行认证消息也有大小上限。消息过大或格式错误时会失败,不会无限缓存。

常见失败:

  • 认证令牌错误:E_IPC_AUTH_FAILED
  • 超时前未收到认证消息:E_IPC_AUTH_FAILED
  • JSON 或协议消息格式错误:E_IPC_PROTOCOL_ERROR
  • 认证消息行过大:E_IPC_PROTOCOL_ERROR

ConnectionMeta

预认证完成后,Node IPC 向 Nexus Core 提供连接元数据:

{
  observed: {
    socket: { kind: "path", path: "..." },
    authenticated: true,
    authMethod: "shared-secret"
  }
}

未配置共享密钥时,observed.authenticated 为 false,observed.authMethod 为 "none"。

Core 策略可以据此使用适配器的预认证结果。

与 Core 授权策略组合

使用 canConnect 要求预认证成功,使用 canCall 限制服务操作。配置守护进程时,可以这样组合:

import { composeNexusConfig, nexus } from "@nexus-js/core";
import { usingNodeIpcDaemon } from "@nexus-js/node-ipc";

nexus.configure(
  composeNexusConfig([
    usingNodeIpcDaemon({
      appId: "example-app",
      authToken: process.env.NEXUS_IPC_TOKEN,
      configure: false,
    }),
    {
      policy: {
        canConnect({ connection }) {
          return connection.observed.authenticated === true;
        },
        canCall({ serviceName, operation }) {
          return serviceName === "example:admin" && operation === "APPLY";
        },
      },
    },
  ]),
);

canConnect、canCall、服务级策略和元数据信任边界见授权。

预认证的能力边界

共享密钥预认证只能证明对端持有配置的认证令牌。

它不能证明:

  • 对端进程运行的是哪个可执行文件
  • 操作系统用户 ID
  • 操作系统用户组 ID
  • 进程 ID 的真实性
  • 用户意图

除非应用另外验证这些声明,否则不能把自行声明的 pid 或身份标签作为安全边界。

在 GitHub 上编辑此页