@sprigr/apps-app-sdk 0.4.0 → 0.6.0

package/README.md

@@ -17,6 +17,31 @@ The runtime injects the `env.SPRIGR` host object **only on `/__sprigr/*` dispatc
 - `resolveInstallBridge(env)` / `installTokenPost(bridge, path, body, opts?)` — build your own `/internal/wfp/*` fallback (collections, files, inbox) with the auth and error extraction handled.
 - `overlaySprigr(env, sprigr)` — overlay a patched `SPRIGR` via `Object.create`. Never rebuild a dispatch-path env by spread: the real bindings live on the prototype and `SPRIGR` is non-enumerable, so `{ ...env }` yields an env whose `DB` is `undefined`.
 
+## Per-actor tool wrappers
+
+An agent-facing tool must resolve the **calling** identity's own credential, or refuse. It must never fall back to another connected account, not even for a read: an install is company-wide, but access is not.
+
+```ts
+// src/handlers/wrap.ts: bind the options once
+import { createToolWrappers, NotConnectedError } from '@sprigr/apps-app-sdk';
+
+export const { tool, actorTool } = createToolWrappers<MyEnv>({
+  notConnectedHint: 'Call my_connect and send the user the link.',
+  mapError: (err) =>
+    err instanceof MyApiError ? { error: err.message, status: err.status } : null,
+});
+
+// src/handlers/things.ts
+export default { list_things: actorTool(async (env, actor, args) => { /* ... */ }) };
+```
+
+- `actorTool(fn)`: reads the platform-stamped `args.actor`, returns `412 no_caller_identity` when it is absent, and maps a thrown `NotConnectedError` to `412 not_connected` with your connect hint. Identity comes only from the nested `args.actor`; flat body fields are agent-supplied and spoofable.
+- `tool(fn)`: for handlers with genuinely no caller (schedules, webhooks, platform mirrors). Those need a *designated service connection*, which is not licence for an agent-facing handler to borrow one.
+- `NotConnectedError`: throw from your token resolver when the **caller** has no connection. Don't throw it for "the install has none", which is a different fault with a different fix.
+- `isNotConnectedError(err)`: matches by class *and* by `name`, so it still works when the vendor pattern puts two copies of this module in one isolate and `instanceof` would silently fail.
+
+**Why this is in the SDK:** every app hand-rolled this, and one shipped a version that fell back to "the first connected actor on the install" when the caller had none. One person's consent then exposed their account to every agent on that install, in production.
+
 ## Webhook callback URLs
 
 - `resolvePlatformWebhookBase(env)` / `buildMarketplaceWebhookUrl(env, installId, topicPath)` — env-correct platform host, so a staging install never registers prod-pointing subscriptions.
@@ -26,7 +51,7 @@ The runtime injects the `env.SPRIGR` host object **only on `/__sprigr/*` dispatc
 - `fetchWithRetry` — rate-limit-header-aware, jittered retry
 - `constantTimeEqual(a, b)` — bearer-secret verification
 - `encodeState` / `decodeState` — OAuth state base64url
-- `parseActor` / `actorKey` — per-actor token scoping
+- `parseActor` / `actorKey` / `ownerFromActorKey` — per-actor token scoping
 - `putAppFile` / `putAppFileStream` / `appFileUrl` / `getAppFile` / `listAppFiles` / `deleteAppFile` — durable app-scoped file storage from outside the injected bridge
 - `fetchFileBytes` / `fetchFileAsBase64` / `bytesToBase64` / `base64ToBytes` — file byte helpers
 

package/dist/index.d.ts

@@ -528,6 +528,191 @@ declare function parseActor(args: unknown): Actor | undefined;
  * treat that as "no caller identity" and fail closed.
  */
 declare function actorKey(actor: Actor | undefined): string | null;
