@devicechain/client 0.14.0-0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright The DeviceChain Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,116 @@
+<!--
+Copyright The DeviceChain Authors
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# @devicechain/client
+
+The DeviceChain client SDK: a small, framework-agnostic core for talking to a
+DeviceChain instance from the browser. Typed GraphQL over `fetch`, live
+subscriptions over `graphql-ws`, and a token seam your app fills in.
+
+There is no Apollo, no store and no React in here. It owns the wire; your app
+owns state and UI.
+
+```bash
+npm install @devicechain/client graphql
+```
+
+`graphql` is a peer dependency — you almost certainly have it already, since the
+typed documents this SDK accepts come from GraphQL Code Generator.
+
+## Where the requests go
+
+Each DeviceChain functional area serves its own GraphQL endpoint, and the SDK
+addresses them **relative to the page**, as `/api/<area>/graphql`. That is the
+contract a DeviceChain ingress serves: the SPA at `/`, each area behind
+`/api/<area>`.
+
+So an app served from the same origin as the instance needs no configuration at
+all. An app served from somewhere else needs a dev-server proxy or a reverse
+proxy that forwards `/api/<area>/...` to the instance — the same shape the
+DeviceChain console's own `vite.config.ts` uses.
+
+## Queries and mutations
+
+```ts
+import { gql } from '@devicechain/client';
+import { DeviceListDocument } from './gql/graphql'; // your generated documents
+
+const { devices } = await gql('device-management', DeviceListDocument, {
+  first: 25,
+});
+```
+
+The area is the first argument, and it is a checked union — `AREAS` is exported
+as a real runtime array, not just a type, so you can enumerate it.
+
+The result and variable types are inferred from the document. If the operation
+takes no variables, the argument is optional.
+
+Failures arrive as a `GraphQLRequestError` carrying the HTTP status and the
+GraphQL error list. `isForbiddenError(err)` is the one classification worth
+special-casing, because "you may not do that" is a different thing to show a
+user than "the request did not arrive".
+
+## Authentication
+
+DeviceChain uses two tokens: a **tenant access token** for ordinary work, and an
+**identity token** for instance-scoped admin endpoints. You register a getter for
+each, and the SDK attaches the right one per request — admin areas are detected
+from the area name, so a new admin call cannot quietly ride the tenant token.
+
+```ts
+import { setAuthTokenGetter, setIdentityTokenGetter } from '@devicechain/client';
+
+setAuthTokenGetter(async () => store.accessToken); // refresh inside if near expiry
+setIdentityTokenGetter(async () => store.identityToken);
+```
+
+Login and refresh calls run without a token; pass `{ anonymous: true }` for those.
+
+`decodeToken`, `isExpired` and `hasAuthority` are exported for reading claims
+client-side. They decode, they do not verify — the server is the authority.
+
+## Subscriptions
+
+```ts
+import { subscribe, disposeSubscriptions } from '@devicechain/client';
+
+const unsubscribe = subscribe(
+  'event-management',
+  MeasurementStreamDocument,
+  { deviceToken: 'sensor-01' },
+  {
+    next: (data) => render(data),
+    error: (err) => report(err),
+    connected: (wasRetry) => setLive(true, wasRetry),
+    closed: () => setLive(false),
+  },
+);
+
+// on sign-out, drop every area socket so a stale token's connection cannot linger
+disposeSubscriptions();
+```
+
+One socket is shared per area and reused across subscriptions. `connected` and
+`closed` are connection-level signals, which is what lets a UI tell "connected
+but idle" apart from "offline" — a distinction a data-only sink cannot make.
+
+## Also in here
+
+- **Basemap resolution** (`resolveBasemap`, `renderableBasemap`) — the client half
+  of the map-tile cascade, so every surface that draws a map resolves a
+  per-surface override over the tenant default the same way.
+- **Token masks** (`generateToken`, `conformsToMask`, `parseMask`, …) — the
+  device-token vocabulary, validated client-side before a round trip.
+
+## Compatibility
+
+ESM only, built for bundler resolution (Vite, webpack, Rollup, esbuild). The
+emitted declarations use extensionless specifiers, which resolve under
+TypeScript's `bundler` module resolution and **not** under `node16`/`nodenext`.
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).

package/dist/basemap.d.ts

@@ -0,0 +1,50 @@
+/** A basemap at any tier: the tile source, and a fallback view. */
+export interface Basemap {
+    tileUrl?: string | null;
+    attribution?: string | null;
+    centerLat?: number | null;
+    centerLon?: number | null;
+    zoom?: number | null;
+}
+/** A resolved basemap that definitely has a tile source, so a renderer can draw it. */
+export interface ResolvedBasemap {
+    tileUrl: string;
+    attribution: string | null;
+    centerLat: number | null;
+    centerLon: number | null;
+    zoom: number | null;
+}
+/**
+ * Fold a per-surface override over the tenant's effective basemap.
+ *
+ * 🔴 The TILE SOURCE is atomic, exactly as it is on the server. If the override names
+ * a tile URL, its attribution comes from the override too — never from the tenant. A
+ * per-field fold would credit the tenant's provider for the override's tiles, which
+ * is a licence violation manufactured by the merge rather than a cosmetic mismatch.
+ * This is the same rule as basemap.Merge in user-management, and it has to be
+ * restated here because this tier never reaches the server.
+ *
+ * The camera folds per field: a widget that only wants to open closer in should not
+ * have to restate a provider to keep it.
+ */
+export declare function resolveBasemap(override: Basemap | null | undefined, tenant: Basemap | null | undefined): Basemap;
+/**
+ * Narrow a folded basemap to one that can actually be rendered, or null.
+ *
+ * A basemap with a camera but no tile source is legitimate — an operator may set a
+ * starting view before choosing a provider — but there is nothing to draw, and the
+ * caller should say so rather than request tiles from an empty URL.
+ */
+export declare function renderableBasemap(b: Basemap | null | undefined): ResolvedBasemap | null;
+/**
+ * The fallback view a surface opens at when it has nothing of its own to fit to.
+ *
+ * 🔴 A FALLBACK, never an override (ADR-079 §5). A surface with real content — an
+ * existing fence's ring, a widget's markers — fits that and ignores this entirely.
+ * Returns null when no tier declared a centre, so the caller keeps its own default
+ * rather than being moved to 0,0.
+ */
+export declare function fallbackView(b: Basemap | null | undefined): {
+    center: [number, number];
+    zoom: number | null;
+} | null;

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+/**
+ * True when the server REFUSED the request for lack of an authority, as opposed
+ * to failing it. Callers use this to render a permission state rather than an
+ * error state.
+ */
+export declare function isForbiddenError(err: unknown): boolean;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { gql, areaPath, areaKey, AREAS, resolveAuthToken, setAuthTokenGetter, setIdentityTokenGetter, GraphQLRequestError, type Area, type RequestOptions, type TypedDocument, } from './transport';
+export { isForbiddenError } from './errors';
+export { resolveBasemap, renderableBasemap, fallbackView, type Basemap, type ResolvedBasemap, } from './basemap';
+export { subscribe, disposeSubscriptions, type SubscriptionSink } from './subscribe';
+export { decodeToken, isExpired, hasAuthority, type DecodedClaims, } from './jwt';
+export { generateToken, normalizeToken, conformsToMask, maskToRegExp, parseMask, resolveMask, isValidToken, sampleToken, validateMask, MAX_TOKEN_LEN, type GenerateOptions, type MaskSegment, type MaskProblem, } from './tokens';

package/dist/index.js

