Skip to content

Add the Agent Signatures feature page - #232

Open
jwrosewell wants to merge 3 commits into
mainfrom
feature/agent-signature-page
Open

Add the Agent Signatures feature page#232
jwrosewell wants to merge 3 commits into
mainfrom
feature/agent-signature-page

Conversation

@jwrosewell

@jwrosewell jwrosewell commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

Adds the customer documentation for the agent signature element that
51Degrees/pipeline-dotnet#373 implements.

Changes:

  1. New feature page src/pipelineapi/features/agentsignature.md
    covering what Web Bot Auth is in plain words, the twelve
    properties, the five statuses with all seventeen reason codes, the
    configuration options with defaults, how keys are fetched and
    cached (including why the first request from a new agent can read
    Timeout), what is not covered (nonce replay, components beyond the
    authority and scheme until Add request method, path and query string to web evidence for signature verification pipeline-dotnet#374 is done,
    and cloud), and the example.
  2. @subpage entry in src/pipelineapi/features/index.md, first in
    the list because AgentSignature sorts before AsynchronousExecution.
  3. Aliases agentsignature and Agentsignature in docs/Doxyfile,
    matching the neighbouring aliases' form.
  4. A "Signed Agents" section in
    src/devicedetection/features/crawlers.md saying the crawler
    properties and the signature properties are used together, with
    IsCrawler reporting what an agent declares and AgentSignature
    reporting what an agent proves.

Every behaviour stated on the page was checked against the element
source on the pipeline-dotnet branch rather than written from memory.
Two things need checking at review: the rendered Doxygen build was
not run here, so the page should be built and looked at before merge,
and the @grabexample identifier for the example block follows the
pattern of the usage sharing page but cannot be confirmed until a
build runs against the pipeline-dotnet branch that carries the
example.

@github-actions

github-actions Bot commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

Documentation preview 👀

@jwrosewell

Copy link
Copy Markdown
Contributor Author

The Doxygen build check this PR was waiting on has been run and is clean.

Doxygen is not installed locally, so the pinned Linux binary the CI script downloads (ci/generate-documentation.ps1, doxygen 1.17.0 from 51Degrees/tools) was run under WSL with OUTPUT_DIRECTORY pointed at a temporary folder, leaving the worktree untouched. Both CI stages were replicated, the site build from docs/Doxyfile and the pipeline-dotnet API build with the repository layout CI uses. Both exited 0.

What was checked on the new page:

  • src/pipelineapi/features/agentsignature.md generates with no warnings of its own.
  • All five anchors are defined and every in-page @ref resolves (AgentSignature_Configuration, AgentSignature_Caching, AgentSignature_Properties, AgentSignature_NotCovered, AgentSignature_HowVerified).
  • The example reference resolves. The page emits grabExample(this, 'pipeline-dotnet', '_agent_signature_2_program_8cs') and the pipeline-dotnet build produces exactly _agent_signature_2_program_8cs-example.html with the element examplegrabber.js loads. This depends on the example being on pipeline-dotnet main, which it now is.
  • Cross-page links resolve both ways between this page and the device detection crawlers page, and the features index lists the new subpage.
  • Every alias the page uses exists in docs/Doxyfile, and ci/validate-html.ps1 -FailOnFinding reports nothing on either changed page.

The remaining warnings in the run are pre-existing or environmental (graphviz and sibling API repositories absent locally, and obsolete Doxyfile tags that are on main). One finding does belong to pipeline-dotnet rather than here, Doxygen reading HTTP signature component names such as @authority in doc comments as commands, raised as 51Degrees/pipeline-dotnet#382.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant