toolkit_gts/
permission.rs

1//! Base GTS Type for Gears authorization permissions.
2//!
3//! Permissions are declared by gears as **well-known GTS Instances** of
4//! this base type and registered with `types-registry` during gear init
5//! (preferably at compile time via the `gts_instance!` macro). The future
6//! `AuthZ` Management gear / admin UI lists permissions by querying
7//! `types-registry` for Instances of `gts.cf.toolkit.authz.permission.v1~`.
8//!
9//! ## `resource_type` semantics
10//!
11//! The `resource_type` field accepts a GTS expression:
12//!
13//! - **Concrete GTS Type Identifier** — `gts.cf.core.ai_chat.chat.v1~cf.core.mini_chat.chat.v1~`
14//! - **Wildcard pattern** (GTS §3.5) — `gts.cf.core.am.tenant.*`
15//! - **Query Language predicates** (GTS §3.3) — `gts.cf.core.ai_chat.chat.v1~[category='support']`
16//!
17//! Attribute selector (GTS §3.4, `@path.nested`) is NOT accepted; it is for
18//! single-value reads, not set expressions.
19//!
20//! ## Well-known Instance Identifier convention
21//!
22//! ```text
23//! gts.cf.toolkit.authz.permission.v1~<vendor>.<package>.<namespace>.<permission_name>.v1
24//! ```
25//!
26//! The right-hand segment encodes the declaring gear's ownership
27//! (`<vendor>.<package>.<namespace>`) — use `_` as a placeholder when a slot
28//! has no meaningful value — and an internal handle for the permission
29//! (`<permission_name>`). Examples:
30//!
31//! - `gts.cf.toolkit.authz.permission.v1~cf.mini_chat._.chat_create.v1`
32//! - `gts.cf.toolkit.authz.permission.v1~cf.am._.tenant_create.v1`
33//!
34//! ## Extending with per-permission metadata
35//!
36//! If a gear needs ABAC-style per-permission attributes (audit category,
37//! MFA requirement, risk class, …), it declares a derived Type Schema with
38//! `#[toolkit_gts::gts_type_schema(base = AuthzPermissionV1, ...)]` and
39//! registers Instances against that derived Type Schema (the wrapper joins
40//! the link-time inventory automatically, same as base types). This path
41//! is reserved for concrete consumers with real need — YAGNI governs
42//! today's shape.
43
44use crate::gts_type_schema;
45use gts::GtsInstanceId;
46
47/// Base GTS Type for authorization permissions.
48///
49/// Permissions are well-known GTS Instances of this type; declaring gears
50/// register them via the `gts_instance!` macro (preferred, compile-time) or
51/// `TypesRegistryClient::register` (runtime).
52///
53/// GTS Type Identifier: `gts.cf.toolkit.authz.permission.v1~`
54#[gts_type_schema(
55    dir_path = "schemas",
56    type_id = gts_id!("cf.toolkit.authz.permission.v1~"),
57    description = "Gears authorization permission",
58    properties = "id,resource_type,action,display_name",
59    base = true
60)]
61pub struct AuthzPermissionV1 {
62    /// Full GTS Instance Identifier of this permission (e.g.
63    /// `gts.cf.toolkit.authz.permission.v1~cf.mini_chat._.chat_read.v1`).
64    pub id: GtsInstanceId,
65    /// GTS expression identifying the set of resources this permission
66    /// applies to. Accepts concrete IDs, wildcard patterns (GTS §3.5), or
67    /// Query Language predicates (GTS §3.3).
68    pub resource_type: String,
69    /// Concrete action name (lowercase `snake_case`). No wildcard, no list.
70    /// Examples: `create`, `read`, `list`, `retry_turn`, `upload_attachment`.
71    pub action: String,
72    /// Human-readable label for admin UIs. Examples: "Create tenant",
73    /// "Retry chat turn".
74    pub display_name: String,
75}
toolkit_gts/permission.rs

toolkit_gts/
permission.rs
