skills/plugins/document-navigator/docs/networking/drive/drive-template

@suaveplan/drive-template - Server-signed drive templates: pre-configured folder structure and per-file metadata with bytes hydrated lazily from peers and CDN. Per-file policy flags (autoDownload/meshAllowed/cdnAllowed/retention), CDN reversed-ID URL builder, key grant envelopes, replay-protected signature verification.

Summary

Server-signed drive templates for the dehydrated-drive workflow. A DriveTemplate describes a drive's full folder structure and per-file metadata; the actual bytes are fetched lazily from peers (via drive-mesh) or a CDN (via drive-transport-https) on first read or on hydrate-time pre-fetch. This package ships the wire types, error registry, and the CDN reversed-ID URL builder. The hydration runtime, signature verification, and key-grant validation will land in subsequent commits.

Documentation tree

• upload-token — Implements CdnUploadToken issuance and verification (DTP-19). Tokens authorise a single chunk write to the CDN and ca…
• url-builder — Deterministic URL builder for the reversed-ID CDN layout described in drive-template-v1 DTP-17. Given a `CdnFallbac…
• canonical — Implements canonicalSerialize, the deterministic byte-level encoding that gates every server signature on a `DriveTem…
• sign — Server-side signing helper that turns an unsigned DriveTemplate into a fully-formed envelope (DTP-04). Produces an Ed…
• verify — Server-signature verification for DriveTemplate (DTP-04). Validates that template.serverSignature is a correct Ed25…
• key — (no submodules)
  • grant-validator — (no submodules)
• schemas — (no submodules)
  • template.schema — (no submodules)
• depth — Folder-depth check for DriveTemplate.rootFolder (DTP-08). Counts from the root (depth 0) and rejects the first folder…
• file — Per-file consistency invariants for every FileTemplate (DTP-09). Files that fail any invariant are rejected with `DRI…
• order — Implements the 8-step validation pipeline that Drive.hydrateFrom(template) runs against every incoming `DriveTemplate…
• replay — Per-client LRU of (driveId, nonce) tuples used to reject replayed templates (DTP-06). The cache holds at most `LRU_CA…
• error-codes — Frozen registry of error codes plus the error class for the @suaveplan/drive-template package. Eleven codes cover the…

- [grant-validator](./src/key/grant-validator.md) — _(no submodules)_- [schemas](./src/schemas/template.schema.md) — _(no submodules)_- [template.schema](./src/schemas/template.schema.md) — _(no submodules)_- [depth](./src/validate/depth.md) — Folder-depth check for `DriveTemplate.rootFolder` (DTP-08). Counts from the root (depth 0) and rejects the first folder…

• file — Per-file consistency invariants for every FileTemplate (DTP-09). Files that fail any invariant are rejected with `DRI…
• order — Implements the 8-step validation pipeline that Drive.hydrateFrom(template) runs against every incoming `DriveTemplate…
• replay — Per-client LRU of (driveId, nonce) tuples used to reject replayed templates (DTP-06). The cache holds at most `LRU_CA…
• error-codes — Frozen registry of error codes plus the error class for the @suaveplan/drive-template package. Eleven codes cover the…
• grant-validator — (no submodules)- schemas — (no submodules)- template.schema — (no submodules)- depth — Folder-depth check for DriveTemplate.rootFolder (DTP-08). Counts from the root (depth 0) and rejects the first folder…
• file — Per-file consistency invariants for every FileTemplate (DTP-09). Files that fail any invariant are rejected with `DRI…
• order — Implements the 8-step validation pipeline that Drive.hydrateFrom(template) runs against every incoming `DriveTemplate…
• replay — Per-client LRU of (driveId, nonce) tuples used to reject replayed templates (DTP-06). The cache holds at most `LRU_CA…
• error-codes — Frozen registry of error codes plus the error class for the @suaveplan/drive-template package. Eleven codes cover the…
• grant-validator — (no submodules)- schemas — (no submodules)- template.schema — (no submodules)- depth — Folder-depth check for DriveTemplate.rootFolder (DTP-08). Counts from the root (depth 0) and rejects the first folder…
• file — Per-file consistency invariants for every FileTemplate (DTP-09). Files that fail any invariant are rejected with `DRI…
• order — Implements the 8-step validation pipeline that Drive.hydrateFrom(template) runs against every incoming `DriveTemplate…
• replay — Per-client LRU of (driveId, nonce) tuples used to reject replayed templates (DTP-06). The cache holds at most `LRU_CA…
• error-codes — Frozen registry of error codes plus the error class for the @suaveplan/drive-template package. Eleven codes cover the…
• grant-validator — (no submodules)- schemas — (no submodules) - template.schema — (no submodules)- depth — Folder-depth check for DriveTemplate.rootFolder (DTP-08). Counts from the root (depth 0) and rejects the first folder…
• file — Per-file consistency invariants for every FileTemplate (DTP-09). Files that fail any invariant are rejected with `DRI…
• order — Implements the 8-step validation pipeline that Drive.hydrateFrom(template) runs against every incoming `DriveTemplate…
• replay — Per-client LRU of (driveId, nonce) tuples used to reject replayed templates (DTP-06). The cache holds at most `LRU_CA…
• error-codes — Frozen registry of error codes plus the error class for the @suaveplan/drive-template package. Eleven codes cover the…

Install

bun add @suaveplan/drive-template

Quick start

import {
    buildCdnChunkUrl,
    DEFAULT_CDN_LEVELS,
    DEFAULT_CDN_PADDING,
    DTP_CODES,
    DriveTemplateError,
    type DriveTemplate,
} from "@suaveplan/drive-template";

// Build a CDN chunk URL using the reversed-ID layout.
const url = buildCdnChunkUrl(
    {
        baseUrl: "https://chunks.example.com",
        pathScheme: "reverse-id",
        levels: DEFAULT_CDN_LEVELS,
        padding: DEFAULT_CDN_PADDING,
    },
    "abcdef1234567890",
    47,
);
// → "https://chunks.example.com/0/9/8/abcdef1234567890_000000047.chunk"

// Errors carry stable codes from DTP_CODES.
try {
    buildCdnChunkUrl({ baseUrl: "x", pathScheme: "reverse-id", levels: 3, padding: 9 }, "", 0);
} catch (err) {
    if (err instanceof DriveTemplateError && err.code === DTP_CODES.TEMPLATE_MALFORMED) {
        console.error("invalid input");
    }
}

Modules

• src/error-codes.md — DTP_CODES registry (eleven codes covering the eight-step validation pipeline plus three operational paths) and the DriveTemplateError class.
• src/cdn/url-builder.md — buildCdnChunkUrl plus DEFAULT_CDN_LEVELS and DEFAULT_CDN_PADDING constants.
• src/types/template.types.ts — DriveTemplate, FolderTemplate, FileTemplate, PerFilePolicy, RetentionPolicy, FileEncryption, KeyDistribution, CdnFallbackConfig, CdnUploadToken, KeyGrantPayload.

Subpath exports

• @suaveplan/drive-template — full barrel.
• @suaveplan/drive-template/types — wire types only.
• @suaveplan/drive-template/cdn — CDN URL builder.
• @suaveplan/drive-template/errors — DTP_CODES, DriveTemplateError.

Spec reference

The wire format and validation pipeline are canonical in the specification (DTP-01..DTP-26). The architectural reference is docs/drive/dehydrated-drives.md.

Status

Skeleton — types, error registry, and CDN URL builder shipped. Canonical serialization, signature verification, replay LRU, hydration orchestrator, and KeyGrantEnvelope validator land in subsequent commits.