• v0.18.0 929e559150

    v0.18.0 Stable

    x released this 2026-11-15 17:34:34 +00:00 | 3 commits to main since this release

    VSKI 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/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.

    Definitions and IaC

    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.

    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 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, plugins, and triggers

    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/....

    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/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.

    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 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.

    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/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.

    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.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.
    Downloads