create-ortha-app 0.4.3 → 0.5.0

package/templates/default/apps/server/ortha.config.ts

@@ -1,7 +1,12 @@
 /**
  * Typed configuration for this app.
  *
- * **`config/` is the single place that reads `process.env`.** Everything
+ * **`config/` is the single place that reads the environment**, and it reads it
+ * only through the readers in `@orthacms/utils-server` — never `process.env`
+ * directly. `readEnv` is where "an empty value means the setting is absent" is
+ * decided, and `.env` ships keys with nothing on the right-hand side; a raw
+ * `process.env['X'] ?? default` skips that decision and lets a blank line win
+ * over the default. Everything
  * downstream — the host, every plugin — receives typed values, so "where does
  * this setting come from" has exactly one answer. Deploy-specific values come
  * from the environment; stable product tuning lives in the builders as literals.

package/templates/default/apps/server/src/plugins.spec.ts

@@ -29,12 +29,18 @@ const EXPECTED_PLUGINS = [
     'activity',
     'users',
     'content',
+    // A second entry from the content package: `ServerPlugin.migrations` holds
+    // one descriptor per entry, and saved list views ship their own tables.
+    'content-views',
     // ortha:if graphql
     'content-graphql',
     // ortha:end
     'i18n',
     'alarms',
+    'webhooks',
     'media',
+    'transfer',
+    'segments',
     'copilot'
     // ortha:if mcp
     ,

package/templates/default/apps/server/src/plugins.ts

@@ -4,10 +4,18 @@ import { ContentPlugin, ContentViewsPlugin } from '@orthacms/content-server';
 import { DatabasePlugin } from '@orthacms/database';
 import { I18nServerPlugin } from '@orthacms/i18n-server';
 import { IdentityPlugin } from '@orthacms/identity-server';
-// ortha:if sso-oidc
+// ortha:if sso
 import type { SsoRegistration } from '@orthacms/identity-domain';
+// ortha:end
+// ortha:if sso-oidc
 import { createOidcProvider } from '@orthacms/identity-provider-oidc';
 // ortha:end
+// ortha:if sso-github
+import { createGithubProvider } from '@orthacms/identity-provider-github';
+// ortha:end
+// ortha:if sso-saml
+import { createSamlProvider } from '@orthacms/identity-provider-saml';
+// ortha:end
 import { MediaServerPlugin } from '@orthacms/media-server';
 // ortha:if media-local
 import { createLocalStorageProvider } from '@orthacms/media-provider-local';
@@ -26,6 +34,9 @@ import { createVercelBlobStorageProvider } from '@orthacms/media-provider-vercel
 // ortha:end
 import { UsersPlugin } from '@orthacms/users-server';
 import { AlarmsPlugin } from '@orthacms/alarms-server';
+import { SegmentsPlugin } from '@orthacms/segments-server';
+import { TransferPlugin } from '@orthacms/transfer-server';
+import { WebhooksPlugin } from '@orthacms/webhooks-server';
 // ortha:if graphql
 import { ContentGraphqlPlugin } from '@orthacms/content-graphql';
 // ortha:end
@@ -59,13 +70,14 @@ import type { OrthaConfig } from '../ortha.config';
  * must stay `false` until a backend is configured — enabling it with an empty
  * list fails at boot rather than shipping a chat that cannot answer.
  */
