@mpgd/game-services 0.15.3 → 0.17.0

package/dist/guest-session.js

@@ -0,0 +1,247 @@
+/** Error messages intentionally contain no token, proof, or installation ID. */
+export class GuestSessionCoordinatorError extends Error {
+    code;
+    constructor(code) {
+        super(`Guest session operation failed: ${code}.`);
+        this.name = 'GuestSessionCoordinatorError';
+        this.code = code;
+    }
+}
+const defaultCredentialKey = 'mpgd.guest.refresh';
+/**
+ * Serializes token mutation and closes synchronously on logout. Native secure
+ * storage failures never fall back to ordinary game storage or mint a new guest.
+ */
+export function createGuestSessionCoordinator(input) {
+    if (typeof input.installationId !== 'string' || input.installationId.trim() === '') {
+        throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_INPUT');
+    }
+    const credentialKey = input.credentialKey ?? defaultCredentialKey;
+    if (credentialKey.trim() === '') {
+        throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_INPUT');
+    }
+    const now = input.now ?? Date.now;
+    let current;
+    let status = 'idle';
+    let tail = Promise.resolve();
+    let startInFlight;
+    let refreshInFlight;
+    let logoutInFlight;
+    function enqueue(operation) {
+        const next = tail.then(operation, operation);
+        tail = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    function assertOpen() {
+        if (status === 'closed') {
+            throw new GuestSessionCoordinatorError('GUEST_SESSION_CLOSED');
+        }
+    }
+    function requireCurrent() {
+        if (status !== 'active' || current === undefined) {
+            throw new GuestSessionCoordinatorError('GUEST_SESSION_NOT_READY');
+        }
+        return current;
+    }
+    async function loadStoredRefreshToken() {
+        try {
+            const stored = await input.credentials.load({ key: credentialKey });
+            if (stored !== null && (typeof stored !== 'string' || stored === '')) {
+                throw new Error('Invalid stored refresh token.');
+            }
+            return stored;
+        }
+        catch {
+            throw new GuestSessionCoordinatorError('GUEST_SESSION_CREDENTIAL_LOAD_FAILED');
+        }
+    }
+    async function fromBackend(operation) {
+        try {
+            return await operation();
+        }
+        catch {
+            // Backend exceptions can contain URLs, proofs, or tokens. The public
+            // coordinator surface intentionally exposes only a stable error code.
+            throw new GuestSessionCoordinatorError('GUEST_SESSION_BACKEND_FAILED');
+        }
+    }
+    async function persist(next) {
+        try {
+            await input.credentials.save({ key: credentialKey, value: next.refreshToken });
+        }
+        catch {
+            // Keep the latest token only for an explicit revoke; never expose it as
+            // an active session after native persistence failed.
+            current = next;
+            if (status !== 'closed') {
+                status = 'failed';
+            }
+            throw new GuestSessionCoordinatorError('GUEST_SESSION_CREDENTIAL_SAVE_FAILED');
+        }
+        current = next;
+        if (status !== 'closed') {
+            status = 'active';
+        }
+    }
+    return {
+        async start() {
+            assertOpen();
+            if (status === 'active' && current !== undefined) {
+                return Promise.resolve(view(current));
+            }
+            if (startInFlight !== undefined) {
+                return startInFlight;
+            }
+            if (status === 'failed') {
+                return Promise.reject(new GuestSessionCoordinatorError('GUEST_SESSION_NOT_READY'));
+            }
+            startInFlight = enqueue(async () => {
+                assertOpen();
+                const stored = await loadStoredRefreshToken();
+                const next = validateSession(stored === null
+                    ? await fromBackend(() => input.backend.issueGuest({ installationId: input.installationId }))
+                    : await fromBackend(() => input.backend.refresh({ refreshToken: stored })));
+                await persist(next);
+                assertOpen();
+                return view(next);
+            }).finally(() => { startInFlight = undefined; });
+            return startInFlight;
+        },
+        async refresh() {
+            assertOpen();
+            if (refreshInFlight !== undefined) {
+                return refreshInFlight;
+            }
+            refreshInFlight = enqueue(async () => {
+                const previous = requireCurrent();
+                const next = validateSession(await fromBackend(() => input.backend.refresh({
+                    refreshToken: previous.refreshToken,
+                })));
+                assertSameOwner(previous, next);
+                await persist(next);
+                assertOpen();
+                return view(next);
+            }).finally(() => { refreshInFlight = undefined; });
+            return refreshInFlight;
+        },
+        async bindAccount(binding) {
+            assertOpen();
+            if (typeof binding.externalProof !== 'string' || binding.externalProof.trim() === ''
+                || typeof binding.idempotencyKey !== 'string' || binding.idempotencyKey.trim() === '') {
+                throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_INPUT');
+            }
+            return enqueue(async () => {
+                const previous = requireCurrent();
+                const result = await fromBackend(() => input.backend.bindAccount({
+                    refreshToken: previous.refreshToken,
+                    externalProof: binding.externalProof,
+                    idempotencyKey: binding.idempotencyKey,
+                }));
+                if (typeof result !== 'object' || result === null || !('status' in result)) {
+                    throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_RESPONSE');
+                }
+                if (result.status === 'conflict') {
+                    assertOpen();
+                    return { status: 'conflict' };
+                }
+                if (result.status !== 'bound' && result.status !== 'already-bound') {
+                    throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_RESPONSE');
+                }
+                const next = validateSession(result.session);
+                assertSameOwner(previous, next);
+                if (next.identityLevel !== 'authenticated') {
+                    throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_RESPONSE');
+                }
+                await persist(next);
+                assertOpen();
+                return { status: result.status };
+            });
+        },
+        getHeaders() {
+            assertOpen();
+            const active = requireCurrent();
+            if (Date.parse(active.accessExpiresAt) <= now()) {
+                throw new GuestSessionCoordinatorError('GUEST_SESSION_NOT_READY');
+            }
+            return { authorization: `Bearer ${active.accessToken}` };
+        },
+        logout() {
+            if (logoutInFlight !== undefined) {
+                return logoutInFlight;
+            }
+            status = 'closed';
+            const attempt = enqueue(async () => {
+                let token = current?.refreshToken;
+                if (token === undefined) {
+                    try {
+                        token = (await input.credentials.load({ key: credentialKey })) ?? undefined;
+                    }
+                    catch {
+                        // Keep the credential intact so a later logout can retry the load.
+                        throw new GuestSessionCoordinatorError('GUEST_SESSION_LOGOUT_UNCERTAIN');
+                    }
+                }
+                if (token !== undefined) {
+                    try {
+                        await input.backend.revoke({ refreshToken: token });
+                    }
+                    catch {
+                        // Do not delete a still-live refresh token on revoke failure.
+                        throw new GuestSessionCoordinatorError('GUEST_SESSION_LOGOUT_UNCERTAIN');
+                    }
+                }
+                try {
+                    await input.credentials.remove({ key: credentialKey });
+                }
+                catch {
+                    throw new GuestSessionCoordinatorError('GUEST_SESSION_LOGOUT_UNCERTAIN');
+                }
+                current = undefined;
+            });
+            logoutInFlight = attempt;
+            void attempt.catch(() => {
+                // A failed revoke or remove can be retried on this closed coordinator.
+                logoutInFlight = undefined;
+            });
+            return logoutInFlight;
+        },
+    };
+}
+function view(session) {
+    return {
+        serverUserId: session.serverUserId,
+        sessionId: session.sessionId,
+        identityLevel: session.identityLevel,
+        accessExpiresAt: session.accessExpiresAt,
+    };
+}
+// A server may already have consumed the previous refresh token. Persist a
+// well-formed rotated token even when the device clock makes access look expired.
+function validateSession(value) {
+    if (!isRecord(value)
+        || typeof value.serverUserId !== 'string' || value.serverUserId.trim() === ''
+        || typeof value.sessionId !== 'string' || value.sessionId.trim() === ''
+        || (value.identityLevel !== 'guest' && value.identityLevel !== 'authenticated')
+        || typeof value.accessToken !== 'string' || value.accessToken.trim() === ''
+        || typeof value.refreshToken !== 'string' || value.refreshToken.trim() === ''
+        || typeof value.accessExpiresAt !== 'string'
+        || !Number.isFinite(Date.parse(value.accessExpiresAt))) {
+        throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_RESPONSE');
+    }
+    return {
+        serverUserId: value.serverUserId,
+        sessionId: value.sessionId,
+        identityLevel: value.identityLevel,
+        accessToken: value.accessToken,
+        refreshToken: value.refreshToken,
+        accessExpiresAt: value.accessExpiresAt,
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertSameOwner(previous, next) {
+    if (previous.serverUserId !== next.serverUserId) {
+        throw new GuestSessionCoordinatorError('GUEST_SESSION_OWNERSHIP_CONFLICT');
+    }
+}

package/dist/index.d.ts

@@ -1,13 +1,17 @@
 export * from './admob-ssv.js';
 export * from './app-store-verifier.js';
+export * from './app-store-recovery.js';
 export * from './apps-in-toss-evidence-verification.js';
 export * from './apps-in-toss-partner-api.js';
 export * from './client.js';
 export * from './contract.js';
 export * from './evidence-verification.js';
+export * from './guest-session.js';
 export * from './google-play-purchase.js';
+export * from './google-play-publisher-client.js';
 export * from './microsoft-store-identity.js';
 export * from './microsoft-store-purchase.js';
+export * from './monetization-recovery.js';
 export * from './notification-delivery.js';
 export * from './platform-order.js';
 export * from './progress-link.js';

package/dist/index.js

@@ -1,13 +1,17 @@
 export * from './admob-ssv.js';
 export * from './app-store-verifier.js';
+export * from './app-store-recovery.js';
 export * from './apps-in-toss-evidence-verification.js';
 export * from './apps-in-toss-partner-api.js';
 export * from './client.js';
 export * from './contract.js';
 export * from './evidence-verification.js';
+export * from './guest-session.js';
 export * from './google-play-purchase.js';
+export * from './google-play-publisher-client.js';
 export * from './microsoft-store-identity.js';
 export * from './microsoft-store-purchase.js';
+export * from './monetization-recovery.js';
 export * from './notification-delivery.js';
 export * from './platform-order.js';
 export * from './progress-link.js';

package/dist/monetization-recovery.d.ts

@@ -0,0 +1,63 @@
+import type { PurchaseResult, RewardedAdResult } from '@mpgd/platform';
+import { type CreateGameServicesClientInput } from './client.js';
+import type { GameServicesOperationClient, GameServicesPurchaseInput, GameServicesPurchaseResult, GameServicesRewardedAdInput, GameServicesRewardedAdResult } from './operations.js';
+import type { ClaimAdRewardRequest, ClaimAdRewardResponse, VerifyPurchaseRequest, VerifyPurchaseResponse } from './types.js';
+interface OperationIdentity {
+  /** The store must enforce uniqueness across users, not just within one account. */
+  readonly key: string;
+  readonly playerId: string;
+  readonly target: string;
+  readonly deploymentTarget: string;
+  readonly revision: number;
+  /** Fixed when a platform result is first journaled, before backend dispatch. */
+  readonly platformCompletedAt?: string;
+}
+export type MonetizationOperationRecord = (OperationIdentity & {
+  readonly kind: 'purchase';
+  readonly input: GameServicesPurchaseInput;
+  readonly platform?: PurchaseResult;
+  readonly request?: VerifyPurchaseRequest;
+  readonly response?: VerifyPurchaseResponse;
+  readonly result?: GameServicesPurchaseResult;
+}) | (OperationIdentity & {
+  readonly kind: 'rewarded-ad';
+  readonly input: GameServicesRewardedAdInput;
+  readonly platform?: RewardedAdResult;
+  readonly request?: ClaimAdRewardRequest;
+  readonly response?: ClaimAdRewardResponse;
+  readonly result?: GameServicesRewardedAdResult;
+});
+/** Games must supply a durable, atomic implementation; an in-memory map is not recovery. */
+export interface MonetizationOperationStore {
+  /** Atomically insert or return the existing operation for this global key. */
+  reserve(record: MonetizationOperationRecord): Promise<{
+    readonly created: boolean;
+    readonly record: MonetizationOperationRecord;
+  }>;
+  read(key: string): Promise<MonetizationOperationRecord | undefined>;
+  /** Compare-and-swap; reject stale revisions and changes to immutable identity. */
+  replace(expectedRevision: number, record: MonetizationOperationRecord): Promise<void>;
+  /** Return only unresolved operations; keep terminal records addressable by read for deduplication. */
+  listRecoverable(playerId: string): Promise<readonly MonetizationOperationRecord[]>;
+}
+export interface CreateRecoverableMonetizationClientInput extends CreateGameServicesClientInput {
+  readonly operationStore: MonetizationOperationStore;
+}
+export interface MonetizationOperationSummary {
+  readonly kind: MonetizationOperationRecord['kind'];
+  readonly idempotencyKey: string;
+  readonly status: 'pending' | 'granted' | 'rejected' | 'cancelled' | 'failed' | 'skipped' | 'unavailable' | 'action-required';
+  readonly finalizationPending: boolean;
+}
+export interface RecoverableMonetizationClient extends GameServicesOperationClient {
+  recoverPurchaseResult(idempotencyKey: string, platform: PurchaseResult): Promise<GameServicesPurchaseResult>;
+  recoverRewardResult(idempotencyKey: string, platform: RewardedAdResult): Promise<GameServicesRewardedAdResult>;
+  reconcile(): Promise<readonly MonetizationOperationSummary[]>;
+}
+/**
+* Client-side recovery coordinates UI callbacks and authoritative backend calls.
+* It never grants a wallet locally. Journal evidence can contain receipts/tokens,
+* so the game's durable store must encrypt and access-control its records.
+*/
+export declare function createRecoverableMonetizationClient(input: CreateRecoverableMonetizationClientInput): RecoverableMonetizationClient;
+export {};