Transmate

A lightweight, passphrase-scoped cross-device clipboard for securely moving text and links between devices without creating an account.

一个轻量的跨设备文本暂存工具，无需注册账号，通过口令空间在手机、电脑和其他设备之间传递文本与链接。

Live Demo · English · 中文

English

Overview

Transmate was built for the small but frequent moment when a link, command, code snippet, or note needs to move from one device to another. Instead of sending content through a messaging account, users open the website, enter a shared passphrase, and access the same private temporary space.

Features

• Passphrase-protected spaces without a traditional account system
• Cross-device text, link, command, and code-snippet transfer
• Optional notes for explaining saved content
• Search across both content and notes
• Device, content-type, preset-date, and custom-date-range filters
• Server-side pagination with 20 records per page by default
• One-click copy and deletion
• Device-based limits for creating new spaces
• First-visit onboarding
• Administrative space, device, cleanup, and backup tools
• A separate link-processing utility loaded only when requested

Architecture

Transmate uses a small Node.js HTTP server, a vanilla HTML/CSS/JavaScript frontend, and SQLite through Node.js's built-in node:sqlite API. Nginx handles HTTPS and reverse proxying on the Debian server.

Passphrases are stored as salted PBKDF2 hashes. Successful authentication creates a signed, HTTP-only session cookie containing only the space identifier and expiration time. Every content query is restricted to the active session's space.

The first version used a JSON file. It was later migrated to SQLite with indexed server-side pagination and filtering. The migration tool verifies every space, passphrase hash, item, note, and device record before switching databases, while preserving the original JSON as a rollback snapshot.

How Codex & GPT-5.6 Were Used

Codex and GPT-5.6 were used as an engineering collaborator throughout the project rather than as a one-shot code generator.

• Requirements were turned into a staged architecture covering passphrase spaces, device limits, notes, search, pagination, administration, and deployment.
• Existing code was inspected before each iteration so new features followed the project's established structure.
• Codex helped implement the Node.js APIs, browser interactions, responsive UI, SQLite storage layer, migration verifier, and automated tests.
• GPT-5.6 helped reason through security boundaries, space isolation, PBKDF2 authentication, signed sessions, deployment rollback, and data-preserving migration steps.
• Automated tests were created for pagination, search, date filtering, administrative APIs, JSON-to-SQLite migration, and cross-space isolation.
• Codex assisted with Debian deployment, Nginx, HTTPS certificates, release directories, systemd services, backups, and production verification.
• The human developer reviewed the design choices, approved server changes, controlled credentials, and made the final product decisions.

No private keys, production environment variables, passphrases, or user data are committed to the repository.

Technology

• JavaScript
• Node.js 24+
• Node.js node:sqlite
• SQLite
• HTML and CSS
• Nginx
• Debian
• systemd
• Let's Encrypt HTTPS

Run Locally

Requirements:

Node.js 24 or newer

Start the application:

npm install
npm start

Open:

http://localhost:3000

Configuration

Copy the example configuration:

cp .env.example .env

Important options:

PORT=3000
HOST=0.0.0.0
DATA_FILE=./data/transmate.json
DATABASE_FILE=./data/transmate.sqlite
SESSION_DAYS=7
MAX_SPACES_PER_DEVICE=3
MAX_ITEM_BYTES=200000
PASSPHRASE_MIN_LENGTH=6
ADMIN_PASSPHRASE=
SESSION_SECRET=

DATA_FILE is the legacy JSON import source. New data is stored in DATABASE_FILE.

Tests

npm test

The test suite covers SQLite migration, duplicate-import prevention, pagination, search, date filtering, administrative APIs, backups, and space isolation.

JSON to SQLite Migration

Stop the application and keep a backup of the original JSON before migrating:

npm run migrate:sqlite -- \
  --json ./data/transmate.json \
  --database ./data/transmate.sqlite

The command refuses to overwrite an existing SQLite file and verifies migrated records before reporting success.

Data and Security Notes

• Passphrases are stored as salted PBKDF2 hashes, not plaintext.
• Saved text and notes are not application-level encrypted and must be protected through filesystem permissions and backups.
• SQLite, JSON backups, .env, session secrets, and private keys are ignored by Git.
• The administrative backup endpoint exports a portable JSON snapshot.
• The device creation limit is lightweight abuse prevention, not a replacement for CAPTCHA or stronger public-service rate limiting.

