@nimbus-sh/sdk 0.1.0

package/README.md

@@ -0,0 +1,254 @@
+# @nimbus-sh/sdk
+
+SDK for Nimbus — programmatic sandbox handles, token mint/verify, typed
+errors, and session URL helpers.
+
+## Install
+
+```bash
+npm install @nimbus-sh/sdk @nimbus-sh/worker @nimbus-sh/config
+```
+
+The sandbox SDK is meant to run inside the Worker or Durable Object that owns
+the `NIMBUS_SESSION` binding. A minimal project setup is:
+
+```bash
+npx @nimbus-sh/cli init my-nimbus-worker
+cd my-nimbus-worker
+npm install
+wrangler secret put JWT_SECRET
+wrangler deploy
+```
+
+From this repository, use the source CLI:
+
+```bash
+bun packages/cli/src/bin.ts init my-nimbus-worker
+cd my-nimbus-worker
+bun install
+wrangler secret put JWT_SECRET
+wrangler deploy
+```
+
+## Programmatic sandbox quickstart
+
+Use `@nimbus-sh/sdk/sandbox` inside the Worker or Durable Object that embeds
+Nimbus. The SDK talks to the `NIMBUS_SESSION` Durable Object binding via DO
+RPC; it does not need a browser WebSocket.
+
+```ts
+import { Nimbus } from '@nimbus-sh/sdk/sandbox';
+import { defineNimbusConfig } from '@nimbus-sh/config';
+
+const nimbusConfig = defineNimbusConfig({
+  endpoint: 'https://my-nimbus.workers.dev',
+  sandboxes: {
+    proteus: {
+      root: '/home/user',
+      tools: { namespace: 'sandbox', kind: 'sandbox' },
+      runtimes: {
+        preinstall: ['python', 'clang'],
+        onDemand: true,
+        allow: ['node', 'bun', 'npm', 'git', 'python', 'ruby', 'clang', 'shell'],
+      },
+    },
+  },
+});
+
+export default {
+  async fetch(_request: Request, env: Env) {
+    const box = Nimbus.fromEnv(env, nimbusConfig).sandbox('job-123', {
+      profile: 'proteus',
+      tenant: 'acme',
+      subject: 'agent',
+    });
+
+    await box.files.write('/home/user/app/main.py', 'print(2 + 2)\n');
+    await box.runtimes.ensure('python');
+    const result = await box.exec('python /home/user/app/main.py');
+
+    return Response.json(result);
+  },
+};
+```
+
+## Sandbox handle API
+
+```ts
+const nimbus = Nimbus.fromEnv(env, config, { binding: 'NIMBUS_SESSION' });
+const box = nimbus.sandbox('session-or-job-id', {
+  profile: 'default',
+  tenant: 'acme',
+  subject: 'agent-7',
+  root: '/home/user',
+});
+
+await box.ready();
+await box.exec('node -e "console.log(2 + 2)"');
+await box.startProcess('node --watch /home/user/app/server.js');
+await box.runCode('print(2 + 2)', { language: 'python', install: 'ifMissing' });
+
+await box.files.write('/home/user/app/a.txt', 'hello');
+await box.files.read('/home/user/app/a.txt');
+await box.files.list('/home/user/app');
+await box.files.delete('/home/user/app/a.txt');
+
+await box.runtimes.available();
+await box.runtimes.installed();
+await box.runtimes.install('python');
+await box.runtimes.ensure(['python', 'clang']);
+
+await box.processes.list();
+await box.processes.logs(7);
+await box.processes.kill(7);
+
+const port = await box.ports.expose(3000);
+// port.url => https://my-nimbus.workers.dev/s/<session-or-job-id>/port/3000/
+await box.ports.unexpose(3000);
+```
+
+Runtime policy comes from the sandbox profile:
+
+- `runtimes.preinstall` is applied by `box.ready()`.
+- `runtimes.allow` gates SDK runtime operations and `runCode()` language use.
+- `runtimes.onDemand: false` blocks installing runtimes that are not listed
+  in `preinstall`.
+
+## Proteus-style tools
+
+`box.tools({ namespace: 'sandbox', kind: 'sandbox' })` returns a provider-like
+object with `tools.exec.execute`, `runCode`, `readFile`, `writeFile`,
+`listFiles`/`readdir`, `deleteFile`, `exists`, `startProcess`, `killProcess`,
+`logs`, `exposePort`, `unexposePort`, `listPorts`, `installRuntime`, and
+`listRuntimes`.
+
+`provider.capabilities` is intentionally honest: Nimbus claims shell,
+JavaScript/TypeScript, npm, git, owned filesystem, outbound fetch, inbound
+HTTP-like port routing, process spawn/long-running processes, Python/Ruby
+when allowed, and clang as WASI-native. It does not claim Docker, apt, GPU,
+custom Linux images, native Linux ELF execution, or raw TCP listeners.
+
+## Quickstart — mint a session token
+
+```ts
+import { issueNimbusToken } from '@nimbus-sh/sdk/token';
+
+const token = await issueNimbusToken(
+  { JWT_SECRET: process.env.JWT_SECRET! },
+  { tn: 'acme', sub: 'alice' },
+  { ttlMs: 60 * 60 * 1000 },  // 1h
+);
+// → 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6Im5pbWJ1cyIsInRu...'
+```
+
+## Verify a token (typically in a Worker)
+
+```ts
+import { verifyNimbusToken } from '@nimbus-sh/sdk/token';
+
+try {
+  const { claims, doInstanceName } = await verifyNimbusToken(env, token);
+  // claims.tn, claims.sub, claims.scopes, claims.sid
+  // doInstanceName = `${tn}:${sub || '_'}` — feed to idFromName
+} catch (e) {
+  // every error extends NimbusAuthError with stable .code + .httpStatus
+}
+```
+
+## Typed errors
+
+```ts
+import {
+  NimbusAuthError,
+  NimbusTokenExpiredError,
+  NimbusScopeError,
+} from '@nimbus-sh/sdk/errors';
+
+try { await verifyNimbusToken(env, token); }
+catch (e) {
+  if (e instanceof NimbusTokenExpiredError) return Response.json({ refresh: true }, { status: 401 });
+  if (e instanceof NimbusScopeError)        return Response.json({ scope: e.requiredScope }, { status: 403 });
+  if (e instanceof NimbusAuthError)         return Response.json({ error: e.message, code: e.code }, { status: e.httpStatus });
+  throw e;
+}
+```
+
+| Error class | code | httpStatus |
+|---|---|---|
+| `NimbusAuthConfigError` | `E_AUTH_CONFIG_MISSING` | 500 |
+| `NimbusTokenMalformedError` | `E_TOKEN_MALFORMED` | 401 |
+| `NimbusTokenSignatureError` | `E_TOKEN_SIGNATURE` | 401 |
+| `NimbusTokenClaimsError` | `E_TOKEN_CLAIMS` | 401 |
+| `NimbusTokenExpiredError` | `E_TOKEN_EXPIRED` | 401 |
+| `NimbusTokenTtlError` | `E_TOKEN_TTL_TOO_LARGE` | 400 |
+| `NimbusScopeError` | `E_SCOPE_MISSING` | 403 |
+| `NimbusSessionPinError` | `E_SESSION_PIN_MISMATCH` | 403 |
+
+## Session URL helpers
+
+```ts
+import { sessionAttachUrl, mintAndAttach } from '@nimbus-sh/sdk';
+
+const url = sessionAttachUrl(
+  'https://my-nimbus.workers.dev',
+  'pretty-otter-1234',
+  token,
+);
+// → "https://my-nimbus.workers.dev/s/pretty-otter-1234/?nimbus_token=…"
+
+// Or combined in one call:
+const { token, url } = await mintAndAttach(
+  env,
+  { tn: 'acme', sub: 'alice' },
+  { endpoint: 'https://my-nimbus.workers.dev', sessionId: 'pretty-otter-1234' },
+);
+```
+
+## Subpath exports
+
+| Subpath | What |
+|---|---|
+| `@nimbus-sh/sdk` | Everything re-exported from a single entry. |
+| `@nimbus-sh/sdk/token` | `issueNimbusToken`, `verifyNimbusToken`, types. |
+| `@nimbus-sh/sdk/errors` | `NimbusAuthError` class hierarchy. |
+| `@nimbus-sh/sdk/session` | `sessionAttachUrl`, `mintAndAttach`. |
+| `@nimbus-sh/sdk/sandbox` | `Nimbus`, `NimbusSandbox`, programmatic exec/files/runtimes/processes/ports/tools. |
+
+## Token wire format
+
+JWT (HS256) with these claims:
+
+```ts
+{
+  scope: 'nimbus',           // always — discriminator vs other JWTs
+  tn:    'acme',             // tenant (required)
+  sub?:  'alice',            // user within tenant (optional)
+  scopes?: ['session:create','session:attach'],  // capability list
+  sid?:  'pretty-otter-1234', // pin to a specific session (optional)
+  iat:   1731612345,         // issued-at (UNIX seconds)
+  exp:   1731615945,         // expires-at (UNIX seconds)
+}
+```
+
+Both `tn` and `sub` must match `[A-Za-z0-9._-]{1,128}` — exported as
+`ID_COMPONENT_RE` if you need to validate user input.
+
+The `scope` discriminator means a token minted for another product
+(e.g. Mossaic VFS, `scope: "vfs"`) is rejected even when signed with
+the same secret.
+
+## Secret rotation
+
+Set `JWT_SECRET_PREVIOUS` during a rotation window. Both old and new
+secrets verify; new tokens are always signed with the primary.
+
+```bash
+# Phase 1: New secret in place, old secret as fallback.
+wrangler secret put JWT_SECRET           # the new one
+wrangler secret put JWT_SECRET_PREVIOUS  # the old one
+
+# Phase 2 (after the longest token TTL has elapsed):
+wrangler secret delete JWT_SECRET_PREVIOUS
+```
+
+MIT.

