Rest server

docs/RestServer/Addons.md

@@ -0,0 +1,108 @@
+## RestServer Plugin
+In this secion of you will learn how to make a `neo-cli` plugin that integrates with `RestServer`
+plugin. Lets take a look at [Example Plugin](/examples/RestServerPlugin).
+
+- No reference to `RestServer` is reqired.
+- Requires DotNet 7.0
+
+## Folder Structure
+```bash
+Project
+├── Controllers
+│   └── ExampleController.cs
+├── ExamplePlugin.cs
+├── ExamplePlugin.csproj
+├── Exceptions
+│   └── CustomException.cs
+└── Models
+    └── ErrorModel.cs
+```
+The only thing that is important here is the `controllers` folder. This folder is required for the `RestServer`
+plugin to register the controllers in its web server. This location is where you put all your controllers.
+
+## Controllers
+The `controller` class is the same as ASP.Net Core's. Controllers must have their attribute set
+as `[ApiController]` and inherent from `ControllerBase`.
+
+## Swagger Controller
+A `Swagger` controller uses special attributes that are set on your controller's class.
+
+**Controller Class Attributes**
+- `[Produces(MediaTypeNames.Application.Json)]` (_Required_)
+- `[Consumes(MediaTypeNames.Application.Json)]` (_Required_)
+- `[ApiExplorerSettings(GroupName = "v1")]`
+  - **GroupName** - _is which version of the API you are targeting._
+- `[ProducesResponseType(StatusCodes.Status400BadRequest, Type = typeof(ErrorModel))]` (_Required_)
+  - **Type** - _Must have a base class of [error](#error-class)._
+
+## Error Class
+Needs to be the same as `RestServer` of else there will be some inconsistencies
+with end users not knowing which type to use. This class can be `public` or `internal`.
+Properties `Code`, `Name` and `Message` values can be whatever you desire.
+
+**Model**
+```csharp
+public class ErrorModel
+{
+    public int Code { get; set; };
+    public string Name { get; set; };
+    public string Message { get; set; };
+}
+```
+
+## Controller Actions
+Controller actions need to have special attributes as well as code comments.
+
+- `[ProducesResponseType(StatusCodes.Status200OK, Type = typeof(string))]`
+
+HTTP status code `200 (OK)` is required with return type defined. You can use more than one attribute. One per HTTP status code.
+
+### Action Example
+```csharp
+[HttpGet("contracts/{hash:required}/sayHello", Name = "GetSayHello")]
+[ProducesResponseType(StatusCodes.Status204NoContent)]
+[ProducesResponseType(StatusCodes.Status200OK, Type = typeof(string))]
+public IActionResult GetSayHello(
+    [FromRoute(Name = "hash")]
+    UInt160 scripthash)
+{
+    if (scripthash == UInt160.Zero)
+        return NoContent();
+    return Ok($"Hello, {scripthash}");
+}
+```
+Notice that the _above_ example also returns with HTTP status code of `204 No Content`.
+This action `route` also extends the `contracts` API. Adding method `sayHello`. Routes
+can be what you like as well. But if you want to extend on any existing controller you
+must use existing routes paths.
+
+### Path(s)
+- `/api/v1/contracts/`
+- `/api/v1/ledger/`
+- `/api/v1/node/`
+- `/api/v1/tokens`
+- `/api/v1/Utils/`
+
+### Excluded Path(s)
+- `/api/v1/wallet/`
+
+_for security reasons_.
+
+### Code Comments for Swagger
+```csharp
+/// <summary>
+/// 
+/// </summary>
+/// <param name="" example=""></param>
+/// <returns></returns>
+/// <response code="200">Successful</response>
+/// <response code="400">An error occurred. See Response for details.</response>
+```
+
+Also note that you need to have `GenerateDocumentationFile` enabled in your
+`.csproj` file. The `xml` file that is generated; in our case would be `RestServerPlugin.xml`.
+This file gets put in same directory `Plugins/RestServerPlugin/` which is in the root of `neo-node`
+executable folder. Where you will see `neo-cli.exe`.
+
+File `RestServerPlugin.xml` will get added to `Swagger` automatically by the `RestServer`
+plugin.

docs/RestServer/ConfigFile.md

@@ -0,0 +1,56 @@
+## Table
+
+| Name | Type | Description |
+| :--- | :---: | :--- |
+|**Network**|_uint32_|_Network you would like the `RestServer` to be enabled on._|
+|**BindAddress**|_string_|_Ip address of the interface you want to bind too._|
+|**Port**|_uint32_|_Port number to bind too._|
+|**KeepAliveTimeout**|_uint32_|_Time to keep the request alive, in seconds._|
+|**SslCertFile**|_string_|_Is the path and file name of a certificate file, relative to the directory that contains the node's executable files._|
+|**SslCertPassword**|_string_|_Is the password required to access the `X.509` certificate data._|
+|**TrustedAuthorities**|_StringArray_|_Tumbprints of the of the last certificate authority in the chain._|
+|**EnableBasicAuthentication**|_boolean_|_enables basic authentication._|
+|**RestUser**|_string_|_Basic authentication's `username`._|
+|**RestPass**|_string_|_Basic authentication's `password`._|
+|**EnableCors**|_boolean_|_Enables Cross-origin resource sharing (`CORS`). Note by default it enables `*` any origin._|
+|**AllowOrigins**|_StringArray_|_A list of the origins to allow. Note needs to add origins for basic auth to work with `CORS`._|
+|**DisableControllers**|_StringArray_|_A list of `controllers` to be disabled. Requires restart of the node, if changed._|
+|**EnableCompression**|_boolean_|_Enables `GZip` data compression._|
+|**CompressionLevel**|_enum_|_Compression level. Values can be `Fastest`, `Optimal`, `NoCompression` or `SmallestSize`_|
+|**EnableForwardedHeaders**|_boolean_|_Enables response/request headers for proxy forwarding. (data center usage)_|
+|**EnableSwagger**|_boolean_|_Enables `Swagger` with `Swagger UI` for the rest services._|
+|**MaxPageSize**|_uint32_|_Max page size for searches on `Ledger`/`Contracts` route._|
+|**MaxConcurrentConnections**|_int64_|_Max allow concurrent HTTP connections._|
+|**MaxTransactionFee**|_int64_|_Max transaction fee for `wallet` transfers._|
+|**MaxInvokeGas**|_int64_|_Max gas to be invoked on the `Neo` virtual machine._|
+|**WalletSessionTimeout**|_uint32_|_When `wallet` session expires, in seconds._|
+
+## Default "Config.json" file
+```json
+{
+  "PluginConfiguration": {
+    "Network": 860833102,
+    "BindAddress": "127.0.0.1",
+    "Port": 10339,
+    "KeepAliveTimeout": 120,
+    "SslCertFile": "",
+    "SslCertPassword": "",
+    "TrustedAuthorities": [],
+    "EnableBasicAuthentication": false,
+    "RestUser": "",
+    "RestPass": "",
+    "EnableCors": true,
+    "AllowOrigins": [],
+    "DisableControllers": [ "WalletController" ],
+    "EnableCompression": true,
+    "CompressionLevel": "SmallestSize",
+    "EnableForwardedHeaders": false,
+    "EnableSwagger": true,
+    "MaxPageSize": 50,
+    "MaxConcurrentConnections": 40,
+    "MaxTransactionFee": 10000000,
+    "MaxInvokeGas": 20000000,
+    "WalletSessionTimeout": 120
+  }
+}
+```

docs/RestServer/README.md

@@ -0,0 +1,135 @@
+## RestServer
+In this section you will learn about `RestServer` plugin and how it works.
+
+See [config.json](ConfigFile.md) for information about the configurations.
+
+## Dependencies
+- **Microsoft.AspNetCore.JsonPatch.dll** `Required`
+- **Microsoft.AspNetCore.Mvc.NewtonsoftJson.dll** `Required`
+- **Microsoft.OpenApi.dll** `Swagger`
+- **Swashbuckle.AspNetCore.Swagger.dll** `Swagger`
+- **Swashbuckle.AspNetCore.SwaggerGen.dll** `Swagger`
+- **Swashbuckle.AspNetCore.SwaggerUI.dll** `Swagger`
+- **Swashbuckle.AspNetCore.Newtonsoft.dll** `Swagger`
+- **RestServer.xml** `Swagger UI`
+
+These files go in the same directory as the `RestServer.dll`. In neo-cli
+`plugins/RestServer/` folder.
+
+## Response Headers
+| Name | Value(s) | Description |
+| :---: | --- | :--- |
+|**server**|_neo-cli/3.6.0 RestServer/3.6.0_|_`neo-cli` and `RestServer` version._|
+
+Custom headers can be added by [Neo RestServer Plugins](Addons.md).
+
+## JSON Serializer
+`RestServer` uses custom Newtonsoft Json Converters to serialize controller action
+responses and `route` parameters.
+
+**One Way Binding** - `Write` only.
+- `Neo.SmartContract.ContractState`
+- `Neo.SmartContract.NefFile`
+- `Neo.SmartContract.MethodToken`
+- `Neo.SmartContract.Native.TrimmedBlock`
+- `Neo.SmartContract.Manifest.ContractAbi`
+- `Neo.SmartContract.Manifest.ContractGroup`
+- `Neo.SmartContract.Manifest.ContractManifest`
+- `Neo.SmartContract.Manifest.ContractPermission`
+- `Neo.SmartContract.Manifest.ContractPermissionDescriptor`
+- `Neo.Network.P2P.Payloads.Block`
+- `Neo.Network.P2P.Payloads.Header`
+- `Neo.Network.P2P.Payloads.Signer`
+- `Neo.Network.P2P.Payloads.TransactionAttribute`
+- `Neo.Network.P2P.Payloads.Transaction`
+- `Neo.Network.P2P.Payloads.Witness`
+
+**Two Way Binding** - `Read` & `Write`
+- `System.Guid`
+- `System.ReadOnlyMemory<T>`
+- `Neo.BigDecimal`
+- `Neo.UInt160`
+- `Neo.UInt256`
+- `Neo.Cryptography.ECC.ECPoint`
+- `Neo.VM.Types.Array`
+- `Neo.VM.Types.Boolean`
+- `Neo.VM.Types.Buffer`
+- `Neo.VM.Types.ByteString`
+- `Neo.VM.Types.Integer`
+- `Neo.VM.Types.InteropInterface`
+- `Neo.VM.Types.Null`
+- `Neo.VM.Types.Map`
+- `Neo.VM.Types.Pointer`
+- `Neo.VM.Types.StackItem`
+- `Neo.VM.Types.Struct`
+
+## Remote Endpoints
+Parametes `{hash}` can be any Neo N3 address or scripthash; `{address}` can be any Neo N3 address **only**; `{number}` and `{index}` can be any _**uint32**_.
+
+**Parameter Examples**
+- `{hash}` - _0xef4073a0f2b305a38ec4050e4d3d28bc40ea63f5_ **or** _NiHURyS83nX2mpxtA7xq84cGxVbHojj5Wc_
+- `{address}` - _NiHURyS83nX2mpxtA7xq84cGxVbHojj5Wc_
+- `{number}` - _1_
+- `{index}` - _2500000_
+
+**Paths**
+- Utils
+  - `[GET]` `/api/v1/utils/{hash}/address`
+  - `[GET]` `/api/v1/utils/{address}/scripthash`
+  - `[GET]` `/api/v1/utils/{hash}/{address}/validate`
+- Node
+  - `[GET]` `/api/v1/node/peers`
+  - `[GET]` `/api/v1/node/plugins`
+  - `[GET]` `/api/v1/node/settings`
+- Ledger
+  - `[GET]` `/api/v1/ledger/neo/accounts`
+  - `[GET]` `/api/v1/ledger/gas/accounts`
+  - `[GET]` `/api/v1/ledger/blocks?page={number}&size={number}`
+  - `[GET]` `/api/v1/ledger/blocks/height`
+  - `[GET]` `/api/v1/ledger/blocks/{index}`
+  - `[GET]` `/api/v1/ledger/blocks/{index}/header`
+  - `[GET]` `/api/v1/ledger/blocks/{index}/witness`
+  - `[GET]` `/api/v1/ledger/blocks/{index}/transactions?page={number}&size={number}`
+  - `[GET]` `/api/v1/ledger/transactions/{hash}`
+  - `[GET]` `/api/v1/ledger/transactions/{hash}/witnesses`
+  - `[GET]` `/api/v1/ledger/transactions/{hash}/signers`
+  - `[GET]` `/api/v1/ledger/transactions/{hash}/atributes`
+  - `[GET]` `/api/v1/ledger/memorypool?page={number}&size={number}`
+  - `[GET]` `/api/v1/ledger/memorypool/verified?page={number}&size={number}`
+  - `[GET]` `/api/v1/ledger/memorypool/unverified?page={number}&size={number}`
+  - `[GET]` `/api/v1/ledger/memorypool/count`
+- Tokens
+  - `[GET]` `/api/v1/tokens/balanceof/{address}`
+  - NFTs
+    - `[GET]` `/api/v1/tokens/nep-11?page={number}&size={number}`
+    - `[GET]` `/api/v1/tokens/nep-11/count`
+    - `[GET]` `/api/v1/tokens/nep-11/{hash}/balanceof/{address}`
+  - NEP-17
+    - `[GET]` `/api/v1/tokens/nep-17?page={number}&size={number}`
+    - `[GET]` `/api/v1/tokens/nep-17/count`
+    - `[GET]` `/api/v1/tokens/nep-17/{hash}/balanceof/{address}`
+- Contracts
+  - `[GET]` `/api/v1/contracts?page={number}&size={number}`
+  - `[GET]` `/api/v1/contracts/count`
+  - `[GET]` `/api/v1/contracts/{hash}`
+  - `[GET]` `/api/v1/contracts/{hash}/abi`
+  - `[GET]` `/api/v1/contracts/{hash}/manifest`
+  - `[GET]` `/api/v1/contracts/{hash}/nef`
+  - `[GET]` `/api/v1/contracts/{hash}/storage`
+- Wallet
+  - `[POST]` `/api/v1/wallet/open`
+  - `[POST]` `/api/v1/wallet/create`
+  - `[POST]` `/api/v1/wallet/{session}/address/create`
+  - `[GET]` `/api/v1/wallet/{session}/address/list`
+  - `[GET]` `/api/v1/wallet/{session}/asset/list`
+  - `[GET]` `/api/v1/wallet/{session}/balance/list`
+  - `[POST]` `/api/v1/wallet/{session}/changepassword`
+  - `[GET]` `/api/v1/wallet/{session}/close`
+  - `[GET]` `/api/v1/wallet/{session}/delete/{address}`
+  - `[GET]` `/api/v1/wallet/{session}/export/{address}`
+  - `[GET]` `/api/v1/wallet/{session}/export`
+  - `[GET]` `/api/v1/wallet/{session}/gas/unclaimed`
+  - `[GET]` `/api/v1/wallet/{session}/key/list`
+  - `[POST]` `/api/v1/wallet/{session}/import`
+  - `[POST]` `/api/v1/wallet/{session}/import/multisigaddress`
+  - `[POST]` `/api/v1/wallet/{session}/transfer`

neo-modules.sln

@@ -43,6 +43,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SQLiteWallet", "src\SQLiteW
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "StorageDumper", "src\StorageDumper\StorageDumper.csproj", "{938D86EA-0F48-436B-9255-4AD9A8E6B9AC}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "RestServer", "src\RestServer\RestServer.csproj", "{A893825D-65FF-4FA9-85EF-16F3AC626A29}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -121,6 +123,10 @@ Global
 		{938D86EA-0F48-436B-9255-4AD9A8E6B9AC}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{938D86EA-0F48-436B-9255-4AD9A8E6B9AC}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{938D86EA-0F48-436B-9255-4AD9A8E6B9AC}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A893825D-65FF-4FA9-85EF-16F3AC626A29}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A893825D-65FF-4FA9-85EF-16F3AC626A29}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A893825D-65FF-4FA9-85EF-16F3AC626A29}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A893825D-65FF-4FA9-85EF-16F3AC626A29}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -144,6 +150,7 @@ Global
 		{8D2EE375-2E2D-45FE-A4E9-0254D12C7554} = {59D802AB-C552-422A-B9C3-64D329FBCDCC}
 		{D121D57A-512E-4F74-ADA1-24482BF5C42B} = {97E81C78-1637-481F-9485-DA1225E94C23}
 		{938D86EA-0F48-436B-9255-4AD9A8E6B9AC} = {97E81C78-1637-481F-9485-DA1225E94C23}
