permission

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 10 Imported by: 0

README

go-permission

CI Go Reference

Role-based access control for multi-tenant SaaS applications, with typed resource policies. Group permissions into roles, assign them to users or API keys per tenant or team, and ask Can(ctx, user, "invoices.create", tenant). Rules that depend on the resource itself ("authors may edit their own posts") live in typed policy functions that can call the RBAC checks. Effective permissions are cached and invalidated across every instance of your application through PostgreSQL LISTEN/NOTIFY.

Install

go get github.com/byteminus/go-permission

Requires Go 1.26 or later. The PostgreSQL store supports PostgreSQL 16 and later.

Quick start

package main

import (
	"context"
	"errors"
	"fmt"
	"log"

	"github.com/byteminus/go-permission"
	"github.com/byteminus/go-permission/memstore"
)

type Post struct {
	AuthorID string
	TeamID   string
}

func main() {
	ctx := context.Background()
	authz, err := permission.New(memstore.New(), permission.Options{SuperAdminRole: "superadmin"})
	if err != nil {
		log.Fatal(err)
	}

	// Roles are defined once and assigned per team.
	if _, err := authz.CreateRole(ctx, "editor", "Writes and publishes posts"); err != nil {
		log.Fatal(err)
	}
	if err := authz.GrantToRole(ctx, "editor", "posts.*"); err != nil {
		log.Fatal(err)
	}
	alice := permission.Subject{Type: "user", ID: "alice"}
	if err := authz.AssignRole(ctx, alice, "editor", "team-1"); err != nil {
		log.Fatal(err)
	}

	ok, err := authz.Can(ctx, alice, "posts.publish", "team-1")
	fmt.Println(ok, err) // true <nil>

	// A policy for one action on one resource type.
	permission.MustRegisterPolicy(authz, "update", func(ctx context.Context, actor permission.Subject, p *Post) (bool, error) {
		if actor.Type == "user" && actor.ID == p.AuthorID {
			return true, nil
		}
		return authz.Can(ctx, actor, "posts.update", p.TeamID)
	})

	bob := permission.Subject{Type: "user", ID: "bob"}
	err = authz.Authorize(ctx, bob, "update", &Post{AuthorID: "carol", TeamID: "team-1"})
	var denied *permission.ForbiddenError
	if errors.As(err, &denied) {
		fmt.Println(denied.Reason) // policy denied action "update" on *main.Post
	}
}

Concepts

Permissions are dotted strings of lowercase letters, digits, _ and -: posts.publish, billing.invoices.refund. A grant may end in *: posts.* covers every permission below posts (but not posts itself), and * covers everything. Checks always ask about a concrete permission.

Roles group permissions. Role names use lowercase letters, digits and _ . : - (admin, billing-manager, org:owner).

Subjects are whoever acts: Subject{Type: "user", ID: "42"}, Subject{Type: "api_key", ID: "k_live_..."}. The type namespaces the ID. The zero Subject is the anonymous actor: it holds nothing, and policies receive it so they can allow public reads.

Scopes are usually tenant or team IDs. Every role assignment and direct grant has one. A grant in the global scope "" applies in every scope; a grant in team-1 applies only to checks made in team-1. A check in the global scope sees only global grants.

Checks: Can, HasRole, HasAnyRole, HasAllRoles, RolesFor and PermissionsFor (the effective set: every permission and pattern the subject holds, through roles or directly, globally or in the scope).

Super-admins: Options.SuperAdminRole names a role whose holders pass every Can and Authorize check in the scopes where they hold it, and Options.SuperAdmin is a function for anything else (for example, internal staff accounts). HasRole and PermissionsFor report facts and ignore the bypass.

Policies attach a typed function to an action and a resource type:

permission.MustRegisterPolicy(authz, "delete", func(ctx context.Context, actor permission.Subject, c *Comment) (bool, error) {
	if c.Locked {
		return false, permission.Deny("comment thread is locked")
	}
	return actor.ID == c.AuthorID, nil
})

Authorize returns nil or a *ForbiddenError (matching ErrForbidden) with the actor, action, resource type and reason. A resource type or action with no policy is denied, even for super-admins, with an error that also matches ErrNoPolicy, so a forgotten registration shows up in tests rather than as a silent hole. Lookups use the exact dynamic type: a policy for *Post does not apply to Post. Allows is the boolean form; it fails closed and passes unexpected errors to Options.OnError. Policies read the current scope with permission.ScopeFrom(ctx); the super-admin check in Authorize uses it too.

Caching: effective sets are cached per subject and scope (default TTL one minute, 10,000 entries). Writes through the Authorizer invalidate the entries they can affect: subject writes drop that subject, role and permission writes drop everything. Another instance's writes reach the cache through Authorizer.Invalidate, which pgxstore.Listener calls. Reads made inside a caller's transaction bypass the cache, so uncommitted or rolled-back grants never leak into it.

HTTP middleware (httpperm):

mw, err := httpperm.New(authz, httpperm.Options{
	Extract: func(r *http.Request) (permission.Subject, string, bool) {
		user, ok := auth.UserFrom(r.Context()) // your authentication
		return permission.Subject{Type: "user", ID: user.ID}, r.PathValue("tenant"), ok
	},
})
mux.Handle("POST /t/{tenant}/invoices", mw.Require("invoices.create")(createInvoice))
mux.Handle("GET /t/{tenant}/admin", mw.RequireRole("admin")(adminPage))

No subject answers 401, a denial 403 and a failed check 500; each response is replaceable through Options. Requests that pass carry the subject and scope in their context (permission.SubjectFrom, permission.ScopeFrom).

PostgreSQL

store, err := pgxstore.New(pool, pgxstore.WithNotifyChannel("perm_invalidate"))
if err != nil { ... }
if err := store.CreateSchema(ctx); err != nil { ... }
authz, err := permission.New(store, permission.Options{})

listener, err := pgxstore.NewListener(pgxstore.ListenerConfig{
	Connect: func(ctx context.Context) (*pgx.Conn, error) { return pgx.Connect(ctx, databaseURL) },
	Channel: "perm_invalidate",
	Handler: authz.Invalidate,
	OnError: func(err error) { log.Printf("permission listener: %v", err) },
})
go listener.Run(ctx)

Every write is a single statement that also sends the invalidation notice, so the notice commits or rolls back with the write. The listener holds its own connection, reconnects with jittered exponential backoff after connection loss, and drops the whole cache each time it starts listening, because notices sent while it was disconnected are lost.

Tables are named with a prefix, default perm_; use pgxstore.WithTablePrefix("authz.perm_") for another prefix or schema. store.Schema() returns the DDL for migration tools. With the default prefix:

CREATE TABLE IF NOT EXISTS "perm_roles" (
    id          uuid PRIMARY KEY,
    name        text NOT NULL UNIQUE
                CHECK (octet_length(name) <= 64 AND name ~ '^[a-z0-9][a-z0-9_.:-]*$'),
    description text NOT NULL DEFAULT ''
                CHECK (octet_length(description) <= 1024),
    created_at  timestamptz NOT NULL
);

