@W-21182296 fix: make webapplication.json optional by lesya7 · Pull Request #1688 · forcedotcom/source-deploy-retrieve

lesya7 · 2026-02-19T23:41:59Z

This PR makes webapplication.json optional for WebApplication bundles and adds client-side validation with path security checks when the file is present.
What changed:
Previously, deploying a WebApplication without a webapplication.json descriptor would fail. Now it's treated as file-based routing and succeeds — only the -meta.xml is required.
When webapplication.json is present, it's validated before deploy: we check for valid JSON, enforce the allowed schema (apiVersion, outputDir, routing, headers), verify types and enum values, and confirm that referenced files (outputDir, fallback, rewrite targets) actually exist in the bundle. Fallback and rewrite file-existence checks run even when outputDir is not set, resolving paths relative to the bundle root. Error messages include the specific problem, the received value, and a suggested fix.
Path values in the descriptor go through security validation matching the server-side WebApplicationFileProcessor.java. A containsPathTraversal() check rejects .. segments, absolute paths, null bytes, control characters, glob wildcards, backslashes, and percent-encoding. A secondary resolved-path check (assertNoTraversal) acts as defense in depth, ensuring no path escapes its parent directory after resolution. An outputDir that resolves to the bundle root itself (e.g. . or ./) is also rejected. Config paths must use forward slashes — they're bundle-relative and URL-style, matching the server's pure-string validation logic. The descriptor is capped at 100 KB, matching the server-side limit.
During retrieve, validation is skipped since the org already validated the metadata server-side. This also fixes a crash where ZipTreeContainer.readFileSync (not implemented) would throw during retrieve.
The filePathGenerator was updated to only return the meta XML for WebApplication — since the descriptor is optional, it shouldn't be listed as a guaranteed file path.

@W-21182296@ or @W-12345678@

bpbuch · 2026-02-23T23:38:11Z

src/resolve/adapters/webApplicationsSourceAdapter.ts

+    ]);
+  }
+
+  let config: unknown;


We should create named types for the config.

+1. If you use named types, then you can do typeguard assertions.

bpbuch · 2026-02-23T23:41:41Z

src/resolve/adapters/webApplicationsSourceAdapter.ts

