@shaferllc/keel 0.59.0 → 0.68.0

package/docs/scheduling.md

@@ -0,0 +1,110 @@
+# Task Scheduling
+
+Declare recurring work with a fluent cadence, then let a **single cron trigger**
+drive it — a code-defined scheduler, edge-first. Instead of a crontab entry per
+job, you register tasks in code and run the scheduler once a minute; it runs
+whatever's due.
+
+## Scheduling tasks
+
+A task is a [`Job`](./queues.md) or a plain function. Register it, then set the
+cadence:
+
+```ts
+import { schedule } from "@shaferllc/keel/core";
+
+schedule(new PruneSessions()).daily();
+schedule(() => syncInventory()).everyFiveMinutes();
+schedule(new SendDigest()).cron("0 9 * * 1"); // 9am Mondays
+```
+
+### Cadences
+
+```ts
+task.everyMinute();
+task.everyFiveMinutes();   // and Ten / Fifteen / Thirty
+task.hourly();
+task.hourlyAt(15);         // :15 past every hour
+task.daily();
+task.dailyAt("13:30");
+task.weekly(1);            // Monday (0 = Sunday) at midnight
+task.monthly(15);          // the 15th at midnight
+task.cron("*/10 9-17 * * 1-5"); // any 5-field cron expression
+```
+
+## Running the scheduler
+
+Run the scheduler once a minute from a cron trigger; `runDue(now)` runs every task
+whose expression matches `now` (to the minute).
+
+### Cloudflare (Cron Triggers)
+
+Add a trigger to `wrangler.jsonc` (`"triggers": { "crons": ["* * * * *"] }`) and
+call the scheduler from the Worker's `scheduled` handler:
+
+```ts
+export default {
+  async scheduled(event, env, ctx) {
+    ctx.waitUntil(scheduler().runDue(new Date(event.scheduledTime)));
+  },
+};
+```
+
+### Node
+
+```ts
+setInterval(() => scheduler().runDue(new Date()), 60_000);
+```
+
+Because the scheduler decides what's due, you only ever wire **one** trigger, no
+matter how many tasks you schedule.
+
+## Inspecting
+
+`scheduler().due(now)` returns the due tasks without running them, and every task
+has an `expression` and optional `name`:
+
+```ts
+schedule(job).named("prune-sessions").daily();
+for (const t of scheduler().due(new Date())) logger().info("due", { task: t.name });
+```
+
+## API reference
+
+### `schedule(job)`
+
+`schedule(job: Job | (() => void | Promise<void>)): ScheduledTask`
+
+Registers a task on the default scheduler and returns it for cadence
+configuration.
+
+### `scheduler()` / `setScheduler(next)`
+
+The default `Scheduler`; `setScheduler` replaces it (reset between tests).
+
+### `ScheduledTask`
+
+Returned by `schedule`. Cadence setters return `this` (chainable):
+`everyMinute` / `everyFiveMinutes` / `everyTenMinutes` / `everyFifteenMinutes` /
+`everyThirtyMinutes` / `hourly` / `hourlyAt(m)` / `daily` / `dailyAt("HH:MM")` /
+`weekly(weekday?)` / `monthly(day?)` / `cron(expr)` / `named(name)`. `isDue(now)`
+reports whether it matches a `Date`.
+
+### `Scheduler`
+
+| Method | Notes |
+|--------|-------|
+| `schedule(job)` | register a task |
+| `due(now?)` | the tasks due at `now` (no run) |
+| `runDue(now?)` | run every due task; returns the count |
+| `tasks` | all registered tasks |
+
+### `cronMatches(expression, date)`
+
+`cronMatches(expression: string, date: Date): boolean`
+
+Whether a 5-field cron expression (`min hour dom month dow`) matches `date` to the
+minute. Supports `*`, exact values, lists (`1,15`), ranges (`9-17`), and steps
+(`*/5`, `0-30/10`). Day-of-month and day-of-week follow standard cron: when both
+are restricted, either matching counts. Fields use the `Date`'s own values (UTC in
+a Worker, local under Node).

package/docs/security.md

