@shaferllc/keel 0.83.2 → 0.83.4

package/docs/hosting.md

@@ -0,0 +1,97 @@
+# Hosting
+
+Keel Hosting is a small toolkit for **hosted Workers / D1 apps**: a Cloudflare
+REST client, hostname helpers, a SQLite-compatible SQL dump, and purpose-scoped
+secret encryption. It ships as `@shaferllc/keel/hosting`.
+
+This is infrastructure — not a control plane. Site orchestration, plans, and
+deploy loops live in your app (for example Keel Cloud).
+
+## Install
+
+```ts
+import {
+  CloudflareClient,
+  cloudflareConfigured,
+  normalizeHostname,
+  isValidHostname,
+  zoneCandidates,
+  dumpConnection,
+  normalizeSecretKey,
+  encryptSecretValue,
+  decryptSecretValue,
+  resolveSecretRows,
+} from "@shaferllc/keel/hosting";
+```
+
+No service provider — import what you need.
+
+## Cloudflare
+
+```ts
+const creds = {
+  accountId: process.env.CF_ACCOUNT_ID!,
+  apiToken: process.env.CF_API_TOKEN!,
+};
+
+if (!cloudflareConfigured(creds)) {
+  throw new Error("Cloudflare credentials missing");
+}
+
+const cf = new CloudflareClient(creds);
+const db = await cf.createD1Database("kc-acme");
+```
+
+Credentials are constructor args — no app config coupling. Optional
+`pinnedZoneId` / `pinnedZoneName` skip a zone lookup when you already know the
+primary zone.
+
+## Hostnames
+
+```ts
+const host = normalizeHostname("https://App.Example.com/"); // "app.example.com"
+isValidHostname(host); // true
+zoneCandidates(host);  // ["app.example.com", "example.com"]
+```
+
+`zoneCandidates` walks from most-specific to apex — useful when attaching a
+Workers Custom Domain and you need to find which zone owns the name.
+
+## SQL dump
+
+Dump any SQLite-compatible `Connection` to a portable `.sql` script (schema +
+data). Useful for export / escape hatches:
+
+```ts
+import { db } from "@shaferllc/keel/core";
+import { dumpConnection } from "@shaferllc/keel/hosting";
+
+const sql = await dumpConnection(db(), "Acme local D1", { generatedBy: "Keel Cloud" });
+// write sql to a .sql file; restore with sqlite3 / D1 import
+```
+
+## Secrets
+
+Encrypt vault values with Keel's purpose-scoped encryption (`config('app.key')`
+must be set). Keys are normalized to `ENV_STYLE` identifiers:
+
+```ts
+const key = normalizeSecretKey("stripe-secret-key"); // "STRIPE_SECRET_KEY"
+const encrypted = await encryptSecretValue(secret, "app-secret");
+const plain = await decryptSecretValue(encrypted, "app-secret");
+
+const env = await resolveSecretRows(
+  [{ key: "STRIPE_SECRET_KEY", value_encrypted: encrypted }],
+  "app-secret",
+);
+// { STRIPE_SECRET_KEY: "…" }
+```
+
+Your app owns the table of rows (`owner_id`, `key`, `value_encrypted`); hosting
+only encrypts and decrypts.
+
+## Related
+
+- [Gates](./gates.md) — private-alpha signup gating used by hosted control planes
+- [Starter kits](./starter-kits.md) — presets Cloud scaffolds from
+- [Building with AI](./ai.md) — MCP Cloud tools (`keel_cloud_*`) that drive hosting

package/llms-full.txt

@@ -4725,6 +4725,35 @@ package, so it always matches your installed version.
 | `keel_list_generators` | The `keel make:*` generators, what they produce, and their flags. |
 | `keel_scaffold` | Generate a controller/provider/middleware/factory/seeder/job/notification/transformer stub. Returns code + target path — it does **not** write to disk. |
 
+When `KEEL_CLOUD_TOKEN` (and optional `KEEL_CLOUD_URL`) is set, Cloud tools are
+also registered:
+
+| Tool | What it does |
+|------|--------------|
+| `keel_cloud_me` | Authenticated Cloud user |
+| `keel_cloud_list_sites` / `keel_cloud_get_site` | List or fetch a site (includes `storage_path`) |
+| `keel_cloud_create_site` | Create from preset (`minimal` \| `api` \| `app` \| `saas`) |
+| `keel_cloud_preview` | Deploy preview Worker |
+| `keel_cloud_publish` | Publish production — requires `confirm: true` |
+| `keel_cloud_set_secret` | Vault a secret (injected on next deploy) |
+| `keel_cloud_deploys` / `keel_cloud_export` | Deploy history and export manifest |
+| `keel_cloud_export_sql` | Portable `.sql` dump (`local` \| `preview` \| `production`) |
+
+```json
+{
+  "mcpServers": {
+    "keel": {
+      "command": "npx",
+      "args": ["-y", "keel-mcp"],
+      "env": {
+        "KEEL_CLOUD_TOKEN": "kc_…",
+        "KEEL_CLOUD_URL": "https://app.keeljs.cloud"
+      }
+    }
+  }
+}
+```
+
 ### Resources
 
 - `keel://overview` — the same orientation text as `keel_overview`
