@shaferllc/keel 0.79.0 → 0.81.0

package/dist/core/relations.js

@@ -28,6 +28,13 @@ import { db } from "./database.js";
 function unique(values) {
     return [...new Set(values)];
 }
+/** Count how many times each value appears — the basis of `withCount`. */
+function tally(values) {
+    const counts = new Map();
+    for (const value of values)
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    return counts;
+}
 /** Base class: a relationship is awaitable (resolves to its loaded result). */
 export class Relation {
     parent;
@@ -76,6 +83,21 @@ export class HasMany extends Relation {
             m.setRelation(name, grouped.get(m[this.localKey]) ?? []);
         }
     }
+    parentColumn() {
+        return this.localKey;
+    }
+    async matchingParentKeys(constrain) {
+        const q = db(this.related.table, this.related.connection);
+        constrain?.(q);
+        return unique((await q.pluck(this.foreignKey)).filter((v) => v != null));
+    }
+    async countsByParent(parentKeys) {
+        return tally(parentKeys.length
+            ? await db(this.related.table, this.related.connection)
+                .whereIn(this.foreignKey, parentKeys)
+                .pluck(this.foreignKey)
+            : []);
+    }
 }
 /* --------------------------------- has-one --------------------------------- */
 export class HasOne extends Relation {
@@ -110,6 +132,21 @@ export class HasOne extends Relation {
             m.setRelation(name, byKey.get(m[this.localKey]) ?? null);
         }
     }
+    parentColumn() {
+        return this.localKey;
+    }
+    async matchingParentKeys(constrain) {
+        const q = db(this.related.table, this.related.connection);
+        constrain?.(q);
+        return unique((await q.pluck(this.foreignKey)).filter((v) => v != null));
+    }
+    async countsByParent(parentKeys) {
+        return tally(parentKeys.length
+            ? await db(this.related.table, this.related.connection)
+                .whereIn(this.foreignKey, parentKeys)
+                .pluck(this.foreignKey)
+            : []);
+    }
 }
 /* -------------------------------- belongs-to ------------------------------- */
 export class BelongsTo extends Relation {
@@ -144,6 +181,25 @@ export class BelongsTo extends Relation {
             m.setRelation(name, byKey.get(m[this.foreignKey]) ?? null);
         }
     }
+    parentColumn() {
+        return this.foreignKey;
+    }
+    async matchingParentKeys(constrain) {
+        const q = db(this.related.table, this.related.connection);
+        constrain?.(q);
+        return unique((await q.pluck(this.ownerKey)).filter((v) => v != null));
+    }
+    async countsByParent(parentKeys) {
+        const existing = new Set(parentKeys.length
+            ? await db(this.related.table, this.related.connection)
+                .whereIn(this.ownerKey, parentKeys)
+                .pluck(this.ownerKey)
+            : []);
+        const counts = new Map();
+        for (const key of parentKeys)
+            counts.set(key, existing.has(key) ? 1 : 0);
+        return counts;
+    }
 }
 /* ----------------------------- belongs-to-many ----------------------------- */
 export class BelongsToMany extends Relation {
@@ -226,4 +282,190 @@ export class BelongsToMany extends Relation {
         for (const id of ids)
             await this.attach(id);
     }
+    parentColumn() {
+        return this.parentKey;
+    }
+    async matchingParentKeys(constrain) {
+        const rq = db(this.related.table, this.related.connection);
+        constrain?.(rq);
+        const relatedIds = unique((await rq.pluck(this.relatedKey)).filter((v) => v != null));
+        if (!relatedIds.length)
+            return [];
+        const pivots = await db(this.pivotTable, this.related.connection)
+            .whereIn(this.relatedPivotKey, relatedIds)
+            .pluck(this.foreignPivotKey);
+        return unique(pivots.filter((v) => v != null));
+    }
+    async countsByParent(parentKeys) {
+        return tally(parentKeys.length
+            ? await db(this.pivotTable, this.related.connection)
+                .whereIn(this.foreignPivotKey, parentKeys)
+                .pluck(this.foreignPivotKey)
+            : []);
+    }
+}
+/* ----------------------------- polymorphic --------------------------------- */
+/** Maps a stored morph-type string to its model class, so `morphTo` can resolve it. */
+const morphRegistry = new Map();
+/** Register a model under a morph type string (usually its class name). */
+export function registerMorphType(type, related) {
+    morphRegistry.set(type, related);
+}
+/** The parent side of a polymorphic one-to-many (`Post.comments()` over `commentable`). */
+export class MorphMany extends Relation {
+    morphType;
+    idColumn;
+    typeColumn;
+    localKey;
+    constructor(parent, related, morphType, idColumn, typeColumn, localKey) {
+        super(parent, related);
+        this.morphType = morphType;
+        this.idColumn = idColumn;
+        this.typeColumn = typeColumn;
+        this.localKey = localKey;
+    }
+    localValue() {
+        return this.parent[this.localKey];
+    }
+    query() {
+        return db(this.related.table, this.related.connection)
+            .where(this.typeColumn, this.morphType)
+            .where(this.idColumn, this.localValue());
+    }
+    async get() {
+        return this.hydrate(await this.query().get());
+    }
+    async eager(models, name) {
+        const keys = unique(models.map((m) => m[this.localKey]).filter((v) => v != null));
+        const rows = keys.length
+            ? await db(this.related.table, this.related.connection)
+                .where(this.typeColumn, this.morphType)
+                .whereIn(this.idColumn, keys)
+                .get()
+            : [];
+        const grouped = new Map();
+        for (const row of rows) {
+            const bucket = grouped.get(row[this.idColumn]) ?? [];
+            bucket.push(new this.related(row));
+            grouped.set(row[this.idColumn], bucket);
+        }
+        for (const m of models)
+            m.setRelation(name, grouped.get(m[this.localKey]) ?? []);
+    }
+    parentColumn() {
+        return this.localKey;
+    }
+    async matchingParentKeys(constrain) {
+        const q = db(this.related.table, this.related.connection).where(this.typeColumn, this.morphType);
+        constrain?.(q);
+        return unique((await q.pluck(this.idColumn)).filter((v) => v != null));
+    }
+    async countsByParent(parentKeys) {
+        return tally(parentKeys.length
+            ? await db(this.related.table, this.related.connection)
+                .where(this.typeColumn, this.morphType)
+                .whereIn(this.idColumn, parentKeys)
+                .pluck(this.idColumn)
+            : []);
+    }
+    /** Create a related row with the morph keys (`*_id` / `*_type`) filled in. */
+    create(attributes) {
+        return this.related.create({
+            ...attributes,
+            [this.idColumn]: this.localValue(),
+            [this.typeColumn]: this.morphType,
+        });
+    }
+}
+/** The parent side of a polymorphic one-to-one. */
+export class MorphOne extends Relation {
+    morphType;
+    idColumn;
+    typeColumn;
+    localKey;
+    constructor(parent, related, morphType, idColumn, typeColumn, localKey) {
+        super(parent, related);
+        this.morphType = morphType;
+        this.idColumn = idColumn;
+        this.typeColumn = typeColumn;
+        this.localKey = localKey;
+    }
+    query() {
+        return db(this.related.table, this.related.connection)
+            .where(this.typeColumn, this.morphType)
+            .where(this.idColumn, this.parent[this.localKey]);
+    }
+    async get() {
+        const row = await this.query().first();
+        return row ? new this.related(row) : null;
+    }
+    async eager(models, name) {
+        const keys = unique(models.map((m) => m[this.localKey]).filter((v) => v != null));
+        const rows = keys.length
+            ? await db(this.related.table, this.related.connection)
+                .where(this.typeColumn, this.morphType)
+                .whereIn(this.idColumn, keys)
+                .get()
+            : [];
+        const byKey = new Map();
+        for (const row of rows)
+            if (!byKey.has(row[this.idColumn]))
+                byKey.set(row[this.idColumn], new this.related(row));
+        for (const m of models)
+            m.setRelation(name, byKey.get(m[this.localKey]) ?? null);
+    }
+}
+/** The owning side of a polymorphic relation — resolves its parent by stored type + id. */
+export class MorphTo {
+    parent;
+    idColumn;
+    typeColumn;
+    constructor(parent, idColumn, typeColumn) {
+        this.parent = parent;
+        this.idColumn = idColumn;
+        this.typeColumn = typeColumn;
+    }
+    relatedClass() {
+        const type = this.parent[this.typeColumn];
+        return type ? morphRegistry.get(type) : undefined;
+    }
+    async get() {
+        const cls = this.relatedClass();
+        const id = this.parent[this.idColumn];
+        if (!cls || id == null)
+            return null;
+        const row = await db(cls.table, cls.connection).where(cls.primaryKey, id).first();
+        return row ? new cls(row) : null;
+    }
+    async eager(models, name) {
+        const byType = new Map();
+        for (const m of models) {
+            const type = m[this.typeColumn];
+            if (!type) {
+                m.setRelation(name, null);
+                continue;
+            }
+            const group = byType.get(type) ?? [];
+            group.push(m);
+            byType.set(type, group);
+        }
+        for (const [type, group] of byType) {
+            const cls = morphRegistry.get(type);
+            if (!cls) {
+                for (const m of group)
+                    m.setRelation(name, null);
+                continue;
+            }
+            const ids = unique(group.map((m) => m[this.idColumn]).filter((v) => v != null));
+            const rows = ids.length ? await db(cls.table, cls.connection).whereIn(cls.primaryKey, ids).get() : [];
+            const byId = new Map(rows.map((row) => [row[cls.primaryKey], row]));
+            for (const m of group) {
+                const row = byId.get(m[this.idColumn]);
+                m.setRelation(name, row ? new cls(row) : null);
+            }
+        }
+    }
+    then(onFulfilled, onRejected) {
+        return this.get().then(onFulfilled, onRejected);
+    }
 }

