@uns-kit/core 3.0.47 → 3.0.49

package/MIGRATIONS.md

@@ -9,6 +9,33 @@ 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.49 - Inline Service access package declarations
+
+Existing file declarations remain compatible; no permission is granted by this
+upgrade. New services may put the declaration object directly at
+`package.json.unsDatahub.serviceAccess`. Use `loadServiceAccessDeclaration` from
+`@uns-kit/core/runtime/service-access-package.js` for runtime reads, or the pure
+resolver/schema from `runtime/service-access.js` for host integrations. Both forms
+normalize to the same semantic digest. Do not declare both `serviceAccess` and
+historical `catalogAccess`.
+
+Inline metadata requires a Controller advertising `rttServiceAccessInline`;
+Controller 2.2.96 accepts only the file form. Keep the file form until the target
+Controller supports inline declarations. This patch does not implement the planned
+configuration-save approval UI or automatic installation grants. Administrator
+review, caller authorization, MQTT ACLs and rotating token use remain separate.
+Both complete examples now use inline metadata and require the matching host.
+
+## 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

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. Declare requirements in `package.json.unsDatahub.serviceAccess` (SDK 3.0.49+ and an inline-capable Controller), or retain the compatible JSON file reference. 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/service-access-examples/README.md

@@ -0,0 +1,21 @@
+# 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. The declarations are inline in package.json (SDK 3.0.49+). Deploy/review/start
+with a Controller advertising rttServiceAccessInline; Controller 2.2.96 requires
+the compatible file form instead.
+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,29 @@
+# background-reader
+
+A complete Node.js 22+ example using SDK APIs from 3.0.49 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.
+
+The access declaration is inline in package.json. This representation requires
+Controller capability `rttServiceAccessInline`; it is unsupported by 2.2.96.
+The SDK also accepts a package-relative JSON file reference for older hosts.

package/dist/runtime/service-access-examples/background-reader/build.mjs

@@ -0,0 +1,7 @@
+import { copyFile, mkdir, rm } from "node:fs/promises";
+
+await rm("dist", { recursive: true, force: true });
+await mkdir("dist");
+await copyFile("src/index.mjs", "dist/index.js");
+await copyFile("src/reader.mjs", "dist/reader.mjs");
+// service-access.json stays at the package root, as declared in package.json.

package/dist/runtime/service-access-examples/background-reader/config-example.json

@@ -0,0 +1,22 @@
+{
+  "infra": {
+    "host": "localhost"
+  },
+  "uns": {
+    "processName": "example-background-reader",
+    "instanceMode": "wait",
+    "handover": false
+  },
+  "mqtt": {
+    "username": {
+      "provider": "env",
+      "key": "MQTT_USERNAME",
+      "default": ""
+    },
+    "password": {
+      "provider": "env",
+      "key": "MQTT_PASSWORD",
+      "default": ""
+    }
+  }
+}

package/dist/runtime/service-access-examples/background-reader/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "example-background-reader",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "config-example.json"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@uns-kit/core": "^3.0.49"
+  },
+  "unsDatahub": {
+    "schemaVersion": 1,
+    "kind": "addon",
+    "controllerCompatibility": ">=2 <3",
+    "serviceAccess": {
+      "protocol": 1,
+      "permissions": {
+        "scopes": [
+          "read:uns"
+        ],
+        "accessRules": [
+          "example/background/line-1/equipment/main/temperature"
+        ]
+      }
+    }
+  }
+}

package/dist/runtime/service-access-examples/background-reader/src/index.mjs

@@ -0,0 +1,55 @@
+import { ConfigFile, UnsProxyProcess } from "@uns-kit/core";
+import { setTimeout as delay } from "node:timers/promises";
+
+import { readHistory } from "./reader.mjs";
+
+const config = await ConfigFile.loadConfig();
+const controllerBase = process.env.UNS_CONTROLLER_PUBLIC_BASE;
+if (!controllerBase) throw new Error("UNS_CONTROLLER_PUBLIC_BASE must name your Controller.");
+const stop = new AbortController();
+const runtime = new UnsProxyProcess(config.infra.host, {
+  processName: config.uns.processName,
+  username: config.mqtt?.username,
+  password: config.mqtt?.password,
+});
+let currentRead = Promise.resolve();
+let stopping;
+const shutdown = () =>
+  (stopping ??= (async () => {
+    stop.abort();
+    await currentRead.catch(() => {});
+    await runtime.shutdown();
+  })());
+for (const signal of ["SIGINT", "SIGTERM"])
+  process.once(signal, () => {
+    void shutdown().then(
+      () => process.exit(0),
+      () => {
+        process.exitCode = 1;
+      },
+    );
+  });
+try {
+  await runtime.prepareHandover(config.uns.instanceMode, config.uns.handover);
+  while (!stop.signal.aborted) {
+    if (runtime.isActive()) {
+      const to = new Date(),
+        from = new Date(to.getTime() - 5 * 60000);
+      try {
+        currentRead = readHistory(controllerBase, from.toISOString(), to.toISOString(), { signal: stop.signal });
+        const rows = await currentRead;
+        // Put application processing here. Never log bearer values or raw records.
+        console.info(`Read ${rows.length} samples.`);
+      } catch {
+        if (!stop.signal.aborted) console.warn("History read failed; check Service access and API availability.");
+      }
+    }
+    try {
+      await delay(30000, undefined, { signal: stop.signal });
+    } catch (error) {
+      if (!stop.signal.aborted) throw error;
+    }
+  }
+} finally {
+  await shutdown();
+}

