@actsecurity/iam-lens 0.1.165 → 0.1.167

package/dist/esm/simulate/roleSessionTags.js

@@ -0,0 +1,213 @@
+import { loadPolicy } from '@actsecurity/iam-policy';
+import { actionMatchesPattern } from '@actsecurity/iam-utils';
+const tagSessionAction = 'sts:TagSession';
+const tagKeysConditionKey = 'aws:tagkeys';
+const policyVariablePattern = /\$\{[^}]+\}/;
+/** No trust-policy Allow permits session tags. */
+const noSessionTags = { type: 'none' };
+/** At least one trust-policy Allow may permit any session-tag key. */
+const anySessionTag = { type: 'any' };
+/**
+ * Determines which tag keys a role session may supply from the role's trust policy.
+ *
+ * This result intentionally does not depend on tags currently stored on the role. Deny statements
+ * and conditions unrelated to `aws:TagKeys` are ignored. Supported
+ * `ForAllValues:StringEquals` operators form a finite allowlist for one Allow statement, while
+ * `ForAnyValue`, unsupported operators, and policy-variable values conservatively permit any key.
+ *
+ * @param trustPolicy the role's validated trust policy, or undefined when it was not collected
+ * @returns the role's session-tag key capability
+ */
+export function roleSessionTagCapability(trustPolicy) {
+    if (!trustPolicy) {
+        return noSessionTags;
+    }
+    if (trustPolicy.errors.length > 0) {
+        return anySessionTag;
+    }
+    const allowedTagKeys = [];
+    let hasTagSessionAllow = false;
+    for (const statement of loadPolicy(trustPolicy).statements()) {
+        if (!statement.isAllow() || !statementAllowsTagSession(statement)) {
+            continue;
+        }
+        hasTagSessionAllow = true;
+        const statementCapability = tagCapabilityForStatement(statement);
+        if (statementCapability.type === 'any') {
+            return anySessionTag;
+        }
+        if (statementCapability.type === 'allowlist') {
+            allowedTagKeys.push(...statementCapability.tagKeys);
+        }
+    }
+    if (!hasTagSessionAllow) {
+        return noSessionTags;
+    }
+    return {
+        type: 'allowlist',
+        tagKeys: uniqueTagKeys(allowedTagKeys)
+    };
+}
+/**
+ * Determines whether a tag key can be supplied by a role session.
+ *
+ * @param capability the trust-policy-derived session-tag capability
+ * @param tagKey the tag key to test
+ * @returns true when a role session may supply the key
+ */
+export function roleSessionCanSetTagKey(capability, tagKey) {
+    if (capability.type === 'any') {
+        return true;
+    }
+    if (capability.type === 'none') {
+        return false;
+    }
+    return capability.tagKeys.some((entry) => tagKeyMatchesEntry(tagKey, entry));
+}
+/**
+ * Builds a slash-delimited regex constraint for PrincipalTag keys that cannot be session supplied.
+ *
+ * The iam-simulate constraint matcher is case-insensitive. Consequently, case variants of a
+ * case-sensitive allowlist entry are also excluded from this strict pattern. That may preserve
+ * extra conditional results, but it cannot incorrectly make a mutable tag strict.
+ *
+ * @param capability the trust-policy-derived session-tag capability
+ * @returns a strict PrincipalTag pattern, or undefined when every tag key may be supplied
+ */
+export function immutablePrincipalTagPattern(capability) {
+    if (capability.type === 'any') {
+        return undefined;
+    }
+    if (capability.type === 'none' || capability.tagKeys.length === 0) {
+        return '/^aws:PrincipalTag\/.*/';
+    }
+    const mutableNames = capability.tagKeys.map((entry) => escapeRegex(entry.tagKey)).join('|');
+    return `/^aws:PrincipalTag\\/(?!(?:${mutableNames})$).*/`;
+}
+/**
+ * Determines whether an Allow statement's Action or NotAction includes `sts:TagSession`.
+ *
+ * @param statement the parsed trust-policy statement to inspect
+ * @returns true when the statement applies to the TagSession action
+ */
+function statementAllowsTagSession(statement) {
+    if (statement.isActionStatement()) {
+        return statement
+            .actions()
+            .some((action) => actionMatchesPattern(tagSessionAction, action.value()));
+    }
+    if (statement.isNotActionStatement()) {
+        return !statement
+            .notActions()
+            .some((action) => actionMatchesPattern(tagSessionAction, action.value()));
+    }
+    return false;
+}
+/**
+ * Determines which tag keys one TagSession Allow statement may supply.
+ *
+ * @param statement a parsed Allow statement that includes TagSession
+ * @returns the statement's session-tag capability
+ */
+function tagCapabilityForStatement(statement) {
+    const tagKeysConditions = statement
+        .conditions()
+        .filter((condition) => stringsEqualIgnoreCase(condition.conditionKey(), tagKeysConditionKey));
+    if (tagKeysConditions.length === 0 || tagKeysConditions.some(conditionIsUnbounded)) {
+        return anySessionTag;
+    }
+    return {
+        type: 'allowlist',
+        tagKeys: intersectTagKeyConditions(tagKeysConditions)
+    };
+}
+/**
+ * Determines whether a TagKeys condition cannot prove a finite exhaustive key allowlist.
+ *
+ * @param condition the parsed `aws:TagKeys` condition
+ * @returns true when the statement must conservatively be treated as permitting any key
+ */
+function conditionIsUnbounded(condition) {
+    const operation = condition.operation();
+    if (operation.isIfExists() || operation.setOperator() !== 'ForAllValues') {
+        return true;
+    }
+    const baseOperator = operation.baseOperator();
+    if (!stringsEqualIgnoreCase(baseOperator, 'StringEquals') &&
+        !stringsEqualIgnoreCase(baseOperator, 'StringEqualsIgnoreCase')) {
+        return true;
+    }
+    return condition.conditionValues().some((value) => policyVariablePattern.test(value));
+}
+/**
+ * Intersects finite ForAllValues TagKeys allowlists within one statement.
+ *
+ * @param conditions supported TagKeys conditions from one statement
+ * @returns tag keys capable of satisfying every condition
+ */
+function intersectTagKeyConditions(conditions) {
+    const conditionEntries = conditions.map(entriesForCondition);
+    const hasCaseSensitiveCondition = conditionEntries.some((entries) => entries.some((entry) => !entry.ignoreCase));
+    const candidates = hasCaseSensitiveCondition
+        ? conditionEntries.flat().filter((entry) => !entry.ignoreCase)
+        : conditionEntries[0];
+    return uniqueTagKeys(candidates.filter((candidate) => conditionEntries.every((entries) => entries.some((entry) => tagKeyMatchesEntry(candidate.tagKey, entry)))));
+}
+/**
+ * Converts one supported TagKeys condition into comparable entries.
+ *
+ * @param condition the parsed supported condition
+ * @returns entries carrying the condition's case-comparison semantics
+ */
+function entriesForCondition(condition) {
+    const ignoreCase = stringsEqualIgnoreCase(condition.operation().baseOperator(), 'StringEqualsIgnoreCase');
+    return condition.conditionValues().map((tagKey) => ({ tagKey, ignoreCase }));
+}
+/**
+ * Tests a concrete tag key against a trust-policy allowlist entry.
+ *
+ * @param tagKey the concrete tag key
+ * @param entry the allowlist entry and its comparison semantics
+ * @returns true when the key matches the entry
+ */
+function tagKeyMatchesEntry(tagKey, entry) {
+    return entry.ignoreCase ? stringsEqualIgnoreCase(tagKey, entry.tagKey) : tagKey === entry.tagKey;
+}
+/**
+ * Removes semantically duplicate tag-key entries while preserving case-sensitive alternatives.
+ *
+ * @param entries tag-key entries to deduplicate
+ * @returns unique entries
+ */
+function uniqueTagKeys(entries) {
+    const unique = [];
+    for (const entry of entries) {
+        if (!unique.some((existing) => existing.ignoreCase === entry.ignoreCase &&
+            (entry.ignoreCase
+                ? stringsEqualIgnoreCase(existing.tagKey, entry.tagKey)
+                : existing.tagKey === entry.tagKey))) {
+            unique.push(entry);
+        }
+    }
+    return unique;
+}
+/**
+ * Compares strings without case sensitivity or normalized string allocations.
+ *
+ * @param left first value to compare
+ * @param right second value to compare
+ * @returns true when the values compare equally without case sensitivity
+ */
+function stringsEqualIgnoreCase(left, right) {
+    return left.localeCompare(right, undefined, { sensitivity: 'base' }) === 0;
+}
+/**
+ * Escapes a literal string for use inside a regular expression.
+ *
+ * @param value the literal value to escape
+ * @returns a regex-safe representation
+ */
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=roleSessionTags.js.map

package/dist/esm/simulate/roleSessionTags.js.map

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

package/dist/esm/simulate/simulate.d.ts

@@ -54,6 +54,18 @@ export interface AnonymousSimulationRequest extends Omit<SimulationRequest, 'pri
      */
     resourceArn: string;
 }
+/**
+ * A simulation request for a principal ARN that is not collected as an IAM identity.
+ *
+ * The principal's captured organization policy hierarchies still apply. Its identity policies
+ * and permission boundary are replaced by one synthetic allow-all policy or `inlinePolicy`.
+ */
+export interface VirtualPrincipalSimulationRequest extends SimulationRequest {
+    /**
+     * Raw inline identity policy that replaces the default synthetic allow-all policy.
+     */
+    inlinePolicy?: Record<string, unknown>;
+}
 /**
  * A simulation request targeting a resource that is not expected to exist in the collected dataset.
  */
@@ -89,6 +101,10 @@ export type InternalSimulationRequest = Omit<SimulationRequest, 'principal'> & {
      * Authenticated principal string, or undefined for an anonymous request.
      */
     principal: string | undefined;
+    /**
+     * Caller-supplied inline identity policy for a virtual principal.
+     */
+    inlinePolicy?: Record<string, unknown>;
     /**
      * Caller-supplied external resource or trust policy.
      */
@@ -147,6 +163,18 @@ export declare function simulateAnonymousRequest(simulationRequest: AnonymousSim
  * @returns the normalized request and simulation result
  */
 export declare function simulateExternalPrincipalRequest(simulationRequest: SimulationRequest, collectClient: IamCollectClient): Promise<SimulateRequestResult>;
+/**
+ * Simulate an uncollected IAM principal while applying organization controls for its account.
+ *
+ * The principal receives a synthetic allow-all identity policy unless `inlinePolicy` replaces it.
+ * Permission boundaries and collected identity policies do not apply; supplied session policies still
+ * constrain the request.
+ *
+ * @param simulationRequest the virtual principal request details
+ * @param collectClient the IAM collect client to use for organization and resource-side data access
+ * @returns the normalized request and simulation result
+ */
+export declare function simulateVirtualPrincipal(simulationRequest: VirtualPrincipalSimulationRequest, collectClient: IamCollectClient): Promise<SimulateRequestResult>;
 /**
  * Simulate a collected principal accessing a resource outside the collected dataset.
  * Wildcard-only actions are unsupported.
@@ -157,14 +185,19 @@ export declare function simulateExternalPrincipalRequest(simulationRequest: Simu
  */
 export declare function simulateExternalResourceRequest(simulationRequest: ExternalResourceSimulationRequest, collectClient: IamCollectClient): Promise<SimulateRequestResult>;
 /**
- * Convert an iam-lens strict context key into an iam-simulate Discovery constraint.
+ * Convert an iam-lens context key into an iam-simulate Discovery constraint.
+ *
+ * Caller-provided and explicitly strict keys remain fully authoritative. A stored PrincipalTag
+ * whose role session may override it has known presence but an unknown value. All other input keys
+ * are strict and continue through the existing special-case handling.
  *
  * @param keyName the literal context key or slash-delimited key pattern
  * @param simulationRequest the normalized request whose context certainty is modeled
+ * @param mutablePrincipalTagKeys stored PrincipalTag keys whose values are non-authoritative
  * @returns the Discovery constraint to pass to iam-simulate
  * @internal
  */
-export declare function discoveryConstraintForStrictKey(keyName: string, simulationRequest: Pick<InternalSimulationRequest, 'customContextKeys' | 'simulationMode' | 'principal'>): DiscoveryContextKeyConstraint;
+export declare function discoveryConstraintForStrictKey(keyName: string, simulationRequest: Pick<InternalSimulationRequest, 'additionalStrictContextKeys' | 'customContextKeys' | 'simulationMode' | 'principal'>, mutablePrincipalTagKeys?: ReadonlySet<string>): DiscoveryContextKeyConstraint;
 /**
  * Compare an actual simulation decision with an optional expected result.
  *

package/dist/esm/simulate/simulate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"simulate.d.ts","sourceRoot":"","sources":["../../../src/simulate/simulate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"simulate.d.ts","sourceRoot":"","sources":["../../../src/simulate/simulate.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,6BAA6B,EAClC,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAEzB,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAA;AASlC,OAAO,EAAE,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAanF,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAExD,OAAO,EAEL,KAAK,WAAW,EAKjB,MAAM,kBAAkB,CAAA;AAWzB;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAE/B;;OAEG;IACH,eAAe,EAAE,MAAM,GAAG,SAAS,CAAA;IAEnC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,iBAAiB,EAAE,WAAW,CAAA;IAE9B;;OAEG;IACH,cAAc,EAAE,cAAc,CAAA;IAE9B;;OAEG;IACH,cAAc,CAAC,EAAE,cAAc,CAAA;IAE/B;;OAEG;IACH,aAAa,CAAC,EAAE,GAAG,CAAA;IAEnB;;OAEG;IACH,2BAA2B,CAAC,EAAE,MAAM,EAAE,CAAA;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA2B,SAAQ,IAAI,CACtD,iBAAiB,EACjB,WAAW,GAAG,aAAa,GAAG,eAAe,CAC9C;IACC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iCAAkC,SAAQ,iBAAiB;IAC1E;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,iCAAkC,SAAQ,IAAI,CAAC,iBAAiB,EAAE,aAAa,CAAC;IAC/F;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IAEnB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,CAAA;IAE9B;;OAEG;IACH,MAAM,EAAE,oBAAoB,CAAA;CAC7B;AAQD;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,iBAAiB,EAAE,WAAW,CAAC,GAAG;IAC7E;;OAEG;IACH,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAE7B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAEtC;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACzC,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,gBAAgB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAE,EAAE,CAAA;IAEjD;;OAEG;IACH,sBAAsB,EAAE,qBAAqB,EAAE,CAAA;IAE/C;;OAEG;IACH,0BAA0B,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAE,EAAE,GAAG,SAAS,CAAA;IAEvE;;OAEG;IACH,oBAAoB,EAAE,qBAAqB,EAAE,CAAA;CAC9C;AAiBD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,iBAAiB,EAAE,iBAAiB,EACpC,aAAa,EAAE,gBAAgB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAEhC;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,iBAAiB,EAAE,0BAA0B,EAC7C,aAAa,EAAE,gBAAgB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAMhC;AAED;;;;;;;;GAQG;AACH,wBAAsB,gCAAgC,CACpD,iBAAiB,EAAE,iBAAiB,EACpC,aAAa,EAAE,gBAAgB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAEhC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC5C,iBAAiB,EAAE,iCAAiC,EACpD,aAAa,EAAE,gBAAgB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAEhC;AAED;;;;;;;GAOG;AACH,wBAAsB,+BAA+B,CACnD,iBAAiB,EAAE,iCAAiC,EACpD,aAAa,EAAE,gBAAgB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAEhC;AAyiBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,MAAM,EACf,iBAAiB,EAAE,IAAI,CACrB,yBAAyB,EACzB,6BAA6B,GAAG,mBAAmB,GAAG,gBAAgB,GAAG,WAAW,CACrF,EACD,uBAAuB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAC5C,6BAA6B,CAoC/B;AAoLD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,GAAG,SAAS,EAClD,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAQT"}

package/dist/esm/simulate/simulate.js

@@ -1,7 +1,7 @@
 import { iamActionDetails, iamActionExists, iamServiceExists } from '@actsecurity/iam-data';
 import {} from '@actsecurity/iam-policy';
 import { anonymousPrincipal, runSimulation } from '@actsecurity/iam-simulate';
-import { convertAssumedRoleArnToRoleArn, isAssumedRoleArn, isIamRoleArn, isS3BucketOrObjectArn, splitArnParts } from '@actsecurity/iam-utils';
+import { convertAssumedRoleArnToRoleArn, isAssumedRoleArn, isIamRoleArn, isIamUserArn, isS3BucketOrObjectArn, splitArnParts } from '@actsecurity/iam-utils';
 import { IamCollectClient } from '../collect/client.js';
 import { getAllPoliciesForPrincipal, isServiceLinkedRole, isServicePrincipal, principalExists } from '../principals.js';
 import { getAccountIdForResource, getRcpsForResource, getResourcePolicyForResource } from '../resources.js';
@@ -9,6 +9,7 @@ import {} from '../utils/s3Abac.js';
 import { AssumeRoleActions } from '../utils/sts.js';
 import { CONTEXT_KEYS, contextValue, createContextKeys, isAnonymousPrincipalContextKey, knownContextKeys } from './contextKeys.js';
 import { externalResourcePolicy, syntheticIdentityPolicy } from './generatedPolicies.js';
+import { immutablePrincipalTagPattern, roleSessionCanSetTagKey, roleSessionTagCapability } from './roleSessionTags.js';
 const kmsRetireGrantAction = 'kms:retiregrant';
 /**
  * Simulate an IAM request using the collected policies for both the principal and resource.
@@ -42,6 +43,20 @@ export async function simulateAnonymousRequest(simulationRequest, collectClient)
 export async function simulateExternalPrincipalRequest(simulationRequest, collectClient) {
     return simulateRequestInternal({ ...simulationRequest }, 'externalPrincipal', collectClient);
 }
+/**
+ * Simulate an uncollected IAM principal while applying organization controls for its account.
+ *
+ * The principal receives a synthetic allow-all identity policy unless `inlinePolicy` replaces it.
+ * Permission boundaries and collected identity policies do not apply; supplied session policies still
+ * constrain the request.
+ *
+ * @param simulationRequest the virtual principal request details
+ * @param collectClient the IAM collect client to use for organization and resource-side data access
+ * @returns the normalized request and simulation result
+ */
+export async function simulateVirtualPrincipal(simulationRequest, collectClient) {
+    return simulateRequestInternal({ ...simulationRequest }, 'virtualPrincipal', collectClient);
+}
 /**
  * Simulate a collected principal accessing a resource outside the collected dataset.
  * Wildcard-only actions are unsupported.
@@ -76,7 +91,11 @@ async function simulateRequestInternal(input, variant, collectClient) {
         throw new Error(`Unable to find action details for ${simulationRequest.action}`);
     }
     const actionDetails = await iamActionDetails(service, serviceAction);
-    if (actionDetails.isWildcardOnly && variant !== 'normal') {
+    if (variant === 'virtualPrincipal' && !splitArnParts(simulationRequest.principal).accountId) {
+        throw new Error(`Virtual principal ${simulationRequest.principal} must contain an account ID.`);
+    }
+    if (actionDetails.isWildcardOnly &&
+        (variant === 'anonymous' || variant === 'externalPrincipal' || variant === 'externalResource')) {
         const variantName = variant === 'anonymous'
             ? 'Anonymous'
             : variant === 'externalPrincipal'
@@ -124,7 +143,7 @@ async function simulateRequestInternal(input, variant, collectClient) {
         ? await resolvePrincipalArnForContext(collectClient, simulationRequest.principal)
         : undefined;
     const includeResourceMetadata = variant !== 'externalResource';
-    const { contextKeys, resourceTagsAreKnown } = await createContextKeys(collectClient, simulationRequest, service, simulationRequest.customContextKeys, principalArnForContext, { includeResourceMetadata });
+    const { contextKeys, resourceTagsAreKnown } = await createContextKeys(collectClient, simulationRequest, service, simulationRequest.customContextKeys, principalArnForContext, { includePrincipalTags: requiresCollectedPrincipal, includeResourceMetadata });
     const vpcEndpointPolicy = await getVpcEndpointPolicy(collectClient, contextKeys);
     request.contextVariables = contextKeys;
     const simulation = {
@@ -138,8 +157,15 @@ async function simulateRequestInternal(input, variant, collectClient) {
         vpcEndpointPolicies: vpcEndpointPolicy ? [vpcEndpointPolicy] : undefined
     };
     await applyS3Settings(simulation, simulationRequest, variant, collectClient);
-    const strictContextKeys = makeStrictContextKeys(simulationRequest, contextKeys, resourceTagsAreKnown, isS3BucketOrObjectArn(simulationRequest.resourceArn || ''));
-    const discoveryContextKeyConstraints = strictContextKeys.map((keyName) => discoveryConstraintForStrictKey(keyName, simulationRequest));
+    const sessionTagCapability = await sessionTagCapabilityForRequest(collectClient, simulationRequest, principalArnForContext, requiresCollectedPrincipal);
+    const mutableExistingPrincipalTagKeys = mutableStoredPrincipalTagKeys(sessionTagCapability, contextKeys, simulationRequest.customContextKeys);
+    const principalTagsAreUnknown = variant === 'externalPrincipal' || variant === 'virtualPrincipal';
+    const strictContextKeys = makeStrictContextKeys(simulationRequest, contextKeys, resourceTagsAreKnown, isS3BucketOrObjectArn(simulationRequest.resourceArn || ''), principalTagsAreUnknown, sessionTagCapability, mutableExistingPrincipalTagKeys);
+    const discoveryContextKeyNames = new Set([
+        ...strictContextKeys,
+        ...mutableExistingPrincipalTagKeys
+    ]);
+    const discoveryContextKeyConstraints = [...discoveryContextKeyNames].map((keyName) => discoveryConstraintForStrictKey(keyName, simulationRequest, mutableExistingPrincipalTagKeys));
     const result = await runSimulation(simulation, {
         simulationMode: simulationRequest.simulationMode,
         discoveryContextKeyConstraints
@@ -150,8 +176,9 @@ async function simulateRequestInternal(input, variant, collectClient) {
  * Build all principal-side policy inputs for the selected simulation variant.
  *
  * Collected-principal variants prepare collected identity policies, SCPs, and permission
- * boundaries. External principals receive only a synthetic administrator identity policy, while
- * anonymous requests receive no principal-side policies.
+ * boundaries. External principals receive only a synthetic administrator identity policy, virtual
+ * principals receive a synthetic or caller-provided identity policy plus captured organization
+ * policies, and anonymous requests receive no principal-side policies.
  *
  * @param variant the simulation policy-source variant
  * @param request the normalized request
@@ -169,6 +196,26 @@ async function principalPoliciesForVariant(variant, request, collectClient) {
         };
     }
     const principalArn = request.principal;
+    if (variant === 'virtualPrincipal') {
+        const accountId = splitArnParts(principalArn).accountId;
+        if (!accountId) {
+            throw new Error(`Virtual principal ${principalArn} must contain an account ID.`);
+        }
+        const [serviceControlPolicies, principalAccountRcps] = await Promise.all([
+            collectClient.getScpHierarchyForAccount(accountId),
+            collectClient.getRcpHierarchyForAccount(accountId)
+        ]);
+        return {
+            identityPolicies: [
+                request.inlinePolicy
+                    ? { name: 'iam-lens:virtual-inline-policy', policy: request.inlinePolicy }
+                    : syntheticIdentityPolicy
+            ],
+            serviceControlPolicies,
+            permissionBoundaryPolicies: undefined,
+            principalAccountRcps
+        };
+    }
     const collectedPolicies = await getAllPoliciesForPrincipal(collectClient, principalArn);
     return {
         identityPolicies: prepareIdentityPolicies(principalArn, collectedPolicies),
@@ -266,9 +313,12 @@ async function applyS3Settings(simulation, request, variant, collectClient) {
  * @param contextKeys generated and caller-provided context values
  * @param resourceTagsAreKnown whether all resource tags are known
  * @param s3BucketOrObjectRequest whether S3 bucket tag keys apply
+ * @param principalTagsAreUnknown whether synthetic principal tag presence and values are unknown
+ * @param sessionTagCapability trust-policy-derived role session-tag capability, when applicable
+ * @param mutablePrincipalTagKeys stored PrincipalTag keys whose values are not authoritative
  * @returns strict literal keys and key patterns
  */
-function makeStrictContextKeys(request, contextKeys, resourceTagsAreKnown, s3BucketOrObjectRequest) {
+function makeStrictContextKeys(request, contextKeys, resourceTagsAreKnown, s3BucketOrObjectRequest, principalTagsAreUnknown, sessionTagCapability, mutablePrincipalTagKeys) {
     const strictContextKeys = [...knownContextKeys, ...(request.additionalStrictContextKeys ?? [])];
     if (!request.principal) {
         strictContextKeys.push(CONTEXT_KEYS.userId, CONTEXT_KEYS.assumedRoot, '/^aws:PrincipalTag\/.*/');
@@ -281,6 +331,15 @@ function makeStrictContextKeys(request, contextKeys, resourceTagsAreKnown, s3Buc
             strictContextKeys.push(CONTEXT_KEYS.assumedRoot);
         }
     }
+    if (!principalTagsAreUnknown && request.principal && isIamUserArn(request.principal)) {
+        strictContextKeys.push('/^aws:PrincipalTag\/.*/');
+    }
+    if (sessionTagCapability) {
+        const immutableTagPattern = immutablePrincipalTagPattern(sessionTagCapability);
+        if (immutableTagPattern) {
+            strictContextKeys.push(immutableTagPattern);
+        }
+    }
     if (request.action.startsWith('s3:')) {
         strictContextKeys.push('s3:DataAccessPointAccount', 's3:DataAccessPointArn');
     }
@@ -291,14 +350,43 @@ function makeStrictContextKeys(request, contextKeys, resourceTagsAreKnown, s3Buc
             strictContextKeys.push('/^s3:BucketTag\/.*/');
         }
     }
+    // There also may be other tag context keys, so add those too. Mutable role tags must not
+    // receive a strict constraint because iam-simulate merges constraints with true-winning semantics.
     for (const key of Object.keys(contextKeys)) {
-        if (key.toLowerCase().includes('tag/')) {
+        if (isTagContextKey(key) &&
+            !(principalTagsAreUnknown && isPrincipalTagContextKey(key)) &&
+            !mutablePrincipalTagKeys.has(key)) {
             strictContextKeys.push(key);
         }
     }
     return strictContextKeys;
 }
+/**
+ * Checks whether a context key's first slash-delimited namespace ends in `Tag`.
+ *
+ * @param key context-key name to inspect
+ * @returns true for tag context keys such as `aws:PrincipalTag/Department`
+ */
+function isTagContextKey(key) {
+    const slashIndex = key.indexOf('/');
+    return (slashIndex >= 3 &&
+        key
+            .slice(slashIndex - 3, slashIndex + 1)
+            .localeCompare('tag/', undefined, { sensitivity: 'base' }) === 0);
+}
 const awsSourceKeyPrefix = 'aws:source';
+const awsPrincipalTagPrefix = 'aws:principaltag/';
+/**
+ * Checks whether a context key is in the PrincipalTag namespace.
+ *
+ * @param key context-key name to inspect
+ * @returns true when the key starts with `aws:PrincipalTag/`, ignoring case
+ */
+function isPrincipalTagContextKey(key) {
+    return (key
+        .slice(0, awsPrincipalTagPrefix.length)
+        .localeCompare(awsPrincipalTagPrefix, undefined, { sensitivity: 'base' }) === 0);
+}
 const anonymousAbsentContextKeys = new Set([
     'aws:principalarn',
     'aws:principalaccount',
@@ -318,17 +406,80 @@ const anonymousAbsentContextKeys = new Set([
     '/^aws:principaltag\/.*/'
 ]);
 /**
- * Convert an iam-lens strict context key into an iam-simulate Discovery constraint.
+ * Derives role session-tag capability independently from tags stored on the role.
+ *
+ * This lookup applies only to Discovery simulations for IAM roles and assumed-role sessions. IAM
+ * user tags are handled separately as fully strict because users cannot receive role-session tags.
+ *
+ * @param collectClient the collect client used to load the canonical role trust policy
+ * @param simulationRequest the request whose principal-tag certainty is being modeled
+ * @param resolvedPrincipalArnForContext the canonical role ARN resolved for an assumed-role session
+ * @param principalIsCollected whether absent principal metadata is authoritative
+ * @returns the role's session-tag capability, or undefined when role metadata is not applicable
+ */
+async function sessionTagCapabilityForRequest(collectClient, simulationRequest, resolvedPrincipalArnForContext, principalIsCollected) {
+    if (simulationRequest.simulationMode !== 'Discovery' || !principalIsCollected) {
+        return undefined;
+    }
+    const requestPrincipal = simulationRequest.principal;
+    const roleArn = requestPrincipal && isIamRoleArn(requestPrincipal)
+        ? requestPrincipal
+        : resolvedPrincipalArnForContext;
+    if (!roleArn || !isIamRoleArn(roleArn)) {
+        return undefined;
+    }
+    const accountId = splitArnParts(roleArn).accountId;
+    if (!accountId) {
+        return undefined;
+    }
+    const trustPolicy = await collectClient.getResourcePolicyForArn(roleArn, accountId);
+    return roleSessionTagCapability(trustPolicy);
+}
+/**
+ * Finds stored role-tag values that a session may override.
+ *
+ * Stored tags determine baseline presence, while the independent trust-policy capability determines
+ * mutability. A mutable stored tag is always present, but its effective session value is unknown.
+ *
+ * @param capability the role's session-tag capability, or undefined for non-role requests
+ * @param contextKeys generated and caller-provided request context
+ * @param customContextKeys authoritative caller-provided context values
+ * @returns existing non-custom PrincipalTag context-key names whose values are mutable
+ */
+function mutableStoredPrincipalTagKeys(capability, contextKeys, customContextKeys) {
+    if (!capability || capability.type === 'none') {
+        return new Set();
+    }
+    const storedPrincipalTagKeys = Object.keys(contextKeys).filter((key) => isPrincipalTagContextKey(key) && !hasCustomContextKey(customContextKeys, key));
+    if (capability.type === 'any') {
+        return new Set(storedPrincipalTagKeys);
+    }
+    return new Set(storedPrincipalTagKeys.filter((key) => {
+        const tagKey = key.slice(awsPrincipalTagPrefix.length);
+        return roleSessionCanSetTagKey(capability, tagKey);
+    }));
+}
+/**
+ * Convert an iam-lens context key into an iam-simulate Discovery constraint.
+ *
+ * Caller-provided and explicitly strict keys remain fully authoritative. A stored PrincipalTag
+ * whose role session may override it has known presence but an unknown value. All other input keys
+ * are strict and continue through the existing special-case handling.
  *
  * @param keyName the literal context key or slash-delimited key pattern
  * @param simulationRequest the normalized request whose context certainty is modeled
+ * @param mutablePrincipalTagKeys stored PrincipalTag keys whose values are non-authoritative
  * @returns the Discovery constraint to pass to iam-simulate
  * @internal
  */
-export function discoveryConstraintForStrictKey(keyName, simulationRequest) {
-    if (hasCustomContextKey(simulationRequest.customContextKeys, keyName)) {
+export function discoveryConstraintForStrictKey(keyName, simulationRequest, mutablePrincipalTagKeys) {
+    if (hasCustomContextKey(simulationRequest.customContextKeys, keyName) ||
+        simulationRequest.additionalStrictContextKeys?.includes(keyName)) {
         return { keyName, presenceIsKnown: true, valueIsKnown: true };
     }
+    if (mutablePrincipalTagKeys?.has(keyName)) {
+        return { keyName, presenceIsKnown: true, valueIsKnown: false };
+    }
     if (simulationRequest.principal === undefined &&
         anonymousAbsentContextKeys.has(keyName.toLowerCase())) {
         return { keyName, presenceIsKnown: true, valueIsKnown: true };