first commit

docs/networking/drive/drive-template/src/codec/verify.md

@@ -0,0 +1,51 @@
+# 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.