sentinelayer-cli 0.30.14 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.30.14",
+  "version": "0.31.0",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/commands/mcp.js

@@ -8,6 +8,7 @@ import fs from "node:fs/promises";
 
 import {
   buildAidenIdProvisioningAdapterTemplate,
+  buildHostedSentiSessionConnectorContract,
   buildAidenIdRegistryTemplate,
   buildMcpToolRegistrySchema,
   buildMcpServerConfigTemplate,
@@ -15,10 +16,12 @@ import {
   buildVsCodeMcpBridgeTemplate,
   readJsonFile,
   resolveDefaultAidenIdAdapterContractPath,
+  resolveDefaultHostedSentiSessionConnectorContractPath,
   resolveDefaultMcpOutputPath,
   resolveDefaultMcpServerConfigPath,
   resolveDefaultVsCodeBridgePath,
   validateAidenIdAdapterContract,
+  validateHostedSentiSessionConnectorContract,
   stringifyJson,
   validateMcpServerConfig,
   validateMcpToolRegistry,
@@ -255,6 +258,46 @@ export function registerMcpCommand(program) {
       console.log(pc.gray("Next: run 'sl mcp server init --id sentinelayer-session --registry-file <path>'."));
     });
 
+  registry
+    .command("init-hosted-session-connector")
+    .description("Write the hosted Senti session MCP connector contract")
+    .option(
+      "--registry-file <path>",
+      "Local session registry file referenced by hosted connector contract",
+      ".sentinelayer/mcp/tool-registry.session-tools.json"
+    )
+    .option("--path <path>", "Destination file path override")
+    .option("--output-dir <path>", "Optional artifact output root override")
+    .option("--force", "Overwrite destination file if it already exists")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const defaultPath = await resolveDefaultHostedSentiSessionConnectorContractPath({
+        cwd: process.cwd(),
+        outputDir: options.outputDir,
+        env: process.env,
+      });
+      const outputPath = normalizeOutputPath(options.path, defaultPath);
+      const template = buildHostedSentiSessionConnectorContract({
+        localRegistryFile: options.registryFile,
+      });
+      validateHostedSentiSessionConnectorContract(template);
+      const writtenPath = await writeJsonFile(outputPath, template, { force: Boolean(options.force) });
+      const payload = {
+        command: "mcp registry init-hosted-session-connector",
+        outputPath: writtenPath,
+        localRegistryFile: template.local_registry_file,
+        toolCount: template.tools.length,
+        tools: template.tools.map((tool) => tool.tool_name),
+      };
+
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      console.log(pc.green(`Wrote hosted Senti session connector contract: ${writtenPath}`));
+      console.log(pc.gray("This is a hosted connector contract, not a local stdio runtime claim."));
+    });
+
   registry
     .command("init-cli")
     .description("Write a generated MCP registry for every SentinelLayer CLI leaf command")
@@ -335,6 +378,66 @@ export function registerMcpCommand(program) {
       }
     });
 
