@sellable/install 0.1.316 → 0.1.317

package/HERMES-SLACK-PROFILE-SCOPING.md

@@ -5,20 +5,18 @@ access.
 
 ## Default Rule
 
-For Sellable-managed customer channels, use one shared Sellable Reply Bot
-Socket Mode listener and route inbound events by exact channel id. Do not run
-multiple active Hermes profile gateways against the same `SLACK_APP_TOKEN`.
+For Sellable-managed customer channels, use one dedicated Slack app/token pair
+per active Hermes customer profile. Run native `hermes -p <profile> gateway run`
+for that profile only. Do not run multiple active Hermes profile gateways
+against the same `SLACK_APP_TOKEN`.
 
-The shared dispatcher maps `slackTeamId + channelId` to `customerSlug`,
-`workspaceId`, `hermesProfile`, and `responsePolicy`. It then invokes
-`hermes -p <profile>` with profile-local `SELLABLE_CONFIG_PATH` and
-`SELLABLE_CONFIGS_DIR`, and posts the response back to the original Slack
-channel/thread.
+The customer's Slack app is bound to the exact Slack channel id and the
+customer's profile-local Sellable MCP config. Customer profiles must not store
+or read Sellable Admin MCP credentials, admin Slack app tokens, or sibling
+profile config.
 
-Customer profiles do not store the shared raw Slack token pair; route records
-store metadata and secret references only. Use dedicated per-customer Slack
-app/token pairs only for customer-owned Slack workspaces or strict enterprise
-isolation.
+The shared dispatcher remains a fallback/research path only. Use it only when
+Sellable Admin explicitly owns one shared listener and route registry.
 
 The 2026-07-06 Hostinger POC proved the native Hermes listener for the
 `sellable-admin` profile with the existing `Sellable Reply Bot` app in
@@ -35,8 +33,9 @@ hermes --profile acme send --to slack:C0BFERDV3N0 --subject '[Hermes acme smoke]
 ```
 
 That succeeded and is useful as an internal smoke test. It does not change the
-inbound listener rule: one shared dispatcher should own Socket Mode for
-Sellable-managed channels.
+inbound listener rule: each active customer profile needs its own native Slack
+app token pair unless Sellable Admin deliberately chooses the dispatcher
+fallback.
 
 ## Which Slack Values Are Enough
 
@@ -114,17 +113,32 @@ SLACK_REQUIRE_MENTION=true
 Keep the file mode at `0600`. Do not copy raw tokens into planning docs, chat,
 or committed artifacts. Record token fingerprints only.
 
+The profile's Hermes MCP env must also include the profile-local Sellable
+config, customer workspace lock, and fail-closed guard:
+
+```yaml
+SELLABLE_CONFIG_PATH: /srv/hermes/profiles/acme/sellable/config.json
+SELLABLE_CONFIGS_DIR: /srv/hermes/profiles/acme/sellable/configs
+SELLABLE_LOCK_WORKSPACE_ID: ws_acme
+SELLABLE_REQUIRE_WORKSPACE_LOCK: "1"
+```
+
+`SELLABLE_REQUIRE_WORKSPACE_LOCK=1` means an unbound customer profile fails
+closed before making Sellable API calls instead of falling back to shared or
+admin config state. Only the `sellable-admin` profile should provision,
+inspect, or repair other profiles.
+
 For the shared dispatcher model, do not copy the shared `SLACK_BOT_TOKEN` or
 `SLACK_APP_TOKEN` into customer profile `.env` files. The dispatcher owns those
 tokens and route metadata decides the customer profile.
 
 ## Shared Dispatcher Ownership
 
-The shared Slack dispatcher and its route registry are internal Sellable Admin
-surfaces. This customer-facing installer must not create Slack apps, write
-shared listener tokens, or validate cross-customer route bundles. Sellable Admin
-owns those steps, then calls this installer only for profile-local Sellable
-runtime bootstrap inside the already-provisioned Hermes profile.
+The shared Slack dispatcher and its route registry are fallback Sellable Admin
+surfaces. This customer-facing installer must not create shared route bundles or
+write shared listener tokens. Sellable Admin owns Slack app creation and profile
+provisioning, then calls this installer for profile-local Sellable runtime
+bootstrap inside the already-provisioned Hermes profile.
 
 ## Verification
 
@@ -147,8 +161,9 @@ Expected proof:
 
 ## Current Phase 03 Status
 
-Phase 03 has proved the profile-scoped installer path, outbound Hermes send
-path, and live Slack listener for the `sellable-admin` profile. Phase 03.1 adds
-the shared dispatcher route registry as a Sellable Admin-owned onboarding
-surface so managed customer channels can be onboarded through the VPS without
-local-only browser state, manual SSH edits, or untracked processes.
+Phase 03 proved the profile-scoped installer path, outbound Hermes send path,
+and live Slack listener for the `sellable-admin` profile. Phase 03.1 now targets
+dedicated native Slack apps per customer profile, profile-local Sellable MCP
+locks, and fail-closed customer profile behavior so managed customer channels
+can be onboarded through the VPS without local-only browser state, manual SSH
+edits, or untracked processes.

package/README.md

@@ -122,11 +122,13 @@ It creates:
 /srv/hermes/profiles/acme/.env        # only when Slack token inputs are supplied
 ```
 
-Bootstrap also writes `SELLABLE_LOCK_WORKSPACE_ID=<workspace-id>` into the
-profile's Hermes MCP env. Customer profiles are therefore locked to their own
-Sellable workspace: Sellable MCP requests are forced to that workspace,
-workspace switching/creation is blocked, and workspace listings are filtered.
-Use the `sellable-admin` profile for provisioning or cross-profile inspection.
+Bootstrap also writes `SELLABLE_LOCK_WORKSPACE_ID=<workspace-id>` and
+`SELLABLE_REQUIRE_WORKSPACE_LOCK=1` into the profile's Hermes MCP env.
+Customer profiles are therefore locked to their own Sellable workspace:
+Sellable MCP requests are forced to that workspace, workspace switching/creation
+is blocked, workspace listings are filtered, and a missing lock fails closed
+instead of falling back to shared/admin config. Use the `sellable-admin` profile
+for provisioning or cross-profile inspection.
 
 See [`HERMES-SLACK-PROFILE-SCOPING.md`](./HERMES-SLACK-PROFILE-SCOPING.md) for
 the customer Slack isolation contract and Socket Mode token requirements.

package/bin/sellable-install.mjs

@@ -179,6 +179,8 @@ Options:
   --server <mode>           package, local, or hosted. Default: package
   --token <token>           Sellable API token. Also reads SELLABLE_TOKEN.
   --workspace-id <id>       Sellable workspace id. Also reads SELLABLE_WORKSPACE_ID.
+  --require-workspace-lock  For Hermes customer profiles, fail closed unless
+                            SELLABLE_LOCK_WORKSPACE_ID is present in MCP env.
   --api-url <url>           Sellable API URL. Default: ${DEFAULT_API_URL}
   --sellable-config-path <path>
                             Profile-scoped Sellable config path. Also reads SELLABLE_CONFIG_PATH.
@@ -222,7 +224,9 @@ Hermes profile bootstrap:
   exact channel id unless --slack-allowed-channels is supplied. Use
   customer-scoped Sellable credentials and customer-scoped Slack credentials for
   customer profiles; shared admin tokens are weaker isolation and should remain
-  internal-only.
+  internal-only. Bootstrap writes SELLABLE_REQUIRE_WORKSPACE_LOCK=1 whenever a
+  workspace id is supplied, so a customer profile fails closed if the workspace
+  lock is later removed or not yet provisioned.
 
 Hermes shared Slack dispatcher:
   Shared listener setup and route-registry validation are internal Sellable
@@ -3517,6 +3521,9 @@ function mcpEnvForHost(host, opts) {
   if (opts.lockWorkspaceId) {
     env.SELLABLE_LOCK_WORKSPACE_ID = opts.lockWorkspaceId;
   }
+  if (opts.requireWorkspaceLock) {
+    env.SELLABLE_REQUIRE_WORKSPACE_LOCK = "1";
+  }
   return env;
 }
 
@@ -3815,6 +3822,7 @@ function parseHermesProfileBootstrapArgs(argv) {
     force: false,
     overwriteEnv: false,
     allowDuplicateSlackTokens: false,
+    requireWorkspaceLock: false,
     verbose: false,
   };
 
@@ -3853,7 +3861,9 @@ function parseHermesProfileBootstrapArgs(argv) {
     else if (arg === "--json") opts.json = true;
     else if (arg === "--force") opts.force = true;
     else if (arg === "--overwrite-env") opts.overwriteEnv = true;
-    else if (arg === "--allow-duplicate-slack-tokens") {
+    else if (arg === "--require-workspace-lock") {
+      opts.requireWorkspaceLock = true;
+    } else if (arg === "--allow-duplicate-slack-tokens") {
       opts.allowDuplicateSlackTokens = true;
     } else if (arg === "--verbose") opts.verbose = true;
     else {
@@ -4111,6 +4121,8 @@ function runHermesProfileBootstrap(argv) {
     const slackEnvKeys = Object.entries(slackEnv)
       .filter(([, value]) => value)
       .map(([key]) => key);
+    const requireWorkspaceLock =
+      parsed.requireWorkspaceLock || Boolean(parsed.workspaceId);
     const opts = {
       ...parsed,
       host: "hermes",
@@ -4121,6 +4133,7 @@ function runHermesProfileBootstrap(argv) {
       tokenSource,
       workspaceId: parsed.workspaceId,
       lockWorkspaceId: parsed.workspaceId,
+      requireWorkspaceLock,
       apiUrl: parsed.apiUrl,
     };
 
@@ -4146,8 +4159,16 @@ function runHermesProfileBootstrap(argv) {
         activeWorkspaceId: parsed.workspaceId || null,
         activeWorkspaceName: parsed.workspaceName || null,
         workspaceLock: parsed.workspaceId
-          ? { enabled: true, workspaceId: parsed.workspaceId }
-          : { enabled: false, workspaceId: null },
+          ? {
+              enabled: true,
+              workspaceId: parsed.workspaceId,
+              required: requireWorkspaceLock,
+            }
+          : {
+              enabled: false,
+              workspaceId: null,
+              required: requireWorkspaceLock,
+            },
         tokenPresent: Boolean(token),
         tokenSource,
         tokenFingerprint: tokenFingerprint(token),
@@ -4319,6 +4340,11 @@ function runHermesProfileBootstrap(argv) {
         `Manual auth pending. Run: sellable auth set <token> --workspace-id <workspace_id> --sellable-config-path ${sellableConfigPath}`
       );
     }
+    if (requireWorkspaceLock && !parsed.workspaceId) {
+      summary.warnings.push(
+        "Sellable MCP will fail closed until sellable-admin provisions SELLABLE_LOCK_WORKSPACE_ID for this customer profile."
+      );
+    }
 
     if (opts.json) {
       console.log(JSON.stringify(summary, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/install",
-  "version": "0.1.316",
+  "version": "0.1.317",
   "type": "module",
   "description": "One-command installer for Sellable MCP in Claude Code, Codex, and Hermes",
   "bin": {