@shaferllc/keel 0.81.0 → 0.81.2

package/dist/teams/migration.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The teams schema: teams, memberships, invitations, and one column on users.
+ *
+ * `team_memberships` is what actually grants access — `teams.owner_id` is a
+ * convenience, not an authorization source. A user is in a team if and only if a
+ * membership row says so.
+ */
+import type { Migration } from "../core/migrations.js";
+export declare function teamsMigration(userTable?: string): Migration;

package/dist/teams/migration.js

@@ -0,0 +1,52 @@
+/**
+ * The teams schema: teams, memberships, invitations, and one column on users.
+ *
+ * `team_memberships` is what actually grants access — `teams.owner_id` is a
+ * convenience, not an authorization source. A user is in a team if and only if a
+ * membership row says so.
+ */
+export function teamsMigration(userTable = "users") {
+    return {
+        name: "teams_00_create_teams",
+        async up(schema) {
+            await schema.createTable("teams", (t) => {
+                t.id();
+                t.string("name");
+                t.string("slug").unique();
+                t.integer("owner_id");
+                t.timestamps();
+            });
+            await schema.createTable("team_memberships", (t) => {
+                t.id();
+                t.integer("team_id");
+                t.integer("user_id");
+                // owner | admin | member
+                t.string("role", 32).default("member");
+                t.timestamps();
+            });
+            await schema.createTable("team_invitations", (t) => {
+                t.id();
+                t.integer("team_id");
+                t.string("email");
+                t.string("role", 32).default("member");
+                // The token's HASH. The token itself lives in the invitee's inbox and
+                // nowhere else, so a database leak doesn't open every pending team.
+                t.string("token");
+                t.timestamp("expires_at");
+                t.timestamps();
+            });
+            // One membership per user per team, enforced by the database rather than by
+            // remembering to check — accepting an invitation twice must not double up.
+            await schema.raw("CREATE UNIQUE INDEX IF NOT EXISTS team_memberships_unique ON team_memberships (team_id, user_id)");
+            await schema.raw("CREATE INDEX IF NOT EXISTS team_invitations_email ON team_invitations (email)");
+            // Which team the user is currently looking at.
+            await schema.raw(`ALTER TABLE ${userTable} ADD COLUMN current_team_id INTEGER`);
+        },
+        async down(schema) {
+            await schema.dropTable("team_invitations");
+            await schema.dropTable("team_memberships");
+            await schema.dropTable("teams");
+            await schema.raw(`ALTER TABLE ${userTable} DROP COLUMN current_team_id`).catch(() => { });
+        },
+    };
+}

package/dist/teams/models.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Teams and membership.
+ *
+ * These are plain models, deliberately **not** `TenantModel` — the tenant scope
+ * constrains queries to the current team, and you have to be able to ask "which
+ * teams does this user belong to?" *before* you know which team you're in.
+ */
+import { Model } from "../core/model.js";
+/** Who can do what. Ordered: an owner can do anything an admin can, and so on. */
+export declare const ROLES: readonly ["owner", "admin", "member"];
+export type Role = (typeof ROLES)[number];
+/** Does `role` carry at least the authority of `needed`? */
+export declare function roleAtLeast(role: Role, needed: Role): boolean;
+export declare class Team extends Model {
+    static table: string;
+    static fillable: string[];
+    static timestamps: boolean;
+    id: number;
+    name: string;
+    slug: string;
+    owner_id: number;
+    /** Everyone in this team, with their role. */
+    members(): Promise<Membership[]>;
+}
+export declare class Membership extends Model {
+    static table: string;
+    static fillable: string[];
+    static timestamps: boolean;
+    id: number;
+    team_id: number;
+    user_id: number;
+    role: Role;
+}
+/** The teams a user belongs to. */
+export declare function teamsFor(userId: string | number): Promise<Team[]>;
+/** A user's role in a team, or `null` if they aren't in it. */
+export declare function roleOf(userId: string | number, teamId: string | number): Promise<Role | null>;
+/** Is this user in this team, at least at this level? */
+export declare function memberOf(userId: string | number, teamId: string | number, atLeast?: Role): Promise<boolean>;
+/**
+ * Create a team and make its creator the owner.
+ *
+ * The membership row is what actually grants access — `teams.owner_id` alone would
+ * leave the owner out of every membership query.
+ */
+export declare function createTeam(name: string, ownerId: string | number, slug?: string): Promise<Team>;
+/**
+ * Switch which team a user is acting as — **only** to a team they're actually in.
+ *
+ * The check is the point. `current_team_id` is a number on the user's own row; if
+ * switching didn't verify membership, changing teams would just be a matter of
+ * writing someone else's id into it.
+ */
+export declare function switchTeam(userId: string | number, teamId: string | number, userTable?: string): Promise<boolean>;

package/dist/teams/models.js

