@frontmcp/skills 1.1.2 → 1.2.0

package/catalog/frontmcp-extensibility/examples/skill-audit-log/verify-chain.md

@@ -0,0 +1,68 @@
+---
+name: verify-chain
+reference: skill-audit-log
+level: intermediate
+description: Verify a stored chain offline using verifyChain and the bundle-signing key registry.
+tags: [extensibility, audit, verification, chain, rs256]
+features:
+  - 'verifyChain returns { ok, breakAt?, reason? } and exits with the first detected break'
+  - 'defaultAuditSignatureVerifier dispatches on record.signatureAlg (HS256 or RS256)'
+  - 'Trusted-keys registry maps signatureKeyId → public key PEM'
+  - 'iterate() reads the chain in order from any SkillAuditStore implementation'
+---
+
+# Verify Audit Chain
+
+Verify a stored chain offline using verifyChain and the bundle-signing key registry.
+
+## Code
+
+```typescript
+// scripts/verify-audit-chain.ts
+import { defaultAuditSignatureVerifier, StorageAdapterAuditStore, verifyChain } from '@frontmcp/adapters/skills';
+import { createStorageAdapter } from '@frontmcp/utils';
+
+async function main() {
+  const storage = await createStorageAdapter({
+    provider: 'redis',
+    host: process.env.REDIS_HOST!,
+    port: 6379,
+    keyPrefix: 'mcp:skill-audit:',
+  });
+
+  const store = new StorageAdapterAuditStore(storage);
+  const records = await store.iterate();
+
+  const trustedKeys: Record<string, string> = {
+    // Map every keyId you have ever rotated through, not just the current one.
+    'bundle-signing-2026-01': process.env.BUNDLE_SIGNING_PUBLIC_KEY_2026_01!,
+    'bundle-signing-2025-12': process.env.BUNDLE_SIGNING_PUBLIC_KEY_2025_12!,
+  };
+
+  const result = verifyChain(records, trustedKeys, defaultAuditSignatureVerifier);
+
+  if (!result.ok) {
+    console.error(`Chain broken at sequence ${result.breakAt}: ${result.reason}`);
+    process.exit(1);
+  }
+
+  console.log(`Verified ${records.length} records, chain intact.`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+```
+
+## What This Demonstrates
+
+- verifyChain returns { ok, breakAt?, reason? } and exits with the first detected break
+- defaultAuditSignatureVerifier dispatches on record.signatureAlg (HS256 or RS256)
+- Trusted-keys registry maps signatureKeyId → public key PEM
+- iterate() reads the chain in order from any SkillAuditStore implementation
+
+## Related
+
+- See `skill-audit-log` for architecture and threat model
+- See `custom-store` for streaming records to S3

package/catalog/frontmcp-extensibility/examples/vectoriadb/product-catalog-search.md

@@ -25,8 +25,6 @@ import { FileStorageAdapter, VectoriaDB, type DocumentMetadata } from 'vectoriad
 
 import { Provider, ProviderScope } from '@frontmcp/sdk';
 
