@creeperhost/modlens-mcp 1.6.24 → 1.6.27

package/README.md

@@ -6,10 +6,11 @@ Store mod metadata, class indexes, mixin targets, AT/AW entries, and decompiled
 
 ## Optional live development client
 
-The `runtime` MCP tool can prepare and launch a **Minecraft 26.3 / Java 25** dev
-client, detect IntelliJ launches, monitor JVM failures and memory pressure, and
-control input without desktop automation. It supports normal, visible watch-only,
-and hidden windows. Ask the AI to call `runtime` with `action:"help"` or set it up
+The `runtime` MCP tool can prepare and launch a Minecraft development client,
+detect IntelliJ launches, monitor JVM failures and memory pressure, capture
+screenshots, and control game input. It uses SDL on Minecraft 26.3, GLFW on
+1.13–1.21, and LWJGL2 on 1.7.10–1.12.2. Ask the AI
+to call `runtime` with `action:"help"` or set it up
 for your mod project. With remote MCP, Codex runs the local `--runtime` helper;
 with local stdio MCP, the tools execute directly. No second MCP connection is needed.
 See [runtime setup, examples, and compatibility limits](RUNTIME.md).
@@ -1105,6 +1106,8 @@ npx -y @creeperhost/modlens-mcp --local-mod --request-file local-request.json
 
 For built-in OAuth sign-in, set `MODLENS_HOSTED_AUTH=oauth` and configure `MODLENS_OAUTH_PUBLIC_URL` (the public `/mcp` URL), `MODLENS_OAUTH_ISSUER`, `MODLENS_OAUTH_CLIENT_ID`, `MODLENS_OAUTH_SCOPES`, and a stable base64-encoded 32-byte `MODLENS_OAUTH_STORAGE_KEY`. Set `MODLENS_OAUTH_PROFILE_URL` unless provider discovery supplies a userinfo endpoint. The provider must support authorization code with S256 PKCE and refresh tokens for persistent sign-in. Register `<public origin>/oauth/upstream/callback` as the provider client's redirect URI. `MODLENS_OAUTH_CLIENT_SECRET` is optional. `MODLENS_OAUTH_SUBJECT_FIELD` defaults to `sub`; optional `MODLENS_OAUTH_REQUIRED_FIELD` and `MODLENS_OAUTH_REQUIRED_VALUE` restrict access using a profile field. The OAuth routes and well-known metadata must be reachable through the public HTTPS origin. OAuth mode does not enable hosted Minecraft source.
 
+Dynamic client registration accepts the optional `client_name` metadata field. The consent page displays this self-reported name alongside the registered callback origin. Existing clients must register again to supply a name; clients without one appear as "Unnamed application".
+
 OAuth clients, short-lived authorization state, grants, and tokens are stored in the configured database. A multi-replica deployment must point every replica at the same persistent database and use the same `MODLENS_OAUTH_STORAGE_KEY`; the embedded SQLite default is suitable only for a single replica. Otherwise, a browser redirect can land on a replica that cannot see the authorization created by the previous request and fail with `invalid_grant`.
 
 The server writes structured OAuth lifecycle events to stderr with a short `flow` identifier. Failures also include an `incident` reference shown on browser-facing error pages, so one report can be matched to its server log. These events include the stage, route, status, error code, hashed client reference, and redirect origin where relevant; authorization codes, state values, PKCE material, tokens, provider profiles, and subjects are never logged.

package/RUNTIME.md

@@ -1,9 +1,11 @@
 # Optional live Minecraft development runtime
 
-ModLens can launch or detect a **Minecraft Java 26.3 / Java 25** development client,
-observe JVM health and failures, and send inputs directly through LWJGL's SDL3
-bindings. Desktop automation and an IntelliJ plugin are not required. This is an
-initial 26.3 adapter, not a claim of compatibility with older versions or every modpack.
+ModLens can launch or detect a Minecraft development client and observe JVM
+health and failures. One Java agent JAR supports Minecraft 1.7.10 and newer.
+It hooks SDL on 26.3, GLFW on 1.13–1.21, and LWJGL2 on 1.7.10–1.12.2 for
+input and screenshots. JFR diagnostics are available when the game runs on
+Java 11 or newer.
+Desktop automation and an IntelliJ plugin are not required.
 
 ## Let the AI set it up
 
