@qodo/sdk 0.13.3 → 2.0.0-next.0

package/dist/skills/trust.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Skills trust model.
+ *
+ * Tier is derived from `source.type` at discovery time and is stored on every
+ * `ParsedSkill` as `trustTier`. The collapsed 3-tier vocabulary
+ * (`'trusted' | 'operator' | 'third-party'`) maps the conceptual 4-tier
+ * (`bundled | project | user | third-party`) onto the policy boundary the SDK
+ * actually applies — bundled / project / config collapse to `'trusted'`,
+ * `user` is `'operator'` (trusted by default, distinct only for telemetry
+ * and policy tightening), and `package` / `cli-fetched` are `'third-party'`.
+ * This module reads the existing `trustTier` field rather than
+ * re-classifying.
+ *
+ * `trustedSources` is the opt-in allowlist that elevates third-party sources
+ * to the same policy as trusted ones. Entries key on **immutable source
+ * identity**:
+ *
+ *   - npm package name (`'@anthropic-skills/core'`) for `package` sources.
+ *   - Full source-spec key (`'package:@anthropic-skills/core'`,
+ *     `'cli-fetched:<ref>'`, `'config:<basename>'`) for the discriminated
+ *     forms.
+ *   - The literal strings `'project'`, `'user'`, `'bundled'` (already
+ *     trusted by default — accepted for forward-compat and explicit allow).
+ *
+ * Wildcards (`*`) are not supported. The author-declared `vendor:`
+ * frontmatter field is **never** consulted for trust — that field is for
+ * namespacing only.
+ */
+import type { ParsedSkill, SkillSource } from './types.js';
+/**
+ * Trust-related error thrown at construction time when `SkillsConfig.trustedSources`
+ * is malformed (e.g., wildcards, unmatched entries). Surfaces through the
+ * `SkillsManager` constructor so misconfiguration is loud.
+ */
+export declare class SkillsTrustConfigError extends Error {
+    readonly entry: string;
+    constructor(entry: string, reason: string);
+}
+/**
+ * Stable identity string for a `SkillSource`. Used both to compute the
+ * `trustedSources` lookup key and to validate `trustedSources` entries
+ * against the configured `sources` list. The output mirrors the manager's
+ * internal `sourceIdentity()` helper: `<type>:<discriminator>`, with a few
+ * shortcuts for the discriminator-less variants (`'project'`, `'user'`,
+ * `'bundled'`) that match the literal tier names a configurer is likely
+ * to type.
+ */
+export declare function sourceIdentityKey(source: SkillSource): string;
+/**
+ * Validate that every `trustedSources` entry matches a known source
+ * identity. Returns the normalized set of identity keys; throws
+ * `SkillsTrustConfigError` on wildcards, empty strings, or unmatched
+ * entries.
+ */
+export declare function validateTrustedSources(trustedSources: readonly string[] | undefined, configuredSources: readonly SkillSource[]): ReadonlySet<string>;
+/**
+ * Decide whether a skill is trusted enough to honor its declarative
+ * affordances (`allowed-tools`, `disable-model-invocation: false`,
+ * `hooks`).
+ *
+ * Rules:
+ *
+ *   - `trustTier === 'trusted'` (`project`/`config`/`bundled`) → always trusted.
+ *   - `trustTier === 'operator'` (`user`) → trusted by default. The operator
+ *     is the user running the SDK on their own box; treating their own files
+ *     as untrusted would require a flag they'd never set.
+ *   - `trustTier === 'third-party'` (`package`/`cli-fetched`) → trusted iff
+ *     the skill's source identity is in `trustedSourceIdentities` (the
+ *     pre-validated `Set` returned by `validateTrustedSources`).
+ */
+export declare function isSkillTrusted(skill: ParsedSkill, trustedSourceIdentities: ReadonlySet<string>): boolean;
+//# sourceMappingURL=trust.d.ts.map

package/dist/skills/trust.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust.d.ts","sourceRoot":"","sources":["../../src/skills/trust.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA2B3D;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,SAAgB,KAAK,EAAE,MAAM,CAAC;gBAElB,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAe7D;AAqCD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAC7C,iBAAiB,EAAE,SAAS,WAAW,EAAE,GACxC,WAAW,CAAC,MAAM,CAAC,CA8BrB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,EAClB,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3C,OAAO,CAGT"}

