dsh-mizar 0.0.0-stage → 0.8.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShirazuNagisa
+
+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.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# DSH-Mizar 插件
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+用手机看 DSH Agent 干活，也能给它发消息、回答审批。
+
+这个仓库是 **Mac 侧插件**（DSH 的一个 Cordis 插件）。另外两个仓库：
+
+| | |
+|---|---|
+| **DSH-Mizar-iOS** | 手机 App（iOS / iPadOS） |
+| **DSH-Mizar-Relay** | 中继服务器，让手机从任何网络连上你的 Mac |
+
+## 一、装插件
+
+插件在 npm 上叫 **`dsh-mizar`**。命令行和图形界面两种装法，装完都要**重启 DSH** ——
+插件只在启动时加载，不重启等于没装。
+
+### 方式 A：图形界面（不想开终端就用这个）
+
+1. 打开 DSH，左侧栏点 **插件（Plugins）**
+2. 安装输入框里填 **`dsh-mizar`**，点安装
+3. 重启 DSH
+
+安装框同时接受 **npm 包名**（`dsh-mizar`）、**GitHub 地址**（`ShirazuNagisa/DSH-Mizar`）、
+**本地 `.tgz`** 或**目录路径**；装之前它会先把包名、版本、描述报给你确认。
+
+### 方式 B：命令行
+
+```sh
+dsh plugin --profile desktop add dsh-mizar          # npm 正式版
+dsh plugin --profile desktop add dsh-mizar@0.8.2    # 锁定版本
+```
+
+尝鲜（还没发版的提交）用 GitHub 直装：
+
+```sh
+dsh plugin --profile desktop add ShirazuNagisa/DSH-Mizar
+```
+
+离线 / 内网就传一个 `.tgz` 过去：
+
+```sh
+dsh plugin --profile desktop add /path/to/dsh-mizar-0.8.2.tgz
+```
+
+重启后侧边栏会出现 **DSH-Mizar** 面板。
+
+### 版本必须与 DSH 对齐
+
+DSH 会**精确比对**插件声明的 `@deepseek-ai/dsh-*` 与运行时版本，不匹配时安装会被拒绝：
+
+```
+Plugin dsh-mizar@0.8.2 is incompatible with dsh 0.2.1-rc.2
+```
+
+- 正常做法：升级到匹配的插件版本（DSH 每个 rc 发布后，插件跟一个 `+0.0.1`）；
+- 临时跑起来（**有风险**，只在确认没有 API 变更时用）：
+  ```sh
+  dsh plugin --profile desktop allow-version dsh-mizar@0.8.2 --dsh-version 0.2.1-rc.2 --accept-risk
+  ```
+
+## 二、配对
+
+1. Mac 上打开 DSH，点侧边栏的 **DSH-Mizar**
+2. 面板里会出现二维码
+3. 手机装好 App 后扫码
+
+**没有别的步骤。** 不用填 token，不用填地址，不用改文件。
+
+## 三、插件做什么
+
+- 把会话列表、对话正文、用量、审批和提问转给手机
+- 手机可以发消息、打断正在跑的 turn、回答审批和提问、切换模型与权限
+- 推送（审批 / 提问 / 跑完）经中继转给 Apple
+- 手机和 Mac 在同一个 Wi-Fi 时也可以直连，二维码里两条路都带着
+
+### 对话只传总结
+
+一页历史里只保留这些：你的提问、每一轮的 `turn/start` 和 `turn/end`、每个 `step/start`
+（只用来数「几步」），以及**每一轮里模型最后那条有正文的消息**。
+
+逐步叙述、工具调用与结果、流式过程，以及**还没结束的那一轮的中间回复**，一律不发。
+手机上那两行状态 —— 「已完成，用时 xx」和「深度求索中，用时 xx」—— 都不能展开，
+下面直接就是这一轮的总结。全量历史经中继是服务器上最大的一块流量，这是为了把它压下来。
+
+分页切点取自 `session/follow` 首帧的 `cursor`（DSH 自己对 `throughSeq` 的定义）。
+用 `session/projections` 的 `asOfSeq` 会滞后于日志头，刚发出的那一轮就不在页里 ——
+手机上表现为「AI 明明在干活，却没有正在工作的提示」。
+
+## 四、通知
+
+三种情况手机会收到推送，插件通过中继发给 Apple：
+
+- Agent 卡在**权限审批**上，等你点头
+- Agent 卡在**提问**上，等你回答
+- 某个会话**跑完了**（跑挂/中断了会说挂掉，不会谎报完成）
+
+**一轮结束不会立刻推。** DSH 里一个指令常常连着跑好几个 turn，每个 turn 都推一次等于一个
+指令三条通知 —— 所以插件会等这个会话安静 15 秒才发。正在看着 App 的时候什么都不发。
+
+推送要 Apple 的签名密钥，密钥只能放在服务器上（放在插件里就等于公开）。**用官方中继
+什么都不用做**；自建中继需要配 `apns`，见 [relay-deployment.md 第 10 节](docs/relay-deployment.md)。
+
+## 五、开发
+
+```sh
+npm install                 # 依赖（npm cache 建议指到本地：npm_config_cache=$PWD/.devcache/npm）
+npm test                    # 全部测试
+npm run typecheck
+npm run build               # tsc + 浏览器半边；lib/ 是提交进仓库的，必须与全新构建一致
+```
+
+`lib/` **故意提交进仓库**：`dsh plugin add` 装的是 git 检出，没有构建步骤，缺了 `lib/`
+等于插件装不上。所以改完 `src/` 一定要 `npm run build` 再提交。
+
+跑一个真的开发实例（用仓库内的 `.devhome`，不碰你 `~/.dsh` 的正式配置）：
+
+```sh
+node scripts/dev.mjs install     # 构建并装进 mizar-dev profile
+node scripts/dev.mjs boot        # 起一个真 DSH；日志 .devstate/dev.log
+node scripts/dev.mjs stop
+```
+
+对着它跑一次真实链路的冒烟测试（会打印配对码）：
+
+```sh
+MIZAR_CODE=XXXX-XXXX node scripts/smoke-listener.mjs
+```
+
+**开发实例不要连中继。** `.devhome` 是从正式配置里拷出来的，会拿到同一个中继房间号，
+两边一抢就会把正式那条隧道踢掉 —— `.devhome/profiles/mizar-dev/cordis.patch.yml` 里
+已经写了 `relay: enabled: false`。
+
+归档：`archive/full-message-transport/` 是 0.7.2 之前那套「全量传输」的实现，**不参与
+编译**，留着以便以后要用（见该目录的 README）。
+
+## 常见问题
+
+**手机连不上。**
+面板顶部会写原因。默认走中继，只要 Mac 和手机都能上网就行，不需要在同一个 Wi-Fi。
+
+**面板里没有二维码。**
+重启 DSH。装完不重启，插件不会加载。
+
+**想改成局域网直连。**
+默认是「有中继就走中继」。二维码里同时带直连地址，App 会先试直连、失败再走中继。
+
+**插件版本对不对。**
+DSH 启动日志里有 `[mizar] dsh-mizar <版本号> · state: … · devices: N live` 这一行。
+
+**收不到通知。**
+按顺序查：App 里「设置 → 通知」有没有允许；插件日志里有没有 `push: registered …`
+（说明手机把推送令牌交上来了）；中继上 `curl localhost:8787/healthz` 的
+`pushDevices` 是不是大于 0。三条都对还是没有，看中继日志里 Apple 回的是什么 ——
+`BadDeviceToken` 基本就是环境选错了。
+
+---
+
+协议、架构决策、自建中继：[docs/](docs/)

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# dsh-mizar bundle patch.
+#
+# Inserts the Mizar host row into the profile tree. The row resolves from the
+# profile's own node_modules (this package is installed as a profile
+# dependency), so no installation-anchor package is required.
+#
+# Every field of this row's `config` belongs to the profile's own patch layer
+# (@see ~/.dsh/profiles/<profile>/cordis.patch.yml), not here, so two profiles
+# can configure Mizar independently.
+- insert:
+    - id: mizar
+      name: 'dsh-mizar'

