hostapi

package
v1.17.1 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 44 Imported by: 0

Documentation

Overview

Package hostapi serves the plugin Host API (wick.host.v1): the calls a plugin makes back into wick. One Server answers both doors — the gRPC broker (Server is a hostpb.HostServer) and the HTTP door (HTTPHandler) — so permissions, identity, audit and the users cache are identical.

The doors authenticate the plugin and put a Caller on the context (WithCaller); everything after that lives here.

Index

Constants

View Source
const (
	AdminBase      = "/manager/api/plugin-host-access"
	AdminCallsPath = "/manager/api/plugin-host-calls"
)

AdminBase is where the admin JSON API of the Host access page lives. The path holds "plugin", so a plugin can never declare it in host_resources (RestPathReserved).

View Source
const (
	// SourceCaller: the person who opened or triggered the plugin.
	SourceCaller = "caller"
	// SourceToken: the owner of the access token the request carried.
	SourceToken = "token"
	// SourcePAT: the owner of the PAT stored in the plugin's wick_pat config.
	SourcePAT = "pat"
)

Where Caller.UserID came from.

View Source
const (
	ConnectorDefaultTimeout = 3 * time.Minute
	ConnectorMaxTimeout     = 5 * time.Minute
)

Connector op deadlines: the default when the call carries none, and the most a call may ask for.

View Source
const (
	StatusAllowed      = "allowed"
	StatusBlocked      = "blocked"
	StatusUndeclared   = "undeclared"     // used but not in the manifest; allowed in phase 1
	StatusOffByDefault = "off-by-default" // default-deny scope nobody allowed yet
	StatusUnknown      = "unknown"        // declared but not known to this wick; denied
)

Effective status of a (plugin, scope), as the admin page colours it.

View Source
const (
	QueryMaxTimeout = 10 * time.Second
	QueryMaxRows    = 5000
)

Query limits.

View Source
const (
	RestMaxRequestBytes  = 16 << 20
	RestMaxResponseBytes = 64 << 20
	RestPerPlugin        = 4
	RestDefaultTimeout   = 30 * time.Second
	RestMaxTimeout       = 60 * time.Second
)

Rest limits, the same on both doors: a request body of at most RestMaxRequestBytes, a buffered response of at most RestMaxResponseBytes, at most RestPerPlugin calls in flight per plugin (the responses are held in memory), RestDefaultTimeout when the call has no deadline and never more than RestMaxTimeout.

View Source
const AuditRetention = 7 * 24 * time.Hour

AuditRetention is how long plugin_host_calls rows are kept.

View Source
const BlockAll = "*"

BlockAll is the scope and item of the "Block all host access" overlay row.

View Source
const HostAPINotStarted = "host API not started"

HostAPINotStarted answers every admin route when the Host API failed to start.

View Source
const PATConfigKey = "wick_pat"

PATConfigKey is the plugin config that holds the PAT user-level calls run as when no person triggered the plugin (a cron job, a webhook).

View Source
const UsersCacheTTL = 60 * time.Second

UsersCacheTTL is how long the users list is served from memory.

Variables

View Source
var ErrRevocationUnavailable = errors.New("host api revocation is not available")

ErrRevocationUnavailable means no store can keep the revoke flag.

Functions

func HTTPHandler

func HTTPHandler(s hostpb.HostServer) http.Handler

HTTPHandler serves the HTTP door from host.Routes over the same Server the gRPC door uses. The door in front of it authenticates the plugin token and puts the Caller on the request context (WithCaller); paths are accepted with or without the host.CallbackPrefix mount.

func RegisterMethod

func RegisterMethod(name, scope string, destructive bool, h InvokeHandler)

RegisterMethod makes name callable through Invoke under scope (an official RPC scope without a host_resources block). The method runs as the acting person when a user-level RPC uses the same scope (sessions, tickets, connectors.read), else as the plugin alone. Its admin item is the method name, so an admin can block one method and keep the rest of the scope. It panics on an unknown, declarative or resource scope, an empty name or a name taken by a built-in alias or another registration: programming errors caught at start-up.

func RegisterUnavailableAdmin

func RegisterUnavailableAdmin(mux *http.ServeMux, wrap func(http.Handler) http.Handler)

RegisterUnavailableAdmin mounts the admin routes answering 503 HostAPINotStarted, for a wick whose Host API did not start; wrap is the admin middleware.

func WarnUnknownScopes

