Documentation
¶
Overview ¶
Package api holds the shared types for the vigolium.* JavaScript API surface: the namespace constants, the JSFuncDef declaration + handler factory, the APIOptions dependency bundle, and the APIFunction documentation record.
It is a leaf package: the jsext engine and each per-domain function package (api/parse, …) import it, but it imports nothing from jsext. This lets API domains live in their own subpackages while sharing one source of truth for the registry types.
Index ¶
Constants ¶
const ( NsRoot = "vigolium" NsLog = "vigolium.log" NsUtils = "vigolium.utils" NsParse = "vigolium.parse" NsHTTP = "vigolium.http" NsScan = "vigolium.scan" NsIngest = "vigolium.ingest" NsAgent = "vigolium.agent" NsDB = "vigolium.db" NsDBRecords = "vigolium.db.records" NsDBFindings = "vigolium.db.findings" NsOAST = "vigolium.oast" NsRecord = "vigolium.record" NsConfig = "vigolium.config" NsMCP = "vigolium.mcp" )
Namespace constants for the vigolium.* JS API.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type APIFunction ¶
type APIFunction struct {
Category string // display category, e.g. "Encoding & Decoding"
Namespace string // e.g. "vigolium.log"
Name string // e.g. "info"
Signature string // e.g. ".info(msg: string)"
Returns string // e.g. "void"
Description string // e.g. "Log an informational message."
Example string // e.g. `vigolium.log.info("scanning " + ctx.request.url)`
}
APIFunction describes a single JS API function for documentation.
func (APIFunction) FullName ¶
func (f APIFunction) FullName() string
FullName returns the fully-qualified function name (e.g. "vigolium.utils.base64Encode").
type APIOptions ¶
type APIOptions struct {
ScriptID string
HTTPClient *http.Requester
ConfigVars map[string]string
// Scanner context (all nil-safe)
ScopeMatcher *config.ScopeMatcher
ScopeConfig *config.ScopeConfig
ScanUUID string
ProjectUUID string
// Security controls (from extensions config)
AllowExec bool // gate for exec() and setEnv(); default false
SandboxDir string // base path for file ops; empty = cwd
ExecTimeout int // max seconds for exec(); default 30, cap 120
// Finding emitter for hooks that want to create findings
FindingEmitter func(*output.ResultEvent)
// Database repository for ingest API (nil = ingest disabled)
Repository *database.Repository
// LLMClient enables vigolium.agent.* API (nil = disabled)
LLMClient llm.Client
// OASTService enables vigolium.oast.* API (nil = disabled)
OASTService *oast.Service
// Mode selects runtime wiring (the default) or load/lint wiring, where
// every non-pure handler is a recording stub. See Mode.
Mode Mode
// OnLoadEffect receives each stubbed effectful call in ModeLoad. Nil
// discards them.
OnLoadEffect func(EffectCall)
}
APIOptions holds all context needed to set up the vigolium.* JS API on a VM.
type Effect ¶ added in v0.5.3
type Effect uint8
Effect classifies what a vigolium.* API function does to the world outside the VM. It decides what a function may do while an extension is being loaded or linted: ModeLoad runs a script's top-level code with every EffectPure handler real and every other handler replaced by a recording stub, so loading or linting a script can never send traffic, touch the filesystem or the database, run a command, or call a model.
EffectUnset is the zero value on purpose: a JSFuncDef that forgets to declare its effect is caught by a contract test instead of silently counting as pure.
const ( // EffectUnset is the undeclared zero value; no registered def may carry it. EffectUnset Effect = iota // EffectPure computes from its arguments (and read-only process state such // as config variables or the module registry) without side effects. EffectPure // EffectNetwork sends HTTP/MCP traffic, or returns an object whose methods do. EffectNetwork // EffectFS reads or writes the filesystem. EffectFS // EffectExec runs a process or changes the process environment. EffectExec // EffectDBRead reads the scan database. EffectDBRead // EffectDBWrite writes the scan database (records, findings, annotations). EffectDBWrite // EffectLLM calls a language model. EffectLLM // EffectOAST uses the out-of-band interaction service. EffectOAST // EffectScan emits findings or queues scans. EffectScan // EffectSleep blocks the calling goroutine. EffectSleep )
type EffectCall ¶ added in v0.5.3
type EffectCall struct {
API string // fully-qualified name, e.g. "vigolium.http.get"
Effect Effect
Line int // 1-based line in the evaluated source, 0 if unknown
Col int // 1-based column, 0 if unknown
}
EffectCall is one effectful API call a script made while it was being loaded (that is, from top-level code, or from a function top-level code invoked).
type HandlerFactory ¶
type HandlerFactory func(vm *sobek.Runtime, opts APIOptions) func(sobek.FunctionCall) sobek.Value
HandlerFactory creates a JS function handler given runtime dependencies. It is called once per VM setup, not per invocation.
type JSFuncDef ¶
type JSFuncDef struct {
Namespace string
Name string
Category string
Signature string
Returns string
Description string
Example string
// Effect is what the function does outside the VM. Required: EffectUnset
// fails the registry contract test. ModeLoad runs EffectPure handlers for
// real and stubs every other effect (see Effect).
Effect Effect
MakeHandler HandlerFactory // nil for metadata-only entries
}
JSFuncDef declares a JS API function with metadata and an optional handler factory. When MakeHandler is nil, the entry is metadata-only (e.g., dynamic config keys, per-request properties like vigolium.record.uuid).
type Mode ¶ added in v0.5.3
type Mode uint8
Mode selects how SetupAPI wires the vigolium.* API onto a VM.
const ( // ModeRuntime is a scan VM: handlers are real, and a namespace whose // dependency is missing (no HTTP client, no repository, …) is left out. ModeRuntime Mode = iota // ModeLoad is a load/lint VM: every namespace is registered so a script's // top-level code sees the same API shape it gets at runtime, EffectPure // handlers are real, and every other handler is a stub that returns an empty // value of its declared type and reports the call to APIOptions.OnLoadEffect. ModeLoad )
Source Files
Directories