@@ -18,6 +20,12 @@ The always-discoverable `runtime` MCP tool describes this workflow. The AI calls
 {"action":"setup","projectDir":"F:/Git/my-mod","mcVersion":"26.3","mode":"observe","gradleTask":"runClient"}
 ```
 
+For an older client, specify its version. For example:
+
+```json
+{"action":"setup","projectDir":"F:/Git/my-old-mod","mcVersion":"1.7.10","mode":"observe","gradleTask":"runClient"}
+```
+
 With local stdio, that tool call executes directly. With remote MCP, it returns
 `executed:false` and a **local execution plan**. Codex writes the supplied JSON
 request to a local file and invokes the version-matched helper through its local
@@ -38,8 +46,8 @@ node /path/to/modlens-mcp/dist/launcher.js --runtime --request-file runtime-requ
 
 The helper automatically starts an authenticated loopback companion. It stays
 running between commands, detects configured IntelliJ launches, and collects
-events while Codex is doing other work. It requires Node.js and the same Minecraft
-JDK as the direct MCP workflow; it does not bootstrap a source database or modify
+events while Codex is doing other work. It requires Node.js and a JDK supported by
+the Minecraft client (Java 8 or newer); it does not bootstrap a source database or modify
 MCP configuration. There is no second local MCP connection, Cloudflare dependency,
 public runtime endpoint, or automatic upload of diagnostics to remote ModLens.
 Codex must have local terminal/file access on the Minecraft PC; a cloud-only shell
@@ -75,9 +83,9 @@ For multi-project builds, select the actual client task, e.g. `:fabric:runClient
 The task must extend Gradle `JavaExec`. A generated init script adds the agent to
 that task only. Custom launch plugins which don't expose a JavaExec task get an
 actionable error. Setup also returns `vmOptions` for the actual game JVM in an
-existing Application run configuration. Add every entry, including
-`-XX:StackShadowPages=32`: the 26.3 client needs this setting independently of the
-agent. The generated Gradle/IntelliJ launch supplies it automatically, only to the
+existing Application run configuration. For 26.3, add every entry, including
+`-XX:StackShadowPages=32`: that client needs this setting independently of the
+agent. Older versions receive only the agent VM option. The generated Gradle/IntelliJ launch supplies the required options, only to the
 selected client task. **Do not put these options on IntelliJ itself or the Gradle
 daemon.** Quote each whole VM option if it contains spaces. The singular `vmOption`
 field remains available for callers that only need the agent argument.
@@ -94,7 +102,7 @@ include the compiled agent; end users do not need to compile it.
 | --- | --- | --- |
 | `interactive` | Visible game window | Human controls; MCP input rejected |
 | `observe` | Visible game window | MCP controls; physical game input filtered |
-| `hidden` | Hidden game window | MCP controls; physical game input filtered |
+| `hidden` | Hidden game window (SDL/GLFW) | MCP controls; physical game input filtered |
 
 Switch a connected client with:
 
@@ -105,7 +113,8 @@ Switch a connected client with:
 Observe mode uses the actual game window as a watch-only display. OS window
 management, including closing it, remains available. Hidden mode still uses a
 graphics device and desktop/display environment; it is not a GPU-free server.
-Input interception covers the normal SDL paths. Mods using another native input
+LWJGL2 clients support `interactive` and `observe`; their Java display API does
+not support hidden mode. Input interception covers the normal LWJGL paths. Mods using another native input
 path need a separate adapter. This is a development convenience, not an OS security
 boundary. Switching to interactive returns control; click the game to resume mouse
 capture normally.