-export const ProductSearch = Symbol('ProductSearch');
-
 // Typed metadata for product documents
 interface ProductDoc extends DocumentMetadata {
   name: string;
@@ -35,7 +33,7 @@ interface ProductDoc extends DocumentMetadata {
   inStock: boolean;
 }
 
-@Provider({ name: 'product-search', provide: ProductSearch, scope: ProviderScope.GLOBAL })
+@Provider({ name: 'product-search', scope: ProviderScope.GLOBAL })
 export class ProductSearchProvider {
   private db: VectoriaDB<ProductDoc>;
   private ready: Promise<void>;
@@ -106,7 +104,7 @@ export class ProductSearchProvider {
 // src/tools/find-products.tool.ts
 import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
-import { ProductSearch } from '../providers/product-search.provider';
+import { ProductSearchProvider } from '../providers/product-search.provider';
 
 @Tool({
   name: 'find_products',
@@ -134,7 +132,7 @@ import { ProductSearch } from '../providers/product-search.provider';
 })
 export class FindProductsTool extends ToolContext {
   async execute(input: { query: string; category?: string; maxPrice?: number; inStockOnly: boolean; limit: number }) {
-    const search = this.get(ProductSearch);
+    const search = this.get(ProductSearchProvider);
 
     const results = await search.search(
       input.query,

package/catalog/frontmcp-extensibility/examples/vectoriadb/semantic-search-with-persistence.md

@@ -25,14 +25,12 @@ import { FileStorageAdapter, VectoriaDB, type DocumentMetadata } from 'vectoriad
 
 import { Provider, ProviderScope } from '@frontmcp/sdk';
 
-export const KnowledgeBase = Symbol('KnowledgeBase');
-
 interface Article extends DocumentMetadata {
   title: string;
   category: string;
 }
 
-@Provider({ name: 'knowledge-base', provide: KnowledgeBase, scope: ProviderScope.GLOBAL })
+@Provider({ name: 'knowledge-base', scope: ProviderScope.GLOBAL })
 export class KnowledgeBaseProvider {
   private db: VectoriaDB<Article>;
   private ready: Promise<void>;
@@ -67,14 +65,9 @@ export class KnowledgeBaseProvider {
     } else {
       await this.db.add(id, text, metadata);
     }
-    // Persist to disk — restored without re-embedding on next startup
+    // Persist to disk — initialize() automatically restores from cache on next startup
     await this.db.saveToStorage();
   }
-
-  async loadFromDisk() {
-    await this.ready;
-    await this.db.loadFromStorage();
-  }
 }
 ```
 
@@ -82,7 +75,7 @@ export class KnowledgeBaseProvider {
 // src/tools/semantic-search.tool.ts
 import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
-import { KnowledgeBase } from '../providers/knowledge-base.provider';
+import { KnowledgeBaseProvider } from '../providers/knowledge-base.provider';
 
 @Tool({
   name: 'semantic_search',
@@ -105,7 +98,7 @@ import { KnowledgeBase } from '../providers/knowledge-base.provider';
 })
 export class SemanticSearchTool extends ToolContext {
   async execute(input: { query: string; category?: string; limit: number }) {
-    const kb = this.get(KnowledgeBase);
+    const kb = this.get(KnowledgeBaseProvider);
 
     const results = await kb.search(input.query, {
       category: input.category,

package/catalog/frontmcp-extensibility/examples/vectoriadb/tfidf-keyword-search.md

@@ -2,19 +2,28 @@
 name: tfidf-keyword-search
 reference: vectoriadb
 level: basic
-description: 'Shows how to use `TFIDFVectoria` for zero-dependency keyword search in a FrontMCP provider, with field weights and index building.'
-tags: [extensibility, vectoriadb, keyword-search, tfidf, keyword, search]
+description: Shows how to use `TFIDFVectoria` for zero-dependency keyword search in a FrontMCP provider. `TFIDFVectoria` indexes a single text string per document, so multi-field documents are concatenated into one searchable blob; the original fields are kept in `metadata` for use on search results.
+tags:
+  - extensibility
+  - vectoriadb
+  - keyword-search
+  - tfidf
+  - keyword
+  - search
 features:
-  - 'Using `TFIDFVectoria` for zero-dependency keyword search (no model downloads)'
-  - 'Configuring field weights to control scoring influence'
-  - 'Calling `buildIndex()` after adding documents (required for TFIDFVectoria)'
-  - 'Wrapping the search engine in a FrontMCP provider with `ProviderScope.GLOBAL`'
-  - 'Injecting the provider into tools via `this.get(FAQSearch)`'
+  - Using `TFIDFVectoria` for zero-dependency keyword search (no model downloads)
+  - Calling `addDocument(id, text, metadata)` with a single concatenated text string
+  - Calling `reindex()` after adding documents (required for TFIDFVectoria)
+  - Wrapping the search engine in a FrontMCP provider with `ProviderScope.GLOBAL`
+  - Injecting the provider into tools via `this.get(FAQSearchProvider)`
 ---
 
 # TFIDFVectoria: Lightweight Keyword Search Provider
 
-Shows how to use `TFIDFVectoria` for zero-dependency keyword search in a FrontMCP provider, with field weights and index building.
+Shows how to use `TFIDFVectoria` for zero-dependency keyword search in a FrontMCP
+provider. `TFIDFVectoria` indexes a single text string per document, so multi-field
+documents are concatenated into one searchable blob; the original fields are kept
+in `metadata` for use on search results.
 
 ## Code
 
@@ -24,32 +33,32 @@ import { TFIDFVectoria } from 'vectoriadb';
 
 import { Provider, ProviderScope } from '@frontmcp/sdk';
 
-export const FAQSearch = Symbol('FAQSearch');
+interface FaqDoc {
+  id: string;
+  question: string;
+  answer: string;
+  tags: string;
+}
 
-@Provider({ name: 'faq-search', provide: FAQSearch, scope: ProviderScope.GLOBAL })
+@Provider({ name: 'faq-search', scope: ProviderScope.GLOBAL })
 export class FAQSearchProvider {
-  private db = new TFIDFVectoria({
-    fields: {
-      question: { weight: 3 }, // Question matches are 3x more important
-      answer: { weight: 1 }, // Answer matches are baseline
-      tags: { weight: 2 }, // Tag matches are 2x
-    },
+  private db = new TFIDFVectoria<FaqDoc>({
+    defaultTopK: 10,
   });
 
-  async initialize(faqs: Array<{ id: string; question: string; answer: string; tags: string }>) {
+  async initialize(faqs: FaqDoc[]) {
     for (const faq of faqs) {
-      this.db.addDocument(faq.id, {
-        question: faq.question,
-        answer: faq.answer,
-        tags: faq.tags,
-      });
+      // Concatenate fields into a single searchable text string;
+      // preserve the original fields in metadata.
+      const text = `${faq.question} ${faq.answer} ${faq.tags}`;
+      this.db.addDocument(faq.id, text, faq);
     }
-    // Required after adding documents — builds the TF-IDF index
-    this.db.buildIndex();
+    // Required after adding documents — rebuilds IDF and embeddings
+    this.db.reindex();
   }
 
   search(query: string, limit = 5) {
-    return this.db.search(query, limit);
+    return this.db.search(query, { topK: limit });
   }
 }
 ```
@@ -58,7 +67,7 @@ export class FAQSearchProvider {
 // src/tools/search-faq.tool.ts
 import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
-import { FAQSearch } from '../providers/faq-search.provider';
+import { FAQSearchProvider } from '../providers/faq-search.provider';
 
 @Tool({
   name: 'search_faq',
@@ -72,19 +81,21 @@ import { FAQSearch } from '../providers/faq-search.provider';
       z.object({
         id: z.string(),
         score: z.number(),
+        question: z.string(),
       }),
     ),
   },
 })
 export class SearchFaqTool extends ToolContext {
   async execute(input: { query: string; limit: number }) {
-    const faqSearch = this.get(FAQSearch);
+    const faqSearch = this.get(FAQSearchProvider);
     const results = faqSearch.search(input.query, input.limit);
 
     return {
       results: results.map((r) => ({
         id: r.id,
         score: r.score,
+        question: r.metadata.question,
       })),
     };
   }
@@ -94,10 +105,10 @@ export class SearchFaqTool extends ToolContext {
 ## What This Demonstrates
 
 - Using `TFIDFVectoria` for zero-dependency keyword search (no model downloads)
-- Configuring field weights to control scoring influence
-- Calling `buildIndex()` after adding documents (required for TFIDFVectoria)
+- Calling `addDocument(id, text, metadata)` with a single concatenated text string
+- Calling `reindex()` after adding documents (required for TFIDFVectoria)
 - Wrapping the search engine in a FrontMCP provider with `ProviderScope.GLOBAL`
-- Injecting the provider into tools via `this.get(FAQSearch)`
+- Injecting the provider into tools via `this.get(FAQSearchProvider)`
 
 ## Related
 

package/catalog/frontmcp-extensibility/references/skill-audit-log.md

@@ -0,0 +1,233 @@
+---
+name: skill-audit-log
+description: Tamper-evident, hash-chained audit log for skill action executions — pluggable signer, pluggable store, offline verification.
+tags: [extensibility, audit, skills, tamper-evident, signature, chain]
+---
+
+# Skill Audit Log
+
+The `@frontmcp/adapters/skills` module provides a tamper-evident, hash-chained audit log for skill action executions. Every authority pass / authority fail / HTTP success / HTTP failure phase emitted by `execute-action.tool.ts` is captured, signed, and chained so any later mutation breaks signature verification.
+
+## Architecture
+
+The writer exposes one method per phase rather than a generic `append`. Each
+phase method assembles its payload internally and routes through a shared
+chain pipeline:
+
+```text
+ExecuteActionTool.execute()
+  ├── writer.writeAuthorityPass(ctx)             // authority-check-pass
+  ├── writer.writeAuthorityFail(ctx, { reason }) // authority-check-fail
+  ├── writer.writeHttpCallSuccess(ctx, { status, output })  // http-call-success
+  └── writer.writeHttpCallFailure(ctx, { status, error })   // http-call-failure
+       └── shared pipeline:
+            ├── store.tail()                     → previous record
+            ├── store.nextSequence()             → atomic monotonic counter
+            ├── compute prevHash from previous record
+            ├── assemble SkillAuditRecord { sequence, prevHash, phase, ... }
+            ├── SkillAuditSigner.sign(record)    → { signature, keyId, alg }
+            └── store.appendAtSequence(signedRecord)
+```
+
+Each `SkillAuditRecord` carries:
+
+| Field            | Description                                                                                             |
+| ---------------- | ------------------------------------------------------------------------------------------------------- |
+| `sequence`       | Strictly increasing position in the chain                                                               |
+| `prevHash`       | SHA-256 hex of the previous record's canonical bytes (genesis sentinel `'0'.repeat(64)` for sequence 1) |
+| `signature`      | Base64url signature over the canonical record bytes                                                     |
+| `signatureKeyId` | The signer key identifier — used by verifiers to look up the public key                                 |
+| `signatureAlg`   | `'HS256'` or `'RS256'`                                                                                  |
+| `phase`          | `'authority-check-pass' \| 'authority-check-fail' \| 'http-call-success' \| 'http-call-failure'`        |
+| `skillId`        | The skill that owns the action                                                                          |
+| `actionId`       | The action that was executed                                                                            |
+| `subject`        | Authenticated principal — redacted per `subjectMode`                                                    |
+| `bundleVersion`  | The bundle version active at the time of the call                                                       |
+
+## Configuration
+
+Wire the audit subsystem through `skillsConfig.audit` on `@FrontMcp`:
+
+```typescript
+import {
+  Hs256AuditSigner,
+  MemoryAuditStore,
+  setSkillAuditFactory,
+  SkillAuditWriter,
+  SkillAuditWriterToken,
+} from '@frontmcp/adapters/skills';
+
+// Inject the audit module into the SDK at boot. The factory returns the
+// module record; the SDK itself constructs SkillAuditWriter from
+// (store, signer, logger, metrics?, options?) so that subjectMode and other
+// options pass through skillsConfig.audit verbatim.
+setSkillAuditFactory(() => ({
+  SkillAuditWriterToken,
+  SkillAuditWriter,
+  Hs256AuditSigner,
+  MemoryAuditStore,
+}));
+
+@FrontMcp({
+  info: { name: 'svr', version: '1.0.0' },
+  apps: [MainApp],
+  skillsConfig: {
+    enabled: true,
+    audit: {
+      enabled: true,
+      signer: new Hs256AuditSigner(secret, 'dev'),
+      store: new MemoryAuditStore(),
+      subjectMode: 'hash', // 'plain' | 'hash' | 'omit'
+    },
+  },
+})
+class Server {}
+```
+
+`setSkillAuditFactory(...)` injects the audit module into the SDK at boot. The SDK does **not** statically depend on `@frontmcp/adapters/skills` — this keeps the static dependency graph clean and works in Edge / CSP runtimes.
+
+| `skillsConfig.audit` field | Type                          | Default   |
+| -------------------------- | ----------------------------- | --------- |
+| `enabled`                  | `boolean`                     | `false`   |
+| `signer`                   | `SkillAuditSigner`            | dev HS256 |
+| `store`                    | `SkillAuditStore`             | memory    |
+| `subjectMode`              | `'plain' \| 'hash' \| 'omit'` | `'hash'`  |
+| `headAnchorIntervalMs`     | `number \| undefined`         | unset     |
+
+## Built-in Signers
+
+| Signer             | Key                                                 | When to use                                                                          |
+| ------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `Hs256AuditSigner` | Symmetric HMAC-SHA-256                              | Dev / tests only. Refuses to fire when `NODE_ENV === 'production'` with a random key |
+| `Rs256AuditSigner` | Asymmetric RSA (RS256, RSASSA-PKCS1-v1_5 + SHA-256) | **Production.** Reuse the bundle-signing keypair so the same trust root covers both  |
+
+```typescript
+import { Rs256AuditSigner } from '@frontmcp/adapters/skills';
+
+// Constructor signature: new Rs256AuditSigner(privateJwk, keyId)
+// The signer accepts a JWK directly so the same key registry that backs
+// bundle signing can be reused. If your key material lives as PEM, convert
+// it to a JWK first (e.g. via `crypto.createPrivateKey(pem).export({ format: 'jwk' })`
+// or `pemToPrivateJwk` from `@frontmcp/utils`).
+const privateJwk = JSON.parse(process.env.BUNDLE_SIGNING_PRIVATE_JWK!) as JsonWebKey;
+const signer = new Rs256AuditSigner(privateJwk, 'bundle-signing-2026-01');
+```
+
+`Rs256AuditSigner` uses `rsaSignBase64Url` from `@frontmcp/utils` under the hood.
+
+## Built-in Stores
+
+| Store                      | Persistence                                               | When to use      |
+| -------------------------- | --------------------------------------------------------- | ---------------- |
+| `MemoryAuditStore`         | In-process; lost on restart                               | Tests, local dev |
+| `StorageAdapterAuditStore` | Any `@frontmcp/utils` storage adapter (Redis, KV, SQLite) | Production       |
+
+```typescript
+import { StorageAdapterAuditStore } from '@frontmcp/adapters/skills';
+import { createStorageAdapter } from '@frontmcp/utils';
+
+const storage = await createStorageAdapter({ provider: 'redis', host: 'localhost', port: 6379 });
+const store = new StorageAdapterAuditStore(storage);
+```
+
+A custom store implements:
+
+```typescript
+interface SkillAuditStore {
+  /** Allocate the next monotonic sequence atomically. Maps to StorageAdapter.incr in production. */
+  nextSequence(): Promise<number>;
+
+  /** Persist a record at its claimed sequence. MUST refuse / throw if the slot is taken. */
+  appendAtSequence(record: SkillAuditRecord): Promise<void>;
+
+  /** Most recent record (or undefined for empty chain). Drives prevHash for the next write. */
+  tail(): Promise<SkillAuditRecord | undefined>;
+
+  /** Read records in sequence order; supports `{ from, limit }` for incremental verification. */
+  read(opts?: { from?: number; limit?: number }): Promise<SkillAuditRecord[]>;
+}
+```
+
+See [`custom-store`](../examples/skill-audit-log/custom-store.md) for an S3-backed implementation.
+
+## Verifying the Chain
+
+```typescript
+import { defaultAuditSignatureVerifier, verifyChain, type AuditTrustedKey } from '@frontmcp/adapters/skills';
+
+// `read()` walks the chain in sequence order; pass `{ from, limit }` for
+// incremental verification in CI.
+const records = await store.read();
+
+// Trusted keys are passed as an array (per-record `signatureKeyId` selects
+// which entry to use). Supply `publicJwk` or `publicKeyPem` for RS256, or
+// `secret` for HS256.
+const trustedKeys: AuditTrustedKey[] = [
+  { keyId: 'bundle-signing-2026-01', alg: 'RS256', publicKeyPem: PUBLIC_KEY_PEM },
+];
+
+const result = verifyChain(records, trustedKeys, defaultAuditSignatureVerifier);
+
+if (result.ok) {
+  console.log(`Chain verified: ${result.verified} record(s) checked`);
+} else {
+  console.error('Chain broken at sequence', result.breakAt, '—', result.reason);
+}
+```
+
+`verifyChain` returns `{ ok: true; verified: number } | { ok: false; breakAt: number; reason: string }`. The `verified` count is the number of records whose signature + prevHash checked out — useful for dashboards and CI assertions. `defaultAuditSignatureVerifier` understands HS256 and RS256 records and dispatches based on `record.signatureAlg`.
+
+## DI Integration
+
+`SkillAuditWriterToken` is the DI token for the active writer. Plugins that need to emit additional audit records (e.g., a custom authority gate) can resolve it:
+
+```typescript
+import { SkillAuditWriterToken } from '@frontmcp/adapters/skills';
+
+class MyPlugin extends DynamicPlugin {
+  @ToolHook.Will('execute')
+  willExecute(flowCtx: FlowCtxOf<'tools:call-tool'>): void {
+    const writer = flowCtx.scope.tryGet(SkillAuditWriterToken);
+    // Use the phase-specific method matching the event you're recording.
+    // The writer assembles the canonical record (sequence, prevHash,
+    // signature, signatureKeyId, signatureAlg) for you.
+    writer?.writeAuthorityPass({
+      subject: 'user-id',
+      skillId: 'my-skill',
+      actionId: 'my-action',
+      bundleId: 'bundle:id',
+      bundleVersion: '1.0.0',
+      input: {},
+    });
+  }
+}
+```
+
+Plugins should always go through `SkillAuditWriterToken` rather than rolling their own audit log so the chain stays unified.
+
+## Threat Model
+
+What the audit log catches:
+
+- **Record mutation** — any byte-level change breaks the signature.
+- **Record reordering** — the `prevHash` chain breaks.
+- **Record deletion in the middle** — `prevHash` mismatch on the next record.
+
+What it does **not** catch by default:
+
+- **Tail truncation** — if an attacker deletes the tail, no record survives to flag it. Mitigation: `headAnchorIntervalMs` writes the latest `(sequence, hash)` pair to an out-of-band notarization channel (queued for v1.3.0 to be wired into the CAS-based atomic head update).
+- **Multi-pod races** — v1.2.0 is **single-writer only**. Multiple pods writing to the same store will produce a loud warning and may interleave sequences. Route writes to a single elected leader pod or use per-pod chains and stitch offline. CAS-based atomic chain head is queued for v1.3.0.
+
+## Examples
+
+| Example                                                       | Level        | Description                                                                                 |
+| ------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- |
+| [`verify-chain`](../examples/skill-audit-log/verify-chain.md) | Intermediate | Verify a stored chain offline using verifyChain and the bundle-signing key registry.        |
+| [`custom-store`](../examples/skill-audit-log/custom-store.md) | Advanced     | Implement a custom SkillAuditStore that streams records to S3 with one object per sequence. |
+
+> See all examples in [`examples/skill-audit-log/`](../examples/skill-audit-log/)
+
+## Reference
+
+- [Skill Audit Log](https://docs.agentfront.dev/frontmcp/extensibility/skill-audit-log)
+- Related skills: `configure-skills-http`, `create-plugin`