@qilin-agent/util-crypto 0.0.0-stage → 3.1.3

package/LICENSE

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

@@ -0,0 +1,34 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/util/crypto/README.md
+/:
+  en: c3004d7d489da8f1
+  zh: 8b6af2f3f48d5544
+/qilin-util-crypto:
+  en: 97c00d05b84bfb0f
+  zh: 48d47a48c3ba76d6
+/qilin-util-crypto/summary:
+  en: 55f117af7ba9f8fe
+  zh: 2cde7f6b69dc4bf8
+/qilin-util-crypto/table-of-contents:
+  en: cd2a60a905c978d6
+  zh: cc71d387d0cbd442
+/qilin-util-crypto/use-this-package:
+  en: 594d34627be8618a
+  zh: 68723dfafb88ac84
+/qilin-util-crypto/api:
+  en: 21d8f33a1c652edb
+  zh: 07a3629d66301d85
+/qilin-util-crypto/model-experience:
+  en: beb00a2635b78870
+  zh: d93b828c08217472
+/qilin-util-crypto/model-experience/kv-cache-effect:
+  en: 3f396619298fe1ae
+  zh: d46e51c86231d485
+/qilin-util-crypto/known-limitations-and-deferred-work:
+  en: 2c79cf7c12f39ab1
+  zh: c6f2ad3e53a62473
+/qilin-util-crypto/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: e88aeb617ffb74ea

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+---
+description: "Cross-runtime UUID generation for maintainers replacing secure-context-only crypto.randomUUID calls."
+kind: "package-library"
+---
 
