@jini-ai/core 0.6.10 → 0.6.11

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @jini-ai/core
 
+## 0.6.11
+
+### Patch Changes
+
+- OAuth accepts a parent protected-resource identifier and forwards the refresh resource; settings definitions are filtered; scope selectors are never id shorthand; secret-named URL parameters are masked by default in redaction.
+- Tool inputs apply a sole near-miss and declared input aliases; plugin-load outcomes are reported; `web_fetch` reads SVG/JS as text; `content_read` suggests its resource first; the browser falls back to system Chrome.
+
 ## 0.6.10
 
 ### Patch Changes

package/dist/redact.js

@@ -181,7 +181,8 @@ function isLuhnValid(digits) {
 // correlation ID uses uppercase hex and is meant to reach the model and be quoted to an
 // operator; delegated-tool-calls is the route segment named in delegated tool failures.
 // Matching the ENTIRE run keeps a secret glued onto either spelling redactable.
-export const LABELED_SECRET_RE = /\b(authorization|bearer|api[-_]?key|access[-_]?token|refresh[-_]?token|client[-_]?secret|password|secret|cookie)\b\s*[:=]\s*\S+/gi;
+const SECRET_LABELS = 'authorization|bearer|api[-_]?key|access[-_]?token|refresh[-_]?token|client[-_]?secret|password|secret|cookie';
+export const LABELED_SECRET_RE = new RegExp(`\\b(${SECRET_LABELS})\\b\\s*[:=]\\s*\\S+`, 'gi');
 export const OPAQUE_TOKEN_RE = /[A-Za-z0-9_-]{20,}/g;
 export const NON_SECRET_TOKEN_RE = /^(?:ERR-[0-9A-F]{4}(?:-[0-9A-F]{4}){3}|delegated-tool-calls|[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)$/;
 // Runtime markers must survive a second pass; the bounded sanitizer deliberately retains
@@ -198,6 +199,15 @@ const PROVIDER_API_KEY_QUERY = /([?&]key=)([^&\s]+)/gi;
 // readable for debugging without exposing credentials that authorize access to the resource.
 const URL_CREDENTIALS_RE = /(\b[a-z][a-z0-9+.-]*:\/\/)([^/\s?#@]+)@/gi;
 const SIGNED_QUERY_RE = /([?&](?:signature|sig|x-amz-signature|x-goog-signature|access_token|refresh_token)=)([^&#\s,;"']+)/gi;
+// A secret word must END a name segment (split at . _ - or the name's end): api_key, apiKey,
+// authtoken, X-Amz-Signature and custom.Token-value are masked, while author, keyword, design,
+// signup and page stay readable. Names that merely end in a secret word (zipcode, error_code,
+// monkey) are masked too; over-masking a URL value is the cheaper failure. Empty values stay.
+// Match through a trailing fragment; only '&', quotes, parentheses or whitespace end the value.
+// Both name runs are bounded so a long separator-free run costs linear time, not quadratic.
+const URL_SECRET_PARAM_RE = /[?&#;]([\w.-]{0,128}?(?:token|key|secret|signature|sig|code|password|passwd|pwd|auth|authorization|credential)s?(?=[._=-])[\w.-]{0,128})=[^&\s"'<>()]+/gi;
+// A parameter the labeled rule already names (password, client_secret, ...) keeps that category.
+const LABELED_URL_PARAM_NAME_RE = new RegExp(`(?:^|[.-])(?:${SECRET_LABELS})$`, 'i');
 // Only an entire marker is already masked. A secret glued onto marker-like text still needs
 // masking; a substring check would preserve credential suffixes in echoed header/query values.
 function isMaskedValue(value) {
@@ -301,6 +311,9 @@ function redactKeyedCredentials({ text, marker }) {
     out = out.replace(API_KEY_QUERY, (match, prefix) => isMaskedValue(match.slice(prefix.length)) ? match : `${prefix}${marker('api_key_query')}`);
     out = out.replace(SHORT_BEARER_RE, () => marker('bearer_token'));
     out = out.replace(PROVIDER_API_KEY_HEADER, (match, name, value) => isMaskedValue(value) ? match : `${name}: ${marker('api_key_header')}`);
+    // Sweep other URL parameters before the general labeled rule can consume harmless
+    // neighboring parameters (`password=x&page=2` used to lose `&page=2`).
+    out = redactUrlSecretParams({ text: out, marker });
     return out.replace(MASK_AWARE_LABELED_SECRET_RE, (match, _label, value) => {
         // Replace only the captured value, retaining labels even when no whitespace separates
         // them. Glued credential suffixes fail the complete-marker check and remain maskable.
@@ -309,6 +322,16 @@ function redactKeyedCredentials({ text, marker }) {
         return `${match.slice(0, -value.length)}${marker('labeled_secret')}`;
     });
 }
+/** Secret-named URL query/fragment values; values already masked above keep their category. */
+function redactUrlSecretParams({ text, marker }) {
+    return text.replace(URL_SECRET_PARAM_RE, (match, name) => {
+        const separator = match.indexOf('=') + 1;
+        if (isMaskedValue(match.slice(separator)))
+            return match;
+        const category = LABELED_URL_PARAM_NAME_RE.test(name) ? 'labeled_secret' : 'url_secret_param';
+        return `${match.slice(0, separator)}${marker(category)}`;
+    });
+}
 /** Email/IPv4/phone rules, then Luhn-checked card candidates. */
 function redactPii({ text, marker }) {
     return applyPatterns({ text, marker, patterns: PII_PATTERNS }).replace(CARD_CANDIDATE, (match) => {

package/dist/settings/agent-tools.js

@@ -49,13 +49,16 @@ import { AGENT_WRITABLE_PREFERENCE_IDS, AGENT_WRITABLE_PREFERENCES } from "./age
    * write entries this file documents but never wires (see file header) carry no schema at all,
    * since one is never published for a tool the model never sees.
    *
- * No arguments — `settings_list_definitions` takes none; it always enumerates the caller's own
- * (boot-wired) workspace's site-owned partition plus the shared platform partition. */
-const NO_INPUT_SCHEMA = {
+ * Optional filters narrow the caller's own (boot-wired) workspace's site-owned partition plus
+ * the shared platform partition; they never select a different workspace. */
+const LIST_DEFINITIONS_SCHEMA = {
     type: "object",
     additionalProperties: false,
     required: [],
-    properties: {},
+    properties: {
+        search: { type: "string", description: "Case-insensitive text filter over the full 'namespace.key' name." },
+        namespace: { type: "string", description: "Only definitions in this exact namespace." },
+    },
 };
 /** Shared by `settings_get_effective`/`settings_get_raw`: naming a DIFFERENT principal than the
  * caller requires `settings.user.read` (checked by the handler, not expressed in this schema). */
@@ -138,10 +141,10 @@ export function getSettingsAgentToolCatalog() {
     return [
         {
             name: "settings_list_definitions",
-            description: "Lists every active setting definition visible to this workspace (platform core/theme definitions plus this workspace's own site-owned definitions): namespace, key, owner kind, scope bitmask, status, version, schema, agentWritable and confirmationRequired. Use before writing a setting. Metadata only — never a value.",
+            description: "Lists active setting definitions visible to this workspace (platform core/theme definitions plus this workspace's own site-owned definitions), optionally filtered by search text and exact namespace: namespace, key, owner kind, scope bitmask, status, version, schema, agentWritable and confirmationRequired. Use before writing a setting. Metadata only — never a value.",
             sideEffects: "none",
             authorization: { permission: "settings.read.definitions" },
-            inputSchema: NO_INPUT_SCHEMA,
+            inputSchema: LIST_DEFINITIONS_SCHEMA,
         },
         {
             name: "settings_get_effective",

package/dist/settings/tool-registrations.js

@@ -1,7 +1,7 @@
 import { adaptLegacyAuthorize } from "../tool-permissions.js";
 import { agentWriteRules, buildSettingsValueWriteHandler, toWriteDeps } from "./agent-value-write-tools.js";
 import { findAgentWriteRule } from "./agent-write-denylist.js";
-import { buildDomainRegistrations, indexCatalogById, optionalString, requireInputRecord, requireNoInput, requireString, withSchemaOnRejection } from "../registration-kit.js";
+import { buildDomainRegistrations, indexCatalogById, optionalString, requireInputRecord, requireString, withSchemaOnRejection } from "../registration-kit.js";
 import { ToolInputError } from "../tool-registry.js";
 import { requireToolPermission } from "../tool-permissions.js";
 import { getSettingsAgentToolCatalog } from "./agent-tools.js";
@@ -140,15 +140,21 @@ export function buildSettingsRegistrations(routeDeps) {
         settings_set_value: buildSettingsValueWriteHandler(routeDeps, "settings_set_value"),
         settings_clear_value: buildSettingsValueWriteHandler(routeDeps, "settings_clear_value"),
         settings_list_definitions: async (ctx) => {
-            requireNoInput({ input: ctx.input });
+            const input = requireInputRecord({ input: ctx.input === undefined ? {} : ctx.input });
+            const search = optionalString({ input, key: "search" })?.toLowerCase();
+            const namespace = optionalString({ input, key: "namespace" });
             await routeDeps.settingsReady;
             await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: routeDeps.authorize }), workspaceId: routeDeps.workspaceId, principalId: ctx.principal.id, permission: "settings.read.definitions" }, { entityType: "setting-definition" });
             const [platformDefs, siteDefs] = await Promise.all([
                 routeDeps.settingsRepo.listActiveDefinitions({ workspaceId: null }),
                 routeDeps.settingsRepo.listActiveDefinitions({ workspaceId: routeDeps.workspaceId }),
             ]);
+            // Filter only authorized workspace rows, before alias lookups; never search stored values.
+            const definitions = [...platformDefs, ...siteDefs]
+                .filter((def) => namespace === undefined || def.namespace === namespace)
+                .filter((def) => !search || `${def.namespace}.${def.key}`.toLowerCase().includes(search));
             const rules = agentWriteRules(routeDeps);
-            const data = (await Promise.all([...platformDefs, ...siteDefs].map((def) => describeDefinitionForAgent(routeDeps, rules, def))))
+            const data = (await Promise.all(definitions.map((def) => describeDefinitionForAgent(routeDeps, rules, def))))
                 .sort((a, b) => a.namespace.localeCompare(b.namespace) || a.key.localeCompare(b.key));
             return { data };
         },

package/dist/tool-input-normalization.d.ts

@@ -8,8 +8,8 @@ export interface NormalizedToolInput {
 export type ToolInputNormalizer = (required: {
     input: Readonly<Record<string, unknown>>;
 }, optional?: Record<string, never>) => NormalizedToolInput | Promise<NormalizedToolInput>;
-/** Canonicalize one batch layer before merging; preserve values and domain aliases for the
- * final normalization. Throws ToolInputError for collisions within this layer, never across
+/** Canonicalize one batch layer (including declared aliases) before merging; leave value conversion
+ * and domain hooks for final normalization. Throws ToolInputError for collisions within this layer, never across
  * layers. Uses the same bounded schema walk as normalizeToolInput.
  * @example canonicalizeToolInputKeys({ input: { max_chars: '1000' }, schema });
  */
@@ -20,7 +20,8 @@ export declare function canonicalizeToolInputKeys({ input, schema }: {
     input: Record<string, unknown>;
     notes: readonly string[];
 };
-/** Normalize before policy, confirmation and handler validation. Domain hooks own semantic aliases.
+/** Normalize before policy, confirmation and handler validation. Schema properties may declare
+ * `aliases: ['search', 'query']`; domain hooks own transformations beyond declared key aliases.
  * Never changes the caller's object or includes values in notes. Invalid/ambiguous input remains
  * a ToolInputError; ordinary domain/schema validation still belongs to the registered handler.
  * @complexity Two bounded schema walks plus the optional domain hook's cost.

package/dist/tool-input-normalization.js

@@ -15,11 +15,16 @@ function sameLengthNearMiss({ left, right, index }) {
     return left.slice(index + 1) === right.slice(index + 1)
         || (left[index] === right[index + 1] && left[index + 1] === right[index] && left.slice(index + 2) === right.slice(index + 2));
 }
-/** Whether either key is the generic id shorthand for the other's id suffix; hints only. */
+/** Scope selectors name a container, never the resource: guessing `workspaceId` as `id` (or the
+ * reverse) would silently drop or invent a scope. Only a declared name or alias may accept one. */
+const SCOPE_SELECTORS = new Set(['workspaceid', 'siteid']);
+/** Whether either key is the generic id shorthand for the other's id suffix; never for a scope selector. */
 function isIdShorthand({ left, right }, _options = {}) {
+    if (SCOPE_SELECTORS.has(left) || SCOPE_SELECTORS.has(right))
+        return false;
     return (left === 'id' && right.endsWith('id')) || (right === 'id' && left.endsWith('id'));
 }
-/** Detect id shorthand or one insertion, deletion, substitution or transposition, for hints only. */
+/** Detect id shorthand or one insertion, deletion, substitution or transposition. */
 function nearMiss({ left, right }, _options = {}) {
     if (left.length > 128 || right.length > 128)
         return false;
@@ -53,6 +58,19 @@ function coerceString({ value, types, path, notes }) {
     }
     return coerceNumber({ value, types, path, notes });
 }
+/** Unwrap only a singleton string array; refuse malformed arrays without exposing values.
+ * Keys-only batch layers preserve values until the final merged input is normalized.
+ * @complexity O(t) time for t allowed schema types, O(1) space; array contents are not scanned.
+ */
+function unwrapStringArray({ value, types, step }) {
+    if (step.walk.keysOnly || !Array.isArray(value) || !types.includes('string'))
+        return value;
+    if (value.length !== 1 || typeof value[0] !== 'string') {
+        throw new ToolInputError({ message: `${step.path}: send one value as a string or a one-element string array.` });
+    }
+    step.walk.notes.push(`${step.path}: one-item string array→string`);
+    return value[0];
+}
 function normalizeArray({ value, schema, step }) {
     const { path, depth, walk } = step;
     let list = value;
@@ -65,12 +83,30 @@ function normalizeArray({ value, schema, step }) {
         return list;
     return list.map((item, index) => normalizeValue({ value: item, schema: schema.items, step: { path: `${path}[${index}]`, depth: depth + 1, walk } }));
 }
-/** The declared property a supplied key names, or undefined; refuses a key that names two. */
+/** Match a canonical spelling or its property's declared string aliases, ignoring case/separators.
+ * Malformed alias annotations confer no alternate names; exact property names still win.
+ * @complexity O(a) comparisons for a aliases on this property; no input mutation or effects.
+ */
+function matchesDeclaredKey({ key, name, schema }, _options = {}) {
+    if (keyShape(name) === keyShape(key))
+        return true;
+    if (!object(schema) || !Array.isArray(schema.aliases))
+        return false;
+    return schema.aliases.some(alias => typeof alias === 'string' && keyShape(alias) === keyShape(key));
+}
+/** Exact names, then case/separator variants and declared aliases, then a sole hint; ambiguous hints stay unresolved
+ * for the domain hook or closed-schema refusal. Never choose one of several candidates.
+ * Hints apply only where a closed schema would refuse the key: an open schema accepts it as data.
+ * @complexity O(p + a) comparisons for p properties and a declared aliases; O(p) space.
+ */
 function canonicalKey({ key, location, shape }) {
-    const candidates = Object.hasOwn(shape.properties, key) ? [key] : shape.names.filter(name => keyShape(name) === keyShape(key));
+    const candidates = Object.hasOwn(shape.properties, key) ? [key] : shape.names.filter(name => matchesDeclaredKey({ key, name, schema: shape.properties[name] }));
     if (candidates.length > 1)
         throw new ToolInputError({ message: `Ambiguous input '${location}': matches ${candidates.join(', ')}. Use exactly one canonical property name.` });
-    return candidates[0];
+    if (candidates.length === 1 || shape.schema.additionalProperties !== false)
+        return candidates[0];
+    const hints = shape.names.filter(name => nearMiss({ left: keyShape(key), right: keyShape(name) }));
+    return hints.length === 1 ? hints[0] : undefined;
 }
 /** Describe the local schema and likely names without choosing a name or exposing input values.
  * Target and permission fields must be declared in the tool schema before callers can use them.
@@ -111,7 +147,7 @@ function normalizeObject({ value, schema, step }) {
     return Object.fromEntries(Object.entries(value).map(([key, raw]) => normalizeEntry({ key, raw, shape, sources, step })));
 }
 /** Schema-guided copies only: unconstrained data and unsupported schema dialects stay untouched.
- * Cost is O(k*p) per object with k supplied keys and p schema properties; recursion is bounded
+ * Cost is O(k*(p+a)) comparisons per object with k supplied keys, p properties and a aliases; recursion is bounded
  * to 64 levels so a hostile input/schema cannot exhaust the execution gate's stack.
  */
 function normalizeValue({ value, schema, step }) {
@@ -126,14 +162,15 @@ function normalizeValue({ value, schema, step }) {
     }
     if (types.includes('array'))
         return normalizeArray({ value, schema, step });
-    return object(value) ? normalizeObject({ value, schema, step }) : value;
+    const unwrapped = unwrapStringArray({ value, types, step });
+    return object(unwrapped) ? normalizeObject({ value: unwrapped, schema, step }) : unwrapped;
 }
 /** A walk from the root of one input. */
 function walkRoot({ input, schema, notes, validateClosed, keysOnly }) {
     return normalizeValue({ value: input, schema, step: { path: '', depth: 0, walk: { notes, validateClosed, keysOnly } } });
 }
-/** Canonicalize one batch layer before merging; preserve values and domain aliases for the
- * final normalization. Throws ToolInputError for collisions within this layer, never across
+/** Canonicalize one batch layer (including declared aliases) before merging; leave value conversion
+ * and domain hooks for final normalization. Throws ToolInputError for collisions within this layer, never across
  * layers. Uses the same bounded schema walk as normalizeToolInput.
  * @example canonicalizeToolInputKeys({ input: { max_chars: '1000' }, schema });
  */
@@ -141,7 +178,8 @@ export function canonicalizeToolInputKeys({ input, schema }, _options = {}) {
     const notes = [];
     return { input: walkRoot({ input, schema, notes, validateClosed: false, keysOnly: true }), notes };
 }
-/** Normalize before policy, confirmation and handler validation. Domain hooks own semantic aliases.
+/** Normalize before policy, confirmation and handler validation. Schema properties may declare
+ * `aliases: ['search', 'query']`; domain hooks own transformations beyond declared key aliases.
  * Never changes the caller's object or includes values in notes. Invalid/ambiguous input remains
  * a ToolInputError; ordinary domain/schema validation still belongs to the registered handler.
  * @complexity Two bounded schema walks plus the optional domain hook's cost.

package/dist/tool-registry.d.ts

@@ -46,6 +46,9 @@ export interface ToolDescriptor {
      * JSON-Schema-shaped description of this tool's accepted input, carried as `unknown` because the
      * gate reads common property/type fields for input normalization but leaves validation and
      * schema dialects to the handler; no validator dependency belongs in every registry consumer.
+     * Each property may declare `aliases: readonly string[]` (e.g. contains: { type: 'string',
+     * aliases: ['search', 'query'] }). The gate treats these like case variants, rejects ambiguous
+     * or conflicting names, and reports the rename in normalization notes.
      *
      * It exists because *every* discovery mechanism needs it and nothing else in the kernel can
      * supply it: a caller that can enumerate `ToolRegistry.list({})` still cannot tell an agent what

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/core",
-  "version": "0.6.10",
+  "version": "0.6.11",
   "description": "The Jini kernel: typed DI tokens, pack composition and lifecycle, the tool registry, redaction, and origin/API-token auth primitives. Zero dependencies.",
   "license": "Apache-2.0",
   "repository": {