@fourier-labs/harbour-contracts 0.44.0 → 0.45.0

package/schema/data-grant-v2.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/data-grant-v2.schema.json",
+  "title": "DataGrantV2",
+  "description": "An app's integration grant for one connection, environment and identity mode (control table sk APP#<appId>#IGRANT#<environment>#<sourceId>#<mode>; grantId = base64url(JSON [\"v2\",appId,environment,sourceId,mode])). Additive to the legacy DataGrant (data-grant.schema.json), which is never consulted by v2 paths. Expiry is enforced from UTC time on every call and SDK calls never extend it. Status edges live in x-transitions; DENIED and REVOKED are terminal (a regrant after revocation is a new REQUESTED record once cleanup is DONE). Database grants add credentialRef/mintedPrincipal, SaaS grants add installation; both hold references only.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "appId", "sourceId", "kind", "environment", "identityMode", "status", "operations", "resources", "version", "provisioning"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.data-grant/2.0" },
+    "appId": { "type": "string", "minLength": 1, "maxLength": 255 },
+    "sourceId": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
+    "kind": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationConnectionKind" },
+    "environment": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationEnvironment" },
+    "identityMode": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationIdentityMode" },
+    "status": { "$ref": "#/definitions/DataGrantV2Status" },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 3,
+      "uniqueItems": true,
+      "items": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationOperation" },
+      "description": "Approved operations; each must match this grant's identityMode."
+    },
+    "resources": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "uniqueItems": true,
+      "items": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
+      "description": "Approved logical resource names (channel aliases or view names). Never inherited by wildcard."
+    },
+    "expiresAt": { "type": "string", "format": "date-time", "description": "Absent only for explicitly approved ongoing production access." },
+    "approvedBy": { "type": "string", "minLength": 1, "maxLength": 255 },
+    "version": { "type": "integer", "minimum": 1, "description": "Optimistic-concurrency version; approvals compare it with the reviewed value." },
+    "pendingRequestId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The one open access request attached to this grant, if any." },
+    "provisioning": { "$ref": "#/definitions/DataGrantV2Provisioning" },
+    "credentialRef": {
+      "type": "string",
+      "pattern": "^secretref://[A-Za-z0-9][A-Za-z0-9/_.:-]*$",
+      "description": "Database grants: secretref://tenant/{t}/app/{a}/env/{env}/source/{s}."
+    },
+    "mintedPrincipal": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Database grants: the deterministic per tenant/app/environment/source principal." },
+    "installation": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,62}$", "description": "SaaS grants: the connection installation this environment maps to." }
+  },
+  "definitions": {
+    "DataGrantV2Status": {
+      "type": "string",
+      "enum": ["REQUESTED", "GRANTED", "DENIED", "REVOKED"],
+      "description": "Grant lifecycle state. Legal edges live in x-transitions; DENIED and REVOKED are terminal."
+    },
+    "DataGrantV2ProvisioningStatus": {
+      "type": "string",
+      "enum": ["NONE", "PENDING", "FAILED", "DONE"],
+      "description": "Provider-side work for the current approved scope (credential mint, cleanup, installation check)."
+    },
+    "DataGrantV2Provisioning": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "attempts"],
+      "properties": {
+        "status": { "$ref": "#/definitions/DataGrantV2ProvisioningStatus" },
+        "attempts": { "type": "integer", "minimum": 0, "maximum": 3, "description": "Failed attempts; three requires an admin retry." },
+        "lastError": { "type": "string", "maxLength": 500, "description": "Sanitized reason; never a provider error body." }
+      }
+    }
+  },
+  "x-status-definition": "DataGrantV2Status",
+  "x-terminal": ["DENIED", "REVOKED"],
+  "x-transitions": [
+    { "from": "REQUESTED", "to": "GRANTED", "trigger": "approval published conditionally after provisioning verified (or auto-approved within development preapproval)" },
+    { "from": "REQUESTED", "to": "DENIED", "trigger": "admin denies the request" },
+    { "from": "GRANTED", "to": "REVOKED", "trigger": "admin revokes; Isomorph access is cut first, provider cleanup follows" }
+  ],
+  "examples": [
+    {
+      "schema": "harbour.data-grant/2.0",
+      "appId": "app-1f2e3d4c",
+      "sourceId": "company-slack",
+      "kind": "saas",
+      "environment": "development",
+      "identityMode": "user",
+      "status": "GRANTED",
+      "operations": ["slack.channel.history"],
+      "resources": ["team-updates"],
+      "expiresAt": "2026-09-10T08:00:00Z",
+      "approvedBy": "policy:development-preapproval",
+      "version": 2,
+      "provisioning": { "status": "DONE", "attempts": 0 },
+      "installation": "nonprod"
+    },
+    {
+      "schema": "harbour.data-grant/2.0",
+      "appId": "app-1f2e3d4c",
+      "sourceId": "sales-warehouse",
+      "kind": "database",
+      "environment": "preview",
+      "identityMode": "app",
+      "status": "REQUESTED",
+      "operations": ["warehouse.view.read"],
+      "resources": ["weekly_sales"],
+      "expiresAt": "2026-09-16T08:00:00Z",
+      "version": 1,
+      "pendingRequestId": "req_9a8b7c6d",
+      "provisioning": { "status": "PENDING", "attempts": 1, "lastError": "credential verification timed out" }
+    }
+  ]
+}

