@minionry/minion 0.7.36

package/dist/server/services/sdk/composer.js

@@ -0,0 +1,129 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { ModelProfileStore, profileModelValue, } from '../../engines/credentials/model-profiles.js';
+import { CLAUDE_MODEL_PRESETS, CODEX_MODEL_PRESETS, ENGINE_EFFORT_LEVELS, ENGINE_IDS, engineForModel, } from '../../engines/types.js';
+import { peekModelCatalog } from '../model-catalog.js';
+import { getEffortLevel, getEngine, getFastMode, getModel } from '../settings.js';
+import { collectAllSkills } from '../websocket/skill-handlers.js';
+import { rankAllSnippets, rankQuerySnippets } from '../websocket/snippet-handlers.js';
+import { isAppOwnedProfile } from './app-endpoints.js';
+import { inferenceEngines } from './inference.js';
+import { SdkMethodError } from './registry.js';
+let composerHost = null;
+export function setSdkComposerHost(host) {
+    composerHost = host;
+}
+export function resetSdkComposerHost() {
+    composerHost = null;
+}
+function requireHost() {
+    if (!composerHost) {
+        throw new SdkMethodError('INTERNAL', 'composer host is not wired — the WebSocket handler installs it at startup');
+    }
+    return composerHost;
+}
+function paramsObject(params) {
+    return typeof params === 'object' && params !== null && !Array.isArray(params) ? params : {};
+}
+export function composerAutocompleteHandler(args) {
+    const raw = paramsObject(args.params);
+    if (typeof raw.query !== 'string') {
+        throw new SdkMethodError('BAD_REQUEST', 'composer.autocomplete requires params { query }');
+    }
+    return requireHost().autocomplete(args.workingDir, raw.query);
+}
+export function composerSkillsHandler(args) {
+    return collectAllSkills(args.workingDir);
+}
+export function composerSnippetsHandler(args) {
+    const raw = paramsObject(args.params);
+    if (raw.query !== undefined && typeof raw.query !== 'string') {
+        throw new SdkMethodError('BAD_REQUEST', 'composer.snippets query must be a string when present');
+    }
+    const query = typeof raw.query === 'string' ? raw.query.trim() : '';
+    const all = requireHost().snippets();
+    const ranked = query.length === 0 ? rankAllSnippets(all) : rankQuerySnippets(all, query);
+    return ranked.map(({ name, aliases, description, origin, preview, bodyLength }) => ({
+        name,
+        aliases,
+        description,
+        origin,
+        preview,
+        bodyLength,
+    }));
+}
+function presetRow(preset, engine) {
+    return {
+        value: preset.value,
+        engine,
+        label: preset.label,
+        description: preset.description,
+        ...(preset.isDefault ? { isDefault: true } : {}),
+    };
+}
+function customProfileRows() {
+    try {
+        return new ModelProfileStore()
+            .list()
+            .filter((profile) => !isAppOwnedProfile(profile))
+            .map((profile) => ({
+            value: profileModelValue(profile),
+            engine: profile.engine,
+            label: profile.label,
+            description: profile.model,
+            ...(profile.contextLength !== undefined ? { contextLength: profile.contextLength } : {}),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+function catalogRow(row) {
+    return {
+        value: row.value,
+        engine: engineForModel(row.value),
+        label: row.label,
+        ...(row.description !== undefined ? { description: row.description } : {}),
+        ...(row.isDefault ? { isDefault: true } : {}),
+        ...(row.contextLength !== undefined ? { contextLength: row.contextLength } : {}),
+    };
+}
+function buildModelCatalog() {
+    const models = [
+        ...CLAUDE_MODEL_PRESETS.map((preset) => presetRow(preset, 'claude-code')),
+        ...CODEX_MODEL_PRESETS.map((preset) => presetRow(preset, 'codex')),
+        ...customProfileRows(),
+    ];
+    const payload = peekModelCatalog();
+    const seen = new Set(models.map((model) => model.value));
+    for (const row of [
+        ...(payload.hermes?.nous ?? []),
+        ...(payload.hermes?.openrouter ?? []),
+        ...(payload.openrouter?.models ?? []),
+    ]) {
+        if (seen.has(row.value))
+            continue;
+        seen.add(row.value);
+        models.push(catalogRow(row));
+    }
+    return {
+        models,
+        status: { fetchedAt: payload.fetchedAt, stale: payload.stale, refreshing: payload.refreshing },
+    };
+}
+export function composerSettingsHandler(_args) {
+    const catalog = buildModelCatalog();
+    return {
+        engines: [...ENGINE_IDS],
+        defaults: {
+            engine: getEngine(),
+            model: getModel(),
+            effortLevel: getEffortLevel(),
+            fastMode: getFastMode(),
+        },
+        models: catalog.models,
+        modelsStatus: catalog.status,
+        effortLevels: Object.fromEntries(ENGINE_IDS.map((engine) => [engine, [...ENGINE_EFFORT_LEVELS[engine]]])),
+        inferenceEngines: inferenceEngines(),
+    };
+}

package/dist/server/services/sdk/connect.js

@@ -0,0 +1,273 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { randomUUID } from 'node:crypto';
+import { basename } from 'node:path';
+import { isScope } from '@minionry/app-manifest';
+import { can, RANK } from '@minionry/roles';
+import { getCredentials } from '../platform-credentials.js';
+import { logAppAudit } from './audit.js';
+import { checkConsentCooldown, recordConsentApproval, recordConsentDismissal, } from './consent-cooldown.js';
+import { computeScopeDelta, getGrant, getSessionGrant, setGrant, setSessionGrant, } from './grant-store.js';
+import { isLocalhostFamilyOrigin } from './local-app-bindings.js';
+import { deriveSpaceId, SdkMethodError } from './registry.js';
+import { isValidAppId } from './sandbox.js';
+export const VIEWER_GRANTABLE_SCOPES = new Set([
+    'identity',
+    'pm:read',
+    'files:workspace:read',
+    'settings:read',
+    'quality:read',
+]);
+export function canPersistGrants(role) {
+    return (RANK[role] ?? 0) > RANK.viewer;
+}
+export const CONSENT_TIMEOUT_MS = 5 * 60 * 1000;
+let consentTimeoutOverrideMs;
+export function setSdkConsentTimeoutMsForTests(ms) {
+    consentTimeoutOverrideMs = ms;
+}
+const pendingConsents = new Map();
+function registerPendingConsent(consentId, accept) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            if (pendingConsents.delete(consentId))
+                resolve({ outcome: 'timeout' });
+        }, consentTimeoutOverrideMs ?? CONSENT_TIMEOUT_MS);
+        pendingConsents.set(consentId, { consentId, accept, resolve, timer });
+    });
+}
+function responderAllowed(accept, responder) {
+    if (accept.kind === 'requester') {
+        return accept.viewerId === responder.viewerId ? null : 'wrong-viewer';
+    }
+    if (responder.viewerId === undefined || !accept.viewerIds.has(responder.viewerId)) {
+        return 'wrong-viewer';
+    }
+    return can(responder.role, 'editSettings') ? null : 'wrong-role';
+}
+export function resolveSdkConsent(consentId, decision, responder) {
+    const entry = pendingConsents.get(consentId);
+    if (!entry)
+        return 'unknown-consent';
+    const refusal = responderAllowed(entry.accept, responder);
+    if (refusal)
+        return refusal;
+    pendingConsents.delete(consentId);
+    clearTimeout(entry.timer);
+    if (decision.approved) {
+        entry.resolve({
+            outcome: 'approved',
+            granted: decision.granted.filter(isScope),
+            remember: decision.remember === true,
+            responder,
+        });
+    }
+    else {
+        entry.resolve({ outcome: 'denied' });
+    }
+    return 'resolved';
+}
+export function pendingSdkConsentCount() {
+    return pendingConsents.size;
+}
+export function clearAllPendingSdkConsents() {
+    for (const entry of pendingConsents.values()) {
+        clearTimeout(entry.timer);
+        entry.resolve({ outcome: 'denied' });
+    }
+    pendingConsents.clear();
+}
+function parsePinnedManifest(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const raw = value;
+    if (typeof raw.hash !== 'string' || raw.hash === '')
+        return null;
+    if (!Array.isArray(raw.scopes))
+        return null;
+    const optional = raw.optionalScopes === undefined ? [] : raw.optionalScopes;
+    if (!Array.isArray(optional))
+        return null;
+    return {
+        hash: raw.hash,
+        scopes: raw.scopes.filter(isScope),
+        optionalScopes: optional.filter(isScope),
+    };
+}
+function parseRequestedScopes(params) {
+    if (params === undefined || params === null)
+        return [];
+    if (typeof params !== 'object' || Array.isArray(params))
+        return null;
+    const raw = params.scopes;
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw) || !raw.every((scope) => typeof scope === 'string')) {
+        return null;
+    }
+    return [...new Set(raw)];
+}
+function hashBoundScopes(grant, manifestHash) {
+    return grant && grant.manifestHash === manifestHash ? grant.scopes : [];
+}
+function connectResult(args) {
+    const persisted = getGrant(args.appId, args.spaceKey);
+    const session = args.viewerId
+        ? getSessionGrant(args.viewerId, args.appId, args.spaceKey)
+        : undefined;
+    const grants = [...new Set([...(persisted?.scopes ?? []), ...(session?.scopes ?? [])])];
+    let user = null;
+    if (args.role !== 'viewer') {
+        const creds = getCredentials();
+        if (creds)
+            user = { id: creds.userId, name: creds.name ?? creds.email, role: args.role };
+    }
+    return {
+        space: { id: deriveSpaceId(args.spaceKey), name: basename(args.workingDir) },
+        user,
+        grants,
+        viewOnly: !can(args.role, 'execute'),
+    };
+}
+function applyApprovedConsent(args, manifest, onCard, outcome) {
+    const { appId, origin, spaceKey, viewerId } = args;
+    const { responder } = outcome;
+    let granted = onCard.filter((scope) => outcome.granted.includes(scope));
+    if (responder.role === 'viewer') {
+        granted = granted.filter((scope) => VIEWER_GRANTABLE_SCOPES.has(scope));
+    }
+    if (granted.length === 0)
+        return;
+    const persist = outcome.remember &&
+        canPersistGrants(responder.role) &&
+        (!isLocalhostFamilyOrigin(origin) || args.verifiedLocalBinding === true);
+    if (persist) {
+        const base = hashBoundScopes(getGrant(appId, spaceKey), manifest.hash);
+        const grant = setGrant({
+            appId,
+            spaceKey,
+            origin,
+            scopes: [...new Set([...base, ...granted])],
+            manifestHash: manifest.hash,
+            ...(args.verifiedLocalBinding === true ? { verifiedLocalBinding: true } : {}),
+        });
+        args.notify?.({
+            type: 'sdkGrantsChanged',
+            data: { appId, grants: [...grant.scopes] },
+            broadcast: true,
+        });
+        return;
+    }
+    if (!viewerId) {
+        throw new SdkMethodError('INTERNAL', 'no viewer identity — a session-scoped grant cannot be stored');
+    }
+    const base = hashBoundScopes(getSessionGrant(viewerId, appId, spaceKey), manifest.hash);
+    const grant = setSessionGrant(viewerId, {
+        appId,
+        spaceKey,
+        origin,
+        scopes: [...new Set([...base, ...granted])],
+        manifestHash: manifest.hash,
+    });
+    const effective = [
+        ...new Set([...(getGrant(appId, spaceKey)?.scopes ?? []), ...grant.scopes]),
+    ];
+    args.notify?.({
+        type: 'sdkGrantsChanged',
+        data: { appId, grants: effective },
+        targetViewerId: viewerId,
+    });
+}
+export async function runConnect(args) {
+    const { appId, viewerId, spaceKey } = args;
+    if (!isValidAppId(appId)) {
+        throw new SdkMethodError('BAD_REQUEST', `invalid appId '${appId}' — expected the D5 grammar (lowercase [a-z0-9-])`);
+    }
+    const requested = parseRequestedScopes(args.params);
+    if (requested === null) {
+        throw new SdkMethodError('BAD_REQUEST', 'connect params.scopes must be an array of scope strings');
+    }
+    const manifest = parsePinnedManifest(args.manifest);
+    if (manifest === null) {
+        throw new SdkMethodError('BAD_REQUEST', 'sdkConnect must carry the pinned manifest envelope { hash, scopes, optionalScopes } stamped by the host');
+    }
+    const cap = new Set([...manifest.scopes, ...manifest.optionalScopes]);
+    const outsideCap = requested.filter((scope) => !cap.has(scope));
+    if (outsideCap.length > 0) {
+        throw new SdkMethodError('SCOPE_DENIED', `scope(s) not declared by the app's pinned manifest: ${outsideCap.join(', ')}`);
+    }
+    const requestedScopes = requested;
+    const persisted = getGrant(appId, spaceKey);
+    const session = viewerId ? getSessionGrant(viewerId, appId, spaceKey) : undefined;
+    const prior = [
+        ...new Set([
+            ...hashBoundScopes(persisted, manifest.hash),
+            ...hashBoundScopes(session, manifest.hash),
+        ]),
+    ];
+    const missing = computeScopeDelta(requestedScopes, prior);
+    if (missing.length === 0) {
+        return connectResult(args);
+    }
+    const outcome = await promptForConsent(args, missing, prior);
+    applyApprovedConsent(args, manifest, missing, outcome);
+    return connectResult(args);
+}
+function resolveConsentRouting(args) {
+    if (args.consentRouting?.mode !== 'owner-sessions') {
+        return { accept: { kind: 'requester', viewerId: args.viewerId }, cardTargets: [args.viewerId] };
+    }
+    const sessions = args.consentRouting.listSessions().filter((id) => id !== '');
+    if (sessions.length === 0) {
+        autoDenyAudit(args, 'no owner session is connected to approve a Browser-transport consent');
+        throw new SdkMethodError('USER_REJECTED', 'no owner session is connected to approve this request — open this Space in Minionry as its owner and try again');
+    }
+    return { accept: { kind: 'owner-sessions', viewerIds: new Set(sessions) }, cardTargets: sessions };
+}
+async function promptForConsent(args, missing, prior) {
+    const { appId, origin, role } = args;
+    if (!args.notify) {
+        throw new SdkMethodError('USER_REJECTED', 'this transport has no consent surface attached — the connect request cannot be prompted');
+    }
+    const cooldown = checkConsentCooldown(origin);
+    if (cooldown.blocked) {
+        autoDenyAudit(args, `consent cooldown after ${cooldown.dismissals} consecutive dismissal(s) — retry in ${Math.ceil(cooldown.retryAfterMs / 1000)}s`);
+        throw new SdkMethodError('USER_REJECTED', 'the connect request was auto-denied — this origin is cooling down after repeated consent dismissals');
+    }
+    const { accept, cardTargets } = resolveConsentRouting(args);
+    const consentId = randomUUID();
+    const card = {
+        consentId,
+        appId,
+        origin,
+        requestedScopes: [...missing],
+        priorScopes: [...prior],
+        mode: prior.length > 0 ? 'delta' : 'full',
+        variant: accept.kind === 'owner-sessions' || role !== 'viewer' ? 'member' : 'viewer',
+        ...(accept.kind === 'owner-sessions' ? { transport: 'browser' } : {}),
+    };
+    const pending = registerPendingConsent(consentId, accept);
+    for (const target of cardTargets) {
+        args.notify({ type: 'sdkConsentRequest', data: card, targetViewerId: target });
+    }
+    const outcome = await pending;
+    if (outcome.outcome === 'denied' || outcome.outcome === 'timeout') {
+        recordConsentDismissal(origin);
+        throw new SdkMethodError('USER_REJECTED', outcome.outcome === 'denied'
+            ? 'the user declined the connect request'
+            : 'the connect request timed out without an answer');
+    }
+    recordConsentApproval(origin);
+    return outcome;
+}
+function autoDenyAudit(args, reason) {
+    logAppAudit({
+        appId: args.appId,
+        origin: args.origin,
+        method: 'connect.autoDenied',
+        decision: 'deny',
+        requestId: args.requestId,
+        spaceKey: args.spaceKey,
+        reason,
+    });
+}

