docs(oauth): add comments addressing code review feedback

- Document intentional RLS bypass in generateCrossOriginToken()
- Document intentional RLS bypass in connected_accounts identity check
- Add note about SQL identifier sources being trusted metaschema config
- Expand isEmailVerified() docs with provider field mappings and TODO

Addresses comments from @pyramation on PR #1220

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

Author: theothersideofgods

graphql/server/src/middleware/oauth.ts

@@ -15,6 +15,10 @@
  * All DB queries run through `req.constructive.withPgClient()` which
  * applies pgSettings (role, claims, request_id) via SET LOCAL, replacing
  * the manual `set_config()` calls in the original implementation.
+ *
+ * SQL Identifiers: Schema/table/function names are interpolated into SQL strings.
+ * These values come exclusively from metaschema module config (trusted, admin-written).
+ * They are not user input and follow PostgreSQL identifier naming conventions.
  */
 
 import crypto from 'crypto';
@@ -217,6 +221,10 @@ async function generateCrossOriginToken(
     RETURNING id
   `;
 
+  // Intentional RLS bypass: This runs as the connection pool user (postgres/superuser)
+  // because we're updating a session that was just created server-side during OAuth callback.
+  // The user hasn't authenticated via JWT yet, so RLS would block this write.
+  // Security: The accessToken hash ensures we only update the session we just created.
   const result = await ctx.pool.query(sql, [otToken, accessToken]);
   if (result.rows.length === 0) {
     throw new Error('Failed to set cross-origin token');
@@ -239,6 +247,19 @@ function getBaseUrl(req: Request): string {
  * Extract email_verified from the raw provider response.
  * OAuthProfile.raw contains the original provider data which includes
  * email_verified for OIDC providers (Google, etc.).
+ *
+ * Known provider field mappings:
+ *   - Google (OIDC): email_verified (boolean)
+ *   - Google (legacy): verified_email (boolean)
+ *   - GitHub: emails[].verified (requires separate API call, not in profile)
+ *   - Microsoft: email_verified (boolean, OIDC)
+ *   - Apple: email_verified (boolean, OIDC)
+ *
+ * For providers that don't include email_verified in the profile (e.g. GitHub),
+ * this returns false. The admin can set oauth_require_verified_email=false
+ * in app_settings_auth to allow sign-in without verification.
+ *
+ * TODO: Consider adding emailVerified to OAuthProfile type upstream in @constructive-io/oauth
  */
 function isEmailVerified(profile: OAuthProfile): boolean {
   const raw = profile.raw as Record<string, unknown> | null;
@@ -512,6 +533,10 @@ export function createOAuthRoutes(_opts: ConstructiveOptions): Router {
             WHERE service = $1 AND identifier = $2
             LIMIT 1
           `;
+          // Intentional RLS bypass: This is a pre-auth lookup for an anonymous user who
+          // cannot query connected_accounts via RLS. We need to check if the OAuth identity
+          // already exists to decide whether to call sign_in_identity or sign_up_identity.
+          // Security: Query only checks existence by service+identifier, no sensitive data returned.
           const checkResult = await ctx.pool.query(checkSql, [
             profile.provider,
             profile.providerId,