har2sdk 0.6.3 → 0.6.4

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.6.4
+
+A privacy fix in the mock's fake data, an Auth section in the README, and tests that pin both.
+
+**Security**
+- When a fake drawn for a recorded value happened to equal it (about 1 in 26³ for a three-letter name), the fallback reversed it: the mock served `"adA"` for `"Ada"`, `"7x"` for `"x7"`, the recorded value backwards and in the wrong shape. A collision now draws again from the same hash stream, so the fake never derives from the recorded value; a last-resort bump of one character remains for the case where 9 draws in a row all return it. Outputs without a collision are unchanged. Found by a CI failure in `review.test.ts`; `test/scrubber.test.ts` has the seeds that reproduce it and a generated run over 20,000 seeds (#4).
+
+**Docs**
+- README: an Auth section. The recorded token never reaches `client.ts`; which auth options a client gets; the token is sent with the scheme the app used (bare if it was sent bare, `Bearer` if no auth was seen); a token function is called before every request; a 401 throws `ApiError` without retry or refresh, with a refresh recipe; the mock doesn't check auth (#3).
+
+**Tests**
+- `test/auth.test.ts` pins every claim in the Auth section and runs its refresh recipe as written. `test/nullability.test.ts` records one field as a string, as `null` and left out, in every order, and checks `client.ts`, `openapi.json`, typechecking under `exactOptionalPropertyTypes` and the mock (#3).
+
 ## 0.6.3
 
 Fixes from an eighth review, the last audit before publishing. Every finding has a test in `test/review8.test.ts` (written first and seen failing), and the second suite of the generated privacy test puts the person's name in a GraphQL comment and in a free-text `operationName`.

package/README.md

@@ -76,6 +76,40 @@ Needs Node 20+. Reads standard HAR 1.2: tested with Chrome-style exports and Pla
 
 The generated `client.ts` has **zero dependencies**, uses the global `fetch` (Node 20+ and browsers), and compiles under `strict`, `exactOptionalPropertyTypes` and `erasableSyntaxOnly`. Non-2xx responses throw `ApiError` with the parsed body.
 
+## Auth
+
+The capture tells har2sdk *how* the app authenticated, never *with what*. The token, cookie or key you recorded is not copied into `client.ts` (if it were, the [leak guard](#privacy) would refuse to write the file). You pass your own:
+
+```ts
+new AcmeShopClient({ token: process.env.TOKEN });  // a string
+new AcmeShopClient({ token: () => getToken() });   // or a function, sync or async
+```
+
+- **Which options you get** depends on what the capture used: `token` (sent in `Authorization` with the scheme the app used, e.g. `Bearer …` or `Token …`, or bare if the app sent it bare; `Bearer` if no auth was seen), `basicAuth`, `apiKey` (in the header or query parameter the app used) and `cookie`. If no auth was seen, you get `token`.
+- **A token function is called before every request**, so it can hand out a fresh token each time. For anything else computed per request (a CSRF header, a signature), pass `headers: async () => ({ … })`.
+- **Refreshing is up to you.** On a `401` the client doesn't retry or refresh: it throws `ApiError` with `status`, the parsed `body` and the `operation` that failed. One way to handle it:
+
+  ```ts
+  import { AcmeShopClient, ApiError } from "./har2sdk-out/client.js";
+
+  let token = await login();
+  const shop = new AcmeShopClient({ token: () => token });
+
+  async function withRefresh<T>(call: () => Promise<T>): Promise<T> {
+    try {
+      return await call();
+    } catch (err) {
+      if (!(err instanceof ApiError) || err.status !== 401) throw err;
+      token = await refresh();
+      return call();
+    }
+  }
+
+  const me = await withRefresh(() => shop.getMe());
+  ```
+
+- **The mock doesn't check auth.** Any token, or none, gets the same response.
+
 ## Privacy
 
 HAR files contain live session cookies, tokens and often other people's data. har2sdk:

package/dist/codegen.d.ts

@@ -3,7 +3,7 @@
  * runtime dependencies (uses the global `fetch`, Node 18+ or any browser).
  */
 import type { Plan, PlannedOp } from "./plan.js";
-export declare const VERSION = "0.6.3";
+export declare const VERSION = "0.6.4";
 export declare function generateTypeScript(plan: Plan): string;
 /** Just the type declarations (used for prompts and MCP responses). */
 export declare function generateTypesOnly(plan: Plan, onlyOps?: PlannedOp[]): string;

package/dist/codegen.js

@@ -1,6 +1,6 @@
 import { printTs, printTsInterface } from "./types.js";
 import { propertyKey } from "./words.js";
-export const VERSION = "0.6.3";
+export const VERSION = "0.6.4";
 export function generateTypeScript(plan) {
     const { model, clientName, ops } = plan;
     const out = [];

package/dist/redact.js

@@ -576,7 +576,9 @@ export class Scrubber {
             h ^= h << 5;
             return h >>> 0;
         };
-        const body = [...v.slice(prefix.length)].map((ch, i) => {
+        const rest = v.slice(prefix.length);
+        const draw = () => [...rest]
+            .map((ch, i) => {
             if (/[0-9]/.test(ch))
                 return String((next() % 9) + (i === 0 ? 1 : 0));
             if (/[a-f]/.test(ch) && /^[0-9a-f-]+$/i.test(v))
@@ -586,13 +588,19 @@ export class Scrubber {
             if (/[A-Z]/.test(ch))
                 return String.fromCharCode(65 + (next() % 26));
             return ch;
-        });
-        f = prefix + body.join("");
-        if (f === v)
-            f = prefix + body.reverse().join("");
-        // Still the recorded value (a palindrome like "66"): bump the first digit or letter.
-        if (f === v)
-            f = prefix + body.join("").replace(/[0-9a-zA-Z]/, (c) => (/\d/.test(c) ? String((Number(c) + 1) % 10) : c === "z" ? "a" : c === "Z" ? "A" : String.fromCharCode(c.charCodeAt(0) + 1)));
+        })
+            .join("");
+        // Drew the recorded value itself: draw again from the same stream. Never derive the
+        // fake from the recorded value (reversing it kept it readable and broke its shape).
+        let body = draw();
+        for (let tries = 0; body === rest && tries < 8; tries++)
+            body = draw();
+        // Still the recorded value (only separators, or a very unlucky run): bump the first digit or letter.
+        // This bump is still derived from the recorded value, but it only runs after 9 draws in a row
+        // all returned it, which is next to impossible for any value with a digit or letter in it.
+        if (body === rest)
+            body = body.replace(/[0-9a-zA-Z]/, (c) => (/\d/.test(c) ? String((Number(c) + 1) % 10) : c === "z" ? "a" : c === "Z" ? "A" : String.fromCharCode(c.charCodeAt(0) + 1)));
+        f = prefix + body;
         this.fakes.set(v, f);
         return f;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "har2sdk",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Turn browser network traffic (HAR) into a typed TypeScript SDK, an OpenAPI 3.1 spec and a mock server. Local, deterministic, no API key. Ships an MCP server so Claude can name and document every endpoint.",
   "keywords": [
     "har",