@gnufoo/canaad 0.3.0 → 0.4.0

package/README.md

@@ -1,104 +1,84 @@
-# canaad-wasm
+# @gnufoo/canaad
 
-WASM bindings for AAD (Additional Authenticated Data) canonicalization per RFC 8785.
-
-This crate provides WebAssembly bindings for the `canaad-core` library, enabling
-AAD canonicalization in browsers, Node.js, and other WASM runtimes like
-Cloudflare Workers.
-
-## Installation
+AAD canonicalization in your browser or Worker. Same spec, same bytes.
 
 ```bash
 npm install @gnufoo/canaad
 ```
 
-## Usage
-
-### Canonicalize JSON
+## canonicalize
 
 ```typescript
 import { canonicalize, canonicalizeString, validate, hash } from '@gnufoo/canaad';
 
-// Canonicalize JSON to bytes
-const json = '{"v":1,"tenant":"org_abc","resource":"secrets/db","purpose":"encryption"}';
-const bytes: Uint8Array = canonicalize(json);
-
-// Canonicalize JSON to string
-const canonical: string = canonicalizeString(json);
-// => '{"purpose":"encryption","resource":"secrets/db","tenant":"org_abc","v":1}'
-
-// Validate JSON
-const isValid: boolean = validate(json);
-
-// Get SHA-256 hash of canonical form
-const hashBytes: Uint8Array = hash(json);
+const bytes = canonicalize('{"v":1,"tenant":"org_abc","resource":"secrets/db","purpose":"encryption"}');
+const str = canonicalizeString('{"v":1,"tenant":"org_abc","resource":"secrets/db","purpose":"encryption"}');
+const ok = validate(json);
+const sha = hash(json);  // 32-byte SHA-256
 ```
 
-### Builder API
+## build
 
 ```typescript
 import { AadBuilder } from '@gnufoo/canaad';
 
-const builder = new AadBuilder()
+const aad = new AadBuilder()
     .tenant("org_abc")
     .resource("secrets/db")
     .purpose("encryption")
     .timestamp(1706400000)
     .extensionString("x_vault_cluster", "us-east-1")
-    .extensionInt("x_app_priority", 5);
+    .extensionInt("x_app_priority", 5)
+    .build();        // Uint8Array
+```
 
-// Build to bytes
-const bytes: Uint8Array = builder.build();
+Numbers only — no BigInt. `build()` and `buildString()` validate all inputs:
 
-// Build to string
-const canonical: string = builder.buildString();
-```
+- NaN, Infinity, negative, fractional → rejected
+- `-0.0` → allowed (equals 0 in IEEE 754)
+- integers > 2^53-1 → rejected (JS safe integer limit)
 
-### Constants
+## exports
 
-```typescript
-import { SPEC_VERSION, MAX_SAFE_INTEGER, MAX_SERIALIZED_BYTES } from '@gnufoo/canaad';
+This package follows the gnufoo tool package format with four entry points:
 
-console.log(SPEC_VERSION);           // 1
-console.log(MAX_SAFE_INTEGER);       // 9007199254740991 (2^53 - 1)
-console.log(MAX_SERIALIZED_BYTES);   // 16384 (16 KiB)
-```
+| Import | What you get |
+|--------|-------------|
+| `@gnufoo/canaad` | Direct WASM functions (after init) |
+| `@gnufoo/canaad/init` | `initWasm()` + `isInitialized()` |
+| `@gnufoo/canaad/meta` | Zod schemas + metadata (no WASM, SSG-safe) |
+| `@gnufoo/canaad/tool` | `toolDefinition` with `execute()` |
 
-## Error Handling
+The `/meta` import is safe for static site generation — no WASM loaded.
 
-All functions that can fail will throw JavaScript errors with descriptive messages:
+The `/tool` path validates inputs via Zod (`z.number().int().nonnegative()` for timestamps and extension integers). Direct WASM imports bypass Zod — the Rust layer validates as defense-in-depth.
 
-```typescript
-try {
-    canonicalize('{"v":1}');  // Missing required fields
-} catch (e) {
-    console.error(e.message);  // "missing required field: tenant"
-}
-```
+## cloudflare workers
 
-## Supported Environments
+```typescript
+import wasmModule from '@gnufoo/canaad/canaad_wasm_bg.wasm';
+import { toolDefinition } from '@gnufoo/canaad/tool';
 
-- **Browsers**: Modern browsers with WASM support
-- **Node.js**: v14+ with WASM support
-- **Cloudflare Workers**: Full support
-- **Deno**: With WASM import
+await toolDefinition.initWasm(wasmModule);
 
