@boxxy/content-hash 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the boxxy authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+<div align="center">
+  <h1>@boxxy/content-hash</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+  <p>
+    <a href="https://www.npmjs.com/package/@boxxy/content-hash"><img src="https://img.shields.io/npm/v/@boxxy/content-hash" alt="npm version"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
+
+  <p>
+    <a href="../../docs/design/boxxy/README.md">Documentation</a>
+  </p>
+</div>
+
+Canonical JSON and the SHA-256 content hashes boxxy records.
+
+boxxy stores a content hash beside each recipe, rules version and snapshot. A value hashes the same
+whatever the order of its object keys.
+
+## Install
+
+Install the package from [npm](https://www.npmjs.com/package/@boxxy/content-hash) with Bun:
+
+```bash
+bun add @boxxy/content-hash
+```
+
+The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Features
+
+- `formatCanonicalJson`, which writes a JSON value in the canonical form of
+  [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785).
+- `contentHash`, the SHA-256 hex of a value's canonical JSON, as a branded `ContentHash`.
+- `hashBytes`, the SHA-256 hex of a file's bytes.
+- `hashTree`, the content hash of a folder's files, whatever order the caller walks them in.
+
+## Documentation
+
+The [first build spec](../../docs/design/boxxy/slice-1.md#packages) lists the hashes boxxy records.

package/dist/content-hash-schema.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+export declare const contentHashSchema: z.core.$ZodBranded<z.ZodString, "ContentHash", "out">;
+export type ContentHash = z.output<typeof contentHashSchema>;

package/dist/content-hash.d.ts

@@ -0,0 +1,3 @@
+import type { ContentHash } from './content-hash-schema.ts';
+import type { JsonValue } from './json-value.ts';
+export declare function contentHash(value: JsonValue): ContentHash;

package/dist/format-canonical-json.d.ts

@@ -0,0 +1,2 @@
+import type { JsonValue } from './json-value.ts';
+export declare function formatCanonicalJson(value: JsonValue): string;

package/dist/hash-bytes.d.ts

@@ -0,0 +1,2 @@
+import type { ContentHash } from './content-hash-schema.ts';
+export declare function hashBytes(bytes: Uint8Array): ContentHash;

package/dist/hash-tree.d.ts

@@ -0,0 +1,7 @@
+import type { ContentHash } from './content-hash-schema.ts';
+export interface TreeFile {
+    readonly path: string;
+    readonly bytes: Uint8Array;
+    readonly executable: boolean;
+}
+export declare function hashTree(files: readonly TreeFile[]): ContentHash;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { contentHash } from './content-hash.ts';
+export { type ContentHash, contentHashSchema } from './content-hash-schema.ts';
+export { formatCanonicalJson } from './format-canonical-json.ts';
+export { hashBytes } from './hash-bytes.ts';
+export { hashTree, type TreeFile } from './hash-tree.ts';
+export type { JsonValue } from './json-value.ts';

package/dist/json-value.d.ts

@@ -0,0 +1,3 @@
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@boxxy/content-hash",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "Canonical JSON and the SHA-256 content hashes boxxy records",
+  "homepage": "https://github.com/zgeoff/boxxy/tree/main/libs/content-hash#readme",
+  "bugs": "https://github.com/zgeoff/boxxy/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zgeoff/boxxy.git",
+    "directory": "libs/content-hash"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsrs -p tsconfig.build.json",
+    "typecheck": "tsrs --noEmit"
+  },
+  "dependencies": {
+    "zod": "4.6.7"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
+  }
+}

package/src/content-hash-schema.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+
+export const contentHashSchema = z
+  .string()
+  .regex(/^[0-9a-f]{64}$/u)
+  .brand<'ContentHash'>();
+
+export type ContentHash = z.output<typeof contentHashSchema>;

package/src/content-hash.ts

@@ -0,0 +1,8 @@
+import type { ContentHash } from './content-hash-schema.ts';
+import { formatCanonicalJson } from './format-canonical-json.ts';
+import { hashBytes } from './hash-bytes.ts';
+import type { JsonValue } from './json-value.ts';
+
+export function contentHash(value: JsonValue): ContentHash {
+  return hashBytes(new TextEncoder().encode(formatCanonicalJson(value)));
+}

