feat: implement cursor-based pagination (#96)

* feat: implement cursor-based pagination and add migration rollback command

This release introduces cursor-based pagination across all list operations
to improve performance and consistency, along with new administrative
commands for database and secret management.

Key changes:
- Refactor all list operations (Audit Logs, Clients, Secrets, Tokenization
  Keys, and Transit Keys) from offset-based to cursor-based pagination.
- Add `migrate-down` CLI command to rollback database migrations.
- Add `purge-secrets` CLI command to permanently delete soft-deleted secrets
  with dry-run and multiple output formats support.
- Add configurable HTTP server read, write, and idle timeouts.
- Implement KMS connectivity validation at server startup.
- Update documentation and OpenAPI specification for new pagination and commands.
- Correct `rotate-master-key` CLI flags and documentation.
- Bump version to v0.25.0 and update CHANGELOG.md.

* fix tests

Author: allisson

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 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).
 
+## [0.25.0] - 2026-03-03
+
+### Added
+- Added secret purge command (`purge-secrets`) with dry-run and formatting support.
+- Added configurable server read/write/idle timeouts for better resource management and security.
+- Added KMS connectivity validation at server startup.
+- Added security scanning tools to CI and development workflow.
+- Updated documentation and CI configuration to enforce coverage and code quality standards.
+
+### Fixed
+- Corrected `rotate-master-key` CLI flags (`kms-provider` and `kms-key-uri`) and documentation to ensure consistency and completeness.
+- Fixed integration tests setup by separating them out from unit tests.
+
 ## [0.24.0] - 2026-03-03
 
 ### Changed
@@ -415,6 +428,8 @@ If you are using `sslmode=disable` (PostgreSQL) or `tls=false` (MySQL) in produc
 - Security model documentation
 - Architecture documentation
 
+[0.25.0]: https://github.com/allisson/secrets/compare/v0.24.0...v0.25.0
+[0.24.0]: https://github.com/allisson/secrets/compare/v0.23.0...v0.24.0
 [0.23.0]: https://github.com/allisson/secrets/compare/v0.22.1...v0.23.0
 [0.22.1]: https://github.com/allisson/secrets/compare/v0.22.0...v0.22.1
 [0.22.0]: https://github.com/allisson/secrets/compare/v0.21.0...v0.22.0

Makefile

@@ -121,7 +121,8 @@ migrate-up: ## Run database migrations up
 	@$(BINARY) migrate
 
 migrate-down: ## Run database migrations down
-	@echo "Rollback migrations not implemented in binary. Use golang-migrate CLI directly."
+	@echo "Rolling back migrations..."
+	@$(BINARY) migrate-down --steps=1
 
 # Docker
 docker-build: ## Build Docker image with version injection

cmd/app/commands/migrations.go

@@ -38,3 +38,32 @@ func RunMigrations(logger *slog.Logger, dbDriver, dbConnectionString string) err
 	logger.Info("migrations completed successfully")
 	return nil
 }
+
+// RunMigrationsDown rolls back database migrations based on the configured driver.
+// Determines migration path from DBDriver (postgresql or mysql) and rolls back the specified
+// number of migrations. Returns nil if no migrations to rollback. Logs migration progress and success.
+func RunMigrationsDown(logger *slog.Logger, dbDriver, dbConnectionString string, steps int) error {
+	logger.Info("rolling back database migrations",
+		slog.String("driver", dbDriver),
+		slog.Int("steps", steps),
+	)
+
+	// Determine migration path based on driver
+	migrationsPath := "file://migrations/postgresql"
+	if dbDriver == "mysql" {
+		migrationsPath = "file://migrations/mysql"
+	}
+
+	m, err := migrate.New(migrationsPath, dbConnectionString)
+	if err != nil {
+		return fmt.Errorf("failed to create migrate instance: %w", err)
+	}
+	defer CloseMigrate(m, logger)
+
+	if err := m.Steps(-steps); err != nil && !errors.Is(err, migrate.ErrNoChange) {
+		return fmt.Errorf("failed to rollback migrations: %w", err)
+	}
+
+	logger.Info("migrations rolled back successfully")
+	return nil
+}

cmd/app/commands/migrations_test.go

@@ -23,3 +23,27 @@ func TestRunMigrations(t *testing.T) {
 		require.Contains(t, err.Error(), "failed to create migrate instance")
 	})
 }
