README

Modular PHP backend kit for the current Xapps backend contract.

Install

composer require xapps-platform/xapps-backend-kit

This package depends on xapps-platform/xapps-php and sits above it.

For the current XMS system behavior and API/package reader path, read:

docs/specifications/xms/README.md

Use it when you want a higher-level packaged backend contract with default routes, mode assembly, payment runtime composition, and override seams.

Use xapps-platform/xapps-php directly only when you need lower-level PHP primitives that the backend kit intentionally does not own.

Current public surface:

backend composition for the shipped backend contract

Direction:

PHP and Node variants should converge on the same backend contract
actor differences should live in adapters, rights/scope, config, and data access
not in duplicated platform backend logic

This package sits above:

xapps-platform/xapps-php

Use it when you want a working backend with default routes, default modes, and override seams, while keeping the later shared tenant/publisher direction open.

For request-capable publisher-rendered widgets, use the package layer to verify browser widget context server-side before exposing private runtime behavior:

$originPolicy = BackendKit::evaluateWidgetBootstrapOriginPolicy([
    'hostOrigin' => $request['body']['hostOrigin'] ?? null,
    'allowedOrigins' => $config['widgetBootstrap']['allowedOrigins'] ?? [],
]);

if (!($originPolicy['ok'] ?? false)) {
    http_response_code(($originPolicy['code'] ?? '') === 'HOST_ORIGIN_REQUIRED' ? 400 : 403);
    echo json_encode([
        'ok' => false,
        'error' => [
            'code' => $originPolicy['code'] ?? 'HOST_ORIGIN_NOT_ALLOWED',
            'message' => $originPolicy['message'] ?? 'Widget bootstrap origin rejected',
        ],
    ]);
    return;
}

$verified = BackendKit::verifyBrowserWidgetContext($gatewayClient, [
    'hostOrigin' => $originPolicy['hostOrigin'],
    'installationId' => 'inst_123',
    'bindToolName' => 'submit_form',
    'subjectId' => 'sub_123',
    'bootstrapTicket' => $request['body']['bootstrapTicket'] ?? null,
]);

Recommended shared local config contract for publisher-rendered bootstrap routes:

widgetBootstrap.allowedOrigins
optional app env:
- XAPPS_WIDGET_ALLOWED_ORIGINS=https://host.example.test,https://host-b.example.test

This stays local/app-owned on purpose. The package helper standardizes the policy behavior without forcing a framework-specific env contract.

Start Here

Consumer rule:

prefer Composer autoload plus the package file autoload
use the package entry surface
do not wire individual src/... files directly in consuming apps

Example:

require_once __DIR__ . "/vendor/autoload.php";

use Xapps\BackendKit\BackendKit;

Packaged consumers should prefer Composer autoload plus the package file autoload. Repo-local consumers can keep loading src/functions.php directly.

What It Gives You

The current package surface provides:

backend-kit option normalization
backend-kit composition
default route surface
default mode tree
payment runtime assembly
higher-level XMS purchase workflow helpers
host-proxy service assembly
request-widget bootstrap verification passthrough
subject-profile sourcing hooks

Internal package structure is intentionally modular:

