@cloud-copilot/iam-utils 0.0.1

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@cloud-copilot/iam-utils",
+  "version": "0.0.1",
+  "description": "",
+  "keywords": [
+    "aws",
+    "iam",
+    "utils"
+  ],
+  "homepage": "https://github.com/cloud-copilot/iam-utils#readme",
+  "bugs": {
+    "url": "https://github.com/cloud-copilot/iam-utils/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/cloud-copilot/iam-utils.git"
+  },
+  "license": "AGPL-3.0-or-later",
+  "author": "David Kerber <dave@cloudcopilot.io>",
+  "scripts": {
+    "build": "npx tsc -p tsconfig.cjs.json && npx tsc -p tsconfig.esm.json && ./postbuild.sh",
+    "clean": "rm -rf dist",
+    "test": "npx vitest --run --coverage",
+    "release": "npm install && npm run clean && npm run build && npm test && npm run format-check && npm publish",
+    "format": "npx prettier --write src/",
+    "format-check": "npx prettier --check src/"
+  },
+  "devDependencies": {
+    "@cloud-copilot/prettier-config": "^0.1.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.1",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.3",
+    "@types/node": "^22.5.0",
+    "@vitest/coverage-v8": "^3.0.7",
+    "semantic-release": "^24.2.1",
+    "typescript": "^5.5.4",
+    "vitest": "^3.0.7"
+  },
+  "prettier": "@cloud-copilot/prettier-config",
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "plugins": [
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "releaseRules": [
+            {
+              "type": "feat",
+              "release": "patch"
+            },
+            {
+              "type": "fix",
+              "release": "patch"
+            },
+            {
+              "breaking": true,
+              "release": "patch"
+            },
+            {
+              "type": "*",
+              "release": "patch"
+            }
+          ]
+        }
+      ],
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/changelog",
+      [
+        "@semantic-release/npm",
+        {
+          "npmPublish": true
+        }
+      ],
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "package.json",
+            "package-lock.json",
+            "CHANGELOG.md"
+          ],
+          "message": "chore(release): ${nextRelease.version} [skip ci]"
+        }
+      ],
+      [
+        "@semantic-release/github",
+        {
+          "assets": []
+        }
+      ]
+    ]
+  }
+}

package/postbuild.sh

@@ -0,0 +1,11 @@
+cat >dist/cjs/package.json <<!EOF
+{
+    "type": "commonjs"
+}
+!EOF
+
+cat >dist/esm/package.json <<!EOF
+{
+    "type": "module"
+}
+!EOF