+		{A893825D-65FF-4FA9-85EF-16F3AC626A29} = {97E81C78-1637-481F-9485-DA1225E94C23}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {61D3ADE6-BBFC-402D-AB42-1C71C9F9EDE3}

src/RestServer/Authentication/BasicAuthenticationHandler.cs

@@ -0,0 +1,62 @@
+// Copyright (C) 2015-2023 neo-restful-plugin.
+//
+// The RestServer is free software distributed under the MIT software
+// license, see the accompanying file LICENSE in the main directory of
+// the project or http://www.opensource.org/licenses/mit-license.php
+// for more details.
+//
+// Redistribution and use in source and binary forms with or without
+// modifications are permitted.
+
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using Neo.Plugins.RestServer;
+using System.Net.Http.Headers;
+using System.Security.Claims;
+using System.Text;
+using System.Text.Encodings.Web;
+
+namespace RestServer.Authentication
+{
+    internal class BasicAuthenticationHandler : AuthenticationHandler<AuthenticationSchemeOptions>
+    {
+        public BasicAuthenticationHandler(
+            IOptionsMonitor<AuthenticationSchemeOptions> options,
+            ILoggerFactory logger,
+            UrlEncoder encoder,
+            ISystemClock clock) : base(options, logger, encoder, clock)
+        {
+        }
+
+        protected override Task<AuthenticateResult> HandleAuthenticateAsync()
+        {
+            var authHeader = Request.Headers.Authorization;
+            if (string.IsNullOrEmpty(authHeader) == false && AuthenticationHeaderValue.TryParse(authHeader, out var authValue))
+            {
+                if (authValue.Scheme.Equals("basic", StringComparison.OrdinalIgnoreCase) && authValue.Parameter != null)
+                {
+                    try
+                    {
+                        var decodedParams = Encoding.UTF8.GetString(Convert.FromBase64String(authValue.Parameter));
+                        var creds = decodedParams.Split(':', 2);
+
+                        if (creds.Length == 2 && creds[0] == RestServerSettings.Current.RestUser && creds[1] == RestServerSettings.Current.RestPass)
+                        {
+                            var claims = new[] { new Claim(ClaimTypes.NameIdentifier, creds[0]) };
+                            var identity = new ClaimsIdentity(claims, Scheme.Name);
+                            var principal = new ClaimsPrincipal(identity);
+                            var ticket = new AuthenticationTicket(principal, Scheme.Name);
+
+                            return Task.FromResult(AuthenticateResult.Success(ticket));
+                        }
+                    }
+                    catch (FormatException)
+                    {
+                    }
+                }
+            }
+            return Task.FromResult(AuthenticateResult.Fail("Authentication Failed!!!"));
+        }
+    }
+}