# @bernierllc/crypto-utils 中文文档

规范地址：https://npmcn.com/package/%40bernierllc/crypto-utils/

版本：1\.4\.0
npm 元数据更新时间：2026-05-20T04:03:37.372Z
中文译文更新时间：2026-11-08T07:48:22.445Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bernierllc/crypto-utils
原文对照：https://npmcn.com/package/%40bernierllc/crypto-utils/?lang=original
项目主页：https://github.com/bernier-llc/tools#readme
源码仓库：https://github.com/bernier-llc/tools

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：141 kB，43 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- 首次发布：2025-08-29T17:19:53.954Z
- 最新版本发布：2026-05-20T04:03:37.243Z
- 近 30 天下载量：1861（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 7 个）

## 中文简介

综合密码公用事业,包括钥匙生成、JWT标志、魔法链接和伯尼环礁生态系统安全散列

## 安装

```sh
npm install @bernierllc/crypto-utils
```

也可以使用：`pnpm add @bernierllc/crypto-utils`、`yarn add @bernierllc/crypto-utils`、`bun add @bernierllc/crypto-utils`

## README

# @bernierllc/crypto-utils

综合密码设施,包括钥匙生成、JWT标志、魔法链接和现代应用的安全散列.

## 安装

```bash
npm install @bernierllc/crypto-utils
```

## 快速启动

```typescript
import { 
  generateApiKey, 
  generateAccessToken, 
  generateEmailMagicLink,
  verifyJWT,
  constantTimeCompare 
} from '@bernierllc/crypto-utils';

// Generate an API key with sensible defaults
const apiKey = await generateApiKey();
console.log(apiKey); // ak_a1b2c3d4e5f6...

// Generate JWT access token
const accessToken = generateAccessToken({ 
  sub: 'user123', 
  email: 'user@example.com' 
}, 'your-secret');

// Generate magic link for email authentication
const magicLink = generateEmailMagicLink('user123', 'user@example.com', 'your-secret');

// Secure password verification
const isValid = constantTimeCompare(providedPassword, storedPasswordHash);
```

## 核心特征

### QQ 密钥生成

-   **多种算法**: 随机字节, UUID v4, 自定义模式
-   **多个编码**:Hex, Base64, Base58 (比特币风格)
-   **安全特性**: Entropy验证,相撞探测,安全散列

### JWT 托肯斯语

-   **标准**: RFC 7519 JWT的实施
-   **多种算法**: HS256, HS384, HS512 (英语)
-   **核实**: 过期,发行人,受众,主题

### QQ 魔法链接

-   **电子邮件认证**: 安全无密码登录
-   **密码重置**: 有时间限制的重新设置符号
-   **URL - 安全**: 用于网络兼容的 Base64URL 编码
-   **TOTP 支持**: 基于时间的一次性密码

### 安全设备

-   **常时比较**:防止时间攻击
-   **密码验证**: 安全散列验证
-   **托肯验证**: 全面安全检查

## API 参考

## 密钥生成

### 核心生成函数

#### `generateRandomKey(options?)`

使用 : `crypto.randomBytes`。 。 。 .

```typescript
import { generateRandomKey } from '@bernierllc/crypto-utils';

const result = await generateRandomKey({
  length: 32,           // Key length in bytes
  prefix: 'ak_',        // Optional prefix
  encoding: 'hex',      // 'hex' | 'base64' | 'base58'
  validateEntropy: true, // Validate entropy requirements
  minEntropyBits: 128,  // Minimum entropy in bits
  checkUnique: async (key) => !await db.keyExists(key), // Collision check
  maxRetries: 5         // Max collision retry attempts
});

console.log(result.key);      // Generated key string
console.log(result.entropy);  // Estimated entropy in bits
console.log(result.metadata); // Generation metadata
```

### 方便职能

预配置带有合理默认的密钥生成器 :

