<commit_before>Authorization and authentication
===============

This folder contains the Active Events related to users and roles management. It allows you to create new users, associate roles with them, and 
all associated concepts. All users are stored in the _"auth.hl"_ file at the root of p5.webapp, but this can be overridden in your web.config.
Passwords are stored in salted hashed values, to increase security. To create a new user, you can use the following code.

```
create-user:john-doe
  password:<PASSWORD>
  role:plain-user
```

The above code will create "john-doe" as a user in your system, and store him into your _"auth.hl"_ file.

Notice, only _"root"_ accounts can create new, edit, or delete users in your systems. Notice also, that we say root accounts in plural form. Contrary to on Linux,
where there in general terms can only exist one root account - In P5 you can have as many root accounts as you wish, with different usernames. I encourage 
you to keep your root accounts to a minimum though. Preferably, only one!

Also notice, that only the root account(s) can actually read or modify your _"auth.hl"_ file in your system directly, using for instance *[load-file]*
or *[save-file]* etc. Your _"auth.hl"_ file, or if you choose to use another filename for it, is in general terms, the by far best protected file
in your file system.

## Users and your filesystem

When you create a new user, a new folder structure will automatically be created for your user, beneath the _"/p5.webapp/users/"_ folder. This is the user's
personal files, and is in general terms, protected such that only that user, and root accounts, can modify or read these files. Each user has a
_"public"_ and a _"private"_ folder. The public folder, is for files which the user doesn't care about is protected or not, and anyone with a direct URL
to the file, can easily download it. The private folder, can only be accessed by the user himself, and/or a root account.

In addition, each user gets his own personal _"temp"_ folder, which is used for temporary files, used whenever a temporary file needs to be created. 

To access the currently logged in user's folder, use the tilde "~". To load the _"foo.txt"_ file from a user's folder, you can use for instance.

```
load-file:~/foo.txt
```

The tilde above (~), will be substituded with _"/users/john-doe"_, if the user attempting to evaluate the above code is our _"john-doe"_ user from the 
above Hyperlambda. If your user is a _"guest"_ account (not loggedd in), the tilde "~" will evaluate to the _"/common/"_ folder. The common folder, has a 
similar file structure, as the _"/users/"_ folder, and this folder substitution can be used transparently if you wish, without caring who is logged in, 
or whether or not any user is logged in at all. Tilde "~" basically means the _"home folder"_. The _"home folder"_ for guests, who are not logged in, is
the _"/common/"_ folder.

Notice, the above *[load-file]* Hyperlambda, will throw an exception, unless you actually have a _"foo.txt"_ file in your user's home folder. 

In general, you should put files you want for everyone to see, but that still belongs to a specific user, including guests visitors, into 
the _"~/documents/public/"_ folder(s), while protected files, into the _"~/documents/private/"_ folder.

If you wish to create files that are accessible to all users of your system, you should put these files in your _"/p5.webapp/common/"_ folder, which is
accessible to all users in your system.

You can also create your own _"path unroll"_ active events, leading to for instance some specific folder on your server. This is done by creating an
Active Event named *[p5.io.unroll-path.@XXX]*, returning for instance _"/my-cool-folder/xxx"_. An example is given below.

```
create-event:p5.io.unroll-path.@FOO-BAR
  return:/foo-bar
```

Notice, do _not_ end the path, as returned from your Active Event with a slash "/". If you create unrolling Active Events, you can also create them 
recursively, meaning that your Active Event returns a user-specific folder. Consider the following for instance, that will always return 
the _"public home folder"_.

```
create-event:p5.io.unroll-path.@PUBLIC
  return:~/documents/public
```

## Editing users

To edit a user, use the *[edit-user]* Active Event. To change the role and password of our _"john-doe"_ user from above, you could do something like
the following.

```
edit-user:john-doe
  role:some-other-role
  password:<PASSWORD>
```

The username of a user, _cannot_ be changed, after you have created your user(s).

