roboto-js 1.7.5 → 1.8.1

package/.last-build

@@ -1 +1 @@
-2025-10-02T14:56:57.111Z
+2025-10-08T10:39:00.776Z

package/SHARING_GUIDE.md

@@ -0,0 +1,483 @@
+# Object Sharing and Access Control Guide for roboto-js
+
+This guide explains how to use the new access control and publishing methods in roboto-js to control access to your rbtObjects using the mod-iac (Identity and Access Control) system.
+
+## Table of Contents
+- [Overview](#overview)
+- [Public Publishing](#public-publishing)
+- [Granting Access to Users and Groups](#granting-access-to-users-and-groups)
+- [Revoking Access](#revoking-access)
+- [Advanced Usage](#advanced-usage)
+- [API Reference](#api-reference)
+
+## Overview
+
+The mod-iac system manages object permissions through an `iac` property on each rbtObject. This property contains:
+
+- **`creator`**: The user ID who created the object
+- **`readGrants`**: Controls who can read the object
+- **`writeGrants`**: Controls who can modify the object
+
+Each grant can include:
+- `users`: Array of user IDs
+- `userGroups`: Array of user group IDs  
+- `organizations`: Array of organization IDs
+- `userSegments`: Array of user segment IDs
+
+## Public Publishing
+
+### Making an Object Public
+
+The simplest way to share an object with everyone is to publish it:
+
+```javascript
+// Load your object
+const myAgent = await roboto.api.load('<@doc_agent.bot>', 'agentId');
+
+// Publish it (make it publicly accessible)
+await myAgent.publishObject();
+
+console.log('Agent is now public!');
+```
+
+### Unpublishing an Object
+
+To remove public access:
+
+```javascript
+// Unpublish the object (explicit method)
+await myAgent.unpublishObject();
+
+console.log('Agent is now private');
+
+// Alternative: using publishObject with flag
+await myAgent.publishObject({ publish: false });
+```
+
+### Checking Publication Status
+
+```javascript
+if (myAgent.isPublished()) {
+  console.log('This object is public');
+} else {
+  console.log('This object is private');
+}
+```
+
+## Granting Access to Users and Groups
+
+### Grant Access to Specific Users
+
+```javascript
+// Grant read access to specific user IDs
+await myAgent.grantAccess({ 
+  userIds: ['user_123', 'user_456'] 
+});
+
+console.log('Granted access to 2 users');
+```
+
+### Grant Access to User Groups
+
+```javascript
+// Grant read access to user groups
+await myAgent.grantAccess({ 
+  groupIds: ['grpRngAccount', 'grpAdmins'] 
+});
+
+console.log('Granted access to 2 groups');
+```
+
+### Grant Access to Both Users and Groups
+
+```javascript
+// Combine users and groups
+await myAgent.grantAccess({ 
+  userIds: ['user_123'],
+  groupIds: ['grpRngAccount', 'grpAdmins']
+});
+```
+
+### Grant Write Access
+
+By default, `grantAccess` grants read access. To grant write access:
+
+```javascript
+// Grant write access to specific users
+await myAgent.grantAccess({ 
+  userIds: ['user_123', 'user_456'],
+  write: true 
+});
+
+console.log('Users can now modify this object');
+```
+
+## Revoking Access
+
+### Revoke Access from Specific Users
+
+```javascript
+// Revoke read access from specific users
+await myAgent.revokeAccess({ 
+  userIds: ['user_123', 'user_456'] 
+});
+
+console.log('Revoked access from 2 users');
+```
+
+### Revoke Access from User Groups
+
+```javascript
+// Revoke read access from user groups
+await myAgent.revokeAccess({ 
+  groupIds: ['grpRngAccount'] 
+});
+
+console.log('Revoked access from group');
+```
+
+### Revoke Write Access
+
+```javascript
+// Revoke write access from specific groups
+await myAgent.revokeAccess({ 
+  groupIds: ['grpEditors'],
+  write: true 
+});
+
+console.log('Revoked write access from editors');
+```
+
+## Advanced Usage
+
+### Merging vs. Replacing Permissions
+
+By default, `grantAccess` merges with existing permissions. Use `replace: true` to replace them entirely:
+
+```javascript
+// Add to existing permissions (default)
+await myAgent.grantAccess({ 
+  userIds: ['user_123'] 
+});
+// Now includes: existing users + user_123
+
+// Replace all permissions
+await myAgent.grantAccess({ 
+  userIds: ['user_789'],
+  replace: true 
+});
+// Now includes: only user_789
+```
+
+### Update Without Auto-Saving
+
+All methods auto-save by default. You can disable this to make multiple changes:
+
+```javascript
+// Update permissions without saving
+await myAgent.grantAccess({ 
+  userIds: ['user_123'],
+  save: false 
+});
+
+// Make other changes
+myAgent.set('configs.title', 'Updated Title');
+
+// Publish without saving
+await myAgent.publishObject({ save: false });
+
+// Save once with all changes
+await myAgent.save();
+```
+
+### Getting Current Sharing Permissions
+
+```javascript
+// Get all current permissions
+const permissions = myAgent.getSharing();
+
+console.log('Read access users:', permissions.readGrants.users);
+console.log('Read access groups:', permissions.readGrants.userGroups);
+console.log('Write access users:', permissions.writeGrants.users);
+console.log('Write access groups:', permissions.writeGrants.userGroups);
+console.log('Organizations:', permissions.readGrants.organizations);
+```
+
+### Combining Public and Private Access
+
+You can combine public access with specific user/group permissions:
+
+```javascript
+// Make public AND grant write access to specific groups
+await myAgent.publishObject({ save: false });
+await myAgent.grantAccess({ 
+  groupIds: ['grpAdmins'],
+  write: true,  // Admins can edit
+  save: true 
+});
+
+// Now:
+// - Everyone can read (public_user)
+// - Admins can write (grpAdmins)
+```
+
+## API Reference
+
+### `publishObject(options)`
+
+Publishes or unpublishes an object for public access.
+
+**Parameters:**
+- `options` (Object, optional)
+  - `publish` (boolean): If true, publishes; if false, unpublishes. Default: `true`
+  - `save` (boolean): If true, auto-saves after updating. Default: `true`
+
+**Returns:** `Promise<RbtObject>` - The object (saved if `save: true`)
+
+**Examples:**
+```javascript
+// Publish
+await obj.publishObject();
+
+// Unpublish
+await obj.publishObject({ publish: false });
+
+// Update without saving
+await obj.publishObject({ save: false });
+```
+
+---
+
+### `unpublishObject(options)`
+
+Unpublishes an object to remove public access. This is a convenience method that's equivalent to `publishObject({ publish: false })`.
+
+**Parameters:**
+- `options` (Object, optional)
+  - `save` (boolean): If true, auto-saves after updating. Default: `true`
+
+**Returns:** `Promise<RbtObject>` - The object (saved if `save: true`)
+
+**Examples:**
+```javascript
+// Unpublish (remove public access)
+await obj.unpublishObject();
+
+// Unpublish without saving
+await obj.unpublishObject({ save: false });
+```
+
+---
+
+### `revokeAccess(options)`
+
+Revokes access from specific users and/or groups.
+
+**Parameters:**
+- `options` (Object, optional)
+  - `userIds` (string[]): Array of user IDs to remove from access. Default: `[]`
+  - `groupIds` (string[]): Array of group IDs to remove from access. Default: `[]`
+  - `write` (boolean): If true, removes write access; if false, removes read access. Default: `false`
+  - `save` (boolean): If true, auto-saves after updating. Default: `true`
+
+**Returns:** `Promise<RbtObject>` - The object (saved if `save: true`)
+
+**Examples:**
+```javascript
+// Revoke read access from users
+await obj.revokeAccess({ userIds: ['user_123', 'user_456'] });
+
+// Revoke write access from groups
+await obj.revokeAccess({ groupIds: ['grpEditors'], write: true });
+
+// Revoke from both users and groups
+await obj.revokeAccess({ 
+  userIds: ['user_123'],
+  groupIds: ['grpViewers']
+});
+
+// Update without saving
+await obj.revokeAccess({ userIds: ['user_123'], save: false });
+```
+
+---
+
+### `grantAccess(options)`
+
+Grants access to this object for specific users and/or groups.
+
+**Parameters:**
+- `options` (Object, optional)
+  - `userIds` (string[]): Array of user IDs to grant access. Default: `[]`
+  - `groupIds` (string[]): Array of group IDs to grant access. Default: `[]`
+  - `write` (boolean): If true, grants write access; if false, read access. Default: `false`
+  - `replace` (boolean): If true, replaces existing grants; if false, merges. Default: `false`
+  - `save` (boolean): If true, auto-saves after updating. Default: `true`
+
+**Returns:** `Promise<RbtObject>` - The object (saved if `save: true`)
+
+**Examples:**
+```javascript
+// Grant read access to users
+await obj.grantAccess({ userIds: ['user_123'] });
+
+// Grant write access to groups
+await obj.grantAccess({ groupIds: ['grpAdmins'], write: true });
+
+// Replace permissions
+await obj.grantAccess({ userIds: ['user_123'], replace: true });
+
+// Update without saving
+await obj.grantAccess({ userIds: ['user_123'], save: false });
+```
+
+---
+
+### `isPublished()`
+
+Checks if an object is currently published (publicly accessible).
+
+**Returns:** `boolean` - True if public, false otherwise
+
+**Example:**
+```javascript
+if (obj.isPublished()) {
+  console.log('Object is public');
+}
+```
+
+---
+
+### `getSharing()`
+
+Gets the current sharing permissions for an object.
+
+**Returns:** `Object` - Object containing read and write grants
+- `readGrants` (Object)
+  - `users` (string[]): User IDs with read access
+  - `userGroups` (string[]): Group IDs with read access
+  - `organizations` (string[]): Organization IDs with read access
+  - `userSegments` (string[]): Segment IDs with read access
+- `writeGrants` (Object) - Same structure as readGrants
+
+**Example:**
+```javascript
+const perms = obj.getSharing();
+console.log('Read users:', perms.readGrants.users);
+console.log('Write groups:', perms.writeGrants.userGroups);
+```
+
+## Common Patterns
+
+### Pattern 1: Template Publishing (like Ringable agents)
+
+```javascript
+async function publishTemplate(agent, isPublished) {
+  if (isPublished) {
+    // Grant access to all account users
+    await agent.grantAccess({ 
+      groupIds: ['grpRngAccount'] 
+    });
+  } else {
+    // Revoke group access
+    await agent.revokeAccess({ 
+      groupIds: ['grpRngAccount'] 
+    });
+  }
+}
+
+// Usage
+await publishTemplate(myAgent, true);  // Publish
+await publishTemplate(myAgent, false); // Unpublish
+```
+
+### Pattern 2: Organization Sharing
+
+```javascript
+async function shareWithOrganization(object, orgId, includeWrite = false) {
+  const iac = object.get('iac') || {};
+  
+  // Add to read grants
+  if (!iac.readGrants) iac.readGrants = {};
+  if (!iac.readGrants.organizations) iac.readGrants.organizations = [];
+  if (!iac.readGrants.organizations.includes(orgId)) {
+    iac.readGrants.organizations.push(orgId);
+  }
+  
+  // Optionally add to write grants
+  if (includeWrite) {
+    if (!iac.writeGrants) iac.writeGrants = {};
+    if (!iac.writeGrants.organizations) iac.writeGrants.organizations = [];
+    if (!iac.writeGrants.organizations.includes(orgId)) {
+      iac.writeGrants.organizations.push(orgId);
+    }
+  }
+  
+  object.set('iac', iac);
+  return await object.save();
+}
+```
+
+### Pattern 3: Tiered Access
+
+```javascript
+async function setupTieredAccess(content) {
+  // Make public for read
+  await content.publishObject({ save: false });
+  
+  // Give write access to editors
+  await content.shareObject({ 
+    groupIds: ['grpEditors'],
+    write: true,
+    save: false 
+  });
+  
+  // Give admin access
+  await content.shareObject({ 
+    groupIds: ['grpAdmins'],
+    write: true,
+    save: true 
+  });
+  
+  console.log('Tiered access configured:');
+  console.log('- Public: read');
+  console.log('- Editors: write');
+  console.log('- Admins: write');
+}
+```
+
+## Important Notes
+
+1. **Permission Propagation**: Changes take effect immediately upon saving. No additional steps required.
+
+2. **Creator Permissions**: The creator always has read and write access by default (managed server-side).
+
+3. **Super Admin Access**: Users in `grpSuperAdmin` have access to all objects regardless of IAC settings.
+
+4. **Array Deduplication**: The methods automatically prevent duplicate entries in permission arrays.
+
+5. **Server-Side Enforcement**: All permissions are enforced server-side. The client methods only update the IAC settings.
+
+6. **Public User**: The special user ID `'public_user'` is assigned to all unauthenticated requests, making any object with `public_user` in readGrants accessible to everyone.
+
+## Quick Reference
+
+```javascript
+// Publishing
+await obj.publishObject();           // Make public
+await obj.unpublishObject();         // Remove public access
+obj.isPublished();                   // Check if public
+
+// Granting Access
+await obj.grantAccess({ userIds: ['user1', 'user2'] });              // Grant read
+await obj.grantAccess({ groupIds: ['grpA'], write: true });          // Grant write
+await obj.grantAccess({ userIds: ['user1'], replace: true });        // Replace all
+
+// Revoking Access
+await obj.revokeAccess({ userIds: ['user1'] });                      // Revoke read
+await obj.revokeAccess({ groupIds: ['grpA'], write: true });         // Revoke write
+
+// Inspecting
+const perms = obj.getSharing();      // Get all permissions
+```
+