@geolonia/geonicdb-cli 0.7.0 → 0.8.0

package/README.md

@@ -193,14 +193,37 @@ Displays the current authenticated user, token expiry, and active profile.
 |---|---|
 | `me oauth-clients list` | List your OAuth clients |
 | `me oauth-clients create [json]` | Create a new OAuth client |
+| `me oauth-clients update <clientId> [json]` | Update an OAuth client |
+| `me oauth-clients regenerate-secret <clientId>` | Regenerate client secret |
 | `me oauth-clients delete <id>` | Delete an OAuth client |
 
+`me oauth-clients create` supports flag options: `--name`, `--policy`, `--save`. Use `--save` to store client credentials in config for automatic re-authentication.
+
+`me oauth-clients update` supports: `--name`, `--description`, `--policy-id` (use `null` to unbind), `--active`, `--inactive`.
+
+```bash
+# Create with flags
+geonic me oauth-clients create --name my-ci-bot --policy <policy-id>
+
+# Create from JSON (note: field is "name", not "clientName")
+geonic me oauth-clients create '{"name":"my-bot","policyId":"<policy-id>"}'
+
+# Attach a personal policy
+geonic me oauth-clients update <client-id> --policy-id my-readonly
+
+# Unbind policy
+geonic me oauth-clients update <client-id> --policy-id null
+```
+
+**Note**: `--policy-id` on update accepts only policies created by yourself (`/me/policies`). Policies created via `admin policies` cannot be bound here.
+
 #### me api-keys
 
 | Subcommand | Description |
 |---|---|
 | `me api-keys list` | List your API keys |
 | `me api-keys create [json]` | Create a new API key |
+| `me api-keys update <keyId> [json]` | Update an API key |
 | `me api-keys delete <keyId>` | Delete an API key |
 
 `me api-keys create` supports flag options:
@@ -208,27 +231,61 @@ Displays the current authenticated user, token expiry, and active profile.
 | Flag | Description |
 |---|---|
 | `--name <name>` | Key name |
-| `--scopes <scopes>` | Allowed scopes (comma-separated) |
+| `--policy <policyId>` | Policy ID to attach (XACML policy) |
 | `--origins <origins>` | Allowed origins (comma-separated, at least 1 required) |
-| `--entity-types <types>` | Allowed entity types (comma-separated) |
 | `--rate-limit <n>` | Rate limit (requests per minute) |
 | `--dpop-required` | Require DPoP token binding (RFC 9449) |
-| `--permissions <perms>` | Permissions for auto-generated XACML policy (comma-separated) |
 | `--save` | Save the API key to profile config |
 
-```bash
-# Create an API key and save to config
-geonic me api-keys create --name my-app --scopes read:entities --save
+`me api-keys update` supports: `--name`, `--policy-id` (use `null` to unbind), `--origins`, `--rate-limit`, `--dpop-required` / `--no-dpop-required`, `--active`, `--inactive`.
 
-# Create with permissions (auto-generates XACML policy)
-geonic me api-keys create --name my-app --permissions read,write --save
+```bash
+# Create an API key with a policy and save to config
+geonic me api-keys create --name my-app --policy <policy-id> --save
 
 # Create from JSON