package/dist/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @nimbus-sh/sdk/errors — Typed error classes re-exported from the
+ * worker auth module.
+ *
+ * Every error in `@nimbus-sh/sdk` extends `NimbusAuthError`, which has
+ * a stable `.code` property for catch-site discrimination and an
+ * `.httpStatus` hint for response mapping. The class hierarchy is
+ * `instanceof`-friendly: a blanket `catch (e instanceof NimbusAuthError)`
+ * catches every subclass.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   NimbusAuthError,
+ *   NimbusTokenExpiredError,
+ *   NimbusScopeError,
+ * } from '@nimbus-sh/sdk/errors';
+ *
+ * try {
+ *   await verifyNimbusToken(env, token);
+ * } catch (e) {
+ *   if (e instanceof NimbusTokenExpiredError) {
+ *     return Response.json({ refresh: true }, { status: 401 });
+ *   }
+ *   if (e instanceof NimbusScopeError) {
+ *     return Response.json({ missingScope: e.requiredScope }, { status: 403 });
+ *   }
+ *   if (e instanceof NimbusAuthError) {
+ *     return Response.json({ error: e.message, code: e.code }, { status: e.httpStatus });
+ *   }
+ *   throw e;
+ * }
+ * ```
+ */
+export { NimbusAuthError, NimbusAuthConfigError, NimbusTokenMalformedError, NimbusTokenSignatureError, NimbusTokenClaimsError, NimbusTokenExpiredError, NimbusTokenTtlError, NimbusScopeError, NimbusSessionPinError, } from '@nimbus-sh/worker/auth';
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,yBAAyB,EACzB,yBAAyB,EACzB,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC"}

package/dist/errors.js

@@ -0,0 +1,35 @@
+/**
+ * @nimbus-sh/sdk/errors — Typed error classes re-exported from the
+ * worker auth module.
+ *
+ * Every error in `@nimbus-sh/sdk` extends `NimbusAuthError`, which has
+ * a stable `.code` property for catch-site discrimination and an
+ * `.httpStatus` hint for response mapping. The class hierarchy is
+ * `instanceof`-friendly: a blanket `catch (e instanceof NimbusAuthError)`
+ * catches every subclass.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   NimbusAuthError,
+ *   NimbusTokenExpiredError,
+ *   NimbusScopeError,
+ * } from '@nimbus-sh/sdk/errors';
+ *
+ * try {
+ *   await verifyNimbusToken(env, token);
+ * } catch (e) {
+ *   if (e instanceof NimbusTokenExpiredError) {
+ *     return Response.json({ refresh: true }, { status: 401 });
+ *   }
+ *   if (e instanceof NimbusScopeError) {
+ *     return Response.json({ missingScope: e.requiredScope }, { status: 403 });
+ *   }
+ *   if (e instanceof NimbusAuthError) {
+ *     return Response.json({ error: e.message, code: e.code }, { status: e.httpStatus });
+ *   }
+ *   throw e;
+ * }
+ * ```
+ */
+export { NimbusAuthError, NimbusAuthConfigError, NimbusTokenMalformedError, NimbusTokenSignatureError, NimbusTokenClaimsError, NimbusTokenExpiredError, NimbusTokenTtlError, NimbusScopeError, NimbusSessionPinError, } from '@nimbus-sh/worker/auth';

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @nimbus-sh/sdk — Client SDK for Nimbus.
+ *
+ * The SDK is the **environment-agnostic** half of Nimbus: token mint /
+ * verify, typed errors, session-handle types, and the HTTP fallback for
+ * non-Worker consumers. Everything in this package is safe to import
+ * from a Node SSR layer, a Worker, an Edge function, or a browser
+ * build.
+ *
+ * For the Worker runtime itself (the Durable Object, the router, the
+ * facet machinery), see `@nimbus-sh/worker`.
+ *
+ * @example mint a token in your Worker's `/api/auth/mint` route
+ * ```ts
+ * import { issueNimbusToken } from '@nimbus-sh/sdk/token';
+ * export default {
+ *   async fetch(req: Request, env: Env) {
+ *     const { tenant, sub } = await req.json();
+ *     const token = await issueNimbusToken(env, { tn: tenant, sub });
+ *     return Response.json({ token });
+ *   },
+ * };
+ * ```
+ */
+export * from './token.js';
+export * from './errors.js';
+export * from './session.js';
+export * from './sandbox.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * @nimbus-sh/sdk — Client SDK for Nimbus.
+ *
+ * The SDK is the **environment-agnostic** half of Nimbus: token mint /
+ * verify, typed errors, session-handle types, and the HTTP fallback for
+ * non-Worker consumers. Everything in this package is safe to import
+ * from a Node SSR layer, a Worker, an Edge function, or a browser
+ * build.
+ *
+ * For the Worker runtime itself (the Durable Object, the router, the
+ * facet machinery), see `@nimbus-sh/worker`.
+ *
+ * @example mint a token in your Worker's `/api/auth/mint` route
+ * ```ts
+ * import { issueNimbusToken } from '@nimbus-sh/sdk/token';
+ * export default {
+ *   async fetch(req: Request, env: Env) {
+ *     const { tenant, sub } = await req.json();
+ *     const token = await issueNimbusToken(env, { tn: tenant, sub });
+ *     return Response.json({ token });
+ *   },
+ * };
+ * ```
+ */
+export * from './token.js';
+export * from './errors.js';
+export * from './session.js';
+export * from './sandbox.js';

