diff --git a/.github/workflows/swagger.yml b/.github/workflows/docs.yml
similarity index 81%
rename from .github/workflows/swagger.yml
rename to .github/workflows/docs.yml
index ac3e5fe..974850f 100644
--- a/.github/workflows/swagger.yml
+++ b/.github/workflows/docs.yml
@@ -1,11 +1,11 @@
-name: API Swagger Docs
+name: API Docs
on:
push:
branches:
- main
paths-ignore:
- - "docs/swagger.yaml"
+ - "docs/api/swagger.yaml"
pull_request:
paths:
- "api/**/*"
@@ -35,13 +35,13 @@ jobs:
uses: actions/upload-artifact@v7
with:
name: swagger.yaml
- path: docs/swagger.yaml
+ path: docs/api/swagger.yaml
- name: Check if there is a difference
uses: mathiasvr/command-output@v2.0.0
id: diff
with:
- run: git diff --no-color docs/swagger.yaml
+ run: git diff --no-color docs/api/swagger.yaml
- name: Mark previous comment as outdated if no diff
if: ${{ github.event_name == 'pull_request' && steps.diff.outputs.stdout == '' }}
@@ -67,12 +67,12 @@ jobs:
run: |
git config user.name "github-actions"
git config user.email "github-actions@users.noreply.github.com"
- git add docs/swagger.yaml
+ git add docs/api/swagger.yaml
git commit -m "ci: regenerate swagger.yaml after merge"
git push
deploy-pages:
- name: Deploy Swagger UI to GitHub Pages
+ name: Deploy docs site and Swagger UI to GitHub Pages
needs: api-swagger
if: github.event_name == 'push'
runs-on: ubuntu-latest
@@ -91,21 +91,29 @@ jobs:
steps:
- uses: actions/checkout@v7
- - name: Overwrite docs/swagger.yaml with the freshly generated spec
+ - name: Overwrite docs/api/swagger.yaml with the freshly generated spec
uses: actions/download-artifact@v4
with:
name: swagger.yaml
- path: docs
+ path: docs/api
- name: Generate Swagger UI assets
run: ./scripts/generate-swagger-ui.sh
+ - name: Setup Ruby
+ uses: ruby/setup-ruby@v1
+ with:
+ bundler-cache: true
+
+ - name: Build docs site with Jekyll
+ run: bundle exec jekyll build --source docs --destination _site
+
- uses: actions/configure-pages@v6
- - name: Upload docs/ (Swagger UI + spec)
+ - name: Upload built site
uses: actions/upload-pages-artifact@v3
with:
- path: docs
+ path: _site
- name: Deploy to GitHub Pages
id: deployment
diff --git a/.gitignore b/.gitignore
index a96d222..2104df7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,4 +2,13 @@
*.env
!.env.example
!example.env
-vegeta.conf
\ No newline at end of file
+vegeta.conf
+
+# Generated Swagger UI assets (produced by scripts/generate-swagger-ui.sh)
+docs/api/index.html
+docs/api/swagger-ui.css
+docs/api/swagger-ui-bundle.js
+docs/api/LICENSE.swagger-ui
+
+# Jekyll build output
+_site/
\ No newline at end of file
diff --git a/Dockerfile b/Dockerfile
deleted file mode 100644
index f4a94ca..0000000
--- a/Dockerfile
+++ /dev/null
@@ -1,35 +0,0 @@
-# syntax=docker/dockerfile:1
-
-FROM golang:1.26-bookworm AS build
-
-WORKDIR /src
-
-COPY go.mod go.sum ./
-RUN go mod download
-
-COPY . .
-
-ARG TARGETOS
-ARG TARGETARCH
-
-RUN CGO_ENABLED=0 \
- GOOS=${TARGETOS:-linux} \
- GOARCH=${TARGETARCH:-amd64} \
- go build \
- -trimpath \
- -ldflags="-s -w" \
- -o /out/api \
- ./cmd/authapi
-
-
-FROM gcr.io/distroless/static-debian13:nonroot
-
-WORKDIR /app
-
-COPY --from=build --chown=nonroot:nonroot /out/api /app/api
-
-EXPOSE 8080
-
-USER nonroot:nonroot
-
-ENTRYPOINT ["/app/api"]
\ No newline at end of file
diff --git a/Gemfile b/Gemfile
new file mode 100644
index 0000000..f00d0e9
--- /dev/null
+++ b/Gemfile
@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.3"
+gem "just-the-docs"
\ No newline at end of file
diff --git a/Gemfile.lock b/Gemfile.lock
new file mode 100644
index 0000000..524fb97
--- /dev/null
+++ b/Gemfile.lock
@@ -0,0 +1,173 @@
+GEM
+ remote: https://rubygems.org/
+ specs:
+ addressable (2.9.0)
+ public_suffix (>= 2.0.2, < 8.0)
+ base64 (0.3.0)
+ bigdecimal (4.1.2)
+ colorator (1.1.0)
+ concurrent-ruby (1.3.8)
+ csv (3.3.6)
+ em-websocket (0.5.3)
+ eventmachine (>= 0.12.9)
+ http_parser.rb (~> 0)
+ eventmachine (1.2.7)
+ ffi (1.17.4)
+ ffi (1.17.4-aarch64-linux-gnu)
+ ffi (1.17.4-aarch64-linux-musl)
+ ffi (1.17.4-arm-linux-gnu)
+ ffi (1.17.4-arm-linux-musl)
+ ffi (1.17.4-arm64-darwin)
+ ffi (1.17.4-x86-linux-gnu)
+ ffi (1.17.4-x86-linux-musl)
+ ffi (1.17.4-x86_64-darwin)
+ ffi (1.17.4-x86_64-linux-gnu)
+ ffi (1.17.4-x86_64-linux-musl)
+ forwardable-extended (2.6.0)
+ google-protobuf (4.36.0)
+ bigdecimal
+ rake (~> 13.3)
+ google-protobuf (4.36.0-aarch64-linux-gnu)
+ bigdecimal
+ rake (~> 13.3)
+ google-protobuf (4.36.0-aarch64-linux-musl)
+ bigdecimal
+ rake (~> 13.3)
+ google-protobuf (4.36.0-arm64-darwin)
+ bigdecimal
+ rake (~> 13.3)
+ google-protobuf (4.36.0-x86-linux-gnu)
+ bigdecimal
+ rake (~> 13.3)
+ google-protobuf (4.36.0-x86-linux-musl)
+ bigdecimal
+ rake (~> 13.3)
+ google-protobuf (4.36.0-x86_64-darwin)
+ bigdecimal
+ rake (~> 13.3)
+ google-protobuf (4.36.0-x86_64-linux-gnu)
+ bigdecimal
+ rake (~> 13.3)
+ google-protobuf (4.36.0-x86_64-linux-musl)
+ bigdecimal
+ rake (~> 13.3)
+ http_parser.rb (0.8.1)
+ i18n (1.15.2)
+ concurrent-ruby (~> 1.0)
+ jekyll (4.4.1)
+ addressable (~> 2.4)
+ base64 (~> 0.2)
+ colorator (~> 1.0)
+ csv (~> 3.0)
+ em-websocket (~> 0.5)
+ i18n (~> 1.0)
+ jekyll-sass-converter (>= 2.0, < 4.0)
+ jekyll-watch (~> 2.0)
+ json (~> 2.6)
+ kramdown (~> 2.3, >= 2.3.1)
+ kramdown-parser-gfm (~> 1.0)
+ liquid (~> 4.0)
+ mercenary (~> 0.3, >= 0.3.6)
+ pathutil (~> 0.9)
+ rouge (>= 3.0, < 5.0)
+ safe_yaml (~> 1.0)
+ terminal-table (>= 1.8, < 4.0)
+ webrick (~> 1.7)
+ jekyll-include-cache (0.2.2)
+ jekyll (>= 3.7, < 5.0)
+ jekyll-sass-converter (3.1.0)
+ sass-embedded (~> 1.75)
+ jekyll-seo-tag (2.9.0)
+ jekyll (>= 3.8, < 5.0)
+ jekyll-watch (2.2.1)
+ listen (~> 3.0)
+ json (2.21.2)
+ just-the-docs (0.12.0)
+ jekyll (>= 3.8.5)
+ jekyll-include-cache
+ jekyll-seo-tag (>= 2.0)
+ rake (>= 12.3.1)
+ kramdown (2.5.2)
+ rexml (>= 3.4.4)
+ kramdown-parser-gfm (1.1.0)
+ kramdown (~> 2.0)
+ liquid (4.0.4)
+ listen (3.10.0)
+ logger
+ rb-fsevent (~> 0.10, >= 0.10.3)
+ rb-inotify (~> 0.9, >= 0.9.10)
+ logger (1.7.0)
+ mercenary (0.4.0)
+ pathutil (0.16.2)
+ forwardable-extended (~> 2.6)
+ public_suffix (7.0.5)
+ rake (13.4.2)
+ rb-fsevent (0.11.2)
+ rb-inotify (0.11.1)
+ ffi (~> 1.0)
+ rexml (3.4.4)
+ rouge (4.7.0)
+ safe_yaml (1.0.5)
+ sass-embedded (1.103.1)
+ google-protobuf (~> 4.31)
+ rake (>= 13)
+ sass-embedded (1.103.1-aarch64-linux-android)
+ google-protobuf (~> 4.31)
+ sass-embedded (1.103.1-aarch64-linux-gnu)
+ google-protobuf (~> 4.31)
+ sass-embedded (1.103.1-aarch64-linux-musl)
+ google-protobuf (~> 4.31)
+ sass-embedded (1.103.1-arm-linux-androideabi)
+ google-protobuf (~> 4.31)
+ sass-embedded (1.103.1-arm-linux-gnueabihf)
+ google-protobuf (~> 4.31)
+ sass-embedded (1.103.1-arm-linux-musleabihf)
+ google-protobuf (~> 4.31)
+ sass-embedded (1.103.1-arm64-darwin)
+ google-protobuf (~> 4.31)
+ sass-embedded (1.103.1-riscv64-linux-android)
+ google-protobuf (~> 4.31)
+ sass-embedded (1.103.1-riscv64-linux-gnu)
+ google-protobuf (~> 4.31)
+ sass-embedded (1.103.1-riscv64-linux-musl)
+ google-protobuf (~> 4.31)
+ sass-embedded (1.103.1-x86_64-darwin)
+ google-protobuf (~> 4.31)
+ sass-embedded (1.103.1-x86_64-linux-android)
+ google-protobuf (~> 4.31)
+ sass-embedded (1.103.1-x86_64-linux-gnu)
+ google-protobuf (~> 4.31)
+ sass-embedded (1.103.1-x86_64-linux-musl)
+ google-protobuf (~> 4.31)
+ terminal-table (3.0.2)
+ unicode-display_width (>= 1.1.1, < 3)
+ unicode-display_width (2.6.0)
+ webrick (1.9.2)
+
+PLATFORMS
+ aarch64-linux-android
+ aarch64-linux-gnu
+ aarch64-linux-musl
+ arm-linux-androideabi
+ arm-linux-gnu
+ arm-linux-gnueabihf
+ arm-linux-musl
+ arm-linux-musleabihf
+ arm64-darwin
+ riscv64-linux-android
+ riscv64-linux-gnu
+ riscv64-linux-musl
+ ruby
+ x86-linux-gnu
+ x86-linux-musl
+ x86_64-darwin
+ x86_64-linux-android
+ x86_64-linux-gnu
+ x86_64-linux-musl
+
+DEPENDENCIES
+ jekyll (~> 4.3)
+ just-the-docs
+
+BUNDLED WITH
+ 2.5.23
diff --git a/Makefile b/Makefile
index aa9b461..8bc0136 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: demo api swagger-ui clean-demo clean-api
+.PHONY: demo api swagger-ui docs clean-demo clean-api
demo: clean-demo
@echo "Building demo image..."
@@ -30,9 +30,19 @@ clean-api:
swagger-ui:
./scripts/generate-swagger.sh
- @trap 'truncate -s 0 docs/swagger.yaml' EXIT; \
+ @trap 'git checkout HEAD -- docs/api/swagger.yaml' EXIT; \
docker run --rm \
-p 8081:8080 \
-e SWAGGER_JSON=/spec/swagger.yaml \
- -v "$$PWD/docs:/spec:ro" \
- docker.swagger.io/swaggerapi/swagger-ui
\ No newline at end of file
+ -v "$$PWD/docs/api:/spec:ro" \
+ docker.swagger.io/swaggerapi/swagger-ui
+
+docs:
+ docker run --rm -it \
+ -p 4000:4000 \
+ -p 35729:35729 \
+ -v "$$PWD:/app" \
+ -v "jekyll-gems:/usr/local/bundle" \
+ -w /app \
+ ruby:3.3 \
+ bash -lc 'gem install bundler -v 2.5.23 --no-document && bundle install && bundle exec jekyll serve --source docs --livereload --host 0.0.0.0'
\ No newline at end of file
diff --git a/README.md b/README.md
index 2496487..f8452f3 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,9 @@
[](https://github.com/simpleauthlink/authapi/releases/latest)
-[](https://godoc.org/github.com/simpleauthlink/authapi)
+[](https://godoc.org/github.com/simpleauthlink/authapi)
[](https://goreportcard.com/report/github.com/simpleauthlink/authapi)
[](https://github.com/simpleauthlink/authapi/actions/workflows/main.yml)
[](LICENSE)
-
# SimpleAuth.link API
@@ -13,100 +12,134 @@
This repository contains the source code of the SimpleAuth.link API Service.
-Read full [documentation here](https://docs.simpleauth.link).
+- Read the full [documentation here](https://docs.simpleauth.link).
+- Try the API in the interactive [Swagger UI](https://simpleauthlink.github.io/authapi/api/).
---
## Technical Details π»
-### Token Generation Process π
+### Token Generation Process π
-* By leveraging the Ed25519 signature algorithm, the service deterministically generates a private key using your App ID and secret.
-* This ensures that each token is cryptographically secure and uniquely tied to your application, eliminating the need to store sensitive keys.
+- By leveraging the Ed25519 signature algorithm, the service deterministically generates a private key using your App ID and secret.
+- This ensures that each token is cryptographically secure and uniquely tied to your application, eliminating the need to store sensitive keys.
### Stateless Architecture ποΈ
-* SimpleAuth.link works without a traditional database. It does not store any user data, including email addresses, on its servers.
-* Instead, the data generated is self-contained, requiring no further information or state to be used. This stateless design increases security and reduces the risk of data breaches.
+- SimpleAuth.link works without a traditional database. It does not store any user data, including email addresses, on its servers.
+- Instead, the data generated is self-contained, requiring no further information or state to be used. This stateless design increases security and reduces the risk of data breaches.
+
+### Token Structure π§©
+
+A token is composed of three parts β the expiration time, the signature and the user's email β base64url-encoded and separated by dots. Read more in the [documentation](https://docs.simpleauth.link/about/tokens).
## Development π§βπ»
### Prerequisites π
- - Go (version 1.24 or later recommended)
- - Docker (optional, for containerized deployment)
+
+- Go (the version declared in [go.mod](./go.mod))
+- Docker (optional, for containerized deployment)
### Clone the Repository π₯
+
```sh
-git clone --branch v2 https://github.com/SimpleAuthLink/authapi.git
+git clone https://github.com/SimpleAuthLink/authapi.git
cd authapi
```
### Code Structure πͺ
-* Modularity: The repository is structured into packages to simplify testing and future expansion.
- - `api/`: Contains the core API endpoint definitions and routing logic.
- - `cmd/`: Entry points and command-line utilities for running the API server.
- - `docker/`: Dockerfiles and configuration for containerized builds.
- - `internal/`: Internal packages and libraries used across the application.
- - `notification/`: Code handling user notifications.
- - `token/`: Modules for token creation and management.
- - `.github/`: GitHub-specific workflows and configurations (CI/CD, issue templates, etc.).
-
- This layout supports modular development and clear separation of concerns across different parts of the API service.
-
-* Testing: Use the standard Go testing framework to run tests. You can run tests with:
- ```sh
- go test ./...
- ```
-### Run with go π¦«
-For development purposes, you can run the API server directly with Go.
+- `api/`: Contains the core API endpoint definitions and routing logic, and the Go client in `api/client`.
+- `cmd/`: Entry points and command-line utilities for running the API server (`authapi`) and the demo (`demo`).
+- `docker/`: Dockerfiles for containerized builds.
+- `notification/`: Code handling user notifications.
+- `token/`: Modules for token creation and management.
+- `scripts/`: Helper scripts (e.g. swagger generation).
+- `.github/`: GitHub-specific workflows and configurations (CI/CD, etc.).
+
+### Testing
+
```sh
-go run ./cmd/authapi -h
+go test ./...
```
+
+### Run with go π¦«
+
+For development purposes, you can run the API server directly with Go. The entry point is `cmd/authapi/main.go` and it loads `.env` automatically when present:
+
```sh
-Usage of authapi:
- -email-addr string
- email account address
- -email-host string
- email server host
- -email-pass string
- email account password
- -email-port int
- email server port (default 587)
- -host string
- service host (default "0.0.0.0")
- -port int
- service host (default 8080)
- -secret string
- secret used to generate the tokens (default "simpleauthlink-secret")
+go run ./cmd/authapi
```
+The main flags (also configurable via environment variables):
+
+- `--host` (env `HOST`) β service host (default `0.0.0.0`)
+- `--port` (env `PORT`) β service port (default `8080`)
+- `--secret` (env `SECRET`) β secret used to generate the tokens
+- `--email-addr` (env `EMAIL_ADDR`) β sender account address
+- `--email-user` (env `EMAIL_USER`) β SMTP username
+- `--email-pass` (env `EMAIL_PASS`) β SMTP password
+- `--email-host` (env `EMAIL_HOST`) β SMTP server host
+- `--email-port` (env `EMAIL_PORT`) β SMTP server port (default `587`)
+- `--queue-size` (env `NOTIFICATION_QUEUE_SIZE`) β notification queue size (default `1000`)
+- `--queue-workers` (env `NOTIFICATION_QUEUE_WORKERS`) β notification queue workers (default `10`)
+
### Run with docker π³
1. **Prepare the Environment File**
-
+
Copy the `example.env` file to `.env` and edit the file to fill in your parameters:
+
```bash
HOST="localhost"
PORT=8080
EMAIL_ADDR="test@test.com"
+ EMAIL_USER="test@test.com"
EMAIL_PASS="smtp_server_password"
EMAIL_HOST="smtp.example.com"
EMAIL_PORT=587
SECRET="my_backend_secret"
+ NOTIFICATION_QUEUE_SIZE=1000
+ NOTIFICATION_QUEUE_WORKERS=10
```
2. **Build the Docker Image**
-
- Run the following command in the root of your project to build the image:
+
```bash
docker build -f docker/Dockerfile.prod -t simpleauthlink .
```
3. **Run the Docker Container**
-
- Once the image is built, start a container using the environment file:
+
```bash
- docker run --name simpleauthlink --env-file .env -p 8080:80 simpleauthlink
+ docker run --name simpleauthlink --env-file .env -p ${PORT}:${PORT} simpleauthlink
```
- This command maps the containerβs port 80 to port 8080 on your host.
\ No newline at end of file
+
+ The API listens on the `PORT` value from your `.env` (default `8080`), both inside the container and on your host.
+
+### Go client
+
+The `api/client` package provides a typed Go client for the API:
+
+```go
+package main
+
+import (
+ "log"
+
+ "github.com/simpleauthlink/authapi/api/client"
+ "github.com/simpleauthlink/authapi/token"
+)
+
+func main() {
+ cli, err := client.Default("", "", false)
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // request a login token for a user
+ if err := cli.RequestToken(new(token.Email).SetString("user@example.com")); err != nil {
+ log.Fatal(err)
+ }
+}
+```
\ No newline at end of file
diff --git a/api/handlers.go b/api/handlers.go
index 52bc749..d5dc746 100644
--- a/api/handlers.go
+++ b/api/handlers.go
@@ -19,8 +19,11 @@ import (
// session duration.
//
// @Summary Create an App
-// @Description Create an App with a provided secret and get the AppID to
-// @Description be used to generate tokens for your users.
+// @Description Register a new application by submitting its configuration
+// @Description details, including the app name, session duration, redirect
+// @Description URL, and secret. This process generates a unique AppID that
+// @Description is used to identify your application and secure subsequent
+// @Description API requests.
// @Tags apps
// @Produce json
// @Param request body api.AppIDRequest true "App ID Request"
@@ -55,9 +58,12 @@ func (s *APIService) generateAppIDHandler(w http.ResponseWriter, r *http.Request
// token with the user email address and send to it the resulting token.
//
// @Summary Request a new token for the user
-// @Description Using the AppID and the AppSecret, request a new token for
-// @Description a user using its email address. The user will receive the
-// @Description session token via email to that address.
+// @Description Request an authentication token for a user by providing
+// @Description their email address. The service generates a secure token
+// @Description using cryptographic methods and sends it via email in a
+// @Description magic link, enabling passwordless login. This endpoint
+// @Description requires X-SIMPLEAUTHLINK-APPID and X-SIMPLEAUTHLINK-SECRET
+// @Description auth headers to be defined.
// @Tags tokens
// @Produce json
// @Security X-SIMPLEAUTHLINK-APPID || X-SIMPLEAUTHLINK-SECRET
@@ -130,8 +136,11 @@ func (s *APIService) requestTokenHandler(w http.ResponseWriter, r *http.Request)
// for the given app configuration and check the token expiration.
//
// @Summary Verify a user token
-// @Description Check that the provided token is valid for the AppID and
-// @Description secret.
+// @Description Validate a received token to ensure it is authentic,
+// @Description unexpired, and properly associated with your application
+// @Description and the user. This step is critical for maintaining secure
+// @Description sessions. This endpoint requires X-SIMPLEAUTHLINK-APPID and
+// @Description X-SIMPLEAUTHLINK-SECRET auth headers to be defined.
// @Tags tokens
// @Produce json
// @Security X-SIMPLEAUTHLINK-APPID || X-SIMPLEAUTHLINK-SECRET
@@ -164,7 +173,8 @@ func (s *APIService) verifyTokenHandler(w http.ResponseWriter, r *http.Request)
// healthCheckHandler handles the ping request.
//
// @Summary Ping endpoint
-// @Description Use this endpoint to ensure that the service is up.
+// @Description This endpoint allows to a third party to check if the
+// @Description service is alive and running.
// @Success 200
// @Router /ping [get]
func (s *APIService) healthCheckHandler(w http.ResponseWriter, r *http.Request) {
diff --git a/docker/Dockerfile.demo b/docker/Dockerfile.demo
index dc0eb0f..94c3eb5 100644
--- a/docker/Dockerfile.demo
+++ b/docker/Dockerfile.demo
@@ -1,18 +1,38 @@
-# build
-FROM golang:1.26-alpine as builder
+# syntax=docker/dockerfile:1
+
+FROM golang:1.26-bookworm AS build
+
+WORKDIR /src
+
+COPY go.mod go.sum ./
+RUN go mod download
-WORKDIR /app/data
COPY . .
-RUN go mod tidy
-RUN go build -o /authapi ./cmd/demo/main.go
+ARG TARGETOS
+ARG TARGETARCH
+
+RUN CGO_ENABLED=0 \
+ GOOS=${TARGETOS:-linux} \
+ GOARCH=${TARGETARCH:-amd64} \
+ go build \
+ -trimpath \
+ -ldflags="-s -w" \
+ -o /out/api \
+ ./cmd/demo
+
+FROM gcr.io/distroless/static-debian13:nonroot
+
+WORKDIR /app
+
+COPY --from=build --chown=nonroot:nonroot /out/api /app/api
-# deploy
-FROM alpine:latest
+# distroless images do not ship a CA certificate bundle; it is required to
+# verify the SMTP server certificate over TLS.
+COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
-EXPOSE 80
+EXPOSE 8080
-WORKDIR /
-COPY --from=builder /authapi /authapi
+USER nonroot:nonroot
-ENTRYPOINT /authapi
\ No newline at end of file
+ENTRYPOINT ["/app/api"]
\ No newline at end of file
diff --git a/docker/Dockerfile.prod b/docker/Dockerfile.prod
index d139ed6..48735f2 100644
--- a/docker/Dockerfile.prod
+++ b/docker/Dockerfile.prod
@@ -1,18 +1,38 @@
-# build
-FROM golang:1.26-alpine as builder
+# syntax=docker/dockerfile:1
+
+FROM golang:1.26-bookworm AS build
+
+WORKDIR /src
+
+COPY go.mod go.sum ./
+RUN go mod download
-WORKDIR /app/data
COPY . .
-RUN go mod tidy
-RUN go build -o /authapi ./cmd/authapi/main.go
+ARG TARGETOS
+ARG TARGETARCH
+
+RUN CGO_ENABLED=0 \
+ GOOS=${TARGETOS:-linux} \
+ GOARCH=${TARGETARCH:-amd64} \
+ go build \
+ -trimpath \
+ -ldflags="-s -w" \
+ -o /out/api \
+ ./cmd/authapi
+
+FROM gcr.io/distroless/static-debian13:nonroot
+
+WORKDIR /app
+
+COPY --from=build --chown=nonroot:nonroot /out/api /app/api
-# deploy
-FROM alpine:latest
+# distroless images do not ship a CA certificate bundle; it is required to
+# verify the SMTP server certificate over TLS.
+COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
-EXPOSE 80
+EXPOSE 8080
-WORKDIR /
-COPY --from=builder /authapi /authapi
+USER nonroot:nonroot
-ENTRYPOINT /authapi
\ No newline at end of file
+ENTRYPOINT ["/app/api"]
\ No newline at end of file
diff --git a/docs/_config.yml b/docs/_config.yml
new file mode 100644
index 0000000..ef2eef8
--- /dev/null
+++ b/docs/_config.yml
@@ -0,0 +1,26 @@
+# Jekyll configuration for the SimpleAuth.link documentation site.
+#
+# By default the docs are deployed to GitHub Pages at
+# https://simpleauthlink.github.io/authapi/ (project site).
+#
+# To publish the same docs on a custom domain instead, change these two keys:
+# url: "https://your-domain.com"
+# baseurl: ""
+#
+# The links inside the docs pages are built with Jekyll's relative_url /
+# absolute_url filters, so they follow the url/baseurl automatically.
+
+title: SimpleAuth.link
+description: >-
+ Passwordless authentication for your users using just an email address.
+url: "https://simpleauthlink.github.io"
+baseurl: "/authapi"
+
+theme: just-the-docs
+
+plugins:
+ - jekyll-include-cache
+ - jekyll-seo-tag
+
+search_enabled: true
+heading_anchors: true
\ No newline at end of file
diff --git a/docs/about.md b/docs/about.md
new file mode 100644
index 0000000..c9aa45f
--- /dev/null
+++ b/docs/about.md
@@ -0,0 +1,57 @@
+---
+title: βΉοΈ About
+layout: default
+nav_order: 2
+permalink: /about/
+---
+
+# About SimpleAuth.link π‘οΈ
+
+SimpleAuth.link is a secure authentication service that enables your users to log in to your platform without the need for traditional passwords. By using SimpleAuth.link, your platform can verify user identities and manage active sessions through cryptographically generated tokens.
+
+## How It Works βοΈ
+
+### 1. App Registration π
+Your platform first registers with SimpleAuth.link by creating an **App ID** along with a corresponding **secret**. The App ID is a *self-contained* representation of your application configuration: it deterministically embeds the app name, redirect URL, session duration and a hash of the secret. Nothing is stored on the server.
+
+### 2. Token Request π
+When a user enters their email address to log in, your platform sends a request to SimpleAuth.link. The service uses your App ID and secret to generate a secure token using the Ed25519 signature algorithm. This process is deterministic β meaning the private key for signing is generated on the fly from your credentials without being stored.
+
+### 3. Magic Link Delivery βοΈ
+The generated token is embedded in a secure URL, known as a **magic link**, which is then sent to the user's email. This link includes:
+
+- The token itself, which authenticates the user and embeds its own expiration time.
+- The user's email address, as a `user` query parameter.
+
+### 4. User Authentication π€
+When the user clicks the magic link:
+
+- The token is submitted back to your platform.
+- Your platform verifies the token's authenticity and validity.
+- Upon successful verification, the user is securely logged in.
+
+## Technical Details π»
+
+- **Stateless Architecture:** SimpleAuth.link operates without a traditional database. It does not store any user data, including email addresses, on its servers. Both App IDs and tokens are self-contained and can be verified with nothing more than the app configuration and secret. This stateless design enhances security and reduces the risk of data breaches.
+- **Token Generation Process:** By leveraging the Ed25519 signature algorithm, the service deterministically generates a private key using your App ID and secret. This ensures that each token is cryptographically secure and uniquely tied to your application, eliminating the need to store sensitive keys.
+- **Token Structure:** A token is composed of three parts β the expiration time, the signature and the user's email β base64url-encoded and separated by dots. See [About Tokens]({{ '/about/tokens' | relative_url }}) for details.
+
+## Benefits of Using SimpleAuth.link π―
+
+- **Enhanced Security:** Eliminates the risks associated with password-based authentication, such as password fatigue, weak passwords, and password reuse. The use of robust cryptographic methods further secures the authentication process.
+- **Improved User Experience:** Users can authenticate with a single click using the magic link sent to their email, streamlining the login process and reducing friction.
+- **Simplified Backend Management:** As a stateless service, SimpleAuth.link removes the need for complex database management and lowers the potential for data storage vulnerabilities.
+
+## API Reference
+
+The full API is described in the interactive [Swagger UI]({{ '/api/' | absolute_url }}), with details about [Apps]({{ '/about/apps' | relative_url }}) and [Tokens]({{ '/about/tokens' | relative_url }}) in the rest of the documentation.
+
+## Magic Links π
+
+Magic links are secure URLs that allow users to perform actions such as logging in without a password. They offer several advantages:
+
+- **Security:** They reduce the risk of unauthorized access by eliminating password vulnerabilities.
+- **Convenience:** They simplify the authentication process, requiring just a single click from the user.
+- **User Verification:** Sending the link directly to the user's email confirms the validity of the email address and enhances the overall security of the login process.
+
+SimpleAuth.link combines these benefits to deliver a reliable, secure, and user-friendly authentication experience for your platform.
\ No newline at end of file
diff --git a/docs/swagger.yaml b/docs/api/swagger.yaml
similarity index 84%
rename from docs/swagger.yaml
rename to docs/api/swagger.yaml
index 5101d64..1c032e6 100644
--- a/docs/swagger.yaml
+++ b/docs/api/swagger.yaml
@@ -80,8 +80,11 @@ paths:
/apps:
post:
description: |-
- Create an App with a provided secret and get the AppID to
- be used to generate tokens for your users.
+ Register a new application by submitting its configuration
+ details, including the app name, session duration, redirect
+ URL, and secret. This process generates a unique AppID that
+ is used to identify your application and secure subsequent
+ API requests.
requestBody:
content:
application/json:
@@ -138,7 +141,9 @@ paths:
- default
/ping:
get:
- description: Use this endpoint to ensure that the service is up.
+ description: |-
+ This endpoint allows to a third party to check if the
+ service is alive and running.
responses:
"200":
description: OK
@@ -146,9 +151,12 @@ paths:
/tokens:
post:
description: |-
- Using the AppID and the AppSecret, request a new token for
- a user using its email address. The user will receive the
- session token via email to that address.
+ Request an authentication token for a user by providing
+ their email address. The service generates a secure token
+ using cryptographic methods and sends it via email in a
+ magic link, enabling passwordless login. This endpoint
+ requires X-SIMPLEAUTHLINK-APPID and X-SIMPLEAUTHLINK-SECRET
+ auth headers to be defined.
requestBody:
content:
application/json:
@@ -185,8 +193,11 @@ paths:
- tokens
put:
description: |-
- Check that the provided token is valid for the AppID and
- secret.
+ Validate a received token to ensure it is authentic,
+ unexpired, and properly associated with your application
+ and the user. This step is critical for maintaining secure
+ sessions. This endpoint requires X-SIMPLEAUTHLINK-APPID and
+ X-SIMPLEAUTHLINK-SECRET auth headers to be defined.
requestBody:
content:
application/json:
diff --git a/docs/apps.md b/docs/apps.md
new file mode 100644
index 0000000..e48c136
--- /dev/null
+++ b/docs/apps.md
@@ -0,0 +1,100 @@
+---
+title: π Apps
+layout: default
+permalink: /apps
+---
+
+# Apps π
+
+An **application** is a collection of user tokens managed by an administrator. Each app encapsulates essential information used to identify, authenticate, and manage user sessions. The app details include:
+
+- **Name (`name`):**
+ A human-readable identifier for the application. This name is used, for example, in the body of the magic link email sent to users during the authentication process.
+
+- **App Session Duration (`session_duration`):**
+ The duration of a user session, expressed as a [Go duration string](https://pkg.go.dev/time#ParseDuration) (e.g. `"30m"`, `"1h"`, `"2h30m"`). This value determines the expiration time of any token generated for the app.
+
+- **Redirect URL (`redirect_url`):**
+ The URL of your service where users are redirected after authentication. The generated user token and the user email will be appended to this URL as query parameters named `token` and `user`.
+
+- **App Secret (`secret`):**
+ A confidential passphrase that must be kept secure. This secret is crucial for generating tokens for your application and validating the AppID.
+
+{: .info }
+> This service does not store any information nor does it depend on any persistent storage component.
+> - AppIDs are generated deterministically from the app configuration and the secret.
+> - Tokens are created with embedded information that verifies both the application and the user's identity.
+>
+> Consequently, both **AppIDs** and **Tokens** are ephemeral. If they are lost, they cannot be recovered unless the original configuration (including the secret) is known.
+
+## About the App ID πͺͺ
+
+The App ID is a **self-contained** representation of the app configuration. It is generated by joining the app attributes (name, redirect URL, session duration and a truncated hash of the secret) with a separator and base64url-encoding the result. Because the App ID embeds a hash of the secret, it can only be produced by an instance that knows both the app configuration and the backend secret.
+
+## About the App Secret π
+
+The app secret is composed of two parts:
+
+- **User-Provided Part:** This component is supplied by the administrator during the app creation process. It is used to prove ownership of the application and to generate the authentication tokens. Since only the administrator knows this part, it must remain confidential.
+
+- **Backend-Defined Part:** This component is determined by the backend to validate that the AppID was generated by the current backend instance. Similar to the user-provided part, it is known only to the backend and must not be disclosed.
+
+Both parts are hashed with SHA-256 and concatenated to compose the **full secret** used to sign tokens. Together, these two parts ensure that the authentication process remains secure and that the tokens generated are valid and unique to your application.
+
+## Create Your App via the API π οΈ
+
+Register a new application by sending its configuration to the [`POST /apps`]({{ '/api/#/apps/post_apps' | absolute_url }}) endpoint:
+
+```http
+POST /apps
+Content-Type: application/json
+
+{
+ "name": "MySuperMegaApp",
+ "session_duration": "30m",
+ "redirect_url": "https://example.com/callback",
+ "secret": "mysupersecret"
+}
+```
+
+Response:
+
+```json
+{
+ "id": ""
+}
+```
+
+Store the returned `id` (the **App ID**) and the **secret** you provided β you will need both to request and verify tokens.
+
+**Important:** The secret must be kept secure. If the secret is lost, the AppID must be regenerated. Note that the secret cannot be recovered, only regenerated; therefore, it is imperative that the administrator maintains its confidentiality.
+
+### Go client example
+
+```go
+import (
+ "log"
+ "time"
+
+ "github.com/simpleauthlink/authapi/api/client"
+)
+
+func main() {
+ // create the client (it performs a health check on startup)
+ cli, err := client.New(&client.Config{
+ APIEndpoint: "https://api.simpleauth.link",
+ })
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // create a new App ID for the app configuration
+ appID, err := cli.NewAppID("MySuperMegaApp", "https://example.com/callback", "mysupersecret", 30*time.Minute)
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // configure the client to use the created App ID and secret
+ cli.SetupAppID(appID, "mysupersecret")
+}
+```
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..3d03910
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,37 @@
+---
+layout: home
+---
+
+# SimpleAuth.link
+
+**Passwordless authentication for your users using just an email address.**
+
+SimpleAuth.link empowers application developers to **eliminate the complexities of user authentication** and login systems. It streamlines the user experience by replacing traditional passwords with a secure, email-based login mechanism.
+
+## Why Choose SimpleAuth.link?
+
+- **π Enhanced Security:** By removing passwords from the equation, you reduce the risks of password theft, reuse, and related vulnerabilities. Instead, authentication is handled via secure, cryptographically generated tokens signed with Ed25519.
+
+- **π§βπ» Improved User Experience:** Users enjoy a simplified login process. With no need to remember or manage passwords, they can quickly and safely access your application using a magic link sent to their email.
+
+- **π Efficient Integration:** With only a couple of API requests, you can seamlessly integrate SimpleAuth.link into your application. A [Go client]({{ '/about/tokens#go-client-examples' | relative_url }}) is also provided to get you started even faster.
+
+- **π‘οΈ Privacy & Uniqueness:** SimpleAuth.link stores nothing. Tokens are self-contained and stateless: the user's email is embedded (base64url-encoded) and the whole token is signed, so no personal data is ever stored on SimpleAuth.link servers.
+
+## Getting Started
+
+1. **Create Your App:** Begin by [creating your app]({{ '/api/#/apps/post_apps' | absolute_url }}). This step involves setting up your application with a unique App ID, defining session parameters, and configuring the redirect URL and secret.
+
+2. **Authenticate Your Users:** Use the authentication endpoint to [request a token for your users]({{ '/api/#/tokens/post_tokens' | absolute_url }}). When a user provides their email, SimpleAuth.link will generate a secure token and send it via a magic link, allowing them to log in effortlessly.
+
+3. **Verify the Token:** When the user returns through the magic link, [verify the token]({{ '/api/#/tokens/put_tokens' | absolute_url }}) before opening the session.
+
+## Try the API
+
+The interactive [Swagger UI]({{ '/api/' | absolute_url }}) is the fastest way to explore and test the endpoints. You can also run the API locally:
+
+```bash
+go run ./cmd/authapi
+```
+
+SimpleAuth.link is designed to take the burden of user authentication off your shoulders, allowing you to focus on what matters mostβdelivering an exceptional experience to your users.
\ No newline at end of file
diff --git a/docs/self-host.md b/docs/self-host.md
new file mode 100644
index 0000000..bb13a0d
--- /dev/null
+++ b/docs/self-host.md
@@ -0,0 +1,122 @@
+---
+title: π Self-host
+layout: default
+permalink: /self-host
+---
+
+# Self-Hosting Your Project π
+
+This section explains how to deploy and run your project in a self-hosted environment. You have three main options:
+
+1. **Using Docker directly with the provided Dockerfile π³**
+2. **Using the Makefile for an automated build and run process βοΈ**
+3. **Executing the Go code directly with command-line flags π¨βπ»**
+
+---
+
+## Option 1: Docker Deployment π³
+
+The Docker deployment is based on the production Dockerfile located at `docker/Dockerfile.prod`. It produces a minimal, [distroless](https://github.com/GoogleContainerTools/distroless) image that runs the API as a non-root user.
+
+### 1. **Prepare the Environment File π**
+
+Copy the `example.env` file to `.env` and edit the file to fill in your parameters:
+
+```bash
+HOST="localhost"
+PORT=8080
+EMAIL_ADDR="test@test.com"
+EMAIL_USER="test@test.com"
+EMAIL_PASS="smtp_server_password"
+EMAIL_HOST="smtp.example.com"
+EMAIL_PORT=587
+SECRET="my_backend_secret"
+NOTIFICATION_QUEUE_SIZE=1000
+NOTIFICATION_QUEUE_WORKERS=10
+```
+
+### 2. Build the Docker Image ποΈ
+
+Run the following command in the root of your project to build the image:
+
+```bash
+docker build -f docker/Dockerfile.prod -t simpleauthlink .
+```
+
+### 3. Run the Docker Container π’
+
+Once the image is built, start a container using the environment file:
+
+```bash
+docker run --name simpleauthlink --env-file .env -p ${PORT}:${PORT} simpleauthlink
+```
+
+The API listens on the `PORT` value defined in your `.env` (default `8080`), both inside the container and on your host.
+
+---
+
+## Option 2: Using the Makefile βοΈ
+
+The Makefile in the root of the project simplifies the build and run process:
+
+- `make api` β builds and runs the API container using `docker/Dockerfile.prod`.
+- `make demo` β builds and runs the demo container using `docker/Dockerfile.demo`.
+- `make swagger-ui` β generates the swagger spec and serves it locally with Swagger UI.
+- `make clean-api` / `make clean-demo` β clean up the corresponding containers and images.
+
+### 1. Set Up the Environment File π
+
+As with the Docker approach, copy and edit `example.env` to `.env` with your configuration.
+
+### 2. Build and Run Using Make πββοΈ
+
+Run the following command from your project root:
+
+```bash
+make api
+```
+
+This will:
+
+- Clean up any previous containers and images.
+- Build the Docker image using `docker/Dockerfile.prod`.
+- Run the container with the environment variables from `.env` and expose the API on the configured `PORT`.
+
+## Option 3: Running the Go Code Directly π¨βπ»
+
+If you prefer to run the API without Docker, you can execute the Go code directly. The entry point is `cmd/authapi/main.go` and it accepts several flags, which can also be provided via environment variables:
+
+- `--host` or environment variable `HOST` (default: `"0.0.0.0"`)
+- `--port` or environment variable `PORT` (default: `8080`)
+- `--secret` or environment variable `SECRET` (required)
+- `--email-addr` or environment variable `EMAIL_ADDR` (required)
+- `--email-user` or environment variable `EMAIL_USER` (SMTP username)
+- `--email-pass` or environment variable `EMAIL_PASS` (SMTP password)
+- `--email-host` or environment variable `EMAIL_HOST` (required)
+- `--email-port` or environment variable `EMAIL_PORT` (default: `587`)
+- `--queue-size` or environment variable `NOTIFICATION_QUEUE_SIZE` (default: `1000`)
+- `--queue-workers` or environment variable `NOTIFICATION_QUEUE_WORKERS` (default: `10`)
+
+The command loads `.env` automatically when it exists, so you can simply run:
+
+```bash
+go run ./cmd/authapi
+```
+
+Or pass everything explicitly:
+
+```bash
+go run ./cmd/authapi \
+ --host="0.0.0.0" \
+ --port=8080 \
+ --secret="my_backend_secret" \
+ --email-addr="test@test.com" \
+ --email-user="test@test.com" \
+ --email-pass="smtp_server_password" \
+ --email-host="smtp.example.com" \
+ --email-port=587
+```
+
+---
+
+Choose the option that best fits your deployment needs. The Docker and Makefile options are ideal for containerized environments, while running the Go code directly might be preferred for development or custom setups.
\ No newline at end of file
diff --git a/docs/tokens.md b/docs/tokens.md
new file mode 100644
index 0000000..c19a657
--- /dev/null
+++ b/docs/tokens.md
@@ -0,0 +1,135 @@
+---
+title: π Tokens
+layout: default
+permalink: /tokens
+---
+
+# Tokens π
+
+A **token** represents a valid session for an authenticated user associated with your application. Each token is designed with the following characteristics:
+
+- **Passwordless:** Users only need an active email account to receive a token. There is no requirement for passwords or additional credentials, simplifying the authentication process.
+- **Self-contained:** Each token embeds everything needed to verify it β the expiration time, a signature and the user's email β so it can be validated with nothing more than the app configuration and secret.
+- **Signed:** The token is signed with Ed25519 using a key derived from your App ID and secret, so any modification invalidates the signature.
+- **Temporal:** Tokens are created with a defined lifespan for security purposes. The expiration time is specified in the application's configuration during its creation process.
+
+## About the Token Structure π§©
+
+Tokens are generated by the service and delivered to users via email. They are included as the `token` query parameter (alongside the `user` email) in a **magic link**, which uses the application's `redirect_url`. This process ensures that the token reaches the intended recipient and that it is only valid for a limited period.
+
+A token consists of **three parts**, separated by a dot:
+
+```
+..
+```
+
+For example:
+
+```
+MjAyNS0wMy0zMVQwMjoyNToyNC4xMjc3NDkrMDI6MDA.6VjTMr+lyUXtxNT7MZ17E/Mvdhtx87bJM8cTQ9El8ERokB+K9ew0AWRkI5vUjmKv1Slq5nvlfdqypege0oXgCg.dXNlckBleGFtcGxlLmNvbQ
+```
+
+Each part is a base64url-encoded value:
+
+- **Expiration:** the moment the token expires, encoded from its RFC 3339 timestamp.
+- **Signature:** the Ed25519 signature over `sha256(AppID || email || expiration)`, computed with a private key deterministically derived from the full secret and the App ID. The signature makes the token tamper-evident: verifying it proves the token was issued by your application and has not been altered.
+- **Email:** the base64url encoding of the authenticated user's email address.
+
+### Token secret
+
+The full secret used to sign tokens is calculated by hashing two parts with `sha256`: one remains private in the service (to ensure that the token comes from the right instance) and another defined by the app creator (to ensure that it comes from your app).
+
+## Request a Token via the API π
+
+Request a token for a user by sending their email to the [`POST /tokens`]({{ '/api/#/tokens/post_tokens' | absolute_url }}) endpoint, authenticating with your App ID and secret headers:
+
+```http
+POST /tokens
+X-SIMPLEAUTHLINK-APPID:
+X-SIMPLEAUTHLINK-SECRET:
+Content-Type: application/json
+
+{
+ "email": "user@example.com"
+}
+```
+
+A magic link is sent to that email address. The link is the app's `redirect_url` with the `token` and `user` query parameters appended.
+
+## Verify a Token via the API β
+
+Verify a token (for example, when the user returns through the magic link) by sending it to the [`PUT /tokens`]({{ '/api/#/tokens/put_tokens' | absolute_url }}) endpoint:
+
+```http
+PUT /tokens
+X-SIMPLEAUTHLINK-APPID:
+X-SIMPLEAUTHLINK-SECRET:
+Content-Type: application/json
+
+{
+ "token": ""
+}
+```
+
+Response:
+
+```json
+{
+ "valid": true,
+ "expiration": "2025-03-31T02:25:24.127749+02:00"
+}
+```
+
+## Go client examples π¨βπ»
+
+### Request and verify a token
+
+```go
+import (
+ "fmt"
+ "log"
+
+ "github.com/simpleauthlink/authapi/api/client"
+ "github.com/simpleauthlink/authapi/token"
+)
+
+func main() {
+ cli, err := client.Default("", "", false)
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // send a login email to the user
+ err = cli.RequestToken(new(token.Email).SetString("user@example.com"))
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // the user receives the token by email (the magic link)
+ rawToken := ""
+ userToken := new(token.Token).SetString(rawToken)
+
+ // verify it
+ valid, expiresAt, err := cli.VerifyToken(userToken)
+ if err != nil {
+ log.Fatal(err)
+ }
+ if valid {
+ fmt.Printf("session valid until %s\n", expiresAt)
+ }
+}
+```
+
+### Verify a token on an incoming request
+
+Once the user returns through the magic link, the token arrives as a `token` query parameter on your `redirect_url` (or as an `X-SIMPLEAUTHLINK-TOKEN` header). You can validate it inside your HTTP handler:
+
+```go
+// token delivered as a query parameter
+email, valid, err := cli.AuthorizedRequestURLParams(r)
+
+// token delivered as a request header
+email, valid, err := cli.AuthorizedRequestHeaders(r)
+```
+
+Both helpers return the authenticated user's email and whether the token is currently valid.
\ No newline at end of file
diff --git a/scripts/generate-swagger-ui.sh b/scripts/generate-swagger-ui.sh
index 1c5e413..a0a670c 100755
--- a/scripts/generate-swagger-ui.sh
+++ b/scripts/generate-swagger-ui.sh
@@ -5,15 +5,15 @@ set -euo pipefail
SWAGGER_UI_VERSION="5.18.2"
CDN="https://cdn.jsdelivr.net/npm/swagger-ui-dist@${SWAGGER_UI_VERSION}"
-mkdir -p docs
+mkdir -p docs/api
echo "Downloading Swagger UI assets..."
-curl -fsSL -o docs/swagger-ui.css "$CDN/swagger-ui.css"
-curl -fsSL -o docs/swagger-ui-bundle.js "$CDN/swagger-ui-bundle.js"
-curl -fsSL -o docs/LICENSE.swagger-ui "$CDN/LICENSE"
+curl -fsSL -o docs/api/swagger-ui.css "$CDN/swagger-ui.css"
+curl -fsSL -o docs/api/swagger-ui-bundle.js "$CDN/swagger-ui-bundle.js"
+curl -fsSL -o docs/api/LICENSE.swagger-ui "$CDN/LICENSE"
echo "Generating Swagger UI entry point..."
-cat > docs/index.html <<'HTML'
+cat > docs/api/index.html <<'HTML'
@@ -42,6 +42,18 @@ cat > docs/index.html <<'HTML'