@zuoyehaoduoa/wire 0.1.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@zuoyehaoduoa/wire",
+  "version": "0.1.0",
+  "description": "Shared message wire types and Zod schemas for codex-deck clients and services",
+  "author": "Kirill Dubovitskiy",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/asfsdsf/codex-deck/tree/main/wire",
+  "bugs": "https://github.com/asfsdsf/codex-deck/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asfsdsf/codex-deck.git",
+    "directory": "wire"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "shx rm -rf dist && pnpm exec tsc --noEmit && pnpm exec pkgroll",
+    "test": "$npm_execpath run build && vitest run",
+    "prepublishOnly": "$npm_execpath run build && $npm_execpath run test",
+    "release": "pnpm exec release-it"
+  },
+  "dependencies": {
+    "@paralleldrive/cuid2": "^2.2.2",
+    "@serenity-kit/opaque": "1.1.0",
+    "tweetnacl": "^1.0.3",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": ">=20",
+    "pkgroll": "^2.14.2",
+    "release-it": "^19.0.6",
+    "shx": "^0.3.3",
+    "typescript": "5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "packageManager": "pnpm@10.32.1"
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./messages";
+export * from "./sessionProtocol";
+export * from "./remote-crypto";
+export * from "./remote-protocol";
+export * from "./remote-auth-errors";

package/src/messageMeta.ts

@@ -0,0 +1,24 @@
+import * as z from "zod";
+
+export const MessageMetaSchema = z.object({
+  sentFrom: z.string().optional(),
+  permissionMode: z
+    .enum([
+      "default",
+      "acceptEdits",
+      "bypassPermissions",
+      "plan",
+      "read-only",
+      "safe-yolo",
+      "yolo",
+    ])
+    .optional(),
+  model: z.string().nullable().optional(),
+  fallbackModel: z.string().nullable().optional(),
+  customSystemPrompt: z.string().nullable().optional(),
+  appendSystemPrompt: z.string().nullable().optional(),
+  allowedTools: z.array(z.string()).nullable().optional(),
+  disallowedTools: z.array(z.string()).nullable().optional(),
+  displayText: z.string().optional(),
+});
+export type MessageMeta = z.infer<typeof MessageMetaSchema>;

package/src/messages.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from "vitest";
+import {
+  CoreUpdateContainerSchema,
+  MessageContentSchema,
+  SessionProtocolMessageSchema,
+  UpdateMachineBodySchema,
+  UpdateNewMessageBodySchema,
+  UpdateSessionBodySchema,
+} from "./messages";
+
+describe("shared wire message schemas", () => {
+  it("parses a new-message update", () => {
+    const parsed = UpdateNewMessageBodySchema.safeParse({
+      t: "new-message",
+      sid: "session-1",
+      message: {
+        id: "msg-1",
+        seq: 10,
+        localId: null,
+        content: {
+          t: "encrypted",
+          c: "ZmFrZS1lbmNyeXB0ZWQ=",
+        },
+        createdAt: 123,
+        updatedAt: 124,
+      },
+    });
+
+    expect(parsed.success).toBe(true);
+  });
+
+  it("parses update-session with nullable agentState value", () => {
+    const parsed = UpdateSessionBodySchema.safeParse({
+      t: "update-session",
+      id: "session-1",
+      metadata: {
+        version: 2,
+        value: "abc",
+      },
+      agentState: {
+        version: 3,
+        value: null,
+      },
+    });
+
+    expect(parsed.success).toBe(true);
+  });
+
+  it("parses update-machine with optional activity fields", () => {
+    const parsed = UpdateMachineBodySchema.safeParse({
+      t: "update-machine",
+      machineId: "machine-1",
+      metadata: {
+        version: 1,
+        value: "abc",
+      },
+      daemonState: {
+        version: 2,
+        value: "def",
+      },
+      active: true,
+      activeAt: 12345,
+    });
+
+    expect(parsed.success).toBe(true);
+  });
+
+  it("parses container updates for all shared update variants", () => {
+    const examples = [
+      {
+        id: "upd-1",
+        seq: 1,
+        body: {
+          t: "new-message",
+          sid: "session-1",
+          message: {
+            id: "msg-1",
+            seq: 1,
+            localId: null,
+            content: { t: "encrypted", c: "x" },
+            createdAt: 1,
+            updatedAt: 1,
+          },
+        },
+        createdAt: 1,
+      },
+      {
+        id: "upd-2",
+        seq: 2,
+        body: {
+          t: "update-session",
+          id: "session-1",
+          metadata: null,
+          agentState: {
+            version: 1,
+            value: null,
+          },
+        },
+        createdAt: 2,
+      },
+      {
+        id: "upd-3",
+        seq: 3,
+        body: {
+          t: "update-machine",
+          machineId: "machine-1",
+          metadata: null,
+          daemonState: null,
+        },
+        createdAt: 3,
+      },
+    ];
+
+    for (const sample of examples) {
+      expect(CoreUpdateContainerSchema.safeParse(sample).success).toBe(true);
+    }
+  });
+
+  it("parses modern session protocol wrapper payload", () => {
+    const parsed = SessionProtocolMessageSchema.safeParse({
+      role: "session",
+      content: {
+        id: "msg-1",
+        time: 1000,
+        role: "agent",
+        turn: "turn-1",
+        ev: {
+          t: "text",
+          text: "hello",
+        },
+      },
+      meta: {
+        sentFrom: "cli",
+      },
+    });
+
+    expect(parsed.success).toBe(true);
+  });
+
+  it("parses top-level message content only for session protocol payloads", () => {
+    const modernParsed = MessageContentSchema.safeParse({
+      role: "session",
+      content: {
+        id: "msg-2",
+        time: 2000,
+        role: "agent",
+        turn: "turn-2",
+        ev: {
+          t: "text",
+          text: "hello from session protocol",
+        },
+      },
+    });
+    const legacyParsed = MessageContentSchema.safeParse({
+      role: "user",
+      content: {
+        type: "text",
+        text: "hello from user",
+      },
+    });
+
+    expect(modernParsed.success).toBe(true);
+    expect(legacyParsed.success).toBe(false);
+  });
+});

package/src/messages.ts

@@ -0,0 +1,97 @@
+import * as z from "zod";
+import { sessionEnvelopeSchema } from "./sessionProtocol";
+import { MessageMetaSchema, type MessageMeta } from "./messageMeta";
+
+export const SessionMessageContentSchema = z.object({
+  c: z.string(),
+  t: z.literal("encrypted"),
+});
+export type SessionMessageContent = z.infer<typeof SessionMessageContentSchema>;
+
+export const SessionMessageSchema = z.object({
+  id: z.string(),
+  seq: z.number(),
+  localId: z.string().nullish(),
+  content: SessionMessageContentSchema,
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});
+export type SessionMessage = z.infer<typeof SessionMessageSchema>;
+export { MessageMetaSchema };
+export type { MessageMeta };
+
+export const SessionProtocolMessageSchema = z.object({
+  role: z.literal("session"),
+  content: sessionEnvelopeSchema,
+  meta: MessageMetaSchema.optional(),
+});
+export type SessionProtocolMessage = z.infer<
+  typeof SessionProtocolMessageSchema
+>;
+
+export const MessageContentSchema = SessionProtocolMessageSchema;
+export type MessageContent = z.infer<typeof MessageContentSchema>;
+
+export const VersionedEncryptedValueSchema = z.object({
+  version: z.number(),
+  value: z.string(),
+});
+export type VersionedEncryptedValue = z.infer<
+  typeof VersionedEncryptedValueSchema
+>;
+
+export const VersionedNullableEncryptedValueSchema = z.object({
+  version: z.number(),
+  value: z.string().nullable(),
+});
+export type VersionedNullableEncryptedValue = z.infer<
+  typeof VersionedNullableEncryptedValueSchema
+>;
+
+export const UpdateNewMessageBodySchema = z.object({
+  t: z.literal("new-message"),
+  sid: z.string(),
+  message: SessionMessageSchema,
+});
+export type UpdateNewMessageBody = z.infer<typeof UpdateNewMessageBodySchema>;
+
+export const UpdateSessionBodySchema = z.object({
+  t: z.literal("update-session"),
+  id: z.string(),
+  metadata: VersionedEncryptedValueSchema.nullish(),
+  agentState: VersionedNullableEncryptedValueSchema.nullish(),
+});
+export type UpdateSessionBody = z.infer<typeof UpdateSessionBodySchema>;
+
+export const VersionedMachineEncryptedValueSchema = z.object({
+  version: z.number(),
+  value: z.string(),
+});
+export type VersionedMachineEncryptedValue = z.infer<
+  typeof VersionedMachineEncryptedValueSchema
+>;
+
+export const UpdateMachineBodySchema = z.object({
+  t: z.literal("update-machine"),
+  machineId: z.string(),
+  metadata: VersionedMachineEncryptedValueSchema.nullish(),
+  daemonState: VersionedMachineEncryptedValueSchema.nullish(),
+  active: z.boolean().optional(),
+  activeAt: z.number().optional(),
+});
+export type UpdateMachineBody = z.infer<typeof UpdateMachineBodySchema>;
+
+export const CoreUpdateBodySchema = z.discriminatedUnion("t", [
+  UpdateNewMessageBodySchema,
+  UpdateSessionBodySchema,
+  UpdateMachineBodySchema,
+]);
+export type CoreUpdateBody = z.infer<typeof CoreUpdateBodySchema>;
+
+export const CoreUpdateContainerSchema = z.object({
+  id: z.string(),
+  seq: z.number(),
+  body: CoreUpdateBodySchema,
+  createdAt: z.number(),
+});
+export type CoreUpdateContainer = z.infer<typeof CoreUpdateContainerSchema>;

package/src/remote-auth-errors.ts

@@ -0,0 +1,87 @@
+export const RemoteAuthErrorCode = {
+  accountNotFound: "remote_account_not_found",
+  accountMismatch: "remote_account_mismatch",
+  setupTokensMissing: "remote_setup_tokens_missing",
+  setupTokenInvalid: "remote_setup_token_invalid",
+  loginAlreadyBound: "remote_login_already_bound",
+  machineAlreadyBound: "remote_machine_already_bound",
+  invalidLogin: "remote_invalid_login",
+  invalidRegister: "remote_invalid_register",
+  invalidLoginState: "remote_invalid_login_state",
+  adminPasswordInvalid: "remote_admin_password_invalid",
+  authUpgradeRequired: "remote_auth_upgrade_required",
+} as const;
+
+export type RemoteAuthErrorCode =
+  (typeof RemoteAuthErrorCode)[keyof typeof RemoteAuthErrorCode];
+
+export type RemoteAuthHintContext = "cli" | "browser" | "admin";
+
+const REMOTE_AUTH_ERROR_CODE_SET = new Set<string>(
+  Object.values(RemoteAuthErrorCode),
+);
+
+export function isRemoteAuthErrorCode(
+  value: unknown,
+): value is RemoteAuthErrorCode {
+  return typeof value === "string" && REMOTE_AUTH_ERROR_CODE_SET.has(value);
+}
+
+export function getRemoteAuthHint(params: {
+  code?: string | null;
+  error?: string | null;
+  context: RemoteAuthHintContext;
+}): string {
+  const code = isRemoteAuthErrorCode(params.code) ? params.code : null;
+  if (code === RemoteAuthErrorCode.invalidLogin) {
+    if (params.context === "cli") {
+      return "Remote password is incorrect for this registered CLI account. Update --remote-password (or CODEXDECK_REMOTE_PASSWORD) to match the target server credentials.";
+    }
+    if (params.context === "admin") {
+      return "Admin password is incorrect.";
+    }
+    return "Incorrect password for this remote username. Use the same password configured on the target CLI.";
+  }
+  if (code === RemoteAuthErrorCode.accountNotFound) {
+    if (params.context === "cli") {
+      return "Remote account not found. Register this CLI first using a valid --remote-setup-token, --remote-username, and --remote-password.";
+    }
+    return "Remote account not found. Start the CLI first with --remote-setup-token, --remote-username, and --remote-password.";
+  }
+  if (code === RemoteAuthErrorCode.accountMismatch) {
+    return "This login is bound to a different machine. Use the credentials originally registered for this machine, or configure a different --remote-machine-id.";
+  }
+  if (code === RemoteAuthErrorCode.setupTokenInvalid) {
+    return "Setup token is invalid or disabled. Generate a valid setup token in the server admin page and retry.";
+  }
+  if (code === RemoteAuthErrorCode.setupTokensMissing) {
+    return "Remote server has no setup tokens configured. Add setup tokens in server admin before registering a CLI.";
+  }
+  if (code === RemoteAuthErrorCode.invalidLoginState) {
+    return "Remote login attempt expired or is no longer valid. Retry login.";
+  }
+  if (code === RemoteAuthErrorCode.invalidRegister) {
+    return "Remote registration attempt expired or is no longer valid. Retry CLI registration.";
+  }
+  if (
+    code === RemoteAuthErrorCode.loginAlreadyBound ||
+    code === RemoteAuthErrorCode.machineAlreadyBound
+  ) {
+    return "This remote login or machine is already bound to different credentials. Verify --remote-username, --remote-password, and --remote-machine-id.";
+  }
+  if (code === RemoteAuthErrorCode.authUpgradeRequired) {
+    return "Legacy remote auth is no longer supported. Re-register this CLI using the current codex-deck version.";
+  }
+  if (code === RemoteAuthErrorCode.adminPasswordInvalid) {
+    return "Admin password is incorrect.";
+  }
+
+  const fallback = params.error?.trim();
+  if (fallback) {
+    return fallback;
+  }
+  if (params.context === "admin") {
+    return "Remote admin login failed.";
+  }
+  return "Remote login failed.";
+}

package/src/remote-crypto.test.ts

@@ -0,0 +1,244 @@
+import { describe, expect, it } from "vitest";
+import {
+  createRemoteOpaqueRegistrationResponse,
+  createRemoteOpaqueServerSetup,
+  decodeBase64,
+  decryptRemotePayload,
+  deriveRemoteLoginHandle,
+  deriveRemoteRelayKeyFromExportKey,
+  encryptRemotePayload,
+  finishRemoteOpaqueLogin,
+  finishRemoteOpaqueRegistration,
+  finishRemoteOpaqueServerLogin,
+  generateRemoteRpcSigningKeyPair,
+  getRemoteOpaqueServerPublicKey,
+  signRemoteRpcResult,
+  startRemoteOpaqueLogin,
+  startRemoteOpaqueRegistration,
+  startRemoteOpaqueServerLogin,
+  verifyRemoteRpcResultSignature,
+} from "./remote-crypto";
+
+describe("remote-crypto", () => {
+  const username = "alice";
+  const password = "correct horse battery staple";
+  const realmId = "realm-a";
+
+  it("derives a stable opaque login handle", async () => {
+    const first = await deriveRemoteLoginHandle(username, realmId);
+    const second = await deriveRemoteLoginHandle(username, realmId);
+    expect(first).toBe(second);
+  });
+
+  it("completes opaque registration and login with a stable export key", async () => {
+    const serverSetup = await createRemoteOpaqueServerSetup();
+    const serverPublicKey = await getRemoteOpaqueServerPublicKey(serverSetup);
+    const loginHandle = await deriveRemoteLoginHandle(username, realmId);
+
+    const registrationStart = await startRemoteOpaqueRegistration(password);
+    const { registrationResponse } =
+      await createRemoteOpaqueRegistrationResponse({
+        serverSetup,
+        loginHandle,
+        registrationRequest: registrationStart.registrationRequest,
+      });
+    const registrationFinish = await finishRemoteOpaqueRegistration({
+      password,
+      clientRegistrationState: registrationStart.clientRegistrationState,
+      registrationResponse,
+      loginHandle,
+      realmId,
+      expectedServerPublicKey: serverPublicKey,
+    });
+
+    const loginStart = await startRemoteOpaqueLogin(password);
+    const loginResponse = await startRemoteOpaqueServerLogin({
+      serverSetup,
+      registrationRecord: registrationFinish.registrationRecord,
+      startLoginRequest: loginStart.startLoginRequest,
+      loginHandle,
+      realmId,
+    });
+    const loginFinish = await finishRemoteOpaqueLogin({
+      password,
+      clientLoginState: loginStart.clientLoginState,
+      loginResponse: loginResponse.loginResponse,
+      loginHandle,
+      realmId,
+      expectedServerPublicKey: serverPublicKey,
+    });
+
+    expect(loginFinish).not.toBeNull();
+    expect(loginFinish?.exportKey).toBe(registrationFinish.exportKey);
+    expect(Array.from(loginFinish?.relayKey || [])).toEqual(
+      Array.from(registrationFinish.relayKey),
+    );
+
+    const serverFinish = await finishRemoteOpaqueServerLogin({
+      serverLoginState: loginResponse.serverLoginState,
+      finishLoginRequest: loginFinish!.finishLoginRequest,
+      loginHandle,
+      realmId,
+    });
+    expect(serverFinish.sessionKey).toMatch(/\S+/);
+    expect(loginFinish?.sessionKey).toMatch(/\S+/);
+  });
+
+  it("rejects opaque login with the wrong password", async () => {
+    const serverSetup = await createRemoteOpaqueServerSetup();
+    const loginHandle = await deriveRemoteLoginHandle(username, realmId);
+
+    const registrationStart = await startRemoteOpaqueRegistration(password);
+    const { registrationResponse } =
+      await createRemoteOpaqueRegistrationResponse({
+        serverSetup,
+        loginHandle,
+        registrationRequest: registrationStart.registrationRequest,
+      });
+    const registrationFinish = await finishRemoteOpaqueRegistration({
+      password,
+      clientRegistrationState: registrationStart.clientRegistrationState,
+      registrationResponse,
+      loginHandle,
+      realmId,
+    });
+
+    const loginStart = await startRemoteOpaqueLogin("wrong password");
+    const loginResponse = await startRemoteOpaqueServerLogin({
+      serverSetup,
+      registrationRecord: registrationFinish.registrationRecord,
+      startLoginRequest: loginStart.startLoginRequest,
+      loginHandle,
+      realmId,
+    });
+    const loginFinish = await finishRemoteOpaqueLogin({
+      password: "wrong password",
+      clientLoginState: loginStart.clientLoginState,
+      loginResponse: loginResponse.loginResponse,
+      loginHandle,
+      realmId,
+    });
+
+    expect(loginFinish).toBeNull();
+  });
+
+  it("derives a stable relay key from an export key", async () => {
+    const serverSetup = await createRemoteOpaqueServerSetup();
+    const loginHandle = await deriveRemoteLoginHandle(username, realmId);
+
+    const registrationStart = await startRemoteOpaqueRegistration(password);
+    const { registrationResponse } =
+      await createRemoteOpaqueRegistrationResponse({
+        serverSetup,
+        loginHandle,
+        registrationRequest: registrationStart.registrationRequest,
+      });
+    const registrationFinish = await finishRemoteOpaqueRegistration({
+      password,
+      clientRegistrationState: registrationStart.clientRegistrationState,
+      registrationResponse,
+      loginHandle,
+      realmId,
+    });
+
+    const derived = await deriveRemoteRelayKeyFromExportKey(
+      registrationFinish.exportKey,
+    );
+    expect(Array.from(derived)).toEqual(
+      Array.from(registrationFinish.relayKey),
+    );
+  });
+
+  it("decodes opaque base64url export keys", async () => {
+    const serverSetup = await createRemoteOpaqueServerSetup();
+    const loginHandle = await deriveRemoteLoginHandle(username, realmId);
+
+    const registrationStart = await startRemoteOpaqueRegistration(password);
+    const { registrationResponse } =
+      await createRemoteOpaqueRegistrationResponse({
+        serverSetup,
+        loginHandle,
+        registrationRequest: registrationStart.registrationRequest,
+      });
+    const registrationFinish = await finishRemoteOpaqueRegistration({
+      password,
+      clientRegistrationState: registrationStart.clientRegistrationState,
+      registrationResponse,
+      loginHandle,
+      realmId,
+    });
+
+    expect(registrationFinish.exportKey).toMatch(/[-_]/);
+    expect(decodeBase64(registrationFinish.exportKey)).toHaveLength(64);
+  });
+
+  it("encrypts and decrypts relay payloads with an opaque-derived relay key", async () => {
+    const serverSetup = await createRemoteOpaqueServerSetup();
+    const loginHandle = await deriveRemoteLoginHandle(username, realmId);
+
+    const registrationStart = await startRemoteOpaqueRegistration(password);
+    const { registrationResponse } =
+      await createRemoteOpaqueRegistrationResponse({
+        serverSetup,
+        loginHandle,
+        registrationRequest: registrationStart.registrationRequest,
+      });
+    const registrationFinish = await finishRemoteOpaqueRegistration({
+      password,
+      clientRegistrationState: registrationStart.clientRegistrationState,
+      registrationResponse,
+      loginHandle,
+      realmId,
+    });
+
+    const encrypted = await encryptRemotePayload(registrationFinish.relayKey, {
+      requestId: "req-1",
+      body: {
+        path: "/api/sessions",
+        method: "GET",
+      },
+    });
+
+    const decrypted = await decryptRemotePayload<{
+      requestId: string;
+      body: { path: string; method: string };
+    }>(registrationFinish.relayKey, encrypted);
+
+    expect(decrypted).toEqual({
+      requestId: "req-1",
+      body: {
+        path: "/api/sessions",
+        method: "GET",
+      },
+    });
+  });
+
+  it("signs and verifies remote RPC result payloads", () => {
+    const keyPair = generateRemoteRpcSigningKeyPair();
+    const signature = signRemoteRpcResult({
+      machineId: "machine-a",
+      requestId: "req-1",
+      encryptedResult: "ciphertext",
+      secretKey: keyPair.secretKey,
+    });
+
+    expect(
+      verifyRemoteRpcResultSignature({
+        machineId: "machine-a",
+        requestId: "req-1",
+        encryptedResult: "ciphertext",
+        signature,
+        publicKey: keyPair.publicKey,
+      }),
+    ).toBe(true);
+    expect(
+      verifyRemoteRpcResultSignature({
+        machineId: "machine-a",
+        requestId: "req-1",
+        encryptedResult: "tampered",
+        signature,
+        publicKey: keyPair.publicKey,
+      }),
+    ).toBe(false);
+  });
+});