@colixsystems/widget-sdk 0.271.0 → 0.273.0

package/README.md

@@ -86,7 +86,19 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.271.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.273.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.273.0 (contract 1.223.0)
+
+**A widget never mints or sets its own permission header.** The host attaches each widget's `X-Widget-Scopes` header itself, from what that widget was granted. Source that calls `/widgets/scope-token` or sets `X-Widget-Scopes` (any casing) is now a blocking `no-scope-header-mint` finding, listed in the new `CONTRACT.scopeMintPatterns`. Comments are not scanned. Declare the scopes your hooks need in `manifest.requestedScopes`, as before; a widget that does that is unaffected.
+
+### What's new in 0.272.0 (contract 1.222.0)
+
+**Breaking for authors: more routes to the page's global object are banned.** `self`, `top`, `parent`, `frames` and `opener` are other names for `window`, `frameElement` leads to the host document, and a function's `.constructor` is `Function()`. The linter now refuses them (`no-self`, `no-top`, `no-parent`, `no-frames`, `no-opener`, `no-frameelement`, `no-constructor-access`), refuses `eval` and `Function` as any reference, not only as a call (`const e = eval`, `(0, eval)(…)`), and refuses a `\u` escape that spells a letter, digit, `_` or `$` in code (`no-identifier-escape`), which would hide a name from the scan. A widget version that uses them fails lint at submission; versions already published keep running.
+
+- **`self` / `top` / `parent` / `frames` / `opener`** are refused wherever they read a variable: `top[k]`, `{ ...self }`, `typeof parent`, `c ? frames : x`. That includes a local variable with one of these names, so rename it (`const [rootTop, setRootTop] = useState(null)`, `const parentId = …`). A property (`insets.top`, `node.parent`), an object key (`{ top: 0 }`, `const { top: topInset } = insets`) and a word in JSX text after another word on the same line (`Back to top`) are fine. JSX text that is only the word (`<Text>top</Text>`) or starts a line is refused; render it as `{"top"}` or through `t()`.
+- **`.constructor`** is refused as a property read (`x.constructor`, `x?.constructor`), a destructured key (`const { constructor } = fn`) and the quoted name (`x["constructor"]`, `Reflect.get(p, "constructor")`). A class component's own `constructor(props)` method is fine.
+- **`Function`** stays allowed after `instanceof` (`v instanceof Function`); prefer `typeof v === "function"`. To test for a plain object, compare `Object.getPrototypeOf(x) === Object.prototype`.
 
 ### What's new in 0.271.0 (contract 1.221.0)
 
@@ -3493,6 +3505,10 @@ joined — it then reads back as `{ id, name, invited: true }`, with no `email`
 behind it. `status: 'open'` is every invite that is neither accepted nor revoked
 (`pending`, `not_sent` or `expired`); a re-invite keeps the id, so without it earlier invites match too.
 
+Only a signed-in member viewer sees a `USER` cell's `email`. A visitor who is not
+signed in, and an anonymous account, read a member as `{ id, name }`, so render
+`name` and treat `email` as optional.
+
 **The gate is `users.write`, not `users.read`.** A pending invite exposes the email of
 someone who is not a member yet, so the backend gates the entire invite surface —
 listing included — on the `users.write` capability plus a signed `users.write:*`
@@ -3776,7 +3792,7 @@ npx appstudio-widget lint path/to/widget.jsx
 npx appstudio-widget lint widget.web.jsx widget.native.jsx --manifest manifest.js
 ```
 
-Scans for banned patterns (`eval`, `new Function`, dynamic `import()`, direct imports of host stores, raw axios) and for the styling rules below. **Only error-severity findings change the exit code**; warnings print and exit 0.
+Scans for banned patterns (every `CONTRACT.bannedApis` entry — `eval`, `Function`, dynamic `import()`, `window` and its other names `self` / `top` / `parent` / `frames`, `.constructor`, … — and direct imports of host stores) and for the styling rules below. **Only error-severity findings change the exit code**; warnings print and exit 0.
 
 ```js
 import {

package/dist/contract.cjs

@@ -4540,6 +4540,20 @@ const BANNED_APIS = [
     reason:
       "Web-only and opens widget-built bytes on the host origin; open a PDF with usePdfExport().openPdf.",
   },
+  ...["self", "top", "parent", "frames", "opener"].map((identifier) => ({
+    identifier,
+    reason:
+      "Another name for window. Refused where it reads a variable, so rename a local one; `insets.top` and `{ top: 0 }` are fine.",
+  })),
+  {
+    identifier: "frameElement",
+    reason: "The element framing the page, a route to the host document.",
+  },
+  {
+    identifier: ".constructor",
+    reason:
+      "Reaches Function(), which evaluates strings. Refused as a property read or quoted name; a class's own constructor() method is fine.",
+  },
 ];
 
 // REQ-WSDK-PLATFORM §3.4, §5: vetted package allowlist. Each entry is a
