@carlos-tzin/tzin 0.1.7 → 0.1.9

package/dist/auth.d.ts

@@ -0,0 +1,76 @@
+import type { Middleware } from './middleware.js';
+export interface AuthUser {
+    id: string;
+    [key: string]: unknown;
+}
+export interface AuthConfig {
+    /** Secret key for JWT signing/verification */
+    secret: string;
+    /** Token issuer (optional) */
+    issuer?: string;
+    /** Token audience (optional) */
+    audience?: string;
+    /** Token expiration (default: '1h') */
+    expiresIn?: string;
+    /** Custom token extractor (default: Bearer header) */
+    extractToken?: (req: Request) => string | null;
+    /** Called when auth fails */
+    onUnauthorized?: (req: Request, reason: string) => Response | Promise<Response>;
+}
+export interface JwtPayload {
+    sub: string;
+    iat: number;
+    exp: number;
+    iss?: string;
+    aud?: string;
+    [key: string]: unknown;
+}
+/** Typed key for the authenticated user */
+export declare const AUTH_USER: import("./context.js").ContextKey<AuthUser>;
+/**
+ * Sign a JWT token.
+ */
+export declare function signJwt(payload: Record<string, unknown>, secret: string, options?: {
+    expiresIn?: string;
+    issuer?: string;
+    audience?: string;
+}): string;
+/**
+ * Verify a JWT token.
+ */
+export declare function verifyJwt(token: string, secret: string, options?: {
+    issuer?: string;
+    audience?: string;
+}): JwtPayload;
+/**
+ * Bearer token authentication middleware.
+ *
+ * Validates the Authorization: Bearer <token> header and attaches
+ * the decoded user to ctx.set(AUTH_USER, user).
+ *
+ * @example
+ * ```ts
+ * import { bearerAuth, AUTH_USER } from '@carlos-tzin/tzin/auth'
+ *
+ * const app = createApp(routes, {
+ *   middleware: [bearerAuth({ secret: process.env.JWT_SECRET! })],
+ * })
+ *
+ * // In handler:
+ * const user = ctx.require(AUTH_USER)
+ * ```
+ */
+export declare function bearerAuth(config: AuthConfig): Middleware;
+/**
+ * Optional auth middleware - doesn't fail if no token,
+ * but validates if present.
+ */
+export declare function optionalAuth(config: AuthConfig): Middleware;
+/**
+ * API key authentication middleware.
+ * Checks for a header like X-API-Key.
+ */
+export declare function apiKeyAuth(config: {
+    key: string;
+    header?: string;
+}): Middleware;

package/dist/auth.js

