Go API
The packages of github.com/zynactra/access/go and what each exports.
Module github.com/zynactra/access/go. Full doc comments: go doc github.com/zynactra/access/go/<package> (or go doc -all). The Go guide shows them in use.
access
The core: decisions, the manifest, errors.
New(Config) (*Access, error) | Build from the manifest, a Cerbos client, a store and a resolver. Options. |
HasPermission(ctx, s, key) (bool, error) | Holds key at some scope? From cached grants; no Cerbos call. The route guard. |
Check(ctx, s, key, r) (bool, error) | One decision. Outages are (false, err). |
Assert(ctx, s, key, r) error | nil when allowed, else an *Error. Outages become a denial with reason unavailable. |
CheckMany(ctx, s, items) ([]CheckItemResult, error) | Several permissions on several records, one Cerbos call. |
Plan(ctx, s, key) (*Plan, error) | The list filter's input: ALWAYS_ALLOWED, ALWAYS_DENIED or a condition. |
Explain(ctx, s, key, r) (*Explanation, error) | Why, with every grant of key. |
Summary(ctx, s) (*Summary, error) | The subject's grants, as GET /access/me returns them. |
Invalidate(orgID, userID), InvalidateAll() | Drop cached grants (the NOTIFY listener calls these). |
ValidateResource(key, r) error | What every check does first: kind, attributes, types, enums. |
Types: Subject{UserID, OrgID, IdP, Groups}, Resource{Kind, ID, Attr}, CheckItem{Resource, Permissions}, CheckItemResult{Allowed map[string]bool, ...}, Explanation, Summary, Plan, Error{Code, Reason, Permission, Field, Message, CallID}, Manifest, Resolver, Store, NoopResolver.
The Cerbos client: NewCerbosHTTP(baseURL) returns *CerbosHTTP (Check, Plan, Healthy); Cerbos is the interface, for other transports.
Helpers: ErrorCode(err), IsDenied(err), SplitKey(key); constants CodeDenied, CodeEscalation, CodeInvalid, CodeNotFound, CodeConflict, CodeUnavailable, the Reason* deny reasons, ScopeGlobal, ScopeSelf, ModeInherit, AdminRole.
accesshttp
HTTP glue for net/http.
Authenticate(SubjectFunc) | Middleware: put the subject from your token verification in the context; 401 on error. |
WithSubject(ctx, s), SubjectFrom(ctx) | For your own middleware, and in handlers. |
Guard{Access, Strict, Logger} | Require(perm, h): the route guard plus strict requirement tracking. RequireCapability(perm, h): the guard only, for routes with no record. |
Handler(Config) http.Handler | The access API. Config{Service, Loaders, MaxChecks, Logger}. |
Loader | func(ctx, s, ids) (map[string]access.Resource, error): loads records for /check and /explain. |
WriteError(w, err), WriteProblem(...), Status(code) | RFC 9457 problems. |
sqlfilter
Translate(plan, Columns, Options) (*Result, error) | A plan as SQL: Result{SQL, Args}. Refuses operators it doesn't know and unmapped attributes. |
Columns | map[string]string, attribute to trusted SQL expression. |
Options{StartAt, Placeholder} | First $n (default 1); $n or ?. |
EscapeLike(s) | The escaping prefix matches use. |
admin
New(access, store) *Service, the admin API in Go. Every method takes the acting access.Subject first and applies the admin rules: ListRoles, GetRole, CreateRole, UpdateRole, SetRolePermissions, DeleteRole, Permissions, ListAssignments, CreateAssignment, PreviewAssignment, RevokeAssignment, ListGroupMappings, CreateGroupMapping, DeleteGroupMapping, ListChanges, Explain.
Bootstrap(ctx, access, store, orgID, userID) gives an org its first access_admin. Constants: the access.* permission keys (PermRoleRead, ...), change kinds (ChangeRoleCreated, ...), SeverityNormal, SeverityHigh, MaxBreakGlass.
sqlstore
New(db *sql.DB) *Store: the Postgres store for database/sql with lib/pq, implementing access.Store and admin.Store. SyncCatalog(ctx, manifest) records the catalog and system roles; EnsureOrg(ctx, manifest, orgID) seeds system roles into an org; GetRoleByKey(ctx, orgID, key) finds a role.
migrate
Apply(ctx, db) ([]int, error): apply the access schema migrations; returns the versions applied.
pqlisten
Listen(ctx, dsn, invalidator, logger) error: LISTEN on access_changed and invalidate caches; reconnects with backoff and clears everything after a reconnect. Pass the *access.Access.
accesstest
StartCerbos(t, policiesDir) *Cerbos | A PDP serving the policies with schema enforcement on: HTTPAddr, Client, AuditLog. Skips without a cerbos binary unless ACCESS_REQUIRE_LIVE=1. |
NewDB(t) (*sql.DB, string) | A fresh migrated database on ACCESS_TEST_DATABASE_URL, dropped after the test. |
StaticResolver{Attrs, Sets} | A resolver from maps. |
MemStore{Rows, GroupRows} | An in-memory store. |
CerbosBin(), RepoRoot(t) | Helpers. |
cmd/zaccess
The CLI.