@salesforce/b2c-tooling-sdk 1.0.1 → 1.1.0

package/dist/esm/index.js

@@ -31,7 +31,7 @@ export { getRole, listRoles } from './operations/roles/index.js';
 // Operations - Organizations
 export { getOrg, getOrgByName, listOrgs } from './operations/orgs/index.js';
 // Safety - Protection against destructive operations
-export { getSafetyLevel, describeSafetyLevel, checkSafetyViolation, SafetyBlockedError } from './safety/index.js';
+export { getSafetyLevel, describeSafetyLevel, checkSafetyViolation, checkLevelViolation, SafetyBlockedError, SafetyConfirmationRequired, SafetyGuard, extractJobIdFromPath, maxSafetyLevel, isValidSafetyLevel, parseSafetyLevelString, resolveEffectiveSafetyConfig, loadGlobalSafetyConfig, isValidSafetyAction, VALID_SAFETY_ACTIONS, withSafetyConfirmation, } from './safety/index.js';
 // Defaults
 export { DEFAULT_ACCOUNT_MANAGER_HOST, DEFAULT_ODS_HOST, DEFAULT_PUBLIC_CLIENT_ID, getDefaultPublicClientId, } from './defaults.js';
 // Version info

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAC,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,WAAW,EAAE,kBAAkB,EAAC,MAAM,oBAAoB,CAAC;AAG7G,OAAO;AACP,OAAO,EAAC,CAAC,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,oBAAoB,EAAE,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAGlH,SAAS;AACT,OAAO,EAAC,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,oBAAoB,EAAC,MAAM,mBAAmB,CAAC;AAe9G,yCAAyC;AACzC,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,SAAS,EACT,mBAAmB,EACnB,yBAAyB,EACzB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAiBzB,2BAA2B;AAC3B,OAAO,EAAC,WAAW,EAAC,MAAM,qBAAqB,CAAC;AAGhD,UAAU;AACV,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,oBAAoB,EACpB,2BAA2B,EAC3B,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,+BAA+B,EAC/B,+BAA+B,EAC/B,oCAAoC,EACpC,8BAA8B,EAC9B,oBAAoB,EACpB,gCAAgC,EAChC,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,0BAA0B,EAC1B,yBAAyB,EACzB,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAwF5B,oBAAoB;AACpB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,4BAA4B,CAAC;AAYpC,oBAAoB;AACpB,OAAO,EACL,UAAU,EACV,eAAe,EACf,UAAU,EACV,mBAAmB,EACnB,uBAAuB,EACvB,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAoBpC,8BAA8B;AAC9B,OAAO,EACL,UAAU,EACV,OAAO,EACP,cAAc,EACd,QAAQ,EACR,eAAe,EACf,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,YAAY,GACb,MAAM,iBAAiB,CAAC;AAYzB,mBAAmB;AACnB,OAAO,EACL,MAAM,EACN,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,0BAA0B,EAC1B,mBAAmB,EACnB,yBAAyB,EACzB,YAAY,EACZ,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,2BAA2B,CAAC;AAKnC,mBAAmB;AACnB,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,aAAa,GACd,MAAM,2BAA2B,CAAC;AAiBnC,qBAAqB;AACrB,OAAO,EACL,OAAO,EACP,cAAc,EACd,SAAS,EACT,UAAU,EACV,UAAU,EACV,UAAU,EACV,SAAS,EACT,SAAS,EACT,SAAS,EACT,UAAU,GACX,MAAM,6BAA6B,CAAC;AAErC,qBAAqB;AACrB,OAAO,EAAC,OAAO,EAAE,SAAS,EAAC,MAAM,6BAA6B,CAAC;AAE/D,6BAA6B;AAC7B,OAAO,EAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAC,MAAM,4BAA4B,CAAC;AAE1E,qDAAqD;AACrD,OAAO,EAAC,cAAc,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAGhH,WAAW;AACX,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AAEvB,eAAe;AACf,OAAO,EAAC,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAC,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/safety/index.d.ts

@@ -3,5 +3,10 @@
  *
  * @module safety
  */
