terp-cli 0.35.0__tar.gz → 0.36.1__tar.gz

{terp_cli-0.35.0 → terp_cli-0.36.1}/PKG-INFO

@@ -1,23 +1,23 @@
 Metadata-Version: 2.5
 Name: terp-cli
-Version: 0.35.0
+Version: 0.36.1
 Summary: Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs.
 Project-URL: Repository, https://github.com/AITT-NL/terp-framework
 Project-URL: Changelog, https://github.com/AITT-NL/terp-framework/blob/main/CHANGELOG.md
 License-Expression: Apache-2.0
 Requires-Python: >=3.13
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: terp-arch==0.35.0
-Requires-Dist: terp-core==0.35.0
-Requires-Dist: terp-migrations==0.35.0
+Requires-Dist: terp-arch==0.36.1
+Requires-Dist: terp-core==0.36.1
+Requires-Dist: terp-migrations==0.36.1
 Provides-Extra: jobs
-Requires-Dist: terp-cap-outbox==0.35.0; extra == 'jobs'
-Requires-Dist: terp-cap-scheduler-apscheduler==0.35.0; extra == 'jobs'
+Requires-Dist: terp-cap-outbox==0.36.1; extra == 'jobs'
+Requires-Dist: terp-cap-scheduler-apscheduler==0.36.1; extra == 'jobs'
 Provides-Extra: release
 Requires-Dist: cryptography>=46; extra == 'release'
 Requires-Dist: packaging>=24; extra == 'release'
-Requires-Dist: terp-cap-egress==0.35.0; extra == 'release'
+Requires-Dist: terp-cap-egress==0.36.1; extra == 'release'
 Provides-Extra: scheduler
-Requires-Dist: terp-cap-scheduler-apscheduler==0.35.0; extra == 'scheduler'
+Requires-Dist: terp-cap-scheduler-apscheduler==0.36.1; extra == 'scheduler'
 Provides-Extra: worker
-Requires-Dist: terp-cap-outbox==0.35.0; extra == 'worker'
+Requires-Dist: terp-cap-outbox==0.36.1; extra == 'worker'

{terp_cli-0.35.0 → terp_cli-0.36.1}/pyproject.toml

@@ -4,18 +4,18 @@ build-backend = "hatchling.build"
 
 [project]
 name = "terp-cli"