package/docs/accounts.md

@@ -0,0 +1,214 @@
+# Accounts
+
+Password reset, email verification, and two-factor authentication — the flows every
+app with a login needs, built on primitives already in core (`hash`, `encryption`,
+`mail`, `rate-limit`).
+
+They live in the framework, tested once, rather than being copy-pasted into each new
+app. A password-reset flow written five times is four copies that quietly rot.
+
+```bash
+npm install @shaferllc/keel
+```
+
+```ts
+// bootstrap/providers.ts
+import { AccountsServiceProvider } from "@shaferllc/keel/accounts";
+
+app.register(AccountsServiceProvider);
+```
+
+That merges config, adds four columns to your `users` table via a migration, and
+mounts the JSON endpoints. **Views stay yours** — these are functions and JSON
+endpoints; your controllers render the forms.
+
+## Login
+
+`attempt()` checks a password. What comes back depends on whether the user has 2FA.
+
+```ts
+const result = await attempt(email, password);
+
+if (result.status === "failed") {
+  return { error: "Those credentials don't match." };
+}
+
+if (result.status === "two-factor") {
+  // Nothing is logged in yet. Hold the challenge, ask for a code.
+  return { twoFactor: true, challenge: result.challenge };
+}
+
+auth().login(result.user.id);
+```
+
+A wrong email and a wrong password give the same answer, and take the same time —
+`attempt()` hashes against `hash.dummy` when no user is found, because a fast "no
+such user" tells an attacker which addresses are registered.
+
+## Two-factor
+
+### The challenge is not a session
+
+When 2FA is on, a correct password yields a **challenge**, not a login. Nothing is
+authenticated until the code verifies.
+
+This matters more than it looks. The usual implementation logs the user in and sets a
+`needs_2fa` flag for middleware to check — which means they are holding a real
+authenticated session *before* the second factor. Every route that forgets the
+middleware, and every `auth()` call that only asks "is anyone logged in?", is then
+bypassable with just a password. The second factor becomes advisory.
+
+Here there is no half-authenticated state to forget about, because there is no
+session. The challenge is a short-lived token bound to a single purpose, so it cannot
+be swapped for a session cookie or spent as a password-reset link.
+
+```ts
+const user = await completeTwoFactor(challenge, code);
+if (!user) return { error: "That code isn't valid." };
+
+auth().login(user.id);
+```
+
+`completeTwoFactor()` accepts an authenticator code **or** a recovery code.
+
+### Turning it on takes two steps
+
+```ts
+// Step one: a secret and recovery codes. 2FA is NOT on yet.
+const setup = await enableTwoFactor(user, { issuer: "Acme" });
+```
+
+`setup.uri` is an `otpauth://` URI to render as a QR code. `setup.secret` is for
+manual entry. `setup.recoveryCodes` are shown **once**.
+
+> Render the QR **locally**. The URI contains the shared secret, so posting it to a
+> QR-image service hands your users' second factor to a third party.
+
+```ts
+// Step two: a working code turns it on.
+const ok = await confirmTwoFactor(user, code);
+```
+
+The two-step dance is deliberate. A one-step "enable" locks out every user who scans
+the QR wrong or whose phone clock is off — and what's broken is the very thing they'd
+need to get back in. Until `confirmTwoFactor()` succeeds, `hasTwoFactor()` is false
+and login works as before.
+
+### Recovery codes
+
+Eight by default, hashed at rest, single-use — redeeming one burns it, so a code read
+over your shoulder is one you have already spent.
+
+```ts
+await recoveryCodesRemaining(user);       // worth surfacing when it gets low
+await regenerateRecoveryCodes(user);      // invalidates the old set
+await disableTwoFactor(user);             // destroys the secret and the codes
+```
+
+### What's stored
+
+The TOTP secret is **encrypted** at rest and the recovery codes are **hashed**, so a
+leaked database hands over neither the second factor nor the backdoor.
+
+TOTP itself is RFC 6238, verified against the RFC's published test vectors, and built
+on WebCrypto with no dependencies — so it runs unchanged on the edge.
+
+## Password reset
+
+```ts
+await requestPasswordReset(email);   // emails a link, or quietly does nothing
+```
+
+The answer is the same whether or not that address has an account. "No account with
+that address" is a free enumeration oracle on an unauthenticated endpoint that anyone
+can ask about anyone.
+
+```ts
+const ok = await resetPassword(token, password);
+```
+
+**A reset link works exactly once**, and there is no `password_resets` table. The
+token carries its own purpose and expiry inside the ciphertext, and it is bound to a
+fingerprint of the current password hash — so the moment the password changes, every
+token minted against the old one is dead. Nothing to store, nothing to clean up, and
+no window where a stale row is still redeemable because a cron job didn't run.
+
+## Email verification
+
+```ts
+await sendVerificationEmail(user);
+const user = await verifyEmail(token);   // idempotent
+```
+
+The token is bound to the address it was sent to. A link mailed to an old address
+cannot verify a new one — otherwise changing your email to someone else's and clicking
+an older link would mark *their* address as proven.
+
+## The endpoints
+
+Mounted at `auth` unless you turn them off (`routes.enabled: false`) and call the
+functions from your own controllers instead.
+
+| Method | Path | Notes |
+| --- | --- | --- |
+| POST | `/auth/login` | `{ email, password }` → a user, or `{ twoFactor, challenge }` |
+| POST | `/auth/two-factor` | `{ challenge, code }` — code or recovery code |
+| POST | `/auth/password/forgot` | Always `202`. Never says who exists. |
+| POST | `/auth/password/reset` | `{ token, password }` |
+| POST | `/auth/email/verify` | `{ token }` |
+| POST | `/auth/email/resend` | Always `202` |
+
+Every one is unauthenticated and touches credentials, so the group is rate-limited
+(5 per minute by default). Without a throttle, a six-digit code inside a 30-second
+window is guessable, and forgot-password is an email cannon pointed at whoever the
+caller names.
+
+## Configuration
+
+```bash
+keel vendor:publish --tag accounts-config
+```
+
+```ts
+export default {
+  userTable: "users",
+  routes: { enabled: true, prefix: "auth" },
+  passwordReset: { expiresIn: "60m", url: "/reset-password?token=:token" },
+  verification: { expiresIn: "24h", url: "/verify-email?token=:token" },
+  twoFactor: {
+    issuer: env("APP_NAME", "Keel"),
+    window: 1,               // ±30s of clock drift
+    challengeExpiresIn: "5m",
+    recoveryCodes: 8,
+  },
+  rateLimit: { max: 5, window: 60 },
+};
+```
+
+`twoFactor.challengeExpiresIn` is the window in which a stolen password alone is
+enough. Keep it short.
+
+## A different users table
+
+Accounts talks to a table through the query builder rather than assuming a `Model`.
+If your users live somewhere else — an auth service, a legacy schema — replace the
+store:
+
+```ts
+setAccountStore({
+  async findById(id) { /* … */ },
+  async findByEmail(email) { /* … */ },
+  async update(id, values) { /* … */ },
+});
+```
+
+## The schema
+
+Four columns on your users table, and no tokens table:
+
+| Column | |
+| --- | --- |
+| `email_verified_at` | null until proven |
+| `two_factor_secret` | encrypted at rest |
+| `two_factor_recovery_codes` | hashed, then encrypted |
+| `two_factor_confirmed_at` | null until a working code proves it |

