@gramatr/client 0.6.2 → 0.6.5

package/CLAUDE.md

@@ -10,7 +10,7 @@ ISC scaffold, capability audit, phase templates, and composed agents.
 **Memory:** Use gramatr MCP tools (`search_semantic`, `create_entity`, `add_observation`),
 not local markdown files.
 
-**Identity:** Read from `~/gmtr-client/settings.json` — `daidentity` for your name,
+**Identity:** Read from `~/.gramatr/settings.json` — `daidentity` for your name,
 `principal` for the user's name.
 
 **If the server is unreachable:** Use 7-phase structure (OBSERVE → THINK → PLAN → BUILD →

package/README.md

@@ -72,14 +72,14 @@ The client never stores intelligence locally. The server delivers everything: be
 ## What gets installed
 
 ```
-~/gmtr-client/          # Client runtime
+~/.gramatr/          # Client runtime
   hooks/                # 8 lifecycle hooks
   core/                 # Shared routing + session logic
   bin/                  # Status line, login, utilities
   CLAUDE.md             # Minimal behavioral framework
 ~/.claude/settings.json # Hook configuration (merged, not overwritten)
 ~/.claude.json          # MCP server registration
-~/.gmtr.json            # Auth token (canonical source)
+~/.gramatr.json            # Auth token (canonical source)
 ```
 
 ## Commands

package/bin/clear-creds.ts

@@ -40,7 +40,7 @@ function showHelp(): void {
   log(`gramatr clear-creds — Remove every stored gramatr credential
 
 Usage:
-  gramatr clear-creds   Sweep ~/.gramatr.json + auth.api_key from gmtr-client/settings.json
+  gramatr clear-creds   Sweep ~/.gramatr.json + auth.api_key from ~/.gramatr/settings.json
 
 After running, the next install or login will be forced through OAuth.
 

package/bin/gmtr-login.ts

@@ -15,10 +15,11 @@
  * The GMTRPromptEnricher hook reads this on every prompt.
  */
 
-import { randomBytes } from 'crypto';
+import { createHash, randomBytes } from 'crypto';
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { createServer, type IncomingMessage, type ServerResponse } from 'http';
+import type { AddressInfo } from 'net';
 
 // ── Config ──
 
@@ -41,7 +42,9 @@ const DASHBOARD_BASE = process.env.GMTR_DASHBOARD_URL || (() => {
     return 'https://app.gramatr.com';
   }
 })();
-const CALLBACK_PORT = 58787; // Must match server's redirect_uris
+// CALLBACK_PORT is now dynamically allocated per login (random localhost port).
+// The server's DCR endpoint accepts arbitrary localhost redirect_uris for
+// public CLIs (token_endpoint_auth_method=none). See loginBrowser() below.
 
 // ── HTML Templates ──
 
@@ -140,7 +143,11 @@ function errorPage(title: string, detail: string): string {
 
 // ── Headless Detection ──
 
-function isHeadless(): boolean {
+function isHeadless(forceFlag: boolean = false): boolean {
+  // Explicit override — user passed --headless, OR env GRAMATR_LOGIN_HEADLESS=1
+  if (forceFlag) return true;
+  if (process.env.GRAMATR_LOGIN_HEADLESS === '1') return true;
+
   // SSH session without display forwarding
   if (process.env.SSH_CONNECTION || process.env.SSH_TTY) {
     if (!process.env.DISPLAY && process.platform !== 'darwin') return true;
@@ -339,7 +346,7 @@ async function loginWithToken(token: string): Promise<void> {
   }
 }
 
-async function loginBrowser(): Promise<void> {
+async function loginBrowser(opts: { forceHeadless?: boolean } = {}): Promise<void> {
   console.log('\n  gramatr login\n');
   console.log(`  Server: ${SERVER_BASE}`);
   console.log(`  Dashboard: ${DASHBOARD_BASE}`);
@@ -355,8 +362,11 @@ async function loginBrowser(): Promise<void> {
 
   console.log('');
 
-  // Headless environments use device auth (no local server needed)
-  if (isHeadless()) {
+  // Headless environments use device auth (no local server needed).
+  // --headless flag or GRAMATR_LOGIN_HEADLESS=1 forces this path even on
+  // desktop — escape hatch when the browser flow is broken or the user
+  // prefers the device flow's out-of-band UX.
+  if (isHeadless(opts.forceHeadless)) {
     console.log('  Headless environment detected. Starting device login...\n');
     try {
       const device = await startDeviceAuthorization();
@@ -406,75 +416,115 @@ async function loginBrowser(): Promise<void> {
     }
   }
 
-  // Browser environments use local callback server
-  const state = randomBytes(16).toString('base64url');
-  const callbackUrl = `http://localhost:${CALLBACK_PORT}/callback`;
+  // ── Browser environments use OAuth 2.0 authorization-code grant + PKCE ──
+  //
+  // v0.6.5: This now mirrors the headless device flow's auth model — both
+  // paths produce an opaque `mcp-access-token-<uuid>` token (1-year TTL,
+  // Redis-backed) instead of the short-lived raw Firebase ID token the old
+  // dashboard-redirect flow stored. Per RFC 7591 (Dynamic Client Registration)
+  // we register the CLI as an OAuth client on first run, then per RFC 7636
+  // (PKCE) we exchange a code for the opaque token.
+  //
+  // Bug history: pre-v0.6.5 the browser flow stored a raw Firebase ID token
+  // (token_type: 'firebase'), which had a 1-hour TTL. After 1 hour every
+  // MCP call returned "JWT signature validation failed" because the token
+  // genuinely expired. See #519 + #524 + this PR.
+
+  // 1. Bind a localhost callback server (random port — server's DCR allows it)
+  const callbackServer = createServer();
+  await new Promise<void>((resolve, reject) => {
+    callbackServer.once('error', reject);
+    callbackServer.listen(0, '127.0.0.1', () => resolve());
+  });
+  const port = (callbackServer.address() as AddressInfo).port;
+  const redirectUri = `http://localhost:${port}/callback`;
+
+  // 2. Dynamic client registration (RFC 7591). We always re-register because
+  //    the redirect_uri changes every run (random localhost port). Server
+  //    allows DCR with token_endpoint_auth_method=none for public CLIs.
+  const config = readConfig();
+  let clientId: string;
+  try {
+    const regRes = await fetch(`${SERVER_BASE}/register`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        client_name: 'gmtr-login',
+        redirect_uris: [redirectUri],
+        grant_types: ['authorization_code'],
+        response_types: ['code'],
+        token_endpoint_auth_method: 'none',
+      }),
+      signal: AbortSignal.timeout(10000),
+    });
+    const reg = await regRes.json().catch(() => ({}));
+    if (!regRes.ok || !reg.client_id) {
+      throw new Error(reg.error_description || reg.error || `HTTP ${regRes.status}`);
+    }
+    clientId = reg.client_id as string;
+    config.oauth_client_id = clientId;
+    writeConfig(config);
+  } catch (e: any) {
+    callbackServer.close();
+    console.log(`  ✗ Dynamic client registration failed: ${e.message}\n`);
+    process.exit(1);
+  }
 
