Core keeps only shared infrastructure, so InstallAuditStore leaves it and lives in packages/server/src/local/install-audit.ts. The trail itself stays: the Audit and Activity tabs, the extend and export routes, and the threat model entry keep working on the same waggle.db table. - @waggle/shared gets RecordAuditInput and the narrow InstallAuditRecorder (record only), which the agent's skill tools now depend on. - The server creates the audit table before the one-time legacy copy, which no longer constructs it in core. - UF-040: GET /api/debug/logs called prepare() on the store's private db wrapper, which has none, so the support bundle never carried recent installs. It now reads them through getRecentSummary().
310 lines
11 KiB
TypeScript
310 lines
11 KiB
TypeScript
/**
|
|
* Shared skill-write service (P5/D4 binding iii).
|
|
*
|
|
* One module, one audit trail, two callers: the agent tool layer
|
|
* (`skill-tools.ts`) and the HTTP route layer (`routes/skills.ts`) both go
|
|
* through here so create / update / delete are redacted, provenance-stamped,
|
|
* and audited exactly once, the same way, regardless of who initiated.
|
|
*
|
|
* Per the D4(iii) AMENDED ruling, the agent tool does NOT call HTTP — it calls
|
|
* this in-process service directly. Caller-specific side effects (skill-hash
|
|
* store, agentState reload) stay in the caller; this service owns the file I/O,
|
|
* redaction, provenance, and audit write.
|
|
*/
|
|
|
|
import * as fs from 'node:fs';
|
|
import * as path from 'node:path';
|
|
import { redactSkillContent } from './skill-redaction.js';
|
|
import type { SkillInitiator } from './skill-frontmatter.js';
|
|
import { parseSkillFrontmatter } from './skill-frontmatter.js';
|
|
import type { InstallAuditRecorder } from '@waggle/shared';
|
|
|
|
/** Shared deps for every skill-write op. auditStore/onChange degrade gracefully. */
|
|
export interface SkillWriteDeps {
|
|
/** Directory holding personal-scope SKILL.md files (~/.waggle/skills). */
|
|
skillsDir: string;
|
|
/** Audit store — when present, every op records an install_audit row. */
|
|
auditStore?: InstallAuditRecorder;
|
|
/** Called after a successful write/delete so the caller can hot-reload skills. */
|
|
onChange?: () => void;
|
|
}
|
|
|
|
export interface WriteSkillInput {
|
|
name: string;
|
|
/** Markdown content (raw or pre-generated). Redacted before persisting. */
|
|
content: string;
|
|
/** Who authored this write — stamped into provenance frontmatter + audit. */
|
|
initiator: SkillInitiator;
|
|
/** Where the write originated (e.g. 'chat', 'api', 'skill-creator'). */
|
|
source: string;
|
|
}
|
|
|
|
export interface DeleteSkillInput {
|
|
name: string;
|
|
initiator: SkillInitiator;
|
|
source: string;
|
|
}
|
|
|
|
export interface SkillWriteResult {
|
|
ok: boolean;
|
|
/** Absolute path written/deleted (present on success). */
|
|
path?: string;
|
|
/** True when the target already existed (update vs create). */
|
|
existed?: boolean;
|
|
/** Secrets/paths stripped before persisting (write ops only). */
|
|
redactions?: string[];
|
|
/** Set when ok=false. */
|
|
error?: string;
|
|
}
|
|
|
|
/** Reject names that could escape skillsDir or collide with shell-hostile chars. */
|
|
function invalidName(name: string): boolean {
|
|
return !name || !/^[a-zA-Z0-9_-]+$/.test(name);
|
|
}
|
|
|
|
/** Subdir under skillsDir holding pre-overwrite/pre-delete snapshots. */
|
|
const BACKUP_DIR = '.backups';
|
|
/** Newest N snapshots retained per skill; older are pruned. */
|
|
const BACKUP_KEEP = 5;
|
|
|
|
function backupsDirFor(skillsDir: string): string {
|
|
return path.join(skillsDir, BACKUP_DIR);
|
|
}
|
|
|
|
/**
|
|
* Monotonic, filesystem-safe, sortable stamp (e.g. 20260710T123456789Z). It
|
|
* never repeats within a process — colliding same-millisecond writes are bumped
|
|
* forward — so backup filenames stay unique and lexical sort == chronological.
|
|
*/
|
|
let lastStampMs = 0;
|
|
function nextBackupStamp(): string {
|
|
let now = Date.now();
|
|
if (now <= lastStampMs) now = lastStampMs + 1;
|
|
lastStampMs = now;
|
|
return new Date(now).toISOString().replace(/[-:.]/g, '');
|
|
}
|
|
|
|
/**
|
|
* Skill name a backup filename belongs to. The stamp is the suffix after the
|
|
* LAST '-' (and contains no '-' itself), so names with hyphens parse correctly.
|
|
*/
|
|
function backupSkillName(file: string): string | null {
|
|
if (!file.endsWith('.md')) return null;
|
|
const base = file.slice(0, -'.md'.length);
|
|
const lastDash = base.lastIndexOf('-');
|
|
if (lastDash <= 0) return null;
|
|
return base.slice(0, lastDash);
|
|
}
|
|
|
|
/** Backup filenames for one skill, newest first (exact-name match, not prefix). */
|
|
function backupsForSkill(skillsDir: string, name: string): string[] {
|
|
const dir = backupsDirFor(skillsDir);
|
|
if (!fs.existsSync(dir)) return [];
|
|
return fs
|
|
.readdirSync(dir)
|
|
.filter((f) => backupSkillName(f) === name)
|
|
.sort()
|
|
.reverse();
|
|
}
|
|
|
|
/**
|
|
* Snapshot the current on-disk skill bytes into .backups before it is
|
|
* overwritten or deleted, then prune to the newest BACKUP_KEEP. Best-effort: a
|
|
* backup failure must never block the primary write/delete.
|
|
*/
|
|
function stashBackup(skillsDir: string, name: string): void {
|
|
const filePath = path.join(skillsDir, `${name}.md`);
|
|
if (!fs.existsSync(filePath)) return;
|
|
try {
|
|
const dir = backupsDirFor(skillsDir);
|
|
if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
|
|
fs.writeFileSync(path.join(dir, `${name}-${nextBackupStamp()}.md`), fs.readFileSync(filePath));
|
|
for (const stale of backupsForSkill(skillsDir, name).slice(BACKUP_KEEP)) {
|
|
try { fs.unlinkSync(path.join(dir, stale)); } catch { /* best-effort prune */ }
|
|
}
|
|
} catch { /* backup is best-effort; never block the primary op */ }
|
|
}
|
|
|
|
/**
|
|
* Inject/overwrite `initiator` + `source` inside the content's frontmatter
|
|
* WITHOUT round-tripping through serializeFrontmatter (which is lossy — it drops
|
|
* unknown keys like custom `permissions:` blocks). Provenance is authoritative:
|
|
* any initiator/source the author embedded in the body is replaced, so a write
|
|
* can't spoof false provenance.
|
|
*/
|
|
function stampProvenance(content: string, initiator: SkillInitiator, source: string): string {
|
|
const provLines = [`initiator: ${initiator}`, `source: ${source}`];
|
|
|
|
if (content.startsWith('---')) {
|
|
const end = content.indexOf('\n---', 3);
|
|
if (end !== -1) {
|
|
const block = content.slice(3, end);
|
|
const afterDelimiter = end + 4; // '\n---'
|
|
const rest = content.slice(afterDelimiter);
|
|
// Strip any existing initiator/source lines, keep everything else.
|
|
const kept = block
|
|
.split('\n')
|
|
.filter((l) => {
|
|
const key = l.trim().toLowerCase();
|
|
return !key.startsWith('initiator:') && !key.startsWith('source:');
|
|
});
|
|
// Drop leading/trailing blank lines introduced by the filter.
|
|
while (kept.length && kept[0].trim() === '') kept.shift();
|
|
while (kept.length && kept[kept.length - 1].trim() === '') kept.pop();
|
|
const newBlock = [...kept, ...provLines].join('\n');
|
|
return `---\n${newBlock}\n---${rest}`;
|
|
}
|
|
}
|
|
|
|
// No frontmatter → prepend a minimal provenance block.
|
|
return `---\n${provLines.join('\n')}\n---\n\n${content}`;
|
|
}
|
|
|
|
/**
|
|
* Create or update a skill. Redacts secrets/paths, stamps provenance
|
|
* (sticky — an update preserves the original author rather than relaundering
|
|
* it), writes to disk, records an audit row, and fires onChange.
|
|
*/
|
|
export function writeSkill(deps: SkillWriteDeps, input: WriteSkillInput): SkillWriteResult {
|
|
const { skillsDir, auditStore, onChange } = deps;
|
|
const { name, content } = input;
|
|
|
|
if (invalidName(name)) {
|
|
return { ok: false, error: 'Invalid skill name (letters, numbers, hyphens, underscores only).' };
|
|
}
|
|
|
|
const filePath = path.join(skillsDir, `${name}.md`);
|
|
const existed = fs.existsSync(filePath);
|
|
|
|
// FILE provenance is sticky: if the skill already exists with an author,
|
|
// preserve it so an edit (by user OR agent) can't reclassify who CREATED it.
|
|
// The AUDIT row, by contrast, must record who performed THIS write (the actual
|
|
// actor) — D4(i) requires agent writes to audit initiator:'agent' even when
|
|
// editing a user-authored skill. The two must NOT share a variable.
|
|
let fileInitiator = input.initiator;
|
|
let fileSource = input.source;
|
|
if (existed) {
|
|
try {
|
|
const prior = parseSkillFrontmatter(fs.readFileSync(filePath, 'utf-8')).frontmatter;
|
|
if (prior.initiator) fileInitiator = prior.initiator;
|
|
if (prior.source) fileSource = prior.source;
|
|
} catch { /* unreadable prior — fall back to the input provenance */ }
|
|
}
|
|
|
|
const { content: safe, redactions } = redactSkillContent(content);
|
|
const stamped = stampProvenance(safe, fileInitiator, fileSource);
|
|
|
|
if (!fs.existsSync(skillsDir)) fs.mkdirSync(skillsDir, { recursive: true });
|
|
// Snapshot the outgoing bytes before overwrite so the write is undoable.
|
|
if (existed) stashBackup(skillsDir, name);
|
|
fs.writeFileSync(filePath, stamped, 'utf-8');
|
|
|
|
try {
|
|
auditStore?.record({
|
|
capabilityName: name,
|
|
capabilityType: 'skill',
|
|
source: input.source,
|
|
riskLevel: 'low',
|
|
trustSource: 'local_user',
|
|
approvalClass: 'standard',
|
|
action: 'installed',
|
|
initiator: input.initiator,
|
|
detail: `${existed ? 'Updated' : 'Created'} skill via ${input.source}${redactions.length ? ` (redacted ${redactions.length})` : ''}.`,
|
|
});
|
|
} catch { /* audit is best-effort */ }
|
|
|
|
onChange?.();
|
|
return { ok: true, path: filePath, existed, redactions };
|
|
}
|
|
|
|
/**
|
|
* Delete a skill. Records an 'uninstalled' audit row (the action added in
|
|
* P5/D4 DEC-1) and fires onChange. Returns ok=false if the skill is absent.
|
|
*/
|
|
export function deleteSkill(deps: SkillWriteDeps, input: DeleteSkillInput): SkillWriteResult {
|
|
const { skillsDir, auditStore, onChange } = deps;
|
|
const { name, initiator, source } = input;
|
|
|
|
if (invalidName(name)) {
|
|
return { ok: false, error: 'Invalid skill name.' };
|
|
}
|
|
|
|
const filePath = path.join(skillsDir, `${name}.md`);
|
|
if (!fs.existsSync(filePath)) {
|
|
return { ok: false, error: `Skill "${name}" not found.` };
|
|
}
|
|
|
|
// Snapshot before unlink so a delete can be undone.
|
|
stashBackup(skillsDir, name);
|
|
fs.unlinkSync(filePath);
|
|
|
|
try {
|
|
auditStore?.record({
|
|
capabilityName: name,
|
|
capabilityType: 'skill',
|
|
source,
|
|
riskLevel: 'low',
|
|
trustSource: 'local_user',
|
|
approvalClass: 'standard',
|
|
action: 'uninstalled',
|
|
initiator,
|
|
detail: `Skill deleted via ${source}.`,
|
|
});
|
|
} catch { /* audit is best-effort */ }
|
|
|
|
onChange?.();
|
|
return { ok: true, path: filePath };
|
|
}
|
|
|
|
export interface UndoSkillInput {
|
|
name: string;
|
|
/** Who triggered the restore — recorded in the audit row. Defaults to 'agent'. */
|
|
initiator?: SkillInitiator;
|
|
}
|
|
|
|
export interface UndoSkillResult {
|
|
ok: boolean;
|
|
/** Absolute path of the restored skill file (present on success). */
|
|
path?: string;
|
|
/** Backup filename that was restored (present on success). */
|
|
restoredFrom?: string;
|
|
/** Set when ok=false. */
|
|
error?: string;
|
|
}
|
|
|
|
/**
|
|
* Restore a skill's newest backup through the sanctioned writeSkill seam: the
|
|
* snapshot bytes are re-written (source 'restored-from-backup'), which also
|
|
* snapshots the current bytes as a fresh backup, records an audit row, and
|
|
* fires onChange. Returns a clear error when no backup exists.
|
|
*/
|
|
export function undoSkillWrite(deps: SkillWriteDeps, input: UndoSkillInput): UndoSkillResult {
|
|
const { skillsDir } = deps;
|
|
const { name } = input;
|
|
|
|
if (invalidName(name)) {
|
|
return { ok: false, error: 'Invalid skill name.' };
|
|
}
|
|
|
|
const newest = backupsForSkill(skillsDir, name)[0];
|
|
if (!newest) {
|
|
return { ok: false, error: `No backup found for skill "${name}".` };
|
|
}
|
|
|
|
let bytes: string;
|
|
try {
|
|
bytes = fs.readFileSync(path.join(backupsDirFor(skillsDir), newest), 'utf-8');
|
|
} catch (err) {
|
|
return { ok: false, error: `Backup unreadable: ${err instanceof Error ? err.message : String(err)}` };
|
|
}
|
|
|
|
const res = writeSkill(deps, {
|
|
name,
|
|
content: bytes,
|
|
initiator: input.initiator ?? 'agent',
|
|
source: 'restored-from-backup',
|
|
});
|
|
if (!res.ok) return { ok: false, error: res.error };
|
|
return { ok: true, path: res.path, restoredFrom: newest };
|
|
}
|