@@ -130,7 +139,7 @@ capture normally.
 ```
 
 Key names include A–Z, 0–9, SPACE, ENTER, ESCAPE, TAB, arrows, modifiers and F1–F12.
-Numeric strings outside single digits represent SDL scancodes. Mouse buttons are
+Numeric strings outside single digits represent backend-specific key codes. Mouse buttons are
 1=left, 2=middle, 3=right. Coordinates are **window pixels**, not scaled GUI units;
 relative movements are deltas. Text sends text-input events independently of keys.
 `scroll` accepts `x` and `y`. Inputs are delivered to the event loop; they do not
@@ -142,8 +151,8 @@ been unreachable for five seconds (as soon as the game event loop runs). Use
 automatically after uncertain delivery. A timeout means execution is unknown;
 inspect state before retrying an action.
 
-Screenshots use 26.3's own renderer-independent screenshot API, after
-`state.observation.gameLoaded` becomes true. PNGs are returned as MCP image content
+On 26.3, screenshots use Minecraft's screenshot API after
+`state.observation.gameLoaded` becomes true. GLFW and LWJGL2 clients capture the OpenGL framebuffer. PNGs are returned as MCP image content
 by `artifact` over local stdio MCP. The CLI returns the local PNG path for Codex's
 image viewer instead of base64 in terminal text. `threads` writes a thread dump including detected deadlock IDs;
 `recording` writes the recent JFR recording. Files live under
@@ -152,8 +161,8 @@ contain application data; delete old session directories when finished.
 
 ## Monitoring and failure semantics
 
-The agent samples heap/non-heap usage, thread counts and GC counters every second,
-keeps a bounded two-minute/16 MiB JFR recording, captures uncaught exceptions while
+The agent samples heap/non-heap usage, thread counts and GC counters every second.
+On Java 11+, it keeps a bounded two-minute/16 MiB JFR recording. It captures uncaught exceptions while
 chaining the previous handler, and hooks the game's fatal crash reporting path.
 It does not intercept every logged/caught exception or exceptions consumed by a
 custom per-thread handler. The optional Minecraft crash hook covers the normal
@@ -203,15 +212,11 @@ not guarantee an idle Codex task wakes up; host scheduling is separate from MCP.
   runtime actions on the Minecraft PC using the same request schema and dispatcher
   as local stdio MCP. HTTP handlers never execute user-supplied local paths.
 - The agent connects only to authenticated loopback HTTP; no browser control routes.
-- SDL events, keyboard state and mouse state are kept consistent. Input/window code
-  lives in `SdlAdapter`; optional game APIs live in `Minecraft263`.
-- Exact transformation descriptors live in `Transformer`. It uses Java 25's
-  standard Class-File API and an isolated bootstrap bridge, with no ASM/Gson or
-  native agent dependencies to collide with mod loaders.
-- Setup accepts `minecraftHooks:false` to isolate compatibility problems. SDL
-  controls and JVM diagnostics remain available; screenshots and structured game
-  state require the Minecraft adapter. A GLFW backend belongs to a future backport:
-  vanilla 26.3 uses SDL3.
+- SDL events, keyboard state and mouse state are kept consistent by `SdlAdapter`;
+  optional 26.3 game APIs live in `Minecraft263`. GLFW and LWJGL2 input use
+  `LegacyInput` and a relocated ASM transformer.
+- Setup accepts `minecraftHooks:false` for the optional 26.3 game hooks. SDL
+  control and JVM diagnostics remain available.
 - Capability presence and validation are distinct. Tests cover selected environments;
   Fabric/NeoForge launchers and rendering replacements still require their own runs.
 

package/dist/hosted-oauth.d.ts

@@ -11,10 +11,15 @@ export declare class HostedOAuth {
     private config;
     private database;
     private ready?;
+    private readonly instance;
     private requestCounts;
+    private refreshes;
     private constructor();
     private audit;
     private clientRef;
+    private grantRef;
+    private observeTokenResponse;
+    private describeTokenResponse;
     logError(method: string | undefined, route: string, error: HostedOAuthError): string;
     static create(env?: NodeJS.ProcessEnv, database?: () => Promise<Database>): Promise<HostedOAuth>;
     private db;
@@ -25,6 +30,7 @@ export declare class HostedOAuth {
     private getObject;
     private takeObject;
     private client;
+    private clientName;
     private upstreamToken;
     private profile;
     private callbackUrl;
@@ -35,6 +41,7 @@ export declare class HostedOAuth {
     authenticate(req: IncomingMessage): Promise<string>;
     private revoke;
     private issue;
+    private refresh;
     private limit;
     handle(req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean>;
     private metadataUrlPath;

package/dist/hosted-oauth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hosted-oauth.d.ts","sourceRoot":"","sources":["../src/hosted-oauth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC,KAAK,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC;AAclD,qBAAa,gBAAiB,SAAQ,KAAK;IACH,MAAM;IAAe,IAAI;IAA6B,MAAM,CAAC,EAAE,MAAM;gBAA7F,OAAO,EAAE,MAAM,EAAS,MAAM,SAAM,EAAS,IAAI,SAAoB,EAAS,MAAM,CAAC,EAAE,MAAM,YAAA;CAC5G;AA2JD,qBAAa,WAAW;IAGA,OAAO,CAAC,MAAM;IAAc,OAAO,CAAC,QAAQ;IAFhE,OAAO,CAAC,KAAK,CAAC,CAAgB;IAC9B,OAAO,CAAC,aAAa,CAAwD;IAC7E,OAAO;IAEP,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,SAAS;IAEjB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,MAAM;WAOvE,MAAM,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,QAAQ,GAAE,MAAM,OAAO,CAAC,QAAQ,CAAS,GAAG,OAAO,CAAC,WAAW,CAAC;YAqC5G,EAAE;IAkBhB,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,IAAI;YAOE,SAAS;YAST,WAAW;YAOX,SAAS;YAOT,UAAU;YAWV,MAAM;YAQN,aAAa;YAsBb,OAAO;IAiCrB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,WAAW;IAInB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAIpC,YAAY,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,gBAAgB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAa7E,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;YA4B3C,MAAM;YAMN,KAAK;IASnB,OAAO,CAAC,KAAK;IAYP,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;IAmOnF,OAAO,CAAC,eAAe;CAC1B"}
+{"version":3,"file":"hosted-oauth.d.ts","sourceRoot":"","sources":["../src/hosted-oauth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC,KAAK,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC;AAclD,qBAAa,gBAAiB,SAAQ,KAAK;IACH,MAAM;IAAe,IAAI;IAA6B,MAAM,CAAC,EAAE,MAAM;gBAA7F,OAAO,EAAE,MAAM,EAAS,MAAM,SAAM,EAAS,IAAI,SAAoB,EAAS,MAAM,CAAC,EAAE,MAAM,YAAA;CAC5G;AA8JD,qBAAa,WAAW;IAKA,OAAO,CAAC,MAAM;IAAc,OAAO,CAAC,QAAQ;IAJhE,OAAO,CAAC,KAAK,CAAC,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,aAAa,CAAwD;IAC7E,OAAO,CAAC,SAAS,CAAuD;IACxE,OAAO;IAEP,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,QAAQ;IAEhB,OAAO,CAAC,oBAAoB;IAoB5B,OAAO,CAAC,qBAAqB;IAY7B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,MAAM;WAOvE,MAAM,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,QAAQ,GAAE,MAAM,OAAO,CAAC,QAAQ,CAAS,GAAG,OAAO,CAAC,WAAW,CAAC;YAqC5G,EAAE;IAoBhB,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,IAAI;YAOE,SAAS;YAST,WAAW;YAOX,SAAS;YAOT,UAAU;YAWV,MAAM;YAQN,UAAU;YAOV,aAAa;YAsBb,OAAO;IAiCrB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,WAAW;IAInB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAIpC,YAAY,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,gBAAgB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAa7E,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;YA6B3C,MAAM;YAON,KAAK;YASL,OAAO;IAiDrB,OAAO,CAAC,KAAK;IAYP,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;IA2OnF,OAAO,CAAC,eAAe;CAC1B"}

package/dist/hosted-oauth.js

@@ -15,19 +15,20 @@ const sha = (value) => createHash("sha256").update(value).digest("hex");
 const token = (prefix) => prefix + randomBytes(32).toString("base64url");
 const now = () => Math.floor(Date.now() / 1000);
 const json = (res, status, value, headers = {}) => {
-    res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store", ...headers });
+    res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store", Pragma: "no-cache", ...headers });
     res.end(JSON.stringify(value));
 };
 const redirect = (res, url) => {
     res.writeHead(302, { Location: url.toString(), "Cache-Control": "no-store" });
     res.end();
 };
+const htmlCsp = (formAction = "'self'") => `default-src 'none'; style-src 'unsafe-inline'; form-action ${formAction}; base-uri 'none'; frame-ancestors 'none'`;
 const htmlHeaders = {
     "Content-Type": "text/html; charset=utf-8",
     "Cache-Control": "no-store",
     "Referrer-Policy": "no-referrer",
     "X-Content-Type-Options": "nosniff",
-    "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'",
+    "Content-Security-Policy": htmlCsp(),
 };
 const escapeHtml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;")
     .replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
@@ -51,7 +52,8 @@ main{width:100%;display:flex;flex:1;flex-direction:column;align-items:center;jus
 .brand{display:flex;align-items:center;justify-content:center;margin:0 auto 22px;color:white}.brand-copy{text-align:center;line-height:1}.brand-copy strong{display:block;font-size:21px;font-weight:750;letter-spacing:.13em}.brand-copy small{display:block;margin-top:7px;color:#ffffff73;font-size:10px;font-weight:650;letter-spacing:.31em}
 .card{width:min(638px,calc(100vw - 34px));border:1px solid var(--line);outline:1px solid var(--line-dark);border-radius:10px;overflow:hidden;background:linear-gradient(180deg,var(--panel-top),var(--panel-bottom));box-shadow:0 0 25px rgba(0,0,0,.2)}
 .content{padding:32px;text-align:left}.eyebrow{display:block;margin:0 0 7px;color:${tone === "error" ? "var(--error)" : "#72d96e"};font-size:10px;font-weight:700;letter-spacing:.17em}.content h1{margin:0;color:var(--text);font-family:"Centra No 2","Segoe UI Variable","Segoe UI",sans-serif;font-size:30px;line-height:36px;letter-spacing:-.03em;font-weight:500}.lead,.content>p{margin:9px 0 0;color:#ffffffb3;font-size:14px;line-height:1.6}
-.app{display:flex;align-items:center;gap:12px;margin:20px 0;padding:12px;background:var(--panel-deep);border:1px solid var(--line);border-radius:6px}.app-icon{display:flex;align-items:center;justify-content:center;width:36px;height:36px;flex:0 0 auto;border-radius:50%;background:#06c20020;color:#8cdd88;font:600 12px/1 Consolas,monospace}.app-copy{min-width:0}.app-origin{display:block;overflow:hidden;text-overflow:ellipsis;color:#f0f0f5;font:600 13px/1.45 Consolas,monospace;white-space:nowrap}.app-label{display:block;color:var(--muted);font-size:11px}
+.app{display:flex;align-items:center;gap:12px;margin:20px 0 12px;padding:12px;background:var(--panel-deep);border:1px solid var(--line);border-radius:6px}.app-icon{display:flex;align-items:center;justify-content:center;width:36px;height:36px;flex:0 0 auto;border-radius:50%;background:#06c20020;color:#8cdd88;font:600 12px/1 Consolas,monospace}.app-copy{min-width:0}.app-name{display:block;color:#f0f0f5;font-size:14px}.app-label{display:block;color:var(--muted);font-size:11px}
+.connection-details{color:var(--muted);font-size:12px}.connection-details summary{width:max-content;max-width:100%;cursor:pointer;color:#d7dbe0}.connection-details summary:focus-visible{outline:2px solid var(--focus);outline-offset:3px}.connection-details p{margin:10px 0 6px}.callback-url{display:block;overflow-wrap:anywhere;color:#d7dbe0;font:500 12px/1.5 Consolas,monospace}
 .permissions{margin:20px 0;padding-left:22px;color:#d7dbe0;font-size:13px;line-height:1.65}.permissions li+li{margin-top:9px}.permissions li::marker{color:#48c544}
 form{margin:0}.actions{display:grid;grid-template-columns:1fr 1.6fr;gap:12px;margin-top:24px}button{display:inline-flex;min-height:48px;align-items:center;justify-content:center;appearance:none;border:1px solid transparent;border-radius:4px;padding:10px 16px;color:white;font:500 14px/1 "Segoe UI Variable","Segoe UI",sans-serif;cursor:pointer;transition:box-shadow .18s ease,background .18s ease}button:focus-visible,a:focus-visible{outline:2px solid var(--focus);outline-offset:3px}.primary{background:linear-gradient(to left,var(--green),var(--green-dark))}.primary:hover{box-shadow:0 0 20px #42d80854}.secondary{background:#242b33;border-color:#343b44}.secondary:hover{background:#2d353e}
 .note{margin:12px 0 0!important;color:#ffffff73!important;font-size:11px!important}.error-code{display:block;margin-top:20px;padding:12px;border:1px solid #d1005650;border-radius:4px;background:#d1005615;color:var(--error);font:12px/1.55 Consolas,monospace;overflow-wrap:anywhere}
@@ -176,15 +178,48 @@ export class HostedOAuth {
     config;
     database;
     ready;
+    instance = randomBytes(6).toString("hex");
     requestCounts = new Map();
+    refreshes = new Map();
     constructor(config, database) {
         this.config = config;
         this.database = database;
     }
     audit(event, fields = {}) {
-        console.error(`[modlens] oauth ${JSON.stringify({ event, ...fields })}`);
+        console.error(`[modlens] oauth ${JSON.stringify({ event, instance: this.instance, ...fields })}`);
     }
     clientRef(clientId) { return sha(clientId).slice(0, 12); }
+    grantRef(grantId) { return sha(grantId).slice(0, 12); }
+    observeTokenResponse(req, res, fields) {
+        const startedAt = performance.now();
+        let finished = false;
+        req.once("aborted", () => this.audit("token_request_aborted", fields));
+        res.once("finish", () => {
+            finished = true;
+            this.audit("token_response_finished", { ...fields, status: res.statusCode,
+                outcome: res.statusCode >= 400 ? "error" : fields.outcome,
+                durationMs: Math.round(performance.now() - startedAt) });
+        });
+        res.once("close", () => {
+            if (!finished)
+                this.audit("token_response_closed", { ...fields, status: res.statusCode,
+                    headersSent: res.headersSent, writableEnded: res.writableEnded, writableFinished: res.writableFinished,
+                    durationMs: Math.round(performance.now() - startedAt) });
+        });
+        res.once("error", error => this.audit("token_response_error", { ...fields, status: res.statusCode,
+            error: error.name, errorCode: error.code }));
+    }
+    describeTokenResponse(response) {
+        const access = typeof response.access_token === "string" ? response.access_token : undefined;
+        const refresh = typeof response.refresh_token === "string" ? response.refresh_token : undefined;
+        return {
+            outcome: "success", responseBytes: Buffer.byteLength(JSON.stringify(response)),
+            returnedRefresh: refresh !== undefined,
+            ...(access ? { accessRef: sha(access).slice(0, 12) } : {}),
+            ...(refresh ? { returnedRefreshRef: sha(refresh).slice(0, 12) } : {}),
+            ...(typeof response.expires_in === "number" ? { accessExpiresIn: response.expires_in } : {}),
+        };
+    }
     logError(method, route, error) {
         const incident = randomBytes(6).toString("hex");
         this.audit("request_failed", { incident, flow: error.flowId, method: method ?? "UNKNOWN", route,
@@ -236,6 +271,8 @@ export class HostedOAuth {
             this.ready = (async () => {
                 await db.$executeRawUnsafe(`CREATE TABLE IF NOT EXISTS hosted_oauth_clients (
                 id TEXT PRIMARY KEY, redirect_uris TEXT NOT NULL, created BIGINT NOT NULL)`);
+                await db.$executeRawUnsafe(`CREATE TABLE IF NOT EXISTS hosted_oauth_client_metadata (
+                id TEXT PRIMARY KEY, client_name TEXT NOT NULL)`);
                 await db.$executeRawUnsafe(`CREATE TABLE IF NOT EXISTS hosted_oauth_objects (
                 id TEXT PRIMARY KEY, kind TEXT NOT NULL, payload TEXT NOT NULL, expires BIGINT NOT NULL)`);
                 await db.$executeRawUnsafe(`CREATE TABLE IF NOT EXISTS hosted_oauth_grants (
@@ -295,6 +332,11 @@ export class HostedOAuth {
             throw new HostedOAuthError("Unknown OAuth client", 400, "invalid_client");
         return JSON.parse(rows[0].redirect_uris);
     }
+    async clientName(clientId) {
+        const db = await this.db();
+        const rows = await db.$queryRawUnsafe(`SELECT client_name FROM hosted_oauth_client_metadata WHERE id=$1`, clientId);
+        return rows[0]?.client_name;
+    }
     async upstreamToken(values) {
         const headers = { "Content-Type": "application/x-www-form-urlencoded" };
         values.set("client_id", this.config.clientId);
@@ -406,21 +448,22 @@ export class HostedOAuth {
         try {
             const profile = await this.profile(this.open(grant.upstream_access));
             if (!profile.allowed || profile.subject !== grant.subject) {
-                await this.revoke(grant.id);
+                await this.revoke(grant.id, "profile_access_denied");
                 throw new HostedOAuthError("Account access denied", 403, "access_denied");
             }
         }
         catch (error) {
             if (error instanceof HostedOAuthError && error.status === 401)
-                await this.revoke(grant.id);
+                await this.revoke(grant.id, "profile_unauthorized");
             throw error;
         }
         return sha(this.config.issuer + "\0" + grant.subject);
     }
-    async revoke(id) {
+    async revoke(id, reason) {
         const db = await this.db();
         await db.$executeRawUnsafe(`DELETE FROM hosted_oauth_access WHERE grant_id=$1`, id);
         await db.$executeRawUnsafe(`DELETE FROM hosted_oauth_grants WHERE id=$1`, id);
+        this.audit("grant_revoked", { grant: this.grantRef(id), reason });
     }
     async issue(grant) {
         const rawAccess = token("mla_");
@@ -429,6 +472,57 @@ export class HostedOAuth {
         await db.$executeRawUnsafe(`INSERT INTO hosted_oauth_access (token_hash,grant_id,expires) VALUES ($1,$2,$3)`, sha(rawAccess), grant.id, now() + expires);
         return { access_token: rawAccess, token_type: "Bearer", expires_in: expires, scope: "modlens" };
     }
+    async refresh(clientId, raw, requestRef) {
+        const db = await this.db();
+        const rows = await db.$queryRawUnsafe(`UPDATE hosted_oauth_grants SET refresh_hash=NULL
+            WHERE refresh_hash=$1 AND client_id=$2 AND refresh_expires>$3 RETURNING *`, sha(raw), clientId, now());
+        if (rows.length !== 1 || !rows[0].upstream_refresh) {
+            this.audit("refresh_rejected", { request: requestRef, client: this.clientRef(clientId), refreshRef: sha(raw).slice(0, 12),
+                reason: rows.length === 1 ? "no_upstream_refresh" : "not_current_or_missing" });
+            throw new HostedOAuthError("Invalid refresh token", 400, "invalid_grant");
+        }
+        const grant = rows[0];
+        let stage = "provider_token";
+        try {
+            const oldUpstreamRefresh = grant.upstream_refresh;
+            const upstream = await this.upstreamToken(new URLSearchParams({ grant_type: "refresh_token",
+                refresh_token: this.open(oldUpstreamRefresh) }));
+            grant.upstream_access = this.seal(upstream.access_token);
+            grant.upstream_refresh = this.seal(upstream.refresh_token ?? this.open(oldUpstreamRefresh));
+            grant.upstream_expires = now() + Math.max(1, Math.min(86400, Number(upstream.expires_in) || 300));
+            stage = "grant_update";
+            await db.$executeRawUnsafe(`UPDATE hosted_oauth_grants SET upstream_access=$2,upstream_refresh=$3,
+                upstream_expires=$4 WHERE id=$1`, grant.id, grant.upstream_access, grant.upstream_refresh, grant.upstream_expires);
+            stage = "profile";
+            const profile = await this.profile(upstream.access_token);
+            if (profile.subject !== grant.subject || !profile.allowed)
+                throw new HostedOAuthError("Account access denied", 403, "access_denied");
+            const next = token("mlr_");
+            grant.refresh_hash = sha(next);
+            stage = "rotation";
+            await db.$executeRawUnsafe(`UPDATE hosted_oauth_grants SET refresh_hash=$2 WHERE id=$1`, grant.id, grant.refresh_hash);
+            stage = "access_issue";
+            const access = await this.issue(grant);
+            const response = { ...access, refresh_token: next };
+            this.audit("refresh_issued", { request: requestRef, client: this.clientRef(clientId), grant: this.grantRef(grant.id),
+                previousRefreshRef: sha(raw).slice(0, 12), refreshRef: sha(next).slice(0, 12),
+                accessExpiresIn: Number(access.expires_in) });
+            return response;
+        }
+        catch (error) {
+            const retryable = error instanceof HostedOAuthError && error.status === 503;
+            this.audit("refresh_failed", { request: requestRef, client: this.clientRef(clientId), grant: this.grantRef(grant.id),
+                refreshRef: sha(raw).slice(0, 12), stage, retryable,
+                status: error instanceof HostedOAuthError ? error.status : undefined,
+                code: error instanceof HostedOAuthError ? error.code : undefined });
+            if (retryable) {
+                await db.$executeRawUnsafe(`UPDATE hosted_oauth_grants SET refresh_hash=$2 WHERE id=$1 AND refresh_hash IS NULL`, grant.id, sha(raw));
+            }
+            else
+                await this.revoke(grant.id, "refresh_failed");
+            throw error;
+        }
+    }
     limit(req, route, maximum) {
         const minute = Math.floor(now() / 60);
         const key = `${route}:${req.socket.remoteAddress ?? "unknown"}`;
@@ -477,12 +571,19 @@ export class HostedOAuth {
                 !redirects.every(value => typeof value === "string" && callbackSafe(value)) ||
                 (registration.token_endpoint_auth_method && registration.token_endpoint_auth_method !== "none"))
                 throw new HostedOAuthError("Invalid client registration");
+            const clientName = registration.client_name;
+            if (clientName !== undefined && (typeof clientName !== "string" || !clientName.trim() ||
+                clientName.length > 120 || /[\x00-\x1f\x7f]/.test(clientName)))
+                throw new HostedOAuthError("Invalid client name");
             const id = token("mlc_");
             const db = await this.db();
             await db.$executeRawUnsafe(`INSERT INTO hosted_oauth_clients (id,redirect_uris,created) VALUES ($1,$2,$3)`, id, JSON.stringify(redirects), now());
+            if (clientName !== undefined)
+                await db.$executeRawUnsafe(`INSERT INTO hosted_oauth_client_metadata (id,client_name) VALUES ($1,$2)`, id, clientName);
             this.audit("client_registered", { client: this.clientRef(id), redirects: redirects.length });
             json(res, 201, { client_id: id, redirect_uris: redirects, grant_types: ["authorization_code", "refresh_token"],
-                response_types: ["code"], token_endpoint_auth_method: "none" });
+                response_types: ["code"], token_endpoint_auth_method: "none",
+                ...(clientName === undefined ? {} : { client_name: clientName }) });
             return true;
         }
         if (route === "/oauth/authorize" && req.method === "GET") {
@@ -543,13 +644,17 @@ export class HostedOAuth {
                 const approval = await this.putObject("approval", { ...state, upstream, subject: profile.subject }, 600);
                 this.audit("consent_presented", { flow: state.flowId, client: this.clientRef(state.clientId),
                     redirectOrigin: callback.origin });
-                const destination = escapeHtml(callback.origin);
+                const clientName = await this.clientName(state.clientId);
+                const destination = escapeHtml(callback.toString());
                 const content = `<h1>Allow access?</h1><p>The application below wants to connect to your hosted ModLens account.</p>`
-                    + `<div class="app"><span class="app-icon" aria-hidden="true">&gt;_</span><span class="app-copy"><strong class="app-origin">${destination}</strong><small class="app-label">Requesting application</small></span></div>`
+                    + `<div class="app"><span class="app-icon" aria-hidden="true">&gt;_</span><span class="app-copy"><strong class="app-name">${clientName ? escapeHtml(clientName) : "Unnamed application"}</strong><small class="app-label">${clientName ? "Name supplied by application" : "No application name supplied"}</small></span></div>`
+                    + `<details class="connection-details"><summary>Connection details</summary><p>After approval, ModLens returns you to this registered callback:</p><code class="callback-url">${destination}</code></details>`
                     + `<ul class="permissions"><li>Run hosted ModLens tools on your behalf</li><li>Use your hosted account allowance</li></ul>`
                     + `<form method="post" action="/oauth/approve"><input type="hidden" name="approval" value="${escapeHtml(approval)}"><div class="actions"><button class="secondary" name="decision" value="deny">Cancel</button><button class="primary" name="decision" value="allow">Allow access</button></div></form>`
                     + `<p class="note">Only continue if you started this request in the app.</p>`;
-                res.writeHead(200, htmlHeaders);
+                // Browsers may apply form-action to the redirect after approval as well as the POST.
+                res.writeHead(200, { ...htmlHeaders,
+                    "Content-Security-Policy": htmlCsp(`'self' ${callback.origin}`) });
                 res.end(page("Connect", content));
                 return true;
             }
@@ -592,10 +697,16 @@ export class HostedOAuth {
             return true;
         }
         if (route === "/oauth/token" && req.method === "POST") {
+            const requestRef = randomBytes(6).toString("hex");
+            const responseAudit = { request: requestRef };
+            this.observeTokenResponse(req, res, responseAudit);
             const params = form(await body(req));
             const clientId = required(params, "client_id");
+            responseAudit.client = this.clientRef(clientId);
             await this.client(clientId);
             const grantType = required(params, "grant_type");
+            responseAudit.grantType = grantType;
+            this.audit("token_request_received", { request: requestRef, client: responseAudit.client, grantType });
             if (grantType === "authorization_code") {
                 const code = await this.takeObject(required(params, "code"), "code");
                 if (code.clientId !== clientId || code.callback !== required(params, "redirect_uri") ||
@@ -612,8 +723,12 @@ export class HostedOAuth {
                 const db = await this.db();
                 await db.$executeRawUnsafe(`INSERT INTO hosted_oauth_grants (id,client_id,subject,resource,upstream_access,upstream_refresh,
                     upstream_expires,refresh_hash,refresh_expires) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)`, grant.id, grant.client_id, grant.subject, grant.resource, grant.upstream_access, grant.upstream_refresh, grant.upstream_expires, grant.refresh_hash, grant.refresh_expires);
-                const response = { ...await this.issue(grant), ...(refresh ? { refresh_token: refresh } : {}) };
-                this.audit("token_issued", { flow: code.flowId, client: this.clientRef(clientId), refresh: !!refresh });
+                const access = await this.issue(grant);
+                const response = { ...access, ...(refresh ? { refresh_token: refresh } : {}) };
+                this.audit("token_issued", { request: requestRef, flow: code.flowId, client: this.clientRef(clientId), refresh: !!refresh,
+                    grant: this.grantRef(grant.id), accessExpiresIn: Number(access.expires_in),
+                    ...(refresh ? { refreshRef: sha(refresh).slice(0, 12) } : {}) });
+                Object.assign(responseAudit, this.describeTokenResponse(response));
                 json(res, 200, response);
                 return true;
             }
@@ -623,37 +738,22 @@ export class HostedOAuth {
                 if (params.has("scope") && params.get("scope") !== "modlens")
                     throw new HostedOAuthError("Unsupported scope", 400, "invalid_scope");
                 const raw = required(params, "refresh_token");
-                const db = await this.db();
-                const rows = await db.$queryRawUnsafe(`UPDATE hosted_oauth_grants SET refresh_hash=NULL
-                    WHERE refresh_hash=$1 AND client_id=$2 AND refresh_expires>$3 RETURNING *`, sha(raw), clientId, now());
-                if (rows.length !== 1 || !rows[0].upstream_refresh)
-                    throw new HostedOAuthError("Invalid refresh token", 400, "invalid_grant");
-                const grant = rows[0];
-                try {
-                    const oldUpstreamRefresh = grant.upstream_refresh;
-                    const upstream = await this.upstreamToken(new URLSearchParams({ grant_type: "refresh_token",
-                        refresh_token: this.open(oldUpstreamRefresh) }));
-                    grant.upstream_access = this.seal(upstream.access_token);
-                    grant.upstream_refresh = this.seal(upstream.refresh_token ?? this.open(oldUpstreamRefresh));
-                    grant.upstream_expires = now() + Math.max(1, Math.min(86400, Number(upstream.expires_in) || 300));
-                    await db.$executeRawUnsafe(`UPDATE hosted_oauth_grants SET upstream_access=$2,upstream_refresh=$3,
-                        upstream_expires=$4 WHERE id=$1`, grant.id, grant.upstream_access, grant.upstream_refresh, grant.upstream_expires);
-                    const profile = await this.profile(upstream.access_token);
-                    if (profile.subject !== grant.subject || !profile.allowed)
-                        throw new HostedOAuthError("Account access denied", 403, "access_denied");
-                    const next = token("mlr_");
-                    grant.refresh_hash = sha(next);
-                    await db.$executeRawUnsafe(`UPDATE hosted_oauth_grants SET refresh_hash=$2 WHERE id=$1`, grant.id, grant.refresh_hash);
-                    json(res, 200, { ...await this.issue(grant), refresh_token: next });
-                }
-                catch (error) {
-                    if (error instanceof HostedOAuthError && error.status === 503) {
-                        await db.$executeRawUnsafe(`UPDATE hosted_oauth_grants SET refresh_hash=$2 WHERE id=$1 AND refresh_hash IS NULL`, grant.id, sha(raw));
-                    }
-                    else
-                        await this.revoke(grant.id);
-                    throw error;
+                responseAudit.presentedRefreshRef = sha(raw).slice(0, 12);
+                const key = `${clientId}:${sha(raw)}`;
+                let pending = this.refreshes.get(key);
+                if (!pending) {
+                    this.audit("refresh_started", { request: requestRef, client: this.clientRef(clientId),
+                        refreshRef: responseAudit.presentedRefreshRef });
+                    pending = this.refresh(clientId, raw, requestRef);
+                    this.refreshes.set(key, pending);
+                    void pending.finally(() => this.refreshes.delete(key)).catch(() => { });
                 }
+                else
+                    this.audit("refresh_joined", { request: requestRef, client: this.clientRef(clientId),
+                        refreshRef: responseAudit.presentedRefreshRef });
+                const response = await pending;
+                Object.assign(responseAudit, this.describeTokenResponse(response));
+                json(res, 200, response);
                 return true;
             }
             throw new HostedOAuthError("Unsupported grant type", 400, "unsupported_grant_type");
@@ -666,12 +766,12 @@ export class HostedOAuth {
             const db = await this.db();
             const rows = await db.$queryRawUnsafe(`SELECT id FROM hosted_oauth_grants WHERE client_id=$1 AND refresh_hash=$2`, clientId, sha(raw));
             if (rows.length)
-                await this.revoke(rows[0].id);
+                await this.revoke(rows[0].id, "client_request");
             else {
                 const access = await db.$queryRawUnsafe(`SELECT g.id FROM hosted_oauth_access a JOIN hosted_oauth_grants g ON g.id=a.grant_id
                      WHERE g.client_id=$1 AND a.token_hash=$2`, clientId, sha(raw));
                 if (access.length)
-                    await this.revoke(access[0].id);
+                    await this.revoke(access[0].id, "client_request");
             }
             json(res, 200, {});
             return true;