package/dist/sandbox.d.ts

@@ -0,0 +1,271 @@
+/**
+ * @nimbus-sh/sdk/sandbox - programmatic Nimbus sandbox handle.
+ */
+export type RuntimeSpec = string;
+export type RuntimeName = 'node' | 'bun' | 'npm' | 'git' | 'python' | 'ruby' | 'clang' | 'shell' | (string & {});
+export interface NimbusRuntimePolicy {
+    preinstall?: RuntimeSpec[];
+    onDemand?: boolean;
+    allow?: RuntimeName[];
+}
+export interface NimbusSandboxProfile {
+    root?: string;
+    runtimes?: NimbusRuntimePolicy;
+    tools?: {
+        namespace?: string;
+        kind?: string;
+    };
+    preview?: {
+        baseUrl?: string;
+        pathStyle?: boolean;
+    };
+}
+export interface NimbusConfig {
+    endpoint?: string;
+    sandboxes?: Record<string, NimbusSandboxProfile>;
+}
+export interface NimbusFromEnvOptions {
+    binding?: string;
+    endpoint?: string;
+}
+export interface NimbusSandboxOptions {
+    profile?: string;
+    tenant?: string;
+    subject?: string;
+    root?: string;
+}
+export interface NimbusExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    stdin?: string;
+}
+export interface NimbusExecResult {
+    command: string;
+    exitCode: number;
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    duration: number;
+    timestamp: number;
+}
+export interface NimbusStartResult extends NimbusExecResult {
+    pid: number | null;
+    process: NimbusProcess | null;
+    ports: NimbusPort[];
+}
+export interface NimbusProcess {
+    pid: number;
+    command: string;
+    argv: string[];
+    cwd: string;
+    state: string;
+    exitCode: number | null;
+    startTime: number;
+    endTime: number | null;
+    longRunning: boolean;
+}
+export interface NimbusPort {
+    port: number;
+    pid: number;
+    registeredAt: number;
+}
+export interface NimbusRuntimeSummary {
+    name: string;
+    version: string;
+    root: string;
+    bins: string[];
+    sizeBytes: number;
+    license: string;
+}
+export interface NimbusAvailableRuntime {
+    name: string;
+    defaultVersion: string;
+    versions: Array<{
+        version: string;
+        sizeBytes: number;
+        license: string;
+    }>;
+}
+type NimbusSessionNamespace = DurableObjectNamespace<any>;
+export declare class Nimbus {
+    private readonly namespace;
+    private readonly config;
+    static fromEnv(env: Record<string, unknown>, config?: NimbusConfig, options?: NimbusFromEnvOptions): Nimbus;
+    constructor(namespace: NimbusSessionNamespace, config?: NimbusConfig);
+    sandbox(id: string, options?: NimbusSandboxOptions): NimbusSandbox;
+}
+export declare class NimbusSandbox {
+    private readonly namespace;
+    private readonly options;
+    private readonly config;
+    readonly id: string;
+    readonly profileName: string;
+    private readonly profile;
+    private readyPromise;
+    constructor(namespace: NimbusSessionNamespace, id: string, options: NimbusSandboxOptions, config: NimbusConfig);
+    private get tenantSegment();
+    private get doName();
+    private get root();
+    private stub;
+    ready(): Promise<void>;
+    exec(command: string, options?: NimbusExecOptions): Promise<NimbusExecResult>;
+    startProcess(command: string, options?: NimbusExecOptions): Promise<NimbusStartResult>;
+    runCode(code: string, options?: NimbusExecOptions & {
+        language?: 'javascript' | 'typescript' | 'python' | 'ruby' | 'shell';
+        install?: 'never' | 'ifMissing';
+    }): Promise<NimbusExecResult>;
+    files: {
+        read: (path: string) => Promise<string | null>;
+        readBytes: (path: string) => Promise<Uint8Array | null>;
+        write: (path: string, content: string | Uint8Array) => Promise<void>;
+        list: (path?: string) => Promise<{
+            name: string;
+            type: string;
+        }[]>;
+        mkdir: (path: string) => Promise<void>;
+        exists: (path: string) => Promise<boolean>;
+        delete: (path: string, options?: {
+            recursive?: boolean;
+        }) => Promise<void>;
+    };
+    runtimes: {
+        available: () => Promise<NimbusAvailableRuntime[]>;
+        installed: () => Promise<NimbusRuntimeSummary[]>;
+        list: () => Promise<{
+            installed: NimbusRuntimeSummary[];
+            available: NimbusAvailableRuntime[];
+        }>;
+        install: (spec: RuntimeSpec, options?: {
+            force?: boolean;
+        }) => Promise<unknown>;
+        ensure: (specs: RuntimeSpec | RuntimeSpec[], options?: {
+            force?: boolean;
+        }) => Promise<unknown>;
+    };
+    processes: {
+        list: () => Promise<NimbusProcess[]>;
+        kill: (pid: number) => Promise<{
+            ok: boolean;
+            pid: number;
+        }>;
+        logs: (pid: number, options?: {
+            lines?: number;
+            bytes?: number;
+        }) => Promise<unknown>;
+    };
+    ports: {
+        list: () => Promise<NimbusPort[]>;
+        expose: (port: number) => Promise<{
+            url: string | undefined;
+            port: number;
+            listening: boolean;
+            pid: number | null;
+            registeredAt: number | null;
+        }>;
+        unexpose: (port: number) => Promise<{
+            port: number;
+            ok: boolean;
+        }>;
+        url: (port: number) => string | undefined;
+    };
+    tools(options?: {
+        namespace?: string;
+        kind?: string;
+        name?: string;
+    }): {
+        name: string;
+        kind: string;
+        capabilities: string[];
+        isAvailable: () => Promise<boolean>;
+        connect: () => Promise<void>;
+        disconnect: () => Promise<undefined>;
+        tools: {
+            exec: {
+                execute: (command: string, opts?: NimbusExecOptions) => Promise<NimbusExecResult>;
+            };
+            runCode: {
+                execute: (code: string, opts?: Parameters<NimbusSandbox["runCode"]>[1]) => Promise<NimbusExecResult>;
+            };
+            readFile: {
+                execute: (input: unknown) => Promise<string | null>;
+            };
+            writeFile: {
+                execute: (input: any) => Promise<void>;
+            };
+            listFiles: {
+                execute: (input?: unknown) => Promise<{
+                    name: string;
+                    type: string;
+                }[]>;
+            };
+            readdir: {
+                execute: (input?: unknown) => Promise<{
+                    name: string;
+                    type: string;
+                }[]>;
+            };
+            deleteFile: {
+                execute: (input: any) => Promise<void>;
+            };
+            exists: {
+                execute: (input: unknown) => Promise<boolean>;
+            };
+            startProcess: {
+                execute: (command: string, opts?: NimbusExecOptions) => Promise<NimbusStartResult>;
+            };
+            killProcess: {
+                execute: (input: number | {
+                    pid: number;
+                }) => Promise<{
+                    ok: boolean;
+                    pid: number;
+                }>;
+            };
+            logs: {
+                execute: (input: number | {
+                    pid: number;
+                    lines?: number;
+                    bytes?: number;
+                }) => Promise<unknown>;
+            };
+            exposePort: {
+                execute: (input: number | {
+                    port: number;
+                }) => Promise<{
+                    url: string | undefined;
+                    port: number;
+                    listening: boolean;
+                    pid: number | null;
+                    registeredAt: number | null;
+                }>;
+            };
+            unexposePort: {
+                execute: (input: number | {
+                    port: number;
+                }) => Promise<{
+                    port: number;
+                    ok: boolean;
+                }>;
+            };
+            listPorts: {
+                execute: () => Promise<NimbusPort[]>;
+            };
+            installRuntime: {
+                execute: (spec: RuntimeSpec) => Promise<unknown>;
+            };
+            listRuntimes: {
+                execute: () => Promise<{
+                    installed: NimbusRuntimeSummary[];
+                    available: NimbusAvailableRuntime[];
+                }>;
+            };
+        };
+    };
+    capabilities(): string[];
+    private execOptions;
+    private assertRuntimeAllowed;
+    private portUrl;
+}
+export {};
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"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"}