-export type { SafetyLevel, SafetyConfig } from './safety-middleware.js';
-export { SafetyBlockedError, checkSafetyViolation, getSafetyLevel, describeSafetyLevel } from './safety-middleware.js';
+export type { SafetyAction, SafetyRule, SafetyOperation, SafetyEvaluation } from './types.js';
+export { isValidSafetyAction, VALID_SAFETY_ACTIONS } from './types.js';
+export type { SafetyLevel, SafetyConfig, SafetyConfigFragment } from './safety-middleware.js';
+export { SafetyBlockedError, SafetyConfirmationRequired, checkSafetyViolation, checkLevelViolation, getSafetyLevel, describeSafetyLevel, maxSafetyLevel, isValidSafetyLevel, parseSafetyLevelString, resolveEffectiveSafetyConfig, loadGlobalSafetyConfig, } from './safety-middleware.js';
+export { SafetyGuard, extractJobIdFromPath } from './safety-guard.js';
+export type { ConfirmHandler } from './with-confirmation.js';
+export { withSafetyConfirmation } from './with-confirmation.js';

package/dist/esm/safety/index.js

@@ -3,5 +3,9 @@
  * SPDX-License-Identifier: Apache-2
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
-export { SafetyBlockedError, checkSafetyViolation, getSafetyLevel, describeSafetyLevel } from './safety-middleware.js';
+export { isValidSafetyAction, VALID_SAFETY_ACTIONS } from './types.js';
+export { SafetyBlockedError, SafetyConfirmationRequired, checkSafetyViolation, checkLevelViolation, getSafetyLevel, describeSafetyLevel, maxSafetyLevel, isValidSafetyLevel, parseSafetyLevelString, resolveEffectiveSafetyConfig, loadGlobalSafetyConfig, } from './safety-middleware.js';
+// SafetyGuard
+export { SafetyGuard, extractJobIdFromPath } from './safety-guard.js';
+export { withSafetyConfirmation } from './with-confirmation.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/safety/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/safety/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,OAAO,EAAC,kBAAkB,EAAE,oBAAoB,EAAE,cAAc,EAAE,mBAAmB,EAAC,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/safety/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,OAAO,EAAC,mBAAmB,EAAE,oBAAoB,EAAC,MAAM,YAAY,CAAC;AAIrE,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,kBAAkB,EAClB,sBAAsB,EACtB,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAEhC,cAAc;AACd,OAAO,EAAC,WAAW,EAAE,oBAAoB,EAAC,MAAM,mBAAmB,CAAC;AAIpE,OAAO,EAAC,sBAAsB,EAAC,MAAM,wBAAwB,CAAC"}

package/dist/esm/safety/safety-guard.d.ts

@@ -0,0 +1,92 @@
+import type { SafetyConfig } from './safety-middleware.js';
+import type { SafetyEvaluation, SafetyOperation, SafetyRule } from './types.js';
+/**
+ * Extract a job ID from a URL path if it's a job execution endpoint.
+ *
+ * Matches patterns like:
+ * - `/s/-/dw/data/v24_5/jobs/sfcc-site-archive-import/executions`
+ * - `/jobs/sfcc-site-archive-export/executions`
+ */
+export declare function extractJobIdFromPath(path: string): string | undefined;
+/**
+ * SafetyGuard evaluates operations against safety rules and levels.
+ *
+ * The guard provides three levels of API:
+ * - {@link evaluate} — returns a {@link SafetyEvaluation} describing what should happen
+ * - {@link assert} — throws {@link SafetyBlockedError} or {@link SafetyConfirmationRequired}
+ * - {@link temporarilyAllow} — creates a scoped exemption for confirmed operations
+ *
+ * The HTTP middleware uses the guard internally so all HTTP requests are
+ * evaluated automatically. CLI commands and other consumers can use the
+ * guard directly for richer safety interaction (command-level checks,
+ * confirmation flows).
+ *
+ * @example
+ * ```typescript
+ * const guard = new SafetyGuard({
+ *   level: 'NO_UPDATE',
+ *   confirm: true,
+ *   rules: [{ job: 'sfcc-site-archive-export', action: 'allow' }],
+ * });
+ *
+ * const evaluation = guard.evaluate({ type: 'job', jobId: 'sfcc-site-archive-export' });
+ * // evaluation.action === 'allow'
+ * ```
+ */
+export declare class SafetyGuard {
+    readonly config: SafetyConfig;
+    private temporaryAllows;
+    private readonly logger;
+    constructor(config: SafetyConfig);
+    /**
+     * Evaluate an operation against safety rules and level.
+     *
+     * Evaluation order:
+     * 1. Temporary allows (from confirmed retries) — if matched, allow
+     * 2. Config rules in order — first matching rule's action wins
+     * 3. Level-based default — confirm if `confirm: true`, otherwise block/allow
+     *
+     * All evaluations are trace-logged for diagnostics.
+     */
+    evaluate(operation: SafetyOperation): SafetyEvaluation;
+    /**
+     * Assert that an operation is allowed.
+     *
+     * @throws {SafetyBlockedError} if the operation is blocked
+     * @throws {SafetyConfirmationRequired} if the operation needs confirmation
+     */
+    assert(operation: SafetyOperation): void;
+    /**
+     * Create a temporary exemption for a confirmed operation.
+     *
+     * Returns a cleanup function that removes the exemption. Use this
+     * to retry an operation after the user has confirmed.
+     */
+    temporarilyAllow(operation: SafetyOperation): () => void;
+    /**
+     * Add a temporary safety rule for a scoped exemption.
+     *
+     * Unlike {@link temporarilyAllow} which derives a rule from an operation,
+     * this accepts an arbitrary rule — useful for granting broad temporary
+     * access (e.g., allowing WebDAV DELETE on Impex paths during a job export).
+     *
+     * Returns a cleanup function that removes the rule.
+     */
+    temporarilyAddRule(rule: SafetyRule): () => void;
+    /**
+     * Evaluate an operation using only the safety level (no rules).
+     */
+    private evaluateByLevel;
+    /**
+     * Convert an operation to a temporary allow rule for retry.
+     */
+    private operationToRule;
+    /**
+     * Describe why a rule matched, for user-facing messages.
+     */
+    private describeRuleMatch;
+    /**
+     * Describe why the level blocked an operation, for user-facing messages.
+     */
+    private describeLevelBlock;
+}