package/src/format-canonical-json.ts

@@ -0,0 +1,59 @@
+import type { JsonValue } from './json-value.ts';
+
+// ts-pattern's match() fails the type check on the recursive JsonValue type ("instantiations of
+// type 'InvertPatternInternal' appear infinitely circular"), so this branches with typeof
+export function formatCanonicalJson(value: JsonValue): string {
+  if (typeof value === 'number') {
+    return formatCanonicalNumber(value);
+  }
+
+  if (typeof value === 'string') {
+    return formatCanonicalString(value);
+  }
+
+  // RFC 8785 writes the literals as ECMAScript's JSON.stringify does
+  if (value === null || typeof value === 'boolean') {
+    return JSON.stringify(value);
+  }
+
+  if (isJsonList(value)) {
+    return formatCanonicalList(value);
+  }
+
+  const members = Object.entries(value)
+    .toSorted(([left], [right]) => (left < right ? -1 : 1))
+    .map(([key, member]) => `${formatCanonicalString(key)}:${formatCanonicalJson(member)}`);
+
+  return `{${members.join(',')}}`;
+}
+
+function formatCanonicalNumber(number: number): string {
+  if (!Number.isFinite(number)) {
+    throw new TypeError(`RFC 8785 has no form for the number ${number}`);
+  }
+
+  // RFC 8785 writes a number as ECMAScript's Number serialization, which JSON.stringify uses
+  return JSON.stringify(number);
+}
+
+function formatCanonicalString(text: string): string {
+  // JSON.stringify escapes a lone surrogate, but RFC 8785 rejects a string that holds one
+  if (!text.isWellFormed()) {
+    throw new TypeError('RFC 8785 has no form for a string with a lone UTF-16 surrogate');
+  }
+
+  return JSON.stringify(text);
+}
+
+function isJsonList(value: JsonValue): value is readonly JsonValue[] {
+  return Array.isArray(value);
+}
+
+function formatCanonicalList(list: readonly JsonValue[]): string {
+  // map() skips the holes of a sparse array, which would write `[,]` or hash like a shorter list
+  if (Object.keys(list).length !== list.length) {
+    throw new TypeError('RFC 8785 has no form for a sparse array');
+  }
+
+  return `[${list.map((item) => formatCanonicalJson(item)).join(',')}]`;
+}

package/src/hash-bytes.ts

@@ -0,0 +1,7 @@
+import { createHash } from 'node:crypto';
+import type { ContentHash } from './content-hash-schema.ts';
+import { contentHashSchema } from './content-hash-schema.ts';
+
+export function hashBytes(bytes: Uint8Array): ContentHash {
+  return contentHashSchema.parse(createHash('sha256').update(bytes).digest('hex'));
+}

package/src/hash-tree.ts

@@ -0,0 +1,27 @@
+import type { ContentHash } from './content-hash-schema.ts';
+import { contentHash } from './content-hash.ts';
+import { hashBytes } from './hash-bytes.ts';
+
+export interface TreeFile {
+  readonly path: string;
+  readonly bytes: Uint8Array;
+  readonly executable: boolean;
+}
+
+export function hashTree(files: readonly TreeFile[]): ContentHash {
+  const entries = files
+    .map((file) => ({
+      path: file.path,
+      sha256: hashBytes(file.bytes),
+      executable: file.executable,
+    }))
+    .toSorted((left, right) => compareUTF8(left.path, right.path));
+
+  return contentHash(entries);
+}
+
+function compareUTF8(left: string, right: string): number {
+  const encoder = new TextEncoder();
+
+  return Buffer.compare(encoder.encode(left), encoder.encode(right));
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { contentHash } from './content-hash.ts';
+export { type ContentHash, contentHashSchema } from './content-hash-schema.ts';
+export { formatCanonicalJson } from './format-canonical-json.ts';
+export { hashBytes } from './hash-bytes.ts';
+export { hashTree, type TreeFile } from './hash-tree.ts';
+export type { JsonValue } from './json-value.ts';

package/src/json-value.ts

@@ -0,0 +1,7 @@
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };