Move CoR artifact security guidance into its own docs (#1875)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MicroFish91

.github/instructions/copilot-on-rails-artifact-security.instructions.md

@@ -0,0 +1,27 @@
+---
+description: 'Securely parse and render untrusted Copilot on Rails workspace artifacts.'
+applyTo: "src/webviews/copilotOnRails/**, src/commands/copilotOnRails/**, src/chat/tools/copilotOnRails/**, src/utils/copilotOnRails/**, src/tree/project/**, resources/agents/**, test/copilotOnRails/**"
+---
+
+# Secure Copilot on Rails artifact handling
+
+Treat `.azure/*`, `.azure/.preview-temp/*`, `.copilot-azure/sessions/*`, and `package.json` files inside
+the Copilot on Rails user's project workspace as untrusted and potentially incomplete. Agents, users, and
+other workspace tools can edit them, and readers can observe a partial write.
+
+When code reads or renders these artifacts:
+
+- Use one-argument `JSON.parse(text)`, assign the result to `unknown`, and narrow the root and every consumed
+  field with runtime checks.
+- Preserve valid fields and array entries in an incomplete artifact. Do not coerce unsupported values into
+  strings.
+- Validate artifact-supplied path parts before joining paths. Validate URLs, commands, process arguments,
+  file operations, HTML, and SVG for their specific destination.
+- Render agent-written Markdown as parsed React nodes rather than with `dangerouslySetInnerHTML`. Explicitly
+  allowlist link protocols and supported HTML tags. Configure Mermaid with `securityLevel: "strict"` before
+  rendering.
+- Add targeted tests for malformed roots, wrong field types, partial objects, traversal strings, unsafe
+  links or tags, and other invalid inputs that reach the changed destination.
+
+Follow the full [Copilot on Rails artifact security contract](../../docs/copilot-create-project-security.md).
+Update that document when the trust boundary or required handling changes.

.github/instructions/copilot-on-rails-docs.instructions.md

@@ -27,10 +27,10 @@ Update the matching section of `docs/copilot-create-project.md` when you:
 | Change what diagnostics capture, or the Report Issue / Inspect Diagnostics behavior | Support & triage runbook, including the "What the diagnostics contain (privacy)" section |
 | Change the launch / resume / empty-folder / autopilot flow | Launching, Resuming a session, and Autopilot mode |
 
-**Security rule:** when CoR code starts reading a new agent or workspace artifact, consumes a new field,
-constructs a path, command, or URL from artifact data, or renders artifact text as HTML or SVG, follow and
-update [Safe parsing and rendering](../../docs/copilot-create-project.md#safe-parsing-and-rendering). Also
-update **Files & state** when the artifact inventory changes.
+**Security documentation:** when the artifact trust boundary or required handling changes, update
+[Copilot on Rails artifact security](../../docs/copilot-create-project-security.md). Also update
+**Files & state** when the artifact inventory changes. Secure implementation requirements live in the
+separate Copilot on Rails artifact security instruction.
 
 ## New or changed UI — flag screenshots to re-capture
 

docs/copilot-create-project-security.md

@@ -0,0 +1,75 @@
+# Copilot on Rails artifact security
+
+This document is the security contract for contributors and reviewers working on code that reads or renders
+Copilot on Rails artifacts. See [Files & state](copilot-create-project.md#files--state) for the artifact
+inventory.
+
+## Trust boundary
+
+**SDL requirement.** Treat `.azure/*`, `.azure/.preview-temp/*`,
+`.copilot-azure/sessions/*`, and `package.json` files inside the Copilot on Rails user's project workspace
+as untrusted input. Agents may write these files, and users and other workspace tools can edit them. A
+reader can also observe a partial write. Validate data before it influences a path, URL, command, process,
+file operation, HTML node, or SVG node.
+
+**Design assumptions.** Artifacts belong to the current workspace and may be incomplete while an agent is
+working. Readers may preserve fields that are already valid, but they must not infer that the rest of the
+document is trustworthy.
+
+**Residual risk.** Runtime shape checks do not make a string safe for every later use. Validate again for the
+specific sink. A future deserializer, renderer, or URL handler can introduce a new execution path even when
+the current JSON parsing step is data-only.
+
+## JSON parsing and partial artifacts
+
+Safe deserialization and safe downstream use are separate checks.
+
+Use plain, one-argument `JSON.parse(text)`. This operation is data-only. JSON content cannot supply or invoke
+a reviver; application code would have to pass the optional second argument. Do not add a reviver without a
+separate security review.
+
+Assign the parse result to `unknown`. Narrow the root and every consumed field with runtime checks before use.
+A TypeScript cast only changes the compiler's view and does not validate runtime data.
+
+Malformed JSON follows the caller's existing error or retry path. For valid JSON with an incomplete object,
+preserve valid fields and ignore or default invalid fields according to the artifact contract. Filtering an
+invalid array entry must not discard its valid siblings. Never silently coerce an object to a string, which
+can turn unsupported input into text such as `[object Object]`.
+
+## Paths and package metadata
+
+Validate every artifact-supplied path part before passing it to `Uri.joinPath`, `path.join`, or another file
+API. Preview page slugs use kebab case and must match `[a-z0-9]+(?:-[a-z0-9]+)*`. A value such as
+`../outside` must fail validation before the code constructs `<slug>.html`; joining first would let the
+artifact escape the preview directory.
+
+When reading a `package.json` from the user's project workspace, require an object root. Require
+`dependencies`, `devDependencies`, and `scripts` to be object records when present. Preserve entries whose
+values are strings and drop entries with other value types. When key presence changes behavior, use an
+own-property check such as `Object.hasOwn(record, key)` rather than reading through the prototype chain.
+
+## Markdown, HTML, and SVG
+
+Prefer a small parsed node model and React nodes for agent-written Markdown. Do not use
+`dangerouslySetInnerHTML` for plan text. Explicitly allowlist link protocols before creating anchors. The
+local debug plan currently allows `http`, `https`, and `mailto`. Restore only the HTML tags required by the
+plan contract, currently attribute-free `<details>`, `<summary>`, and `<br>` tags. Leave unknown or
+attribute-bearing HTML as text.
+
+Mermaid output is still generated SVG inserted into the document. Initialize Mermaid with
+`securityLevel: "strict"` before rendering and keep that setting in place before inserting its SVG.
+
+## Audit checklist
+
+1. Find every JSON parse, file read, and deserializer used by the changed flow.
+2. Confirm each `JSON.parse` call has one argument and no reviver. Review deserializer dependencies for code
+   execution or unsafe object construction.
+3. Parse into `unknown`, validate the root, and narrow every consumed field at runtime.
+4. Check malformed JSON follows the existing error or retry path. Check incomplete objects preserve valid
+   fields without coercing invalid values.
+5. Trace artifact values into path construction, shell or process calls, file operations, and URLs. Apply
+   sink-specific validation and confinement.
+6. Trace artifact text into HTML and SVG sinks. Prefer React nodes, allowlist protocols and tags, and keep
+   Mermaid in strict security mode.
+7. Add targeted tests for malformed roots, wrong field types, partial objects, traversal strings, unsafe
+   links or tags, and other inputs that reach the changed sink.

docs/copilot-create-project.md

@@ -34,7 +34,6 @@ the work as it happens.
   - [The agents](#the-agents)
   - [The MCP tools](#the-mcp-tools)
   - [Files & state](#files--state)
-  - [Safe parsing and rendering](#safe-parsing-and-rendering)
 - [Part 5 — Support & triage runbook](#part-5--support--triage-runbook)
   - [Report an issue](#report-an-issue)
   - [Inspect diagnostics](#inspect-diagnostics)
@@ -495,79 +494,6 @@ app (`az containerapp exec`, `az webapp ssh`), then a one‑shot job in the same
 firewall rule is a last resort, and it is never widened beyond a single address — see
 [`cor-references/migration-access.md`](../resources/agents/azure-deploy/cor-references/migration-access.md).
 
-## Safe parsing and rendering
-
-This section is the security contract for code that reads or renders the artifacts above.
-
-### Trust boundary
-
-**SDL requirement.** Treat `.azure/*`, `.azure/.preview-temp/*`,
-`.copilot-azure/sessions/*`, and workspace `package.json` files as untrusted input. Agents may write these
-files, and users and other workspace tools can edit them. A reader can also observe a partial write. Validate
-data before it influences a path, URL, command, process, file operation, HTML node, or SVG node.
-
-**Design assumptions.** Artifacts belong to the current workspace and may be incomplete while an agent is
-working. Readers may preserve fields that are already valid, but they must not infer that the rest of the
-document is trustworthy.
-
-**Residual risk.** Runtime shape checks do not make a string safe for every later use. Validate again for the
-specific sink. A future deserializer, renderer, or URL handler can introduce a new execution path even when
-the current JSON parsing step is data-only.
-
-### JSON parsing and partial artifacts
-
-Safe deserialization and safe downstream use are separate checks.
-
-Use plain, one-argument `JSON.parse(text)`. This operation is data-only. JSON content cannot supply or invoke
-a reviver; application code would have to pass the optional second argument. Do not add a reviver without a
-separate security review.
-
-Assign the parse result to `unknown`. Narrow the root and every consumed field with runtime checks before use.
-A TypeScript cast only changes the compiler's view and does not validate runtime data.
-
-Malformed JSON follows the caller's existing error or retry path. For valid JSON with an incomplete object,
-preserve valid fields and ignore or default invalid fields according to the artifact contract. Filtering an
-invalid array entry must not discard its valid siblings. Never silently coerce an object to a string, which
-can turn unsupported input into text such as `[object Object]`.
-
-### Paths and package metadata
-
-Validate every artifact-supplied path part before passing it to `Uri.joinPath`, `path.join`, or another file
-API. Preview page slugs use kebab case and must match `[a-z0-9]+(?:-[a-z0-9]+)*`. A value such as
-`../outside` must fail validation before the code constructs `<slug>.html`; joining first would let the
-artifact escape the preview directory.
-
-When reading a workspace `package.json`, require an object root. Require `dependencies`, `devDependencies`,
-and `scripts` to be object records when present. Preserve entries whose values are strings and drop entries
-with other value types. When key presence changes behavior, use an own-property check such as
-`Object.hasOwn(record, key)` rather than reading through the prototype chain.
-
-### Markdown, HTML, and SVG
-
-Prefer a small parsed node model and React nodes for agent-written Markdown. Do not use
-`dangerouslySetInnerHTML` for plan text. Allowlist link protocols before creating anchors. The local debug
-plan currently allows `http`, `https`, and `mailto`. Restore only the tags required by the plan contract,
-currently attribute-free `<details>`, `<summary>`, and `<br>` tags. Leave unknown or attribute-bearing HTML
-as text.
-
-Mermaid output is still generated SVG inserted into the document. Initialize Mermaid with
-`securityLevel: "strict"` before rendering and keep that setting in place before inserting its SVG.
-
-### Audit Checklist
-
-1. Find every JSON parse, file read, and deserializer used by the changed flow.
-2. Confirm each `JSON.parse` call has one argument and no reviver. Review deserializer dependencies for code
-   execution or unsafe object construction.
-3. Parse into `unknown`, validate the root, and narrow every consumed field at runtime.
-4. Check malformed JSON follows the existing error or retry path. Check incomplete objects preserve valid
-   fields without coercing invalid values.
-5. Trace artifact values into path construction, shell or process calls, file operations, and URLs. Apply
-   sink-specific validation and confinement.
-6. Trace artifact text into HTML and SVG sinks. Prefer React nodes, allowlist protocols and tags, and keep
-   Mermaid in strict security mode.
-7. Add targeted tests for malformed roots, wrong field types, partial objects, traversal strings, unsafe
-   links or tags, and other inputs that reach the changed sink.
-
 ---
 
 # Part 5 — Support & triage runbook