package/dist/server/services/sdk/consent-cooldown.js

@@ -0,0 +1,31 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+export const CONSENT_COOLDOWN_BASE_MS = 30_000;
+export const CONSENT_COOLDOWN_FACTOR = 4;
+export const CONSENT_COOLDOWN_MAX_MS = 30 * 60_000;
+const cooldowns = new Map();
+let now = Date.now;
+export function setSdkConsentCooldownClockForTests(clock) {
+    now = clock ?? Date.now;
+}
+export function checkConsentCooldown(origin) {
+    const state = cooldowns.get(origin);
+    if (!state)
+        return { blocked: false };
+    const remaining = state.blockedUntil - now();
+    if (remaining <= 0)
+        return { blocked: false };
+    return { blocked: true, retryAfterMs: remaining, dismissals: state.dismissals };
+}
+export function recordConsentDismissal(origin) {
+    const dismissals = (cooldowns.get(origin)?.dismissals ?? 0) + 1;
+    const blockedForMs = Math.min(CONSENT_COOLDOWN_BASE_MS * CONSENT_COOLDOWN_FACTOR ** (dismissals - 1), CONSENT_COOLDOWN_MAX_MS);
+    cooldowns.set(origin, { dismissals, blockedUntil: now() + blockedForMs });
+    return { dismissals, blockedForMs };
+}
+export function recordConsentApproval(origin) {
+    cooldowns.delete(origin);
+}
+export function clearAllConsentCooldowns() {
+    cooldowns.clear();
+}

package/dist/server/services/sdk/endpoint-url.js

@@ -0,0 +1,141 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { isIP } from 'node:net';
+export const ENDPOINT_BLOCKED_IP_RANGES = [
+    { cidr: '169.254.169.254/32', reason: 'cloud metadata endpoint' },
+    { cidr: '169.254.0.0/16', reason: 'IPv4 link-local (RFC 3927)' },
+    { cidr: '127.0.0.0/8', reason: 'IPv4 loopback' },
+    { cidr: '0.0.0.0/8', reason: '"this network" (reaches loopback)' },
+    { cidr: '10.0.0.0/8', reason: 'RFC 1918 private' },
+    { cidr: '172.16.0.0/12', reason: 'RFC 1918 private' },
+    { cidr: '192.168.0.0/16', reason: 'RFC 1918 private' },
+    { cidr: '100.64.0.0/10', reason: 'carrier-grade NAT (RFC 6598)' },
+    { cidr: '192.0.0.0/24', reason: 'IETF protocol assignments (RFC 6890)' },
+    { cidr: '198.18.0.0/15', reason: 'network benchmarking (RFC 2544)' },
+    { cidr: '224.0.0.0/4', reason: 'IPv4 multicast' },
+    { cidr: '240.0.0.0/4', reason: 'reserved (RFC 1112)' },
+    { cidr: '::/128', reason: 'IPv6 unspecified' },
+    { cidr: '::1/128', reason: 'IPv6 loopback' },
+    { cidr: 'fc00::/7', reason: 'IPv6 unique-local (RFC 4193)' },
+    { cidr: 'fe80::/10', reason: 'IPv6 link-local' },
+    { cidr: 'fec0::/10', reason: 'IPv6 site-local (RFC 3879)' },
+    { cidr: 'ff00::/8', reason: 'IPv6 multicast' },
+    { cidr: '64:ff9b::/96', reason: 'NAT64 (RFC 6052)' },
+    { cidr: '2002::/16', reason: '6to4 (RFC 3056)' },
+];
+function ipv4Value(address) {
+    if (isIP(address) !== 4)
+        return undefined;
+    return address.split('.').reduce((value, octet) => ((value << 8) | Number(octet)) >>> 0, 0);
+}
+function ipv6Value(address) {
+    if (isIP(address) !== 6)
+        return undefined;
+    let text = address;
+    const lastColon = text.lastIndexOf(':');
+    const tail = text.slice(lastColon + 1);
+    if (tail.includes('.')) {
+        const v4 = ipv4Value(tail);
+        if (v4 === undefined)
+            return undefined;
+        text = `${text.slice(0, lastColon + 1)}${(v4 >>> 16).toString(16)}:${(v4 & 0xffff).toString(16)}`;
+    }
+    const halves = text.split('::');
+    if (halves.length > 2)
+        return undefined;
+    const head = halves[0] ? halves[0].split(':') : [];
+    const rest = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+    const zeros = 8 - head.length - rest.length;
+    if (halves.length === 1 ? zeros !== 0 : zeros < 0)
+        return undefined;
+    const groups = [...head, ...new Array(Math.max(zeros, 0)).fill('0'), ...rest];
+    let value = 0n;
+    for (const group of groups) {
+        if (!/^[0-9a-f]{1,4}$/i.test(group))
+            return undefined;
+        value = (value << 16n) | BigInt(Number.parseInt(group, 16));
+    }
+    return value;
+}
+const IPV4_RULES = [];
+const IPV6_RULES = [];
+for (const { cidr, reason } of ENDPOINT_BLOCKED_IP_RANGES) {
+    const [address, prefixText] = cidr.split('/');
+    const prefix = Number(prefixText);
+    if (address.includes(':')) {
+        const base = ipv6Value(address);
+        if (base === undefined)
+            throw new Error(`invalid blocked range: ${cidr}`);
+        const shift = BigInt(128 - prefix);
+        IPV6_RULES.push({ base: base >> shift, shift, reason });
+    }
+    else {
+        const base = ipv4Value(address);
+        if (base === undefined)
+            throw new Error(`invalid blocked range: ${cidr}`);
+        const mask = (0xffffffff << (32 - prefix)) >>> 0;
+        IPV4_RULES.push({ base: (base & mask) >>> 0, mask, reason });
+    }
+}
+function blockedIpv4Reason(value) {
+    return IPV4_RULES.find((rule) => ((value & rule.mask) >>> 0) === rule.base)?.reason;
+}
+function blockedIpv6Reason(value) {
+    if (value >> 32n === 0xffffn) {
+        const reason = blockedIpv4Reason(Number(value & 0xffffffffn));
+        return reason === undefined ? undefined : `IPv4-mapped IPv6: ${reason}`;
+    }
+    const rule = IPV6_RULES.find((candidate) => value >> candidate.shift === candidate.base);
+    if (rule)
+        return rule.reason;
+    if (value >> 32n === 0n) {
+        const reason = blockedIpv4Reason(Number(value & 0xffffffffn));
+        return reason === undefined ? undefined : `IPv4-compatible IPv6: ${reason}`;
+    }
+    return undefined;
+}
+export function findBlockedEndpointAddressReason(address) {
+    const bare = address.split('%')[0];
+    const v4 = ipv4Value(bare);
+    if (v4 !== undefined)
+        return blockedIpv4Reason(v4) ?? null;
+    if (isIP(bare) === 6) {
+        const v6 = ipv6Value(bare);
+        return v6 === undefined ? 'unparseable address' : (blockedIpv6Reason(v6) ?? null);
+    }
+    return 'not an IP address';
+}
+export const MAX_ENDPOINT_URL_BYTES = 2048;
+const LOCAL_ONLY_SUFFIXES = ['localhost', 'local', 'internal', 'home.arpa'];
+export function validateEndpointUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return { ok: false, reason: 'is not a valid absolute URL' };
+    }
+    if (url.protocol !== 'https:')
+        return { ok: false, reason: 'must use https' };
+    if (url.username !== '' || url.password !== '')
+        return { ok: false, reason: 'must not carry credentials' };
+    if (url.search !== '' || url.href.includes('?'))
+        return { ok: false, reason: 'must not carry a query' };
+    if (url.hash !== '' || url.href.includes('#'))
+        return { ok: false, reason: 'must not carry a fragment' };
+    const host = url.hostname;
+    const name = host.replace(/\.+$/, '').toLowerCase();
+    if (name === '')
+        return { ok: false, reason: 'must name a host' };
+    if (isIP(name.replace(/^\[|\]$/g, '')) !== 0) {
+        return { ok: false, reason: 'must name a hostname, not an IP address' };
+    }
+    if (LOCAL_ONLY_SUFFIXES.some((suffix) => name === suffix || name.endsWith(`.${suffix}`))) {
+        return { ok: false, reason: 'must not name a local-network host' };
+    }
+    const canonical = `${url.origin}${url.pathname === '/' ? '' : url.pathname}`;
+    if (Buffer.byteLength(canonical, 'utf8') > MAX_ENDPOINT_URL_BYTES) {
+        return { ok: false, reason: `must be at most ${MAX_ENDPOINT_URL_BYTES} bytes` };
+    }
+    return { ok: true, host, url: canonical };
+}