@janssenproject/cedarling_wasm 2.1.0 → 2.3.0-nodejs

package/README.md

@@ -53,7 +53,9 @@ async function main() {
   await initWasm(); // Initialize the WebAssembly module
 
   let instance = await init(BOOTSTRAP_CONFIG);
-  let result = await instance.authorize_unsigned(REQUEST_UNSIGNED);
+  // 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);
 }
 main().catch(console.error);
@@ -110,12 +112,13 @@ export class Cedarling {
    * residual-dependent requests fail closed with `Decision::Deny` and surface
    * residual policy ids in `response.diagnostics.reason`.
    */
-  authorize_unsigned(request: any): Promise<AuthorizeResult>;
+  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: any): Promise<MultiIssuerAuthorizeResult>;
+  authorize_multi_issuer(request: string): Promise<MultiIssuerAuthorizeResult>;
   /**
    * Get logs and remove them from the storage.
    * Returns `Array` of `Map`
@@ -418,6 +421,10 @@ Cedarling supports multiple ways to load policy stores. **In WASM environments,
 // 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);

package/cedarling_wasm.d.ts

@@ -56,6 +56,116 @@ export class AuthorizeResultResponse {
     readonly diagnostics: Diagnostics;
 }
 
+/**
+ * WASM wrapper for
+ * `cedarling::BatchAuthorizeResponse<Result<MultiIssuerAuthorizeResult, BatchItemError>>`.
+ * Same shape as [`BatchAuthorizeUnsignedResponse`] with multi-issuer results.
+ */
+export class BatchAuthorizeMultiIssuerResponse {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Shared correlation id stamped on every per-item decision log entry.
+     */
+    readonly batch_id: string;
+    /**
+     * Per-item results in input order — each slot is a
+     * [`BatchItemMultiIssuerResult`].
+     */
+    readonly results: BatchItemMultiIssuerResult[];
+}
+
+/**
+ * WASM wrapper for `cedarling::BatchAuthorizeResponse<Result<AuthorizeResult, BatchItemError>>`.
+ *
+ * Carries a shared `batch_id` (UUIDv7) alongside per-item results. Each result
+ * is a [`BatchItemUnsignedResult`] — Cedar decision on `is_ok()`, per-item
+ * build failure on `error`. `results[i]` corresponds to `items[i]`.
+ */
+export class BatchAuthorizeUnsignedResponse {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Shared correlation id stamped on every per-item decision log entry.
+     */
+    readonly batch_id: string;
+    /**
+     * Per-item results in input order — each slot is a
+     * [`BatchItemUnsignedResult`].
+     */
+    readonly results: BatchItemUnsignedResult[];
+}
+
+/**
+ * Per-item build failure surfaced inside a batch response at `results[i]`
+ * when Cedar couldn't be reached for that item.
+ */
+export class BatchItemError {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Stable variant slug — `action_parse`, `resource_build`, `context_build`,
+     * `principal_build`, `schema_validation`, `multi_issuer_entity`,
+     * `request_validation`.
+     */
+    readonly category: string;
+    /**
+     * Position of the failing item in the original `items` vector.
+     */
+    readonly item_index: number;
+    /**
+     * Human-readable diagnostic. Safe to log.
+     */
+    readonly message: string;
+}
+
+/**
+ * Multi-issuer analog of [`BatchItemUnsignedResult`].
+ */
+export class BatchItemMultiIssuerResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * The multi-issuer decision if `is_ok()`; throws otherwise.
+     */
+    unwrap(): MultiIssuerAuthorizeResult;
+    /**
+     * The per-item error if `!is_ok()`; `undefined` otherwise.
+     */
+    readonly error: BatchItemError | undefined;
+    /**
+     * `true` when Cedar evaluated this item.
+     */
+    readonly is_ok: boolean;
+}
+
+/**
+ * One slot in a batch response's `results` array. Callers switch on
+ * `is_ok()` — on `true`, read `unwrap()`; on `false`, read `error()`.
+ */
+export class BatchItemUnsignedResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * The Cedar decision if `is_ok()`; throws otherwise.
+     */
+    unwrap(): AuthorizeResult;
+    /**
+     * The per-item error if `!is_ok()`; `undefined` otherwise.
+     */
+    readonly error: BatchItemError | undefined;
+    /**
+     * `true` when Cedar evaluated this item (Allow or Deny); `false` when it
+     * failed to build.
+     */
+    readonly is_ok: boolean;
+}
+
 /**
  * The instance of the Cedarling application.
  */
