@uns-kit/core 3.0.42 → 3.0.44

package/MIGRATIONS.md

@@ -9,6 +9,40 @@ Agents must inspect the application's existing ownership and shutdown flow
 before editing it. The examples below describe the intended behavior, not a
 mechanical search-and-replace operation.
 
+## 3.0.44 - Bounded operator JWKS recovery
+
+When crossing `<3.0.44` to `>=3.0.44`, ordinary application handlers, standalone
+shutdown and existing input/output journals need no migration. Applications using
+declared operator endpoints receive this correction from `@uns-kit/api`; consume
+the reviewed published API/core versions together with a frozen dependency lock.
+No application-specific retry wrapper, configuration flag or new Controller
+capability is needed.
+
+The shared verifier coalesces key refreshes and retries a transient public-key GET
+once within a bounded deadline. It does not retry an operator request or business
+effect, extend the original key-cache lifetime, or skip parent revocation checks.
+Persistent key-source failure remains a503 and a revoked parent remains denied.
+Keep existing service permissions, launch identity, keys, queues, pause policies
+and durable command receipts; never resume a paused target or broaden scopes to
+make an upgrade pass. Follow the normal reviewed upgrade procedure after npm
+publication. See the [operator contract and regression examples](../../docs/operator-api.md#bounded-jwks-recovery-3044).
+
+## 3.0.43 - Shared managed operator route registration
+
+This entry describes the prepared 3.0.43 release; npm publication is separate. Existing ordinary
+API endpoints and standalone services require no changes. Applications exposing
+`operatorOperations` must adopt the coordinated API/core release, then be launched
+by a Controller providing the reviewed route-token file and exact launch metadata.
+`UnsApiProxy` registers and renews its own route automatically; no application-name
+branch or custom route publisher is needed. Route credentials grant no data or
+operator-command permissions. See [the contract](../../docs/operator-api.md).
+
+Do not replace the owning Controller URL with a generic master URL, copy tokens
+into config, normalize the launch's version tag or broaden service scopes to make
+registration succeed. A Controller-only hot update cannot add launch metadata to
+an already running process. Use the normal reviewed restart/upgrade after the
+coordinated versions are published. Keep old application data and queues intact.
+
 ## 3.0.42 - Opt-in registered operator APIs and Service API body metadata
 
 Existing applications require no operator-API change when crossing this version.

package/dist/runtime/route-registration.d.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+export declare const RUNTIME_ROUTE_REGISTRATION_PATH = "/api/runtime-services/routes";
+export declare const RUNTIME_ROUTE_REGISTRATION_LEASE_MS = 30000;
+export declare const runtimeRouteDeploymentSchema: z.ZodObject<{
+    controllerName: z.ZodString;
+    rttNode: z.ZodString;
+    version: z.ZodString;
+    instanceId: z.ZodString;
+    launchId: z.ZodString;
+}, z.core.$strict>;
+export type RuntimeRouteDeployment = z.infer<typeof runtimeRouteDeploymentSchema>;
+export declare function runtimeRouteOrigin(value: string): string;
+export declare const runtimeRouteBindingSchema: z.ZodObject<{
+    processName: z.ZodString;
+    version: z.ZodString;
+    apiHost: z.ZodString;
+    controllerName: z.ZodString;
+    controllerPublicBase: z.ZodString;
+    instanceId: z.ZodString;
+    deploymentId: z.ZodString;
+}, z.core.$strict>;
+export type RuntimeRouteBinding = z.infer<typeof runtimeRouteBindingSchema>;
+export declare const runtimeRouteReceiptSchema: z.ZodObject<{
+    protocolVersion: z.ZodLiteral<1>;
+    expiresInMs: z.ZodLiteral<30000>;
+    binding: z.ZodObject<{
+        processName: z.ZodString;
+        version: z.ZodString;
+        apiHost: z.ZodString;
+        controllerName: z.ZodString;
+        controllerPublicBase: z.ZodString;
+        instanceId: z.ZodString;
+        deploymentId: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** A receipt is ownership evidence only for this exact process launch/origin. */
+export declare function readRuntimeRouteReceipt(value: unknown, expected: RuntimeRouteDeployment & {
+    processName: string;
+    apiHost: string;
+}): {
+    protocolVersion: 1;
+    expiresInMs: 30000;
+    binding: {
+        processName: string;
+        version: string;
+        apiHost: string;
+        controllerName: string;
+        controllerPublicBase: string;
+        instanceId: string;
+        deploymentId: string;
+    };
+};
+//# sourceMappingURL=route-registration.d.ts.map

package/dist/runtime/route-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-registration.d.ts","sourceRoot":"","sources":["../../src/runtime/route-registration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,+BAA+B,iCAAiC,CAAC;AAC9E,eAAO,MAAM,mCAAmC,QAAS,CAAC;AAE1D,eAAO,MAAM,4BAA4B;;;;;;kBAG9B,CAAC;AACZ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMxD;AAED,eAAO,MAAM,yBAAyB;;;;;;;;kBAG3B,CAAC;AACZ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAC5E,eAAO,MAAM,yBAAyB;;;;;;;;;;;;kBAE3B,CAAC;AAEZ,iFAAiF;AACjF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,sBAAsB,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;EAQlI"}

package/dist/runtime/route-registration.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+export const RUNTIME_ROUTE_REGISTRATION_PATH = "/api/runtime-services/routes";
+export const RUNTIME_ROUTE_REGISTRATION_LEASE_MS = 30_000;
+const name = z.string().min(1).max(256);
+export const runtimeRouteDeploymentSchema = z.object({
+    controllerName: name, rttNode: name, version: name, instanceId: name,
+    launchId: z.string().regex(/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/),
+}).strict();
+export function runtimeRouteOrigin(value) {
+    if (typeof value !== "string" || value.length > 2048)
+        throw Error("Invalid runtime route origin");
+    const url = new URL(value);
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== "/")
+        throw Error("Invalid runtime route origin");
+    return url.origin;
+}
+export const runtimeRouteBindingSchema = z.object({
+    processName: name, version: name, apiHost: z.string().min(1).max(2048), controllerName: name,
+    controllerPublicBase: z.string().min(1).max(2048), instanceId: name, deploymentId: z.string().min(1).max(1024),
+}).strict();
+export const runtimeRouteReceiptSchema = z.object({
+    protocolVersion: z.literal(1), expiresInMs: z.literal(RUNTIME_ROUTE_REGISTRATION_LEASE_MS), binding: runtimeRouteBindingSchema,
+}).strict();
+/** A receipt is ownership evidence only for this exact process launch/origin. */
+export function readRuntimeRouteReceipt(value, expected) {
+    const receipt = runtimeRouteReceiptSchema.parse(value), binding = receipt.binding;
+    if (binding.controllerName !== expected.controllerName || binding.instanceId !== expected.instanceId
+        || binding.version !== expected.version || binding.processName !== expected.processName
+        || runtimeRouteOrigin(binding.apiHost) !== runtimeRouteOrigin(expected.apiHost)
+        || !binding.deploymentId.startsWith(expected.launchId + ":"))
+        throw Error("Runtime route receipt does not match launch");
+    runtimeRouteOrigin(binding.controllerPublicBase);
+    return receipt;
+}
+//# sourceMappingURL=route-registration.js.map

package/dist/runtime/route-registration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-registration.js","sourceRoot":"","sources":["../../src/runtime/route-registration.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\n\nexport const RUNTIME_ROUTE_REGISTRATION_PATH = \"/api/runtime-services/routes\";\nexport const RUNTIME_ROUTE_REGISTRATION_LEASE_MS = 30_000;\nconst name = z.string().min(1).max(256);\nexport const runtimeRouteDeploymentSchema = z.object({\n  controllerName: name, rttNode: name, version: name, instanceId: name,\n  launchId: z.string().regex(/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/),\n}).strict();\nexport type RuntimeRouteDeployment = z.infer<typeof runtimeRouteDeploymentSchema>;\n\nexport function runtimeRouteOrigin(value: string): string {\n  if (typeof value !== \"string\" || value.length > 2048) throw Error(\"Invalid runtime route origin\");\n  const url = new URL(value);\n  if (![\"http:\", \"https:\"].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== \"/\")\n    throw Error(\"Invalid runtime route origin\");\n  return url.origin;\n}\n\nexport const runtimeRouteBindingSchema = z.object({\n  processName: name, version: name, apiHost: z.string().min(1).max(2048), controllerName: name,\n  controllerPublicBase: z.string().min(1).max(2048), instanceId: name, deploymentId: z.string().min(1).max(1024),\n}).strict();\nexport type RuntimeRouteBinding = z.infer<typeof runtimeRouteBindingSchema>;\nexport const runtimeRouteReceiptSchema = z.object({\n  protocolVersion: z.literal(1), expiresInMs: z.literal(RUNTIME_ROUTE_REGISTRATION_LEASE_MS), binding: runtimeRouteBindingSchema,\n}).strict();\n\n/** A receipt is ownership evidence only for this exact process launch/origin. */\nexport function readRuntimeRouteReceipt(value: unknown, expected: RuntimeRouteDeployment & { processName: string; apiHost: string }) {\n  const receipt = runtimeRouteReceiptSchema.parse(value), binding = receipt.binding;\n  if (binding.controllerName !== expected.controllerName || binding.instanceId !== expected.instanceId\n    || binding.version !== expected.version || binding.processName !== expected.processName\n    || runtimeRouteOrigin(binding.apiHost) !== runtimeRouteOrigin(expected.apiHost)\n    || !binding.deploymentId.startsWith(expected.launchId + \":\")) throw Error(\"Runtime route receipt does not match launch\");\n  runtimeRouteOrigin(binding.controllerPublicBase);\n  return receipt;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uns-kit/core",
-  "version": "3.0.42",
+  "version": "3.0.44",
   "description": "Core utilities and runtime building blocks for UNS-based realtime transformers.",
   "type": "module",
   "license": "MIT",