@cratis/pi 7.126.0 → 7.128.0

package/package/corpus/skills/cratis-showrunner-herald/references/templates-and-images.md

@@ -0,0 +1,70 @@
+# Templates and images
+
+## Layout
+
+```
+Emails/
+  invitation.json          the values the invitation email accepts
+  invitation.en.html       English
+  invitation.nb.html       Norwegian
+  images/
+    logo.png
+```
+
+## Manifest
+
+```json
+{
+  "values": [
+    { "name": "invitation.link", "required": true },
+    "invitation.expiresAt",
+    "inviter.name"
+  ]
+}
+```
+
+A plain string is an optional value. A required value that is missing or blank stops the email
+before it is queued. A name cannot be both a value and a group (`inviter` and `inviter.name`),
+and `look` is reserved for `look.brandColor` and `look.footer`.
+
+## Template
+
+A header between two `---` lines carries `subject` and optionally `preview`; both may use values.
+Then email-ready HTML.
+
+```html
+---
+subject: {{inviter.name}} invited you to Ledger
+preview: Accept the invitation before {{date invitation.expiresAt "d MMMM"}}
+---
+<html>
+<head><style>.button { background-color: {{look.brandColor}}; color: #ffffff; }</style></head>
+<body>
+  <table role="presentation" width="600" align="center"><tr><td>
+    <img src="cid:logo.png" alt="Ledger" width="120">
+    {{#if inviter.name}}<p>{{inviter.name}} invited you.</p>{{/if}}
+    <a class="button" href="{{invitation.link}}">Accept the invitation</a>
+    <p>{{look.footer}}</p>
+  </td></tr></table>
+</body>
+</html>
+```
+
+Author for email clients: table layout, about 600 px wide, `role="presentation"` on layout tables,
+an `alt` on every image. Write styles in a `<style>` element; Herald moves the rules into `style`
+attributes at render. Media queries stay in the element.
+
+## Rendering rules
+
+- Every value is HTML-encoded in the body, quotes in attributes included. Subject and preview are plain text and not encoded.
+- The subject is collapsed to one line. The plain-text alternative is generated from the HTML.
+- Dates are ISO 8601 and formatted in the culture of the email's language.
+- Language falls back from `nb-NO` to `nb` to `DefaultLanguage`; the language used is recorded.
+
+## Images
+
+Referenced as `cid:logo.png` and embedded inline, so nothing is hosted and no remote content has
+to be allowed. PNG, JPEG and GIF are embedded. SVG and anything else fail the rendering with an
+error naming the file, because mail clients do not render SVG; export a PNG at twice the display
+size. A referenced image that is missing also fails rendering. File names use letters, digits,
+dots, dashes and underscores and are looked up only inside the images folder.

package/package/corpus/skills/cratis-stage-rendering-and-sandbox/SKILL.md

@@ -206,6 +206,11 @@ generated application: API on `9090`, Workbench on `https://localhost:35000`.
 Requires Cratis CLI 3.73.0 for the semantic engine by default, 3.75.0 for v27 keys;
 older CLIs use the legacy EventModel engine, which does not enforce authorization.
 Unsigned caller headers make sandbox authorization no security boundary.
+A model with `authentication` makes `cratis run` start a stack instead: AuthProxy (the
+address to open), the Stage with `Stage__Sandbox__ForwardedIdentity=true` so it trusts the
+forwarded identity instead of playing a persona, and with `onboarding` Ante and MongoDB.
+`cratis render` realizes authentication and onboarding (`references/rendered-application.md`).
+Requires cratis CLI 3.116.0 (`cratis --version`); older CLIs run the Stage alone and play a persona.
 Read [references/sandbox-and-specrunner.md](references/sandbox-and-specrunner.md)
 before running either image: engine selection, protected reads, outside-append
 conflicts/retries, reached bodies, authored occurrence and generated-spec limits live there.

package/package/corpus/skills/cratis-stage-rendering-and-sandbox/references/rendered-application.md

@@ -6,6 +6,7 @@
 - Runtime package migration
 - Lists on screen
 - Reducer layout for new applications
+- Authentication and onboarding
 - What is managed
 - `Customizations/` (unmanaged)
 - Re-render checklist
@@ -104,6 +105,53 @@ an existing classic application to `self`: observer identity and old reducer rem
 need migration-aware publication. This opt-in does not automatically change CLI,
 Studio or semantic-engine execution.
 
