@starci/hfs 5.1.0 → 5.3.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 5.3.0 - 2026-11-03
+
+- Fixed: the secrets family of the committed check cache stores codes, paths, positions and digests only (`cache/secret-records.mts`, `runtime/scripts/lib/secret-records.mts`), and the one secret judgement of R06 judges a file of `.starcistacks/cache/check/secrets/` by that contract, so `starci app check` can no longer write a cache the staged guard refuses (`HFS_PLAINTEXT_SECRET` for the `secrets/` folder name). A cache written before reads back as digests. Codemod: `starci app codemod secrets-cache`.
+- Added: `@starci/nest-kit` in the starter dependencies and in every module-definition template: a module definition is one call (`defineConfigurableModule<XOptions>()`, `defineCapabilityModule<XOptions>()` for a capability's representative module). The lint on stated export types (R368) accepts a destructured export of those two calls and no other; the digest of the file carries the call, so a change of the options type reaches the importers; `capability-module-shape` (R45) accepts the helper and `module-per-transport` confines it to the definition file. Codemod: `starci app codemod module-definition` rewrites the destructured and the typed builder forms and adds the dependency.
+- Fixed: `HFS_MONO_WORKSPACES` asks for `packages/*` after the fe workspaces once the app tracks a root package (slot `app.packages`, the module packages), so `starci app sync` and `starci app check` keep the entry `app add module` writes; the managed `test` and `build:be` scripts build the module packages first and the CI fast job runs `npm run test:modules` (PROJECT-3, BE-TEST-13).
+- Added: `starci app stack up` builds the harness runtime layer an app image stands on (`openclaw-runtime`) from the recipe this package ships (`stack/images/openclaw-runtime`, kept byte-equal to the harness `images/openclaw-runtime` by `npm run bundles`) when the host neither holds nor can pull it, as a governed heavy build.
+- Fixed: a secret member no creation rule of `.sops.yaml` reaches is refused `SECRET_SOPS_RULE_MISSING` before sops runs (a rule written for the legacy `.enc` spelling does not reach a `.enc.yaml` member), naming the path and `starci app secret init --env <env>`. Codemod: `starci app codemod sops-rules` migrates the legacy rule to the managed one (public recipients only).
+- Fixed: `starci app secret set` on a tooling member (`sonar.enc.yaml`, any member a service credential's custody path names) no longer declares it in `environments.<env>.secrets` (which made CI custody refuse the analysis token); it binds the member to its service (`credentials` and `ci.secrets`, the shape the template renders) or prints the exact binding. Codemod: `starci app codemod quality-binding` binds an app scaffolded before and names a runtime entry an earlier set declared.
+- Added: the lite starter depends on `@starci/mail` and renders the five email doors (BE `IdentityEmailService` and `identity_email_tokens`; FE `/auth/signup`, `/auth/resend`, `/auth/forgot`, `/auth/confirm`, `/auth/reset`, `EmailDoorForm`, the managed `modules/auth/email-doors.ts`), a Mailpit dev sink pinned by digest (`mail-sink.spec.mts`), and the stack links `@starci/mail` in the scaffold type-check.
+- Fixed: the `theme-tokens` codemod drops an alias whose rename would name itself (`--starci-core-accent: var(--accent)` became `--accent: var(--accent)`, which is invalid at computed-value time and blanked every brand colour) and a rule block that held only such aliases, with its comment; R61 now lists the stylelint rule `no-self-reference` (`@starci/stylelint-canon` 2.6.0) among its enforcers.
+- Changed: the scaffold type-check runs the back-end and front-end chains and both editions concurrently (the same checks, async spawns).
+- Fixed: an app's root workspace packages (`packages/agent-sdk`, `packages/module-<name>`, the managed `packages/modules`) are first-party packages of the import graph. A side imports one by its package name through the `exports` of its manifest: that is no import that leaves the side (`ARCH_INTERNAL_IMPORT_OUTSIDE` stopped the front-end lint run on `@scope/agent-sdk/workbench`) and adds no edge; an import into the package's source past its entry points stays refused, with a message that lists the entry points. The packages are read from the app root's `workspaces` (patterns that start with no side folder) and from the slots `app.packages` and `app.module-registry` (`architecture/root-packages.mts`, `rootPackages` of the architecture config). Spec: `architecture-root-packages.spec.mts`.
+- Added: the slots `app.packages`, `app.module-registry` and `app.packages-lint` in the runtime slot manifest (3.17.0; the first two were only in `contexts/hfs/slots.yaml`, so `packages/` classified as `HFS_SLOT_UNDECLARED`). `eslint.config.mjs` at the app root is the managed config of the root packages, no longer a forbidden tool config.
+- Added: `starci app sync` renders `eslint.config.mjs` at the app root whenever the app has a root package: the back-end canon over the back-end subpaths of `packages/<pkg>/src/**`, the front-end canon and the Grammar family's `<family>GrammarPackagesConfig` over `src/workbench/**` and `src/public/**`. `starci app check --gate lint` runs it as a third scope (`packages`, from the app root, uncached) beside `be` and `fe`. The package view of the slot resolver (`openPackagesHfsView`, `declaredPackagesHfsView` in `view.mts`) is the profile of a side over the paths of the app root; a package file is of the tier `package` and has no owner. Spec: `lint-packages.spec.mts`.
+- Changed: the lite sign-in and the email doors reach accounts through the account doors. The baseline migration includes `templates/app/auth-doors.sql.partial`, which is now the source of truth of the doors (it is no longer a byte copy of an app's own migration): eight SECURITY DEFINER functions `public.be_auth_user_by_email`, `_by_id`, `_by_google`, `be_auth_create_user`, `be_auth_link_google`, `be_auth_touch_user`, `be_auth_confirm_user(user, now)` (stamps the confirmation only, no sign-in record) and `be_auth_set_password(user, hash, confirm, now)` (sets the hash and, when `confirm` is true, confirms the mailbox), each with a pinned `search_path` and EXECUTE revoked from public, anon and authenticated and granted to `app_be` alone, plus a `lower(email)` index on `auth.users` the by-address door reads. `be_auth_set_password` is a four-argument function: an app that already has a three-argument one of its own keeps both. The three grants of `app_be` on schema `auth`, `auth.users` and `auth.identities` are gone from the baseline, so one injectable query no longer reaches every account's hash, role and metadata. The eight doors are in `ruleParams.be.dbFunctions`; an app lists none of them in hfs.json.
+- Changed: the managed identity glue (slot `be.identity.sign-in`): `AuthUserEntity` and `AuthIdentityEntity` are deleted; the account directory, the authenticator and `IdentityEmailService` (signup insert, mailbox confirm, password reset) call the doors through the new managed `persistence/account-doors.port.ts`, which validates every answer (`returnedRows`, `rowShape`); the database decides `disabled` at its own now() (a banned account no longer receives a reset mail). The rate counter over `identity_attempts` and the fail-closed refusal mapping are unchanged.
+- Added: `IdentitySignInService.endOthers(principal)` signs the caller out of every other device, and `Principal.sessionId` carries the device session of the access token. The authenticator logs an account created by Google sign-in as `identity.sign_in.account_created` (new managed `identity-sign-in.log-events.ts`) with the account id only. The lite starter carries `platform/database/database.client.ts` and exports `callDbFunction`.
+- Changed: R255 (`DB_APP_ROLE`) also refuses any grant to the declared back-end role on schema `auth`, on a table or sequence in it, or by default privilege for it, with no transition tolerance. The migrations are judged in order, so a later migration that revokes a grant clears it. BE-AUTH-2, BE-PERSISTENCE-4 and BE-PERSISTENCE-17 follow.
+- Added: `starci app codemod account-doors [--contract] [--execute]`, the upgrade of a lite app already on the template: it writes the expand migration `db/migrations/<ts>_account-doors.sql` with the doors the app lacks (a door is known by name and argument types, so an app that has the six earlier doors gets only the two new ones) and, with `--contract`, the migration `<ts>_contract_revoke-auth-grants.sql` that revokes the three grants from the declared role.
+- Changed: `starci app sync --execute` deletes the retired `auth-user.entity.ts` and `auth-identity.entity.ts` of an app on the old glue.
+- Upgrade, for a lite app scaffolded at 3.16.0 or later (the old glue grants `app_be` on `auth.users`): the new glue calls functions the app's database does not have until the expand migration is applied. Ship these three steps in one release, in this order; R255 reports the old grants until step 3 is in the chain, so they cannot ship apart.
+  1. `npx starci app codemod account-doors --execute` (expand): writes the migration that creates the doors the app lacks and the index.
+  2. `npx starci app sync --execute`: moves the glue onto the doors and deletes the two entity files; `npx starci app check` is green except R255 until step 3.
+  3. `npx starci app codemod account-doors --contract --execute` (contract): writes the migration that revokes the old grants. It refuses while an account door is undefined or a back-end source still maps `schema: "auth"`.
+  4. The deploy applies the expand migration before the services and the contract migration after the accept.
+  5. Rollback: the release before this one still reads the auth tables, so a rollback to it after the accept must restore the grants by hand, as the database owner:
+     ```sql
+     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;
+     ```
+     (use the role `db.appRole` of hfs.json when it is not app_be). Revoke them again with the contract migration when the rollback is undone.
+  6. An app that already defines the six earlier doors (Nivo) runs step 1 too and gets only `be_auth_confirm_user` and the four-argument `be_auth_set_password`; its hfs.json `sides.be.dbFunctions` may drop the doors, which the canon now lists.
+
+## 5.2.0 - 2026-11-03
+
+- Added: a scaffolded app of each edition type-checks and builds on every side (`scaffold-type-check.spec.mts`: one install per edition, `tsc` of the back end and its specs, the back-end build, the workspace packages, `tsc` and `next build` of each front-end app). The templates follow the Grammar contract: `Link` and `Page` for `SiteShell` and `NotFoundNotice`, a callable `toast`, the session reducers as a type, explicit next-intl navigation generics, optional access to the test world's apps and connections, no unused import in the migrations fixture. The lite dev api process no longer runs `--transpile-only`.
+- Added: the custody kind `ed25519-pem` of `local.custody` (the dev sign-in key is EdDSA); the lite dev environment names `AUTH_WEB_ORIGIN`.
+- Added: `starci app add module <name>` and `starci app remove module <name>`: a module package `packages/module-<name>` of the product's agent SDK (`./template`, `./manifest`, `./workbench`, `./public`), registered in the root `workspaces` and the back-end and front-end dependencies, listed in the managed registry package `packages/modules` that `starci app sync` renders and drift-checks. Slots `app.packages` and `app.module-registry` (manifest 3.17.0). The module packages enter the Sonar sources, the Codecov paths and a `build:modules` / `test:modules` script pair that the typecheck, the lint and the build run first.
+- Added: rule R374 (`STACKS_CODE_BIND_MOUNT`, `STACKS_IMAGE_BASE_UNPINNED`, `STACKS_IMAGE_BASE_NOT_FORK`, `STACKS_IMAGE_ENV_DIVERGES`): a customised service is an image built from `.starcistacks/images/<name>/` on the harness's pinned base, no bind-mounted code, the same image in every environment (PROJECT-STACKS-11).
+- Changed: FE-PACKAGES-2 (a shared package, a module's workbench included, draws only with Grammar) and BE-TEST-13 (a module package's logic is inside the 100 per file scope).
+- Added: the lite starter composes `@starci/auth`: it depends on the package and on none of the identity libraries, `integrations/passport` is the glue the slot lists (`passport.config.ts`, `passport.options.ts`, `passport.decorators.ts`, `passport.kit.ts`, `errors/`), the web app keeps one `@starci/auth/client` instance in `modules/auth/client.ts`, and the baseline migration holds the package's session tables (`identity_sessions`, `identity_refresh_tokens`) byte for byte.
+- Changed: `infraOwners` own `@nestjs/passport`, `passport*`, `@nestjs/jwt`, `jose` and `bcryptjs` by nobody and `@starci/auth` by `integrations/passport` alone (R328); the `own-jwks-principal` machine refuses a `jwtVerify` call anywhere in the app and requires the `@starci/auth/server` import in the passport integration (R329); `transport-owner` no longer admits an auth door in `modules/auth`; the `auth` stack concern names `@starci/auth` and forbids `jose`, `jwt-decode`, `next-auth`, `@auth/core`, `keycloak-js` and `oidc-client-ts`.
+- Changed: the lite stack templates name `AUTH_WEB_ORIGIN` and the Ed25519 signing key; `AUTH_JWT_PRIVATE_KEY` is an EdDSA key and the public key is derived from it.
+- Added: the lite starter signs in with no hand-written auth code. The managed slots `be.identity.sign-in`, `be.feature.auth` and `fe.modules.auth.client` render, from `templates/be/auth-lite` and `templates/fe/auth-lite`, the `/auth` doors (login, refresh, session, logout, Google start and callback, jwks), the entities of the session, attempt, user and identity tables, the session, account and rate stores, the authenticator, `IdentitySignInService`, their specs and the web app's `createAuthClient` client; an edit is `HFS_MANAGED_FILE_DRIFT`. The identity error family gains the sign-in codes, the passport family keeps its `PASSPORT_` codes.
+- Added: the slot field `managedOnly` (a slot that only lists files sync renders; the slot owning the path judges them). Manifest 3.16.0.
+- Changed: the sync and the scaffold count the back-end source files their own targets render, so the CI shard count and the coverage scope are the same before and after the targets are written (one sync leaves the app in sync).
+- Added: the canon pin of `@starci/auth` 0.1.0.
+- Added: `starci app stack prepare|doctor|up|status|logs|down|verify --env <env>` for a docker-compose (dev) environment, driven by the new `environments.<env>.local` block of application-stacks.yaml: ports, compose services and their health, the environment's own database role (the migrations run as it and the app role gets its own password), dev-only custody generators, least grants (`STACK_GRANT_<NAME>`), data directories (`STACK_DATA_DIR`, `${data}`), setup and seed commands (a seed runs after the migration or after readiness), native app processes, readiness and verification probes. `up --execute` is the one command (host table, custody, setup, services, database, migrate with a receipt, seed once, processes, readiness, origins); `prepare`, `up` and `down` are dry runs until `--execute`, `down` never removes a volume, `doctor` prints the owner-run install step per OS for each missing prerequisite and installs nothing. A swarm environment keeps the swarm verbs and refuses the dev-only ones.
+- Added: `starci app secret init --env <dev env> [--execute]` creates the dev-only values `local.custody` declares (hex, base64, password, uuid, rsa-pem, ec-pem), once: a sealed value is kept, a half-present pair is refused, a vps or production environment is refused.
+- Added: `db migrate` runs its client tools inside the database container named by `STARCI_DB_CONTAINER`, so a host without PostgreSQL client tools migrates a dev database.
+- Added: rules R372 (`STACKS_LOCAL_CONFIG_INVALID`, `STACKS_DEV_UNDECLARED`: a coherent local block, and a lite app declares its dev environment) and R373 (`STACKS_RUNBOOK_DOCKER_COMMAND`: the dev runbook names `starci app stack up --env <env>` and carries no docker command).
+- Changed: the lite skeleton's dev environment is `docker-compose` with a local block, a compose file and a runbook of the new verbs (it was a Swarm stack with illustrative digests); slot `app.starcistacks` admits `<env>/infra/compose/**` in lite; `add queue` in lite adds the Redis to the dev compose file and the queue settings to the dev processes.
+
 ## 5.1.0
 
 - Added: `starci app codemod explicit-surface` writes the inferred type of every export the classifier counts as open (R368): return types, variable, parameter and property types, from the app's own TypeScript program. It prefers a named type the program exports, writes `ReactElement` for components and Next's `Metadata` for `generateMetadata`, adds merged type-only imports after a directive prologue, compiles the result beside the original and writes a file only when it gains no diagnostic, and reports (with a suggested fix) destructured exports and anonymous, computed, too long, `any`, unnameable and predicate types. Prettier of the app formats what is written.

package/README.md

@@ -24,10 +24,19 @@ starci app world <up|down|status> [--stack <dir>] [--services <list>] [--k3d] [-
 starci app slot <path> [--cwd <dir>] [--json]
 starci app emit [--cwd <dir>]
 starci app db drift [--db-url-env <NAME>] [--json] [--cwd <dir>]
-starci app secret init | <set|get|unset|rename|remove|materialize|list|verify|recipients|migrate|split|audit|server-key> --env <env> ... [--cwd <dir>]
+starci app stack <prepare|up|down> --env <dev env> [--execute] | <doctor|status|verify> --env <dev env> | logs --env <dev env> --service <name> [--lines <n>]
+starci app secret init [--env <dev env> [--execute]] | <set|get|unset|rename|remove|materialize|list|verify|recipients|migrate|split|audit|server-key> --env <env> ... [--cwd <dir>]
 starci app ci secret set <NAME> [--from-custody] [--env <env>] [--repo <owner/name>] [--execute]
 ```
 
+**The dev environment in one command.** `starci app stack up --env dev --execute` brings a docker-compose environment up from its `local` block of
+`.starcistacks/application-stacks.yaml` (PROJECT-STACKS-6 of `contexts/project/stacks.md`): the host table (`doctor` prints the owner-run install
+step per OS for each missing prerequisite and installs nothing), the dev custody (`secret init --env dev --execute` creates the dev-only values once),
+the setup commands, the compose services and their health, the environment's own database role, the migrations with a receipt (`db migrate` runs its
+client tools in the database container named by `STARCI_DB_CONTAINER`, so the host needs no PostgreSQL client), the seed once, the native app
+processes, readiness and the origins. `prepare`, `up` and `down` are dry runs until `--execute`; `down` never removes a volume. State (process ids,
+logs, receipts) is under the state base (`STARCI_LOCAL_ROOT`), the opened custody under the private secrets directory outside the checkout.
+
 `starci app add` writes every front-end unit, in either edition, already in the shape of the harness's `contexts/code/fe`
 and `contexts/ui`, from `templates/fe/units`, with its copy in every catalog; nothing that exists is overwritten.
 
@@ -139,7 +148,7 @@ Every file of a spec-required role of `ruleParams.be.unitRoles` — a `*.service
 
 The spec skeleton is `Test.createTestingModule({ providers: [Service, { provide: TOKEN, useValue: double }, ...] }).compile()` and `moduleRef.get(Service)`, with one provider per constructor dependency and nothing else, every double imported from `@starci/jest-preset` (the root), and one placeholder `it` per public method. The double of a token comes from `ruleParams.be.specDoubles` of the slot manifest, the table the lint law `spec-infra-double-from-kit` holds a spec to (`*_ENTITY_MANAGER` -> `mockEntityManager()`, `CLOCK` -> `new FakeClock(...)`, `EVENT_BUS` -> `recordingEventBus()`, `QUEUE_OUTBOX` -> `recordingQueueOutbox()`, `CACHE` -> `fakeCache(clock)`, lock, lease, fence and hold -> `fakeLock(clock)`, ids -> `fakeIds()`, `*_OPTIONS` -> a literal to fill in, everything else and every class -> `mock<T>()`), so the skeleton satisfies the law by construction: no cast, no `new` of the service, no ambient clock. A back end only (a front end has no services); the files are written for prettier (print width 120).
 
-`starci app check` runs ESLint once per side through the app's installed managed flat config: the backend canon on `be/`, and the universal FE canon plus the explicitly selected Grammar-family package on `fe/`. It also reads the app's `hfs.json` and tracked paths (`git ls-files`), checks the work tree (the root rules once, the side rules per side), and runs the whole architecture machine over each side folder. HFS findings carry their why code and Vietnamese text (`modules/kernel/failure-codes.yaml`); ESLint findings retain their rule id and failure code.
+`starci app check` runs ESLint once per side through the app's installed managed flat config: the backend canon on `be/`, and the universal FE canon plus the explicitly selected Grammar-family package on `fe/`; an app with root workspace packages (`packages/agent-sdk`, `packages/module-<name>`) has a third run from the app root through the managed root `eslint.config.mjs` that `starci app sync` renders, over `packages/<pkg>/src/**` by subpath (the backend canon on everything but `src/workbench/` and `src/public/`, the workbench contract kept; the universal FE canon and the Grammar family on those two, the contract left out). It also reads the app's `hfs.json` and tracked paths (`git ls-files`), checks the work tree (the root rules once, the side rules per side), and runs the whole architecture machine over each side folder. HFS findings carry their why code and Vietnamese text (`modules/kernel/failure-codes.yaml`); ESLint findings retain their rule id and failure code.
 
 Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file checks (`sync/managed.mjs`) and the prettier check (`sync/format.mjs`) live in `sync/` because they read the templates and the repository's own install, and reach `starci app check` as `extraFindings`; the jest / vitest preset the coverage exclusions come from and prettier are read from the repository's `node_modules`, so run `npm ci` first):
 

package/cache/hfs-family.d.mts

@@ -1,11 +1,10 @@
 import type { HeavyNodeRun } from '../runtime/scripts/api/node/run-node.mjs';
 import { type MachineFn, type RepositoryResult } from '../runtime/scripts/hfs/check.mjs';
 import type { Presets } from '../sync/index.mjs';
+import { SECRETS_FOLDER, SECRET_CODES } from './secret-records.mjs';
 import type { CheckSession, FamilyReport } from './types.mjs';
 export declare const HFS_FOLDER = "check/hfs";
-export declare const SECRETS_FOLDER = "check/secrets";
-/** The finding codes of the secrets family: plaintext secrets, sealed custody, untracked secret files. */
-export declare const SECRET_CODES: ReadonlySet<string>;
+export { SECRETS_FOLDER, SECRET_CODES };
 /** What the structure pass answers. */
 export interface PassResult {
     /** The whole-app check result of the pass (the shape `printCheck` reads), or the slot result when only secrets were asked for. */

package/cache/hfs-family.mjs

@@ -16,15 +16,10 @@ import { withRuleMemo } from '../runtime/scripts/hfs/rule-memo.mjs';
 import { RecordSet, scopedStep } from './records.mjs';
 import { FILE_RULES_STEP, RULE_STEP_PREFIX, UNIT_STEP_PREFIX, createStructureMemo } from './structure-memo.mjs';
 import { makeReport } from './report.mjs';
+import { SECRETS_FOLDER, SECRET_CODES, safeSecretFinding, safeSecretRecords } from './secret-records.mjs';
 import { sideKey } from './side-key.mjs';
 export const HFS_FOLDER = 'check/hfs';
-export const SECRETS_FOLDER = 'check/secrets';
-/** The finding codes of the secrets family: plaintext secrets, sealed custody, untracked secret files. */
-export const SECRET_CODES = new Set([
-    'HFS_PLAINTEXT_SECRET', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'HFS_LITE_SECRET_CUSTODY', 'HFS_IDENTITY_CUSTODY',
-    'HFS_AGE_KEY_CUSTODY', 'RT_SECRET_TRACKED', 'STACKS_SECRET_ENV_LITERAL', 'STACKS_SECRET_NOT_EXTERNAL', 'STACKS_SECRET_UNVERSIONED', 'SEALED_CUSTODY_LOCATION',
-    'APP_SECRET_IN_CI', 'CI_SECRET_SEALED', 'BE_LOG_SECRET', 'BE_SECRET_DEFAULT', 'HFS_DOCKER_SECRETS',
-]);
+export { SECRETS_FOLDER, SECRET_CODES };
 const compact = (finding) => ({
     path: finding.path ?? '.', line: finding.line ?? 0, column: finding.column ?? 0, rule: finding.code, message: String(finding.message ?? ''),
 });
@@ -169,8 +164,8 @@ export async function runStructurePass(session, input) {
         const secretDecision = session.decide('secrets');
         const prior = session.records(SECRETS_FOLDER);
         const secretFindings = result.findings.filter((finding) => SECRET_CODES.has(finding.code));
-        session.replace(SECRETS_FOLDER, findingRecords(secretFindings, session.index.hashOf.bind(session.index), 'secrets'));
-        secretsReport = makeReport({ family: 'secrets', mode: secretDecision.mode, reason: secretDecision.reason, checked: filesChecked, reused: filesReused, previous: prior.flatMap((record) => record.findings), current: secretFindings.map(compact) });
+        session.replace(SECRETS_FOLDER, safeSecretRecords(findingRecords(secretFindings, session.index.hashOf.bind(session.index), 'secrets')));
+        secretsReport = makeReport({ family: 'secrets', mode: secretDecision.mode, reason: secretDecision.reason, checked: filesChecked, reused: filesReused, previous: prior.flatMap((record) => record.findings.map(safeSecretFinding)), current: secretFindings.map((finding) => safeSecretFinding(compact(finding))) });
         session.report(secretsReport);
     }
     return { result, contracts, machineReused: reasons, report, secretsReport };

package/cache/secret-records.d.mts

@@ -0,0 +1,7 @@
+import { SECRETS_FOLDER, SECRET_CODES } from '../runtime/scripts/lib/secret-records.mjs';
+import type { CacheRecord, Finding } from './types.mjs';
+export { SECRETS_FOLDER, SECRET_CODES };
+/** A finding as the secrets cache stores it: the same code, path and position, the message as its digest. */
+export declare function safeSecretFinding(finding: Finding): Finding;
+/** The records as the secrets cache stores them: each finding safe, no `data`. */
+export declare function safeSecretRecords(records: readonly CacheRecord[]): CacheRecord[];

package/cache/secret-records.mjs

@@ -0,0 +1,12 @@
+// secret-records.mts - the writer side of the secrets records contract (runtime/scripts/lib/secret-records.mts): the cache is committed, so the
+// records of `check/secrets` are projected to codes, paths, positions and digests before they are stored or compared, whoever produced them.
+import { messageDigest, SECRETS_FOLDER, SECRET_CODES } from '../runtime/scripts/lib/secret-records.mjs';
+export { SECRETS_FOLDER, SECRET_CODES };
+/** A finding as the secrets cache stores it: the same code, path and position, the message as its digest. */
+export function safeSecretFinding(finding) {
+    return { path: finding.path, line: finding.line, column: finding.column, rule: finding.rule, message: messageDigest(finding.message) };
+}
+/** The records as the secrets cache stores them: each finding safe, no `data`. */
+export function safeSecretRecords(records) {
+    return records.map((record) => ({ path: record.path, step: record.step, hash: record.hash, findings: record.findings.map(safeSecretFinding) }));
+}

package/cache/session.mjs

@@ -8,6 +8,7 @@ import { createContentIndex } from './content-index.mjs';
 import { computeFingerprint, fingerprintDifferences, parseFingerprint, serializeFingerprint } from './fingerprint.mjs';
 import { hashFile } from './hash.mjs';
 import { groupByArea, parseRecords, serializeRecords } from './jsonl.mjs';
+import { SECRETS_FOLDER, safeSecretRecords } from './secret-records.mjs';
 import { readCacheDir, resolveTrust, verifyCommitted } from './trust.mjs';
 import { CACHE_DIR } from './types.mjs';
 /** `STARCI_APP_CHECK_CACHE`: `full` ignores the cache (the release gate sets it), `verify` is read by the caller (runs diff, then full, compares). */
@@ -122,10 +123,11 @@ export function createDiskSession(options) {
             return global() ?? { mode: 'diff', reason: `against ${trust.reason}` };
         },
         records(folder) {
-            return replaced.get(folder)?.records ?? trustedRecords(folder);
+            return replaced.get(folder)?.records ?? (folder === SECRETS_FOLDER ? safeSecretRecords(trustedRecords(folder)) : trustedRecords(folder));
         },
         replace(folder, records, replaceOptions) {
-            replaced.set(folder, { records, depth: replaceOptions?.depth ?? 2 });
+            // The secrets family never stores secret material, whoever produced the records (secret-records.mts).
+            replaced.set(folder, { records: folder === SECRETS_FOLDER ? safeSecretRecords(records) : records, depth: replaceOptions?.depth ?? 2 });
         },
         unchanged: (paths, captured) => paths.every((file) => {
             const now = hashFile(path.join(root, file));

package/codemod/account-doors.d.mts

@@ -0,0 +1,36 @@
+/** One migration the codemod writes (or would write). */
+export interface AccountDoorsChange {
+    file: string;
+    phase: 'expand' | 'contract';
+    why: string;
+}
+/** One case left for a person. */
+export interface AccountDoorsFinding {
+    file: string;
+    reason: string;
+}
+/** The report of the upgrade (`starci app codemod account-doors`). */
+export interface AccountDoorsReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    phase: 'expand' | 'contract';
+    changes: AccountDoorsChange[];
+    findings: AccountDoorsFinding[];
+    next: string[];
+}
+/**
+ * Upgrade of a lite app that signs in over direct grants on auth.users and auth.identities to the account doors. The expand step (default)
+ * writes the migration that creates the doors the app lacks, with the text the lite baseline includes; the app then runs `starci app sync --execute`
+ * (the sign-in glue switches to the doors and the two entity files go). The contract step (`contract`) writes the migration that revokes the three
+ * grants, once the doors exist and no be source maps the auth tables; R255 reports the grants until that migration is in the chain. Nothing is written while a case is left for a person, and a step that is already
+ * done changes nothing.
+ */
+export declare function migrateAccountDoors({ root, write, contract, now }: {
+    root: string;
+    write?: boolean;
+    contract?: boolean;
+    now?: () => number;
+}): AccountDoorsReport;
+/** Render the migrations and what is left for a person as Markdown; JSON consumers read the same report object. */
+export declare function accountDoorsMarkdown(report: AccountDoorsReport): string;

package/codemod/account-doors.mjs

@@ -0,0 +1,128 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { nextStamp } from '../db/new.mjs';
+import { MIGRATIONS_DIR } from '../runtime/scripts/hfs/rules/database-constants.mjs';
+import { filesUnder, relativePosix } from './source-tree.mjs';
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+/** The owner of the account doors: the partial the lite baseline includes, byte for byte. */
+const DOORS_PARTIAL = path.join(PACKAGE_ROOT, 'templates', 'app', 'auth-doors.sql.partial');
+/** A grant to anyone on schema auth or on a table in it. */
+const AUTH_GRANT = /\bgrant\b[^;]*?\bon\b\s+(?:schema\s+auth\b|(?:table\s+)?auth\.)/iu;
+const EXPAND_NAME = 'account-doors';
+const CONTRACT_NAME = 'contract_revoke-auth-grants';
+const SOURCE = /\.[cm]?tsx?$/iu;
+const ENTITY_FILES = ['auth-user.entity.ts', 'auth-identity.entity.ts'];
+/** The argument types of a signature, the `p_` parameter names dropped and case and spacing folded: a door is known by its name and types alone. */
+const typesOf = (args) => args.split(',').map((arg) => arg.trim().replace(/^p_\w+\s+/u, '').replace(/\s+/gu, ' ').toLowerCase()).join(', ');
+/** The partial split into its head (the comment and the index) and its doors, in the partial's order. */
+function partialParts(text) {
+    const lines = text.split('\n');
+    const doors = [...text.matchAll(/^(?:-- [^\n]*\n)?CREATE FUNCTION public\.(\w+)\(([^)]*)\)[\s\S]*?\$\$;\n/gmu)].map((match) => {
+        const own = lines.filter((line) => /^(?:REVOKE|GRANT) EXECUTE ON FUNCTION public\.(\w+)\(/u.exec(line)?.[1] === match[1] && typesOf(/\(([^)]*)\)/u.exec(line)[1]) === typesOf(match[2]));
+        return { name: match[1], types: typesOf(match[2]), block: match[0], grants: `${own.join('\n')}\n` };
+    });
+    return { head: text.slice(0, text.indexOf(doors[0].block)), doors };
+}
+/** The doors a text defines, as name(types) keys. */
+const definedDoors = (statements) => [...statements.matchAll(/create\s+(?:or\s+replace\s+)?function\s+public\.(\w+)\s*\(([^)]*)\)/giu)].map((match) => `${match[1].toLowerCase()}(${typesOf(match[2])})`);
+const migrationsOf = (root) => {
+    const dir = path.join(root, MIGRATIONS_DIR);
+    return fs.existsSync(dir) ? fs.readdirSync(dir).filter((name) => name.endsWith('.sql')).sort() : [];
+};
+const textOf = (root, name) => fs.readFileSync(path.join(root, MIGRATIONS_DIR, name), 'utf8');
+/** The statements of a migration, its line comments left out. */
+const statementsOf = (root, name) => textOf(root, name).replace(/--[^\n]*/gu, '');
+/** The application role hfs.json declares (`db.appRole`), app_be by default. */
+function appRoleOf(root) {
+    const role = JSON.parse(fs.readFileSync(path.join(root, 'hfs.json'), 'utf8')).db?.appRole;
+    return typeof role === 'string' && /^[a-z_][a-z0-9_]*$/u.test(role) ? role : 'app_be';
+}
+/** The be source that still maps or names the auth tables: an entity of schema auth, or the retired entity files. */
+function accountTableReferences(root) {
+    const be = path.join(root, 'be', 'src');
+    if (!fs.existsSync(be))
+        return [];
+    return filesUnder(be, SOURCE).map((file) => relativePosix(root, file)).filter((file) => {
+        const retired = ENTITY_FILES.some((name) => file.endsWith(`/${name}`));
+        return retired || /schema:\s*["']auth["']/u.test(fs.readFileSync(path.join(root, file), 'utf8'));
+    });
+}
+function contractText(role) {
+    return [
+        '-- contract: the back end reaches auth.users and auth.identities through the account doors (public.be_auth_*), so the application role',
+        '-- gives up its direct grants. The release before the doors still reads those tables, so a rollback to it after the accept needs them granted again.',
+        `revoke select, insert, update on table auth.users from ${role};`,
+        `revoke select, insert on table auth.identities from ${role};`,
+        `revoke usage on schema auth from ${role};`,
+        '',
+    ].join('\n');
+}
+/**
+ * Upgrade of a lite app that signs in over direct grants on auth.users and auth.identities to the account doors. The expand step (default)
+ * writes the migration that creates the doors the app lacks, with the text the lite baseline includes; the app then runs `starci app sync --execute`
+ * (the sign-in glue switches to the doors and the two entity files go). The contract step (`contract`) writes the migration that revokes the three
+ * grants, once the doors exist and no be source maps the auth tables; R255 reports the grants until that migration is in the chain. Nothing is written while a case is left for a person, and a step that is already
+ * done changes nothing.
+ */
+export function migrateAccountDoors({ root, write = false, contract = false, now = Date.now }) {
+    const phase = contract ? 'contract' : 'expand';
+    const report = { schema: 'starci/account-doors-report@1', root, write, phase, changes: [], findings: [], next: [] };
+    const declaration = JSON.parse(fs.readFileSync(path.join(root, 'hfs.json'), 'utf8'));
+    if (declaration.edition !== 'lite') {
+        report.findings.push({ file: 'hfs.json', reason: 'the account doors belong to the lite edition; a full app signs in through its identity provider' });
+        return report;
+    }
+    const names = migrationsOf(root);
+    const parts = partialParts(fs.readFileSync(DOORS_PARTIAL, 'utf8'));
+    const defined = new Set(names.flatMap((name) => definedDoors(statementsOf(root, name))));
+    const missing = parts.doors.filter((door) => !defined.has(`${door.name}(${door.types})`));
+    const stamp = nextStamp(names, now());
+    if (!contract) {
+        if (!missing.length)
+            return report;
+        const file = `${MIGRATIONS_DIR}/${stamp}_${EXPAND_NAME}.sql`;
+        const kept = missing.length === parts.doors.length ? 'all' : missing.map((door) => door.name).join(', ');
+        report.changes.push({ file, phase, why: `creates the account doors the app lacks (${kept}; SECURITY DEFINER, pinned search_path, EXECUTE for the application role alone) and the lower(email) index the by-address door reads` });
+        report.next.push('run `npx starci app sync --execute` (the sign-in glue moves onto the doors and the retired entity files are deleted), then verify and release both together', 'then run `npx starci app codemod account-doors --contract --execute` to revoke the old grants (R255 reports them until that migration is in the chain) and release the three together');
+        const text = `${parts.head}${missing.map((door) => door.block).join('\n')}\n${missing.map((door) => door.grants).join('')}`;
+        if (write)
+            fs.writeFileSync(path.join(root, file), text, { flag: 'wx' });
+        return report;
+    }
+    if (missing.length)
+        report.findings.push({ file: MIGRATIONS_DIR, reason: `no migration defines the account doors ${missing.map((door) => door.name).join(', ')}: run the expand step first` });
+    for (const file of accountTableReferences(root)) {
+        report.findings.push({ file, reason: 'still maps or names the auth tables; run `npx starci app sync --execute` so the sign-in glue uses the doors, and release that before the contract migration' });
+    }
+    if (report.findings.length)
+        return report;
+    if (names.some((name) => name.includes(`_${CONTRACT_NAME}`)) || !names.some((name) => AUTH_GRANT.test(statementsOf(root, name))))
+        return report;
+    const file = `${MIGRATIONS_DIR}/${stamp}_${CONTRACT_NAME}.sql`;
+    report.changes.push({ file, phase, why: 'revokes the direct grants on schema auth, auth.users and auth.identities from the application role' });
+    report.next.push('the deploy applies it right after the accept; the release before the doors cannot sign in after a rollback unless the grants are given back');
+    if (write)
+        fs.writeFileSync(path.join(root, file), contractText(appRoleOf(root)), { flag: 'wx' });
+    return report;
+}
+const cell = (value) => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+/** Render the migrations and what is left for a person as Markdown; JSON consumers read the same report object. */
+export function accountDoorsMarkdown(report) {
+    const out = ['# account-doors', '', `Step ${report.phase}: ${report.changes.length} migration${report.changes.length === 1 ? '' : 's'} ${report.write ? 'written' : 'to write'}, ${report.findings.length} left for a person.`, ''];
+    if (report.findings.length) {
+        out.push('## Left for a person', '', '| location | reason |', '|---|---|');
+        for (const finding of report.findings)
+            out.push(`| ${cell(finding.file)} | ${cell(finding.reason)} |`);
+        out.push('');
+    }
+    if (report.changes.length) {
+        out.push('## Migrations', '', '| file | step | why |', '|---|---|---|');
+        for (const change of report.changes)
+            out.push(`| ${cell(change.file)} | ${change.phase} | ${cell(change.why)} |`);
+        out.push('');
+    }
+    if (report.next.length)
+        out.push('## Next', '', ...report.next.map((line) => `- ${line}`), '');
+    return `${out.join('\n')}\n`;
+}

package/codemod/main.mjs

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { accountDoorsMarkdown, migrateAccountDoors } from './account-doors.mjs';
 import { codemodMain as buttonIntentMain } from './button-intent.mjs';
 import { migratePageNavigation, pageNavigationMarkdown } from './page-navigation.mjs';
 import { loadingStatesMarkdown, migrateLoadingStates } from './loading-states.mjs';
@@ -9,10 +10,14 @@ import { migrateSpacingRoles, spacingRolesMarkdown } from './spacing-roles.mjs';
 import { migrateSurfaceCardKinds, surfaceCardKindsMarkdown } from './surface-card-kinds.mjs';
 import { explicitSurfaceMarkdown, migrateExplicitSurface } from './explicit-surface.mjs';
 import { directiveFirstMarkdown, migrateDirectiveFirst } from './directive-first.mjs';
+import { migrateModuleDefinition, moduleDefinitionMarkdown } from './module-definition.mjs';
+import { migrateQualityBinding, qualityBindingMarkdown } from './quality-binding.mjs';
+import { migrateSopsRules, sopsRulesMarkdown } from './sops-rules.mjs';
+import { migrateSecretsCache, secretsCacheMarkdown } from './secrets-cache.mjs';
 import { migrateThemeTokens, themeTokensMarkdown } from './theme-tokens.mjs';
 import { migrateTierBinding, tierBindingMarkdown } from './tier-binding.mjs';
 /** The codemods `starci app codemod` runs, by name. */
-export const CODEMODS = Object.freeze(['button-intent', 'spacing-roles', 'theme-tokens', 'small-renames', 'page-navigation', 'section-frame', 'surface-card-kinds', 'tier-binding', 'loading-states', 'explicit-surface', 'directive-first']);
+export const CODEMODS = Object.freeze(['button-intent', 'spacing-roles', 'theme-tokens', 'small-renames', 'page-navigation', 'section-frame', 'surface-card-kinds', 'tier-binding', 'loading-states', 'explicit-surface', 'directive-first', 'secrets-cache', 'module-definition', 'sops-rules', 'quality-binding', 'account-doors']);
 /** The arguments of every report-style `starci app codemod`: --execute, --json, --format and --out; any other is refused. */
 export function spacingRolesArguments(argv) {
     const options = { write: false, format: 'markdown' };
@@ -46,6 +51,22 @@ export function spacingRolesArguments(argv) {
 }
 /** One of the report-style codemods run at an app root: its report object and the Markdown of it. */
 function runCodemod(name, root, write) {
+    if (name === 'quality-binding') {
+        const report = migrateQualityBinding({ root, write });
+        return { report, markdown: qualityBindingMarkdown(report) };
+    }
+    if (name === 'sops-rules') {
+        const report = migrateSopsRules({ root, write });
+        return { report, markdown: sopsRulesMarkdown(report) };
+    }
+    if (name === 'module-definition') {
+        const report = migrateModuleDefinition({ root, write });
+        return { report, markdown: moduleDefinitionMarkdown(report) };
+    }
+    if (name === 'secrets-cache') {
+        const report = migrateSecretsCache({ root, write });
+        return { report, markdown: secretsCacheMarkdown(report) };
+    }
     if (name === 'directive-first') {
         const report = migrateDirectiveFirst({ root, write });
         return { report, markdown: directiveFirstMarkdown(report) };
@@ -105,6 +126,13 @@ async function explicitSurfaceMain(argv, io) {
     const report = await migrateExplicitSurface({ root: path.resolve(io.cwd), write: options.write });
     return emit(options, { report, markdown: explicitSurfaceMarkdown(report) }, io);
 }
+/** `starci app codemod account-doors [--contract]`: the expand migration of the account doors, or (a release later) the contract migration that revokes the old grants. */
+function accountDoorsMain(argv, io) {
+    const contract = argv.includes('--contract');
+    const options = reportArguments(argv.filter((arg) => arg !== '--contract'));
+    const report = migrateAccountDoors({ root: path.resolve(io.cwd), write: options.write, contract });
+    return emit(options, { report, markdown: accountDoorsMarkdown(report) }, io);
+}
 /**
  * CLI boundary of `starci app codemod <name>`. Dry run by default; --execute writes only the safe rewrites. A codemod
  * that leaves a case for a person exits 1 with the complete report.
@@ -115,6 +143,8 @@ export function codemodMain(argv, io) {
         return buttonIntentMain(argv, io);
     if (name === 'explicit-surface')
         return explicitSurfaceMain(rest, io);
+    if (name === 'account-doors')
+        return accountDoorsMain(rest, io);
     if (name === undefined || !CODEMODS.includes(name))
         throw new Error(`starci app codemod takes ${CODEMODS.join(' or ')}`);
     const options = reportArguments(rest);

package/codemod/module-definition.d.mts

@@ -0,0 +1,52 @@
+/** The TypeScript compiler API of the app's own install (loadTypescript), typed by the version this package develops against. */
+type Ts = typeof import('typescript');
+/** One definition the migration rewrites: which form it was written in, the helper it became and the names it exports. */
+export interface ModuleDefinitionChange {
+    file: string;
+    from: 'destructured builder' | 'typed builder';
+    helper: string;
+    names: string[];
+}
+/** One case left for a person. */
+export interface ModuleDefinitionFinding {
+    file: string;
+    line: number;
+    code: string;
+    reason: string;
+}
+/** The report of a migration (`starci app codemod module-definition`). */
+export interface ModuleDefinitionReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    filesScanned: number;
+    filesChanged: string[];
+    changes: ModuleDefinitionChange[];
+    findings: ModuleDefinitionFinding[];
+    /** The `@starci/nest-kit` requirement of the app's root package.json: added by `--execute` when a definition changed, then `npm install` resolves it. */
+    dependency: {
+        name: string;
+        version: string;
+        declared: boolean;
+        added: boolean;
+    };
+}
+/** Rewrite one definition file's text to the helper form; `text` unchanged when the file holds no definition the codemod can rewrite. */
+export declare function transformModuleDefinition({ ts, text, file }: {
+    ts: Ts;
+    text: string;
+    file?: string;
+}): {
+    text: string;
+    changes: ModuleDefinitionChange[];
+    findings: ModuleDefinitionFinding[];
+};
+/** Preview or apply the rewrite in one app: every `*.module-definition.ts` under its sides, then the dependency in the root package.json. */
+export declare function migrateModuleDefinition({ root, write, ts }: {
+    root: string;
+    write?: boolean;
+    ts?: Ts | null;
+}): ModuleDefinitionReport;
+/** Render the rewrite and what is left for a person as Markdown; JSON consumers read the same report object. */
+export declare function moduleDefinitionMarkdown(report: ModuleDefinitionReport): string;
+export {};