# Scoped API Permissions & Architecture (SmochAlai / סמוך עליי)

**Platform**: סמוך עליי (SmochAlai / TrustMe, formerly Vybio וייביו)  
**Standard**: RFC 9728 (OAuth 2.0 Protected Resource Metadata) & OpenAPI 3.1  
**Base URL**: `https://smochalai.netlify.app`  
**API Endpoint**: `https://api.smochalai.netlify.app`  

---

## Machine-Readable Specifications
- **RFC 9728 Metadata**: [/.well-known/oauth-protected-resource](https://smochalai.netlify.app/.well-known/oauth-protected-resource)
- **OpenAPI 3.1 (JSON)**: [/openapi.json](https://smochalai.netlify.app/openapi.json)
- **OpenAPI 3.1 (YAML)**: [/openapi.yaml](https://smochalai.netlify.app/openapi.yaml)

---

## Declared Scopes (Least-Privilege Model)

| Scope ID | Name | Description | Enforcement Level |
| :--- | :--- | :--- | :--- |
| `profile:read` | Profile Read | Read public and contact-shared user profiles | PostgreSQL RLS |
| `profile:write` | Profile Write | Update profile details, handle (@handle), bio, and links | Edge / Stored Procedure |
| `recommendations:read` | Recommendations Read | Read living stack items curated by trusted contacts | PostgreSQL RLS |
| `recommendations:write` | Recommendations Write | Create living stack recommendations in 8 core categories | PostgreSQL RLS & Triggers |
| `recommendations:delete` | Recommendations Delete | Remove recommendations owned by authenticated user | PostgreSQL RLS |
| `contacts:match` | Contact Graph Match | Match privacy-preserving SHA-256 phone hashes | Zero-Knowledge RPC |
| `ai:extract` | AI Copilot Extract | Natural language blueprint extraction (10 req/min limit) | Edge JWT + Sliding Window Rate Limiter |
| `link:unfurl` | Link Preview Unfurl | Extract OpenGraph metadata with SSRF & HTTPS validation | Edge Function Guard |

---

## Zero-Trust Guardrails
1. **Bearer Authentication**: All requests require `Authorization: Bearer <token>` carrying machine-readable scope claims.
2. **Strict RLS**: Mutating actions verify `auth.uid() = user_id`.
3. **Sliding-Window Rate Limiting**: AI endpoints enforce 10 requests per minute per user ID.
4. **HTTPS Enforced**: Non-HTTPS URLs are rejected at the database and gateway levels.