@starci/hfs 4.11.11 → 4.11.13

package/scaffold/app.mjs

@@ -353,13 +353,25 @@ const CLI_APP_DIR = 'apps/cli/';
 const declaresCliApp = app => app.sides.be.apps.some(entry => entry.kind === 'cli' && entry.name === 'cli');
 
 const LITE_APP_REUSED = new Set(['.editorconfig', '.gitattributes', '.nvmrc']);
+/**
+ * The lite be files a generator writes when it first needs them, never the starter: the cli's runners, the in-order relay, and the
+ * raw SQL helpers of platform/database (the sql tag, and the database-function call statement with its spec), which only the table,
+ * queue, jobs and webhook capabilities call; a fresh app reads and writes through entities alone (R334).
+ */
 const LITE_DEFERRED_GENERATOR_FILES = new Set([
+  'src/modules/platform/database/database.client.ts',
+  'src/modules/platform/database/database.client.spec.ts',
+  'src/modules/platform/database/database.sql.ts',
   'src/modules/platform/database/migration-runner.service.ts',
   'src/modules/platform/database/seed-runner.service.ts',
   'src/modules/platform/primitives/sequence.policy.ts',
 ]);
-/** The TypeORM schema files of a platform capability: lite's schema authority is db/migrations (be.persistence lite overlay). */
-const LITE_TYPEORM_SCHEMA = /^src\/modules\/platform\/[^/]+\/persistence\/(?:connection\.ts$|entities\/|migrations\/)/;
+/**
+ * The persistence folder of a full platform capability (TypeORM migrations, connection arrays, `sql`-tagged statements and rows):
+ * lite's schema authority is db/migrations and its code reads and writes through entities (be.persistence lite overlay, R334), so a
+ * lite platform capability takes its persistence/ from the lite overlay alone.
+ */
+const FULL_PLATFORM_PERSISTENCE = /^src\/modules\/platform\/[^/]+\/persistence\//;
 const liteBaseSource = (rel) => !rel.startsWith('apps/cli/')
     && !rel.startsWith('src/features/cli/')
     && !rel.startsWith('src/modules/domain/note/')
@@ -367,7 +379,7 @@ const liteBaseSource = (rel) => !rel.startsWith('apps/cli/')
     && rel !== 'src/modules/platform/database/migrate-connections.client.ts'
     && rel !== 'src/modules/platform/database/seed-connections.client.ts'
     && !LITE_DEFERRED_GENERATOR_FILES.has(rel)
