@superglue/cli 1.1.26 → 1.1.28

package/skills/superglue/references/access-rules.md

@@ -1,147 +1,111 @@
 # Access Rules (RBAC)
 
-On superglue, roles define tool-level and system-level allowlists. Users can have multiple roles. Roles and access rules are only available on enterprise organizations. Non-enterprise orgs do not have RBAC — all users have admin access on personal organizations.
+On superglue, roles define active resource grants for tools and systems. Users can have multiple roles. Roles and access rules are only available on enterprise organizations.
 
 ## Data Model
 
-### Role
-
 ```typescript
-interface Role {
-  id: string;
-  name: string;
-  description?: string;
-  tools: "ALL" | string[]; // tool allowlist
-  systems: "ALL" | Record<string, SystemPermission>; // system allowlist
-  isBaseRole?: boolean; // true for admin, member, enduser
+interface ResourceGrant {
+  roleId: string;
+  resourceRef: "tool:<encodedId>" | "system:<encodedId>" | "tool:*" | "system:*";
+  permissions: Array<"viewer" | "editor">;
+  source: "access_rule" | "ownership" | "share";
+  grantedByUserId?: string;
+  revokedAt?: Date;
+  revokedByUserId?: string;
 }
-```
-
-### SystemPermission
-
-Each system entry is either a predefined access level or a custom rule:
 
-```typescript
-type SystemPermission = SystemAccessLevel | { rules: CustomRule[] };
-```
-
-| Type               | Meaning                                          |
-| ------------------ | ------------------------------------------------ |
-| `"read-write"`     | All HTTP methods allowed                         |
-| `"read-only"`      | Only GET and HEAD; POST/PUT/PATCH/DELETE blocked |
-| `{ rules: [...] }` | Custom JS expressions that gate access           |
-
-Systems not listed in the role's `systems` map are DENIED, unless the system access is set to `"ALL"`.
-
-### CustomRule
-
-```typescript
-interface CustomRule {
+interface Role {
   id: string;
   name: string;
-  expression?: string; // JS expression, receives stepConfig
-  isActive: boolean;
+  description?: string;
+  resourceGrants: ResourceGrant[];
+  isBaseRole?: boolean;
 }
 ```
 
-Custom rules are inline in the systems map. A system either has a standard access level OR a custom rule, never both. Custom rules must return truthy to **allow** the request. If it returns falsy, throws, or has no expression, the request is blocked (fail-closed).
-
-## Tool Permissions
-
-- `tools: "ALL"` — every tool is allowed, including tools created in the future
-- `tools: ["tool-id-1", "tool-id-2"]` — only these specific tools are allowed; new tools are NOT auto-included (but see Auto-Append below)
-
-## System Permissions
+Only active grants where `revokedAt` is empty contribute to access. `editor` implies `viewer`.
 
-- `systems: "ALL"` — every system allowed at READ_WRITE level, including future systems. Custom rules are not possible in this mode.
-- `systems: { "gmail": "read-write", "stripe": "read-only" }` — SPECIFIC mode: per-system access levels; unlisted systems are denied.
-- `systems: { "gmail": { rules: [{ name: "block-deletes", expression: "stepConfig.method !== 'DELETE'", isActive: true }] } }` — custom rule on a specific system
+## Resource Refs
 
-## Mutation Detection by Protocol
+- `tool:<encodedToolId>` — one specific tool.
+- `system:<encodedSystemId>` — one specific system.
+- `tool:*` — every current and future tool.
+- `system:*` — every current and future system.
 
-Read-only mode blocks mutating requests. How "mutating" is determined per protocol:
+Resource ids are URL-encoded inside `resourceRef`; use shared helpers rather than hand-building refs.
 
-- **HTTP** — POST, PUT, PATCH, DELETE are mutating; GET and HEAD are read-only
-- **Postgres** — SQL statements starting with or containing INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, etc. are mutating; everything else (SELECT) is read-only
-- **FTP / SMB** — operations other than `list`, `get`, `exists`, `stat` are mutating
-- **Redis** — commands not in the read-only set (GET, MGET, EXISTS, KEYS, SCAN, TTL, TYPE, HGET, HGETALL, LRANGE, SMEMBERS, SCARD, etc.) are mutating
-- **Transform** — never mutating (pure data transformation, no external system)
+## Permissions
 
-On parse failure, all protocols default to **mutating** (fail-closed).
+- `viewer` — can see and execute/use the resource.
+- `editor` — can mutate/delete/share the resource and includes `viewer`.
 
