@vurb/core 3.2.3 → 3.3.4

package/dist/cli/templates/vectors/database.js

@@ -4,79 +4,79 @@
  */
 /** Generate `prisma/schema.prisma` */
 export function prismaSchema() {
-    return `// Prisma Schema — Database-Driven MCP Server
-//
-// The @vurb/prisma-gen generator reads annotations
-// and auto-generates Presenters + ToolBuilders with:
-// - Field-level security (/// @vurb.hide)
-// - Tenant isolation
-// - OOM protection
-
-generator client {
-    provider = "prisma-client-js"
-}
-
-generator vurb {
-    provider = "@vurb/prisma-gen"
-}
-
-datasource db {
-    provider = "postgresql"
-    url      = env("DATABASE_URL")
-}
-
-model User {
-    id        String   @id @default(cuid())
-    email     String   @unique
-    name      String
-
-    /// @vurb.hide — Stripped by the Egress Firewall before reaching the LLM
-    password  String
-
-    role      String   @default("USER")
-    createdAt DateTime @default(now())
-    updatedAt DateTime @updatedAt
-
-    posts     Post[]
-}
-
-model Post {
-    id        String   @id @default(cuid())
-    title     String
-    content   String?
-    published Boolean  @default(false)
-    createdAt DateTime @default(now())
-
-    author    User     @relation(fields: [authorId], references: [id])
-    authorId  String
-}
+    return `// Prisma Schema — Database-Driven MCP Server
+//
+// The @vurb/prisma-gen generator reads annotations
+// and auto-generates Presenters + ToolBuilders with:
+// - Field-level security (/// @vurb.hide)
+// - Tenant isolation
+// - OOM protection
+
+generator client {
+    provider = "prisma-client-js"
+}
+
+generator vurb {
+    provider = "@vurb/prisma-gen"
+}
+
+datasource db {
+    provider = "postgresql"
+    url      = env("DATABASE_URL")
+}
+
+model User {
+    id        String   @id @default(cuid())
+    email     String   @unique
+    name      String
+
+    /// @vurb.hide — Stripped by the Egress Firewall before reaching the LLM
+    password  String
+
+    role      String   @default("USER")
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    posts     Post[]
+}
+
+model Post {
+    id        String   @id @default(cuid())
+    title     String
+    content   String?
+    published Boolean  @default(false)
+    createdAt DateTime @default(now())
+
+    author    User     @relation(fields: [authorId], references: [id])
+    authorId  String
+}
 `;
 }
 /** Generate `src/tools/db/users.ts` */
 export function dbUsersToolTs() {
-    return `/**
- * Database Users Tool — Prisma-Driven CRUD (Fluent API)
- *
- * Demonstrates:
- * - f.query() with .withOptionalNumber() typed parameter
- * - .handle(input, ctx) — input.take is typed as number | undefined
- * - Implicit success() wrapping
- */
-import { f } from '../../vurb.js';
-
-export default f.query('db.list_users')
-    .describe('List users from the database')
-    .withOptionalNumber('take', 'Max results (1-50)')
-    .handle(async (input, ctx) => {
-        // TODO: Replace with your Prisma client
-        // const users = await ctx.db.user.findMany({ take: input.take ?? 10 });
-        // return users;
-
-        return {
-            hint: 'Connect your Prisma client in src/context.ts to enable database queries.',
-            example: 'const users = await ctx.db.user.findMany({ take: 10 })',
-        };
-    });
+    return `/**
+ * Database Users Tool — Prisma-Driven CRUD (Fluent API)
+ *
+ * Demonstrates:
+ * - f.query() with .withOptionalNumber() typed parameter
+ * - .handle(input, ctx) — input.take is typed as number | undefined
+ * - Implicit success() wrapping
+ */
+import { f } from '../../vurb.js';
+
+export default f.query('db.list_users')
+    .describe('List users from the database')
+    .withOptionalNumber('take', 'Max results (1-50)')
+    .handle(async (input, ctx) => {
+        // TODO: Replace with your Prisma client
+        // const users = await ctx.db.user.findMany({ take: input.take ?? 10 });
+        // return users;
+
+        return {
+            hint: 'Connect your Prisma client in src/context.ts to enable database queries.',
+            example: 'const users = await ctx.db.user.findMany({ take: 10 })',
+        };
+    });
 `;
 }
 //# sourceMappingURL=database.js.map

package/dist/cli/templates/vectors/oauth.js

@@ -4,73 +4,73 @@
  */
 /** Generate `src/auth.ts` — OAuth Device Flow setup */
 export function oauthSetupTs(config) {
-    return `/**
- * OAuth Setup — Device Flow Authentication (RFC 8628)
- *
- * Pre-configured \`createAuthTool()\` with login, complete, status, logout actions.
- * The \`requireAuth()\` middleware protects any tool with one line.
- *
- * 1. Set CLIENT_ID and AUTH endpoints in .env
- * 2. Register the auth tool in server.ts
- * 3. Use \`requireAuth()\` on protected tools
- */
-import { createAuthTool, TokenManager } from '@vurb/oauth';
-import type { ToolRegistry } from '@vurb/core';
-
-export function registerAuth<TContext>(registry: ToolRegistry<TContext>): void {
-    const clientId = process.env['OAUTH_CLIENT_ID'];
-    const authEndpoint = process.env['OAUTH_AUTH_ENDPOINT'];
-    const tokenEndpoint = process.env['OAUTH_TOKEN_ENDPOINT'];
-
-    if (!clientId || !authEndpoint || !tokenEndpoint) {
-        console.error('⚠️  OAUTH_CLIENT_ID, OAUTH_AUTH_ENDPOINT, OAUTH_TOKEN_ENDPOINT are required in .env');
-        return;
-    }
-
-    const auth = createAuthTool({
-        clientId,
-        authorizationEndpoint: authEndpoint,
-        tokenEndpoint,
-        tokenManager: {
-            configDir: '.${config.name}',
-            envVar: '${config.name.toUpperCase().replace(/-/g, '_')}_TOKEN',
-        },
-    });
-
-    registry.register(auth);
-    console.error('🔐 OAuth Device Flow registered (auth.login → auth.complete → auth.status)');
-}
+    return `/**
+ * OAuth Setup — Device Flow Authentication (RFC 8628)
+ *
+ * Pre-configured \`createAuthTool()\` with login, complete, status, logout actions.
+ * The \`requireAuth()\` middleware protects any tool with one line.
+ *
+ * 1. Set CLIENT_ID and AUTH endpoints in .env
+ * 2. Register the auth tool in server.ts
+ * 3. Use \`requireAuth()\` on protected tools
+ */
+import { createAuthTool, TokenManager } from '@vurb/oauth';
+import type { ToolRegistry } from '@vurb/core';
+
+export function registerAuth<TContext>(registry: ToolRegistry<TContext>): void {
+    const clientId = process.env['OAUTH_CLIENT_ID'];
+    const authEndpoint = process.env['OAUTH_AUTH_ENDPOINT'];
+    const tokenEndpoint = process.env['OAUTH_TOKEN_ENDPOINT'];
+
+    if (!clientId || !authEndpoint || !tokenEndpoint) {
+        console.error('⚠️  OAUTH_CLIENT_ID, OAUTH_AUTH_ENDPOINT, OAUTH_TOKEN_ENDPOINT are required in .env');
+        return;
+    }
+
+    const auth = createAuthTool({
+        clientId,
+        authorizationEndpoint: authEndpoint,
+        tokenEndpoint,
+        tokenManager: {
+            configDir: '.${config.name}',
+            envVar: '${config.name.toUpperCase().replace(/-/g, '_')}_TOKEN',
+        },
+    });
+
+    registry.register(auth);
+    console.error('🔐 OAuth Device Flow registered (auth.login → auth.complete → auth.status)');
+}
 `;
 }
 /** Generate `src/middleware/auth.ts` — requireAuth middleware */
 export function oauthMiddlewareTs() {
-    return `/**
- * Auth Middleware — Protect tools with requireAuth()
- *
- * @example
- * \`\`\`ts
- * import { withAuth } from '../middleware/auth.js';
- *
- * export default f.query('projects.list')
- *     .describe('List all projects')
- *     .use(withAuth)
- *     .handle(async (input, ctx) => { /* authenticated */ });
- * \`\`\`
- */
-import { requireAuth } from '@vurb/oauth';
-
-/**
- * Pre-configured auth middleware.
- * Rejects unauthenticated requests with \`AUTH_REQUIRED\` + self-healing hints.
- */
-export const withAuth = requireAuth({
-    extractToken: (ctx: unknown) => {
-        const obj = ctx as Record<string, unknown>;
-        return typeof obj['token'] === 'string' ? obj['token'] : null;
-    },
-    recoveryHint: 'Call auth action=login to authenticate via browser',
-    recoveryAction: 'auth',
-});
+    return `/**
+ * Auth Middleware — Protect tools with requireAuth()
+ *
+ * @example
+ * \`\`\`ts
+ * import { withAuth } from '../middleware/auth.js';
+ *
+ * export default f.query('projects.list')
+ *     .describe('List all projects')
+ *     .use(withAuth)
+ *     .handle(async (input, ctx) => { /* authenticated */ });
+ * \`\`\`
+ */
+import { requireAuth } from '@vurb/oauth';
+
+/**
+ * Pre-configured auth middleware.
+ * Rejects unauthenticated requests with \`AUTH_REQUIRED\` + self-healing hints.
+ */
+export const withAuth = requireAuth({
+    extractToken: (ctx: unknown) => {
+        const obj = ctx as Record<string, unknown>;
+        return typeof obj['token'] === 'string' ? obj['token'] : null;
+    },
+    recoveryHint: 'Call auth action=login to authenticate via browser',
+    recoveryAction: 'auth',
+});
 `;
 }
 //# sourceMappingURL=oauth.js.map

package/dist/cli/templates/vectors/openapi.js

@@ -1,106 +1,106 @@
 /** Generate `openapi.yaml` — Sample OpenAPI spec */
 export function openapiYaml(config) {
-    return `# OpenAPI 3.0 Specification — Sample
-#
-# Replace this with your actual API spec, then run:
-#   npx @vurb/openapi-gen ./openapi.yaml --outDir ./src/generated
-#
-# The generator creates Presenters, Tools, Registry, and server
-# bootstrap — all configurable via YAML annotations.
-
-openapi: '3.0.3'
-info:
-  title: '${config.name} API'
-  version: '0.1.0'
-  description: Sample API for Vurb OpenAPI generation
-
-servers:
-  - url: http://localhost:3000/api
-
-paths:
-  /health:
-    get:
-      operationId: getHealth
-      summary: Health check endpoint
-      responses:
-        '200':
-          description: Server health status
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  status:
-                    type: string
-                    example: healthy
-                  uptime:
-                    type: number
-                    example: 12345.67
-
-  /users:
-    get:
-      operationId: listUsers
-      summary: List all users
-      parameters:
-        - name: limit
-          in: query
-          schema:
-            type: integer
-            minimum: 1
-            maximum: 100
-            default: 10
-      responses:
-        '200':
-          description: List of users
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/User'
-
-components:
-  schemas:
-    User:
-      type: object
-      properties:
-        id:
-          type: string
-        name:
-          type: string
-        email:
-          type: string
+    return `# OpenAPI 3.0 Specification — Sample
+#
+# Replace this with your actual API spec, then run:
+#   npx @vurb/openapi-gen ./openapi.yaml --outDir ./src/generated
+#
+# The generator creates Presenters, Tools, Registry, and server
+# bootstrap — all configurable via YAML annotations.
+
+openapi: '3.0.3'
+info:
+  title: '${config.name} API'
+  version: '0.1.0'
+  description: Sample API for Vurb OpenAPI generation
+
+servers:
+  - url: http://localhost:3000/api
+
+paths:
+  /health:
+    get:
+      operationId: getHealth
+      summary: Health check endpoint
+      responses:
+        '200':
+          description: Server health status
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: healthy
+                  uptime:
+                    type: number
+                    example: 12345.67
+
+  /users:
+    get:
+      operationId: listUsers
+      summary: List all users
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 10
+      responses:
+        '200':
+          description: List of users
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        email:
+          type: string
 `;
 }
 /** Generate `SETUP.md` — OpenAPI generation instructions */
 export function openapiSetupMd() {
-    return `# OpenAPI Generator Setup
-
-This project is configured for the **Legacy API Proxy** ingestion vector.
-
-## Steps
-
-1. Replace \`openapi.yaml\` with your actual OpenAPI 3.x spec
-
-2. Generate the MCP server from the spec:
-   \`\`\`bash
-   npx @vurb/openapi-gen ./openapi.yaml --outDir ./src/generated
-   \`\`\`
-
-3. The generator creates:
-   - Presenters with Zod schemas (Egress Firewall)
-   - Tool builders with typed handlers
-   - Registry setup with all endpoints
-
-4. Import and register in \`src/server.ts\`:
-   \`\`\`typescript
-   import { generatedTools } from './generated/registry.js';
-   registry.registerAll(...generatedTools);
-   \`\`\`
-
-## Documentation
-
-See: [OpenAPI Generator](https://vurb.vinkius.com/openapi-gen)
+    return `# OpenAPI Generator Setup
+
+This project is configured for the **Legacy API Proxy** ingestion vector.
+
+## Steps
+
+1. Replace \`openapi.yaml\` with your actual OpenAPI 3.x spec
+
+2. Generate the MCP server from the spec:
+   \`\`\`bash
+   npx @vurb/openapi-gen ./openapi.yaml --outDir ./src/generated
+   \`\`\`
+
+3. The generator creates:
+   - Presenters with Zod schemas (Egress Firewall)
+   - Tool builders with typed handlers
+   - Registry setup with all endpoints
+
+4. Import and register in \`src/server.ts\`:
+   \`\`\`typescript
+   import { generatedTools } from './generated/registry.js';
+   registry.registerAll(...generatedTools);
+   \`\`\`
+
+## Documentation
+
+See: [OpenAPI Generator](https://vurb.vinkius.com/openapi-gen)
 `;
 }
 //# sourceMappingURL=openapi.js.map