@@ -0,0 +1,360 @@
+// src/transport.ts
+var AREAS = [
+  "user-management",
+  "user-management/admin",
+  "user-management/settings",
+  "device-management",
+  "event-management",
+  "event-processing",
+  "device-state",
+  "command-delivery",
+  "dashboard-management",
+  "outbound-connectors",
+  "ai-inference/admin"
+];
+function areaPath(area) {
+  return `/api/${area}/graphql`;
+}
+function areaKey(area) {
+  return area.split("/")[0];
+}
+function isIdentityArea(area) {
+  return area.endsWith("/admin") || area.endsWith("/settings");
+}
+var tokenGetter = null;
+function setAuthTokenGetter(getter) {
+  tokenGetter = getter;
+}
+var identityTokenGetter = null;
+function setIdentityTokenGetter(getter) {
+  identityTokenGetter = getter;
+}
+async function resolveAuthToken() {
+  return tokenGetter ? tokenGetter() : null;
+}
+var GraphQLRequestError = class extends Error {
+  constructor(message, status, errors) {
+    super(message);
+    this.status = status;
+    this.errors = errors;
+    this.name = "GraphQLRequestError";
+  }
+};
+async function gql(area, document, ...[variables, options]) {
+  const headers = { "Content-Type": "application/json" };
+  if (!options?.anonymous) {
+    const useIdentity = options?.identity ?? isIdentityArea(area);
+    const getter = useIdentity ? identityTokenGetter : tokenGetter;
+    if (getter) {
+      const token = await getter();
+      if (token) headers["Authorization"] = `Bearer ${token}`;
+    }
+  }
+  let res;
+  try {
+    res = await fetch(areaPath(area), {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ query: document.toString(), variables })
+    });
+  } catch (err) {
+    throw new GraphQLRequestError(
+      err instanceof Error ? err.message : "Network request failed",
+      0
+    );
+  }
+  if (!res.ok) {
+    throw new GraphQLRequestError(`Request failed (${res.status})`, res.status);
+  }
+  const body = await res.json();
+  if (body.errors && body.errors.length > 0) {
+    throw new GraphQLRequestError(body.errors[0].message, res.status, body.errors);
+  }
+  if (body.data === void 0) {
+    throw new GraphQLRequestError("Empty GraphQL response", res.status);
+  }
+  return body.data;
+}
+
+// src/errors.ts
+var FORBIDDEN_PREFIX = /^forbidden\b/i;
+function isForbiddenError(err) {
+  if (!(err instanceof GraphQLRequestError)) return false;
+  if (err.status === 403) return true;
+  const messages = err.errors?.length ? err.errors.map((e) => e.message) : [err.message];
+  return messages.some((m) => FORBIDDEN_PREFIX.test(m.trim()));
+}
+
+// src/basemap.ts
+function text(v) {
+  if (typeof v !== "string") return null;
+  const trimmed = v.trim();
+  return trimmed === "" ? null : trimmed;
+}
+function num(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+function resolveBasemap(override, tenant) {
+  const o = override ?? {};
+  const t = tenant ?? {};
+  const overrideAttribution = text(o.attribution);
+  const overrideTiles = overrideAttribution === null ? null : text(o.tileUrl);
+  const tileUrl = overrideTiles ?? text(t.tileUrl);
+  const attribution = overrideTiles ? overrideAttribution : text(t.attribution);
+  const hasOverrideCentre = num(o.centerLat) !== null || num(o.centerLon) !== null;
+  const centerLat = hasOverrideCentre ? num(o.centerLat) : num(t.centerLat);
+  const centerLon = hasOverrideCentre ? num(o.centerLon) : num(t.centerLon);
+  return {
+    tileUrl,
+    attribution,
+    centerLat,
+    centerLon,
+    zoom: num(o.zoom) ?? num(t.zoom)
+  };
+}
+function renderableBasemap(b) {
+  const tileUrl = text(b?.tileUrl);
+  if (!tileUrl) return null;
+  return {
+    tileUrl,
+    attribution: text(b?.attribution),
+    centerLat: num(b?.centerLat),
+    centerLon: num(b?.centerLon),
+    zoom: num(b?.zoom)
+  };
+}
+function fallbackView(b) {
+  const lat = num(b?.centerLat);
+  const lon = num(b?.centerLon);
+  if (lat === null || lon === null) return null;
+  return { center: [lon, lat], zoom: num(b?.zoom) };
+}
+
+// src/subscribe.ts
+import { createClient } from "graphql-ws";
+function wsUrl(area) {
+  const scheme = window.location.protocol === "https:" ? "wss" : "ws";
+  return `${scheme}://${window.location.host}${areaPath(area)}`;
+}
+var clients = /* @__PURE__ */ new Map();
+function clientFor(area) {
+  let client = clients.get(area);
+  if (!client) {
+    client = createClient({
+      url: wsUrl(area),
+      connectionParams: async () => {
+        const token = await resolveAuthToken();
+        return token ? { Authorization: `Bearer ${token}` } : {};
+      }
+    });
+    clients.set(area, client);
+  }
+  return client;
+}
+function subscribe(area, document, variables, sink) {
+  const client = clientFor(area);
+  const disposers = [];
+  if (sink.connected) {
+    disposers.push(client.on("connected", (_socket, _payload, wasRetry) => sink.connected(wasRetry)));
+  }
+  if (sink.closed) {
+    disposers.push(client.on("closed", () => sink.closed()));
+  }
+  disposers.push(
+    client.subscribe(
+      {
+        query: document.toString(),
+        variables
+      },
+      {
+        next: (result) => {
+          if (result.data != null) sink.next(result.data);
+        },
+        error: (err) => sink.error?.(err),
+        complete: () => sink.complete?.()
+      }
+    )
+  );
+  return () => {
+    for (const dispose of disposers) dispose();
+  };
+}
+function disposeSubscriptions() {
+  for (const client of clients.values()) {
+    void client.dispose();
+  }
+  clients.clear();
+}
+
+// src/jwt.ts
+function base64UrlDecode(segment) {
+  const padded = segment.replace(/-/g, "+").replace(/_/g, "/");
+  const json = atob(padded);
+  return decodeURIComponent(
+    Array.prototype.map.call(json, (c) => "%" + ("00" + c.charCodeAt(0).toString(16)).slice(-2)).join("")
+  );
+}
+function decodeToken(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  try {
+    const payload = JSON.parse(base64UrlDecode(parts[1]));
+    return {
+      tenant: payload.tenant ?? "",
+      username: payload.username ?? "",
+      roles: payload.roles ?? [],
+      authorities: payload.authorities ?? [],
+      typ: payload.typ ?? "",
+      exp: payload.exp
+    };
+  } catch {
+    return null;
+  }
+}
+function isExpired(token, skewSeconds = 30) {
+  const claims = decodeToken(token);
+  if (!claims || claims.exp === void 0) return true;
+  const nowSeconds = Date.now() / 1e3;
+  return claims.exp - skewSeconds <= nowSeconds;
+}
+function hasAuthority(claims, required) {
+  if (!claims) return false;
+  return claims.authorities.some((a) => a === "*" || a === required);
+}
+
+// src/tokens.ts
+var READABLE_ALPHABET = "abcdefghjkmnpqrstuvwxyz23456789";
+var DIGITS = "0123456789";
+var TOKEN_GRAMMAR = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+var MAX_TOKEN_LEN = 128;
+function isValidToken(token) {
+  return token.length > 0 && token.length <= MAX_TOKEN_LEN && TOKEN_GRAMMAR.test(token);
+}
+var PLACEHOLDER = /\{([a-zA-Z]+)(?:-(\d+))?\}/g;
+var KNOWN = ["alphanumeric", "numeric", "slug", "uuid"];
+function parseMask(mask) {
+  const segments = [];
+  let last = 0;
+  for (const m of mask.matchAll(PLACEHOLDER)) {
+    const at = m.index ?? 0;
+    if (at > last) segments.push({ kind: "literal", text: mask.slice(last, at) });
+    const name = m[1].toLowerCase();
+    const type = KNOWN.includes(name) ? name : "unknown";
+    segments.push({ kind: "placeholder", type, n: m[2] ? parseInt(m[2], 10) : void 0, raw: m[0] });
+    last = at + m[0].length;
+  }
+  if (last < mask.length) segments.push({ kind: "literal", text: mask.slice(last) });
+  return segments;
+}
+function randomUUID() {
+  const g = globalThis;
+  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    return (c === "x" ? r : r & 3 | 8).toString(16);
+  });
+}
+function generateToken(mask, opts = {}) {
+  const rand = opts.random ?? Math.random;
+  const uuid = opts.uuid ?? randomUUID;
+  const pick = (alphabet, n) => n > MAX_TOKEN_LEN ? "" : Array.from({ length: n }, () => alphabet[Math.floor(rand() * alphabet.length)]).join("");
+  return parseMask(mask).map((seg) => {
+    if (seg.kind === "literal") return seg.text;
+    switch (seg.type) {
+      case "alphanumeric":
+        return pick(READABLE_ALPHABET, seg.n ?? 8);
+      case "numeric":
+        return pick(DIGITS, seg.n ?? 4);
+      case "slug":
+        return opts.seed ? normalizeToken(opts.seed) : pick(READABLE_ALPHABET, 6);
+      case "uuid":
+        return uuid();
+      default:
+        return "";
+    }
+  }).join("");
+}
+function normalizeToken(input) {
+  return input.toLowerCase().trim().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]+/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function maskToRegExp(mask) {
+  const body = parseMask(mask).map((seg) => {
+    if (seg.kind === "literal") return escapeRegExp(seg.text);
+    switch (seg.type) {
+      case "alphanumeric":
+        return `[A-Za-z0-9]{${seg.n ?? 8}}`;
+      case "numeric":
+        return `[0-9]{${seg.n ?? 4}}`;
+      case "slug":
+        return `[a-z0-9]+(?:-[a-z0-9]+)*`;
+      case "uuid":
+        return `[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}`;
+      default:
+        return escapeRegExp(seg.raw);
+    }
+  }).join("");
+  return new RegExp(`^${body}$`);
+}
+function conformsToMask(mask, token) {
+  return maskToRegExp(mask).test(token);
+}
+var SAMPLE_SEED = "Sample Name";
+function sampleToken(mask, seed = SAMPLE_SEED) {
+  return generateToken(mask, {
+    seed,
+    random: () => 0,
+    uuid: () => "3f2b8c14-9d7e-4a51-b6c2-0e8d5a1f7b93"
+  });
+}
+function validateMask(mask) {
+  if (mask === "") return { reason: "empty" };
+  let placeholders = 0;
+  for (const seg of parseMask(mask)) {
+    if (seg.kind !== "placeholder") continue;
+    if (seg.type === "unknown") return { reason: "unknownPlaceholder", placeholder: seg.raw };
+    if (seg.n !== void 0 && seg.n > MAX_TOKEN_LEN) {
+      return { reason: "widthTooLarge", placeholder: seg.raw, max: MAX_TOKEN_LEN };
+    }
+    placeholders++;
+  }
+  if (placeholders === 0) return { reason: "noPlaceholder" };
+  const sample = sampleToken(mask);
+  if (!isValidToken(sample)) return { reason: "invalidToken", sample };
+  return null;
+}
+function resolveMask(masks, entityType) {
+  return masks[entityType] ?? masks.default ?? "{slug}";
+}
+export {
+  AREAS,
+  GraphQLRequestError,
+  MAX_TOKEN_LEN,
+  areaKey,
+  areaPath,
+  conformsToMask,
+  decodeToken,
+  disposeSubscriptions,
+  fallbackView,
+  generateToken,
+  gql,
+  hasAuthority,
+  isExpired,
+  isForbiddenError,
+  isValidToken,
+  maskToRegExp,
+  normalizeToken,
+  parseMask,
+  renderableBasemap,
+  resolveAuthToken,
+  resolveBasemap,
+  resolveMask,
+  sampleToken,
+  setAuthTokenGetter,
+  setIdentityTokenGetter,
+  subscribe,
+  validateMask
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/transport.ts", "../src/errors.ts", "../src/basemap.ts", "../src/subscribe.ts", "../src/jwt.ts", "../src/tokens.ts"],
+  "sourcesContent": ["// Copyright The DeviceChain Authors\n// SPDX-License-Identifier: Apache-2.0\n\n// A tiny GraphQL-over-fetch client, in the spirit of a REST `fetchJson` helper \u2014\n// no Apollo. Each DeviceChain functional area serves its own /graphql endpoint;\n// `area` selects which one. Requests carry the access-token Bearer when one is\n// available (see setAuthTokenGetter); login/refresh run with no token (the\n// GraphQL handler lets an absent token through with no tenant).\n\nimport type { DocumentTypeDecoration } from '@graphql-typed-document-node/core';\n\n// DeviceChain functional areas that expose a GraphQL endpoint. An \"area\" ending in\n// `/admin` is a service's instance-scoped admin API (ADR-033), served by that\n// service at a second path and authenticated with the identity token rather than a\n// tenant access token (see the `identity` request option).\n//\n// `ai-inference` has no `/admin` sibling here because it has no tenant-facing\n// surface a console would call: its data plane serves exactly one mutation, reached\n// by event-processing's service token, never by a browser. Its whole console-facing\n// surface is the operator provider list (ADR-065).\n// Declared as a const array with the type derived from it, rather than as a bare\n// union, so the set is enumerable at RUNTIME. That is what lets a test walk every\n// member and check it against the deployment catalog the Helm chart uses \u2014 a\n// union alone erases at compile time, leaving the check to a hand-kept copy of\n// this list, which is the drift this whole mechanism exists to prevent.\nexport const AREAS = [\n  'user-management',\n  'user-management/admin',\n  'user-management/settings',\n  'device-management',\n  'event-management',\n  'event-processing',\n  'device-state',\n  'command-delivery',\n  'dashboard-management',\n  'outbound-connectors',\n  'ai-inference/admin',\n] as const;\n\nexport type Area = (typeof AREAS)[number];\n\n// Relative URL matching the cluster ingress contract: the ingress routes\n// https://<host>/api/<area>/graphql to each functional-area service and serves\n// the SPA at \"/\". In `vite dev` the same path is handled by the config proxy.\n// 'user-management/admin' resolves to /api/user-management/admin/graphql.\nexport function areaPath(area: Area): string {\n  return `/api/${area}/graphql`;\n}\n\n/**\n * The deployed functional area an Area is served by \u2014 the segment before the\n * first slash, since a suffix like `/admin` or `/settings` names a PLANE of an\n * area rather than an area of its own.\n *\n * This is the join between an Area (a client-side routing convention) and the\n * area vocabulary the server reports from what the chart actually deployed, so\n * the console can tell \"never deployed here\" apart from a transport failure.\n * Note it is deliberately many-to-one: `user-management`,\n * `user-management/admin` and `user-management/settings` all key to\n * `user-management`, and the reverse direction does not exist \u2014 plenty of\n * deployed areas (event-sources, notification-management) have no Area member.\n */\nexport function areaKey(area: Area): string {\n  return area.split('/')[0];\n}\n\n// Whether an area is served on an instance-scoped lane that authenticates with the\n// IDENTITY token rather than a tenant access token (ADR-033). Those endpoints accept\n// nothing else, so the credential follows from the area and is not a per-call\n// choice: deriving it here means a new admin call cannot silently ride the tenant\n// token and 401 (or, worse, be given a tenant token that some future endpoint\n// accepts). Callers may still pass `identity` explicitly; this is the default, not\n// an override.\nexport function isIdentityArea(area: Area): boolean {\n  return area.endsWith('/admin') || area.endsWith('/settings');\n}\n\n// \u2500\u2500 Auth token injection \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// A host (e.g. the console's AuthProvider) registers a getter so the client can\n// attach a fresh access token \u2014 refreshing it first if near expiry \u2014 without the\n// SDK owning React state or storage.\n\nlet tokenGetter: (() => Promise<string | null>) | null = null;\n\nexport function setAuthTokenGetter(getter: (() => Promise<string | null>) | null) {\n  tokenGetter = getter;\n}\n\n// The identity-token getter feeds the admin API (ADR-033): admin requests carry\n// the instance-scoped identity token, not the tenant access token. Registered\n// alongside setAuthTokenGetter; selected per request via the `identity` option.\nlet identityTokenGetter: (() => Promise<string | null>) | null = null;\n\nexport function setIdentityTokenGetter(getter: (() => Promise<string | null>) | null) {\n  identityTokenGetter = getter;\n}\n\n// resolveAuthToken returns the current access token (refreshing via the getter),\n// or null. Internal to the SDK \u2014 the ws subscribe path (subscribe.ts) reuses it\n// so subscriptions authenticate with the same token as queries.\nexport async function resolveAuthToken(): Promise<string | null> {\n  return tokenGetter ? tokenGetter() : null;\n}\n\n// \u2500\u2500 Errors \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport class GraphQLRequestError extends Error {\n  constructor(\n    message: string,\n    /** HTTP status, or 0 for a transport-level failure. */\n    public status: number,\n    /** The raw `errors` array from a GraphQL response, when present. */\n    public errors?: { message: string }[],\n  ) {\n    super(message);\n    this.name = 'GraphQLRequestError';\n  }\n}\n\ninterface GraphQLResponse<T> {\n  data?: T;\n  errors?: { message: string }[];\n}\n\nexport interface RequestOptions {\n  /** Skip attaching the Bearer token (login / refresh run unauthenticated). */\n  anonymous?: boolean;\n  /**\n   * Authenticate with the identity token instead of the tenant access token \u2014\n   * for the instance-scoped admin API (ADR-033). Ignored when `anonymous`.\n   *\n   * Rarely needed: an `/admin` or `/settings` area defaults to the identity token\n   * already (see isIdentityArea). Pass it only to force the lane for an area whose\n   * name does not say so.\n   */\n  identity?: boolean;\n}\n\n// A GraphQL document tagged with its result/variable types \u2014 what gql()/subscribe()\n// accept. A code-generated `TypedDocumentString` (client preset) satisfies it, and\n// so does a hand-authored query string cast to it: the SDK runs in documentMode\n// 'string', calling only `toString()` to get the query text, so the phantom result\n// (`TResult`) and variable (`TVariables`) generics are all that distinguish them.\n// Exported so packages/apps without codegen (dashboards, widgets, the dash app)\n// hand-author typed documents against one shared alias instead of re-inlining it.\nexport type TypedDocument<TResult, TVariables> = DocumentTypeDecoration<TResult, TVariables> & {\n  toString(): string;\n};\n\n// `document` is a code-generated typed document (a `TypedDocumentString` from the\n// GraphQL Code Generator client preset). It implements\n// `DocumentTypeDecoration<TResult, TVariables>`, which carries the result and\n// variable types as phantom generics, and stringifies (via `toString()`) to the\n// raw query text the server expects. The structural `& { toString(): string }`\n// keeps this accepting a document from ANY service while still inferring both the\n// result (`TResult`) and the variables (`TVariables`).\nexport async function gql<TResult, TVariables>(\n  area: Area,\n  document: TypedDocument<TResult, TVariables>,\n  ...[variables, options]: TVariables extends Record<string, never>\n    ? [variables?: undefined, options?: RequestOptions]\n    : [variables: TVariables, options?: RequestOptions]\n): Promise<TResult> {\n  const headers: Record<string, string> = { 'Content-Type': 'application/json' };\n\n  if (!options?.anonymous) {\n    const useIdentity = options?.identity ?? isIdentityArea(area);\n    const getter = useIdentity ? identityTokenGetter : tokenGetter;\n    if (getter) {\n      const token = await getter();\n      if (token) headers['Authorization'] = `Bearer ${token}`;\n    }\n  }\n\n  let res: Response;\n  try {\n    res = await fetch(areaPath(area), {\n      method: 'POST',\n      headers,\n      body: JSON.stringify({ query: document.toString(), variables }),\n    });\n  } catch (err) {\n    throw new GraphQLRequestError(\n      err instanceof Error ? err.message : 'Network request failed',\n      0,\n    );\n  }\n\n  if (!res.ok) {\n    throw new GraphQLRequestError(`Request failed (${res.status})`, res.status);\n  }\n\n  const body = (await res.json()) as GraphQLResponse<TResult>;\n  if (body.errors && body.errors.length > 0) {\n    throw new GraphQLRequestError(body.errors[0].message, res.status, body.errors);\n  }\n  if (body.data === undefined) {\n    throw new GraphQLRequestError('Empty GraphQL response', res.status);\n  }\n  return body.data;\n}\n", "// Copyright The DeviceChain Authors\n// SPDX-License-Identifier: Apache-2.0\n\n// Classification of transport failures a caller has to render differently.\n//\n// Most errors are one shape to a screen (\"something went wrong\"), but a refusal\n// is not: \"you may not see this\" and \"this could not be loaded\" call for\n// different copy, and collapsing them makes a permission boundary look like an\n// outage.\n//\n// This lives beside GraphQLRequestError rather than in a host app because more\n// than one consumer needs it: the console renders a device's position panel from\n// it, and the dashboard runtime's location channel turns the same refusal into a\n// first-class snapshot state (location:read is deliberately outside the read-only\n// viewer baseline, so being refused is an ordinary state rather than a fault).\n\nimport { GraphQLRequestError } from './transport';\n\n// The backend's authorization gate returns core/auth's ErrForbidden, whose text\n// is \"forbidden: missing required authority\"; graphql-go surfaces a resolver\n// error verbatim as the entry's `message`, over HTTP 200. Anchoring the match at\n// the START of the message keeps it from firing on an unrelated error that\n// merely mentions the word (an entity literally named \"forbidden-zone\", say).\nconst FORBIDDEN_PREFIX = /^forbidden\\b/i;\n\n/**\n * True when the server REFUSED the request for lack of an authority, as opposed\n * to failing it. Callers use this to render a permission state rather than an\n * error state.\n */\nexport function isForbiddenError(err: unknown): boolean {\n  if (!(err instanceof GraphQLRequestError)) return false;\n  // A transport-level 403 counts even with no GraphQL body to read.\n  if (err.status === 403) return true;\n  const messages = err.errors?.length ? err.errors.map((e) => e.message) : [err.message];\n  return messages.some((m) => FORBIDDEN_PREFIX.test(m.trim()));\n}\n", "// Copyright The DeviceChain Authors\n// SPDX-License-Identifier: Apache-2.0\n\n// The client half of the basemap cascade (ADR-079).\n//\n// The SERVER resolves a tenant's override over the operator's instance default and\n// hands back one effective value. This module resolves the last tier \u2014 a per-surface\n// override, set on the widget or held as a personal preference in the browser \u2014 over\n// that tenant value, and turns the result into something a renderer can use.\n//\n// It lives in the SDK rather than in either app because THREE surfaces need the\n// identical answer: the console's geofence editor, the dashboard map widget, and the\n// `/dash` viewer app, which has its own login and would otherwise be the one place\n// that quietly disagrees.\n\n/** A basemap at any tier: the tile source, and a fallback view. */\nexport interface Basemap {\n  tileUrl?: string | null;\n  attribution?: string | null;\n  centerLat?: number | null;\n  centerLon?: number | null;\n  zoom?: number | null;\n}\n\n/** A resolved basemap that definitely has a tile source, so a renderer can draw it. */\nexport interface ResolvedBasemap {\n  tileUrl: string;\n  attribution: string | null;\n  centerLat: number | null;\n  centerLon: number | null;\n  zoom: number | null;\n}\n\n/** Treat blank and whitespace-only strings as unset \u2014 an emptied form field means \"inherit\". */\nfunction text(v: string | null | undefined): string | null {\n  if (typeof v !== 'string') return null;\n  const trimmed = v.trim();\n  return trimmed === '' ? null : trimmed;\n}\n\nfunction num(v: number | null | undefined): number | null {\n  return typeof v === 'number' && Number.isFinite(v) ? v : null;\n}\n\n/**\n * Fold a per-surface override over the tenant's effective basemap.\n *\n * \uD83D\uDD34 The TILE SOURCE is atomic, exactly as it is on the server. If the override names\n * a tile URL, its attribution comes from the override too \u2014 never from the tenant. A\n * per-field fold would credit the tenant's provider for the override's tiles, which\n * is a licence violation manufactured by the merge rather than a cosmetic mismatch.\n * This is the same rule as basemap.Merge in user-management, and it has to be\n * restated here because this tier never reaches the server.\n *\n * The camera folds per field: a widget that only wants to open closer in should not\n * have to restate a provider to keep it.\n */\nexport function resolveBasemap(override: Basemap | null | undefined, tenant: Basemap | null | undefined): Basemap {\n  const o = override ?? {};\n  const t = tenant ?? {};\n\n  // \uD83D\uDD34 AN INCOMPLETE OVERRIDE IS NOT AN OVERRIDE. A tile URL with no credit line is\n  // refused outright by the server at the tenant and instance tiers \u2014 the two halves\n  // are stored as one value or not at all \u2014 but THIS tier never reaches the server: a\n  // widget's own options and the fence editor's browser-local fields are entered\n  // client-side and rendered directly.\n  //\n  // Without this the atomic fold below did its job and still produced the defect it\n  // exists to prevent: it correctly refused to lend the tenant's credit line to the\n  // override's tiles, and then drew those tiles with NO credit line at all. Correct\n  // about the cross-crediting, wrong about the licence.\n  //\n  // So an override naming tiles without their attribution is discarded whole, and the\n  // surface falls back to the tenant's properly-credited basemap. Failing closed to a\n  // map that is credited beats honouring a preference that cannot legally be shown.\n  //\n  // On an ordinary instance the fallback is a real map, because a shipped default\n  // means some tier below almost always has one. On an instance whose operator\n  // deliberately stored `{}` there is nothing below, and the surface falls through to\n  // the bundled schematic world \u2014 which is the correct outcome for the same reason,\n  // just a less pretty one.\n  const overrideAttribution = text(o.attribution);\n  const overrideTiles = overrideAttribution === null ? null : text(o.tileUrl);\n  const tileUrl = overrideTiles ?? text(t.tileUrl);\n  const attribution = overrideTiles ? overrideAttribution : text(t.attribution);\n\n  // Latitude and longitude move as a pair for the same reason: half a coordinate\n  // from each tier names a point neither one chose.\n  const hasOverrideCentre = num(o.centerLat) !== null || num(o.centerLon) !== null;\n  const centerLat = hasOverrideCentre ? num(o.centerLat) : num(t.centerLat);\n  const centerLon = hasOverrideCentre ? num(o.centerLon) : num(t.centerLon);\n\n  return {\n    tileUrl,\n    attribution,\n    centerLat,\n    centerLon,\n    zoom: num(o.zoom) ?? num(t.zoom),\n  };\n}\n\n/**\n * Narrow a folded basemap to one that can actually be rendered, or null.\n *\n * A basemap with a camera but no tile source is legitimate \u2014 an operator may set a\n * starting view before choosing a provider \u2014 but there is nothing to draw, and the\n * caller should say so rather than request tiles from an empty URL.\n */\nexport function renderableBasemap(b: Basemap | null | undefined): ResolvedBasemap | null {\n  const tileUrl = text(b?.tileUrl);\n  if (!tileUrl) return null;\n  return {\n    tileUrl,\n    attribution: text(b?.attribution),\n    centerLat: num(b?.centerLat),\n    centerLon: num(b?.centerLon),\n    zoom: num(b?.zoom),\n  };\n}\n\n/**\n * The fallback view a surface opens at when it has nothing of its own to fit to.\n *\n * \uD83D\uDD34 A FALLBACK, never an override (ADR-079 \u00A75). A surface with real content \u2014 an\n * existing fence's ring, a widget's markers \u2014 fits that and ignores this entirely.\n * Returns null when no tier declared a centre, so the caller keeps its own default\n * rather than being moved to 0,0.\n */\nexport function fallbackView(b: Basemap | null | undefined): { center: [number, number]; zoom: number | null } | null {\n  const lat = num(b?.centerLat);\n  const lon = num(b?.centerLon);\n  if (lat === null || lon === null) return null;\n  return { center: [lon, lat], zoom: num(b?.zoom) };\n}\n", "// Copyright The DeviceChain Authors\n// SPDX-License-Identifier: Apache-2.0\n\n// GraphQL subscriptions over the graphql-transport-ws protocol (ADR-037) \u2014 the\n// live half of the client wire, consumed by dashboards (the ADR-039 Hub) for\n// live telemetry. The backend serves subscriptions on the same /api/<area>/graphql\n// path via a WebSocket upgrade; a client derives the ws:// URL from the http one.\n//\n// This is the low-level SDK primitive: one lazily-created graphql-ws client per\n// area (connection reuse), and a subscribe() that binds a typed document to a\n// sink. The dashboard Hub layers subscription multiplexing on top (many widgets,\n// one connection).\n\nimport type { DocumentTypeDecoration } from '@graphql-typed-document-node/core';\nimport { createClient, type Client } from 'graphql-ws';\n\nimport { areaPath, resolveAuthToken, type Area } from './transport';\n\n// wsUrl builds the absolute ws(s):// URL for an area from the current origin,\n// mirroring the relative http path so dev proxy and prod ingress both work.\nfunction wsUrl(area: Area): string {\n  const scheme = window.location.protocol === 'https:' ? 'wss' : 'ws';\n  return `${scheme}://${window.location.host}${areaPath(area)}`;\n}\n\n// One graphql-ws client per area \u2014 the WebSocket (and its connection_init auth)\n// is reused across every subscription to that area. connectionParams is a\n// function so the token is re-resolved on each (re)connect, surviving refresh.\nconst clients = new Map<Area, Client>();\n\nfunction clientFor(area: Area): Client {\n  let client = clients.get(area);\n  if (!client) {\n    client = createClient({\n      url: wsUrl(area),\n      connectionParams: async () => {\n        const token = await resolveAuthToken();\n        return token ? { Authorization: `Bearer ${token}` } : {};\n      },\n    });\n    clients.set(area, client);\n  }\n  return client;\n}\n\nexport interface SubscriptionSink<T> {\n  next: (data: T) => void;\n  error?: (err: unknown) => void;\n  complete?: () => void;\n  // Connection-level signals for the shared per-area socket, distinct from the\n  // per-operation next/error/complete above. `connected` fires on each successful\n  // connection_ack \u2014 `wasRetry` distinguishes a reconnect (after a dropped socket)\n  // from the first connect; `closed` fires on each socket close (graphql-ws then\n  // auto-retries a transient close). A consumer that only needs data can omit both;\n  // a live-status indicator uses them to tell \"connected but idle\" from \"offline\".\n  connected?: (wasRetry: boolean) => void;\n  closed?: () => void;\n}\n\n// subscribe binds a typed subscription document to a sink and returns an\n// unsubscribe function. The document is the same code-generated typed document\n// the query path uses, so the result type is inferred. Errors from the operation\n// (or the socket) surface via sink.error; normal termination via sink.complete.\nexport function subscribe<TResult, TVariables>(\n  area: Area,\n  document: DocumentTypeDecoration<TResult, TVariables> & { toString(): string },\n  variables: TVariables extends Record<string, never> ? undefined : TVariables,\n  sink: SubscriptionSink<TResult>,\n): () => void {\n  const client = clientFor(area);\n  // Client-level connection events are registered per subscribe() and torn down with\n  // it, alongside the operation itself, so a single dispose() call releases both.\n  const disposers: Array<() => void> = [];\n  if (sink.connected) {\n    disposers.push(client.on('connected', (_socket, _payload, wasRetry) => sink.connected!(wasRetry)));\n  }\n  if (sink.closed) {\n    disposers.push(client.on('closed', () => sink.closed!()));\n  }\n  disposers.push(\n    client.subscribe<TResult>(\n      {\n        query: document.toString(),\n        variables: variables as Record<string, unknown> | undefined,\n      },\n      {\n        next: (result) => {\n          if (result.data != null) sink.next(result.data);\n        },\n        error: (err) => sink.error?.(err),\n        complete: () => sink.complete?.(),\n      },\n    ),\n  );\n  return () => {\n    for (const dispose of disposers) dispose();\n  };\n}\n\n// disposeSubscriptions tears down every cached area client (their sockets). A\n// host calls this on sign-out so a stale token's socket does not linger.\nexport function disposeSubscriptions(): void {\n  for (const client of clients.values()) {\n    void client.dispose();\n  }\n  clients.clear();\n}\n", "// Copyright The DeviceChain Authors\n// SPDX-License-Identifier: Apache-2.0\n\n// Client-side decode of the DeviceChain access token (ADR-008 JWT). This reads\n// the payload for display + routing only; it does NOT verify the signature \u2014\n// every protected operation is still enforced server-side by the token's\n// authorities. Never trust these claims for authorization decisions beyond what\n// the UI shows.\n\nexport interface DecodedClaims {\n  /** Tenant the subject acts within (authoritative server-side). */\n  tenant: string;\n  /** Human-readable subject identifier. */\n  username: string;\n  /** Assigned role names \u2014 display/audit only; enforcement is on authorities. */\n  roles: string[];\n  /** Effective capabilities (e.g. \"device:write\", or \"*\" for super-authority). */\n  authorities: string[];\n  /** \"access\" | \"refresh\". */\n  typ: string;\n  /** Expiry, epoch seconds (from the standard `exp` claim). */\n  exp?: number;\n}\n\nfunction base64UrlDecode(segment: string): string {\n  const padded = segment.replace(/-/g, '+').replace(/_/g, '/');\n  const json = atob(padded);\n  // Handle UTF-8 payloads.\n  return decodeURIComponent(\n    Array.prototype.map\n      .call(json, (c: string) => '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2))\n      .join(''),\n  );\n}\n\n/** Decode a JWT's payload, or null if it is malformed. */\nexport function decodeToken(token: string): DecodedClaims | null {\n  const parts = token.split('.');\n  if (parts.length !== 3) return null;\n  try {\n    const payload = JSON.parse(base64UrlDecode(parts[1]));\n    return {\n      tenant: payload.tenant ?? '',\n      username: payload.username ?? '',\n      roles: payload.roles ?? [],\n      authorities: payload.authorities ?? [],\n      typ: payload.typ ?? '',\n      exp: payload.exp,\n    };\n  } catch {\n    return null;\n  }\n}\n\n/** True if the token is missing, malformed, or within `skewSeconds` of expiry. */\nexport function isExpired(token: string, skewSeconds = 30): boolean {\n  const claims = decodeToken(token);\n  if (!claims || claims.exp === undefined) return true;\n  const nowSeconds = Date.now() / 1000;\n  return claims.exp - skewSeconds <= nowSeconds;\n}\n\n/** True if the claims grant the authority (the super-authority \"*\" passes all). */\nexport function hasAuthority(claims: DecodedClaims | null, required: string): boolean {\n  if (!claims) return false;\n  return claims.authorities.some((a) => a === '*' || a === required);\n}\n", "// Copyright The DeviceChain Authors\n// SPDX-License-Identifier: Apache-2.0\n\n// Token masks (ADR-042 P3): the client-side template language that mints, and\n// soft-validates, entity tokens. A mask is literal text plus typed placeholders,\n// and one mask drives three operations:\n//\n//   generate  fill placeholders to produce a concrete token\n//   normalize kebab-case a human string into a {slug}\n//   validate  does a token conform to the mask's shape (soft, UI-only)\n//\n// Masks are advisory: the backend enforces only the security grammar\n// (isValidToken below mirrors rdb.ValidateToken). Style \u2014 lowercase-kebab,\n// prefixes \u2014 lives in the mask, applied here in the console, never on the wire.\n\n// The human-readable alphabet for generated ids: lowercase letters + digits minus\n// the ambiguous 0 o 1 l i, so a minted token can be read back off a label without\n// transcription errors.\nconst READABLE_ALPHABET = 'abcdefghjkmnpqrstuvwxyz23456789';\nconst DIGITS = '0123456789';\n\n// The security grammar the backend enforces (rdb.ValidateToken): letters (either\n// case), digits, hyphen and underscore, starting alphanumeric. Kept in sync by\n// hand \u2014 the same regex, mirrored for a pre-submit check so the user sees a bad\n// token before the server rejects it.\nconst TOKEN_GRAMMAR = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;\n\n/** The maximum token length (mirrors rdb.MaxTokenLen). */\nexport const MAX_TOKEN_LEN = 128;\n\n/** isValidToken mirrors the backend security grammar for a pre-submit check. */\nexport function isValidToken(token: string): boolean {\n  return token.length > 0 && token.length <= MAX_TOKEN_LEN && TOKEN_GRAMMAR.test(token);\n}\n\n/** A parsed mask segment: a literal run, or a typed placeholder. */\nexport type MaskSegment =\n  | { kind: 'literal'; text: string }\n  | { kind: 'placeholder'; type: 'alphanumeric' | 'numeric' | 'slug' | 'uuid' | 'unknown'; n?: number; raw: string };\n\nconst PLACEHOLDER = /\\{([a-zA-Z]+)(?:-(\\d+))?\\}/g;\nconst KNOWN = ['alphanumeric', 'numeric', 'slug', 'uuid'] as const;\n\n/** parseMask splits a mask into its literal and placeholder segments. */\nexport function parseMask(mask: string): MaskSegment[] {\n  const segments: MaskSegment[] = [];\n  let last = 0;\n  for (const m of mask.matchAll(PLACEHOLDER)) {\n    const at = m.index ?? 0;\n    if (at > last) segments.push({ kind: 'literal', text: mask.slice(last, at) });\n    const name = m[1].toLowerCase();\n    const type = (KNOWN as readonly string[]).includes(name) ? (name as 'alphanumeric') : 'unknown';\n    segments.push({ kind: 'placeholder', type, n: m[2] ? parseInt(m[2], 10) : undefined, raw: m[0] });\n    last = at + m[0].length;\n  }\n  if (last < mask.length) segments.push({ kind: 'literal', text: mask.slice(last) });\n  return segments;\n}\n\nexport interface GenerateOptions {\n  /** A human string (e.g. the entity's name) that fills {slug} placeholders. */\n  seed?: string;\n  /** Injectable RNG in [0,1) for deterministic tests; defaults to Math.random. */\n  random?: () => number;\n  /** Injectable uuid for deterministic tests; defaults to crypto.randomUUID. */\n  uuid?: () => string;\n}\n\nfunction randomUUID(): string {\n  const g = globalThis as { crypto?: { randomUUID?: () => string } };\n  if (g.crypto?.randomUUID) return g.crypto.randomUUID();\n  // Fallback for environments without Web Crypto (not the console; belt & braces).\n  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {\n    const r = (Math.random() * 16) | 0;\n    return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);\n  });\n}\n\n/**\n * generateToken fills a mask's placeholders to produce a concrete token:\n * {alphanumeric-N} \u2192 N readable chars, {numeric-N} \u2192 N digits, {uuid} \u2192 a uuid,\n * {slug} \u2192 the normalized seed (or a short readable id when no seed is given, so\n * a \"regenerate\" button always yields something). Literals pass through.\n */\nexport function generateToken(mask: string, opts: GenerateOptions = {}): string {\n  const rand = opts.random ?? Math.random;\n  const uuid = opts.uuid ?? randomUUID;\n  // \uD83D\uDD34 The width is bounded before it is used. A mask may name any width the\n  // regexp matches, and `Array.from({length: 1e20})` THROWS RangeError \u2014 which\n  // made this function, called during render by the settings editor and by every\n  // create form, a way to kill the page from a stored value. No width past\n  // MAX_TOKEN_LEN can mint a legal token anyway, so an absurd one contributes\n  // nothing rather than exploding. validateMask refuses such a mask outright;\n  // this keeps generation safe for a mask stored before it did.\n  const pick = (alphabet: string, n: number) =>\n    n > MAX_TOKEN_LEN\n      ? ''\n      : Array.from({ length: n }, () => alphabet[Math.floor(rand() * alphabet.length)]).join('');\n\n  return parseMask(mask)\n    .map((seg) => {\n      if (seg.kind === 'literal') return seg.text;\n      switch (seg.type) {\n        case 'alphanumeric':\n          return pick(READABLE_ALPHABET, seg.n ?? 8);\n        case 'numeric':\n          return pick(DIGITS, seg.n ?? 4);\n        case 'slug':\n          return opts.seed ? normalizeToken(opts.seed) : pick(READABLE_ALPHABET, 6);\n        case 'uuid':\n          return uuid();\n        default:\n          return ''; // an unknown placeholder contributes nothing to a generated token\n      }\n    })\n    .join('');\n}\n\n/**\n * normalizeToken kebab-cases a human string into a slug: lower-case, spaces and\n * underscores to hyphens, drop anything else, collapse and trim hyphens.\n * \"Ops Overview\" \u2192 \"ops-overview\".\n */\nexport function normalizeToken(input: string): string {\n  return input\n    .toLowerCase()\n    .trim()\n    .replace(/[\\s_]+/g, '-')\n    .replace(/[^a-z0-9-]+/g, '')\n    .replace(/-+/g, '-')\n    .replace(/^-+|-+$/g, '');\n}\n\nfunction escapeRegExp(s: string): string {\n  return s.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\n/**\n * maskToRegExp compiles a mask into a whole-string RegExp for soft, UI-only\n * conformance checking. It is intentionally lenient (accepts either case in\n * alphanumeric/uuid segments) \u2014 the backend, not this, is the authority.\n */\nexport function maskToRegExp(mask: string): RegExp {\n  const body = parseMask(mask)\n    .map((seg) => {\n      if (seg.kind === 'literal') return escapeRegExp(seg.text);\n      switch (seg.type) {\n        case 'alphanumeric':\n          return `[A-Za-z0-9]{${seg.n ?? 8}}`;\n        case 'numeric':\n          return `[0-9]{${seg.n ?? 4}}`;\n        case 'slug':\n          return `[a-z0-9]+(?:-[a-z0-9]+)*`;\n        case 'uuid':\n          return `[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}`;\n        default:\n          return escapeRegExp(seg.raw); // unknown placeholder must match itself literally\n      }\n    })\n    .join('');\n  return new RegExp(`^${body}$`);\n}\n\n/** conformsToMask reports whether a token matches the mask's shape (soft check). */\nexport function conformsToMask(mask: string, token: string): boolean {\n  return maskToRegExp(mask).test(token);\n}\n\n/** The fixed seed sampleToken fills {slug} placeholders from. */\nconst SAMPLE_SEED = 'Sample Name';\n\n/**\n * sampleToken generates the token a mask would mint, deterministically. Same\n * generator as generateToken \u2014 a pinned RNG and uuid rather than a second\n * implementation, so a sample can never disagree with what a create form\n * actually produces.\n */\nexport function sampleToken(mask: string, seed: string = SAMPLE_SEED): string {\n  return generateToken(mask, {\n    seed,\n    random: () => 0,\n    uuid: () => '3f2b8c14-9d7e-4a51-b6c2-0e8d5a1f7b93',\n  });\n}\n\n/**\n * Why a mask cannot mint usable tokens. Structured rather than a message\n * because this package is consumed by localized apps \u2014 the caller maps a reason\n * to its own wording.\n */\nexport type MaskProblem =\n  | { reason: 'empty' }\n  | { reason: 'unknownPlaceholder'; placeholder: string }\n  | { reason: 'noPlaceholder' }\n  | { reason: 'widthTooLarge'; placeholder: string; max: number }\n  | { reason: 'invalidToken'; sample: string };\n\n/**\n * validateMask reports why a mask is unusable, or null when it is fine. It\n * mirrors the server (the tokenmask Go package), which is the authority and\n * refuses the same four things \u2014 every one of which fails SILENTLY otherwise:\n *\n *   empty              nothing to mint from\n *   unknownPlaceholder contributes nothing, so \"dev-{sulg}\" mints \"dev-\"\n *   noPlaceholder      every entity mints the SAME token; the second create collides\n *   invalidToken       the minted sample is not a legal token (a space, a slash\u2026)\n *\n * \uD83D\uDD34 Keep this NO STRICTER than the server. A check the server does not make\n * would refuse a mask the platform accepts, and the operator would have no way\n * to get past it.\n */\nexport function validateMask(mask: string): MaskProblem | null {\n  if (mask === '') return { reason: 'empty' };\n  let placeholders = 0;\n  for (const seg of parseMask(mask)) {\n    if (seg.kind !== 'placeholder') continue;\n    if (seg.type === 'unknown') return { reason: 'unknownPlaceholder', placeholder: seg.raw };\n    // \uD83D\uDD34 Checked BEFORE anything samples the mask. This function is called during\n    // render, per keystroke \u2014 a width of 5e7 froze the tab for seconds building a\n    // string nobody would ever see, and 1e20 threw RangeError and killed the\n    // page. Neither reached the `invalidToken` check below, which is where a\n    // reader would expect an over-long token to be caught.\n    if (seg.n !== undefined && seg.n > MAX_TOKEN_LEN) {\n      return { reason: 'widthTooLarge', placeholder: seg.raw, max: MAX_TOKEN_LEN };\n    }\n    placeholders++;\n  }\n  if (placeholders === 0) return { reason: 'noPlaceholder' };\n  const sample = sampleToken(mask);\n  if (!isValidToken(sample)) return { reason: 'invalidToken', sample };\n  return null;\n}\n\n/**\n * resolveMask picks the mask for an entity type from a token-masks map, falling\n * back to the \"default\" entry and finally to a bare {slug}.\n */\nexport function resolveMask(masks: Record<string, string>, entityType: string): string {\n  return masks[entityType] ?? masks.default ?? '{slug}';\n}\n"],
+  "mappings": ";AAyBO,IAAM,QAAQ;AAAA,EACnB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAQO,SAAS,SAAS,MAAoB;AAC3C,SAAO,QAAQ,IAAI;AACrB;AAeO,SAAS,QAAQ,MAAoB;AAC1C,SAAO,KAAK,MAAM,GAAG,EAAE,CAAC;AAC1B;AASO,SAAS,eAAe,MAAqB;AAClD,SAAO,KAAK,SAAS,QAAQ,KAAK,KAAK,SAAS,WAAW;AAC7D;AAQA,IAAI,cAAqD;AAElD,SAAS,mBAAmB,QAA+C;AAChF,gBAAc;AAChB;AAKA,IAAI,sBAA6D;AAE1D,SAAS,uBAAuB,QAA+C;AACpF,wBAAsB;AACxB;AAKA,eAAsB,mBAA2C;AAC/D,SAAO,cAAc,YAAY,IAAI;AACvC;AAIO,IAAM,sBAAN,cAAkC,MAAM;AAAA,EAC7C,YACE,SAEO,QAEA,QACP;AACA,UAAM,OAAO;AAJN;AAEA;AAGP,SAAK,OAAO;AAAA,EACd;AACF;AAuCA,eAAsB,IACpB,MACA,aACG,CAAC,WAAW,OAAO,GAGJ;AAClB,QAAM,UAAkC,EAAE,gBAAgB,mBAAmB;AAE7E,MAAI,CAAC,SAAS,WAAW;AACvB,UAAM,cAAc,SAAS,YAAY,eAAe,IAAI;AAC5D,UAAM,SAAS,cAAc,sBAAsB;AACnD,QAAI,QAAQ;AACV,YAAM,QAAQ,MAAM,OAAO;AAC3B,UAAI,MAAO,SAAQ,eAAe,IAAI,UAAU,KAAK;AAAA,IACvD;AAAA,EACF;AAEA,MAAI;AACJ,MAAI;AACF,UAAM,MAAM,MAAM,SAAS,IAAI,GAAG;AAAA,MAChC,QAAQ;AAAA,MACR;AAAA,MACA,MAAM,KAAK,UAAU,EAAE,OAAO,SAAS,SAAS,GAAG,UAAU,CAAC;AAAA,IAChE,CAAC;AAAA,EACH,SAAS,KAAK;AACZ,UAAM,IAAI;AAAA,MACR,eAAe,QAAQ,IAAI,UAAU;AAAA,MACrC;AAAA,IACF;AAAA,EACF;AAEA,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,IAAI,oBAAoB,mBAAmB,IAAI,MAAM,KAAK,IAAI,MAAM;AAAA,EAC5E;AAEA,QAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,MAAI,KAAK,UAAU,KAAK,OAAO,SAAS,GAAG;AACzC,UAAM,IAAI,oBAAoB,KAAK,OAAO,CAAC,EAAE,SAAS,IAAI,QAAQ,KAAK,MAAM;AAAA,EAC/E;AACA,MAAI,KAAK,SAAS,QAAW;AAC3B,UAAM,IAAI,oBAAoB,0BAA0B,IAAI,MAAM;AAAA,EACpE;AACA,SAAO,KAAK;AACd;;;AClLA,IAAM,mBAAmB;AAOlB,SAAS,iBAAiB,KAAuB;AACtD,MAAI,EAAE,eAAe,qBAAsB,QAAO;AAElD,MAAI,IAAI,WAAW,IAAK,QAAO;AAC/B,QAAM,WAAW,IAAI,QAAQ,SAAS,IAAI,OAAO,IAAI,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,IAAI,OAAO;AACrF,SAAO,SAAS,KAAK,CAAC,MAAM,iBAAiB,KAAK,EAAE,KAAK,CAAC,CAAC;AAC7D;;;ACFA,SAAS,KAAK,GAA6C;AACzD,MAAI,OAAO,MAAM,SAAU,QAAO;AAClC,QAAM,UAAU,EAAE,KAAK;AACvB,SAAO,YAAY,KAAK,OAAO;AACjC;AAEA,SAAS,IAAI,GAA6C;AACxD,SAAO,OAAO,MAAM,YAAY,OAAO,SAAS,CAAC,IAAI,IAAI;AAC3D;AAeO,SAAS,eAAe,UAAsC,QAA6C;AAChH,QAAM,IAAI,YAAY,CAAC;AACvB,QAAM,IAAI,UAAU,CAAC;AAsBrB,QAAM,sBAAsB,KAAK,EAAE,WAAW;AAC9C,QAAM,gBAAgB,wBAAwB,OAAO,OAAO,KAAK,EAAE,OAAO;AAC1E,QAAM,UAAU,iBAAiB,KAAK,EAAE,OAAO;AAC/C,QAAM,cAAc,gBAAgB,sBAAsB,KAAK,EAAE,WAAW;AAI5E,QAAM,oBAAoB,IAAI,EAAE,SAAS,MAAM,QAAQ,IAAI,EAAE,SAAS,MAAM;AAC5E,QAAM,YAAY,oBAAoB,IAAI,EAAE,SAAS,IAAI,IAAI,EAAE,SAAS;AACxE,QAAM,YAAY,oBAAoB,IAAI,EAAE,SAAS,IAAI,IAAI,EAAE,SAAS;AAExE,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,MAAM,IAAI,EAAE,IAAI,KAAK,IAAI,EAAE,IAAI;AAAA,EACjC;AACF;AASO,SAAS,kBAAkB,GAAuD;AACvF,QAAM,UAAU,KAAK,GAAG,OAAO;AAC/B,MAAI,CAAC,QAAS,QAAO;AACrB,SAAO;AAAA,IACL;AAAA,IACA,aAAa,KAAK,GAAG,WAAW;AAAA,IAChC,WAAW,IAAI,GAAG,SAAS;AAAA,IAC3B,WAAW,IAAI,GAAG,SAAS;AAAA,IAC3B,MAAM,IAAI,GAAG,IAAI;AAAA,EACnB;AACF;AAUO,SAAS,aAAa,GAAyF;AACpH,QAAM,MAAM,IAAI,GAAG,SAAS;AAC5B,QAAM,MAAM,IAAI,GAAG,SAAS;AAC5B,MAAI,QAAQ,QAAQ,QAAQ,KAAM,QAAO;AACzC,SAAO,EAAE,QAAQ,CAAC,KAAK,GAAG,GAAG,MAAM,IAAI,GAAG,IAAI,EAAE;AAClD;;;ACvHA,SAAS,oBAAiC;AAM1C,SAAS,MAAM,MAAoB;AACjC,QAAM,SAAS,OAAO,SAAS,aAAa,WAAW,QAAQ;AAC/D,SAAO,GAAG,MAAM,MAAM,OAAO,SAAS,IAAI,GAAG,SAAS,IAAI,CAAC;AAC7D;AAKA,IAAM,UAAU,oBAAI,IAAkB;AAEtC,SAAS,UAAU,MAAoB;AACrC,MAAI,SAAS,QAAQ,IAAI,IAAI;AAC7B,MAAI,CAAC,QAAQ;AACX,aAAS,aAAa;AAAA,MACpB,KAAK,MAAM,IAAI;AAAA,MACf,kBAAkB,YAAY;AAC5B,cAAM,QAAQ,MAAM,iBAAiB;AACrC,eAAO,QAAQ,EAAE,eAAe,UAAU,KAAK,GAAG,IAAI,CAAC;AAAA,MACzD;AAAA,IACF,CAAC;AACD,YAAQ,IAAI,MAAM,MAAM;AAAA,EAC1B;AACA,SAAO;AACT;AAoBO,SAAS,UACd,MACA,UACA,WACA,MACY;AACZ,QAAM,SAAS,UAAU,IAAI;AAG7B,QAAM,YAA+B,CAAC;AACtC,MAAI,KAAK,WAAW;AAClB,cAAU,KAAK,OAAO,GAAG,aAAa,CAAC,SAAS,UAAU,aAAa,KAAK,UAAW,QAAQ,CAAC,CAAC;AAAA,EACnG;AACA,MAAI,KAAK,QAAQ;AACf,cAAU,KAAK,OAAO,GAAG,UAAU,MAAM,KAAK,OAAQ,CAAC,CAAC;AAAA,EAC1D;AACA,YAAU;AAAA,IACR,OAAO;AAAA,MACL;AAAA,QACE,OAAO,SAAS,SAAS;AAAA,QACzB;AAAA,MACF;AAAA,MACA;AAAA,QACE,MAAM,CAAC,WAAW;AAChB,cAAI,OAAO,QAAQ,KAAM,MAAK,KAAK,OAAO,IAAI;AAAA,QAChD;AAAA,QACA,OAAO,CAAC,QAAQ,KAAK,QAAQ,GAAG;AAAA,QAChC,UAAU,MAAM,KAAK,WAAW;AAAA,MAClC;AAAA,IACF;AAAA,EACF;AACA,SAAO,MAAM;AACX,eAAW,WAAW,UAAW,SAAQ;AAAA,EAC3C;AACF;AAIO,SAAS,uBAA6B;AAC3C,aAAW,UAAU,QAAQ,OAAO,GAAG;AACrC,SAAK,OAAO,QAAQ;AAAA,EACtB;AACA,UAAQ,MAAM;AAChB;;;AClFA,SAAS,gBAAgB,SAAyB;AAChD,QAAM,SAAS,QAAQ,QAAQ,MAAM,GAAG,EAAE,QAAQ,MAAM,GAAG;AAC3D,QAAM,OAAO,KAAK,MAAM;AAExB,SAAO;AAAA,IACL,MAAM,UAAU,IACb,KAAK,MAAM,CAAC,MAAc,OAAO,OAAO,EAAE,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAAC,EAC/E,KAAK,EAAE;AAAA,EACZ;AACF;AAGO,SAAS,YAAY,OAAqC;AAC/D,QAAM,QAAQ,MAAM,MAAM,GAAG;AAC7B,MAAI,MAAM,WAAW,EAAG,QAAO;AAC/B,MAAI;AACF,UAAM,UAAU,KAAK,MAAM,gBAAgB,MAAM,CAAC,CAAC,CAAC;AACpD,WAAO;AAAA,MACL,QAAQ,QAAQ,UAAU;AAAA,MAC1B,UAAU,QAAQ,YAAY;AAAA,MAC9B,OAAO,QAAQ,SAAS,CAAC;AAAA,MACzB,aAAa,QAAQ,eAAe,CAAC;AAAA,MACrC,KAAK,QAAQ,OAAO;AAAA,MACpB,KAAK,QAAQ;AAAA,IACf;AAAA,EACF,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAGO,SAAS,UAAU,OAAe,cAAc,IAAa;AAClE,QAAM,SAAS,YAAY,KAAK;AAChC,MAAI,CAAC,UAAU,OAAO,QAAQ,OAAW,QAAO;AAChD,QAAM,aAAa,KAAK,IAAI,IAAI;AAChC,SAAO,OAAO,MAAM,eAAe;AACrC;AAGO,SAAS,aAAa,QAA8B,UAA2B;AACpF,MAAI,CAAC,OAAQ,QAAO;AACpB,SAAO,OAAO,YAAY,KAAK,CAAC,MAAM,MAAM,OAAO,MAAM,QAAQ;AACnE;;;AChDA,IAAM,oBAAoB;AAC1B,IAAM,SAAS;AAMf,IAAM,gBAAgB;AAGf,IAAM,gBAAgB;AAGtB,SAAS,aAAa,OAAwB;AACnD,SAAO,MAAM,SAAS,KAAK,MAAM,UAAU,iBAAiB,cAAc,KAAK,KAAK;AACtF;AAOA,IAAM,cAAc;AACpB,IAAM,QAAQ,CAAC,gBAAgB,WAAW,QAAQ,MAAM;AAGjD,SAAS,UAAU,MAA6B;AACrD,QAAM,WAA0B,CAAC;AACjC,MAAI,OAAO;AACX,aAAW,KAAK,KAAK,SAAS,WAAW,GAAG;AAC1C,UAAM,KAAK,EAAE,SAAS;AACtB,QAAI,KAAK,KAAM,UAAS,KAAK,EAAE,MAAM,WAAW,MAAM,KAAK,MAAM,MAAM,EAAE,EAAE,CAAC;AAC5E,UAAM,OAAO,EAAE,CAAC,EAAE,YAAY;AAC9B,UAAM,OAAQ,MAA4B,SAAS,IAAI,IAAK,OAA0B;AACtF,aAAS,KAAK,EAAE,MAAM,eAAe,MAAM,GAAG,EAAE,CAAC,IAAI,SAAS,EAAE,CAAC,GAAG,EAAE,IAAI,QAAW,KAAK,EAAE,CAAC,EAAE,CAAC;AAChG,WAAO,KAAK,EAAE,CAAC,EAAE;AAAA,EACnB;AACA,MAAI,OAAO,KAAK,OAAQ,UAAS,KAAK,EAAE,MAAM,WAAW,MAAM,KAAK,MAAM,IAAI,EAAE,CAAC;AACjF,SAAO;AACT;AAWA,SAAS,aAAqB;AAC5B,QAAM,IAAI;AACV,MAAI,EAAE,QAAQ,WAAY,QAAO,EAAE,OAAO,WAAW;AAErD,SAAO,uCAAuC,QAAQ,SAAS,CAAC,MAAM;AACpE,UAAM,IAAK,KAAK,OAAO,IAAI,KAAM;AACjC,YAAQ,MAAM,MAAM,IAAK,IAAI,IAAO,GAAK,SAAS,EAAE;AAAA,EACtD,CAAC;AACH;AAQO,SAAS,cAAc,MAAc,OAAwB,CAAC,GAAW;AAC9E,QAAM,OAAO,KAAK,UAAU,KAAK;AACjC,QAAM,OAAO,KAAK,QAAQ;AAQ1B,QAAM,OAAO,CAAC,UAAkB,MAC9B,IAAI,gBACA,KACA,MAAM,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,SAAS,KAAK,MAAM,KAAK,IAAI,SAAS,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE;AAE7F,SAAO,UAAU,IAAI,EAClB,IAAI,CAAC,QAAQ;AACZ,QAAI,IAAI,SAAS,UAAW,QAAO,IAAI;AACvC,YAAQ,IAAI,MAAM;AAAA,MAChB,KAAK;AACH,eAAO,KAAK,mBAAmB,IAAI,KAAK,CAAC;AAAA,MAC3C,KAAK;AACH,eAAO,KAAK,QAAQ,IAAI,KAAK,CAAC;AAAA,MAChC,KAAK;AACH,eAAO,KAAK,OAAO,eAAe,KAAK,IAAI,IAAI,KAAK,mBAAmB,CAAC;AAAA,MAC1E,KAAK;AACH,eAAO,KAAK;AAAA,MACd;AACE,eAAO;AAAA,IACX;AAAA,EACF,CAAC,EACA,KAAK,EAAE;AACZ;AAOO,SAAS,eAAe,OAAuB;AACpD,SAAO,MACJ,YAAY,EACZ,KAAK,EACL,QAAQ,WAAW,GAAG,EACtB,QAAQ,gBAAgB,EAAE,EAC1B,QAAQ,OAAO,GAAG,EAClB,QAAQ,YAAY,EAAE;AAC3B;AAEA,SAAS,aAAa,GAAmB;AACvC,SAAO,EAAE,QAAQ,uBAAuB,MAAM;AAChD;AAOO,SAAS,aAAa,MAAsB;AACjD,QAAM,OAAO,UAAU,IAAI,EACxB,IAAI,CAAC,QAAQ;AACZ,QAAI,IAAI,SAAS,UAAW,QAAO,aAAa,IAAI,IAAI;AACxD,YAAQ,IAAI,MAAM;AAAA,MAChB,KAAK;AACH,eAAO,eAAe,IAAI,KAAK,CAAC;AAAA,MAClC,KAAK;AACH,eAAO,SAAS,IAAI,KAAK,CAAC;AAAA,MAC5B,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT;AACE,eAAO,aAAa,IAAI,GAAG;AAAA,IAC/B;AAAA,EACF,CAAC,EACA,KAAK,EAAE;AACV,SAAO,IAAI,OAAO,IAAI,IAAI,GAAG;AAC/B;AAGO,SAAS,eAAe,MAAc,OAAwB;AACnE,SAAO,aAAa,IAAI,EAAE,KAAK,KAAK;AACtC;AAGA,IAAM,cAAc;AAQb,SAAS,YAAY,MAAc,OAAe,aAAqB;AAC5E,SAAO,cAAc,MAAM;AAAA,IACzB;AAAA,IACA,QAAQ,MAAM;AAAA,IACd,MAAM,MAAM;AAAA,EACd,CAAC;AACH;AA4BO,SAAS,aAAa,MAAkC;AAC7D,MAAI,SAAS,GAAI,QAAO,EAAE,QAAQ,QAAQ;AAC1C,MAAI,eAAe;AACnB,aAAW,OAAO,UAAU,IAAI,GAAG;AACjC,QAAI,IAAI,SAAS,cAAe;AAChC,QAAI,IAAI,SAAS,UAAW,QAAO,EAAE,QAAQ,sBAAsB,aAAa,IAAI,IAAI;AAMxF,QAAI,IAAI,MAAM,UAAa,IAAI,IAAI,eAAe;AAChD,aAAO,EAAE,QAAQ,iBAAiB,aAAa,IAAI,KAAK,KAAK,cAAc;AAAA,IAC7E;AACA;AAAA,EACF;AACA,MAAI,iBAAiB,EAAG,QAAO,EAAE,QAAQ,gBAAgB;AACzD,QAAM,SAAS,YAAY,IAAI;AAC/B,MAAI,CAAC,aAAa,MAAM,EAAG,QAAO,EAAE,QAAQ,gBAAgB,OAAO;AACnE,SAAO;AACT;AAMO,SAAS,YAAY,OAA+B,YAA4B;AACrF,SAAO,MAAM,UAAU,KAAK,MAAM,WAAW;AAC/C;",
+  "names": []
+}

