@sixtyninecommerce/admin 0.4.0 → 0.5.0

package/README.md

@@ -38,6 +38,7 @@ for await (const form of await admin.content.forms.list()) {
 |---|---|---|
 | API token | `auth: { token: 's69t_…' }` | server only — constructing one in a browser throws `CREDENTIAL_IN_BROWSER` |
 | Admin session | `auth: { session: { token?, onToken } }` | server or browser |
+| App installation | `auth: { app: { appId, kid, privateKey }, installationId }` | server only — a private key in a browser throws `CREDENTIAL_IN_BROWSER` |
 
 A session client can start empty and sign in:
 
@@ -94,14 +95,72 @@ const created = await scoped.apiTokens.create({
 console.log(created.token); // shown exactly once
 ```
 
+### Apps
+
+An app is registered once by a platform operator from its `sixtynine.app.json` manifest, enabled
+per tenant, and then installed by a tenant admin who consents to a subset of what it declares.
+
+```ts
+// Tenant side — needs `InstallApps` and a tenant context.
+const available = await scoped.apps.list();
+const installation = await scoped.apps.install({
+  appId: available[0]!.id,
+  grantedPermissions: ['ReadCatalog', 'ReadOrder'], // ⊆ declaredPermissions, and ⊆ your own
+});
+```
+
+Your own permissions are the ceiling: you cannot grant an app something you do not hold on that
+channel. When the app's declarations later grow, the installation moves to `needs_consent` and its
+`pendingConsentReasons` say what changed — **tokens already minted keep the old grants and keep
+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.
+
+```ts
+// App side — the app authenticates as itself. No token handling.
+const app = createAdminClient({
+  urls,
+  auth: {
+    app: { appId: process.env.APP_ID!, kid: '2026-09', privateKey: process.env.APP_PRIVATE_KEY! },
+    installationId: process.env.INSTALLATION_ID!,
+  },
+  tenant: { scope: { kind: 'channel', code: 'velvet-thread' } },
+});
+
+// A token is minted on the first call and refreshed for you from then on.
+const me = await app.auth.whoami();          // kind: 'app_installation'
+me.installation?.status;                     // 'needs_consent' → tell the merchant
+me.permissions;                              // what this installation was actually granted
+const products = await app.content.forms.list();  // …and any module those permissions allow
+```
+
+The SDK signs a short-lived Ed25519 assertion with your private key, exchanges it for an `s69i_`
+bearer, and refreshes that bearer a minute before it expires. The key never leaves your process and
+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.
+
+`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
+through `auth.whoami()`.
+
+Registering apps, managing their keys, suspension and per-tenant enablement live under
+`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.
+
 ### Knowing what credential you hold
 
 ```ts
 const who = await admin.auth.whoami();
-who.kind;          // 'api_token' | 'user'
+who.kind;          // 'api_token' | 'user' | 'app_installation'
 who.token?.expiresAt;  // null means it never expires
 who.permissions;   // effective on the ACTIVE channel, not the union
 who.entitlements;  // connected plugin keys for that channel
+// For an app: who.app (id, slug, name) and who.installation (status, consentVersion).
+// `installation.status === 'needs_consent'` is how an app learns the merchant has
+// to approve declarations it has since grown.
 ```
 
 For a machine credential this is the only way to learn any of it without being refused. It needs a

package/dist/apps/assertion.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Signing the app assertion the platform exchanges for an `s69i_` token
+ * (headless spec §6.3).
+ *
+ * Web Crypto, not `jose`. `@sixtyninecommerce/core` has zero runtime
+ * dependencies by contract and `@sixtyninecommerce/admin` may depend only on
+ * it, so pulling a JWS library in here to produce ONE fixed shape — an EdDSA
+ * compact JWS over five claims — would trade that contract for about forty lines.
+ * `crypto.subtle` is available on Node 20+, Deno, Bun, Cloudflare Workers and
+ * every browser, which is the same reach.
+ *
+ * Ed25519 only. RS256 is accepted by the REGISTRY (an app may have been built
+ * around an existing RSA key), but this SDK signs with Ed25519: one algorithm
+ * means one code path, and an app using the SDK has no reason to want the
+ * larger, slower one.
+ */
+/**
+ * Web Crypto, typed LOCALLY rather than from `lib.dom` or `@types/node`.
+ *
+ * This package compiles with `lib: ["ES2022"]` and no DOM — deliberately, so a
+ * stray `document.` reference cannot slip in (`client.ts` makes the same point
+ * about the browser guard). Naming just the two operations used keeps that
+ * property and keeps the published `.d.ts` free of a lib a consumer may not have.
+ */
+export interface AppCryptoKey {
+    readonly type: string;
+    readonly algorithm: {
+        readonly name: string;
+    };
+}
+/** The private half, as an app author holds it. */
+export type AppPrivateKey = 
+/** PKCS#8 PEM (`-----BEGIN PRIVATE KEY-----`). */
+string
+/** A JWK (`{ kty: 'OKP', crv: 'Ed25519', d, x }`). */
+ | Record<string, unknown>
+/** An already-imported key, for a caller that keeps one in a KMS-backed handle. */
+ | AppCryptoKey;
+/**
+ * Import the key once. Wrapping the failure is the point: `importKey` rejects
+ * with `DataError`/`OperationError`, which tells an app author nothing about
+ * which of their two keys they pasted.
+ */
+export declare function importAppPrivateKey(key: AppPrivateKey): Promise<AppCryptoKey>;
+export interface AssertionClaims {
+    /** The registered app's id — the platform checks it against the installation. */
+    appId: 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
+     * handed a token for the wrong one by sending the wrong path.
+     */
+    installationId: string;
+    kid: string;
+    /** Seconds. The platform refuses more than 600 (spec §6.3). */
+    lifetimeSeconds?: number;
+    /** Injectable clock, so a spec can pin `iat`/`exp` without waiting. */
+    now?: () => number;
+}
+/** Default assertion lifetime: well inside the 600 s cap, with room for skew. */
+export declare const DEFAULT_ASSERTION_LIFETIME_SECONDS = 120;
+/**
+ * Build and sign the assertion.
+ *
+ * `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.
+ */
+export declare function signAppAssertion(key: AppCryptoKey, claims: AssertionClaims): Promise<string>;

package/dist/apps/assertion.js

@@ -0,0 +1,141 @@
+import { ValidationError } from '@sixtyninecommerce/core';
+const PEM_BODY = /-----BEGIN [A-Z ]*PRIVATE KEY-----([\s\S]*?)-----END [A-Z ]*PRIVATE KEY-----/;
+function base64UrlEncode(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    // `btoa` is in every runtime this package targets; Node has had it since 16.
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function encodeJson(value) {
+    return base64UrlEncode(new TextEncoder().encode(JSON.stringify(value)));
+}
+function pemToDer(pem) {
+    const match = PEM_BODY.exec(pem);
+    if (!match?.[1]) {
+        throw new ValidationError({
+            code: 'APP_PRIVATE_KEY_INVALID',
+            message: 'The app private key is not a PKCS#8 PEM. Expected a block starting with "-----BEGIN PRIVATE KEY-----", a JWK object, or an imported CryptoKey.',
+            status: 400,
+            service: 'vendure',
+        });
+    }
+    const binary = atob(match[1].replace(/\s+/g, ''));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+function subtle() {
+    const webcrypto = globalThis.crypto;
+    if (!webcrypto?.subtle) {
+        throw new ValidationError({
+            code: 'WEB_CRYPTO_UNAVAILABLE',
+            message: 'globalThis.crypto.subtle is not available, so an app assertion cannot be signed. Node 20+, Deno, Bun and browsers all provide it; a Node 18 runtime needs --experimental-global-webcrypto.',
+            status: 400,
+            service: 'vendure',
+        });
+    }
+    return webcrypto.subtle;
+}
+/**
+ * Import the key once. Wrapping the failure is the point: `importKey` rejects
+ * with `DataError`/`OperationError`, which tells an app author nothing about
+ * which of their two keys they pasted.
+ */
+export async function importAppPrivateKey(key) {
+    if (typeof key === 'object' && 'type' in key && 'algorithm' in key) {
+        const handle = key;
+        // Checked, not trusted. The registry also accepts RS256 keys, so an app
+        // built around one can reach here with a perfectly valid RSA handle —
+        // `subtle.sign('Ed25519', …)` would then reject with a raw WebCrypto
+        // `InvalidAccessError`, and every other failure in this file is an
+        // actionable `APP_PRIVATE_KEY_INVALID`.
+        if (handle.algorithm?.name !== 'Ed25519') {
+            throw new ValidationError({
+                code: 'APP_PRIVATE_KEY_INVALID',
+                message: `This SDK signs app assertions with Ed25519, but the key handle provided is ${String(handle.algorithm?.name)}. Register an Ed25519 key for the app, or sign the assertion yourself.`,
+                status: 400,
+                service: 'vendure',
+            });
+        }
+        // The PRIVATE half, too. A public Ed25519 handle passes the check above and
+        // fails inside `subtle.sign` as a raw `DOMException`, which is not a
+        // `PlatformError`: the transport reads it as a network fault, marks it
+        // retryable and burns the whole backoff budget reporting a permanent key
+        // mistake as an outage.
+        if (handle.type !== 'private') {
+            throw new ValidationError({
+                code: 'APP_PRIVATE_KEY_INVALID',
+                message: `The key handle provided is a "${String(handle.type)}" key. Sign with the PRIVATE half; the public half is what you register with addAppKey.`,
+                status: 400,
+                service: 'vendure',
+            });
+        }
+        return handle;
+    }
+    try {
+        if (typeof key === 'string') {
+            return await subtle().importKey('pkcs8', pemToDer(key), 'Ed25519', false, ['sign']);
+        }
+        return await subtle().importKey('jwk', key, 'Ed25519', false, ['sign']);
+    }
+    catch (error) {
+        if (error instanceof ValidationError)
+            throw error;
+        throw new ValidationError({
+            code: 'APP_PRIVATE_KEY_INVALID',
+            message: 'The app private key could not be imported as an Ed25519 key. Check that it is the PRIVATE half, in PKCS#8 PEM or JWK form, and that the runtime supports Ed25519.',
+            status: 400,
+            service: 'vendure',
+            cause: error,
+        });
+    }
+}
+/** Default assertion lifetime: well inside the 600 s cap, with room for skew. */
+export const DEFAULT_ASSERTION_LIFETIME_SECONDS = 120;
+/**
+ * Build and sign the assertion.
+ *
+ * `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.
+ */
+export async function signAppAssertion(key, claims) {
+    const now = Math.floor((claims.now?.() ?? Date.now()) / 1000);
+    const lifetime = claims.lifetimeSeconds ?? DEFAULT_ASSERTION_LIFETIME_SECONDS;
+    const header = encodeJson({ alg: 'EdDSA', typ: 'JWT', kid: claims.kid });
+    const payload = encodeJson({
+        iss: claims.appId,
+        sub: claims.installationId,
+        iat: now,
+        exp: now + lifetime,
+        jti: randomId(),
+    });
+    const signingInput = `${header}.${payload}`;
+    const signature = await subtle().sign('Ed25519', key, new TextEncoder().encode(signingInput));
+    return `${signingInput}.${base64UrlEncode(new Uint8Array(signature))}`;
+}
+/** A uuid for `jti`. `randomUUID` is available wherever `subtle` is. */
+function randomId() {
+    const webcrypto = globalThis.crypto;
+    if (webcrypto?.randomUUID)
+        return webcrypto.randomUUID();
+    // Only reachable on a runtime with `subtle` but no `randomUUID`; 16 random
+    // bytes are as unique as a v4 uuid, and the platform treats `jti` as opaque.
+    // `Math.random` is NOT a fallback here: a guessable `jti` would let anyone who
+    // saw one assertion pre-burn the next one's id and lock the app out.
+    if (!webcrypto?.getRandomValues) {
+        throw new ValidationError({
+            code: 'WEB_CRYPTO_UNAVAILABLE',
+            message: 'This runtime provides neither crypto.randomUUID nor crypto.getRandomValues, so a unique assertion id cannot be generated.',
+            status: 400,
+            service: 'vendure',
+        });
+    }
+    const bytes = webcrypto.getRandomValues(new Uint8Array(16));
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}

package/dist/apps/credential.d.ts

@@ -0,0 +1,36 @@
+import { type AppPrivateKey } from './assertion.js';
+/**
+ * Holding, minting and refreshing an installation token (headless spec §6.3).
+ *
+ * An app never handles the `s69i_` bearer itself: it hands the SDK its private
+ * key and installation id, and every call goes out with a live token. The token
+ * lasts an hour, so this mints once and refreshes a minute before expiry —
+ * early enough that a call is never made with a token that expires mid-flight.
+ *
+ * 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.
+ */
+export interface AppCredentialConfig {
+    /** The registered app's id, which the assertion carries as `iss`. */
+    appId: string;
+    /** The `kid` of the key below, as registered with `addAppKey`. */
+    kid: string;
+    /** PKCS#8 PEM, a JWK, or an already-imported `CryptoKey`. Never leaves the process. */
+    privateKey: AppPrivateKey;
+}
+export interface AppCredential {
+    /** A live bearer, minting or refreshing if needed. */
+    current(): Promise<string>;
+    /** The last bearer minted, or `''`. Synchronous, for the transport's principal. */
+    peek(): string;
+    /** Drop the cached token, so the next call mints a fresh one. */
+    invalidate(): void;
+    /**
+     * Replace `stale`, which the server has just refused. Returns whatever a
+     * sibling minted if one already has, so a burst of concurrent 401s collapses
+     * onto ONE exchange instead of one per request.
+     */
+    refresh(stale: string): Promise<string>;
+}
+export declare function createAppCredential(app: AppCredentialConfig, installationId: string, vendureUrl: string, fetchImpl: typeof globalThis.fetch): AppCredential;

package/dist/apps/credential.js

@@ -0,0 +1,182 @@
+import { errorFromResponse, TransportError } from '@sixtyninecommerce/core';
+import { importAppPrivateKey, signAppAssertion, } from './assertion.js';
+/** Refresh this long before expiry, so no call goes out on a dying token. */
+const REFRESH_MARGIN_MS = 60_000;
+/**
+ * Wall-clock budget for one exchange; see the `signal` below. The SAME 15 s the
+ * transport gives every other call — a longer one here meant a caller who
+ * budgeted 15 s could block for 45 while a stalled mint ran to its own deadline.
+ */
+const EXCHANGE_TIMEOUT_MS = 15_000;
+export function createAppCredential(app, installationId, vendureUrl, fetchImpl) {
+    let token = '';
+    let expiresAt = 0;
+    let inFlight = null;
+    /** Bumped by `invalidate()`; a mint from an older generation is not cached. */
+    let invalidations = 0;
+    /** The dead bearer the in-flight mint is REPLACING, for `refresh()`. */
+    let refreshingFrom = null;
+    let key = null;
+    async function mint() {
+        // The generation this mint belongs to. An `invalidate()` that lands while
+        // this is in flight bumps it, and the result is then returned to the caller
+        // but NOT cached — otherwise the token the server has just killed would be
+        // written back over the fresh one and the app would 401 again.
+        const generation = invalidations;
+        // Imported once and kept: `importKey` is not free, and an app makes this
+        // call every hour for the life of the process.
+        key ??= importAppPrivateKey(app.privateKey);
+        const assertion = await signAppAssertion(await key, {
+            appId: app.appId,
+            installationId,
+            kid: app.kid,
+        });
+        // Trailing slash stripped, as every other URL in the client is: a
+        // `vendureUrl` of `https://api.example.test/` works for every GraphQL call
+        // and produced `…test//apps/installations/…` here, which the controller's
+        // route does not match — app auth 404s while the rest of the client works.
+        const base = vendureUrl.replace(/\/+$/, '');
+        const url = `${base}/apps/installations/${encodeURIComponent(installationId)}/access-tokens`;
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ assertion }),
+                // DEADLINED, like every other call the client makes. Without it an
+                // exchange that never settles wedges `current()` for the life of the
+                // process: the slot it holds is freed only by `invalidate()`, which is
+                // only reachable from a 401 — which can never arrive, because no
+                // request ever goes out.
+                signal: AbortSignal.timeout(EXCHANGE_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            // A network failure minting the credential is retryable, and must not be
+            // reported as "your key is wrong".
+            throw new TransportError({
+                code: 'INSTALLATION_TOKEN_UNREACHABLE',
+                message: `Could not reach the token exchange at ${url}.`,
+                status: 0,
+                service: 'vendure',
+                retryable: true,
+                cause: error,
+            });
+        }
+        if (!response.ok) {
+            // problem+json first, legacy second — the exchange answers the same shape
+            // every other refusal on this platform does.
+            throw await errorFromResponse(response, 'vendure');
+        }
+        // Read inside the same guard as the request: an abort that fires while the
+        // body is still streaming would otherwise escape as a raw `AbortError`,
+        // which is not a `PlatformError` — the transport then re-wraps it as a
+        // timeout naming a deadline that did not fire.
+        let body;
+        try {
+            body = (await response.json());
+        }
+        catch (error) {
+            throw new TransportError({
+                code: 'INSTALLATION_TOKEN_UNREACHABLE',
+                message: `The token exchange at ${url} did not answer in full.`,
+                status: 0,
+                service: 'vendure',
+                retryable: true,
+                cause: error,
+            });
+        }
+        const minted = typeof body.access_token === 'string' ? body.access_token : '';
+        if (minted === '') {
+            throw new TransportError({
+                code: 'INSTALLATION_TOKEN_MALFORMED',
+                message: 'The token exchange answered 200 with no access_token.',
+                status: 0,
+                service: 'vendure',
+                retryable: true,
+            });
+        }
+        // `expires_in` WINS, because it is the only one of the two that does not
+        // require the two clocks to agree. `expires_at` is the SERVER's absolute
+        // instant; comparing it against this host's `Date.now()` on a client running
+        // two minutes slow means refreshing two minutes late in real time — the
+        // bearer is already dead, and the gate answers a NON-retryable 401 that
+        // nothing here recovers from. The relative form is measured from the moment
+        // the response arrived, on this clock, and cannot skew.
+        //
+        // `expires_at` stays the fallback for a server that sends only the absolute
+        // form. A body with neither is treated as already-expiring rather than
+        // never-expiring: minting again costs one round trip, while trusting a
+        // missing expiry means every call 401s from the hour mark on with nothing to
+        // tell the caller why.
+        const relative = typeof body.expires_in === 'number' ? Date.now() + body.expires_in * 1000 : Number.NaN;
+        const absolute = typeof body.expires_at === 'string' ? Date.parse(body.expires_at) : Number.NaN;
+        const expiry = Number.isFinite(relative)
+            ? relative
+            : Number.isFinite(absolute)
+                ? absolute
+                : Date.now();
+        // Nothing from a discarded generation is cached — not the token, and not
+        // its expiry, which would otherwise move the live token's refresh window.
+        if (generation !== invalidations)
+            return minted;
+        expiresAt = expiry;
+        token = minted;
+        return token;
+    }
+    /** Start a mint, or join the one already running. */
+    function mintOnce() {
+        if (inFlight)
+            return inFlight;
+        // The slot is cleared only by the mint that OWNS it: `invalidate()` also
+        // nulls it, and an unconditional `finally` then cleared the slot belonging
+        // to the newer mint that had already replaced it.
+        const pending = mint().finally(() => {
+            if (inFlight === pending) {
+                inFlight = null;
+                refreshingFrom = null;
+            }
+        });
+        inFlight = pending;
+        return pending;
+    }
+    return {
+        async current() {
+            if (token !== '' && Date.now() < expiresAt - REFRESH_MARGIN_MS)
+                return token;
+            return mintOnce();
+        },
+        peek: () => token,
+        async refresh(stale) {
+            // A sibling has already replaced it — the commonest case when a burst of
+            // concurrent calls all meet the same 401. Its freshness is checked too, so
+            // the retry cannot go out on a bearer that has since expired and burn the
+            // one attempt it gets.
+            if (token !== '' && token !== stale && Date.now() < expiresAt - REFRESH_MARGIN_MS) {
+                return token;
+            }
+            // A mint is already running for a state that is no older than this refusal
+            // — either a refresh for this same dead bearer, or one started after an
+            // invalidation (`token === ''`, so nothing is cached to be stale). Join it
+            // rather than dropping it and starting another: N concurrent 401s would
+            // otherwise sign N assertions for the one kill they are all reacting to.
+            if (inFlight && (refreshingFrom === stale || token === ''))
+                return inFlight;
+            token = '';
+            expiresAt = 0;
+            invalidations += 1;
+            inFlight = null;
+            refreshingFrom = stale;
+            return mintOnce();
+        },
+        invalidate() {
+            token = '';
+            expiresAt = 0;
+            // Drops any mint already in flight as well: it was started for the
+            // credential state that has just been declared dead.
+            invalidations += 1;
+            inFlight = null;
+            refreshingFrom = null;
+        },
+    };
+}

package/dist/apps/index.d.ts

@@ -0,0 +1,106 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+export declare const APP_FIELDS = "\n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n";
+export declare const INSTALLATION_FIELDS = "\n  id\n  appId\n  targetKind\n  targetId\n  grantedPermissions\n  grantedFieldOwnership\n  locationIds\n  status\n  consentVersion\n  pendingConsentReasons\n  installedAt\n  uninstalledAt\n";
+export declare const AVAILABLE_APPS_QUERY = "\n  query AvailableApps {\n    availableApps { \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const MY_INSTALLATIONS_QUERY = "\n  query MyInstallations {\n    myInstallations { \n  id\n  appId\n  targetKind\n  targetId\n  grantedPermissions\n  grantedFieldOwnership\n  locationIds\n  status\n  consentVersion\n  pendingConsentReasons\n  installedAt\n  uninstalledAt\n }\n  }\n";
+export declare const INSTALLATION_QUERY = "\n  query AppInstallation($id: ID!) {\n    appInstallation(id: $id) { \n  id\n  appId\n  targetKind\n  targetId\n  grantedPermissions\n  grantedFieldOwnership\n  locationIds\n  status\n  consentVersion\n  pendingConsentReasons\n  installedAt\n  uninstalledAt\n }\n  }\n";
+export declare const INSTALL_MUTATION = "\n  mutation InstallApp($input: InstallAppInput!) {\n    installApp(input: $input) { \n  id\n  appId\n  targetKind\n  targetId\n  grantedPermissions\n  grantedFieldOwnership\n  locationIds\n  status\n  consentVersion\n  pendingConsentReasons\n  installedAt\n  uninstalledAt\n }\n  }\n";
+export declare const APPROVE_MUTATION = "\n  mutation ApproveInstallationConsent($id: ID!, $input: ApproveInstallationConsentInput) {\n    approveInstallationConsent(id: $id, input: $input) { \n  id\n  appId\n  targetKind\n  targetId\n  grantedPermissions\n  grantedFieldOwnership\n  locationIds\n  status\n  consentVersion\n  pendingConsentReasons\n  installedAt\n  uninstalledAt\n }\n  }\n";
+export declare const UNINSTALL_MUTATION = "\n  mutation UninstallApp($id: ID!) {\n    uninstallApp(id: $id) { \n  id\n  appId\n  targetKind\n  targetId\n  grantedPermissions\n  grantedFieldOwnership\n  locationIds\n  status\n  consentVersion\n  pendingConsentReasons\n  installedAt\n  uninstalledAt\n }\n  }\n";
+/** A registered app, as a tenant admin sees it on the consent screen. */
+export interface App {
+    id: string;
+    slug: string;
+    name: string;
+    ownerLabel: string;
+    /** The ceiling on what an installation may be granted. */
+    declaredPermissions: string[];
+    declaredEvents: string[];
+    /** Normalised `"<entity>.<field>"` claims, e.g. `product.price`. */
+    declaredFieldOwnership: string[];
+    /** `none` | `identity` | `full`. */
+    customerData: string;
+    customerDataPurpose: string | null;
+    metafieldDefinitions: unknown[];
+    configSchema: Record<string, unknown> | null;
+    hooks: unknown[];
+    headTemplates: unknown[];
+    sandboxOnly: boolean;
+    /** `active` | `suspended`. */
+    status: string;
+    manifestVersion: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AppInstallation {
+    id: string;
+    appId: string;
+    /** `channel` today; `organization` arrives with multi-region. */
+    targetKind: string;
+    targetId: string;
+    grantedPermissions: string[];
+    /** Normalised `"<entity>.<field>"` claims, e.g. `product.price`. */
+    grantedFieldOwnership: string[];
+    /** Null means unrestricted. */
+    locationIds: string[] | null;
+    /** `active` | `needs_consent` | `suspended` | `uninstalled`. */
+    status: string;
+    consentVersion: number;
+    /** Why consent is pending, in the approver's words. Null unless `needs_consent`. */
+    pendingConsentReasons: string[] | null;
+    installedAt: string;
+    uninstalledAt: string | null;
+}
+/** What an approver agrees to. Every field omitted means "keep what was granted". */
+export interface ApproveConsentInput {
+    grantedPermissions?: string[];
+    grantedFieldOwnership?: string[];
+    /**
+     * Replace the stock-location restriction. Omit to keep it; pass `null` to LIFT
+     * it entirely — the engine distinguishes the two, so a plain `string[]` would
+     * leave a tenant who restricted an app to one warehouse no way back short of
+     * uninstalling it.
+     */
+    locationIds?: string[] | null;
+}
+export interface InstallAppInput {
+    appId: string;
+    /** Must be a subset of the app's `declaredPermissions`, and of the caller's own. */
+    grantedPermissions?: string[];
+    grantedFieldOwnership?: string[];
+    /** Restrict the installation to these stock locations. Omit for unrestricted. */
+    locationIds?: string[];
+}
+/**
+ * Installing and managing apps on the caller's OWN store (headless spec §6.3).
+ *
+ * Needs `InstallApps` and a tenant context. Every method acts on the active
+ * channel — there is no channel parameter, because a channel-id input would have
+ * to be permission-checked against a store the caller may not belong to, and the
+ * engine refuses that shape for the same reason it does on API tokens.
+ *
+ * The REGISTRY side (registering apps, keys, suspension, enabling an app for a
+ * tenant) lives under `admin.platform.apps` and needs a human SuperAdmin session.
+ */
+export interface AppsModule {
+    /** Apps a platform operator has enabled for this store and that are not suspended. */
+    list(options?: Call): Promise<App[]>;
+    /** Consent to a subset of an app's declarations and install it. */
+    install(input: InstallAppInput, options?: Call): Promise<AppInstallation>;
+    /** This store's installations, newest first. */
+    installations(options?: Call): Promise<AppInstallation[]>;
+    installation(id: string, options?: Call): Promise<AppInstallation | null>;
+    /**
+     * Approve declarations that grew, granting what you name.
+     *
+     * Growth is granted only by naming it — omit `grants` and the installation
+     * keeps exactly what it had, which is the right default for an app that grew
+     * an event type or a metafield. Tokens already minted keep the OLD grants
+     * until this lands.
+     */
+    approveConsent(id: string, grants?: ApproveConsentInput, options?: Call): Promise<AppInstallation>;
+    /** Revoke every token and end the grant. The row is kept as provenance. */
+    uninstall(id: string, options?: Call): Promise<AppInstallation>;
+}
+export declare function createAppsModule(transport: Transport): AppsModule;

package/dist/apps/index.js

@@ -0,0 +1,92 @@
+export const APP_FIELDS = /* GraphQL */ `
+  id
+  slug
+  name
+  ownerLabel
+  declaredPermissions
+  declaredEvents
+  declaredFieldOwnership
+  customerData
+  customerDataPurpose
+  metafieldDefinitions
+  configSchema
+  hooks
+  headTemplates
+  sandboxOnly
+  status
+  manifestVersion
+  createdAt
+  updatedAt
+`;
+export const INSTALLATION_FIELDS = /* GraphQL */ `
+  id
+  appId
+  targetKind
+  targetId
+  grantedPermissions
+  grantedFieldOwnership
+  locationIds
+  status
+  consentVersion
+  pendingConsentReasons
+  installedAt
+  uninstalledAt
+`;
+export const AVAILABLE_APPS_QUERY = /* GraphQL */ `
+  query AvailableApps {
+    availableApps { ${APP_FIELDS} }
+  }
+`;
+export const MY_INSTALLATIONS_QUERY = /* GraphQL */ `
+  query MyInstallations {
+    myInstallations { ${INSTALLATION_FIELDS} }
+  }
+`;
+export const INSTALLATION_QUERY = /* GraphQL */ `
+  query AppInstallation($id: ID!) {
+    appInstallation(id: $id) { ${INSTALLATION_FIELDS} }
+  }
+`;
+export const INSTALL_MUTATION = /* GraphQL */ `
+  mutation InstallApp($input: InstallAppInput!) {
+    installApp(input: $input) { ${INSTALLATION_FIELDS} }
+  }
+`;
+export const APPROVE_MUTATION = /* GraphQL */ `
+  mutation ApproveInstallationConsent($id: ID!, $input: ApproveInstallationConsentInput) {
+    approveInstallationConsent(id: $id, input: $input) { ${INSTALLATION_FIELDS} }
+  }
+`;
+export const UNINSTALL_MUTATION = /* GraphQL */ `
+  mutation UninstallApp($id: ID!) {
+    uninstallApp(id: $id) { ${INSTALLATION_FIELDS} }
+  }
+`;
+export function createAppsModule(transport) {
+    return {
+        async list(options) {
+            const data = await transport.graphql({ api: 'admin', query: AVAILABLE_APPS_QUERY }, options);
+            return data.availableApps;
+        },
+        async install(input, options) {
+            const data = await transport.graphql({ api: 'admin', query: INSTALL_MUTATION, variables: { input } }, options);
+            return data.installApp;
+        },
+        async installations(options) {
+            const data = await transport.graphql({ api: 'admin', query: MY_INSTALLATIONS_QUERY }, options);
+            return data.myInstallations;
+        },
+        async installation(id, options) {
+            const data = await transport.graphql({ api: 'admin', query: INSTALLATION_QUERY, variables: { id } }, options);
+            return data.appInstallation;
+        },
+        async approveConsent(id, grants, options) {
+            const data = await transport.graphql({ api: 'admin', query: APPROVE_MUTATION, variables: { id, input: grants ?? null } }, options);
+            return data.approveInstallationConsent;
+        },
+        async uninstall(id, options) {
+            const data = await transport.graphql({ api: 'admin', query: UNINSTALL_MUTATION, variables: { id } }, options);
+            return data.uninstallApp;
+        },
+    };
+}

package/dist/client.d.ts

@@ -1,11 +1,14 @@
 import { type DeprecationNotice, type RateLimitInfo, type RetryPolicy, type TenantContext, type TenantScope } from '@sixtyninecommerce/core';
 import { type ApiTokensModule } from './api-tokens/index.js';
+import { type AppCredentialConfig } from './apps/credential.js';
+import { type AppsModule } from './apps/index.js';
 import { type AuditModule } from './audit/index.js';
 import { type AuthModule } from './auth/index.js';
 import { type FormsModule } from './content/forms.js';
 import { type HeadsModule } from './heads/index.js';
 import { type LocationsModule } from './locations/index.js';
 import { type MetaModule } from './meta/index.js';
+import { type PlatformAppsModule } from './platform/apps.js';
 import { type PlatformModule } from './platform/provision-store.js';
 import { type RedirectsModule } from './seo/redirects.js';
 import { type ChannelsModule } from './tenant/channels.js';
@@ -33,7 +36,7 @@ export interface AdminClientConfig {
         token: string;
     } | {
         session: SessionConfig;
-    };
+    } | AppAuthConfig;
     tenant?: Partial<TenantContext> & {
         scope?: TenantScope;
     };
@@ -42,9 +45,21 @@ export interface AdminClientConfig {
     timeoutMs?: number;
     onDeprecation?: (notice: DeprecationNotice) => void;
 }
+/**
+ * An APP's own credential (headless spec §6.3). The SDK signs an assertion with
+ * the app's private key, exchanges it for an `s69i_` bearer, and refreshes that
+ * bearer a minute before it expires — an app never handles the token itself.
+ */
+export interface AppAuthConfig {
+    app: AppCredentialConfig;
+    /** The installation this credential acts as, from `admin.apps.install(...)`. */
+    installationId: string;
+}
 export interface AdminClient {
     auth: AuthModule;
     apiTokens: ApiTokensModule;
+    /** Installing and managing apps on the ACTIVE store. Needs `InstallApps`. */
+    apps: AppsModule;
     audit: AuditModule;
     channels: ChannelsModule;
     content: {
@@ -64,10 +79,13 @@ export interface AdminClient {
         retention: RetentionModule;
     };
     /**
-     * Human SuperAdmin surface. Every method refuses an API token before the
-     * request leaves the process (`PLATFORM_REQUIRES_SESSION`).
+     * Human SuperAdmin surface. Every method refuses an API token or an app
+     * credential before the request leaves the process
+     * (`PLATFORM_REQUIRES_SESSION`).
      */
-    platform: PlatformModule;
+    platform: PlatformModule & {
+        apps: PlatformAppsModule;
+    };
     /** A derived client on another tenant, sharing this one's principal. */
     withTenant(tenant: Partial<TenantContext> & {
         scope?: TenantScope;

package/dist/client.js

@@ -1,11 +1,14 @@
 import { createChannelResolver, createTransport, mergeTenant, UNSCOPED_TENANT, ValidationError, } from '@sixtyninecommerce/core';
 import { createApiTokensModule } from './api-tokens/index.js';
+import { createAppCredential, } from './apps/credential.js';
+import { createAppsModule } from './apps/index.js';
 import { createAuditModule } from './audit/index.js';
 import { createAuthModule } from './auth/index.js';
 import { createFormsModule } from './content/forms.js';
 import { createHeadsModule } from './heads/index.js';
 import { createLocationsModule } from './locations/index.js';
 import { createMetaModule } from './meta/index.js';
+import { createPlatformAppsModule } from './platform/apps.js';
 import { createPlatformModule } from './platform/provision-store.js';
 import { createRedirectsModule } from './seo/redirects.js';
 import { createChannelsModule } from './tenant/channels.js';
@@ -16,7 +19,10 @@ import { createRetentionModule } from './tenant/retention.js';
  * the dashboard is — so the refusal is specifically about a long-lived token.
  */
 function assertNotInBrowser(auth) {
-    if (!('token' in auth))
+    // An app's PRIVATE KEY is the strongest credential this SDK accepts — it mints
+    // tokens rather than being one — so it is refused in a browser exactly as a
+    // long-lived token is, and for the same reason.
+    if (!('token' in auth) && !('app' in auth))
         return;
     // Indexed off a typed view of globalThis: this package compiles without the
     // DOM lib on purpose, so that a stray `document.` reference cannot slip in.
@@ -24,9 +30,10 @@ function assertNotInBrowser(auth) {
     const inBrowser = runtime.window !== undefined && runtime.document !== undefined;
     if (!inBrowser)
         return;
+    const credential = 'app' in auth ? "An app's private key" : 'An API token';
     throw new ValidationError({
         code: 'CREDENTIAL_IN_BROWSER',
-        message: 'An API token must never be constructed in a browser — it would ship the credential to every visitor. Use a session bearer in the browser and keep tokens server-side.',
+        message: `${credential} must never be constructed in a browser — it would ship the credential to every visitor. Use a session bearer in the browser and keep machine credentials server-side.`,
         status: 400,
         service: 'vendure',
     });
@@ -140,15 +147,101 @@ export function createAdminClient(config) {
     });
     if ('session' in config.auth)
         assertSessionIsWritable(config.auth.session);
+    else if ('app' in config.auth)
+        assertAppCredentialIsPresent(config.auth);
     else
         assertTokenIsPresent(config.auth);
     // Shared by every client `withTenant` derives, because the session store is.
     // `rotations` lets `login()` tell a bearer THIS sign-in produced apart from
     // one that merely sits in the slot already.
     const shared = { rotations: 0 };
-    return buildClient(config, config.tenant, resolver, shared);
+    // One credential per CLIENT, shared with everything `withTenant` derives:
+    // the token is minted for an installation, and an installation is one app on
+    // one store — deriving a tenant does not change which credential it is.
+    const credential = 'app' in config.auth ? appCredentialFor(config, config.auth) : undefined;
+    return buildClient(config, config.tenant, resolver, shared, credential);
 }
-function buildClient(config, overrides, resolver, shared) {
+/**
+ * Nothing about an app credential is readable live (unlike `auth.token`, which
+ * may be a getter over a secret store), so every field is checked at
+ * construction rather than on the call that would have used it.
+ */
+function assertAppCredentialIsPresent(auth) {
+    const missing = [
+        isPresent(auth.app?.appId) ? null : 'app.appId',
+        isPresent(auth.app?.kid) ? null : 'app.kid',
+        auth.app?.privateKey ? null : 'app.privateKey',
+        isPresent(auth.installationId) ? null : 'installationId',
+    ].filter((field) => field !== null);
+    if (missing.length === 0)
+        return;
+    throw new ValidationError({
+        code: 'APP_CREDENTIAL_INCOMPLETE',
+        message: `An app credential needs ${missing.join(', ')}. Without them no assertion can be signed and every call would go out unauthenticated.`,
+        status: 400,
+        service: 'vendure',
+    });
+}
+function appCredentialFor(config, auth) {
+    // The exchange is fetched DIRECTLY, never through the wrapper below: that
+    // wrapper asks this credential for a bearer, so routing the mint through it
+    // would recurse forever on the very first call.
+    const baseFetch = config.fetch ?? globalThis.fetch;
+    return createAppCredential(auth.app, auth.installationId, config.urls.vendureUrl, baseFetch);
+}
+/**
+ * Every request an app makes goes out with a LIVE bearer.
+ *
+ * Done in `fetch` rather than in `principal` because minting is asynchronous and
+ * `principal` is not: a synchronous getter cannot wait for an exchange. The
+ * header the transport built is overwritten here, which is also what makes the
+ * first call work — at that point nothing has been minted and `peek()` is empty.
+ */
+function appFetch(credential, base) {
+    const send = async (input, init, bearer) => {
+        const headers = { ...(init?.headers ?? {}) };
+        headers.Authorization = `Bearer ${bearer}`;
+        return base(input, { ...init, headers });
+    };
+    return async (input, init) => {
+        // No try/catch: a credential failure must reach the caller AS ITSELF, and it
+        // already does. `createTransport`'s `send()` opens its catch with
+        // `if (error instanceof PlatformError) throw error`, so the refusal the
+        // exchange returned — built by `errorFromResponse`, carrying the server's
+        // own `trace_id` — passes through untouched. Catching it here to re-emit a
+        // synthesized problem+json would only lose that trace id and turn a
+        // status-0 transport failure into a 503.
+        const bearer = await credential.current();
+        const response = await send(input, init, bearer);
+        // A 401 on a token this SDK believes is live means the SERVER killed it —
+        // an app suspended and resumed, a key revoked, a tenant re-consenting — and
+        // the cached bearer can be up to an hour from its natural expiry. Without
+        // this the app is simply down for that hour: `PermissionDeniedError` is not
+        // retryable, and nothing else ever calls `invalidate()`. Exactly ONE retry,
+        // and only when a fresh bearer actually differs, so a genuinely
+        // unauthorised call cannot become an exchange loop.
+        if (response.status !== 401)
+            return response;
+        // The 401 body is read and discarded: an unread body holds its socket out of
+        // the keep-alive pool, and this one is replaced by the retry's.
+        void response
+            .clone()
+            .text()
+            .catch(() => undefined);
+        // `refresh`, not invalidate-then-current: it returns a bearer a sibling has
+        // already minted, and joins a refresh already running for this same dead
+        // one, so a burst of concurrent 401s costs ONE exchange rather than one per
+        // request.
+        const fresh = await credential.refresh(bearer);
+        // Compared against the bearer THIS request used: an identical token back
+        // from the exchange (a caching proxy in front of it) must end here rather
+        // than retry forever.
+        if (fresh === bearer)
+            return response;
+        return send(input, init, fresh);
+    };
+}
+function buildClient(config, overrides, resolver, shared, credential) {
     // No scope configured leaves the client on UNSCOPED_TENANT, which only the
     // auth documents may use; the transport refuses everything else with
     // TENANT_REQUIRED (spec §15.2).
@@ -160,6 +253,12 @@ function buildClient(config, overrides, resolver, shared) {
         channels: resolver,
         tenant,
         principal: () => {
+            // The bearer the LAST mint produced, which `appFetch` overwrites with a
+            // live one before the request leaves. Empty on the very first call, and
+            // deliberately not refused for it: an app credential is complete or it
+            // was rejected at construction.
+            if (credential)
+                return { kind: 'bearer', token: credential.peek() };
             if (!store) {
                 // Read live, so a getter over a request context follows the request
                 // being served — and refuse an empty one HERE rather than sending an
@@ -191,7 +290,12 @@ function buildClient(config, overrides, resolver, shared) {
                 },
             };
         },
-        ...(config.fetch ? { fetch: config.fetch } : {}),
+        // Every app request carries a freshly minted bearer; see `appFetch`.
+        ...(credential
+            ? { fetch: appFetch(credential, config.fetch ?? globalThis.fetch) }
+            : config.fetch
+                ? { fetch: config.fetch }
+                : {}),
         ...(config.retry ? { retry: config.retry } : {}),
         ...(config.timeoutMs === undefined ? {} : { timeoutMs: config.timeoutMs }),
         ...(config.onDeprecation ? { onDeprecation: config.onDeprecation } : {}),
@@ -219,6 +323,7 @@ function buildClient(config, overrides, resolver, shared) {
             },
         }),
         apiTokens: createApiTokensModule(transport),
+        apps: createAppsModule(transport),
         audit: createAuditModule(transport),
         channels: createChannelsModule(resolver),
         content: { forms: createFormsModule(transport) },
@@ -227,7 +332,10 @@ function buildClient(config, overrides, resolver, shared) {
         meta: createMetaModule(transport),
         seo: { redirects: createRedirectsModule(transport) },
         tenant: { retention: createRetentionModule(transport) },
-        platform: createPlatformModule(transport, config),
+        platform: {
+            ...createPlatformModule(transport, config),
+            apps: createPlatformAppsModule(transport, config),
+        },
         withTenant(next) {
             // `mergeTenant`, not a spread: it merges `actor` FIELD BY FIELD, so a
             // derived client that names only a registerRef keeps the staffRef this
@@ -238,7 +346,7 @@ function buildClient(config, overrides, resolver, shared) {
             // Resolver and rotation count are shared, and the session store IS the
             // caller's object — so a derived client reuses the channel cache and the
             // bearer this one signed in with, in both directions and in either order.
-            return buildClient(config, mergeTenant(tenant, next), resolver, shared);
+            return buildClient(config, mergeTenant(tenant, next), resolver, shared, credential);
         },
         get rateLimit() {
             return transport.rateLimit;

package/dist/index.d.ts

@@ -25,15 +25,19 @@ export type { DeprecationNotice, Page, PageMeta, RateLimitInfo, RetryPolicy, } f
  */
 export { AuthenticationError, BusinessRuleError, ConflictError, type ErrorDetail, NotFoundError, PermissionDeniedError, PlatformError, type ProblemDetails, RateLimitedError, TransportError, UpstreamError, ValidationError, } from '@sixtyninecommerce/core';
 export type { ApiTokensModule, CreatedApiToken } from './api-tokens/index.js';
+export type { AppCryptoKey, AppPrivateKey } from './apps/assertion.js';
+export type { AppCredential, AppCredentialConfig } from './apps/credential.js';
+export type { App, AppInstallation, ApproveConsentInput, AppsModule, InstallAppInput, } from './apps/index.js';
 export type { AuditCall, AuditCallFilter, AuditCorrelation, AuditEvent, AuditEventFilter, AuditModule, } from './audit/index.js';
 export type { AuthModule } from './auth/index.js';
-export { type AdminClient, type AdminClientConfig, createAdminClient, type SessionConfig, } from './client.js';
+export { type AdminClient, type AdminClientConfig, type AppAuthConfig, createAdminClient, type SessionConfig, } from './client.js';
 export type { Form, FormField, FormFieldInput, FormFieldTranslation, FormFieldTranslationInput, FormInput, FormsModule, FormTranslation, FormTranslationInput, } from './content/forms.js';
 export { AdminProjectionError } from './errors.js';
 export type { CreateHeadInput, Head, HeadsModule, UpdateHeadInput, } from './heads/index.js';
 export type { LocationProfile, LocationStockLocation, LocationsModule, OpeningHours, OpeningHoursDay, OpeningHoursInterval, StockLocationAddress, StockLocationAddressInput, UpsertLocationProfileInput, } from './locations/index.js';
 export { OPENING_HOURS_DAYS } from './locations/index.js';
 export type { ApiTokenTemplate, JsonSchema, LabelMap, MetaCatalog, MetaCatalogLabels, MetaCatalogPermissions, MetaCatalogPlugins, MetaCatalogTransitions, MetaModule, PermissionGroup, PluginCatalogEntry, RoleTemplate, StatusMetaMap, StatusTone, TransitionMap, } from './meta/index.js';
+export type { AppKey, PlatformAppsModule, RegisterAppResult, RegisteredApp, } from './platform/apps.js';
 export { requireHumanSession } from './platform/guard.js';
 export type { JobHandle, PlatformModule, ProvisionProfile, ProvisionRun, ProvisionRunStatus, ProvisionStep, ProvisionStepStatus, ProvisionStoreInput, ProvisionStoreResult, WaitOptions, } from './platform/provision-store.js';
 export { PROVISION_PROFILES } from './platform/provision-store.js';

package/dist/platform/apps.d.ts

@@ -0,0 +1,76 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import { type App } from '../apps/index.js';
+import type { AdminClientConfig } from '../client.js';
+import type { Call } from '../types.js';
+export declare const APPS_QUERY = "\n  query Apps($options: AppListOptions) {\n    apps(options: $options) {\n      totalItems\n      items { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n    }\n  }\n";
+export declare const APP_QUERY = "\n  query App($id: ID!) {\n    app(id: $id) { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n  }\n";
+export declare const REGISTER_MUTATION = "\n  mutation RegisterApp($manifest: JSON!) {\n    registerApp(manifest: $manifest) { \n  created\n  consentRequiredInstallationIds\n  consentReasons\n  app { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n }\n  }\n";
+export declare const UPDATE_MUTATION = "\n  mutation UpdateApp($id: ID!, $manifest: JSON!) {\n    updateApp(id: $id, manifest: $manifest) { \n  created\n  consentRequiredInstallationIds\n  consentReasons\n  app { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n }\n  }\n";
+export declare const ADD_KEY_MUTATION = "\n  mutation AddAppKey($appId: ID!, $kid: String!, $alg: String!, $publicKey: String!) {\n    addAppKey(appId: $appId, kid: $kid, alg: $alg, publicKey: $publicKey) {\n      id\n      kid\n      alg\n      publicKey\n      revokedAt\n      createdAt\n    }\n  }\n";
+export declare const REVOKE_KEY_MUTATION = "\n  mutation RevokeAppKey($appId: ID!, $kid: String!) {\n    revokeAppKey(appId: $appId, kid: $kid) {\n      id\n      kid\n      alg\n      revokedAt\n    }\n  }\n";
+export declare const SUSPEND_MUTATION = "\n  mutation SuspendApp($id: ID!) {\n    suspendApp(id: $id) { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n  }\n";
+export declare const RESUME_MUTATION = "\n  mutation ResumeApp($id: ID!) {\n    resumeApp(id: $id) { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n  }\n";
+export declare const ENABLE_MUTATION = "\n  mutation EnableAppForTenant($appId: ID!, $channelId: ID!) {\n    enableAppForTenant(appId: $appId, channelId: $channelId) { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n  }\n";
+export declare const DISABLE_MUTATION = "\n  mutation DisableAppForTenant($appId: ID!, $channelId: ID!) {\n    disableAppForTenant(appId: $appId, channelId: $channelId) { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n  }\n";
+/** A registered public key. Only public material is ever returned. */
+export interface AppKey {
+    id: string;
+    kid: string;
+    /** `EdDSA` | `RS256`. */
+    alg: string;
+    publicKey: string;
+    revokedAt: string | null;
+    createdAt: string;
+}
+export interface RegisteredApp extends App {
+    keys: AppKey[];
+    /** Channels a SuperAdmin has enabled this app for. */
+    enabledChannelIds: string[];
+}
+export interface RegisterAppResult {
+    app: RegisteredApp;
+    /** False when the manifest updated an app that was already registered. */
+    created: boolean;
+    /** Installations this registration moved to `needs_consent`. */
+    consentRequiredInstallationIds: string[];
+    /** Why, in the words their approvers will read. */
+    consentReasons: string[];
+}
+/**
+ * The app REGISTRY — the platform operator's surface (headless spec §6.3, §6.12).
+ *
+ * Human SuperAdmin session only, enforced twice over: the engine gates every
+ * operation on Vendure's `SuperAdmin` permission — not a custom one, because a
+ * custom permission is evaluated against the ACTIVE channel and every mutation
+ * here is platform-wide — and the SDK refuses to put a machine credential on the
+ * wire towards it at all (`requireHumanSession`). An app that could register
+ * apps could declare anything and enable itself.
+ */
+export interface PlatformAppsModule {
+    list(options?: {
+        skip?: number;
+        take?: number;
+    }, call?: Call): Promise<{
+        items: RegisteredApp[];
+        totalItems: number;
+    }>;
+    get(id: string, call?: Call): Promise<RegisteredApp | null>;
+    /** Ingest a `sixtynine.app.json`. Upserts by slug: a known slug is an update. */
+    register(manifest: Record<string, unknown>, call?: Call): Promise<RegisterAppResult>;
+    /** The same ingest addressed by id; refuses a manifest whose slug is another app's. */
+    update(id: string, manifest: Record<string, unknown>, call?: Call): Promise<RegisterAppResult>;
+    addKey(input: {
+        appId: string;
+        kid: string;
+        alg: string;
+        publicKey: string;
+    }, call?: Call): Promise<AppKey>;
+    revokeKey(appId: string, kid: string, call?: Call): Promise<AppKey>;
+    /** Suspend platform-wide and kill every installation token in one action. */
+    suspend(id: string, call?: Call): Promise<RegisteredApp>;
+    resume(id: string, call?: Call): Promise<RegisteredApp>;
+    /** Offer an app to one tenant. A tenant admin can only install what is enabled. */
+    enableForTenant(appId: string, channelId: string, call?: Call): Promise<RegisteredApp>;
+    disableForTenant(appId: string, channelId: string, call?: Call): Promise<RegisteredApp>;
+}
+export declare function createPlatformAppsModule(transport: Transport, config: AdminClientConfig): PlatformAppsModule;

package/dist/platform/apps.js

@@ -0,0 +1,153 @@
+import { APP_FIELDS } from '../apps/index.js';
+import { requireHumanSession } from './guard.js';
+const APP_WITH_KEYS_FIELDS = /* GraphQL */ `
+  ${APP_FIELDS}
+  keys {
+    id
+    kid
+    alg
+    publicKey
+    revokedAt
+    createdAt
+  }
+  enabledChannelIds
+`;
+const REGISTER_RESULT_FIELDS = /* GraphQL */ `
+  created
+  consentRequiredInstallationIds
+  consentReasons
+  app { ${APP_WITH_KEYS_FIELDS} }
+`;
+export const APPS_QUERY = /* GraphQL */ `
+  query Apps($options: AppListOptions) {
+    apps(options: $options) {
+      totalItems
+      items { ${APP_WITH_KEYS_FIELDS} }
+    }
+  }
+`;
+export const APP_QUERY = /* GraphQL */ `
+  query App($id: ID!) {
+    app(id: $id) { ${APP_WITH_KEYS_FIELDS} }
+  }
+`;
+export const REGISTER_MUTATION = /* GraphQL */ `
+  mutation RegisterApp($manifest: JSON!) {
+    registerApp(manifest: $manifest) { ${REGISTER_RESULT_FIELDS} }
+  }
+`;
+export const UPDATE_MUTATION = /* GraphQL */ `
+  mutation UpdateApp($id: ID!, $manifest: JSON!) {
+    updateApp(id: $id, manifest: $manifest) { ${REGISTER_RESULT_FIELDS} }
+  }
+`;
+export const ADD_KEY_MUTATION = /* GraphQL */ `
+  mutation AddAppKey($appId: ID!, $kid: String!, $alg: String!, $publicKey: String!) {
+    addAppKey(appId: $appId, kid: $kid, alg: $alg, publicKey: $publicKey) {
+      id
+      kid
+      alg
+      publicKey
+      revokedAt
+      createdAt
+    }
+  }
+`;
+export const REVOKE_KEY_MUTATION = /* GraphQL */ `
+  mutation RevokeAppKey($appId: ID!, $kid: String!) {
+    revokeAppKey(appId: $appId, kid: $kid) {
+      id
+      kid
+      alg
+      revokedAt
+    }
+  }
+`;
+export const SUSPEND_MUTATION = /* GraphQL */ `
+  mutation SuspendApp($id: ID!) {
+    suspendApp(id: $id) { ${APP_WITH_KEYS_FIELDS} }
+  }
+`;
+export const RESUME_MUTATION = /* GraphQL */ `
+  mutation ResumeApp($id: ID!) {
+    resumeApp(id: $id) { ${APP_WITH_KEYS_FIELDS} }
+  }
+`;
+export const ENABLE_MUTATION = /* GraphQL */ `
+  mutation EnableAppForTenant($appId: ID!, $channelId: ID!) {
+    enableAppForTenant(appId: $appId, channelId: $channelId) { ${APP_WITH_KEYS_FIELDS} }
+  }
+`;
+export const DISABLE_MUTATION = /* GraphQL */ `
+  mutation DisableAppForTenant($appId: ID!, $channelId: ID!) {
+    disableAppForTenant(appId: $appId, channelId: $channelId) { ${APP_WITH_KEYS_FIELDS} }
+  }
+`;
+export function createPlatformAppsModule(transport, config) {
+    const guarded = async (run) => {
+        requireHumanSession(config);
+        return run();
+    };
+    return {
+        list(options, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: APPS_QUERY, variables: { options: options ?? null } }, call);
+                return data.apps;
+            });
+        },
+        get(id, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: APP_QUERY, variables: { id } }, call);
+                return data.app;
+            });
+        },
+        register(manifest, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: REGISTER_MUTATION, variables: { manifest } }, call);
+                return data.registerApp;
+            });
+        },
+        update(id, manifest, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: UPDATE_MUTATION, variables: { id, manifest } }, call);
+                return data.updateApp;
+            });
+        },
+        addKey(input, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: ADD_KEY_MUTATION, variables: input }, call);
+                return data.addAppKey;
+            });
+        },
+        revokeKey(appId, kid, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: REVOKE_KEY_MUTATION, variables: { appId, kid } }, call);
+                return data.revokeAppKey;
+            });
+        },
+        suspend(id, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: SUSPEND_MUTATION, variables: { id } }, call);
+                return data.suspendApp;
+            });
+        },
+        resume(id, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: RESUME_MUTATION, variables: { id } }, call);
+                return data.resumeApp;
+            });
+        },
+        enableForTenant(appId, channelId, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: ENABLE_MUTATION, variables: { appId, channelId } }, call);
+                return data.enableAppForTenant;
+            });
+        },
+        disableForTenant(appId, channelId, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: DISABLE_MUTATION, variables: { appId, channelId } }, call);
+                return data.disableAppForTenant;
+            });
+        },
+    };
+}

