@skillguard/cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release of `@skillguard/cli`
+- Added `init`, `scan`, and `verify` commands
+- Added CI-friendly fail thresholds and JSON output
+- Added Ed25519 signature verification via SkillGuard JWKS

package/README.md

@@ -0,0 +1,94 @@
+# @skillguard/cli
+
+Security scanner CLI for AI agent `SKILL.md` files.
+
+## Quick start
+
+```bash
+npx @skillguard/cli scan SKILL.md
+```
+
+## Setup
+
+```bash
+npx @skillguard/cli init
+```
+
+You can also provide the key via env:
+
+```bash
+export SKILLGUARD_API_KEY="sgk_..."
+```
+
+## Usage
+
+### Scan one file
+
+```bash
+npx @skillguard/cli scan ./SKILL.md
+```
+
+### Scan a directory
+
+```bash
+npx @skillguard/cli scan ./skills --fail-on warning
+```
+
+### JSON output for CI
+
+```bash
+npx @skillguard/cli scan ./skills --json > skillguard-report.json
+```
+
+### Verify signature
+
+```bash
+npx @skillguard/cli verify ./SKILL.md
+```
+
+## Options
+
+### scan
+
+- `--json`
+- `--fail-on <safe|warning|dangerous>` (default: `warning`)
+- `--timeout <ms>` (default: `30000`)
+- `--base-url <url>` (default: `https://skillguard.ai`)
+- `--api-key <key>`
+- `--dry-run`
+- `--quiet`
+- `--no-color`
+
+### verify
+
+- `--json`
+- `--timeout <ms>`
+- `--base-url <url>`
+
+## Exit codes
+
+- `0` success / below threshold
+- `1` threshold exceeded (scan) or invalid/tampered signature (verify)
+- `2` usage/input error
+- `3` network/API/runtime external failure
+
+## GitHub Actions example
+
+```yaml
+name: Skill Security Scan
+on: [push, pull_request]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npx @skillguard/cli scan ./skills
+        env:
+          SKILLGUARD_API_KEY: ${{ secrets.SKILLGUARD_API_KEY }}
+```
+
+More info: [skillguard.ai](https://skillguard.ai)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { runInit } from './commands/init.js';
+import { runScan } from './commands/scan.js';
+import { runVerify } from './commands/verify.js';
+const VERSION = '0.1.0';
+function printUsage() {
+    console.log(`SkillGuard CLI ${VERSION}
+
+Usage:
+  skillguard init [--api-key <key>] [--base-url <url>]
+  skillguard scan <path> [--json] [--fail-on <safe|warning|dangerous>] [--timeout <ms>] [--base-url <url>] [--api-key <key>] [--dry-run] [--quiet] [--no-color]
+  skillguard verify <path> [--json] [--timeout <ms>] [--base-url <url>]
+
+Options:
+  --help         Show help
+  --version      Show version
+`);
+}
+function toPositiveInteger(raw, fallback) {
+    if (!raw) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error('Expected a positive integer value.');
+    }
+    return parsed;
+}
+function toFailOn(raw) {
+    if (!raw) {
+        return 'warning';
+    }
+    if (raw === 'safe' || raw === 'warning' || raw === 'dangerous') {
+        return raw;
+    }
+    throw new Error("Invalid --fail-on value. Use 'safe', 'warning', or 'dangerous'.");
+}
+function parseShared(args) {
+    const parsed = parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            help: { type: 'boolean' },
+            version: { type: 'boolean' },
+            json: { type: 'boolean' },
+            'dry-run': { type: 'boolean' },
+            quiet: { type: 'boolean' },
+            'no-color': { type: 'boolean' },
+            'fail-on': { type: 'string' },
+            timeout: { type: 'string' },
+            'base-url': { type: 'string' },
+            'api-key': { type: 'string' },
+        },
+        strict: false,
+    });
+    return {
+        options: parsed.values,
+        positionals: parsed.positionals,
+    };
+}
+async function run() {
+    const argv = process.argv.slice(2);
+    const command = argv[0];
+    if (!command || command === '--help' || command === '-h') {
+        printUsage();
+        return 0;
+    }
+    if (command === '--version' || command === '-v') {
+        console.log(VERSION);
+        return 0;
+    }
+    const { options, positionals } = parseShared(argv.slice(1));
+    if (options.version) {
+        console.log(VERSION);
+        return 0;
+    }
+    if (options.help) {
+        printUsage();
+        return 0;
+    }
+    if (command === 'init') {
+        return await runInit({
+            apiKey: typeof options['api-key'] === 'string' ? options['api-key'] : undefined,
+            baseUrl: typeof options['base-url'] === 'string' ? options['base-url'] : undefined,
+        });
+    }
+    if (command === 'scan') {
+        const pathArg = positionals[0];
+        if (!pathArg) {
+            console.error('Missing required <path> argument.');
+            return 2;
+        }
+        let parsedTimeout;
+        let failOn;
+        try {
+            parsedTimeout = toPositiveInteger(typeof options.timeout === 'string' ? options.timeout : undefined, 30000);
+            failOn = toFailOn(typeof options['fail-on'] === 'string' ? options['fail-on'] : undefined);
+        }
+        catch (error) {
+            console.error(error.message);
+            return 2;
+        }
+        const scanOptions = {
+            json: options.json === true,
+            failOn,
+            timeoutMs: parsedTimeout,
+            baseUrl: typeof options['base-url'] === 'string' ? options['base-url'] : undefined,
+            apiKey: typeof options['api-key'] === 'string' ? options['api-key'] : undefined,
+            dryRun: options['dry-run'] === true,
+            quiet: options.quiet === true,
+            noColor: options['no-color'] === true,
+        };
+        return await runScan(pathArg, scanOptions);
+    }
+    if (command === 'verify') {
+        const pathArg = positionals[0];
+        if (!pathArg) {
+            console.error('Missing required <path> argument.');
+            return 2;
+        }
+        let parsedTimeout;
+        try {
+            parsedTimeout = toPositiveInteger(typeof options.timeout === 'string' ? options.timeout : undefined, 30000);
+        }
+        catch (error) {
+            console.error(error.message);
+            return 2;
+        }
+        const verifyOptions = {
+            baseUrl: typeof options['base-url'] === 'string' ? options['base-url'] : undefined,
+            timeoutMs: parsedTimeout,
+            json: options.json === true,
+        };
+        return await runVerify(pathArg, verifyOptions);
+    }
+    console.error(`Unknown command: ${command}`);
+    printUsage();
+    return 2;
+}
+run()
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch(() => {
+    console.error('Unexpected CLI error.');
+    process.exitCode = 3;
+});