package/dist/jwt.d.ts

@@ -0,0 +1,20 @@
+export interface DecodedClaims {
+    /** Tenant the subject acts within (authoritative server-side). */
+    tenant: string;
+    /** Human-readable subject identifier. */
+    username: string;
+    /** Assigned role names — display/audit only; enforcement is on authorities. */
+    roles: string[];
+    /** Effective capabilities (e.g. "device:write", or "*" for super-authority). */
+    authorities: string[];
+    /** "access" | "refresh". */
+    typ: string;
+    /** Expiry, epoch seconds (from the standard `exp` claim). */
+    exp?: number;
+}
+/** Decode a JWT's payload, or null if it is malformed. */
+export declare function decodeToken(token: string): DecodedClaims | null;
+/** True if the token is missing, malformed, or within `skewSeconds` of expiry. */
+export declare function isExpired(token: string, skewSeconds?: number): boolean;
+/** True if the claims grant the authority (the super-authority "*" passes all). */
+export declare function hasAuthority(claims: DecodedClaims | null, required: string): boolean;

package/dist/subscribe.d.ts

@@ -0,0 +1,13 @@
+import type { DocumentTypeDecoration } from '@graphql-typed-document-node/core';
+import { type Area } from './transport';
+export interface SubscriptionSink<T> {
+    next: (data: T) => void;
+    error?: (err: unknown) => void;
+    complete?: () => void;
+    connected?: (wasRetry: boolean) => void;
+    closed?: () => void;
+}
+export declare function subscribe<TResult, TVariables>(area: Area, document: DocumentTypeDecoration<TResult, TVariables> & {
+    toString(): string;
+}, variables: TVariables extends Record<string, never> ? undefined : TVariables, sink: SubscriptionSink<TResult>): () => void;
+export declare function disposeSubscriptions(): void;