package/src/arn.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest'
+import { ArnParts, splitArnParts } from './arn.js'
+
+const splitArnPartsTests: {
+  name: string
+  arn: string
+  expected: ArnParts
+  only?: boolean
+}[] = [
+  {
+    name: 'should split a full ARN',
+    arn: 'arn:aws:iam::123456789012:user/Development/user1',
+    expected: {
+      partition: 'aws',
+      service: 'iam',
+      region: '',
+      accountId: '123456789012',
+      resource: 'user/Development/user1',
+      resourceType: 'user',
+      resourcePath: 'Development/user1'
+    }
+  },
+  {
+    name: 'should split an S3 bucket ARN',
+    arn: 'arn:aws:s3:::my_corporate_bucket',
+    expected: {
+      partition: 'aws',
+      service: 's3',
+      region: '',
+      accountId: '',
+      resource: 'my_corporate_bucket',
+      resourceType: '',
+      resourcePath: 'my_corporate_bucket'
+    }
+  },
+  {
+    name: 'should split an S3 object ARN',
+    arn: 'arn:aws:s3:::my_corporate_bucket/my_corporate_object.txt',
+    expected: {
+      partition: 'aws',
+      service: 's3',
+      region: '',
+      accountId: '',
+      resource: 'my_corporate_bucket/my_corporate_object.txt',
+      resourceType: '',
+      resourcePath: 'my_corporate_bucket/my_corporate_object.txt'
+    }
+  },
+  {
+    name: 'should split an SNS topic ARN',
+    arn: 'arn:aws:sns:us-east-1:123456789012:MyTopic',
+    expected: {
+      partition: 'aws',
+      service: 'sns',
+      region: 'us-east-1',
+      accountId: '123456789012',
+      resource: 'MyTopic',
+      resourceType: '',
+      resourcePath: 'MyTopic'
+    }
+  },
+  {
+    name: 'should split an SQS queue ARN',
+    arn: 'arn:aws:sqs:us-east-1:123456789012:MyQueue',
+    expected: {
+      partition: 'aws',
+      service: 'sqs',
+      region: 'us-east-1',
+      accountId: '123456789012',
+      resource: 'MyQueue',
+      resourceType: '',
+      resourcePath: 'MyQueue'
+    }
+  },
+  {
+    name: 'should split a Lambda function ARN',
+    arn: 'arn:aws:lambda:us-west-2:123456789012:function:my-function',
+    expected: {
+      partition: 'aws',
+      service: 'lambda',
+      region: 'us-west-2',
+      accountId: '123456789012',
+      resource: 'function:my-function',
+      resourceType: 'function',
+      resourcePath: 'my-function'
+    }
+  },
+  {
+    name: 'rest api ARN',
+    arn: 'arn:aws:apigateway:us-east-1::/restapis/1234567890',
+    expected: {
+      partition: 'aws',
+      service: 'apigateway',
+      region: 'us-east-1',
+      accountId: '',
+      resource: '/restapis/1234567890',
+      resourceType: 'restapis',
+      resourcePath: '1234567890'
+    }
+  },
+  {
+    name: 'should split a glue root catalog ARN',
+    arn: 'arn:aws:glue:us-east-1:111111111111:catalog',
+    expected: {
+      partition: 'aws',
+      service: 'glue',
+      region: 'us-east-1',
+      accountId: '111111111111',
+      resource: 'catalog',
+      resourceType: 'catalog',
+      resourcePath: ''
+    }
+  }
+]
+
+describe('splitArnParts', () => {
+  for (const test of splitArnPartsTests) {
+    const { name, arn, expected, only } = test
+    const testFn = only ? it.only : it
+
+    testFn(name, () => {
+      const result = splitArnParts(arn)
+      expect(result).toEqual(expected)
+    })
+  }
+})

package/src/arn.ts

