@sprigr/apps-app-sdk 0.8.5 → 0.8.7

package/dist/index.d.ts

@@ -1424,6 +1424,122 @@ interface OfferUndoArgs {
  */
 declare function offerUndo(args: OfferUndoArgs): Promise<AppUndoEnvelope | undefined>;
 
+/**
+ * Apply confirmation policies to a parsed `sprigr-app.json`, for an app's
+ * `gen:confirmation` script and its drift-guard test.
+ *
+ * Pure: takes the parsed manifest, mutates it in place, returns what it
+ * touched. The script owns the two lines of file I/O around it, so this
+ * module stays free of `node:fs` and safe to bundle into a Worker.
+ *
+ * Besides writing each policy, it retires the two mechanisms a policy
+ * supersedes: the legacy `confirmation_required` flag (a bare
+ * `{ always: true }` with no describe) and any app-declared `confirm` input
+ * (the platform injects its own top-level `confirm` wherever a policy is
+ * present). Both are stripped from EVERY tool, not only the gated ones,
+ * because a stray copy on an ungated tool is how a handler ends up reading
+ * a flag nothing enforces.
+ */
+
+interface ManifestDispatchBlock {
+    actionField: string;
+    actions: string[];
+    actionInputs?: Record<string, {
+        accepts: string[];
+        required?: string[];
+    }>;
+}
+interface ManifestToolLike {
+    name: string;
+    input_schema?: {
+        properties?: Record<string, unknown>;
+        required?: string[];
+        [k: string]: unknown;
+    };
+    confirmation?: unknown;
+    confirmation_required?: boolean;
+    dispatch?: unknown;
+    [k: string]: unknown;
+}
+interface ManifestLike {
+    tools?: ManifestToolLike[];
+    [k: string]: unknown;
+}
+interface ApplyPoliciesOptions {
+    /** Tool name -> its policy: a tool-level rule, or `{ actions }` for a dispatcher. */
+    policies: Readonly<Record<string, ConfirmationPolicy>>;
+    /** Tool name -> dispatch block to write alongside (dispatchers only). */
+    dispatch?: Readonly<Record<string, ManifestDispatchBlock>>;
+    /** Delete `confirmation_required` from every tool. Default true. */
+    stripLegacyFlag?: boolean;
+    /** Delete an app-declared `confirm` input (property + required entry) from every tool. Default true. */
+    dropConfirmParam?: boolean;
+}
+/**
+ * Write the policies (and dispatch blocks) onto the named tools in place.
+ * Throws when a policy names a tool the manifest does not have, so a
+ * renamed tool cannot silently lose its gate. Returns the tool names touched.
+ */
+declare function applyConfirmationPolicies(manifest: ManifestLike, opts: ApplyPoliciesOptions): string[];
+/**
+ * True when applying the policies to a copy of the manifest changes nothing:
+ * the committed file is a fresh generation. The drift-guard test's one call.
+ */
+declare function manifestIsFresh(manifest: ManifestLike, opts: ApplyPoliciesOptions): boolean;
+/** The manifest, serialised the way the repo commits it (2-space, trailing newline). */
+declare function serializeManifest(manifest: ManifestLike): string;
+
+/**
+ * Derive a confirmation policy from an action registry by NAME, for apps
+ * whose registry carries no destructive flag: the verb prefix says what an
+ * action does (`delete_`, `void_`, `cancel_`, `archive_`), so the policy
+ * follows from a small table of verb rules instead of a hand-kept list
+ * that drifts the moment an action is added.
+ *
+ * Each rule names a prefix (or regex), the tier it lands in, and how to
+ * phrase the describe from the rest of the name. The first matching rule
+ * wins, so put the specific ones first.
+ */
+
+interface VerbRule {
+    /** A name prefix (`'delete_'`) or a regex tested against the whole name. */
+    match: string | RegExp;
+    /** `irreversible` marks the card "cannot be undone"; `always` is a plain confirmation. */
+    tier: 'irreversible' | 'always';
+    /**
+     * Describe for a matching action. Receives the full name and `rest`: the
+     * name with the matched prefix removed and underscores turned to spaces
+     * (for a regex match, the whole name spaced). No trailing period.
+     */
+    describe: (name: string, rest: string) => string;
+}
+interface DerivePolicyOptions {
+    /** Verb rules, most specific first. */
+    rules: readonly VerbRule[];
+    /** Actions to leave ungated even though a rule matches (returned in `ungated`). */
+    exempt?: readonly string[];
+    /** Explicit rules that win over the verb table (e.g. a hand-written describe). */
+    overrides?: Readonly<Record<string, ConfirmRule>>;
+}
+interface DerivedPolicy {
+    policy: ConfirmationPolicy & {
+        actions: Record<string, ConfirmRule>;
+    };
+    /** Registry names a rule matched but `exempt` kept ungated. */
+    ungated: string[];
+    /** Registry names no rule matched (reads and writes the table does not classify). */
+    unmatched: string[];
+}
+/** Build a policy over `registry` from the verb table; see the file comment. */
+declare function deriveConfirmationPolicy(registry: Iterable<string>, opts: DerivePolicyOptions): DerivedPolicy;
+/**
+ * The verb table most registries need: hard deletes, voids, refunds and
+ * cancellations cannot be undone; archives, removals from a parent and
+ * unassignments are plain confirmations. `subject` names the system for
+ * the describe ("in Xero").
+ */
+declare function commonDestructiveVerbs(subject: string): VerbRule[];
+
 /**
  * @sprigr/apps-app-sdk
  *
@@ -1824,4 +1940,4 @@ interface ExecutionContextLike {
 }
 type HandlerFn<TArgs, TResult> = (args: TArgs, env: Record<string, unknown>, ctx?: ExecutionContextLike) => Promise<TResult>;
 
-export { APPROVAL_GRANTED_KEY, type Actor, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppUndoEnvelope, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type DispatcherApprovalGate, type DispatcherApprovalOptions, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InboxOwner, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type RestoreResult, type RestoreSpec, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataIndexOpts, type SprigrDataSearchOpts, type SprigrDataSearchResult, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, checkConfirmationPolicy, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, runUndoApply, safeCapture, seq, set, tool, undoEnvelope, withSprigrEmitFallback };
+export { APPROVAL_GRANTED_KEY, type Actor, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type DerivePolicyOptions, type DerivedPolicy, type DispatcherApprovalGate, type DispatcherApprovalOptions, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InboxOwner, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type RestoreResult, type RestoreSpec, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataIndexOpts, type SprigrDataSearchOpts, type SprigrDataSearchResult, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, type VerbRule, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, applyConfirmationPolicies, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, checkConfirmationPolicy, commonDestructiveVerbs, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, manifestIsFresh, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, withSprigrEmitFallback };

package/dist/index.js

@@ -940,6 +940,98 @@ function checkConfirmationPolicy(input) {
   }
   return out.sort();
 }
+
+// src/write-protection/manifest.ts
+function applyConfirmationPolicies(manifest, opts) {
+  const tools = manifest.tools ?? [];
+  const byName = new Map(tools.map((t) => [t.name, t]));
+  const touched = [];
+  for (const [name, policy] of Object.entries(opts.policies)) {
+    const tool2 = byName.get(name);
+    if (!tool2) throw new Error(`applyConfirmationPolicies: no tool named '${name}' in the manifest`);
+    tool2.confirmation = policy;
+    touched.push(name);
+  }
+  for (const [name, block] of Object.entries(opts.dispatch ?? {})) {
+    const tool2 = byName.get(name);
+    if (!tool2) throw new Error(`applyConfirmationPolicies: no tool named '${name}' in the manifest (dispatch)`);
+    tool2.dispatch = block;
+    if (!touched.includes(name)) touched.push(name);
+  }
+  const stripLegacy = opts.stripLegacyFlag ?? true;
+  const dropConfirm = opts.dropConfirmParam ?? true;
+  for (const tool2 of tools) {
+    if (stripLegacy) delete tool2.confirmation_required;
+    if (dropConfirm) {
+      const schema = tool2.input_schema;
+      if (schema?.properties && "confirm" in schema.properties) delete schema.properties.confirm;
+      if (schema?.required?.includes("confirm")) {
+        schema.required = schema.required.filter((k) => k !== "confirm");
+        if (schema.required.length === 0) delete schema.required;
+      }
+    }
+  }
+  return touched;
+}
+function manifestIsFresh(manifest, opts) {
+  const copy = JSON.parse(JSON.stringify(manifest));
+  applyConfirmationPolicies(copy, opts);
+  return JSON.stringify(copy) === JSON.stringify(manifest);
+}
+function serializeManifest(manifest) {
+  return `${JSON.stringify(manifest, null, 2)}
+`;
+}
+
+// src/write-protection/derive-policy.ts
+function spaced(s) {
+  return s.replace(/_/g, " ");
+}
+function matchRule(name, rule) {
+  if (typeof rule.match === "string") {
+    return name.startsWith(rule.match) ? spaced(name.slice(rule.match.length)) : null;
+  }
+  return rule.match.test(name) ? spaced(name) : null;
+}
+function deriveConfirmationPolicy(registry, opts) {
+  const exempt = new Set(opts.exempt ?? []);
+  const irreversible = {};
+  const always = {};
+  const ungated = [];
+  const unmatched = [];
+  const overrides = opts.overrides ?? {};
+  for (const name of registry) {
+    if (overrides[name]) continue;
+    let hit = false;
+    for (const rule of opts.rules) {
+      const rest = matchRule(name, rule);
+      if (rest == null) continue;
+      hit = true;
+      if (exempt.has(name)) ungated.push(name);
+      else (rule.tier === "irreversible" ? irreversible : always)[name] = rule.describe(name, rest);
+      break;
+    }
+    if (!hit) unmatched.push(name);
+  }
+  const policy = buildConfirmationPolicy({ irreversible, always, rules: overrides });
+  return { policy, ungated, unmatched };
+}
+function commonDestructiveVerbs(subject) {
+  const where = subject ? ` ${subject}` : "";
+  return [
+    { match: "delete_", tier: "irreversible", describe: (_n, rest) => `Delete ${rest}${where}` },
+    { match: "void_", tier: "irreversible", describe: (_n, rest) => `Void ${rest}${where}` },
+    { match: "refund_", tier: "irreversible", describe: (_n, rest) => `Refund ${rest}${where}` },
+    { match: "cancel_", tier: "irreversible", describe: (_n, rest) => `Cancel ${rest}${where}` },
+    { match: "destroy_", tier: "irreversible", describe: (_n, rest) => `Destroy ${rest}${where}` },
+    { match: "purge_", tier: "irreversible", describe: (_n, rest) => `Purge ${rest}${where}` },
+    { match: "revoke_", tier: "irreversible", describe: (_n, rest) => `Revoke ${rest}${where}` },
+    { match: "archive_", tier: "always", describe: (_n, rest) => `Archive ${rest}${where}` },
+    { match: "remove_", tier: "always", describe: (_n, rest) => `Remove ${rest}${where}` },
+    { match: "unassign_", tier: "always", describe: (_n, rest) => `Unassign ${rest}${where}` },
+    { match: "deactivate_", tier: "always", describe: (_n, rest) => `Deactivate ${rest}${where}` }
+  ];
+}
 export {
   APPROVAL_GRANTED_KEY,
   DEFAULT_EMIT_TIMEOUT_MS,
@@ -952,6 +1044,7 @@ export {
   actorKey,
   actorTool,
   appFileUrl,
+  applyConfirmationPolicies,
   approvalHash,
   archiveOfferRefusal,
   base64ToBytes,
@@ -960,11 +1053,13 @@ export {
   bytesToBase64,
   canEmit,
   checkConfirmationPolicy,
+  commonDestructiveVerbs,
   constantTimeEqual,
   createMarketplaceEmitter,
   createToolWrappers,
   decodeState,
   deleteAppFile,
+  deriveConfirmationPolicy,
   describeMissingBridge,
   dispatcherApproval,
   emitMarketplaceEvent,
@@ -979,6 +1074,7 @@ export {
   isNotConnectedError,
   isStagingHost,
   listAppFiles,
+  manifestIsFresh,
   offerUndo,
   overlaySprigr,
   ownerFromActorKey,
@@ -996,6 +1092,7 @@ export {
   runUndoApply,
   safeCapture,
   seq,
+  serializeManifest,
   set,
   tool,
   undoEnvelope,

package/package.json

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