@reclaimprotocol/agent 0.1.18 → 0.1.21

package/src/provider/to-version.ts

@@ -105,6 +105,13 @@ const CONTEXT_PARAM_RE = /\{\{context\.([A-Za-z_][A-Za-z0-9_]*)\}\}/g
  * recipe can never reference a context value the Builder doesn't require.
  * Returns undefined when nothing references context (the field is optional).
  * Authors can refine types/descriptions in the version editor.
+ *
+ * A SECRET-named context param (see `classifyParamName`) is NOT rejected here
+ * even when it's templated into the URL/geoLocation — write-redaction can
+ * still hide it there, up to `secretUrlCharBudget` characters (summed across
+ * every such value in that URL). Whether it actually fits is only knowable
+ * once a real value exists, so that check runs at verification time
+ * (`verify/run.ts`), against the consumer's actual supplied value — not here.
  */
 export function deriveRequiredContext(
 	providers: ReclaimProvider[],
@@ -114,7 +121,11 @@ export function deriveRequiredContext(
 	} = {},
 ): CreateProviderVersionRequest['requiredContext'] {
 	const parts: string[] = []
-	for(const p of [...providers, ...(injection.allowedJsRequests ?? [])]) {
+	for(const p of providers) {
+		parts.push(p.url, p.body ?? '')
+	}
+
+	for(const p of injection.allowedJsRequests ?? []) {
 		parts.push(p.url, p.body ?? '')
 	}
 

package/lib/authoring/find.d.ts

@@ -1,3 +0,0 @@
-import { type RegisteredTool } from '../tools/registry.ts';
-import { type ResolveBackend } from './util.ts';
-export declare function findTool(resolveBackend: ResolveBackend): RegisteredTool;

package/lib/authoring/find.js

@@ -1,54 +0,0 @@
-/**
- * `find_requests_containing` — search captured responses for any encoding of a
- * value and rank the requests that return it. Authored once as a plain
- * {@link RegisteredTool}; the MCP and cloud loop each pass their own backend
- * resolver (see tools.ts / mcp/tools/agent/shared.ts). Server-side: response
- * bodies stay here, only metadata + a short snippet leave.
- */
-import { normalizeCandidates } from "../provider/normalize.js";
-import { defineTool } from "../tools/registry.js";
-import { objectSchema, publicRequest } from "./util.js";
-export function findTool(resolveBackend) {
-    return defineTool({
-        name: 'find_requests_containing',
-        description: 'Search captured responses for any encoding of `value` (raw, '
-            + 'URL/JSON/HTML-escaped, …). Returns a ranked candidate list with '
-            + 'the matched variant, score, and a short snippet — used to locate '
-            + 'the request that returns a target. Server-side; bodies stay here.',
-        inputSchema: objectSchema({ value: { type: 'string' }, limit: { type: 'number' } }, ['value']),
-    }, async (args) => {
-        const backend = resolveBackend(args);
-        const variants = normalizeCandidates(String(args.value));
-        const ranked = [];
-        for (const r of backend.capture.requests.values()) {
-            if (!r.responseBody) {
-                continue;
-            }
-            let hit;
-            for (const v of variants) {
-                const idx = r.responseBody.indexOf(v);
-                if (idx >= 0) {
-                    const start = Math.max(0, idx - 40);
-                    const end = Math.min(r.responseBody.length, idx + v.length + 40);
-                    hit = { snippet: r.responseBody.slice(start, end), variant: v };
-                    break;
-                }
-            }
-            if (!hit) {
-                continue;
-            }
-            // Prefer JSON responses + smaller bodies (likely API endpoints).
-            const score = (r.contentType.includes('json') ? 10 : 0)
-                + Math.max(0, 5 - Math.log10(Math.max(r.size, 1)));
-            ranked.push({
-                ...publicRequest(r),
-                matchedVariant: hit.variant,
-                snippet: hit.snippet,
-                score,
-            });
-        }
-        ranked.sort((a, b) => b.score - a.score);
-        const limit = Number(args.limit) || 10;
-        return { candidates: ranked.slice(0, limit) };
-    });
-}

package/lib/authoring/propose.d.ts

@@ -1,3 +0,0 @@
-import { type RegisteredTool } from '../tools/registry.ts';
-import { type ResolveBackend } from './util.ts';
-export declare function proposeTool(resolveBackend: ResolveBackend): RegisteredTool;

package/lib/authoring/propose.js

@@ -1,109 +0,0 @@
-/**
- * `propose_provider` — draft a provider (recipe + captured secrets) from ONE
- * captured request, one match + redaction per target value. Authored once as a
- * plain {@link RegisteredTool}; hosts pass their own backend resolver. The
- * draft (recipe + real secret header values) is held server-side under an
- * opaque `draftId`; the result carries only the secret-free provider.
- */
-import { draftProvider } from "../provider/draft.js";
-import { OPRF_MAX_BYTES } from "../provider/matcher.js";
-import { verificationWarnings } from "../provider/verification-checks.js";
-import { defineTool } from "../tools/registry.js";
-import { objectSchema } from "./util.js";
-export function proposeTool(resolveBackend) {
-    return defineTool({
-        name: 'propose_provider',
-        description: 'Draft a provider from ONE captured request. Pass `targets` (an '
-            + 'array): one entry per value to extract, each with its `value` '
-            + '(verbatim) and a distinct `name` (its param). The provider gets '
-            + 'one match + redaction per target. Returns a draftId + recipe '
-            + '(never secrets). Prefer a SINGLE request holding ALL values. '
-            + 'Single-value shorthand: `target` + `name`. Per-target `hash` '
-            + 'OPRF-hashes that value.',
-        inputSchema: objectSchema({
-            requestId: { type: 'string' },
-            name: { type: 'string' },
-            targets: {
-                type: 'array',
-                items: {
-                    type: 'object',
-                    properties: {
-                        value: { type: 'string' },
-                        name: { type: 'string' },
-                        hash: {
-                            type: 'string',
-                            enum: ['oprf-raw', 'oprf', 'oprf-mpc'],
-                        },
-                    },
-                    required: ['value', 'name'],
-                },
-            },
-            target: { type: 'string' },
-            hash: { type: 'string', enum: ['oprf-raw', 'oprf', 'oprf-mpc'] },
-        }, ['requestId', 'name']),
-    }, async (args) => {
-        const backend = resolveBackend(args);
-        const requestId = String(args.requestId);
-        const providerName = String(args.name);
-        const defaultHash = args.hash;
-        // Explicit multi-value `targets`, else the single `target` shorthand.
-        const raw = Array.isArray(args.targets) ? args.targets : [];
-        const targets = raw.length
-            ? raw.map((t) => {
-                const o = t;
-                return {
-                    value: String(o.value),
-                    name: String(o.name),
-                    ...(typeof o.hash === 'string'
-                        ? { hash: o.hash }
-                        : {}),
-                };
-            })
-            : typeof args.target === 'string'
-                ? [{
-                        value: args.target,
-                        name: providerName,
-                        ...(defaultHash ? { hash: defaultHash } : {}),
-                    }]
-                : [];
-        if (targets.length === 0) {
-            throw new Error('propose_provider needs a `target` value or a non-empty '
-                + '`targets` array');
-        }
-        for (const t of targets) {
-            if ((t.hash ?? defaultHash) !== undefined
-                && t.value.length > OPRF_MAX_BYTES) {
-                throw new Error(`OPRF caps hashed values at ${OPRF_MAX_BYTES} bytes; got `
-                    + `${t.value.length}-byte "${t.value}". Use a tighter `
-                    + 'target or drop `hash`.');
-            }
-        }
-        const captured = backend.capture.requests.get(requestId);
-        if (!captured) {
-            throw new Error(`no captured request ${requestId}`);
-        }
-        if (!captured.responseBody) {
-            throw new Error(`request body unavailable for ${requestId}`);
-        }
-        const { provider, secretRefs, extractions } = draftProvider(captured, targets, providerName, defaultHash);
-        // Materialize the real secret header values for later replay/prove;
-        // they stay in the server-side draft, never in this result.
-        const secrets = {};
-        for (const ref of secretRefs) {
-            const real = captured.requestHeaders[ref.name];
-            if (real !== undefined) {
-                secrets[ref.name] = real;
-            }
-        }
-        const draftId = backend.drafts.put({
-            provider, secretRefs, secrets, requestId, extractions,
-        });
-        const warnings = verificationWarnings(provider);
-        return {
-            draftId,
-            provider,
-            secretRefs,
-            ...(warnings.length ? { verificationWarnings: warnings } : {}),
-        };
-    });
-}

package/lib/authoring/replay.d.ts

@@ -1,10 +0,0 @@
-/**
- * `replay_request` — validate a drafted recipe before proving: confirm its
- * selectors extract the target(s), and (with `withoutSecrets`) that the
- * endpoint is auth-bound. Authored once as a plain {@link RegisteredTool}; the
- * backend does the actual replay (MCP re-runs locally, cloud re-issues in the
- * TEE pod).
- */
-import { type RegisteredTool } from '../tools/registry.ts';
-import { type ResolveBackend } from './util.ts';
-export declare function replayTool(resolveBackend: ResolveBackend): RegisteredTool;

package/lib/authoring/replay.js

@@ -1,34 +0,0 @@
-/**
- * `replay_request` — validate a drafted recipe before proving: confirm its
- * selectors extract the target(s), and (with `withoutSecrets`) that the
- * endpoint is auth-bound. Authored once as a plain {@link RegisteredTool}; the
- * backend does the actual replay (MCP re-runs locally, cloud re-issues in the
- * TEE pod).
- */
-import { defineTool } from "../tools/registry.js";
-import { objectSchema } from "./util.js";
-export function replayTool(resolveBackend) {
-    return defineTool({
-        name: 'replay_request',
-        description: 'Validate the drafted recipe before proving — confirm its selectors '
-            + 'extract the target value. Returns diagnostics; run before '
-            + 'proving. Set `withoutSecrets: true` for the AUTH-BOUND check: it '
-            + 're-issues the request with NO secrets/cookies (an anonymous '
-            + 'visitor). If the values still extract (valid:true), the endpoint '
-            + 'is PUBLIC and the proof would not bind to the user — reject it '
-            + 'and find an auth-bound request instead.',
-        inputSchema: objectSchema({
-            draftId: { type: 'string' },
-            withoutSecrets: { type: 'boolean' },
-        }, ['draftId']),
-    }, async (args) => {
-        const backend = resolveBackend(args);
-        const draft = backend.drafts.get(String(args.draftId));
-        if (!draft) {
-            throw new Error(`no draft ${String(args.draftId)}`);
-        }
-        return backend.replay(draft, {
-            withoutSecrets: Boolean(args.withoutSecrets),
-        });
-    });
-}

package/lib/cli/args.d.ts

@@ -1,14 +0,0 @@
-export declare function parseCliArgs(argv: string[]): {
-    values: {
-        [longOption: string]: string | boolean | undefined;
-    } & {
-        'base-url'?: string | boolean | undefined;
-        token?: string | boolean | undefined;
-        param?: (string | boolean)[] | undefined;
-        query?: (string | boolean)[] | undefined;
-        body?: string | boolean | undefined;
-        help?: string | boolean | undefined;
-        version?: string | boolean | undefined;
-    };
-    positionals: string[];
-};

package/lib/cli/args.js

@@ -1,19 +0,0 @@
-import { parseArgs as nodeParseArgs } from 'node:util';
-// Placeholder. Final shape decided once the backend openapi stabilises and
-// the CLI surface is fleshed out (see AGENTS.md → "CLI").
-export function parseCliArgs(argv) {
-    return nodeParseArgs({
-        args: argv,
-        options: {
-            'base-url': { type: 'string' },
-            token: { type: 'string' },
-            param: { type: 'string', multiple: true },
-            query: { type: 'string', multiple: true },
-            body: { type: 'string' },
-            help: { type: 'boolean', short: 'h' },
-            version: { type: 'boolean', short: 'v' },
-        },
-        allowPositionals: true,
-        strict: false,
-    });
-}

package/lib/cli/commands.d.ts

@@ -1 +0,0 @@
-export declare function run(argv: string[]): Promise<void>;

package/lib/cli/commands.js

@@ -1,19 +0,0 @@
-import { notImplemented } from '@hapi/boom';
-import { DESCRIPTION, NAME, VERSION } from "../pkg.js";
-import { parseCliArgs } from "./args.js";
-// Entry point for the `reclaim` bin. Placeholder until backend openapi
-// finalises — `--version` and `--help` work; everything else throws.
-export async function run(argv) {
-    const parsed = parseCliArgs(argv);
-    if (parsed.values['version']) {
-        process.stdout.write(`${NAME} ${VERSION}\n`);
-        return;
-    }
-    if (parsed.values['help']) {
-        process.stdout.write(`${NAME} ${VERSION}\n${DESCRIPTION}\n\n` +
-            'Usage: reclaim call <OperationId> ' +
-            '[--param k=v] [--query k=v] [--body <json>]\n');
-        return;
-    }
-    throw notImplemented('reclaim CLI: pending @reclaimprotocol/app spec finalisation');
-}

package/lib/cli.d.ts

@@ -1 +0,0 @@
-export {};

package/lib/cli.js

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-import { run } from "./cli/commands.js";
-import { LOGGER } from "./logger.js";
-run(process.argv.slice(2)).catch((err) => {
-    LOGGER.error({ err }, 'cli failed');
-    process.exitCode = 1;
-});

package/lib/mcp/credentials/authenticate.d.ts

@@ -1,3 +0,0 @@
-import type { ReclaimClient } from '@reclaimprotocol/client';
-import { type RegisteredTool } from '../server.ts';
-export declare function authenticateTool(client: ReclaimClient): RegisteredTool;

package/lib/mcp/credentials/authenticate.js

@@ -1,108 +0,0 @@
-import { defineTool } from "../server.js";
-import { writeSession } from "./session-cache.js";
-export function authenticateTool(client) {
-    return defineTool({
-        name: 'reclaim_authenticate',
-        description: 'Authorize the CLI / MCP to make authenticated API calls by having ' +
-            'the user sign in on the dashboard. Two steps:\n\n' +
-            'Step 1 — call with no arguments. Returns a `code` and `attachUrl`. ' +
-            'Tell the user to open the URL, sign in, and authorize.\n\n' +
-            'Step 2 — once the user says they have authorized, call again ' +
-            'with the same `code` from step 1 to check if confirmed. ' +
-            'Returns `LINKED` with a 2-day bearer token when confirmed, ' +
-            '`PENDING` if not yet, or `EXPIRED` if too long has passed.\n\n' +
-            'The token is cached in ~/.reclaim/session.json automatically.\n\n' +
-            'To then link a credential to an org (needed only to use it ' +
-            'for verification in production), use the token with the ' +
-            'generated tools: `list_orgs` → `link_credential` with the ' +
-            "credential's `address` and the target `orgId`.",
-        inputSchema: {
-            type: 'object',
-            properties: {
-                code: {
-                    type: 'string',
-                    pattern: '^[A-HJ-NP-Z2-9]{5}$',
-                    description: '5-character code from a previous step-1 call. ' +
-                        'When provided, checks whether the user has ' +
-                        'confirmed that session instead of opening a new one.',
-                },
-            },
-        },
-    }, async (args) => {
-        // Step 2: check an existing session
-        if (args.code) {
-            return checkSession(client, args.code);
-        }
-        // Step 1: open a new auth-only session
-        const sessionResult = (await client.call('CreateAttachSession'));
-        const session = sessionResult.data;
-        return {
-            status: 'PENDING',
-            code: session.code,
-            attachUrl: session.attachUrl,
-            expiresAt: session.expiresAt,
-            instructions: `Open ${session.attachUrl} in your browser, sign in, and click ` +
-                '"Authorize this device". ' +
-                'Once done, call authenticate again with code: ' +
-                `"${session.code}" to confirm.`,
-        };
-    });
-}
-async function checkSession(client, code) {
-    let session;
-    try {
-        const sessionResult = (await client.call('GetAttachSession', {
-            params: { code }
-        }));
-        session = sessionResult.data;
-    }
-    catch (err) {
-        const status = err.status;
-        if (status === 404) {
-            return {
-                status: 'NOT_FOUND',
-                hint: 'Session not found — it may have expired (15-min window). ' +
-                    'Call authenticate without a code to start a new session.',
-            };
-        }
-        throw new Error(`Failed to check session: ${err.message}`);
-    }
-    if (session.status === 'LINKED') {
-        const token = session.token?.trim();
-        if (token) {
-            writeSession({
-                token,
-                expiresAt: new Date(Date.now() + 2 * 24 * 60 * 60 * 1000).toISOString(),
-            });
-            client.setToken(token);
-            return {
-                status: 'LINKED',
-                token,
-                note: 'Token cached in ~/.reclaim/session.json and active now.',
-            };
-        }
-        return {
-            status: 'LINKED_NO_TOKEN',
-            hint: 'Session confirmed but no token issued. ' +
-                'Restart the backend (npm run dev) and try again.',
-        };
-    }
-    if (session.status === 'EXPIRED') {
-        return {
-            status: 'EXPIRED',
-            hint: 'Session expired (15-min window passed). ' +
-                'Call authenticate without a code to start a new session.',
-        };
-    }
-    // Still PENDING
-    return {
-        status: 'PENDING',
-        code: session.code,
-        attachUrl: session.attachUrl,
-        hint: 'Session is still waiting. ' +
-            `Make sure you opened ${session.attachUrl}, ` +
-            'signed in, and clicked "Authorize this device". ' +
-            `Call authenticate again with code: "${session.code}"` +
-            ' once you have done so.',
-    };
-}

package/lib/mcp/credentials/build.d.ts

@@ -1,5 +0,0 @@
-import type { ReclaimClient } from '@reclaimprotocol/client';
-import type { RegisteredTool } from '../server.ts';
-/** Credential lifecycle tools — build the flat list of RegisteredTool
- *  entries. Mirrors buildAgentTools() in mcp/register.ts. */
-export declare function buildCredentialTools(client: ReclaimClient): RegisteredTool[];

package/lib/mcp/credentials/build.js

@@ -1,18 +0,0 @@
-import { authenticateTool } from "./authenticate.js";
-import { importTool } from "./import.js";
-import { issueTool } from "./issue.js";
-import { listCachedTool } from "./list-cached.js";
-import { resolveOwnerKeyTool } from "./resolve-owner-key.js";
-import { statusTool } from "./status.js";
-/** Credential lifecycle tools — build the flat list of RegisteredTool
- *  entries. Mirrors buildAgentTools() in mcp/register.ts. */
-export function buildCredentialTools(client) {
-    return [
-        authenticateTool(client),
-        listCachedTool(),
-        resolveOwnerKeyTool(),
-        issueTool(),
-        importTool(),
-        statusTool(client),
-    ];
-}

package/lib/mcp/credentials/cache.d.ts

@@ -1,70 +0,0 @@
-export type CachedCredential = {
-    address: string;
-    privateKey: string;
-    label?: string;
-    orgId?: string;
-    createdAt: string;
-    /** Project dir where this credential was first created. */
-    createdIn: string;
-    /** All project dirs this credential has been used in ("used by"). */
-    projectDirs: string[];
-};
-type CacheFile = {
-    version: 1;
-    credentials: CachedCredential[];
-};
-/**
- * Read the cache file. Returns an empty doc if missing. Surface-level
- * shape errors fall back to empty — we'd rather lose the cache than
- * crash the CLI on a corrupted file the user can re-create.
- */
-export declare function readCache(): CacheFile;
-/**
- * Write the cache file with strict permissions. The directory gets
- * `0700` and the file `0600` — same posture as `~/.ssh`. We rewrite
- * the whole doc each save; the file is tiny and the alternative
- * (append-only) loses our ability to deduplicate `projectDirs`.
- */
-export declare function writeCache(doc: CacheFile): void;
-/**
- * Upsert a credential entry. If a row already exists for `address`,
- * we merge the new `projectDirs` into the existing list, refresh
- * mutable fields, and keep the original `createdAt` / `createdIn`
- * (backfilling `createdIn` from the new entry when an old row lacks it).
- */
-export declare function upsertCredential(entry: CachedCredential): CachedCredential;
-/** Look up a cached credential by address. Case-insensitive. */
-export declare function findCached(address: string): CachedCredential | undefined;
-export type SuggestionReason = 'createdIn' | 'usedIn' | 'newest';
-export type CredentialSuggestion = {
-    credential: CachedCredential;
-    reason: SuggestionReason;
-};
-/**
- * Pick the best cached credential for `dir`. Ranking tiers:
- *   1. created in `dir`           (reason: 'createdIn')
- *   2. previously used in `dir`   (reason: 'usedIn')
- *   3. most recently created      (reason: 'newest')
- * Within every tier, newest `createdAt` wins; address ascending is the
- * final deterministic tie-break. Returns undefined only on an empty cache.
- *
- * Pass a pre-read `creds` array to avoid a redundant `readCache()` (and to
- * rank against the same snapshot the caller already holds).
- */
-export declare function suggestCredentialForDir(dir: string, creds?: CachedCredential[]): CredentialSuggestion | undefined;
-/**
- * Resolve the private key to sign attestor proofs with (the claim
- * "owner"). Reuses the app credential rather than a dedicated key — for
- * build-time test proofs the developer is both the app and the proof
- * owner, and the owner identity is immaterial to whether the provider's
- * matching works.
- *
- * The owner is chosen up front (see the `resolve_owner_key` tool) and
- * passed by `address`; this just fetches the matching private key:
- *   - the `RECLAIM_PRIVATE_KEY` env / project `.env` key, if it derives
- *     to `address` (the dev pinned it), else
- *   - the cached credential with that address.
- * Returns undefined when no key for `address` is known.
- */
-export declare function resolveOwnerPrivateKey(address: string): string | undefined;
-export {};

package/lib/mcp/credentials/cache.js

@@ -1,131 +0,0 @@
-import { deriveFromPrivateKey } from '@reclaimprotocol/client';
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
-import { credentialsCachePath, findProjectRoot, reclaimHomeDirPath } from "../../paths.js";
-import { readPrivateKeyFromEnvFile } from "./env-file.js";
-const EMPTY = { version: 1, credentials: [] };
-/**
- * Read the cache file. Returns an empty doc if missing. Surface-level
- * shape errors fall back to empty — we'd rather lose the cache than
- * crash the CLI on a corrupted file the user can re-create.
- */
-export function readCache() {
-    const path = credentialsCachePath();
-    if (!existsSync(path)) {
-        return { ...EMPTY };
-    }
-    try {
-        const raw = readFileSync(path, 'utf8');
-        const parsed = JSON.parse(raw);
-        if (parsed.version !== 1 || !Array.isArray(parsed.credentials)) {
-            return { ...EMPTY };
-        }
-        return parsed;
-    }
-    catch {
-        return { ...EMPTY };
-    }
-}
-/**
- * Write the cache file with strict permissions. The directory gets
- * `0700` and the file `0600` — same posture as `~/.ssh`. We rewrite
- * the whole doc each save; the file is tiny and the alternative
- * (append-only) loses our ability to deduplicate `projectDirs`.
- */
-export function writeCache(doc) {
-    const dir = reclaimHomeDirPath();
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
-    }
-    chmodSync(dir, 0o700);
-    const path = credentialsCachePath();
-    writeFileSync(path, JSON.stringify(doc, null, 2) + '\n', { mode: 0o600 });
-    chmodSync(path, 0o600);
-}
-/**
- * Upsert a credential entry. If a row already exists for `address`,
- * we merge the new `projectDirs` into the existing list, refresh
- * mutable fields, and keep the original `createdAt` / `createdIn`
- * (backfilling `createdIn` from the new entry when an old row lacks it).
- */
-export function upsertCredential(entry) {
-    const doc = readCache();
-    const idx = doc.credentials.findIndex((c) => c.address === entry.address.toLowerCase());
-    const merged = {
-        ...entry,
-        address: entry.address.toLowerCase(),
-        projectDirs: Array.from(new Set([
-            ...(doc.credentials[idx]?.projectDirs ?? []),
-            ...entry.projectDirs,
-        ])),
-        createdAt: doc.credentials[idx]?.createdAt ?? entry.createdAt,
-        createdIn: doc.credentials[idx]?.createdIn ?? entry.createdIn,
-    };
-    if (idx >= 0) {
-        doc.credentials[idx] = merged;
-    }
-    else {
-        doc.credentials.unshift(merged);
-    }
-    writeCache(doc);
-    return merged;
-}
-/** Look up a cached credential by address. Case-insensitive. */
-export function findCached(address) {
-    const doc = readCache();
-    const lc = address.toLowerCase();
-    return doc.credentials.find((c) => c.address === lc);
-}
-/**
- * Pick the best cached credential for `dir`. Ranking tiers:
- *   1. created in `dir`           (reason: 'createdIn')
- *   2. previously used in `dir`   (reason: 'usedIn')
- *   3. most recently created      (reason: 'newest')
- * Within every tier, newest `createdAt` wins; address ascending is the
- * final deterministic tie-break. Returns undefined only on an empty cache.
- *
- * Pass a pre-read `creds` array to avoid a redundant `readCache()` (and to
- * rank against the same snapshot the caller already holds).
- */
-export function suggestCredentialForDir(dir, creds = readCache().credentials) {
-    if (creds.length === 0) {
-        return undefined;
-    }
-    const byNewest = (a, b) => {
-        return (b.createdAt ?? '').localeCompare(a.createdAt ?? '') ||
-            a.address.localeCompare(b.address);
-    };
-    const createdHere = creds.filter((c) => c.createdIn === dir).sort(byNewest);
-    if (createdHere[0]) {
-        return { credential: createdHere[0], reason: 'createdIn' };
-    }
-    const usedHere = creds
-        .filter((c) => c.projectDirs.includes(dir))
-        .sort(byNewest);
-    if (usedHere[0]) {
-        return { credential: usedHere[0], reason: 'usedIn' };
-    }
-    return { credential: [...creds].sort(byNewest)[0], reason: 'newest' };
-}
-/**
- * Resolve the private key to sign attestor proofs with (the claim
- * "owner"). Reuses the app credential rather than a dedicated key — for
- * build-time test proofs the developer is both the app and the proof
- * owner, and the owner identity is immaterial to whether the provider's
- * matching works.
- *
- * The owner is chosen up front (see the `resolve_owner_key` tool) and
- * passed by `address`; this just fetches the matching private key:
- *   - the `RECLAIM_PRIVATE_KEY` env / project `.env` key, if it derives
- *     to `address` (the dev pinned it), else
- *   - the cached credential with that address.
- * Returns undefined when no key for `address` is known.
- */
-export function resolveOwnerPrivateKey(address) {
-    const target = address.toLowerCase();
-    const envKey = process.env.RECLAIM_PRIVATE_KEY ??
-        readPrivateKeyFromEnvFile(findProjectRoot(process.cwd()));
-    if (envKey && deriveFromPrivateKey(envKey).address === target) {
-        return envKey;
-    }
-    return findCached(target)?.privateKey;
-}