Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(cn): standardize the translations of the word taint #1361

Merged
merged 1 commit into from
Oct 30, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions src/content/reference/react/experimental_taintObjectReference.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,19 +56,19 @@ experimental_taintObjectReference(

* `message`:对象被传递给客户端组件时显示的消息。如果对象被传递给客户端组件,此消息将作为错误的一部分显示。

* `object`:要标记的对象。函数和类实例可以作为 `object` 传递给 `taintObjectReference`。React 会阻止直接将函数和类传递给客户端组件,并把默认的错误消息替换为在 `message` 中定义的内容。当将特定类型数组的实例作为 `object` 传递给 `taintObjectReference` 时,该类型数组的其他副本将不会被标记
* `object`:被污染的对象。函数和类实例可以作为 `object` 传递给 `taintObjectReference`。React 会阻止直接将函数和类传递给客户端组件,并把默认的错误消息替换为在 `message` 中定义的内容。当将特定类型数组的实例作为 `object` 传递给 `taintObjectReference` 时,该类型数组的其他副本将不会被污染

#### 返回值 {/*returns*/}

`experimental_taintObjectReference` 返回 `undefined`。

#### 注意 {/*caveats*/}

- 重新创建或克隆一个被标记的对象会创建一个新的未标记的对象,其中可能包含敏感数据。如果有一个被标记的 `user` 对象,执行 `const userInfo = {name: user.name, ssn: user.ssn}` 或 `{...user}` 将创建新的未标记对象。`taintObjectReference` 只能防止把未修改的对象传递给客户端组件这种简单的错误。
- 重新创建或克隆一个被污染的对象会创建一个新的未被污染的对象,其中可能包含敏感数据。如果有一个被污染的 `user` 对象,执行 `const userInfo = {name: user.name, ssn: user.ssn}` 或 `{...user}` 将创建新的未被污染的对象。`taintObjectReference` 只能防止把未修改的对象传递给客户端组件这种简单的错误。

<Pitfall>

**不要仅依赖于标记来确保安全**。标记对象并不防止泄露每一个可能的派生值。例如,被标记对象的克隆将创建一个新的未标记对象。使用来自被标记对象的数据(例如 `{secret: taintedObj.secret}`)将创建一个新的值或对象,它不被标记。标记只是一层保护,安全的应用程序应该有多层保护、精心设计的 API 和隔离模式。
**不要仅依赖于污点标记来确保安全**。被污染的对象并不防止泄露每一个可能的派生值。例如,被污染的对象的克隆将创建一个新的未被污染的对象。使用来自被污染的对象的数据(例如 `{secret: taintedObj.secret}`)将创建一个新的值或对象,它不被污染。污点标记只是一层保护,安全的应用程序应该有多层保护、精心设计的 API 和隔离模式。

</Pitfall>

Expand All @@ -78,7 +78,7 @@ experimental_taintObjectReference(

### 防止用户数据被无意间传递到客户端 {/*prevent-user-data-from-unintentionally-reaching-the-client*/}

客户端组件不应接受携带敏感数据的对象。理想情况下数据获取函数不应暴露当前用户不允许访问的数据。有时在重构过程中会发生错误。为了防止这些错误在以后发生,我们可以在数据 API 中“标记”用户对象。
客户端组件不应接受携带敏感数据的对象。理想情况下数据获取函数不应暴露当前用户不允许访问的数据。有时在重构过程中会发生错误。为了防止这些错误在以后发生,我们可以在数据 API 中“污染”用户对象。

```js
import {experimental_taintObjectReference} from 'react';
Expand Down Expand Up @@ -130,7 +130,7 @@ export async function InfoCard({ user }) {
}
```

理想情况下 `getUser` 不应暴露当前用户不允许访问的数据。为了防止将来把 `user` 对象传递给客户端组件,我们可以对用户对象进行“标记”:
理想情况下 `getUser` 不应暴露当前用户不允许访问的数据。为了防止将来把 `user` 对象传递给客户端组件,我们可以对用户对象进行“污染”:


```js
Expand Down
28 changes: 14 additions & 14 deletions src/content/reference/react/experimental_taintUniqueValue.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ experimental_taintUniqueValue(

* `message`:`value` 被传递给客户端组件时显示的消息。如果将 `value` 传递给客户端组件,此消息将作为错误的一部分显示。

* `lifetime`:指示 `value` 应该被标记多长时间的任何对象。只要此对象仍然存在,将阻止把 `value` 发送到任何客户端组件。例如,传递 `globalThis` 将在应用程序的生命周期内阻止该值的传递。`lifetime` 通常是一个包含 `value` 属性的对象。
* `lifetime`:指示 `value` 应该被污染多长时间的任何对象。只要此对象仍然存在,将阻止把 `value` 发送到任何客户端组件。例如,传递 `globalThis` 将在应用程序的生命周期内阻止该值的传递。`lifetime` 通常是一个包含 `value` 属性的对象。

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

Expand All @@ -67,18 +67,18 @@ experimental_taintUniqueValue(

#### 注意 {/*caveats*/}

* 从受标记的值派生新值可能会破坏标记保护。通过将受标记的值大写、将受标记的字符串值连接成较大的字符串、将受标记的值转换为 base64、对受标记的值进行子字符串操作以及其他类似的转换来创建的新值,除非明确调用 `taintUniqueValue` 标记这些新创建的值,否则它们不会受到标记
* Do not use `taintUniqueValue` to protect low-entropy values such as PIN codes or phone numbers. If any value in a request is controlled by an attacker, they could infer which value is tainted by enumerating all possible values of the secret.
* 从被污染的值派生新值可能会破坏污点标记保护。通过将被污染的值大写、将被污染的字符串值连接成较大的字符串、将被污染的值转换为 base64、对被污染的值进行子字符串操作以及其他类似的转换来创建的新值,除非明确调用 `taintUniqueValue` 污染这些新创建的值,否则它们不会被污染
* 不要使用 `taintUniqueValue` 保护诸如 PIN 码与电话号码这类低熵值。如果请求中的任何值都可以受攻击者控制,那么他们可以秘密枚举所有值来判断那个值是被污染的。

---

## 用法 {/*usage*/}

### 防止将令牌传递给客户端组件 {/*prevent-a-token-from-being-passed-to-client-components*/}

为了确保敏感信息(如密码、会话令牌或其他唯一值)不会被意外地传递给客户端组件,`taintUniqueValue` 函数提供了一层保护。当一个值被标记时,任何尝试将其传递给客户端组件的操作都将导致错误。
为了确保敏感信息(如密码、会话令牌或其他唯一值)不会被意外地传递给客户端组件,`taintUniqueValue` 函数提供了一层保护。当一个值被污染时,任何尝试将其传递给客户端组件的操作都将导致错误。

`lifetime` 参数定义了值保持受标记状态的持续时间。对于应该永久保持受标记状态的值,可以使用像 [`globalThis`](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/globalThis) 或 `process` 这样的对象作为 `lifetime` 参数。这些对象的生命周期跨越应用程序执行的整个持续时间。
`lifetime` 参数定义了值保持被污染的状态的持续时间。对于应该永久保持被污染的状态的值,可以使用像 [`globalThis`](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/globalThis) 或 `process` 这样的对象作为 `lifetime` 参数。这些对象的生命周期跨越应用程序执行的整个持续时间。

```js
import {experimental_taintUniqueValue} from 'react';
Expand All @@ -90,7 +90,7 @@ experimental_taintUniqueValue(
);
```

如果受标记值的寿命与某个对象相关联,那么 `lifetime` 应该是封装该值的对象。这样可以确保受标记值在封装对象的生命周期内保持受保护状态
如果被污染的值的寿命与某个对象相关联,那么 `lifetime` 应该是封装该值的对象。这样可以确保被污染的值在封装对象的生命周期内保持受保护状态

```js
import {experimental_taintUniqueValue} from 'react';
Expand All @@ -106,11 +106,11 @@ export async function getUser(id) {
}
```

在此示例中,`user` 对象用作 `lifetime` 参数。如果此对象存储在全局缓存中或可以被其他请求访问,会话令牌将保持受标记状态
在此示例中,`user` 对象用作 `lifetime` 参数。如果此对象存储在全局缓存中或可以被其他请求访问,会话令牌将保持被污染的状态

<Pitfall>

**不要仅依赖于标记来确保安全**。对一个值进行标记不会阻止每一个可能派生出的值。例如,通过将受标记的字符串大写来创建新值,将不会标记新值
**不要仅依赖于污点标记来确保安全**。污染一个值不会阻止每一个可能派生出的值。例如,通过将被污染的字符串大写来创建新值,将不会污染新值


```js
Expand All @@ -124,14 +124,14 @@ experimental_taintUniqueValue(
password
);

const uppercasePassword = password.toUpperCase() // `uppercasePassword` 不受标记
const uppercasePassword = password.toUpperCase() // `uppercasePassword` 不被污染
```

在此示例中,常量 `password` 受到标记。然后,通过在 `password` 上调用 `toUpperCase` 方法使用 `password` 创建新值 `uppercasePassword`。新创建的 `uppercasePassword` 不受标记
在此示例中,常量 `password` 被污染。然后,通过在 `password` 上调用 `toUpperCase` 方法使用 `password` 创建新值 `uppercasePassword`。新创建的 `uppercasePassword` 不被污染

从受标记值派生新值的其他类似方式,如将其连接到较大的字符串中、将其转换为 base64 或返回子字符串,会创建未受标记的值
从被污染的值派生新值的其他类似方式,如将其连接到较大的字符串中、将其转换为 base64 或返回子字符串,会创建未被污染的值

标记仅保护免受简单错误的影响,比如明确将机密值传递给客户端的错误。在调用 `taintUniqueValue` 时出现的错误,例如在 React 外部使用全局存储,没有相应的生命周期对象,可能会导致受标记的值变为未受标记。标记是一层保护,安全的应用程序将具有多层保护、精心设计的 API 和隔离模式。
污点标记仅保护免受简单错误的影响,比如明确将机密值传递给客户端的错误。在调用 `taintUniqueValue` 时出现的错误,例如在 React 外部使用全局存储,没有相应的生命周期对象,可能会导致被污染的值变为未被污染。污点标记是一层保护,安全的应用程序将具有多层保护、精心设计的 API 和隔离模式。

</Pitfall>

Expand Down Expand Up @@ -166,7 +166,7 @@ export async function Overview({ password }) {

[comment]: <> (TODO: 一旦 `server-only` 文档写好就就将其链接到对应处)

理想情况下,像这样的机密信息应该被抽象到一个单独的辅助文件中,只有服务器上的可信数据工具才能导入它。这个辅助文件甚至可以被标记为 [`server-only`](https://www.npmjs.com/package/server-only),以确保此文件不会在客户端被导入。
理想情况下,像这样的机密信息应该被抽象到一个单独的辅助文件中,只有服务器上的可信数据工具才能导入它。这个辅助文件甚至可以被污染为 [`server-only`](https://www.npmjs.com/package/server-only),以确保此文件不会在客户端被导入。

```js
import "server-only";
Expand All @@ -178,7 +178,7 @@ export function fetchAPI(url) {
```

有时,在重构过程中可能会发生错误,而且不是所有同事都可能知道这一点。
为了防止此类错误在后续发生,我们可以对实际密码进行“标记”:
为了防止此类错误在后续发生,我们可以对实际密码进行“污染”:

```js
import "server-only";
Expand Down
Loading