package/schema/integration-connect-result.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/integration-connect-result.schema.json",
+  "title": "IntegrationConnectResult",
+  "description": "The `data` member of the connect (POST) and disconnect (DELETE) responses on /_harbour/integrations/connect. connected: this user's consent link for the app/environment/connection is ACTIVE (accountLabel is a display label, never an ID or token); consent_required: the user must follow authorizationUrl (governance OAuth start with an opaque ticket); disconnected: only this user's consent for this app/environment was revoked. Connect is a user action and never requests IT app approval.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["status"],
+  "properties": {
+    "status": { "type": "string", "enum": ["connected", "consent_required", "disconnected"] },
+    "accountLabel": { "type": "string", "minLength": 1, "maxLength": 255 },
+    "authorizationUrl": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048 }
+  },
+  "oneOf": [
+    { "properties": { "status": { "const": "connected" } }, "required": ["accountLabel"], "maxProperties": 2 },
+    { "properties": { "status": { "const": "consent_required" } }, "required": ["authorizationUrl"], "maxProperties": 2 },
+    { "properties": { "status": { "const": "disconnected" } }, "maxProperties": 1 }
+  ],
+  "examples": [
+    { "status": "connected", "accountLabel": "Acme Workspace (jane)" },
+    { "status": "consent_required", "authorizationUrl": "https://governance.example/v1/integrations/oauth/slack/start?ticket=opaque" },
+    { "status": "disconnected" }
+  ]
+}

