ac-framework 2.2.0 → 2.4.0

package/framework/mobile_development/.crush/skills/vibe-security/references/database-security.md

@@ -0,0 +1,151 @@
+# Database Access Control
+
+This is the #1 source of critical vulnerabilities in vibe-coded apps. AI assistants routinely generate database schemas without proper access control, leaving entire tables exposed.
+
+## Supabase Row-Level Security (RLS)
+
+### Enable RLS on Every Table
+
+Tables created via SQL Editor or migrations have RLS **disabled by default**. A table without RLS is fully readable and writable by anyone with the anon key (which is public). Run this in every migration to catch missed tables:
+
+```sql
+DO $$ DECLARE r RECORD;
+BEGIN
+  FOR r IN SELECT tablename FROM pg_tables WHERE schemaname = 'public'
+  LOOP
+    EXECUTE format('ALTER TABLE public.%I ENABLE ROW LEVEL SECURITY;', r.tablename);
+  END LOOP;
+END $$;
+```
+
+### Dangerous RLS Policies
+
+**Never use `USING (true)` or `USING (auth.uid() IS NOT NULL)` on SELECT/UPDATE/DELETE.** These let any authenticated user access every row in the table. Always scope to the row owner:
+
+```sql
+-- BAD: any logged-in user can read all rows
+CREATE POLICY "Users can view data" ON public.documents
+  FOR SELECT TO authenticated USING (true);
+
+-- BAD: any logged-in user can read all rows
+CREATE POLICY "Users can view data" ON public.documents
+  FOR SELECT TO authenticated USING (auth.uid() IS NOT NULL);
+
+-- GOOD: users can only read their own rows
+CREATE POLICY "Users can view own data" ON public.documents
+  FOR SELECT TO authenticated USING ((SELECT auth.uid()) = user_id);
+```
+
+### Missing WITH CHECK
+
+Always include `WITH CHECK` on INSERT and UPDATE policies. Without it, a user can reassign row ownership or insert rows as another user:
+
+```sql
+-- BAD: user can UPDATE user_id to someone else's ID
+CREATE POLICY "Users can update tasks" ON public.tasks
+  FOR UPDATE TO authenticated USING ((SELECT auth.uid()) = user_id);
+
+-- GOOD: WITH CHECK prevents changing user_id
+CREATE POLICY "Users can update tasks" ON public.tasks
+  FOR UPDATE TO authenticated
+  USING ((SELECT auth.uid()) = user_id)
+  WITH CHECK ((SELECT auth.uid()) = user_id);
+```
+
+### Sensitive Fields on User-Accessible Tables
+
+If a `profiles` table lets users UPDATE their own row, they can set `is_admin = true`, `credits = 99999`, or `subscription_tier = 'enterprise'`. Fixes:
+
+- **Option A:** Move sensitive fields to a `private` schema table not exposed via PostgREST. Access them through `SECURITY DEFINER` functions.
+- **Option B:** Use column-level privileges:
+  ```sql
+  REVOKE UPDATE ON profiles FROM authenticated;
+  GRANT UPDATE (display_name, avatar_url) ON profiles TO authenticated;
+  ```
+
+### Forgotten Related Tables
+
+Junction tables, audit logs, and metadata tables often lack RLS even when the main table has it. Every table exposed via the REST API needs its own policies. If a table has RLS enabled but no policies defined, it blocks all access — which is safe but may cause subtle bugs.
+
+### SECURITY DEFINER Functions
+
+`SECURITY DEFINER` functions bypass RLS entirely. If created in the `public` schema, they're callable via the REST API by anyone. Always:
+- Keep them in a `private` schema
+- Set `SET search_path = ''`
+- Validate all inputs inside the function
+
+### Storage Buckets
+
+Storage buckets need their own policies. Without them, any authenticated user can upload, read, or delete any file. Scope uploads to the user's UID folder:
+
+```sql
+CREATE POLICY "Users upload to own folder"
+  ON storage.objects FOR INSERT TO authenticated
+  WITH CHECK (
+    bucket_id = 'avatars'
+    AND (storage.foldername(name))[1] = (SELECT auth.uid())::TEXT
+  );
+```
+
+
+## Firebase Security Rules
+
+### Default Rules Are Dangerous
+
+Never ship these:
+```
+// BAD: world-readable and writable
+allow read, write: if true;
+
+// BAD: any logged-in user can access everything
+allow read, write: if request.auth != null;
+```
+
+Always validate ownership:
+```
+allow read, write: if request.auth.uid == userId;
+```
+
+### Field-Level Protection
+
+Without restricting which fields users can modify, they can set `isAdmin: true` or `credits: 99999`:
+
+```
+// GOOD: restrict modifiable fields on UPDATE
+allow update: if request.auth.uid == userId
+  && request.resource.data.diff(resource.data)
+     .affectedKeys()
+     .hasOnly(['displayName', 'avatarUrl']);
+```
+
+### Subcollection Trap
+
+Subcollections are **NOT** secured by parent rules. Each subcollection needs its own explicit rules. AI assistants frequently miss this.
+
+### Data Validation
+
+Validate data types and sizes on writes:
+```
+allow create: if request.resource.data.displayName is string
+  && request.resource.data.displayName.size() <= 50;
+```
+
+Enforce server timestamps:
+```
+allow create: if request.resource.data.createdAt == request.time;
+```
+
+### Role Checks
+
+Use custom claims (`request.auth.token.role`) instead of querying a users document. Custom claims can't be tampered with by the user and don't require extra reads.
+
+### Cloud Storage Rules
+
+Must validate `contentType`, `size`, and path ownership. Without this, users can upload executables or store files in other users' paths.
+
+
+## Convex
+
+- Every public `query` and `mutation` must call `ctx.auth.getUserIdentity()` and handle the unauthenticated case.
+- Mutations must verify ownership — checking auth is not enough. Verify the user owns the specific resource they're modifying.
+- Functions only called internally must use `internalQuery` / `internalMutation` / `internalAction`, not `query` / `mutation`. Public functions are callable by anyone.

package/framework/mobile_development/.crush/skills/vibe-security/references/deployment.md

@@ -0,0 +1,49 @@
+# Deployment Security
+
+## Production Configuration
+
+- **Disable debug mode** in production. Debug pages often leak stack traces, environment variables, and internal paths.
+- **Disable source maps** in production. Source maps expose your entire source code to anyone who opens DevTools.
+- **Verify `.git` directory is not accessible** in production. If `https://yoursite.com/.git/HEAD` returns content, your entire source code and commit history (including any secrets ever committed) are exposed.
+
+## Environment Separation
+
+Use separate environment variables for each environment in Vercel (or equivalent):
+
+| Environment | Purpose |
+|-------------|---------|
+| Production | Live users, real keys |
+| Preview | PR previews, should use test/staging keys |
+| Development | Local dev, uses local/test keys |
+
+Preview deployments should **never** use production API keys, database credentials, or payment keys. A preview deployment is often accessible to anyone with the URL.
+
+## Security Headers
+
+Set these headers on all responses:
+
+```
+Content-Security-Policy: default-src 'self'; script-src 'self'
+Strict-Transport-Security: max-age=31536000; includeSubDomains
+X-Frame-Options: DENY
+X-Content-Type-Options: nosniff
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: camera=(), microphone=(), geolocation=()
+```
+
+Adjust `Content-Security-Policy` based on your app's needs (e.g., if you use inline styles or load scripts from CDNs), but start restrictive and loosen as needed — not the other way around.
+
+## Pre-Ship Checks
+
+Before deploying:
+- Run `gitleaks detect` on your repo to scan for leaked secrets in git history
+- Verify `.env` files are in `.gitignore`
+- Confirm debug mode / verbose logging is disabled
+- Check that error pages don't leak stack traces
+- Verify CORS is configured to allow only your domains, not `*`
+
+## CORS Configuration
+
+- Never use `Access-Control-Allow-Origin: *` on authenticated endpoints
+- Whitelist only your own domains
+- Be careful with `Access-Control-Allow-Credentials: true` — it must be paired with specific origins, not wildcards

package/framework/mobile_development/.crush/skills/vibe-security/references/mobile.md

