rnxsim 0.1.516 → 0.1.518

package/src/cloud.ts

@@ -9,22 +9,39 @@
 // public surface.
 
 import { isLoopbackHost } from './backend-origin'
+import type { SimStateOptions } from './bridge-contract'
 import { isRnxScreenCapture, type RnxScreenCapture } from './capture-contract'
 import {
+  isRnxCloudCommandScope,
   isRnxCloudCommandType,
   RNX_CLOUD_COMMAND_TYPES,
   RNX_CLOUD_MAX_ARTIFACT_BYTES,
+  RNX_CLOUD_SCOPED_TOKEN_PREFIX,
   RNX_CLOUD_TOKEN_SCOPES,
   rnxCloudCommandScope,
   rnxCloudScopesAllowCommand,
   type RnxCloudBoxCreateReceipt,
   type RnxCloudClaim,
+  type RnxCloudCommandScope,
   type RnxCloudCreateReceipt,
+  type RnxCloudScopedToken,
 } from './cloud-contract'
 import { rnxPublicBrand } from './public-brand'
 
-export { isRnxCloudCommandType, RNX_CLOUD_COMMAND_TYPES, RNX_CLOUD_MAX_ARTIFACT_BYTES }
-export type { RnxCloudClaim, RnxCloudCreateReceipt, RnxScreenCapture }
+export {
+  isRnxCloudCommandScope,
+  isRnxCloudCommandType,
+  RNX_CLOUD_COMMAND_TYPES,
+  RNX_CLOUD_MAX_ARTIFACT_BYTES,
+  RNX_CLOUD_SCOPED_TOKEN_PREFIX,
+}
+export type {
+  RnxCloudClaim,
+  RnxCloudCommandScope,
+  RnxCloudCreateReceipt,
+  RnxCloudScopedToken,
+  RnxScreenCapture,
+}
 
 const DEFAULT_DEVICE = 'iphone-16'
 const DEFAULT_WAIT_READY_MS = 20_000
@@ -51,6 +68,15 @@ export interface CreateRemoteSimulatorInput {
   sha256?: string
 }
 
