Summary

• Problem: src/media/ exposes MIME and audio-classification primitives, but there is no shared seam that distinguishes the caller-provided classified kind of a media payload from filename/URL hints, and no shared seam that normalizes a free-form MIME string before it reaches an outbound header. Adapter and core paths inline ad hoc checks that drift over time.
• Why it matters: a single shared helper surface makes follow-up call-site work small and reviewable, and lets reviewers compare a single trust boundary instead of N inlined regexes.
• What changed: two helpers added at the end of src/media/mime.ts and re-exported via the existing src/plugin-sdk/media-runtime.ts wildcard barrel: isVerifiedAudioSource(media: { kind?, contentType? }) and sanitizeMediaMime(input, options?). Tests added in src/media/mime.test.ts. Brief CHANGELOG entry added under ### Changes for plugin-author visibility.
• What did NOT change (scope boundary): no callers added, no runtime behavior change, no API generalization (no expectedPrefix option, no isVerifiedMediaSource(media, kind) shape), no cross-channel adapter changes, no docs.

Supporting context: the helper-only / adopter-PR split direction was previously affirmed by the maintainer in the close note on #68744.

Trust model

isVerifiedAudioSource reads only the caller-provided classified kind field. It does not infer audio from filename or URL hints, and a contentType starting with audio/ is not enough on its own (a remote sender can set the HTTP Content-Type). The contentType field is kept on the parameter shape as a seam for a later sniffed-MIME extension via detectMime, but it is not read today.

sanitizeMediaMime validates a MIME string against the RFC 2045 token character set (broader than RFC 6838's restricted-name, to admit valid vendor types such as application/vnd.x~v1+json), strips ASCII control characters and DEL, lowercases the type/subtype, and by default strips all parameters. preserveCodecsParam: true preserves common single-codec, multi-codec, and quoted codecs=... parameters when present (e.g. audio/ogg; codecs=opus, audio/mp4; codecs=mp4a.40.2,opus, video/mp4; codecs="avc1.42e01e,mp4a.40.2"); it remains the only parameter the helper round-trips, and malformed or injection-shaped values fall through to the strip-all-parameters path.

Non-goals

• No runtime behavior change. No call site is migrated in this PR.
• No broad cross-channel sweep. No outbound MIME normalization is applied anywhere yet.
• No speculative helper options. No expectedPrefix, no isVerifiedMediaSource(media, kind) generalization, no header-level helper.

Follow-up candidates

Adopter PRs (outbound paths and core audio-source classification call sites) will land separately, each small and individually revertable.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related fix(whatsapp): respect audioAsVoice flag in outbound delivery #68744 (split direction for helper surface vs adopter changes)
• This PR fixes a bug or regression

Root Cause (if applicable)

N/A — additive helper surface, no behavior fixed.

• Root cause: N/A
• Missing detection / guardrail: N/A
• Contributing context (if known): N/A

Regression Test Plan (if applicable)

N/A — no regression; helpers have no caller in this PR.

• Coverage level that should have caught this:
  • Unit test (for the helpers themselves)
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/media/mime.test.ts
• Scenario the test should lock in: helper input/output contracts (RFC 2045 token shape, control-character rejection, parameter handling, audio-kind classification trust model)
• Why this is the smallest reliable guardrail: helpers are pure functions with no I/O; unit tests are sufficient and proportionate
• Existing test that already covers this (if any): none — these are new helpers
• If no new test is added, why not: N/A

User-visible / Behavior Changes

None.

Diagram (if applicable)

N/A.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: N/A

No runtime security impact; this PR adds security-relevant helper surface only, and nothing calls it.

Repro + Verification

Environment

• OS: Linux
• Runtime/container: Node 22+, pnpm
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): default

Steps

1. pnpm install
2. pnpm check:changed (covers tsgo:core, tsgo:core:test, oxlint, vitest changed lanes)
3. pnpm test src/media/mime.test.ts
4. pnpm exec oxfmt --check --threads=1 src/media/mime.ts src/media/mime.test.ts

