Skip to content

VSKI v0.18.0

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/sdk 2.11.0 and vski-sdk 0.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 connectorDefinitions before connectors; vski apply already orders definitions first.
  • OAuth providers need <server>/api/connectors/oauth/callback as their registered callback. Set PUBLIC_URL when 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 the workflows role; admins also pass.

connectorDefinitions and connectors are global IaC kinds. vski plan, vski apply, and vski pull round-trip them, with definitions applied before connectors. vski pull writes connector-definitions.yaml and 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-form metadata.

api.baseUrl and api.allowedHosts accept {field} placeholders filled from connect-time values, so one definition can target per-account sites without giving up the host allow-list. api.readOnly rejects every method except GET and HEAD.

Auth schemes cover bearer, header, query, basic, and none. A custom-header connector declares its api.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.

  • 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 enables refresh.
  • 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, and headerSecrets name 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 gain a connector step. It resolves account, path, url, headers, and body as templates, attaches the account credential server-side, and returns {status, headers, body}. Non-2xx provider responses fail the step so the usual retries and onError behavior 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 account is 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}/request with an API key that carries the workflows role. The proxy applies the stored credential, enforces the host allow-list, and returns the provider status, headers, and body. The proxy call itself answers 200; a provider rejection is reported in status, and transport or configuration failures return 4xx or 5xx with the reason.

A connector is bound to its declared hosts. Only api.allowedHosts entries 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/....

  • 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/sdk 2.11.0 adds client.connectors with definitions, configs, accounts, OAuth start, and the request proxy.
  • Python vski-sdk 0.20.0 adds client.connectors and IaC loading, diffing, applying, and pulling for both connector kinds. The synchronous client exposes the same namespace.

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 to path. 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, next stays dashboard-relative, and a stale saved API key is cleared: the dashboard’s admin endpoints reject API keys and X-API-Key is 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 (-field for descending), page, perPage, and db (/w/collections, /w/graphs, /w/sql; database is accepted as an alias on the SQL console), plus status/collection for webhook logs. action=create opens the create dialog on a list page (or the record form on a collection), and action=run opens the run dialog in the pipeline editor. /w/sql also takes sql to pre-fill the query and execute=true to 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.

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/signals widget) lists every waiting signal across the deployment: pipeline signal steps 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 as by. Delivery uses a single-use workflow hook: create it with a random token, POST /api/workflows/hooks/:token (emits signal_received and 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: description on a pipeline signal step, or the option on waitForSignal / wait_for_signal. It is rendered with the run context when the step parks and carried in the signal_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, and GET /repos/:name/signals returns it as description.
  • 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.Pending and the notification body.
  • The approval flow was validated against a running deployment: a parked pipeline run and a waitForSignal run both appear in the inbox, a response writes signal_received with {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 and action params, 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.