Merge pull request #9 from leap0-dev/feature/presigned-urls

Add presigned URL APIs

Author: steven-passynkov

README.md

@@ -132,6 +132,18 @@ const access = await sandbox.ssh.createAccess();
 console.log(access.hostname, access.port, access.username);
 ```
 
+### Presigned URLs
+
+Create a temporary public URL for a sandbox port. The optional second argument to
+`createPresignedUrl(port, expiresIn)` is `expiresIn` in seconds.
+
+```ts
+const presigned = await sandbox.createPresignedUrl(8080, 900); // 15 minutes
+console.log(presigned.url);
+
+await sandbox.deletePresignedUrl(presigned.id);
+```
+
 ### Desktop Automation
 
 Control a graphical desktop inside the sandbox.

examples/ssh.ts

@@ -11,6 +11,9 @@ async function main(): Promise<void> {
 
       const validation = await sandbox.ssh.validateAccess(access.id, access.password);
       console.log("ssh valid:", validation.valid);
+
+      const rotated = await sandbox.ssh.regenerateAccess(access.id);
+      console.log("rotated ssh command:", rotated.sshCommand);
     } finally {
       await sandbox.delete();
     }

src/client/sandbox.ts

@@ -1,4 +1,4 @@
-import type { SandboxData, SandboxState } from "@/models/index.js";
+import type { PresignedUrl, SandboxData, SandboxState } from "@/models/index.js";
 import { sandboxStateSchema } from "@/models/sandbox.js";
 import {
   CodeInterpreterClient,
@@ -209,6 +209,24 @@ export class Sandbox implements SandboxData {
     await this.client.sandboxes.delete(this.id, options);
   }
 
+  /**
+   * Creates a temporary public URL for a specific sandbox port.
+   */
+  async createPresignedUrl(
+    port: number,
+    expiresIn?: number,
+    options?: { timeout?: number },
+  ): Promise<PresignedUrl> {
+    return this.client.sandboxes.createPresignedUrl(this.id, { port, expiresIn }, options);
+  }
+
+  /**
+   * Deletes a previously issued presigned URL.
+   */
+  async deletePresignedUrl(id: string, options?: { timeout?: number }): Promise<void> {
+    await this.client.sandboxes.deletePresignedUrl(this.id, id, options);
+  }
+
   /**
    * Returns the public invoke URL for the sandbox.
    *

src/index.ts

@@ -16,13 +16,15 @@ export {
 
 export { Leap0Client, Sandbox } from "@/client/index.js";
 export {
+  createPresignedUrlParamsSchema,
   CodeLanguage,
   codeLanguageSchema,
   listSandboxesParamsSchema,
   listSandboxesResponseSchema,
   listSnapshotsParamsSchema,
   listSnapshotsResponseSchema,
   NetworkPolicyMode,
+  presignedUrlSchema,
   RegistryCredentialType,
   SandboxState,
   StreamEventType,
@@ -43,6 +45,7 @@ export {
 } from "@/services/index.js";
 
 export type {
+  CreatePresignedUrlParams,
   CodeContext,
   CodeExecutionError,
   CodeExecutionOutput,
@@ -80,6 +83,7 @@ export type {
   LsResult,
   NetworkPolicy,
   ProcessResult,
+  PresignedUrl,
   PtySession,
   ResumeSnapshotParams,
   SandboxListItem,

src/models/index.ts

@@ -3,17 +3,21 @@ export type { RequestOptions } from "@/models/shared.js";
 export type { SandboxRef, SnapshotRef, TemplateRef } from "@/models/refs.js";
 
 export {
+  createPresignedUrlParamsSchema,
   createSandboxParamsSchema,
   listSandboxesParamsSchema,
   listSandboxesResponseSchema,
   NetworkPolicyMode,
+  presignedUrlSchema,
   SandboxState,
 } from "@/models/sandbox.js";
 export type {
+  CreatePresignedUrlParams,
   CreateSandboxParams,
   ListSandboxesParams,
   ListSandboxesResponse,
   NetworkPolicy,
+  PresignedUrl,
   SandboxData,
   SandboxListItem,
 } from "@/models/sandbox.js";

src/models/sandbox.ts

@@ -158,6 +158,25 @@ export const listSandboxesResponseSchema = z
 /** Paginated sandbox list response. */
 export type ListSandboxesResponse = z.infer<typeof listSandboxesResponseSchema>;
 
+export const createPresignedUrlParamsSchema = z.object({
+  port: z.number().int().min(1).max(65535),
+  expiresIn: z.number().int().min(1).optional(),
+});
+export type CreatePresignedUrlParams = z.infer<typeof createPresignedUrlParamsSchema>;
+
+export const presignedUrlSchema = z
+  .object({
+    id: z.string(),
+    token: z.string(),
+    url: z.string().url(),
+    sandboxId: z.string(),
+    port: z.number().int().min(1).max(65535),
+    expiresAt: z.string(),
+    createdAt: z.string(),
+  })
+  .catchall(z.unknown());
+export type PresignedUrl = z.infer<typeof presignedUrlSchema>;
+
 export const listSandboxesParamsSchema = z
   .object({
     state: z

src/services/sandboxes.ts

@@ -2,16 +2,20 @@ import { OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS } from "@/confi
 import { Leap0Error } from "@/core/errors.js";
 import { normalize } from "@/core/normalize.js";
 import {
+  createPresignedUrlParamsSchema,
   createSandboxRuntimeParamsSchema,
   listSandboxesParamsSchema,
   listSandboxesResponseSchema,
+  presignedUrlSchema,
   sandboxDataSchema,
   toNetworkPolicyWire,
 } from "@/models/sandbox.js";
 import type {
+  CreatePresignedUrlParams,
   CreateSandboxParams,
   ListSandboxesParams,
   ListSandboxesResponse,
+  PresignedUrl,
   RequestOptions,
   SandboxData,
   SandboxRef,
@@ -252,6 +256,52 @@ export class SandboxesClient<T = SandboxData> {
     });
   }
 
+  /**
+   * Creates a temporary public URL for a specific sandbox port.
+   */
+  async createPresignedUrl(
+    sandbox: SandboxRef,
+    params: CreatePresignedUrlParams,
+    options: RequestOptions = {},
+  ): Promise<PresignedUrl> {
+    const parsed = createPresignedUrlParamsSchema.parse(params);
+    return withErrorPrefix("Failed to create presigned URL: ", async () => {
+      const data = await this.transport.requestJson<unknown>(
+        `/v1/sandbox/${sandboxIdOf(sandbox)}/presigned-url`,
+        {
+          method: "POST",
+          body: jsonBody({
+            port: parsed.port,
+            expires_in: parsed.expiresIn,
+          }),
+        },
+        options,
+      );
+      return normalize(presignedUrlSchema, data);
+    });
+  }
+
+  /**
+   * Deletes a previously issued presigned URL.
+   */
+  async deletePresignedUrl(
+    sandbox: SandboxRef,
+    id: string,
+    options: RequestOptions = {},
+  ): Promise<void> {
+    const trimmedID = id.trim();
+    if (!trimmedID) {
+      throw new Leap0Error("id must be a non-empty string");
+    }
+    await withErrorPrefix("Failed to delete presigned URL: ", () =>
+      this.transport.request(
+	      `/v1/sandbox/${sandboxIdOf(sandbox)}/presigned-url/${trimmedID}`,
+        { method: "DELETE" },
+        options,
+      ),
+    );
+  }
+
 
   /**
    * Builds the public invoke URL for a sandbox.

src/services/ssh.ts

@@ -29,52 +29,54 @@ export class SshClient {
   }
 
   /**
-   * Deletes the active SSH credentials for a sandbox.
+   * Deletes a specific SSH credential for a sandbox.
    *
    * @param sandbox Sandbox ID or sandbox-like object.
+   * @param id The SSH credential ID to delete.
    * @param options Optional request settings such as timeout and query params.
    */
-  async deleteAccess(sandbox: SandboxRef, options: RequestOptions = {}): Promise<void> {
+  async deleteAccess(sandbox: SandboxRef, id: string, options: RequestOptions = {}): Promise<void> {
     await this.transport.request(
-      `/v1/sandbox/${sandboxIdOf(sandbox)}/ssh/access`,
+      `/v1/sandbox/${sandboxIdOf(sandbox)}/ssh/${id}`,
       { method: "DELETE" },
       options,
     );
   }
 
   /**
-   * Verifies a previously issued SSH credential pair.
+   * Verifies a specific previously issued SSH credential pair.
    *
    * @param sandbox Sandbox ID or sandbox-like object.
-   * @param accessId The SSH access ID to validate.
+   * @param id The SSH credential ID to validate.
    * @param password The password returned when the access credential was created.
    * @param options Optional request settings such as timeout and query params.
    * @returns The validation result.
    */
   async validateAccess(
     sandbox: SandboxRef,
-    accessId: string,
+    id: string,
     password: string,
     options: RequestOptions = {},
   ): Promise<SshValidation> {
     const data = await this.transport.requestJson<SshValidation>(
-      `/v1/sandbox/${sandboxIdOf(sandbox)}/ssh/validate`,
-      { method: "POST", body: jsonBody({ id: accessId, password }) },
+      `/v1/sandbox/${sandboxIdOf(sandbox)}/ssh/${id}/validate`,
+      { method: "POST", body: jsonBody({ password }) },
       options,
     );
     return normalize(sshValidationSchema, data);
   }
 
   /**
-   * Rotates SSH credentials for a sandbox.
+   * Rotates a specific SSH credential for a sandbox.
    *
    * @param sandbox Sandbox ID or sandbox-like object.
+   * @param id The SSH credential ID to rotate.
    * @param options Optional request settings such as timeout and query params.
    * @returns The newly generated SSH access payload.
    */
-  async regenerateAccess(sandbox: SandboxRef, options: RequestOptions = {}): Promise<SshAccess> {
+  async regenerateAccess(sandbox: SandboxRef, id: string, options: RequestOptions = {}): Promise<SshAccess> {
     const data = await this.transport.requestJson<SshAccess>(
-      `/v1/sandbox/${sandboxIdOf(sandbox)}/ssh/regen`,
+      `/v1/sandbox/${sandboxIdOf(sandbox)}/ssh/${id}/regen`,
       { method: "POST" },
       options,
     );

tests/client/client-sandbox.test.ts

@@ -3,7 +3,7 @@ import { expectTypeOf, test } from "vitest";
 
 import { Leap0Client, Sandbox } from "@/client/index.js";
 import { SERVICES } from "@/client/sandbox.js";
-import type { RequestOptions } from "@/models/index.js";
+import type { PresignedUrl, RequestOptions } from "@/models/index.js";
 
 test("Leap0Client wires services and supports direct access", async () => {
   const originalApiKey = process.env.LEAP0_API_KEY;
@@ -86,6 +86,16 @@ test("Sandbox binds service methods to itself", async () => {
         createdAt: "2026-01-01T00:00:00Z",
       }),
       delete: async () => undefined,
+      createPresignedUrl: async () => ({
+        id: "psu-1",
+        token: "tok_1",
+        url: "https://tok_1.leap0.app",
+        sandboxId: "sb-1",
+        port: 8080,
+        expiresAt: "2026-01-01T00:15:00Z",
+        createdAt: "2026-01-01T00:00:00Z",
+      }),
+      deletePresignedUrl: async () => undefined,
       getUserHomeDir: async (id: string) => `home:${id}`,
       getWorkdir: async (id: string) => `workdir:${id}`,
       invokeUrl: (id: string, path: string, port?: number) => `invoke:${id}:${path}:${port ?? ""}`,
@@ -124,6 +134,8 @@ test("Sandbox binds service methods to itself", async () => {
   assert.equal(sandbox.invokeUrl("/healthz", 3000), "invoke:sb-1:/healthz:3000");
   assert.equal(await sandbox.getUserHomeDir(), "home:sb-1");
   assert.equal(await sandbox.getWorkdir(), "workdir:sb-1");
+  assert.equal((await sandbox.createPresignedUrl(8080, 15)).url, "https://tok_1.leap0.app");
+  await sandbox.deletePresignedUrl("psu-1");
 });
 
 test("Sandbox refresh rejects invalid sandbox states", async () => {
@@ -180,10 +192,17 @@ test("client and sandbox helpers stay strongly typed", () => {
     [params: { command: string; cwd?: string; timeout?: number; env?: Record<string, string> }, options?: RequestOptions]
   >();
   expectTypeOf<Sandbox["ssh"]["validateAccess"]>().parameters.toEqualTypeOf<
-    [accessId: string, password: string, options?: RequestOptions]
+    [id: string, password: string, options?: RequestOptions]
+  >();
+  expectTypeOf<Sandbox["ssh"]["deleteAccess"]>().parameters.toEqualTypeOf<
+    [id: string, options?: RequestOptions]
+  >();
+  expectTypeOf<Sandbox["ssh"]["regenerateAccess"]>().parameters.toEqualTypeOf<
+    [id: string, options?: RequestOptions]
   >();
   expectTypeOf<ReturnType<Sandbox["getUserHomeDir"]>>().toEqualTypeOf<Promise<string>>();
   expectTypeOf<ReturnType<Sandbox["getWorkdir"]>>().toEqualTypeOf<Promise<string>>();
+  expectTypeOf<ReturnType<Sandbox["createPresignedUrl"]>>().toEqualTypeOf<Promise<PresignedUrl>>();
   expectTypeOf<Sandbox["templateName"]>().toEqualTypeOf<string | undefined>();
   expectTypeOf<Sandbox["timeoutMin"]>().toEqualTypeOf<number | undefined>();
   expectTypeOf<Sandbox["envVars"]>().toEqualTypeOf<Record<string, string> | undefined>();

tests/services/sandboxes-client.test.ts

@@ -115,6 +115,39 @@ test("sandboxes runtime info rejects non-object responses", async () => {
   await assert.rejects(() => client.getWorkdir("sb-1"), /missing workdir/);
 });
 
+test("sandboxes create and delete presigned urls", async () => {
+  const { transport, calls } = createRecordedTransport({
+    requestJson: (path: string, init: RequestInit, options: unknown) => {
+      calls.push({ path, init, options: options as never });
+      return Promise.resolve({
+        id: "psu-1",
+        token: "tok_1",
+        url: "https://tok_1.leap0.app",
+        sandbox_id: "sb-1",
+        port: 8080,
+        expires_at: "2026-01-01T00:15:00Z",
+        created_at: "2026-01-01T00:00:00Z",
+      });
+    },
+    request: (path: string, init: RequestInit, options: unknown) => {
+      calls.push({ path, init, options: options as never });
+      return Promise.resolve(new Response(null, { status: 204 }));
+    },
+  });
+  const client = new SandboxesClient(transport as never);
+
+  const created = await client.createPresignedUrl("sb-1", { port: 8080, expiresIn: 900 });
+  await client.deletePresignedUrl("sb-1", created.id);
+
+  assert.equal(created.url, "https://tok_1.leap0.app");
+  assert.equal(calls[0]?.path, "/v1/sandbox/sb-1/presigned-url");
+  assert.deepEqual(jsonOf(calls[0]!) as { port: number; expires_in: number }, {
+    port: 8080,
+    expires_in: 900,
+  });
+  assert.equal(calls[1]?.path, "/v1/sandbox/sb-1/presigned-url/psu-1");
+});
+
 
 test("sandboxes list sends query params and normalizes response", async () => {
   const { transport, calls } = createRecordedTransport({