@aglyn/aglyn 1.0.0-beta.211 → 1.0.0-beta.213

package/src/lib/app-utils/plugin-bundle-checks.d.ts

@@ -16,7 +16,7 @@
  */
 import type { PluginContributions } from '../plugin-manager/plugin-contributions';
 /** The areas the verifier reports on, in the order a reviewer reads them. */
-export type BundleCheckId = 'parse' | 'entry' | 'self-contained' | 'size' | 'code-execution' | 'globals' | 'storage' | 'dynamic-import' | 'network' | 'obfuscation' | 'contributions' | 'credentials';
+export type BundleCheckId = 'parse' | 'entry' | 'self-contained' | 'host-abi' | 'size' | 'code-execution' | 'globals' | 'storage' | 'dynamic-import' | 'network' | 'obfuscation' | 'contributions' | 'credentials';
 export interface BundleCheckProblem {
     level: 'error' | 'warning';
     message: string;
@@ -87,8 +87,9 @@ export declare const MAX_PLUGIN_BUNDLE_BYTES = 1000000;
  * 6 — registrations are compared with the declared contributions (AGL-3116).
  * 7 — inputs that collect a password, card or one-time code (AGL-3362).
  * 8 — declared network origins that are a brand's lookalike (AGL-3365).
+ * 9 — lookups on the host ABI name only keys a host provides (AGL-3392).
  */
-export declare const PLUGIN_VERIFIER_VERSION = 8;
+export declare const PLUGIN_VERIFIER_VERSION = 10;
 /** A verdict as stored on a `pluginVersions` doc (AGL-962). */
 export interface StoredBundleVerdict {
     ok?: boolean;

package/src/lib/app-utils/plugin-bundle-checks.js

@@ -38,10 +38,13 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
 // type, autocomplete token and raw HTML (AGL-3362).
 import { credentialForInputAttribute, credentialInHtml } from "@aglyn/shared-util-email/hosted-page-screen";
 import { lookalikeBrandForHost } from "@aglyn/shared-util-email/outbound-phishing-screen";
+import { PLUGIN_HOST_ABI_KEYS, PLUGIN_HOST_GLOBAL, PLUGIN_HOST_MODULE_KEYS } from "./plugin-host-abi.js";
+import { REALM_HOST_SURFACE_NAMES } from "./realm-host-surface.generated.js";
 const CHECK_LABELS = {
     parse: 'Parses as an ES module',
     entry: 'Exports an entry point',
     'self-contained': 'Self-contained (no static imports)',
+    'host-abi': 'Reads only what the host provides',
     size: 'Within the size limit',
     'code-execution': 'No eval / Function constructor',
     globals: 'No computed access on a global',
@@ -56,6 +59,7 @@ const CHECK_LABELS = {
     'parse',
     'entry',
     'self-contained',
+    'host-abi',
     'size',
     'code-execution',
     'globals',
@@ -85,7 +89,8 @@ export const MAX_PLUGIN_BUNDLE_BYTES = 1000000;
  * 6 — registrations are compared with the declared contributions (AGL-3116).
  * 7 — inputs that collect a password, card or one-time code (AGL-3362).
  * 8 — declared network origins that are a brand's lookalike (AGL-3365).
- */ export const PLUGIN_VERIFIER_VERSION = 8;
+ * 9 — lookups on the host ABI name only keys a host provides (AGL-3392).
+ */ export const PLUGIN_VERIFIER_VERSION = 10;
 /**
  * Whether a stored verdict may be served instead of re-running the checks.
  *
@@ -605,6 +610,207 @@ const BASE64_BLOB = /^[A-Za-z0-9+/\r\n]+={0,2}$/;
     }
     return messages;
 }
+/**
+ * Walks every expression-position node with its parent, by the same rules as
+ * {@link walk}.
+ */ function walkWithParents(root, visit) {
+    const stack = [
+        [
+            root,
+            null
+        ]
+    ];
+    while(stack.length){
+        const entry = stack.pop();
+        if (!entry) continue;
+        const [node, parent] = entry;
+        visit(node, parent);
+        for (const key of Object.keys(node)){
+            if (key === 'type' || key === 'start' || key === 'end') continue;
+            if (skippedChild(node, key)) continue;
+            const value = node[key];
+            const children = Array.isArray(value) ? value : [
+                value
+            ];
+            for (const child of children){
+                if (child && typeof child === 'object' && typeof child.type === 'string') {
+                    stack.push([
+                        child,
+                        node
+                    ]);
+                }
+            }
+        }
+    }
+}
+/**
+ * What a bundle reads from the host ABI (AGL-3392), read off the bytes.
+ *
+ * The realm Rollup configs compile each host import into
+ * `const host = globalThis.__AGLYN_PLUGIN_HOST__; … host["mui"]`, and each use
+ * of an import into a member read on that: `_aglynHost_mui.Button`. So:
+ *
+ * - `read` / `unknown` / `computed` are the KEYS a bundle reads off the host
+ *   object. A key outside `PLUGIN_HOST_ABI_KEYS` is undefined on every host
+ *   and the bundle fails where it is used; a key chosen at runtime cannot be
+ *   reviewed at all.
+ * - `imports` is what it reads from each host MODULE, by name, so each name
+ *   can be checked against what the host holds. A module handed around as a
+ *   value (`import * as M`, a spread, a computed read) cannot be narrowed and
+ *   records `'*'`.
+ *
+ * The host is reached through `globalThis.__AGLYN_PLUGIN_HOST__`, a name bound
+ * to it, or the parameter of the exported `register(host)` — the last only
+ * inside `register` itself, since the same name elsewhere is another variable.
+ * A bad key on that parameter is a warning rather than a refusal: bundles
+ * written before this check read it freely, and refusing them would report a
+ * regression on bytes that are already installed.
+ */ function hostAbiReads(program, constants, isGlobalRef) {
+    const parents = new Map();
+    const identifiers = new Map();
+    walkWithParents(program, (node, parent)=>{
+        parents.set(node, parent);
+        if (node.type === 'Identifier') {
+            const name = node['name'];
+            const list = identifiers.get(name);
+            if (list) list.push(node);
+            else identifiers.set(name, [
+                node
+            ]);
+        }
+    });
+    const within = (node, ancestor)=>{
+        for(let at = node; at; at = parents.get(at)){
+            if (at === ancestor) return true;
+        }
+        return false;
+    };
+    const isHostGlobal = (node)=>(node == null ? void 0 : node.type) === 'Identifier' && node['name'] === PLUGIN_HOST_GLOBAL || (node == null ? void 0 : node.type) === 'MemberExpression' && isGlobalRef(node['object']) && propertyName(node) === PLUGIN_HOST_GLOBAL;
+    // Names bound to the host object, each valid everywhere (`scope` null) or
+    // only inside one function (the `register(host)` parameter).
+    const hostNames = new Map();
+    walk(program, (node)=>{
+        var _node_id;
+        if (node.type === 'VariableDeclarator') {
+            const id = node['id'];
+            const init = node['init'];
+            const roots = (init == null ? void 0 : init.type) === 'LogicalExpression' ? [
+                init['left'],
+                init['right']
+            ] : [
+                init
+            ];
+            if ((id == null ? void 0 : id.type) === 'Identifier' && roots.some(isHostGlobal)) {
+                hostNames.set(id['name'], null);
+            }
+        }
+        if (node.type === 'FunctionDeclaration' && ((_node_id = node['id']) == null ? void 0 : _node_id['name']) === 'register') {
+            var _node_params;
+            const param = ((_node_params = node['params']) != null ? _node_params : [])[0];
+            if ((param == null ? void 0 : param.type) === 'Identifier' && !hostNames.has(param['name'])) {
+                hostNames.set(param['name'], node);
+            }
+        }
+    });
+    /** `'global'` for the host reached by name, `'param'` for `register(host)`. */ const hostRef = (node)=>{
+        if (isHostGlobal(node)) return 'global';
+        if ((node == null ? void 0 : node.type) !== 'Identifier') return null;
+        const name = node['name'];
+        if (!hostNames.has(name)) return null;
+        const scope = hostNames.get(name);
+        if (!scope) return 'global';
+        return within(node, scope) ? 'param' : null;
+    };
+    const modules = new Set(PLUGIN_HOST_MODULE_KEYS);
+    const allowed = new Set(PLUGIN_HOST_ABI_KEYS);
+    const read = new Set();
+    const unknown = new Set();
+    const unknownOnParam = new Set();
+    let computed = 0;
+    let computedOnParam = 0;
+    const names = new Map();
+    const whole = (key)=>{
+        names.set(key, '*');
+    };
+    const note = (key, name)=>{
+        if (name === null) return whole(key);
+        const current = names.get(key);
+        if (current === '*') return;
+        if (current) current.add(name);
+        else names.set(key, new Set([
+            name
+        ]));
+    };
+    const seenAliases = new Set();
+    /** Records how one reference to a lazy key's module is used. */ const useOf = (key, ref)=>{
+        const parent = parents.get(ref);
+        // A presence check reads no name from the module: `if (!h.aglyn) return`
+        // is how a bundle stays inert on a host without the key, and every
+        // example plugin does it.
+        if ((parent == null ? void 0 : parent.type) === 'UnaryExpression' && (parent['operator'] === '!' || parent['operator'] === 'typeof') || ((parent == null ? void 0 : parent.type) === 'IfStatement' || (parent == null ? void 0 : parent.type) === 'ConditionalExpression') && parent['test'] === ref) {
+            return;
+        }
+        if ((parent == null ? void 0 : parent.type) === 'MemberExpression' && parent['object'] === ref) {
+            return note(key, propertyName(parent, constants));
+        }
+        if ((parent == null ? void 0 : parent.type) === 'VariableDeclarator' && parent['init'] === ref) {
+            const id = parent['id'];
+            if ((id == null ? void 0 : id.type) === 'Identifier') {
+                var _identifiers_get;
+                const alias = id['name'];
+                if (seenAliases.has(alias)) return;
+                seenAliases.add(alias);
+                for (const use of (_identifiers_get = identifiers.get(alias)) != null ? _identifiers_get : []){
+                    if (use !== id) useOf(key, use);
+                }
+                return;
+            }
+            if ((id == null ? void 0 : id.type) === 'ObjectPattern') {
+                var _id_properties;
+                for (const property of (_id_properties = id['properties']) != null ? _id_properties : []){
+                    if (property.type !== 'Property' || property['computed']) {
+                        return whole(key);
+                    }
+                    const propertyKey = property['key'];
+                    const name = (propertyKey == null ? void 0 : propertyKey.type) === 'Identifier' ? propertyKey['name'] : staticString(propertyKey);
+                    note(key, name);
+                }
+                return;
+            }
+        }
+        whole(key);
+    };
+    walk(program, (node)=>{
+        if (node.type !== 'MemberExpression') return;
+        const via = hostRef(node['object']);
+        if (!via) return;
+        const key = propertyName(node, constants);
+        if (key === null) {
+            if (via === 'param') computedOnParam += 1;
+            else computed += 1;
+        } else if (!allowed.has(key)) {
+            ;
+            (via === 'param' ? unknownOnParam : unknown).add(key);
+        } else {
+            read.add(key);
+            if (modules.has(key)) useOf(key, node);
+        }
+    });
+    const imports = {};
+    for (const [key, value] of names){
+        imports[key] = value === '*' ? '*' : [
+            ...value
+        ].sort();
+    }
+    return {
+        read,
+        unknown,
+        unknownOnParam,
+        computed,
+        computedOnParam,
+        imports
+    };
+}
 function analyseBundle(source, options) {
     var _ref;
     const problems = [];
@@ -645,7 +851,7 @@ function analyseBundle(source, options) {
     details.set('size', `${bytes.toLocaleString('en-US')} bytes of ${maxBytes.toLocaleString('en-US')}`);
     if (bytes === 0) {
         add('error', 'size', 'bundle is empty');
-        unknownFrom('parse', 'entry', 'self-contained', 'code-execution', 'globals', 'storage', 'dynamic-import', 'network', 'obfuscation', 'contributions', 'credentials');
+        unknownFrom('parse', 'entry', 'self-contained', 'host-abi', 'code-execution', 'globals', 'storage', 'dynamic-import', 'network', 'obfuscation', 'contributions', 'credentials');
         return {
             ok: false,
             problems,
@@ -674,7 +880,7 @@ function analyseBundle(source, options) {
         // Nothing else ran, and saying so is the whole point of `unknown`: a
         // bundle nobody could read must not show nine green rows.
         add('error', 'parse', `bundle does not parse as an ES module: ${error instanceof Error ? error.message : String(error)}`);
-        unknownFrom('entry', 'self-contained', 'code-execution', 'globals', 'storage', 'dynamic-import', 'network', 'obfuscation', 'contributions', 'credentials');
+        unknownFrom('entry', 'self-contained', 'host-abi', 'code-execution', 'globals', 'storage', 'dynamic-import', 'network', 'obfuscation', 'contributions', 'credentials');
         return {
             ok: false,
             problems,
@@ -1041,6 +1247,39 @@ function analyseBundle(source, options) {
             runtimeUrls ? `${runtimeUrls} call(s) with a URL only known at runtime` : ''
         ].filter(Boolean).join(' · '));
     }
+    const abi = hostAbiReads(program, constants, isGlobalRef);
+    for (const key of abi.unknown){
+        add('error', 'host-abi', `bundle reads "${key}" from the host, which provides only ` + `${PLUGIN_HOST_ABI_KEYS.join(', ')} — it would be undefined on every site`);
+    }
+    for (const key of abi.unknownOnParam){
+        add('warning', 'host-abi', `register() reads "${key}" from its host argument, which provides only ` + `${PLUGIN_HOST_ABI_KEYS.join(', ')} — it will be undefined`);
+    }
+    if (abi.computedOnParam) {
+        add('warning', 'host-abi', `register() reads its host argument by a key chosen at runtime ` + `(${abi.computedOnParam}×)`);
+    }
+    if (abi.computed) {
+        add('error', 'host-abi', `bundle reads the host by a key chosen at runtime (${abi.computed}×) — ` + 'a lookup that cannot be named cannot be reviewed');
+    }
+    // Each name the bundle reads from a host module must be one the host holds
+    // (AGL-3392): core's realm plugin surface, or the whole of the others.
+    for (const key of PLUGIN_HOST_MODULE_KEYS){
+        const read = abi.imports[key];
+        if (!read) continue;
+        const holds = REALM_HOST_SURFACE_NAMES[key];
+        if (read === '*') {
+            if (key === 'aglyn') {
+                add('warning', 'host-abi', 'uses @aglyn/aglyn as a namespace value — only the realm plugin ' + 'surface is on the host, so any other name read through it is ' + 'undefined; import what you use by name');
+            }
+            continue;
+        }
+        const missing = read.filter((name)=>!holds.has(name));
+        if (missing.length) {
+            add('error', 'host-abi', `reads ${missing.join(', ')} from the host's ${key}, which does not ` + `hold ${missing.length === 1 ? 'it' : 'them'}` + (key === 'aglyn' ? ' — only the realm plugin surface of @aglyn/aglyn is on the host' : ''));
+        }
+    }
+    details.set('host-abi', abi.read.size ? `reads ${[
+        ...abi.read
+    ].sort().join(', ')}` : 'reads nothing by name');
     const detected = detectRegistrations(program, constants);
     for (const message of credentialInputsIn(program, constants)){
         add('warning', 'credentials', message);