package/lib/auth/devices.d.ts

@@ -0,0 +1,153 @@
+/** Prefix identifying a Mizar device token in logs and support requests. */
+export declare const TOKEN_PREFIX = "mz_";
+/** Longest accepted device name, in characters. */
+export declare const MAX_DEVICE_NAME = 64;
+/** One paired device. */
+export interface DeviceRecord {
+    /** Stable identity, generated at pairing time. */
+    readonly deviceId: string;
+    /** Operator-visible name, defaulted from the device model. */
+    readonly name: string;
+    /** Device model reported by the app, when it sent one. */
+    readonly model?: string;
+    /** App version reported at pairing time. */
+    readonly appVersion?: string;
+    /** SHA-256 of the token, hex encoded. */
+    readonly tokenHash: string;
+    /** Short, non-secret display id derived from the token. */
+    readonly tokenPrefix: string;
+    /** When the device paired, in epoch milliseconds. */
+    readonly createdAt: number;
+    /** Last successful authentication, in epoch milliseconds. */
+    readonly lastSeenAt: number;
+    /** When the device was revoked; absent while it is valid. */
+    readonly revokedAt?: number;
+    /**
+     * Where to send a notification for this device, once its app has asked.
+     *
+     * Kept on the device rather than in a store of its own, because that is what
+     * it is: a property of a paired phone. Revoking a device drops it with the
+     * record, and there is no second roster to keep in step with this one.
+     *
+     * Absent until the app registers, which it does on its own after the operator
+     * grants notification permission -- so a host whose phone never asked simply
+     * never grows this field.
+     */
+    readonly push?: DevicePush;
+}
+/** A device's push endpoint. */
+export interface DevicePush {
+    /** The device token: hex for APNs, an opaque registration token for FCM. */
+    readonly token: string;
+    /**
+     * Which push service the token belongs to.
+     *
+     * Stored rather than inferred from the token's shape, because a relay that
+     * guessed would send an Android token to Apple on the strength of it looking
+     * unusual. Defaulted to `'ios'` when a record predates the field, which is
+     * what every stored record does.
+     */
+    readonly platform: 'ios' | 'android';
+    /**
+     * Which APNs environment issued it, or `null` on Android.
+     *
+     * Not inferable and not interchangeable: a token minted for the sandbox is
+     * rejected by the production endpoint with `BadDeviceToken`, which says
+     * nothing about why. FCM has one service, so an Android registration has no
+     * environment to record.
+     */
+    readonly environment: 'sandbox' | 'production' | null;
+    /** The language the app is running in, so notifications match it. */
+    readonly locale: string;
+    /** When the app last told this host where it is. */
+    readonly updatedAt: number;
+}
+/** A freshly minted token and the record material derived from it. */
+export interface IssuedToken {
+    /** The secret handed to the phone exactly once. */
+    readonly token: string;
+    /** The record fields to persist. */
+    readonly tokenHash: string;
+    /** The short display id. */
+    readonly tokenPrefix: string;
+}
+/**
+ * Hash a token for storage or comparison.
+ * @param token - the token.
+ * @returns the hex-encoded SHA-256 digest.
+ */
+export declare function hashToken(token: string): string;
+/**
+ * Mint a new device token.
+ * @returns the token plus the material to persist.
+ */
+export declare function issueToken(): IssuedToken;
+/**
+ * Build a device record for a pairing request.
+ * @param issued - the minted token material.
+ * @param details - what the phone reported about itself.
+ * @param now - current epoch milliseconds.
+ * @returns the record to persist.
+ */
+export declare function createDeviceRecord(issued: IssuedToken, details: {
+    name?: string;
+    model?: string;
+    appVersion?: string;
+}, now?: number): DeviceRecord;
+/**
+ * A token's record, and whether that record has been revoked.
+ *
+ * Both are needed because the two are different answers for the client:
+ * "this host has never seen you" sends the app back to pairing, while "you were
+ * removed on purpose" also makes it clear its stored token is dead.
+ */
+export interface TokenMatch {
+    readonly record: DeviceRecord;
+    readonly revoked: boolean;
+}
+/**
+ * Find the record a token belongs to, revoked or not.
+ *
+ * Every record is compared without an early exit, so a caller cannot time which
+ * record matched or how close a wrong token was. A live record wins over a
+ * revoked one when a token somehow appears twice, which is the order the roster
+ * itself is kept in.
+ *
+ * @param devices - the known device records.
+ * @param token - the token presented by the client.
+ * @returns the match, or `null` when no record holds this token.
+ */
+export declare function matchToken(devices: readonly DeviceRecord[], token: string): TokenMatch | null;
+/**
+ * Find the live device a token belongs to.
+ *
+ * @param devices - the known device records.
+ * @param token - the token presented by the client.
+ * @returns the matching live record, or `null`.
+ */
+export declare function verifyToken(devices: readonly DeviceRecord[], token: string): DeviceRecord | null;
+/**
+ * Mark a device revoked, preserving its record for the roster.
+ * @param devices - the known records.
+ * @param deviceId - the device to revoke.
+ * @param now - current epoch milliseconds.
+ * @returns the updated records, or the input when the id is unknown.
+ */
+export declare function revokeDevice(devices: readonly DeviceRecord[], deviceId: string, now?: number): readonly DeviceRecord[];
+/**
+ * Record a successful authentication against a device.
+ * @param devices - the known records.
+ * @param deviceId - the authenticated device.
+ * @param now - current epoch milliseconds.
+ * @returns the updated records.
+ */
+export declare function touchDevice(devices: readonly DeviceRecord[], deviceId: string, now?: number): readonly DeviceRecord[];
+/**
+ * Split the roster into live and revoked devices, newest first.
+ * @param devices - the known records.
+ * @returns the two lists, each ordered by creation time descending.
+ */
+export declare function partitionDevices(devices: readonly DeviceRecord[]): {
+    live: readonly DeviceRecord[];
+    revoked: readonly DeviceRecord[];
+};

