agentfootprint 9.7.0 → 9.9.0

package/dist/esm/adapters/observability/githubDeviceSignIn.js

@@ -0,0 +1,259 @@
+/**
+ * githubDeviceSignIn — let the REPORTER sign in, so the issue is filed as them.
+ *
+ *   import { githubDeviceSignIn } from 'agentfootprint/observe';
+ *
+ *   const signIn = await githubDeviceSignIn({ clientId: 'Iv1.0123456789abcdef' });
+ *   show(`Go to ${signIn.verificationUri} and enter ${signIn.userCode}`);
+ *   const { token, login } = await signIn.completed;   // resolves on authorize
+ *
+ * GitHub's OAuth **device flow**, spoken as three plain `fetch` calls and
+ * nothing else: request a code, show it to the human, poll until they approve.
+ * Zero dependencies, and it runs in a browser as well as on a server — there is
+ * no client secret in this flow, which is exactly why it is the one that works
+ * from a page.
+ *
+ * ## Why this exists beside a server token
+ *
+ * A server-side PAT files every report as the application. That is right for an
+ * automated "Report a problem" button: the app owns the repo, the app owns the
+ * token. It is wrong when the value is ATTRIBUTION — a field tester filing
+ * upstream should appear as themselves, so a maintainer can ask them a
+ * follow-up question and so their report counts as theirs.
+ *
+ * | | server PAT | device sign-in |
+ * |---|---|---|
+ * | Who the issue is from | the application | the reporter |
+ * | Where the token lives | server environment | the reporter's session, in memory |
+ * | Human steps | none | one: enter a code, approve |
+ * | Right for | in-app "report a problem" | field testers filing upstream |
+ *
+ * The token this returns is handed to {@link githubBugReporter} as `token`,
+ * with no special-casing anywhere: a token is a token.
+ *
+ * ## Keep it in memory, for the session only
+ *
+ * **Never `localStorage`, never a cookie, never a log line.** A device-flow
+ * token is a live credential for the account that approved it; persisting it in
+ * a browser turns one XSS into a lasting account compromise. Hold it in a
+ * variable, use it, drop it when the tab closes.
+ *
+ * ## Scopes are coarse here, and that is GitHub's design
+ *
+ * The device flow issues a CLASSIC OAuth token, and classic scopes are coarse:
+ * `public_repo` (the default here) grants write across every public repository
+ * the account can reach, and `repo` grants it across private ones too. There is
+ * no fine-grained equivalent in this flow. That trade buys attribution — the
+ * issue is really from that person — and it is the reason the default stops at
+ * `public_repo`: filing an issue needs no more, and the token disappears with
+ * the session. Where least privilege matters more than attribution, use a
+ * fine-grained PAT on a server instead (see {@link githubBugReporter}).
+ *
+ * ## The collaborator caveat, stated rather than discovered
+ *
+ * A reporter who signs in as themselves can file an issue on a public repo, and
+ * can commit evidence ONLY to a repository they can write to. Pointing
+ * `evidenceRepo` at a private repo the reporter is not a collaborator on will
+ * fail with a 404 (GitHub hides private repos from tokens that cannot see
+ * them). Either add the reporter as a collaborator, or let them attach the zip
+ * to the issue by hand — `exportBugReport` gives them the file either way.
+ *
+ * ## Secrecy
+ *
+ * The token appears in no message this module can produce. The three failure
+ * shapes of the flow — the human denied it, the code expired, the poll was
+ * aborted — are named plainly, with GitHub's `error_description` only, never a
+ * response body or a request.
+ */
+/** The endpoints, so a GitHub Enterprise Server deployment can move them. */
+const DEFAULT_AUTH_BASE = 'https://github.com';
+const DEFAULT_API_BASE = 'https://api.github.com';
+const defaultSleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(abortedError());
+        return;
+    }
+    const timer = setTimeout(() => {
+        signal?.removeEventListener('abort', onAbort);
+        resolve();
+    }, ms);
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(abortedError());
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+});
+const abortedError = () => new Error('githubDeviceSignIn: sign-in was cancelled before the code was approved.');
+/**
+ * Start a device-flow sign-in.
+ *
+ * Resolves as soon as GitHub hands back a code — that is the point, because
+ * the human cannot approve a code they have not been shown. The waiting happens
+ * on the returned `completed` promise.
+ *
+ * @throws TypeError when `clientId` is missing (naming where it comes from).
+ * @throws Error naming the status when GitHub refuses to issue a code.
+ */
+export async function githubDeviceSignIn(options) {
+    if (typeof options?.clientId !== 'string' || options.clientId.trim() === '') {
+        throw new TypeError('githubDeviceSignIn: `clientId` is required. Create an OAuth App once under your ' +
+            'organisation (Settings → Developer settings → OAuth Apps), tick "Enable Device ' +
+            'Flow", and pass its Client ID here. It is public by design — the device flow has no ' +
+            'client secret, which is why it can run in a browser.');
+    }
+    const authBase = (options.authBase ?? DEFAULT_AUTH_BASE).replace(/\/+$/, '');
+    const apiBase = (options.apiBase ?? DEFAULT_API_BASE).replace(/\/+$/, '');
+    const doFetch = options._fetch ?? ((...args) => fetch(...args));
+    const sleep = options._sleep ?? defaultSleep;
+    const scopes = options.scopes ?? ['public_repo'];
+    const start = await postForm({
+        doFetch,
+        url: `${authBase}/login/device/code`,
+        what: 'request a device code',
+        form: { client_id: options.clientId, scope: scopes.join(' ') },
+    });
+    const deviceCode = stringField(start, 'device_code');
+    const userCode = stringField(start, 'user_code');
+    const verificationUri = stringField(start, 'verification_uri');
+    if (!deviceCode || !userCode || !verificationUri) {
+        throw new Error(`githubDeviceSignIn: GitHub did not return a device code${errorSuffix(start)}. Check that ` +
+            'the OAuth App exists and has Device Flow enabled.');
+    }
+    const expiresIn = numberField(start, 'expires_in') ?? 900;
+    const interval = numberField(start, 'interval') ?? 5;
+    const completed = pollForToken({
+        doFetch,
+        sleep,
+        authBase,
+        apiBase,
+        clientId: options.clientId,
+        deviceCode,
+        interval,
+        expiresIn,
+        ...(options.signal !== undefined && { signal: options.signal }),
+    });
+    // Nobody has to await `completed` for polling to run; make sure an unawaited
+    // rejection is not an unhandled one in the meantime.
+    completed.catch(() => undefined);
+    return { userCode, verificationUri, expiresIn, interval, completed };
+}
+async function pollForToken(args) {
+    let waitSeconds = args.interval;
+    const deadline = Date.now() + args.expiresIn * 1000;
+    for (;;) {
+        if (args.signal?.aborted)
+            throw abortedError();
+        await args.sleep(waitSeconds * 1000, args.signal);
+        if (Date.now() > deadline) {
+            throw new Error(`githubDeviceSignIn: the code expired after ${args.expiresIn}s without being ` +
+                'approved. Start the sign-in again to get a fresh one.');
+        }
+        const body = await postForm({
+            doFetch: args.doFetch,
+            url: `${args.authBase}/login/oauth/access_token`,
+            what: 'exchange the device code',
+            form: {
+                client_id: args.clientId,
+                device_code: args.deviceCode,
+                grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+            },
+        });
+        const token = stringField(body, 'access_token');
+        if (token) {
+            const scope = stringField(body, 'scope') ?? '';
+            const login = await readLogin(args.doFetch, args.apiBase, token);
+            return {
+                token,
+                tokenType: stringField(body, 'token_type') ?? 'bearer',
+                scopes: scope ? scope.split(/[\s,]+/).filter(Boolean) : [],
+                ...(login !== undefined && { login }),
+            };
+        }
+        const error = stringField(body, 'error');
+        switch (error) {
+            case 'authorization_pending':
+                // The human has not finished yet. This is the normal answer.
+                break;
+            case 'slow_down':
+                // GitHub's own back-pressure: it tells us the new interval, and polling
+                // faster than it asked gets the flow rate-limited out entirely.
+                waitSeconds = numberField(body, 'interval') ?? waitSeconds + 5;
+                break;
+            case 'expired_token':
+                throw new Error('githubDeviceSignIn: the code expired before it was approved. Start the sign-in ' +
+                    'again to get a fresh one.');
+            case 'access_denied':
+                throw new Error('githubDeviceSignIn: the sign-in was denied on GitHub, so no token was issued. ' +
+                    'Nothing has been filed.');
+            default:
+                throw new Error(`githubDeviceSignIn: GitHub refused the device code exchange${errorSuffix(body)}.`);
+        }
+    }
+}
+/** Attribution: which login will the issue read as? Never fatal — a token that
+ *  cannot read `/user` can still file an issue. */
+async function readLogin(doFetch, apiBase, token) {
+    try {
+        const res = await doFetch(`${apiBase}/user`, {
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: 'application/vnd.github+json',
+                'x-github-api-version': '2022-11-28',
+            },
+        });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        return typeof body?.login === 'string' ? body.login : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * One `application/x-www-form-urlencoded` POST that asks for JSON back.
+ *
+ * The device flow's endpoints answer form-encoded by default; `accept: json` is
+ * what makes them speak JSON. A thrown fetch is re-wrapped so no implementation
+ * can put the request — which carries the device code, and later the token — in
+ * the message.
+ */
+async function postForm(args) {
+    let res;
+    try {
+        res = await args.doFetch(args.url, {
+            method: 'POST',
+            headers: { accept: 'application/json', 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams(args.form).toString(),
+        });
+    }
+    catch (err) {
+        throw new Error(`githubDeviceSignIn: could not reach GitHub to ${args.what} ` +
+            `(${err instanceof Error ? err.name || 'network error' : 'network error'}).`);
+    }
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        body = undefined;
+    }
+    const record = typeof body === 'object' && body !== null ? body : {};
+    // A 4xx/5xx with no parsed error field is all we may say: the response body
+    // of this endpoint can echo the request.
+    if (!res.ok && typeof record.error !== 'string') {
+        throw new Error(`githubDeviceSignIn: GitHub answered ${res.status} when asked to ${args.what}.`);
+    }
+    return record;
+}
+const stringField = (body, key) => typeof body[key] === 'string' && body[key] !== '' ? body[key] : undefined;
+const numberField = (body, key) => typeof body[key] === 'number' ? body[key] : undefined;
+/** GitHub's `error` / `error_description` — the only response text we echo. */
+function errorSuffix(body) {
+    const code = stringField(body, 'error');
+    const description = stringField(body, 'error_description');
+    if (!code && !description)
+        return '';
+    return ` (${[code, description].filter(Boolean).join(': ').slice(0, 200)})`;
+}
+//# sourceMappingURL=githubDeviceSignIn.js.map

package/dist/esm/adapters/observability/githubDeviceSignIn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"githubDeviceSignIn.js","sourceRoot":"","sources":["../../../../src/adapters/observability/githubDeviceSignIn.ts"],"names":[],"mappings":"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"}

