@uns-kit/core 3.0.46 → 3.0.48

package/MIGRATIONS.md

@@ -9,6 +9,35 @@ 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.48 - Checked Service access documentation and examples
+
+This patch clarifies existing 3.0.47 contracts; no new permission mode or automatic
+application migration is introduced. Follow the
+[source walkthrough](https://github.com/uns-openhub/uns-kit/blob/master/docs/catalog-publication-access.md)
+or bundled `@uns-kit/core/runtime/service-access-guide.md` and complete projects in
+`dist/runtime/service-access-examples/`. Examples use a rotating token provider;
+background API reads, caller-mediated catalogs and MQTT ACLs are separate.
+An application adopting the capability must still follow the 3.0.47 entry below.
+
+## 3.0.47 - Common Service access and publications
+
+When crossing `<3.0.47` to `>=3.0.47`, adoption is explicit; existing endpoint authorization and caller forwarding do
+not change automatically. Ship `service-access.json` referenced by
+`package.json` `unsDatahub.serviceAccess`, retaining the data file in the build.
+Use `parseServiceAccessDeclaration` and review the exact installed release in
+Controller Service access. Background services need no Catalog/API. Optional
+`publications` reuse the catalog manifest, `CatalogPublicationClient`, and API
+`catalogPublicationHandler`; call `api.registerCatalogRoute()` for signed launch
+route publication. Source approval remains separate from raw workload rights.
+The unpublished earlier `catalogAccess` marker is a compatibility reader only;
+never declare both. Read the [bundled Service access guide](dist/runtime/service-access-guide.md).
+
+Do not remove existing credentials until the new path passes deployed
+acceptance. The matching Controller capability must be installed and reviewed
+before enabling the declaration. SDK publication and consumer frozen-lock
+updates remain separate steps. This bounded adapter covers UNS history; it
+does not create SQL, broker or arbitrary external-resource permissions.
+
 ## 3.0.46 - Verified retained-store copy and recovery
 
 When crossing `<3.0.46` to `>=3.0.46`, existing rename and unbound consumers

package/README.md

@@ -8,10 +8,10 @@ Note: Apps built with uns-kit are intended to be managed by the **UNS OpenHub co
 
 | Package | Description |
 | --- | --- |
-| [`@uns-kit/core`](https://github.com/uns-openhub/uns-kit/tree/main/packages/uns-core) | Base runtime (UnsProxyProcess, MQTT helpers, config tooling, gRPC gateway). |
-| [`@uns-kit/api`](https://github.com/uns-openhub/uns-kit/tree/main/packages/uns-api) | Express plugin — HTTP endpoints, JWT/JWKS auth, Swagger, UNS metadata. |
-| [`@uns-kit/cron`](https://github.com/uns-openhub/uns-kit/tree/main/packages/uns-cron) | Cron-driven scheduler that emits UNS events on a fixed cadence. |
-| [`@uns-kit/cli`](https://github.com/uns-openhub/uns-kit/tree/main/packages/uns-cli) | CLI for scaffolding new UNS applications. |
+| [`@uns-kit/core`](https://github.com/uns-openhub/uns-kit/tree/master/packages/uns-core) | Base runtime (UnsProxyProcess, MQTT helpers, config tooling, gRPC gateway). |
+| [`@uns-kit/api`](https://github.com/uns-openhub/uns-kit/tree/master/packages/uns-api) | Express plugin — HTTP endpoints, JWT/JWKS auth, Swagger, UNS metadata. |
+| [`@uns-kit/cron`](https://github.com/uns-openhub/uns-kit/tree/master/packages/uns-cron) | Cron-driven scheduler that emits UNS events on a fixed cadence. |
+| [`@uns-kit/cli`](https://github.com/uns-openhub/uns-kit/tree/master/packages/uns-cli) | CLI for scaffolding new UNS applications. |
 
 ## Installation
 
@@ -95,47 +95,49 @@ const cron = await proc.createCrontabProxy("*/5 * * * *", { event: "tick" });
 
 ## Datahub client (last value + history)
 
-`UnsClient` provides a minimal REST client for the UNS OpenHub API, including batch last-value, single-topic catch-all history, and batch range endpoints. Prefer a long-lived service token if available; you can pass it directly and skip username/password auth.
+`UnsClient` provides a minimal REST client for the UNS OpenHub API, including batch last-value, single-topic catch-all history, and batch range endpoints. Use `ServiceTokenProvider` for Controller-managed services so credential rotation is picked up on every request. Review the service's declared scopes and resource paths before Start; never cache a managed token at application startup.
 
-```ts
-import { UnsClient } from "@uns-kit/core";
-import { ConfigFile } from "@uns-kit/core";
+Read the [source Service access walkthrough](https://github.com/uns-openhub/uns-kit/blob/master/docs/catalog-publication-access.md)
+or bundled `@uns-kit/core/runtime/service-access-guide.md`. Complete background-reader
+and catalog projects ship in `dist/runtime/service-access-examples/`. A background
+reader uses its service identity only; a catalog operation also carries its caller's
+identity. These API permissions do not create MQTT ACLs or SQL grants.
 
-const config = await ConfigFile.loadConfig();
+```ts
+import { ServiceTokenProvider, UnsClient } from "@uns-kit/core";
 
-const client = new UnsClient("https://datahub.example.com", {
-  token: process.env.UNS_SERVICE_TOKEN ?? config.uns.token,
-});
+const baseUrl = process.env.UNS_CONTROLLER_PUBLIC_BASE;
+if (!baseUrl) throw new Error("Set the trusted Controller base URL.");
+const client = new UnsClient(baseUrl, { tokenProvider: new ServiceTokenProvider() });
 
 const values = await client.lastValue([
-  "raw/data/line-1/motor/main/temperature",
-  "raw/data/line-1/motor/main/status",
+  "example/plant/line-1/motor/main/temperature",
+  "example/plant/line-1/motor/main/status",
 ]);
-console.log(values);
+// Process the values without logging private records.
 
-const data = await client.getAttributeData("sij/acroni/vv/hrm-furnace/equipment/pusher/output-quantity", {
+const data = await client.getAttributeData("example/plant/line-1/motor/main/temperature", {
   from: "2026-05-07T11:17:01.157Z",
   to: "2026-05-07T11:22:01.157Z",
-  table: "uns_sij_hrm_furnace_data",
   aggregate: "last",
   dedupe: false,
 });
-console.log(data?.toRecords());
+const records = data?.toRecords();
 
 const customData = await client.getData("/projects/project-name/path-to-data/data", {
   fromDate: "20260325",
 });
-console.log(await customData.json());
+const customResult = await customData.json();
 
 const batchHistory = await client.history([
-  "sij/acroni/vv/hrm-furnace/equipment/zone-1/temperature",
-  "sij/acroni/vv/hrm-furnace/equipment/zone-2/temperature",
+  "example/plant/line-1/motor/main/temperature",
+  "example/plant/line-1/motor/main/status",
 ], {
   from: "2026-04-09T06:00:00Z",
   to: "2026-04-09T07:00:00Z",
   limit: 500,
 });
-console.log(batchHistory?.byTopic);
+// Process the bounded batch result.
 ```
 
 ## Sub-Asset Publishing

package/dist/runtime/catalog-publication-client.d.ts

@@ -0,0 +1,21 @@
+import { type AccessTokenProvider } from "../tools/auth/service-token-provider.js";
+import { type CatalogPublicationManifest } from "./catalog-publication.js";
+/** No caller-token fallback and no arbitrary source URL or topic. */
+export declare class CatalogPublicationClient {
+    private readonly options;
+    constructor(options: {
+        controllerBase: string;
+        rttNode: string;
+        version: string;
+        instanceId: string;
+        manifest: CatalogPublicationManifest;
+        tokenProvider?: AccessTokenProvider;
+        fetch?: typeof fetch;
+    });
+    private call;
+    execute<T>(operationId: string, input: Record<string, unknown>, callerToken: string, transform: (context: {
+        signal: AbortSignal;
+        history: (sourceId: string) => Promise<unknown>;
+    }) => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=catalog-publication-client.d.ts.map

package/dist/runtime/catalog-publication-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-publication-client.d.ts","sourceRoot":"","sources":["../../src/runtime/catalog-publication-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAwB,MAAM,yCAAyC,CAAC;AACzG,OAAO,EAIL,KAAK,0BAA0B,EAIhC,MAAM,0BAA0B,CAAC;AAElC,qEAAqE;AACrE,qBAAa,wBAAwB;IAEjC,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE;QACxB,cAAc,EAAE,MAAM,CAAC;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,0BAA0B,CAAC;QACrC,aAAa,CAAC,EAAE,mBAAmB,CAAC;QACpC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;KACtB;YAEW,IAAI;IAmDZ,OAAO,CAAC,CAAC,EACb,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3G,OAAO,CAAC,CAAC,CAAC;CA6Bd"}

package/dist/runtime/catalog-publication-client.js

@@ -0,0 +1,92 @@
+import { ServiceTokenProvider } from "../tools/auth/service-token-provider.js";
+import { CatalogAccessError, assertCatalogRequest, assertCatalogResponse, catalogAccessDigest, } from "./catalog-publication.js";
+/** No caller-token fallback and no arbitrary source URL or topic. */
+export class CatalogPublicationClient {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async call(action, operation, input, callerToken, sourceId, signal) {
+        assertCatalogRequest(operation, input);
+        const token = await (this.options.tokenProvider ?? new ServiceTokenProvider()).getAccessToken();
+        if (!token)
+            throw Error("Catalog service credential unavailable.");
+        const body = {
+            rttNode: this.options.rttNode,
+            version: this.options.version,
+            instanceId: this.options.instanceId,
+            operationId: operation.id,
+            manifestDigest: catalogAccessDigest(this.options.manifest),
+            input,
+            callerToken,
+        };
+        const response = await (this.options.fetch ?? fetch)(new URL(`/api/catalog-publications/${action}`, this.options.controllerBase), {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+            body: JSON.stringify({ ...body, ...(sourceId ? { sourceId } : {}) }),
+            signal: signal ?? AbortSignal.timeout(operation.timeoutMs),
+            redirect: "error",
+        });
+        if (!response.ok)
+            throw new CatalogAccessError("catalog_access_denied", [400, 401, 403, 409, 429].includes(response.status) ? response.status : 503);
+        if (!response.body)
+            throw new CatalogAccessError("catalog_source_unavailable", 503);
+        const reader = response.body.getReader();
+        let size = 0, text = "";
+        const decoder = new TextDecoder();
+        try {
+            while (true) {
+                const r = await reader.read();
+                if (r.done)
+                    break;
+                size += r.value.byteLength;
+                if (size > 1048576) {
+                    await reader.cancel();
+                    throw new CatalogAccessError("catalog_source_budget", 503);
+                }
+                text += decoder.decode(r.value, { stream: true });
+            }
+            text += decoder.decode();
+            return JSON.parse(text);
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    async execute(operationId, input, callerToken, transform) {
+        const operation = this.options.manifest.operations.find((op) => op.id === operationId);
+        if (!operation)
+            throw Error("Catalog operation not declared.");
+        const signal = AbortSignal.timeout(operation.timeoutMs);
+        await this.call("authorize", operation, input, callerToken, undefined, signal);
+        const work = transform({
+            signal,
+            history: async (sourceId) => {
+                if (!operation.sources.some((source) => source.id === sourceId))
+                    throw Error("Catalog source not declared.");
+                return this.call("history", operation, input, callerToken, sourceId, signal);
+            },
+        });
+        let stop;
+        const deadline = new Promise((_resolve, reject) => {
+            stop = () => reject(new CatalogAccessError("catalog_execution_timeout", 504));
+            if (signal.aborted)
+                stop();
+            else
+                signal.addEventListener("abort", stop, { once: true });
+        });
+        let result;
+        try {
+            result = await Promise.race([work, deadline]);
+        }
+        finally {
+            if (stop)
+                signal.removeEventListener("abort", stop);
+        }
+        // Recheck after asynchronous processing, including a cached application result.
+        await this.call("authorize", operation, input, callerToken, undefined, signal);
+        assertCatalogResponse(operation, result);
+        return result;
+    }
+}
+//# sourceMappingURL=catalog-publication-client.js.map

package/dist/runtime/catalog-publication-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-publication-client.js","sourceRoot":"","sources":["../../src/runtime/catalog-publication-client.ts"],"names":[],"mappings":"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","sourcesContent":["import { type AccessTokenProvider, ServiceTokenProvider } from \"../tools/auth/service-token-provider.js\";\nimport {\n  CatalogAccessError,\n  type CatalogInvocation,\n  type CatalogOperation,\n  type CatalogPublicationManifest,\n  assertCatalogRequest,\n  assertCatalogResponse,\n  catalogAccessDigest,\n} from \"./catalog-publication.js\";\n\n/** No caller-token fallback and no arbitrary source URL or topic. */\nexport class CatalogPublicationClient {\n  constructor(\n    private readonly options: {\n      controllerBase: string;\n      rttNode: string;\n      version: string;\n      instanceId: string;\n      manifest: CatalogPublicationManifest;\n      tokenProvider?: AccessTokenProvider;\n      fetch?: typeof fetch;\n    },\n  ) {}\n  private async call(\n    action: \"authorize\" | \"history\",\n    operation: CatalogOperation,\n    input: Record<string, unknown>,\n    callerToken: string,\n    sourceId?: string,\n    signal?: AbortSignal,\n  ): Promise<unknown> {\n    assertCatalogRequest(operation, input);\n    const token = await (this.options.tokenProvider ?? new ServiceTokenProvider()).getAccessToken();\n    if (!token) throw Error(\"Catalog service credential unavailable.\");\n    const body: CatalogInvocation = {\n      rttNode: this.options.rttNode,\n      version: this.options.version,\n      instanceId: this.options.instanceId,\n      operationId: operation.id,\n      manifestDigest: catalogAccessDigest(this.options.manifest),\n      input,\n      callerToken,\n    };\n    const response = await (this.options.fetch ?? fetch)(new URL(`/api/catalog-publications/${action}`, this.options.controllerBase), {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\", Authorization: `Bearer ${token}` },\n      body: JSON.stringify({ ...body, ...(sourceId ? { sourceId } : {}) }),\n      signal: signal ?? AbortSignal.timeout(operation.timeoutMs),\n      redirect: \"error\",\n    });\n    if (!response.ok)\n      throw new CatalogAccessError(\"catalog_access_denied\", [400, 401, 403, 409, 429].includes(response.status) ? response.status : 503);\n    if (!response.body) throw new CatalogAccessError(\"catalog_source_unavailable\", 503);\n    const reader = response.body.getReader();\n    let size = 0,\n      text = \"\";\n    const decoder = new TextDecoder();\n    try {\n      while (true) {\n        const r = await reader.read();\n        if (r.done) break;\n        size += r.value.byteLength;\n        if (size > 1048576) {\n          await reader.cancel();\n          throw new CatalogAccessError(\"catalog_source_budget\", 503);\n        }\n        text += decoder.decode(r.value, { stream: true });\n      }\n      text += decoder.decode();\n      return JSON.parse(text);\n    } finally {\n      reader.releaseLock();\n    }\n  }\n  async execute<T>(\n    operationId: string,\n    input: Record<string, unknown>,\n    callerToken: string,\n    transform: (context: { signal: AbortSignal; history: (sourceId: string) => Promise<unknown> }) => Promise<T>,\n  ): Promise<T> {\n    const operation = this.options.manifest.operations.find((op) => op.id === operationId);\n    if (!operation) throw Error(\"Catalog operation not declared.\");\n    const signal = AbortSignal.timeout(operation.timeoutMs);\n    await this.call(\"authorize\", operation, input, callerToken, undefined, signal);\n    const work = transform({\n      signal,\n      history: async (sourceId) => {\n        if (!operation.sources.some((source) => source.id === sourceId)) throw Error(\"Catalog source not declared.\");\n        return this.call(\"history\", operation, input, callerToken, sourceId, signal);\n      },\n    });\n    let stop: (() => void) | undefined;\n    const deadline = new Promise<never>((_resolve, reject) => {\n      stop = () => reject(new CatalogAccessError(\"catalog_execution_timeout\", 504));\n      if (signal.aborted) stop();\n      else signal.addEventListener(\"abort\", stop, { once: true });\n    });\n    let result: T;\n    try {\n      result = await Promise.race([work, deadline]);\n    } finally {\n      if (stop) signal.removeEventListener(\"abort\", stop);\n    }\n    // Recheck after asynchronous processing, including a cached application result.\n    await this.call(\"authorize\", operation, input, callerToken, undefined, signal);\n    assertCatalogResponse(operation, result);\n    return result;\n  }\n}\n"]}

package/dist/runtime/catalog-publication.d.ts

@@ -0,0 +1,97 @@
+import { z } from "zod";
+export declare const CATALOG_PUBLICATION_PROTOCOL = 1;
+export declare const CATALOG_SOURCE_SCOPE = "catalog:sources:read";
+export declare const CATALOG_MANIFEST_FIELD = "catalogAccess";
+export declare class CatalogAccessError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, status?: number);
+}
+declare const historySource: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"history">;
+    topic: z.ZodString;
+    maxWindowMs: z.ZodDefault<z.ZodNumber>;
+    maxRows: z.ZodDefault<z.ZodNumber>;
+    fromParameter: z.ZodDefault<z.ZodString>;
+    toParameter: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+declare const operation: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    method: z.ZodLiteral<"GET">;
+    path: z.ZodString;
+    mode: z.ZodEnum<{
+        caller: "caller";
+        "approved-service": "approved-service";
+    }>;
+    requestSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    responseSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    sources: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"history">;
+        topic: z.ZodString;
+        maxWindowMs: z.ZodDefault<z.ZodNumber>;
+        maxRows: z.ZodDefault<z.ZodNumber>;
+        fromParameter: z.ZodDefault<z.ZodString>;
+        toParameter: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    maxResponseBytes: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+declare const manifest: z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    operations: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        method: z.ZodLiteral<"GET">;
+        path: z.ZodString;
+        mode: z.ZodEnum<{
+            caller: "caller";
+            "approved-service": "approved-service";
+        }>;
+        requestSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        responseSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        sources: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodLiteral<"history">;
+            topic: z.ZodString;
+            maxWindowMs: z.ZodDefault<z.ZodNumber>;
+            maxRows: z.ZodDefault<z.ZodNumber>;
+            fromParameter: z.ZodDefault<z.ZodString>;
+            toParameter: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        maxResponseBytes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CatalogOperationInput = z.input<typeof operation>;
+export type CatalogOperation = z.output<typeof operation>;
+export type CatalogHistorySource = z.output<typeof historySource>;
+export type CatalogPublicationManifest = z.output<typeof manifest>;
+export declare const catalogAccessDigest: (value: unknown) => string;
+/** Catalog routes use the same UNS resource path as SDK endpoint guards. */
+export declare const catalogOperationResource: (path: string) => string;
+/** Inspection consumes bounded JSON data, never application JavaScript. */
+export declare function parseCatalogPublicationManifest(input: unknown): CatalogPublicationManifest;
+export declare function assertCatalogRequest(op: CatalogOperation, input: unknown): void;
+export declare function assertCatalogResponse(op: CatalogOperation, value: unknown): void;
+export declare function catalogHistoryQuery(source: CatalogHistorySource, input: unknown): {
+    topics: string[];
+    from: string;
+    to: string;
+    limit: number;
+    dedupe: false;
+};
+export declare const catalogInvocationSchema: z.ZodObject<{
+    rttNode: z.ZodString;
+    version: z.ZodString;
+    instanceId: z.ZodString;
+    operationId: z.ZodString;
+    manifestDigest: z.ZodString;
+    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    callerToken: z.ZodString;
+}, z.core.$strict>;
+export type CatalogInvocation = z.infer<typeof catalogInvocationSchema>;
+export {};
+//# sourceMappingURL=catalog-publication.d.ts.map

package/dist/runtime/catalog-publication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-publication.d.ts","sourceRoot":"","sources":["../../src/runtime/catalog-publication.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAC9C,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAC3D,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AAkBtD,qBAAa,kBAAmB,SAAQ,KAAK;aAEzB,IAAI,EAAE,MAAM;aACZ,MAAM;gBADN,IAAI,EAAE,MAAM,EACZ,MAAM,SAAM;CAI/B;AACD,QAAA,MAAM,aAAa;;;;;;;;kBAeR,CAAC;AACZ,QAAA,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;kBAaJ,CAAC;AACZ,QAAA,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;kBAA+F,CAAC;AAC9G,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAC1D,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAClE,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC;AACnE,eAAO,MAAM,mBAAmB,4BAAiB,CAAC;AAClD,4EAA4E;AAC5E,eAAO,MAAM,wBAAwB,GAAI,MAAM,MAAM,KAAG,MAAsC,CAAC;AAE/F,2EAA2E;AAC3E,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,CAmC1F;AAiDD,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAI/E;AACD,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAEhF;AACD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,OAAO,GACb;IACD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,KAAK,CAAC;CACf,CAWA;AAED,eAAO,MAAM,uBAAuB;;;;;;;;kBAUzB,CAAC;AACZ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/runtime/catalog-publication.js

@@ -0,0 +1,185 @@
+import { z } from "zod";
+import { operatorDigest, operatorJson, operatorRequestSchema } from "./operator-api.js";
+export const CATALOG_PUBLICATION_PROTOCOL = 1;
+export const CATALOG_SOURCE_SCOPE = "catalog:sources:read";
+export const CATALOG_MANIFEST_FIELD = "catalogAccess";
+const id = z
+    .string()
+    .min(1)
+    .max(120)
+    .regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/);
+const topic = z
+    .string()
+    .min(1)
+    .max(512)
+    .regex(/^[A-Za-z0-9-]+(?:\/[A-Za-z0-9-]+)*$/)
+    .refine((value) => !value.split("/").some((part) => part === "." || part === ".."));
+const localPath = z
+    .string()
+    .min(1)
+    .max(1024)
+    .regex(/^\/api\/[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_.-]+)*$/)
+    .refine((value) => !value.split("/").some((part) => part === "." || part === ".."));
+export class CatalogAccessError extends Error {
+    code;
+    status;
+    constructor(code, status = 400) {
+        super(code);
+        this.code = code;
+        this.status = status;
+    }
+}
+const historySource = z
+    .object({
+    id,
+    kind: z.literal("history"),
+    topic,
+    maxWindowMs: z
+        .number()
+        .int()
+        .min(1000)
+        .max(31 * 86400000)
+        .default(7 * 86400000),
+    maxRows: z.number().int().min(1).max(27000).default(1000),
+    fromParameter: id.default("from"),
+    toParameter: id.default("to"),
+})
+    .strict();
+const operation = z
+    .object({
+    id,
+    title: z.string().min(1).max(160),
+    method: z.literal("GET"),
+    path: localPath,
+    mode: z.enum(["caller", "approved-service"]),
+    requestSchema: z.record(z.string(), z.unknown()),
+    responseSchema: z.record(z.string(), z.unknown()),
+    sources: z.array(historySource).min(1).max(16),
+    timeoutMs: z.number().int().min(500).max(30000).default(10000),
+    maxResponseBytes: z.number().int().min(256).max(1048576).default(262144),
+})
+    .strict();
+const manifest = z.object({ protocol: z.literal(1), operations: z.array(operation).min(1).max(32) }).strict();
+export const catalogAccessDigest = operatorDigest;
+/** Catalog routes use the same UNS resource path as SDK endpoint guards. */
+export const catalogOperationResource = (path) => path.replace(/^\/api\//, "");
+/** Inspection consumes bounded JSON data, never application JavaScript. */
+export function parseCatalogPublicationManifest(input) {
+    try {
+        operatorJson(input);
+        const parsed = manifest.parse(input), ids = new Set(), paths = new Set();
+        for (const op of parsed.operations) {
+            if (ids.has(op.id) || paths.has(op.path))
+                throw Error("duplicate operation");
+            ids.add(op.id);
+            paths.add(op.path);
+            op.requestSchema = catalogSchema(op.requestSchema);
+            op.responseSchema = catalogSchema(op.responseSchema);
+            if (op.requestSchema["type"] !== "object")
+                throw Error("request must be an object");
+            if (Object.values(op.requestSchema["properties"] ?? {}).some((p) => p["type"] !== "string"))
+                throw Error("GET parameters must be strings");
+            const sources = new Set();
+            for (const source of op.sources) {
+                if (sources.has(source.id) || source.fromParameter === source.toParameter)
+                    throw Error("source binding");
+                sources.add(source.id);
+                const properties = op.requestSchema["properties"];
+                for (const key of [source.fromParameter, source.toParameter]) {
+                    const parameter = properties?.[key];
+                    if (parameter?.["type"] !== "string" ||
+                        parameter["format"] !== "date-time" ||
+                        !op.requestSchema["required"]?.includes(key))
+                        throw Error("time parameter binding");
+                }
+            }
+        }
+        return parsed;
+    }
+    catch {
+        throw new CatalogAccessError("catalog_manifest_invalid");
+    }
+}
+function catalogSchema(value) {
+    const schema = operatorRequestSchema(value);
+    const visit = (node) => {
+        if (!["object", "array", "string", "integer", "number", "boolean", "null"].includes(String(node["type"])) ||
+            ["oneOf", "anyOf", "allOf", "default"].some((key) => key in node))
+            throw Error("unsupported catalog schema");
+        if (node["properties"])
+            for (const child of Object.values(node["properties"]))
+                visit(child);
+        if (node["items"])
+            visit(node["items"]);
+    };
+    visit(schema);
+    return schema;
+}
+/** Zod's JSON Schema importer limits date-time to UTC. JSON Schema permits
+ * explicit offsets. Check these formats separately without altering input. */
+function offsetSchema(schema, value) {
+    const copy = { ...schema };
+    if (copy["format"] === "date-time") {
+        if (value !== undefined && !z.iso.datetime({ offset: true }).safeParse(value).success)
+            throw Error("date-time");
+        delete copy["format"];
+    }
+    if (copy["properties"])
+        copy["properties"] = Object.fromEntries(Object.entries(copy["properties"]).map(([key, child]) => [
+            key,
+            offsetSchema(child, value && typeof value === "object" ? value[key] : undefined),
+        ]));
+    if (copy["items"]) {
+        const child = copy["items"];
+        if (Array.isArray(value))
+            for (const item of value)
+                offsetSchema(child, item);
+        copy["items"] = offsetSchema(child, undefined);
+    }
+    return copy;
+}
+function assertSchema(schema, value, code, maxBytes) {
+    try {
+        const json = JSON.stringify(value);
+        if (json === undefined || Buffer.byteLength(json, "utf8") > maxBytes)
+            throw Error("size");
+        // fromJSONSchema strips unknown keys by default, so validate the unchanged
+        // value against a strict schema rather than returning parsed/transformed data.
+        if (!z.fromJSONSchema(offsetSchema(schema, value)).safeParse(value).success)
+            throw Error("schema");
+    }
+    catch {
+        throw new CatalogAccessError(code, code === "catalog_response_invalid" ? 502 : 400);
+    }
+}
+export function assertCatalogRequest(op, input) {
+    operatorJson(input);
+    assertSchema(op.requestSchema, input, "catalog_request_invalid", 65536);
+    for (const source of op.sources)
+        catalogHistoryQuery(source, input);
+}
+export function assertCatalogResponse(op, value) {
+    assertSchema(op.responseSchema, value, "catalog_response_invalid", op.maxResponseBytes);
+}
+export function catalogHistoryQuery(source, input) {
+    const values = input;
+    const from = values?.[source.fromParameter], to = values?.[source.toParameter];
+    if (!z.iso.datetime({ offset: true }).safeParse(from).success || !z.iso.datetime({ offset: true }).safeParse(to).success)
+        throw new CatalogAccessError("catalog_window_invalid");
+    const start = Date.parse(from), end = Date.parse(to);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || start > end || end - start > source.maxWindowMs)
+        throw new CatalogAccessError("catalog_window_invalid");
+    return { topics: [source.topic], from: new Date(start).toISOString(), to: new Date(end).toISOString(), limit: source.maxRows, dedupe: false };
+}
+export const catalogInvocationSchema = z
+    .object({
+    rttNode: id,
+    version: id,
+    instanceId: id,
+    operationId: id,
+    manifestDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    input: z.record(z.string(), z.unknown()),
+    callerToken: z.string().min(1).max(16384),
+})
+    .strict();
+//# sourceMappingURL=catalog-publication.js.map

package/dist/runtime/catalog-publication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-publication.js","sourceRoot":"","sources":["../../src/runtime/catalog-publication.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\n\nimport { operatorDigest, operatorJson, operatorRequestSchema } from \"./operator-api.js\";\n\nexport const CATALOG_PUBLICATION_PROTOCOL = 1;\nexport const CATALOG_SOURCE_SCOPE = \"catalog:sources:read\";\nexport const CATALOG_MANIFEST_FIELD = \"catalogAccess\";\nconst id = z\n  .string()\n  .min(1)\n  .max(120)\n  .regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/);\nconst topic = z\n  .string()\n  .min(1)\n  .max(512)\n  .regex(/^[A-Za-z0-9-]+(?:\\/[A-Za-z0-9-]+)*$/)\n  .refine((value) => !value.split(\"/\").some((part) => part === \".\" || part === \"..\"));\nconst localPath = z\n  .string()\n  .min(1)\n  .max(1024)\n  .regex(/^\\/api\\/[A-Za-z0-9_-]+(?:\\/[A-Za-z0-9_.-]+)*$/)\n  .refine((value) => !value.split(\"/\").some((part) => part === \".\" || part === \"..\"));\nexport class CatalogAccessError extends Error {\n  constructor(\n    public readonly code: string,\n    public readonly status = 400,\n  ) {\n    super(code);\n  }\n}\nconst historySource = z\n  .object({\n    id,\n    kind: z.literal(\"history\"),\n    topic,\n    maxWindowMs: z\n      .number()\n      .int()\n      .min(1000)\n      .max(31 * 86400000)\n      .default(7 * 86400000),\n    maxRows: z.number().int().min(1).max(27000).default(1000),\n    fromParameter: id.default(\"from\"),\n    toParameter: id.default(\"to\"),\n  })\n  .strict();\nconst operation = z\n  .object({\n    id,\n    title: z.string().min(1).max(160),\n    method: z.literal(\"GET\"),\n    path: localPath,\n    mode: z.enum([\"caller\", \"approved-service\"]),\n    requestSchema: z.record(z.string(), z.unknown()),\n    responseSchema: z.record(z.string(), z.unknown()),\n    sources: z.array(historySource).min(1).max(16),\n    timeoutMs: z.number().int().min(500).max(30000).default(10000),\n    maxResponseBytes: z.number().int().min(256).max(1048576).default(262144),\n  })\n  .strict();\nconst manifest = z.object({ protocol: z.literal(1), operations: z.array(operation).min(1).max(32) }).strict();\nexport type CatalogOperationInput = z.input<typeof operation>;\nexport type CatalogOperation = z.output<typeof operation>;\nexport type CatalogHistorySource = z.output<typeof historySource>;\nexport type CatalogPublicationManifest = z.output<typeof manifest>;\nexport const catalogAccessDigest = operatorDigest;\n/** Catalog routes use the same UNS resource path as SDK endpoint guards. */\nexport const catalogOperationResource = (path: string): string => path.replace(/^\\/api\\//, \"\");\n\n/** Inspection consumes bounded JSON data, never application JavaScript. */\nexport function parseCatalogPublicationManifest(input: unknown): CatalogPublicationManifest {\n  try {\n    operatorJson(input);\n    const parsed = manifest.parse(input),\n      ids = new Set<string>(),\n      paths = new Set<string>();\n    for (const op of parsed.operations) {\n      if (ids.has(op.id) || paths.has(op.path)) throw Error(\"duplicate operation\");\n      ids.add(op.id);\n      paths.add(op.path);\n      op.requestSchema = catalogSchema(op.requestSchema);\n      op.responseSchema = catalogSchema(op.responseSchema);\n      if (op.requestSchema[\"type\"] !== \"object\") throw Error(\"request must be an object\");\n      if (Object.values((op.requestSchema[\"properties\"] as Record<string, Record<string, unknown>>) ?? {}).some((p) => p[\"type\"] !== \"string\"))\n        throw Error(\"GET parameters must be strings\");\n      const sources = new Set<string>();\n      for (const source of op.sources) {\n        if (sources.has(source.id) || source.fromParameter === source.toParameter) throw Error(\"source binding\");\n        sources.add(source.id);\n        const properties = op.requestSchema[\"properties\"] as Record<string, unknown> | undefined;\n        for (const key of [source.fromParameter, source.toParameter]) {\n          const parameter = properties?.[key] as Record<string, unknown> | undefined;\n          if (\n            parameter?.[\"type\"] !== \"string\" ||\n            parameter[\"format\"] !== \"date-time\" ||\n            !(op.requestSchema[\"required\"] as string[] | undefined)?.includes(key)\n          )\n            throw Error(\"time parameter binding\");\n        }\n      }\n    }\n    return parsed;\n  } catch {\n    throw new CatalogAccessError(\"catalog_manifest_invalid\");\n  }\n}\n\nfunction catalogSchema(value: unknown): Record<string, unknown> {\n  const schema = operatorRequestSchema(value);\n  const visit = (node: Record<string, unknown>): void => {\n    if (\n      ![\"object\", \"array\", \"string\", \"integer\", \"number\", \"boolean\", \"null\"].includes(String(node[\"type\"])) ||\n      [\"oneOf\", \"anyOf\", \"allOf\", \"default\"].some((key) => key in node)\n    )\n      throw Error(\"unsupported catalog schema\");\n    if (node[\"properties\"]) for (const child of Object.values(node[\"properties\"] as Record<string, Record<string, unknown>>)) visit(child);\n    if (node[\"items\"]) visit(node[\"items\"] as Record<string, unknown>);\n  };\n  visit(schema);\n  return schema;\n}\n/** Zod's JSON Schema importer limits date-time to UTC. JSON Schema permits\n * explicit offsets. Check these formats separately without altering input. */\nfunction offsetSchema(schema: Record<string, unknown>, value: unknown): Record<string, unknown> {\n  const copy = { ...schema };\n  if (copy[\"format\"] === \"date-time\") {\n    if (value !== undefined && !z.iso.datetime({ offset: true }).safeParse(value).success) throw Error(\"date-time\");\n    delete copy[\"format\"];\n  }\n  if (copy[\"properties\"])\n    copy[\"properties\"] = Object.fromEntries(\n      Object.entries(copy[\"properties\"] as Record<string, Record<string, unknown>>).map(([key, child]) => [\n        key,\n        offsetSchema(child, value && typeof value === \"object\" ? (value as Record<string, unknown>)[key] : undefined),\n      ]),\n    );\n  if (copy[\"items\"]) {\n    const child = copy[\"items\"] as Record<string, unknown>;\n    if (Array.isArray(value)) for (const item of value) offsetSchema(child, item);\n    copy[\"items\"] = offsetSchema(child, undefined);\n  }\n  return copy;\n}\nfunction assertSchema(schema: Record<string, unknown>, value: unknown, code: string, maxBytes: number): void {\n  try {\n    const json = JSON.stringify(value);\n    if (json === undefined || Buffer.byteLength(json, \"utf8\") > maxBytes) throw Error(\"size\");\n    // fromJSONSchema strips unknown keys by default, so validate the unchanged\n    // value against a strict schema rather than returning parsed/transformed data.\n    if (!z.fromJSONSchema(offsetSchema(schema, value) as never).safeParse(value).success) throw Error(\"schema\");\n  } catch {\n    throw new CatalogAccessError(code, code === \"catalog_response_invalid\" ? 502 : 400);\n  }\n}\nexport function assertCatalogRequest(op: CatalogOperation, input: unknown): void {\n  operatorJson(input);\n  assertSchema(op.requestSchema, input, \"catalog_request_invalid\", 65536);\n  for (const source of op.sources) catalogHistoryQuery(source, input);\n}\nexport function assertCatalogResponse(op: CatalogOperation, value: unknown): void {\n  assertSchema(op.responseSchema, value, \"catalog_response_invalid\", op.maxResponseBytes);\n}\nexport function catalogHistoryQuery(\n  source: CatalogHistorySource,\n  input: unknown,\n): {\n  topics: string[];\n  from: string;\n  to: string;\n  limit: number;\n  dedupe: false;\n} {\n  const values = input as Record<string, unknown> | null;\n  const from = values?.[source.fromParameter],\n    to = values?.[source.toParameter];\n  if (!z.iso.datetime({ offset: true }).safeParse(from).success || !z.iso.datetime({ offset: true }).safeParse(to).success)\n    throw new CatalogAccessError(\"catalog_window_invalid\");\n  const start = Date.parse(from as string),\n    end = Date.parse(to as string);\n  if (!Number.isFinite(start) || !Number.isFinite(end) || start > end || end - start > source.maxWindowMs)\n    throw new CatalogAccessError(\"catalog_window_invalid\");\n  return { topics: [source.topic], from: new Date(start).toISOString(), to: new Date(end).toISOString(), limit: source.maxRows, dedupe: false };\n}\n\nexport const catalogInvocationSchema = z\n  .object({\n    rttNode: id,\n    version: id,\n    instanceId: id,\n    operationId: id,\n    manifestDigest: z.string().regex(/^[a-f0-9]{64}$/),\n    input: z.record(z.string(), z.unknown()),\n    callerToken: z.string().min(1).max(16384),\n  })\n  .strict();\nexport type CatalogInvocation = z.infer<typeof catalogInvocationSchema>;\n"]}

package/dist/runtime/service-access-examples/README.md

@@ -0,0 +1,20 @@
+# Service access examples
+
+- `background-reader/`: no API or catalog; a reviewed workload token reads one UNS history source.
+- `catalog-summary/`: a catalog-only caller requests a bounded derived count; the workload has no direct source permission.
+
+Each folder is an independent, credential-free Node.js package. Copy one folder
+to a new project, install dependencies and build. Deploy/review/start with a
+Controller supporting common Service access (verified with Controller 2.2.95).
+The [walkthrough](https://github.com/uns-openhub/uns-kit/blob/master/docs/catalog-publication-access.md)
+explains what the developer, administrator, Controller, SDK and caller each own.
+
+The examples are also shipped in `@uns-kit/core/dist/runtime/service-access-examples/`.
+No real broker, database, user or production endpoint is supplied. Configure your
+own local test resources. These files create no identities, grants or MQTT ACLs.
+
+Maintainers: run `pnpm run ts:build` then `pnpm run test:service-access-examples`.
+The verifier packs the SDK, installs it in a temporary consumer, builds/packs both
+examples, and exercises their real handlers/token provider against a synthetic
+loopback API. This checks imports, shipped files, token rotation, denial and
+closed output, not real Controller policy, MQTT connectivity or cluster ownership.

package/dist/runtime/service-access-examples/background-reader/README.md

@@ -0,0 +1,25 @@
+# background-reader
+
+A complete Node.js 22+ example using published SDK APIs from 3.0.47 onward.
+Read the [Service access walkthrough](https://github.com/uns-openhub/uns-kit/blob/master/docs/catalog-publication-access.md) for the declaration, Controller review and acceptance steps.
+
+```sh
+pnpm install
+pnpm run build
+cp config-example.json config.json
+```
+
+The example configuration targets a local development broker/Controller. Select
+your own endpoints and secret references before deployment. The Controller owns
+instance configuration when deployed. `MQTT_USERNAME`/`MQTT_PASSWORD` concern broker
+ACLs only and grant no OpenHub API rights. Do not commit `config.json` or `.env`.
+
+Deploy the package, apply its exact-version Service access policy, and then Start.
+The Controller supplies managed identity/credential paths. Do not manufacture RTT
+launch variables or paste a human token into configuration.
+
+This worker has no API or catalog. It polls five minutes of history, at most
+100 rows, every 30 seconds while active. Provision the exact declared source in
+your own test environment; zero rows is a valid result. Its token can read that
+source, while another source must return 403. SIGINT/SIGTERM aborts the current
+request and stops polling before runtime cleanup.