package/dist/commands/init.d.ts

@@ -0,0 +1,5 @@
+export interface InitOptions {
+    apiKey?: string;
+    baseUrl?: string;
+}
+export declare function runInit(options: InitOptions): Promise<number>;

package/dist/commands/init.js

@@ -0,0 +1,31 @@
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { DEFAULT_BASE_URL, getConfigPath, writeConfig } from '../lib/config.js';
+function sanitizeApiKey(value) {
+    const key = value.trim();
+    if (!key) {
+        throw new Error('API key cannot be empty.');
+    }
+    return key;
+}
+async function promptApiKey() {
+    const rl = createInterface({ input, output });
+    try {
+        const answer = await rl.question('Enter your SkillGuard API key: ');
+        return sanitizeApiKey(answer);
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function runInit(options) {
+    const apiKey = options.apiKey ? sanitizeApiKey(options.apiKey) : await promptApiKey();
+    const apiUrl = (options.baseUrl || DEFAULT_BASE_URL).trim() || DEFAULT_BASE_URL;
+    const configPath = getConfigPath();
+    await writeConfig({
+        apiKey,
+        apiUrl,
+    }, configPath);
+    console.log(`API key saved to ${configPath}`);
+    return 0;
+}

package/dist/commands/scan.d.ts

@@ -0,0 +1,18 @@
+import { type ScanFinding, type ScanScore } from '../lib/api.js';
+export interface ScanOptions {
+    json: boolean;
+    failOn: ScanScore;
+    timeoutMs: number;
+    baseUrl?: string;
+    apiKey?: string;
+    dryRun: boolean;
+    quiet: boolean;
+    noColor: boolean;
+}
+export interface ScanResult {
+    file: string;
+    score: ScanScore;
+    findings: ScanFinding[];
+    signatureStatus: string;
+}
+export declare function runScan(inputPath: string, options: ScanOptions): Promise<number>;

package/dist/commands/scan.js

@@ -0,0 +1,193 @@
+import { readFile, readdir, realpath } from 'node:fs/promises';
+import { basename, resolve, sep } from 'node:path';
+import { normalizeFindings, scanContent, toScanScore } from '../lib/api.js';
+import { normalizeBaseUrl, readConfig, resolveApiKey } from '../lib/config.js';
+import { renderSingleScan, renderSummary, shouldUseColor, summarizeScores } from '../lib/format.js';
+const FAIL_LEVELS = {
+    safe: 0,
+    warning: 1,
+    dangerous: 2,
+};
+function shouldFail(score, failOn) {
+    if (failOn === 'safe') {
+        return score !== 'safe';
+    }
+    return FAIL_LEVELS[score] >= FAIL_LEVELS[failOn];
+}
+function isForbiddenFilePath(filePath) {
+    const name = basename(filePath).toLowerCase();
+    return (name === '.env' ||
+        name.endsWith('.pem') ||
+        name.endsWith('.key') ||
+        name.includes('id_rsa') ||
+        name.includes('id_ed25519'));
+}
+function isWithinRoot(rootPath, candidatePath) {
+    if (candidatePath === rootPath) {
+        return true;
+    }
+    return candidatePath.startsWith(`${rootPath}${sep}`);
+}
+async function findSkillFiles(rootPath) {
+    const rootRealPath = await realpath(rootPath);
+    const queue = [rootPath];
+    const found = new Set();
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current) {
+            continue;
+        }
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = resolve(current, entry.name);
+            if (entry.isSymbolicLink()) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                const resolvedDir = await realpath(fullPath);
+                if (!isWithinRoot(rootRealPath, resolvedDir)) {
+                    continue;
+                }
+                queue.push(fullPath);
+                continue;
+            }
+            if (!entry.isFile()) {
+                continue;
+            }
+            const entryName = entry.name.toLowerCase();
+            if (entryName !== 'skill.md') {
+                continue;
+            }
+            if (isForbiddenFilePath(fullPath)) {
+                continue;
+            }
+            const resolvedFile = await realpath(fullPath);
+            if (!isWithinRoot(rootRealPath, resolvedFile)) {
+                continue;
+            }
+            found.add(fullPath);
+        }
+    }
+    return Array.from(found).sort();
+}
+async function resolveTargets(inputPath) {
+    const path = resolve(inputPath);
+    const stat = await import('node:fs/promises').then((mod) => mod.lstat(path));
+    if (stat.isSymbolicLink()) {
+        throw new Error('Symlink paths are not supported.');
+    }
+    if (stat.isDirectory()) {
+        const files = await findSkillFiles(path);
+        if (files.length === 0) {
+            throw new Error('No SKILL.md files found in directory.');
+        }
+        return files;
+    }
+    if (!stat.isFile()) {
+        throw new Error('Path must be a file or directory.');
+    }
+    if (isForbiddenFilePath(path)) {
+        throw new Error('Refusing to scan secret-like files.');
+    }
+    return [path];
+}
+export async function runScan(inputPath, options) {
+    let baseUrl;
+    try {
+        baseUrl = normalizeBaseUrl(options.baseUrl);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 2;
+    }
+    let targets;
+    try {
+        targets = await resolveTargets(inputPath);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 2;
+    }
+    if (options.dryRun) {
+        if (!options.quiet) {
+            console.log(`Dry run: ${targets.length} file(s) would be scanned.`);
+            for (const file of targets) {
+                console.log(`- ${file}`);
+            }
+        }
+        return 0;
+    }
+    const hasApiKeyFlag = typeof options.apiKey === 'string' && options.apiKey.trim().length > 0;
+    const hasApiKeyEnv = typeof process.env.SKILLGUARD_API_KEY === 'string' && process.env.SKILLGUARD_API_KEY.trim().length > 0;
+    let config = null;
+    if (!hasApiKeyFlag && !hasApiKeyEnv) {
+        try {
+            config = await readConfig();
+        }
+        catch (error) {
+            console.error(error.message);
+            return 2;
+        }
+    }
+    const resolvedApiKey = resolveApiKey({
+        apiKeyFlag: options.apiKey,
+        env: process.env,
+        config,
+    });
+    if (!resolvedApiKey) {
+        console.error("No API key found. Run 'skillguard init' or set SKILLGUARD_API_KEY.");
+        return 2;
+    }
+    const color = shouldUseColor(options.noColor);
+    const results = [];
+    for (const filePath of targets) {
+        const content = await readFile(filePath, 'utf8');
+        let apiResponse;
+        try {
+            apiResponse = await scanContent({
+                baseUrl,
+                apiKey: resolvedApiKey.apiKey,
+                content,
+                timeoutMs: options.timeoutMs,
+            });
+        }
+        catch (error) {
+            console.error(error.message);
+            return 3;
+        }
+        const findings = normalizeFindings(apiResponse.findings);
+        const score = toScanScore(apiResponse.score || apiResponse.overallRisk);
+        const signatureStatus = typeof apiResponse.signatureStatus === 'string'
+            ? apiResponse.signatureStatus
+            : (apiResponse.security ? 'issued' : 'disabled');
+        results.push({
+            file: filePath,
+            score,
+            findings,
+            signatureStatus,
+        });
+    }
+    const failedFiles = results.filter((result) => shouldFail(result.score, options.failOn)).map((result) => result.file);
+    if (!options.quiet) {
+        if (options.json) {
+            const summary = summarizeScores(results);
+            console.log(JSON.stringify({
+                cli_version: '0.1.0',
+                scanned_at: new Date().toISOString(),
+                fail_on: options.failOn,
+                summary,
+                failed_files: failedFiles,
+                results,
+            }, null, 2));
+        }
+        else {
+            for (const result of results) {
+                console.log(renderSingleScan(result, color));
+            }
+            const summary = summarizeScores(results);
+            const rootLabel = targets.length === 1 ? targets[0] : resolve(inputPath);
+            console.log(renderSummary(summary, rootLabel, color, failedFiles));
+        }
+    }
+    return failedFiles.length > 0 ? 1 : 0;
+}

