@everystack/mcp 0.2.3 → 0.3.0

package/dist/security-device.md

@@ -0,0 +1,99 @@
+# Device Security
+
+> Device attestation and biometric auth. Import from `@everystack/security`.
+
+## When to Use
+Read this when adding hardware-backed security: device trust verification, biometric authentication, or certificate pinning.
+
+## Setup
+
+```typescript
+import { createSecurityHandler } from '@everystack/security';
+
+const security = createSecurityHandler({
+  apple: { teamId: '...', bundleId: '...' },
+  google: { packageName: '...' },
+});
+```
+
+## Device Attestation
+
+Verify that requests come from genuine devices (not emulators or modified apps).
+
+### Apple App Attest
+```typescript
+import { verifyAppleAttestation } from '@everystack/security';
+
+const result = await verifyAppleAttestation({
+  attestation: base64AttestationData,
+  challenge: serverChallenge,
+  teamId: 'TEAM_ID',
+  bundleId: 'com.example.app',
+});
+```
+
+### Google Play Integrity
+```typescript
+import { verifyPlayIntegrity } from '@everystack/security';
+
+const result = await verifyPlayIntegrity({
+  token: integrityToken,
+  packageName: 'com.example.app',
+});
+```
+
+## RS256 Device Keys
+
+Per-device RSA key pairs for request signing:
+
+```typescript
+import { generateDeviceKey, signRequest, verifySignature } from '@everystack/security/crypto';
+
+// Client: generate and store key pair
+const { publicKey, privateKey } = await generateDeviceKey();
+
+// Client: sign requests
+const signature = await signRequest(privateKey, requestBody);
+
+// Server: verify signature
+const valid = await verifySignature(publicKey, requestBody, signature);
+```
+
+## Auth Plugin Integration
+
+```typescript
+import { authPlugin } from '@everystack/auth/plugin';
+
+authPlugin({
+  device: {
+    verify: async (attestation, claims) => {
+      // Verify device attestation
+      return true; // or false to reject
+    },
+    require: 'always', // or 'optional'
+  },
+});
+```
+
+## Schema
+
+```typescript
+import { securitySchema } from '@everystack/security/schema';
+// Adds: device_attestations, device_keys tables
+```
+
+## Client SDK
+
+```typescript
+import { createSecurityClient } from '@everystack/security/client';
+
+const security = createSecurityClient({ baseUrl: '/api/security' });
+await security.registerDevice({ publicKey, attestation });
+```
+
+## Gotchas
+
+- Apple App Attest requires iOS 14+ and a real device (not simulator)
+- Google Play Integrity requires Google Play Services
+- Device keys should be stored in the device's secure enclave/keystore
+- Attestation verification should be done server-side only

package/dist/security.md

@@ -0,0 +1,270 @@
+# everystack Security
+
+Defense-in-depth across three independent layers. Each layer is a complete security boundary. An attacker must bypass all three.
+
+## Three-Layer Model
+
+```
+Request
+  -> Edge (CloudFront)     JWT valid?              -> 401 if invalid
+  -> Handler (Lambda)      SET LOCAL ROLE + inject  -> 401/403
+  -> PostgreSQL (RLS)      GRANT + RLS policies     -> 403 if denied
+```
+
+1. **Edge (CloudFront Functions):** HS256 JWT signature + expiry check. Invalid tokens never reach Lambda. Constant-time comparison prevents timing attacks.
+2. **Handler (Lambda):** JWT verification, `SET LOCAL ROLE` via pgSettings, RPC role gates, rowOwnership, exposedTables/hiddenColumns/protectedFields.
+3. **Database (PostgreSQL):** GRANTs (table-level) + RLS policies (row-level). The single source of truth for authorization. Even if the handler has a bug, the database enforces access.
+
+## AWS IAM Credential Profiles
+
+Three named profiles prevent full account takeover. Configure in `~/.aws/config`:
+
+### everystack-create (infrastructure provisioning)
+```ini
+[profile everystack-create]
+region = us-east-1
+```
+**Permissions:** CloudFormation, RDS, VPC, IAM role creation, Route53, SQS, S3 bucket creation, Lambda function creation.
+**When to use:** Initial `sst deploy` and when adding new infrastructure (new queue, new bucket).
+**DISABLE after initial deployment.** Re-enable temporarily when infrastructure changes are needed. This profile can create IAM roles, which is the most dangerous permission.
+
+### everystack-manage (day-to-day operations)
+```ini
+[profile everystack-manage]
+region = us-east-1
+```
+**Permissions:** Lambda invoke, S3 read/write, CloudWatch logs, SSM parameters, CloudFront KVS.
+**When to use:** All CLI commands: `AWS_PROFILE=everystack-manage everystack db:migrate`, `everystack logs:tail`, `everystack update`, `everystack console`.
+**Cannot** create or destroy infrastructure, modify IAM, or change VPC/RDS configuration.
+
+### everystack-deploy (CI/CD)
+```ini
+[profile everystack-deploy]
+region = us-east-1
+```
+**Permissions:** Lambda update-function-code, CloudFront invalidation, S3 sync (deploy buckets only).
+**When to use:** GitHub Actions deploys. Can push code, cannot change infrastructure shape.
+**Cannot** read secrets, invoke Lambda, or access CloudWatch logs.
+
+### Hard boundary
+None of the three profiles can: modify IAM policies, assume other roles, access other AWS accounts, or create new IAM users/keys.
+
+## Row-Level Security (RLS)
+
+RLS is PostgreSQL's built-in mechanism for restricting which rows a query can see or modify. everystack makes RLS work automatically through pgSettings.
+
+### Mental Model
+
+1. Handler receives JWT, extracts claims (user ID, role)
+2. Handler calls `SET LOCAL ROLE authenticated` inside a transaction
+3. Handler calls `set_config('request.jwt.claims', '{"sub":"user-123","role":"authenticated"}', true)`
+4. PostgreSQL evaluates RLS policies using the role and claims
+5. Transaction ends, role and settings reset (no leakage across requests)
+
+### Role Architecture
+
+```sql
+-- Login role (NOINHERIT -- has no privileges of its own)
+CREATE ROLE authenticator LOGIN NOINHERIT;
+
+-- Application roles (NOLOGIN -- can't connect directly)
+CREATE ROLE anon NOLOGIN;
+CREATE ROLE authenticated NOLOGIN;
+CREATE ROLE admin NOLOGIN;
+
+-- Grant chain: authenticator can become any role via SET LOCAL ROLE
+GRANT anon TO authenticator;
+GRANT authenticated TO authenticator;
+GRANT admin TO authenticator;
+```
+
+Why `NOINHERIT`: authenticator has zero privileges. All access comes through the granted roles. This prevents accidental privilege leakage.
+
+### Table Grants
+
+```sql
+GRANT USAGE ON SCHEMA public TO anon, authenticated, admin;
+
+-- anon: read-only (public data)
+GRANT SELECT ON posts, profiles TO anon;
+
+-- authenticated: read + write (own data, enforced by RLS)
+GRANT SELECT, INSERT, UPDATE, DELETE ON posts, profiles TO authenticated;
+
+-- admin: full access
+GRANT SELECT, INSERT, UPDATE, DELETE ON posts, profiles TO admin;
+```
+
+### Enable RLS
+
+```sql
+ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
+ALTER TABLE posts FORCE ROW LEVEL SECURITY;
+```
+
+`FORCE` ensures RLS applies even to the table owner. Without it, the role that created the table bypasses all policies silently.
+
+### Policy Templates
+
+Copy-paste these patterns. Replace `posts` with your table name and `author_id` with your ownership column.
+
+**Anon read (public data):**
+```sql
+CREATE POLICY posts_select_anon ON posts
+  FOR SELECT TO anon
+  USING (deleted_at IS NULL);
+```
+
+**Authenticated read (all non-deleted):**
+```sql
+CREATE POLICY posts_select_authenticated ON posts
+  FOR SELECT TO authenticated
+  USING (deleted_at IS NULL);
+```
+
+**Authenticated insert (own rows only):**
+```sql
+CREATE POLICY posts_insert_own ON posts
+  FOR INSERT TO authenticated
+  WITH CHECK (
+    author_id = (current_setting('request.jwt.claims', true)::jsonb->>'sub')::uuid
+  );
+```
+
+**Authenticated update (own rows only):**
+```sql
+CREATE POLICY posts_update_own ON posts
+  FOR UPDATE TO authenticated
+  USING (author_id = (current_setting('request.jwt.claims', true)::jsonb->>'sub')::uuid)
+  WITH CHECK (author_id = (current_setting('request.jwt.claims', true)::jsonb->>'sub')::uuid);
+```
+
+**Authenticated delete (own rows only):**
+```sql
+CREATE POLICY posts_delete_own ON posts
+  FOR DELETE TO authenticated
+  USING (author_id = (current_setting('request.jwt.claims', true)::jsonb->>'sub')::uuid);
+```
+
+**Admin full access:**
+```sql
+CREATE POLICY posts_admin ON posts
+  FOR ALL TO admin
+  USING (true)
+  WITH CHECK (true);
+```
+
+The `current_setting('request.jwt.claims', true)::jsonb->>'sub'` pattern reads the JWT payload injected by the handler via pgSettings. The `true` parameter returns NULL instead of raising an error when the setting doesn't exist.
+
+### Handler Configuration for RLS
+
+```typescript
+createHandler(db, schema, {
+  auth: {
+    verifyToken: async (token) => verifyJwt(token),
+    publicRoutes: ['GET'],
+  },
+  pgSettings: (user) => ({
+    role: user?.role === 'admin' ? 'admin' : user ? 'authenticated' : 'anon',
+    'request.jwt.claims': JSON.stringify(user || { role: 'anon' }),
+  }),
+});
+```
+
+The `role` key triggers `SET LOCAL ROLE <value>`. The role name is validated against `^[a-zA-Z_][a-zA-Z0-9_]*$` to prevent injection.
+
+## SECURITY DEFINER vs SECURITY INVOKER
+
+PostgreSQL functions default to SECURITY INVOKER (runs as the current role, RLS applies). SECURITY DEFINER runs as the function owner, bypassing RLS.
+
+**Use SECURITY INVOKER (default)** for read-only functions (list, get, search). RLS policies apply normally.
+
+**Use SECURITY DEFINER** only for mutations needing privilege escalation (stats aggregation, cross-user operations). Always:
+1. `REVOKE EXECUTE FROM PUBLIC` on the function
+2. Set `search_path` explicitly to prevent hijacking
+3. Document why DEFINER is needed
+
+```sql
+CREATE FUNCTION aggregate_stats()
+RETURNS TABLE(total bigint)
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$ SELECT count(*) FROM posts; $$
+LANGUAGE sql;
+
+REVOKE EXECUTE ON FUNCTION aggregate_stats() FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION aggregate_stats() TO admin;
+```
+
+## IDOR Prevention
+
+Two layers working together:
+
+**Handler layer (rowOwnership):**
+```typescript
+rowOwnership: {
+  posts: { column: 'authorId', userField: 'sub' },
+}
+```
+Effect: PATCH and DELETE auto-append `WHERE authorId = user.sub`. Returns 404 if row doesn't belong to user.
+
+**Database layer (RLS):** Policies enforce the same constraint at SQL level. Even if the handler is bypassed (e.g., SSR direct query), the database enforces ownership.
+
+Use both. rowOwnership catches IDOR at HTTP level with clear 404. RLS catches it at SQL level as a safety net.
+
+## Testing Checklist
+
+Before deploying RLS:
+
+```sql
+-- As authenticator (the connection role)
+SET ROLE authenticated;
+SET LOCAL request.jwt.claims = '{"sub":"user-123","role":"authenticated"}';
+
+-- Verify: only user-123's posts visible
+SELECT * FROM posts;
+
+-- Verify: can create own post
+INSERT INTO posts (body, author_id) VALUES ('test', 'user-123');
+
+-- Verify: cannot create post as another user
+INSERT INTO posts (body, author_id) VALUES ('test', 'user-456');  -- should fail
+
+-- Verify: admin sees everything
+SET ROLE admin;
+SELECT * FROM posts;
+
+RESET ROLE;
+```
+
+## Deployment Checklist
+
+### Database
+- [ ] Create `authenticator`, `anon`, `authenticated`, `admin` roles
+- [ ] Grant chain: authenticator can SET ROLE to each
+- [ ] GRANT table-level permissions per role
+- [ ] ENABLE + FORCE ROW LEVEL SECURITY on all public tables
+- [ ] Write RLS policies per table x role
+- [ ] Connect as `authenticator` (never use RDS master/superuser in production)
+- [ ] Test: SET ROLE authenticated; SELECT returns only expected rows
+
+### Handler
+- [ ] `exposedTables` whitelist (404 for unlisted tables)
+- [ ] `hiddenColumns` for password hashes, tokens, internal IDs
+- [ ] `protectedFields` for role, status, admin-only fields
+- [ ] `rowOwnership` scoping writes to authenticated user
+- [ ] `pgSettings` injecting role + request.jwt.claims
+- [ ] `maxEmbedDepth: 3` and `maxLimit: 1000`
+
+### Auth
+- [ ] JWT secret in SST secrets (not in code or env vars)
+- [ ] Access tokens short-lived (15 min for edge, 1h otherwise)
+- [ ] DB-backed refresh tokens with one-time-use rotation
+- [ ] Bcrypt cost >= 10
+
+### Infrastructure
+- [ ] WAF managed rules (exclude SQLi_QUERYARGUMENTS on API paths for PostgREST syntax)
+- [ ] Rate limiting (1000 req/5 min per IP)
+- [ ] CloudFront edge JWT verification for latency-sensitive paths
+- [ ] Database credentials via SST Resource linking
+- [ ] No debug endpoints or env dumps in production

package/dist/ssr.md

@@ -0,0 +1,82 @@
+# Server-Side Rendering
+
+> SSR with direct database access for everystack Expo apps. Import from `@everystack/server/ssr`.
+
+## When to Use
+Read this when building server-rendered pages for SEO, social sharing, or initial load performance.
+
+## Setup
+
+```typescript
+import { getWebHandler } from '@everystack/server/ssr';
+
+const webHandler = getWebHandler({
+  channel: process.env.ENVIRONMENT || 'production',
+  bucket: Resource.Updates.name,
+});
+```
+
+## How SSR Works
+
+1. Browser requests a page (e.g., `/alice`)
+2. Expo Router matches `app/[username]/index.tsx`
+3. The `loader()` function runs server-side
+4. Loader queries database directly via Drizzle (zero network overhead)
+5. Component renders with data, `<Head>` injects OG meta + JSON-LD
+6. HTML sent to browser with full SEO markup
+
+## Loader Pattern
+
+```typescript
+// app/[username]/index.tsx
+export async function loader({ params }) {
+  const profile = await db.query.profiles.findFirst({
+    where: eq(profiles.username, params.username),
+  });
+  const postCount = await db.select({ count: count() }).from(posts)
+    .where(eq(posts.authorId, profile.id));
+
+  return { profile, postCount: Number(postCount[0].count) };
+}
+
+export default function ProfilePage() {
+  const { profile, postCount } = useLoaderData();
+  return (
+    <>
+      <Head>
+        <title>{profile.displayName}</title>
+        <meta property="og:title" content={profile.displayName} />
+      </Head>
+      <ProfileView profile={profile} postCount={postCount} />
+    </>
+  );
+}
+```
+
+## SSR Best Practices
+
+**Do:**
+- Return absolute timestamps from loaders (ISO strings)
+- Use `timeZone: 'UTC'` in `toLocaleDateString()` calls
+- Coerce SQL aggregates to numbers in the loader (`Number(count)`)
+- Use `<Head>` for OG meta and JSON-LD structured data
+
+**Don't:**
+- Render relative time ("5 minutes ago") in loaders (gets cached for days)
+- Use `useEffect(() => fetchData(), [])` when loader data is available
+- Forget `timeZone: 'UTC'` (server and client render different dates)
+
+## Debugging
+
+```bash
+everystack diag https://myapp.com/page --hydration   # Runtime analysis
+everystack analyze:ssr                                 # Static code analysis
+```
+
+## Gotchas
+
+- SSR loaders query the database directly (no HTTP, no auth overhead)
+- SSR responses are cached by CloudFront (check `Cache-Control` headers)
+- Relative time in SSR HTML becomes stale in cache
+- SQL aggregates return strings after JSON round-trip (coerce with `Number()`)
+- Both SSR and API use the same Drizzle schema (add column once, both paths see it)

package/dist/storage.md

@@ -0,0 +1,63 @@
+# File Storage
+
+> S3 file uploads with presigned URLs and CDN delivery. Import from `@everystack/storage`.
+
+## When to Use
+Read this when adding file uploads (V3): profile pictures, attachments, media.
+
+## Setup
+
+```typescript
+import { createStorageHandler } from '@everystack/storage';
+
+const storage = createStorageHandler({
+  bucket: Resource.Media.name,
+  maxSize: 10 * 1024 * 1024, // 10MB
+  allowedTypes: ['image/jpeg', 'image/png', 'image/webp'],
+  auth: { verifyToken: auth.verifyToken },
+  presignedUrlExpiry: 3600, // 1 hour
+});
+```
+
+## Upload Flow
+
+1. Client requests presigned upload URL: `POST /api/storage/upload`
+2. Server generates presigned S3 PUT URL with MIME validation
+3. Client uploads directly to S3 (no Lambda in the upload path)
+4. Client confirms upload: `POST /api/storage/confirm`
+5. Server validates the object exists and records metadata
+
+## Client SDK
+
+```typescript
+import { createStorageClient } from '@everystack/storage/client';
+
+const storage = createStorageClient({ baseUrl: '/api/storage' });
+
+// Upload a file
+const { url, key } = await storage.upload(file, {
+  contentType: 'image/jpeg',
+  metadata: { userId: user.sub },
+});
+```
+
+## CDN Delivery
+
+Files are served via CloudFront. The image handler (`@everystack/images`) can resize on-the-fly:
+```
+/media/photo.jpg?w=400&h=300&fit=cover&fm=webp&q=80
+```
+
+## Plugin
+
+```typescript
+import { storagePlugin } from '@everystack/storage/plugin';
+// Adds upload, confirm, list, delete routes
+```
+
+## Gotchas
+
+- Presigned URLs bypass Lambda (upload goes directly to S3)
+- MIME validation happens both at presign time and on confirm
+- Ownership is enforced: users can only list/delete their own files
+- `auth.verifyToken` must be configured (default-deny without it)

package/dist/testing.md

@@ -0,0 +1,118 @@
+# Testing Patterns
+
+> Jest setup, TDD workflow, and testing conventions for everystack packages.
+
+## When to Use
+Read this when writing tests for everystack apps or packages.
+
+## TDD Workflow
+
+1. Write a failing test that describes expected behavior
+2. Implement the minimum code to make it pass
+3. Refactor while keeping tests green
+4. No features without tests. No tests without features.
+
+## Test Structure
+
+```
+__tests__/
+├── handler/
+│   ├── get.test.ts          # GET endpoint tests
+│   ├── post.test.ts         # POST endpoint tests
+│   ├── filters.test.ts      # Filter operator tests
+│   └── relations.test.ts    # Relation embedding tests
+├── client/
+│   └── client.test.ts       # Client SDK tests
+├── schema.test.ts           # Schema validation tests
+└── integration/
+    └── full-flow.test.ts    # End-to-end tests
+```
+
+Files mirror `src/` structure. Named `{feature}.test.ts`.
+
+## Jest Configuration
+
+Every package extends the base config:
+```javascript
+// jest.config.js
+const { config } = require('../../jest.config.base');
+module.exports = { ...config };
+```
+
+For packages without database needs, override global setup:
+```javascript
+module.exports = {
+  ...config,
+  globalSetup: undefined,
+  globalTeardown: undefined,
+  setupFiles: [],
+};
+```
+
+## Test Patterns
+
+### Handler Tests
+```typescript
+describe('GET /posts', () => {
+  it('returns all posts', async () => {
+    const handler = createHandler(db, schema);
+    const req = new Request('http://localhost/posts');
+    const res = await handler(req);
+    expect(res.status).toBe(200);
+    const data = await res.json();
+    expect(data).toHaveLength(3);
+  });
+
+  it('filters by status', async () => {
+    const req = new Request('http://localhost/posts?status=eq.published');
+    const res = await handler(req);
+    const data = await res.json();
+    expect(data.every((p: any) => p.status === 'published')).toBe(true);
+  });
+});
+```
+
+### Database Integration Tests
+The test framework creates a template database and clones it per test suite for isolation:
+```typescript
+// Tests get a fresh database with schema applied
+// No cleanup needed between tests (each suite gets its own DB)
+```
+
+### Mocking Patterns
+
+**ESM module mocking (required for dynamic imports):**
+```typescript
+jest.unstable_mockModule('@aws-sdk/client-s3', () => ({
+  S3Client: jest.fn(),
+  PutObjectCommand: jest.fn(),
+}));
+```
+
+**Sharp mock (for image processing):**
+```typescript
+jest.unstable_mockModule('sharp', () => ({
+  __esModule: true,
+  default: jest.fn(() => ({
+    resize: jest.fn().mockReturnThis(),
+    toBuffer: jest.fn().mockResolvedValue(Buffer.from('mock')),
+  })),
+}));
+```
+
+## Running Tests
+
+```bash
+pnpm test                                    # All packages (via turbo)
+pnpm --filter @everystack/api test           # Single package
+npx jest __tests__/handler/get.test.ts       # Single file (from package dir)
+npx jest --watch                             # Watch mode
+```
+
+## Gotchas
+
+- Tests require `--experimental-vm-modules` for ESM mocking
+- `jest.unstable_mockModule` + top-level `await` needed for ESM modules
+- Template database requires PostgreSQL 16 running locally or `DATABASE_URL` set
+- `turbo test` has `cache: false` (tests always run, never cached)
+- `sharp` mock needs `__esModule: true` for dynamic `import()` pattern

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@everystack/mcp",
-  "version": "0.2.3",
-  "description": "MCP server that makes Claude an everystack expert",
+  "version": "0.3.0",
+  "description": "Governance layer that governs how any agent builds everystack — grounding, cheat gates, and Model-aware tooling over MCP",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
   "repository": {
@@ -17,6 +17,7 @@
     "access": "public"
   },
   "files": [
+    "dist",
     "src",
     "README.md"
   ],
@@ -27,23 +28,24 @@
     }
   },
   "bin": {
-    "everystack-mcp": "./src/index.ts"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "1.29.0",
-    "zod": "3.25.67"
+    "everystack-mcp": "./dist/index.cjs"
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
     "@types/jest": "29.5.14",
     "@types/node": "22.19.18",
+    "esbuild": "0.25.12",
     "jest": "29.7.0",
     "ts-jest": "29.4.9",
     "tsx": "4.21.0",
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "zod": "3.25.67",
+    "@everystack/cli": "0.3.6",
+    "@everystack/model": "0.3.3"
   },
   "scripts": {
     "test": "jest",
-    "build": "tsc --build",
+    "build": "node scripts/build.mjs",
     "lint": "tsc --noEmit"
   }
 }