zyket 1.2.17 → 1.2.19

package/src/templates/api-rest/README.md

@@ -0,0 +1,50 @@
+# api-rest template
+
+Backend-only REST API starter with email/password auth and a protected CRUD
+resource (`Task`). No frontend, no sockets.
+
+## What's included
+- `index.js` — boots the kernel (auth + database + express) and syncs the `Task` table.
+- `src/services/auth/` — auth service (email/password, no organizations).
+- `src/models/Task.js` — example Sequelize model.
+- `src/routes/tasks/` — full CRUD, every endpoint protected with `RequireAuthMiddleware`.
+
+## Endpoints (all require a valid session)
+| Method | Path | Description |
+|--------|------|-------------|
+| GET    | `/tasks`      | List tasks |
+| POST   | `/tasks`      | Create a task `{ title, description? }` |
+| GET    | `/tasks/:id`  | Get one task |
+| PUT    | `/tasks/:id`  | Update a task |
+| DELETE | `/tasks/:id`  | Delete a task |
+
+Auth endpoints are mounted by better-auth under `/api/auth/*`.
+
+## Setup
+```bash
+npm install
+# 1) Create the better-auth tables (uses src/services/auth/auth.js)
+npx @better-auth/cli migrate
+# 2) Run
+node index.js
+```
+
+The `Task` table is created automatically via `sequelize.sync()` on boot.
+
+## Auth quick test
+```bash
+# Sign up
+curl -X POST http://localhost:3000/api/auth/sign-up/email \
+  -H "Content-Type: application/json" \
+  -d '{"email":"me@example.com","password":"supersecret","name":"Me"}' -c cookies.txt
+
+# Create a task with the session cookie
+curl -X POST http://localhost:3000/tasks \
+  -H "Content-Type: application/json" -b cookies.txt \
+  -d '{"title":"My first task"}'
+```
+
+## Notes
+- `RequireAuthMiddleware` attaches `request.user` / `request.session`. Restrict by role with `new RequireAuthMiddleware(['admin'])`.
+- Email sending is stubbed (logged to console) — wire a real provider in `src/services/auth/index.js`.
+- Review [SECURITY.md] in the framework for hardening (Swagger password, CORS, rate limiting).

package/src/templates/api-rest/index.js

@@ -0,0 +1,18 @@
+const { Kernel } = require('zyket');
+
+const kernel = new Kernel({
+  services: [
+    // The database and express services are auto-registered by the framework
+    // (they activate from your .env). We only register the auth service here.
+    ['auth', require('./src/services/auth'), ['@service_container']],
+  ],
+});
+
+kernel.boot().then(async () => {
+  // Create the example tables (Task). better-auth tables are created via the
+  // better-auth CLI migrate step (see README).
+  await kernel.container.get('database').sync();
+  kernel.container.get('logger').info('api-rest template ready — try GET /tasks');
+}).catch((error) => {
+  console.error('Error booting kernel:', error);
+});

package/src/templates/api-rest/src/models/Task.js

@@ -0,0 +1,18 @@
+module.exports = ({ sequelize, Sequelize }) => {
+  const Task = sequelize.define('Task', {
+    title: {
+      type: Sequelize.STRING,
+      allowNull: false,
+    },
+    description: {
+      type: Sequelize.TEXT,
+      allowNull: true,
+    },
+    completed: {
+      type: Sequelize.BOOLEAN,
+      defaultValue: false,
+    },
+  });
+
+  return Task;
+};

package/src/templates/api-rest/src/routes/tasks/[id].js