@@ -4942,6 +4956,12 @@ const TRANSLATION_API_HOSTS = [
   "lingvanex.com",
 ];
 
+// sc-12906: the host mints a widget's `X-Widget-Scopes` header, never the
+// widget. Bundles share the host's JS realm, so a widget calling the mint
+// itself, or forging the header, could borrow another widget's scopes. Matched
+// case-insensitively against code (comments are blanked before matching).
+const SCOPE_MINT_PATTERNS = ["/widgets/scope-token", "x-widget-scopes"];
+
 // sc-4686 — the currency a price renders in when the HOST does not supply the
 // workspace's own (a host predating the workspace.currency slice, or a caller
 // that forgot to wire it). A rendering fallback so a price is never blank or
@@ -6542,7 +6562,13 @@ const CONTRACT = deepFreeze({
   //    useDatastoreRecord, useDatastoreFigure and useDatastoreAggregate.
   // 1.221.0: additive (sc-14460) — `basicStyleSchema`, exported as
   //    `BASIC_STYLE_SCHEMA`, and `basicStyle(style)`, which applies it.
-  version: "1.221.0",
+  // 1.222.0: stricter (sc-14479) — `self`, `top`, `parent`, `frames`,
+  //    `opener`, `frameElement` and `.constructor` join bannedApis; `eval` and
+  //    `Function` are refused as any reference, not only as a call.
+  // 1.223.0: stricter (sc-12906) — `scopeMintPatterns`; a widget that calls
+  //    the scope-header mint or sets `X-Widget-Scopes` is refused
+  //    (`no-scope-header-mint`).
+  version: "1.223.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6587,6 +6613,7 @@ const CONTRACT = deepFreeze({
   currencyFormats: CURRENCY_FORMATS,
   currencyFormatFallback: CURRENCY_FORMAT_FALLBACK,
   translationApiHosts: TRANSLATION_API_HOSTS,
+  scopeMintPatterns: SCOPE_MINT_PATTERNS,
 });
 
 function isHookAllowed(name) {

package/dist/contract.js

@@ -4537,6 +4537,20 @@ const BANNED_APIS = [
     reason:
       "Web-only and opens widget-built bytes on the host origin; open a PDF with usePdfExport().openPdf.",
   },
+  ...["self", "top", "parent", "frames", "opener"].map((identifier) => ({
+    identifier,
+    reason:
+      "Another name for window. Refused where it reads a variable, so rename a local one; `insets.top` and `{ top: 0 }` are fine.",
+  })),
+  {
+    identifier: "frameElement",
+    reason: "The element framing the page, a route to the host document.",
+  },
+  {
+    identifier: ".constructor",
+    reason:
+      "Reaches Function(), which evaluates strings. Refused as a property read or quoted name; a class's own constructor() method is fine.",
+  },
 ];
 
 // REQ-WSDK-PLATFORM §3.4, §5: vetted package allowlist. Each entry is a
@@ -4939,6 +4953,12 @@ const TRANSLATION_API_HOSTS = [
   "lingvanex.com",
 ];
 
+// sc-12906: the host mints a widget's `X-Widget-Scopes` header, never the
+// widget. Bundles share the host's JS realm, so a widget calling the mint
+// itself, or forging the header, could borrow another widget's scopes. Matched
+// case-insensitively against code (comments are blanked before matching).
+const SCOPE_MINT_PATTERNS = ["/widgets/scope-token", "x-widget-scopes"];
+
 // sc-4686 — the currency a price renders in when the HOST does not supply the
 // workspace's own (a host predating the workspace.currency slice, or a caller
 // that forgot to wire it). A rendering fallback so a price is never blank or