-## Custom Rule Expressions
+Current configured role access and ownership grants are generally stored as `editor`.
 
-Custom rules only apply in SPECIFIC mode. If systems is `"ALL"`, no custom rules exist.
+## Grant Sources
 
-Expressions receive a **resolved** `stepConfig` object — all template variables (`<<variable>>` and `<<(sourceData) => ...>>` expressions) are substituted with their actual runtime values before the rule evaluates. This means rules see the real URL, headers, body, and query params, not raw templates.
-
-```typescript
-interface StepConfig {
-  url: string;
-  method: string;
-  headers: Record<string, string>;
-  queryParams: Record<string, string>;
-  body: unknown;
-  systemId: string;
-}
-```
+- `access_rule` — explicit admin/Access Rules edit.
+- `ownership` — authorization projection from the resource creator.
+- `share` — explicit user-to-user sharing through the app/agent sharing flow.
 
-Example expressions:
+Ownership source of truth remains the tool/system row. Ownership grants are a permission projection and should be preserved by ordinary role edits.
 
-```javascript
-// Block all POST requests to a specific endpoint
-stepConfig.method !== "POST" || !stepConfig.url.includes("/admin");
+## Visibility and Execution Surfaces
 
-// Only allow GET requests to /api/v1/read endpoints
-stepConfig.method === "GET" && stepConfig.url.includes("/api/v1/read");
-
-// Block requests with certain headers
-!stepConfig.headers["x-dangerous-header"];
-
-// Block a specific datasource ID in the resolved body
-!(typeof stepConfig.body === "object" && stepConfig.body?.datasource?.id === "blocked-id");
-```
+- **Tools** — list/detail, agent views, VFS, REST detail, and tool history use tool `viewer`.
+- **Systems** — list/detail, agent views, VFS, docs, credentials, and `sg system call` use system `viewer`.
+- **Execution** — running a tool requires tool `viewer` plus system `viewer` for every referenced system.
+- **Editing** — updating tools/systems requires `editor`.
+- **Runs** — visible only when the user has tool `viewer` and system `viewer` for every captured system.
+- **Schedules** — visibility follows current tool behavior; editing requires tool `editor`.
+- **MCP** — config shows configured tools; runtime registration uses tool `viewer`, and execution still checks referenced systems.
 
 ## Multi-Role Semantics
 
-Users can have multiple roles. Resolution is **union (most permissive wins) everywhere**:
-
-| Layer        | Semantics                      | Example                                                                     |
-| ------------ | ------------------------------ | --------------------------------------------------------------------------- |
-| Tools        | Union (most permissive wins)   | If role A allows tool X and role B doesn't, tool X is allowed               |
-| Systems      | Union (most permissive wins)   | If role A gives READ_ONLY and role B gives READ_WRITE, result is READ_WRITE |
-| Custom rules | Per-role union (any role wins) | If any role's complete rule set allows the request, it goes through         |
+Users can have multiple roles. Resolution is union:
 
-Custom rule detail:
+| Layer   | Semantics                                                                  |
+| ------- | -------------------------------------------------------------------------- |
+| Tools   | If any active grant targets a tool, that grant's permission is effective   |
+| Systems | If any active grant targets a system, that grant's permission is effective |
 
-- **Within a single role**, all custom rules for that system must pass (AND logic)
-- **Across roles**, evaluation is per-role: if any role fully allows the request (all its rules pass, or it has no custom rule for that system), the request is allowed (OR logic)
+Assigned roles can add access but cannot remove access granted by another role.
 
 ## Base Roles
 
-Every user has exactly **one** base role. There are three:
+Every user has exactly one base role:
 
-- **`admin`** — Full access to everything. Bypasses all RBAC checks. The admin role is **immutable** — it cannot be edited at all, nor can it be re-assigned.
-- **`member`** — Default for org team members. Starts with `tools: "ALL"`, `systems: "ALL"`. Tool and system allowlists can be narrowed to restrict access. Name and description cannot be changed. Cannot be deleted.
-- **`enduser`** — Default for end users with Credentials-only access. Starts with `tools: []`, `systems: {}` (no access). Tool and system allowlists must be explicitly populated to grant access. Name and description cannot be changed. Cannot be deleted.
+- **`admin`** — full access to everything. The admin role is immutable and has wildcard `editor` grants.
+- **`member`** — default for org team members. New organizations seed it with wildcard `editor` grants for tools and systems. Access-rule grants can be narrowed. Name and description cannot be changed. Cannot be deleted.
 
