@slicervm/sdk 0.1.6 → 0.1.8

package/dist/index.d.ts

@@ -27,6 +27,15 @@ interface VMInfo {
     status?: string;
     persistent?: boolean;
 }
+/**
+ * Per-launch network policy override for isolated host groups.
+ * Omitted lists inherit the host group's policy. Empty lists intentionally
+ * clear that list for this VM launch.
+ */
+interface CreateVMNetworkPolicy {
+    allow?: string[];
+    drop?: string[];
+}
 interface CreateVMRequest {
     ramBytes?: number;
     cpus?: number;
@@ -39,6 +48,7 @@ interface CreateVMRequest {
     ip?: string;
     tags?: string[];
     secrets?: string[];
+    network?: CreateVMNetworkPolicy;
 }
 interface CreateVMResponse {
     hostname: string;
@@ -53,6 +63,7 @@ interface AgentHealth {
     agentVersion?: string;
     systemUptime?: number;
     userdataRan?: boolean;
+    userdataExitCode?: number;
 }
 interface VMLogs {
     hostname: string;
@@ -267,6 +278,91 @@ interface FSWatchEvent {
 interface ShutdownRequest {
     action?: 'shutdown' | 'reboot';
 }
+interface VMCommitOptions {
+    tags?: string[];
+    labels?: Record<string, string>;
+    cacheKey?: string;
+}
+interface VMCommitResponse {
+    hostname: string;
+    commitId: string;
+    status: string;
+    parentStatus?: string;
+    mode: string;
+    tags?: string[];
+    labels?: Record<string, string>;
+    cacheKey?: string;
+}
+interface VMCommitListOptions {
+    tags?: string[];
+    cacheKey?: string;
+    source?: string;
+    mode?: string;
+}
+interface VMCommitInfo {
+    commitId: string;
+    sourceHostname: string;
+    sourceHostGroup: string;
+    createdAt: string;
+    mode: string;
+    tags?: string[];
+    labels?: Record<string, string>;
+    cacheKey?: string;
+}
+interface VMCommitDeleteResponse {
+    commitId: string;
+    status: string;
+}
+/** Isolated-network policy override for a forked VM. */
+interface VMForkNetworkPolicy {
+    /** Omit to inherit; pass an empty array to clear the allow list. */
+    allow?: string[];
+    /** Omit to inherit; pass an empty array to clear the drop list. */
+    drop?: string[];
+}
+interface VMForkOptions {
+    /** Agent-readiness timeout in seconds. Forks always wait for the child agent. */
+    waitTimeoutSec?: number;
+    network?: VMForkNetworkPolicy;
+    tags?: string[];
+}
+interface VMForkResponse {
+    hostname: string;
+    sourceHostname: string;
+    commitId?: string;
+    status: string;
+    parentStatus?: string;
+    childStatus?: string;
+    mode: string;
+}
+interface VMNetworkPolicy {
+    allow: string[];
+    drop: string[];
+}
+interface VMNetworkDescription {
+    mode?: string;
+    policySource?: string;
+    hostGroup: VMNetworkPolicy;
+    override?: CreateVMNetworkPolicy;
+    effective: VMNetworkPolicy;
+}
+interface VMDescription {
+    hostname: string;
+    hostGroup?: string;
+    ip?: string;
+    ramBytes?: number;
+    cpus?: number;
+    createdAt?: string;
+    arch?: string;
+    tags?: string[];
+    status?: string;
+    persistent?: boolean;
+    storage?: string;
+    image?: string;
+    commitId?: string;
+    parentCommitId?: string;
+    network: VMNetworkDescription;
+}
 interface VMStat {
     hostname: string;
     ip: string;
@@ -534,6 +630,21 @@ interface VMInit {
     createdAt?: string;
     arch?: string;
 }
+declare class CommittedVM {
+    private readonly transport;
+    readonly hostname: string;
+    readonly hostGroup: string;
+    readonly commitId: string;
+    readonly status: string;
+    readonly parentStatus?: string;
+    readonly mode: VMCommitResponse['mode'];
+    readonly tags?: string[];
+    readonly labels?: Record<string, string>;
+    readonly cacheKey?: string;
+    constructor(transport: TransportClient, hostGroup: string, response: VMCommitResponse);
+    fork(opts?: VMForkOptions): Promise<VM>;
+    forkRaw(opts?: VMForkOptions): Promise<VMForkResponse>;
+}
 declare class VM {
     readonly hostname: string;
     readonly hostGroup: string;
@@ -547,6 +658,8 @@ declare class VM {
     delete(): Promise<void>;
     health(): Promise<AgentHealth>;
     logs(): Promise<VMLogs>;
+    /** Return configuration, fork lineage, and effective network policy. */
+    describe(): Promise<VMDescription>;
     waitForAgent(opts?: WaitOptions): Promise<AgentHealth>;
     waitForUserdata(opts?: WaitOptions): Promise<AgentHealth>;
     shutdown(req?: ShutdownRequest): Promise<void>;
@@ -557,6 +670,10 @@ declare class VM {
     suspend(): Promise<void>;
     /** Mac-only on current daemons. Throws `SlicerAPIError 404` on Linux. */
     restore(): Promise<void>;
+    /**
+     * Commit a stopped persistent VM disk into an immutable parent.
+     */
+    commit(opts?: VMCommitOptions): Promise<CommittedVM>;
     /**
      * Open one or more port forwards from the host to this VM. Each spec follows
      * the same syntax as `slicer vm forward -L`:
@@ -644,7 +761,7 @@ declare class VMBg {
 }
 
 /**
- * Top-level namespaces on SlicerClient: hostGroups, vms, secrets.
+ * Top-level namespaces on SlicerClient: hostGroups, vms, commits, secrets.
  * Keep control-plane operations here; per-VM operations live on the VM handle.
  */
 
@@ -676,6 +793,13 @@ declare class VMsAPI {
      */
     createRaw(hostGroup: string, req?: CreateVMRequest, opts?: CreateVMOptions): Promise<CreateVMResponse>;
 }
+declare class CommitsAPI {
+    private readonly transport;
+    constructor(transport: TransportClient);
+    list(opts?: VMCommitListOptions): Promise<VMCommitInfo[]>;
+    delete(commitId: string): Promise<VMCommitDeleteResponse>;
+    fork(commitId: string, opts?: VMForkOptions): Promise<VMForkResponse>;
+}
 declare class SecretsAPI {
     private readonly transport;
     constructor(transport: TransportClient);
@@ -685,18 +809,202 @@ declare class SecretsAPI {
     delete(name: string): Promise<void>;
 }
 
+/**
+ * Slicer egress-proxy admin API.
+ *
+ * Three resources:
+ *   - clients: opaque token holders. Each VM (or other consumer) presents
+ *     the token via HTTPS_PROXY; the proxy resolves it to the client and
+ *     walks the client's allow rules.
+ *   - secrets: upstream credentials (bearer or basic). When an allow rule
+ *     references a secret, the proxy strips the client's Authorization on
+ *     the inner request and substitutes the secret's value.
+ *   - allow rules: per-client. host (exact, *.suffix wildcard, or "*"),
+ *     optional method/path filters, optional secret reference, optional
+ *     TTL, optional `passthrough` (TCP-splice CONNECT, no MITM).
+ *
+ * Calls go through slicerd's `/proxy/v1/*` broker (the same transport
+ * SlicerClient already uses for every other API), so no extra
+ * configuration is needed beyond a working SlicerClient.
+ *
+ * Wire shapes mirror the Go SDK at github.com/slicervm/sdk/proxy.go.
+ * Field-name conversion (snake_case ↔ camelCase) is handled in the
+ * `*FromWire` / `*ToWire` helpers; user-facing types are camelCase.
+ */
+
+/** Credential type for upstream injection. */
+type ProxySecretType = 'bearer' | 'basic' | 'oauth-client-creds';
+declare const ProxySecretBearer: ProxySecretType;
+/** For basic auth, the secret value must be in `user:pass` form. */
+declare const ProxySecretBasic: ProxySecretType;
+/** OAuth 2.0 client credentials exchanged and renewed by the proxy host. */
+declare const ProxySecretOAuthClientCredentials: ProxySecretType;
+/** A registered proxy client. Tokens are never returned by list/get. */
+interface ProxyClient {
+    name: string;
+    /** RFC 3339 timestamp. */
+    createdAt: string;
+}
+/**
+ * Returned only by `clients.create`. The token is shown once and never
+ * surfaced by any other endpoint — store it now or rotate the client.
+ */
+interface ProxyClientCreated {
+    name: string;
+    token: string;
+    createdAt: string;
+}
+/**
+ * Optional input to `clients.create`. Pass `token` to bring your own
+ * literal (handy for demos and reproducible tests); omit for a
+ * server-minted high-entropy `spt_…` token (recommended).
+ */
+interface CreateProxyClientOptions {
+    token?: string;
+}
+/** A registered upstream credential. `value` is never returned. */
+interface ProxySecret {
+    name: string;
+    host: string;
+    /** Defaults to `bearer` when empty in older state files. */
+    type?: ProxySecretType;
+    createdAt: string;
+}
+interface CreateProxySecretRequest {
+    name: string;
+    host: string;
+    /** Defaults to `bearer` when omitted. */
+    type?: ProxySecretType;
+    /**
+     * Plaintext credential. For `bearer`, the raw token. For `basic`,
+     * must be in `user:pass` form (the proxy base64-encodes it on the
+     * inner request). For `oauth-client-creds`, pass top-level JSON containing
+     * `token_endpoint`, `client_id`, and `client_secret`; optional `scope` is
+     * supported. The proxy obtains, caches, and renews the bearer host-side.
+     */
+    value: string;
+}
+/**
+ * Per-client allow entry. First-match-wins by declaration order.
+ *
+ * - When `secret` is set, the proxy strips the client's Authorization
+ *   on the inner request and substitutes the secret's value.
+ * - `methods`/`paths` are optional filters (any-of within each list,
+ *   all-of across lists). Empty list = any.
+ * - When `passthrough` is true, the proxy splices TCP both ways at
+ *   CONNECT without terminating TLS. Cert-pinned clients work
+ *   unchanged. Mutually exclusive with `secret`, `methods`, `paths`;
+ *   the admin API rejects rules that combine them.
+ */
+interface ProxyAllowRule {
+    host: string;
+    secret?: string;
+    methods?: string[];
+    paths?: string[];
+    /** RFC 3339 timestamp; absent / zero-value when no expiry. */
+    expires?: string;
+    passthrough?: boolean;
+}
+/** Input to `allows.add`. */
+interface AddProxyAllowRequest {
+    client: string;
+    host: string;
+    secret?: string;
+    methods?: string[];
+    paths?: string[];
+    /**
+     * Time-to-live in seconds. 0 / omitted = never expires. Resolved to
+     * an absolute `expires` timestamp on the returned rule.
+     */
+    ttlSeconds?: number;
+    /** See ProxyAllowRule.passthrough. Mutually exclusive with secret/methods/paths. */
+    passthrough?: boolean;
+}
+/**
+ * Input to `allows.removeByTuple`. Mirrors the create payload minus
+ * `ttlSeconds` (TTL is mutable lifetime, not part of identity). The
+ * proxy matches the rule by (host, methods, paths, passthrough) and
+ * removes the single matching rule. Use when several rules share a
+ * host and you want surgical removal of one — pass exactly the same
+ * fields you used at create time.
+ */
+interface RemoveProxyAllowByTupleRequest {
+    client: string;
+    host: string;
+    secret?: string;
+    methods?: string[];
+    paths?: string[];
+    passthrough?: boolean;
+}
+declare class ProxyAPI {
+    private readonly transport;
+    readonly clients: ProxyClientsAPI;
+    readonly secrets: ProxySecretsAPI;
+    readonly allows: ProxyAllowsAPI;
+    constructor(transport: TransportClient);
+}
+declare class ProxyClientsAPI {
+    private readonly transport;
+    constructor(transport: TransportClient);
+    /** Mint a new proxy client. The returned token is shown once. */
+    create(name: string, opts?: CreateProxyClientOptions): Promise<ProxyClientCreated>;
+    list(): Promise<ProxyClient[]>;
+    /**
+     * Revoke the token, drop every allow rule the client owned, and
+     * remove the client.
+     */
+    delete(name: string): Promise<void>;
+    /** List a client's allow rules in declaration order (first-match-wins). */
+    rules(name: string): Promise<ProxyAllowRule[]>;
+}
+declare class ProxySecretsAPI {
+    private readonly transport;
+    constructor(transport: TransportClient);
+    create(req: CreateProxySecretRequest): Promise<void>;
+    list(): Promise<ProxySecret[]>;
+    /**
+     * Remove a secret. Allow rules that reference it stop matching until
+     * the secret is recreated or the rule is rewritten.
+     */
+    delete(name: string): Promise<void>;
+}
+declare class ProxyAllowsAPI {
+    private readonly transport;
+    constructor(transport: TransportClient);
+    /** Add an allow rule. Returns the resolved rule with absolute `expires`. */
+    add(req: AddProxyAllowRequest): Promise<ProxyAllowRule>;
+    /**
+     * Host-bulk revoke: removes **every** rule on the client whose host
+     * matches. For surgical removal of one rule among siblings on the
+     * same host (e.g. several path-scoped rules on `github.com`), use
+     * `removeByTuple` instead.
+     */
+    remove(client: string, host: string): Promise<void>;
+    /**
+     * Surgical revoke: removes the single rule whose
+     * (host, methods, paths, passthrough) tuple matches the request.
+     * Pass exactly the same fields you used at create time. Method and
+     * host casing are normalised server-side, so `"GET"` / `"get"` and
+     * `"github.com"` / `"GITHUB.COM"` all match the same stored rule.
+     *
+     * Returns 404 (surfaced as a SlicerAPIError) when no rule matches.
+     */
+    removeByTuple(req: RemoveProxyAllowByTupleRequest): Promise<void>;
+}
+
 /**
  * SlicerClient — grouped TypeScript client for the Slicer VM API.
  *
  * Shape:
  *   client.hostGroups.list() / find(name) / listVMs(name)
  *   client.vms.create(group, req, opts) → VM / get(name) / list() / stats() / attach(group, name)
+ *   client.commits.list() / fork(id) / delete(id)
  *   client.secrets.list / create / patch / delete
  *   client.getInfo()
  *
  * Per-VM operations live on the `VM` handle returned from `client.vms.create`
  * or `client.vms.attach`: `vm.exec`, `vm.execBuffered`, `vm.fs.*`,
- * `vm.pause/resume/suspend/restore/shutdown/relaunch`, `vm.health/logs`,
+ * `vm.pause/resume/suspend/restore/shutdown/relaunch`, `vm.commit/describe`, `vm.health/logs`,
  * `vm.waitForAgent/waitForUserdata`, `vm.delete`.
  */
 
@@ -706,7 +1014,9 @@ declare class SlicerClient {
     readonly transport: TransportClient;
     readonly hostGroups: HostGroupsAPI;
     readonly vms: VMsAPI;
+    readonly commits: CommitsAPI;
     readonly secrets: SecretsAPI;
+    readonly proxy: ProxyAPI;
     constructor(opts: SlicerClientOptions);
     static fromEnv(overrides?: Partial<SlicerClientOptions>): SlicerClient;
     getInfo(): Promise<SlicerInfo>;
@@ -778,4 +1088,4 @@ declare class SlicerShellSession {
     private teardown;
 }
 
-export { type AddressMapping, type AgentHealth, type BgDeleteResponse, type BgExecInfo, type BgExecRequest, type BgExecResponse, type BgKillOptions, type BgKillResponse, type BgLogOptions, type BgWaitExitResponse, type CreateSecretRequest, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, FRAME_TYPE_DATA, FRAME_TYPE_HEARTBEAT, FRAME_TYPE_SESSION_CLOSE, FRAME_TYPE_SHUTDOWN, FRAME_TYPE_WINDOW_SIZE, type FSEntry, type FSMkdirRequest, type FSWatchEvent, type FSWatchEventType, type FSWatchRequest, Forwarder, type ForwarderListener, type ForwarderOptions, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, type Secret, SecretExistsError, SecretsAPI, type ShellSessionOptions, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, SlicerShellSession, type UpdateSecretRequest, VM, VMBg, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, type XTermLike, encodeFrame, parseAddressMapping, parseFrame, resolveTransport };
+export { type AddProxyAllowRequest, type AddressMapping, type AgentHealth, type BgDeleteResponse, type BgExecInfo, type BgExecRequest, type BgExecResponse, type BgKillOptions, type BgKillResponse, type BgLogOptions, type BgWaitExitResponse, CommitsAPI, CommittedVM, type CreateProxyClientOptions, type CreateProxySecretRequest, type CreateSecretRequest, type CreateVMNetworkPolicy, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, FRAME_TYPE_DATA, FRAME_TYPE_HEARTBEAT, FRAME_TYPE_SESSION_CLOSE, FRAME_TYPE_SHUTDOWN, FRAME_TYPE_WINDOW_SIZE, type FSEntry, type FSMkdirRequest, type FSWatchEvent, type FSWatchEventType, type FSWatchRequest, Forwarder, type ForwarderListener, type ForwarderOptions, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, ProxyAPI, type ProxyAllowRule, ProxyAllowsAPI, type ProxyClient, type ProxyClientCreated, ProxyClientsAPI, type ProxySecret, ProxySecretBasic, ProxySecretBearer, ProxySecretOAuthClientCredentials, type ProxySecretType, ProxySecretsAPI, type RemoveProxyAllowByTupleRequest, type Secret, SecretExistsError, SecretsAPI, type ShellSessionOptions, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, SlicerShellSession, type UpdateSecretRequest, VM, VMBg, type VMCommitDeleteResponse, type VMCommitInfo, type VMCommitListOptions, type VMCommitOptions, type VMCommitResponse, type VMDescription, VMFileSystem, type VMForkNetworkPolicy, type VMForkOptions, type VMForkResponse, type VMInfo, type VMInit, type VMLogs, type VMNetworkDescription, type VMNetworkPolicy, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, type XTermLike, encodeFrame, parseAddressMapping, parseFrame, resolveTransport };