<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: HK Analytical</title>
    <description>The latest articles on DEV Community by HK Analytical (@hkanalytical).</description>
    <link>https://dev.to/hkanalytical</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4250235%2Fd02dac8b-e3ce-4403-b684-087cf066dc6d.png</url>
      <title>DEV Community: HK Analytical</title>
      <link>https://dev.to/hkanalytical</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/hkanalytical"/>
    <language>en</language>
    <item>
      <title>Signing lab reports with Ed25519: why we sign a canonical record, not the PDF</title>
      <dc:creator>HK Analytical</dc:creator>
      <pubDate>Wed, 18 Nov 2026 05:59:05 +0000</pubDate>
      <link>https://dev.to/hkanalytical/signing-lab-reports-with-ed25519-why-we-sign-a-canonical-record-not-the-pdf-4i7m</link>
      <guid>https://dev.to/hkanalytical/signing-lab-reports-with-ed25519-why-we-sign-a-canonical-record-not-the-pdf-4i7m</guid>
      <description>&lt;p&gt;A lab report (a certificate of analysis, or COA) is a small document with a large trust problem. The lab issues a PDF. A seller posts it. A buyer reads it months later, on a page the lab does not control. A PDF can be edited in minutes, and a screenshot is easier still.&lt;/p&gt;

&lt;p&gt;We wanted a report that a stranger can check without trusting the page it sits on, and without trusting us to answer an email. This post covers the design we chose: an Ed25519 signature over a canonical data record, with the PDF tied to that record by its hash. The pattern works for any document that has to stay provable: invoices, certificates, audit exports.&lt;/p&gt;

&lt;h2&gt;
  
  
  Option 1: sign the PDF
&lt;/h2&gt;

&lt;p&gt;PDF has its own signature standard, PAdES (ETSI EN 319 142-1). The reader software shows a signature panel, and trust comes from certificates that the reader already knows.&lt;/p&gt;

&lt;p&gt;That solves a related problem, but it has costs for our case:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;The signature is tied to one rendering. The same results on a web page or in an API response are not covered.&lt;/li&gt;
&lt;li&gt;A check needs a PDF library that understands signatures, or a desktop reader. It is hard to do in twenty lines of code.&lt;/li&gt;
&lt;li&gt;The signed thing is a layout. To learn what was signed, a program has to extract text from a page.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Option 2: sign the data
&lt;/h2&gt;

&lt;p&gt;A report is data first: sample, tests, methods, dates, results. The PDF and the web page are two views of it. So we sign the data, in one fixed form, and derive every view from the signed record.&lt;/p&gt;

&lt;p&gt;The check then needs three inputs: the record, the signature and a public key. Any language with an Ed25519 library can do it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why canonicalisation matters
&lt;/h2&gt;

&lt;p&gt;A signature covers bytes, not meaning. These two objects are equal as JSON and different as bytes:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="nb"&gt;JSON&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;stringify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;purity&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"99.0"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;lot&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"A1"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// {"purity":"99.0","lot":"A1"}&lt;/span&gt;
&lt;span class="nb"&gt;JSON&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;stringify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;lot&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"A1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;purity&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"99.0"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// {"lot":"A1","purity":"99.0"}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If the signer and the verifier serialise in different ways, a correct record fails the check. "Canonical" means there is exactly one way to write the record down. We use the JSON Canonicalization Scheme, RFC 8785: object keys sorted by UTF-16 code unit, no whitespace, numbers in the ECMAScript shortest form, strings escaped as &lt;code&gt;JSON.stringify&lt;/code&gt; does it.&lt;/p&gt;