@@ -0,0 +1,85 @@
+/**
+ * Teams and membership.
+ *
+ * These are plain models, deliberately **not** `TenantModel` — the tenant scope
+ * constrains queries to the current team, and you have to be able to ask "which
+ * teams does this user belong to?" *before* you know which team you're in.
+ */
+import { Model } from "../core/model.js";
+import { db } from "../core/database.js";
+/** Who can do what. Ordered: an owner can do anything an admin can, and so on. */
+export const ROLES = ["owner", "admin", "member"];
+const RANK = { owner: 3, admin: 2, member: 1 };
+/** Does `role` carry at least the authority of `needed`? */
+export function roleAtLeast(role, needed) {
+    return RANK[role] >= RANK[needed];
+}
+export class Team extends Model {
+    static table = "teams";
+    static fillable = ["name", "slug", "owner_id"];
+    static timestamps = true;
+    /** Everyone in this team, with their role. */
+    async members() {
+        const rows = await db(Membership.table).where("team_id", this.id).get();
+        return rows.map((row) => new Membership(row));
+    }
+}
+export class Membership extends Model {
+    static table = "team_memberships";
+    static fillable = ["team_id", "user_id", "role"];
+    static timestamps = true;
+}
+/* --------------------------------- lookups -------------------------------- */
+/** The teams a user belongs to. */
+export async function teamsFor(userId) {
+    const memberships = await db(Membership.table).where("user_id", userId).get();
+    if (!memberships.length)
+        return [];
+    const ids = memberships.map((m) => m.team_id);
+    const rows = await db(Team.table).whereIn("id", ids).get();
+    return rows.map((row) => new Team(row));
+}
+/** A user's role in a team, or `null` if they aren't in it. */
+export async function roleOf(userId, teamId) {
+    const row = await db(Membership.table).where("user_id", userId).where("team_id", teamId).first();
+    return row ? row.role : null;
+}
+/** Is this user in this team, at least at this level? */
+export async function memberOf(userId, teamId, atLeast = "member") {
+    const role = await roleOf(userId, teamId);
+    return role ? roleAtLeast(role, atLeast) : false;
+}
+/**
+ * Create a team and make its creator the owner.
+ *
+ * The membership row is what actually grants access — `teams.owner_id` alone would
+ * leave the owner out of every membership query.
+ */
+export async function createTeam(name, ownerId, slug) {
+    const team = await Team.create({
+        name,
+        slug: slug ?? slugify(name),
+        owner_id: ownerId,
+    });
+    await Membership.create({ team_id: team.id, user_id: ownerId, role: "owner" });
+    return team;
+}
+/**
+ * Switch which team a user is acting as — **only** to a team they're actually in.
+ *
+ * The check is the point. `current_team_id` is a number on the user's own row; if
+ * switching didn't verify membership, changing teams would just be a matter of
+ * writing someone else's id into it.
+ */
+export async function switchTeam(userId, teamId, userTable = "users") {
+    if (!(await memberOf(userId, teamId)))
+        return false;
+    await db(userTable).where("id", userId).update({ current_team_id: teamId });
+    return true;
+}
+function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}

package/dist/teams/provider.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Teams — multi-tenancy, membership, roles, and invitations, shipped as a Keel
+ * package. One line in `bootstrap/providers.ts`:
+ *
+ *   app.register(TeamsServiceProvider)
+ *
+ * Then put your requests inside a team, and every `TenantModel` is scoped:
+ *
+ *   // app/Http/Kernel.ts
+ *   protected middleware = [sessionMiddleware(), teamContext()];
+ */
+import { PackageProvider } from "../core/package.js";
+export declare class TeamsServiceProvider extends PackageProvider {
+    readonly name = "teams";
+    private config;
+    register(): void;
+}

package/dist/teams/provider.js

@@ -0,0 +1,27 @@
+/**
+ * Teams — multi-tenancy, membership, roles, and invitations, shipped as a Keel
+ * package. One line in `bootstrap/providers.ts`:
+ *
+ *   app.register(TeamsServiceProvider)
+ *
+ * Then put your requests inside a team, and every `TenantModel` is scoped:
+ *
+ *   // app/Http/Kernel.ts
+ *   protected middleware = [sessionMiddleware(), teamContext()];
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { PackageProvider } from "../core/package.js";
+import { defaultConfig, resolveConfig } from "./config.js";
+import { teamsMigration } from "./migration.js";
+const here = dirname(fileURLToPath(import.meta.url));
+export class TeamsServiceProvider extends PackageProvider {
+    name = "teams";
+    config;
+    register() {
+        this.mergeConfig("teams", defaultConfig);
+        this.config = resolveConfig();
+        this.migrations([teamsMigration(this.config.userTable)]);
+        this.publishes({ [join(here, "teams.config.stub")]: "config/teams.ts" }, "teams-config");
+    }
+}

package/dist/teams/teams.config.stub

@@ -0,0 +1,24 @@
+import { env } from "@shaferllc/keel/core";
+
+/**
+ * Teams configuration — multi-tenancy, membership, roles, invitations.
+ * Published with `keel vendor:publish --tag teams-config`.
+ */
+export default {
+  // The users table. Teams adds `current_team_id` to it and touches nothing else.
+  userTable: "users",
+
+  // Give every new user a team of their own. Worth leaving on even if the app feels
+  // single-user: a personal workspace is a team of one, and adding tenancy LATER
+  // means backfilling every table and rewriting every query.
+  personalTeams: true,
+
+  invitations: {
+    expiresInHours: 72,
+    url: "/invitations/:token",
+  },
+
+  mail: {
+    from: env("MAIL_FROM", undefined),
+  },
+};

