@janssenproject/cedarling_wasm 2.1.0-nodejs → 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.
      *