```typescript
import { 
  generateApiKey,       // ak_ + 32 bytes + hex
  generateSecretKey,    // sk_ + 48 bytes + base64  
  generateSessionToken, // sess_ + UUID + base58
  generateLicenseKey    // lic_ + pattern XXXX-XXXX-XXXX-XXXX
} from '@bernierllc/crypto-utils';

const apiKey = await generateApiKey();          // ak_a1b2c3...
const secret = await generateSecretKey();       // sk_SGVsbG8...
const session = await generateSessionToken();   // sess_23456789...
const license = await generateLicenseKey();     // lic_A1B2-C3D4...
```

## 日本 键

### 脚本生成

#### `generateJWT(payload, secret, options?)`

生成带有自定义要求的 JWT 令牌 .

```typescript
import { generateJWT } from '@bernierllc/crypto-utils';

const token = generateJWT({
  sub: 'user123',
  email: 'user@example.com',
  role: 'admin'
}, 'your-jwt-secret', {
  algorithm: 'HS256',     // HS256 | HS384 | HS512
  expiresIn: 3600,        // 1 hour in seconds
  issuer: 'your-app',
  audience: 'api',
  includeIssuedAt: true   // Include iat claim
});
```

#### `verifyJWT(token, secret, options?)`

校验和验证 JWT 标志 .

```typescript
import { verifyJWT } from '@bernierllc/crypto-utils';

const result = verifyJWT(token, 'your-jwt-secret', {
  issuer: 'your-app',      // Expected issuer
  audience: 'api',         // Expected audience
  clockTolerance: 30,      // Allow 30 seconds clock skew
  ignoreExpiration: false  // Enforce expiration
});

if (result.valid) {
  console.log('User:', result.payload?.sub);
  console.log('Expires in:', result.expiresIn, 'seconds');
} else {
  console.error('Invalid token:', result.error);
}
```

### 方便调试函数

```typescript
import { 
  generateAccessToken,  // 1 hour expiry, HS256
  generateRefreshToken, // 7 days expiry, HS256
} from '@bernierllc/crypto-utils';

// Generate access token (1 hour expiry)
const accessToken = generateAccessToken({
  sub: 'user123',
  email: 'user@example.com'
}, 'your-secret');

// Generate refresh token (7 days expiry)
const refreshToken = generateRefreshToken({
  sub: 'user123'
}, 'your-secret');
```

## 魔法链接

### 电子邮件认证链接

#### `generateMagicLink(userId, email, secret, options?)`

生成无密码认证的安全魔法链接 .

```typescript
import { generateMagicLink } from '@bernierllc/crypto-utils';

const result = generateMagicLink('user123', 'user@example.com', 'your-secret', {
  expirationMinutes: 15,  // Link expires in 15 minutes
  action: 'login',        // Action type
  customData: {           // Additional data
    ip: '192.168.1.1',
    userAgent: 'Mozilla/5.0...'
  }
});

const magicUrl = `https://yourapp.com/auth/verify?token=${result.token}`;
console.log('Magic link expires at:', new Date(result.expiresAt));
```

#### `verifyMagicLink(token, secret, options?)`

校验魔法链接符号 .

```typescript
import { verifyMagicLink } from '@bernierllc/crypto-utils';

const result = verifyMagicLink(token, 'your-secret');

if (result.valid) {
  console.log('User ID:', result.payload?.userId);
  console.log('Email:', result.payload?.email);
  console.log('Action:', result.payload?.action);
  console.log('Remaining time:', result.remainingMinutes, 'minutes');
  
  // Authenticate user
  await authenticateUser(result.payload.userId);
} else {
  console.error('Invalid magic link:', result.error);
}
```

### 方便魔法链接函数

```typescript
import { 
  generateEmailMagicLink,    // 15 min expiry, email_auth action
  generatePasswordResetLink  // 30 min expiry, password_reset action
} from '@bernierllc/crypto-utils';

// Email verification link
const emailLink = generateEmailMagicLink('user123', 'user@example.com', 'secret');

// Password reset link  
const resetLink = generatePasswordResetLink('user123', 'user@example.com', 'secret');
```

### 一次性密码

```typescript
import { generateOTP, generateTOTP, verifyTOTP } from '@bernierllc/crypto-utils';

// Simple numeric OTP
const otp = generateOTP(6); // 123456

