experimental_taintUniqueValue

taintUniqueValue(errMessage, lifetime, value)

• 参考
  • taintUniqueValue(message, lifetime, value)
• 用法
  • 阻止将令牌传递给客户端组件

参考

taintUniqueValue(message, lifetime, value)

使用密码、令牌、密钥或哈希值调用 taintUniqueValue，将其注册到 React 中，作为不允许按原样传递给客户端的内容

import {experimental_taintUniqueValue} from 'react';

experimental_taintUniqueValue(
  'Do not pass secret keys to the client.',
  process,
  process.env.SECRET_KEY
);

请参阅下面的更多示例。

参数

• message：如果将 value 传递给客户端组件，则要显示的消息。如果将 value 传递给客户端组件，则此消息将作为抛出错误的一部分显示。

• lifetime：任何指示 value 应被污染多长时间的对象。当此对象仍然存在时，value 将被阻止发送到任何客户端组件。例如，传递 globalThis 会在应用程序的生存期内阻止该值。lifetime 通常是一个对象的属性包含 value 的对象。

• value：字符串、bigint 或 TypedArray。value 必须是具有高熵的唯一字符或字节序列，例如加密令牌、私钥、哈希值或长密码。value 将被阻止发送到任何客户端组件。

返回值

experimental_taintUniqueValue 返回 undefined。

注意事项

• 从受污染的值派生新值可能会损害污染保护。通过将受污染的值转换为大写、将受污染的字符串值连接成更大的字符串、将受污染的值转换为 base64、对受污染的值进行子字符串化以及其他类似转换创建的新值不会被污染，除非您在新创建的值上显式调用 taintUniqueValue。
• 不要使用 taintUniqueValue 来保护低熵值，例如 PIN 码或电话号码。如果请求中的任何值由攻击者控制，他们可以通过枚举密钥的所有可能值来推断哪个值被污染。

---

用法

防止令牌传递到客户端组件

为了确保密码、会话令牌或其他唯一值等敏感信息不会无意中传递到客户端组件，taintUniqueValue 函数提供了一层保护。当一个值被污染后，任何尝试将其传递给客户端组件的操作都将导致错误。

lifetime 参数定义了值保持污染状态的持续时间。对于应该无限期保持污染状态的值，可以使用 globalThis 或 process 等对象作为 lifetime 参数。这些对象的寿命涵盖了应用程序执行的整个过程。

import {experimental_taintUniqueValue} from 'react';

experimental_taintUniqueValue(
  'Do not pass a user password to the client.',
  globalThis,
  process.env.SECRET_KEY
);

如果受污染值的寿命与某个对象绑定，则 lifetime 应该是封装该值的 object。这确保了受污染的值在封装对象的整个生命周期内都受到保护。

import {experimental_taintUniqueValue} from 'react';

export async function getUser(id) {
  const user = await db`SELECT * FROM users WHERE id = ${id}`;
  experimental_taintUniqueValue(
    'Do not pass a user session token to the client.',
    user,
    user.session.token
  );
  return user;
}

在这个例子中，user 对象作为 lifetime 参数。如果此对象存储在全局缓存中或可被另一个请求访问，则会话令牌将保持污染状态。

import {experimental_taintUniqueValue} from 'react';

const password = 'correct horse battery staple';

experimental_taintUniqueValue(
  'Do not pass the password to the client.',
  globalThis,
  password
);

const uppercasePassword = password.toUpperCase() // `uppercasePassword` is not tainted

export async function Dashboard(props) {
  // DO NOT DO THIS
  return <Overview password={process.env.API_PASSWORD} />;
}

"use client";

import {useEffect} from '...'

export async function Overview({ password }) {
  useEffect(() => {
    const headers = { Authorization: password };
    fetch(url, { headers }).then(...);
  }, [password]);
  ...
}

import "server-only";

export function fetchAPI(url) {
  const headers = { Authorization: process.env.API_PASSWORD };
  return fetch(url, { headers });
}

import "server-only";
import {experimental_taintUniqueValue} from 'react';

experimental_taintUniqueValue(
  'Do not pass the API token password to the client. ' +
    'Instead do all fetches on the server.'
  process,
  process.env.API_PASSWORD
);