wardn

type AssignOption func(*assignWindow)

type Assignment struct {
	User  string `json:"user"`
	Role  string `json:"role"` // a system role name, or a custom role ID ("cr-...")
	Scope Scope  `json:"scope"`

	// StartsAt and ExpiresAt bound when the assignment applies. The zero
	// time means "no bound". The window is half-open: it applies from
	// StartsAt (inclusive) until ExpiresAt (exclusive).
	StartsAt  time.Time `json:"starts_at,omitzero"`
	ExpiresAt time.Time `json:"expires_at,omitzero"`
}

type AssignmentStore interface {
	// Assign saves an assignment. There is at most one assignment per
	// (user, role, scope): assigning again replaces the time window and
	// clears any expiry report.
	Assign(ctx context.Context, a Assignment) error

	// Revoke deletes the assignment of role to user at scope, if any.
	// Revoking an assignment that does not exist is not an error.
	Revoke(ctx context.Context, user, role string, scope Scope) error

	// Assignments returns the user's assignments at any of the given
	// scopes, regardless of time window. It must never return assignments
	// for other users or other scopes.
	Assignments(ctx context.Context, user string, scopes []Scope) ([]Assignment, error)

	// Members returns up to limit assignments at exactly scope, ordered by
	// user then role, starting after cursor ("" for the first page). It
	// returns the cursor for the next page, or "" after the last page.
	// Cursors are opaque to callers.
	Members(ctx context.Context, scope Scope, cursor string, limit int) ([]Assignment, string, error)

	// RoleInUse reports whether any assignment refers to role.
	RoleInUse(ctx context.Context, role string) (bool, error)

	// RevokeRole deletes every assignment of role.
	RevokeRole(ctx context.Context, role string) error

	// ExpiredUnreported returns up to limit assignments whose ExpiresAt is
	// at or before t and that have not been marked as reported.
	ExpiredUnreported(ctx context.Context, t time.Time, limit int) ([]Assignment, error)

	// MarkExpiryReported records that the given assignments' expiry was
	// reported. An assignment whose time window has changed since it was
	// read (it was assigned again) must not be marked.
	MarkExpiryReported(ctx context.Context, as []Assignment) error

	// RevokeExpired deletes the assignment only if its ExpiresAt still
	// equals a.ExpiresAt. If it was assigned again with a new window, it
	// stays. The check and the deletion must be atomic.
	RevokeExpired(ctx context.Context, a Assignment) error
}

type Cache interface {
	// Get returns the value stored under key, and false if there is none
	// or it has expired.
	Get(ctx context.Context, key string) ([]byte, bool, error)
	// Set stores value under key for ttl.
	Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
	// Counters returns the current values of counters; a counter that has
	// never been incremented is 0. Counters never expire.
	Counters(ctx context.Context, keys []string) ([]uint64, error)
	// Incr atomically increments each counter by one.
	Incr(ctx context.Context, keys []string) error
}

type Clock interface {
	Now() time.Time
}

type Config struct {
	// File is the path of a YAML policy file. Default: "wardn.yaml".
	File string

	// Policy is a policy defined in Go, used instead of File.
	Policy *Policy

	// Store persists assignments and scope links. Default: a new
	// MemoryStore, which is lost on exit. Use a database store in
	// production.
	Store Store

	// ParentOf, if set, resolves a scope's parent from the application's own
	// data instead of links stored with Link. It must return the true parent
	// from authoritative data; returning ok=false means "no parent".
	ParentOf func(ctx context.Context, child Scope) (parent Scope, ok bool, err error)

	// Cache, if set, caches store reads across requests (see Cache). Off
	// by default: without it every request reads the store, so a change is
	// visible on the very next request. Use a shared cache when running
	// more than one instance.
	Cache Cache

	// CacheSecret seals cache entries so they cannot be forged by whoever
	// can write to a shared cache. Required with a shared Cache: at least 32
	// random bytes from your secret store, the same on every instance.
	// Optional with NewMemoryCache.
	CacheSecret []byte

	// CacheTTL is how long cache entries live (default 5s, at most 5m). It
	// only matters for changes made behind wardn's back; wardn's own
	// changes invalidate the cache immediately.
	CacheTTL time.Duration

	// ManualMigrations stops New from migrating the Store's database
	// schema. Set it if your deploy pipeline runs migrations itself.
	ManualMigrations bool

	// Clock supplies the current time for time-limited assignments.
	// Default: the system clock. Tests can inject a fake clock.
	Clock Clock

	// UserFrom, if set, returns the authenticated user's ID for a request.
	// By default wardn's HTTP middleware reads it from the request context,
	// where the application's authentication middleware put it with
	// WithUser.
	UserFrom func(r *http.Request) (userID string, ok bool)

	// OnError, if set, writes the response when wardn's HTTP middleware
	// rejects a request. Use HTTPStatus(err) for the status code. By default
	// wardn writes a generic JSON error that does not reveal which
	// permission was missing.
	OnError func(w http.ResponseWriter, r *http.Request, err error)

	// OnChange, if set, is called before every change to assignments,
	// custom roles and scope links, with the acting user, for the audit
	// trail. If it returns an error, the change is not made (fail closed).
	// If the change then fails, it is called again with Event.Err set.
	OnChange func(ctx context.Context, e Event) error

	// OnDecision, if set, is called with every authorization decision and
	// any error, for audit logging and debugging. It must be fast and must
	// not panic.
	OnDecision func(ctx context.Context, d Decision, err error)
}

