mirror of
https://github.com/AeThex-Corporation/AeThex-OS.git
synced 2026-04-18 06:17:21 +00:00
147 lines
3.4 KiB
Markdown
147 lines
3.4 KiB
Markdown
# Entitlements Quickstart
|
|
|
|
This guide helps you set up the OS Kernel (identity + entitlements) and use the API to issue, verify, resolve, and revoke entitlements.
|
|
|
|
## 1) Run OS Kernel Migration
|
|
|
|
Ensure `DATABASE_URL` is set in your environment (Railway/Supabase Postgres). Then run the OS Kernel migration. You can do this either from the dev shell or the in-app Terminal (Admin only).
|
|
|
|
- Dev shell:
|
|
- `npx ts-node script/run-os-migration.ts`
|
|
- In-app Terminal:
|
|
- Command: `migrate-os` (now available in the command dropdown)
|
|
|
|
This creates tables:
|
|
- `aethex_subjects`, `aethex_subject_identities`
|
|
- `aethex_issuers`, `aethex_issuer_keys`
|
|
- `aethex_entitlements`, `aethex_entitlement_events`
|
|
- `aethex_audit_log`
|
|
|
|
## 2) Create an Issuer
|
|
|
|
Insert an issuer record with a `public_key` and optional metadata. You can use SQL or your DB console (Supabase) for now.
|
|
|
|
Example SQL:
|
|
|
|
```sql
|
|
INSERT INTO public.aethex_issuers (name, issuer_class, scopes, public_key, is_active)
|
|
VALUES ('AeThex Platform', 'platform', '["issue","revoke"]'::json, 'PUBLIC_KEY_STRING', true)
|
|
RETURNING id;
|
|
```
|
|
|
|
Save the returned `id` as your `issuer_id`.
|
|
|
|
## 3) Issue an Entitlement
|
|
|
|
Endpoint: `POST /api/os/entitlements/issue`
|
|
|
|
Headers:
|
|
- `x-issuer-id: <issuer_id>`
|
|
|
|
Body:
|
|
```json
|
|
{
|
|
"subject_id": "<optional: internal subject id>",
|
|
"external_subject_ref": "roblox:12345",
|
|
"entitlement_type": "achievement",
|
|
"scope": "project",
|
|
"data": { "name": "Alpha Access" },
|
|
"expires_at": null
|
|
}
|
|
```
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"entitlement": {
|
|
"id": "...",
|
|
"type": "achievement",
|
|
"scope": "project",
|
|
"created_at": "..."
|
|
}
|
|
}
|
|
```
|
|
|
|
## 4) Verify an Entitlement
|
|
|
|
Endpoint: `POST /api/os/entitlements/verify`
|
|
|
|
Body:
|
|
```json
|
|
{ "entitlement_id": "..." }
|
|
```
|
|
|
|
Response (valid):
|
|
```json
|
|
{
|
|
"valid": true,
|
|
"entitlement": {
|
|
"id": "...",
|
|
"type": "achievement",
|
|
"scope": "project",
|
|
"data": { "name": "Alpha Access" },
|
|
"issuer": { "id": "...", "name": "AeThex Platform", "class": "platform" },
|
|
"issued_at": "...",
|
|
"expires_at": null
|
|
}
|
|
}
|
|
```
|
|
|
|
Response (revoked/expired):
|
|
```json
|
|
{ "valid": false, "reason": "revoked|expired", ... }
|
|
```
|
|
|
|
## 5) Resolve Entitlements (by subject or external ref)
|
|
|
|
Endpoint: `GET /api/os/entitlements/resolve`
|
|
|
|
Query params (choose one path):
|
|
- `?subject_id=<internal_subject_id>`
|
|
- `?platform=roblox&id=12345`
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"entitlements": [
|
|
{
|
|
"id": "...",
|
|
"type": "achievement",
|
|
"scope": "project",
|
|
"data": { "name": "Alpha Access" },
|
|
"issuer": { "name": "AeThex Platform", "class": "platform" },
|
|
"issued_at": "...",
|
|
"expires_at": null
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## 6) Revoke an Entitlement
|
|
|
|
Endpoint: `POST /api/os/entitlements/revoke`
|
|
|
|
Headers:
|
|
- `x-issuer-id: <issuer_id>`
|
|
|
|
Body:
|
|
```json
|
|
{ "entitlement_id": "...", "reason": "Fraudulent use" }
|
|
```
|
|
|
|
Response:
|
|
```json
|
|
{ "success": true, "message": "Entitlement revoked" }
|
|
```
|
|
|
|
## Notes
|
|
- All OS routes are protected by the capability guard and expect authenticated context where relevant.
|
|
- Use Supabase console to inspect tables and audit logs.
|
|
- For production, plan issuer key rotation via `aethex_issuer_keys`; rotation endpoints can be added similarly.
|
|
|
|
### Bot Integration Env (for external bots)
|
|
Add these to your bot repo (not the OS) so it can call the OS API:
|
|
- AETHEX_API_BASE=`https://<your-os-host>`
|
|
- AETHEX_ISSUER_ID=`<issuer_id from step 2>`
|
|
- AETHEX_REALM=`foundation` (optional; foundation already has required capabilities)
|