@sixtyninecommerce/admin 0.6.0 → 0.8.0

package/README.md

@@ -115,6 +115,21 @@ channel. When the app's declarations later grow, the installation moves to `need
 working** until `apps.approveConsent(id)` lands, so this is a notice, not an outage. `apps.uninstall(id)`
 revokes every token immediately and keeps the row as provenance for what the app wrote.
 
+Growth is granted only by NAMING it, and an approval should carry what the approver was shown:
+
+```ts
+await admin.apps.approveConsent(installation.id, {
+  grantedPermissions: [...installation.grantedPermissions, 'UpdateProduct'],
+  // What was on screen. The engine refuses the approval if the app changed
+  // while it was being read, so a re-registration between the screen and the
+  // button cannot be ratified by somebody who never saw it.
+  acknowledgedConsentReasons: installation.pendingConsentReasons ?? [],
+});
+```
+
+Omit `grantedPermissions` and the installation keeps exactly what it had — the right default for an
+app that grew an event type or a metafield rather than a permission.
+
 ```ts
 // App side — the app authenticates as itself. No token handling.
 const app = createAdminClient({
@@ -138,6 +153,25 @@ bearer, and refreshes that bearer a minute before it expires. The key never leav
 the bearer is never yours to store. `privateKey` takes a PKCS#8 PEM, a JWK, or an already-imported
 `CryptoKey` for a caller whose key lives in a KMS handle.
 
+The assertion carries `aud` — the origin of the deployment it may be exchanged at — and the platform
+verifies it strictly. The SDK derives it from the `urls.vendureUrl` you already configured, so there
+is nothing to set. It matters because `iss` and `sub` name one app on one installation, and those ids
+survive a database restore unchanged: without `aud`, an assertion minted for a staging restore of a
+production dump verifies against production. A mismatch answers
+`400 ASSERTION_AUDIENCE_MISMATCH` naming the origin that deployment expects.
+
+**Signing by hand?** Read the audience from the authenticated capability manifest and put it in
+`aud` verbatim — do not re-derive it. Through this SDK that is
+`(await admin.tenant.capabilities()).assertionAudience`; straight off the wire
+(`GET /capabilities`) the member is `assertion_audience`, since the SDK camelises response keys. A
+`null` there means the plugins service cannot state one, which does not mean the exchange accepts an
+assertion without `aud` — the two run as separate deployment resources, so ask the operator rather
+than omitting the claim.
+
+An assertion with no `aud` at all is still accepted **until 2026-12-01**; those exchanges answer 200
+with `Deprecation`, `Sunset` and `Link` headers, and the platform logs `APP_ASSERTION_AUD_MISSING`
+naming your app. After the sunset they are refused.
+
 `apps.*` itself is a TENANT ADMIN's surface, not an app's: `InstallApps` is never grantable to an
 app, because an installation is a minted credential and an app that could install one could grant
 another app a subset of its own permissions with nobody consenting. An app reads its own state
@@ -147,8 +181,66 @@ Registering apps, managing their keys, suspension and per-tenant enablement live
 `platform.apps.*` and need a human SuperAdmin session — an app that could register apps could
 declare anything and enable itself.
 
-`APP_MANIFEST_SCHEMA` is exported from `@sixtyninecommerce/core`, so a build step can validate a
-manifest before anyone tries to register it.
+`APP_MANIFEST_SCHEMA` (and its `APP_MANIFEST_SCHEMA_SOURCE` text) is re-exported from THIS package,
+so a build step can validate a manifest before anyone tries to register it. It is defined in
+`@sixtyninecommerce/core`, which is a transitive dependency pnpm will not resolve for you — import it
+from here.
+
+The registry is deliberately STRICTER than that schema: it refuses a padded string, a duplicate list
+entry, an unknown key inside a metafield definition, and a namespace naming another app. Validating
+against the schema says "worth sending", never "certain to be accepted".
+
+### An app's settings, and its own state
+
+Two surfaces, and the difference between them is who owns the data.
+
+`apps.installation.config` is the **settings form** the app declares and the merchant fills in. A
+tenant admin with `InstallApps` reads and writes it; the owning app may READ its own and may never
+write it — an app that could write its own settings could grant itself whatever its own code reads
+out of them.
+
+```ts
+const { value } = await admin.apps.installation.config.get(installationId);
+await admin.apps.installation.config.set(installationId, { endpoint: 'https://acme.test/hook' });
+```
+
+What you save is validated against the app's declared `configSchema`. A refusal is `CONFIG_INVALID`
+with one `details[]` entry per failing JSON Pointer, so a form can mark every field at once. An app
+that declares no schema has nothing to configure (`APP_DECLARES_NO_CONFIG`), and a schema using a
+keyword or type the platform does not recognise refuses every save rather than half-checking it
+(`CONFIG_SCHEMA_UNENFORCEABLE` — the app's author must re-register).
+
+That covers both axes: a keyword the platform does not recognise, and one it recognises but cannot
+apply to the level's declared type — `minLength` on an `integer`, `required` on a `string` — which
+would constrain nothing. Declare each keyword on a type it applies to: `minLength`/`maxLength`/
+`pattern` on a string, `minimum`/`maximum` on a number or integer, `minItems`/`maxItems` on an
+array, `required` on an object. Reading never fails because the
+schema moved: the stored value comes back as it was saved even where the current schema no longer
+describes it, so you can show it and offer to clear it.
+
+`customObjects` is the app's **own private state**, `(container, key)` documents that only an
+installation token reaches. A human session — SuperAdmin included — is refused
+(`CUSTOM_OBJECT_FORBIDDEN`), and one installation never sees another's rows.
+
+```ts
+await admin.customObjects.set('sync-state', 'cursor', { at: lastSyncedAt });
+const page = await admin.customObjects.list('sync-state');
+await admin.customObjects.delete('sync-state', 'cursor');
+```
+
+Quotas are per installation per store: 128 KiB a document and 10,000 live objects. The row quota is
+checked only when a NEW key is written, so a full installation can still shrink a value it already
+has, and the merchant's settings row never counts against it. A container name is 1-64 characters,
+starts with a lowercase letter or digit and uses only lowercase letters, digits, `-` and `_`; a key
+is 1-200 characters with no control characters.
+
+Both `value` payloads keep their keys exactly as you send them — the case conversion this SDK
+applies to its own field names never reaches inside them, so a field named `order_ref` stays
+`order_ref`.
+
+Neither write is deduplicated by an `Idempotency-Key`. `customObjects.set` replaces a value by key,
+so repeating it is the same as doing it once; the settings write is a human saving a form, where
+replaying an earlier answer to a later edit would be wrong.
 
 ### Knowing what credential you hold
 
@@ -388,6 +480,271 @@ had before the registry.
 Read with `ReadSettings` and written with `UpdateSettings` — the same grants that govern
 `storefrontUrl` itself. A head an app installed (`installationId` set) is managed through that app's
 declarations and is refused here with `HEAD_APP_OWNED`.
+
+### Tax classes
+
+Tax categories and their rates are **platform-wide**, shared by every store. A tax class is your
+store's own name for how something is taxed — `standard`, `reduced`, `zero-rated` — mapped per
+country onto the category that prices it.
+
+```ts
+await admin.tax.classes.upsert({ key: 'reduced', label: 'Verlaagd tarief' }); // kebab-case key
+await admin.tax.mappings.set('reduced', 'NL', nlReducedCategoryId);
+await admin.tax.mappings.set('reduced', '*', nlReducedCategoryId);           // the fallback
+
+const classes = await admin.tax.classes.list();      // a Page; the list is complete today
+await admin.tax.classes.get('reduced');              // null when this store has no such key
+await admin.tax.classes.delete('reduced');           // false when there was none
+```
+
+Resolution is **country → `*` → refuse**: the country the money is taxed in, then the fallback row,
+then `TAX_CLASS_UNMAPPED` naming the country. `*` is a mapping like any other, set and removed the
+same way, so "this class says nothing about Germany" and "this class charges Germany the fallback"
+stay different states.
+
+`upsert` is keyed on `key` and there is **no rename**: the key lives on product variants and on
+every `tax_class.changed` a consumer has stored. Create a new class and delete the old — in that
+order, because `delete` is refused with `TAX_CLASS_IN_USE` while variants still carry it. Refusals:
+`TAX_CLASS_NOT_FOUND` (`NotFoundError`, and also the answer for another store's class),
+`TAX_CLASS_KEY_TAKEN` / `TAX_CLASS_IN_USE` (`ConflictError`), `TAX_CLASS_UNMAPPED` and the
+`INVALID_TAX_CLASS_*` codes (`ValidationError`).
+
+Read with `ReadSettings` and written with `UpdateSettings` — deliberately not the tax-category
+permissions, which govern the table every store shares.
+
+### Order surcharges
+
+A surcharge is an adjustment on a placed order that is not a line: a delivery charge, a negotiated
+discount, a handling fee. Money is integer minor units, negative for a discount, and
+`priceIncludesTax` is required because guessing the basis is a 21% error.
+
+```ts
+await admin.orders.surcharges.add(orderId, {
+  description: 'Bezorgtoeslag',
+  price: 500,
+  priceIncludesTax: true,
+}, { taxClass: 'reduced' });                   // the class decides the rate, per order
+
+await admin.orders.surcharges.add(orderId, {
+  description: 'Kortingsafspraak',
+  price: -7522,                                 // negative: a discount agreed after the order
+  priceIncludesTax: true,
+  taxRate: 21,                                  // or state the percentage yourself
+  taxDescription: 'NL Standard VAT 21%',
+});
+
+await admin.orders.surcharges.update(orderId, surchargeId, input, { taxClass: 'reduced' });
+await admin.orders.surcharges.remove(orderId, surchargeId);
+```
+
+`taxClass` is resolved **per order**, and the two halves are different questions: the order's
+shipping **country** picks the class's mapping, and the order's tax **zone** picks that category's
+rate. They can legitimately differ — a store only moves a country into its own zone by listing it in
+its tax-exclusive countries — so map the country *and* give that zone a rate for the category, or the
+write is refused (`TAX_CLASS_UNMAPPED`, `TAX_CLASS_RATE_MISSING`) rather than silently untaxed.
+
+The order's own tax policy still wins: a tax-removed order and an EU reverse charge override
+whatever the class resolved to, because the rate goes through the same tax-line strategy the order's
+lines do. A per-line rate imported from an ERP is the one policy that does not carry over — it
+belongs to a line the ERP sent, not to a charge added afterwards. The class chooses which rate is looked up, never what the line finally
+says — which is also why sending `taxClass` together with `input.taxRate` or `input.taxDescription`
+is refused. Omit it and the explicit-rate path is exactly what it always was.
+
+`update` replaces the surcharge in place, so it keeps its id (a delivery charge stays linked to the
+fulfillment that created it) and an omitted `sku` is left alone rather than cleared. **Tax is not
+like `sku`**: it is a whole replacement, so omitting both `taxClass` and `input.taxRate` writes a
+surcharge with no tax line and lowers the order total — re-send whichever of the two it should
+carry. A `taxClass` is then re-resolved on every write, so the rate that applies now is the one
+stored. All three need `UpdateOrder` and are refused once the order's invoice has been approved.
+
+### Payment providers
+
+Onboard the PSP account a store is paid through, place its card terminals, and ask whether it can
+actually take money.
+
+```ts
+const { url, state } = await admin.payments.providers.startOnboarding('mollie', {
+  returnUrl: 'https://merchant.example/settings/payments',
+});                                            // send the merchant to `url`
+
+await admin.payments.providers.completeOnboarding('mollie', { state, code });  // on their return
+await admin.payments.providers.activateMethod('mollie', 'pointofsale');
+
+await admin.payments.providers.terminals.provision('mollie', { label: 'Counter 1' });
+await admin.payments.providers.terminals.assign(terminalId, locationId);
+await admin.payments.providers.terminals.unassign(terminalId);   // still a terminal, just in a drawer
+
+await admin.payments.providers.terminals.list('mollie');     // what the platform holds — a pure read
+await admin.payments.providers.terminals.refresh('mollie');  // reconcile with the provider (a write)
+
+const readiness = await admin.payments.providers.readiness('mollie', { locationId });
+readiness.overall;    // can this store take money at that counter?
+readiness.blockers;   // if not, the server's own evidence — one entry per failing gate
+readiness.path;       // 'connect' | 'legacy' | 'none'
+```
+
+**A connection belongs to the seller, not the store.** A PSP account belongs to the legal entity that
+gets paid, so every store of one seller shares one connection: onboard once, and the money lands in
+one place. A channel with no seller is refused with `SELLER_REQUIRED` rather than given a connection
+keyed on nothing.
+
+**Ask the question you are about to act on.** Pass `locationId` for a counter sale and the terminal
+signals gate the verdict; pass `orderId` and `orderPayable` does. Signals outside your question never
+gate `overall` and never produce a blocker — a web-only store has no terminal and is not broken. Two
+of them read `false` when you did not ask (`terminalUsableForLocation`, `orderPayable`): there is no
+location and no order for them to be true of, so don't render either as a problem unless you asked
+the question it answers. Terminals belong to a provider connection, so on the `legacy` path a
+`locationId` question says so rather than claiming a counter is ready. `partialSupported` never gates at all: it answers *may I take a deposit here*, not
+*can this store be paid*.
+
+**Two credential paths, both first-class.** `path` is `connect` for an account onboarded through the
+platform and `legacy` for the store's own per-channel API key. There is no migration: a legacy store
+is supported indefinitely, can be fully ready, and moves when it chooses to. The per-channel key
+surface is deprecated in the schema and supported in the code; those are different statements.
+
+`completeOnboarding` and `terminals.provision` take an `idempotencyKey`, so a retried request cannot
+leave a second account or a second reader behind. Provisioning the same reader twice is the same
+reader either way — the provider's id is its identity. `startOnboarding` deliberately takes none: its
+response carries a link that can be single-use, an idempotency store keeps a response for 24 hours
+and re-serves it, and retrying is safe anyway — a repeat replaces the pending attempt and answers
+with a fresh url and state, which is what a merchant who lost the first link needs.
+
+**One connection, every store of the seller.** `UpdatePaymentMethod` in ANY of a seller's stores can
+disconnect and re-connect, which re-points revenue for all of them. That is the same sharing that
+makes onboarding happen once, but it means the permission's blast radius is the seller, not the
+store — worth knowing before granting it. Terminals hang off that one connection, so the same holds
+for them: `terminals.assign`/`unassign` from one store can move a reader that serves a sibling
+store's counter, and the `terminal.changed` event is filed under the store that made the change, so
+the sibling's POS learns about it on its next read rather than from the event.
+
+`terminals.list` is a pure read of what the platform holds; `terminals.refresh` reconciles with the
+provider and is a WRITE — it records readers the merchant added in the provider's own dashboard,
+updates the ones it knows, and marks a reader the provider no longer reports `inactive` so it stops
+counting towards readiness. Rows are never deleted: a row is the evidence a reader existed and where
+it stood.
+
+`terminals.unassign(id)` is how a terminal comes off a location — `assign` requires a location id, so
+there is no call with a meaningless argument. (Underneath, both are `assignProviderTerminal`, whose
+`locationId` is nullable; a null and an omitted one mean the same thing to the server.)
+
+Refusals: `PROVIDER_ALREADY_CONNECTED` (`ConflictError` — disconnect first; silently re-pointing a
+store's money is not something a retry should do), `SELLER_REQUIRED`, `PROVIDER_NOT_CONNECTED`,
+`PROVIDER_CREDENTIAL_REJECTED` and `TERMINAL_REJECTED` (`BusinessRuleError` — what the provider
+itself refused, with its own message kept out of the response),
+`PAYMENT_PROVIDER_NOT_REGISTERED`, `ONBOARDING_STATE_INVALID` and the `INVALID_*` inputs
+(`ValidationError`), `TERMINAL_NOT_FOUND` (`NotFoundError`), and `LOCATION_NOT_IN_CHANNEL` when a
+terminal or a readiness question names another channel's location — the same code the rest of the
+platform uses for that one rule.
+
+`LIVE_CONNECTION_REFUSED` is declared and classified but nothing throws it yet: the rule that a
+sandbox store may hold only a `test` connection needs a way to identify a sandbox store, which
+arrives with the sandbox flag. `readiness.mode` already reports which kind a store holds.
+
+Reading needs `ReadPaymentMethod`, writing `UpdatePaymentMethod`.
+
+### Documents
+
+Invoices, credit notes and packing slips: issuing them, the numbered facts they were built from, and
+your own extension blocks.
+
+```ts
+// Issue. `subjectId` is what the document is FOR: an order for an invoice, a
+// FULFILLMENT for a packing slip. An invoice date is required, never assumed.
+const invoice = await admin.documents.generate(orderId, 'invoice', {
+  invoicedOn: '2026-09-18',
+  extensions: [{ key: 'export-declaration', schemaVersion: 1, data: { hsCode: '8471.30' } }],
+});
+
+const data = await admin.documents.data(invoice.id, 'invoice');
+data.numbering;           // { scope: 'channel', scopeId, series, number }
+data.totals?.totalWithTax; // the figures the PDF printed, in minor units (null on a lump-sum note)
+data.reconciled;          // false when the ORDER moved after the invoice was numbered
+
+await admin.documents.invoices(orderId);       // a Page; complete today
+await admin.documents.creditNotes(orderId);
+await admin.documents.previewInvoice(orderId, { invoicedOn: '2026-09-18' }); // PDF bytes, nothing stored
+await admin.documents.sendInvoiceEmail({ orderId, recipientsTo: ['ap@buyer.example'] });
+```
+
+**`documentData` is the read to build on.** It returns what the document was numbered with —
+numbering, issuer, recipient, lines, per-rate VAT, totals and the blocks it froze — so a vertical can
+render its own document from the platform's own figures. Two fields say what a re-derivation would
+hide: `reconciled` is `false` when the rebuilt figures no longer match `issuedTotalWithTax` (a
+standard invoice derives its lines from the order, and an order can be modified after the invoice was
+numbered), and `taxSummary` is `null` rather than `[]` on a lump-sum credit note that never stated a
+per-rate split.
+
+Numbering, the VAT summary and issuer identity stay platform-owned — there is no method that
+allocates a number. `numbering.scope` is modelled for the per-legal-entity series multi-region will
+add, so a consumer reading `scope`/`scopeId` keeps working when it lands.
+
+#### Extension blocks
+
+A block is a named, schema-validated island of **your** data drawn into the reserved region of a
+document — after the summary table, before the footer.
+
+```ts
+await admin.documents.extensions.register({
+  key: 'export-declaration',                       // lower-case kebab, ≤ 64 chars
+  documentTypes: ['invoice', 'packing-slip'],
+  jsonSchema: {
+    type: 'object',
+    required: ['hsCode'],
+    properties: { hsCode: { type: 'string', minLength: 4 } },
+  },
+  templateFragment: { node: 'text', text: 'HS code {{ /hsCode }}' },
+});
+
+await admin.documents.extensions.list();          // the USABLE set: newest version per key
+await admin.documents.extensions.delete('export-declaration');   // false when there was none
+```
+
+The schema grammar is **bounded**. Exactly fifteen JSON Schema keywords are accepted — thirteen of
+them constrain the data, `title` and `description` are annotations — and any other is refused **by
+name** at registration (`DOCUMENT_EXTENSION_SCHEMA_KEYWORD_UNSUPPORTED`, with the keyword and the
+JSON Pointer in `error.details`, one entry per pointer).
+
+A keyword must also sit on a **type it can constrain**, refused the same way and naming both:
+`minLength`/`maxLength`/`pattern` on a `string`, `minimum`/`maximum` on a `number` or `integer`,
+`minItems`/`maxItems`/`items` on an `array`, `properties`/`required`/`additionalProperties` on an
+`object`, `enum` on the four scalar types; `type`, `title` and `description` anywhere. A PIN is a
+`string` with `minLength`, not an `integer` with one. The fifteen keywords:
+
+`type`, `title`, `description`, `properties`, `required`, `additionalProperties`, `items`, `enum`,
+`minLength`, `maxLength`, `minimum`, `maximum`, `minItems`, `maxItems`, `pattern`.
+
+Six types are accepted — `object`, `array`, `string`, `number`, `integer`, `boolean` — and
+`additionalProperties` defaults to **false**, unlike JSON Schema, so a block cannot carry
+unvalidated fields onto a document. A keyword that looks enforced but is not is worse than one that
+is rejected while you are still editing.
+
+The template fragment is allow-listed too. Each node names its kind in `node` — the five kinds are
+`text`, `stack`, `columns`, `table` and `repeat` — and `{{ /json/pointer }}` placeholders are filled
+from the block's data. Margins are bounded and never negative, a table's rows must all be the same
+width, and a `repeat` goes inside a `stack` rather than being a table cell: each of those would
+otherwise throw inside the PDF engine *after* the document had been numbered. Text is never
+interpreted as document markup, and a placeholder resolving to nothing — or to an object or array —
+is refused at **generation** (`DOCUMENT_EXTENSION_PLACEHOLDER_UNRESOLVED`) rather than printed as an
+empty string or `[object Object]`.
+
+**A document is immutable once numbered.** Generation freezes the data *and* the fragment onto the
+document's own row, so re-rendering it after you changed or deleted the registration reproduces the
+document that was issued — and a void & reissue carries the original's frozen blocks onto the
+replacement for the same reason. Re-registering a key writes a new version; a generation naming a
+stale `schemaVersion` is refused (`DOCUMENT_EXTENSION_VERSION_MISMATCH`), never coerced. At most ten
+blocks per document, and an invalid, duplicate or over-long list refuses the whole document rather
+than issuing a numbered one that silently dropped something — on `issuePartialCreditNote` that
+refusal runs **before** the refund moves.
+
+`delete` RETIRES a key rather than erasing it: the rows are the only record of what each version
+meant, and a document frozen at version 1 must keep pointing at the schema that was version 1. A
+retired key is gone from `list()` and unusable on a new document, and a later re-registration
+continues the version sequence rather than minting a second version 1.
+
+Registering needs `UpdateSettings`, listing `ReadSettings`, and `documentData` `ReadOrder`.
+`idempotencyKey` is recorded on the wire and acts on nothing here: the Admin API is GraphQL and has
+no header for it.
+
 ### Capabilities
 
 `admin.tenant.capabilities()` answers what this tenant's channel can actually do — one read instead

package/dist/apps/assertion.d.ts

@@ -45,6 +45,19 @@ export declare function importAppPrivateKey(key: AppPrivateKey): Promise<AppCryp
 export interface AssertionClaims {
     /** The registered app's id — the platform checks it against the installation. */
     appId: string;
+    /**
+     * The deployment this assertion may be exchanged at: the ORIGIN of its
+     * Vendure API, e.g. `https://engine.sixtyninecommerce.com`. Signed as `aud`
+     * and verified strictly.
+     *
+     * Required, deliberately. `iss` and `sub` name one app on one installation,
+     * but those ids survive a database restore unchanged — so without `aud` an
+     * assertion minted for a staging restore of a production dump verifies
+     * against production. `createAppCredential` derives it from the `vendureUrl`
+     * the client is already configured with; a caller signing by hand reads it
+     * from `assertion_audience` in the authenticated capability manifest.
+     */
+    audience: string;
     /**
      * The installation this assertion may be exchanged at. Signed, and compared to
      * the id in the exchange URL, so an app installed on two tenants cannot be
@@ -65,8 +78,22 @@ export declare const DEFAULT_ASSERTION_LIFETIME_SECONDS = 120;
  * `jti` is a fresh uuid every time: the platform refuses a replayed one, so a
  * cached assertion is worse than useless. `sub` is the installation id, which is
  * what actually binds the assertion to one tenant — the path parameter alone
- * would not, since the endpoint is unauthenticated. `aud` is deliberately absent:
- * there is no stable audience string a self-hosted platform could publish, and
- * `iss` + `sub` already name exactly one app on one installation.
+ * would not, since the endpoint is unauthenticated. `aud` names the DEPLOYMENT,
+ * which `iss` and `sub` cannot: all three ids survive a database restore, so an
+ * assertion minted for a staging restore of a production dump would otherwise
+ * verify against production.
+ *
+ * `aud` is normalized through `new URL(...).origin`, the SAME normalization the
+ * platform applies to its own `VENDURE_HOST`. That is what lets a deployment
+ * configured with a trailing slash still match an SDK configured without one:
+ * both sides reduce to the origin before comparing.
  */
 export declare function signAppAssertion(key: AppCryptoKey, claims: AssertionClaims): Promise<string>;
