@privos_ai/app-server 0.1.0 → 0.4.0

package/README.md

@@ -77,6 +77,195 @@ Your handler owns `tools/list`, `tools/call`, and custom resources.
 import { verifyPrivosUser } from '@privos_ai/app-server/auth';
 ```
 
+## Secretless workload identity
+
+Production Cluster installs mount a per-installation Unix socket. The runtime creates an
+ephemeral P-256 DPoP key in memory, attests through that socket, and refreshes a short-lived,
+sender-constrained token without writing credentials to disk or environment variables.
+
+```ts
+import { getWorkloadIdentityClient } from '@privos_ai/app-server/workload';
+
+const identity = getWorkloadIdentityClient();
+const capabilities = await identity.getEffectiveCapabilities();
+const stop = identity.onCapabilitiesChanged((next) => {
+  // Disable optional features when next.scopes no longer contains their scope.
+});
+
+identity.requireCapability('basic:information');
+const response = await identity.authorizedRequest('/api/v1/mcp-apps.context', {
+  requiredScope: 'basic:information',
+});
+```
+
+`authorizedFetch` only sends authorization to the Hub origin supplied by the broker. It retries
+one 401 automatically only for safe/idempotent methods; POST/PATCH require an explicit
+`retryMode: 'idempotent'`. `authorizedRequest` maps 403 to `WorkloadPermissionDeniedError` so
+optional-feature degradation is stable. Do not convert a workload token into a user identity;
+user-delegated operations stay in the iframe host bridge.
+
+Managed Cluster ingress uses the legacy workload boundary and should set
+`workloadSecurity: 'required'`. Protocol-v3 `SELF_HOSTED_LOCAL` and
+`PUBLISHER_HOSTED` runtimes must instead configure `runtimeDispatchV3`; the two
+security modes are deliberately mutually exclusive.
+
+## Protocol-v3 runtime dispatch
+
+The v3 receiver verifies the final Hub-to-app boundary independently of the
+managed workload broker. Direct HTTP accepts the assertion only in
+`X-PrivOS-MCP-Dispatch-Assertion`. Relay accepts it only at
+`params._meta.privosAuthorization`, reconstructs the exact signed logical RPC,
+removes `privosAuthorization` and `privosUser`, and passes only the sanitized RPC
+to the application handler.
+
+Direct HTTP has no separate runtime-installation or room-binding wrapper
+headers; both IDs are protected payload fields. Relay additionally carries
+`runtimeInstallationId` and, for room work, `authorizationBindingId` inside the
+reserved authorization wrapper, and the receiver cross-checks them before
+consuming replay state.
+
+```ts
+import {
+  BoundedRuntimeDispatchReplayConsumerV3,
+  createDirectRouter,
+  type RuntimeDispatchSecurityV3,
+  type RuntimeDispatchTrustHintV3,
+  type RuntimeDispatchTrustV3,
+} from '@privos_ai/app-server';
+
+// Load this from an authenticated provisioning/configuration channel. The
+// assertion itself and its unverified resolver hint are never trust sources.
+async function resolvePinnedTrust(
+  hint: RuntimeDispatchTrustHintV3,
+): Promise<RuntimeDispatchTrustV3> {
+  return trustStore.loadExactActiveGeneration(hint);
+}
+
+const runtimeDispatchV3: RuntimeDispatchSecurityV3 = {
+  mode: 'required',
+  trust: resolvePinnedTrust,
+  replayConsumer: new BoundedRuntimeDispatchReplayConsumerV3(),
+};
+
+app.use(createDirectRouter({
+  descriptor,
+  handler,
+  runtimeDispatchV3,
+}));
+```
+
+The pinned trust record must contain the Hub P-256 public JWK and its RFC 7638
+thumbprint `kid`, plus the exact workspace, deployment, app, execution mode,
+generation, runtime installation, manifest digest, and resource-manifest hash.
+Those stable fields exist before a local runtime starts. The signed assertion
+always contains the runtime inventory hash, approval receipt hash, and current
+authorization epoch; a dynamic publisher resolver may additionally supply any
+of those three as exact expectations once its trusted control-plane state has
+them. They are optional in static local startup trust because the runtime
+inventory is finalized only after readiness evidence exists.
+
+Use `parseRuntimeDispatchTrustV3Json` for strict JSON configuration parsing. It
+rejects unknown keys, private or non-P-256 JWK material, a mismatched key
+thumbprint, malformed affinity, and invalid optional expectations. A resolver
+hint is attacker-controlled until signature verification completes; use it only
+to locate a pre-provisioned record, then return that record for exact comparison.
+
+`BoundedRuntimeDispatchReplayConsumerV3` is process-local and suitable only for
+a single runtime process. A multi-process or multi-replica publisher must inject
+a shared implementation whose `consume` operation atomically reserves both the
+JTI and nonce until expiration. A full store fails closed; replay protection is
+never silently disabled.
+
+Local supervision or publisher connector provisioning must deliver the pinned
+trust record out of band before executable traffic is admitted. The receiver
+does not discover keys or affinity from a request and does not fall back to
+legacy/unsigned authorization when v3 is configured. Treat a deployment as
+blocked if its provisioning path does not supply this record (and, for multiple
+replicas, a shared atomic replay consumer).
+
+Publisher-hosted deployments can mount the production provisioning receiver:
+
+```ts
+const store = new SingleProcessFilePublisherRuntimeTrustStoreV3({
+  filePath: '/var/lib/my-app/privos-runtime-trust.json',
+  deploymentMode: 'single-process',
+});
+const portalJwksResolver = createPinnedPortalJwksResolverV3({
+  issuer: 'portal:marketplace-broker',
+  jwksUrl: 'https://portal.privos.io/approval-jwks',
+});
+
+// Mount before any global JSON parser so canonical raw bytes and duplicate
+// keys can be checked before proof verification.
+app.use(createPublisherRuntimeTrustProvisioningRouterV3({
+  provisioningUrl: manifest.runtimeTrustProvisioningUrl,
+  mcpAppId: manifest.name,
+  portalJwksResolver,
+  store,
+}));
+
+const runtimeDispatchV3: RuntimeDispatchSecurityV3 = {
+  mode: 'required',
+  trust: (hint) => store.resolveDispatchTrust(hint),
+  replayConsumer: store,
+};
+```
+
+The receiver independently verifies canonical Portal Ed25519 approval,
+execution-grant, and deployment-descriptor bytes, the exact artifact chain,
+the approval-pinned Hub P-256 key, a current single-use Hub possession proof,
+and the canonical request body before an atomic state transition. `PREPARE`
+exposes stable trust only to the three exact signed readiness RPCs. `ACTIVATE`
+pins the final inventory hash, approval hash, and authorization epoch; only then
+does the normal dynamic resolver authorize application traffic. An exact
+already-PREPARED generation may complete `ACTIVATE` after the Portal envelopes
+expire, but a fresh expired `PREPARE` is denied.
+
+`SingleProcessFilePublisherRuntimeTrustStoreV3` uses atomic file replacement and
+durable replay state but intentionally supports exactly one Node process. It is
+not safe for PM2 cluster mode, Kubernetes replicas, or multiple containers.
+Those deployments must provide a transactional shared implementation of
+`PublisherRuntimeTrustDurableStoreV3`; do not share the reference file over NFS.
+
+The default scaffolder maps the local production surface to
+`PRIVOS_RUNTIME_SECURITY_MODE=runtime-v3`, strict trust JSON in
+`PRIVOS_RUNTIME_DISPATCH_TRUST_V3`, and the optional Direct-only local activation
+probe switch `PRIVOS_RUNTIME_ALLOW_UNSIGNED_PREACTIVATION_READINESS=true`.
+Publisher mode instead uses `PRIVOS_PUBLISHER_RUNTIME_TRUST_STORE_PATH`,
+`PRIVOS_PORTAL_JWKS_URL`, `PRIVOS_PORTAL_ISSUER`, and the explicit
+`PRIVOS_PUBLISHER_SINGLE_PROCESS=true` guard. Publisher readiness is always
+signed and never enables the unsigned exception.
+
+Local Direct pre-activation probing has one explicit, non-authorizing exception:
+`unsignedReadiness: 'initialize-and-tools-list'`. It permits only these exact Hub
+messages:
+
+1. `initialize`, numeric ID `1`, protocol `2025-03-26`, the exact MCP UI
+   capability, and client `privos-hub/1.0.0`;
+2. bodyless `notifications/initialized` with no ID or params;
+3. `tools/list`, numeric ID `2`, and exactly empty params.
+
+Any extra key, metadata, different ID, or changed nested value is denied.
+`tools/call`, `resources/read`, and custom methods always require a valid
+assertion. Relay never permits unsigned discovery. After activation, Hub sends
+signed discovery requests as well.
+
+Verified runtime authorization is exposed as the frozen
+`ToolCallContext.runtimeAuthorization`. Room assertions include both the parent
+`runtimeInstallationId` and child `authorizationBindingId`; any separately
+verified actor JWT with a missing or different room is denied.
+
+## Manifest v2 preflight
+
+```bash
+npx privos-app-lint ./privos-app.json
+```
+
+The command rejects mixed legacy/v2 permission declarations and prints deterministic
+`canonicalManifestHash` and `publisherPermissionDeclarationHash` values. The latter covers the
+publisher declaration only; Hub/Portal compute the authoritative permission contract hash with
+the versioned server-owned catalog and immutable image digest.
+
 ## Scripts
 
 - `npm run build` — emit `dist/` (JS + `.d.ts`)

package/dist/app-descriptor.d.ts

@@ -1,5 +1,18 @@
 export declare const MCP_PROTOCOL_VERSION = "2025-03-26";
 export declare const MCP_UI_MIME = "text/html;profile=mcp-app";
+export type AppPermissionRequirement = 'required' | 'optional';
+export type AppPermissionContext = 'workspace' | 'room';
+export type AppPermissionExecutionContext = 'user' | 'background' | 'both';
+export interface AppPermissionDescriptor {
+    scope: string;
+    requirement: AppPermissionRequirement;
+    context: AppPermissionContext;
+    executionContext: AppPermissionExecutionContext;
+    feature: string;
+    reason: string;
+    recommended?: boolean;
+    degradedBehavior?: string;
+}
 export interface AppDescriptor {
     id: string;
     name: string;
@@ -13,6 +26,8 @@ export interface AppDescriptor {
         website?: string;
     };
     scopes?: readonly string[];
+    /** Manifest v2 permission contract. Do not combine with legacy scopes. */
+    permissions?: readonly AppPermissionDescriptor[];
     /** Direct manifest icon path/URL (e.g. `/public/icon.svg`). */
     manifestIcon?: string;
     /** Pairing / initialize icon (often a data URI for relay). */
@@ -21,6 +36,7 @@ export interface AppDescriptor {
     capabilities?: Record<string, unknown>;
 }
 export declare function validateDescriptorCapabilities(capabilities: Record<string, unknown> | undefined): void;
+export declare function validateDescriptorPermissions(descriptor: Pick<AppDescriptor, 'scopes' | 'permissions'>): void;
 export declare function buildInitializeResult(descriptor: AppDescriptor, options?: {
     uiEnabled?: boolean;
 }): {
@@ -35,5 +51,6 @@ export declare function buildPairingMetadata(descriptor: AppDescriptor): {
     version: string;
     icon?: string;
     scopes?: string[];
+    permissions?: AppPermissionDescriptor[];
 };
 //# sourceMappingURL=app-descriptor.d.ts.map

package/dist/app-descriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-descriptor.d.ts","sourceRoot":"","sources":["../src/app-descriptor.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD,eAAO,MAAM,WAAW,8BAA8B,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5D,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8FAA8F;IAC9F,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAID,wBAAgB,8BAA8B,CAC7C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC/C,IAAI,CASN;AAED,wBAAgB,qBAAqB,CACpC,UAAU,EAAE,aAAa,EACzB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/B;IACF,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CA6BA;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmBpF;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,aAAa,GAAG;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,CAQA"}
+{"version":3,"file":"app-descriptor.d.ts","sourceRoot":"","sources":["../src/app-descriptor.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD,eAAO,MAAM,WAAW,8BAA8B,CAAC;AAEvD,MAAM,MAAM,wBAAwB,GAAG,UAAU,GAAG,UAAU,CAAC;AAC/D,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,MAAM,CAAC;AACxD,MAAM,MAAM,6BAA6B,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,CAAC;AAE3E,MAAM,WAAW,uBAAuB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,wBAAwB,CAAC;IACtC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,gBAAgB,EAAE,6BAA6B,CAAC;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5D,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,0EAA0E;IAC1E,WAAW,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACjD,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8FAA8F;IAC9F,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAID,wBAAgB,8BAA8B,CAC7C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC/C,IAAI,CASN;AAED,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,aAAa,CAAC,GAAG,IAAI,CA4B7G;AAED,wBAAgB,qBAAqB,CACpC,UAAU,EAAE,aAAa,EACzB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/B;IACF,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CA+BA;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsBpF;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,aAAa,GAAG;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,uBAAuB,EAAE,CAAC;CACxC,CAUA"}

package/dist/app-descriptor.js

@@ -10,8 +10,39 @@ export function validateDescriptorCapabilities(capabilities) {
         }
     }
 }
+export function validateDescriptorPermissions(descriptor) {
+    if (descriptor.scopes?.length && descriptor.permissions?.length) {
+        throw new Error('descriptor must not combine legacy scopes with permissions v2');
+    }
+    if (!descriptor.permissions)
+        return;
+    if (descriptor.permissions.length === 0)
+        throw new Error('descriptor.permissions must not be empty');
+    const seen = new Set();
+    for (const permission of descriptor.permissions) {
+        if (!permission ||
+            !/^[-a-z0-9]+:[-a-z0-9:]+$/.test(permission.scope) ||
+            !['required', 'optional'].includes(permission.requirement) ||
+            !['workspace', 'room'].includes(permission.context) ||
+            !['user', 'background', 'both'].includes(permission.executionContext) ||
+            !/^[-a-z0-9.]+$/.test(permission.feature) ||
+            permission.reason.trim().length < 3) {
+            throw new Error(`invalid permission declaration: ${permission?.scope || 'unknown'}`);
+        }
+        if (seen.has(permission.scope))
+            throw new Error(`duplicate permission scope: ${permission.scope}`);
+        if (permission.requirement === 'optional' && (!permission.degradedBehavior || permission.degradedBehavior.trim().length < 10)) {
+            throw new Error(`optional permission must declare safe degraded behavior: ${permission.scope}`);
+        }
+        if (permission.requirement === 'required' && permission.degradedBehavior) {
+            throw new Error(`required permission cannot declare degraded behavior: ${permission.scope}`);
+        }
+        seen.add(permission.scope);
+    }
+}
 export function buildInitializeResult(descriptor, options) {
     validateDescriptorCapabilities(descriptor.capabilities);
+    validateDescriptorPermissions(descriptor);
     const capabilities = {
         tools: {},
         ...(options?.uiEnabled
@@ -33,6 +64,8 @@ export function buildInitializeResult(descriptor, options) {
         serverInfo.icon = descriptor.relayIcon;
     if (descriptor.scopes?.length)
         serverInfo.scopes = [...descriptor.scopes];
+    if (descriptor.permissions?.length)
+        serverInfo.permissions = descriptor.permissions.map((permission) => ({ ...permission }));
     return {
         protocolVersion: MCP_PROTOCOL_VERSION,
         capabilities,
@@ -40,7 +73,9 @@ export function buildInitializeResult(descriptor, options) {
     };
 }
 export function buildManifestJson(descriptor) {
+    validateDescriptorPermissions(descriptor);
     return {
+        schemaVersion: descriptor.permissions ? 2 : 1,
         name: descriptor.id,
         version: descriptor.version,
         title: descriptor.title || descriptor.name,
@@ -57,15 +92,18 @@ export function buildManifestJson(descriptor) {
             : {}),
         ...(descriptor.homepage ? { homepage: descriptor.homepage } : {}),
         ...(descriptor.scopes ? { scopes: [...descriptor.scopes] } : {}),
+        ...(descriptor.permissions ? { permissions: descriptor.permissions.map((permission) => ({ ...permission })) } : {}),
     };
 }
 export function buildPairingMetadata(descriptor) {
+    validateDescriptorPermissions(descriptor);
     return {
         name: descriptor.title || descriptor.name || descriptor.id,
         description: descriptor.description ?? '',
         version: descriptor.version,
         ...(descriptor.relayIcon ? { icon: descriptor.relayIcon } : {}),
         ...(descriptor.scopes?.length ? { scopes: [...descriptor.scopes] } : {}),
+        ...(descriptor.permissions?.length ? { permissions: descriptor.permissions.map((permission) => ({ ...permission })) } : {}),
     };
 }
 //# sourceMappingURL=app-descriptor.js.map

package/dist/app-descriptor.js.map

@@ -1 +1 @@
-{"version":3,"file":"app-descriptor.js","sourceRoot":"","sources":["../src/app-descriptor.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC;AAEjD,MAAM,CAAC,MAAM,WAAW,GAAG,2BAA2B,CAAC;AAmBvD,MAAM,wBAAwB,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;AAElE,MAAM,UAAU,8BAA8B,CAC7C,YAAiD;IAEjD,IAAI,CAAC,YAAY;QAAE,OAAO;IAC1B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QAC7C,IAAI,wBAAwB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CACd,kEAAkE,GAAG,GAAG,CACxE,CAAC;QACH,CAAC;IACF,CAAC;AACF,CAAC;AAED,MAAM,UAAU,qBAAqB,CACpC,UAAyB,EACzB,OAAiC;IAMjC,8BAA8B,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;IAExD,MAAM,YAAY,GAA4B;QAC7C,KAAK,EAAE,EAAE;QACT,GAAG,CAAC,OAAO,EAAE,SAAS;YACrB,CAAC,CAAC;gBACA,UAAU,EAAE;oBACX,4BAA4B,EAAE;wBAC7B,SAAS,EAAE,CAAC,WAAW,CAAC;qBACxB;iBACD;aACD;YACF,CAAC,CAAC,EAAE,CAAC;QACN,GAAG,CAAC,UAAU,CAAC,YAAY,IAAI,EAAE,CAAC;KAClC,CAAC;IAEF,MAAM,UAAU,GAA4B;QAC3C,IAAI,EAAE,UAAU,CAAC,KAAK,IAAI,UAAU,CAAC,IAAI,IAAI,UAAU,CAAC,EAAE;QAC1D,OAAO,EAAE,UAAU,CAAC,OAAO;KAC3B,CAAC;IACF,IAAI,UAAU,CAAC,SAAS;QAAE,UAAU,CAAC,IAAI,GAAG,UAAU,CAAC,SAAS,CAAC;IACjE,IAAI,UAAU,CAAC,MAAM,EAAE,MAAM;QAAE,UAAU,CAAC,MAAM,GAAG,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAE1E,OAAO;QACN,eAAe,EAAE,oBAAoB;QACrC,YAAY;QACZ,UAAU;KACV,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,UAAyB;IAC1D,OAAO;QACN,IAAI,EAAE,UAAU,CAAC,EAAE;QACnB,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,UAAU,CAAC,IAAI;QAC1C,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,EAAE;QACzC,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,GAAG,CAAC,UAAU,CAAC,MAAM;YACpB,CAAC,CAAC;gBACA,MAAM,EAAE;oBACP,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,IAAI;oBAC5B,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACtE,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC5E;aACD;YACF,CAAC,CAAC,EAAE,CAAC;QACN,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjE,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,UAAyB;IAO7D,OAAO;QACN,IAAI,EAAE,UAAU,CAAC,KAAK,IAAI,UAAU,CAAC,IAAI,IAAI,UAAU,CAAC,EAAE;QAC1D,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,EAAE;QACzC,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,GAAG,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxE,CAAC;AACH,CAAC"}
+{"version":3,"file":"app-descriptor.js","sourceRoot":"","sources":["../src/app-descriptor.ts"],"names":[],"mappings":"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"}

package/dist/context/platform-context.d.ts

@@ -0,0 +1,43 @@
+/**
+ * How the platform tells an app about itself.
+ *
+ * A PrivOS-managed runtime receives two variables the platform owns. The
+ * `PRIVOS_` prefix is reserved end to end — the Portal refuses a manifest that
+ * declares it, the Hub refuses to send it, and the Cluster refuses a grant that
+ * carries it — so a value read here can only have come from the platform.
+ */
+export type AppAccessMode = 'managed-runtime' | 'publisher-hosted';
+export interface PlatformContext {
+    /**
+     * This app's own public origin, e.g. `https://my-app.apps.privos.link`.
+     *
+     * This is NOT where tool calls and interface requests arrive: those ride the
+     * signed broker dispatch on `/mcp`, and reaching the app any other way is
+     * refused. Use the public origin for what genuinely has to be reachable from
+     * outside — public static media, webhook callbacks, OAuth redirect URIs.
+     *
+     * `undefined` when the app runs somewhere that does not allocate one, or on
+     * a platform release that predates the variable.
+     */
+    publicUrl?: string;
+    /**
+     * `managed-runtime` when PrivOS operates this container behind the broker,
+     * `publisher-hosted` when the publisher runs the endpoint themselves.
+     * `undefined` on a platform release that predates the variable.
+     */
+    accessMode?: AppAccessMode;
+}
+/**
+ * Read the platform-injected context. Undefined-safe by design: an app built
+ * against this SDK must still run on an older platform, and on a publisher's
+ * own infrastructure where nothing is injected at all.
+ */
+export declare function getPlatformContext(env?: NodeJS.ProcessEnv): PlatformContext;
+/**
+ * Absolute URL for a path on this app's public origin, or `undefined` when no
+ * public origin was injected. Prefer this over string concatenation so a
+ * missing origin is a visible `undefined` rather than a relative URL that
+ * silently resolves against the wrong host.
+ */
+export declare function publicUrlFor(path: string, env?: NodeJS.ProcessEnv): string | undefined;
+//# sourceMappingURL=platform-context.d.ts.map