package/lib/auth/devices.js

@@ -0,0 +1,139 @@
+/**
+ * Device credentials.
+ *
+ * A device token is the long-lived credential the phone stores in the Keychain.
+ * It is opaque, 256-bit random, and never persisted on the host — only its
+ * SHA-256 hash is, so a leaked `devices.json` cannot be replayed against the
+ * listener. Verification walks every record without an early exit so the time it
+ * takes does not reveal which record matched.
+ *
+ * @module dsh-mizar/auth/devices
+ */
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { base32 } from './pairing.js';
+/** Prefix identifying a Mizar device token in logs and support requests. */
+export const TOKEN_PREFIX = 'mz_';
+/** Random bytes behind one token. 32 bytes is 256 bits. */
+const TOKEN_BYTES = 32;
+/** Longest accepted device name, in characters. */
+export const MAX_DEVICE_NAME = 64;
+/**
+ * Hash a token for storage or comparison.
+ * @param token - the token.
+ * @returns the hex-encoded SHA-256 digest.
+ */
+export function hashToken(token) {
+    return createHash('sha256').update(token, 'utf8').digest('hex');
+}
+/**
+ * Mint a new device token.
+ * @returns the token plus the material to persist.
+ */
+export function issueToken() {
+    const token = `${TOKEN_PREFIX}${base32(new Uint8Array(randomBytes(TOKEN_BYTES)))}`;
+    const tokenHash = hashToken(token);
+    return { token, tokenHash, tokenPrefix: tokenHash.slice(0, 8) };
+}
+/**
+ * Build a device record for a pairing request.
+ * @param issued - the minted token material.
+ * @param details - what the phone reported about itself.
+ * @param now - current epoch milliseconds.
+ * @returns the record to persist.
+ */
+export function createDeviceRecord(issued, details, now = Date.now()) {
+    const rawName = details.name?.trim() ?? '';
+    const model = details.model?.trim();
+    const name = rawName !== '' ? rawName : (model ?? '').trim() !== '' ? model : 'Unnamed device';
+    return {
+        deviceId: randomUUID(),
+        name: name.slice(0, MAX_DEVICE_NAME),
+        ...(model !== undefined && model !== '' ? { model: model.slice(0, MAX_DEVICE_NAME) } : {}),
+        ...(details.appVersion !== undefined && details.appVersion !== ''
+            ? { appVersion: details.appVersion.slice(0, 32) }
+            : {}),
+        tokenHash: issued.tokenHash,
+        tokenPrefix: issued.tokenPrefix,
+        createdAt: now,
+        lastSeenAt: now,
+    };
+}
+/**
+ * Find the record a token belongs to, revoked or not.
+ *
+ * Every record is compared without an early exit, so a caller cannot time which
+ * record matched or how close a wrong token was. A live record wins over a
+ * revoked one when a token somehow appears twice, which is the order the roster
+ * itself is kept in.
+ *
+ * @param devices - the known device records.
+ * @param token - the token presented by the client.
+ * @returns the match, or `null` when no record holds this token.
+ */
+export function matchToken(devices, token) {
+    const presented = Buffer.from(hashToken(token), 'utf8');
+    let match = null;
+    for (const device of devices) {
+        const stored = Buffer.from(device.tokenHash, 'utf8');
+        if (stored.length !== presented.length || !timingSafeEqual(stored, presented))
+            continue;
+        if (device.revokedAt === undefined) {
+            if (match === null || match.revoked)
+                match = { record: device, revoked: false };
+        }
+        else if (match === null) {
+            match = { record: device, revoked: true };
+        }
+    }
+    return match;
+}
+/**
+ * Find the live device a token belongs to.
+ *
+ * @param devices - the known device records.
+ * @param token - the token presented by the client.
+ * @returns the matching live record, or `null`.
+ */
+export function verifyToken(devices, token) {
+    const match = matchToken(devices, token);
+    return match !== null && !match.revoked ? match.record : null;
+}
+/**
+ * Mark a device revoked, preserving its record for the roster.
+ * @param devices - the known records.
+ * @param deviceId - the device to revoke.
+ * @param now - current epoch milliseconds.
+ * @returns the updated records, or the input when the id is unknown.
+ */
+export function revokeDevice(devices, deviceId, now = Date.now()) {
+    let changed = false;
+    const next = devices.map((device) => {
+        if (device.deviceId !== deviceId || device.revokedAt !== undefined)
+            return device;
+        changed = true;
+        return { ...device, revokedAt: now };
+    });
+    return changed ? next : devices;
+}
+/**
+ * Record a successful authentication against a device.
+ * @param devices - the known records.
+ * @param deviceId - the authenticated device.
+ * @param now - current epoch milliseconds.
+ * @returns the updated records.
+ */
+export function touchDevice(devices, deviceId, now = Date.now()) {
+    return devices.map((device) => device.deviceId === deviceId ? { ...device, lastSeenAt: now } : device);
+}
+/**
+ * Split the roster into live and revoked devices, newest first.
+ * @param devices - the known records.
+ * @returns the two lists, each ordered by creation time descending.
+ */
+export function partitionDevices(devices) {
+    const byNewest = [...devices].sort((a, b) => b.createdAt - a.createdAt);
+    return {
+        live: byNewest.filter((device) => device.revokedAt === undefined),
+        revoked: byNewest.filter((device) => device.revokedAt !== undefined),
+    };
+}

