@usequeek/app-sdk 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+All notable changes to `@usequeek/app-sdk` are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.2.0] - 2026-09-25
+
+GitHub-style app credentials (slice S1 of `app-credentials-and-databases`, built against the
+`/api/v1/apps` wire contract in parallel with the backend B1/B2 — the backend is not deployed yet).
+
+### Changed
+
+- **BREAKING:** the install handoff no longer carries a store-callable `api_key`, and the store
+  no longer has an `api_key_enc` column. Installations cache one minted token instead
+  (`token_enc` + `token_expires_at` + `token_kid`); opening a 0.1.x SQLite database migrates it
+  (legacy key ciphertext is discarded — minted tokens replace it).
+- `InstallationRecord` carries the cached token (`token`/`tokenExpiresAt`/`tokenKid`, memory-only
+  plaintext) plus the persisted 409-pending mark (`pending`); `InstallationStore` gains
+  `listInstallations()`, `clearCachedToken()`, `clearAllCachedTokens()`,
+  `markInstallationPending()` / `clearInstallationPending()` / `isKnownPending()`.
+  Opening a v1 database migrates it (schema v2: `pending` column, backfilled false;
+  Postgres `schema_version` guard converges to exactly one row at version 2).
+- The default install handler merges a redelivered install envelope for an existing installation
+  idempotently (resync path): secret + settings refresh, `installedAt` and the cached token kept.
+- The logger additionally redacts bare RS256 JWTs and PEM private-key blocks.
+- `.env.example` files document `APP_KEY_ID` + `APP_PRIVATE_KEY`.
+
+### Added
+
+- `app-auth.ts`: `loadAppCredential` (`APP_SLUG`/`APP_KEY_ID`/`APP_PRIVATE_KEY`, RSA PEM validated
+  at boot), `signAppJwt` (RS256 via `node:crypto` only, `iat` now − 60 s, `exp` window 540 s,
+  `kid` header), and the wire-contract error codes in exactly one place (`INVALID_CLIENT_CODE`,
+  `APP_TOKEN_REVOKED_CODE` (confirmed: `ApiError::APP_TOKEN_REVOKED`, also returned when the app is
+  disabled), `APP_INSTALLATION_GONE_CODE`, `APP_INSTALLATION_PENDING_CODE`, `RESYNC_COOLDOWN_CODE`,
+  `TOO_MANY_REQUESTS_CODE`).
+- `tokens.ts`: `createAppTokenProvider` (`acquireToken` with 5-minute validity skew, in-process
+  single-flight per installation, exact contract error mapping: `invalid_client` halts, kill-switch
+  403 drops all tokens and halts, `app_installation_gone` purges, 429 + jitter, bounded 5xx
+  backoff) and `createInstallationClient` (every call through `acquireToken`; merchant re-mint
+  only on token refusals — any 401 or 403 `api_key_revoked`/`api_key_expired`/`invalid_client_key`
+  → drop, re-mint once, retry once; merchant 403 `app_token_revoked` → drop all + halt; every
+  other 403 propagates without a mint).
+
+### Fixed
+
+- Merchant 403s that are NOT token refusals (e.g. `insufficient_scope`, plan, mode) no longer
+  burn a mint per call: they propagate to the caller untouched (rev 7 review). `AppTokens` gains
+  `revokeAppAccess()` for the merchant-observed kill switch.
+- Mint/resync 409 `app_installation_pending` (rev 8 review): retry later with backoff
+  (bounded), NEVER purge, NEVER halt. The installation carries a persisted pending mark
+  (B2 review r2: `pending` column on the installation row, schema v2 — survives restarts;
+  `markInstallationPending` / `isKnownPending` / `clearInstallationPending` on both the
+  stores and `AppTokenProvider`, which delegates); a 409 with any other code propagates
+  untouched.
+- Resync 404 `app_installation_gone` purges just that installation and the run continues
+  (backend re-checks status on resync per B2 review r2 — an uninstall landing between
+  authorize and resync 404s here); the row's deletion drops its pending mark with it.
+- Resync 429s are distinguished by code (rev 8): 429 `resync_cooldown` is the ≤1/hour
+  rotation cooldown (skipped + recorded in `cooldownSkipped`, never retried); any other 429
+  is the per-app bucket (`too_many_requests`: `Retry-After` + jitter, bounded retries,
+  then the run aborts — never recorded as a cooldown skip). `ResyncResult` gains
+  `pendingSkipped` for installations still pending after the retry budget.
+- Resync purge-absent keeps locally pending rows (rev 8): `GET installations` lists active
+  installations only, so absence never purges an installation the app knows (via a 409 on
+  mint or resync) is pending. The list cursor is treated as opaque keyset throughout —
+  followed until `next_cursor` is null, never interpreted.
+- `resync.ts`: `resyncFromQueek` (active-only list over an opaque keyset cursor →
+  per-installation resync with pending-retry/skip + cooldown-skip vs throttle-retry →
+  drop cached tokens → purge absent except known-pending; connectivity scope only).
+- `store.ts`: `PostgresInstallationStore` (`pg`, pool max 2, advisory-locked schema +
+  `schema_version` row), `createInstallationStore` (`DATABASE_URL` → Postgres, else SQLite —
+  refused in production), AES-GCM envelope unchanged.
+- `background.ts`: `runInstallationCatchup` (uniform 0–600 s start jitter, per-install error
+  isolation, concurrency ≤ pool size, honors 429 once per installation).
+- CI runs the Postgres suite via a `postgres:16` service container (`DATABASE_URL` always set);
+  without `DATABASE_URL` those tests skip cleanly.
+- Vitest suites against a local fake Queek server (JWT-verifying mint, opaque-cursor list, resync,
+  merchant refusals): cache-hit/expiry/single-flight/two-container minting, every contract error,
+  wipe → resync → connectivity, cooldown skip vs throttle retry, pending mint/resync retry + skip,
+  purge-absent (including pending-kept), resync-404 purges one installation without aborting,
+  persisted pending marks (v1→v2 migration + restart simulation on both stores),
+  production-refuses-SQLite.
+
+## [0.3.0] - 2026-09-25
+
+One shared Postgres pool per app process (the apps' own tables now live beside the SDK's tables in the same per-app database).
+
+### Added
+
+- `store.ts`: `createPostgresPool(connectionString, max)` — builds one `pg` Pool with the idle-client error guard for a process to share between its installation store and its app store. `PostgresInstallationStore` and `createInstallationStore` accept an optional shared `pool` (a provided pool wins over `DATABASE_URL`; `close()` never ends a pool the store does not own). `PostgresStoreOptions.connectionString` is now optional when `pool` is given.
+
+## [0.4.0] - 2026-09-28
+
+Standalone release: `@usequeek/app-sdk` ships from its own repo (`usequeek/app-sdk`).
+
+### Added
+
+- Session verifier as a server-only export (`@usequeek/app-sdk/server`): `verifySessionToken` — HS256 dashboard session tokens minted per installation (`embsec_…` secret, 20 s clock tolerance, slug audience + api_base issuer, full installation binding). The secret never enters a browser bundle: the main entry does not export the verifier. `sessionTokenInstallationId` reads the token's `installation_id` as an unverified routing hint.
+- Frame bridge (`frame.ts`, browser-safe, no secret): `listenToDashboard` (accepts only the exact dashboard origin) and `sendReady` (exact target origin, never `"*"`).
+- Resync handoff accepted on both `/install` and `/settings` (`type: app/resync`): the install-shaped data plus the resync-only `secret_rotated` flag merges via `saveResyncedInstallation` (secrets/settings/scopes refresh, `installedAt` and the cached token kept).
+- Install handoff carries `app_id` + `embed_secret`: the app's own id (exactly as the session token signs it) and the installation's `embsec_…` embed secret, handed over on install/resync and kept on the installation record (`embedSecret` encrypted, `appId`).
+
+### Changed
+
+- Merchant snapshot refreshed from production (line-properties PATCH, `storefront.domains`, `app_id`, no list `meta.currency`): regenerated types from the live Merchant API contract (decision 2026-09-24-one-public-product-object) — the product list + retrieve now return the one public `ProductResource`, the same object as `products/*` webhooks (`id` = int p_id, `uid` = UUID, plus `url`, `storefront_price`, `storefront_compare_at_price`, `primary_image_url`, `variants[]` with integer `id` = variant p_id, `images[]`; no cost/wholesale/discount internals).
+- Installation-bound app writes for the S3a contract (queek_backend@c1fa1c31; snapshot intentionally ahead of production — see `openapi/merchant.drift.json`, re-check after the S3a deploy): `setSetupNotice` (PUT app/setup, full-sheet write), `sendAlert` (POST app/alerts, severity/title/message plus optional dedupe key), `collectedDefinitions.list/create/update` (the calling installation's own collected types), and `createRecord` (POST records with a fresh Idempotency-Key per submit; `values` is a `{field_key: value}` object per the backend's FormsAppCollectedTest).
+
+## [0.1.0] - 2026-09-24
+
+First release: the kit every Queek app is built from.
+
+### Added
+
+- Standard Webhooks signature verification (`verifyQueekSignature`) with timestamp-skew enforcement.
+- Hono install/uninstall/settings handlers (`createInstallHandlers`) with encrypted persistence defaults.
+- Typed Merchant API client (`createQueekClient`): `X-Client-Key` auth, `Idempotency-Key` on writes, typed errors, 429 retry helpers. Types generated from the committed `openapi/merchant.json` snapshot.
+- Topic webhook dispatch (`createWebhookHandler`) with per-installation secrets and `webhook-id` dedupe.
+- Encrypted SQLite installation store (`SqliteInstallationStore`, AES-GCM).
+- Detached background-task helper (`detach`) with delivery-result tracking.
+- Redacting JSON logger (`createLogger`).
+- Dev-only `QUEEK_DEV_API_HOSTS` API-host override (refused when `NODE_ENV=production`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Queek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# @usequeek/app-sdk
+
+The SDK for building a Queek app on the public Merchant API and signed webhooks. Hono route helpers for the install handoff and topic webhooks, 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).
+
+```sh
+npm i @usequeek/app-sdk hono pg
+```
+
+Requires Node `>=22.14`. `hono` is a peer dependency so your app never carries two copies. `pg` is a regular dependency (the production store).
+
+## Example
+
+A minimal app: health check, install/uninstall/settings handlers, and one webhook topic:
+
+```ts
+import {
+  createAppTokenProvider,
+  createInstallHandlers,
+  createWebhookHandler,
+  loadAppCredential,
+  SqliteInstallationStore,
+} from "@usequeek/app-sdk";
+import { Hono } from "hono";
+
+const store = new SqliteInstallationStore({
+  path: "./data/installations.db",
+  storeKey: process.env.APP_ENCRYPTION_KEY!,
+});
+const tokens = createAppTokenProvider({
+  credential: loadAppCredential({ appSlug: "hello" }), // APP_SLUG/APP_KEY_ID/APP_PRIVATE_KEY
+  store,
+});
+
+const app = new Hono();
+app.get("/health", (c) => c.json({ ok: true }));
+app.route("/", createInstallHandlers({ appSecret: process.env.QUEEK_APP_SECRET!, store }));
+app.route(
+  "/webhooks",
+  createWebhookHandler({
+    store,
+    handlers: {
+      "orders/updated": async (envelope, context) => {
+        console.log("order update:", context.installation.storePid, envelope.data);
+      },
+    },
+  }),
+);
+
+export default app;
+```
+
+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`.
+
+## Credential lifecycle (S1: GitHub-style installation tokens)
+
+One asymmetric credential per app — no per-installation secrets cross the handoff any more.
+
+1. **Generate a keypair** (once, offline) and keep the private key in the founder's password
+   manager beside `APP_ENCRYPTION_KEY` (key + DB loss = working data lost — see below):
+
+   ```sh
+   openssl genrsa -out app-private.pem 2048
+   openssl rsa -in app-private.pem -pubout -out app-public.pem
+   ```
+
+2. **Register the public key** (Queek side; the backend stores it under a `kid`):
+
+   ```sh
+   php artisan app:register --public-key=./app-public.pem
+   ```
+
+   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).
+
+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
+   (`iss` = slug, `iat` = now − 60 s, `exp` = `iat` + 540 s, header `kid` — `node:crypto`
+   only) and `POST`s `access_tokens`, then persists the token encrypted with its expiry and
+   `kid` (one shared cache row per installation — restarts never burst). Concurrent callers
+   in one process share one in-flight mint; two containers minting at once is harmless by
+   design (Queek keeps coexisting tokens valid; a residual race self-heals via re-mint).
+   Merchant refusal table (rev 7): any 401, or 403 `api_key_revoked` / `api_key_expired` /
+   `invalid_client_key` → drop the token, re-mint once, retry once (a second refusal
+   propagates); 403 `app_token_revoked` → drop ALL cached tokens and halt minting (kill
+   switch / disabled app, no mint); every other 403 (scope, plan, mode) propagates to the
+   caller without a mint.
+
+4. **Failures follow the wire contract exactly** (`app-auth.ts` holds each code in one
+   constant, confirmed against the backend build):
+   - `401 invalid_client` — fatal for the app: loud log, minting stops, no retry loop.
+   - `403 app_token_revoked` (kill switch / disabled app) — drops ALL cached tokens, stops
+     minting, loud log. Minting resumes after the app is re-enabled + process restart
+     (or `resumeMinting()`).
+   - `404 app_installation_gone` — purges that installation locally.
+   - `409 app_installation_pending` — the installation is not active yet: retry later
+     with backoff, NEVER purge, NEVER halt. The row carries a persisted pending mark
+     (store column, schema v2 — survives restarts, cleared when the installation is
+     seen active or its mint succeeds).
+   - `429 resync_cooldown` (per-installation resync only) — the ≤1/hour rotation
+     cooldown: skipped + recorded, never retried. Any OTHER 429 is the per-app bucket
+     (`too_many_requests`): `Retry-After` honored with jitter, bounded retries.
+   - `5xx` — bounded exponential backoff.
+
+5. **Resync after DB loss or a long outage.** `resyncFromQueek({ apiBase, tokens, store })`
+   lists ACTIVE installations only (opaque keyset cursor — followed until `next_cursor`
+   is null, never interpreted) → requests a resync per installation (409 pending →
+   backoff + bounded retry, then skipped + recorded, never purged; 429 `resync_cooldown`
+   → skipped + recorded, never retried; any other 429 → `Retry-After` + jitter, bounded
+   retry; 404 `app_installation_gone` purges just that row and the run continues) → drops
+   cached tokens → purges local rows absent from Queek's list, EXCEPT rows carrying the
+   persisted pending mark — absence never purges a pending row, even across a restart.
+   The fresh `webhook_secret` + non-secret settings arrive over the
+   existing signed install channel — the install handler merges a redelivery for an
+   existing installation idempotently (secret + settings refresh, `installedAt` and the
+   cached token kept).
+
+6. **Kill switch behaviour.** One backend operation revokes every token of an app across
+   every store on the next request. The SDK side: cached tokens are dropped, minting halts
+   with a loud log, and every call fails closed until the app is re-enabled and the
+   process restarts (or resumes). Rotation without drama: add a `kid` (both verify) →
+   switch the app to it → wait one token TTL → remove the old `kid`.
+
+## Data rule + backups
+
+The app database holds INSTALLATIONS ONLY (refs, token cache, webhook secrets, settings).
+Business data lives in Queek. `resyncFromQueek` restores CONNECTIVITY with zero merchant
+action — but app WORKING data (inbound tokens, order links, form tokens, app-side-only
+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.
+
+## 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,
+  `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`.
+- **tokens** (`tokens.ts`): `createAppTokenProvider({ credential, store, … })` —
+  `acquireToken` (cache → sign → mint → persist), single-flight per installation, the exact
+  contract error mapping (409 pending → backoff + bounded retry, marked, never purged);
+  `createInstallationClient({ installationId, apiBase, tokens })` — the `QueekClient`
+  every app call uses (re-mint once + retry once on token refusals only).
+- **resync** (`resync.ts`): `resyncFromQueek({ apiBase, tokens, store })` — list active
+  only (opaque keyset cursor) → resync each (409 pending → retry then skip + record;
+  429 `resync_cooldown` → skip + record; other 429 → backoff + retry) → drop tokens →
+  purge absent except known-pending. Connectivity scope only.
+- **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.
+- **install handlers** (`install-handlers.ts`): `createInstallHandlers({ appSecret, store, onInstall?, onUninstall?, onSettings? })` — serves the signed install/uninstall/settings handoff. Defaults persist the installation (encrypted) in the store; a redelivered install for an existing installation merges idempotently (`saveResyncedInstallation`).
+- **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`): `createWebhookHandler({ store, handlers })` — verifies each delivery against the installation's endpoint secret, dedupes on `webhook-id`, and dispatches `topic → handler` at most once.
+- **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
+  persisted 409-pending mark (`pending` column, schema v2, migrated in place) and the
+  seen-webhook-id claim table behind dedupe. Pick with `createInstallationStore()`
+  (`DATABASE_URL` set → Postgres, else SQLite — which production REFUSES with a clear
+  message). Set once when the app is deployed; installs never change env: each install adds
+  a row to the app's database, with that store's token + webhook secret encrypted using this key.
+- **background** (`background.ts`): `detach` plus `runInstallationCatchup` — jittered
+  per-installation cron (uniform 0–600 s start jitter, per-install error isolation,
+  concurrency ≤ pool size, honors 429 once per installation).
+- **logger** (`logger.ts`): redacts `sk_`/`pk_`/`whsec_`/`Bearer` values, bare RS256 JWTs, and
+  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
+  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 `"*"`).
+
+## Embedded merchant page (S4 stage 2)
+
+The dashboard frames your app's granted merchant page in a
+`sandbox="allow-scripts allow-forms"` iframe and delivers the session token
+by postMessage. Serve the page with a `frame-ancestors` policy naming ONLY
+your dashboard origin, for example:
+
+```http
+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.
+
+## Local development
+
+Point the client at a local backend with `QUEEK_DEV_API_HOSTS` (comma-separated hosts). It is refused when `NODE_ENV=production`, so it can never weaken a live app. See `devApiHostsFromEnv` in `client.ts`.
+
+Postgres locally: any Postgres works — point `DATABASE_URL` at it and the pg suite runs
+(CI always runs it via a service container); without `DATABASE_URL` those tests skip cleanly.
+
+## Registration
+
+App registration is by the Queek team today: you ship Queek your manifest URL and receive the app secret + store key. There is no public self-serve registration yet.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/app-auth.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The app credential (S1, SDK 0.2.0): ONE asymmetric RS256 key per app.
+ * Queek holds the PUBLIC keys (`apps.public_keys`, kid-capped); the app
+ * holds the PRIVATE key in `APP_PRIVATE_KEY` and signs short-lived app
+ * JWTs that mint per-installation tokens (`acquireToken()`).
+ *
+ * Wire contract (BINDING for B2 and S1): every call under `/api/v1/apps`
+ * carries `Authorization: Bearer <app JWT>` (RS256, header `kid`, claims
+ * `iss` = app slug, `iat`, `exp`, `exp − iat` ≤ 600 s). `node:crypto` only
+ * — no new dependency. The JWT and the private key are NEVER logged (the
+ * logger redacts `Bearer …` values; signers below never emit them).
+ */
+/** 401 on an app-credential call: bad/expired JWT or unknown kid. Fatal for the app. */
+export declare const INVALID_CLIENT_CODE = "invalid_client";
+/**
+ * 403 on an app-credential call: the app is disabled or its token epoch was
+ * bumped by `app:revoke-tokens` (kill switch). Confirmed against B1
+ * (`ApiError::APP_TOKEN_REVOKED`, returned in both cases); matched in
+ * exactly one place (`isAppTokenRevoked`).
+ */
+export declare const APP_TOKEN_REVOKED_CODE = "app_token_revoked";
+/** 404 on an installation-scoped app call: purge that installation locally. */
+export declare const APP_INSTALLATION_GONE_CODE = "app_installation_gone";
+/**
+ * 409 on an installation-scoped app call: the installation is PENDING
+ * (not yet active). Retry later with backoff — NEVER purge, NEVER halt.
+ * `GET installations` lists active installations only, so a pending row is
+ * absent from the list: resync's purge-absent step must keep local rows
+ * the app knows (via a 409) are pending.
+ */
+export declare const APP_INSTALLATION_PENDING_CODE = "app_installation_pending";
+/**
+ * 429 on a per-installation resync: the ≤1/hour rotation COOLDOWN. Skip
+ * that installation (recorded, no retry loop). Any OTHER resync 429 is the
+ * per-app bucket (`too_many_requests`): back off on `Retry-After`
+ * (jittered) and retry — never recorded as a cooldown skip.
+ */
+export declare const RESYNC_COOLDOWN_CODE = "resync_cooldown";
+/** 429 everywhere: honor `Retry-After`, jittered. */
+export declare const TOO_MANY_REQUESTS_CODE = "too_many_requests";
+/** 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. */
+export declare function isInvalidClient(code: string | undefined): boolean;
+/** True when a Queek error code means the installation is gone server-side. */
+export declare function isInstallationGone(code: string | undefined): boolean;
+/** True when a Queek error code means the installation is pending (409: retry later, never purge). */
+export declare function isInstallationPending(code: string | undefined): boolean;
+/** True when a resync 429 code is the per-installation rotation cooldown (skip, recorded). */
+export declare function isResyncCooldown(code: string | undefined): boolean;
+/**
+ * Merchant-API token-refusal codes (rev 7): a token in one of these states
+ * 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)
+ * propagates to the caller without a mint.
+ */
+export declare const API_KEY_REVOKED_CODE = "api_key_revoked";
+export declare const API_KEY_EXPIRED_CODE = "api_key_expired";
+export declare const INVALID_CLIENT_KEY_CODE = "invalid_client_key";
+/**
+ * True when a merchant-API refusal means the presented token is dead: any
+ * 401, or a 403 with a revoked/expired-key code. `app_token_revoked` is
+ * deliberately NOT here — that is the app-wide kill switch (drop all +
+ * halt), not a single dead token.
+ */
+export declare function isTokenRefusal(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. */
+export declare const APP_JWT_TTL_SECONDS = 540;
+/** A cached installation token counts as valid only while its expiry is more than this far away. */
+export declare const TOKEN_VALIDITY_SKEW_SECONDS = 300;
+/** Mint attempts per `acquireToken` before surfacing a 429/5xx (1 initial + retries). */
+export declare const MAX_MINT_ATTEMPTS = 3;
+/** 5xx backoff base (doubles per attempt); every sleep also carries uniform jitter (see below). */
+export declare const MINT_BACKOFF_BASE_MS = 250;
+/** 5xx backoff ceiling (a 429 `Retry-After` may exceed it — the server's word wins). */
+export declare const MINT_BACKOFF_MAX_MS = 5000;
+/** Uniform jitter added to every mint/resync backoff sleep (0–1000 ms). */
+export declare const RETRY_JITTER_MAX_MS = 1000;
+/** Thrown when `APP_PRIVATE_KEY`/`APP_KEY_ID`/slug fail validation — before any fetch. */
+export declare class InvalidAppCredentialError extends Error {
+    readonly code = "invalid_app_credential";
+    constructor(message: string);
+}
+/**
+ * Thrown (and cached in-process) when Queek refuses the app itself:
+ * `invalid_client` (bad/unknown key — fatal until the key is fixed) or the
+ * kill-switch 403 (disabled/epoch-revoked — fatal until the app is
+ * re-enabled). Minting STOPS: no retry loop. Clears on process restart;
+ * call `resumeMinting()` to clear it sooner (tests, or an operator who
+ * just re-enabled the app).
+ */
+export declare class AppMintHaltedError extends Error {
+    readonly code = "app_mint_halted";
+    readonly reason: typeof INVALID_CLIENT_CODE | typeof APP_TOKEN_REVOKED_CODE;
+    constructor(reason: AppMintHaltedError["reason"], detail: string);
+}
+/** Thrown when no installation row exists locally for an id. */
+export declare class UnknownInstallationError extends Error {
+    readonly code = "unknown_installation";
+    constructor(installationId: string);
+}
+export interface AppCredential {
+    /** `iss`: the app slug (as registered with `app:register`). */
+    appSlug: string;
+    /** `kid`: which of the app's public keys Queek verifies against (`APP_KEY_ID`). */
+    keyId: string;
+    /** PEM-encoded PKCS#8 / PKCS#1 RSA private key (`APP_PRIVATE_KEY`). Memory only, never logged. */
+    privateKeyPem: string;
+}
+export interface AppCredentialOptions {
+    appSlug?: string;
+    keyId?: string;
+    privateKeyPem?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * 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
+ * private key here, once, so a broken key fails at boot — never mid-mint.
+ * Throws `InvalidAppCredentialError` before any fetch.
+ */
+export declare function loadAppCredential(options?: AppCredentialOptions): AppCredential;
+export interface SignAppJwtOptions {
+    credential: AppCredential;
+    /** Seconds since epoch. Defaults to `Date.now() / 1000` (injectable in tests). */
+    nowSeconds?: number;
+}
+/**
+ * Sign an app JWT (RS256, `node:crypto` only): header `{alg RS256, kid}`,
+ * claims `{iss = app slug, iat = now − 60 s, exp = iat + 540 s}` — the
+ * `exp − iat` window (540 s) stays under the 600 s wire bound. Returns the
+ * compact JWT; NEVER logs it or the private key.
+ */
+export declare function signAppJwt(options: SignAppJwtOptions): string;
+//# sourceMappingURL=app-auth.d.ts.map

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

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