Expected

• pnpm check:changed passes; targeted vitest run reports the new helper assertions pass; oxfmt check is clean.

Actual

• All of the above pass locally.

Evidence

• Failing test/log before + passing after (new tests pass; no prior coverage to fail)
• Real-behavior trace — see ## Real behavior proof section below.
• Screenshot/recording
• Perf numbers (if relevant)

Real behavior proof

Captured 2026-05-17 against branch pr/openclaw-media-helper-bundle head 9fbe30b0a3 (= base fb83e6a03f + new commit 9fbe30b0a3 fix(plugin-sdk): expose isVerifiedAudioSource and sanitizeMediaMime via media-mime subpath).

Behavior or issue addressed: the two new helpers (isVerifiedAudioSource, sanitizeMediaMime) added in src/media/mime.ts are intended for plugin code to consume through the narrow public alias openclaw/plugin-sdk/media-mime (the same alias that already re-exports detectMime, extensionForMime, getFileExtension, mediaKindFromMime, normalizeMimeType). The original commit on this PR only added the helpers to src/media/mime.ts and did not extend the re-export list, so plugin code could not reach them from the public SDK surface — addressing the Codex P2 finding about the missing SDK export.

Real environment tested: Linux x86_64 local dev workspace (Node 22, pnpm 10.33.2) running against this branch's actual source tree. The proof script resolves the import alias openclaw/plugin-sdk/media-mime through the real plugin-sdk path map (the same resolver bundled plugins use at runtime), and the script is run via tsx — no mocks, no test framework, no stubs.

Exact steps or command run after this patch:

1. Add the two helpers (isVerifiedAudioSource, sanitizeMediaMime) to the re-export list in src/plugin-sdk/media-mime.ts.
2. Import them in a standalone script using the public alias openclaw/plugin-sdk/media-mime (scripts/proof-media-helper-narrow-subpath.ts, not committed).
3. Invoke both helpers against well-formed, malformed/unsafe, and trust-model inputs.
4. Probe the resolved module's full export shape to confirm the new exports appear next to the existing ones.

Concrete commands run on the rebased branch:

$ node node_modules/.bin/tsx scripts/proof-media-helper-narrow-subpath.ts
$ CI=true pnpm test src/media/mime.test.ts
$ CI=true pnpm check:changed

Evidence after fix:

Terminal transcript from the standalone SDK-subpath probe (actual production helpers resolved via the real plugin-sdk alias and invoked against fixed inputs, no test framework involved):

=== narrow SDK subpath: openclaw/plugin-sdk/media-mime ===
  typeof isVerifiedAudioSource                                 -> "function"
  typeof sanitizeMediaMime                                     -> "function"

=== sanitizeMediaMime — well-formed inputs (preserveCodecsParam=true) ===
  sanitizeMediaMime("Audio/OGG; codecs=opus", {preserveCodecsParam:true}) -> "audio/ogg; codecs=opus"
  sanitizeMediaMime("video/mp4; codecs=avc1.42e01e,mp4a.40.2", {preserveCodecsParam:true}) -> "video/mp4; codecs=avc1.42e01e,mp4a.40.2"
  sanitizeMediaMime("video/mp4; codecs=\"avc1.42e01e,mp4a.40.2\"", {preserveCodecsParam:true}) -> "video/mp4; codecs=\"avc1.42e01e,mp4a.40.2\""

=== sanitizeMediaMime — default (strip all parameters) ===
  sanitizeMediaMime("application/pdf; charset=utf-8; foo=bar") -> "application/pdf"
  sanitizeMediaMime("application/vnd.x~v1+json")               -> "application/vnd.x~v1+json"

=== sanitizeMediaMime — malformed / unsafe inputs (must return null) ===
  sanitizeMediaMime("image/png\r\nX-Injected: 1")              -> null
  sanitizeMediaMime("image/png\x00evil")                       -> null
  sanitizeMediaMime("not-a-mime")                              -> null
  sanitizeMediaMime(null)                                      -> null
  sanitizeMediaMime(undefined)                                 -> null
  sanitizeMediaMime("")                                        -> null