@@ -0,0 +1,81 @@
+export interface ArnParts {
+  partition: string | undefined
+  service: string | undefined
+  region: string | undefined
+  accountId: string | undefined
+  resource: string | undefined
+  resourceType: string | undefined
+  resourcePath: string | undefined
+}
+
+/**
+ * Split an ARN into its parts
+ *
+ * @param arn the arn to split
+ * @returns the parts of the ARN
+ */
+export function splitArnParts(arn: string): ArnParts {
+  const parts = arn.split(':')
+  const partition = parts.at(1)
+  const service = parts.at(2)!
+  const region = parts.at(3)!
+  const accountId = parts.at(4)!
+  const resource = parts.slice(5).join(':')
+  const [resourceType, resourcePath] = getResourceSegments(service, accountId, region, resource)
+
+  return {
+    partition,
+    service,
+    region,
+    accountId,
+    resource,
+    resourceType,
+    resourcePath
+  }
+}
+
+/**
+ * Get the product/id segments of the resource portion of an ARN.
+ * The first segment is the product segment and the second segment is the resource id segment.
+ * This could be split by a colon or a slash, so it checks for both. It also checks for S3 buckets/objects.
+ *
+ * @param resource The resource to get the resource segments. Must be an ARN resource.
+ * @returns a tuple with the first segment being the product segment (without the separator) and the second segment being the resource id.
+ */
+export function getResourceSegments(
+  service: string,
+  accountId: string,
+  region: string,
+  resourceString: string
+): [string, string] {
+  // This is terrible, and I hate it
+  if (
+    (service === 's3' && accountId === '' && region === '') ||
+    service === 'sns' ||
+    service === 'sqs'
+  ) {
+    return ['', resourceString]
+  }
+
+  if (resourceString.startsWith('/')) {
+    resourceString = resourceString.slice(1)
+  }
+
+  const slashIndex = resourceString.indexOf('/')
+  const colonIndex = resourceString.indexOf(':')
+
+  let splitIndex = slashIndex
+  if (slashIndex != -1 && colonIndex != -1) {
+    splitIndex = Math.min(slashIndex, colonIndex) + 1
+  } else if (slashIndex == -1 && colonIndex == -1) {
+    splitIndex = resourceString.length + 1
+  } else if (colonIndex == -1) {
+    splitIndex = slashIndex + 1
+  } else if (slashIndex == -1) {
+    splitIndex = colonIndex + 1
+  } else {
+    throw new Error(`Unable to split resource ${resourceString}`)
+  }
+
+  return [resourceString.slice(0, splitIndex - 1), resourceString.slice(splitIndex)]
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { getResourceSegments, splitArnParts, type ArnParts } from './arn'
+export {
+  convertAssumedRoleArnToRoleArn,
+  convertRoleArnToAssumedRoleArn,
+  isAssumedRoleArn,
+  isIamUserArn
+} from './principals'

package/src/principals.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from 'vitest'
+import {
+  convertAssumedRoleArnToRoleArn,
+  convertRoleArnToAssumedRoleArn,
+  isAssumedRoleArn,
+  isFederatedUserArn,
+  isIamUserArn
+} from './principals.js'
+
+describe('convertAssumedRoleArnToRoleArn', () => {
+  it('should return the role ARN from an assumed role ARN', () => {
+    //Given an assumed role ARN
+    const assumedRoleArn = 'arn:aws:sts::123456789012:assumed-role/role-name/session-name'
+
+    //When we get the role ARN from the assumed role ARN
+    const result = convertAssumedRoleArnToRoleArn(assumedRoleArn)
+
+    //Then it should return the role ARN
+    expect(result).toBe('arn:aws:iam::123456789012:role/role-name')
+  })
+
+  it('should return the role ARN from an assumed role ARN with a path', () => {
+    //Given an assumed role ARN
+    const assumedRoleArn = 'arn:aws:sts::123456789012:assumed-role/admin/global-admin/session-name'
+
+    //When we get the role ARN from the assumed role ARN
+    const result = convertAssumedRoleArnToRoleArn(assumedRoleArn)
+
+    //Then it should return the role ARN
+    expect(result).toBe('arn:aws:iam::123456789012:role/admin/global-admin')
+  })
+
+  it('should work in a different partition', () => {
+    //Given an assumed role ARN with a different partition
+    const assumedRoleArn = 'arn:aws-cn:sts::123456789012:assumed-role/role-name/session-name'
+
+    //When we get the role ARN from the assumed role ARN
+    const result = convertAssumedRoleArnToRoleArn(assumedRoleArn)
+
+    //Then it should return the role ARN
+    expect(result).toBe('arn:aws-cn:iam::123456789012:role/role-name')
+  })
+})
+
+describe('convertRoleArnToAssumedRoleArn', () => {
+  it('should return the assumed role ARN from a role ARN', () => {
+    //Given a role ARN
+    const roleArn = 'arn:aws:iam::123456789012:role/role-name'
+
+    //When we get the assumed role ARN from the role ARN
+    const result = convertRoleArnToAssumedRoleArn(roleArn, 'session-name')
+
+    //Then it should return the assumed role ARN
+    expect(result).toBe('arn:aws:sts::123456789012:assumed-role/role-name/session-name')
+  })
+
+  it('should return the assumed role ARN from a role ARN with a path', () => {
+    //Given a role ARN
+    const roleArn = 'arn:aws:iam::123456789012:role/admin/global-admin'
+
+    //When we get the assumed role ARN from the role ARN
+    const result = convertRoleArnToAssumedRoleArn(roleArn, 'session-name')
+
+    //Then it should return the assumed role ARN
+    expect(result).toBe('arn:aws:sts::123456789012:assumed-role/admin/global-admin/session-name')
+  })
+
+  it('should work with a different partition', () => {
+    //Given a role ARN with a different partition
+    const roleArn = 'arn:aws-cn:iam::123456789012:role/role-name'
+
+    //When we get the assumed role ARN from the role ARN
+    const result = convertRoleArnToAssumedRoleArn(roleArn, 'session-name')
+
+    //Then it should return the assumed role ARN
+    expect(result).toBe('arn:aws-cn:sts::123456789012:assumed-role/role-name/session-name')
+  })
+})
+
+describe('isAssumedRoleArn', () => {
+  it('should return true for assumed role ARN', () => {
+    //Given an assumed role ARN
+    const assumedRoleArn = 'arn:aws:sts::123456789012:assumed-role/role-name/session-name'
+
+    //When we check if it is an assumed role ARN
+    const result = isAssumedRoleArn(assumedRoleArn)
+
+    //Then it should return true
+    expect(result).toBe(true)
+  })
+
+  it('should return false for non-assumed role ARN', () => {
+    //Given a non-assumed role ARN
+    const userArn = 'arn:aws:iam::123456789012:user/user-name'
+
+    //When we check if it is an assumed role ARN
+    const result = isAssumedRoleArn(userArn)
+
+    //Then it should return false
+    expect(result).toBe(false)
+  })
+
+  it('should work for a different partition', () => {
+    //Given an assumed role ARN with a different partition
+    const assumedRoleArn = 'arn:aws-cn:sts::123456789012:assumed-role/role-name/session-name'
+
+    //When we check if it is an assumed role ARN
+    const result = isAssumedRoleArn(assumedRoleArn)
+
+    //Then it should return true
+    expect(result).toBe(true)
+  })
+})
+
+describe('isIamUserArn', () => {
+  it('should return true for IAM user ARN', () => {
+    //Given an IAM user ARN
+    const userArn = 'arn:aws:iam::123456789012:user/user-name'
+
+    //When we check if it is an IAM user ARN
+    const result = isIamUserArn(userArn)
+
+    //Then it should return true
+    expect(result).toBe(true)
+  })
+
+  it('should return false for non-IAM user ARN', () => {
+    //Given a non-IAM user ARN
+    const roleArn = 'arn:aws:sts::123456789012:assumed-role/role-name/session-name'
+
+    //When we check if it is an IAM user ARN
+    const result = isIamUserArn(roleArn)
+
+    //Then it should return false
+    expect(result).toBe(false)
+  })
+
+  it('should work for a different partition', () => {
+    //Given an IAM user ARN with a different partition
+    const userArn = 'arn:aws-cn:iam::123456789012:user/user-name'
+
+    //When we check if it is an IAM user ARN
+    const result = isIamUserArn(userArn)
+
+    //Then it should return true
+    expect(result).toBe(true)
+  })
+})
+
+describe('isFederatedUserArn', () => {
+  it('should return true for federated user ARN', () => {
+    //Given a federated user ARN
+    const federatedUserArn = 'arn:aws:sts::123456789012:federated-user/user-name'
+
+    //When we check if it is a federated user ARN
+    const result = isFederatedUserArn(federatedUserArn)
+
+    //Then it should return true
+    expect(result).toBe(true)
+  })
+
+  it('should return false for non-federated user ARN', () => {
+    //Given a non-federated user ARN
+    const roleArn = 'arn:aws:sts::123456789012:assumed-role/role-name/session-name'
+
+    //When we check if it is a federated user ARN
+    const result = isFederatedUserArn(roleArn)
+
+    //Then it should return false
+    expect(result).toBe(false)
+  })
+
+  it('should work for a different partition', () => {
+    //Given a federated user ARN with a different partition
+    const federatedUserArn = 'arn:aws-cn:sts::123456789012:federated-user/user-name'
+
+    //When we check if it is a federated user ARN
+    const result = isFederatedUserArn(federatedUserArn)
+
+    //Then it should return true
+    expect(result).toBe(true)
+  })
+})

package/src/principals.ts

@@ -0,0 +1,62 @@
+import { splitArnParts } from './arn.js'
+
+/**
+ * Transform an assumed role session ARN into a role ARN
+ *
+ * @param assumedRoleArn the assumed role session ARN
+ * @returns the role ARN for the assumed role session
+ */
+export function convertAssumedRoleArnToRoleArn(assumedRoleArn: string): string {
+  const arnParts = splitArnParts(assumedRoleArn)
+  const rolePathAndName = arnParts.resourcePath?.split('/').slice(0, -1).join('/')
+  return `arn:${arnParts.partition}:iam::${arnParts.accountId}:role/${rolePathAndName}`
+}
+
+/**
+ * Create an assumed role ARN from a role ARN and a session name
+ *
+ * @param roleArn the role ARN to create an assumed role ARN from
+ * @param sessionName the session name to use
+ * @returns the assumed role ARN
+ */
+export function convertRoleArnToAssumedRoleArn(roleArn: string, sessionName: string): string {
+  const arnParts = splitArnParts(roleArn)
+  const rolePathAndName = arnParts.resourcePath
+  return `arn:${arnParts.partition}:sts::${arnParts.accountId}:assumed-role/${rolePathAndName}/${sessionName}`
+}
+
+const assumedRoleArnRegex = /^arn:[a-zA-Z\-]+:sts::\d{12}:assumed-role\/.*$/
+
+/**
+ * Tests if a principal string is an assumed role ARN
+ *
+ * @param principal the principal string to test
+ * @returns true if the principal is an assumed role ARN, false otherwise
+ */
+export function isAssumedRoleArn(principal: string): boolean {
+  return assumedRoleArnRegex.test(principal)
+}
+
+const userArnRegex = /^arn:[a-zA-Z\-]+:iam::\d{12}:user\/.*$/
+
+/**
+ * Test if a principal string is an IAM user ARN
+ *
+ * @param principal the principal string to test
+ * @returns true if the principal is an IAM user ARN, false otherwise
+ */
+export function isIamUserArn(principal: string): boolean {
+  return userArnRegex.test(principal)
+}
+
+const federatedUserArnRegex = /^arn:[a-zA-Z\-]+:sts::\d{12}:federated-user\/.*$/
+
+/**
+ * Test if a principal string is a federated user ARN
+ *
+ * @param principal the principal string to test
+ * @returns true if the principal is a federated user ARN, false otherwise
+ */
+export function isFederatedUserArn(principal: string): boolean {
+  return federatedUserArnRegex.test(principal)
+}

package/tsconfig.cjs.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+
+  "include": ["src/**/*"],
+  "exclude": ["**/*.test.ts"],
+
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist/cjs",
+  }
+}

package/tsconfig.esm.json

@@ -0,0 +1,14 @@
+{
+  "extends": "./tsconfig.json",
+
+  "include": ["src/**/*"],
+  "exclude": ["**/*.test.ts"],
+
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "rootDir": "src",
+    "outDir": "dist/esm"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "es2022",
+    "outDir": "dist",
+    "rootDir": "src",
+    "sourceMap": true,
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "lib": ["es2023", "DOM"],
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": false,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": false,
+    "forceConsistentCasingInFileNames": true,
+    "paths": {
+      // workaround for: https://github.com/vitest-dev/vitest/issues/4567
+      "rollup/parseAst": ["./node_modules/rollup/dist/parseAst"]
+    }
+  },
+  "exclude": ["tests", "test", "dist", "bin", "**/bin", "**/dist", "node_modules", "cdk.out"],
+}