@fourier-labs/harbour-contracts 0.70.0 → 0.72.0

package/gen-ts/integration-operations.ts

@@ -0,0 +1,118 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/** Declaration and execute metadata from the contract schemas. */
+export const IntegrationOperations = {
+  "slack.channel.history": {
+    "kind": "saas",
+    "identities": [
+      "user",
+      "app"
+    ],
+    "readOnly": true,
+    "declaredMode": true,
+    "idempotencyKey": false
+  },
+  "slack.message.post": {
+    "kind": "saas",
+    "identities": [
+      "app",
+      "user"
+    ],
+    "readOnly": false,
+    "declaredMode": true,
+    "idempotencyKey": true
+  },
+  "slack.message.update": {
+    "kind": "saas",
+    "identities": [
+      "app",
+      "user"
+    ],
+    "readOnly": false,
+    "declaredMode": true,
+    "idempotencyKey": false
+  },
+  "slack.message.delete": {
+    "kind": "saas",
+    "identities": [
+      "app",
+      "user"
+    ],
+    "readOnly": false,
+    "declaredMode": true,
+    "idempotencyKey": false
+  },
+  "slack.dm.send": {
+    "kind": "saas",
+    "identities": [
+      "app"
+    ],
+    "readOnly": false,
+    "declaredMode": false,
+    "idempotencyKey": true
+  },
+  "slack.user.lookup": {
+    "kind": "saas",
+    "identities": [
+      "app"
+    ],
+    "readOnly": true,
+    "declaredMode": false,
+    "idempotencyKey": false
+  },
+  "gmail.thread.list": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": true,
+    "declaredMode": false,
+    "idempotencyKey": false
+  },
+  "gmail.thread.read": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": true,
+    "declaredMode": false,
+    "idempotencyKey": false
+  },
+  "gmail.message.read": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": true,
+    "declaredMode": false,
+    "idempotencyKey": false
+  },
+  "gmail.message.send": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": false,
+    "declaredMode": false,
+    "idempotencyKey": true
+  },
+  "gmail.attachment.read": {
+    "kind": "saas",
+    "identities": [
+      "user"
+    ],
+    "readOnly": true,
+    "declaredMode": false,
+    "idempotencyKey": false
+  },
+  "warehouse.view.read": {
+    "kind": "database",
+    "identities": [
+      "app"
+    ],
+    "readOnly": true,
+    "declaredMode": false,
+    "idempotencyKey": false
+  }
+} as const;

package/gen-ts/saas-connection.ts

@@ -2,7 +2,7 @@
 // Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
 
 /**
- * Slack carries an installation and a channel map; Gmail is user-consent only and read-only.
+ * Slack carries an installation and a channel map; Gmail is user-consent only.
  */
 export type SaasProvider = 'slack' | 'gmail';
 /**
@@ -10,6 +10,18 @@ export type SaasProvider = 'slack' | 'gmail';
  */
 export type SaasConnectionStatus = 'ACTIVE' | 'DISABLED';
 export type SaasInstallationStatus = 'installed' | 'reconnect_required' | 'revoked';
+/**
+ * How a user-mode access request on this connection is approved (0.71.0): automatic — the person's own consent is the approval, since the app only ever acts as them; it — an IT admin reviews it like an app-mode request. Absent means it.
+ */
+export type UserModeApproval = 'automatic' | 'it';
+/**
+ * signed_in_person — only the person using the app; channel_members — the members of the named channel; anyone — any workspace member.
+ */
+export type DirectMessageAudience = 'signed_in_person' | 'channel_members' | 'anyone';
+/**
+ * block — every recipient must be internal (what a new Gmail connection is given; a connection stored without a policy reads as allow); allowlist — internal or in `allowedDomains`; allow — any address.
+ */
+export type ExternalRecipientMode = 'block' | 'allowlist' | 'allow';
 /**
  */
 export type InstallationName = string;
