@usequeek/app-sdk 0.5.0 → 0.6.0

package/README.md

@@ -1,5 +1,7 @@
 # @usequeek/app-sdk
 
+> In development — not yet released. APIs may change before 1.0.
+
 The SDK for building a Queek app on the public Merchant API and signed webhooks. Framework-agnostic Web-standard handlers for the install handoff and topic webhooks (`Request` in, `Response` out — use them from Next.js route handlers, Express, or any runtime), a typed Merchant API client (types generated from the live contract), GitHub-style app credentials (one asymmetric key per app, short-lived per-installation tokens minted on demand), resync recovery, and an encrypted installation store (SQLite for local/test, Postgres in production). Optional Hono wrappers live under `@usequeek/app-sdk/hono`.
 
 ```sh
@@ -28,7 +30,7 @@ const store = new SqliteInstallationStore({
   storeKey: process.env.APP_ENCRYPTION_KEY!,
 });
 const tokens = createAppTokenProvider({
-  credential: loadAppCredential({ appSlug: "hello" }), // APP_SLUG/APP_KEY_ID/APP_PRIVATE_KEY
+  credential: loadAppCredential({ appSlug: "hello" }), // APP_SLUG/APP_KEY_ID/APP_PRIVATE_KEY (base64 of the PEM, one line)
   store,
 });
 const installOptions = { appSecret: process.env.QUEEK_APP_SECRET!, store };
@@ -126,7 +128,7 @@ Signature verification covers the exact bytes Queek sent (`{id}.{timestamp}.{bod
 
 ### Body-size posture
 
-The SDK itself imposes no maximum body size (`arrayBuffer` / `TextDecoder` / `JSON.parse` are unbounded, as in 0.4.0) — the cap belongs to the framework parser in front of it, which already rejects oversized bodies before the SDK ever sees them. Queek deliveries are small JSON payloads, so the framework defaults are plenty; if you set them explicitly, `express.raw({ type: "application/json", limit: "1mb" })` and Fastify's default `bodyLimit` of 1 MiB are the recommended ceilings. No SDK option is needed unless Queek ever ships large deliveries.
+The SDK itself imposes no maximum body size (`arrayBuffer` / `TextDecoder` / `JSON.parse` are unbounded) — the cap belongs to the framework parser in front of it, which already rejects oversized bodies before the SDK ever sees them. Queek deliveries are small JSON payloads, so the framework defaults are plenty; if you set them explicitly, `express.raw({ type: "application/json", limit: "1mb" })` and Fastify's default `bodyLimit` of 1 MiB are the recommended ceilings. No SDK option is needed unless Queek ever ships large deliveries.
 
 (If you already run Hono on Node, `@hono/node-server`'s `getRequestListener` bridges serving for you — but the adapters above need no extra dependency.)
 
@@ -162,8 +164,6 @@ app.route(
 export default app;
 ```
 
-> Migrating from 0.4.x: `import { createInstallHandlers } from "@usequeek/app-sdk/hono"` — the creators moved out of the root entry so non-Hono apps never install `hono`. The options objects are unchanged.
-
 Every Merchant API call goes through `createInstallationClient({ installationId, apiBase, tokens })`,
 which resolves the installation's token via `acquireToken()` and sends it as `X-Client-Key`.
 
@@ -187,7 +187,8 @@ One asymmetric credential per app — no per-installation secrets cross the hand
 
    Queek prints the app secret (`QUEEK_APP_SECRET`, verifies the handoff) and the key id
    (`APP_KEY_ID`, rides the JWT `kid` header). Configure the app with `APP_SLUG` (= `iss`),
-   `APP_KEY_ID`, and `APP_PRIVATE_KEY` (the PEM — never logged, never shipped to clients).
+   `APP_KEY_ID`, and `APP_PRIVATE_KEY` (base64 of the private key PEM, one line — the
+   Developer page shows it; raw PEM also accepted — never logged, never shipped to clients).
 
 3. **Acquire / cache / re-mint.** `acquireToken(installationId)` serves the cached token while
    its expiry is more than 5 minutes away; otherwise it signs an RS256 app JWT
@@ -246,10 +247,49 @@ settings) does NOT come back from resync: it needs the per-app `pg_dump` backup
 (RPO ≤ 24 h) plus the `APP_ENCRYPTION_KEY` backup. Events missed beyond Queek's webhook
 retries (~4 h) are gone; resync cannot backfill them. Full runbook: `docs/deploy.md` + O1.
 
+## Data deletion
+
+Treat the uninstall handoff (`app/uninstalled`) as the deletion trigger: the default
+`onUninstall` already deletes the installation row (secrets, token cache, settings) —
+keep that delete when you override it, and purge any app-side working data keyed by the
+installation there too.
+
+Unknown topics answer 200 without running a handler (forward compatibility, not consent):
+that 200 must not swallow a future privacy topic. If Queek ships mandatory privacy
+topics, register explicit handlers for them — an unhandled topic only reports
+`unhandled: true`, it deletes nothing.
+
+## Storefront app-proxy (signed reads)
+
+Queek signs each storefront proxy fetch with the installation's `proxy_secret`
+(`AppProxyService::signQuery`); verify before answering the shopper:
+
+```ts
+import { handleProxyRequest } from "@usequeek/app-sdk";
+
+export async function GET(request: Request) {
+  return handleProxyRequest(
+    request,
+    { store, path: "/apps/booking/availability" }, // Queek-side canonical path, not the local route
+    ({ installation, params }) =>
+      Response.json({ slots: slotsFor(params.date, installation.storePid) }),
+  );
+}
+```
+
+The canonical string is `path + "\n" + shop + "\n" + ts + "\n" + sorted(k=v&...)`
+(`sig` excluded), hex HMAC-SHA256 over the FULL `whsec_…` string — no base64 decode
+step. `kid` routes to the installation whose `proxy_secret` verifies (previous-secret
+grace: pass every active secret to `verifyProxyQuery`); timestamps skew at most 5
+minutes, each `jti` is single-use, and only `GET` is served (phase 1 is read-only).
+Hono: mount `createProxyHandler({ store, path, onVerified })` from
+`@usequeek/app-sdk/hono`.
+
 ## API surface
 
-- **app-auth** (`app-auth.ts`): `loadAppCredential` (`APP_SLUG`/`APP_KEY_ID`/`APP_PRIVATE_KEY`,
-  PEM validated at boot), `signAppJwt` (RS256, `iat` now − 60 s, `exp` window 540 s ≤ 600 s,
+- **app-auth** (`app-auth.ts`): `loadAppCredential` (`APP_SLUG`/`APP_KEY_ID`/`APP_PRIVATE_KEY`
+  — base64 of the PEM, raw PEM, or `\n`-escaped one-line PEM; RSA validated at boot),
+  `signAppJwt` (RS256, `iat` now − 60 s, `exp` window 540 s ≤ 600 s,
   `kid` header), the wire-contract error codes in one place (`INVALID_CLIENT_CODE`,
   `APP_TOKEN_REVOKED_CODE`, `APP_INSTALLATION_GONE_CODE`, `APP_INSTALLATION_PENDING_CODE`,
   `RESYNC_COOLDOWN_CODE`, `TOO_MANY_REQUESTS_CODE`), `AppMintHaltedError`.
@@ -265,8 +305,9 @@ retries (~4 h) are gone; resync cannot backfill them. Full runbook: `docs/deploy
 - **verify** (`signatures.ts`): `verifyQueekSignature` — Standard Webhooks verification (`webhook-id`, `webhook-timestamp`, `webhook-signature` over `{id}.{timestamp}.{body}`, keyed by the decoded `whsec_…` bytes), with timestamp-skew enforcement.
 - **delivery core** (`delivery.ts`): `CoreDelivery` (`rawBody` + `headers`) / `InstallDelivery` (+ `method`/`path`) / `DeliveryResult` (`{ status, body }`) / `CoreHeaders`, plus `readHeader` (case-insensitive, array-tolerant), `decodeBody`, and `toResponse`. Zero request/response types.
 - **install handlers** (`install-handlers.ts`): layer 1 `handleInstallDelivery(input, { appSecret, store, onInstall?, onUninstall?, onSettings? })` serves the signed install/uninstall/settings handoff from raw bytes + headers (routes on the path's trailing segment); layer 2 `handleInstallRequest(request, …)` adapts `Request` → `Response` onto it. Defaults persist the installation (encrypted) in the store; a redelivered install for an existing installation merges idempotently (`saveResyncedInstallation`). The Hono wrapper `createInstallHandlers` lives under `@usequeek/app-sdk/hono` (`hono.ts`).
-- **client** (`client.ts`): `createQueekClient({ apiBase, apiKey })` — the low-level typed fetch client over the Merchant API (`X-Client-Key`), with `Idempotency-Key` on writes, typed `QueekApiError`s, and 429 retry helpers. Types come from `openapi/merchant.json`, the committed snapshot of the live contract. Prefer `createInstallationClient` in apps.
-- **webhooks** (`webhooks.ts`): layer 1 `handleWebhookDelivery(input, { store, handlers })` verifies each delivery against the installation's endpoint secret, dedupes on `webhook-id`, and dispatches `topic → handler` at most once; layer 2 `handleWebhookRequest(request, …)` adapts `Request` → `Response` onto it. The Hono wrapper `createWebhookHandler` lives under `@usequeek/app-sdk/hono` (`hono.ts`).
+- **client** (`client.ts`): `createQueekClient({ apiBase, apiKey })` — the low-level typed fetch client over the Merchant API (`X-Client-Key`), with `Idempotency-Key` on writes, typed `QueekApiError`s, and 429 retry helpers. Both it and `createInstallationClient({ installationId, apiBase, tokens })` are generic (`<AppPaths>`, default: the bundled `merchant-schema.ts` compat shim): pass the app's own codegen output for current types with zero SDK publish. The default does NOT auto-update (re-run codegen in the app; sunset signal at 1.0). `openapi/merchant.json` stays in-repo as `gen:merchant`'s reference input and is not shipped in the published package. Prefer `createInstallationClient` in apps.
+- **webhooks** (`webhooks.ts`): layer 1 `handleWebhookDelivery(input, { store, handlers })` verifies each delivery against the installation's endpoint secret, dedupes on `webhook-id`, and dispatches `topic → handler` at most once; layer 2 `handleWebhookRequest(request, …)` adapts `Request` → `Response` onto it. The Hono wrapper `createWebhookHandler` lives under `@usequeek/app-sdk/hono` (`hono.ts`). Unknown topics answer 200 `unhandled` — see Data deletion before relying on that.
+- **proxy** (`proxy.ts`): `verifyProxyQuery` / `verifyProxyQueryDetailed` — app-proxy query verification byte-exact with the backend (`path\nshop\nts\nsorted(k=v&...)`, hex HMAC-SHA256 over the FULL `whsec_…` string, 5-minute skew floored at 60 s, `timingSafeEqual`, previous-secret grace over the secrets list); layer 1 `verifyProxyDelivery(input, { store, … })` resolves the installation from the store by `kid` and claims single-use `jti`; layer 2 `handleProxyRequest(request, { store, path, … }, onVerified)` serves GET only. The Hono wrapper `createProxyHandler` lives under `@usequeek/app-sdk/hono` (`hono.ts`).
 - **store** (`store.ts`): `SqliteInstallationStore` (local/dev/test) and `PostgresInstallationStore`
   (`pg`, pool max 2, advisory-locked schema + `schema_version` row so two containers boot
   safely) — installations encrypted at rest (AES-GCM via `APP_ENCRYPTION_KEY`), plus the
@@ -282,16 +323,128 @@ retries (~4 h) are gone; resync cannot backfill them. Full runbook: `docs/deploy
   PEM private-key blocks — the app JWT and private key can never reach logs.
 - **session** (`session.ts`, server-only via `@usequeek/app-sdk/server`):
   `verifySessionToken` — HS256 dashboard session tokens minted per installation
-  (`embsec_…` secret, raw UTF-8 key bytes, 20 s clock tolerance, slug audience
-  + api_base issuer, full installation binding). The secret never enters a
+  (`embsec_…` secret, raw UTF-8 key bytes, 20 s clock tolerance, slug audience,
+  issuer = the handoff `apiBase` verbatim (`installation.apiBase` — it equals the
+  bare `app.url` the backend signs as `iss`), full installation binding). The secret never enters a
   browser bundle: the main entry does not export the verifier. The install
   and resync handoffs deliver `embed_secret` + `app_id`; the store keeps
   them on the installation (`embedSecret` encrypted, `appId`), and
   `sessionTokenInstallationId` reads the token's `installation_id` as an
   unverified routing hint so a server can load that row before verifying.
-- **frame** (`frame.ts`, browser-safe, no secret): `listenToDashboard`
-  (accepts only the exact dashboard origin) and `sendReady` (exact target
-  origin, never `"*"`).
+  `verifyLaunchToken` checks the signed-first-load token the same way plus the purpose pin
+  (`purpose` must be `launch`, with the `store` p_id and `theme` hints) — a launch token is refused
+  as a bridge token and vice versa.
+- **frame** (`frame.ts`, browser-safe, no secret): the embedded-app bridge
+  v1 — typed unions both directions (`ready{capabilities,sdkVersion}`,
+  `theme`, `title`/`title-action`, `toast`, `save-bar`/`save-bar-action`,
+  `navigate`/`navigated`, `open`, `pick-resource`/`resource-picked`/
+  `resource-pick-cancelled`), unknown types ignored, every outbound string
+  length-capped client-side. `listenToDashboard` (accepts only the exact
+  dashboard origin, plus an `expectSource` window check) and typed senders
+  (`sendReady`, `sendToast`, `sendSaveBar`, `sendTitle`, `sendNavigated`,
+  `sendOpen`, `sendPickResource`, …) to the exact target origin, never `"*"`.
+  `parseOutboundMessage` runs the same per-type validation the dashboard
+  runs — the dashboard re-validates everything before acting (open targets,
+  title/toast/pick content), so a compromised frame cannot smuggle
+  `javascript:` URLs or uncapped strings through the bridge. `open` targets
+  are a dashboard-relative path or an absolute `https:` URL; backslashes,
+  control characters, protocol-relative URLs and every other scheme are
+  refused (by `clipOutbound` as well as `isAllowedOpenTarget`).
+
+  **Bridge handshake.** The app announces `ready{capabilities,sdkVersion}`;
+  the dashboard answers with its `theme` message, which also declares the
+  DASHBOARD's capabilities: `{ type: "theme", mode, locale?, capabilities?:
+  string[], bridge?: "1" }` (same caps as outbound: at most 32 entries of 64
+  characters). `listenToDashboard` exposes both on the `BridgeTheme` passed to
+  `onTheme`. A dashboard that omits `capabilities` is legacy (ready/token/
+  resize only). `<QueekProvider>` stores the declared set: `pickResource`
+  rejects at once when it lacks `pick-resource`, waits up to 1.5 s after
+  `ready` when the set is still unknown, and rejects if no handshake arrives.
+  Each pick carries a `requestId` (on `pick-resource`); a dashboard that
+  declares `pick-resource` MUST echo it on `resource-picked` / `resource-pick-cancelled` — answers with a
+  different or missing id are dropped as stale.
+- **auth** (`auth-fetch.ts`, browser-safe, no secret): `installAuthFetch({ exchange })`
+  — reads the launch token (`queek_token` query param) from the signed first
+  load, strips it with `history.replaceState`, exchanges it once for the
+  app's own session, attaches `Authorization: Bearer <session>` to
+  same-origin fetch (cookies stay out), and re-establishes via the bridge
+  `ready→token` flow + one retry on 401. Session recovery runs only when framed (a post target other than the
+  window itself) and is not retried per request after a failed attempt — only
+  after a later dashboard token arrives. Pass the same `capabilities`/
+  `sdkVersion` as the provider so its refresh `ready` announces one consistent set. The app's
+  token-exchange endpoint receives the LAUNCH token on first load and a BRIDGE token on every
+  401 refresh through the same `exchange` callback, so it must try
+  `verifyLaunchTokenDetailed`/`verifyLaunchToken` first and fall back to `verifySessionToken`
+  (both purposes):
+
+  ```ts
+  import { verifyLaunchTokenDetailed, verifySessionTokenDetailed } from "@usequeek/app-sdk/server";
+
+  async function exchange(token: string): Promise<string> {
+    const options = { secret: installation.embedSecret!, audience: "my-app", issuer: installation.apiBase, expected };
+    const launch = await verifyLaunchTokenDetailed(token, options);
+    if (launch.ok) return mintAppSession(launch.claims);
+    const bridge = await verifySessionTokenDetailed(token, options);
+    if (bridge.ok) return mintAppSession(bridge.claims);
+    throw Object.assign(new Error("unauthorized"), { status: 401 });
+  }
+  ```
+- **theme** (`theme.ts`, browser-safe, no secret): `applyTheme(mode)` toggles
+  `.dark` on `<html>` + `color-scheme` (shadcn's dark-mode mechanism);
+  `themeBootstrapScript()` returns the inline `<head>` snippet that reads
+  `theme` from the URL before first paint (no flash);
+  `installThemeListener` follows live bridge `theme{mode}` messages (only from
+  `window.parent` by default; pass `expectSource` to override). The live mode is
+  remembered in `sessionStorage`, and the bootstrap script falls back to it when
+  the URL carries no `theme` param, so an in-frame reload never flashes light. Every live `theme` message also
+  rewrites the `theme` URL param (other params kept) so a stale first-load param
+  never beats the current mode on reload, and the first-load mode is remembered
+  too (a legacy dashboard that never sends `theme` still reloads flash-free).
+- **react** (`react.ts`, via `@usequeek/app-sdk/react` — `react` is an
+  optional peer, same pattern as `./hono`): `<QueekProvider>` owns one
+  bridge subscription; `useQueek()` returns `{ toast, saveBar, title,
+  navigate, pickResource, theme }` over the framework-free core.
+- **scopes** (`scopes.ts`): `createInstallationScopesClient({ installationId, store, signJwt, … })`
+  — the optional-scopes session, wired to the same store + token provider as the
+  installation client. `queryScopes` reads the cached grant (no network);
+  `requestScopes` builds the dashboard consent link (pure — the SDK never
+  renders consent); `revokeScopes` posts the app-authenticated revoke and
+  refreshes the cache. The install/settings handlers accept the signed
+  `app/scopes_update` handoff on both routes and refresh the cached grant
+  (dropping the cached token when it moved).
+
+## Scopes
+
+Apps declare required scopes (granted at install) plus optional scopes
+(requested later, revocable). The per-installation session covers the app side:
+
+```ts
+import { createInstallationScopesClient } from "@usequeek/app-sdk";
+
+const scopes = createInstallationScopesClient({
+  installationId,
+  store,
+  signJwt: () => provider.signJwt(),
+  appSlug: "my-app",
+  optionalScopes: ["merchant-orders-read"], // the app's own manifest knowledge
+});
+
+await scopes.queryScopes(); // { granted, optional } — cached, no network
+scopes.requestScopes(["merchant-orders-read"]); // dashboard consent link (open via sendOpen)
+await scopes.revokeScopes(["merchant-orders-read"]); // 422 app_scope_required → AppScopeRequiredError
+```
+
+`queryScopes` splits the cached effective grant against the declared-optional
+list you pass (the app surface exposes the grant but no declared list, so the
+split needs your manifest knowledge). `requestScopes` returns
+`/apps?app={slug}&view=scopes&scopes={a},{b}` (absolute under
+`dashboardOrigin` when configured) — open it via `sendOpen` or a redirect: it
+opens the merchant's consent screen in the dashboard (shipped with dashboard
+item 8). The link carries the slug + the scope list only; the dashboard
+resolves the installation from the signed-in store. The grant reaches you as a
+signed `app/scopes_update` handoff, which the install/settings handlers apply
+like a resync (same verifier, same replay claim): cached grant refreshed,
+cached token dropped only when the grant moved.
 
 ## Embedded merchant page (S4 stage 2)
 
@@ -307,8 +460,11 @@ Content-Security-Policy: frame-ancestors https://merchant.queek.com
 Replace the host with the dashboard origin you registered. `frame-ancestors`
 is a docs-only control the dashboard cannot enforce for you: without it any
 site may frame the page, and the token handshake (origin-bound) is your only
-remaining gate. Verify every token server-side with `verifySessionToken`
-before trusting calls that carry one.
+remaining gate. Verify every token server-side before trusting calls that carry one:
+the token-exchange endpoint receives the LAUNCH token on first load and a BRIDGE token on
+every 401 refresh through the same `installAuthFetch({ exchange })` callback, so it must try
+`verifyLaunchTokenDetailed`/`verifyLaunchToken` first and fall back to `verifySessionToken`
+(both purposes — see the `auth` entry above).
 
 ## Local development
 

package/dist/app-auth.d.ts

@@ -38,6 +38,12 @@ export declare const APP_INSTALLATION_PENDING_CODE = "app_installation_pending";
 export declare const RESYNC_COOLDOWN_CODE = "resync_cooldown";
 /** 429 everywhere: honor `Retry-After`, jittered. */
 export declare const TOO_MANY_REQUESTS_CODE = "too_many_requests";
+/**
+ * 403 on a merchant call: the cached installation token was minted for an
+ * older grant (missing scope). The grant changed server-side — drop the
+ * cached token, re-mint once, retry once.
+ */
+export declare const INSUFFICIENT_SCOPE_CODE = "insufficient_scope";
 /** True when a Queek error code is the kill-switch/disabled refusal. */
 export declare function isAppTokenRevoked(code: string | undefined): boolean;
 /** True when a Queek error code is the fatal app-credential refusal. */
@@ -53,7 +59,7 @@ export declare function isResyncCooldown(code: string | undefined): boolean;
  * is dead — drop it, re-mint once, retry once. `api_key_revoked` covers the
  * uninstalled store, the removed kid, and the replaced K-slot; the re-mint
  * then answers 404 `app_installation_gone` (purge) or 401 `invalid_client`
- * (halt) where applicable. Every OTHER merchant 403 (scope, plan, mode)
+ * (halt) where applicable. Every OTHER merchant 403 (plan, mode)
  * propagates to the caller without a mint.
  */
 export declare const API_KEY_REVOKED_CODE = "api_key_revoked";
@@ -66,6 +72,8 @@ export declare const INVALID_CLIENT_KEY_CODE = "invalid_client_key";
  * halt), not a single dead token.
  */
 export declare function isTokenRefusal(status: number, code: string | undefined): boolean;
+/** True when a merchant-API 403 means the cached token predates a grant change. */
+export declare function isInsufficientScope(status: number, code: string | undefined): boolean;
 /** App-JWT `iat` is backdated this far (clock skew, GitHub's recommendation). */
 export declare const APP_JWT_SKEW_SECONDS = 60;
 /** App-JWT lifetime: `exp = iat + 540`, so `exp − iat` (540 s) stays ≤ the 600 s wire bound. */
@@ -117,9 +125,22 @@ export interface AppCredentialOptions {
     privateKeyPem?: string;
     env?: NodeJS.ProcessEnv;
 }
+/**
+ * Accepted `APP_PRIVATE_KEY` forms (env files are one line per variable):
+ * raw PEM text, one-line PEM with literal `\n` escapes, or base64 of the
+ * full PEM text (one line, no wrapping — what the Developer page shows).
+ */
+export declare const APP_PRIVATE_KEY_FORMS = "raw PEM text, one-line PEM with literal \\n escapes, or base64 of the PEM text";
+/**
+ * Normalize an `APP_PRIVATE_KEY` value to PEM text. Detection: a trimmed
+ * value starting with `-----BEGIN` is PEM (literal `\n` unescaped first);
+ * anything else is base64-decoded and must decode to `-----BEGIN…`.
+ * Never echoes the value.
+ */
+export declare function decodePrivateKeyInput(raw: string): string;
 /**
  * Load the app credential: explicit options win, otherwise `APP_SLUG`,
- * `APP_KEY_ID`, `APP_PRIVATE_KEY` from env. The PEM must parse as an RSA
+ * `APP_KEY_ID`, `APP_PRIVATE_KEY` from env. The key must parse as an RSA
  * private key here, once, so a broken key fails at boot — never mid-mint.
  * Throws `InvalidAppCredentialError` before any fetch.
  */

package/dist/app-auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-auth.d.ts","sourceRoot":"","sources":["../src/app-auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app-auth.d.ts","sourceRoot":"","sources":["../src/app-auth.ts"],"names":[],"mappings":"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"}

package/dist/app-auth.js

@@ -44,6 +44,12 @@ export const APP_INSTALLATION_PENDING_CODE = "app_installation_pending";
 export const RESYNC_COOLDOWN_CODE = "resync_cooldown";
 /** 429 everywhere: honor `Retry-After`, jittered. */
 export const TOO_MANY_REQUESTS_CODE = "too_many_requests";
+/**
+ * 403 on a merchant call: the cached installation token was minted for an
+ * older grant (missing scope). The grant changed server-side — drop the
+ * cached token, re-mint once, retry once.
+ */
+export const INSUFFICIENT_SCOPE_CODE = "insufficient_scope";
 /** True when a Queek error code is the kill-switch/disabled refusal. */
 export function isAppTokenRevoked(code) {
     return code === APP_TOKEN_REVOKED_CODE;
@@ -69,7 +75,7 @@ export function isResyncCooldown(code) {
  * is dead — drop it, re-mint once, retry once. `api_key_revoked` covers the
  * uninstalled store, the removed kid, and the replaced K-slot; the re-mint
  * then answers 404 `app_installation_gone` (purge) or 401 `invalid_client`
- * (halt) where applicable. Every OTHER merchant 403 (scope, plan, mode)
+ * (halt) where applicable. Every OTHER merchant 403 (plan, mode)
  * propagates to the caller without a mint.
  */
 export const API_KEY_REVOKED_CODE = "api_key_revoked";
@@ -87,6 +93,10 @@ export function isTokenRefusal(status, code) {
     return (status === 403 &&
         (code === API_KEY_REVOKED_CODE || code === API_KEY_EXPIRED_CODE || code === INVALID_CLIENT_KEY_CODE));
 }
+/** True when a merchant-API 403 means the cached token predates a grant change. */
+export function isInsufficientScope(status, code) {
+    return status === 403 && code === INSUFFICIENT_SCOPE_CODE;
+}
 // ---------------------------------------------------------------------------
 // Timing bounds (all in the open, all injectable in tests).
 // ---------------------------------------------------------------------------
@@ -140,9 +150,32 @@ export class UnknownInstallationError extends Error {
         this.name = "UnknownInstallationError";
     }
 }
+/**
+ * Accepted `APP_PRIVATE_KEY` forms (env files are one line per variable):
+ * raw PEM text, one-line PEM with literal `\n` escapes, or base64 of the
+ * full PEM text (one line, no wrapping — what the Developer page shows).
+ */
+export const APP_PRIVATE_KEY_FORMS = "raw PEM text, one-line PEM with literal \\n escapes, or base64 of the PEM text";
+/**
+ * Normalize an `APP_PRIVATE_KEY` value to PEM text. Detection: a trimmed
+ * value starting with `-----BEGIN` is PEM (literal `\n` unescaped first);
+ * anything else is base64-decoded and must decode to `-----BEGIN…`.
+ * Never echoes the value.
+ */
+export function decodePrivateKeyInput(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith("-----BEGIN")) {
+        return trimmed.replace(/\\n/g, "\n").trim();
+    }
+    const decoded = Buffer.from(trimmed, "base64").toString("utf8");
+    if (!decoded.trimStart().startsWith("-----BEGIN")) {
+        throw new InvalidAppCredentialError(`Invalid APP_PRIVATE_KEY: not a PEM and not base64 of a PEM. Accepted forms: ${APP_PRIVATE_KEY_FORMS}.`);
+    }
+    return decoded.trim();
+}
 /**
  * Load the app credential: explicit options win, otherwise `APP_SLUG`,
- * `APP_KEY_ID`, `APP_PRIVATE_KEY` from env. The PEM must parse as an RSA
+ * `APP_KEY_ID`, `APP_PRIVATE_KEY` from env. The key must parse as an RSA
  * private key here, once, so a broken key fails at boot — never mid-mint.
  * Throws `InvalidAppCredentialError` before any fetch.
  */
@@ -156,10 +189,11 @@ export function loadAppCredential(options = {}) {
     if (keyId === "") {
         throw new InvalidAppCredentialError("Missing APP_KEY_ID: set it to the kid registered with Queek (`php artisan app:register --public-key=…`).");
     }
-    const privateKeyPem = (options.privateKeyPem ?? env.APP_PRIVATE_KEY ?? "").trim();
-    if (privateKeyPem === "") {
-        throw new InvalidAppCredentialError("Missing APP_PRIVATE_KEY: set it to the app's PEM-encoded RSA private key.");
+    const privateKeyInput = (options.privateKeyPem ?? env.APP_PRIVATE_KEY ?? "").trim();
+    if (privateKeyInput === "") {
+        throw new InvalidAppCredentialError(`Missing APP_PRIVATE_KEY: set it to base64 of the app's RSA private key PEM (one line). Accepted forms: ${APP_PRIVATE_KEY_FORMS}.`);
     }
+    const privateKeyPem = decodePrivateKeyInput(privateKeyInput);
     try {
         const key = createPrivateKey(privateKeyPem);
         if (key.asymmetricKeyType !== "rsa") {
@@ -169,7 +203,7 @@ export function loadAppCredential(options = {}) {
     catch (error) {
         if (error instanceof InvalidAppCredentialError)
             throw error;
-        throw new InvalidAppCredentialError(`Invalid APP_PRIVATE_KEY: not a parseable PEM private key (${error instanceof Error ? error.message : "undecodable"}).`);
+        throw new InvalidAppCredentialError(`Invalid APP_PRIVATE_KEY: not a parseable PEM private key (${error instanceof Error ? error.message : "undecodable"}). Accepted forms: ${APP_PRIVATE_KEY_FORMS}.`);
     }
     // The PEM stays in this object only; callers must never log it (see
     // `signAppJwt`: the only consumer, and it never emits the key).

package/dist/app-auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"app-auth.js","sourceRoot":"","sources":["../src/app-auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app-auth.js","sourceRoot":"","sources":["../src/app-auth.ts"],"names":[],"mappings":"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"}

package/dist/auth-fetch.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Same-origin session carriage for embedded apps (U-validation "Auth
+ * carriage"): `installAuthFetch()` reads the launch token from the signed
+ * first load, exchanges it ONCE for the app's own session, and attaches
+ * `Authorization: Bearer <session>` to every same-origin fetch. A 401
+ * re-establishes the session via the bridge `ready→token` flow and retries
+ * once. Cookies stay out (`credentials: "omit"` on handled requests —
+ * the cross-site iframe cannot rely on them anyway).
+ *
+ * The caller supplies `exchange(token) => session`: the app's own endpoint
+ * that verifies the dashboard token server-side and mints the app
+ * session — the exchange runs once on the signed first load so the first
+ * paint needs no bridge round-trip, and again (same callback) with a
+ * bridge token after every 401 refresh. The endpoint therefore receives
+ * the LAUNCH token on first load and a BRIDGE token on every refresh, so
+ * it must try `verifyLaunchTokenDetailed`/`verifyLaunchToken` first and
+ * fall back to `verifySessionToken` (both purposes). This module never
+ * sees secrets — it only carries opaque tokens.
+ *
+ * DOM-free by design (like `frame.ts`): location/history access is
+ * injectable and defaults to the global window when present.
+ */
+import { type EmbedEventTarget, type EmbedPostTarget } from "./frame.js";
+/**
+ * Launch token query param on the signed first load. Matches the dashboard
+ * frame src contract (`launchFrameUrl` in queek-merchant: the ONLY token
+ * that may ride a URL, namespaced so it cannot collide with an app's own
+ * `token` param).
+ */
+export declare const LAUNCH_TOKEN_PARAM = "queek_token";
+/** How long to wait for the dashboard's token reply after a `ready`. */
+export declare const BRIDGE_TOKEN_TIMEOUT_MS = 8000;
+export interface AuthFetchOptions {
+    /**
+     * Exchange a dashboard token for the app's own session (caller's endpoint).
+     * The endpoint receives the LAUNCH token on first load and a BRIDGE token
+     * on every 401 refresh through this same callback, so it must try
+     * `verifyLaunchTokenDetailed`/`verifyLaunchToken` first and fall back to
+     * `verifySessionToken` (both purposes).
+     */
+    exchange: (token: string) => Promise<string>;
+    /** Exact dashboard origin for the `ready→token` refresh flow. */
+    dashboardOrigin: string;
+    /** Launch-token query param (default `queek_token`). */
+    param?: string;
+    /** postMessage target for `ready` (defaults to the global window's parent). */
+    postTarget?: EmbedPostTarget;
+    /**
+     * Capabilities announced in the refresh `ready` — pass the SAME list as the
+     * React provider / theme listener so the dashboard sees one consistent set.
+     */
+    capabilities?: string[];
+    /** SDK version announced in the refresh `ready`. */
+    sdkVersion?: string;
+    /** message-event target for the token reply (defaults to the global window). */
+    listenTarget?: EmbedEventTarget;
+    /**
+     * Required `event.source` for bridge messages. Defaults to the global
+     * window's parent when present (the embedding dashboard); pass `null` to
+     * disable the source check.
+     */
+    expectSource?: unknown;
+    /** fetch implementation (defaults to the global fetch). */
+    fetchImpl?: typeof fetch;
+    /** Current href (defaults to the global window location). */
+    getHref?: () => string;
+    /** Replace the URL without navigating (defaults to history.replaceState). */
+    replaceUrl?: (url: string) => void;
+}
+export interface InstalledAuth {
+    /** Session-carrying fetch: same-origin requests gain the session as a Bearer token, and a 401 retries once after a refresh. */
+    fetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+    /** Current app session, or null before the exchange settles / without a token. */
+    getSession: () => string | null;
+    /** Settles to the session, or null when there is no launch token to exchange. */
+    ready: Promise<string | null>;
+    /** Re-establish the session via the bridge `ready→token` flow. */
+    refresh: () => Promise<string>;
+    /** Unsubscribe the bridge token listener. */
+    dispose: () => void;
+}
+/** Read the launch token from a URL without touching it. */
+export declare function readLaunchToken(href: string, param?: string): string | null;
+/**
+ * Strip the launch token from a URL (every other param, plus the hash, is
+ * preserved). Returns the stripped href, or null when no token is present.
+ */
+export declare function stripLaunchToken(href: string, param?: string): string | null;
+export declare function installAuthFetch(options: AuthFetchOptions): InstalledAuth;
+//# sourceMappingURL=auth-fetch.d.ts.map

package/dist/auth-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-fetch.d.ts","sourceRoot":"","sources":["../src/auth-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAgC,MAAM,YAAY,CAAC;AAEvG;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAEhD,wEAAwE;AACxE,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,iEAAiE;IACjE,eAAe,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;IACvB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,+HAA+H;IAC/H,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChF,kFAAkF;IAClF,UAAU,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAChC,iFAAiF;IACjF,KAAK,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9B,kEAAkE;IAClE,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,6CAA6C;IAC7C,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAeD,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAA2B,GAAG,MAAM,GAAG,IAAI,CAO/F;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAA2B,GAAG,MAAM,GAAG,IAAI,CAWhG;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,aAAa,CAqNzE"}