Veritabanı erişimi ve ajan izolasyonu

Münderecat veritabanı erişimini iki ayrı unsurla sınırlar:

1. Login olmayan PostgreSQL capability rolleri ne yapılabileceğini belirler.
2. Her write-capable packet ayrı Supabase projesi, Docker ağı, port seti, disposable login ve credential dosyası kullanır.

Bu yapı ayrı database adlarının paylaşılan tek cluster içinde kullanılmasını izolasyon saymaz. Aynı mutable geliştirme veritabanında paralel DDL/DML yoktur.

Rol modeli

Canonical rol sözleşmesi config/db-access-policy.yml, uygulanabilir SQL ise db/supabase/migrations/20260818090000_f1_031_database_roles.sql dosyasıdır.

Rol	Kullanım	Temel sınır
legacy_reader	Legacy extraction	Read-only transaction, mevcut public table ve sequence için SELECT
agent_local_owner	Tek packet disposable DB	Yalnız o stack içinde ownership ve migration yazımı
ci_migrator	Ephemeral CI/staging migration	Public schema DDL; production yetkisi yok
app_runtime	Uygulama runtime	Schema usage; table/RPC grantleri yalnız explicit migration ile
curation_executor	Kontrollü curation	Direct DML yok; yalnız explicit approved procedure execute
prod_migrator	Korumalı deploy job	Short-lived dış credential; repository bunu üretmez
auditor	Release/audit	Read-only transaction ve mevcut public nesnelerde SELECT
break_glass_owner	İnsan incident müdahalesi	Login, BYPASSRLS veya kullanılabilir membership yok; aktivasyon bu repo dışında iki onaylıdır

Capability rollerinin hiçbiri login olamaz. PostgreSQL 17’nin non-superuser role creator için zorunlu tuttuğu administrative kayıt SET FALSE, INHERIT FALSE kalır; canlı kapı kullanılabilir veya creator dışı üyeliği reddeder. PUBLIC için database TEMPORARY, public schema CREATE ve public routine EXECUTE kaldırılır. Migration owner rollerinin yeni table, sequence, routine ve type nesneleri de otomatik runtime yetkisi dağıtmaz. Uygulama tablosu veya RPC eklendiğinde gerekli grant aynı schema migration’ında açıkça yazılır.

Politikayı veritabanı açmadan doğrulamak için:

make db-role-contract-check

Çalışan canonical local stack’in gerçek pg_roles ve ACL snapshot’ını karşılaştırmak için:

make db-role-live-check

make db-migration-check, reset sonrasında bu canlı karşılaştırmayı otomatik çalıştırır.

Destructive komut sınırı

Repository’nin tek destructive veritabanı giriş noktası make db-resettir ve yalnız canonical local Supabase stack’ini yeniden kurabilir. Target, komutu scripts/db/destructive_command_guard.rb üzerinden çalıştırır. Guard child process başlamadan önce şu değerlerin tamamını exact olarak doğrular:

• environment sınıfı local;
• project ve network kimliği munderecat-local;
• API ve PostgreSQL container adları canonical local adlar;
• guard içinde sabit argv değeri corepack pnpm exec supabase --workdir db db reset --local.

production, staging, linked project, --project-ref, database URL, eksik --local, ek argüman ve Make variable override’ları yürütülebilir komuta dönüşemez. Make target’ında caller-controlled komut parçası yoktur; guard positional komut girdisini reddeder ve sabit argv’yi repository kökünden doğrudan exec eder. Guard credential veya URL kabul etmez ve shell çalıştırmaz. Bu sınır table-level immutable trigger ve rol ACL’lerinin yerine geçmez; repository komutunun uzak bir hedefe yönelmesini engelleyen ayrı katmandır. Dışarıdaki break-glass insan operasyonu bu CLI sözleşmesinin kapsamı değildir.

Sözleşmeyi Docker veya reset çalıştırmadan doğrulamak için:

make destructive-command-policy-check

Canonical local stack

make db-start
make db-status
make db-stop

db-start, Supabase project label’ına sahip bütün container’ları keşfeder, yayınlanan bütün portları structured Docker inspect çıktısından denetler ve host’un loopback dışı IPv4/IPv6 adreslerinden gerçek TCP erişimini de yoklar. API ve PostgreSQL container’larında beklenen container/host port eşlemesi de birebir doğrulanır. Herhangi bir wildcard/non-loopback ya da beklenmeyen port yayını görülürse stack --no-backup ile durdurulur, ağı kaldırılır ve komut hata verir. Bu durumda veri yüklemeyin; uyarıyı bypass eden destekli bir komut yoktur.

Docker Desktop’ın bridge host_binding_ipv4 seçeneğini yok saydığı sürümlerde bu fail-closed sonuç beklenir. Linux Docker Engine üzerinde binding gerçekten 127.0.0.1 ise aynı komut normal çalışır.

Packet veritabanı

Gerçek provisioning için packet’ın şu şartları birlikte sağlaması gerekir:

• db_access: isolated_local, aktif ve süresi geçmemiş lease,
• komutun kayıtlı packet worktree/branch’i içinde çalışması,
• MUNDERECAT_ACTOR_ID değerinin lease holder ile aynı olması,
• F1-033 tarafından Git common metadata alanına yazılmış, main commit ve certificate hashine bağlı trusted readiness receipt,
• boş ve packet’a özgü port seti,
• loopback-only canlı exposure kontrolü.

F1-033 readiness certificate tamamlanana kadar provisioning komutu Docker’a ulaşmadan write_agent_readiness_missing ile durur. Bu, bootstrap sole-writer istisnasının yanlışlıkla erken açılmasını önler.

Yerel işletim sistemi hesabı ve dosya izinleri operator güven sınırıdır. MUNDERECAT_ACTOR_ID kriptografik kimlik doğrulama değil, lease/audit kimliğidir. Başlatma ayrıca operator’e ait repo/Git metadata yollarını, korumalı trusted receipt’i ve kayıtlı worktree/lease’i doğrular. Güvenilmeyen çok kullanıcılı veya uzak ajan çalıştırma bu yerel bootstrap mekanizmasının kapsamında değildir.

Readiness sonrasında kayıtlı worktree içinde:

MUNDERECAT_PACKET_ID=F2-001-W01 \
MUNDERECAT_ACTOR_ID=<lease-holder-id> \
make db-agent-start

Başarılı çıktı password veya database URL yazmaz; yalnız credential dosyasının Git common metadata altındaki yolunu bildirir. Dosya mode 0600 ile en son adımda yaratılır. Her packet farklı project ID, network, üçlü port aralığı, 64-hex password ve actual database owner login alır.

Secret içermeyen durum ve geri dönüşsüz disposable cleanup:

MUNDERECAT_PACKET_ID=F2-001-W01 MUNDERECAT_ACTOR_ID=<actor-id> make db-agent-status
MUNDERECAT_PACKET_ID=F2-001-W01 MUNDERECAT_ACTOR_ID=<actor-id> make db-agent-destroy

destroy, Supabase’i --no-backup ile durdurur; network, workspace, state ve credential dosyasını kaldırır. Stop veya network cleanup başarısızsa dosyaları silmez ve cleanup_required durumunu korur; böylece çalışan bir stack izsiz bırakılmaz.

Sorun giderme

• worktree_gate_failed: packet/branch/lease kaydını make worktree-check ile doğrulayın.
• lease_is_stale: yeni lease epoch gerekir; eski credential yeniden kullanılmaz.
• port_unavailable: aynı packet için yarım kalmış stack’i db-agent-status ile kontrol edin; başka süreç portu tutuyorsa çakışmayı kaldırın.
• exposure_gate_failed: stack otomatik kaldırılmıştır. cleanup_failed de varsa state’i koruyup container ve network’ü inceleyin.
• packet_database_state_exists: var olan state çözülmeden ikinci credential üretilmez.

Legacy supabase_db_sql_ref_only bu komutların project, network veya cleanup kapsamına girmez.