@kavtuai/guildgate 0.1.0

package/docs/custom-stores.md

@@ -0,0 +1,111 @@
+# Custom storage drivers
+
+GuildGate does not select a database. Implement the interfaces in `GuildGateStores` and pass them to `createGuildGate()`.
+
+## Record placement
+
+A common production layout is:
+
+| Record | Suggested storage | Reason |
+|---|---|---|
+| Sessions | Redis or a database with expiry cleanup | Fast lookup and revocation |
+| OAuth state | Redis or an atomic database record | Single-use consume operation |
+| OAuth credentials | Durable database | Encrypted refresh tokens must survive restarts |
+| Rate limits | Redis or another atomic counter store | Shared limits across instances |
+| Cache | Redis or application cache | Shared invalidation |
+| Idempotency | Redis or durable database | Atomic first-writer ownership |
+| Locks | Redis, database advisory locks, or lease service | Shared resource exclusion |
+| Audit | Durable append-oriented database | Search, retention, incident review |
+| Outbox | Same database as the domain write when possible | Commit and delivery coordination |
+| Policies | Durable database | Maintenance and block state survives restart |
+
+This is a deployment suggestion, not a package requirement.
+
+## Required semantics
+
+### SessionStore
+
+`set()` must replace the complete record. `listByUser()` must return active and revoked records still present in storage. The session manager removes expired records and enforces the per-user cap.
+
+Do not store the raw session token. The core sends only `idHash` to the store.
+
+### OAuthStateStore
+
+`consume(stateHash, nowIso)` must read and delete in one atomic operation. Two callbacks using the same state must not both succeed.
+
+### OAuthCredentialStore
+
+Store only ciphertext produced by `TokenCipher`. Restrict direct database access because a stolen encryption key and copied ciphertext together expose Discord credentials.
+
+### RateLimitStore
+
+`hit()` must atomically decide whether the cost fits within the current window. It returns the limit, remaining count, reset time, and retry delay.
+
+A read followed by a write without a transaction is not sufficient for multiple instances.
+
+### CacheStore
+
+`deleteByTags()` must delete entries matching any requested tag. It may return an approximate count if the backing cache expires index entries independently, but it must not leave known matching entries intentionally.
+
+### IdempotencyStore
+
+`begin()` is a first-writer operation:
+
+- No record: write `inflight` and return `started`.
+- Same key and same request hash, still inflight: return `inflight`.
+- Same key and same request hash, completed: return the stored response.
+- Same key and different request hash: return `conflict`.
+
+`complete()` must preserve the original request hash and store the result. `fail()` removes an abandoned reservation so a later retry can run.
+
+### LockStore
+
+`acquire()` writes a lease only when no valid lease exists. `release()` must compare the token before deleting the lease. Deleting a lock by key alone can release a newer owner’s lock.
+
+Long operations should renew leases or use a driver whose transaction lock lasts for the operation. GuildGate 0.1.0 does not include lease renewal.
+
+### AuditStore
+
+Prefer append-only permissions for the application account. Redaction in the kernel covers known secret field names, but applications should avoid sending secrets in `changes` at all.
+
+### OutboxStore
+
+`next()` returns unpublished rows. Multiple workers need row claiming, skip-locked reads, or another lease mechanism in the custom driver. `markPublished()` must be idempotent.
+
+### PolicyStore
+
+Block lookup must ignore or remove expired blocks. `bumpPolicyVersion()` must be atomic. The version is written into audit events so an operator can see which policy generation handled a request.
+
+## Driver package layout
+
+A separate adapter can be published without changing the core package:
+
+```text
+packages/
+  guildgate-postgres/
+    src/
+      sessions.ts
+      credentials.ts
+      audit.ts
+      outbox.ts
+      policies.ts
+      index.ts
+```
+
+Use peer dependencies for the ORM or database client when the adapter should share the application’s installed client.
+
+## Driver contract tests
+
+Run the same behavior tests against every adapter:
+
+- OAuth state can be consumed once under concurrency.
+- A session can be revoked immediately.
+- Rate costs never exceed the limit under parallel requests.
+- One idempotency key has one owner.
+- A changed payload causes a conflict.
+- A lock cannot be released by another token.
+- Tag invalidation removes all matching cache entries.
+- Two outbox workers do not publish one row twice without an idempotent publisher.
+- Expired blocks stop applying.
+
+The repository’s memory driver is a reference for behavior, not for production durability.

