Add READMEs for new credential packages

Author: mtdowling

aws/aws-config/README.md

@@ -0,0 +1,56 @@
+# AWS Config
+
+Parses AWS shared configuration files (`~/.aws/config` and `~/.aws/credentials`) and resolves credentials from profiles.
+
+## Dependency
+
+```kotlin
+dependencies {
+    implementation("software.amazon.smithy.java:aws-config:1.1.0")
+}
+```
+
+## Usage
+
+Config file-based credential resolution is wired up automatically when
+`AwsCredentialChainPlugin` is installed on a client. This module registers
+itself in the `SHARED_CONFIG` chain slot via ServiceLoader, so no additional
+code is needed beyond adding the dependency.
+
+## Programmatic config file support
+
+You can load and query config files directly:
+
+```java
+// Load and query the config file
+AwsProfileFile file = AwsProfileFile.load();
+AwsProfile profile = file.profile("default");
+String region = profile.property("region");
+
+// Resolve credentials from a profile directly
+AwsProfileCredentialsResolver resolver = AwsProfileCredentialsResolver.builder()
+    .profileName("dev")
+    .build();
+
+IdentityResult<AwsCredentialsIdentity> result = resolver.resolveIdentity(Context.empty());
+```
+
+## Supported credential sources
+
+Profiles can define credentials in multiple ways. This module handles:
+
+- **Static keys** — `aws_access_key_id` + `aws_secret_access_key`
+- **Session keys** — static keys + `aws_session_token`
+- **credential_process** — external program that outputs JSON credentials
+
+## Modular credential sources
+
+Additional sources like IMDS, AssumeRole, SSO, WebIdentity, and Login are
+detected and typed but require separate handler modules (`aws-credentials-sts`,
+`aws-credentials-sso`, etc.) to resolve. When possible, this module detects
+if you intended to use one of these providers but are missing the dependency.
+
+## Extensibility
+
+Implement `AwsConfigCredentialSourceHandler` and register via
+`META-INF/services` to handle additional source types.

aws/aws-credential-chain/README.md

@@ -0,0 +1,93 @@
+# AWS Credential Chain
+
+Assembles an ordered AWS credential provider chain from SPI-discovered
+providers. Provides the infrastructure for modular credential resolution.
+
+## Dependency
+
+```kotlin
+dependencies {
+    implementation("software.amazon.smithy.java:aws-credential-chain:1.1.0")
+}
+```
+
+## Wiring to a client
+
+### Automatic (codegen)
+
+Services modeled with `@aws.auth#sigv4` or `@aws.auth#sigv4a` automatically get
+`AwsCredentialChainPlugin` added as a default plugin during code generation.
+No manual wiring is needed: just add the provider modules you need to your
+runtime dependencies.
+
+### Manual
+
+```java
+var client = MyClient.builder()
+    .addPlugin(new AwsCredentialChainPlugin())
+    .build();
+```
+
+The plugin registers the credential chain as the client's identity resolver and
+adds an interceptor that invalidates cached credentials on auth failures
+(`ExpiredToken`, `InvalidToken`, `AuthFailure`).
+
+## Standalone usage
+
+```java
+try (AwsCredentialChain chain = AwsCredentialChain.create()) {
+    IdentityResult<AwsCredentialsIdentity> result = chain.resolveIdentity(context);
+}
+```
+
+## How it works
+
+The chain discovers `AwsCredentialProvider` implementations via ServiceLoader, 
+orders them by builtin enum slots, and tries each in order until one succeeds.
+
+## Builtin slots (in priority order)
+
+1. `CODE` — programmatic
+2. `JAVA_SYSTEM_PROPERTIES` — `aws.accessKeyId`
+3. `ENVIRONMENT` — `AWS_ACCESS_KEY_ID`
+4. `WEB_IDENTITY_TOKEN_ENV` — `AWS_WEB_IDENTITY_TOKEN_FILE` + `AWS_ROLE_ARN`
+5. `SHARED_CONFIG` — `~/.aws/config` / `~/.aws/credentials`
+6. `ECS_CONTAINER` — `AWS_CONTAINER_CREDENTIALS_FULL_URI`
+7. `EC2_INSTANCE_METADATA` — IMDS
+
+## Ordering
+
+Providers position themselves relative to builtin slots using
+`OrderingConstraint`:
+
+- `Builtin(slot)` — claims a builtin slot (one provider per slot). Only one
+  provider can claim a builtin. Not all builtins have to be claimed.
+- `Before(slot)` — inserts before the given slot's position
+- `After(slot)` — inserts after the given slot's position
+
+Before/After reference enum values only, so cycles are impossible. If the
+referenced slot has no registered provider, the custom provider is placed
+where that slot would be in enum order.
+
+## Adding a custom provider
+
+```java
+public class MyProvider implements AwsCredentialProvider {
+    @Override
+    public String name() {
+        return "MyCustomProvider";
+    }
+
+    @Override
+    public OrderingConstraint ordering() {
+        return new OrderingConstraint.After(BuiltinProvider.SHARED_CONFIG);
+    }
+
+    @Override
+    public IdentityResolver<AwsCredentialsIdentity> create(ProviderContext ctx) {
+        return new MyResolver();
+    }
+}
+```
+
+Register in `META-INF/services/software.amazon.smithy.java.aws.credentials.chain.AwsCredentialProvider`.

aws/aws-credentials-imds/README.md

@@ -0,0 +1,43 @@
+# AWS Credentials IMDS
+
+Credential provider for EC2 instances using the Instance Metadata Service
+(IMDSv2).
+
+## Dependency
+
+```kotlin
+dependencies {
+    implementation("software.amazon.smithy.java:aws-credentials-imds:1.1.0")
+}
+```
+
+## Usage
+
+No code changes are needed. The provider is discovered automatically via
+ServiceLoader and claims the `EC2_INSTANCE_METADATA` slot in the credential
+chain.
+
+## Behavior
+
+- Uses IMDSv2 exclusively (no v1 fallback)
+- Tries the extended API first (`/security-credentials-extended/`), falls back
+  to legacy on 404
+- Caches credentials with background refresh before expiration
+- Implements static stability: expired credentials are returned during outages
+- Retries with exponential backoff (3 attempts)
+
+## Configuration
+
+Configuration is checked in priority order. The first non-null value wins.
+
+    system property > env var > config file
+
+| Source | Key | Effect |
+|--------|-----|--------|
+| System property | `aws.disableEc2Metadata=true` | Disables IMDS |
+| Environment | `AWS_EC2_METADATA_DISABLED=true` | Disables IMDS |
+| Config file | `disable_ec2_metadata=true` | Disables IMDS |
+| Environment | `AWS_EC2_METADATA_SERVICE_ENDPOINT` | Overrides endpoint (e.g., for IPv6) |
+| System property | `aws.ec2InstanceProfileName` | Skips profile discovery |
+| Environment | `AWS_EC2_INSTANCE_PROFILE_NAME` | Skips profile discovery |
+| Config file | `ec2_instance_profile_name` | Skips profile discovery |