@@ -0,0 +1,55 @@
+# Mobile Security (React Native / Expo)
+
+## No Secrets in the JavaScript Bundle
+
+All API keys and secrets in the JavaScript bundle are extractable — even with Hermes bytecode compilation. The bundle is a file on the device that can be read, decompiled, and searched for strings.
+
+- `react-native-config` values are baked into the bundle at build time. They are not secret.
+- `EXPO_PUBLIC_` values are baked into the bundle at build time. They are not secret.
+- Environment variables set via `eas.json` or `app.config.js` that end up in the JS bundle are not secret.
+
+The only safe approach: **use a backend proxy** for all third-party API calls that require secret keys. The mobile app calls your server; your server calls the third-party API with the key.
+
+```typescript
+// BAD: API key in the mobile app
+const response = await fetch('https://api.openai.com/v1/chat/completions', {
+  headers: { 'Authorization': `Bearer ${OPENAI_API_KEY}` }
+});
+
+// GOOD: call your own backend, which holds the key
+const response = await fetch('https://your-api.com/ai/chat', {
+  headers: { 'Authorization': `Bearer ${userSessionToken}` },
+  body: JSON.stringify({ message: userInput }),
+});
+```
+
+## Secure Token Storage
+
+- **Use `expo-secure-store`** (Expo) or **`react-native-keychain`** (bare React Native) for auth tokens.
+- **Never use `AsyncStorage`** — it's unencrypted plaintext on disk. On a rooted/jailbroken device, tokens are trivially readable.
+
+```typescript
+// BAD: plaintext on disk
+await AsyncStorage.setItem('authToken', token);
+
+// GOOD: encrypted in device keychain
+await SecureStore.setItemAsync('authToken', token);
+```
+
+## Deep Link Security
+
+Deep links (`myapp://path?param=value`) can be triggered by any app or website. They are an attack surface:
+
+- **Validate and sanitize all parameters.** Never trust deep link input.
+- **Never include sensitive data in deep link URLs** (tokens, passwords, user IDs that grant access).
+- **Don't perform destructive actions** directly from deep link parameters without user confirmation.
+
+## Biometric Authentication
+
+A simple boolean success check from biometric auth (`isAuthenticated = true`) can be hooked with tools like Frida on a jailbroken device. Proper biometric auth must use **cryptographic verification**:
+
+1. Server sends a challenge (random nonce)
+2. App signs the challenge with a hardware-backed key (Secure Enclave / Strongbox)
+3. Server verifies the signature
+
+This way, even if the biometric check is bypassed, the attacker can't forge the cryptographic signature.

package/framework/mobile_development/.crush/skills/vibe-security/references/payments.md

@@ -0,0 +1,63 @@
+# Payment Security (Stripe)
+
+## Never Trust Client-Submitted Prices
+
+The #1 payment vulnerability in vibe-coded apps: the price comes from the client. An attacker can set any amount, including $0.
+
+```typescript
+// BAD: price comes from the request body
+const session = await stripe.checkout.sessions.create({
+  line_items: [{
+    price_data: {
+      currency: 'usd',
+      unit_amount: req.body.price, // attacker controls this
+      product_data: { name: req.body.name },
+    },
+    quantity: 1,
+  }],
+});
+
+// GOOD: look up the price server-side
+const product = await db.products.findUnique({ where: { id: req.body.productId } });
+if (!product) return new Response('Not found', { status: 404 });
+
+const session = await stripe.checkout.sessions.create({
+  line_items: [{ price: product.stripePriceId, quantity: 1 }],
+});
+```
+
+Use Stripe Price IDs (created via the Stripe dashboard or API) rather than constructing prices from your database. This way, prices are defined in Stripe and can't be manipulated.
+
+## Webhook Signature Verification
+
+Stripe webhooks must have their signatures verified. This requires the **raw request body** — parsing the body as JSON first destroys the signature.
+
+```typescript
+// Express: webhook route MUST use express.raw() BEFORE express.json()
+app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+  const sig = req.headers['stripe-signature'];
+  const event = stripe.webhooks.constructEvent(req.body, sig, webhookSecret);
+  // ... handle event
+});
+
+// Next.js App Router: use request.text(), NOT request.json()
+export async function POST(request: Request) {
+  const body = await request.text();
+  const sig = request.headers.get('stripe-signature')!;
+  const event = stripe.webhooks.constructEvent(body, sig, webhookSecret);
+  // ... handle event
+}
+```
+
+## Subscription Status Validation
+
+Check subscription status **server-side on every protected request** using your database (kept in sync via webhooks). Do not rely on:
+- A cached session value from login time
+- A client-side flag
+- A JWT claim that was set at token creation and never refreshed
+
+Subscriptions can be cancelled, expire, or change tier at any time. Your database (updated via webhooks) is the source of truth.
+
+## Checkout Session Metadata
+
+Validate that checkout session metadata (user ID, plan, etc.) was set **server-side** when creating the session, not passed from the client. If metadata comes from the client, an attacker can claim to be a different user or select a different plan.

package/framework/mobile_development/.crush/skills/vibe-security/references/rate-limiting.md

@@ -0,0 +1,55 @@
+# Rate Limiting & Abuse Prevention
+
+## Where Rate Limiting Is Required
+
+Every one of these endpoints needs rate limiting. AI assistants almost never add it:
+
+- **Auth endpoints** — login, register, password reset, OTP verification, magic link. Without limits, attackers can brute-force passwords or enumerate accounts.
+- **AI API calls** — Any endpoint that calls OpenAI, Anthropic, or similar. A single user can drain your entire monthly budget in minutes.
+- **Email / SMS sending** — Attackers can use your app as a spam relay.
+- **File processing** — Upload, resize, convert. CPU-intensive operations without limits enable denial-of-service.
+- **Webhook-like endpoints** — Anything accepting external input at scale.
+
+## Don't Store Rate Limits in Public Tables
+
+If rate limit counters live in a Supabase public table, users can reset their own counters via the REST API. Use:
+
+- **Upstash Redis** — Serverless Redis with built-in rate limiting primitives
+- **Private schema table** — Not exposed via PostgREST
+- **Middleware-level limiting** — At the edge or API gateway
+- **In-memory stores** — For single-server deployments (Redis for multi-server)
+
+## Combine Per-IP and Per-User Limiting
+
+- IP-only limits are defeated by rotating IPs (trivial with VPNs or botnets)
+- User-only limits are defeated by creating new accounts
+- Use both together for effective protection
+
+## Billing Protection
+
+- Set billing alerts on every cloud provider (AWS, GCP, Vercel, etc.)
+- Set **hard spending caps** on AI API providers (OpenAI, Anthropic)
+- Use per-user usage quotas with hard limits, not just soft warnings
+- Monitor for anomalous usage patterns (sudden spikes, requests at odd hours)
+
+## Implementation Pattern
+
+```typescript
+// Example: rate limiting with Upstash Redis
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, '1 m'), // 10 requests per minute
+});
+
+export async function POST(request: Request) {
+  const ip = request.headers.get('x-forwarded-for') ?? '127.0.0.1';
+  const { success } = await ratelimit.limit(ip);
+  if (!success) {
+    return new Response('Too many requests', { status: 429 });
+  }
+  // ... handle request
+}
+```

package/framework/mobile_development/.crush/skills/vibe-security/references/secrets-and-env.md

@@ -0,0 +1,47 @@
+# Secrets & Environment Variables
+
+## Hardcoded Credentials
+
+Never hardcode API keys, tokens, passwords, or credentials in source code. This includes:
+- Strings that look like API keys in source files
+- Connection strings with embedded passwords
+- Private keys or certificates in the repo
+
+If a secret was ever committed to Git history, consider it compromised — deleting the file doesn't remove it from history. The key must be rotated immediately. Run `gitleaks detect` to scan for leaked secrets.
+
+## Client-Side Environment Variable Prefixes
+
+These prefixes cause env vars to be inlined into the client bundle at build time. Everything in the bundle is visible to anyone:
+
+| Framework | Client Prefix | Danger |
+|-----------|--------------|--------|
+| Next.js | `NEXT_PUBLIC_` | Inlined into browser JS at build time |
+| Vite | `VITE_` | Inlined into browser JS at build time |
+| Expo / React Native | `EXPO_PUBLIC_` | Baked into the app bundle |
+| Create React App | `REACT_APP_` | Inlined into browser JS at build time |
+
+**What belongs client-side:**
+- Stripe publishable key (`pk_live_*`, `pk_test_*`)
+- Supabase anon key
+- Firebase client config (apiKey, authDomain, projectId)
+- Public analytics IDs
+
+**What must NEVER be client-side:**
+- Supabase `service_role` key (bypasses all RLS)
+- Stripe secret key (`sk_live_*`, `sk_test_*`)
+- Any database connection string
+- Any third-party API secret key
+- JWT signing secrets
+- OAuth client secrets
+
+## .gitignore
+
+Ensure `.env`, `.env.local`, `.env.*.local`, and any file containing secrets is in `.gitignore` **before the first commit**. Check that `.env.example` or `.env.sample` files contain only placeholder values, not real keys.
+
+## Detection Tips
+
+When auditing, search for:
+- Files named `.env` that are tracked by git (`git ls-files | grep .env`)
+- Strings matching common key patterns: `sk_live_`, `sk_test_`, `AKIA`, `ghp_`, `glpat-`, `xoxb-`, `Bearer `
+- `process.env.NEXT_PUBLIC_` or `import.meta.env.VITE_` referencing anything with "secret", "private", "service", or "key" in the name
+- Hardcoded URLs containing credentials (e.g., `postgresql://user:password@host`)