package/docs/ai-manifest.json

@@ -1,10 +1,17 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.79.0",
+  "version": "0.81.0",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "repo": "https://github.com/shaferllc/keel",
   "generated": "run `npm run build:ai` to regenerate",
   "docs": [
+    {
+      "slug": "accounts",
+      "title": "Accounts",
+      "summary": "Password reset, email verification, and two-factor authentication — the flows every app with a login needs, built on primitives already in core (hash, encryption, mail, rate-limit).",
+      "path": "docs/accounts.md",
+      "example": "docs/examples/accounts.ts"
+    },
     {
       "slug": "ai",
       "title": "Building Keel apps with AI",
@@ -40,6 +47,13 @@
       "path": "docs/authorization.md",
       "example": "docs/examples/authorization.ts"
     },
+    {
+      "slug": "billing",
+      "title": "Billing",
+      "summary": "Keel Billing is a subscription-billing layer — a port of Laravel Cashier — for charging customers, managing subscriptions, and reconciling gateway state through webhooks.",
+      "path": "docs/billing.md",
+      "example": null
+    },
     {
       "slug": "broadcasting",
       "title": "Broadcasting",
@@ -468,6 +482,11 @@
       "kind": "value",
       "module": "helpers"
     },
+    {
+      "name": "AlterTableBuilder",
+      "kind": "value",
+      "module": "migrations"
+    },
     {
       "name": "AnyCommand",
       "kind": "type",
@@ -1373,6 +1392,11 @@
       "kind": "value",
       "module": "exceptions"
     },
+    {
+      "name": "ForeignKeyBuilder",
+      "kind": "value",
+      "module": "migrations"
+    },
     {
       "name": "formatMessage",
       "kind": "value",
@@ -1438,6 +1462,11 @@
       "kind": "value",
       "module": "social"
     },
+    {
+      "name": "GlobalScope",
+      "kind": "type",
+      "module": "model"
+    },
     {
       "name": "google",
       "kind": "value",
@@ -1883,11 +1912,46 @@
       "kind": "type",
       "module": "binding"
     },
+    {
+      "name": "ModelEvent",
+      "kind": "type",
+      "module": "model-events"
+    },
     {
       "name": "ModelFactory",
       "kind": "value",
       "module": "factory"
     },
+    {
+      "name": "ModelHook",
+      "kind": "type",
+      "module": "model-events"
+    },
+    {
+      "name": "ModelObserver",
+      "kind": "type",
+      "module": "model-events"
+    },
+    {
+      "name": "ModelQuery",
+      "kind": "value",
+      "module": "model-query"
+    },
+    {
+      "name": "MorphMany",
+      "kind": "value",
+      "module": "relations"
+    },
+    {
+      "name": "MorphOne",
+      "kind": "value",
+      "module": "relations"
+    },
+    {
+      "name": "MorphTo",
+      "kind": "value",
+      "module": "relations"
+    },
     {
       "name": "namedLogger",
       "kind": "value",
@@ -2258,6 +2322,11 @@
       "kind": "type",
       "module": "pages"
     },
+    {
+      "name": "registerMorphType",
+      "kind": "value",
+      "module": "relations"
+    },
     {
       "name": "Relation",
       "kind": "value",