Rene Nochebuena
18fcd2bee3
Add MaxPermission constant (62) to make the valid bit range explicit in the API. Document in PermissionProvider that audit logging belongs in the application layer. API committed as stable: Identity, PermissionMask, context helpers, and PermissionProvider interface are unchanged from v0.9.0.
52 lines
3.4 KiB
Markdown
52 lines
3.4 KiB
Markdown
# Changelog
|
||
|
||
All notable changes to this module will be documented in this file.
|
||
|
||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||
and this module adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||
|
||
## [1.0.0] — 2026-05-08
|
||
|
||
### Added
|
||
|
||
- `MaxPermission Permission = 62` — exported constant that makes the valid bit range
|
||
explicit in the API; applications can use it in validation code and it is referenced
|
||
in the `Permission` type godoc
|
||
|
||
### Changed
|
||
|
||
- `Permission` type godoc updated to reference `MaxPermission` and document that
|
||
values outside `[0, MaxPermission]` are silently ignored
|
||
- `PermissionProvider` godoc updated to document that audit logging of permission
|
||
checks is out of scope for this package — log denials and grants inside
|
||
PermissionProvider implementations or in the middleware layer
|
||
|
||
### Unchanged
|
||
|
||
Identity, PermissionMask (Has, Grant), context helpers (SetInContext, FromContext),
|
||
and the PermissionProvider interface are API-compatible with v0.9.0.
|
||
|
||
[1.0.0]: https://code.nochebuena.dev/go/rbac/releases/tag/v1.0.0
|
||
|
||
## [0.9.0] - 2026-03-18
|
||
|
||
### Added
|
||
|
||
- `Permission` — `int64` type representing a named bit position (0–62) for a single capability; applications define their own constants using this type
|
||
- `PermissionMask` — `int64` type representing a resolved bit-set of capabilities for a user on a resource
|
||
- `PermissionMask.Has(p Permission) bool` — O(1) check whether a permission bit is set; returns false for out-of-range values (p < 0 or p >= 63)
|
||
- `PermissionMask.Grant(p Permission) PermissionMask` — returns a new mask with the given bit set without mutating the receiver; silently ignores out-of-range values
|
||
- `Identity` — value type (not a pointer) carrying `UID`, `TenantID`, `DisplayName`, and `Email` for an authenticated principal
|
||
- `NewIdentity(uid, displayName, email string) Identity` — constructs an Identity from token authentication data; `TenantID` is intentionally left empty for later enrichment
|
||
- `Identity.WithTenant(id string) Identity` — returns a copy of the Identity with `TenantID` set; does not mutate the receiver, safe for concurrent middleware use
|
||
- `SetInContext(ctx context.Context, id Identity) context.Context` — stores an Identity in a context using a private unexported key type to prevent collisions
|
||
- `FromContext(ctx context.Context) (Identity, bool)` — retrieves the Identity stored by `SetInContext`; returns the zero-value Identity and false if no identity is present
|
||
- `PermissionProvider` interface — `ResolveMask(ctx context.Context, uid, resource string) (PermissionMask, error)` for DB-backed or in-memory permission resolution
|
||
|
||
### Design Notes
|
||
|
||
- `Identity` is a value type throughout — every enrichment call (e.g. `WithTenant`) returns a new copy, eliminating nil-pointer bugs and preventing accidental mutation of a shared context value across concurrent middleware.
|
||
- Permissions are bit positions (0–62) packed into an `int64` mask; applications define their own named `Permission` constants — none are prescribed by this package — keeping the bit-set model flat and free of role-hierarchy complexity.
|
||
- This package owns the context key for `Identity` via an unexported `authContextKey{}` struct, so any module that needs to carry an authenticated identity imports only `rbac`; zero micro-lib dependencies (stdlib only).
|
||
|
||
[0.9.0]: https://code.nochebuena.dev/go/rbac/releases/tag/v0.9.0 |