create-ortha-app 0.4.2 → 0.5.0

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

@@ -0,0 +1,129 @@
+/** Identity — sessions, tokens, the SSO handshake, and the first admin. */
+import type { IdentityPluginConfig } from '@orthacms/identity-server';
+// ortha:if sso-oidc
+import type { OidcProviderConfig } from '@orthacms/identity-provider-oidc';
+// ortha:end
+// ortha:if sso-github
+import type { GithubProviderConfig } from '@orthacms/identity-provider-github';
+// ortha:end
+// ortha:if sso-saml
+import type { SamlProviderConfig } from '@orthacms/identity-provider-saml';
+// ortha:end
+import {
+    defined,
+    isProduction,
+    readEnv,
+    readList,
+    readPositiveInt
+} from '@orthacms/utils-server';
+
+// ortha:if sso-oidc
+import { oidcProvider } from './sso-oidc';
+// ortha:end
+// ortha:if sso-github
+import { githubProvider } from './sso-github';
+// ortha:end
+// ortha:if sso-saml
+import { samlProvider } from './sso-saml';
+// ortha:end
+
+/**
+ * Identity settings, plus the identity providers this app can reach.
+ *
+ * The provider settings live here rather than inside `IdentityPluginConfig`,
+ * for the same reason the copilot's backends do: the plugin names no protocol,
+ * and this file is the one place that reads the environment. The constructed
+ * adapters are registered in `src/plugins.ts`.
+ */
+export interface AppIdentityConfig extends IdentityPluginConfig {
+    /**
+     * Identity providers, keyed by the name they are registered under. That
+     * name appears in the sign-in URL and in every `sso_identities` row, so
+     * renaming one orphans the links that name it.
+     *
+     * Optional, and absent unless this app was generated with single sign-on.
+     */
+    ssoProviders?: {
+        // ortha:if sso-oidc
+        /** A generic OpenID Connect provider. Present when both env vars are set. */
+        oidc?: OidcProviderConfig & { name: string };
+        // ortha:end
+        // ortha:if sso-github
+        /** GitHub or GitHub Enterprise Server. Present when both env vars are set. */
+        github?: GithubProviderConfig & { name: string };
+        // ortha:end
+        // ortha:if sso-saml
+        /** A SAML 2.0 identity provider. Present when all three env vars are set. */
+        saml?: SamlProviderConfig & { name: string };
+        // ortha:end
+    };
+}
+
+/** Identity — sessions, tokens, the SSO handshake, and the first admin. */
+export function identityConfig(): AppIdentityConfig {
+    return {
+        // Origins allowed to make state-changing calls (login-CSRF defence).
+        // In development that is the Vite dev server; in production the app is
+        // same-origin, so this list is what a separately-hosted admin would
+        // need adding to.
+        allowedOrigins: readList(
+            'ALLOWED_ORIGINS',
+            `http://localhost:${readPositiveInt('ADMIN_PORT', 4200)}`
+        ),
+        session: {
+            ttlSeconds: readPositiveInt('SESSION_TTL_SECONDS', 60 * 60 * 24 * 7),
+            cookieSecure: isProduction(),
+            cookieSameSite: 'lax' as const
+        },
+        token: {
+            inviteTtlSeconds: readPositiveInt(
+                'INVITE_TTL_SECONDS',
+                60 * 60 * 24 * 7
+            ),
+            resetTtlSeconds: readPositiveInt('RESET_TTL_SECONDS', 60 * 60)
+        },
+        rateLimit: {
+            ttlSeconds: readPositiveInt('LOGIN_RATE_LIMIT_TTL_SECONDS', 60),
+            limit: readPositiveInt('LOGIN_RATE_LIMIT', 10)
+        },
+        sso: ssoConfig(),
+        // ortha:if sso
+        ssoProviders: defined({
+            // ortha:if sso-oidc
+            oidc: oidcProvider(),
+            // ortha:end
+            // ortha:if sso-github
+            github: githubProvider(),
+            // ortha:end
+            // ortha:if sso-saml
+            saml: samlProvider()
+            // ortha:end
+        }),
+        // ortha:end
+        // With an email set, an admin is provisioned on boot — idempotent and
+        // non-destructive. This is how you get your first login.
+        // Read through `readEnv`, so all three are trimmed and a whitespace-only
+        // value is nothing rather than a value — a password of three spaces
+        // would otherwise be provisioned as the administrator's, silently.
+        rootAdmin: {
+            email: readEnv('ORTHA_ROOT_ADMIN_EMAIL') ?? '',
+            password: readEnv('ORTHA_ROOT_ADMIN_PASSWORD') ?? '',
+            name: readEnv('ORTHA_ROOT_ADMIN_NAME') ?? ''
+        }
+    };
+}
+
+/**
+ * The shape of the single sign-on handshake. The providers themselves are
+ * constructed in `src/plugins.ts`; these settings say how the round trip runs.
+ */
+function ssoConfig(): NonNullable<IdentityPluginConfig['sso']> {
+    return defined({
+        // The origin browsers reach this API on. It builds the redirect_uri
+        // you register with each provider, and it is configured rather than
+        // read from the request's Host header, which a client controls. Leave
+        // it unset when the admin and the API share an origin — the usual case.
+        publicBaseUrl: readEnv('SSO_PUBLIC_BASE_URL'),
+        requestTtlSeconds: readPositiveInt('SSO_REQUEST_TTL_SECONDS', 600)
+    });
+}

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