@@ -0,0 +1,85 @@
+# Securing SSR apps
+
+Two middlewares harden server-rendered apps: `securityHeaders()` sets the
+defensive HTTP headers browsers act on, and `csrf()` blocks cross-site form
+submissions. (For cross-origin API access, see [CORS](./cors.md).)
+
+## Security headers
+
+`securityHeaders()` sets a Content-Security-Policy, HSTS, and the clickjacking /
+MIME-sniffing / referrer guards in one place:
+
+```ts
+import { securityHeaders } from "@shaferllc/keel/core";
+
+this.use(securityHeaders()); // sensible defaults
+
+this.use(
+  securityHeaders({
+    csp: { defaultSrc: ["'self'"], scriptSrc: ["'self'", "https://cdn.example.com"] },
+    hsts: { maxAge: 15552000, includeSubDomains: true },
+    frameGuard: "DENY",
+  }),
+);
+```
+
+| Option | Header | Default |
+|--------|--------|---------|
+| `csp` | `Content-Security-Policy` | off (opt-in) |
+| `hsts` | `Strict-Transport-Security` | off (opt-in) |
+| `frameGuard` | `X-Frame-Options` | `"SAMEORIGIN"` |
+| `noSniff` | `X-Content-Type-Options: nosniff` | on |
+| `referrerPolicy` | `Referrer-Policy` | `strict-origin-when-cross-origin` |
+
+Set any of these to `false` to omit the header. `csp` accepts a ready-made string
+or a **directives object** whose camelCase keys become the kebab-case spelling
+(`defaultSrc` → `default-src`, `scriptSrc` → `script-src`).
+
+**HSTS is sticky** — once a browser sees it, it refuses plain HTTP for `maxAge`
+seconds. Only enable it once HTTPS works everywhere, and start with a short
+`maxAge` (say a day) while you test.
+
+## CSRF protection
+
+`csrf()` guards against forged form submissions. It keeps a token in the
+[session](./sessions.md) and rejects any `POST`/`PUT`/`PATCH`/`DELETE` that
+doesn't echo it back — with `419 Page Expired`. It needs `sessionMiddleware()`
+installed first:
+
+```ts
+import { sessionMiddleware, csrf } from "@shaferllc/keel/core";
+
+this.use(sessionMiddleware());
+this.use(csrf());
+```
+
+### In forms
+
+Drop `csrfField()` into any form — it renders a hidden `_token` input:
+
+```ts
+import { csrfField } from "@shaferllc/keel/core";
+
+`<form method="POST" action="/posts">
+  ${csrfField()}
+  <button>Save</button>
+</form>`
+```
+
+Or read the raw token with `csrfToken()` to place it yourself.
+
+### In SPAs
+
+`csrf()` also writes a readable `XSRF-TOKEN` cookie. Axios and most fetch wrappers
+send it back automatically as the `X-XSRF-TOKEN` header, so AJAX requests are
+covered with no extra code. The token is accepted from the `X-CSRF-Token` /
+`X-XSRF-Token` header or a `_token` / `_csrf` body field.
+
+### Exempting routes
+
+Webhooks and provider callbacks can't send your token — exempt them (a trailing
+`*` matches a prefix):
+
+```ts
+this.use(csrf({ except: ["/webhooks/*", "/payments/callback"] }));
+```

package/docs/sessions.md

