mates-fullstack 1.0.0-beta.1

package/README.md

@@ -0,0 +1,311 @@
+# mates-fullstack
+
+TypeScript-first full-stack framework for Mates apps. It adds SSR, direct RPC-style server functions, raw HTTP escape hatches, WebSockets, static assets, and production builds without requiring a compiler in production.
+
+**Custom SSR engine** — no DOM, no happy-dom, no per-request global patching, fully concurrent. `TemplateResult` objects are serialized directly to HTML using a 300-line pure-JS serializer. No virtual DOM, no fake browser, no overhead per request.
+
+No JSX. No virtual DOM. No Express/Hono/Fastify. Runtime server is pure Node.js (`node:http`). Bundling and TypeScript transforms use esbuild.
+
+---
+
+## Install
+
+```bash
+npm install mates-fullstack-beta mates
+```
+
+Add scripts to your app:
+
+```json
+{
+  "scripts": {
+    "dev": "mates-fullstack dev",
+    "build": "mates-fullstack build",
+    "start": "mates-fullstack start"
+  }
+}
+```
+
+---
+
+## Project structure
+
+`mates-fullstack` is convention-based; no config file is required.
+
+```txt
+my-app/
+  client/
+    App.ts          # SSR root component and client router
+    client.ts       # browser entry; calls renderX(App, ...)
+  server/
+    api/            # RPC functions callable from client imports
+    helpers/        # server-only utilities; never bundled for browser
+    main.ts         # optional middleware registration
+    socket/         # optional WebSocket handlers
+  shared/           # code/types used by both sides
+  public/           # static files copied to dist/public in production
+  package.json
+```
+
+---
+
+## Minimal app
+
+### `client/App.ts`
+
+```ts
+import { html } from "mates";
+
+export default () => {
+  return () => html`<h1>Hello from mates-fullstack</h1>`;
+};
+```
+
+### `client/client.ts`
+
+```ts
+import { renderX } from "mates";
+import App from "./App";
+
+renderX(App, document.getElementById("app")!);
+```
+
+### `server/api/todos.ts`
+
+```ts
+import type { ServerCtx } from "mates-fullstack";
+import { ValidationError } from "mates-fullstack";
+
+export async function listTodos(_payload: {}, _ctx: ServerCtx) {
+  return [{ id: 1, title: "Write docs" }];
+}
+
+export async function addTodo(payload: { title: string }, _ctx: ServerCtx) {
+  if (!payload.title.trim()) {
+    throw new ValidationError("Invalid todo", {
+      fields: { title: "Required" },
+    });
+  }
+  return { id: Date.now(), title: payload.title };
+}
+```
+
+### Client code calls server functions directly
+
+```ts
+import { asyncAction, html } from "mates";
+import { listTodos } from "../server/api/todos";
+
+const TodoPage = () => {
+  const load = asyncAction(() => listTodos({}));
+  load();
+
+  return () => html`
+    <pre>${JSON.stringify(load.data(), null, 2)}</pre>
+  `;
+};
+```
+
+During development and production builds, imports from `server/api/**` are converted into browser-safe RPC stubs. Imports from any other `server/**` path are blocked from client code.
+
+---
+
+## Commands
+
+```bash
+npm run dev      # native ESM dev server, no browser bundle
+npm run build    # production client bundle + compiled server runtime
+npm run start    # start production server from dist/
+```
+
+### Development mode
+
+Development intentionally serves source modules instead of a client bundle:
+
+- app source modules: `/_src/**`
+- package modules: `/_pkg/**`  
+- framework helpers: `/_mates/**`
+- import map injected into the HTML shell
+- chokidar watches `client/`, `server/`, `shared/`, `public/`, `.env*`, and config files
+- reload generation is owned by the parent dev process and delivered through SSE
+
+This makes stack traces point at source-like module URLs and keeps rebuilds fast.
+
+---
+
+## Authentication
+
+### Email/Password + Social Login
+
+`mates-fullstack` provides a complete auth system out of the box. Access tokens are short-lived (15 min default), stored in httpOnly cookies. Refresh tokens (30 days) live in a separate httpOnly cookie and rotate automatically, with JTI replay detection.
+
+```ts
+// server/main.ts
+import { matesAuth, auth, useArctic } from "mates-fullstack";
+
+matesAuth({ secret: process.env.AUTH_JWT_SECRET! });
+
+useArctic({
+  google: {
+    clientId: process.env.GOOGLE_CLIENT_ID!,
+    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    onSuccess: async (profile, ctx) => {
+      const user = await db.users.upsert({ ... });
+      await auth.login(ctx, { userId: user.id, email: user.email });
+    },
+  },
+});
+```
+
+Routes `/auth/google` and `/auth/google/callback` are registered automatically. `onSuccess` gives you full control — call `auth.login()` to issue tokens, or skip it to just link accounts.
+
+10 built-in OAuth providers: Google, GitHub, Discord, Microsoft, Twitter, LinkedIn, Facebook, Apple, Spotify, GitLab. Custom providers via `arcticProvider({ handler, ... })`.
+
+### Cross-Domain SSO
+
+For apps on different domains sharing one auth server. The auth server signs a 30-second code JWT with a shared secret — each app verifies it locally, no round-trip needed.
+
+```ts
+// auth.com/server/main.ts
+import { useSsoProvider } from "mates-fullstack";
+
+useSsoProvider({
+  secret: process.env.SSO_SECRET!,
+  login: "/login",
+  allowedOrigins: ["https://app1.com", "https://app2.com"],
+});
+
+// app1.com/server/main.ts
+import { useSsoClient } from "mates-fullstack";
+
+useSsoClient({
+  authUrl: "https://auth.com",
+  secret: process.env.SSO_SECRET!,
+  protected: ["/dashboard", "/settings"],
+});
+```
+
+Each app issues its own httpOnly session cookies. Works with social login — put `useArctic()` on the auth server, `useSsoClient()` on every app.
+
+---
+
+## Middleware
+
+All middleware registers globally in `server/main.ts` and runs in registration order.
+
+**Recommended `server/main.ts`:**
+```ts
+import {
+  matesAuth, requestLogger, useSecurityHeaders, useCors, rateLimit,
+} from "mates-fullstack";
+
+matesAuth({ secret: process.env.AUTH_JWT_SECRET! });
+requestLogger({ skip: [/^\/health$/, /^\/_mates\//] });
+useSecurityHeaders();
+useCors({ origins: "https://app.example.com" });
+rateLimit({ max: 10, window: "15m", pathPrefix: "/auth" });
+rateLimit({ max: 300, window: "1m" });
+```
+
+### Request Logger
+
+```ts
+requestLogger({ skip: [/^\/health$/, /^\/assets\//] });
+```
+
+Logs every request (method, path, IP) on arrival and every RPC response (status, ms) on completion. Stamps `x-request-id` on every response. Structured logging — NDJSON in production, pretty-printed in dev.
+
+### Security Headers
+
+```ts
+useSecurityHeaders();
+useSecurityHeaders({ contentSecurityPolicy: "default-src 'self'", xFrameOptions: "DENY" });
+```
+
+Sets 14 standard security headers on every response — complete helmet-equivalent coverage. Every header individually overridable or disableable. HSTS auto-enabled in production, skipped in dev. CSP and Permissions-Policy are opt-in.
+
+### CORS
+
+```ts
+useCors({ origins: "https://app.example.com", credentials: true });
+useCors({ origins: (origin) => origin.endsWith(".example.com") });
+```
+
+Handles preflight `OPTIONS` automatically (returns 204). Reflects origin when `credentials: true` as required by the CORS spec. Sets `Vary: Origin`.
+
+### Rate Limiting
+
+```ts
+rateLimit({ max: 100, window: "1m" });                             // all routes
+rateLimit({ max: 10, window: "15m", pathPrefix: "/auth" });        // auth only
+rateLimit({ max: 5, window: "1h", key: (_req, ctx) => String(ctx.auth.userId) }); // per-user
+```
+
+Sliding-window counter, in-memory. Returns 429 with `Retry-After` and `X-RateLimit-*` headers. Auto-evicts expired entries. Custom key function for per-user or per-endpoint limiting.
+
+### Raw HTTP hooks
+
+For cases where an external service dictates the HTTP contract (webhooks, custom OAuth flows):
+
+```ts
+import { onHttpRequest } from "mates-fullstack";
+
+onHttpRequest(async (req, ctx) => {
+  const url = new URL(req.url);
+  if (req.method === "POST" && url.pathname === "/stripe-webhook") {
+    const body = await req.text();
+    await handleWebhook(body, ctx.reqHeaders["stripe-signature"]);
+    return new Response("ok");
+  }
+});
+```
+
+---
+
+## Request Limits / Resource Protection
+
+Built-in limits prevent CPU and memory exhaustion. All have safe defaults — override only to tune for your app.
+
+```ts
+// server/main.ts — at the top, before middleware
+import { configureRpcRunner } from "mates-fullstack/internal";
+
+configureRpcRunner({
+  maxJsonBytes: 5 * 1024 * 1024,     // default 1MB
+  maxJsonDepth: 30,                    // default 50
+  maxArrayLength: 5000,                // default 10_000
+  maxStringLength: 50_000,             // default 100_000
+  maxUploadBytes: 50 * 1024 * 1024,   // default 10MB
+  maxMultipartParts: 100,              // default 200
+});
+```
+
+Or set server-level limits when starting:
+
+```ts
+await startServer({
+  maxConnections: 2000,           // default 1000
+  staticStreamTimeout: 120_000,   // default 60s
+  maxSseClients: 1000,            // default 500
+});
+```
+
+All defaults are active without any configuration call. See `DOCS.md` for full details.
+
+---
+
+## Public entrypoints
+
+| Import | Use for |
+|---|---|
+| `mates-fullstack` | stable app API: errors, redirects, middleware registration, `ServerCtx`, validation/sanitize/upload helpers |
+| `mates-fullstack/client` | browser hydration and RPC helpers |
+| `mates-fullstack/browser` | browser-safe error/redirect/stream/download helpers |
+| `mates-fullstack/server` | server-safe helpers and middleware runners |
+| `mates-fullstack/internal` | unstable build/runtime/scanner internals for tooling |
+
+---
+
+## License
+
+MIT