type CustomRole struct {
	ID          string `json:"id"`          // generated; starts with "cr-", so it never clashes with a system role name
	Owner       Scope  `json:"owner"`       // where the role was created
	Name        string `json:"name"`        // display name, unique within the owner scope and its ancestors
	NameKey     string `json:"name_key"`    // normalised name used for uniqueness; set by wardn
	Description string `json:"description"` //

	// Allow lists the permissions the role grants: concrete permissions or
	// wildcards from the catalog.
	Allow []string `json:"allow"`

	// AssignableAt lists the scope types where the role may be assigned:
	// the owner's type and types below it. Default: the owner's type.
	AssignableAt []string `json:"assignable_at"`

	Version   int       `json:"version"` // incremented on every update; used to detect conflicting edits
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type Decision struct {
	Allowed    bool   `json:"allowed"`
	User       string `json:"user"`
	Permission string `json:"permission"`
	Scope      Scope  `json:"scope"` // the scope that was checked

	// Role is the role that decided the outcome: the role whose deny rule
	// matched, or the role that granted the permission. Empty when no role
	// matched or an error occurred.
	Role string `json:"role,omitempty"`
	// At is the scope where Role is assigned: Scope itself or an ancestor.
	At Scope `json:"at,omitzero"`
	// Rule is the allow or deny pattern that matched, e.g. "loan:*".
	Rule string `json:"rule,omitempty"`
	// Reason explains the decision in words, for logs and debugging.
	Reason string `json:"reason"`
}

type DeleteOption func(*deleteOptions)

type DeniedError struct {
	Decisions []Decision
}

type Event struct {
	Type EventType `json:"type"`
	// Actor is the acting user's ID. It is empty when System is true.
	Actor string `json:"actor,omitempty"`
	// System is true where no user is acting: changes made through
	// Warden.System, Link and Move called with no signed-in user in ctx,
	// and the expiry sweeper.
	System bool      `json:"system"`
	At     time.Time `json:"at,omitzero"`

	User   string `json:"user,omitempty"`  // assignments: whose access changed
	Role   string `json:"role,omitempty"`  // assignments and roles: system role name or custom role ID
	Scope  Scope  `json:"scope,omitzero"`  // assignments: where; roles: the owner; links and moves: the child
	Parent Scope  `json:"parent,omitzero"` // links and moves: the new parent
	// PreviousParent is the parent before a move (EventMoved).
	PreviousParent Scope `json:"previous_parent,omitzero"`

	StartsAt  time.Time `json:"starts_at,omitzero"` // assignments: the time window
	ExpiresAt time.Time `json:"expires_at,omitzero"`

	Before *CustomRole `json:"before,omitempty"` // role updates and deletions
	After  *CustomRole `json:"after,omitempty"`  // role creations and updates

	// Err is set when OnChange is called a second time for the same change
	// because it failed after OnChange approved it. A failed change may
	// have been partly applied (for example, a cascade deletion that deleted
	// the role but not all its assignments); the store is the source of
	// truth. OnChange's return value is ignored on that call.
	Err error `json:"-"`
}

type EventType string

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

type MemoryCacheOption func(*MemoryCache)

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

type Migrator interface {
	Migrate(ctx context.Context) error
}

type Permission struct {
	Name        string `json:"name"`
	Description string `json:"description"`
}

type Policy struct {
	// Scopes declares the scope types and how they nest. Leave it empty for
	// a product without tenancy, which uses only the Global scope.
	Scopes map[string]ScopeType

	// Permissions is the catalog: every permission the code checks, mapped
	// to a human-readable description. The built-in wardn:... permissions
	// are added automatically and must not be declared.
	Permissions map[string]string

	// Roles are the system roles, keyed by name.
	Roles map[string]Role
	// contains filtered or unexported fields
}

type PolicyError struct {
	Source string        // the file name, or "policy" for a Go-defined policy
	Issues []PolicyIssue // sorted by line, then path
}

type PolicyIssue struct {
	Line    int    // line in the source file; 0 if unknown
	Path    string // location in the policy, e.g. "roles.teller.allow[1]"
	Message string
}

type Role struct {
	Description string

	// Allow lists the permissions this role grants. Entries may be concrete
	// permissions ("loan:create"), resource wildcards ("loan:*"), or "*".
	Allow []string

	// Deny lists permissions this role takes away. A deny from any role
	// overrides an allow from every role.
	Deny []string

	// AssignableAt lists the scope types (or "global") at which this role
	// may be assigned. Empty means anywhere.
	AssignableAt []string
}

type RoleInfo struct {
	ID           string   `json:"id"`   // system role name, or custom role ID
	Name         string   `json:"name"` // display name (the system role name for system roles)
	Description  string   `json:"description"`
	Allow        []string `json:"allow"`
	Deny         []string `json:"deny,omitempty"`          // system roles only
	AssignableAt []string `json:"assignable_at,omitempty"` // empty: anywhere
	Custom       bool     `json:"custom"`
	Owner        Scope    `json:"owner,omitzero"`   // custom roles only
	Version      int      `json:"version,omitzero"` // custom roles only
}

type RoleSpec struct {
	Name         string   `json:"name"`
	Description  string   `json:"description"`
	Allow        []string `json:"allow"`
	AssignableAt []string `json:"assignable_at,omitempty"` // default: the owner scope's type
	// Deny is not supported for custom roles in this release: a RoleSpec
	// with Deny entries is rejected (design decision D2).
	Deny []string `json:"deny,omitempty"`
}

type RoleStore interface {
	// CreateRole saves a new custom role. It returns ErrRoleNameTaken if a
	// role with the same Owner and NameKey exists; the check and the write
	// must be atomic.
	CreateRole(ctx context.Context, r CustomRole) error

	// UpdateRole replaces a custom role if its stored version equals
	// expectedVersion, and returns ErrConflict otherwise, ErrRoleNotFound if
	// it does not exist, or ErrRoleNameTaken. r.Version is the new version.
	UpdateRole(ctx context.Context, r CustomRole, expectedVersion int) error

	// DeleteRole deletes a custom role. Deleting a role that does not exist
	// is not an error.
	DeleteRole(ctx context.Context, id string) error

	// Roles returns the custom roles with the given IDs, omitting IDs that
	// do not exist.
	Roles(ctx context.Context, ids []string) ([]CustomRole, error)

	// RolesOwnedBy returns the custom roles owned by any of the scopes.
	RolesOwnedBy(ctx context.Context, owners []Scope) ([]CustomRole, error)
}

type Scope struct {
	Type string `json:"type"` // a scope type declared in the policy, e.g. "branch"
	ID   string `json:"id"`   // the application's identifier for this instance, e.g. "b7"
}

type ScopeStore interface {
	// Link records that parent is the parent of child, replacing any
	// existing parent.
	Link(ctx context.Context, child, parent Scope) error

	// Parent returns child's parent, and false if none is recorded.
	Parent(ctx context.Context, child Scope) (Scope, bool, error)
}

type ScopeType struct {
	// Parent is the scope type this one sits inside, or "" for a top-level
	// type. Roles assigned at a parent scope apply in its children.
	Parent string
}

type Store interface {
	AssignmentStore
	RoleStore
	ScopeStore
}

type SweepOption func(*sweepOptions)

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

type TxStore interface {
	Store
	// InTx reports whether ctx carries an application transaction that
	// this store will use instead of starting its own. A wrapper around a
	// TxStore must implement it too, by calling the wrapped store.
	InTx(ctx context.Context) bool
}

type UndefinedError struct {
	Kind       string // "permission", "role" or "scope type"
	Name       string // the undefined name
	Suggestion string // the closest defined name, or ""
}

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