package/dist/esm/safety/safety-guard.js

@@ -0,0 +1,270 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * SafetyGuard: SDK-level safety evaluation engine.
+ *
+ * Evaluates operations against safety rules and levels, producing typed
+ * evaluations (allow/block/confirm). Used by both the HTTP middleware
+ * (automatic) and command-level checks (opt-in).
+ *
+ * @module safety/safety-guard
+ */
+import { Minimatch } from 'minimatch';
+import { getLogger } from '../logging/index.js';
+import { SafetyBlockedError, SafetyConfirmationRequired, checkLevelViolation, describeSafetyLevel, } from './safety-middleware.js';
+/** Regex to extract job ID from OCAPI job execution URLs. */
+const JOB_EXECUTION_PATTERN = /\/jobs\/([^/]+)\/executions/;
+/**
+ * Extract a job ID from a URL path if it's a job execution endpoint.
+ *
+ * Matches patterns like:
+ * - `/s/-/dw/data/v24_5/jobs/sfcc-site-archive-import/executions`
+ * - `/jobs/sfcc-site-archive-export/executions`
+ */
+export function extractJobIdFromPath(path) {
+    const match = JOB_EXECUTION_PATTERN.exec(path);
+    return match?.[1];
+}
+/**
+ * Test whether a string matches a glob pattern.
+ * Uses minimatch with dot matching enabled.
+ */
+function matchGlob(value, pattern) {
+    const matcher = new Minimatch(pattern, { dot: true, nocase: true });
+    return matcher.match(value);
+}
+/**
+ * Check if a rule matches an operation.
+ */
+function ruleMatchesOperation(rule, operation) {
+    // Command matcher
+    if (rule.command !== undefined) {
+        if (!operation.commandId)
+            return false;
+        return matchGlob(operation.commandId, rule.command);
+    }
+    // Job matcher
+    if (rule.job !== undefined) {
+        const jobId = operation.jobId ?? (operation.path ? extractJobIdFromPath(operation.path) : undefined);
+        if (!jobId)
+            return false;
+        return matchGlob(jobId, rule.job);
+    }
+    // HTTP method + path matcher
+    if (rule.path !== undefined) {
+        if (!operation.path)
+            return false;
+        if (!matchGlob(operation.path, rule.path))
+            return false;
+        // If method is specified, it must also match
+        if (rule.method !== undefined) {
+            if (!operation.method)
+                return false;
+            return matchGlob(operation.method.toUpperCase(), rule.method.toUpperCase());
+        }
+        return true;
+    }
+    // Method-only matcher (no path)
+    if (rule.method !== undefined) {
+        if (!operation.method)
+            return false;
+        return matchGlob(operation.method.toUpperCase(), rule.method.toUpperCase());
+    }
+    // Rule has no matchers — does not match anything
+    return false;
+}
+/**
+ * SafetyGuard evaluates operations against safety rules and levels.
+ *
+ * The guard provides three levels of API:
+ * - {@link evaluate} — returns a {@link SafetyEvaluation} describing what should happen
+ * - {@link assert} — throws {@link SafetyBlockedError} or {@link SafetyConfirmationRequired}
+ * - {@link temporarilyAllow} — creates a scoped exemption for confirmed operations
+ *
+ * The HTTP middleware uses the guard internally so all HTTP requests are
+ * evaluated automatically. CLI commands and other consumers can use the
+ * guard directly for richer safety interaction (command-level checks,
+ * confirmation flows).
+ *
+ * @example
+ * ```typescript
+ * const guard = new SafetyGuard({
+ *   level: 'NO_UPDATE',
+ *   confirm: true,
+ *   rules: [{ job: 'sfcc-site-archive-export', action: 'allow' }],
+ * });
+ *
+ * const evaluation = guard.evaluate({ type: 'job', jobId: 'sfcc-site-archive-export' });
+ * // evaluation.action === 'allow'
+ * ```
+ */
+export class SafetyGuard {
+    config;
+    temporaryAllows = [];
+    logger;
+    constructor(config) {
+        this.config = config;
+        this.logger = getLogger();
+    }
+    /**
+     * Evaluate an operation against safety rules and level.
+     *
+     * Evaluation order:
+     * 1. Temporary allows (from confirmed retries) — if matched, allow
+     * 2. Config rules in order — first matching rule's action wins
+     * 3. Level-based default — confirm if `confirm: true`, otherwise block/allow
+     *
+     * All evaluations are trace-logged for diagnostics.
+     */
+    evaluate(operation) {
+        // 1. Check temporary allows (confirmed operations)
+        for (const rule of this.temporaryAllows) {
+            if (ruleMatchesOperation(rule, operation)) {
+                const evaluation = {
+                    action: 'allow',
+                    reason: 'Temporarily allowed after confirmation',
+                    operation,
+                    rule,
+                };
+                this.logger.trace({ operation, evaluation }, '[SafetyGuard] Allowed by temporary exemption');
+                return evaluation;
+            }
+        }
+        // 2. Check config rules (first match wins)
+        if (this.config.rules) {
+            for (const rule of this.config.rules) {
+                if (ruleMatchesOperation(rule, operation)) {
+                    const evaluation = {
+                        action: rule.action,
+                        reason: this.describeRuleMatch(rule, operation),
+                        operation,
+                        rule,
+                    };
+                    this.logger.trace({ operation, rule, action: rule.action }, '[SafetyGuard] Matched rule');
+                    return evaluation;
+                }
+            }
+        }
+        // 3. Fall back to level-based evaluation
+        return this.evaluateByLevel(operation);
+    }
+    /**
+     * Assert that an operation is allowed.
+     *
+     * @throws {SafetyBlockedError} if the operation is blocked
+     * @throws {SafetyConfirmationRequired} if the operation needs confirmation
+     */
+    assert(operation) {
+        const evaluation = this.evaluate(operation);
+        switch (evaluation.action) {
+            case 'allow':
+                return;
+            case 'block':
+                throw new SafetyBlockedError(evaluation.reason, operation.method ?? '', operation.url ?? '', this.config.level);
+            case 'confirm':
+                throw new SafetyConfirmationRequired(evaluation);
+        }
+    }
+    /**
+     * Create a temporary exemption for a confirmed operation.
+     *
+     * Returns a cleanup function that removes the exemption. Use this
+     * to retry an operation after the user has confirmed.
+     */
+    temporarilyAllow(operation) {
+        const rule = this.operationToRule(operation);
+        return this.temporarilyAddRule(rule);
+    }
+    /**
+     * Add a temporary safety rule for a scoped exemption.
+     *
+     * Unlike {@link temporarilyAllow} which derives a rule from an operation,
+     * this accepts an arbitrary rule — useful for granting broad temporary
+     * access (e.g., allowing WebDAV DELETE on Impex paths during a job export).
+     *
+     * Returns a cleanup function that removes the rule.
+     */
+    temporarilyAddRule(rule) {
+        this.temporaryAllows.push(rule);
+        this.logger.trace({ rule }, '[SafetyGuard] Added temporary rule');
+        return () => {
+            const idx = this.temporaryAllows.indexOf(rule);
+            if (idx >= 0) {
+                this.temporaryAllows.splice(idx, 1);
+                this.logger.trace({ rule }, '[SafetyGuard] Removed temporary rule');
+            }
+        };
+    }
+    /**
+     * Evaluate an operation using only the safety level (no rules).
+     */
+    evaluateByLevel(operation) {
+        // For HTTP operations, check the level
+        if (operation.method && operation.path) {
+            const violation = checkLevelViolation(operation.method, operation.path, this.config.level);
+            if (violation) {
+                const action = this.config.confirm ? 'confirm' : 'block';
+                const evaluation = {
+                    action,
+                    reason: this.describeLevelBlock(operation),
+                    operation,
+                };
+                this.logger.trace({ operation, action, level: this.config.level }, '[SafetyGuard] Level evaluation');
+                return evaluation;
+            }
+        }
+        // For command operations, no level-based blocking (levels are HTTP-level)
+        // Commands opt into safety via rules or assertDestructiveOperationAllowed()
+        const evaluation = {
+            action: 'allow',
+            reason: 'No matching rule and level allows this operation',
+            operation,
+        };
+        this.logger.trace({ operation, level: this.config.level }, '[SafetyGuard] Allowed by level');
+        return evaluation;
+    }
+    /**
+     * Convert an operation to a temporary allow rule for retry.
+     */
+    operationToRule(operation) {
+        if (operation.commandId) {
+            return { command: operation.commandId, action: 'allow' };
+        }
+        if (operation.jobId) {
+            return { job: operation.jobId, action: 'allow' };
+        }
+        // HTTP operation — match exact method + path
+        return {
+            method: operation.method,
+            path: operation.path,
+            action: 'allow',
+        };
+    }
+    /**
+     * Describe why a rule matched, for user-facing messages.
+     */
+    describeRuleMatch(rule, operation) {
+        if (rule.command) {
+            return `Command "${operation.commandId}" matched safety rule (command: "${rule.command}", action: ${rule.action})`;
+        }
+        if (rule.job) {
+            return `Job "${operation.jobId}" matched safety rule (job: "${rule.job}", action: ${rule.action})`;
+        }
+        const method = operation.method ?? 'unknown';
+        const path = operation.path ?? 'unknown';
+        return `${method} ${path} matched safety rule (action: ${rule.action})`;
+    }
+    /**
+     * Describe why the level blocked an operation, for user-facing messages.
+     */
+    describeLevelBlock(operation) {
+        const method = operation.method ?? 'unknown';
+        const path = operation.path ?? 'unknown';
+        const levelDesc = describeSafetyLevel(this.config.level);
+        return `${method} ${path} blocked by safety level ${this.config.level} — ${levelDesc}`;
+    }
+}
+//# sourceMappingURL=safety-guard.js.map

package/dist/esm/safety/safety-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety-guard.js","sourceRoot":"","sources":["../../../src/safety/safety-guard.ts"],"names":[],"mappings":"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"}

package/dist/esm/safety/safety-middleware.d.ts

@@ -1,3 +1,5 @@
+import type { SafetyRule } from './types.js';
+import type { SafetyEvaluation } from './types.js';
 /**
  * Safety levels for preventing destructive operations.
  *
@@ -7,11 +9,34 @@
  * - READ_ONLY: Block all write operations (only GET allowed)
  */
 export type SafetyLevel = 'NONE' | 'NO_DELETE' | 'NO_UPDATE' | 'READ_ONLY';
+/**
+ * Safety configuration.
+ *
+ * Supports both simple level-based blocking and granular per-rule actions.
+ */
 export interface SafetyConfig {
+    /** The base safety level. */
     level: SafetyLevel;
+    /** When true, operations that the level would block require confirmation instead of hard-blocking. */
+    confirm?: boolean;
+    /** Ordered list of rules. First matching rule wins. */
+    rules?: SafetyRule[];
 }
 /**
- * Safety error thrown when an operation is blocked by safety middleware.
+ * Returns the more restrictive of two safety levels.
+ */
+export declare function maxSafetyLevel(a: SafetyLevel, b: SafetyLevel): SafetyLevel;
+/**
+ * Check if a string is a valid SafetyLevel.
+ */
+export declare function isValidSafetyLevel(value: string): value is SafetyLevel;
+/**
+ * Parse a string to a SafetyLevel, returning undefined for invalid values.
+ * Accepts case-insensitive input and converts dashes to underscores.
+ */
+export declare function parseSafetyLevelString(value: string | undefined): SafetyLevel | undefined;
+/**
+ * Safety error thrown when an operation is blocked by safety configuration.
  */
 export declare class SafetyBlockedError extends Error {
     readonly method: string;
@@ -19,6 +44,28 @@ export declare class SafetyBlockedError extends Error {
     readonly safetyLevel: SafetyLevel;
     constructor(message: string, method: string, url: string, safetyLevel: SafetyLevel);
 }
+/**
+ * Error thrown when an operation requires interactive confirmation.
+ *
+ * Callers can catch this error, prompt the user, and retry the operation
+ * using {@link withSafetyConfirmation}.
+ */
+export declare class SafetyConfirmationRequired extends Error {
+    readonly evaluation: SafetyEvaluation;
+    constructor(evaluation: SafetyEvaluation);
+}
+/**
+ * Checks if an HTTP operation should be blocked based on a safety level.
+ *
+ * This is the low-level level check. For full rule-based evaluation,
+ * use {@link SafetyGuard.evaluate}.
+ *
+ * @param method - HTTP method (GET, POST, PUT, PATCH, DELETE)
+ * @param path - URL pathname
+ * @param level - Safety level to check against
+ * @returns Error message if blocked, undefined if allowed
+ */
+export declare function checkLevelViolation(method: string, path: string, level: SafetyLevel): string | undefined;
 /**
  * Checks if an HTTP operation should be blocked based on safety configuration.
  *
@@ -26,6 +73,7 @@ export declare class SafetyBlockedError extends Error {
  * @param url - Request URL
  * @param config - Safety configuration
  * @returns Error message if blocked, undefined if allowed
+ * @deprecated Use {@link SafetyGuard.evaluate} for full rule-based evaluation.
  */
 export declare function checkSafetyViolation(method: string, url: string, config: SafetyConfig): string | undefined;
 /**
@@ -43,3 +91,40 @@ export declare function getSafetyLevel(defaultLevel?: SafetyLevel): SafetyLevel;
  * Get a user-friendly description of the safety level.
  */
 export declare function describeSafetyLevel(level: SafetyLevel): string;
+/** Validated safety config fragment (shared by global and per-instance). */
+export interface SafetyConfigFragment {
+    level?: SafetyLevel;
+    confirm?: boolean;
+    rules?: SafetyRule[];
+}
+/**
+ * Load global safety configuration from a JSON file.
+ *
+ * Resolution order:
+ * 1. `SFCC_SAFETY_CONFIG` env var — explicit path to a safety config file
+ * 2. `{configDir}/safety.json` — oclif config directory (e.g., `~/.config/b2c/safety.json`)
+ *
+ * The file has the same shape as the `safety` object in dw.json:
+ * ```json
+ * { "level": "NO_DELETE", "confirm": true, "rules": [...] }
+ * ```
+ *
+ * @param configDir - oclif config directory path (e.g., `this.config.configDir`)
+ * @returns Validated safety config fragment, or undefined if no file found
+ */
+export declare function loadGlobalSafetyConfig(configDir?: string): SafetyConfigFragment | undefined;
+/**
+ * Compute effective safety config by merging environment variables, global
+ * safety config, and per-instance config.
+ *
+ * Merge strategy:
+ * - **Level**: `max(env, global, instance)` — most restrictive wins
+ * - **Confirm**: OR across all sources
+ * - **Rules**: instance rules first, then global rules (first-match-wins,
+ *   so instance rules can override global policy)
+ *
+ * @param instanceSafety - Per-instance safety config from dw.json
+ * @param globalSafety - Global safety config from safety.json
+ * @returns Merged SafetyConfig
+ */
+export declare function resolveEffectiveSafetyConfig(instanceSafety?: SafetyConfigFragment, globalSafety?: SafetyConfigFragment): SafetyConfig;