中文

项目简介

Transmate 用于解决一个常见的小问题：把链接、命令、代码片段或临时文字从一台设备快速传到另一台设备。用户不需要注册账号，只需在不同设备上输入同一个口令，就能进入对应的私人暂存空间。

主要功能

• 无账号的口令空间
• 跨设备传输文字、链接、命令和代码片段
• 为每条内容添加可选备注
• 同时搜索正文和备注
• 按设备、类型、预设时间和自定义日期范围筛选
• 服务端分页，默认每页只加载 20 条
• 一键复制和删除
• 按设备限制新建口令空间数量
• 首次访问新手引导
• 空间、设备、清理和备份管理后台
• 仅在点击后加载的独立链接处理工具

技术架构

Transmate 使用轻量 Node.js HTTP 服务端、原生 HTML/CSS/JavaScript 前端，以及 Node.js 内置的 node:sqlite API。Debian 服务器通过 Nginx 提供 HTTPS 和反向代理。

口令使用随机盐和 PBKDF2 哈希保存。验证成功后，服务器签发只包含空间 ID 和有效期的 HTTP-only 会话 Cookie。所有内容查询都会在服务端限制到当前会话对应的空间，避免跨空间数据泄露。

项目早期使用 JSON 文件保存数据，之后迁移到带索引、分页和筛选能力的 SQLite。迁移工具会逐条核对空间、口令哈希、正文、备注和设备记录，全部一致后才允许切换，同时保留原 JSON 作为回滚快照。

Codex 与 GPT-5.6 的使用方式

Codex 和 GPT-5.6 在这个项目中承担的是持续协作的工程伙伴角色，而不是一次性生成整套代码。

• 将需求拆分为口令空间、设备限制、备注、搜索、分页、后台管理和部署等可验证阶段。
• 每次迭代前先阅读已有代码，确保新功能延续项目原有结构。
• 协助实现 Node.js API、浏览器交互、响应式界面、SQLite 数据层、迁移校验器和自动化测试。
• 协助分析空间隔离、PBKDF2 口令验证、签名会话、部署回滚和数据迁移的安全边界。
• 编写分页、搜索、日期筛选、后台接口、JSON 到 SQLite 迁移和跨空间隔离测试。
• 协助完成 Debian 部署、Nginx、HTTPS、systemd、release 目录、备份和线上验证。
• 人类开发者负责审查方案、批准服务器操作、管理凭据，并作出最终产品决策。

仓库不会提交私钥、生产环境变量、口令或用户数据。

技术栈

• JavaScript
• Node.js 24+
• Node.js node:sqlite
• SQLite
• HTML 和 CSS
• Nginx
• Debian
• systemd
• Let's Encrypt HTTPS

本地运行

需要 Node.js 24 或更高版本：

npm install
npm start

访问：

http://localhost:3000

配置

cp .env.example .env

PORT=3000
HOST=0.0.0.0
DATA_FILE=./data/transmate.json
DATABASE_FILE=./data/transmate.sqlite
SESSION_DAYS=7
MAX_SPACES_PER_DEVICE=3
MAX_ITEM_BYTES=200000
PASSPHRASE_MIN_LENGTH=6
ADMIN_PASSPHRASE=
SESSION_SECRET=

DATA_FILE 是旧 JSON 的导入来源，新数据保存在 DATABASE_FILE。

自动测试

npm test

测试覆盖 SQLite 迁移、防止重复导入、分页、搜索、日期筛选、后台接口、备份和空间隔离。

从 JSON 迁移到 SQLite

迁移前应停止网站并备份原 JSON：

npm run migrate:sqlite -- \
  --json ./data/transmate.json \
  --database ./data/transmate.sqlite

迁移命令不会覆盖已有 SQLite 文件，并会在成功前逐条核对迁移数据。

数据与安全说明

• 口令以带盐 PBKDF2 哈希保存，不会明文存储。
• 暂存正文和备注没有进行应用层加密，需要通过文件权限和备份管理保护。
• SQLite、JSON 备份、.env、会话密钥和私钥都已加入 Git 忽略列表。
• 管理后台仍可导出便于迁移和恢复的 JSON 备份。
• 设备新建限制属于轻量防滥用措施，面向大规模公开服务时仍建议增加验证码或更严格的限流。