@mpgd/game-services 0.26.0 → 0.27.1

package/dist/client.d.ts

@@ -7,8 +7,10 @@ import type { MonetizationOperationStore } from './monetization-recovery.js';
 import type { GameServicesOperationClient } from './operations.js';
 export type { GameServicesOperationClient, GameServicesPurchaseInput, GameServicesPurchaseResult, GameServicesRewardedAdInput, GameServicesRewardedAdResult, } from './operations.js';
 import type { GameServicesContractClient } from './contract.js';
+import { type GameServicesHeaderResolver } from './request-headers.js';
 import type { ClaimAdRewardRequest, ClaimAdRewardResponse, GameServicesLedgerTarget, PurchaseLedgerStatusRequest, PurchaseLedgerStatusResponse, RecordLeaderboardScoreRequest, RecordLeaderboardScoreResponse, VerifyPurchaseRequest, VerifyPurchaseResponse } from './types.js';
 export type { GameServicesOperationKind, GameServicesOperationLocation, GameServicesOperationOptions, GameServicesOperationProgress, GameServicesPurchaseProgress, GameServicesRewardedAdProgress, } from './operation-progress.js';
+export { GameServicesHeaderResolutionError, resolveGameServicesRequestHeaders, type GameServicesHeaderResolver, } from './request-headers.js';
 export interface PurchaseVerificationApi {
   verifyPurchase(input: VerifyPurchaseRequest): Promise<VerifyPurchaseResponse>;
   /**
@@ -75,7 +77,6 @@ export interface CreateGameServicesOrpcClientInput {
   readonly headers?: Record<string, string>;
   readonly getHeaders?: GameServicesHeaderResolver;
 }
-export type GameServicesHeaderResolver = () => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
 export type GameServicesFetch = (url: string, init: {
   readonly method: 'POST';
   readonly headers: Record<string, string>;
@@ -96,16 +97,6 @@ export declare class GameServicesBackendTransportError extends Error {
   readonly endpoint: GameServicesBackendEndpoint;
   constructor(endpoint: GameServicesBackendEndpoint);
 }
-/** Credentials could not be resolved; no backend request was dispatched. */
-export declare class GameServicesHeaderResolutionError extends Error {
-  constructor();
-}
-/** Resolve rotating credentials once and preserve static → dynamic → request precedence. */
-export declare function resolveGameServicesRequestHeaders(input: {
-  readonly headers?: Readonly<Record<string, string>> | undefined;
-  readonly getHeaders?: GameServicesHeaderResolver | undefined;
-  readonly requestHeaders?: Readonly<Record<string, string>> | undefined;
-}): Promise<Readonly<Record<string, string>>>;
 export interface GameServicesClient extends GameServicesOperationClient {
   submitLeaderboardScore(input: GameServicesLeaderboardInput): Promise<GameServicesLeaderboardResult>;
   /**

package/dist/client.js

@@ -6,6 +6,8 @@ import { createCommerceReconciler, toGameServicesPurchaseResult, } from './comme
 import { createDefaultClientRewardEvidenceRegistry } from './default-client-reward-evidence.js';
 import { createInMemoryMonetizationOperationStore } from './monetization-operation-store.js';
 import { observeGameServicesOperation } from './operation-progress.js';
+import { GameServicesHeaderResolutionError, resolveGameServicesRequestHeaders, } from './request-headers.js';
+export { GameServicesHeaderResolutionError, resolveGameServicesRequestHeaders, } from './request-headers.js';
 export const gameServicesBackendEndpoints = {
     verifyPurchase: '/game-services/purchases/verify',
     getPurchaseLedgerStatus: '/game-services/purchases/ledger-status',
@@ -33,31 +35,6 @@ export class GameServicesBackendTransportError extends Error {
         this.endpoint = endpoint;
     }
 }
-/** Credentials could not be resolved; no backend request was dispatched. */
-export class GameServicesHeaderResolutionError extends Error {
-    constructor() {
-        super('Game Services request headers could not be resolved before dispatch.');
-        this.name = 'GameServicesHeaderResolutionError';
-    }
-}
-/** Resolve rotating credentials once and preserve static → dynamic → request precedence. */
-export async function resolveGameServicesRequestHeaders(input) {
-    let dynamicHeaders;
-    try {
-        dynamicHeaders = await input.getHeaders?.();
-    }
-    catch {
-        // Resolver exceptions can contain credentials; expose a stable outcome.
-        throw new GameServicesHeaderResolutionError();
-    }
-    const merged = new Map();
-    for (const layer of [input.headers, dynamicHeaders, input.requestHeaders]) {
-        for (const [name, value] of Object.entries(layer ?? {})) {
-            merged.set(name.toLowerCase(), value);
-        }
-    }
-    return Object.fromEntries(merged);
-}
 export function createGameServicesClient(input) {
     const now = input.now ?? (() => new Date().toISOString());
     const requestNow = input.requestNow ?? now;

package/dist/microsoft-store-purchase.d.ts

@@ -107,7 +107,12 @@ export interface MicrosoftStoreRecoveryOwnershipRecord {
   readonly storeId: string;
   readonly playerId: string;
   readonly generation: string;
-  /** Stable identity derived from the exact Collections item being granted. */
+  /**
+  * Identity of one Collections purchase. `transactionId` is preferred. When it
+  * is absent, the id is the collection item id plus `modifiedDate`, so a later
+  * purchase of the same item is distinct after the previous claim is released.
+  * An unreleased claim keeps the id it was claimed with.
+  */
   readonly providerPurchaseId: string;
 }
 export type MicrosoftStoreRecoveryOwnershipLookup = Omit<MicrosoftStoreRecoveryOwnershipRecord, 'generation' | 'providerPurchaseId'> & {
@@ -125,10 +130,9 @@ export type MicrosoftStoreRecoveryOwnershipResult = {
 export interface MicrosoftStoreRecoveryOwnershipStore {
   /**
   * Atomically claims an unconsumed Store product for one authenticated game player. An
-  * existing claim for the same provider purchase remains unchanged so a retry cannot replace
-  * its generation. A different provider purchase may atomically replace the same player's
-  * consumed purchase claim. Return the effective record, or undefined when another player owns
-  * the Store product binding.
+  * existing unreleased claim remains unchanged: a retry cannot replace its generation, and a
+  * different provider purchase cannot replace it until `release` runs after consume. Return
+  * the effective record, or undefined when another player owns the Store product binding.
   */
   claim(input: MicrosoftStoreRecoveryOwnershipRecord): Promise<MicrosoftStoreRecoveryOwnershipRecord | undefined>;
   get(input: MicrosoftStoreRecoveryOwnershipLookup): Promise<MicrosoftStoreRecoveryOwnershipRecord | undefined>;

package/dist/microsoft-store-purchase.js

@@ -11,11 +11,13 @@ export class InMemoryMicrosoftStoreRecoveryOwnershipStore {
         if (owner !== undefined && owner.playerId !== input.playerId) {
             return undefined;
         }
-        if (owner === undefined || owner.providerPurchaseId !== input.providerPurchaseId) {
-            this.owners.set(key, Object.freeze({ ...input }));
-            return Object.freeze({ ...input });
+        // A later Collections query can change modifiedDate or item id while quantity is still 1.
+        // Replacing that unreleased claim would mint a second ledger identity for the same unit.
+        if (owner !== undefined) {
+            return Object.freeze({ ...owner });
         }
-        return Object.freeze({ ...owner });
+        this.owners.set(key, Object.freeze({ ...input }));
+        return Object.freeze({ ...input });
     }
     async get(input) {
         const owner = this.owners.get(createRecoveryOwnershipKey(input));
@@ -174,7 +176,10 @@ export function createMicrosoftStorePurchaseBoundary(input) {
                 playerId,
             },
             ...(item.status === 'verified'
-                ? { providerPurchaseId: createVerificationId(item.item) }
+                ? {
+                    providerPurchaseId: createVerificationId(item.item),
+                    item: item.item,
+                }
                 : {}),
             ...(generation === undefined ? {} : { requestedGeneration: generation }),
         };
@@ -188,10 +193,21 @@ export function createMicrosoftStorePurchaseBoundary(input) {
             if (ownership.requestedGeneration === undefined) {
                 return { status: 'denied' };
             }
-            if (ownership.providerPurchaseId === undefined) {
+            if (ownership.providerPurchaseId === undefined || ownership.item === undefined) {
                 return { status: 'unavailable' };
             }
             try {
+                const existing = await input.recoveryOwnershipStore.get(ownership.record);
+                if (existing !== undefined) {
+                    if (existing.playerId !== ownership.record.playerId
+                        || !sameUnconsumedPurchase(existing.providerPurchaseId, ownership.item)
+                        || existing.generation !== ownership.requestedGeneration) {
+                        return { status: 'denied' };
+                    }
+                    // Keep the stored purchase id. Replacing it with a stable id would
+                    // make a later verify miss the ledger row already keyed by it.
+                    return { status: 'granted', idempotencyKey: existing.generation };
+                }
                 const effective = await input.recoveryOwnershipStore.claim({
                     ...ownership.record,
                     generation: ownership.requestedGeneration,
@@ -220,7 +236,7 @@ export function createMicrosoftStorePurchaseBoundary(input) {
                 if (existing.playerId !== ownership.record.playerId) {
                     return { status: 'denied' };
                 }
-                if (ownership.providerPurchaseId === undefined) {
+                if (ownership.providerPurchaseId === undefined || ownership.item === undefined) {
                     // Collections stops listing an item after consume. Preserve only an exact durable
                     // generation so its already-granted finalizer can retry a failed conditional release;
                     // a generationless listing still cannot establish player ownership.
@@ -231,23 +247,17 @@ export function createMicrosoftStorePurchaseBoundary(input) {
                         ? { status: 'granted', idempotencyKey: existing.generation }
                         : { status: 'denied' };
                 }
-                if (existing.providerPurchaseId === ownership.providerPurchaseId) {
-                    return (ownership.requestedGeneration === undefined
-                        || existing.generation === ownership.requestedGeneration)
+                if (!sameUnconsumedPurchase(existing.providerPurchaseId, ownership.item)) {
+                    // A changed item or transaction id is not a new unit while this claim is
+                    // unreleased. Do not mint a generation. The exact generation may resume so
+                    // its finalizer can consume and release; every other query stays denied.
+                    return ownership.requestedGeneration === existing.generation
                         ? { status: 'granted', idempotencyKey: existing.generation }
                         : { status: 'denied' };
                 }
-                if (ownership.requestedGeneration !== undefined) {
-                    return { status: 'denied' };
-                }
-                const effective = await input.recoveryOwnershipStore.claim({
-                    ...ownership.record,
-                    generation: await createRecoveryGeneration(ownership.providerPurchaseId),
-                    providerPurchaseId: ownership.providerPurchaseId,
-                });
-                return effective?.playerId === ownership.record.playerId
-                    && effective.providerPurchaseId === ownership.providerPurchaseId
-                    ? { status: 'granted', idempotencyKey: effective.generation }
+                return (ownership.requestedGeneration === undefined
+                    || existing.generation === ownership.requestedGeneration)
+                    ? { status: 'granted', idempotencyKey: existing.generation }
                     : { status: 'denied' };
             }
             catch {
@@ -347,27 +357,49 @@ export function createMicrosoftStorePurchaseBoundary(input) {
             if (!validIsoDate(verifiedAt)) {
                 return pending('MICROSOFT_STORE_VERIFIER_CLOCK_INVALID');
             }
-            const verificationId = createVerificationId(item.item);
-            if (recoveryOwnership.providerPurchaseId !== verificationId) {
+            const verificationId = recoveryOwnership.providerPurchaseId;
+            const currentItemMatches = sameUnconsumedPurchase(verificationId, item.item);
+            const storedIdentity = currentItemMatches
+                ? undefined
+                : readStoredCollectionIdentity(verificationId, item.item.productId);
+            if (!currentItemMatches && storedIdentity === undefined) {
                 return rejected('MICROSOFT_STORE_RECOVERY_OWNERSHIP_REQUIRED');
             }
+            // Keep the stored purchase id when Collections rotates the item. The ledger
+            // dedupes on that id, and finalization resumes the existing grant instead of
+            // writing a second one. The resume item id is only the consume echo.
+            const collectionItemId = storedIdentity?.itemId ?? item.item.id;
+            const transactionId = storedIdentity === undefined
+                ? item.item.transactionId
+                : storedIdentity.transactionId;
+            const modifiedDate = storedIdentity?.modifiedDate ?? item.item.modifiedDate;
+            const resumeCollectionItemId = storedIdentity !== undefined
+                && item.item.id !== collectionItemId
+                ? item.item.id
+                : undefined;
             return {
                 status: 'verified',
                 verificationId,
                 verifiedAt,
-                platformEvidenceId: null,
+                // The client purchase token is the add-on product, not a transaction.
+                // Publish the stored purchase id so the ledger's platform-transaction
+                // index applies, including a re-verify that must keep the legacy key.
+                platformEvidenceId: verificationId,
                 payload: {
-                    microsoftStoreCollectionItemId: item.item.id,
-                    microsoftStoreModifiedDate: item.item.modifiedDate,
+                    microsoftStoreCollectionItemId: collectionItemId,
+                    microsoftStoreModifiedDate: modifiedDate,
                     microsoftStoreProductId: item.item.productId,
                     microsoftStoreProductKind: item.item.productKind,
                     microsoftStoreQuantity: item.item.quantity,
                     microsoftStoreStatus: item.item.status,
                     microsoftStoreAccountBindingHash: accountBindingHash,
                     microsoftStoreRecoveryOwnershipGeneration: recoveryOwnership.generation,
-                    ...(item.item.transactionId === undefined
+                    ...(transactionId === undefined
+                        ? {}
+                        : { microsoftStoreTransactionId: transactionId }),
+                    ...(resumeCollectionItemId === undefined
                         ? {}
-                        : { microsoftStoreTransactionId: item.item.transactionId }),
+                        : { microsoftStoreResumeCollectionItemId: resumeCollectionItemId }),
                     digitalGoodsItemId: clientEvidence.itemId,
                 },
             };
@@ -432,16 +464,36 @@ async function consumeMicrosoftStorePurchase(input, finalizationInput, context)
             trackingId,
             signal: finalizationInput.signal,
         });
-        if (!isRecord(raw)) {
-            return finalizationPending('MICROSOFT_STORE_CONSUME_RESPONSE_INVALID');
+        if (!isRecord(raw) || raw.trackingId !== trackingId) {
+            return finalizationPending('MICROSOFT_STORE_CONSUME_RESPONSE_MISMATCH');
         }
-        if (raw.itemId !== context.collectionItemId
-            || raw.trackingId !== trackingId
-            || raw.newQuantity !== 0) {
+        const orderTransactions = readConsumeOrderTransactions(raw.orderTransactions);
+        const echoedItemId = optionalIdentifier(raw.itemId);
+        const itemMatches = echoedItemId !== undefined
+            && (echoedItemId === context.collectionItemId
+                || echoedItemId === context.resumeCollectionItemId);
+        // A reused tracking id is a confirmation, not a second consume. Microsoft
+        // documents that retry as the current remaining balance with order ids
+        // omitted. The echoed item must be the granted item or the item Collections
+        // currently lists for this product. A missing balance, a malformed balance,
+        // or an unrelated item keeps the claim.
+        const currentBalance = readDocumentedCurrentBalance(raw.newQuantity);
+        const echoedItemIsCurrent = !itemMatches
+            && echoedItemId !== undefined
+            && raw.orderTransactions === undefined
+            && currentBalance !== undefined
+            && currentBalance > 0
+            && await echoedItemIsCurrentCollection(input, credentials, context.storeId, echoedItemId, finalizationInput.signal);
+        const priorFulfillmentConfirmed = raw.orderTransactions === undefined
+            && currentBalance !== undefined
+            && currentBalance > 0
+            && (itemMatches || echoedItemIsCurrent);
+        if (!priorFulfillmentConfirmed
+            && (!itemMatches
+                || currentBalance !== 0)) {
             return finalizationPending('MICROSOFT_STORE_CONSUME_RESPONSE_MISMATCH');
         }
         if (input.persistConsumptionReceipt !== undefined) {
-            const orderTransactions = readConsumeOrderTransactions(raw.orderTransactions);
             // Some consume responses omit the product echo. Attribution comes from the
             // verified context and the item/tracking checks above; reject a conflicting echo.
             if ((raw.productId !== undefined && raw.productId !== context.storeId)
@@ -493,6 +545,28 @@ async function consumeMicrosoftStorePurchase(input, finalizationInput, context)
         return finalizationPending('MICROSOFT_STORE_CONSUME_UNAVAILABLE');
     }
 }
+async function echoedItemIsCurrentCollection(input, credentials, storeId, itemId, signal) {
+    let response;
+    try {
+        response = await input.client.queryProduct({ credentials, storeId, signal });
+    }
+    catch (error) {
+        if (signal.aborted) {
+            throw error;
+        }
+        return false;
+    }
+    const item = inspectPublisherQuery(response, storeId);
+    return item.status === 'verified' && item.item.id === itemId;
+}
+function readDocumentedCurrentBalance(value) {
+    // Consume documents newQuantity as an int: the remaining balance. A missing,
+    // fractional, or negative value is not that balance.
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        return undefined;
+    }
+    return value;
+}
 function readConsumeOrderTransactions(value) {
     // Microsoft documents omitted order IDs for developer-managed consume retries.
     // Never invent them from the collection item, client token, or tracking ID.
@@ -617,19 +691,23 @@ function readFinalizationContext(input) {
     const modifiedDate = optionalIdentifier(input.evidencePayload?.microsoftStoreModifiedDate);
     const accountBindingHash = optionalIdentifier(input.evidencePayload?.microsoftStoreAccountBindingHash);
     const recoveryOwnershipGeneration = optionalIdentifier(input.evidencePayload?.microsoftStoreRecoveryOwnershipGeneration);
+    const transactionId = optionalIdentifier(input.evidencePayload?.microsoftStoreTransactionId);
+    const resumeCollectionItemId = optionalIdentifier(input.evidencePayload?.microsoftStoreResumeCollectionItemId);
     // The binding and this verifier ship together in the first Store release. Missing bindings are
     // therefore malformed evidence, not legacy evidence, and must fail closed to prevent an account
-    // switch between verification and consumption.
+    // switch between verification and consumption. A grant already keyed by the modifiedDate id is
+    // not malformed: finalization must still accept that stored key.
     if (payloadStoreId === undefined
         || collectionItemId === undefined
         || modifiedDate === undefined
         || accountBindingHash === undefined
         || recoveryOwnershipGeneration === undefined
         || recoveryOwnershipGeneration !== input.request.idempotencyKey
-        || input.evidenceVerificationId !== createVerificationId({
+        || !sameUnconsumedPurchase(input.evidenceVerificationId, {
             id: collectionItemId,
             modifiedDate,
             productId: payloadStoreId,
+            ...(transactionId === undefined ? {} : { transactionId }),
         })) {
         return {
             status: 'pending',
@@ -641,22 +719,76 @@ function readFinalizationContext(input) {
     return {
         status: 'verified',
         collectionItemId,
+        ...(resumeCollectionItemId === undefined ? {} : { resumeCollectionItemId }),
         storeId: payloadStoreId,
         accountBindingHash,
         recoveryOwnershipGeneration,
     };
 }
 function createVerificationId(item) {
+    // transactionId names the purchase. When Collections omits it, modifiedDate
+    // is the documented per-purchase discriminator. An unreleased claim is not
+    // replaced with that new id; see sameUnconsumedPurchase.
+    return item.transactionId === undefined
+        ? `microsoft-store:${item.productId}:${item.id}:${item.modifiedDate}`
+        : `microsoft-store:${item.productId}:${item.id}:${item.transactionId}`;
+}
+/**
+ * Parses a verification id this boundary wrote. Item ids are not expected to
+ * contain `:`; a date suffix may, so only the first separator is split.
+ */
+function readStoredCollectionIdentity(verificationId, storeId) {
+    const prefix = `microsoft-store:${storeId}:`;
+    if (!verificationId.startsWith(prefix) || verificationId.length <= prefix.length) {
+        return undefined;
+    }
+    const rest = verificationId.slice(prefix.length);
+    const separator = rest.indexOf(':');
+    if (separator === -1) {
+        return optionalIdentifier(rest) === undefined ? undefined : { itemId: rest };
+    }
+    const itemId = rest.slice(0, separator);
+    const suffix = rest.slice(separator + 1);
+    if (optionalIdentifier(itemId) === undefined || optionalIdentifier(suffix) === undefined) {
+        return undefined;
+    }
+    return validIsoDate(suffix)
+        ? { itemId, modifiedDate: suffix }
+        : { itemId, transactionId: suffix };
+}
+/** Ledger key written when a purchase omits transactionId, including older rows. */
+function createLegacyVerificationId(item) {
     return `microsoft-store:${item.productId}:${item.id}:${item.modifiedDate}`;
 }
-/** Keep existing short generations stable while bounding new provider-derived request keys. */
-async function createRecoveryGeneration(providerPurchaseId) {
-    if (providerPurchaseId.length <= gameServicesRequestLimits.maxStringLength) {
-        return providerPurchaseId;
+/**
+ * True when a stored purchase id still names this unconsumed Collections item.
+ * A changed `modifiedDate` still matches, so that query resumes the stored
+ * claim instead of minting another id. A stored `transactionId` still matches
+ * if the collection item id changed. After release, a new modifiedDate is a
+ * new id because no stored claim remains to match.
+ */
+function sameUnconsumedPurchase(storedId, item) {
+    if (storedId === createVerificationId(item)
+        || storedId === createLegacyVerificationId(item)
+        || storedId === `microsoft-store:${item.productId}:${item.id}`) {
+        return true;
+    }
+    const itemPrefix = `microsoft-store:${item.productId}:${item.id}:`;
+    if (storedId.startsWith(itemPrefix)) {
+        const suffix = storedId.slice(itemPrefix.length);
+        if (validIsoDate(suffix)) {
+            return true;
+        }
+        return item.transactionId === undefined || item.transactionId === suffix;
+    }
+    if (item.transactionId !== undefined && !validIsoDate(item.transactionId)) {
+        const productPrefix = `microsoft-store:${item.productId}:`;
+        const transactionSuffix = `:${item.transactionId}`;
+        return storedId.startsWith(productPrefix)
+            && storedId.endsWith(transactionSuffix)
+            && storedId.length > productPrefix.length + transactionSuffix.length;
     }
-    const encoded = new TextEncoder().encode(providerPurchaseId);
-    const digest = new Uint8Array(await readGlobalSubtleCrypto().digest('SHA-256', encoded));
-    return `microsoft-store-recovery:${Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('')}`;
+    return false;
 }
 async function deterministicTrackingId(value) {
     const subtle = readGlobalSubtleCrypto();

package/dist/notifications/ait-functional-delivery.d.ts

@@ -31,7 +31,12 @@ import type { AppsInTossMutualTlsFetcher } from '../apps-in-toss-partner-api.js'
 *   recipient who has not agreed to the template. `agreementErrorCodes` and
 *   `agreementFailReasons` let a deployment name the ones it observes, so
 *   such an answer is `rejected` with reason `agreement` and records the
-*   denial; without them it is reason `recipient`.
+*   denial; without them it is reason `recipient`. A deployment list cannot
+*   override 4095, 5004, 4034, or 4010: those documented codes are classified
+*   first, so a rate limit is not stored as an agreement denial.
+* - `baseUrl` must be the partner API host (`apps-in-toss-api.toss.im`).
+*   The mTLS client certificate and the recipient key are not sent to any
+*   other host unless the caller sets `allowUnlistedHost` (tests only).
 * - Limits: 15,000 calls per minute per app and 10 per minute per user, the
 *   reference registry entry's `rate` and `limits`, which the scheduler and
 *   the gate apply.
@@ -39,6 +44,12 @@ import type { AppsInTossMutualTlsFetcher } from '../apps-in-toss-partner-api.js'
 export declare const aitFunctionalMessageProviderId: "apps-in-toss";
 export declare const aitFunctionalMessagePath = "api-partner/v1/apps-in-toss/messenger/send-message";
 export declare const defaultAitFunctionalMessageBaseUrl = "https://apps-in-toss-api.toss.im";
+/**
+* Hosts the partner certificate and the recipient key may be sent to.
+* `docs/APPS_IN_TOSS_PRODUCTION_EVIDENCE.md` names this production base and
+* no sandbox API host.
+*/
+export declare const aitFunctionalMessageAllowedHosts: readonly string[];
 export declare const defaultAitFunctionalMessageTimeoutMs = 10000;
 /** The longest `Retry-After` the provider passes on; the scheduler backs off from it. */
 export declare const maximumAitFunctionalMessageRetryAfterSeconds = 86400;
@@ -112,6 +123,12 @@ export interface CreateAitFunctionalMessageDeliveryProviderOptions {
   */
   readonly recipientKey: 'toss-user' | 'anonymous';
   readonly baseUrl?: string;
+  /**
+  * Send to a `baseUrl` whose host is not
+  * {@link aitFunctionalMessageAllowedHosts}. Tests only: a deployment that
+  * sets this can leak the partner certificate and the recipient key.
+  */
+  readonly allowUnlistedHost?: boolean;
   /** 1 to 60,000 ms, as the partner API client accepts. */
   readonly timeoutMs?: number;
   /** `FAIL` error codes that mean the recipient has not agreed to the template. */
@@ -135,13 +152,13 @@ export interface AitFunctionalMessageDeliveryProvider {
 *   With none sent, the per-channel `fail` lists decide: `rejected` with
 *   reason `agreement` when a failure's `reachedFailReason` is one of
 *   `agreementFailReasons`, otherwise `recipient`.
-* - `FAIL` with a code in `agreementErrorCodes` (first) or
-*   `recipientErrorCodes` is `rejected` with that reason, before any
-*   documented meaning of the code, on any status except HTTP 429, 5xx,
-*   408, and 425, which the status alone decides (see below);
-*   otherwise 4095 is `rate-limited` with `retryAfterSeconds` (at most a
-*   day), and 5004, 4034, and 4010 are `rejected` with reason
-*   `configuration`. Any other code is `rejected` with reason `recipient` on HTTP 200
+* - `FAIL` with a documented code is classified before any deployment list:
+*   4095 is `rate-limited` with `retryAfterSeconds` (at most a day), and
+*   5004, 4034, and 4010 are `rejected` with reason `configuration`. A
+*   deployment cannot store those as an agreement denial. Then a code in
+*   `agreementErrorCodes` or `recipientErrorCodes` is `rejected` with that
+*   reason, on any status except HTTP 429, 5xx, 408, and 425, which the
+*   status alone decides (see below). Any other code is `rejected` with reason `recipient` on HTTP 200
 *   and `configuration` when the HTTP status refused the request (400, 401,
 *   403, 404, 405, 413, 415, 422): a `FAIL` envelope reports a failed
 *   request, and answering `ambiguous` would replay a send that fails the

package/dist/notifications/ait-functional-delivery.js

@@ -30,7 +30,12 @@ import { notificationTemplateDataIssue, referenceNotificationProviders, } from '
  *   recipient who has not agreed to the template. `agreementErrorCodes` and
  *   `agreementFailReasons` let a deployment name the ones it observes, so
  *   such an answer is `rejected` with reason `agreement` and records the
- *   denial; without them it is reason `recipient`.
+ *   denial; without them it is reason `recipient`. A deployment list cannot
+ *   override 4095, 5004, 4034, or 4010: those documented codes are classified
+ *   first, so a rate limit is not stored as an agreement denial.
+ * - `baseUrl` must be the partner API host (`apps-in-toss-api.toss.im`).
+ *   The mTLS client certificate and the recipient key are not sent to any
+ *   other host unless the caller sets `allowUnlistedHost` (tests only).
  * - Limits: 15,000 calls per minute per app and 10 per minute per user, the
  *   reference registry entry's `rate` and `limits`, which the scheduler and
  *   the gate apply.
@@ -41,6 +46,12 @@ export const aitFunctionalMessagePath = 'api-partner/v1/apps-in-toss/messenger/s
 // `defaultAppsInTossPartnerApiTimeoutMs` (a test keeps them equal), kept here
 // so this module loads none of the partner client's code.
 export const defaultAitFunctionalMessageBaseUrl = 'https://apps-in-toss-api.toss.im';
+/**
+ * Hosts the partner certificate and the recipient key may be sent to.
+ * `docs/APPS_IN_TOSS_PRODUCTION_EVIDENCE.md` names this production base and
+ * no sandbox API host.
+ */
+export const aitFunctionalMessageAllowedHosts = Object.freeze(['apps-in-toss-api.toss.im']);
 export const defaultAitFunctionalMessageTimeoutMs = 10_000;
 /** The longest `Retry-After` the provider passes on; the scheduler backs off from it. */
 export const maximumAitFunctionalMessageRetryAfterSeconds = 86_400;
@@ -77,13 +88,13 @@ const maximumTimeoutMs = 60_000;
  *   With none sent, the per-channel `fail` lists decide: `rejected` with
  *   reason `agreement` when a failure's `reachedFailReason` is one of
  *   `agreementFailReasons`, otherwise `recipient`.
- * - `FAIL` with a code in `agreementErrorCodes` (first) or
- *   `recipientErrorCodes` is `rejected` with that reason, before any
- *   documented meaning of the code, on any status except HTTP 429, 5xx,
- *   408, and 425, which the status alone decides (see below);
- *   otherwise 4095 is `rate-limited` with `retryAfterSeconds` (at most a
- *   day), and 5004, 4034, and 4010 are `rejected` with reason
- *   `configuration`. Any other code is `rejected` with reason `recipient` on HTTP 200
+ * - `FAIL` with a documented code is classified before any deployment list:
+ *   4095 is `rate-limited` with `retryAfterSeconds` (at most a day), and
+ *   5004, 4034, and 4010 are `rejected` with reason `configuration`. A
+ *   deployment cannot store those as an agreement denial. Then a code in
+ *   `agreementErrorCodes` or `recipientErrorCodes` is `rejected` with that
+ *   reason, on any status except HTTP 429, 5xx, 408, and 425, which the
+ *   status alone decides (see below). Any other code is `rejected` with reason `recipient` on HTTP 200
  *   and `configuration` when the HTTP status refused the request (400, 401,
  *   403, 404, 405, 413, 415, 422): a `FAIL` envelope reports a failed
  *   request, and answering `ambiguous` would replay a send that fails the
@@ -109,24 +120,29 @@ export function createAitFunctionalMessageDeliveryProvider(options) {
         throw new TypeError("recipientKey must be 'toss-user' or 'anonymous'.");
     }
     const recipientHeader = options.recipientKey === 'anonymous' ? 'x-anon-key' : 'x-toss-user-key';
-    const url = new URL(aitFunctionalMessagePath, normalizeBaseUrl(options.baseUrl ?? defaultAitFunctionalMessageBaseUrl)).href;
+    const url = new URL(aitFunctionalMessagePath, normalizeBaseUrl(options.baseUrl ?? defaultAitFunctionalMessageBaseUrl, {
+        allowUnlistedHost: options.allowUnlistedHost === true,
+    })).href;
     const timeoutMs = normalizeTimeout(options.timeoutMs);
     const agreementErrorCodes = new Set(options.agreementErrorCodes ?? []);
     const recipientErrorCodes = new Set(options.recipientErrorCodes ?? []);
     const agreementFailReasons = new Set((options.agreementFailReasons ?? []).map((reason) => reason.trim()));
-    // The deployment's codes come first, then the documented ones (RFC
-    // "Delivery providers -> Apps in Toss").
+    // Documented codes come first (RFC "Delivery providers -> Apps in Toss"),
+    // then the deployment's. A list must not turn 4095 into an agreement denial.
     const classifyFailCode = (code, status) => {
+        if (code === rateLimitedErrorCode) {
+            return { status: 'rate-limited', providerCode: code };
+        }
+        if (configurationErrorCodes.has(code)) {
+            return { status: 'rejected', reason: 'configuration', providerCode: code };
+        }
         if (agreementErrorCodes.has(code)) {
             return { status: 'rejected', reason: 'agreement', providerCode: code };
         }
         if (recipientErrorCodes.has(code)) {
             return { status: 'rejected', reason: 'recipient', providerCode: code };
         }
-        if (code === rateLimitedErrorCode) {
-            return { status: 'rate-limited', providerCode: code };
-        }
-        if (configurationErrorCodes.has(code) || refusedRequestStatuses.has(status)) {
+        if (refusedRequestStatuses.has(status)) {
             return { status: 'rejected', reason: 'configuration', providerCode: code };
         }
         // An undocumented code on another status proves nothing either way.
@@ -421,8 +437,8 @@ function isCount(value) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/** A credential-free HTTPS base URL ending in `/`, as the partner API client requires. */
-function normalizeBaseUrl(input) {
+/** A credential-free HTTPS base URL ending in `/`, on an allowlisted partner host. */
+function normalizeBaseUrl(input, options) {
     const url = new URL(input);
     if (url.protocol !== 'https:'
         || url.username.length > 0
@@ -431,6 +447,11 @@ function normalizeBaseUrl(input) {
         || url.hash.length > 0) {
         throw new TypeError('The Apps in Toss partner API baseUrl must be a credential-free HTTPS URL.');
     }
+    const allowedHost = aitFunctionalMessageAllowedHosts.includes(url.hostname)
+        && (url.port === '' || url.port === '443');
+    if (!allowedHost && !options.allowUnlistedHost) {
+        throw new TypeError(`The Apps in Toss partner API baseUrl host must be ${aitFunctionalMessageAllowedHosts.join(' or ')}.`);
+    }
     url.pathname = url.pathname.endsWith('/') ? url.pathname : `${url.pathname}/`;
     return url.href;
 }