CREATE TABLE IF NOT EXISTS "perm_permissions" (
    id         uuid PRIMARY KEY,
    name       text NOT NULL UNIQUE
               CHECK (octet_length(name) <= 255 AND name ~ '^(\*|[a-z0-9][a-z0-9_-]*(\.[a-z0-9][a-z0-9_-]*)*(\.\*)?)$'),
    created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE IF NOT EXISTS "perm_role_permissions" (
    role_id       uuid NOT NULL REFERENCES "perm_roles" (id) ON DELETE CASCADE,
    permission_id uuid NOT NULL REFERENCES "perm_permissions" (id) ON DELETE CASCADE,
    created_at    timestamptz NOT NULL DEFAULT now(),
    PRIMARY KEY (role_id, permission_id)
);
CREATE INDEX IF NOT EXISTS "perm_role_permissions_permission_idx" ON "perm_role_permissions" (permission_id);

CREATE TABLE IF NOT EXISTS "perm_subject_roles" (
    subject_type text NOT NULL
                 CHECK (octet_length(subject_type) <= 64 AND subject_type ~ '^[a-z0-9][a-z0-9_.:-]*$'),
    subject_id   text NOT NULL
                 CHECK (octet_length(subject_id) BETWEEN 1 AND 255),
    scope        text NOT NULL DEFAULT ''
                 CHECK (octet_length(scope) <= 255),
    role_id      uuid NOT NULL REFERENCES "perm_roles" (id) ON DELETE CASCADE,
    created_at   timestamptz NOT NULL DEFAULT now(),
    PRIMARY KEY (subject_type, subject_id, scope, role_id)
);
CREATE INDEX IF NOT EXISTS "perm_subject_roles_role_idx" ON "perm_subject_roles" (role_id, scope);

CREATE TABLE IF NOT EXISTS "perm_subject_permissions" (
    subject_type  text NOT NULL
                  CHECK (octet_length(subject_type) <= 64 AND subject_type ~ '^[a-z0-9][a-z0-9_.:-]*$'),
    subject_id    text NOT NULL
                  CHECK (octet_length(subject_id) BETWEEN 1 AND 255),
    scope         text NOT NULL DEFAULT ''
                  CHECK (octet_length(scope) <= 255),
    permission_id uuid NOT NULL REFERENCES "perm_permissions" (id) ON DELETE CASCADE,
    created_at    timestamptz NOT NULL DEFAULT now(),
    PRIMARY KEY (subject_type, subject_id, scope, permission_id)
);
CREATE INDEX IF NOT EXISTS "perm_subject_permissions_permission_idx" ON "perm_subject_permissions" (permission_id);
Joining transactions

WithConn resolves the connection per call. Return the transaction your request carries and the permission write commits or rolls back with the rest of its work; return nil to use the pool.

store, err := pgxstore.New(pool, pgxstore.WithConn(func(ctx context.Context) pgxstore.Querier {
	if tx, ok := ctx.Value(txKey{}).(pgx.Tx); ok {
		return tx
	}
	return nil
}))

err = pgx.BeginFunc(ctx, pool, func(tx pgx.Tx) error {
	txCtx := context.WithValue(ctx, txKey{}, tx)
	if err := createTeam(txCtx, team); err != nil {
		return err
	}
	return authz.AssignRole(txCtx, owner, "owner", team.ID)
})

Checks made with a context that resolves to a transaction read through it (so they see the transaction's own writes) and bypass the cache. The local cache is invalidated when the write statement runs; other instances, and this one when it runs a Listener, are notified at commit.

API overview

Area API
Setup New(store, Options), Options{CacheTTL, CacheMaxEntries, SuperAdminRole, SuperAdmin, Now, OnError}
Checks Can, HasRole, HasAnyRole, HasAllRoles, RolesFor, PermissionsFor
Policies RegisterPolicy[T], MustRegisterPolicy[T], PolicyFunc[T], Authorize, Allows, Deny, ForbiddenError
Roles CreateRole, Role, ListRoles, DeleteRole, GrantToRole, RevokeFromRole, RolePermissions
Subjects AssignRole, UnassignRole, SubjectsWithRole, Grant, Revoke
Permissions ListPermissions, DeletePermission, ValidatePermission, Match
Cache Invalidate(Invalidation), CacheBypass
Context WithSubject, SubjectFrom, WithScope, ScopeFrom
Validation ValidateSubject, ValidateRole, ValidateScope, Role.Validate
Errors ErrInvalidSubject, ErrInvalidPermission, ErrInvalidRole, ErrInvalidScope, ErrInvalidPolicy, ErrRoleNotFound, ErrRoleExists, ErrPermissionNotFound, ErrForbidden, ErrNoPolicy
pgxstore New, WithConn, WithTablePrefix, WithNotifyChannel, Store.Schema, Store.CreateSchema, NewListener, ListenerConfig, Listener.Run
memstore New
storetest Run(t, newStore)
httpperm New, Options{Extract, Unauthorized, Forbidden, Error}, Middleware.Require, Middleware.RequireRole

Writes are idempotent where repeating them is harmless: granting a held permission, revoking an absent one, repeating an assignment or removing an absent one all succeed. Operations on a missing role return ErrRoleNotFound (so typos surface), creating a taken role name returns ErrRoleExists, and deleting an unknown permission returns ErrPermissionNotFound.

Testing

go test -race ./...
TEST_DATABASE_URL='postgres://postgres:postgres@localhost:5432/permission?sslmode=disable' \
  go test -race -count=1 ./...

Integration tests create and drop their own schemas and run in parallel. To check your own store:

func TestMyStore(t *testing.T) {
	storetest.Run(t, func(t *testing.T) permission.Store { return newMyStore(t) })
}

Roadmap

  • Pagination for ListRoles, SubjectsWithRole and ListPermissions.
  • Listing a subject's raw assignments and direct grants per scope (today RolesFor and PermissionsFor return the effective, merged view).
  • Role hierarchies (roles that include other roles).
  • Explicit deny rules.
  • Audit hooks for management writes.
  • A Redis-backed invalidation transport for deployments without PostgreSQL.

License

MIT. See LICENSE.

Documentation

Overview

Package permission is role-based access control for SaaS applications, with resource-level policies.

Model

Permissions are dotted strings such as "posts.publish". A grant may end in a wildcard: "posts.*" covers everything below "posts", and "*" covers everything. Roles group permissions. Subjects (users, API keys, service accounts) are identified by a type and an ID, and receive roles and direct permissions.

Every grant and assignment has a scope, typically a tenant or team ID. A grant in GlobalScope ("") applies in every scope; a grant in "team-1" applies only to checks made in "team-1".

Checks

An Authorizer answers Can, HasRole, HasAnyRole, HasAllRoles, RolesFor and PermissionsFor. A super-admin, configured as a role name or a function in Options, passes every Can and Authorize check.

Effective sets are cached per subject and scope with a TTL. Writes made through the Authorizer invalidate what they affect; writes made by other instances arrive through Authorizer.Invalidate, which the pgxstore Listener calls from PostgreSQL notifications.

Policies

RegisterPolicy attaches a typed function to an action and a resource type, such as "update" on *Post. Authorize returns nil or a *ForbiddenError that matches ErrForbidden and explains the denial; a resource type without a policy is denied and also matches ErrNoPolicy. Allows is the boolean form.

Storage

The Store interface is implemented by the memstore (tests, examples) and pgxstore (PostgreSQL) subpackages; storetest verifies third-party stores. The httpperm subpackage provides net/http middleware.

Example
package main

import (
	"context"
	"fmt"

	"github.com/byteminus/go-permission"
	"github.com/byteminus/go-permission/memstore"
)

func main() {
	ctx := context.Background()
	authz, err := permission.New(memstore.New(), permission.Options{SuperAdminRole: "superadmin"})
	if err != nil {
		panic(err)
	}

	// Define a role once, then assign it per team.
	if _, err := authz.CreateRole(ctx, "editor", "Writes and publishes posts"); err != nil {
		panic(err)
	}
	if err := authz.GrantToRole(ctx, "editor", "posts.*", "comments.moderate"); err != nil {
		panic(err)
	}
	alice := permission.Subject{Type: "user", ID: "alice"}
	if err := authz.AssignRole(ctx, alice, "editor", "team-1"); err != nil {
		panic(err)
	}

	inTeam, _ := authz.Can(ctx, alice, "posts.publish", "team-1")
	elsewhere, _ := authz.Can(ctx, alice, "posts.publish", "team-2")
	fmt.Println(inTeam, elsewhere)
}
Output:
true false

Index

Examples

Constants

View Source
const (
	DefaultCacheTTL        = time.Minute
	DefaultCacheMaxEntries = 10000
)

Default cache settings used when Options leaves them zero.

View Source
const (
	// MaxNameLength is the longest role name, subject type or policy action,
	// in bytes.
	MaxNameLength = 64
	// MaxPermissionLength is the longest permission string, in bytes.
	MaxPermissionLength = 255
	// MaxSubjectIDLength is the longest subject ID, in bytes.
	MaxSubjectIDLength = 255
	// MaxScopeLength is the longest scope, in bytes.
	MaxScopeLength = 255
	// MaxDescriptionLength is the longest role description, in bytes.
	MaxDescriptionLength = 1024
)

Limits enforced by the validators. The PostgreSQL store mirrors them in CHECK constraints, so changing one is a schema change.

View Source
const GlobalScope = ""

GlobalScope is the scope of grants that apply in every scope. Checks made with GlobalScope see only global grants.

Variables

View Source
var (
	// ErrInvalidSubject reports a Subject whose type or ID is malformed.
	ErrInvalidSubject = errors.New("permission: invalid subject")
	// ErrInvalidPermission reports a malformed permission string.
	ErrInvalidPermission = errors.New("permission: invalid permission")
	// ErrInvalidRole reports a malformed role name or role record.
	ErrInvalidRole = errors.New("permission: invalid role")
	// ErrInvalidScope reports a malformed scope.
	ErrInvalidScope = errors.New("permission: invalid scope")
	// ErrInvalidPolicy reports a policy registration that cannot be accepted:
	// a malformed action, a nil function, an interface resource type or a
	// duplicate registration.
	ErrInvalidPolicy = errors.New("permission: invalid policy")
	// ErrRoleNotFound reports that a named role does not exist.
	ErrRoleNotFound = errors.New("permission: role not found")
	// ErrRoleExists reports an attempt to create a role whose name is taken.
	ErrRoleExists = errors.New("permission: role already exists")
	// ErrPermissionNotFound reports that a permission is not registered.
	ErrPermissionNotFound = errors.New("permission: permission not found")
	// ErrForbidden is matched by every authorization denial returned by
	// Authorizer.Authorize. The concrete error is a *ForbiddenError.
	ErrForbidden = errors.New("permission: forbidden")
	// ErrNoPolicy is matched, in addition to ErrForbidden, when Authorize
	// denies because no policy is registered for the action and resource type.
	ErrNoPolicy = errors.New("permission: no policy registered")
)

Sentinel errors returned by the package. Errors carrying details wrap one of these, so callers test them with errors.Is.

Functions

func Deny

func Deny(reason string) error

Deny returns an error that a policy function returns to deny access with a specific reason. Authorize turns it into a *ForbiddenError carrying that reason, the actor, the action and the resource type.

Example
package main

import (
	"context"
	"fmt"

	"github.com/byteminus/go-permission"
	"github.com/byteminus/go-permission/memstore"
)

type Document struct {
	OwnerID string
	Team    string
}

func main() {
	ctx := context.Background()
	authz, _ := permission.New(memstore.New(), permission.Options{})
	permission.MustRegisterPolicy(authz, "edit", func(ctx context.Context, actor permission.Subject, d *Document) (bool, error) {
		return false, permission.Deny("document is archived")
	})
	err := authz.Authorize(ctx, permission.Subject{Type: "user", ID: "alice"}, "edit", &Document{})
	fmt.Println(err)
}
Output:
permission: forbidden: document is archived

func Match

func Match(granted, p string) bool

Match reports whether a granted permission or pattern covers the concrete permission p. Match does not validate its arguments.

Example
package main

import (
	"fmt"

	"github.com/byteminus/go-permission"
)

func main() {
	fmt.Println(permission.Match("posts.*", "posts.comments.delete"))
	fmt.Println(permission.Match("posts.*", "posts"))
}
Output:
true
false

func MustRegisterPolicy

func MustRegisterPolicy[T any](a *Authorizer, action string, fn PolicyFunc[T])

MustRegisterPolicy is RegisterPolicy for program setup; it panics on a registration error, which is always a programming mistake.

func RegisterPolicy

func RegisterPolicy[T any](a *Authorizer, action string, fn PolicyFunc[T]) error

RegisterPolicy registers fn as the policy for action on resources of type T, such as "update" on *Post. Lookups use the exact dynamic type of the resource, so T must be a concrete type: a policy for *Post does not apply to Post. Registering the same action and type twice is an error. RegisterPolicy is safe to call concurrently with checks.

Example
package main

import (
	"context"
	"errors"
	"fmt"

	"github.com/byteminus/go-permission"
	"github.com/byteminus/go-permission/memstore"
)

type Document struct {
	OwnerID string
	Team    string
}

func main() {
	ctx := context.Background()
	authz, _ := permission.New(memstore.New(), permission.Options{})

	// Owners may edit their documents; others need the RBAC permission in
	// the document's team.
	permission.MustRegisterPolicy(authz, "edit", func(ctx context.Context, actor permission.Subject, d *Document) (bool, error) {
		if actor.Type == "user" && actor.ID == d.OwnerID {
			return true, nil
		}
		return authz.Can(ctx, actor, "documents.edit", d.Team)
	})

	doc := &Document{OwnerID: "alice", Team: "team-1"}
	alice := permission.Subject{Type: "user", ID: "alice"}
	bob := permission.Subject{Type: "user", ID: "bob"}

	fmt.Println(authz.Authorize(ctx, alice, "edit", doc))

	err := authz.Authorize(ctx, bob, "edit", doc)
	var denied *permission.ForbiddenError
	if errors.As(err, &denied) {
		fmt.Println(denied.Reason)
	}

	err = authz.Authorize(ctx, alice, "delete", doc)
	fmt.Println(errors.Is(err, permission.ErrForbidden), errors.Is(err, permission.ErrNoPolicy))
}
Output:
<nil>
policy denied action "edit" on *permission_test.Document
true true

func ScopeFrom

func ScopeFrom(ctx context.Context) string

ScopeFrom returns the scope set by WithScope, or GlobalScope.

func ValidatePermission

func ValidatePermission(p string) error

ValidatePermission reports whether p is a valid permission or wildcard pattern. A permission is dot-separated segments of lowercase letters, digits, '_' and '-', each starting with a letter or digit, such as "posts.publish". The last segment may be "*", which grants everything below the prefix ("posts.*" grants "posts.publish" and "posts.comments.delete" but not "posts"); "*" alone grants everything.

func ValidateRole

func ValidateRole(name string) error

ValidateRole reports whether name is a valid role name: 1 to MaxNameLength bytes, starting with a lowercase letter or digit, followed by lowercase letters, digits, '_', '.', ':' or '-'.

func ValidateScope

func ValidateScope(scope string) error

ValidateScope reports whether scope is valid: up to MaxScopeLength bytes of UTF-8 without NUL. The empty scope is GlobalScope.

func ValidateSubject

func ValidateSubject(s Subject) error

ValidateSubject reports whether s is a storable subject. Type follows the role name rules; ID is 1 to MaxSubjectIDLength bytes of UTF-8 without NUL.

func WithScope

func WithScope(ctx context.Context, scope string) context.Context

WithScope returns a context carrying the current scope, typically the tenant or team of the request. Authorize uses it for the super-admin check, and policies can use it for their own RBAC checks.

func WithSubject

func WithSubject(ctx context.Context, s Subject) context.Context

WithSubject returns a context carrying the acting subject. The httpperm middleware sets it for every request it lets through.

Types

type Authorizer

type Authorizer struct {
	// contains filtered or unexported fields
}

Authorizer answers permission, role and policy checks, and is the write path for roles and grants so that its cache stays consistent. It is safe for concurrent use.

func New

func New(store Store, opts Options) (*Authorizer, error)

New returns an Authorizer over store.

func (*Authorizer) Allows

func (a *Authorizer) Allows(ctx context.Context, actor Subject, action string, resource any) bool

Allows is Authorize reduced to a bool for templates and conditionals. It fails closed: any error denies. Errors other than a plain policy denial, including a missing policy, are passed to Options.OnError.

func (*Authorizer) AssignRole

func (a *Authorizer) AssignRole(ctx context.Context, subject Subject, role, scope string) error

AssignRole assigns role to subject in scope; GlobalScope makes it apply in every scope. Repeating an assignment is a no-op. It returns ErrRoleNotFound when the role is absent.

func (*Authorizer) Authorize

func (a *Authorizer) Authorize(ctx context.Context, actor Subject, action string, resource any) error

Authorize checks whether actor may perform action on resource and returns nil when allowed. A denial is a *ForbiddenError matching ErrForbidden and carrying a reason. Resources without a registered policy are denied with an error that also matches ErrNoPolicy, even for super-admins, so missing registrations surface early. Super-admins (see Options) otherwise pass without consulting the policy; the scope for that check comes from ScopeFrom(ctx). Errors from the policy or the store are returned wrapped and do not match ErrForbidden. The zero Subject may be passed as an anonymous actor.

func (*Authorizer) Can

func (a *Authorizer) Can(ctx context.Context, subject Subject, permission, scope string) (bool, error)

Can reports whether subject holds permission in scope, through a role or a direct grant made globally or in scope, or as a super-admin. The permission must be concrete (no wildcard). The anonymous zero Subject holds nothing.

func (*Authorizer) CreateRole

func (a *Authorizer) CreateRole(ctx context.Context, name, description string) (Role, error)

CreateRole creates a role. It returns ErrRoleExists when the name is taken: a role's identity matters to everyone holding it, so silently reusing an existing role is not treated as success.

func (*Authorizer) DeletePermission

func (a *Authorizer) DeletePermission(ctx context.Context, permission string) error

DeletePermission retires a permission: it is removed from every role and subject and unregistered. It returns ErrPermissionNotFound when absent.

func (*Authorizer) DeleteRole

func (a *Authorizer) DeleteRole(ctx context.Context, name string) error

DeleteRole deletes a role, its permission grants and all its assignments. It returns ErrRoleNotFound when absent.

func (*Authorizer) Grant

func (a *Authorizer) Grant(ctx context.Context, subject Subject, permission, scope string) error

Grant gives subject a permission (or wildcard pattern) directly in scope. Repeating a grant is a no-op.

func (*Authorizer) GrantToRole

func (a *Authorizer) GrantToRole(ctx context.Context, role string, permissions ...string) error

GrantToRole grants permissions (or wildcard patterns) to a role, all or none. Granting a held permission is a no-op. It returns ErrRoleNotFound when the role is absent.

func (*Authorizer) HasAllRoles

func (a *Authorizer) HasAllRoles(ctx context.Context, subject Subject, roles []string, scope string) (bool, error)

HasAllRoles reports whether subject holds every one of roles globally or in scope. roles must not be empty.

func (*Authorizer) HasAnyRole

func (a *Authorizer) HasAnyRole(ctx context.Context, subject Subject, roles []string, scope string) (bool, error)

HasAnyRole reports whether subject holds at least one of roles globally or in scope. roles must not be empty.

func (*Authorizer) HasRole

func (a *Authorizer) HasRole(ctx context.Context, subject Subject, role, scope string) (bool, error)

HasRole reports whether subject is assigned role globally or in scope. The super-admin bypass does not apply: this answers a factual question.

func (*Authorizer) Invalidate

func (a *Authorizer) Invalidate(inv Invalidation)

Invalidate drops cached effective sets. Wire it to a cross-instance notification source such as pgxstore.Listener; local writes made through this Authorizer invalidate on their own.

func (*Authorizer) ListPermissions

func (a *Authorizer) ListPermissions(ctx context.Context) ([]string, error)

ListPermissions returns every registered permission, ordered. A permission is registered the first time it is granted.

func (*Authorizer) ListRoles

func (a *Authorizer) ListRoles(ctx context.Context) ([]Role, error)

ListRoles returns all roles ordered by name.

func (*Authorizer) PermissionsFor

func (a *Authorizer) PermissionsFor(ctx context.Context, subject Subject, scope string) ([]string, error)

PermissionsFor returns the effective permission set of subject in scope: every permission or wildcard pattern granted through its roles or directly, globally or in scope, ordered and without duplicates. The super-admin bypass is not reflected here.

Example
package main

import (
	"context"
	"fmt"

	"github.com/byteminus/go-permission"
	"github.com/byteminus/go-permission/memstore"
)

func main() {
	ctx := context.Background()
	authz, _ := permission.New(memstore.New(), permission.Options{})
	bot := permission.Subject{Type: "api_key", ID: "ci"}

	// Global grants apply in every scope; scoped grants only in theirs.
	_ = authz.Grant(ctx, bot, "builds.trigger", permission.GlobalScope)
	_ = authz.Grant(ctx, bot, "deploys.*", "staging")

	staging, _ := authz.PermissionsFor(ctx, bot, "staging")
	production, _ := authz.PermissionsFor(ctx, bot, "production")
	fmt.Println(staging)
	fmt.Println(production)
}
Output:
[builds.trigger deploys.*]
[builds.trigger]

func (*Authorizer) Revoke

func (a *Authorizer) Revoke(ctx context.Context, subject Subject, permission, scope string) error

Revoke removes a direct grant made in exactly scope. Removing an absent grant is a no-op. Permissions held through roles are unaffected.

func (*Authorizer) RevokeFromRole

func (a *Authorizer) RevokeFromRole(ctx context.Context, role string, permissions ...string) error

RevokeFromRole revokes permissions from a role, all or none. Revoking a permission the role does not hold is a no-op. It returns ErrRoleNotFound when the role is absent.

func (*Authorizer) Role

func (a *Authorizer) Role(ctx context.Context, name string) (Role, error)

Role returns the named role, or ErrRoleNotFound.

func (*Authorizer) RolePermissions

func (a *Authorizer) RolePermissions(ctx context.Context, role string) ([]string, error)

RolePermissions returns the permissions granted to a role, ordered. It returns ErrRoleNotFound when the role is absent.

func (*Authorizer) RolesFor

func (a *Authorizer) RolesFor(ctx context.Context, subject Subject, scope string) ([]string, error)

RolesFor returns the roles subject holds in scope, including global assignments, ordered by name.

func (*Authorizer) SubjectsWithRole

func (a *Authorizer) SubjectsWithRole(ctx context.Context, role, scope string) ([]Subject, error)

SubjectsWithRole returns the subjects assigned role in exactly scope, so listing a team's admins does not include global admins. It returns ErrRoleNotFound when the role is absent.

func (*Authorizer) UnassignRole

func (a *Authorizer) UnassignRole(ctx context.Context, subject Subject, role, scope string) error

UnassignRole removes the assignment of role to subject in exactly scope. Removing an absent assignment is a no-op. It returns ErrRoleNotFound when the role is absent, which catches misspelled role names.

type CacheBypass

type CacheBypass interface {
	BypassCache(ctx context.Context) bool
}

CacheBypass is implemented by stores that can tell when a read must not be cached. The PostgreSQL store reports true while the caller carries its own connection or transaction, because such reads can see uncommitted writes that a rollback would undo.

type ForbiddenError

type ForbiddenError struct {
	// Actor is the subject that was denied.
	Actor Subject
	// Action is the policy action that was checked.
	Action string
	// Resource is the Go type of the resource, such as "*app.Post".
	Resource string
	// Reason is a human-readable explanation suitable for logs. It is not
	// meant to be shown to end users verbatim.
	Reason string
	// Err is an optional cause, such as ErrNoPolicy.
	Err error
}

ForbiddenError describes why an authorization was denied. It matches ErrForbidden with errors.Is, and also matches Err when Err is set.

func (*ForbiddenError) Error

func (e *ForbiddenError) Error() string

Error returns the denial with its reason.

func (*ForbiddenError) Is

func (e *ForbiddenError) Is(target error) bool

Is reports whether target is ErrForbidden.

func (*ForbiddenError) Unwrap

func (e *ForbiddenError) Unwrap() error

Unwrap returns the optional cause.

type Grants

type Grants struct {
	Roles       []string
	Permissions []string
}

Grants is the effective set of a subject in a scope.

type Invalidation

type Invalidation struct {
	// All invalidates every cached entry. Role-level writes affect every
	// holder of the role and use it.
	All bool
	// Subject invalidates every scope cached for one subject when All is
	// false.
	Subject Subject
}

Invalidation identifies cached effective sets that are out of date. It is what cross-instance notifications carry; pass received values to Authorizer.Invalidate.

type Options

type Options struct {
	// CacheTTL bounds how long an effective set is reused. Zero means
	// DefaultCacheTTL; a negative value disables caching. Local writes
	// invalidate immediately; the TTL bounds staleness from writes made by
	// other processes when no cross-instance listener is running.
	CacheTTL time.Duration
	// CacheMaxEntries caps the number of cached (subject, scope) pairs.
	// Zero means DefaultCacheMaxEntries.
	CacheMaxEntries int
	// SuperAdminRole, when set, names a role whose holders pass every Can
	// and Authorize check, in any scope where they hold it.
	SuperAdminRole string
	// SuperAdmin, when set, is consulted before any other check; returning
	// true grants access. It may be combined with SuperAdminRole.
	SuperAdmin func(ctx context.Context, subject Subject, scope string) (bool, error)
	// Now is the clock for cache expiry and role creation times. Nil means
	// time.Now.
	Now func() time.Time
	// OnError receives errors that Allows turns into a denial, including
	// missing policies, so they are not lost. Nil discards them.
	OnError func(ctx context.Context, err error)
}

Options configures an Authorizer. The zero value is valid: caching with the defaults, no super-admin, the system clock.

type PolicyFunc

type PolicyFunc[T any] func(ctx context.Context, actor Subject, resource T) (bool, error)

PolicyFunc decides whether actor may perform an action on resource. It returns true to allow and false to deny; returning the error from Deny denies with a specific reason, and any other error aborts the check. A policy may call the Authorizer's RBAC checks, using ScopeFrom(ctx) for the current scope.

type Role

type Role struct {
	ID          uuid.UUID
	Name        string
	Description string
	// CreatedAt is in UTC with microsecond precision.
	CreatedAt time.Time
}

Role groups permissions under a name.

func (Role) Validate

func (r Role) Validate() error

Validate reports whether r can be stored: a non-nil ID, a valid name, a description within MaxDescriptionLength and a non-zero creation time.

type Store

type Store interface {
	// CreateRole stores a new role. It returns ErrRoleExists when the name
	// is taken.
	CreateRole(ctx context.Context, role Role) error
	// DeleteRole removes a role together with its permission grants and
	// every assignment of it. It returns ErrRoleNotFound when absent.
	DeleteRole(ctx context.Context, name string) error
	// Role returns the named role, or ErrRoleNotFound.
	Role(ctx context.Context, name string) (Role, error)
	// ListRoles returns all roles ordered by name (byte order).
	ListRoles(ctx context.Context) ([]Role, error)

	// GrantToRole atomically grants permissions to a role, registering any
	// permission not seen before. Granting a held permission is a no-op.
	// It returns ErrRoleNotFound when the role is absent.
	GrantToRole(ctx context.Context, role string, permissions []string) error
	// RevokeFromRole atomically revokes permissions from a role. Revoking a
	// permission the role does not hold is a no-op. It returns
	// ErrRoleNotFound when the role is absent.
	RevokeFromRole(ctx context.Context, role string, permissions []string) error
	// RolePermissions returns the permissions granted to a role, ordered
	// (byte order). It returns ErrRoleNotFound when the role is absent.
	RolePermissions(ctx context.Context, role string) ([]string, error)

	// AssignRole assigns a role to a subject in a scope. Assigning an
	// existing assignment is a no-op. It returns ErrRoleNotFound when the
	// role is absent.
	AssignRole(ctx context.Context, subject Subject, role, scope string) error
	// UnassignRole removes an assignment. Removing an absent assignment is a
	// no-op. It returns ErrRoleNotFound when the role is absent.
	UnassignRole(ctx context.Context, subject Subject, role, scope string) error
	// SubjectsWithRole returns the subjects assigned the role in exactly
	// scope, ordered by Type then ID (byte order). It returns
	// ErrRoleNotFound when the role is absent.
	SubjectsWithRole(ctx context.Context, role, scope string) ([]Subject, error)

	// Grant gives a subject a permission directly in a scope, registering
	// the permission if needed. Granting a held permission is a no-op.
	Grant(ctx context.Context, subject Subject, permission, scope string) error
	// Revoke removes a direct grant. Removing an absent grant is a no-op.
	Revoke(ctx context.Context, subject Subject, permission, scope string) error

	// ListPermissions returns every registered permission, ordered (byte
	// order). A permission is registered the first time it is granted.
	ListPermissions(ctx context.Context) ([]string, error)
	// DeletePermission unregisters a permission and removes it from every
	// role and subject. It returns ErrPermissionNotFound when absent.
	DeletePermission(ctx context.Context, permission string) error

	// Effective returns what a subject holds in scope: the roles assigned
	// globally or in scope, and the permissions granted by those roles or
	// directly, globally or in scope. Both lists are ordered (byte order)
	// and free of duplicates, and are read from one consistent snapshot.
	Effective(ctx context.Context, subject Subject, scope string) (Grants, error)
}

Store persists roles, role permissions, role assignments and direct permission grants. Implementations validate their inputs with the Validate* functions and return the package's sentinel errors, so every store behaves the same; the storetest package verifies this.

Applications do not call a Store directly: writes go through an Authorizer, which keeps its cache consistent.

Implementations must be safe for concurrent use.

type Subject

type Subject struct {
	Type string
	ID   string
}

Subject is anything that can hold roles and permissions: a user, an API key, a service account. Type namespaces the ID, so "user"/"42" and "api_key"/"42" are different subjects. The zero Subject stands for an anonymous actor: it holds nothing and cannot be granted anything.

func SubjectFrom

func SubjectFrom(ctx context.Context) (Subject, bool)

SubjectFrom returns the subject set by WithSubject, and whether one was set.

func (Subject) IsZero

func (s Subject) IsZero() bool

IsZero reports whether s is the anonymous subject.

func (Subject) String

func (s Subject) String() string

String returns "type:id", for logs.

Directories

Path Synopsis
Package httpperm provides net/http middleware that requires a permission or a role before calling the next handler.
Package httpperm provides net/http middleware that requires a permission or a role before calling the next handler.
Package memstore is an in-memory permission.Store for tests, examples and single-process tools.
Package memstore is an in-memory permission.Store for tests, examples and single-process tools.
Package pgxstore is a PostgreSQL permission.Store built on pgx v5, with LISTEN/NOTIFY-based cache invalidation across application instances.
Package pgxstore is a PostgreSQL permission.Store built on pgx v5, with LISTEN/NOTIFY-based cache invalidation across application instances.
Package storetest is a conformance suite for permission.Store implementations.
Package storetest is a conformance suite for permission.Store implementations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL