@starci/hfs 5.2.0 → 5.3.0

package/sync/index.mjs

@@ -237,6 +237,9 @@ export function sonarScope(presets) {
     const tests = preset.filter(glob => !glob.endsWith('/**'));
     return { tests, exclusions: [...new Set([...preset, '**/.next/**', '**/node_modules/**'])] };
 }
+/** The managed ESLint config at the app root that lints the root workspace packages. */
+export const PACKAGES_LINT_FILE = 'eslint.config.mjs';
+const LINE = '\n';
 const SOURCE_FILE = /\.[cm]?ts$/;
 const SOURCE_SKIPPED = new Set(['node_modules', 'dist', 'coverage']);
 /**
@@ -396,6 +399,30 @@ const moduleExclusions = (dirs) => dirs.flatMap(dir => [`${dir}/src/workbench/**
 function registryTargets(app, source) {
     return registryFiles(app.project, source?.modules ?? []).map((file) => ({ path: file.path, scope: APP_SCOPE, mode: 'file', content: file.content, hash: hashOf(file.content) }));
 }
+/**
+ * The root `eslint.config.mjs` of an app that has root workspace packages (packages/agent-sdk, packages/module-<name>, the registry): no side config
+ * reaches `packages/`, so this managed file lints their source by subpath. The back-end canon judges everything but the front-end subpaths
+ * (`src/workbench/` outside its contract, `src/public/`), the front-end canon and the selected Grammar family those, each over the package view of
+ * the app root. An app without a root package has no such file; the family factory for packages is the family's `<name>GrammarPackagesConfig`.
+ */
+function packagesLintTargets(app, source) {
+    if (!(source?.modules?.length || source?.otherPackages?.length))
+        return [];
+    const grammar = grammarLintFor(app.sides.fe.grammar);
+    const factory = grammar.package ? grammar.factory.replace(/Config$/, 'PackagesConfig') : null;
+    const content = [
+        'import { loadPackagesHfs as loadBePackages, starciBePackagesConfig } from "@starci/eslint-canon-be"',
+        'import { loadPackagesHfs as loadFePackages, starciFePackagesConfig } from "@starci/eslint-canon-fe"',
+        ...(grammar.package ? [`import { ${factory} } from "${grammar.package}"`] : []),
+        '',
+        'const be = loadBePackages(import.meta.url)',
+        'const fe = loadFePackages(import.meta.url)',
+        '',
+        `export default [...(await starciBePackagesConfig({ hfs: be })), ...starciFePackagesConfig({ hfs: fe })${grammar.package ? `, ...${factory}({ hfs: fe })` : ''}]`,
+        '',
+    ].join(LINE);
+    return [{ path: PACKAGES_LINT_FILE, scope: APP_SCOPE, mode: 'file', content, hash: hashOf(content) }];
+}
 export function variables(app, scope, presets, sonarKey, manifest = loadSlotManifest(), source = { files: [], read: () => '' }) {
     const stack = source.stack ?? { images: [], passEnv: [] };
     const fe = app.sides.fe;
@@ -429,7 +456,9 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
         typecheck: `${modulesFirst}npm run codegen --silent && tsc -p be/tsconfig.json && turbo run typecheck`,
         // The typed lint reads the types the fe packages declare (their dist), so the packages are built first.
         lintPrefix: `${modulesFirst}${packages ? 'npm run codegen --silent && turbo run build --filter=./fe/packages/* && ' : 'npm run codegen --silent && '}`,
-        moduleTests: modules.length ? ' && npm run test:modules' : '',
+        // The unit run, the back-end build and every CI job that imports a module package find it built (build:modules precedes them); the logic of a package is held at 100 per file by its own jest run, a step of the fast job.
+        modulesFirst,
+        moduleTestStep: modules.length ? '      - name: module packages\n        run: npm run test:modules\n' : '',
         nodeMajor: String(NODE_MAJOR),
         // The deploy server's age identity the restore workflow writes (stack/server-key.mjs owns the path).
         serverAgeIdentity: SERVER_AGE_IDENTITY,
@@ -503,7 +532,7 @@ function renderOnce(hfs, presets, { sonarKey, readTemplate = readBundled, manife
             declaredTargets.push({ path: 'README.md', mode: 'block', markdown: true, template: 'app/readme-badges/README.md' });
         const targets = declaredTargets
             .filter(target => !(app.edition === 'lite' && source?.workPresent === false && target.path === '.starciwork/.gitignore'));
-        return [...(scope === APP_SCOPE ? registryTargets(app, source) : []), ...targets.map((target) => {
+        return [...(scope === APP_SCOPE ? [...registryTargets(app, source), ...packagesLintTargets(app, source)] : []), ...targets.map((target) => {
                 const template = target.path === 'codecov.yml' && source?.quality?.codecov.enabled === false
                     ? '{{header}}\n# Codecov is disabled in the manifest.\ncodecov:\n  require_ci_to_pass: false\n'
                     : readTemplate(target.template);
@@ -657,6 +686,8 @@ const LITE_RETIRED_DIRS = Object.freeze(['supabase/types']);
 /** The files a lite app's sync retires, each with the reason the dry run prints. */
 const LITE_RETIRED_FILES = Object.freeze({
     [RETIRED_DB_DOCKERFILE]: `the db image moved to ${DB_DOCKERFILE} (ruling lite-db-image-in-stacks)`,
+    'be/src/modules/domain/identity/persistence/entities/auth-user.entity.ts': 'the sign-in reaches accounts through the account doors (be/src/modules/domain/identity/persistence/account-doors.port.ts); the application role holds no grant on schema auth',
+    'be/src/modules/domain/identity/persistence/entities/auth-identity.entity.ts': 'the sign-in reaches accounts through the account doors (be/src/modules/domain/identity/persistence/account-doors.port.ts); the application role holds no grant on schema auth',
     '.github/workflows/db-deploy.yml': 'the stack deploy migrates the database (a verified backup, the expand migrations before the services, the contract migrations after the accept; ruling app-cicd-auto-deploy)',
 });
 /** Why a retired file goes: a retired file's own reason, else the folder's. */

package/templates/app/auth-doors.sql.partial

@@ -0,0 +1,115 @@
+-- The account doors of a lite app: the only way app_be reaches auth.users and auth.identities (it holds no grant on schema auth). Eight
+-- SECURITY DEFINER functions with a pinned search_path, EXECUTE revoked from public and the browser roles and granted to app_be alone: an
+-- account comes back only for an exact address or id, a hash only for an exact address, and no door writes role or app metadata; the hash
+-- is written only by a new account and by be_auth_set_password.
+-- The text is the canon owner of the doors (templates/app/auth-doors.sql.partial); the back end calls them through persistence/account-doors.port.ts.
+
+-- Looks up an address in lower case; the bootstrap index serves email as written, not lower(email).
+create index if not exists users_email_lower_idx on auth.users (lower(email)) where is_anonymous = false;
+
+-- A person by sign-in address (lower-cased), with the stored bcrypt hash so the back end can verify it.
+CREATE FUNCTION public.be_auth_user_by_email(p_email text)
+    RETURNS TABLE(id uuid, email text, encrypted_password text, email_confirmed_at timestamp with time zone, disabled boolean)
+    LANGUAGE sql STABLE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  select u.id, u.email::text, u.encrypted_password::text, u.email_confirmed_at,
+         (u.deleted_at is not null or (u.banned_until is not null and u.banned_until > now()))
+    from auth.users u
+   where lower(u.email) = p_email and u.is_anonymous = false
+   order by u.created_at asc nulls last
+   limit 1;
+$$;
+
+-- One person by id.
+CREATE FUNCTION public.be_auth_user_by_id(p_user uuid)
+    RETURNS TABLE(id uuid, email text, last_sign_in_at timestamp with time zone, meta jsonb, disabled boolean)
+    LANGUAGE sql STABLE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  select u.id, u.email::text, u.last_sign_in_at, coalesce(u.raw_user_meta_data, '{}'::jsonb),
+         (u.deleted_at is not null or (u.banned_until is not null and u.banned_until > now()))
+    from auth.users u where u.id = p_user;
+$$;
+
+-- The person a Google account is linked to, if any.
+CREATE FUNCTION public.be_auth_user_by_google(p_provider_id text) RETURNS uuid
+    LANGUAGE sql STABLE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  select i.user_id from auth.identities i where i.provider = 'google' and i.provider_id = p_provider_id limit 1;
+$$;
+
+-- Creates a person; a null hash is an invited or Google-only account that has no password yet.
+CREATE FUNCTION public.be_auth_create_user(p_id uuid, p_email text, p_hash text, p_confirmed boolean, p_meta jsonb, p_now timestamp with time zone)
+    RETURNS uuid
+    LANGUAGE sql VOLATILE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  insert into auth.users (instance_id, id, aud, role, email, encrypted_password, email_confirmed_at, invited_at,
+                          raw_app_meta_data, raw_user_meta_data, created_at, updated_at)
+  values ('00000000-0000-0000-0000-000000000000', p_id, 'authenticated', 'authenticated', p_email, p_hash,
+          case when p_confirmed then p_now end, case when p_hash is null and not p_confirmed then p_now end,
+          '{"provider":"email","providers":["email"]}'::jsonb, p_meta, p_now, p_now)
+  returning id;
+$$;
+
+-- Links a Google account to a person.
+CREATE FUNCTION public.be_auth_link_google(p_user uuid, p_provider_id text, p_data jsonb, p_now timestamp with time zone) RETURNS void
+    LANGUAGE sql VOLATILE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  insert into auth.identities (provider_id, user_id, identity_data, provider, last_sign_in_at, created_at, updated_at)
+  values (p_provider_id, p_user, p_data, 'google', p_now, p_now, p_now)
+  on conflict (provider_id, provider) do update set last_sign_in_at = p_now, updated_at = p_now;
+$$;
+
+-- Records a sign-in; a verified Google address also confirms the mailbox; profile keys only fill what the person has not set.
+CREATE FUNCTION public.be_auth_touch_user(p_user uuid, p_now timestamp with time zone, p_confirm boolean, p_meta jsonb) RETURNS void
+    LANGUAGE sql VOLATILE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  update auth.users
+     set last_sign_in_at = p_now,
+         updated_at = p_now,
+         email_confirmed_at = case when p_confirm then coalesce(email_confirmed_at, p_now) else email_confirmed_at end,
+         raw_user_meta_data = p_meta || coalesce(raw_user_meta_data, '{}'::jsonb)
+   where id = p_user;
+$$;
+
+-- Stamps the confirmation of a mailbox (a spent confirmation link); a mailbox that is already confirmed keeps its date and the sign-in record is untouched.
+CREATE FUNCTION public.be_auth_confirm_user(p_user uuid, p_now timestamp with time zone) RETURNS void
+    LANGUAGE sql VOLATILE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  update auth.users set email_confirmed_at = coalesce(email_confirmed_at, p_now), updated_at = p_now where id = p_user;
+$$;
+
+-- Sets a new password hash; when p_confirm is true (a spent reset link proved the mailbox) the address is confirmed too.
+CREATE FUNCTION public.be_auth_set_password(p_user uuid, p_hash text, p_confirm boolean, p_now timestamp with time zone) RETURNS void
+    LANGUAGE sql VOLATILE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  update auth.users
+     set encrypted_password = p_hash,
+         email_confirmed_at = case when p_confirm then coalesce(email_confirmed_at, p_now) else email_confirmed_at end,
+         updated_at = p_now
+   where id = p_user;
+$$;
+
+REVOKE EXECUTE ON FUNCTION public.be_auth_user_by_email(text) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_user_by_email(text) TO app_be;
+REVOKE EXECUTE ON FUNCTION public.be_auth_user_by_id(uuid) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_user_by_id(uuid) TO app_be;
+REVOKE EXECUTE ON FUNCTION public.be_auth_user_by_google(text) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_user_by_google(text) TO app_be;
+REVOKE EXECUTE ON FUNCTION public.be_auth_create_user(uuid, text, text, boolean, jsonb, timestamp with time zone) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_create_user(uuid, text, text, boolean, jsonb, timestamp with time zone) TO app_be;
+REVOKE EXECUTE ON FUNCTION public.be_auth_link_google(uuid, text, jsonb, timestamp with time zone) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_link_google(uuid, text, jsonb, timestamp with time zone) TO app_be;
+REVOKE EXECUTE ON FUNCTION public.be_auth_touch_user(uuid, timestamp with time zone, boolean, jsonb) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_touch_user(uuid, timestamp with time zone, boolean, jsonb) TO app_be;
+REVOKE EXECUTE ON FUNCTION public.be_auth_confirm_user(uuid, timestamp with time zone) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_confirm_user(uuid, timestamp with time zone) TO app_be;
+REVOKE EXECUTE ON FUNCTION public.be_auth_set_password(uuid, text, boolean, timestamp with time zone) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_set_password(uuid, text, boolean, timestamp with time zone) TO app_be;

package/templates/app/ci-workflows/github/workflows/ci.yml

@@ -92,7 +92,7 @@ jobs:
         run: npm run typecheck
         env:
           NODE_OPTIONS: {{nodeOptions}}
-
+{{moduleTestStep}}
   lint:
     needs: plan
     if: ${{ needs.plan.outputs.checks == 'true' }}

package/templates/app/ci-workflows-lite/github/workflows/ci.yml

@@ -92,7 +92,7 @@ jobs:
         run: npm run typecheck
         env:
           NODE_OPTIONS: {{nodeOptions}}
-
+{{moduleTestStep}}
   lint:
     needs: plan
     if: ${{ needs.plan.outputs.checks == 'true' }}

package/templates/app/package-scripts/core.json

@@ -1,4 +1,4 @@
-    "build:be": "cd be && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "build:be": "{{modulesFirst}}cd be && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
     "build:fe": "{{buildFe}}",
     "codegen": "node scripts/codegen.mjs",
     "codegen:graphql": "node scripts/codegen.mjs --graphql",

package/templates/app/package-scripts/package.json

@@ -4,7 +4,7 @@
     {{appScripts}}
 {{> app/package-scripts/core.json}}
     "typecheck:tests": "tsc -p be/src/tests/tsconfig.json",
-    "test": "cd be && jest --selectProjects unit --coverage{{moduleTests}}",
+    "test": "{{modulesFirst}}cd be && jest --selectProjects unit --coverage",
     "test:integration": "npm run typecheck:tests && cd be && jest --selectProjects integration",
     "test:e2e": "npm run typecheck:tests && cd be && jest --selectProjects e2e",
     "test:contract": "npm run typecheck:tests && cd be && jest --selectProjects contract",

package/templates/app/package-scripts-lite/package.json

@@ -4,7 +4,7 @@
     {{appScripts}}
 {{> app/package-scripts/core.json}}
     "typecheck:tests": "tsc -p be/src/tests/tsconfig.json",
-    "test": "cd be && jest --selectProjects unit --coverage{{moduleTests}}",
+    "test": "{{modulesFirst}}cd be && jest --selectProjects unit --coverage",
     "test:integration": "npm run typecheck:tests && cd be && jest --selectProjects integration",
 {{> app/package-scripts/db.json}}
 {{backingScripts}}

package/templates/app/skeleton-lite/.starcistacks/application-stacks.yaml

@@ -58,8 +58,11 @@ environments:
         db: 54322
         api: 3001
         web: 3000
+        mail: 1025
+        mailui: 8025
       services:
         - {name: db, wait: healthy}
+        - {name: mail, wait: healthy}
       database:
         service: db
         port: db
@@ -97,6 +100,11 @@ environments:
             AUTH_WEB_ORIGIN: "http://localhost:${port.web}"
             AUTH_JWT_AUDIENCE: {{project}}
             AUTH_JWT_KEY_ID: dev-1
+            MAIL_HOST: 127.0.0.1
+            MAIL_PORT: "${port.mail}"
+            MAIL_SECURITY: none
+            MAIL_FROM: no-reply@{{project}}.example.invalid
+            MAIL_FROM_NAME: {{project}}
             STORAGE_ENDPOINT: "http://127.0.0.1:9000"
             STORAGE_REGION: us-east-1
             STORAGE_BUCKET: {{project}}-dev
@@ -120,6 +128,7 @@ environments:
       origins:
         - {name: web, url: "http://localhost:${port.web}"}
         - {name: api, url: "http://localhost:${port.api}"}
+        - {name: mail, url: "http://localhost:${port.mailui}"}
   production:
     status: supported
     runtime: docker-swarm

package/templates/app/skeleton-lite/.starcistacks/dev/README.md

@@ -2,7 +2,7 @@
 
 The dev environment is one command: `starci app stack up --env dev --execute`. It checks the machine, opens the dev custody, runs the setup
 commands, starts the dependencies in Docker Linux containers (the `db` service: the official postgres image plus pgvector, built from
-`.starcistacks/images/db/Dockerfile`), gives the environment its own database role, migrates, runs the seed, starts the api and web
+`.starcistacks/images/db/Dockerfile`; the `mail` service: Mailpit, the dev mail sink), gives the environment its own database role, migrates, runs the seed, starts the api and web
 processes natively and waits for readiness. What it runs is the `local` block of `environments.dev` in `.starcistacks/application-stacks.yaml`
 (PROJECT-STACKS-6 in contexts/project/stacks.md); this runbook never carries a docker command, an agent never runs docker by hand.
 
@@ -26,5 +26,7 @@ another environment.
 | down | `starci app stack down --env dev --execute`: ends the processes and stops the compose project; volumes and sealed values stay. |
 | verification | `starci app stack verify --env dev`: the declared liveness and readiness probes after a real start, then `npm run lint` from the app root. |
 
+**Mail.** The confirmation and reset mails of the sign-in go to the `mail` service on its SMTP port (`MAIL_HOST`, `MAIL_PORT`, `MAIL_SECURITY: none`: a plain channel that only the loopback sink accepts) and nothing leaves the machine. Open the web UI at the `mail` origin `up` prints (`http://localhost:8025` by default), sign up in the web app and follow the link from the message there. A deployed environment names a real SMTP server and `MAIL_SECURITY: starttls` or `tls`.
+
 The database volume `db-data` is rebuildable development data: `starci app db migrate` recreates its schema from `db/bootstrap.sql` and
 `db/migrations`. Key names of the environment are in `.starcistacks/dev/runtime/env/KEYS.md`.

package/templates/app/skeleton-lite/.starcistacks/dev/infra/compose/compose.yaml

@@ -1,6 +1,8 @@
 # The dev environment's dependencies, run by `starci app stack up --env dev --execute` (PROJECT-STACKS-3, PROJECT-STACKS-6).
 # Host ports come from environments.dev.local.ports through STACK_PORT_<NAME>; the superuser password is read from a file through the least
-# grant STACK_GRANT_DB (a directory holding only POSTGRES_PASSWORD), never from the environment. Every port publishes on loopback only. The api and web run natively against these containers.
+# grant STACK_GRANT_DB (a directory holding only POSTGRES_PASSWORD), never from the environment. Every port publishes on loopback only.
+# `mail` is the dev mail sink (Mailpit, an unmodified upstream image pinned by digest in contexts/stack/pins.yaml): the api sends the
+# confirmation and reset mails to its SMTP port, over a plain channel that exists on loopback only, and a person reads them in its web UI. The api and web run natively against these containers.
 name: {{project}}-dev
 services:
   db:
@@ -21,5 +23,21 @@ services:
       retries: 30
       start_period: 10s
     restart: unless-stopped
+  mail:
+    image: axllent/mailpit:v1.31.6@sha256:23fe39e81bde596a918000b3135c0f85dc8bb4c9ea6be274b051143f3e300387
+    environment:
+      MP_SMTP_BIND_ADDR: 0.0.0.0:1025
+      MP_UI_BIND_ADDR: 0.0.0.0:8025
+      MP_MAX_MESSAGES: "500"
+    ports:
+      - "127.0.0.1:${STACK_PORT_MAIL}:1025"
+      - "127.0.0.1:${STACK_PORT_MAILUI}:8025"
+    healthcheck:
+      test: ["CMD", "/mailpit", "readyz"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+      start_period: 5s
+    restart: unless-stopped
 volumes:
   db-data: {}

package/templates/app/skeleton-lite/.starcistacks/dev/runtime/env/KEYS.md

@@ -18,5 +18,8 @@ Names only. Dev values are generated once by the owner-armed `starci app secret
 | `AUTH_JWT_PRIVATE_KEY` | API Ed25519 (EdDSA) signing key (member `auth`) |
 | `STORAGE_ENDPOINT`, `STORAGE_REGION`, `STORAGE_BUCKET` | API storage address |
 | `STORAGE_ACCESS_KEY_ID`, `STORAGE_SECRET_ACCESS_KEY` | API storage credentials (member `storage`) |
+| `MAIL_HOST`, `MAIL_PORT`, `MAIL_SECURITY`, `MAIL_FROM`, `MAIL_FROM_NAME` | API outgoing mail server (the dev `mail` service, Mailpit, on its SMTP port: a plain channel on loopback only) and the sender of the confirmation and reset mails |
+| `MAIL_DEFAULT_LANGUAGE`, `MAIL_CONFIRM_TTL_SECONDS`, `MAIL_RESET_TTL_SECONDS` | API mail language (`vi` or `en`) and link lifetimes; optional |
+| `MAIL_USER`, `MAIL_PASSWORD` | API mail server login; optional, the password reads `MAIL_PASSWORD_FILE` |
 | `NEXT_PUBLIC_SITE_URL`, `NEXT_PUBLIC_API_URL`, `NEXT_PUBLIC_GRAPHQL_URL` | Front-end site, auth doors and GraphQL transport |
 | `DATABASE_URL` | `starci app db` verbs; the stack verb composes it in memory for the migration |

package/templates/app/skeleton-lite/.starcistacks/production/infra/swarm/stack.yaml

@@ -17,6 +17,11 @@ services:
       AUTH_JWT_KEY_ID: production-1
       AUTH_COOKIE_DOMAIN: {{project}}.example.invalid
       AUTH_JWT_PRIVATE_KEY_FILE: /run/secrets/auth-jwt-private-key
+      MAIL_HOST: smtp.{{project}}.example.invalid
+      MAIL_PORT: "587"
+      MAIL_SECURITY: starttls
+      MAIL_FROM: no-reply@{{project}}.example.invalid
+      MAIL_FROM_NAME: {{project}}
       STORAGE_ENDPOINT: https://storage.{{project}}.example.invalid
       STORAGE_REGION: us-east-1
       STORAGE_BUCKET: {{project}}-production

package/templates/app/skeleton-lite/.starcistacks/production/runtime/env/KEYS.md

@@ -23,6 +23,10 @@ This inventory declares names, consumers and mounted file paths. Scaffolding gen
 | `STORAGE_BUCKET` | API storage bucket |
 | `STORAGE_ACCESS_KEY_ID` | API storage credential; reads `STORAGE_ACCESS_KEY_ID_FILE` at `/run/secrets/storage-access-key-id` |
 | `STORAGE_SECRET_ACCESS_KEY` | API storage credential; reads `STORAGE_SECRET_ACCESS_KEY_FILE` at `/run/secrets/storage-secret-access-key` |
+| `MAIL_HOST`, `MAIL_PORT`, `MAIL_SECURITY` | API outgoing mail server and how its channel is secured (`starttls` is required to succeed, `tls` is implicit TLS) |
+| `MAIL_FROM`, `MAIL_FROM_NAME` | API sender address and name of the confirmation and reset mails |
+| `MAIL_DEFAULT_LANGUAGE`, `MAIL_CONFIRM_TTL_SECONDS`, `MAIL_RESET_TTL_SECONDS` | API mail language (`vi` or `en`) and link lifetimes; optional |
+| `MAIL_USER`, `MAIL_PASSWORD` | API mail server login; optional, the password reads `MAIL_PASSWORD_FILE` at `/run/secrets/mail-password` |
 | `DATABASE_URL` | `starci app db` verbs (migrate, dump) and `contract:emit`, from the operator's environment |
 | `NEXT_PUBLIC_SITE_URL` | Front-end site URL |
 | `NEXT_PUBLIC_API_URL` | Front-end auth doors of the API |

package/templates/app/skeleton-lite/db/migrations/__timestamp___baseline.sql

@@ -24,10 +24,6 @@ begin
 end;
 $$;
 
-grant usage on schema auth to app_be;
-grant select, insert, update on table auth.users to app_be;
-grant select, insert on table auth.identities to app_be;
-
 -- The device sessions and rotating refresh tokens of @starci/auth. A token is stored by its sha256 only; a rotated token stays,
 -- marked used, so a replay is detected (a replay inside the grace window is a racing tab, an older one ends the session).
 -- identity_attempts counts the sign-in attempts of one address in a window every replica shares (the budget of failures).
@@ -87,6 +83,30 @@ create policy identity_refresh_tokens_app_be_all on public.identity_refresh_toke
 create policy identity_attempts_app_be_all on public.identity_attempts
     for all to app_be using (current_user = 'app_be') with check (current_user = 'app_be');
 
+{{> app/auth-doors.sql.partial}}
+
+-- The single-use links that confirm a mailbox or reset a password (the email doors of sign-in): only the sha256 of the token is
+-- stored, a spent link stays marked used, and a new link of the same purpose ends the older ones.
+create table public.identity_email_tokens (
+    id uuid primary key,
+    user_id uuid not null references auth.users (id) on delete cascade,
+    purpose varchar(16) not null check (purpose in ('confirm', 'reset')),
+    token_hash varchar(64) not null,
+    expires_at timestamptz not null,
+    used_at timestamptz,
+    created_at timestamptz not null,
+    constraint identity_email_tokens_hash_key unique (token_hash)
+);
+
+create index identity_email_tokens_user_idx on public.identity_email_tokens (user_id, purpose);
+
+alter table public.identity_email_tokens enable row level security;
+alter table public.identity_email_tokens force row level security;
+revoke all on table public.identity_email_tokens from public;
+grant select, insert, update, delete on table public.identity_email_tokens to app_be;
+create policy identity_email_tokens_app_be_all on public.identity_email_tokens
+    for all to app_be using (current_user = 'app_be') with check (current_user = 'app_be');
+
 create table public.profiles (
     id uuid primary key references auth.users (id) on delete cascade,
     display_name text not null check (char_length(display_name) between 1 and 120),

package/templates/be/auth-lite/src/features/api/auth/application/auth.contracts.ts

@@ -1,4 +1,5 @@
 // Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import type { MailLanguage } from "@modules/integrations/mail"
 import type { HttpExchange } from "@modules/integrations/passport"
 
 /** One cookie door of sign-in: the request and response the strategy or the refresh cookie work on. */
@@ -9,3 +10,35 @@ export interface ExchangeRequest {
 
 /** A request with nothing in it. */
 export type EmptyRequest = Record<string, never>
+
+/** The posted data of the signup door. */
+export interface SignupData {
+    /** The sign-in address. */
+    readonly email: string
+    /** The chosen password. */
+    readonly password: string
+    /** The language of the confirmation mail, when the request names one. */
+    readonly language: MailLanguage | undefined
+}
+
+/** The posted data of the resend and forgot doors. */
+export interface AddressData {
+    /** The address the mail goes to. */
+    readonly email: string
+    /** The language of the mail, when the request names one. */
+    readonly language: MailLanguage | undefined
+}
+
+/** The link token of the confirm door. */
+export interface TokenData {
+    /** The token the link carries. */
+    readonly token: string
+}
+
+/** The posted data of the reset door. */
+export interface ResetData {
+    /** The token the link carries. */
+    readonly token: string
+    /** The new password. */
+    readonly password: string
+}

package/templates/be/auth-lite/src/features/api/auth/application/confirm.command.ts

@@ -0,0 +1,11 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { Command } from "@nestjs/cqrs"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { TokenData } from "./auth.contracts"
+
+/** Spends a confirmation link and confirms the mailbox. */
+export class ConfirmCommand extends Command<void> {
+    constructor(readonly params: PublicExecuteParams<TokenData>) {
+        super()
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/confirm.handler.ts

@@ -0,0 +1,22 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { CommandHandler } from "@nestjs/cqrs"
+import { IdentityEmailService } from "@modules/domain/identity"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { ConfirmCommand } from "./confirm.command"
+
+@CommandHandler(ConfirmCommand)
+/** Spends a confirmation link and confirms the mailbox. */
+export class ConfirmHandler extends ICQRSHandler<ConfirmCommand, void> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly email: IdentityEmailService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: ConfirmCommand): Promise<void> {
+        return this.email.confirm(command.params.request.token)
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/forgot.command.ts

@@ -0,0 +1,11 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { Command } from "@nestjs/cqrs"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { AddressData } from "./auth.contracts"
+
+/** Mails a password reset link when the address has an account; the answer never says whether it does. */
+export class ForgotCommand extends Command<void> {
+    constructor(readonly params: PublicExecuteParams<AddressData>) {
+        super()
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/forgot.handler.ts

@@ -0,0 +1,22 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { CommandHandler } from "@nestjs/cqrs"
+import { IdentityEmailService } from "@modules/domain/identity"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { ForgotCommand } from "./forgot.command"
+
+@CommandHandler(ForgotCommand)
+/** Mails a password reset link when the address has an account; the answer never says whether it does. */
+export class ForgotHandler extends ICQRSHandler<ForgotCommand, void> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly email: IdentityEmailService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: ForgotCommand): Promise<void> {
+        return this.email.forgot(command.params.request.email, command.params.request.language)
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/resend.command.ts

@@ -0,0 +1,11 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { Command } from "@nestjs/cqrs"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { AddressData } from "./auth.contracts"
+
+/** Mails a new confirmation link to an unconfirmed account; the answer never says whether the address has one. */
+export class ResendCommand extends Command<void> {
+    constructor(readonly params: PublicExecuteParams<AddressData>) {
+        super()
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/resend.handler.ts

@@ -0,0 +1,22 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { CommandHandler } from "@nestjs/cqrs"
+import { IdentityEmailService } from "@modules/domain/identity"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { ResendCommand } from "./resend.command"
+
+@CommandHandler(ResendCommand)
+/** Mails a new confirmation link to an unconfirmed account; the answer never says whether the address has one. */
+export class ResendHandler extends ICQRSHandler<ResendCommand, void> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly email: IdentityEmailService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: ResendCommand): Promise<void> {
+        return this.email.resend(command.params.request.email, command.params.request.language)
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/reset.command.ts

@@ -0,0 +1,11 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { Command } from "@nestjs/cqrs"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { ResetData } from "./auth.contracts"
+
+/** Spends a reset link: sets the new password and ends every session of the person. */
+export class ResetCommand extends Command<void> {
+    constructor(readonly params: PublicExecuteParams<ResetData>) {
+        super()
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/reset.handler.ts

@@ -0,0 +1,22 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { CommandHandler } from "@nestjs/cqrs"
+import { IdentityEmailService } from "@modules/domain/identity"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { ResetCommand } from "./reset.command"
+
+@CommandHandler(ResetCommand)
+/** Spends a reset link: sets the new password and ends every session of the person. */
+export class ResetHandler extends ICQRSHandler<ResetCommand, void> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly email: IdentityEmailService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: ResetCommand): Promise<void> {
+        return this.email.reset(command.params.request.token, command.params.request.password)
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/signup.command.ts

@@ -0,0 +1,11 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { Command } from "@nestjs/cqrs"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { SignupData } from "./auth.contracts"
+
+/** Creates an unconfirmed password account and mails the confirmation link; the answer never says whether the address already had an account. */
+export class SignupCommand extends Command<void> {
+    constructor(readonly params: PublicExecuteParams<SignupData>) {
+        super()
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/signup.handler.ts

@@ -0,0 +1,22 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { CommandHandler } from "@nestjs/cqrs"
+import { IdentityEmailService } from "@modules/domain/identity"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { SignupCommand } from "./signup.command"
+
+@CommandHandler(SignupCommand)
+/** Creates an unconfirmed password account and mails the confirmation link; the answer never says whether the address already had an account. */
+export class SignupHandler extends ICQRSHandler<SignupCommand, void> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly email: IdentityEmailService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: SignupCommand): Promise<void> {
+        return this.email.signup(command.params.request.email, command.params.request.password, command.params.request.language)
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/auth.module-definition.ts

@@ -1,13 +1,6 @@
-// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineConfigurableModule } from "@starci/nest-kit"
 import type { AuthApiOptions } from "./auth.options"
 
-const built = new ConfigurableModuleBuilder<AuthApiOptions>().setClassMethodName("register").build()
-type Host = ConfigurableModuleHost<AuthApiOptions, "register", "create", {}>
-
 /** The configurable-module base of the auth feature module. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The injection token of the registered options. */
-export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    defineConfigurableModule<AuthApiOptions>()