@@ -43,20 +55,30 @@ export interface SaasConnection {
     [k: string]: string;
   };
   /**
-   * Operations IT allows apps to request on this connection: the provider's own SaaS operations (Slack: slack.channel.history, slack.message.post; Gmail: gmail.thread.list, gmail.message.read, gmail.message.send). Never warehouse.view.read.
+   * Operations IT allows apps to request on this connection: the provider's own SaaS operations (Slack: slack.channel.history, slack.message.post, slack.message.update, slack.message.delete, slack.dm.send, slack.user.lookup; Gmail: gmail.thread.list, gmail.thread.read, gmail.message.read, gmail.message.send, gmail.attachment.read). Never warehouse.view.read.
    *
    * @minItems 1
-   * @maxItems 5
+   * @maxItems 11
    */
   operations: (
     | 'slack.channel.history'
     | 'slack.message.post'
+    | 'slack.message.update'
+    | 'slack.message.delete'
+    | 'slack.dm.send'
+    | 'slack.user.lookup'
     | 'gmail.thread.list'
+    | 'gmail.thread.read'
     | 'gmail.message.read'
     | 'gmail.message.send'
+    | 'gmail.attachment.read'
     | 'warehouse.view.read'
   )[];
   developmentPreapproval: DevelopmentPreapproval;
+  oauthClient?: SaasOauthClient;
+  userModeApproval?: UserModeApproval;
+  directMessages?: DirectMessagePolicy;
+  externalRecipients?: ExternalRecipientPolicy;
   /**
    * Lower-cased builder emails excluded from development preapproval.
    *
@@ -125,6 +147,48 @@ export interface DevelopmentPreapproval {
    */
   hours: number;
 }
+/**
+ * The tenant's own OAuth client for this provider (0.71.0; the ADR 0068 follow-up): when present, installation and user consent run through the company's Slack app or Google Cloud project instead of the platform-owned one, so the tenant's IT sees and controls the app in their own admin console. A reference to the secret, never the secret.
+ */
+export interface SaasOauthClient {
+  clientId: string;
+  /**
+   * Where the client secret lives.
+   */
+  secretRef: string;
+  setAt: string;
+  /**
+   * The IT admin who saved it (lower-cased email).
+   */
+  setBy: string;
+}
+/**
+ * Whom an app may direct-message through slack.dm.send (0.71.0), set by IT on the connection and enforced by governance on every send.
+ */
+export interface DirectMessagePolicy {
+  allowed: DirectMessageAudience;
+  /**
+   * Tenant-wide logical alias of a connection (governance sourceId) or of a resource under it.
+   */
+  channel?: string;
+  /**
+   * Distinct recipients one app may message per UTC day on this connection; the cap refuses the send that would exceed it.
+   */
+  dailyRecipientCap: number;
+}
+/**
+ * Whether a gmail.message.send may address people outside the company (0.71.0). An external recipient is one whose email domain is not one of the tenant's verified domains.
+ */
+export interface ExternalRecipientPolicy {
+  mode: ExternalRecipientMode;
+  /**
+   * allowlist only: the external domains a send may address; a recipient's domain must equal one of them.
+   *
+   * @minItems 1
+   * @maxItems 50
+   */
+  allowedDomains?: string[];
+}
 /**
  * @deprecated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour-contracts",
-  "version": "0.70.0",
+  "version": "0.72.0",
   "description": "Single source of truth for every data shape that crosses a boundary between Isomorph components.",
   "license": "UNLICENSED",
   "private": false,

package/schema/app-integrations-declaration.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://schemas.harbour.dev/app-integrations-declaration.schema.json",
   "title": "AppIntegrationsDeclaration",
-  "description": "Committed `.isomorph/integrations.json`: the app's declared use of tenant-wide integration connections. Keys are logical connection aliases (the governance sourceId); resources are logical names (Slack channel alias, warehouse view name), never IDs, tokens or URLs. The operation set is closed (six operations). Each operation carries a fixed identity mode — slack.channel.history=user, gmail.thread.list=user, gmail.message.read=user, gmail.message.send=user, warehouse.view.read=app — except slack.message.post, whose mode the app DECLARES: `app` posts as the company's Slack app (the one audited bot identity, under the IT-approved per-app display name when the connection declares `presentation`), `user` posts as the signed-in person after their own consent. The declared mode is the one the app requests access for; an app may hold approved grants for both modes after two requests, and each slack.message.post call names which approved mode it runs under (`mode` on the execute request, 0.55.0) — a mode IT did not approve is refused, never swapped for the other. A `saas` connection may declare only the Slack and Gmail operations and a `database` connection only warehouse.view.read; `presentation` is a `saas` connection's optional per-app display name and icon for app-mode Slack posts, shown to IT at approval time and applied only from the approved grant. Gmail is user-mode only (reads plus one send); its single resource is the fixed `inbox` alias. This file also owns the shared IntegrationOperation / IntegrationIdentityMode / IntegrationEnvironment / IntegrationConnectionKind / IntegrationPresentation definitions referenced by the other integration schemas.",
+  "description": "Committed `.isomorph/integrations.json`: the app's declared use of tenant-wide integration connections. Keys are logical connection aliases (the governance sourceId); resources are logical names (Slack channel alias, warehouse view name), never IDs, tokens or URLs. The operation set is closed (twelve operations since 0.71.0, ADR 0018). Each operation carries a fixed identity mode — slack.dm.send=app, slack.user.lookup=app, every gmail.* operation=user, warehouse.view.read=app — except the declared-mode Slack operations (slack.message.post, and since 0.71.0 slack.channel.history, slack.message.update and slack.message.delete), whose mode the app DECLARES: `app` acts as the company's Slack app (the one audited bot identity; a post goes out under the IT-approved per-app display name when the connection declares `presentation`), `user` acts as the signed-in person after their own consent (reads what they can read, edits what they wrote). The declared mode is the one the app requests access for; an app may hold approved grants for both modes after two requests, and each declared-mode call names which approved mode it runs under (`mode` on the execute request, 0.55.0) — a mode IT did not approve is refused, never swapped for the other. A `saas` connection may declare only the Slack and Gmail operations and a `database` connection only warehouse.view.read; `presentation` is a `saas` connection's optional per-app display name and icon for app-mode Slack posts, shown to IT at approval time and applied only from the approved grant. Gmail is user-mode only (reads, one send); its single resource is the fixed `inbox` alias. slack.dm.send and slack.user.lookup address people by email rather than a channel, so their single resource is the fixed `workspace` alias (the connection's installed workspace), the way Gmail's is `inbox`. This file also owns the shared IntegrationOperation / IntegrationIdentityMode / IntegrationEnvironment / IntegrationConnectionKind / IntegrationPresentation definitions referenced by the other integration schemas.",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema", "connections"],
@@ -25,13 +25,13 @@
     "IntegrationConnectionKind": { "type": "string", "enum": ["saas", "database"] },
     "IntegrationOperation": {
       "type": "string",
-      "enum": ["slack.channel.history", "slack.message.post", "gmail.thread.list", "gmail.message.read", "gmail.message.send", "warehouse.view.read"],
-      "description": "Closed operation set. Extending it is a contracts change. gmail.message.send (0.50.0) sends one plain-text email as the signed-in person: a send like slack.message.post (explicit Send, idempotencyKey, write receipt) under user identity. slack.message.post (0.53.0) runs in the mode the app declares: app (the company's Slack app, under the IT-approved per-app name) or user (the signed-in person, after their consent); since 0.55.0 each call names which of the approved modes it runs under."
+      "enum": ["slack.channel.history", "slack.message.post", "slack.message.update", "slack.message.delete", "slack.dm.send", "slack.user.lookup", "gmail.thread.list", "gmail.thread.read", "gmail.message.read", "gmail.message.send", "gmail.attachment.read", "warehouse.view.read"],
+      "description": "Closed operation set. Extending it is a contracts change. gmail.message.send (0.50.0) sends one email as the signed-in person: a send like slack.message.post (explicit Send, idempotencyKey, write receipt) under user identity; since 0.71.0 it may carry an HTML body and attachments. slack.message.post (0.53.0) runs in the mode the app declares: app (the company's Slack app, under the IT-approved per-app name) or user (the signed-in person, after their consent); since 0.55.0 each call names which of the approved modes it runs under. 0.71.0 (ADR 0018) adds slack.message.update and slack.message.delete (declared mode, like post), slack.dm.send (app mode: a direct message to 1..8 workspace members named by email), slack.user.lookup (app mode: email to Slack user id), gmail.thread.read (every message of one thread) and gmail.attachment.read (one attachment's bytes), and lets slack.channel.history run in app mode as well as user mode."
     },
     "IntegrationIdentityMode": {
       "type": "string",
       "enum": ["app", "user"],
-      "description": "Whose authority an operation runs under. Fixed per operation, except slack.message.post: declared per app for the access request, and named per call among the app's approved modes (execute request `mode`, 0.55.0)."
+      "description": "Whose authority an operation runs under. Fixed per operation, except the declared-mode Slack operations (slack.message.post; since 0.71.0 also slack.channel.history, slack.message.update, slack.message.delete): declared per app for the access request, and named per call among the app's approved modes (execute request `mode`, 0.55.0)."
     },
     "IntegrationEnvironment": {
       "type": "string",
@@ -92,12 +92,22 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["identity", "resources"],
-      "description": "slack.message.post: the app declares the mode — app (posts as the company's Slack app) or user (posts as the signed-in person).",
+      "description": "slack.message.post, slack.channel.history, slack.message.update, slack.message.delete: the app declares the mode — app (acts as the company's Slack app) or user (acts as the signed-in person).",
       "properties": {
         "identity": { "$ref": "#/definitions/IntegrationIdentityMode" },
         "resources": { "$ref": "#/definitions/ResourceNames" }
       }
     },
+    "AppModeChannelOperation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["identity", "resources"],
+      "description": "slack.dm.send, slack.user.lookup (0.71.0): app mode only — the company's Slack app messages people or resolves them by email; the resource is the fixed `workspace` alias.",
+      "properties": {
+        "identity": { "type": "string", "const": "app" },
+        "resources": { "$ref": "#/definitions/ResourceNames" }
+      }
+    },
     "AppModeViewOperation": {
       "type": "object",
       "additionalProperties": false,
@@ -125,11 +135,17 @@
           "additionalProperties": false,
           "minProperties": 1,
           "properties": {
-            "slack.channel.history": { "$ref": "#/definitions/UserModeChannelOperation" },
+            "slack.channel.history": { "$ref": "#/definitions/DeclaredModeChannelOperation" },
             "slack.message.post": { "$ref": "#/definitions/DeclaredModeChannelOperation" },
+            "slack.message.update": { "$ref": "#/definitions/DeclaredModeChannelOperation" },
+            "slack.message.delete": { "$ref": "#/definitions/DeclaredModeChannelOperation" },
+            "slack.dm.send": { "$ref": "#/definitions/AppModeChannelOperation" },
+            "slack.user.lookup": { "$ref": "#/definitions/AppModeChannelOperation" },
             "gmail.thread.list": { "$ref": "#/definitions/UserModeChannelOperation" },
+            "gmail.thread.read": { "$ref": "#/definitions/UserModeChannelOperation" },
             "gmail.message.read": { "$ref": "#/definitions/UserModeChannelOperation" },
             "gmail.message.send": { "$ref": "#/definitions/UserModeChannelOperation" },
+            "gmail.attachment.read": { "$ref": "#/definitions/UserModeChannelOperation" },
             "warehouse.view.read": { "$ref": "#/definitions/AppModeViewOperation" }
           }
         }
@@ -140,7 +156,7 @@
         "not": { "required": ["presentation"] },
         "properties": {
           "operations": {
-            "not": { "anyOf": [{ "required": ["slack.channel.history"] }, { "required": ["slack.message.post"] }, { "required": ["gmail.thread.list"] }, { "required": ["gmail.message.read"] }, { "required": ["gmail.message.send"] }] }
+            "not": { "anyOf": [{ "required": ["slack.channel.history"] }, { "required": ["slack.message.post"] }, { "required": ["slack.message.update"] }, { "required": ["slack.message.delete"] }, { "required": ["slack.dm.send"] }, { "required": ["slack.user.lookup"] }, { "required": ["gmail.thread.list"] }, { "required": ["gmail.thread.read"] }, { "required": ["gmail.message.read"] }, { "required": ["gmail.message.send"] }, { "required": ["gmail.attachment.read"] }] }
           }
         }
       }
@@ -155,15 +171,21 @@
           "presentation": { "displayName": "Lunch Vote", "iconEmoji": ":sandwich:" },
           "operations": {
             "slack.channel.history": { "identity": "user", "resources": ["team-updates"] },
-            "slack.message.post": { "identity": "app", "resources": ["team-updates"] }
+            "slack.message.post": { "identity": "app", "resources": ["team-updates"] },
+            "slack.message.update": { "identity": "app", "resources": ["team-updates"] },
+            "slack.message.delete": { "identity": "app", "resources": ["team-updates"] },
+            "slack.dm.send": { "identity": "app", "resources": ["workspace"] },
+            "slack.user.lookup": { "identity": "app", "resources": ["workspace"] }
           }
         },
         "gmail": {
           "kind": "saas",
           "operations": {
             "gmail.thread.list": { "identity": "user", "resources": ["inbox"] },
+            "gmail.thread.read": { "identity": "user", "resources": ["inbox"] },
             "gmail.message.read": { "identity": "user", "resources": ["inbox"] },
-            "gmail.message.send": { "identity": "user", "resources": ["inbox"] }
+            "gmail.message.send": { "identity": "user", "resources": ["inbox"] },
+            "gmail.attachment.read": { "identity": "user", "resources": ["inbox"] }
           }
         },
         "sales-warehouse": {

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

@@ -17,10 +17,10 @@
     "status": { "$ref": "#/definitions/DataGrantV2Status" },
     "operations": {
       "type": "array",
-      "maxItems": 5,
+      "maxItems": 11,
       "uniqueItems": true,
       "items": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationOperation" },
-      "description": "Approved operations; each must match this grant's mode. Empty until the first approval."
+      "description": "Approved operations; each must match this grant's mode. Empty until the first approval. At most the eleven SaaS operations (0.71.0); a database grant holds one."
     },
     "resources": {
       "type": "array",

package/schema/deployment-app-registration.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://contracts.harbour.dev/deployment-app-registration.schema.json",
   "title": "DeploymentAppRegistration",
-  "description": "IAM/SigV4 POST /v1/deployment/apps/register body. Governance derives tenant identity-provider configuration; no identity secrets are supplied. apiHostnames explicitly identifies API hosts among backendHostnames; runtime validates that subset. Omission preserves legacy .api. inference during the coordinated V2 auth migration.",
+  "description": "IAM/SigV4 POST /v1/internal/deployment/apps/{appId}/register (Internal API) or POST /v1/deployment/apps/register body. Governance derives tenant identity-provider configuration; no identity secrets are supplied. apiHostnames explicitly identifies API hosts among backendHostnames; runtime validates that subset. Omission preserves legacy .api. inference during the coordinated V2 auth migration.",
   "type": "object",
   "additionalProperties": false,
   "required": ["tenantId", "appId", "origin"],

package/schema/deployment-preview-retirement.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://contracts.harbour.dev/deployment-preview-retirement.schema.json",
   "title": "DeploymentPreviewRetirement",
-  "description": "IAM-protected POST /v1/deployment/apps/retire-preview request after production is LIVE and the deployment plane holds the preview retirement reservation. Disables only the registered preview version's serving routes and workload authority.",
+  "description": "IAM-protected POST /v1/internal/deployment/apps/{appId}/retire-preview (Internal API) or POST /v1/deployment/apps/retire-preview request after production is LIVE and the deployment plane holds the preview retirement reservation. Disables only the registered preview version's serving routes and workload authority.",
   "type": "object",
   "additionalProperties": false,
   "required": ["tenantId", "appId", "previewVersionId"],