aws-asmr 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cc279ebf6f98696525bd333297e3d9e07f4546235685e4cc56ede2f6e5936df
-  data.tar.gz: 5e8ba9aa25320658bbe860b0733141d4bda426a75330bd52603922bb6e0274fb
+  metadata.gz: 5f82db6a4f331d524f5c56dab14452abe7e6b727e4870990fec14410eb728cdd
+  data.tar.gz: 62c1380dbe38966db335122e19e285fb1b3c6d0b3ba960c1e9d3023312d689ba
 SHA512:
-  metadata.gz: 3ac9215a9c0ddb69a23eb94e7aa30eb91b07ea2e4bdf1fe2be1f03f2ec4fdbb4890bd329432e443044c70360b4aba568f03e5294a9f311779aac95ec334273f2
-  data.tar.gz: 52d2bf0b95b0f377a2507ed9e72372edce4a6dcd1aeacc1e231558bf1f4b2b228a9798c9e6d63f54f18b02c28d77c572b405aa0272ce134aaa2417f84d76254f
+  metadata.gz: 5ce7c9d028f0e67023005ff923e663d1fa79ea32229656ace998ce56736251264644ca87e1f61615534097c633927b729a7fbaa2444e2652caaa285651ff8276
+  data.tar.gz: 0dd4c41871053793bece7cd69f82e8776f342137f2f927a07272023a39fd9e6badb13dfee37c2f308fc035ffbc5781b8972b1b1abb8efa2b175ef16272f6fc37

data/README.md

@@ -33,12 +33,14 @@ Of course you can set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` respectively
 AWS_ACCESS_KEY_ID=xxxx AWS_SECRET_ACCESS_KEY=yyyy asmr --name=arn:aws:iam::0000:role/AwesomeRole aws sts get-caller-identity
 ```
 
-To specify ARN (or alias name of assumed role), you MUST set `name` option with a form like `--name=<arn>` NOT a form like `--name <arn>`. For short version, `-n<arn>` works, `-n <arn>` doesn't. You must be wasting time for this pitfall, sorry!  
-This is due to a development circumstance. This tool is supposed to run 2 commands. One is assume_role, and the other is subsequential(this is main though) command. To safely separate options for assume_role and subsequential commands, all components of the `asmr` args must be start with `-`. Curse my programming ability!
+To specify ARN (or alias name of assumed role), set the `name` option in any of the usual forms. Option parsing stops at the first argument that is not an option (or at a literal `--`), and everything from there on is the subsequential command, including its own options such as `--filter`.
 
 ```
 asmr --name=arn:aws:iam::0000:role/AwesomeRole
+asmr --name arn:aws:iam::0000:role/AwesomeRole
 asmr -narn:aws:iam::0000:role/AwesomeRole
+asmr -n arn:aws:iam::0000:role/AwesomeRole
+asmr -n arn:aws:iam::0000:role/AwesomeRole -- aws sts get-caller-identity
 ```
 
 Of course you can set options for subsequential command.
@@ -47,10 +49,13 @@ Of course you can set options for subsequential command.
 asmr --name=arn:aws:iam::0000:role/AwesomeRole aws ec2 describe-instances --filter '[{"Name":"instance-state-name","Values":["stopped"]}]'
 ```
 
-Unfortunatelly you need quote and appropriate escape to run piped command as subsequential.
+When the subsequential command is given as several arguments, it is executed directly (no shell in between): each argument reaches the command exactly as your shell handed it to `asmr`, so quotes, spaces and `$` in arguments need no extra escaping. Note that your shell still interprets `|`, `&&` and redirects *before* `asmr` runs, so in `asmr aws s3 ls | grep foo` only `aws s3 ls` gets the credentials (which is usually what you want).
+
+To run a whole pipeline as the assumed role, pass it as a single argument; a single argument is run through `sh`, so pipes, redirects and variable expansion work inside it.
 
 ```
 asmr --name=arn:aws:iam::0000:role/AwesomeRole "aws sts get-caller-identity | grep Arn"
+asmr --name=arn:aws:iam::0000:role/AwesomeRole 'echo $AWS_ACCESS_KEY_ID'
 ```
 
 Without subsequential command, it just prints environment variables for assume_role.
@@ -95,6 +100,39 @@ Or you can specify alias name.
 asmr --name=awesome-app-staging aws sts get-caller-identity
 ```
 
+## Pin a role to a directory (`asmr local`)
+
+Following the `rbenv local` convention, you can pin an alias (or a role ARN) to a directory. `asmr local NAME` writes the name to `.asmr` in the current directory; from then on, `asmr` and `asmr-login` run there **without `--name`** assume that role instead of asking you to choose one. The nearest `.asmr` in the current directory or any of its parents wins, so pinning a project root covers its subdirectories.
+
+```
+cd ~/src/awesome-app
+asmr local awesome-app-staging   # writes ./.asmr
+asmr aws sts get-caller-identity # assumes awesome-app-staging, no prompt
+asmr-login                       # opens the console as awesome-app-staging
+```
+
+`asmr local` refuses a name that is neither an alias defined in `~/.aws-asmr/alias` nor a role ARN, the same way rbenv refuses a version that is not installed. A pin whose alias was deleted later fails with a message pointing at the `.asmr` file.
+
+```
+asmr local            # prints the name pinned in the current directory
+asmr local --unset    # removes ./.asmr
+```
+
+`--name` always takes precedence over the pin. Note that pinning is by directory, not by shell: entering a pinned directory silently switches the role, so be careful with production aliases (checking `asmr local` before a destructive command is cheap). Like `.ruby-version`, `.asmr` is yours to commit or ignore.
+
+## Session duration
+
+The lifetime of the temporary credentials (seconds, 900-43200) is set via the alias's optional `session_duration`. It is passed as `DurationSeconds` to `assume_role`, so a longer value means fewer MFA prompts: the cached credentials stay valid until they expire.
+
+```
+[my-awesome-project]
+arn = arn:aws:iam::xxxx:role/AdminRole
+profile = smcdk-prejp
+session_duration = 43200
+```
+
+When omitted, the role's default (1 hour) applies. The value must not exceed the role's *Maximum session duration* in IAM, and it cannot exceed 1 hour when the credentials used to assume the role are themselves temporary (role chaining). When STS rejects it, `asmr` retries without `session_duration` and tells you so, **except** when an MFA code was just consumed: a TOTP code cannot be reused, so `asmr` fails with guidance instead of asking you for another code. A change to `session_duration` only takes effect after the currently cached credentials expire (or after `asmr --clear`).
+
 ## Web Login (AWS Management Console)
 
 The companion command `asmr-login` opens the **AWS Management Console** in your browser as the assumed role, using the [AWS federation endpoint](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_enable-console-custom-url.html). This is handy when you want a *browser* session for a role you normally only use from the CLI.
@@ -120,14 +158,6 @@ Then `asmr-login --name=my-awesome-project` opens the console home of `ap-northe
 
 ### Session duration
 
-The console session duration (seconds, 900-43200) is set via the alias's optional `session_duration`. When omitted, it defaults to 43200 (12h).
-
-```
-[my-awesome-project]
-arn = arn:aws:iam::xxxx:role/AdminRole
-profile = smcdk-prejp
-region = ap-northeast-1
-session_duration = 3600
-```
+The console session duration is the alias's `session_duration` described above; it is sent as `SessionDuration` to the federation endpoint as well. When omitted, `asmr-login` requests 43200 (12h).
 
-Note: the requested duration must be **less than the assumed role's maximum session duration** (1 hour by default). When the federation endpoint rejects it (e.g. the role's max is shorter, or you reached the role via role chaining), `asmr-login` automatically retries *without* it, falling back to the lifetime of the temporary credentials. To get a full 12-hour console session, raise the role's *Maximum session duration* in IAM accordingly.
+Note: the requested duration must be **less than the assumed role's maximum session duration** (1 hour by default). When the federation endpoint rejects it (e.g. the role's max is shorter, or you reached the role via role chaining), `asmr-login` automatically retries *without* it, falling back to the lifetime of the temporary credentials. To get a full 12-hour console session, raise the role's *Maximum session duration* in IAM and set `session_duration = 43200`.

data/bin/asmr

@@ -2,28 +2,26 @@
 
 require "aws/asmr/cli"
 
-def run(command, shell_variables=[])
+# Runs command with the temporary credentials in its environment. The
+# credentials never go through a shell command line, so they are not visible
+# in `ps` output or shell history of the child.
+#
+#   asmr                                  # no command: print the variables
+#   asmr "aws sts get-caller-identity | grep Arn"
+#       # one argument: a shell command line, so pipes and redirects work
+#   asmr aws ec2 describe-instances --filter '[{"Name":"instance-state-name","Values":["stopped"]}]'
+#       # several arguments: executed directly, each argument passed verbatim
+def run(cache, command)
   if command.empty?
-    exec("echo \"#{shell_variables.join($/)}\"")
+    puts cache.shell_variables
   else
-    command = if command.length == 1
-      # Ex: asmr "aws sts get-caller-identity | grep Arn"
-      command
-    else
-      # Ex: asmr aws ec2 describe-instances --filter '[{"Name":"instance-state-name","Values":["stopped"]}]'
-      command.map{|plain|
-        if plain.match?(/[\"\'\ ]/)
-          quoted = plain.gsub("'"){"\\'"}
-          "'#{quoted}'"
-        else
-          plain
-        end
-      }
-    end
-    exec([*shell_variables, *command].join(' '))
+    exec(cache.environment, *command)
   end
+rescue Errno::ENOENT
+  STDERR.puts "asmr: command not found: #{command.first}"
+  exit(127)
 end
 
 Aws::ASMR::CLI.main(ARGV) do |cache, command_args, _options|
-  run(command_args, cache.shell_variables)
+  run(cache, command_args)
 end

data/bin/asmr-login

@@ -2,16 +2,11 @@
 
 require "aws/asmr/cli"
 
-# Session duration is read from the alias only (a raw, possibly empty string).
-# Returns nil to let WebLogin fall back to its default.
-def alias_session_duration(asmr_alias)
-  raw = asmr_alias&.session_duration
-  raw.to_i if raw && !raw.empty?
-end
-
+# Session duration is read from the alias only; nil lets WebLogin fall back to
+# its default.
 Aws::ASMR::CLI.main(ARGV) do |cache, _command_args, _options, asmr_alias|
   args = { region: asmr_alias&.region }
-  duration = alias_session_duration(asmr_alias)
+  duration = asmr_alias&.duration_seconds
   args[:session_duration] = duration if duration
   url = Aws::ASMR::WebLogin.signin_url(cache, **args)
   Aws::ASMR::WebLogin.open_browser(url)

data/lib/aws/asmr/alias.rb

@@ -58,7 +58,13 @@ module Aws
       end
 
       def assume_role_args
-        {external_id: external_id, role_session_name: role_session_name}.compact
+        {external_id: external_id, role_session_name: role_session_name, duration_seconds: duration_seconds}.compact
+      end
+
+      # session_duration as an Integer, or nil when unset. Used both as
+      # DurationSeconds of assume_role and as SessionDuration of the console.
+      def duration_seconds
+        session_duration.to_i if session_duration && !session_duration.empty?
       end
     end
   end

data/lib/aws/asmr/cache.rb

@@ -52,12 +52,18 @@ module Aws
         end
       end
 
-      def shell_variables
+      # Environment for a process running as the assumed role, ready for
+      # Kernel#exec / Kernel#spawn.
+      def environment
         {
-          AWS_ACCESS_KEY_ID: access_key_id,
-          AWS_SECRET_ACCESS_KEY: secret_access_key,
-          AWS_SESSION_TOKEN: session_token,
-        }.map{|k,v| "#{k}=#{v}"}
+          "AWS_ACCESS_KEY_ID" => access_key_id,
+          "AWS_SECRET_ACCESS_KEY" => secret_access_key,
+          "AWS_SESSION_TOKEN" => session_token,
+        }
+      end
+
+      def shell_variables
+        environment.map{|k,v| "#{k}=#{v}"}
       end
     end
   end

data/lib/aws/asmr/cli.rb

@@ -20,8 +20,8 @@ module Aws
       # resolved alias is nil when an ARN was given directly. Top-level errors
       # are reported here (with a backtrace under --verbose) and exit non-zero.
       def main(argv)
-        asmr_args, command_args = Options.partition(argv)
-        options = Options.parse(asmr_args)
+        options, command_args = Options.parse(argv)
+        Local.run(command_args.drop(1)) if command_args.first == "local"
 
         if options[:version]
           require "aws/asmr/version"
@@ -47,12 +47,13 @@ module Aws
         end
       end
 
-      # Resolves the role to assume (from --name/-n or an interactive alias
-      # selection) and returns [cache, asmr_alias]: a Cache holding temporary
-      # credentials (reusing a valid cache entry or performing assume_role with an
-      # MFA prompt), and the resolved Alias (nil when an ARN was given directly).
+      # Resolves the role to assume (from --name/-n, the nearest .asmr pin, or an
+      # interactive alias selection) and returns [cache, asmr_alias]: a Cache
+      # holding temporary credentials (reusing a valid cache entry or performing
+      # assume_role with an MFA prompt), and the resolved Alias (nil when an ARN
+      # was given directly).
       def resolve_credentials(options, prompt)
-        name = options[:name] || begin
+        name = options[:name] || pinned_name || begin
           alias_keys = Alias.base.keys
           if alias_keys.empty?
             STDERR.puts "Please specify --name=ARN to assume_role or make alias at #{ROOT}/alias"
@@ -80,13 +81,39 @@ module Aws
           assume_role_args = assume_role_args.merge(serial_number: serial_number, token_code: token_code)
         end
 
-        res = Aws::ASMR.assume_role(assume_role_arn, **assume_role_args)
+        res = perform_assume_role(assume_role_arn, assume_role_args, mfa: !serial_number.nil?)
         cache = Cache.new(**res.credentials.to_h)
         cache.save!(assume_role_arn)
         [cache, asmr_alias]
       end
 
-      module_function :main, :resolve_credentials
+      # Name pinned by the nearest .asmr (see Local), validated so that a stale
+      # pin fails with a clear message instead of an obscure assume_role error.
+      def pinned_name
+        name, file = Local.find
+        return nil unless name
+        Local.validate!(name, source: file)
+        name
+      end
+
+      # Calls assume_role. When DurationSeconds is rejected (the role's max
+      # session duration is shorter, or the source credentials are temporary so
+      # role chaining caps it at 1h), retries without it -- unless an MFA code
+      # was consumed, since a TOTP code cannot be reused; then it fails with
+      # guidance rather than asking for another code.
+      def perform_assume_role(arn, args, mfa:)
+        Aws::ASMR.assume_role(arn, **args)
+      rescue Aws::STS::Errors::ValidationError => e
+        raise unless args[:duration_seconds] && e.message.match?(/durationseconds/i)
+        hint = "assume_role with DurationSeconds=#{args[:duration_seconds]} was rejected: #{e.message}"
+        if mfa
+          raise "#{hint}\nLower session_duration in the alias (or raise the role's maximum session duration) and try again."
+        end
+        STDERR.puts "#{hint} Retrying without DurationSeconds..."
+        Aws::ASMR.assume_role(arn, **args.reject { |k, _| k == :duration_seconds })
+      end
+
+      module_function :main, :resolve_credentials, :pinned_name, :perform_assume_role
     end
   end
 end

data/lib/aws/asmr/local.rb

@@ -0,0 +1,79 @@
+require 'pathname'
+require 'aws/asmr'
+
+module Aws
+  module ASMR
+    # Per-directory pinning of the role to assume, modelled after `rbenv local`.
+    #
+    #   asmr local NAME      # write NAME (alias or ARN) to ./.asmr
+    #   asmr local           # print the name pinned in the current directory
+    #   asmr local --unset   # remove ./.asmr
+    #
+    # When asmr runs without --name, the nearest .asmr found in the current
+    # directory or any of its parents decides the role, so the interactive
+    # alias selection is skipped.
+    module Local
+      FILE_NAME = ".asmr"
+      ARN_PATTERN = %r{\Aarn:aws[\w-]*:iam::\d{12}:role/}
+
+      # Runs the `local` subcommand with its remaining args and exits.
+      def run(args)
+        if args.empty?
+          name = read(Dir.pwd)
+          abort "asmr: no local role configured for this directory" unless name
+          puts name
+        elsif args == ["--unset"]
+          unset(Dir.pwd)
+        elsif args.length == 1 && !args.first.start_with?('-')
+          write(args.first, Dir.pwd)
+        else
+          abort "Usage: asmr local [NAME|--unset]"
+        end
+        exit(0)
+      rescue RuntimeError => e
+        abort e.message
+      end
+
+      def path(dir)
+        File.join(dir, FILE_NAME)
+      end
+
+      # Name pinned exactly in dir (first non-empty, non-comment line), or nil.
+      def read(dir)
+        file = path(dir)
+        return nil unless File.file?(file)
+        File.readlines(file).map(&:strip).find { |l| !l.empty? && !l.start_with?('#') }
+      end
+
+      # Walks up from dir to the filesystem root and returns [name, file] of the
+      # nearest .asmr, or nil when none is found.
+      def find(dir = Dir.pwd)
+        Pathname.new(dir).expand_path.ascend do |d|
+          name = read(d.to_s)
+          return [name, path(d.to_s)] if name
+        end
+        nil
+      end
+
+      def write(name, dir)
+        validate!(name)
+        File.write(path(dir), "#{name}\n")
+      end
+
+      def unset(dir)
+        file = path(dir)
+        File.delete(file) if File.exist?(file)
+      end
+
+      # A name must be a defined alias or a role ARN, the same way rbenv refuses
+      # to pin a version that is not installed.
+      def validate!(name, source: nil)
+        return if Alias.get(name) || name.match?(ARN_PATTERN)
+        where = source ? " (pinned at #{source})" : ""
+        raise "asmr: '#{name}'#{where} is neither an alias defined at #{Alias::PATH} nor a role ARN"
+      end
+
+      module_function :run, :path, :read, :find, :write, :unset, :validate!
+    end
+  end
+end

data/lib/aws/asmr/options.rb

@@ -3,27 +3,24 @@ require "aws/asmr"
 
 module Aws::ASMR
   module Options
-    def partition(args)
-      _idx, asmr_args, command_args = args.reduce([1, [], []]) do |acc,i|
-        idx, _, _ = acc
-        unless i.start_with?('-')
-          idx = 2
-          acc[0] = idx
-        end
-        acc[idx] << i
-        acc
-      end
-      [asmr_args, command_args]
-    end
-
-    def parse(args)
+    # Parses asmr's own options from the head of argv and returns
+    # [options, command_args]. Parsing stops at the first non-option argument
+    # (or after a literal "--"), so anything from there on -- including
+    # arguments like --filter that start with "-" -- belongs to the command:
+    #
+    #   asmr --name=foo aws ec2 describe-instances --filter '...'
+    #   asmr --name foo aws sts get-caller-identity
+    #   asmr -n foo -- aws sts get-caller-identity
+    def parse(argv)
       options = {}
+      command_args = argv.dup
       OptionParser.new do |opts|
         # opts.banner = "Usage: asmr [options]"
         opts.banner = <<~EOS
           You can use ALIAS to shortcut name input by setting it at #{Aws::ASMR::ROOT}/alias
 
-          Usage: asmr [options] [command] [arg...]
+          Usage: asmr [options] [--] [command] [arg...]
+                 asmr local [NAME|--unset]   Pin NAME (alias or ARN) to the current directory
         EOS
 
         opts.on("-nNAME", "--name=NAME", "Name to perform assume role with ARN or ALIAS") do |name|
@@ -42,14 +39,11 @@ module Aws::ASMR
         end
         opts.on("--clear", "Clear cache") do
           options[:clear] = true
-          # require "aws/asmr/version"
-          # puts Aws::ASMR::VERSION
-          # exit(0)
         end
-      end.parse(args)
-      options
+      end.order!(command_args)
+      [options, command_args]
     end
 
-    module_function :partition, :parse
+    module_function :parse
   end
 end

data/lib/aws/asmr/version.rb

@@ -1,5 +1,5 @@
 module Aws
   module ASMR
-    VERSION = "0.0.5"
+    VERSION = "0.0.7"
   end
 end

data/lib/aws/asmr.rb

@@ -34,4 +34,5 @@ end
 
 require 'aws/asmr/cache'
 require 'aws/asmr/alias'
+require 'aws/asmr/local'
 require 'aws/asmr/web_login'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-asmr
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.7
 platform: ruby
 authors:
 - metheglin
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-04 00:00:00.000000000 Z
+date: 2026-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -81,6 +81,7 @@ files:
 - lib/aws/asmr/alias.rb
 - lib/aws/asmr/cache.rb
 - lib/aws/asmr/cli.rb
+- lib/aws/asmr/local.rb
 - lib/aws/asmr/options.rb
 - lib/aws/asmr/prompt.rb
 - lib/aws/asmr/version.rb