Merge pull request #140 from sil-org/develop

Release 2.6.0 -- add TOTP endpoints

Author: briskt

.air-cdk.toml

@@ -0,0 +1,11 @@
+root = "."
+tmp_dir = "tmp"
+
+[build]
+bin = ""
+cmd = './build.sh'
+delay = 100
+exclude_dir = ["tmp", "cdk"]
+full_bin = "sam local start-api --port 8160 --template cdk/cdk.out/twosv-api-dev.template.json --env-vars cdk/env.json"
+include_ext = ["go"]
+kill_delay = "0s"

.dockerignore

@@ -2,9 +2,8 @@
 *
 
 # Whitelist required files
-!.env.encrypted
-!scripts/*
 !lambda/*
+!router/*
 !server/*
 !u2fsimulator/*
 !u2fserver/*

.github/CODEOWNERS

@@ -1,4 +1,4 @@
-* @silinternational/developers
-*.tf @silinternational/tf-devs
-*.go @silinternational/go-devs
-go.* @silinternational/go-devs
+* @sil-org/developers
+*.tf @sil-org/tf-devs
+*.go @sil-org/go-devs
+go.* @sil-org/go-devs

Dockerfile

@@ -1,32 +1,16 @@
-FROM node:22
+FROM golang:1.24
 
-ENV GO_VERSION=1.24.4
-
-ADD https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip .
-ADD https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz .
-
-RUN <<EOF
-  unzip awscli-exe-linux-x86_64.zip
-  rm awscli-exe-linux-x86_64.zip
-  ./aws/install
-  rm -rf ./aws
-
-  tar -C /usr/local -xzf go${GO_VERSION}.linux-amd64.tar.gz
-  rm go${GO_VERSION}.linux-amd64.tar.gz
-  ln -s /usr/local/go/bin/go /usr/local/bin/go
-
-  npm install --ignore-scripts --global aws-cdk
-
-  adduser user
-EOF
+RUN adduser user
 
 WORKDIR /src
 
 RUN curl -sSfL --proto "=https" https://raw.githubusercontent.com/cosmtrek/air/master/install.sh | \
-  sh -s -- -b $(go env GOPATH)/bin
+  sh -s -- -b /usr/local/bin && \
+  git config --global --add safe.directory /src
 
 COPY ./ .
-RUN go get ./...
+RUN go get ./... && \
+  git config --global --add safe.directory /src
 
 EXPOSE 8080
 

Makefile

@@ -18,7 +18,7 @@ test: clean db
 db:
 	docker compose up -d dynamo
 
-dbinit: db wait createwebauthntable createapikeytable
+dbinit: db wait createwebauthntable createapikeytable createtotptable
 
 wait:
 	sleep 5

README.md

@@ -1,18 +1,56 @@
-# A Serverless MFA API with support for WebAuthn
+# A Serverless MFA API with support for TOTP and WebAuthn
 
-This project provides a semi-generic backend API for supporting WebAuthn credential registration and authentication.
-It is intended to be run in a manner as to be shared between multiple consuming applications. It uses an API key 
-and secret to authenticate requests, and further uses that secret as the encryption key. Loss of the API secret 
-would mean loss of all WebAuthn credentials stored.
+This project provides a semi-generic backend API for supporting Time-based One Time Passcode (TOTP) and WebAuthn 
+Passkey registration and authentication. It is intended to be run in a manner as to be shared between multiple consuming
+applications. It uses an API key and secret to authenticate requests, and further uses that secret as the encryption 
+key. Loss of the API secret would mean loss of all credentials stored.
 
 This application can be run in two ways:
 1. As a standalone server using the builtin webserver available in the `server/` folder
-2. As a AWS Lambda function using the `lambda/` implementation. This implementation can also use 
+2. As an AWS Lambda function using the `lambda/` implementation. This implementation can also use 
 [AWS CDK](https://aws.amazon.com/cdk/) to help automate build/deployment. It should also be 
 noted that the `lambda` format depends on some resources already existing in AWS. There is a `lambda/terraform/`
 folder with the Terraform configurations needed to provision them. 
 
-## The API
+# API definition
+
+The full definition of the API is found in the openapi.yaml file. A brief summary follows.
+
+## The APIKey API
+
+### Create APIKey
+
+`POST /api-key`
+
+### Activate APIKey
+
+`POST /api-key/activate`
+
+### Rotate APIKey (experimental)
+
+This endpoint has not yet been proven in production use. Proceed at your own risk.
+
+`POST /api-key/rotate`
+
+## The TOTP API
+
+### Required Headers
+1. `x-mfa-apikey` - The API Key
+2. `x-mfa-apisecret` - The API Key Secret
+
+### Create TOTP Passcode
+
+`POST /totp`
+
+### Delete TOTP Passcode
+
+`DELETE /totp/{uuid}`
+
+### Validate TOTP Passcode
+
+`POST /totp/{uuid}/validate`
+
+## The Webauthn API
 Yes, as you'll see below this API makes heavy use of custom headers for things that seem like they could go into 
 the request body. We chose to use headers though so that what is sent in the body can be handed off directly
 to the WebAuthn library and fit the structures it was expecting without causing any conflicts, etc.
@@ -52,3 +90,60 @@ to do with WebAuthn, but is the primary key for finding the right records in Dyn
 
 ### Delete one of the user's Webauthn credentials
 `DELETE /webauthn/credential`
+
+# Development
+
+## Unit tests
+
+To run unit tests, simply run "make test". It will spin up a Docker Compose environment and run the tests using
+Docker containers for the API and for DynamoDB.
+
+## Manual testing
+
+Unit tests can be run individually, either on the command line or through your IDE. It is also possible to 
+test the server and Lambda implementations locally.
+
+### Server
+
+#### HTTP
+
+If HTTPS is not needed, simply start the `app` container and exercise the API using localhost and the Docker port
+defined in docker-compose.yml (currently 8161).
+
+#### HTTPS
+
+To use a "demo UI" that can interact with the API using HTTPS, use Traefik proxy, which is defined in the Docker
+Compose environment. Traefik is a proxy that creates a Let's Encrypt certificate and routes traffic to the local
+container via a registered DNS record. To configure this, define the following variables in `local.env`:
+
+- DNS_PROVIDER=cloudflare
+- CLOUDFLARE_DNS_API_TOKEN=<insert a valid Cloudflare token that has DNS write permission on the domain defined below>
+- LETS_ENCRYPT_EMAIL=<insert your actual email address here>
+- LETS_ENCRYPT_CA=production
+- TLD=<your DNS domain>
+- SANS=mfa-ui.<your domain>,mfa-app.<your domain>
+- BACKEND1_URL=http://ui:80
+- FRONTEND1_DOMAIN=mfa-ui.<your domain>
+- BACKEND2_URL=http://app:8080
+- FRONTEND2_DOMAIN=mfa-app.<your domain>
+
+Create DNS A records (without Cloudflare proxy enabled) for the values defined in `FRONTEND1_DOMAIN` and 
+`FRONTEND2_DOMAIN` pointing to 127.0.0.1 and wait for DNS propagation. Once all of the above configuration is in place,
+run `make demo`. The first time will take several minutes for all the initialization. You can watch Docker logs on the 
+proxy container to keep tabs on the progress.
+
+### Lambda
+
+To exercise the API as it would be used in AWS Lambda, run this command: `air -c .air-cdk.toml`. This will run a
+file watcher that will rebuild the app code and the CDK stack, then run `sam local start-api` using the generated
+Cloudformation template. This will listen on port 8160. Any code changes will trigger a rebuild and SAM will restart
+using the new code.
+
+Implementation notes:
+
+- SAM uses Docker internally, which would make it complicated to run with Docker Compose.
+- You will need to install CDK and SAM on your computer for this to work.
+- It can use the DynamoDB container in Docker Compose, which can be started using `make dbinit`.
+- The `make dbinit` command creates an APIKey (key: `EC7C2E16-5028-432F-8AF2-A79A64CF3BC1` 
+secret: `1ED18444-7238-410B-A536-D6C15A3C`)
+- Some unit tests will delete the APIKey created by `make dbinit`.

api.go

@@ -2,21 +2,32 @@ package mfa
 
 import (
 	"encoding/json"
+	"errors"
 	"log"
 	"net/http"
+	"strings"
+
+	"github.com/google/uuid"
 )
 
-const IDParam = "id"
+const (
+	IDParam   = "id"
+	UUIDParam = "uuid"
+)
 
 // simpleError is a custom error type that can be JSON-encoded for API responses
 type simpleError struct {
-	Error string `json:"error"`
+	Err string `json:"error"`
 }
 
 // newSimpleError creates a new simpleError from the given error
-func newSimpleError(err error) simpleError {
-	return simpleError{Error: err.Error()}
-}
+func newSimpleError(err error) simpleError { return simpleError{Err: err.Error()} }
+
+// Error satisfies the error interface.
+func (s simpleError) Error() string { return s.Err }
+
+// Is returns true if the error strings are equal.
+func (s simpleError) Is(err error) bool { return s.Err == err.Error() || errors.Is(err, simpleError{}) }
 
 // jsonResponse encodes a body as JSON and writes it to the response. It sets the response Content-Type header to
 // "application/json".
@@ -25,6 +36,8 @@ func jsonResponse(w http.ResponseWriter, body interface{}, status int) {
 	switch b := body.(type) {
 	case error:
 		data = newSimpleError(b)
+	case string:
+		data = newSimpleError(errors.New(b))
 	default:
 		data = body
 	}
@@ -34,7 +47,12 @@ func jsonResponse(w http.ResponseWriter, body interface{}, status int) {
 	if data != nil {
 		jBody, err = json.Marshal(data)
 		if err != nil {
-			log.Printf("failed to marshal response body to json: %s", err)
+
+			// SonarQube flagged this as vulnerable to injection attacks. Rather than exhaustively search for places
+			// where user input is inserted into the error message, I'll just sanitize it as recommended.
+			sanitizedError := strings.ReplaceAll(strings.ReplaceAll(err.Error(), "\n", "_"), "\r", "_")
+
+			log.Printf("failed to marshal response body to json: %s", sanitizedError)
 			w.WriteHeader(http.StatusInternalServerError)
 			_, _ = w.Write([]byte("failed to marshal response body to json"))
 			return
@@ -45,6 +63,15 @@ func jsonResponse(w http.ResponseWriter, body interface{}, status int) {
 	w.WriteHeader(status)
 	_, err = w.Write(jBody)
 	if err != nil {
-		log.Printf("failed to write response in jsonResponse: %s\n", err)
+		log.Printf("failed to write response in jsonResponse: %s", err)
+	}
+}
+
+// NewUUID returns a new V4 UUID value as a text string
+func NewUUID() string {
+	u, err := uuid.NewRandom()
+	if err != nil {
+		panic("failed to generate uuid: " + err.Error())
 	}
+	return u.String()
 }