Enhanced Digest Authentication, JWT Authentication, Certificate Management & RFC Compliance

.gitignore

@@ -269,3 +269,8 @@ docs/Getting-Started/Samples.md
 
 # Dump Folder
 Dump
+examples/certs/*-public.pem
+examples/certs/*-private.pem
+tests/certs/*
+/examples/certs
+examples/Authentication/certs/*

.vscode/settings.json

@@ -38,5 +38,13 @@
     "javascript.format.insertSpaceBeforeFunctionParenthesis": false,
     "[yaml]": {
         "editor.tabSize": 2
+    },
+    "markdownlint.config": {
+        "default": true,
+        "MD045": false,
+        "MD033": false,
+        "MD026": {
+            "punctuation": ".,;:"
+        }
     }
 }

README.md

@@ -1,6 +1,6 @@
-<p align="center">
+<h1 align="center">
     <img src="https://github.com/Badgerati/Pode/raw/develop/images/icon-new.svg?raw=true" width="250" />
-</p>
+</h1>
 
 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/Badgerati/Pode/master/LICENSE.txt)
 [![Documentation](https://img.shields.io/github/v/release/badgerati/pode?label=docs&logo=readthedocs&logoColor=white)](https://badgerati.github.io/Pode)
@@ -53,36 +53,37 @@ Then navigate to `http://127.0.0.1:8000` in your browser.
 
 ## 🚀 Features
 
-* Cross-platform using PowerShell Core (with support for PS5)
-* Docker support, including images for ARM/Raspberry Pi
-* Azure Functions, AWS Lambda, and IIS support
-* OpenAPI specification version 3.0.x and 3.1.0
-* OpenAPI documentation with Swagger, Redoc, RapidDoc, StopLight, OpenAPI-Explorer and RapiPdf
-* Listen on a single or multiple IP(v4/v6) address/hostnames
-* Cross-platform support for HTTP(S), WS(S), SSE, SMTP(S), and TCP(S)
-* Host REST APIs, Web Pages, and Static Content (with caching)
-* Support for custom error pages
-* Request and Response compression using GZip/Deflate
-* Multi-thread support for incoming requests
-* Inbuilt template engine, with support for third-parties
-* Async timers for short-running repeatable processes
-* Async scheduled tasks using cron expressions for short/long-running processes
-* Supports logging to CLI, Files, and custom logic for other services like LogStash
-* Cross-state variable access across multiple runspaces
-* Restart the server via file monitoring, or defined periods/times
-* Ability to allow/deny requests from certain IP addresses and subnets
-* Basic rate limiting for IP addresses and subnets
-* Middleware and Sessions on web servers, with Flash message and CSRF support
-* Authentication on requests, such as Basic, Windows and Azure AD
-* Authorisation support on requests, using Roles, Groups, Scopes, etc.
-* Support for dynamically building Routes from Functions and Modules
-* Generate/bind self-signed certificates
-* Secret management support to load secrets from vaults
-* Support for File Watchers
-* In-memory caching, with optional support for external providers (such as Redis)
-* (Windows) Open the hosted server as a desktop application
-* FileBrowsing support
-* Localization (i18n) in Arabic, German, Spanish, France, Italian, Japanese, Korean, Polish, Portuguese, and Chinese
+- ✅ Cross-platform using PowerShell Core (with support for PS5)
+- ✅ Docker support, including images for ARM/Raspberry Pi
+- ✅ Azure Functions, AWS Lambda, and IIS support
+- ✅ OpenAPI specification version 3.0.x and 3.1.0
+- ✅ OpenAPI documentation with Swagger, Redoc, RapidDoc, StopLight, OpenAPI-Explorer and RapiPdf
+- ✅ Listen on a single or multiple IP(v4/v6) addresses/hostnames
+- ✅ Cross-platform support for HTTP(S), WS(S), SSE, SMTP(S), and TCP(S)
+- ✅ Host REST APIs, Web Pages, and Static Content (with caching)
+- ✅ Support for custom error pages
+- ✅ Request and Response compression using GZip/Deflate
+- ✅ Multi-thread support for incoming requests
+- ✅ Inbuilt template engine, with support for third-parties
+- ✅ Async timers for short-running repeatable processes
+- ✅ Async scheduled tasks using cron expressions for short/long-running processes
+- ✅ Supports logging to CLI, Files, and custom logic for other services like LogStash
+- ✅ Cross-state variable access across multiple runspaces
+- ✅ Restart the server via file monitoring, or defined periods/times
+- ✅ Ability to allow/deny requests from certain IP addresses and subnets
+- ✅ Basic rate limiting for IP addresses and subnets
+- ✅ Middleware and Sessions on web servers, with Flash message and CSRF support
+- ✅ Authentication on requests, such as Basic, Windows and Azure AD
+- ✅ Authorisation support on requests, using Roles, Groups, Scopes, etc.
+- ✅ Enhanced authentication support, including Basic, Bearer (with JWT), Certificate, Digest, Form, OAuth2, and ApiKey (with JWT).
+- ✅ Support for dynamically building Routes from Functions and Modules
+- ✅ Generate/bind self-signed certificates
+- ✅ Secret management support to load secrets from vaults
+- ✅ Support for File Watchers
+- ✅ In-memory caching, with optional support for external providers (such as Redis)
+- ✅ (Windows) Open the hosted server as a desktop application
+- ✅ FileBrowsing support
+- ✅ Localization (i18n) in Arabic, German, Spanish, France, Italian, Japanese, Korean, Polish, Portuguese,Dutch and Chinese
 
 ## 📦 Install
 

docs/Tutorials/Authentication/Methods/ApiKey.md

@@ -26,13 +26,13 @@ Start-PodeServer {
 }
 ```
 
-By default, Pode will look for an `X-API-KEY` header in the request. You can change this to Cookie or Query by using the `-Location` parameter. To change the name of what Pode looks for, you can use `-LocationName`.
+By default, Pode will look for an `X-API-KEY` header in the request. You can change this to Cookie or Query by using the `-ApiKeyLocation` parameter. To change the name of what Pode looks for, you can use `-LocationName`.
 
 For example, to look for an `appId` query value:
 
 ```powershell
 Start-PodeServer {
-    New-PodeAuthScheme -ApiKey -Location Query -LocationName 'appId' | Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
+    New-PodeAuthScheme -ApiKey -ApiKeyLocation Query -LocationName 'appId' | Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
         param($key)
 
         # check if the key is valid, and get user

docs/Tutorials/Authentication/Methods/Bearer.md

@@ -6,13 +6,30 @@ Bearer authentication lets you authenticate a user based on a token, with option
 Authorization: Bearer <token>
 ```
 
+!!! note
+    **`New-PodeAuthScheme -Bearer` is deprecated.** Please use **`New-PodeAuthBearerScheme`**.
+
 ## Setup
 
-To start using Bearer authentication in Pode you can use `New-PodeAuthScheme -Bearer`, and then pipe the returned object into [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth). The parameter supplied to the [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth) function's ScriptBlock is the `$token` from the Authorization token:
+To start using Bearer authentication in Pode, call **`New-PodeAuthBearerScheme`**, and then pipe the returned object into [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth). The parameter supplied to the [`Add-PodeAuth`](../../../../Functions/Authentication/Add-PodeAuth) function's **ScriptBlock** is the `$token` from the Authorization header.
+
+```powershell
+Start-PodeServer {
+    New-PodeAuthBearerScheme | Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
+        param($token)
+
+        # check if the token is valid, and get user
+
+        return @{ User = $user }
+    }
+}
+```
+
+By default, Pode will look for a token in the **`Authorization`** header, verifying that it starts with the **`Bearer`** tag. You can customize this tag via **`-HeaderTag`**. You can also change the token extraction location to the **query string** using **`-Location Query`**. For the **`-Location query`** the standard tag is **`access_token`**:
 
 ```powershell
 Start-PodeServer {
-    New-PodeAuthScheme -Bearer | Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
+    New-PodeAuthBearerScheme -Location Query | Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
         param($token)
 
         # check if the token is valid, and get user
@@ -22,13 +39,129 @@ Start-PodeServer {
 }
 ```
 
-By default, Pode will check if the request's header contains an `Authorization` key, and whether the value of that key starts with `Bearer` tag. The `New-PodeAuthScheme -Bearer` function can be supplied parameters to customise the tag using `-HeaderTag`.
+**Note:** Per [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750), using the Authorization header is recommended for sending bearer tokens. Query parameters should only be used when headers are not feasible, as query strings may be logged in URLs, potentially exposing sensitive information.
+
+## JWT Support
+
+`New-PodeAuthBearerScheme` supports **JWT authentication** with various security levels and algorithms. Set **`-AsJWT`** to enable JWT validation. Depending on the chosen algorithm, you can specify:
+
+- **HMAC**-based secret keys (`-Secret`)
+- **Certificate**-based parameters (`-Certificate`, `-CertificateThumbprint`, `-CertificateName`, `-X509Certificate`, `-SelfSigned`)
+- The **RSA padding scheme** (`-RsaPaddingScheme`)
+- The **JWT verification mode** (`-JwtVerificationMode`)
+
+### JwtVerificationMode
+
+Defines how aggressively JWT claims should be checked:
+
+- **Strict**: Requires all standard claims:
+  - `exp` (Expiration Time)
+  - `nbf` (Not Before)
+  - `iat` (Issued At)
+  - `iss` (Issuer)
+  - `aud` (Audience)
+  - `jti` (JWT ID)
+
+- **Moderate**: Allows missing `iss` (Issuer) and `aud` (Audience) but still checks expiration (`exp`).
+- **Lenient**: Ignores missing `iss` and `aud`, only verifies expiration (`exp`), not-before (`nbf`), and issued-at (`iat`).
+
+### HMAC Example
+
+Here’s an example using **HMAC** (HS256) JWT validation:
+
+```powershell
+Start-PodeServer {
+    New-PodeAuthBearerScheme `
+        -AsJWT `
+        -Algorithm 'HS256' `
+        -Secret (ConvertTo-SecureString "MySecretKey" -AsPlainText -Force) `
+        -JwtVerificationMode 'Strict' |
+    Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
+        param($token)
+
+        # validate and decode JWT, then extract user details
+
+        return @{ User = $user }
+    }
+}
+```
+
+### Certificate-Based Example
+
+For **RSA/ECDSA** JWT validation, you can specify a **certificate** or **thumbprint** instead of a secret key. Pode will infer the appropriate signing algorithms (e.g., RS256, ES256) from the certificate. For instance, using a local **PFX** certificate file:
+
+```powershell
+Start-PodeServer {
+    New-PodeAuthBearerScheme `
+        -AsJWT `
+        -Algorithm 'RS256' `
+        -Certificate "C:\path\to\cert.pfx" `
+        -CertificatePassword (ConvertTo-SecureString "CertPass" -AsPlainText -Force) `
+        -JwtVerificationMode 'Moderate' |
+    Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
+        param($token)
+
+        # validate JWT and extract user
+
+        return @{ User = $user }
+    }
+}
+```
+
+### Self-Signed Certificate Example
+
+For testing purposes or internal deployments, you can use the **`-SelfSigned`** parameter, which automatically generates an **ephemeral self-signed ECDSA certificate** (ES384) for JWT signing. This avoids the need to manually create and manage certificate files.
+
+#### Example:
+
+```powershell
+Start-PodeServer {
+    New-PodeAuthBearerScheme `
+        -AsJWT `
+        -SelfSigned |
+    Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
+        param($token)
+
+        # validate JWT and extract user
+
+        return @{ User = $user }
+    }
+}
+```
+
+This is equivalent to manually generating a self-signed ECDSA certificate and passing it via `-X509Certificate`:
+
+```powershell
+Start-PodeServer {
+    $x509Certificate = New-PodeSelfSignedCertificate `
+        -CommonName 'JWT Signing Certificate' `
+        -KeyType ECDSA `
+        -KeyLength 384 `
+        -CertificatePurpose CodeSigning `
+        -Ephemeral
+
+    New-PodeAuthBearerScheme `
+        -AsJWT `
+        -X509Certificate $x509Certificate |
+    Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
+        param($token)
+
+        # validate JWT and extract user
+
+        return @{ User = $user }
+    }
+}
+```
+
+Using `-SelfSigned` simplifies setup by automatically handling certificate creation and disposal, making it a convenient choice for local development and testing scenarios.
+
+## Scope Validation
 
-You can also optionally return a `Scope` property alongside the `User`. If you specify any scopes with [`New-PodeAuthScheme`](../../../../Functions/Authentication/New-PodeAuthScheme) then it will be validated in the Bearer's post validator - a 403 will be returned if the scope is invalid.
+You can optionally include `-Scope` when creating the scheme. Pode will validate any returned `Scope` from your auth **ScriptBlock** against the scheme’s required scopes. If the scope is invalid, Pode will return 403 (Forbidden).
 
 ```powershell
 Start-PodeServer {
-    New-PodeAuthScheme -Bearer -Scope 'write' | Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
+    New-PodeAuthBearerScheme -Scope 'write' | Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
         param($token)
 
         # check if the token is valid, and get user
@@ -38,19 +171,21 @@ Start-PodeServer {
 }
 ```
 
+
+
 ## Middleware
 
-Once configured you can start using Bearer authentication to validate incoming requests. You can either configure the validation to happen on every Route as global Middleware, or as custom Route Middleware.
+Once configured, you can instruct Pode to validate every request with Bearer authentication by using **Global Middleware**, or you can require it on individual Routes.
 
-The following will use Bearer authentication to validate every request on every Route:
+**Global Middleware Example** – Validate **every** incoming request:
 
 ```powershell
 Start-PodeServer {
     Add-PodeAuthMiddleware -Name 'GlobalAuthValidation' -Authentication 'Authenticate'
 }
 ```
 
-Whereas the following example will use Bearer authentication to only validate requests on specific a Route:
+**Route-Specific Example** – Validate only on a certain Route:
 
 ```powershell
 Start-PodeServer {
@@ -60,46 +195,42 @@ Start-PodeServer {
 }
 ```
 
-## JWT
-
-You can supply a JWT using Bearer authentication, for more details [see here](../JWT).
-
 ## Full Example
 
-The following full example of Bearer authentication will setup and configure authentication, validate the token, and then validate on a specific Route:
+Below is a complete example demonstrating Bearer authentication with JWT. It configures a server, sets up JWT validation with a shared secret, and validates requests on one route (`/cpu`) while leaving another (`/memory`) open:
 
 ```powershell
 Start-PodeServer {
     Add-PodeEndpoint -Address * -Port 8080 -Protocol Http
 
-    # setup bearer authentication to validate a user
-    New-PodeAuthScheme -Bearer | Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
-        param($token)
-
-        # here you'd check a real storage, this is just for example
-        if ($token -eq 'test-token') {
-            return @{
-                User = @{
-                    'ID' ='M0R7Y302'
-                    'Name' = 'Morty'
-                    'Type' = 'Human'
+    # Setup Bearer authentication to validate a user via JWT
+    New-PodeAuthBearerScheme -AsJWT -Algorithm 'HS256' -Secret (ConvertTo-SecureString "MySecretKey" -AsPlainText -Force) -JwtVerificationMode 'Lenient' |
+        Add-PodeAuth -Name 'Authenticate' -Sessionless -ScriptBlock {
+            param($token)
+
+            # Example: in real usage, you would decode/verify the JWT fully
+            if ($token -eq 'test-token') {
+                return @{
+                    User = @{
+                        'ID'   = 'M0R7Y302'
+                        'Name' = 'Morty'
+                        'Type' = 'Human'
+                    }
+                    # Scope = 'read'
                 }
-                # Scope = 'read'
             }
-        }
 
-        # authentication failed
-        return $null
-    }
+            # authentication failed
+            return $null
+        }
 
-    # check the request on this route against the authentication
+    # Validate against the authentication on this route
     Add-PodeRoute -Method Get -Path '/cpu' -Authentication 'Authenticate' -ScriptBlock {
         Write-PodeJsonResponse -Value @{ 'cpu' = 82 }
     }
 
-    # this route will not be validated against the authentication
+    # Open route, no auth required
     Add-PodeRoute -Method Get -Path '/memory' -ScriptBlock {
         Write-PodeJsonResponse -Value @{ 'memory' = 14 }
     }
 }
-```