package/dist/sandbox.js

@@ -0,0 +1,259 @@
+/**
+ * @nimbus-sh/sdk/sandbox - programmatic Nimbus sandbox handle.
+ */
+export class Nimbus {
+    namespace;
+    config;
+    static fromEnv(env, config = {}, options = {}) {
+        const bindingName = options.binding ?? 'NIMBUS_SESSION';
+        const binding = env[bindingName];
+        if (!binding) {
+            throw new Error(`Nimbus.fromEnv: env.${bindingName} Durable Object binding is missing`);
+        }
+        return new Nimbus(binding, {
+            ...config,
+            endpoint: options.endpoint ?? config.endpoint,
+        });
+    }
+    constructor(namespace, config = {}) {
+        this.namespace = namespace;
+        this.config = config;
+    }
+    sandbox(id, options = {}) {
+        return new NimbusSandbox(this.namespace, String(id), options, this.config);
+    }
+}
+export class NimbusSandbox {
+    namespace;
+    options;
+    config;
+    id;
+    profileName;
+    profile;
+    readyPromise = null;
+    constructor(namespace, id, options, config) {
+        this.namespace = namespace;
+        this.options = options;
+        this.config = config;
+        this.id = id;
+        this.profileName = options.profile ?? 'default';
+        this.profile = config.sandboxes?.[this.profileName] ?? config.sandboxes?.default ?? {};
+    }
+    get tenantSegment() {
+        const tenant = sanitizeSegment(this.options.tenant ?? 'default');
+        const subject = sanitizeSegment(this.options.subject ?? '_');
+        return `${tenant}:${subject}`;
+    }
+    get doName() {
+        return `${this.tenantSegment}:${this.id}`;
+    }
+    get root() {
+        return this.options.root ?? this.profile.root ?? '/home/user';
+    }
+    stub() {
+        const namespace = this.namespace;
+        const id = namespace.idFromName(this.doName);
+        return namespace.get(id);
+    }
+    async ready() {
+        if (!this.readyPromise) {
+            const preinstall = this.profile.runtimes?.preinstall ?? [];
+            for (const spec of preinstall)
+                this.assertRuntimeAllowed(spec, 'preinstall');
+            this.readyPromise = this.stub()._rpcReady({ preinstall }).then(() => undefined);
+        }
+        return this.readyPromise;
+    }
+    async exec(command, options = {}) {
+        await this.ready();
+        return this.stub()._rpcExec(command, this.execOptions(options));
+    }
+    async startProcess(command, options = {}) {
+        await this.ready();
+        return this.stub()._rpcStartProcess(command, this.execOptions(options));
+    }
+    async runCode(code, options = {}) {
+        const language = options.language ?? 'javascript';
+        if (language === 'python' || language === 'ruby') {
+            this.assertRuntimeAllowed(language, options.install === 'ifMissing' ? 'onDemand' : 'use');
+        }
+        await this.ready();
+        return this.stub()._rpcRunCode(code, {
+            ...this.execOptions(options),
+            language,
+            install: options.install ?? 'never',
+        });
+    }
+    files = {
+        read: async (path) => {
+            await this.ready();
+            return this.stub()._rpcReadFile(path);
+        },
+        readBytes: async (path) => {
+            await this.ready();
+            return this.stub()._rpcReadFileBytes(path);
+        },
+        write: async (path, content) => {
+            await this.ready();
+            return this.stub()._rpcWriteFile(path, content);
+        },
+        list: async (path = this.root) => {
+            await this.ready();
+            return this.stub()._rpcReaddir(path);
+        },
+        mkdir: async (path) => {
+            await this.ready();
+            return this.stub()._rpcMkdir(path);
+        },
+        exists: async (path) => {
+            await this.ready();
+            return this.stub()._rpcExists(path);
+        },
+        delete: async (path, options = {}) => {
+            await this.ready();
+            return this.stub()._rpcDeleteFile(path, options);
+        },
+    };
+    runtimes = {
+        available: async () => {
+            await this.ready();
+            return (await this.stub()._rpcListRuntimes()).available;
+        },
+        installed: async () => {
+            await this.ready();
+            return (await this.stub()._rpcListRuntimes()).installed;
+        },
+        list: async () => {
+            await this.ready();
+            return this.stub()._rpcListRuntimes();
+        },
+        install: async (spec, options = {}) => {
+            this.assertRuntimeAllowed(spec, 'onDemand');
+            await this.ready();
+            return this.stub()._rpcInstallRuntime(spec, options);
+        },
+        ensure: async (specs, options = {}) => {
+            const list = Array.isArray(specs) ? specs : [specs];
+            for (const spec of list)
+                this.assertRuntimeAllowed(spec, 'onDemand');
+            await this.ready();
+            return this.stub()._rpcEnsureRuntimes(list, options);
+        },
+    };
+    processes = {
+        list: async () => {
+            await this.ready();
+            return this.stub()._rpcListProcesses();
+        },
+        kill: async (pid) => {
+            await this.ready();
+            return this.stub()._rpcKillProcess(pid);
+        },
+        logs: async (pid, options = {}) => {
+            await this.ready();
+            return this.stub()._rpcProcessLogs(pid, options);
+        },
+    };
+    ports = {
+        list: async () => {
+            await this.ready();
+            return this.stub()._rpcListPorts();
+        },
+        expose: async (port) => {
+            await this.ready();
+            const result = await this.stub()._rpcExposePort(port);
+            return { ...result, url: this.portUrl(port) };
+        },
+        unexpose: async (port) => {
+            await this.ready();
+            return this.stub()._rpcUnexposePort(port);
+        },
+        url: (port) => this.portUrl(port),
+    };
+    tools(options = {}) {
+        const namespace = options.namespace ?? this.profile.tools?.namespace ?? 'nimbus';
+        const kind = options.kind ?? this.profile.tools?.kind ?? 'nimbus';
+        const callPath = (input) => typeof input === 'string' ? input : String(input?.path ?? '');
+        return {
+            name: options.name ?? namespace,
+            kind,
+            capabilities: this.capabilities(),
+            isAvailable: async () => true,
+            connect: async () => this.ready(),
+            disconnect: async () => undefined,
+            tools: {
+                exec: { execute: (command, opts) => this.exec(command, opts) },
+                runCode: { execute: (code, opts) => this.runCode(code, opts) },
+                readFile: { execute: (input) => this.files.read(callPath(input)) },
+                writeFile: { execute: (input) => this.files.write(callPath(input), input.content ?? input.data ?? '') },
+                listFiles: { execute: (input = this.root) => this.files.list(callPath(input) || this.root) },
+                readdir: { execute: (input = this.root) => this.files.list(callPath(input) || this.root) },
+                deleteFile: { execute: (input) => this.files.delete(callPath(input), { recursive: !!input?.recursive }) },
+                exists: { execute: (input) => this.files.exists(callPath(input)) },
+                startProcess: { execute: (command, opts) => this.startProcess(command, opts) },
+                killProcess: { execute: (input) => this.processes.kill(typeof input === 'number' ? input : input.pid) },
+                logs: { execute: (input) => this.processes.logs(typeof input === 'number' ? input : input.pid, typeof input === 'number' ? {} : input) },
+                exposePort: { execute: (input) => this.ports.expose(typeof input === 'number' ? input : input.port) },
+                unexposePort: { execute: (input) => this.ports.unexpose(typeof input === 'number' ? input : input.port) },
+                listPorts: { execute: () => this.ports.list() },
+                installRuntime: { execute: (spec) => this.runtimes.install(spec) },
+                listRuntimes: { execute: () => this.runtimes.list() },
+            },
+        };
+    }
+    capabilities() {
+        const allow = this.profile.runtimes?.allow;
+        const hasRuntime = (name) => !allow || allow.includes(name);
+        const caps = [
+            'javascript',
+            'typescript',
+            'shell',
+            'npm',
+            'git',
+            'fs_owned',
+            'net_outbound',
+            'net_inbound',
+            'process_spawn',
+            'process_long',
+        ];
+        if (hasRuntime('python'))
+            caps.push('python');
+        if (hasRuntime('clang'))
+            caps.push('native_binary');
+        return caps;
+    }
+    execOptions(options) {
+        return {
+            ...options,
+            cwd: options.cwd ?? this.root,
+        };
+    }
+    assertRuntimeAllowed(spec, action) {
+        const policy = this.profile.runtimes;
+        const allow = policy?.allow;
+        const name = String(spec).split('@')[0];
+        if (allow && !allow.includes(name)) {
+            throw new Error(`Nimbus runtime '${name}' is not allowed by sandbox profile '${this.profileName}'`);
+        }
+        if (action !== 'onDemand' || policy?.onDemand !== false)
+            return;
+        const preinstalled = new Set((policy.preinstall ?? []).map((s) => String(s).split('@')[0]));
+        if (!preinstalled.has(name)) {
+            throw new Error(`Nimbus runtime '${name}' is not preinstalled and on-demand runtime installs are disabled by sandbox profile '${this.profileName}'`);
+        }
+    }
+    portUrl(port) {
+        const explicit = this.profile.preview?.baseUrl;
+        if (explicit) {
+            const base = explicit.replace('{sessionId}', encodeURIComponent(this.id)).replace(/\/+$/, '');
+            return `${base}/port/${port}/`;
+        }
+        const endpoint = this.config.endpoint?.replace(/\/+$/, '');
+        if (!endpoint)
+            return undefined;
+        return `${endpoint}/s/${encodeURIComponent(this.id)}/port/${port}/`;
+    }
+}
+function sanitizeSegment(value) {
+    return String(value).replace(/[^A-Za-z0-9_.:-]/g, '_') || '_';
+}

