first commit

docs/networking/drive/drive-template/src/validate/order.md

@@ -0,0 +1,74 @@
+# order
+
+## Purpose
+
+Implements the 8-step validation pipeline that `Drive.hydrateFrom(template)` runs against every incoming `DriveTemplate` (DTP-05). Failure at any step aborts before the next; the error code is pinned to the spec so monitoring dashboards can attach SLOs per stage.
+
+## Features
+
+- `validateTemplate(template, ctx)` — runs the full 8-step pipeline.
+- Step order is fixed: schema-version, expiry, issuance window, replay LRU, trusted issuer, server signature, folder depth, per-file invariants.
+- Replay LRU commit happens AFTER the signature check so a tampered template doesn't pollute the cache.
+- `ValidationContext` carries the injectable `Clock` and the per-client `TemplateNonceLru` so tests can step time deterministically.
+
+## Usage: Basic Example
+
+```ts
+import {
+    TemplateNonceLru,
+    validateTemplate,
+} from "@suaveplan/drive-template";
+
+const lru = new TemplateNonceLru();
+validateTemplate(template, {
+    clock: () => Date.now(),
+    nonceLru: lru,
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    DTP_CODES,
+    DriveTemplateError,
+    TemplateNonceLru,
+    validateTemplate,
+} from "@suaveplan/drive-template";
+
+const lru = new TemplateNonceLru();
+
+async function hydrateFrom(template) {
+    try {
+        validateTemplate(template, {
+            clock: () => Date.now(),
+            nonceLru: lru,
+        });
+    } catch (err) {
+        if (err instanceof DriveTemplateError) {
+            switch (err.code) {
+                case DTP_CODES.TEMPLATE_EXPIRED:
+                case DTP_CODES.TEMPLATE_STALE:
+                    return refreshTemplate();
+                case DTP_CODES.TEMPLATE_SIG_INVALID:
+                case DTP_CODES.TEMPLATE_UNTRUSTED_ISSUER:
+                    return alertOps(err);
+                default:
+                    throw err;
+            }
+        }
+        throw err;
+    }
+    return realisTree(template);
+}
+```
+
+## API Reference
+
+- `validateTemplate(template: DriveTemplate, ctx: ValidationContext): void`.
+- `interface ValidationContext` — `{ clock: Clock; nonceLru: TemplateNonceLru }`.
+- `ISSUANCE_WINDOW_MS: number` — fixed 24-hour issuance window pinned by DTP-07.
+
+## Implementation Notes
+
+The `trustedKeyAuthorities` allowlist is treated as advisory when empty — an empty array means "no allowlist configured" rather than "deny all". This matches the spec's `globalPolicy.trustedKeyAuthorities` being `optional`, but it surfaces as a hard precondition in the validator so the failure mode is well-defined. The replay-LRU `remember` call is the last side effect in the pipeline so an exception thrown in any prior step rolls back cleanly. Step ordering is structurally important: cheap synchronous checks come first so a malformed template never reaches the cryptographic verification path.