Skip to content

fix(media-use): audio scripts judge a received .env by the CLI's rule - #8086

Merged
michaelwang11394 merged 7 commits into
mainfrom
sec-low26d-1117
Nov 17, 2026
Merged

michaelwang11394 merged 7 commits into
mainfrom
sec-low26d-1117

Conversation

@michaelwang11394

Copy link
Copy Markdown
Contributor

What

The media-use audio scripts now decide whether a project .env came from someone else by the same rule as the CLI. Before, they used a smaller hand-kept copy of that rule.

  • packages/cli/src/media-use/lib/received-env.mjs is a dependency-free port of the CLI's received-project rule. The generated-copy script copies it into skills/media-use/scripts/lib/, and the copy-parity check keeps the two equal. heygen.mjs uses it in place of its old receivedEnvFile.
  • A .env now counts as received in these cases:
    • host state all at, above or below its folder;
    • host state expected with a missing record;
    • a host state file that is set but unreadable, missing or unknown;
    • a nested or unreadable received-files record;
    • a content-hash match, or an unreadable hash store;
    • the folder scan running out of budget.
  • The folder walk skips exactly the folders the CLI's walk skips, using a port of isStudioPrivatePath.
  • The CLI passes the keys it unset to the scripts it launches, in HYPERFRAMES_PROJECT_ENV_YIELDED. The scripts don't load those keys again from the same .env. Keys are matched by the folder's real path.
  • A .env the scripts find in a folder above the working one is judged by itself only: a record at or above its folder that lists it, matches its bytes or can't be read, or host state covering that folder or one above it. Siblings, subfolders and the scan limit don't change its status.

Why

The audio scripts can run directly, without the CLI in front of them. Their own copy of the rule ignored the host's received-state file, content hashes and nested records. So a shared project's .env key for ElevenLabs or Gemini could count as the person's own and receive their narration text or music prompts.

Related work

Stacked on #8056, which adds the note printed when a project .env provider key is used. Follows #8004, #8041 and #8025.

How

See What. The port is plain JavaScript so the skill can run without installing the CLI's packages. A parity test runs the CLI rule and the port over the same 25 sample projects and requires them to agree.

No visible change

Your own project's keys keep working. A key from a received project now gives way to your own credential in the audio scripts, as it already does in the CLI.

Test plan

  • Unit tests added/updated

  • Manual testing performed

  • Documentation updated (if applicable)

  • Comments follow CONTRIBUTING.md "Comments": they say why, not what, and a bug fix says what the code must do and how to reproduce the bug

  • fails without the fix: the new media-use tests fail on the previous heygen.mjs. A host state file naming the folder all leaves a received GEMINI_API_KEY in place, and a key the CLI yielded is loaded again from the same .env. The new parity cases, including hidden asset-named Studio folders, a folder named like a key file and the scan limit, differ from the CLI before the fix.

  • Parity, media-use, dotEnv and privateProjectFile tests (103), 267 media-use audio tests, copy-parity and import-boundary checks, cli tsc, oxlint, oxfmt, fallow, the comment ratchet and the citations check pass.

  • A home-level .env stays your own next to a received sibling project, and one the host marks as received still gives way.

  • Not run: Windows.

A provider key from a project .env is still used when no own credential
competes. Capture vision (OpenRouter, Gemini, Google and both Vertex parts),
snapshot --describe, Gemini speech and Lyria music now print one note per key
before it is first used, naming the variable and the escaped .env path, as
the ElevenLabs note does. The ignoring notes escape the path too, and the
media-use skill gets a generated copy of the CLI's terminal-text helper.
…ull rule

The audio scripts judged a project .env as received only from
received-files.json at or above it. They now use a generated copy of the
CLI's rule, which also reads the host's received-state file, nested records
and the received content hashes, and treats an unreadable one as received.
A parity test runs the CLI and the copy over the same projects.

A key the CLI unset from a .env is now passed to the scripts it launches,
so they do not load it again from the same file.
…y itself