-## Building from Source
+const result = await toolDefinition.execute({
+    action: 'build',
+    tenant: 'org_abc',
+    resource: 'secrets/db',
+    purpose: 'encryption',
+});
+```
 
-```bash
-# Install wasm-pack
-cargo install wasm-pack
+## browser (vite)
 
-# Build for bundlers (webpack, vite, etc.)
-wasm-pack build --target bundler
+With `vite-plugin-wasm` and `vite-plugin-top-level-await`:
 
-# Build for Node.js
-wasm-pack build --target nodejs
+```typescript
+import { toolDefinition } from '@gnufoo/canaad/tool';
 
-# Build for web (no bundler)
-wasm-pack build --target web
+await toolDefinition.initWasm();
 ```
 
-## License
+## license
 
 MIT OR Apache-2.0

package/canaad_wasm.d.ts

@@ -2,92 +2,25 @@
 /* eslint-disable */
 
 /**
- * Builder for constructing AAD objects programmatically.
- *
- * Provides a fluent API for building AAD with method chaining.
- * All setter methods return a new builder to enable chaining.
- *
- * # Example (JavaScript)
- *
- * ```javascript
- * const builder = new AadBuilder()
- *     .tenant("org_abc")
- *     .resource("secrets/db")
- *     .purpose("encryption")
- *     .timestamp(1706400000)
- *     .extensionString("x_vault_cluster", "us-east-1");
- *
- * const bytes = builder.build();
- * const canonical = builder.buildString();
- * ```
+ * Fluent builder for AAD objects. Chain setters, call `build()` or `buildString()`.
  */
 export class AadBuilder {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Builds the AAD and returns the canonical bytes.
-     *
-     * # Returns
-     *
-     * A `Uint8Array` containing the UTF-8 encoded canonical JSON.
-     *
-     * # Errors
-     *
-     * Throws a JavaScript error if:
-     * - Required fields (tenant, resource, purpose) are missing
-     * - Any field value is invalid
-     * - Extension keys don't match the required pattern
-     * - The serialized output exceeds 16 KiB
+     * Builds AAD and returns canonical bytes.
      */
     build(): Uint8Array;
     /**
-     * Builds the AAD and returns the canonical string.
-     *
-     * # Returns
-     *
-     * The canonical (JCS) representation as a string.
-     *
-     * # Errors
-     *
-     * Throws a JavaScript error if:
-     * - Required fields (tenant, resource, purpose) are missing
-     * - Any field value is invalid
-     * - Extension keys don't match the required pattern
-     * - The serialized output exceeds 16 KiB
+     * Builds AAD and returns canonical UTF-8 string.
      */
     buildString(): string;
     /**
-     * Adds an integer extension field.
-     *
-     * Extension keys must match pattern `x_<app>_<field>` where:
-     * - `<app>` is one or more lowercase letters
-     * - `<field>` is one or more lowercase letters or underscores
-     *
-     * # Arguments
-     *
-     * * `key` - Extension key (e.g., `x_app_priority`)
-     * * `value` - Integer value (0 to 2^53-1)
-     *
-     * # Returns
-     *
-     * A new builder with the extension added.
+     * Adds an integer extension. Validated at `build()`.
      */
     extensionInt(key: string, value: number): AadBuilder;
     /**
-     * Adds a string extension field.
-     *
-     * Extension keys must match pattern `x_<app>_<field>` where:
-     * - `<app>` is one or more lowercase letters
-     * - `<field>` is one or more lowercase letters or underscores
-     *
-     * # Arguments
-     *
-     * * `key` - Extension key (e.g., `x_vault_cluster`)
-     * * `value` - String value (no NUL bytes)
-     *
-     * # Returns
-     *
-     * A new builder with the extension added.
+     * Adds a string extension. Key format: `x_<app>_<field>`.
      */
     extensionString(key: string, value: string): AadBuilder;
     /**
@@ -95,160 +28,55 @@ export class AadBuilder {
      */
     constructor();
     /**
-     * Sets the purpose or usage context.
-     *
-     * # Arguments
-     *
-     * * `value` - Purpose description (1+ bytes, no NUL bytes)
-     *
-     * # Returns
-     *
-     * A new builder with the purpose set.
+     * Sets the purpose. 1+ bytes, no NUL.
      */
     purpose(value: string): AadBuilder;
     /**
-     * Sets the resource path or identifier.
-     *
-     * # Arguments
-     *
-     * * `value` - Resource path (1-1024 bytes, no NUL bytes)
-     *
-     * # Returns
-     *
-     * A new builder with the resource set.
+     * Sets the resource. 1-1024 bytes, no NUL.
      */
     resource(value: string): AadBuilder;
     /**
-     * Sets the tenant identifier.
-     *
-     * # Arguments
-     *
-     * * `value` - Tenant identifier (1-256 bytes, no NUL bytes)
-     *
-     * # Returns
-     *
-     * A new builder with the tenant set.
+     * Sets the tenant. 1-256 bytes, no NUL.
      */
     tenant(value: string): AadBuilder;
     /**
-     * Sets the timestamp.
-     *
-     * # Arguments
-     *
-     * * `ts` - Unix timestamp (0 to 2^53-1)
-     *
-     * # Returns
-     *
-     * A new builder with the timestamp set.
+     * Sets the timestamp. Validated at `build()`.
      */
     timestamp(ts: number): AadBuilder;
 }
 
 /**
- * Returns the maximum safe integer value (2^53 - 1).
- *
- * This is the maximum integer value that can be exactly represented in
- * JavaScript's Number type.
+ * Maximum safe integer (2^53 - 1).
  */
 export function MAX_SAFE_INTEGER(): number;
 
 /**
- * Returns the maximum serialized AAD size in bytes (16 KiB).
+ * Maximum serialized AAD size in bytes (16 KiB).
  */
 export function MAX_SERIALIZED_BYTES(): number;
 
 /**
- * Returns the current AAD specification version.
- *
- * Currently always returns 1.
+ * Current AAD specification version (always 1).
  */
 export function SPEC_VERSION(): number;
 
 /**
- * Parses and canonicalizes a JSON string to bytes.
- *
- * This function:
- * 1. Parses the JSON with duplicate key detection
- * 2. Validates all fields according to the AAD specification
- * 3. Returns the canonical (JCS) representation as bytes
- *
- * # Arguments
- *
- * * `json` - A JSON string containing an AAD object
- *
- * # Returns
- *
- * A `Uint8Array` containing the UTF-8 encoded canonical JSON.
- *
- * # Errors
- *
- * Throws a JavaScript error if:
- * - The JSON is invalid or contains duplicate keys
- * - Any field violates AAD constraints
- * - The serialized output exceeds 16 KiB
+ * Parses and canonicalizes a JSON string to bytes (RFC 8785).
  */
 export function canonicalize(json: string): Uint8Array;
 
 /**
  * Parses and canonicalizes a JSON string to a UTF-8 string.
- *
- * This is equivalent to `canonicalize` but returns a string instead of bytes.
- *
- * # Arguments
- *
- * * `json` - A JSON string containing an AAD object
- *
- * # Returns
- *
- * The canonical (JCS) representation as a string.
- *
- * # Errors
- *
- * Throws a JavaScript error if:
- * - The JSON is invalid or contains duplicate keys
- * - Any field violates AAD constraints
- * - The serialized output exceeds 16 KiB
  */
 export function canonicalizeString(json: string): string;
 
 /**
- * Computes the SHA-256 hash of the canonical JSON form.
- *
- * This function:
- * 1. Parses and validates the JSON
- * 2. Canonicalizes according to RFC 8785
- * 3. Returns the SHA-256 hash of the canonical bytes
- *
- * # Arguments
- *
- * * `json` - A JSON string containing an AAD object
- *
- * # Returns
- *
- * A 32-byte `Uint8Array` containing the SHA-256 hash.
- *
- * # Errors
- *
- * Throws a JavaScript error if:
- * - The JSON is invalid or contains duplicate keys
- * - Any field violates AAD constraints
- * - The serialized output exceeds 16 KiB
+ * SHA-256 hash of the canonical JSON form.
  */
 export function hash(json: string): Uint8Array;
 
 /**
  * Validates a JSON string against the AAD specification.
- *
- * This function performs full validation without returning the context.
- * Use this for quick validation checks.
- *
- * # Arguments
- *
- * * `json` - A JSON string to validate
- *
- * # Returns
- *
- * `true` if the JSON is valid AAD, `false` otherwise.
  */
 export function validate(json: string): boolean;
 

