Skip to content

Перевод experimental_taintUniqueValue.md на русский язык #1214

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.

Sign up for GitHub

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

Open
NivaldoFarias wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Перевод experimental_taintUniqueValue.md на русский язык #1214

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
90 changes: 45 additions & 45 deletions src/content/reference/react/experimental_taintUniqueValue.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,113 +5,113 @@ version: experimental

<Experimental>

**This API is experimental and is not available in a stable version of React yet.**
**Этот API является экспериментальным и пока недоступен в стабильной версии React.**

You can try it by upgrading React packages to the most recent experimental version:
Вы можете попробовать его, обновив пакеты React до последней экспериментальной версии:

- `react@experimental`
- `react-dom@experimental`
- `eslint-plugin-react-hooks@experimental`

Experimental versions of React may contain bugs. Don't use them in production.
Экспериментальные версии React могут содержать ошибки. Не используйте их в продакшене.

This API is only available inside [React Server Components](/reference/rsc/use-client).
Этот API доступен только внутри [React Server Components](/reference/rsc/use-client).

</Experimental>


<Intro>

`taintUniqueValue` lets you prevent unique values from being passed to Client Components like passwords, keys, or tokens.
`taintUniqueValue` позволяет предотвратить передачу уникальных значений, таких как пароли, ключи или токены, в компоненты клиента.

```js
taintUniqueValue(errMessage, lifetime, value)
```

To prevent passing an object containing sensitive data, see [`taintObjectReference`](/reference/react/experimental_taintObjectReference).
Чтобы предотвратить передачу объекта, содержащего конфиденциальные данные, см. [`taintObjectReference`](/reference/react/experimental_taintObjectReference).

</Intro>

<InlineToc />

---

## Reference {/*reference*/}
## Справочник {/*reference*/}

### `taintUniqueValue(message, lifetime, value)` {/*taintuniquevalue*/}

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:
Вызовите `taintUniqueValue` с паролем, токеном, ключом или хешем, чтобы зарегистрировать его в React как нечто, что не должно быть передано клиенту в исходном виде:

```js
import {experimental_taintUniqueValue} from 'react';

experimental_taintUniqueValue(
'Do not pass secret keys to the client.',
'Не передавайте секретные ключи клиенту.',
process,
process.env.SECRET_KEY
);
```

