@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/policy/allow-write.d.ts

@@ -0,0 +1,37 @@
+import type { RootConfiguration } from "../config/types";
+import type { OperationId } from "./operations";
+/**
+ * Per-environment write gate. Throws `INPUT_INVALID` unless the
+ * environment is configured to allow writes (via `allowWrite` in
+ * `sitecoreai.cli.json`, an `SITECOREAI_ENV_<NAME>_ALLOW_WRITE=true`
+ * env var, or the per-invocation `override` boolean — typically the
+ * caller's `--allow-write` flag).
+ *
+ * Used by hygiene cleanups, workflow mutations, and any other
+ * caller-of-record for tenant-side writes. Same gate, one source of
+ * truth — see `feedback_destructive_ops_need_consent` for the broader
+ * consent model these commands sit inside.
+ *
+ * MCP note: when an MCP write tool is invoked, the registry dispatch
+ * has already cleared the host's write-confirmation UX, so the MCP
+ * layer auto-elevates `allowWrite: true` before calling runners. That
+ * means *this* gate is effectively a no-op for MCP callers — the
+ * library can't tell elevation apart from a direct `--allow-write`.
+ * `ensureMcpElevationAllowed` is the companion gate enforced at the
+ * MCP tool boundary; together they let an env opt out of MCP-driven
+ * writes via `denyMcpElevation` without changing CLI behaviour.
+ */
+export declare const ensureAllowWrite: (root: RootConfiguration, envName: string, override?: boolean, operation?: OperationId) => void;
+/**
+ * MCP boundary gate. Throws `AUTH_DENIED` when the target environment
+ * has opted out of MCP-elevated writes via `denyMcpElevation: true`.
+ * Call this from every MCP write tool's handler (auth: "write") before
+ * delegating to a destructive runner — `ensureAllowWrite` alone can't
+ * see the elevation origin once it's been folded into `options.allowWrite`.
+ *
+ * The intent is per-environment risk control: a sandbox env keeps the
+ * default (MCP elevation allowed); a production-shaped env can set
+ * `denyMcpElevation: true` to require every destructive op originate
+ * from a human CLI invocation. The flag doesn't affect direct CLI use.
+ */
+export declare const ensureMcpElevationAllowed: (root: RootConfiguration, envName: string) => void;

