@janssenproject/cedarling_wasm 0.0.466 → 0.0.467-nodejs

package/README.md

@@ -1,6 +1,16 @@
 # Cedarling WASM
 
-This module is designed to build cedarling for browser wasm.
+This module builds Cedarling's Rust implementation for WebAssembly. This guide
+covers building and testing the generated binding and running its local browser
+examples; JavaScript package consumers should use the npm package guide below.
+
+## Choose the right guide
+
+- For a JavaScript or TypeScript application, use the
+  [npm package guide](./js/README.md).
+- For package generation, artifact qualification, and release maintenance, use
+  the [maintainer guide](./js/docs/maintainer.md).
+- This guide covers direct development with the wasm-pack-generated binding.
 
 ## Building
 
@@ -55,563 +65,23 @@ async function main() {
   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));
+  let result = await instance.authorizeUnsigned(JSON.stringify(REQUEST_UNSIGNED));
   console.log("result:", result);
 }
 main().catch(console.error);
 ```
 
-Before using any function from library you need initialize WASM runtime by calling `initWasm` function.
-
-### Defined API
-
-```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>;
-}
-
-/**
- * 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;
-}
-
-/**
- * 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;
-}
-
-/**
- * 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;
-}
-
-/**
- * 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[];
-}
-
-/**
- * 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;
-}
-
-/**
- * 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;
-}
-```
-
-## Configuration
-
-### Policy Store Sources
-
-Cedarling supports multiple ways to load policy stores. **In WASM environments, only URL-based loading is available** (no filesystem access).
-
-#### WASM-Supported Options
-
-```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);
-```
-
-> **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.
-
-#### Cedar Archive (.cjar) Format
-
-For the new directory-based format in WASM, package the directory structure as a `.cjar` file (ZIP archive):
-
-```bash
-cd policy-store && zip -r ../policy-store.cjar .
-```
-
-See [Policy Store Formats](../../../docs/cedarling/reference/cedarling-policy-store.md#policy-store-formats) for details on the directory structure and metadata.json format.
-
-### Testing Configuration
-
-For testing scenarios, you may want to disable JWT validation. You can configure this in your bootstrap configuration:
-
-```javascript
-const BOOTSTRAP_CONFIG = {
-  CEDARLING_JWT_SIG_VALIDATION: "disabled",
-  CEDARLING_JWT_STATUS_VALIDATION: "disabled",
-};
-```
-
-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/).
-
-## Context Data API
-
-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.
-
-### Push Data
-
-Store data with an optional TTL (Time To Live):
-
-```javascript
-// Push data without TTL (uses default from config)
-cedarling.push_data_ctx("user:123", {
-  role: ["admin", "editor"],
-  country: "US"
-});
-
-// Push data with TTL (5 minutes = 300 seconds)
-cedarling.push_data_ctx("config:app", { setting: "value" }, 300);
-
-// 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" });
-```
-
-### Get Data
-
-Retrieve stored data:
-
-```javascript
-// Get data by key
-const value = cedarling.get_data_ctx("user:123");
-if (value) {
-  console.log(`User roles: ${value.role}`);
-}
-```
-
-### Get Data Entry with Metadata
-
-Get a data entry with full metadata including creation time, expiration, access count, and type:
-
-```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);
-}
-```
-
-### Remove Data
-
-Remove a specific entry:
-
-```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");
-}
-```
-
-### Clear All Data
-
-Remove all entries from the data store:
-
-```javascript
-cedarling.clear_data_ctx();
-```
-
-### List All Data
-
-List all entries with their metadata:
-
-```javascript
-const entries = cedarling.list_data_ctx();
-entries.forEach(entry => {
-  console.log(`Key: ${entry.key}, Type: ${entry.data_type}, Created: ${entry.created_at}`);
-});
-```
-
-### Get Statistics
-
-Get statistics about the data store:
-
-```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}%`);
-```
-
-### Error Handling
-
-The Context Data API methods throw errors for different error conditions:
-
-```javascript
-try {
-  cedarling.push_data_ctx("", { data: "value" }); // Empty key
-} 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");
-}
-```
-
-### Using Data in Cedar Policies
+When importing the generated glue directly from `pkg/`, call `initWasm()` before
+using the binding. The npm package's automatic entries handle this initialization.
 
-Data pushed via the Context Data API is automatically available in Cedar policies under the `context.data` namespace:
+## API contract
 
-```cedar
-permit(
-    principal,
-    action == Action::"read",
-    resource
-) when {
-    context.data["user:123"].role.contains("admin")
-};
-```
-
-The data is injected into the evaluation context before policy evaluation, allowing policies to make decisions based on dynamically pushed data.
-
-## Trusted Issuer Loading Info
+`pkg/cedarling_wasm.d.ts` is the authoritative direct WebAssembly API after a
+successful build. Callable JavaScript APIs use camelCase, including
+`jsonString()`. Cedarling bootstrap properties, request JSON keys, and returned
+data fields retain their canonical names, including snake_case fields such as
+`request_id`.
 
-When a policy store contains `trusted-issuers/` entries, you can inspect loading status:
-
-```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();
-```
+For portable npm consumption across browser, Node.js ESM, Node.js CommonJS,
+edge, and manual bundler paths, use `@janssenproject/cedarling_wasm` and its
+consumer guide instead of importing files under `pkg/`.