MIGRATION.md

Migration & workspace layout

The repository hosts one Go workspace (go.work) and several Go modules. This layout lets consumers import only the pieces they need, keeps the core free of heavy transitive dependencies, and lets each module be tagged and released on its own cadence.

Modules

Path	Module	Purpose
.	github.com/hyperscale-stack/security	Core: transport-agnostic primitives (Authentication, Engine, Voter…)
./http	github.com/hyperscale-stack/security/http	httpsec — net/http adapter
./grpc	github.com/hyperscale-stack/security/grpc	grpcsec — gRPC unary/stream interceptors
./connectrpc	github.com/hyperscale-stack/security/connectrpc	connectrpcsec — ConnectRPC auth + authorize interceptors
./basic	github.com/hyperscale-stack/security/basic	HTTP Basic extractor + authenticator
./bearer	github.com/hyperscale-stack/security/bearer	Bearer extractor + TokenVerifier-based authenticator
./password	github.com/hyperscale-stack/security/password	BCrypt + Argon2id hashers
./jwt	github.com/hyperscale-stack/security/jwt	jwtsec — JWT signer/verifier + JWKS
./session	github.com/hyperscale-stack/security/session	Stateless encrypted cookie sessions + CSRF
./oauth2	github.com/hyperscale-stack/security/oauth2	OAuth2 server (profiles, grants, endpoints)
./oauth2/store/sql	github.com/hyperscale-stack/security/oauth2/store/sql	Production storage on database/sql
./oauth2/store/redis	github.com/hyperscale-stack/security/oauth2/store/redis	Production storage on Redis (Lua atomicity)
./examples	github.com/hyperscale-stack/security/examples	Runnable use-case demos (one sub-package per scenario)
./internal/integrations	github.com/hyperscale-stack/security/internal/integrations	Cross-module end-to-end tests (private)

oauth2/storage/memory is a sub-package of the oauth2 module (not a standalone module): it ships the in-memory oauth2.Storage used for dev and tests.

The legacy v0 packages (authentication/, authentication/credential/, authentication/provider/{dao,oauth2}/, authorization/, and the old in-tree password) were removed during the rewrite. The core module now depends only on stdlib + go.opentelemetry.io/otel (+ testify for its own tests).

Dependency policy

core (.)                ← stdlib + go.opentelemetry.io/otel
http/                   ← core + otel
grpc/                   ← core + otel + google.golang.org/grpc
connectrpc/             ← core + otel + connectrpc.com/connect
basic/                  ← core + password
bearer/                 ← core
password/               ← golang.org/x/crypto
jwt/                    ← core + bearer + oauth2 + go-jose/v4 + otel
session/                ← core + golang.org/x/crypto + otel
oauth2/                 ← core + stdlib
oauth2/store/sql/       ← oauth2 + database/sql
oauth2/store/redis/     ← oauth2 + github.com/redis/go-redis/v9
examples/               ← may depend on every module above

(`oauth2/storage/memory` is a sub-package of the `oauth2` module.)

The core MUST NOT depend on: gRPC, ConnectRPC, JWT/JOSE libs, OAuth2, Redis, SQL drivers, HTTP routers, or concrete loggers. Its direct dependency set is exactly stdlib + go.opentelemetry.io/otel (+ stretchr/testify scoped to its own tests). The policy is enforced by review.

Local development

make sync         # go work sync
make build        # build all modules
make test         # race + coverage, aggregated into build/coverage.out
make lint         # golangci-lint on every module with the shared config
make tidy         # go mod tidy on every module + go work sync

The Makefile discovers modules dynamically via find . -name go.mod, so a new sub-module is picked up automatically as soon as its go.mod lands. Example program lines are excluded from the aggregated coverage profile (their main() is not unit-testable); the examples are still built, tested, and linted.

CI

.github/workflows/go.yml runs make sync, make build, make test, and make lint against every module in one job, then publishes the aggregated coverage to Coveralls. .github/workflows/release.yml validates the whole workspace and publishes a GitHub release when a module/vX.Y.Z tag is pushed.

Replace directives

Every sub-module declares replace github.com/hyperscale-stack/security => ../ (or => ../../ for the SQL/Redis sub-modules) so local development and CI work without published versions. Releases are cut per module with module/vX.Y.Z tags.