@@ -6539,7 +6559,13 @@ const CONTRACT = deepFreeze({
   //    useDatastoreRecord, useDatastoreFigure and useDatastoreAggregate.
   // 1.221.0: additive (sc-14460) — `basicStyleSchema`, exported as
   //    `BASIC_STYLE_SCHEMA`, and `basicStyle(style)`, which applies it.
-  version: "1.221.0",
+  // 1.222.0: stricter (sc-14479) — `self`, `top`, `parent`, `frames`,
+  //    `opener`, `frameElement` and `.constructor` join bannedApis; `eval` and
+  //    `Function` are refused as any reference, not only as a call.
+  // 1.223.0: stricter (sc-12906) — `scopeMintPatterns`; a widget that calls
+  //    the scope-header mint or sets `X-Widget-Scopes` is refused
+  //    (`no-scope-header-mint`).
+  version: "1.223.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6584,6 +6610,7 @@ const CONTRACT = deepFreeze({
   currencyFormats: CURRENCY_FORMATS,
   currencyFormatFallback: CURRENCY_FORMAT_FALLBACK,
   translationApiHosts: TRANSLATION_API_HOSTS,
+  scopeMintPatterns: SCOPE_MINT_PATTERNS,
 });
 
 function isHookAllowed(name) {

package/dist/linter.cjs

@@ -13,42 +13,151 @@
 const { CONTRACT, normaliseActionTriggerTypes } = require("./contract.cjs");
 const { LUCIDE_ICON_NAMES, LUCIDE_VERSION } = require("./lucideIconNames.cjs");
 
+// Per-identifier match rule, run over the whole masked source. Most banned
+// identifiers compile to a whole-word match.
 function _ruleForIdentifier(identifier, reason) {
   const id = identifier;
   if (id === "Function") {
+    // Any reference, so an alias (`const F = Function`) is refused too.
     return {
       id: "no-function-constructor",
       label: `${reason} (banned: Function() constructor)`,
-      pattern: /(^|[^A-Za-z0-9_$.])Function\s*\(/,
+      pattern: /(?<![\w$])Function(?![\w$])/g,
+      accept: (code, index) =>
+        !_isMemberName(code, index) && _wordBefore(code, index) !== "instanceof",
     };
   }
   if (id === "new Function") {
     return {
       id: "no-new-function",
       label: `${reason} (banned: new Function())`,
-      pattern: /\bnew\s+Function\s*\(/,
+      pattern: /\bnew\s+Function\s*\(/g,
     };
   }
   if (id === "import(") {
     return {
       id: "no-dynamic-import",
       label: `${reason} (banned: dynamic import())`,
-      pattern: /(^|[^A-Za-z0-9_$.])import\s*\(/,
+      pattern: /(?<![\w$.])import\s*\(/g,
     };
   }
   if (id === "eval") {
+    // Any reference, so indirect `(0, eval)(…)` is refused too.
     return {
       id: "no-eval",
       label: `${reason} (banned: eval)`,
-      pattern: /\beval\s*\(/,
+      pattern: /(?<![\w$])eval(?![\w$])/g,
+    };
+  }
+  if (id === ".constructor") {
+    return {
+      id: "no-constructor-access",
+      label: `${reason} (banned: .constructor)`,
+      // Also `{ constructor: F } = fn`; a class's `constructor(` passes.
+      pattern: /\.\s*constructor(?![\w$])|(?<![\w$.])constructor(?![\w$])(?!\s*\()/g,
+      stringPattern: /(["'`])constructor\1/g,
     };
   }
   const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return {
-    id: `no-${id.toLowerCase()}`,
-    label: `${reason} (banned: ${id})`,
-    pattern: new RegExp(`\\b${escaped}\\b`),
-  };
+  const rule = { id: `no-${id.toLowerCase()}`, label: `${reason} (banned: ${id})` };
+  if (_GLOBAL_OBJECT_ALIASES.has(id)) {
+    // Also a common property name, so only a read of the variable is refused.
+    return {
+      ...rule,
+      pattern: new RegExp(`(?<![\\w$])${escaped}(?![\\w$])`, "g"),
+      accept: (code, index) => _readsVariable(code, index, id.length),
+    };
+  }
+  return { ...rule, pattern: new RegExp(`\\b${escaped}\\b`, "g") };
+}
+
+// Other names for the page's global object that are also everyday property
+// names (`insets.top`, `node.parent`).
+const _GLOBAL_OBJECT_ALIASES = new Set(["self", "top", "parent", "frames", "opener"]);
+
+// Read-leading keywords `_EXPRESSION_LEAD_WORDS` leaves out.
+const _READ_LEAD_WORDS = new Set(["new", "extends", "default"]);
+
+// Index of the last non-space character before `index`, and whether a
+// newline lies between.
+function _tokenBefore(code, index) {
+  let at = index - 1;
+  let newline = false;
+  for (; at >= 0 && /\s/.test(code[at]); at -= 1) {
+    if (code[at] === "\n") newline = true;
+  }
+  return { at, newline };
+}
+
+function _wordBefore(code, index) {
+  const { at } = _tokenBefore(code, index);
+  let start = at + 1;
+  while (start > 0 && /[\w$]/.test(code[start - 1])) start -= 1;
+  return code.slice(start, at + 1);
+}
+
+// `x.name` / `x?.name`, but not a spread (`...name`) and not the decimal point
+// of an integer (`1.` + newline starts a new statement).
+function _isMemberName(code, index) {
+  const { at } = _tokenBefore(code, index);
+  if (code[at] !== ".") return false;
+  if (code[at - 1] === ".") return false;
+  return !/(^|[^\w$.])\d[\d_]*$/.test(code.slice(Math.max(0, at - 64), at));
+}
+
+// Whether the name at `index` reads its variable. A member name, an object
+// key, a write, and a word after a declaration keyword or JSX text on the
+// same line do not.
+function _readsVariable(code, index, length) {
+  if (_isMemberName(code, index)) return false;
+  const { at: before, newline } = _tokenBefore(code, index);
+  let after = index + length;
+  while (after < code.length && /\s/.test(code[after])) after += 1;
+  const prev = code[before] || "";
+  if (code[after] === ":" && (prev === "{" || prev === ",")) return false;
+  if (code[after] === "=" && !/[=>]/.test(code[after + 1] || "")) return false;
+  if (newline || !/[\w$]/.test(prev)) return true;
+  const word = _wordBefore(code, index);
+  return _EXPRESSION_LEAD_WORDS.has(word) || _READ_LEAD_WORDS.has(word);
+}
+
+// A `\u` escape spelling an ASCII identifier character (`\u0077indow`).
+const _IDENTIFIER_ESCAPE_RE = /\\u(?:\{0*([0-9a-fA-F]{1,6})\}|([0-9a-fA-F]{4}))/g;
+
+function _escapesAsciiIdentifier(code, index) {
+  // A fresh regex: matchAll clones the shared one with its lastIndex.
+  const at = new RegExp(_IDENTIFIER_ESCAPE_RE.source, "y");
+  at.lastIndex = index;
+  const m = at.exec(code);
+  const ch = String.fromCodePoint(parseInt(m[1] || m[2], 16));
+  return /^[\w$]$/.test(ch);
+}
+
+// One finding per rule per line, in line order, then rule order. Masking keeps
+// every index, so a match's line is the source's line.
+function _bannedApiFindings(source, lines) {
+  const masks = [_stripNonCode(source), _stripNonCode(source, { keepStrings: true })];
+  const hits = [];
+  RULES.forEach((rule, order) => {
+    const ruleLines = new Set();
+    [rule.pattern, rule.stringPattern].forEach((pattern, maskIndex) => {
+      if (!pattern) return;
+      const code = masks[maskIndex];
+      const lineAt = _lineCounter(code);
+      for (const match of code.matchAll(pattern)) {
+        if (!rule.accept || rule.accept(code, match.index)) ruleLines.add(lineAt(match.index));
+      }
+    });
+    for (const line of ruleLines) hits.push({ rule, order, line });
+  });
+  hits.sort((a, b) => a.line - b.line || a.order - b.order);
+  return hits.map(({ rule, line }) => ({
+    rule: rule.id,
+    severity: "error",
+    label: rule.label,
+    line,
+    snippet: lines[line - 1].trim().slice(0, 200),
+  }));
 }
 
 const CONTRACT_RULES = CONTRACT.bannedApis.map((b) =>
@@ -209,7 +318,14 @@ const EXTRA_RULES = [
   {
     id: "no-auth-store-import",
     label: "widgets must not import the host's auth store",
-    pattern: /useAuthStore/,
+    pattern: /useAuthStore/g,
+  },
+  {
+    id: "no-identifier-escape",
+    label:
+      "a \\u escape spelling a letter, digit, _ or $ hides a name from the banned-API scan; write the name plainly",
+    pattern: _IDENTIFIER_ESCAPE_RE,
+    accept: _escapesAsciiIdentifier,
   },
 ];
 
@@ -647,6 +763,36 @@ function _translationApiRules(source) {
   return findings;
 }
 
+// sc-12906 — no-scope-header-mint.
+//
+// The host mints each widget's `X-Widget-Scopes` header from the widget's own
+// installation. A bundle runs in the host's JS realm, so one that calls the
+// mint itself, or sets the header, could borrow another widget's scopes. The
+// server refuses a built-in nobody placed; this catches the attempt at publish.
+// An error with no opt-out: no correct widget touches either.
+function _scopeMintRules(source) {
+  const findings = [];
+  const needles = CONTRACT.scopeMintPatterns || [];
+  const lines = _stripNonCode(source, { keepStrings: true }).split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const lowered = lines[i].toLowerCase();
+    const needle = needles.find((n) => lowered.includes(n));
+    if (!needle) continue;
+    findings.push({
+      rule: "no-scope-header-mint",
+      severity: "error",
+      label:
+        `source references "${needle}" — the host attaches each widget's ` +
+        `permission header itself. Never call that endpoint or set that ` +
+        `header; declare the scopes your hooks need in ` +
+        `manifest.requestedScopes.`,
+      line: i + 1,
+      snippet: lines[i].trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-required-for-user-mutation. See
 // linter.js for the rationale comment. The two files must stay in
 // lockstep (the contract test asserts behaviour-equivalence).
@@ -2330,26 +2476,9 @@ function lintSource(source, options) {
   }
   const findings = [];
   const lines = source.split(/\r?\n/);
-  // Scan code with comments + string/template text blanked out so a banned
-  // identifier only fires on an actual code reference, not on the same word
-  // appearing in prose or string data. `codeLines` lines up 1:1 with `lines`
-  // (masking preserves newlines), so the reported snippet still comes from
-  // the original source.
-  const codeLines = _stripNonCode(source).split(/\r?\n/);
-  for (let i = 0; i < lines.length; i++) {
-    const codeLine = codeLines[i];
-    for (const rule of RULES) {
-      if (rule.pattern.test(codeLine)) {
-        findings.push({
-          rule: rule.id,
-          severity: "error",
-          label: rule.label,
-          line: i + 1,
-          snippet: lines[i].trim().slice(0, 200),
-        });
-      }
-    }
-  }
+  // Comments and string text are masked, so a banned identifier fires only on
+  // code, never on the same word in prose or string data.
+  findings.push(..._bannedApiFindings(source, lines));
   findings.push(
     ..._importRules(source, options && options.manifest).map((f) => ({
       ...f,
@@ -2361,6 +2490,7 @@ function lintSource(source, options) {
   // sc-6970 — soft warning: HTML markup spliced into a content string.
   findings.push(..._htmlInContentRules(source));
   findings.push(..._translationApiRules(source));
+  findings.push(..._scopeMintRules(source));
   findings.push(..._handBuiltPageUrlRules(source));
   findings.push(..._lucideIconRules(source));
   findings.push(..._bundledAssetRules(source, options && options.assetFiles));

package/dist/linter.js

@@ -9,47 +9,151 @@
 import { CONTRACT, normaliseActionTriggerTypes } from "./contract.js";
 import { LUCIDE_ICON_NAMES, LUCIDE_VERSION } from "./lucideIconNames.js";
 
-// Per-identifier match rule. Most banned identifiers compile to a
-// whole-word match; a few have special syntax (`Function(`, `new Function`,
-// `import(`) that needs a tighter regex.
+// Per-identifier match rule, run over the whole masked source. Most banned
+// identifiers compile to a whole-word match.
 function _ruleForIdentifier(identifier, reason) {
   const id = identifier;
   if (id === "Function") {
+    // Any reference, so an alias (`const F = Function`) is refused too.
     return {
       id: "no-function-constructor",
       label: `${reason} (banned: Function() constructor)`,
-      pattern: /(^|[^A-Za-z0-9_$.])Function\s*\(/,
+      pattern: /(?<![\w$])Function(?![\w$])/g,
+      accept: (code, index) =>
+        !_isMemberName(code, index) && _wordBefore(code, index) !== "instanceof",
     };
   }
   if (id === "new Function") {
     return {
       id: "no-new-function",
       label: `${reason} (banned: new Function())`,
-      pattern: /\bnew\s+Function\s*\(/,
+      pattern: /\bnew\s+Function\s*\(/g,
     };
   }
   if (id === "import(") {
     return {
       id: "no-dynamic-import",
       label: `${reason} (banned: dynamic import())`,
-      pattern: /(^|[^A-Za-z0-9_$.])import\s*\(/,
+      pattern: /(?<![\w$.])import\s*\(/g,
     };
   }
   if (id === "eval") {
+    // Any reference, so indirect `(0, eval)(…)` is refused too.
     return {
       id: "no-eval",
       label: `${reason} (banned: eval)`,
-      pattern: /\beval\s*\(/,
+      pattern: /(?<![\w$])eval(?![\w$])/g,
+    };
+  }
+  if (id === ".constructor") {
+    return {
+      id: "no-constructor-access",
+      label: `${reason} (banned: .constructor)`,
+      // Also `{ constructor: F } = fn`; a class's `constructor(` passes.
+      pattern: /\.\s*constructor(?![\w$])|(?<![\w$.])constructor(?![\w$])(?!\s*\()/g,
+      stringPattern: /(["'`])constructor\1/g,
     };
   }
-  // Default: word-boundary anchored. Used for the simple identifier
-  // forms (`window`, `document`, `process`, ...).
   const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return {
-    id: `no-${id.toLowerCase()}`,
-    label: `${reason} (banned: ${id})`,
-    pattern: new RegExp(`\\b${escaped}\\b`),
-  };
+  const rule = { id: `no-${id.toLowerCase()}`, label: `${reason} (banned: ${id})` };
+  if (_GLOBAL_OBJECT_ALIASES.has(id)) {
+    // Also a common property name, so only a read of the variable is refused.
+    return {
+      ...rule,
+      pattern: new RegExp(`(?<![\\w$])${escaped}(?![\\w$])`, "g"),
+      accept: (code, index) => _readsVariable(code, index, id.length),
+    };
+  }
+  return { ...rule, pattern: new RegExp(`\\b${escaped}\\b`, "g") };
+}
+
+// Other names for the page's global object that are also everyday property
+// names (`insets.top`, `node.parent`).
+const _GLOBAL_OBJECT_ALIASES = new Set(["self", "top", "parent", "frames", "opener"]);
+
+// Read-leading keywords `_EXPRESSION_LEAD_WORDS` leaves out.
+const _READ_LEAD_WORDS = new Set(["new", "extends", "default"]);
+
+// Index of the last non-space character before `index`, and whether a
+// newline lies between.
+function _tokenBefore(code, index) {
+  let at = index - 1;
+  let newline = false;
+  for (; at >= 0 && /\s/.test(code[at]); at -= 1) {
+    if (code[at] === "\n") newline = true;
+  }
+  return { at, newline };
+}
+
+function _wordBefore(code, index) {
+  const { at } = _tokenBefore(code, index);
+  let start = at + 1;
+  while (start > 0 && /[\w$]/.test(code[start - 1])) start -= 1;
+  return code.slice(start, at + 1);
+}
+
+// `x.name` / `x?.name`, but not a spread (`...name`) and not the decimal point
+// of an integer (`1.` + newline starts a new statement).
+function _isMemberName(code, index) {
+  const { at } = _tokenBefore(code, index);
+  if (code[at] !== ".") return false;
+  if (code[at - 1] === ".") return false;
+  return !/(^|[^\w$.])\d[\d_]*$/.test(code.slice(Math.max(0, at - 64), at));
+}
+
+// Whether the name at `index` reads its variable. A member name, an object
+// key, a write, and a word after a declaration keyword or JSX text on the
+// same line do not.
+function _readsVariable(code, index, length) {
+  if (_isMemberName(code, index)) return false;
+  const { at: before, newline } = _tokenBefore(code, index);
+  let after = index + length;
+  while (after < code.length && /\s/.test(code[after])) after += 1;
+  const prev = code[before] || "";
+  if (code[after] === ":" && (prev === "{" || prev === ",")) return false;
+  if (code[after] === "=" && !/[=>]/.test(code[after + 1] || "")) return false;
+  if (newline || !/[\w$]/.test(prev)) return true;
+  const word = _wordBefore(code, index);
+  return _EXPRESSION_LEAD_WORDS.has(word) || _READ_LEAD_WORDS.has(word);
+}
+
+// A `\u` escape spelling an ASCII identifier character (`\u0077indow`).
+const _IDENTIFIER_ESCAPE_RE = /\\u(?:\{0*([0-9a-fA-F]{1,6})\}|([0-9a-fA-F]{4}))/g;
+
+function _escapesAsciiIdentifier(code, index) {
+  // A fresh regex: matchAll clones the shared one with its lastIndex.
+  const at = new RegExp(_IDENTIFIER_ESCAPE_RE.source, "y");
+  at.lastIndex = index;
+  const m = at.exec(code);
+  const ch = String.fromCodePoint(parseInt(m[1] || m[2], 16));
+  return /^[\w$]$/.test(ch);
+}
+
+// One finding per rule per line, in line order, then rule order. Masking keeps
+// every index, so a match's line is the source's line.
+function _bannedApiFindings(source, lines) {
+  const masks = [_stripNonCode(source), _stripNonCode(source, { keepStrings: true })];
+  const hits = [];
+  RULES.forEach((rule, order) => {
+    const ruleLines = new Set();
+    [rule.pattern, rule.stringPattern].forEach((pattern, maskIndex) => {
+      if (!pattern) return;
+      const code = masks[maskIndex];
+      const lineAt = _lineCounter(code);
+      for (const match of code.matchAll(pattern)) {
+        if (!rule.accept || rule.accept(code, match.index)) ruleLines.add(lineAt(match.index));
+      }
+    });
+    for (const line of ruleLines) hits.push({ rule, order, line });
+  });
+  hits.sort((a, b) => a.line - b.line || a.order - b.order);
+  return hits.map(({ rule, line }) => ({
+    rule: rule.id,
+    severity: "error",
+    label: rule.label,
+    line,
+    snippet: lines[line - 1].trim().slice(0, 200),
+  }));
 }
 
 const CONTRACT_RULES = CONTRACT.bannedApis.map((b) =>
@@ -73,7 +177,14 @@ const EXTRA_RULES = [
   {
     id: "no-auth-store-import",
     label: "widgets must not import the host's auth store",
-    pattern: /useAuthStore/,
+    pattern: /useAuthStore/g,
+  },
+  {
+    id: "no-identifier-escape",
+    label:
+      "a \\u escape spelling a letter, digit, _ or $ hides a name from the banned-API scan; write the name plainly",
+    pattern: _IDENTIFIER_ESCAPE_RE,
+    accept: _escapesAsciiIdentifier,
   },
 ];
 
@@ -584,6 +695,36 @@ function _translationApiRules(source) {
   return findings;
 }
 
+// sc-12906 — no-scope-header-mint.
+//
+// The host mints each widget's `X-Widget-Scopes` header from the widget's own
+// installation. A bundle runs in the host's JS realm, so one that calls the
+// mint itself, or sets the header, could borrow another widget's scopes. The
+// server refuses a built-in nobody placed; this catches the attempt at publish.
+// An error with no opt-out: no correct widget touches either.
+function _scopeMintRules(source) {
+  const findings = [];
+  const needles = CONTRACT.scopeMintPatterns || [];
+  const lines = _stripNonCode(source, { keepStrings: true }).split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const lowered = lines[i].toLowerCase();
+    const needle = needles.find((n) => lowered.includes(n));
+    if (!needle) continue;
+    findings.push({
+      rule: "no-scope-header-mint",
+      severity: "error",
+      label:
+        `source references "${needle}" — the host attaches each widget's ` +
+        `permission header itself. Never call that endpoint or set that ` +
+        `header; declare the scopes your hooks need in ` +
+        `manifest.requestedScopes.`,
+      line: i + 1,
+      snippet: lines[i].trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-required-for-user-mutation.
 //
 // A widget that calls `useUsers().invite()` / `.deactivate()` /
@@ -2393,26 +2534,9 @@ export function lintSource(source, options) {
   }
   const findings = [];
   const lines = source.split(/\r?\n/);
-  // Scan code with comments + string/template text blanked out so a banned
-  // identifier only fires on an actual code reference, not on the same word
-  // appearing in prose or string data. `codeLines` lines up 1:1 with `lines`
-  // (masking preserves newlines), so the reported snippet still comes from
-  // the original source.
-  const codeLines = _stripNonCode(source).split(/\r?\n/);
-  for (let i = 0; i < lines.length; i++) {
-    const codeLine = codeLines[i];
-    for (const rule of RULES) {
-      if (rule.pattern.test(codeLine)) {
-        findings.push({
-          rule: rule.id,
-          severity: "error",
-          label: rule.label,
-          line: i + 1,
-          snippet: lines[i].trim().slice(0, 200),
-        });
-      }
-    }
-  }
+  // Comments and string text are masked, so a banned identifier fires only on
+  // code, never on the same word in prose or string data.
+  findings.push(..._bannedApiFindings(source, lines));
   // REQ-WSDK-PLATFORM §3.4: import-specifier validation.
   findings.push(
     ..._importRules(source, options && options.manifest).map((f) => ({
@@ -2426,6 +2550,7 @@ export function lintSource(source, options) {
   // sc-6970 — soft warning: HTML markup spliced into a content string.
   findings.push(..._htmlInContentRules(source));
   findings.push(..._translationApiRules(source));
+  findings.push(..._scopeMintRules(source));
   findings.push(..._handBuiltPageUrlRules(source));
   findings.push(..._lucideIconRules(source));
   findings.push(..._bundledAssetRules(source, options && options.assetFiles));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.271.0",
+  "version": "0.273.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -4537,6 +4537,20 @@ const BANNED_APIS = [
     reason:
       "Web-only and opens widget-built bytes on the host origin; open a PDF with usePdfExport().openPdf.",
   },
+  ...["self", "top", "parent", "frames", "opener"].map((identifier) => ({
+    identifier,
+    reason:
+      "Another name for window. Refused where it reads a variable, so rename a local one; `insets.top` and `{ top: 0 }` are fine.",
+  })),
+  {
+    identifier: "frameElement",
+    reason: "The element framing the page, a route to the host document.",
+  },
+  {
+    identifier: ".constructor",
+    reason:
+      "Reaches Function(), which evaluates strings. Refused as a property read or quoted name; a class's own constructor() method is fine.",
+  },
 ];
 
 // REQ-WSDK-PLATFORM §3.4, §5: vetted package allowlist. Each entry is a
@@ -4939,6 +4953,12 @@ const TRANSLATION_API_HOSTS = [
   "lingvanex.com",
 ];
 
+// sc-12906: the host mints a widget's `X-Widget-Scopes` header, never the
+// widget. Bundles share the host's JS realm, so a widget calling the mint
+// itself, or forging the header, could borrow another widget's scopes. Matched
+// case-insensitively against code (comments are blanked before matching).
+const SCOPE_MINT_PATTERNS = ["/widgets/scope-token", "x-widget-scopes"];
+
 // sc-4686 — the currency a price renders in when the HOST does not supply the
 // workspace's own (a host predating the workspace.currency slice, or a caller
 // that forgot to wire it). A rendering fallback so a price is never blank or
@@ -6539,7 +6559,13 @@ const CONTRACT = deepFreeze({
   //    useDatastoreRecord, useDatastoreFigure and useDatastoreAggregate.
   // 1.221.0: additive (sc-14460) — `basicStyleSchema`, exported as
   //    `BASIC_STYLE_SCHEMA`, and `basicStyle(style)`, which applies it.
-  version: "1.221.0",
+  // 1.222.0: stricter (sc-14479) — `self`, `top`, `parent`, `frames`,
+  //    `opener`, `frameElement` and `.constructor` join bannedApis; `eval` and
+  //    `Function` are refused as any reference, not only as a call.
+  // 1.223.0: stricter (sc-12906) — `scopeMintPatterns`; a widget that calls
+  //    the scope-header mint or sets `X-Widget-Scopes` is refused
+  //    (`no-scope-header-mint`).
+  version: "1.223.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6584,6 +6610,7 @@ const CONTRACT = deepFreeze({
   currencyFormats: CURRENCY_FORMATS,
   currencyFormatFallback: CURRENCY_FORMAT_FALLBACK,
   translationApiHosts: TRANSLATION_API_HOSTS,
+  scopeMintPatterns: SCOPE_MINT_PATTERNS,
 });
 
 function isHookAllowed(name) {