@@ -0,0 +1,354 @@
+# Sessions
+
+Keel ships a cookie-backed session store. There's no external service to run, so
+it works the same on Node and on the edge. Session data lives in an HTTP-only
+cookie: the middleware reads it before your handler runs and writes it back
+afterward.
+
+> **The cookie is base64-encoded, not signed or encrypted.** Anyone can decode
+> and forge it. Keep secrets out of the session (store an id, not a password
+> hash or a role you trust for authorization on its own), and set
+> `cookie: { secure: true }` in production so it's only sent over HTTPS.
+
+## Enable it
+
+Add the middleware to your HTTP kernel:
+
+```ts
+import { HttpKernel, sessionMiddleware } from "@shaferllc/keel/core";
+
+export class Kernel extends HttpKernel {
+  constructor(app: Application) {
+    super(app);
+    this.use(sessionMiddleware());
+    // options: sessionMiddleware({ cookieName: "sid", cookie: { secure: true } })
+  }
+}
+```
+
+The cookie is named `keel_session` by default and is written `httpOnly`,
+`path: "/"`, `sameSite: "Lax"`. Anything you pass in `cookie` is merged over
+those defaults, so `cookie: { secure: true }` adds the `Secure` flag while
+keeping the rest.
+
+## Use it
+
+Reach the session anywhere with `session()`:
+
+```ts
+import { session } from "@shaferllc/keel/core";
+
+session().put("userId", user.id);
+const id = session().get("userId");
+const id2 = session().get("userId", null); // with a fallback
+
+session().has("userId");
+session().forget("userId");
+session().pull("cart");      // read and remove
+session().increment("visits");
+session().clear();
+session().all();
+```
+
+`session()` returns a fresh `Session` wrapper each call, but every wrapper points
+at the *same* underlying data object stashed on the request context — so writes
+made through one call are visible through the next. There's no need to hold onto
+the instance:
+
+```ts
+session().put("step", 1);
+session().get("step"); // 1 — same request, same data
+```
+
+Calling `session()` without `sessionMiddleware()` installed throws
+`Session is not available. Add sessionMiddleware() to your HTTP kernel.` — the
+guard is there so a missing middleware fails loudly instead of silently dropping
+writes.
+
+## Flash messages
+
+Flash data survives exactly one request — perfect for post-redirect messages:
+
+```ts
+// during a request that redirects
+session().flash("status", "Profile saved!");
+return redirect("/profile");
+
+// on the next request
+session().flashed("status");     // "Profile saved!"
+session().flashed("status");     // still there this request…
+// …gone on the request after
+```
+
+Flash and the values you `put` live in separate compartments. `flash(key, …)`
+writes to a pending-flash bucket; `flashed(key)` reads the bucket that was
+flashed on the *previous* request. So within the request that calls `flash`, a
+`flashed` for the same key won't see it yet — it lands on the next request:
+
+```ts
+session().flash("status", "Saved!");
+session().flashed("status"); // undefined — not flashed until next request
+session().get("status");     // undefined — flash isn't a normal key
+```
+
+`all()` returns only your own keys — the internal flash and "old flash" buckets
+are filtered out, so they never leak into a template's session dump.
+
+## Counters
+
+`increment` and `decrement` treat a missing key as `0` and step by `1` (or any
+amount you pass):
+
+```ts
+session().increment("visits");      // 0 -> 1
+session().increment("credits", 10); // += 10
+session().decrement("credits", 3);  // -= 3
+```
+
+Both coerce the stored value to a number, so seeding a counter with a non-numeric
+value will produce `NaN` — keep counters numeric.
+
+## How it works
+
+`sessionMiddleware()` reads the session cookie before your handler runs and
+writes it back afterward. Data is JSON, base64-encoded into the cookie. On each
+request it rotates flash: last request's pending flash becomes this request's
+"old" (what `flashed` reads), and a fresh empty flash bucket starts. After your
+handler returns, the "old" bucket is dropped and the cookie is rewritten — so a
+value only ever survives one hop.
+
+Because it's cookie-backed there's a ~4KB size budget — keep sessions small (an
+id, a few flags), not whole objects. For larger sessions, swap in your own
+middleware that persists to a store and stashes the data on the context under the
+`"session"` key the same way.
+
+> **Latin1 only.** Values are serialized with `btoa`, which throws on characters
+> outside the Latin1 range. A flash message or stored string containing an emoji
+> or many non-Latin scripts will throw `InvalidCharacterError` when the cookie is
+> written. Keep session values ASCII/Latin1, or encode them yourself first.
+
+## Related
+
+Sessions underpin [authentication](./authentication.md) — the auth layer stores
+the logged-in user's id in the session. Install `sessionMiddleware()` before any
+middleware that reads the session.
+
+---
+
+## API reference
+
+### `session()`
+
+`session(): Session`
+
+Returns the current request's `Session`, wrapping the data on the request
+context.
+
+```ts
+session().put("userId", 1);
+```
+
+**Notes:** throws `Session is not available…` if `sessionMiddleware()` isn't
+installed (no `"session"` on the context). Returns a new wrapper each call, but
+all wrappers share the same underlying data for the request, so writes persist
+across calls.
+
+### `sessionMiddleware(options?)`
+
+`sessionMiddleware(options?: SessionOptions): MiddlewareHandler`
+
+Builds the middleware that loads the session from its cookie before the request
+and writes it back after. Register it in your HTTP kernel.
+
+```ts
+this.use(sessionMiddleware({ cookieName: "sid", cookie: { secure: true } }));
+```
+
+**Notes:** cookie name defaults to `"keel_session"`. A missing or malformed
+cookie starts an empty session (parse errors are swallowed — "tampered/expired,
+start fresh"). The write applies `httpOnly`, `path: "/"`, `sameSite: "Lax"`,
+merged with (and overridable by) `options.cookie`. Rotates flash on every
+request.
+
+### `Session`
+
+The wrapper `session()` returns. You don't construct it directly in app code
+(the middleware and `session()` build it), though its constructor takes the raw
+data object. Mutating methods return `this`, so they chain.
+
+#### `all()`
+
+`all(): SessionData`
+
+Returns every key you've stored, excluding the internal flash/old-flash buckets.
+
+```ts
+const data = session().all(); // Record<string, unknown>
+```
+
+**Notes:** `SessionData` is `Record<string, unknown>`. A shallow copy of the
+public keys — mutating the result doesn't write back to the session.
+
+#### `get(key, fallback?)`
+
+`get<T = unknown>(key: string, fallback?: T): T`
+
+Reads a value, returning `fallback` when the key is absent.
+
+```ts
+const id = session().get<number>("userId");
+const theme = session().get("theme", "light");
+```
+
+**Notes:** presence is checked with `key in data`, so a key explicitly set to
+`null` returns `null` (not the fallback). The `T` type parameter is an unchecked
+cast — it doesn't validate the runtime value.
+
+#### `put(key, value)`
+
+`put(key: string, value: unknown): this`
+
+Stores a value under `key`.
+
+```ts
+session().put("userId", user.id).put("theme", "dark");
+```
+
+**Notes:** chainable. Values must be JSON-serializable (they're `JSON.stringify`d
+into the cookie) and Latin1 once stringified.
+
+#### `set(key, value)`
+
+`set(key: string, value: unknown): this`
+
+Alias for `put`.
+
+```ts
+session().set("locale", "en");
+```
+
+#### `has(key)`
+
+`has(key: string): boolean`
+
+`true` when the key is present *and* non-null.
+
+```ts
+if (session().has("userId")) { /* logged in */ }
+```
+
+**Notes:** returns `false` for a key set to `null` or `undefined`, even though
+`get` would still return that stored `null`.
+
+#### `forget(key)`
+
+`forget(key: string): this`
+
+Deletes a key.
+
+```ts
+session().forget("userId");
+```
+
+#### `pull(key, fallback?)`
+
+`pull<T = unknown>(key: string, fallback?: T): T`
+
+Reads a value and removes it in one step (`get` + `forget`).
+
+```ts
+const cart = session().pull("cart", []);
+```
+
+**Notes:** returns `fallback` when absent, same rules as `get`. Useful for
+one-shot values you don't want lingering.
+
+#### `increment(key, by?)`
+
+`increment(key: string, by = 1): this`
+
+Adds `by` to a numeric value, treating a missing key as `0`.
+
+```ts
+session().increment("visits");
+session().increment("credits", 25);
+```
+
+**Notes:** coerces the current value with `as number` — non-numeric stored values
+yield `NaN`. Chainable.
+
+#### `decrement(key, by?)`
+
+`decrement(key: string, by = 1): this`
+
+Subtracts `by` from a numeric value (`increment` by `-by`).
+
+```ts
+session().decrement("credits", 3);
+```
+
+#### `clear()`
+
+`clear(): this`
+
+Removes every key, including the flash buckets.
+
+```ts
+session().clear();
+```
+
+**Notes:** deletes all keys off the underlying data object, so it also wipes
+pending and old flash. Use to reset on logout.
+
+#### `flash(key, value)`
+
+`flash(key: string, value: unknown): this`
+
+Stores a value that survives only the *next* request.
+
+```ts
+session().flash("status", "Profile saved!");
+```
+
+**Notes:** writes to a separate flash bucket, not the normal keyspace — `get`
+and `all` won't see it. Read it next request with `flashed`. Chainable.
+
+#### `flashed(key, fallback?)`
+
+`flashed<T = unknown>(key: string, fallback?: T): T`
+
+Reads a value flashed on the *previous* request.
+
+```ts
+const status = session().flashed("status");
+const msg = session().flashed("msg", "");
+```
+
+**Notes:** reads the "old" bucket the middleware rotated in at the start of the
+request. A value flashed and read in the same request won't appear here (it's not
+yet rotated). Returns `fallback` when absent.
+
+### Interfaces & types
+
+#### `SessionOptions`
+
+```ts
+interface SessionOptions {
+  cookieName?: string;
+  cookie?: CookieOptions; // hono's setCookie options (Parameters<typeof setCookie>[3])
+}
+```
+
+Configures `sessionMiddleware()`. Use it to rename the cookie or set flags like
+`secure`, `maxAge`, or `domain`.
+
+```ts
+sessionMiddleware({
+  cookieName: "sid",
+  cookie: { secure: true, maxAge: 60 * 60 * 24 },
+});
+```
+
+**Notes:** `cookieName` defaults to `"keel_session"`. `cookie` is merged *over*
+the middleware's defaults (`httpOnly`, `path: "/"`, `sameSite: "Lax"`), so you
+can override any of them.