@ismaelsoilet/synapsejs 1.8.0 → 1.11.1

package/src/core/oauth-client.ts

@@ -0,0 +1,322 @@
+/**
+ * SynapseJS - Isomorphic OAuth2 & PKCE (Proof Key for Code Exchange) Client
+ *
+ * Provides RFC 7636 compliant PKCE generators and standard authorization / token exchange
+ * flows for Google, GitHub, Microsoft, and generic OAuth2/OIDC providers.
+ */
+
+import { Err, Ok, type Result } from './machine-types';
+
+export interface PkceChallenge {
+  codeVerifier: string;
+  codeChallenge: string;
+  codeChallengeMethod: 'S256';
+}
+
+/**
+ * Generates a high-entropy cryptographic code verifier and SHA-256 code challenge (RFC 7636).
+ */
+export function generatePkceChallenge(): PkceChallenge {
+  const randomBytes = new Uint8Array(32);
+  crypto.getRandomValues(randomBytes);
+
+  // Base64URL encoding without padding
+  const codeVerifier = Buffer.from(randomBytes)
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+
+  const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(codeVerifier);
+  const codeChallenge = hasher.digest('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+
+  return {
+    codeVerifier,
+    codeChallenge,
+    codeChallengeMethod: 'S256'
+  };
+}
+
+export interface OAuthProviderConfig {
+  clientId: string;
+  clientSecret?: string;
+  authorizationUrl: string;
+  tokenUrl: string;
+  redirectUri: string;
+  scope: string[];
+}
+
+export interface BuildAuthUrlOptions {
+  config: OAuthProviderConfig;
+  state: string;
+  codeChallenge?: string;
+  extraParams?: Record<string, string>;
+}
+
+/**
+ * Constructs standard OAuth2 authorization URL with PKCE parameters.
+ */
+export function buildOAuthAuthorizationUrl(options: BuildAuthUrlOptions): string {
+  const url = new URL(options.config.authorizationUrl);
+  url.searchParams.set('client_id', options.config.clientId);
+  url.searchParams.set('redirect_uri', options.config.redirectUri);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('scope', options.config.scope.join(' '));
+  url.searchParams.set('state', options.state);
+
+  if (options.codeChallenge) {
+    url.searchParams.set('code_challenge', options.codeChallenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+  }
+
+  if (options.extraParams) {
+    for (const [key, value] of Object.entries(options.extraParams)) {
+      url.searchParams.set(key, value);
+    }
+  }
+
+  return url.toString();
+}
+
+export interface TokenExchangeOptions {
+  config: OAuthProviderConfig;
+  code: string;
+  codeVerifier?: string;
+  /** Maximum time to wait for the provider, in milliseconds (default: 10s). */
+  timeoutMs?: number;
+}
+
+/** Generates an opaque, high-entropy OAuth `state` value. */
+export function generateOAuthState(): string {
+  const randomBytes = new Uint8Array(32);
+  crypto.getRandomValues(randomBytes);
+
+  return Buffer.from(randomBytes).toString('base64url');
+}
+
+/** Constant-time comparison of the state emitted by the server and the value returned. */
+export function verifyOAuthState(expected: string, received: string | null | undefined): boolean {
+  if (!expected || !received) {
+    return false;
+  }
+
+  const expectedBuf = Buffer.from(expected);
+  const receivedBuf = Buffer.from(received);
+
+  if (expectedBuf.length !== receivedBuf.length) {
+    return false;
+  }
+
+  return require('node:crypto').timingSafeEqual(expectedBuf, receivedBuf);
+}
+
+export interface OAuthTokenResponse {
+  accessToken: string;
+  tokenType: string;
+  expiresIn?: number;
+  refreshToken?: string;
+  scope?: string;
+  idToken?: string;
+  raw: Record<string, unknown>;
+}
+
+/**
+ * Exchanges authorization code for access tokens via standard HTTP POST.
+ */
+export async function exchangeOAuthCode(
+  options: TokenExchangeOptions
+): Promise<Result<OAuthTokenResponse, 'TOKEN_EXCHANGE_FAILED' | 'NETWORK_ERROR'>> {
+  const bodyParams = new URLSearchParams();
+  bodyParams.set('client_id', options.config.clientId);
+  bodyParams.set('code', options.code);
+  bodyParams.set('redirect_uri', options.config.redirectUri);
+  bodyParams.set('grant_type', 'authorization_code');
+
+  if (options.config.clientSecret) {
+    bodyParams.set('client_secret', options.config.clientSecret);
+  }
+
+  if (options.codeVerifier) {
+    bodyParams.set('code_verifier', options.codeVerifier);
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 10_000);
+
+  try {
+    const response = await fetch(options.config.tokenUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json'
+      },
+      body: bodyParams.toString(),
+      signal: controller.signal
+    });
+
+    if (!response.ok) {
+      return Err('TOKEN_EXCHANGE_FAILED');
+    }
+
+    const data = (await response.json()) as Record<string, unknown>;
+    const accessToken = String(data.access_token || data.accessToken || '');
+
+    if (!accessToken) {
+      return Err('TOKEN_EXCHANGE_FAILED');
+    }
+
+    return Ok({
+      accessToken,
+      tokenType: String(data.token_type || data.tokenType || 'Bearer'),
+      expiresIn: typeof data.expires_in === 'number' ? data.expires_in : undefined,
+      refreshToken: typeof data.refresh_token === 'string' ? data.refresh_token : undefined,
+      scope: typeof data.scope === 'string' ? data.scope : undefined,
+      idToken: typeof data.id_token === 'string' ? data.id_token : undefined,
+      raw: data
+    });
+  } catch {
+    return Err('NETWORK_ERROR');
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// ============================================================================
+// OAUTH PROVIDER PRESETS & UNIFIED USER PROFILE
+// ============================================================================
+export interface OAuthUserProfile {
+  id: string;
+  email?: string;
+  name?: string;
+  avatarUrl?: string;
+  provider: 'google' | 'github' | 'discord' | 'oidc';
+  raw: Record<string, unknown>;
+}
+
+export function googleOAuthPreset(options: {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+}): OAuthProviderConfig {
+  return {
+    clientId: options.clientId,
+    clientSecret: options.clientSecret,
+    authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+    tokenUrl: 'https://oauth2.googleapis.com/token',
+    redirectUri: options.redirectUri,
+    scope: ['openid', 'email', 'profile']
+  };
+}
+
+export function githubOAuthPreset(options: {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+}): OAuthProviderConfig {
+  return {
+    clientId: options.clientId,
+    clientSecret: options.clientSecret,
+    authorizationUrl: 'https://github.com/login/oauth/authorize',
+    tokenUrl: 'https://github.com/login/oauth/access_token',
+    redirectUri: options.redirectUri,
+    scope: ['read:user', 'user:email']
+  };
+}
+
+export function discordOAuthPreset(options: {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+}): OAuthProviderConfig {
+  return {
+    clientId: options.clientId,
+    clientSecret: options.clientSecret,
+    authorizationUrl: 'https://discord.com/api/oauth2/authorize',
+    tokenUrl: 'https://discord.com/api/oauth2/token',
+    redirectUri: options.redirectUri,
+    scope: ['identify', 'email']
+  };
+}
+
+export async function fetchOAuthUserProfile(
+  provider: 'google' | 'github' | 'discord' | 'oidc',
+  accessToken: string,
+  userInfoUrl?: string
+): Promise<Result<OAuthUserProfile, 'FETCH_PROFILE_FAILED'>> {
+  const url =
+    userInfoUrl ||
+    (provider === 'google'
+      ? 'https://openidconnect.googleapis.com/v1/userinfo'
+      : provider === 'github'
+        ? 'https://api.github.com/user'
+        : provider === 'discord'
+          ? 'https://discord.com/api/users/@me'
+          : null);
+
+  if (!url) {
+    return Err('FETCH_PROFILE_FAILED');
+  }
+
+  try {
+    const res = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/json',
+        'User-Agent': 'SynapseJS'
+      }
+    });
+
+    if (!res.ok) {
+      return Err('FETCH_PROFILE_FAILED');
+    }
+
+    const data = (await res.json()) as Record<string, unknown>;
+    let id = '';
+    let email: string | undefined;
+    let name: string | undefined;
+    let avatarUrl: string | undefined;
+
+    if (provider === 'google') {
+      id = String(data.sub || data.id || '');
+      email = typeof data.email === 'string' ? data.email : undefined;
+      name = typeof data.name === 'string' ? data.name : undefined;
+      avatarUrl = typeof data.picture === 'string' ? data.picture : undefined;
+    } else if (provider === 'github') {
+      id = String(data.id || '');
+      email = typeof data.email === 'string' ? data.email : undefined;
+      name = typeof data.name === 'string' ? data.name : typeof data.login === 'string' ? data.login : undefined;
+      avatarUrl = typeof data.avatar_url === 'string' ? data.avatar_url : undefined;
+    } else if (provider === 'discord') {
+      id = String(data.id || '');
+      email = typeof data.email === 'string' ? data.email : undefined;
+      name =
+        typeof data.global_name === 'string'
+          ? data.global_name
+          : typeof data.username === 'string'
+            ? data.username
+            : undefined;
+      avatarUrl = data.avatar ? `https://cdn.discordapp.com/avatars/${id}/${data.avatar}.png` : undefined;
+    } else {
+      id = String(data.sub || data.id || '');
+      email = typeof data.email === 'string' ? data.email : undefined;
+      name = typeof data.name === 'string' ? data.name : undefined;
+      avatarUrl = typeof data.picture === 'string' ? data.picture : undefined;
+    }
+
+    if (!id) {
+      return Err('FETCH_PROFILE_FAILED');
+    }
+
+    return Ok({
+      id,
+      email,
+      name,
+      avatarUrl,
+      provider,
+      raw: data
+    });
+  } catch {
+    return Err('FETCH_PROFILE_FAILED');
+  }
+}

package/src/core/path-guard.ts

@@ -0,0 +1,105 @@
+/**
+ * SynapseJS - Path Segment Guard
+ *
+ * The single rule that decides whether caller-supplied input may become one
+ * segment of a filesystem path. Every write surface — slice scaffolding,
+ * shared-module scaffolding, application creation and the upload parser —
+ * passes its input through this validator before joining, so containment
+ * cannot hold on one path and be missing on a sibling.
+ *
+ * It rejects rather than rewrites: a silently sanitized name turns a traversal
+ * into "expected behaviour".
+ */
+
+import * as path from 'path';
+import { Err, Ok, type Result } from './machine-types';
+
+export const MAX_PATH_SEGMENT_LENGTH = 120;
+
+/** An ordinary name: alphanumeric start, then alphanumerics, dot, underscore or dash. */
+const SEGMENT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** The same rule as a pattern source, for schemas that declare the constraint. */
+export const PATH_SEGMENT_PATTERN = SEGMENT_PATTERN.source;
+
+export type PathSegmentErrorCode = 'INVALID_PATH_SEGMENT';
+
+/**
+ * Accepts a caller-supplied string only when it is one safe path segment.
+ *
+ * Rejections: separators, parent traversal, absolute prefixes, empty or
+ * blank segments, over-length input, and anything outside the plain-name
+ * pattern. Every write surface that joins caller input into a filesystem
+ * path applies exactly this rule.
+ */
+export function validatePathSegment(
+  raw: string | null | undefined,
+  maxLength: number = MAX_PATH_SEGMENT_LENGTH
+): Result<string, PathSegmentErrorCode> {
+  if (typeof raw !== 'string') {
+    return Err('INVALID_PATH_SEGMENT');
+  }
+
+  const segment = raw.trim();
+
+  if (!segment || segment.length > maxLength) {
+    return Err('INVALID_PATH_SEGMENT');
+  }
+
+  if (segment.includes('/') || segment.includes('\\') || segment.includes('\0')) {
+    return Err('INVALID_PATH_SEGMENT');
+  }
+
+  if (segment.includes('..')) {
+    return Err('INVALID_PATH_SEGMENT');
+  }
+
+  if (path.isAbsolute(segment) || /^[A-Za-z]:/.test(segment)) {
+    return Err('INVALID_PATH_SEGMENT');
+  }
+
+  if (!SEGMENT_PATTERN.test(segment)) {
+    return Err('INVALID_PATH_SEGMENT');
+  }
+
+  return Ok(segment);
+}
+
+/**
+ * True only when `target` resolves to a location strictly inside `base`.
+ *
+ * This is the post-join assertion: character validation alone is defeated by
+ * a compound path that looks safe segment by segment, so the resolved target
+ * is compared against the resolved base before any write.
+ */
+export function isInsideBase(base: string, target: string): boolean {
+  const resolvedBase = path.resolve(base);
+  const resolvedTarget = path.resolve(target);
+  const relative = path.relative(resolvedBase, resolvedTarget);
+
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+
+/**
+ * Validates every segment, joins them onto `base` and asserts the resolved
+ * target stays inside it. The only way to turn caller input into a write path.
+ */
+export function resolveWithinBase(base: string, ...segments: string[]): Result<string, PathSegmentErrorCode> {
+  const resolvedBase = path.resolve(base);
+
+  for (const segment of segments) {
+    const validated = validatePathSegment(segment);
+
+    if (!validated.ok) {
+      return validated;
+    }
+  }
+
+  const target = path.join(resolvedBase, ...segments);
+
+  if (!isInsideBase(resolvedBase, target)) {
+    return Err('INVALID_PATH_SEGMENT');
+  }
+
+  return Ok(target);
+}

package/src/core/postgres-client.ts

@@ -95,6 +95,26 @@ export class PostgresDatabaseClient implements DatabaseClient {
     return rows.length;
   }
 
+  async count(table: string, where?: WhereCondition): Promise<number> {
+    const { sql, params } = compileSelect(table, {
+      aggregations: [{ fn: 'COUNT', column: '*', as: 'total' }],
+      where
+    });
+    const row = await this.queryOne<{ total: number | string }>(sql, params);
+    return row ? Number(row.total) : 0;
+  }
+
+  async exists(table: string, where: WhereCondition): Promise<boolean> {
+    const { sql, params } = compileSelect(table, { select: ['1'], where, limit: 1 });
+    const row = await this.queryOne<Record<string, unknown>>(sql, params);
+
+    return row !== null;
+  }
+
+  async aggregate<T = Record<string, unknown>>(table: string, options: QueryOptions): Promise<T[]> {
+    return this.findMany<T>(table, options);
+  }
+
   async transaction<T>(operation: (tx: DatabaseClient) => Promise<T>): Promise<T> {
     const res = await this.client.begin(async (sqlTx) => {
       const txClient: DatabaseClient = {
@@ -155,6 +175,23 @@ export class PostgresDatabaseClient implements DatabaseClient {
           const rows = await txClient.query(sql, params);
           return rows.length;
         },
+        count: async (table: string, where?: WhereCondition) => {
+          const { sql, params } = compileSelect(table, {
+            aggregations: [{ fn: 'COUNT', column: '*', as: 'total' }],
+            where
+          });
+          const row = await txClient.queryOne<{ total: number | string }>(sql, params);
+          return row ? Number(row.total) : 0;
+        },
+        exists: async (table: string, where: WhereCondition) => {
+          const { sql, params } = compileSelect(table, { select: ['1'], where, limit: 1 });
+          const row = await txClient.queryOne<Record<string, unknown>>(sql, params);
+
+          return row !== null;
+        },
+        aggregate: async <U = Record<string, unknown>>(table: string, options: QueryOptions) => {
+          return txClient.findMany<U>(table, options);
+        },
         transaction: async <U>(subOp: (nestedTx: DatabaseClient) => Promise<U>) => {
           return await subOp(txClient);
         }

package/src/core/postgres-queue.ts

@@ -14,6 +14,8 @@ import {
   createDefaultLogger,
   type JobDefinition,
   type JobEnqueueOptions,
+  JobScheduleError,
+  jobPayloadMatchesSchema,
   type SessionContext,
   type StructuredLogger
 } from './index';
@@ -97,6 +99,28 @@ export class PostgresQueueEngine {
 
   registerJob<T>(job: JobDefinition<T>): void {
     this.registry.set(job.name, job as JobDefinition<unknown>);
+
+    if (job.cron) {
+      throw new JobScheduleError(
+        'CRON_UNSUPPORTED_ENGINE',
+        `Job "${job.name}" uses cron, which the PostgreSQL queue engine does not implement yet. Use the SQLite QueueEngine or schedule externally.`
+      );
+    }
+
+    if (job.runAt !== undefined) {
+      const payload = job.cronPayload ? job.cronPayload() : ({} as T);
+
+      if (!jobPayloadMatchesSchema(job.schema, payload)) {
+        throw new JobScheduleError(
+          'INVALID_CRON_PAYLOAD',
+          `Job "${job.name}" has a schema that rejects its initial runAt payload.`
+        );
+      }
+
+      void this.enqueue(job, payload, { runAt: job.runAt }).catch((err) => {
+        this.logger.error(`Falha ao registrar agendamento runAt para ${job.name}: ${err}`);
+      });
+    }
   }
 
   async enqueue<TPayload>(
@@ -106,6 +130,13 @@ export class PostgresQueueEngine {
   ): Promise<string> {
     await this.initSchema();
 
+    if (options?.runAt !== undefined && options?.delaySeconds !== undefined) {
+      throw new JobScheduleError(
+        'CONFLICTING_SCHEDULE',
+        `Job "${typeof jobOrName === 'string' ? jobOrName : jobOrName.name}" cannot declare both runAt and delaySeconds.`
+      );
+    }
+
     const id = `job_${crypto.randomUUID().replace(/-/g, '')}`;
     const name = typeof jobOrName === 'string' ? jobOrName : jobOrName.name;
     const maxAttempts = typeof jobOrName === 'object' && jobOrName.retryLimit ? jobOrName.retryLimit : 3;
@@ -113,7 +144,7 @@ export class PostgresQueueEngine {
     const priority = options?.priority ?? 0;
     const delaySeconds = options?.delaySeconds ?? 0;
     const now = Date.now();
-    const runAt = now + delaySeconds * 1000;
+    const runAt = options?.runAt ?? now + delaySeconds * 1000;
     const payloadStr = JSON.stringify(payload);
 
     await this.db.query(
@@ -146,14 +177,32 @@ export class PostgresQueueEngine {
     );
 
     for (const deadJob of deadJobs) {
-      await this.db
-        .query(
-          `INSERT INTO _synapse_jobs_dlq (id, name, payload, attempts, max_attempts, last_error, failed_at)
-           VALUES ($1, $2, $3, $4, $5, $6, $7)
+      // `job_id` is NOT NULL in the table, and the id is derived from the job so a
+      // repeated recovery of the same zombie stays idempotent. A failure here is
+      // logged: swallowing it is how a dead-letter queue silently holds nothing.
+      const dlqId = `dlq_${deadJob.id}`;
+
+      try {
+        await this.db.query(
+          `INSERT INTO _synapse_jobs_dlq (id, job_id, name, payload, attempts, max_attempts, last_error, failed_at)
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
            ON CONFLICT (id) DO UPDATE SET attempts = EXCLUDED.attempts, last_error = EXCLUDED.last_error, failed_at = EXCLUDED.failed_at;`,
-          [deadJob.id, deadJob.name, deadJob.payload, deadJob.attempts, deadJob.max_attempts, deadJob.last_error, now]
-        )
-        .catch(() => {});
+          [
+            dlqId,
+            deadJob.id,
+            deadJob.name,
+            deadJob.payload,
+            deadJob.attempts,
+            deadJob.max_attempts,
+            deadJob.last_error,
+            now
+          ]
+        );
+      } catch (error: unknown) {
+        this.logger.warn(
+          `[DLQ] Falha ao registrar o job ${deadJob.id} na dead letter queue: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
     }
 
     const rows = await this.db.query<JobRecord>(
@@ -189,7 +238,8 @@ export class PostgresQueueEngine {
     }
 
     const jobDef = this.registry.get(job.name);
-    const attempts = Number(job.attempts) + 1;
+    // Note: attempts is already incremented in SQL by claimNextJob (`attempts = attempts + 1 RETURNING *`)
+    const attempts = Number(job.attempts);
     const now = Date.now();
 
     if (!jobDef) {
@@ -302,6 +352,23 @@ export class PostgresQueueEngine {
     return true;
   }
 
+  /** SQLite QueueEngine-compatible alias for inspecting the DLQ. */
+  async getDeadLetterJobs(limit = 50): Promise<DlqRecord[]> {
+    return this.getDlqJobs(limit);
+  }
+
+  /** SQLite QueueEngine-compatible alias: retries the DLQ entry for a job id. */
+  async retryJob(jobId: string): Promise<boolean> {
+    await this.initSchema();
+    const rows = await this.db.query<{ id: string }>(`SELECT id FROM _synapse_jobs_dlq WHERE job_id = $1`, [jobId]);
+
+    if (rows.length === 0) {
+      return false;
+    }
+
+    return this.retryDlqJob(rows[0].id);
+  }
+
   async close(): Promise<void> {
     // No-op for db instance managed externally
   }