@gnufoo/canaad 0.2.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,159 +28,105 @@ 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.
+ */
+export function validate(json: string): boolean;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly MAX_SAFE_INTEGER: () => number;
+    readonly MAX_SERIALIZED_BYTES: () => number;
+    readonly SPEC_VERSION: () => number;
+    readonly __wbg_aadbuilder_free: (a: number, b: number) => void;
+    readonly aadbuilder_build: (a: number) => [number, number, number, number];
+    readonly aadbuilder_buildString: (a: number) => [number, number, number, number];
+    readonly aadbuilder_extensionInt: (a: number, b: number, c: number, d: number) => number;
+    readonly aadbuilder_extensionString: (a: number, b: number, c: number, d: number, e: number) => number;
+    readonly aadbuilder_new: () => number;
+    readonly aadbuilder_purpose: (a: number, b: number, c: number) => number;
+    readonly aadbuilder_resource: (a: number, b: number, c: number) => number;
+    readonly aadbuilder_tenant: (a: number, b: number, c: number) => number;
+    readonly aadbuilder_timestamp: (a: number, b: number) => number;
+    readonly canonicalize: (a: number, b: number) => [number, number, number, number];
+    readonly canonicalizeString: (a: number, b: number) => [number, number, number, number];
+    readonly hash: (a: number, b: number) => [number, number, number, number];
+    readonly validate: (a: number, b: number) => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
  *
- * This function performs full validation without returning the context.
- * Use this for quick validation checks.
- *
- * # Arguments
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
  *
- * * `json` - A JSON string to validate
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
  *
- * # Returns
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
  *
- * `true` if the JSON is valid AAD, `false` otherwise.
+ * @returns {Promise<InitOutput>}
  */
-export function validate(json: string): boolean;
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;

package/canaad_wasm.js

@@ -1,9 +1,454 @@
 /* @ts-self-types="./canaad_wasm.d.ts" */
 
