# 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

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

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

## Usage: Advanced Example

```ts
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.