package/dist/skills/trust.js

@@ -0,0 +1,183 @@
+/**
+ * Skills trust model.
+ *
+ * Tier is derived from `source.type` at discovery time and is stored on every
+ * `ParsedSkill` as `trustTier`. The collapsed 3-tier vocabulary
+ * (`'trusted' | 'operator' | 'third-party'`) maps the conceptual 4-tier
+ * (`bundled | project | user | third-party`) onto the policy boundary the SDK
+ * actually applies — bundled / project / config collapse to `'trusted'`,
+ * `user` is `'operator'` (trusted by default, distinct only for telemetry
+ * and policy tightening), and `package` / `cli-fetched` are `'third-party'`.
+ * This module reads the existing `trustTier` field rather than
+ * re-classifying.
+ *
+ * `trustedSources` is the opt-in allowlist that elevates third-party sources
+ * to the same policy as trusted ones. Entries key on **immutable source
+ * identity**:
+ *
+ *   - npm package name (`'@anthropic-skills/core'`) for `package` sources.
+ *   - Full source-spec key (`'package:@anthropic-skills/core'`,
+ *     `'cli-fetched:<ref>'`, `'config:<basename>'`) for the discriminated
+ *     forms.
+ *   - The literal strings `'project'`, `'user'`, `'bundled'` (already
+ *     trusted by default — accepted for forward-compat and explicit allow).
+ *
+ * Wildcards (`*`) are not supported. The author-declared `vendor:`
+ * frontmatter field is **never** consulted for trust — that field is for
+ * namespacing only.
+ */
+/**
+ * POSIX/Windows path-basename without `node:path`. trust.ts is reachable
+ * from the universal `@qodo/sdk` bundle (re-exported by `src/index.ts`),
+ * which is browser-bundled via esbuild — and esbuild's universal target
+ * cannot resolve `node:path`. Reduces the path to its last segment by
+ * walking either separator.
+ */
+function pathBasename(p) {
+    if (p.length === 0)
+        return '';
+    let i = p.length - 1;
+    // Trim trailing separators.
+    while (i >= 0 && (p.charCodeAt(i) === 0x2f /* '/' */ || p.charCodeAt(i) === 0x5c /* '\\' */)) {
+        i -= 1;
+    }
+    if (i < 0)
+        return '';
+    const end = i + 1;
+    let start = i;
+    while (start > 0) {
+        const code = p.charCodeAt(start - 1);
+        if (code === 0x2f || code === 0x5c)
+            break;
+        start -= 1;
+    }
+    return p.slice(start, end);
+}
+/**
+ * Trust-related error thrown at construction time when `SkillsConfig.trustedSources`
+ * is malformed (e.g., wildcards, unmatched entries). Surfaces through the
+ * `SkillsManager` constructor so misconfiguration is loud.
+ */
+export class SkillsTrustConfigError extends Error {
+    entry;
+    constructor(entry, reason) {
+        super(`SkillsConfig.trustedSources entry ${JSON.stringify(entry)} is invalid: ${reason}`);
+        this.name = 'SkillsTrustConfigError';
+        this.entry = entry;
+    }
+}
+/**
+ * Stable identity string for a `SkillSource`. Used both to compute the
+ * `trustedSources` lookup key and to validate `trustedSources` entries
+ * against the configured `sources` list. The output mirrors the manager's
+ * internal `sourceIdentity()` helper: `<type>:<discriminator>`, with a few
+ * shortcuts for the discriminator-less variants (`'project'`, `'user'`,
+ * `'bundled'`) that match the literal tier names a configurer is likely
+ * to type.
+ */
+export function sourceIdentityKey(source) {
+    switch (source.type) {
+        case 'project':
+            return 'project';
+        case 'config':
+            return `config:${source.path}`;
+        case 'user':
+            return 'user';
+        case 'package':
+            return `package:${source.packageName}`;
+        case 'cli-fetched':
+            return source.ref !== undefined ? `cli-fetched:${source.ref}` : 'cli-fetched';
+        case 'bundled':
+            return 'bundled';
+    }
+}
+/**
+ * Aliases a `trustedSources` entry can take. We accept the long-form
+ * `package:<name>` AND the bare package name (`'@anthropic-skills/core'`)
+ * for ergonomics; the bare form is preferred.
+ */
+function aliasesForSource(source) {
+    switch (source.type) {
+        case 'package':
+            return [`package:${source.packageName}`, source.packageName];
+        case 'cli-fetched':
+            return source.ref !== undefined
+                ? [`cli-fetched:${source.ref}`, source.ref]
+                : ['cli-fetched'];
+        case 'project':
+            return ['project'];
+        case 'user':
+            return ['user'];
+        case 'bundled':
+            return ['bundled'];
+        case 'config': {
+            // `config:` always carries a `path`. Accept BOTH the full configured
+            // path and the basename — the manager already scrubs to basename
+            // for emitted telemetry, and the public `SkillsConfig` JSDoc
+            // documents `'config:my-skills.json'` as a valid trustedSources
+            // entry, so the basename alias has to validate.
+            const basename = pathBasename(source.path);
+            const aliases = [`config:${source.path}`];
+            if (basename.length > 0 && basename !== source.path) {
+                aliases.push(`config:${basename}`);
+            }
+            return aliases;
+        }
+    }
+}
+/**
+ * Validate that every `trustedSources` entry matches a known source
+ * identity. Returns the normalized set of identity keys; throws
+ * `SkillsTrustConfigError` on wildcards, empty strings, or unmatched
+ * entries.
+ */
+export function validateTrustedSources(trustedSources, configuredSources) {
+    if (trustedSources === undefined || trustedSources.length === 0)
+        return new Set();
+    const out = new Set();
+    // Build an alias→canonical map once so we can both validate and normalize.
+    const canonicalByAlias = new Map();
+    for (const source of configuredSources) {
+        const canonical = sourceIdentityKey(source);
+        for (const alias of aliasesForSource(source)) {
+            canonicalByAlias.set(alias, canonical);
+        }
+    }
+    for (const entry of trustedSources) {
+        if (typeof entry !== 'string' || entry.length === 0) {
+            throw new SkillsTrustConfigError(String(entry), 'must be a non-empty string');
+        }
+        if (entry.includes('*')) {
+            throw new SkillsTrustConfigError(entry, 'wildcards are not supported — list each source explicitly');
+        }
+        const canonical = canonicalByAlias.get(entry);
+        if (canonical === undefined) {
+            throw new SkillsTrustConfigError(entry, 'does not match any configured source identity. Use the npm package name, ' +
+                `the full \`<type>:<discriminator>\` key, or one of 'project' / 'user' / 'bundled'. ` +
+                `Vendor-name strings from skill frontmatter are not accepted.`);
+        }
+        out.add(canonical);
+    }
+    return out;
+}
+/**
+ * Decide whether a skill is trusted enough to honor its declarative
+ * affordances (`allowed-tools`, `disable-model-invocation: false`,
+ * `hooks`).
+ *
+ * Rules:
+ *
+ *   - `trustTier === 'trusted'` (`project`/`config`/`bundled`) → always trusted.
+ *   - `trustTier === 'operator'` (`user`) → trusted by default. The operator
+ *     is the user running the SDK on their own box; treating their own files
+ *     as untrusted would require a flag they'd never set.
+ *   - `trustTier === 'third-party'` (`package`/`cli-fetched`) → trusted iff
+ *     the skill's source identity is in `trustedSourceIdentities` (the
+ *     pre-validated `Set` returned by `validateTrustedSources`).
+ */
+export function isSkillTrusted(skill, trustedSourceIdentities) {
+    if (skill.trustTier !== 'third-party')
+        return true;
+    return trustedSourceIdentities.has(sourceIdentityKey(skill.source));
+}
+//# sourceMappingURL=trust.js.map

package/dist/skills/trust.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust.js","sourceRoot":"","sources":["../../src/skills/trust.ts"],"names":[],"mappings":"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"}