@miosa/sdk 1.0.0 → 1.2.0

package/src/resources/egressAudit.ts

@@ -0,0 +1,245 @@
+/**
+ * Egress audit log — paginated query + live tail.
+ *
+ * Backed by:
+ *   GET    /api/v1/egress/audit
+ *   GET    /api/v1/egress/audit/:id
+ *
+ * `client.audit.tail()` long-polls the REST endpoint and yields new
+ * events as they arrive. The sandbox-scoped variant
+ * (`sandbox.audit.tail()`) upgrades to a live SSE connection backed by
+ * `GET /sandboxes/:id/audit/stream` so the tail latency is
+ * sub-second.
+ */
+
+import type { HttpClient } from "../http.js";
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+export interface EgressAuditEvent {
+  id: string;
+  action?: string;
+  effect?: string;
+  host?: string;
+  method?: string;
+  path?: string;
+  status_code?: number;
+  actor_id?: string;
+  resource_id?: string;
+  resource_type?: string;
+  policy_id?: string;
+  rule_id?: string;
+  external_user_id?: string;
+  external_workspace_id?: string;
+  metadata?: Record<string, unknown>;
+  inserted_at?: string;
+  timestamp?: string;
+  [key: string]: unknown;
+}
+
+// ── Request payloads ─────────────────────────────────────────────────────────
+
+export interface AuditListParams {
+  resourceId?: string;
+  resource_id?: string;
+  resourceType?: string;
+  resource_type?: string;
+  host?: string;
+  action?: string;
+  since?: string;
+  until?: string;
+  limit?: number;
+  cursor?: string;
+  externalUserId?: string;
+  external_user_id?: string;
+  externalWorkspaceId?: string;
+  external_workspace_id?: string;
+}
+
+export interface AuditTailParams extends AuditListParams {
+  pollIntervalMs?: number;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+interface WireEnvelope<T> {
+  data?: T;
+  event?: T;
+  items?: T;
+}
+
+function unwrap<T>(payload: unknown): T {
+  if (payload && typeof payload === "object") {
+    const p = payload as Record<string, unknown>;
+    for (const k of ["data", "event", "items"]) {
+      if (k in p) return p[k] as T;
+    }
+  }
+  return payload as T;
+}
+
+function unwrapList<T>(payload: unknown): T[] {
+  if (Array.isArray(payload)) return payload as T[];
+  if (payload && typeof payload === "object") {
+    const p = payload as Record<string, unknown>;
+    for (const k of ["data", "events", "audit", "items"]) {
+      if (Array.isArray(p[k])) return p[k] as T[];
+    }
+  }
+  return [];
+}
+
+function stripUndefined(
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, v]) => v !== undefined),
+  );
+}
+
+function pickFirst<T>(...values: Array<T | undefined>): T | undefined {
+  for (const v of values) if (v !== undefined) return v;
+  return undefined;
+}
+
+function listQuery(
+  params: AuditListParams,
+): Record<string, string | number | boolean | undefined> {
+  return stripUndefined({
+    resource_id: pickFirst(params.resourceId, params.resource_id),
+    resource_type: pickFirst(params.resourceType, params.resource_type),
+    host: params.host,
+    action: params.action,
+    since: params.since,
+    until: params.until,
+    limit: params.limit,
+    cursor: params.cursor,
+    external_user_id: pickFirst(params.externalUserId, params.external_user_id),
+    external_workspace_id: pickFirst(
+      params.externalWorkspaceId,
+      params.external_workspace_id,
+    ),
+  }) as Record<string, string | number | boolean | undefined>;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ── Main resource ─────────────────────────────────────────────────────────────
+
+export class EgressAudit {
+  constructor(protected readonly http: HttpClient) {}
+
+  /** List audit events with optional filters. */
+  async list(params: AuditListParams = {}): Promise<EgressAuditEvent[]> {
+    const data = await this.http.get<unknown>(
+      "/egress/audit",
+      listQuery(params),
+    );
+    return unwrapList<EgressAuditEvent>(data);
+  }
+
+  /** Get a single audit event by id. */
+  async get(id: string): Promise<EgressAuditEvent> {
+    const data = await this.http.get<WireEnvelope<EgressAuditEvent>>(
+      `/egress/audit/${id}`,
+    );
+    return unwrap<EgressAuditEvent>(data);
+  }
+
+  /**
+   * Long-poll the audit endpoint and yield new events as they appear.
+   *
+   * Tenant-wide `client.audit.tail()` is REST-based long polling. A
+   * live WebSocket / SSE tail is only available for the sandbox-scoped
+   * variant — see {@link SandboxAudit.tail}.
+   */
+  async *tail(
+    params: AuditTailParams = {},
+  ): AsyncIterableIterator<EgressAuditEvent> {
+    const pollMs = params.pollIntervalMs ?? 2000;
+    let since: string | undefined = params.since;
+    const seen = new Set<string>();
+    while (true) {
+      const queryParams: AuditListParams = { ...params };
+      if (since !== undefined) queryParams.since = since;
+      const data = await this.http.get<unknown>(
+        "/egress/audit",
+        listQuery(queryParams),
+      );
+      const events = unwrapList<EgressAuditEvent>(data);
+      for (const event of events) {
+        if (event.id && seen.has(event.id)) continue;
+        if (event.id) seen.add(event.id);
+        yield event;
+        const ts = event.inserted_at ?? event.timestamp;
+        if (typeof ts === "string") since = ts;
+      }
+      await sleep(pollMs);
+    }
+  }
+}
+
+// ── Resource-scoped wrappers ─────────────────────────────────────────────────
+
+/**
+ * Sandbox-bound view of {@link EgressAudit}. `list()` pre-scopes
+ * `resource_id` + `resource_type="sandbox"`. `tail()` upgrades to the
+ * per-sandbox SSE stream for sub-second tail latency.
+ */
+export class SandboxAudit {
+  protected readonly resourceType: string = "sandbox";
+  private readonly delegate: EgressAudit;
+
+  constructor(
+    protected readonly http: HttpClient,
+    protected readonly resourceId: string,
+  ) {
+    this.delegate = new EgressAudit(http);
+  }
+
+  list(params: AuditListParams = {}): Promise<EgressAuditEvent[]> {
+    return this.delegate.list({
+      ...params,
+      resource_id: params.resourceId ?? params.resource_id ?? this.resourceId,
+      resource_type:
+        params.resourceType ?? params.resource_type ?? this.resourceType,
+    });
+  }
+
+  get(id: string): Promise<EgressAuditEvent> {
+    return this.delegate.get(id);
+  }
+
+  /** SSE tail of the sandbox-scoped audit stream. */
+  async *tail(
+    params: AuditTailParams = {},
+  ): AsyncIterableIterator<EgressAuditEvent> {
+    const streamPath =
+      this.resourceType === "sandbox"
+        ? `/sandboxes/${this.resourceId}/audit/stream`
+        : `/computers/${this.resourceId}/audit/stream`;
+    try {
+      const stream = this.http.stream<EgressAuditEvent>(streamPath, {
+        method: "GET",
+      });
+      for await (const event of stream) {
+        yield event;
+      }
+    } catch {
+      // SSE endpoint unavailable — fall back to long-poll on the
+      // tenant-wide endpoint with this resource pre-filtered.
+      yield* this.delegate.tail({
+        ...params,
+        resource_id: this.resourceId,
+        resource_type: this.resourceType,
+      });
+    }
+  }
+}
+
+/** Computer-bound audit — same surface, `resource_type="computer"`. */
+export class ComputerAudit extends SandboxAudit {
+  protected readonly resourceType: string = "computer";
+}

package/src/resources/egressNetwork.ts

@@ -0,0 +1,450 @@
+/**
+ * Egress network — policies, allowlist, suggestions.
+ *
+ * Backed by:
+ *   GET    /api/v1/egress/policies
+ *   POST   /api/v1/egress/policies
+ *   PATCH  /api/v1/egress/policies/:id   (or no id for tenant default)
+ *
+ *   GET    /api/v1/egress/allowlist
+ *   POST   /api/v1/egress/allowlist
+ *   DELETE /api/v1/egress/allowlist/:id
+ *
+ *   GET    /api/v1/egress/audit/suggestions
+ */
+
+import type { HttpClient } from "../http.js";
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+export type EgressPolicyMode = "enforce" | "audit_only";
+export type EgressRuleEffect = "allow" | "deny";
+
+export interface EgressAllowlistRule {
+  id: string;
+  host: string;
+  effect: EgressRuleEffect | string;
+  methods?: string[];
+  path_glob?: string | null;
+  policy_id?: string | null;
+  resource_id?: string | null;
+  resource_type?: string | null;
+  note?: string | null;
+  created_at?: string;
+  [key: string]: unknown;
+}
+
+export interface EgressPolicyData {
+  id: string;
+  name?: string;
+  mode: EgressPolicyMode | string;
+  default_effect: EgressRuleEffect | string;
+  description?: string | null;
+  resource_id?: string | null;
+  resource_type?: string | null;
+  rules?: EgressAllowlistRule[];
+  created_at?: string;
+  updated_at?: string;
+  [key: string]: unknown;
+}
+
+export interface EgressSuggestion {
+  host: string;
+  methods?: string[];
+  path_glob?: string | null;
+  count?: number;
+  first_seen?: string;
+  last_seen?: string;
+  resource_id?: string | null;
+  [key: string]: unknown;
+}
+
+// ── Request payloads ─────────────────────────────────────────────────────────
+
+export interface AllowParams {
+  methods?: string[];
+  pathGlob?: string;
+  path_glob?: string;
+  policyId?: string;
+  policy_id?: string;
+  resourceId?: string;
+  resource_id?: string;
+  resourceType?: string;
+  resource_type?: string;
+  note?: string;
+}
+
+export interface PolicyCreateParams {
+  name: string;
+  mode?: EgressPolicyMode | string;
+  defaultEffect?: EgressRuleEffect | string;
+  default_effect?: EgressRuleEffect | string;
+  resourceId?: string;
+  resource_id?: string;
+  resourceType?: string;
+  resource_type?: string;
+  description?: string;
+}
+
+export interface PolicyUpdateParams {
+  mode?: EgressPolicyMode | string;
+  defaultEffect?: EgressRuleEffect | string;
+  default_effect?: EgressRuleEffect | string;
+  name?: string;
+  description?: string;
+}
+
+export interface ModeParams {
+  policyId?: string;
+  policy_id?: string;
+  resourceId?: string;
+  resource_id?: string;
+  resourceType?: string;
+  resource_type?: string;
+}
+
+export interface SuggestionsParams {
+  resourceId?: string;
+  resource_id?: string;
+  resourceType?: string;
+  resource_type?: string;
+  since?: string;
+}
+
+export interface PolicyListParams {
+  resourceId?: string;
+  resource_id?: string;
+  resourceType?: string;
+  resource_type?: string;
+}
+
+export interface RulesListParams {
+  policyId?: string;
+  policy_id?: string;
+  resourceId?: string;
+  resource_id?: string;
+  resourceType?: string;
+  resource_type?: string;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+interface WireEnvelope<T> {
+  data?: T;
+  policy?: T;
+  rule?: T;
+  items?: T;
+}
+
+function unwrap<T>(payload: unknown): T {
+  if (payload && typeof payload === "object") {
+    const p = payload as Record<string, unknown>;
+    for (const k of ["data", "policy", "rule", "items"]) {
+      if (k in p) return p[k] as T;
+    }
+  }
+  return payload as T;
+}
+
+function unwrapList<T>(payload: unknown): T[] {
+  if (Array.isArray(payload)) return payload as T[];
+  if (payload && typeof payload === "object") {
+    const p = payload as Record<string, unknown>;
+    for (const k of [
+      "data",
+      "policies",
+      "rules",
+      "allowlist",
+      "suggestions",
+      "items",
+    ]) {
+      if (Array.isArray(p[k])) return p[k] as T[];
+    }
+  }
+  return [];
+}
+
+function stripUndefined(
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, v]) => v !== undefined),
+  );
+}
+
+function pickFirst<T>(...values: Array<T | undefined>): T | undefined {
+  for (const v of values) if (v !== undefined) return v;
+  return undefined;
+}
+
+function ruleBody(
+  host: string,
+  params: AllowParams,
+  effect: EgressRuleEffect,
+): Record<string, unknown> {
+  return stripUndefined({
+    host,
+    effect,
+    methods: params.methods,
+    path_glob: pickFirst(params.pathGlob, params.path_glob),
+    policy_id: pickFirst(params.policyId, params.policy_id),
+    resource_id: pickFirst(params.resourceId, params.resource_id),
+    resource_type: pickFirst(params.resourceType, params.resource_type),
+    note: params.note,
+  });
+}
+
+// ── Main resource ─────────────────────────────────────────────────────────────
+
+export class EgressNetwork {
+  constructor(protected readonly http: HttpClient) {}
+
+  // ── allowlist ─────────────────────────────────────────────────────────────
+
+  /** Add an `allow` rule for `host` to the allowlist. */
+  async allow(
+    host: string,
+    params: AllowParams = {},
+  ): Promise<EgressAllowlistRule> {
+    const data = await this.http.post<WireEnvelope<EgressAllowlistRule>>(
+      "/egress/allowlist",
+      ruleBody(host, params, "allow"),
+    );
+    return unwrap<EgressAllowlistRule>(data);
+  }
+
+  /** Add a `deny` rule for `host` to the allowlist. */
+  async deny(
+    host: string,
+    params: AllowParams = {},
+  ): Promise<EgressAllowlistRule> {
+    const data = await this.http.post<WireEnvelope<EgressAllowlistRule>>(
+      "/egress/allowlist",
+      ruleBody(host, params, "deny"),
+    );
+    return unwrap<EgressAllowlistRule>(data);
+  }
+
+  /** List allowlist rules. */
+  async rules(params: RulesListParams = {}): Promise<EgressAllowlistRule[]> {
+    const query = stripUndefined({
+      policy_id: pickFirst(params.policyId, params.policy_id),
+      resource_id: pickFirst(params.resourceId, params.resource_id),
+      resource_type: pickFirst(params.resourceType, params.resource_type),
+    }) as Record<string, string | number | boolean | undefined>;
+    const data = await this.http.get<unknown>("/egress/allowlist", query);
+    return unwrapList<EgressAllowlistRule>(data);
+  }
+
+  /** Delete an allowlist rule by id. */
+  async removeRule(ruleId: string): Promise<void> {
+    await this.http.delete<unknown>(`/egress/allowlist/${ruleId}`);
+  }
+
+  // ── policies ──────────────────────────────────────────────────────────────
+
+  /** List egress policies. */
+  async policies(params: PolicyListParams = {}): Promise<EgressPolicyData[]> {
+    const query = stripUndefined({
+      resource_id: pickFirst(params.resourceId, params.resource_id),
+      resource_type: pickFirst(params.resourceType, params.resource_type),
+    }) as Record<string, string | number | boolean | undefined>;
+    const data = await this.http.get<unknown>("/egress/policies", query);
+    return unwrapList<EgressPolicyData>(data);
+  }
+
+  /** Create an egress policy. */
+  async createPolicy(params: PolicyCreateParams): Promise<EgressPolicyData> {
+    const body = stripUndefined({
+      name: params.name,
+      mode: params.mode ?? "enforce",
+      default_effect: pickFirst(
+        params.defaultEffect,
+        params.default_effect,
+        "deny" as EgressRuleEffect,
+      ),
+      resource_id: pickFirst(params.resourceId, params.resource_id),
+      resource_type: pickFirst(params.resourceType, params.resource_type),
+      description: params.description,
+    });
+    const data = await this.http.post<WireEnvelope<EgressPolicyData>>(
+      "/egress/policies",
+      body,
+    );
+    return unwrap<EgressPolicyData>(data);
+  }
+
+  /** Update an egress policy by id. */
+  async updatePolicy(
+    policyId: string,
+    params: PolicyUpdateParams,
+  ): Promise<EgressPolicyData> {
+    const body = stripUndefined({
+      mode: params.mode,
+      default_effect: pickFirst(params.defaultEffect, params.default_effect),
+      name: params.name,
+      description: params.description,
+    });
+    const data = await this.http.patch<WireEnvelope<EgressPolicyData>>(
+      `/egress/policies/${policyId}`,
+      body,
+    );
+    return unwrap<EgressPolicyData>(data);
+  }
+
+  // ── mode helpers ──────────────────────────────────────────────────────────
+
+  /** Set the policy to `mode="enforce"` — denied egress is blocked. */
+  async lockdown(params: ModeParams = {}): Promise<EgressPolicyData> {
+    return this.setMode("enforce", params);
+  }
+
+  /** Set the policy to `mode="audit_only"` — log but do not block. */
+  async observe(params: ModeParams = {}): Promise<EgressPolicyData> {
+    return this.setMode("audit_only", params);
+  }
+
+  private async setMode(
+    mode: EgressPolicyMode,
+    params: ModeParams,
+  ): Promise<EgressPolicyData> {
+    const policyId = pickFirst(params.policyId, params.policy_id);
+    const resourceId = pickFirst(params.resourceId, params.resource_id);
+    const resourceType = pickFirst(params.resourceType, params.resource_type);
+
+    if (policyId) {
+      return this.updatePolicy(policyId, { mode });
+    }
+
+    const body =
+      resourceId !== undefined && resourceType !== undefined
+        ? stripUndefined({
+            mode,
+            resource_id: resourceId,
+            resource_type: resourceType,
+          })
+        : { mode };
+    const data = await this.http.patch<WireEnvelope<EgressPolicyData>>(
+      "/egress/policies",
+      body,
+    );
+    return unwrap<EgressPolicyData>(data);
+  }
+
+  // ── suggestions ───────────────────────────────────────────────────────────
+
+  /** AI-generated allowlist suggestions from recent denied egress. */
+  async suggestions(
+    params: SuggestionsParams = {},
+  ): Promise<EgressSuggestion[]> {
+    const query = stripUndefined({
+      resource_id: pickFirst(params.resourceId, params.resource_id),
+      resource_type: pickFirst(params.resourceType, params.resource_type),
+      since: params.since ?? "7d",
+    }) as Record<string, string | number | boolean | undefined>;
+    const data = await this.http.get<unknown>(
+      "/egress/audit/suggestions",
+      query,
+    );
+    return unwrapList<EgressSuggestion>(data);
+  }
+}
+
+// ── Resource-scoped wrappers ─────────────────────────────────────────────────
+
+/**
+ * Sandbox-bound view of {@link EgressNetwork}. Pre-scopes
+ * `resource_id` + `resource_type="sandbox"` on every call.
+ */
+export class SandboxNetwork {
+  protected readonly resourceType: string = "sandbox";
+  private readonly delegate: EgressNetwork;
+
+  constructor(
+    http: HttpClient,
+    protected readonly resourceId: string,
+  ) {
+    this.delegate = new EgressNetwork(http);
+  }
+
+  private resolvedResourceId(params: {
+    resourceId?: string;
+    resource_id?: string;
+  }): string {
+    return params.resourceId ?? params.resource_id ?? this.resourceId;
+  }
+
+  private resolvedResourceType(params: {
+    resourceType?: string;
+    resource_type?: string;
+  }): string {
+    return params.resourceType ?? params.resource_type ?? this.resourceType;
+  }
+
+  allow(host: string, params: AllowParams = {}): Promise<EgressAllowlistRule> {
+    return this.delegate.allow(host, {
+      ...params,
+      resource_id: this.resolvedResourceId(params),
+      resource_type: this.resolvedResourceType(params),
+    });
+  }
+
+  deny(host: string, params: AllowParams = {}): Promise<EgressAllowlistRule> {
+    return this.delegate.deny(host, {
+      ...params,
+      resource_id: this.resolvedResourceId(params),
+      resource_type: this.resolvedResourceType(params),
+    });
+  }
+
+  rules(params: RulesListParams = {}): Promise<EgressAllowlistRule[]> {
+    return this.delegate.rules({
+      ...params,
+      resource_id: this.resolvedResourceId(params),
+      resource_type: this.resolvedResourceType(params),
+    });
+  }
+
+  removeRule(ruleId: string): Promise<void> {
+    return this.delegate.removeRule(ruleId);
+  }
+
+  lockdown(params: { policyId?: string } = {}): Promise<EgressPolicyData> {
+    const body: ModeParams = {
+      resource_id: this.resourceId,
+      resource_type: this.resourceType,
+    };
+    if (params.policyId !== undefined) body.policyId = params.policyId;
+    return this.delegate.lockdown(body);
+  }
+
+  observe(params: { policyId?: string } = {}): Promise<EgressPolicyData> {
+    const body: ModeParams = {
+      resource_id: this.resourceId,
+      resource_type: this.resourceType,
+    };
+    if (params.policyId !== undefined) body.policyId = params.policyId;
+    return this.delegate.observe(body);
+  }
+
+  suggestions(params: { since?: string } = {}): Promise<EgressSuggestion[]> {
+    const body: SuggestionsParams = {
+      resource_id: this.resourceId,
+      resource_type: this.resourceType,
+    };
+    if (params.since !== undefined) body.since = params.since;
+    return this.delegate.suggestions(body);
+  }
+
+  policies(): Promise<EgressPolicyData[]> {
+    return this.delegate.policies({
+      resource_id: this.resourceId,
+      resource_type: this.resourceType,
+    });
+  }
+}
+
+/** Computer-bound network — same surface, `resource_type="computer"`. */
+export class ComputerNetwork extends SandboxNetwork {
+  protected readonly resourceType: string = "computer";
+}