package/dist/policy/allow-write.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureMcpElevationAllowed = exports.ensureAllowWrite = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("../shared/errors");
+const authorize_1 = require("./authorize");
+const operations_1 = require("./operations");
+/**
+ * Per-environment write gate. Throws `INPUT_INVALID` unless the
+ * environment is configured to allow writes (via `allowWrite` in
+ * `sitecoreai.cli.json`, an `SITECOREAI_ENV_<NAME>_ALLOW_WRITE=true`
+ * env var, or the per-invocation `override` boolean — typically the
+ * caller's `--allow-write` flag).
+ *
+ * Used by hygiene cleanups, workflow mutations, and any other
+ * caller-of-record for tenant-side writes. Same gate, one source of
+ * truth — see `feedback_destructive_ops_need_consent` for the broader
+ * consent model these commands sit inside.
+ *
+ * MCP note: when an MCP write tool is invoked, the registry dispatch
+ * has already cleared the host's write-confirmation UX, so the MCP
+ * layer auto-elevates `allowWrite: true` before calling runners. That
+ * means *this* gate is effectively a no-op for MCP callers — the
+ * library can't tell elevation apart from a direct `--allow-write`.
+ * `ensureMcpElevationAllowed` is the companion gate enforced at the
+ * MCP tool boundary; together they let an env opt out of MCP-driven
+ * writes via `denyMcpElevation` without changing CLI behaviour.
+ */
+const ensureAllowWrite = (root, envName, override, operation) => {
+    const env = root.environments[envName];
+    // Workspace-policy gate — environment ceiling + caller context, at the
+    // risk tier the operation registry assigns (`write` by default,
+    // `destructive` for a registered destructive operation). Runs
+    // unconditionally: `--allow-write` (override) bypasses the config
+    // `allowWrite` requirement below but never the policy. A no-op in
+    // unmanaged mode. See docs/policy-and-guardrails.md.
+    (0, authorize_1.authorizeOperation)({
+        envName,
+        configRootDir: root.physicalPath ? node_path_1.default.dirname(root.physicalPath) : undefined,
+        tier: operation ? (0, operations_1.riskTierForOperation)(operation) : "write",
+        tokenLastUpdated: env?.deployTokenLastUpdated ?? undefined,
+    });
+    if (override || env?.allowWrite)
+        return;
+    const envKey = envName
+        .trim()
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    throw (0, errors_1.createScaiError)(`Environment ${envName} is not configured to allow writing data.`, "INPUT_INVALID", {
+        hint: `Set allowWrite in sitecoreai.cli.json, set SITECOREAI_ENV_${envKey}_ALLOW_WRITE=true, or pass --allow-write.`,
+    });
+};
+exports.ensureAllowWrite = ensureAllowWrite;
+/**
+ * MCP boundary gate. Throws `AUTH_DENIED` when the target environment
+ * has opted out of MCP-elevated writes via `denyMcpElevation: true`.
+ * Call this from every MCP write tool's handler (auth: "write") before
+ * delegating to a destructive runner — `ensureAllowWrite` alone can't
+ * see the elevation origin once it's been folded into `options.allowWrite`.
+ *
+ * The intent is per-environment risk control: a sandbox env keeps the
+ * default (MCP elevation allowed); a production-shaped env can set
+ * `denyMcpElevation: true` to require every destructive op originate
+ * from a human CLI invocation. The flag doesn't affect direct CLI use.
+ */
+const ensureMcpElevationAllowed = (root, envName) => {
+    const env = root.environments?.[envName];
+    if (env?.denyMcpElevation !== true)
+        return;
+    throw (0, errors_1.createScaiError)(`Environment ${envName} has denyMcpElevation set; MCP write tools cannot mutate this tenant.`, "AUTH_DENIED", {
+        hint: "Run the destructive command via the CLI with --allow-write, or set denyMcpElevation: false in sitecoreai.cli.json if MCP-driven writes are acceptable here.",
+    });
+};
+exports.ensureMcpElevationAllowed = ensureMcpElevationAllowed;

package/dist/policy/authorize.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tier-aware operation gate — Phase 2 of the workspace policy.
+ *
+ * `enforceEnvironmentPolicy` (Phase 1) answers "may scai touch this
+ * environment at all". `authorizeOperation` answers the Phase 2
+ * question: "may *this caller* perform a *write* / *destructive* /
+ * *mint* operation here". See docs/policy-and-guardrails.md.
+ */
+import { type CallerContext } from "./caller";
+import { type RiskTier } from "./types";
+export interface AuthorizeOperationParams {
+    envName: string;
+    /**
+     * Directory holding the resolved `sitecoreai.cli.json`. Optional —
+     * when absent, the repo-policy narrowing layer is skipped (the
+     * user-global policy still applies).
+     */
+    configRootDir?: string;
+    /** Risk tier of the operation being attempted. */
+    tier: RiskTier;
+    /** Override the detected caller context — for tests. */
+    caller?: CallerContext;
+    /**
+     * ISO timestamp the deploy token was last minted (`deployTokenLastUpdated`
+     * on the env profile). Drives the Phase 3 step-up freshness check on
+     * `destructive` / `mint` operations; ignored when the policy sets no
+     * step-up window.
+     */
+    tokenLastUpdated?: string;
+}
+/**
+ * Throws `POLICY_DENIED` when the workspace policy does not permit the
+ * current caller to run a `tier` operation against `envName`. A no-op
+ * for the `read` tier and in unmanaged mode (no `~/.sitecoreai/policy.json`).
+ */
+export declare const authorizeOperation: (params: AuthorizeOperationParams) => void;

