@sprigr/apps-app-sdk 0.16.0 → 0.17.0

package/README.md

@@ -78,6 +78,7 @@ export default {
 - `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
+- `readableStoredKey(appKey, downloadUrl)` / `agentFileKeyFromUrl` — turn the install-relative key your app stored a file under into the absolute key the platform's `read_file` tool opens (read off the signed URL `appFileUrl` minted). Return it as a tool's `file_key` so an agent can open the file. `appKeyFromCallerKey` / `callerKeyRefusal` go the other way, for a key an agent hands back to your tool (0.17.0)
 
 Full platform semantics: [`docs/platform-reference.md`](../../docs/platform-reference.md).
 

package/dist/index.d.ts

@@ -2472,6 +2472,79 @@ declare function connectDisconnect(env: WfpBridgeEnv, req: {
     deleted: number;
 }>;
 
+/**
+ * Stored-file keys an agent can open (sprigr/sprigr-apps#2394).
+ *
+ * The platform hands an app its storage keys INSTALL-RELATIVE
+ * (`drive/reads/<id>.docx`): that is the app's own view of its storage, and the
+ * platform never names the install prefix or the per-user owner segment in a
+ * files response. The platform tool read_file needs the ABSOLUTE key:
+ *
+ *   `_apps/<installId>/<appKey>`                  (shared storage)
+ *   `_apps/<installId>/~u/<ownerHash>/<appKey>`   (a manifest
+ *                                                  actor_scoped_storage_prefixes key,
+ *                                                  sprigr/sprigr-team#9621)
+ *
+ * A signed URL from env.SPRIGR.files.url carries exactly that key as its path,
+ * so a tool that stores a file and mints a link can hand the agent a key that
+ * opens. The github app found the same gap first (sprigr/sprigr-apps#2276,
+ * deriveAgentFileKey); this version also accepts the owner segment.
+ */
+/** Root every marketplace-app file lives under. */
+declare const APP_FILES_ROOT = "_apps/";
+/** The platform's per-user owner segment (sprigr/sprigr-team#9621). An app never
+ *  names it in a key it hands env.SPRIGR.files; the platform refuses that. */
+declare const APP_OWNER_SEGMENT = "~u";
+/**
+ * The absolute key behind a minted download URL, for the app key it was minted
+ * for. Returns null, never a guess, unless the URL path is exactly
+ * `_apps/<one segment>/<appKey>` or `_apps/<one segment>/~u/<one segment>/<appKey>`:
+ * a key handed to an agent as openable that is not the stored object's key is
+ * worse than no key.
+ */
+declare function agentFileKeyFromUrl(downloadUrl: string, appKey: string): string | null;
+/**
+ * The key a tool returns as `file_key` for a file it stored under `appKey`
+ * and minted `downloadUrl` for: the absolute key when it can be read off the
+ * URL, otherwise the app key unchanged (the behaviour before sprigr/sprigr-apps#2394).
+ */
+declare function readableStoredKey(appKey: string, downloadUrl: string): string;
+/** A caller-supplied stored-file key, resolved to this install's app key. */
+type CallerKeyResolution = {
+    ok: true;
+    /** The install-relative key to hand env.SPRIGR.files. */
+    appKey: string;
+    /** True when the caller passed the absolute form or a signed link. */
+    wasAbsolute: boolean;
+} | {
+    ok: false;
+    /** `other_install`: an absolute key for a different install. `malformed`:
+     *  an `_apps/` key or a link with no file path after the prefix. */
+    reason: 'other_install' | 'malformed';
+    /** The install the key names, for `other_install`. */
+    installId?: string;
+};
+/**
+ * Accept a stored-file key in any form a tool may have handed out and return
+ * the app-relative key for env.SPRIGR.files:
+ *   - the app-relative key itself (`drive/reads/<id>.docx`): unchanged;
+ *   - the absolute key (`_apps/<installId>/[~u/<hash>/]drive/reads/<id>.docx`);
+ *   - the signed download link, whose path is that absolute key.
+ *
+ * The owner segment is dropped, not checked: the platform re-derives the
+ * owner from the call's verified actor (sprigr/sprigr-team#9621), so another user's
+ * key resolves to the caller's own copy, which usually does not exist. An
+ * absolute key naming a different install is refused when `ownInstallId` is
+ * known, because the platform would otherwise read THIS install's file at the
+ * same relative path. When it is unknown the key is accepted: the platform
+ * still confines every read to this install.
+ */
+declare function appKeyFromCallerKey(key: string, ownInstallId?: string | null): CallerKeyResolution;
+/** The sentence a refusal from appKeyFromCallerKey ends with, naming the key. */
+declare function callerKeyRefusal(key: string, r: Extract<CallerKeyResolution, {
+    ok: false;
+}>): string;
+
 /**
  * @sprigr/apps-app-sdk
  *
@@ -3027,4 +3100,4 @@ interface ExecutionContextLike {
 }
 type HandlerFn<TArgs, TResult> = (args: TArgs, env: Record<string, unknown>, ctx?: ExecutionContextLike) => Promise<TResult>;
 
-export { ACTOR_RETIRED_HOOK_TOOL, ACTOR_RETIRE_REASONS, APPROVAL_GRANTED_KEY, type Actor, type ActorRetireReason, type ActorRetired, type ActorRetiredHookBody, type ActorRetiredResult, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppToolEffectsDeclaration, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type ConnectCompleteRequest, type ConnectCompleteResult, type D1Like, type D1PreparedStatementLike, DATA_PARTIAL_UPDATE_PATH, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_LOG_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, INBOX_SEND_CONTRACT_V1, type InboxAddress, type InboxAppendRequest, type InboxAppendResult, type InboxChannelDeclaration, type InboxFoldersRequest, type InboxFoldersResult, type InboxOwner, type InboxSendConnection, type InboxSendHandlerImpl, InboxSendRefusal, type InboxSendSupports, type InboxSendV1Args, type InboxSendV1Result, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type LogToPlatformOptions, type ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PartialUpdateDataOptions, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type ResolveViewerOptions, type RestoreResult, type RestoreSpec, SPRIGR_DATA_MAX_OBJECTS_PER_CALL, SPRIGR_LOG_LEVELS, SPRIGR_LOG_LIMITS, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataImportOpts, type SprigrDataIndexOpts, type SprigrDataPartialUpdateBody, type SprigrDataPartialUpdateOpts, type SprigrDataPartialUpdateResult, type SprigrDataPatch, type SprigrDataSearchOpts, type SprigrDataSearchResult, SprigrDataValidationError, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type SprigrFilesListItem, type SprigrFilesListResult, type SprigrInboxApi, type SprigrLogEntry, type SprigrLogFn, type SprigrLogLevel, type SprigrLogResult, SprigrLogValidationError, type SyncedAttachment, type SyncedMessage, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, VIEWER_ANONYMOUS, VIEWER_CONTEXT_HEADER, VIEWER_PLATFORM_USER_ID_HEADER, VIEWER_ROLE_HEADER, VIEWER_USER_ID_HEADER, type VerbRule, type ViewerContext, type ViewerContextFailure, type ViewerContextVerification, type ViewerEnv, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorRetiredHook, actorTool, appFileUrl, applyConfirmationPolicies, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, buildPartialUpdateBody, bytesToBase64, canEmit, canLog, canPartialUpdate, checkConfirmationPolicy, commonDestructiveVerbs, connectComplete, connectDisconnect, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, defineInboxSendHandler, deleteAppFile, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, manifestIsFresh, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, parseActorRetiredArgs, partialUpdateData, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSprigrEmitFallback, withSprigrInboxFallback, withSprigrLogFallback };
+export { ACTOR_RETIRED_HOOK_TOOL, ACTOR_RETIRE_REASONS, APPROVAL_GRANTED_KEY, APP_FILES_ROOT, APP_OWNER_SEGMENT, type Actor, type ActorRetireReason, type ActorRetired, type ActorRetiredHookBody, type ActorRetiredResult, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppToolEffectsDeclaration, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CallerKeyResolution, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type ConnectCompleteRequest, type ConnectCompleteResult, type D1Like, type D1PreparedStatementLike, DATA_PARTIAL_UPDATE_PATH, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_LOG_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, INBOX_SEND_CONTRACT_V1, type InboxAddress, type InboxAppendRequest, type InboxAppendResult, type InboxChannelDeclaration, type InboxFoldersRequest, type InboxFoldersResult, type InboxOwner, type InboxSendConnection, type InboxSendHandlerImpl, InboxSendRefusal, type InboxSendSupports, type InboxSendV1Args, type InboxSendV1Result, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type LogToPlatformOptions, type ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PartialUpdateDataOptions, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type ResolveViewerOptions, type RestoreResult, type RestoreSpec, SPRIGR_DATA_MAX_OBJECTS_PER_CALL, SPRIGR_LOG_LEVELS, SPRIGR_LOG_LIMITS, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataImportOpts, type SprigrDataIndexOpts, type SprigrDataPartialUpdateBody, type SprigrDataPartialUpdateOpts, type SprigrDataPartialUpdateResult, type SprigrDataPatch, type SprigrDataSearchOpts, type SprigrDataSearchResult, SprigrDataValidationError, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type SprigrFilesListItem, type SprigrFilesListResult, type SprigrInboxApi, type SprigrLogEntry, type SprigrLogFn, type SprigrLogLevel, type SprigrLogResult, SprigrLogValidationError, type SyncedAttachment, type SyncedMessage, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, VIEWER_ANONYMOUS, VIEWER_CONTEXT_HEADER, VIEWER_PLATFORM_USER_ID_HEADER, VIEWER_ROLE_HEADER, VIEWER_USER_ID_HEADER, type VerbRule, type ViewerContext, type ViewerContextFailure, type ViewerContextVerification, type ViewerEnv, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorRetiredHook, actorTool, agentFileKeyFromUrl, appFileUrl, appKeyFromCallerKey, applyConfirmationPolicies, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, buildPartialUpdateBody, bytesToBase64, callerKeyRefusal, canEmit, canLog, canPartialUpdate, checkConfirmationPolicy, commonDestructiveVerbs, connectComplete, connectDisconnect, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, defineInboxSendHandler, deleteAppFile, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, manifestIsFresh, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, parseActorRetiredArgs, partialUpdateData, putAppFile, putAppFileStream, randomHex, readableStoredKey, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSprigrEmitFallback, withSprigrInboxFallback, withSprigrLogFallback };

package/dist/index.js

@@ -1684,10 +1684,88 @@ async function connectDisconnect(env, req) {
   if (!bridge) throw new Error("connectDisconnect: SPRIGR_PLATFORM_BASE / SPRIGR_INSTALL_TOKEN are not bound");
   return await installTokenPost(bridge, "/internal/wfp/connect/disconnect", req, { label: "connect disconnect" });
 }
+
+// src/stored-file-keys.ts
+var APP_FILES_ROOT = "_apps/";
+var APP_OWNER_SEGMENT = "~u";
+function isSegment(s) {
+  return typeof s === "string" && s.length > 0 && !s.includes("/");
+}
+function trimLeadingSlashes(key) {
+  return key.replace(/^\/+/, "");
+}
+function parseAbsolute(key) {
+  if (!key.startsWith(APP_FILES_ROOT)) return null;
+  const parts = key.slice(APP_FILES_ROOT.length).split("/");
+  const installId = parts[0];
+  if (!isSegment(installId)) return null;
+  let i = 1;
+  let ownerHash = null;
+  if (parts[1] === APP_OWNER_SEGMENT) {
+    if (!isSegment(parts[2])) return null;
+    ownerHash = parts[2];
+    i = 3;
+  }
+  const rest = parts.slice(i).join("/");
+  if (!rest || rest.split("/").some((seg) => seg === "")) return null;
+  return { installId, ownerHash, rest };
+}
+function urlPathKey(url) {
+  try {
+    return trimLeadingSlashes(decodeURIComponent(new URL(url).pathname));
+  } catch {
+    return null;
+  }
+}
+function agentFileKeyFromUrl(downloadUrl, appKey) {
+  const rel = trimLeadingSlashes(appKey);
+  if (!rel) return null;
+  const path = urlPathKey(downloadUrl);
+  if (!path) return null;
+  const parsed = parseAbsolute(path);
+  if (!parsed || parsed.rest !== rel) return null;
+  return path;
+}
+function readableStoredKey(appKey, downloadUrl) {
+  return agentFileKeyFromUrl(downloadUrl, appKey) ?? appKey;
+}
+function appKeyFromCallerKey(key, ownInstallId) {
+  let candidate = key.trim();
+  let wasAbsolute = false;
+  if (/^https?:\/\//i.test(candidate)) {
+    const path = urlPathKey(candidate);
+    if (!path || !path.startsWith(APP_FILES_ROOT)) return { ok: false, reason: "malformed" };
+    candidate = path;
+  }
+  candidate = trimLeadingSlashes(candidate);
+  if (candidate.startsWith(APP_FILES_ROOT)) {
+    const parsed = parseAbsolute(candidate);
+    if (!parsed) return { ok: false, reason: "malformed" };
+    if (ownInstallId && parsed.installId !== ownInstallId) {
+      return { ok: false, reason: "other_install", installId: parsed.installId };
+    }
+    return { ok: true, appKey: parsed.rest, wasAbsolute: true };
+  }
+  const parts = candidate.split("/");
+  if (parts[0] === APP_OWNER_SEGMENT) {
+    const rest = parts.slice(2).join("/");
+    if (!isSegment(parts[1]) || !rest) return { ok: false, reason: "malformed" };
+    return { ok: true, appKey: rest, wasAbsolute: true };
+  }
+  return { ok: true, appKey: candidate, wasAbsolute };
+}
+function callerKeyRefusal(key, r) {
+  if (r.reason === "other_install") {
+    return `"${key}" is a stored file of a different app install (${r.installId}), not this one. Pass a file_key this app returned to you.`;
+  }
+  return `"${key}" is not a stored file key: it has no file path after the app storage prefix.`;
+}
 export {
   ACTOR_RETIRED_HOOK_TOOL,
   ACTOR_RETIRE_REASONS,
   APPROVAL_GRANTED_KEY,
+  APP_FILES_ROOT,
+  APP_OWNER_SEGMENT,
   DATA_PARTIAL_UPDATE_PATH,
   DEFAULT_EMIT_TIMEOUT_MS,
   DEFAULT_LOG_TIMEOUT_MS,
@@ -1712,7 +1790,9 @@ export {
   actorKey,
   actorRetiredHook,
   actorTool,
+  agentFileKeyFromUrl,
   appFileUrl,
+  appKeyFromCallerKey,
   applyConfirmationPolicies,
   approvalHash,
   archiveOfferRefusal,
@@ -1721,6 +1801,7 @@ export {
   buildMarketplaceWebhookUrl,
   buildPartialUpdateBody,
   bytesToBase64,
+  callerKeyRefusal,
   canEmit,
   canLog,
   canPartialUpdate,
@@ -1760,6 +1841,7 @@ export {
   putAppFile,
   putAppFileStream,
   randomHex,
+  readableStoredKey,
   recreatedWarning,
   refuseWithoutForce,
   requireApproval,

package/package.json

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