package/dist/arctic-auth.d.ts

@@ -0,0 +1,101 @@
+import { type OAuth2Tokens } from "arctic";
+import type { CookieOptions, Context } from "./ctx.js";
+export type ArcticBuiltInProvider = "apple" | "discord" | "facebook" | "github" | "gitlab" | "google" | "linkedin" | "microsoft" | "spotify" | "twitter";
+export interface ArcticTokenSet {
+    accessToken: string | null;
+    refreshToken: string | null;
+    idToken: string | null;
+    tokenType: string | null;
+    expiresAt: Date | null;
+    scopes: string[] | null;
+    raw: object;
+}
+export interface ArcticProfile<Raw = unknown> {
+    provider: string;
+    id: string;
+    email: string | null;
+    name: string | null;
+    avatar: string | null;
+    username?: string | null;
+    raw: Raw;
+    tokens: ArcticTokenSet;
+}
+export interface ArcticProviderConfig {
+    clientId: string;
+    clientSecret?: string | null;
+    redirectUri?: string;
+    scopes?: string[];
+    /** Microsoft Entra ID tenant. Defaults to "common". */
+    tenant?: string;
+    /** Apple Team ID. */
+    teamId?: string;
+    /** Apple Key ID. */
+    keyId?: string;
+    /** Apple private key in PKCS#8 PEM format. */
+    privateKey?: string;
+    /** GitLab base URL. Defaults to https://gitlab.com. */
+    baseURL?: string;
+    /** Override the built-in profile fetcher or add one for custom providers. */
+    profile?: ArcticProfileLoader;
+    /** Override whether this provider uses PKCE. */
+    usesPKCE?: boolean;
+    /**
+     * Called after the provider returns a profile.
+     * Return the claims to bake into the JWT — typically after an upsert in your DB.
+     */
+    onSuccess: ArcticSuccessHandler;
+}
+export type ArcticProvidersConfig = Partial<Record<ArcticBuiltInProvider | string, ArcticProviderConfig | ArcticCustomProvider>>;
+/**
+ * Called after the provider returns a verified profile.
+ * You are fully in control — call `auth.login(ctx, claims)` to issue tokens,
+ * update the DB to link an account, or do nothing at all.
+ * Return a path string to override the post-OAuth redirect.
+ */
+export type ArcticSuccessHandler = (profile: ArcticProfile, ctx: Context) => string | void | Promise<string | void>;
+export interface ArcticUseOptions {
+    /** Route base for OAuth endpoints. Default: "/auth". */
+    basePath?: string;
+    /** Default redirect after login. Default: "/". */
+    afterLogin?: string;
+    /** Redirect after OAuth failure. If omitted, failures return JSON. */
+    onErrorRedirect?: string;
+    /** Cookie path/domain/sameSite/secure controls for temporary OAuth cookies. */
+    cookie?: Pick<CookieOptions, "path" | "domain" | "sameSite" | "secure">;
+    /** Temporary OAuth state cookie lifetime in seconds. Default: 10 minutes. */
+    stateMaxAge?: number;
+}
+export interface ArcticProviderHandler {
+    defaultScopes: string[];
+    usesPKCE: boolean;
+    start(config: ArcticProviderConfig, redirectUri: string, state: string, codeVerifier: string | null): Promise<URL> | URL;
+    callback(config: ArcticProviderConfig, redirectUri: string, code: string, codeVerifier: string | null, providerName: string): Promise<ArcticProfile>;
+}
+export interface ArcticCustomProvider extends ArcticProviderConfig {
+    handler: ArcticProviderHandler;
+}
+export type ArcticProfileLoader = (tokens: OAuth2Tokens, providerName: string) => Promise<Omit<ArcticProfile, "provider" | "tokens">>;
+/**
+ * Register social login routes for every configured provider.
+ *
+ * The framework automatically handles:
+ *   GET /auth/:provider          — redirect to provider
+ *   GET /auth/:provider/callback — exchange code, call onSuccess, set cookies
+ *
+ * @example
+ * useArctic({
+ *   google: {
+ *     clientId: process.env.GOOGLE_CLIENT_ID!,
+ *     clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ *     onSuccess: async (profile) => {
+ *       const user = await db.upsert({ provider: profile.provider, providerId: profile.id, ... });
+ *       return { userId: user.id, email: user.email, roles: user.roles };
+ *     },
+ *   },
+ * });
+ */
+export declare function useArctic(providers: ArcticProvidersConfig, options?: ArcticUseOptions): void;
+/** Define a custom Arctic provider adapter for providers without a built-in profile normalizer. */
+export declare function arcticProvider(config: ArcticCustomProvider): ArcticCustomProvider;
+export declare function listArcticProviders(): ArcticBuiltInProvider[];
+//# sourceMappingURL=arctic-auth.d.ts.map

package/dist/arctic-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arctic-auth.d.ts","sourceRoot":"","sources":["../src/arctic-auth.ts"],"names":[],"mappings":"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"}