feat(api): add SpiceDB authorization, member filters, and infra

- Add SpiceDB schema with hierarchical role-based permissions
  (외부인 < 비기너 < 레귤러 < 교육장 < 트랙장 < 부회장/회장 < 멘토)
- Add authz client wrapper (check, add/remove relation)
- Add docker-compose.yml (SpiceDB + API services)
- Add GET /v1/members/filters (tracks, statuses, payment_statuses)
- Add Forbidden (403) exception
- Auto-load SpiceDB schema on app startup

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ImTotem

.env.example

@@ -16,3 +16,7 @@ RESEND_SENDER=onboarding@resend.dev
 
 # CORS (쉼표로 여러 origin 구분)
 CORS_ORIGINS=http://localhost:3000
+
+# SpiceDB (권한 관리)
+SPICEDB_ENDPOINT=localhost:50051
+SPICEDB_TOKEN=bcsd-dev-token

docker-compose.yml

@@ -0,0 +1,26 @@
+services:
+  spicedb:
+    image: authzed/spicedb:latest
+    command: serve
+    ports:
+      - "50051:50051"   # gRPC
+      - "8443:8443"     # HTTP gateway
+      - "9090:9090"     # metrics
+    environment:
+      SPICEDB_GRPC_PRESHARED_KEY: "${SPICEDB_TOKEN:-bcsd-dev-token}"
+      SPICEDB_DATASTORE_ENGINE: memory
+    healthcheck:
+      test: ["CMD", "grpc_health_probe", "-addr=localhost:50051"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  api:
+    build: .
+    ports:
+      - "8000:8000"
+    env_file:
+      - .env
+    depends_on:
+      spicedb:
+        condition: service_healthy

pyproject.toml

@@ -16,6 +16,7 @@ dependencies = [
     "python-jose[cryptography]>=3.3.0",
 
     "resend>=2.0.0",
+    "authzed>=1.0.0",
 ]
 
 [project.optional-dependencies]

spicedb/schema.zed

@@ -0,0 +1,79 @@
+/**
+ * BCSDLab 권한 관리 스키마
+ *
+ * 계층 구조 (아래에서 위로 권한 누적):
+ * 외부인 < 비기너 < 레귤러 < 교육장 < 트랙장 < 부회장/회장 < 멘토
+ *
+ * 한 사용자가 여러 역할을 가질 수 있음 (예: 레귤러 + 트랙장)
+ */
+
+definition user {}
+
+definition track {
+    relation leader: user
+    relation member: user
+
+    permission manage = leader
+    permission view = leader + member
+}
+
+definition organization {
+    /** 역할 관계 (낮은 → 높은) */
+    relation outsider: user
+    relation beginner: user
+    relation regular: user
+    relation educator: user
+    relation track_leader: user
+    relation vice_president: user
+    relation president: user
+    relation mentor: user
+
+    /** 계층 누적 권한 */
+    permission member_view = beginner + regular + educator + track_leader + vice_president + president + mentor
+    permission member_edit = regular + educator + track_leader + vice_president + president + mentor
+    permission fee_view = educator + track_leader + vice_president + president + mentor
+    permission fee_edit = vice_president + president + mentor
+    permission group_manage = vice_president + president + mentor
+    permission admin = president + mentor
+    permission full_control = mentor
+}
+
+definition member {
+    relation owner: user
+    relation organization: organization
+    relation track: track
+
+    permission view = owner + organization->member_view
+    permission edit = owner + organization->member_edit + track->leader
+    permission delete = organization->admin
+}
+
+definition fee {
+    relation organization: organization
+    relation payer: user
+
+    permission view = payer + organization->fee_view
+    permission edit = organization->fee_edit
+    permission delete = organization->admin
+}
+
+definition group {
+    relation organization: organization
+    relation leader: user
+    relation member: user
+
+    permission view = leader + member + organization->member_view
+    permission edit = leader + organization->group_manage
+    permission delete = organization->admin
+    permission manage = leader + organization->group_manage
+}
+
+definition event {
+    relation organization: organization
+    relation organizer: user
+    relation attendee: user
+
+    permission view = organizer + attendee + organization->member_view
+    permission edit = organizer + organization->group_manage
+    permission delete = organization->admin
+}

src/bcsd_api/authz/__init__.py

@@ -0,0 +1,3 @@
+from .client import AuthzClient
+
+__all__ = ["AuthzClient"]

src/bcsd_api/authz/client.py

@@ -0,0 +1,71 @@
+from authzed.api.v1 import (
+    CheckPermissionRequest,
+    CheckPermissionResponse,
+    Client,
+    ObjectReference,
+    Relationship,
+    RelationshipUpdate,
+    SubjectReference,
+    WriteRelationshipsRequest,
+    WriteSchemaRequest,
+)
+from grpcutil import insecure_bearer_token_credentials
+
+_TOUCH = RelationshipUpdate.Operation.OPERATION_TOUCH
+_DELETE = RelationshipUpdate.Operation.OPERATION_DELETE
+_HAS = CheckPermissionResponse.PERMISSIONSHIP_HAS_PERMISSION
+
+
+def _object_ref(obj_type: str, obj_id: str) -> ObjectReference:
+    return ObjectReference(object_type=obj_type, object_id=obj_id)
+
+
+def _subject_ref(user_id: str) -> SubjectReference:
+    return SubjectReference(object=_object_ref("user", user_id))
+
+
+def _relationship(res_type: str, res_id: str, relation: str, user_id: str) -> Relationship:
+    return Relationship(
+        resource=_object_ref(res_type, res_id),
+        relation=relation,
+        subject=_subject_ref(user_id),
+    )
+
+
+def _update(operation, res_type: str, res_id: str, relation: str, user_id: str) -> RelationshipUpdate:
+    return RelationshipUpdate(
+        operation=operation,
+        relationship=_relationship(res_type, res_id, relation, user_id),
+    )
+
+
+class AuthzClient:
+    def __init__(self, endpoint: str, token: str):
+        self._client = Client(
+            endpoint,
+            insecure_bearer_token_credentials(token),
+        )
+
+    def check(self, res_type: str, res_id: str, permission: str, user_id: str) -> bool:
+        resp = self._client.CheckPermission(
+            CheckPermissionRequest(
+                resource=_object_ref(res_type, res_id),
+                permission=permission,
+                subject=_subject_ref(user_id),
+            )
+        )
+        return resp.permissionship == _HAS
+
+    def add_relation(self, res_type: str, res_id: str, relation: str, user_id: str) -> None:
+        self._write(_TOUCH, res_type, res_id, relation, user_id)
+
+    def remove_relation(self, res_type: str, res_id: str, relation: str, user_id: str) -> None:
+        self._write(_DELETE, res_type, res_id, relation, user_id)
+
+    def write_schema(self, schema: str) -> None:
+        self._client.WriteSchema(WriteSchemaRequest(schema=schema))
+
+    def _write(self, operation: int, res_type: str, res_id: str, relation: str, user_id: str) -> None:
+        self._client.WriteRelationships(
+            WriteRelationshipsRequest(updates=[_update(operation, res_type, res_id, relation, user_id)])
+        )

src/bcsd_api/config.py

@@ -13,4 +13,6 @@ class Settings(BaseSettings):
     cors_origins: str = "http://localhost:3000"
     cookie_name: str = "access_token"
     cookie_secure: bool = False
+    spicedb_endpoint: str = "localhost:50051"
+    spicedb_token: str = "bcsd-dev-token"
     model_config = {"env_file": ".env"}

src/bcsd_api/dependencies.py

@@ -3,6 +3,7 @@
 from fastapi import Depends, Request
 
 from .auth import token as jwt_token
+from .authz.client import AuthzClient
 from .config import Settings
 from .email import ResendSender
 from .email.sender import EmailSender
@@ -40,6 +41,17 @@ def get_email_sender(settings: Settings = Depends(get_settings)) -> EmailSender:
     return _sender_cache
 
 
+_authz_cache: AuthzClient | None = None
+
+
+def get_authz(settings: Settings = Depends(get_settings)) -> AuthzClient:
+    global _authz_cache
+    if _authz_cache:
+        return _authz_cache
+    _authz_cache = AuthzClient(settings.spicedb_endpoint, settings.spicedb_token)
+    return _authz_cache
+
+
 def get_member_repo(sheets: SheetsClient = Depends(get_sheets)) -> MemberRepository:
     return MemberRepository(sheets)
 

src/bcsd_api/exception/__init__.py

@@ -1,11 +1,12 @@
 from .base import AppException
-from .errors import BadRequest, Conflict, NotFound, Unauthorized
+from .errors import BadRequest, Conflict, Forbidden, NotFound, Unauthorized
 from .handlers import register_handlers
 
 __all__ = [
     "AppException",
     "BadRequest",
     "Conflict",
+    "Forbidden",
     "NotFound",
     "Unauthorized",
     "register_handlers",

src/bcsd_api/exception/errors.py

@@ -23,3 +23,9 @@ class BadRequest(AppException):
     status_code = 400
     error_code = "BAD_REQUEST"
     message = "bad request"
+
+
+class Forbidden(AppException):
+    status_code = 403
+    error_code = "FORBIDDEN"
+    message = "permission denied"