Add content-hash plugin asset URL segments #226

New issue

Closed

opened 2026-06-02 13:31:26 +00:00 by steve · 0 comments

steve commented

2026-06-02 13:31:26 +00:00

Owner

Problem

The original dual ESM/CJS loader plan and the current plugin runtime spec require
renderer ESM asset URLs to include both the installed plugin version and a
verified content hash. The implemented asset URL helpers currently encode only
the vault id, plugin id, version, and asset path, so browser/Electron asset URLs
do not provide the hash-based cache-busting and integrity signal described by
the milestone.

Goal

Make plugin asset URL generation and resolution comply with the planned
/<version-or-content-hash>/... behavior and the current runtime spec's
version-plus-hash URL contract.

Scope

Add a stable content-hash segment to web and Electron plugin asset URLs for
renderer ESM chunks and related plugin assets.
Decide whether the hash should be the verified plugin file hash, a generated
bundle asset hash, or another manifest-backed hash, then document that exact
source of truth.
Update URL parsing and validation so stale or mismatched hash segments do not
silently serve the wrong asset.
Update tests and spec text to match the implemented URL shape.

Non-goals

Reworking plugin package installation or release signing beyond the hash data
needed for asset URL validation.
Changing public plugin ids, installed plugin versions, or import-map host
module semantics.

Acceptance Criteria

Web URLs include a content-hash segment in addition to plugin id, version, and
path, and the API asset server validates that segment before serving content.
Electron lapis-plugin:// URLs include the same cache-busting/integrity
segment and reject malformed, missing, or mismatched hashes consistently with
the web asset server.
First-party plugin ESM import maps and generated runtime URLs continue to load
successfully in browser and desktop contexts.
Unit tests cover successful URL generation/resolution and at least one
mismatched-hash rejection path for web and Electron URL helpers.
The plugin runtime spec no longer overstates or understates the implemented
URL contract.

Implementation Notes

Audit packages/api/src/lib/plugin-asset-server.ts,
packages/web/src/plugin-asset-server.ts, and any desktop protocol adapter
before choosing the hash source.
Current focused tests that should be extended include
packages/api/src/lib/__tests__/plugin-asset-server.test.ts and
packages/web/src/plugin-asset-server.test.ts.
Keep URL encoding behavior stable for vault ids, plugin ids, versions, hashes,
and asset paths.

Suggested Files or Specs To Inspect

spec/src/30-cross-package-contracts/plugin-runtime.md
packages/api/src/lib/plugin-asset-server.ts
packages/web/src/plugin-asset-server.ts
packages/api/src/lib/__tests__/plugin-asset-server.test.ts
packages/web/src/plugin-asset-server.test.ts
Desktop Electron plugin asset protocol or URL registration code, if separate
from the API helper

Validation Commands

pnpm --filter @lapis-notes/api exec vitest run src/lib/__tests__/plugin-asset-server.test.ts
pnpm --filter @lapis-notes/web exec vitest run src/plugin-asset-server.test.ts
pnpm --filter @lapis-notes/api check:all
pnpm --filter @lapis-notes/web check:all
make spec-lint
mdbook build spec

Follow-up to #217 — [loader] Add Web/PWA plugin asset server

Follow-up Tasks

Implementation Summary

Added content-hash segments to web and Electron plugin asset URLs, validated URL hashes against installed asset metadata before serving, updated host integrations, tests, and specs.

## Problem The original dual ESM/CJS loader plan and the current plugin runtime spec require renderer ESM asset URLs to include both the installed plugin version and a verified content hash. The implemented asset URL helpers currently encode only the vault id, plugin id, version, and asset path, so browser/Electron asset URLs do not provide the hash-based cache-busting and integrity signal described by the milestone. ## Goal Make plugin asset URL generation and resolution comply with the planned `/<version-or-content-hash>/...` behavior and the current runtime spec's version-plus-hash URL contract. ## Scope - Add a stable content-hash segment to web and Electron plugin asset URLs for renderer ESM chunks and related plugin assets. - Decide whether the hash should be the verified plugin file hash, a generated bundle asset hash, or another manifest-backed hash, then document that exact source of truth. - Update URL parsing and validation so stale or mismatched hash segments do not silently serve the wrong asset. - Update tests and spec text to match the implemented URL shape. ## Non-goals - Reworking plugin package installation or release signing beyond the hash data needed for asset URL validation. - Changing public plugin ids, installed plugin versions, or import-map host module semantics. ## Acceptance Criteria - Web URLs include a content-hash segment in addition to plugin id, version, and path, and the API asset server validates that segment before serving content. - Electron `lapis-plugin://` URLs include the same cache-busting/integrity segment and reject malformed, missing, or mismatched hashes consistently with the web asset server. - First-party plugin ESM import maps and generated runtime URLs continue to load successfully in browser and desktop contexts. - Unit tests cover successful URL generation/resolution and at least one mismatched-hash rejection path for web and Electron URL helpers. - The plugin runtime spec no longer overstates or understates the implemented URL contract. ## Implementation Notes - Audit `packages/api/src/lib/plugin-asset-server.ts`, `packages/web/src/plugin-asset-server.ts`, and any desktop protocol adapter before choosing the hash source. - Current focused tests that should be extended include `packages/api/src/lib/__tests__/plugin-asset-server.test.ts` and `packages/web/src/plugin-asset-server.test.ts`. - Keep URL encoding behavior stable for vault ids, plugin ids, versions, hashes, and asset paths. ## Suggested Files or Specs To Inspect - `spec/src/30-cross-package-contracts/plugin-runtime.md` - `packages/api/src/lib/plugin-asset-server.ts` - `packages/web/src/plugin-asset-server.ts` - `packages/api/src/lib/__tests__/plugin-asset-server.test.ts` - `packages/web/src/plugin-asset-server.test.ts` - Desktop Electron plugin asset protocol or URL registration code, if separate from the API helper ## Validation Commands - `pnpm --filter @lapis-notes/api exec vitest run src/lib/__tests__/plugin-asset-server.test.ts` - `pnpm --filter @lapis-notes/web exec vitest run src/plugin-asset-server.test.ts` - `pnpm --filter @lapis-notes/api check:all` - `pnpm --filter @lapis-notes/web check:all` - `make spec-lint` - `mdbook build spec` ## Related Issues - Follow-up to #217 — [[loader] Add Web/PWA plugin asset server](../closed/217-loader-add-web-pwa-plugin-asset-server.md) ## Follow-up Tasks ## Implementation Summary Added content-hash segments to web and Electron plugin asset URLs, validated URL hashes against installed asset metadata before serving, updated host integrations, tests, and specs.

steve added this to the Dual ESM/CJS plugin loader milestone

2026-06-02 13:31:26 +00:00

steve

2026-06-02 13:31:26 +00:00