package/dist/teams/tenant.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `TenantModel` — a model that belongs to a team, and can't be read or written
+ * outside one.
+ *
+ *   class Post extends TenantModel {
+ *     static table = "posts";
+ *   }
+ *
+ *   await Post.all();                 // only the current team's posts
+ *   await Post.create({ title: … });  // stamped with the current team
+ *
+ * Two halves, and both matter. The **read** side is a global scope, so every query
+ * the model builds is constrained — you cannot forget it, because you never write
+ * it. The **write** side is a `creating` hook that stamps the team id, so a row
+ * can't be born ownerless and then be visible to everyone (or to no one).
+ *
+ * Outside a team context both halves throw. See context.ts for why that's the point.
+ */
+import { Model } from "../core/model.js";
+/** The name of the scope, so it can be escaped by name: `Post.withoutGlobalScope(TENANT_SCOPE)`. */
+export declare const TENANT_SCOPE = "tenant";
+export declare class TenantModel extends Model {
+    /** The column holding the owning team. Override if your schema differs. */
+    static teamColumn: string;
+}

package/dist/teams/tenant.js

@@ -0,0 +1,45 @@
+/**
+ * `TenantModel` — a model that belongs to a team, and can't be read or written
+ * outside one.
+ *
+ *   class Post extends TenantModel {
+ *     static table = "posts";
+ *   }
+ *
+ *   await Post.all();                 // only the current team's posts
+ *   await Post.create({ title: … });  // stamped with the current team
+ *
+ * Two halves, and both matter. The **read** side is a global scope, so every query
+ * the model builds is constrained — you cannot forget it, because you never write
+ * it. The **write** side is a `creating` hook that stamps the team id, so a row
+ * can't be born ownerless and then be visible to everyone (or to no one).
+ *
+ * Outside a team context both halves throw. See context.ts for why that's the point.
+ */
+import { Model } from "../core/model.js";
+import { addModelHook } from "../core/model-events.js";
+import { currentTeamId } from "./context.js";
+/** The name of the scope, so it can be escaped by name: `Post.withoutGlobalScope(TENANT_SCOPE)`. */
+export const TENANT_SCOPE = "tenant";
+export class TenantModel extends Model {
+    /** The column holding the owning team. Override if your schema differs. */
+    static teamColumn = "team_id";
+}
+// Registered on the base class, and inherited by every subclass — that inheritance
+// is load-bearing. If it didn't hold, `Post.query()` would come back unconstrained
+// and every tenant's rows would be readable, silently. (Both the scope and the hook
+// walk the prototype chain; see model.ts / model-events.ts.)
+TenantModel.addGlobalScope(TENANT_SCOPE, (query, model) => {
+    // `model` is the concrete subclass being queried, so each one gets its own
+    // teamColumn rather than the base class's.
+    query.where(model.teamColumn, currentTeamId());
+});
+addModelHook(TenantModel, "creating", (model) => {
+    const column = model.constructor.teamColumn;
+    const row = model;
+    // Don't overwrite an explicit team — a deliberate cross-team write (an admin tool,
+    // a transfer) already said what it meant. Everything else gets the current team.
+    if (row[column] === undefined || row[column] === null) {
+        row[column] = currentTeamId();
+    }
+});

package/docs/ai-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.81.0",
+  "version": "0.81.2",
   "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",
@@ -75,6 +75,13 @@
       "path": "docs/cache.md",
       "example": "docs/examples/cache.ts"
     },
+    {
+      "slug": "changelog",
+      "title": "Changelog",
+      "summary": "All notable changes to Keel are documented here.",
+      "path": "docs/changelog.md",
+      "example": null
+    },
     {
       "slug": "configuration",
       "title": "Configuration",
@@ -362,6 +369,13 @@
       "path": "docs/storage.md",
       "example": "docs/examples/storage.ts"
     },
+    {
+      "slug": "teams",
+      "title": "Teams",
+      "summary": "Multi-tenancy, membership, roles, and invitations — where a row belongs to a team, and one team can never see another's.",
+      "path": "docs/teams.md",
+      "example": "docs/examples/teams.ts"
+    },
     {
       "slug": "telemetry",
       "title": "Telemetry",