@quillmark/quiver 0.23.0 → 0.24.0

package/README.md

@@ -68,6 +68,8 @@ await build('./node_modules/@org/my-quiver', './public/quivers/my-quiver');
 
 `build` owns its output path outright: it assembles a generation in `<outDir>.stage`, moves it in whole, and deletes the one it replaced. A reader fetching mid-build sees the previous generation rather than a torn tree, and a build that throws leaves it serving. An `outDir` that is, or contains, the source quiver or the working directory is refused with a `transport_error` rather than deleted.
 
+Quills below `0.1.0` are drafts and are left out: they stay in the source layout, which `fromDir` reads whole, and reach the artifact only under `build(src, out, { drafts: true })`. A quill with no version above the floor is absent from the built catalog entirely.
+
 ```ts
 // browser runtime
 import { Engine, init } from '@quillmark/wasm';
@@ -82,7 +84,7 @@ const quill = await quiver.getQuill(doc.quillRef);
 const result = await engine.render(quill, doc, { format: 'pdf' });
 ```
 
-A CDN URL works the same way, for consumers who cannot run a Node build step of their own.
+A CDN URL works the same way, for consumers who cannot run a Node build step of their own — a collection you publish, on a host you pick, and pinned like the dependency [it is](#what-a-quiver-is-trusted-to-be).
 
 ## Server-side runtime (Node, packed artifact on disk)
 
@@ -124,6 +126,14 @@ The seed answers first and the URL serves what it does not carry. Seeding `lates
 
 `Quiver.fromBuiltUrl(url)` first fetches `<url>/latest.json`, a stable-named pointer to the current manifest. Everything behind that pointer is content-addressed and checked against the digest in its name; the pointer itself is not, so a cache layer can serve a stale one and silently pin the client to the old catalog. It is therefore the one request fetched `no-cache` (revalidate with the origin; a 304 still serves from disk), which closes the browser-cache layer. A stale CDN edge is answered by that host's cache headers.
 
+The check itself needs `crypto.subtle`, which a browser exposes only in a secure context. An `https` page, `http://localhost` and Node have one; a page served over plain `http` to anything else — a dev host on a LAN address, a staging box without a certificate — has none, and there every fetch passes through unchecked.
+
+## What a quiver is trusted to be
+
+**A quill is a template the backend executes, so loading a quiver runs its author's code.** Point one at a source you would take a dependency from — an npm package or a git tag, pinned like any other — because nothing here sandboxes a quill, and a collection assembled from anywhere else is a decision to make on purpose.
+
+Content addressing is an integrity check and not a provenance one: the digest in each name catches a corrupted object, a partial sync and a name reused across releases, and says nothing about who packed the bytes. Where the primitive behind it is absent the page is no secure context either, so the pointer, the manifest, the digests and the client itself all arrived over the same unauthenticated channel — which is the whole of why a built quiver is served over `https`.
+
 ## Error handling
 
 Every error is a `QuiverError` carrying a `code` from a closed set — `invalid_ref`, `quill_not_found`, `quiver_invalid`, `transport_error` — a human-readable `message`, and the offending `ref` where there is one.

package/dist/build.d.ts

@@ -5,6 +5,15 @@
  * a module reaching this one for types alone does not pull `node:fs` or
  * `node:crypto` into a browser bundle.
  */
+/** Options for {@link buildQuiver}. */
+export interface BuildOptions {
+    /**
+     * Pack versions below `MIN_PUBLISHED_VERSION` too. Off by default: the
+     * artifact is a deployment, and the draft space is not part of one. An
+     * author's own viewer turns it on, which is the only caller that should.
+     */
+    drafts?: boolean;
+}
 /**
  * Reads a Source Quiver, validates it, and writes the build output to outDir.
  *
@@ -12,8 +21,8 @@
  * names, which is what the loader checks on fetch:
  *   outDir/
  *     latest.json                     # the format, and a stable pointer to the manifest
- *     manifest.<sha256:12>.json       # hashed manifest
- *     <name>@<version>.<sha256:12>.zip  # one bundle per quill
+ *     manifest.<sha256:32>.json       # hashed manifest
+ *     <name>@<version>.<sha256:32>.zip  # one bundle per quill
  *     store/
  *       <sha256>                      # dehydrated font bytes (full hash, no ext)
  *
@@ -21,9 +30,13 @@
  * fetching mid-build reads the previous one rather than a torn tree, and a
  * build that throws leaves the previous one serving.
  *
+ * Versions below `MIN_PUBLISHED_VERSION` are drafts and are left out unless
+ * `options.drafts` asks for them; a quill with nothing above the floor is
+ * absent from the manifest entirely.
+ *
  * Throws:
  *   - `quiver_invalid` on source validation failures (propagated from scanner)
  *   - `transport_error` on I/O failures, and on an outDir the build would have
  *     to delete something it does not own to write (see `assertSafeOutDir`)
  */
-export declare function buildQuiver(sourceDir: string, outDir: string): Promise<void>;
+export declare function buildQuiver(sourceDir: string, outDir: string, options?: BuildOptions): Promise<void>;

package/dist/build.js

@@ -9,6 +9,7 @@ import { QuiverError } from './errors.js';
 import { packFiles } from './bundle.js';
 import { NAME_DIGEST_LENGTH } from './digest.js';
 import { MANIFEST_VERSION, POINTER_FORMAT } from './format.js';
+import { isDraft } from './semver.js';
 /** Font file extensions recognised by the builder (case-insensitive). */
 const FONT_EXT = /\.(ttf|otf|woff|woff2)$/i;
 /** The two trees a build owns beside its output: where a generation is assembled, and
@@ -55,8 +56,8 @@ function assertSafeOutDir(path, sourceDir, outDir) {
  * names, which is what the loader checks on fetch:
  *   outDir/
  *     latest.json                     # the format, and a stable pointer to the manifest
- *     manifest.<sha256:12>.json       # hashed manifest
- *     <name>@<version>.<sha256:12>.zip  # one bundle per quill
+ *     manifest.<sha256:32>.json       # hashed manifest
+ *     <name>@<version>.<sha256:32>.zip  # one bundle per quill
  *     store/
  *       <sha256>                      # dehydrated font bytes (full hash, no ext)
  *
@@ -64,12 +65,16 @@ function assertSafeOutDir(path, sourceDir, outDir) {
  * fetching mid-build reads the previous one rather than a torn tree, and a
  * build that throws leaves the previous one serving.
  *
+ * Versions below `MIN_PUBLISHED_VERSION` are drafts and are left out unless
+ * `options.drafts` asks for them; a quill with nothing above the floor is
+ * absent from the manifest entirely.
+ *
  * Throws:
  *   - `quiver_invalid` on source validation failures (propagated from scanner)
  *   - `transport_error` on I/O failures, and on an outDir the build would have
  *     to delete something it does not own to write (see `assertSafeOutDir`)
  */
-export async function buildQuiver(sourceDir, outDir) {
+export async function buildQuiver(sourceDir, outDir, options = {}) {
     // Dynamic imports keep this module safe to type-import from browser contexts.
     const path = await import('node:path');
     const { dirname, join, resolve } = path;
@@ -110,6 +115,8 @@ export async function buildQuiver(sourceDir, outDir) {
         const manifestQuills = [];
         for (const [quillName, versions] of catalog) {
             for (const version of versions) {
+                if (!options.drafts && isDraft(version))
+                    continue;
                 const quillDir = join(sourceDir, 'quills', quillName, version);
                 const tree = await readQuillTree(quillDir);
                 const fontEntries = [];
@@ -139,7 +146,16 @@ export async function buildQuiver(sourceDir, outDir) {
                 for (const [path, bytes] of contentEntries) {
                     contentRecord[path] = bytes;
                 }
-                const zipBytes = packFiles(contentRecord);
+                // The budget `bundle.ts` carries is spent here as well as at the read, so
+                // a quill no loader would take is refused by the build that packs it,
+                // where the author it names can still do something about it.
+                let zipBytes;
+                try {
+                    zipBytes = packFiles(contentRecord);
+                }
+                catch (err) {
+                    throw new QuiverError('quiver_invalid', `Quill "${quillName}@${version}": ${err.message}`, { quiverName: meta.name, version, cause: err });
+                }
                 const bundleHash = createHash('sha256')
                     .update(zipBytes)
                     .digest('hex')

package/dist/built-loader.js

@@ -7,6 +7,7 @@
  */
 import { QuiverError } from './errors.js';
 import { unpackFiles } from './bundle.js';
+import { isQuillName } from './ref.js';
 import { isCanonicalSemver, compareSemver } from './semver.js';
 import { NAME_DIGEST_LENGTH, sha256Hex } from './digest.js';
 import { MANIFEST_VERSION, POINTER_FORMAT } from './format.js';
@@ -37,7 +38,9 @@ async function fetchVerified(transport, path, expected) {
 // chars for bundles and manifests and the full 64 for store entries.
 const DIGEST = `[0-9a-f]{${NAME_DIGEST_LENGTH},}`;
 const MANIFEST_FILENAME_RE = new RegExp(`^manifest\\.(${DIGEST})\\.json$`);
-const BUNDLE_FILENAME_RE = new RegExp(`^[A-Za-z0-9_.-]+@[0-9]+\\.[0-9]+\\.[0-9]+\\.(${DIGEST})\\.zip$`);
+// The name span is the ref charset, not a filename charset: `build` spells a bundle
+// off the catalog row, and a row is a name a ref can spell.
+const BUNDLE_FILENAME_RE = new RegExp(`^[A-Za-z0-9_-]+@[0-9]+\\.[0-9]+\\.[0-9]+\\.(${DIGEST})\\.zip$`);
 const FONT_HASH_RE = /^[0-9a-f]{64}$/;
 /** The digest a content-addressed filename carries. Throws `quiver_invalid`. */
 function digestOfName(re, name, what) {
@@ -171,6 +174,9 @@ function parseManifest(raw) {
         if (typeof e['name'] !== 'string' || e['name'].length === 0) {
             throw new QuiverError('quiver_invalid', `manifest.quills[${i}].name must be a non-empty string`);
         }
+        if (!isQuillName(e['name'])) {
+            throw new QuiverError('quiver_invalid', `manifest.quills[${i}].name "${e['name']}" is not a name a ref can spell — only [A-Za-z0-9_-] are allowed`);
+        }
         if (typeof e['version'] !== 'string' || !isCanonicalSemver(e['version'])) {
             throw new QuiverError('quiver_invalid', `manifest.quills[${i}].version must be canonical semver (x.y.z), got "${String(e['version'])}"`);
         }

package/dist/bundle.d.ts

@@ -4,10 +4,12 @@
 /**
  * Pack a flat file map into a deterministic zip.
  * Keys are sorted before zipping so insertion order doesn't affect output.
+ * Throws `quiver_invalid` where the budget is spent.
  */
 export declare function packFiles(files: Record<string, Uint8Array>): Uint8Array;
 /**
  * Unpack a zip into a flat file map.
  * Returns { path: Uint8Array } for every file entry in the archive.
+ * Throws `quiver_invalid` where the budget is spent, before any entry inflates.
  */
 export declare function unpackFiles(data: Uint8Array): Record<string, Uint8Array>;

package/dist/bundle.js

@@ -2,6 +2,7 @@
  * Zip utilities — browser-safe (uses fflate only).
  */
 import { zipSync, unzipSync } from 'fflate';
+import { QuiverError } from './errors.js';
 /**
  * Fixed epoch mtime for deterministic zip output.
  *
@@ -13,24 +14,75 @@ import { zipSync, unzipSync } from 'fflate';
  * is always identical.
  */
 const ZIP_EPOCH = new Date(1980, 0, 1, 0, 0, 0, 0);
+/**
+ * What a bundle may hold. Deflate tops out near 1032:1, so a megabyte of zip is a
+ * gigabyte resident and the bundle is what a reader inflates to find that out.
+ *
+ * The ceiling is a constant rather than something a consumer raises, because a quiver
+ * is a dependency pinned like any other (README, "What a quiver is trusted to be") and
+ * what a budget bounds there is a build that packed something enormous. Both ends spend
+ * it, so an artifact no loader would read is refused where it is written.
+ *
+ * Fonts are not in here: `build` writes them to the store and the manifest names them,
+ * leaving a bundle its markdown, its Typst, and what those inline.
+ */
+const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
+const MAX_ENTRY_BYTES = 16 * 1024 * 1024;
+const MAX_BUNDLE_ENTRIES = 2048;
+/**
+ * The budget, spent one entry at a time. Throws `quiver_invalid`.
+ *
+ * Unpacking spends the sizes the central directory declares, and those are the sizes
+ * fflate allocates: each entry inflates into a buffer of exactly its declared size,
+ * which never grows. So a header cannot buy more than it declares — it can only
+ * understate itself and truncate its own entry, which is the corrupt bundle the digest
+ * already answers.
+ */
+function bundleBudget() {
+    let total = 0;
+    let count = 0;
+    return (name, size) => {
+        if (++count > MAX_BUNDLE_ENTRIES) {
+            throw new QuiverError('quiver_invalid', `Bundle holds over ${MAX_BUNDLE_ENTRIES} files, the most one may hold`);
+        }
+        if (size > MAX_ENTRY_BYTES) {
+            throw new QuiverError('quiver_invalid', `Bundled file "${name}" is ${size} bytes, over the ${MAX_ENTRY_BYTES} one file may be`);
+        }
+        total += size;
+        if (total > MAX_BUNDLE_BYTES) {
+            throw new QuiverError('quiver_invalid', `Bundle unpacks to over ${MAX_BUNDLE_BYTES} bytes, the most one may hold`);
+        }
+    };
+}
 /**
  * Pack a flat file map into a deterministic zip.
  * Keys are sorted before zipping so insertion order doesn't affect output.
+ * Throws `quiver_invalid` where the budget is spent.
  */
 export function packFiles(files) {
+    const spend = bundleBudget();
     const sorted = Object.keys(files).sort();
     const input = {};
     for (const key of sorted) {
-        input[key] = [files[key], { mtime: ZIP_EPOCH }];
+        const bytes = files[key];
+        spend(key, bytes.length);
+        input[key] = [bytes, { mtime: ZIP_EPOCH }];
     }
     return zipSync(input, { level: 6 });
 }
 /**
  * Unpack a zip into a flat file map.
  * Returns { path: Uint8Array } for every file entry in the archive.
+ * Throws `quiver_invalid` where the budget is spent, before any entry inflates.
  */
 export function unpackFiles(data) {
-    const raw = unzipSync(data);
+    const spend = bundleBudget();
+    const raw = unzipSync(data, {
+        filter: ({ name, originalSize }) => {
+            spend(name, originalSize);
+            return true;
+        }
+    });
     const result = {};
     for (const [key, value] of Object.entries(raw)) {
         result[key] = value;

package/dist/digest.d.ts

@@ -9,11 +9,15 @@
  * have one.
  */
 /**
- * Digest width in the names `build` writes, in hex chars: 48 bits of SHA-256.
- * Wide enough that a manifest name colliding with a prior release's, which
- * under immutable CDN caching serves the old catalog forever, is not a birthday
- * problem within any release count a quiver will see.
+ * Digest width in the names `build` writes, in hex chars: 128 bits of SHA-256.
+ *
+ * The width answers a chosen prefix, not a collision. Where the manifest is trusted
+ * and the bundles are not — the seeded deployment, where the two come from different
+ * places by design — this is the only thing between a served zip and the quill it
+ * claims to be, and a quill is a template the backend executes. Grinding padding until
+ * SHA-256 lands on a chosen prefix costs hours of one GPU at 48 bits and is out of
+ * reach at 128.
  */
-export declare const NAME_DIGEST_LENGTH = 12;
+export declare const NAME_DIGEST_LENGTH = 32;
 /** SHA-256 over `bytes` as lowercase hex, or undefined where no digest exists. */
 export declare function sha256Hex(bytes: Uint8Array): Promise<string | undefined>;

package/dist/digest.js

@@ -9,12 +9,16 @@
  * have one.
  */
 /**
- * Digest width in the names `build` writes, in hex chars: 48 bits of SHA-256.
- * Wide enough that a manifest name colliding with a prior release's, which
- * under immutable CDN caching serves the old catalog forever, is not a birthday
- * problem within any release count a quiver will see.
+ * Digest width in the names `build` writes, in hex chars: 128 bits of SHA-256.
+ *
+ * The width answers a chosen prefix, not a collision. Where the manifest is trusted
+ * and the bundles are not — the seeded deployment, where the two come from different
+ * places by design — this is the only thing between a served zip and the quill it
+ * claims to be, and a quill is a template the backend executes. Grinding padding until
+ * SHA-256 lands on a chosen prefix costs hours of one GPU at 48 bits and is out of
+ * reach at 128.
  */
-export const NAME_DIGEST_LENGTH = 12;
+export const NAME_DIGEST_LENGTH = 32;
 /** SHA-256 over `bytes` as lowercase hex, or undefined where no digest exists. */
 export async function sha256Hex(bytes) {
     const subtle = globalThis.crypto?.subtle;

package/dist/node.d.ts

@@ -9,6 +9,7 @@
  * makes no static or dynamic reference to it.
  */
 import { Quiver } from './quiver.js';
+import type { BuildOptions } from './build.js';
 /**
  * Reads a Source Quiver from a local directory containing `Quiver.yaml` and
  * `quills/<name>/<version>/Quill.yaml` entries.
@@ -42,10 +43,14 @@ export declare function fromBuiltDir(dirPath: string): Promise<Quiver>;
  * Reads the Source Quiver at sourceDir, validates it, and writes the runtime
  * build artifact to outDir, which the build clears first and therefore owns.
  *
+ * Quills below `0.1.0` are drafts: they stay in the source layout, which
+ * `fromDir` reads whole, and reach the artifact only under `{ drafts: true }`.
+ *
  * Throws `quiver_invalid` on source validation failures, `transport_error` on
  * I/O failures and on an outDir holding the source quiver or the cwd.
  */
-export declare function build(sourceDir: string, outDir: string): Promise<void>;
+export declare function build(sourceDir: string, outDir: string, options?: BuildOptions): Promise<void>;
 export { Quiver } from './quiver.js';
 export { QuiverError } from './errors.js';
 export type { QuiverErrorCode } from './errors.js';
+export type { BuildOptions } from './build.js';

package/dist/node.js

@@ -55,11 +55,14 @@ export async function fromBuiltDir(dirPath) {
  * Reads the Source Quiver at sourceDir, validates it, and writes the runtime
  * build artifact to outDir, which the build clears first and therefore owns.
  *
+ * Quills below `0.1.0` are drafts: they stay in the source layout, which
+ * `fromDir` reads whole, and reach the artifact only under `{ drafts: true }`.
+ *
  * Throws `quiver_invalid` on source validation failures, `transport_error` on
  * I/O failures and on an outDir holding the source quiver or the cwd.
  */
-export async function build(sourceDir, outDir) {
-    return buildQuiver(sourceDir, outDir);
+export async function build(sourceDir, outDir, options) {
+    return buildQuiver(sourceDir, outDir, options);
 }
 // The rest of the public surface, so a Node consumer needs one import.
 export { Quiver } from './quiver.js';

package/dist/quiver-yaml.js

@@ -5,7 +5,7 @@
  */
 import { parse as parseYaml } from 'yaml';
 import { QuiverError } from './errors.js';
-const NAME_RE = /^[A-Za-z0-9_-]+$/;
+import { isQuillName } from './ref.js';
 const KNOWN_FIELDS = new Set(['name', 'description']);
 /**
  * Parses and validates Quiver.yaml contents.
@@ -42,7 +42,7 @@ export function parseQuiverYaml(raw) {
         throw new QuiverError('quiver_invalid', `Quiver.yaml: "name" must be a string, got ${typeof doc['name']}`);
     }
     const name = doc['name'];
-    if (!NAME_RE.test(name)) {
+    if (!isQuillName(name)) {
         throw new QuiverError('quiver_invalid', `Quiver.yaml: "name" value "${name}" contains invalid characters — only [A-Za-z0-9_-] are allowed`);
     }
     if ('description' in doc && doc['description'] !== undefined) {

package/dist/ref.d.ts

@@ -6,6 +6,12 @@ export interface ParsedQuillRef {
     /** Selector part count: 1 = `x`, 2 = `x.y`, 3 = `x.y.z` (exact). */
     selectorDepth?: 1 | 2 | 3;
 }
+/**
+ * Whether `name` is a name a ref can spell. A quiver's own name and every catalog
+ * row are held to it: a row seated outside it is one `quillNames` lists and
+ * `getQuill` refuses.
+ */
+export declare function isQuillName(name: string): boolean;
 /**
  * Throws QuiverError('invalid_ref') on malformed input. The name is
  * `[A-Za-z0-9_-]+`; the selector is `x`, `x.y` or `x.y.z`, digits only, with no

package/dist/ref.js

@@ -1,6 +1,14 @@
 import { QuiverError } from './errors.js';
 const NAME_RE = /^[A-Za-z0-9_-]+$/;
 const SELECTOR_RE = /^\d+(\.\d+){0,2}$/;
+/**
+ * Whether `name` is a name a ref can spell. A quiver's own name and every catalog
+ * row are held to it: a row seated outside it is one `quillNames` lists and
+ * `getQuill` refuses.
+ */
+export function isQuillName(name) {
+    return NAME_RE.test(name);
+}
 /**
  * Throws QuiverError('invalid_ref') on malformed input. The name is
  * `[A-Za-z0-9_-]+`; the selector is `x`, `x.y` or `x.y.z`, digits only, with no

package/dist/semver.d.ts

@@ -1,3 +1,5 @@
+/** The lowest version a build packs. Below it is the draft space. */
+export declare const MIN_PUBLISHED_VERSION = "0.1.0";
 /** Returns true for exactly `x.y.z` with non-negative integer parts. */
 export declare function isCanonicalSemver(version: string): boolean;
 /**
@@ -8,5 +10,7 @@ export declare function isCanonicalSemver(version: string): boolean;
 export declare function matchesSemverSelector(version: string, selector: string): boolean;
 /** Compares two canonical semver strings. Returns <0, 0, or >0. */
 export declare function compareSemver(a: string, b: string): number;
+/** Returns true for a canonical version below `MIN_PUBLISHED_VERSION`. */
+export declare function isDraft(version: string): boolean;
 /** Returns the highest version string, or null if empty. */
 export declare function chooseHighestVersion(versions: string[]): string | null;

package/dist/semver.js

@@ -1,3 +1,5 @@
+/** The lowest version a build packs. Below it is the draft space. */
+export const MIN_PUBLISHED_VERSION = '0.1.0';
 /** Returns true for exactly `x.y.z` with non-negative integer parts. */
 export function isCanonicalSemver(version) {
     return /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(version);
@@ -33,6 +35,10 @@ export function compareSemver(a, b) {
     }
     return 0;
 }
+/** Returns true for a canonical version below `MIN_PUBLISHED_VERSION`. */
+export function isDraft(version) {
+    return compareSemver(version, MIN_PUBLISHED_VERSION) < 0;
+}
 /** Returns the highest version string, or null if empty. */
 export function chooseHighestVersion(versions) {
     if (versions.length === 0)

package/dist/source-loader.d.ts

@@ -11,8 +11,10 @@ import type { QuiverLoader } from './quiver.js';
  * to build a catalog of quill names → sorted versions (descending).
  *
  * Throws:
- *   - `quiver_invalid` if Quiver.yaml is missing/invalid, a version dir name is
- *     non-canonical, or a version dir is missing its Quill.yaml sentinel.
+ *   - `quiver_invalid` if Quiver.yaml is missing/invalid, a quill or version directory
+ *     is a symlink, a quill dir holding versions is named outside the ref charset, a
+ *     version dir name is non-canonical, or a version dir is missing its Quill.yaml
+ *     sentinel.
  *   - `transport_error` for I/O failures (permissions, etc.).
  *
  * Missing `quills/` directory is not an error — the quiver is valid but empty.
@@ -25,7 +27,7 @@ export declare function scanSourceQuiver(rootDir: string): Promise<{
  * Recursively reads all files under a quill version directory into a Map.
  *
  * Keys are relative POSIX paths (forward slashes, no leading slash).
- * Throws `transport_error` on I/O failure.
+ * Throws `quiver_invalid` on a symlink, `transport_error` on I/O failure.
  */
 export declare function readQuillTree(quillDir: string): Promise<Map<string, Uint8Array>>;
 /**

package/dist/source-loader.js

@@ -2,11 +2,24 @@
  * Internal filesystem scanner for the Source Quiver layout. Statically imports
  * `node:fs`, so it is reachable from the Node entry alone.
  */
-import { readdir, readFile, stat } from 'node:fs/promises';
+import { readdir, readFile, lstat, stat } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 import { QuiverError } from './errors.js';
 import { parseQuiverYaml } from './quiver-yaml.js';
+import { isQuillName } from './ref.js';
 import { isCanonicalSemver, compareSemver } from './semver.js';
+/**
+ * Refuse a symlink. Every rung that opens a tree or reads a file `lstat`s and asks,
+ * because a source quiver is content and a link is a reference out of it: followed,
+ * `readFile` reads whatever it points at into the quill, where the backend can typeset
+ * it and `build` packs it into the published artifact. A linked directory smuggles a
+ * tree where a linked file smuggles one, so the answer is the same at each.
+ */
+function refuseSymlink(st, path) {
+    if (st.isSymbolicLink()) {
+        throw new QuiverError('quiver_invalid', `"${path}" is a symlink; a quiver holds its own content, and nothing under it may point outside`);
+    }
+}
 /**
  * Scans a Source Quiver root directory.
  *
@@ -14,8 +27,10 @@ import { isCanonicalSemver, compareSemver } from './semver.js';
  * to build a catalog of quill names → sorted versions (descending).
  *
  * Throws:
- *   - `quiver_invalid` if Quiver.yaml is missing/invalid, a version dir name is
- *     non-canonical, or a version dir is missing its Quill.yaml sentinel.
+ *   - `quiver_invalid` if Quiver.yaml is missing/invalid, a quill or version directory
+ *     is a symlink, a quill dir holding versions is named outside the ref charset, a
+ *     version dir name is non-canonical, or a version dir is missing its Quill.yaml
+ *     sentinel.
  *   - `transport_error` for I/O failures (permissions, etc.).
  *
  * Missing `quills/` directory is not an error — the quiver is valid but empty.
@@ -56,11 +71,12 @@ export async function scanSourceQuiver(rootDir) {
         const quillNameDir = join(quillsDir, quillName);
         let st;
         try {
-            st = await stat(quillNameDir);
+            st = await lstat(quillNameDir);
         }
         catch (err) {
             throw new QuiverError('transport_error', `Failed to stat "${quillNameDir}": ${err.message}`, { cause: err });
         }
+        refuseSymlink(st, quillNameDir);
         if (!st.isDirectory())
             continue;
         let versionDirs;
@@ -75,11 +91,12 @@ export async function scanSourceQuiver(rootDir) {
             const versionPath = join(quillNameDir, versionDir);
             let vst;
             try {
-                vst = await stat(versionPath);
+                vst = await lstat(versionPath);
             }
             catch (err) {
                 throw new QuiverError('transport_error', `Failed to stat "${versionPath}": ${err.message}`, { cause: err });
             }
+            refuseSymlink(vst, versionPath);
             if (!vst.isDirectory())
                 continue;
             if (!isCanonicalSemver(versionDir)) {
@@ -99,6 +116,11 @@ export async function scanSourceQuiver(rootDir) {
             versions.push(versionDir);
         }
         if (versions.length > 0) {
+            // Asked here rather than at the directory, so a stray one holding no quill
+            // stays ignored: what has to be addressable is a catalog row.
+            if (!isQuillName(quillName)) {
+                throw new QuiverError('quiver_invalid', `Quill directory "${quillName}" is not a name a ref can spell — only [A-Za-z0-9_-] are allowed`, { quiverName: meta.name });
+            }
             versions.sort((a, b) => compareSemver(b, a));
             catalog.set(quillName, versions);
         }
@@ -109,7 +131,7 @@ export async function scanSourceQuiver(rootDir) {
  * Recursively reads all files under a quill version directory into a Map.
  *
  * Keys are relative POSIX paths (forward slashes, no leading slash).
- * Throws `transport_error` on I/O failure.
+ * Throws `quiver_invalid` on a symlink, `transport_error` on I/O failure.
  */
 export async function readQuillTree(quillDir) {
     const tree = new Map();
@@ -128,11 +150,12 @@ async function walkDir(baseDir, currentDir, tree) {
         const fullPath = join(currentDir, entry);
         let st;
         try {
-            st = await stat(fullPath);
+            st = await lstat(fullPath);
         }
         catch (err) {
             throw new QuiverError('transport_error', `Failed to stat "${fullPath}": ${err.message}`, { cause: err });
         }
+        refuseSymlink(st, fullPath);
         if (st.isDirectory()) {
             await walkDir(baseDir, fullPath, tree);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quillmark/quiver",
-	"version": "0.23.0",
+	"version": "0.24.0",
 	"description": "A quiver of Quillmark quills: load one, pack one, hand out quills.",
 	"type": "module",
 	"license": "Apache-2.0",
@@ -42,7 +42,7 @@
 		"NOTICE"
 	],
 	"peerDependencies": {
-		"@quillmark/wasm": ">=0.105.0-0"
+		"@quillmark/wasm": ">=0.108.0-0"
 	},
 	"dependencies": {
 		"fflate": "^0.8.2",