@@ -0,0 +1,177 @@
+import { defineContext } from './context.js';
+// ── Context Key ──────────────────────────────────────────────────────
+/** Typed key for the authenticated user */
+export const AUTH_USER = defineContext('auth_user');
+// ── JWT Utilities (minimal, no dependencies) ────────────────────────
+function base64UrlEncode(data) {
+    return Buffer.from(data).toString('base64url');
+}
+function base64UrlDecode(data) {
+    return Buffer.from(data, 'base64url').toString();
+}
+function hmacSign(data, secret) {
+    const { createHmac } = require('node:crypto');
+    return createHmac('sha256', secret).update(data).digest('base64url');
+}
+/**
+ * Sign a JWT token.
+ */
+export function signJwt(payload, secret, options) {
+    const header = { alg: 'HS256', typ: 'JWT' };
+    const now = Math.floor(Date.now() / 1000);
+    const exp = options?.expiresIn ? parseDuration(options.expiresIn) : 3600;
+    const fullPayload = {
+        ...payload,
+        iat: now,
+        exp: now + exp,
+        ...(options?.issuer && { iss: options.issuer }),
+        ...(options?.audience && { aud: options.audience }),
+    };
+    const headerEncoded = base64UrlEncode(JSON.stringify(header));
+    const payloadEncoded = base64UrlEncode(JSON.stringify(fullPayload));
+    const signature = hmacSign(`${headerEncoded}.${payloadEncoded}`, secret);
+    return `${headerEncoded}.${payloadEncoded}.${signature}`;
+}
+/**
+ * Verify a JWT token.
+ */
+export function verifyJwt(token, secret, options) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        throw new Error('Invalid JWT format');
+    const [headerEncoded, payloadEncoded, signature] = parts;
+    const expectedSig = hmacSign(`${headerEncoded}.${payloadEncoded}`, secret);
+    if (signature !== expectedSig)
+        throw new Error('Invalid JWT signature');
+    const payload = JSON.parse(base64UrlDecode(payloadEncoded));
+    if (payload.exp && payload.exp < Math.floor(Date.now() / 1000)) {
+        throw new Error('Token expired');
+    }
+    if (options?.issuer && payload.iss !== options.issuer) {
+        throw new Error('Invalid issuer');
+    }
+    if (options?.audience && payload.aud !== options.audience) {
+        throw new Error('Invalid audience');
+    }
+    return payload;
+}
+function parseDuration(str) {
+    const match = str.match(/^(\d+)([smhd])$/);
+    if (!match)
+        return 3600;
+    const [, num, unit] = match;
+    const n = parseInt(num, 10);
+    switch (unit) {
+        case 's': return n;
+        case 'm': return n * 60;
+        case 'h': return n * 3600;
+        case 'd': return n * 86400;
+        default: return 3600;
+    }
+}
+// ── Middleware ────────────────────────────────────────────────────────
+/**
+ * Bearer token authentication middleware.
+ *
+ * Validates the Authorization: Bearer <token> header and attaches
+ * the decoded user to ctx.set(AUTH_USER, user).
+ *
+ * @example
+ * ```ts
+ * import { bearerAuth, AUTH_USER } from '@carlos-tzin/tzin/auth'
+ *
+ * const app = createApp(routes, {
+ *   middleware: [bearerAuth({ secret: process.env.JWT_SECRET! })],
+ * })
+ *
+ * // In handler:
+ * const user = ctx.require(AUTH_USER)
+ * ```
+ */
+export function bearerAuth(config) {
+    const extract = config.extractToken ?? defaultExtractToken;
+    const onUnauthorized = config.onUnauthorized ?? defaultUnauthorized;
+    return async ({ req, ctx, next }) => {
+        const token = extract(req);
+        if (!token) {
+            return onUnauthorized(req, 'Missing token');
+        }
+        try {
+            const payload = verifyJwt(token, config.secret, {
+                issuer: config.issuer,
+                audience: config.audience,
+            });
+            const user = {
+                id: payload.sub,
+                ...payload,
+            };
+            ctx.set(AUTH_USER, user);
+            return next();
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : 'Invalid token';
+            return onUnauthorized(req, reason);
+        }
+    };
+}
+/**
+ * Optional auth middleware - doesn't fail if no token,
+ * but validates if present.
+ */
+export function optionalAuth(config) {
+    const extract = config.extractToken ?? defaultExtractToken;
+    return async ({ req, ctx, next }) => {
+        const token = extract(req);
+        if (!token) {
+            return next();
+        }
+        try {
+            const payload = verifyJwt(token, config.secret, {
+                issuer: config.issuer,
+                audience: config.audience,
+            });
+            const user = {
+                id: payload.sub,
+                ...payload,
+            };
+            ctx.set(AUTH_USER, user);
+        }
+        catch {
+            // Ignore invalid tokens in optional mode
+        }
+        return next();
+    };
+}
+/**
+ * API key authentication middleware.
+ * Checks for a header like X-API-Key.
+ */
+export function apiKeyAuth(config) {
+    const headerName = config.header ?? 'x-api-key';
+    return async ({ req, next }) => {
+        const apiKey = req.headers.get(headerName);
+        if (!apiKey || apiKey !== config.key) {
+            return new Response(JSON.stringify({ error: 'Invalid API key' }), {
+                status: 401,
+                headers: { 'content-type': 'application/json' },
+            });
+        }
+        return next();
+    };
+}
+// ── Helpers ──────────────────────────────────────────────────────────
+function defaultExtractToken(req) {
+    const auth = req.headers.get('authorization');
+    if (!auth)
+        return null;
+    const parts = auth.split(' ');
+    if (parts.length !== 2 || parts[0] !== 'Bearer')
+        return null;
+    return parts[1];
+}
+function defaultUnauthorized(_req, reason) {
+    return new Response(JSON.stringify({ error: reason }), {
+        status: 401,
+        headers: { 'content-type': 'application/json' },
+    });
+}

package/dist/jobs.d.ts

@@ -0,0 +1,104 @@
+export interface JobConfig {
+    /** Unique job name */
+    name: string;
+    /** Max retries on failure (default: 3) */
+    maxRetries?: number;
+    /** Delay between retries in ms (default: 1000) */
+    retryDelay?: number;
+    /** Job timeout in ms (default: 30000) */
+    timeout?: number;
+}
+export interface JobDefinition<Payload = unknown> {
+    readonly name: string;
+    readonly config: JobConfig;
+    /** Process the job */
+    handler: (payload: Payload, ctx: JobContext) => Promise<void>;
+}
+export interface JobContext {
+    /** Job attempt number (0-based) */
+    attempt: number;
+    /** Abort signal for cancellation */
+    signal: AbortSignal;
+    /** Logger scoped to this job */
+    log: JobLogger;
+}
+export interface JobLogger {
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+export interface Job<Payload = unknown> {
+    /** Job name */
+    readonly name: string;
+    /** Job configuration */
+    readonly config: JobConfig;
+    /** Enqueue the job for processing */
+    enqueue(payload: Payload, options?: EnqueueOptions): Promise<JobHandle>;
+}
+export interface EnqueueOptions {
+    /** Delay before processing in ms */
+    delay?: number;
+    /** Schedule for a specific time */
+    scheduledAt?: Date;
+}
+export interface JobHandle {
+    /** Job ID */
+    id: string;
+    /** Poll for completion */
+    wait(): Promise<JobResult>;
+}
+export interface JobResult {
+    status: 'completed' | 'failed';
+    error?: string;
+    duration: number;
+}
+export type JobStatus = 'pending' | 'running' | 'completed' | 'failed';
+export interface JobRecord {
+    id: string;
+    name: string;
+    payload: unknown;
+    status: JobStatus;
+    attempt: number;
+    maxRetries: number;
+    error?: string;
+    createdAt: Date;
+    startedAt?: Date;
+    completedAt?: Date;
+}
+export interface JobStore {
+    add(record: JobRecord): void;
+    update(id: string, data: Partial<JobRecord>): void;
+    getById(id: string): JobRecord | null;
+    getPending(): JobRecord[];
+}
+/**
+ * Define a background job.
+ *
+ * @example
+ * ```ts
+ * import { defineJob } from '@carlos-tzin/tzin/jobs'
+ *
+ * const sendEmail = defineJob<{ to: string; subject: string; body: string }>({
+ *   name: 'send-email',
+ *   maxRetries: 3,
+ *   handler: async (payload, ctx) => {
+ *     ctx.log.info('Sending email', { to: payload.to })
+ *     await resend.emails.send({ ... })
+ *   },
+ * })
+ *
+ * // In a handler:
+ * await sendEmail.enqueue({ to: 'ada@example.com', subject: 'Hello', body: '...' })
+ * ```
+ */
+export declare function defineJob<Payload = void>(config: JobConfig & {
+    handler: (payload: Payload, ctx: JobContext) => Promise<void>;
+}): Job<Payload>;
+/**
+ * Get all job records (useful for debugging).
+ */
+export declare function getJobRecords(): JobRecord[];
+/**
+ * Reset the job store (useful for testing).
+ */
+export declare function resetJobs(): void;

package/dist/jobs.js

@@ -0,0 +1,202 @@
+// ── Types ────────────────────────────────────────────────────────────
+class MemoryJobStore {
+    records = new Map();
+    add(record) {
+        this.records.set(record.id, { ...record });
+    }
+    update(id, data) {
+        const record = this.records.get(id);
+        if (record)
+            Object.assign(record, data);
+    }
+    getById(id) {
+        const record = this.records.get(id);
+        return record ? { ...record } : null;
+    }
+    getPending() {
+        return [...this.records.values()].filter((r) => r.status === 'pending');
+    }
+}
+// ── Queue State ──────────────────────────────────────────────────────
+let globalStore = new MemoryJobStore();
+let processing = false;
+let processTimer = null;
+const handlers = new Map();
+// ── defineJob ────────────────────────────────────────────────────────
+/**
+ * Define a background job.
+ *
+ * @example
+ * ```ts
+ * import { defineJob } from '@carlos-tzin/tzin/jobs'
+ *
+ * const sendEmail = defineJob<{ to: string; subject: string; body: string }>({
+ *   name: 'send-email',
+ *   maxRetries: 3,
+ *   handler: async (payload, ctx) => {
+ *     ctx.log.info('Sending email', { to: payload.to })
+ *     await resend.emails.send({ ... })
+ *   },
+ * })
+ *
+ * // In a handler:
+ * await sendEmail.enqueue({ to: 'ada@example.com', subject: 'Hello', body: '...' })
+ * ```
+ */
+export function defineJob(config) {
+    const jobConfig = {
+        maxRetries: 3,
+        retryDelay: 1000,
+        timeout: 30000,
+        ...config,
+    };
+    handlers.set(config.name, config.handler);
+    return {
+        name: config.name,
+        config: jobConfig,
+        async enqueue(payload, options) {
+            const id = `${config.name}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const record = {
+                id,
+                name: config.name,
+                payload,
+                status: 'pending',
+                attempt: 0,
+                maxRetries: jobConfig.maxRetries,
+                createdAt: new Date(),
+                ...(options?.scheduledAt && { scheduledAt: options.scheduledAt }),
+            };
+            globalStore.add(record);
+            scheduleProcess();
+            return {
+                id,
+                async wait() {
+                    return waitForJob(id, jobConfig.timeout * (jobConfig.maxRetries + 1));
+                },
+            };
+        },
+    };
+}
+// ── Processing ───────────────────────────────────────────────────────
+function scheduleProcess() {
+    if (processTimer)
+        return;
+    processTimer = setTimeout(async () => {
+        processTimer = null;
+        await processPending();
+    }, 10);
+}
+async function processPending() {
+    if (processing)
+        return;
+    processing = true;
+    try {
+        const pending = globalStore.getPending();
+        for (const record of pending) {
+            await processRecord(record);
+        }
+    }
+    finally {
+        processing = false;
+        if (globalStore.getPending().length > 0) {
+            scheduleProcess();
+        }
+    }
+}
+async function processRecord(record) {
+    const handler = handlers.get(record.name);
+    if (!handler) {
+        globalStore.update(record.id, { status: 'failed', error: 'No handler found' });
+        return;
+    }
+    globalStore.update(record.id, { status: 'running', startedAt: new Date() });
+    const controller = new AbortController();
+    const ctx = {
+        attempt: record.attempt,
+        signal: controller.signal,
+        log: createLogger(record.name),
+    };
+    try {
+        await Promise.race([
+            handler(record.payload, ctx),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('Job timeout')), 30000)),
+        ]);
+        globalStore.update(record.id, {
+            status: 'completed',
+            completedAt: new Date(),
+        });
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        const attempt = record.attempt + 1;
+        if (attempt < record.maxRetries) {
+            globalStore.update(record.id, { status: 'pending', attempt });
+            setTimeout(() => scheduleProcess(), 1000);
+        }
+        else {
+            globalStore.update(record.id, {
+                status: 'failed',
+                error,
+                attempt,
+                completedAt: new Date(),
+            });
+        }
+    }
+}
+function waitForJob(id, timeout) {
+    return new Promise((resolve, reject) => {
+        const start = Date.now();
+        const check = () => {
+            const record = globalStore.getById(id);
+            if (!record) {
+                reject(new Error('Job not found'));
+                return;
+            }
+            if (record.status === 'completed') {
+                resolve({
+                    status: 'completed',
+                    duration: (record.completedAt?.getTime() ?? Date.now()) - record.createdAt.getTime(),
+                });
+                return;
+            }
+            if (record.status === 'failed') {
+                resolve({
+                    status: 'failed',
+                    error: record.error,
+                    duration: (record.completedAt?.getTime() ?? Date.now()) - record.createdAt.getTime(),
+                });
+                return;
+            }
+            if (Date.now() - start > timeout) {
+                reject(new Error('Timeout waiting for job'));
+                return;
+            }
+            setTimeout(check, 100);
+        };
+        check();
+    });
+}
+function createLogger(name) {
+    const prefix = `[job:${name}]`;
+    return {
+        info: (msg, data) => console.log(prefix, msg, data ?? ''),
+        warn: (msg, data) => console.warn(prefix, msg, data ?? ''),
+        error: (msg, data) => console.error(prefix, msg, data ?? ''),
+    };
+}
+// ── Utilities ────────────────────────────────────────────────────────
+/**
+ * Get all job records (useful for debugging).
+ */
+export function getJobRecords() {
+    return globalStore['records']
+        ? [...globalStore['records'].values()]
+        : [];
+}
+/**
+ * Reset the job store (useful for testing).
+ */
+export function resetJobs() {
+    globalStore = new MemoryJobStore();
+    handlers.clear();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlos-tzin/tzin",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Contract-first TypeScript framework. Types that scale, realtime channels with presence, and an MCP server for every API.",
   "license": "MIT",
   "author": "The tzin authors",
@@ -50,6 +50,14 @@
     "./db": {
       "types": "./dist/db.d.ts",
       "default": "./dist/db.js"
+    },
+    "./auth": {
+      "types": "./dist/auth.d.ts",
+      "default": "./dist/auth.js"
+    },
+    "./jobs": {
+      "types": "./dist/jobs.d.ts",
+      "default": "./dist/jobs.js"
     }
   },
   "files": [