Cedarling JavaScript/TypeScript API
    Preparing search index...

    Class Cedarling

    The instance of the Cedarling application.

    Index
    • Returns void

    • Return the annotations of each given policy, grouped by policy ID. It is the loss-free companion to annotationsMap. 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

      const byPolicy = cedarling.annotationsByPolicy(result.response.diagnostics.reason);
      // { "5": { redirect: "/upgrade", tier: "premium" } }

      Parameters

      • policy_ids: string[]

      Returns 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 annotationValues / annotationsByPolicy 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

      const annotations = cedarling.annotationsMap(result.response.diagnostics.reason);
      // { redirect: "/upgrade", tier: "premium" }

      Parameters

      • policy_ids: string[]

      Returns any

    • 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

      const redirects = cedarling.annotationValues(
      result.response.diagnostics.reason,
      "redirect",
      );
      // ["/upgrade"]

      Parameters

      • policy_ids: string[]
      • key: string

      Returns string[]

    • Authorize multi-issuer request. Makes authorization decision based on multiple JWT tokens from different issuers.

      Arguments

      • request - JSON string representation of [AuthorizeMultiIssuerRequest].

      Example

      const result = await cedarling.authorizeMultiIssuer(JSON.stringify(request));
      

      Parameters

      • request: string

      Returns 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

      const result = await cedarling.authorizeMultiIssuerBatch(JSON.stringify(batchRequest));
      

      Parameters

      • request: string

      Returns Promise<BatchAuthorizeMultiIssuerResponse>

    • Authorize an unsigned request carrying an optional single principal. Makes an authorization decision based on the [RequestUnsigned].

      When principal is omitted / null on the JS side the core uses Cedar 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

      const result = await cedarling.authorizeUnsigned(JSON.stringify(request));
      

      Parameters

      • request: string

      Returns 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

      const result = await cedarling.authorizeUnsignedBatch(JSON.stringify(batchRequest));
      

      Parameters

      • request: string

      Returns Promise<BatchAuthorizeUnsignedResponse>

    • Clear all entries from the data store.

      Arguments

      None.

      Example

      cedarling.clearDataCtx();
      console.log("All data entries cleared");

      Returns void

    • Destructive read: returns the telemetry metrics snapshot and resets the counters for the next interval.

      Fails when CEDARLING_METRICS_COLLECTION is disabled or whenever CEDARLING_LOCK_TELEMETRY_INTERVAL is set (even if the Lock server has no telemetry endpoint). interval_secs is fractional seconds, so sub-second intervals are reported exactly.

      Example

      const snapshot = cedarling.drainMetrics();
      console.log(`Requests: ${snapshot.operational_stats.get("authz.requests_total")}`);

      Returns MetricsSnapshot

    • Get trusted issuer identifiers that failed to load.

      Arguments

      None.

      Example

      const ids = cedarling.failedTrustedIssuerIds();
      

      Returns any[]

    • Returns 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 - A string key for the data entry to retrieve

      Example

      const value = cedarling.getDataCtx("user:123");
      if (value !== null) {
      console.log(value.name); // "John"
      }

      Parameters

      • key: string

      Returns any

    • Get a data entry with full metadata by key. Returns undefined if the key doesn't exist or the entry has expired.

      Arguments

      • key - A string key for the data entry to retrieve

      Example

      const entry = cedarling.getDataEntryCtx("user:123");
      if (entry !== undefined) {
      console.log(entry.key); // "user:123"
      console.log(entry.value()); // { name: "John", age: 30 }
      console.log(entry.data_type); // "Record"
      console.log(entry.created_at); // "2024-01-01T12:00:00Z"
      console.log(entry.access_count); // 5
      }

      Parameters

      • key: string

      Returns DataEntry | undefined

    • Returns one retained memory log by ID, or null when it is not retained.

      Arguments

      • id - The retained log identifier.

      Example

      const log = cedarling.getLogById("request-id");
      

      Parameters

      • id: string

      Returns any

    • Returns identifiers for all retained memory logs.

      Arguments

      None.

      Example

      const ids = cedarling.getLogIds();
      

      Returns any[]

    • Returns retained memory logs for one request ID.

      Arguments

      • requestId - The request identifier to match.

      Example

      const logs = cedarling.getLogsByRequestId("request-id");
      

      Parameters

      • request_id: string

      Returns any[]

    • Returns retained memory logs matching one request ID and indexed value.

      Arguments

      • requestId - The request identifier to match.
      • tag - A log kind ("System", "Decision", or "Metric") or a system-log level such as "DEBUG".

      Example

      const logs = cedarling.getLogsByRequestIdAndTag("request-id", "System");
      

      Parameters

      • request_id: string
      • tag: string

      Returns any[]

    • Returns retained memory logs matching an indexed value.

      Arguments

      • tag - A log kind ("System", "Decision", or "Metric") or a system-log level such as "DEBUG".

      Example

      const logs = cedarling.getLogsByTag("System");
      

      Parameters

      • tag: string

      Returns any[]

    • Get statistics about the data store.

      Arguments

      None.

      Example

      const stats = cedarling.getStatsCtx();
      console.log(`Entries: ${stats.entry_count}/${stats.max_entries || 'unlimited'}`);
      console.log(`Capacity: ${stats.capacity_usage_percent.toFixed(2)}%`);
      console.log(`Total size: ${stats.total_size_bytes} bytes`);

      Returns DataStoreStats

    • Check whether a trusted issuer was loaded by iss claim.

      Arguments

      • iss_claim - Issuer iss claim value to check.

      Example

      const ok = cedarling.isTrustedIssuerLoadedByIss("https://issuer.example.org");
      

      Parameters

      • iss_claim: string

      Returns boolean

    • Check whether a trusted issuer was loaded by name.

      Arguments

      • issuer_name - The issuer name, the issuer of its token types.

      Example

      const ok = cedarling.isTrustedIssuerLoadedByName("Acme");
      

      Parameters

      • issuer_name: string

      Returns boolean

    • List all entries with their metadata. Returns an array of DataEntry objects.

      Arguments

      None.

      Example

      const entries = cedarling.listDataCtx();
      entries.forEach(entry => {
      console.log(`${entry.key}: ${entry.data_type} (accessed ${entry.access_count} times)`);
      });

      Returns any[]

    • Get trusted issuer identifiers loaded successfully.

      Arguments

      None.

      Example

      const ids = cedarling.loadedTrustedIssuerIds();
      

      Returns any[]

    • Get the number of trusted issuers loaded successfully.

      Arguments

      None.

      Example

      const loadedCount = cedarling.loadedTrustedIssuersCount();
      

      Returns number

    • Get the ID of the currently published policy store, if it carries one.

      undefined means the store carries no ID. The value is an opaque, source-dependent string; it may change after a background refresh.

      Arguments

      None.

      Example

      const id = cedarling.policyStoreId();
      

      Returns string | undefined

    • Returns all retained memory logs and removes them from storage. Other log configurations return an empty array.

      Arguments

      None.

      Example

      const logs = cedarling.popLogs();
      

      Returns 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 - A string key for the data entry (must not be empty)
      • value - The value to store (any JSON-serializable JavaScript value: object, array, string, number, boolean)
      • ttl_secs - Optional TTL in seconds (undefined/null uses default from config)

      Example

      cedarling.pushDataCtx("user:123", { name: "John", age: 30 }, 3600);
      cedarling.pushDataCtx("config", { setting: "value" }); // Uses default TTL

      Parameters

      • key: string
      • value: any
      • Optionalttl_secs: bigint | null

      Returns void

    • Remove a value from the data store by key. Returns true if the key existed and was removed, false otherwise.

      Arguments

      • key - A string key for the data entry to remove

      Example

      const removed = cedarling.removeDataCtx("user:123");
      if (removed) {
      console.log("Entry was successfully removed");
      }

      Parameters

      • key: string

      Returns boolean

    • Closes Lock Server connections and pushes all available logs.

      Arguments

      None.

      Example

      await cedarling.shutDown();
      

      Returns Promise<void>

    • Get the total number of trusted issuer entries discovered.

      Arguments

      None.

      Example

      const total = cedarling.totalIssuers();
      

      Returns number

    • Creates a Cedarling application from bootstrap properties.

      Arguments

      • config - A plain object of Cedarling bootstrap-property names and values.

      Example

      await initWasm();
      const cedarling = await Cedarling.new({
      CEDARLING_APPLICATION_NAME: "task-api",
      CEDARLING_POLICY_STORE_URI: "https://example.com/policy-store.cjar",
      CEDARLING_LOG_TYPE: "memory",
      CEDARLING_LOG_TTL: 120,
      });

      Parameters

      • config: object

      Returns Promise<Cedarling>

    • Creates a new Cedarling application from a JavaScript Map.

      Arguments

      • config - A Map of Cedarling bootstrap-property names and values.

      Example

      await initWasm();
      const cedarling = await Cedarling.newFromMap(new Map([
      ["CEDARLING_APPLICATION_NAME", "task-api"],
      ["CEDARLING_POLICY_STORE_URI", "https://example.com/policy-store.cjar"],
      ["CEDARLING_LOG_TYPE", "memory"],
      ["CEDARLING_LOG_TTL", 120],
      ]));

      Parameters

      • config: Map<any, any>

      Returns Promise<Cedarling>