@cubis/foundry 0.3.10

package/Ai Agent Workflow/powers/fastify-patterns/steering/secure-sessions.md

@@ -0,0 +1,479 @@
+# Secure Sessions with Fastify
+
+> Reference for: Fastify Patterns
+> Load when: Cookie authentication, session management, secure-session, key rotation, stateless sessions
+
+---
+
+## Overview
+
+`@fastify/secure-session` provides encrypted, stateless cookie sessions using libsodium's Secret Key Box Encryption. Unlike server-side sessions (Redis/database), the session data is stored entirely in an encrypted cookie.
+
+## When to Use
+
+**Use secure-session when:**
+
+- You want stateless authentication (no session store)
+- Session data is small (< 4KB after encryption)
+- You need horizontal scaling without shared state
+- You want simple deployment without Redis
+
+**Use server-side sessions (Redis) when:**
+
+- You need to revoke sessions server-side
+- Session data exceeds cookie limits
+- You need to track active sessions
+- Compliance requires server-side session control
+
+---
+
+## Installation
+
+```bash
+bun add @fastify/cookie @fastify/secure-session
+```
+
+## Generate Session Key
+
+```bash
+# Generate hex string for environment variable (recommended)
+bun -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+
+# Or generate a secure key file
+bunx @fastify/secure-session > secret-key
+```
+
+---
+
+## Basic Setup
+
+### Using Key File
+
+```typescript
+// main.ts
+import { NestFactory } from "@nestjs/core";
+import {
+  FastifyAdapter,
+  NestFastifyApplication,
+} from "@nestjs/platform-fastify";
+import cookie from "@fastify/cookie";
+import secureSession from "@fastify/secure-session";
+import * as fs from "fs";
+import * as path from "path";
+
+async function bootstrap() {
+  const app = await NestFactory.create<NestFastifyApplication>(
+    AppModule,
+    new FastifyAdapter(),
+  );
+
+  await app.register(cookie);
+  await app.register(secureSession, {
+    key: fs.readFileSync(path.join(__dirname, "..", "secret-key")),
+    cookie: {
+      path: "/",
+      httpOnly: true,
+      secure: process.env.NODE_ENV === "production",
+      sameSite: "lax",
+    },
+  });
+
+  await app.listen(3000, "0.0.0.0");
+}
+```
+
+### Using Environment Variable (Recommended for Production)
+
+```typescript
+// main.ts
+import secureSession from "@fastify/secure-session";
+
+async function bootstrap() {
+  const app = await NestFactory.create<NestFastifyApplication>(
+    AppModule,
+    new FastifyAdapter(),
+  );
+
+  // Validate session secret exists
+  if (!process.env.SESSION_SECRET) {
+    throw new Error("SESSION_SECRET environment variable is required");
+  }
+
+  await app.register(cookie);
+  await app.register(secureSession, {
+    cookieName: process.env.SESSION_COOKIE_NAME || "oneup.sid",
+    key: Buffer.from(process.env.SESSION_SECRET, "hex"),
+    expiry: 24 * 60 * 60, // 1 day in seconds
+    cookie: {
+      path: "/",
+      httpOnly: true,
+      secure: process.env.NODE_ENV === "production",
+      sameSite: "lax",
+    },
+  });
+
+  await app.listen(3000, "0.0.0.0");
+}
+```
+
+---
+
+## Session Guard Implementation
+
+```typescript
+// src/core/guards/session-auth.guard.ts
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  UnauthorizedException,
+} from "@nestjs/common";
+import { FastifyRequest } from "fastify";
+
+export interface SessionUser {
+  userId: string;
+  role: string;
+  organizationId: string;
+  departmentId?: string;
+  positionId?: string;
+}
+
+@Injectable()
+export class SessionAuthGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const request = context.switchToHttp().getRequest<FastifyRequest>();
+    const session = request.session;
+
+    // Check if session has userId
+    const userId = session.get("userId");
+    if (!userId) {
+      throw new UnauthorizedException("Authentication required");
+    }
+
+    // Attach user object to request for downstream use
+    (request as any).user = {
+      userId,
+      role: session.get("role"),
+      organizationId: session.get("organizationId"),
+      departmentId: session.get("departmentId"),
+      positionId: session.get("positionId"),
+    } as SessionUser;
+
+    return true;
+  }
+}
+```
+
+---
+
+## Auth Service with Sessions
+
+```typescript
+// src/modules/auth/auth.service.ts
+import { Injectable, UnauthorizedException } from "@nestjs/common";
+import { FastifyRequest } from "fastify";
+import * as bcrypt from "bcrypt";
+import { UsersRepository } from "../users/users.repository";
+import { LoginDto } from "./dto/login.dto";
+
+@Injectable()
+export class AuthService {
+  constructor(private readonly usersRepository: UsersRepository) {}
+
+  async login(request: FastifyRequest, dto: LoginDto): Promise<void> {
+    // Find user by username
+    const user = await this.usersRepository.findByUsername(dto.username);
+    if (!user) {
+      throw new UnauthorizedException("Invalid credentials");
+    }
+
+    // Verify password
+    const isValid = await bcrypt.compare(dto.password, user.password);
+    if (!isValid) {
+      throw new UnauthorizedException("Invalid credentials");
+    }
+
+    // Check if account is enabled
+    if (!user.enabled) {
+      throw new UnauthorizedException("Account is disabled");
+    }
+
+    // Set session data
+    request.session.set("userId", user._id.toString());
+    request.session.set("role", user.role);
+    request.session.set("organizationId", user.organizationId);
+    request.session.set("departmentId", user.departmentId);
+    request.session.set("positionId", user.positionId);
+
+    // Update last login
+    await this.usersRepository.updateLastLogin(user._id.toString());
+  }
+
+  async logout(request: FastifyRequest): Promise<void> {
+    request.session.delete();
+  }
+
+  async refreshSession(request: FastifyRequest): Promise<void> {
+    // Touch session to extend expiry
+    request.session.touch();
+  }
+}
+```
+
+---
+
+## Auth Controller
+
+```typescript
+// src/modules/auth/auth.controller.ts
+import {
+  Body,
+  Controller,
+  HttpCode,
+  HttpStatus,
+  Post,
+  Req,
+  UseGuards,
+} from "@nestjs/common";
+import { ApiOperation, ApiResponse, ApiTags } from "@nestjs/swagger";
+import { FastifyRequest } from "fastify";
+import { AuthService } from "./auth.service";
+import { LoginDto } from "./dto/login.dto";
+import { SessionAuthGuard } from "../../core/guards/session-auth.guard";
+
+@ApiTags("Authentication")
+@Controller("auth")
+export class AuthController {
+  constructor(private readonly authService: AuthService) {}
+
+  @Post("login")
+  @HttpCode(HttpStatus.OK)
+  @ApiOperation({ summary: "Login and create session" })
+  @ApiResponse({ status: 200, description: "Login successful" })
+  @ApiResponse({ status: 401, description: "Invalid credentials" })
+  async login(
+    @Req() request: FastifyRequest,
+    @Body() dto: LoginDto,
+  ): Promise<{ status: string }> {
+    await this.authService.login(request, dto);
+    return { status: "ok" };
+  }
+
+  @Post("logout")
+  @UseGuards(SessionAuthGuard)
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({ summary: "Logout and destroy session" })
+  async logout(@Req() request: FastifyRequest): Promise<void> {
+    await this.authService.logout(request);
+  }
+
+  @Post("refresh")
+  @UseGuards(SessionAuthGuard)
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({ summary: "Refresh session expiry" })
+  async refresh(@Req() request: FastifyRequest): Promise<void> {
+    await this.authService.refreshSession(request);
+  }
+}
+```
+
+---
+
+## Key Rotation
+
+Support rotating session keys without invalidating existing sessions:
+
+```typescript
+// main.ts - Key rotation setup
+import * as fs from "fs";
+import * as path from "path";
+
+async function bootstrap() {
+  const app = await NestFactory.create<NestFastifyApplication>(
+    AppModule,
+    new FastifyAdapter(),
+  );
+
+  // Load keys - newest first
+  const keys = [process.env.SESSION_SECRET_NEW, process.env.SESSION_SECRET_OLD]
+    .filter(Boolean)
+    .map((hex) => Buffer.from(hex!, "hex"));
+
+  if (keys.length === 0) {
+    throw new Error("At least one SESSION_SECRET is required");
+  }
+
+  await app.register(cookie);
+  await app.register(secureSession, {
+    cookieName: "oneup.sid",
+    key: keys, // Array of keys for rotation
+    cookie: {
+      path: "/",
+      httpOnly: true,
+      secure: process.env.NODE_ENV === "production",
+      sameSite: "lax",
+    },
+  });
+
+  await app.listen(3000, "0.0.0.0");
+}
+```
+
+**Key Rotation Process:**
+
+1. Generate new key: `bun -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
+2. Set `SESSION_SECRET_NEW` to new key
+3. Set `SESSION_SECRET_OLD` to current key
+4. Deploy - new sessions use new key, old sessions still work
+5. After all old sessions expire, remove `SESSION_SECRET_OLD`
+
+---
+
+## Session Data Access Patterns
+
+```typescript
+// Setting session data
+request.session.set("userId", "123");
+request.session.set("role", "admin");
+
+// Getting session data
+const userId = request.session.get("userId");
+const role = request.session.get("role");
+
+// Get all session data
+const allData = request.session.data();
+
+// Delete specific key (set to undefined)
+request.session.set("tempData", undefined);
+
+// Delete entire session
+request.session.delete();
+
+// Touch session (extend expiry without changing data)
+request.session.touch();
+
+// Regenerate session (clear all data, keep session)
+request.session.regenerate();
+
+// Regenerate but keep specific keys
+request.session.regenerate(["userId", "role"]);
+
+// Update cookie options for this request
+request.session.options({ maxAge: 3600 });
+```
+
+---
+
+## TypeScript Session Typing
+
+```typescript
+// src/types/fastify.d.ts
+import "@fastify/secure-session";
+
+declare module "@fastify/secure-session" {
+  interface SessionData {
+    userId: string;
+    role: string;
+    organizationId: string;
+    departmentId?: string;
+    positionId?: string;
+  }
+}
+```
+
+---
+
+## Security Best Practices
+
+### Cookie Configuration
+
+```typescript
+cookie: {
+  path: '/',
+  httpOnly: true,        // Prevent XSS access
+  secure: true,          // HTTPS only in production
+  sameSite: 'lax',       // CSRF protection
+  // maxAge is handled by 'expiry' option
+}
+```
+
+### Environment Variables
+
+```bash
+# .env.production
+SESSION_SECRET=<64-char-hex-string>
+SESSION_COOKIE_NAME=oneup.sid
+NODE_ENV=production
+```
+
+### Session Expiry
+
+```typescript
+await app.register(secureSession, {
+  expiry: 24 * 60 * 60, // 1 day in seconds
+  // ...
+});
+```
+
+---
+
+## Troubleshooting
+
+### Session Not Persisting
+
+1. Check `httpOnly` and `secure` settings match environment
+2. Verify CORS `credentials: true` if cross-origin
+3. Check cookie domain matches request domain
+4. Verify session secret is valid hex string
+
+### "Invalid session" Errors
+
+1. Session secret changed - users need to re-login
+2. Key rotation not configured correctly
+3. Cookie expired
+
+### Debug Logging
+
+```typescript
+const app = await NestFactory.create<NestFastifyApplication>(
+  AppModule,
+  new FastifyAdapter({ logger: { level: "debug" } }),
+);
+```
+
+---
+
+## Testing Sessions
+
+```typescript
+// test/auth.e2e-spec.ts
+import { Test } from "@nestjs/testing";
+import { INestApplication } from "@nestjs/common";
+import * as request from "supertest";
+
+describe("Auth (e2e)", () => {
+  let app: INestApplication;
+  let agent: request.SuperAgentTest;
+
+  beforeAll(async () => {
+    // ... setup
+    agent = request.agent(app.getHttpServer());
+  });
+
+  it("should login and maintain session", async () => {
+    // Login
+    await agent
+      .post("/auth/login")
+      .send({ username: "test", password: "password" })
+      .expect(200);
+
+    // Access protected route with session cookie
+    await agent.get("/users/me").expect(200);
+  });
+
+  it("should logout and clear session", async () => {
+    await agent.post("/auth/logout").expect(204);
+    await agent.get("/users/me").expect(401);
+  });
+});
+```

package/Ai Agent Workflow/powers/feature-forge/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: feature-forge
+description: Use when defining new features, gathering requirements, or writing specifications. Invoke for feature definition, requirements gathering, user stories, EARS format specs.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.0.0"
+  domain: workflow
+  triggers: requirements, specification, feature definition, user stories, EARS, planning
+  role: specialist
+  scope: design
+  output-format: document
+  related-skills: fullstack-guardian, spec-miner, test-master
+---
+
+# Feature Forge
+
+Requirements specialist conducting structured workshops to define comprehensive feature specifications.
+
+## Role Definition
+
+You are a senior product analyst with 10+ years of experience. You operate with two perspectives:
+- **PM Hat**: Focused on user value, business goals, success metrics
+- **Dev Hat**: Focused on technical feasibility, security, performance, edge cases
+
+## When to Use This Skill
+
+- Defining new features from scratch
+- Gathering comprehensive requirements
+- Writing specifications in EARS format
+- Creating acceptance criteria
+- Planning implementation TODO lists
+
+## Core Workflow
+
+1. **Discover** - Use `AskUserQuestions` to understand the feature goal, target users, and user value. Present structured choices where possible (e.g., user types, priority level).
+2. **Interview** - Systematic questioning from both PM and Dev perspectives using `AskUserQuestions` for structured choices and open-ended follow-ups. Use multi-agent discovery with Task subagents when the feature spans multiple domains (see interview-questions.md for guidance).
+3. **Document** - Write EARS-format requirements
+4. **Validate** - Use `AskUserQuestions` to review acceptance criteria with stakeholder, presenting key trade-offs as structured choices
+5. **Plan** - Create implementation checklist
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| EARS Syntax | `steering/ears-syntax.md` | Writing functional requirements |
+| Interview Questions | `steering/interview-questions.md` | Gathering requirements |
+| Specification Template | `steering/specification-template.md` | Writing final spec document |
+| Acceptance Criteria | `steering/acceptance-criteria.md` | Given/When/Then format |
+| Pre-Discovery Subagents | `steering/pre-discovery-subagents.md` | Multi-domain features needing front-loaded context |
+
+## Constraints
+
+### MUST DO
+- Use `AskUserQuestions` tool for structured elicitation (priority, scope, format choices)
+- Use open-ended questions only when choices cannot be predetermined
+- Conduct thorough interview before writing spec
+- Use EARS format for all functional requirements
+- Include non-functional requirements (performance, security)
+- Provide testable acceptance criteria
+- Include implementation TODO checklist
+- Ask for clarification on ambiguous requirements
+
+### MUST NOT DO
+- Output interview questions as plain text when `AskUserQuestions` can provide structured options
+- Generate spec without conducting interview
+- Accept vague requirements ("make it fast")
+- Skip security considerations
+- Forget error handling requirements
+- Write untestable acceptance criteria
+
+## Output Templates
+
+The final specification must include:
+1. Overview and user value
+2. Functional requirements (EARS format)
+3. Non-functional requirements
+4. Acceptance criteria (Given/When/Then)
+5. Error handling table
+6. Implementation TODO checklist
+
+Save as: `specs/{feature_name}.spec.md`
+
+## Knowledge Reference
+
+EARS syntax, user stories, acceptance criteria, Given-When-Then, INVEST criteria, MoSCoW prioritization, OWASP security requirements

package/Ai Agent Workflow/powers/feature-forge/steering/acceptance-criteria.md

@@ -0,0 +1,104 @@
+# Acceptance Criteria
+
+## Given-When-Then Format
+
+```markdown
+### AC-001: [Scenario Name]
+Given [context/precondition]
+When [action taken]
+Then [expected result]
+```
+
+## Examples by Type
+
+### Happy Path
+
+```markdown
+### AC-001: Successful Login
+Given a registered user with valid credentials
+When they submit the login form
+Then they are redirected to the dashboard
+And a success message is displayed
+And their session is created
+
+### AC-002: Add Item to Cart
+Given a logged-in user viewing a product
+When they click "Add to Cart"
+Then the item appears in their cart
+And the cart badge updates with the count
+And a confirmation toast is shown
+```
+
+### Error Cases
+
+```markdown
+### AC-003: Invalid Login
+Given a user with incorrect password
+When they submit the login form
+Then an error message "Invalid credentials" is displayed
+And the password field is cleared
+And they remain on the login page
+
+### AC-004: Duplicate Email Registration
+Given an email already exists in the system
+When a new user tries to register with that email
+Then an error message "Email already registered" is displayed
+And the form is not submitted
+```
+
+### Edge Cases
+
+```markdown
+### AC-005: Empty Cart Checkout
+Given a user with an empty cart
+When they navigate to checkout
+Then they see "Your cart is empty" message
+And a "Continue Shopping" button is displayed
+
+### AC-006: Session Expiry
+Given a user whose session has expired
+When they try to perform any authenticated action
+Then they are redirected to login
+And a message "Session expired, please log in again" is shown
+And their intended action is preserved for after login
+```
+
+### Authorization
+
+```markdown
+### AC-007: Admin-Only Access
+Given a regular user (non-admin)
+When they try to access /admin/users
+Then they receive a 403 Forbidden response
+And are redirected to the home page
+And an "Access denied" message is shown
+
+### AC-008: Own Resource Only
+Given a user viewing another user's profile
+When they try to edit the profile
+Then the edit button is not visible
+And direct URL access returns 403
+```
+
+## INVEST Criteria
+
+Good acceptance criteria follow INVEST:
+
+| Criterion | Description | Check |
+|-----------|-------------|-------|
+| **I**ndependent | Can be tested alone | No dependencies on other ACs |
+| **N**egotiable | Details can be discussed | Not over-specified |
+| **V**aluable | Delivers user value | Ties to requirement |
+| **E**stimable | Effort can be estimated | Clear scope |
+| **S**mall | Testable in one session | Not too broad |
+| **T**estable | Pass/fail is clear | Objective criteria |
+
+## Quick Reference
+
+| Scenario Type | Given | When | Then |
+|---------------|-------|------|------|
+| Happy path | Valid state | Valid action | Success result |
+| Error | Invalid state/input | Action | Error message |
+| Edge case | Boundary condition | Action | Graceful handling |
+| Authorization | User role | Protected action | Appropriate access |
+| Concurrency | Multiple actors | Simultaneous action | Consistent state |