Skip to content

fix(webapi): protect native records with private types - #404

Draft
jderochervlk wants to merge 9 commits into
mainfrom
fix/403-private-native-records
Draft

jderochervlk wants to merge 9 commits into
mainfrom
fix/403-private-native-records

Conversation

@jderochervlk

@jderochervlk jderochervlk commented Nov 8, 2026 •

Copy link
Copy Markdown
Collaborator

Private-record migration for #403, updated with current main and ReScript 13.0.0-alpha.7 from #414. Native records retain direct field reads, use typed setters for supported mutation, and reject ordinary record construction, updates, and structural coercion into private types. Caller-owned options, initializers, and callback dictionaries remain constructible.

The branch now specializes native identity upcasts on concrete receiver modules rather than exposing arbitrary-receiver identity casts from public Impl functors. Existing inherited asNode, asElement, event, file, SVG, and audio conversion helpers remain available on concrete modules. Stream reader/writer and rendering-context placeholders have abstract identities; performance entry lists are ordinary arrays of native entries, and NodeFilter is a caller-owned callback dictionary.

Additional boundary fixes make Canvas-style and intersection-root downcasts checked option results, give media-key access a concrete result type, and model omitted MessageEvent data as nullable. Public media, DOM-node, and geometry setters cover audited write paths. Review fixes preserve the template shadow-mode empty string, require native Float32Array values for WaveShaper curves, remove setters for readonly output/textarea type properties, restore concrete base conversions for Attr/CDATA/ProcessingInstruction, and preserve annotated throwing setter behavior. The docs renderer also preserves callback-type links in record fields.

The checked inventory covers 294 public modules and records private backings/views, abstract identities, public setter routes, constructible exceptions, and remaining modeling gaps. Packed-consumer regressions cover construction/coercion rejection, removed generic identity routes, checked conversions, concrete inherited helpers, and warning-free setters. Native browser workflows exercise the changed boundaries.

Why this remains a draft

This is not yet a package-wide native-instance soundness guarantee. Independent review and an alpha.7 compiler/runtime probe confirmed that public generic Impl methods can still return a fabricated native value from a caller-owned receiver, even after their identity upcasts are removed. Resolving that requires hiding/constraining generic binding functors or explicitly treating their instantiation as trusted FFI outside the guarantee.

Other explicit gaps remain:

  • Event callbacks accept caller-selected payload types unrelated to their event descriptor; typed descriptors versus base-event callbacks needs an API decision.
  • Unknown native unions/results remain in canvas owners, stylesheet owner nodes, IndexedDB sources/cursors, DOM label lists, media/message sources, and generic crypto results.
  • Additional inherited write/conversion routes remain in DOMImplementation, HTMLOptionsCollection, and AudioWorklet.

The inventory and project-status documentation list these limitations. Passing declaration checks does not prove every exported binding sound. This PR remains draft pending those scope decisions and follow-up work; it does not close #403 automatically.

Refs #403.

@jderochervlk
jderochervlk changed the base branch from main to build/rescript-alpha-7 November 16, 2026 21:04
jderochervlk added a commit that referenced this pull request Nov 16, 2026
Upgrade the compiler baseline before continuing the private-record
migration in #404. ReScript 13.0.0-alpha.7 includes
rescript-lang/rescript#9125, which rejects coercion from another type
into a private record—the loophole reproduced on alpha.5 in #403.

Pin the development compiler and raise the minimum peer version to
alpha.7, update the lockfile and installation guidance, and reject the
former alpha.5 baseline in packed-consumer checks. Add a regression for
forged Response coercion alongside positive coverage for native
construction, direct field reads, outward coercion, and the existing
File-to-Blob helper. This does not introduce package-wide native-record
privacy.

The upgrade also requires a concrete typed-array operation in the
ImageData fixture and support for the compiler's new documentation
parameter/type schema. Preserve rendered signatures and type links,
including callbacks, tuples, and generic parameters. The changes across
40 existing ReScript files are the new compiler's formatting output.

Alpha.7 no longer supports native compilation on Intel Macs
(`darwin-x64`); the migration notes and project status call out that
compatibility break.

Refs #403. This is the prerequisite branch for #404, not the
private-record migration itself.
Base automatically changed from build/rescript-alpha-7 to main November 16, 2026 21:08
@jderochervlk

Copy link
Copy Markdown
Collaborator Author

Updated through 2c182af4 with current main/alpha.7. Merge conflicts are resolved; this remains a draft rather than a merge recommendation.

Local validation passed on Node 26: npm run format:check, npm run build, npm test, npm run check:features, npm run test:negative, npm run test:browser (four Chromium tests), npm run check:consumer, npm run build:docs, npm run check:docs-links, and npm run check:release.

An independent source review identified readonly-property setters, a WaveShaper typed-array mismatch, the missing template empty-string state, inherited conversion gaps, and lost throwing annotations. Those concrete findings were corrected and covered by the subsequent local checks. This is not independent approval of all later edits or a package-wide soundness guarantee.

The main remaining public-functor policy blocker was reproduced separately against the packed alpha.7 package:

module Receiver = {type t = {getRootNode: unit => string}}
module FakeNode = WebAPI.Node.Impl(Receiver)
let forged: WebAPI.Node.t =
  FakeNode.getRootNode({getRootNode: () => "not a node"})

This compiles without unsafe casts, raw JavaScript, consumer externals, or :>, and forged is a string at runtime. Removing generic identity upcasts closes those shortcuts but not arbitrary receiver instantiation of native-returning binding methods. Hiding/constraining that surface versus explicitly excluding it as trusted FFI needs a scope decision. The PR body and inventory also record callback typing, unknown native unions/results, and remaining inherited routes.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make native Web API object types private

1 participant