The received-rule copy now skips folders by the CLI's exact private-path rule,
so a hidden Studio folder with an asset-like name is walked as the CLI walks
it. A .env the scripts find in a folder above the working one is judged only
by records and host state at or above that folder, so a received sibling or
a large parent folder cannot flip the person's own key. Keys the CLI unset
are matched by the folder's real path.
jrusso1020
jrusso1020 previously approved these changes Nov 17, 2026

@jrusso1020 jrusso1020 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at 7014d20ebf6a847de42eef2b3adaa2b2b1079a6f.

Approve. The port matches the CLI's received rule, the parity test really runs both sides, and both audio entry points that load a .env now go through it. I have three non-blocking notes below.

Need: yes, the standalone audio scripts used a narrower rule than the CLI and could take a received ElevenLabs/Gemini key · Size: ok, the PR's own delta is 12 files, +1362/-54, and 938 of those lines are the port plus its generated copy · Reuse: reuses the existing skill-copy generator and copy-parity check; the CLI rule itself cannot be imported because the skill runs without the CLI's packages · Simpler: already minimal for a dependency-free copy · Structure: one ask (Nit 1). I checked privateProjectFile.ts, receivedContent.ts, walkBudget.ts, projectRecords.ts and parsers/privatePath.ts. The port mirrors them function for function and adds no new abstraction. The PR bundles nothing separable.

Risk: medium — it decides which provider key gets narration text and music prompts in scripts that run without the CLI, and it is a hand-kept second copy of a security rule.

What the 167-file / +5616 number is