// Time-based OTP (Google Authenticator compatible)
const secret = '48656c6c6f21deadbeef'; // Hex-encoded secret
const totp = generateTOTP(secret, {
  timeStep: 30,    // 30-second windows
  digits: 6,       // 6-digit codes
  algorithm: 'sha1' // sha1 | sha256 | sha512
});

// Verify TOTP code
const isValid = verifyTOTP(userProvidedCode, secret, {
  window: 1 // Allow ±1 time window (90 seconds total)
});
```

## 安保公用事业

### 常时比较

在比较敏感值时防止时间攻击.

```typescript
import { 
  constantTimeCompare,
  constantTimeCompareHex,
  validateSecureToken
} from '@bernierllc/crypto-utils';

// Basic constant-time string comparison
const isMatch = constantTimeCompare(providedToken, expectedToken);

// Hex comparison (case-insensitive)  
const hexMatch = constantTimeCompareHex('deadbeef', 'DEADBEEF'); // true

// Secure token validation with options
const isValid = validateSecureToken(providedToken, expectedToken, {
  caseSensitive: false,  // Case-insensitive comparison
  trimWhitespace: true,  // Trim whitespace
  maxLength: 1000        // Maximum token length
});
```

### 密码 hash 校验

```typescript
import { verifyPasswordHash } from '@bernierllc/crypto-utils';

// Custom hash function (use bcrypt, scrypt, etc. in production)
const hashPassword = (password: string) => {
  return crypto.createHash('sha256').update(password + 'salt').digest('hex');
};

const isValidPassword = verifyPasswordHash(
  providedPassword,
  storedPasswordHash,
  hashPassword
);
```

### 定时安全阵列操作

```typescript
import { timingSafeIncludes } from '@bernierllc/crypto-utils';

const allowedTokens = ['token1', 'token2', 'token3'];
const isAllowed = timingSafeIncludes(allowedTokens, userToken);
```

## 完整认证流程示例

```typescript
import {
  generateEmailMagicLink,
  verifyMagicLink,
  generateAccessToken,
  generateRefreshToken,
  verifyJWT
} from '@bernierllc/crypto-utils';

const JWT_SECRET = process.env.JWT_SECRET!;
const MAGIC_SECRET = process.env.MAGIC_SECRET!;

// Step 1: Send magic link via email
async function sendMagicLink(email: string) {
  const user = await getUserByEmail(email);
  if (!user) throw new Error('User not found');
  
  const magicLink = generateEmailMagicLink(user.id, email, MAGIC_SECRET, {
    expirationMinutes: 10
  });
  
  const url = `https://app.com/auth/verify?token=${magicLink.token}`;
  await sendEmail(email, 'Login to Your Account', `Click: ${url}`);
}

// Step 2: Verify magic link and issue tokens
async function verifyMagicLinkAndIssueTokens(token: string) {
  const verification = verifyMagicLink(token, MAGIC_SECRET);
  
  if (!verification.valid) {
    throw new Error(`Invalid magic link: ${verification.error}`);
  }
  
  const userId = verification.payload!.userId;
  const user = await getUserById(userId);
  
  const accessToken = generateAccessToken({
    sub: userId,
    email: user.email,
    role: user.role
  }, JWT_SECRET);
  
  const refreshToken = generateRefreshToken({
    sub: userId
  }, JWT_SECRET);
  
  return { accessToken, refreshToken, user };
}

// Step 3: Validate API requests
async function authenticateRequest(authHeader: string) {
  const token = authHeader.replace('Bearer ', '');
  const verification = verifyJWT(token, JWT_SECRET);
  
  if (!verification.valid) {
    throw new Error(`Authentication failed: ${verification.error}`);
  }
  
  return verification.payload;
}
```

## 安保最佳做法

### 密钥生成

-   **最小 128 位数** 用于生产键的py
-   使用 `generateRandomKey()` 最大 en
-   执行碰撞检查 `checkUnique`

### JWT 安全保卫

-   **使用强大的秘密** (256+位的 en
-   **短的过期时间** (15-60分钟)
-   **核证所有索赔** (实例,是,是,是等)
-   **仅使用 HTTPS** 用于符号传输

### 魔法链接安全

-   **短的过期时间** (登录时间5至15分钟,密码重置时间30分钟)
-   **仅一次使用** - 经核实无效
-   **限制费率** - 防止魔法链接垃圾邮件
-   **所需HTTPS** - 从不发送HTTP

### 常时业务

-   **总是用于密码** 和敏感标志
-   **用于会话验证** 和 API 密钥检查
-   **避免字符串长度漏出** 错误消息中

### 安全总局

-   **永远不要记录机密** 生产中的标志
-   **使用环境变量** 秘密调查
-   **执行适当的密钥旋转** 政策
-   **在所有地方使用 HTTPS** 用于符号传输

## 处理错误

```typescript
import { generateJWT, verifyJWT, generateMagicLink } from '@bernierllc/crypto-utils';

