Merge pull request 'docs: instance branches should be orphan branches' (#18) from docs/instance-branch-note into main

Records why, so the next person doesn't rebuild the trap: a branch off main
carries a full copy of the app it has no reason to have and drifts behind it,
and syncing it via `git merge origin/main` silently replaces the instance
manifests with main's placeholders — no conflict, because only main touches
those paths.

instance/dnspegasus has been converted accordingly.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

README.md

@@ -410,6 +410,25 @@ claude plugin marketplace add https://your-git-host/you/shared-memory.git#instan
 The `#ref` suffix is undocumented in `claude plugin marketplace add --help` but is
 honored and persisted in `known_marketplaces.json` (verified on Claude Code 2.1.220).
 
+**Make that an orphan branch, not a branch off `main`.** `marketplace add` reads
+only the manifests, so the branch needs nothing else:
+
+```bash
+git checkout --orphan instance/<name>
+git rm -rf --cached . && find . -mindepth 1 -maxdepth 1 ! -name .git -exec rm -rf {} +
+# restore just .claude-plugin/marketplace.json, plugin/.claude-plugin/plugin.json,
+# plugin/.mcp.json — fill in your URL and client ID
+claude plugin validate . && git add -A && git commit && git push
+```
+
+A branch off `main` carries a full copy of the application it has no reason to
+have, so it drifts and someone can cut a stale deploy from it. Worse, syncing it
+means `git merge origin/main`, which **silently replaces those manifests** with
+the placeholders below — no conflict is raised, because only `main` ever touches
+those paths. With no shared history there is nothing to sync and nothing to
+clobber; if the manifest format changes upstream, hand-edit the three files and
+re-run `claude plugin validate .`.
+
 ### B. OAuth flow (manual, per-machine)
 
 ```bash

apps/web/app/.well-known/oauth-protected-resource/route.ts

@@ -26,7 +26,7 @@ export function GET() {
     // The MCP application's issuer, which is not necessarily the Web UI's —
     // see mcpIssuer(). Advertising the wrong one sends clients to a discovery
     // document whose tokens this endpoint will then reject on `iss`.
-    authorization_servers: [mcpIssuer()],
+    authorization_servers: [mcpIssuer()],  // as configured, slash and all
     scopes_supported: ["openid", "profile", "email", audienceScope],
     bearer_methods_supported: ["header"],
     resource_documentation: `${resource}/`,

apps/web/lib/auth/jwt.ts

@@ -29,7 +29,25 @@ const g = globalThis as GlobalWithJwks;
  * application slug, so this is NOT interchangeable with OIDC_ISSUER.
  */
 export function mcpIssuer(): string {
-  return (env().OIDC_ISSUER_MCP ?? env().OIDC_ISSUER).replace(/\/$/, "");
+  return env().OIDC_ISSUER_MCP ?? env().OIDC_ISSUER;
+}
+
+/**
+ * Issuer values accepted for the `iss` claim.
+ *
+ * jose compares `iss` by exact string, and IdPs are inconsistent about the
+ * trailing slash: Authentik emits `.../application/o/<slug>/` while the same
+ * value is routinely configured without it. Normalizing to one form and
+ * comparing against that fails whenever the two disagree — which is exactly
+ * how this broke: the URL-safe (stripped) form was reused for the claim check
+ * against a token whose `iss` ended in a slash.
+ *
+ * Accept both spellings rather than making correctness depend on how someone
+ * typed an env var.
+ */
+function acceptedIssuers(): [string, string] {
+  const bare = mcpIssuer().replace(/\/$/, "");
+  return [bare, `${bare}/`];
 }
 
 function jwks() {
@@ -37,7 +55,7 @@ function jwks() {
   // Authentik discovery is at `${issuer}/.well-known/openid-configuration`;
   // the JWKS URI is normally `${issuer}/jwks/` or `${issuer}/.well-known/jwks.json`.
   // Authentik canonically serves `${issuer}/jwks/`.
-  const url = new URL(`${mcpIssuer()}/jwks/`);
+  const url = new URL(`${mcpIssuer().replace(/\/$/, "")}/jwks/`);
   g.__sharedMemoryJwks = createRemoteJWKSet(url, {
     cacheMaxAge: 10 * 60 * 1000, // 10 min
     cooldownDuration: 30 * 1000,
@@ -126,7 +144,7 @@ export async function authenticateBearer(authHeader: string | null): Promise<Aut
     }
 
     const { payload } = await jwtVerify(token, jwks(), {
-      issuer: mcpIssuer(),
+      issuer: acceptedIssuers(),
       audience: env().OIDC_AUDIENCE,
     });
     if (!payload.sub) {