@nathanld/obsidian-server 0.0.1 → 0.0.2

package/README.md

@@ -4,30 +4,54 @@ Point it at any [Obsidian](https://obsidian.md) vault and get, out of the box:
 
 - an **MCP server** (Streamable HTTP, `/mcp`) exposing your vault's commands as tools to Claude and other MCP clients
 - a **REST API** (`/api/*`) over the same commands
-- **Bearer-token auth** (via [better-auth](https://www.better-auth.com/)'s API key plugin) protecting everything except a bare `/health` check
+- **two Bearer-token auth paths**, both via [better-auth](https://www.better-auth.com/) and both protecting everything except a bare `/health` check:
+  - a long-lived **API key** (better-auth's API key plugin) — unscoped, owner-minted, the simplest path for a client you trust with everything `--allow` exposes
+  - full **OAuth 2.1** (MCP Authorization spec, targeting spec revision **2026-07-28**, the locked release candidate as of 2026-05-21, with back-compat for the **2025-11-25** revision) — dynamic client registration or Client ID Metadata Documents, PKCE, scoped access tokens, for clients like claude.ai that expect to discover and authorize themselves
 
 It works by driving the official Obsidian CLI companion binary under the hood, then classifying and gating every command by how safe it is to expose to an LLM.
 
 ## Requirements
 
-- **Bun >= 1.2** — the server is Bun-only (it uses `bun:sqlite`, `Bun.serve`, and `Bun.spawn` directly; it will not run under Node).
+- **Node >= 18** (to run the published package via `npx`/`npm`), **or Bun >= 1.2** (to run it via `bunx`/`bun add`, or to build/run from source - the server itself is written against Bun APIs like `bun:sqlite`, `Bun.serve`, and `Bun.spawn`). You do not need both: see [Install / run](#install--run) below.
 - The **Obsidian desktop app** must be running, with its official CLI companion installed and on `PATH` (or pass `--binary <path>` to point at it explicitly). If the CLI can't be reached, `serve` exits with an error explaining how to fix it.
 
 ## Install / run
 
-Run it without installing anything:
+**No Bun required.** `@nathanld/obsidian-server` ships a native, self-contained binary for every supported platform (built with `bun build --compile`, the same approach [esbuild](https://esbuild.github.io/), [Biome](https://biomejs.dev/), and [Turborepo](https://turbo.build/) use), published as `optionalDependencies`. `npm`/`npx` on a supported platform installs and runs the matching binary directly - Node just spawns it, and Bun is never invoked:
+
+```sh
+npx @nathanld/obsidian-server serve
+```
+
+Or with Bun, if you already have it:
 
 ```sh
 bunx @nathanld/obsidian-server serve
 ```
 
-Or install it globally:
+Or install it globally with either:
 
 ```sh
+npm install -g @nathanld/obsidian-server
+obsidian-server serve
+
+# or
 bun add -g @nathanld/obsidian-server
 obsidian-server serve
 ```
 
+### Platform support
+
+| OS      | Arch       | Native binary |
+| ------- | ---------- | ------------- |
+| Linux   | x64, arm64 | yes           |
+| macOS   | x64, arm64 | yes           |
+| Windows | x64        | yes           |
+
+On any other platform/arch, or if the matching binary was skipped at install time (e.g. `npm install --omit=optional`), the CLI's launcher falls back to running the bundled `cli.js` under `bun` if `bun` is on `PATH`; if neither a native binary nor `bun` is available, it exits with an error explaining how to fix it (install without skipping optional dependencies, or install Bun).
+
+Either way, the **Obsidian desktop app + its CLI companion** (see [Requirements](#requirements)) is a runtime requirement regardless of how you install `@nathanld/obsidian-server` - it's what actually drives your vault.
+
 ## First run: the token flow
 
 The first time `serve` starts, it bootstraps a single local "owner" account and mints an API key automatically. That key is printed **exactly once**, in the startup banner:
@@ -71,10 +95,10 @@ claude mcp add --transport http obsidian http://127.0.0.1:3000/mcp --header "Aut
 obsidian-server <command> [flags]
 ```
 
-| Flag | Global |
-|---|---|
+| Flag              | Global                      |
+| ----------------- | --------------------------- |
 | `--version`, `-v` | Print the version and exit. |
-| `--help`, `-h` | Print usage and exit. |
+| `--help`, `-h`    | Print usage and exit.       |
 
 ### `serve`
 
@@ -82,18 +106,22 @@ obsidian-server <command> [flags]
 obsidian-server serve [--vault <name>] [--port 3000] [--host 127.0.0.1]
                        [--allow destructive] [--allow app-control]
                        [--data-dir <path>] [--binary <path>] [--timeout-ms <n>]
+                       [--public-url https://host[:port]]
+                       [--dangerously-allow-insecure-cimd-hosts]
 ```
 
-| Flag | Meaning |
-|---|---|
-| `--vault <name>` | Target a specific vault by name. Omit to use whatever vault is currently active in the running Obsidian app. |
-| `--port <n>` | Port to bind (default `3000`). |
-| `--host <host>` | Host/interface to bind (default `127.0.0.1`). See [Security](#security) before binding beyond localhost. |
-| `--allow destructive` | Also expose commands classified `destructive` (repeatable/combinable with `--allow app-control`). |
-| `--allow app-control` | Also expose commands classified `app-control`. |
-| `--data-dir <path>` | Override where the auth SQLite database lives. Defaults to `$XDG_DATA_HOME/obsidian-server`, or `~/.local/share/obsidian-server`. |
-| `--binary <path>` | Explicit path to the `obsidian` CLI binary, if it isn't on `PATH`. |
-| `--timeout-ms <n>` | Timeout for each underlying `obsidian` CLI invocation. |
+| Flag                                      | Meaning                                                                                                                                                                                                                       |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--vault <name>`                          | Target a specific vault by name. Omit to use whatever vault is currently active in the running Obsidian app.                                                                                                                  |
+| `--port <n>`                              | Port to bind (default `3000`).                                                                                                                                                                                                |
+| `--host <host>`                           | Host/interface to bind (default `127.0.0.1`). See [Security](#security) before binding beyond localhost.                                                                                                                      |
+| `--allow destructive`                     | Also expose commands classified `destructive` (repeatable/combinable with `--allow app-control`).                                                                                                                             |
+| `--allow app-control`                     | Also expose commands classified `app-control`.                                                                                                                                                                                |
+| `--data-dir <path>`                       | Override where the auth SQLite database lives. Defaults to `$XDG_DATA_HOME/obsidian-server`, or `~/.local/share/obsidian-server`.                                                                                             |
+| `--binary <path>`                         | Explicit path to the `obsidian` CLI binary, if it isn't on `PATH`.                                                                                                                                                            |
+| `--timeout-ms <n>`                        | Timeout for each underlying `obsidian` CLI invocation.                                                                                                                                                                        |
+| `--public-url https://host[:port]`        | The canonical OAuth issuer / MCP resource URL — the URL a remote client actually reaches this server through. Defaults to `http://<host>:<port>`, which only works for local clients. See [OAuth 2.1](#oauth-21-mcp-clients). |
+| `--dangerously-allow-insecure-cimd-hosts` | Allow Client ID Metadata Document URLs on `http:`/loopback/private hosts. Local testing only — never set this on a server reachable from anything but the machine running it.                                                 |
 
 ### `token`
 
@@ -109,13 +137,13 @@ obsidian-server token revoke --id <id> [--data-dir <path>]
 
 ## REST endpoints
 
-| Method | Path | Auth | Description |
-|---|---|---|---|
-| `GET` | `/health` | open | `{ ok, obsidian, vault }` — whether the server is up and whether the Obsidian CLI is currently reachable. |
-| `GET` | `/api/commands` | Bearer | List every exposed command (name, description, classification, options), given the current `--allow` flags. |
+| Method | Path                  | Auth   | Description                                                                                                                                                                                                                                                                                                                                       |
+| ------ | --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET`  | `/health`             | open   | `{ ok, obsidian, vault }` — whether the server is up and whether the Obsidian CLI is currently reachable.                                                                                                                                                                                                                                         |
+| `GET`  | `/api/commands`       | Bearer | List every exposed command (name, description, classification, options), given the current `--allow` flags.                                                                                                                                                                                                                                       |
 | `POST` | `/api/commands/:name` | Bearer | Run one command. JSON body is a flat object of option values (string/number/boolean); empty body is fine for commands that take no options. Returns `{ ok: true, stdout }`, or `{ ok: false, error }` with `404` (unknown command or gated-off), `400` (bad body/options), `504` (the CLI call timed out), or `502` (the CLI call itself failed). |
 
-Every route under `/api/*` (and `/mcp`, below) requires `Authorization: Bearer <token>`; a missing, malformed, unknown, expired, or disabled key all get an identical `401 { "error": "unauthorized" }` — see [Security](#security).
+Every route under `/api/*` (and `/mcp`, below) requires `Authorization: Bearer <token>` — either an API key or an OAuth access token (see [OAuth 2.1](#oauth-21-mcp-clients)). A missing or invalid credential of either kind gets a spec-shaped `401` with a `WWW-Authenticate: Bearer ...` challenge (see [Security](#security)); an OAuth token missing the scope a command needs gets `403 insufficient_scope` instead (API keys are unscoped and never hit this).
 
 ## MCP
 
@@ -124,16 +152,32 @@ Every route under `/api/*` (and `/mcp`, below) requires `Authorization: Bearer <
 - **`obsidian_<command>`** — one tool per exposed command, named by replacing `:` with `_` and prefixing `obsidian_` (e.g. the `daily:append` command becomes the `obsidian_daily_append` tool). Commands that aren't currently allowed (see gating, below) are never registered as tools at all — they don't exist, rather than existing and refusing.
 - **`server_commands`** — lists every currently-exposed command along with its MCP tool name, description, classification, and options, as JSON. Useful for a client to discover what's available without guessing tool names.
 
+Calling a tool with an OAuth access token that lacks the scope its command's classification requires (see below) doesn't refuse the call at the transport level — it returns a normal tool result with `isError: true` naming the missing scope, since JSON-RPC `tools/call` has no HTTP status code to carry instead.
+
+## OAuth 2.1 (MCP clients)
+
+Alongside API keys, this server is a **co-located OAuth 2.1 Authorization Server** for its own `/mcp` endpoint, implementing the MCP Authorization spec — targeting revision **2026-07-28** (the locked release candidate as of 2026-05-21), with back-compat for the **2025-11-25** revision's clients. This is what lets clients like claude.ai add the server themselves, with no manually-minted token: they discover the server's Authorization Server, register themselves (dynamically, or via a Client ID Metadata Document), and run the standard authorization-code-with-PKCE flow.
+
+- **Discovery**: `/.well-known/oauth-protected-resource/mcp` and `/.well-known/oauth-protected-resource` (RFC 9728) advertise this server's `resource` (the exact `/mcp` URL) and its Authorization Server; `/.well-known/oauth-authorization-server` (RFC 8414) advertises the OAuth endpoints, `S256`-only PKCE, and (RFC 9207 / RC 2026-07-28) `authorization_response_iss_parameter_supported`.
+- **Client registration**: `POST /api/auth/mcp/register` (RFC 7591 Dynamic Client Registration — no auth required to register, by design) **or** a Client ID Metadata Document (RC 2026-07-28): a `client_id` that's itself an HTTPS URL pointing at a small JSON document (`{client_id, client_name, redirect_uris}`). Both are supported side by side; `client_id_metadata_document_supported: true` is advertised in the Authorization Server metadata alongside `"none"` in `token_endpoint_auth_methods_supported`, which is what claude.ai checks for before preferring CIMD.
+- **Sign-in**: this is a single-owner server with no password login. The authorize flow redirects an unauthenticated browser to `/login`, which sends a one-time magic sign-in link — **printed to the terminal `obsidian-server` is running in**, not emailed anywhere (there's no email transport in a self-hosted, single-owner deployment).
+- **PKCE is required** (`S256` only — `plain` is rejected) on every authorization-code exchange.
+- **Scopes**: one scope per command classification — `vault:read`, `vault:write`, `vault:destructive`, `vault:app-control` — mapping 1:1 onto the `--allow` gates above. Only the classifications currently exposed by `--allow` are ever accepted or advertised; requesting a scope for a classification `--allow` doesn't currently expose is refused the same way an unrecognized scope would be.
+- **Refresh tokens**: request `offline_access` alongside another scope to get one back. This server additionally revokes the previous access/refresh token pair on every successful refresh (single-use rotation) — a hardening this server adds on top of the underlying OAuth plugin, which mints a new pair but doesn't invalidate the old one on its own.
+- **`--public-url`** is the issuer and the base of every URL above — it must be the URL a remote client actually reaches this server through (HTTPS, generally, for anything but same-machine clients). Defaults to `http://<host>:<port>`, which only works locally; the startup banner prints a warning when that default is in effect.
+
+API keys and OAuth access tokens are accepted interchangeably on every Bearer-protected route — this is additive, not a replacement; existing API-key-based setups keep working unmodified.
+
 ## Safety gating model
 
 The Obsidian CLI exposes a **102-command surface**. Every command is hand-classified into one of four tiers (`packages/obsidian-cli`'s `classify.ts`):
 
-| Classification | Exposed by default? | Meaning |
-|---|---|---|
-| `read` | Yes | Pure queries — no side effects on vault content or the app. |
-| `write` | Yes | Mutates vault note content (create/append/prepend a note, set a property, insert a template, toggle a task, ...). |
-| `destructive` | No — needs `--allow destructive` | Irreversibly removes or overwrites vault content (delete, remove a property, restore an older version over the current one). |
-| `app-control` | No — needs `--allow app-control` | Affects the running app/workspace rather than vault content: opening panes/tabs, plugin/theme/snippet management, sync pause/resume, restart/reload, running an arbitrary registered command by id, and the entire `Developer:` surface (DevTools protocol access, arbitrary `eval`). Treated as the most restricted tier even where an individual verb only reads data, because the blast radius or opacity is high. An unrecognized/future command name also defaults here. |
+| Classification | Exposed by default?              | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| -------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `read`         | Yes                              | Pure queries — no side effects on vault content or the app.                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `write`        | Yes                              | Mutates vault note content (create/append/prepend a note, set a property, insert a template, toggle a task, ...).                                                                                                                                                                                                                                                                                                                                                             |
+| `destructive`  | No — needs `--allow destructive` | Irreversibly removes or overwrites vault content (delete, remove a property, restore an older version over the current one).                                                                                                                                                                                                                                                                                                                                                  |
+| `app-control`  | No — needs `--allow app-control` | Affects the running app/workspace rather than vault content: opening panes/tabs, plugin/theme/snippet management, sync pause/resume, restart/reload, running an arbitrary registered command by id, and the entire `Developer:` surface (DevTools protocol access, arbitrary `eval`). Treated as the most restricted tier even where an individual verb only reads data, because the blast radius or opacity is high. An unrecognized/future command name also defaults here. |
 
 `read` and `write` are always exposed; `destructive` and `app-control` are opt-in per `serve` invocation via `--allow`, and only take effect for that run — nothing is ever persisted as "allowed" across restarts.
 
@@ -141,8 +185,69 @@ The Obsidian CLI exposes a **102-command surface**. Every command is hand-classi
 
 - **Binds to `127.0.0.1` by default.** Only requests from the same machine can reach it.
 - **Binding beyond localhost is not fully wired up yet.** Passing `--host 0.0.0.0` (or any non-localhost address) prints a startup warning that DNS-rebinding protection is disabled for that bind, because the underlying MCP transport only auto-enables its Host/Origin allowlist for localhost-class binds and this CLI does not yet expose flags to configure `allowedHosts`/`allowedOrigins` itself. Treat any non-localhost bind as unprotected against DNS rebinding until that's addressed, and prefer an SSH tunnel or reverse proxy you control instead of binding a public interface directly.
-- **Keys are hashed at rest.** better-auth's API key plugin hashes stored keys (SHA-256); the plaintext is only ever shown once, at mint time.
-- **Uniform 401s.** A missing header, malformed header, unknown key, expired key, or disabled key are all indistinguishable from the outside — every failure mode returns the same `401 { "error": "unauthorized" }` with a `WWW-Authenticate: Bearer` challenge, so nothing about *why* auth failed is observable.
+- **API keys are hashed at rest.** better-auth's API key plugin hashes stored keys (SHA-256); the plaintext is only ever shown once, at mint time. They are unscoped — an API key grants everything `--allow` currently exposes, with no per-command scope check (that's the OAuth model's job; see below).
+- **OAuth access tokens are opaque, single-audience, and scoped.** They're random strings stored in this server's own database — never a JWT, never verified any way but a database lookup — so they're only ever redeemable against this server (the RFC 8707 "audience binding" intent is satisfied structurally: there's no shared token namespace another resource server could accept). Each token carries the scopes (`vault:read`/`vault:write`/`vault:destructive`/`vault:app-control`) it was granted for, enforced per command classification on every `/mcp` tool call and `/api/*` request.
+- **Uniform 401s.** A missing header, malformed header, unknown/expired/disabled API key, or unknown/expired OAuth token are all indistinguishable from the outside — every failure mode returns a spec-shaped `401 { "error": "unauthorized" }` with a `WWW-Authenticate: Bearer error="invalid_token", ...` challenge (carrying `resource_metadata` and the currently-exposed `scope` list, per the MCP spec), so nothing about _why_ auth failed is observable. An authenticated-but-under-scoped OAuth request gets `403 insufficient_scope` instead, naming the missing scope.
+- **Client ID Metadata Document fetches are SSRF-guarded.** A CIMD `client_id` is unauthenticated attacker-controllable input (anyone can point an authorize request at any URL); this server only fetches `https:` URLs on non-private, non-loopback hosts unless `--dangerously-allow-insecure-cimd-hosts` is set (local testing only). This guard is about the metadata-document URL only — it never restricts `redirect_uris`, which legitimately include loopback addresses for native/CLI clients (RFC 8252).
+
+## Development
+
+This is a Bun monorepo: `apps/server` (the CLI/server entrypoint), `packages/auth` and `packages/obsidian-cli` (private workspace libraries bundled into it), plus `docs` and `scripts` (private, never published). The published artifact is npm's `@nathanld/obsidian-server` **main package** (built by `bun run build:dist` - see that script's header comment for exactly what it bundles) plus one **platform package** per supported OS/arch (`@nathanld/obsidian-server-<os>-<arch>`, built by `bun run build:binaries` - see `scripts/platform-targets.ts` for the matrix), each containing a `bun build --compile` standalone binary. The main package's `bin` is `dist/launcher.cjs`, a dependency-free Node script that resolves and runs the right platform package's binary (falling back to `bun cli.js` when none matches) - see that file's header comment for the resolution/fallback logic.
+
+```sh
+bun install
+bun test                    # unit tests (Bun's test runner)
+bunx tsc --noEmit -p .      # typecheck
+bunx oxlint .               # lint
+bunx oxfmt --check .        # format check (bunx oxfmt . to fix)
+bun run build:dist          # build dist/ (the main package)
+bun run smoke:dist          # pack + install the main tarball + exercise the bin (via bun)
+bun run build:binaries      # build dist-binaries/<os>-<arch>/ (one platform package per target)
+bun run smoke:binaries      # pack + npm install main+linux-x64 tarballs + exercise the bin (via node, no Bun)
+bun run release:check       # all of the above, in order
+```
+
+`.github/workflows/ci.yml` runs this exact gate (plus `npm publish --dry-run` from `dist/` and from `dist-binaries/linux-x64/`) on every pull request and every push to `main`.
+
+### Releasing
+
+Releases are driven by [changesets](https://github.com/changesets/changesets), with a small twist: this repo publishes a single npm package (`@nathanld/obsidian-server`) whose version lives in the **root** `package.json`, but changesets only versions workspace packages. `.changeset/config.json` handles this by:
+
+- fixed-grouping the three private `@obsidian-server/*` workspace packages (`apps/server`, `packages/auth`, `packages/obsidian-cli`) so they always version together,
+- `privatePackages: { version: true, tag: false }` so those `"private": true` packages still get versioned (just never individually git-tagged - `docs` and `scripts` are separately excluded via `ignore`, since they're internal-only and never meant to carry a release version at all),
+- and `scripts/sync-version.ts`, run right after `bunx changeset version` (see the `changeset:version` root script), which copies `apps/server/package.json`'s newly-bumped version onto the root `package.json` - keeping root the single source of truth that `scripts/build-dist.ts` reads and bakes into the published binary.
+
+End-to-end flow:
+
+1. A contributor makes a change and runs `bunx changeset` to describe it (patch/minor/major + a human-readable summary), and commits the generated `.changeset/*.md` file alongside their change.
+2. That PR merges to `main`. `.github/workflows/release-pr.yml` runs [`changesets/action`](https://github.com/changesets/action) in **version-only mode** (no `publish` command configured, so it never runs `npm publish` - it only opens or updates a "Version Packages" PR that runs `bun run changeset:version`, i.e. `bunx changeset version` + the sync step above).
+3. Repeat 1-2 for as many changes as you like; the Version Packages PR keeps accumulating them.
+4. When ready to release, merge the "Version Packages" PR. That merge lands on `main` with no changesets left pending and the new version already baked into `package.json` (root, `apps/server`, and the fixed-grouped packages, all in agreement).
+5. `release-pr.yml`'s `tag` job runs again on that push. Since there are now no pending changesets and no existing `v<version>` tag for the new version, `scripts/tag-if-ready.ts` (unit tested in `scripts/test/tag-if-ready.test.ts`; dry-run it locally with `bun run tag:release -- --dry-run`) creates and pushes tag `v<version>`.
+6. That tag push triggers `.github/workflows/publish.yml`, which re-runs the full gate (now including `build:binaries`/`smoke:binaries`), guards that the tag exactly matches `v<root package.json version>`, and then runs the **real** `npm publish` - every platform package (`@nathanld/obsidian-server-<os>-<arch>`) first, then the main package `dist/` - plus creates a GitHub release with the npm tarball and a compressed archive per platform binary attached. This is the only place in the whole setup that publishes for real. Every publish is idempotent (skipped if that exact `name@version` is already on the registry), so re-running the workflow after a partial failure is safe.
+
+**Important limitation:** the tag pushed in step 5 uses the workflow's default `GITHUB_TOKEN`, which - by GitHub's built-in loop-prevention behavior - does **not** trigger other workflows' `on: push: tags` triggers. So step 6 may not start automatically. If it doesn't, trigger it manually:
+
+```sh
+gh workflow run publish.yml -f tag=v<version>
+```
+
+(`publish.yml` accepts this as a `workflow_dispatch` input specifically as a fallback for this case.)
+
+#### Repo settings required
+
+- **"Allow GitHub Actions to create and approve pull requests"** must be enabled under the repo's Settings → Actions → General, or `release-pr.yml` cannot open/update the Version Packages PR.
+- **`NPM_TOKEN` secret**: create a granular npm automation token on [npmjs.com](https://www.npmjs.com) scoped to publish rights for `@nathanld/obsidian-server` **and every `@nathanld/obsidian-server-<os>-<arch>` platform package** (see `scripts/platform-targets.ts` for the current list), and add it as a repo secret named `NPM_TOKEN`. A granular token scoped to only the main package will publish `dist/` fine but fail on the platform packages. This is required because npm's interactive 2FA prompt can't be answered from CI - an automation token bypasses that.
+
+#### Manual fallback
+
+If you need to publish outside the automated flow entirely (e.g. the very first release, or CI is down), `dist/` and every `dist-binaries/<os>-<arch>/` can be published by hand from your own machine, once their version is already correct:
+
+```sh
+bun run release:check                                    # full gate, dry-run only
+bun run release:publish -- --yes                         # real publish
+bun run release:publish -- --yes --otp=123456             # if your npm account has 2FA
+```
 
 ## License
 

package/cli.js

@@ -6,7 +6,10 @@ import { parseArgs } from "util";
 
 // apps/server/src/gating.ts
 var DEFAULT_CLASSIFICATIONS = ["read", "write"];
-var GATED_CLASSIFICATIONS = ["destructive", "app-control"];
+var GATED_CLASSIFICATIONS = [
+  "destructive",
+  "app-control"
+];
 
 class UnknownAllowFlagError extends Error {
   value;
@@ -39,6 +42,7 @@ import { dirname } from "path";
 import { Database } from "bun:sqlite";
 import { betterAuth } from "better-auth";
 import { apiKey } from "@better-auth/api-key";
+import { magicLink, mcp } from "better-auth/plugins";
 
 // packages/auth/src/bearer.ts
 var BEARER_PATTERN = /^Bearer\s+(.+)$/i;
@@ -51,6 +55,12 @@ function extractBearerToken(headerValue) {
 }
 
 // packages/auth/src/config.ts
+var DEFAULT_OAUTH_SCOPES = [
+  "vault:read",
+  "vault:write",
+  "vault:destructive",
+  "vault:app-control"
+];
 function ensureParentDirExists(dbPath) {
   if (dbPath === ":memory:" || dbPath.startsWith("file::memory:"))
     return;
@@ -59,6 +69,11 @@ function ensureParentDirExists(dbPath) {
 function createAuth(options) {
   ensureParentDirExists(options.dbPath);
   const database = new Database(options.dbPath, { create: true });
+  if (options.oauth && !options.baseURL) {
+    throw new Error("createAuth: options.baseURL is required when options.oauth is set (better-auth's " + "mcp plugin needs it to build OAuth issuer/endpoint URLs).");
+  }
+  const oauth = options.oauth;
+  const scopes = oauth?.scopes ?? DEFAULT_OAUTH_SCOPES;
   return betterAuth({
     database,
     baseURL: options.baseURL,
@@ -72,6 +87,23 @@ function createAuth(options) {
         requireName: true,
         rateLimit: { enabled: false },
         customAPIKeyGetter: (ctx) => extractBearerToken(ctx.headers?.get("authorization") ?? null)
+      }),
+      magicLink({
+        disableSignUp: true,
+        sendMagicLink: async (data) => {
+          await oauth?.sendMagicLink?.({ email: data.email, url: data.url, token: data.token });
+        }
+      }),
+      mcp({
+        loginPage: oauth?.loginPage ?? "/login",
+        resource: oauth?.resource,
+        oidcConfig: {
+          loginPage: oauth?.loginPage ?? "/login",
+          requirePKCE: true,
+          storeClientSecret: "hashed",
+          scopes: [...scopes],
+          metadata: { scopes_supported: [...scopes] }
+        }
       })
     ]
   });
@@ -90,7 +122,12 @@ async function bootstrap(auth, options = {}) {
   const existing = await ctx.adapter.findMany({ model: "user", limit: 1 });
   const existingUser = existing[0];
   if (existingUser) {
-    return { id: existingUser.id, email: existingUser.email, name: existingUser.name, created: false };
+    return {
+      id: existingUser.id,
+      email: existingUser.email,
+      name: existingUser.name,
+      created: false
+    };
   }
   const email = options.email ?? DEFAULT_OWNER_EMAIL;
   const name = options.name ?? DEFAULT_OWNER_NAME;
@@ -101,13 +138,17 @@ async function bootstrap(auth, options = {}) {
   });
   return { id: user.id, email: user.email, name: user.name, created: true };
 }
-async function resolveOwnerId(auth) {
+async function getOwner(auth) {
   const ctx = await auth.$context;
   const existing = await ctx.adapter.findMany({ model: "user", limit: 1 });
   const owner = existing[0];
   if (!owner) {
     throw new Error("No owner user found. Run bootstrap() (or the `bootstrap` CLI command) first.");
   }
+  return { id: owner.id, email: owner.email, name: owner.name };
+}
+async function resolveOwnerId(auth) {
+  const owner = await getOwner(auth);
   return owner.id;
 }
 // packages/auth/src/keys.ts
@@ -129,7 +170,16 @@ async function mintKey(auth, options) {
     expiresAt: created.expiresAt
   };
 }
-var SAFE_KEY_COLUMNS = ["id", "name", "start", "enabled", "createdAt", "expiresAt", "lastRequest", "referenceId"];
+var SAFE_KEY_COLUMNS = [
+  "id",
+  "name",
+  "start",
+  "enabled",
+  "createdAt",
+  "expiresAt",
+  "lastRequest",
+  "referenceId"
+];
 async function listKeys(auth, options = {}) {
   const userId = options.userId ?? await resolveOwnerId(auth);
   const ctx = await auth.$context;
@@ -172,34 +222,81 @@ async function ensureOwnerAndKey(auth, options = {}) {
   const minted = await mintKey(auth, { userId: owner.id, name: options.keyName ?? "bootstrap" });
   return { created: true, key: minted.key, keyId: minted.id };
 }
+// packages/auth/src/challenge.ts
+function quote(value) {
+  return value.replace(/"/g, "'");
+}
+function buildBearerChallenge(options) {
+  let header = `Bearer error="${options.error}", error_description="${quote(options.description)}"`;
+  if (options.scope && options.scope.length > 0) {
+    header += `, scope="${options.scope.join(" ")}"`;
+  }
+  if (options.resourceMetadataUrl) {
+    header += `, resource_metadata="${options.resourceMetadataUrl}"`;
+  }
+  return header;
+}
+
 // packages/auth/src/middleware.ts
-function unauthorized(c) {
-  c.header("WWW-Authenticate", "Bearer");
+function unauthorized(c, options) {
+  const challenge = buildBearerChallenge({
+    error: "invalid_token",
+    description: "missing or invalid bearer token",
+    scope: options.scopes,
+    resourceMetadataUrl: options.resourceMetadataUrl
+  });
+  c.header("WWW-Authenticate", challenge);
   return c.json({ error: "unauthorized" }, 401);
 }
-function requireAuth(auth) {
+function requireAuth(auth, options = {}) {
   return async (c, next) => {
     const token = extractBearerToken(c.req.header("authorization"));
     if (!token) {
-      return unauthorized(c);
+      return unauthorized(c, options);
     }
-    let result;
+    let apiKeyResult;
     try {
-      result = await auth.api.verifyApiKey({ body: { key: token } });
+      apiKeyResult = await auth.api.verifyApiKey({ body: { key: token } });
     } catch {
-      return unauthorized(c);
+      apiKeyResult = undefined;
     }
-    if (!result.valid || !result.key) {
-      return unauthorized(c);
+    if (apiKeyResult?.valid && apiKeyResult.key) {
+      const ctx = await auth.$context;
+      const user = await ctx.internalAdapter.findUserById(apiKeyResult.key.referenceId);
+      if (!user) {
+        return unauthorized(c, options);
+      }
+      c.set("user", { id: user.id, email: user.email, name: user.name });
+      c.set("apiKey", { id: apiKeyResult.key.id, name: apiKeyResult.key.name });
+      await next();
+      return;
     }
-    const ctx = await auth.$context;
-    const user = await ctx.internalAdapter.findUserById(result.key.referenceId);
-    if (!user) {
-      return unauthorized(c);
+    let session = null;
+    try {
+      session = await auth.api.getMcpSession({
+        headers: c.req.raw.headers,
+        request: c.req.raw,
+        asResponse: false
+      });
+    } catch {
+      session = null;
     }
-    c.set("user", { id: user.id, email: user.email, name: user.name });
-    c.set("apiKey", { id: result.key.id, name: result.key.name });
-    await next();
+    if (session) {
+      const ctx = await auth.$context;
+      const user = await ctx.internalAdapter.findUserById(session.userId);
+      if (!user) {
+        return unauthorized(c, options);
+      }
+      c.set("user", { id: user.id, email: user.email, name: user.name });
+      c.set("oauthToken", {
+        clientId: session.clientId,
+        scopes: session.scopes ? session.scopes.split(" ").filter((s) => s.length > 0) : [],
+        expiresAt: Math.floor(session.accessTokenExpiresAt.getTime() / 1000)
+      });
+      await next();
+      return;
+    }
+    return unauthorized(c, options);
   };
 }
 // packages/obsidian-cli/src/classify.ts
@@ -602,7 +699,132 @@ function commandToZodShape(cmd) {
 }
 // apps/server/src/app.ts
 import { createMcpHonoApp } from "@modelcontextprotocol/hono";
-import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/server";
+import {
+  getOAuthProtectedResourceMetadataUrl,
+  WebStandardStreamableHTTPServerTransport
+} from "@modelcontextprotocol/server";
+
+// apps/server/src/cimd.ts
+var LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1", "[::1]", "0.0.0.0"]);
+function isPrivateOrLoopbackHost(hostname) {
+  const h = hostname.toLowerCase();
+  if (LOOPBACK_HOSTNAMES.has(h) || h.endsWith(".localhost"))
+    return true;
+  const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(h);
+  if (ipv4) {
+    const a = Number(ipv4[1]);
+    const b = Number(ipv4[2]);
+    if (a === 10 || a === 127 || a === 0)
+      return true;
+    if (a === 169 && b === 254)
+      return true;
+    if (a === 172 && b >= 16 && b <= 31)
+      return true;
+    if (a === 192 && b === 168)
+      return true;
+  }
+  if (h === "::1" || h.startsWith("fc") || h.startsWith("fd") || h.startsWith("fe80"))
+    return true;
+  return false;
+}
+function isCimdClientId(value, options = {}) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  const schemeOk = url.protocol === "https:" || options.allowInsecureHosts === true && url.protocol === "http:";
+  if (!schemeOk)
+    return false;
+  if (!options.allowInsecureHosts && isPrivateOrLoopbackHost(url.hostname))
+    return false;
+  return true;
+}
+function isValidCimdDocument(value, clientId) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const doc = value;
+  if (doc.client_id !== clientId)
+    return false;
+  if (!Array.isArray(doc.redirect_uris) || doc.redirect_uris.length === 0)
+    return false;
+  if (!doc.redirect_uris.every((u) => typeof u === "string"))
+    return false;
+  if (doc.client_name !== undefined && typeof doc.client_name !== "string")
+    return false;
+  return true;
+}
+var DEFAULT_TTL_MS = 5 * 60 * 1000;
+var resolvedCache = new Map;
+function ttlFromCacheControl(header) {
+  if (!header)
+    return DEFAULT_TTL_MS;
+  const match = /max-age=(\d+)/.exec(header);
+  if (!match?.[1])
+    return DEFAULT_TTL_MS;
+  return Math.max(1, Number(match[1])) * 1000;
+}
+async function resolveCimdClient(auth, clientId, options = {}) {
+  if (!isCimdClientId(clientId, options))
+    return;
+  const cached = resolvedCache.get(clientId);
+  if (cached && cached.expiresAt > Date.now())
+    return;
+  const ctx = await auth.$context;
+  const existing = await ctx.adapter.findOne({
+    model: "oauthApplication",
+    where: [{ field: "clientId", value: clientId }]
+  });
+  let res;
+  try {
+    res = await fetch(clientId, { headers: { Accept: "application/json" } });
+  } catch {
+    if (existing)
+      resolvedCache.set(clientId, { expiresAt: Date.now() + DEFAULT_TTL_MS });
+    return;
+  }
+  if (!res.ok) {
+    if (existing)
+      resolvedCache.set(clientId, { expiresAt: Date.now() + DEFAULT_TTL_MS });
+    return;
+  }
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    return;
+  }
+  if (!isValidCimdDocument(body, clientId))
+    return;
+  const now = new Date;
+  const redirectUrls = body.redirect_uris.join(",");
+  const name = body.client_name ?? clientId;
+  if (existing) {
+    await ctx.adapter.update({
+      model: "oauthApplication",
+      where: [{ field: "clientId", value: clientId }],
+      update: { name, redirectUrls, updatedAt: now }
+    });
+  } else {
+    await ctx.adapter.create({
+      model: "oauthApplication",
+      data: {
+        name,
+        clientId,
+        clientSecret: "",
+        redirectUrls,
+        type: "public",
+        disabled: false,
+        createdAt: now,
+        updatedAt: now
+      }
+    });
+  }
+  resolvedCache.set(clientId, {
+    expiresAt: Date.now() + ttlFromCacheControl(res.headers.get("cache-control"))
+  });
+}
 
 // apps/server/src/exposed-commands.ts
 function exposedCommands(commands, allowed) {
@@ -616,6 +838,91 @@ function countExposedByClassification(commands, allowed) {
   return counts;
 }
 
+// apps/server/src/login-page.ts
+function escapeHtml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function escapeJsString(value) {
+  return JSON.stringify(value);
+}
+function renderLoginPage(options) {
+  const emailHtml = escapeHtml(options.ownerEmail);
+  const emailJs = escapeJsString(options.ownerEmail);
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Sign in - obsidian-server</title>
+<style>
+  :root { color-scheme: light dark; }
+  body {
+    font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+    max-width: 32rem;
+    margin: 4rem auto;
+    padding: 0 1.5rem;
+    line-height: 1.5;
+  }
+  h1 { font-size: 1.25rem; }
+  button {
+    font: inherit;
+    padding: 0.6rem 1.2rem;
+    border-radius: 0.4rem;
+    border: 1px solid #8884;
+    cursor: pointer;
+  }
+  button:disabled { opacity: 0.6; cursor: default; }
+  #status { margin-top: 1rem; }
+  code { padding: 0.1rem 0.3rem; border-radius: 0.25rem; background: #8882; }
+</style>
+</head>
+<body>
+<h1>Sign in to obsidian-server</h1>
+<p>
+  This server has one owner account (<code>${emailHtml}</code>). Signing in
+  sends a one-time link - it is printed to the terminal where
+  <code>obsidian-server</code> is running, not emailed anywhere.
+</p>
+<button id="send" type="button">Send me a sign-in link</button>
+<p id="status"></p>
+<script>
+(function () {
+  var ownerEmail = ${emailJs};
+  var button = document.getElementById("send");
+  var status = document.getElementById("status");
+
+  button.addEventListener("click", function () {
+    button.disabled = true;
+    status.textContent = "Sending...";
+
+    var callbackURL = window.location.origin + "/api/auth/mcp/authorize" + window.location.search;
+
+    fetch("/api/auth/sign-in/magic-link", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: ownerEmail, callbackURL: callbackURL }),
+    })
+      .then(function (res) {
+        if (!res.ok) throw new Error("request failed: " + res.status);
+        return res.json();
+      })
+      .then(function () {
+        status.textContent =
+          "A sign-in link has been printed to the terminal where obsidian-server " +
+          "is running. Open it there to finish signing in.";
+      })
+      .catch(function (err) {
+        button.disabled = false;
+        status.textContent = "Could not send the sign-in link: " + err.message;
+      });
+  });
+})();
+</script>
+</body>
+</html>
+`;
+}
+
 // apps/server/src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/server";
 import { z as z2 } from "zod";
@@ -625,9 +932,40 @@ function commandToToolName(command) {
   return `obsidian_${command.replace(/:/g, "_")}`;
 }
 
+// apps/server/src/scopes.ts
+function classificationToScope(classification) {
+  return `vault:${classification}`;
+}
+var CLASSIFICATIONS = [
+  "read",
+  "write",
+  "destructive",
+  "app-control"
+];
+function exposedScopes(allowed) {
+  return CLASSIFICATIONS.filter((c) => allowed.has(c)).map(classificationToScope);
+}
+
 // apps/server/src/mcp.ts
 var SERVER_NAME = "obsidian-server";
 var SERVER_VERSION = "0.1.0";
+function checkScope(ctx, classification) {
+  const authInfo = ctx.http?.authInfo;
+  if (!authInfo || authInfo.extra?.credentialType === "api-key")
+    return;
+  const requiredScope = classificationToScope(classification);
+  if (authInfo.scopes.includes(requiredScope))
+    return;
+  return {
+    content: [
+      {
+        type: "text",
+        text: `insufficient_scope: this tool requires the "${requiredScope}" scope`
+      }
+    ],
+    isError: true
+  };
+}
 function buildMcpServer(options) {
   const { client, allowed } = options;
   const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
@@ -641,7 +979,10 @@ function buildMcpServer(options) {
     registered.add(toolName);
     const description = `${command.description} [${classification}]`;
     const inputSchema = commandToZodShape(command);
-    server.registerTool(toolName, { title: command.name, description, inputSchema }, async (args) => {
+    server.registerTool(toolName, { title: command.name, description, inputSchema }, async (args, ctx) => {
+      const scopeError = checkScope(ctx, classification);
+      if (scopeError)
+        return scopeError;
       try {
         const result = await client.run(command.name, args);
         return { content: [{ type: "text", text: result.stdout || "(empty)" }] };
@@ -664,7 +1005,12 @@ function buildMcpServer(options) {
       options: command.options
     }));
     return {
-      content: [{ type: "text", text: JSON.stringify({ vault: client.vault, commands }, null, 2) }]
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ vault: client.vault, commands }, null, 2)
+        }
+      ]
     };
   });
   return server;
@@ -679,10 +1025,72 @@ function needsDnsRebindingWarning(host, allowedHosts) {
   return !isLocalhostClass(host) && (!allowedHosts || allowedHosts.length === 0);
 }
 
+// apps/server/src/well-known.ts
+import { oAuthDiscoveryMetadata, oAuthProtectedResourceMetadata } from "better-auth/plugins";
+function authorizationServerMetadata(auth, scopesSupported) {
+  const upstream = oAuthDiscoveryMetadata(auth);
+  return async (request) => {
+    const res = await upstream(request);
+    if (res.status !== 200)
+      return res;
+    const body = await res.json();
+    body.scopes_supported = [...scopesSupported];
+    body.authorization_response_iss_parameter_supported = true;
+    body.client_id_metadata_document_supported = true;
+    return new Response(JSON.stringify(body), { status: 200, headers: res.headers });
+  };
+}
+function protectedResourceMetadata(auth) {
+  return oAuthProtectedResourceMetadata(auth);
+}
+
 // apps/server/src/app.ts
 function isOptionValue(value) {
   return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
 }
+function appendIssParam(res, issuer) {
+  const location = res.headers.get("location");
+  if (!location)
+    return res;
+  let url;
+  try {
+    url = new URL(location, issuer);
+  } catch {
+    return res;
+  }
+  if (!url.searchParams.has("code"))
+    return res;
+  url.searchParams.set("iss", issuer);
+  const headers = new Headers(res.headers);
+  headers.set("location", url.toString());
+  return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+}
+async function extractClientId(req) {
+  const fields = await extractTokenRequestFields(req);
+  return fields.client_id;
+}
+async function extractTokenRequestFields(req) {
+  if (req.method === "GET" || req.method === "HEAD") {
+    const params = new URL(req.url).searchParams;
+    return {
+      client_id: params.get("client_id") ?? undefined,
+      grant_type: params.get("grant_type") ?? undefined,
+      refresh_token: params.get("refresh_token") ?? undefined
+    };
+  }
+  const clone = req.clone();
+  try {
+    const contentType = clone.headers.get("content-type") ?? "";
+    const raw = contentType.includes("application/json") ? await clone.json() : Object.fromEntries(new URLSearchParams(await clone.text()));
+    return {
+      client_id: typeof raw.client_id === "string" ? raw.client_id : undefined,
+      grant_type: typeof raw.grant_type === "string" ? raw.grant_type : undefined,
+      refresh_token: typeof raw.refresh_token === "string" ? raw.refresh_token : undefined
+    };
+  } catch {
+    return {};
+  }
+}
 async function parseCommandBody(req) {
   const raw = await req.text();
   if (raw.trim().length === 0)
@@ -707,6 +1115,10 @@ async function parseCommandBody(req) {
 }
 async function buildApp(options) {
   const { client, auth, allowed } = options;
+  const publicUrl = options.publicUrl.replace(/\/$/, "");
+  const mcpResourceUrl = `${publicUrl}/mcp`;
+  const resourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(new URL(mcpResourceUrl));
+  const scopesSupported = exposedScopes(allowed);
   const warnings = [];
   if (needsDnsRebindingWarning(options.host, options.allowedHosts)) {
     warnings.push(`Binding to "${options.host}" without --allow-hosts/--allow-origins leaves DNS-rebinding protection ` + "disabled. Pass allowedHosts/allowedOrigins when binding beyond localhost.");
@@ -725,7 +1137,37 @@ async function buildApp(options) {
     }
     return c.json({ ok: true, obsidian: reachable, vault: client.vault ?? null });
   });
-  const authMiddleware = requireAuth(auth);
+  const prmHandler = protectedResourceMetadata(auth);
+  app.get("/.well-known/oauth-protected-resource/mcp", (c) => prmHandler(c.req.raw));
+  app.get("/.well-known/oauth-protected-resource", (c) => prmHandler(c.req.raw));
+  const asHandler = authorizationServerMetadata(auth, scopesSupported);
+  app.get("/.well-known/oauth-authorization-server", (c) => asHandler(c.req.raw));
+  const owner = await getOwner(auth);
+  app.get("/login", (c) => c.html(renderLoginPage({ ownerEmail: owner.email })));
+  const cimdOptions = { allowInsecureHosts: options.allowInsecureCimdHosts };
+  app.get("/api/auth/mcp/authorize", async (c) => {
+    const clientId = await extractClientId(c.req.raw);
+    if (clientId)
+      await resolveCimdClient(auth, clientId, cimdOptions).catch(() => {});
+    const res = await auth.handler(c.req.raw);
+    return appendIssParam(res, publicUrl);
+  });
+  app.post("/api/auth/mcp/token", async (c) => {
+    const fields = await extractTokenRequestFields(c.req.raw);
+    if (fields.client_id)
+      await resolveCimdClient(auth, fields.client_id, cimdOptions).catch(() => {});
+    const res = await auth.handler(c.req.raw);
+    if (fields.grant_type === "refresh_token" && fields.refresh_token && res.status === 200) {
+      const ctx = await auth.$context;
+      await ctx.adapter.delete({
+        model: "oauthAccessToken",
+        where: [{ field: "refreshToken", value: fields.refresh_token }]
+      }).catch(() => {});
+    }
+    return res;
+  });
+  app.all("/api/auth/*", (c) => auth.handler(c.req.raw));
+  const authMiddleware = requireAuth(auth, { resourceMetadataUrl, scopes: scopesSupported });
   app.use("/api/*", authMiddleware);
   app.use("/mcp", authMiddleware);
   app.get("/api/commands", (c) => {
@@ -754,6 +1196,19 @@ async function buildApp(options) {
         error: `Command "${name}" is classified "${classification}" and is not exposed. Restart the server with --allow ${classification} to enable it.`
       }, 403);
     }
+    const oauthToken = c.get("oauthToken");
+    if (oauthToken) {
+      const requiredScope = classificationToScope(classification);
+      if (!oauthToken.scopes.includes(requiredScope)) {
+        c.header("WWW-Authenticate", buildBearerChallenge({
+          error: "insufficient_scope",
+          description: `command "${name}" requires the "${requiredScope}" scope`,
+          scope: [requiredScope],
+          resourceMetadataUrl
+        }));
+        return c.json({ ok: false, error: `insufficient_scope: requires the "${requiredScope}" scope` }, 403);
+      }
+    }
     const parsedBody = await parseCommandBody(c.req.raw);
     if (!parsedBody.ok) {
       return c.json({ ok: false, error: parsedBody.error }, 400);
@@ -783,11 +1238,19 @@ async function buildApp(options) {
   app.all("/mcp", async (c) => {
     const user = c.get("user");
     const apiKey2 = c.get("apiKey");
-    const authInfo = {
+    const oauthToken = c.get("oauthToken");
+    const authInfo = oauthToken ? {
+      token: extractBearerToken(c.req.header("authorization")) ?? "",
+      clientId: oauthToken.clientId,
+      scopes: oauthToken.scopes,
+      expiresAt: oauthToken.expiresAt,
+      resource: new URL(mcpResourceUrl),
+      extra: { credentialType: "oauth", user, oauthToken }
+    } : {
       token: apiKey2?.id ?? "",
       clientId: apiKey2?.id ?? "unknown",
-      scopes: [],
-      extra: { user, apiKey: apiKey2 }
+      scopes: scopesSupported,
+      extra: { credentialType: "api-key", user, apiKey: apiKey2 }
     };
     return transport.handleRequest(c.req.raw, { parsedBody: c.get("parsedBody"), authInfo });
   });
@@ -833,6 +1296,16 @@ function renderStartupBanner(input) {
   lines.push("");
   lines.push("  Add this server to an MCP client:");
   lines.push(`    ${renderMcpAddCommand(input.host, input.port, input.freshToken)}`);
+  if (input.publicUrl) {
+    lines.push("");
+    lines.push("  OAuth 2.1 (MCP spec rev 2026-07-28, RC-hardened; also accepted alongside API keys):");
+    lines.push(`    issuer:            ${input.publicUrl}`);
+    lines.push(`    protected resource: ${input.publicUrl}/.well-known/oauth-protected-resource/mcp`);
+    lines.push(`    login page:        ${input.publicUrl}/login`);
+    if (input.oauthScopes && input.oauthScopes.length > 0) {
+      lines.push(`    scopes:            ${input.oauthScopes.join(", ")}`);
+    }
+  }
   return lines.join(`
 `);
 }
@@ -855,7 +1328,23 @@ var OBSIDIAN_NOT_FOUND_HINT = "Could not run the `obsidian` CLI. Make sure the O
 async function runServe(options) {
   const dataDir = resolveDataDir(process.env, options.dataDir);
   mkdirSync2(dataDir, { recursive: true });
-  const auth = createAuth({ dbPath: join2(dataDir, "auth.db"), baseURL: `http://${options.host}:${options.port}` });
+  const publicUrl = (options.publicUrl ?? `http://${options.host}:${options.port}`).replace(/\/$/, "");
+  const allowed = computeAllowedClassifications(options.allow);
+  const scopes = exposedScopes(allowed);
+  const auth = createAuth({
+    dbPath: join2(dataDir, "auth.db"),
+    baseURL: publicUrl,
+    oauth: {
+      resource: `${publicUrl}/mcp`,
+      scopes,
+      sendMagicLink: (data) => {
+        console.log("");
+        console.log("A sign-in link was requested for the OAuth login page. Open it to finish signing in:");
+        console.log(`  ${data.url}`);
+        console.log("");
+      }
+    }
+  });
   await migrate(auth);
   const ensured = await ensureOwnerAndKey(auth);
   let client;
@@ -873,15 +1362,19 @@ async function runServe(options) {
     }
     throw err;
   }
-  const allowed = computeAllowedClassifications(options.allow);
   const { app, warnings } = await buildApp({
     client,
     auth,
     allowed,
     host: options.host,
     allowedHosts: options.allowedHosts,
-    allowedOrigins: options.allowedOrigins
+    allowedOrigins: options.allowedOrigins,
+    publicUrl,
+    allowInsecureCimdHosts: options.allowInsecureCimdHosts
   });
+  if (!options.publicUrl && publicUrl.startsWith("http://")) {
+    warnings.push(`No --public-url was given; OAuth discovery defaults to "${publicUrl}", which is only reachable ` + "locally. Most remote MCP clients (including claude.ai) require HTTPS - pass --public-url " + "https://<host> once this server is reachable at one.");
+  }
   for (const warning of warnings)
     console.warn(`warning: ${warning}`);
   const banner = renderStartupBanner({
@@ -892,7 +1385,9 @@ async function runServe(options) {
     exposedCounts: countExposedByClassification(client.schema.commands, allowed),
     totalExposed: exposedCommands(client.schema.commands, allowed).length,
     totalCommands: client.schema.commands.length,
-    freshToken: ensured.created ? ensured.key : undefined
+    freshToken: ensured.created ? ensured.key : undefined,
+    publicUrl,
+    oauthScopes: scopes
   });
   console.log(banner);
   const server = Bun.serve({ fetch: app.fetch, port: options.port, hostname: options.host });
@@ -909,7 +1404,11 @@ async function tokenMint(options) {
   const auth = authForDataDir(options.dataDir);
   await migrate(auth);
   const owner = await bootstrap(auth);
-  const minted = await mintKey(auth, { name: options.name, expiresDays: options.expiresDays, userId: owner.id });
+  const minted = await mintKey(auth, {
+    name: options.name,
+    expiresDays: options.expiresDays,
+    userId: owner.id
+  });
   return { id: minted.id, key: minted.key, expiresAt: minted.expiresAt };
 }
 async function tokenList(options = {}) {
@@ -936,7 +1435,7 @@ function formatKeySummary(key) {
 }
 
 // apps/server/src/version.ts
-var VERSION = "0.0.1";
+var VERSION = "0.0.2";
 
 // apps/server/src/cli.ts
 var USAGE = [
@@ -946,7 +1445,12 @@ var USAGE = [
   "  serve [--vault <name>] [--port 3000] [--host 127.0.0.1]",
   "        [--allow destructive] [--allow app-control]",
   "        [--data-dir <path>] [--binary <path>] [--timeout-ms <n>]",
+  "        [--public-url https://host[:port]]",
+  "        [--dangerously-allow-insecure-cimd-hosts]",
   "    Start the MCP + REST server for a vault.",
+  "    --public-url is the canonical OAuth issuer / MCP resource URL - the",
+  "    URL a remote client actually reaches this server through. Defaults to",
+  "    http://<host>:<port>, which only works for local clients.",
   "",
   "  token mint --name <label> [--expires-days <n>] [--data-dir <path>]",
   "    Mint a new API key (printed once).",
@@ -985,7 +1489,9 @@ async function main() {
         allow: { type: "string", multiple: true, default: [] },
         "data-dir": { type: "string" },
         binary: { type: "string" },
-        "timeout-ms": { type: "string" }
+        "timeout-ms": { type: "string" },
+        "public-url": { type: "string" },
+        "dangerously-allow-insecure-cimd-hosts": { type: "boolean", default: false }
       },
       allowPositionals: false
     });
@@ -1018,7 +1524,9 @@ async function main() {
       allow: values.allow ?? [],
       dataDir: values["data-dir"],
       binary: values.binary,
-      timeoutMs
+      timeoutMs,
+      publicUrl: values["public-url"],
+      allowInsecureCimdHosts: values["dangerously-allow-insecure-cimd-hosts"]
     });
     return;
   }
@@ -1047,7 +1555,11 @@ async function main() {
           process.exitCode = 1;
           return;
         }
-        const minted = await tokenMint({ name: values.name, expiresDays, dataDir: values["data-dir"] });
+        const minted = await tokenMint({
+          name: values.name,
+          expiresDays,
+          dataDir: values["data-dir"]
+        });
         console.log("API key (shown once - it cannot be recovered later):");
         console.log(minted.key);
         console.log(`id: ${minted.id}`);

package/launcher.cjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Node-compatible launcher shim for `@nathanld/obsidian-server`'s `bin`.
+ *
+ * Plain CommonJS, zero dependencies, no Bun APIs - must run on Node >=18
+ * (the "no Bun required" floor this whole binaries setup exists for).
+ * Mirrors the esbuild/biome/turbo pattern:
+ *
+ *   1. Work out which `@nathanld/obsidian-server-<os>-<cpu>` platform
+ *      package (an optionalDependency of this package, see
+ *      scripts/build-binaries.ts) matches the current platform, and try to
+ *      `require.resolve` it as an installed sibling package.
+ *   2. If found, spawn its compiled binary directly with argv passthrough,
+ *      inherited stdio, and the child's exit code/signal mirrored back.
+ *   3. If not found (unsupported platform, or optionalDependencies were
+ *      skipped e.g. via `npm install --no-optional` / `--omit=optional`),
+ *      fall back to `bun <this dir>/cli.js` if `bun` is on PATH.
+ *   4. If neither works, exit with a clear, actionable error.
+ *
+ * KEEP THIS FILE IN SYNC with `scripts/platform-targets.ts`'s PLATFORM_TARGETS
+ * if the supported platform/arch matrix ever changes - it's duplicated here
+ * (rather than imported) because this file must stay plain, dependency-free
+ * CommonJS that Node can run with no build step.
+ */
+
+const path = require("node:path");
+const fs = require("node:fs");
+const { spawn } = require("node:child_process");
+
+/** @type {Record<string, string>} "<process.platform> <process.arch>" -> platform package name suffix */
+const PLATFORM_PACKAGE_DIRS = {
+  "linux x64": "linux-x64",
+  "linux arm64": "linux-arm64",
+  "darwin x64": "darwin-x64",
+  "darwin arm64": "darwin-arm64",
+  "win32 x64": "win32-x64",
+};
+
+const PACKAGE_NAME = "@nathanld/obsidian-server";
+
+function platformKey() {
+  return `${process.platform} ${process.arch}`;
+}
+
+function binaryFileName() {
+  return process.platform === "win32" ? "obsidian-server.exe" : "obsidian-server";
+}
+
+/**
+ * Resolve the installed platform package's directory, or undefined if it
+ * isn't installed (unsupported platform, or optionalDependencies skipped).
+ *
+ * Uses plain `require.resolve` first (relies on Node's normal node_modules
+ * directory walk from this file's location, which is how npm/yarn/pnpm all
+ * lay out optionalDependencies as an installable sibling of this package),
+ * then retries with an explicit `paths` list covering a few layouts
+ * (bunx's isolated install dirs, global installs) where the natural walk
+ * from `__dirname` alone might not reach the sibling package.
+ */
+function resolvePlatformPackageDir(pkgName) {
+  const candidate = `${pkgName}/package.json`;
+  try {
+    return path.dirname(require.resolve(candidate));
+  } catch {
+    // fall through to the explicit-paths retry below
+  }
+
+  const extraRoots = [
+    __dirname,
+    path.join(__dirname, ".."),
+    path.join(__dirname, "..", ".."),
+    path.join(__dirname, "..", "..", ".."),
+    process.cwd(),
+  ];
+  try {
+    return path.dirname(require.resolve(candidate, { paths: extraRoots }));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Minimal, dependency-free `which`: search PATH for an executable. */
+function findOnPath(command) {
+  const pathEnv = process.env.PATH || process.env.Path || "";
+  const dirs = pathEnv.split(path.delimiter).filter(Boolean);
+  const candidates =
+    process.platform === "win32"
+      ? (process.env.PATHEXT || ".EXE;.CMD;.BAT").split(";").map((ext) => command + ext)
+      : [command];
+
+  for (const dir of dirs) {
+    for (const name of candidates) {
+      const full = path.join(dir, name);
+      try {
+        fs.accessSync(full, fs.constants.X_OK);
+        return full;
+      } catch {
+        // not here, keep looking
+      }
+    }
+  }
+  return undefined;
+}
+
+function installHint() {
+  const suffix = PLATFORM_PACKAGE_DIRS[platformKey()];
+  const platformPkgLine = suffix
+    ? `The platform package "${PACKAGE_NAME}-${suffix}" was not found (it may have been skipped by --no-optional / --omit=optional).`
+    : `"${platformKey()}" has no prebuilt binary (supported: ${Object.keys(PLATFORM_PACKAGE_DIRS).join(", ")}).`;
+
+  return [
+    `${PACKAGE_NAME}: could not find a native binary to run.`,
+    "",
+    platformPkgLine,
+    "No fallback either: `bun` was not found on PATH.",
+    "",
+    "To fix this, either:",
+    "  - reinstall without skipping optional dependencies, e.g. `npm install`, or",
+    "  - install Bun (https://bun.sh) so the bundled cli.js fallback can run.",
+    "",
+  ].join("\n");
+}
+
+/**
+ * Spawn `command`/`args`, inherit stdio, forward SIGINT/SIGTERM to the
+ * child, and mirror the child's exit code/signal back onto this process
+ * once it exits.
+ */
+function runAndExit(command, args) {
+  const child = spawn(command, args, { stdio: "inherit" });
+
+  const forward = (signal) => {
+    if (!child.killed) child.kill(signal);
+  };
+  process.on("SIGINT", forward);
+  process.on("SIGTERM", forward);
+
+  child.on("error", (err) => {
+    console.error(`${PACKAGE_NAME}: failed to run "${command}": ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      // Re-raise the same signal on ourselves so our own exit status/signal
+      // matches what killed the child, instead of guessing an exit code.
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code === null ? 1 : code);
+  });
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  const suffix = PLATFORM_PACKAGE_DIRS[platformKey()];
+  if (suffix) {
+    const platformDir = resolvePlatformPackageDir(`${PACKAGE_NAME}-${suffix}`);
+    if (platformDir) {
+      const binPath = path.join(platformDir, binaryFileName());
+      if (fs.existsSync(binPath)) {
+        runAndExit(binPath, args);
+        return;
+      }
+    }
+  }
+
+  const bunPath = findOnPath("bun");
+  if (bunPath) {
+    const cliPath = path.join(__dirname, "cli.js");
+    runAndExit(bunPath, [cliPath, ...args]);
+    return;
+  }
+
+  console.error(installHint());
+  process.exit(1);
+}
+
+main();

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@nathanld/obsidian-server",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Point any Obsidian vault at an MCP server + REST API with Bearer-token auth out of the box, backed by the official Obsidian CLI.",
   "type": "module",
   "bin": {
-    "obsidian-server": "cli.js"
+    "obsidian-server": "launcher.cjs"
   },
   "dependencies": {
     "@better-auth/api-key": "1.6.23",
@@ -14,16 +14,23 @@
     "hono": "^4.12.29",
     "zod": "^4.4.3"
   },
+  "optionalDependencies": {
+    "@nathanld/obsidian-server-linux-x64": "0.0.2",
+    "@nathanld/obsidian-server-linux-arm64": "0.0.2",
+    "@nathanld/obsidian-server-darwin-x64": "0.0.2",
+    "@nathanld/obsidian-server-darwin-arm64": "0.0.2",
+    "@nathanld/obsidian-server-win32-x64": "0.0.2"
+  },
   "engines": {
-    "bun": ">=1.2.0"
+    "node": ">=18"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/nathanld/obsidian-server.git"
+    "url": "git+https://github.com/UpToNathan/obsidian-server.git"
   },
-  "homepage": "https://github.com/nathanld/obsidian-server#readme",
+  "homepage": "https://github.com/UpToNathan/obsidian-server#readme",
   "bugs": {
-    "url": "https://github.com/nathanld/obsidian-server/issues"
+    "url": "https://github.com/UpToNathan/obsidian-server/issues"
   },
   "license": "MIT",
   "keywords": [
@@ -37,6 +44,7 @@
   ],
   "files": [
     "cli.js",
+    "launcher.cjs",
     "README.md",
     "LICENSE"
   ],