@yadsh/dsh-web-fetch-authenticated
Русский гайд: настройка Jira и Confluence
An authenticated, policy-gated WebFetchProvider for the
DeepSeek Harness web capability seam (ctx.web). It lets the existing
model-facing web_fetch(url) tool retrieve content from approved
authenticated resources — corporate Jira, Confluence, GitLab, internal wikis —
without exposing credentials to the model, the tool arguments, session logs,
prompts, or the browser UI.
The model chooses a URL. The plugin decides whether that URL is allowed,
which credential may be used for it, how authentication is attached, and
whether redirects are safe. The model never supplies or receives secrets.
Installation
Install the published npm package by name:
dsh plugin --profile web add @yadsh/dsh-web-fetch-authenticated
To remove the plugin:
dsh plugin --profile web remove @yadsh/dsh-web-fetch-authenticated
Then pin the provider in the profile patch (fetchProvider: authenticated) so
the model-facing web_fetch tool routes through this plugin; without the pin
the plugin stays inert.
How it works
web_fetch(url)
-> ctx.web (fetchProvider: authenticated)
-> normalize URL
-> rule match (exact hosts, glob paths)
-> network policy (SSRF: DNS resolution + per-address classification)
-> credential lookup (ctx.credentials, per request)
-> auth injection (Bearer / Basic / API-key header)
-> request with DNS pinning
-> per-hop redirect re-validation
-> bounded body read
-> content adapter (optional: REST fetch + normalization, see below)
-> WebFetchResult (existing dsh-tool-web HTML -> Markdown)
- One fetch provider (
id: authenticated) routes internally across all rules —
web_fetch and the model stay unchanged (SPEC §16).
- Requests without a matching rule fail closed (
AUTH_FETCH_NO_MATCHING_RULE).
- Authentication is attached only after URL validation, rule matching, and
network-policy approval; redirect targets are re-matched and re-checked, and
a credential never crosses into an origin its own rule does not authorize.
- Logs, audit records, error messages, and UI previews are scrubbed by the
centralized redaction utilities.
Configuration
Everything is editable from the DSH Web UI — the configuration of this
plugin's row on the host Plugins page: rules, credential write-only fields,
network policy, redirects, limits, connection tester, and diagnostics. The row
is headed with this package's name and its manifest description; the card under
it is the configuration. The declarative profile config below edits the same
document and stays available:
- id: web
config:
fetchProvider: authenticated
- id: web-fetch-authenticated
name: '@yadsh/dsh-web-fetch-authenticated'
config:
rules:
- id: corp-jira
name: Corporate Jira
enabled: true
testUrl: https://jira.example.corp/status
match:
hosts: [jira.example.corp]
allowPaths: [/browse/**, /rest/api/**]
auth:
type: bearer
credential: JIRA_TOKEN # credential REFERENCE, not the secret
networkPolicy:
allowPrivate: true
allowedCidrs: [10.40.0.0/16]
redirects:
mode: same-origin
maxRedirects: 3
- id: tool-web
name: '@deepseek-ai/dsh-tool-web'
config:
fetch: true
Secrets are stored through the DSH credential store ($DSH_HOME credential
backend) under POSIX-style reference names (JIRA_TOKEN); configuration keeps
only the reference. Use the UI (or api.credentials.set) to store the value.
For an end-to-end corporate setup, including provider selection, credentials,
private-network policy, Jira/Confluence Cloud and Server/Data Center examples,
testing, and troubleshooting, see the
Russian Jira and Confluence guide.
Security defaults
| Policy | Default |
|---|
| Schemes | HTTPS only (per-rule http opt-in warns) |
| Private networks / loopback / link-local / CGNAT / IPv6 ULA | denied |
| Cloud metadata (169.254.169.254, fd00:ec2::254) | always denied |
| Redirects | same-origin only, max 3 |
| Timeout / response size / body chars | 30 s / 5 MiB / 100 k chars |
| Unmatched URLs | blocked (strict) |
Narrow allowedCidrs are preferred over blanket allowPrivate: true. DNS
answers are resolved, all candidates are classified, one denied answer denies
the whole set (DNS-rebinding defense), and the socket is pinned to the
approved addresses.
Content adapters (Jira / Confluence)
Raw HTML from enterprise apps converts to Markdown with all the application
chrome attached. A rule can instead select a content adapter: recognized
URLs are re-fetched from the product's REST API through the same authenticated
transport (same network policy, credentials, redirect policy, and limits) and
normalized into compact Markdown text — issue fields, description, and optional
comments/links for Jira; page metadata and the storage-format body for
Confluence. Unrecognized URLs fall back to raw HTTP/HTML.
- Jira —
/browse/ISSUE-KEY at any deployment depth and /issues/KEY.
jiraFlavor: server (default) uses REST v2 and converts wiki-markup bodies;
jiraFlavor: cloud uses REST v3 and converts Atlassian Document Format.
includeComments and includeLinks add comments and issue links (off by
default).
- Confluence —
/pages/<id>/… (Server and Cloud, including /wiki/…
paths), the page links Confluence itself hands out
(/pages/viewpage.action?pageId=<id>, plus the legacy
?spaceKey=<KEY>&title=<Title> form), and /display/<SPACE>/<Title>
(resolved through the title lookup). Storage-format XHTML becomes Markdown:
headings, paragraphs, lists (task lists become - [x] checkboxes), tables,
code/noformat fences, panel/info/note/warning/tip callouts, status badges,
links and entities. Layout macros (section, column, div) are unwrapped
so the content they wrap keeps its block structure.
Confluence cleanup levels
A Confluence storage body carries page chrome beside the prose. adapter.cleanup
decides how much of it reaches the model; the readable content is rendered
identically at every level.
| Level | Navigation macros¹ | Unknown macros | Attachments/images | Emoticons | Inline links, page links, callouts, tasks |
|---|
off | _[macro: toc — 2]_ | name + parameters | link to the file (marker only when the URL is unknown) | name | kept |
balanced (default) | dropped | _[macro: name]_ | link to the file (marker only when the URL is unknown) | name | kept |
strict | dropped | body only, no marker | dropped | dropped | kept |
¹ A table of contents, child-page list, attachment list, search widget, and the
like: macros that aggregate or navigate instead of carrying content. Cross-page
includes still leave _[includes: Page]_ at off/balanced, because that
reference is the only trace of the missing text.
Configured in the rule editor ("Content adapter" → "Page cleanup") or
declaratively:
adapter:
type: jira
jiraFlavor: server
includeComments: true
adapter:
type: confluence
cleanup: strict
maxAttachments: 50
Non-2xx REST responses stay results (the seam never throws for status codes):
the model sees a short [Jira]/[Confluence] HTTP-status note. Malformed or
non-JSON REST bodies fail with AUTH_FETCH_ADAPTER_FAILED. The generated text
is capped by the rule's maxBodyChars, and the connection tester runs the
adapter too, so Test shows the exact normalized text the model will get.
Confluence attachments and document text
A storage body names an attachment and nothing else — <ri:attachment ri:filename="Регламент.docx"/> — so a page that says "see the attached
regulation" used to reach the model as a bare filename it could do nothing with.
The adapter now resolves every attachment reference (linked file, embedded
image, embedded Office/PDF viewer macro) into its download URL and appends the
page's attachment list:
## Attachments
- [Регламент v3.docx](https://wiki.example.corp/wiki/download/attachments/483043310/Регламент%20v3.docx?api=v2) — 46.0 KiB, application/vnd.openxmlformats-officedocument.wordprocessingml.document
The list is the page's own attachment collection, so a document the prose
mentions without linking it is still reachable. adapter.maxAttachments
(default 50, 0 disables the list) caps how many entries one page reports; the
remainder is stated as a count, never dropped silently. A failed collection
request never costs the page — the prose is served with an
_[attachment list unavailable]_ marker. cleanup: strict serves neither links
nor the list.
The normal web_fetch result is text-only: the WebFetchBody union is
html | text and owned by @deepseek-ai/dsh-web. This plugin therefore
extracts supported document text inside the provider and returns it as text:
- Supported: Word
.docx/.docm/.dotx and OpenDocument .odt — the
document is inflated in memory (no external binary, no temporary file) and
rendered as Markdown: headings, paragraphs, list items, tables, tabs. Field
codes, deleted revisions, comments, drawings, and footnotes are left out.
- Refused with a reason:
.pdf, .doc, .xlsx, .pptx, archives — the
model gets AUTH_FETCH_DOCUMENT_UNREADABLE naming the format instead of a
bare "unsupported content type".
- Not a document: everything else keeps the plain
AUTH_FETCH_UNSUPPORTED_CONTENT behavior.
Files: web_fetch_file
For a PDF, spreadsheet, presentation, archive, log, unsupported Office file,
or an ordinary HTML/JSON/XML response whose exact bytes are needed, the plugin
registers web_fetch_file(url) while durable attachment storage is available.
It runs the same authenticated rule, SSRF, DNS pinning, redirect, timeout and
response-size pipeline as web_fetch, then saves the successful response as an
immutable file attachment. Non-2xx responses and bodies above the matched
rule's byte cap are refused and are never stored.
The settings card lists these content families so operators can see which of
the three tools to grant. Registration does not grant access by itself:
administrators still decide which roles or grantable skills receive
web_fetch_file, just as they do for web_fetch_image.
Images: web_fetch_image
An image is the one download the text seam cannot carry at all, so the plugin
registers a second model-facing tool beside web_fetch (SPEC §15.4):
web_fetch_image(url)
-> the same rule match, network policy and credentials as web_fetch
-> bounded byte read (deployment image limits)
-> format verified from the file signature, not the server header
-> ctx.attachments.saveImage (durable raster attachment)
-> tool result: text summary + the image block the model can look at
- Use it for image attachments, screenshots and charts whose URL
web_fetch
refuses as binary content. web_fetch itself stays text-only: the harness
body union (html | text) belongs to @deepseek-ai/dsh-web and has no
binary arm a provider could fill.
- Stored formats are the attachment store's raster set: PNG, JPEG, WebP, GIF.
A response that is not one of them — an HTML error page, a PDF, a 404 —
fails with
AUTH_FETCH_NOT_AN_IMAGE naming what arrived instead, and one
above the byte budget fails with AUTH_FETCH_IMAGE_TOO_LARGE.
- The tool registers only while a durable attachment store is mounted: without
one there is nowhere to keep the image and nothing that could render it
back to the model. A route whose model declares no image input is refused
before any download starts.
Caps are per rule and exist because the model's context is finite:
- id: corp-confluence
config:
documents:
enabled: true # default: true
maxBytes: 4194304 # largest attachment downloaded for extraction (4 MiB)
maxChars: 40000 # largest extracted text handed to the model
documents also exists at the top level as the default every rule inherits;
a rule's own block overrides it field by field. Exceeding maxBytes is
AUTH_FETCH_DOCUMENT_TOO_LARGE; text longer than maxChars is cut with an
explicit _[text truncated at N characters …]_ line and truncated: true in
the result. Both appear in the connection tester as well, so Test on an
attachment URL shows exactly the extracted text the model would receive.
Two rules are needed when Jira and Confluence share a hostname (jira.example.corp
serving both /browse/** and /wiki/**): one rule per product, with
non-overlapping allowPaths — a rule has exactly one adapter, and a Confluence
page served by a rule whose adapter is jira falls through to raw HTML.
Error codes
AUTH_FETCH_NO_MATCHING_RULE, AUTH_FETCH_AMBIGUOUS_MATCH,
AUTH_FETCH_RULE_DISABLED, AUTH_FETCH_CREDENTIAL_MISSING,
AUTH_FETCH_CREDENTIAL_INVALID, AUTH_FETCH_NETWORK_DENIED,
AUTH_FETCH_DNS_POLICY_DENIED, AUTH_FETCH_REDIRECT_DENIED,
AUTH_FETCH_RESPONSE_TOO_LARGE, AUTH_FETCH_UNSUPPORTED_CONTENT,
AUTH_FETCH_DOCUMENT_TOO_LARGE, AUTH_FETCH_DOCUMENT_UNREADABLE,
AUTH_FETCH_NOT_AN_IMAGE, AUTH_FETCH_IMAGE_TOO_LARGE,
AUTH_FETCH_TIMEOUT, AUTH_FETCH_INVALID_URL, AUTH_FETCH_PROVIDER_ERROR,
AUTH_FETCH_ADAPTER_FAILED —
surfaced as WebError codes through the existing web_fetch error metadata.
Development
pnpm install
pnpm --filter @yadsh/dsh-web-fetch-authenticated build
pnpm --filter @yadsh/dsh-web-fetch-authenticated test
pnpm --filter @yadsh/dsh-web-fetch-authenticated check # lint + typecheck + test + verify
INVESTIGATE.md documents the exact DSH APIs and integration assumptions
(SPEC phase 0). Cookies/OAuth and advanced auth remain excluded (SPEC §29
phase 5); the Jira/Confluence content adapters (phase 4) are implemented.
License
MIT