It is not a rebase accident. Commit a2cc6d31 merges origin/main (df31ce2b) into sec-low26c-1117. The base branch on GitHub is still at #8056's head caa1b64c, so GitHub's diff also counts every main commit since then.

  • git diff caa1b64c a2cc6d31 gives 155 files, +4254/-446. That is all main.
  • git diff a2cc6d31 7014d20e gives 12 files, +1362/-54. That is this PR.
  • The merge is clean. git merge-tree --write-tree caa1b64c df31ce2b gives tree cce2d56e, which is exactly a2cc6d31^{tree}, so no hand edits are hidden in the merge.
  • caa1b64c (#8056 head) is an ancestor of this head. The head also merges cleanly with current main (a56fa2ca).

Nothing has to be fixed before merge. Once #8056 lands, a restack onto main would bring the PR view back to the 12 real files. That helps later readers but does not block.

Port vs CLI, side by side

I read received-env.mjs against receivedFiles / receivedRecordStatus / readRecord / receivedRecordsAtOrAbove / receivedRecordsBelow / host-state parsing in privateProjectFile.ts, readReceivedContent / contentHash in receivedContent.ts, walkBudget.ts, recordKind in projectRecords.ts and isStudioPrivatePath / projectPathSegments in parsers/src/privatePath.ts.

  • They are the same function for function: record kinds, host-state all/expected/identity/unreadable, the overlap test above and below, the nested-record prefixing, the 20,000-entry / 2 s walk budget, the no-follow read of the hash store, the code-file hash limit, and the gone-file rule.
  • Two differences have no effect on results. The CLI caches parsed host state, and the regex [. ]+$ replaces the trailing dot/space loop.
  • The order of checks differs (listed, then hash, then gone, instead of an OR of all three), but every branch returns "received", so the answer is the same.
  • The parity test is real. Each of the 25 cases runs receivedFiles/receivedRecordStatus and receivedFileState on the same tree, and both must equal the expected value (receivedEnv.parity.test.ts).

Entry points

loadEnvFromDir has three callers: heygen-tts.mjs:66, heygen-voice.mjs:96 and audio.mjs:120. All of them go through untrustedOrigin → receivedFileState. lyria-recipe.py mentions python-dotenv in a comment but never calls load_dotenv. It reads only the inherited env, which already has the yield applied. No other script in skills/media-use reads a .env.

Yielded keys

  • Under the CLI: the CLI loads only cwd/.env and keys yields by resolve(dir). The script skips <realpath(dir)>\0<key> for whichever .env it finds first (heygen.mjs loadFirstEnvFile). So a script that reaches the same .env from a child folder, or through a symlink, still leaves the key out.
  • Standalone: HYPERFRAMES_PROJECT_ENV_YIELDED is empty and the full rule decides. A .env found above the working folder uses the at-or-above-only mode.

Findings

  • Nit 1 (Structure): received-env.mjs is now the third copy of isStudioPrivatePath/projectPathSegments, alongside parsers and core's re-export. The copy-parity check only keeps the two .mjs files equal. A new credential folder or loaded-asset type added to parsers/src/privatePath.ts won't fail any test unless a parity fixture happens to touch it. Cheap fix: export the port's isStudioPrivatePath and add one test that compares it with the parsers one over a path corpus (the existing privatePath test inputs would do).
  • Nit 2 (test gap): no test covers the at-or-above-only host-state branch (states !== null && (states.unreadable || allReceivedAtOrAbove(...))). I replaced it with false and all 51 heygen tests still passed. The existing parent test passes through readRecord instead, because no record exists there. Fix: add a case with a readable record in the parent that lists only index.html, plus host state all naming that parent, and expect the key to give way.
  • Nit 3: at-or-above-only mode also skips the gone-listed-file rule (receivedFileState, last line). For a .env that is not a code file, that only matters when the parent .env links outside the project and a listed file is gone. That is narrow, but the docstring doesn't say this branch is dropped. Either keep mayBeGoneFile in both modes or add a line to the comment.

Evidence

  • bun install --frozen-lockfile, then built parsers, lint, core, engine, producer and studio-server.
  • vitest run receivedEnv.parity.test.ts commands/media-use.test.ts utils/dotEnv.test.ts utils/privateProjectFile.test.ts → 4 files, 103 passed. This matches the PR body.
  • node --test skills/media-use/audio/scripts/lib/heygen.test.mjs → 51/51. node --test scripts/check-media-use-copy-parity.test.mjs → 4/4.
  • Mutants, each restored afterwards:
    • Dropping the hidden-asset exception in the port's isStudioPrivatePath → parity 2 failed.
    • Dropping the hash match → parity 1 failed.
    • Dropping the gone-file rule → parity 1 failed.
    • Ignoring the yielded set in heygen.mjs → 2 failed.
    • Yield matching without realpath → 1 failed (the symlink test).
    • Forcing the full walk for a parent .env → 1 failed (the received-sibling test).
    • Host-state-unreadable → not all and overlap-below removed both survived. Both are covered by a second path that has the same effect (allReceivedAround returns true when the state is unreadable; the walk's readRecord sees host state on the subfolder), so they are equivalent mutants.
    • The parent host-state branch survived (Nit 2).
  • CI at this head: 24 pass, 11 pending (regression shards), 1 skipped, none failing. No other reviews yet.
  • Stack state: #8056 head caa1b64c is an ancestor of this head. This approval covers the #8086 increment (a2cc6d31..7014d20e) only.

— Rames

Base automatically changed from sec-low26c-1117 to main November 17, 2026 17:14
@michaelwang11394
michaelwang11394 dismissed jrusso1020’s stale review November 17, 2026 17:14

The base branch was changed.

@mintlify

mintlify Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
hyperframes 🟢 Ready View Preview Nov 17, 2026, 6:52 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

# Conflicts:
#	scripts/generate-skill-module-copies.mjs
#	skills-manifest.json
#	skills/media-use/audio/scripts/lib/heygen.mjs
@michaelwang11394

Copy link
Copy Markdown
Contributor Author

#8056 has merged, so this PR now targets main. I merged main in (c41db98). The three conflicting files already held #8056's code, so the diff against main is the same 12 files as before. The touched CLI tests, the parity test, the media-use audio tests, copy-parity, tsc, oxlint and oxfmt pass.

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Edit accuracy: accurate 267 (base branch 267), smooth 75 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (8)

@eddy-heygen eddy-heygen left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Eddy's agent) Reviewed by Eddy's Claude agent at commit c41db98.

Verdict: approved, good to ship.

Summary. The audio scripts used a smaller hand-kept rule to decide whether a project .env came from someone else, so a received provider key could be treated as the person's own. The PR replaces it with a dependency-free port of the CLI rule (host received-state file, nested and unreadable records, content hashes, scan budget), copied into the skill and held equal by the copy-parity check and a 25-fixture parity test. The CLI also now tells the scripts it launches which keys it unset, and they do not reload those from the same .env.

Approved. Reviewed at 7014d20 while the PR was stacked; it now targets main at c41db98 with the same change (I compared the two diffs line for line: identical, 12 files). I read the audio-script change myself: the hand-kept copy of the rule is gone, the script asks the ported CLI rule, and keys the CLI already set aside are not loaded again from the same file.

Blockers

None.

Non-blockers

  1. skills/media-use/scripts/lib/received-env.mjs:322: A .env in a folder above the working one is not judged by the full CLI rule. When the script walks up and loads a .env from a parent folder, heygen.mjs:149 sets atOrAboveOnly, so received-env.mjs:322-327 and :458 skip records below that folder, host state 'all' on a folder under it, the scan budget and the gone-file rule. Example: the .env sits in /x/P, the host marks only /x/P/video as all received, and the script runs in /x/P/video: the CLI rule on /x/P says received, the port says own. I could not show that a sender can place a .env above the folder the host marks (that lies outside the received boundary), so this is a stated remainder, not a proven bypass. The base branch ignored host state entirely, so the PR still narrows the gap. To resolve: Owner to confirm the host always marks the outermost folder holding received content. If not, in parent mode also treat the .env as received when the working folder itself is at or under a folder marked 'all'. Add a parity or unit fixture for the parent mode either way.
  2. skills/media-use/audio/scripts/lib/heygen.mjs:152: A person's own key can be dropped when the project tree is too large to scan. receivedFileState returns 'unchecked' past 20,000 folders or 2 seconds, and keyRank (heygen.mjs:158-161) ranks that like received. Running a script from a very large folder with your own voice vendor key in ./.env and a saved HeyGen login unsets the key, so an explicit voice vendor provider choice then fails. This is fail-closed and matches the over-budget criterion, but the CLI never yields an voice vendor key, and the result depends on a 2 second clock. To resolve: Accept as intended fail-closed behaviour and document it, or check for a competing credential before running the walk so the common case skips it.
  3. skills/media-use/audio/scripts/lib/heygen.mjs:117: Yielded-key match compares folders with a realpath that does not normalise letter case. realFolder uses realpathSync, while the port uses realpathSync.native. On a case-insensitive volume, if the CLI yielded a key for one spelling of a folder and the script is given another letter-case spelling, the ids at heygen.mjs:130 and :239 differ and the script reloads the key the CLI had unset. The reloaded key is then judged by the full rule again, so the exposure is limited to cases where that rule passes it. To resolve: Use realpathSync.native (with the same EISDIR fallback) in realFolder.
  4. skills/media-use/scripts/lib/received-env.mjs:423: Same-file match now ignores listed entries outside the working folder. The removed script rule matched a .env that is a hard link to any entry listed in a record above it. The port, like the CLI (privateProjectFile.ts:425), only compares listed entries at or under the working folder. A record above that lists sibling/.env no longer marks a hard link to it in the working folder as received unless a content hash is stored. This is exact CLI parity and needs an unlisted hard link to exist, so it is low risk. To resolve: Accept as CLI parity, or raise it against the CLI rule so both change together.

What the change needed to do

  • n/a (public repository: ids withheld): The script calls a project .env received whenever the CLI rule would: host state 'all' at, above or below the folder; 'expected' with a missing record; unreadable or unknown state file; content-hash match or unreadable hash store; unreadable nested record; unknown states fail closed: partly met (packages/cli/src/media-use/lib/received-env.mjs:448-459 mirrors receivedFiles/receivedRecordStatus in packages/cli/src/utils/privateProjectFile.ts:387-485 branch for branch for a .env in the working folder. For a .env found in a folder above the working one (skills/media-use/audio/scripts/lib/heygen.mjs:149, received-env.mjs:322-327) state and records below that folder, the scan budget and the gone-file rule are deliberately not applied.)
  • n/a (public repository: ids withheld): A parity test runs both rules over the same fixtures, including a host-state-marked folder with an unlisted .env, and a test confirms a received voice vendor or Gemini key is dropped when the person holds a competing credential: met (packages/cli/src/media-use/receivedEnv.parity.test.ts:180-214 asserts the CLI rule and the port both equal the expected value per fixture; skills/media-use/audio/scripts/lib/heygen.test.mjs:777-812 drops a received voice vendor key (host state 'all') and a received Gemini key (content hash). Parity fixtures only cover the full rule, not the parent-folder mode.)
  • n/a (public repository: ids withheld): A key the launching CLI yielded for a given .env folder stays unset in the scripts it starts, with a test: met (packages/cli/src/commands/media-use.ts:98 passes the yielded list; skills/media-use/audio/scripts/lib/heygen.mjs:239 skips a yielded key for that real folder; heygen.test.mjs:814-858 covers same folder, a linked spelling, and another folder.)

CI: all checks pass at c41db98 (the rest are skipped by path).

How this was reviewed: a code-review pass and a security-review pass, by a reviewer agent in an isolated checkout of this commit; I then read the core of the fix and the cited lines myself. Nothing was built or run.

@michaelwang11394
michaelwang11394 added this pull request to the merge queue Nov 17, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 17, 2026
The CLI's private-file rule now treats a hidden file as private whatever its type,
and framework build-output folders and service-account key names as private.
The media-use copy of the rule follows it, so the parity cases for hidden
asset-named Studio folders agree again.
@michaelwang11394

Copy link
Copy Markdown
Contributor Author

This PR fell out of the merge queue at 18:09 UTC with a real failure, not a flaky one. #7990 merged after this branch's last update and narrowed the CLI's private-file rule: a hidden file is private whatever its type, and build-output folders and service-account key names are private too. The media-use copy of the rule in this PR still had the old version, so two parity cases (records in hidden, asset-named Studio folders) failed.

Fix: I merged main in (ce97c9b), ported #7990's rule into received-env.mjs and its generated copy (648f585), and updated the two parity cases to the CLI's new answer, which is that the walk skips those folders. The parity and received tests pass 62/62 against freshly built packages. Lint, format, fallow, typecheck and the copy-parity check pass. @eddy-heygen, could you re-approve at the new head?

@eddy-heygen eddy-heygen left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Eddy's agent) Re-review by Eddy's Claude agent at commit 648f585.

Verdict: approved, good to ship.

What changed since c41db98 (I compared the two PR diffs line for line). The media-use copy of the received rule now carries the narrowed private-file check that landed on the default branch in #7990 (which I reviewed and approved): the extra credential file names, the build-output folders, and no asset exception for a hidden file name. Two parity cases changed to match, because the walk now skips those folders, and one generated hash moved with the copy. Nothing else in the diff changed.

Blockers

None.

CI: all checks pass at this commit (the rest are skipped by path).

How this was reviewed: an earlier round was a code-review pass and a security-review pass by a reviewer agent; I compared the diff since then myself. Nothing was built or run.

@michaelwang11394
michaelwang11394 added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit bc5259d Nov 17, 2026
84 checks passed
@michaelwang11394
michaelwang11394 deleted the sec-low26d-1117 branch November 17, 2026 19:54

This branch was successfully deployed

1 active deployment
staging - docs — 648f585c Deployed Nov 17, 2026 by mintlify[bot]
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.

3 participants