experimental_taintUniqueValue

Довідник

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 буде передано клієнтському компоненту.

• lifetime: Будь-який об'єкт, який вказує, як довго значення має бути зіпсованим. Значення буде заблоковано для надсилання до будь-якого клієнтського компонента, доки цей об'єкт існує. Наприклад, передача globalThis заблокує значення на весь час існування програми. lifetime зазвичай є об'єктом, властивості якого містять value.

• value: Рядок, bigint або типізований масив. 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 має бути об'єктом, який інкапсулює значення. Це гарантує, що зіпсоване значення залишатиметься захищеним протягом усього часу існування об'єкта, що його інкапсулює.

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