-
v0.18.0 Stable
released this
2026-11-15 17:34:34 +00:00 | 3 commits to main since this releaseVSKI v0.18.0: Connectors
Connectors are now a first-class platform feature. A definition is a
declarative provider manifest, a connector is one configured instance of
it, and an account is an authorized credential. One generic engine handles
OAuth grants, API keys, basic passwords, custom headers, and public APIs.
Provider tokens stay on the server: pipelines, plugins, and triggers call
through an authenticated proxy instead of holding credentials.Definitions are data. Nothing is built into the binary, so the provider
catalog is exactly what your IaC declares and the dashboard shows.SDKs:
@vski/sdk2.11.0 andvski-sdk0.20.0.Upgrade notes:
- Four system collections (
_connector_definitions,_connectors,
_connector_accounts,_connector_oauth_states) are created
automatically on start. Existing collections are untouched. - Existing deployments start with an empty definition catalog. Apply
connectorDefinitionsbeforeconnectors;vski applyalready orders
definitions first. - OAuth providers need
<server>/api/connectors/oauth/callbackas their
registered callback. SetPUBLIC_URLwhen the server is behind a proxy
that does not forward the public host. - Accounts are connected interactively and are not IaC data. Their
credentials can reference entries in the encrypted secrets store. - Connector management endpoints require an admin. The request proxy
requires theworkflowsrole; admins also pass.
Definitions and IaC
connectorDefinitionsandconnectorsare global IaC kinds.vski plan,
vski apply, andvski pullround-trip them, with definitions applied
before connectors.vski pullwritesconnector-definitions.yamland
connectors.yaml.A definition declares:
api: base URL, exact allowed hosts, default headers, header fields,
auth scheme, and read-only mode.oauth: static client, authorization and token URLs, PKCE, token auth
style, form or JSON token requests, scopes, extra auth and refresh params,
token refresh, and the connect-time form.key: credential label, connect-time form, and auth scheme.account: profile URL and JSON paths for the remote account id, label,
and avatar. It labels OAuth accounts after the grant completes.name,description,icon,docs, and free-formmetadata.
api.baseUrlandapi.allowedHostsaccept{field}placeholders filled from
connect-time values, so one definition can target per-account sites without
giving up the host allow-list.api.readOnlyrejects every method except
GETandHEAD.Auth schemes cover
bearer,header,query,basic, andnone. A
custom-header connector declares itsapi.headerFields; a basic connector
names the form field used as the username.Definition ids match
[a-z0-9][a-z0-9-]{0,63}. OAuth registration is static:
the client id and secret belong to the connector config. Invalid definitions
fail before anything is written.Accounts and secrets
- OAuth: start a connection with
POST /api/connectors/{id}/connect.
The returned authorize URL carries a single-use state that expires after
10 minutes. The callback exchanges the code, stores the encrypted grant,
fetches the account profile, and returns to the dashboard. Access tokens
refresh automatically when an expiry is known, a refresh token is present,
and the definition enablesrefresh. - API key and basic password: connect with a token, a token secret, or
form values. Basic auth combines the username form field with the token. - Custom headers: each declared header is collected per account and can
come from a secret. - None: public APIs need no account.
tokenSecret,valueSecrets, andheaderSecretsname entries in the
encrypted VSKI secrets store and resolve at request time. Rotating a stored
secret updates every account that references it without rewriting the account
or the connector config. Credential values never appear in account responses,
connector configs, pipeline output, or run events.A connector can hold several accounts. Requests select one by id or name, or
fall back to the first active account.Pipelines, plugins, and triggers
Pipelines gain a
connectorstep. It resolvesaccount,path,url,
headers, andbodyas templates, attaches the account credential
server-side, and returns{status, headers, body}. Non-2xx provider responses
fail the step so the usual retries andonErrorbehavior apply. The timeout
defaults to 30 seconds and is capped at 120.{ "id": "projects", "type": "connector", "connector": "internal", "account": "{{input.account}}", "method": "GET", "path": "/v1/projects?limit=50" }Because
accountis templated, one pipeline definition can run against any
connected account supplied as run input, including accounts for different
sites of the same provider.Plugins and external systems use
POST /api/connectors/{id}/requestwith an
API key that carries theworkflowsrole. The proxy applies the stored
credential, enforces the host allow-list, and returns the provider status,
headers, and body. The proxy call itself answers200; a provider rejection
is reported instatus, and transport or configuration failures return
4xxor5xxwith the reason.A connector is bound to its declared hosts. Only
api.allowedHostsentries
and the resolved base URL host are reachable, matched exactly with no
wildcards. A single account at a site root can serve several APIs on that
host, such as Confluence under/wiki/api/v2/...and Jira under
/rest/api/3/....Connector dashboard and SDKs
- The Connectors page lists configured connectors with auth mode, account
count, status, base URL, and connect, accounts, test, and delete actions. - The add and edit wizard walks provider, auth, endpoints, credential rules,
connect-time form, and review as separate steps. Every provider comes from
the applied definition catalog or the custom definition; no provider list
is hardcoded in the UI. - The account dialog renders the definition form and supports stored-secret
references. The test dialog sends an authenticated provider path and shows
the status and response. - Dialog actions sit in a sticky footer outside the scrolling body.
SDK support:
- TypeScript
@vski/sdk2.11.0 addsclient.connectorswith definitions,
configs, accounts, OAuth start, and the request proxy. - Python
vski-sdk0.20.0 addsclient.connectorsand IaC loading, diffing,
applying, and pulling for both connector kinds. The synchronous client
exposes the same namespace.
Agent-facing dashboard
The dashboard can be handed a connection and opened on a single surface,
which is what an agent does when a human has to act: approve a run, filter
records, run a pipeline.GET /connect?endpoint=...&token=...&path=...saves the deployment URL and
its bearer token and forwards topath. Without a token it goes to login
with the target kept as?next=, so the user lands where they were headed.
The endpoint is normalized to an http(s) origin,nextstays
dashboard-relative, and a stale saved API key is cleared: the dashboard's
admin endpoints reject API keys andX-API-Keyis checked before
Authorization, so a leftover key would shadow the token./w/...routes render the same pages inside a chrome-less shell: no
sidebar, connection badge, breadcrumbs, feature chips, or desktop titlebar,
with dense padding. The page keeps its own actions — record create, edit,
delete, run, save, approve, reject — because widget mode strips navigation,
never capability.- Every surface has a widget route:
/w/overview,/w/collections/:name
(and/stats,/:id,/create),/w/workflows,/w/workflows/:runId,
/w/signals,/w/pipelines(and/:name),/w/connectors,/w/cron,
/w/gates,/w/webhooks,/w/api-keys,/w/secrets,/w/plugins,
/w/migrations,/w/graphs(and/:name,/create),/w/logs,/w/sql,
/w/settings(and/auth). - Widget query params are
filter(list and collection tables),sort
(-fieldfor descending),page,perPage, anddb(/w/collections,
/w/graphs,/w/sql;databaseis accepted as an alias on the SQL
console), plusstatus/collectionfor webhook logs.action=create
opens the create dialog on a list page (or the record form on a collection),
andaction=runopens the run dialog in the pipeline editor./w/sqlalso
takessqlto pre-fill the query andexecute=trueto run it on load and
show the results, so an agent can hand over a query and its outcome in one
link. Links stay inside/w, and the surface name is the document title,
so the browser tab identifies the widget. - The widget gains no leftover dashboard space: the SQL results modal fills
the viewport instead of leaving the sidebar's column, and the pipeline
canvas drops React Flow's minimap (it duplicated the canvas and took room
from the step palette). - The Harness Account panel gains Open dashboard:
Vski.dashboard
(GET /api/vski/connections/:id/dashboard) builds a one-shot/connect
URL signed with the selected slot's bearer token and opens it externally.
An API-key slot yields a URL without a token, because the dashboard cannot
be signed in with one.
Signal approvals
A run parked on a signal is a human decision waiting to happen, so the
dashboard treats it as a first-class surface./signals(and the/w/signalswidget) lists every waiting signal across
the deployment: pipelinesignalsteps and code workflows parked in
waitForSignal. Plugin-managed pipeline steps also park on a signal, but
that is the plugin's wake-up, so the inbox hides it.- Each entry renders approve or reject with an optional reason and records
the signed-in admin asby. Delivery uses a single-use workflow hook:
create it with a random token,POST /api/workflows/hooks/:token(emits
signal_receivedand requeues the run), then delete the hook. The payload
is{ ok, by, reason?, signalId? }. The run page renders the same form
above its timeline. - A wait can carry a description:
descriptionon a pipelinesignal
step, or the option onwaitForSignal/wait_for_signal. It is rendered
with the run context when the step parks and carried in thesignal_waiting
payload, so the inbox and the run say what is being approved. Rendering is
best-effort: an unresolved template path is kept as written rather than
failing the run. The pipeline builder edits it in the signal step inspector. - Harness automation notifications carry the prompt as their body ahead of
the run reference, andGET /repos/:name/signalsreturns it as
description.
Tests and docs
- A new end-to-end suite covers definition storage, encrypted accounts, the
authenticated proxy, a pipeline step with a templated account, stored
secret references, and rejection of hosts outside the allow-list. - The connector engine and pipeline step have unit coverage for auth
scheme application, OAuth refresh, stored secret resolution, templating,
non-2xx failures, and host rejection. - Managed providers were validated end to end: Google over OAuth and
Atlassian over one account token serving both Confluence and Jira. - Executor tests cover the signal description payload and its
unresolved-template fallback; harness tests cover the description reaching
Signal.Pendingand the notification body. - The approval flow was validated against a running deployment: a parked
pipeline run and awaitForSignalrun both appear in the inbox, a response
writessignal_receivedwith{ok, by, reason, signalId}, the run resumes
and completes, and the single-use hook is gone afterwards. Every widget
route was opened against a running deployment — tables, editors, and config
pages — checking for the compressed header, no sidebar or connection badge,
the surface title in the tab, the filter andactionparams, and links that
stay under/w; the normal routes were checked unchanged. - The wiki gains a Connectors page linked from the sidebar, and the IaC and
Pipelines pages document the new kinds and step. The Workflows and Pipelines
pages document signal descriptions.
Downloads
-
Source code (ZIP)
0 downloads
-
Source code (TAR.GZ)
0 downloads
- Four system collections (