@krovacloud/sdk 0.3.9 → 0.3.11

package/README.md

@@ -49,6 +49,14 @@ const cube = await krova.cubes.create("space_123", {
 console.log(`Created cube ${cube.id} (${cube.state})`);
 console.log(`  ${cube.resources.vcpu} vCPU / ${cube.resources.ramGb} GB RAM, image ${cube.image}`);
 
+// Everything needed to SSH in — including WHICH USER to log in as.
+// Read `user`; do not derive it from `image`. It is "ubuntu" or "debian" on
+// Cubes from images that ship a default user (both with passwordless sudo)
+// and "root" on Cubes created before that change, so the image id cannot
+// tell you. `cube.sshUser` on the Cube object carries the same value.
+const ssh = await krova.cubes.ssh("space_123", cube.id);
+console.log(`ssh ${ssh.user}@${ssh.host} -p ${ssh.port}`);
+
 // Power it off, then start it again
 await krova.cubes.powerOff("space_123", cube.id);
 await krova.cubes.wake("space_123", cube.id);
@@ -120,7 +128,7 @@ const cube = await krova.cubes.create(
     image: "ubuntu-24.04",
     resources: { vcpu: 2, ramGb: 4, diskGb: 40 },
     sshPublicKey: "ssh-ed25519 AAAA... you@host",
-    region: "us-east",           // optional — slug from catalog.regions()
+    region: "us",                // optional — slug from catalog.regions()
     userData: "#cloud-config\n",  // optional — cloud-init (max 16 KB)
   },
   { idempotencyKey: "deploy-2026-07-01" },
@@ -301,6 +309,34 @@ The package ships its own type declarations — no `@types/*` install needed. `C
 
 See [CONTRIBUTING.md](https://github.com/krovacloud/krova-node/blob/main/CONTRIBUTING.md). Report security issues privately per [SECURITY.md](https://github.com/krovacloud/krova-node/blob/main/SECURITY.md).
 
+
+## Custom domains: HTTPS to the Cube
+
+By default the edge reaches your Cube over cleartext HTTP — visitors are on
+HTTPS either way, since TLS terminates at the edge. Set `originScheme: "https"`
+when the Cube terminates TLS *itself*: a control panel holding its own
+certificate, or an app listening on HTTPS, answers plain HTTP with a redirect
+and cannot be served over cleartext at all.
+
+```ts
+// When attaching the domain…
+await krova.domains.create(spaceId, cubeId, {
+  domain: "panel.example.com",
+  port: 443,
+  originScheme: "https",
+});
+
+// …or switch an already-attached domain over.
+await krova.domains.update(spaceId, cubeId, mappingId, {
+  originScheme: "https",
+});
+```
+
+The dial port is derived: `https` on the default port 80 connects on 443, and a
+deliberate custom port is honoured exactly. The setting is verified against the
+Cube before it is applied — if the domain does not serve, the route is left on
+`http`.
+
 ## License
 
 [MIT](./LICENSE) © 2026 Krova Inc.

package/dist/index.d.cts

@@ -366,7 +366,7 @@ interface paths {
                             ramGb: number;
                             diskGb: number;
                         };
-                        /** @description SSH public key written to /root/.ssh/authorized_keys at boot. Must start with ssh-ed25519, ssh-rsa, ecdsa-sha2-*, ssh-dss, or sk-*@openssh.com. */
+                        /** @description SSH public key written to the Cube login user's authorized_keys at boot (~/.ssh/authorized_keys for the ubuntu or debian user; /root/.ssh/authorized_keys on Cubes created before the default-user change). GET /cubes/{cubeId}/ssh reports the login user for a given Cube. Must start with ssh-ed25519, ssh-rsa, ecdsa-sha2-*, ssh-dss, or sk-*@openssh.com. */
                         sshPublicKey: string;
                         /** @description Region slug from /v1/regions (optional). */
                         region?: string;
@@ -557,7 +557,7 @@ interface paths {
         put?: never;
         /**
          * Restart a running Cube
-         * @description Cold-restarts the Cube: the hypervisor process is stopped and relaunched, so the Cube boots against the host's current kernel. This is how a Cube picks up a refreshed guest kernel after a platform image update — a `reboot` issued inside the Cube cannot do it, because the kernel is supplied externally by the host. Disk state is preserved; only the kernel changes. The Cube must be `running` (a stopped Cube already picks up the latest kernel when started). Concurrent restarts of the same Cube are rejected with 409 rather than queued twice.
+         * @description Cold-restarts the Cube: the hypervisor process is stopped and relaunched, so the Cube boots against the host's current kernel. This is how a Cube picks up a refreshed guest kernel after a platform image update — a `reboot` issued inside the Cube cannot do it, because the kernel is supplied externally by the host. Disk state is preserved; only the kernel changes. Cube must be `running` (a stopped Cube already picks up the latest kernel when started). Concurrent restarts of the same Cube are rejected with 409 rather than queued twice.
          */
         post: {
             parameters: {
@@ -654,7 +654,7 @@ interface paths {
         };
         /**
          * Get a Cube's SSH connection info
-         * @description Host (server public IPv4), host SSH port, login user, and any captured SSH host public keys. `hostKeys` is empty until Krova captures cube host keys — clients fall back to trust-on-first-use until then.
+         * @description Host (server public IPv4), host SSH port, login user, and the Cube's captured SSH host public keys. **Use `user` rather than assuming a username** — it is `ubuntu` or `debian` on Cubes created from images that ship a default user, and `root` on Cubes created before that change or imported from a rootfs without one. `hostKeys` is empty only until the reachability cron makes its first capture; clients fall back to trust-on-first-use until then, and pin strictly afterwards.
          */
         get: {
             parameters: {
@@ -744,7 +744,7 @@ interface paths {
                     "application/json": {
                         /** @description The hostname to attach, e.g. app.example.com */
                         domain: string;
-                        /** @description The Cube port the domain proxies to. */
+                        /** @description Cube port the domain proxies to. */
                         port: number;
                         /**
                          * @description enforced = proxy sets platform security headers (HSTS, X-Frame-Options, …); app_managed = the app's own headers pass through. Default enforced.
@@ -769,6 +769,26 @@ interface paths {
                         } | null;
                         /** @description Max request body size (MB). Null = unlimited (default). */
                         maxRequestBodyMb?: number | null;
+                        /** @description Per-domain CORS policy, applied at the edge. Null (default) = CORS disabled and no Access-Control-* header is emitted anywhere. When set, the proxy answers OPTIONS preflight itself (204, the cube is never involved) and adds the headers to normal AND error responses, so a cross-origin request to a failing or sleeping cube is never CORS-masked. */
+                        corsConfig?: {
+                            /** @description Exact scheme://host[:port] origins (no path, query or trailing slash), or the single-element wildcard ["*"]. "*" and allowCredentials are mutually exclusive. */
+                            allowedOrigins: string[];
+                            /** @description Allowed methods. Omitted = GET, POST, PUT, PATCH, DELETE, OPTIONS. */
+                            allowedMethods?: string[];
+                            /** @description Allowed request headers. Omitted/empty = echo the preflight's Access-Control-Request-Headers. */
+                            allowedHeaders?: string[];
+                            /** @description Response headers exposed to JS. Omitted/empty = none. */
+                            exposedHeaders?: string[];
+                            /** @description Send Access-Control-Allow-Credentials: true. Rejected together with the "*" origin. */
+                            allowCredentials?: boolean;
+                            /** @description Preflight cache TTL. Default 600; 86400 is Chromium's hard cap. */
+                            maxAgeSeconds?: number;
+                        } | null;
+                        /**
+                         * @description Scheme the edge speaks to the CUBE on the backend hop. http (default) = cleartext. https = the cube terminates TLS itself (a control panel holding its own certificate, or an app listening on HTTPS) and answers plain HTTP with a redirect, so it cannot be reached over cleartext at all. Visitors are on HTTPS either way. The dial port is derived: https on the default port 80 connects on 443; a deliberate custom port is honoured exactly. Verified against the cube before it is applied — if the domain does not serve, the route is left on http.
+                         * @enum {string}
+                         */
+                        originScheme?: "http" | "https";
                         /** @description Edge gzip/zstd compression. Default false (domains behind a CDN are already compressed there). */
                         responseCompression?: boolean;
                         /** @description Visitor IP/CIDR allow-list (v4+v6). Non-empty ⇒ only these reach the app. Null/empty = open. */
@@ -885,6 +905,26 @@ interface paths {
                         } | null;
                         /** @description Max request body size (MB). Null = unlimited (default). */
                         maxRequestBodyMb?: number | null;
+                        /** @description Per-domain CORS policy, applied at the edge. Null (default) = CORS disabled and no Access-Control-* header is emitted anywhere. When set, the proxy answers OPTIONS preflight itself (204, the cube is never involved) and adds the headers to normal AND error responses, so a cross-origin request to a failing or sleeping cube is never CORS-masked. */
+                        corsConfig?: {
+                            /** @description Exact scheme://host[:port] origins (no path, query or trailing slash), or the single-element wildcard ["*"]. "*" and allowCredentials are mutually exclusive. */
+                            allowedOrigins: string[];
+                            /** @description Allowed methods. Omitted = GET, POST, PUT, PATCH, DELETE, OPTIONS. */
+                            allowedMethods?: string[];
+                            /** @description Allowed request headers. Omitted/empty = echo the preflight's Access-Control-Request-Headers. */
+                            allowedHeaders?: string[];
+                            /** @description Response headers exposed to JS. Omitted/empty = none. */
+                            exposedHeaders?: string[];
+                            /** @description Send Access-Control-Allow-Credentials: true. Rejected together with the "*" origin. */
+                            allowCredentials?: boolean;
+                            /** @description Preflight cache TTL. Default 600; 86400 is Chromium's hard cap. */
+                            maxAgeSeconds?: number;
+                        } | null;
+                        /**
+                         * @description Scheme the edge speaks to the CUBE on the backend hop. http (default) = cleartext. https = the cube terminates TLS itself (a control panel holding its own certificate, or an app listening on HTTPS) and answers plain HTTP with a redirect, so it cannot be reached over cleartext at all. Visitors are on HTTPS either way. The dial port is derived: https on the default port 80 connects on 443; a deliberate custom port is honoured exactly. Verified against the cube before it is applied — if the domain does not serve, the route is left on http.
+                         * @enum {string}
+                         */
+                        originScheme?: "http" | "https";
                         /** @description Edge gzip/zstd compression. Default false (domains behind a CDN are already compressed there). */
                         responseCompression?: boolean;
                         /** @description Visitor IP/CIDR allow-list (v4+v6). Non-empty ⇒ only these reach the app. Null/empty = open. */
@@ -1283,10 +1323,12 @@ interface paths {
                         name: string;
                         fileSizeBytes: number;
                         /**
+                         * @description What to do with SSH access on the imported rootfs. `replace` (default) writes `sshPublicKey` to the login user's authorized_keys and requires `sshPublicKey` to be set. `keep` leaves the image's own authorized_keys and sshd configuration completely untouched — nothing is written — so you must already hold a private key that the image accepts, or you will not be able to log in.
                          * @default replace
                          * @enum {string}
                          */
                         sshKeyMode?: "replace" | "keep";
+                        /** @description Public key to install when `sshKeyMode` is `replace`. Written to the login user's `~/.ssh/authorized_keys` — which user that is comes from the imported rootfs itself, so an image without a Krova default user keeps logging in as root. Ignored when `sshKeyMode` is `keep`. */
                         sshPublicKey?: string | null;
                         region?: string | null;
                         vcpusOverride?: number | null;
@@ -1726,6 +1768,7 @@ interface components {
                 diskGb: number;
             };
             image: string;
+            sshUser: string;
             costPerHour: number;
             /** Format: date-time */
             createdAt: string;
@@ -1748,6 +1791,7 @@ interface components {
             name: string;
             version: string;
             description: string;
+            defaultUser: string;
         };
         PricingTier: {
             minVcpus: number;
@@ -1998,6 +2042,7 @@ declare class KrovaClient {
                     diskGb: number;
                 };
                 image: string;
+                sshUser: string;
                 costPerHour: number;
                 createdAt: string;
                 updatedAt: string;
@@ -2189,6 +2234,7 @@ declare class KrovaClient {
                 name: string;
                 version: string;
                 description: string;
+                defaultUser: string;
             }[];
         }>;
         /** Per-resource hourly rates and volume pricing tiers. */

package/dist/index.d.ts

@@ -366,7 +366,7 @@ interface paths {
                             ramGb: number;
                             diskGb: number;
                         };
-                        /** @description SSH public key written to /root/.ssh/authorized_keys at boot. Must start with ssh-ed25519, ssh-rsa, ecdsa-sha2-*, ssh-dss, or sk-*@openssh.com. */
+                        /** @description SSH public key written to the Cube login user's authorized_keys at boot (~/.ssh/authorized_keys for the ubuntu or debian user; /root/.ssh/authorized_keys on Cubes created before the default-user change). GET /cubes/{cubeId}/ssh reports the login user for a given Cube. Must start with ssh-ed25519, ssh-rsa, ecdsa-sha2-*, ssh-dss, or sk-*@openssh.com. */
                         sshPublicKey: string;
                         /** @description Region slug from /v1/regions (optional). */
                         region?: string;
@@ -557,7 +557,7 @@ interface paths {
         put?: never;
         /**
          * Restart a running Cube
-         * @description Cold-restarts the Cube: the hypervisor process is stopped and relaunched, so the Cube boots against the host's current kernel. This is how a Cube picks up a refreshed guest kernel after a platform image update — a `reboot` issued inside the Cube cannot do it, because the kernel is supplied externally by the host. Disk state is preserved; only the kernel changes. The Cube must be `running` (a stopped Cube already picks up the latest kernel when started). Concurrent restarts of the same Cube are rejected with 409 rather than queued twice.
+         * @description Cold-restarts the Cube: the hypervisor process is stopped and relaunched, so the Cube boots against the host's current kernel. This is how a Cube picks up a refreshed guest kernel after a platform image update — a `reboot` issued inside the Cube cannot do it, because the kernel is supplied externally by the host. Disk state is preserved; only the kernel changes. Cube must be `running` (a stopped Cube already picks up the latest kernel when started). Concurrent restarts of the same Cube are rejected with 409 rather than queued twice.
          */
         post: {
             parameters: {
@@ -654,7 +654,7 @@ interface paths {
         };
         /**
          * Get a Cube's SSH connection info
-         * @description Host (server public IPv4), host SSH port, login user, and any captured SSH host public keys. `hostKeys` is empty until Krova captures cube host keys — clients fall back to trust-on-first-use until then.
+         * @description Host (server public IPv4), host SSH port, login user, and the Cube's captured SSH host public keys. **Use `user` rather than assuming a username** — it is `ubuntu` or `debian` on Cubes created from images that ship a default user, and `root` on Cubes created before that change or imported from a rootfs without one. `hostKeys` is empty only until the reachability cron makes its first capture; clients fall back to trust-on-first-use until then, and pin strictly afterwards.
          */
         get: {
             parameters: {
@@ -744,7 +744,7 @@ interface paths {
                     "application/json": {
                         /** @description The hostname to attach, e.g. app.example.com */
                         domain: string;
-                        /** @description The Cube port the domain proxies to. */
+                        /** @description Cube port the domain proxies to. */
                         port: number;
                         /**
                          * @description enforced = proxy sets platform security headers (HSTS, X-Frame-Options, …); app_managed = the app's own headers pass through. Default enforced.
@@ -769,6 +769,26 @@ interface paths {
                         } | null;
                         /** @description Max request body size (MB). Null = unlimited (default). */
                         maxRequestBodyMb?: number | null;
+                        /** @description Per-domain CORS policy, applied at the edge. Null (default) = CORS disabled and no Access-Control-* header is emitted anywhere. When set, the proxy answers OPTIONS preflight itself (204, the cube is never involved) and adds the headers to normal AND error responses, so a cross-origin request to a failing or sleeping cube is never CORS-masked. */
+                        corsConfig?: {
+                            /** @description Exact scheme://host[:port] origins (no path, query or trailing slash), or the single-element wildcard ["*"]. "*" and allowCredentials are mutually exclusive. */
+                            allowedOrigins: string[];
+                            /** @description Allowed methods. Omitted = GET, POST, PUT, PATCH, DELETE, OPTIONS. */
+                            allowedMethods?: string[];
+                            /** @description Allowed request headers. Omitted/empty = echo the preflight's Access-Control-Request-Headers. */
+                            allowedHeaders?: string[];
+                            /** @description Response headers exposed to JS. Omitted/empty = none. */
+                            exposedHeaders?: string[];
+                            /** @description Send Access-Control-Allow-Credentials: true. Rejected together with the "*" origin. */
+                            allowCredentials?: boolean;
+                            /** @description Preflight cache TTL. Default 600; 86400 is Chromium's hard cap. */
+                            maxAgeSeconds?: number;
+                        } | null;
+                        /**
+                         * @description Scheme the edge speaks to the CUBE on the backend hop. http (default) = cleartext. https = the cube terminates TLS itself (a control panel holding its own certificate, or an app listening on HTTPS) and answers plain HTTP with a redirect, so it cannot be reached over cleartext at all. Visitors are on HTTPS either way. The dial port is derived: https on the default port 80 connects on 443; a deliberate custom port is honoured exactly. Verified against the cube before it is applied — if the domain does not serve, the route is left on http.
+                         * @enum {string}
+                         */
+                        originScheme?: "http" | "https";
                         /** @description Edge gzip/zstd compression. Default false (domains behind a CDN are already compressed there). */
                         responseCompression?: boolean;
                         /** @description Visitor IP/CIDR allow-list (v4+v6). Non-empty ⇒ only these reach the app. Null/empty = open. */
@@ -885,6 +905,26 @@ interface paths {
                         } | null;
                         /** @description Max request body size (MB). Null = unlimited (default). */
                         maxRequestBodyMb?: number | null;
+                        /** @description Per-domain CORS policy, applied at the edge. Null (default) = CORS disabled and no Access-Control-* header is emitted anywhere. When set, the proxy answers OPTIONS preflight itself (204, the cube is never involved) and adds the headers to normal AND error responses, so a cross-origin request to a failing or sleeping cube is never CORS-masked. */
+                        corsConfig?: {
+                            /** @description Exact scheme://host[:port] origins (no path, query or trailing slash), or the single-element wildcard ["*"]. "*" and allowCredentials are mutually exclusive. */
+                            allowedOrigins: string[];
+                            /** @description Allowed methods. Omitted = GET, POST, PUT, PATCH, DELETE, OPTIONS. */
+                            allowedMethods?: string[];
+                            /** @description Allowed request headers. Omitted/empty = echo the preflight's Access-Control-Request-Headers. */
+                            allowedHeaders?: string[];
+                            /** @description Response headers exposed to JS. Omitted/empty = none. */
+                            exposedHeaders?: string[];
+                            /** @description Send Access-Control-Allow-Credentials: true. Rejected together with the "*" origin. */
+                            allowCredentials?: boolean;
+                            /** @description Preflight cache TTL. Default 600; 86400 is Chromium's hard cap. */
+                            maxAgeSeconds?: number;
+                        } | null;
+                        /**
+                         * @description Scheme the edge speaks to the CUBE on the backend hop. http (default) = cleartext. https = the cube terminates TLS itself (a control panel holding its own certificate, or an app listening on HTTPS) and answers plain HTTP with a redirect, so it cannot be reached over cleartext at all. Visitors are on HTTPS either way. The dial port is derived: https on the default port 80 connects on 443; a deliberate custom port is honoured exactly. Verified against the cube before it is applied — if the domain does not serve, the route is left on http.
+                         * @enum {string}
+                         */
+                        originScheme?: "http" | "https";
                         /** @description Edge gzip/zstd compression. Default false (domains behind a CDN are already compressed there). */
                         responseCompression?: boolean;
                         /** @description Visitor IP/CIDR allow-list (v4+v6). Non-empty ⇒ only these reach the app. Null/empty = open. */
@@ -1283,10 +1323,12 @@ interface paths {
                         name: string;
                         fileSizeBytes: number;
                         /**
+                         * @description What to do with SSH access on the imported rootfs. `replace` (default) writes `sshPublicKey` to the login user's authorized_keys and requires `sshPublicKey` to be set. `keep` leaves the image's own authorized_keys and sshd configuration completely untouched — nothing is written — so you must already hold a private key that the image accepts, or you will not be able to log in.
                          * @default replace
                          * @enum {string}
                          */
                         sshKeyMode?: "replace" | "keep";
+                        /** @description Public key to install when `sshKeyMode` is `replace`. Written to the login user's `~/.ssh/authorized_keys` — which user that is comes from the imported rootfs itself, so an image without a Krova default user keeps logging in as root. Ignored when `sshKeyMode` is `keep`. */
                         sshPublicKey?: string | null;
                         region?: string | null;
                         vcpusOverride?: number | null;
@@ -1726,6 +1768,7 @@ interface components {
                 diskGb: number;
             };
             image: string;
+            sshUser: string;
             costPerHour: number;
             /** Format: date-time */
             createdAt: string;
@@ -1748,6 +1791,7 @@ interface components {
             name: string;
             version: string;
             description: string;
+            defaultUser: string;
         };
         PricingTier: {
             minVcpus: number;
@@ -1998,6 +2042,7 @@ declare class KrovaClient {
                     diskGb: number;
                 };
                 image: string;
+                sshUser: string;
                 costPerHour: number;
                 createdAt: string;
                 updatedAt: string;
@@ -2189,6 +2234,7 @@ declare class KrovaClient {
                 name: string;
                 version: string;
                 description: string;
+                defaultUser: string;
             }[];
         }>;
         /** Per-resource hourly rates and volume pricing tiers. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krovacloud/sdk",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "Official TypeScript SDK for Krova Cloud — a typed client for provisioning and managing Cubes (Firecracker microVMs) with dedicated resources.",
   "license": "MIT",
   "type": "module",
@@ -61,7 +61,7 @@
     "openapi-fetch": "^0.17.0"
   },
   "devDependencies": {
-    "@types/node": "^26.1.1",
+    "@types/node": "^26.1.2",
     "openapi-typescript": "^7.13.0",
     "tsup": "^8.5.1",
     "tsx": "^4.23.1",