package/dist/runtime/service-access-examples/background-reader/src/reader.mjs

@@ -0,0 +1,26 @@
+import { ServiceTokenProvider } from "@uns-kit/core/tools/auth/service-token-provider.js";
+import { loadServiceAccessDeclaration } from "@uns-kit/core/runtime/service-access-package.js";
+
+const declaration = await loadServiceAccessDeclaration(new URL("../package.json", import.meta.url));
+if (declaration?.permissions.scopes.length !== 1 || declaration.permissions.scopes[0] !== "read:uns" ||
+    declaration.permissions.accessRules.length !== 1 || /[+#]/.test(declaration.permissions.accessRules[0]))
+  throw new Error("This example requires one exact declared background source.");
+export const sourceTopic = declaration.permissions.accessRules[0];
+
+/** A background API read has a workload identity and no human caller token. */
+export async function readHistory(controllerBase, from, to, { tokenProvider = new ServiceTokenProvider(), fetch: request = fetch, signal } = {}) {
+  const token = await tokenProvider.getAccessToken();
+  if (!token) throw new Error("Service credential unavailable; review Service access.");
+  const response = await request(new URL("/api/catchall/batch/range", controllerBase), {
+    method: "POST",
+    redirect: "error",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+    body: JSON.stringify({ topics: [sourceTopic], from, to, limit: 100 }),
+    signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(10000)]) : AbortSignal.timeout(10000),
+  });
+  if (!response.ok) throw new Error(`UNS history returned HTTP ${response.status}; no credential fallback.`);
+  const result = await response.json();
+  const rows = result.results?.[0]?.data;
+  if (!Array.isArray(rows)) throw new Error("Unexpected history response.");
+  return rows;
+}

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

@@ -0,0 +1,30 @@
+# catalog-summary
+
+A complete Node.js 22+ example using SDK APIs from 3.0.49 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 service requires a managed Controller launch for signed catalog route
+publication. Its workload has no direct UNS access. Apply catalog:sources:read
+and approve the publication for the intended audience. Give a test reader access
+to the operation path, not the private source path. Execute a timezone-qualified
+window of at most one hour. Expect {count, hasMore}; raw source fields are excluded.
+A direct source request with the reader or service token must return 403.
+
+The access declaration is inline in package.json. This representation requires
+Controller capability `rttServiceAccessInline`; it is unsupported by 2.2.96.
+The SDK also accepts a package-relative JSON file reference for older hosts.

package/dist/runtime/service-access-examples/catalog-summary/build.mjs

@@ -0,0 +1,7 @@
+import { copyFile, mkdir, rm } from "node:fs/promises";
+
+await rm("dist", { recursive: true, force: true });
+await mkdir("dist");
+await copyFile("src/index.mjs", "dist/index.js");
+await copyFile("src/offer.mjs", "dist/offer.mjs");
+// The declaration lives in package.json, which npm always retains.

package/dist/runtime/service-access-examples/catalog-summary/config-example.json

@@ -0,0 +1,23 @@
+{
+  "infra": {
+    "host": "localhost"
+  },
+  "uns": {
+    "processName": "example-catalog-summary",
+    "instanceMode": "wait",
+    "handover": false,
+    "jwksWellKnownUrl": "http://localhost:3200/api/.well-known/jwks.json"
+  },
+  "mqtt": {
+    "username": {
+      "provider": "env",
+      "key": "MQTT_USERNAME",
+      "default": ""
+    },
+    "password": {
+      "provider": "env",
+      "key": "MQTT_PASSWORD",
+      "default": ""
+    }
+  }
+}

package/dist/runtime/service-access-examples/catalog-summary/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "example-catalog-summary",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "config-example.json"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@uns-kit/core": "^3.0.49",
+    "@uns-kit/api": "^3.0.49"
+  },
+  "unsDatahub": {
+    "schemaVersion": 1,
+    "kind": "addon",
+    "controllerCompatibility": ">=2 <3",
+    "serviceAccess": {
+      "protocol": 1,
+      "permissions": {
+        "scopes": [],
+        "accessRules": []
+      },
+      "publications": {
+        "protocol": 1,
+        "operations": [
+          {
+            "id": "sample-count",
+            "title": "Temperature sample count",
+            "method": "GET",
+            "path": "/api/example/public/line-1/equipment/dataset/sample-count/json",
+            "mode": "approved-service",
+            "requestSchema": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "from",
+                "to"
+              ],
+              "properties": {
+                "from": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "to": {
+                  "type": "string",
+                  "format": "date-time"
+                }
+              }
+            },
+            "responseSchema": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "count",
+                "hasMore"
+              ],
+              "properties": {
+                "count": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "hasMore": {
+                  "type": "boolean"
+                }
+              }
+            },
+            "sources": [
+              {
+                "id": "temperature",
+                "kind": "history",
+                "topic": "example/private/line-1/equipment/main/temperature",
+                "maxWindowMs": 3600000,
+                "maxRows": 1000
+              }
+            ],
+            "timeoutMs": 10000,
+            "maxResponseBytes": 4096
+          }
+        ]
+      }
+    }
+  }
+}