-  const tokenPromise = new Promise<string>((resolve, reject) => {
-    const server = createServer(async (req: IncomingMessage, res: ServerResponse) => {
-      const url = new URL(req.url || '/', `http://localhost:${CALLBACK_PORT}`);
+  // 3. PKCE: generate verifier + S256 challenge
+  const codeVerifier = randomBytes(32).toString('base64url');
+  const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url');
+  const state = randomBytes(16).toString('base64url');
 
+  // 4. Run the callback server, waiting for /callback?code=...&state=...
+  //
+  // v0.6.5: capture the timeout handle and clearTimeout() in finally — same
+  // orphan-timer bug that v0.3.63 fixed for the device flow. Without the
+  // clear, Promise.race against a setTimeout keeps the Node event loop
+  // alive past success and the process hangs until Ctrl+C.
+  let codeTimeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  const codePromise = new Promise<string>((resolve, reject) => {
+    callbackServer.on('request', (req: IncomingMessage, res: ServerResponse) => {
+      const url = new URL(req.url || '/', redirectUri);
       if (url.pathname !== '/callback') {
         res.writeHead(404);
         res.end('Not found');
         return;
       }
-
-      const token = url.searchParams.get('token');
+      const code = url.searchParams.get('code');
       const returnedState = url.searchParams.get('state');
       const error = url.searchParams.get('error');
-
       if (error) {
         res.writeHead(200, { 'Content-Type': 'text/html' });
         res.end(errorPage('Authentication Failed', error));
-        server.close();
+        callbackServer.close();
         reject(new Error(`OAuth error: ${error}`));
         return;
       }
-
-      if (!token || returnedState !== state) {
+      if (!code || returnedState !== state) {
         res.writeHead(400, { 'Content-Type': 'text/html' });
-        res.end(errorPage('Invalid Callback', 'Missing Firebase token or state mismatch. Please try again.'));
-        server.close();
+        res.end(errorPage('Invalid Callback', 'Missing code or state mismatch. Please try again.'));
+        callbackServer.close();
         reject(new Error('Invalid callback'));
         return;
       }
-
-      try {
-        const validation = await testToken(token);
-        if (!validation.valid) {
-          res.writeHead(200, { 'Content-Type': 'text/html' });
-          res.end(errorPage('Token Validation Failed', validation.error || 'Server rejected token'));
-          server.close();
-          reject(new Error(validation.error || 'Server rejected token'));
-          return;
-        }
-
-        res.writeHead(200, { 'Content-Type': 'text/html' });
-        res.end(successPage());
-        server.close();
-        resolve(token);
-      } catch (e: any) {
-        res.writeHead(500, { 'Content-Type': 'text/html' });
-        res.end(errorPage('Unexpected Error', e.message));
-        server.close();
-        reject(e);
-      }
-    });
-
-    server.listen(CALLBACK_PORT, () => {
-      // Server ready
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(successPage());
+      callbackServer.close();
+      resolve(code);
     });
-
-    // Timeout after 2 minutes
-    setTimeout(() => {
-      server.close();
-      reject(new Error('Login timed out after 2 minutes'));
-    }, 120000);
+    codeTimeoutHandle = setTimeout(() => {
+      callbackServer.close();
+      reject(new Error('Login timed out after 5 minutes'));
+    }, 5 * 60 * 1000);
   });
 
-  const authorizeUrl = new URL('/login', `${DASHBOARD_BASE}/`);
-  authorizeUrl.searchParams.set('callback', callbackUrl);
+  // 5. Open the browser to the server's /authorize endpoint with PKCE params
+  const authorizeUrl = new URL('/authorize', SERVER_BASE);
+  authorizeUrl.searchParams.set('response_type', 'code');
+  authorizeUrl.searchParams.set('client_id', clientId);
+  authorizeUrl.searchParams.set('redirect_uri', redirectUri);
+  authorizeUrl.searchParams.set('code_challenge', codeChallenge);
+  authorizeUrl.searchParams.set('code_challenge_method', 'S256');
   authorizeUrl.searchParams.set('state', state);
 
   console.log('  Opening browser for authentication...');
@@ -482,33 +532,64 @@ async function loginBrowser(): Promise<void> {
   console.log(`  ${authorizeUrl.toString()}`);
   console.log('');
 
-  // Open browser
   const { exec } = await import('child_process');
   const openCmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
   exec(`${openCmd} "${authorizeUrl.toString()}"`);
 
   console.log('  Waiting for authorization...');
 
+  let authCode: string;
   try {
-    const accessToken = await tokenPromise;
-
-    // Save token
-    const config = readConfig();
-    config.token = accessToken;
-    config.token_type = 'firebase';
-    config.authenticated_at = new Date().toISOString();
-    config.server_url = SERVER_BASE;
-    config.dashboard_url = DASHBOARD_BASE;
-    writeConfig(config);
-
-    console.log('');
-    console.log('  ✓ Authenticated successfully');
-    console.log('  Token saved to ~/.gramatr.json');
-    console.log('  gramatr intelligence is now active.\n');
+    authCode = await codePromise;
   } catch (e: any) {
+    if (codeTimeoutHandle) clearTimeout(codeTimeoutHandle);
     console.log(`\n  ✗ Authentication failed: ${e.message}\n`);
     process.exit(1);
   }
+  if (codeTimeoutHandle) clearTimeout(codeTimeoutHandle);
+
+  // 6. Exchange the code for an opaque MCP access token at /token
+  let accessToken: string;
+  let expiresIn: number = 31536000; // server default = 1 year
+  try {
+    const tokenRes = await fetch(`${SERVER_BASE}/token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        grant_type: 'authorization_code',
+        code: authCode,
+        code_verifier: codeVerifier,
+        client_id: clientId,
+        redirect_uri: redirectUri,
+      }),
+      signal: AbortSignal.timeout(10000),
+    });
+    const payload = await tokenRes.json().catch(() => ({}));
+    if (!tokenRes.ok || !payload.access_token) {
+      throw new Error(payload.error_description || payload.error || `HTTP ${tokenRes.status}`);
+    }
+    accessToken = payload.access_token as string;
+    if (typeof payload.expires_in === 'number') expiresIn = payload.expires_in;
+  } catch (e: any) {
+    console.log(`\n  ✗ Token exchange failed: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  // 7. Save the opaque token — same shape as the device flow
+  const updated = readConfig();
+  updated.token = accessToken;
+  updated.token_type = 'oauth';
+  updated.authenticated_at = new Date().toISOString();
+  updated.server_url = SERVER_BASE;
+  updated.dashboard_url = DASHBOARD_BASE;
+  updated.token_expires_at = new Date(Date.now() + expiresIn * 1000).toISOString();
+  if (clientId) updated.oauth_client_id = clientId;
+  writeConfig(updated);
+
+  console.log('');
+  console.log('  ✓ Authenticated successfully');
+  console.log('  Token saved to ~/.gramatr.json');
+  console.log('  gramatr intelligence is now active.\n');
 }
 
 // ── CLI ──
@@ -563,13 +644,19 @@ export async function main(): Promise<void> {
   gmtr-login — Authenticate with the gramatr server
 
   Usage:
-    gmtr-login              Interactive dashboard login (browser or headless device flow)
+    gmtr-login              Interactive login (browser PKCE when display available,
+                            device flow otherwise — auto-detected)
+    gmtr-login --headless   Force the device flow even on desktops (escape hatch
+                            when the browser flow is broken or unavailable)
     gmtr-login --token      Paste a token (API key or Firebase token)
     gmtr-login --token <t>  Provide token directly
     gmtr-login --status     Check authentication status
     gmtr-login --logout     Remove stored credentials
     gmtr-login --help       Show this help
 
+  Environment:
+    GRAMATR_LOGIN_HEADLESS=1  Same as --headless (forces device flow)
+
   Token storage: ~/.gramatr.json
   Server: ${SERVER_BASE}
   Dashboard: ${DASHBOARD_BASE}
@@ -577,8 +664,10 @@ export async function main(): Promise<void> {
     return;
   }
 
-  // Default: browser login flow
-  await loginBrowser();
+  // Default: browser login flow (falls back to device flow if headless
+  // detected, OR if --headless / GRAMATR_LOGIN_HEADLESS=1 is set).
+  const forceHeadless = args.includes('--headless');
+  await loginBrowser({ forceHeadless });
 }
 
 // Module-run guard. Works both when invoked directly via

package/bin/uninstall.ts

@@ -170,7 +170,7 @@ async function main(): Promise<void> {
       try {
         const settings = JSON.parse(readFileSync(claudeSettings, 'utf8'));
         if (settings.hooks) {
-          // Remove hook entries that reference gmtr-client
+          // Remove hook entries that reference .gramatr or gramatr paths
           for (const [event, hooks] of Object.entries(settings.hooks)) {
             if (Array.isArray(hooks)) {
               settings.hooks[event] = (hooks as any[]).filter(

package/chatgpt/README.md

@@ -19,7 +19,7 @@ bun chatgpt/install.ts
 ```
 
 The installer will:
-1. Find your API key from `~/.gmtr.json`, `GRAMATR_API_KEY` env, or prompt you
+1. Find your API key from `~/.gramatr.json`, `GRAMATR_API_KEY` env, or prompt you
 2. Validate connectivity to the gramatr server
 3. Detect your platform and locate the ChatGPT config file
 4. Merge the gramatr MCP server entry without overwriting existing servers

package/codex/README.md

@@ -21,8 +21,8 @@ Install locally with:
 - `pnpm --filter @gramatr/client install-codex`
 
 The installer:
-- syncs this Codex runtime into `~/gmtr-client/codex`
-- syncs the shared `gmtr-hook-utils.ts` dependency into `~/gmtr-client/hooks/lib`
+- syncs this Codex runtime into `~/.gramatr/codex`
+- syncs the shared `gmtr-hook-utils.ts` dependency into `~/.gramatr/hooks/lib`
 - merges `~/.codex/hooks.json`
 - enables `codex_hooks` in `~/.codex/config.toml`
 - upserts a managed gramatr block in `~/.codex/AGENTS.md`

package/core/version-check.ts

@@ -2,7 +2,7 @@
  * version-check.ts — opportunistic npm registry version check.
  *
  * Queries https://registry.npmjs.org/gramatr/latest on a 3s timeout, caches
- * the result for one hour under ~/.gmtr-client/.cache/version-check.json, and
+ * the result for one hour under ~/.gramatr/.cache/version-check.json, and
  * reports whether the installed client is behind the published version.
  *
  * Design constraints (see issue #468 sibling work):
@@ -56,7 +56,7 @@ export function compareVersions(a: string, b: string): number {
 }
 
 export function getCachePath(home: string = homedir()): string {
-  return join(home, '.gmtr-client', '.cache', 'version-check.json');
+  return join(home, '.gramatr', '.cache', 'version-check.json');
 }
 
 function readCache(path: string): CacheFile | null {

package/desktop/README.md

@@ -12,7 +12,7 @@ bun packages/client/desktop/install.ts
 ```
 
 The installer:
-1. Resolves your API key from `~/.gmtr.json`, `GRAMATR_API_KEY` env, or prompts
+1. Resolves your API key from `~/.gramatr.json`, `GRAMATR_API_KEY` env, or prompts
 2. Validates connectivity to the gramatr server
 3. Detects platform (macOS or Windows)
 4. Reads existing `claude_desktop_config.json` without overwriting other MCP servers

package/gemini/README.md

@@ -62,7 +62,7 @@ echo "GRAMATR_API_KEY=your-key-here" > ~/.gemini/extensions/gramatr/.env
 
 gramatr requires a Bearer token for all MCP calls. The installer handles this by:
 
-1. Checking `~/.gmtr.json` for an existing token (shared with Claude Code / Codex)
+1. Checking `~/.gramatr.json` for an existing token (shared with Claude Code / Codex)
 2. Checking the `GRAMATR_API_KEY` environment variable
 3. Prompting for a token interactively
 
@@ -72,7 +72,7 @@ To authenticate before installing, run:
 bun packages/client/bin/gmtr-login.ts
 ```
 
-This stores the token in `~/.gmtr.json`, which the installer reads automatically.
+This stores the token in `~/.gramatr.json`, which the installer reads automatically.
 
 API keys start with `gramatr_sk_` and can be created at [gramatr.com](https://gramatr.com) or via the `gramatr_create_api_key` MCP tool.
 
@@ -92,4 +92,4 @@ After installing and restarting Gemini CLI:
 > @gramatr search for recent learning signals
 ```
 
-If the MCP server responds, the extension is working. If you see auth errors, re-run the installer or check `~/.gmtr.json`.
+If the MCP server responds, the extension is working. If you see auth errors, re-run the installer or check `~/.gramatr.json`.

package/hooks/session-start.hook.ts

@@ -321,7 +321,7 @@ async function main(): Promise<void> {
         log('This will:');
         log(`  1. Search gramatr for existing project: ${git.projectName}`);
         log('  2. Create project entity if not found');
-        log('  3. Link entity to .gmtr.json');
+        log('  3. Link entity to .gramatr.json');
         log('  4. Enable full memory persistence');
         log('');
       } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gramatr/client",
-  "version": "0.6.2",
+  "version": "0.6.5",
   "publishConfig": {
     "access": "public"
   },