@jaimevalasek/aioson 1.30.1 → 1.30.2

package/template/.aioson/docs/play/README.md

@@ -60,6 +60,7 @@ AIOSON can build any kind of app. Apply this Play compatibility layer only when
 - Data Bindings and Global Connectors via `app-config.yaml`
 - MCPI/API/MCP connector execution through the Play registry
 - Local operator auth via `aioson-auth` and `@aioson/auth-sdk`
+- App-owned RBAC catalog via `manifest.json` `auth.permissions[]`
 - Cloud owner/trial auth via `AIOSON_COM_TOKEN`
 - Play Services via `service.json` and `requires_services`
 - Dev-link and local smoke testing
@@ -69,4 +70,5 @@ AIOSON can build any kind of app. Apply this Play compatibility layer only when
 - Do not copy the whole Play integration directory into app projects.
 - Do not make apps depend on source-repo-only files from `aioson-play`.
 - Do not invent Play env vars, port ranges, manifest fields, or connector APIs.
+- Do not infer app permissions by scanning source code; Play apps declare the catalog in `manifest.json` `auth.permissions[]`.
 - Do not treat `llm-chain.json` or `aioson-models.json` in the app cwd as the primary credential contract for installed apps.

package/template/.aioson/docs/play/agent-usage-guide.md

@@ -26,6 +26,7 @@ Load this folder when the user mentions:
 - `manifest.json` for Play apps
 - `app-config.yaml`
 - `requires_services`
+- `auth.permissions`
 - `/api/aioson-play`
 
 Do not load it for generic web apps unless the user connects the app to Play.
@@ -61,7 +62,7 @@ For a Play-targeted app, answer these before creating files:
 
 4. Does the app need users/operators?
    - Owner/trial/billing: use `AIOSON_COM_TOKEN` and backend proxy routes.
-   - Local operators/RBAC: use `aioson-auth` as Play Service and `@aioson/auth-sdk`.
+   - Local operators/RBAC: use `aioson-auth` as Play Service, declare `manifest.json` `auth.permissions[]`, and use `@aioson/auth-sdk`.
    - No auth: do not add login just because it is a Play app.
 
 ## Source priority
@@ -81,6 +82,8 @@ Use this priority order:
 - Do not put provider API keys in `llm-chain.json`, `tools.json`, manifest, app docs, or frontend code.
 - Do not make browser code call `https://aioson.com` directly with a token.
 - Do not treat `aioson-auth` and `aioson.com` auth as the same system.
+- Do not create app permissions only in the Auth dashboard. For Play apps, the app declares the permission catalog in `manifest.json` `auth.permissions[]`; the dashboard assigns those permissions to roles.
+- Do not ask Auth or Play to scan source code for policies/permissions.
 - Do not add `@tauri-apps/api` to Play Services. Services are standalone background processes.
 - Do not assume SSO operator token injection is implemented unless the canonical Play docs and code confirm it.
 
@@ -94,6 +97,8 @@ For implementation, produce or verify:
 - `/api/aioson-play` when `has_api: true`
 - Lazy LLM client initialization when the app uses LLM providers
 - Degraded state when required bindings are absent
+- `manifest.json` `auth.permissions[]` when the app uses `aioson-auth`
+- Frontend/backend permission gates implemented with `@aioson/auth-sdk`
 - Local smoke steps through dev-link or standalone `PORT=...` run
 
 For QA, verify:
@@ -103,4 +108,5 @@ For QA, verify:
 - No secret in frontend or package artifact
 - Data bindings use alias names that match `app-config.yaml`
 - Auth path uses the right system: `aioson-auth` for operators, `aioson.com` for owner/trial
+- Apps using `aioson-auth` declare permissions in `manifest.json`, and those declared permissions match implemented route/API gates.
 - `manifest.compatibility` exists for publishable apps

package/template/.aioson/docs/play/app-compatibility-guide.md

@@ -42,6 +42,7 @@ If the app has a UI, the Play webview must be able to load the UI from the proce
 - Use `http://localhost:5180` or `VITE_AIOSON_PLAY_URL` for ProductBridge calls.
 - Use `GET /api/registry` when discovering other apps or services dynamically.
 - Use `requires_services` for Play Service dependencies.
+- If the app uses `aioson-auth`, declare the permission catalog in `manifest.json` `auth.permissions[]` and implement matching gates in the app with `@aioson/auth-sdk`.
 - Keep app-local operational DB separate from Play Global Connectors.
 - Fail clearly or degrade gracefully when optional Play integrations are absent.
 
@@ -53,6 +54,8 @@ If the app has a UI, the Play webview must be able to load the UI from the proce
 - Do not create a UI inside the app for creating global Database Connections or Data Connectors. Those live in Play Settings.
 - Do not put LLM provider secrets in files shipped with the app.
 - Do not call cloud APIs from browser code with `AIOSON_COM_TOKEN`.