package/dist/esm/identity.d.ts

@@ -35,3 +35,4 @@ export type { AuthorizationRequiredMode, ConsentRequest } from './identity/conse
 export { CredentialConsentRequiredError, type CredentialConsentRequiredContext, } from './identity/CredentialConsentRequiredError.js';
 export { withCredentialRetry, type WithCredentialRetryOptions, } from './identity/withCredentialRetry.js';
 export { agentCoreIdentity, type AgentCoreIdentityOptions, type AgentCoreIdentityClientLike, type AgentCoreOauthResponse, } from './adapters/identity/agentcore.js';
+export { vaultCredentials, type VaultCredentialsOptions } from './adapters/identity/vault.js';

package/dist/esm/identity.js

@@ -33,4 +33,8 @@ export { staticTokens } from './identity/staticTokens.js';
 export { CredentialConsentRequiredError, } from './identity/CredentialConsentRequiredError.js';
 export { withCredentialRetry, } from './identity/withCredentialRetry.js';
 export { agentCoreIdentity, } from './adapters/identity/agentcore.js';
+// HashiCorp-Vault-compatible KV v2, over plain HTTP (9.8.0) — no SDK, no
+// vendor client. V1 is token auth + KV v2 + no leases, and every other shape
+// is refused by name rather than guessed at; see the module docstring.
+export { vaultCredentials } from './adapters/identity/vault.js';
 //# sourceMappingURL=identity.js.map

