@sprigr/apps-app-sdk 0.8.8 → 0.10.0

package/README.md

@@ -69,6 +69,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.
+- 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.
 - `refuseWithoutForce(name, handler, opts)` / `archiveOfferRefusal(...)`: a delete refuses once and offers the vendor's native archive unless `force: true`.

package/dist/index.d.ts

@@ -582,6 +582,168 @@ interface InboxOwner {
  */
 declare function ownerFromActorKey(key: string | null | undefined): InboxOwner | null;
 
+/**
+ * Who is looking at this app's UI right now.
+ *
+ * A marketplace app UI is embedded in the portal iframe with only
+ * `#install_id=...` in its src, so nothing about the human viewer arrives in
+ * the URL. It arrives in HTTP headers the platform's `website-serve` worker
+ * stamps on every dispatch, and this module is the ONE place that reads them.
+ *
+ * ## Use this, do not hand-roll `src/lib/viewer.ts`
+ *
+ * Twelve apps in `sprigr-apps` each carried their own copy of this logic as
+ * of 2026-09-03, all textually different. Five apps had a query-param
+ * fallback that outranked the header, which is a connection-hijack bug (any
+ * tenant member could bind their own provider account to a colleague's actor
+ * row): `sprigr-apps` #1487-#1491, and `sprigr-apps#474` before them. That is
+ * why this lives in the SDK.
+ *
+ * **Never take a viewer identity from a query param, a form field, a cookie
+ * your app set, or a `postMessage` payload — not even as a fallback for when
+ * the header is missing.** A missing header means "no viewer"; it does not
+ * mean "believe the client".
+ *
+ * ## Two channels, one preferred
+ *
+ * - **`X-Sprigr-Viewer`** (preferred, platform issue #3210): a signed token
+ *   naming the viewer, bound to YOUR install and expiring in ~2 minutes.
+ *   Everything in it is inside an HMAC your install alone can check, using
+ *   the `SPRIGR_VIEWER_SECRET` binding the platform derives per install. It
+ *   is the only channel that carries a display name.
+ * - **`x-sprigr-platform-user-id`** (legacy): the viewer's OIDC sub as a
+ *   plain header. Not signed. It rests on transport integrity: your Worker
+ *   is reachable only through the platform's WFP dispatch, and the platform
+ *   overwrites the header unconditionally on every forward, so a browser
+ *   cannot smuggle its own value through. That is a real guarantee, but you
+ *   cannot verify it yourself.
+ *
+ * `resolveViewerContext` prefers the signed channel and returns
+ * `trust: 'verified'`. The legacy channel is used ONLY when you pass
+ * `allowTransportFallback: true`, and then reports `trust: 'transport'`. The
+ * fallback is opt-in per call site on purpose: it is needed while an install
+ * predates its `SPRIGR_VIEWER_SECRET` binding (the platform binds it on the
+ * install's next build or rebind), and it should be dropped once every
+ * install has been rebound.
+ */
+/** Header carrying the signed viewer context. */
+declare const VIEWER_CONTEXT_HEADER = "x-sprigr-viewer";
+/** Legacy transport-attested header carrying the viewer's OIDC sub. */
+declare const VIEWER_PLATFORM_USER_ID_HEADER = "x-sprigr-platform-user-id";
+/** Legacy transport-attested header carrying the sprigr-team `users.id`. */
+declare const VIEWER_USER_ID_HEADER = "x-sprigr-user-id";
+/** Legacy transport-attested header carrying the viewer's company role. */
+declare const VIEWER_ROLE_HEADER = "x-sprigr-role";
+/** Sentinel both id headers carry when nobody is signed in. */
+declare const VIEWER_ANONYMOUS = "anonymous";
+/** Raw wire claims. snake_case because they are the signed payload. */
+interface WireClaims {
+    install_id: string;
+    company_id: string;
+    user_id: string;
+    platform_user_id: string;
+    role: string;
+    display_name?: string;
+    email?: string;
+    issued_at: number;
+    expires_at: number;
+}
+/** The resolved viewer. */
+interface ViewerContext {
+    /**
+     * How this was established.
+     *
+     *  - `'verified'` — the signed `X-Sprigr-Viewer` token checked out against
+     *    your install's own key. Authorise on this.
+     *  - `'transport'` — the legacy unsigned header, accepted because the call
+     *    site passed `allowTransportFallback`. Same practical guarantee the
+     *    platform has always given, but nothing was cryptographically checked
+     *    and `displayName` / `email` are never available.
+     */
+    trust: 'verified' | 'transport';
+    /** OIDC sub (`usr_...`) of the viewer, or null when signed out. This is
+     *  what per-actor state keys on. */
+    platformUserId: string | null;
+    /** sprigr-team `users.id` row id, or null when signed out. */
+    userId: string | null;
+    /** Company that owns the install. Null on the legacy channel when the
+     *  header is absent. */
+    companyId: string | null;
+    /** The viewer's role at the company, or null when signed out. */
+    role: string | null;
+    /** Display name. Only ever present on a verified context. DISPLAY ONLY —
+     *  never branch authorisation on it. */
+    displayName: string | null;
+    /** Email. Only ever present on a verified context. DISPLAY ONLY. */
+    email: string | null;
+    /** The install the context was minted for. Null on the legacy channel. */
+    installId: string | null;
+}
+interface ViewerEnv {
+    /** Per-install key the platform derives and binds. Absent on an install
+     *  that has not been rebuilt since the platform started binding it. */
+    SPRIGR_VIEWER_SECRET?: string;
+    /** This install's id, bound by the platform. Used to refuse a context
+     *  minted for a different install. */
+    INSTALL_ID?: string;
+}
+interface ResolveViewerOptions {
+    /**
+     * Accept the legacy unsigned `x-sprigr-platform-user-id` header when no
+     * verified token is available. Defaults to FALSE: a call site that wants
+     * the weaker guarantee has to say so, so the weaker path is visible in
+     * review instead of being the silent default.
+     */
+    allowTransportFallback?: boolean;
+    /** Override the clock, for tests. Epoch seconds. */
+    nowSeconds?: number;
+    /** Override the future-issued tolerance, in seconds. */
+    clockSkewSeconds?: number;
+}
+type ViewerContextFailure = 'missing' | 'no_secret' | 'malformed' | 'bad_signature' | 'expired' | 'not_yet_valid' | 'install_mismatch';
+type ViewerContextVerification = {
+    ok: true;
+    claims: WireClaims;
+} | {
+    ok: false;
+    reason: ViewerContextFailure;
+};
+/**
+ * Verify a raw `X-Sprigr-Viewer` token.
+ *
+ * Most apps want `resolveViewerContext` instead; reach for this when you
+ * need to log or branch on the specific failure reason. Do NOT surface the
+ * reason to the browser: collapse every failure into the same "no viewer"
+ * outcome so a caller learns nothing from probing.
+ *
+ * The signature is checked before any claim, so nothing about an unsigned
+ * payload is observable through the failure reason.
+ */
+declare function verifyViewerToken(token: string | null | undefined, env: ViewerEnv, options?: ResolveViewerOptions): Promise<ViewerContextVerification>;
+/**
+ * Resolve the viewer from a request's headers.
+ *
+ *   const viewer = await resolveViewerContext(request.headers, env);
+ *   if (!viewer?.platformUserId) return jsonError(401, 'sign in to continue');
+ *   // authorise on viewer.platformUserId, render viewer.displayName
+ *
+ * Returns null when there is no viewer at all: no token (or one that did not
+ * verify) and either no legacy header or no `allowTransportFallback`. A
+ * signed-out visitor on a verified context comes back non-null with every id
+ * field null, so an app can tell "nobody is signed in" from "I cannot tell".
+ */
+declare function resolveViewerContext(headers: Headers, env: ViewerEnv, options?: ResolveViewerOptions): Promise<ViewerContext | null>;
+/**
+ * The viewer's platform user id, or null.
+ *
+ * The narrow shape the twelve hand-rolled `viewer.ts` copies exposed, so an
+ * app can migrate onto the SDK in one import change and adopt the richer
+ * context later. `allowTransportFallback` defaults to TRUE here and only
+ * here, because that is exactly what those copies did — an app that wants
+ * the stronger guarantee should call `resolveViewerContext` directly.
+ */
+declare function resolveViewerUserId(headers: Headers, env: ViewerEnv, options?: ResolveViewerOptions): Promise<string | null>;
+
 /**
  * Adapters between the marketplace wrapper's calling convention and an app's
  * inner handler signatures, with fail-closed per-actor authorization built in.
@@ -1088,12 +1250,25 @@ declare function refuseWithoutForce<E>(deleteAction: string, inner: ToolHandler<
  *    `_undo` ON A NULL CAPTURE. A failed capture does not fail the write: the
  *    user asked for it and a human approved it. It degrades to no token.
  *
+ * Every resolver here is gate-level by default and overridable per spec:
+ * `ApprovalSpec.resolveConnection` / `.describeTarget` / `.stampConnection`
+ * win over the gate's for that spec alone. One rule cannot describe two
+ * families of write truthfully, and both consumers of the resolved value are
+ * safety surfaces (the card a person reads, and the grant hash).
+ *
  * Generalised from the Shopify app's `require-approval.ts`; the per-tool
  * questions stay in the app, because only the app knows what cannot be walked
  * back.
  */
-/** Per-tool (or per-action) spec: how the card reads, and (optionally) how to journal a before-image. */
-interface ApprovalSpec<P = unknown> {
+/**
+ * Per-tool (or per-action) spec: how the card reads, and (optionally) how to
+ * journal a before-image.
+ *
+ * `P` is the pinned connection handed to `capture` / `describeTarget`; `E` is
+ * the env a spec-level `resolveConnection` receives. `E` defaults to `unknown`
+ * so `ApprovalSpec<MyState>` keeps working unchanged.
+ */
+interface ApprovalSpec<P = unknown, E = unknown> {
     /**
      * Arg names that may carry the target id, most specific first. ONE list, used
      * for both the card label and the grant hash, so the two cannot drift apart
@@ -1122,6 +1297,27 @@ interface ApprovalSpec<P = unknown> {
      * can ever cover it, which is the safe side but not the useful one.
      */
     count?: (args: ToolArgs) => number;
+    /**
+     * Overrides the gate's `resolveConnection` for THIS spec only; the gate's
+     * value stays the default for every spec that omits it.
+     *
+     * One gate serves every spec, so a gate-level resolver has to pick one rule.
+     * That is wrong the moment an app has two families of write that reach a
+     * connection differently: in meta-ads (sprigr-apps#1462) six creates POST
+     * under an ad account and three address a Graph object by id on a path that
+     * carries no account at all, so the account resolved for the creates was
+     * printed on the delete's card and mixed into its hash while being false.
+     * A resolver returning '' here is the honest answer for such a spec.
+     */
+    resolveConnection?: (env: E, args: ToolArgs) => Promise<string>;
+    /** Overrides the gate's `describeTarget` for this spec only. */
+    describeTarget?: (pinned: P, id: string, name: string) => Promise<string>;
+    /**
+     * Overrides the gate's `stampConnection` for this spec only. The stamp
+     * repeats the card's claim in the agent's "done" report, so a spec that
+     * resolves its own connection usually wants to stamp it its own way too.
+     */
+    stampConnection?: (result: unknown, connection: string) => unknown;
     /** Present only for tools whose write can be (partly) reversed. */
     undo?: UndoCaptureSpec<P>;
 }
@@ -1160,6 +1356,10 @@ interface ApprovalGateOptions<E, P = E> {
      * arguments and the install, canonicalised (a label like "EU store" becomes
      * the real domain). Return '' for a single-connection app. Never read it off
      * the arguments alone: on the retry the model usually omits it.
+     *
+     * This is the DEFAULT for every spec. A spec whose write reaches a
+     * connection by another rule overrides it with
+     * `ApprovalSpec.resolveConnection`.
      */
     resolveConnection: (env: E, args: ToolArgs) => Promise<string>;
     /**
@@ -1172,7 +1372,8 @@ interface ApprovalGateOptions<E, P = E> {
      * back to the id on any miss; never guess, a confidently wrong card is worse
      * than a terse one. Omit to always show the raw id. `name` is the tool, or
      * for a dispatcher the action, so a lookup can route by resource type when
-     * the id alone does not say what it is (an Asana gid).
+     * the id alone does not say what it is (an Asana gid). Overridable per
+     * spec.
      */
     describeTarget?: (pinned: P, id: string, name: string) => Promise<string>;
     /**
@@ -1183,7 +1384,8 @@ interface ApprovalGateOptions<E, P = E> {
     journal?: (env: E) => CaptureJournal;
     /**
      * Stamp the resolved connection onto a successful result (e.g. `{ store }`)
-     * so an agent reporting "deleted it" can name where. Optional.
+     * so an agent reporting "deleted it" can name where. Optional, and
+     * overridable per spec.
      */
     stampConnection?: (result: unknown, connection: string) => unknown;
 }
@@ -1220,7 +1422,7 @@ interface DispatcherApprovalGate<E> {
  * rename that quietly ungated a permanent delete is exactly the failure this
  * guard exists to prevent, and it would look identical to working.
  */
-declare function requireApproval<E>(handlers: Record<string, ToolHandler<E>>, specs: Record<string, ApprovalSpec<E>>, opts: RequireApprovalOptions<E>): Record<string, ToolHandler<E>>;
+declare function requireApproval<E>(handlers: Record<string, ToolHandler<E>>, specs: Record<string, ApprovalSpec<E, E>>, opts: RequireApprovalOptions<E>): Record<string, ToolHandler<E>>;
 /**
  * The same gate for a dispatcher tool (one tool, many actions selected by an
  * input field). Build it once beside the action registry and call `run` from
@@ -1234,7 +1436,7 @@ declare function requireApproval<E>(handlers: Record<string, ToolHandler<E>>, sp
  * params are read from `opts.inputField` (default `input`), or from the
  * top-level args when that field is absent (the flat-verb envelope).
  */
-declare function dispatcherApproval<E, P = E>(specs: Record<string, ApprovalSpec<P>>, opts: DispatcherApprovalOptions<E, P>): DispatcherApprovalGate<E>;
+declare function dispatcherApproval<E, P = E>(specs: Record<string, ApprovalSpec<P, E>>, opts: DispatcherApprovalOptions<E, P>): DispatcherApprovalGate<E>;
 
 /**
  * The reversal entry point every adopting app declares as `undo.reverse_tool`.
@@ -1957,4 +2159,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 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 };
+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 ResolveViewerOptions, 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, 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, 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, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, verifyViewerToken, withSprigrEmitFallback };

package/dist/index.js

@@ -339,6 +339,123 @@ function ownerFromActorKey(key) {
   return null;
 }
 
+// src/viewer.ts
+var VIEWER_CONTEXT_HEADER = "x-sprigr-viewer";
+var VIEWER_PLATFORM_USER_ID_HEADER = "x-sprigr-platform-user-id";
+var VIEWER_USER_ID_HEADER = "x-sprigr-user-id";
+var VIEWER_ROLE_HEADER = "x-sprigr-role";
+var VIEWER_ANONYMOUS = "anonymous";
+var TOKEN_VERSION = "svc1";
+var DEFAULT_CLOCK_SKEW_SECONDS = 60;
+function base64urlDecode2(s) {
+  try {
+    let b64 = s.replace(/-/g, "+").replace(/_/g, "/");
+    while (b64.length % 4 !== 0) b64 += "=";
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+  } catch {
+    return null;
+  }
+}
+async function hmacBytes(secret, message) {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  return new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message)));
+}
+function constantTimeEqualBytes(a, b) {
+  if (a.byteLength !== b.byteLength) return false;
+  let diff = 0;
+  for (let i = 0; i < a.byteLength; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+async function verifyViewerToken(token, env, options = {}) {
+  if (!token) return { ok: false, reason: "missing" };
+  const secret = env.SPRIGR_VIEWER_SECRET;
+  if (!secret) return { ok: false, reason: "no_secret" };
+  const parts = token.split(".");
+  if (parts.length !== 3 || parts[0] !== TOKEN_VERSION) return { ok: false, reason: "malformed" };
+  const payloadB64 = parts[1];
+  const macB64 = parts[2];
+  const provided = base64urlDecode2(macB64);
+  if (!provided) return { ok: false, reason: "malformed" };
+  const expected = await hmacBytes(secret, `${TOKEN_VERSION}.${payloadB64}`);
+  if (!constantTimeEqualBytes(provided, expected)) return { ok: false, reason: "bad_signature" };
+  const payloadBytes = base64urlDecode2(payloadB64);
+  if (!payloadBytes) return { ok: false, reason: "malformed" };
+  let parsed;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(payloadBytes));
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+  const p = parsed;
+  if (!p || typeof p !== "object" || typeof p.install_id !== "string" || !p.install_id || typeof p.company_id !== "string" || !p.company_id || typeof p.user_id !== "string" || !p.user_id || typeof p.platform_user_id !== "string" || !p.platform_user_id || typeof p.role !== "string" || !p.role || typeof p.issued_at !== "number" || !Number.isFinite(p.issued_at) || typeof p.expires_at !== "number" || !Number.isFinite(p.expires_at) || p.display_name !== void 0 && typeof p.display_name !== "string" || p.email !== void 0 && typeof p.email !== "string") {
+    return { ok: false, reason: "malformed" };
+  }
+  const now = options.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  const skew = options.clockSkewSeconds ?? DEFAULT_CLOCK_SKEW_SECONDS;
+  if (now >= p.expires_at) return { ok: false, reason: "expired" };
+  if (p.issued_at - now > skew) return { ok: false, reason: "not_yet_valid" };
+  if (env.INSTALL_ID && p.install_id !== env.INSTALL_ID) {
+    return { ok: false, reason: "install_mismatch" };
+  }
+  return { ok: true, claims: p };
+}
+function anonymousOrValue(raw) {
+  const v = raw?.trim();
+  if (!v || v === VIEWER_ANONYMOUS) return null;
+  return v;
+}
+async function resolveViewerContext(headers, env, options = {}) {
+  const verified = await verifyViewerToken(headers.get(VIEWER_CONTEXT_HEADER), env, options);
+  if (verified.ok) {
+    const c = verified.claims;
+    const platformUserId2 = anonymousOrValue(c.platform_user_id);
+    return {
+      trust: "verified",
+      platformUserId: platformUserId2,
+      userId: anonymousOrValue(c.user_id),
+      companyId: c.company_id,
+      role: anonymousOrValue(c.role),
+      // Display fields are ignored for a signed-out viewer even if a future
+      // platform version were to send them: a name with no identity behind
+      // it has nobody to belong to.
+      displayName: platformUserId2 ? c.display_name ?? null : null,
+      email: platformUserId2 ? c.email ?? null : null,
+      installId: c.install_id
+    };
+  }
+  if (!options.allowTransportFallback) return null;
+  const platformUserId = anonymousOrValue(headers.get(VIEWER_PLATFORM_USER_ID_HEADER));
+  const userId = anonymousOrValue(headers.get(VIEWER_USER_ID_HEADER));
+  if (!platformUserId && !userId) return null;
+  return {
+    trust: "transport",
+    platformUserId,
+    userId,
+    companyId: null,
+    role: anonymousOrValue(headers.get(VIEWER_ROLE_HEADER)),
+    // The legacy channel never carries these.
+    displayName: null,
+    email: null,
+    installId: null
+  };
+}
+async function resolveViewerUserId(headers, env, options = {}) {
+  const viewer = await resolveViewerContext(headers, env, {
+    allowTransportFallback: true,
+    ...options
+  });
+  return viewer?.platformUserId ?? null;
+}
+
 // src/tool-wrappers.ts
 var NotConnectedError = class extends Error {
   constructor(message = "The calling actor has no connection with this app.") {
@@ -641,10 +758,11 @@ async function pin(opts, env, connection) {
   return opts.pinEnv(env, connection);
 }
 async function askPass(name, spec, params, env, opts, hashPrefix) {
-  const connection = await opts.resolveConnection(env, params);
+  const connection = await (spec.resolveConnection ?? opts.resolveConnection)(env, params);
   const rawId = rawIdOf(params, spec.keys);
   const pinned = await pin(opts, env, connection);
-  const target = rawId && opts.describeTarget ? await safeLabel(opts.describeTarget, pinned, rawId, name) : rawId || "(unknown id)";
+  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 count = countOf(spec, params, rawId);
   return {
@@ -657,8 +775,9 @@ async function askPass(name, spec, params, env, opts, hashPrefix) {
   };
 }
 async function grantedPass(name, spec, params, env, opts, write) {
-  const connection = await opts.resolveConnection(env, params);
-  const stamp = (r) => connection && opts.stampConnection ? opts.stampConnection(r, connection) : r;
+  const connection = await (spec.resolveConnection ?? opts.resolveConnection)(env, params);
+  const stampConnection = spec.stampConnection ?? opts.stampConnection;
+  const stamp = (r) => connection && stampConnection ? stampConnection(r, connection) : r;
   const undo = spec.undo;
   const id = rawIdOf(params, spec.keys);
   if (!undo || !id) return stamp(await write());
@@ -1054,6 +1173,11 @@ export {
   InvalidUndoEnvelopeError,
   NotConnectedError,
   UNIT_SEP,
+  VIEWER_ANONYMOUS,
+  VIEWER_CONTEXT_HEADER,
+  VIEWER_PLATFORM_USER_ID_HEADER,
+  VIEWER_ROLE_HEADER,
+  VIEWER_USER_ID_HEADER,
   actorKey,
   actorTool,
   appFileUrl,
@@ -1102,6 +1226,8 @@ export {
   resolveOAuthBouncerBase,
   resolveOAuthBouncerCallbackUrl,
   resolvePlatformWebhookBase,
+  resolveViewerContext,
+  resolveViewerUserId,
   runUndoApply,
   safeCapture,
   seq,
@@ -1109,5 +1235,6 @@ export {
   set,
   tool,
   undoEnvelope,
+  verifyViewerToken,
   withSprigrEmitFallback
 };

package/package.json

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