The complete list of operations you can perform on your user objects, are as following.

* [create-user] - Creates a new user
* [edit-user] - Edits existing user (changes his or her password, settings, role)
* [list-users] - List all usernames, and their roles, in your system
* [get-user] - Returns one or more named user(s)
* [delete-user] - Deletes a user (WARNING! This will delete all his files!)

The above Active Events, can only be evaluated by a root account.

### User settings

In addition to *[role]* and *[password]*, you can associate any data you wish with your user, such as a user's personal settings, by simply adding these 
as nodes beneath you *[edit-user]* and *[create-user]* invocations. Consider this for instance.

```
edit-user:john-doe
  role:some-other-role
  password:<PASSWORD>
  some-data:foo-bar
  some-complex-data
    name:foo
    value:bar
```

If you evaluate tha above Hyperlambda, then both *[some-data]* and *[some-complex-data]* will be associated with the _"john-doe"_ user, as settings. To
retrieve the settings for the currently logged in user, you can use the *[user-settings]* Active Event. The user's settings are a convenient place to
store small pieces of user related data, which are unique to each user in your system.

You can also change your currently logged in user's settings, with the following code.

```
set-my-user-settings
  some-data:foo-bar
  some-complex-data
    name:foo
    value:bar
```

The difference is that *[edit-user]* can only be invoked by root accounts, while the latter, *[set-my-user-settings]* can be invoked by all users, except
"guest" users of course (which actually aren't "real users").

To get your user's settings, use the *[get-my-user-settings]* Active Event.

To change the passsword of the currently logged in user, use the following code.

```
change-password:bar
```

The above Hyperlambda will change the passsword for the currentlylogged in user to _"bar"_.
<commit_msg>More dox<commit_after>Users and roles
===============

This folder contains the Active Events related to users and roles management. It allows you to create new users, associate roles with them, and 
all associated concepts. All users are stored in the _"auth.hl"_ file at the root of p5.webapp, but this can be overridden in your web.config.
Passwords are stored in salted hashed values, to increase security. To create a new user, you can use the following code.

```
create-user:john-doe
  password:<PASSWORD>
  role:plain-user
```

The above code will create "john-doe" as a user in your system, and store him into your _"auth.hl"_ file.

Notice, only _"root"_ accounts can create new, edit, or delete users in your systems. Notice also, that we say root accounts in plural form. Contrary to on Linux,
where there in general terms can only exist one root account - In P5 you can have as many root accounts as you wish, with different usernames. I encourage 
you to keep your root accounts to a minimum though. Preferably, only one!

Also notice, that only the root account(s) can actually read or modify your _"auth.hl"_ file in your system directly, using for instance *[load-file]*
or *[save-file]* etc. Your _"auth.hl"_ file, or if you choose to use another filename for it, is in general terms, the by far best protected file
in your file system.

## Users and your filesystem

When you create a new user, a new folder structure will automatically be created for your user, beneath the _"/p5.webapp/users/"_ folder. This is the user's
personal files, and is in general terms, protected such that only that user, and root accounts, can modify or read these files. Each user has a
_"public"_ and a _"private"_ folder. The public folder, is for files which the user doesn't care about is protected or not, and anyone with a direct URL
to the file, can easily download it. The private folder, can only be accessed by the user himself, and/or a root account.

In addition, each user gets his own personal _"temp"_ folder, which is used for temporary files, used whenever a temporary file needs to be created. 

To access the currently logged in user's folder, use the tilde "~". To load the _"foo.txt"_ file from a user's folder, you can use for instance.

```
load-file:~/foo.txt
```

The tilde above (~), will be substituded with _"/users/john-doe"_, if the user attempting to evaluate the above code is our _"john-doe"_ user from the 
above Hyperlambda. If your user is a _"guest"_ account (not loggedd in), the tilde "~" will evaluate to the _"/common/"_ folder. The common folder, has a 
similar file structure, as the _"/users/"_ folder, and this folder substitution can be used transparently if you wish, without caring who is logged in, 
or whether or not any user is logged in at all. Tilde "~" basically means the _"home folder"_. The _"home folder"_ for guests, who are not logged in, is
the _"/common/"_ folder.

Notice, the above *[load-file]* Hyperlambda, will throw an exception, unless you actually have a _"foo.txt"_ file in your user's home folder. 

In general, you should put files you want for everyone to see, but that still belongs to a specific user, including guests visitors, into 
the _"~/documents/public/"_ folder(s), while protected files, into the _"~/documents/private/"_ folder.

If you wish to create files that are accessible to all users of your system, you should put these files in your _"/p5.webapp/common/"_ folder, which is
accessible to all users in your system.

## Adding to the system "PATH" variable

You can also create your own _"path unroll"_ active events, leading to for instance some specific folder on your server. This is done by creating an
Active Event named *[p5.io.unroll-path.@XXX]*, returning for instance _"/my-cool-folder/xxx"_. An example is given below.

```
create-event:p5.io.unroll-path.@XXX
  return:/my-cool-folder/xxx
```

Notice, do _not_ end the path, as returned from your Active Event with a slash "/". If you create unrolling Active Events, you can also create them 
recursively, meaning that your Active Event returns a user-specific folder. Consider the following for instance, that will always return 
the _"public home folder"_.

```
create-event:p5.io.unroll-path.@PUBLIC
  return:~/documents/public
```

All IO Active Events in Phosphorus Five, will try to unroll the path, if necessary, according to the above logic. Meaning, you can use for instance 
also *[list-folders]*, *[copy-file]*, etc, with path modifiers as our examples above shows you.

## Editing users

To edit a user, use the *[edit-user]* Active Event. To change the role and password of our _"john-doe"_ user from above, you could do something like
the following.

```
edit-user:john-doe
  role:some-other-role
  password:<PASSWORD>
```

The username of a user, _cannot_ be changed, after you have created your user(s).

The complete list of operations you can perform on your user objects, are as following.

* [create-user] - Creates a new user
* [edit-user] - Edits existing user (changes his or her password, settings, role)
* [list-users] - List all usernames, and their roles, in your system
* [get-user] - Returns one or more named user(s)
* [delete-user] - Deletes one or more user(s) (WARNING! This will delete all files for user(s)!)

The above Active Events, can only be evaluated by a root account.

## User settings

In addition to *[role]* and *[password]*, you can associate any data you wish with your user, such as a user's personal settings, by simply adding these 
as nodes beneath you *[edit-user]* and *[create-user]* invocations. Consider this for instance.

```
edit-user:john-doe
  role:some-other-role
  password:<PASSWORD>
  some-data:foo-bar
  some-complex-data
    name:foo
    value:bar
```

If you evaluate tha above Hyperlambda, then both *[some-data]* and *[some-complex-data]* will be associated with the _"john-doe"_ user, as settings. To
retrieve the settings for the currently logged in user, you can use the *[get-my-user-settings]* Active Event. The user's settings are a convenient place to
store small pieces of user related data, which are unique to each user in your system, such as name, email address, twitter handler, etc.

You can also change your currently logged in user's settings, with the following code.

```
set-my-user-settings
  some-data:foo-bar
  some-complex-data
    name:foo
    value:bar
```

The difference is that *[edit-user]* can only be invoked by root accounts, while the latter, *[set-my-user-settings]* can be invoked by all users, except
"guest" users of course (which actually aren't "real users").

To get your user's settings, use the *[get-my-user-settings]* Active Event.

To change the passsword of the currently logged in user, use the following code.

```
change-password:bar
```

The above Hyperlambda will change the passsword for the currentlylogged in user to _"bar"_.

{'fraction_non_alphanumeric': 0.08211950059453033, 'fraction_numerical': 0.0010404280618311534, 'mean_word_length': 4.2098335269066975, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7232000', 'n_tokens_mistral': 3825, 'n_tokens_neox': 3606, 'n_words': 1999}