@sprigr/apps-app-sdk 0.22.0 → 0.23.0

package/README.md

@@ -95,6 +95,7 @@ Three platform tiers, and they are not substitutes for each other. Full guide: [
 
 - `requireApproval(handlers, specs, opts)` wraps the named tools so each returns an `_approval` card instead of writing, then on the granted pass captures a before-image through the **pinned** connection and offers `_undo`. It resolves the connection inside itself, before the label lookup, the hash and the capture: a gate that sits outside the app's own pin names the wrong store, hashes the wrong store and captures the wrong store's copy. Register the result after the originals: `Object.assign(registry, requireApproval(registry, SPECS, opts))`.
 - `dispatcherApproval(specs, opts)`: the same gate for a one-tool-many-actions dispatcher. Build it beside the action registry and call `gate.run(action, args, env, () => def.execute(state, parsed))` from the dispatcher; params are read from `opts.inputField` (default `input`), the action name is hashed in, and `pinEnv` may return a per-actor token state rather than the env.
+- A spec with no `hash` binds the grant to its payload: every argument except the `keys` fields, the attestation flags and the gate's `connectionArgs` (e.g. `['store']`) goes into the hash canonically, so a tap on one payload cannot be spent on another (sprigr-apps#2605). See docs/write-protection.md.
 - Every resolver on the gate is a **default, overridable per spec**: `ApprovalSpec.resolveConnection`, `.describeTarget` and `.stampConnection` win over the gate's for that spec alone. Reach for it when one app has two families of write that reach a connection differently (creates that POST under an account, deletes that address a global object id on a path carrying no account). One gate-level rule has to pick one of them, and for the other it prints a false connection on the card a person taps and mixes it into the grant hash. A spec that hits no connection returns `''`.
 - `approvalHash(rawId, connection, ...parts)`, `set(values)`, `seq(values)`: a stable operation identity so a tap survives the model reordering a list or dropping an optional argument on the retry.
 - `undoEnvelope({...})` throws on a blank field. The platform drops the whole envelope on a blank and mints nothing, silently.

package/dist/index.d.ts

@@ -1890,6 +1890,14 @@ interface ApprovalSpec<P = unknown, E = unknown> {
     /**
      * Extra identity parts beyond `rawId + connection`, e.g. a sorted tag set.
      * Use `set()` / `seq()` from `approval-hash`. Never include `confirm`.
+     *
+     * Omitted, the wrapper appends a canonical form of every OTHER argument:
+     * not the `keys` fields, not `confirm` / `_approval_granted`, and not the
+     * gate's `connectionArgs` (sprigr-apps#2605). So a grant approved for one
+     * payload cannot be spent on another; before, a hash-less refund hashed the
+     * same for 10.00 and 250.00. Supply `hash` when that default is too strict
+     * (an order-insensitive set, a free-text field the model rewords) or
+     * `() => []` when the id and connection really are the whole operation.
      */
     hash?: (args: ToolArgs) => Array<string | number | undefined | null>;
     /**
@@ -1972,6 +1980,14 @@ interface ApprovalGateOptions<E, P = E> {
      * `ApprovalSpec.resolveConnection`.
      */
     resolveConnection: (env: E, args: ToolArgs) => Promise<string>;
+    /**
+     * Argument names that only CHOOSE the connection (e.g. `['store']`). They
+     * are left out of the default payload hash (see `ApprovalSpec.hash`)
+     * because the connection is already in the hash in its RESOLVED form, and
+     * the model usually omits the raw argument on the retry. Omit for a
+     * single-connection app.
+     */
+    connectionArgs?: string[];
     /**
      * Re-pin to a resolved connection so lookups and captures hit it. Omit when
      * `P` is `E` and the env needs no pin (a single-connection app).

package/dist/index.js

@@ -1470,6 +1470,23 @@ async function offerUndo(args) {
 }
 
 // src/write-protection/require-approval.ts
+var ATTESTATION_KEYS = ["confirm", APPROVAL_GRANTED_KEY];
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.keys(value).filter((k) => value[k] !== void 0).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`);
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+function defaultPayloadParts(params, keys, connectionArgs = []) {
+  const skip = /* @__PURE__ */ new Set([...keys, ...ATTESTATION_KEYS, ...connectionArgs]);
+  const rest = {};
+  for (const [k, v] of Object.entries(params)) {
+    if (!skip.has(k) && v !== void 0) rest[k] = v;
+  }
+  return Object.keys(rest).length ? [canonicalJson(rest)] : [];
+}
 function rawIdOf(args, keys) {
   for (const k of keys) {
     const v = args[k];
@@ -1509,7 +1526,7 @@ async function askPass(name, spec, params, env, opts, hashPrefix) {
   const pinned = await pin(opts, env, connection);
   const describeTarget = spec.describeTarget ?? opts.describeTarget;
   const target = rawId && describeTarget ? await safeLabel(describeTarget, pinned, rawId, name) : rawId || "(unknown id)";
-  const extra = spec.hash ? spec.hash(params) : [];
+  const extra = spec.hash ? spec.hash(params) : defaultPayloadParts(params, spec.keys, opts.connectionArgs);
   const count = countOf(spec, params, rawId);
   return {
     ok: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprigr/apps-app-sdk",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",