glirastes 0.4.0 → 0.5.0

package/dist/cjs/server/adapters/nextjs/approval-binding.js

@@ -0,0 +1,724 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApprovalExecutionRefusedError = exports.ApprovalHistoryError = exports.ApprovalSecretMissingError = exports.MAX_RUNNABLE_APPROVALS_PER_REQUEST = exports.DEFAULT_MEMORY_APPROVAL_STORE_ENTRIES_PER_SCOPE = exports.DEFAULT_MEMORY_APPROVAL_STORE_ENTRIES = exports.APPROVAL_SECRET_ENV = exports.MAX_APPROVAL_MAX_AGE_MS = exports.DEFAULT_APPROVAL_MAX_AGE_MS = void 0;
+exports.assertApprovalMaxAge = assertApprovalMaxAge;
+exports.createMemoryApprovalStore = createMemoryApprovalStore;
+exports.defaultApprovalStore = defaultApprovalStore;
+exports.canonicalJson = canonicalJson;
+exports.approvalScope = approvalScope;
+exports.createApprovalBinder = createApprovalBinder;
+exports.resolveApprovalBinder = resolveApprovalBinder;
+exports.bindApprovalRequests = bindApprovalRequests;
+exports.assertUnambiguousToolHistory = assertUnambiguousToolHistory;
+exports.enforceApprovalBindings = enforceApprovalBindings;
+exports.createApprovalExecutionGate = createApprovalExecutionGate;
+exports.gateApprovalTools = gateApprovalTools;
+const node_crypto_1 = require("node:crypto");
+const engine_js_1 = require("../../../runtime/ai-sdk/engine.js");
+/**
+ * Approvals the server asked for, bound to the call they were asked for.
+ *
+ * When a tool call needs the user's approval, the AI SDK ends the turn with an
+ * approval request. The browser sends the whole history back with the answer,
+ * and the SDK then runs the approved call with the tool name and input *from
+ * that history*, which the client wrote. Without a binding, a forged history
+ * runs any tool with any input, and an old approved history runs it again.
+ *
+ * The binding is the approval id itself. The AI SDK sends the id to the
+ * client, keeps it through `addToolApprovalResponse`, returns it in the
+ * history and passes it on through `convertToModelMessages`; no other field of
+ * an approval request survives that round trip (the stream chunk has only
+ * `approvalId` and `toolCallId`). The id has the form
+ *
+ *   glirastes-approval.v1.<issuedAtMs>.<expiresAtMs>.<nonce>.<mac>
+ *
+ * where `mac` is an HMAC-SHA-256, keyed with a server secret, over the issue
+ * time, the expiry, the nonce, the scope, the tool call id, the tool name and
+ * the canonical JSON of the input. The expiry is the issuing handler's
+ * decision and is signed, so a handler with a longer `approvalMaxAgeMs` that
+ * shares the secret cannot accept what the issuer would refuse; the verifier
+ * applies its own maximum age on top. (The format gained the expiry before
+ * 0.5.0 was published, which is why it is still `v1`.)
+ */
+exports.DEFAULT_APPROVAL_MAX_AGE_MS = 15 * 60_000;
+/** The longest `approvalMaxAgeMs` accepted: 24 hours. */
+exports.MAX_APPROVAL_MAX_AGE_MS = 24 * 60 * 60_000;
+/**
+ * Throws unless `value` is a usable maximum approval age: a whole number of milliseconds above 0
+ * and at most 24 hours. A fractional age would sign an expiry the id format cannot carry.
+ */
+function assertApprovalMaxAge(value) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0 || value > exports.MAX_APPROVAL_MAX_AGE_MS) {
+        throw new RangeError(`approvalMaxAgeMs must be a whole number above 0 and at most ${exports.MAX_APPROVAL_MAX_AGE_MS} (24 hours)`);
+    }
+}
+exports.APPROVAL_SECRET_ENV = 'GLIRASTES_APPROVAL_SECRET';
+const ID_PREFIX = 'glirastes-approval.v1.';
+const MIN_SECRET_LENGTH = 16;
+/** Clock differences between processes sharing a secret. */
+const CLOCK_SKEW_MS = 60_000;
+/**
+ * Default size of the in-process single-use store (a few MB at most). With
+ * the per-scope default, at least 100 scopes must use up their quota before
+ * the store is full for everyone.
+ */
+exports.DEFAULT_MEMORY_APPROVAL_STORE_ENTRIES = 20_000;
+/** Default share of the in-process store one scope may hold. */
+exports.DEFAULT_MEMORY_APPROVAL_STORE_ENTRIES_PER_SCOPE = 200;
+/** Approved calls that can run in one request; more is refused (`too_many_approvals`). */
+exports.MAX_RUNNABLE_APPROVALS_PER_REQUEST = 32;
+/**
+ * A single-use store in this process's memory. Each id is kept until its
+ * approval has expired (plus the allowed clock skew), after which it can no
+ * longer verify anyway. The store is bounded: when it holds `maxEntries` live
+ * ids, or the approval's scope holds `maxEntriesPerScope`, `consume` throws,
+ * which the handler reports as `approval_store_unavailable`, rather than
+ * forgetting a live id and letting it run again. The per-scope quota keeps
+ * one scope from filling the store for everyone else. The scope is the one
+ * `ApprovalStore` describes: the managed tenant and subject, else
+ * `approvalScope`, else a key derived from the request's credentials
+ * (`caller:<hmac>`), else `''`, which all requests without credentials share.
+ * A caller who varies their credentials gets a fresh quota per value; the
+ * global `maxEntries` still bounds them, and only consumed genuine approvals
+ * create entries.
+ *
+ * It protects one process only. Instances behind a load balancer each have
+ * their own memory, so an approved history replayed to another instance runs
+ * there again unless they share an `approvalStore`.
+ */
+function createMemoryApprovalStore(options = {}) {
+    const maxEntries = options.maxEntries ?? exports.DEFAULT_MEMORY_APPROVAL_STORE_ENTRIES;
+    const maxEntriesPerScope = options.maxEntriesPerScope ?? exports.DEFAULT_MEMORY_APPROVAL_STORE_ENTRIES_PER_SCOPE;
+    const now = options.now ?? Date.now;
+    const entries = new Map();
+    const perScope = new Map();
+    const remove = (id, scope) => {
+        entries.delete(id);
+        const left = (perScope.get(scope) ?? 1) - 1;
+        if (left > 0)
+            perScope.set(scope, left);
+        else
+            perScope.delete(scope);
+    };
+    const purge = (at) => {
+        for (const [id, entry] of entries)
+            if (entry.keepUntil <= at)
+                remove(id, entry.scope);
+    };
+    const full = (scope) => entries.size >= maxEntries || (perScope.get(scope) ?? 0) >= maxEntriesPerScope;
+    return {
+        consume: (approvalId, expiresAtMs, context) => {
+            const at = now();
+            const scope = context?.scope ?? '';
+            const existing = entries.get(approvalId);
+            if (existing && existing.keepUntil > at)
+                return false;
+            if (existing)
+                remove(approvalId, existing.scope);
+            if (full(scope))
+                purge(at);
+            if (entries.size >= maxEntries)
+                throw new Error('The in-process approval store is full');
+            if ((perScope.get(scope) ?? 0) >= maxEntriesPerScope) {
+                throw new Error('The in-process approval store quota of this scope is used up');
+            }
+            entries.set(approvalId, { keepUntil: expiresAtMs + CLOCK_SKEW_MS, scope });
+            perScope.set(scope, (perScope.get(scope) ?? 0) + 1);
+            return true;
+        },
+    };
+}
+let processApprovalStore;
+/** The in-process store every handler of this process shares when none is configured. */
+function defaultApprovalStore() {
+    processApprovalStore ??= createMemoryApprovalStore();
+    return processApprovalStore;
+}
+class ApprovalSecretMissingError extends Error {
+    code = 'approval_secret_missing';
+    constructor() {
+        super(`Tools that ask for approval are registered, but no approval secret is configured. `
+            + `Set ${exports.APPROVAL_SECRET_ENV} (at least ${MIN_SECRET_LENGTH} characters, the same on every instance) `
+            + `or pass approvalSecret to createAiChatHandler. Approvals are refused in production without it.`);
+        this.name = 'ApprovalSecretMissingError';
+    }
+}
+exports.ApprovalSecretMissingError = ApprovalSecretMissingError;
+const NONCE_BYTES = 16;
+const MAC_BYTES = 32;
+/** A decimal without sign or leading zeros, as `String(Date.now())` writes it. */
+const CANONICAL_TIME = /^(?:0|[1-9]\d{0,15})$/;
+function isCanonicalBase64Url(text, bytes) {
+    if (!/^[A-Za-z0-9_-]+$/.test(text))
+        return false;
+    const decoded = Buffer.from(text, 'base64url');
+    return decoded.length === bytes && decoded.toString('base64url') === text;
+}
+/**
+ * JSON with sorted keys, so an input hashes the same after any JSON round
+ * trip. A non-finite number (`JSON.parse` turns `1e999` into `Infinity`)
+ * throws a RangeError: `JSON.stringify` would write it as `null`, so an
+ * approval for `null` would also hold for it.
+ */
+function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value)) ?? 'null';
+}
+function sortKeys(value) {
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+        throw new RangeError('An approval input must contain only finite numbers');
+    }
+    if (Array.isArray(value))
+        return value.map((item) => sortKeys(item === undefined ? null : item));
+    if (typeof value !== 'object' || value === null)
+        return value;
+    // No prototype: an own `__proto__` key (JSON.parse creates one) must stay a
+    // key. On a plain object the assignment would set the prototype and the key
+    // would drop out of the JSON, so two different inputs would share a MAC.
+    const sorted = Object.create(null);
+    for (const key of Object.keys(value).sort()) {
+        const entry = value[key];
+        if (entry !== undefined)
+            sorted[key] = sortKeys(entry);
+    }
+    return sorted;
+}
+/**
+ * The binder scope of a principal. Tenant and subject are encoded as a JSON
+ * array, so ids that contain a separator cannot make two principals share a
+ * scope (`acme:ops` + `alice` and `acme` + `ops:alice`).
+ */
+function approvalScope(principal) {
+    return principal ? JSON.stringify([principal.tenantId, principal.subjectId]) : '';
+}
+function createApprovalBinder(options) {
+    if (typeof options.secret !== 'string' || options.secret.length < MIN_SECRET_LENGTH) {
+        throw new Error(`The approval secret must be a string of at least ${MIN_SECRET_LENGTH} characters`);
+    }
+    const maxAgeMs = options.maxAgeMs ?? exports.DEFAULT_APPROVAL_MAX_AGE_MS;
+    assertApprovalMaxAge(maxAgeMs);
+    const now = options.now ?? Date.now;
+    const scope = options.scope ?? '';
+    const mac = (issuedAt, expiresAt, nonce, call) => (0, node_crypto_1.createHmac)('sha256', options.secret)
+        .update(JSON.stringify(['v1', issuedAt, expiresAt, nonce, scope, call.toolCallId, call.toolName, canonicalJson(call.input)]))
+        .digest();
+    return {
+        maxAgeMs,
+        callerQuotaKey: (credentials) => `caller:${(0, node_crypto_1.createHmac)('sha256', options.secret)
+            .update('glirastes-approval-quota-key\0')
+            .update(credentials)
+            .digest('base64url')}`,
+        issue: (call) => {
+            const issued = now();
+            const issuedAt = String(issued);
+            const expiresAt = String(issued + maxAgeMs);
+            const nonce = (0, node_crypto_1.randomBytes)(NONCE_BYTES).toString('base64url');
+            return `${ID_PREFIX}${issuedAt}.${expiresAt}.${nonce}.${mac(issuedAt, expiresAt, nonce, call).toString('base64url')}`;
+        },
+        verify: (call) => {
+            const notIssued = { ok: false, code: 'approval_not_issued' };
+            if (typeof call.approvalId !== 'string' || !call.approvalId.startsWith(ID_PREFIX))
+                return notIssued;
+            const [issuedAt, expiresAt, nonce, presented, ...rest] = call.approvalId.slice(ID_PREFIX.length).split('.');
+            // Every segment must be spelled exactly as `issue` spells it: Node's
+            // base64url decoder accepts padding, stray characters and changed low
+            // bits, which would give one approval many ids.
+            if (!issuedAt || !expiresAt || !nonce || !presented || rest.length > 0)
+                return notIssued;
+            if (!CANONICAL_TIME.test(issuedAt) || !CANONICAL_TIME.test(expiresAt))
+                return notIssued;
+            if (!isCanonicalBase64Url(nonce, NONCE_BYTES) || !isCanonicalBase64Url(presented, MAC_BYTES))
+                return notIssued;
+            let expected;
+            try {
+                expected = mac(issuedAt, expiresAt, nonce, call);
+            }
+            catch {
+                return notIssued;
+            }
+            const actual = Buffer.from(presented, 'base64url');
+            if (actual.length !== expected.length || !(0, node_crypto_1.timingSafeEqual)(actual, expected))
+                return notIssued;
+            const at = now();
+            if (at - Number(issuedAt) < -CLOCK_SKEW_MS)
+                return notIssued;
+            // The issuer's signed expiry, and this handler's own maximum age.
+            if (at > Math.min(Number(expiresAt), Number(issuedAt) + maxAgeMs))
+                return { ok: false, code: 'approval_expired' };
+            return {
+                ok: true,
+                expiresAtMs: Number(expiresAt),
+                key: `${ID_PREFIX}${issuedAt}.${expiresAt}.${nonce}.${expected.toString('base64url')}`,
+            };
+        },
+    };
+}
+let processSecret;
+let warnedAboutProcessSecret = false;
+/**
+ * The binder of a request. The secret is the configured one, else
+ * `GLIRASTES_APPROVAL_SECRET`. Without one, and when approvals can occur, a
+ * production process refuses to serve them (`ApprovalSecretMissingError`);
+ * any other process derives a random secret that lives as long as the process
+ * and warns once. Approvals then do not survive a restart or reach another
+ * instance, which is why they are refused in production.
+ */
+function resolveApprovalBinder(options) {
+    const env = options.env ?? (typeof process !== 'undefined' ? process.env : {});
+    const configured = options.secret || env[exports.APPROVAL_SECRET_ENV] || undefined;
+    const common = { scope: options.scope, maxAgeMs: options.maxAgeMs, now: options.now };
+    if (configured)
+        return createApprovalBinder({ secret: configured, ...common });
+    if (options.hasApprovalTools && env.NODE_ENV === 'production')
+        throw new ApprovalSecretMissingError();
+    if (options.hasApprovalTools && !warnedAboutProcessSecret) {
+        warnedAboutProcessSecret = true;
+        (options.warn ?? ((message) => console.warn(message)))(`[glirastes] No ${exports.APPROVAL_SECRET_ENV} is set. Approvals are signed with a random secret that lives as long as `
+            + `this process, so they do not survive a restart and do not work across instances. `
+            + `Production refuses to serve approvals without the secret.`);
+    }
+    processSecret ??= (0, node_crypto_1.randomBytes)(32).toString('base64url');
+    return createApprovalBinder({ secret: processSecret, ...common });
+}
+/**
+ * Gives every approval request of a UI message stream an id bound to the
+ * call it announced (tool name and input come from the preceding
+ * `tool-input-available` chunk, which is also what the client stores).
+ */
+function bindApprovalRequests(stream, binder) {
+    const calls = new Map();
+    return stream.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            const record = chunk;
+            if (record.type === 'tool-input-available' && typeof record.toolCallId === 'string') {
+                calls.set(record.toolCallId, { toolName: String(record.toolName), input: record.input });
+            }
+            if (record.type === 'tool-approval-request' && typeof record.toolCallId === 'string') {
+                const announced = calls.get(record.toolCallId);
+                if (announced) {
+                    let approvalId;
+                    try {
+                        approvalId = binder.issue({ toolCallId: record.toolCallId, ...announced });
+                    }
+                    catch {
+                        // An input that cannot be hashed (a non-finite number) gets no
+                        // bound id; the AI SDK's own id never verifies, so the approval
+                        // can be answered but never runs.
+                    }
+                    if (approvalId) {
+                        controller.enqueue({ ...chunk, approvalId });
+                        return;
+                    }
+                }
+            }
+            controller.enqueue(chunk);
+        },
+    }));
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const RESULT_STATES = new Set(['output-available', 'output-error', 'output-denied']);
+/** A UI tool part as the AI SDK recognizes one (`isToolUIPart`). */
+function isToolPart(part) {
+    return typeof part.type === 'string' && (part.type.startsWith('tool-') || part.type === 'dynamic-tool');
+}
+function toolNameOf(part) {
+    if (part.type === 'dynamic-tool')
+        return typeof part.toolName === 'string' && part.toolName ? part.toolName : undefined;
+    return typeof part.type === 'string' && part.type.startsWith('tool-') ? part.type.slice('tool-'.length) : undefined;
+}
+/**
+ * The input of the tool call that `convertToModelMessages` writes for a part,
+ * which is what the AI SDK would execute: for `output-error` it falls back to
+ * `rawInput`.
+ */
+function modelInputOf(part) {
+    return part.state === 'output-error' && part.input == null && 'rawInput' in part ? part.rawInput : part.input;
+}
+/** A history the handler refuses as a whole (HTTP 400) instead of repairing it. */
+class ApprovalHistoryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ApprovalHistoryError';
+    }
+}
+exports.ApprovalHistoryError = ApprovalHistoryError;
+/**
+ * Refuses a history that the AI SDK could read in more than one way.
+ *
+ * - Every tool part has a string tool call id, and a dynamic tool part a
+ *   tool name that is a non-empty string (`tool_part_malformed`): the AI SDK
+ *   converts any value and looks the tool up with it.
+ * - A tool call id may belong to one tool part only, in the whole history
+ *   (`duplicate_tool_call_id`). The AI SDK maps an approval response to a
+ *   tool call by the tool call id alone (`collectToolApprovals` keeps the last
+ *   tool call of an id, and the model message sanitizer keeps the first one of
+ *   a message), so a second part with the same id can lend its tool name and
+ *   input to the approval of the other one.
+ * - An approval id may belong to one tool part only, in the whole history
+ *   (`duplicate_approval_id`). Every part with an `approval` becomes an
+ *   approval request with that id, and `collectToolApprovals` keeps the last
+ *   request of an id, so a copy of a genuine id on another part would take
+ *   over the genuine part's approved answer.
+ * - An `approval` is an object with a non-empty string `id`, and its
+ *   `approved`, when set, is a boolean (`approval_malformed`). The AI SDK
+ *   turns any value other than `null` / `undefined` into an approval response
+ *   and treats a truthy one as approved.
+ *
+ * The AI SDK's own client never writes any of these: its UI message reducer
+ * (`updateToolPart` / `updateDynamicToolPart` in `processUIMessageStream`)
+ * updates the existing part of a tool call id in place, also for a
+ * provider-executed tool whose result arrives later, an approval continuation
+ * goes on in the same assistant message, and every approval request carries
+ * its own id. There is therefore no legitimate shape with a repeated id, and
+ * none is allowed.
+ */
+function assertUnambiguousToolHistory(messages) {
+    const toolCallIds = new Set();
+    const approvalIds = new Set();
+    for (const message of messages) {
+        if (!isRecord(message) || !Array.isArray(message.parts))
+            continue;
+        for (const part of message.parts) {
+            if (!isRecord(part) || !isToolPart(part))
+                continue;
+            if (!toolNameOf(part)) {
+                throw new ApprovalHistoryError('tool_part_malformed', 'A dynamic tool part has no tool name.');
+            }
+            if (typeof part.toolCallId !== 'string') {
+                throw new ApprovalHistoryError('tool_part_malformed', 'A tool part has no tool call id.');
+            }
+            if (toolCallIds.has(part.toolCallId)) {
+                throw new ApprovalHistoryError('duplicate_tool_call_id', 'A tool call id appears in more than one tool part.');
+            }
+            toolCallIds.add(part.toolCallId);
+            if (part.approval !== undefined && part.approval !== null) {
+                const approval = part.approval;
+                if (!isRecord(approval)) {
+                    throw new ApprovalHistoryError('approval_malformed', 'A tool part carries an approval that is not an object.');
+                }
+                if (typeof approval.id !== 'string' || approval.id === '') {
+                    throw new ApprovalHistoryError('approval_malformed', 'An approval has no id.');
+                }
+                if (approval.approved !== undefined && approval.approved !== null && typeof approval.approved !== 'boolean') {
+                    throw new ApprovalHistoryError('approval_malformed', 'approval.approved must be true or false.');
+                }
+                if (approvalIds.has(approval.id)) {
+                    throw new ApprovalHistoryError('duplicate_approval_id', 'An approval id appears in more than one tool part.');
+                }
+                approvalIds.add(approval.id);
+            }
+        }
+    }
+}
+/**
+ * Checks, before anything runs, every tool part of the request history that
+ * carries an approval, whatever its state, its answer and whether or not the
+ * provider executed it. The history must first pass
+ * `assertUnambiguousToolHistory` (this function calls it and throws
+ * `ApprovalHistoryError`).
+ *
+ * - An approved part that the AI SDK can run in this request (no result yet,
+ *   or provider-executed, and in the last block of a last assistant message,
+ *   see `runnableBlockOf`) needs an approval id issued for exactly this tool
+ *   call id, tool name and input, not older than the maximum age, not used
+ *   before in this history and not consumed before by the store (with the
+ *   request's scope). More than `MAX_RUNNABLE_APPROVALS_PER_REQUEST` of them
+ *   refuse the request (`too_many_approvals`) before any is consumed. A part that
+ *   fails is rewritten to `output-denied` with the code as its reason, so the
+ *   model messages carry a denied result for it and the AI SDK runs nothing.
+ *   The request continues: the model sees the denial and answers.
+ * - Every other approved part without a result (an earlier block, an
+ *   earlier message, a history with any trailing message) is rewritten to
+ *   `output-denied` with the reason `approval_not_runnable` (or
+ *   `approval_not_issued` with an id that verifies for nothing, when its id
+ *   was not issued for it). It is neither consumed nor handed to the gate.
+ * - Every other part with an approval (one that holds its result, an
+ *   unanswered request, a refusal) needs an id issued for this tool call id,
+ *   tool name and input; age and use do not count. A part that fails loses
+ *   its approval (an `output-denied` part, which the AI SDK cannot convert
+ *   without one, gets an id of its own that verifies for nothing). Such parts
+ *   are not refused, because an honest history holds them after a secret
+ *   rotation, a restart of a process without a configured secret, or from
+ *   0.4.0; they run nothing either way.
+ *
+ * The invariants this establishes, together with `assertUnambiguousToolHistory`:
+ *
+ * 1. Every approved part without a result that is left in the history is in
+ *    `verified`, so it passed binding, age, single use and the cap. Every
+ *    other approved part either holds its result or is denied. The AI SDK
+ *    runs an approved call only from a part without a result, so it can run
+ *    only verified calls, whatever it treats as the last step; this does not
+ *    depend on predicting which shapes it runs (tested against the installed
+ *    `ai` for the shapes the reviews found).
+ * 2. Every approval id left in the history belongs to exactly one tool part
+ *    and was issued for that part's tool call id, tool name and model input
+ *    (the input `convertToModelMessages` writes, `rawInput` for an
+ *    `output-error` part without input). The AI SDK pairs an approved answer
+ *    with a call by approval id → the one request with that id, emitted from
+ *    the same part → its tool call id, which is unique → the tool call
+ *    emitted from that same part. So an approved answer can only ever pair
+ *    with the call its id was issued for.
+ */
+async function enforceApprovalBindings(messages, options) {
+    if (options.localToolNames)
+        messages = withoutLocalProviderExecuted(messages, options.localToolNames);
+    assertUnambiguousToolHistory(messages);
+    const lastBlock = runnableBlockOf(messages);
+    const runnableCount = [...lastBlock].filter((part) => isRunnableApproval(part)).length;
+    if (runnableCount > exports.MAX_RUNNABLE_APPROVALS_PER_REQUEST) {
+        throw new ApprovalHistoryError('too_many_approvals', `At most ${exports.MAX_RUNNABLE_APPROVALS_PER_REQUEST} approved calls can run in one request.`);
+    }
+    const denied = [];
+    const verified = [];
+    const usedIds = new Set();
+    const next = [];
+    for (const message of messages) {
+        if (!isRecord(message) || !Array.isArray(message.parts)) {
+            next.push(message);
+            continue;
+        }
+        let changed = false;
+        const parts = [];
+        for (const part of message.parts) {
+            const toolName = isRecord(part) && isToolPart(part) ? toolNameOf(part) : undefined;
+            const approval = isRecord(part) && isRecord(part.approval) ? part.approval : undefined;
+            if (!toolName || !approval) {
+                parts.push(part);
+                continue;
+            }
+            const record = part;
+            const toolCallId = record.toolCallId;
+            const approvalId = approval.id;
+            const input = modelInputOf(record);
+            const runnable = lastBlock.has(part) && isRunnableApproval(record);
+            const code = runnable
+                ? await denialCode({ input, toolName, toolCallId, approvalId, usedIds, ...options })
+                : bindingCode({ input, toolName, toolCallId, approvalId, binder: options.binder })
+                    ?? (isUnsettledApproval(record) ? 'approval_not_runnable' : undefined);
+            if (!code) {
+                if (runnable && record.providerExecuted !== true)
+                    verified.push({ toolCallId, toolName, input });
+                parts.push(part);
+                continue;
+            }
+            changed = true;
+            if (runnable) {
+                denied.push({ toolCallId, code });
+                parts.push({ ...record, state: 'output-denied', approval: { id: approvalId, approved: false, reason: code } });
+                continue;
+            }
+            if (isUnsettledApproval(record)) {
+                // Approved, no result, and not checked for age and single use: denied,
+                // so the AI SDK cannot run it, whatever shape the history has.
+                denied.push({ toolCallId, code });
+                const id = code === 'approval_not_issued' ? `glirastes-approval-unbound.${toolCallId}` : approvalId;
+                parts.push({ ...record, state: 'output-denied', approval: { id, approved: false, reason: code } });
+                continue;
+            }
+            if (approval.approved === true)
+                denied.push({ toolCallId, code });
+            if (record.state === 'output-denied') {
+                parts.push({ ...record, approval: { ...approval, id: `glirastes-approval-unbound.${toolCallId}`, approved: false } });
+            }
+            else {
+                const { approval: _dropped, ...withoutApproval } = record;
+                parts.push(withoutApproval);
+            }
+        }
+        next.push(changed ? { ...message, parts } : message);
+    }
+    return { messages: next, denied, verified };
+}
+/** The history with `providerExecuted` removed from every part of a local tool. */
+function withoutLocalProviderExecuted(messages, local) {
+    return messages.map((message) => {
+        if (!isRecord(message) || !Array.isArray(message.parts))
+            return message;
+        let changed = false;
+        const parts = message.parts.map((part) => {
+            if (!isRecord(part) || !isToolPart(part) || !('providerExecuted' in part))
+                return part;
+            const toolName = toolNameOf(part);
+            if (toolName === undefined || !local.has(toolName))
+                return part;
+            changed = true;
+            const { providerExecuted: _ignored, ...rest } = part;
+            return rest;
+        });
+        return changed ? { ...message, parts } : message;
+    });
+}
+/** An approved part without a result of any kind: the AI SDK may run it. */
+function isUnsettledApproval(part) {
+    return isRecord(part.approval) && part.approval.approved === true && !RESULT_STATES.has(String(part.state));
+}
+/** An approved part without its result: the AI SDK runs it if it is in the runnable block. */
+function isRunnableApproval(part) {
+    if (!isRecord(part) || !isToolPart(part) || !isRecord(part.approval) || part.approval.approved !== true)
+        return false;
+    return !(RESULT_STATES.has(String(part.state)) && part.providerExecuted !== true);
+}
+/**
+ * The parts whose approvals the AI SDK can run in this request.
+ * `collectToolApprovals` reads only the last model message, and only when it
+ * is a tool message; `convertToModelMessages` writes that message for the
+ * last block (the parts after the last `step-start`) of the last UI message,
+ * when that message is the assistant's. Only these are checked in full,
+ * consumed and handed to the execution gate; an approved part without a
+ * result anywhere else is denied (`approval_not_runnable`), so a shape in
+ * which the AI SDK would still run it cannot skip age and single use.
+ */
+function runnableBlockOf(messages) {
+    const last = messages.at(-1);
+    if (!isRecord(last) || last.role !== 'assistant' || !Array.isArray(last.parts))
+        return new Set();
+    const parts = last.parts;
+    let start = 0;
+    parts.forEach((part, index) => {
+        if (isRecord(part) && part.type === 'step-start')
+            start = index + 1;
+    });
+    return new Set(parts.slice(start));
+}
+function bindingCode(args) {
+    const verified = args.binder.verify({
+        approvalId: args.approvalId,
+        toolCallId: args.toolCallId,
+        toolName: args.toolName,
+        input: args.input,
+    });
+    // Only the binding counts here: an executed call may be older than the maximum age.
+    return !verified.ok && verified.code === 'approval_not_issued' ? 'approval_not_issued' : undefined;
+}
+async function denialCode(args) {
+    const verified = args.binder.verify({
+        approvalId: args.approvalId,
+        toolCallId: args.toolCallId,
+        toolName: args.toolName,
+        input: args.input,
+    });
+    if (!verified.ok)
+        return verified.code;
+    if (args.usedIds.has(verified.key))
+        return 'approval_already_used';
+    args.usedIds.add(verified.key);
+    if (args.store) {
+        try {
+            if (!(await args.store.consume(verified.key, verified.expiresAtMs, { scope: args.scope ?? '' })))
+                return 'approval_already_used';
+        }
+        catch {
+            return 'approval_store_unavailable';
+        }
+    }
+    return undefined;
+}
+class ApprovalExecutionRefusedError extends Error {
+    code;
+    constructor(code, toolName) {
+        super(`${code}: the call of "${toolName}" was not approved for this tool call and input`);
+        this.code = code;
+        this.name = 'ApprovalExecutionRefusedError';
+    }
+}
+exports.ApprovalExecutionRefusedError = ApprovalExecutionRefusedError;
+/**
+ * The second layer of the binding, checked where the tool executes.
+ *
+ * The AI SDK never executes a call within the run whose `needsApproval`
+ * answered true: it emits the approval request and the run ends (traced in
+ * `ai` 6.0: `runToolsTransformation` stops at `isApprovalNeeded`, and only
+ * `collectToolApprovals` on the next request's history executes an approved
+ * call). So a gated tool executes only
+ *
+ * - for an approval this request verified, with exactly its tool call id,
+ *   tool name and canonical input, once; or
+ * - for a live call whose `needsApproval` this run answered with false.
+ *
+ * Everything else, including a call whose `needsApproval` was never asked,
+ * is refused.
+ */
+function createApprovalExecutionGate(verified) {
+    const approvals = new Map(verified.map((entry) => [entry.toolCallId, {
+            toolName: entry.toolName,
+            input: canonicalJson(entry.input),
+        }]));
+    const executed = new Set();
+    const liveWithoutApproval = new Map();
+    return {
+        recordDecision: ({ toolName, toolCallId, needed }) => {
+            if (typeof toolCallId !== 'string' || approvals.has(toolCallId))
+                return;
+            if (needed)
+                liveWithoutApproval.delete(toolCallId);
+            else
+                liveWithoutApproval.set(toolCallId, toolName);
+        },
+        authorize: ({ toolName, toolCallId, input }) => {
+            if (typeof toolCallId !== 'string')
+                throw new ApprovalExecutionRefusedError('approval_not_verified', toolName);
+            const approval = approvals.get(toolCallId);
+            if (approval) {
+                if (executed.has(toolCallId))
+                    throw new ApprovalExecutionRefusedError('approval_already_used', toolName);
+                if (approval.toolName !== toolName || approval.input !== canonicalOrUndefined(input)) {
+                    throw new ApprovalExecutionRefusedError('approval_not_verified', toolName);
+                }
+                executed.add(toolCallId);
+                return;
+            }
+            if (liveWithoutApproval.get(toolCallId) === toolName) {
+                liveWithoutApproval.delete(toolCallId);
+                return;
+            }
+            throw new ApprovalExecutionRefusedError('approval_not_verified', toolName);
+        },
+    };
+}
+function canonicalOrUndefined(value) {
+    try {
+        return canonicalJson(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Puts the gate on every tool for which `isGated` says it can ask for
+ * approval. The gated tool records its own `needsApproval` answers and checks
+ * the gate in its own `execute`, so a stream handler that builds AI SDK tools
+ * from these objects itself is held to the gate as well; `createAiSdkTools`
+ * finds the gate on the tool and checks it with the input before validation.
+ */
+function gateApprovalTools(tools, gate, isGated) {
+    const gated = {};
+    for (const [toolName, raw] of Object.entries(tools)) {
+        const tool = raw;
+        if (typeof raw !== 'object' || raw === null || typeof tool.execute !== 'function' || !isGated(toolName, tool)) {
+            gated[toolName] = raw;
+            continue;
+        }
+        const original = tool.needsApproval;
+        const execute = tool.execute;
+        gated[toolName] = {
+            ...tool,
+            [engine_js_1.AI_SDK_APPROVAL_GATE]: gate,
+            needsApproval: async (input, options) => {
+                const needed = typeof original === 'function'
+                    ? Boolean(await original(input, options))
+                    : original === true;
+                gate.recordDecision({ toolName, toolCallId: options?.toolCallId, needed });
+                return needed;
+            },
+            execute: async (input, options) => {
+                const passed = options?.[engine_js_1.AI_SDK_APPROVAL_GATE_PASSED];
+                if (passed !== gate) {
+                    gate.authorize({ toolName, toolCallId: options?.toolCallId, input });
+                }
+                return execute(input, options);
+            },
+        };
+    }
+    return gated;
+}