package/framework/mobile_development/.cursor/commands/ac-lite.md

@@ -43,6 +43,57 @@ acfm memory stats
 
 ---
 
+
+## SynapseGrid Collaboration Protocol (Optional but Recommended for Complex Tasks)
+
+Use SynapseGrid when a task benefits from role-based collaboration and explicit review loops.
+
+**Delegate to SynapseGrid when:**
+- Scope spans planning + implementation + review
+- Risk is medium/high (security, migrations, API contract changes)
+- You need auditable outputs (transcript, meeting summary, artifacts)
+- A single-pass implementation is likely to miss edge cases
+
+**Role delegation map:**
+- `planner` -> plan/constraints/acceptance criteria
+- `critic` -> risk analysis and challenge assumptions
+- `coder` -> implementation and concrete edits
+- `reviewer` -> final verification and readiness checks
+
+**Preferred MCP flow:**
+1. `collab_start_session`
+2. `collab_invoke_team`
+3. `collab_wait_run`
+4. `collab_get_result`
+5. Optional: `collab_get_transcript`, `collab_get_meeting_log`, `collab_status`
+
+**CLI fallback:**
+```bash
+acfm agents setup
+acfm agents runtime set auto
+acfm agents doctor --verbose
+acfm agents start --task "..." --mux auto
+acfm agents transcript --role all --limit 80
+acfm agents summary
+acfm agents artifacts --watch --interval 1200
+```
+
+**Model and runtime controls:**
+```bash
+acfm agents model list
+acfm agents model choose
+acfm agents runtime get
+acfm agents runtime install-zellij
+```
+
+**Artifacts to inspect:**
+- `~/.acfm/synapsegrid/<sessionId>/meeting-log.md`
+- `~/.acfm/synapsegrid/<sessionId>/meeting-summary.md`
+- `~/.acfm/synapsegrid/<sessionId>/turns/raw/*.ndjson`
+
+**Lite rule:** delegate only when collaboration adds value; otherwise continue with normal `ac-lite` flow.
+
+
 ## Conditional Skill Gates
 
 ### Platform/Stack Gate
@@ -57,6 +108,9 @@ Load based on selected implementation stack:
 - `mobile-ios-design` [IF iOS UI changes]
 - `mobile-android-design` [IF Android UI changes]
 
+### Security Gate
+- `vibe-security` [MANDATORY final audit before closure]
+
 ### Clarity/Scale Gate
 - `spec-clarification` [IF requirements ambiguous]
 - `spec-analysis` [IF cross-artifact consistency needs verification]
@@ -87,7 +141,8 @@ Before `openspec-apply-change`, all must be true:
 ### Gate B: Ready to Close
 Before `openspec-archive-change`, all must be true:
 - `openspec-verify-change` completed
-- Critical issues resolved (or explicitly accepted with warning)
+- `vibe-security` executed as final security validation
+- No unresolved CRITICAL/HIGH findings remain (or explicitly accepted with warning)
 - Task list reflects final state
 - Reusable context saved to memory
 - `documentation` / `sync-index` / changelog steps executed as required
@@ -105,8 +160,9 @@ Before `openspec-archive-change`, all must be true:
 6. Pass Gate A.
 7. Implement (`openspec-apply-change`).
 8. Verify (`openspec-verify-change`).
-9. Pass Gate B.
-10. Archive/sync and generate closure docs.
+9. Run `vibe-security` for final security audit and remediate findings.
+10. Pass Gate B.
+11. Archive/sync and generate closure docs.
 
 ### Existing Mobile Change
 1. Confirm initialization and target change.
@@ -116,8 +172,9 @@ Before `openspec-archive-change`, all must be true:
 5. Pass Gate A.
 6. Implement and debug as needed.
 7. Verify.
-8. Pass Gate B.
-9. Archive/sync.
+8. Run `vibe-security` for final security audit and remediate findings.
+9. Pass Gate B.
+10. Archive/sync.
 
 ---