&lt;p&gt;For values that came out of &lt;code&gt;JSON.parse&lt;/code&gt;, a canonicaliser is short:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;canonicalize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;v&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;v&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="n"&gt;v&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="s2"&gt;"object"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="n"&gt;v&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s2"&gt;"number"&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nb"&gt;Number&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isFinite&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;v&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;TypeError&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"not JSON"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nb"&gt;JSON&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;stringify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;v&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Array&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isArray&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;v&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="sb"&gt;`[${v.map(canonicalize).join(",")}]`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;keys&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Object&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;keys&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;v&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sort&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="sb"&gt;`{${keys.map((k) =&amp;gt; `&lt;/span&gt;&lt;span class="nv"&gt;${JSON.stringify(k)}&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="nv"&gt;${canonicalize(v[k])}&lt;/span&gt;&lt;span class="sb"&gt;`).join(",")}}`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two decisions made this safer in practice.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Reported numbers are strings.&lt;/strong&gt; A purity of &lt;code&gt;"99.0"&lt;/code&gt; is not the same statement as &lt;code&gt;99&lt;/code&gt;. A JSON number loses the trailing zero, and with it the precision the lab reported. In our records every reported value is a decimal string, so what is signed is what is printed.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The exact signed string travels with the signature.&lt;/strong&gt; Our public signed record carries a &lt;code&gt;canonical&lt;/code&gt; field: the canonical JSON as a string. The signature is Ed25519 over the UTF-8 bytes of that string, encoded as base64url without padding (86 characters). A verifier does not need to re-serialise anything to check the signature. A careful verifier also parses the string, canonicalises it again and confirms that the result is identical, so a non-canonical record is refused.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;canonical&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;canonicalize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;record&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;bytes&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;TextEncoder&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;encode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;canonical&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;sig&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;crypto&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;subtle&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sign&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Ed25519"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;privateKey&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;bytes&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;// publish { canonical, signature: base64url(sig) }&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  What goes inside the record
&lt;/h2&gt;

&lt;p&gt;Anything inside the record is protected. Anything outside it is not. So scope matters as much as the algorithm. Our record holds the report ID, a version number, the issue time, the ID of the signing key, the lab's details at the time of issue, and the full report input: product, client, dates, tests and results. Attachments are in by fingerprint: the vial photo and the raw instrument files appear as SHA-256 values.&lt;/p&gt;

&lt;p&gt;The record also states how the client is related to the lab. That statement is inside the signed bytes, so it cannot be cropped off a screenshot without breaking the check.&lt;/p&gt;

&lt;h2&gt;
  
  
  The PDF is tied in by hash
&lt;/h2&gt;

&lt;p&gt;A PDF cannot contain its own hash, so the record cannot name the PDF. We sign a second, small object, the manifest:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"coa_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"HK-..."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"version"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"record_sha256"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&amp;lt;SHA-256 of the canonical record&amp;gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"pdf_sha256"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&amp;lt;SHA-256 of the PDF file&amp;gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"issued_at"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"2026-10-25T08:39:05Z"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"key_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"hk-..."&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two signatures, one key. The first proves the data. The second proves which PDF file is the rendering of that data. The file fingerprint is SHA-256 over every byte of the file, so "print to PDF" or a re-save gives a different file, even when the text looks the same.&lt;/p&gt;

&lt;h2&gt;
  
  
  Key publication
&lt;/h2&gt;

&lt;p&gt;A signature is only as good as the source of the public key. If a forger can hand you a key, the forger can sign anything. Our keys are in one JSON file at a fixed address, &lt;code&gt;hkanalytical.com/.well-known/hk-coa-keys.json&lt;/code&gt;. Each entry has a key ID (&lt;code&gt;kid&lt;/code&gt;), the algorithm, the 32-byte public key as base64url (&lt;code&gt;x&lt;/code&gt;), a creation date and a status. Each record names its key by &lt;code&gt;kid&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Status does real work. A retired key no longer signs, but old reports still check against it. A compromised key is marked revoked, with a date. One key is marked demo: it signs only our example reports, and a report signed with it is never shown as valid.&lt;/p&gt;

&lt;p&gt;The private key never leaves the lab's control. Verification needs only the public key, so nothing that serves or checks a report has to hold a secret.&lt;/p&gt;

&lt;h2&gt;
  
  
  What a signature proves, and what it does not
&lt;/h2&gt;

&lt;p&gt;A valid signature proves that the record was signed with the lab's private key, that not one byte changed since, which key signed it, and which version you hold.&lt;/p&gt;

