Skip to content

Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.

release v1.2.13 (#328)

Nahuel Nuceraa6eb0d6cd66d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c5cd3092..beb704dc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,12 +7,19 @@ Versioning follows [Semantic Versioning](https://semver.org/).
---
-## [Unreleased]
+## [1.2.13] — 2026-04-14
### Added
-- **RDS real MySQL/MariaDB connectivity** — `pymysql` (44 KB, pure Python) is now bundled in the Docker image. When MiniStack runs inside Docker, RDS containers are attached to MiniStack's Docker network with internal IP endpoints for sibling-container connectivity. The public `localhost` endpoint remains unchanged for host-mode access. The Data API authenticates using credentials from Secrets Manager, mapping the master user to MySQL `root` for admin operations. `CreateDBCluster` stores the master password; `CreateDBInstance` inherits credentials from parent clusters; `ModifyDBCluster` propagates password changes to the real MySQL container via `ALTER USER`.
+- **RDS real MySQL/MariaDB connectivity** — `pymysql` (44 KB, pure Python) is now bundled in the Docker image. When MiniStack runs inside Docker, RDS containers are attached to MiniStack's Docker network with internal IP endpoints for sibling-container connectivity. The public `localhost` endpoint remains unchanged for host-mode access. The Data API authenticates using credentials from Secrets Manager, mapping the master user to MySQL `root` for admin operations. `CreateDBCluster` stores the master password; `CreateDBInstance` inherits credentials from parent clusters; `ModifyDBCluster` propagates password changes to the real MySQL container via `ALTER USER`. Contributed by @jayjanssen (#316)
+- **Cognito Identity Provider CRUD** — `CreateIdentityProvider`, `DescribeIdentityProvider`, `UpdateIdentityProvider`, `DeleteIdentityProvider`, `ListIdentityProviders`. Enables SAML/OIDC federation setup in local development. Reported by @prandogabriel (#325)
+- **CodeBuild `BatchGetProjects` ARN lookup** — accepts full ARNs in addition to project names, matching real AWS behavior. Contributed by @alexanderkrum-next (#321)
+
### Fixed
-- **SFN States.Format escape handling** — `States.Format` now correctly processes `\'`, `\{`, `\}`, and `\` escape sequences in template strings, matching AWS behavior. Escaped quotes no longer truncate the template during intrinsic argument parsing. Interpolated values are preserved verbatim (backslashes in arguments are not interpreted as escapes).
+- **SFN States.Format escape handling** — `States.Format` now correctly processes `\'`, `\{`, `\}`, and `\\` escape sequences in template strings, matching AWS behavior. Escaped quotes no longer truncate the template during intrinsic argument parsing. Interpolated values are preserved verbatim (backslashes in arguments are not interpreted as escapes). Contributed by @jayjanssen (#315)
+- **S3 GetBucketLifecycleConfiguration returns canonical XML** — lifecycle rules are now parsed on PUT and reconstructed as canonical `<LifecycleConfiguration>` XML on GET, instead of echoing back the raw PUT body. Fixes Terraform Go SDK v2 deserialization failures. Reported by @alexanderkrum-next (#324)
+- **Cognito AdminGetUser accepts sub UUID** — `AdminGetUser` and all user-resolving operations now accept the user's `sub` UUID as the `Username` parameter, matching real AWS behavior. Reported by @prandogabriel (#326)
+- **Cognito IdToken missing user attributes** — `IdToken` now includes `email`, `cognito:username`, `email_verified`, and other user attributes. Uses `aud` claim instead of `client_id`, matching the OIDC spec and real AWS Cognito. Reported by @prandogabriel (#327)
+- **Cognito AnalyticsConfiguration drift** — `AnalyticsConfiguration` defaults to `None` instead of empty dict, preventing Terraform drift on every plan. Contributed by @alexanderkrum-next (#322)
---
diff --git a/README.md b/README.md
index b88ac3f3..4f541cca 100644
--- a/README.md
+++ b/README.md
@@ -73,13 +73,16 @@ curl http://localhost:4566/_ministack/health
# Reset all state — wipe every service back to empty (useful between test runs)
curl -X POST http://localhost:4566/_ministack/reset
+# Reset and re-run init scripts (boot.d + ready.d)
+curl -X POST http://localhost:4566/_ministack/reset?init=1
+
# Runtime config — change service-level settings without restart
curl -X POST http://localhost:4566/_ministack/config \
-H "Content-Type: application/json" \
-d '{"lambda_svc.LAMBDA_EXECUTOR": "docker"}'
```
-The reset endpoint is especially useful in CI pipelines and test suites — call it in `setUp`/`beforeEach` to get a clean environment for every test without restarting the container.
+The reset endpoint is especially useful in CI pipelines and test suites — call it in `setUp`/`beforeEach` to get a clean environment for every test without restarting the container. Add `?init=1` to re-run your init scripts after the reset, restoring any resources they create (VPCs, queues, seed data, etc.).
The config endpoint supports these keys:
@@ -89,6 +92,7 @@ The config endpoint supports these keys:
| `athena.ATHENA_ENGINE` | Athena query engine (`duckdb` or `mock`) |
| `athena.ATHENA_DATA_DIR` | Directory for Athena DuckDB data files |
| `stepfunctions._sfn_mock_config` | SFN mock config (AWS SFN Local compatible) |
+| `stepfunctions._SFN_WAIT_SCALE` | Scale factor for Wait state durations and retry sleeps (`0` = skip all waits) |
To set region or account ID, use environment variables at startup:
diff --git a/ministack/services/cognito.py b/ministack/services/cognito.py
index 34011c65..ab57679b 100644
--- a/ministack/services/cognito.py
+++ b/ministack/services/cognito.py
@@ -220,7 +220,7 @@ def _identity_id(pool_id: str) -> str:
def _fake_token(sub: str, pool_id: str, client_id: str, token_type: str = "access",
- username: str = "") -> str:
+ username: str = "", user_attrs: dict | None = None) -> str:
"""Return a JWT signed with the RSA key when cryptography is available."""
header = base64.urlsafe_b64encode(
json.dumps({"alg": "RS256", "kid": "ministack-key-1"}).encode()
@@ -229,14 +229,31 @@ def _fake_token(sub: str, pool_id: str, client_id: str, token_type: str = "acces
claims = {
"sub": sub,
"iss": f"https://cognito-idp.{REGION}.amazonaws.com/{pool_id}",
- "client_id": client_id,
"token_use": token_type,
"iat": now,
"exp": now + 3600,
"jti": new_uuid(),
+ "auth_time": now,
+ "origin_jti": new_uuid(),
}
- if token_type == "access" and username:
- claims["username"] = username
+ if token_type == "id":
+ # IdToken uses 'aud' (not 'client_id') per OIDC spec
+ claims["aud"] = client_id
+ if username:
+ claims["cognito:username"] = username
+ # Include user attributes in IdToken
+ if user_attrs:
+ for k, v in user_attrs.items():
+ if k == "sub":
+ continue
+ claims[k] = v
+ if "email" in user_attrs:
+ claims.setdefault("email_verified", True)
+ else:
+ # AccessToken uses 'client_id'
+ claims["client_id"] = client_id
+ if username:
+ claims["username"] = username
payload = base64.urlsafe_b64encode(
json.dumps(claims).encode()
).rstrip(b"=").decode()
@@ -277,6 +294,13 @@ def _resolve_pool(pool_id: str):
def _resolve_user(pool: dict, username: str):
user = pool["_users"].get(username)
+ if not user:
+ # Real AWS also accepts the user's 'sub' UUID as Username.
+ for u in pool["_users"].values():
+ attrs = _attr_list_to_dict(u.get("Attributes", []))
+ if attrs.get("sub") == username:
+ user = u
+ break
if not user:
return None, error_response_json(
"UserNotFoundException",
@@ -400,6 +424,12 @@ def _dispatch_idp(action: str, data: dict):
"CreateUserPoolDomain": _create_user_pool_domain,
"DeleteUserPoolDomain": _delete_user_pool_domain,
"DescribeUserPoolDomain": _describe_user_pool_domain,
+ # Identity Providers
+ "CreateIdentityProvider": _create_identity_provider,
+ "DescribeIdentityProvider": _describe_identity_provider,
+ "UpdateIdentityProvider": _update_identity_provider,
+ "DeleteIdentityProvider": _delete_identity_provider,
+ "ListIdentityProviders": _list_identity_providers,
# MFA
"GetUserPoolMfaConfig": _get_user_pool_mfa_config,
"SetUserPoolMfaConfig": _set_user_pool_mfa_config,
@@ -992,11 +1022,13 @@ def _mfa_challenge_for_user(pool: dict, user: dict, pid: str, username: str) ->
def _build_auth_result(pool_id: str, client_id: str, user: dict) -> dict:
- sub = _attr_list_to_dict(user.get("Attributes", [])).get("sub", user["Username"])
+ attrs = _attr_list_to_dict(user.get("Attributes", []))
+ sub = attrs.get("sub", user["Username"])
username = user.get("Username", "")
return {
"AccessToken": _fake_token(sub, pool_id, client_id, "access", username=username),
- "IdToken": _fake_token(sub, pool_id, client_id, "id"),
+ "IdToken": _fake_token(sub, pool_id, client_id, "id", username=username,
+ user_attrs=attrs),
"RefreshToken": _fake_token(sub, pool_id, client_id, "refresh"),
"TokenType": "Bearer",
"ExpiresIn": 3600,
@@ -1576,6 +1608,111 @@ def _describe_user_pool_domain(data):
})
+# ===========================================================================
+# IDENTITY PROVIDERS
+# ===========================================================================
+
+def _create_identity_provider(data):
+ pid = data.get("UserPoolId")
+ pool, err = _resolve_pool(pid)
+ if err:
+ return err
+ provider_name = data.get("ProviderName")
+ provider_type = data.get("ProviderType")
+ if not provider_name or not provider_type:
+ return error_response_json(
+ "InvalidParameterException", "ProviderName and ProviderType are required.", 400)
+ providers = pool.setdefault("_identity_providers", {})
+ if provider_name in providers:
+ return error_response_json(
+ "DuplicateProviderException",
+ f"A provider with name {provider_name} already exists.", 400)
+ provider = {
+ "UserPoolId": pid,
+ "ProviderName": provider_name,
+ "ProviderType": provider_type,
+ "ProviderDetails": data.get("ProviderDetails", {}),
+ "AttributeMapping": data.get("AttributeMapping", {}),
+ "IdpIdentifiers": data.get("IdpIdentifiers", []),
+ "LastModifiedDate": int(time.time()),
+ "CreationDate": int(time.time()),
+ }
+ providers[provider_name] = provider
+ return json_response({"IdentityProvider": provider})
+
+
+def _describe_identity_provider(data):
+ pid = data.get("UserPoolId")
+ pool, err = _resolve_pool(pid)
+ if err:
+ return err
+ provider_name = data.get("ProviderName")
+ providers = pool.get("_identity_providers", {})
+ provider = providers.get(provider_name)
+ if not provider:
+ return error_response_json(
+ "ResourceNotFoundException",
+ f"Identity provider {provider_name} does not exist.", 400)
+ return json_response({"IdentityProvider": provider})
+
+
+def _update_identity_provider(data):
+ pid = data.get("UserPoolId")
+ pool, err = _resolve_pool(pid)
+ if err:
+ return err
+ provider_name = data.get("ProviderName")
+ providers = pool.get("_identity_providers", {})
+ provider = providers.get(provider_name)
+ if not provider:
+ return error_response_json(
+ "ResourceNotFoundException",
+ f"Identity provider {provider_name} does not exist.", 400)
+ if "ProviderDetails" in data:
+ provider["ProviderDetails"] = data["ProviderDetails"]
+ if "AttributeMapping" in data:
+ provider["AttributeMapping"] = data["AttributeMapping"]
+ if "IdpIdentifiers" in data:
+ provider["IdpIdentifiers"] = data["IdpIdentifiers"]
+ provider["LastModifiedDate"] = int(time.time())
+ return json_response({"IdentityProvider": provider})
+
+
+def _delete_identity_provider(data):
+ pid = data.get("UserPoolId")
+ pool, err = _resolve_pool(pid)
+ if err:
+ return err
+ provider_name = data.get("ProviderName")
+ providers = pool.get("_identity_providers", {})
+ if provider_name not in providers:
+ return error_response_json(
+ "ResourceNotFoundException",
+ f"Identity provider {provider_name} does not exist.", 400)
+ del providers[provider_name]
+ return json_response({})
+
+
+def _list_identity_providers(data):
+ pid = data.get("UserPoolId")
+ pool, err = _resolve_pool(pid)
+ if err:
+ return err
+ providers = pool.get("_identity_providers", {})
+ max_results = data.get("MaxResults", 60)
+ items = list(providers.values())[:max_results]
+ # ListIdentityProviders returns a lighter shape per AWS docs
+ out = []
+ for p in items:
+ out.append({
+ "ProviderName": p["ProviderName"],
+ "ProviderType": p["ProviderType"],
+ "LastModifiedDate": p["LastModifiedDate"],
+ "CreationDate": p["CreationDate"],
+ })
+ return json_response({"Providers": out})
+
+
# ===========================================================================
# MFA CONFIG
# ===========================================================================
diff --git a/ministack/services/rds_data.py b/ministack/services/rds_data.py
index 7e6973ec..f32a8ccf 100644
--- a/ministack/services/rds_data.py
+++ b/ministack/services/rds_data.py
@@ -280,16 +280,14 @@ def _connect(instance, engine, database=None, password=None,
"pymysql is required for MySQL/Aurora MySQL rds-data support. "
"Install with: pip install pymysql"
)
- # In RDS the master user has full privileges. In a Docker MySQL
- # container the equivalent is 'root'. When the secret identifies
- # the master user (username matches MasterUsername or is absent),
- # connect as root. Otherwise use the actual username from the
- # secret so user-level operations (e.g. ALTER USER … REPLACE)
- # authenticate correctly.
+ # In Docker MySQL, 'root' has full privileges. Map the master
+ # user (or absent username) to root. Non-master usernames pass
+ # through for user-level operations.
master = instance.get("MasterUsername", "admin")
- connect_user = username or "root"
- if username and username == master:
+ if not username or username == master:
connect_user = "root"
+ else:
+ connect_user = username
return pymysql.connect(
host=host, port=int(port), user=connect_user,
password=pw, database=db or None, autocommit=True,
diff --git a/ministack/services/s3.py b/ministack/services/s3.py
index 9f54401a..60ba3b27 100644
--- a/ministack/services/s3.py
+++ b/ministack/services/s3.py
@@ -35,6 +35,7 @@ import time
from urllib.parse import quote as url_quote, unquote as url_unquote, parse_qs as _parse_qs
from defusedxml.ElementTree import fromstring
from xml.etree.ElementTree import Element, SubElement, tostring
+from xml.sax.saxutils import escape as _esc
from ministack.core.persistence import load_state, PERSIST_STATE
from ministack.core.responses import (
@@ -752,12 +753,71 @@ def _delete_bucket_encryption(name: str):
def _get_bucket_lifecycle(name: str):
if name not in _buckets:
return _no_such_bucket(name)
- config = _bucket_lifecycle.get(name)
- if config:
+ rules = _bucket_lifecycle.get(name)
+ if rules is not None:
+ xml = '<?xml version="1.0" encoding="UTF-8"?>\n'
+ xml += '<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">'
+ for rule in rules:
+ xml += "<Rule>"
+ if rule.get("ID"):
+ xml += f"<ID>{_esc(rule['ID'])}</ID>"
+ # Filter
+ filt = rule.get("Filter", {})
+ xml += "<Filter>"
+ if "Prefix" in filt:
+ xml += f"<Prefix>{_esc(filt['Prefix'])}</Prefix>"
+ if "Tag" in filt:
+ xml += f"<Tag><Key>{_esc(filt['Tag']['Key'])}</Key><Value>{_esc(filt['Tag']['Value'])}</Value></Tag>"
+ if "And" in filt:
+ xml += "<And>"
+ if "Prefix" in filt["And"]:
+ xml += f"<Prefix>{_esc(filt['And']['Prefix'])}</Prefix>"
+ for tag in filt["And"].get("Tags", []):
+ xml += f"<Tag><Key>{_esc(tag['Key'])}</Key><Value>{_esc(tag['Value'])}</Value></Tag>"
+ xml += "</And>"
+ xml += "</Filter>"
+ xml += f"<Status>{rule.get('Status', 'Enabled')}</Status>"
+ for t in rule.get("Transitions", []):
+ xml += "<Transition>"
+ if "Days" in t:
+ xml += f"<Days>{t['Days']}</Days>"
+ if "Date" in t:
+ xml += f"<Date>{t['Date']}</Date>"
+ xml += f"<StorageClass>{t.get('StorageClass', 'STANDARD_IA')}</StorageClass>"
+ xml += "</Transition>"
+ for t in rule.get("NoncurrentVersionTransitions", []):
+ xml += "<NoncurrentVersionTransition>"
+ if "NoncurrentDays" in t:
+ xml += f"<NoncurrentDays>{t['NoncurrentDays']}</NoncurrentDays>"
+ xml += f"<StorageClass>{t.get('StorageClass', 'STANDARD_IA')}</StorageClass>"
+ xml += "</NoncurrentVersionTransition>"
+ if "Expiration" in rule:
+ exp = rule["Expiration"]
+ xml += "<Expiration>"
+ if "Days" in exp:
+ xml += f"<Days>{exp['Days']}</Days>"
+ if "Date" in exp:
+ xml += f"<Date>{exp['Date']}</Date>"
+ if "ExpiredObjectDeleteMarker" in exp:
+ xml += f"<ExpiredObjectDeleteMarker>{str(exp['ExpiredObjectDeleteMarker']).lower()}</ExpiredObjectDeleteMarker>"
+ xml += "</Expiration>"
+ if "NoncurrentVersionExpiration" in rule:
+ nve = rule["NoncurrentVersionExpiration"]
+ xml += "<NoncurrentVersionExpiration>"
+ if "NoncurrentDays" in nve:
+ xml += f"<NoncurrentDays>{nve['NoncurrentDays']}</NoncurrentDays>"
+ xml += "</NoncurrentVersionExpiration>"
+ if rule.get("AbortIncompleteMultipartUpload"):
+ aimu = rule["AbortIncompleteMultipartUpload"]
+ xml += "<AbortIncompleteMultipartUpload>"
+ xml += f"<DaysAfterInitiation>{aimu.get('DaysAfterInitiation', 7)}</DaysAfterInitiation>"
+ xml += "</AbortIncompleteMultipartUpload>"
+ xml += "</Rule>"
+ xml += "</LifecycleConfiguration>"
return 200, {
"Content-Type": "application/xml",
"x-amz-transition-default-minimum-object-size": "all_storage_classes_128K",
- }, config
+ }, xml.encode()
return _error(
"NoSuchLifecycleConfiguration",
"The lifecycle configuration does not exist",
@@ -769,7 +829,104 @@ def _get_bucket_lifecycle(name: str):
def _put_bucket_lifecycle(name: str, body: bytes):
if name not in _buckets:
return _no_such_bucket(name)
- _bucket_lifecycle[name] = body
+ # Parse incoming XML into structured rules for canonical GET responses.
+ rules = []
+ try:
+ from defusedxml import ElementTree as ET
+ root = ET.fromstring(body)
+ ns = {"s3": "http://s3.amazonaws.com/doc/2006-03-01/"}
+ for rule_el in root.findall("Rule", ns) or root.findall("s3:Rule", ns):
+ rule: dict = {}
+ _lc_text = lambda el, tag: (el.findtext(tag) or el.findtext(f"s3:{tag}", namespaces=ns) or "")
+ _lc_find = lambda el, tag: (el.find(tag) or el.find(f"s3:{tag}", ns))
+ _lc_findall = lambda el, tag: (el.findall(tag) or el.findall(f"s3:{tag}", ns))
+ id_val = _lc_text(rule_el, "ID")
+ if id_val:
+ rule["ID"] = id_val
+ rule["Status"] = _lc_text(rule_el, "Status") or "Enabled"
+ # Filter
+ filt_el = _lc_find(rule_el, "Filter")
+ filt: dict = {}
+ if filt_el is not None:
+ prefix = _lc_text(filt_el, "Prefix")
+ if prefix or _lc_find(filt_el, "Prefix") is not None:
+ filt["Prefix"] = prefix
+ tag_el = _lc_find(filt_el, "Tag")
+ if tag_el is not None:
+ filt["Tag"] = {"Key": _lc_text(tag_el, "Key"), "Value": _lc_text(tag_el, "Value")}
+ and_el = _lc_find(filt_el, "And")
+ if and_el is not None:
+ and_data: dict = {}
+ p = _lc_text(and_el, "Prefix")
+ if p or _lc_find(and_el, "Prefix") is not None:
+ and_data["Prefix"] = p
+ tags = []
+ for t in _lc_findall(and_el, "Tag"):
+ tags.append({"Key": _lc_text(t, "Key"), "Value": _lc_text(t, "Value")})
+ if tags:
+ and_data["Tags"] = tags
+ filt["And"] = and_data
+ rule["Filter"] = filt
+ # Transitions
+ transitions = []
+ for t in _lc_findall(rule_el, "Transition"):
+ td: dict = {}
+ days = _lc_text(t, "Days")
+ if days:
+ td["Days"] = int(days)
+ date = _lc_text(t, "Date")
+ if date:
+ td["Date"] = date
+ td["StorageClass"] = _lc_text(t, "StorageClass") or "STANDARD_IA"
+ transitions.append(td)
+ if transitions:
+ rule["Transitions"] = transitions
+ # NoncurrentVersionTransitions
+ nv_transitions = []
+ for t in _lc_findall(rule_el, "NoncurrentVersionTransition"):
+ td = {}
+ days = _lc_text(t, "NoncurrentDays")
+ if days:
+ td["NoncurrentDays"] = int(days)
+ td["StorageClass"] = _lc_text(t, "StorageClass") or "STANDARD_IA"
+ nv_transitions.append(td)
+ if nv_transitions:
+ rule["NoncurrentVersionTransitions"] = nv_transitions
+ # Expiration
+ exp_el = _lc_find(rule_el, "Expiration")
+ if exp_el is not None:
+ exp: dict = {}
+ days = _lc_text(exp_el, "Days")
+ if days:
+ exp["Days"] = int(days)
+ date = _lc_text(exp_el, "Date")
+ if date:
+ exp["Date"] = date
+ eodm = _lc_text(exp_el, "ExpiredObjectDeleteMarker")
+ if eodm:
+ exp["ExpiredObjectDeleteMarker"] = eodm.lower() == "true"
+ rule["Expiration"] = exp
+ # NoncurrentVersionExpiration
+ nve_el = _lc_find(rule_el, "NoncurrentVersionExpiration")
+ if nve_el is not None:
+ nve: dict = {}
+ days = _lc_text(nve_el, "NoncurrentDays")
+ if days:
+ nve["NoncurrentDays"] = int(days)
+ rule["NoncurrentVersionExpiration"] = nve
+ # AbortIncompleteMultipartUpload
+ aimu_el = _lc_find(rule_el, "AbortIncompleteMultipartUpload")
+ if aimu_el is not None:
+ days = _lc_text(aimu_el, "DaysAfterInitiation")
+ rule["AbortIncompleteMultipartUpload"] = {
+ "DaysAfterInitiation": int(days) if days else 7
+ }
+ rules.append(rule)
+ except Exception:
+ # Fallback: store raw if parsing fails
+ _bucket_lifecycle[name] = body
+ return 200, {"x-amz-transition-default-minimum-object-size": "all_storage_classes_128K"}, b""
+ _bucket_lifecycle[name] = rules
return 200, {"x-amz-transition-default-minimum-object-size": "all_storage_classes_128K"}, b""
diff --git a/pyproject.toml b/pyproject.toml
index 793a774b..bf83d761 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "ministack"
-version = "1.2.12"
+version = "1.2.13"
description = "Free, open-source local AWS emulator — drop-in LocalStack replacement"
readme = "README.md"
license = { file = "LICENSE" }