package/dist/session.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @nimbus-sh/sdk/session — High-level session handle helpers.
+ *
+ * Useful for embedders who want to compute a session URL ahead of time
+ * (e.g. for sharing) or attach to a known session ID. The helpers in
+ * this module are pure URL/token plumbing; no network calls.
+ */
+import { type NimbusAuthEnv } from '@nimbus-sh/worker/auth';
+import type { IssueTokenOptions } from '@nimbus-sh/worker/auth';
+/**
+ * Compute the canonical attach URL for a session. The returned URL
+ * embeds the token in the `?nimbus_token=` query so an `<iframe src>`
+ * can carry it without custom headers.
+ *
+ * @param endpoint Base URL of the Nimbus deploy (e.g. `https://my.workers.dev`).
+ *                 No trailing slash required.
+ * @param sessionId Session ID (e.g. `pretty-otter-1234`).
+ * @param token Verified Nimbus JWT.
+ * @returns Fully-qualified URL: `${endpoint}/s/${sessionId}/?nimbus_token=${token}`.
+ *
+ * @example
+ * ```ts
+ * import { sessionAttachUrl, issueNimbusToken } from '@nimbus-sh/sdk';
+ * const token = await issueNimbusToken(env, { tn: 'acme', sub: 'alice' });
+ * const url = sessionAttachUrl('https://my-nimbus.workers.dev', 'pretty-otter-1234', token);
+ * // → "https://my-nimbus.workers.dev/s/pretty-otter-1234/?nimbus_token=eyJ…"
+ * ```
+ */
+export declare function sessionAttachUrl(endpoint: string, sessionId: string, token: string): string;
+/**
+ * Convenience: mint a token AND build the attach URL in one call.
+ *
+ * @param env Env with `JWT_SECRET` (and optionally `JWT_SECRET_PREVIOUS`).
+ * @param input Token claims minus iat/exp/scope.
+ * @param opts Mint options ({@link IssueTokenOptions}) plus endpoint + sessionId.
+ *
+ * @example
+ * ```ts
+ * const { token, url } = await mintAndAttach(env,
+ *   { tn: 'acme', sub: 'alice' },
+ *   { endpoint: 'https://my-nimbus.workers.dev', sessionId: 'pretty-otter-1234' });
+ * ```
+ */
+export declare function mintAndAttach(env: NimbusAuthEnv, input: {
+    tn: string;
+    sub?: string;
+    scopes?: string[];
+    sid?: string;
+}, opts: IssueTokenOptions & {
+    endpoint: string;
+    sessionId: string;
+}): Promise<{
+    token: string;
+    url: string;
+}>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,MAAM,CAGR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EACpE,IAAI,EAAE,iBAAiB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAChE,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAIzC"}