=== isVerifiedAudioSource — trust model ===
  isVerifiedAudioSource({kind:"audio", contentType:"text/plain"}) -> true
  isVerifiedAudioSource({contentType:"audio/ogg"})  // no kind -> reject -> false
  isVerifiedAudioSource({kind:"image", contentType:"audio/ogg"}) -> false
  isVerifiedAudioSource({kind:"audio"})                        -> true
  isVerifiedAudioSource({})                                    -> false

=== import-shape probe ===
  Object.keys(import * from 'openclaw/plugin-sdk/media-mime')  -> ["detectMime","extensionForMime","getFileExtension","isVerifiedAudioSource","mediaKindFromMime","normalizeMimeType","sanitizeMediaMime"]

Observed result after fix:

• Both helpers resolve from openclaw/plugin-sdk/media-mime (the import-shape probe lists both alongside the previously-exposed detectMime / extensionForMime / getFileExtension / mediaKindFromMime / normalizeMimeType).
• isVerifiedAudioSource honors the documented trust model: {kind:"audio"} → true; raw {contentType:"audio/ogg"} (no kind) → false; mismatched {kind:"image", contentType:"audio/ogg"} → false; {} → false. URL/extension hints cannot promote a payload to "audio".
• sanitizeMediaMime strips control characters (CRLF, NUL, DEL) by returning null, accepts RFC 2045 tokens including vendor types like application/vnd.x~v1+json, normalizes case (Audio/OGG → audio/ogg), strips unrelated parameters by default, and preserves codecs=... (single, comma-separated multi-codec, and matched-quote forms) when preserveCodecsParam:true is passed. Malformed inputs and non-MIME strings return null.

Against the prior commit fb83e6a03f the same import statement would fail with a TS / module-resolution error because the two helpers were absent from the re-export list — the public SDK surface had no path to them.

What was not tested:

• Cross-channel integration with adapters (e.g. WhatsApp, Telegram, Matrix) — this PR is helper-only by design and intentionally has no caller; channel adoption is staged in follow-up PRs (B-4 through B-9 per the PR scope split rule).
• Runtime behavior of the built dist/ artifact — the proof imports from the alias-resolved source. pnpm check:changed ran tsgo-typecheck-all on the changed surface so the public type shape is validated against consumers.
• Live OpenClaw gateway end-to-end consumption — no caller exists yet in this PR; that is the boundary the follow-up adapter PRs will exercise.

Human Verification (required)

• Verified scenarios:
  • isVerifiedAudioSource returns true only for kind === "audio"; explicit negative cases for audio/-prefixed contentType alone, missing kind, and unrelated kinds.
  • sanitizeMediaMime rejects ASCII control characters (\r\n, \n, \t, \x00, \x7f), accepts the RFC 2045 token character set including ~, %, * for valid vendor types, and preserves common single-codec, multi-codec, and quoted codecs=... parameters when preserveCodecsParam: true is passed (e.g. codecs=opus, codecs=mp4a.40.2,opus, codecs="avc1.42e01e,mp4a.40.2"); malformed or injection-shaped values (mismatched quotes, trailing comma, semicolon inside a quoted value) fall through to the strip-all-parameters path.
  • Local pnpm check:changed (core + core test lanes) was run and reported clean.
• Edge cases checked:
  • contentType: "audio/ogg" alone is not enough to be a verified audio source.
  • application/vnd.example~v1+json is not falsely rejected by the MIME validation regex.
  • audio/ogg; charset=utf-8 is normalized to audio/ogg (parameters stripped by default).
• What you did not verify: cross-channel integration (intentionally out of scope; helpers have no caller in this PR).

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes (additive surface only)
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: a future caller adopts the helpers in a way that diverges from the trust model documented here.
  • Mitigation: follow-up adopter PRs must include call-site tests proving the intended trust boundary at the actual call point; reviewers can match adopting code against the helper JSDoc.