116 lines
4.3 KiB
Markdown
116 lines
4.3 KiB
Markdown
# Toolbox Portal requirements
|
|
|
|
av-tools is built and packaged independently. Toolbox Portal consumes the
|
|
exact ZIP and SHA-256 from a reviewed release lock; it must never import the
|
|
app source into its React build.
|
|
|
|
## Required serving behavior
|
|
|
|
All app, wrapper, core, WASM and worker responses are same-origin and served
|
|
over HTTPS (or trusted localhost). Apply:
|
|
|
|
```text
|
|
Cross-Origin-Opener-Policy: same-origin
|
|
Cross-Origin-Embedder-Policy: require-corp
|
|
Cross-Origin-Resource-Policy: same-origin
|
|
X-Content-Type-Options: nosniff
|
|
```
|
|
|
|
Serve `.wasm` as `application/wasm`, JavaScript modules as a JavaScript MIME
|
|
type and JSON as `application/json`. Test real responses under
|
|
`/apps/av/vendor/ffmpeg/0.12.10/...`; a file-extension allowlist alone does not
|
|
prove the MIME type.
|
|
|
|
Suggested CSP:
|
|
|
|
```text
|
|
default-src 'self';
|
|
script-src 'self' 'wasm-unsafe-eval';
|
|
worker-src 'self' blob:;
|
|
connect-src 'self';
|
|
img-src 'self' blob: data:;
|
|
media-src 'self' blob:;
|
|
font-src 'self';
|
|
style-src 'self';
|
|
object-src 'none';
|
|
frame-src 'none';
|
|
frame-ancestors 'none';
|
|
base-uri 'none';
|
|
form-action 'none';
|
|
```
|
|
|
|
`'wasm-unsafe-eval'` is the narrow WebAssembly permission; broad
|
|
`'unsafe-eval'` is unnecessary. `worker-src blob:` covers the wrapper-created
|
|
worker path. `media-src blob:` permits local source/result previews.
|
|
|
|
## Immutable reference and active-worktree state
|
|
|
|
Portal revision `bda9da044d61c109afd9969d357cc27f76648938` already sends COOP
|
|
`same-origin`, COEP `require-corp`, CORP `same-origin`, `script-src 'self'
|
|
'wasm-unsafe-eval'`, and `worker-src 'self' blob:`. Its packaged nginx CSP does
|
|
**not** declare `media-src`; `default-src 'self'` therefore blocks local
|
|
`blob:` audio/video URLs. The expected browser diagnostic is equivalent to:
|
|
|
|
```text
|
|
Refused to load media from 'blob:…' because it violates
|
|
"default-src 'self'".
|
|
```
|
|
|
|
Smallest required Portal change: append exactly
|
|
`media-src 'self' blob:;` to that CSP. This permits only same-origin and
|
|
in-memory Blob media; it does not permit remote media hosts, inline script or
|
|
eval. If the Portal is not changed, conversion/download can remain available
|
|
but Blob source/result preview must show a clear disabled reason.
|
|
|
|
As inspected on 2026-07-24, the active
|
|
`/mnt/DATA/git/toolbox-portal/deploy/nginx.conf` contains that exact directive
|
|
as a local worktree patch. The worktree still resolves to the immutable
|
|
revision above, so the patch is useful for local deployment testing but is not
|
|
a committed Portal revision and must not be cited as published release
|
|
evidence. The clean-reference assembly smoke therefore continues to require
|
|
`--allow-known-header-gap` until a reviewed Portal commit contains the fix.
|
|
|
|
The nginx profile includes `.wasm` in its static allowlist/gzip types but
|
|
relies on the base image `mime.types`. Verify `Content-Type:
|
|
application/wasm` against the pinned image; add an explicit mapping if the
|
|
response differs.
|
|
|
|
## Caching
|
|
|
|
The immutable Portal reference's cache map makes Vite content-hashed assets
|
|
immutable but leaves versioned FFmpeg cores at `no-cache`. Correctness is
|
|
unaffected.
|
|
For performance, the exact directory
|
|
`apps/av/vendor/ffmpeg/0.12.10/{st,mt}/` may receive:
|
|
|
|
```text
|
|
Cache-Control: public, max-age=31536000, immutable
|
|
```
|
|
|
|
Only do this while a version path is immutable and verified against
|
|
`version.json`. Keep `index.html`, manifest/catalog/release JSON and legal
|
|
notices revalidated.
|
|
|
|
## Nested path and context
|
|
|
|
The artifact uses `base: './'`, `entry: './'`, a relative icon, a relative
|
|
manifest URL and relative core URLs. Portal may therefore target `av`, yielding
|
|
`apps/av/`. Do not rewrite files to root-absolute `/assets` or `/vendor`.
|
|
Use top-level navigation; embedding is unsupported.
|
|
|
|
The app remains usable without valid Toolbox context. It validates context
|
|
version/origin and falls back to standalone shell behavior without moving or
|
|
duplicating suite controls.
|
|
|
|
## Fallback contract
|
|
|
|
MT requires all isolation headers plus secure context and
|
|
`SharedArrayBuffer`. When any prerequisite or MT load fails, the app terminates
|
|
that instance and loads ST. The manifest intentionally declares
|
|
`crossOriginIsolated: false` because isolation is not an unconditional
|
|
requirement; it declares workers, secure context, IndexedDB and top-level
|
|
context.
|
|
|
|
See `scripts/portal-assembly-smoke.mjs` and `docs/RELEASE.md` for the temporary,
|
|
non-mutating assembly procedure.
|