@starci/hfs 5.1.0 → 5.3.0

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

@@ -42,78 +42,93 @@ components:
 environments:
   dev:
     status: supported
-    runtime: docker-swarm
-    composeFiles: [infra/swarm/stack.yaml]
+    runtime: docker-compose
+    composeFiles: [infra/compose/compose.yaml]
     components:
-      api: {replicas: 1, port: 3001}
-      web: {replicas: 1, port: 3000}
-      db: {replicas: 1, port: 5432}
-      ingress: {replicas: 1, port: 80}
+      db: {port: 54322}
+      api: {port: 3001}
+      web: {port: 3000}
     runbook: README.md
-    ingress:
-      component: ingress
-      hosts: ["dev.{{project}}.example.invalid"]
-    dns:
-      - host: "dev.{{project}}.example.invalid"
-        owner: Development operator
-        receipt: .starcistacks/dev/infra/swarm/owner-actions.md#dns
-    tls:
-      owner: Development operator
-      receipt: .starcistacks/dev/infra/swarm/owner-actions.md#tls
-    release:
-      imagesLock: .starcistacks/dev/infra/swarm/releases/images.lock.yaml
-      pointer: .starcistacks/dev/infra/swarm/releases/current.yaml
-      previous: .starcistacks/dev/infra/swarm/releases/previous.yaml
-      healthAssertions: [API /health/live, API /health/ready, Web /health/live]
-    backup:
-      - component: ingress
-        target: Owner-provisioned encrypted off-host storage for both ingress volumes
-        retention: Seven daily snapshots
-        owner: Development operator
-        restoreProof: .starcistacks/dev/infra/swarm/recovery/restore-proof.md
-      - component: db
-        target: Owner-provisioned encrypted off-host storage for starci app db dump archives
-        retention: Seven daily exports
-        owner: Development operator
-        restoreProof: .starcistacks/dev/infra/swarm/recovery/restore-proof.md
-    # Scaffolding seals generated placeholders to this app's own recipient; set real values before use.
-    secrets:
-      - name: primary-db-url
-        runtimeName: "{{project}}-dev-primary-db-url-v1"
-        version: 1
-        where: secrets/primary-db-url
-        recipientPolicy: This app's own age recipient configured in .sops.yaml
-        keyCustody: SOPS_AGE_KEY in the host's untracked .claude/secret.env
-      - name: db-password
-        runtimeName: "{{project}}-dev-db-password-v1"
-        version: 1
-        where: secrets/db-password
-        recipientPolicy: This app's own age recipient configured in .sops.yaml
-        keyCustody: SOPS_AGE_KEY in the host's untracked .claude/secret.env
-      - name: google-client-secret
-        runtimeName: "{{project}}-dev-google-client-secret-v1"
-        version: 1
-        where: secrets/google-client-secret
-        recipientPolicy: This app's own age recipient configured in .sops.yaml
-        keyCustody: SOPS_AGE_KEY in the host's untracked .claude/secret.env
-      - name: auth-jwt-private-key
-        runtimeName: "{{project}}-dev-auth-jwt-private-key-v1"
-        version: 1
-        where: secrets/auth-jwt-private-key
-        recipientPolicy: This app's own age recipient configured in .sops.yaml
-        keyCustody: SOPS_AGE_KEY in the host's untracked .claude/secret.env
-      - name: storage-access-key-id
-        runtimeName: "{{project}}-dev-storage-access-key-id-v1"
-        version: 1
-        where: secrets/storage-access-key-id
-        recipientPolicy: This app's own age recipient configured in .sops.yaml
-        keyCustody: SOPS_AGE_KEY in the host's untracked .claude/secret.env
-      - name: storage-secret-access-key
-        runtimeName: "{{project}}-dev-storage-secret-access-key-v1"
-        version: 1
-        where: secrets/storage-secret-access-key
-        recipientPolicy: This app's own age recipient configured in .sops.yaml
-        keyCustody: SOPS_AGE_KEY in the host's untracked .claude/secret.env
+    # Dev custody is generated once, dev-only, by the owner-armed `starci app secret init --env dev --execute`, which also declares each key here.
+    secrets: []
+    # `starci app stack up --env dev --execute` reads this block (PROJECT-STACKS-6): host prerequisites, dev custody, setup, the compose services,
+    # the environment's own database role, migrations, native api and web processes, readiness, origins.
+    local:
+      ports:
+        db: 54322
+        api: 3001
+        web: 3000
+        mail: 1025
+        mailui: 8025
+      services:
+        - {name: db, wait: healthy}
+        - {name: mail, wait: healthy}
+      database:
+        service: db
+        port: db
+        urlEnv: PRIMARY_DB_URL
+        appRole: app_be
+        password: {member: db, key: DEV_DB_OWNER_PASSWORD}
+        adminPassword: {member: db, key: POSTGRES_PASSWORD}
+        appPassword: {member: db, key: DEV_DB_APP_PASSWORD}
+      grants:
+        - {name: db, keys: [POSTGRES_PASSWORD]}
+      custody:
+        - {member: db, key: POSTGRES_PASSWORD, kind: password}
+        - {member: db, key: DEV_DB_OWNER_PASSWORD, kind: password}
+        - {member: db, key: DEV_DB_APP_PASSWORD, kind: password}
+        - {member: auth, key: AUTH_JWT_PRIVATE_KEY, kind: ed25519-pem}
+        - {member: google, key: GOOGLE_CLIENT_SECRET, kind: hex}
+        - {member: storage, key: STORAGE_ACCESS_KEY_ID, kind: hex, bytes: 12}
+        - {member: storage, key: STORAGE_SECRET_ACCESS_KEY, kind: hex}
+      setup:
+        - {name: install, argv: [npm, ci], heavy: install, skipIfExists: node_modules}
+        - {name: codegen, argv: [npm, run, codegen, --silent], heavy: build}
+      processes:
+        - name: api
+          argv: [npx, ts-node-dev, --respawn, -r, tsconfig-paths/register, apps/api/src/main.ts]
+          cwd: be
+          port: api
+          files: [GOOGLE_CLIENT_SECRET, AUTH_JWT_PRIVATE_KEY, STORAGE_ACCESS_KEY_ID, STORAGE_SECRET_ACCESS_KEY]
+          env:
+            PORT: "${port.api}"
+            HTTP_SECURITY_ALLOWED_ORIGINS: "http://localhost:${port.web}"
+            PRIMARY_DB_SCHEMA: public
+            GOOGLE_CLIENT_ID: dev-local-client-id
+            GOOGLE_CALLBACK_URL: "http://localhost:${port.api}/auth/google/callback"
+            AUTH_JWT_ISSUER: "http://localhost:${port.api}"
+            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
+          health: {url: "http://localhost:${port.api}/health/live"}
+        - name: web
+          argv: [npm, run, dev:fe]
+          port: web
+          env:
+            NEXT_PUBLIC_SITE_URL: "http://localhost:${port.web}"
+            NEXT_PUBLIC_API_URL: "http://localhost:${port.api}"
+            NEXT_PUBLIC_GRAPHQL_URL: "http://localhost:${port.api}/graphql"
+          health: {url: "http://localhost:${port.web}/health/live"}
+      ready:
+        - {name: api-live, url: "http://localhost:${port.api}/health/live"}
+        - {name: api-ready, url: "http://localhost:${port.api}/health/ready"}
+        - {name: web-live, url: "http://localhost:${port.web}/health/live"}
+      verify:
+        - {name: api-live, url: "http://localhost:${port.api}/health/live"}
+        - {name: api-ready, url: "http://localhost:${port.api}/health/ready"}
+        - {name: web-live, url: "http://localhost:${port.web}/health/live"}
+      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

@@ -1,20 +1,32 @@
 # Development stack
 
-Every development dependency runs in Docker Linux containers. The `db` service (the official postgres image plus pgvector, built from `.starcistacks/images/db/Dockerfile`) starts with `npm run db:start` and takes the migrations with `npm run db:push`; storage is the S3-compatible MinIO the environment names. Every other declared dependency, such as Redis, starts through its managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts or the declared container model; Compose is an implementation detail. The app services may run in the local Docker Swarm model or through a declared native development profile while dependencies stay in Docker.
-The application image references contain illustrative all-zero digests. Replace them with verified published release digests in the manifest, model and `.starcistacks/dev/infra/swarm/releases/images.lock.yaml` before starting the container model. Seal the local database connection and the integration credentials; a container cannot use the host's loopback address without owner-configured networking. Local source development remains available through the app scripts.
+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`; 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.
 
-The runtime template tracks no encrypted members. Scaffolding generates the six declared members with placeholder values encrypted to this app's own recipient in `.sops.yaml`. Replace those values with `starci app secret set --env dev` using the matching host age identity in untracked local custody. Existing generated envelopes are decryptable with that app identity and can be updated in place. Each Docker secret contains the corresponding key's real value, and the API receives it through its declared mounted file.
+**A new machine.** Install what `starci app stack doctor --env dev` reports missing (it prints the exact winget, brew or apt step per tool; Node
+from `.nvmrc`, npm, git, Docker with Compose v2 running Linux containers, WSL2 on Windows, sops and age), then run `up`. A fresh clone needs
+nothing else: `up` runs `npm ci` and the codegen itself.
+
+**Custody.** Dev values are sealed like any secret and generated once, dev-only: the owner arms `starci app secret init --env dev --execute`, which
+creates every value `local.custody` declares, declares its key in the manifest and never replaces a value that is already sealed. A machine that
+lacks the age identity of an existing dev member is refused with the owner step to obtain it. The `db` service takes `POSTGRES_PASSWORD`, the
+migrations run as the environment's own owner role and the api connects as the `app_be` role with its own password, so no role is shared with
+another environment.
 
 | Command | Operation |
 | --- | --- |
-| prepare | Run `npm run db:start` at the app root; then `npm run db:push` to apply the migrations; export `DATABASE_URL` for the database verbs. For a declared Redis (its `redis:create`, `redis:start` and `redis:stop` scripts arrive in package.json with the first queue or job), run the create script once, then the start script when using the native app profile. An owner who chooses local Swarm initializes it, labels its node `{{project}}=dev` and provisions the ingress volumes; the model starts its declared Redis with the app. Replace the reserved development host consistently in the manifest, Caddyfile and public configuration; resolve it to the node and record this in `.starcistacks/dev/infra/swarm/owner-actions.md`. Create the external development secrets named in the model from real sealed members. |
-| doctor | From this directory, run `docker stack config -c infra/swarm/stack.yaml`. Confirm image, secret and local database availability. |
-| up | Run `docker stack deploy -c infra/swarm/stack.yaml {{project}}-dev` from this directory after preparation. |
-| status | Run `docker stack services {{project}}-dev`. |
-| logs | Run `docker service logs {{project}}-dev_api`; never print mounted credentials. |
-| down | Run `docker stack rm {{project}}-dev`. |
-| verification | Confirm the API `/health/live` and `/health/ready` endpoints and web `/health/live`, then run `npm run lint` from the app root. Retain the last accepted release in `.starcistacks/dev/infra/swarm/releases/previous.yaml` before recording the verified release in `.starcistacks/dev/infra/swarm/releases/current.yaml`. |
+| prepare | `starci app stack prepare --env dev --execute`: checks the machine, opens the custody, runs the setup commands and builds the images. |
+| doctor | `starci app stack doctor --env dev`: read-only table of host prerequisites with the owner-run install step per OS, custody, compose render and ports. |
+| up | `starci app stack up --env dev --execute`: prepare, then the services, the database role, migrations with a receipt, the seed, the processes and readiness; prints the origins. |
+| status | `starci app stack status --env dev`: desired against running, the migration receipt and every readiness probe. |
+| logs | `starci app stack logs --env dev --service api` (a process or a compose service, bounded and redacted). |
+| 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. |
 
-Keep real sealed members under `.starcistacks/dev/secrets/*.enc` at the declared paths and inventory their key names in `.starcistacks/dev/runtime/env/KEYS.md`. Rotation creates a new immutable `-v<N>` external secret and updates its version and runtime name together in the manifest and model. Only the declared ingress publishes port 80; the local route uses HTTP with automatic TLS disabled.
+**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 manifest declares seven daily encrypted off-host database exports and ingress-volume snapshots owned by the development operator. `.starcistacks/dev/infra/swarm/recovery/restore-proof.md` is a pending recovery record. Complete an isolated restore and attach a dated receipt before relying on these backups. Release, DNS and restore records remain explicitly pending until an operator supplies real evidence.
+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

@@ -0,0 +1,43 @@
+# 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.
+# `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:
+    build:
+      context: ../../../images/db
+    image: {{project}}-db:local
+    environment:
+      POSTGRES_PASSWORD_FILE: /run/secrets/POSTGRES_PASSWORD
+    ports:
+      - "127.0.0.1:${STACK_PORT_DB}:5432"
+    volumes:
+      - db-data:/var/lib/postgresql/data
+      - ${STACK_GRANT_DB}:/run/secrets:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]
+      interval: 5s
+      timeout: 5s
+      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

@@ -1,30 +1,25 @@
-# Environment key roster
+# Environment key roster (dev)
 
-This roster declares names only. Scaffolding generates the six declared encrypted members with placeholder values encrypted to this app's own age recipient. Replace their values through `starci app secret set --env dev` before creating external secrets. The runtime template tracks no ciphertext; its specs generate members with ephemeral identities in disposable copies. Store product credential values in sealed custody and materialize private KEY files outside the repository.
+Names only. Dev values are generated once by the owner-armed `starci app secret init --env dev --execute`, sealed in
+`.starcistacks/dev/secrets/<member>.enc.yaml` and opened by `starci app stack up --env dev --execute` into private files outside the repository
+(`<KEY>_FILE`, which the back end reads first). The public front-end configuration is supplied by the manifest's `local.processes` environment.
 
 | Key | Consumer |
 | --- | --- |
-| `PORT` | API listener |
-| `HTTP_SECURITY_ALLOWED_ORIGINS` | API origin allowlist |
-| `PRIMARY_DB_URL` | API least-privilege database connection; `.starcistacks/dev/secrets/primary-db-url.enc` maps to external `{{project}}-dev-primary-db-url-v1` and mounted `/run/secrets/primary-db-url` |
-| `PRIMARY_DB_SCHEMA` | API primary database schema |
-| `POSTGRES_PASSWORD` | The db service's superuser password; `.starcistacks/dev/secrets/db-password.enc` maps to external `{{project}}-dev-db-password-v1` and mounted `/run/secrets/db-password` |
-| `GOOGLE_CLIENT_ID` | API Google OAuth client |
-| `GOOGLE_CLIENT_SECRET` | API Google OAuth client; `.starcistacks/dev/secrets/google-client-secret.enc` maps to external `{{project}}-dev-google-client-secret-v1` and mounted `/run/secrets/google-client-secret` |
-| `GOOGLE_CALLBACK_URL` | API Google OAuth callback door |
-| `AUTH_JWT_ISSUER` | API access-token issuer |
-| `AUTH_JWT_AUDIENCE` | API access-token audience |
-| `AUTH_JWT_KEY_ID` | API signing key id, published in the JWKS |
-| `AUTH_COOKIE_DOMAIN` | API cookie `Domain` (a bare domain such as `example.com`, no scheme or port); optional while the web and the API share one host, required when they are served on different hosts, because a host-only refresh cookie never reaches the web server's forwarded `Cookie` header |
-| `AUTH_JWT_PRIVATE_KEY` | API ES256 signing key; `.starcistacks/dev/secrets/auth-jwt-private-key.enc` maps to external `{{project}}-dev-auth-jwt-private-key-v1` and mounted `/run/secrets/auth-jwt-private-key` |
-| `STORAGE_ENDPOINT` | API S3-compatible storage endpoint |
-| `STORAGE_REGION` | API storage signing region |
-| `STORAGE_BUCKET` | API storage bucket |
-| `STORAGE_ACCESS_KEY_ID` | API storage credential; `.starcistacks/dev/secrets/storage-access-key-id.enc` maps to external `{{project}}-dev-storage-access-key-id-v1` and mounted `/run/secrets/storage-access-key-id` |
-| `STORAGE_SECRET_ACCESS_KEY` | API storage credential; `.starcistacks/dev/secrets/storage-secret-access-key.enc` maps to external `{{project}}-dev-storage-secret-access-key-v1` and mounted `/run/secrets/storage-secret-access-key` |
-| `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 |
-| `NEXT_PUBLIC_GRAPHQL_URL` | Front-end GraphQL transport |
-
-Public front-end configuration is supplied at build time and stays outside sealed custody. The database verbs read `DATABASE_URL` from the operator's environment; the GitHub secret store carries only the age identity.
+| `PORT`, `HTTP_SECURITY_ALLOWED_ORIGINS`, `PRIMARY_DB_SCHEMA` | API listener, origin allowlist, primary schema (manifest `local.processes.api.env`) |
+| `PRIMARY_DB_URL` | API least-privilege connection as `app_be` with this environment's own password; composed by the stack verb, read through `PRIMARY_DB_URL_FILE` |
+| `POSTGRES_PASSWORD` | The db service's superuser password (member `db`) |
+| `DEV_DB_OWNER_PASSWORD` | The environment's own owner role, which runs the migrations (member `db`) |
+| `DEV_DB_APP_PASSWORD` | The password of the `app_be` role in this environment's database (member `db`) |
+| `GOOGLE_CLIENT_ID`, `GOOGLE_CALLBACK_URL` | API Google OAuth client and callback (local placeholders in the manifest) |
+| `GOOGLE_CLIENT_SECRET` | API Google OAuth client secret (member `google`) |
+| `AUTH_JWT_ISSUER`, `AUTH_JWT_AUDIENCE`, `AUTH_JWT_KEY_ID` | API access-token claims and key id (the key id is published in the JWKS) |
+| `AUTH_WEB_ORIGIN` | API origin of the web app: where the Google callback lands and the only origin a return address may name |
+| `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

@@ -12,10 +12,16 @@ services:
       GOOGLE_CLIENT_SECRET_FILE: /run/secrets/google-client-secret
       GOOGLE_CALLBACK_URL: https://api.{{project}}.example.invalid/auth/google/callback
       AUTH_JWT_ISSUER: https://api.{{project}}.example.invalid
+      AUTH_WEB_ORIGIN: https://{{project}}.example.invalid
       AUTH_JWT_AUDIENCE: {{project}}
       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

@@ -13,15 +13,20 @@ This inventory declares names, consumers and mounted file paths. Scaffolding gen
 | `GOOGLE_CLIENT_SECRET` | API Google OAuth client; reads `GOOGLE_CLIENT_SECRET_FILE` at `/run/secrets/google-client-secret` |
 | `GOOGLE_CALLBACK_URL` | API Google OAuth callback door |
 | `AUTH_JWT_ISSUER` | API access-token issuer |
+| `AUTH_WEB_ORIGIN` | API origin of the web app: where the Google callback lands and the only origin a return address may name |
 | `AUTH_JWT_AUDIENCE` | API access-token audience |
 | `AUTH_JWT_KEY_ID` | API signing key id, published in the JWKS |
 | `AUTH_COOKIE_DOMAIN` | API cookie `Domain` (a bare domain such as `example.com`, no scheme or port); optional while the web and the API share one host, required when they are served on different hosts, because a host-only refresh cookie never reaches the web server's forwarded `Cookie` header |
-| `AUTH_JWT_PRIVATE_KEY` | API ES256 signing key; reads `AUTH_JWT_PRIVATE_KEY_FILE` at `/run/secrets/auth-jwt-private-key` |
+| `AUTH_JWT_PRIVATE_KEY` | API Ed25519 (EdDSA) signing key; reads `AUTH_JWT_PRIVATE_KEY_FILE` at `/run/secrets/auth-jwt-private-key` |
 | `STORAGE_ENDPOINT` | API S3-compatible storage endpoint |
 | `STORAGE_REGION` | API storage signing region |
 | `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,25 +24,88 @@ begin
 end;
 $$;
 
--- The rotating refresh sessions of integrations/passport (auth.users comes from db/bootstrap.sql).
--- One row per issued refresh token, stored by its sha256 only. A family is one sign-in; rotation revokes the presented row
--- and inserts its successor, and presenting a revoked row revokes the whole family (reuse detection).
-create table auth.refresh_sessions (
+-- 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).
+-- The app owns auth.users (db/bootstrap.sql) and the role app_be.
+
+create table public.identity_sessions (
+    id uuid primary key,
+    user_id uuid not null references auth.users (id) on delete cascade,
+    created_at timestamptz not null default now(),
+    refreshed_at timestamptz not null default now(),
+    user_agent text,
+    ip text
+);
+
+create index identity_sessions_user_idx on public.identity_sessions (user_id);
+
+create table public.identity_refresh_tokens (
     id uuid primary key default gen_random_uuid(),
-    family_id uuid not null,
+    session_id uuid not null references public.identity_sessions (id) on delete cascade,
+    user_id uuid not null,
+    token_hash text not null,
+    created_at timestamptz not null default now(),
+    expires_at timestamptz not null,
+    used_at timestamptz,
+    constraint identity_refresh_tokens_hash_key unique (token_hash)
+);
+
+create index identity_refresh_tokens_session_idx on public.identity_refresh_tokens (session_id);
+create index identity_refresh_tokens_expiry_idx on public.identity_refresh_tokens (user_id, expires_at);
+
+create table public.identity_attempts (
+    key varchar(128) primary key,
+    hits integer not null,
+    reset_at timestamptz not null
+);
+
+create index identity_attempts_reset_idx on public.identity_attempts (reset_at);
+
+alter table public.identity_sessions enable row level security;
+alter table public.identity_sessions force row level security;
+alter table public.identity_refresh_tokens enable row level security;
+alter table public.identity_refresh_tokens force row level security;
+alter table public.identity_attempts enable row level security;
+alter table public.identity_attempts force row level security;
+
+revoke all on table public.identity_sessions from public;
+revoke all on table public.identity_refresh_tokens from public;
+revoke all on table public.identity_attempts from public;
+grant select, insert, update, delete on table public.identity_sessions to app_be;
+grant select, insert, update, delete on table public.identity_refresh_tokens to app_be;
+grant select, insert, update, delete on table public.identity_attempts to app_be;
+
+create policy identity_sessions_app_be_all on public.identity_sessions
+    for all to app_be using (current_user = 'app_be') with check (current_user = 'app_be');
+create policy identity_refresh_tokens_app_be_all on public.identity_refresh_tokens
+    for all to app_be using (current_user = 'app_be') with check (current_user = 'app_be');
+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,
-    token_hash char(64) not null unique,
+    purpose varchar(16) not null check (purpose in ('confirm', 'reset')),
+    token_hash varchar(64) not null,
     expires_at timestamptz not null,
-    revoked_at timestamptz,
-    created_at timestamptz not null default now()
+    used_at timestamptz,
+    created_at timestamptz not null,
+    constraint identity_email_tokens_hash_key unique (token_hash)
 );
 
-create index refresh_sessions_family_idx on auth.refresh_sessions (family_id);
+create index identity_email_tokens_user_idx on public.identity_email_tokens (user_id, purpose);
 
-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;
-grant select, insert, update on table auth.refresh_sessions to app_be;
+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,

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

@@ -0,0 +1,44 @@
+// 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. */
+export interface ExchangeRequest {
+    /** The request and response. */
+    readonly exchange: HttpExchange
+}
+
+/** 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/get-jwks.handler.ts

@@ -0,0 +1,23 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { QueryHandler } from "@nestjs/cqrs"
+import { IdentitySignInService } from "@modules/domain/identity"
+import type { JwksDocument } from "@modules/integrations/passport"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { GetJwksQuery } from "./get-jwks.query"
+
+@QueryHandler(GetJwksQuery)
+/** Answers the JWKS. */
+export class GetJwksHandler extends ICQRSHandler<GetJwksQuery, JwksDocument> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly signIn: IdentitySignInService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(): Promise<JwksDocument> {
+        return this.signIn.jwks()
+    }
+}