@@ -0,0 +1,42 @@
+const { Route, RequireAuthMiddleware } = require('zyket');
+
+// Item endpoints: GET/PUT/DELETE /tasks/:id
+module.exports = class TaskRoute extends Route {
+  middlewares = {
+    get: [new RequireAuthMiddleware()],
+    put: [new RequireAuthMiddleware()],
+    delete: [new RequireAuthMiddleware()],
+  };
+
+  async #find(container, id) {
+    const { Task } = container.get('database').models;
+    return Task.findByPk(id);
+  }
+
+  async get({ container, request }) {
+    const task = await this.#find(container, request.params.id);
+    if (!task) return { success: false, message: 'Task not found', status: 404 };
+    return { task };
+  }
+
+  async put({ container, request }) {
+    const task = await this.#find(container, request.params.id);
+    if (!task) return { success: false, message: 'Task not found', status: 404 };
+
+    const { title, completed, description } = request.body || {};
+    await task.update({
+      title: title ?? task.title,
+      description: description ?? task.description,
+      completed: completed ?? task.completed,
+    });
+    return { task };
+  }
+
+  async delete({ container, request }) {
+    const task = await this.#find(container, request.params.id);
+    if (!task) return { success: false, message: 'Task not found', status: 404 };
+
+    await task.destroy();
+    return { message: 'Task deleted' };
+  }
+};

package/src/templates/api-rest/src/routes/tasks/index.js

@@ -0,0 +1,26 @@
+const { Route, RequireAuthMiddleware } = require('zyket');
+
+// Collection endpoints: GET /tasks and POST /tasks
+module.exports = class TasksRoute extends Route {
+  middlewares = {
+    get: [new RequireAuthMiddleware()],
+    post: [new RequireAuthMiddleware()],
+  };
+
+  async get({ container }) {
+    const { Task } = container.get('database').models;
+    const tasks = await Task.findAll({ order: [['createdAt', 'DESC']] });
+    return { tasks };
+  }
+
+  async post({ container, request }) {
+    const { title, description } = request.body || {};
+    if (!title) {
+      return { success: false, message: 'title is required', status: 400 };
+    }
+
+    const { Task } = container.get('database').models;
+    const task = await Task.create({ title, description });
+    return { task, status: 201 };
+  }
+};

package/src/templates/api-rest/src/services/auth/auth.js

@@ -0,0 +1,9 @@
+// Used by the better-auth CLI (`npx @better-auth/cli generate|migrate`) to
+// discover your auth configuration.
+const AuthService = require('./index.js');
+
+const auth = new AuthService({
+  get: () => {},
+});
+
+module.exports = auth.auth;

package/src/templates/api-rest/src/services/auth/index.js

@@ -0,0 +1,23 @@
+const { AuthService } = require('zyket');
+
+module.exports = class CustomAuthService extends AuthService {
+  // This API does not use organizations/multi-tenancy.
+  get organizationEnabled() {
+    return false;
+  }
+
+  // Set to true once you wire a real email provider below.
+  get requireEmailVerification() {
+    return false;
+  }
+
+  async sendResetPasswordEmail({ user, url }) {
+    // TODO: integrate your email provider. Logged for local development.
+    this.client && console.log(`[auth] Reset password for ${user.email}: ${url}`);
+  }
+
+  async sendVerificationEmail({ user, url }) {
+    // TODO: integrate your email provider. Logged for local development.
+    console.log(`[auth] Verify email for ${user.email}: ${url}`);
+  }
+};

package/src/templates/realtime-chat/.env.example

@@ -0,0 +1,26 @@
+# --- realtime-chat template ---
+DEBUG=true
+PORT=3000
+
+# HTTP (/api/auth), the socket server and the Vite frontend.
+DISABLE_EXPRESS=false
+DISABLE_SOCKET=false
+DISABLE_VITE=false
+VITE_ROOT=./frontend
+VITE_PORT=5173
+VITE_API_BASE=http://localhost:3000
+
+# Set true only when frontend and backend live on different domains (needs HTTPS).
+# AUTH_CROSS_DOMAIN=false
+
+DATABASE_URL=./database.sqlite
+DATABASE_DIALECT=sqlite
+
+SOCKET_MAX_HTTP_BUFFER_SIZE=10485760
+
+# Optional: scale Socket.IO across instances with a Redis adapter
+# REDIS_URL=redis://localhost:6379
+
+# AUTH_SECRET is generated automatically on first run.
+# BETTER_AUTH_URL=http://localhost:3000
+# TRUSTED_ORIGINS=http://localhost:3000

package/src/templates/realtime-chat/README.md

@@ -0,0 +1,38 @@
+# realtime-chat template
+
+Authenticated real-time chat over Socket.IO. Sessions come from better-auth
+(cookie sent during the websocket handshake), so only logged-in users can
+connect or send messages.
+
+## What's included
+- `src/services/auth/` — email/password auth service.
+- `src/guards/auth.js` — reuses the framework `AuthGuard` (session check per event).
+- `src/handlers/connection.js` — enforces auth on connect, joins the `general` room.
+- `src/handlers/message.js` — broadcasts `message` events to the room (guarded by `auth`).
+- `frontend/` — React + Vite chat UI (login/register + live chat over Socket.IO).
+
+## Setup
+```bash
+npm install
+npx @better-auth/cli migrate
+node index.js
+```
+This starts the API + websocket server on `:3000` and the Vite frontend on `:5173`.
+Open http://localhost:5173, register a user, and start chatting (open two
+browsers/users to see real-time delivery).
+
+## How auth works here
+1. The frontend signs in via better-auth → receives the session cookie.
+2. The Socket.IO client connects with `withCredentials: true`; the cookie travels in the handshake.
+3. `connection.js` validates the session and disconnects unauthenticated sockets.
+
+## Cookies & local dev
+Cookie security is now environment-aware (see the framework auth service):
+- **Local dev** (default): `sameSite=lax`, not `secure` → works over `http://localhost`
+  because the Vite frontend (`:5173`) and API (`:3000`) are same-site.
+- **Cross-domain** front/back in production: set `AUTH_CROSS_DOMAIN=true` (requires HTTPS)
+  to switch to `sameSite=none; secure`.
+
+## Notes
+- Set `REDIS_URL` to broadcast across multiple instances.
+- `VITE_API_BASE` (frontend `.env`) points the UI at the backend; defaults to `http://localhost:3000`.

package/src/templates/realtime-chat/frontend/.env.example

@@ -0,0 +1,3 @@
+# Vite reads env from the frontend folder. Copy to frontend/.env if your
+# backend is not on http://localhost:3000.
+VITE_API_BASE=http://localhost:3000

package/src/templates/realtime-chat/frontend/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Zyket Chat</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.jsx"></script>
+  </body>
+</html>

package/src/templates/realtime-chat/frontend/main.jsx

@@ -0,0 +1,18 @@
+import { createRoot } from 'react-dom/client'
+import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom'
+import './styles.css'
+import AuthView from './src/views/AuthView'
+import ChatView from './src/views/ChatView'
+import LoggedMiddleware from './src/middlewares/LoggedMiddleware'
+import NotLoggedMiddleware from './src/middlewares/NotLoggedMiddleware'
+
+createRoot(document.getElementById('root')).render(
+  <BrowserRouter>
+    <Routes>
+      <Route path="/" element={<Navigate to="/chat" replace />} />
+      <Route path="/auth" element={<NotLoggedMiddleware><AuthView /></NotLoggedMiddleware>} />
+      <Route path="/chat" element={<LoggedMiddleware><ChatView /></LoggedMiddleware>} />
+      <Route path="*" element={<Navigate to="/chat" replace />} />
+    </Routes>
+  </BrowserRouter>
+)

package/src/templates/realtime-chat/frontend/src/hooks/useAuth.jsx

@@ -0,0 +1,27 @@
+import { useStoreAuth } from "../store/storeAuth";
+
+export default function useAuth() {
+  const context = useStoreAuth();
+  const sessionContext = context?.client?.useSession();
+  const { isPending, refetch } = sessionContext || {};
+  const { user, session } = sessionContext?.data || {};
+
+  const login = async (email, password) => {
+    const { data, error } = await context.client.signIn.email({ email, password });
+    if (error) throw error;
+    return data;
+  };
+
+  const register = async ({ email, password, name }) => {
+    const { data, error } = await context.client.signUp.email({ email, password, name });
+    if (error) throw error;
+    return data;
+  };
+
+  const logout = async () => {
+    await context.client.signOut();
+    window.location.href = "/auth";
+  };
+
+  return { ...context, login, register, logout, isPending, refetch, user, session };
+}

package/src/templates/realtime-chat/frontend/src/hooks/useChatSocket.jsx

@@ -0,0 +1,29 @@
+import { useEffect, useRef, useState } from "react";
+import { io } from "socket.io-client";
+import { useStoreAuth } from "../store/storeAuth";
+
+// Connects to the Socket.IO server with the session cookie (withCredentials).
+export default function useChatSocket() {
+  const { apiBase } = useStoreAuth();
+  const socketRef = useRef(null);
+  const [messages, setMessages] = useState([]);
+  const [connected, setConnected] = useState(false);
+
+  useEffect(() => {
+    const socket = io(apiBase, { withCredentials: true });
+    socketRef.current = socket;
+
+    socket.on("connect", () => setConnected(true));
+    socket.on("disconnect", () => setConnected(false));
+    socket.on("message", (m) => setMessages((prev) => [...prev, m]));
+
+    return () => socket.disconnect();
+  }, [apiBase]);
+
+  const send = (text) =>
+    new Promise((resolve) => {
+      socketRef.current?.emit("message", { text }, resolve);
+    });
+
+  return { messages, connected, send };
+}

package/src/templates/realtime-chat/frontend/src/middlewares/LoggedMiddleware.jsx

@@ -0,0 +1,12 @@
+import PropTypes from "prop-types";
+import { Navigate } from "react-router-dom";
+import useAuth from "../hooks/useAuth";
+
+export default function LoggedMiddleware({ children }) {
+  const { user, isPending } = useAuth();
+  if (isPending) return null;
+  if (!user) return <Navigate to="/auth" replace />;
+  return children;
+}
+
+LoggedMiddleware.propTypes = { children: PropTypes.node.isRequired };

package/src/templates/realtime-chat/frontend/src/middlewares/NotLoggedMiddleware.jsx

@@ -0,0 +1,12 @@
+import PropTypes from "prop-types";
+import { Navigate } from "react-router-dom";
+import useAuth from "../hooks/useAuth";
+
+export default function NotLoggedMiddleware({ children }) {
+  const { user, isPending } = useAuth();
+  if (isPending) return null;
+  if (user) return <Navigate to="/chat" replace />;
+  return children;
+}
+
+NotLoggedMiddleware.propTypes = { children: PropTypes.node.isRequired };

package/src/templates/realtime-chat/frontend/src/store/storeAuth.jsx

@@ -0,0 +1,11 @@
+import { create } from "zustand";
+import { createAuthClient } from "better-auth/react";
+
+const API_BASE = import.meta.env.VITE_API_BASE || "http://localhost:3000";
+
+export const useStoreAuth = create(() => ({
+  apiBase: API_BASE,
+  client: createAuthClient({
+    baseURL: `${API_BASE}/api/auth/`,
+  }),
+}));

package/src/templates/realtime-chat/frontend/src/views/AuthView.jsx