package/dist/context/platform-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-context.d.ts","sourceRoot":"","sources":["../../src/context/platform-context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAEnE,MAAM,WAAW,eAAe;IAC/B;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC;CAC3B;AAKD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,eAAe,CASxF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAInG"}

package/dist/context/platform-context.js

@@ -0,0 +1,37 @@
+/**
+ * How the platform tells an app about itself.
+ *
+ * A PrivOS-managed runtime receives two variables the platform owns. The
+ * `PRIVOS_` prefix is reserved end to end — the Portal refuses a manifest that
+ * declares it, the Hub refuses to send it, and the Cluster refuses a grant that
+ * carries it — so a value read here can only have come from the platform.
+ */
+const isAccessMode = (value) => value === 'managed-runtime' || value === 'publisher-hosted';
+/**
+ * Read the platform-injected context. Undefined-safe by design: an app built
+ * against this SDK must still run on an older platform, and on a publisher's
+ * own infrastructure where nothing is injected at all.
+ */
+export function getPlatformContext(env = process.env) {
+    const publicUrl = env.PRIVOS_PUBLIC_URL;
+    const accessMode = env.PRIVOS_ACCESS_MODE;
+    return {
+        // A malformed value is treated as absent rather than passed on: an app
+        // that builds a callback URL from it would otherwise emit a broken one.
+        ...(typeof publicUrl === 'string' && publicUrl.startsWith('https://') ? { publicUrl } : {}),
+        ...(isAccessMode(accessMode) ? { accessMode } : {}),
+    };
+}
+/**
+ * Absolute URL for a path on this app's public origin, or `undefined` when no
+ * public origin was injected. Prefer this over string concatenation so a
+ * missing origin is a visible `undefined` rather than a relative URL that
+ * silently resolves against the wrong host.
+ */
+export function publicUrlFor(path, env = process.env) {
+    const { publicUrl } = getPlatformContext(env);
+    if (!publicUrl)
+        return undefined;
+    return new URL(path, publicUrl.endsWith('/') ? publicUrl : `${publicUrl}/`).toString();
+}
+//# sourceMappingURL=platform-context.js.map

