experimental_taintUniqueValue

taintUniqueValue(errMessage, lifetime, value)

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

参考

🌐 Reference

taintUniqueValue(message, lifetime, value)

使用密码、令牌、密钥或哈希调用 taintUniqueValue，将其注册到 React 中，作为不应直接传递给客户端的内容：

🌐 Call taintUniqueValue with a password, token, key or hash to register it with React as something that should not be allowed to be passed to the Client as is:

import {experimental_taintUniqueValue} from 'react';

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

查看更多示例。

参数

🌐 Parameters

• message：如果将 value 传递给客户端组件时要显示的消息。 如果将 value 传递给客户端组件时，将会作为抛出的错误的一部分显示此消息。
• lifetime：任何指示 value 应该被污染多长时间的对象。在此对象仍然存在期间，value 将被阻止发送到任何客户端组件。例如，传递 globalThis 会阻止该值在应用的整个生命周期内使用。lifetime 通常是一个其属性包含 value 的对象。
• value：一个字符串、bigint 或 TypedArray。value 必须是具有高熵的唯一字符或字节序列，例如加密令牌、私钥、哈希或一个长密码。value 将被阻止发送到任何客户端组件。

返回

🌐 Returns

experimental_taintUniqueValue 返回 undefined。

注意事项

🌐 Caveats

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

用法

🌐 Usage

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

🌐 Prevent a token from being passed to Client Components

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

🌐 To ensure that sensitive information such as passwords, session tokens, or other unique values do not inadvertently get passed to Client Components, the taintUniqueValue function provides a layer of protection. When a value is tainted, any attempt to pass it to a Client Component will result in an error.

lifetime 参数定义了值保持污染状态的持续时间。对于应该无限期保持污染的值，像 globalThis 或 process 这样的对象可以用作 lifetime 参数。这些对象的生命周期贯穿应用的整个执行期间。

🌐 The lifetime argument defines the duration for which the value remains tainted. For values that should remain tainted indefinitely, objects like globalThis or process can serve as the lifetime argument. These objects have a lifespan that spans the entire duration of your app’s execution.

import {experimental_taintUniqueValue} from 'react';

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

如果被污染值的生命周期与某个对象绑定，lifetime 应该是封装该值的对象。这确保了被污染的值在封装对象的生命周期内保持受保护状态。

🌐 If the tainted value’s lifespan is tied to a object, the lifetime should be the object that encapsulates the value. This ensures the tainted value remains protected for the lifetime of the encapsulating 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 参数。如果此对象被存储在全局缓存中或被另一个请求访问，会话令牌将保持受污染状态。

🌐 In this example, the user object serves as the lifetime argument. If this object gets stored in a global cache or is accessible by another request, the session token remains tainted.

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
);