@@ -0,0 +1,70 @@
+import { useState } from "react";
+import { useNavigate } from "react-router-dom";
+import useAuth from "../hooks/useAuth";
+
+export default function AuthView() {
+  const { login, register } = useAuth();
+  const navigate = useNavigate();
+  const [mode, setMode] = useState("login");
+  const [form, setForm] = useState({ name: "", email: "", password: "" });
+  const [error, setError] = useState(null);
+  const [loading, setLoading] = useState(false);
+
+  const submit = async (e) => {
+    e.preventDefault();
+    setError(null);
+    setLoading(true);
+    try {
+      if (mode === "login") await login(form.email, form.password);
+      else await register(form);
+      navigate("/chat", { replace: true });
+    } catch (err) {
+      setError(err?.message || "Authentication failed");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const field = (key, type = "text", placeholder = "") => (
+    <input
+      type={type}
+      placeholder={placeholder}
+      value={form[key]}
+      onChange={(e) => setForm({ ...form, [key]: e.target.value })}
+      className="w-full px-4 py-2 rounded-lg bg-zinc-800 border border-zinc-700 text-white outline-none focus:border-orange-500"
+      required
+    />
+  );
+
+  return (
+    <div className="min-h-screen bg-zinc-950 text-white flex items-center justify-center p-4">
+      <form onSubmit={submit} className="w-full max-w-sm space-y-4 bg-zinc-900 p-8 rounded-2xl border border-zinc-800">
+        <h1 className="text-2xl font-bold text-center">
+          {mode === "login" ? "Sign in" : "Create account"}
+        </h1>
+
+        {mode === "register" && field("name", "text", "Name")}
+        {field("email", "email", "Email")}
+        {field("password", "password", "Password")}
+
+        {error && <p className="text-sm text-red-400">{error}</p>}
+
+        <button
+          type="submit"
+          disabled={loading}
+          className="w-full py-2 rounded-lg bg-orange-500 text-black font-semibold disabled:opacity-50"
+        >
+          {loading ? "..." : mode === "login" ? "Sign in" : "Sign up"}
+        </button>
+
+        <button
+          type="button"
+          onClick={() => setMode(mode === "login" ? "register" : "login")}
+          className="w-full text-sm text-zinc-400 hover:text-white"
+        >
+          {mode === "login" ? "Need an account? Sign up" : "Have an account? Sign in"}
+        </button>
+      </form>
+    </div>
+  );
+}

package/src/templates/realtime-chat/frontend/src/views/ChatView.jsx

@@ -0,0 +1,69 @@
+import { useState, useRef, useEffect } from "react";
+import useAuth from "../hooks/useAuth";
+import useChatSocket from "../hooks/useChatSocket";
+
+export default function ChatView() {
+  const { user, logout } = useAuth();
+  const { messages, connected, send } = useChatSocket();
+  const [text, setText] = useState("");
+  const bottomRef = useRef(null);
+
+  useEffect(() => {
+    bottomRef.current?.scrollIntoView({ behavior: "smooth" });
+  }, [messages]);
+
+  const onSend = async (e) => {
+    e.preventDefault();
+    const value = text.trim();
+    if (!value) return;
+    setText("");
+    await send(value);
+  };
+
+  return (
+    <div className="min-h-screen bg-zinc-950 text-white flex flex-col">
+      <header className="flex items-center justify-between px-6 py-4 border-b border-zinc-800">
+        <div className="flex items-center gap-3">
+          <span className="font-bold">#general</span>
+          <span className={`text-xs ${connected ? "text-green-400" : "text-zinc-500"}`}>
+            {connected ? "● online" : "○ connecting…"}
+          </span>
+        </div>
+        <div className="flex items-center gap-3 text-sm">
+          <span className="text-zinc-400">{user?.name || user?.email}</span>
+          <button onClick={logout} className="text-zinc-400 hover:text-white">Logout</button>
+        </div>
+      </header>
+
+      <main className="flex-1 overflow-auto px-6 py-4 space-y-3">
+        {messages.length === 0 && (
+          <p className="text-zinc-600 text-sm">No messages yet. Say hi 👋</p>
+        )}
+        {messages.map((m) => {
+          const mine = m.user?.id === user?.id;
+          return (
+            <div key={m.id} className={`flex ${mine ? "justify-end" : "justify-start"}`}>
+              <div className={`max-w-md px-4 py-2 rounded-2xl ${mine ? "bg-orange-500 text-black" : "bg-zinc-800"}`}>
+                {!mine && <p className="text-xs text-zinc-400 mb-0.5">{m.user?.name}</p>}
+                <p className="text-sm break-words">{m.text}</p>
+              </div>
+            </div>
+          );
+        })}
+        <div ref={bottomRef} />
+      </main>
+
+      <form onSubmit={onSend} className="flex gap-2 px-6 py-4 border-t border-zinc-800">
+        <input
+          value={text}
+          onChange={(e) => setText(e.target.value)}
+          placeholder="Type a message…"
+          className="flex-1 px-4 py-2 rounded-lg bg-zinc-800 border border-zinc-700 outline-none focus:border-orange-500"
+        />
+        <button type="submit" className="px-5 py-2 rounded-lg bg-orange-500 text-black font-semibold">
+          Send
+        </button>
+      </form>
+    </div>
+  );
+}

package/src/templates/realtime-chat/frontend/styles.css

@@ -0,0 +1 @@
+@import "tailwindcss";

package/src/templates/realtime-chat/frontend/vite.config.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+})

