Packeton authentication docs.

README.md

@@ -9,9 +9,9 @@ Packeton - Private PHP package repository for vendors
 Fork of [Packagist](https://github.com/composer/packagist). 
 The Open Source alternative of [Private Packagist for vendors](https://packagist.com), that based on [Satis](https://github.com/composer/satis) and [Packagist](https://github.com/composer/packagist).
 
-### Legacy Symfony 3.4 version 
+**All** documentation here [docs.packeton.org](https://docs.packeton.org/)
 
-[Legacy docs](../1.4/README.md)
+### Legacy Symfony 3.4 version
 
 Update to 2.0. [UPGRADE.md](./UPGRADE.md)
 

docs/SUMMARY.md

@@ -10,7 +10,17 @@
 # Usage
   - [Administration](usage/README.md)
     - [Admin API](usage/api.md)
-    - [Webhooks](webhook.md)
+    - [Outgoing Webhook](webhook.md)
+      - [Intro](webhook.md)
+      - [Examples](webhook.md)
+      - [Secrets](webhook/webhook-secrets.md)
+      - [Security Policy](webhook/wh-security.md)
+      - [Testing](webhook/wh-test.md)
+    - [Update Webhooks](usage/update-packages.md)
+
   - [User Authentication](authentication.md)
     - [JWT Configuration](authentication-jwt.md)
     - [LDAP Configuration](authentication-ldap.md)
+
+# Development
+  - [Contributing](dev/contributing.md)

docs/authentication-jwt.md

@@ -100,6 +100,3 @@ Simply use the JWT, like standard API token for composer api.
 Since 2.0 composer downloads all packages in parallel, it may run more 12 request at the same time. 
 To prevent calls external LDAP provider each time for JWT token verify, the obtained LDAP user object
 placed to cache with 60 sec TTL. 
-
-
-

docs/dev/contributing.md

@@ -0,0 +1,33 @@
+# Contributing
+
+Everyone is welcome to contribute code to https://github.com/vtsykun/packeton.git
+
+### 1. Development environment.
+
+If you are running Windows, the Linux Windows Subsystem (WSL) is recommended for development.
+The code of Packeton is written in PHP.
+
+#### Requirements
+
+- PHP 8.1+
+- Redis (or Docker) for some functionality.
+- Symfony CLI / nginx / php-fpm to run the web server.
+- (optional) MySQL or PostgresSQL for the main data store, default SQLite.
+
+### 2. Get the source.
+
+Make a fork on GitHub, and then create a pull request to provide your changes.
+
+```
+git clone [email protected]:YOUR_GITHUB_NAME/packeton.git
+git checkout -b patch-1
+```
+
+### 4. Install the dependencies
+
+Run composer install
+
+```
+cd packeton
+composer install
+```

docs/usage/README.md

@@ -0,0 +1,31 @@
+# Administration
+
+This section contains information on managing your Packeton application. 
+
+Table of content
+----------------
+
+- [API Usage](api.md)
+- [Outgoing Webhook](../webhook.md)
+    - [Intro](../webhook.md#introduction)
+    - [Examples](../webhook.md#examples)
+        - [Telegram notification](../webhook.md#telegram-notification)
+        - [Slack notification](../webhook.md#slack-notification)
+        - [JIRA issue fix version](../webhook.md#jira-create-a-new-release-and-set-fix-version)
+        - [Gitlab setup auto webhook](../webhook.md#gitlab-auto-webhook)
+- [Application Roles](#application-roles)
+
+
+## Application Roles
+
+- `ROLE_USER` - minimal customer access level, these users only can read metadata only for selected packages.
+- `ROLE_FULL_CUSTOMER` - Can read all packages metadata.
+- `ROLE_MAINTAINER` -  Can submit a new package and read all metadata.
+- `ROLE_ADMIN` - Can create a new customer users, management webhooks and credentials.
+
+You can create a user and then promote to admin or maintainer via console using fos user bundle commands.
+
+```
+php bin/console packagist:user:manager username [email protected] --password=123456 --admin # create admin user
+php bin/console packagist:user:manager user1 --add-role=ROLE_MAINTAINER # Add ROLE_MAINTAINER to user user1
+```

docs/usage/api.md

@@ -0,0 +1,153 @@
+# API documentation
+
+About API authorization methods see [here](../authentication.md#composer-api-authentication)
+
+#### Submit package 
+
+```
+POST https://example.com/api/create-package?token=<api_token>
+Content-Type: application/json
+
+{
+    "repository": {
+        "url": "[email protected]:symfony/mime.git"
+    }
+}
+```
+
+#### Listing package names
+
+```
+GET https://example.com/packages/list.json?token=<api_token>
+
+# Result
+{
+  "packageNames": [
+    "[vendor]/[package]",
+    ...
+  ]
+}
+```
+
+#### List packages by vendor
+
+```
+
+GET https://example.com/packages/list.json?vendor=[vendor]&token=<api_token>
+
+{
+  "packageNames": [
+    "[vendor]/[package]",
+    ...
+  ]
+}
+```
+
+#### List packages by type
+
+```
+GET https://example.com/packages/list.json?type=[type]&token=<api_token>
+
+{
+  "packageNames": [
+    "[vendor]/[package]",
+    ...
+  ]
+}
+```
+
+
+#### Get the package git changelog
+
+Get git diff between two commits or tags. **WARNING** Working only if repository was cloned by git. 
+If you want to use this feature for GitHub you need set composer config flag no-api see here
+
+```
+GET https://example.com/packages/{name}/changelog?token=<api_token>&from=3.1.14&to=3.1.15
+
+{
+  "result": [
+    "BAP-18660: ElasticSearch 6",
+    "BB-17293: Back-office >Wrong height"
+  ],
+  "error": null,
+  "metadata": {
+    "from": "3.1.14",
+    "to": "3.1.15",
+    "package": "okvpn/platform"
+  }
+}
+```
+
+#### Getting package data
+
+This is the preferred way to access the data as it is always up-to-date, and dumped to static files so it is very efficient on our end.
+
+You can also send If-Modified-Since headers to limit your bandwidth usage 
+and cache the files on your end with the proper filemtime set according to our Last-Modified header.
+
+There are a few gotchas though with using this method:
+* It only provides you with the package metadata but not information about the maintainers, download stats or github info.
+* It contains providers information which must be ignored but can appear confusing at first. This will disappear in the future though.
+
+```
+GET https://example.com/p/[vendor]/[package].json?token=<api_token>
+
+{
+  "packages": {
+    "[vendor]/[package]": {
+      "[version1]": {
+        "name": "[vendor]/[package],
+        "description": [description],
+        // ...
+      },
+      "[version2]": {
+        // ...
+      }
+      // ...
+    }
+  }
+}
+```
+
+**Composer v2** 
+
+```
+GET https://example.com/p2/firebase/php-jwt.json
+
+
+{
+  "minified": "composer/2.0",
+  "packages": {
+    "[vendor]/[package]": [... list versions ]
+  }
+}
+```
+
+**Using the API**
+
+The JSON API for packages gives you all the infos we have including downloads, 
+dependents count, github info, etc. However, it is generated dynamically so for performance reason we cache the responses 
+for twelve hours. As such if the static file endpoint described above is enough please use it instead.
+
+```
+GET https://example.com/packages/[vendor]/[package].json?token=<api_token>
+
+{
+  "package": {
+    "name": "[vendor]/[package],
+    "description": [description],
+    "time": [time of the last release],
+    "maintainers": [list of maintainers],
+    "versions": [list of versions and their dependencies, the same data of composer.json]
+    "type": [package type],
+    "repository": [repository url],
+    "downloads": {
+      "total": [numbers of download],
+      "monthly": [numbers of download per month],
+      "daily": [numbers of download per day]
+    },
+    "favers": [number of favers]
+  }
+}
+```

docs/usage/update-packages.md

@@ -0,0 +1,63 @@
+# How to auto update packages?
+
+You can use GitLab, GitHub, and Bitbucket project post-receive hook to keep your packages up to date every time you push code.
+
+## Into
+
+Webhook API request authorization with minimum access level `ROLE_MAINTAINER`. 
+You can use `token` query parameter with `<username:api_token>` to call it. 
+
+Also support Packagist.org authorization with `username` and `apiToken` query parameters.
+
+## Bitbucket Webhooks
+To enable the Bitbucket web hook, go to your BitBucket repository,
+open the settings and select "Webhooks" in the menu. Add a new hook. Y
+ou have to enter the Packagist endpoint, containing both your username and API token.
+Enter `https://<app>/api/bitbucket?token=user:token` as URL. Save your changes and you're done.
+
+## GitLab Service
+
+To enable the GitLab service integration, go to your GitLab repository, open
+the Settings > Integrations page from the menu.
+Search for Packagist in the list of Project Services. Check the "Active" box,
+enter your `packeton.org` username and API token. Save your changes and you're done.
+
+## GitLab Group Hooks
+
+Group webhooks will apply to all projects in a group and allow to sync all projects.
+To enable the Group GitLab webhook you must have the paid plan.
+Go to your GitLab Group > Settings > Webhooks.
+Enter `https://<app>/api/update-package?token=user:token` as URL.
+
+## GitHub Webhooks
+To enable the GitHub webhook go to your GitHub repository. Click the "Settings" button, click "Webhooks".
+Add a new hook. Enter `https://<app>/api/github?token=user:token` as URL.
+
+## Gitea Webhooks
+
+To enable the Gitea web hook, go to your Gitea repository, open the settings, select "Webhooks" 
+in the menu and click on 'Add Webhook'. From the dropdown menu select Gitea.
+You have to enter the Packagist endpoint, containing both your username and API token. 
+Enter `https://<app>/api/update-package?token=user:token` as URL. 
+The HTTP method has to be POST and content type is application/json. Save your changes and you're done.
+
+## Manual hook setup
+
+If you do not use Bitbucket or GitHub there is a generic endpoint you can call manually
+from a git post-receive hook or similar. You have to do a POST request to
+`https://<app>g/api/update-package?token=user:api_token` with a request body looking like this:
+
+
+```
+{
+  "repository": {
+    "url": "PACKAGIST_PACKAGE_URL"
+  }
+}
+```
+
+You can also send a GET request with query parameter `composer_package_name`
+
+```
+curl 'https://<app>/api/update-package?token=<user:token>&composer_package_name=vender/name'
+```

docs/webhook.md

@@ -26,7 +26,7 @@ update "fix version" attribute of all the related issues from that release.
 To build a custom request payload uses Twig expression language.
 This allows you to create custom queries. Untrusted template code is evaluate in a Twig sandbox mode, so 
 you will get an error if try to get access for security sensitive information.
-By default only admin users can use Webhooks.
+By default, only admin users can use Webhooks.
 
 ```
 Exception (Twig\Sandbox\SecurityNotAllowedMethodError). Calling "setemail" method on a "Packagist\WebBundle\Entity\User" object is not allowed in "__string_template__0d2344b042278505e67568413272d80429f07ecccea43af39cb33608fa747830" at line 1.
@@ -348,4 +348,4 @@ Here you need replace `request.url` on your packagist.
 New twig functions
 -----------------
 
-See [WebhookExtension](/src/Packagist/WebBundle/Webhook/Twig/WebhookExtension.php) for details.
+See [WebhookExtension](/src/Webhook/Twig/WebhookExtension.php) for details.

docs/webhook/webhook-secrets.md

@@ -0,0 +1,60 @@
+# Manage secrets
+
+Before adding sensitive data such as API credentials to your webhook payload strongly 
+recommended to encrypt it. Secret data will not be save to database or shows on webhooks' status. 
+Alternative way you can set own visibility for webhook entity to prevent edit by other admin users.
+
+### Encrypt secrets
+
+To add secrets to your webhook, put JSON body to `Request options` field, for example
+
+```json
+{
+//     "headers"  more other options 
+    "secrets": {
+        "allowed-domains": ["api.telegram.org"],
+        "TOKEN": "167000000:AAzddkPzfgzkqzzFghiwPutin_khuylo",
+        "CHART_ID": "-1000017160005"
+    }
+}
+```
+
+[![secrets](../img/secrets.png)](../img/secrets.png)
+
+Once the form is submitted, the secret params will be encrypted and sign and cannot be changed.
+The sign algo is hmac sha256 with `APP_SECRET` as key. Digital signature required to prevent modification
+encrypted data and attack on change `allowed-domains` 
+
+#### Secrets option
+
+`allowed-domains` - you can restrict webhook call to untrusted hosts to prevent modify the change URL parameter.
+
+### Usage secrets
+
+Use secrets params in request, url or headers options, example:
+
+```
+https://api.telegram.org/bot${secrets.TOKEN}/sendMessage
+```
+
+In body
+
+```twig
+{% set request = {
+    'chat_id': '${secrets.CHART_ID}',
+    'text': 'example text'
+} %}
+{{ request|json_encode }}
+```
+
+But this example will not work.
+
+```twig
+{% set request = {
+    'chat_id': '${secrets.CHART_ID}',
+    'text': 'example text'
+} %}
+{% do log('${secrets.CHART_ID}')
+
+{{ request|json_encode }}
+```