@@ -63,11 +173,103 @@ export class Cedarling {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Collect every value of the annotation `key` across the given policies,
+     * preserving duplicates. Unknown policy IDs are silently skipped.
+     *
+     * # Arguments
+     *
+     * * `policy_ids` - List of policy IDs to search. Typically
+     *   `result.response.diagnostics.reason` from an authorization result.
+     * * `key` - The annotation key to collect values for (e.g. `"redirect"`).
+     *
+     * # Example
+     *
+     * ```javascript
+     * const redirects = cedarling.annotation_values(result.response.diagnostics.reason, "redirect");
+     * // ["/upgrade"]
+     * ```
+     */
+    annotation_values(policy_ids: string[], key: string): string[];
+    /**
+     * Return the annotations of each given policy, grouped by policy ID
+     * the loss-free companion to `annotations_map`. Unknown policy IDs are
+     * silently skipped.
+     *
+     * # Arguments
+     *
+     * * `policy_ids` - List of policy IDs whose annotations should be returned
+     *   grouped by policy ID. Typically `result.response.diagnostics.reason` from
+     *   an authorization result.
+     *
+     * # Example
+     *
+     * ```javascript
+     * const byPolicy = cedarling.annotations_by_policy(result.response.diagnostics.reason);
+     * // { "5": { redirect: "/upgrade", tier: "premium" } }
+     * ```
+     */
+    annotations_by_policy(policy_ids: string[]): any;
+    /**
+     * Merge the annotations (`@key("value")`) of the given policies into a single object.
+     *
+     * Intended for resolving the determining policies of an authorization decision:
+     * pass `result.response.diagnostics.reason`.
+     *
+     * Lossy: if the same annotation key appears on several policies, one value wins
+     * arbitrarily. Use `annotation_values` / `annotations_by_policy` when duplicates
+     * matter. Unknown policy IDs are silently skipped.
+     *
+     * # Arguments
+     *
+     * * `policy_ids` - List of policy IDs whose annotations should be merged into
+     *   a single object. Typically `result.response.diagnostics.reason` from an
+     *   authorization result.
+     *
+     * # Example
+     *
+     * ```javascript
+     * const annotations = cedarling.annotations_map(result.response.diagnostics.reason);
+     * // { redirect: "/upgrade", tier: "premium" }
+     * ```
+     */
+    annotations_map(policy_ids: string[]): any;
     /**
      * Authorize multi-issuer request.
-     * Makes authorization decision based on multiple JWT tokens from different issuers
+     * Makes authorization decision based on multiple JWT tokens from different issuers.
+     *
+     * # Arguments
+     *
+     * * `request` - JSON string representation of [`AuthorizeMultiIssuerRequest`].
+     *
+     * # Example
+     *
+     * ```javascript
+     * const result = await cedarling.authorize_multi_issuer(JSON.stringify(request));
+     * ```
+     */
+    authorize_multi_issuer(request: string): Promise<MultiIssuerAuthorizeResult>;
+    /**
+     * Authorize a batch of multi-issuer requests against one shared token set.
+     *
+     * Tokens are validated and token/issuer entities are built once, then
+     * each item is evaluated in input order. Batch-level failures (validation,
+     * JWT verification, status-list refresh) reject the whole call; per-item
+     * failures are returned as `BatchItemError` results and exposed by WASM
+     * with `is_ok=false` and `error`, while genuine Cedar denials remain
+     * `AuthorizeResult` values with `decision=false`.
+     *
+     * # Arguments
+     *
+     * * `request` - JSON string representation of [`BatchAuthorizeMultiIssuerRequest`].
+     *
+     * # Example
+     *
+     * ```javascript
+     * const result = await cedarling.authorize_multi_issuer_batch(JSON.stringify(batchRequest));
+     * ```
      */
-    authorize_multi_issuer(request: any): Promise<MultiIssuerAuthorizeResult>;
+    authorize_multi_issuer_batch(request: string): Promise<BatchAuthorizeMultiIssuerResponse>;
     /**
      * Authorize an unsigned request carrying an optional single principal.
      * Makes an authorization decision based on the [`RequestUnsigned`].
@@ -76,8 +278,39 @@ export class Cedarling {
      * partial evaluation; residual-dependent requests fail closed with
      * `Decision::Deny` and surface residual policy ids in
      * `response.diagnostics.reason`.
+     *
+     * # Arguments
+     *
+     * * `request` - JSON string representation of [`RequestUnsigned`].
+     *
+     * # Example
+     *
+     * ```javascript
+     * const result = await cedarling.authorize_unsigned(JSON.stringify(request));
+     * ```
+     */
+    authorize_unsigned(request: string): Promise<AuthorizeResult>;
+    /**
+     * Authorize a batch of unsigned requests against one shared principal.
+     *
+     * Setup work (principal build + pushed-data snapshot) runs once and each
+     * item is evaluated in input order. Results are returned inside a
+     * [`BatchAuthorizeUnsignedResponse`] carrying the shared `batch_id`.
+     * Batch-level failures (validation, principal parse) reject the whole
+     * call; per-item failures are returned as `BatchItemError` results and
+     * exposed by WASM with `is_ok=false` and `error`, while genuine Cedar
+     * denials remain `AuthorizeResult` values with `decision=false`.
+     * # Arguments
+     *
+     * * `request` - JSON string representation of [`BatchAuthorizeUnsignedRequest`].
+     *
+     * # Example
+     *
+     * ```javascript
+     * const result = await cedarling.authorize_unsigned_batch(JSON.stringify(batchRequest));
+     * ```
      */
-    authorize_unsigned(request: any): Promise<AuthorizeResult>;
+    authorize_unsigned_batch(request: string): Promise<BatchAuthorizeUnsignedResponse>;
     /**
      * Clear all entries from the data store.
      *
@@ -524,153 +757,3 @@ export function init(config: any): Promise<Cedarling>;
  * ```
  */
 export function init_from_archive_bytes(config: any, archive_bytes: Uint8Array): Promise<Cedarling>;
-
-export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
-
-export interface InitOutput {
-    readonly memory: WebAssembly.Memory;
-    readonly __wbg_authorizeresult_free: (a: number, b: number) => void;
-    readonly __wbg_authorizeresultresponse_free: (a: number, b: number) => void;
-    readonly __wbg_cedarling_free: (a: number, b: number) => void;
-    readonly __wbg_dataentry_free: (a: number, b: number) => void;
-    readonly __wbg_datastorestats_free: (a: number, b: number) => void;
-    readonly __wbg_diagnostics_free: (a: number, b: number) => void;
-    readonly __wbg_get_authorizeresult_decision: (a: number) => number;
-    readonly __wbg_get_authorizeresult_request_id: (a: number) => [number, number];
-    readonly __wbg_get_authorizeresult_response: (a: number) => number;
-    readonly __wbg_get_dataentry_access_count: (a: number) => bigint;
-    readonly __wbg_get_dataentry_created_at: (a: number) => [number, number];
-    readonly __wbg_get_dataentry_data_type: (a: number) => [number, number];
-    readonly __wbg_get_dataentry_expires_at: (a: number) => [number, number];
-    readonly __wbg_get_dataentry_key: (a: number) => [number, number];
-    readonly __wbg_get_datastorestats_avg_entry_size_bytes: (a: number) => number;
-    readonly __wbg_get_datastorestats_capacity_usage_percent: (a: number) => number;
-    readonly __wbg_get_datastorestats_entry_count: (a: number) => number;
-    readonly __wbg_get_datastorestats_max_entries: (a: number) => number;
-    readonly __wbg_get_datastorestats_max_entry_size: (a: number) => number;
-    readonly __wbg_get_datastorestats_memory_alert_threshold: (a: number) => number;
-    readonly __wbg_get_datastorestats_memory_alert_triggered: (a: number) => number;
-    readonly __wbg_get_datastorestats_metrics_enabled: (a: number) => number;
-    readonly __wbg_get_datastorestats_total_size_bytes: (a: number) => number;
-    readonly __wbg_policyevaluationerror_free: (a: number, b: number) => void;
-    readonly __wbg_set_authorizeresult_decision: (a: number, b: number) => void;
-    readonly __wbg_set_authorizeresult_request_id: (a: number, b: number, c: number) => void;
-    readonly __wbg_set_authorizeresult_response: (a: number, b: number) => void;
-    readonly __wbg_set_dataentry_access_count: (a: number, b: bigint) => void;
-    readonly __wbg_set_dataentry_created_at: (a: number, b: number, c: number) => void;
-    readonly __wbg_set_dataentry_data_type: (a: number, b: number, c: number) => void;
-    readonly __wbg_set_dataentry_expires_at: (a: number, b: number, c: number) => void;
-    readonly __wbg_set_dataentry_key: (a: number, b: number, c: number) => void;
-    readonly __wbg_set_datastorestats_avg_entry_size_bytes: (a: number, b: number) => void;
-    readonly __wbg_set_datastorestats_capacity_usage_percent: (a: number, b: number) => void;
-    readonly __wbg_set_datastorestats_entry_count: (a: number, b: number) => void;
-    readonly __wbg_set_datastorestats_max_entries: (a: number, b: number) => void;
-    readonly __wbg_set_datastorestats_max_entry_size: (a: number, b: number) => void;
-    readonly __wbg_set_datastorestats_memory_alert_threshold: (a: number, b: number) => void;
-    readonly __wbg_set_datastorestats_memory_alert_triggered: (a: number, b: number) => void;
-    readonly __wbg_set_datastorestats_metrics_enabled: (a: number, b: number) => void;
-    readonly __wbg_set_datastorestats_total_size_bytes: (a: number, b: number) => void;
-    readonly authorizeresult_json_string: (a: number) => [number, number];
-    readonly authorizeresultresponse_decision: (a: number) => number;
-    readonly authorizeresultresponse_diagnostics: (a: number) => number;
-    readonly cedarling_authorize_multi_issuer: (a: number, b: any) => any;
-    readonly cedarling_authorize_unsigned: (a: number, b: any) => any;
-    readonly cedarling_clear_data_ctx: (a: number) => [number, number];
-    readonly cedarling_failed_trusted_issuer_ids: (a: number) => any;
-    readonly cedarling_get_data_ctx: (a: number, b: number, c: number) => [number, number, number];
-    readonly cedarling_get_data_entry_ctx: (a: number, b: number, c: number) => [number, number, number];
-    readonly cedarling_get_log_by_id: (a: number, b: number, c: number) => [number, number, number];
-    readonly cedarling_get_log_ids: (a: number) => any;
-    readonly cedarling_get_logs_by_request_id: (a: number, b: number, c: number) => [number, number, number, number];
-    readonly cedarling_get_logs_by_request_id_and_tag: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
-    readonly cedarling_get_logs_by_tag: (a: number, b: number, c: number) => [number, number, number, number];
-    readonly cedarling_get_stats_ctx: (a: number) => [number, number, number];
-    readonly cedarling_is_trusted_issuer_loaded_by_iss: (a: number, b: number, c: number) => number;
-    readonly cedarling_is_trusted_issuer_loaded_by_name: (a: number, b: number, c: number) => number;
-    readonly cedarling_list_data_ctx: (a: number) => [number, number, number];
-    readonly cedarling_loaded_trusted_issuer_ids: (a: number) => any;
-    readonly cedarling_loaded_trusted_issuers_count: (a: number) => number;
-    readonly cedarling_new: (a: any) => any;
-    readonly cedarling_new_from_map: (a: any) => any;
-    readonly cedarling_pop_logs: (a: number) => [number, number, number];
-    readonly cedarling_push_data_ctx: (a: number, b: number, c: number, d: any, e: number, f: bigint) => [number, number];
-    readonly cedarling_remove_data_ctx: (a: number, b: number, c: number) => [number, number, number];
-    readonly cedarling_shut_down: (a: number) => any;
-    readonly cedarling_total_issuers: (a: number) => number;
-    readonly dataentry_json_string: (a: number) => [number, number];
-    readonly dataentry_value: (a: number) => [number, number, number];
-    readonly datastorestats_json_string: (a: number) => [number, number];
-    readonly diagnostics_errors: (a: number) => [number, number];
-    readonly diagnostics_reason: (a: number) => [number, number];
-    readonly init: (a: any) => any;
-    readonly init_from_archive_bytes: (a: any, b: any) => any;
-    readonly multiissuerauthorizeresult_json_string: (a: number) => [number, number];
-    readonly policyevaluationerror_error: (a: number) => [number, number];
-    readonly policyevaluationerror_id: (a: number) => [number, number];
-    readonly __wbg_get_multiissuerauthorizeresult_decision: (a: number) => number;
-    readonly __wbg_set_multiissuerauthorizeresult_response: (a: number, b: number) => void;
-    readonly __wbg_set_multiissuerauthorizeresult_request_id: (a: number, b: number, c: number) => void;
-    readonly __wbg_set_multiissuerauthorizeresult_decision: (a: number, b: number) => void;
-    readonly __wbg_get_multiissuerauthorizeresult_response: (a: number) => number;
-    readonly __wbg_get_multiissuerauthorizeresult_request_id: (a: number) => [number, number];
-    readonly __wbg_multiissuerauthorizeresult_free: (a: number, b: number) => void;
-    readonly __wbg_intounderlyingbytesource_free: (a: number, b: number) => void;
-    readonly __wbg_intounderlyingsink_free: (a: number, b: number) => void;
-    readonly __wbg_intounderlyingsource_free: (a: number, b: number) => void;
-    readonly intounderlyingbytesource_autoAllocateChunkSize: (a: number) => number;
-    readonly intounderlyingbytesource_cancel: (a: number) => void;
-    readonly intounderlyingbytesource_pull: (a: number, b: any) => any;
-    readonly intounderlyingbytesource_start: (a: number, b: any) => void;
-    readonly intounderlyingbytesource_type: (a: number) => number;
-    readonly intounderlyingsink_abort: (a: number, b: any) => any;
-    readonly intounderlyingsink_close: (a: number) => any;
-    readonly intounderlyingsink_write: (a: number, b: any) => any;
-    readonly intounderlyingsource_cancel: (a: number) => void;
-    readonly intounderlyingsource_pull: (a: number, b: any) => any;
-    readonly rust_zstd_wasm_shim_calloc: (a: number, b: number) => number;
-    readonly rust_zstd_wasm_shim_free: (a: number) => void;
-    readonly rust_zstd_wasm_shim_malloc: (a: number) => number;
-    readonly rust_zstd_wasm_shim_memcmp: (a: number, b: number, c: number) => number;
-    readonly rust_zstd_wasm_shim_memcpy: (a: number, b: number, c: number) => number;
-    readonly rust_zstd_wasm_shim_memmove: (a: number, b: number, c: number) => number;
-    readonly rust_zstd_wasm_shim_memset: (a: number, b: number, c: number) => number;
-    readonly rust_zstd_wasm_shim_qsort: (a: number, b: number, c: number, d: number) => void;
-    readonly wasm_bindgen__convert__closures_____invoke__he0d1df4f45812a75: (a: number, b: number, c: any) => [number, number];
-    readonly wasm_bindgen__convert__closures_____invoke__h03fb46086606eb61: (a: number, b: number, c: any, d: any) => void;
-    readonly wasm_bindgen__convert__closures_____invoke__hdd4256d54acb8ff1: (a: number, b: number, c: any) => void;
-    readonly wasm_bindgen__convert__closures_____invoke__hc7b60e1a5fd69b6e: (a: number, b: number) => void;
-    readonly wasm_bindgen__convert__closures_____invoke__h6f2d88ffbcba67ef: (a: number, b: number) => void;
-    readonly wasm_bindgen__convert__closures_____invoke__h32cbe4603be323e5: (a: number, b: number) => void;
-    readonly __wbindgen_malloc: (a: number, b: number) => number;
-    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
-    readonly __wbindgen_exn_store: (a: number) => void;
-    readonly __externref_table_alloc: () => number;
-    readonly __wbindgen_externrefs: WebAssembly.Table;
-    readonly __wbindgen_destroy_closure: (a: number, b: number) => void;
-    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
-    readonly __externref_table_dealloc: (a: number) => void;
-    readonly __externref_drop_slice: (a: number, b: number) => void;
-    readonly __wbindgen_start: () => void;
-}
-
-export type SyncInitInput = BufferSource | WebAssembly.Module;
-
-/**
- * Instantiates the given `module`, which can either be bytes or
- * a precompiled `WebAssembly.Module`.
- *
- * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
- *
- * @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.
- *
- * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
- *
- * @returns {Promise<InitOutput>}
- */
-export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;