package/dist/tokens.d.ts

@@ -0,0 +1,92 @@
+/** The maximum token length (mirrors rdb.MaxTokenLen). */
+export declare const MAX_TOKEN_LEN = 128;
+/** isValidToken mirrors the backend security grammar for a pre-submit check. */
+export declare function isValidToken(token: string): boolean;
+/** A parsed mask segment: a literal run, or a typed placeholder. */
+export type MaskSegment = {
+    kind: 'literal';
+    text: string;
+} | {
+    kind: 'placeholder';
+    type: 'alphanumeric' | 'numeric' | 'slug' | 'uuid' | 'unknown';
+    n?: number;
+    raw: string;
+};
+/** parseMask splits a mask into its literal and placeholder segments. */
+export declare function parseMask(mask: string): MaskSegment[];
+export interface GenerateOptions {
+    /** A human string (e.g. the entity's name) that fills {slug} placeholders. */
+    seed?: string;
+    /** Injectable RNG in [0,1) for deterministic tests; defaults to Math.random. */
+    random?: () => number;
+    /** Injectable uuid for deterministic tests; defaults to crypto.randomUUID. */
+    uuid?: () => string;
+}
+/**
+ * generateToken fills a mask's placeholders to produce a concrete token:
+ * {alphanumeric-N} → N readable chars, {numeric-N} → N digits, {uuid} → a uuid,
+ * {slug} → the normalized seed (or a short readable id when no seed is given, so
+ * a "regenerate" button always yields something). Literals pass through.
+ */
+export declare function generateToken(mask: string, opts?: GenerateOptions): string;
+/**
+ * normalizeToken kebab-cases a human string into a slug: lower-case, spaces and
+ * underscores to hyphens, drop anything else, collapse and trim hyphens.
+ * "Ops Overview" → "ops-overview".
+ */
+export declare function normalizeToken(input: string): string;
+/**
+ * maskToRegExp compiles a mask into a whole-string RegExp for soft, UI-only
+ * conformance checking. It is intentionally lenient (accepts either case in
+ * alphanumeric/uuid segments) — the backend, not this, is the authority.
+ */
+export declare function maskToRegExp(mask: string): RegExp;
+/** conformsToMask reports whether a token matches the mask's shape (soft check). */
+export declare function conformsToMask(mask: string, token: string): boolean;
+/**
+ * sampleToken generates the token a mask would mint, deterministically. Same
+ * generator as generateToken — a pinned RNG and uuid rather than a second
+ * implementation, so a sample can never disagree with what a create form
+ * actually produces.
+ */
+export declare function sampleToken(mask: string, seed?: string): string;
+/**
+ * Why a mask cannot mint usable tokens. Structured rather than a message
+ * because this package is consumed by localized apps — the caller maps a reason
+ * to its own wording.
+ */
+export type MaskProblem = {
+    reason: 'empty';
+} | {
+    reason: 'unknownPlaceholder';
+    placeholder: string;
+} | {
+    reason: 'noPlaceholder';
+} | {
+    reason: 'widthTooLarge';
+    placeholder: string;
+    max: number;
+} | {
+    reason: 'invalidToken';
+    sample: string;
+};
+/**
+ * validateMask reports why a mask is unusable, or null when it is fine. It
+ * mirrors the server (the tokenmask Go package), which is the authority and
+ * refuses the same four things — every one of which fails SILENTLY otherwise:
+ *
+ *   empty              nothing to mint from
+ *   unknownPlaceholder contributes nothing, so "dev-{sulg}" mints "dev-"
+ *   noPlaceholder      every entity mints the SAME token; the second create collides
+ *   invalidToken       the minted sample is not a legal token (a space, a slash…)
+ *
+ * 🔴 Keep this NO STRICTER than the server. A check the server does not make
+ * would refuse a mask the platform accepts, and the operator would have no way
+ * to get past it.
+ */
+export declare function validateMask(mask: string): MaskProblem | null;
+/**
+ * resolveMask picks the mask for an entity type from a token-masks map, falling
+ * back to the "default" entry and finally to a bare {slug}.
+ */
+export declare function resolveMask(masks: Record<string, string>, entityType: string): string;