package/dist/types.d.ts

@@ -48,9 +48,12 @@ export interface Me {
 }
 /** What `auth.whoami()` reports about the calling credential. */
 export interface WhoAmI {
-    /** `api_token` never discloses the hidden administrator behind the token. */
-    kind: 'api_token' | 'user';
-    /** Present only for a token principal; null for a human session. */
+    /**
+     * A MACHINE principal (`api_token`, `app_installation`) never discloses the
+     * hidden administrator behind it.
+     */
+    kind: 'api_token' | 'user' | 'app_installation';
+    /** Present only for a personal API token; null for every other principal. */
     token: {
         id: string;
         name: string;
@@ -60,7 +63,27 @@ export interface WhoAmI {
         lastUsedAt: string | null;
         scopeKind: string;
     } | null;
-    /** Present only for a human session; null for a token principal. */
+    /** Present only for `kind: 'app_installation'`; null otherwise. */
+    app: {
+        id: string;
+        slug: string;
+        name: string;
+    } | null;
+    /** Present only for `kind: 'app_installation'`; null otherwise. */
+    installation: {
+        id: string;
+        /** `channel` today; `organization` arrives with multi-region. */
+        targetKind: string;
+        targetId: string;
+        /**
+         * `active` | `needs_consent` | `suspended` | `uninstalled`. `needs_consent`
+         * is how an app learns the merchant has to approve declarations it has since
+         * grown — this credential keeps working with the OLD grants meanwhile.
+         */
+        status: string;
+        consentVersion: number;
+    } | null;
+    /** Present only for a human session; null for a machine principal. */
     user: {
         id: string;
         identifier: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sixtyninecommerce/admin",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Back-office SDK for sixtynine-commerce: every capability of the platform as a method",
   "homepage": "https://github.com/SIXTYNINE-digital/sixtynine-commerce-engine/tree/main/packages/admin-client#readme",
   "repository": {
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@sixtyninecommerce/core": "^0.2.3"
+    "@sixtyninecommerce/core": "^0.2.4"
   },
   "devDependencies": {
     "@types/node": "22.19.7",