experimental_taintUniqueValue

taintUniqueValue(errMessage, lifetime, value)

• Referência
  • taintUniqueValue(message, lifetime, value)
• Uso
  • Impedir que um token seja passado para Componentes de Cliente

Referência

taintUniqueValue(message, lifetime, value)

Chame taintUniqueValue com uma senha, token, chave ou hash para registrá-lo com o React como algo que não deve ser permitido passar para o Cliente como está:

import {experimental_taintUniqueValue} from 'react';

experimental_taintUniqueValue(
  'Não passe chaves secretas para o cliente.',
  process,
  process.env.SECRET_KEY
);

Veja mais exemplos abaixo.

Parâmetros

• message: A mensagem que você deseja exibir se value for passado para um Componente de Cliente. Esta mensagem será exibida como parte do Erro que será lançado se value for passado para um Componente de Cliente.

• lifetime: Qualquer objeto que indique por quanto tempo value deve ser contaminado. value será bloqueado de ser enviado para qualquer Componente de Cliente enquanto este objeto ainda existir. Por exemplo, passar globalThis bloqueia o valor durante o tempo de vida de um aplicativo. lifetime é tipicamente um objeto cujas propriedades contêm value.

• value: Uma string, bigint ou TypedArray. value deve ser uma sequência exclusiva de caracteres ou bytes com alta entropia, como um token criptográfico, chave privada, hash ou uma senha longa. value será bloqueado de ser enviado para qualquer Componente de Cliente.

Retorna

experimental_taintUniqueValue retorna undefined.

Ressalvas

• Derivar novos valores de valores contaminados pode comprometer a proteção contra contaminação. Novos valores criados por uppercase de valores contaminados, concatenando valores de string contaminados em uma string maior, convertendo valores contaminados para base64, substringando valores contaminados e outras transformações semelhantes não são contaminados, a menos que você explicitamente chame taintUniqueValue nesses valores recém-criados.
• Não use taintUniqueValue para proteger valores de baixa entropia, como códigos PIN ou números de telefone. Se algum valor em uma solicitação for controlado por um invasor, ele poderá inferir qual valor está contaminado enumerando todos os valores possíveis do segredo.

Uso

Impedir que um token seja passado para Componentes de Cliente

Para garantir que informações confidenciais, como senhas, tokens de sessão ou outros valores exclusivos, não sejam passados inadvertidamente para Componentes de Cliente, a função taintUniqueValue oferece uma camada de proteção. Quando um valor é contaminado, qualquer tentativa de passá-lo para um Componente de Cliente resultará em um erro.

O argumento lifetime define a duração em que o valor permanece contaminado. Para valores que devem permanecer contaminados indefinidamente, objetos como globalThis ou process podem servir como argumento lifetime. Esses objetos têm um tempo de vida que abrange toda a duração da execução do seu aplicativo.

import {experimental_taintUniqueValue} from 'react';

experimental_taintUniqueValue(
  'Não passe uma senha de usuário para o cliente.',
  globalThis,
  process.env.SECRET_KEY
);

Se o tempo de vida do valor contaminado estiver ligado a um objeto, o lifetime deve ser o objeto que encapsula o valor. Isso garante que o valor contaminado permaneça protegido durante a vida útil do objeto encapsulador.

import {experimental_taintUniqueValue} from 'react';

export async function getUser(id) {
  const user = await db`SELECT * FROM users WHERE id = ${id}`;
  experimental_taintUniqueValue(
    'Não passe um token de sessão do usuário para o cliente.',
    user,
    user.session.token
  );
  return user;
}

Neste exemplo, o objeto user serve como argumento lifetime. Se este objeto for armazenado em um cache global ou for acessível por outra requisição, o token da sessão permanecerá contaminado.

import {experimental_taintUniqueValue} from 'react';

const password = 'correct horse battery staple';

experimental_taintUniqueValue(
  'Não passe a senha para o cliente.',
  globalThis,
  password
);

const uppercasePassword = password.toUpperCase() // `uppercasePassword` não está contaminado

export async function Dashboard(props) {
  // NÃO FAÇA ISSO
  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(
  'Não passe a senha do token da API para o cliente. ' +
    'Em vez disso, faça todas as buscas no servidor.'
  process,
  process.env.API_PASSWORD
);