package/schema/integration-error-details.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/integration-error-details.schema.json",
+  "title": "IntegrationErrorDetails",
+  "description": "The `error` member of an integration failure response `{error, requestId}` on the execute/connect routes; the SDK maps it onto HarbourError(category, message, details). `category` is the app-SDK HarbourErrorCategory (not the deployment pipeline's dot-path error-category registry), with the HTTP status fixed per category: 401 AUTH_REQUIRED, 403 FORBIDDEN (denied/revoked/expired), 404 NOT_FOUND (unknown app/connection/resource), 409 CONFLICT (pending provisioning/consent/concurrent request), 400 or 413 VALIDATION_FAILED (invalid input / size overflow), 429 RATE_LIMITED (+ Retry-After header), 503 UNAVAILABLE. `details.code` is the closed stable reason set; `message` is human-facing and never carries provider error bodies, tokens or SQL.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["category", "message", "details"],
+  "properties": {
+    "category": { "$ref": "#/definitions/IntegrationErrorCategory" },
+    "message": { "type": "string", "minLength": 1, "maxLength": 500 },
+    "details": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code"],
+      "properties": {
+        "code": { "$ref": "#/definitions/IntegrationErrorCode" },
+        "retryAfterSeconds": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 86400,
+          "description": "Mirrors the Retry-After header on RATE_LIMITED responses."
+        }
+      }
+    }
+  },
+  "definitions": {
+    "IntegrationErrorCategory": {
+      "type": "string",
+      "enum": ["AUTH_REQUIRED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "VALIDATION_FAILED", "RATE_LIMITED", "UNAVAILABLE"],
+      "description": "App-SDK HarbourErrorCategory values an integration route may emit; INTERNAL is reserved for the transport."
+    },
+    "IntegrationErrorCode": {
+      "type": "string",
+      "enum": [
+        "USER_CONNECTION_REQUIRED",
+        "USER_RECONNECT_REQUIRED",
+        "GRANT_NOT_READY",
+        "GRANT_EXPIRED",
+        "GRANT_REVOKED",
+        "CONNECTION_DISABLED",
+        "OPERATION_NOT_DECLARED",
+        "RESOURCE_NOT_APPROVED",
+        "IDENTITY_MODE_MISMATCH",
+        "SEND_OUTCOME_UNKNOWN",
+        "SEND_KEY_REUSED",
+        "PROVIDER_RATE_LIMITED",
+        "PROVIDER_UNAVAILABLE",
+        "REQUEST_TOO_LARGE",
+        "RESULT_TOO_LARGE",
+        "DEADLINE_EXCEEDED",
+        "APP_ACCESS_REQUIRED",
+        "GRANT_DENIED",
+        "TOKEN_REFRESH_PENDING",
+        "REQUEST_PENDING"
+      ],
+      "description": "Stable reason codes. SEND_OUTCOME_UNKNOWN: dispatch happened but the outcome is unknown; never re-post automatically. SEND_KEY_REUSED: the idempotency key was seen with a different payload or subject. GRANT_DENIED: IT denied the request. TOKEN_REFRESH_PENDING: another call holds the refresh lease; retry shortly. REQUEST_PENDING: a different request for this grant is still open."
+    }
+  },
+  "examples": [
+    { "category": "FORBIDDEN", "message": "Connect your Slack account to read team-updates.", "details": { "code": "USER_CONNECTION_REQUIRED" } },
+    { "category": "RATE_LIMITED", "message": "Slack is rate limiting this workspace.", "details": { "code": "PROVIDER_RATE_LIMITED", "retryAfterSeconds": 30 } }
+  ]
+}

package/schema/integration-execute-request.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/integration-execute-request.schema.json",
+  "title": "IntegrationExecuteRequest",
+  "description": "Body of POST /_harbour/integrations/execute (app SDK), forwarded unchanged to the governance development and runtime execute routes. Exactly one declared operation against one declared resource. The identity mode is NOT a caller field: it is fixed by the operation and enforced from the approved grant; any identity/userId/scope field is rejected by additionalProperties. Per-operation input bounds: slack.channel.history {limit? 1..15, default 15}; slack.message.post {text 1..4000 chars} and a required idempotencyKey retained across retries of one explicit Send; warehouse.view.read {columns 1..32, limit? 1..1000, default 100}. Transport limits (not expressible here): request <= 16 KiB, total deadline 10 s.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["connection", "operation", "resource", "input"],
+  "properties": {
+    "connection": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
+    "operation": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationOperation" },
+    "resource": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "limit": { "type": "integer", "minimum": 1, "maximum": 1000 },
+        "text": { "type": "string", "minLength": 1, "maxLength": 4000 },
+        "columns": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$" }
+        }
+      }
+    },
+    "idempotencyKey": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+      "description": "UUID of one explicit Send action; required for slack.message.post only. The same key with the same payload and subject returns the recorded outcome for seven days."
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "operation": { "const": "slack.channel.history" } } },
+      "then": {
+        "not": { "required": ["idempotencyKey"] },
+        "properties": {
+          "input": { "properties": { "limit": { "maximum": 15 } }, "not": { "anyOf": [{ "required": ["text"] }, { "required": ["columns"] }] } }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "operation": { "const": "slack.message.post" } } },
+      "then": {
+        "required": ["idempotencyKey"],
+        "properties": {
+          "input": { "required": ["text"], "not": { "anyOf": [{ "required": ["limit"] }, { "required": ["columns"] }] } }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "operation": { "const": "warehouse.view.read" } } },
+      "then": {
+        "not": { "required": ["idempotencyKey"] },
+        "properties": {
+          "input": { "required": ["columns"], "not": { "required": ["text"] } }
+        }
+      }
+    }
+  ],
+  "examples": [
+    { "connection": "company-slack", "operation": "slack.channel.history", "resource": "team-updates", "input": { "limit": 15 } },
+    {
+      "connection": "company-slack",
+      "operation": "slack.message.post",
+      "resource": "team-updates",
+      "input": { "text": "Weekly update posted." },
+      "idempotencyKey": "6f1c2c1e-3a1c-4c3e-9f0e-2b6f7d8a9c10"
+    },
+    { "connection": "sales-warehouse", "operation": "warehouse.view.read", "resource": "weekly_sales", "input": { "columns": ["week", "total"], "limit": 100 } }
+  ]
+}

