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

import {
    TemplateNonceLru,
    validateTemplate,
} from "@suaveplan/drive-template";

const lru = new TemplateNonceLru();
validateTemplate(template, {
    clock: () => Date.now(),
    nonceLru: lru,
});

Usage: Advanced Example

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.

2.7 KiB Raw Permalink Blame History