manifest.schema

(no submodules)

Purpose

Defines the Zod schemas that gate every manifest the plugin parses from untrusted bytes. Schema validation is the line between "raw bytes that may or may not be a manifest" and "a typed Manifest ready to flow through the rest of the plugin"; it runs before signature verification so structural errors surface as MANIFEST_INVALID without paying the cost of an Ed25519 verify.

Features

ManifestSchema — the top-level schema for a complete signed manifest, including a 64-byte signature, version literal 0x0001, 32-byte fileId, positive chunkSize / totalChunks, and an array of per-chunk entries.
ManifestEncryptionSchema — the embedded encryption envelope: algo is locked to "xchacha20poly1305", baseNonce is exactly 24 bytes, and fileKeyWrapped is left length-flexible to leave room for future KEMs.
ManifestChunkEntrySchema — per-chunk entries with non-negative chunkId / payloadLen and a 32-byte SHA-256 hash.
fileSize accepts both bigint and decimal-string inputs and normalises to bigint, which makes JSON-serialised manifests round-trip cleanly even though native JSON has no bigint type.

Usage: Basic Example

import { ManifestSchema } from "@suaveplan/drive-plugin-chunks";

const result = ManifestSchema.safeParse(decodedFromJson);
if (!result.success) throw new Error(result.error.message);
const manifest = result.data;

Usage: Advanced Example

import {
    ManifestChunkEntrySchema,
    ManifestEncryptionSchema,
    ManifestSchema,
} from "@suaveplan/drive-plugin-chunks";

function isLooselyValid(maybe: unknown): boolean {
    return ManifestSchema.safeParse(maybe).success;
}

const enc = ManifestEncryptionSchema.parse({
    algo: "xchacha20poly1305",
    fileKeyWrapped: new Uint8Array(32),
    baseNonce: new Uint8Array(24),
});
const entry = ManifestChunkEntrySchema.parse({
    chunkId: 0,
    hash: new Uint8Array(32),
    payloadLen: 50,
});

API Reference

ManifestSchema: ZodTypeAny — top-level boundary schema.
ManifestEncryptionSchema: ZodTypeAny — encryption sub-schema.
ManifestChunkEntrySchema: ZodTypeAny — chunk-entry sub-schema.
type ManifestInput = z.input<typeof ManifestSchema> — the pre-transform JSON shape.

Implementation Notes

The // schema: boundary-only annotation tells the conformance script that these schemas are deliberately part of the public surface even when this file is the only place inside src/ that calls .parse / .safeParse on them. Removing the annotation (or moving the schemas) would be an enterprise-grade signal change so consumers should not depend on internal validation paths.

2.7 KiB Raw Blame History