package/src/templates/realtime-chat/index.js

@@ -0,0 +1,14 @@
+const { Kernel } = require('zyket');
+
+const kernel = new Kernel({
+  services: [
+    ['auth', require('./src/services/auth'), ['@service_container']],
+  ],
+});
+
+kernel.boot().then(async () => {
+  await kernel.container.get('database').sync();
+  kernel.container.get('logger').info('realtime-chat template ready (ws + http)');
+}).catch((error) => {
+  console.error('Error booting kernel:', error);
+});

package/src/templates/realtime-chat/src/guards/auth.js

@@ -0,0 +1,3 @@
+// Reuse the framework's session-based socket guard.
+// Referenced from handlers via `guards = ["auth"];`
+module.exports = require('zyket').AuthGuard;

package/src/templates/realtime-chat/src/handlers/connection.js

@@ -0,0 +1,23 @@
+const { Handler } = require('zyket');
+
+// The connection handler enforces auth on connect: throwing here disconnects
+// the socket (see the SocketIO service). Authenticated sockets join the room.
+module.exports = class ConnectionHandler extends Handler {
+  async handle({ container, socket }) {
+    const session = await container.get('auth').getSession(socket.handshake.headers);
+
+    if (!session || !session.user) {
+      throw new Error('Unauthorized'); // disconnects the socket
+    }
+
+    socket.data.user = session.user;
+    socket.data.session = session.session;
+    socket.join('general');
+
+    container.get('logger').info(`Chat: ${session.user.email} connected (${socket.id})`);
+    socket.emit('welcome', {
+      room: 'general',
+      user: { id: session.user.id, name: session.user.name },
+    });
+  }
+};

package/src/templates/realtime-chat/src/handlers/message.js

@@ -0,0 +1,29 @@
+const { Handler } = require('zyket');
+
+// Handles `socket.emit("message", { text })`. The `auth` guard re-validates the
+// session before every message (defense in depth) and re-attaches the user.
+module.exports = class MessageHandler extends Handler {
+  guards = ['auth'];
+
+  async handle({ container, socket, data, io }) {
+    const user = socket.data.user;
+    const text = String(data?.text || '').trim().slice(0, 2000);
+
+    if (!text) {
+      return { error: 'Empty message' };
+    }
+
+    const message = {
+      id: `${Date.now()}-${socket.id}`,
+      text,
+      user: { id: user.id, name: user.name },
+      at: new Date().toISOString(),
+    };
+
+    // Broadcast to everyone in the room (including sender).
+    io.to('general').emit('message', message);
+
+    container.get('logger').debug(`Chat message from ${user.email}`);
+    return { ok: true, message };
+  }
+};

package/src/templates/realtime-chat/src/services/auth/auth.js

@@ -0,0 +1,8 @@
+// Used by the better-auth CLI (`npx @better-auth/cli generate|migrate`).
+const AuthService = require('./index.js');
+
+const auth = new AuthService({
+  get: () => {},
+});
+
+module.exports = auth.auth;

package/src/templates/realtime-chat/src/services/auth/index.js

@@ -0,0 +1,19 @@
+const { AuthService } = require('zyket');
+
+module.exports = class CustomAuthService extends AuthService {
+  get organizationEnabled() {
+    return false;
+  }
+
+  get requireEmailVerification() {
+    return false;
+  }
+
+  async sendResetPasswordEmail({ user, url }) {
+    console.log(`[auth] Reset password for ${user.email}: ${url}`);
+  }
+
+  async sendVerificationEmail({ user, url }) {
+    console.log(`[auth] Verify email for ${user.email}: ${url}`);
+  }
+};