feat (jans-cedarling): Support new Policy Store ZIP format

docs/cedarling/reference/cedarling-policy-store.md

@@ -21,7 +21,242 @@ For a comprehensive JSON schema defining the structure of the policy store, see:
 
 **Note:** The `cedarling_store.json` file is only needed if the bootstrap properties: `CEDARLING_LOCK`; `CEDARLING_POLICY_STORE_URI`; and `CEDARLING_POLICY_STORE_ID` are not set to a local location. If you're fetching the policies remotely, you don't need a `cedarling_store.json` file.
 
-## JSON Schema
+## Policy Store Formats
+
+Cedarling supports two policy store formats and automatically detects the correct format based on file extension or URL:
+
+| Configuration | Detection |
+|---------------|-----------|
+| `CEDARLING_POLICY_STORE_URI` ending in `.cjar` | Cedar Archive from URL |
+| `CEDARLING_POLICY_STORE_URI` (other) | Legacy JSON from Lock Server |
+| `CEDARLING_POLICY_STORE_LOCAL_FN` pointing to directory | Directory-based format |
+| `CEDARLING_POLICY_STORE_LOCAL_FN` with `.cjar` extension | Cedar Archive file |
+| `CEDARLING_POLICY_STORE_LOCAL_FN` with `.json` extension | JSON file |
+| `CEDARLING_POLICY_STORE_LOCAL_FN` with `.yaml`/`.yml` extension | YAML file |
+
+### 1. Legacy Single-File Format (JSON/YAML)
+
+The original format stores all policies and schema in a single JSON or YAML file with Base64-encoded content. This is documented in detail in the sections below.
+
+### 2. New Directory-Based Format
+
+The new directory-based format uses human-readable Cedar files organized in a structured directory:
+
+```text
+policy-store/
+├── metadata.json           # Required: Store identification and versioning
+├── manifest.json           # Optional: File checksums for integrity validation
+├── schema.cedarschema      # Required: Cedar schema in human-readable format
+├── policies/               # Required: Directory containing .cedar policy files
+│   ├── allow-read.cedar
+│   └── deny-guest.cedar
+├── templates/              # Optional: Directory containing .cedar template files
+├── entities/               # Optional: Directory containing .json entity files
+└── trusted-issuers/        # Optional: Directory containing .json issuer configs
+```
+
+#### metadata.json
+
+Contains policy store identification and versioning:
+
+```json
+{
+  "cedar_version": "4.4.0",
+  "policy_store": {
+    "id": "abc123def456",
+    "name": "My Application Policies",
+    "description": "Optional description",
+    "version": "1.0.0",
+    "created_date": "2024-01-01T00:00:00Z",
+    "updated_date": "2024-01-02T00:00:00Z"
+  }
+}
+```
+
+#### manifest.json (Optional)
+
+Provides integrity validation with file checksums:
+
+```json
+{
+  "policy_store_id": "abc123def456",
+  "generated_date": "2024-01-01T12:00:00Z",
+  "files": {
+    "metadata.json": {
+      "size": 245,
+      "checksum": "sha256:abc123..."
+    },
+    "schema.cedarschema": {
+      "size": 1024,
+      "checksum": "sha256:def456..."
+    }
+  }
+}
+```
+
+When a manifest is present, Cedarling validates:
+
+- File checksums match (SHA-256)
+- File sizes match
+- Policy store ID matches between manifest and metadata
+
+#### Policy Files
+
+Policies are stored as human-readable `.cedar` files in the `policies/` directory:
+
+```cedar
+@id("allow-read")
+permit(
+    principal,
+    action == MyApp::Action::"read",
+    resource
+);
+```
+
+Each policy file must have an `@id` annotation that uniquely identifies the policy.
+
+#### Template Files
+
+Templates are stored as human-readable `.cedar` files in the `templates/` directory:
+
+```cedar
+@id("resource-access-template")
+permit(
+    principal == ?principal,
+    action,
+    resource == ?resource
+);
+```
+
+Each template file must have an `@id` annotation and use Cedar's template slot syntax (`?principal`, `?resource`).
+
+#### Entity Files
+
+Entity files in the `entities/` directory use the Cedar JSON entity format as a **JSON array**. Each file can contain one or more entity definitions:
+
+```json
+[
+  {
+    "uid": {
+      "type": "Jans::Organization",
+      "id": "acme-dolphins"
+    },
+    "attrs": {
+      "name": "Acme Dolphins Division",
+      "org_id": "100129",
+      "domain": "acme-dolphin.sea",
+      "regions": ["Atlantic", "Pacific", "Indian"]
+    },
+    "parents": []
+  },
+  {
+    "uid": {
+      "type": "Jans::Role",
+      "id": "admin"
+    },
+    "attrs": {
+      "name": "Administrator",
+      "permissions": ["read", "write", "delete"]
+    },
+    "parents": []
+  }
+]
+```
+
+Each entity requires:
+
+- **`uid`**: Object with `type` (Cedar entity type name, e.g., `"Jans::Organization"`) and `id` (unique entity identifier)
+- **`attrs`**: Object containing entity attributes matching your Cedar schema
+- **`parents`**: Optional array of parent entity references for hierarchical relationships
+
+Example with parent relationships (`entities/users.json`):
+
+```json
+[
+  {
+    "uid": {
+      "type": "Jans::User",
+      "id": "alice"
+    },
+    "attrs": {
+      "name": "Alice Smith",
+      "email": "alice@example.com"
+    },
+    "parents": [
+      {"type": "Jans::Role", "id": "admin"},
+      {"type": "Jans::Organization", "id": "acme-dolphins"}
+    ]
+  }
+]
+```
+
+#### Trusted Issuer Files
+
+Trusted issuer configuration files in the `trusted-issuers/` directory define identity providers that can issue tokens. Each file contains a JSON object mapping issuer IDs to their configurations:
+
+```json
+{
+  "jans_issuer": {
+    "name": "Jans Server",
+    "description": "Primary Janssen Identity Provider",
+    "openid_configuration_endpoint": "https://jans.example.com/.well-known/openid-configuration",
+    "token_metadata": {
+      "access_token": {
+        "trusted": true,
+        "entity_type_name": "Jans::Access_token",
+        "token_id": "jti",
+        "workload_id": "aud"
+      },
+      "id_token": {
+        "trusted": true,
+        "entity_type_name": "Jans::Id_token",
+        "user_id": "sub",
+        "role_mapping": "role"
+      }
+    }
+  }
+}
+```
+
+Each trusted issuer configuration includes:
+
+- **`name`**: Human-readable name for the issuer (used as namespace for `TrustedIssuer` entity)
+- **`description`**: Optional description of the issuer
+- **`openid_configuration_endpoint`**: HTTPS URL for the OpenID Connect discovery endpoint
+- **`token_metadata`**: Map of token types to their metadata configuration (see [Token Metadata Schema](#token-metadata-schema))
+
+You can define multiple issuers in a single file or split them across multiple files in the `trusted-issuers/` directory.
+
+#### Cedar Archive (.cjar) Format
+
+The directory structure can be packaged as a `.cjar` file (ZIP archive) for distribution:
+
+```bash
+# Create a .cjar archive from a policy store directory
+cd policy-store && zip -r ../policy-store.cjar .
+```
+
+**Note:** In WASM environments, only URL-based and inline string sources are available. Use `CEDARLING_POLICY_STORE_URI` with a `.cjar` URL or `init_from_archive_bytes()` for custom fetch scenarios.
+
+## Advanced: Loading from Bytes
+
+For scenarios requiring custom fetch logic (e.g., auth headers), archive bytes can be loaded directly:
+
+- **WASM**: Use `init_from_archive_bytes(config, bytes)` function
+- **Rust**: Use `PolicyStoreSource::ArchiveBytes(Vec<u8>)` or `load_policy_store_archive_bytes()` function
+
+```javascript
+// WASM example with custom fetch
+const response = await fetch(url, { headers: { Authorization: "..." } });
+const bytes = new Uint8Array(await response.arrayBuffer());
+const cedarling = await init_from_archive_bytes(config, bytes);
+```
+
+## Legacy Single-File Format (JSON)
+
+The following sections document the legacy single-file JSON format.
+
+### JSON Schema
 
 The JSON Schema accepted by Cedarling is defined as follows:
 
@@ -510,9 +745,9 @@ entity Tokens = {
 
 The naming follows this pattern:
 
-- **Issuer name**: From trusted issuer metadata `name` field, or hostname from JWT `iss` claim  
-- **Token type**: Extracted from the `mapping` field (e.g., "Jans::Access_Token" → "access_token")  
-- Both converted to lowercase with underscores replacing special characters  
+- **Issuer name**: From trusted issuer metadata `name` field, or hostname from JWT `iss` claim
+- **Token type**: Extracted from the `mapping` field (e.g., "Jans::Access_Token" → "access_token")
+- Both converted to lowercase with underscores replacing special characters
 
 ### Schema Requirements for Multi-Issuer
 

docs/cedarling/reference/cedarling-properties.md

@@ -26,12 +26,24 @@ To load policy store one of the following keys must be provided:
 
 - **`CEDARLING_POLICY_STORE_LOCAL`** : JSON object as string with policy store. You can use [this](https://jsontostring.com/) converter.
 
-- **`CEDARLING_POLICY_STORE_URI`** : Location of policy store JSON, used if policy store is not local, or retrieved from Lock Master.
+- **`CEDARLING_POLICY_STORE_URI`** : URL to fetch policy store from. Cedarling automatically detects the format:
+  - URLs ending in `.cjar` → loads as Cedar Archive
+  - Other URLs → loads as legacy JSON from Lock Server
 
-- **`CEDARLING_POLICY_STORE_LOCAL_FN`** : Path to a Policy Store JSON file
+- **`CEDARLING_POLICY_STORE_LOCAL_FN`** : Path to local policy store. Cedarling automatically detects the format:
+  - Directories → loads as directory-based policy store
+  - `.cjar` files → loads as Cedar Archive
+  - `.json` files → loads as JSON
+  - `.yaml`/`.yml` files → loads as YAML
+
+**New Directory-Based Format** (Native platforms only):
+
+Cedarling now supports a directory-based policy store format with human-readable Cedar files. See [Policy Store Formats](./cedarling-policy-store.md#policy-store-formats) for details.
+
+**Note:** In WASM environments, only `CEDARLING_POLICY_STORE_URI` and `CEDARLING_POLICY_STORE_LOCAL` are available. File and directory sources (`CEDARLING_POLICY_STORE_LOCAL_FN`) are not supported in WASM due to lack of filesystem access.
 
 !!! NOTE
-    All other fields are optional and can be omitted. If a field is not provided, Cedarling will use the default value specified in the property definition.
+All other fields are optional and can be omitted. If a field is not provided, Cedarling will use the default value specified in the property definition.
 
 **Auxilliary properties**
 

docs/cedarling/tutorials/go.md

@@ -13,8 +13,8 @@ Go bindings for the Jans Cedarling authorization engine, providing policy-based
 
 ### Build with dynamic linking
 
-1. Download the appropriate pre-built binary for your platform from the Jans releases page or build it from source as 
-described above.
+1. Download the appropriate pre-built binary for your platform from the Jans releases page or build it from source as
+   described above.
 
 2. Specify linker flags in your main.go file to link against the Cedarling library.
 
@@ -42,14 +42,14 @@ described above.
     - **Windows**
 
         - Place the Rust artifacts (`cedarling_go.dll` and `cedarling_go.lib`) alongside the Go binary.
-        - Windows searches libraries in directories below in the 
+        - Windows searches libraries in directories below in the
           following order
             1. The directory containing your Go executable (recommended location)
             2. Windows system directories (e.g., `C:\Windows\System32`)
             3. The `PATH` environment variable directories
 
     - **Linux**
-    
+
         Add the library directory that contains `libcedarling_go.so` to the
         `LD_LIBRARY_PATH` environment variable
 
@@ -58,10 +58,10 @@ described above.
         ```
 
     - **MacOS**
-        
+
         Add the library directory that contains `libcedarling_go.dylib` to the
         `LD_LIBRARY_PATH` environment variable
-        
+
         ```sh
         export DYLD_LIBRARY_PATH=$(pwd):$DYLD_LIBRARY_PATH
         ```
@@ -147,14 +147,44 @@ if err != nil {
 }
 ```
 
+### Policy Store Sources
+
+Go bindings support all native policy store source types. See [Cedarling Properties](../reference/cedarling-properties.md) for the full list of configuration options.
+
+**Example configurations:**
+
+```go
+// Load from a directory
+config := map[string]any{
+    "CEDARLING_APPLICATION_NAME":      "MyApp",
+    "CEDARLING_POLICY_STORE_LOCAL_FN": "/path/to/policy-store/",
+    // ... other config
+}
+
+// Load from a local .cjar archive (Cedar Archive)
+config := map[string]any{
+    "CEDARLING_APPLICATION_NAME":      "MyApp",
+    "CEDARLING_POLICY_STORE_LOCAL_FN": "/path/to/policy-store.cjar",
+    // ... other config
+}
+
+// Load from a remote .cjar archive (Cedar Archive)
+config := map[string]any{
+    "CEDARLING_APPLICATION_NAME":   "MyApp",
+    "CEDARLING_POLICY_STORE_URI":   "https://example.com/policy-store.cjar",
+    // ... other config
+}
+```
+
+See [Policy Store Formats](../reference/cedarling-policy-store.md#policy-store-formats) for more details.
+
 ### Authorization
 
 Cedarling provides two main interfaces for performing authorization checks: **Token-Based Authorization** and **Unsigned Authorization**. Both methods involve evaluating access requests based on various factors, including principals (entities), actions, resources, and context. The difference lies in how the Principals are provided.
 
 - [**Token-Based Authorization**](#token-based-authorization) is the standard method where principals are extracted from JSON Web Tokens (JWTs), typically used in scenarios where you have existing user authentication and authorization data encapsulated in tokens.
 - [**Unsigned Authorization**](#unsigned-authorization) allows you to pass principals directly, bypassing tokens entirely. This is useful when you need to authorize based on internal application data, or when tokens are not available.
 
-
 #### Token-Based Authorization
 
 **1. Define the resource:**
@@ -318,10 +348,10 @@ if err != nil {
 if result.Decision {
     fmt.Println("Access granted")
     fmt.Printf("Request ID: %s\n", result.RequestID)
-    
+
     // Access detailed Cedar response
     fmt.Printf("Cedar decision: %s\n", result.Response.Decision().ToString())
-    
+
     // Get diagnostic information
     diagnostics := result.Response.Diagnostics()
     if len(diagnostics.Reason()) > 0 {