-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.
+# qilin-util-crypto
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Zero-dependency browser-safe UUID and byte-encoding helpers. UUID minting uses `crypto.getRandomValues`, the one random primitive every shipped context provides. `crypto.randomUUID` is a secure-context Web API: a page or worker served over plain HTTP on a LAN address (the browser preview deployment) has no such method, so code that must run there cannot call it. The repository-wide `no-restricted-properties` lint rule points `crypto.randomUUID` callers here; Node-only code importing `randomUUID` from `node:crypto` stays as it is.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [API](#api)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+It is a **library, not a service or plugin**: no `ctx`, registers nothing, holds no state.
+
+-----
+
+<a id="api"></a>
+## API
+
+```ts
+import { bytesToBase64, randomUUID, type Uuid } from '@qilin-agent/util-crypto'
+```
+
+| Export | Role |
+|---|---|
+| `bytesToBase64(data)` | Canonical base64 for a byte array, encoded in bounded chunks. |
+| `randomUUID()` | Random RFC 9562 v4 UUID string, minted from `crypto.getRandomValues`. Drop-in for `crypto.randomUUID()`. |
+| `Uuid` | The five-group UUID string type, matching `crypto.randomUUID`'s declared return shape. |
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through consumers that mint request, session, and attachment identifiers with it, none of which enter prompts as semantic content.
+
+#### KV Cache effect
+
+No direct invalidation; identifier-minting consumers own any request changes.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **v4 only** — no other UUID versions, namespaces, or parsing; consumers needing more should take a real UUID dependency.
+- **Uniqueness is probabilistic** — 122 random bits, the same guarantee `crypto.randomUUID` gives; nothing here detects collisions.
+
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,69 @@
+---
+description: "面向替换仅安全上下文可用的 crypto.randomUUID 调用的维护者，说明跨运行时 UUID 生成。"
+kind: "package-library"
+---
+
+# qilin-util-crypto
+
+[English](README.md) | 中文
+
+## 概述
+
+零依赖、可在浏览器使用的 UUID 与字节编码辅助函数。UUID 铸造基于 `crypto.getRandomValues`——所有发布上下文都提供的那个随机原语。`crypto.randomUUID` 是安全上下文限定的 Web API：经普通 HTTP 在局域网地址上提供的页面或 worker（浏览器预览部署）根本没有这个方法，必须在那里运行的代码不能调它。全仓 `no-restricted-properties` lint 规则把 `crypto.randomUUID` 的调用者指到这里；只跑在 Node 的代码从 `node:crypto` 导入 `randomUUID` 维持原样。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [API](#api)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+它是**库，不是服务也不是插件**：无 `ctx`、不注册任何东西、不持有状态。
+
+-----
+
+<a id="api"></a>
+## API
+
+```ts
+import { bytesToBase64, randomUUID, type Uuid } from '@qilin-agent/util-crypto'
+```
+
+| 导出 | 角色 |
+|---|---|
+| `bytesToBase64(data)` | 以有界分片把字节数组编码为标准 base64。 |
+| `randomUUID()` | 随机 RFC 9562 v4 UUID 字符串，由 `crypto.getRandomValues` 铸造。可原位替换 `crypto.randomUUID()`。 |
+| `Uuid` | 五段式 UUID 字符串类型，与 `crypto.randomUUID` 声明的返回形状一致。 |
+
+<a id="model-experience"></a>
+## 模型体验
+
+间接地，经由用它铸造请求、会话与附件标识符的消费方，这些标识符均不作为语义内容进入提示词。
+
+#### KV Cache 影响
+
+无直接失效；铸造标识符的消费方自行负责其请求变化。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **仅 v4**——不提供其他 UUID 版本、命名空间或解析；需要更多能力的消费方应引入真正的 UUID 依赖。
+- **唯一性是概率性的**——122 位随机，与 `crypto.randomUUID` 同级保证；此处不做碰撞检测。
+
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,35 @@
+//#region lib/types/index.js
+/**
+* UUID minting that works in every JavaScript context this repository ships
+* to. `crypto.randomUUID` is a secure-context Web API — a page or worker
+* served over plain HTTP on a LAN address has no such method — while
+* `crypto.getRandomValues` is unrestricted everywhere (browsers, workers,
+* Node ≥ 19). One implementation here replaces per-caller polyfills; the
+* `no-restricted-properties` lint rule points `crypto.randomUUID` callers at
+* this module.
+* @module @qilin-agent/util-crypto
+*/
+/**
+* Encode bytes as canonical base64 without overflowing function argument limits.
+* @param data - Bytes to encode.
+* @returns base64 text.
+*/
+function bytesToBase64(data) {
+	let binary = "";
+	const chunk = 32768;
+	for (let offset = 0; offset < data.length; offset += chunk) binary += String.fromCharCode(...data.subarray(offset, offset + chunk));
+	return btoa(binary);
+}
+/**
+* Random v4 UUID, minted from `crypto.getRandomValues`.
+* @returns the UUID string.
+*/
+function randomUUID() {
+	const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+	const hex = Array.from(bytes, (byte, index) => {
+		return (index === 6 ? byte & 15 | 64 : index === 8 ? byte & 63 | 128 : byte).toString(16).padStart(2, "0");
+	}).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+//#endregion
+export { bytesToBase64, randomUUID };

package/lib/types/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * UUID minting that works in every JavaScript context this repository ships
+ * to. `crypto.randomUUID` is a secure-context Web API — a page or worker
+ * served over plain HTTP on a LAN address has no such method — while
+ * `crypto.getRandomValues` is unrestricted everywhere (browsers, workers,
+ * Node ≥ 19). One implementation here replaces per-caller polyfills; the
+ * `no-restricted-properties` lint rule points `crypto.randomUUID` callers at
+ * this module.
+ * @module @qilin-agent/util-crypto
+ */
+/** RFC 9562 UUID string, the shape `crypto.randomUUID` declares. */
+export type Uuid = `${string}-${string}-${string}-${string}-${string}`;
+/**
+ * Encode bytes as canonical base64 without overflowing function argument limits.
+ * @param data - Bytes to encode.
+ * @returns base64 text.
+ */
+export declare function bytesToBase64(data: Uint8Array): string;
+/**
+ * Random v4 UUID, minted from `crypto.getRandomValues`.
+ * @returns the UUID string.
+ */
+export declare function randomUUID(): Uuid;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@qilin-agent/util-crypto",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Zero-dependency browser-safe UUID and byte-encoding helpers",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/util/crypto"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }