hecks 3.9.1 → 3.10.0

data/lib/hecks/projections/site/cms_editor/checks.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # What the `Editor` row must satisfy beyond the class of each field: paths that start with
+        # a slash, a sign-in path the editor serves itself, a role to admit, and a login page a
+        # visitor with no session can reach.
+        module Checks
+          # A base path: one or more segments, starting with a slash and not ending with one.
+          BASE_PATH = %r{\A(/[^/\s]+)+\z}
+
+          # The largest upload size cap a row may name: 100 MiB.
+          MAX_UPLOAD = 104_857_600
+
+          module_function
+
+          # @param row [Hash{Symbol => String}] the row, defaults filled
+          # @param roles [Array<String>] the roles the row names
+          # @param table [Table, nil] the checked route table, to check the login page against
+          # @return [Array<String>] every problem, in the order the fields are declared
+          def problems(row, roles, table)
+            base = row[:base_path]
+            [*path_problems(row, base), *("Editor roles name no role" if roles.empty?), *login_problems(row[:login], table),
+             *media_problems(row)]
+          end
+
+          # @return [Array<String>] the problems with the base path and the sign-in path
+          def path_problems(row, base)
+            found = []
+            found << "base_path #{base.inspect} must start with a slash and not end with one" unless BASE_PATH.match?(base)
+            found << "sso_path #{row[:sso_path]} must be under #{base}/" unless row[:sso_path].start_with?("#{base}/")
+            found
+          end
+
+          # @return [Array<String>] the problems with the picture directory and the upload size cap
+          def media_problems(row)
+            found = []
+            found << "media_dir must not be empty" if row[:media_dir].strip.empty?
+            cap = row[:media_max_bytes]
+            unless cap.match?(/\A[1-9]\d{0,9}\z/) && cap.to_i <= MAX_UPLOAD
+              found << "media_max_bytes #{cap.inspect} must be a whole number of bytes from 1 to #{MAX_UPLOAD}"
+            end
+            found
+          end
+
+          # The login page is a public row: a visitor with no session must reach it.
+          #
+          # @return [Array<String>] the problems with the login page
+          def login_problems(login, table)
+            return ["login #{login} must start with a slash"] unless login.start_with?("/")
+            return [] if table.nil?
+
+            found = table.rows.find { |candidate| candidate.path == login }
+            return ["login #{login} is not a route of the table"] if found.nil?
+
+            found.auth == "public" ? [] : ["login #{login} is #{found.auth}; the login page must be public"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/media.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # The aggregate that registers pictures, found by shape in the schema the editor reads.
+        #
+        # It is an aggregate with a creating command whose attributes are the aggregate's identity
+        # (the key), an alt text and a mime type, and optionally a width and a height; every other
+        # attribute of that command must be optional, because an upload cannot fill it. Neither the
+        # aggregate's name nor the command's decides it; the attribute names are the vocabulary, the
+        # way `blocks`, `kind` and `spans` are for a document body. An attribute is a plain value or
+        # a value object whose first part is a plain value; the editor sends a value the same way.
+        #
+        # The domain keeps the picture's record, never its bytes.
+        module Media
+          # The attribute names that carry each part of a picture's record besides its key.
+          ROLES = { "alt" => %w[alt alt_text], "mime" => %w[mime_type mime content_type],
+                    "width" => %w[width], "height" => %w[height] }.freeze
+
+          # The parts every picture's registration must take.
+          REQUIRED = %w[key alt mime].freeze
+
+          module_function
+
+          # @param aggregates [Array<Hash{String => Object}>] the aggregates, as `Schema` reads them
+          # @return [Hash{String => Object}, nil] the aggregate and command that register a
+          #   picture, each part's attribute and the query that lists the pictures; nil when no
+          #   aggregate has the shape
+          def read(aggregates)
+            aggregates.each do |agg|
+              agg["commands"].select { |command| command["creates"] }.each do |command|
+                found = fields(agg, command)
+                return describe(agg, command, found) if found
+              end
+            end
+            nil
+          end
+
+          # @return [Hash{String => Hash}, nil] each part's attribute and how its value is sent, or
+          #   nil when the command is not a picture's registration
+          def fields(agg, command)
+            chosen = parts(agg, command["attributes"])
+            return nil unless REQUIRED.all? { |role| chosen.key?(role) } && others_optional?(command, chosen)
+
+            wrapped = chosen.transform_values { |attr| wrap(agg, attr) }
+            return nil if wrapped.value?(false)
+
+            chosen.to_h { |role, attr| [role, { "name" => attr["name"], "wrap" => wrapped.fetch(role) }] }
+          end
+
+          # @return [Boolean] whether every attribute that is not a part of the record is optional
+          def others_optional?(command, chosen)
+            (command["attributes"] - chosen.values).all? { |attr| attr["optional"] }
+          end
+
+          # @return [Hash{String => Hash}] each part of the record to the attribute that carries it
+          def parts(agg, attrs)
+            found = { "key" => attrs.find { |attr| attr["name"] == agg["identity"] } }
+            ROLES.each { |role, names| found[role] = attrs.find { |attr| names.include?(attr["name"]) } }
+            found.compact
+          end
+
+          # @return [String, nil, false] the part a value object's value is sent in, nil for a
+          #   plain value, false for an attribute an upload cannot fill
+          def wrap(agg, attr)
+            return false if attr["list"] || attr["kind"] == "reference"
+            return nil unless attr["kind"] == "object"
+
+            first = agg["valueObjects"].fetch(attr["type"], []).first
+            first && first["kind"] != "object" && !first["list"] ? first["name"] : false
+          end
+
+          # @return [Hash{String => Object}] the picture aggregate as the editor's schema names it
+          def describe(agg, command, found)
+            listing = agg["queries"].find { |query| query["attributes"].empty? }
+            { "aggregate" => agg["name"], "command" => command["name"], "fields" => found,
+              "listing" => listing && listing["name"] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/pretty.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # JSON indented two spaces, with an empty list or object as `[]` or `{}`. It does not use
+        # `JSON.pretty_generate`, whose spelling of an empty list depends on which JSON extensions
+        # are loaded, so the projection's text is the same wherever it runs.
+        module Pretty
+          module_function
+
+          # @param value [Object] a hash, array, string, number, boolean or nil
+          # @param depth [Integer] the indentation level of the line the value starts on
+          # @return [String] the value as indented JSON
+          def generate(value, depth = 0)
+            case value
+            when Hash then block("{", "}", value.map { |key, item| member(key, item, depth) }, depth)
+            when Array then block("[", "]", value.map { |item| generate(item, depth + 1) }, depth)
+            else JSON.generate(value)
+            end
+          end
+
+          # @return [String] one `"key": value` line of an object
+          def member(key, item, depth) = "#{JSON.generate(key.to_s)}: #{generate(item, depth + 1)}"
+
+          # @return [String] the lines between `open` and `close`, each indented under `depth`
+          def block(open, close, lines, depth)
+            return "#{open}#{close}" if lines.empty?
+
+            pad = "  " * (depth + 1)
+            "#{open}\n#{lines.map { |line| "#{pad}#{line}" }.join(",\n")}\n#{"  " * depth}#{close}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/schema.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "attributes"
+require_relative "media"
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # What the editor reads of a domain chapter, as plain data: each aggregate with its
+        # identity, attributes, value objects, lifecycle, commands and queries. The editor's
+        # `schema.ts` is this hash as a typed constant, and nothing else about the domain reaches
+        # the generated files, so the output is a pure function of the chapter.
+        #
+        # An aggregate that registers pictures (see `Media`) is also named under `media`, so the
+        # editor can offer an upload; a chapter with none has no such key.
+        #
+        # A query that `returns` a value object is answered outside the domain and is left out: the
+        # host refuses it, so a list cannot be built from it.
+        class Schema
+          # @param chapter [Bluebook::Chapter] the domain's chapter
+          # @param skip [Array<String>] aggregates to leave out
+          # @return [Hash{String => Object}] the domain's name and its aggregates
+          # @raise [ArgumentError] when no aggregate is left
+          def self.read(chapter, skip: [])
+            aggregates = chapter.aggregates.reject { |agg| skip.include?(agg.hecks_name) }
+            raise ArgumentError, "the #{chapter.name} chapter has no aggregate to edit" if aggregates.empty?
+
+            shaped = aggregates.map { |agg| new(agg).to_h }
+            media = Media.read(shaped)
+            { "domain" => chapter.name, "aggregates" => shaped, **(media ? { "media" => media } : {}) }
+          end
+
+          # @param aggregate [Bluebook::Aggregate] one aggregate of the chapter
+          def initialize(aggregate)
+            @agg = aggregate
+            @attributes = Attributes.new(aggregate.value_objects)
+          end
+
+          # @return [Hash{String => Object}] the aggregate as the editor reads it
+          def to_h
+            { "name" => @agg.hecks_name, "description" => @agg.description, "identity" => @agg.identified_by.to_s,
+              "lifecycle" => lifecycle, "attributes" => attributes(@agg.attributes.reject { |a| a.name == lifecycle_field }),
+              "valueObjects" => value_objects, "commands" => @agg.commands.map { |command| command(command) },
+              "queries" => queries }
+          end
+
+          private
+
+          def lifecycle_field = @agg.lifecycle&.field
+
+          def attributes(list) = list.map { |attribute| @attributes.of(attribute) }
+
+          def value_objects
+            @agg.value_objects.to_h { |object| [object.hecks_name, attributes(object.attributes)] }
+          end
+
+          def lifecycle
+            lifecycle = @agg.lifecycle
+            return nil unless lifecycle
+
+            { "field" => lifecycle.field.to_s, "default" => lifecycle.default,
+              "transitions" => lifecycle.transitions.map { |verb, move| transition(verb, move) } }
+          end
+
+          def transition(verb, move)
+            { "verb" => verb, "from" => Array(move.from), "to" => move.target }
+          end
+
+          def command(command)
+            { "name" => command.hecks_name, "goal" => command.goal, "role" => command.role, "creates" => command.creates?,
+              "on" => command.creates? ? nil : command.references.to_s, "attributes" => attributes(command.attributes) }
+          end
+
+          def queries
+            @agg.queries.reject(&:returns).map do |query|
+              { "name" => query.name, "description" => query.description, "attributes" => attributes(query.attributes) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/setting.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../root_rows"
+require_relative "../routes_ts"
+require_relative "checks"
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # The project's `Editor` row, checked: which domain chapter the editor edits, where the
+        # editor is served, the session cookie it keeps, and the host and sign-in it reads.
+        #
+        # `docs/site-routes.md` lists the fields. A project that declares no row has no editor to
+        # project.
+        class Setting
+          # The `Editor` row: its fields, which are required and what the others default to.
+          ROW = RootRows.new(
+            "Editor",
+            fields:   { domain: String, chapter: String, base_path: String, sso_path: String, session_cookie: String,
+                        host_cookie: String, host_env: String, host_default: String, roles: String, login: String,
+                        title: String, skip: String, media_dir: String, media_max_bytes: String },
+            required: %i[domain chapter host_env login],
+            defaults: { base_path: "/editor", session_cookie: "hecks_editor", host_cookie: "hecks_session",
+                        host_default: "http://127.0.0.1:4322", roles: "Admin,Owner", title: "Editor", skip: "",
+                        media_dir: "media", media_max_bytes: "5242880" }
+          )
+
+          # @return [Hash{Symbol => String}] the checked row, defaults filled
+          attr_reader :row
+
+          # Reads and checks the row a chapter declares.
+          #
+          # @param chapter [Bluebook::Chapter] the chapter that declares the route table
+          # @param table [Table, nil] the checked route table, to check the login page against
+          # @return [Setting, nil] the checked setting, or nil when the chapter declares no row
+          # @raise [Table::Invalid] when the row is refused
+          def self.read(chapter, table: nil)
+            row = ROW.read(chapter).first
+            row && new(row, table: table)
+          end
+
+          # @param row [Hash{Symbol => String}] the row, defaults filled
+          # @param table [Table, nil] the checked route table
+          # @raise [Table::Invalid] naming every problem when there is one
+          def initialize(row, table: nil)
+            @row = { sso_path: "#{row[:base_path]}/api/sso" }.merge(row)
+            problems = Checks.problems(@row, roles, table)
+            return if problems.empty?
+
+            raise Table::Invalid, "the Editor row is refused:\n#{problems.map { |line| "  - #{line}" }.join("\n")}"
+          end
+
+          # @return [String] the domain's directory, relative to the project
+          def domain = row.fetch(:domain)
+
+          # @return [String] the chapter the editor edits
+          def chapter = row.fetch(:chapter)
+
+          # @return [Array<String>] the aggregates left out
+          def skip = row.fetch(:skip).split(",").map(&:strip).reject(&:empty?)
+
+          # @return [Array<String>] the roles that count as an editor
+          def roles = row.fetch(:roles).split(",").map(&:strip).reject(&:empty?)
+
+          # @return [String] the generated package's name
+          def package = "#{chapter.gsub(/([a-z])([A-Z])/, '\1-\2').tr("_", "-").downcase}-editor"
+
+          # @return [Hash{String => String}] each placeholder to the text that replaces it
+          def tokens
+            { "__BANNER__" => RoutesTs::BANNER, "__PACKAGE__" => package, "__ROLES__" => RoutesTs.literal(roles),
+              "__MEDIA_MAX_BYTES__" => row.fetch(:media_max_bytes), **quoted }
+          end
+
+          # @return [Hash{String => String}] each text field's placeholder to the field as JSON
+          def quoted
+            { "TITLE" => :title, "BASE_PATH" => :base_path, "SSO_PATH" => :sso_path, "LOGIN" => :login,
+              "SESSION_COOKIE" => :session_cookie, "HOST_COOKIE" => :host_cookie, "HOST_ENV" => :host_env,
+              "HOST_DEFAULT" => :host_default, "MEDIA_DIR" => :media_dir }
+              .to_h { |token, field| ["__#{token}__", JSON.generate(row.fetch(field))] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/templates/package.json.tmpl

@@ -0,0 +1,19 @@
+{
+  "name": "__PACKAGE__",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "start": "node src/server.ts",
+    "check": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@hecks/client": "^3.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.8.0"
+  }
+}

data/lib/hecks/projections/site/cms_editor/templates/src/app.ts.tmpl

@@ -0,0 +1,176 @@
+__BANNER__
+
+// The editor as a function from a web `Request` to a `Response`, with its host client, clock and
+// secret passed in, so it runs the same under src/server.ts and under a test with a fake `fetch`.
+//
+// Every request is authenticated here: a signed session cookie, then the host's membership list
+// (auth/membership.ts). A visitor with neither is sent to the site's login page; nothing in the
+// domain is read or changed before that. Posts must come from this site (the cookie is SameSite=Lax
+// and the Origin header is checked too).
+import { readFileSync } from "node:fs";
+
+import { DomainRefusal, DomainUnavailable, rowsOf } from "@hecks/client";
+import type { HostClient } from "@hecks/client";
+
+import { authSecret, membershipCheck } from "./auth/membership.ts";
+import type { Membership } from "./auth/membership.ts";
+import { readSession } from "./auth/session.ts";
+import { signIn } from "./auth/sso.ts";
+import { idOf, instanceIn, runCommand } from "./commands.ts";
+import type { State } from "./commands.ts";
+import { EDITOR } from "./config.ts";
+import { hostClient } from "./host.ts";
+import { SCHEMA } from "./schema.ts";
+import type { Aggregate, Command } from "./schema.ts";
+import { commandArguments, parseForm } from "./ui/input.ts";
+import { commandPage, detailPage, home, listPage, notFound } from "./ui/pages.ts";
+import type { Submitted } from "./ui/pages.ts";
+import { href } from "./ui/html.ts";
+__MEDIA_IMPORT__
+
+export interface AppOptions {
+  /** The host's address, when not read from the environment variable the Editor row names. */
+  url?: string;
+  fetch?: typeof fetch;
+  secret?: string;
+  now?: () => number;
+  membership?: Membership;
+__MEDIA_OPTION__
+}
+
+const html = (body: string, status = 200): Response =>
+  new Response(body, { status, headers: { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" } });
+
+const redirect = (location: string, status = 303, cookie?: string): Response => {
+  const headers = new Headers({ Location: location });
+  if (cookie) headers.append("Set-Cookie", cookie);
+  return new Response(null, { status, headers });
+};
+
+/** A post is refused when the browser says it came from another site. */
+function sameSite(request: Request): boolean {
+  const origin = request.headers.get("origin");
+  if (origin) return new URL(origin).host === new URL(request.url).host;
+  return (request.headers.get("sec-fetch-site") ?? "same-origin") !== "cross-site";
+}
+
+/** The editor, as a handler. */
+export function createApp(options: AppOptions = {}): (request: Request) => Promise<Response> {
+  const secret = options.secret ?? authSecret();
+  const now = options.now ?? Date.now;
+  const membership = options.membership ?? membershipCheck({ url: options.url, fetch: options.fetch, secret, now });
+  const client = hostClient({ url: options.url, fetch: options.fetch });
+__MEDIA_SETUP__
+
+  async function handle(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const path = url.pathname.replace(/\/+$/, "") || "/";
+    if (path === EDITOR.ssoPath) return enter(url, secret, membership, now);
+    if (path !== EDITOR.basePath && !path.startsWith(`${EDITOR.basePath}/`)) return html(notFound(path), 404);
+
+    const email = readSession(request.headers.get("cookie"), secret, now);
+    if (!email || !(await membership.isAdmitted(email))) {
+      return request.method === "GET" ? redirect(EDITOR.login, 302) : new Response("Sign in again.", { status: 403 });
+    }
+    if (request.method === "POST" && !sameSite(request)) return new Response("Cross-site post refused.", { status: 403 });
+    const segments = path.slice(EDITOR.basePath.length).split("/").filter(Boolean).map(decodeURIComponent);
+__MEDIA_ROUTE__
+    return route(client, request, url, segments);
+  }
+
+  return async (request) => {
+    try {
+      return await handle(request);
+    } catch (err) {
+      if (err instanceof DomainUnavailable) return html(notFound(`The domain could not be reached: ${err.message}`), 502);
+      throw err;
+    }
+  };
+}
+
+/** The browser modules the rich-text widget loads (with the picture picker when there are pictures), for signed-in editors only. */
+const ASSETS = __ASSETS__;
+
+function asset(name: string): Response {
+  if (!ASSETS.includes(name)) return html(notFound(`No asset ${name}.`), 404);
+  const text = readFileSync(new URL(`./ui/${name}`, import.meta.url), "utf8");
+  return new Response(text, { headers: { "Content-Type": "text/javascript; charset=utf-8", "Cache-Control": "private, max-age=300" } });
+}
+
+async function enter(url: URL, secret: string, membership: Membership, now: () => number): Promise<Response> {
+  const result = await signIn(url.searchParams.get("token"), secret, membership, now);
+  if (!result.ok) return new Response(result.message, { status: result.status });
+  return redirect(result.location, 302, result.cookie);
+}
+
+function route(client: HostClient, request: Request, url: URL, segments: string[]): Promise<Response> | Response {
+  const [name, verb, ...rest] = segments;
+  if (segments.length === 0) return html(home());
+  if (name === "assets" && segments.length === 2 && request.method === "GET") return asset(verb);
+  const agg = SCHEMA.aggregates.find((candidate) => candidate.name === name);
+  if (!agg) return html(notFound(`No aggregate ${name}.`), 404);
+  if (verb === undefined) return list(client, agg, url);
+  if (verb === "id" && rest.length === 1 && request.method === "GET") return detail(client, agg, rest[0], null);
+  if (request.method === "POST") return post(client, request, agg, verb, rest);
+  if ((verb === "new" || verb === "run") && rest.length === 1) return commandView(agg, verb, rest[0]);
+  return html(notFound(`No page ${segments.join("/")}.`), 404);
+}
+
+async function list(client: HostClient, agg: Aggregate, url: URL): Promise<Response> {
+  const query = agg.queries.find((candidate) => candidate.name === url.searchParams.get("query")) ?? null;
+  const form = parseForm(url.search.slice(1));
+  const args = query ? commandArguments(agg, query.attributes, form) : {};
+  const asked = query !== null && (query.attributes.length === 0 || Object.keys(args).length > 0);
+  if (query && !asked) return html(listPage(agg, [], query, null));
+  try {
+    const rows = await rowsFor(client, agg, asked ? query : null, args);
+    return html(listPage(agg, rows, query, null));
+  } catch (err) {
+    if (err instanceof DomainRefusal) return html(listPage(agg, [], query, err.message), 200);
+    throw err;
+  }
+}
+
+async function rowsFor(client: HostClient, agg: Aggregate, query: { name: string } | null, args: State): Promise<[string, State][]> {
+  if (!query) return client.instancesOf(await client.read(), agg.name);
+  const rows = rowsOf(await client.query(`${agg.name}.${query.name}`, args), `${agg.name}.${query.name}`) ?? [];
+  return rows.flatMap((row): [string, State][] => {
+    const id = idOf(agg, row);
+    return id === null ? [] : [[id, row]];
+  });
+}
+
+async function detail(client: HostClient, agg: Aggregate, id: string, shown: Submitted | null, status = 200): Promise<Response> {
+  const values = instanceIn(client, await client.read(), agg, id);
+  if (!values) return html(notFound(`No ${agg.name} ${id}.`), 404);
+  return html(detailPage(agg, id, values, shown), status);
+}
+
+function commandView(agg: Aggregate, verb: string, name: string): Response {
+  const command = commandFor(agg, verb, name);
+  if (!command) return html(notFound(`No command ${name}.`), 404);
+  return html(commandPage(agg, command, href(agg.name, verb, name), null));
+}
+
+/** The command a `new` (creating) or `run` (acting on another aggregate) path names, or null. */
+function commandFor(agg: Aggregate, verb: string, name: string): Command | null {
+  const command = agg.commands.find((candidate) => candidate.name === name);
+  if (!command) return null;
+  if (verb === "new") return command.creates ? command : null;
+  if (verb === "run") return !command.creates && command.on !== agg.name ? command : null;
+  return command.on === agg.name ? command : null;
+}
+
+async function post(client: HostClient, request: Request, agg: Aggregate, verb: string, rest: string[]): Promise<Response> {
+  const onInstance = verb === "id" && rest.length === 2;
+  const command = onInstance ? commandFor(agg, "id", rest[1]) : rest.length === 1 ? commandFor(agg, verb, rest[0]) : null;
+  if (!command) return html(notFound("No such command."), 404);
+  const form = parseForm(await request.text());
+  const args = commandArguments(agg, command.attributes, form);
+  const to = onInstance ? rest[0] : command.creates ? undefined : (form.get("__to") ?? "");
+  const outcome = to === "" ? { ok: false as const, message: "Name the instance to act on." } : await runCommand(client, agg, command, args, to);
+  if (outcome.ok) return redirect(href(agg.name, "id", outcome.id));
+  const shown: Submitted = { command: command.name, message: outcome.message, values: { ...args, __to: to } };
+  if (onInstance) return detail(client, agg, rest[0], shown, 422);
+  return html(commandPage(agg, command, href(agg.name, verb, command.name), shown), 422);
+}

data/lib/hecks/projections/site/cms_editor/templates/src/auth/membership.ts.tmpl

@@ -0,0 +1,79 @@
+__BANNER__
+
+// Is this person still an editor? The domain's membership list decides, not this server. Signing in
+// (auth/sso.ts) proved the person was admitted then; this asks again on every request, so that
+// disabling or removing someone locks them out at once, not when their session runs out.
+//
+// The question is the host's members list, asked with a short account token signed by the secret the
+// host checks (AUTH_SECRET here is the host's SESSION_SECRET). The person counts when the list holds
+// their email with one of the configured roles and not disabled. The answer is remembered for a
+// minute per email so each request does not cost a round trip; a question that cannot be asked is
+// answered no.
+import { accountToken, resolveAccountCookieName } from "@hecks/client";
+
+import { EDITOR } from "../config.ts";
+import { hostUrl } from "../host.ts";
+
+const TOKEN_TTL_SECONDS = 60;
+
+/** The secret shared with the host. Outside production it falls back to the host's development default. */
+export function authSecret(): string {
+  return process.env.AUTH_SECRET || (process.env.NODE_ENV === "production" ? "" : "dev_only_change_me_in_production");
+}
+
+export interface Membership {
+  /** True while `email` holds an editor role on the host; false when it does not, or cannot be asked. */
+  isAdmitted(email: string): Promise<boolean>;
+}
+
+export interface MembershipOptions {
+  url?: string;
+  secret?: string;
+  fetch?: typeof fetch;
+  now?: () => number;
+}
+
+/** True when the host's members list holds `email` with an editor role and not disabled. */
+export function holdsRole(rows: unknown, email: string): boolean {
+  const roles: readonly string[] = EDITOR.roles;
+  return (
+    Array.isArray(rows) &&
+    rows.some(
+      (row: any) =>
+        typeof row?.email === "string" && row.email.trim().toLowerCase() === email && roles.includes(row.role) && row.disabled !== true,
+    )
+  );
+}
+
+/** A membership check with its own one-minute memory. */
+export function membershipCheck(options: MembershipOptions = {}): Membership {
+  const remembered = new Map<string, { admitted: boolean; until: number }>();
+  const now = options.now ?? Date.now;
+  const send = options.fetch ?? fetch;
+
+  async function ask(email: string): Promise<boolean> {
+    const secret = options.secret ?? authSecret();
+    if (!secret) return false;
+    const cookieName = resolveAccountCookieName(process.env.HECKS_SESSION_COOKIE || EDITOR.hostCookie);
+    try {
+      const res = await send(`${hostUrl({ url: options.url })}${EDITOR.membersPath}`, {
+        headers: { Cookie: `${cookieName}=${accountToken(secret, email, TOKEN_TTL_SECONDS)}` },
+        signal: AbortSignal.timeout(EDITOR.timeoutMs),
+      });
+      return res.ok && holdsRole(await res.json().catch(() => null), email);
+    } catch {
+      return false;
+    }
+  }
+
+  return {
+    async isAdmitted(email: string): Promise<boolean> {
+      const key = email.trim().toLowerCase();
+      const hit = remembered.get(key);
+      if (hit && hit.until > now()) return hit.admitted;
+      const admitted = await ask(key);
+      remembered.set(key, { admitted, until: now() + EDITOR.rememberMs });
+      return admitted;
+    },
+  };
+}