feat(cas): add helper method for authenticated citation sources

[scottcmg]

Details

Customers have reported issues with the generated PDF citations that are returned as part of the conversational agent response where clicking the inline citation or the source in the source list returns a 401 in a new tab. This is because these citations require an authorized fetch from ECS to display.

This PR is to add a helper method that customers can use to add support for these citation links so they do not have to be responsible for independently determining the wiring needed for support. It adds some security hardening against (1) inline HTML execution and (2) hijacked download requests sending user credentials to a non-UiPath-origin source.

[claude]

Review findings

New inline comments posted this run:

1. Telemetry key casing (conversational-agent.ts line 171) — key uses camelCase 'downloadCitationSource' while existing keys use PascalCase (GetAll, GetById). Should be 'ConversationalAgent.DownloadCitationSource'.

2. Security: origin guard fails open when baseUrl is absent (conversational-agent.ts line 191) — the guard is silently skipped when baseUrl is not configured, so the bearer token would be sent to any absolute URL. Suggest changing to fail closed.

3. any type in test factory (conversational-agent.test.ts line 364) — violates the no-any convention; should be Partial.

4. Missing test branches (conversational-agent.test.ts after line 438) — no tests for (a) fetch() throwing a network error and (b) a malformed downloadUrl failing new URL() parsing.

5. Missing integration test and oauth-scopes.md entry (conversational-agent.ts line 172) — post-implementation checklist: integration test in tests/integration/shared/agents/ and a scope row for downloadCitationSource() in docs/oauth-scopes.md.

[scottcmg]

Pushed fixes for the review 👇

• Telemetry key → DownloadCitationSource (PascalCase)
• Origin check now fails closed (!base || ...)
• Test param typed Partial<CitationSourceMedia> (no more any)
• Added network-failure + malformed-URL branch tests (fwiw 'not a url :://' actually resolves against the base, so used 'https://[')
• oauth-scopes: checked the ECS ReferenceController — it's just ORG_MEMBER_OR_S2S, no specific scope, so the entry says "none (authenticated org-member token)"

Skipped the integration test for now — conv-agent has no integration suite at all yet, so a one-off here felt out of place. Can do it as a separate pass if we want to stand that up.

[claude]

The test file path does not mirror the src/ structure. Per the architecture docs: "tests/unit/ mirrors src/ structure".

• Source: src/services/conversational-agent/helpers/citation.ts
• Expected test path: tests/unit/services/conversational-agent/helpers/citation.test.ts
• Actual path: tests/unit/helpers/conversational-agent/citation.test.ts

The file should be moved to match the source tree.

[claude]

Review findings

New inline comments posted this run:

1. {@link} in @param description (models.ts:158) — ({@link CitationSourceMedia}) inside a @param description violates the convention; TypeDoc auto-links param types, making this redundant noise. Fix: use backtick notation or drop the inline link.

2. Service class JSDoc not in sync with model (conversational-agent.ts:146–170) — Convention requires the service class and ServiceModel JSDoc to be identical. Three divergences: missing 4-sentence description paragraph, mismatched @param format, and @example title/comment differences.

3. Test file not mirroring src/ structure (citation.test.ts:1) — tests/unit/ must mirror src/ structure. The helper source is at src/services/conversational-agent/helpers/citation.ts, so the test belongs at tests/unit/services/conversational-agent/helpers/citation.test.ts.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

Review findings

One previously-resolved thread was unresolved this run:

• Test file path not mirroring src/ structure (citation.test.ts:1) — The test file is still at tests/unit/helpers/conversational-agent/citation.test.ts. The fix (moving it to tests/unit/services/conversational-agent/helpers/citation.test.ts to mirror the source at src/services/conversational-agent/helpers/citation.ts) was not included in the pushed fixes. Unresolved the thread.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
94.8% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud