docs(ocr): OLLAMA_ORIGINS is not needed — drop the "one gotcha" and reword the 403 hint #31

Merged
daniel merged 1 commit from agent/ollama-origins-not-needed into main 2026-10-20 20:13:38 +02:00
Collaborator

Part of #28 (item 2, OLLAMA_ORIGINS). Docs plus one error message. No new behaviour.

Why (evidence, established empirically on #28)

The docs and the 403 hint tell every Ollama user to set OLLAMA_ORIGINS=app://obsidian.md. That is not needed for any of the plugin's OCR calls, for two independent reasons:

  1. The plugin's requests carry no Origin header. All OCR traffic (checkConnection, transcribe via obsidianHttp → requestUrl, src/main.ts:2388) and the v1 pull (nodeNdjson) sends none.
    • Obsidian 1.14.4's obsidian.asar main.js implements requestUrl as an IPC "request-url" handler that calls electron.net.request({url, method, redirect:"follow"}) in the main process, setting only Content-Type and the caller's headers.
    • Reproduced with Electron 43 net.request against a local header-echo server: GET and POST both arrive with origin=undefined (sec-fetch-mode: no-cors, sec-fetch-site: none).
  2. Ollama allows app://* by default anyway. It has done so since v0.1.42 (June 2024), in commit 1a29e9a8 "API app/browser access (#4879)". envconfig.AllowedOrigins() appends app://*, file://*, tauri://*, … to whatever OLLAMA_ORIGINS holds. It is absent in v0.1.41 and present in v0.1.42.
    • Tested against a real Ollama 0.40.4 started without OLLAMA_ORIGINS:
Origin header GET /api/version GET /v1/models POST /v1/chat/completions
none 200 200 404 (unknown model — passed CORS)
app://obsidian.md 200 200 404 (passed CORS)
https://evil.example (positive control) 403 403 403

So a 403 from a local Ollama with no API key now realistically means one of two things: an Ollama older than 0.1.42, or a proxy or other server in front of it. It does not mean "set OLLAMA_ORIGINS".

What to change

  1. docs/ocr-endpoint-setup.md

    • One-click setup (desktop) section (around line 30): replace the paragraph "It does not set OLLAMA_ORIGINS — if Test connection then reports …" with one sentence: no origin or CORS setting is needed. Keep the sentence about the manual steps being the fallback.
    • Ollama, step by step, step 2 ("The one gotcha — origin/CORS"): rewrite it as "2. No origin setting needed."
      • Say briefly that the plugin's requests carry no Origin header, and that Ollama 0.1.42+ accepts Obsidian's app:// origin by default.
      • Move the per-OS OLLAMA_ORIGINS instructions (macOS launchctl setenv, Linux systemctl edit, Windows env vars) under a clearly secondary note: "Only if you run an Ollama older than 0.1.42 and cannot update it". Updating Ollama is the first advice.
      • Keep the OLLAMA_HOST paragraph as is.
      • Keep the step numbering 1–4, so existing "step 3/4" references stay valid.
    • LM Studio equivalent, last paragraph: reword to say that neither server needs an origin allowlist.
    • Troubleshooting, 403 / forbidden row: say "Ollama older than 0.1.42 → update it (or set OLLAMA_ORIGINS as in step 2's note). With an API key set → the key was refused. Otherwise a proxy or the server's own access rules refused the request."
  2. src/transport/ocr.ts mapStatus() (line ~196–203). Reword the 403-without-API-key message and its comment above it. It should say:

    • the local endpoint refused the request;
    • Ollama 0.1.42 and later accept the plugin's requests as they are, so update Ollama;
    • on an older Ollama, set OLLAMA_ORIGINS=app://obsidian.md (or *) and restart it;
    • see docs/ocr-endpoint-setup.md → Troubleshooting.

    Keep the ${raw} suffix and the status code, and keep the branch order (403 without a key before 401/403 with a key). The message must still contain OLLAMA_ORIGINS, because the existing tests match on it.

  3. src/ollamasetup.ts, the failed-test notify in setUpLocalOllama (… See the setup guide: docs/ocr-endpoint-setup.md → step 2.): point it at → Troubleshooting instead, since step 2 is no longer where failures are explained.

  4. src/main.ts desktopNdjson() doc comment (line ~2405–2411): drop "so the pull works before OLLAMA_ORIGINS is set". Say instead that no Origin header goes out this way, as with requestUrl.

  5. CHANGELOG-INK.md → Unreleased: one bullet, e.g. "No OLLAMA_ORIGINS needed: the setup guide no longer asks you to set it; Ollama 0.1.42+ accepts the plugin's requests as they are."

Constraints and decisions

  • Decision: simplify the docs; do not automate OLLAMA_ORIGINS. The issue offered option (a), copy a command, and option (b), run launchctl/setx/systemd. Both are moot, so child_process stays out of the plugin.
  • Do not delete the 403 special case in mapStatus(). It is still the right first hint for old Ollama installs.
  • Out of scope: the LM Studio detect-and-guide work (sibling MR on agent/lmstudio-detect-guide) and the installer download (sibling MR on agent/ollama-installer-download). Those also touch docs/ocr-endpoint-setup.md's One-click setup section and src/ollamasetup.ts. Merge origin/main before you finish and resolve any overlap.

Validation contract

  • Red gate first: in src/__tests__/ocr.test.ts, add /update Ollama/i (or similar wording you choose) to the assertions of "403 without an API key points at OLLAMA_ORIGINS, not the key" (line ~30) and the second 403 assertion (line ~79). Run npm ci && npx vitest run src/__tests__/ocr.test.ts on the unchanged code → it FAILS on the new assertion.
  • After the change: npx vitest run src/__tests__/ocr.test.ts → PASS. Then npx vitest run → whole suite PASS, and npm run build → exits 0, ending with check-bundle's "bundle clean" line.
  • grep -n "OLLAMA_ORIGINS" docs/ocr-endpoint-setup.md → hits only in step 2's old-version note and the troubleshooting row, and none in the One-click setup section.
  • (The repo has no flake.nix, so use plain npm/npx, not nix develop.)

🤖 Generated with Claude Code

Part of #28 (item 2, `OLLAMA_ORIGINS`). Docs plus one error message. No new behaviour. ## Why (evidence, established empirically on #28) The docs and the 403 hint tell every Ollama user to set `OLLAMA_ORIGINS=app://obsidian.md`. **That is not needed** for any of the plugin's OCR calls, for two independent reasons: 1. **The plugin's requests carry no `Origin` header.** All OCR traffic (`checkConnection`, `transcribe` via `obsidianHttp` → `requestUrl`, `src/main.ts:2388`) and the v1 pull (`nodeNdjson`) sends none. - Obsidian 1.14.4's `obsidian.asar` `main.js` implements `requestUrl` as an IPC `"request-url"` handler that calls `electron.net.request({url, method, redirect:"follow"})` in the **main process**, setting only `Content-Type` and the caller's headers. - Reproduced with Electron 43 `net.request` against a local header-echo server: GET and POST both arrive with `origin=undefined` (`sec-fetch-mode: no-cors`, `sec-fetch-site: none`). 2. **Ollama allows `app://*` by default anyway.** It has done so since **v0.1.42 (June 2024)**, in commit `1a29e9a8` "API app/browser access (#4879)". `envconfig.AllowedOrigins()` appends `app://*`, `file://*`, `tauri://*`, … to whatever `OLLAMA_ORIGINS` holds. It is absent in v0.1.41 and present in v0.1.42. - Tested against a real Ollama 0.40.4 started **without** `OLLAMA_ORIGINS`: | Origin header | `GET /api/version` | `GET /v1/models` | `POST /v1/chat/completions` | |---|---|---|---| | none | 200 | 200 | 404 (unknown model — passed CORS) | | `app://obsidian.md` | 200 | 200 | 404 (passed CORS) | | `https://evil.example` (positive control) | **403** | **403** | **403** | So a 403 from a local Ollama with no API key now realistically means one of two things: an Ollama older than 0.1.42, or a proxy or other server in front of it. It does not mean "set OLLAMA_ORIGINS". ## What to change 1. **`docs/ocr-endpoint-setup.md`** - *One-click setup (desktop)* section (around line 30): replace the paragraph "It does not set `OLLAMA_ORIGINS` — if *Test connection* then reports …" with one sentence: no origin or CORS setting is needed. Keep the sentence about the manual steps being the fallback. - *Ollama, step by step*, **step 2** ("The one gotcha — origin/CORS"): rewrite it as **"2. No origin setting needed."** - Say briefly that the plugin's requests carry no `Origin` header, and that Ollama 0.1.42+ accepts Obsidian's `app://` origin by default. - Move the per-OS `OLLAMA_ORIGINS` instructions (macOS `launchctl setenv`, Linux `systemctl edit`, Windows env vars) under a clearly secondary note: *"Only if you run an Ollama older than 0.1.42 and cannot update it"*. Updating Ollama is the first advice. - Keep the `OLLAMA_HOST` paragraph as is. - **Keep the step numbering 1–4**, so existing "step 3/4" references stay valid. - *LM Studio equivalent*, last paragraph: reword to say that neither server needs an origin allowlist. - *Troubleshooting*, `403 / forbidden` row: say "Ollama older than 0.1.42 → update it (or set `OLLAMA_ORIGINS` as in step 2's note). With an API key set → the key was refused. Otherwise a proxy or the server's own access rules refused the request." 2. **`src/transport/ocr.ts` `mapStatus()`** (line ~196–203). Reword the 403-without-API-key message and its comment above it. It should say: - the local endpoint refused the request; - Ollama 0.1.42 and later accept the plugin's requests as they are, so update Ollama; - on an older Ollama, set `OLLAMA_ORIGINS=app://obsidian.md` (or `*`) and restart it; - see `docs/ocr-endpoint-setup.md → Troubleshooting`. Keep the `${raw}` suffix and the status code, and keep the branch order (403 without a key before 401/403 with a key). The message must still contain `OLLAMA_ORIGINS`, because the existing tests match on it. 3. **`src/ollamasetup.ts`**, the failed-test notify in `setUpLocalOllama` (`… See the setup guide: docs/ocr-endpoint-setup.md → step 2.`): point it at `→ Troubleshooting` instead, since step 2 is no longer where failures are explained. 4. **`src/main.ts` `desktopNdjson()` doc comment** (line ~2405–2411): drop "so the pull works before OLLAMA_ORIGINS is set". Say instead that no `Origin` header goes out this way, as with `requestUrl`. 5. **`CHANGELOG-INK.md`** → *Unreleased*: one bullet, e.g. "**No `OLLAMA_ORIGINS` needed:** the setup guide no longer asks you to set it; Ollama 0.1.42+ accepts the plugin's requests as they are." ## Constraints and decisions - **Decision:** simplify the docs; do not automate `OLLAMA_ORIGINS`. The issue offered option (a), copy a command, and option (b), run `launchctl`/`setx`/systemd. Both are moot, so `child_process` stays out of the plugin. - Do **not** delete the 403 special case in `mapStatus()`. It is still the right first hint for old Ollama installs. - Out of scope: the LM Studio detect-and-guide work (sibling MR on `agent/lmstudio-detect-guide`) and the installer download (sibling MR on `agent/ollama-installer-download`). Those also touch `docs/ocr-endpoint-setup.md`'s *One-click setup* section and `src/ollamasetup.ts`. Merge `origin/main` before you finish and resolve any overlap. ## Validation contract - **Red gate first:** in `src/__tests__/ocr.test.ts`, add `/update Ollama/i` (or similar wording you choose) to the assertions of `"403 without an API key points at OLLAMA_ORIGINS, not the key"` (line ~30) and the second 403 assertion (line ~79). Run `npm ci && npx vitest run src/__tests__/ocr.test.ts` **on the unchanged code** → it FAILS on the new assertion. - After the change: `npx vitest run src/__tests__/ocr.test.ts` → PASS. Then `npx vitest run` → whole suite PASS, and `npm run build` → exits 0, ending with check-bundle's "bundle clean" line. - `grep -n "OLLAMA_ORIGINS" docs/ocr-endpoint-setup.md` → hits only in step 2's old-version note and the troubleshooting row, and none in the *One-click setup* section. - (The repo has no `flake.nix`, so use plain `npm`/`npx`, not `nix develop`.) 🤖 Generated with [Claude Code](https://claude.com/claude-code)
claude self-assigned this 2026-10-20 20:05:17 +02:00
Author
Collaborator

✅ Agent run completed

1m48s · 17 turns · $0.47 · pushed agent/ollama-origins-not-needed · session saved — new comments resume this run

✅ **Agent run completed** _1m48s · 17 turns · $0.47 · pushed `agent/ollama-origins-not-needed` · session saved — new comments resume this run_
The plugin's requests carry no Origin header, and Ollama 0.1.42+ allows
app:// origins by default, so the setup guide no longer asks users to set
OLLAMA_ORIGINS. The per-OS instructions stay as a note for older Ollama, and
the 403-without-key hint now says to update Ollama first.

Part of #28.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Author
Collaborator

What changed

  • docs/ocr-endpoint-setup.md:
    • One-click setup now says no origin or CORS setting is needed.
    • Step 2 is now "No origin setting needed." The per-OS OLLAMA_ORIGINS steps sit in a quoted note: "Only if you run an Ollama older than 0.1.42 and cannot update it". Steps are still numbered 1–4.
    • Reworded the LM Studio paragraph and the 403 troubleshooting row.
  • mapStatus() 403-without-key message now says the local endpoint refused the request and to update Ollama (0.1.42+ accepts the requests as they are). It still gives OLLAMA_ORIGINS=app://obsidian.md (or *) for older versions and points at → Troubleshooting. The ${raw} suffix and the branch order are unchanged.
  • ollamasetup.ts now points at → Troubleshooting. Also updated the desktopNdjson() comment and added a CHANGELOG-INK bullet.

Verify

  • Red gate: with the new /update Ollama/i assertions, ocr.test.ts failed 2 tests on the unchanged code.
  • After the change, npx vitest run passes (762 tests). npm run build exits 0 and ends with "bundle clean".
  • OLLAMA_ORIGINS now appears in the guide only in step 2's old-version note and the 403 row.
  • No CI pipeline has run for this branch yet.

Follow-ups

None. I merged origin/main and it was already up to date; the sibling MRs that touch One-click setup had not landed yet.

## What changed - `docs/ocr-endpoint-setup.md`: - One-click setup now says no origin or CORS setting is needed. - Step 2 is now **"No origin setting needed."** The per-OS `OLLAMA_ORIGINS` steps sit in a quoted note: *"Only if you run an Ollama older than 0.1.42 and cannot update it"*. Steps are still numbered 1–4. - Reworded the LM Studio paragraph and the 403 troubleshooting row. - `mapStatus()` 403-without-key message now says the local endpoint refused the request and to update Ollama (0.1.42+ accepts the requests as they are). It still gives `OLLAMA_ORIGINS=app://obsidian.md (or *)` for older versions and points at `→ Troubleshooting`. The `${raw}` suffix and the branch order are unchanged. - `ollamasetup.ts` now points at `→ Troubleshooting`. Also updated the `desktopNdjson()` comment and added a CHANGELOG-INK bullet. ## Verify - Red gate: with the new `/update Ollama/i` assertions, `ocr.test.ts` failed 2 tests on the unchanged code. - After the change, `npx vitest run` passes (762 tests). `npm run build` exits 0 and ends with "bundle clean". - `OLLAMA_ORIGINS` now appears in the guide only in step 2's old-version note and the 403 row. - No CI pipeline has run for this branch yet. ## Follow-ups None. I merged `origin/main` and it was already up to date; the sibling MRs that touch *One-click setup* had not landed yet.
daniel merged commit 665992f918 into main 2026-10-20 20:13:38 +02:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
daniel/obsidian-remarkable-round-trip!31
No description provided.