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
- Variables
- func HTTPHandler(s hostpb.HostServer) http.Handler
- func RegisterMethod(name, scope string, destructive bool, h InvokeHandler)
- func RegisterUnavailableAdmin(mux *http.ServeMux, wrap func(http.Handler) http.Handler)
- func WarnUnknownScopes(ctx context.Context, m wickplugin.Manifest)
- func WithCaller(ctx context.Context, c Caller) context.Context
- type AccessItem
- type AccessScope
- type AccountDirectory
- type Admin
- type AdminDirectory
- type Audit
- type AuditWriter
- type Bridge
- func (b *Bridge) BeginCall(key, kind, userID, sessionID string) (string, func())
- func (b *Bridge) BeginCallFrom(key, kind, userID, source, sessionID string) (string, func())
- func (b *Bridge) BeginCallInstance(key, kind, userID, sessionID, instanceID string) (string, func())
- func (b *Bridge) Close() error
- func (b *Bridge) GRPCServer(key, kind string) func([]grpc.ServerOption) *grpc.Server
- func (b *Bridge) ProcessEnv(key, kind string) ([]string, func())
- func (b *Bridge) RevokeKey(key string)
- func (b *Bridge) Revoked(key string) bool
- func (b *Bridge) ServeAs(w http.ResponseWriter, r *http.Request, key, kind string, scopes []string)
- func (b *Bridge) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (b *Bridge) SetRevoked(key string, revoked bool) (dropped int, changed bool, err error)
- func (b *Bridge) Start() error
- func (b *Bridge) URL() string
- type CallFilter
- type CallReader
- type CallStat
- type CallView
- type Caller
- type ConfigReader
- type ConnectorCall
- type ConnectorResult
- type ConnectorRunner
- type Decision
- type Deps
- type GormStore
- func (s *GormStore) CallStats(ctx context.Context, since time.Time) ([]CallStat, error)
- func (s *GormStore) Delete(ctx context.Context, pluginKey, scope, item string) error
- func (s *GormStore) List(ctx context.Context, pluginKey string) ([]entity.PluginHostPermission, error)
- func (s *GormStore) ListCalls(ctx context.Context, f CallFilter) ([]entity.PluginHostCall, int64, error)
- func (s *GormStore) PurgeCallsBefore(ctx context.Context, t time.Time) (int64, error)
- func (s *GormStore) Set(ctx context.Context, p entity.PluginHostPermission) error
- func (s *GormStore) WriteCalls(ctx context.Context, calls []entity.PluginHostCall) error
- type InvokeCall
- type InvokeHandler
- type LayoutData
- func (l *LayoutData) AttachSession(ctx context.Context, userID string, in *hostpb.AttachSessionRequest) error
- func (l *LayoutData) CreateTicket(ctx context.Context, userID string, in *hostpb.CreateTicketRequest) (*hostpb.Ticket, error)
- func (l *LayoutData) GetSessionMeta(ctx context.Context, userID, id string) (*hostpb.SessionMeta, error)
- func (l *LayoutData) GetTicket(ctx context.Context, userID string, in *hostpb.GetTicketRequest) (*hostpb.Ticket, error)
- func (l *LayoutData) ListSessions(ctx context.Context, userID string, in *hostpb.ListSessionsRequest) ([]*hostpb.SessionMeta, error)
- func (l *LayoutData) ListTickets(ctx context.Context, userID string, in *hostpb.ListTicketsRequest) ([]*hostpb.Ticket, error)
- func (l *LayoutData) SendToSession(ctx context.Context, userID, sessionID, text string) (bool, error)
- func (l *LayoutData) UpdateTicket(ctx context.Context, userID string, in *hostpb.UpdateTicketRequest) (*hostpb.Ticket, error)
- type ManifestDirectory
- type Manifests
- type MemoryPermissionStore
- type PermissionStore
- type Permissions
- func (p *Permissions) Clear(ctx context.Context, pluginKey, scope, item string) error
- func (p *Permissions) Decide(ctx context.Context, plugin PluginInfo, scope, item string) Decision
- func (p *Permissions) Invalidate(pluginKey string)
- func (p *Permissions) Set(ctx context.Context, pluginKey, scope, item string, allowed bool, by string) error
- func (p *Permissions) Statuses(ctx context.Context, plugin PluginInfo) []ScopeStatus
- type PluginAccess
- type PluginDirectory
- type PluginInfo
- type Principal
- type Principals
- type RevocationStore
- type ScopeStatus
- type Server
- func (s *Server) AttachSession(ctx context.Context, in *hostpb.AttachSessionRequest) (*hostpb.Empty, error)
- func (s *Server) ConnectedAccounts(ctx context.Context, in *hostpb.ConnectedAccountsRequest) (*hostpb.ConnectedAccountsResponse, error)
- func (s *Server) CreateTicket(ctx context.Context, in *hostpb.CreateTicketRequest) (*hostpb.Ticket, error)
- func (s *Server) ExecuteConnector(ctx context.Context, in *hostpb.ExecuteConnectorRequest) (*hostpb.ExecuteConnectorResponse, error)
- func (s *Server) GetConfig(ctx context.Context, in *hostpb.GetConfigRequest) (*hostpb.GetConfigResponse, error)
- func (s *Server) GetSessionMeta(ctx context.Context, in *hostpb.GetSessionMetaRequest) (*hostpb.SessionMeta, error)
- func (s *Server) GetTicket(ctx context.Context, in *hostpb.GetTicketRequest) (*hostpb.Ticket, error)
- func (s *Server) GetUser(ctx context.Context, in *hostpb.GetUserRequest) (*hostpb.User, error)
- func (s *Server) GetUserByEmail(ctx context.Context, in *hostpb.GetUserByEmailRequest) (*hostpb.User, error)
- func (s *Server) Invoke(ctx context.Context, in *hostpb.InvokeRequest) (*hostpb.InvokeResponse, error)
- func (s *Server) ListConnectorInstances(ctx context.Context, in *hostpb.ListConnectorInstancesRequest) (*hostpb.ListConnectorInstancesResponse, error)
- func (s *Server) ListMethods(ctx context.Context, _ *hostpb.ListMethodsRequest) (*hostpb.ListMethodsResponse, error)
- func (s *Server) ListSessions(ctx context.Context, in *hostpb.ListSessionsRequest) (*hostpb.ListSessionsResponse, error)
- func (s *Server) ListTickets(ctx context.Context, in *hostpb.ListTicketsRequest) (*hostpb.ListTicketsResponse, error)
- func (s *Server) ListUsers(ctx context.Context, in *hostpb.ListUsersRequest) (*hostpb.ListUsersResponse, error)
- func (s *Server) Query(ctx context.Context, in *hostpb.QueryRequest) (*hostpb.QueryResponse, error)
- func (s *Server) Rest(ctx context.Context, in *hostpb.RestRequest) (*hostpb.RestResponse, error)
- func (s *Server) SendToSession(ctx context.Context, in *hostpb.SendToSessionRequest) (*hostpb.SendToSessionResponse, error)
- func (s *Server) UpdateTicket(ctx context.Context, in *hostpb.UpdateTicketRequest) (*hostpb.Ticket, error)
- func (s *Server) Whoami(ctx context.Context, _ *hostpb.WhoamiRequest) (*hostpb.WhoamiResponse, error)
- type ServiceTokens
- type SessionService
- type TicketService
- type TokenAuthenticator
- type UserDirectory
- type UserLookup
Constants ¶
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).
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.
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.
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.
const ( QueryMaxTimeout = 10 * time.Second QueryMaxRows = 5000 )
Query limits.
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.
const AuditRetention = 7 * 24 * time.Hour
AuditRetention is how long plugin_host_calls rows are kept.
const BlockAll = "*"
BlockAll is the scope and item of the "Block all host access" overlay row.
const HostAPINotStarted = "host API not started"
HostAPINotStarted answers every admin route when the Host API failed to start.
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).
const UsersCacheTTL = 60 * time.Second
UsersCacheTTL is how long the users list is served from memory.
Variables ¶
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 ¶
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.
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 ¶
Get returns one plugin's access (any kind, declaring or not: the detail card shows "no host access" for the latter).
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 ¶
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.
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 ¶
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 ¶
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) GRPCServer ¶
GRPCServer is the broker-side Host API server for one process of key.
func (*Bridge) ProcessEnv ¶
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 ¶
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) ServeAs ¶
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 ¶
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.
type CallFilter ¶
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.
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 (*GormStore) CallStats ¶
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) 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 ¶
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 ¶
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 ¶
func (m *MemoryPermissionStore) List(_ context.Context, pluginKey string) ([]entity.PluginHostPermission, error)
List implements PermissionStore.
func (*MemoryPermissionStore) Set ¶
func (m *MemoryPermissionStore) Set(_ context.Context, p entity.PluginHostPermission) error
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 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 ¶
RevocationStore persists the per-plugin revoke flag (the service host's token file, the same flag as the "Callback to wick" switch).
type ScopeStatus ¶
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 (*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 ¶
func (s *Server) ConnectedAccounts(ctx context.Context, in *hostpb.ConnectedAccountsRequest) (*hostpb.ConnectedAccountsResponse, error)
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 ¶
func (s *Server) ExecuteConnector(ctx context.Context, in *hostpb.ExecuteConnectorRequest) (*hostpb.ExecuteConnectorResponse, error)
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 ¶
func (s *Server) GetConfig(ctx context.Context, in *hostpb.GetConfigRequest) (*hostpb.GetConfigResponse, error)
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) 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 ¶
func (s *Server) Invoke(ctx context.Context, in *hostpb.InvokeRequest) (*hostpb.InvokeResponse, error)
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 ¶
func (s *Server) ListConnectorInstances(ctx context.Context, in *hostpb.ListConnectorInstancesRequest) (*hostpb.ListConnectorInstancesResponse, error)
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 ¶
func (s *Server) ListMethods(ctx context.Context, _ *hostpb.ListMethodsRequest) (*hostpb.ListMethodsResponse, error)
ListMethods lists the Host API RPCs, then the Invoke methods (built-in aliases and RegisterMethod registrations), each with its scope.
func (*Server) ListSessions ¶
func (s *Server) ListSessions(ctx context.Context, in *hostpb.ListSessionsRequest) (*hostpb.ListSessionsResponse, error)
ListSessions lists session metadata the acting user can see.
func (*Server) ListTickets ¶
func (s *Server) ListTickets(ctx context.Context, in *hostpb.ListTicketsRequest) (*hostpb.ListTicketsResponse, error)
ListTickets lists a project's tickets.
func (*Server) ListUsers ¶
func (s *Server) ListUsers(ctx context.Context, in *hostpb.ListUsersRequest) (*hostpb.ListUsersResponse, error)
ListUsers lists approved users (all with include_unapproved), filtered by q against name and email, from a cache refreshed every UsersCacheTTL.
func (*Server) Query ¶
func (s *Server) Query(ctx context.Context, in *hostpb.QueryRequest) (*hostpb.QueryResponse, error)
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 ¶
func (s *Server) Rest(ctx context.Context, in *hostpb.RestRequest) (*hostpb.RestResponse, error)
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 ¶
func (s *Server) SendToSession(ctx context.Context, in *hostpb.SendToSessionRequest) (*hostpb.SendToSessionResponse, error)
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 ¶
func (s *Server) Whoami(ctx context.Context, _ *hostpb.WhoamiRequest) (*hostpb.WhoamiResponse, error)
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 ¶
UserDirectory lists wick users (the admin users repo satisfies it).