verify

Purpose

Server-signature verification for DriveTemplate (DTP-04). Validates that template.serverSignature is a correct Ed25519 signature over canonicalSerialize(template - sig) under the issuer's public key (interpreted as a hex string and decoded to a 32-byte buffer). Tampering with any field — including nonce, issuedAt, or any nested folder/file — causes verification to fail.

Features

verifyTemplateSignature(template) — throws on mismatch or invalid input.
decodeIssuerKey(hex) — exposed helper that wraps @suaveplan/crypto-utils.fromHex so consumers see DRIVE.TEMPLATE_SIG_INVALID instead of a raw decode error.
Trusts @noble/curves to return false on malformed signatures (no separate try/catch).

Usage: Basic Example

import { verifyTemplateSignature } from "@suaveplan/drive-template";

verifyTemplateSignature(template);
// throws DriveTemplateError(DRIVE.TEMPLATE_SIG_INVALID) on any tampering

Usage: Advanced Example

import {
    DTP_CODES,
    DriveTemplateError,
    verifyTemplateSignature,
} from "@suaveplan/drive-template";

function ingestPeerTemplate(tpl: import("@suaveplan/drive-template").DriveTemplate) {
    try {
        verifyTemplateSignature(tpl);
    } catch (err) {
        if (err instanceof DriveTemplateError && err.code === DTP_CODES.TEMPLATE_SIG_INVALID) {
            return reportTamperedTemplate(tpl.driveId);
        }
        throw err;
    }
    persist(tpl);
}

API Reference

verifyTemplateSignature(template: DriveTemplate): true — returns true on success; throws DriveTemplateError(DRIVE.TEMPLATE_SIG_INVALID) otherwise.
decodeIssuerKey(issuerHex: string): Uint8Array — throws DriveTemplateError(DRIVE.TEMPLATE_SIG_INVALID) on malformed hex.

Implementation Notes

The verifier rebuilds withoutSig by destructuring out the serverSignature field rather than zeroing it in place; this matches the encoder's behaviour precisely and avoids any subtle aliasing bugs across runtimes. The function returns true on success rather than void so the type system can express "this template has been verified" downstream — the codebase pairs this with the OpaqueKeyHandle brand pattern used in @suaveplan/vault for the same effect. There is no async path; templates verify in well under a millisecond on commodity hardware so the synchronous API stays branch-free.

2.4 KiB Raw Blame History