package/dist/transport.d.ts

@@ -0,0 +1,54 @@
+import type { DocumentTypeDecoration } from '@graphql-typed-document-node/core';
+export declare const AREAS: readonly ['user-management', 'user-management/admin', 'user-management/settings', 'device-management', 'event-management', 'event-processing', 'device-state', 'command-delivery', 'dashboard-management', 'outbound-connectors', 'ai-inference/admin'];
+export type Area = (typeof AREAS)[number];
+export declare function areaPath(area: Area): string;
+/**
+ * The deployed functional area an Area is served by — the segment before the
+ * first slash, since a suffix like `/admin` or `/settings` names a PLANE of an
+ * area rather than an area of its own.
+ *
+ * This is the join between an Area (a client-side routing convention) and the
+ * area vocabulary the server reports from what the chart actually deployed, so
+ * the console can tell "never deployed here" apart from a transport failure.
+ * Note it is deliberately many-to-one: `user-management`,
+ * `user-management/admin` and `user-management/settings` all key to
+ * `user-management`, and the reverse direction does not exist — plenty of
+ * deployed areas (event-sources, notification-management) have no Area member.
+ */
+export declare function areaKey(area: Area): string;
+export declare function isIdentityArea(area: Area): boolean;
+export declare function setAuthTokenGetter(getter: (() => Promise<string | null>) | null): void;
+export declare function setIdentityTokenGetter(getter: (() => Promise<string | null>) | null): void;
+export declare function resolveAuthToken(): Promise<string | null>;
+export declare class GraphQLRequestError extends Error {
+    /** HTTP status, or 0 for a transport-level failure. */
+    status: number;
+    /** The raw `errors` array from a GraphQL response, when present. */
+    errors?: {
+        message: string;
+    }[] | undefined;
+    constructor(message: string, 
+    /** HTTP status, or 0 for a transport-level failure. */
+    status: number, 
+    /** The raw `errors` array from a GraphQL response, when present. */
+    errors?: {
+        message: string;
+    }[] | undefined);
+}
+export interface RequestOptions {
+    /** Skip attaching the Bearer token (login / refresh run unauthenticated). */
+    anonymous?: boolean;
+    /**
+     * Authenticate with the identity token instead of the tenant access token —
+     * for the instance-scoped admin API (ADR-033). Ignored when `anonymous`.
+     *
+     * Rarely needed: an `/admin` or `/settings` area defaults to the identity token
+     * already (see isIdentityArea). Pass it only to force the lane for an area whose
+     * name does not say so.
+     */
+    identity?: boolean;
+}
+export type TypedDocument<TResult, TVariables> = DocumentTypeDecoration<TResult, TVariables> & {
+    toString(): string;
+};
+export declare function gql<TResult, TVariables>(area: Area, document: TypedDocument<TResult, TVariables>, ...[variables, options]: TVariables extends Record<string, never> ? [variables?: undefined, options?: RequestOptions] : [variables: TVariables, options?: RequestOptions]): Promise<TResult>;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@devicechain/client",
+  "version": "0.14.0-0",
+  "description": "DeviceChain client SDK — two-tier auth, typed GraphQL operations, and graphql-ws subscriptions over the client wire.",
+  "keywords": [
+    "devicechain",
+    "iot",
+    "graphql",
+    "sdk",
+    "typescript"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://devicechain.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devicechain-io/devicechain.git",
+    "directory": "frontend/packages/client"
+  },
+  "bugs": {
+    "url": "https://github.com/devicechain-io/devicechain/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@graphql-typed-document-node/core": "^3.2.0",
+    "graphql-ws": "^6.2.1"
+  },
+  "peerDependencies": {
+    "graphql": "^16.0.0 || ^17.0.0"
+  },
+  "devDependencies": {
+    "graphql": "^17.0.2",
+    "typescript": "~7.0.2"
+  }
+}