package/schema/integration-execute-result.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/integration-execute-result.schema.json",
+  "title": "IntegrationExecuteResult",
+  "description": "The `data` member of a successful execute response `{data, requestId}`; the SDK unwraps `data`. Exactly one of the three operation results: slack.channel.history -> {messages, hasMore} (plain text/IDs/time only, never the provider payload); slack.message.post -> {messageId}; warehouse.view.read -> {rows} (decimal/64-bit values as strings, dates as ISO strings). An unknown send outcome is never a result; it is an error with details.code SEND_OUTCOME_UNKNOWN. Results over 1 MiB are rejected, not truncated.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "messages": {
+      "type": "array",
+      "maxItems": 15,
+      "items": { "$ref": "#/definitions/ChannelMessage" }
+    },
+    "hasMore": { "type": "boolean" },
+    "messageId": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "rows": {
+      "type": "array",
+      "maxItems": 1000,
+      "items": { "type": "object", "additionalProperties": {}, "description": "One row keyed by the requested column names." }
+    }
+  },
+  "oneOf": [
+    { "required": ["messages", "hasMore"], "maxProperties": 2 },
+    { "required": ["messageId"], "maxProperties": 1 },
+    { "required": ["rows"], "maxProperties": 1 }
+  ],
+  "definitions": {
+    "ChannelMessage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "text", "authorId", "createdAt"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "text": { "type": "string", "maxLength": 40000 },
+        "authorId": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "createdAt": { "type": "string", "format": "date-time" }
+      }
+    }
+  },
+  "examples": [
+    {
+      "messages": [{ "id": "1725840000.000100", "text": "Shipped the weekly report.", "authorId": "U0123456", "createdAt": "2026-09-09T08:00:00Z" }],
+      "hasMore": false
+    },
+    { "messageId": "1725840100.000200" },
+    { "rows": [{ "week": "2026-W36", "total": "1234.50" }] }
+  ]
+}