try {
  // Token generation
  const token = generateJWT(payload, secret);
  
  // Token verification
  const result = verifyJWT(token, secret);
  if (!result.valid) {
    // Handle specific errors
    if (result.error?.includes('expired')) {
      console.log('Token expired, refresh required');
    } else if (result.error?.includes('signature')) {
      console.log('Invalid token signature');
    }
  }
  
  // Magic link generation
  const magicLink = generateMagicLink(userId, email, secret, {
    expirationMinutes: 5
  });
  
} catch (error) {
  console.error('Crypto operation failed:', error.message);
}
```

## 类型脚本支持

包含全面类型定义的完整类型脚本支持 :

```typescript
import type { 
  // Key generation types
  KeyOptions, 
  GenerationResult, 
  ValidationResult,
  KeyEncoding,
  KeyAlgorithm,
  
  // JWT types
  JWTPayload,
  JWTOptions,
  JWTVerifyResult,
  
  // Magic link types
  MagicLinkOptions,
  MagicLinkResult,
  MagicLinkVerifyResult
} from '@bernierllc/crypto-utils';

// Strongly typed JWT payload
const payload: JWTPayload = {
  sub: 'user123',
  email: 'user@example.com',
  exp: Math.floor(Date.now() / 1000) + 3600
};

// Strongly typed options
const keyOptions: KeyOptions = {
  length: 32,
  encoding: 'hex',
  validateEntropy: true
};
```

## 业绩

-   **高吞吐量**: > 10 000个操作/秒
-   **高效编码**: 优化实施
-   **最小依赖性**: 0 运行时间依赖性
-   **内存效率**: 尽可能精简业务

## 从 @bernierllc/ api- key- 生成器迁移

软件包保持了完全后向相容性 :

```typescript
// All existing imports continue to work
import { 
  generateApiKey,
  generateSecretKey,
  generateRandomKey,
  validateKeyFormat
} from '@bernierllc/crypto-utils'; // was @bernierllc/api-key-generator
```

## 许可证

(c) 2025 Bernier有限责任公司

## 另见

-   [@ bernierllc/ 拖放器](https://npmcn.com/package/%40bernierllc/logger) - 结构化伐木(绝不是秘密记录)
-   [@bernierllc/ 绝不是适应器](https://npmcn.com/package/%40bernierllc/neverhub-adapter) - 服务发现一体化

## 常见问题

### @bernierllc/crypto-utils 是什么？

综合密码公用事业,包括钥匙生成、JWT标志、魔法链接和伯尼环礁生态系统安全散列

### 如何安装 @bernierllc/crypto-utils？

在项目目录运行 npm install @bernierllc/crypto-utils，或使用 pnpm add / yarn add / bun add。

### @bernierllc/crypto-utils 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bernierllc/crypto-utils 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bernierllc/crypto-utils 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bernierllc/crypto-utils 可以商用吗？

@bernierllc/crypto-utils 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bernierllc/crypto-utils 的下载量有多少？

根据 npm 官方下载统计，@bernierllc/crypto-utils 在 2026/10/08 – 2026/11/06 这 30 天内被下载 1,861 次，日均约 62 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bernierllc/crypto-utils 还在维护吗？

最新版本 1\.4\.0 发布于 2026/05/20（5 个月前）；至今共发布 8 个版本，其中过去 12 个月发布了 7 个；首次发布于 2025/08/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。