feat(devframe): validate remote-assets package name and version

A remote source's `package` and `version` are interpolated into CDN URLs
and the on-disk cache path, so `resolveStaticAssetsSource` now rejects a
value that isn't a valid npm package name / exact semver version (new
`DF0065`) — closing off malformed URLs and cache-path traversal (e.g. a
`..` version segment).

Author: antfubot

docs/errors/DF0065.md

@@ -0,0 +1,45 @@
+---
+outline: deep
+---
+
+# DF0065: Invalid Remote Assets Package Or Version
+
+## Message
+
+> Invalid remote-assets `{field}` "`{value}`".
+
+## Cause
+
+A remote-assets source's `package` and `version` are interpolated into CDN URLs (`https://cdn.jsdelivr.net/npm/<package>@<version>/…`) and into the on-disk cache path (`.remote-assets/<package>@<version>/`). To keep those safe and well-formed, the `package` must be a valid npm package name and the `version` an exact semver version — a value carrying path separators, `@`, whitespace, or traversal segments (`..`) is rejected.
+
+## Example
+
+```ts
+defineDevframe({
+  cli: {
+    distDir: {
+      package: '@devframes/plugin-git-client',
+      version: '../etc', // ✗ not a semver version
+    },
+  },
+})
+```
+
+## Fix
+
+Use a valid npm package name and an exact version:
+
+```ts
+defineDevframe({
+  cli: {
+    distDir: {
+      package: '@devframes/plugin-git-client',
+      version: '1.2.3',
+    },
+  },
+})
+```
+
+## Source
+
+- [`packages/devframe/src/utils/remote-assets.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/remote-assets.ts) — `resolveStaticAssetsSource()` validates a remote source before resolving it.

packages/devframe/src/node/diagnostics.ts

@@ -166,5 +166,10 @@ export const diagnostics = defineDiagnostics({
         `Failed to materialize the remote assets of "${p.package}@${p.version}": ${p.reason}`,
       fix: 'Static builds need every asset file up front. Install the assets package locally, or ensure the provider (and its file-listing API) is reachable during the build.',
     },
+    DF0065: {
+      why: (p: { field: 'package' | 'version', value: string }) =>
+        `Invalid remote-assets ${p.field} "${p.value}".`,
+      fix: 'A remote-assets `package` must be a valid npm package name and `version` an exact semver version (e.g. `1.2.3`) — they are interpolated into CDN URLs and the cache path.',
+    },
   },
 })

packages/devframe/src/utils/remote-assets.test.ts

@@ -208,6 +208,33 @@ describe('resolveStaticAssetsSource (installed package)', () => {
   })
 })
 
+describe('resolveStaticAssetsSource (validation)', () => {
+  it.each([
+    ['UPPERCASE/name', '1.2.3'],
+    ['has spaces', '1.2.3'],
+    ['../escape', '1.2.3'],
+    ['@scope/', '1.2.3'],
+  ])('rejects invalid package %j (DF0065)', (pkg, version) => {
+    expect(() => resolveStaticAssetsSource({ package: pkg, version }, makeTmp())).toThrow(/Invalid remote-assets package/)
+  })
+
+  it.each([
+    ['@scope/ok', '../etc'],
+    ['@scope/ok', 'latest'],
+    ['@scope/ok', '1.2'],
+    ['@scope/ok', '1.2.3/x'],
+  ])('rejects invalid version for %j (DF0065)', (pkg, version) => {
+    expect(() => resolveStaticAssetsSource({ package: pkg, version }, makeTmp())).toThrow(/Invalid remote-assets version/)
+  })
+
+  it('accepts valid scoped names and semver (incl. prerelease/build)', () => {
+    const tmp = makeTmp()
+    for (const version of ['1.2.3', '0.9.0-beta.4', '1.0.0+build.5', '10.20.30-rc.1+meta']) {
+      expect(() => resolveStaticAssetsSource({ package: '@devframes/plugin-git-client', version, fetch: async () => new Response(null) }, tmp)).not.toThrow()
+    }
+  })
+})
+
 describe('serveStaticHandler with a remote store', () => {
   async function serve(store: RemoteAssetsStore): Promise<{ url: string, close: () => Promise<void> }> {
     const app = new H3()

packages/devframe/src/utils/remote-assets.ts

@@ -304,6 +304,24 @@ function errText(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+// npm package name rules (github.com/npm/validate-npm-package-name), and an
+// exact semver version — both interpolated into CDN URLs and the cache path,
+// so they must not carry separators, `@`, or traversal segments.
+const PACKAGE_NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/
+const VERSION_RE = /^\d+\.\d+\.\d+(?:-[a-z0-9-]+(?:\.[a-z0-9-]+)*)?(?:\+[a-z0-9-]+(?:\.[a-z0-9-]+)*)?$/i
+
+/** Reject a {@link RemoteAssets} with an unsafe package name or version (`DF0065`). */
+function assertValidRemoteAssets(assets: RemoteAssets): void {
+  if (assets.package.length > 214 || !PACKAGE_NAME_RE.test(assets.package))
+    throw diagnostics.DF0065({ field: 'package', value: assets.package })
+  if (!VERSION_RE.test(assets.version))
+    throw diagnostics.DF0065({ field: 'version', value: assets.version })
+}
+
 // ---------------------------------------------------------------------------
 // Source resolution
 // ---------------------------------------------------------------------------
@@ -314,13 +332,17 @@ function errText(error: unknown): string {
  * locally installed copy of its package when present) or a caching
  * {@link RemoteAssetsStore} back-proxy. Remote caches live under
  * `<projectStorageDir>/.remote-assets/<package>@<version>/`.
+ *
+ * A remote source's `package`/`version` are validated first (`DF0065`) — both
+ * are interpolated into CDN URLs and the cache path.
  */
 export function resolveStaticAssetsSource(
   source: StaticAssetsSource,
   projectStorageDir: string,
 ): string | RemoteAssetsStore {
   if (typeof source === 'string')
     return source
+  assertValidRemoteAssets(source)
   return resolveInstalled(source)
     ?? createStore(source, join(projectStorageDir, '.remote-assets', `${source.package.replace(/\//g, '+')}@${source.version}`))
 }

tests/__snapshots__/tsnapi/devframe/internal.snapshot.d.ts

@@ -298,6 +298,13 @@ export declare const diagnostics: import("nostics").Diagnostics<{
     }) => string;
     readonly fix: "Static builds need every asset file up front. Install the assets package locally, or ensure the provider (and its file-listing API) is reachable during the build.";
   };
+  readonly DF0065: {
+    readonly why: (p: {
+      field: "package" | "version";
+      value: string;
+    }) => string;
+    readonly fix: "A remote-assets `package` must be a valid npm package name and `version` an exact semver version (e.g. `1.2.3`) — they are interpolated into CDN URLs and the cache path.";
+  };
 }, readonly [typeof devframeReporter]>;
 // #endregion