@janssenproject/cedarling_wasm 2.0.0 → 2.0.1-nodejs

package/README.md

@@ -37,7 +37,7 @@ To run example using `index.html` you need execute following steps:
 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.
+   - Also you can try use cedarling with web app using [cedarling_app](http://localhost:8000/cedarling_app.html), using custom bootstrap properties and request.
 
 ## WASM Usage
 
@@ -46,17 +46,17 @@ After building WASM bindings in folder `pkg` you can find where you can find `ce
 In `index.html` described simple usage of `cedarling wasm` API:
 
 ```js
-        import { BOOTSTRAP_CONFIG, REQUEST } from "/example_data.js" // Import js objects: bootstrap config and request
-        import initWasm, { init } from "/pkg/cedarling_wasm.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";
 
-        async function main() {
-            await initWasm(); // Initialize the WebAssembly module
+async function main() {
+  await initWasm(); // Initialize the WebAssembly module
 
-            let instance = await init(BOOTSTRAP_CONFIG);
-            let result = await instance.authorize(REQUEST);
-            console.log("result:", result);
-        }
-        main().catch(console.error);
+  let instance = await init(BOOTSTRAP_CONFIG);
+  let result = await instance.authorize_unsigned(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.
@@ -70,6 +70,25 @@ Before using any function from library you need initialize WASM runtime by calli
  */
 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.
  */
@@ -85,10 +104,18 @@ export class Cedarling {
    */
   static new_from_map(config: Map<any, any>): Promise<Cedarling>;
   /**
-   * Authorize request
-   * makes authorization decision based on the [`Request`]
+   * 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(request: any): Promise<AuthorizeResult>;
+  authorize_unsigned(request: any): Promise<AuthorizeResult>;
+  /**
+   * Authorize multi-issuer request.
+   * Makes authorization decision based on multiple JWT tokens from different issuers
+   */
+  authorize_multi_issuer(request: any): Promise<MultiIssuerAuthorizeResult>;
   /**
    * Get logs and remove them from the storage.
    * Returns `Array` of `Map`
@@ -120,6 +147,111 @@ export class Cedarling {
    * 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>;
 }
 
 /**
@@ -132,13 +264,9 @@ export class AuthorizeResult {
    */
   json_string(): string;
   /**
-   * Result of authorization where principal is `Jans::Workload`
-   */
-  workload?: AuthorizeResultResponse;
-  /**
-   * Result of authorization where principal is `Jans::User`
+   * Cedar authorization response for the request.
    */
-  person?: AuthorizeResultResponse;
+  response: AuthorizeResultResponse;
   /**
    * Result of authorization
    * true means `ALLOW`
@@ -153,6 +281,31 @@ export class AuthorizeResult {
   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.
@@ -181,12 +334,12 @@ export class Diagnostics {
    *
    * The ids should be treated as unordered,
    */
-  readonly reason: (string)[];
+  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)[];
+  readonly errors: PolicyEvaluationError[];
 }
 
 /**
@@ -205,4 +358,253 @@ export class PolicyEvaluationError {
    */
   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",
+  // ... 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
+
+Data pushed via the Context Data API is automatically available in Cedar policies under the `context.data` namespace:
+
+```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
+
+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();
 ```