@mesh-tech/mesh-cli 0.22.3 → 0.23.0

package/dist/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "0b5ff27ae",
-  "builtAt": "2026-09-14T20:11:30.580Z"
+  "commit": "f1a582a76",
+  "builtAt": "2026-09-15T14:25:47.683Z"
 }

package/dist/src/commands/app-check.d.ts

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { jsonReport, type Check, type CheckResult, type CheckStatus } from "./dev-doctor.js";
-export type AppCheckCode = "UI_IN_API" | "NO_UI_SERVICE" | "NO_REGISTER" | "CUSTOM_SESSION_AUTH" | "NON_PLATFORM_LOGGER" | "LOCAL_AUTH_LIB" | "NO_AUTHZ_POINTER" | "METADATA_UNPUBLISHED" | "IAC_GRANTS" | "POINTER_PROJECT_OVERRIDE" | "PASSWORD_STORE" | "EMAIL_ALLOWLIST" | "USERS_TABLE" | "DOCS_SITE_UNAUTHED" | "DOCS_AUDIENCE_IMPLICIT";
+export type AppCheckCode = "UI_IN_API" | "NO_UI_SERVICE" | "NO_REGISTER" | "CUSTOM_SESSION_AUTH" | "NON_PLATFORM_LOGGER" | "LOCAL_AUTH_LIB" | "NO_AUTHZ_POINTER" | "METADATA_UNPUBLISHED" | "IAC_GRANTS" | "POINTER_PROJECT_OVERRIDE" | "PASSWORD_STORE" | "EMAIL_ALLOWLIST" | "USERS_TABLE" | "DOCS_SITE_UNAUTHED" | "DOCS_AUDIENCE_IMPLICIT" | "DOCS_AUDIENCE_UNGRANTABLE";
 export interface AppCheckRule {
     gate: string;
     title: string;
@@ -17,6 +17,7 @@ export interface Finding {
 }
 export declare function srcFiles(dir: string): string[];
 export declare function isUiDir(name: string): boolean;
+export declare function stringList(value: string | undefined): string[] | undefined;
 export declare function balancedSpan(text: string, open: number): string;
 export declare function splitTopLevel(inner: string): string[];
 export declare function stripTrailingComments(value: string): string;

package/dist/src/commands/app-check.js

@@ -110,6 +110,13 @@ export const APP_CHECK_RULES = {
         remediation: 'declare the surface as mesh.apps.AppApiSurface or VendorApiSurface (or pass kind: "app" | "vendor"), or state docs: { audience: { roles: […] } }',
         scope: "app",
     },
+    DOCS_AUDIENCE_UNGRANTABLE: {
+        gate: "H",
+        title: "Docs audience grantable from the Hub",
+        severity: "block",
+        remediation: 'declare every audience role on the ZitadelAppIdentity (roles: ["docs"]) so the Hub can grant it, and do not set idTokenRoleAssertion: false on the application the docs sign-in proxy uses (applications.<name>) — the identity asserts roles into the ID token by default, and the site\'s gate reads that token',
+        scope: "app",
+    },
 };
 export const APP_CHECK_CODES = Object.keys(APP_CHECK_RULES);
 const SRC_EXT = new Set([".ts", ".tsx", ".js", ".mjs", ".jsx"]);
