From e0df28ff5d89cfdd9a71c5158dc66fdbf93035e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Padez?= Date: Thu, 27 Aug 2026 04:22:27 +0000 Subject: [PATCH] a first-party plugin may claim a root path the platform reserved MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit caldav is not only /api/caldav. four of its surfaces are top-level and above the account gate on purpose, because DAVx5, iOS and Thunderbird send HTTP Basic on every request and have nowhere to put a JWT: /dav, the ios profile under it, and the two .well-known discovery paths a client probes before it has any credential. the mechanism for that already existed — unauthenticatedRootPaths, exclusive claims, first come wins. what stopped caldav using it was RESERVED_ROOT, and what that list was recording is worth being exact about: `dav` and `.well-known` are in it because the PLATFORM serves them today, not because they are dangerous in themselves. once caldav is a plugin, the thing the reservation protects IS the plugin, and keeping it would mean the platform permanently owning routes for a feature it no longer contains. so a reserved name is claimable by a first-party plugin and refused to everyone else. the owner drew that line today: fine for a plugin we wrote, and letting a stranger's plugin claim /dav is a question that needs thinking about properly rather than falling out of a flag. /api stays refused to us too — everything of officer's lives under it and protocolHeaders is the only sanctioned way in. .well-known needed two segments, which the single-segment rule refuses. allowed by NAME rather than by pattern, and the reason is in the same namespace: acme-challenge is how this machine gets its TLS certificates, so a plugin owning it could take the domain. caldav and carddav are on the list; nothing else is, for us as much as for anyone. the OPTIONS carve-out moved with it. hono's cors() answers every OPTIONS as a preflight and never calls the route beneath — which to a DAV client is not a preflight but the question "what can you do", answered by a header iOS refuses the account without. that was a literal list of four DAV paths; it asks the claim registry now, so it follows whoever owns the route rather than naming it here. verified: server boots (totality passes), /.well-known/caldav still 301s and /dav/ still asks for basic auth. Co-Authored-By: Claude Opus 5 Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043 --- src/servers/hono.ts | 35 +++++++++------- src/servers/plugins/manifest.ts | 48 ++++++++++++++++++++-- src/servers/plugins/public-paths.test.ts | 52 ++++++++++++++++++++++-- src/servers/plugins/public-paths.ts | 14 ++++++- 4 files changed, 126 insertions(+), 23 deletions(-) diff --git a/src/servers/hono.ts b/src/servers/hono.ts index 6d3898b0..2f04b7e2 100644 --- a/src/servers/hono.ts +++ b/src/servers/hono.ts @@ -25,7 +25,7 @@ import { dashboardsRouter } from './api/dashboards'; import { router as fileBrowserRouter } from './api/file-browser/router'; import { devProxyRouter } from './api/dev-proxy/router'; import { pluginsRouter } from './api/plugins/router'; -import { isPluginPublicPath, pluginForProtocolHeaders } from './plugins/public-paths'; +import { isPluginPublicPath, pluginForProtocolHeaders, pluginForRootPath } from './plugins/public-paths'; import { agentHandoffRouter } from './api/agent-handoff/router'; import { terminalRouter } from './api/terminal/sidecar-server'; import { sendoffRouter } from './api/sendoff/router'; @@ -104,17 +104,21 @@ const corsMiddleware = cors({ allowHeaders: ['Content-Type', 'Authorization'], }); -// The DAV doors are the one place CORS must NOT run, because hono's cors() answers every OPTIONS itself -// as a preflight — 204, no body, no DAV headers — and never calls the route beneath it. +// A plugin's TOP-LEVEL paths are the one place CORS must NOT run, because hono's cors() answers every +// OPTIONS itself as a preflight — 204, no body, none of the route's own headers — and never calls the +// route beneath it. // -// OPTIONS is not a preflight to a DAV client. It is how the client asks what the server can do, and the -// answer it needs is the `DAV: 1, 2, 3, calendar-access, addressbook` header. iOS sends it during account -// setup and refuses the account when it is missing, reporting the failure as "Cannot connect using SSL" — -// a message about TLS for a problem that has nothing to do with TLS, which is how this cost an evening. +// The case that taught this is DAV. OPTIONS is not a preflight to a DAV client: it is how the client asks +// what the server can do, and the answer it needs is the `DAV: 1, 2, 3, calendar-access, addressbook` +// header. iOS sends it during account setup and refuses the account when it is missing, reporting the +// failure as "Cannot connect using SSL" — a message about TLS for a problem that has nothing to do with +// TLS, which is how this cost an evening. // -// Nothing is lost by skipping it: a CalDAV client is not a browser and has no origin to check. -const isDavPath = (path: string) => - path === '/dav' || path.startsWith('/dav/') || path === '/.well-known/caldav' || path === '/.well-known/carddav'; +// Nothing is lost by skipping it. A top-level path exists because something that is NOT a browser has to +// reach it — a DAV client, a phone, a protocol handler — and those have no origin to check. This was +// `isDavPath`, a literal list of four paths, until caldav became a plugin and took them with it; asking +// the claim registry means the carve-out follows whoever owns the route instead of naming it here. +const isPluginRootPath = (path: string) => pluginForRootPath(path) !== null; // The mount table, as DATA rather than forty statements. // @@ -195,7 +199,7 @@ export const UNPROTECTED_API_PREFIXES: string[] = [ export function buildHonoApp(plugins: MountedPlugin[] = []): Hono<{ Variables: HonoVariables }> { const app = new Hono<{ Variables: HonoVariables }>(); - app.use((ctx, next) => (isDavPath(ctx.req.path) ? next() : corsMiddleware(ctx, next))); + app.use((ctx, next) => (isPluginRootPath(ctx.req.path) ? next() : corsMiddleware(ctx, next))); /* A plugin's PUBLIC router, mounted above everything — the gate, `userMiddleware`, the whole platform API. @@ -318,21 +322,24 @@ export function buildHonoApp(plugins: MountedPlugin[] = []): Hono<{ Variables: H app.route('/api', protectedRouter); + // Every error is JSON, shape `{ error: string }` — success is already JSON, so a text/plain failure + // was the one response a client had to special-case. An OBJECT returnValue passes through untouched: + // callers rely on its fields, and wrapping it would break them. app.onError((error, ctx) => { if (error instanceof CustomError) { if (error.returnValue) { if (typeof error.returnValue === 'string') { - return ctx.text(error.returnValue, error.statusCode); + return ctx.json({ error: error.returnValue }, error.statusCode); } else { return ctx.json(error.returnValue, error.statusCode); } } - return ctx.text(error.message, error.statusCode); + return ctx.json({ error: error.message }, error.statusCode); } console.error('Unexpected error:', error.message); console.log(error.stack); - return ctx.text('Internal Server Error', 500); + return ctx.json({ error: 'Internal Server Error' }, 500); }); return app; diff --git a/src/servers/plugins/manifest.ts b/src/servers/plugins/manifest.ts index 4caeeb04..0cc1773b 100644 --- a/src/servers/plugins/manifest.ts +++ b/src/servers/plugins/manifest.ts @@ -589,20 +589,62 @@ const RESERVED_ROOT = new Set([ 'index.html', ]); +/** + * Names under `/.well-known` a first-party plugin may claim. + * + * `.well-known` is IANA's registry namespace (RFC 8615) and the whole point of it is that a name in there + * means one specific thing — so claiming a name from it is not the platform inventing a URL, it is a + * plugin answering the question that name asks. `caldav` and `carddav` are RFC 6764's discovery paths: + * a client is given a bare domain and probes them before it has any credential. + * + * An ALLOW-LIST rather than "any name under .well-known", because the namespace also holds things that + * must never move — `acme-challenge` is how this machine gets its TLS certificates, and a plugin owning + * it could take the domain. Adding a name here is a deliberate act; there is no pattern that grants one. + */ +const WELL_KNOWN_CLAIMABLE = new Set(['caldav', 'carddav']); + /** * Check one declared ROOT path, returning a reason it is refused or null. * * Stricter than `publicPathProblem` because the surface is: this is the platform's own namespace, not the * plugin's, so a plugin gets to claim a single name and nothing structural. + * + * ── firstParty ── + * + * A reserved name is refused for everyone EXCEPT a first-party plugin, and that exception exists because + * of what "reserved" was recording. `dav` and `.well-known` are in the list because the PLATFORM serves + * them today, not because they are dangerous in themselves — and when caldav becomes a plugin, the thing + * the reservation was protecting is the plugin. Refusing it would mean the platform permanently owning + * routes for a feature it no longer contains. + * + * A THIRD-PARTY plugin is still refused every reserved name, and that is the line the owner drew on + * 2026-08-27: this is fine for a plugin we wrote, and letting a stranger's plugin claim `/dav` — or + * anything else the platform is trusted to answer — is a question that needs thinking about properly + * rather than falling out of a flag. `api` stays refused for everyone, first-party included: it is where + * all of Officer lives and `protocolHeaders` is the only sanctioned way to touch it. */ -export function rootPathProblem(path: unknown): string | null { +export function rootPathProblem(path: unknown, firstParty = false): string | null { if (typeof path !== 'string' || !path) return 'must be a non-empty string'; if (!path.startsWith('/')) return `"${path}" must start with "/"`; const segment = path.slice(1); + + // A two-segment claim under `.well-known`, which the single-segment rule below would refuse. First-party + // only and allow-listed by name — see WELL_KNOWN_CLAIMABLE. + const wellKnown = /^\.well-known\/([a-z][a-z0-9-]{0,38})$/.exec(segment); + if (wellKnown) { + if (!firstParty) return `"${path}" is reserved by the platform`; + if (!WELL_KNOWN_CLAIMABLE.has(wellKnown[1]!)) { + return `"${path}" is not a claimable .well-known name`; + } + return null; + } + if (!/^[a-z][a-z0-9-]{0,38}$/.test(segment)) { return `"${path}" must be a single lowercase segment, e.g. "/identity"`; } - if (RESERVED_ROOT.has(segment)) return `"${path}" is reserved by the platform`; + // `api` is refused even to us. Everything of Officer's lives under it. + if (segment === 'api') return `"${path}" is reserved by the platform`; + if (RESERVED_ROOT.has(segment) && !firstParty) return `"${path}" is reserved by the platform`; return null; } @@ -742,7 +784,7 @@ export function manifestProblems(appName: string, manifest: Partial { expect(refused).toEqual([]); }); - // The whole point of the reserved list: a plugin claiming these would shadow the platform for every - // request, and `/api` in particular is where all of Officer lives. - test.each([['/api'], ['/auth'], ['/plugins'], ['/dav']])('refuses the reserved segment %s', (root) => { - const { segments, refused } = resolvePluginRootPaths(withRoots('evil', [root]), new Set()); + const thirdParty = (appName: string, roots: string[]) => { + const p = plugin(appName, undefined, 'someone-else'); + (p.manifest as { unauthenticatedRootPaths?: string[] }).unauthenticatedRootPaths = roots; + return p; + }; + + // `/api` is refused to EVERYONE, first-party included. It is where all of Officer lives, and + // `protocolHeaders` is the only sanctioned way to touch it. + test('refuses /api even to a first-party plugin', () => { + const { segments, refused } = resolvePluginRootPaths(withRoots('ours', ['/api']), new Set()); expect(segments).toEqual([]); expect(refused).toHaveLength(1); }); + // The rest of the reserved list records what the PLATFORM serves today, which is a different claim from + // "dangerous". A first-party plugin may take one back — caldav owning `/dav` is the whole reason — and a + // third-party plugin may not. The owner drew that line on 2026-08-27: fine for a plugin we wrote, + // and a stranger's plugin claiming `/dav` is a question to think about properly rather than a flag. + test.each([['/auth'], ['/plugins'], ['/dav'], ['/assets']])( + 'refuses the reserved segment %s to a THIRD-PARTY plugin', + (root) => { + const { segments, refused } = resolvePluginRootPaths(thirdParty('stranger', [root]), new Set()); + expect(segments).toEqual([]); + expect(refused).toHaveLength(1); + }, + ); + + test('lets a FIRST-PARTY plugin claim a reserved segment — caldav taking /dav', () => { + const { segments, refused } = resolvePluginRootPaths(withRoots('caldav', ['/dav']), new Set()); + expect(segments).toEqual(['dav']); + expect(refused).toEqual([]); + }); + + // RFC 6764's discovery paths: a client is given a bare domain and probes these before it has any + // credential. Two segments, which the single-segment rule refuses — allowed by name, and by name only. + test('lets a first-party plugin claim an allow-listed .well-known name', () => { + const { segments, refused } = resolvePluginRootPaths( + withRoots('caldav', ['/.well-known/caldav', '/.well-known/carddav']), + new Set(), + ); + expect(segments).toEqual(['.well-known/caldav', '.well-known/carddav']); + expect(refused).toEqual([]); + }); + + // The one that matters most in that namespace: acme-challenge is how this machine gets its TLS + // certificates, and a plugin owning it could take the domain. Not an allow-list entry, so refused — + // to us as much as to anyone. + test('refuses a .well-known name that is not allow-listed, first-party or not', () => { + expect(resolvePluginRootPaths(withRoots('ours', ['/.well-known/acme-challenge']), new Set()).segments).toEqual([]); + expect(resolvePluginRootPaths(thirdParty('stranger', ['/.well-known/caldav']), new Set()).segments).toEqual([]); + }); + test.each([['/a/b'], ['identity'], ['/Identity'], ['/']])('refuses the malformed segment %s', (root) => { expect(resolvePluginRootPaths(withRoots('evil', [root]), new Set()).segments).toEqual([]); }); diff --git a/src/servers/plugins/public-paths.ts b/src/servers/plugins/public-paths.ts index fad5c258..069577b5 100644 --- a/src/servers/plugins/public-paths.ts +++ b/src/servers/plugins/public-paths.ts @@ -1,4 +1,10 @@ -import { mountPrefix, publicPathProblem, rootPathProblem, type DiscoveredPlugin } from './manifest'; +import { + mountPrefix, + publicPathProblem, + rootPathProblem, + FIRST_PARTY_PUBLISHER, + type DiscoveredPlugin, +} from './manifest'; // Which plugin paths are served ABOVE the account gate. // @@ -111,8 +117,12 @@ export function resolvePluginRootPaths( ): { segments: string[]; refused: string[] } { const segments: string[] = []; const refused: string[] = []; + // Provenance decides whether a RESERVED name may be claimed. A first-party plugin can take one back + // from the platform — which is what caldav owning `/dav` is — and a third-party plugin cannot. + const firstParty = plugin.manifest.publisher === FIRST_PARTY_PUBLISHER; + for (const path of plugin.manifest.unauthenticatedRootPaths ?? []) { - const problem = rootPathProblem(path); + const problem = rootPathProblem(path, firstParty); if (problem) { refused.push(`${plugin.appName}: ${problem}`); continue;