-version = "0.35.0"
+version = "0.36.1"
 description = "Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs."
 requires-python = ">=3.13"
 license = "Apache-2.0"
 dependencies = [
-    "terp-core==0.35.0",
+    "terp-core==0.36.1",
     # `terp migrate` delegates to terp-migrations (lazily imported), keeping Alembic
     # off the path for `terp inspect` / `terp guide` while making migrations work.
-    "terp-migrations==0.35.0",
+    "terp-migrations==0.36.1",
     # `terp guide rules` projects the live rule registry; terp-arch is imported lazily
     # (only when that topic is rendered), so it stays off the common `terp guide` path.
-    "terp-arch==0.35.0",
+    "terp-arch==0.36.1",
     # `terp verify --only env-seams` and `terp smoke` read the compose profiles as data
     # (anchors and `<<:` merge keys resolved), so both answer without a Docker daemon or
     # even the `docker` binary. Declared explicitly rather than leant on: every app
@@ -29,11 +29,11 @@ dependencies = [
 # or a scheduler engine into apps that only use inspect/check/migrate. Deployments can select
 # one process role, while `jobs` is the convenient complete jobs-process bundle.
 [project.optional-dependencies]
-worker = ["terp-cap-outbox==0.35.0"]
-scheduler = ["terp-cap-scheduler-apscheduler==0.35.0"]
+worker = ["terp-cap-outbox==0.36.1"]
+scheduler = ["terp-cap-scheduler-apscheduler==0.36.1"]
 jobs = [
-    "terp-cap-outbox==0.35.0",
-    "terp-cap-scheduler-apscheduler==0.35.0",
+    "terp-cap-outbox==0.36.1",
+    "terp-cap-scheduler-apscheduler==0.36.1",
 ]
 # `terp release` and `terp promote` (ADR 0187): the DSSE signature (cryptography), the lock's
 # markers (packaging), and the one declared way to a registry, an index and the vulnerability
@@ -42,7 +42,7 @@ jobs = [
 release = [
     "cryptography>=46",
     "packaging>=24",
-    "terp-cap-egress==0.35.0",
+    "terp-cap-egress==0.36.1",
 ]
 
 [project.scripts]

{terp_cli-0.35.0 → terp_cli-0.36.1}/signer/Dockerfile

@@ -26,7 +26,7 @@
 # (tests/release_lane/).
 
 # python:3.14-slim, the base-image table's interpreter (terp-arch's base-images.json).
-FROM python@sha256:fbecd461fc72d21b2143c6eaba25143738079154a6d0ea3da3aec724f50eed4a AS install
+FROM python@sha256:930e1abba7c4e8f96ed93e8012c35d174d7732752731bbd5e8e757d7ec6f3966 AS install
 COPY wheels/ /wheels/
 COPY requirements.txt /requirements.txt
 # Every distribution by its hash: the third-party ones as uv.lock pins them, the framework's as
@@ -41,7 +41,7 @@ FROM zricethezav/gitleaks@sha256:c00b6bd0aeb3071cbcb79009cb16a60dd9e0a7c60e2be9a
 # The docker client 29.9.2, by digest (docker:29.9.2-cli, read 2026-10-22).
 FROM docker@sha256:5e6baf67325a79f64ed3bed6863954d5e05d0f3d4e57cbdb14809346814bbfdb AS docker
 
-FROM python@sha256:fbecd461fc72d21b2143c6eaba25143738079154a6d0ea3da3aec724f50eed4a
+FROM python@sha256:930e1abba7c4e8f96ed93e8012c35d174d7732752731bbd5e8e757d7ec6f3966
 RUN apt-get update \
     && apt-get install -y --no-install-recommends git \
     && rm -rf /var/lib/apt/lists/* \

{terp_cli-0.35.0 → terp_cli-0.36.1}/src/terp/cli/__init__.py

@@ -41,7 +41,7 @@ from terp.cli.jobs import (
     run_scheduler_command,
     run_worker_command,
 )
-from terp.cli.openapi import _load_app, export_openapi
+from terp.cli.openapi import _load_app, export_openapi, run_openapi_command
 from terp.cli.routes import run_routes_command
 from terp.cli.profiles import DEFAULT_PROFILE, profile_names
 from terp.cli.scaffold import new_module, new_module_message
@@ -133,6 +133,9 @@ Then the codegen chain, in this order — each step reads what the one before it
 
 `terp verify` runs the drift halves of that chain and names the command to re-run when
 something is stale, so it is the one to reach for if you are unsure what is out of date.
+An API-only app (rendered with the template's `frontend: false`, ADR 0202) has no
+frontend: its chain is `terp migrate make`, `terp openapi` and `terp check`, and
+`terp new module` writes no frontend slot where there is none.
 Policy.default() = authenticated; read VIEWER, write EDITOR.
 
 FORMATTING: `terp fmt`, NOT `ruff format .`
@@ -339,11 +342,15 @@ Both are comma-separated. The procedure, in this order:
   1. Put the old key in BOTH lists and the new one in SECRET_KEY. Deploy.
   2. Run `terp secrets reseal` where the app runs (its own container, its own
      environment). It rewrites every value sealed under a fallback under SECRET_KEY,
+     one nested in a JSON column included (a queued mail in the outbox, ADR 0199),
      one transaction per table, refuses while a migration is pending, is safe to run
      twice, and exits 0 only when nothing is left. `--check` counts and writes nothing.
   3. Drop SECRET_KEY_DECRYPT_FALLBACKS once reseal reports nothing left. Keep the old
      key itself while a backup sealed under it may still be restored: restoring one
-     means listing it again and running reseal.
+     means listing it again and running reseal. A self-service link already mailed is
+     sealed under the key it was sent under, where reseal cannot reach it, so dropping
+     the fallback sooner than its lifetime (a day for a sign-up link by default) only
+     makes such a link stop working, and its owner asks for a new one.
   4. Drop SECRET_KEY_FALLBACKS once the longest signature lifetime has passed since
      step 1: REFRESH_TOKEN_TTL_SECONDS if the app issues refresh sessions, 15 minutes
      if not. Dropping it sooner loses nothing; it signs out sessions still on the old key.
@@ -1100,9 +1107,27 @@ The security declaration (SecurityConfig, refused at production boot)
   /openapi.json are hidden there because a production API's full schema is not public
   information. Development always serves them, and `terp openapi` exports the document
   either way - so turning this on is a choice to publish, not a way to get the file.
+  Commit that file instead: `openapi.json` is the app's API contract, the one a mobile
+  app or a site in another repository pins, and `terp verify --only api-contract` holds
+  it to the API the app serves, naming every change to its shape, the ones that break a
+  client first (ADR 0194). Who may call a route is not in it: authz-surface pins that.
 - headers ships a safe SecurityHeaders set; max_request_bytes (1 MiB) is the body cap and
   is per-mount overridable (ADR 0067); request_id_header names the correlation header
   ("X-Request-ID") echoed on every response.
+- A NATIVE MOBILE CLIENT stays signed in through its own routes, opt-in with a reason
+  (ADR 0195): build_login_module(..., native_clients=NativeClients(reason="...")) mounts
+  POST /api/v1/auth/native/login, /native/refresh and /native/logout. The first two answer
+  the refresh token in the JSON body and run the same rotation, reuse detection and
+  revocation as the cookie, its rotation grace window included; /native/logout takes the
+  token and revokes its whole family without minting a successor. The client keeps that
+  token in the OS keychain or keystore and nowhere else, and treats a 401 from
+  /native/refresh as signed out. All three refuse any request with browser provenance
+  (Origin, any Sec-Fetch-* header, the refresh cookie) with 403 native_client_only before
+  the body is validated, so a browser stays on /login, /refresh and /logout. A HYBRID app
+  (a page inside a native shell) calls them from its native layer and hands its page only
+  access tokens: a page that holds the refresh token has given up what the cookie
+  protects. No route that mints a credential (/login, /token, /refresh, /native/login,
+  /native/refresh) accepts an Idempotency-Key; retry without one.
 - No terp.arch check applies - there is no module code shape to police. Enforcement is
   the create_app production fail-fast plus the production-readiness verify lane.
 """,
@@ -1213,6 +1238,21 @@ Password strength (PasswordPolicy, Tier-B)
   The reason is the opt-out: it is stored as `relaxed_reason` and named back to you in the
   BootError, so "why is this off" always has an answer that travels with the declaration.
       PasswordPolicy.relaxed(reason="legacy bulk import")
+- SELF-SERVICE accounts (ADR 0196) hold sign-up and reset to the same policy. They are
+  opt-in and never discovered: after configure_mail(...), build the module and mount it
+      build_accounts_module(SelfService(reason="members open their own accounts",
+          users=users_service, throttle_store=shared_store,
+          link_base="https://app.example.com"))
+  for POST /api/v1/accounts/sign-up, /verify, /password-reset, /password-reset/confirm
+  and /me/close. Sign-up takes only the address: the account opens when the mailed token
+  is redeemed at /verify with the password, so whoever asked cannot choose it. Every
+  request about an address answers 202 the same way and sends that address exactly one
+  message, whether or not it has an account, and addresses compare case-insensitively.
+  Tokens are sealed, expire, work once, and ride the URL fragment, so your account pages
+  read them from location.hash and post them. Closing needs the password again and ends
+  every session (AccountDeletion.SCRUB by default, or REMOVE: building the module refuses
+  it while a reference to the user table would refuse the delete, so declare CASCADE or
+  SET NULL on that reference; one the build cannot see is scrubbed instead, with a warning).
 - No terp.arch check applies (no module code shape to police) — enforcement is the
   service chokepoint plus the create_app production fail-fast.
 """,
@@ -1716,11 +1756,35 @@ File objects (files capability, ADR 0056/0057)
   objects) in a NAMED-PROFILE registry;
   metadata (name, type, size, sha256, storage_key, storage_profile) lives in the platform
   DB. storage_key/storage_profile never leave the boundary (FileRead omits both).
-- Any provider is an adapter subclass (local ships; S3/Azure/NAS are each a
-  StorageBackend). Register each store once at the composition root:
-      register_storage_backend("azure-invoices", AzureBlobStorage(container="invoices"))
-      register_storage_backend("azure-hr", AzureBlobStorage(container="hr"))
-  Keep credentials in settings / sealed config — never in module code.
+- Any provider is an adapter subclass (local ships; a NAS mount is the local adapter on
+  another root). Two object-store adapters ship behind extras (ADR 0201): S3Storage
+  (terp-cap-files[s3]) takes the SDK's own client and a bucket; AzureBlobStorage
+  (terp-cap-files[azure]) takes the SDK's ContainerClient and, for user-delegation SAS
+  links, a BlobServiceClient under an Entra credential. Register each store once at the
+  composition root:
+      register_storage_backend("s3-media", S3Storage(boto3.client("s3"), bucket="app-media"))
+      register_storage_backend("azure-invoices", AzureBlobStorage(invoices_container))
+      register_storage_backend("azure-hr", AzureBlobStorage(hr_container, delegation=service))
+  Keep credentials in settings / sealed config — never in module code. Building the Azure
+  adapter without its extra fails at boot with the install line (StorageSdkMissingError);
+  the S3 adapter takes the SDK's client, so a missing extra fails where that is built.
+- A client that cannot send a bearer (an <audio>/<video> element, a PDF viewer, a native
+  client's media stack) gets a short-lived LINK to one file's bytes instead (ADR 0201):
+      GET /api/v1/files/{id}/link?ttl_seconds=600&inline=true   ->  {url, expires_at}
+  The link is minted where a download is authorized (row scope, then quarantine), by the
+  store the ROW names: an S3 presigned GET or an Azure SAS where the store can sign, else
+  an app-signed token the capability serves itself at GET /api/v1/files/link/{token} —
+  its one public route, rate-limited, answering 404 to an expired, altered or foreign
+  token. The default lifetime is an hour, the longest 24 hours; a link is not single-use
+  (a player makes many range requests), its expiry is the control. inline is honoured only
+  for a type a browser renders without running it (image, audio, video, PDF — not an XML
+  image such as SVG, which is a document with script in it). From a module, mint through
+  your own authorized row and a declared FileRef:
+      link = FileService().link_for(session, invoice, "attachment_file_id", ttl=timedelta(minutes=10))
+  Both content routes honour one bytes= Range (206 / 416); the local adapter seeks, an
+  object store's stream is read forward. A link from a store that signs never streams
+  through the API; the authenticated content route still serves any store's bytes to a
+  caller who asks it to.
 - Pick the store per module (subclass default) or per call — never from a client:
       class InvoiceFileService(FileService):
           storage_profile = "azure-invoices"
@@ -1924,6 +1988,11 @@ Sending e-mail (terp-cap-mail)
   dead-letters` lists it. With the
   in-process default queue (no worker) the mail is sent inline, and a failing relay
   fails the request that asked for it.
+- The queued message is SEALED at rest (ADR 0199): the outbox row's payload holds the
+  Message-ID and one value sealed under SECRET_KEY, never an address or the text. After a
+  key rotation keep SECRET_KEY_DECRYPT_FALLBACKS until `terp secrets reseal` reports
+  nothing left: a queued mail no configured key opens is never sent, and fails with
+  MailSealError, which names that remedy, until it dead-letters.
 - Test without a relay:
       from terp.capabilities.mail import (
           CapturingMailTransport, MailSettings, configure_mail, reset_mail)
@@ -2757,7 +2826,12 @@ FOUR STATES, EXACTLY ONE AT A TIME
   "build": "generated"            the framework renders Dockerfile.prod,
                                   frontend/Dockerfile.prod and docker-compose.prod.yml
                                   from this file (`terp deployment render`), and a
-                                  committed copy that is not the render is refused
+                                  committed copy that is not the render is refused.
+                                  frontend/Dockerfile.prod only beside a web unit: an api
+                                  unit with no web unit in front of it is the deployment's
+                                  only way in and publishes ${API_PORT:-23200}:8000 (ADR
+                                  0202) -- the shape an app rendered API-only (the
+                                  template's `frontend: false`) has from the start
   {"unmanaged": true, "reason"}   no tool can drive this deploy; the checks are off and
                                   a tool shows the reason. Nothing may stand beside it.
 
@@ -2854,7 +2928,8 @@ or an override; externalDatabase beside a database unit; a database or store wit
 or two of a kind; a one-shot that declares `terp migrate upgrade` (drop the command: the
 one-shot without one is the migration step) or a second step; a role with no command of
 its own and none declared; a web unit with a command, with no single api to proxy to, or
-without frontend/package-lock.json; an api without both health paths; a start-order cycle
+without frontend/package-lock.json; two or more api units with no web unit in front of
+them (which one callers reach would be a guess); an api without both health paths; a start-order cycle
 or a unit it names that is not declared; a volume without its mount, mounted anywhere but
 var/files, on a unit not on the backend image, or on a unit that already mounts another
 volume there (Compose would mount only the last of them, without a word); any system
@@ -3000,14 +3075,20 @@ build container holds a credential or writes into what is built. Each takes the
     <registry>/<image>:<tag> with the credential your docker configuration holds for this
     release. It writes terp-release-build.json: BuildKit's own digests.
   uv run terp release gate --sha <sha> --build terp-release-build.json
-    runs in a clean checkout of the commit: `terp verify --profile release --format
-    assurance` with npm's scripts off, then the schedule catalog, read by running the pushed
-    image sealed (no network, read-only, its own non-root user). It holds no push credential
-    and no key. It writes terp-release-gate.json.
+    runs in a clean checkout of the commit: `terp verify --profile release` once, with npm's
+    scripts off, recording every check's verdict and the release-assurance claim those same
+    results compose (no check's output), then the schedule catalog, read by running the
+    pushed image sealed (no network, read-only, its own non-root user). It holds no push
+    credential and no key. It writes terp-release-gate.json, and exits 1 unless every check
+    passed and the claim holds, naming each red check. Run it from the commit's own
+    environment: sign reads the document only in the version the commit's pinned terp-cli
+    writes (ADR 0200).
   terp release sign --sha <sha> --tag <tag> --registry ... --build ... --gate ... \\
       --hosts separated --signer '["your-kms-signer", "--key", "release"]' --public-key k.pub
     runs from the signer image, never the commit's own toolchain, and runs nothing of the
-    app: it repeats the refusals, renders a generated app's files with the terp-arch the
+    app: it repeats the refusals, refuses a gate with a red check or a claim that does not
+    hold (ADR 0200; a commit pinning terp-cli below 0.36.1 has a gate that records the claim
+    alone, and is held to it), renders a generated app's files with the terp-arch the
     commit pins (fetched by hash, run in a process of its own), reads the backend image from
     the registry as data and holds it to the tree and the lock, scans for known
     vulnerabilities and for secrets in the history, and signs the manifest as a DSSE envelope
@@ -5182,7 +5263,7 @@ def main(argv: Sequence[str] | None = None) -> None:
             emit(f"wrote {path}")
         return
     if args.command == "openapi":
-        emit(f"wrote {export_openapi(args.app, out=args.out, app_root=args.app_root)}")
+        emit(run_openapi_command(args.app, out=args.out, app_root=args.app_root))
         return
     if args.command == "routes":
         emit(