feat(pem): add parsePem to extract multiple DER blocks with labels

PEM files can contain multiple blocks (e.g., certificate chains).
This helper parses all blocks and returns their labels and DER data.

Author: Mythie

src/helpers/pem.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, expect, it } from "vitest";
 
-import { derToPem, getPemLabel, isPem, normalizePem, pemToDer } from "./pem";
+import { derToPem, getPemLabel, isPem, normalizePem, parsePem, pemToDer } from "./pem";
 
 describe("PEM utilities", () => {
   // Sample DER data (just random bytes for testing)
@@ -164,6 +164,113 @@ describe("PEM utilities", () => {
     });
   });
 
+  describe("parsePem", () => {
+    it("parses a single PEM block", () => {
+      const pem = derToPem(sampleDer, "CERTIFICATE");
+      const blocks = parsePem(pem);
+
+      expect(blocks).toHaveLength(1);
+      expect(blocks[0].label).toBe("CERTIFICATE");
+      expect(blocks[0].der).toEqual(sampleDer);
+    });
+
+    it("parses multiple PEM blocks", () => {
+      const der1 = new Uint8Array([0x01, 0x02, 0x03]);
+      const der2 = new Uint8Array([0x04, 0x05, 0x06]);
+      const der3 = new Uint8Array([0x07, 0x08, 0x09]);
+
+      const pem = [
+        derToPem(der1, "CERTIFICATE"),
+        derToPem(der2, "CERTIFICATE"),
+        derToPem(der3, "PRIVATE KEY"),
+      ].join("\n");
+
+      const blocks = parsePem(pem);
+
+      expect(blocks).toHaveLength(3);
+      expect(blocks[0]).toEqual({ label: "CERTIFICATE", der: der1 });
+      expect(blocks[1]).toEqual({ label: "CERTIFICATE", der: der2 });
+      expect(blocks[2]).toEqual({ label: "PRIVATE KEY", der: der3 });
+    });
+
+    it("handles different label types", () => {
+      const labels = [
+        "CERTIFICATE",
+        "PUBLIC KEY",
+        "PRIVATE KEY",
+        "RSA PRIVATE KEY",
+        "EC PRIVATE KEY",
+        "ENCRYPTED PRIVATE KEY",
+      ];
+
+      const pem = labels.map(label => derToPem(sampleDer, label)).join("\n");
+
+      const blocks = parsePem(pem);
+
+      expect(blocks).toHaveLength(labels.length);
+      for (let i = 0; i < labels.length; i++) {
+        expect(blocks[i].label).toBe(labels[i]);
+        expect(blocks[i].der).toEqual(sampleDer);
+      }
+    });
+
+    it("returns empty array for non-PEM string", () => {
+      expect(parsePem("not a pem")).toEqual([]);
+      expect(parsePem("")).toEqual([]);
+    });
+
+    it("handles PEM with extra whitespace and text between blocks", () => {
+      const der1 = new Uint8Array([0x01, 0x02]);
+      const der2 = new Uint8Array([0x03, 0x04]);
+
+      const pem = `
+        Some header text
+        ${derToPem(der1, "CERTIFICATE")}
+        Intermediate text here
+        ${derToPem(der2, "PRIVATE KEY")}
+        Footer text
+      `;
+
+      const blocks = parsePem(pem);
+
+      expect(blocks).toHaveLength(2);
+      expect(blocks[0]).toEqual({ label: "CERTIFICATE", der: der1 });
+      expect(blocks[1]).toEqual({ label: "PRIVATE KEY", der: der2 });
+    });
+
+    it("throws on mismatched BEGIN/END labels", () => {
+      const pem = `-----BEGIN CERTIFICATE-----
+AQID
+-----END PRIVATE KEY-----`;
+
+      expect(() => parsePem(pem)).toThrow(/label mismatch.*BEGIN CERTIFICATE.*END PRIVATE KEY/);
+    });
+
+    it("handles empty PEM blocks", () => {
+      const pem = `-----BEGIN CERTIFICATE-----
+-----END CERTIFICATE-----`;
+
+      const blocks = parsePem(pem);
+
+      expect(blocks).toHaveLength(1);
+      expect(blocks[0].label).toBe("CERTIFICATE");
+      expect(blocks[0].der).toEqual(new Uint8Array(0));
+    });
+
+    it("handles trailing text after last block", () => {
+      const pem = `${derToPem(sampleDer, "CERTIFICATE")}
+Some trailing text here
+-----BEGIN ORPHAN-----
+AQID`;
+
+      const blocks = parsePem(pem);
+
+      // Should only parse the complete block, ignoring the incomplete one
+      expect(blocks).toHaveLength(1);
+      expect(blocks[0].label).toBe("CERTIFICATE");
+    });
+  });
+
   describe("round-trip", () => {
     it("preserves data through multiple round-trips", () => {
       let data: Uint8Array = sampleDer;

src/helpers/pem.ts

@@ -7,6 +7,71 @@
 
 import { base64 } from "@scure/base";
 
+/**
+ * A single PEM block parsed from a PEM file.
+ */
+export interface PemBlock {
+  /** The label from the BEGIN statement (e.g., "CERTIFICATE", "PRIVATE KEY") */
+  label: string;
+  /** The DER-encoded binary data */
+  der: Uint8Array;
+}
+
+/**
+ * Parse a PEM file into a series of DER blocks with their types.
+ *
+ * PEM files can contain multiple blocks (e.g., certificate chains). This function
+ * extracts each block along with its label from the BEGIN statement.
+ *
+ * @param pem - The PEM-encoded string (may contain multiple blocks)
+ * @returns Array of PEM blocks, each containing a label and DER data
+ * @throws {Error} if the PEM format is invalid (mismatched labels or missing markers)
+ *
+ * @example
+ * ```typescript
+ * const blocks = parsePem(pemString);
+ * // [
+ * //   { label: "CERTIFICATE", der: Uint8Array(...) },
+ * //   { label: "CERTIFICATE", der: Uint8Array(...) },
+ * //   { label: "PRIVATE KEY", der: Uint8Array(...) }
+ * // ]
+ * ```
+ */
+export function parsePem(pem: string): PemBlock[] {
+  const blocks: PemBlock[] = [];
+
+  // Match all BEGIN...END blocks with their content
+  // The regex captures: (1) label from BEGIN, (2) base64 content, (3) label from END
+  const blockRegex = /-----BEGIN ([A-Z0-9 ]+)-----([\s\S]*?)-----END ([A-Z0-9 ]+)-----/g;
+
+  let match: RegExpExecArray | null;
+
+  while ((match = blockRegex.exec(pem)) !== null) {
+    const beginLabel = match[1];
+    const content = match[2];
+    const endLabel = match[3];
+
+    // Validate that BEGIN and END labels match
+    if (beginLabel !== endLabel) {
+      throw new Error(`PEM label mismatch: BEGIN ${beginLabel} but END ${endLabel}`);
+    }
+
+    // Remove all whitespace from base64 content
+    const b64 = content.replace(/\s/g, "");
+
+    // Skip empty blocks
+    if (b64.length === 0) {
+      blocks.push({ label: beginLabel, der: new Uint8Array(0) });
+      continue;
+    }
+
+    const der = base64.decode(b64);
+    blocks.push({ label: beginLabel, der });
+  }
+
+  return blocks;
+}
+
 /**
  * Convert DER (binary) bytes to PEM format.
  *

src/index.ts

@@ -188,6 +188,12 @@ export {
   type TextLine,
 } from "./api/drawing";
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+export { parsePem, type PemBlock } from "./helpers/pem";
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Annotations
 // ─────────────────────────────────────────────────────────────────────────────