Merge pull request #227 from ember-nexus/github-issue/131

Add `/.well-known/security.txt` endpoint, documentation for it and (d…

CHANGELOG.md

@@ -5,6 +5,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+### Added
+- Add `/.well-known/security.txt` endpoint, documentation for it and (disabled) file check on container startup which
+  will crash the container intentionally if the file is missing. Check will be enabled with the release of version
+  0.2.0, see also #225. Closes issue #131.
 ### Changed
 - Constants are changed to contain type declarations, closes #211.
 - Remove timeout from PHP-tasks, closes #220. CI timeouts still apply.

docker/supervisord/docker-entrypoint.sh

@@ -2,6 +2,13 @@
 
 set -e
 
+#todo: enable intentional container crash with the release of version 0.2.0
+#if [ ! -f /well-known-security.txt ]; then
+#  echo "Error: Unable to start Ember Nexus API due to missing security.txt file at path /well-known-security.txt ."
+#  echo "See https://ember-nexus.github.io/api/ for details."
+#  exit 1
+#fi
+
 mkdir -p /var/www/html/var/logs
 touch /var/www/html/var/logs/log.log
 

docs/_sidebar.md

@@ -51,6 +51,7 @@
     - [<span class="method-post">POST</span>` /search -` Search](/api-endpoints/search/post-search)
   - **System Endpoints**
     - [<span class="method-get">GET</span>` /instance-configuration -` Get Instance Configuration](/api-endpoints/system/get-instance-configuration)
+    - [<span class="method-get">GET</span>` /.well-known/security.txt -` Get Well Known security.txt](/api-endpoints/system/get-well-known-security-txt)
   - **Error Endpoints**
     - [<span class="method-get">GET</span>` /error/400/bad-content`](/api-endpoints/error/get-400-bad-content)
     - [<span class="method-get">GET</span>` /error/400/forbidden-property`](/api-endpoints/error/get-400-forbidden-property)

docs/api-endpoints/system/get-well-known-security-txt.md

@@ -0,0 +1,93 @@
+# <span class="method-get">GET</span>` /.well-known/security.txt -` Get Well Known security.txt
+
+<!-- panels:start -->
+<!-- div:left-panel -->
+
+Returns the configured security.txt file.
+
+See [https://securitytxt.org/](https://securitytxt.org/) for details regarding this file standard.
+
+## Request Example
+
+```bash
+curl https://api.localhost/.well-known/security.txt
+```
+
+<!-- tabs:start -->
+
+### **🟢 Success 200**
+
+<div class="code-title auto-refresh">Response Headers</div>
+
+[Response Body](./get-well-known-security-txt/200-response-header.txt ':include :type=code')
+
+<div class="code-title auto-refresh">Response Body</div>
+
+[Response Body](./get-well-known-security-txt/200-response-body.txt ':include :type=code')
+
+<!-- tabs:end -->
+
+<!-- div:right-panel -->
+
+## Internal Workflow
+
+The server returns the configured file directly.
+
+<div id="graph-container-1" class="graph-container" style="height:800px"></div>
+
+<!-- panels:end -->
+
+<script>
+G6.registerEdge('polyline-edge', {
+  draw(cfg, group) {
+    const { startPoint, endPoint } = cfg;
+    const hgap = Math.abs(endPoint.x - startPoint.x);
+
+    const path = [
+      ['M', startPoint.x, startPoint.y],
+      [
+        'C',
+        startPoint.x + hgap / 4,
+        startPoint.y,
+        endPoint.x - hgap / 2,
+        endPoint.y,
+        endPoint.x,
+        endPoint.y,
+      ],
+    ];
+    const shape = group.addShape('path', {
+      attrs: {
+        stroke: '#AAB7C4',
+        path,
+      },
+      name: 'path-shape',
+    });
+    const midPoint = {
+      x: (startPoint.x + endPoint.x) / 2,
+      y: (startPoint.y + endPoint.y) / 2,
+    };
+    const label = group.addShape('text', {
+      attrs: {
+        text: cfg.label + '###########',
+        x: midPoint.x,
+        y: midPoint.y,
+        textAlign: 'center',
+        textBaseline: 'middle',
+        fill: '#000',
+        fontSize: 14,
+      },
+      name: 'label-shape',
+    });
+    return shape;
+  },
+});
+renderWorkflow(document.getElementById('graph-container-1'), {
+  nodes: [
+    { id: 'init', ...workflowStart, label: 'server receives GET-request' },
+    { id: 'success200', ...workflowEndSuccess , label: "return 200"},
+  ],
+  edges: [
+    { source: 'init', target: 'success200', label: '' },
+  ],
+}, 'TB');
+</script>

docs/api-endpoints/system/get-well-known-security-txt/200-response-body.txt

@@ -0,0 +1,2 @@
+Contact: https://ember-nexus.dev/contact
+Expires: 2026-01-01T00:00:00.000Z

docs/api-endpoints/system/get-well-known-security-txt/200-response-header.txt

@@ -0,0 +1,10 @@
+Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
+Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
+Access-Control-Allow-Origin: *
+Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
+Cache-Control: no-cache, private
+Content-Type: text/plain; charset=utf-8
+Date: Fri, 22 Dec 2023 23:05:08 GMT
+Server: Unit
+Transfer-Encoding: chunked
+X-Powered-By: Ember-Nexus-API

src/Controller/System/GetWellKnownSecurityTxtController.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace App\Controller\System;
+
+use App\Factory\Exception\Client404NotFoundExceptionFactory;
+use App\Response\TextResponse;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\Routing\Annotation\Route;
+
+class GetWellKnownSecurityTxtController extends AbstractController
+{
+    public const string PATH_TO_WELL_KNOWN_SECURITY_TXT = '/well-known-security.txt';
+
+    public function __construct(
+        private Client404NotFoundExceptionFactory $client404NotFoundExceptionFactory
+    ) {
+    }
+
+    #[Route(
+        '/.well-known/security.txt',
+        name: 'get-well-known-security-txt',
+        methods: ['GET']
+    )]
+    public function getWellKnownSecurityTxt(): Response
+    {
+        if (!file_exists(self::PATH_TO_WELL_KNOWN_SECURITY_TXT)) {
+            throw $this->client404NotFoundExceptionFactory->createFromTemplate();
+        }
+        $wellKnownSecurityTxtContent = \Safe\file_get_contents(self::PATH_TO_WELL_KNOWN_SECURITY_TXT);
+
+        return new TextResponse($wellKnownSecurityTxtContent);
+    }
+}

