# Entscheidungsmarken

Wenn ein Checkpoint eine Terminalentscheidung erreicht, gibt Maetra eine **Entscheidungstoken** eine unterzeichnete JWT in `decision_token`. Es bindet die Entscheidung an den kanonischen Aktionsumschlag, die genauen Richtlinienversionen, den Arbeitsbereich und den beabsichtigten Executor.

Überprüfen Sie es lokal auf schnelle Ablehnung und konsumieren Sie es dann durch `POST /v1/executions/authorize` unmittelbar vor dem auswärtigen Handeln. Diese autoritative Überprüfung erzwingt Widerruf und One-Use-Semantik.

### Öffentliche Schlüssel (JWKS)

`GET /.well-known/jwks.json` — **keine Authentifizierung erforderlich.** Gibt den Schlüsselsatz zurück, der zum Signieren von Entscheidungstoken verwendet wurde. Einmal abrufen und Cache; der Token-Header `kid` Identifizieren Sie, welcher Schlüssel es signiert hat.

#### cURL

```bash
curl "https://api.maetra.io/.well-known/jwks.json" \
  -H "Authorization: Bearer $MAETRA_API_KEY"
```

#### JavaScript

```javascript
const res = await fetch("https://api.maetra.io/.well-known/jwks.json", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAETRA_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Maetra API ${res.status}`);
const data = await res.json();
console.log(data);
```

#### TypeScript

```typescript
const res = await fetch("https://api.maetra.io/.well-known/jwks.json", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAETRA_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Maetra API ${res.status}`);
const data = (await res.json());
```

#### Python

```python
import os, requests

res = requests.get(
    "https://api.maetra.io/.well-known/jwks.json",
    headers={"Authorization": f"Bearer {os.environ['MAETRA_API_KEY']}"},
)
res.raise_for_status()
print(res.json())
```

#### Rust

```rust
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key = std::env::var("MAETRA_API_KEY")?;
    let client = reqwest::Client::new();
    let res = client
        .get("https://api.maetra.io/.well-known/jwks.json")
        .bearer_auth(&key)
        .send()
        .await?;
    let data: serde_json::Value = res.json().await?;
    println!("{data:#}");
    Ok(())
}
```

#### C++

```cpp
#include <curl/curl.h>
#include <cstdlib>
#include <string>

int main() {
    CURL* curl = curl_easy_init();
    std::string auth = "Authorization: Bearer " + std::string(std::getenv("MAETRA_API_KEY"));
    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, auth.c_str());
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.maetra.io/.well-known/jwks.json");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_perform(curl);   // response is written to stdout by default
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}
```

#### Java

```java
import java.net.URI;
import java.net.http.*;

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.maetra.io/.well-known/jwks.json"))
    .header("Authorization", "Bearer " + System.getenv("MAETRA_API_KEY"))
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```


```json
{ "keys": [ { "kty": "OKP", "crv": "Ed25519", "alg": "EdDSA", "kid": "…", "x": "…" } ] }
```

### Überprüfung eines Tokens

Entscheidungstoken sind signiert mit **EdDSA mit Ed25519**. Überprüfen Sie mit einer JWT-Bibliothek, die Ed25519 und die JWKS oben unterstützt.

#### JavaScript / TypeScript

```typescript
import { jwtVerify, createRemoteJWKSet } from "jose";

const JWKS = createRemoteJWKSet(new URL("https://api.maetra.io/.well-known/jwks.json"));

export async function verifyDecision(token: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    algorithms: ["EdDSA"],
    issuer: "maetra-govern",
    audience: "payments-worker",
  });
  if (payload.status !== "approved" || payload.maxUses !== 1) {
    throw new Error(`Action not approved: ${payload.status}`);
  }
  return payload; // identifies the checkpoint, action, decision, and expiry
}
```

#### Python

```python
import jwt  # PyJWT
from jwt import PyJWKClient

jwks = PyJWKClient("https://api.maetra.io/.well-known/jwks.json")

def verify_decision(token: str) -> dict:
    key = jwks.get_signing_key_from_jwt(token).key
    payload = jwt.decode(token, key, algorithms=["EdDSA"], issuer="maetra-govern", audience="payments-worker")
    if payload.get("status") != "approved":
        raise ValueError(f"Action not approved: {payload.get('status')}")
    return payload
```

#### Go

```go
// Use github.com/lestrrat-go/jwx/v2/jwk + /jwt
keySet, _ := jwk.Fetch(ctx, "https://api.maetra.io/.well-known/jwks.json")
tok, err := jwt.Parse(raw, jwt.WithKeySet(keySet), jwt.WithValidate(true))
if err != nil { /* reject */ }
if status, _ := tok.Get("status"); status != "approved" {
    // do not perform the action
}
```


#### Was zu überprüfen ist

* **Unterschrift** — muss gegen einen Schlüssel in der JWKS validieren.
* **`status`** - nur dann vorgehen, wenn `approved`.
* **Verfallsdatum** Reject Expired Tokens (Standard) `exp`).
* **Emittent und Publikum** — erfordern `iss=maetra-govern` Und Ihr Executor ist genau `aud` Wert.
* **Bindend** Recomputing und Vergleich `actionEnvelopeHash`, dann vergleichen `checkpointId`, `workspaceId`, und `policyDigest`.
* **Verwendungsobergrenze** — erfordern `maxUses=1` und autorisieren Sie durch Maetra, so dass eine Wiederholung oder ein widerrufenes Token bei der Ausführung fehlschlägt.

> **Note**
> Behandeln Sie das Token als kurzlebige One-Use-Fähigkeit. `decision_token_expires_at` Grenzen des Tokens; Checkpoint `expires_at` ist das Genehmigungs-Timeout.