+/**
+ * Mailbox-owner attribution for one `env.SPRIGR.inbox.append` /
+ * `env.SPRIGR.inbox.folders` batch.
+ *
+ * Exactly ONE of the two fields must be set:
+ *
+ *   - `platformUserId` — OIDC sub of the user whose mailbox the batch was
+ *     synced from (a personal mailbox connection).
+ *   - `agentId` — agent id for an agent-keyed connection (a shared /
+ *     departmental mailbox connected through a shared agent rather than a
+ *     person).
+ *
+ * Why this exists: a mail app install is shared by the whole company, and
+ * several users can each connect their own mailbox to it. The platform files
+ * every appended message under the ONE integration behind the install, so
+ * without attribution it cannot tell whose mailbox a batch came from and has
+ * historically granted thread visibility to every connected user. Passing
+ * `owner` pins each synced thread's visibility to exactly the mailbox owner:
+ * user connections stay private to that user, agent-keyed connections stay
+ * visible to that agent's audience.
+ *
+ * This is the OWNER OF THE MAILBOX (the connection identity the app keyed
+ * the sync on), NOT the dispatch caller — a scheduled poll has no caller at
+ * all yet must still attribute every batch. Populate it from the per-actor
+ * connection row the sync loop is iterating, e.g.:
+ *
+ *   const owner = row.sprigr_user_id
+ *     ? { platformUserId: row.sprigr_user_id }
+ *     : { agentId: row.sprigr_agent_id };
+ *   await env.SPRIGR.inbox.append({ channel, messages, owner });
+ *
+ * Mail apps must send it on EVERY append/folders call (sync poll, push
+ * delivery, backfill, folder reports). Batches without it fall back to the
+ * platform's legacy integration-level resolution, which on a multi-user
+ * install pins nobody (fail closed) rather than everyone.
+ *
+ * Hosts older than the attribution surface ignore the field entirely, so
+ * sending it is always safe.
+ */
+interface InboxOwner {
+    /** OIDC sub (platform user id) of the mailbox's owner. */
+    platformUserId?: string;
+    /** Agent id for an agent-keyed (shared-mailbox) connection. */
+    agentId?: string;
+}
+/**
+ * Inverse of `actorKey`: turn a stored `u:<platformUserId>` / `a:<agentId>`
+ * key back into an `InboxOwner`. For apps that persist the connection
+ * identity as an actor-key string and need to attribute inbox batches from
+ * it. Returns null for null/empty/unrecognised input — callers should treat
+ * that as "owner unknown" and omit the field rather than guess.
+ */
+declare function ownerFromActorKey(key: string | null | undefined): InboxOwner | null;
+
+/**
+ * Adapters between the marketplace wrapper's calling convention and an app's
+ * inner handler signatures, with fail-closed per-actor authorization built in.
+ *
+ * The wrapper calls `handler(args, env, ctx)`, args first. Inner handlers are
+ * usually written `(env, args)` or `(env, actor, args)`, so something has to
+ * flip them and shape thrown errors into a result an agent can read.
+ *
+ *   tool(fn)       actor-less handlers: schedules, webhooks, internal work.
+ *   actorTool(fn)  per-actor handlers: reads the platform-stamped
+ *                  `args.actor`, fails closed with 412 when it is absent, and
+ *                  maps NotConnectedError to a 412 `not_connected`.
+ *
+ * WHY THIS IS IN THE SDK. Every app hand-rolled this wrapper, and the gorgias
+ * app got it wrong in the way that matters: when the caller had no connection
+ * it fell through to "the first connected actor on the install", so one
+ * person's consent made their whole helpdesk readable and writable by every
+ * agent on a company-wide install. That reached production. The rule is not
+ * hard, but it is easy to write a plausible-looking fallback for, so the
+ * correct version belongs in one place that apps import rather than copy.
+ *
+ * THE RULE: an agent-facing tool resolves the CALLING identity's own
+ * credential, or refuses. Never another actor's, not even to be helpful, and
+ * not even for a read. Background paths (schedules, webhooks, platform
+ * mirrors) genuinely have no caller and need a designated service connection;
+ * that is what `tool()` is for, and it is not licence for an agent-facing
+ * handler to borrow one.
+ */
+
+/** What every wrapped handler returns. `ok:false` never throws past the wrapper. */
+type ToolResult<R> = {
+    ok: true;
+    result: R;
+} | {
+    ok: false;
+    error: string;
+    hint?: string;
+    status?: number;
+};
+/**
+ * Throw this from a token resolver when the CALLING actor has no connection
+ * of their own. `actorTool` turns it into a 412 `not_connected` carrying the
+ * app's connect hint, which is the agent's cue to mint an authorize link
+ * rather than retry.
+ *
+ * Do not throw it for "the install has no connection at all" on a background
+ * path: that is a different failure with a different fix (an admin
+ * designating a service connection), and collapsing the two sends the agent
+ * chasing a consent link it cannot complete.
+ */
+declare class NotConnectedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * True for a NotConnectedError, INCLUDING one thrown by a different copy of
+ * this module.
+ *
+ * `instanceof` alone is wrong here and would fail silently. Apps reach this
+ * package two ways: a normal npm dependency, and the legacy `sprigrVendor`
+ * mirror that copies the source into `src/lib/vendor/`. An app that vendors
+ * the SDK while a dependency resolves its own npm copy has TWO distinct
+ * `NotConnectedError` classes at runtime, and `instanceof` across them is
+ * false. The failure mode is the bad one: the error falls through to the
+ * generic branch, the agent gets an opaque message instead of `not_connected`,
+ * and never learns to offer a connect link. Matching on `name` as well costs
+ * nothing and survives the boundary.
+ */
+declare function isNotConnectedError(err: unknown): boolean;
+interface ToolWrapperOptions {
+    /**
+     * Hint returned alongside `not_connected`. Name the app's connect tool and
+     * frame it as a one-click authorization rather than an error, because this
+     * string is what the agent repeats to the user.
+     */
+    notConnectedHint?: string;
+    /**
+     * Hint returned alongside `no_caller_identity`.
+     */
+    noCallerIdentityHint?: string;
+    /**
+     * Shape an app-specific error (a provider API error carrying an HTTP
+     * status) into a result. Return null to fall through to the generic
+     * `{ error: message }`. Runs AFTER the not_connected check.
+     *
+     *   mapError: (err) => err instanceof GraphApiError
+     *     ? { error: err.message, status: err.status }
+     *     : null,
+     */
+    mapError?: (err: unknown) => {
+        error: string;
+        status?: number;
+        hint?: string;
+    } | null;
+}
+/**
+ * Wrap an actor-less handler. Catches throws into `{ ok: false, error }` so an
+ * agent caller never sees a bare exception.
+ */
+declare function tool<Env, A, R>(fn: (env: Env, args: A) => Promise<R>, opts?: ToolWrapperOptions): (args: A, env: Env) => Promise<ToolResult<R>>;
+/**
+ * Wrap a per-actor handler. Fails closed twice over: no stamped identity is
+ * `no_caller_identity`, and a caller with no connection of their own is
+ * `not_connected`. Both 412, both distinct on purpose: the first is a
+ * plumbing fault the agent should retry differently, the second the agent can
+ * resolve itself by sending the user a link.
+ *
+ * Identity comes ONLY from the nested, platform-stamped `args.actor`.
+ * `parseActor` deliberately ignores flat body fields, which are agent-supplied
+ * and spoofable; honouring one would let a caller name any colleague and act
+ * as them.
+ */
+declare function actorTool<Env, A, R>(fn: (env: Env, actor: Actor, args: A) => Promise<R>, opts?: ToolWrapperOptions): (args: A, env: Env) => Promise<ToolResult<R>>;
+/**
+ * Bind the options once and get both wrappers typed to the app's env, so
+ * handler files call `actorTool(fn)` with no per-call ceremony:
+ *
+ *   // src/handlers/wrap.ts
+ *   export const { tool, actorTool } = createToolWrappers<Ms365Env>({
+ *     notConnectedHint: 'Call ms_connect and send the user the link…',
+ *     mapError: (err) =>
+ *       err instanceof GraphApiError ? { error: err.message, status: err.status } : null,
+ *   });
+ *
+ * Options bound once is the point: an app that repeats them at each of fifty
+ * call sites will drift, and the one that drifts is the hint telling a user
+ * how to connect.
+ */
+declare function createToolWrappers<Env>(opts?: ToolWrapperOptions): {
+    tool: <A, R>(fn: (env: Env, args: A) => Promise<R>) => (args: A, env: Env) => Promise<ToolResult<R>>;
+    actorTool: <A, R>(fn: (env: Env, actor: Actor, args: A) => Promise<R>) => (args: A, env: Env) => Promise<ToolResult<R>>;
+};
 
 /**
  * App-scoped R2 file storage (platform feature, 2026-06).
@@ -939,4 +1124,4 @@ interface ExecutionContextLike {
 }
 type HandlerFn<TArgs, TResult> = (args: TArgs, env: Record<string, unknown>, ctx?: ExecutionContextLike) => Promise<TResult>;
 
-export { type Actor, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InstallBridge, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, type OAuthBouncerSignals, type OAuthState, type PlatformHostEnv, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type ScheduleArgs, type SprigrDataApi, type SprigrDataSearchOpts, type SprigrDataSearchResult, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, appFileUrl, base64ToBytes, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, constantTimeEqual, createMarketplaceEmitter, decodeState, deleteAppFile, describeMissingBridge, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, getAppFile, hmacSha256Hex, installTokenPost, isStagingHost, listAppFiles, overlaySprigr, parseActor, putAppFile, putAppFileStream, randomHex, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, withSprigrEmitFallback };
+export { type Actor, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InboxOwner, type InstallBridge, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type PlatformHostEnv, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type ScheduleArgs, type SprigrDataApi, type SprigrDataSearchOpts, type SprigrDataSearchResult, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type ToolResult, type ToolWrapperOptions, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, base64ToBytes, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, describeMissingBridge, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, tool, withSprigrEmitFallback };

package/dist/index.js

@@ -332,6 +332,72 @@ function actorKey(actor) {
   if (actor.agentId) return `a:${actor.agentId}`;
   return null;
 }
+function ownerFromActorKey(key) {
+  if (!key) return null;
+  if (key.startsWith("u:") && key.length > 2) return { platformUserId: key.slice(2) };
+  if (key.startsWith("a:") && key.length > 2) return { agentId: key.slice(2) };
+  return null;
+}
+
+// src/tool-wrappers.ts
+var NotConnectedError = class extends Error {
+  constructor(message = "The calling actor has no connection with this app.") {
+    super(message);
+    this.name = "NotConnectedError";
+  }
+};
+function isNotConnectedError(err) {
+  if (err instanceof NotConnectedError) return true;
+  return err instanceof Error && err.name === "NotConnectedError";
+}
+var DEFAULT_NO_CALLER_HINT = "The platform did not stamp caller identity on this call. Retry from an agent context.";
+var DEFAULT_NOT_CONNECTED_HINT = "You have not connected your own account with this app yet, and this tool only ever acts as the person calling it. Use the app's connect tool to get an authorize link.";
+function shapeError(err, opts) {
+  const mapped = opts.mapError?.(err);
+  if (mapped) return { ok: false, ...mapped };
+  return { ok: false, error: err instanceof Error ? err.message : String(err) };
+}
+function tool(fn, opts = {}) {
+  return async (args, env) => {
+    try {
+      return { ok: true, result: await fn(env, args ?? {}) };
+    } catch (err) {
+      return shapeError(err, opts);
+    }
+  };
+}
+function actorTool(fn, opts = {}) {
+  return async (args, env) => {
+    const actor = parseActor(args);
+    if (!actor || !actor.platformUserId && !actor.agentId) {
+      return {
+        ok: false,
+        error: "no_caller_identity",
+        hint: opts.noCallerIdentityHint ?? DEFAULT_NO_CALLER_HINT,
+        status: 412
+      };
+    }
+    try {
+      return { ok: true, result: await fn(env, actor, args ?? {}) };
+    } catch (err) {
+      if (isNotConnectedError(err)) {
+        return {
+          ok: false,
+          error: "not_connected",
+          hint: opts.notConnectedHint ?? DEFAULT_NOT_CONNECTED_HINT,
+          status: 412
+        };
+      }
+      return shapeError(err, opts);
+    }
+  };
+}
+function createToolWrappers(opts = {}) {
+  return {
+    tool: (fn) => tool(fn, opts),
+    actorTool: (fn) => actorTool(fn, opts)
+  };
+}
 
 // src/app-files.ts
 var DEFAULT_PLATFORM_BASE = "https://webhooks.sprigr.com";
@@ -422,7 +488,9 @@ function deleteAppFile(env, key) {
 export {
   DEFAULT_EMIT_TIMEOUT_MS,
   DEFAULT_MAX_FILE_BYTES,
+  NotConnectedError,
   actorKey,
+  actorTool,
   appFileUrl,
   base64ToBytes,
   buildMarketplaceWebhookUrl,
@@ -430,6 +498,7 @@ export {
   canEmit,
   constantTimeEqual,
   createMarketplaceEmitter,
+  createToolWrappers,
   decodeState,
   deleteAppFile,
   describeMissingBridge,
@@ -441,9 +510,11 @@ export {
   getAppFile,
   hmacSha256Hex,
   installTokenPost,
+  isNotConnectedError,
   isStagingHost,
   listAppFiles,
   overlaySprigr,
+  ownerFromActorKey,
   parseActor,
   putAppFile,
   putAppFileStream,
@@ -452,5 +523,6 @@ export {
   resolveOAuthBouncerBase,
   resolveOAuthBouncerCallbackUrl,
   resolvePlatformWebhookBase,
+  tool,
   withSprigrEmitFallback
 };

package/package.json

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