+## Authentication and onboarding
+
+A model with an `authentication` block renders an application that runs behind AuthProxy
+and trusts the identity it forwards. The model's `onboarding` block renders the code that
+acts on the outcomes of the application's own Ante. Both are realized by the renderer;
+none of it is hand-written gap-fill.
+
+Requires cratis CLI 3.116.0 with Stage 4.211.0 (`cratis --version`); older releases report `authentication` and `onboarding` as unrendered warnings.
+
+| Rendered | Purpose |
+| --- | --- |
+| `appsettings.json` with `Cratis:Arc:TrustForwardedIdentityHeaders` true | Arc builds the caller from the headers AuthProxy forwards. |
+| `GeneratedAuthentication/` (`Personas`, `MemberIdentity`, `RuntimeConventions`) | Roles and claims per persona, the identity of a person, and the Chronicle connection string read from `CRATIS_CHRONICLE_CONNECTION_STRING_FILE`. |
+| `GeneratedOnboarding/` | Reactor on Ante's outcomes, idempotent provisioning, the invite-member command, member persona claims, Herald email sending. |
+| `Emails/` | Email templates and images laid out for Herald. |
+| `.runtime/authproxy.application.json`, `.runtime/ante.onboarding.json`, `.runtime/environment.json` | What a runtime (`cratis run`, Stage Manager) starts AuthProxy and Ante with, and the environment keys the model needs. |
+
+- The identity headers are unsigned. Never expose a rendered application with authentication
+  except through AuthProxy.
+- Only provider kinds AuthProxy supports render (`EntraId`, `GitHub`, `Google`, `Apple`,
+  `OpenId`). Another kind is left out with `STAGE-AUTH-001`; a persona that is not a
+  requirement on authentication, roles or claims is never matched (`STAGE-AUTH-002`).
+- `offering <Name>` renders against Box Office: the default offering is declared, and a
+  retrying reactor on tenant provisioning starts each new tenant on it (`StartTenant`) as soon as
+  the operator publishes the offer. Provisioning and the welcome email do not wait for it.
+  `STAGE-ONBOARDING-008` is information: the operator must publish an offer with that name, and
+  Box Office seat and compute policies are not rendered. Requires Stage 4.212.0
+  for the offering and the declined email; older renderers render neither.
+  `STAGE-ONBOARDING-002` to `-006` cover a tenant invitation with no command,
+  a sign-up without a first-member persona, a legal document count other than two, a
+  missing email template and an invitation without inviters. `-001` and `-007` are retired
+  and never reused.
+- An invitation Ante rejects (a persona or invitation type the model does not allow) is a
+  mistake in the invitation, not a decision about the person: the application records
+  `OnboardingInvitationRejected` and logs a warning for an administrator, and emails no
+  one.
+- The `signupDeclined` template is sent on `OrganizationRegistrationDeclined`, with the
+  reviewer's message as `decline.message`, once per registration. Ante publishes that only
+  when sign-up review is on; the model has no review syntax, so a rendered application leaves
+  review off and the host adds approve and decline commands by hand (`cratis-onboarding-runtime`).
+- An application with onboarding pins a newer Chronicle client and kernel image than
+  other applications; read them from the rendered files.
+- Realization needs the model folder: email images are read from the model root.
+
+Read the Stage references `authentication-rendering.md` and `onboarding-rendering.md` for
+exact files and keys.
+
 ## What is managed
 
 Every path in `.cratis-render.json` is managed: the scaffold files (project, solution,

package/package/corpus/skills/cratis-stage-rendering-and-sandbox/references/sandbox-and-specrunner.md

@@ -49,6 +49,13 @@ ports or an authenticated proxy). Rendered applications use the renderer's admit
 authorization instead, which is the thing to test for production behavior (Debug tests
 of a render, [render-example.md](render-example.md)).
 
+`Stage__Sandbox__ForwardedIdentity=true` (`Stage:Sandbox:ForwardedIdentity`) is the exception:
+the sandbox runs behind AuthProxy, trusts the identity it forwards and plays no persona, so the
+signed-in caller is the caller authorization runs for. It overrides `Stage:Sandbox:Identity`.
+`cratis run` sets it when the model declares `authentication`; set it yourself only behind an
+AuthProxy, because the headers are unsigned and anything that can reach the sandbox directly
+can forge them. Requires Stage 4.211.0; an older sandbox ignores the setting.
+
 The semantic Host encrypts personal-data and secret concepts at rest through Chronicle and
 releases values on read; erasure deletes event-source keys. Encryption applies to new
 writes only: events already stored in plaintext in an existing Play store are not

package/package/profile-catalog.json

@@ -522,7 +522,8 @@
         "cratis-chronicle-reducer",
         "cratis-event-model-diagram",
         "cratis-multi-service-architecture",
-        "cratis-multi-service-local-orchestration"
+        "cratis-multi-service-local-orchestration",
+        "cratis-showrunner-herald"
       ],
       "languages": [
         "csharp",
@@ -623,7 +624,8 @@
       "availableTargets": [
         "cratis-commits-and-pull-requests",
         "cratis-rtk",
-        "cratis-chronicle-cli-operations"
+        "cratis-chronicle-cli-operations",
+        "cratis-environments-and-secrets"
       ],
       "languages": [
         "shell"
@@ -953,6 +955,7 @@
       "availableTargets": [
         "cratis-commits-and-pull-requests",
         "cratis-rtk",
+        "cratis-screenplay-authentication-and-onboarding",
         "cratis-screenplay-automations-and-translations",
         "cratis-screenplay-captures-and-reactions",
         "cratis-screenplay-command-surface",
@@ -1026,6 +1029,7 @@
       "availableTargets": [
         "cratis-commits-and-pull-requests",
         "cratis-rtk",
+        "cratis-onboarding-runtime",
         "cratis-stage-rendering-and-sandbox"
       ],
       "languages": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.126.0",
+  "version": "7.128.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [