Skip to content

Commit

Permalink
docs(cn): standardize the translations of the word taint (#1361)
Browse files Browse the repository at this point in the history
  • Loading branch information
Yucohny authored Oct 30, 2023
1 parent 7b5f856 commit 1846584
Show file tree
Hide file tree
Showing 2 changed files with 19 additions and 19 deletions.
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

0 comments on commit 1846584

Please sign in to comment.