+
+func TestRunMigrationsDown(t *testing.T) {
+	logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
+
+	t.Run("invalid-driver", func(t *testing.T) {
+		err := RunMigrationsDown(logger, "invalid", "postgres://localhost", 1)
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "failed to create migrate instance")
+	})
+
+	t.Run("invalid-connection-string", func(t *testing.T) {
+		err := RunMigrationsDown(logger, "postgres", "invalid-connection-string", 1)
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "failed to create migrate instance")
+	})
+
+	t.Run("zero-steps", func(t *testing.T) {
+		// Zero steps should still attempt to create the migrate instance and return ErrNoChange
+		err := RunMigrationsDown(logger, "postgres", "postgres://localhost/testdb", 0)
+		require.Error(t, err)
+		// Will fail at migrate instance creation since we don't have a real DB, which is expected
+		require.Contains(t, err.Error(), "failed to create migrate instance")
+	})
+}

cmd/app/main.go

@@ -12,7 +12,7 @@ import (
 
 // Build-time version information (injected via ldflags during build).
 var (
-	version   = "v0.24.0" // Semantic version with "v" prefix (e.g., "v0.12.0")
+	version   = "v0.25.0" // Semantic version with "v" prefix (e.g., "v0.12.0")
 	buildDate = "unknown" // ISO 8601 build timestamp
 	commitSHA = "unknown" // Git commit SHA
 )

cmd/app/system_commands.go

@@ -37,6 +37,32 @@ func getSystemCommands(version string) []*cli.Command {
 				)
 			},
 		},