package/dist/policy/authorize.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Tier-aware operation gate — Phase 2 of the workspace policy.
+ *
+ * `enforceEnvironmentPolicy` (Phase 1) answers "may scai touch this
+ * environment at all". `authorizeOperation` answers the Phase 2
+ * question: "may *this caller* perform a *write* / *destructive* /
+ * *mint* operation here". See docs/policy-and-guardrails.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authorizeOperation = void 0;
+const errors_1 = require("../shared/errors");
+const caller_1 = require("./caller");
+const resolve_1 = require("./resolve");
+const types_1 = require("./types");
+/**
+ * Phase 3 step-up: when the environment policy sets a `stepUpMinutes`
+ * window, a `destructive` / `mint` operation requires the deploy token to
+ * have been minted within it. Pre-flight only — scai commands are
+ * one-shot, so this cannot pause and resume; it refuses and tells the
+ * operator to re-login.
+ */
+const assertFreshAuth = (envName, stepUpMinutes, tokenLastUpdated) => {
+    if (stepUpMinutes === undefined) {
+        return;
+    }
+    const mintedAtMs = tokenLastUpdated ? Date.parse(tokenLastUpdated) : Number.NaN;
+    const fresh = Number.isFinite(mintedAtMs) && Date.now() - mintedAtMs <= stepUpMinutes * 60000;
+    if (!fresh) {
+        throw (0, errors_1.createScaiError)(`Environment '${envName}' requires a deploy token authenticated within the last ${stepUpMinutes} minutes for this operation.`, "POLICY_DENIED", { hint: `Re-run 'scai setup login -n ${envName}' and retry.` });
+    }
+};
+/**
+ * Throws `POLICY_DENIED` when the workspace policy does not permit the
+ * current caller to run a `tier` operation against `envName`. A no-op
+ * for the `read` tier and in unmanaged mode (no `~/.sitecoreai/policy.json`).
+ */
+const authorizeOperation = (params) => {
+    const { envName, configRootDir, tier } = params;
+    if (tier === "read") {
+        return;
+    }
+    const effective = (0, resolve_1.resolveEffectivePolicy)(envName, configRootDir);
+    if (!effective.managed) {
+        return;
+    }
+    if (!effective.enrolled) {
+        // Phase 1's enforceEnvironmentPolicy already denies a non-enrolled
+        // environment before this point; this is a defensive backstop.
+        throw (0, errors_1.createScaiError)(`Environment '${envName}' is not in the scai workspace policy allowlist.`, "POLICY_DENIED", {
+            hint: `Enroll it with 'scai policy allow ${envName}'.`,
+            remediation: {
+                actor: "agent",
+                fix: `scai policy allow ${envName}`,
+                detail: "Enrolls the environment in the workspace-policy allowlist.",
+            },
+        });
+    }
+    const caller = params.caller ?? (0, caller_1.resolveCallerContext)();
+    if (tier === "mint") {
+        if (!effective.mintCredentials) {
+            throw (0, errors_1.createScaiError)(`The workspace policy does not permit minting automation clients for '${envName}'.`, "POLICY_DENIED", {
+                hint: `An operator can enable it with 'scai policy set ${envName} --mint on'.`,
+                remediation: {
+                    actor: "agent",
+                    fix: `scai policy set ${envName} --mint on`,
+                    detail: "Grants this environment mint eligibility in the workspace policy.",
+                },
+            });
+        }
+        if (caller.kind !== "interactive-human") {
+            throw (0, errors_1.createScaiError)(`Minting an automation client for '${envName}' requires an interactive human operator — the caller is '${caller.kind}'.`, "POLICY_DENIED", {
+                hint: "Run 'scai setup client create' yourself in a terminal. Agents, CI, and unattended processes cannot mint credentials.",
+                remediation: {
+                    actor: "needs-human-terminal",
+                    fix: `scai setup client create ${envName}`,
+                    detail: "Credential minting requires an interactive human terminal; agents and CI callers are refused.",
+                },
+            });
+        }
+        assertFreshAuth(envName, effective.stepUpMinutes, params.tokenLastUpdated);
+        return;
+    }
+    // write / destructive — ceiling check first.
+    if ((0, types_1.riskRank)(tier) > (0, types_1.riskRank)(effective.ceiling)) {
+        throw (0, errors_1.createScaiError)(`Environment '${envName}' is capped at the '${effective.ceiling}' tier by the workspace policy; a '${tier}' operation is not allowed.`, "POLICY_DENIED", {
+            hint: `An operator can raise the ceiling with 'scai policy set ${envName} --ceiling ${tier}'.`,
+        });
+    }
+    if (caller.kind === "ci" && !effective.ciWrites) {
+        throw (0, errors_1.createScaiError)(`CI '${tier}' operations on '${envName}' are not enabled in the workspace policy.`, "POLICY_DENIED", { hint: `An operator can enable them with 'scai policy set ${envName} --ci-writes on'.` });
+    }
+    if (tier === "destructive" && (caller.kind === "m2m" || caller.kind === "mcp")) {
+        throw (0, errors_1.createScaiError)(`A '${caller.kind}' caller cannot run destructive operations on '${envName}'.`, "POLICY_DENIED", {
+            hint: "Destructive operations require an interactive human operator, or a CI pipeline with ci-writes enabled.",
+        });
+    }
+    if (tier === "destructive") {
+        assertFreshAuth(envName, effective.stepUpMinutes, params.tokenLastUpdated);
+    }
+};
+exports.authorizeOperation = authorizeOperation;