+// attach to a simulator another process created. the token is the full
+// per-simulator token or a scoped `sk_rnx_sim_` token holding the scopes the
+// verbs below need.
+export interface ConnectRemoteSimulatorInput {
+  id: string
+  token: string
+  origin?: string
+}
+
 // the simulator-driving verbs. the same vocabulary the CLI drives, one for
 // one: `rnx describe`, `rnx do tap`, `rnx wait selector`.
 export interface RnxCommands {
@@ -68,16 +94,26 @@ export interface RnxCommands {
   screenshot(options?: { layers?: 'full' | 'tenant' | 'shell' }): Promise<string>
   capture(): Promise<RnxScreenCapture>
   reset(): Promise<unknown>
+  // the one-call read: screenshot, tree, route, and recent errors together.
+  state(options?: SimStateOptions): Promise<unknown>
 }
 
 interface RemoteSimulatorSession {
   origin: string
-  boxId: string
-  boxToken: string
+  // present on the create path only. a connected simulator never learned its
+  // box, so closing one stops the simulator rather than its box.
+  boxId: string | null
+  boxToken: string | null
   simId: string
   simulatorToken: string
-  claim: RnxCloudClaim
+  // null until the simulator reports one. connect takes no claim and steals
+  // none, so an unconfirmed simulator attaches with none.
+  claim: RnxCloudClaim | null
   artifact: RnxCloudCreateReceipt['artifact']
+  // what this token may send. the create path carries every scope except
+  // debug; a connected simulator carries what its token was minted with, and
+  // verbs outside it are refused before any request.
+  scopes: readonly RnxCloudCommandScope[]
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -333,7 +369,10 @@ function readBoxCreate(
   }
 }
 
-function cloudCommand(command: { type: string; [key: string]: unknown }): RemoteCommand {
+function cloudCommand(
+  command: { type: string; [key: string]: unknown },
+  scopes: readonly RnxCloudCommandScope[],
+): RemoteCommand {
   const clean: Record<string, unknown> = {}
   for (const [key, value] of Object.entries(command)) {
     if (key !== 'id' && key !== 'simId') clean[key] = value
@@ -341,9 +380,10 @@ function cloudCommand(command: { type: string; [key: string]: unknown }): Remote
   if (!isRnxCloudCommandType(command.type)) {
     throw new Error(`RNX Cloud does not support bridge command type ${command.type}`)
   }
-  // the customer sdk never carries debug: evaluate/call/close belong to the
-  // account api key caller. refusing here names the scope before a request.
-  if (!rnxCloudScopesAllowCommand(RNX_CLOUD_TOKEN_SCOPES, command.type)) {
+  // a verb outside this token's scopes never leaves the sdk: the refusal
+  // names the scope before a request. the full token carries every scope
+  // except debug, so evaluate/call/close stop here for it.
+  if (!rnxCloudScopesAllowCommand(scopes, command.type)) {
     throw new Error(
       `RNX Cloud command ${command.type} requires the ${rnxCloudCommandScope(command.type)} scope`,
     )
@@ -394,6 +434,10 @@ export class RemoteSimulator {
         return result
       },
       reset: () => this.sendCommand({ type: 'reset' }),
+      state: (options) =>
+        this.sendCommand(
+          options === undefined ? { type: 'state' } : { type: 'state', stateOptions: options },
+        ),
     }
   }
 
@@ -401,11 +445,18 @@ export class RemoteSimulator {
     return this.session.simId
   }
 
-  get claim(): RnxCloudClaim {
+  get claim(): RnxCloudClaim | null {
     return this.session.claim
   }
 
+  get scopes(): readonly RnxCloudCommandScope[] {
+    return this.session.scopes
+  }
+
   get receipt(): RnxCloudCreateReceipt {
+    if (!this.session.claim) {
+      throw new Error('this simulator was attached with connect() and holds no claim')
+    }
     return {
       simId: this.session.simId,
       artifact: this.session.artifact,
@@ -419,8 +470,10 @@ export class RemoteSimulator {
   ): Promise<unknown> {
     const body = {
       id: globalThis.crypto.randomUUID(),
-      claimId: this.session.claim.id,
-      command: cloudCommand(command),
+      // a scoped token drives without a claim: the service checks the token
+      // instead. a full token still joins the claim it names here.
+      claimId: this.session.claim?.id ?? '',
+      command: cloudCommand(command, this.session.scopes),
     }
     let response: Response
     try {
@@ -462,6 +515,10 @@ export class RemoteSimulator {
   }
 
   async confirm(): Promise<RnxCloudClaim> {
+    if (!this.session.claim) {
+      throw new Error('this simulator was attached with connect() and holds no claim')
+    }
+    const claimId = this.session.claim.id
     const response = await fetchWithCloudRetry(
       `${this.session.origin}/v1/sims/${encodeURIComponent(this.session.simId)}/claim`,
       {
@@ -470,7 +527,7 @@ export class RemoteSimulator {
           authorization: `Bearer ${this.session.simulatorToken}`,
           'content-type': 'application/json',
         },
-        body: JSON.stringify({ claimId: this.session.claim.id }),
+        body: JSON.stringify({ claimId }),
       },
     )
     const text = await response.text()
@@ -482,7 +539,7 @@ export class RemoteSimulator {
       throw new Error('RNX Cloud claim returned unreadable JSON')
     }
     const claim = readClaim(isRecord(parsed) ? parsed.claim : null)
-    if (claim.id !== this.session.claim.id) {
+    if (claim.id !== claimId) {
       throw new Error('RNX Cloud confirmation replaced the initial claim')
     }
     this.session = { ...this.session, claim }
@@ -490,13 +547,24 @@ export class RemoteSimulator {
   }
 
   async close(): Promise<void> {
-    const response = await fetchWithCloudRetry(
-      `${this.session.origin}/v1/boxes/${encodeURIComponent(this.session.boxId)}`,
-      {
-        method: 'DELETE',
-        headers: { authorization: `Bearer ${this.session.boxToken}` },
-      },
-    )
+    // the create path tears down the box it made. a connected simulator never
+    // learned its box, so it stops its own simulator instead; a scoped token
+    // is refused there, which is the service telling the holder it may drive
+    // but never delete.
+    const target =
+      this.session.boxId !== null && this.session.boxToken !== null
+        ? {
+            url: `${this.session.origin}/v1/boxes/${encodeURIComponent(this.session.boxId)}`,
+            authorization: `Bearer ${this.session.boxToken}`,
+          }
+        : {
+            url: `${this.session.origin}/v1/sims/${encodeURIComponent(this.session.simId)}`,
+            authorization: `Bearer ${this.session.simulatorToken}`,
+          }
+    const response = await fetchWithCloudRetry(target.url, {
+      method: 'DELETE',
+      headers: { authorization: target.authorization },
+    })
     const text = await response.text()
     if (!response.ok && response.status !== 404) {
       throw responseError(response.status, text)
@@ -560,7 +628,96 @@ export async function createRemoteSimulator(
     simulatorToken: created.simulatorToken,
     claim: created.receipt.simulator.claim,
     artifact: created.receipt.artifact,
+    scopes: RNX_CLOUD_TOKEN_SCOPES,
   })
   await simulator.confirm()
   return simulator
 }
+
+function readSimArtifact(value: unknown): RnxCloudCreateReceipt['artifact'] {
+  if (
+    !isRecord(value) ||
+    typeof value.sha256 !== 'string' ||
+    !/^[a-f0-9]{64}$/.test(value.sha256) ||
+    typeof value.bytes !== 'number' ||
+    !Number.isInteger(value.bytes) ||
+    value.bytes <= 0
+  ) {
+    throw new Error('RNX Cloud returned an invalid simulator artifact')
+  }
+  return { id: `sha256:${value.sha256}`, bytes: value.bytes }
+}
+
+function readConnectClaim(value: unknown): RnxCloudClaim | null {
+  if (value === null) return null
+  return readClaim(value)
+}
+
+function readConnectScopes(value: unknown, token: string): readonly RnxCloudCommandScope[] {
+  // the full per-simulator token carries every scope except debug, which the
+  // service already guarantees. a scoped token learns its verbs from the get
+  // it just made, so a verb outside them is refused before any request.
+  if (!token.startsWith(RNX_CLOUD_SCOPED_TOKEN_PREFIX)) return RNX_CLOUD_TOKEN_SCOPES
+  if (
+    !isRecord(value) ||
+    typeof value.id !== 'string' ||
+    !value.id ||
+    !Array.isArray(value.scopes) ||
+    value.scopes.length === 0 ||
+    !value.scopes.every(
+      (scope): scope is RnxCloudCommandScope =>
+        typeof scope === 'string' && isRnxCloudCommandScope(scope),
+    ) ||
+    typeof value.expiresAt !== 'number'
+  ) {
+    throw new Error('RNX Cloud returned an invalid scoped token')
+  }
+  return Object.freeze([...value.scopes])
+}
+
+// attach to a simulator another process created. one get proves the token,
+// and the simulator it returns drives with that token's scopes, takes no
+// claim, and never steals one.
+export async function connect(input: ConnectRemoteSimulatorInput): Promise<RemoteSimulator> {
+  if (!input.id) throw new Error('RNX Cloud connect needs a simulator id')
+  if (!input.token) throw new Error('RNX Cloud connect needs a token')
+  const origin = resolveOrigin(input.origin)
+  let response: Response
+  try {
+    response = await fetchWithCloudRetry(
+      `${origin}/v1/sims/${encodeURIComponent(input.id)}`,
+      { headers: { authorization: `Bearer ${input.token}` } },
+    )
+  } catch (error) {
+    throw new Error(
+      `could not reach RNX Cloud at ${origin}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    )
+  }
+  const text = await response.text()
+  if (!response.ok) throw responseError(response.status, text)
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    throw new Error('RNX Cloud connect returned unreadable JSON')
+  }
+  if (!isRecord(parsed) || !isRecord(parsed.sim)) {
+    throw new Error('RNX Cloud connect returned an invalid simulator')
+  }
+  const sim = parsed.sim
+  if (typeof sim.simId !== 'string' || !sim.simId) {
+    throw new Error('RNX Cloud connect returned an invalid simulator')
+  }
+  return new RemoteSimulator({
+    origin,
+    boxId: null,
+    boxToken: null,
+    simId: sim.simId,
+    simulatorToken: input.token,
+    claim: readConnectClaim(sim.claim ?? null),
+    artifact: readSimArtifact(sim.artifact),
+    scopes: readConnectScopes(isRecord(parsed) ? parsed.token : null, input.token),
+  })
+}