feat(rbac): initial stable release v0.9.0

Foundational identity and permission types for role-based access control — bit-set PermissionMask, immutable Identity value type, and PermissionProvider interface.

What's included:
- `Identity` value type with NewIdentity / WithTenant constructors and SetInContext / FromContext context helpers
- `Permission` (int64 bit position) and `PermissionMask` (int64 bit-set) with O(1) Has and non-mutating Grant
- `PermissionProvider` interface for DB-backed ResolveMask(ctx, uid, resource) resolution

Tested-via: todo-api POC integration
Reviewed-against: docs/adr/
This commit is contained in:
2026-03-18 13:25:43 -06:00
commit 0864f031a1
17 changed files with 940 additions and 0 deletions

50
doc.go Normal file
View File

@@ -0,0 +1,50 @@
/*
Package rbac provides the foundational types and helpers for identity and
role-based access control across the micro-lib ecosystem.
It is Tier 0: zero external dependencies, stdlib only. Every other module
that needs to carry or inspect an authenticated identity imports this package.
# Identity
[Identity] represents the authenticated principal. It is a value type — never
a pointer — to eliminate nil-check burden and prevent accidental mutation of
a shared context value.
id := rbac.NewIdentity(uid, displayName, email)
// Enrichment (e.g. from a database lookup) returns a new value
id = id.WithTenant(tenantID)
// Thread it through the request context
ctx = rbac.SetInContext(ctx, id)
// Retrieve it anywhere downstream
id, ok := rbac.FromContext(ctx)
# Permissions
[Permission] is a typed bit position (062). Applications define their own
named constants using this type:
const (
Read rbac.Permission = 0
Write rbac.Permission = 1
Delete rbac.Permission = 2
)
[PermissionMask] is the resolved bit-mask returned by a [PermissionProvider].
Use [PermissionMask.Has] to check whether a permission is granted:
mask, err := provider.ResolveMask(ctx, uid, "orders")
if !mask.Has(Read) {
return rbac.ErrPermissionDenied
}
# PermissionProvider
[PermissionProvider] is the interface that authorization backends implement.
The httpauth module calls it from its AuthzMiddleware without knowing the
concrete implementation.
*/
package rbac