tests/ExampleGenerationCommand/docker-compose.yml

@@ -7,6 +7,7 @@ services:
       - "80"
     volumes:
       - ../../:/var/www/html
+      - ./well-known-security.txt:/well-known-security.txt
 
   ember-nexus-neo4j:
     container_name: ember-nexus-neo4j

tests/ExampleGenerationCommand/well-known-security.txt

@@ -0,0 +1,2 @@
+Contact: https://ember-nexus.dev/contact
+Expires: 2026-01-01T00:00:00.000Z

tests/ExampleGenerationController/System/GetWellKnownSecurityTxtTest.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace App\tests\ExampleGenerationController\System;
+
+use App\Tests\ExampleGenerationController\BaseRequestTestCase;
+
+class GetWellKnownSecurityTxtTest extends BaseRequestTestCase
+{
+    private const string PATH_TO_ROOT = __DIR__.'/../../../';
+
+    public function testGetWellKnownSecurityTxtSuccess(): void
+    {
+        $response = $this->runGetRequest('/.well-known/security.txt', null);
+        $documentationHeadersPath = 'docs/api-endpoints/system/get-well-known-security-txt/200-response-header.txt';
+        $documentationBodyPath = 'docs/api-endpoints/system/get-well-known-security-txt/200-response-body.txt';
+        $this->assertHeadersInDocumentationAreIdenticalToHeadersFromRequest(
+            self::PATH_TO_ROOT,
+            $documentationHeadersPath,
+            $response
+        );
+        $this->assertBodyInDocumentationIsIdenticalToBodyFromRequest(
+            self::PATH_TO_ROOT,
+            $documentationBodyPath,
+            $response,
+            false,
+            [
+                'Expires',
+            ]
+        );
+    }
+}

tests/ExampleGenerationController/docker-compose.yml

@@ -7,6 +7,7 @@ services:
       - "80"
     volumes:
       - ../../:/var/www/html
+      - ./well-known-security.txt:/well-known-security.txt
 
   ember-nexus-neo4j:
     container_name: ember-nexus-neo4j

tests/ExampleGenerationController/well-known-security.txt

@@ -0,0 +1,2 @@
+Contact: https://ember-nexus.dev/contact
+Expires: 2026-01-01T00:00:00.000Z

tests/FeatureTests/Endpoint/System/GetWellKnownSecurityTxtTest.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace App\tests\FeatureTests\Endpoint\System;
+
+use App\Tests\FeatureTests\BaseRequestTestCase;
+
+class GetWellKnownSecurityTxtTest extends BaseRequestTestCase
+{
+    public function testGetWellKnownSecurityTxt(): void
+    {
+        $response = $this->runGetRequest('/.well-known/security.txt', null);
+        $this->assertIsTextResponse($response, 200);
+    }
+}

tests/FeatureTests/docker-compose-neo4j-5.1.yml

@@ -7,6 +7,7 @@ services:
       - "80"
     volumes:
       - ../../:/var/www/html
+      - ./well-known-security.txt:/well-known-security.txt
 
   ember-nexus-neo4j:
     container_name: ember-nexus-neo4j

tests/FeatureTests/docker-compose-neo4j-5.12.yml

@@ -7,6 +7,7 @@ services:
       - "80"
     volumes:
       - ../../:/var/www/html
+      - ./well-known-security.txt:/well-known-security.txt
 
   ember-nexus-neo4j:
     container_name: ember-nexus-neo4j

tests/FeatureTests/docker-compose-neo4j-5.13.yml

@@ -7,6 +7,7 @@ services:
       - "80"
     volumes:
       - ../../:/var/www/html
+      - ./well-known-security.txt:/well-known-security.txt
 
   ember-nexus-neo4j:
     container_name: ember-nexus-neo4j

tests/FeatureTests/well-known-security.txt

@@ -0,0 +1,2 @@
+Contact: https://ember-nexus.dev/contact
+Expires: 2026-01-01T00:00:00.000Z