-// ortha:if sso-oidc
+// ortha:if sso
 /**
  * The identity providers this app can actually reach.
  *
  * **Only what is configured is registered.** `ortha.config.ts` omits a provider
- * whose issuer or client id is missing, and an unconfigured one is skipped here
- * too — it would appear on the sign-in page as a button that can only fail.
+ * whose connection settings are missing, and an unconfigured one is skipped
+ * here too — it would appear on the sign-in page as a button that can only
+ * fail.
  *
  * Running two directories at once is another entry. The name is what
  * `/api/auth/sso/<name>/start` and every `sso_identities` row refer to the
@@ -75,12 +87,28 @@ import type { OrthaConfig } from '../ortha.config';
  * string, which matters because most providers match it byte for byte.
  */
 export function ssoProviders(config: OrthaConfig): SsoRegistration[] {
-    const oidc = config.plugins.identity.ssoProviders?.oidc;
-    if (!oidc) {
-        return [];
+    const configured = config.plugins.identity.ssoProviders;
+    const providers: SsoRegistration[] = [];
+    // ortha:if sso-oidc
+    if (configured?.oidc) {
+        const { name, ...settings } = configured.oidc;
+        providers.push({ name, provider: createOidcProvider(settings) });
+    }
+    // ortha:end
+    // ortha:if sso-github
+    if (configured?.github) {
+        const { name, ...settings } = configured.github;
+        providers.push({ name, provider: createGithubProvider(settings) });
     }
-    const { name, ...settings } = oidc;
-    return [{ name, provider: createOidcProvider(settings) }];
+    // ortha:end
+    // ortha:if sso-saml
+    if (configured?.saml) {
+        const { name, ...settings } = configured.saml;
+        providers.push({ name, provider: createSamlProvider(settings) });
+    }
+    // ortha:end
+
+    return providers;
 }
 // ortha:end
 
@@ -138,7 +166,7 @@ export function buildPlugins(config: OrthaConfig): ServerPlugin[] {
     return [
         // First: the only plugin that opens a resource in `onPluginInit`.
         DatabasePlugin({ connectionString: config.database.url }),
-        // ortha:if sso-oidc
+        // ortha:if sso
         // Identity, plus the identity providers this app offers. The second
         // argument is where constructed adapters go: `ortha.config.ts` holds
         // the typed view of the environment, and an adapter instance is not an
@@ -147,14 +175,14 @@ export function buildPlugins(config: OrthaConfig): ServerPlugin[] {
             sso: { providers: ssoProviders(config) }
         }),
         // ortha:end
-        // ortha:ifnot sso-oidc
+        // ortha:ifnot sso
         IdentityPlugin(config.plugins.identity),
         // ortha:end
         WorkspacesPlugin(),
         ActivityPlugin(),
         UsersPlugin(),
-        // No content types yet. Define some in `src/server/content/`, pass them
-        // here as `types`, then add a `drizzle.config.ts` pointing at them and
+        // No content types yet. Define some in `apps/server/src/content/`, pass
+        // them here as `types`, then add a `drizzle.config.ts` pointing at them and
         // a `migrations` descriptor so `ortha generate` / `ortha migrate` can
         // manage their tables:
         //
@@ -197,6 +225,10 @@ export function buildPlugins(config: OrthaConfig): ServerPlugin[] {
         // blocking a save or a publish. After content, whose registry and
         // filter surface it evaluates rules through.
         AlarmsPlugin(),
+        // Outgoing webhooks. Inert until someone adds an endpoint in the admin,
+        // and it only subscribes to the outbox, so nothing depends on it being
+        // registered any earlier than this.
+        WebhooksPlugin(),
         MediaServerPlugin({
             // ortha:if media-local
             provider: createLocalStorageProvider(config.plugins.media.storage),
@@ -217,6 +249,29 @@ export function buildPlugins(config: OrthaConfig): ServerPlugin[] {
             // ortha:end
             config: config.plugins.media
         }),
+        // Content export and import, one hop deep: relations, files and
+        // locales travel with a record, relations-of-relations stay as
+        // references. After content (every write goes through its writer, so
+        // an import cannot outrun validation or your own permissions) and
+        // after media (files travel with the records that use them). Owns no
+        // tables.
+        //
+        // The setting worth filling in per install is `identity`: it says
+        // which field identifies a record of each type, which is what lets an
+        // import recognise "this is that record" instead of adding a
+        // duplicate. Without it the natural key is a heuristic —
+        // `TransferPlugin({ identity: { post: ['slug'] } })`.
+        TransferPlugin(),
+        // Reader entitlements — who may *read* published content, as against
+        // who may touch it. After content, whose read-scope port it binds, so
+        // one decision covers REST, GraphQL and MCP at once.
+        //
+        // Registering it changes nothing on its own: with no audience created
+        // in the admin no predicate is emitted and every read costs what it
+        // did before. The line to fill in per install is `resolver` — it says
+        // where a reader's tags come from, and its absence means every reader
+        // is anonymous, which serves unrestricted content and nothing else.
+        SegmentsPlugin(),
         // Registered after workspaces (runs are workspace-scoped) and identity
         // (runs execute as the calling user, gated on `copilot:use`). The
         // composition root is the single place that selects a backend: the

package/templates/default/env.tmpl

@@ -138,8 +138,85 @@ SSO_OIDC_LABEL=
 # claiming an existing account.
 SSO_OIDC_EMAIL_VERIFIED_WHEN_ABSENT=
 # ortha:end
+# ortha:if sso-github
+# GitHub, or GitHub Enterprise Server. Both of these are what make the provider
+# configured at all — and unlike OIDC the secret is not optional: GitHub's code
+# exchange has no PKCE, so the secret is the only thing proving the code is
+# being redeemed by this application.
+# Register <origin>/api/auth/sso/<SSO_GITHUB_NAME>/callback as the OAuth app's
+# authorization callback URL.
+SSO_GITHUB_CLIENT_ID=
+SSO_GITHUB_CLIENT_SECRET=
+# What the route and every sso_identities row call this provider. Renaming it
+# orphans the links that name it. Default: github
+SSO_GITHUB_NAME=
+# The sign-in button's text. Default: GitHub
+SSO_GITHUB_LABEL=
+# Comma-separated. Defaults to `read:user,user:email` — a profile and the
+# verified addresses on it. GitHub's scopes are coarse, so anything wider hands
+# this CMS access it has no use for.
+SSO_GITHUB_SCOPES=
+# For GitHub Enterprise Server, e.g. https://github.acme.com. Leave empty for
+# github.com.
+SSO_GITHUB_ENTERPRISE_BASE_URL=
+# Restricts the account chooser to one organisation's members. Cosmetic: who
+# actually gets in is this CMS's decision, not GitHub's.
+SSO_GITHUB_ORGANIZATION=
+# ortha:end
+# ortha:if sso-saml
+# SAML 2.0. All three are required and none has a fallback: SAML has no
+# discovery document and no key endpoint, so the certificate you copy out of
+# your identity provider is the whole of the trust relationship.
+# The IdP's single-sign-on URL, where the AuthnRequest is sent.
+SSO_SAML_ENTRY_POINT=
+# The IdP's signing certificate, PEM or bare base64. An environment variable
+# cannot hold real newlines, so `\n` escapes are accepted and put back.
+SSO_SAML_IDP_CERT=
+# This CMS's entity id — the Issuer on the AuthnRequest, and what the IdP has
+# registered as the service provider.
+SSO_SAML_ISSUER=
+# What the route and every sso_identities row call this provider. Renaming it
+# orphans the links that name it. Default: saml
+SSO_SAML_NAME=
+# The sign-in button's text. Default: SAML
+SSO_SAML_LABEL=
+# The attribute holding a STABLE identifier for the person. Worth setting
+# whenever your IdP's NameID format is emailAddress: an address is not a stable
+# identifier, and a profile whose subject is one is refused.
+SSO_SAML_SUBJECT_ATTRIBUTE=
+# Which attributes to read, when the usual spellings are not what your IdP
+# sends. Left empty, each falls back to a list of the common ones.
+SSO_SAML_EMAIL_ATTRIBUTE=
+SSO_SAML_NAME_ATTRIBUTE=
+SSO_SAML_GROUPS_ATTRIBUTE=
+# Set to true ONLY if you are asserting that this directory owns the addresses
+# it reports. SAML carries no verification claim at all — there is nothing to
+# read — and this is the only gate on a first sign-in claiming an existing
+# account.
+SSO_SAML_EMAIL_VERIFIED=
+# ortha:end
 # The origin browsers reach the API on, when the admin is served from a
 # different one. Leave empty for the usual same-origin deployment.
 SSO_PUBLIC_BASE_URL=
 # How long one sign-in attempt stays live, in seconds. Default 600.
 SSO_REQUEST_TTL_SECONDS=
+
+# --- webhooks (outgoing notifications on content changes) ---
+# Endpoints live in the database — add them in the admin's Webhooks page
+# (administrator-only). These settings are how hard the sender pushes and where
+# it is allowed to reach.
+#
+# How often the sender looks for queued deliveries, in milliseconds. 0 queues
+# but never sends from this process.
+WEBHOOKS_DELIVERY_INTERVAL=2000
+# Per-request timeout, in milliseconds.
+WEBHOOKS_TIMEOUT=10000
+# How long a finished delivery stays in the log. Nothing else prunes it.
+WEBHOOKS_RETENTION_DAYS=30
+# Permit http:// destinations — for local development only; the payload is
+# readable to anyone on the path even though it is signed.
+WEBHOOKS_ALLOW_INSECURE_URLS=false
+# Permit loopback and RFC 1918 destinations. OFF by default: a webhook is the
+# server making a request to an address a user typed, which is the shape of
+# every SSRF. Turn it on only if your receiver really is inside this network.
+WEBHOOKS_ALLOW_PRIVATE_NETWORKS=false