@@ -243,6 +250,28 @@ const RE_ALLOWLIST = /ADMIN_EMAILS|ALLOWED_EMAILS|allowedEmails|adminEmails/;
 const RE_USERS_TABLE = /create table (if not exists )?"?(users|roles|user_roles|permissions)"?/i;
 const RE_SURFACE_NEW = /new\s+mesh\.apps\.(ApiSurface|AppApiSurface|VendorApiSurface|Integration)\s*\(/g;
 const RE_APIDOCS_NEW = /new\s+mesh\.apps\.ApiDocs\s*\(/g;
+const RE_IDENTITY_NEW = /new\s+mesh\.auth\.(ZitadelAppIdentity)\s*\(/g;
+const RE_IDENTITY_BINDING = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*new\s+mesh\.auth\.ZitadelAppIdentity\s*\(/g;
+const DEFAULT_PARTNER_DOCS_ROLES = ["docs"];
+const RE_IDENTITY_APP_CLIENT = /\bapplications\.([A-Za-z_$][\w$]*)\.clientId\b/;
+export function stringList(value) {
+    if (!value)
+        return undefined;
+    const text = value.trim();
+    if (!text.startsWith("[") || !text.endsWith("]"))
+        return undefined;
+    const out = [];
+    for (const entry of splitTopLevel(text.slice(1, -1))) {
+        const item = stripLeadingComments(entry).trim();
+        if (!item)
+            continue;
+        const m = /^(["'])((?:(?!\1).)*)\1$/.exec(stripTrailingComments(item));
+        if (!m)
+            return undefined;
+        out.push(m[2]);
+    }
+    return out;
+}
 const DOCS_SITE_FIELDS = ["pages", "playground", "audience", "basePath", "ingress", "auth"];
 const RE_DEV_BYPASS = /^["']dev-bypass["']$/;
 export function balancedSpan(text, open) {
@@ -467,6 +496,8 @@ export function docsSiteFindings(text) {
                 why: `mesh.apps.${decl.ctor} declares a docs site but neither its kind nor its audience — who may read it would fall out of the name heuristic, and a vendor surface must never default to partner-readable that way`,
             });
         }
+        for (const f of docsAudienceUngrantable(text, decl, args, docs, httpText))
+            findings.push(f);
     }
     for (const decl of surfaceDeclarations(text, RE_APIDOCS_NEW)) {
         const options = optionsObject(decl.body);
@@ -485,6 +516,70 @@ export function docsSiteFindings(text) {
     }
     return findings;
 }
+function docsAudienceUngrantable(text, decl, args, docs, httpText) {
+    const findings = [];
+    let roles;
+    if (docs.has("audience")) {
+        const audience = objectLiteralOf(docs.get("audience"), text);
+        roles = audience ? stringList(topLevelProperties(audience).get("roles")) : undefined;
+    }
+    else {
+        const kind = decl.ctor === "AppApiSurface"
+            ? "app"
+            : decl.ctor === "VendorApiSurface"
+                ? "vendor"
+                : /^["']([a-z]+)["']$/.exec(args.get("kind") ?? "")?.[1];
+        if (kind === "app")
+            roles = DEFAULT_PARTNER_DOCS_ROLES;
+    }
+    if (!roles || roles.length === 0)
+        return findings;
+    const identities = [];
+    for (const d of surfaceDeclarations(text, RE_IDENTITY_NEW)) {
+        const options = optionsObject(d.body);
+        if (!options)
+            continue;
+        const binding = [...text.matchAll(RE_IDENTITY_BINDING)].find((m) => text.indexOf(d.body, m.index) === m.index + m[0].length - 1)?.[1];
+        identities.push({ binding, options: topLevelProperties(options) });
+    }
+    if (identities.length === 0)
+        return findings;
+    const docsAuth = objectLiteralOf(docs.get("auth"), text);
+    const clientExpr = (docsAuth ? topLevelProperties(docsAuth).get("clientId") : undefined) ??
+        (httpText ? topLevelProperties(objectLiteralOf(topLevelProperties(httpText).get("auth"), text) ?? "{}").get("clientId") : undefined);
+    const appName = clientExpr ? RE_IDENTITY_APP_CLIENT.exec(clientExpr)?.[1] : undefined;
+    const clientRoot = clientExpr ? /^([A-Za-z_$][\w$]*)\.applications\./.exec(clientExpr.trim())?.[1] : undefined;
+    const identity = (clientRoot ? identities.find((id) => id.binding === clientRoot) : undefined) ??
+        (identities.length === 1 ? identities[0] : undefined);
+    if (!identity)
+        return findings;
+    const rolesText = identity.options.get("roles");
+    const coarseText = identity.options.get("coarseRoles");
+    const declared = rolesText !== undefined ? stringList(rolesText) : coarseText !== undefined ? stringList(coarseText) : [];
+    if (declared) {
+        for (const role of roles) {
+            if (declared.includes(role))
+                continue;
+            findings.push({
+                code: "DOCS_AUDIENCE_UNGRANTABLE",
+                line: decl.line,
+                why: `the docs audience gates on role "${role}", which the app's ZitadelAppIdentity does not declare in roles — the Hub cannot grant it, so no one can read the site`,
+            });
+        }
+    }
+    if (!appName)
+        return findings;
+    const apps = objectLiteralOf(identity.options.get("applications"), text);
+    const app = apps ? objectLiteralOf(topLevelProperties(apps).get(appName), text) : undefined;
+    if (app && topLevelProperties(app).get("idTokenRoleAssertion") === "false") {
+        findings.push({
+            code: "DOCS_AUDIENCE_UNGRANTABLE",
+            line: decl.line,
+            why: `the docs sign-in client is applications.${appName} on the ZitadelAppIdentity, which sets idTokenRoleAssertion: false — the proxy's ID token then carries no roles and the site's gate admits nobody`,
+        });
+    }
+    return findings;
+}
 export function listApps(root) {
     const apps = [];
     const appsDir = path.join(root, "apps");

package/fragments/base/index.ts.hbs

@@ -106,7 +106,10 @@ const worker = new mesh.apps.TemporalWorker("worker", {
 // ingress, so nothing is published on a hostname until you choose to. To
 // publish it, give it an ingress AND the platform sign-in (`auth: { provider:
 // "mesh", clientId, clientSecret }` from a ZitadelAppIdentity application),
-// then list it in the Hub with `env.register({ docs: { url: docs.url,
+// choose its readers with `auth.requireRoles: ["docs"]` (signed in AND holding
+// that role in this app's project — declare the role on the identity, which
+// then asserts it into the application's ID token; omit it for every signed-in
+// user), then list it in the Hub with `env.register({ docs: { url: docs.url,
 // provider: "zudoku" } })`. An API surface (`mesh.apps.ApiSurface`) declares
 // the same site on its `docs` block and wires all of that itself.
 // =============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mesh-tech/mesh-cli",
-  "version": "0.22.3",
+  "version": "0.23.0",
   "description": "CLI for Mesh platform development utilities",
   "type": "module",
   "license": "UNLICENSED",
@@ -42,7 +42,7 @@
   },
   "devDependencies": {
     "@mesh-tech/agent-contracts": "0.2.0",
-    "@mesh-tech/tsconfig": "2.10.0",
+    "@mesh-tech/tsconfig": "2.11.0",
     "@mesh-tech/workflow-viz": "0.3.0",
     "@tanstack/intent": "^0.3.6",
     "@types/node": "^20.0.0",