[See more examples below.](#usage)
[См. больше примеров ниже.](#usage)

#### Parameters {/*parameters*/}
#### Параметры {/*parameters*/}

* `message`: The message you want to display if `value` is passed to a Client Component. This message will be displayed as a part of the Error that will be thrown if `value` is passed to a Client Component.
* `message`: Сообщение, которое вы хотите отобразить, если `value` будет передано в компонент клиента. Это сообщение будет отображено как часть ошибки, которая будет выброшена, если `value` будет передано в компонент клиента.

* `lifetime`: Any object that indicates how long `value` should be tainted. `value` will be blocked from being sent to any Client Component while this object still exists. For example, passing `globalThis` blocks the value for the lifetime of an app. `lifetime` is typically an object whose properties contains `value`.
* `lifetime`: Любой объект, указывающий, как долго `value` будет помечено как "tainted" (скомпрометированное). `value` будет заблокировано от отправки в любой компонент клиента, пока этот объект существует. Например, передача `globalThis` блокирует значение на время жизни приложения. `lifetime` обычно является объектом, свойства которого содержат `value`.

* `value`: A string, bigint or TypedArray. `value` must be a unique sequence of characters or bytes with high entropy such as a cryptographic token, private key, hash, or a long password. `value` will be blocked from being sent to any Client Component.
* `value`: Строка, bigint или TypedArray. `value` должно быть уникальной последовательностью символов или байтов с высокой энтропией, такой как криптографический токен, закрытый ключ, хеш или длинный пароль. `value` будет заблокировано от отправки в любой компонент клиента.

#### Returns {/*returns*/}
#### Возвращает {/*returns*/}

`experimental_taintUniqueValue` returns `undefined`.
`experimental_taintUniqueValue` возвращает `undefined`.

#### Caveats {/*caveats*/}
#### Оговорки {/*caveats*/}

* Deriving new values from tainted values can compromise tainting protection. New values created by uppercasing tainted values, concatenating tainted string values into a larger string, converting tainted values to base64, substringing tainted values, and other similar transformations are not tainted unless you explicitly call `taintUniqueValue` on these newly created values.
* 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.
* Получение новых значений из "tainted" значений может скомпрометировать защиту "tainting". Новые значения, созданные путем преобразования "tainted" значений в верхний регистр, объединения "tainted" строковых значений в более крупную строку, преобразования "tainted" значений в base64, извлечения подстроки из "tainted" значений и других подобных преобразований, не будут "tainted", если вы явно не вызовете `taintUniqueValue` для этих вновь созданных значений.
* Не используйте `taintUniqueValue` для защиты значений с низкой энтропией, таких как PIN-коды или номера телефонов. Если любое значение в запросе контролируется злоумышленником, он может вывести, какое значение "tainted", перечисляя все возможные значения секрета.

---

## Usage {/*usage*/}
## Использование {/*usage*/}

### Prevent a token from being passed to Client Components {/*prevent-a-token-from-being-passed-to-client-components*/}
### Предотвращение передачи токена в компоненты клиента {/*prevent-a-token-from-being-passed-to-client-components*/}

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.
Чтобы гарантировать, что конфиденциальная информация, такая как пароли, токены сеанса или другие уникальные значения, случайно не передается в компоненты клиента, функция `taintUniqueValue` обеспечивает уровень защиты. Когда значение помечено как "tainted", любая попытка передать его в компонент клиента приведет к ошибке.

The `lifetime` argument defines the duration for which the value remains tainted. For values that should remain tainted indefinitely, objects like [`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) or `process` can serve as the `lifetime` argument. These objects have a lifespan that spans the entire duration of your app's execution.
Аргумент `lifetime` определяет продолжительность, в течение которой значение остается "tainted". Для значений, которые должны оставаться "tainted" бессрочно, в качестве аргумента `lifetime` могут выступать такие объекты, как [`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) или `process`. Эти объекты имеют жизненный цикл, охватывающий все время выполнения вашего приложения.

```js
import {experimental_taintUniqueValue} from 'react';

experimental_taintUniqueValue(
'Do not pass a user password to the client.',
'Не передавайте пароль пользователя клиенту.',
globalThis,
process.env.SECRET_KEY
);
```

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.
Если жизненный цикл "tainted" значения связан с объектом, `lifetime` должен быть объектом, который инкапсулирует это значение. Это гарантирует, что "tainted" значение останется защищенным в течение всего жизненного цикла инкапсулирующего объекта.

```js
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;
}
```

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.
В этом примере объект `user` выступает в качестве аргумента `lifetime`. Если этот объект будет сохранен в глобальном кеше или будет доступен другому запросу, токен сеанса останется "tainted".

<Pitfall>

**Do not rely solely on tainting for security.** Tainting a value doesn't block every possible derived value. For example, creating a new value by upper casing a tainted string will not taint the new value.
**Не полагайтесь исключительно на "tainting" для безопасности.** Пометка значения как "tainted" не блокирует все возможные производные значения. Например, создание нового значения путем преобразования "tainted" строки в верхний регистр не сделает новое значение "tainted".


```js
Expand All @@ -120,31 +120,31 @@ 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
const uppercasePassword = password.toUpperCase() // `uppercasePassword` не помечен как "tainted"
```

In this example, the constant `password` is tainted. Then `password` is used to create a new value `uppercasePassword` by calling the `toUpperCase` method on `password`. The newly created `uppercasePassword` is not tainted.
В этом примере константа `password` помечена как "tainted". Затем `password` используется для создания нового значения `uppercasePassword` путем вызова метода `toUpperCase` для `password`. Вновь созданное значение `uppercasePassword` не помечено как "tainted".

Other similar ways of deriving new values from tainted values like concatenating it into a larger string, converting it to base64, or returning a substring create untained values.
Другие аналогичные способы получения новых значений из "tainted" значений, такие как объединение их в более крупную строку, преобразование в base64 или возврат подстроки, создают не "tainted" значения.

Tainting only protects against simple mistakes like explicitly passing secret values to the client. Mistakes in calling the `taintUniqueValue` like using a global store outside of React, without the corresponding lifetime object, can cause the tainted value to become untainted. Tainting is a layer of protection; a secure app will have multiple layers of protection, well designed APIs, and isolation patterns.
"Tainting" защищает только от простых ошибок, таких как явная передача секретных значений клиенту. Ошибки при вызове `taintUniqueValue`, такие как использование глобального хранилища вне React, без соответствующего объекта жизненного цикла, могут привести к тому, что "tainted" значение станет не "tainted". "Tainting" — это уровень защиты; безопасное приложение будет иметь несколько уровней защиты, хорошо спроектированные API и шаблоны изоляции.

</Pitfall>

<DeepDive>

#### Using `server-only` and `taintUniqueValue` to prevent leaking secrets {/*using-server-only-and-taintuniquevalue-to-prevent-leaking-secrets*/}
#### Использование `server-only` и `taintUniqueValue` для предотвращения утечки секретов {/*using-server-only-and-taintuniquevalue-to-prevent-leaking-secrets*/}

If you're running a Server Components environment that has access to private keys or passwords such as database passwords, you have to be careful not to pass that to a Client Component.
Если вы используете среду Server Components, имеющую доступ к закрытым ключам или паролям, таким как пароли баз данных, вы должны быть осторожны, чтобы не передавать их в Client Component.

```js
export async function Dashboard(props) {
// DO NOT DO THIS
// НЕ ДЕЛАЙТЕ ЭТОГО
return <Overview password={process.env.API_PASSWORD} />;
}
```
Expand All @@ -163,11 +163,11 @@ export async function Overview({ password }) {
}
```

This example would leak the secret API token to the client. If this API token can be used to access data this particular user shouldn't have access to, it could lead to a data breach.
Этот пример приведет к утечке секретного API-токена клиенту. Если этот API-токен может быть использован для доступа к данным, к которым данный пользователь не должен иметь доступа, это может привести к утечке данных.

[comment]: <> (TODO: Link to `server-only` docs once they are written)
[comment]: <> (TODO: Добавить ссылку на документацию `server-only`, как только она будет написана)

Ideally, secrets like this are abstracted into a single helper file that can only be imported by trusted data utilities on the server. The helper can even be tagged with [`server-only`](https://www.npmjs.com/package/server-only) to ensure that this file isn't imported on the client.
В идеале, такие секреты должны быть абстрагированы в отдельный вспомогательный файл, который может быть импортирован только доверенными утилитами данных на сервере. Вспомогательный файл может быть даже помечен как [`server-only`](https://www.npmjs.com/package/server-only), чтобы гарантировать, что этот файл не будет импортирован на клиенте.

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

Sometimes mistakes happen during refactoring and not all of your colleagues might know about this.
To protect against this mistakes happening down the line we can "taint" the actual password:
Иногда при рефакторинге случаются ошибки, и не все ваши коллеги могут знать об этом.
Чтобы защититься от таких ошибок в будущем, мы можем "пометить" фактический пароль:

```js
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.'
'Не передавайте пароль API-токена клиенту. ' +
'Вместо этого выполняйте все запросы на сервере.'
process,
process.env.API_PASSWORD
);
```

Now whenever anyone tries to pass this password to a Client Component, or send the password to a Client Component with a Server Function, an error will be thrown with message you defined when you called `taintUniqueValue`.
Теперь, когда кто-либо попытается передать этот пароль в Client Component или отправить пароль в Client Component с помощью Server Function, будет выброшена ошибка с сообщением, которое вы определили при вызове `taintUniqueValue`.

</DeepDive>

---
---
Loading