experimental_taintUniqueValue

taintUniqueValue(errMessage,lifetime,value)

• Reference
  • taintUniqueValue(message, lifetime, value)
• Usage
  • Prevent a token from being passed to Client Components

Reference

taintUniqueValue(message, lifetime, value)

CalltaintUniqueValue 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:

import{experimental_taintUniqueValue}from'react';

experimental_taintUniqueValue(
'Do not pass secret keys to the client.',
process,
process.env.SECRET_KEY
);

See more examples below.

Parameters

• message: The message you want to display ifvalue is passed to a Client Component. This message will be displayed as a part of the Error that will be thrown ifvalue is passed to a Client Component.

• lifetime: Any object that indicates how longvalue should be tainted.value will be blocked from being sent to any Client Component while this object still exists. For example, passingglobalThis blocks the value for the lifetime of an app.lifetime is typically an object whose properties containsvalue.

• 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.

Returns

experimental_taintUniqueValue returnsundefined.

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 calltaintUniqueValue on these newly created values.
• Do not usetaintUniqueValue 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.

Usage

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, thetaintUniqueValue 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.

Thelifetime argument defines the duration for which the value remains tainted. For values that should remain tainted indefinitely, objects likeglobalThis orprocess can serve as thelifetime argument. These objects have a lifespan that spans the entire duration of your app’s execution.

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, thelifetime should be the object that encapsulates the value. This ensures the tainted value remains protected for the lifetime of the encapsulating object.

import{experimental_taintUniqueValue}from'react';

exportasyncfunctiongetUser(id){
constuser =awaitdb`SELECT * FROM users WHERE id =${id}`;
experimental_taintUniqueValue(
'Do not pass a user session token to the client.',
user,
user.session.token
);
returnuser;
}

In this example, theuser object serves as thelifetime argument. If this object gets stored in a global cache or is accessible by another request, the session token remains tainted.

import{experimental_taintUniqueValue}from'react';

constpassword ='correct horse battery staple';

experimental_taintUniqueValue(
'Do not pass the password to the client.',
globalThis,
password
);

constuppercasePassword =password.toUpperCase()// `uppercasePassword` is not tainted

exportasyncfunctionDashboard(props){
// DO NOT DO THIS
return<Overviewpassword={process.env.API_PASSWORD}/>;
}

"use client";

import{useEffect}from'...'

exportasyncfunctionOverview({password}){
useEffect(()=>{
constheaders ={Authorization:password};
fetch(url,{headers}).then(...);
},[password]);
...
}

import"server-only";

exportfunctionfetchAPI(url){
constheaders ={Authorization:process.env.API_PASSWORD};
returnfetch(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
);