-geonic me api-keys create '{"name":"my-app","allowedScopes":["read:entities"]}'
+geonic me api-keys create '{"name":"my-app","policyId":"<policy-id>"}'
+
+# Attach a personal policy
+geonic me api-keys update <key-id> --policy-id my-readonly
+
+# Unbind policy
+geonic me api-keys update <key-id> --policy-id null
 ```
 
 `me api-keys list` output includes a `dpopRequired` field (boolean).
 
+**Note**: `--policy-id` on update accepts only policies created by yourself (`/me/policies`). Policies created via `admin policies` cannot be bound here.
+
+#### me policies
+
+| Subcommand | Description |
+|---|---|
+| `me policies list` | List your personal policies |
+| `me policies get <policyId>` | Get a personal policy by ID |
+| `me policies create [json]` | Create a personal policy |
+| `me policies update <policyId> [json]` | Update a personal policy |
+| `me policies delete <policyId>` | Delete a personal policy |
+
+Personal policies (`scope: personal`) are created by `user` role accounts for self-service access control. They can be bound to your own API keys and OAuth clients.
+
+**Constraints (enforced server-side)**:
+- `priority` is fixed at 100 (user role minimum — cannot escalate)
+- `scope` is always `personal` — not applied tenant-wide
+- `target` is required
+- Data API paths only (`/v2/**`, `/ngsi-ld/**` etc.) — admin/me paths are not allowed
+
+```bash
+# Create a GET-only policy
+geonic me policies create @readonly-policy.json
+
+# Bind to an API key
+geonic me api-keys update <key-id> --policy-id my-readonly
+
+# Bind to an OAuth client
+geonic me oauth-clients update <client-id> --policy-id my-readonly
+```
+
 ### entities — Manage context entities
 
 | Subcommand | Description |
@@ -396,15 +453,24 @@ Temporal entityOperations query supports: `--aggr-methods`, `--aggr-period`.
 | `admin policies activate <id>` | Activate a policy |
 | `admin policies deactivate <id>` | Deactivate a policy |
 
-**XACML Authorization Model**: All authorization is unified under XACML policies. Default role policies (priority 0):
+**XACML Authorization Model**: All authorization is unified under XACML policies. Default role policies:
 
-| Role | Default Behavior |
-|---|---|
-| `user` | GET only (read-only) |
-| `api_key` | All Deny |
-| `anonymous` | All Deny |
+| Role | Default Behavior | Default priority |
+|---|---|---|
+| `user` | `/v2/**` and `/ngsi-ld/**` — all methods (CRUD) Permit. Other data APIs (`/catalog`, `/rules`, etc.) — GET only. | 100 |
+| `api_key` | All Deny | 100 |
+| `anonymous` | All Deny | 100 |
 
-Custom policies with higher priority (e.g. 100) override defaults. Target resource attributes include: `path`, `entityType`, `entityId`, `entityOwner`, `tenantService`, `servicePath`. The `servicePath` attribute supports glob patterns (e.g. `/opendata/**`) and regex matching.
+**Priority**: Smaller `priority` value = higher precedence (e.g. `priority: 10` overrides the user default at `priority: 100`).
+
+| priority range | Who creates | Notes |
+|---|---|---|
+| -1 | System | deny-fence (e.g. super_admin data API block) — cannot be overridden |
+| 0 | System | super_admin default — tenant_admin and below cannot override |
+| 10–99 | `tenant_admin` | Custom tenant-wide policies |
+| 100 | System / `user` (self-service via `/me/policies`) | `user` / `api_key` / `anonymous` defaults and personal policies — server fixes personal policy priority at 100 |
+
+Custom `tenant_admin` policies (priority 10–99) override the user defaults. Target resource attributes include: `path`, `entityType`, `entityId`, `entityOwner`, `tenantService`, `servicePath`. The `servicePath` attribute supports glob patterns (e.g. `/opendata/**`) and regex matching.
 
 #### admin oauth-clients
 
@@ -426,11 +492,11 @@ Custom policies with higher priority (e.g. 100) override defaults. Target resour
 | `admin api-keys update <keyId> [json]` | Update an API key |
 | `admin api-keys delete <keyId>` | Delete an API key |
 
-`admin api-keys list` supports `--tenant-id` to filter by tenant. `admin api-keys create` supports flag options: `--name`, `--scopes`, `--origins`, `--entity-types`, `--rate-limit`, `--dpop-required`, `--permissions`, `--tenant-id`, `--save`. `admin api-keys update` supports `--name`, `--scopes`, `--origins`, `--entity-types`, `--rate-limit`, `--dpop-required` / `--no-dpop-required`, `--permissions`.
+`admin api-keys list` supports `--tenant-id` to filter by tenant. `admin api-keys create` supports flag options: `--name`, `--policy`, `--origins`, `--rate-limit`, `--dpop-required`, `--tenant-id`, `--save`. `admin api-keys update` supports `--name`, `--policy`, `--origins`, `--rate-limit`, `--dpop-required` / `--no-dpop-required`.
 
-**Permissions**: The `--permissions` flag accepts a comma-separated list of `read`, `write`, `create`, `update`, `delete`. `write` is an alias for `create` + `update` + `delete`. When specified, XACML policies are auto-generated for the API key (respects `allowedEntityTypes`).
+**Policy**: Use `--policy <policyId>` to attach an existing XACML policy to the API key. Manage policies with `geonic admin policies` commands.
 
-**Note**: `allowedOrigins` must contain at least 1 item when specified. Use `*` to allow all origins. `allowedEntityTypes` is enforced at runtime — API key holders can only access entities of the specified types. `admin api-keys list` / `admin api-keys get` output includes a `dpopRequired` field (boolean).
+**Note**: `allowedOrigins` must contain at least 1 item when specified. Use `*` to allow all origins. `admin api-keys list` / `admin api-keys get` output includes a `dpopRequired` field (boolean).
 
 #### admin cadde
 
@@ -578,17 +644,16 @@ GDB_API_KEY=gdb_your_api_key_here geonic entities list
 
 When both a Bearer token and an API key are configured, headers are sent exclusively — the API key takes precedence when present.
 
-### Valid Scopes
-
-`read:entities`, `write:entities`, `read:subscriptions`, `write:subscriptions`, `read:registrations`, `write:registrations`, `read:rules`, `write:rules`, `read:custom-data-models`, `write:custom-data-models`, `admin:users`, `admin:tenants`, `admin:policies`, `admin:oauth-clients`, `admin:api-keys`, `admin:metrics`
+### Authorization Model
 
-`admin:X` implies both `read:X` and `write:X`. `write:X` does **not** imply `read:X` — specify both explicitly if needed.
+All authorization for API keys and OAuth clients is controlled via XACML policies. Use `--policy <policyId>` when creating API keys or OAuth clients to attach an existing policy.
 
-Special scopes: `permanent` (no token expiry), `jwt` (JWT format token).
+- **Tenant admins**: manage tenant-wide policies with `geonic admin policies` commands.
+- **Users**: manage personal policies with `geonic me policies` commands and bind them to your own API keys / OAuth clients with `--policy-id`.
 
-### Entity Type Restrictions
+See the [admin policies](#admin-policies) section for details on the XACML authorization model, default role policies, and target resource attributes.
 
-API keys with `allowedEntityTypes` are restricted to the specified entity types at runtime. Attempting to access entities of other types results in a 403 error with a descriptive message.
+**Note**: `--policy-id` on `me api-keys update` / `me oauth-clients update` accepts only policies where `createdBy` matches your own user ID (i.e. policies created via `me policies create`). Policies created via `admin policies` cannot be bound to personal resources.
 
 ## Development