# @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.

<!-- begin:auto-docs -->
## Documentation tree

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

## Install

```bash
bun add @suaveplan/drive-template
```

## Quick start

```ts
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`](./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`](./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`](../../../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.