func WarnUnknownScopes(ctx context.Context, m wickplugin.Manifest)

WarnUnknownScopes logs the host_scopes of a loaded manifest this wick does not know. The plugin still loads (§8); calls under them are denied.

func WithCaller

func WithCaller(ctx context.Context, c Caller) context.Context

WithCaller returns ctx carrying c. Both doors call it before handing the request to the Server.

Types

type AccessItem

type AccessItem struct {
	Item        string `json:"item"`
	Blocked     bool   `json:"blocked"`
	Destructive bool   `json:"destructive"`
}

AccessItem is one declared item of a scope.

type AccessScope

type AccessScope struct {
	Scope        string       `json:"scope"`
	Label        string       `json:"label,omitempty"`
	Description  string       `json:"description,omitempty"`
	Declared     bool         `json:"declared"`
	Known        bool         `json:"known"`
	Status       string       `json:"status"`
	Reason       string       `json:"reason,omitempty"`
	Overlay      string       `json:"overlay,omitempty"` // "allow", "block" or "" (default)
	DefaultAllow bool         `json:"default_allow"`
	Destructive  bool         `json:"destructive"`
	Sensitive    bool         `json:"sensitive"`
	Declarative  bool         `json:"declarative"`
	Resource     string       `json:"resource,omitempty"`
	Items        []AccessItem `json:"items,omitempty"`
	Calls        int64        `json:"calls_24h"`
	Failed       int64        `json:"failed_24h"`
	Denied       int64        `json:"denied_24h"`
}

AccessScope is one scope row of a plugin.

type AccountDirectory

type AccountDirectory interface {
	ConnectedAccounts(ctx context.Context, instanceID string) ([]*hostpb.AccountRef, error)
}

AccountDirectory lists the accounts linked to a connector instance.

type Admin

type Admin struct {
	Plugins AdminDirectory
	Perms   *Permissions
	Calls   CallReader
	// Op reports a connector op's destructive flag (ConnectorRunner.Op);
	// nil = connector items are never marked destructive.
	Op func(connector, op string) (destructive, found bool)
	// Revoke revokes (true) or restores (false) all Host API access of a
	// plugin, persistently and over both doors (Bridge.SetRevoked); nil =
	// the host API is not running. dropped counts live process tokens
	// dropped; changed is false when nothing changed.
	Revoke func(key string, revoked bool) (dropped int, changed bool, err error)
	// Revoked reports the revoke flag (Bridge.Revoked); nil = never.
	Revoked func(key string) bool
	// Actor is the signed-in admin making a change ("" when unknown).
	Actor func(*http.Request) string
	// contains filtered or unexported fields
}

Admin serves the "Plugins → Host access" page: what every plugin declares, the overlay decisions, the audit, and the emergency switches.

func (*Admin) Get

func (a *Admin) Get(ctx context.Context, key string) (PluginAccess, bool)

Get returns one plugin's access (any kind, declaring or not: the detail card shows "no host access" for the latter).

func (*Admin) List

func (a *Admin) List(ctx context.Context) []PluginAccess

List returns every plugin that declares Host API access, was seen calling it in the audit window, or is blocked; sorted by key.

func (*Admin) RegisterAdmin

func (a *Admin) RegisterAdmin(mux *http.ServeMux, wrap func(http.Handler) http.Handler)

RegisterAdmin mounts the Host access API; wrap is the admin middleware (the same one every other plugin admin route uses).

type AdminDirectory

type AdminDirectory interface {
	PluginDirectory
	All() []PluginInfo
}

AdminDirectory is what the admin page needs from the plugin directory: every installed plugin, plus the scopes ManifestDirectory flagged unknown.

type Audit

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

Audit records every Host API call off the request path: Record only queues; one goroutine writes batches and purges rows past AuditRetention. A full queue, or a Record after Close, drops the record (counted in Dropped) rather than slow a plugin down or panic during shutdown. The queue channel is never closed: Close signals through stop instead, so a late Record cannot send on a closed channel.

func NewAudit

func NewAudit(w AuditWriter) *Audit

NewAudit returns an Audit writing to w. Call Start to run it.

func (*Audit) Close

func (a *Audit) Close()

Close stops accepting records and waits (bounded by auditCloseTimeout) for what is queued to be written. Safe to call more than once.

func (*Audit) Dropped

func (a *Audit) Dropped() int64

Dropped is how many records were lost (full queue, after Close, or a row the writer refused).

func (*Audit) Record