package/dist/policy/caller.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Caller context — who is invoking scai *right now*.
+ *
+ * Phase 2 gates operations on this rather than on stored token
+ * provenance: a token is acquired once and reused for weeks, so its
+ * birth ("a human logged in") says nothing about the current caller
+ * ("an unattended cron is replaying it"). Caller context is computed
+ * fresh, per invocation, from the process environment.
+ *
+ * See docs/policy-and-guardrails.md (Phase 2).
+ */
+/** Who is invoking scai. */
+export type CallerKind = "interactive-human" | "ci" | "m2m" | "mcp";
+export interface CallerContext {
+    kind: CallerKind;
+    /** CI pipeline identifier, when one can be resolved from the environment. */
+    pipelineId?: string;
+}
+/**
+ * Resolve the current caller context. First match wins, in order:
+ * `mcp` → `ci` → `interactive-human` → `m2m`.
+ */
+export declare const resolveCallerContext: () => CallerContext;

package/dist/policy/caller.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Caller context — who is invoking scai *right now*.
+ *
+ * Phase 2 gates operations on this rather than on stored token
+ * provenance: a token is acquired once and reused for weeks, so its
+ * birth ("a human logged in") says nothing about the current caller
+ * ("an unattended cron is replaying it"). Caller context is computed
+ * fresh, per invocation, from the process environment.
+ *
+ * See docs/policy-and-guardrails.md (Phase 2).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCallerContext = void 0;
+/** Env vars that, if set, mean "running inside CI". */
+const CI_MARKERS = [
+    "CI",
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "CIRCLECI",
+    "TRAVIS",
+    "BUILDKITE",
+    "JENKINS_URL",
+    "TEAMCITY_VERSION",
+    "TF_BUILD",
+];
+/** Per-provider env vars carrying a stable pipeline / run identifier. */
+const PIPELINE_ID_VARS = [
+    "GITHUB_RUN_ID",
+    "CI_PIPELINE_ID",
+    "CIRCLE_WORKFLOW_ID",
+    "BUILDKITE_BUILD_ID",
+    "BUILD_BUILDID",
+    "TRAVIS_BUILD_ID",
+];
+const isSet = (key) => {
+    const value = process.env[key];
+    return value !== undefined && value.trim() !== "";
+};
+const resolvePipelineId = () => {
+    for (const key of PIPELINE_ID_VARS) {
+        const value = process.env[key]?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return undefined;
+};
+/**
+ * Resolve the current caller context. First match wins, in order:
+ * `mcp` → `ci` → `interactive-human` → `m2m`.
+ */
+const resolveCallerContext = () => {
+    if (isSet("SITECOREAI_MCP_SERVE")) {
+        return { kind: "mcp" };
+    }
+    if (CI_MARKERS.some(isSet)) {
+        const pipelineId = resolvePipelineId();
+        return pipelineId ? { kind: "ci", pipelineId } : { kind: "ci" };
+    }
+    const interactive = Boolean(process.stdin.isTTY) &&
+        Boolean(process.stdout.isTTY) &&
+        process.env.SITECOREAI_NON_INTERACTIVE !== "1";
+    return { kind: interactive ? "interactive-human" : "m2m" };
+};
+exports.resolveCallerContext = resolveCallerContext;

package/dist/policy/enforce.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The deny-by-default environment gate.
+ *
+ * Called from inside `resolveEnvironment` (`src/shared/env.ts`) — the one
+ * resolver every surface (CLI, SDK, MCP) routes through — so no call site
+ * can miss it.
+ */
+import type { EnvironmentConfiguration } from "../config/types";
+export interface EnforceEnvironmentPolicyParams {
+    envName: string;
+    environment: EnvironmentConfiguration;
+    /** Directory holding the resolved `sitecoreai.cli.json`. */
+    configRootDir: string;
+}
+/**
+ * Throws `POLICY_DENIED` when the environment is not on the workspace-
+ * policy allowlist, or when its tenant identity has drifted from what was
+ * pinned at enrollment.
+ *
+ * A no-op in "unmanaged mode" (no `~/.sitecoreai/policy.json`), so a
+ * setup that predates this feature is never locked out — the policy file
+ * appears, and enforcement switches on, the next time the operator runs
+ * `scai setup login`, `scai mcp serve`, or `scai policy init`.
+ */
+export declare const enforceEnvironmentPolicy: (params: EnforceEnvironmentPolicyParams) => void;

package/dist/policy/enforce.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * The deny-by-default environment gate.
+ *
+ * Called from inside `resolveEnvironment` (`src/shared/env.ts`) — the one
+ * resolver every surface (CLI, SDK, MCP) routes through — so no call site
+ * can miss it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enforceEnvironmentPolicy = void 0;
+const errors_1 = require("../shared/errors");
+const identity_1 = require("./identity");
+const resolve_1 = require("./resolve");
+/**
+ * Throws `POLICY_DENIED` when the environment is not on the workspace-
+ * policy allowlist, or when its tenant identity has drifted from what was
+ * pinned at enrollment.
+ *
+ * A no-op in "unmanaged mode" (no `~/.sitecoreai/policy.json`), so a
+ * setup that predates this feature is never locked out — the policy file
+ * appears, and enforcement switches on, the next time the operator runs
+ * `scai setup login`, `scai mcp serve`, or `scai policy init`.
+ */
+const enforceEnvironmentPolicy = (params) => {
+    const { envName, environment, configRootDir } = params;
+    const effective = (0, resolve_1.resolveEffectivePolicy)(envName, configRootDir);
+    if (!effective.managed) {
+        return;
+    }
+    if (!effective.enrolled) {
+        throw (0, errors_1.createScaiError)(`Environment '${envName}' is not in the scai workspace policy allowlist.`, "POLICY_DENIED", {
+            hint: `Enroll it with 'scai policy allow ${envName}', or run ` +
+                `'scai policy show' to see which environments are allowed.`,
+            remediation: {
+                actor: "agent",
+                fix: `scai policy allow ${envName}`,
+                detail: "Enrolls the environment in the workspace-policy allowlist.",
+            },
+        });
+    }
+    if (effective.identity) {
+        const drift = (0, identity_1.describeIdentityDrift)(effective.identity, (0, identity_1.extractIdentity)(environment));
+        if (drift.length > 0) {
+            throw (0, errors_1.createScaiError)(`Environment '${envName}' identity has changed since it was enrolled in the workspace policy.`, "POLICY_DENIED", {
+                details: drift,
+                hint: `If this change is expected, re-pin it with 'scai policy trust ${envName}'. ` +
+                    `If not, your sitecoreai.cli.json may have been tampered with.`,
+                remediation: {
+                    actor: "agent",
+                    fix: `scai policy trust ${envName}`,
+                    detail: "Re-pins the tenant identity to the current config — only if the change is expected.",
+                },
+            });
+        }
+    }
+};
+exports.enforceEnvironmentPolicy = enforceEnvironmentPolicy;

package/dist/policy/enroll.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Auto-populate the workspace policy. The operator never hand-edits
+ * `policy.json`; it is created and maintained here, from `scai setup
+ * login`, `scai mcp serve`, and the `scai policy` commands.
+ */
+import type { EnvironmentConfiguration } from "../config/types";
+import type { EnrollSource, RiskTier } from "./types";
+export interface EnrollEnvironmentParams {
+    envName: string;
+    environment: EnvironmentConfiguration;
+    via: EnrollSource;
+    /** Ceiling for a newly-enrolled environment. Defaults to `write`. */
+    ceiling?: RiskTier;
+}
+export interface EnrollResult {
+    /** True when this call created the policy file (first-ever enrollment). */
+    created: boolean;
+    /** True when the environment was already enrolled before this call. */
+    alreadyEnrolled: boolean;
+    /** False when no policy directory is resolvable, so nothing was written. */
+    written: boolean;
+}
+/**
+ * Idempotently enroll an environment into the user-global workspace
+ * policy. Creates the policy file on first use. Re-enrolling an existing
+ * environment refreshes its pinned identity and `enrolledAt` but keeps
+ * its original ceiling and `enrolledVia` — re-running login must not
+ * silently widen a ceiling the operator narrowed.
+ *
+ * Never throws on a missing policy directory (Vitest without
+ * `SITECOREAI_POLICY_HOME`) — it returns `written: false` instead, so
+ * callers in the login / serve paths stay simple.
+ */
+export declare const enrollEnvironment: (params: EnrollEnvironmentParams) => EnrollResult;
+/**
+ * Re-pin an already-enrolled environment's identity to whatever the
+ * config currently says — the `scai policy trust` path, used after a
+ * legitimate tenant change. Returns `false` if the environment is not
+ * enrolled or nothing could be written.
+ */
+export declare const repinEnvironment: (envName: string, environment: EnvironmentConfiguration) => boolean;
+/** Remove an environment from the allowlist. Returns `false` if absent. */
+export declare const unenrollEnvironment: (envName: string) => boolean;
+/** Policy flags an operator may tune on an enrolled environment. */
+export interface EnvironmentFlags {
+    ceiling?: RiskTier;
+    mintCredentials?: boolean;
+    ciWrites?: boolean;
+    /** Step-up window in minutes; `null` clears it (no requirement). */
+    stepUpMinutes?: number | null;
+}
+/**
+ * Explicitly update an enrolled environment's Phase 2 policy flags — the
+ * `scai policy set` path. Only the fields provided are changed. Returns
+ * `false` if the environment is not enrolled or nothing could be written.
+ */
+export declare const setEnvironmentFlags: (envName: string, flags: EnvironmentFlags) => boolean;

package/dist/policy/enroll.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * Auto-populate the workspace policy. The operator never hand-edits
+ * `policy.json`; it is created and maintained here, from `scai setup
+ * login`, `scai mcp serve`, and the `scai policy` commands.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setEnvironmentFlags = exports.unenrollEnvironment = exports.repinEnvironment = exports.enrollEnvironment = void 0;
+const identity_1 = require("./identity");
+const store_1 = require("./store");
+/**
+ * Idempotently enroll an environment into the user-global workspace
+ * policy. Creates the policy file on first use. Re-enrolling an existing
+ * environment refreshes its pinned identity and `enrolledAt` but keeps
+ * its original ceiling and `enrolledVia` — re-running login must not
+ * silently widen a ceiling the operator narrowed.
+ *
+ * Never throws on a missing policy directory (Vitest without
+ * `SITECOREAI_POLICY_HOME`) — it returns `written: false` instead, so
+ * callers in the login / serve paths stay simple.
+ */
+const enrollEnvironment = (params) => {
+    const existing = (0, store_1.readWorkspacePolicy)();
+    const policy = existing ?? { version: 1, environments: {} };
+    const prior = policy.environments[params.envName];
+    const entry = {
+        identity: (0, identity_1.extractIdentity)(params.environment),
+        ceiling: prior?.ceiling ?? params.ceiling ?? "write",
+        enrolledAt: new Date().toISOString(),
+        enrolledVia: prior?.enrolledVia ?? params.via,
+        // `setup login` is the operator interactively choosing this env, so a
+        // new login enrollment is mint-eligible; every other path is not. A
+        // prior value always wins — re-login never re-widens what an operator
+        // narrowed via `scai policy set`.
+        mintCredentials: prior?.mintCredentials ?? params.via === "setup-login",
+        ciWrites: prior?.ciWrites ?? false,
+        // Step-up is off unless an operator opts in via `scai policy set`.
+        stepUpMinutes: prior?.stepUpMinutes,
+    };
+    policy.environments[params.envName] = entry;
+    const writtenPath = (0, store_1.writeWorkspacePolicy)(policy);
+    return {
+        created: existing === null && writtenPath !== null,
+        alreadyEnrolled: prior !== undefined,
+        written: writtenPath !== null,
+    };
+};
+exports.enrollEnvironment = enrollEnvironment;
+/**
+ * Re-pin an already-enrolled environment's identity to whatever the
+ * config currently says — the `scai policy trust` path, used after a
+ * legitimate tenant change. Returns `false` if the environment is not
+ * enrolled or nothing could be written.
+ */
+const repinEnvironment = (envName, environment) => {
+    const policy = (0, store_1.readWorkspacePolicy)();
+    const prior = policy?.environments[envName];
+    if (!policy || !prior) {
+        return false;
+    }
+    policy.environments[envName] = { ...prior, identity: (0, identity_1.extractIdentity)(environment) };
+    return (0, store_1.writeWorkspacePolicy)(policy) !== null;
+};
+exports.repinEnvironment = repinEnvironment;
+/** Remove an environment from the allowlist. Returns `false` if absent. */
+const unenrollEnvironment = (envName) => {
+    const policy = (0, store_1.readWorkspacePolicy)();
+    if (!policy || !policy.environments[envName]) {
+        return false;
+    }
+    delete policy.environments[envName];
+    return (0, store_1.writeWorkspacePolicy)(policy) !== null;
+};
+exports.unenrollEnvironment = unenrollEnvironment;
+/**
+ * Explicitly update an enrolled environment's Phase 2 policy flags — the
+ * `scai policy set` path. Only the fields provided are changed. Returns
+ * `false` if the environment is not enrolled or nothing could be written.
+ */
+const setEnvironmentFlags = (envName, flags) => {
+    const policy = (0, store_1.readWorkspacePolicy)();
+    const prior = policy?.environments[envName];
+    if (!policy || !prior) {
+        return false;
+    }
+    const next = {
+        ...prior,
+        ceiling: flags.ceiling ?? prior.ceiling,
+        mintCredentials: flags.mintCredentials ?? prior.mintCredentials,
+        ciWrites: flags.ciWrites ?? prior.ciWrites,
+    };
+    if (flags.stepUpMinutes === null) {
+        delete next.stepUpMinutes;
+    }
+    else if (flags.stepUpMinutes !== undefined) {
+        next.stepUpMinutes = flags.stepUpMinutes;
+    }
+    policy.environments[envName] = next;
+    return (0, store_1.writeWorkspacePolicy)(policy) !== null;
+};
+exports.setEnvironmentFlags = setEnvironmentFlags;

package/dist/policy/environment.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared environment-resolution helper. Replaces the three near-duplicate
+ * implementations that grew up across `recipe/tasks/shared.ts:resolveTenant`,
+ * `deploy/tasks/shared.ts:getDeployContext`, and the hand-copied
+ * `resolveAuthoringEnvironment` blocks in `deploy/tasks/site.ts` and
+ * `deploy/tasks/site-bind.ts` — all doing the same
+ * readRoot → defaultEnvProfile → environment-or-throw dance with slightly
+ * different error messages and return shapes.
+ *
+ * Domain-specific wrappers (recipe `resolveTenant`, deploy
+ * `getDeployContext`) compose this and add their own decoration
+ * (auth client, deploy token lookup, etc.).
+ */
+import type { EnvironmentConfiguration, RootConfiguration } from "../config/types";
+export interface ResolvedEnvironment {
+    envName: string;
+    environment: EnvironmentConfiguration;
+    root: RootConfiguration;
+    /** Tenant API client timeout in ms, derived from
+     *  `settings.apiClientTimeoutInMinutes`. `undefined` when unset/invalid. */
+    timeoutMs: number | undefined;
+}
+export interface ResolveEnvironmentOptions {
+    config?: string;
+    environmentName?: string;
+    /**
+     * Skip the workspace-policy gate (`enforceEnvironmentPolicy`). Used by
+     * the paths that run *before* an environment is enrolled — `scai mcp
+     * serve` startup (which enrolls the bound env immediately after) and
+     * the `setup` / `policy` commands. Everything that touches tenant data
+     * leaves this unset, so the gate is on by default.
+     */
+    skipPolicy?: boolean;
+}
+export declare const resolveEnvironment: (options: ResolveEnvironmentOptions) => ResolvedEnvironment;