package/dist/core/middleware/AuditTrail.d.ts

@@ -0,0 +1,128 @@
+/**
+ * AuditTrail — SOC2/GDPR Compliance Middleware
+ *
+ * Structured audit logging of every tool invocation via {@link TelemetrySink}.
+ * Emits `security.audit` events with identity, action, args hash, result
+ * status, and duration — providing a complete audit trail for compliance.
+ *
+ * SOC2 Coverage:
+ * - CC6.1 — Logical Access (identity.userId, identity.role)
+ * - CC7.2 — Monitoring (every invocation logged)
+ * - CC7.3 — Change Detection (argsHash for mutation tracking)
+ *
+ * GDPR Coverage:
+ * - Art.30 — Records of Processing (tool, action, identity, timestamp)
+ * - Art.5(1)(c) — Data Minimization (hashArgs: true — no PII in log)
+ *
+ * @example
+ * ```typescript
+ * import { auditTrail } from '@vurb/core';
+ *
+ * const billing = createTool('billing')
+ *     .use(auditTrail({
+ *         sink: telemetrySink,
+ *         extractIdentity: (ctx) => ({
+ *             userId: ctx.userId,
+ *             role: ctx.role,
+ *         }),
+ *     }));
+ * ```
+ *
+ * @module
+ */
+import type { MiddlewareFn } from '../types.js';
+/** Identity information extracted from the request context */
+export interface AuditIdentity {
+    readonly userId?: string;
+    readonly role?: string;
+    readonly ip?: string;
+    readonly [key: string]: string | undefined;
+}
+/**
+ * Result status for audit logging.
+ */
+export type AuditStatus = 'success' | 'error' | 'firewall_blocked' | 'rate_limited';
+/**
+ * A single audit event emitted by the middleware.
+ */
+export interface SecurityAuditEvent {
+    readonly type: 'security.audit';
+    /** Tool name (e.g., 'billing') */
+    readonly tool: string;
+    /** Action name (e.g., 'create_invoice') */
+    readonly action: string;
+    /** Extracted identity information */
+    readonly identity: AuditIdentity;
+    /** SHA-256 hash of the arguments (or 'none' if disabled) */
+    readonly argsHash: string;
+    /** Execution result status */
+    readonly status: AuditStatus;
+    /** Execution duration in milliseconds */
+    readonly durationMs: number;
+    /** Epoch milliseconds */
+    readonly timestamp: number;
+}
+/**
+ * Sink function for audit events.
+ * Fire-and-forget — dropping events must never affect the server.
+ */
+export type AuditSink = (event: SecurityAuditEvent) => void;
+/**
+ * Configuration for the AuditTrail middleware.
+ */
+export interface AuditTrailConfig {
+    /**
+     * Sink function for audit events.
+     * Can be a TelemetrySink, a logging function, or any other consumer.
+     */
+    readonly sink: AuditSink;
+    /**
+     * Tool name to include in audit events.
+     * Should match the tool's registered name (e.g., 'billing').
+     */
+    readonly toolName?: string;
+    /**
+     * Field name used as the action discriminator in tool arguments.
+     * Defaults to `'action'`. Set to the correct discriminator for
+     * non-standard tools (e.g., `'command'`, `'operation'`).
+     *
+     * @default 'action'
+     */
+    readonly actionField?: string;
+    /**
+     * Extract identity information from the request context.
+     * Return fields relevant for your compliance requirements.
+     *
+     * @param ctx - Request context
+     * @returns Identity object for audit logging
+     */
+    readonly extractIdentity?: (ctx: unknown) => AuditIdentity;
+    /**
+     * Whether to hash the arguments (SHA-256).
+     * When `true`, args are hashed for change detection without storing PII.
+     *
+     * @default true
+     */
+    readonly hashArgs?: boolean;
+    /**
+     * What level of result detail to log.
+     *
+     * - `'status'` — Log only success/error status (recommended)
+     * - `'none'` — Don't log result at all
+     *
+     * @default 'status'
+     */
+    readonly logResult?: 'status' | 'none';
+}
+/**
+ * Create an AuditTrail middleware for SOC2/GDPR compliance.
+ *
+ * Logs every tool invocation with identity, args hash, status,
+ * and duration. The audit event is emitted AFTER the handler
+ * completes (or fails), capturing the full lifecycle.
+ *
+ * @param config - Audit trail configuration
+ * @returns A middleware function compatible with `.use()`
+ */
+export declare function auditTrail(config: AuditTrailConfig): MiddlewareFn<unknown>;
+//# sourceMappingURL=AuditTrail.d.ts.map

package/dist/core/middleware/AuditTrail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuditTrail.d.ts","sourceRoot":"","sources":["../../../src/core/middleware/AuditTrail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,kBAAkB,GAAG,cAAc,CAAC;AAEpF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,aAAa,CAAC;IAE3D;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC1C;AAyBD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,YAAY,CAAC,OAAO,CAAC,CA+C1E"}