+  registry
+    .command("validate-hosted-session-connector")
+    .description("Validate a hosted Senti session MCP connector contract")
+    .requiredOption("--file <path>", "Hosted connector contract JSON file to validate")
+    .option("--registry-file <path>", "Optional local session registry JSON file for cross-check")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const inputPath = path.resolve(process.cwd(), String(options.file || "").trim());
+      const loaded = await readJsonFile(inputPath);
+      const registryFile = String(options.registryFile || "").trim();
+      const loadedRegistry = registryFile
+        ? await readJsonFile(path.resolve(process.cwd(), registryFile))
+        : null;
+
+      let parsed;
+      try {
+        parsed = validateHostedSentiSessionConnectorContract(loaded.data, {
+          registryPayload: loadedRegistry ? loadedRegistry.data : undefined,
+        });
+      } catch (error) {
+        const payload = {
+          command: "mcp registry validate-hosted-session-connector",
+          valid: false,
+          filePath: loaded.path,
+          registryFilePath: loadedRegistry ? loadedRegistry.path : null,
+          error: zodIssueSummary(error),
+        };
+        if (shouldEmitJson(options, command)) {
+          console.log(JSON.stringify(payload, null, 2));
+        } else {
+          console.log(pc.red(`Hosted Senti session connector contract invalid: ${payload.error}`));
+          console.log(pc.gray(`File: ${loaded.path}`));
+          if (payload.registryFilePath) {
+            console.log(pc.gray(`Registry: ${payload.registryFilePath}`));
+          }
+        }
+        process.exitCode = 2;
+        return;
+      }
+
+      const payload = {
+        command: "mcp registry validate-hosted-session-connector",
+        valid: true,
+        filePath: loaded.path,
+        registryFilePath: loadedRegistry ? loadedRegistry.path : null,
+        connector: parsed.connector,
+        toolCount: parsed.tools.length,
+        releaseGateCount: parsed.release_gates.length,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      console.log(pc.green(`Hosted Senti session connector contract valid (${parsed.tools.length} tools)`));
+      console.log(pc.gray(`File: ${loaded.path}`));
+      if (payload.registryFilePath) {
+        console.log(pc.gray(`Registry: ${payload.registryFilePath}`));
+      }
+    });
+
   registry
     .command("validate-aidenid-adapter")
     .description(

package/src/mcp/registry.js

@@ -12,6 +12,8 @@ export const MCP_TOOL_REGISTRY_SCHEMA_VERSION = "1.0.0";
 export const MCP_SERVER_CONFIG_SCHEMA_VERSION = "1.0.0";
 /** AIdenID adapter-contract schema version used by Sentinelayer CLI generated artifacts. */
 export const AIDENID_ADAPTER_CONTRACT_SCHEMA_VERSION = "1.0.0";
+/** Hosted Senti session connector-contract schema version. */
+export const HOSTED_SENTI_SESSION_CONNECTOR_CONTRACT_SCHEMA_VERSION = "1.0.0";
 
 const serverIdRegex = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/;
 const inputPlaceholderRegex = /^\{\{input\.[a-zA-Z0-9_.-]+\}\}$/;
@@ -142,6 +144,113 @@ const aidenIdAdapterContractSchema = z
   })
   .strict();
 
