@fleetbase/solid-engine 0.0.3 → 0.0.5

package/MANUAL_ACL_SETUP.md

@@ -0,0 +1,135 @@
+# Manual ACL Setup Guide
+
+## The Problem
+
+CSS is not granting the `webid` scope even when requested during client registration and authentication. This means:
+- Access tokens have `"scope": ""` (empty)
+- Cannot programmatically update ACLs (requires `webid` scope)
+- Must manually set up root ACL with proper permissions
+
+## The Solution
+
+Manually create the root ACL file for each pod using one of these methods:
+
+### Method 1: Using curl (Recommended)
+
+```bash
+# 1. Create ACL file
+cat > /tmp/root.acl << 'EOF'
+@prefix acl: <http://www.w3.org/ns/auth/acl#>.
+
+<#owner>
+    a acl:Authorization;
+    acl:agent <http://solid:3000/test/profile/card#me>;
+    acl:accessTo <http://solid:3000/test/>;
+    acl:default <http://solid:3000/test/>;
+    acl:mode acl:Read, acl:Write, acl:Control.
+EOF
+
+# 2. Upload to CSS (requires admin access or direct file system access)
+curl -X PUT \
+  -H "Content-Type: text/turtle" \
+  --data-binary @/tmp/root.acl \
+  http://solid:3000/test/.acl
+```
+
+### Method 2: Direct File System Access
+
+If you have access to the CSS server file system:
+
+```bash
+# Navigate to the pod directory
+cd /path/to/css/data/test/
+
+# Create .acl file
+cat > .acl << 'EOF'
+@prefix acl: <http://www.w3.org/ns/auth/acl#>.
+
+<#owner>
+    a acl:Authorization;
+    acl:agent <http://solid:3000/test/profile/card#me>;
+    acl:accessTo <http://solid:3000/test/>;
+    acl:default <http://solid:3000/test/>;
+    acl:mode acl:Read, acl:Write, acl:Control.
+EOF
+
+# Set proper permissions
+chmod 644 .acl
+```
+
+### Method 3: CSS Admin API (if available)
+
+If your CSS instance has an admin API:
+
+```bash
+# Use admin credentials to create ACL
+curl -X PUT \
+  -H "Authorization: Bearer <admin_token>" \
+  -H "Content-Type: text/turtle" \
+  --data-binary @root.acl \
+  http://solid:3000/admin/pods/test/.acl
+```
+
+## ACL Template
+
+Replace `<WEBID>` and `<POD_URL>` with actual values:
+
+```turtle
+@prefix acl: <http://www.w3.org/ns/auth/acl#>.
+
+# Full control for the pod owner
+<#owner>
+    a acl:Authorization;
+    acl:agent <WEBID>;
+    acl:accessTo <POD_URL>;
+    acl:default <POD_URL>;
+    acl:mode acl:Read, acl:Write, acl:Control.
+```
+
+**Example for test pod:**
+- WebID: `http://solid:3000/test/profile/card#me`
+- Pod URL: `http://solid:3000/test/`
+
+## Verification
+
+After setting up the ACL, verify it works:
+
+```bash
+# Check WAC-Allow header (should now include "write")
+curl -I http://solid:3000/test/
+
+# Expected response:
+# WAC-Allow: user="read write append control",public="read"
+```
+
+## For Fleetbase Integration
+
+Once the root ACL is set up:
+
+1. ✅ User can create folders
+2. ✅ User can import resources
+3. ✅ All descendants inherit permissions (via `acl:default`)
+4. ✅ No need for programmatic ACL updates
+
+## Why This Is Necessary
+
+CSS does not grant `webid` scope by default, which means:
+- Cannot use OIDC tokens to update ACLs programmatically
+- Root ACL must be created manually during pod provisioning
+- This is expected behavior for CSS security model
+
+## Long-Term Solution
+
+For production:
+1. Configure CSS to grant `webid` scope (server configuration)
+2. Or create root ACL during pod creation (provisioning hook)
+3. Or use CSS admin API to set up ACLs automatically
+
+## Current Status
+
+- ✅ Authentication works (DPoP + OIDC)
+- ✅ Read operations work
+- ❌ Write operations fail (no ACL permissions)
+- ❌ Cannot update ACL (no `webid` scope)
+
+**Action Required:** Manually create root ACL for each pod using one of the methods above.