package/dist/session.js

@@ -0,0 +1,50 @@
+/**
+ * @nimbus-sh/sdk/session — High-level session handle helpers.
+ *
+ * Useful for embedders who want to compute a session URL ahead of time
+ * (e.g. for sharing) or attach to a known session ID. The helpers in
+ * this module are pure URL/token plumbing; no network calls.
+ */
+import { issueNimbusToken } from '@nimbus-sh/worker/auth';
+/**
+ * Compute the canonical attach URL for a session. The returned URL
+ * embeds the token in the `?nimbus_token=` query so an `<iframe src>`
+ * can carry it without custom headers.
+ *
+ * @param endpoint Base URL of the Nimbus deploy (e.g. `https://my.workers.dev`).
+ *                 No trailing slash required.
+ * @param sessionId Session ID (e.g. `pretty-otter-1234`).
+ * @param token Verified Nimbus JWT.
+ * @returns Fully-qualified URL: `${endpoint}/s/${sessionId}/?nimbus_token=${token}`.
+ *
+ * @example
+ * ```ts
+ * import { sessionAttachUrl, issueNimbusToken } from '@nimbus-sh/sdk';
+ * const token = await issueNimbusToken(env, { tn: 'acme', sub: 'alice' });
+ * const url = sessionAttachUrl('https://my-nimbus.workers.dev', 'pretty-otter-1234', token);
+ * // → "https://my-nimbus.workers.dev/s/pretty-otter-1234/?nimbus_token=eyJ…"
+ * ```
+ */
+export function sessionAttachUrl(endpoint, sessionId, token) {
+    const base = endpoint.replace(/\/+$/, '');
+    return `${base}/s/${sessionId}/?nimbus_token=${encodeURIComponent(token)}`;
+}
+/**
+ * Convenience: mint a token AND build the attach URL in one call.
+ *
+ * @param env Env with `JWT_SECRET` (and optionally `JWT_SECRET_PREVIOUS`).
+ * @param input Token claims minus iat/exp/scope.
+ * @param opts Mint options ({@link IssueTokenOptions}) plus endpoint + sessionId.
+ *
+ * @example
+ * ```ts
+ * const { token, url } = await mintAndAttach(env,
+ *   { tn: 'acme', sub: 'alice' },
+ *   { endpoint: 'https://my-nimbus.workers.dev', sessionId: 'pretty-otter-1234' });
+ * ```
+ */
+export async function mintAndAttach(env, input, opts) {
+    const token = await issueNimbusToken(env, input, opts);
+    const url = sessionAttachUrl(opts.endpoint, opts.sessionId, token);
+    return { token, url };
+}

