/*
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 (0–62). 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