-Base roles define the starting permissions that custom roles can extend or build on top of. Users can also have additional **custom roles** on top of their base role. Custom roles are fully editable (name, description, tools, systems) and can be created and deleted.
+Users can also have additional custom roles on top of their base role. Custom roles are fully editable and can be created/deleted.
 
 ## Personal Roles
 
-Admins can create a **personal role** for a specific user. A personal role is a per-user override that scopes which tools and systems that individual can access — independent of their base role and shared custom roles.
+Personal roles are per-user containers for ownership, share, and explicit access-rule grants.
+
+- Each user can have at most one personal role.
+- Ownership grants are added automatically when a user creates a tool or system.
+- Personal role grants are unioned with the user's other roles.
+- Managed via the Personal Roles tab in Access Rules and backend role APIs.
+
+## Sharing Semantics
+
+V1 sharing targets organization users only. It does not share directly to base roles or custom roles.
 
-- Each user can have at most one personal role
-- Personal roles follow the same structure as custom roles (tools allowlist, systems map, custom rules)
-- Resolution: personal role permissions are unioned with the user's other roles (most permissive wins)
-- Use case: giving a single team member access to a sensitive system without creating a shared role
-- Managed via the **Personal Roles** tab in Access Rules (web app) or the REST API (`POST /v1/users/:userId/personal-role`)
+- Sharing writes `source: "share"` grants into the target user's personal role.
+- A user can grant only permissions up to their own effective access: viewer can grant viewer, editor can grant viewer or editor.
+- If the target already has the requested permission or stronger from any active grant, sharing is redundant and should be blocked.
+- If the target has viewer access and the acting user can grant editor, sharing can promote the user to editor through the personal `source: "share"` grant.
+- Sharing a tool also grants viewer access to required systems when the recipient lacks system access.
+- Tool sharing is atomic. If any selected user or required system grant cannot be applied, nothing is shared.
+- Normal users cannot unshare in V1. Admin cleanup should use Access Rules/admin grant management.
 
-### Auto-append on resource creation
+## Auto-Grant On Resource Creation
 
-When a user creates a new tool or system, the backend automatically adds it to the **creator's personal role**:
+When a user creates a new tool or system, the backend automatically grants ownership access to the creator's personal role:
 
-- New tool created → appended to the creator's personal role's `tools` list
-- New system created → appended to the creator's personal role's `systems` map with `read-write` access
+- New tool created -> `ownership` grant on `tool:<toolId>` with `editor`.
+- New system created -> `ownership` grant on `system:<systemId>` with `editor`.
 
-This only affects the creator's personal role, not base roles or additional custom roles. It ensures that a user on a restricted allowlist automatically gets access to resources they create without granting those resources to everyone with the same base role.
+This only affects the creator's personal role, not base roles or additional custom roles.

package/skills/superglue/references/superglue-info.md

@@ -54,7 +54,7 @@ The persistent left sidebar contains these top-level items:
 - **Landscape** (`/landscape`) — graph overview of tools, systems, and their connections.
 - **Tools** (`/tools`, detail at `/tools/{toolId}`) — saved tools; opens the tool playground for editing, testing, and running.
 - **Systems** (`/systems`, detail at `/systems/{systemId}`) — connected external systems with credentials and documentation.
-- **My Credentials** (`/credentials`) — credential management. The **My Credentials** section is for personal user-owned system credentials; the **superglue API keys** section is for API keys. Admins and members open it inside the normal app shell from the sidebar; end users only see this standalone credentials surface.
+- **My Credentials** (`/credentials`) — credential management. The **My Credentials** section is for personal user-owned system credentials; the **superglue API keys** section is for API keys. Admins and members open it inside the normal app shell from the sidebar.
 - **Runs** (`/runs`, detail at `/runs/{runId}`) — execution history for full, draft, and single-step tool runs. Runs is a top-level sidebar item, not a Control Panel sub-item.
 - **Control Panel** (`/admin`) — expandable group for organization and account administration:
   - **Overview** (`/admin`) — dashboard summary, including failed-run and schedule summaries.
@@ -81,7 +81,6 @@ Below the navigation, the sidebar shows the organization switcher and Sign Out.
    e. Wrap result: `{ currentItem, data, success }`
    f. On failure: abort if `failureBehavior !== "continue"`
 3. **Output transform** (if present): run JS function, validate against outputSchema
-4. **Response filters** (if present): remove/mask/fail on pattern matches
 
 ### Strategy Routing