docs(jans-cedarling): improve cedarling docs

docs/cedarling/cedarling-getting-started.md

@@ -0,0 +1,82 @@
+---
+tags:
+  - cedar
+  - cedarling
+  - getting-started
+---
+
+# Getting Started with Cedarling
+
+**Cedarling** is a lightweight, embeddable Policy Decision Point (PDP) that enables fast, fine-grained, and decentralized access control across modern applications. Built on the Rust-based [Cedar](https://cedarpolicy.com/) engine, Cedarling is designed for both client-side and server-side use, supporting environments like browsers, mobile apps, cloud-native services, and API gateways.
+
+Cedarling supports both [Token-Based Access Control (TBAC)](./cedarling-overview.md#token-based-access-control-tbac) using JWTs and unsigned authorization requests. In both cases, it enforces policies locally for low-latency and consistent Zero Trust security.
+
+You can integrate Cedarling into your application using the following language libraries:
+
+- [JavaScript](./getting-started/javascript.md)
+- [Python](./getting-started/python.md)
+- [Rust](./getting-started/rust.md)
+- [Kotlin](./getting-started/kotlin.md)
+- [Swift](./getting-started/swift.md)
+
+Alternatively, you can use the [Cedarling Sidecar](./cedarling-overview.md) for a drop-in deployment.
+
+From here, you can either jump directly to the language-specific examples above or continue reading for a high-level overview of how Cedarling works.
+
+---
+
+## Cedarling Interfaces
+
+The main way you will interact with Cedarling are through the following interfaces
+
+- [Initialization](#initialization)
+- [Authorization](#authorization)
+- [Logging](#logging)
+
+### Initialization
+
+The initialization or `init` interface is how you will initialize Cedarling. Initialization involves loading:
+
+**Bootstrap Configuration**
+- A set of properties that will tells how Cedarling behaves within your application.
+- Learn more in the [bootstrap properties guide](./cedarling-properties.md).
+
+**Policy Store**
+- A JSON file containing the schema, policies, trusted issuers, and token metadata schema used for making authorization decisions.
+- Learn more in the [policy store guide](./cedarling-policy-store.md).
+
+The bootstrap configuration and policy store directly influence how Cedarling performs [authorization](#authorization).
+
+
+### Authorization
+
+The authorization, or `authz`, interface is used to evaluate access control decisions by answering the question:
+
+> Is this **Action**, on this **Resource**, in this **Context**, allowed for these **Principals**?
+
+When using Cedarling, **Action** and **Resource** are typically defined in the [policy store](./cedarling-policy-store.md), while **Principal** and **Context** are supplied at runtime via the `authz` interface.
+
+Cedarling currently provides two modes of authorization:
+
+**Standard (Token-based) Interface**
+- Extracts the **Principal** from a JWT.
+- Accepts the **Context** as a structured map (format might vary by language).
+
+**Unsigned Authorization**
+- Accepts the **Principal** directly without requiring a JWT.
+- This makes authorization decisions by passing a set of **Principals** directly.
+- Similar to the standard interface, the **Context** is passed in as-is in a map-like structure.
+
+### Logging
+
+Cedarling supports logging of both **decision** and **system** events, useful for auditing and troubleshooting. Logging is optional and can be configured (or disabled) via the [bootstrap properties](./cedarling-properties.md).
+
+---
+
+## What's next?
+
+You're now ready to dive deeper into Cedarling. From here, you could either:
+
+- [Pick a language](#getting-started-with-cedarling) and start building with the Cedarling library.
+- Use the [Cedarling Sidecar](./cedarling-overview.md) for a quick, zero-code deployment.
+- Learn more about [why Cedarling exists](./cedarling-overview.md) and the problems it solves.

docs/cedarling/getting-started/javascript.md

@@ -0,0 +1,18 @@
+---
+tags:
+  - cedarling
+  - javascript
+  - getting-started
+---
+
+# Getting Started with Cedarling JavaScript
+
+The Janssen Project documentation is currently in development. Topic pages are being created in order of broadest relevance, and this page is coming in the near future.
+
+**Have questions in the meantime?**
+
+While this documentation is in progress, you can ask questions through [GitHub Discussions](https://github.com/JanssenProject/jans/discussions) or the [community chat on Gitter](https://gitter.im/JanssenProject/Lobby). Any questions you have will help determine what information our documentation should cover.
+
+**Want to contribute?**
+
+If you have content you'd like to contribute to this page in the meantime, you can get started with our [Contribution guide](https://docs.jans.io/head/CONTRIBUTING/).

docs/cedarling/getting-started/kotlin.md

@@ -0,0 +1,18 @@
+---
+tags:
+  - cedarling
+  - kotlin
+  - getting-started
+---
+
+# Getting Started with Cedarling Kotlin
+
+The Janssen Project documentation is currently in development. Topic pages are being created in order of broadest relevance, and this page is coming in the near future.
+
+**Have questions in the meantime?**
+
+While this documentation is in progress, you can ask questions through [GitHub Discussions](https://github.com/JanssenProject/jans/discussions) or the [community chat on Gitter](https://gitter.im/JanssenProject/Lobby). Any questions you have will help determine what information our documentation should cover.
+
+**Want to contribute?**
+
+If you have content you'd like to contribute to this page in the meantime, you can get started with our [Contribution guide](https://docs.jans.io/head/CONTRIBUTING/).

docs/cedarling/getting-started/python.md

@@ -0,0 +1,278 @@
+---
+tags:
+  - cedarling
+  - python
+  - getting-started
+---
+
+# Getting Started with Cedarling Python
+
+- [Installation](#installation)
+- [Usage](#usage)
+
+## Installation
+
+### Building from source
+
+The recommended way to use Cedarling in a Python project is by compiling a wheel using [Maturin](https://github.com/PyO3/maturin).
+
+**1. Set up a virtual environment**
+
+```sh
+python -m venv venv
+source venv/bin/activate
+```
+
+**2. Install `maturin`**
+
+```sh
+# for non-Linux systems
+pip install maturin
+
+# for Linux systems
+pip install maturin[patchelf]
+```
+
+**3. Clone the [jans](https://github.com/JanssenProject/jans) repository and navigate to the python bindings directory.**
+
+```sh
+git clone https://github.com/JanssenProject/jans.git jans
+cd jans/jans-cedarling/bindings/cedarling_python/
+```
+
+**Build the bindings**
+
+You have two options from here:
+
+**a. Build a wheel**
+
+```sh
+maturin build --release
+```
+
+This produces a `.whl` file in the `target/wheels/` directory.
+
+**b. Install into your virtual environment directly**
+
+```sh
+maturin develop
+```
+
+### Installation using `pip`
+
+Coming Soon...
+
+## Including in projects
+
+If you're using a dependency manager like [Poetry](https://python-poetry.org/), you can:
+
+**Option 1: Add the wheel via CLI**
+
+```
+poetry add path/to/wheel.whl
+```
+
+**Option 2: Install it manually into Poetry's virtual environment**
+
+```
+poetry run pip install path/to/wheel.whl
+```
+
+**Option 3: Add it to `pyproject.toml` statically**
+
+```
+[tool.poetry.dependencies]
+cedarling_python = {path = "path/to/wheel.whl"}
+```
+
+For other dependency managers, refer to their documentation on how to use local wheels.
+
+## Usage
+
+### Initialization
+
+```py
+# Load the bootstrap properties from the environment variable, using default values
+# for unset properties
+bootstrap_config = BootstrapConfig.from_env()
+
+# Initialize Cedarling
+cedarling = Cedarling(bootstrap_config)
+```
+
+See the python documentation for `BootstrapConfig` for other config loading options.
+
+### 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
+
+To perform an authorization check, follow these steps:
+
+**1. Prepare tokens**
+
+```py
+access_token = "<access_token>"
+id_token = "<id_token>"
+userinfo_token = "<userinfo_token>"
+```
+
+Your *principals* will be build from this tokens.
+
+**2. Define the resource**
+
+```py
+resource = EntityData(
+  entity_type="Jans::Application",
+  id="app_id_001",
+  name="App Name",
+  url={
+    "host": "example.com",
+    "path": "/admin-dashboard",
+    "protocol": "https"
+  }
+)
+```
+
+**3. Define the action**
+
+```py
+action = 'Jans::Action::"Read"'
+```
+
+**4. Define Context**
+
+```py
+context = {
+  "current_time": int(time.time()),
+  "device_health": ["Healthy"],
+  "fraud_indicators": ["Allowed"],
+  "geolocation": ["America"],
+  "network": "127.0.0.1",
+  "network_type": "Local",
+  "operating_system": "Linux",
+  "user_agent": "Linux"
+}
+```
+
+**5. Build the request**
+
+```py
+request = Request(
+  tokens={
+    "access_token": access_token,
+    "id_token": id_token,
+    "userinfo_token": userinfo_token,
+  },
+  action=action,
+  resource=resource,
+  context=context
+)
+```
+
+**6. Authorize**
+
+```py
+authorize_result = cedarling.authorize(request)
+```
+
+#### Unsigned Authorization
+
+In unsigned authorization, you pass a set of Principals directly, without relying on tokens. This can be useful when the application needs to perform authorization based on internal data, or when token-based data is not available.
+
+**1. Define the Principals**
+
+```py
+principals = [
+  EntityData(
+    entity_type="Jans::Workload",
+    id="some_workload_id",
+    client_id="some_client_id",
+  ),
+  EntityData(
+    entity_type="Jans::User",
+    id="random_user_id",
+    roles=["admin", "manager"]
+  ),
+]
+```
+
+**2. Define the Resource**
+
+This represents the *resource* that the action will be performed on, such as a protected API endpoint or file.
+
+```py
+resource = EntityData(
+  entity_type="Jans::Application",
+  id="app_id_001",
+  name="App Name",
+  url={
+    "host": "example.com",
+    "path": "/admin-dashboard",
+    "protocol": "https"
+  }
+)
+```
+
+**3. Define the Action**
+
+An *action* represents what the principal is trying to do to the resource. For example, read, write, or delete operations.
+
+```py
+action = 'Jans::Action::"Write"'
+```
+
+**4. Define the Context**
+
+The *context* represents additional data that may affect the authorization decision, such as time, location, or user-agent.
+
+```py
+context = {
+    "current_time": int(time.time()),
+    "device_health": ["Healthy"],
+    "location": "US",
+    "network": "127.0.0.1",
+    "operating_system": "Linux",
+}
+```
+
+**5. Build the Request**
+
+Now you'll construct the ***request*** by including the *principals*, *action*, and *context*.
+
+```py
+request = RequestUnsigned(
+  principals=principals,
+  action=action,
+  resource=resource,
+  context=context
+)
+```
+
+**6. Perform Authorization**
+
+Finally, call the `authorize` function to check whether the principals are allowed to perform the specified action on the resource.A
+
+```py
+result = cedarling.authorize_unsigned(request);
+```
+
+### Logging
+
+The logs could be retrieved using the `pop_logs` function.
+
+```py
+logs = cedarling.pop_logs()
+print(logs)
+```
+
+---
+
+## See Also
+
+- [Cedarling Sidecar Tutorial](../cedarling-sidecar-tutorial.md)
+