aws-iam-language-server 0.0.13 → 0.0.15

package/src/handlers/hover/principal-typed-value.js

@@ -0,0 +1,118 @@
+import { MarkupKind } from 'vscode-languageserver';
+import { ServiceReference } from "../../lib/iam-policy/reference/services.js";
+export function handlePrincipalTypedValueHover(location) {
+    if (location.value === '*') {
+        return {
+            range: location.range,
+            contents: {
+                kind: MarkupKind.Markdown,
+                value: '**All principals** of this type.',
+            },
+        };
+    }
+    const principalType = location.principalType;
+    if (principalType === 'Service') {
+        const principals = ServiceReference.getServicePrincipals();
+        if (principals.includes(location.value)) {
+            const serviceName = location.value.split('.')[0];
+            return {
+                range: location.range,
+                contents: {
+                    kind: MarkupKind.Markdown,
+                    value: `**AWS service principal**\n\n\`${location.value}\` — allows the \`${serviceName}\` service to assume this role or access this resource.`,
+                },
+            };
+        }
+    }
+    if (principalType === 'AWS') {
+        if (/^\d{12}$/.test(location.value)) {
+            return {
+                range: location.range,
+                contents: {
+                    kind: MarkupKind.Markdown,
+                    value: `**AWS account**\n\nGrants access to the root user and all IAM identities in account \`${location.value}\`.`,
+                },
+            };
+        }
+        if (location.value.startsWith('arn:')) {
+            const parts = location.value.split(':');
+            const resource = parts.slice(5).join(':');
+            if (resource.startsWith('root')) {
+                return {
+                    range: location.range,
+                    contents: {
+                        kind: MarkupKind.Markdown,
+                        value: `**AWS account root user**\n\nGrants access to the root user of this account. Equivalent to specifying the account ID.`,
+                    },
+                };
+            }
+            if (resource.startsWith('role/')) {
+                return {
+                    range: location.range,
+                    contents: {
+                        kind: MarkupKind.Markdown,
+                        value: `**IAM role**\n\n\`${resource}\`\n\nAny identity that assumes this role will have the permissions granted by this statement.`,
+                    },
+                };
+            }
+            if (resource.startsWith('user/')) {
+                return {
+                    range: location.range,
+                    contents: {
+                        kind: MarkupKind.Markdown,
+                        value: `**IAM user**\n\n\`${resource}\``,
+                    },
+                };
+            }
+            if (resource.startsWith('assumed-role/')) {
+                return {
+                    range: location.range,
+                    contents: {
+                        kind: MarkupKind.Markdown,
+                        value: `**Assumed role session**\n\n\`${resource}\``,
+                    },
+                };
+            }
+        }
+    }
+    if (principalType === 'Federated') {
+        if (location.value.startsWith('arn:')) {
+            const resource = location.value.split(':').slice(5).join(':');
+            if (resource.startsWith('oidc-provider/')) {
+                return {
+                    range: location.range,
+                    contents: {
+                        kind: MarkupKind.Markdown,
+                        value: `**OIDC identity provider**\n\n\`${resource}\``,
+                    },
+                };
+            }
+            if (resource.startsWith('saml-provider/')) {
+                return {
+                    range: location.range,
+                    contents: {
+                        kind: MarkupKind.Markdown,
+                        value: `**SAML identity provider**\n\n\`${resource}\``,
+                    },
+                };
+            }
+        }
+        const knownProviders = {
+            'cognito-identity.amazonaws.com': 'Amazon Cognito identity pool',
+            'www.amazon.com': 'Login with Amazon',
+            'accounts.google.com': 'Google',
+            'graph.facebook.com': 'Facebook',
+        };
+        const description = knownProviders[location.value];
+        if (description) {
+            return {
+                range: location.range,
+                contents: {
+                    kind: MarkupKind.Markdown,
+                    value: `**Federated identity provider**\n\n${description}`,
+                },
+            };
+        }
+    }
+    return null;
+}

package/src/handlers/hover/principal-value.d.ts

@@ -0,0 +1,3 @@
+import { type Hover } from 'vscode-languageserver';
+import type { PrincipalValueLocation } from '../../lib/iam-policy/location.ts';
+export declare function handlePrincipalValueHover(location: PrincipalValueLocation): Hover | null;

package/src/handlers/hover/principal-value.js

@@ -0,0 +1,13 @@
+import { MarkupKind } from 'vscode-languageserver';
+export function handlePrincipalValueHover(location) {
+    if (location.value === '*') {
+        return {
+            range: location.range,
+            contents: {
+                kind: MarkupKind.Markdown,
+                value: '**Public (unauthenticated) access**\n\nMatches all principals, including anonymous users.\n\n> **Warning:** Combining `"Principal": "*"` with `"Effect": "Allow"` grants public access. Always scope with a `Condition` element unless public access is intended.',
+            },
+        };
+    }
+    return null;
+}

package/src/handlers/hover/resource-value.d.ts

@@ -0,0 +1,3 @@
+import { type Hover } from 'vscode-languageserver';
+import type { ResourceValueLocation } from '../../lib/iam-policy/location.ts';
+export declare function handleResourceValueHover(location: ResourceValueLocation): Hover | null;

package/src/handlers/hover/resource-value.js

@@ -0,0 +1,45 @@
+import { MarkupKind } from 'vscode-languageserver';
+import { parseArn } from "../../lib/iam-policy/arn.js";
+import { ServiceReference } from "../../lib/iam-policy/reference/services.js";
+export function handleResourceValueHover(location) {
+    if (location.value === '*') {
+        return {
+            range: location.range,
+            contents: {
+                kind: MarkupKind.Markdown,
+                value: 'Matches **all resources**.\n\nSome actions do not support resource-level permissions and require `"Resource": "*"`.',
+            },
+        };
+    }
+    const parsed = parseArn(location.value);
+    if (!parsed)
+        return null;
+    const resources = ServiceReference.getResources(parsed);
+    if (resources.length === 0)
+        return null;
+    const lines = [];
+    for (let i = 0; i < resources.length; i++) {
+        lines.push(`**${parsed.service} ${resources[i].name}**`);
+        if (resources[i].arnFormats.length > 0) {
+            lines.push('\n**ARNs**');
+            for (const format of resources[i].arnFormats) {
+                lines.push(`- \`${format}\``);
+            }
+        }
+        if (resources[i].conditionKeys.length > 0) {
+            lines.push('\n**Condition keys**');
+            for (const key of resources[i].conditionKeys) {
+                lines.push(`- \`${key}\``);
+            }
+        }
+        if (i + 1 !== resources.length)
+            lines.push('\n---\n');
+    }
+    return {
+        range: location.range,
+        contents: {
+            kind: MarkupKind.Markdown,
+            value: lines.join('\n'),
+        },
+    };
+}

package/src/handlers/hover/statement-block.d.ts

@@ -0,0 +1,3 @@
+import { type Hover } from 'vscode-languageserver';
+import type { StatementBlockLocation } from '../../lib/iam-policy/location.ts';
+export declare function handleStatementBlockHover(location: StatementBlockLocation): Hover | null;

package/src/handlers/hover/statement-block.js

@@ -0,0 +1,14 @@
+import { MarkupKind } from 'vscode-languageserver';
+import { findHclElement } from "../completion/statement-block.js";
+export function handleStatementBlockHover(location) {
+    const element = findHclElement(location.value);
+    if (!element)
+        return null;
+    return {
+        range: location.range,
+        contents: {
+            kind: MarkupKind.Markdown,
+            value: element.description,
+        },
+    };
+}

package/src/handlers/hover/statement-key.d.ts

@@ -0,0 +1,3 @@
+import { type Connection, type Hover } from 'vscode-languageserver';
+import type { StatementKeyLocation } from '../../lib/iam-policy/location.ts';
+export declare function handleStatementKeyHover(_connection: Connection, location: StatementKeyLocation): Hover | null;

package/src/handlers/hover/statement-key.js

@@ -0,0 +1,14 @@
+import { MarkupKind } from 'vscode-languageserver';
+import { StatementKeys } from "../../lib/iam-policy/statement-keys.js";
+export function handleStatementKeyHover(_connection, location) {
+    const statementKey = StatementKeys[location.value];
+    if (!statementKey)
+        return null;
+    return {
+        range: location.range,
+        contents: {
+            kind: MarkupKind.Markdown,
+            value: statementKey.description,
+        },
+    };
+}