package/docs/owner-management.md

@@ -0,0 +1,44 @@
+# Owner management routes
+
+Kernel owner methods are internal application APIs. They do not inspect an HTTP request by themselves. Expose them only through actions that require an owner session.
+
+```ts
+const setMaintenance = gate.action({
+  name: "owner.maintenance.set",
+  parse(value) {
+    const body = value as Record<string, unknown>;
+    if (typeof body.enabled !== "boolean") throw new Error("enabled is required");
+    return {
+      enabled: body.enabled,
+      reason: typeof body.reason === "string" ? body.reason : undefined,
+    };
+  },
+  resource: () => ({ type: "policy", id: "maintenance" }),
+  rateLimit: { limit: 5, windowMs: 60_000 },
+  idempotency: { ttlMs: 10 * 60_000 },
+  authorize: (context) => ({
+    allowed: context.isOwner,
+    code: context.isOwner ? undefined : "GUILD_ACCESS_DENIED",
+  }),
+  async execute(_context, input) {
+    await gate.owner.setMaintenance({
+      enabled: input.enabled,
+      reason: input.reason,
+      allowOwners: true,
+    });
+    return { enabled: input.enabled };
+  },
+  audit: { changes: (result) => result },
+});
+```
+
+Use the same structure for user, guild, or IP blocks and for session revocation. Keep the actor, reason, affected subject, and policy version in audit records.
+
+A read-only owner page can use:
+
+```ts
+const sessions = await gate.sessions.list(userId);
+const auditRows = await gate.config.stores.audit.list?.({ userId, limit: 100 });
+```
+
+Do not return session hashes, OAuth ciphertext, raw IP values, or internal exception stacks to the browser.

package/docs/research-notes.md

@@ -0,0 +1,61 @@
+# Research notes
+
+Reviewed on 25 July 2026.
+
+## Writing review
+
+Wikipedia’s “Signs of AI writing” page is an editing essay, not a conclusive detector. It groups possible signs under content, vocabulary and grammar, formatting, user-directed boilerplate, markup artifacts, citation faults, edit summaries, and older model behaviors.
+
+GuildGate applies that material in two places:
+
+- `docs/WRITING_STYLE.md` contains the full repository checklist in project terms.
+- `guildgate-writing-check` rejects common assistant boilerplate, internal citation artifacts, tracking query strings, unfinished placeholders, and a selected list of vague promotional words outside the checklist itself.
+
+Source: https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing
+
+## Discord OAuth and guild access
+
+The Discord OAuth authorization-code flow supports a `state` value and Discord recommends it for request integrity. GuildGate hashes a one-time state record and binds it to a separate browser nonce cookie. The callback consumes the state once.
+
+The default scopes are `identify` and `guilds`. The first identifies the signed-in user. The second returns the user’s guild list and guild permission value.
+
+Discord permission values are serialized as strings because the bitfield can exceed safe JavaScript number precision. GuildGate parses them with `BigInt` and keeps user and bot permission checks separate.
+
+Sources:
+
+- https://docs.discord.com/developers/topics/oauth2
+- https://docs.discord.com/developers/resources/user#get-current-user-guilds
+- https://docs.discord.com/developers/topics/permissions
+
+## HTTP and session controls
+
+OWASP session guidance recommends meaningless session identifiers with server-side state. GuildGate returns a random opaque token once and stores only its SHA-256 hash.
+
+Cookie-authenticated write requests are exposed to cross-site request forgery. GuildGate requires an exact allowed origin and a session-bound CSRF token for unsafe methods.
+
+Sources:
+
+- https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html
+- https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html
+
+## WebSocket controls
+
+OWASP WebSocket guidance calls for origin validation, session handling beyond the initial handshake, authorization for individual messages or actions, payload limits, and logging without secret content.
+
+GuildGate validates the origin and session at attach time, rechecks the session on a timer, authorizes each subscription, limits messages and subscriptions, and closes slow or expired connections.
+
+Source: https://cheatsheetseries.owasp.org/cheatsheets/WebSocket_Security_Cheat_Sheet.html
+
+## Rate limits and retries
+
+Discord applies route and global HTTP rate limits and returns response data that clients must respect. GuildGate’s inbound dashboard limits are separate from Discord’s outbound limits. The OAuth client honors `retry_after` under one total deadline. The guild authorizer surfaces a Discord 429 as a typed rate-limit error. Applications already using a Discord library REST manager should reuse that manager for broader bot traffic.
+
+Source: https://docs.discord.com/developers/topics/rate-limits
+
+## npm publishing
+
+npm trusted publishing uses OIDC from a supported CI provider instead of a long-lived npm publishing token. Current npm documentation also describes automatic provenance for supported trusted-publishing workflows.
+
+The included release workflow grants `id-token: write`, runs tests, and publishes on a GitHub release. The npm package page must first be configured to trust the repository and workflow.
+
+Source: https://docs.npmjs.com/trusted-publishers