@@ -0,0 +1,25 @@
+// ortha:if mcp
+import type { McpPluginConfig } from '@orthacms/mcp-server';
+import { readFlag, readPositiveInt } from '@orthacms/utils-server';
+
+/** The MCP front door — off unless an operator turns it on. */
+export function mcpConfig(): McpPluginConfig {
+    return {
+        // Off by default: once on, any holder of a full-scope API token can
+        // drive content CRUD from an external agent.
+        enabled: readFlag('MCP_ENABLED', false),
+        // The identity MCP clients display in their connector lists.
+        name: '__APP_NAME__',
+        version: '1.0.0',
+        // A request/response transport owes its caller an answer, and the tool
+        // registry has no deadline of its own — so without this the only bound
+        // on a `tools/call` is the query underneath it, and a blocked pool
+        // turns one call into a socket held until the client gives up.
+        callTimeoutMs: readPositiveInt('MCP_CALL_TIMEOUT_MS', 30_000),
+        // Deliberately generous: the ceiling exists to stop a pathological
+        // result being serialised several times over, not to shape normal use.
+        // A result this large does not fit a model's context anyway.
+        maxResultBytes: readPositiveInt('MCP_MAX_RESULT_BYTES', 4_194_304)
+    };
+}
+// ortha:end

package/templates/default/apps/server/config/media-storage.ts

@@ -0,0 +1,84 @@
+/**
+ * Where uploads are written.
+ *
+ * One block per adapter, and the wizard picks exactly one — so a generated app
+ * has the body it chose and nothing else. Swapping backends later means
+ * swapping this file, the type on `AppMediaConfig.storage`, and the factory
+ * `src/plugins.ts` imports; nothing inside the media package changes.
+ */
+// ortha:if media-local
+import type { LocalStorageConfig } from '@orthacms/media-provider-local';
+import { readEnv } from '@orthacms/utils-server';
+
+/** Local-filesystem blobs. */
+export function mediaStorage(): LocalStorageConfig {
+    return {
+        // Point MEDIA_LOCAL_ROOT at a persistent volume in production: a
+        // container's own disk is wiped on every deploy.
+        rootDir: readEnv('MEDIA_LOCAL_ROOT') ?? './.storage/media'
+    };
+}
+// ortha:end
+// ortha:if media-vercel-blob
+import type { VercelBlobStorageConfig } from '@orthacms/media-provider-vercel-blob';
+import { defined, readEnv } from '@orthacms/utils-server';
+/** Vercel Blob. */
+export function mediaStorage(): VercelBlobStorageConfig {
+    return defined({
+        // On Vercel the SDK reads BLOB_READ_WRITE_TOKEN itself, so this is only
+        // for running the app elsewhere.
+        token: readEnv('BLOB_READ_WRITE_TOKEN')
+    });
+}
+// ortha:end
+// ortha:if media-gcs
+import type { GcsStorageConfig } from '@orthacms/media-provider-gcs';
+import { defined, readEnv, readFlag, requireEnv } from '@orthacms/utils-server';
+/** Google Cloud Storage. */
+export function mediaStorage(): GcsStorageConfig {
+    return defined({
+        bucket: requireEnv('MEDIA_GCS_BUCKET'),
+        // Everything else is optional: with no key file and no inline
+        // credentials the client uses Application Default Credentials, which is
+        // what a GKE or Cloud Run deployment wants.
+        projectId: readEnv('MEDIA_GCS_PROJECT_ID'),
+        keyFilename: readEnv('MEDIA_GCS_KEY_FILE'),
+        signWithIam: readFlag('MEDIA_GCS_SIGN_WITH_IAM', false)
+    });
+}
+// ortha:end
+// ortha:if media-azure
+import type { AzureStorageConfig } from '@orthacms/media-provider-azure';
+import { requireEnv } from '@orthacms/utils-server';
+/** Azure Blob Storage. */
+export function mediaStorage(): AzureStorageConfig {
+    return {
+        container: requireEnv('MEDIA_AZURE_CONTAINER'),
+        connectionString: requireEnv('MEDIA_AZURE_CONNECTION_STRING')
+    };
+}
+// ortha:end
+// ortha:if media-s3
+import type { S3StorageConfig } from '@orthacms/media-provider-s3';
+import { defined, readEnv, readFlag, requireEnv } from '@orthacms/utils-server';
+/** S3 or an S3-compatible endpoint — R2, MinIO, Spaces, B2. */
+export function mediaStorage(): S3StorageConfig {
+    const accessKeyId = readEnv('MEDIA_S3_ACCESS_KEY_ID');
+    const secretAccessKey = readEnv('MEDIA_S3_SECRET_ACCESS_KEY');
+    return defined({
+        bucket: requireEnv('MEDIA_S3_BUCKET'),
+        // `auto` is what R2 expects; AWS needs its real region.
+        region: readEnv('MEDIA_S3_REGION') ?? 'auto',
+        // Omit for AWS S3 itself; set it for R2, MinIO, Spaces, B2…
+        endpoint: readEnv('MEDIA_S3_ENDPOINT'),
+        forcePathStyle: readFlag('MEDIA_S3_FORCE_PATH_STYLE', false),
+        // Absent means "use the SDK's own provider chain" — an instance role,
+        // IRSA, a shared config file. Passing blanks instead would shadow all
+        // of that with credentials that cannot sign.
+        credentials:
+            accessKeyId && secretAccessKey
+                ? { accessKeyId, secretAccessKey }
+                : undefined
+    });
+}
+// ortha:end

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