package/dist/commands/verify.d.ts

@@ -0,0 +1,6 @@
+export interface VerifyOptions {
+    baseUrl?: string;
+    timeoutMs: number;
+    json: boolean;
+}
+export declare function runVerify(inputPath: string, options: VerifyOptions): Promise<number>;

package/dist/commands/verify.js

@@ -0,0 +1,85 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fetchJwks } from '../lib/api.js';
+import { normalizeBaseUrl } from '../lib/config.js';
+import { parseSkillContent, verifySignature } from '../lib/verify.js';
+function renderHuman(result) {
+    if (!result.security) {
+        return 'Invalid signature: missing security block.';
+    }
+    const signedBy = `${String(result.security.verified_by || 'unknown')} (${String(result.security.kid || 'unknown')})`;
+    const score = String(result.security.score || 'unknown');
+    const scanned = String(result.security.scanned_at || 'unknown');
+    const validUntil = String(result.security.valid_until || 'unknown');
+    return [
+        result.signatureValid && result.hashMatches && !result.expired ? 'Signature valid' : 'Signature invalid',
+        `Signed by: ${signedBy}`,
+        `Score: ${score}`,
+        `Scanned: ${scanned}`,
+        `Valid until: ${validUntil}${result.expired ? ' (expired)' : ''}`,
+        `Content hash matches: ${result.hashMatches ? 'yes' : 'no'}`,
+        !result.hashMatches ? `Computed hash: ${result.computedHash}` : '',
+    ].filter(Boolean).join('\n');
+}
+export async function runVerify(inputPath, options) {
+    const filePath = resolve(inputPath);
+    let baseUrl;
+    try {
+        baseUrl = normalizeBaseUrl(options.baseUrl);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 2;
+    }
+    let rawContent;
+    try {
+        rawContent = await readFile(filePath, 'utf8');
+    }
+    catch {
+        console.error('Could not read file.');
+        return 2;
+    }
+    const parsedSkill = parseSkillContent(rawContent);
+    if (!parsedSkill.security || typeof parsedSkill.security.signature !== 'string') {
+        const message = 'Invalid signature: missing security block.';
+        if (options.json) {
+            console.log(JSON.stringify({ valid: false, reason: 'missing_security_block' }, null, 2));
+        }
+        else {
+            console.error(message);
+        }
+        return 1;
+    }
+    let jwks;
+    try {
+        jwks = await fetchJwks({
+            baseUrl,
+            timeoutMs: options.timeoutMs,
+        });
+    }
+    catch (error) {
+        console.error(error.message);
+        return 3;
+    }
+    const verification = verifySignature({ parsedSkill, jwks });
+    const valid = verification.signatureValid && verification.hashMatches && !verification.expired;
+    if (options.json) {
+        console.log(JSON.stringify({
+            valid,
+            signatureValid: verification.signatureValid,
+            hashMatches: verification.hashMatches,
+            expired: verification.expired,
+            security: verification.security,
+        }, null, 2));
+    }
+    else {
+        const output = renderHuman(verification);
+        if (valid) {
+            console.log(output);
+        }
+        else {
+            console.error(output);
+        }
+    }
+    return valid ? 0 : 1;
+}