&lt;p&gt;It does not prove that the measurements are right, that the evidence supports the result, or that your vial came from the batch tested. It also does not prove when the record was signed. A signed date is the signer's claim. An independent time needs an outside timestamp (RFC 3161) or an append-only public log (the pattern in RFC 9162).&lt;/p&gt;

&lt;p&gt;A signature also does not stop anyone from making a fake. It makes the fake fail a check that anyone can run.&lt;/p&gt;

&lt;h2&gt;
  
  
  Corrections
&lt;/h2&gt;

&lt;p&gt;Signing only works if issued records stay as issued. So a correction is never an edit. It is a new signed version. The old version stays on record, marked superseded, with the reason.&lt;/p&gt;

&lt;p&gt;This is not common practice yet. In HK Analytical's September 2026 review of public COAs from 25 labs and one rating site's certificate wrapper, none offered a public-key signature that anyone could check (two had partial schemes), 7 showed records edited or re-rendered in place with no visible version number, and only 1 showed a public change history.&lt;/p&gt;

&lt;h2&gt;
  
  
  Try it
&lt;/h2&gt;

&lt;p&gt;Our verify page prints a twelve-line Node script that checks both signatures from a downloaded record and the key file, with no packages. The steps for a full manual check are in &lt;a href="https://hkanalytical.com/guides/how-to-verify-a-peptide-coa" rel="noopener noreferrer"&gt;how to verify a peptide COA&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;HK Analytical is a peptide testing lab. The longer, non-developer version of this design is in our guide to &lt;a href="https://hkanalytical.com/guides/signed-coa" rel="noopener noreferrer"&gt;signed COAs&lt;/a&gt;.&lt;/p&gt;

</description>
      <category>security</category>
      <category>cryptography</category>
      <category>javascript</category>
      <category>architecture</category>
    </item>
    <item>
      <title>Independent third-party testing and certificates of analysis for research peptides. https://hkanalytical.com</title>
      <dc:creator>HK Analytical</dc:creator>
      <pubDate>Tue, 17 Nov 2026 16:17:54 +0000</pubDate>
      <link>https://dev.to/hkanalytical/independent-third-party-testing-and-certificates-of-analysis-for-research-peptides-a1m</link>
      <guid>https://dev.to/hkanalytical/independent-third-party-testing-and-certificates-of-analysis-for-research-peptides-a1m</guid>
      <description>&lt;div class="crayons-card c-embed text-styles text-styles--secondary"&gt;
    &lt;div class="c-embed__content"&gt;
        &lt;div class="c-embed__cover"&gt;
          &lt;a href="https://hkanalytical.com/" class="c-link align-middle" rel="noopener noreferrer"&gt;
            &lt;img alt="" src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fhkanalytical.com%2F_astro%2Fog-default.DZaHf-aZ.png" height="420" class="m-0" width="800"&gt;
          &lt;/a&gt;
        &lt;/div&gt;
      &lt;div class="c-embed__body"&gt;
        &lt;h2 class="fs-xl lh-tight"&gt;
          &lt;a href="https://hkanalytical.com/" rel="noopener noreferrer" class="c-link"&gt;
            Precision peptide analysis | HK Analytical
          &lt;/a&gt;
        &lt;/h2&gt;
          &lt;p class="truncate-at-3"&gt;
            Peptide reports you can check: identity by mass, raw data in every report, a signed record and USP &amp;lt;71&amp;gt; sterility. Results within days of receipt.
          &lt;/p&gt;
        &lt;div class="color-secondary fs-s flex items-center"&gt;
            &lt;img alt="favicon" class="c-embed__favicon m-0 mr-2 radius-0" src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fhkanalytical.com%2F_astro%2Ffavicon.CUgqV5iX.svg" width="16" height="16"&gt;
          hkanalytical.com
        &lt;/div&gt;
      &lt;/div&gt;
    &lt;/div&gt;
&lt;/div&gt;


</description>
    </item>
  </channel>
</rss>