src/BackendKit.php thin public facade
src/Backend/Support.php small shared value helpers
src/Backend/Options.php option normalization and config shaping
src/Backend/Runtime.php plain-PHP request/bootstrap helpers
src/Backend/PaymentRuntime.php payment runtime assembly and payment-page API helpers
src/Backend/Xms.php higher-level XMS purchase workflow helpers on top of the PHP gateway client
src/Backend/HostProxy.php host-proxy service and plain-app creation
src/Backend/Modules.php backend module composition
src/Backend/Modes/* explicit default mode tree
src/Backend/Routes/* explicit default route tree

Current route surface includes:

health
reference
host core
lifecycle
current-user host monetization lifecycle under /api/my-xapps/:xappId/...
- includes /api/my-xapps/:xappId/monetization/history for recent current-user XMS audit buckets
bridge
payment
guard
subject profiles

Current workflow helpers also include:

BackendKit::normalizeXappMonetizationScopeKind(...) normalizes subject / installation / realm scope selection
BackendKit::resolveXappMonetizationScope(...) resolves scope fields from runtime context plus optional realm reference
BackendKit::resolveXappHostedPaymentDefinition(...) resolves a manifest payment definition into hosted session config, including delegated signing metadata
BackendKit::listXappHostedPaymentPresets(...) shapes manifest payment definitions into generic hosted-lane preset options for UI selectors
BackendKit::findXappHostedPaymentPreset(...) looks up one hosted-lane preset by paymentGuardRef
BackendKit::readXappMonetizationSnapshot(...) reads the common app-facing XMS state bundle: access, current subscription, entitlements, and wallet accounts
BackendKit::buildXappMonetizationReferenceSummary(...) interprets the current-user XMS snapshot plus projected paywall packages into:
- primary recurring membership
- owned additive unlocks
- available additive unlocks
- recurring options
- credit top-ups
- blocked packages
host-mounted plans surfaces can now also consume the recent current-user history bundle exposed through:
- /api/my-xapps/:xappId/monetization/history
- portal /v1/me/xapps/:xappId/monetization/history
- embed /embed/my-xapps/:xappId/monetization/history
BackendKit::consumeXappWalletCredits(...) consumes credits from one wallet account through the XMS API and returns the updated wallet, ledger entry, and refreshed access projection
BackendKit::startXappHostedPurchase(...) prepares a purchase intent and creates the lane-bootstrapped gateway payment session
BackendKit::finalizeXappHostedPurchase(...) finalizes a hosted purchase through the platform finalize endpoint, returning reconciliation and issued access state
BackendKit::activateXappPurchaseReference(...) prepares a purchase intent, creates a verified reference transaction, and issues access

Verify locally

php packages/xapps-backend-kit-php/test/run.php
php packages/xapps-backend-kit-php/examples/smoke/smoke.php

Minimal usage

<?php

require_once __DIR__ . "/vendor/autoload.php";

use Xapps\BackendKit\BackendKit;

Current default mode tree includes:

gateway_managed
tenant_delegated
publisher_delegated
owner_managed

For owner_managed, the packaged default can run tenant-owned or publisher-owned. Use payments.ownerIssuer when the backend should default the owner-managed lane to publisher instead of tenant when the guard config does not narrow the issuer explicitly.

For hosted-integrator mode, the PHP kit mirrors the same secure bootstrap shape as the Node variant:

host.allowedOrigins
host.bootstrap.apiKeys
host.bootstrap.signingSecret
optional host.bootstrap.signingKeyId
optional host.bootstrap.verifierKeys
optional host.bootstrap.ttlSeconds

For the stronger host-session exchange posture, also configure:

host.session.signingSecret
optional host.session.signingKeyId
optional host.session.verifierKeys
host.session.absoluteTtlSeconds
optional host.session.idleTtlSeconds
host.session.cookiePath (recommended /api)
optional host.session.cookieDomain
host.session.cookieSameSite
host.session.cookieSecure
required when host.session.idleTtlSeconds > 0: host.session.store.activate
required when host.session.idleTtlSeconds > 0: host.session.store.touch
required host.session.store.isRevoked
required host.session.store.revoke
optional host.bootstrap.rateLimitBootstrap
optional host.bootstrap.auditBootstrap
optional host.bootstrap.deprecatedWarn
optional host.session.rateLimitLogout
optional host.session.auditLogout
optional host.session.auditRevocation

Minimal preferred session-store shape:

'host' => [
    'bootstrap' => [
        'apiKeys' => ['bootstrap_key_123'],
        'signingSecret' => 'bootstrap_secret_123',
    ],
    'session' => [
        'signingSecret' => 'session_secret_123',
        'absoluteTtlSeconds' => 1800,
        'idleTtlSeconds' => 900,
        'store' => [
            'activate' => static fn (array $input): bool => true,
            'touch' => static fn (array $input): array => ['active' => true],
            'isRevoked' => static fn (array $input): bool => false,
            'revoke' => static fn (array $input): bool => true,
        ],
    ],
],

Generic file-backed helpers are also available when you want backend-owned state without reimplementing the file locking and JSON persistence:

$consumeJti = BackendKit::createFileHostBootstrapReplayConsumer([
    'replayFile' => sys_get_temp_dir() . '/xapps-host-bootstrap-replay.json',
]);

$store = BackendKit::createFileHostSessionStore([
    'stateFile' => sys_get_temp_dir() . '/xapps-host-session-state.json',
    'revocationsFile' => sys_get_temp_dir() . '/xapps-host-session-revocations.json',
]);

Redis-backed helpers are available for multi-replica/shared-state deployments:

$redis = new \Redis();
$redis->connect('127.0.0.1', 6379);

$consumeJti = BackendKit::createRedisHostBootstrapReplayConsumer([
    'client' => $redis,
    'keyPrefix' => 'xapps:host',
]);

$store = BackendKit::createRedisHostSessionStore([
    'client' => $redis,
    'keyPrefix' => 'xapps:host',
]);

Redis key layout:

xapps:host:bootstrap:jti:{jti}
xapps:host:session:state:{jti}
xapps:host:session:revoked:{jti}

Important rule:

absoluteTtlSeconds is the real cookie/session lifetime baseline
host.session.signingSecret should be distinct from host.bootstrap.signingSecret
signingKeyId + verifierKeys enable additive key rotation; the current signingSecret remains the active signer, and verifierKeys can carry older verification keys by kid
idleTtlSeconds is only meaningful when both host.session.store.activate and host.session.store.touch are configured against backend-owned session state

Host auth classes:

browser bootstrap entry
- POST /api/browser/host-bootstrap
- browser-safe local renewal/bootstrap route
tenant bootstrap operation
- POST /api/host-bootstrap
- server-side X-API-Key
host control-plane
- host session cookie
- catalog/session/lifecycle/advanced bridge routes
token-scoped execution-plane
- gateway-issued widget/access token
- widget tool execution and current-user monetization routes

Execution-plane rule:

prefer Authorization: Bearer <token> on host execution-plane routes
query/body token input should be treated as compatibility input, not the preferred contract
when host_session_jti is present, execution tokens should also carry host_session_bound: true so verifiers can enforce host-session claims only for bound tokens
when execution tokens carry host_session_jti, backend-kit performs best-effort revoke propagation to POST /v1/host-sessions/revocations during host-session logout when gateway client config is present
manual revoke propagation to the same endpoint remains available for non-logout revocation sources

This split is intentional. The PHP backend kit should not turn the tenant backend into a generic gateway proxy. Host session protects the hosted control-plane. Scoped widget/access tokens protect execution-plane flows that already run on gateway-issued runtime tokens.

The tenant backend resolves subject through the gateway/host proxy and signs the short-lived browser bootstrap token locally. Raw platform API keys stay on the integrator backend or tenant backend, never in browser code.

That host.allowedOrigins allowlist covers the browser-facing host API surface, including:

/api/host-config
/api/resolve-subject
/api/create-catalog-session
/api/create-widget-session
/api/widget-tool-request
lifecycle routes under /api/install*
current-user XMS host routes under /api/my-xapps/:xappId/...
bridge routes under /api/bridge/*

Hosted-integrator session expectations are the same as in the Node backend kit:

browser hosts use a short-lived bootstrapToken only for POST /api/host-session/exchange
backend kit mints the host session cookie
ongoing hosted API calls use the host session cookie
widget sessions renew through /api/bridge/token-refresh
bootstrap renewal should re-run bootstrap instead of treating subjectId alone as durable proof
terminal widget-session failure should surface at the host shell layer, not as a raw iframe error

The PHP runtime should therefore be documented and reasoned about as an implementation variant of the same hosted-integrator/session contract, not as a separate feature line.

What Should Stay Local

A consuming app should still keep these local when they are actor-specific:

startup and env/config mapping
branding and host pages/assets
actor-specific subject-profile catalogs or resolver hooks
explicit mode or route overrides

Recommended Consumer Structure

Keep the local PHP adapter thin and predictable.

tenant-backend/
  bootstrap.php
  public/index.php
  lib/
    config.php
    appSurfaceModule.php
    subjectProfiles/defaultProfiles.php
  routes/
    host/
      pages.php
      shared.php
  modes/
    README.md
    */README.md

Recommended override order:

backend-kit options
local branding/assets and subject-profile data
injected services or resolver hooks
explicit route or mode overrides

Do not wire individual package route files directly in the app just to recreate the packaged backend surface locally.

When To Drop Lower

Use xapps-platform/xapps-php directly only when the consumer needs a lower-level PHP primitive that the backend kit intentionally does not own.

Rule

Do not add route-level wrapper aliases here.

Keep the public surface:

module oriented
config driven
hook based

Keep internals:

explicit
modular
safe to refactor behind the stable entry surface

Node and PHP should keep the same backend behavior in the end. Differences should be runtime-adapter concerns, not separate platform feature lines.

Verify locally

composer smoke

xapps-platform / xapps-backend-kit

Maintainers

Package info

Statistics

Security

README

Install

Start Here

What It Gives You

Verify locally

Minimal usage

What Should Stay Local

Recommended Consumer Structure

When To Drop Lower

Rule

Verify locally