-    && !LITE_TYPEORM_SCHEMA.test(rel)
+    && !FULL_PLATFORM_PERSISTENCE.test(rel)
     && !rel.startsWith('src/tests/');
 /** The be files the lite overlay replaces: a base unit spec of such a file tests the full variant, so lite carries its own. */
 const liteOverlaid = (() => {

package/scaffold/lite-exports.mjs

@@ -51,6 +51,22 @@ const REGISTRATIONS = Object.freeze({
       names: ["sql"],
       beforeSource: "./errors/database.error",
     },
+    {
+      // The outbox write and the relay call the queue functions of their migration (R334).
+      file: "be/src/modules/platform/database/index.ts",
+      source: "./database.client",
+      names: ["callDbFunction"],
+      beforeSource: "./primary.decorators",
+    },
+  ],
+  // The jobs capability (add job, the fenced-job pattern): its tick takes a transaction-scoped lock before it claims the minute (R335).
+  jobs: [
+    {
+      file: "be/src/modules/platform/database/index.ts",
+      source: "./database.client",
+      names: ["advisoryXactLock", "callDbFunction"],
+      beforeSource: "./primary.decorators",
+    },
   ],
   webhook: [
     {
@@ -59,6 +75,13 @@ const REGISTRATIONS = Object.freeze({
       names: ["BATCH_ROWS", "sql"],
       beforeSource: "./errors/database.error",
     },
+    {
+      // The inbox claim and the lite event bus call the functions of their migration (R334).
+      file: "be/src/modules/platform/database/index.ts",
+      source: "./database.client",
+      names: ["callDbFunction"],
+      beforeSource: "./primary.decorators",
+    },
     {
       // PRIMARY_ENTITY_MANAGER: the token the inbox service's unit spec provides its EntityManager double under.
       file: "be/src/modules/platform/database/index.ts",

package/src/main.mjs

@@ -435,8 +435,8 @@ function declaredEdition(cwd) {
  * `starci app stack`: the deploy actions (prepare, doctor, render, deploy, converge, verify, rollback, prune, backup, jobs, ...) are the Swarm
  * tooling of stack/cli.mjs; up, down and status are the full edition's test-world infrastructure.
  */
-async function stackAppMain(argv, { cwd, edition, stackMain, stdout: out, stderr: err, env, sops, stackIo }) {
-  if (STACK_ACTIONS.includes(argv[0])) return deployStackMain(argv, { ...stackIo, cwd, stdout: out, stderr: err, env, ...(sops ? { sops } : {}) });
+async function stackAppMain(argv, { cwd, edition, stackMain, stdout: out, stderr: err, env, sops, hostIdentity, stackIo }) {
+  if (STACK_ACTIONS.includes(argv[0])) return deployStackMain(argv, { ...stackIo, cwd, stdout: out, stderr: err, env, hostIdentity, ...(sops ? { sops } : {}) });
   if ((edition ?? declaredEdition(cwd)) === 'lite') throw new Error('starci app stack up|down|status manage the local test world of the full edition; a lite app starts its local database with npm run db:start');
   const run = stackMain ?? await installedStackMain(cwd);
   return run(argv, { cwd, out, err });
@@ -462,7 +462,7 @@ function errorMessage(error) {
  * `harness` ({ version }) is the CLI that runs this package in-process: its version is the starci-harness an app is judged and
  * scaffolded at (runtime/scripts/hfs/canon-pins.mjs). `run` injects the database runner, `runLinter` the linter transport, `checkApp`
  * the HFS check and `stackIo` Swarm tools; production defaults execute every check. `hostIdentity` ({ label, read }) is the
- * harness CLI's own secret.env SOPS_AGE_KEY, which `secret` reads last for the age identity; `prompt` replaces its masked prompt.
+ * harness CLI's own secret.env SOPS_AGE_KEY, which every verb that opens a sealed member (secret, stack, release, db) reads last for the age identity (decryptionIdentity); `prompt` replaces its masked prompt.
  */
 export async function main(argv, {
   cwd: baseCwd = process.cwd(), harness, stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier, lock, run, stackMain,

package/stack/age-install.mjs

@@ -17,10 +17,18 @@ const STATIC_INSTALL = [
   `echo "${AGE_SHA256}  $tmp/age.tgz" | sha256sum -c -`,
   'tar -xzf "$tmp/age.tgz" -C "$tmp"',
   'sudo -n install -m 0755 "$tmp/age/age" "$tmp/age/age-keygen" /usr/local/bin/',
+  // sudo's secure_path (AlmaLinux 10, RHEL) leaves /usr/local/bin out: a link in /usr/bin makes both tools visible to the deploy
+  // user and to root alike; an existing /usr/bin tool (a packaged age) is kept.
+  'for b in age age-keygen; do if [ ! -e "/usr/bin/$b" ]; then sudo -n ln -s "/usr/local/bin/$b" "/usr/bin/$b"; fi; done',
 ].join('; ');
 
 const packageManager = (run) => run('for m in dnf yum apk apt-get; do command -v $m >/dev/null 2>&1 && echo $m && break; done').stdout.trim();
-const present = (run) => run('command -v age').status === 0;
+/**
+ * Both tools, as the deploy user and, where passwordless sudo exists, as root: an install the root PATH cannot see is not taken
+ * for present.
+ */
+const PRESENT = 'command -v age >/dev/null 2>&1 && command -v age-keygen >/dev/null 2>&1 && { [ "$(id -u)" -eq 0 ] || ! sudo -n true 2>/dev/null || sudo -n sh -c \'command -v age >/dev/null 2>&1 && command -v age-keygen >/dev/null 2>&1\'; }';
+const present = (run) => run(PRESENT).status === 0;
 
 /** Installs age when it is missing; reports through `report`. */
 export function installAge(run, report) {
@@ -33,6 +41,6 @@ export function installAge(run, report) {
     failure = `${manager} could not install age: ${firstLine(packaged.stderr)}`;
   }
   const fetched = run(STATIC_INSTALL);
-  if (fetched.status === 0 && present(run)) report.note(`installed the official static age ${AGE_VERSION} (sha256 verified) into /usr/local/bin; ${failure}`);
+  if (fetched.status === 0 && present(run)) report.note(`installed the official static age ${AGE_VERSION} (sha256 verified) into /usr/local/bin, linked from /usr/bin; ${failure}`);
   else report.bad(`cannot install age (${failure}); the static install failed too: ${firstLine(fetched.stderr)} (needs passwordless sudo once, or install age by hand)`);
 }

package/stack/context.mjs

@@ -57,7 +57,7 @@ const realSleep = (ms) => new Promise((done) => { setTimeout(done, ms); });
  *   stdout, stderr text writers
  *   fetch          the HTTP seam of verify (url, init) -> Response
  *   pipe           (source, sink) -> Promise<{ source, sink, stderr }>: one process's stdout streamed into another's stdin (realPipe)
- *   sops           the secret seam (decrypt(file, format) -> map; decryptBinary(file) -> text); `io.sops`, else on first use `io.openSops()` or the app's own sops/age tools
+ *   sops           the secret seam (decrypt(file, format) -> map; decryptBinary(file) -> text); `io.sops`, else on first use `io.openSops()` or the app's own sops/age tools with the age identity decryptionIdentity finds (`io.hostIdentity` the harness CLI's secret.env)
  */
 export function stackContext(io = {}) {
   const cwd = io.cwd ?? process.cwd();
@@ -78,7 +78,7 @@ export function stackContext(io = {}) {
     pipe: io.pipe ?? realPipe,
     /** The secret seam: the app's own sops/age tools, created on first use so verbs that open no custody never need them. */
     get sops() {
-      sops ??= io.openSops?.() ?? defaultSops(env, cwd);
+      sops ??= io.openSops?.() ?? defaultSops(env, cwd, io.platform ?? process.platform, undefined, io.hostIdentity ?? null);
       return sops;
     },
   });

package/stack/remote.mjs

@@ -64,24 +64,36 @@ function sshCommandArgv(sshCmd) {
   return parts;
 }
 
-/** A sealed binary member is the file itself; a JSON object around it ({ data | <names> }, the re-sealed shape of `starci app secret rename`) is unwrapped. */
-function unwrap(text, names) {
+/**
+ * The key each sealed SSH member of `deploy.remote.sealed` holds (contexts/project/stacks.md PROJECT-STACKS-5): the one owner of
+ * these names. `sshKey` names the member whose `privateKey` is the PEM private key, `knownHosts` the member whose `knownHosts` is
+ * the pinned known_hosts text.
+ */
+export const SEALED_SSH_KEYS = Object.freeze({ sshKey: 'privateKey', knownHosts: 'knownHosts' });
+
+/** A legacy binary member is the file itself; a JSON object around it ({ data | <key> }, the re-sealed shape of `starci app secret rename`) is unwrapped. */
+function unwrap(text, key) {
   const body = lfOnly(text);
   const trimmed = body.trim();
   if (!trimmed.startsWith('{')) return body;
   let parsed;
   try { parsed = JSON.parse(trimmed); } catch { return body; }
-  for (const name of ['data', ...names]) if (typeof parsed[name] === 'string') return lfOnly(parsed[name]);
+  for (const name of ['data', key]) if (typeof parsed[name] === 'string') return lfOnly(parsed[name]);
   return body;
 }
 
+/** The sops format a sealed member is read as: a `.enc.yaml` member is YAML, a legacy `.enc` one dotenv. */
+const memberFormat = (file) => (isLegacyName(file) ? 'dotenv' : 'yaml');
+
+/** Opens one member through the sops seam; a failure is refused naming the member and the seam's own reason (format, recipients, identity). */
 function openMember(slug, read) {
   try { return read(); } catch (error) { throw refusal('STACK_REMOTE_SEALED', `cannot open the sealed member ${slug}: ${error.message}`); }
 }
 
 function opsAccount(ctx, config) {
   const slug = config.remote.sealed.ops;
-  const map = openMember(slug, () => ctx.sops.decrypt(memberFile(config.secretsDir, slug), isLegacyName(memberFile(config.secretsDir, slug)) ? 'dotenv' : 'yaml'));
+  const file = memberFile(config.secretsDir, slug);
+  const map = openMember(slug, () => ctx.sops.decrypt(file, memberFormat(file)));
   for (const name of ['VPS_HOST', 'VPS_USER']) {
     const value = map[name];
     if (typeof value !== 'string' || !ACCOUNT.test(value) || value.startsWith('-')) throw refusal('STACK_REMOTE_OPS', `${slug} must hold ${name} (letters, digits, . _ @ -)`);
@@ -89,8 +101,17 @@ function opsAccount(ctx, config) {
   return `${map.VPS_USER}@${map.VPS_HOST}`;
 }
 
-function binaryMember(ctx, config, slug, names) {
-  return unwrap(openMember(slug, () => ctx.sops.decryptBinary(memberFile(config.secretsDir, slug))), names);
+/**
+ * The text a sealed SSH member holds under `key` (SEALED_SSH_KEYS): a `.enc.yaml` member is read as YAML and the key taken from
+ * its map; a legacy `.enc` member is the sops binary or JSON envelope it was sealed as.
+ */
+function sshMember(ctx, config, slug, key) {
+  const file = memberFile(config.secretsDir, slug);
+  if (isLegacyName(file)) return unwrap(openMember(slug, () => ctx.sops.decryptBinary(file)), key);
+  const map = openMember(slug, () => ctx.sops.decrypt(file, 'yaml'));
+  if (typeof map[key] !== 'string' || map[key] === '')
+    throw refusal('STACK_REMOTE_SEALED', `the sealed member ${slug} holds no ${key} (it holds ${Object.keys(map).join(', ') || 'no key'}): seal it with starci app secret set ${config.env ?? '<env>'} ${slug} ${key} --from-file ${key}=<file>`);
+  return lfOnly(map[key]);
 }
 
 const withNewline = (text) => `${text.trim()}\n`;
@@ -107,9 +128,9 @@ export function openSealedSession(ctx, config) {
   const account = opsAccount(ctx, config);
   if (config.nativeTarget && account !== `${config.nativeTarget.user}@${config.nativeTarget.host}`)
     throw refusal('STACK_REMOTE_OPS', 'the sealed SSH account differs from the accepted native target');
-  const key = binaryMember(ctx, config, sealed.sshKey, ['privateKey', 'key']);
+  const key = sshMember(ctx, config, sealed.sshKey, SEALED_SSH_KEYS.sshKey);
   if (!key.includes('PRIVATE KEY')) throw refusal('STACK_REMOTE_KEY', `${sealed.sshKey} does not hold a PEM private key`);
-  const known = binaryMember(ctx, config, sealed.knownHosts, ['knownHosts', 'known_hosts']).trim();
+  const known = sshMember(ctx, config, sealed.knownHosts, SEALED_SSH_KEYS.knownHosts).trim();
   assertStackAccount(config.nativeTarget, account, known);
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-ssh-'));
   const keyFile = path.join(dir, 'id');

package/stack/sealed.mjs

@@ -5,7 +5,6 @@ import { createHash, createHmac } from 'node:crypto';
 import { memberFile } from '../runtime/scripts/lib/sealed-member.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
-import { secretRoots } from '../runtime/scripts/hfs/secret-files.mjs';
 import { readMap } from '../runtime/scripts/hfs/secret-store.mjs';
 import { refusal } from './errors.mjs';
 
@@ -52,27 +51,32 @@ function secretRuntimeName(stack, key, value, versionKey) {
   return name;
 }
 
-const AGE_IDENTITY_ENV = /^SOPS_AGE_KEY(?:_FILE)?$/iu;
-const AGE_HINT = 'load the age identity into SOPS_AGE_KEY (the secret.env of the owner machine, or the CI secret) and retry';
+const AGE_HINT = 'add SOPS_AGE_KEY to .claude/secret.env of the app or the harness secret.env of the owner machine (the CI secret in a workflow) and retry';
 
-/** True when an age identity is reachable: SOPS_AGE_KEY or SOPS_AGE_KEY_FILE in the environment, the repository's .claude/secret.env or the per-user keys.txt. */
-export function hasAgeIdentity(ctx, config) {
-  const named = Object.entries(ctx.env).some(([name, value]) => AGE_IDENTITY_ENV.test(name) && value);
-  return named || fs.existsSync(path.join(config.repoRoot, '.claude', 'secret.env')) || fs.existsSync(secretRoots(ctx.env).identity);
+/**
+ * True when the sops seam found an age identity (secret-init.mjs decryptionIdentity, the one lookup every decrypt uses). A seam
+ * that reports no `identity` (a spec double) decides for itself.
+ */
+export function hasAgeIdentity(ctx) {
+  const { identity } = ctx.sops;
+  return identity === undefined || identity.source !== null;
 }
 
 /** Refuses up front, before any work, when sealed custody must be opened and no age identity is reachable. */
 export function requireAgeIdentity(ctx, config, purpose) {
-  if (!hasAgeIdentity(ctx, config)) throw refusal('STACK_AGE_IDENTITY_MISSING', `${purpose} needs the sealed members, and no age identity is available: ${AGE_HINT}`);
+  if (!hasAgeIdentity(ctx)) throw refusal('STACK_AGE_IDENTITY_MISSING', `${purpose} needs the sealed members, and no age identity is available (looked in ${ctx.sops.identity.looked.join(', ')}): ${AGE_HINT}`);
 }
 
-/** Opens one sealed member (`<secretsDir>/<member>.enc.yaml`, or a legacy `.enc`) into a { KEY: value } map. Names the member only on failure. */
+/**
+ * Opens one sealed member (`<secretsDir>/<member>.enc.yaml`, or a legacy `.enc`) into a { KEY: value } map. A failure is refused
+ * naming the member and the seam's reason (its format, recipients and the identity tried); no value.
+ */
 export function openMember(ctx, config, member) {
   try {
     const map = readMap(memberFile(config.secretsDir, member), ctx.sops);
     return Object.fromEntries(Object.entries(map).map(([key, value]) => [key, typeof value === 'string' && !value.includes(String.fromCodePoint(0)) ? lfText(value) : value]));
-  } catch {
-    throw refusal('STACK_SECRET_MEMBER_UNREADABLE', `the sealed member ${member} cannot be opened${hasAgeIdentity(ctx, config) ? ' (is the age identity a recipient of this member?)' : `: no age identity is available, ${AGE_HINT}`}`);
+  } catch (error) {
+    throw refusal('STACK_SECRET_MEMBER_UNREADABLE', `the sealed member ${member} cannot be opened: ${error.message}${hasAgeIdentity(ctx) ? '' : `; ${AGE_HINT}`}`);
   }
 }
 

package/stack/server-key.mjs

@@ -42,6 +42,22 @@ const RECIPIENT = /^age1[a-z0-9]+$/u;
 /** A command run as root: directly when the deploy user is root, else over passwordless sudo, the script read from stdin. */
 const AS_ROOT = 'if [ "$(id -u)" -eq 0 ]; then sh -s; else sudo -n sh -s; fi';
 
+/**
+ * The directories, after root's PATH, where age-keygen is looked for: sudo's secure_path (AlmaLinux 10, RHEL) leaves out
+ * /usr/local/bin, where the static installer puts it, so the presence check and every call resolve it the same way, as root.
+ */
+export const AGE_KEYGEN_DIRS = ['/usr/local/bin', '/usr/bin', '/bin'];
+
+/** The shell lines that set k to age-keygen's absolute path as root sees it, or exit 127 naming it missing. Every root script holds them. */
+export const RESOLVE_AGE_KEYGEN = [
+  'k="$(command -v age-keygen 2>/dev/null || true)"',
+  `for d in ${AGE_KEYGEN_DIRS.join(' ')}; do if [ -z "$k" ] && [ -x "$d/age-keygen" ]; then k="$d/age-keygen"; fi; done`,
+  'if [ -z "$k" ]; then echo "age-keygen is not installed" >&2; exit 127; fi',
+].join('\n');
+
+/** The root script that only resolves age-keygen and prints its path: the presence check, run exactly as the calls run. */
+export const ageKeygenScript = () => ['set -eu', RESOLVE_AGE_KEYGEN, String.raw`printf '%s\n' "$k"`].join('\n');
+
 /**
  * The GitHub Environment secret that holds an environment's server identity. It carries the name the deploy workflows read
  * (secrets.SOPS_AGE_KEY), scoped to the Environment <env>: for a job bound to <env> it overrides a repository secret of that name.
@@ -54,24 +70,25 @@ export function ensureIdentityScript(file) {
   return [
     'set -eu',
     'umask 077',
+    RESOLVE_AGE_KEYGEN,
     `f=${quoted}`,
     'if [ -e "$f" ] || [ -L "$f" ]; then',
     '  if [ -L "$f" ] || [ ! -f "$f" ]; then echo "the identity path is not an ordinary file" >&2; exit 4; fi',
     '  echo "identity kept" >&2',
     'else',
     '  mkdir -p "$(dirname "$f")"',
-    '  age-keygen -o "$f" >/dev/null 2>&1',
+    '  "$k" -o "$f" >/dev/null 2>&1',
     '  echo "identity created" >&2',
     'fi',
     'chown root:root "$f"',
     'chmod 600 "$f"',
-    'age-keygen -y "$f"',
+    '"$k" -y "$f"',
   ].join('\n');
 }
 
 /** The shell that prints only the public key of `file`, or exits 5 when there is none. */
 export function publicKeyScript(file) {
-  return ['set -eu', `f=${shellQuote(file)}`, '[ -f "$f" ] || exit 5', 'age-keygen -y "$f"'].join('\n');
+  return ['set -eu', RESOLVE_AGE_KEYGEN, `f=${shellQuote(file)}`, '[ -f "$f" ] || exit 5', '"$k" -y "$f"'].join('\n');
 }
 
 /** The shell that swaps the staged `<file>.next` in, keeping the old identity as `retired`, then prints only the new public key. */
@@ -79,6 +96,7 @@ export function swapIdentityScript(file, retired) {
   return [
     'set -eu',
     'umask 077',
+    RESOLVE_AGE_KEYGEN,
     `f=${shellQuote(file)}`,
     `r=${shellQuote(retired)}`,
     'n="$f.next"',
@@ -87,7 +105,7 @@ export function swapIdentityScript(file, retired) {
     'mv "$f" "$r"',
     'mv "$n" "$f"',
     'chmod 600 "$f" "$r"',
-    'age-keygen -y "$f"',
+    '"$k" -y "$f"',
   ].join('\n');
 }
 
@@ -112,14 +130,20 @@ function declaredRemote(repoRoot, env) {
   return remote;
 }
 
-/** Ensures age-keygen on the server: stack prepare's installer owns the install (with --execute); without it the exact commands. */
+/** True when root resolves age-keygen the way every server-key script does (ageKeygenScript). */
+const hasKeygen = (run) => asRoot(run, ageKeygenScript()).status === 0;
+
+/**
+ * Ensures age-keygen on the server, checked as root exactly as it is called: stack prepare's installer owns the install (with
+ * --execute); without it the exact commands.
+ */
 function ensureTool(run, execute, lines) {
-  if (run('command -v age-keygen').status === 0) return true;
+  if (hasKeygen(run)) return true;
   const install = `install age on the server (one of: ${Object.values(AGE_INSTALL).join('; ')})`;
   if (!execute) { lines.push(`dry run: age-keygen is missing on the server; --execute installs it with stack prepare's installer, or ${install}`); return false; }
   const problems = [];
   installAge(run, { note: (text) => lines.push(text), bad: (text) => problems.push(text) });
-  if (problems.length || run('command -v age-keygen').status !== 0)
+  if (problems.length || !hasKeygen(run))
     throw refusal('STACK_SERVER_KEY_NO_AGE', `age-keygen is not on the server and could not be installed (${problems.join('; ') || 'still missing'}): ${install}`);
   return true;
 }

package/templates/app/ci-workflows/github/workflows/stack-key-restore.yml

@@ -53,6 +53,6 @@ jobs:
           printf '%s\n' "$VPS_SSH_KEY" > "$dir/id"
           printf '%s\n' "$VPS_KNOWN_HOSTS" > "$dir/known_hosts"
           # The server writes the identity beside its target, keeps it only when its public key is the recipient, then moves it in.
-          remote="f={{serverAgeIdentity}}; r=$RECIPIENT; "'if [ "$(id -u)" -eq 0 ]; then S=; else S="sudo -n"; fi; if $S test -e "$f"; then cat >/dev/null; echo "the server already holds $f; move it aside first" >&2; exit 3; fi; $S sh -c '"'"'umask 077; f="$1"; r="$2"; d="$(dirname "$f")"; mkdir -p "$d"; t="$(mktemp "$d/.restore.XXXXXX")"; cat > "$t"; if [ "$(age-keygen -y "$t" 2>/dev/null)" != "$r" ]; then rm -f "$t"; echo "the secret is not the identity of $r (or age-keygen is missing); nothing was written" >&2; exit 6; fi; chown root:root "$t"; chmod 600 "$t"; mv "$t" "$f"; age-keygen -y "$f"'"'"' sh "$f" "$r"'
+          remote="f={{serverAgeIdentity}}; r=$RECIPIENT; "'if [ "$(id -u)" -eq 0 ]; then S=; else S="sudo -n"; fi; if $S test -e "$f"; then cat >/dev/null; echo "the server already holds $f; move it aside first" >&2; exit 3; fi; $S sh -c '"'"'PATH="$PATH:/usr/local/bin"; umask 077; f="$1"; r="$2"; d="$(dirname "$f")"; mkdir -p "$d"; t="$(mktemp "$d/.restore.XXXXXX")"; cat > "$t"; if [ "$(age-keygen -y "$t" 2>/dev/null)" != "$r" ]; then rm -f "$t"; echo "the secret is not the identity of $r (or age-keygen is missing); nothing was written" >&2; exit 6; fi; chown root:root "$t"; chmod 600 "$t"; mv "$t" "$f"; age-keygen -y "$f"'"'"' sh "$f" "$r"'
           printf '%s\n' "$AGE_IDENTITY" | ssh -T -i "$dir/id" -o IdentitiesOnly=yes -o UserKnownHostsFile="$dir/known_hosts" \
             -o StrictHostKeyChecking=yes -o BatchMode=yes -o ConnectTimeout=20 "$VPS_USER@$VPS_HOST" "$remote"

package/templates/app/ci-workflows-lite/github/workflows/stack-key-restore.yml

@@ -53,6 +53,6 @@ jobs:
           printf '%s\n' "$VPS_SSH_KEY" > "$dir/id"
           printf '%s\n' "$VPS_KNOWN_HOSTS" > "$dir/known_hosts"
           # The server writes the identity beside its target, keeps it only when its public key is the recipient, then moves it in.
-          remote="f={{serverAgeIdentity}}; r=$RECIPIENT; "'if [ "$(id -u)" -eq 0 ]; then S=; else S="sudo -n"; fi; if $S test -e "$f"; then cat >/dev/null; echo "the server already holds $f; move it aside first" >&2; exit 3; fi; $S sh -c '"'"'umask 077; f="$1"; r="$2"; d="$(dirname "$f")"; mkdir -p "$d"; t="$(mktemp "$d/.restore.XXXXXX")"; cat > "$t"; if [ "$(age-keygen -y "$t" 2>/dev/null)" != "$r" ]; then rm -f "$t"; echo "the secret is not the identity of $r (or age-keygen is missing); nothing was written" >&2; exit 6; fi; chown root:root "$t"; chmod 600 "$t"; mv "$t" "$f"; age-keygen -y "$f"'"'"' sh "$f" "$r"'
+          remote="f={{serverAgeIdentity}}; r=$RECIPIENT; "'if [ "$(id -u)" -eq 0 ]; then S=; else S="sudo -n"; fi; if $S test -e "$f"; then cat >/dev/null; echo "the server already holds $f; move it aside first" >&2; exit 3; fi; $S sh -c '"'"'PATH="$PATH:/usr/local/bin"; umask 077; f="$1"; r="$2"; d="$(dirname "$f")"; mkdir -p "$d"; t="$(mktemp "$d/.restore.XXXXXX")"; cat > "$t"; if [ "$(age-keygen -y "$t" 2>/dev/null)" != "$r" ]; then rm -f "$t"; echo "the secret is not the identity of $r (or age-keygen is missing); nothing was written" >&2; exit 6; fi; chown root:root "$t"; chmod 600 "$t"; mv "$t" "$f"; age-keygen -y "$f"'"'"' sh "$f" "$r"'
           printf '%s\n' "$AGE_IDENTITY" | ssh -T -i "$dir/id" -o IdentitiesOnly=yes -o UserKnownHostsFile="$dir/known_hosts" \
             -o StrictHostKeyChecking=yes -o BatchMode=yes -o ConnectTimeout=20 "$VPS_USER@$VPS_HOST" "$remote"

package/templates/be/skeleton-lite/src/modules/platform/database/database.options.ts

@@ -1,5 +1,8 @@
 import type { Secret } from "@modules/platform/config"
 
+/** An entity class as TypeORM registers it. */
+export type EntityClass = new () => object
+
 /** What the primary connection parser reads from the environment. */
 export interface DatabaseConnectionConfig {
     /** The logical connection name declared in `hfs.json`. */
@@ -21,5 +24,5 @@ export interface DatabaseOptions {
     /** The connections this app opens; one per physical database. */
     readonly connections: ReadonlyArray<DatabaseConnectionOptions>
     /** The TypeORM entities the connections map: PRIMARY_ENTITIES of `@modules/platform/database/entities`, passed by the app's composition root only. */
-    readonly entities: ReadonlyArray<Function>
+    readonly entities: ReadonlyArray<EntityClass>
 }

package/templates/be/skeleton-lite/src/modules/platform/database/entities.ts

@@ -1,7 +1,10 @@
+import { httpSecurityEntities } from "@modules/platform/http-security"
+import type { EntityClass } from "./database.options"
+
 /**
  * The entity list of the primary connection: each capability's `<c>Entities` array (its `persistence/entities/index.ts`), by
  * name, no glob (the entity registry, slot be.platform.database.entities). Only app composition and the test world import this
  * file, from the deep path `@modules/platform/database/entities`; DatabaseModule and the database barrel never do, since the
  * capability barrels import the database capability back.
  */
-export const PRIMARY_ENTITIES: ReadonlyArray<Function> = []
+export const PRIMARY_ENTITIES: ReadonlyArray<EntityClass> = [...httpSecurityEntities]

package/templates/be/skeleton-lite/src/modules/platform/database/index.ts

@@ -1,9 +1,7 @@
 export { DatabaseModule } from "./database.module"
-export { advisoryXactLock, callDbFunction, notify } from "./database.client"
 export { DATABASE_PROBE, InjectDatabaseProbe, InjectPrimaryEntityManager, PRIMARY_ENTITY_MANAGER } from "./primary.decorators"
 export { DatabaseProbeService } from "./database-probe.service"
 export type { DatabaseConnectionOptions } from "./database.options"
 export { PRIMARY_DATA_SOURCE } from "./database.port"
-export { sql } from "./database.sql"
 export { DATABASE_ERROR_KINDS } from "./errors/database.error"
 export { parsePrimaryDatabaseConfig } from "./primary.config"

package/templates/be/skeleton-lite/src/modules/platform/http-security/index.ts

@@ -5,6 +5,7 @@ export { HttpSecurityModule } from "./http-security.module"
 export type { HttpSecurityOptions } from "./http-security.options"
 export { HTTP_SECURITY_MESSAGES } from "./messages/http-security.messages"
 export { OriginGuard, ServerToServer } from "./origin.guard"
+export { httpSecurityEntities } from "./persistence/entities"
 export { RateLimitGuard } from "./rate-limit.guard"
 export { applyHttpSecurity } from "./edge-security.service"
 export { ReadinessService } from "./readiness.service"

package/templates/be/skeleton-lite/src/modules/platform/http-security/persistence/entities/index.ts

@@ -0,0 +1,4 @@
+import { RateWindowEntity } from "./rate-window.entity"
+
+/** The entities of the http-security capability, named in PRIMARY_ENTITIES of platform/database/entities.ts. */
+export const httpSecurityEntities = [RateWindowEntity]

package/templates/be/skeleton-lite/src/modules/platform/http-security/persistence/entities/rate-window.entity.ts

@@ -0,0 +1,17 @@
+import { Column, Entity, PrimaryColumn } from "typeorm"
+
+@Entity({ schema: "public", name: "http_security_rate_windows" })
+/** One rate limit window of one caller and tier, mapped from public.http_security_rate_windows of the baseline migration in db/migrations. */
+export class RateWindowEntity {
+    /** The tier and caller address the window counts. */
+    @PrimaryColumn({ name: "key", type: "varchar", length: 128 })
+    key!: string
+
+    /** The hits counted in the window. */
+    @Column({ name: "hits", type: "integer" })
+    hits!: number
+
+    /** When the window ends; a hit after it opens a fresh one. */
+    @Column({ name: "reset_at", type: "timestamptz" })
+    resetAt!: Date
+}