-import * as wasm from "./canaad_wasm_bg.wasm";
-import { __wbg_set_wasm } from "./canaad_wasm_bg.js";
-__wbg_set_wasm(wasm);
-wasm.__wbindgen_start();
-export {
-    AadBuilder, MAX_SAFE_INTEGER, MAX_SERIALIZED_BYTES, SPEC_VERSION, canonicalize, canonicalizeString, hash, validate
-} from "./canaad_wasm_bg.js";
+/**
+ * Fluent builder for AAD objects. Chain setters, call `build()` or `buildString()`.
+ */
+export class AadBuilder {
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(AadBuilder.prototype);
+        obj.__wbg_ptr = ptr;
+        AadBuilderFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        AadBuilderFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_aadbuilder_free(ptr, 0);
+    }
+    /**
+     * Builds AAD and returns canonical bytes.
+     * @returns {Uint8Array}
+     */
+    build() {
+        const ret = wasm.aadbuilder_build(this.__wbg_ptr);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        var v1 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        return v1;
+    }
+    /**
+     * Builds AAD and returns canonical UTF-8 string.
+     * @returns {string}
+     */
+    buildString() {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const ret = wasm.aadbuilder_buildString(this.__wbg_ptr);
+            var ptr1 = ret[0];
+            var len1 = ret[1];
+            if (ret[3]) {
+                ptr1 = 0; len1 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
+    /**
+     * Adds an integer extension. Validated at `build()`.
+     * @param {string} key
+     * @param {number} value
+     * @returns {AadBuilder}
+     */
+    extensionInt(key, value) {
+        const ptr = this.__destroy_into_raw();
+        const ptr0 = passStringToWasm0(key, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.aadbuilder_extensionInt(ptr, ptr0, len0, value);
+        return AadBuilder.__wrap(ret);
+    }
+    /**
+     * Adds a string extension. Key format: `x_<app>_<field>`.
+     * @param {string} key
+     * @param {string} value
+     * @returns {AadBuilder}
+     */
+    extensionString(key, value) {
+        const ptr = this.__destroy_into_raw();
+        const ptr0 = passStringToWasm0(key, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(value, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.aadbuilder_extensionString(ptr, ptr0, len0, ptr1, len1);
+        return AadBuilder.__wrap(ret);
+    }
+    /**
+     * Creates a new AAD builder.
+     */
+    constructor() {
+        const ret = wasm.aadbuilder_new();
+        this.__wbg_ptr = ret >>> 0;
+        AadBuilderFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * Sets the purpose. 1+ bytes, no NUL.
+     * @param {string} value
+     * @returns {AadBuilder}
+     */
+    purpose(value) {
+        const ptr = this.__destroy_into_raw();
+        const ptr0 = passStringToWasm0(value, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.aadbuilder_purpose(ptr, ptr0, len0);
+        return AadBuilder.__wrap(ret);
+    }
+    /**
+     * Sets the resource. 1-1024 bytes, no NUL.
+     * @param {string} value
+     * @returns {AadBuilder}
+     */
+    resource(value) {
+        const ptr = this.__destroy_into_raw();
+        const ptr0 = passStringToWasm0(value, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.aadbuilder_resource(ptr, ptr0, len0);
+        return AadBuilder.__wrap(ret);
+    }
+    /**
+     * Sets the tenant. 1-256 bytes, no NUL.
+     * @param {string} value
+     * @returns {AadBuilder}
+     */
+    tenant(value) {
+        const ptr = this.__destroy_into_raw();
+        const ptr0 = passStringToWasm0(value, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.aadbuilder_tenant(ptr, ptr0, len0);
+        return AadBuilder.__wrap(ret);
+    }
+    /**
+     * Sets the timestamp. Validated at `build()`.
+     * @param {number} ts
+     * @returns {AadBuilder}
+     */
+    timestamp(ts) {
+        const ptr = this.__destroy_into_raw();
+        const ret = wasm.aadbuilder_timestamp(ptr, ts);
+        return AadBuilder.__wrap(ret);
+    }
+}
+if (Symbol.dispose) AadBuilder.prototype[Symbol.dispose] = AadBuilder.prototype.free;
+
+/**
+ * Maximum safe integer (2^53 - 1).
+ * @returns {number}
+ */
+export function MAX_SAFE_INTEGER() {
+    const ret = wasm.MAX_SAFE_INTEGER();
+    return ret;
+}
+
+/**
+ * Maximum serialized AAD size in bytes (16 KiB).
+ * @returns {number}
+ */
+export function MAX_SERIALIZED_BYTES() {
+    const ret = wasm.MAX_SERIALIZED_BYTES();
+    return ret >>> 0;
+}
+
+/**
+ * Current AAD specification version (always 1).
+ * @returns {number}
+ */
+export function SPEC_VERSION() {
+    const ret = wasm.SPEC_VERSION();
+    return ret >>> 0;
+}
+
+/**
+ * Parses and canonicalizes a JSON string to bytes (RFC 8785).
+ * @param {string} json
+ * @returns {Uint8Array}
+ */
+export function canonicalize(json) {
+    const ptr0 = passStringToWasm0(json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.canonicalize(ptr0, len0);
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
+    }
+    var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+    return v2;
+}
+
+/**
+ * Parses and canonicalizes a JSON string to a UTF-8 string.
+ * @param {string} json
+ * @returns {string}
+ */
+export function canonicalizeString(json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.canonicalizeString(ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
+/**
+ * SHA-256 hash of the canonical JSON form.
+ * @param {string} json
+ * @returns {Uint8Array}
+ */
+export function hash(json) {
+    const ptr0 = passStringToWasm0(json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.hash(ptr0, len0);
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
+    }
+    var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+    return v2;
+}
+
+/**
+ * Validates a JSON string against the AAD specification.
+ * @param {string} json
+ * @returns {boolean}
+ */
+export function validate(json) {
+    const ptr0 = passStringToWasm0(json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.validate(ptr0, len0);
+    return ret !== 0;
+}
+
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbg_Error_8c4e43fe74559d73: function(arg0, arg1) {
+            const ret = Error(getStringFromWasm0(arg0, arg1));
+            return ret;
+        },
+        __wbg___wbindgen_throw_be289d5034ed271b: function(arg0, arg1) {
+            throw new Error(getStringFromWasm0(arg0, arg1));
+        },
+        __wbindgen_init_externref_table: function() {
+            const table = wasm.__wbindgen_externrefs;
+            const offset = table.grow(4);
+            table.set(0, undefined);
+            table.set(offset + 0, undefined);
+            table.set(offset + 1, null);
+            table.set(offset + 2, true);
+            table.set(offset + 3, false);
+        },
+    };
+    return {
+        __proto__: null,
+        "./canaad_wasm_bg.js": import0,
+    };
+}
+
+const AadBuilderFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_aadbuilder_free(ptr >>> 0, 1));
+
+function getArrayU8FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
+}
+
+function getStringFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return decodeText(ptr, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeFromExternrefTable0(idx) {
+    const value = wasm.__wbindgen_externrefs.get(idx);
+    wasm.__externref_table_dealloc(idx);
+    return value;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+const MAX_SAFARI_DECODE_BYTES = 2146435072;
+let numBytesDecoded = 0;
+function decodeText(ptr, len) {
+    numBytesDecoded += len;
+    if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+        cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+        cachedTextDecoder.decode();
+        numBytesDecoded = len;
+    }
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+let wasmModule, wasm;
+function __wbg_finalize_init(instance, module) {
+    wasm = instance.exports;
+    wasmModule = module;
+    cachedUint8ArrayMemory0 = null;
+    wasm.__wbindgen_start();
+    return wasm;
+}
+
+async function __wbg_load(module, imports) {
+    if (typeof Response === 'function' && module instanceof Response) {
+        if (typeof WebAssembly.instantiateStreaming === 'function') {
+            try {
+                return await WebAssembly.instantiateStreaming(module, imports);
+            } catch (e) {
+                const validResponse = module.ok && expectedResponseType(module.type);
+
+                if (validResponse && module.headers.get('Content-Type') !== 'application/wasm') {
+                    console.warn("`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n", e);
+
+                } else { throw e; }
+            }
+        }
+
+        const bytes = await module.arrayBuffer();
+        return await WebAssembly.instantiate(bytes, imports);
+    } else {
+        const instance = await WebAssembly.instantiate(module, imports);
+
+        if (instance instanceof WebAssembly.Instance) {
+            return { instance, module };
+        } else {
+            return instance;
+        }
+    }
+
+    function expectedResponseType(type) {
+        switch (type) {
+            case 'basic': case 'cors': case 'default': return true;
+        }
+        return false;
+    }
+}
+
+function initSync(module) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module !== undefined) {
+        if (Object.getPrototypeOf(module) === Object.prototype) {
+            ({module} = module)
+        } else {
+            console.warn('using deprecated parameters for `initSync()`; pass a single object instead')
+        }
+    }
+
+    const imports = __wbg_get_imports();
+    if (!(module instanceof WebAssembly.Module)) {
+        module = new WebAssembly.Module(module);
+    }
+    const instance = new WebAssembly.Instance(module, imports);
+    return __wbg_finalize_init(instance, module);
+}
+
+async function __wbg_init(module_or_path) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module_or_path !== undefined) {
+        if (Object.getPrototypeOf(module_or_path) === Object.prototype) {
+            ({module_or_path} = module_or_path)
+        } else {
+            console.warn('using deprecated parameters for the initialization function; pass a single object instead')
+        }
+    }
+
+    if (module_or_path === undefined) {
+        module_or_path = new URL('canaad_wasm_bg.wasm', import.meta.url);
+    }
+    const imports = __wbg_get_imports();
+
+    if (typeof module_or_path === 'string' || (typeof Request === 'function' && module_or_path instanceof Request) || (typeof URL === 'function' && module_or_path instanceof URL)) {
+        module_or_path = fetch(module_or_path);
+    }
+
+    const { instance, module } = await __wbg_load(await module_or_path, imports);
+
+    return __wbg_finalize_init(instance, module);
+}
+
+export { initSync, __wbg_init as default };

package/init.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Initialize WASM. Call once before using any WASM functions.
+ *
+ * @param wasmModule - Pass the WebAssembly.Module in Workers, omit in browser
+ */
+export function initWasm(wasmModule?: WebAssembly.Module): Promise<void>;
+
+/**
+ * Check if WASM has been initialized.
+ */
+export function isInitialized(): boolean;

package/init.js

@@ -0,0 +1,24 @@
+import init from './canaad_wasm.js';
+
+let initialized = false;
+let initPromise = null;
+
+/**
+ * Initialize WASM. Call once before using any WASM functions.
+ *
+ * @param {WebAssembly.Module | undefined} wasmModule - Pass the Module in Workers, omit in browser
+ */
+export async function initWasm(wasmModule) {
+  if (initialized) return;
+  if (initPromise) return initPromise;
+
+  initPromise = init(wasmModule).then(() => {
+    initialized = true;
+  });
+
+  return initPromise;
+}
+
+export function isInitialized() {
+  return initialized;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gnufoo/canaad",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "canaad_wasm.js",
   "types": "canaad_wasm.d.ts",
@@ -16,6 +16,10 @@
     "./tool": {
       "types": "./tool.d.ts",
       "import": "./tool.js"
+    },
+    "./init": {
+      "types": "./init.d.ts",
+      "import": "./init.js"
     }
   },
   "dependencies": {
@@ -26,9 +30,7 @@
     "*.d.ts",
     "*.wasm"
   ],
-  "sideEffects": [
-    "./canaad_wasm.js"
-  ],
+  "sideEffects": false,
   "keywords": [
     "aead",
     "aad",

package/tool.d.ts

@@ -1,5 +1,8 @@
 import type { meta, CanaadInput, CanaadOutput } from './meta.js';
+import type { initWasm, isInitialized } from './init.js';
 
 export declare const toolDefinition: typeof meta & {
+  initWasm: typeof initWasm;
+  isInitialized: typeof isInitialized;
   execute(input: CanaadInput): Promise<CanaadOutput>;
 };

package/tool.js

@@ -1,13 +1,25 @@
 import { meta, inputSchema } from './meta.js';
+import { initWasm, isInitialized } from './init.js';
 import { canonicalize, canonicalizeString, hash, validate, AadBuilder } from './canaad_wasm.js';
 
 const bytesToHex = (bytes) => Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
-const bytesToBase64 = (bytes) => btoa(String.fromCharCode(...bytes));
+const bytesToBase64 = (bytes) => globalThis.btoa(String.fromCharCode(...bytes));
 
 export const toolDefinition = {
   ...meta,
 
+  /**
+   * Initialize WASM. Must be called before execute() in Workers.
+   * In browsers with vite-plugin-wasm, this is optional.
+   */
+  initWasm,
+  isInitialized,
+
   async execute(rawInput) {
+    if (!isInitialized()) {
+      throw new Error('WASM not initialized. Call initWasm() first.');
+    }
+
     const input = inputSchema.parse(rawInput);
 
     switch (input.action) {