22 KiB
This is the forum board source, this is the assembled version of the forum,
this git will be used to work the themes without having to worries about having to assemble it.
What is PRiVY?
PRiVY is a mixed bag of acquaintances. We build Communication network for modern hackers security needs. We strongly believes in the right to share and right to privacy. PRiVY will always be fully transparent and open towards people using our services
*PRiVYBB is an unique bulletin board / forum, written entirely in assembly language (FASM) and not WASM and using SQLEET(sSQLITE) as a forum database engine. It is designed to be extremely portables and easy to deploy. *
The main and major change in this release is the support for encrypted forum database. The great SQLite plugin SQLeet is used. According to the specification it supports:
PBKDF2-HMAC-SHA256 key derivation with a 16-byte salt and 12345 iterations. ChaCha20 stream cipher with one-time keys. Poly1305 authentication tags.
PRiVY template engine reference
Overview
The source of the template engine is located in the file PRiVY/source/render2.asm
The function of the template engine is to render the text template file containing random text, mixed with template commands into a result text. In fact, it is kind of text editor.
The procedure is defined following way:
proc RenderTemplate, .pText, .hTemplate, .sqlite_statement, .pSpecial
Arguments:
.pText - pointer to TText data structure. If [.pText] == 0, a new TText structure will be created and returned. If [.hTemplate] <> 0, the template named in [.hTemplate] is appended at the end of the [.pText] structure and then rendererd. If [.hTemplate] == 0 then is assumed that the template is already loaded in the TText structure and the structure will be processed from the beginning. .hTemplate - handle or pointer to the template name. This argument must specify only the filename, not the path. The template is loaded from the path templates/SKIN_NAME/TEMPLATE_NAME - where the SKIN_NAME is determined depending on the current user preferences, the default forum setting, and the user browser (mobile or desktop browser). .sqlite_statement - this is a handler to a SQLite statement. The statement must to be prepared, executed and must contain a valid row of data. The render engine can insert data from this row into the template text. The SQL statement depends on the specific template. .pSpecial - pointer to the TSpecialParams for the current HTTP request. Can't be 0
Return value:
The procedure returns the TText structure (possibly reallocated) in the register EAX. Template symbols escape
There are 4 special characters used in the template commands that must to be escaped in the template text that is not command. These characters are: [, ], | and ^.
The escaped characters should be prefixed by the escape character ^ when used as a part of the text. I.e. ^[, ^], ^| and ^^. Template database fields
The database fields from the passed SQLite statement can be inserted in the template text by simply enclosing the field name in square brackets:
For example:
The user [UserName] has been banned!
The field names are case insensitive.
The content of the field is always rendered as a text (if the field is NULL, then it is rendered as an empty string) and the content is HTML encoded.
In order to include a database field not HTML encoded (for example, it it already contains HTML code) it need to be nested in a [html:] command (read bellow):
For example:
This is my HTML formatted [html:[signature]].
But notice, that such constructions can be not safe. PRiVY does not use such HTML formatted fields. Template commands
The general command syntax is:
[COMMAND:SOME_NESTED_TEMPLATE_TEXT]
COMMAND is the command name.
SOME_NESTED_TEMPLATE_TEXT is template text. It can contain nested template commands and field names.
The rendering of the nested commands is almost always (except the [case:] command - see below) inside out, from the most nested command/field to the least nested command.
[case:] - conditional processing.
The command [case:] has the following syntax:
[case:VALUE|CASE_TEXT0|CASE_TEXT1|...|CASE_TEXTN]
Depending on the value of VALUE it returns the text CASE_TEXT0, CASE_TEXT1 and so on up to CASE_TEXTN.
Notice that the last text CASE_TEXTN is returned for all values greater or equal to N. I.e. the command works with "saturation".
The case texts can contains nested template commands as any other command, but the processing is a little bit different.
The command [case:] has the greatest priority and is processed before any nesting template commands or SQL query fields, including the nested [case:] commands.
The value of VALUE is computed a little bit unusual.
All whitespace characters are ignored.
If it contains digits, they are interpreted as a decimal number.
Every other than digit character increments VALUE by the number of bytes in the character (UTF-8 encoding!).
In the below example, the VALUE will be computed as equal to 126: 123 (as number) + 3 (for the characters A, B and C).
[case: 1A2B3C |case = 0|case = 1|case >= 2]
... and will be rendered as case >= 2
[special:PARAM_NAME] - returns special information related to the internal engine variables and data structures.
This command inserts some information, depending on PARAM_NAME into the template. The possible PARAM_NAME values are:
The command name "special" is named after the TSpecialParams structure used for storage internal engine context during the request processing and it returns some fields from this structure, but also it can return other engine/database internal data.
visitors - returns a table with users that has been active online for the last 5 minutes.
version - return the current version of the engine.
sqliteversion - returns the current version of SQLite
cmdtype - returns value, depending on the current command detected in the URL of the request:
0 = no command
1 = prefix command. Example /!avatar/atmos
2 = suffix command. Example /the-PRiVY-template-engine-specification.272/15792/!edit_thread
stats - returns an informational html block about the current forum statistics. The value is actually the rendered template statistics.tpl.
timestamp - the time, passed after the start of the request. The time is in milliseconds with microseconds resolution. This value is used as a benchmark and should be used at the end of the page.
title - returns the needed value that to be included in the HTML <title></title> element, depending on the current page rendered.
header - this returns the html that have to be put in the forum header. This value is contained in the database and is set by the forum administrator from the forum settings panel.
tagprefix - returns a web site specific unique prefix that to be used for creating globally unique IDs for the Atom feeds. Tag URI scheme is used.
hostroot - returns the root part of the forum URLs - for example: "https://is.privy.ws" for this very site.
allstyles - returns all CSS styles used until this moment in the templates (see the command [css:] bellow) Depending on the forum settings it returns the CSS in a form of set of <link> tags, or as a <style> tag.
description - returns the forum description (for the <meta name="description"> tag) as set from the forum administrator.
keywords - returns the forum keywords (for the <meta name="keywords"> tag)
username - the username for the current user. Can be empty string, if the user is not logged-in.
userid - the current user ID (the primary ID from the Users table in the database). Can be 0 if the user is not logged-in.
skin - the currently rendered forum skin. Depends on the user preferences, administration settings and the type of the user client (mobile/desktop).
lang - the ID of the currently selected language for the user interface of the forum. Depending on the user preferences and forum settings. Notice that the forum always supports utf-8 and the posts can be written in random language. This parameter concerns only the language of the forum interface.
skincookie - returns the currently set session cookie named skin. It is aimed to provide a forum skin change for the not logged-in users.
page - the current page specified in the URL. For threads and thread lists.
dir - the current selected tag in the URL. The name is not tag because of compatibility reasons with the old versions of the engine.
limited - can be 0 or 1 depending on whether URL points to limited access threads or not.
variant - it is a complex bit field value that depending on the URL can be:
0 = "/" root of the forum.
1 = "/(o)/" the limited access threads area.
2 = "/SOME_TAG/" some tag is selected.
3 = "/(o)/SOME_TAG/" some tag is selected in the limited access threads area.
thread - the currently selected thread slug. The "slug" is a human readable URL representation of the thread title. Example: "the-PRiVY-template-engine-specification.272"
permissions - the permissions of the current user as a one number - bit field.
isadmin - 1 if the user is administrator.
canregister - 1 if the visitor can register account.
canpost - 1 if the user can post in this place.
canstart - 1 if the user can start new threads.
canedit - 1 if the user can edit the post currently selected in the SQLite statement.
candel - 1 if the user can delete the post currently selected in the SQLite statement.
canchat - 1 if the user can chat in the real-time chat of the forum.
canupload - 1 if the user can attach files to his posts.
referer - the HTTP_REFERER for the current request. Aimed to provide back links in some dialogs.
alltags - renders the tag block for the top of the forum page.
allusers - returns a list of the users for use in autocomplete dialogs.
setupmode - 1 if the database is empty and the forum is just created. Else 0;
search - returns the current search query.
order - returns the currently selected sorting order (the value of the sort= URL argument).
usearch - returns the value of the URL parameter u=; Used for searching posts from specific user.
skins=CURRENT_SKIN - returns a list of <option> tags with all available skins. Marks the CURRENT_SKIN as selected.
posters=THREAD_ID - Returns a list of the users participated in the thread with ID = THREAD_ID.
invited=THREAD_ID - Returns a list of the users invited in the thread with ID = THREAD_ID. Has meaning only for the limited access threads.
threadtags=THREAD_ID - Returns a list of the tags for the thread with ID = THREAD_ID
markup=MARKUP returns 1 if the MARKUP number is available and active in the forum. Else returns 0
environment - returns the whole environment rendered in a text form. For debug purposes only. In order to be available, the engine must be compiled with options.DebugWeb = 1;
[raw:PATH_TO_FILE] - includes file without processing.
This command includes a file as it is, without future processing.
This is useful for including files that are not templates - such as JS or already prepared files.
[include:PATH_TO_FILE] - includes template
This command includes the specified file and then renders it as a template.
[minimag:SOME_TEXT] - renders MiniMag markup.
This command translates the MiniMag formatted text SOME_TEXT into HTML.
[bbcode:SOME_TEXT] - renders BBCode markup.
This command translates BBCode formatted text SOME_TEXT into HTML.
[html:SOME_TEXT] - skips the HTML encoding of the database fields.
SOME_TEXT is already HTML formatted and must not be HTML entity encoded.
[attachments:POST_ID] - attachments list
This command returns a HTML formatted list of attached files in the post with ID = POST_ID.
[attach_edit:POST_ID] - editable attachments list
The same as [attachments:] but the list contains some editing controls for the author of the post.
[url:SOME_TEXT] - URL encode
Makes URL encoding of the included text.
[json:SOME_TEXT] - json escape
Escapes the included text in order to be included in JSON structure.
[css:FILE_NAME] - use CSS
Adds the specified file to the CSS list if it is not already there. This list is later included in the HTML by the command [special:allstyles].
[equ:NAME=VALUE] - named constant definition.
This command defines a constant with name NAME and value VALUE.
The named constant can be defined in several places. It always has the value of the latest assignment.
[const:NAME] - returns named constant value.
Returns the latest set value for the constant NAME.
See the command [equ:] from above.
[enc:SOME_TEXT] - HTML entity encoding.
Forces HTML encoding of the included text.
Some notes on the forum engine structure
The table "Params"
The table "Params" contains name/value pairs for the global forum settings. The table is defined following way:
create table Params (
id text primary key,
val text
);
Here are some parameters used in the current version of the forum engine. The parameters, marked as "Mandatory!" must be set during the installation of the forum engine.
"host" - string; Mandatory! The domain name of the forum.
"smtp_addr" - string; Mandatory! The URL or IP address of the smtp server used to send the user activation emails. This address should be on the same host (see "host" above) as the forum itself, or should allow sending emails without authentication.
"smtp_port" - integer; Mandatory! The port (the usual is 25, but can vary) of the smtp server.
"smtp_user" - string; Mandatory! The email account of the email sender (the administrator email). The whole email address of the sender should be \smtp_user@\host\ or \smtp_user@\smtp_addr\
"page_length" - integer (default: 20); The number of items, grouped in pages (both posts in a thread and threads in the thread list).
"log_events" - integer (flag (0, 1), default: 0); When 1 enables the logging mechanism of the forum. The logging is useful for debugging, but slows down the engine.
"forum_title" - string (default: "AsmBB"; The initial part of the forum title, as displayed in the browser title bar. Some suffix parts are added to this string (for example the current thread title) to form the result title of the current page.
"user_perm" - integer (default: 29); Bit-mask, indicating the initial permissions the user have after registration. Later the individual permissions can be edited for the individual users. The permissions are defined in the beginning of the "commands.asm" and currently are:
permLogin = 1
permPost = 4
permThreadStart = 8
permEditOwn = 16
permEditAll = 32
permDelOwn = 64
permDelAll = 128
permAdmin = $80000000
"avatar_max_size" - integer (default: 50KB); The maximal size of the user uploaded images in bytes.
"avatar_width" - integer (default: 128px); The width of the user uploaded avatars. Avatars with different width are rejected. Notice, that the avatars already uploaded to the database will not be affected by the change of this parameter.
"avatar_height" - integer (default: 128px); The height of the user uploaded avatars. Avatars with different height are rejected. Notice, that the avatars already uploaded to the database will not be affected by the change of this parameter.
More important of these parameters can be set from the /!settings (settings panel) of the forum.
The remaining should be set from the SQLite console. Something like:
insert or replace into Params values ("avatar_max_size", 10*1024);The parameter can be deleted by:
delete from Params where id="avatar_max_size";
The whole content of the table can be displayed by:
select * from Params;
Templates Introduction
The templates are text files, with extension ".tpl" located in the directory "/templates". They contains some text, mixed with special commands, interpreted by the forum engine in order to create the HTML code of the pages, sent to the user.
By editing the template files, it is possible to change the appearance of the forum to any desirable visual skin.
The commands are enclosed in square brackets and can be nested recursively. Each command in fact returns some text value, replacing the command itself.
The template engine is always called with 2 (optional) parameters:
Active SQLite statement, containing one row of some SQL query and
Pointer to an array of engine internal variables about the currently served HTTP request.
This way, the commands are two types - commands returning information from the internal data structures of the engine and commands returning information from the SQL statement. Commands returning request information
[special:KEYWORD] It is group of commands, returning information from the internal data structure.
Depending on KEYWORD, there are:
[special:version] - Returns the version of the engine executable file.
[special:timestamp] - Returns the time elapsed from the beginning of the current HTTP request, formatted as a decimal number with 3 digits after the decimal point. The time is measured in milliseconds with resolution in microseconds.
[special:title] - Returns the full current page title.
[special:username] - Returns the username of the user that made the request, or empty string if the user is not logged in.
[special:userid] - Returns the ID of the user (as in Users table of the database) that made the request, or 0 if the user is not logged in.
[special:permissions] - Returns the permissions of the user that made the request. If the user is not logged in - returns 0.
[special:isadmin] - 1 if the user is admin. 0 - if not admin or not logged in.
[special:canlogin] - 1 if the user is permitted to login. Currently, it is always 1, but in the future versions is possible to be used to ban users by IP.
[special:canpost] - 1 if the user is permitted to post messages in existing threads.
[special:canstart] - 1 if the user is permitted to start new threads.
[special:canedit] - 1 if the user can edit the currently displayed post. 0 elsewhere. This flag is a little bit tricky. It will be 1 only if the user has global editing permission or if the current SQL statement, passed to the template engine has field "userid" equal to the userid of the current user and this current user has editing permissions for its own content.
[special:candel] - 1 if the user can delete the currently displayed post. See [special:canedit] for detailed explanation.
[special:page] - Returns the number of the page, as specified in the requested URL or 0 if no page is specified. It has meaning only for the thread lists and threads pages.
[special:dir] - Returns the current directory (in other words the current selected tag) as specified in the requested URL.
[special:thread] - Returns the slug of the thread as specified in the request URL. Has meaning only for threads.
[special:referer] - Returns the page from where the user came. i.e. the HTTP_REFERER header of the request.
[special:alltags] - Returns all tags, of the forum, that have at least 1 thread attached, formatted in HTML with sizes, proportional to their popularity (i.e. the number of threads tagged with every tag). This command is aimed especially to construct the tag list displayed at the top of the pages. Can be styled by CSS or/and JS if needed.
[special:setupmode] - Special tag, that has value of 1 only when the forum is in setup mode, i.e. the Users table is empty. In this mode, only the admin created form is displayed by the forum. Should not be used in the templates actually.
[special:search] - Returns the current search query of the forum search engine.
[special:posters=THREAD_ID] - Returns list of the usernames of the thread starter and first several posters in the thread with ID=THREAD_ID. Can be used in the thread list summary representation of the thread. The list is formatted in HTML.
[special:threadtags=THREAD_ID] - Similar to the previous command, returns a list of the tags, assigned to a thread with ID=THREAD_ID. Commands for data processing
[minimag:MARKDOWN_TEXT] - This command parses the markdown formatted text MARKDOWN_TEXT and converts it into HTML. The markup is very similar to the base markdown, but has some differences.
[case:INDEX|TEXT0|TEXT1|TEXT2..|TEXTN] - case operator, depending on the value of INDEX, one of the "|" delimited texts is returned. The operator works with saturation. If the value of INDEX is bigger than the number of provided texts, the last text is returned.
[sql:SQL_STATEMENT|PARAM1|PARAM2|...|PARAMN] - Prepares SQL statement SQL_STATEMENT, binds the "?" parameters to the provided, "|" separated values and executes the query. The query must be scalar - i.e. to return only one value and this value is returned as a result of the operation. If the query ends with empty set or error, an empty string is returned. Notice: this is extremely dangerous command that can destroy the data base! Use only "select" statements and always use fixed query and parameter bindings.
Actually this command is usually used not for extracting data from the database, but simply as a calculator to compute complex expressions by using the SQLite expression parser. In this case the command looks like:
[sql: select EXPRESSION|PARAM1|PARAM2...|PARAMN]
and is safe for use, because does not access the database at all. SQL statement data fields.
The fields of the SQL statement passed to the template are replaced by simply enclosing the field name in square brackets.
For example [username] will return the value of the field "username" from the statement if such field exists.
If such field does not exists, the command is not replaced at all.
Every template file has its own different SQL query that is passed to it with its own set of accessible database fields.
The fields will be described with the description of the particular template files.