@shaferllc/keel 0.80.0 → 0.81.1

package/dist/teams/middleware.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Putting a request inside a team.
+ *
+ * `teamContext()` resolves which team the signed-in user is acting as and runs the
+ * rest of the request inside it, so every `TenantModel` query is scoped without any
+ * handler doing anything.
+ *
+ * The membership check is the security boundary. `users.current_team_id` is just a
+ * number on a row the user can influence, so it is **verified against a membership**
+ * on every request — not trusted. Otherwise switching teams is a matter of writing a
+ * different id, and tenancy is decoration.
+ */
+import type { MiddlewareHandler } from "hono";
+import { type Role } from "./models.js";
+export interface TeamContextOptions {
+    /**
+     * What to do when a signed-in user has no team at all. `"error"` throws;
+     * `"pass"` continues with no team context (so any TenantModel query will throw —
+     * which is the right outcome for a route that shouldn't have needed one).
+     */
+    onMissing?: "error" | "pass";
+}
+/** Resolve the acting team and run the request inside it. */
+export declare function teamContext(options?: TeamContextOptions): MiddlewareHandler;
+/**
+ * Require at least this role in the current team.
+ *
+ *   router.delete("/posts/:post", …).middleware(requireRole("admin"))
+ */
+export declare function requireRole(role?: Role): MiddlewareHandler;

package/dist/teams/middleware.js

@@ -0,0 +1,92 @@
+/**
+ * Putting a request inside a team.
+ *
+ * `teamContext()` resolves which team the signed-in user is acting as and runs the
+ * rest of the request inside it, so every `TenantModel` query is scoped without any
+ * handler doing anything.
+ *
+ * The membership check is the security boundary. `users.current_team_id` is just a
+ * number on a row the user can influence, so it is **verified against a membership**
+ * on every request — not trusted. Otherwise switching teams is a matter of writing a
+ * different id, and tenancy is decoration.
+ */
+import { auth } from "../core/auth.js";
+import { db } from "../core/database.js";
+import { ForbiddenException } from "../core/exceptions.js";
+import { runForTeam, withoutTenant } from "./context.js";
+import { Membership, roleOf, teamsFor } from "./models.js";
+import { resolveConfig } from "./config.js";
+/** Resolve the acting team and run the request inside it. */
+export function teamContext(options = {}) {
+    return async (c, next) => {
+        const userId = auth().id();
+        if (!userId) {
+            // Nobody's signed in: no team, and no guessing. A tenant-scoped query on this
+            // request will throw, which is what we want it to do.
+            await next();
+            return;
+        }
+        const teamId = await resolveTeam(userId);
+        if (teamId === null) {
+            if (options.onMissing === "error") {
+                throw new ForbiddenException("You don't belong to any team.");
+            }
+            await next();
+            return;
+        }
+        c.set("team_id", teamId);
+        await runForTeam(teamId, () => next());
+    };
+}
+/**
+ * Require at least this role in the current team.
+ *
+ *   router.delete("/posts/:post", …).middleware(requireRole("admin"))
+ */
+export function requireRole(role = "member") {
+    return async (c, next) => {
+        const userId = auth().id();
+        const teamId = c.get("team_id");
+        if (!userId || !teamId)
+            throw new ForbiddenException("You don't belong to this team.");
+        const actual = await withoutTenant(() => roleOf(userId, teamId));
+        if (!actual)
+            throw new ForbiddenException("You don't belong to this team.");
+        const { roleAtLeast } = await import("./models.js");
+        if (!roleAtLeast(actual, role)) {
+            throw new ForbiddenException(`This needs the ${role} role.`);
+        }
+        await next();
+    };
+}
+/* --------------------------------- internals ------------------------------ */
+/**
+ * The team this user is acting as — verified, not trusted.
+ *
+ * Reads `current_team_id`, then confirms a membership actually exists. If it doesn't
+ * (they were removed, or the id was tampered with), it falls back to a team they are
+ * genuinely in rather than honouring the number on the row.
+ */
+async function resolveTeam(userId) {
+    const settings = resolveConfig();
+    // These lookups are *about* teams, so they must not themselves be tenant-scoped.
+    return withoutTenant(async () => {
+        const user = await db(settings.userTable).where("id", userId).first();
+        const current = user?.current_team_id;
+        if (current != null) {
+            const membership = await db(Membership.table)
+                .where("user_id", userId)
+                .where("team_id", current)
+                .first();
+            if (membership)
+                return current;
+            // Stale or forged: fall through and pick a team they're really in.
+        }
+        const teams = await teamsFor(userId);
+        if (!teams.length)
+            return null;
+        const first = teams[0].id;
+        await db(settings.userTable).where("id", userId).update({ current_team_id: first });
+        return first;
+    });
+}

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();
+    }
+});