+- Do not rely on Auth/Play scanning source code to discover permissions.
+- Do not create app permissions only in the Auth dashboard for manifest-driven Play apps.
 
 ## Implementation sequence
 
@@ -61,7 +64,7 @@ If the app has a UI, the Play webview must be able to load the UI from the proce
 3. Make every server listen on Play-injected env ports.
 4. Add `GET /api/aioson-play` if the app exposes API capabilities.
 5. Add `app-config.yaml` for operational DB defaults and/or `data_bindings`.
-6. Add Play auth only if the app needs it.
+6. Add Play auth only if the app needs it; include `requires_services: ["aioson-auth"]`, `auth.permissions[]`, and SDK gates.
 7. Add local smoke tests and dev-link run instructions.
 
 ## Ready-for-Play checklist
@@ -77,6 +80,8 @@ If the app has a UI, the Play webview must be able to load the UI from the proce
 - [ ] App handles missing bindings with degraded UI or a clear blocking state.
 - [ ] LLM clients are lazy-initialized and read credentials from app config or injected env vars.
 - [ ] Auth uses the correct path: `aioson-auth` for operators/RBAC, `aioson.com` for owner/trial/billing.
+- [ ] Apps using `aioson-auth` declare `manifest.json` `auth.permissions[]`.
+- [ ] Declared permissions match frontend/backend gates implemented by the app.
 - [ ] Publishable apps declare `manifest.compatibility`.
 - [ ] Dev-link smoke was run inside Play or the app was manually started with a test `PORT`.
 

package/template/.aioson/docs/play/auth-services-and-testing.md

@@ -57,10 +57,22 @@ For operator login and RBAC, depend on `aioson-auth`:
 
 ```json
 {
-  "requires_services": ["aioson-auth"]
+  "requires_services": ["aioson-auth"],
+  "auth": {
+    "version": 1,
+    "permissions": ["orders:read", "orders:create"],
+    "policies": [
+      { "id": "page:orders", "kind": "route", "path": "/orders", "requires": ["orders:read"] }
+    ]
+  }
 }
 ```
 
+`auth.permissions[]` is the app-owned permission catalog. Play syncs it through
+the owner-only app inventory; `aioson-auth` registers it on the existing binding
+so the admin can assign permissions to global roles. Do not rely on Auth scanning
+app source code.
+
 Use `@aioson/auth-sdk` as the client layer when available. Avoid handwritten calls to auth endpoints unless the SDK cannot cover the specific case.
 
 Env vars Play injects for auth (only these exist):
@@ -83,6 +95,7 @@ Legacy `?token=` may still work in older paths, but new app code should prefer B
 Current implemented auth expectations from the Play docs:
 
 - JWT can include `binding_id` and `permissions`.
+- App permissions are declared in `manifest.json` `auth.permissions[]` and implemented by the app with SDK gates.
 - `/me/permissions` exists in `aioson-auth`.
 - `@aioson/auth-sdk` MVP exists.
 - Operator SSO token injection from Play keyring is planned in docs, not safe to rely on unless the local code confirms it.
@@ -199,6 +212,8 @@ curl http://localhost:3001/health
 ## QA checklist
 
 - [ ] `requires_services` matches actual service use.
+- [ ] Apps using `aioson-auth` declare `auth.permissions[]` in `manifest.json`.
+- [ ] Frontend and backend gates use `@aioson/auth-sdk` or a Bearer-compatible server check for those permissions.
 - [ ] Missing service does not produce a confusing crash.
 - [ ] `AIOSON_COM_TOKEN` is never exposed to frontend code.
 - [ ] Operator auth uses SDK or Bearer-compatible client.

package/template/.aioson/docs/play/manifest-and-runtime.md

@@ -209,6 +209,29 @@ When an app requires a Play Service:
 
 Play uses this to show onboarding requirements, check service install/runtime state, and block or degrade app launch when the required service is missing.
 
+For apps that use `aioson-auth`, declare the RBAC catalog in the same manifest:
+
+```json
+{
+  "requires_services": ["aioson-auth"],
+  "auth": {
+    "version": 1,
+    "permissions": [
+      "orders:read",
+      { "name": "orders:create", "label": "Criar pedidos" }
+    ],
+    "policies": [
+      { "id": "page:orders", "kind": "route", "path": "/orders", "requires": ["orders:read"] }
+    ]
+  }
+}
+```
+
+`auth.permissions[]` is the source of truth for the permission catalog shown by
+`aioson-auth`. The app still implements the actual route/API gates with the SDK;
+the Auth dashboard assigns the declared permissions to global roles. Play/Auth do
+not scan app source code to infer permissions.
+
 ## Publish compatibility
 
 Publishable apps should declare compatibility: