@uns-kit/core 3.0.47 → 3.0.48

package/MIGRATIONS.md

@@ -9,6 +9,16 @@ 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

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/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.

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,28 @@
+{
+  "name": "example-background-reader",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "service-access.json",
+    "config-example.json"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@uns-kit/core": "^3.0.47"
+  },
+  "unsDatahub": {
+    "schemaVersion": 1,
+    "kind": "addon",
+    "controllerCompatibility": ">=2 <3",
+    "serviceAccess": "service-access.json"
+  }
+}

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

@@ -0,0 +1,11 @@
+{
+  "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,21 @@
+import { ServiceTokenProvider } from "@uns-kit/core/tools/auth/service-token-provider.js";
+
+export const sourceTopic = "example/background/line-1/equipment/main/temperature";
+
+/** 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,26 @@
+# catalog-summary
+
+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 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.

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");
+// service-access.json stays at the package root, as declared in package.json.

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,29 @@
+{
+  "name": "example-catalog-summary",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "service-access.json",
+    "config-example.json"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@uns-kit/core": "^3.0.47",
+    "@uns-kit/api": "^3.0.47"
+  },
+  "unsDatahub": {
+    "schemaVersion": 1,
+    "kind": "addon",
+    "controllerCompatibility": ">=2 <3",
+    "serviceAccess": "service-access.json"
+  }
+}

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

@@ -0,0 +1,65 @@
+{
+  "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 { parseServiceAccessDeclaration } from "@uns-kit/core/runtime/service-access.js";
+import { readFile } from "node:fs/promises";
+
+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 = parseServiceAccessDeclaration(JSON.parse(await readFile(new URL("../service-access.json", import.meta.url), "utf8")));
+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),
+  });
+}

package/dist/runtime/service-access-guide.md

@@ -1,130 +1,246 @@
-# Service access and publications (3.0.47)
+# Service access: from declaration to a running service
 
-This opt-in protocol separates permission to call a catalog operation from
-permission to read its source. It is not a sandbox for arbitrary application
-code or a substitute for restricted database and MQTT identities.
+For application developers and coding agents using **SDK 3.0.47 or later**.
+Common Service access also requires a matching Controller; these workflows were
+verified with Controller **2.2.95**. SDK installation alone enables no host rights.
 
-Package metadata requests authority; it never grants it. Keep existing JWT/JWKS
-endpoint guards. Do not forward caller tokens to privileged sources or retry a
-denied caller read with stronger credentials.
+The developer declares a permission ceiling and uses the SDK. An administrator
+reviews the installed release in **Micro services → instance → Service access**.
+The Controller stores that decision, issues the instance credential and supplies
+its file path. The SDK reads the current credential when making a request. The UI
+is a policy editor, not a place to copy a bearer token into application code.
 
-## Declaration
+## Choose the access model
 
-Ship a bounded JSON file with the installed package, and retain it in the build:
+| Application activity | Credential used | Administrator approves | Mechanism |
+| --- | --- | --- | --- |
+| Background UNS API read | Service token only | `read:uns` and explicit UNS paths | `ServiceTokenProvider` / API client |
+| Approved derived catalog operation | Service token plus the incoming user's token | Service capability, exact publication sources/output and audience; user separately needs operation access | `CatalogPublicationClient` + `catalogPublicationHandler` |
+| Direct MQTT subscribe/publish | Broker credentials | Broker ACLs for the relevant topics | MQTT connection settings and broker authorization |
+| Direct SQL/external API access | That resource's credential | Database/external-system grants | Application adapter and secret references |
+
+**`read:uns` protects OpenHub API reads. It does not install MQTT ACLs.**
+MQTT-style filters in Service access describe API resource paths; their syntax
+does not make the HTTP service token a broker password. `infra.host` and the
+example's `mqtt.username/password` concern runtime MQTT connectivity. Configure
+broker ACLs separately, including the runtime signaling topics your deployment
+requires. A direct database connection is governed by its database identity.
+This capability is not an arbitrary-code sandbox.
+
+## Runnable examples and package contents
+
+Both examples are independent Node.js 22+ projects with complete source,
+credential-free configuration, a declaration, build script and package metadata:
+
+- [Background reader](https://github.com/uns-openhub/uns-kit/tree/master/examples/service-access/background-reader)
+- [Catalog summary](https://github.com/uns-openhub/uns-kit/tree/master/examples/service-access/catalog-summary)
+
+The npm core package also ships this guide at
+`@uns-kit/core/runtime/service-access-guide.md` and both projects under
+`node_modules/@uns-kit/core/dist/runtime/service-access-examples/`. Copy a project
+to your own directory before installing/building it; do not edit `node_modules`.
+Source code, not repeated prose fragments, is the complete runnable example.
+
+Each `package.json` points at the root declaration and retains it in the artifact:
 
 ```json
-{"unsDatahub":{"serviceAccess":"service-access.json"}}
+{
+  "files": ["dist", "service-access.json", "config-example.json"],
+  "unsDatahub": {
+    "schemaVersion": 1,
+    "kind": "addon",
+    "controllerCompatibility": ">=2 <3",
+    "serviceAccess": "service-access.json"
+  }
+}
+```
+
+This is metadata to merge into the application's existing package.json. Keep the
+real name/version/dependencies/scripts. The SDK is imported as published packages;
+no copied validators, source overlays or application-name Controller branches.
+Do not declare the historical `catalogAccess` marker alongside `serviceAccess`.
+
+In either copied example:
+
+```sh
+pnpm install
+pnpm run build
+cp config-example.json config.json
 ```
 
-Use `parseServiceAccessDeclaration` from `@uns-kit/core/runtime/service-access.js`:
+Select your local MQTT/Controller endpoints and use environment or secret-provider
+references for credentials. Never commit config.json, .env, keys or tokens. Under
+a Controller deployment, instance configuration is managed by that Controller.
+The examples declare ordinary cold operation, not state-preserving hot handover.
+
+## 1. Background service: no Catalog and no HTTP listener
+
+The background reader asks for one source through the OpenHub history API:
 
 ```json
 {
   "protocol": 1,
   "permissions": {
     "scopes": ["read:uns"],
-    "accessRules": ["example/background/#"]
+    "accessRules": ["example/background/line-1/equipment/main/temperature"]
   }
 }
 ```
 
-This works without a catalog, HTTP endpoint, or human requester. The declaration
-requests a ceiling; an administrator must apply the effective policy under
-**Microservices → instance → Service access** before the service can start with
-a managed identity. Review the exact installed version and declaration digest.
-The administrator can select fewer capabilities and narrower MQTT path filters;
-unknown or administrative scopes are rejected. The identity, revocation and
-same-request reissue mechanisms are the existing managed workload mechanisms.
-UNS resource rules bound direct UNS reads; other recognized runtime scopes retain
-their existing authorization semantics. This protocol does not create new
-SQL, broker, filesystem or arbitrary external-service permissions.
-
-A combined service adds optional `publications`, containing the manifest parsed
-by `parseCatalogPublicationManifest`, to the same envelope. A publication-only
-service uses empty `permissions.scopes` and `permissions.accessRules`. Its
-managed token then has `catalog:sources:read` and **no raw UNS paths**. Adding
-publication sources never adds them to the service's direct `read:uns` rules.
-Publication approval is a separate operation/audience grant and never silently
-grants other package-requested capabilities. Review both in Service access.
-The Catalog contains execution/status and an administrator link to that editor.
-There is one writable publication editor.
-
-The earlier unpublished `unsDatahub.catalogAccess` marker remains an isolated
-compatibility adapter for the first local fixtures. New consumers use
-`serviceAccess`; declaring both markers is rejected. No released applications
-are automatically migrated.
-
-The optional publication manifest supports GET JSON,
-closed JSON schemas (primitive, object and array types; no references, defaults,
-or composition), string query parameters, and exact history source topics.
-Source path segments follow the existing managed-identity resource vocabulary:
-ASCII letters, digits and hyphens. Each source binds required `from`/`to` date-time parameters, a maximum window
-(at most 31 days) and row count (at most 27000). Dates require a UTC offset.
-Wildcard topics, arbitrary URLs/SQL/source selectors and undeclared input fields
-are rejected. The broker caps source responses at 1 MiB; published responses
-have a separately declared cap of at most 1 MiB.
-
-Each operation declares `caller` or `approved-service`. Both require an explicit
-administrator publication review and current caller permission on the SDK UNS
-resource path (the operation path without `/api/`). In caller mode, source rules
-and `read:uns` must also belong to the caller. Service mode never grants these
-raw permissions to the caller.
-
-## Runtime
-
-Use `CatalogPublicationClient` with the installed, normalized manifest and the
-Controller-provided runtime identity (`RTT_NODE`, `version`, `RTT_INSTANCE_ID`,
-`UNS_CONTROLLER_PUBLIC_BASE`). The default `ServiceTokenProvider` reads the
-Controller's rotating token file. There is no caller-token fallback.
-
-Use `catalogPublicationHandler(client, operationId, transform)` in an existing
-`registerApiCatalog` handler. Call `api.registerCatalogRoute()` to opt into the
-existing signed launch route lease. The transform receives `history(sourceId)`
-and the already validated input. It owns the derived result, not authorization.
-The HTTP helper sets `Cache-Control: no-store` and rejects undeclared result
-fields. Each execution rechecks current authority after asynchronous work,
-including cached application results. Custom downloads and other handlers must
-use the same mediated path; this candidate adds no persistent result cache.
-
-A publication-only workload token has `catalog:sources:read` and no direct
-`read:uns` authority. A combined service may separately receive `read:uns` on
-its reviewed background paths, without receiving raw access to publication
-sources. The Controller broker checks current user policy, active machine
-identity/token generation, reviewed identity binding, launch, loaded portable
-configuration, publication revision, audience and source bounds. Its internal
-history token is exact-topic, lasts 15 seconds, and never leaves the broker.
-Neither token bytes nor raw records belong in logs, review receipts or audit.
-
-Two local acceptance consumers (energy intervals and quality sample counts) use
-the same helper and Controller path. No application-name branch is needed.
-
-## Adoption boundary
-
-The SDK contract is introduced in 3.0.47. A matching Controller implementation
-must also be installed; an SDK upgrade alone does not enable the host capability.
-Existing applications do not change mode
-implicitly. Install the shared SDK release first, update consumer lockfiles,
-then review the matching installed declaration through the Controller.
-Controller publication is bound to the installed declaration and portable
-configuration; edits require review. A changed loaded configuration requires a
-new launch, not token refresh. With the matching Controller candidate, the
-signed digest of the same confirmed live launch survives ordinary credential
-expiry and Controller restart. Current identity, policy, generation and approval
-are still checked; expired bearer tokens remain invalid. Missing, corrupt,
-foreign or changed-launch evidence requires explicit reviewed recovery.
-
-
-## Local common-contract acceptance
-
-An unrelated background history processor, with no API or Catalog offer, was
-reviewed, narrowed live, revoked, reissued with the same identity and cold-moved
-to another Controller. It retained the same policy and generation across the
-move. A combined service read its separate background source directly, while a
-catalog-only user consumed a derived result from a different approved source.
-Both the user and workload were denied direct access to that publication source.
-A publication-only empty raw policy stayed empty in storage and actual tokens.
-
-These are local candidate checks, including clean packed-SDK installs. They are
-not production, arbitrary-code isolation or external-resource adapter acceptance.
-SDK publication and downstream frozen dependency updates
-remain separate steps.
+There is no `publications` section and no human caller. The complete
+`background-reader/src/reader.mjs` imports:
+
+```js
+import { ServiceTokenProvider } from '@uns-kit/core/tools/auth/service-token-provider.js';
+const tokens = new ServiceTokenProvider();
+// Inside each request, not once at application startup:
+const token = await tokens.getAccessToken();
+```
+
+It sends the token as `Authorization: Bearer …` to
+`/api/catchall/batch/range` at `UNS_CONTROLLER_PUBLIC_BASE`, with a fixed declared
+source, explicit from/to, a row limit, timeout and no redirects. Missing credentials
+or 401/403 fail the request; no retry with a human or more powerful credential.
+`src/index.mjs` schedules reads only while the runtime is active. Shutdown stops
+admission, aborts the pending read and cleans up the runtime on SIGINT/SIGTERM.
+
+Administrator steps after deployment:
+
+1. Open **Service access** for the exact installed example release and instance.
+2. Use **Restore defaults** to populate the draft, or select `read:uns` and the
+   exact declared path manually. Defaults do not save or grant anything.
+3. Review **Permitted UNS paths**, then **Apply access policy** and confirm.
+   Only declared paths or narrower filters are allowed; do not replace them with `#`.
+4. **Start** the prepared instance. First managed launch requires reviewed access.
+   There is no catalog publication to approve.
+
+The Controller supplies `UNS_SERVICE_TOKEN_FILE` and runtime endpoint/identity
+metadata. `ServiceTokenProvider` rereads that file for every request, so atomic
+credential rotation is visible without an application restart. When the file is
+configured it is authoritative: missing/empty/unreadable means failure, not fallback.
+Do not cache the returned token for the lifetime of the process.
+
+Acceptance on your local stack: create some history for the declared example
+source. Expect 200 for that source and 403 for another source with the same service
+credential. Verify a policy narrowing or revocation takes effect without granting
+additional paths. Zero rows is a valid response if the selected window has no data.
+
+## 2. Catalog: a user requests a derived result
+
+The catalog summary has empty direct `permissions.scopes` and `accessRules`. Its
+optional `publications` declaration defines `sample-count`, GET JSON, from/to with
+a timezone, at most one hour/1000 rows from
+`example/private/line-1/equipment/main/temperature`, and a closed result containing
+only `{count, hasMore}`. The response cap is 4096 bytes. See its complete
+`service-access.json`; the source and response schema are reviewed data.
+
+`catalog-summary/src/index.mjs` reads and validates that declaration with
+`parseServiceAccessDeclaration`, then constructs `CatalogPublicationClient` using
+the real Controller-injected `RTT_NODE`, `RTT_INSTANCE_ID`, `version` and
+`UNS_CONTROLLER_PUBLIC_BASE`. It configures JWT/JWKS authentication, calls
+`api.registerCatalogRoute()` for the signed installed-launch route lease, and
+registers the offer with `registerApiCatalog`. Do not manufacture these launch
+variables to make a directly started process appear Controller-managed.
+
+`src/offer.mjs` wraps its business transform with the actual SDK helper:
+
+```js
+catalogPublicationHandler(client, 'sample-count', async ({ history }) => {
+  const rows = await history('temperature');
+  return { count: rows.data.length, hasMore: rows.truncated };
+});
+```
+
+`temperature` is the declared source ID, not an arbitrary topic or URL from the
+request. The complete source also validates the source response. The helper takes
+the caller's bearer from the incoming HTTP request. The client separately reads
+the service token through `ServiceTokenProvider`; they are never substituted for
+each other. The business transform owns the count, not the authorization policy.
+
+Administrator steps after preparation:
+
+1. Apply only `catalog:sources:read` in **Service access**, with **no direct UNS
+   paths**. This capability permits the reviewed catalog workflow, not raw reads.
+2. Expand **Published operations → Review access**. Check the exact source,
+   maximum interval/rows, **Published fields** and intended audience.
+3. **Review publication**, then **Approve publication**. A selected audience role
+   does not itself grant every user access to the catalog operation.
+4. Give a test reader access to the operation's SDK resource path:
+   `example/public/line-1/equipment/dataset/sample-count/json` (without `/api/`).
+   Do not grant the private source path just to make Execute work.
+5. Start the prepared instance and Execute the operation as that reader, for
+   example `from=2026-01-01T00:00:00Z` and `to=2026-01-01T01:00:00Z`.
+
+When moving an existing service from legacy credentials to this declaration,
+prepare the new version first. Use **Stop → review Service access/publication →
+Start prepared version** on the chosen owner. A still-live older version can
+block inspection of the prepared release; the same-instance Apply guard requires
+this first-adoption sequence. Retain the old configuration for controlled rollback
+until acceptance; do not grant raw access to get past an adoption error.
+
+The request path is:
+
+1. Browser sends the user's token to the service API through the Controller.
+2. The SDK sends its service credential and the caller context to the Controller.
+3. Controller checks current user operation access, audience, active service
+   identity/generation, live launch, loaded configuration, declaration and approval.
+4. Controller obtains bounded source data using a short-lived exact-source
+   credential internally. It never sends that credential to the service/browser.
+5. The service transforms the data; SDK rechecks authority after the asynchronous
+   work and validates the closed output schema before returning JSON.
+
+Only SDK-integrated execution gets that output validation. Preserve ordinary
+endpoint JWT/JWKS guards; a custom endpoint or custom download must use the same
+mediated path. Arbitrary app code with independent DB/MQTT credentials is outside
+this enforcement. Revocation cannot erase bytes already delivered.
+
+Acceptance: reader Execute 200/{count,hasMore}; caller and service direct source
+reads 403; unapproved/revoked publication 403; invalid window/unknown parameter
+400; no raw source fields or credentials in result/logs. The caller needs no
+source permission in `approved-service` mode. `caller` mode instead requires the
+caller's own source permissions as well; it never retries with stronger authority.
+
+## Contract limits
+
+The publication protocol supports GET JSON, string query parameters, exact history
+topics and closed primitive/object/array schemas. Schema references, defaults and
+composition, wildcard source topics, arbitrary URLs/SQL and undeclared inputs are
+rejected. Source path segments use ASCII letters, digits and hyphens. Each source
+binds the required timezone-qualified `from`/`to`, at most 31 days and 27000 rows.
+The broker caps source responses at 1 MiB; the separately declared output cap is
+also at most 1 MiB. The example intentionally chooses narrower limits.
+
+A combined service can declare background `read:uns` paths and `publications` in
+the same envelope. Review both separately. A publication source never becomes a
+directly readable background path just because it appears in the manifest.
+Unknown or administrative service scopes are rejected.
+
+Ordinary credential renewal and Controller restart preserve a confirmed live
+launch binding. They do not approve a different identity, declaration, policy,
+configuration or launch. Missing or changed evidence requires reviewed recovery;
+an expired bearer remains invalid.
+
+## Troubleshooting and agent checklist
+
+| Symptom | Check |
+| --- | --- |
+| Start requires access review | Exact installed release and `unsDatahub.serviceAccess`; admin must apply the policy |
+| Credential file missing | Real Controller launch/file access; never copy a human token into config |
+| Background read 403 | Active workload identity, `read:uns`, matching permitted path, current generation |
+| Catalog 403 | Caller operation access, audience, service capability and current publication approval |
+| Placement/access changed | Current owner/version/loaded config; stop the legacy owner for first adoption and review the prepared release |
+| API works, MQTT denied | Broker credentials/ACLs; API scopes do not create broker access |
+| Configuration changed | Review the new configuration/contract and restart as required; token refresh cannot replace loaded-launch evidence |
+
+For an agent generating a service: choose the model above, use the published SDK
+imports, ship/validate the declaration, preserve local cleanup, and list the admin
+review needed. Do not create identities, modify user rules or broker ACLs, disable
+JWT checks, synthesize launch metadata, or broaden paths as an automatic fix.
+Keep install/build, review, start, release and production deployment separate.
+
+Maintainers run `pnpm run ts:build` and `pnpm run test:service-access-examples`.
+The latter verifies packaged imports/assets, rotating token use, failures and the
+real catalog HTTP helper using synthetic loopback endpoints. It does not certify
+real MQTT ACLs, Controller RBAC/cluster ownership, or production resource grants.
+Additional SQL, filesystem, broker and external-resource permission adapters are
+outside this protocol. Follow the version-bounded core MIGRATIONS.md on adoption.

package/package.json

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