TiddlyWiki5/plugins/tiddlywiki/multiwikiserver/docs

title: $:/plugins/tiddlywiki/multiwikiserver/readme

This plugin extends the TiddlyWiki 5 server running on Node.js to be able to host multiple wikis that can share content or be independent.

!! Installation

```
# Clone the repo into ./TiddlyWiki5
git clone https://github.com/Jermolene/TiddlyWiki5.git --branch multi-wiki-support
cd TiddlyWiki5

# Install dependencies
npm install

# Start the server
npm start
```

Then visit the administration interface in a browser: http://127.0.0.1:8080/

The `npm start` command is a shortcut for the following command:

```
node ./tiddlywiki.js ./editions/multiwikiserver --mws-listen
```

Note that changes are written to the topmost bag in a recipe.

Note that until syncing is improved it is necessary to use "Get latest changes from the server" to speed up propogation of changes between users.

To run the tests:

```
./bin/test.sh
```

# Authentication & Authorization

## Overview

Our application has transitioned from a conventional username/password authentication system to a more robust Authentication and Authorization implementation. This new system supports multiple user accounts, roles, permissions, and a comprehensive access control list.

## Key Features

1. Multiple User Accounts
2. Role-based Access Control
3. Granular Permissions
4. Access Control List (ACL)

## Running the App
By default, the Multiwiki Server starts up without the need for authentication. An admin user is created by default with the username `user` and password `pass123`.
This user has the `ADMIN` role which grants full access to all recipes. This user is automatically assigned the `READ` and `WRITE` permissions.
You can create additional users and roles through the admin interface.

Access control is enforced at the recipe level. A user can read or write to a recipe if they have the `READ` or `WRITE` permission for that recipe.
Roles can be assigned to users and can have the `READ` and `WRITE` permissions assigned to them.

Guest users have no permissions and can only access recipes that do not have an ACL assigned to them.

To start the app, run the following command:

```bash
npm run start
```


## Setting Up the Admin User

To initialize the system with an admin user, use the following command:

```bash
npm run mws-add-user
```

This command performs the following actions:
- Creates a default admin user with the credentials:
  - Username: `user`
  - Password: `pass123`
- Establishes `READ` and `WRITE` permissions
- Creates an `ADMIN` role
- Assigns `READ` and `WRITE` permissions to the `ADMIN` role
- Assigns the `ADMIN` role to the newly created user

## User Management

Users can be managed through the application interface or via command-line tools. Each user account consists of:
- Unique username
- Securely hashed password
- Assigned role(s)

## Roles and Permissions

### Roles

Roles are used to group sets of permissions. The default setup includes an `ADMIN` role, but additional roles can be created as needed (e.g., `USER`, `MANAGER`).

### Permissions

Permissions define specific actions that can be performed. The default permissions are:
- `READ`: Allows viewing of resources
- `WRITE`: Allows creation, modification, and deletion of resources

Additional permissions can be created to suit specific application needs.

## Access Control List (ACL)

The ACL maintains a mapping between roles, permissions, and entities (such as recipes or bags). This allows for fine-grained control over who can perform what actions on which resources.

## Authentication Flow

1. User provides credentials (username and password)
2. System verifies credentials against stored user data
3. If valid, a session is created for the user

## Authorization Flow

1. User attempts to perform an action on a resource
2. System checks the user's role
3. System verifies if the role has the required permission for the action
4. System checks the ACL to ensure the role has permission for the specific entity
5. If all checks pass, the action is allowed; otherwise, it's denied

## Extending the System

To add new roles, permissions, or modify the ACL:

1. Use the provided administrative interface or CLI tools
2. Update the ACL structure in the application's configuration
3. Implement new permission checks in the relevant parts of the application

By following this documentation, you can effectively manage and utilize the new Authentication and Authorization system in your application.