package/schema/kit-bundle-manifest.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/kit-bundle-manifest.schema.json",
+  "title": "KitBundleManifest",
+  "description": "Identity of one published development-kit bundle (shipped with the CLI). It pins the app SDK tarball, the local runtime images and the agent-brief fingerprint that a kit-built app was developed against, so the hosted pipeline can prove compatibility before replacing the vendored SDK (see kit-lock.schema.json).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "kitVersion", "sdk", "images", "brief", "declarationSchema"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.kit-bundle/1.0" },
+    "kitVersion": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[0-9A-Za-z.-]+)?$", "description": "The CLI package version that published this bundle." },
+    "sdk": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["package", "tarballSha256"],
+      "properties": {
+        "package": { "type": "string", "const": "@harbour/app-sdk" },
+        "tarballSha256": { "$ref": "#/definitions/HexSha256", "description": "SHA-256 of the SDK tarball baked into this bundle; the CodeBuild gate compares it with the pipeline's own tarball." }
+      }
+    },
+    "images": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["appGateway", "sessionFixture"],
+      "properties": {
+        "appGateway": { "$ref": "#/definitions/ImageDigestReference" },
+        "sessionFixture": { "$ref": "#/definitions/ImageDigestReference" }
+      }
+    },
+    "brief": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fingerprint"],
+      "properties": {
+        "fingerprint": {
+          "type": "string",
+          "pattern": "^([0-9a-f]{64}|unknown)$",
+          "description": "SHA-256 of the agent-brief tar, or the literal unknown when the bundle carried no brief."
+        }
+      }
+    },
+    "declarationSchema": { "type": "string", "const": "harbour.app-integrations/2.0" }
+  },
+  "definitions": {
+    "HexSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "ImageDigestReference": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._/-]*(:[0-9]+)?(/[a-z0-9._-]+)*@sha256:[0-9a-f]{64}$",
+      "maxLength": 512,
+      "description": "Digest-pinned image reference <repository>@sha256:<hex>; tags are never accepted."
+    }
+  },
+  "examples": [
+    {
+      "schema": "harbour.kit-bundle/1.0",
+      "kitVersion": "0.2.0",
+      "sdk": { "package": "@harbour/app-sdk", "tarballSha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" },
+      "images": {
+        "appGateway": "123456789012.dkr.ecr.us-east-1.amazonaws.com/harbour/app-gateway@sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
+        "sessionFixture": "123456789012.dkr.ecr.us-east-1.amazonaws.com/harbour/session-fixture@sha256:fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9"
+      },
+      "brief": { "fingerprint": "unknown" },
+      "declarationSchema": "harbour.app-integrations/2.0"
+    }
+  ]
+}

package/schema/kit-lock.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/kit-lock.schema.json",
+  "title": "KitLock",
+  "description": "Committed `.harbour/kit.lock.json`: which app and tenant a kit-built app belongs to and the exact bundle it was developed against. The data-plane vendorAppSDK gate reads bundle.sdk.tarballSha256 and fails with kit_bundle_incompatible (naming both digests) when it differs from the baked tarball; apps without a kit.lock keep the existing path.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "appId", "tenantId", "bundle", "createdAt", "updatedAt"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.kit-lock/1.0" },
+    "appId": { "type": "string", "pattern": "^app-[0-9a-f]{8,}$" },
+    "tenantId": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "bundle": { "$ref": "kit-bundle-manifest.schema.json" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  },
+  "examples": [
+    {
+      "schema": "harbour.kit-lock/1.0",
+      "appId": "app-1f2e3d4c",
+      "tenantId": "fourier",
+      "bundle": {
+        "schema": "harbour.kit-bundle/1.0",
+        "kitVersion": "0.2.0",
+        "sdk": { "package": "@harbour/app-sdk", "tarballSha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" },
+        "images": {
+          "appGateway": "123456789012.dkr.ecr.us-east-1.amazonaws.com/harbour/app-gateway@sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
+          "sessionFixture": "123456789012.dkr.ecr.us-east-1.amazonaws.com/harbour/session-fixture@sha256:fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9"
+        },
+        "brief": { "fingerprint": "unknown" },
+        "declarationSchema": "harbour.app-integrations/2.0"
+      },
+      "createdAt": "2026-09-09T08:00:00Z",
+      "updatedAt": "2026-09-09T08:00:00Z"
+    }
+  ]
+}

