@gaunt-sloth/core 2.0.0-alpha.24 → 2.0.0-alpha.26

package/dist/core/approvals/grants.d.ts

@@ -0,0 +1,216 @@
+import type { ApprovalEntry, McpToolApprovalEntry, ShellApprovalEntry, ToolApprovalEntry, ToolAnnotationHint } from '#src/config/shell-policy.js';
+import type { ShellApprovalGateNotice } from '#src/config/shell-policy.js';
+import { type EffectiveToolAnnotations, type McpToolApprovalSubject, type ToolApprovalSubject } from '#src/core/approvals/matcher.js';
+import { type ToolApprovalScope } from '#src/core/types.js';
+/**
+ * The scopes a grant can be REMEMBERED at. `once` is absent by construction: it persists nothing,
+ * so it never becomes a grant.
+ */
+export type ApprovalGrantScope = Exclude<ToolApprovalScope, 'once'>;
+/**
+ * §3 — one thing the human granted: the entry that will be matched, plus what the approvals UI
+ * must be able to show about it (*what* was granted, *when*, and *at what scope*).
+ *
+ * The metadata is display only. The `entry` is the whole of what decides.
+ */
+export interface ApprovalGrant {
+    /** §3.1 — the entry, in the one grammar. */
+    entry: ApprovalEntry;
+    /** ISO-8601 instant the grant was made. */
+    grantedAt: string;
+    /** `session` for the life of this runner instance, `always` for the persisted store. */
+    scope: ApprovalGrantScope;
+    /**
+     * §4.7.4 — **the effective annotation set (§4.7.1) this tool grant was made under**, so a later
+     * `tools/list` that weakens it can be seen to have done so ({@link annotationWeakenings}) and the
+     * approvals UI can show what the user believed they were granting.
+     *
+     * Absent on a `shell` grant, which has no annotations, and on a tool grant restored from a file
+     * written before this field existed — in both cases there is nothing to compare, so the grant
+     * simply stands.
+     *
+     * **A private copy, always**, made on the way into the store: an effective set is something the
+     * source may hand out afresh or a caller may hold, and a snapshot that aliased either would let
+     * one grant's record be rewritten by something outside it — which is the same class of bug as a
+     * source returning the shared fail-closed constant instead of a copy.
+     */
+    annotations?: EffectiveToolAnnotations;
+}
+/**
+ * §3.1/§6 — the entry the escalation menu writes for a shell command: **that command, and only
+ * that command**.
+ *
+ * The single place a menu grant's entry is built, so the line the prompt shows the human ("this is
+ * what will be stored") and the line that lands in the store cannot drift apart.
+ */
+export declare function shellGrantEntry(command: string): ShellApprovalEntry;
+/**
+ * §4.7.4/§6 — the entry the escalation menu writes for a **tool** call: the tool's identity, plus
+ * the host where the call carries one.
+ *
+ * The counterpart of {@link shellGrantEntry} and the single place a tool grant's entry is built, so
+ * the line the prompt shows the human and the line that lands in the store cannot drift apart.
+ *
+ * **Identity, never arguments.** A grant recording a full argument signature would never match a
+ * second time — not a narrower grant, a useless one. That is knowingly broader than the shell's
+ * exact-command grant, with one bound: on the shell path §4.6's escape carries the host inside the
+ * command string, so it is host-scoped by construction, while a tool-identity-only grant on a fetch
+ * tool would be every host, forever.
+ *
+ * `server` on an `mcpTool` grant is the user's own `mcpServers` config key (§4.7.5). Nothing a
+ * server declares about its own name participates, and a grant for one server's tool can never be
+ * claimed by another server's same-named tool because the other server sits under a different key.
+ *
+ * **Returns `null` for a call whose server could not be resolved.** {@link UNRESOLVED_MCP_SERVER}
+ * is the empty string, which `server` (`z.string().min(1)`) cannot hold: such an entry would be
+ * written to the file and then silently dropped by the grammar's own validator on the next read, so
+ * the human would be told their approval was remembered when it was not. A call nobody can attribute
+ * to a server is not one anything can remember.
+ */
+export declare function toolGrantEntry(subject: ToolApprovalSubject | McpToolApprovalSubject): ToolApprovalEntry | McpToolApprovalEntry | null;
+/**
+ * §4.7.4 — which hints moved in the weakening direction between the set a grant was made under and
+ * the set that holds now. Empty means the grant still stands.
+ *
+ * **Only the four booleans are compared, so schema and description changes invalidate nothing** —
+ * not by a rule that exempts them, but because a snapshot is four booleans and a description is not
+ * one of them. Descriptions churn on every server release, and a grant that dissolved on churn
+ * would teach users that grants are worthless.
+ *
+ * **An untrusted server's declaration change likewise invalidates nothing**, again by construction:
+ * §4.7.1 makes an untrusted server's effective set the constant fail-closed default, so both sides
+ * of this comparison are that constant however the server re-declares itself. Only a **trusted**
+ * server can move an effective value — which is exactly where invalidation matters, since the
+ * trusted server is the one whose rug-pull would otherwise ride an existing grant.
+ */
+export declare function annotationWeakenings(snapshot: EffectiveToolAnnotations, current: EffectiveToolAnnotations): ToolAnnotationHint[];
+/**
+ * §4.7.1/§4.7.4 — **can WITHDRAWING trust in this hint weaken an effective set?**
+ *
+ * Withdrawing trust pushes a hint back to its MCP fail-closed default, and every weakening move
+ * *ends* at that default, so the answer does not depend on what a server declared: it is exactly
+ * whether the move (not-the-default → the default) is one of {@link WEAKENING_MOVES}. Three of the
+ * four hints answer yes — `readOnlyHint`, `openWorldHint` and `destructiveHint`, whose fail-closed
+ * default is `true`, so a server whose `destructiveHint: false` was believed becomes destructive
+ * again the moment it is not. `idempotentHint` is the only one that answers no, because no
+ * weakening move names it.
+ *
+ * **It asks {@link annotationWeakenings} rather than restating the table.** A second statement of
+ * which moves weaken is how a warning comes to describe a rule the gate no longer has — which
+ * matters most here, since this decides whether the human is told their saved approvals are about
+ * to be withdrawn.
+ */
+export declare function trustWithdrawalWeakens(hint: ToolAnnotationHint): boolean;
+/**
+ * §4.7.4 — the notice a weakened grant is removed with. **It names the tool, the server and the
+ * hint that moved**, because the human approved a tool *as annotated*: a tool that re-annotates
+ * itself into a more dangerous shape is a different proposition wearing the same name, and a notice
+ * that did not say which name changed would be indistinguishable from the gate malfunctioning.
+ *
+ * It takes the **entry** rather than the call's subject, so it describes the grant that was actually
+ * withdrawn — including its host bound, where it had one. One call may withdraw both a host-bound
+ * grant and a tool-only one, and two notices that could not be told apart would be worse than one.
+ * The entry is rendered by {@link describeApprovalEntry}, the same one-liner every other provenance
+ * message uses.
+ */
+export declare function describeWeakenedGrant(entry: ApprovalEntry, weakened: readonly ToolAnnotationHint[], snapshot: EffectiveToolAnnotations, current: EffectiveToolAnnotations): string;
+/**
+ * A set of grants with entry-identity semantics. Pure data + membership: it holds what the human
+ * granted and answers *is this the same grant*, never *does this grant cover that command*.
+ */
+export declare class ApprovalGrantStore {
+    private readonly grants;
+    constructor(initial?: readonly ApprovalGrant[]);
+    /**
+     * Add a grant. Returns whether it was new — an identical entry is not stored twice.
+     *
+     * The {@link ApprovalGrant.annotations} snapshot is **copied on the way in**, so what the store
+     * holds is private to this grant whatever the caller passed: the effective set may be a live
+     * object the caller keeps, or (were a source ever to regress) the shared fail-closed constant, and
+     * a store aliasing either would let one grant's record be rewritten from outside it. Copying here
+     * rather than at each call site makes that structural instead of a habit every caller must keep.
+     */
+    add(grant: ApprovalGrant): boolean;
+    /**
+     * The grant stored under this entry's identity, or `undefined`.
+     *
+     * **Identity, never a match decision** — the same de-duplication question {@link add} asks. It
+     * answers *"is this the same grant"*, and whether a grant covers a call remains
+     * `resolveApprovalRules`'s alone.
+     */
+    find(entry: ApprovalEntry): ApprovalGrant | undefined;
+    /**
+     * Drop the grant stored under this entry's identity. Returns whether one was there.
+     *
+     * §4.7.4's invalidation is a **removal** rather than a skip, and that is load-bearing: {@link add}
+     * de-duplicates by entry identity, so a grant left in place while being ignored would silently
+     * swallow the human's re-approval of the same tool — the grant would appear to be re-made and the
+     * stale snapshot would keep invalidating it.
+     */
+    remove(entry: ApprovalEntry): boolean;
+    /** Every grant, in the order they were made. */
+    list(): ApprovalGrant[];
+    /** Just the entries, for handing to the matcher as one of its rule lists. */
+    entries(): ApprovalEntry[];
+    /** How many grants are held. */
+    size(): number;
+}
+/** Optional seams for {@link PersistedApprovalGrants}. */
+export interface PersistedApprovalGrantsOptions {
+    /**
+     * Where the v1→v2 migration notice goes — the established {@link ShellApprovalGateNotice} shape
+     * the runner forwards to `statusUpdate`. Absent means the migration happens silently, which is
+     * why the runner always passes one.
+     */
+    onNotice?: (notice: ShellApprovalGateNotice) => void;
+}
+/**
+ * The persisted (`always`) grant store, backed by a JSON file whose path is injected (the runner
+ * resolves it via fileUtils → `.gsloth/.gsloth-settings/shell-allowlist.json`) so tests can point it
+ * at a temp dir.
+ *
+ * ## The v1 migration, and the direction it goes
+ *
+ * The shipped v1 file held `prefixes: string[]` — classified command PREFIXES, so a stored
+ * `npm test` also auto-approved `npm test --watch`. Each prefix migrates to an **`exact` entry for
+ * the same string**, with **one** notice naming the file.
+ *
+ * That narrows what the file grants, on purpose: a v1 prefix was broader than what the human was
+ * actually shown when they answered the prompt, so narrowing it costs at worst a re-prompt and
+ * never an execution — the direction every ambiguity in this design resolves. The migrated file is
+ * rewritten as v2 immediately, so the notice is a one-time event rather than a per-session one; a
+ * write that fails (read-only checkout) is not fatal — the grants are in force for this session and
+ * the notice simply appears again next time.
+ */
+export declare class PersistedApprovalGrants {
+    private readonly store;
+    private readonly filePath;
+    constructor(filePath: string, options?: PersistedApprovalGrantsOptions);
+    private static load;
+    /** Each v1 prefix → an `exact` entry for the same string, with ONE notice naming the file. */
+    private static migrateFromV1;
+    /** Every grant. */
+    list(): ApprovalGrant[];
+    /** Just the entries, for handing to the matcher as one of its rule lists. */
+    entries(): ApprovalEntry[];
+    /** How many grants are persisted. */
+    size(): number;
+    /** Add a grant and persist the whole store. A duplicate entry rewrites nothing. */
+    add(grant: ApprovalGrant): void;
+    /** The grant held under this entry's identity, or `undefined`. */
+    find(entry: ApprovalEntry): ApprovalGrant | undefined;
+    /**
+     * Drop the grant held under this entry's identity and rewrite the file. Returns whether one was
+     * there.
+     *
+     * The write is what makes §4.7.4's invalidation a one-time event: a removal held only in memory
+     * would be undone by the next session reloading the same stale snapshot, so the user would be
+     * told their grant had been withdrawn once per session, forever.
+     */
+    remove(entry: ApprovalEntry): boolean;
+    /**
+     * Write the file. Never throws: the grants are already in force for this session, and a
+     * read-only checkout must not end a run over a bookkeeping write.
+     */
+    private tryPersist;
+}