@@ -0,0 +1,67 @@
+/** Media — the storage backend, plus how downloads and uploads are bounded. */
+import type { MediaPluginConfig } from '@orthacms/media-server';
+// ortha:if media-local
+import type { LocalStorageConfig } from '@orthacms/media-provider-local';
+// ortha:end
+// ortha:if media-s3
+import type { S3StorageConfig } from '@orthacms/media-provider-s3';
+// ortha:end
+// ortha:if media-azure
+import type { AzureStorageConfig } from '@orthacms/media-provider-azure';
+// ortha:end
+// ortha:if media-gcs
+import type { GcsStorageConfig } from '@orthacms/media-provider-gcs';
+// ortha:end
+// ortha:if media-vercel-blob
+import type { VercelBlobStorageConfig } from '@orthacms/media-provider-vercel-blob';
+// ortha:end
+import { readEnv, readPositiveInt } from '@orthacms/utils-server';
+
+import { mediaStorage } from './media-storage';
+
+/**
+ * Media settings, plus whatever the storage backend `src/plugins.ts`
+ * constructs needs. The two move together: the type below is the one exported
+ * by the adapter that file imports.
+ */
+export interface AppMediaConfig extends MediaPluginConfig {
+    // ortha:if media-local
+    storage: LocalStorageConfig;
+    // ortha:end
+    // ortha:if media-s3
+    storage: S3StorageConfig;
+    // ortha:end
+    // ortha:if media-azure
+    storage: AzureStorageConfig;
+    // ortha:end
+    // ortha:if media-gcs
+    storage: GcsStorageConfig;
+    // ortha:end
+    // ortha:if media-vercel-blob
+    storage: VercelBlobStorageConfig;
+    // ortha:end
+}
+
+/** Media — the storage backend, plus how downloads and uploads are bounded. */
+export function mediaConfig(): AppMediaConfig {
+    return {
+        storage: mediaStorage(),
+        // Redirect an already-authorized download straight to the storage
+        // backend instead of streaming it through the app. Off unless asked
+        // for, and only possible on a backend that can sign a URL — the plugin
+        // refuses the combination at boot rather than proxying while the
+        // operator believes otherwise.
+        directServe:
+            readEnv('MEDIA_DIRECT_SERVE') === 'signed-url'
+                ? 'signed-url'
+                : 'off',
+        directServeTtlSeconds: readPositiveInt(
+            'MEDIA_DIRECT_SERVE_TTL_SECONDS',
+            300
+        ),
+        maxUploadBytes: readPositiveInt(
+            'MEDIA_MAX_UPLOAD_BYTES',
+            50 * 1024 * 1024
+        )
+    };
+}

package/templates/default/apps/server/config/sso-github.ts

@@ -0,0 +1,42 @@
+// ortha:if sso-github
+import type { GithubProviderConfig } from '@orthacms/identity-provider-github';
+import { defined, readEnv, readList } from '@orthacms/utils-server';
+
+/**
+ * The GitHub provider, or nothing.
+ *
+ * Present only when both values are set. The secret is not optional the way an
+ * OIDC one can be: GitHub's code exchange has no PKCE, so the secret is the
+ * only thing proving the code is being redeemed by this application — and the
+ * adapter refuses at construction rather than at the first sign-in, because
+ * every SSO failure looks the same to whoever clicked the button.
+ */
+export function githubProvider():
+    | (GithubProviderConfig & { name: string })
+    | undefined {
+    const clientId = readEnv('SSO_GITHUB_CLIENT_ID');
+    const clientSecret = readEnv('SSO_GITHUB_CLIENT_SECRET');
+    if (!clientId || !clientSecret) {
+        return undefined;
+    }
+    // `.env` ships this key blank, and `readList` answers a blank with `[]` —
+    // which is a value, not an absence, so passing it straight through would
+    // request *no* scopes and leave the profile read with nothing to read.
+    const scopes = readList('SSO_GITHUB_SCOPES', '');
+    return defined({
+        name: readEnv('SSO_GITHUB_NAME') ?? 'github',
+        clientId,
+        clientSecret,
+        label: readEnv('SSO_GITHUB_LABEL'),
+        // Defaults to `read:user user:email` — a profile and the verified
+        // addresses on it. GitHub's scopes are coarse, so anything wider hands
+        // the CMS access it has no use for.
+        scopes: scopes.length > 0 ? scopes : undefined,
+        // Only for GitHub Enterprise Server; github.com needs none.
+        enterpriseBaseUrl: readEnv('SSO_GITHUB_ENTERPRISE_BASE_URL'),
+        // Cosmetic, like Google's `hd`: it shapes the account chooser. Who
+        // actually gets in is this CMS's own decision, not GitHub's.
+        organization: readEnv('SSO_GITHUB_ORGANIZATION')
+    });
+}
+// ortha:end