package/README.md

@@ -72,48 +72,95 @@ Solid, an innovative technology developed by Sir Tim Berners-Lee, offers a groun
 
 ### Fleetbase UI Updates 
 
-- As per the latest release, this is the updated UI screenshots for Fleetbase for users to manage pods.
+Developer/User Guide: 
 
-- You can see the full release details here: https://github.com/fleetbase/solid/pull/2
+Fleetbase Solid ExtensionThis guide provides detailed instructions for integrating the Solid extension with your Fleetbase account. Solid is an innovative technology that lets users store their own data in personal online data stores, called "Pods," that they control. By using the Solid extension on Fleetbase, users can manage their data directly through the Fleetbase interface.
 
-- Install Solid Extension and click link: 'Sign up for an account' This will take you to Solid to create your own Solid Server & Pods,
+1. Create a New Fleetbase Account
+- If you don't already have a Fleetbase account, you'll need to create one:
 
-![image](https://github.com/fleetbase/solid/assets/58805033/e4cf882a-d04f-4abd-9107-e04cb0a47949)
+- Go to the Fleetbase website
+- Click on "Sign Up" and follow the registration process.
+- Verify your account as required.
 
-- Once you head to this link, you can create your own Solid Server. You should be able to generate as per the Screenshot:
+![image](https://github.com/fleetbase/solid/assets/58805033/8dd8084c-5007-420e-b235-b46848cbe884)
 
-<img width="1134" alt="image" src="https://github.com/fleetbase/solid/assets/58805033/97015745-a1a6-487a-a958-fe97d0a7bca7">
+2. Install the Solid Extension
+- Once your Fleetbase account is active, follow these steps to install the Solid extension:
 
+- Log in to your Fleetbase dashboard.Navigate to the Extensions section.
+- Find the Solid extension and click "Install."Fleetbase Extensions Registry will be launching Q3 2024
 
-- Input your Solid Server details directly into Fleetbase in company admin settings
+3. Admin Configuration
+- As an admin, you need to set up the Solid server for your organization:
 
-![image](https://github.com/fleetbase/solid/assets/58805033/dcfe2953-71d4-41c0-9243-36811b52017e)
+- After installation, navigate to Admin so you can configure the Solid extension settings.
+- Input the Solid server ID where your organization's data will be stored. This might be a private server or a service like solidcommunity.net
 
-Next steps would be to continue to update the UI from feedback and also conduct thorough testing and documentation. UI enhancements will be things like viewing the specific pods created as well as last synced. 
+![image](https://github.com/fleetbase/solid/assets/58805033/a9324b10-f963-4a41-89c8-9ed574b450b5)
+
+
+4. Get Started with Solid
+- Users must individually sign up for a Solid account:
+
+- Click ‘Sign up for an account’ or Visit https://solidcommunity.net/register or your organization's own Solid server.
+- Complete the registration process to create a new Solid account.
+
+![image](https://github.com/fleetbase/solid/assets/58805033/2bbc7406-ae08-4500-afb0-b52af675110b)
+
+5.​​ Retrieve Your Web ID
+- Your Web ID is your unique identifier in the Solid ecosystem:
+
+- After registering, your Web ID will typically be displayed on your Solid dashboard.Note this Web ID as it will be used to link your Solid account with Fleetbase.
+
+![image](https://github.com/fleetbase/solid/assets/58805033/1ef66dfd-fe19-4795-b1bf-3d16ba7e65f8)
+
+6.​​ Navigate to ‘Account’ in Fleetbase
+- Once your Web ID is set up:Go back to Fleetbase and navigate to the ‘Account’ section. Your User details should be pulled in automatically if properly configured.
+
+![image](https://github.com/fleetbase/solid/assets/58805033/4d3d3090-1e3e-49e6-babc-f1c3db205080)
+
+7.​​ Navigate to PodsTo manage your Pods:
+ - In Fleetbase, find and navigate to the ‘Pods’ section after linking your Solid account.
+
+![image](https://github.com/fleetbase/solid/assets/58805033/bcc83875-e4ed-4ae1-be83-6044eefe323e)
+
+8.​​ Create a New POD
+- Here’s how to create a new POD:
+
+- Click “Create New POD.”Enter a name for your POD and submit.
+
+![image](https://github.com/fleetbase/solid/assets/58805033/2677491c-7de3-4592-9f30-80448e818ff6)
+
+9.​​ Manage Files/Folders in PODs
+- To access and manage data within a POD:
+
+- Click into the POD you wish to view.
+- You’ll see files and folders stored in this POD
+
+![image](https://github.com/fleetbase/solid/assets/58805033/e04e151a-d640-4e29-a91a-a6f09347e59d)
+
+10. Operations on PODsSelect 
+
+- Box Delete: To delete files or folders, select them and use the delete option.
+- Re-sync / Back Up the PODs: To ensure your data is up-to-date, use the re-sync option to resynchronize the data in the POD.
+
+![image](https://github.com/fleetbase/solid/assets/58805033/1f5ef3a8-bed8-476b-b176-cdd19b6212cd)
+
+11. View Data in Pods
+- To view specific data within a POD:
+
+- Simply click on the file or folder you are interested in within the POD interface in Fleetbase.
+
+![image](https://github.com/fleetbase/solid/assets/58805033/55f8af9b-f82b-406d-9434-50404c282740)
+
+Next: We will continue work on completing the Sold <> Fleetbase integration with the following Further User Interface (UI) Enhancement for renaming Pods. Extensive User testing / bug fixes and production release. 
 
 ### Features:
 
 Fleetbase has implemented a Solid Client which implements the Standard Solid authentication methods to communicate with the server. The Fleetbase SolidClient is able to communicate securely with the Solid protocol using the Standard DPoP encryption method for authentication provided by the Solid specification (https://solidproject.org/TR/oidc#tokens-id)
 
 - Ability to link Fleetbase account with Solid Web ID later via user settings.
-- View and manage data stored on Solid Pod:
-  - Orders
-  - Payload
-  - Entity
-  - Service Quote
-  - Purchase Rate
-- Retrieve list of Solid Pods approved to receive data.
-- Ability to add approved pods to send order data too (Verification Process)
-- View order details 
-- Send order details 
-- Select Pod to send order details too 
-- Send order details to Solid partners:
-  - View Order
-  - Send Order
-  - Select from Dropdown of Solid Partners
-  - Confirmation popup for sending data
-  - Review and confirm data to be sent
-- Access a separate table to view all data shared with you or shared with other Solid users.
 
 # Funding
 

package/REFACTORING_SUMMARY.md

@@ -0,0 +1,330 @@
+# Solid Extension Refactoring Summary
+
+## Overview
+Refactored the Fleetbase Solid Protocol extension from a multi-pod architecture to a single-pod architecture with user-friendly terminology.
+
+## Key Changes
+
+### Terminology Updates
+- **"Pods" → "Data"**: More intuitive for users to understand they're managing their data
+- **"Container" → "Folder"**: Familiar file system metaphor instead of technical Solid terminology
+
+### Architecture Shift
+**Before (Multi-Pod):**
+- Users could create multiple pods
+- Complex pod listing and management UI
+- Cross-pod authentication issues
+- Routes: `pods`, `pods.index`, `pods.explorer`, `pods.index.pod`
+
+**After (Single-Pod):**
+- Users have ONE primary pod from OIDC authentication
+- Data organized in folders within the pod (vehicles/, drivers/, contacts/, orders/)
+- Simplified permissions model
+- Routes: `data`, `data.content`
+
+---
+
+## Frontend Changes
+
+### Routes Refactored
+**File:** `addon/routes.js`
+
+**Old Structure:**
+```javascript
+this.route('pods', function () {
+    this.route('explorer', { path: '/explorer/:id' }, function () {
+        this.route('content', { path: '/~/:slug' });
+    });
+    this.route('index', { path: '/' }, function () {
+        this.route('pod', { path: '/pod/:slug' });
+    });
+});
+```
+
+**New Structure:**
+```javascript
+this.route('data', { path: '/data' }, function () {
+    this.route('content', { path: '/:slug' });
+});
+```
+
+### Files Created
+1. **`addon/routes/data/index.js`** - Main data browser route
+2. **`addon/routes/data/content.js`** - Folder navigation route
+3. **`addon/controllers/data/index.js`** - Data browser controller with folder operations
+4. **`addon/controllers/data/content.js`** - Folder content controller
+5. **`addon/templates/data/index.hbs`** - Data browser template
+6. **`addon/templates/data/content.hbs`** - Folder content viewer template
+
+### Files Removed
+- `addon/routes/pods/` (entire directory)
+- `addon/controllers/pods/` (entire directory)
+- `addon/templates/pods/` (entire directory)
+
+### Files Updated
+1. **`addon/templates/application.hbs`**
+   - Updated sidebar navigation: `console.solid-protocol.pods` → `console.solid-protocol.data`
+
+2. **`addon/templates/home.hbs`**
+   - "Browse Pods" → "Browse Data"
+   - "Explore and manage your Solid pods" → "Explore and manage your Fleetops data in Solid"
+   - Updated all pod references to use "storage" terminology
+
+3. **`addon/controllers/home.js`**
+   - `navigateToPods()` now routes to `console.solid-protocol.data`
+
+---
+
+## Backend Changes
+
+### New Controller
+**File:** `server/src/Http/Controllers/DataController.php`
+
+**Methods:**
+- `index()` - Get root level contents of user's pod
+- `showFolder($slug)` - Get contents of a specific folder
+- `createFolder()` - Create a new folder in the pod
+- `deleteItem($type, $slug)` - Delete a file or folder
+- `importResources()` - Import Fleetops resources into folders
+
+### Routes Updated
+**File:** `server/src/routes.php`
+
+**Old Routes:**
+```php
+$router->get('pods', 'PodController@index');
+$router->post('pods', 'PodController@create');
+$router->get('pods/{podId}', 'PodController@show');
+$router->delete('pods/{podId}', 'PodController@destroy');
+$router->post('import-resources', 'PodController@importResources');
+
+$router->get('containers', 'ContainerController@index');
+$router->post('containers', 'ContainerController@create');
+$router->delete('containers/{containerName}', 'ContainerController@destroy');
+```
+
+**New Routes:**
+```php
+$router->get('data', 'DataController@index');
+$router->get('data/folder/{slug}', 'DataController@showFolder');
+$router->post('data/folder', 'DataController@createFolder');
+$router->delete('data/{type}/{slug}', 'DataController@deleteItem');
+$router->post('data/import', 'DataController@importResources');
+```
+
+### Service Methods Added
+**File:** `server/src/Services/PodService.php`
+
+**New Methods:**
+- `createFolder(SolidIdentity $identity, string $folderUrl): bool`
+  - Creates a folder (LDP BasicContainer) in the pod
+  - Uses PUT request with proper Content-Type and Link headers
+
+- `deleteResource(SolidIdentity $identity, string $resourceUrl): bool`
+  - Deletes a file or folder from the pod
+  - Uses DELETE request
+
+**Existing Method Used:**
+- `getPodUrlFromWebId(string $webId): string`
+  - Extracts the pod URL from the user's WebID
+  - Example: `http://solid:3000/test/profile/card#me` → `http://solid:3000/test/`
+
+---
+
+## API Endpoint Mapping
+
+### Frontend → Backend
+| Frontend Route | API Endpoint | Controller Method |
+|----------------|--------------|-------------------|
+| `data.index` | `GET /data` | `DataController@index` |
+| `data.content/:slug` | `GET /data/folder/:slug` | `DataController@showFolder` |
+| Create folder action | `POST /data/folder` | `DataController@createFolder` |
+| Delete item action | `DELETE /data/:type/:slug` | `DataController@deleteItem` |
+| Import resources | `POST /data/import` | `DataController@importResources` |
+
+---
+
+## User Experience Improvements
+
+### Navigation
+- **Sidebar:** "Data" instead of "Pods"
+- **Home Page:** "Browse Data" quick action
+- **Breadcrumbs:** Will show folder hierarchy instead of pod names
+
+### Data Browser Features
+1. **Folder Management**
+   - Create new folders with "New Folder" button
+   - Browse folders like a file explorer
+   - Delete folders and files
+
+2. **Resource Import**
+   - "Import Resources" button in data browser
+   - Select resource types: Vehicles, Drivers, Contacts, Orders
+   - Resources imported into respective folders in the pod
+
+3. **File Operations**
+   - View file information in overlay
+   - Open files in new tab
+   - Delete files with confirmation
+
+---
+
+## Technical Benefits
+
+### Simplified Architecture
+1. **No Multi-Pod Management**
+   - Removed pod listing complexity
+   - Removed pod creation/deletion UI
+   - Removed pod selection logic
+
+2. **Single Authentication Flow**
+   - One DPoP-bound access token for the user's pod
+   - No cross-pod permission issues
+   - Cleaner token management
+
+3. **Standard Solid Patterns**
+   - Follows Solid specification for single-pod-per-user
+   - Uses LDP containers (folders) for organization
+   - Proper RDF/Turtle format for resources
+
+### Code Cleanliness
+1. **Removed Unused Code**
+   - Deleted 12 files related to multi-pod management
+   - Removed unused routes and controllers
+   - Cleaner route structure (2 routes vs 4)
+
+2. **Clear Naming**
+   - `DataController` vs `PodController` - clearer intent
+   - `data/folder` routes - self-documenting
+   - User-facing terms match technical implementation
+
+---
+
+## Data Organization
+
+### Pod Structure
+```
+http://solid:3000/user/
+├── vehicles/
+│   ├── vehicle-uuid-1.ttl
+│   ├── vehicle-uuid-2.ttl
+│   └── ...
+├── drivers/
+│   ├── driver-uuid-1.ttl
+│   └── ...
+├── contacts/
+│   ├── contact-uuid-1.ttl
+│   └── ...
+└── orders/
+    ├── order-uuid-1.ttl
+    └── ...
+```
+
+### Resource Format
+Each resource is stored as an RDF/Turtle file with semantic metadata following Solid conventions.
+
+---
+
+## Next Steps
+
+### Testing Required
+1. **Authentication Flow**
+   - Verify OIDC authentication still works
+   - Check DPoP token binding
+   - Confirm pod URL extraction from WebID
+
+2. **Data Browser**
+   - Test folder creation
+   - Test folder navigation
+   - Test file deletion
+   - Test search functionality
+
+3. **Resource Import**
+   - Test importing vehicles
+   - Test importing drivers
+   - Test importing contacts
+   - Test importing orders
+   - Verify RDF/Turtle format
+   - Check folder creation for each resource type
+
+4. **Error Handling**
+   - Test 401 unauthorized scenarios
+   - Test invalid folder names
+   - Test deleting non-existent resources
+
+### Future Enhancements
+1. **Incremental Sync**
+   - Only sync changed resources
+   - Track last sync timestamp
+   - Show sync status per resource type
+
+2. **Resource Filtering**
+   - Filter by date range
+   - Filter by status
+   - Search within resources
+
+3. **Sync History**
+   - Track sync operations
+   - Show sync logs
+   - Rollback capability
+
+4. **Real-time Sync**
+   - Webhook integration with Fleetops
+   - Automatic sync on data changes
+   - Conflict resolution
+
+---
+
+## Migration Notes
+
+### For Developers
+- Update any references to `pods` routes to use `data` routes
+- Replace `PodController` usage with `DataController`
+- Update API calls from `import-resources` to `data/import`
+- Remove any pod selection logic from components
+
+### For Users
+- Existing data: Users will need to re-import resources into their primary pod
+- No action required for authentication - existing OIDC flow remains the same
+- UI will automatically reflect new "Data" terminology
+
+---
+
+## Files Modified Summary
+
+### Created (7 files)
+- `addon/routes/data/index.js`
+- `addon/routes/data/content.js`
+- `addon/controllers/data/index.js`
+- `addon/controllers/data/content.js`
+- `addon/templates/data/index.hbs`
+- `addon/templates/data/content.hbs`
+- `server/src/Http/Controllers/DataController.php`
+
+### Modified (6 files)
+- `addon/routes.js`
+- `addon/templates/application.hbs`
+- `addon/templates/home.hbs`
+- `addon/controllers/home.js`
+- `server/src/routes.php`
+- `server/src/Services/PodService.php`
+
+### Deleted (12 files)
+- `addon/routes/pods/explorer.js`
+- `addon/routes/pods/explorer/content.js`
+- `addon/routes/pods/index.js`
+- `addon/routes/pods/index/pod.js`
+- `addon/controllers/pods/explorer.js`
+- `addon/controllers/pods/explorer/content.js`
+- `addon/controllers/pods/index.js`
+- `addon/controllers/pods/index/pod.js`
+- `addon/templates/pods/explorer.hbs`
+- `addon/templates/pods/explorer/content.hbs`
+- `addon/templates/pods/index.hbs`
+- `addon/templates/pods/index/pod.hbs`
+
+---
+
+## Conclusion
+
+This refactoring significantly simplifies the Solid extension architecture while improving user experience through familiar terminology. The single-pod approach aligns with Solid best practices and eliminates cross-pod authentication complexity. The codebase is now cleaner, more maintainable, and easier for developers to understand.

package/VERIFICATION_CHECKLIST.md

@@ -0,0 +1,82 @@
+# Refactoring Verification Checklist
+
+## Code Cleanup ✓
+- [x] Removed old `addon/routes/pods/` directory
+- [x] Removed old `addon/controllers/pods/` directory  
+- [x] Removed old `addon/templates/pods/` directory
+- [x] Removed `server/src/Http/Controllers/PodController.php`
+- [x] Removed `server/src/Http/Controllers/ContainerController.php`
+- [x] Removed commented code from `addon/templates/application.hbs`
+- [x] Removed commented routes from `server/src/routes.php`
+
+## New Files Created ✓
+- [x] `addon/routes/data/index.js`
+- [x] `addon/routes/data/content.js`
+- [x] `addon/controllers/data/index.js`
+- [x] `addon/controllers/data/content.js`
+- [x] `addon/templates/data/index.hbs`
+- [x] `addon/templates/data/content.hbs`
+- [x] `server/src/Http/Controllers/DataController.php`
+
+## Routes Updated ✓
+- [x] `addon/routes.js` - Simplified to data routes
+- [x] `server/src/routes.php` - Updated API endpoints
+
+## Templates Updated ✓
+- [x] `addon/templates/application.hbs` - Sidebar navigation
+- [x] `addon/templates/home.hbs` - Quick actions and terminology
+
+## Controllers Updated ✓
+- [x] `addon/controllers/home.js` - Navigation method
+
+## Services Updated ✓
+- [x] `server/src/Services/PodService.php` - Added createFolder() and deleteResource()
+
+## Terminology Changes ✓
+- [x] "Pods" → "Data" throughout UI
+- [x] "Container" → "Folder" in code comments and user-facing text
+- [x] Updated all user-facing messages
+
+## Testing Required
+- [ ] OIDC authentication flow
+- [ ] Pod URL extraction from WebID
+- [ ] Data browser loads correctly
+- [ ] Folder creation works
+- [ ] Folder navigation works
+- [ ] File/folder deletion works
+- [ ] Resource import (vehicles, drivers, contacts, orders)
+- [ ] Search functionality
+- [ ] Error handling (401, invalid inputs)
+
+## API Endpoints to Test
+
+### GET /solid/int/v1/data
+Expected: Returns root contents of user's pod
+
+### GET /solid/int/v1/data/folder/{slug}
+Expected: Returns contents of specified folder
+
+### POST /solid/int/v1/data/folder
+Payload: `{ "name": "test-folder", "path": "" }`
+Expected: Creates new folder
+
+### DELETE /solid/int/v1/data/{type}/{slug}
+Example: `DELETE /solid/int/v1/data/folder/vehicles`
+Expected: Deletes specified folder or file
+
+### POST /solid/int/v1/data/import
+Payload: `{ "resource_types": ["vehicles", "drivers"] }`
+Expected: Imports selected resources into folders
+
+## Files Count Summary
+- **Created:** 7 files
+- **Modified:** 6 files
+- **Deleted:** 14 files (12 frontend + 2 backend)
+- **Net change:** -1 files (cleaner codebase!)
+
+## Code Quality Checks
+- [x] No references to old `pods.explorer` or `pods.index` routes
+- [x] No references to `PodController` or `ContainerController`
+- [x] All imports and dependencies updated
+- [x] Consistent naming conventions (data/folder)
+- [x] Clean, readable code structure