package/src/lib/iam-policy/arn.d.ts

@@ -0,0 +1,17 @@
+export type ArnParts = {
+    partition: string;
+    service: string;
+    region: string;
+    account: string;
+    resource: string;
+};
+/**
+ * Parse an ARN string into its structural components.
+ * Returns null if the string is not a valid ARN structure (fewer than 6 colon-separated segments).
+ * Everything after the 5th colon is treated as the resource portion.
+ */
+export declare function parseArn(arn: string): ArnParts | null;
+/**
+ * Check if a parsed user ARN matches a parsed template ARN.
+ */
+export declare function arnMatches(userArn: ArnParts, templateArn: ArnParts): boolean;

package/src/lib/iam-policy/arn.js

@@ -0,0 +1,77 @@
+/**
+ * Parse an ARN string into its structural components.
+ * Returns null if the string is not a valid ARN structure (fewer than 6 colon-separated segments).
+ * Everything after the 5th colon is treated as the resource portion.
+ */
+export function parseArn(arn) {
+    const segments = arn.split(':');
+    if (segments.length < 6)
+        return null;
+    if (segments[0] !== 'arn')
+        return null;
+    return {
+        partition: segments[1],
+        service: segments[2],
+        region: segments[3],
+        account: segments[4],
+        resource: segments.slice(5).join(':'),
+    };
+}
+const placeholderPattern = /\$\{[^}]+\}/;
+/**
+ * Check if two ARN tokens match. A token matches if:
+ * - Either is a wildcard (`*`) or contains `?`
+ * - Either is a placeholder (`${...}`)
+ * - Both are empty (valid for region/account in some ARNs)
+ * - They are literally equal
+ */
+function tokensMatch(a, b) {
+    if (a === b)
+        return true;
+    if (a === '*' || b === '*')
+        return true;
+    if (a.includes('?') || b.includes('?'))
+        return true;
+    // Placeholders expect a value — don't match empty strings
+    if (a !== '' && b !== '' && (placeholderPattern.test(a) || placeholderPattern.test(b)))
+        return true;
+    return false;
+}
+/**
+ * Tokenize a resource string by splitting on both `:` and `/` delimiters.
+ * Preserves the delimiter as a separate token so structural comparison
+ * handles both `function:name` and `role/name` patterns.
+ */
+function tokenizeResource(resource) {
+    return resource.split(/(?<=[:\/])|(?=[:\/])/);
+}
+/**
+ * Check if the resource portion of a user ARN matches a template resource pattern.
+ * Splits on `:` and `/` and compares tokens positionally.
+ */
+function resourceMatches(userResource, templateResource) {
+    const userTokens = tokenizeResource(userResource);
+    const templateTokens = tokenizeResource(templateResource);
+    if (userTokens.length !== templateTokens.length) {
+        // A trailing `*` in the user ARN can match multiple template tokens
+        if (userTokens.length < templateTokens.length && userTokens[userTokens.length - 1] === '*') {
+            return userTokens.slice(0, -1).every((token, i) => tokensMatch(token, templateTokens[i]));
+        }
+        return false;
+    }
+    return userTokens.every((token, i) => tokensMatch(token, templateTokens[i]));
+}
+/**
+ * Check if a parsed user ARN matches a parsed template ARN.
+ */
+export function arnMatches(userArn, templateArn) {
+    if (!tokensMatch(userArn.partition, templateArn.partition))
+        return false;
+    if (!tokensMatch(userArn.service, templateArn.service))
+        return false;
+    if (!tokensMatch(userArn.region, templateArn.region))
+        return false;
+    if (!tokensMatch(userArn.account, templateArn.account))
+        return false;
+    return resourceMatches(userArn.resource, templateArn.resource);
+}

package/src/lib/iam-policy/location.d.ts

