@veltrixsecops/app-sdk 3.2.0 → 3.5.1

package/dist/{use-app-context-OQlcmq7t.d.ts → use-app-context-Byv_fam0.d.ts}

@@ -24,6 +24,20 @@ interface AppManifest {
     database?: {
         migrations: string;
         tablePrefix: string;
+        /**
+         * How the app's tables are namespaced in Postgres.
+         *   - 'shared' (default): prefixed tables in the shared `public` schema.
+         *     Reserved for trusted first-party apps whose SQL the platform ships.
+         *   - 'schema': the app gets its own Postgres schema (+ least-privilege
+         *     role); its migrations run with search_path pinned to it.
+         *   - 'database': the app gets its own Postgres database — hard,
+         *     cross-database-query-proof isolation.
+         *   - 'external': the app owns its datastore entirely; the platform manages
+         *     no schema for it (connection supplied at runtime via app settings).
+         * The platform forces at least 'schema' for marketplace and customer-
+         * authored (self-managed) apps, which may opt up to 'database'/'external'.
+         */
+        isolation?: 'shared' | 'schema' | 'database' | 'external';
     };
     pipeline: {
         configurationTypes: AppConfigurationTypeManifest[];
@@ -61,10 +75,101 @@ interface AppManifest {
         onEnable?: string;
         onDisable?: string;
         onUpgrade?: string;
+        /** Handler the platform invokes for inbound webhooks routed to this app. */
+        onWebhook?: string;
+        /** Handler the platform invokes for inbound message-bus events routed to this app. */
+        onEvent?: string;
     };
     events?: string[];
+    /**
+     * Connection-level connectivity testing. `testHandler` is an extensionless path
+     * to a module whose default export is a `testConnection` handler — the platform
+     * runs it in-process (with the decrypted credential) to verify a Connection's
+     * endpoint + credentials. Optional: apps without it report "test not supported".
+     */
+    connectivity?: {
+        testHandler?: string;
+    };
+    /**
+     * Connection lifecycle declarations. `onboarding` opts the app into the
+     * platform's one-click connection onboarding: the app declares what it needs
+     * (a named onboarding adapter + parameters) and the platform drives it.
+     * Microsoft Entra admin-consent (`provider: 'entra-admin-consent'`) is the
+     * first adapter; nothing here is provider-specific to the platform core.
+     */
+    connection?: AppConnectionDeclaration;
     settings?: AppSettingDeclaration[];
 }
+/** App-declared connection lifecycle capabilities. */
+interface AppConnectionDeclaration {
+    onboarding?: ConnectionOnboardingDescriptor;
+}
+/**
+ * Declarative "one-click connect" descriptor. The platform reads it to render a
+ * "Connect …" button and to drive a named onboarding adapter; the app supplies
+ * only data, never platform code.
+ */
+interface ConnectionOnboardingDescriptor {
+    /** Names a platform onboarding adapter (e.g. `entra-admin-consent`). */
+    provider: string;
+    /** Button label in the Connections UI (e.g. "Connect Microsoft Defender"). */
+    label: string;
+    params?: ConnectionOnboardingParams;
+    /**
+     * Optional app-provided finalize hook (extensionless path). Run in-process
+     * after a successful onboarding, exactly like `connectivity.testHandler`.
+     */
+    onboardingHandler?: string;
+}
+interface ConnectionOnboardingParams {
+    /** App-setting key whose value selects the sovereign cloud (e.g. `azure_cloud`). */
+    cloudSetting?: string;
+    /**
+     * App permissions this connection needs — for display + audience selection.
+     * The effective grant is fixed on the connector app registration, not here.
+     */
+    requiredResourceAccess?: OnboardingRequiredResource[];
+    /** What the flow captures and where it maps back onto the connection. */
+    capture?: OnboardingCapture;
+    /** True → the connection uses the platform token broker and stores NO secret. */
+    brokered?: boolean;
+    /**
+     * App settings the admin must supply BEFORE the consent click (they cannot be
+     * derived from consent), e.g. Sentinel's subscription/resource-group/workspace.
+     */
+    requiredSettings?: string[];
+    /** Post-consent provisioning steps the adapter runs (e.g. Sentinel ARM RBAC). */
+    provisioning?: OnboardingProvisioningStep[];
+}
+interface OnboardingRequiredResource {
+    /** Well-known resource name or appId (e.g. `WindowsDefenderATP`, `Graph`). */
+    resource: string;
+    /** Application permissions requested on that resource (display only). */
+    appPermissions: string[];
+}
+interface OnboardingCapture {
+    /**
+     * Where to write the consented tenant id. `setting:<key>` writes it into the
+     * named app setting (the app libs read it as their `tenant_id`).
+     */
+    tenantId?: string;
+}
+/** A post-consent provisioning step. Only ARM role assignment exists today. */
+interface OnboardingProvisioningStep {
+    type: 'arm-role-assignment';
+    /** Well-known built-in role name (resolved to a role-definition id by the adapter). */
+    role: string;
+    /** ARM scope granularity for the assignment. */
+    scope: 'resourceGroup' | 'subscription';
+    /**
+     * How the ARM token for the assignment is obtained:
+     *   - `manual` (default): show a portal deep-link/CLI + a verify probe. No
+     *     extra platform privilege — consent does not grant ARM RBAC.
+     *   - `delegated`: opt-in second delegated-ARM leg (requires the admin to hold
+     *     Owner / User Access Administrator). Not implemented in the first cut.
+     */
+    armToken?: 'manual' | 'delegated';
+}
 /**
  * App brand identity. The platform renders it in a per-app navbar above the
  * app's pages and exposes the colors to app pages as scoped CSS variables
@@ -76,9 +181,10 @@ interface AppBrandingDeclaration {
     /** Optional secondary color as #RGB or #RRGGBB hex. */
     accentColor?: string;
     /**
-     * Vendor logo shown in the app navbar. Repo-relative .svg (preferred) or
-     * .png, at most 128 KB; rendered at 28px height, so use a wide/landscape
-     * mark with transparent background.
+     * Vendor logo shown in the app navbar and on the marketplace card. Either a
+     * repo-relative .svg (preferred) or .png at most 128 KB, OR an absolute
+     * https:// URL to an externally hosted asset. Rendered at ~28px height, so
+     * use a wide/landscape mark with a transparent background.
      */
     logo?: string;
     /** Optional logo variant for dark backgrounds; same constraints as logo. */
@@ -97,6 +203,12 @@ interface AppConfigurationTypeManifest {
         healthCheck: string;
         driftDetect?: string | null;
         getStatus: string;
+        /**
+         * Optional options provider — powers live `remote-multiselect` config fields
+         * (returns {value,label} options fetched from the target system). Loaded like
+         * driftDetect (optional); omit when the config type has no live-option fields.
+         */
+        options?: string | null;
     };
     targets: {
         componentTypes: string[];
@@ -232,6 +344,12 @@ interface InventoryItem {
     hostname: string;
     /** Management/API port, as a string (e.g. "8089"). */
     port?: string;
+    /** Optional secondary service port, e.g. a web UI (Splunk Web "8000"). */
+    webPort?: string | null;
+    /** Optional OS login user for SSH to this target (e.g. "root", "ubuntu"). */
+    sshUser?: string | null;
+    /** Optional $SPLUNK_HOME on the target (e.g. "/opt/splunk", "/opt/splunkforwarder"). */
+    splunkHome?: string | null;
     /** Component type tags (e.g. ["server"]) that classify the target. */
     type?: string[];
     /** DNS names this target is reachable at. */
@@ -258,6 +376,12 @@ interface InventoryItem {
 interface InventoryItemInput {
     hostname: string;
     port?: string;
+    /** Optional secondary service port, e.g. a web UI (Splunk Web "8000"). */
+    webPort?: string | null;
+    /** Optional OS login user for SSH to this target (e.g. "root", "ubuntu"). */
+    sshUser?: string | null;
+    /** Optional $SPLUNK_HOME on the target. */
+    splunkHome?: string | null;
     type?: string[];
     domains?: string[];
     ipRanges?: string[];
@@ -309,6 +433,8 @@ interface CredentialSummary {
     type: string | null;
     /** API base URL / endpoint this connection authenticates to, or null. */
     endpoint: string | null;
+    /** Environment type these creds apply to (from the env's types), or null = any. */
+    environmentType: string | null;
     /** The tool this credential belongs to. */
     toolId: string;
     /** True when a write-only secret (apiToken or password) is stored. */
@@ -334,6 +460,8 @@ interface CredentialInput {
     type?: string;
     /** API base URL / endpoint this connection authenticates to. Not a secret. */
     endpoint?: string;
+    /** Environment type these creds apply to (from the env's environmentTypes); null = any. */
+    environmentType?: string | null;
     /** The tool this credential belongs to. Required by the platform on create. */
     toolId?: string;
     /** IDs of existing platform tags to attach to the credential. */
@@ -416,6 +544,67 @@ interface AppHookContext {
     appId: string;
     customerId?: string;
 }
+/**
+ * Context passed to an app's `onWebhook` hook when the platform receives an
+ * inbound webhook. The platform stays ignorant of the app's semantics — the
+ * app inspects `source`/`event` and decides whether and how to act (e.g. update
+ * its own tables via `db`).
+ */
+interface AppWebhookContext {
+    db: PlatformDatabaseClient;
+    appId: string;
+    /** Origin of the webhook, e.g. 'github'. */
+    source: string;
+    /** Event name within the source, e.g. 'deployment'. */
+    event: string;
+    /** Normalized webhook payload. */
+    payload: any;
+}
+/**
+ * Context passed to an app's `onEvent` hook when the platform routes a message-
+ * bus event to it. Symmetric with `events.publish` (outbound): the app inspects
+ * `topic` and acts on its own data.
+ */
+interface AppEventContext {
+    db: PlatformDatabaseClient;
+    appId: string;
+    /** Event topic, e.g. 'deployment.status'. */
+    topic: string;
+    /** Event payload. */
+    payload: any;
+}
+/**
+ * Publish an event/message from an app to the platform's message bus. The
+ * platform routes it on a topic exchange keyed by `<appId>.<topic>`; consumers
+ * (provisioning workers, other apps) subscribe by routing key. The platform is
+ * ignorant of the payload's meaning — the app owns the message shape.
+ */
+interface AppEventPublisher {
+    publish(topic: string, payload: unknown): Promise<void>;
+}
+/**
+ * A tenant Connection (a stored {@link Credential}) resolved to its DECRYPTED
+ * secret + endpoint, returned by {@link AppRouteContext.resolveConnection}.
+ *
+ * SERVER-SIDE ONLY. The secret fields (`password` / `apiToken` / `certificate`)
+ * are in the clear — use them to reach the connected system from a route, and
+ * NEVER return them to the client or log them.
+ */
+interface ResolvedConnection {
+    id: string;
+    /** Human-readable connection label. */
+    name: string;
+    /** API base URL / management endpoint (non-secret), or null. */
+    endpoint: string | null;
+    /** Account / client id the credential authenticates as. */
+    username: string;
+    /** Decrypted password (empty string for token-only connections). */
+    password: string;
+    /** Decrypted API token, or null. */
+    apiToken: string | null;
+    /** Decrypted client certificate, or null. */
+    certificate: string | null;
+}
 /**
  * Context passed to an app's server route module (the `server.entry`
  * declared in manifest.yaml). The platform mounts the module as a Fastify
@@ -427,12 +616,25 @@ interface AppRouteContext {
     appDir: string;
     manifest: AppManifest;
     db: PlatformDatabaseClient;
+    /** Publish events/messages from this app to the platform message bus. */
+    events: AppEventPublisher;
     /**
      * Returns a Fastify preHandler enforcing an app-scoped permission.
      * Typed `any` so the SDK does not depend on Fastify's hook types —
      * pass it straight into a route's `preHandler` array.
      */
     hasPermission: (resource: string, action: string) => any;
+    /**
+     * Resolve one of the tenant's Connections (a stored Credential, by id) to its
+     * DECRYPTED secret + endpoint, so a route can reach the connected system
+     * WITHOUT re-implementing the platform's credential decryption or querying
+     * platform tables directly. Scoped to `customerId` (the tenant boundary);
+     * returns null when no matching connection exists. The decrypted secret stays
+     * server-side — never send it to the client. Pass a `credentialId` the app
+     * obtained from its own connections list (e.g. the SDK `listCredentials`
+     * helper), mirroring the platform's own "test connection" resolution.
+     */
+    resolveConnection: (customerId: string, credentialId: string) => Promise<ResolvedConnection | null>;
 }
 
 interface AppContextValue {
@@ -470,4 +672,4 @@ declare const AppContext: Context<AppContextValue | null>;
  */
 declare function useAppContext(): AppContextValue;
 
-export { APP_PAGE_LAYOUTS as A, type InventoryItemInput as B, type Component as C, type PermissionEntry as D, type PlatformDatabaseClient as E, AppContext as F, useAppContext as G, type InventoryItem as I, type PermissionCheckOptions as P, type Tag as T, type User as U, APP_PAGE_NAV as a, type AppBrandingDeclaration as b, type AppConfigurationTypeManifest as c, type AppContextValue as d, type AppDetail as e, type AppHookContext as f, type AppInstallationDetail as g, type AppInstallationStatus as h, type AppListItem as i, type AppManifest as j, type AppPageDeclaration as k, type AppPageLayout as l, type AppPageNav as m, type AppPagePermission as n, type AppPermissionDeclaration as o, type AppPermissionsApi as p, type AppRouteContext as q, type AppSettingDeclaration as r, type AppSource as s, type AppStatusType as t, type Connectivity as u, type ConnectivityProviderRef as v, type Credential as w, type CredentialInput as x, type CredentialSummary as y, type Customer as z };
+export { APP_PAGE_LAYOUTS as A, type CredentialInput as B, type Component as C, type CredentialSummary as D, type Customer as E, type InventoryItemInput as F, type PermissionEntry as G, type PlatformDatabaseClient as H, type InventoryItem as I, AppContext as J, useAppContext as K, type PermissionCheckOptions as P, type Tag as T, type User as U, APP_PAGE_NAV as a, type AppBrandingDeclaration as b, type AppConfigurationTypeManifest as c, type AppContextValue as d, type AppDetail as e, type AppEventContext as f, type AppEventPublisher as g, type AppHookContext as h, type AppInstallationDetail as i, type AppInstallationStatus as j, type AppListItem as k, type AppManifest as l, type AppPageDeclaration as m, type AppPageLayout as n, type AppPageNav as o, type AppPagePermission as p, type AppPermissionDeclaration as q, type AppPermissionsApi as r, type AppRouteContext as s, type AppSettingDeclaration as t, type AppSource as u, type AppStatusType as v, type AppWebhookContext as w, type Connectivity as x, type ConnectivityProviderRef as y, type Credential as z };

package/opentofu/README.md

@@ -0,0 +1,114 @@
+# @veltrixsecops/app-sdk — OpenTofu (generic BYOI provisioning)
+
+Tool-agnostic OpenTofu modules that every BYOI app composes to provision a fully
+Veltrix-hosted environment. **There is no per-tool HCL** — an app declares its
+shape as data (an `InfraSpec`) and the SDK renders it into these modules' tfvars.
+Any tool — a log/analytics platform, a sensor fleet, a clustered database, and so
+on — reuses the same modules.
+
+## The three layers
+
+```
+sdk/opentofu/modules/<cloud>/     ← generic HCL (this dir). Nothing tool-specific.
+sdk/src/opentofu/                 ← InfraSpec types + renderInfraVars() + validateInfraSpec()
+apps/<app>/infra/spec.ts          ← the app's InfraSpec (its ports/LB/DNS/roles as DATA)
+apps/<app>/infra/bringup/         ← the app's config management + readiness gate
+```
+
+The platform's render+apply **worker** (in the Veltrix platform repo) builds the
+base tfvars from the deploy request, merges `renderInfraVars(spec)` on top,
+`tofu apply`s the pinned module, then runs the app's `spec.bringup` entrypoint.
+
+## What the module does (and what the app supplies)
+
+| Concern | Module (generic) | App (via InfraSpec) |
+|---|---|---|
+| Compute nodes | one instance per non-foundation plan item | roles are just plan `kind`s |
+| Security groups | SG-to-SG, one rule per `(port, source)` | `securityRules[]` |
+| Front door | ALB + WAF + optional Cognito MFA + target group | `loadBalancer` (port, health path, target kinds) |
+| DNS | public ALB record + private zone + per-node FQDNs | `dnsPrefixes` (kind → label) |
+| Object storage | private S3 bucket | `storage[]` |
+| TLS | ACM public wildcard (ALB); Private-CA per node (fabric) | — |
+| Tags | every resource merges the canonical Veltrix tag set | — |
+
+Compute detection is **foundation-exclusion**: any plan item whose `kind` is not
+in `foundation_kinds` (network/storage/secrets/tls/load-balancer/dns/license-file/
+hec) is a compute node — so a new tool's roles are compute automatically.
+
+## Authoring an app's infra (example)
+
+```ts
+// apps/<app>/infra/spec.ts
+import type { InfraSpec } from '@veltrixsecops/app-sdk/opentofu';
+
+export const spec: InfraSpec = {
+  securityRules: [
+    { port: 443, sources: ['alb'], description: 'Web UI' },
+    { port: 8089, sources: ['self', 'admin'] },
+  ],
+  loadBalancer: { targetPort: 443, healthCheckPath: '/healthz', targetKinds: ['web'] },
+  dnsPrefixes: { web: 'web', sensor: 'sensor', manager: 'mgr' },
+  bringup: './bringup/run.mjs',
+};
+```
+
+Validate it in a test with `validateInfraSpec(spec)` (returns `[]` when valid).
+
+## Deployment modes — Veltrix-hosted vs BYOC
+
+The same modules deploy into Veltrix's account *or* the customer's own cloud
+account (Bring Your Own Cloud). This is controlled by two **worker-set**
+variables — they are NOT part of the app's `InfraSpec` (which describes only the
+tool), so one app spec serves both:
+
+- **`network_mode`**
+  - `shared` — Veltrix-hosted: data-source the shared VPC + the IPAM-allocated
+    per-stack subnet.
+  - `dedicated` — BYOC: **create** a fresh VPC/VNet/network + multi-AZ
+    public/private subnets + gateway + NAT in the customer's account.
+  - `existing` — BYOC: data-source a customer-designated network + create
+    subnets in it.
+- **`dns_mode`** (private intra-cluster DNS is always created in the deploy
+  account's network regardless)
+  - `managed` — module creates the public record + cert in-account (Veltrix zone
+    for hosted, customer zone for BYOC customer-owned).
+  - `delegated` — BYOC cross-account: the **worker** writes the public record +
+    cert-validation into Veltrix's zone; the module takes a pre-validated
+    `certificate_arn` and creates no public record/cert.
+  - `private-only` — no public DNS; reached via the customer's network.
+
+**Credentials/trust** are worker-level (the customer registers a least-privilege
+role/SP/SA/token per cloud via Connections; the worker configures the provider
+with it) — the module body is credential-agnostic.
+
+## Contract notes / invariants
+
+- **`plan_key` is the status-back key.** Every compute node and foundation tier
+  maps `plan_key → cloud ref` via `output "resource_refs"`; keep it 1:1.
+- **`node_fqdns` output** (`plan_key → function FQDN`) is what an app's bring-up
+  inventory consumes.
+- A `securityRules` entry using source `"alb"` requires a `loadBalancer`
+  (enforced by `validateInfraSpec`).
+- `alb_auth` (Cognito MFA) is off by default; when enabled all three
+  `userPool*` fields are required.
+- The module is **pinned + shipped in the package** (`files: ["opentofu"]`);
+  the worker resolves it by path from the installed SDK.
+
+## Status
+
+All four clouds implement the identical spec-derived variable + output contract
+and both deployment modes (`network_mode`, `dns_mode`). None is `tofu validate`-
+gated yet — no OpenTofu binary in this environment, so they were built by close
+translation of the AWS reference + manual review; **run `tofu validate` per
+module in CI before first apply.**
+
+| Cloud | Front door / WAF | SG-to-SG | Private DNS | Notable gaps (documented, no-op) |
+|---|---|---|---|---|
+| **aws** (reference) | ALB + WAFv2 + Cognito MFA | SG self-ref | Route53 private zone | — |
+| **azure** | App Gateway + WAF_v2 | NSG + ASG | Private DNS zone | MFA (→ AAD App Proxy); TLS needs a KV cert + identity (no in-module ACM); `web_ingress_cidr` not wired |
+| **gcp** | Global HTTPS LB + Cloud Armor | network tag + firewall | Cloud DNS private zone | MFA (→ IAP); no HTTP→HTTPS redirect; single-zone compute |
+| **hetzner** | hcloud LB (no WAF) | firewall (CIDR) | **none in-provider** — FQDNs emitted for the bring-up / `hetznerdns` | no WAF; no managed DNS; object store → block volume; secrets → platform vault; no MFA |
+
+Tags map to **labels** (sanitized) on GCP and Hetzner; Azure and AWS use tags
+directly. Provider-specific vars (image, sizing, zone, public-zone refs) differ
+per cloud by name; the **spec-derived** vars are identical everywhere.