package/templates/default/apps/server/config/sso-oidc.ts

@@ -0,0 +1,34 @@
+// ortha:if sso-oidc
+import type { OidcProviderConfig } from '@orthacms/identity-provider-oidc';
+import { defined, readEnv, readFlag } from '@orthacms/utils-server';
+
+/**
+ * The OIDC provider, or nothing.
+ *
+ * Present only when both values are set: an issuer with no client id becomes a
+ * sign-in button that can only fail, and every SSO failure looks the same, so
+ * whoever clicks it learns nothing.
+ */
+export function oidcProvider(): (OidcProviderConfig & { name: string }) | undefined {
+    const issuer = readEnv('SSO_OIDC_ISSUER');
+    const clientId = readEnv('SSO_OIDC_CLIENT_ID');
+    if (!issuer || !clientId) {
+        return undefined;
+    }
+    return defined({
+        name: readEnv('SSO_OIDC_NAME') ?? 'oidc',
+        issuer,
+        clientId,
+        clientSecret: readEnv('SSO_OIDC_CLIENT_SECRET'),
+        label: readEnv('SSO_OIDC_LABEL'),
+        // The only gate on a first sign-in claiming an existing account. A
+        // provider that omits the claim — Entra ID, notably — links nobody
+        // until an operator asserts that this directory owns the addresses it
+        // reports.
+        emailVerifiedWhenAbsent: readFlag(
+            'SSO_OIDC_EMAIL_VERIFIED_WHEN_ABSENT',
+            false
+        )
+    });
+}
+// ortha:end

package/templates/default/apps/server/config/sso-saml.ts

@@ -0,0 +1,46 @@
+// ortha:if sso-saml
+import type { SamlProviderConfig } from '@orthacms/identity-provider-saml';
+import { defined, readEnv, readFlag } from '@orthacms/utils-server';
+
+/**
+ * The SAML provider, or nothing.
+ *
+ * All three of the entry point, the certificate and this app's entity id are
+ * required, and there is nothing to fall back to: SAML has no discovery
+ * document and no key endpoint, so the certificate an operator copies out of
+ * their IdP is the whole of the trust relationship.
+ */
+export function samlProvider():
+    | (SamlProviderConfig & { name: string })
+    | undefined {
+    const entryPoint = readEnv('SSO_SAML_ENTRY_POINT');
+    const idpCert = readEnv('SSO_SAML_IDP_CERT');
+    const issuer = readEnv('SSO_SAML_ISSUER');
+    if (!entryPoint || !idpCert || !issuer) {
+        return undefined;
+    }
+    return defined({
+        name: readEnv('SSO_SAML_NAME') ?? 'saml',
+        entryPoint,
+        // A PEM body on one line, `\n` escapes and all: an environment
+        // variable cannot hold real newlines, so they are put back here rather
+        // than left for the XML parser to fail on.
+        idpCert: idpCert.replace(/\\n/g, '\n'),
+        issuer,
+        label: readEnv('SSO_SAML_LABEL'),
+        // Worth setting whenever the IdP's NameID format is `emailAddress`: an
+        // address is not a stable identifier, and a profile whose subject is
+        // one is refused.
+        subjectAttribute: readEnv('SSO_SAML_SUBJECT_ATTRIBUTE'),
+        emailAttribute: readEnv('SSO_SAML_EMAIL_ATTRIBUTE'),
+        nameAttribute: readEnv('SSO_SAML_NAME_ATTRIBUTE'),
+        groupsAttribute: readEnv('SSO_SAML_GROUPS_ATTRIBUTE'),
+        // Defaults to false, and stays an assertion rather than a reading:
+        // **SAML carries no verification claim at all**, so there is nothing
+        // an adapter could inspect and be honest about. Setting it says this
+        // directory is authoritative for the addresses it reports — which is
+        // the only gate on a first sign-in claiming an existing account.
+        emailVerified: readFlag('SSO_SAML_EMAIL_VERIFIED', false)
+    });
+}
+// ortha:end