diene.go-auth-engine

README

Diene Go auth-engine library

Diene's reproducible development environment is managed by Nix. Run direnv allow once, then use pls tasks from the loaded shell.

This repository inherits the all-features workspace baseline: split CI/CD, secrets, release configuration, validators, standards, and vendored agent-skill synchronization.

Commands

• pls setup — synchronize installed diene package skills.
• pls lint — run every pre-commit gate.
• pls secret:scan — scan tracked content for secrets.
• pls skills:sync — rebuild .claude/skills/vendor/ from installed packages.

Publishable Go module

github.com/AtomiCloud/diene.go-auth-engine is the Go family's server-side auth engine: JWT/JWKS validation against a baked OIDC issuer, the Logto adapter, per-resource access tokens over the resourceTree model, machine-to-machine client-credential flows, deferred deep-link login mint/redeem, the OnboardSync per-backend onboarding phase machine, and the family nullable-userId ownership authorization pattern — all problem-typed through github.com/AtomiCloud/diene.go-errors-problems and shipped with a consumer-facing testhelper package.

go get github.com/AtomiCloud/diene.go-auth-engine@latest

principal, err := validator.Validate(ctx, bearer)
if err != nil {
	return err
}
if err := guard.SubOrAny(principal, query.UserID, authengine.ClaimRoles, "admin"); err != nil {
	return err
}

Packages:

• lib/authengine — validation, principal mapping, resource tree and token cache, retrievers, refresh rotation, ownership guard, named claim policies, and the engine-owned config block.
• lib/logto — the Logto adapter behind the provider seam (OIDC discovery, remote JWKS, token endpoint, one-time tokens, Management API claim write-back).
• lib/deferred — deferred deep-link login: nonce mint/exchange plus the Android Install Referrer and iOS clipboard carrier builders.
• lib/onboard — OnboardSync: claims-first per-backend onboarding phase machine and the pre-onboarding home-landscape selector.
• testhelper — fake IdP/JWKS, fake provider, in-memory stores, per-backend onboarding fakes, and Problem-shaped auth assertions.

Engine concepts (resourceTree, deferred deep-link login, the onboarding phase machine, and the ownership guard) are documented on the packages themselves and in the shipped usage skill skills/diene-go-auth-engine-usage/SKILL.md. The authorization doctrine this library implements is the shared standard Authorization.

Go commands

• pls build — build every package in the module.
• pls typecheck — compile every source package without running tests.
• pls test / pls test:coverage — run unit, integration, and active meta tiers.
• pls deadcode — run strict whole-repository and production passes plus the LLM-lax report.
• pls up / pls down — start or stop local infrastructure (this library binds none).
• ./scripts/ci/pkg-validate.sh all — run module-path, vet, API, docs, and example validators.

See the Go baseline for the language contract and template-maintenance boundary. See the Go library baseline for promotion, testing, compatibility, and publication policy.

Standards

• CI/CD workflows
• conventional commits
• Infisical and secrets
• linting and pre-commit
• Nix flakes and development shells
• release automation
• service-tree identity
• shell scripts
• Taskfile conventions

Shared standards

• Authorization
• Contributor documentation
• Date and time
• Domain-driven design
• Functional practices
• Software design philosophy
• SOLID principles
• Stateless OOP and dependency injection
• Testing
• Three-layer architecture
• Utility libraries
• Data validation

Domain-specific documentation belongs under docs/domain/. The docs/standards/contracts/ location is reserved for the separately owned C0 contracts standard.

Go language variants

• Date and time
• Domain-driven design
• Functional practices
• SOLID principles
• Stateless OOP and dependency injection
• Testing
• Utilities
• Validation