waku-memory 0.1.0 → 0.3.0

package/dist/login.js

@@ -0,0 +1,312 @@
+// `login` -- the browser OAuth flow that mints an API key without the
+// person ever seeing one (spec 012 §7). Wired by cli.ts's `login` command
+// and, since task 13, `capture enable`'s third path (a person who has no
+// key yet is offered this instead of the paste prompt); this file only
+// orchestrates the flow itself against an injected deps bag, the same
+// split hook.ts/capture.ts already established, so login.test.mjs can
+// drive it against a fake authorization server and a fake API on
+// 127.0.0.1 and never touch a real browser or a real waku.one.
+//
+// The shape, in order: discover the authorization server from the API's
+// protected-resource metadata, dynamically register a public client,
+// listen on a loopback port, send the person to the authorization
+// endpoint (PKCE S256, a random state, printed and opened), wait for the
+// redirect back, exchange the code for a token, mint a key with it, and
+// write that key exactly where a pasted one goes (writeConfigJson,
+// sanitizeKey -- both capture.ts's, not reimplemented here).
+//
+// Zero new runtime dependency, per the shim's package.json: node:http,
+// node:crypto, node:os and capture.ts (itself dependency-free) only.
+import { createServer } from 'node:http';
+import { randomBytes, createHash } from 'node:crypto';
+import { hostname } from 'node:os';
+import { sanitizeKey, writeConfigJson } from "./capture.js";
+// §7: five minutes to complete a browser round trip is generous without
+// being indefinite -- a person who wanders off leaves nothing running past
+// that, and the loopback server closes either way (see login()'s finish).
+export const LOGIN_TIMEOUT_MS = 300_000;
+export const LOGIN_SCOPES = 'openid profile email offline_access';
+// The `resource` parameter (RFC 8707) login sends in the authorize URL and
+// the token request is always derived at runtime from deps.apiBase --
+// `${apiBase}/mcp` with a trailing slash stripped first -- never this
+// constant. LOGIN_RESOURCE exists only as the documented value for the
+// default apiBase, so a reader (or a test asserting against the default)
+// has something to compare the runtime value to without recomputing it.
+export const LOGIN_RESOURCE = 'https://api.waku.one/mcp';
+const REGISTERED_REDIRECT_URI = 'http://127.0.0.1/callback';
+// Carries which of the four network steps failed and the HTTP status that
+// said so -- login()'s refusal branches read both off this and print
+// neither a response body nor anything from the request (never the token,
+// never the key): "Sign-in failed at <step> (HTTP <status>)." is the whole
+// line.
+class StepError extends Error {
+    step;
+    status;
+    constructor(step, status) {
+        super(`${step} step failed with HTTP ${status}`);
+        this.step = step;
+        this.status = status;
+    }
+}
+function stripSlash(url) {
+    return url.replace(/\/+$/, '');
+}
+// GET <apiBase>/.well-known/oauth-protected-resource for the resource's
+// authorization server, then that server's own
+// /.well-known/oauth-authorization-server for the three endpoints login
+// needs. Throws StepError('discovery', status) on anything short of a
+// clean pair of 2xx JSON responses carrying the fields this reads --
+// login() is the only caller and turns that into the one printed line.
+export async function discover(apiBase, fetchImpl) {
+    const base = stripSlash(apiBase);
+    const resourceRes = await fetchImpl(`${base}/.well-known/oauth-protected-resource`);
+    if (!resourceRes.ok)
+        throw new StepError('discovery', resourceRes.status);
+    const resourceBody = (await resourceRes.json());
+    const issuer = Array.isArray(resourceBody.authorization_servers) ? resourceBody.authorization_servers[0] : undefined;
+    if (typeof issuer !== 'string' || issuer === '')
+        throw new StepError('discovery', resourceRes.status);
+    const asRes = await fetchImpl(`${stripSlash(issuer)}/.well-known/oauth-authorization-server`);
+    if (!asRes.ok)
+        throw new StepError('discovery', asRes.status);
+    const asBody = (await asRes.json());
+    const { authorization_endpoint, token_endpoint, registration_endpoint } = asBody;
+    if (typeof authorization_endpoint !== 'string' ||
+        typeof token_endpoint !== 'string' ||
+        typeof registration_endpoint !== 'string') {
+        throw new StepError('discovery', asRes.status);
+    }
+    return {
+        issuer,
+        authorizationEndpoint: authorization_endpoint,
+        tokenEndpoint: token_endpoint,
+        registrationEndpoint: registration_endpoint,
+    };
+}
+// Dynamic client registration (RFC 7591): a public client, redirect fixed
+// at the bare loopback address (RFC 8252 §7.3 -- the *port* login actually
+// redirects to is chosen per run and never registered, which is the whole
+// point of the loopback exception). Returns client_id; throws
+// StepError('registration', status) otherwise.
+export async function registerClient(registrationEndpoint, fetchImpl, version) {
+    const res = await fetchImpl(registrationEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            client_name: `waku-memory ${version}`,
+            redirect_uris: [REGISTERED_REDIRECT_URI],
+            grant_types: ['authorization_code'],
+            response_types: ['code'],
+            token_endpoint_auth_method: 'none',
+        }),
+    });
+    if (!res.ok)
+        throw new StepError('registration', res.status);
+    const body = (await res.json());
+    if (typeof body.client_id !== 'string' || body.client_id === '')
+        throw new StepError('registration', res.status);
+    return body.client_id;
+}
+// PKCE (RFC 7636), S256 only: a 32-byte random verifier, base64url; the
+// challenge is its SHA-256 digest, also base64url. Buffer's own
+// 'base64url' encoding already omits padding, so neither value needs the
+// usual base64 cleanup.
+export function pkce() {
+    const verifier = randomBytes(32).toString('base64url');
+    const challenge = createHash('sha256').update(verifier).digest('base64url');
+    return { verifier, challenge };
+}
+export function authorizeUrl(p) {
+    const url = new URL(p.authorizationEndpoint);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', p.clientId);
+    url.searchParams.set('redirect_uri', p.redirectUri);
+    url.searchParams.set('state', p.state);
+    url.searchParams.set('code_challenge', p.challenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    url.searchParams.set('scope', LOGIN_SCOPES);
+    url.searchParams.set('resource', p.resource);
+    return url.toString();
+}
+async function exchangeToken(tokenEndpoint, fetchImpl, p) {
+    const body = new URLSearchParams({
+        grant_type: 'authorization_code',
+        code: p.code,
+        redirect_uri: p.redirectUri,
+        client_id: p.clientId,
+        code_verifier: p.verifier,
+        resource: p.resource,
+    });
+    const res = await fetchImpl(tokenEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: body.toString(),
+    });
+    if (!res.ok)
+        throw new StepError('token', res.status);
+    const json = (await res.json());
+    if (typeof json.access_token !== 'string' || json.access_token === '')
+        throw new StepError('token', res.status);
+    return { accessToken: json.access_token, idToken: typeof json.id_token === 'string' ? json.id_token : undefined };
+}
+// The email printed in the final "Signed in as <email>" line -- read from
+// the token response's id_token, an unsigned decode of its middle segment
+// (base64url JSON), never signature-checked: it arrived over TLS from the
+// issuer discover() itself found, and the only use is one word in a
+// stdout line, not an authorization decision. Anything short of a clean
+// {email: string} there (no id_token, unparseable, wrong shape) falls back
+// to the literal word "you" -- login() never blocks on this.
+function emailFromIdToken(idToken) {
+    if (!idToken)
+        return null;
+    const parts = idToken.split('.');
+    if (parts.length < 2)
+        return null;
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+        return typeof payload.email === 'string' && payload.email !== '' ? payload.email : null;
+    }
+    catch {
+        return null;
+    }
+}
+// keys.py's CreateKeyRequest.label: free text, default "unnamed", capped
+// at 200 chars server-side -- truncated here too so a very long hostname
+// never trips the server's own validation into a refusal this file would
+// then have to explain.
+function keyLabel() {
+    const label = `waku-memory on ${hostname()}`;
+    return label.length > 200 ? label.slice(0, 200) : label;
+}
+function reportRefusal(deps, fallbackStep, err) {
+    const step = err instanceof StepError ? err.step : fallbackStep;
+    const status = err instanceof StepError ? err.status : 0;
+    deps.stdout(`Sign-in failed at ${step} (HTTP ${status}).`);
+}
+// The whole flow. Never prints the token or the key on any path -- the
+// only things written to deps.stdout are the authorize URL, the final
+// "Signed in as <email>" line, and (on refusal) the one-line step/status
+// report above. The loopback server, once opened, is closed on every path
+// out of the returned promise: 'signed-in', 'timeout', and 'refused' from
+// a bad token or keys response all go through the same finish().
+// 'refused' from discovery or registration returns before any server
+// exists, so there is nothing to close on those two paths.
+export async function login(deps) {
+    const apiBase = stripSlash(deps.apiBase);
+    const resource = `${apiBase}/mcp`;
+    const timeoutMs = deps.timeoutMs ?? LOGIN_TIMEOUT_MS;
+    let discovered;
+    try {
+        discovered = await discover(apiBase, deps.fetchImpl);
+    }
+    catch (err) {
+        reportRefusal(deps, 'discovery', err);
+        return 'refused';
+    }
+    let clientId;
+    try {
+        clientId = await registerClient(discovered.registrationEndpoint, deps.fetchImpl, deps.version);
+    }
+    catch (err) {
+        reportRefusal(deps, 'registration', err);
+        return 'refused';
+    }
+    const { verifier, challenge } = pkce();
+    const state = randomBytes(16).toString('hex');
+    return new Promise((resolveLogin) => {
+        let settled = false;
+        let port = 0;
+        let accepted = false;
+        const server = createServer((req, res) => {
+            const requestUrl = new URL(req.url ?? '/', 'http://127.0.0.1');
+            if (requestUrl.pathname !== '/callback') {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+            const code = requestUrl.searchParams.get('code');
+            const receivedState = requestUrl.searchParams.get('state');
+            if (receivedState !== state || !code) {
+                // Wrong or missing state: keep waiting -- a stray or forged hit on
+                // this port must not end the flow the real browser is still
+                // carrying.
+                res.writeHead(400);
+                res.end();
+                return;
+            }
+            // OAuth codes are single-use and minting a credential should be
+            // idempotent only by accident; the client must not rely on the
+            // authorization server to defend against replay. Guard here: flag
+            // the code accepted before any async work, so a concurrent request
+            // sees the flag and returns 200 without re-running the exchange.
+            if (accepted) {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end('Signed in. You can close this tab.');
+                return;
+            }
+            accepted = true;
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end('Signed in. You can close this tab.');
+            void finishSignIn(code);
+        });
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            server.close();
+            resolveLogin(result);
+        };
+        async function finishSignIn(code) {
+            try {
+                const redirectUri = `http://127.0.0.1:${port}/callback`;
+                const tokenResult = await exchangeToken(discovered.tokenEndpoint, deps.fetchImpl, {
+                    code,
+                    redirectUri,
+                    clientId,
+                    verifier,
+                    resource,
+                });
+                const keysRes = await deps.fetchImpl(`${apiBase}/keys`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: `Bearer ${tokenResult.accessToken}`,
+                    },
+                    body: JSON.stringify({ label: keyLabel() }),
+                });
+                if (!keysRes.ok)
+                    throw new StepError('keys', keysRes.status);
+                const keysBody = (await keysRes.json());
+                if (typeof keysBody.plaintext !== 'string' || keysBody.plaintext === '') {
+                    throw new StepError('keys', keysRes.status);
+                }
+                const { key } = sanitizeKey(keysBody.plaintext);
+                writeConfigJson(deps.configDir, { url: apiBase, key });
+                const email = emailFromIdToken(tokenResult.idToken) ?? 'you';
+                deps.stdout(`Signed in as ${email}. Key stored in ${deps.configDir}/config.json.`);
+                finish('signed-in');
+            }
+            catch (err) {
+                reportRefusal(deps, 'token', err);
+                finish('refused');
+            }
+        }
+        const timer = setTimeout(() => finish('timeout'), timeoutMs);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            port = typeof address === 'object' && address !== null ? address.port : 0;
+            const redirectUri = `http://127.0.0.1:${port}/callback`;
+            const url = authorizeUrl({
+                authorizationEndpoint: discovered.authorizationEndpoint,
+                clientId,
+                redirectUri,
+                state,
+                challenge,
+                resource,
+            });
+            deps.stdout(`Open this URL if your browser did not: ${url}`);
+            deps.openBrowser(url);
+        });
+    });
+}