package/dist/esm/identity.js.map

@@ -1 +1 @@
-{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAWH,OAAO,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC;AACzF,OAAO,EACL,MAAM,EACN,MAAM,EACN,KAAK,EACL,OAAO,GAKR,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAA4B,MAAM,4BAA4B,CAAC;AAKpF,OAAO,EACL,8BAA8B,GAE/B,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,mBAAmB,GAEpB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,iBAAiB,GAIlB,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAWH,OAAO,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC;AACzF,OAAO,EACL,MAAM,EACN,MAAM,EACN,KAAK,EACL,OAAO,GAKR,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAA4B,MAAM,4BAA4B,CAAC;AAKpF,OAAO,EACL,8BAA8B,GAE/B,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,mBAAmB,GAEpB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,iBAAiB,GAIlB,MAAM,kCAAkC,CAAC;AAC1C,yEAAyE;AACzE,6EAA6E;AAC7E,uEAAuE;AACvE,OAAO,EAAE,gBAAgB,EAAgC,MAAM,8BAA8B,CAAC"}

package/dist/esm/lib/bug-report/build.d.ts

@@ -0,0 +1,103 @@
+/**
+ * exportBugReport / describeBugReport — a bug report IS the evidence.
+ *
+ * The usual bug report is a person's memory of a run: "it said the wrong
+ * thing, I think it called the search tool twice". The run itself — the
+ * timeline, the state, the chart, the narrative — is sitting right there in
+ * the process and never leaves it. This turns that around: the report is the
+ * run, packaged, with the prose attached.
+ *
+ * ## Two calls, because consent needs two
+ *
+ *   1. {@link describeBugReport} — "here is what would be sent." A manifest of
+ *      SELECTABLE UNITS: each conversation with its event and turn counts and
+ *      its size, each derived file, the redacted keys by name, the total, and
+ *      a loud warning with trim hints if it is too big.
+ *   2. {@link exportBugReport} — "send exactly these." The reporter's ticked
+ *      unit ids come back as `include`, and the bundle carries only those.
+ *
+ * One call does work for a server-side reporter that has no human in front of
+ * it; the two-call shape is what makes a browser consent dialog possible at
+ * all, because a dialog cannot ask about a blob it has not measured.
+ *
+ * ## What is in the bundle
+ *
+ * | file | what it is |
+ * |---|---|
+ * | `manifest.json` | this manifest — always present, never a selectable unit |
+ * | `recording.json` | the canon `{ snapshot, events, structure }` — drops straight into `observeRecording()` |
+ * | `conversations/<id>.json` | one file per conversation, when there is more than one run |
+ * | `conversation.json` | the readable transcript, derived from the events |
+ * | `narrative.txt` | the narrative recorder's lines, when one was attached |
+ * | `environment.json` | versions + the reporter's prose |
+ *
+ * `environment.json` is deliberately the whole environment: library version,
+ * engine version, Node version, platform and architecture. **No username, no
+ * hostname, no working directory, no environment variables, no file paths.**
+ * A bug report should not be the way an internal directory layout leaves a
+ * company.
+ *
+ * ## Redaction is already done, and the manifest proves it
+ *
+ * The recording arrives ALREADY redacted: footprintjs scrubs at commit time
+ * under the run's `RedactionPolicy`, so a redacted value was never in the
+ * snapshot this reads. Nothing here scrubs anything — it would be too late to
+ * matter and a second policy could only disagree with the first. What this
+ * does do is LIST the redacted keys by name, derived from the placeholders
+ * actually present in the evidence, so a human consenting to the bundle can
+ * see which secrets were protected. A key that is not on that list was not
+ * redacted, and the honest reading of an empty list is "no policy was set" —
+ * which the manifest says in a note.
+ *
+ * @example  The consent flow
+ * ```ts
+ * const manifest = describeBugReport(recording);
+ * // …show manifest.units to the human; they tick some…
+ * const report = exportBugReport(recording, {
+ *   include: ['conv-1', 'file-narrative', 'file-environment'],
+ *   title: 'Agent answered with a stale price',
+ *   stepsToReproduce: '1. ask for the price\n2. update it\n3. ask again',
+ *   expected: 'the new price',
+ *   actual: 'the old one',
+ * });
+ * fs.writeFileSync(report.filename, report.zip);
+ * ```
+ */
+import type { BugReport, BugReportInput, BugReportManifest, DescribeBugReportOptions, ExportBugReportOptions } from './types.js';
+/**
+ * A size a human reads. KB under a megabyte, MB above it — a ceiling reported
+ * as "0.0 MB" teaches nothing, and these strings are the whole content of a
+ * refusal.
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Measure a bug report before anything leaves — the consent step.
+ *
+ * Every unit is "selected" in the manifest this returns, because nothing has
+ * been chosen yet: it is the offer, with sizes and counts attached, for a human
+ * (or a policy) to narrow. Show `units` to the reporter; pass the ids they keep
+ * to {@link exportBugReport} as `include`.
+ *
+ * Cheap enough to call on every dialog open: it serializes the files to measure
+ * them, and throws them away.
+ *
+ * @param input   a recording, a `recordRun` handle, a runner, or an array.
+ * @param options size ceiling and a fixed timestamp.
+ */
+export declare function describeBugReport(input: BugReportInput, options?: DescribeBugReportOptions): BugReportManifest;
+/**
+ * Build the bundle: the manifest, the named files, and a real zip of them.
+ *
+ * @param input   a recording, a `recordRun` handle, a runner, or an array.
+ * @param options the reporter's prose, plus `include` — the ids from
+ *                {@link describeBugReport} that the reporter consented to.
+ *
+ * @throws TypeError naming the unknown id when `include` names a unit that
+ *         does not exist, and naming the available conversations when the
+ *         selection would carry no evidence at all.
+ */
+export declare function exportBugReport(input: BugReportInput, options: ExportBugReportOptions): BugReport;
+/** `2026-08-11-agent-answered-with-a-stale-price.zip`. */
+export declare function bundleFilename(title: string, createdAt: Date): string;
+/** Lower-case, ASCII, hyphenated, bounded — a filename, not a sentence. */
+export declare function slugify(title: string): string;