+		{
+			Name:  "migrate-down",
+			Usage: "Rollback database migrations",
+			Flags: []cli.Flag{
+				&cli.IntFlag{
+					Name:    "steps",
+					Aliases: []string{"n"},
+					Value:   1,
+					Usage:   "Number of migrations to rollback",
+				},
+			},
+			Action: func(ctx context.Context, cmd *cli.Command) error {
+				return commands.ExecuteWithContainer(
+					ctx,
+					func(ctx context.Context, container *app.Container) error {
+						cfg := container.Config()
+						return commands.RunMigrationsDown(
+							container.Logger(),
+							cfg.DBDriver,
+							cfg.DBConnectionString,
+							int(cmd.Int("steps")),
+						)
+					},
+				)
+			},
+		},
 		{
 			Name:  "clean-audit-logs",
 			Usage: "Delete audit logs older than specified days",

docs/cli-commands.md

@@ -50,6 +50,43 @@ Docker:
 docker run --rm --network secrets-net --env-file .env allisson/secrets migrate
 ```
 
+### `migrate-down`
+
+Rolls back database migrations. This command should **only be used for emergency rollbacks**, not for regular operations.
+
+Flags:
+
+- `--steps`, `-n` (default `1`): number of migrations to rollback
+
+Local:
+
+```bash
+# Rollback the last migration
+./bin/app migrate-down
+
+# Rollback the last 3 migrations
+./bin/app migrate-down --steps 3
+```
+
+Docker:
+
+```bash
+docker run --rm --network secrets-net --env-file .env allisson/secrets migrate-down --steps 1
+```
+
+**Important warnings:**
+
+- Migration rollbacks are **potentially destructive** operations that may result in data loss
+- Always backup your database before running rollback operations
+- Only use this command for emergency rollbacks (e.g., after a failed migration)
+- For production systems, test rollback procedures in a staging environment first
+- Consider forward-only migrations instead of rollbacks when possible
+
+Requirements:
+
+- Database must be reachable
+- Down migration SQL files must exist for the migrations being rolled back
+
 ## Key Management
 
 ### `create-master-key`

docs/engines/secrets.md

@@ -79,14 +79,45 @@ Example response (`200 OK`):
 
 - **Endpoint**: `GET /v1/secrets`
 - **Capability**: `read`
-- **Query Params**: `offset` (default 0), `limit` (default 50)
+- **Query Params**:
+  - `after_path` (optional) - Cursor for pagination. Omit for first page.
+  - `limit` (default 50, max 1000) - Number of items per page.
 - **Success**: `200 OK` (Does not return secret values)
 
 ```bash
-curl "http://localhost:8080/v1/secrets?offset=0&limit=50" 
+# First page
+curl "http://localhost:8080/v1/secrets?limit=50" \
   -H "Authorization: Bearer <token>"
+
+# Subsequent pages (use next_cursor from previous response)
+curl "http://localhost:8080/v1/secrets?after_path=app/prod/db&limit=50" \
+  -H "Authorization: Bearer <token>"
+```
+
+Example response (`200 OK`):
+
+```json
+{
+  "data": [
+    {
+      "id": "0194f4a5-73fe-7a7d-a3a0-6fbe9b5ef8f3",
+      "path": "app/prod/database-password",
+      "version": 3,
+      "created_at": "2026-02-27T18:22:00Z"
+    },
+    {
+      "id": "0194f4b2-91ab-7c3d-b5e1-8adc2f6ea4c9",
+      "path": "app/prod/redis-password",
+      "version": 1,
+      "created_at": "2026-02-27T19:15:00Z"
+    }
+  ],
+  "next_cursor": "app/prod/redis-password"
+}
 ```
 
+**Note**: The `next_cursor` field is only present when there are more pages available. When it's absent, you've reached the last page.
+
 ### Delete Secret
 
 - **Endpoint**: `DELETE /v1/secrets/*path`

docs/engines/tokenization.md

@@ -98,8 +98,60 @@ Example response (`200 OK`):
 
 ### List and Delete Keys
 
-- `GET /v1/tokenization/keys` (Capability: `read`)
-- `DELETE /v1/tokenization/keys/:id` (Capability: `delete`)
+#### List Tokenization Keys
+
+- **Endpoint**: `GET /v1/tokenization/keys`
+- **Capability**: `read`
+- **Query Params**:
+  - `after_name` (optional) - Cursor for pagination. Omit for first page.
+  - `limit` (default 50, max 1000) - Number of items per page.
+- **Success**: `200 OK`
+
+```bash
+# First page
+curl "http://localhost:8080/v1/tokenization/keys?limit=50" \
+  -H "Authorization: Bearer <token>"
+
+# Subsequent pages (use next_cursor from previous response)
+curl "http://localhost:8080/v1/tokenization/keys?after_name=payment-tokens&limit=50" \
+  -H "Authorization: Bearer <token>"
+```
+
+Example response (`200 OK`):
+
+```json
+{
+  "data": [
+    {
+      "id": "0194f4c1-82de-7f9a-c2b3-9def1a7bc5d8",
+      "name": "customer-ids",
+      "algorithm": "uuid_v7",
+      "is_deterministic": true,
+      "version": 2,
+      "created_at": "2026-02-27T20:10:00Z",
+      "updated_at": "2026-02-28T10:30:00Z"
+    },
+    {
+      "id": "0194f4d3-a5bc-7e2f-d8a1-4bef2c9ad7e1",
+      "name": "payment-tokens",
+      "algorithm": "luhn_preserving",
+      "is_deterministic": false,
+      "version": 1,
+      "created_at": "2026-02-27T21:45:00Z",
+      "updated_at": "2026-02-27T21:45:00Z"
+    }
+  ],
+  "next_cursor": "payment-tokens"
+}
+```
+
+**Note**: The `next_cursor` field is only present when there are more pages available.
+
+#### Delete Tokenization Key
+
+- **Endpoint**: `DELETE /v1/tokenization/keys/:name`
+- **Capability**: `delete`
+- **Success**: `204 No Content`
 
 ## Deterministic Tokenization
 

docs/engines/transit.md

@@ -98,8 +98,58 @@ Example decrypt response (`200 OK`):
 
 ### List and Delete Keys
 
-- `GET /v1/transit/keys` (Capability: `read`)
-- `DELETE /v1/transit/keys/:id` (Capability: `delete`)
+#### List Transit Keys
+
+- **Endpoint**: `GET /v1/transit/keys`
+- **Capability**: `read`
+- **Query Params**:
+  - `after_name` (optional) - Cursor for pagination. Omit for first page.
+  - `limit` (default 50, max 1000) - Number of items per page.
+- **Success**: `200 OK`
+
+```bash
+# First page
+curl "http://localhost:8080/v1/transit/keys?limit=50" \
+  -H "Authorization: Bearer <token>"
+
+# Subsequent pages (use next_cursor from previous response)
+curl "http://localhost:8080/v1/transit/keys?after_name=main-encryption&limit=50" \
+  -H "Authorization: Bearer <token>"
+```
+
+Example response (`200 OK`):
+
+```json
+{
+  "data": [
+    {
+      "id": "0194f4e1-c3ab-7d8e-a9f2-5cde3b8fa6c1",
+      "name": "app-encryption",
+      "algorithm": "aes256-gcm96",
+      "version": 3,
+      "created_at": "2026-02-27T22:00:00Z",
+      "updated_at": "2026-02-28T12:00:00Z"
+    },
+    {
+      "id": "0194f4f2-d5bc-7a1f-b8c3-6def4c9eb7d2",
+      "name": "main-encryption",
+      "algorithm": "chacha20-poly1305",
+      "version": 1,
+      "created_at": "2026-02-27T23:15:00Z",
+      "updated_at": "2026-02-27T23:15:00Z"
+    }
+  ],
+  "next_cursor": "main-encryption"
+}
+```
+
+**Note**: The `next_cursor` field is only present when there are more pages available.
+
+#### Delete Transit Key
+
+- **Endpoint**: `DELETE /v1/transit/keys/:name`
+- **Capability**: `delete`
+- **Success**: `204 No Content`
 
 ## Relevant CLI Commands