+const hostedSessionConnectorToolSchema = z
+  .object({
+    tool_name: z
+      .string()
+      .min(1)
+      .regex(/^[a-zA-Z0-9_.:-]+$/, "tool_name must contain only [a-zA-Z0-9_.:-]"),
+    local_tool_name: z
+      .string()
+      .min(1)
+      .regex(/^[a-zA-Z0-9_.:-]+$/, "local_tool_name must contain only [a-zA-Z0-9_.:-]"),
+    operation: z.enum([
+      "join_and_hydrate",
+      "read_history",
+      "send_message",
+      "session_action",
+      "session_lock",
+      "session_unlock",
+      "list_locks",
+      "attention_request",
+      "subscribe_wake",
+      "presence_renew",
+      "runner_teardown",
+    ]),
+    input_policy: z
+      .object({
+        identity_source: z.literal("server_session_seat"),
+        rejects_identity_from_tool_args: z.literal(true),
+        allowed_user_args: z.array(z.string().min(1)).default([]),
+        forbidden_capability_args: z
+          .array(z.enum(["sessionId", "session_id", "agentId", "agent_id", "userId", "user_id", "orgId", "org_id"]))
+          .default(["sessionId", "session_id", "agentId", "agent_id", "userId", "user_id", "orgId", "org_id"]),
+      })
+      .strict(),
+    authorization: z
+      .object({
+        requires_validated_claims: z.literal(true),
+        requires_session_seat: z.literal(true),
+        required_scopes: z.array(z.string().min(1)).min(1),
+      })
+      .strict(),
+    wake_payload: z
+      .object({
+        policy: z.enum(["none", "cursor_reason_counts_only", "bounded_redacted_window"]),
+        may_include_message_content: z.boolean().default(false),
+        max_events: z.number().int().positive().max(200).optional(),
+      })
+      .strict()
+      .superRefine((payload, ctx) => {
+        if (payload.policy === "cursor_reason_counts_only" && payload.may_include_message_content) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["may_include_message_content"],
+            message: "cursor/reason wake payloads must not include message content.",
+          });
+        }
+      }),
+    audit: z
+      .object({
+        durable_receipt_required: z.literal(true),
+        idempotency_key_fields: z.array(z.string().min(1)).min(1),
+      })
+      .strict(),
+    runner_lifecycle: z
+      .object({
+        requires_scoped_runner_token: z.literal(true),
+        revoke_token_on_idle_teardown: z.literal(true),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+const hostedSessionConnectorContractSchema = z
+  .object({
+    version: z
+      .literal(HOSTED_SENTI_SESSION_CONNECTOR_CONTRACT_SCHEMA_VERSION)
+      .default(HOSTED_SENTI_SESSION_CONNECTOR_CONTRACT_SCHEMA_VERSION),
+    provider: z.literal("sentinelayer"),
+    connector: z.literal("hosted-senti-session"),
+    generated_at: z.string().min(1),
+    local_registry_file: z.string().min(1),
+    runtime_status: z.literal("contract_only"),
+    boundary: z
+      .object({
+        transport: z.literal("https_mcp_streamable_http"),
+        identity_source: z.literal("validated_oauth_claims_and_server_session_seat"),
+        local_stdio_registry_is_not_hosted_capability: z.literal(true),
+        long_lived_cli_token_passthrough_allowed: z.literal(false),
+      })
+      .strict(),
+    tools: z.array(hostedSessionConnectorToolSchema).min(1),
+    release_gates: z.array(z.string().min(1)).min(1),
+  })
+  .strict();
+
+const REQUIRED_HOSTED_SESSION_CONNECTOR_RELEASE_GATES = [
+  "oauth_resource_binding",
+  "session_seat_ownership",
+  "deny_identity_from_tool_args",
+  "approval_policy_enforcement",
+  "scoped_runner_token_revocation",
+  "wake_payload_minimization",
+  "durable_audit_receipts",
+  "output_redaction",
+  "omar_gate_mcp_security_pack",
+];
+
 const mcpServerTransportSchema = z.discriminatedUnion("mode", [
   z
     .object({
@@ -812,6 +921,152 @@ export function buildSentinelayerSessionRegistryTemplate({ generatedAt = new Dat
   };
 }
 
+function hostedSessionTool({
+  toolName,
+  operation,
+  allowedUserArgs,
+  requiredScopes,
+  wakePayload = { policy: "none", may_include_message_content: false },
+  runnerLifecycle = null,
+}) {
+  const tool = {
+    tool_name: toolName,
+    local_tool_name: toolName,
+    operation,
+    input_policy: {
+      identity_source: "server_session_seat",
+      rejects_identity_from_tool_args: true,
+      allowed_user_args: allowedUserArgs,
+      forbidden_capability_args: ["sessionId", "session_id", "agentId", "agent_id", "userId", "user_id", "orgId", "org_id"],
+    },
+    authorization: {
+      requires_validated_claims: true,
+      requires_session_seat: true,
+      required_scopes: requiredScopes,
+    },
+    wake_payload: wakePayload,
+    audit: {
+      durable_receipt_required: true,
+      idempotency_key_fields: ["subject", "session_seat", "tool_name", "normalized_inputs"],
+    },
+  };
+  if (runnerLifecycle) {
+    tool.runner_lifecycle = runnerLifecycle;
+  }
+  return tool;
+}
+
+/**
+ * Create the hosted Senti session connector contract.
+ *
+ * This is intentionally separate from the local stdio session registry. Local
+ * tools need sessionId/agentId arguments; hosted tools must derive identity from
+ * validated OAuth claims plus a server-side session seat and must not treat those
+ * arguments as capabilities.
+ *
+ * @param {{ generatedAt?: string, localRegistryFile?: string }} [options]
+ * @returns {Record<string, any>}
+ */
+export function buildHostedSentiSessionConnectorContract({
+  generatedAt = new Date().toISOString(),
+  localRegistryFile = ".sentinelayer/mcp/tool-registry.session-tools.json",
+} = {}) {
+  return {
+    version: HOSTED_SENTI_SESSION_CONNECTOR_CONTRACT_SCHEMA_VERSION,
+    provider: "sentinelayer",
+    connector: "hosted-senti-session",
+    generated_at: generatedAt,
+    local_registry_file: String(localRegistryFile || "").trim() || ".sentinelayer/mcp/tool-registry.session-tools.json",
+    runtime_status: "contract_only",
+    boundary: {
+      transport: "https_mcp_streamable_http",
+      identity_source: "validated_oauth_claims_and_server_session_seat",
+      local_stdio_registry_is_not_hosted_capability: true,
+      long_lived_cli_token_passthrough_allowed: false,
+    },
+    tools: [
+      hostedSessionTool({
+        toolName: "poll_inbox",
+        operation: "read_history",
+        allowedUserArgs: ["cursor", "limit", "actionLimit", "includeActions"],
+        requiredScopes: ["session:read"],
+        wakePayload: { policy: "bounded_redacted_window", may_include_message_content: true, max_events: 50 },
+      }),
+      hostedSessionTool({
+        toolName: "send_message",
+        operation: "send_message",
+        allowedUserArgs: ["message", "to", "idempotencyKey"],
+        requiredScopes: ["session:write"],
+      }),
+      hostedSessionTool({
+        toolName: "session_action",
+        operation: "session_action",
+        allowedUserArgs: ["actionType", "targetSequenceId", "targetCursor", "targetActionId", "note", "idempotencyKey"],
+        requiredScopes: ["session:write", "session:action"],
+      }),
+      hostedSessionTool({
+        toolName: "session_react",
+        operation: "session_action",
+        allowedUserArgs: ["reaction", "targetSequenceId", "targetCursor", "targetActionId", "idempotencyKey"],
+        requiredScopes: ["session:write", "session:action"],
+      }),
+      hostedSessionTool({
+        toolName: "session_reply",
+        operation: "session_action",
+        allowedUserArgs: ["targetSequenceId", "targetCursor", "targetActionId", "message", "idempotencyKey"],
+        requiredScopes: ["session:write", "session:action"],
+      }),
+      hostedSessionTool({
+        toolName: "session_lock",
+        operation: "session_lock",
+        allowedUserArgs: ["files", "intent", "ttlSeconds"],
+        requiredScopes: ["session:lock"],
+      }),
+      hostedSessionTool({
+        toolName: "session_unlock",
+        operation: "session_unlock",
+        allowedUserArgs: ["files", "reason"],
+        requiredScopes: ["session:lock"],
+      }),
+      hostedSessionTool({
+        toolName: "session_locks",
+        operation: "list_locks",
+        allowedUserArgs: [],
+        requiredScopes: ["session:lock"],
+      }),
+      hostedSessionTool({
+        toolName: "attention_request",
+        operation: "attention_request",
+        allowedUserArgs: ["message", "to", "priority", "severity", "idempotencyKey"],
+        requiredScopes: ["session:write"],
+        wakePayload: { policy: "cursor_reason_counts_only", may_include_message_content: false },
+      }),
+      hostedSessionTool({
+        toolName: "subscribe_wake",
+        operation: "subscribe_wake",
+        allowedUserArgs: ["cadencePreset", "wakeTriggers", "sinceCursor"],
+        requiredScopes: ["session:read", "session:wake"],
+        wakePayload: { policy: "cursor_reason_counts_only", may_include_message_content: false },
+        runnerLifecycle: {
+          requires_scoped_runner_token: true,
+          revoke_token_on_idle_teardown: true,
+        },
+      }),
+    ],
+    release_gates: [
+      "oauth_resource_binding",
+      "session_seat_ownership",
+      "deny_identity_from_tool_args",
+      "approval_policy_enforcement",
+      "scoped_runner_token_revocation",
+      "wake_payload_minimization",
+      "durable_audit_receipts",
+      "output_redaction",
+      "omar_gate_mcp_security_pack",
+    ],
+  };
+}
+
 /**
  * Create an AIdenID adapter contract template that binds MCP tools to provisioning endpoints.
  *
@@ -975,6 +1230,68 @@ export function validateAidenIdAdapterContract(payload, { registryPayload } = {}
   return parsed;
 }
 
+/**
+ * Validate and normalize hosted Senti session connector contract payload.
+ * Optionally cross-validates hosted local_tool_name references against a local
+ * session registry payload. Contract-only hosted tools, such as subscribe_wake,
+ * can omit a local registry binding by using the same name as a non-local tool.
+ *
+ * @param {unknown} payload
+ * @param {{ registryPayload?: unknown }} [options]
+ * @returns {any}
+ */
+export function validateHostedSentiSessionConnectorContract(payload, { registryPayload } = {}) {
+  const parsed = hostedSessionConnectorContractSchema.parse(payload);
+  const releaseGateSet = new Set(parsed.release_gates);
+
+  for (const gate of REQUIRED_HOSTED_SESSION_CONNECTOR_RELEASE_GATES) {
+    if (!releaseGateSet.has(gate)) {
+      throw new Error(`Hosted connector contract is missing required release gate ${gate}.`);
+    }
+  }
+
+  for (const tool of parsed.tools) {
+    const forbidden = new Set(tool.input_policy.forbidden_capability_args);
+    for (const key of ["sessionId", "session_id", "agentId", "agent_id"]) {
+      if (!forbidden.has(key)) {
+        throw new Error(`Hosted connector tool ${tool.tool_name} must forbid capability argument ${key}.`);
+      }
+    }
+    for (const arg of tool.input_policy.allowed_user_args) {
+      if (forbidden.has(arg)) {
+        throw new Error(`Hosted connector tool ${tool.tool_name} allows forbidden capability argument ${arg}.`);
+      }
+    }
+    if (tool.operation === "subscribe_wake") {
+      if (!tool.runner_lifecycle) {
+        throw new Error(`Hosted connector tool ${tool.tool_name} must define scoped runner-token lifecycle controls.`);
+      }
+      if (!tool.runner_lifecycle.requires_scoped_runner_token) {
+        throw new Error(`Hosted connector tool ${tool.tool_name} must require a scoped runner token.`);
+      }
+      if (!tool.runner_lifecycle.revoke_token_on_idle_teardown) {
+        throw new Error(`Hosted connector tool ${tool.tool_name} must revoke runner tokens on idle teardown.`);
+      }
+    }
+  }
+
+  if (registryPayload !== undefined) {
+    const registry = validateMcpToolRegistry(registryPayload);
+    const localToolNames = new Set(registry.tools.map((tool) => tool.name));
+    const missingLocalTools = parsed.tools
+      .filter((tool) => tool.operation !== "subscribe_wake" && tool.operation !== "presence_renew" && tool.operation !== "runner_teardown")
+      .map((tool) => tool.local_tool_name)
+      .filter((toolName) => !localToolNames.has(toolName));
+    if (missingLocalTools.length > 0) {
+      throw new Error(
+        `Hosted connector references local tools not present in registry: ${[...new Set(missingLocalTools)].join(", ")}`
+      );
+    }
+  }
+
+  return parsed;
+}
+
 /**
  * Validate and normalize MCP server runtime config payload.
  *
@@ -1069,6 +1386,21 @@ export async function resolveDefaultAidenIdAdapterContractPath({ cwd, outputDir,
   return path.join(outputRoot, "mcp", "aidenid-provisioning-adapter.json");
 }
 
+/**
+ * Resolve default output path for hosted Senti session connector contracts.
+ *
+ * @param {{ cwd?: string, outputDir?: string, env?: NodeJS.ProcessEnv }} [options]
+ * @returns {Promise<string>}
+ */
+export async function resolveDefaultHostedSentiSessionConnectorContractPath({ cwd, outputDir, env } = {}) {
+  const outputRoot = await resolveOutputRoot({
+    cwd,
+    outputDirOverride: outputDir,
+    env,
+  });
+  return path.join(outputRoot, "mcp", "hosted-senti-session-connector.json");
+}
+
 /**
  * Resolve default MCP server config output path for a specific server id.
  *

package/src/review/persona-prompts.js

@@ -72,6 +72,12 @@ MCP / agent-security (clearance-layer specific):
 - Agent sandbox / microVM handed a long-lived or user credential instead of a short-lived, narrowly-scoped, per-session token; secrets injected via env or baked into a VM image/snapshot
 - Sandbox egress not default-denied, or the cloud metadata endpoint (169.254.169.254 / IMDS) reachable from guest code
 - VM memory snapshot reused across sessions or tenants (entropy/RNG/credential bleed)
+- Hosted/bridge tool execution without SERVER-SIDE approval enforcement: requires_human_approval/scopes/kill_switch trusted from client-supplied metadata or skipped, or destructive tools (auth/config/session-kill/file-write/network-scan) runnable with no approval gate (must deny-by-default when policy metadata is missing or malformed)
+- Token-like values UNREDACTED in tool output: stdout/stderr/parsed JSON/command echo/error messages returning bearer tokens, API keys, private keys, OTPs, session cookies, or local auth-store paths to the client or into stored artifacts
+- Blind unpinned @latest CLI/dependency install inside a hosted runner, not resolved to an immutable version with checksum/signature/attestation verification (supply-chain RCE into every spawned VM)
+- Notification/subscribe authorization derived from a sessionId (or other tool arg) instead of the caller's validated claims + server-side session membership (a sessionId is not a capability)
+- Wake/notification payloads exposing message content or PII outside the subscriber's authorized scope (prefer counts/cursors/reasons; redact embedded content per scope)
+- Idle teardown that kills the runner without revoking its scoped token, or session artifacts written by the guest/runner instead of by the control-plane under the owner's account
 
 Evidence standard: Every finding MUST include file:line, exploit scenario, and remediation.
 Do NOT report hypothetical issues without concrete code evidence.`,