package/schema/saas-connection.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/saas-connection.schema.json",
+  "title": "SaasConnection",
+  "description": "Tenant-wide SaaS connection record (control table sk SAASCONN#<sourceId>, same tenant partition as database sources; alias uniqueness is enforced across both). IT maps each environment to a provider installation and logical channel aliases to channel IDs; apps only ever see the aliases. Contains references, never secrets: the client secret lives in Secrets Manager under clientSecretRef and installation tokens under their own token records.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sourceId", "kind", "provider", "displayName", "status", "version", "clientId", "environments", "operations", "developmentPreapproval"],
+  "properties": {
+    "sourceId": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
+    "kind": { "type": "string", "const": "saas" },
+    "provider": { "type": "string", "enum": ["slack"] },
+    "displayName": { "type": "string", "minLength": 1, "maxLength": 255 },
+    "status": { "$ref": "#/definitions/SaasConnectionStatus" },
+    "version": { "type": "integer", "minimum": 1, "description": "Optimistic-concurrency version; every write is conditional on it." },
+    "clientId": { "type": "string", "minLength": 1, "maxLength": 255 },
+    "clientSecretRef": {
+      "type": "string",
+      "pattern": "^secretref://[A-Za-z0-9][A-Za-z0-9/_.:-]*$",
+      "description": "secretref://tenant/{tenantId}/saas/{sourceId}/client"
+    },
+    "environments": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "development": { "$ref": "#/definitions/SaasEnvironmentMapping" },
+        "preview": { "$ref": "#/definitions/SaasEnvironmentMapping" },
+        "production": { "$ref": "#/definitions/SaasEnvironmentMapping" }
+      }
+    },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 2,
+      "uniqueItems": true,
+      "items": { "type": "string", "enum": ["slack.channel.history", "slack.message.post"] },
+      "description": "Operations IT allows apps to request on this connection."
+    },
+    "developmentPreapproval": { "$ref": "#/definitions/DevelopmentPreapproval" },
+    "installations": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/definitions/InstallationName" },
+      "additionalProperties": { "$ref": "#/definitions/SaasInstallation" },
+      "description": "Provider installations keyed by the installation name environments point at."
+    },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  },
+  "definitions": {
+    "SaasConnectionStatus": {
+      "type": "string",
+      "enum": ["ACTIVE", "DISABLED"],
+      "description": "DISABLED stops every app call immediately (details.code CONNECTION_DISABLED)."
+    },
+    "InstallationName": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,62}$" },
+    "SaasEnvironmentMapping": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["installation", "channels"],
+      "properties": {
+        "installation": { "$ref": "#/definitions/InstallationName" },
+        "channels": {
+          "type": "object",
+          "maxProperties": 64,
+          "propertyNames": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
+          "additionalProperties": { "type": "string", "pattern": "^[A-Z0-9]{1,32}$", "description": "Provider channel ID; only public, non-archived channels are valid." }
+        }
+      }
+    },
+    "DevelopmentPreapproval": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["enabled", "hours"],
+      "properties": {
+        "enabled": { "type": "boolean", "description": "Auto-approve development requests within the allowlist." },
+        "hours": { "type": "integer", "minimum": 1, "maximum": 168, "description": "Development grant duration; default 24." }
+      }
+    },
+    "SaasInstallation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tokenRecordId", "workspaceId", "botUserId", "status"],
+      "properties": {
+        "tokenRecordId": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "workspaceId": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "botUserId": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "status": { "type": "string", "enum": ["ACTIVE", "RECONNECT_REQUIRED", "REVOKED"] }
+      }
+    }
+  },
+  "examples": [
+    {
+      "sourceId": "company-slack",
+      "kind": "saas",
+      "provider": "slack",
+      "displayName": "Company Slack",
+      "status": "ACTIVE",
+      "version": 3,
+      "clientId": "1234567890.1234567890",
+      "clientSecretRef": "secretref://tenant/fourier/saas/company-slack/client",
+      "environments": {
+        "development": { "installation": "nonprod", "channels": { "team-updates": "C0123NONPROD" } },
+        "production": { "installation": "prod", "channels": { "team-updates": "C0123PROD" } }
+      },
+      "operations": ["slack.channel.history", "slack.message.post"],
+      "developmentPreapproval": { "enabled": true, "hours": 24 },
+      "installations": {
+        "nonprod": { "tokenRecordId": "tok_nonprod", "workspaceId": "T0NONPROD", "botUserId": "U0BOT", "status": "ACTIVE" }
+      },
+      "createdAt": "2026-09-09T08:00:00Z",
+      "updatedAt": "2026-09-09T08:00:00Z"
+    }
+  ]
+}