Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): require trusted private skill origins (PRD-10110) (#7899)

Andrew Mikofalvyae8bb2320e5b
diff --git a/.changeset/trusted-website-skill-origins.md b/.changeset/trusted-website-skill-origins.md
new file mode 100644
index 000000000..bb2bd1685
--- /dev/null
+++ b/.changeset/trusted-website-skill-origins.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Website skills now require public network destinations by default. For trusted private hosts, add an exact HTTPS-origin exception to user configuration; see [private website sources](https://openknowledge.ai/docs/features/skills/find-and-install#use-a-private-website-source).
diff --git a/docs/content/features/skills/find-and-install.mdx b/docs/content/features/skills/find-and-install.mdx
index a96ecd2cb..c7b52a848 100644
--- a/docs/content/features/skills/find-and-install.mdx
+++ b/docs/content/features/skills/find-and-install.mdx
@@ -57,6 +57,26 @@ Skills already in your AI tools' folders show up in the dock on their own. Open
A skill can include scripts that run on your machine. Read what it does and use sources you trust. OpenKnowledge does not run a skill's scripts during import.
</Callout>
+## Use a private website source
+
+Website skill downloads require public network addresses by default. To use a trusted website on a private network, add its exact HTTPS origin to the **user** config at `~/.ok/global.yml` (`~/.ok-beta/global.yml` for Beta):
+
+```yaml
+skills:
+ trustedPrivateOrigins:
+ - https://skills.example.com
+```
+
+Use the canonical origin: a lowercase hostname and no explicit default `:443` port. Include a nondefault port if the source needs one, such as `https://skills.example.com:8443`. Do not include credentials, a trailing slash, path, wildcard, query, or fragment. Trust applies only to that exact origin, not its subdomains or other ports. Project configuration and catalog entries cannot grant this permission.
+
+The website still needs a trusted HTTPS certificate matching its hostname. Removing an origin from the list blocks subsequent private-network requests without restarting OpenKnowledge.
+
+Add approvals by editing this user file on the computer or inside the container running OpenKnowledge. There is no Settings control for this list. Collaboration sessions, including remote browser sessions, may remove approvals and change unrelated settings, but cannot add approvals.
+
+Invalid entries are ignored individually and reported by `ok config validate`; other valid approvals remain active. A malformed user config cannot grant private-network access.
+
+Unapproved sources use direct connections to public unicast addresses. Private, reserved, and translated addresses such as NAT64 are blocked. Proxy-only networks may also need explicit origin approval. Approved sources keep the runtime's configured proxy routing; approval does not disable certificate or hostname verification.
+
## Keep it up to date
An imported skill remembers where it came from.
diff --git a/docs/content/reference/configuration.mdx b/docs/content/reference/configuration.mdx
index f714a908c..3582ddf8a 100644
--- a/docs/content/reference/configuration.mdx
+++ b/docs/content/reference/configuration.mdx
@@ -58,6 +58,7 @@ A key set in a file more specific than its scope (a user-scope key in `.ok/confi
| `autoSync.pushIntervalSeconds` | `number` | `60` | project-local | Seconds between scheduled pushes while `autoSync.mode` is `full` (30–3600). Shown in **Settings → Sync** as **Push my edits every**. Ignored in every other mode, which never pushes on a schedule. Each cycle with pending edits authors a commit, so a shorter interval means more, smaller commits in shared history. |
| `autoSync.enabled` | `boolean \| null` | `null` | project-local | Legacy per-machine auto-sync toggle, superseded by `autoSync.mode`. Read only when `mode` is absent (`true` = full, `false` = off). `null` means "unanswered". |
| `autoSync.default` | `"off" \| "follow" \| "full" \| boolean \| null` | `null` | project | Project seed for each machine's first-open sync mode: `off` / `follow` / `full`, or the legacy boolean (`true` = full, `false` = off). `null` = ask. Lets a maintainer pre-answer the onboarding prompt for everyone who clones, but only when **Config sharing** is set to **Shared** so `.ok/config.yml` is committed; with **Only me** the value stays on this machine. A per-machine `autoSync.mode` overrides it. Compatibility note: a committed string value (`off` / `follow` / `full`) is rejected by app versions released before `autoSync.mode` existed, resetting that machine to config defaults until it updates (it never silently syncs). The legacy boolean seed (`true` / `false`) stays readable by older apps — commit `follow` only once collaborators are on a current version. |
+| `skills.trustedPrivateOrigins` | string[] | `[]` | user | Canonical HTTPS origins approved for private website skill hosting. Add approvals by editing the user file on the host computer or container; collaboration sessions may revoke but cannot add approvals. Invalid entries produce diagnostics without erasing valid siblings. Project configuration cannot grant trust. Certificate and hostname checks still apply. See [Private website sources](/docs/features/skills/find-and-install#use-a-private-website-source). |
| `git.hosts.<host>.provider` | `"github"` | (unset) | user | Declares that `<host>` is a GitHub Enterprise Server instance, so OpenKnowledge treats remotes on it the way it treats `github.com`: OpenKnowledge's own credential handling, the push-permission check, share links, and the default host for `ok auth`. `github` is the only accepted value today. Shown in **Settings → Git** as **GitHub Enterprise Server hosts**, which adds and removes entries for you. A host that is neither `github.com` nor declared here is treated as a generic git remote, so OpenKnowledge leaves the machine's own git credentials alone, unless a token is stored for that host and the remote uses `https:`, in which case the running server's sync uses the token, and reports push permission as unknown instead of pausing sync. Per-machine: one entry covers every project on this machine, and a declaration committed in a project's `.ok/config.yml` is ignored. Read at server start. Matching uses the hostname without its port, across transports. Without a running server, `ok sync`, `ok pull` and `ok push` use OpenKnowledge's sign-in only for an `https://` remote that names the host in lowercase and with no port; any other form, even an explicit `:443`, keeps your own git credentials. Invalid entries produce config diagnostics without erasing valid siblings. Undeclared origins cause GitHub-specific CLI commands and project sign-in requests to refuse; CLI commands can still target a declared host with `--host`. |
| `server.bind` | list of addresses | `["127.0.0.1"]` | project-local | Addresses the server binds, e.g. `[127.0.0.1]` or `[0.0.0.0]`. The loopback default keeps everything off-machine out. A non-loopback bind additionally requires the `server.allowExternal` consent interlock. Per-machine — a value committed to `.ok/config.yml` is ignored (the exposing host would otherwise refuse to boot for every teammate who clones and runs locally, since the interlock needs per-machine consent that is never committed). Set it where the server is exposed: `OK_BIND` (space-separated), `ok start --bind <address>`, or `.ok/local/config.yml`. Lists replace, never merge. Read at server start. |
| `server.port` | number | (unset) | project | TCP port the server listens on. Unset = a local start picks a free port dynamically (deployment platforms inject `PORT` instead). Read at server start. |
diff --git a/packages/core/package.json b/packages/core/package.json
index ea38450b9..1304c6629 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -882,6 +882,7 @@
"ajv-formats": "^3.0.1",
"decode-named-character-reference": "^1.3.0",
"diff-match-patch": "^1.0.5",
+ "ipaddr.js": "^2.3.0",
"markdownlint": "^0.41.0",
"mdast-util-from-markdown": "^2.0.3",
"mdast-util-math": "^3.0.0",
@@ -908,6 +909,7 @@
"remark-rehype": "^11.1.2",
"remark-stringify": "^11.0.0",
"remend": "1.3.0",
+ "undici": "~7.29.0",
"unified": "^11.0.5",
"unified-lint-rule": "^3.0.0",
"unist-util-visit": "^5.1.0",
diff --git a/packages/core/src/config/bind-config-doc.test.ts b/packages/core/src/config/bind-config-doc.test.ts
index 342b4d081..dca3817ea 100644
--- a/packages/core/src/config/bind-config-doc.test.ts
+++ b/packages/core/src/config/bind-config-doc.test.ts
@@ -117,6 +117,20 @@ describe('bindConfigDoc — current()', () => {
});
describe('bindConfigDoc — patch()', () => {
+ test('rejects malformed private-origin patches without changing the synced document', () => {
+ const binding = bindSyncedConfigDoc('user');
+ const origin = 'https://skills.example.com';
+ expect(binding.patch({ skills: { trustedPrivateOrigins: [origin] } }).ok).toBe(true);
+ const before = doc.getText('source').toString();
+ expect(
+ binding.patch({ skills: { trustedPrivateOrigins: [origin, `${origin}/`] } }),
+ ).toMatchObject({
+ ok: false,
+ error: { code: 'SCHEMA_INVALID' },
+ });
+ expect(doc.getText('source').toString()).toBe(before);
+ binding.dispose();
+ });
test('allows removing providers and hosts without discarding sibling declarations', () => {
const binding = bindSyncedConfigDoc('user');
expect(
diff --git a/packages/core/src/config/bind-config-doc.ts b/packages/core/src/config/bind-config-doc.ts
index b670530a2..ba4098435 100644
--- a/packages/core/src/config/bind-config-doc.ts
+++ b/packages/core/src/config/bind-config-doc.ts
@@ -4,6 +4,7 @@ import type { ConfigValidationError, WriteScope } from './errors.ts';
import { validateGitHostPatch } from './git-host-config.ts';
import type { Err, Ok, Result } from './result.ts';
import { type Config, type ConfigPatch, ConfigSchema } from './schema.ts';
+import { validateSkillSourcePatch } from './skill-source-config.ts';
import { addConfigSpanEvent, withConfigSpanSync } from './telemetry.ts';
import { validatePatchScopes } from './validate-patch-scopes.ts';
import { applyPatchToDocument, toConfigIssue } from './yaml-patch.ts';
@@ -154,6 +155,8 @@ function bindConfigDocInner(
}
const hostViolation = validateGitHostPatch(patch);
if (hostViolation !== null) return err(hostViolation);
+ const skillSourceViolation = validateSkillSourcePatch(patch);
+ if (skillSourceViolation !== null) return err(skillSourceViolation);
const currentContent = ytext.toString();
let doc = parseDocument(currentContent);
diff --git a/packages/core/src/config/field-registry.test.ts b/packages/core/src/config/field-registry.test.ts
index 8cc46ca5c..06f2a31ad 100644
--- a/packages/core/src/config/field-registry.test.ts
+++ b/packages/core/src/config/field-registry.test.ts
@@ -184,6 +184,7 @@ describe('ConfigSchema coverage (NR3 — every leaf has fieldRegistry metadata)'
'editor.previewTabs',
'editor.wordWrap',
'git.hosts',
+ 'skills.trustedPrivateOrigins',
'slides.enabled',
'telemetry.skillInstallReports.enabled',
]);
diff --git a/packages/core/src/config/read-config-safely.ts b/packages/core/src/config/read-config-safely.ts
index dc5f0a967..8d208f55c 100644
--- a/packages/core/src/config/read-config-safely.ts
+++ b/packages/core/src/config/read-config-safely.ts
@@ -21,6 +21,7 @@ import {
MIN_EMBEDDINGS_MAX_BATCH_CHARS,
MIN_EMBEDDINGS_MAX_BATCH_SIZE,
} from './schema.ts';
+import { TrustedPrivateOriginsSchema } from './skill-source-config.ts';
import { locateIssue } from './source-locator.ts';
export interface ReadConfigSafelyOptions {
@@ -194,6 +195,38 @@ function detectAutolinkFallbacks(input: {
return [{ code: 'VALUE_FALLBACK', issues }];
}
+function detectSkillSourceFallbacks(input: {
+ rawConfig: unknown;
+ doc: Document;
+ source: string;
+ absPath: string;
+}): ValueFallbackDiagnostic[] {
+ const origins = rawValueAtPath(input.rawConfig, ['skills', 'trustedPrivateOrigins']);
+ if (origins === undefined) return [];
+ const parsed = TrustedPrivateOriginsSchema.safeParse(origins);
+ if (parsed.success) return [];
+ const issues = parsed.error.issues.map((issue) => {
+ const path = ['skills', 'trustedPrivateOrigins', ...issue.path.map(String)];
+ const located = locateIssue({
+ file: input.absPath,
+ source: input.source,
+ doc: input.doc,
+ path,
+ });
+ return {
+ path,
+ message:
+ issue.path.length === 0
+ ? `${issue.message}; ignoring the trusted website origins list.`
+ : `${issue.message}; ignoring this trusted website origin.`,
+ ...(located !== undefined
+ ? { source: { file: located.file, line: located.line, column: located.column } }
+ : {}),
+ };
+ });
+ return [{ code: 'VALUE_FALLBACK', issues }];
+}
+
export function readConfigSafely(options: ReadConfigSafelyOptions): ReadConfigSafelyResult {
const { absPath, sideline = true, timestamp = new Date().toISOString() } = options;
const warn = options.warn ?? ((msg: string) => console.warn(msg));
@@ -243,6 +276,7 @@ export function readConfigSafely(options: ReadConfigSafelyOptions): ReadConfigSa
const valueFallbackDiagnostics = [
...detectGitHostFallbacks({ rawConfig: cleaned, doc, source, absPath }),
...detectAutolinkFallbacks({ rawConfig: cleaned, doc, source, absPath }),
+ ...detectSkillSourceFallbacks({ rawConfig: cleaned, doc, source, absPath }),
];
for (const diagnostic of valueFallbackDiagnostics) {
for (const issue of diagnostic.issues) {
@@ -255,10 +289,16 @@ export function readConfigSafely(options: ReadConfigSafelyOptions): ReadConfigSa
const error = buildSchemaInvalidError(parsed, doc, source, absPath);
const git =
ConfigSchema.shape.git.safeParse(rawValueAtPath(cleaned, ['git'])).data ?? defaults.git;
- const fallback =
+ const skills =
+ ConfigSchema.shape.skills.safeParse(rawValueAtPath(cleaned, ['skills'])).data ??
+ defaults.skills;
+ let fallback =
Object.keys(git.hosts).length > 0
? 'Using schema defaults while preserving valid git-host declarations.'
: 'Using schema defaults.';
+ if (skills.trustedPrivateOrigins.some((origin) => origin !== null)) {
+ fallback += ' Valid website-origin approvals were preserved.';
+ }
warn(
`[config] ${absPath} fails schema validation (${parsed.error.issues.length} issue(s)). ${fallback}` +
(sideline ? '' : ' Pass-through mode: file left in place.'),
@@ -274,6 +314,7 @@ export function readConfigSafely(options: ReadConfigSafelyOptions): ReadConfigSa
value: {
...defaults,
git,
+ skills,
},
error,
diagnostics,
diff --git a/packages/core/src/config/schema.ts b/packages/core/src/config/schema.ts
index 1d89110a1..3259cb94e 100644
--- a/packages/core/src/config/schema.ts
+++ b/packages/core/src/config/schema.ts
@@ -21,6 +21,7 @@ import {
import { EffectiveAutolinkEntrySchema } from './autolinks-config.ts';
import { fieldRegistry } from './field-registry.ts';
import { EffectiveGitHostEntrySchema } from './git-host-config.ts';
+import { EffectiveTrustedPrivateOriginSchema } from './skill-source-config.ts';
function base16SlotFields() {
return Object.fromEntries(
@@ -715,6 +716,22 @@ export const ConfigSchema = z.looseObject({
.default(null),
})
.default({ mode: null, enabled: null, default: null }),
+ skills: z
+ .looseObject({
+ trustedPrivateOrigins: z
+ .array(EffectiveTrustedPrivateOriginSchema)
+ .register(fieldRegistry, {
+ scope: 'user',
+ agentSettable: false,
+ reload: 'live',
+ defaultScope: 'user',
+ description:
+ 'Canonical HTTPS origins allowed to serve website skills from private network addresses. Empty by default: website skills require public addresses. Set only in user global.yml, never project configuration or acquisition requests. Use a lowercase hostname and omit credentials, default port 443, trailing slash, path, query, fragment and wildcards. Include nondefault ports when required. Invalid entries are ignored with located config diagnostics; valid siblings remain approved. TLS certificate and hostname checks still apply.',
+ })
+ .default([])
+ .catch([]),
+ })
+ .default({ trustedPrivateOrigins: [] }),
git: z
.looseObject({
hosts: z
diff --git a/packages/core/src/config/skill-source-config.ts b/packages/core/src/config/skill-source-config.ts
new file mode 100644
index 000000000..98af21e27
--- /dev/null
+++ b/packages/core/src/config/skill-source-config.ts
@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import type { ConfigValidationError } from './errors.ts';
+import type { ConfigPatch } from './schema.ts';
+import { toConfigIssue } from './yaml-patch.ts';
+
+const TrustedPrivateOriginSchema = z.string().refine((value) => {
+ try {
+ const url = new URL(value);
+ return url.protocol === 'https:' && url.origin === value && !url.hostname.includes('*');
+ } catch {
+ return false;
+ }
+}, 'Expected a canonical credential-free HTTPS origin: lowercase hostname, no default port, trailing slash, path, query, fragment or wildcard');
+
+export const TrustedPrivateOriginsSchema = z.array(TrustedPrivateOriginSchema);
+export const EffectiveTrustedPrivateOriginSchema =
+ TrustedPrivateOriginSchema.nullable().catch(null);
+
+const SkillSourcePatchSchema = z.looseObject({
+ skills: z.looseObject({ trustedPrivateOrigins: TrustedPrivateOriginsSchema.nullish() }).nullish(),
+});
+
+export function validateSkillSourcePatch(
+ patch: ConfigPatch,
+): Extract<ConfigValidationError, { code: 'SCHEMA_INVALID' }> | null {
+ const parsed = SkillSourcePatchSchema.safeParse(patch);
+ return parsed.success
+ ? null
+ : { code: 'SCHEMA_INVALID', issues: parsed.error.issues.map(toConfigIssue) };
+}
diff --git a/packages/core/src/config/skill-source-policy.test.ts b/packages/core/src/config/skill-source-policy.test.ts
new file mode 100644
index 000000000..500c396d2
--- /dev/null
+++ b/packages/core/src/config/skill-source-policy.test.ts
@@ -0,0 +1,148 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { mergeLayered } from './merge-layered.ts';
+import { readConfigSafely } from './read-config-safely.ts';
+import { ConfigSchema } from './schema.ts';
+import { getLeafFieldMeta } from './schema-leaf.ts';
+import { validatePatchScopes } from './validate-patch-scopes.ts';
+import { resolveConfigPath, writeConfigPatch } from './write-config-patch.ts';
+
+describe('website skill private-origin trust', () => {
+ const origin = 'https://skills.example.com';
+ const trusted = ConfigSchema.parse({ skills: { trustedPrivateOrigins: [origin] } });
+ const defaults = ConfigSchema.parse({});
+ let home: string;
+ beforeEach(() => {
+ home = mkdtempSync(join(tmpdir(), 'skill-trust-config-'));
+ });
+ afterEach(() => {
+ rmSync(home, { recursive: true, force: true });
+ });
+
+ function configFile(): string {
+ const file = resolveConfigPath('user', home, home);
+ mkdirSync(dirname(file), { recursive: true });
+ return file;
+ }
+
+ test('reports each rejected entry with its location without erasing valid siblings', () => {
+ const file = configFile();
+ writeFileSync(
+ file,
+ `skills:\n trustedPrivateOrigins:\n - ${origin}\n - https://user:[email protected]/path?token=fixture\n`,
+ );
+ const warnings: string[] = [];
+ const result = readConfigSafely({
+ absPath: file,
+ sideline: false,
+ warn: (value) => warnings.push(value),
+ });
+ expect(result.value.skills.trustedPrivateOrigins).toEqual([origin, null]);
+ expect(result.diagnostics).toContainEqual({
+ code: 'VALUE_FALLBACK',
+ issues: expect.arrayContaining([
+ expect.objectContaining({
+ path: ['skills', 'trustedPrivateOrigins', '1'],
+ source: expect.objectContaining({ file, line: 4 }),
+ }),
+ ]),
+ });
+ expect(warnings.join('\n')).toContain('skills.trustedPrivateOrigins.1');
+ expect(warnings.join('\n')).not.toContain('fixture-secret');
+ expect(warnings.join('\n')).not.toContain('token=fixture');
+ });
+
+ test('preserves valid user trust when an unrelated config field is invalid', () => {
+ const file = configFile();
+ writeFileSync(
+ file,
+ `server:\n port: invalid\nskills:\n trustedPrivateOrigins: [${origin}]\n`,
+ );
+ const result = readConfigSafely({ absPath: file, sideline: false, warn: () => {} });
+ expect(result.valid).toBe(false);
+ expect(result.value.skills.trustedPrivateOrigins).toEqual([origin]);
+ });
+
+ test('explains that a non-array trust value discards the entire list', () => {
+ const file = configFile();
+ writeFileSync(file, `skills:\n trustedPrivateOrigins: ${origin}\n`);
+ const result = readConfigSafely({ absPath: file, sideline: false, warn: () => {} });
+ expect(result.value.skills.trustedPrivateOrigins).toEqual([]);
+ expect(result.diagnostics).toContainEqual({
+ code: 'VALUE_FALLBACK',
+ issues: [
+ expect.objectContaining({
+ path: ['skills', 'trustedPrivateOrigins'],
+ message: expect.stringContaining('ignoring the trusted website origins list'),
+ }),
+ ],
+ });
+ });
+
+ test('rejects an invalid user patch instead of acknowledging an unusable approval', async () => {
+ const args = {
+ cwd: home,
+ scope: 'user' as const,
+ homedirOverride: home,
+ firstWriteHeader: null,
+ };
+ expect(
+ (await writeConfigPatch({ ...args, patch: { skills: { trustedPrivateOrigins: [origin] } } }))
+ .ok,
+ ).toBe(true);
+ const before = readFileSync(configFile(), 'utf8');
+ const result = await writeConfigPatch({
+ ...args,
+ patch: { skills: { trustedPrivateOrigins: [origin, `${origin}/`] } },
+ });
+ expect(result).toMatchObject({ ok: false, error: { code: 'SCHEMA_INVALID' } });
+ expect(readFileSync(configFile(), 'utf8')).toBe(before);
+ });
+
+ test('requires user trust rather than either project layer', () => {
+ expect(defaults.skills.trustedPrivateOrigins).toEqual([]);
+ expect(mergeLayered(defaults, trusted, trusted).skills.trustedPrivateOrigins).toEqual([]);
+ expect(mergeLayered(trusted, defaults, defaults).skills.trustedPrivateOrigins).toEqual([
+ origin,
+ ]);
+ for (const scope of ['project', 'project-local'] as const) {
+ expect(
+ validatePatchScopes({ skills: { trustedPrivateOrigins: [origin] } }, scope),
+ ).toMatchObject({ code: 'SCOPE_VIOLATION' });
+ }
+ expect(validatePatchScopes({ skills: { trustedPrivateOrigins: [origin] } }, 'user')).toBeNull();
+ });
+
+ test('does not make the setting agent-settable', () => {
+ expect(getLeafFieldMeta(ConfigSchema, ['skills', 'trustedPrivateOrigins'])).toMatchObject({
+ scope: 'user',
+ agentSettable: false,
+ });
+ });
+
+ test.each([
+ 'http://skills.example.com',
+ 'https://*.example.com',
+ 'https://skills.example.com/',
+ 'https://skills.example.com/path',
+ 'https://skills.example.com?query',
+ 'https://skills.example.com#fragment',
+ 'https://user:[email protected]',
+ 'https://skills.example.com:443',
+ 'not-a-url',
+ ])('fails closed for a nonexact HTTPS origin: %s', (value) => {
+ expect(
+ ConfigSchema.parse({ skills: { trustedPrivateOrigins: [value] } }).skills
+ .trustedPrivateOrigins,
+ ).toEqual([null]);
+ });
+
+ test('allows exact origin ports without granting related hosts', () => {
+ expect(
+ ConfigSchema.parse({ skills: { trustedPrivateOrigins: ['https://skills.example.com:8443'] } })
+ .skills.trustedPrivateOrigins,
+ ).toEqual(['https://skills.example.com:8443']);
+ });
+});
diff --git a/packages/core/src/config/write-config-patch.ts b/packages/core/src/config/write-config-patch.ts
index cf69e5dc1..c0743ca51 100644
--- a/packages/core/src/config/write-config-patch.ts
+++ b/packages/core/src/config/write-config-patch.ts
@@ -12,6 +12,7 @@ import { validateGitHostPatch } from './git-host-config.ts';
import type { Err, Ok, Result } from './result.ts';
import { type Config, type ConfigPatch, ConfigSchema } from './schema.ts';
import { CONFIG_SCHEMA_MAJOR_PATH } from './schema-version.ts';
+import { validateSkillSourcePatch } from './skill-source-config.ts';
import { addConfigSpanEvent, withConfigSpan, withConfigSpanSync } from './telemetry.ts';
import { validatePatchScopes } from './validate-patch-scopes.ts';
import { applyPatchToDocument, toConfigIssue } from './yaml-patch.ts';
@@ -101,6 +102,8 @@ async function writeConfigPatchInner(
}
const hostViolation = validateGitHostPatch(patch);
if (hostViolation !== null) return err(hostViolation);
+ const skillSourceViolation = validateSkillSourcePatch(patch);
+ if (skillSourceViolation !== null) return err(skillSourceViolation);
try {
await mkdir(dirname(absPath), { recursive: true });
diff --git a/packages/core/src/server.ts b/packages/core/src/server.ts
index 901d374bd..24f6cf824 100644
--- a/packages/core/src/server.ts
+++ b/packages/core/src/server.ts
@@ -53,6 +53,7 @@ export {
withFileLock,
withFileLockSync,
} from './util/file-lock.ts';
+export { classifyHost, isPublicUnicastIp } from './util/ip-classifier.ts';
export {
isProjectLogsKey,
okProjectLogsDir,
diff --git a/packages/core/src/skills-catalog/acquire/errors.ts b/packages/core/src/skills-catalog/acquire/errors.ts
index 12c346e16..c5abdbc99 100644
--- a/packages/core/src/skills-catalog/acquire/errors.ts
+++ b/packages/core/src/skills-catalog/acquire/errors.ts
@@ -1,3 +1,16 @@
export class SkillFetchError extends Error {}
+export class SkillDestinationPolicyError extends SkillFetchError {
+ readonly origin: string;
+
+ constructor(origin: string, configurationInvalid = false) {
+ const canonicalOrigin = new URL(origin).origin;
+ super(
+ `Website skills require public addresses. Approve ${canonicalOrigin} in user skills.trustedPrivateOrigins for trusted private hosting.${configurationInvalid ? ' The user configuration contains errors; check global.yml with ok config validate.' : ''}`,
+ );
+ this.name = 'SkillDestinationPolicyError';
+ this.origin = canonicalOrigin;
+ }
+}
+
export class SkillSubpathNotFoundError extends SkillFetchError {}
diff --git a/packages/core/src/skills-catalog/acquire/fetch.ts b/packages/core/src/skills-catalog/acquire/fetch.ts
index b4e03d91b..a8b94a5dc 100644
--- a/packages/core/src/skills-catalog/acquire/fetch.ts
+++ b/packages/core/src/skills-catalog/acquire/fetch.ts
@@ -23,7 +23,11 @@ export interface SkillsShSourceRef {
skill: string;
}
-export { SkillFetchError, SkillSubpathNotFoundError } from './errors.ts';
+export {
+ SkillDestinationPolicyError,
+ SkillFetchError,
+ SkillSubpathNotFoundError,
+} from './errors.ts';
const GIT_FETCH_BUDGET_MS = 60_000;
diff --git a/packages/core/src/skills-catalog/acquire/website-dns.test.ts b/packages/core/src/skills-catalog/acquire/website-dns.test.ts
new file mode 100644
index 000000000..2a9e7dff7
--- /dev/null
+++ b/packages/core/src/skills-catalog/acquire/website-dns.test.ts
@@ -0,0 +1,51 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { readWellKnownIndex } from './well-known.ts';
+
+const fixture = vi.hoisted(() => ({
+ home: '',
+ addresses: [] as { address: string; family: number }[],
+}));
+vi.mock('node:os', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('node:os')>()),
+ homedir: () => fixture.home,
+}));
+vi.mock('node:dns', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('node:dns')>()),
+ lookup: (_host: string, options: { all?: boolean }, callback: (...args: unknown[]) => void) => {
+ queueMicrotask(() => {
+ if (options.all) callback(null, fixture.addresses);
+ else callback(null, fixture.addresses[0]?.address, fixture.addresses[0]?.family);
+ });
+ },
+}));
+
+describe('website skill resolved-address admission', () => {
+ beforeEach(() => {
+ fixture.home = mkdtempSync(join(tmpdir(), 'skill-dns-policy-'));
+ });
+ afterEach(() => {
+ rmSync(fixture.home, { recursive: true, force: true });
+ });
+
+ test.each([
+ [],
+ ['127.0.0.1'],
+ ['93.184.216.34', '127.0.0.1'],
+ ['93.184.216.34', '::1'],
+ ['2606:4700:4700::1111', '10.0.0.1'],
+ ['::ffff:127.0.0.1'],
+ ['::ffff:93.184.216.34'],
+ ['169.254.169.254'],
+ ])('rejects an empty or mixed nonpublic DNS answer %j', async (...addresses: string[]) => {
+ fixture.addresses = addresses.map((address) => ({
+ address,
+ family: address.includes(':') ? 6 : 4,
+ }));
+ await expect(readWellKnownIndex('https://localhost', { timeoutMs: 1000 })).rejects.toThrow(
+ /require public addresses/,
+ );
+ });
+});
diff --git a/packages/core/src/skills-catalog/acquire/website-fetch.test.ts b/packages/core/src/skills-catalog/acquire/website-fetch.test.ts
new file mode 100644
index 000000000..bd0a66de5
--- /dev/null
+++ b/packages/core/src/skills-catalog/acquire/website-fetch.test.ts
@@ -0,0 +1,195 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer as createProxyServer } from 'node:http';
+import { createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { getGlobalDispatcher, ProxyAgent, setGlobalDispatcher } from 'undici';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { resolveConfigPath, writeConfigPatch } from '../../config/write-config-patch.ts';
+import { SkillDestinationPolicyError } from './errors.ts';
+import { fetchWellKnownSkill, readWellKnownIndex } from './well-known.ts';
+
+const home = vi.hoisted(() => ({ value: '' }));
+vi.mock('node:os', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('node:os')>()),
+ homedir: () => home.value,
+}));
+
+describe('website skill network admission', () => {
+ const servers: ReturnType<typeof createServer>[] = [];
+ const index = {
+ basePath: '/.well-known/agent-skills',
+ skills: [{ name: 'fixture', description: '', files: ['SKILL.md'] }],
+ };
+
+ function trust(origins: string[]): void {
+ const file = resolveConfigPath('user', home.value, home.value);
+ mkdirSync(dirname(file), { recursive: true });
+ writeFileSync(file, JSON.stringify({ skills: { trustedPrivateOrigins: origins } }));
+ }
+
+ async function listener() {
+ let connections = 0;
+ const server = createServer((socket) => {
+ connections++;
+ socket.destroy();
+ });
+ servers.push(server);
+ await new Promise<void>((resolve, reject) => {
+ server.once('error', reject);
+ server.listen(0, '127.0.0.1', resolve);
+ });
+ const address = server.address();
+ if (address === null || typeof address === 'string') throw new Error('Expected TCP listener');
+ return {
+ origin: `https://localhost:${address.port}`,
+ port: address.port,
+ get connections() {
+ return connections;
+ },
+ };
+ }
+
+ function fetchFiles(origin: string) {
+ return fetchWellKnownSkill(
+ { kind: 'well-known', origin, skill: 'fixture' },
+ { index, timeoutMs: 5000 },
+ );
+ }
+ beforeEach(() => {
+ home.value = mkdtempSync(join(tmpdir(), 'skill-host-policy-'));
+ });
+ afterEach(async () => {
+ await Promise.all(
+ servers
+ .splice(0)
+ .map((server) => new Promise<void>((resolve) => server.close(() => resolve()))),
+ );
+ rmSync(home.value, { recursive: true, force: true });
+ });
+
+ test.each([
+ '127.0.0.1',
+ '2130706433',
+ '0x7f000001',
+ '[::1]',
+ '10.0.0.1',
+ '169.254.169.254',
+ '[::ffff:127.0.0.1]',
+ ])('rejects private IP spellings before fetch: %s', async (host) => {
+ await expect(readWellKnownIndex(`https://${host}`, { timeoutMs: 1000 })).rejects.toThrow(
+ /require public addresses/,
+ );
+ });
+
+ test('rejects a hostname resolving to loopback before a TCP connection', async () => {
+ let connections = 0;
+ const server = createServer((socket) => {
+ connections++;
+ socket.destroy();
+ });
+ servers.push(server);
+ await new Promise<void>((resolve, reject) => {
+ server.once('error', reject);
+ server.listen(0, '127.0.0.1', resolve);
+ });
+ const address = server.address();
+ if (address === null || typeof address === 'string') throw new Error('Expected TCP listener');
+ await expect(
+ readWellKnownIndex(`https://localhost:${address.port}`, { timeoutMs: 1000 }),
+ ).rejects.toThrow(/require public addresses/);
+ expect(connections).toBe(0);
+ });
+
+ test('admits only the exact approved origin including its nondefault port', async () => {
+ const rig = await listener();
+ trust([`https://localhost:${rig.port === 65535 ? 65534 : rig.port + 1}`]);
+ await expect(fetchFiles(rig.origin)).rejects.toBeInstanceOf(SkillDestinationPolicyError);
+ expect(rig.connections).toBe(0);
+ trust([rig.origin]);
+ await expect(fetchFiles(rig.origin)).rejects.not.toBeInstanceOf(SkillDestinationPolicyError);
+ expect(rig.connections).toBeGreaterThan(0);
+ });
+
+ test('revoking trust blocks subsequent index and cached-index file requests without restarting', async () => {
+ const rig = await listener();
+ trust([rig.origin]);
+ await expect(fetchFiles(rig.origin)).rejects.not.toBeInstanceOf(SkillDestinationPolicyError);
+ const admitted = rig.connections;
+ expect(admitted).toBeGreaterThan(0);
+ trust([]);
+ await expect(readWellKnownIndex(rig.origin)).rejects.toBeInstanceOf(
+ SkillDestinationPolicyError,
+ );
+ await expect(fetchFiles(rig.origin)).rejects.toBeInstanceOf(SkillDestinationPolicyError);
+ expect(rig.connections).toBe(admitted);
+ });
+
+ test('admits an exact trusted IP literal and blocks it again after revocation', async () => {
+ const rig = await listener();
+ const origin = `https://127.0.0.1:${rig.port}`;
+ expect(
+ (
+ await writeConfigPatch({
+ cwd: home.value,
+ scope: 'user',
+ homedirOverride: home.value,
+ patch: { skills: { trustedPrivateOrigins: [origin] } },
+ firstWriteHeader: null,
+ })
+ ).ok,
+ ).toBe(true);
+ await expect(fetchFiles(origin)).rejects.not.toBeInstanceOf(SkillDestinationPolicyError);
+ const admitted = rig.connections;
+ expect(admitted).toBeGreaterThan(0);
+ trust([]);
+ await expect(readWellKnownIndex(origin)).rejects.toBeInstanceOf(SkillDestinationPolicyError);
+ await expect(fetchFiles(origin)).rejects.toBeInstanceOf(SkillDestinationPolicyError);
+ expect(rig.connections).toBe(admitted);
+ });
+
+ test('reports the exact origin once and explains an unreadable trust configuration', async () => {
+ const rig = await listener();
+ const file = resolveConfigPath('user', home.value, home.value);
+ mkdirSync(dirname(file), { recursive: true });
+ writeFileSync(file, 'skills: [');
+ const failure = await readWellKnownIndex(rig.origin).catch((error: unknown) => error);
+ expect(failure).toBeInstanceOf(SkillDestinationPolicyError);
+ if (!(failure instanceof Error)) throw new Error('Expected policy failure');
+ expect(failure.message.split(rig.origin)).toHaveLength(2);
+ expect(failure.message).toMatch(/user configuration.*errors/);
+ expect(rig.connections).toBe(0);
+ });
+
+ test('keeps the runtime proxy dispatcher for approved origins but never for revoked origins', async () => {
+ const previous = getGlobalDispatcher();
+ let tunnels = 0;
+ const server = createProxyServer();
+ server.on('connect', (_request, socket) => {
+ tunnels++;
+ socket.destroy();
+ });
+ servers.push(server);
+ await new Promise<void>((resolve, reject) => {
+ server.once('error', reject);
+ server.listen(0, '127.0.0.1', resolve);
+ });
+ const address = server.address();
+ if (address === null || typeof address === 'string') throw new Error('Expected proxy listener');
+ const origin = `https://localhost:${address.port}`;
+ const proxy = new ProxyAgent(`http://127.0.0.1:${address.port}`);
+ try {
+ setGlobalDispatcher(proxy);
+ trust([origin]);
+ await expect(fetchFiles(origin)).rejects.not.toBeInstanceOf(SkillDestinationPolicyError);
+ expect(tunnels).toBeGreaterThan(0);
+ const admitted = tunnels;
+ trust([]);
+ await expect(fetchFiles(origin)).rejects.toBeInstanceOf(SkillDestinationPolicyError);
+ expect(tunnels).toBe(admitted);
+ } finally {
+ setGlobalDispatcher(previous);
+ await proxy.destroy();
+ }
+ });
+});
diff --git a/packages/core/src/skills-catalog/acquire/website-fetch.ts b/packages/core/src/skills-catalog/acquire/website-fetch.ts
new file mode 100644
index 000000000..19419857e
--- /dev/null
+++ b/packages/core/src/skills-catalog/acquire/website-fetch.ts
@@ -0,0 +1,58 @@
+import { lookup } from 'node:dns';
+import type { LookupFunction } from 'node:net';
+import { Agent } from 'undici';
+import { readConfigSafely } from '../../config/read-config-safely.ts';
+import { resolveConfigPath } from '../../config/write-config-patch.ts';
+import { classifyHost, isPublicUnicastIp } from '../../util/ip-classifier.ts';
+import { SkillDestinationPolicyError } from './errors.ts';
+
+class NonPublicSkillAddressError extends Error {}
+
+const publicLookup: LookupFunction = (hostname, options, callback) => {
+ lookup(hostname, { all: true }, (error, addresses) => {
+ if (error) {
+ callback(error, '', 4);
+ return;
+ }
+ if (addresses.length === 0 || addresses.some(({ address }) => !isPublicUnicastIp(address))) {
+ callback(new NonPublicSkillAddressError(), '', 4);
+ return;
+ }
+ if (options.all) callback(null, addresses);
+ else callback(null, addresses[0].address, addresses[0].family);
+ });
+};
+
+const publicDispatcher = new Agent({ connect: { lookup: publicLookup } });
+
+export async function fetchWebsiteSkill(url: string, init: RequestInit): Promise<Response> {
+ const target = new URL(url);
+ const config = readConfigSafely({
+ absPath: resolveConfigPath('user', '.'),
+ sideline: false,
+ warn: () => {},
+ });
+ const configurationInvalid =
+ !config.valid ||
+ config.diagnostics.some(
+ (diagnostic) =>
+ diagnostic.code === 'VALUE_FALLBACK' &&
+ diagnostic.issues.some(
+ (issue) => issue.path[0] === 'skills' && issue.path[1] === 'trustedPrivateOrigins',
+ ),
+ );
+ const trusted = config.value.skills.trustedPrivateOrigins.includes(target.origin);
+ const host = classifyHost(target.hostname);
+ if (!trusted && host.kind === 'ip-literal' && !host.allowed) {
+ throw new SkillDestinationPolicyError(target.origin, configurationInvalid);
+ }
+ const requestInit = trusted ? init : { ...init, dispatcher: publicDispatcher };
+ try {
+ return await globalThis.fetch(url, requestInit);
+ } catch (error) {
+ if (error instanceof Error && error.cause instanceof NonPublicSkillAddressError) {
+ throw new SkillDestinationPolicyError(target.origin, configurationInvalid);
+ }
+ throw error;
+ }
+}
diff --git a/packages/core/src/skills-catalog/acquire/well-known.ts b/packages/core/src/skills-catalog/acquire/well-known.ts
index e5b9b6640..396cac237 100644
--- a/packages/core/src/skills-catalog/acquire/well-known.ts
+++ b/packages/core/src/skills-catalog/acquire/well-known.ts
@@ -6,7 +6,8 @@ import {
SKILL_IMPORT_MAX_FILE_BYTES,
SKILL_IMPORT_MAX_TOTAL_BYTES,
} from '../import-limits.ts';
-import { SkillFetchError } from './errors.ts';
+import { SkillDestinationPolicyError, SkillFetchError } from './errors.ts';
+import { fetchWebsiteSkill } from './website-fetch.ts';
const INDEX_CANDIDATES = [
'/.well-known/agent-skills/index.json',
@@ -51,7 +52,7 @@ export interface WellKnownSkillSummary {
const MAX_REDIRECTS = 5;
async function fetchWithinOrigin(
- fetchImpl: typeof fetch,
+ fetchImpl: typeof fetchWebsiteSkill,
url: string,
origin: string,
init: RequestInit,
@@ -60,6 +61,7 @@ async function fetchWithinOrigin(
for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
const response = await fetchImpl(current, { ...init, redirect: 'manual' });
if (response.status < 300 || response.status >= 400) return response;
+ await response.body?.cancel();
const location = response.headers.get('location');
if (location === null || location === '') {
@@ -170,7 +172,7 @@ async function readBoundedBody(
async function readIndex(
origin: string,
- fetchImpl: typeof fetch,
+ fetchImpl: typeof fetchWebsiteSkill,
timeoutMs: number,
): Promise<{ basePath: string; skills: LegacySkillEntry[] }> {
const failures: string[] = [];
@@ -204,6 +206,7 @@ async function readIndex(
}
return { basePath: indexPath.slice(0, -'/index.json'.length), skills };
} catch (error) {
+ if (error instanceof SkillDestinationPolicyError) throw error;
failures.push(`${indexPath}: ${error instanceof Error ? error.message : String(error)}`);
}
}
@@ -223,8 +226,7 @@ export async function readWellKnownIndex(
opts: WellKnownFetchOptions = {},
): Promise<WellKnownIndex> {
const origin = normalizedOrigin(rawOrigin);
- const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
- if (!fetchImpl) throw new SkillFetchError('No fetch implementation available.');
+ const fetchImpl = opts.fetchImpl ?? fetchWebsiteSkill;
return readIndex(origin, fetchImpl, opts.timeoutMs ?? 15_000);
}
@@ -236,8 +238,7 @@ export async function fetchWellKnownSkill(
throw new SkillFetchError(`Invalid website skill name: ${spec.skill}`);
}
const origin = normalizedOrigin(spec.origin);
- const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
- if (!fetchImpl) throw new SkillFetchError('No fetch implementation available.');
+ const fetchImpl = opts.fetchImpl ?? fetchWebsiteSkill;
const timeoutMs = opts.timeoutMs ?? 15_000;
const { basePath, skills } = opts.index ?? (await readIndex(origin, fetchImpl, timeoutMs));
const entry = skills.find((candidate) => candidate.name === spec.skill);
diff --git a/packages/core/src/skills-catalog/index.ts b/packages/core/src/skills-catalog/index.ts
index 826cbb4c8..bd42b1d14 100644
--- a/packages/core/src/skills-catalog/index.ts
+++ b/packages/core/src/skills-catalog/index.ts
@@ -6,6 +6,7 @@ export {
fetchSourceListing,
parseSkillsShSource,
parseSource,
+ SkillDestinationPolicyError,
SkillFetchError,
SkillSubpathNotFoundError,
type SkillsShSourceRef,
diff --git a/packages/core/src/util/ip-classifier.ts b/packages/core/src/util/ip-classifier.ts
new file mode 100644
index 000000000..448f63d39
--- /dev/null
+++ b/packages/core/src/util/ip-classifier.ts
@@ -0,0 +1,35 @@
+import ipaddr from 'ipaddr.js';
+
+type ParsedIp = ipaddr.IPv4 | ipaddr.IPv6;
+
+export type HostClassification =
+ | { kind: 'hostname' }
+ | { kind: 'ip-literal'; allowed: boolean; canonical: string; family: 4 | 6 };
+
+function parseIpLiteral(host: string): ParsedIp | null {
+ const bare =
+ host.length >= 2 && host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+ try {
+ if (ipaddr.IPv4.isValid(bare)) return ipaddr.IPv4.parse(bare);
+ if (ipaddr.IPv6.isValid(bare)) return ipaddr.IPv6.parse(bare);
+ } catch {
+ return null;
+ }
+ return null;
+}
+
+export function isPublicUnicastIp(ip: string): boolean {
+ const parsed = parseIpLiteral(ip);
+ return parsed !== null && parsed.range() === 'unicast';
+}
+
+export function classifyHost(host: string): HostClassification {
+ const parsed = parseIpLiteral(host);
+ if (parsed === null) return { kind: 'hostname' };
+ return {
+ kind: 'ip-literal',
+ allowed: parsed.range() === 'unicast',
+ canonical: parsed.toString(),
+ family: parsed.kind() === 'ipv6' ? 6 : 4,
+ };
+}
diff --git a/packages/server/package.json b/packages/server/package.json
index 397bbb29e..9b0f69377 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -61,7 +61,6 @@
"happy-dom": "^20.10.2",
"hono": "^4.12.29",
"ignore": "^5.3.2",
- "ipaddr.js": "^2.3.0",
"jsonc-parser": "^3.3.1",
"just-bash": "2.14.5",
"mermaid": "^11.14.0",
diff --git a/packages/server/src/api-skill-policy-errors.test.ts b/packages/server/src/api-skill-policy-errors.test.ts
new file mode 100644
index 000000000..0083da70f
--- /dev/null
+++ b/packages/server/src/api-skill-policy-errors.test.ts
@@ -0,0 +1,133 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, beforeEach, expect, test, vi } from 'vitest';
+import type { BootedServer } from './boot.ts';
+import { bootCompositionRig, rawRequest } from './composition-rig.test-helper.ts';
+import { readSkillsLockFile } from './skills-lock-store.ts';
+
+const scenario = vi.hoisted(() => ({ mode: 'real' as 'real' | 'bulk-files' | 'generic' }));
+vi.mock('@inkeep/open-knowledge-core/skills-catalog', async (original) => {
+ const actual = await original<typeof import('@inkeep/open-knowledge-core/skills-catalog')>();
+ return {
+ ...actual,
+ readWellKnownIndex: (...args: Parameters<typeof actual.readWellKnownIndex>) =>
+ scenario.mode === 'bulk-files'
+ ? Promise.resolve({
+ basePath: '/.well-known/agent-skills',
+ skills: [{ name: 'fixture', description: '', files: ['SKILL.md'] }],
+ })
+ : actual.readWellKnownIndex(...args),
+ fetchSource: (...args: Parameters<typeof actual.fetchSource>) => {
+ if (scenario.mode === 'bulk-files' && args[0].kind === 'well-known')
+ return Promise.reject(new actual.SkillDestinationPolicyError(args[0].origin));
+ return actual.fetchSource(...args);
+ },
+ discoverWellKnownSkills: (...args: Parameters<typeof actual.discoverWellKnownSkills>) =>
+ scenario.mode === 'generic'
+ ? Promise.reject(new actual.SkillFetchError('internal-cause-not-public'))
+ : actual.discoverWellKnownSkills(...args),
+ };
+});
+
+let root: string;
+let server: BootedServer;
+beforeAll(async () => {
+ root = mkdtempSync(join(tmpdir(), 'skill-policy-http-'));
+ mkdirSync(join(root, '.claude'));
+ server = await bootCompositionRig(root);
+ await server.ready;
+}, 60_000);
+beforeEach(() => {
+ scenario.mode = 'real';
+});
+afterAll(async () => {
+ await server?.destroy();
+ rmSync(root, { recursive: true, force: true });
+});
+
+function post(path: string, body: object) {
+ return rawRequest(server.port, path, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(body),
+ });
+}
+
+test.each([
+ ['discover', '/api/skills/discover?source=127.0.0.1', null],
+ ['preview', '/api/skills/preview?source=127.0.0.1&name=fixture', null],
+ ['single import', '/api/skill/import', { source: '127.0.0.1', skill: 'fixture', install: false }],
+ [
+ 'bulk index',
+ '/api/skills/import-bulk',
+ { source: '127.0.0.1', skills: ['fixture'], install: false },
+ ],
+] as const)(
+ 'publishes a single actionable private-origin remedy for %s',
+ async (_name, path, body) => {
+ const response = body === null ? await rawRequest(server.port, path) : await post(path, body);
+ expect(response.status, response.body).toBe(400);
+ const problem = JSON.parse(response.body);
+ expect(problem.title).toBe('Website source requires explicit trust.');
+ expect(problem.detail.split('https://127.0.0.1')).toHaveLength(2);
+ expect(problem.detail.split('skills.trustedPrivateOrigins')).toHaveLength(2);
+ },
+);
+
+test('bulk per-skill policy failures are failed with the remedy, not not-found', async () => {
+ scenario.mode = 'bulk-files';
+ const response = await post('/api/skills/import-bulk', {
+ source: '127.0.0.1',
+ skills: ['fixture'],
+ install: false,
+ });
+ expect(response.status, response.body).toBe(200);
+ expect(JSON.parse(response.body)).toMatchObject({
+ failed: 1,
+ results: [
+ {
+ requested: 'fixture',
+ status: 'failed',
+ error: expect.stringContaining('skills.trustedPrivateOrigins'),
+ },
+ ],
+ });
+});
+
+test('ordinary fetch failures keep their internal cause out of public details', async () => {
+ scenario.mode = 'generic';
+ const response = await rawRequest(server.port, '/api/skills/discover?source=127.0.0.1');
+ expect(response.status, response.body).toBe(400);
+ expect(response.body).not.toContain('internal-cause-not-public');
+ expect(JSON.parse(response.body).detail).toBeUndefined();
+});
+
+test('reimport of a formerly approved website source publishes the remedy', async () => {
+ const name = 'policy-reimport';
+ const source = join(root, 'source', name);
+ mkdirSync(source, { recursive: true });
+ writeFileSync(
+ join(source, 'SKILL.md'),
+ `---\nname: ${name}\ndescription: Synthetic fixture\n---\n\nFixture.\n`,
+ );
+ const imported = await post('/api/skill/import', { source, install: false });
+ expect(imported.status, imported.body).toBe(200);
+ const file = join(root, '.ok', 'skills-lock.json');
+ const lock = readSkillsLockFile(file);
+ const entry = lock.skills[name];
+ if (!entry) throw new Error('Expected imported skill');
+ writeFileSync(
+ file,
+ JSON.stringify({
+ ...lock,
+ skills: { ...lock.skills, [name]: { ...entry, source: '127.0.0.1', upstreamSkill: name } },
+ }),
+ );
+ const response = await post('/api/skill/reimport', { name, scope: 'project' });
+ expect(response.status, response.body).toBe(400);
+ expect(JSON.parse(response.body)).toMatchObject({
+ title: 'Website source requires explicit trust.',
+ detail: expect.stringContaining('https://127.0.0.1'),
+ });
+});
diff --git a/packages/server/src/http/error-response.ts b/packages/server/src/http/error-response.ts
index b9db0c336..85e3f1b04 100644
--- a/packages/server/src/http/error-response.ts
+++ b/packages/server/src/http/error-response.ts
@@ -8,6 +8,7 @@ import {
StreamingProblemEventSchema,
stripPathspecMagic,
} from '@inkeep/open-knowledge-core';
+import { SkillDestinationPolicyError } from '@inkeep/open-knowledge-core/skills-catalog';
import type { Counter } from '@opentelemetry/api';
import { PrivateStateSymlinkError, SymlinkEscapeError } from '../fs-safety.ts';
import { getLogger } from '../logger.ts';
@@ -74,6 +75,12 @@ export function errorResponse(
title: string,
options: ErrorResponseOptions = {},
): void {
+ if (options.cause instanceof SkillDestinationPolicyError) {
+ status = 400;
+ type = 'urn:ok:error:invalid-request';
+ title = 'Website source requires explicit trust.';
+ options = { ...options, detail: options.cause.message };
+ }
if (
status === 500 &&
options.cause instanceof SymlinkEscapeError &&
diff --git a/packages/server/src/http/skills-import-routes.ts b/packages/server/src/http/skills-import-routes.ts
index b5f8f255b..d9fbc65e2 100644
--- a/packages/server/src/http/skills-import-routes.ts
+++ b/packages/server/src/http/skills-import-routes.ts
@@ -22,6 +22,7 @@ import {
readSkillDirMeta,
readWellKnownIndex,
resolveSkillsShImportSource,
+ SkillDestinationPolicyError,
SkillFetchError,
type SourceSpec,
type WellKnownIndex,
@@ -356,12 +357,16 @@ export function createSkillsImportRoutes(deps: SkillsImportRouteDeps): ApiRouteG
perSkill = one.cleanup;
upstreamSkill = requested;
} catch (e) {
+ const notFound =
+ e instanceof SkillFetchError && !(e instanceof SkillDestinationPolicyError);
results.push({
requested,
- status: e instanceof SkillFetchError ? 'not-found' : 'failed',
+ status: notFound ? 'not-found' : 'failed',
warnings: [],
warningCodes: [],
- ...(e instanceof SkillFetchError ? {} : { error: String(e) }),
+ ...(notFound
+ ? {}
+ : { error: e instanceof SkillDestinationPolicyError ? e.message : String(e) }),
});
continue;
}
diff --git a/packages/server/src/link-preview/ip-classifier.ts b/packages/server/src/link-preview/ip-classifier.ts
index 448f63d39..0413e488a 100644
--- a/packages/server/src/link-preview/ip-classifier.ts
+++ b/packages/server/src/link-preview/ip-classifier.ts
@@ -1,35 +1,4 @@
-import ipaddr from 'ipaddr.js';
-
-type ParsedIp = ipaddr.IPv4 | ipaddr.IPv6;
-
-export type HostClassification =
- | { kind: 'hostname' }
- | { kind: 'ip-literal'; allowed: boolean; canonical: string; family: 4 | 6 };
-
-function parseIpLiteral(host: string): ParsedIp | null {
- const bare =
- host.length >= 2 && host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
- try {
- if (ipaddr.IPv4.isValid(bare)) return ipaddr.IPv4.parse(bare);
- if (ipaddr.IPv6.isValid(bare)) return ipaddr.IPv6.parse(bare);
- } catch {
- return null;
- }
- return null;
-}
-
-export function isPublicUnicastIp(ip: string): boolean {
- const parsed = parseIpLiteral(ip);
- return parsed !== null && parsed.range() === 'unicast';
-}
-
-export function classifyHost(host: string): HostClassification {
- const parsed = parseIpLiteral(host);
- if (parsed === null) return { kind: 'hostname' };
- return {
- kind: 'ip-literal',
- allowed: parsed.range() === 'unicast',
- canonical: parsed.toString(),
- family: parsed.kind() === 'ipv6' ? 6 : 4,
- };
-}
+export {
+ classifyHost,
+ isPublicUnicastIp,
+} from '@inkeep/open-knowledge-core/server';
diff --git a/packages/server/src/private-skill-trust-admission.test.ts b/packages/server/src/private-skill-trust-admission.test.ts
new file mode 100644
index 000000000..c55ab0b1c
--- /dev/null
+++ b/packages/server/src/private-skill-trust-admission.test.ts
@@ -0,0 +1,560 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { setImmediate } from 'node:timers/promises';
+import { MessageType } from '@hocuspocus/server';
+import { CONFIG_DOC_NAME_USER, okUserHomeDisplayPath } from '@inkeep/open-knowledge-core';
+import { resolveConfigPath, writeConfigPatch } from '@inkeep/open-knowledge-core/server';
+import * as decoding from 'lib0/decoding';
+import * as encoding from 'lib0/encoding';
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+import { WebSocket } from 'ws';
+import { parse } from 'yaml';
+import * as Y from 'yjs';
+import type { BootedServer } from './boot.ts';
+import { bootCompositionRig } from './composition-rig.test-helper.ts';
+import * as configFileWatcher from './config-file-watcher.ts';
+import { getLogger } from './logger.ts';
+
+const origin = 'https://skills.intranet.example:8443';
+let root: string;
+let file: string;
+let server: BootedServer | undefined;
+const sockets: WebSocket[] = [];
+const docs: Y.Doc[] = [];
+
+beforeEach(() => {
+ root = mkdtempSync(join(tmpdir(), 'skill-trust-admission-'));
+});
+afterEach(async () => {
+ for (const socket of sockets.splice(0)) socket.terminate();
+ await server?.destroy();
+ server = undefined;
+ for (const doc of docs.splice(0)) doc.destroy();
+ rmSync(root, { recursive: true, force: true });
+ vi.restoreAllMocks();
+ vi.unstubAllEnvs();
+});
+
+async function start(source = 'skills: {trustedPrivateOrigins: []}\nappearance: {theme: light}\n') {
+ const home = join(root, 'home');
+ file = resolveConfigPath('user', root, home);
+ mkdirSync(dirname(file), { recursive: true });
+ writeFileSync(file, source);
+ server = await bootCompositionRig(root, {
+ configHomedirOverride: home,
+ debounce: 1,
+ maxDebounce: 2,
+ serverRuntime: {
+ port: undefined,
+ bind: ['127.0.0.1'],
+ externalUrl: 'http://remote.example',
+ allowExternal: true,
+ openBrowser: false,
+ idleShutdown: 'off',
+ loopbackOnly: true,
+ },
+ });
+ return server;
+}
+
+async function client(headers: Record<string, string>) {
+ if (!server) throw new Error('Expected composed server');
+ const doc = new Y.Doc();
+ docs.push(doc);
+ const ws = new WebSocket(`ws://127.0.0.1:${server.port}/collab`, { headers });
+ sockets.push(ws);
+ const ready = Promise.withResolvers<void>();
+ let closed: { code?: number; reason: string } | undefined;
+ const acknowledgements: boolean[] = [];
+ function send(update: Uint8Array, type = 2) {
+ const encoder = encoding.createEncoder();
+ encoding.writeVarString(encoder, CONFIG_DOC_NAME_USER);
+ encoding.writeVarUint(encoder, MessageType.Sync);
+ encoding.writeVarUint(encoder, type);
+ encoding.writeVarUint8Array(encoder, update);
+ ws.send(encoding.toUint8Array(encoder));
+ }
+ ws.on('close', (code, reason) => {
+ closed = { code, reason: reason.toString() };
+ });
+ ws.on('message', (bytes) => {
+ const decoder = decoding.createDecoder(new Uint8Array(bytes as Buffer));
+ decoding.readVarString(decoder);
+ const kind = decoding.readVarUint(decoder);
+ if (kind === MessageType.Auth) {
+ const status = decoding.readVarUint(decoder);
+ if (status !== 2) {
+ ready.reject(new Error('Expected authentication success'));
+ return;
+ }
+ send(Y.encodeStateVector(doc), 0);
+ } else if (kind === MessageType.Sync || kind === MessageType.SyncReply) {
+ const type = decoding.readVarUint(decoder);
+ const update = decoding.readVarUint8Array(decoder);
+ if (type === 0) send(Y.encodeStateAsUpdate(doc, update), 1);
+ else {
+ Y.applyUpdate(doc, update);
+ ready.resolve();
+ }
+ } else if (kind === MessageType.SyncStatus) {
+ acknowledgements.push(decoding.readVarUint(decoder) === 1);
+ } else if (kind === MessageType.CLOSE) {
+ closed = { reason: decoding.readVarString(decoder) };
+ ready.reject(new Error(closed.reason));
+ }
+ });
+ await new Promise<void>((resolve, reject) => {
+ ws.once('open', resolve);
+ ws.once('error', reject);
+ });
+ ws.on('error', ready.reject);
+ const auth = encoding.createEncoder();
+ encoding.writeVarString(auth, CONFIG_DOC_NAME_USER);
+ encoding.writeVarUint(auth, MessageType.Auth);
+ encoding.writeVarUint(auth, 0);
+ encoding.writeVarString(auth, '');
+ ws.send(encoding.toUint8Array(auth));
+ await ready.promise;
+ await viWait(() => expect(acknowledgements.length).toBeGreaterThan(0));
+ return {
+ doc,
+ send,
+ get closed() {
+ return closed;
+ },
+ get acknowledgements() {
+ return acknowledgements;
+ },
+ change(fn: (text: Y.Text) => void) {
+ const vector = Y.encodeStateVector(doc);
+ doc.transact(() => fn(doc.getText('source')));
+ return Y.encodeStateAsUpdate(doc, vector);
+ },
+ };
+}
+
+async function viWait(assertion: () => void) {
+ await vi.waitFor(assertion, { timeout: 10_000 });
+}
+
+const remoteHeaders = { Host: 'remote.example', Origin: 'http://remote.example' };
+const localHeaders = { Host: 'localhost', Origin: 'http://localhost' };
+
+test.each([1, 2])(
+ 'refuses new private approvals over the actual remote sync type %s',
+ async (type) => {
+ await start();
+ const peer = await client(remoteHeaders);
+ const update = peer.change((text) => {
+ const start = text.toString().indexOf('[]');
+ text.delete(start, 2);
+ text.insert(start, `[${origin}]`);
+ });
+ const previous = peer.acknowledgements.length;
+ peer.send(update, type);
+ await viWait(() =>
+ expect(peer.closed !== undefined || peer.acknowledgements.length > previous).toBe(true),
+ );
+ if (peer.closed === undefined) {
+ await viWait(() =>
+ expect(parse(readFileSync(file, 'utf8')).skills.trustedPrivateOrigins).toEqual([origin]),
+ );
+ }
+ expect(parse(readFileSync(file, 'utf8')).skills.trustedPrivateOrigins).toEqual([]);
+ expect(peer.closed?.reason).toContain('computer');
+ expect(peer.closed?.reason).toContain(okUserHomeDisplayPath('global.yml'));
+ },
+);
+
+test.each([1, 2])(
+ 'refuses collab approvals even for a local-looking client over sync type %s',
+ async (type) => {
+ await start();
+ const peer = await client(localHeaders);
+ const previous = peer.acknowledgements.length;
+ peer.send(
+ peer.change((text) => {
+ const at = text.toString().indexOf('[]');
+ text.delete(at, 2);
+ text.insert(at, `[${origin}]`);
+ }),
+ type,
+ );
+ await viWait(() =>
+ expect(peer.closed !== undefined || peer.acknowledgements.length > previous).toBe(true),
+ );
+ if (peer.closed === undefined)
+ await viWait(() =>
+ expect(parse(readFileSync(file, 'utf8')).skills.trustedPrivateOrigins).toEqual([origin]),
+ );
+ expect(parse(readFileSync(file, 'utf8')).skills.trustedPrivateOrigins).toEqual([]);
+ expect(peer.closed?.reason).toContain('global.yml');
+ },
+);
+
+test('native user-file approval wins over a stale collaboration settings save', async () => {
+ let holdWatcher = false;
+ const delayed: (() => void)[] = [];
+ const original = configFileWatcher.startConfigFileWatcher;
+ vi.spyOn(configFileWatcher, 'startConfigFileWatcher').mockImplementation((path, onChange) =>
+ original(path, (content) => {
+ if (path === file && holdWatcher) delayed.push(() => onChange(content));
+ else onChange(content);
+ }),
+ );
+ const booted = await start();
+ const peer = await client(remoteHeaders);
+ expect(peer.doc.getText('source').toString()).not.toContain(origin);
+ const update = peer.change((text) => {
+ const at = text.toString().indexOf('light');
+ text.delete(at, 5);
+ text.insert(at, 'dark');
+ });
+ const stored = Promise.withResolvers<void>();
+ booted.serverInstance.hocuspocus.configuration.extensions.push({
+ async afterStoreDocument({ documentName }) {
+ if (documentName === CONFIG_DOC_NAME_USER) stored.resolve();
+ },
+ });
+ holdWatcher = true;
+ try {
+ const result = await writeConfigPatch({
+ cwd: root,
+ scope: 'user',
+ homedirOverride: join(root, 'home'),
+ patch: { skills: { trustedPrivateOrigins: [origin] } },
+ });
+ expect(result.ok).toBe(true);
+ expect(peer.doc.getText('source').toString()).not.toContain(origin);
+ const previous = peer.acknowledgements.length;
+ peer.send(update);
+ await viWait(() =>
+ expect(peer.closed !== undefined || peer.acknowledgements.length > previous).toBe(true),
+ );
+ expect(peer.closed).toBeUndefined();
+ expect(peer.acknowledgements.at(-1)).toBe(true);
+ await stored.promise;
+ expect(parse(readFileSync(file, 'utf8')).skills.trustedPrivateOrigins).toEqual([origin]);
+ expect(parse(readFileSync(file, 'utf8')).appearance.theme).toBe('light');
+ await viWait(() => expect(peer.doc.getText('source').toString()).toContain(origin));
+ } finally {
+ holdWatcher = false;
+ for (const apply of delayed) apply();
+ }
+});
+
+test.each(['skills: [', 'skills: {'])(
+ 'allows unchanged malformed user-file handshakes and a repair without new trust: %s',
+ async (source) => {
+ await start(source);
+ const warn = vi.spyOn(getLogger('server'), 'warn');
+ const peer = await client(localHeaders);
+ expect(peer.doc.getText('source').toString()).toBe(source);
+ expect(peer.closed).toBeUndefined();
+ const previous = peer.acknowledgements.length;
+ peer.send(Y.encodeStateAsUpdate(peer.doc));
+ await viWait(() =>
+ expect(peer.closed !== undefined || peer.acknowledgements.length > previous).toBe(true),
+ );
+ expect(peer.closed).toBeUndefined();
+ expect(peer.acknowledgements.at(-1)).toBe(true);
+ expect(readFileSync(file, 'utf8')).toBe(source);
+ expect(
+ warn.mock.calls.filter(
+ ([event]) =>
+ typeof event === 'object' &&
+ event !== null &&
+ 'check' in event &&
+ event.check === 'private-skill-trust',
+ ),
+ ).toHaveLength(0);
+ peer.send(
+ peer.change((text) => {
+ text.delete(0, text.length);
+ text.insert(0, 'skills: {trustedPrivateOrigins: []}\nappearance: {theme: dark}\n');
+ }),
+ );
+ await viWait(() => expect(parse(readFileSync(file, 'utf8')).appearance.theme).toBe('dark'));
+ expect(peer.closed).toBeUndefined();
+ },
+);
+
+test.each(['skills: [', 'skills: {'])(
+ 'a malformed base cannot be repaired with a new private grant: %s',
+ async (source) => {
+ await start(source);
+ const peer = await client(remoteHeaders);
+ const previous = peer.acknowledgements.length;
+ peer.send(
+ peer.change((text) => {
+ text.delete(0, text.length);
+ text.insert(0, `skills: {trustedPrivateOrigins: [${origin}]}\n`);
+ }),
+ );
+ await viWait(() =>
+ expect(peer.closed !== undefined || peer.acknowledgements.length > previous).toBe(true),
+ );
+ if (peer.closed === undefined) {
+ await viWait(() =>
+ expect(parse(readFileSync(file, 'utf8')).skills.trustedPrivateOrigins).toEqual([origin]),
+ );
+ }
+ expect(readFileSync(file, 'utf8')).toBe(source);
+ expect(peer.closed?.reason).toContain(okUserHomeDisplayPath('global.yml'));
+ },
+);
+
+test('a malformed base does not authorize a different malformed source', async () => {
+ const source = 'skills: [';
+ await start(source);
+ const peer = await client(remoteHeaders);
+ const previous = peer.acknowledgements.length;
+ peer.send(
+ peer.change((text) => {
+ text.delete(0, text.length);
+ text.insert(0, 'skills: {');
+ }),
+ );
+ await viWait(() =>
+ expect(peer.closed !== undefined || peer.acknowledgements.length > previous).toBe(true),
+ );
+ expect(readFileSync(file, 'utf8')).toBe(source);
+ expect(peer.closed?.reason).toContain('valid YAML');
+});
+
+test('grant refusals resolve the user-file display path at the time of refusal', async () => {
+ await start();
+ const peer = await client(remoteHeaders);
+ vi.stubEnv('OK_CHANNEL', 'beta');
+ peer.send(
+ peer.change((text) => {
+ const at = text.toString().indexOf('[]');
+ text.delete(at, 2);
+ text.insert(at, `[${origin}]`);
+ }),
+ );
+ await viWait(() => expect(peer.closed).toBeDefined());
+ expect(peer.closed?.reason).toContain('~/.ok-beta/global.yml');
+});
+
+test.each([{ Host: 'localhost' }, { ...localHeaders, Origin: 'file://' }])(
+ 'local-looking or desktop headers do not grant filesystem approval authority: %j',
+ async (headers) => {
+ await start();
+ const peer = await client(headers),
+ previous = peer.acknowledgements.length;
+ peer.send(
+ peer.change((text) => {
+ const at = text.toString().indexOf('[]');
+ text.delete(at, 2);
+ text.insert(at, `[${origin}]`);
+ }),
+ );
+ await viWait(() =>
+ expect(peer.closed !== undefined || peer.acknowledgements.length > previous).toBe(true),
+ );
+ if (peer.closed === undefined)
+ await viWait(() =>
+ expect(parse(readFileSync(file, 'utf8')).skills.trustedPrivateOrigins).toEqual([origin]),
+ );
+ expect(parse(readFileSync(file, 'utf8')).skills.trustedPrivateOrigins).toEqual([]);
+ },
+);
+
+test('preserves remote revocation and unrelated settings edits', async () => {
+ await start(`skills: {trustedPrivateOrigins: [${origin}]}\nappearance: {theme: light}\n`);
+ const peer = await client(remoteHeaders);
+ peer.send(
+ peer.change((text) => {
+ const at = text.toString().indexOf('light');
+ text.delete(at, 5);
+ text.insert(at, 'dark');
+ }),
+ );
+ await viWait(() => expect(parse(readFileSync(file, 'utf8')).appearance.theme).toBe('dark'));
+ peer.send(
+ peer.change((text) => {
+ const at = text.toString().indexOf(origin);
+ text.delete(at, origin.length);
+ }),
+ );
+ await viWait(() =>
+ expect(parse(readFileSync(file, 'utf8')).skills.trustedPrivateOrigins).toEqual([]),
+ );
+ expect(peer.closed).toBeUndefined();
+});
+
+test('drains an owning connection queue and releases it after a rejected peer', async () => {
+ await start();
+ const remote = await client(remoteHeaders);
+ const denied = remote.change((text) => {
+ const at = text.toString().indexOf('[]');
+ text.delete(at, 2);
+ text.insert(at, `[${origin}]`);
+ });
+ remote.send(denied);
+ remote.send(denied);
+ await viWait(() => expect(remote.closed).toBeDefined());
+ const local = await client(localHeaders);
+ const theme = local.change((text) => {
+ const at = text.toString().indexOf('light');
+ text.delete(at, 5);
+ text.insert(at, 'dark');
+ });
+ const following = local.change((text) => {
+ text.insert(text.length, 'unrelated: fixture\n');
+ });
+ local.send(theme);
+ local.send(following);
+ await viWait(() =>
+ expect(parse(readFileSync(file, 'utf8'))).toMatchObject({
+ skills: { trustedPrivateOrigins: [] },
+ appearance: { theme: 'dark' },
+ unrelated: 'fixture',
+ }),
+ );
+ expect(local.closed).toBeUndefined();
+});
+
+test('refuses a remote update whose missing dependencies could be completed later', async () => {
+ await start();
+ const remote = await client(remoteHeaders);
+ const before = readFileSync(file, 'utf8');
+ remote.change((text) => text.insert(text.length, 'unrelated: "'));
+ const delayed = remote.change((text) => text.insert(text.length, 'fixture"\n'));
+ remote.send(delayed);
+ await viWait(() => expect(remote.closed).toBeDefined());
+ expect(remote.closed?.reason).toContain('synchronized');
+ expect(readFileSync(file, 'utf8')).toBe(before);
+});
+
+test.each(['grant', 'invalid-update'] as const)(
+ 'logs a bounded refusal class and a matching client reason for %s',
+ async (mode) => {
+ await start();
+ const peer = await client(remoteHeaders);
+ const warn = vi.spyOn(getLogger('server'), 'warn');
+ const before = readFileSync(file, 'utf8');
+ peer.send(
+ mode === 'grant'
+ ? peer.change((text) => {
+ const at = text.toString().indexOf('[]');
+ text.delete(at, 2);
+ text.insert(at, `[${origin}]`);
+ })
+ : new Uint8Array([255, 255]),
+ );
+ await viWait(() => expect(peer.closed).toBeDefined());
+ const records = warn.mock.calls.filter(
+ ([event]) =>
+ typeof event === 'object' &&
+ event !== null &&
+ 'check' in event &&
+ event.check === 'private-skill-trust',
+ );
+ expect(records).toHaveLength(1);
+ expect(records[0]).toEqual([
+ expect.objectContaining({
+ reason: 'config-doc-admission-denied',
+ docName: CONFIG_DOC_NAME_USER,
+ rejectionClass: mode === 'grant' ? 'new-private-origin' : 'invalid-update',
+ }),
+ '[auth-rejection] config-doc-admission-denied',
+ ]);
+ expect(peer.closed?.reason).toContain(mode === 'grant' ? 'global.yml' : 'serialized');
+ expect(JSON.stringify(records)).not.toContain(origin);
+ expect(readFileSync(file, 'utf8')).toBe(before);
+ },
+);
+
+test.each(['skills: [', 'skills: *missing\n', '- fixture\n'])(
+ 'refuses invalid remote configuration without granting trust: %s',
+ async (invalid) => {
+ await start();
+ const remote = await client(remoteHeaders);
+ const before = readFileSync(file, 'utf8');
+ remote.send(
+ remote.change((text) => {
+ text.delete(0, text.length);
+ text.insert(0, invalid);
+ }),
+ );
+ await viWait(() => expect(remote.closed).toBeDefined());
+ expect(remote.closed?.reason).toContain('valid YAML');
+ expect(readFileSync(file, 'utf8')).toBe(before);
+ },
+);
+
+test.each([
+ { Host: 'localhost', Origin: 'http://remote.example' },
+ { ...localHeaders, 'X-Forwarded-For': '203.0.113.8' },
+])('rejects new approvals with remote-origin or forwarded headers: %j', async (headers) => {
+ await start();
+ const peer = await client(headers);
+ peer.send(
+ peer.change((text) => {
+ const at = text.toString().indexOf('[]');
+ text.delete(at, 2);
+ text.insert(at, `[${origin}]`);
+ }),
+ );
+ await viWait(() => expect(peer.closed).toBeDefined());
+ expect(parse(readFileSync(file, 'utf8')).skills.trustedPrivateOrigins).toEqual([]);
+});
+
+test('serializes concurrent remote YAML-alias edits before admission', async () => {
+ const booted = await start('policy: &policy {trustedPrivateOrigins: []}\nskills: {}\n');
+ const a = await client(remoteHeaders),
+ b = await client(remoteHeaders);
+ const updateA = a.change((text) => {
+ const at = text.toString().indexOf('[]');
+ text.delete(at, 2);
+ text.insert(at, `[${origin}]`);
+ });
+ const updateB = b.change((text) => {
+ const at = text.toString().indexOf('skills: {}') + 8;
+ text.delete(at, 2);
+ text.insert(at, '*policy');
+ });
+ const entered = Promise.withResolvers<void>(),
+ release = Promise.withResolvers<void>(),
+ second = Promise.withResolvers<void>();
+ let messages = 0,
+ passed = 0;
+ const previousA = a.acknowledgements.length,
+ previousB = b.acknowledgements.length;
+ booted.serverInstance.hocuspocus.configuration.extensions.unshift({
+ async beforeHandleMessage() {
+ if (++messages === 2) second.resolve();
+ },
+ });
+ booted.serverInstance.hocuspocus.configuration.extensions.push({
+ async beforeSync({ type }) {
+ if (type !== 2) return;
+ if (++passed === 1) {
+ entered.resolve();
+ await release.promise;
+ }
+ },
+ });
+ try {
+ a.send(updateA);
+ await entered.promise;
+ b.send(updateB);
+ await second.promise;
+ await setImmediate();
+ } finally {
+ release.resolve();
+ }
+ await viWait(() => {
+ expect(a.closed !== undefined || a.acknowledgements.length > previousA).toBe(true);
+ expect(b.closed !== undefined || b.acknowledgements.length > previousB).toBe(true);
+ });
+ if (a.closed === undefined && b.closed === undefined) {
+ await viWait(() =>
+ expect(parse(readFileSync(file, 'utf8')).skills.trustedPrivateOrigins).toEqual([origin]),
+ );
+ }
+ expect(parse(readFileSync(file, 'utf8')).skills?.trustedPrivateOrigins ?? []).toEqual([]);
+}, 30_000);
diff --git a/packages/server/src/private-skill-trust-admission.ts b/packages/server/src/private-skill-trust-admission.ts
new file mode 100644
index 000000000..8b5a05c1c
--- /dev/null
+++ b/packages/server/src/private-skill-trust-admission.ts
@@ -0,0 +1,96 @@
+import type { Connection, Extension } from '@hocuspocus/server';
+import {
+ CONFIG_DOC_NAME_USER,
+ ConfigSchema,
+ okUserHomeDisplayPath,
+} from '@inkeep/open-knowledge-core';
+import { parseDocument } from 'yaml';
+import * as Y from 'yjs';
+
+const skillConfigSchema = ConfigSchema.pick({ skills: true });
+
+function approvedOrigins(source: string): Set<string> | null {
+ try {
+ const yaml = parseDocument(source);
+ if (yaml.errors.length > 0) return null;
+ const parsed = skillConfigSchema.safeParse(yaml.toJS() ?? {});
+ return parsed.success
+ ? new Set(parsed.data.skills.trustedPrivateOrigins.filter((origin) => origin !== null))
+ : null;
+ } catch {
+ return null;
+ }
+}
+
+const rejectionReasons = {
+ 'invalid-config': 'Configuration updates must contain valid YAML configuration.',
+ 'unresolved-update':
+ 'Configuration updates must be fully synchronized; reconnect before retrying.',
+ 'invalid-update': 'Configuration updates must contain a valid serialized document update.',
+ 'new-private-origin': () =>
+ `Edit ${okUserHomeDisplayPath('global.yml')} on the computer running OpenKnowledge to approve private website skill origins.`,
+};
+
+interface ConfigMessageLease {
+ connection: Connection;
+ processing: Promise<void>;
+}
+
+export function createPrivateSkillTrustAdmission(
+ onRejected: (rejection: keyof typeof rejectionReasons) => void,
+): Extension {
+ const leases = new WeakMap<Y.Doc, ConfigMessageLease>();
+ return {
+ async beforeHandleMessage({ documentName, document, connection }) {
+ if (documentName !== CONFIG_DOC_NAME_USER) return;
+ await Promise.resolve();
+ while (true) {
+ const held = leases.get(document);
+ if (held === undefined || held.connection === connection) break;
+ await held.processing;
+ }
+ const processing = connection.waitForPendingMessages();
+ if (leases.get(document)?.processing === processing) return;
+ const lease = { connection, processing };
+ leases.set(document, lease);
+ const release = () => {
+ if (leases.get(document) === lease) leases.delete(document);
+ };
+ void processing.then(release, release);
+ },
+ async beforeSync({ documentName, document, connection, type, payload }) {
+ if (documentName !== CONFIG_DOC_NAME_USER || (type !== 1 && type !== 2)) return;
+ const currentSource = document.getText('source').toString();
+ const before = approvedOrigins(currentSource) ?? new Set();
+ const preview = new Y.Doc();
+ let rejection: keyof typeof rejectionReasons | undefined;
+ try {
+ Y.applyUpdate(preview, Y.encodeStateAsUpdate(document));
+ try {
+ Y.applyUpdate(preview, payload);
+ } catch {
+ rejection = 'invalid-update';
+ }
+ if (rejection === undefined) {
+ const resultingSource = preview.getText('source').toString();
+ const after = approvedOrigins(resultingSource);
+ if (!Y.snapshotContainsUpdate(Y.snapshot(preview), payload))
+ rejection = 'unresolved-update';
+ else if (resultingSource !== currentSource && after === null)
+ rejection = 'invalid-config';
+ else if (after !== null && [...after].some((origin) => !before.has(origin)))
+ rejection = 'new-private-origin';
+ }
+ } finally {
+ preview.destroy();
+ }
+ if (rejection !== undefined) {
+ connection.readOnly = true;
+ onRejected(rejection);
+ const refusal = rejectionReasons[rejection];
+ const reason = typeof refusal === 'function' ? refusal() : refusal;
+ throw Object.assign(new Error(reason), { code: 4403, reason });
+ }
+ },
+ };
+}
diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.ts
index 0c00511d6..69c56cf50 100644
--- a/packages/server/src/server-factory.ts
+++ b/packages/server/src/server-factory.ts
@@ -293,6 +293,7 @@ import {
StructuralDiskReadError,
} from './persistence-staleness-watchdog.ts';
import { loadPrincipal } from './principal.ts';
+import { createPrivateSkillTrustAdmission } from './private-skill-trust-admission.ts';
import { RecentlyRemovedDocs } from './recently-removed-docs.ts';
import { type ReconcileOutcome, reconcile } from './reconciliation.ts';
import { reconcileRecoveredFileTarget } from './recovered-file-target.ts';
@@ -2612,6 +2613,14 @@ export function createServer(options: ServerOptions): ServerInstance {
},
};
hocuspocus.configuration.extensions.push(configDocAdmissionGuard);
+ hocuspocus.configuration.extensions.push(
+ createPrivateSkillTrustAdmission((rejectionClass) =>
+ logAuthRejection('config-doc-admission-denied', CONFIG_DOC_NAME_USER, {
+ check: 'private-skill-trust',
+ rejectionClass,
+ }),
+ ),
+ );
const removalRedirectGuard: Extension & { __kind: 'removal-redirect-guard' } = {
__kind: 'removal-redirect-guard',
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4c1fcb2be..363334d86 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1014,6 +1014,9 @@ importers:
diff-match-patch:
specifier: ^1.0.5
version: 1.0.5
+ ipaddr.js:
+ specifier: ^2.3.0
+ version: 2.4.0
markdownlint:
specifier: ^0.41.0
version: 0.41.1([email protected])
@@ -1092,6 +1095,9 @@ importers:
remend:
specifier: 1.3.0
version: 1.3.0
+ undici:
+ specifier: ~7.29.0
+ version: 7.29.0
unified:
specifier: ^11.0.5
version: 11.0.5
@@ -1367,9 +1373,6 @@ importers:
ignore:
specifier: ^5.3.2
version: 5.3.2
- ipaddr.js:
- specifier: ^2.3.0
- version: 2.4.0
jsonc-parser:
specifier: ^3.3.1
version: 3.3.1