package/dist/token.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @nimbus-sh/sdk/token — JWT mint + verify, re-exported from the worker
+ * auth module.
+ *
+ * Why a re-export and not a copy? The auth module is the single source
+ * of truth — both Worker (verify) and SDK (mint) call the same code
+ * paths so wire-format drift is structurally impossible. The
+ * `@nimbus-sh/worker` peer-dependency is OPTIONAL (declared in
+ * package.json#peerDependenciesMeta); consumers who only mint tokens
+ * outside a Worker can install just `@nimbus-sh/sdk` and the
+ * worker peer-dep is tree-shaken to its auth subpath.
+ *
+ * @example mint
+ * ```ts
+ * import { issueNimbusToken } from '@nimbus-sh/sdk/token';
+ * const jwt = await issueNimbusToken({ JWT_SECRET: 'hex' }, {
+ *   tn: 'acme', sub: 'alice'
+ * });
+ * ```
+ *
+ * @example verify in a Worker
+ * ```ts
+ * import { verifyNimbusToken } from '@nimbus-sh/sdk/token';
+ * const { claims, doInstanceName } = await verifyNimbusToken(env, jwt);
+ * ```
+ */
+export { issueNimbusToken, verifyNimbusToken, type NimbusAuthEnv, } from '@nimbus-sh/worker/auth';
+export { DEFAULT_TOKEN_TTL_MS, MAX_TOKEN_TTL_MS, ID_COMPONENT_RE, type NimbusTokenClaims, type VerifiedNimbusToken, type IssueTokenOptions, } from '@nimbus-sh/worker/auth';
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,aAAa,GACnB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,wBAAwB,CAAC"}

package/dist/token.js

@@ -0,0 +1,28 @@
+/**
+ * @nimbus-sh/sdk/token — JWT mint + verify, re-exported from the worker
+ * auth module.
+ *
+ * Why a re-export and not a copy? The auth module is the single source
+ * of truth — both Worker (verify) and SDK (mint) call the same code
+ * paths so wire-format drift is structurally impossible. The
+ * `@nimbus-sh/worker` peer-dependency is OPTIONAL (declared in
+ * package.json#peerDependenciesMeta); consumers who only mint tokens
+ * outside a Worker can install just `@nimbus-sh/sdk` and the
+ * worker peer-dep is tree-shaken to its auth subpath.
+ *
+ * @example mint
+ * ```ts
+ * import { issueNimbusToken } from '@nimbus-sh/sdk/token';
+ * const jwt = await issueNimbusToken({ JWT_SECRET: 'hex' }, {
+ *   tn: 'acme', sub: 'alice'
+ * });
+ * ```
+ *
+ * @example verify in a Worker
+ * ```ts
+ * import { verifyNimbusToken } from '@nimbus-sh/sdk/token';
+ * const { claims, doInstanceName } = await verifyNimbusToken(env, jwt);
+ * ```
+ */
+export { issueNimbusToken, verifyNimbusToken, } from '@nimbus-sh/worker/auth';
+export { DEFAULT_TOKEN_TTL_MS, MAX_TOKEN_TTL_MS, ID_COMPONENT_RE, } from '@nimbus-sh/worker/auth';

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@nimbus-sh/sdk",
+  "version": "0.1.0",
+  "description": "Nimbus SDK — programmatic sandboxes, token mint, types, and Worker client helpers.",
+  "homepage": "https://github.com/AshishKumar4/Nimbus",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AshishKumar4/Nimbus.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": "https://github.com/AshishKumar4/Nimbus/issues",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "workspace": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./token": {
+      "workspace": "./src/token.ts",
+      "types": "./dist/token.d.ts",
+      "import": "./dist/token.js"
+    },
+    "./session": {
+      "workspace": "./src/session.ts",
+      "types": "./dist/session.d.ts",
+      "import": "./dist/session.js"
+    },
+    "./sandbox": {
+      "workspace": "./src/sandbox.ts",
+      "types": "./dist/sandbox.d.ts",
+      "import": "./dist/sandbox.js"
+    },
+    "./errors": {
+      "workspace": "./src/errors.ts",
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noCheck --noEmit false --declaration true --declarationMap true --outDir dist --rootDir src",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@nimbus-sh/worker": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@nimbus-sh/worker": { "optional": true }
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250327.0",
+    "@nimbus-sh/worker": "^0.1.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}