gigarag-cursor 0.1.1 → 0.2.1

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gigarag",
   "description": "Your GigaRAG knowledge base inside Cursor: index a codebase, save decisions, recall them later.",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "author": { "name": "GigaRAG", "url": "https://gigarag.com" },
   "homepage": "https://gigarag.com/connect/cursor",
   "license": "UNLICENSED",

package/cli/auth/account.js

@@ -0,0 +1,106 @@
+import { updateConfig } from '../config.js';
+import { DEFAULT_MCP_URL } from '../constants.js';
+import { assertSecureUrl } from '../secureUrl.js';
+import { ACCOUNT_SLOT, configuredIssuer, loadAccountCredential, refreshOAuth, workspaceSlot, writeSlot, currentGeneration, } from './credentials.js';
+/**
+ * The account sign-in: list every workspace the person can reach, and trade
+ * the account token for one workspace's token.
+ *
+ * The account token opens no workspace by itself. The app refuses it at /mcp
+ * and says so, so everything that talks to a workspace goes through
+ * `exchangeForWorkspace` first. See section 9 of the app's sharing levels spec.
+ */
+export const TOKEN_EXCHANGE = 'urn:ietf:params:oauth:grant-type:token-exchange';
+const ACCESS_TOKEN_TYPE = 'urn:ietf:params:oauth:token-type:access_token';
+const REFRESH_MARGIN_MS = 60_000;
+export class AccountError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AccountError';
+    }
+}
+const NOT_SIGNED_IN = 'This computer has no GigaRAG account sign-in. Run: gigarag login';
+/** The account credential, refreshed when it is about to lapse. */
+async function accountCredential(fetchImpl, now, force = false) {
+    const credential = loadAccountCredential();
+    if (!credential)
+        throw new AccountError(NOT_SIGNED_IN);
+    const due = credential.expiresAt !== undefined && credential.expiresAt - now() < REFRESH_MARGIN_MS;
+    if ((force || due) && credential.refreshToken) {
+        try {
+            return await refreshOAuth(credential, fetchImpl, now, ACCOUNT_SLOT);
+        }
+        catch (err) {
+            throw new AccountError(err.message);
+        }
+    }
+    return credential;
+}
+export async function listAccountWorkspaces(opts = {}) {
+    const fetchImpl = opts.fetch ?? fetch;
+    const now = opts.now ?? Date.now;
+    const issuer = (opts.issuer ?? configuredIssuer()).replace(/\/$/, '');
+    const url = assertSecureUrl(`${issuer}/api/cli/workspaces`, 'The GigaRAG app');
+    const call = async (credential) => fetchImpl(url, {
+        headers: { authorization: `Bearer ${credential.accessToken}`, accept: 'application/json' },
+        signal: AbortSignal.timeout(30_000),
+    });
+    let res = await call(await accountCredential(fetchImpl, now));
+    if (res.status === 401)
+        res = await call(await accountCredential(fetchImpl, now, true));
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || !Array.isArray(body.workspaces)) {
+        throw new AccountError(body.error ?? `Could not list your workspaces (HTTP ${res.status}). Run: gigarag login`);
+    }
+    updateConfig(c => {
+        c.workspaceNames = Object.fromEntries(body.workspaces.map(w => [w.id, w.name]));
+    });
+    return body.workspaces;
+}
+export async function exchangeForWorkspace(workspaceId, opts = {}) {
+    const fetchImpl = opts.fetch ?? fetch;
+    const now = opts.now ?? Date.now;
+    // Read before the account credential: a browser sign-in that lands while this exchange is in
+    // flight moves the generation on, and the old account's token must not be stored under the new one.
+    const generation = currentGeneration();
+    const account = await accountCredential(fetchImpl, now);
+    assertSecureUrl(account.tokenEndpoint, 'The token endpoint');
+    const res = await fetchImpl(account.tokenEndpoint, {
+        method: 'POST',
+        signal: AbortSignal.timeout(30_000),
+        headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+        body: new URLSearchParams({
+            grant_type: TOKEN_EXCHANGE,
+            subject_token: account.accessToken,
+            subject_token_type: ACCESS_TOKEN_TYPE,
+            resource: opts.mcpUrl ?? DEFAULT_MCP_URL,
+            workspace_id: workspaceId,
+            client_id: account.clientId,
+        }),
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || typeof body['access_token'] !== 'string') {
+        const said = typeof body['error_description'] === 'string' ? body['error_description'] : undefined;
+        throw new AccountError(said ??
+            `Could not connect to workspace ${workspaceId} (HTTP ${res.status}). Retrying may help if GigaRAG was down; ` +
+                'otherwise run: gigarag workspaces, to check your account can still reach it, or gigarag login to sign in again.');
+    }
+    const fresh = {
+        type: 'oauth',
+        accessToken: body['access_token'],
+        refreshToken: typeof body['refresh_token'] === 'string' ? body['refresh_token'] : undefined,
+        expiresAt: typeof body['expires_in'] === 'number' ? now() + body['expires_in'] * 1000 : undefined,
+        clientId: account.clientId,
+        tokenEndpoint: account.tokenEndpoint,
+    };
+    // Hand back the stamped copy, not `fresh`: a bridge keeps this credential in memory, and one
+    // without a stamp would pass as current after a later sign-in and be written back on refresh.
+    const slot = workspaceSlot(workspaceId);
+    const credential = { ...fresh, gen: generation };
+    // Stored only if no sign-in happened meanwhile. Otherwise this call still gets a working token,
+    // stamped with the old generation, so nothing refreshes it back into the slot later.
+    if (currentGeneration() === generation)
+        writeSlot(slot, credential);
+    const ws = (body['workspace'] ?? {});
+    return { credential, workspace: { id: ws.id ?? workspaceId, name: ws.name ?? workspaceId, role: ws.role ?? '' } };
+}

package/cli/auth/credentials.js

@@ -1,8 +1,7 @@
-import { readConfig } from '../config.js';
+import { readConfig, updateConfig } from '../config.js';
 import { assertSecureUrl } from '../secureUrl.js';
 import { DEFAULT_ISSUER } from '../constants.js';
 import { deleteSecret, getSecret, setSecret } from '../secrets.js';
-const ACCOUNT = 'default';
 /**
  * The shape agent keys take, `gr_live_<region>_<32 base62>_<6 hex>`. Checked
  * loosely: a format that changes must not lock people out.
@@ -19,16 +18,50 @@ export function envKey(env = process.env) {
     const value = env['GIGARAG_API_KEY']?.trim();
     return value && !value.startsWith('${') ? value : undefined;
 }
-/** `GIGARAG_API_KEY` wins, so CI and containers need no login step. */
-export function loadCredential(env = process.env) {
-    const fromEnv = envKey(env);
-    if (fromEnv)
-        return { type: 'key', key: fromEnv };
-    const stored = getSecret(ACCOUNT);
+/**
+ * Where each credential lives in the keychain.
+ *
+ * `account` holds the GigaRAG CLI's account sign-in, which lists workspaces and
+ * is exchanged for one token per workspace. Each workspace's token pair, or a
+ * pasted agent key for it, lives in its own slot. `default` is the single slot
+ * every version before this used, read so a machine signed in before still
+ * works until it signs in again.
+ *
+ * The slot is `workspace-<id>`: the file store names its file after the slot,
+ * and Windows refuses a colon in a filename.
+ */
+export const ACCOUNT_SLOT = 'account';
+export const LEGACY_SLOT = 'default';
+export const workspaceSlot = (id) => `workspace-${id}`;
+const isWorkspaceSlot = (slot) => slot.startsWith('workspace-');
+/** The sign-in generation this machine is on, bumped by `clearWorkspaceSlots`. */
+export function currentGeneration() {
+    return readConfig().authGeneration ?? 0;
+}
+/**
+ * True for a workspace slot stamped with a generation that isn't the current one: a credential a
+ * previous account's sign-in wrote or refreshed, left behind after a fresh browser sign-in cleared
+ * the slot it came from. Only workspace slots carry this check; the account and legacy slots are
+ * rewritten in full on every sign-in and are never subject to `clearWorkspaceSlots`.
+ */
+function isStale(slot, credential) {
+    // An unstamped credential counts as generation 0: slots written before stamping existed stay
+    // readable until the first new sign-in, which deletes them anyway, and a bridge holding one in
+    // memory cannot write it back after that sign-in.
+    return isWorkspaceSlot(slot) && (credential.gen ?? 0) !== currentGeneration();
+}
+/** The credential as `writeSlot` stores it: stamped with this sign-in generation for a workspace slot. */
+export function stampForSlot(slot, credential) {
+    return isWorkspaceSlot(slot) ? { ...credential, gen: currentGeneration() } : credential;
+}
+export function readSlot(slot) {
+    const stored = getSecret(slot);
     if (!stored)
         return undefined;
     try {
         const parsed = JSON.parse(stored.value);
+        if (isStale(slot, parsed))
+            return undefined;
         if (parsed.type === 'key' && parsed.key)
             return parsed;
         if (parsed.type === 'oauth' && parsed.accessToken)
@@ -39,17 +72,86 @@ export function loadCredential(env = process.env) {
     }
     return undefined;
 }
-/** Stores a credential and returns where it went, for the "connected" line. */
-export function saveCredential(credential) {
-    return setSecret(ACCOUNT, JSON.stringify(credential));
+/** Stores a credential in a slot and returns where it went, for the "connected" line. */
+export function writeSlot(slot, credential) {
+    const stamped = stampForSlot(slot, credential);
+    const where = setSecret(slot, JSON.stringify(stamped));
+    updateConfig(c => {
+        const slots = new Set(c.credentialSlots ?? []);
+        slots.add(slot);
+        c.credentialSlots = [...slots];
+    });
+    return where;
+}
+export function clearSlot(slot) {
+    deleteSecret(slot);
+}
+/**
+ * Deletes every `workspace-<id>` slot, and the machine default and cached
+ * workspace names that go with them, without touching the account slot or the
+ * legacy one.
+ *
+ * Called before a fresh browser sign-in is stored. Without it, a workspace
+ * token minted for a previous account keeps working after a different person
+ * signs in on the same machine, because each slot is keyed by workspace id and
+ * a new account's own workspace could reuse an id the old one also happened to
+ * reach, or the stale slot is simply presented for a workspace the new account
+ * was never granted, either of which sends the new person's work to a
+ * workspace their sign-in never chose.
+ *
+ * Deleting the slots isn't enough by itself: a bridge process started before this
+ * runs can still hold one of them in memory, and its normal refresh-on-expiry
+ * logic would write the rotated pair straight back afterwards. So this also bumps
+ * `authGeneration`, and `refreshOAuth` refuses to write a workspace slot back
+ * under a generation that has moved on (see `isStale` above).
+ */
+export function clearWorkspaceSlots() {
+    const config = readConfig();
+    const kept = [];
+    for (const slot of config.credentialSlots ?? []) {
+        if (isWorkspaceSlot(slot))
+            deleteSecret(slot);
+        else
+            kept.push(slot);
+    }
+    updateConfig(c => {
+        c.credentialSlots = kept;
+        c.workspaceId = undefined;
+        c.workspaceNames = undefined;
+        c.authGeneration = (c.authGeneration ?? 0) + 1;
+    });
+}
+export function loadAccountCredential() {
+    const credential = readSlot(ACCOUNT_SLOT);
+    return credential?.type === 'oauth' ? credential : undefined;
+}
+/**
+ * `GIGARAG_API_KEY` wins, so CI and containers need no login step. Then the
+ * workspace's own slot when a workspace is named, and the legacy slot only when
+ * none is: answering a workspace with another workspace's credential would send
+ * a person's memos to the wrong place without a word.
+ */
+export function loadCredential(env = process.env, workspaceId) {
+    const fromEnv = envKey(env);
+    if (fromEnv)
+        return { type: 'key', key: fromEnv };
+    return readSlot(workspaceId ? workspaceSlot(workspaceId) : LEGACY_SLOT);
+}
+/** Stores a credential and returns where it went. The legacy slot unless told otherwise. */
+export function saveCredential(credential, slot = LEGACY_SLOT) {
+    return writeSlot(slot, credential);
 }
+/** Deletes every credential this machine holds: the account, each workspace, and the legacy slot. */
 export function clearCredential() {
-    deleteSecret(ACCOUNT);
+    const slots = new Set([...(readConfig().credentialSlots ?? []), ACCOUNT_SLOT, LEGACY_SLOT]);
+    for (const slot of slots)
+        deleteSecret(slot);
+    updateConfig(c => void (c.credentialSlots = []));
 }
-export function credentialSource(env = process.env) {
+export function credentialSource(env = process.env, slot = LEGACY_SLOT) {
     if (envKey(env))
         return 'the GIGARAG_API_KEY environment variable';
-    return getSecret(ACCOUNT)?.store;
+    return getSecret(slot)?.store;
 }
 /** `gr_live_eu_*****`, for printing. */
 export function mask(key) {
@@ -72,7 +174,7 @@ export async function authorizationHeader(credential, fetchImpl = fetch, now = D
     }
     return `Bearer ${credential.accessToken}`;
 }
-export async function refreshOAuth(credential, fetchImpl = fetch, now = Date.now) {
+export async function refreshOAuth(credential, fetchImpl = fetch, now = Date.now, slot = LEGACY_SLOT) {
     if (!credential.refreshToken)
         throw new Error('The sign-in has expired. Run: gigarag login');
     assertSecureUrl(credential.tokenEndpoint, 'The token endpoint');
@@ -98,7 +200,14 @@ export async function refreshOAuth(credential, fetchImpl = fetch, now = Date.now
         refreshToken: typeof body['refresh_token'] === 'string' ? body['refresh_token'] : credential.refreshToken,
         expiresAt: typeof body['expires_in'] === 'number' ? now() + body['expires_in'] * 1000 : undefined,
     };
-    saveCredential(next);
+    // `credential` was loaded (or held in memory by a long-running bridge) under an older sign-in
+    // generation than this machine is now on: a fresh browser sign-in cleared this workspace slot
+    // and moved the generation forward since. Writing the refreshed pair back would resurrect the
+    // previous account's access for every later process that reads the slot, so it is dropped
+    // instead. The caller here still gets a working pair for this one call.
+    if (isStale(slot, credential))
+        return next;
+    saveCredential(next, slot);
     return next;
 }
 export function configuredIssuer() {

package/cli/binding.js

@@ -0,0 +1,117 @@
+import { existsSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readConfig, updateConfig } from './config.js';
+import { findRepoRoot } from './scan/repo.js';
+/**
+ * Which GigaRAG workspace a repository belongs to.
+ *
+ * `.gigarag.json` at the repository root names a workspace, and optionally the
+ * bucket the repository is indexed into. It holds no secret, so it can be
+ * committed, and a teammate's checkout then reaches the same workspace with
+ * their own sign-in. `gigarag use` writes it.
+ */
+export const BINDING_FILE = '.gigarag.json';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** The binding above `start`, or undefined when there is none or it does not validate. */
+export function readBinding(start) {
+    const { root } = findRepoRoot(start);
+    const path = join(root, BINDING_FILE);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const text = readFileSync(path, 'utf8');
+        const raw = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+        if (typeof raw.workspace !== 'string' || !UUID.test(raw.workspace))
+            return undefined;
+        const binding = { workspace: raw.workspace.toLowerCase() };
+        if (typeof raw.workspaceName === 'string')
+            binding.workspaceName = raw.workspaceName.slice(0, 200);
+        if (typeof raw.bucket === 'string' && SLUG.test(raw.bucket))
+            binding.bucket = raw.bucket;
+        return { binding, root };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Writes the binding at `root`, atomically, and returns its path. */
+export function writeBinding(root, binding) {
+    const path = join(root, BINDING_FILE);
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(binding, null, 2)}\n`);
+    renameSync(tmp, path);
+    return path;
+}
+/**
+ * The repository root, canonicalised the way trust is keyed: symlinks and
+ * junctions resolved, and lowercased on Windows, where the same folder can be
+ * reached under more than one case. Trust must not be foolable by either.
+ */
+function trustKey(root) {
+    const real = realpathSync(root);
+    return process.platform === 'win32' ? real.toLowerCase() : real;
+}
+/**
+ * Whether `root`'s binding to `workspace` has been trusted: recorded when the
+ * person ran `gigarag use` or `gigarag trust` for this exact pair. Trust-on-
+ * first-use, the way `direnv` treats a new `.envrc`, because `.gigarag.json` is
+ * committed and read before anyone has reviewed it, and it otherwise silently
+ * redirects a clone to whatever workspace the file names, including one an
+ * attacker invited the victim into.
+ */
+export function isTrusted(root, workspace) {
+    return readConfig().trustedBindings?.[trustKey(root)] === workspace;
+}
+/**
+ * The binding at `root`, but only once it has been trusted; an untrusted one reads exactly like
+ * no binding at all. `repoInfo` (`scan/repo.ts`) and `syncSlug` (`sync/slug.ts`) both resolve a
+ * bucket slug and workspace through this one function so they cannot drift on what "trusted"
+ * means: before this existed, `repoInfo` read `readBinding` directly and skipped the trust check
+ * entirely, so a committed `.gigarag.json` an attacker pointed at another of the victim's buckets
+ * was followed on sight by `/gigaindex`, `gigarag record` and the PostToolUse dirty-marking hook.
+ */
+export function trustedBinding(root) {
+    const found = readBinding(root);
+    if (!found || !isTrusted(found.root, found.binding.workspace))
+        return undefined;
+    return found;
+}
+/** Records that `root`'s binding to `workspace` is trusted. A changed workspace id needs trusting again. */
+export function trustBinding(root, workspace) {
+    const key = trustKey(root);
+    updateConfig(c => {
+        c.trustedBindings = { ...(c.trustedBindings ?? {}), [key]: workspace };
+    });
+}
+/** The binding above `cwd`, when there is one but it has not been trusted yet. */
+export function untrustedBinding(cwd = process.cwd()) {
+    const found = readBinding(cwd);
+    if (!found || isTrusted(found.root, found.binding.workspace))
+        return undefined;
+    return { workspace: found.binding.workspace, root: found.root };
+}
+/** The one-line notice for an untrusted binding: which workspace it names, and the exact command to trust it. */
+export function untrustedBindingNotice(untrusted) {
+    return (`${BINDING_FILE} at ${untrusted.root} links this folder to workspace ${untrusted.workspace}, which has not been trusted, ` +
+        'so GigaRAG used the default workspace instead. If you placed or reviewed this file yourself, run: gigarag trust');
+}
+/**
+ * The workspace a process in `cwd` should use: `GIGARAG_WORKSPACE`, then the
+ * repository's binding when it has been trusted, then the machine default that
+ * `gigarag login` set. An untrusted binding is treated as absent here; callers
+ * that want to tell the person about it call `untrustedBinding` themselves,
+ * since a library call and a background hook must not print anything, and a
+ * bridge or hook is what decides where that notice goes.
+ */
+export function resolveWorkspace(cwd = process.cwd(), env = process.env) {
+    const fromEnv = env['GIGARAG_WORKSPACE']?.trim();
+    if (fromEnv && UUID.test(fromEnv))
+        return { id: fromEnv.toLowerCase(), source: 'env' };
+    const found = readBinding(cwd);
+    if (found && isTrusted(found.root, found.binding.workspace)) {
+        return { id: found.binding.workspace, source: 'binding', binding: found.binding };
+    }
+    const fallback = readConfig().workspaceId;
+    return fallback && UUID.test(fallback) ? { id: fallback.toLowerCase(), source: 'default' } : undefined;
+}

package/cli/cli.js

@@ -8,10 +8,15 @@ Connect GigaRAG to your AI clients.
   gigarag logout                   Delete the stored credential
   gigarag connect [client...]      Add GigaRAG to your installed clients
   gigarag status                   What is configured, and whether the key works
+  gigarag workspaces               Every workspace your account can reach
+  gigarag use <workspace>          Link this repository to a workspace
+  gigarag trust [path]             Trust a .gigarag.json a teammate already committed
 
   gigarag scan [path]              What changed in a repo since it was last indexed
   gigarag repo [path]              Which bucket a directory belongs to
   gigarag record                   Tell the local index what was indexed (reads JSON on stdin)
+  gigarag hooks install [path]     Git hooks that keep GigaRAG in step after each commit
+  gigarag sync begin|end|status    Keep a repository's memos in step with git (/gigasync runs it)
 
   gigarag mcp                      The stdio bridge a client's config runs
   gigarag auth-header              The auth header, for headersHelper
@@ -24,9 +29,14 @@ const COMMANDS = {
     logout: async () => (await import('./commands/login.js')).logout,
     connect: async () => (await import('./commands/connect.js')).connect,
     status: async () => (await import('./commands/status.js')).status,
+    workspaces: async () => (await import('./commands/workspaces.js')).workspaces,
+    use: async () => (await import('./commands/use.js')).use,
+    trust: async () => (await import('./commands/trust.js')).trust,
     scan: async () => (await import('./commands/scan.js')).scan,
     repo: async () => (await import('./commands/repo.js')).repo,
     record: async () => (await import('./commands/record.js')).record,
+    hooks: async () => (await import('./commands/gitHooks.js')).hooks,
+    sync: async () => (await import('./commands/sync.js')).sync,
     mcp: async () => (await import('./commands/mcp.js')).mcp,
     'auth-header': async () => (await import('./commands/authHeader.js')).authHeader,
     'index-sync': async () => (await import('./commands/indexSync.js')).indexSync,

package/cli/commands/authHeader.js

@@ -1,18 +1,15 @@
-import { authorizationHeader, loadCredential } from '../auth/credentials.js';
+import { createClient } from '../mcp/session.js';
 import { err, out } from '../ui.js';
 /**
  * What `headersHelper` runs. Claude Code expects one JSON object of string
  * pairs on stdout, and gives up after 10 seconds, so nothing else may print here
- * and nothing slow may run.
+ * and nothing slow may run. The workspace comes from the folder Claude Code
+ * starts it in, the same way the bridge picks it.
  */
 export async function authHeader() {
-    const credential = loadCredential();
-    if (!credential) {
-        err('Not signed in to GigaRAG. Run: gigarag login');
-        return 1;
-    }
     try {
-        out(JSON.stringify({ Authorization: await authorizationHeader(credential) }));
+        const authorization = await createClient().authorizationHeader();
+        out(JSON.stringify({ Authorization: authorization }));
         return 0;
     }
     catch (e) {

package/cli/commands/connect.js

@@ -1,6 +1,7 @@
 import { parseArgs } from 'node:util';
 import { updateConfig, readConfig } from '../config.js';
-import { loadCredential } from '../auth/credentials.js';
+import { loadAccountCredential, loadCredential } from '../auth/credentials.js';
+import { resolveWorkspace } from '../binding.js';
 import { resolveUrl } from '../mcp/session.js';
 import { tildify } from '../paths.js';
 import { connectClient, removeClientEntry, renderConfig } from '../clients/connect.js';
@@ -168,7 +169,8 @@ export async function connect(argv) {
     }
     // With --json the output is for a program, and one stray line after the JSON would break its parser.
     if (!values.json) {
-        if (!loadCredential()) {
+        const signedIn = loadCredential(process.env, resolveWorkspace()?.id) || loadAccountCredential();
+        if (!signedIn) {
             out('\nYou are not signed in yet, so these clients cannot reach GigaRAG. Run: gigarag login');
         }
         if (named.length === 0) {