package/lib/auth/pairing.d.ts

@@ -0,0 +1,133 @@
+/** Characters in a pairing code. 8 base32 characters carry 40 bits. */
+export declare const CODE_LENGTH = 8;
+/** Default lifetime of an issued code, in seconds. */
+export declare const DEFAULT_CODE_TTL_SECONDS = 300;
+/** The persisted pairing slot. `expiresAt: 0` means no code is outstanding. */
+export interface PairingSlot {
+    /** Counter folded into the code derivation; advances on issue and on redeem. */
+    readonly epoch: number;
+    /**
+     * Epoch milliseconds at which the outstanding code stops being accepted, or
+     * `0` when none is outstanding.
+     *
+     * The deadline lives in the slot rather than being passed to
+     * {@link redeemCode} as a TTL. Storing it once removes any way for the
+     * issuing and redeeming sides to disagree and silently extend a code's life.
+     */
+    readonly expiresAt: number;
+}
+/** An outstanding pairing code. */
+export interface IssuedCode {
+    /** The display form, grouped for reading aloud. */
+    readonly display: string;
+    /** The canonical form to compare against, uppercase without separators. */
+    readonly code: string;
+    /** The slot to persist; carries the deadline in `expiresAt`. */
+    readonly slot: PairingSlot;
+}
+/** Outcome of redeeming a code. */
+export type RedeemResult = {
+    readonly ok: true;
+    readonly slot: PairingSlot;
+} | {
+    readonly ok: false;
+    readonly reason: 'no-code' | 'consumed' | 'expired' | 'mismatch';
+};
+/**
+ * Encode bytes as Crockford base32.
+ * @param bytes - the bytes to encode.
+ * @returns the encoded string.
+ */
+export declare function base32(bytes: Uint8Array): string;
+/**
+ * Normalise a user-entered code.
+ *
+ * Accepts lowercase, spaces, and hyphens; maps the characters Crockford treats
+ * as equivalent (`I`/`L` to `1`, `O` to `0`).
+ *
+ * @param input - the raw text.
+ * @returns the canonical uppercase form.
+ */
+export declare function normalizeCode(input: string): string;
+/**
+ * Derive the code for one host secret and epoch.
+ * @param hostSecret - the per-installation secret.
+ * @param epoch - the pairing counter.
+ * @returns a {@link CODE_LENGTH}-character code.
+ */
+export declare function deriveCode(hostSecret: Uint8Array, epoch: number): string;
+/**
+ * Group a code for display, four characters at a time.
+ * @param code - the canonical code.
+ * @returns the display form, for example `AB2C-D3EF`.
+ */
+export declare function displayCode(code: string): string;
+/**
+ * Issue a fresh pairing code.
+ *
+ * Issuing invalidates any outstanding code: the epoch advances, so a code handed
+ * out a moment ago stops working the instant a new one is generated.
+ *
+ * @param hostSecret - the per-installation secret.
+ * @param previous - the outstanding slot, if any.
+ * @param now - current epoch milliseconds.
+ * @param ttlSeconds - how long the code stays valid.
+ * @returns the issued code and the slot to persist.
+ */
+export declare function issueCode(hostSecret: Uint8Array, previous: PairingSlot | null, now?: number, ttlSeconds?: number): IssuedCode;
+/**
+ * Redeem a pairing code.
+ *
+ * Comparison is constant-time over equal-length buffers, so the response time
+ * does not reveal how much of a wrong guess was correct.
+ *
+ * `consumed` and `expired` are reported separately here because the audit log is
+ * the operator's only forensic trail and "someone replayed a code" is a
+ * different story from "the code timed out". Callers must still answer both with
+ * the same client-facing code — telling a caller which of the two it hit turns
+ * the endpoint into an oracle.
+ *
+ * @param hostSecret - the per-installation secret.
+ * @param slot - the outstanding pairing slot, carrying its own deadline.
+ * @param input - the code the phone sent.
+ * @param now - current epoch milliseconds.
+ * @returns whether the code was redeemed, and the cleared slot when it was.
+ */
+export declare function redeemCode(hostSecret: Uint8Array, slot: PairingSlot | null, input: string, now?: number): RedeemResult;
+/**
+ * Generate a host secret with full entropy.
+ * @returns 32 random bytes.
+ */
+export declare function generateHostSecret(): Uint8Array;
+/**
+ * A counted, time-windowed limiter for authentication attempts.
+ *
+ * Pairing is the only unauthenticated endpoint, so it is the only place an
+ * attacker can guess. A fixed window is deliberate: it must be cheap enough to
+ * run on every attempt and simple enough to reason about.
+ */
+export declare class RateLimiter {
+    #private;
+    private readonly limit;
+    private readonly windowMs;
+    /**
+     * @param limit - attempts allowed per window, per key.
+     * @param windowMs - window length in milliseconds.
+     */
+    constructor(limit: number, windowMs: number);
+    /**
+     * Record one attempt and report whether it may proceed.
+     * @param key - the caller identity, for example a remote address.
+     * @param now - current epoch milliseconds.
+     * @returns whether the attempt is within the limit, and how long to wait when it is not.
+     */
+    check(key: string, now?: number): {
+        allowed: boolean;
+        retryAfterMs: number;
+    };
+    /**
+     * Drop windows that have expired.
+     * @param now - current epoch milliseconds.
+     */
+    prune(now?: number): void;
+}