func (a *Audit) Record(c entity.PluginHostCall)

Record queues one call, its columns clipped to their sizes. Safe on a nil Audit and after Close.

func (*Audit) Start

func (a *Audit) Start(ctx context.Context)

Start runs the writer until ctx ends or Close is called; the queue is flushed on the way out.

type AuditWriter

type AuditWriter interface {
	WriteCalls(ctx context.Context, calls []entity.PluginHostCall) error
	PurgeCallsBefore(ctx context.Context, t time.Time) (int64, error)
}

AuditWriter persists audit rows. GormStore implements it.

type Bridge

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

Bridge carries the Server to plugin processes: the gRPC door over each go-plugin broker, the private HTTP door, the per-process tokens and the call ids that tie a Host API call to the person behind the request. It satisfies wickplugin.HostBridge.

func NewBridge

func NewBridge(srv *Server, service ServiceTokens) *Bridge

NewBridge returns a Bridge over srv. service may be nil (no service plugins).

func (*Bridge) BeginCall

func (b *Bridge) BeginCall(key, kind, userID, sessionID string) (string, func())

BeginCall records that the request about to be sent to plugin key runs for userID (from sessionID); the plugin echoes the returned id on its Host API calls. Nothing to record yields "".

func (*Bridge) BeginCallFrom

func (b *Bridge) BeginCallFrom(key, kind, userID, source, sessionID string) (string, func())

BeginCallFrom is BeginCall with the identity's source (SourceToken for a service route reached with an access token).

func (*Bridge) BeginCallInstance

func (b *Bridge) BeginCallInstance(key, kind, userID, sessionID, instanceID string) (string, func())

BeginCallInstance is BeginCall for a connector Execute: it also records the instance being executed, which instance-bound RPCs are held to.

func (*Bridge) Close

func (b *Bridge) Close() error

Close stops the HTTP door.

func (*Bridge) GRPCServer

func (b *Bridge) GRPCServer(key, kind string) func([]grpc.ServerOption) *grpc.Server

GRPCServer is the broker-side Host API server for one process of key.

func (*Bridge) ProcessEnv

func (b *Bridge) ProcessEnv(key, kind string) ([]string, func())

ProcessEnv is the Host API env of a new connector/tool/job process: the private door, the broker flag and a fresh token (none while an admin has revoked the plugin's callback access). release revokes that token; the spawner calls it once the process is gone.

func (*Bridge) RevokeKey

func (b *Bridge) RevokeKey(key string)

RevokeKey drops every live process token of key at once (the admin's "Callback to wick" revoke for any kind). Broker calls are refused through the same CallbackRevoked flag the door checks.

func (*Bridge) Revoked

func (b *Bridge) Revoked(key string) bool

Revoked reports whether an admin revoked key's Host API access.

func (*Bridge) ServeAs

func (b *Bridge) ServeAs(w http.ResponseWriter, r *http.Request, key, kind string, scopes []string)

ServeAs serves r for a plugin the caller already authenticated (the public callback door's whoami).

func (*Bridge) ServeHTTP

func (b *Bridge) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP is the private HTTP door: plugin token → Caller → the shared handler.

func (*Bridge) SetRevoked

func (b *Bridge) SetRevoked(key string, revoked bool) (dropped int, changed bool, err error)

SetRevoked revokes (true) or restores (false) all Host API access of key, for every kind and both doors. Revoking sets the persistent flag (the broker interceptor and the door refuse key, ProcessEnv issues no token, a service's callback token is dropped) and drops key's live process tokens; dropped counts those. changed is false when key already was in the asked state. Restoring lets the next process get a token again.

func (*Bridge) Start

func (b *Bridge) Start() error

Start opens the private HTTP door on a loopback port. Plugins learn the address from WICK_HOST_API_URL; wick's public URL never takes a plugin token.

func (*Bridge) URL

func (b *Bridge) URL() string

URL is the private door address ("" before Start).

type CallFilter

type CallFilter struct {
	PluginKey  string
	FailedOnly bool
	Since      time.Time
	Offset     int
	Limit      int
}

CallFilter narrows the audit list.

type CallReader

type CallReader interface {
	ListCalls(ctx context.Context, f CallFilter) ([]entity.PluginHostCall, int64, error)
	CallStats(ctx context.Context, since time.Time) ([]CallStat, error)
}

CallReader reads the audit back for the admin page. GormStore implements it.

type CallStat

type CallStat struct {
	PluginKey string
	Scope     string
	Calls     int64
	// Failed counts every call that did not succeed; Denied only those
	// refused with PermissionDenied.
	Failed int64
	Denied int64
	Last   time.Time
}

CallStat counts one (plugin, scope)'s calls since a point in time.

type CallView

type CallView struct {
	Ts         time.Time `json:"ts"`
	PluginKey  string    `json:"plugin"`
	Kind       string    `json:"kind"`
	RPC        string    `json:"rpc"`
	Scope      string    `json:"scope"`
	Item       string    `json:"item,omitempty"`
	UserID     string    `json:"user_id,omitempty"`
	Source     string    `json:"source,omitempty"`
	OK         bool      `json:"ok"`
	Code       string    `json:"code,omitempty"`
	DurationMs int64     `json:"duration_ms"`
}

CallView is one audit row.

type Caller

type Caller struct {
	PluginKey string
	Kind      string // connector | tool | job | service
	// UserID is the person the call runs for ("" = none known; user-level
	// calls then fall back to the plugin's wick_pat).
	UserID string
	Source string
	// SessionID is the wick session the plugin was triggered from, when
	// there is one. Reserved: the doors fill it in W3 so session/ticket
	// access can apply the calling agent's own data scope.
	SessionID string
	// InstanceID is the connector instance the Execute behind this call
	// runs ("" = none, e.g. a tool or job request). Instance-bound RPCs
	// (ConnectedAccounts) answer for this instance only.
	InstanceID string
	// CallbackScopes are a service plugin's legacy callback_scopes, echoed
	// as "scopes" by the HTTP whoami for plugins that predate the Host API.
	CallbackScopes []string
}

Caller is the plugin making a Host API call, as the door authenticated it.

func CallerFrom

func CallerFrom(ctx context.Context) (Caller, bool)

CallerFrom returns the Caller on ctx.

type ConfigReader

type ConfigReader interface {
	Config(ctx context.Context, owner, key string) (value string, found, secret bool, err error)
}

ConfigReader reads one config row by owner and key.

type ConnectorCall

type ConnectorCall struct {
	Connector  string
	InstanceID string
	Op         string
	Args       map[string]any
	AccountID  string
	// PluginKey names the plugin in the run history.
	PluginKey string
}

ConnectorCall is one ExecuteConnector request after the gate.

type ConnectorResult

type ConnectorResult struct {
	RunID  string
	Status string
	// ResultJSON is the op's response after wick's masking.
	ResultJSON string
}

ConnectorResult is the masked outcome of one connector op.

type ConnectorRunner

type ConnectorRunner interface {
	// ListInstances lists the enabled instances p can see; connector ""
	// means every module.
	ListInstances(ctx context.Context, p Principal, connector string) ([]*hostpb.ConnectorInstance, error)
	// Op reports whether connector has op and whether the op is destructive.
	Op(connector, op string) (destructive, found bool)
	// Execute runs one op as p. An instance p cannot see, or one of another
	// module, is NotFound.
	Execute(ctx context.Context, p Principal, call ConnectorCall) (*ConnectorResult, error)
}

ConnectorRunner lists and runs connector instances exactly as a person reaches them through wick_list / wick_execute (NewConnectorRunner wraps connectors.Service).

func NewConnectorRunner

func NewConnectorRunner(svc *connectors.Service) ConnectorRunner

NewConnectorRunner wraps svc.

type Decision

type Decision struct {
	Allowed bool
	Status  string
	// Reason says why a call was denied, for the PermissionDenied message.
	Reason string
}

Decision is the effective answer for one call.

type Deps

type Deps struct {
	Plugins PluginDirectory
	Users   UserDirectory
	// UserTags returns the tag ids of many users in one query, for
	// User.tags (optional).
	UserTags func(ctx context.Context, userIDs []string) (map[string][]string, error)
	Configs  ConfigReader
	PATs     TokenAuthenticator
	Accounts AccountDirectory
	Sessions SessionService
	Tickets  TicketService
	// Principals resolves the acting user for Rest and connectors.
	Principals Principals
	// Connectors backs ListConnectorInstances and ExecuteConnector.
	Connectors ConnectorRunner
	// Router is wick's own HTTP handler (the one the public listener
	// serves); Rest dispatches into it in-process.
	Router http.Handler
	// DB is wick's database handle; Query runs on it and never opens a
	// connection of its own.
	DB    *gorm.DB
	Perms *Permissions
	Audit *Audit
	// WickVersion is reported by Whoami.
	WickVersion string
}

Deps wires the Server to wick. A nil dependency makes the RPCs that need it answer Unimplemented (the SDK reports ErrHostAPIUnavailable).

type GormStore

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

GormStore keeps the permission overlay and the call audit in the wick database (plugin_host_permissions, plugin_host_calls).

func NewGormStore

func NewGormStore(db *gorm.DB) *GormStore

NewGormStore wraps db.

func (*GormStore) CallStats

func (s *GormStore) CallStats(ctx context.Context, since time.Time) ([]CallStat, error)

CallStats implements CallReader: one row per (plugin, scope) with calls since since. The last call time is read back by id so no database has to scan MAX(ts) into a time.

func (*GormStore) Delete

func (s *GormStore) Delete(ctx context.Context, pluginKey, scope, item string) error

Delete implements PermissionStore.

func (*GormStore) List

func (s *GormStore) List(ctx context.Context, pluginKey string) ([]entity.PluginHostPermission, error)

List implements PermissionStore.

func (*GormStore) ListCalls

func (s *GormStore) ListCalls(ctx context.Context, f CallFilter) ([]entity.PluginHostCall, int64, error)

ListCalls implements CallReader: newest first, with the total that matched the filter for paging.

func (*GormStore) PurgeCallsBefore

func (s *GormStore) PurgeCallsBefore(ctx context.Context, t time.Time) (int64, error)

PurgeCallsBefore implements AuditWriter.

func (*GormStore) Set

Set implements PermissionStore. A map is written so a false Allowed is stored as such on insert.

func (*GormStore) WriteCalls

func (s *GormStore) WriteCalls(ctx context.Context, calls []entity.PluginHostCall) error

WriteCalls implements AuditWriter.

type InvokeCall

type InvokeCall struct {
	PluginKey string
	// UserID is the acting person; "" for a method whose scope is
	// plugin-level.
	UserID string
	Args   json.RawMessage
}

InvokeCall is what an Invoke method handler runs with.

type InvokeHandler

type InvokeHandler func(ctx context.Context, in InvokeCall) (json.RawMessage, error)

InvokeHandler serves one method registered with RegisterMethod. It returns the JSON result.

type LayoutData

type LayoutData struct {
	Layout agentconfig.Layout
	Users  UserLookup
	// Send queues text into a session as userID (optional; nil answers
	// Unimplemented until the agent pool is wired in).
	Send func(ctx context.Context, userID, sessionID, text string) (bool, error)
}

LayoutData serves sessions and tickets from wick's on-disk agent layout, through the same packages and access checks the built-in tickets connector uses (ticket.*, session.*, team.Check*). Only metadata leaves: never a conversation.

func (*LayoutData) AttachSession

func (l *LayoutData) AttachSession(ctx context.Context, userID string, in *hostpb.AttachSessionRequest) error

AttachSession implements TicketService. The acting user must reach both the ticket and the session.

func (*LayoutData) CreateTicket

func (l *LayoutData) CreateTicket(ctx context.Context, userID string, in *hostpb.CreateTicketRequest) (*hostpb.Ticket, error)

CreateTicket implements TicketService.

func (*LayoutData) GetSessionMeta

func (l *LayoutData) GetSessionMeta(ctx context.Context, userID, id string) (*hostpb.SessionMeta, error)

GetSessionMeta implements SessionService.

func (*LayoutData) GetTicket

func (l *LayoutData) GetTicket(ctx context.Context, userID string, in *hostpb.GetTicketRequest) (*hostpb.Ticket, error)

GetTicket implements TicketService.

func (*LayoutData) ListSessions

func (l *LayoutData) ListSessions(ctx context.Context, userID string, in *hostpb.ListSessionsRequest) ([]*hostpb.SessionMeta, error)

ListSessions implements SessionService: top-level sessions userID may see, most recently active first.

func (*LayoutData) ListTickets

func (l *LayoutData) ListTickets(ctx context.Context, userID string, in *hostpb.ListTicketsRequest) ([]*hostpb.Ticket, error)

ListTickets implements TicketService: a project's tickets, newest first.

func (*LayoutData) SendToSession

func (l *LayoutData) SendToSession(ctx context.Context, userID, sessionID, text string) (bool, error)

SendToSession implements SessionService.

func (*LayoutData) UpdateTicket

func (l *LayoutData) UpdateTicket(ctx context.Context, userID string, in *hostpb.UpdateTicketRequest) (*hostpb.Ticket, error)

UpdateTicket implements TicketService. Only set fields change; a field sent empty is removed; if_updated_at guards against a concurrent edit.

type ManifestDirectory

type ManifestDirectory struct {

	// ConfigOwner names the configs owner of a plugin's own rows per kind
	// ("" = the kind has no plugin config store).
	ConfigOwner func(kind, key string) string
	// contains filtered or unexported fields
}

ManifestDirectory is the PluginDirectory over the installed plugin manifests. Loading a manifest warns about host_scopes this wick does not know (WarnUnknownScopes) and keeps them for the admin page.

func NewManifestDirectory

func NewManifestDirectory(scan Manifests) *ManifestDirectory

NewManifestDirectory returns a directory over scan; call Reload once the plugins are installed.

func (*ManifestDirectory) All

func (d *ManifestDirectory) All() []PluginInfo

All lists every installed plugin, sorted by key (the admin Host access page).

func (*ManifestDirectory) Plugin

func (d *ManifestDirectory) Plugin(key string) (PluginInfo, bool)

Plugin resolves key; a miss rescans at most every rescanAfter.

func (*ManifestDirectory) Reload

func (d *ManifestDirectory) Reload(ctx context.Context)

Reload rescans every kind.

func (*ManifestDirectory) UnknownScopes

func (d *ManifestDirectory) UnknownScopes(key string) []string

UnknownScopes lists the host_scopes key declares that this wick does not know (denied; shown to the admin).

type Manifests

type Manifests func(kind string) ([]wickplugin.Manifest, error)

Manifests lists the installed manifests of one kind (connplugin.ScanKind over the kind's folder).

type MemoryPermissionStore

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

MemoryPermissionStore is an in-memory PermissionStore (tests, or a wick running without a database).

func NewMemoryPermissionStore

func NewMemoryPermissionStore() *MemoryPermissionStore

NewMemoryPermissionStore returns an empty store.

func (*MemoryPermissionStore) Delete

func (m *MemoryPermissionStore) Delete(_ context.Context, pluginKey, scope, item string) error

Delete implements PermissionStore.

func (*MemoryPermissionStore) List

List implements PermissionStore.

func (*MemoryPermissionStore) Set

Set implements PermissionStore.

type PermissionStore

type PermissionStore interface {
	List(ctx context.Context, pluginKey string) ([]entity.PluginHostPermission, error)
	Set(ctx context.Context, p entity.PluginHostPermission) error
	Delete(ctx context.Context, pluginKey, scope, item string) error
}

PermissionStore persists the admin overlay. Small on purpose: the admin UI needs exactly list, set and clear.

type Permissions

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

Permissions decides scope access from the manifest, the overlay and the scope defaults. Overlay rows are cached per plugin; Set/Clear/Invalidate drop the cache so an admin change applies to the next call.

func NewPermissions

func NewPermissions(store PermissionStore) *Permissions

NewPermissions wraps store (nil = no overlay, defaults only).

func (*Permissions) Clear

func (p *Permissions) Clear(ctx context.Context, pluginKey, scope, item string) error

Clear removes one overlay decision, returning it to the default.

func (*Permissions) Decide

func (p *Permissions) Decide(ctx context.Context, plugin PluginInfo, scope, item string) Decision

Decide answers whether plugin may call under scope. item is the table, the "METHOD /path" or the "connector.op" the call reaches; "" asks about the scope as a whole (whoami's scopes_allowed). Order: whoami is always allowed; an unreadable store denies; Block all; unknown scope; declaration (rest/db/connectors/config need the scope and the item declared); scope overlay or default; item overlay.

func (*Permissions) Invalidate

func (p *Permissions) Invalidate(pluginKey string)

Invalidate drops the cached overlay of pluginKey.

func (*Permissions) Set

func (p *Permissions) Set(ctx context.Context, pluginKey, scope, item string, allowed bool, by string) error

Set stores one overlay decision (item "" = the whole scope; BlockAll for both = block every scope of the plugin).

func (*Permissions) Statuses

func (p *Permissions) Statuses(ctx context.Context, plugin PluginInfo) []ScopeStatus

Statuses lists every official scope plus the unknown ones the plugin declared, each with its scope-level decision (W4 admin card).

type PluginAccess

type PluginAccess struct {
	Key        string `json:"key"`
	Kind       string `json:"kind"`
	Version    string `json:"version"`
	Declares   bool   `json:"declares"`
	BlockedAll bool   `json:"blocked_all"`
	// Revoked: an admin revoked all Host API access (tokens and broker)
	// until it is restored.
	Revoked   bool          `json:"revoked"`
	Scopes    []AccessScope `json:"scopes"`
	ItemCount int           `json:"item_count"`
	Calls     int64         `json:"calls_24h"`
	Failed    int64         `json:"failed_24h"`
	Denied    int64         `json:"denied_24h"`
	LastCall  *time.Time    `json:"last_call,omitempty"`
}

PluginAccess is one plugin on the Host access page and the "What it can do" card.

type PluginDirectory

type PluginDirectory interface {
	Plugin(key string) (PluginInfo, bool)
}

PluginDirectory resolves a plugin key to its manifest facts.

type PluginInfo

type PluginInfo struct {
	Key     string
	Kind    string
	Version string
	// ConfigOwner is the configs owner of the plugin's own rows (where
	// wick_pat lives); "" when the plugin has no config store.
	ConfigOwner string
	Scopes      []string
	Resources   *wickplugin.HostResources
}

PluginInfo is what the Server needs to know about an installed plugin.

type Principal

type Principal struct {
	User   *entity.User
	TagIDs []string
}

Principal is the acting person a user-level call runs as.

type Principals

type Principals interface {
	GetUserByID(ctx context.Context, id string) (*entity.User, error)
	GetUserFilterTagIDs(ctx context.Context, userID string) []string
}

Principals loads the acting user and their filter tags: the pair the PAT middleware stamps on a request (login.Service satisfies it).

type RevocationStore

type RevocationStore interface {
	SetCallbackRevoked(key string, revoked bool) error
}

RevocationStore persists the per-plugin revoke flag (the service host's token file, the same flag as the "Callback to wick" switch).

type ScopeStatus

type ScopeStatus struct {
	Scope    string
	Declared bool
	Decision Decision
}

ScopeStatus is one row of the admin "what this plugin can do" card.

type Server

type Server struct {
	hostpb.UnimplementedHostServer
	// contains filtered or unexported fields
}

Server implements hostpb.HostServer for both doors.

func NewServer

func NewServer(d Deps) *Server

NewServer returns a Server over d. A nil d.Perms decides on defaults only.

func (*Server) AttachSession

func (s *Server) AttachSession(ctx context.Context, in *hostpb.AttachSessionRequest) (*hostpb.Empty, error)

AttachSession attaches a session to a ticket as the acting user.

func (*Server) ConnectedAccounts

ConnectedAccounts lists the accounts linked to a connector instance. Like the in-process Ctx it answers for the instance being executed only: the caller must be a connector plugin inside an Execute wick started (its call id carries the instance), and instance_id must be that instance.

func (*Server) CreateTicket

func (s *Server) CreateTicket(ctx context.Context, in *hostpb.CreateTicketRequest) (*hostpb.Ticket, error)

CreateTicket creates a ticket as the acting user.

func (*Server) ExecuteConnector

ExecuteConnector runs a declared connector op as the acting user. The item is "connector.op": it must be declared in host_resources.connectors and not blocked by an admin. Instance ACL, per-op gates, account ownership, rate limits and masking are connectors.Service's, exactly as for wick_execute.

func (*Server) GetConfig

GetConfig reads one config value. The plugin's own rows (owner "" or its own owner/key) need no scope; another owner's need config.read_other. A secret of another owner is reported (found, secret) without its value unless config.read_secret allows that declared owner/key. wick_pat is never returned to anyone: wick resolves it itself.

func (*Server) GetSessionMeta

func (s *Server) GetSessionMeta(ctx context.Context, in *hostpb.GetSessionMetaRequest) (*hostpb.SessionMeta, error)

GetSessionMeta returns one session's metadata.

func (*Server) GetTicket

func (s *Server) GetTicket(ctx context.Context, in *hostpb.GetTicketRequest) (*hostpb.Ticket, error)

GetTicket returns one ticket the acting user can see.

func (*Server) GetUser

func (s *Server) GetUser(ctx context.Context, in *hostpb.GetUserRequest) (*hostpb.User, error)

GetUser returns one user by id.

func (*Server) GetUserByEmail

func (s *Server) GetUserByEmail(ctx context.Context, in *hostpb.GetUserByEmailRequest) (*hostpb.User, error)

GetUserByEmail returns one user by email (case-insensitive).

func (*Server) Invoke

Invoke calls a method by name with the scope of that method. Built-in aliases run their RPC (its own gate and audit row); registered methods are gated and audited here with the method name as the item.

func (*Server) ListConnectorInstances

ListConnectorInstances lists the connector instances the acting user can see: id, module key, label, status, ops, owner and the ids of the linked accounts that user may run as. Never a credential.

func (*Server) ListMethods

ListMethods lists the Host API RPCs, then the Invoke methods (built-in aliases and RegisterMethod registrations), each with its scope.

func (*Server) ListSessions

ListSessions lists session metadata the acting user can see.

func (*Server) ListTickets

ListTickets lists a project's tickets.

func (*Server) ListUsers

ListUsers lists approved users (all with include_unapproved), filtered by q against name and email, from a cache refreshed every UsersCacheTTL.

func (*Server) Query

Query runs one SQL statement on wick's database. write=false needs db.read and runs in a read-only transaction that is always rolled back; write=true needs db.write. Every table the statement reads is checked as db.read "<table>:read" (also on a write: an admin block on reading a table holds for INSERT ... SELECT too), every table it changes as db.write "<table>:write"; none may be undeclared or blocked. The SQL and params go to the audit note (each param cut to 64 bytes, all of it to 4 KB).

Placeholders follow the database dialect: $1, $2, ... on Postgres (what production wick runs), ? on SQLite. Params bind as text values.

func (*Server) Rest

Rest calls wick's own REST API in-process, as the acting user: the request enters the same router the public listener serves, with the user stamped on its context exactly as the PAT middleware stamps a token owner (login.WithUser), so every route keeps its own authorization checks. GET and HEAD need rest.read, other methods rest.write; the path must match a declared host_resources.rest pattern. The response (3xx included) is returned as the router wrote it, minus Set-Cookie.

func (*Server) SendToSession

SendToSession queues a message into a session as the acting user.

func (*Server) UpdateTicket

func (s *Server) UpdateTicket(ctx context.Context, in *hostpb.UpdateTicketRequest) (*hostpb.Ticket, error)

UpdateTicket updates a ticket as the acting user.

func (*Server) Whoami

Whoami reports the plugin, its declared scopes and the ones it may use.

type ServiceTokens

type ServiceTokens interface {
	LookupCallback(bearer string) (key string, scopes []string, ok bool)
	CallbackRevoked(key string) bool
}

ServiceTokens is the service host's callback token store: service plugins keep their scoped WICK_PLUGIN_TOKEN, and the door accepts it too.

type SessionService

type SessionService interface {
	ListSessions(ctx context.Context, userID string, in *hostpb.ListSessionsRequest) ([]*hostpb.SessionMeta, error)
	GetSessionMeta(ctx context.Context, userID, id string) (*hostpb.SessionMeta, error)
	SendToSession(ctx context.Context, userID, sessionID, text string) (queued bool, err error)
}

SessionService is the session metadata a plugin may see, always for userID (the acting person) and under that person's access rules.

type TicketService

type TicketService interface {
	GetTicket(ctx context.Context, userID string, in *hostpb.GetTicketRequest) (*hostpb.Ticket, error)
	ListTickets(ctx context.Context, userID string, in *hostpb.ListTicketsRequest) ([]*hostpb.Ticket, error)
	CreateTicket(ctx context.Context, userID string, in *hostpb.CreateTicketRequest) (*hostpb.Ticket, error)
	UpdateTicket(ctx context.Context, userID string, in *hostpb.UpdateTicketRequest) (*hostpb.Ticket, error)
	AttachSession(ctx context.Context, userID string, in *hostpb.AttachSessionRequest) error
}

TicketService is the ticket board as userID sees and edits it. Ticket ids are unique per project only: a request without project_id that matches in more than one project is FailedPrecondition, never a guess.

type TokenAuthenticator

type TokenAuthenticator interface {
	Authenticate(ctx context.Context, plain string) (userID string, err error)
}

TokenAuthenticator resolves a personal access token to its owner (accesstoken.Service satisfies it).

type UserDirectory

type UserDirectory interface {
	ListUsers(ctx context.Context) ([]*entity.User, error)
}

UserDirectory lists wick users (the admin users repo satisfies it).

type UserLookup

type UserLookup func(ctx context.Context, userID string) (*entity.User, []string, error)

UserLookup loads the acting user and their tag ids, so access checks see them exactly as they would see that person signed in.

Jump to

Keyboard shortcuts

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