Add Experimental Taint API Docs

[sebmarkbage]

These are still experimental. I haven't linked to them from anywhere yet.

Previews:

• taintUniqueValue
• taintObjectReference

[github-actions]

Size changes

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

One Page Changed Size

The following page changed size from the code in this PR compared to its base branch:

Page	Size (compressed)	First Load
/[[...markdownPath]]	78.38 KB (🟡 +36 B)	182.33 KB

Details

Only the gzipped size is provided here based on an expert tip.

First Load is the size of the global bundle plus the bundle for the individual page. If a user were to show up to your website and land on a given page, the first load size represents the amount of javascript that user would need to download. If next/link is used, subsequent page loads would only need to download that page's bundle (the number in the "Size" column), since the global bundle has already been downloaded.

Any third party scripts you have added directly to your app using the <script> tag are not accounted for in this analysis

Next to the size is how much the size has increased or decreased compared with the base branch of this PR. If this percentage has increased by 10% or more, there will be a red status indicator applied, indicating that special attention should be given to this.

[mattcarrollcode]

This is great! Thank you for doing this. This makes a huge difference in being able to document these APIs early. You writing the initial docs takes so much back and forth out of the equation, and makes write the docs so much more pleasant!

I did a quick pass and added some thoughts. I'm also happy to take this PR over and make the changes I suggested if you like.

Another general thought: We should probably add this to the ToC with some kind of label like canary to indicate this is an experimental API (but I can do this after the fact if you like)

[sebmarkbage]

I'm also happy to take this PR over and make the changes I suggested if you like.

Yea, please take it over with whatever change you'd like.

[sebmarkbage]

lgtm. Left some nits.

[gnoff]

Might need to go in a separate PR but we should change the API ordering to sort based on the first letter of the string after experimental_ This will help keep the order stable when the experimental prefix is removed and make it clearer where to find the API when you only know it by it's semantic name, "taint" for instance

alternatively consider putting all experimental references at the end of the list

[mattcarrollcode]

Might need to go in a separate PR but we should change the API ordering to sort based on the first letter of the string after experimental_ This will help keep the order stable when the experimental prefix is removed and make it clearer where to find the API when you only know it by it's semantic name, "taint" for instance

alternatively consider putting all experimental references at the end of the list

Good note. I'll add the experimental APIs at the end of the list for now.

[sophiebits]

Did you want to mention that the value taint lives through the end of a request?

[sebmarkbage]

The way it's described is in terms of the reverse, that it only gets promoted if the object outlives the request.

If this object gets stored in a global cache or is accessible by another request, the session token remains tainted.

Not sure the intricacies are important for knowing how it's used. It might be important if you're vetting the implementation details but you should probably assume it works as described otherwise.