107 lines
9.4 KiB
Markdown
107 lines
9.4 KiB
Markdown
# @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.
|
|
|