@@ -1,68 +1,98 @@
-import type { CursorContext } from '../treesitter/base.ts';
+import type { CursorContext, Range } from '../treesitter/base.ts';
 export type StatementKeyLocation = {
     type: 'statement-key';
     partial: string;
+    value: string;
+    range?: Range;
 };
 export type StatementBlockLocation = {
     type: 'statement-block';
     partial: string;
+    value: string;
+    range?: Range;
 };
 export type EffectValueLocation = {
     type: 'effect-value';
     partial: string;
+    value: string;
+    range?: Range;
 };
 export type ActionValueLocation = {
     type: 'action-value';
     partial: string;
+    value: string;
+    range?: Range;
 };
 export type ResourceValueLocation = {
     type: 'resource-value';
     partial: string;
+    value: string;
+    range?: Range;
 };
 export type PrincipalValueLocation = {
     type: 'principal-value';
     partial: string;
+    value: string;
+    range?: Range;
 };
 export type PrincipalTypeLocation = {
     type: 'principal-type';
     partial: string;
+    value: string;
+    range?: Range;
 };
 export type PrincipalBlockLocation = {
     type: 'principal-block';
     partial: string;
+    value: string;
+    range?: Range;
 };
 export type PrincipalBlockTypeLocation = {
     type: 'principal-block-type';
     partial: string;
+    value: string;
+    range?: Range;
 };
 export type PrincipalBlockIdentifierLocation = {
     type: 'principal-block-identifier';
     principalType: string | null;
     partial: string;
+    value: string;
+    range?: Range;
 };
 export type PrincipalTypedValueLocation = {
     type: 'principal-typed-value';
     principalType: string;
     partial: string;
+    value: string;
+    range?: Range;
 };
 export type ConditionBlockLocation = {
     type: 'condition-block';
     partial: string;
+    value: string;
+    range?: Range;
 };
 export type ConditionOperatorLocation = {
     type: 'condition-operator';
     partial: string;
+    value: string;
+    range?: Range;
 };
 export type ConditionKeyLocation = {
     type: 'condition-key';
     operator: string;
     partial: string;
+    value: string;
+    range?: Range;
 };
 export type ConditionValueLocation = {
     type: 'condition-value';
     operator: string;
     key: string;
     partial: string;
+    value: string;
+    range?: Range;
 };
 export type UnknownLocation = {
     type: 'unknown';

package/src/lib/iam-policy/location.js

@@ -16,66 +16,103 @@ export function resolvePolicyLocation(context) {
     const statementKey = isHclBlock ? (snakeToPascal[keys[0]] ?? keys[0]) : keys[0];
     if (keys.length === 0 && context.role === 'key') {
         if (isHclBlock)
-            return { type: 'statement-block', partial: context.partial };
-        return { type: 'statement-key', partial: context.partial };
+            return { type: 'statement-block', partial: context.partial, value: context.value, range: context.range };
+        return { type: 'statement-key', partial: context.partial, value: context.value, range: context.range };
     }
     if (keys.length === 1 && context.role === 'value') {
         if (statementKey === 'Effect')
-            return { type: 'effect-value', partial: context.partial };
+            return { type: 'effect-value', partial: context.partial, value: context.value, range: context.range };
         if (statementKey === 'Action' || statementKey === 'NotAction')
-            return { type: 'action-value', partial: context.partial };
+            return { type: 'action-value', partial: context.partial, value: context.value, range: context.range };
         if (statementKey === 'Resource' || statementKey === 'NotResource')
-            return { type: 'resource-value', partial: context.partial };
+            return { type: 'resource-value', partial: context.partial, value: context.value, range: context.range };
         if (statementKey === 'Principal' || statementKey === 'NotPrincipal')
-            return { type: 'principal-value', partial: context.partial };
+            return { type: 'principal-value', partial: context.partial, value: context.value, range: context.range };
         if (statementKey === 'Condition')
-            return { type: 'condition-operator', partial: context.partial };
+            return { type: 'condition-operator', partial: context.partial, value: context.value, range: context.range };
     }
     if (keys.length === 1 && context.role === 'key') {
         if (statementKey === 'Principal' || statementKey === 'NotPrincipal') {
             if (isHclBlock) {
-                return { type: 'principal-block', partial: context.partial };
+                return { type: 'principal-block', partial: context.partial, value: context.value, range: context.range };
             }
-            return { type: 'principal-type', partial: context.partial };
+            return { type: 'principal-type', partial: context.partial, value: context.value, range: context.range };
         }
         if (statementKey === 'Condition') {
             if (isHclBlock)
-                return { type: 'condition-block', partial: context.partial };
-            return { type: 'condition-operator', partial: context.partial };
+                return { type: 'condition-block', partial: context.partial, value: context.value, range: context.range };
+            return { type: 'condition-operator', partial: context.partial, value: context.value, range: context.range };
         }
     }
     if ((keys.length === 2 || keys.length === 3) && context.role === 'value') {
         if (statementKey === 'Principal' || statementKey === 'NotPrincipal') {
             if (isHclBlock && keys[1] === 'type') {
-                return { type: 'principal-block-type', partial: context.partial };
+                return { type: 'principal-block-type', partial: context.partial, value: context.value, range: context.range };
             }
             if (isHclBlock && keys[1] === 'identifiers') {
-                return { type: 'principal-block-identifier', principalType: keys[2] ?? null, partial: context.partial };
+                return {
+                    type: 'principal-block-identifier',
+                    principalType: keys[2] ?? null,
+                    partial: context.partial,
+                    value: context.value,
+                    range: context.range,
+                };
             }
             if (keys.length === 2) {
-                return { type: 'principal-typed-value', principalType: keys[1], partial: context.partial };
+                return {
+                    type: 'principal-typed-value',
+                    principalType: keys[1],
+                    partial: context.partial,
+                    value: context.value,
+                    range: context.range,
+                };
             }
         }
     }
     if (keys.length === 2 && context.role === 'value') {
         if (statementKey === 'Condition' && isHclBlock && keys[1] === 'test') {
-            return { type: 'condition-operator', partial: context.partial };
+            return { type: 'condition-operator', partial: context.partial, value: context.value, range: context.range };
         }
         if (statementKey === 'Condition' && isHclBlock && keys[1] === 'variable') {
-            return { type: 'condition-key', operator: '', partial: context.partial };
+            return {
+                type: 'condition-key',
+                operator: '',
+                partial: context.partial,
+                value: context.value,
+                range: context.range,
+            };
         }
         if (statementKey === 'Condition' && !isHclBlock) {
-            return { type: 'condition-key', operator: keys[1], partial: context.partial };
+            return {
+                type: 'condition-key',
+                operator: keys[1],
+                partial: context.partial,
+                value: context.value,
+                range: context.range,
+            };
         }
     }
     if (keys.length === 2 && context.role === 'key') {
         if (statementKey === 'Condition') {
-            return { type: 'condition-key', operator: keys[1], partial: context.partial };
+            return {
+                type: 'condition-key',
+                operator: keys[1],
+                partial: context.partial,
+                value: context.value,
+                range: context.range,
+            };
         }
     }
     if (keys.length === 3 && context.role === 'value') {
         if (statementKey === 'Condition') {
-            return { type: 'condition-value', operator: keys[1], key: keys[2], partial: context.partial };
+            return {
+                type: 'condition-value',
+                operator: keys[1],
+                key: keys[2],
+                partial: context.partial,
+                value: context.value,
+                range: context.range,
+            };
         }
     }
     return { type: 'unknown' };

package/src/lib/iam-policy/reference/services.d.ts

@@ -1,8 +1,9 @@
-import type { Action, ConditionKey, GlobalConditionKey, ServiceData } from './types.ts';
+import { type ArnParts } from '../arn.ts';
+import type { Action, ConditionKey, GlobalConditionKey, ResourceDef, ServiceData } from './types.ts';
 export declare class ServiceReference {
     #private;
-    static getServiceData(service: string): ServiceData;
-    static getServicePrincipals(): string[];
+    static getServiceData(service: string): ServiceData | undefined;
+    static getServicePrincipals(): Array<string>;
     static getAllActions(): Array<string>;
     static getAllServices(): Array<string>;
     static getActionsForService(service: string): Array<Action>;
@@ -13,6 +14,7 @@ export declare class ServiceReference {
     static getGlobalConditionKeys(): Array<GlobalConditionKey>;
     static getAction(action: string): Action | undefined;
     static getConditionKey(service: string, keyName: string): ConditionKey | undefined;
+    static getResources(arn: ArnParts): ResourceDef[];
     static getResourcesForActions(actions: string[]): Map<string, {
         service: string;
         name: string;