package/dist/context/platform-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-context.js","sourceRoot":"","sources":["../../src/context/platform-context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAyBH,MAAM,YAAY,GAAG,CAAC,KAAyB,EAA0B,EAAE,CAC1E,KAAK,KAAK,iBAAiB,IAAI,KAAK,KAAK,kBAAkB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACtE,MAAM,SAAS,GAAG,GAAG,CAAC,iBAAiB,CAAC;IACxC,MAAM,UAAU,GAAG,GAAG,CAAC,kBAAkB,CAAC;IAC1C,OAAO;QACN,uEAAuE;QACvE,wEAAwE;QACxE,GAAG,CAAC,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3F,GAAG,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnD,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,MAAyB,OAAO,CAAC,GAAG;IAC9E,MAAM,EAAE,SAAS,EAAE,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAC9C,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IACjC,OAAO,IAAI,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;AACxF,CAAC"}

package/dist/context/tool-call-context.d.ts

@@ -1,3 +1,4 @@
+import type { VerifiedRuntimeDispatchAssertionV3 } from '../workload/dispatch-assertion.js';
 export interface VerifiedActor {
     /** JWT `sub` — stable opaque user id. */
     userId: string;
@@ -17,6 +18,8 @@ export interface ToolCallContext {
     appId?: string;
     traceId?: string;
     identityState: IdentityState;
+    /** Immutable Hub runtime authorization verified at the final HTTP/Relay boundary. */
+    readonly runtimeAuthorization?: VerifiedRuntimeDispatchAssertionV3;
     /**
      * Scope for duplicate in-flight JSON-RPC id detection.
      * Direct: MCP-Session-Id or per-request ephemeral id.

package/dist/context/tool-call-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-call-context.d.ts","sourceRoot":"","sources":["../../src/context/tool-call-context.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC7B,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC1C;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACnC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,aAAa,CAAC;IAC7B;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB"}
+{"version":3,"file":"tool-call-context.d.ts","sourceRoot":"","sources":["../../src/context/tool-call-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kCAAkC,EAAE,MAAM,mCAAmC,CAAC;AAE5F,MAAM,WAAW,aAAa;IAC7B,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC1C;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACnC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,aAAa,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,kCAAkC,CAAC;IACnE;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB"}

package/dist/direct/express-router.d.ts

@@ -2,6 +2,7 @@ import { Router, type Request } from 'express';
 import { type AppDescriptor } from '../app-descriptor.js';
 import type { AuthOptions } from '../auth/user-token.js';
 import { AppServerRuntime, extractDirectCallerCredential, type AppErrorMapper, type AppMcpHandler, type AppServerRuntimeOptions, type CallerCredentialExtractor, type RuntimeLimits, type UiResourceProvider } from '../runtime.js';
+import { type RuntimeDispatchSecurityV3 } from '../workload/dispatch-assertion.js';
 export interface DirectRouterOptions {
     descriptor: AppDescriptor | (() => AppDescriptor | Promise<AppDescriptor>);
     handler: AppMcpHandler;
@@ -24,6 +25,10 @@ export interface DirectRouterOptions {
         headers: Request['headers'];
     }>;
     runtime?: AppServerRuntime;
+    /** Require Hub dispatch assertions when the Cluster identity socket is mounted. */
+    workloadSecurity?: 'auto' | 'required' | 'disabled';
+    /** Explicit required final-boundary authorization for local or publisher protocol-v3 runtimes. */
+    runtimeDispatchV3?: RuntimeDispatchSecurityV3;
 }
 /**
  * Composable Express Router for Direct MCP transport.

package/dist/direct/express-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"express-router.d.ts","sourceRoot":"","sources":["../../src/direct/express-router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,EAAoC,MAAM,SAAS,CAAC;AAGjF,OAAO,EAEN,KAAK,aAAa,EAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAOzD,OAAO,EACN,gBAAgB,EAGhB,6BAA6B,EAE7B,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,mBAAmB;IACnC,UAAU,EAAE,aAAa,GAAG,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;IAC3E,OAAO,EAAE,aAAa,CAAC;IACvB,EAAE,CAAC,EAAE,kBAAkB,CAAC;IACxB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAC3C,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,oEAAoE;IACpE,uBAAuB,CAAC,EAAE,yBAAyB,CAAC;QACnD,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;KAC5B,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAUD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAgFvE;AAyFD,OAAO,EAAE,gBAAgB,EAAE,6BAA6B,EAAE,CAAC"}
+{"version":3,"file":"express-router.d.ts","sourceRoot":"","sources":["../../src/direct/express-router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,EAAoC,MAAM,SAAS,CAAC;AAGjF,OAAO,EAEN,KAAK,aAAa,EAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAOzD,OAAO,EACN,gBAAgB,EAGhB,6BAA6B,EAE7B,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAIN,KAAK,yBAAyB,EAE9B,MAAM,mCAAmC,CAAC;AAE3C,MAAM,WAAW,mBAAmB;IACnC,UAAU,EAAE,aAAa,GAAG,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;IAC3E,OAAO,EAAE,aAAa,CAAC;IACvB,EAAE,CAAC,EAAE,kBAAkB,CAAC;IACxB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAC3C,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,oEAAoE;IACpE,uBAAuB,CAAC,EAAE,yBAAyB,CAAC;QACnD,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;KAC5B,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IACpD,kGAAkG;IAClG,iBAAiB,CAAC,EAAE,yBAAyB,CAAC;CAC9C;AAYD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAsFvE;AAuKD,OAAO,EAAE,gBAAgB,EAAE,6BAA6B,EAAE,CAAC"}

package/dist/direct/express-router.js

@@ -3,12 +3,16 @@ import express from 'express';
 import { buildManifestJson, } from '../app-descriptor.js';
 import { INVALID_REQUEST, PARSE_ERROR, errorResponse, jsonRpcError, } from '../protocol/errors.js';
 import { AppServerRuntime, DEFAULT_MAX_MESSAGE_BYTES, ephemeralSessionScope, extractDirectCallerCredential, resolveCallerCredential, } from '../runtime.js';
+import { getWorkloadIdentityClient } from '../workload/workload-identity.js';
+import { isUnsignedRuntimeReadinessRpcV3, verifyDispatchAssertion, verifyRuntimeDispatchAssertionV3, } from '../workload/dispatch-assertion.js';
 const REQUIRED_CORS_HEADERS = [
     'Content-Type',
     'Authorization',
     'X-MCP-User-Id',
     'Mcp-Session-Id',
     'MCP-Protocol-Version',
+    'X-PrivOS-Dispatch-Assertion',
+    'X-PrivOS-MCP-Dispatch-Assertion',
 ];
 /**
  * Composable Express Router for Direct MCP transport.
@@ -27,6 +31,12 @@ export function createDirectRouter(options) {
             logger: options.logger,
         });
     const mcpPath = options.mcpPath ?? '/mcp';
+    if (options.runtimeDispatchV3 && mcpPath !== '/mcp') {
+        throw new Error('Protocol-v3 runtime dispatch requires the canonical /mcp path.');
+    }
+    if (options.runtimeDispatchV3 && options.workloadSecurity === 'required') {
+        throw new Error('Legacy managed workload security and runtime-v3 security cannot both be required.');
+    }
     const manifestPath = options.manifestPath ?? '/.well-known/mcp/manifest.json';
     const allowHeaders = mergeCorsHeaders(options.corsAllowHeaders);
     const maxBytes = runtime.getLimits().maxMessageBytes || DEFAULT_MAX_MESSAGE_BYTES;
@@ -82,25 +92,94 @@ export function createDirectRouter(options) {
     return router;
 }
 async function handleMcpPost(req, res, runtime, options) {
-    const extract = options.extractCallerCredential ??
-        ((ingress) => extractDirectCallerCredential(ingress.headers));
-    const credentialResolution = await resolveCallerCredential(extract, {
-        headers: req.headers,
-    });
     const body = req.body;
-    const requestId = body && typeof body === 'object' && Object.prototype.hasOwnProperty.call(body, 'id')
+    const candidateRequestId = body && typeof body === 'object' && Object.prototype.hasOwnProperty.call(body, 'id')
         ? body.id
         : undefined;
+    const requestId = candidateRequestId === null ||
+        typeof candidateRequestId === 'string' ||
+        typeof candidateRequestId === 'number'
+        ? candidateRequestId
+        : undefined;
+    let runtimeAuthorization;
+    const legacyAssertionHeaders = rawHeaderValues(req, 'x-privos-dispatch-assertion');
+    const runtimeAssertionHeaders = rawHeaderValues(req, 'x-privos-mcp-dispatch-assertion');
+    const unsupportedRuntimeAffinityHeaders = [
+        ...rawHeaderValues(req, 'x-privos-mcp-runtime-installation-id'),
+        ...rawHeaderValues(req, 'x-privos-mcp-authorization-binding-id'),
+    ];
+    if (unsupportedRuntimeAffinityHeaders.length > 0) {
+        denyDispatch(res, requestId);
+        return;
+    }
+    if (options.runtimeDispatchV3) {
+        try {
+            if (legacyAssertionHeaders.length > 0 || runtimeAssertionHeaders.length > 1) {
+                throw new Error('dispatch_assertion_ambiguous');
+            }
+            if (runtimeAssertionHeaders.length === 0) {
+                if (!isUnsignedRuntimeReadinessRpcV3(body, options.runtimeDispatchV3)) {
+                    throw new Error('dispatch_assertion_missing');
+                }
+            }
+            else {
+                runtimeAuthorization = await verifyRuntimeDispatchAssertionV3({
+                    compact: runtimeAssertionHeaders[0],
+                    body,
+                    security: options.runtimeDispatchV3,
+                });
+            }
+        }
+        catch {
+            denyDispatch(res, requestId);
+            return;
+        }
+    }
+    else {
+        if (runtimeAssertionHeaders.length > 0) {
+            denyDispatch(res, requestId);
+            return;
+        }
+        const workloadClient = getWorkloadIdentityClient();
+        const workloadSecurity = options.workloadSecurity ?? 'auto';
+        const requireDispatchAssertion = workloadSecurity === 'required' || (workloadSecurity === 'auto' && workloadClient.isAvailable());
+        if (requireDispatchAssertion) {
+            try {
+                const assertion = headerValue(req.headers['x-privos-dispatch-assertion']);
+                if (!assertion)
+                    throw new Error('dispatch_assertion_missing');
+                verifyDispatchAssertion({ compact: assertion, body, context: await workloadClient.brokerContext() });
+            }
+            catch {
+                denyDispatch(res, requestId);
+                return;
+            }
+        }
+    }
+    const extract = options.extractCallerCredential ??
+        ((ingress) => extractDirectCallerCredential(ingress.headers));
+    const credentialResolution = await resolveCallerCredential(extract, { headers: req.headers });
     const sessionHeader = headerValue(req.headers['mcp-session-id']);
     const sessionScope = sessionHeader?.trim()
         ? `mcp-session:${sessionHeader.trim()}`
         : ephemeralSessionScope('direct');
-    const context = await runtime.buildContext({
-        transport: 'direct',
-        requestId,
-        sessionScope,
-        credentialResolution,
-    });
+    let context;
+    try {
+        context = await runtime.buildContext({
+            transport: 'direct',
+            requestId,
+            sessionScope,
+            credentialResolution,
+            ...(runtimeAuthorization ? { runtimeAuthorization } : {}),
+        });
+    }
+    catch (error) {
+        if (runtimeAuthorization && error instanceof Error && error.message === 'dispatch_assertion_binding_mismatch') {
+            denyDispatch(res, requestId);
+            return;
+        }
+        throw error;
+    }
     const outcome = await runtime.dispatchObject(body, context);
     if (outcome.type === 'no_response' || outcome.type === 'protocol_warning') {
         res.status(202).end();
@@ -133,6 +212,19 @@ function headerValue(value) {
         return value[0];
     return value;
 }
+function rawHeaderValues(req, name) {
+    const values = [];
+    for (let index = 0; index < req.rawHeaders.length; index += 2) {
+        if (req.rawHeaders[index]?.toLowerCase() === name)
+            values.push(req.rawHeaders[index + 1] ?? '');
+    }
+    return values;
+}
+function denyDispatch(res, requestId) {
+    res.status(403).json(errorResponse(requestId ?? null, jsonRpcError(INVALID_REQUEST, 'Authenticated private dispatch required', {
+        code: 'DISPATCH_ASSERTION_INVALID',
+    })));
+}
 function mergeCorsHeaders(extra) {
     const set = new Set(REQUIRED_CORS_HEADERS.map((h) => h.toLowerCase()));
     const ordered = [...REQUIRED_CORS_HEADERS];