Light, fluffy, and always free - The AWS Local Emulator alternative
fix(iam): route long-term access keys to owning accounts (#2319)
Saatvik Arya02898cf5e2d3
diff --git a/docs/configuration/advanced/application-yml.md b/docs/configuration/advanced/application-yml.mdindex 58bcfa49fd..4dac5fddbe 100644--- a/docs/configuration/advanced/application-yml.md+++ b/docs/configuration/advanced/application-yml.md@@ -87,7 +87,7 @@ floci:# - localhost.localstack.cloudauth:- validate-signatures: false # Set to true to enforce AWS SigV4 validation+ validate-signatures: false # Set to true to verify S3 presigned URL signaturespresign-secret: local-emulator-secret # HMAC secret for S3 pre-signed URL verificationtls:diff --git a/docs/configuration/docker-compose.md b/docs/configuration/docker-compose.mdindex 5672e6627b..42b9a9259d 100644--- a/docs/configuration/docker-compose.md+++ b/docs/configuration/docker-compose.md@@ -173,7 +173,7 @@ The most frequently set variables when running Floci as a Docker image:| `FLOCI_STORAGE_MODE` | `memory` | `memory`, `persistent`, `hybrid`, or `wal` || `FLOCI_STORAGE_PERSISTENT_PATH` | `./data` | Directory for persistent storage || `FLOCI_SERVICES_DOCKER_NETWORK` | _(none)_ | Docker network for spawned containers (Lambda, ElastiCache, RDS, OpenSearch, MSK) |-| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | Verify AWS request signatures |+| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | Verify S3 presigned URL signatures || `FLOCI_SERVICES_LAMBDA_EPHEMERAL` | `false` | Remove Lambda containers after each invocation |For the complete list of every `FLOCI_*` variable, see [Environment Variables Reference](./environment-variables.md).diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.mdindex f4ef6860fe..c3deefaf33 100644--- a/docs/configuration/environment-variables.md+++ b/docs/configuration/environment-variables.md@@ -22,7 +22,7 @@ Floci is configured exclusively through environment variables. Every option belo| Variable | Default | Description ||---|---|---|-| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | When `true`, verifies AWS Signature V4 on every request. Leave `false` for local development |+| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | When `true`, verifies S3 presigned URL signatures || `FLOCI_AUTH_PRESIGN_SECRET` | `local-emulator-secret` | Secret used to sign and verify pre-signed URLs |## Browser CORSdiff --git a/docs/configuration/multi-account.md b/docs/configuration/multi-account.mdindex ff4fc7097f..215d984b0b 100644--- a/docs/configuration/multi-account.md+++ b/docs/configuration/multi-account.md@@ -4,10 +4,12 @@ Floci supports full per-account resource isolation out of the box. Resources cre## How It Works-Every incoming request carries an AWS SigV4 `Authorization` header. Floci reads the **Access Key ID** (AKID) from that header and applies one simple rule:+Every incoming request carries an AWS SigV4 `Authorization` header. Floci reads the **Access Key ID** (AKID) from that header and resolves the account in this order:-> **If the AKID is exactly 12 digits, it is used as the account ID.**-> Any other key format (e.g. `AKIAIOSFODNN7EXAMPLE`) falls back to `FLOCI_DEFAULT_ACCOUNT_ID`.+1. An exactly 12-digit AKID is used directly as the account ID.+2. An active long-term IAM access key resolves to the account that owns it.+3. A live STS temporary credential resolves to its recorded account.+4. Any other key falls back to `FLOCI_DEFAULT_ACCOUNT_ID`.```Authorization: AWS4-HMAC-SHA256 Credential=111111111111/20260510/us-east-1/sqs/aws4_request, ...@@ -20,6 +22,12 @@ Once the account ID is determined, every storage read and write is transparently!!! note "Same convention as LocalStack"This 12-digit AKID → account ID rule matches LocalStack's multi-account behavior, so existing multi-account test setups work without changes.+## Long-Term IAM Credentials++Active access keys created through IAM route requests back to the account that owns the key. This lets a client keep using its generated `AKIA…` credentials instead of replacing the access key ID with a synthetic 12-digit account ID.++Account selection is AKID-based and is not proof that the caller possesses the corresponding secret. This extends Floci's existing local-emulator trust model for 12-digit AKIDs; do not treat account namespaces as a security boundary between mutually untrusted clients.+## Temporary Credentials (AssumeRole)STS temporary credentials are also routed to the correct account. When you call `AssumeRole` (or `AssumeRoleWithWebIdentity`, `AssumeRoleWithSAML`, `GetFederationToken`), Floci issues a temporary `ASIA…` access key and remembers which account it belongs to:@@ -33,11 +41,11 @@ Account 111111111111 ──AssumeRole arn:aws:iam::222222222222:role/Deployer─ASIA… temp key ──CreateTable orders──▶ stored as 222222222222/...::orders ◀──┘```-This makes the cross-account `AssumeRole`-then-provision pattern (e.g. CloudFormation deploying into a target account) work locally exactly as it does in AWS. Resolution precedence is: **12-digit AKID → account ID; otherwise temporary-session lookup → `FLOCI_DEFAULT_ACCOUNT_ID`.**+This makes the cross-account `AssumeRole`-then-provision pattern (e.g. CloudFormation deploying into a target account) work locally exactly as it does in AWS.## Default Behavior (Single Account)-If you use any non-12-digit credentials (e.g. `test`, `AKIA…`), all requests resolve to the default account ID:+If a credential is not a 12-digit account ID, an active IAM access key, or a live STS session (for example, `test`), requests resolve to the default account ID:```bashFLOCI_DEFAULT_ACCOUNT_ID=000000000000 # default@@ -151,16 +159,16 @@ Background workers (Lambda event-source pollers, DynamoDB TTL sweeper, MSK readi## Signature Validation-By default Floci **does not** validate SigV4 signatures — only the access key ID matters for account resolution. The secret access key can be any non-empty string.+Floci does not currently perform general SigV4 validation for `Authorization` headers. Only the access key ID matters for account resolution, so the secret access key can be any non-empty string.-To enforce real signature validation:+`FLOCI_AUTH_VALIDATE_SIGNATURES` currently applies only to S3 presigned URL validation. It does not authenticate general service requests or protect IAM and STS account routing. To validate S3 presigned URLs:```bashFLOCI_AUTH_VALIDATE_SIGNATURES=trueFLOCI_AUTH_PRESIGN_SECRET=your-secret # for pre-signed URL verification```-When `validate-signatures` is `false` (the default), account isolation still works correctly — the AKID is extracted from the `Authorization` header regardless of whether the signature itself is verified.+When `validate-signatures` is `false` (the default), S3 presigned URL signatures are not verified. Account routing remains AKID-based regardless of this setting.## Persistence and Account Isolation@@ -170,6 +178,6 @@ Storage keys are namespaced per account at the persistence layer. When using `pe| Variable | Default | Description ||---|---|---|-| `FLOCI_DEFAULT_ACCOUNT_ID` | `000000000000` | Account ID used when the AKID is not exactly 12 digits |+| `FLOCI_DEFAULT_ACCOUNT_ID` | `000000000000` | Account ID used when the AKID does not resolve directly or through a stored credential || `FLOCI_DEFAULT_REGION` | `us-east-1` | Region used when not derivable from the `Authorization` header |-| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | Enforce SigV4 signature verification |+| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | Verify S3 presigned URL signatures |diff --git a/src/main/java/io/github/hectorvent/floci/core/common/AccountContextFilter.java b/src/main/java/io/github/hectorvent/floci/core/common/AccountContextFilter.javaindex 3010d66ddf..53f96a8d0b 100644--- a/src/main/java/io/github/hectorvent/floci/core/common/AccountContextFilter.java+++ b/src/main/java/io/github/hectorvent/floci/core/common/AccountContextFilter.java@@ -17,8 +17,8 @@ import java.util.Optional;* downstream filters (e.g. IAM enforcement) can rely on the context being set.** <p>Account resolution precedence: a 12-digit access key ID is used directly as- * the account; otherwise temporary credentials (e.g. assumed-role {@code ASIA...}- * keys) are looked up in the session store via {@link SessionAccountLookup}; if+ * the account; otherwise IAM and temporary credentials (e.g. assumed-role {@code ASIA...}+ * keys) are looked up via {@link SessionAccountLookup}; if* neither matches, the configured default account applies.*/@Provider@@ -66,13 +66,13 @@ public class AccountContextFilter implements ContainerRequestFilter {/*** Applies the account-resolution precedence. A 12-digit AKID is already reflected in* {@code resolvedDefault} (the account or default returned by {@link AccountResolver});- * for any other key shape, a live session lookup takes precedence before falling back.+ * for any other key shape, an IAM or live-session lookup takes precedence before falling back.*/private String resolveAccount(String akid, String resolvedDefault) {if (akid != null && !akid.matches("\\d{12}")) {- Optional<String> sessionAccount = sessionAccountLookup.resolveAccountId(akid);- if (sessionAccount.isPresent()) {- return sessionAccount.get();+ Optional<String> credentialAccount = sessionAccountLookup.resolveAccountId(akid);+ if (credentialAccount.isPresent()) {+ return credentialAccount.get();}}return resolvedDefault;diff --git a/src/main/java/io/github/hectorvent/floci/core/common/SessionAccountLookup.java b/src/main/java/io/github/hectorvent/floci/core/common/SessionAccountLookup.javaindex 47ce083747..bb3388f806 100644--- a/src/main/java/io/github/hectorvent/floci/core/common/SessionAccountLookup.java+++ b/src/main/java/io/github/hectorvent/floci/core/common/SessionAccountLookup.java@@ -3,8 +3,7 @@ package io.github.hectorvent.floci.core.common;import java.util.Optional;/**- * Port that maps an STS temporary access key ID (e.g. {@code ASIA...}) to the AWS- * account the request should resolve to.+ * Port that maps an IAM or STS access key ID to the AWS account the request should resolve to.** <p>Declared in {@code core.common} so {@link AccountContextFilter} can route* assumed-role and other temporary credentials to the correct account without@@ -14,8 +13,8 @@ import java.util.Optional;public interface SessionAccountLookup {/**- * Returns the account ID associated with the given temporary access key ID,- * or {@link Optional#empty()} if it is not a known, live session.+ * Returns the account ID associated with the given access key ID, or+ * {@link Optional#empty()} if it is not a known, active credential.*/Optional<String> resolveAccountId(String accessKeyId);}diff --git a/src/main/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackend.java b/src/main/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackend.javaindex 7ce91deb54..65e11461d6 100644--- a/src/main/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackend.java+++ b/src/main/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackend.java@@ -31,6 +31,9 @@ import java.util.stream.Collectors;*/public class AccountAwareStorageBackend<V> implements StorageBackend<String, V> {+ /** A stored value together with its owning AWS account and account-relative key. */+ public record AccountEntry<T>(String accountId, String key, T value) {}+private final StorageBackend<String, V> delegate;private final Instance<RequestContext> requestContextInstance;private final String defaultAccountId;@@ -129,6 +132,27 @@ public class AccountAwareStorageBackend<V> implements StorageBackend<String, V>return result;}+ /**+ * Returns entries across every account while preserving the account that owns each logical key.+ * The filter receives the account-relative key. Keys without a 12-digit ASCII account prefix,+ * including legacy keys that contain slashes, are returned unchanged under the configured+ * default account. Unlike {@link #get}, this scan does not migrate legacy entries.+ */+ public List<AccountEntry<V>> scanAllAccountEntries(Predicate<String> keyFilter) {+ List<AccountEntry<V>> result = new ArrayList<>();+ for (String rawKey : delegate.keys()) {+ boolean hasAccountPrefix = hasAccountPrefix(rawKey);+ String accountId = hasAccountPrefix ? rawKey.substring(0, 12) : defaultAccountId;+ String logicalKey = hasAccountPrefix ? rawKey.substring(13) : rawKey;+ if (!keyFilter.test(logicalKey)) {+ continue;+ }+ delegate.get(rawKey).ifPresent(value ->+ result.add(new AccountEntry<>(accountId, logicalKey, value)));+ }+ return result;+ }+/*** Returns all entries across every account as a map of logical-key (account prefix stripped)* to value. Entries without a slash-prefixed account segment are skipped.@@ -325,4 +349,17 @@ public class AccountAwareStorageBackend<V> implements StorageBackend<String, V>private String prefixed(String key) {return prefix() + "/" + key;}++ private static boolean hasAccountPrefix(String key) {+ if (key.length() < 13 || key.charAt(12) != '/') {+ return false;+ }+ for (int i = 0; i < 12; i++) {+ char character = key.charAt(i);+ if (character < '0' || character > '9') {+ return false;+ }+ }+ return true;+ }}diff --git a/src/main/java/io/github/hectorvent/floci/services/iam/IamService.java b/src/main/java/io/github/hectorvent/floci/services/iam/IamService.javaindex 68eabbcb22..6e5bd8fcc7 100644--- a/src/main/java/io/github/hectorvent/floci/services/iam/IamService.java+++ b/src/main/java/io/github/hectorvent/floci/services/iam/IamService.java@@ -1631,15 +1631,21 @@ public class IamService implements SessionAccountLookup {}/**- * Resolves the account a temporary access key belongs to: the account encoded in the- * session's role (or federated-user) ARN when present, otherwise the caller account captured- * at mint time. Returns empty for unknown or expired sessions so callers fall back to the- * default account.+ * Resolves the account an IAM or temporary access key belongs to. Long-term IAM access keys+ * resolve from their owning account namespace. Temporary credentials resolve from the account+ * encoded in the session's role (or federated-user) ARN when present, otherwise the caller+ * account captured at mint time. Returns empty for unknown, inactive, or expired credentials.*/@Overridepublic Optional<String> resolveAccountId(String accessKeyId) {if (!isTemporaryAccessKey(accessKeyId)) {- return Optional.empty();+ if (accessKeyId == null || !(accessKeys instanceof AccountAwareStorageBackend<AccessKey> aware)) {+ return Optional.empty();+ }+ return aware.scanAllAccountEntries(accessKeyId::equals).stream()+ .filter(entry -> "Active".equals(entry.value().getStatus()))+ .map(AccountAwareStorageBackend.AccountEntry::accountId)+ .findFirst();}Optional<SessionCredential> sessionOpt = findSessionAnyAccount(accessKeyId);if (sessionOpt.isEmpty()) {diff --git a/src/test/java/io/github/hectorvent/floci/core/common/AccountContextFilterTest.java b/src/test/java/io/github/hectorvent/floci/core/common/AccountContextFilterTest.javaindex 428912542f..e2b1fbf976 100644--- a/src/test/java/io/github/hectorvent/floci/core/common/AccountContextFilterTest.java+++ b/src/test/java/io/github/hectorvent/floci/core/common/AccountContextFilterTest.java@@ -104,6 +104,29 @@ class AccountContextFilterTest {assertEquals("us-west-2", requestContext.getRegion());}+ @Test+ void resolvesIamAccessKeyToOwningAccount() {+ sessionAccounts.put("AKIAEXAMPLEACCESSKEY", "333344445555");+ ContainerRequestContext ctx = mockContext(+ "AWS4-HMAC-SHA256 Credential=AKIAEXAMPLEACCESSKEY/20260617/us-west-2/kms/aws4_request, "+ + "SignedHeaders=host, Signature=abc",+ null+ );+ filter.filter(ctx);+ assertEquals("333344445555", requestContext.getAccountId());+ assertEquals("us-west-2", requestContext.getRegion());+ }++ @Test+ void resolvesIamAccessKeyFromPresignedCredential() {+ sessionAccounts.put("AKIAPRESIGNEDACCESSKEY", "444455556666");+ ContainerRequestContext ctx = mockContext(null,+ "AKIAPRESIGNEDACCESSKEY/20260617/eu-central-1/s3/aws4_request");+ filter.filter(ctx);+ assertEquals("444455556666", requestContext.getAccountId());+ assertEquals("eu-central-1", requestContext.getRegion());+ }+@Testvoid twelveDigitAkidWinsOverSessionLookup() {sessionAccounts.put("000000000001", "999999999999");diff --git a/src/test/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackendTest.java b/src/test/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackendTest.javaindex 92a1f92a79..2e9edfa962 100644--- a/src/test/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackendTest.java+++ b/src/test/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackendTest.java@@ -5,6 +5,7 @@ import org.junit.jupiter.api.Test;import java.util.List;import java.util.Map;import java.util.Optional;+import java.util.Set;import static org.junit.jupiter.api.Assertions.assertEquals;import static org.junit.jupiter.api.Assertions.assertTrue;@@ -158,4 +159,47 @@ class AccountAwareStorageBackendTest {assertEquals(Optional.empty(), raw.get("us-east-1::Orders"),"the superseded legacy key must be deleted, not left to collide again later");}++ @Test+ void scanAllAccountEntriesPreservesOwnersAndTreatsNonAwsPrefixesAsLegacy() {+ InMemoryStorage<String, String> raw = new InMemoryStorage<>();+ raw.put("123456789012/us-east-1::api-a", "account-a");+ raw.put("210987654321/us-east-1::api-b", "account-b");+ raw.put("legacy/path", "legacy");+ raw.put("12345678901/short", "short-prefix");+ raw.put("1234567890123/long", "long-prefix");+ raw.put("123456789012/unicode", "unicode-prefix");++ AccountAwareStorageBackend<String> storage =+ new AccountAwareStorageBackend<>(raw, null, "000000000000");++ List<AccountAwareStorageBackend.AccountEntry<String>> entries =+ storage.scanAllAccountEntries(key -> true);++ assertEquals(Set.of(+ new AccountAwareStorageBackend.AccountEntry<>("123456789012", "us-east-1::api-a", "account-a"),+ new AccountAwareStorageBackend.AccountEntry<>("210987654321", "us-east-1::api-b", "account-b"),+ new AccountAwareStorageBackend.AccountEntry<>("000000000000", "legacy/path", "legacy"),+ new AccountAwareStorageBackend.AccountEntry<>("000000000000", "12345678901/short", "short-prefix"),+ new AccountAwareStorageBackend.AccountEntry<>("000000000000", "1234567890123/long", "long-prefix"),+ new AccountAwareStorageBackend.AccountEntry<>(+ "000000000000", "123456789012/unicode", "unicode-prefix")),+ Set.copyOf(entries));+ }++ @Test+ void scanAllAccountEntriesFiltersAccountRelativeKeys() {+ InMemoryStorage<String, String> raw = new InMemoryStorage<>();+ raw.put("123456789012/us-east-1::api-a", "account-a");+ raw.put("210987654321/eu-west-1::api-b", "account-b");+ raw.put("us-east-1::legacy", "legacy");++ AccountAwareStorageBackend<String> storage =+ new AccountAwareStorageBackend<>(raw, null, "000000000000");++ assertEquals(Set.of(+ new AccountAwareStorageBackend.AccountEntry<>("123456789012", "us-east-1::api-a", "account-a"),+ new AccountAwareStorageBackend.AccountEntry<>("000000000000", "us-east-1::legacy", "legacy")),+ Set.copyOf(storage.scanAllAccountEntries(key -> key.startsWith("us-east-1::"))));+ }}diff --git a/src/test/java/io/github/hectorvent/floci/services/iam/IamServiceTest.java b/src/test/java/io/github/hectorvent/floci/services/iam/IamServiceTest.javaindex e3a094c4eb..b5ecef9d83 100644--- a/src/test/java/io/github/hectorvent/floci/services/iam/IamServiceTest.java+++ b/src/test/java/io/github/hectorvent/floci/services/iam/IamServiceTest.java@@ -36,11 +36,11 @@ class IamServiceTest {return iamService(seedDeployerPrincipal, new InMemoryStorage<>());}- private static IamService iamService(boolean seedDeployerPrincipal, InMemoryStorage<String, AccessKey> accessKeys) {+ private static IamService iamService(boolean seedDeployerPrincipal, StorageBackend<String, AccessKey> accessKeys) {return iamService(seedDeployerPrincipal, accessKeys, new InMemoryStorage<>());}- private static IamService iamService(boolean seedDeployerPrincipal, InMemoryStorage<String, AccessKey> accessKeys,+ private static IamService iamService(boolean seedDeployerPrincipal, StorageBackend<String, AccessKey> accessKeys,StorageBackend<String, SessionCredential> sessions) {return new IamService(new InMemoryStorage<>(),@@ -500,12 +500,28 @@ class IamServiceTest {}@Test- void resolveAccountIdDoesNotScanSessionsForLongTermAccessKey() {- CountingAccountAwareSessionStorage sessions = new CountingAccountAwareSessionStorage();- IamService service = iamService(false, new InMemoryStorage<>(), sessions);+ void resolveAccountIdUsesLongTermAccessKeyOwnerAccount() {+ AccountAwareStorageBackend<AccessKey> accessKeys = new AccountAwareStorageBackend<>(+ new InMemoryStorage<>(), null, "000000000000");+ AccessKey accessKey = new AccessKey("AKIAIOSFODNN7EXAMPLE", "secret", "worker");+ accessKeys.putForAccount("111122223333", accessKey.getAccessKeyId(), accessKey);++ IamService service = iamService(false, accessKeys, new InMemoryStorage<>());++ assertEquals("111122223333", service.resolveAccountId(accessKey.getAccessKeyId()).orElseThrow());+ }++ @Test+ void resolveAccountIdIgnoresInactiveLongTermAccessKey() {+ AccountAwareStorageBackend<AccessKey> accessKeys = new AccountAwareStorageBackend<>(+ new InMemoryStorage<>(), null, "000000000000");+ AccessKey accessKey = new AccessKey("AKIAINACTIVEEXAMPLE", "secret", "worker");+ accessKey.setStatus("Inactive");+ accessKeys.putForAccount("111122223333", accessKey.getAccessKeyId(), accessKey);++ IamService service = iamService(false, accessKeys, new InMemoryStorage<>());- assertTrue(service.resolveAccountId("AKIAIOSFODNN7EXAMPLE").isEmpty());- assertEquals(0, sessions.scanAllAccountsAsMapCalls);+ assertTrue(service.resolveAccountId(accessKey.getAccessKeyId()).isEmpty());}private static final class CountingAccountAwareSessionStorage