+/**
+ * Reduce a deployment URL to the origin the platform compares against.
+ *
+ * Exported so `createAppCredential` and a caller signing by hand cannot derive
+ * it two different ways. A URL that cannot be parsed is an actionable error
+ * here, not a mystery 400 from the exchange twenty lines later.
+ */
+export declare function assertionAudience(vendureUrl: string): string;

package/dist/apps/assertion.js

@@ -100,9 +100,15 @@ export const DEFAULT_ASSERTION_LIFETIME_SECONDS = 120;
  * `jti` is a fresh uuid every time: the platform refuses a replayed one, so a
  * cached assertion is worse than useless. `sub` is the installation id, which is
  * what actually binds the assertion to one tenant — the path parameter alone
- * would not, since the endpoint is unauthenticated. `aud` is deliberately absent:
- * there is no stable audience string a self-hosted platform could publish, and
- * `iss` + `sub` already name exactly one app on one installation.
+ * would not, since the endpoint is unauthenticated. `aud` names the DEPLOYMENT,
+ * which `iss` and `sub` cannot: all three ids survive a database restore, so an
+ * assertion minted for a staging restore of a production dump would otherwise
+ * verify against production.
+ *
+ * `aud` is normalized through `new URL(...).origin`, the SAME normalization the
+ * platform applies to its own `VENDURE_HOST`. That is what lets a deployment
+ * configured with a trailing slash still match an SDK configured without one:
+ * both sides reduce to the origin before comparing.
  */
 export async function signAppAssertion(key, claims) {
     const now = Math.floor((claims.now?.() ?? Date.now()) / 1000);
@@ -111,6 +117,7 @@ export async function signAppAssertion(key, claims) {
     const payload = encodeJson({
         iss: claims.appId,
         sub: claims.installationId,
+        aud: assertionAudience(claims.audience),
         iat: now,
         exp: now + lifetime,
         jti: randomId(),
@@ -119,6 +126,36 @@ export async function signAppAssertion(key, claims) {
     const signature = await subtle().sign('Ed25519', key, new TextEncoder().encode(signingInput));
     return `${signingInput}.${base64UrlEncode(new Uint8Array(signature))}`;
 }
+/**
+ * Reduce a deployment URL to the origin the platform compares against.
+ *
+ * Exported so `createAppCredential` and a caller signing by hand cannot derive
+ * it two different ways. A URL that cannot be parsed is an actionable error
+ * here, not a mystery 400 from the exchange twenty lines later.
+ */
+export function assertionAudience(vendureUrl) {
+    let url;
+    try {
+        url = new URL(vendureUrl);
+    }
+    catch {
+        throw new ValidationError({
+            code: 'APP_ASSERTION_AUDIENCE_INVALID',
+            message: `The app assertion audience must be an absolute URL (the deployment's Vendure origin), got "${vendureUrl}".`,
+            status: 400,
+            service: 'vendure',
+        });
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new ValidationError({
+            code: 'APP_ASSERTION_AUDIENCE_INVALID',
+            message: `The app assertion audience must be an http(s) URL, got "${vendureUrl}".`,
+            status: 400,
+            service: 'vendure',
+        });
+    }
+    return url.origin;
+}
 /** A uuid for `jti`. `randomUUID` is available wherever `subtle` is. */
 function randomId() {
     const webcrypto = globalThis.crypto;

package/dist/apps/config.d.ts

@@ -0,0 +1,39 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** An installation's settings, as the merchant has filled them in. */
+export interface AppInstallationConfig {
+    installationId: string;
+    /** Null until the merchant has saved anything. */
+    value: unknown;
+    /** Null until the merchant has saved anything. */
+    updatedAt: string | null;
+}
+/**
+ * The settings form an app declares and a merchant fills in (spec §8.13).
+ *
+ * **Who may do what is asymmetric, on purpose.** A tenant admin with
+ * `InstallApps` reads and writes; the owning app may READ its own settings and
+ * may never write them (`CONFIG_FORBIDDEN`). An app that could write its own
+ * settings could grant itself whatever its own code reads out of them, which is
+ * the opposite of what asking the merchant to fill in a form is for.
+ *
+ * **What is stored is judged by the app's declaration, not by the caller.** The
+ * value is validated against the `configSchema` in the app's manifest — the
+ * platform's bounded grammar, refused at registration if it uses a keyword
+ * nothing enforces. A rejected save is `CONFIG_INVALID` with one `details[]`
+ * entry per failing JSON Pointer, so a form can mark every field at once
+ * instead of surfacing them one failed save at a time. An app that declares no
+ * schema has nothing to configure: writing settings to it is
+ * `APP_DECLARES_NO_CONFIG`.
+ *
+ * **A read never fails because the schema moved.** The stored value comes back
+ * as it was saved even where the app's current schema no longer describes it,
+ * so a settings screen can show what is there and offer to clear it. Changing
+ * the schema in a way that demands something new parks the installation at
+ * `needs_consent` — see `apps.approveConsent`.
+ */
+export interface AppInstallationConfigModule {
+    get(installationId: string, options?: Call): Promise<AppInstallationConfig>;
+    set(installationId: string, value: unknown, options?: Call): Promise<AppInstallationConfig>;
+}
+export declare function createAppConfigModule(transport: Transport): AppInstallationConfigModule;

package/dist/apps/config.js

@@ -0,0 +1,22 @@
+import { PLATFORM_PASSTHROUGH_KEYS } from '@sixtyninecommerce/core';
+/**
+ * `value` is the merchant's saved settings, whose inner keys are the APP's
+ * declared field names. The transport would otherwise camelise them, so a field
+ * an app declared as `api_key_ref` would come back as `apiKeyRef` and never
+ * match the schema it is validated against.
+ */
+const PRESERVE = new Set([...PLATFORM_PASSTHROUGH_KEYS, 'value']);
+export function createAppConfigModule(transport) {
+    const path = (installationId) => `/apps/installations/${encodeURIComponent(installationId)}/config`;
+    return {
+        async get(installationId, options) {
+            return transport.rest('plugins', { method: 'GET', path: path(installationId) }, { ...options, preserveKeys: PRESERVE });
+        },
+        async set(installationId, value, options) {
+            // No idempotency key: this is a human saving a form, and replaying an
+            // earlier answer to a later edit is the wrong outcome. The route is
+            // deliberately undecorated on the server for the same reason.
+            return transport.rest('plugins', { method: 'PUT', path: path(installationId), body: { value } }, { ...options, preserveKeys: PRESERVE });
+        },
+    };
+}

package/dist/apps/credential.d.ts

@@ -10,6 +10,11 @@ import { type AppPrivateKey } from './assertion.js';
  * Concurrent calls collapse onto ONE mint (`inFlight`). Without it, an app that
  * fires ten requests at startup signs ten assertions and burns ten tokens, and
  * every one of them is a round trip the caller waits for.
+ *
+ * The exchange carries a route budget of its own, per installation and calling
+ * address, so a 429 from it is HELD: nothing is sent again until the window the
+ * server named has passed, and calls that land inside it are refused here with
+ * the wait that is actually left.
  */
 export interface AppCredentialConfig {
     /** The registered app's id, which the assertion carries as `iss`. */