package/canaad_wasm.js

@@ -1,24 +1,7 @@
 /* @ts-self-types="./canaad_wasm.d.ts" */
 
 /**
- * Builder for constructing AAD objects programmatically.
- *
- * Provides a fluent API for building AAD with method chaining.
- * All setter methods return a new builder to enable chaining.
- *
- * # Example (JavaScript)
- *
- * ```javascript
- * const builder = new AadBuilder()
- *     .tenant("org_abc")
- *     .resource("secrets/db")
- *     .purpose("encryption")
- *     .timestamp(1706400000)
- *     .extensionString("x_vault_cluster", "us-east-1");
- *
- * const bytes = builder.build();
- * const canonical = builder.buildString();
- * ```
+ * Fluent builder for AAD objects. Chain setters, call `build()` or `buildString()`.
  */
 export class AadBuilder {
     static __wrap(ptr) {
@@ -39,19 +22,7 @@ export class AadBuilder {
         wasm.__wbg_aadbuilder_free(ptr, 0);
     }
     /**
-     * Builds the AAD and returns the canonical bytes.
-     *
-     * # Returns
-     *
-     * A `Uint8Array` containing the UTF-8 encoded canonical JSON.
-     *
-     * # Errors
-     *
-     * Throws a JavaScript error if:
-     * - Required fields (tenant, resource, purpose) are missing
-     * - Any field value is invalid
-     * - Extension keys don't match the required pattern
-     * - The serialized output exceeds 16 KiB
+     * Builds AAD and returns canonical bytes.
      * @returns {Uint8Array}
      */
     build() {
@@ -64,19 +35,7 @@ export class AadBuilder {
         return v1;
     }
     /**
-     * Builds the AAD and returns the canonical string.
-     *
-     * # Returns
-     *
-     * The canonical (JCS) representation as a string.
-     *
-     * # Errors
-     *
-     * Throws a JavaScript error if:
-     * - Required fields (tenant, resource, purpose) are missing
-     * - Any field value is invalid
-     * - Extension keys don't match the required pattern
-     * - The serialized output exceeds 16 KiB
+     * Builds AAD and returns canonical UTF-8 string.
      * @returns {string}
      */
     buildString() {
@@ -98,20 +57,7 @@ export class AadBuilder {
         }
     }
     /**
-     * Adds an integer extension field.
-     *
-     * Extension keys must match pattern `x_<app>_<field>` where:
-     * - `<app>` is one or more lowercase letters
-     * - `<field>` is one or more lowercase letters or underscores
-     *
-     * # Arguments
-     *
-     * * `key` - Extension key (e.g., `x_app_priority`)
-     * * `value` - Integer value (0 to 2^53-1)
-     *
-     * # Returns
-     *
-     * A new builder with the extension added.
+     * Adds an integer extension. Validated at `build()`.
      * @param {string} key
      * @param {number} value
      * @returns {AadBuilder}
@@ -124,20 +70,7 @@ export class AadBuilder {
         return AadBuilder.__wrap(ret);
     }
     /**
-     * Adds a string extension field.
-     *
-     * Extension keys must match pattern `x_<app>_<field>` where:
-     * - `<app>` is one or more lowercase letters
-     * - `<field>` is one or more lowercase letters or underscores
-     *
-     * # Arguments
-     *
-     * * `key` - Extension key (e.g., `x_vault_cluster`)
-     * * `value` - String value (no NUL bytes)
-     *
-     * # Returns
-     *
-     * A new builder with the extension added.
+     * Adds a string extension. Key format: `x_<app>_<field>`.
      * @param {string} key
      * @param {string} value
      * @returns {AadBuilder}
@@ -161,15 +94,7 @@ export class AadBuilder {
         return this;
     }
     /**
-     * Sets the purpose or usage context.
-     *
-     * # Arguments
-     *
-     * * `value` - Purpose description (1+ bytes, no NUL bytes)
-     *
-     * # Returns
-     *
-     * A new builder with the purpose set.
+     * Sets the purpose. 1+ bytes, no NUL.
      * @param {string} value
      * @returns {AadBuilder}
      */
@@ -181,15 +106,7 @@ export class AadBuilder {
         return AadBuilder.__wrap(ret);
     }
     /**
-     * Sets the resource path or identifier.
-     *
-     * # Arguments
-     *
-     * * `value` - Resource path (1-1024 bytes, no NUL bytes)
-     *
-     * # Returns
-     *
-     * A new builder with the resource set.
+     * Sets the resource. 1-1024 bytes, no NUL.
      * @param {string} value
      * @returns {AadBuilder}
      */
@@ -201,15 +118,7 @@ export class AadBuilder {
         return AadBuilder.__wrap(ret);
     }
     /**
-     * Sets the tenant identifier.
-     *
-     * # Arguments
-     *
-     * * `value` - Tenant identifier (1-256 bytes, no NUL bytes)
-     *
-     * # Returns
-     *
-     * A new builder with the tenant set.
+     * Sets the tenant. 1-256 bytes, no NUL.
      * @param {string} value
      * @returns {AadBuilder}
      */
@@ -221,15 +130,7 @@ export class AadBuilder {
         return AadBuilder.__wrap(ret);
     }
     /**
-     * Sets the timestamp.
-     *
-     * # Arguments
-     *
-     * * `ts` - Unix timestamp (0 to 2^53-1)
-     *
-     * # Returns
-     *
-     * A new builder with the timestamp set.
+     * Sets the timestamp. Validated at `build()`.
      * @param {number} ts
      * @returns {AadBuilder}
      */
@@ -242,10 +143,7 @@ export class AadBuilder {
 if (Symbol.dispose) AadBuilder.prototype[Symbol.dispose] = AadBuilder.prototype.free;
 
 /**
- * Returns the maximum safe integer value (2^53 - 1).
- *
- * This is the maximum integer value that can be exactly represented in
- * JavaScript's Number type.
+ * Maximum safe integer (2^53 - 1).
  * @returns {number}
  */
 export function MAX_SAFE_INTEGER() {
@@ -254,7 +152,7 @@ export function MAX_SAFE_INTEGER() {
 }
 
 /**
- * Returns the maximum serialized AAD size in bytes (16 KiB).
+ * Maximum serialized AAD size in bytes (16 KiB).
  * @returns {number}
  */
 export function MAX_SERIALIZED_BYTES() {
@@ -263,9 +161,7 @@ export function MAX_SERIALIZED_BYTES() {
 }
 
 /**
- * Returns the current AAD specification version.
- *
- * Currently always returns 1.
+ * Current AAD specification version (always 1).
  * @returns {number}
  */
 export function SPEC_VERSION() {
@@ -274,27 +170,7 @@ export function SPEC_VERSION() {
 }
 
 /**
- * Parses and canonicalizes a JSON string to bytes.
- *
- * This function:
- * 1. Parses the JSON with duplicate key detection
- * 2. Validates all fields according to the AAD specification
- * 3. Returns the canonical (JCS) representation as bytes
- *
- * # Arguments
- *
- * * `json` - A JSON string containing an AAD object
- *
- * # Returns
- *
- * A `Uint8Array` containing the UTF-8 encoded canonical JSON.
- *
- * # Errors
- *
- * Throws a JavaScript error if:
- * - The JSON is invalid or contains duplicate keys
- * - Any field violates AAD constraints
- * - The serialized output exceeds 16 KiB
+ * Parses and canonicalizes a JSON string to bytes (RFC 8785).
  * @param {string} json
  * @returns {Uint8Array}
  */
@@ -312,23 +188,6 @@ export function canonicalize(json) {
 
 /**
  * Parses and canonicalizes a JSON string to a UTF-8 string.
- *
- * This is equivalent to `canonicalize` but returns a string instead of bytes.
- *
- * # Arguments
- *
- * * `json` - A JSON string containing an AAD object
- *
- * # Returns
- *
- * The canonical (JCS) representation as a string.
- *
- * # Errors
- *
- * Throws a JavaScript error if:
- * - The JSON is invalid or contains duplicate keys
- * - Any field violates AAD constraints
- * - The serialized output exceeds 16 KiB
  * @param {string} json
  * @returns {string}
  */
@@ -354,27 +213,7 @@ export function canonicalizeString(json) {
 }
 
 /**
- * Computes the SHA-256 hash of the canonical JSON form.
- *
- * This function:
- * 1. Parses and validates the JSON
- * 2. Canonicalizes according to RFC 8785
- * 3. Returns the SHA-256 hash of the canonical bytes
- *
- * # Arguments
- *
- * * `json` - A JSON string containing an AAD object
- *
- * # Returns
- *
- * A 32-byte `Uint8Array` containing the SHA-256 hash.
- *
- * # Errors
- *
- * Throws a JavaScript error if:
- * - The JSON is invalid or contains duplicate keys
- * - Any field violates AAD constraints
- * - The serialized output exceeds 16 KiB
+ * SHA-256 hash of the canonical JSON form.
  * @param {string} json
  * @returns {Uint8Array}
  */
@@ -392,17 +231,6 @@ export function hash(json) {
 
 /**
  * Validates a JSON string against the AAD specification.
- *
- * This function performs full validation without returning the context.
- * Use this for quick validation checks.
- *
- * # Arguments
- *
- * * `json` - A JSON string to validate
- *
- * # Returns
- *
- * `true` if the JSON is valid AAD, `false` otherwise.
  * @param {string} json
  * @returns {boolean}
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gnufoo/canaad",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "canaad_wasm.js",
   "types": "canaad_wasm.d.ts",