package/dist/lib/api.d.ts

@@ -0,0 +1,36 @@
+export type ScanScore = 'safe' | 'warning' | 'dangerous';
+export interface ScanFinding {
+    severity?: string;
+    title?: string;
+    description?: string;
+    recommendation?: string;
+}
+export interface ScanApiResponse {
+    score?: string;
+    overallRisk?: string;
+    findings?: unknown;
+    signatureStatus?: string;
+    security?: Record<string, unknown>;
+    signedSkillContent?: string;
+    [key: string]: unknown;
+}
+export interface SanitizedApiError {
+    message: string;
+    exitCode: 2 | 3;
+}
+export declare function toScanScore(value: unknown): ScanScore;
+export declare function scanContent(input: {
+    baseUrl: string;
+    apiKey: string;
+    content: string;
+    timeoutMs: number;
+    fetchImpl?: typeof fetch;
+}): Promise<ScanApiResponse>;
+export declare function fetchJwks(input: {
+    baseUrl: string;
+    timeoutMs: number;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    keys: Array<Record<string, unknown>>;
+}>;
+export declare function normalizeFindings(rawFindings: unknown): ScanFinding[];

package/dist/lib/api.js

@@ -0,0 +1,155 @@
+export function toScanScore(value) {
+    if (value === 'safe' || value === 'warning' || value === 'dangerous') {
+        return value;
+    }
+    return 'safe';
+}
+function withTimeout(ms) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), ms);
+    timeout.unref?.();
+    return {
+        signal: controller.signal,
+        cancel: () => clearTimeout(timeout),
+    };
+}
+function shouldRetryStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+async function fetchWithRetry(fetchFn, input, init, retries) {
+    let attempt = 0;
+    let lastError = null;
+    while (attempt <= retries) {
+        try {
+            const response = await fetchFn(input, init);
+            if (attempt < retries && shouldRetryStatus(response.status)) {
+                attempt += 1;
+                continue;
+            }
+            return response;
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= retries) {
+                throw error;
+            }
+            attempt += 1;
+        }
+    }
+    throw lastError || new Error('Network request failed.');
+}
+async function parseJsonSafe(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        throw new Error('Unexpected API response.');
+    }
+}
+function mapStatusMessage(status) {
+    if (status === 401) {
+        return "Invalid API key. Run 'skillguard init' or set SKILLGUARD_API_KEY.";
+    }
+    if (status === 429) {
+        return 'Rate limit exceeded. Wait and retry.';
+    }
+    if (status >= 500) {
+        return 'SkillGuard API error. Try again later.';
+    }
+    return 'SkillGuard API request failed.';
+}
+export async function scanContent(input) {
+    const fetchFn = input.fetchImpl || fetch;
+    const endpoint = `${input.baseUrl}/api/v1/scan`;
+    const timeout = withTimeout(input.timeoutMs);
+    try {
+        const response = await fetchWithRetry(fetchFn, endpoint, {
+            method: 'POST',
+            headers: {
+                'X-API-Key': input.apiKey,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ content: input.content }),
+            signal: timeout.signal,
+        }, 1);
+        if (!response.ok) {
+            throw new Error(mapStatusMessage(response.status));
+        }
+        const parsed = await parseJsonSafe(response);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('Unexpected API response.');
+        }
+        return parsed;
+    }
+    catch (error) {
+        const typed = error;
+        if (typed.name === 'AbortError') {
+            throw new Error('Cannot reach skillguard.ai. Check your connection.');
+        }
+        if (typed.message === 'Unexpected API response.') {
+            throw typed;
+        }
+        if (typed.message.includes('Invalid API key.') ||
+            typed.message.includes('Rate limit exceeded.') ||
+            typed.message.includes('SkillGuard API error.') ||
+            typed.message.includes('SkillGuard API request failed.')) {
+            throw typed;
+        }
+        throw new Error('Cannot reach skillguard.ai. Check your connection.');
+    }
+    finally {
+        timeout.cancel();
+    }
+}
+export async function fetchJwks(input) {
+    const fetchFn = input.fetchImpl || fetch;
+    const endpoint = `${input.baseUrl}/.well-known/skillguard-jwks.json`;
+    const timeout = withTimeout(input.timeoutMs);
+    try {
+        const response = await fetchWithRetry(fetchFn, endpoint, {
+            method: 'GET',
+            signal: timeout.signal,
+        }, 1);
+        if (!response.ok) {
+            throw new Error('Could not fetch SkillGuard JWKS.');
+        }
+        const parsed = await parseJsonSafe(response);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('Could not fetch SkillGuard JWKS.');
+        }
+        const keys = parsed.keys;
+        if (!Array.isArray(keys)) {
+            throw new Error('Could not fetch SkillGuard JWKS.');
+        }
+        return { keys: keys };
+    }
+    catch (error) {
+        const typed = error;
+        if (typed.name === 'AbortError') {
+            throw new Error('Could not fetch SkillGuard JWKS.');
+        }
+        if (typed.message === 'Could not fetch SkillGuard JWKS.') {
+            throw typed;
+        }
+        throw new Error('Could not fetch SkillGuard JWKS.');
+    }
+    finally {
+        timeout.cancel();
+    }
+}
+export function normalizeFindings(rawFindings) {
+    if (!Array.isArray(rawFindings)) {
+        return [];
+    }
+    return rawFindings
+        .filter((item) => item && typeof item === 'object' && !Array.isArray(item))
+        .map((item) => {
+        const finding = item;
+        return {
+            severity: typeof finding.severity === 'string' ? finding.severity : undefined,
+            title: typeof finding.title === 'string' ? finding.title : undefined,
+            description: typeof finding.description === 'string' ? finding.description : undefined,
+            recommendation: typeof finding.recommendation === 'string' ? finding.recommendation : undefined,
+        };
+    });
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,19 @@
+export declare const DEFAULT_BASE_URL = "https://skillguard.ai";
+export interface SkillguardCliConfig {
+    apiKey?: string;
+    apiUrl?: string;
+}
+export interface ResolvedApiKey {
+    apiKey: string;
+    source: 'flag' | 'env' | 'config';
+}
+export interface ApiKeyResolutionInput {
+    apiKeyFlag?: string;
+    config?: SkillguardCliConfig | null;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function getConfigPath(home?: string): string;
+export declare function readConfig(configPath?: string): Promise<SkillguardCliConfig | null>;
+export declare function writeConfig(config: SkillguardCliConfig, configPath?: string): Promise<void>;
+export declare function normalizeBaseUrl(value?: string): string;
+export declare function resolveApiKey(input: ApiKeyResolutionInput): ResolvedApiKey | null;

package/dist/lib/config.js

@@ -0,0 +1,73 @@
+import { mkdir, readFile, chmod, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export const DEFAULT_BASE_URL = 'https://skillguard.ai';
+export function getConfigPath(home = homedir()) {
+    return join(home, '.config', 'skillguard', 'config.json');
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+export async function readConfig(configPath = getConfigPath()) {
+    try {
+        const raw = await readFile(configPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return null;
+        }
+        return {
+            apiKey: isNonEmptyString(parsed.apiKey) ? parsed.apiKey.trim() : undefined,
+            apiUrl: isNonEmptyString(parsed.apiUrl) ? parsed.apiUrl.trim() : undefined,
+        };
+    }
+    catch (error) {
+        const typed = error;
+        if (typed?.code === 'ENOENT') {
+            return null;
+        }
+        throw new Error('Failed to read CLI config.');
+    }
+}
+export async function writeConfig(config, configPath = getConfigPath()) {
+    const dirPath = dirname(configPath);
+    await mkdir(dirPath, { recursive: true, mode: 0o700 });
+    await chmod(dirPath, 0o700);
+    const body = JSON.stringify({
+        apiKey: config.apiKey,
+        apiUrl: config.apiUrl || DEFAULT_BASE_URL,
+    }, null, 2);
+    await writeFile(configPath, `${body}\n`, { encoding: 'utf8', mode: 0o600 });
+    await chmod(configPath, 0o600);
+}
+export function normalizeBaseUrl(value) {
+    const raw = (value || DEFAULT_BASE_URL).trim();
+    const withoutTrailingSlash = raw.replace(/\/+$/, '');
+    if (!withoutTrailingSlash) {
+        return DEFAULT_BASE_URL;
+    }
+    let parsed;
+    try {
+        parsed = new URL(withoutTrailingSlash);
+    }
+    catch {
+        throw new Error('Invalid --base-url value.');
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error('Invalid --base-url protocol. Use http or https.');
+    }
+    return parsed.toString().replace(/\/+$/, '');
+}
+export function resolveApiKey(input) {
+    if (isNonEmptyString(input.apiKeyFlag)) {
+        return { apiKey: input.apiKeyFlag.trim(), source: 'flag' };
+    }
+    const envValue = input.env?.SKILLGUARD_API_KEY;
+    if (isNonEmptyString(envValue)) {
+        return { apiKey: envValue.trim(), source: 'env' };
+    }
+    const configValue = input.config?.apiKey;
+    if (isNonEmptyString(configValue)) {
+        return { apiKey: configValue.trim(), source: 'config' };
+    }
+    return null;
+}

package/dist/lib/format.d.ts

@@ -0,0 +1,18 @@
+import { ScanFinding, ScanScore } from './api.js';
+export interface ScanRenderedResult {
+    file: string;
+    score: ScanScore;
+    findings: ScanFinding[];
+    signatureStatus: string;
+}
+export interface ScanSummary {
+    total: number;
+    safe: number;
+    warning: number;
+    dangerous: number;
+}
+export declare function shouldUseColor(noColorFlag: boolean): boolean;
+export declare function scoreLabel(score: ScanScore, color: boolean): string;
+export declare function renderSingleScan(result: ScanRenderedResult, color: boolean): string;
+export declare function summarizeScores(results: ScanRenderedResult[]): ScanSummary;
+export declare function renderSummary(summary: ScanSummary, rootPath: string, color: boolean, failedFiles: string[]): string;

package/dist/lib/format.js

@@ -0,0 +1,92 @@
+const RESET = '\u001B[0m';
+const GREEN = '\u001B[32m';
+const YELLOW = '\u001B[33m';
+const RED = '\u001B[31m';
+const CYAN = '\u001B[36m';
+const DIM = '\u001B[2m';
+function maybeColor(enabled, color, text) {
+    return enabled ? `${color}${text}${RESET}` : text;
+}
+export function shouldUseColor(noColorFlag) {
+    if (noColorFlag) {
+        return false;
+    }
+    if (process.env.NO_COLOR && process.env.NO_COLOR.length > 0) {
+        return false;
+    }
+    return process.stdout.isTTY !== false;
+}
+export function scoreLabel(score, color) {
+    if (score === 'safe') {
+        return maybeColor(color, GREEN, 'safe');
+    }
+    if (score === 'warning') {
+        return maybeColor(color, YELLOW, 'warning');
+    }
+    return maybeColor(color, RED, 'dangerous');
+}
+function statusLabel(status, color) {
+    return status === 'issued'
+        ? maybeColor(color, CYAN, 'issued')
+        : maybeColor(color, DIM, 'disabled');
+}
+export function renderSingleScan(result, color) {
+    const lines = [
+        '┌─────────────────────────────────────────┐',
+        '│  SkillGuard Scan Report                 │',
+        '├─────────────────────────────────────────┤',
+        `│  File:     ${truncate(result.file, 30).padEnd(30, ' ')} │`,
+        `│  Score:    ${padInline(scoreLabel(result.score, color), 28)} │`,
+        `│  Findings: ${String(result.findings.length).padEnd(28, ' ')} │`,
+        `│  Signature:${padInline(statusLabel(result.signatureStatus, color), 28)} │`,
+    ];
+    if (result.findings.length > 0) {
+        lines.push('├─────────────────────────────────────────┤');
+        for (const finding of result.findings.slice(0, 3)) {
+            const sev = (finding.severity || 'info').toUpperCase();
+            const title = finding.title || finding.description || 'Finding';
+            lines.push(`│  [${sev}] ${truncate(title, 30).padEnd(30, ' ')} │`);
+        }
+    }
+    lines.push('└─────────────────────────────────────────┘');
+    return lines.join('\n');
+}
+function truncate(value, limit) {
+    if (value.length <= limit) {
+        return value;
+    }
+    return `${value.slice(0, limit - 1)}…`;
+}
+function padInline(value, target) {
+    const strippedLength = value.replace(/\u001B\[[0-9;]*m/g, '').length;
+    if (strippedLength >= target) {
+        return value;
+    }
+    return value + ' '.repeat(target - strippedLength);
+}
+export function summarizeScores(results) {
+    const summary = {
+        total: results.length,
+        safe: 0,
+        warning: 0,
+        dangerous: 0,
+    };
+    for (const result of results) {
+        summary[result.score] += 1;
+    }
+    return summary;
+}
+export function renderSummary(summary, rootPath, color, failedFiles) {
+    const lines = [
+        `Scanned ${summary.total} skills in ${rootPath}`,
+        '',
+        `  ${maybeColor(color, GREEN, 'safe')}: ${String(summary.safe).padStart(4, ' ')}`,
+        `  ${maybeColor(color, YELLOW, 'warning')}: ${String(summary.warning).padStart(4, ' ')}`,
+        `  ${maybeColor(color, RED, 'dangerous')}: ${String(summary.dangerous).padStart(4, ' ')}`,
+    ];
+    if (failedFiles.length > 0) {
+        lines.push('');
+        lines.push(`Failed: ${failedFiles.join(', ')}`);
+    }
+    return lines.join('\n');
+}

package/dist/lib/verify.d.ts

@@ -0,0 +1,21 @@
+export interface ParsedSkillFile {
+    normalizedContent: string;
+    body: string;
+    unsignedContent: string;
+    security: Record<string, unknown> | null;
+}
+export interface VerificationResult {
+    signatureValid: boolean;
+    hashMatches: boolean;
+    expired: boolean;
+    security: Record<string, unknown> | null;
+    computedHash: string;
+}
+export declare function parseSkillContent(content: string): ParsedSkillFile;
+export declare function buildSignaturePayload(security: Record<string, unknown>): Record<string, unknown>;
+export declare function verifySignature(input: {
+    parsedSkill: ParsedSkillFile;
+    jwks: {
+        keys: Array<Record<string, unknown>>;
+    };
+}): VerificationResult;

package/dist/lib/verify.js

@@ -0,0 +1,193 @@
+import { createHash, createPublicKey, verify as cryptoVerify } from 'node:crypto';
+function normalizeLineEndings(value) {
+    return value.replace(/\r\n?/g, '\n');
+}
+function parseScalar(raw) {
+    const value = raw.trim();
+    if (value === 'null' || value === '~') {
+        return null;
+    }
+    if (value === 'true') {
+        return true;
+    }
+    if (value === 'false') {
+        return false;
+    }
+    if (/^-?\d+$/.test(value)) {
+        return Number.parseInt(value, 10);
+    }
+    if (/^-?\d+\.\d+$/.test(value)) {
+        return Number.parseFloat(value);
+    }
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function extractFrontMatter(content) {
+    const normalized = normalizeLineEndings(content);
+    if (!normalized.startsWith('---\n')) {
+        return {
+            frontMatterLines: [],
+            body: normalized,
+        };
+    }
+    const closeIdx = normalized.indexOf('\n---\n', 4);
+    if (closeIdx === -1) {
+        return {
+            frontMatterLines: [],
+            body: normalized,
+        };
+    }
+    const frontMatterRaw = normalized.slice(4, closeIdx);
+    const body = normalized.slice(closeIdx + 5);
+    return {
+        frontMatterLines: frontMatterRaw.length > 0 ? frontMatterRaw.split('\n') : [],
+        body,
+    };
+}
+function splitSecurityBlock(frontMatterLines) {
+    const withoutSecurity = [];
+    const security = {};
+    let index = 0;
+    let foundSecurity = false;
+    while (index < frontMatterLines.length) {
+        const line = frontMatterLines[index];
+        if (!foundSecurity && /^security:\s*$/.test(line)) {
+            foundSecurity = true;
+            index += 1;
+            while (index < frontMatterLines.length) {
+                const nested = frontMatterLines[index];
+                if (!/^\s+/.test(nested)) {
+                    break;
+                }
+                const match = nested.match(/^\s{2}([A-Za-z0-9_]+):\s*(.*)$/);
+                if (match) {
+                    security[match[1]] = parseScalar(match[2]);
+                }
+                index += 1;
+            }
+            continue;
+        }
+        withoutSecurity.push(line);
+        index += 1;
+    }
+    if (!foundSecurity) {
+        return {
+            security: null,
+            withoutSecurity: frontMatterLines,
+        };
+    }
+    return {
+        security,
+        withoutSecurity,
+    };
+}
+function buildUnsignedContent(frontMatterLines, body) {
+    if (frontMatterLines.length === 0) {
+        return body;
+    }
+    return `---\n${frontMatterLines.join('\n')}\n---\n${body}`;
+}
+function fromBase64Url(value) {
+    const normalized = value.replace(/-/g, '+').replace(/_/g, '/');
+    const padding = normalized.length % 4;
+    const padded = padding ? `${normalized}${'='.repeat(4 - padding)}` : normalized;
+    return Buffer.from(padded, 'base64');
+}
+function canonicalJSONStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalJSONStringify(item)).join(',')}]`;
+    }
+    const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+    const serialized = entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJSONStringify(item)}`);
+    return `{${serialized.join(',')}}`;
+}
+function sha256Hex(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+export function parseSkillContent(content) {
+    const normalizedContent = normalizeLineEndings(content);
+    const parsed = extractFrontMatter(normalizedContent);
+    const split = splitSecurityBlock(parsed.frontMatterLines);
+    return {
+        normalizedContent,
+        body: parsed.body,
+        unsignedContent: buildUnsignedContent(split.withoutSecurity, parsed.body),
+        security: split.security,
+    };
+}
+export function buildSignaturePayload(security) {
+    return {
+        verified_by: security.verified_by,
+        version: security.version,
+        issuer: security.issuer,
+        kid: security.kid,
+        alg: security.alg,
+        scan_id: security.scan_id,
+        score: security.score,
+        scanned_at: security.scanned_at,
+        valid_until: security.valid_until,
+        content_sha256: security.content_sha256,
+    };
+}
+function findJwkByKid(jwks, kid) {
+    if (typeof kid !== 'string' || kid.trim().length === 0) {
+        return null;
+    }
+    for (const key of jwks.keys) {
+        if (typeof key.kid === 'string' && key.kid === kid) {
+            return key;
+        }
+    }
+    return null;
+}
+export function verifySignature(input) {
+    const security = input.parsedSkill.security;
+    const computedHash = sha256Hex(input.parsedSkill.unsignedContent);
+    if (!security || typeof security.signature !== 'string') {
+        return {
+            signatureValid: false,
+            hashMatches: false,
+            expired: false,
+            security,
+            computedHash,
+        };
+    }
+    const jwk = findJwkByKid(input.jwks, security.kid);
+    if (!jwk) {
+        return {
+            signatureValid: false,
+            hashMatches: false,
+            expired: false,
+            security,
+            computedHash,
+        };
+    }
+    let signatureValid = false;
+    try {
+        const publicKey = createPublicKey({
+            key: jwk,
+            format: 'jwk',
+        });
+        const payload = buildSignaturePayload(security);
+        signatureValid = cryptoVerify(null, Buffer.from(canonicalJSONStringify(payload), 'utf8'), publicKey, fromBase64Url(String(security.signature)));
+    }
+    catch {
+        signatureValid = false;
+    }
+    const expectedHash = typeof security.content_sha256 === 'string' ? security.content_sha256 : '';
+    const hashMatches = expectedHash.length > 0 && expectedHash === computedHash;
+    const validUntil = typeof security.valid_until === 'string' ? Date.parse(security.valid_until) : NaN;
+    const expired = Number.isFinite(validUntil) ? Date.now() > validUntil : true;
+    return {
+        signatureValid,
+        hashMatches,
+        expired,
+        security,
+        computedHash,
+    };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@skillguard/cli",
+  "version": "0.1.0",
+  "description": "Security scanner for AI agent skill files",
+  "type": "module",
+  "bin": {
+    "skillguard": "./dist/cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.node.mjs"
+  },
+  "keywords": [
+    "security",
+    "ai",
+    "agent",
+    "skill",
+    "scanner",
+    "openclaw"
+  ],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.7.3"
+  }
+}