PHPackages                             vzool/dove.php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. vzool/dove.php

ActiveLibrary[Mail & Notifications](/categories/mail)

vzool/dove.php
==============

Dove Notification File System (DNFS)

1.0.52(3y ago)111MITPHPPHP >=7.3

Since Jan 29Pushed 2y ago1 watchersCompare

[ Source](https://github.com/vzool/dove.php)[ Packagist](https://packagist.org/packages/vzool/dove.php)[ Docs](https://github.com/vzool/dove.php)[ RSS](/packages/vzool-dovephp/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (9)Used By (0)

🐦 Dove Notification File System (DNFS)
======================================

[](#bird-dove-notification-file-system-dnfs)

[![ar](https://camo.githubusercontent.com/e08d7403b339a2e5fdc4ceb34adc7736f7437fa6b302ea5c59ba8ebac8404b6d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c616e672d61722d677265656e2e737667)](https://github.com/vzool/dove.php/blob/main/README.ar.md)[![Build Status](https://github.com/vzool/dove.php/workflows/tests/badge.svg)](https://github.com/vzool/dove.php/actions)[![Total Downloads](https://camo.githubusercontent.com/6bf65056316065cd9eb9517e11566ac9748e12103c0681d13c7b6c7de60718f8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f767a6f6f6c2f646f76652e706870)](https://packagist.org/packages/vzool/dove.php)[![Latest Stable Version](https://camo.githubusercontent.com/dd3ce94488fd4e67df36080d148cc271a131dd55a013cf3fa70d59eba2598d3a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f767a6f6f6c2f646f76652e706870)](https://packagist.org/packages/vzool/dove.php)[![License](https://camo.githubusercontent.com/dc87dda561ab119f0082278493aa7e9cf822547e49365de8a3d3a9e92f030270/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f767a6f6f6c2f646f76652e706870)](https://packagist.org/packages/vzool/dove.php)

Dove is a notification system based on the file storage system to deliver messages, it is working as a one-direction stream of data from the server to the clients. So, the server just puts the messages, and later the clients will check for any updates on their own schedules.

DNFS by default will store all its data in `.dove` directory in the same directory where `dove.php` is located, this can be changed by `$path` argument in the constructor:

```
# constructor
$dove = new Dove(
    string $client, # client address used to reference.
    int $expiration_in_days = 0, # disabled by default, store forever without removing any.
    int $integrity = Dove::INTEGRITY_ALL, # level of integrity of the messages.
    string $cmd = '*', # all commands allowed, otherwise start with a limited constructor without `Push` cmd.
    string $path = __DIR__ . '/'
);
```

Dove doesn't process the sent or received data in any way like encryption or encoding, so it just acts like a bridge to transfer data from server to clients. If you have some concerns like binary data just encode them by using `base64` and to maintain privacy use encryption, all that were left to the developer choices.

"**Expiration of Messages**" is temporarily stored in request memory when a new instance of Dove object is created, by default its value is zero which means disabled, otherwise it will be in days. If the expiration is disabled the DNFS will store all the messages without deleting any. So, the delete operation after expiration is calculated and old messages are removed when a Pull call is performed with a specific client.

DNFS is a lazy actor which it does not require any scheduled job to be active in order to do its job, it is only waiting for client action to update the status of the message.

"**Integrity**" is a part of zero-trust that Dove hopes to offer, and it has many options:

```
class Dove{
    const INTEGRITY_DISABLED = 0b0000;
    const INTEGRITY_GENERATE_HASH = 0b0001;
    const INTEGRITY_VERIFY_HASH = 0b0010;
    const INTEGRITY_GENERATE_SIGNATURE = 0b0100;
    const INTEGRITY_VERIFY_SIGNATURE = 0b1000;
    const INTEGRITY_ALL = 0b1111; # generate and verify for hash and signature
    # ...
}
```

In general, the generation of hash and signature will happen when a new message is pushed by the `Push` command and verification occurs when the `Read` command is called. The fastest option is `Dove::INTEGRITY_DISABLED` then (`Dove::INTEGRITY_GENERATE_HASH` or `Dove::INTEGRITY_VERIFY_HASH`), then (`Dove::INTEGRITY_GENERATE_SIGNATURE` or `Dove::INTEGRITY_VERIFY_SIGNATURE`), while the slowest option is `Dove::INTEGRITY_ALL` which it depends on the message size. So, you have to do benchmarking in order to select the best option.

To start the server it behaves similarly to the `Dove` constructor:

```
Dove::Serve(
    true, # Block the execution.
    int $expiration_in_days = 0, # disabled by default, store forever without removing any.
    int $integrity = Dove::INTEGRITY_ALL, # level of integrity of the messages.
    string $path = __DIR__ . '/'
);
```

For integrity parameter is a bitwise variable which you can combine multiple options at once like the following:

```
$dove = new Dove(
    # ..
    Dove::INTEGRITY_GENERATE_HASH | Dove::INTEGRITY_GENERATE_SIGNATURE, # generate all without verifying
    # ..
);

# AND

Dove::Serve(
    # ..
    Dove::INTEGRITY_GENERATE_HASH | Dove::INTEGRITY_GENERATE_SIGNATURE, # generate all without verifying
    # ..
);
```

### ⛔ Cryptography Matrix

[](#no_entry-cryptography-matrix)

Cryptography is only limited as an option to message integrity while transfer only, `Dove` deliver the messages as it is, without any encoding or encryption of the message contents.

FunctionCipherOptionalChangeableClient ReferenceBLAKE2b**No****No**Message HashSHA-256Yes**No**Message SignatureEd25519Yes**No**Signature Encodingbase64Yes**No**Times EncyptionXsals20 + Poly1305**No****No**Times Encodingbase64url**No****No**### ✨ Motivation

[](#sparkles-motivation)

The main idea came from the [Passky-Server](https://github.com/Rabbit-Company/Passky-Server) project chats on the [discord server](https://discord.gg/y2ZBKbW5TA) about what happened to the LastPass data breach, which affects Personally Identifiable Information (PII) and lets a bad actor uses that information to stage a Phishing-Attack. There were many ideas shared, one of them was [Zica Zajc](https://github.com/zigazajc007) who is a great man and the CEO of Passky project, he suggested that the server can store the messages and the clients will check them later. So, I thought it will be a better for everyone to consildate this idea into a usable library.

### 👀 Anatomy

[](#eyes-anatomy)

Dove is a very small library that is less than 180 LOC (lines of code), and the core implementation took only about 59%, 10% for HTTP handling and the rest is for testing.

Yes, one single file has them all, `dove.php` file contains the implementation, HTTP router, and testing, isn't this great? 😋✌️

In fact, Dove is a special library in which you can use the single file `dove.php`, or install it via composer without any namespaces required. Both of these methods will make you use the full functions of the library.

**Dove Storage Data Structure (DSDS)**

[![dove-storage-system](images/dove-storage-system.png)](images/dove-storage-system.png)

The `.dove` directory can be in a public path with a directory listing feature if it does support by the web server, but you can also put it in a private location and DNFS will be the only access point to those data.

[![storage-data-file-content](images/storage-data-file-content.png)](images/storage-data-file-content.png)[![storage-hash-file-content](images/storage-hash-file-content.png)](images/storage-hash-file-content.png)[![storage-signature-file-content](images/storage-signature-file-content.png)](images/storage-signature-file-content.png)

**REST API Pull Request**

[![rest-api-pull-request](images/rest-api-pull-request.png)](images/rest-api-pull-request.png)

That was a list of times, in descending order from the newest to the old. So, by selecting a time you can ask for the latest messages after that time, or read the message contents.

**REST API Pull Request After Some Time**

[![rest-api-pull-request](images/rest-api-pull-request-after-time.png)](images/rest-api-pull-request-after-time.png)

**REST API Pull Request After Last Time**

[![rest-api-pull-request](images/rest-api-pull-request-after-last-time.png)](images/rest-api-pull-request-after-last-time.png)

**REST API Read Request**

[![rest-api-pull-request](images/rest-api-read-request.png)](images/rest-api-read-request.png)

DNFS tries to implement zero-trust by making a clear border between inside and outside, so it always encodes times automatically, and the key used to encode/decode will be changed automatically, according to `dove.php` contents, file state and location.

If `dove.php` identity changed then `.dove` entire folder will be deleted automatically.

So, if the client got some time references then the `dove.php` contents got updated somehow or the file location changed, then the old references will not work unless the client asks for new references, and then the client can get the rest of the messages with updated references.

**REST API Read Request with Invalid Signature**

[![rest-api-pull-request-invalid-signature](images/rest-api-read-request-invalid-signature.png)](images/rest-api-read-request-invalid-signature.png)

Here the signature is invalid while the hash is valid because the hash is about the message content only, while the signature involves the source code of `dove.php` itself as the source of truth, which has changed and makes all new keypair, then all past signatures are invalid by default. In a normal situation, and while messages are in transmission the `dove.php` file should not be changed, except if there is an urgent update, so the developer later can decide if this is acceptable or cancel all messages and create new ones if needed.

**REST API Read Request with Missing Message**

[![rest-api-pull-request-missing](images/rest-api-read-request-missing.png)](images/rest-api-read-request-missing.png)

### 🏢 Requirements

[](#office-requirements)

- PHP 7.3+

### ⚓ Installation & Usage

[](#anchor-installation--usage)

Dove project will do its best to be compatible with all its released versions, so in future development releases, there will be no breaking changes.

#### 🔧 Single File Library (Server-Side)

[](#wrench-single-file-library-server-side)

The whole library is just a single file called `dove.php`, so you can just copy and paste it where ever is relevant to you.

Use the following when you want to process messages:

```