@janssenproject/cedarling_wasm 2.4.0 → 2.5.0

package/README.md

@@ -1,617 +1,511 @@
-# Cedarling WASM
+# Getting Started with Cedarling in a JavaScript App
 
-This module is designed to build cedarling for browser wasm.
+The `@janssenproject/cedarling_wasm` package brings
+[Cedarling](https://docs.jans.io/stable/cedarling/) authorization to JavaScript and
+TypeScript applications. Cedarling evaluates Cedar policies within your
+application's process, whether it runs in a browser, on a server, or at the edge.
+It determines whether a principal or token set may perform an action on a resource.
 
-## Building
+Use Cedarling to apply consistent access policies, inspect authorization decisions,
+retain decision logs, and make application context available to policy evaluation.
 
-For building we use [`wasm-pack`](https://developer.mozilla.org/en-US/docs/WebAssembly/Rust_to_Wasm) for install you can use command `cargo install wasm-pack`
+## Installation
 
-Build cedarling in release:
+### Using the Package Manager
 
-```bash
-wasm-pack build --release --target web
+```sh
+npm install @janssenproject/cedarling_wasm
 ```
 
-Build cedarling in dev mode
+Choose the package entry for your application. The package ships Cedarling's
+WebAssembly (`.wasm`) binary; the last column describes how that binary is loaded
+and initialized. Your application's policy archive is configured separately.
 
-```bash
-wasm-pack build --target web --dev
-```
+| Environment                                  | Package Entry                                       | Packaged WASM Loading               |
+| -------------------------------------------- | --------------------------------------------------- | ----------------------------------- |
+| Browser applications with supported bundlers | `@janssenproject/cedarling_wasm`                    | Automatic                           |
+| Node.js 22, 24, or 26, ESM or CommonJS       | `@janssenproject/cedarling_wasm`                    | Automatic                           |
+| Cloudflare Workers and Vercel Edge           | `@janssenproject/cedarling_wasm/edge`               | Bundled as a precompiled module     |
+| Other ESM bundlers                           | `@janssenproject/cedarling_wasm/manual` and `/wasm` | Application-configured WASM loading |
+
+Browser applications use an ESM-aware bundler. Follow
+[Other Integration Paths](#other-integration-paths) for edge deployment and
+application-controlled WASM loading.
+
+### Build from Source
+
+For local generation, package build, and qualification instructions, see the
+[maintainer guide](https://github.com/JanssenProject/jans/blob/main/jans-cedarling/bindings/cedarling_wasm/js/docs/maintainer.md).
 
-Result files will be in `pkg` folder.
+## Usage
 
-## Testing
+### Initialization
 
-For WASM testing we use `wasm-pack` and it allows to make test in `node`, `chrome`, `firefox`, `safari`. You just need specify appropriate flag.
+Create a Cedarling instance with `init()`. It ensures the package's WASM binary is
+loaded and initialized, then creates the instance using an object or `Map` of
+canonical Cedarling bootstrap properties.
 
-Example for firefox.
+For browser or Node.js ESM applications:
 
-```bash
-wasm-pack test --firefox
+```ts
+import { init } from "@janssenproject/cedarling_wasm";
+
+const config = {
+  CEDARLING_APPLICATION_NAME: "task-api",
+  CEDARLING_LOG_TYPE: "memory",
+  CEDARLING_LOG_TTL: 120,
+};
+let cedarling;
+try {
+  cedarling = await init({
+    ...config,
+    CEDARLING_POLICY_STORE_URI: "https://example.com/policy-store.cjar",
+  });
+} catch (error) {
+  console.error("Cedarling initialization failed", error);
+  throw error;
+}
 ```
 
-## Run browser example
+Replace the example URL with your application's policy archive. For Node.js
+CommonJS, use the following import and run the initialization inside an async
+function:
 
-To run example using `index.html` you need execute following steps:
+```js
+const { init } = require("@janssenproject/cedarling_wasm");
+```
 
-1. Build wasm cedarling.
-2. Run webserver using `python3 -m http.server` or any other.
-3. Visit example app [localhost](http://localhost:8000/), on this app you will get log in browser console.
-   - Also you can try use cedarling with web app using [cedarling_app](http://localhost:8000/cedarling_app.html), using custom bootstrap properties and request.
+The examples below reuse `cedarling`. Run each authorization walkthrough
+separately, with a policy store that matches its entities and attributes.
+Handle initialization failures in your application's startup error handler.
+See the [bootstrap-property reference](https://docs.jans.io/stable/cedarling/reference/cedarling-properties/)
+for configuration values, defaults, and token-validation settings.
 
-## WASM Usage
+### Policy Store Sources
 
-After building WASM bindings in folder `pkg` you can find where you can find `cedarling_wasm.js` and `cedarling_wasm.d.ts` where is defined interface for application.
+A Cedar archive (`.cjar`) packages the schema, policies, and trusted-issuer
+configuration. Prepare policies with the
+[Agama Lab Policy Designer](https://cloud.gluu.org/agama-lab/dashboard/policy-designer)
+and follow the [Cedar Archive format](https://docs.jans.io/nightly/cedarling/reference/cedarling-policy-store/#cedar-archive-cjar-format)
+for packaging.
 
-In `index.html` described simple usage of `cedarling wasm` API:
+#### Load a Cedar Archive from a URL
 
-```js
-import { BOOTSTRAP_CONFIG, REQUEST_UNSIGNED } from "/example_data.js"; // Import js objects: bootstrap config and request
-import initWasm, { init } from "/pkg/cedarling_wasm.js";
+Set `CEDARLING_POLICY_STORE_URI` as shown in [Initialization](#initialization).
+Cedarling downloads the archive while creating the instance. Use an absolute
+HTTP(S) URL. For browser downloads, use the application's origin or configure the
+archive server's CORS headers to allow the application origin.
+
+#### Load a Cedar Archive from Bytes
+
+Use `initFromArchiveBytes()` instead of `init()` when your application controls
+the download. This browser example reuses `config` from Initialization and
+fetches an archive through a same-origin application endpoint:
 
-async function main() {
-  await initWasm(); // Initialize the WebAssembly module
+```ts
+import { initFromArchiveBytes } from "@janssenproject/cedarling_wasm";
 
-  let instance = await init(BOOTSTRAP_CONFIG);
-  // authorize calls take the request as a JSON string: it crosses the
-  // JS/WASM boundary as one string copy parsed by serde_json
-  let result = await instance.authorize_unsigned(JSON.stringify(REQUEST_UNSIGNED));
-  console.log("result:", result);
+let policyArchiveBytes;
+let cedarling;
+try {
+  const response = await fetch("/api/policy-store");
+  if (!response.ok) throw new Error("Policy-store download failed");
+  policyArchiveBytes = new Uint8Array(await response.arrayBuffer());
+  cedarling = await initFromArchiveBytes(config, policyArchiveBytes);
+} catch (error) {
+  console.error("Policy-store download or initialization failed", error);
+  throw error;
 }
-main().catch(console.error);
 ```
 
-Before using any function from library you need initialize WASM runtime by calling `initWasm` function.
+The archive bytes supply the policy store; `config` supplies the other bootstrap
+properties. The package still loads and initializes its own WASM binary. In
+Node.js, use an absolute download URL. Keep upstream policy-store credentials on
+a trusted server; browser configuration is visible to its users.
 
-### Defined API
+### Authorization
 
-```ts
-/**
- * Create a new instance of the Cedarling application.
- * This function can take as config parameter the eather `Map` other `Object`
- */
-export function init(config: any): Promise<Cedarling>;
-
-/**
- * Create a new instance of the Cedarling application from archive bytes.
- *
- * This function allows loading a policy store from a Cedar Archive (.cjar)
- * that was fetched with custom logic (e.g., with authentication headers).
- *
- * # Arguments
- * * `config` - Bootstrap configuration (Map or Object). Policy store config is ignored.
- * * `archive_bytes` - The .cjar archive bytes (Uint8Array)
- *
- * # Example
- * ```javascript
- * const response = await fetch(url, { headers: { Authorization: 'Bearer ...' } });
- * const bytes = new Uint8Array(await response.arrayBuffer());
- * const cedarling = await init_from_archive_bytes(config, bytes);
- * ```
- */
-export function init_from_archive_bytes(config: any, archive_bytes: Uint8Array): Promise<Cedarling>;
-
-/**
- * The instance of the Cedarling application.
- */
-export class Cedarling {
-  /**
-   * Create a new instance of the Cedarling application.
-   * Assume that config is `Object`
-   */
-  static new(config: object): Promise<Cedarling>;
-  /**
-   * Create a new instance of the Cedarling application.
-   * Assume that config is `Map`
-   */
-  static new_from_map(config: Map<any, any>): Promise<Cedarling>;
-  /**
-   * Authorize an unsigned request carrying an optional single principal.
-   * Makes an authorization decision based on the [`RequestUnsigned`].
-   * When `principal` is omitted / `null` the core uses Cedar partial evaluation;
-   * residual-dependent requests fail closed with `Decision::Deny` and surface
-   * residual policy ids in `response.diagnostics.reason`.
-   */
-  authorize_unsigned(request: string): Promise<AuthorizeResult>;
-  /**
-   * Authorize multi-issuer request.
-   * Makes authorization decision based on multiple JWT tokens from different issuers
-   * The request is passed as a JSON string.
-   */
-  authorize_multi_issuer(request: string): Promise<MultiIssuerAuthorizeResult>;
-  /**
-   * Get logs and remove them from the storage.
-   * Returns `Array` of `Map`
-   */
-  pop_logs(): Array<any>;
-  /**
-   * Get specific log entry.
-   * Returns `Map` with values or `null`.
-   */
-  get_log_by_id(id: string): any;
-  /**
-   * Returns a list of all log ids.
-   * Returns `Array` of `String`
-   */
-  get_log_ids(): Array<any>;
-  /**
-   * Get logs by tag, like `log_kind` or `log level`.
-   * Tag can be `log_kind`, `log_level`.
-   */
-  get_logs_by_tag(tag: string): any[];
-  /**
-   * Get logs by request_id.
-   * Return log entries that match the given request_id.
-   */
-  get_logs_by_request_id(request_id: string): any[];
-  /**
-   * Get log by request_id and tag, like composite key `request_id` + `log_kind`.
-   * Tag can be `log_kind`, `log_level`.
-   * Return log entries that match the given request_id and tag.
-   */
-  get_logs_by_request_id_and_tag(request_id: string, tag: string): any[];
-  /**
-   * Push a value into the data store with an optional TTL.
-   * If the key already exists, the value will be replaced.
-   * If TTL is not provided, the default TTL from configuration is used.
-   *
-   * # Arguments
-   * * `key` - The key for the data entry
-   * * `value` - The value to store (any JSON-serializable value)
-   * * `ttl_secs` - Optional TTL in seconds (undefined uses default from config)
-   *
-   * # Example
-   * ```javascript
-   * cedarling.push_data_ctx("user:123", { name: "John", age: 30 }, 3600);
-   * cedarling.push_data_ctx("config", { setting: "value" }); // Uses default TTL
-   * ```
-   */
-  push_data_ctx(key: string, value: any, ttl_secs?: number): void;
-  /**
-   * Get a value from the data store by key.
-   * Returns null if the key doesn't exist or the entry has expired.
-   *
-   * # Arguments
-   * * `key` - The key to retrieve
-   *
-   * # Example
-   * ```javascript
-   * const value = cedarling.get_data_ctx("user:123");
-   * if (value) {
-   *   console.log(value.name);
-   * }
-   * ```
-   */
-  get_data_ctx(key: string): any;
-  /**
-   * Get a data entry with full metadata by key.
-   * Returns null if the key doesn't exist or the entry has expired.
-   * Includes metadata like creation time, expiration, access count, and type.
-   *
-   * # Arguments
-   * * `key` - The key to retrieve
-   *
-   * # Example
-   * ```javascript
-   * const entry = cedarling.get_data_entry_ctx("user:123");
-   * if (entry) {
-   *   console.log(`Created: ${entry.created_at}, Access count: ${entry.access_count}`);
-   * }
-   * ```
-   */
-  get_data_entry_ctx(key: string): any;
-  /**
-   * Remove a value from the data store by key.
-   * Returns true if the key existed and was removed, false otherwise.
-   *
-   * # Arguments
-   * * `key` - The key to remove
-   *
-   * # Example
-   * ```javascript
-   * const removed = cedarling.remove_data_ctx("user:123");
-   * ```
-   */
-  remove_data_ctx(key: string): boolean;
-  /**
-   * Clear all entries from the data store.
-   *
-   * # Example
-   * ```javascript
-   * cedarling.clear_data_ctx();
-   * ```
-   */
-  clear_data_ctx(): void;
-  /**
-   * List all entries with their metadata.
-   * Returns an array of data entries containing key, value, type, and timing metadata.
-   *
-   * # Example
-   * ```javascript
-   * const entries = cedarling.list_data_ctx();
-   * entries.forEach(entry => {
-   *   console.log(`Key: ${entry.key}, Type: ${entry.data_type}`);
-   * });
-   * ```
-   */
-  list_data_ctx(): any[];
-  /**
-   * Get statistics about the data store.
-   * Returns current entry count, capacity limits, and configuration state.
-   *
-   * # Example
-   * ```javascript
-   * const stats = cedarling.get_stats_ctx();
-   * console.log(`Entries: ${stats.entry_count}/${stats.max_entries}`);
-   * ```
-   */
-  get_stats_ctx(): DataStoreStats;
-  /**
-   * Trusted issuer loading status helpers.
-   */
-  is_trusted_issuer_loaded_by_name(issuer_id: string): boolean;
-  is_trusted_issuer_loaded_by_iss(iss_claim: string): boolean;
-  total_issuers(): number;
-  loaded_trusted_issuers_count(): number;
-  loaded_trusted_issuer_ids(): Array<string>;
-  failed_trusted_issuer_ids(): Array<string>;
-}
+Choose token-based authorization when identity comes from JWTs, or unsigned
+authorization when the application supplies a trusted principal. Both methods
+accept a JSON-string request and return a promise that resolves to an authorization
+result containing `decision` and `request_id`.
 
-/**
- * A WASM wrapper for the Rust `cedarling::AuthorizeResult` struct.
- * Represents the result of an authorization request.
- */
-export class AuthorizeResult {
-  /**
-   * Convert `AuthorizeResult` to json string value
-   */
-  json_string(): string;
-  /**
-   * Cedar authorization response for the request.
-   */
-  response: AuthorizeResultResponse;
-  /**
-   * Result of authorization
-   * true means `ALLOW`
-   * false means `Deny`
-   *
-   * this field is [`bool`] type to be compatible with [authzen Access Evaluation Decision](https://openid.github.io/authzen/#section-6.2.1).
-   */
-  decision: boolean;
-  /**
-   * Request ID of the authorization request
-   */
-  request_id: string;
-}
+#### Token-Based Authorization (Multi-Issuer)
 
-/**
- * A WASM wrapper for the Rust `cedarling::MultiIssuerAuthorizeResult` struct.
- * Represents the result of a multi-issuer authorization request.
- */
-export class MultiIssuerAuthorizeResult {
-  /**
-   * Convert `MultiIssuerAuthorizeResult` to json string value
-   */
-  json_string(): string;
-  /**
-   * Result of Cedar policy authorization
-   */
-  response: AuthorizeResultResponse;
-  /**
-   * Result of authorization
-   * true means `ALLOW`
-   * false means `Deny`
-   */
-  decision: boolean;
-  /**
-   * Request ID of the authorization request
-   */
-  request_id: string;
-}
+Use `authorizeMultiIssuer()` to evaluate tokens from one or more issuers. Your
+policy store must define the token mappings, trusted issuers, resource schema,
+action, and context used below. Configure token validation for those issuers;
+the initialization example retains Cedarling's validation defaults.
 
-/**
- * A WASM wrapper for the Rust `cedar_policy::Response` struct.
- * Represents the result of an authorization request.
- */
-export class AuthorizeResultResponse {
-  /**
-   * Authorization decision
-   */
-  readonly decision: boolean;
-  /**
-   * Diagnostics providing more information on how this decision was reached
-   */
-  readonly diagnostics: Diagnostics;
-}
+1. Prepare the tokens.
 
-/**
- * Diagnostics
- * ===========
- *
- * Provides detailed information about how a policy decision was made, including policies that contributed to the decision and any errors encountered during evaluation.
- */
-export class Diagnostics {
-  /**
-   * `PolicyId`s of the policies that contributed to the decision.
-   * If no policies applied to the request, this set will be empty.
-   *
-   * The ids should be treated as unordered,
-   */
-  readonly reason: string[];
-  /**
-   * Errors that occurred during authorization. The errors should be
-   * treated as unordered, since policies may be evaluated in any order.
-   */
-  readonly errors: PolicyEvaluationError[];
-}
+   Obtain `acmeAccessToken` and `dolphinAccessToken` from your application's
+   authentication flows. Each `mapping` must match its policy-store token
+   metadata; each `payload` is the actual JWT string.
 
-/**
- * PolicyEvaluationError
- * =====================
- *
- * Represents an error that occurred when evaluating a Cedar policy.
- */
-export class PolicyEvaluationError {
-  /**
-   * Id of the policy with an error
-   */
-  readonly id: string;
-  /**
-   * Underlying evaluation error string representation
-   */
-  readonly error: string;
-}
+   ```ts
+   const tokens = [
+     { mapping: "Acme::Access_Token", payload: acmeAccessToken },
+     { mapping: "Dolphin::Access_Token", payload: dolphinAccessToken },
+   ];
+   ```
 
-/**
- * DataStoreStats
- * ==============
- *
- * Statistics about the DataStore, providing insight into the current state
- * and usage of the data store, including memory usage metrics and capacity information.
- */
-export class DataStoreStats {
-  /**
-   * Number of entries currently stored
-   */
-  readonly entry_count: number;
-  /**
-   * Maximum number of entries allowed (0 = unlimited)
-   */
-  readonly max_entries: number;
-  /**
-   * Maximum size per entry in bytes (0 = unlimited)
-   */
-  readonly max_entry_size: number;
-  /**
-   * Whether metrics tracking is enabled
-   */
-  readonly metrics_enabled: boolean;
-  /**
-   * Total size of all entries in bytes (approximate, based on JSON serialization)
-   */
-  readonly total_size_bytes: number;
-  /**
-   * Average size per entry in bytes (0 if no entries)
-   */
-  readonly avg_entry_size_bytes: number;
-  /**
-   * Percentage of capacity used (0.0-100.0, based on entry count)
-   */
-  readonly capacity_usage_percent: number;
-  /**
-   * Memory usage threshold percentage (from config)
-   */
-  readonly memory_alert_threshold: number;
-  /**
-   * Whether memory usage exceeds the alert threshold
-   */
-  readonly memory_alert_triggered: boolean;
-}
-```
+2. Define the resource.
 
-## Configuration
+   This example targets a document. Its type and attributes must match your schema.
 
-### Policy Store Sources
+   ```ts
+   const resource = {
+     cedar_entity_mapping: { entity_type: "Task::Document", id: "document-1" },
+     owner: "alice",
+   };
+   ```
 
-Cedarling supports multiple ways to load policy stores. **In WASM environments, only URL-based loading is available** (no filesystem access).
+3. Define the action.
 
-#### WASM-Supported Options
+   ```ts
+   const action = 'Task::Action::"Read"';
+   ```
 
-```javascript
-// Option 1: Fetch policy store from URL (simple)
-const BOOTSTRAP_CONFIG = {
-  CEDARLING_POLICY_STORE_URI: "https://example.com/policy-store.cjar",
-  // Optional: re-fetch every 60s and atomically swap on change.
-  // Default is 0 (load-once-at-startup). See "Refreshing the policy store"
-  // in docs/cedarling/reference/cedarling-properties.md for details.
-  CEDARLING_POLICY_STORE_REFRESH_INTERVAL: 60,
-  // ... other config
-};
-const cedarling = await init(BOOTSTRAP_CONFIG);
-
-// Option 2: Inline JSON string (for embedded policy stores)
-// policyStoreJson is the policy store JSON as a string
-// See: https://docs.jans.io/stable/cedarling/reference/cedarling-policy-store/
-const policyStoreJson = '{"cedar_version":"4.0","policy_stores":{...}}';
-const BOOTSTRAP_CONFIG = {
-  CEDARLING_POLICY_STORE_LOCAL: policyStoreJson,
-  // ... other config
-};
-const cedarling = await init(BOOTSTRAP_CONFIG);
-
-// Option 3: Custom fetch with auth headers (use init_from_archive_bytes)
-const response = await fetch("https://example.com/policy-store.cjar", {
-  headers: { Authorization: `Bearer ${token}` },
-});
-const bytes = new Uint8Array(await response.arrayBuffer());
-const cedarling = await init_from_archive_bytes(BOOTSTRAP_CONFIG, bytes);
-```
+4. Define the context.
 
-> **Note:** Directory-based loading and file-based loading are **NOT supported in WASM** (no filesystem access). Use URL-based loading or `init_from_archive_bytes` for custom fetch scenarios.
+   Supply request-specific data required by your policies and schema.
 
-#### Cedar Archive (.cjar) Format
+   ```ts
+   const context = { tenant: "example" };
+   ```
 
-For the new directory-based format in WASM, package the directory structure as a `.cjar` file (ZIP archive):
+5. Build the request.
 
-```bash
-cd policy-store && zip -r ../policy-store.cjar .
-```
+   ```ts
+   const request = { tokens, action, resource, context };
+   ```
 
-See [Policy Store Formats](../../../docs/cedarling/reference/cedarling-policy-store.md#policy-store-formats) for details on the directory structure and metadata.json format.
+6. Perform authorization and handle the decision.
 
-### Testing Configuration
+   ```ts
+   try {
+     const result = await cedarling.authorizeMultiIssuer(JSON.stringify(request));
+     console.log(result.decision ? "Allowed" : "Denied", result.request_id);
+   } catch (error) {
+     console.error("Authorization failed", error);
+   }
+   ```
 
-For testing scenarios, you may want to disable JWT validation. You can configure this in your bootstrap configuration:
+#### Unsigned Authorization
 
-```javascript
-const BOOTSTRAP_CONFIG = {
-  CEDARLING_JWT_SIG_VALIDATION: "disabled",
-  CEDARLING_JWT_STATUS_VALIDATION: "disabled",
-};
-```
+Use `authorizeUnsigned()` when your application supplies the principal and its
+attributes. Obtain those values from trusted application state. The policy store
+for this example must define `Task::User` with a `role`, `Task::Document` with an
+`owner`, and the `Read` action with the `tenant` context field.
+
+1. Prepare the principal.
+
+   ```ts
+   const principal = {
+     cedar_entity_mapping: { entity_type: "Task::User", id: "alice" },
+     role: "member",
+   };
+   ```
+
+2. Define the resource.
 
-For complete configuration documentation, see [cedarling-properties.md](../../../docs/cedarling/cedarling-properties.md) or on [our page](https://docs.jans.io/stable/cedarling/cedarling-properties/).
+   ```ts
+   const resource = {
+     cedar_entity_mapping: { entity_type: "Task::Document", id: "document-1" },
+     owner: "alice",
+   };
+   ```
 
-## Context Data API
+3. Define the action.
 
-The Context Data API allows you to push external data into the Cedarling evaluation context, making it available in Cedar policies through the `context.data` namespace.
+   ```ts
+   const action = 'Task::Action::"Read"';
+   ```
 
-### Push Data
+4. Define the context.
 
-Store data with an optional TTL (Time To Live):
+   ```ts
+   const context = { tenant: "example" };
+   ```
 
-```javascript
-// Push data without TTL (uses default from config)
-cedarling.push_data_ctx("user:123", {
-  role: ["admin", "editor"],
-  country: "US"
-});
+5. Build the request.
 
-// Push data with TTL (5 minutes = 300 seconds)
-cedarling.push_data_ctx("config:app", { setting: "value" }, 300);
+   ```ts
+   const request = { principal, action, resource, context };
+   ```
 
-// Push different data types
-cedarling.push_data_ctx("key1", "string_value");
-cedarling.push_data_ctx("key2", 42);
-cedarling.push_data_ctx("key3", [1, 2, 3]);
-cedarling.push_data_ctx("key4", { nested: "data" });
+6. Perform authorization and handle the decision.
+
+   ```ts
+   try {
+     const result = await cedarling.authorizeUnsigned(JSON.stringify(request));
+     console.log(result.decision ? "Allowed" : "Denied", result.request_id);
+   } catch (error) {
+     console.error("Authorization failed", error);
+   }
+   ```
+
+For both methods, `decision: false` is a valid denial. Malformed requests reject
+the call. Multi-issuer authorization can continue with tokens that pass validation,
+so policies must require the tokens needed for access. Perform the protected
+operation only after receiving `decision: true`; enforce server-side access at the
+server boundary.
+
+#### Batch Authorization
+
+Evaluate several resources with one principal or token set. Each item contains
+an action, resource, and optional context. Reuse the values from the relevant
+walkthrough:
+
+```ts
+const items = [
+  { action, resource, context },
+  {
+    action,
+    resource: {
+      ...resource,
+      cedar_entity_mapping: { entity_type: "Task::Document", id: "document-2" },
+    },
+    context,
+  },
+];
+```
+
+For the unsigned walkthrough:
+
+```ts
+let batch;
+try {
+  batch = await cedarling.authorizeUnsignedBatch(
+    JSON.stringify({ principal, items }),
+  );
+} catch (error) {
+  console.error("Batch authorization failed", error);
+  throw error;
+}
 ```
 
-### Get Data
+For the token-based walkthrough, use this call instead:
+
+```ts
+let batch;
+try {
+  batch = await cedarling.authorizeMultiIssuerBatch(
+    JSON.stringify({ tokens, items }),
+  );
+} catch (error) {
+  console.error("Batch authorization failed", error);
+  throw error;
+}
+```
 
-Retrieve stored data:
+After a successful batch call, inspect each item in the same order as the
+submitted `items`:
 
-```javascript
-// Get data by key
-const value = cedarling.get_data_ctx("user:123");
-if (value) {
-  console.log(`User roles: ${value.role}`);
+```ts
+for (const item of batch.results) {
+  if (item.is_ok) {
+    console.log(item.unwrap().decision ? "Allowed" : "Denied");
+  } else {
+    console.error(item.error?.category, item.error?.message);
+  }
 }
 ```
 
-### Get Data Entry with Metadata
+A valid denial has `is_ok === true` and a false decision. A per-item build error
+has `is_ok === false`. The returned `batch_id` correlates the batch's decision logs.
+
+### Logging
 
-Get a data entry with full metadata including creation time, expiration, access count, and type:
+The initialization example enables memory logging and retains entries for up to 120
+seconds. Inside either authorization walkthrough's `try` block, use the returned
+request ID to inspect its logs:
+
+```ts
+const logs = cedarling.getLogsByRequestId(result.request_id);
+console.log(logs);
+```
 
-```javascript
-const entry = cedarling.get_data_entry_ctx("user:123");
-if (entry) {
-  console.log(`Key: ${entry.key}`);
-  console.log(`Created at: ${entry.created_at}`);
-  console.log(`Access count: ${entry.access_count}`);
-  console.log(`Data type: ${entry.data_type}`);
-  console.log(`Value:`, entry.value);
+Log records are plain JavaScript objects. To retrieve and clear all retained logs
+when your application is ready to consume them:
+
+```ts
+try {
+  const retainedLogs = cedarling.popLogs();
+  console.log(retainedLogs);
+} catch (error) {
+  console.error("Log retrieval failed", error);
 }
 ```
 
-### Remove Data
+### Context Data
 
-Remove a specific entry:
+Store application-scoped data for policy evaluation, then retrieve or remove it:
 
-```javascript
-// Remove data by key
-const removed = cedarling.remove_data_ctx("user:123");
-if (removed) {
-  console.log("Entry was removed");
-} else {
-  console.log("Entry did not exist");
+```ts
+try {
+  cedarling.pushDataCtx("user:alice", { plan: "pro" }, 3600n);
+  const value = cedarling.getDataCtx("user:alice");
+  console.log(value);
+  cedarling.removeDataCtx("user:alice");
+} catch (error) {
+  console.error("Context-data operation failed", error);
 }
 ```
 
-### Clear All Data
+The optional TTL is a `bigint` number of seconds; omitting it uses the configured
+default. Retrieval returns `null` when a value is absent or expired.
+
+### Metrics Snapshot
 
-Remove all entries from the data store:
+Destructive read: returns a metrics snapshot and resets the counters.
 
-```javascript
-cedarling.clear_data_ctx();
+```ts
+try {
+  const snapshot = cedarling.drainMetrics();
+  console.log(snapshot.operational_stats.get("authz.requests_total"));
+  console.log(snapshot.interval_secs);
+} catch (error) {
+  console.error("Metrics snapshot failed", error);
+}
 ```
 
-### List All Data
+Requires `CEDARLING_METRICS_COLLECTION: "enabled"`. Fails whenever
+`CEDARLING_LOCK_TELEMETRY_INTERVAL` is set, even if the Lock server has no
+telemetry endpoint. `interval_secs` is a plain `Number` (not `BigInt`), so
+`snapshot.interval_secs + 1` works. It carries fractional seconds, so
+sub-second intervals are reported exactly. Use `snapshot.jsonString()` for a
+JSON-serializable form with plain objects.
 
-List all entries with their metadata:
+### Trusted Issuer Readiness
 
-```javascript
-const entries = cedarling.list_data_ctx();
-entries.forEach(entry => {
-  console.log(`Key: ${entry.key}, Type: ${entry.data_type}, Created: ${entry.created_at}`);
-});
+Before token-based authorization, inspect which configured issuers loaded and
+which failed:
+
+```ts
+console.log("Loaded issuers", cedarling.loadedTrustedIssuerIds());
+console.log("Failed issuers", cedarling.failedTrustedIssuerIds());
 ```
 
-### Get Statistics
+To check one issuer, pass its configured identifier to
+`cedarling.isTrustedIssuerLoadedByName(issuerId)`.
 
-Get statistics about the data store:
+### Policy Annotations
 
-```javascript
-const stats = cedarling.get_stats_ctx();
-console.log(`Entries: ${stats.entry_count}/${stats.max_entries}`);
-console.log(`Total size: ${stats.total_size_bytes} bytes`);
-console.log(`Capacity usage: ${stats.capacity_usage_percent}%`);
+Annotations attach metadata such as descriptions to policies using
+`@key("value")`. They describe policies independently of their authorization rules.
+For example, a policy in your archive can include:
+
+```cedar
+@description("Allows Alice to read document-1")
+permit (
+    principal == Task::User::"alice",
+    action == Task::Action::"Read",
+    resource == Task::Document::"document-1"
+);
 ```
 
-### Error Handling
+Inside the unsigned walkthrough's `try` block, retrieve descriptions for the
+determining policy IDs returned in the result:
+
+```ts
+const descriptions = cedarling.annotationValues(
+  result.response.diagnostics.reason,
+  "description",
+);
+console.log(descriptions);
+```
 
-The Context Data API methods throw errors for different error conditions:
+See the [Cedar annotation reference](https://docs.cedarpolicy.com/policies/syntax-policy.html#annotations)
+for annotation syntax and behavior.
 
-```javascript
+### Shutdown
+
+When the application finishes using a Cedarling instance, shut it down:
+
+```ts
 try {
-  cedarling.push_data_ctx("", { data: "value" }); // Empty key
+  await cedarling.shutDown();
 } catch (error) {
-  if (error.message.includes("InvalidKey")) {
-    console.log("Invalid key provided");
-  }
-}
-
-const value = cedarling.get_data_ctx("nonexistent");
-if (value === null) {
-  console.log("Key not found");
+  console.error("Cedarling shutdown failed", error);
 }
 ```
 
-### Using Data in Cedar Policies
+### Other Integration Paths
 
-Data pushed via the Context Data API is automatically available in Cedar policies under the `context.data` namespace:
+#### Edge Deployments
 
-```cedar
-permit(
-    principal,
-    action == Action::"read",
-    resource
-) when {
-    context.data["user:123"].role.contains("admin")
+Use the ESM-only `./edge` entry in hosts whose deployment tool bundles the package's
+WASM binary as a precompiled WebAssembly module. In Cloudflare Workers, initialize inside
+the [request context](https://developers.cloudflare.com/workers/runtime-apis/request/#the-request-context)
+so policy downloads can run:
+
+```ts
+import { init } from "@janssenproject/cedarling_wasm/edge";
+
+export default {
+  async fetch() {
+    let cedarling;
+    try {
+      cedarling = await init({
+        CEDARLING_APPLICATION_NAME: "edge-api",
+        CEDARLING_POLICY_STORE_URI: "https://example.com/policy-store.cjar",
+      });
+      return new Response("Cedarling initialized");
+    } catch (error) {
+      console.error("Cedarling initialization failed", error);
+      return new Response("Internal server error", { status: 500 });
+    } finally {
+      try {
+        await cedarling?.shutDown();
+      } catch (error) {
+        console.error("Cedarling shutdown failed", error);
+      }
+    }
+  },
 };
 ```
 
-The data is injected into the evaluation context before policy evaluation, allowing policies to make decisions based on dynamically pushed data.
+#### Manual Bundler Integration
 
-## Trusted Issuer Loading Info
+For application-controlled WASM loading, configure your ESM bundler to emit the
+package's `./wasm` export as a URL-addressable binary asset. Configure the server
+to serve it with the `application/wasm` content type. The example below reuses
+`config` and `policyArchiveBytes` from
+[Load a Cedar Archive from Bytes](#load-a-cedar-archive-from-bytes), replacing
+that section's initialization call:
 
-When a policy store contains `trusted-issuers/` entries, you can inspect loading status:
+```ts
+import initWasm, {
+  initFromArchiveBytes,
+} from "@janssenproject/cedarling_wasm/manual";
+import wasmUrl from "@janssenproject/cedarling_wasm/wasm";
 
-```javascript
-const loaded = cedarling.is_trusted_issuer_loaded_by_name("issuer_id");
-const loadedByIss = cedarling.is_trusted_issuer_loaded_by_iss("https://issuer.example.org");
-const total = cedarling.total_issuers();
-const loadedCount = cedarling.loaded_trusted_issuers_count();
-const loadedIds = cedarling.loaded_trusted_issuer_ids();
-const failedIds = cedarling.failed_trusted_issuer_ids();
+let cedarling;
+try {
+  await initWasm({ module_or_path: wasmUrl });
+  cedarling = await initFromArchiveBytes(config, policyArchiveBytes);
+} catch (error) {
+  console.error("WASM loading or Cedarling initialization failed", error);
+  throw error;
+}
 ```
+
+Configure the `.wasm` import to return an asset URL; the exact rule or plugin
+depends on your bundler.
+
+## Upgrading Existing Applications
+
+Update calls such as `authorize_unsigned()` to `authorizeUnsigned()`,
+`shut_down()` to `shutDown()`, and `json_string()` to `jsonString()`.
+Bootstrap keys (`CEDARLING_*`), request JSON, result/data fields such as
+`request_id`, and serialized JSON retain their names.
+
+## See Also
+
+- [JavaScript tutorial](https://docs.jans.io/stable/cedarling/tutorials/javascript/)
+- [Full API reference](https://docs.jans.io/stable/cedarling/tutorials/javascript/#api-reference)
+- [Bootstrap-property reference](https://docs.jans.io/stable/cedarling/reference/cedarling-properties/)
+- [Cedar Archive format](https://docs.jans.io/nightly/cedarling/reference/cedarling-policy-store/#cedar-archive-cjar-format)
+- [Maintainer guide](https://github.com/JanssenProject/jans/blob/main/jans-cedarling/bindings/cedarling_wasm/js/docs/maintainer.md)