+
+  // Report all unknown properties at once so the developer can fix them in a single pass.
+  const disallowed = keys.filter((k) => !ALLOWED_TOP_LEVEL.has(k));
+  if (disallowed.length > 0) {


Local dev will have some properties in the config that are not included in this validation. I don't think we need to prevent deployment due to unused properties being set.

if the property isn't allowed, we should throw an error because the deploy would fail server-side anyway. We don't check for unused props here.

bpbuch · 2026-02-23T23:44:45Z

src/resolve/adapters/webApplicationsSourceAdapter.ts

+    }
+
+    const hasFileUnder = (dirPath: SourcePath, depth = 0): boolean => {
+      if (depth > MAX_RECURSION_DEPTH) return false;


Suggested change

if (depth > MAX_RECURSION_DEPTH) return false;

if (depth >= MAX_RECURSION_DEPTH) return false;

bpbuch · 2026-02-23T23:48:09Z

src/resolve/adapters/webApplicationsSourceAdapter.ts

+          const raw = this.tree.readFileSync(descriptorPath);
+          validateWebApplicationJson(raw, descriptorPath, contentPath, this.tree);
+        } catch (e) {
+          if (e instanceof Error && e.message === 'Method not implemented') {


I'm not sure that I understand this error condition. If validation throws Method not implemented, the config is considered valid? Is this correct?

During retrieve, the tree is a zip. Zip trees don't support readFileSync, so it throws. We catch that and skip validation — the config in the org was already validated server-side when it was deployed.

- Make webapplication.json optional (file-based routing when absent) - Skip client-side validation during retrieve (ZipTreeContainer) - Add containsPathTraversal() rejecting .., absolute paths, null bytes, control chars, glob wildcards, backslashes, and percent-encoding - Add assertNoTraversal() resolved-path check as defense in depth - Add 100 KB size limit matching server-side WebApplicationFileProcessor - Validate fallback/rewrite file existence with and without outputDir - Reject outputDir that resolves to the bundle root (. or ./) - Config paths must use forward slashes (URL-style, portable) Co-authored-by: Cursor <cursoragent@cursor.com>

trimPathToContent splits by path.sep, so zip-style forward-slash paths break on Windows. Use path.join to produce native separators. Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

jfeingold35 · 2026-02-26T14:48:01Z

src/resolve/adapters/webApplicationsSourceAdapter.ts

+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';


Nitpick: I dislike single-line if statements. Can you change these to use braces?

jfeingold35 · 2026-02-26T14:49:36Z

src/resolve/adapters/webApplicationsSourceAdapter.ts

+function configError(message: string, actions?: string[]): SfError {
+  return new SfError(message, 'InvalidWebApplicationConfigError', actions);
+}
+
+function fileError(message: string, actions?: string[]): SfError {
+  return new SfError(message, 'ExpectedSourceFilesError', actions);
+}


Nitpick: Could these methods be called createXError instead of xError, so that it's immediately clear in their invocations that they're functions and not classes?

jfeingold35 · 2026-02-26T14:50:45Z

src/resolve/adapters/webApplicationsSourceAdapter.ts

+  if (DOT_DOT_SEGMENT.test(value)) return 'path traversal (..)';
+  if (value === '..') return 'path traversal (..)';
+  if (value.startsWith('/') || value.startsWith('\\')) return 'absolute path';
+  if (value.includes('\0')) return 'null byte';
+  for (let i = 0; i < value.length; i++) {
+    if (value.charCodeAt(i) < 0x20) return 'control character';
+  }
+  if (value.includes('*') || value.includes('?')) return 'glob wildcard';
+  if (value.includes('\\')) return 'backslash (use forward slashes)';
+  if (value.includes('%')) return 'percent-encoding';


Nitpick: Single-line if statements.

jfeingold35 · 2026-02-26T14:51:30Z

src/resolve/adapters/webApplicationsSourceAdapter.ts

+      `webapplication.json '${configKey}' value "${value}" contains ${reason}. Config paths must use forward slashes.`,
+      [`Fix "${value}": use relative paths with forward slashes only, no special characters.`]


You should put these strings in the messages.md file instead of defining them here. Same goes for other user-facing text.

jfeingold35 · 2026-02-26T14:53:43Z

src/resolve/adapters/webApplicationsSourceAdapter.ts

+    ]);
+  }
+
+  let config: unknown;


+1. If you use named types, then you can do typeguard assertions.

jfeingold35 · 2026-02-26T14:54:43Z

src/resolve/adapters/webApplicationsSourceAdapter.ts

+  descriptorPath: string,
+  contentPath: SourcePath,
+  tree: TreeContainer
+): void {


Is it possible for this method to be split into smaller sub-methods? It's just a little bulky as-is. Additionally, does it maybe make sense for this code to be moved into a new file altogether?

lesya7 force-pushed the make-webapplication-optional branch 6 times, most recently from cb14d90 to c7d2de7 Compare February 20, 2026 02:56

lesya7 requested review from bpbuch and iowillhoit February 20, 2026 04:06

bpbuch reviewed Feb 23, 2026

View reviewed changes

lesya7 and others added 2 commits February 24, 2026 12:38

fix: use path.join for cross-platform NUT test compatibility

384ca1b

trimPathToContent splits by path.sep, so zip-style forward-slash paths break on Windows. Use path.join to produce native separators. Co-authored-by: Cursor <cursoragent@cursor.com>

lesya7 force-pushed the make-webapplication-optional branch from bd9ef6b to 384ca1b Compare February 24, 2026 20:38

chore: retrigger CI

1999c74

Co-authored-by: Cursor <cursoragent@cursor.com>

bpbuch approved these changes Feb 26, 2026

View reviewed changes

jfeingold35 requested changes Feb 26, 2026

View reviewed changes

feat: addressing feedback

b5eda18

lesya7 requested a review from a team as a code owner February 26, 2026 19:56

jfeingold35 approved these changes Feb 26, 2026

View reviewed changes

	if (depth > MAX_RECURSION_DEPTH) return false;
	if (depth >= MAX_RECURSION_DEPTH) return false;

		if (value === null) return 'null';
		if (Array.isArray(value)) return 'array';

		`webapplication.json '${configKey}' value "${value}" contains ${reason}. Config paths must use forward slashes.`,
		[`Fix "${value}": use relative paths with forward slashes only, no special characters.`]

Conversation

lesya7 commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

lesya7 commented Feb 19, 2026 •

edited

Loading