package/dist/runtime/service-access-examples/catalog-summary/src/index.mjs

@@ -0,0 +1,50 @@
+import "@uns-kit/api";
+import { registerApiCatalog } from "@uns-kit/api";
+import { ConfigFile, UnsProxyProcess } from "@uns-kit/core";
+import { CatalogPublicationClient } from "@uns-kit/core/runtime/catalog-publication-client.js";
+import { loadServiceAccessDeclaration } from "@uns-kit/core/runtime/service-access-package.js";
+
+import { createSummaryOffer } from "./offer.mjs";
+
+const required = (key) => {
+  const value = process.env[key];
+  if (!value) throw new Error(`Missing managed runtime value: ${key}`);
+  return value;
+};
+const declaration = await loadServiceAccessDeclaration(new URL("../package.json", import.meta.url));
+if (!declaration?.publications) throw new Error("Package must declare its catalog operations.");
+const client = new CatalogPublicationClient({
+  controllerBase: required("UNS_CONTROLLER_PUBLIC_BASE"),
+  rttNode: required("RTT_NODE"),
+  instanceId: required("RTT_INSTANCE_ID"),
+  version: required("version"),
+  manifest: declaration.publications,
+});
+const config = await ConfigFile.loadConfig();
+if (!config.uns.jwksWellKnownUrl) throw new Error("Configure the Controller JWKS URL.");
+const runtime = new UnsProxyProcess(config.infra.host, {
+  processName: config.uns.processName,
+  username: config.mqtt?.username,
+  password: config.mqtt?.password,
+});
+let stopping;
+const shutdown = () => (stopping ??= runtime.shutdown());
+for (const signal of ["SIGINT", "SIGTERM"])
+  process.once(signal, () => {
+    void shutdown().then(
+      () => process.exit(0),
+      () => {
+        process.exitCode = 1;
+      },
+    );
+  });
+try {
+  await runtime.prepareHandover(config.uns.instanceMode, config.uns.handover);
+  const api = await runtime.createApiProxy("catalog", { jwks: { wellKnownJwksUrl: config.uns.jwksWellKnownUrl } });
+  api.registerCatalogRoute();
+  await registerApiCatalog(api, { dataOfferSources: { sampleCount: createSummaryOffer(client) }, context: undefined });
+} catch {
+  console.error("Catalog startup failed; check configuration, Service access and runtime logs.");
+  await shutdown();
+  process.exitCode = 1;
+}

package/dist/runtime/service-access-examples/catalog-summary/src/offer.mjs

@@ -0,0 +1,35 @@
+import { defineDataCatalogField, defineDataCatalogOfferSource, defineDataCatalogQueryParam, defineDataCatalogSchema } from "@uns-kit/api";
+import { catalogPublicationHandler } from "@uns-kit/api/catalog-publication-handler.js";
+
+export function createSummaryOffer(client) {
+  return defineDataCatalogOfferSource({
+    offerId: "sample-count",
+    displayName: "Temperature sample count",
+    description: "Count of samples in an approved interval; raw measurements are not returned.",
+    topic: "example/public/line-1",
+    asset: "equipment",
+    objectType: "dataset",
+    objectId: "sample-count",
+    attribute: "json",
+    method: "GET",
+    queryParams: ["from", "to"].map((name) =>
+      defineDataCatalogQueryParam(name, "ISO 8601 with timezone; at most one hour.", { required: true, format: "date-time" }),
+    ),
+    response: { statusCode: "200", contentType: "application/json" },
+    schema: defineDataCatalogSchema({
+      id: "sample-count",
+      title: "Sample count",
+      contentType: "application/json",
+      fields: [
+        defineDataCatalogField("count", "integer", "Number of returned samples"),
+        defineDataCatalogField("hasMore", "boolean", "More source samples exist than the bounded result contains"),
+      ],
+    }),
+    handler: ({ req, res }) =>
+      catalogPublicationHandler(client, "sample-count", async ({ history }) => {
+        const rows = await history("temperature");
+        if (!Array.isArray(rows.data) || typeof rows.truncated !== "boolean") throw new Error("Unexpected source response.");
+        return { count: rows.data.length, hasMore: rows.truncated };
+      })(req, res),
+  });
+}