package/docs/setup.md

@@ -0,0 +1,104 @@
+# Setup and first release
+
+## 1. Prepare the repository
+
+```bash
+unzip guildgate-0.1.0.zip
+cd guildgate-0.1.0
+npm install
+npm test
+```
+
+`npm install` creates `package-lock.json` on the first connected development machine. Commit that lockfile before the first pull request so CI and contributors install the same dependency graph.
+
+## 2. Run the deployment check
+
+Copy `.env.example` to a private local environment file and fill the values. Generate separate random values for each secret.
+
+```bash
+node ./bin/guildgate-doctor.mjs
+```
+
+Use `GUILDGATE_ENVIRONMENT=production` for the final check. Production mode verifies HTTPS, the origin allowlist, secret lengths, and the token encryption key format.
+
+## 3. Create the GitHub repository
+
+Create an empty public repository named `guildgate` under the `kavtuai` account. Do not add a remote README or license because the archive already contains both.
+
+```bash
+git init
+git branch -M main
+git add .
+git commit -m "feat: initial GuildGate release"
+git remote add origin git@github.com:kavtuai/guildgate.git
+git push -u origin main
+```
+
+Enable these repository settings:
+
+- Branch protection for `main`.
+- Required CI and CodeQL checks.
+- Pull-request review before merge.
+- Secret scanning and push protection where available.
+- Private vulnerability reporting.
+- Dependabot alerts and security updates.
+
+## 4. Reserve and configure the npm package
+
+The package name in `package.json` is `@kavtuai/guildgate`. The `kavtuai` npm organization or user scope must exist and permit public scoped packages.
+
+Configure npm trusted publishing for this repository and the `.github/workflows/publish.yml` workflow. The workflow uses GitHub OIDC and does not need a long-lived npm token when trusted publishing is active.
+
+Before release:
+
+```bash
+npm login
+npm whoami
+npm run pack:check
+```
+
+`npm pack --dry-run` shows the exact files that npm will receive.
+
+## 5. Publish through a GitHub release
+
+Update `CHANGELOG.md`, commit the version, and create a signed or protected tag:
+
+```bash
+npm version 0.1.0 --no-git-tag-version
+git add package.json package-lock.json CHANGELOG.md
+git commit -m "release: v0.1.0"
+git tag -s v0.1.0 -m "GuildGate 0.1.0"
+git push origin main v0.1.0
+```
+
+Create a GitHub release from `v0.1.0`. The publish workflow runs tests and then sends the package to npm.
+
+Do not publish from a workstation after trusted publishing is configured unless an incident procedure explicitly requires it.
+
+## 6. Test an installed package
+
+Create a separate empty directory:
+
+```bash
+mkdir guildgate-consumer-test
+cd guildgate-consumer-test
+npm init -y
+npm install @kavtuai/guildgate@0.1.0
+node -e "import('@kavtuai/guildgate').then(m => console.log(typeof m.createGuildGate))"
+```
+
+The command should print `function`.
+
+## 7. First application integration
+
+Use this order:
+
+1. Select durable and short-lived stores.
+2. Configure the kernel and run the doctor command.
+3. Add Discord OAuth start and callback routes.
+4. Add a session bootstrap endpoint that returns the CSRF token to the signed-in frontend.
+5. Add one read action and one idempotent write action.
+6. Add live guild authorization to the write action.
+7. Add audit and outbox retention jobs.
+8. Connect the realtime hub only after HTTP authorization works.
+9. Test role removal, bot removal, session revocation, Redis loss, database timeout, and duplicate writes.

package/docs/threat-model.md

@@ -0,0 +1,79 @@
+# Threat model
+
+## Protected assets
+
+- Discord bot token and OAuth client secret.
+- OAuth access and refresh tokens.
+- Session tokens and active sessions.
+- Guild settings and moderation actions.
+- Audit history and owner policies.
+- Realtime events that may reveal guild state.
+- Availability of the dashboard and Discord API allowance.
+
+## Attackers considered
+
+- An unauthenticated internet client.
+- An authenticated Discord user without permission for the target guild.
+- A former guild manager whose role was removed while a session remains open.
+- A malicious site attempting cross-site requests or WebSocket connections.
+- A user replaying a request, OAuth callback, or idempotency key.
+- A user sending many requests, large socket messages, or slow-client backpressure.
+- An application bug that logs or returns secrets.
+- A compromised low-privilege database account.
+- A package supply-chain attacker.
+
+## Main controls
+
+| Threat | Control |
+|---|---|
+| Session theft from script | HttpOnly cookie; no localStorage requirement |
+| Session database leak | Only token hashes are stored |
+| Session fixation | New opaque token on login and scheduled rotation |
+| CSRF | Exact origin check plus session-bound token on unsafe methods |
+| OAuth login CSRF or callback replay | One-time state plus browser nonce binding |
+| Open redirect | Local return paths only |
+| Guild ID substitution | Resource and permission checks run on parsed server input |
+| Stale manager permission | Live authorization option for writes |
+| Bot overreach | Required bot permissions are checked separately |
+| Double submission | Idempotency reservation and response replay |
+| Concurrent setting overwrite | Resource lock; application revision check recommended |
+| Request flooding | Per-action store-backed limits |
+| Slow upstream | Deadline, abort signal, retry policy, and circuit breaker utility |
+| WebSocket cross-site use | Origin allowlist and session resolution |
+| Unauthorized channel subscription | Authorization callback per channel |
+| Socket memory pressure | Payload, subscription, lifetime, idle, and buffered-byte caps |
+| Secret exposure in audit | Known-key redaction and caller responsibility |
+| Event before commit | Durable outbox option |
+| Owner policy loss after restart | Durable PolicyStore implementation |
+| Malicious package release | Protected repository, CI tests, npm trusted publishing, provenance |
+
+## Out of scope
+
+GuildGate does not:
+
+- Secure a compromised host or stolen deployment secret.
+- Configure TLS, a reverse proxy, a firewall, database roles, backups, or operating-system updates.
+- Validate application-specific setting schemas unless the action supplies a parser.
+- Create database transactions for an unknown driver.
+- Decide which Discord command or moderation operation is appropriate.
+- Prevent a bot owner from intentionally granting excessive access in application policy.
+- Replace dependency review or incident response.
+
+## Open risks in 0.1.0
+
+- Redis leases have no renewal helper. Keep the lock TTL above the expected operation time or use a driver with stronger locking.
+- The included Discord REST helper has a small retry policy but does not coordinate a process-wide Discord route bucket. Reuse a Discord library REST manager when the application already has one.
+- General audit writes happen after the action result. Put mandatory domain audit records inside the database transaction.
+- Live Discord authorization adds API requests and can be affected by Discord availability. A bot gateway cache with event-based invalidation may be preferable at scale.
+- The memory store uses one process and loses records on restart.
+
+## Review triggers
+
+Review this model when:
+
+- A new store or framework adapter is added.
+- Owner APIs are exposed.
+- Realtime client-to-server commands are added.
+- Premium, billing, or account linking is added.
+- A Discord permission flag or OAuth behavior changes.
+- A release changes session, token, idempotency, lock, audit, or outbox behavior.

package/docs/tr/arastirma-notlari.md

@@ -0,0 +1,41 @@
+# Araştırma notları
+
+İnceleme tarihi: 25 Temmuz 2026.
+
+## Yazım kontrolü
+
+Wikipedia “Signs of AI writing” sayfası kesin yazar tespiti sunmaz. İçerik, kelime ve dilbilgisi, biçim, kullanıcıya konuşan hazır metin, işaretleme kalıntıları, kaynak hataları, edit özeti ve eski model davranışları altında olası işaretleri toplar.
+
+GuildGate bu başlıkları `docs/tr/yazim-kilavuzu.md` dosyasında proje kurallarına çevirdi. `guildgate-writing-check` komutu da hazır asistan cümlelerini, model içi kaynak kalıntılarını, takip parametrelerini, boş şablonları ve belirsiz tanıtım kelimelerini sürüm kontrolünde arar.
+
+Kaynak: https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing
+
+## Discord OAuth ve sunucu yetkisi
+
+Discord authorization-code girişinde `state` kullanımı istek bütünlüğü için önerilir. GuildGate state kaydını hash’ler, ayrı tarayıcı nonce çereziyle eşler ve callback sırasında tek kez tüketir.
+
+Varsayılan scope değerleri `identify` ve `guilds` olarak belirlenmiştir. Discord izin değeri güvenli JavaScript sayı sınırını aşabildiği için string olarak gelir; GuildGate bunu `BigInt` ile işler. Kullanıcı izni ve bot izni ayrı kontrol edilir.
+
+Kaynaklar:
+
+- https://docs.discord.com/developers/topics/oauth2
+- https://docs.discord.com/developers/resources/user#get-current-user-guilds
+- https://docs.discord.com/developers/topics/permissions
+
+## Oturum, CSRF ve WebSocket
+
+OWASP oturum kimliğinin anlamsız olmasını ve asıl verinin sunucuda tutulmasını önerir. GuildGate ham oturum tokenını yalnızca istemciye verir ve sürücüye SHA-256 hash yazar.
+
+Çerezle kimlik doğrulanan yazma isteklerinde tam origin ve oturuma bağlı CSRF tokenı gerekir. WebSocket bağlantısında origin ve oturum ilk bağlantıda doğrulanır; oturum belirli aralıklarla yeniden kontrol edilir ve her kanal aboneliği ayrıca yetkilendirilir.
+
+Kaynaklar:
+
+- https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html
+- https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html
+- https://cheatsheetseries.owasp.org/cheatsheets/WebSocket_Security_Cheat_Sheet.html
+
+## npm yayını
+
+npm trusted publishing, desteklenen CI sağlayıcısından OIDC kullanır ve uzun süreli yayın tokenı ihtiyacını kaldırır. Paketteki GitHub release workflow’u testlerden sonra `id-token: write` izniyle npm yayını yapacak şekilde hazırlanmıştır. npm tarafında depo ve workflow güven ilişkisi önceden tanımlanmalıdır.
+
+Kaynak: https://docs.npmjs.com/trusted-publishers

package/docs/tr/guvenlik-bildirimi.md

@@ -0,0 +1,7 @@
+# Güvenlik bildirimi
+
+Şüpheli güvenlik açığı için herkese açık issue açmayın. Depo kullanıma açıldığında GitHub private vulnerability reporting özelliğini kullanın.
+
+Bildirimde etkilenen sürüm, gerekli ayarlar, tekrar adımları, beklenen ve görülen davranış, olası etki ve denenmiş geçici çözüm bulunmalıdır. Gerçek bot tokenı, OAuth sırrı, oturum çerezi, veritabanı bilgisi veya kullanıcı verisi eklemeyin.
+
+`1.0.0` öncesinde yalnızca en yeni minor sürüm güvenlik düzeltmesi alır. Güvenlik sürümünde etkilenen sürüm aralığı, etki, gerekli koşullar ve güncelleme adımları açıkça yazılır.

package/docs/tr/kurulum.md

@@ -0,0 +1,63 @@
+# Kurulum ve ilk yayın
+
+## 1. Depoyu hazırlama
+
+```bash
+unzip guildgate-0.1.0.zip
+cd guildgate-0.1.0
+npm install
+npm test
+```
+
+İlk internet bağlantılı geliştirme bilgisayarında `npm install`, `package-lock.json` dosyasını oluşturur. İlk pull request öncesinde bu dosyayı commit edin.
+
+## 2. Yapılandırma kontrolü
+
+`.env.example` dosyasını özel bir ortam dosyasına kopyalayın ve her gizli değer için ayrı rastgele veri üretin.
+
+```bash
+node ./bin/guildgate-doctor.mjs
+```
+
+Son kontrolde `GUILDGATE_ENVIRONMENT=production` kullanın. Doctor; HTTPS, origin listesi, gizli değer uzunlukları ve token şifreleme anahtarını kontrol eder.
+
+## 3. GitHub deposu
+
+`kavtuai` hesabında `guildgate` adında boş ve herkese açık bir depo oluşturun.
+
+```bash
+git init
+git branch -M main
+git add .
+git commit -m "feat: initial GuildGate release"
+git remote add origin git@github.com:kavtuai/guildgate.git
+git push -u origin main
+```
+
+`main` dalı için koruma, zorunlu CI ve CodeQL kontrolü, pull request incelemesi, secret scanning, private vulnerability reporting ve Dependabot özelliklerini açın.
+
+## 4. npm ayarı
+
+Paket adı `@kavtuai/guildgate` olarak tanımlıdır. npm tarafında `kavtuai` scope’u herkese açık scoped paket yayımlayabilmelidir.
+
+npm trusted publishing ayarını bu GitHub deposu ve `.github/workflows/publish.yml` dosyasıyla eşleyin. Bu yapı GitHub OIDC kullanır ve uzun süreli npm tokenı gerektirmez.
+
+Yayın öncesi:
+
+```bash
+npm login
+npm whoami
+npm run pack:check
+```
+
+## 5. İlk uygulama bağlantısı
+
+1. Kalıcı ve kısa ömürlü veri sürücülerini seçin.
+2. Çekirdeği kurun ve doctor komutunu çalıştırın.
+3. Discord OAuth başlangıç ve callback endpoint’lerini ekleyin.
+4. Giriş yapmış frontend’e CSRF tokenı veren başlangıç endpoint’ini ekleyin.
+5. Bir okuma ve bir idempotent yazma işlemi hazırlayın.
+6. Yazma işlemine canlı Discord sunucu yetkisi kontrolü ekleyin.
+7. Denetim ve outbox saklama görevlerini hazırlayın.
+8. HTTP yetkilendirmesi tamamlandıktan sonra gerçek zamanlı merkezi bağlayın.
+9. Rol kaldırma, botu sunucudan çıkarma, oturum iptali, Redis kesintisi, veritabanı zaman aşımı ve çift kayıt senaryolarını test edin.

package/docs/tr/mimari.md

@@ -0,0 +1,59 @@
+# Mimari
+
+GuildGate politika, taşıyıcı, Discord erişimi ve veri saklamayı birbirinden ayırır. Çekirdek paket Fastify, Express, Redis, PostgreSQL, MongoDB veya WebSocket sunucusu import etmez.
+
+## Bileşenler
+
+1. **Çekirdek**, oturum, origin, CSRF, engel, bakım, limit, yetki, idempotency, kilit, zaman aşımı, denetim, cache ve gerçek zamanlı teslim kontrollerini yürütür.
+2. **Oturum yöneticisi**, ham token yerine SHA-256 hash kaydeder. Süre, boşta kalma, yenileme, oturum sayısı ve iptal kurallarını uygular.
+3. **Discord OAuth istemcisi**, tek kullanımlık state üretir, state’i tarayıcı nonce değeriyle eşler, code değişimini yapar, şifreli kimlik bilgilerini yeniler ve iptal eder.
+4. **Discord yetkilendiricisi**, kullanıcının OAuth sunucu izinlerini botun güncel rol ve izinleriyle ayrı ayrı kontrol eder.
+5. **Veri arayüzleri**, her uygulamanın kendi veritabanını seçmesini sağlar.
+6. **Framework bağlayıcıları**, framework tiplerini çekirdeğe taşımadan istek ve cevap nesnelerini çevirir.
+7. **Gerçek zamanlı merkez**, bağlantıyı doğrular, her aboneliği yetkilendirir, mesajları sınırlar ve oturum iptalinde socket’i kapatır.
+8. **Outbox dağıtıcısı**, kalıcı outbox sürücüsündeki commit edilmiş olayları yayımlar.
+
+Bileşen şeması: [`../uml/components.mmd`](../uml/components.mmd).
+
+## İşlem sırası
+
+Kimlik doğrulamalı bir yazma isteğinde varsayılan sıra:
+
+1. Oturumu çöz ve zamanı geldiyse kimliği yenile.
+2. İstek origin değerini tam eşleşmeyle kontrol et.
+3. CSRF tokenını oturum hash’iyle doğrula.
+4. Girdiyi doğrula.
+5. Korunan kaynağı belirle.
+6. Bakım ve engel politikalarını uygula.
+7. İşlem limitini uygula.
+8. Uygulama veya Discord yetkilendirmesini çalıştır.
+9. Idempotency anahtarını ayır.
+10. Kaynak kilidini al.
+11. İşlemi tek zaman sınırı altında çalıştır.
+12. Transaction dışındaki takip işlerinden önce idempotency kaydını tamamla.
+13. Cache etiketlerini temizle.
+14. Olayları outbox’a yaz veya doğrudan yayımla.
+15. Denetim olayını yaz.
+16. Kilidi bırak.
+
+Sıra şeması: [`../uml/action-sequence.mmd`](../uml/action-sequence.mmd).
+
+## Transaction sınırı
+
+GuildGate, tanımadığı bir veritabanı sürücüsü için transaction oluşturamaz. Transaction, action içindeki `execute()` fonksiyonuna aittir.
+
+Zorunlu denetim kaydı ayar değişikliğiyle aynı transaction içinde olmalıysa uygulama bu kaydı `execute()` içinde yazmalıdır. Çekirdeğin genel denetim kaydı işlem sonucundan sonra yazılır ve commit edilmiş bir transaction’ı geri alamaz.
+
+## Tutarlılık seçimi
+
+- Oturum ve OAuth state kayıtları tek kullanımlı ve fail-closed olmalıdır.
+- Birden fazla instance için idempotency ve kilit işlemleri atomik olmalıdır.
+- Görüntüleme verileri kısa süre cache’lenebilir.
+- İzin gerektiren yazma işlemleri canlı Discord kontrolü veya olaylarla temizlenen bot cache’i kullanmalıdır.
+- Denetim ve outbox için kalıcı veri saklama önerilir.
+- Yeniden başlatma sonrasında olay teslimi gerekiyorsa outbox kullanılmalıdır.
+
+
+## Commit sonrası sorunlar
+
+`execute()` döndüğünde uygulama kaydı commit etmiş olabilir. Bu nedenle cache, realtime veya genel denetim hatası domain işlemini yeniden çalıştırmaz. Sonuç başarılı döner ve sorunlar `meta.postCommitIssues` içinde bildirilir. Audit için fail-closed kullanılan işlemlerde idempotency zorunludur. Zorunlu ve atomik domain denetimi yine `execute()` içindeki veritabanı transaction’ına yazılmalıdır.

package/docs/tr/sahip-yonetimi.md

@@ -0,0 +1,7 @@
+# Sahip yönetimi
+
+Çekirdeğin `owner` metotları uygulama içi API’dir. HTTP isteğini kendi başına kontrol etmez. Bu metotları yalnızca sahip oturumu isteyen `action()` tanımları içinden çağırın.
+
+Sahip işlemlerinde de origin, CSRF, rate limit, idempotency ve denetim kaydı kullanılmalıdır. Bakım modu, kullanıcı veya sunucu engeli ve oturum iptali için işlem nedeni denetim kaydına eklenmelidir.
+
+Salt okunur sahip ekranı `gate.sessions.list(userId)` ve sürücü destekliyorsa `gate.config.stores.audit.list()` kullanabilir. Oturum hash’i, OAuth ciphertext, ham IP veya exception stack bilgisi tarayıcıya döndürülmemelidir.

package/docs/tr/tehdit-modeli.md

@@ -0,0 +1,39 @@
+# Tehdit modeli
+
+## Korunan veriler
+
+Discord bot tokenı, OAuth sırrı, OAuth tokenları, oturumlar, sunucu ayarları, moderasyon işlemleri, denetim geçmişi, sahip politikaları ve gerçek zamanlı sunucu olayları korunur.
+
+## Dikkate alınan saldırılar
+
+- Kimlik doğrulamamış internet isteği.
+- Hedef sunucuda yetkisi olmayan oturum sahibi.
+- Rolü kaldırılmış ancak paneli açık kalan eski yönetici.
+- CSRF veya siteler arası WebSocket bağlantısı kuran başka site.
+- OAuth callback, istek veya idempotency tekrar saldırısı.
+- Çok sayıda istek, büyük socket mesajı veya yavaş istemci.
+- Gizli değerleri loglayan uygulama hatası.
+- Düşük yetkili veritabanı hesabının ele geçirilmesi.
+- Paket yayın zincirine müdahale.
+
+## Başlıca kontroller
+
+- HttpOnly oturum çerezi ve sunucuda yalnızca token hash’i.
+- Girişte ve belirli aralıklarla yeni oturum kimliği.
+- Yazma isteklerinde tam origin ve oturuma bağlı CSRF kontrolü.
+- OAuth state için tek kullanımlık kayıt ve tarayıcı nonce eşlemesi.
+- Harici adrese yönlendirmeyi reddeden yerel dönüş path’i.
+- Kullanıcı ve bot Discord izinlerinin ayrı kontrolü.
+- İzin gerektiren yazmalarda canlı kontrol seçeneği.
+- Idempotency kaydı, kaynak kilidi ve uygulama revision kontrolü.
+- İşlem bazlı rate limit ve zaman aşımı.
+- Kanal başına WebSocket abonelik yetkisi.
+- Mesaj boyutu, abonelik, boşta kalma, ömür ve buffer sınırı.
+- Gizli alanları maskeleyen denetim kaydı.
+- Commit sonrasında teslim için outbox.
+
+## Kapsam dışı
+
+GuildGate ele geçirilmiş sunucuyu, çalınmış deployment sırrını, TLS ve firewall kurulumunu, veritabanı rollerini, yedeklemeyi, uygulamaya özel şema doğrulamasını veya yanlış yazılmış bot politikasını kendiliğinden düzeltemez.
+
+0.1.0 sürümünde Redis kilit yenileme yardımcısı yoktur. Genel denetim kaydı action sonucundan sonra yazılır. Discord REST yardımcısı süreç genelinde route bucket yöneticisi değildir. Bu sınırlar üretim tasarımında hesaba katılmalıdır.

package/docs/tr/veritabani-suruculeri.md

@@ -0,0 +1,23 @@
+# Özel veritabanı sürücüleri
+
+GuildGate bir veritabanı seçmez. `GuildGateStores` içindeki arayüzleri uygulayıp `createGuildGate()` fonksiyonuna verin.
+
+## Kayıtların yerleştirilmesi
+
+- Oturum, OAuth state, rate limit, cache, idempotency ve kısa süreli kilitler Redis benzeri atomik bir serviste tutulabilir.
+- Şifreli OAuth kimlik bilgileri, denetim, outbox ve politikalar kalıcı veritabanında tutulmalıdır.
+- Outbox’ın domain kaydıyla aynı veritabanında olması commit ile olay teslimi arasındaki boşluğu azaltır.
+
+## Zorunlu davranışlar
+
+- `OAuthStateStore.consume()` okuma ve silmeyi tek atomik işlemde yapmalıdır.
+- `RateLimitStore.hit()` eşzamanlı isteklerde limiti aşan maliyeti kabul etmemelidir.
+- `IdempotencyStore.begin()` aynı anahtar için tek ilk yazara izin vermelidir.
+- `LockStore.release()` kilidi silmeden önce tokenı karşılaştırmalıdır.
+- `AuditStore` için mümkünse sadece ekleme yetkisi olan ayrı veritabanı rolü kullanılmalıdır.
+- Birden fazla outbox worker varsa kayıt sahipliği veya `skip locked` benzeri bir yöntem kullanılmalıdır.
+- `PolicyStore.bumpPolicyVersion()` atomik olmalıdır.
+
+Ham oturum tokenı veri sürücüsüne verilmez. Çekirdek yalnızca `idHash` kaydeder. OAuth tokenları da `TokenCipher` çıktısı olarak saklanır.
+
+Her sürücü; eşzamanlı state tüketimi, idempotency yarışı, limit yarışı, yanlış tokenla kilit bırakma, cache etiketi temizleme ve iki worker’ın aynı outbox kaydını alma senaryolarıyla test edilmelidir.