@@ -4739,6 +4768,13 @@ package, so it always matches your installed version.
 4. `keel_scaffold { kind: "controller", name: "Post", resource: true }` → get the stub.
 5. Write the file, add the route, run `npm run typecheck`.
 
+### A typical Keel Cloud loop
+
+1. `keel_cloud_create_site { name: "Acme", preset: "app" }`
+2. Edit the returned `storage_path` (real Keel app + git)
+3. `keel_cloud_preview { site_id }`
+4. `keel_cloud_publish { site_id, confirm: true }` after the user approves
+
 ## `llms.txt` and `llms-full.txt`
 
 At the package root:
@@ -5716,6 +5752,15 @@ const intent = await user.createSetupIntent();  // return intent.clientSecret to
 const methods = await user.paymentMethods();
 ```
 
+### Customer portal (Stripe)
+
+Send the customer to Stripe's hosted portal to update their card or cancel:
+
+```ts
+const portal = await user.billingPortal("https://app.example.com/billing");
+// redirect to portal.url
+```
+
 These are Stripe-only capabilities; calling them on the Paddle gateway throws a
 `BillingError` (Paddle collects cards in its own hosted checkout).
 
@@ -5810,7 +5855,7 @@ real gateway from `config/billing.ts` and `.env`.
 |---------|--------|--------|
 | Create a subscription server-side | `create(pmId)` | Not supported — use `checkout()`; the webhook creates the local row |
 | One-off `charge()` | Confirms a PaymentIntent | Not supported — use `checkout({ mode })` / transactions |
-| SetupIntent / `paymentMethods()` | Supported | Throws `BillingError` (hosted checkout) |
+| SetupIntent / `paymentMethods()` / `billingPortal()` | Supported | Throws `BillingError` (hosted checkout) |
 | Checkout handle | `session.url` (redirect) | `session.clientToken` (overlay/inline) |
 | Webhook signature | `Stripe-Signature: t=…,v1=…` | `Paddle-Signature: ts=…;h1=…` |
 
@@ -9429,6 +9474,88 @@ definition function.
 
 
 
+---
+
+<!-- source: docs/gates.md -->
+
+# Gates
+
+Keel Gates is a **signup gate** for private alpha / waitlist apps: an email
+allowlist, invite codes with use limits and expiry, and a single check that
+answers "may this person register?". It ships as `@shaferllc/keel/gates`.
+
+This is **not** authorization (`can` / policies in [authorization](./authorization.md))
+and **not** team invitations ([teams](./teams.md)). Those answer different
+questions. Gates answers only: *is this email allowed to create an account?*
+
+## Install
+
+```ts
+// bootstrap/providers.ts
+import { GatesServiceProvider } from "@shaferllc/keel/gates";
+
+export const providers = [AppServiceProvider, GatesServiceProvider];
+```
+
+Then migrate — the provider contributes `invite_codes` and `email_allowlist`
+tables (`CREATE TABLE IF NOT EXISTS`, so existing apps stay safe):
+
+```bash
+keel migrate
+```
+
+## Checking registration
+
+```ts
+import { canRegister, redeemInvite } from "@shaferllc/keel/gates";
+
+const gate = await canRegister(email, inviteCode);
+if (!gate.ok) {
+  return json({ error: gate.reason }, 403);
+}
+
+// …create the user…
+
+if (gate.via === "code" && gate.invite) {
+  await redeemInvite(gate.invite); // increments uses
+}
+```
+
+`canRegister` returns:
+
+| Result | Meaning |
+|--------|---------|
+| `{ ok: true, via: "allowlist" }` | Email is on `email_allowlist` |
+| `{ ok: true, via: "code", invite }` | Valid invite code (not expired, uses left) |
+| `{ ok: false, reason }` | Rejected — show `reason` to the user |
+
+Allowlist wins over codes: if the email is allowlisted, the code is ignored.
+
+## Managing codes and allowlist
+
+The models are ordinary Keel models — create rows from an admin UI or a seeder:
+
+```ts
+import { InviteCode, EmailAllowlist } from "@shaferllc/keel/gates";
+
+await InviteCode.create({
+  code: "ALPHA-42",
+  max_uses: 10,
+  uses: 0,
+  expires_at: null,
+});
+
+await EmailAllowlist.create({ email: "ada@example.com" });
+```
+
+## Related
+
+- [Accounts](./accounts.md) — register / login flows that call `canRegister` first
+- [Teams](./teams.md) — invitations *into* a team, after the user already exists
+- [Authorization](./authorization.md) — ability checks once they're signed in
+
+
+
 ---
 
 <!-- source: docs/hashing.md -->
@@ -10597,6 +10724,110 @@ The signature of `onReady` / `onShutdown` hooks.
 
 
 
+---
+
+<!-- source: docs/hosting.md -->
+
+# Hosting
+
+Keel Hosting is a small toolkit for **hosted Workers / D1 apps**: a Cloudflare
+REST client, hostname helpers, a SQLite-compatible SQL dump, and purpose-scoped
+secret encryption. It ships as `@shaferllc/keel/hosting`.
+
+This is infrastructure — not a control plane. Site orchestration, plans, and
+deploy loops live in your app (for example Keel Cloud).
+
+## Install
+
+```ts
+import {
+  CloudflareClient,
+  cloudflareConfigured,
+  normalizeHostname,
+  isValidHostname,
+  zoneCandidates,
+  dumpConnection,
+  normalizeSecretKey,
+  encryptSecretValue,
+  decryptSecretValue,
+  resolveSecretRows,
+} from "@shaferllc/keel/hosting";
+```
+
+No service provider — import what you need.
+
+## Cloudflare
+
+```ts
+const creds = {
+  accountId: process.env.CF_ACCOUNT_ID!,
+  apiToken: process.env.CF_API_TOKEN!,
+};
+
+if (!cloudflareConfigured(creds)) {
+  throw new Error("Cloudflare credentials missing");
+}
+
+const cf = new CloudflareClient(creds);
+const db = await cf.createD1Database("kc-acme");
+```
+
+Credentials are constructor args — no app config coupling. Optional
+`pinnedZoneId` / `pinnedZoneName` skip a zone lookup when you already know the
+primary zone.
+
+## Hostnames
+
+```ts
+const host = normalizeHostname("https://App.Example.com/"); // "app.example.com"
+isValidHostname(host); // true
+zoneCandidates(host);  // ["app.example.com", "example.com"]
+```
+
+`zoneCandidates` walks from most-specific to apex — useful when attaching a
+Workers Custom Domain and you need to find which zone owns the name.
+
+## SQL dump
+
+Dump any SQLite-compatible `Connection` to a portable `.sql` script (schema +
+data). Useful for export / escape hatches:
+
+```ts
+import { db } from "@shaferllc/keel/core";
+import { dumpConnection } from "@shaferllc/keel/hosting";
+
+const sql = await dumpConnection(db(), "Acme local D1", { generatedBy: "Keel Cloud" });
+// write sql to a .sql file; restore with sqlite3 / D1 import
+```
+
+## Secrets
+
+Encrypt vault values with Keel's purpose-scoped encryption (`config('app.key')`
+must be set). Keys are normalized to `ENV_STYLE` identifiers:
+
+```ts
+const key = normalizeSecretKey("stripe-secret-key"); // "STRIPE_SECRET_KEY"
+const encrypted = await encryptSecretValue(secret, "app-secret");
+const plain = await decryptSecretValue(encrypted, "app-secret");
+
+const env = await resolveSecretRows(
+  [{ key: "STRIPE_SECRET_KEY", value_encrypted: encrypted }],
+  "app-secret",
+);
+// { STRIPE_SECRET_KEY: "…" }
+```
+
+Your app owns the table of rows (`owner_id`, `key`, `value_encrypted`); hosting
+only encrypts and decrypts.
+
+## Related
+
+- [Gates](./gates.md) — private-alpha signup gating used by hosted control planes
+- [Starter kits](./starter-kits.md) — presets Cloud scaffolds from
+- [Building with AI](./ai.md) — MCP Cloud tools (`keel_cloud_*`) that drive hosting
+
+
+
 ---
 
 <!-- source: docs/i18n.md -->

package/llms.txt

@@ -30,12 +30,14 @@ Userland imports everything from `@shaferllc/keel/core`.
 - [Errors & Exceptions](https://github.com/shaferllc/keel/blob/main/docs/errors.md): Throw an exception anywhere — a handler, middleware, or a service deep in the container — and Keel's HTTP kernel turns it into the right response.
 - [Events](https://github.com/shaferllc/keel/blob/main/docs/events.md): A tiny event emitter for decoupling — fire an event in one place, handle it in another.
 - [Factories & Seeders](https://github.com/shaferllc/keel/blob/main/docs/factories.md): Populate the database with realistic fixtures for tests and demos.
+- [Gates](https://github.com/shaferllc/keel/blob/main/docs/gates.md): Keel Gates is a signup gate for private alpha / waitlist apps: an email allowlist, invite codes with use limits and expiry, and a single check that answers "may this person register?".
 - [Getting Started](https://github.com/shaferllc/keel/blob/main/docs/getting-started.md): Keel is a house framework for Node.js — a small, legible MVC layer over Hono.
 - [Hashing & Encryption](https://github.com/shaferllc/keel/blob/main/docs/hashing.md): Password hashing and value encryption, both built on the Web Crypto API — so they run identically on Node and the edge, with no native bindings (no bcrypt to compile).
 - [Health Checks](https://github.com/shaferllc/keel/blob/main/docs/health.md): Two endpoints, answering the two questions an orchestrator — Kubernetes, Fly, Railway, a load balancer — actually asks:
 - [Helpers](https://github.com/shaferllc/keel/blob/main/docs/helpers.md): Keel gives you a handful of global helper functions so you can reach the running application from anywhere — a route handler, a model, a plain function — without threading a container reference through every call.
 - [Built on Hono](https://github.com/shaferllc/keel/blob/main/docs/hono.md): Keel's HTTP layer is Hono — an ultrafast, web-standard router that runs on Node, Cloudflare Workers, Deno, Bun, and more.
 - [Lifecycle Hooks](https://github.com/shaferllc/keel/blob/main/docs/hooks.md): Tap into the application lifecycle — run code once the app is ready, clean up on shutdown, and observe route registration.
+- [Hosting](https://github.com/shaferllc/keel/blob/main/docs/hosting.md): Keel Hosting is a small toolkit for hosted Workers / D1 apps: a Cloudflare REST client, hostname helpers, a SQLite-compatible SQL dump, and purpose-scoped secret encryption.
 - [Internationalization](https://github.com/shaferllc/keel/blob/main/docs/i18n.md): Translations with ICU message formatting, plus the Intl formatters that go with them.
 - [Inertia](https://github.com/shaferllc/keel/blob/main/docs/inertia.md): Keel ships a server-side Inertia.js adapter.
 - [Locks](https://github.com/shaferllc/keel/blob/main/docs/locks.md): "Only one of you may do this at a time" — across processes, across nodes.
@@ -97,11 +99,13 @@ Every topic has a runnable, type-checked example:
 - [Errors & Exceptions example](https://github.com/shaferllc/keel/blob/main/docs/examples/errors.ts)
 - [Events example](https://github.com/shaferllc/keel/blob/main/docs/examples/events.ts)
 - [Factories & Seeders example](https://github.com/shaferllc/keel/blob/main/docs/examples/factories.ts)
+- [Gates example](https://github.com/shaferllc/keel/blob/main/docs/examples/gates.ts)
 - [Hashing & Encryption example](https://github.com/shaferllc/keel/blob/main/docs/examples/hashing.ts)
 - [Health Checks example](https://github.com/shaferllc/keel/blob/main/docs/examples/health.ts)
 - [Helpers example](https://github.com/shaferllc/keel/blob/main/docs/examples/helpers.ts)
 - [Built on Hono example](https://github.com/shaferllc/keel/blob/main/docs/examples/hono.ts)
 - [Lifecycle Hooks example](https://github.com/shaferllc/keel/blob/main/docs/examples/hooks.ts)
+- [Hosting example](https://github.com/shaferllc/keel/blob/main/docs/examples/hosting.ts)
 - [Internationalization example](https://github.com/shaferllc/keel/blob/main/docs/examples/i18n.ts)
 - [Inertia example](https://github.com/shaferllc/keel/blob/main/docs/examples/inertia.ts)
 - [Locks example](https://github.com/shaferllc/keel/blob/main/docs/examples/locks.ts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.83.2",
+  "version": "0.83.4",
   "type": "module",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "license": "MIT",
@@ -77,6 +77,14 @@
       "types": "./dist/billing/index.d.ts",
       "import": "./dist/billing/index.js"
     },
+    "./gates": {
+      "types": "./dist/gates/index.d.ts",
+      "import": "./dist/gates/index.js"
+    },
+    "./hosting": {
+      "types": "./dist/hosting/index.d.ts",
+      "import": "./dist/hosting/index.js"
+    },
     "./cli": {
       "types": "./dist/core/cli/index.d.ts",
       "import": "./dist/core/cli/index.js"