@voltius/plugin-types 0.20.0 → 0.21.1

package/index.d.ts

@@ -165,6 +165,52 @@ export interface PluginIdentity {
   tags: string[];
 }
 
+/** A vault the user organizes objects into. Unrelated to `api.vault`, which is plugin storage. */
+export interface PluginVault {
+  id: string;
+  name: string;
+  /** Backed by a team; every write verb refuses it. */
+  team: boolean;
+}
+
+/** The four folder trees the app has. One `keychain` tree holds keys AND identities. */
+export type PluginFolderKind = "connection" | "keychain" | "port_forwarding" | "snippet";
+
+export interface PluginFolder {
+  id: string;
+  name: string;
+  kind: PluginFolderKind;
+  vaultId: string;
+  parentFolderId: string | null;
+  team: boolean;
+}
+
+/**
+ * One relocation of vault objects: the same operation a cut/copy + paste is on
+ * the page, so the ids must all belong to one tab (hosts, keychain, port
+ * forwarding or snippets). Folder ids may travel with them, contents included.
+ */
+export interface PluginObjectMoveInput {
+  ids: string[];
+  /** Destination folder, or null for the destination vault's root. */
+  folderId: string | null;
+  /** Destination vault. null keeps every object in the vault it has. */
+  vaultId: string | null;
+  /**
+   * Authorizes a destination vault other than the objects' own. Without it a
+   * crossing is refused before anything is written, and the refusal carries the
+   * plan — how many objects, which vault, and what would travel with them.
+   */
+  allowCrossVault?: boolean;
+}
+
+export interface PluginObjectMoveOutcome {
+  moved: number;
+  created: number;
+  /** Ids that no longer exist, or objects already where the call would put them. */
+  skipped: number;
+}
+
 export interface OmniCommand {
   id: string;
   label: string;
@@ -544,6 +590,35 @@ export interface DockerAPI {
   };
 }
 
+export interface ReachPortRequest {
+  sessionId: string;
+  isRemote: boolean;
+  /** Published host port on the Docker host. */
+  hostPort: number;
+  /** The publish's bind address; wildcard binds collapse to loopback. */
+  hostIp?: string | null;
+  scheme?: "http" | "https";
+  action: "browser" | "copy";
+}
+
+export interface ReachPortResponse {
+  /** Full URL for "browser", bare host:port for "copy". */
+  address: string;
+  localPort: number;
+  /** True when this call opened a new tunnel (as opposed to reusing or not needing one). */
+  tunneled: boolean;
+}
+
+/**
+ * GATED (ports:forward). One verb: make a published port reachable from this
+ * machine and act on it. Deliberately host-executed — a plugin never receives a
+ * raw URL-opener or raw tunnel control, both of which are larger grants than
+ * this needs.
+ */
+export interface PortsAPI {
+  reach(req: ReachPortRequest): Promise<ReachPortResponse>;
+}
+
 /** A local audit row, projected. Drops the internal id, actor id, team/vault
  *  ids and IP — none of which a plugin or an external client has any use for. */
 export interface PluginAuditRow {
@@ -602,6 +677,9 @@ export interface PluginAPI {
     /** Creates a key entry and stores private/public content in the vault. */
     create(data: { name?: string; key_type?: string; tags?: string[] }, privateKey: string, publicKey?: string): Promise<PluginKey>;
     delete(id: string): Promise<void>;
+    /** Appends the key's public half to a connection's authorized_keys over SSH.
+     *  Requires keys:read and connections:read. Never accepts a script. */
+    addToHost(input: { keyId: string; connectionId: string; location?: string; filename?: string }): Promise<void>;
   };
 
   // Identities (requires identities:*)
@@ -629,6 +707,48 @@ export interface PluginAPI {
     subscribe(cb: (connections: PluginConnection[]) => void): () => void;
   };
 
+  // The user's vaults (requires the gated vaults:*). Note the plural: `vault`
+  // below is this plugin's own secret storage and is a different thing.
+  vaults: {
+    list(): PluginVault[];
+    create(name: string): PluginVault;
+    /** Rejects a team vault. */
+    rename(id: string, name: string): void;
+    /**
+     * Rejects the personal vault, a team vault, and a vault that still holds
+     * objects unless `cascade` is passed — in which case its contents are
+     * deleted with it.
+     */
+    delete(id: string, opts?: { cascade?: boolean }): Promise<void>;
+  };
+
+  // Folders across all four trees (requires the gated folders:*)
+  folders: {
+    list(kind?: PluginFolderKind): PluginFolder[];
+    create(input: {
+      kind: PluginFolderKind;
+      name: string;
+      /** Defaults to the personal vault. */
+      vaultId?: string;
+      parentFolderId?: string;
+    }): Promise<PluginFolder>;
+    /** Name only — kind, vault and parent are preserved. Rejects a team vault. */
+    rename(id: string, name: string): Promise<void>;
+    /** Cascades by default. Rejects a team vault. */
+    delete(id: string, opts?: { cascade?: boolean }): Promise<void>;
+  };
+
+  /**
+   * Move and copy vault objects between folders and vaults, through the same
+   * paste path the pages use. Each method requires the write permission of every
+   * kind it names, and folders:write when a folder travels. Team vaults are
+   * refused.
+   */
+  objects: {
+    move(input: PluginObjectMoveInput): Promise<PluginObjectMoveOutcome>;
+    copy(input: PluginObjectMoveInput): Promise<PluginObjectMoveOutcome>;
+  };
+
   // Vault — plugin-scoped secrets (requires vault:*)
   vault: {
     get(key: string): Promise<string | null>;
@@ -815,6 +935,9 @@ export interface PluginAPI {
   // docker:read (list/services/checkUpdate/logs.*) / docker:manage (everything else).
   docker: DockerAPI;
 
+  // Reach a published Docker port from this machine — GATED (ports:forward).
+  ports: PortsAPI;
+
   // Lifecycle hooks (always available)
   lifecycle: {
     /** Fires when an SSH/local session transitions to "connected". */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltius/plugin-types",
-  "version": "0.20.0",
+  "version": "0.21.1",
   "description": "TypeScript definitions for the Voltius plugin API",
   "types": "index.d.ts",
   "files": [