agentfootprint 9.7.0 → 9.9.0

package/dist/adapters/observability/githubDeviceSignIn.js

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.githubDeviceSignIn = void 0;
+/** 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.
+ */
+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 };
+}
+exports.githubDeviceSignIn = githubDeviceSignIn;
+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/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/adapters/identity/vault.d.ts

@@ -0,0 +1,146 @@
+/**
+ * vaultCredentials — a {@link CredentialProvider} over a HashiCorp-Vault-compatible
+ * KV v2 secret store, spoken as plain HTTP.
+ *
+ *   import { vaultCredentials } from 'agentfootprint/security';
+ *
+ *   const credentials = vaultCredentials({
+ *     address: 'https://vault.internal:8200',   // https, or say `allowHttp` out loud
+ *     mount: 'secret',                          // KV v2 mount, default 'secret'
+ *     paths: { github: 'ci/github' },           // service → path INSIDE the mount
+ *   });                                         // token: VAULT_TOKEN, or `token`
+ *
+ * Zero dependencies and no SDK: one `GET` per resolution through the runtime's
+ * own `fetch`. Vault's HTTP API is small, stable and the thing every
+ * Vault-compatible store (OpenBao, and the Vault-API modes of several managed
+ * stores) implements — so the adapter that speaks HTTP works against more
+ * backends than the adapter that imports one vendor's client.
+ *
+ * ## V1 is deliberately one shape, and says so by name
+ *
+ * | Axis | V1 | Anything else |
+ * |---|---|---|
+ * | Auth | a **token** (`token` option, else `VAULT_TOKEN`) | AppRole / Kubernetes / JWT / AWS IAM login are **refused by name**, naming the option that would carry them |
+ * | Secret engine | **KV v2** (`<mount>/data/<path>`, the `data.data` envelope) | a KV v1 mount is refused by name once the response shape gives it away |
+ * | Leases / renewal | **none** — every `getCredential` re-reads the secret | a lease-aware provider is a different object, and the library's model since 9.7.0 is re-resolve-per-call |
+ *
+ * That is not modesty, it is the honest edge: an auth method the author cannot
+ * exercise against a real cluster would be a guess wearing an adapter's clothes.
+ * Each refusal names the option it would arrive on, so "tell us your auth shape"
+ * is a field report rather than an issue title.
+ *
+ * ## Field → credential kind
+ *
+ * A KV v2 read returns `{ data: { data: { …your fields… }, metadata: {…} } }`.
+ * The inner object is mapped to a {@link Credential} by the FIRST rule that
+ * matches, so a secret written the ordinary way needs no configuration:
+ *
+ * | Fields present | Becomes | Header it applies |
+ * |---|---|---|
+ * | `token` | `bearer(token)` | `authorization: Bearer …` |
+ * | `api_key` \| `apiKey` \| `key` | `apiKey(value, header ?? 'x-api-key')` | that header |
+ * | `username` + `password` | `basic(username, password)` | `authorization: Basic …` |
+ * | `headers` (an object of strings) | `headers(map)` | all of them |
+ *
+ * A secret matching none of them is refused — naming the PATH and the four
+ * shapes, never the secret. `toCredential` is the seam for a shop whose fields
+ * are named otherwise; it sees the secret and returns a `Credential`, and
+ * returning `undefined` falls back to the table above.
+ *
+ * ## Secrecy (the 8.6.0 two-clause law, applied here)
+ *
+ * A thrown message reaches the model as a tool result AND rides
+ * `agentfootprint.credential.failed`. So every error this adapter raises names
+ * **the service, the path and the HTTP status, and nothing from the response
+ * body or the token**. Nothing here logs, and no secret value, no `X-Vault-Token`
+ * header and no field name from the payload appears in any message it can throw
+ * — pinned by a grep-shaped test over every failure path. The credential it
+ * returns hides its own secret fields (non-enumerable) and carries `toHeaders`,
+ * so `structuredClone` rejects it and it cannot enter tracked scope by accident.
+ *
+ * @example Dev → prod is the same two lines
+ * ```ts
+ * // dev
+ * const credentials = staticTokens({ github: 'ghp_dev_xxx' });
+ * // prod — the tool code does not change
+ * const credentials = vaultCredentials({ address: process.env.VAULT_ADDR! });
+ * Agent.create({ provider, model, credentials }).build();
+ * ```
+ */
+import type { Credential, CredentialProvider } from '../../identity/types.js';
+/** The base options every form shares. */
+interface VaultCredentialsBase {
+    /** Vault's base URL, e.g. `https://vault.internal:8200` — **required**, and
+     *  **https** unless {@link VaultCredentialsBase.allowHttp} says otherwise. No
+     *  `VAULT_ADDR` fallback: an agent that silently picks up an address from the
+     *  environment is an agent that reads a different vault when the environment
+     *  changes under it. Name it. */
+    readonly address: string;
+    /** The Vault token. Falls back to `VAULT_TOKEN` (the variable every Vault
+     *  tool already sets). This is a secret: it is sent as `X-Vault-Token` and
+     *  appears in no message this adapter can throw. */
+    readonly token?: string;
+    /** Auth method. **`'token'` is the only one V1 implements.** Anything else is
+     *  refused at construction, by name, with what it would take — see
+     *  {@link vaultCredentials}. */
+    readonly auth?: 'token';
+    /** KV v2 mount point. Default `'secret'` (Vault's own default for the KV v2
+     *  engine). The read URL is `<address>/v1/<mount>/data/<path>`. */
+    readonly mount?: string;
+    /** Vault Enterprise / HCP namespace, sent as `X-Vault-Namespace`. Omit for
+     *  open-source Vault and OpenBao, which have no namespaces. */
+    readonly namespace?: string;
+    /** Map the secret's fields to a {@link Credential} yourself. Returns
+     *  `undefined` to fall back to the built-in table (`token` / `api_key` /
+     *  `username`+`password` / `headers`). The seam for a shop whose field names
+     *  are its own — and the reason this adapter does not need an option per
+     *  spelling. **Never log or return the fields from here**; they are the
+     *  secret. */
+    readonly toCredential?: (secret: Readonly<Record<string, unknown>>, service: string) => Credential | undefined;
+    /** Header name for the `api_key` shape when the secret does not carry its own
+     *  `header` field. Default `'x-api-key'`. */
+    readonly apiKeyHeader?: string;
+    /** Request timeout in ms. Default 5000 — a credential resolution sits in
+     *  front of a tool call, so a hung vault must fail rather than hang a run. */
+    readonly timeoutMs?: number;
+    /** Allow a plain-`http://` address. **Refused unless you set this**, because
+     *  the Vault token travels in a request header: over plaintext HTTP, anyone
+     *  on the path reads a token that can usually read every secret it can reach.
+     *  Set it only for a loopback dev server (`http://127.0.0.1:8200`). */
+    readonly allowHttp?: boolean;
+    /** Stable provider id (default `'vault'`). Shows up in "which provider vended
+     *  this". */
+    readonly id?: string;
+    /** Test seam — inject `fetch`. Bypasses the network entirely. */
+    readonly _fetch?: typeof fetch;
+}
+/**
+ * How a `service` becomes a path inside the mount. Three arms, and they
+ * EXCLUDE each other — two spellings of one rule can disagree, so the type
+ * refuses the pair and so does the constructor.
+ */
+type VaultPathMapping = {
+    /** `service → path inside the mount`, the {@link staticTokens} shape one
+     *  level up: the same literal map, holding a path instead of a token. An
+     *  unknown service is refused by name, listing the known ones. */
+    readonly paths: Readonly<Record<string, string>>;
+    readonly resolve?: never;
+} | {
+    /** `service → path`, computed. Return `undefined` to refuse a service.
+     *  For the convention-driven shop: ``(s) => `agents/${s}` ``. */
+    readonly resolve: (service: string) => string | undefined;
+    readonly paths?: never;
+} | {
+    /** Neither: the **service id IS the path** under the mount, so
+     *  `service: 'github'` reads `<mount>/data/github`. */
+    readonly paths?: undefined;
+    readonly resolve?: undefined;
+};
+export type VaultCredentialsOptions = VaultCredentialsBase & VaultPathMapping;
+/**
+ * Build a {@link CredentialProvider} that reads KV v2 secrets from a
+ * Vault-compatible store. See {@link VaultCredentialsOptions} for the
+ * per-option contract and this module's docstring for the V1 boundary.
+ */
+export declare function vaultCredentials(options: VaultCredentialsOptions): CredentialProvider;
+export {};