@push.rocks/smartlinuxrepo 1.0.0 → 1.1.0

package/ts/signing/openpgpframing.ts

@@ -1,4 +1,5 @@
-import { LinuxRepoError } from '../shared/errors.js';
+import { decodeLatin1, decodeStrictUtf8 } from '../readers/text.js';
+import { LinuxRepoError, type TLinuxRepoErrorCode } from '../shared/errors.js';
 import { assertAsyncIterable, assertBytes, assertString, assertTimestamp } from '../shared/validation.js';
 import { singleChunk, type IOpenPgpSigner } from './signers.js';
 
@@ -6,6 +7,10 @@ import { singleChunk, type IOpenPgpSigner } from './signers.js';
  * The OpenPGP framing the codec owns: only the bytes of the signature packet
  * may vary; framing and armor are deterministic.
  * Armor has no headers, 64-column base64 and a CRC-24 line.
+ *
+ * The readers below are the strict inverses the verifier uses; openpgp.js's
+ * own dearmoring is never used (it skips text around the block, ignores the
+ * CRC-24 and strips trailing whitespace inside cleartext).
  */
 
 const BASE64_LINE = 64;
@@ -47,7 +52,7 @@ export async function createDetachedArmoredSignature(inputArg: {
  * Cleartext-signs `text` (`InRelease`). The text must be canonical: no CR and
  * no trailing spaces or tabs on any line. The signed text is `text` without
  * its final line break; the output always ends the text with one line break
- * before the signature block, as GnuPG and Go do. Lines starting with `-` are
+ * before the signature block, as GnuPG does. Lines starting with `-` are
  * dash-escaped. The header is always `Hash: SHA256`.
  */
 export async function createCleartextSignedMessage(inputArg: {
@@ -98,6 +103,294 @@ function assertSignatureBytes(packetArg: unknown): asserts packetArg is Uint8Arr
   }
 }
 
+/** How a framing reader refuses its input: the error code and the input field it names. */
+export interface IFramingFailure {
+  code: TLinuxRepoErrorCode;
+  field: string;
+}
+
+export type TArmorLabel = 'PUBLIC KEY BLOCK' | 'SIGNATURE';
+
+/** A well-formed armor header line (`Key: Value`), as openpgp.js 6.3.2 checks it (`verifyHeaders$1`). */
+const ARMOR_HEADER_PATTERN = /^([^\s:]|[^\s:][^:]*[^\s:]): .+$/;
+const BASE64_LINE_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/;
+const BASE64_PATTERN = /^[A-Za-z0-9+/]*={0,2}$/;
+const CRC_LINE_PATTERN = /^=[A-Za-z0-9+/]{4}$/;
+const CLEARTEXT_BEGIN = '-----BEGIN PGP SIGNED MESSAGE-----';
+const SIGNATURE_BEGIN = '-----BEGIN PGP SIGNATURE-----';
+
+/** RFC 9580 table 23 hash text names (the `Hash:` header) and their algorithm IDs. */
+const HASH_TEXT_NAMES: ReadonlyMap<string, number> = new Map([
+  ['MD5', 1],
+  ['SHA1', 2],
+  ['RIPEMD160', 3],
+  ['SHA256', 8],
+  ['SHA384', 9],
+  ['SHA512', 10],
+  ['SHA224', 11],
+  ['SHA3-256', 12],
+  ['SHA3-512', 14],
+]);
+
+function framingError(failureArg: IFramingFailure, messageArg: string): LinuxRepoError {
+  return new LinuxRepoError(failureArg.code, messageArg, { field: failureArg.field });
+}
+
+/** Bytes that must be ASCII armor, as text; any byte above 0x7F is refused. */
+export function decodeArmorBytes(bytesArg: Uint8Array, failureArg: IFramingFailure): string {
+  for (let i = 0; i < bytesArg.length; i++) {
+    if (bytesArg[i] > 0x7f) {
+      throw framingError(failureArg, 'ASCII armor must be ASCII');
+    }
+  }
+  return decodeLatin1(bytesArg);
+}
+
+/**
+ * Reads exactly one ASCII armor block labelled `labelArg` (RFC 9580 section
+ * 6.2) and returns its bytes; the inverse of `armorSignature`. Lines may end
+ * in LF or CRLF and carry trailing spaces or tabs, and blank lines may
+ * surround the block. Well-formed `Key: Value` headers are ignored; the
+ * CRC-24 line is optional and must match when present. Refused with
+ * `failureArg`: non-ASCII text, another label, a second block or any other
+ * text outside the block, a malformed header line, no blank line before the
+ * data, base64 that is not canonical, no data, and a CRC-24 that does not
+ * match.
+ */
+export function dearmor(textArg: string, labelArg: TArmorLabel, failureArg: IFramingFailure): Uint8Array {
+  const lines = textArg.split('\n').map(trimLineEnd);
+  let first = 0;
+  while (first < lines.length && lines[first] === '') {
+    first += 1;
+  }
+  let last = lines.length - 1;
+  while (last >= first && lines[last] === '') {
+    last -= 1;
+  }
+  return readArmorBlock(lines.slice(first, last + 1), labelArg, failureArg);
+}
+
+/** The line without trailing spaces, tabs and CRs; a loop, as a `+$` regex is quadratic on a long run of them. */
+function trimLineEnd(lineArg: string): string {
+  let end = lineArg.length;
+  while (end > 0 && (lineArg[end - 1] === ' ' || lineArg[end - 1] === '\t' || lineArg[end - 1] === '\r')) {
+    end -= 1;
+  }
+  return lineArg.slice(0, end);
+}
+
+/** One armor block, from its BEGIN line to its END line, as exactly these lines; ASCII only. */
+function readArmorBlock(linesArg: readonly string[], labelArg: TArmorLabel, failureArg: IFramingFailure): Uint8Array {
+  if (linesArg.some((line) => !/^[\x00-\x7f]*$/.test(line))) {
+    throw framingError(failureArg, 'ASCII armor must be ASCII');
+  }
+  const begin = `-----BEGIN PGP ${labelArg}-----`;
+  const end = `-----END PGP ${labelArg}-----`;
+  if (linesArg[0] !== begin) {
+    throw framingError(failureArg, `expected exactly one ${begin} block and nothing else`);
+  }
+  const endIndex = linesArg.indexOf(end);
+  if (endIndex < 0 || endIndex !== linesArg.length - 1) {
+    throw framingError(failureArg, `expected exactly one ${begin} block ending in ${end} and nothing else`);
+  }
+  let index = 1;
+  for (; index < endIndex && linesArg[index] !== ''; index++) {
+    if (!ARMOR_HEADER_PATTERN.test(linesArg[index])) {
+      throw framingError(failureArg, 'malformed armor header line');
+    }
+  }
+  if (index >= endIndex) {
+    throw framingError(failureArg, 'the armor has no blank line before its data');
+  }
+  index += 1;
+  const dataLines: string[] = [];
+  let crcLine: string | null = null;
+  for (; index < endIndex; index++) {
+    const line = linesArg[index];
+    if (index === endIndex - 1 && line.startsWith('=')) {
+      crcLine = line;
+      break;
+    }
+    if (!BASE64_LINE_PATTERN.test(line)) {
+      throw framingError(failureArg, 'the armor data is not base64');
+    }
+    dataLines.push(line);
+  }
+  const base64 = dataLines.join('');
+  if (base64.length === 0 || base64.length % 4 !== 0 || !BASE64_PATTERN.test(base64)) {
+    throw framingError(failureArg, 'the armor data is not one base64 string');
+  }
+  const decoded = Buffer.from(base64, 'base64');
+  if (decoded.toString('base64') !== base64) {
+    throw framingError(failureArg, 'the armor data is not canonical base64');
+  }
+  const bytes = new Uint8Array(decoded.buffer, decoded.byteOffset, decoded.byteLength);
+  if (crcLine !== null && (!CRC_LINE_PATTERN.test(crcLine) || crcLine.slice(1) !== crc24Base64(bytes))) {
+    throw framingError(failureArg, 'the armor CRC-24 does not match its data');
+  }
+  return bytes;
+}
+
+/**
+ * The packet tags of a binary OpenPGP packet sequence, read from the packet
+ * headers alone (RFC 9580 section 4.2); no body is parsed. openpgp.js skips
+ * marker, trust and padding packets and unknown non-critical packet types
+ * without a trace (`PacketList.read`, `dist/node/openpgp.mjs:12320-12385`),
+ * so the verifier counts packets here. Refused with `failureArg`: a header
+ * without its high bit, a partial body length (no key or signature packet
+ * may use one), and input that ends inside a header or a body.
+ */
+export function readPacketTags(bytesArg: Uint8Array, failureArg: IFramingFailure): number[] {
+  const tags: number[] = [];
+  let offset = 0;
+  while (offset < bytesArg.length) {
+    const ctb = bytesArg[offset];
+    if ((ctb & 0x80) === 0) {
+      throw framingError(failureArg, `no OpenPGP packet header at byte ${offset}`);
+    }
+    let tag: number;
+    let headerLength: number;
+    let bodyLength: number;
+    if ((ctb & 0x40) !== 0) {
+      tag = ctb & 0x3f;
+      const first = bytesArg[offset + 1];
+      if (first === undefined) {
+        throw framingError(failureArg, 'the input ends inside a packet header');
+      }
+      if (first < 192) {
+        headerLength = 2;
+        bodyLength = first;
+      } else if (first < 224) {
+        if (offset + 3 > bytesArg.length) {
+          throw framingError(failureArg, 'the input ends inside a packet header');
+        }
+        headerLength = 3;
+        bodyLength = (first - 192) * 256 + bytesArg[offset + 2] + 192;
+      } else if (first === 255) {
+        if (offset + 6 > bytesArg.length) {
+          throw framingError(failureArg, 'the input ends inside a packet header');
+        }
+        headerLength = 6;
+        bodyLength = readUint32(bytesArg, offset + 2);
+      } else {
+        throw framingError(failureArg, 'a partial body length is not allowed here');
+      }
+    } else {
+      tag = (ctb >> 2) & 0x0f;
+      const lengthType = ctb & 0x03;
+      if (lengthType === 3) {
+        // indeterminate length: the packet runs to the end of the input
+        headerLength = 1;
+        bodyLength = bytesArg.length - offset - 1;
+      } else {
+        const lengthBytes = 1 << lengthType;
+        if (offset + 1 + lengthBytes > bytesArg.length) {
+          throw framingError(failureArg, 'the input ends inside a packet header');
+        }
+        headerLength = 1 + lengthBytes;
+        bodyLength = 0;
+        for (let i = 0; i < lengthBytes; i++) {
+          bodyLength = bodyLength * 256 + bytesArg[offset + 1 + i];
+        }
+      }
+    }
+    const packetEnd = offset + headerLength + bodyLength;
+    if (packetEnd > bytesArg.length) {
+      throw framingError(failureArg, 'the input ends inside a packet');
+    }
+    tags.push(tag);
+    offset = packetEnd;
+  }
+  return tags;
+}
+
+function readUint32(bytesArg: Uint8Array, offsetArg: number): number {
+  return ((bytesArg[offsetArg] * 256 + bytesArg[offsetArg + 1]) * 256 + bytesArg[offsetArg + 2]) * 256 + bytesArg[offsetArg + 3];
+}
+
+/** A cleartext-signed message split into its parts. */
+export interface ICleartextSignedParts {
+  /** Dash-escaping removed, lines joined by LF, without the line break before the signature block. */
+  signedText: string;
+  /** The RFC 9580 hash algorithm IDs the `Hash:` headers name, in order; empty without headers. */
+  headerHashAlgorithms: number[];
+  /** The bytes of the signature armor block. */
+  signature: Uint8Array;
+}
+
+/**
+ * Splits a cleartext-signed message (`InRelease`, RFC 9580 section 7); the
+ * inverse of `createCleartextSignedMessage`, and as strict as apt's own split
+ * (apt-pkg `SplitClearSignedFile`). The message is strict UTF-8 with LF line
+ * endings: the first line is `-----BEGIN PGP SIGNED MESSAGE-----`, then
+ * optional `Hash:` headers (comma-separated RFC 9580 text names), a blank
+ * line, the dash-escaped text and exactly one signature armor block, which
+ * may be followed by one line break and nothing else. Refused with
+ * `failureArg`: invalid UTF-8, a CR, a line ending in a space or tab, text
+ * before the message block or after the signature block, any other header, an
+ * unknown hash name, a text line starting with `-` but not `- `, and an empty
+ * text section. Armor headers inside the signature block are ignored as in
+ * `dearmor`.
+ */
+export function splitCleartextSignedMessage(bytesArg: Uint8Array, failureArg: IFramingFailure): ICleartextSignedParts {
+  const text = decodeStrictUtf8(bytesArg);
+  if (text === null) {
+    throw framingError(failureArg, 'the cleartext-signed message is not valid UTF-8');
+  }
+  if (text.includes('\r')) {
+    throw framingError(failureArg, 'the cleartext-signed message must use LF line endings');
+  }
+  const lines = text.split('\n');
+  if (lines[lines.length - 1] === '') {
+    lines.pop();
+  }
+  if (lines.some((line) => /[ \t]$/.test(line))) {
+    throw framingError(failureArg, 'a line of the cleartext-signed message ends with a space or tab');
+  }
+  if (lines[0] !== CLEARTEXT_BEGIN) {
+    throw framingError(failureArg, `the message does not start with ${CLEARTEXT_BEGIN}`);
+  }
+  let index = 1;
+  const headerHashAlgorithms: number[] = [];
+  for (; index < lines.length && lines[index] !== ''; index++) {
+    const header = /^Hash: (.+)$/.exec(lines[index]);
+    if (header === null) {
+      throw framingError(failureArg, 'only Hash: headers are allowed in a cleartext-signed message');
+    }
+    for (const name of header[1].split(',')) {
+      const algorithm = HASH_TEXT_NAMES.get(name.trim());
+      if (algorithm === undefined) {
+        throw framingError(failureArg, `unknown hash name in the Hash: header: ${name.trim()}`);
+      }
+      headerHashAlgorithms.push(algorithm);
+    }
+  }
+  index += 1;
+  const textLines: string[] = [];
+  for (; index < lines.length && lines[index] !== SIGNATURE_BEGIN; index++) {
+    const line = lines[index];
+    if (line.startsWith('-')) {
+      if (!line.startsWith('- ')) {
+        throw framingError(failureArg, 'a text line starts with "-" without the "- " escape');
+      }
+      textLines.push(line.slice(2));
+    } else {
+      textLines.push(line);
+    }
+  }
+  if (index >= lines.length) {
+    throw framingError(failureArg, `the message has no ${SIGNATURE_BEGIN} block`);
+  }
+  if (textLines.length === 0) {
+    throw framingError(failureArg, 'the message has no text section');
+  }
+  return {
+    signedText: textLines.join('\n'),
+    headerHashAlgorithms,
+    signature: readArmorBlock(lines.slice(index), 'SIGNATURE', failureArg),
+  };
+}
+
 /** RFC 4880 section 6.1 CRC-24, base64-encoded. */
 function crc24Base64(bytesArg: Uint8Array): string {
   let crc = 0xb704ce;

package/ts/signing/verifiers.ts

@@ -0,0 +1,357 @@
+import * as plugins from '../plugins.js';
+import { LinuxRepoError } from '../shared/errors.js';
+import { assertBytes, assertString, assertTimestamp } from '../shared/validation.js';
+import {
+  dearmor,
+  decodeArmorBytes,
+  readPacketTags,
+  splitCleartextSignedMessage,
+  type IFramingFailure,
+} from './openpgpframing.js';
+
+/** The hash algorithms the verifier accepts. */
+export type TOpenPgpHashAlgorithm = 'sha256' | 'sha384' | 'sha512';
+
+/** A signature that verified. */
+export interface IOpenPgpSignatureVerification {
+  /** The primary key or subkey that verified the signature, 40 uppercase hex digits. */
+  readonly signingKeyFingerprint: string;
+  /** The signature's creation time (whole seconds). */
+  readonly created: Date;
+  readonly hashAlgorithm: TOpenPgpHashAlgorithm;
+}
+
+/** A cleartext-signed message that verified. */
+export interface IOpenPgpCleartextVerification extends IOpenPgpSignatureVerification {
+  /**
+   * The signed text: dash-escaping removed, lines joined by LF, without the
+   * line break before the signature block (RFC 9580 section 7.1). For
+   * GnuPG's and the codec's `InRelease` this is `Release` without its final
+   * line break; for Gitea 28.2.0's (go-crypto) it is the whole `Release`.
+   */
+  readonly signedText: string;
+}
+
+/**
+ * Verifies OpenPGP signatures against one public key. Every method fails
+ * closed with a `LinuxRepoError` and never returns a verdict of failure:
+ * `malformed-signature`, `wrong-key`, `unusable-key` or `bad-signature`
+ * (bad arguments are `invalid-input`).
+ *
+ * A signature is valid when it is exactly one OpenPGP v4 signature packet,
+ * SHA-256, SHA-384 or SHA-512, issued by the primary key or one of its
+ * subkeys, created at or before `date` and not expired at `date`, made by a
+ * key or subkey that can sign both at the signature's creation time and at
+ * `date` (not expired, not revoked, sign flag set, valid binding and
+ * back-signature, openpgp.js's algorithm floor), and when it verifies
+ * cryptographically. `date` is required; the codec reads no clock.
+ */
+export interface IOpenPgpVerifier {
+  /** The primary key's v4 fingerprint, 40 uppercase hex digits (as `IOpenPgpKeyPair.fingerprint`). */
+  readonly fingerprint: string;
+  /**
+   * A binary detached signature of type 0x00 over `data`: the packet
+   * `IOpenPgpSigner.signBinary` returns, an Arch `.sig`.
+   */
+  verifyDetachedSignature(inputArg: { data: Uint8Array; signature: Uint8Array; date: Date }): Promise<IOpenPgpSignatureVerification>;
+  /**
+   * An armored detached signature of type 0x00 over `data`: `Release.gpg`,
+   * `repomd.xml.asc`. The armor is ASCII.
+   */
+  verifyArmoredDetachedSignature(inputArg: {
+    data: Uint8Array;
+    signatureArmored: Uint8Array;
+    date: Date;
+  }): Promise<IOpenPgpSignatureVerification>;
+  /**
+   * A cleartext-signed message with a signature of type 0x01: `InRelease`.
+   * The message is strict UTF-8 with LF line endings; see
+   * `splitCleartextSignedMessage` for what its framing may hold.
+   */
+  verifyCleartextMessage(inputArg: { message: Uint8Array; date: Date }): Promise<IOpenPgpCleartextVerification>;
+}
+
+const HASH_ALGORITHMS: ReadonlyMap<number, TOpenPgpHashAlgorithm> = new Map([
+  [plugins.openpgp.enums.hash.sha256, 'sha256'],
+  [plugins.openpgp.enums.hash.sha384, 'sha384'],
+  [plugins.openpgp.enums.hash.sha512, 'sha512'],
+]);
+
+/** Subpacket types openpgp.js reads in the unhashed area (issuer, embedded signature, issuer fingerprint). */
+const UNHASHED_SUBPACKETS_READ = new Set([16, 32, 33]);
+
+/**
+ * The openpgp.js settings verification depends on, pinned instead of taken
+ * from the process-wide `openpgp.config`. The values are openpgp.js 6.3.2's
+ * defaults except `ignoreUnsupportedPackets`.
+ */
+const VERIFY_CONFIG: plugins.openpgp.Config = {
+  ...plugins.openpgp.config,
+  ignoreUnsupportedPackets: false,
+  ignoreMalformedPackets: false,
+  enableParsingV5Entities: false,
+  additionalAllowedPackets: [],
+  allowMissingKeyFlags: false,
+  allowInsecureVerificationWithReformattedKeys: false,
+  minRSABits: 2047,
+  knownNotations: [],
+  rejectHashAlgorithms: new Set([plugins.openpgp.enums.hash.md5, plugins.openpgp.enums.hash.ripemd]),
+  rejectMessageHashAlgorithms: new Set([
+    plugins.openpgp.enums.hash.md5,
+    plugins.openpgp.enums.hash.ripemd,
+    plugins.openpgp.enums.hash.sha1,
+  ]),
+  rejectPublicKeyAlgorithms: new Set([plugins.openpgp.enums.publicKey.elgamal, plugins.openpgp.enums.publicKey.dsa]),
+  rejectCurves: new Set([plugins.openpgp.enums.curve.secp256k1]),
+};
+
+/**
+ * Builds a verifier from one armored OpenPGP public key: exactly one
+ * transferable v4 public key (the primary key with its user IDs, subkeys and
+ * self-signatures, all v4) in exactly one `PUBLIC KEY BLOCK`. A private key
+ * block, several blocks or keys, a v6 key, text around the block, an armor
+ * CRC-24 that does not match or any other garbage is `invalid-key`
+ * (`detail.field` `publicKeyArmored`). Only the structure is checked here;
+ * whether a key can sign depends on time and is checked at verification.
+ */
+export async function createOpenPgpVerifier(inputArg: { publicKeyArmored: string }): Promise<IOpenPgpVerifier> {
+  if (inputArg === null || typeof inputArg !== 'object') {
+    throw new LinuxRepoError('invalid-input', 'input must be an object', { field: 'input' });
+  }
+  assertString(inputArg.publicKeyArmored, 'publicKeyArmored');
+  const keyBytes = dearmor(inputArg.publicKeyArmored, 'PUBLIC KEY BLOCK', { code: 'invalid-key', field: 'publicKeyArmored' });
+  let keys: plugins.openpgp.Key[];
+  try {
+    keys = await plugins.openpgp.readKeys({ binaryKeys: keyBytes, config: VERIFY_CONFIG });
+  } catch (error) {
+    throw new LinuxRepoError('invalid-key', 'the OpenPGP public key cannot be read', { field: 'publicKeyArmored' }, {
+      cause: error,
+    });
+  }
+  if (keys.length !== 1) {
+    throw new LinuxRepoError('invalid-key', `expected exactly one OpenPGP public key, got ${keys.length}`, {
+      field: 'publicKeyArmored',
+    });
+  }
+  const key = keys[0];
+  if (key.isPrivate()) {
+    throw new LinuxRepoError('invalid-key', 'a private key is not accepted as the verification key', {
+      field: 'publicKeyArmored',
+    });
+  }
+  if (key.keyPacket.version !== 4 || key.subkeys.some((subkey) => subkey.keyPacket.version !== 4)) {
+    throw new LinuxRepoError('invalid-key', 'only OpenPGP v4 keys and subkeys are accepted', { field: 'publicKeyArmored' });
+  }
+  const publicKey: plugins.openpgp.PublicKey = key;
+  return {
+    fingerprint: publicKey.getFingerprint().toUpperCase(),
+    verifyDetachedSignature: async (input) => {
+      assertInputObject(input);
+      assertBytes(input.data, 'data');
+      assertBytes(input.signature, 'signature');
+      assertTimestamp(input.date, 'date');
+      return verifySignature({
+        key: publicKey,
+        packets: input.signature,
+        content: { binary: input.data },
+        signatureType: plugins.openpgp.enums.signature.binary,
+        date: input.date,
+        field: 'signature',
+        headerHashAlgorithms: [],
+      });
+    },
+    verifyArmoredDetachedSignature: async (input) => {
+      assertInputObject(input);
+      assertBytes(input.data, 'data');
+      assertBytes(input.signatureArmored, 'signatureArmored');
+      assertTimestamp(input.date, 'date');
+      const failure: IFramingFailure = { code: 'malformed-signature', field: 'signatureArmored' };
+      return verifySignature({
+        key: publicKey,
+        packets: dearmor(decodeArmorBytes(input.signatureArmored, failure), 'SIGNATURE', failure),
+        content: { binary: input.data },
+        signatureType: plugins.openpgp.enums.signature.binary,
+        date: input.date,
+        field: 'signatureArmored',
+        headerHashAlgorithms: [],
+      });
+    },
+    verifyCleartextMessage: async (input) => {
+      assertInputObject(input);
+      assertBytes(input.message, 'message');
+      assertTimestamp(input.date, 'date');
+      const parts = splitCleartextSignedMessage(input.message, { code: 'malformed-signature', field: 'message' });
+      const verification = await verifySignature({
+        key: publicKey,
+        packets: parts.signature,
+        // a text signature hashes the text with CRLF line endings; the split refused trailing whitespace,
+        // so this equals the cleartext digest of RFC 9580 section 7.1
+        content: { text: parts.signedText },
+        signatureType: plugins.openpgp.enums.signature.text,
+        date: input.date,
+        field: 'message',
+        headerHashAlgorithms: parts.headerHashAlgorithms,
+      });
+      return { ...verification, signedText: parts.signedText };
+    },
+  };
+}
+
+function hexByte(valueArg: number | null): string {
+  return valueArg === null ? 'none' : `0x${valueArg.toString(16).padStart(2, '0')}`;
+}
+
+function assertInputObject(inputArg: unknown): void {
+  if (inputArg === null || typeof inputArg !== 'object') {
+    throw new LinuxRepoError('invalid-input', 'input must be an object', { field: 'input' });
+  }
+}
+
+/**
+ * The verification steps, each with its own error code: structure
+ * (`malformed-signature`), issuer (`wrong-key`), the signature's own time
+ * rules (`bad-signature`), the issuing key's ability to sign at creation and
+ * at `date` (`unusable-key`), then the cryptographic check (`bad-signature`).
+ */
+async function verifySignature(inputArg: {
+  key: plugins.openpgp.PublicKey;
+  packets: Uint8Array;
+  /** The signed document: bytes for a binary signature, text for a text signature. */
+  content: { binary: Uint8Array } | { text: string };
+  signatureType: plugins.openpgp.enums.signature;
+  date: Date;
+  field: string;
+  headerHashAlgorithms: number[];
+}): Promise<IOpenPgpSignatureVerification> {
+  const { key, date, field } = inputArg;
+  const malformed = (messageArg: string, causeArg?: unknown) =>
+    new LinuxRepoError('malformed-signature', messageArg, { field }, causeArg === undefined ? undefined : { cause: causeArg });
+
+  // 1. structure, before any cryptography
+  const tags = readPacketTags(inputArg.packets, { code: 'malformed-signature', field });
+  if (tags.length !== 1 || tags[0] !== plugins.openpgp.enums.packet.signature) {
+    throw malformed(`expected exactly one signature packet, got packet tags [${tags.join(', ')}]`);
+  }
+  let signature: plugins.openpgp.Signature;
+  try {
+    signature = await plugins.openpgp.readSignature({ binarySignature: inputArg.packets, config: VERIFY_CONFIG });
+  } catch (error) {
+    throw malformed('the signature packet cannot be read', error);
+  }
+  const packet = signature.packets[0];
+  if (signature.packets.length !== 1 || !(packet instanceof plugins.openpgp.SignaturePacket)) {
+    throw malformed('expected exactly one signature packet');
+  }
+  if (packet.version !== 4) {
+    throw malformed(`only v4 signatures are accepted, got v${packet.version}`);
+  }
+  if (packet.signatureType !== inputArg.signatureType) {
+    throw malformed(`expected signature type ${hexByte(inputArg.signatureType)}, got ${hexByte(packet.signatureType)}`);
+  }
+  const hashId = packet.hashAlgorithm;
+  const hashAlgorithm = hashId === null ? undefined : HASH_ALGORITHMS.get(hashId);
+  if (hashId === null || hashAlgorithm === undefined) {
+    throw malformed(`hash algorithm ${hashId} is not SHA-256, SHA-384 or SHA-512`);
+  }
+  if (inputArg.headerHashAlgorithms.length > 0 && !inputArg.headerHashAlgorithms.includes(hashId)) {
+    throw malformed('the Hash: header does not name the signature hash algorithm');
+  }
+  if (packet.created === null) {
+    throw malformed('the signature has no creation time');
+  }
+  const issuerKeyId = packet.issuerKeyID.toHex();
+  if (!/^[0-9a-f]{16}$/.test(issuerKeyId) || /^0+$/.test(issuerKeyId)) {
+    throw malformed('the signature names no issuer, or the wildcard issuer');
+  }
+  if (packet.unknownSubpackets.some((subpacket) => subpacket.critical)) {
+    throw malformed('the signature has an unknown critical subpacket');
+  }
+  if (packet.unhashedSubpackets.some((subpacket) => subpacket.critical && !UNHASHED_SUBPACKETS_READ.has(subpacket.type))) {
+    throw malformed('the signature has a critical unhashed subpacket the verifier does not read');
+  }
+  if (packet.rawNotations.some((notation) => notation.critical)) {
+    throw malformed('the signature has a critical notation');
+  }
+
+  // 2. issuer: the primary key or one of its subkeys, by key ID and, when present, by fingerprint
+  const issuerFingerprint = packet.issuerFingerprint === null ? null : Buffer.from(packet.issuerFingerprint).toString('hex');
+  const issuers = [key, ...key.subkeys].filter(
+    (candidate) =>
+      candidate.getKeyID().equals(packet.issuerKeyID) && (issuerFingerprint === null || candidate.getFingerprint() === issuerFingerprint),
+  );
+  if (issuers.length === 0) {
+    throw new LinuxRepoError('wrong-key', 'the signature was not issued by this key or one of its subkeys', {
+      field,
+      value: (issuerFingerprint ?? issuerKeyId).toUpperCase(),
+    });
+  }
+
+  // 3. the signature's own time rules
+  if (packet.isExpired(date)) {
+    const reason = packet.created.getTime() > date.getTime() ? 'was created after the verification date' : 'has expired at the verification date';
+    throw new LinuxRepoError('bad-signature', `the signature ${reason}`, { field });
+  }
+
+  // 4. the issuing key or subkey must be able to sign at the creation time and at `date`
+  const signingKeyAt = async (whenArg: Date): Promise<plugins.openpgp.PublicKey | plugins.openpgp.Subkey> => {
+    let signingKey: plugins.openpgp.PublicKey | plugins.openpgp.Subkey;
+    try {
+      signingKey = await key.getSigningKey(packet.issuerKeyID, whenArg, undefined, VERIFY_CONFIG);
+    } catch (error) {
+      throw new LinuxRepoError(
+        'unusable-key',
+        `key ${issuerKeyId.toUpperCase()} cannot sign at ${whenArg.toISOString()}`,
+        { field: 'publicKeyArmored', value: issuers[0].getFingerprint().toUpperCase() },
+        { cause: error },
+      );
+    }
+    if (!issuers.includes(signingKey)) {
+      throw new LinuxRepoError('unusable-key', `key ${issuerKeyId.toUpperCase()} cannot sign at ${whenArg.toISOString()}`, {
+        field: 'publicKeyArmored',
+        value: issuers[0].getFingerprint().toUpperCase(),
+      });
+    }
+    return signingKey;
+  };
+  const atCreation = await signingKeyAt(packet.created);
+  const atDate = await signingKeyAt(date);
+  if (atCreation !== atDate) {
+    throw new LinuxRepoError('unusable-key', `key ${issuerKeyId.toUpperCase()} is not the same signing key at creation and at the verification date`, {
+      field: 'publicKeyArmored',
+      value: issuers[0].getFingerprint().toUpperCase(),
+    });
+  }
+
+  // 5. cryptography
+  try {
+    const content = inputArg.content;
+    const { signatures } =
+      'text' in content
+        ? await plugins.openpgp.verify({
+            message: await plugins.openpgp.createMessage({ text: content.text }),
+            signature,
+            verificationKeys: key,
+            date,
+            config: VERIFY_CONFIG,
+          })
+        : await plugins.openpgp.verify({
+            message: await plugins.openpgp.createMessage({ binary: content.binary }),
+            signature,
+            verificationKeys: key,
+            date,
+            format: 'binary',
+            config: VERIFY_CONFIG,
+          });
+    if (signatures.length !== 1) {
+      throw new Error(`openpgp.js evaluated ${signatures.length} signatures, expected 1`);
+    }
+    await signatures[0].verified;
+  } catch (error) {
+    throw new LinuxRepoError('bad-signature', 'the signature does not verify', { field }, { cause: error });
+  }
+  return {
+    signingKeyFingerprint: atDate.getFingerprint().toUpperCase(),
+    created: new Date(packet.created.getTime()),
+    hashAlgorithm,
+  };
+}