package/dist/project.js

@@ -0,0 +1,43 @@
+// Spec 011 §7: the project is the directory name, except that a git
+// worktree names the repository it belongs to. A worktree's `.git` is a
+// file holding `gitdir: <repo>/.git/worktrees/<name>`; a checkout's `.git`
+// is a directory. Read with fs only -- no git binary.
+import { readFileSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+export function resolveProject(cwd, io = { statSync, readFileSync }) {
+    const start = resolve(cwd);
+    let dir = start;
+    for (;;) {
+        const dotGit = join(dir, '.git');
+        let stat;
+        try {
+            stat = io.statSync(dotGit);
+        }
+        catch {
+            stat = undefined;
+        }
+        if (stat?.isDirectory())
+            return basename(start);
+        if (stat?.isFile()) {
+            let content;
+            try {
+                content = io.readFileSync(dotGit, 'utf8');
+            }
+            catch {
+                return basename(start); // unreadable: the checkout's own name, never a throw (§7)
+            }
+            const m = /^gitdir:\s*(.+?)\s*$/m.exec(content);
+            if (m) {
+                const gitdir = isAbsolute(m[1]) ? m[1] : resolve(dir, m[1]);
+                const wt = /^(.*)[\\/]\.git[\\/]worktrees[\\/][^\\/]+$/.exec(gitdir);
+                if (wt)
+                    return basename(wt[1]);
+            }
+            return basename(start);
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return basename(start);
+        dir = parent;
+    }
+}

package/hooks/hooks.json

@@ -0,0 +1,63 @@
+{
+  "description": "Waku Memory: the session brief and turn capture through the waku MCP server.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "mcp_tool",
+            "server": "waku",
+            "tool": "session.hook",
+            "timeout": 10,
+            "statusMessage": "Waku memory",
+            "input": {
+              "event": "${hook_event_name}",
+              "session_id": "${session_id}",
+              "cwd": "${cwd}",
+              "source": "${source}"
+            }
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "mcp_tool",
+            "server": "waku",
+            "tool": "session.hook",
+            "timeout": 10,
+            "input": {
+              "event": "${hook_event_name}",
+              "session_id": "${session_id}",
+              "cwd": "${cwd}",
+              "turn_id": "${turn_id}",
+              "prompt": "${prompt}"
+            }
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "mcp_tool",
+            "server": "waku",
+            "tool": "session.hook",
+            "timeout": 10,
+            "input": {
+              "event": "${hook_event_name}",
+              "session_id": "${session_id}",
+              "cwd": "${cwd}",
+              "turn_id": "${turn_id}",
+              "last_assistant_message": "${last_assistant_message}"
+            }
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waku-memory",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Install Waku Memory into your agent harness, and turn on automatic session capture.",
   "keywords": ["mcp", "memory", "claude-code", "agent", "waku"],
   "homepage": "https://github.com/ShenSeanChen/waku-memory-backend/tree/spec-driven/shim#readme",
@@ -14,7 +14,7 @@
   },
   "type": "module",
   "bin": { "waku-memory": "./dist/index.js" },
-  "files": ["dist"],
+  "files": ["dist", ".codex-plugin", ".mcp.json", "hooks", "skills"],
   "engines": { "node": ">=20" },
   "publishConfig": { "access": "public" },
   "scripts": {

package/skills/waku/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: waku
+description: Durable memory for this person across sessions. Use memory.recall for what is known about a project and memory.remember for something worth keeping.
+---
+
+Waku Memory keeps what a person tells their agents and what their agents
+learn, and brings it back into later sessions.
+
+- At the start of a session the plugin's hooks add a short brief of the
+  project's memories to your context. It arrives on the first or second
+  prompt; nothing needs to be called for it.
+- Call `memory.recall` with `scope: "project:<name>"` when the person asks
+  what is known, or when a task depends on a preference or decision you do
+  not have. Call `memory.search` for one specific thing.
+- Call `memory.remember` when the person states a preference, a decision,
+  a procedure or a fact they will want next time. Use their words. Do not
+  store secrets, credentials or file contents.
+- What the person types and what you reply is sent to Waku after each turn
+  by the plugin's hooks; tool output is not.
+
+One-time setup the person does: after installing, Codex asks them to
+review and trust this plugin's hooks (`/hooks` in the CLI). Until then
+the brief and the capture do not run.