@raidiant/notifai 8.0.0 → 9.1.0

package/src/commands-init.ts

@@ -8,11 +8,12 @@ import { randomBytes } from 'node:crypto'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { parse as parseToml, stringify as stringifyToml } from 'smol-toml'
+import { ensurePrivateDirectory } from './atomic-file.js'
 import { ApiCallError, NetworkError, type ApiClient } from './client.js'
-import { type CliConfig } from './config.js'
+import { personalProjectConfigPath, type CliConfig } from './config.js'
 import { projectSlugFrom as inferredProjectSlugFrom } from './invocation-context.js'
-import type { SkillScope } from './native-skills.js'
-import { firstBlocker, type Readiness, type ReadinessRefresh, type ReadinessState } from './readiness.js'
+import { SKILLS_INSTALLER_SPEC, type SkillScope } from './native-skills.js'
+import { firstBlocker, readinessJson, type Readiness, type ReadinessRefresh, type ReadinessState } from './readiness.js'
 import { buildDraft, formatReceipt } from './send.js'
 import { loginCommand } from './commands-auth.js'
 import {
@@ -26,8 +27,15 @@ import {
 import { readyCompanionDevices, supportPageUrl } from './commands-devices.js'
 import { assessReadiness, remedyLine } from './commands-doctor.js'
 import { hooksInstallCommand, pickHarnessesToInstall } from './commands-hooks.js'
-import { observedCompanionReceipt, readSetupProof, writeSetupProof } from './commands-setup-proof.js'
-import { SKILLS_SOURCE } from './commands-skill.js'
+import {
+  observedCompanionReceipt,
+  readSetupProof,
+  setupProofProject,
+  setupProofApplies,
+  setupProofIsStale,
+  writeSetupProof,
+} from './commands-setup-proof.js'
+import { listScopedNotifaiSkills, SKILLS_SOURCE } from './commands-skill.js'
 
 // ---------------------------------------------------------------------------
 // init
@@ -39,7 +47,12 @@ export function projectSlugFrom(name: string): string {
   return inferredProjectSlugFrom(name) ?? 'project'
 }
 
+/** Project checkout vs this machine. Drives skill, hooks, and config together. */
+export type SetupScope = SkillScope
+
 export interface InitFlags {
+  /** Emit the final shared readiness model and never prompt. */
+  json?: boolean
   projectId?: string
   /**
    * Install the agent guidance skill. Tri-state on purpose:
@@ -48,7 +61,13 @@ export interface InitFlags {
    * never spawn npx against the network by default.
    */
   skills?: boolean
-  /** Scope selected by an unattended caller; humans choose inside npx skills. */
+  /**
+   * One setup-scope for skill, hooks, and config. The unattended answer to
+   * init's single project-vs-machine question. Pairing, devices, and the CLI
+   * binary are not this flag.
+   */
+  setupScope?: SetupScope
+  /** Alias of `--setup-scope` when installing the skill unattended. */
   skillsScope?: SkillScope
   /** Same tri-state, for the harness hooks. */
   hooks?: boolean
@@ -97,12 +116,17 @@ async function closeGap(
   flags: InitFlags,
 ): Promise<GapCloseResult> {
   if (state.id === 'project') {
-    const configPath = path.join(deps.cwd, '.notifai', 'config.toml')
+    const slug = projectSlugFrom(flags.projectId ?? path.basename(deps.cwd))
+    const configPath =
+      flags.setupScope === 'global'
+        ? personalProjectConfigPath(deps.cwd, deps.env)
+        : path.join(deps.cwd, '.notifai', 'config.toml')
     const existing = existsSync(configPath)
       ? (parseToml(readFileSync(configPath, 'utf8')) as Record<string, unknown>)
       : {}
-    existing['project'] = projectSlugFrom(flags.projectId ?? path.basename(deps.cwd))
-    mkdirSync(path.dirname(configPath), { recursive: true })
+    existing['project'] = slug
+    if (flags.setupScope === 'global') ensurePrivateDirectory(path.dirname(configPath))
+    else mkdirSync(path.dirname(configPath), { recursive: true })
     writeFileSync(configPath, `${stringifyToml(existing)}\n`)
     return 'closed'
   }
@@ -111,8 +135,9 @@ async function closeGap(
     const harnesses = await pickHarnessesToInstall(deps)
     if (harnesses === null || harnesses.length === 0) return 'failed'
     let ok = true
+    const hookFlags = flags.setupScope === 'global' ? { global: true as const } : {}
     for (const harness of harnesses) {
-      if (hooksInstallCommand(deps, { harness }) !== EXIT.ok) ok = false
+      if (hooksInstallCommand(deps, { harness, ...hookFlags }) !== EXIT.ok) ok = false
     }
     return ok ? 'closed' : 'failed'
   }
@@ -130,22 +155,43 @@ async function closeGap(
       )
       return 'failed'
     }
-    const scopeText = flags.skillsScope === undefined ? 'the scope you choose' : `${flags.skillsScope} scope`
-    deps.io.out(`Starting the native npx skills setup for the notifai agent skill (${scopeText})...`)
-    const addOptions = {
+    const installScope = flags.setupScope ?? flags.skillsScope
+    if (installScope === undefined) {
+      deps.io.err(
+        'Skill installation refused — choose a setup scope: `notifai init --skills --setup-scope project` or `... global`.',
+      )
+      return 'failed'
+    }
+    const { installed } = await listScopedNotifaiSkills(deps)
+    const extras = installed.filter((skill) => skill.scope !== installScope)
+    for (const extra of extras) {
+      const code = await deps.nativeSkills.remove({
+        skill: 'notifai',
+        scope: extra.scope,
+        cwd: deps.cwd,
+        env: deps.env,
+      })
+      if (code !== 0) {
+        deps.io.err(
+          `Skill installation refused — could not uninstall the ${extra.scope} copy (${extra.ref ?? 'unknown pin'}), so installing ${installScope} would leave both active.`,
+        )
+        return 'failed'
+      }
+    }
+    deps.io.out(`Starting the native npx skills setup for the notifai agent skill (${installScope} scope)...`)
+    const code = await deps.nativeSkills.add({
       source: SKILLS_SOURCE,
       skill: 'notifai',
       cwd: deps.cwd,
       env: deps.env,
-      ...(flags.skillsScope === undefined ? {} : { scope: flags.skillsScope }),
-    }
-    const code = await deps.nativeSkills.add(addOptions)
+      scope: installScope,
+    })
     if (code !== 0) {
       deps.io.err('Skill installation failed — run it manually with:')
       deps.io.err(
-        `  npx skills add ${SKILLS_SOURCE} --skill notifai${
-          flags.skillsScope === 'global' ? ' --global' : ''
-        }${flags.skillsScope === undefined ? '' : ' --yes'}`,
+        `  npx -y ${SKILLS_INSTALLER_SPEC} add ${SKILLS_SOURCE} --skill notifai${
+          installScope === 'global' ? ' --global' : ''
+        } --yes`,
       )
     }
     return code === 0 ? 'closed' : 'failed'
@@ -289,7 +335,6 @@ function setupProofDraft(
       project === null
         ? 'This real notification completed setup verification.'
         : `This real notification completed setup verification for ${project}.`,
-    event: 'setup_verified',
     kind: 'update',
     platform: device.platform,
     device: [device.device_id],
@@ -356,21 +401,41 @@ async function runSetupProof(deps: CommandDeps): Promise<GapCloseResult> {
     return 'failed'
   }
   const candidates = readyCompanionDevices(devices)
-  const existing = readSetupProof(deps)
-  const target =
-    candidates.find(
-      (device) =>
-        device.device_id === existing?.device_id && existing.project === config.project.value,
-    ) ?? candidates[0]
+  const project = setupProofProject(deps, config.project.value)
+  const existing = readSetupProof(deps, project)
+  const existingApplies = setupProofApplies(
+    existing,
+    project,
+    candidates.map((device) => device.device_id),
+  )
+  const target = (existingApplies
+    ? candidates.find((device) => device.device_id === existing.device_id)
+    : undefined) ?? candidates[0]
   if (!target) {
     deps.io.err('Setup proof needs a receipt-capable iPhone or Android Companion App.')
     return 'pending'
   }
 
   let proof =
-    existing?.device_id === target.device_id && existing.project === config.project.value
+    existingApplies && existing.device_id === target.device_id
       ? existing
       : null
+  const nowMs = (deps.now ?? Date.now)()
+  if (proof !== null && setupProofIsStale(proof, nowMs)) {
+    let keepStale = false
+    try {
+      const snapshot = await authed.client.evidence(proof.request_id)
+      keepStale = observedCompanionReceipt(snapshot, proof.device_id) !== null
+    } catch {
+      keepStale = false
+    }
+    if (!keepStale) {
+      deps.io.out(
+        `The saved proof ${proof.request_id} is older than 24h without a Companion Receipt; sending a replacement.`,
+      )
+      proof = null
+    }
+  }
   if (proof === null) {
     const receipt = await submitSetupProof(deps, authed.client, config, target)
     if (receipt === null) return 'failed'
@@ -381,7 +446,7 @@ async function runSetupProof(deps: CommandDeps): Promise<GapCloseResult> {
     proof = {
       request_id: receipt.request_id,
       device_id: target.device_id,
-      project: config.project.value,
+      project,
       started_at: new Date((deps.now ?? Date.now)()).toISOString(),
     }
     if (!writeSetupProof(deps, proof)) return 'failed'
@@ -429,7 +494,7 @@ async function runSetupProof(deps: CommandDeps): Promise<GapCloseResult> {
         proof = {
           request_id: receipt.request_id,
           device_id: target.device_id,
-          project: config.project.value,
+          project,
           started_at: new Date(now()).toISOString(),
         }
         if (!writeSetupProof(deps, proof)) return 'failed'
@@ -503,36 +568,93 @@ function wantsOptional(deps: CommandDeps, state: ReadinessState, flags: InitFlag
  * and a revoked credential are the same code path arriving at different
  * states rather than four branches to enumerate.
  */
-export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<number> {
+function isSetupScope(value: string | undefined): value is SetupScope {
+  return value === 'project' || value === 'global'
+}
+
+async function resolveSetupScope(
+  deps: CommandDeps,
+  flags: InitFlags,
+): Promise<SetupScope | undefined | 'usage'> {
+  if (flags.setupScope !== undefined && !isSetupScope(flags.setupScope)) {
+    deps.io.err('Invalid setup scope. Choose `project` or `global`.')
+    return 'usage'
+  }
+  if (flags.skillsScope !== undefined && !isSetupScope(flags.skillsScope)) {
+    deps.io.err('Invalid skill scope. Choose `project` or `global`.')
+    return 'usage'
+  }
   if (
+    flags.setupScope !== undefined &&
     flags.skillsScope !== undefined &&
-    flags.skillsScope !== 'project' &&
-    flags.skillsScope !== 'global'
+    flags.setupScope !== flags.skillsScope
   ) {
-    deps.io.err('Invalid skill scope. Choose `project` or `global`.')
-    return EXIT.usage
+    deps.io.err('`--setup-scope` and `--skills-scope` disagree. Pass one, or pass the same value twice.')
+    return 'usage'
   }
   if (flags.skillsScope !== undefined && flags.skills !== true) {
-    deps.io.err('`--skills-scope` requires `--skills`. Choose project or global in the native installer.')
-    return EXIT.usage
+    deps.io.err('`--skills-scope` requires `--skills`. Use `--setup-scope` to choose project or machine for the whole setup.')
+    return 'usage'
   }
-  if (
-    flags.skills === true &&
-    deps.io.interactive !== true &&
-    flags.skillsScope === undefined
-  ) {
+  const fromFlags = flags.setupScope ?? flags.skillsScope
+  if (fromFlags !== undefined) return fromFlags
+  if (flags.skills === false && flags.hooks === false) return undefined
+  if (deps.io.interactive === true && deps.io.select) {
+    const selected = await deps.io.select(
+      'Should this Notifai setup apply to this project only, or to every project on this machine?',
+      [
+        {
+          value: 'project',
+          label: 'This project',
+          hint: 'skill, hooks, and shared config stay in this checkout',
+        },
+        {
+          value: 'global',
+          label: 'This machine',
+          hint: 'skill and hooks follow you into every repo',
+        },
+      ],
+    )
+    if (selected === 'project' || selected === 'global') return selected
+    deps.io.err('No setup scope selected. Pass `--setup-scope project` or `--setup-scope global`.')
+    return 'usage'
+  }
+  if (flags.skills === true) {
     deps.io.err(
-      'Unattended skill setup requires an explicit scope: `notifai init --skills --skills-scope project` or `... global`.',
+      'Unattended skill setup requires an explicit scope: `notifai init --skills --setup-scope project` or `... global`.',
     )
-    return EXIT.usage
+    return 'usage'
+  }
+  return undefined
+}
+
+export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<number> {
+  const workingDeps: CommandDeps = flags.json === true
+    ? {
+        ...deps,
+        io: {
+          interactive: false,
+          out: () => {},
+          err: (line) => deps.io.err(line),
+          confirm: async () => false,
+          openUrl: (url) => deps.io.openUrl(url),
+        },
+      }
+    : deps
+  const setupScope = await resolveSetupScope(workingDeps, flags)
+  if (setupScope === 'usage') return EXIT.usage
+  const resolved: InitFlags = {
+    ...flags,
+    ...(setupScope === undefined ? {} : { setupScope, skillsScope: flags.skillsScope ?? setupScope }),
   }
-  await deps.io.intro?.('Notifai setup')
+  await workingDeps.io.intro?.('Notifai setup')
 
-  const skillOpts = flags.skillsScope === undefined ? {} : { skillScope: flags.skillsScope }
-  let readiness = await assessReadiness(deps, skillOpts)
+  const skillOpts = resolved.setupScope === undefined ? {} : { skillScope: resolved.setupScope }
+  let readiness = await assessReadiness(workingDeps, { ...skillOpts, ...(flags.json === true ? { json: true } : {}) })
   const reassess = (refresh?: readonly ReadinessRefresh[]) =>
-    assessReadiness(deps, {
+    assessReadiness(workingDeps, {
       ...skillOpts,
+      ...(flags.json === true ? { json: true } : {}),
       ...(refresh === undefined ? {} : { previous: readiness, refresh }),
     })
   let failed = false
@@ -560,9 +682,9 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
       }
 
       if (state.status === 'optional-gap') {
-        if (remedy.by !== 'cli' || !(await wantsOptional(deps, state, flags))) continue
+        if (remedy.by !== 'cli' || !(await wantsOptional(workingDeps, state, resolved))) continue
         attempted.add(state.id)
-        const result = await closeGap(deps, state, flags)
+        const result = await closeGap(workingDeps, state, resolved)
         if (result === 'failed') failed = true
         if (result === 'failed' && state.status === 'optional-gap') {
           readiness = await reassess(refreshAfterClose(state.id))
@@ -580,7 +702,7 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
 
       if (remedy.by === 'cli') {
         attempted.add(state.id)
-        const result = await closeGap(deps, state, flags)
+        const result = await closeGap(workingDeps, state, resolved)
         if (result === 'failed') failed = true
         if (result !== 'closed') {
           stop = true
@@ -596,11 +718,11 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
       if (
         remedy.by === 'user-here' &&
         remedy.interactive === true &&
-        deps.io.interactive === true
+        workingDeps.io.interactive === true
       ) {
         attempted.add(state.id)
-        deps.io.out('Opening your browser to approve this machine — Ctrl-C to stop.')
-        if ((await loginCommand(deps, {})) !== EXIT.ok) {
+        workingDeps.io.out('Opening your browser to approve this machine — Ctrl-C to stop.')
+        if ((await loginCommand(workingDeps, {})) !== EXIT.ok) {
           failed = true
           stop = true
           break
@@ -613,10 +735,10 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
       if (
         state.id === 'devices' &&
         remedy.by === 'user-elsewhere' &&
-        deps.io.interactive === true
+        workingDeps.io.interactive === true
       ) {
         attempted.add(state.id)
-        const result = await waitForReadyDevice(deps, state)
+        const result = await waitForReadyDevice(workingDeps, state)
         if (result === 'failed') failed = true
         if (result !== 'closed') {
           stop = true
@@ -635,10 +757,11 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
     if (stop || !advanced) break
   }
 
-  await printInitClose(deps, readiness, flags)
+  if (flags.json === true) deps.io.out(JSON.stringify(readinessJson(readiness), null, 2))
+  else await printInitClose(deps, readiness, resolved)
   const blocker = firstBlocker(readiness)
   if (blocker === null) return failed ? EXIT.failed : EXIT.ok
-  return failed || deps.io.interactive !== true ? EXIT.failed : EXIT.ok
+  return failed || workingDeps.io.interactive !== true ? EXIT.failed : EXIT.ok
 }
 
 function isHookSubstate(id: string): boolean {

package/src/commands-send-support.test.ts

@@ -0,0 +1,156 @@
+import { NOTIFICATION_IMAGE_MAX_BYTES } from '@raidiant/notifai-protocol'
+import { createServer, type Server } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { afterEach, describe, expect, it } from 'vitest'
+import { EXIT, type CommandDeps, type CommandIo } from './commands-core.js'
+import { readCappedBytes, uploadImage } from './commands-send-support.js'
+import type { ApiClient } from './client.js'
+
+let server: Server | undefined
+
+afterEach(async () => {
+  if (server) {
+    const closing = server
+    server = undefined
+    await new Promise<void>((resolve) => closing.close(() => resolve()))
+  }
+})
+
+async function serving(handler: Parameters<typeof createServer>[1]): Promise<string> {
+  server = createServer(handler)
+  await new Promise<void>((resolve) => server?.listen(0, '127.0.0.1', resolve))
+  const { port } = server.address() as AddressInfo
+  return `http://127.0.0.1:${port}`
+}
+
+function io(): CommandIo {
+  return {
+    out: () => undefined,
+    err: () => undefined,
+    confirm: async () => false,
+    openUrl: () => undefined,
+  }
+}
+
+describe('readCappedBytes', () => {
+  it('refuses Content-Length over the cap before reading the body', async () => {
+    const response = new Response(null, { headers: { 'content-length': '64' } })
+    expect(await readCappedBytes(response, 16)).toBe('too-large')
+  })
+
+  it('stops reading once the downloaded bytes exceed the cap', async () => {
+    const response = new Response(
+      new ReadableStream({
+        start(controller) {
+          controller.enqueue(new Uint8Array(12))
+          controller.enqueue(new Uint8Array(12))
+          controller.close()
+        },
+      }),
+    )
+    expect(await readCappedBytes(response, 16)).toBe('too-large')
+  })
+
+  it('returns a payload that fits the cap', async () => {
+    const payload = new Uint8Array([1, 2, 3, 4])
+    expect(await readCappedBytes(new Response(payload), 16)).toEqual(payload)
+  })
+})
+
+function uploadingClient(uploaded: number[]): ApiClient {
+  return {
+    createMediaUpload: async () => ({
+      media_id: 'med_1',
+      upload_url: 'https://upload.invalid/1',
+      upload_headers: {},
+      expires_at: new Date(Date.now() + 60_000).toISOString(),
+    }),
+    uploadMedia: async (_grant: unknown, bytes: Uint8Array) => {
+      uploaded.push(bytes.byteLength)
+    },
+  } as unknown as ApiClient
+}
+
+function refusingClient(): ApiClient {
+  return {
+    createMediaUpload: async () => {
+      throw new Error('must not request an upload')
+    },
+  } as unknown as ApiClient
+}
+
+describe('uploadImage remote fetch', () => {
+  it('uploads bytes under the media limit from an allowed self-hosted origin', async () => {
+    const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47])
+    const baseUrl = await serving((_request, response) => {
+      response.setHeader('content-type', 'image/png')
+      response.end(Buffer.from(png))
+    })
+    const uploaded: number[] = []
+    const deps = { io: io(), env: {}, cwd: '/tmp' } as CommandDeps
+
+    const result = await uploadImage(deps, uploadingClient(uploaded), `${baseUrl}/shot.png`, [
+      baseUrl,
+    ])
+    expect(result).toEqual({ ok: true, mediaId: 'med_1' })
+    expect(uploaded).toEqual([png.byteLength])
+  })
+
+  it('refuses that same loopback origin when the User has not allowed it', async () => {
+    const baseUrl = await serving((_request, response) => {
+      response.setHeader('content-type', 'image/png')
+      response.end(Buffer.from(new Uint8Array([0x89, 0x50, 0x4e, 0x47])))
+    })
+    const deps = { io: io(), env: {}, cwd: '/tmp' } as CommandDeps
+
+    const result = await uploadImage(deps, refusingClient(), `${baseUrl}/shot.png`)
+    expect(result.ok).toBe(false)
+    if (result.ok) throw new Error('expected refusal')
+    expect(result.exit).toBe(EXIT.usage)
+    expect(result.error).toContain('media_origins')
+  })
+
+  it('refuses a remote image whose Content-Length exceeds the server media limit', async () => {
+    const baseUrl = await serving((_request, response) => {
+      response.setHeader('content-type', 'image/png')
+      response.setHeader('content-length', String(NOTIFICATION_IMAGE_MAX_BYTES + 1))
+      response.end()
+    })
+    const deps = { io: io(), env: {}, cwd: '/tmp' } as CommandDeps
+
+    const result = await uploadImage(deps, refusingClient(), `${baseUrl}/huge.png`, [baseUrl])
+    expect(result.ok).toBe(false)
+    if (result.ok) throw new Error('expected refusal')
+    expect(result.exit).toBe(EXIT.usage)
+    expect(result.error).toContain(String(NOTIFICATION_IMAGE_MAX_BYTES))
+  })
+
+  it('refuses a redirect out of an allowed origin into an unallowed one', async () => {
+    const target = await serving((_request, response) => {
+      response.setHeader('content-type', 'image/png')
+      response.end(Buffer.from(new Uint8Array([0x89, 0x50, 0x4e, 0x47])))
+    })
+    // A second loopback origin the User never allowed. The first hop is
+    // trusted; the destination is not, and each hop is checked on its own.
+    const redirector = createServer((_request, response) => {
+      response.writeHead(302, { location: `${target}/shot.png` })
+      response.end()
+    })
+    await new Promise<void>((resolve) => redirector.listen(0, '127.0.0.1', resolve))
+    const { port } = redirector.address() as AddressInfo
+    const redirectOrigin = `http://127.0.0.1:${port}`
+    const deps = { io: io(), env: {}, cwd: '/tmp' } as CommandDeps
+
+    try {
+      const result = await uploadImage(deps, refusingClient(), `${redirectOrigin}/shot.png`, [
+        redirectOrigin,
+      ])
+      expect(result.ok).toBe(false)
+      if (result.ok) throw new Error('expected refusal')
+      expect(result.exit).toBe(EXIT.usage)
+      expect(result.error).toContain('media_origins')
+    } finally {
+      await new Promise<void>((resolve) => redirector.close(() => resolve()))
+    }
+  })
+})

package/src/commands-send-support.ts

@@ -1,8 +1,9 @@
-import { type ListRepliesResponse } from '@raidiant/notifai-protocol'
+import { NOTIFICATION_IMAGE_MAX_BYTES, type ListRepliesResponse } from '@raidiant/notifai-protocol'
 import { sha256Hex } from '@raidiant/notifai-protocol/node'
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { isRetryableReplyPollError, type ApiClient } from './client.js'
+import { fetchMediaUrl } from './url-policy.js'
 import { buildSourceContext, inferInvocationContext } from './invocation-context.js'
 import { readOrcaSessionTitle } from './orca-session-title.js'
 import { type DraftInvocation, type SendFlags } from './send.js'
@@ -209,17 +210,78 @@ type UploadResult =
   /** `error: null` means `reportError` already said it; do not print it twice. */
   | { ok: false; error: string | null; exit: number }
 
-/** `--image` accepts a media id, a local file path, or an http(s) URL. */
-export async function uploadImage(deps: CommandDeps, client: ApiClient, source: string): Promise<UploadResult> {
+/**
+ * Read a remote image without buffering more than the server will accept.
+ *
+ * Content-Length is an early refusal, not trust: a lying header still hits
+ * the byte cap while the body is read. Supported schemes stay http and https.
+ */
+export async function readCappedBytes(
+  response: Response,
+  maxBytes: number,
+): Promise<Uint8Array | 'too-large'> {
+  const contentLength = Number(response.headers.get('content-length'))
+  if (Number.isFinite(contentLength) && contentLength > maxBytes) return 'too-large'
+  const reader = response.body?.getReader()
+  if (reader === undefined) {
+    const buf = new Uint8Array(await response.arrayBuffer())
+    return buf.byteLength > maxBytes ? 'too-large' : buf
+  }
+  const chunks: Uint8Array[] = []
+  let received = 0
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    received += value.byteLength
+    if (received > maxBytes) {
+      await reader.cancel()
+      return 'too-large'
+    }
+    chunks.push(value)
+  }
+  const out = new Uint8Array(received)
+  let offset = 0
+  for (const chunk of chunks) {
+    out.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return out
+}
+
+/**
+ * `--image` accepts a media id, a local file path, or an http(s) URL.
+ *
+ * A remote URL is fetched under the media URL policy (`url-policy.ts`):
+ * public HTTPS by default, every redirect hop re-validated, and non-public
+ * destinations only through the User's `media_origins` — never a
+ * repository's. `--image` values routinely arrive from an agent that read
+ * them in a working tree, so the URL is hostile input until proven otherwise.
+ */
+export async function uploadImage(
+  deps: CommandDeps,
+  client: ApiClient,
+  source: string,
+  allowOrigins: readonly string[] = [],
+): Promise<UploadResult> {
   let bytes: Uint8Array
   let mediaType: 'image/jpeg' | 'image/png' | 'image/gif' | undefined
   if (/^https?:\/\//.test(source)) {
     try {
-      const response = await fetch(source)
+      const fetched = await fetchMediaUrl(source, { allowOrigins }, deps.fetchImpl)
+      if (!fetched.ok) return { ok: false, error: fetched.reason, exit: EXIT.usage }
+      const response = fetched.response
       if (!response.ok) return { ok: false, error: `Could not fetch ${source} (${response.status}).`, exit: EXIT.usage }
       const contentType = response.headers.get('content-type')?.split(';')[0]?.trim() ?? ''
       mediaType = (['image/jpeg', 'image/png', 'image/gif'] as const).find((t) => t === contentType)
-      bytes = new Uint8Array(await response.arrayBuffer())
+      const downloaded = await readCappedBytes(response, NOTIFICATION_IMAGE_MAX_BYTES)
+      if (downloaded === 'too-large') {
+        return {
+          ok: false,
+          error: `Remote image exceeds the ${NOTIFICATION_IMAGE_MAX_BYTES} byte media limit.`,
+          exit: EXIT.usage,
+        }
+      }
+      bytes = downloaded
     } catch (err) {
       return { ok: false, error: `Could not fetch ${source}: ${String(err)}`, exit: EXIT.network }
     }