* iam: add ServiceAccount protobuf schema
Add ServiceAccount message type to iam.proto with support for:
- Unique ID and parent user linkage
- Optional expiration timestamp
- Separate credentials (access key/secret)
- Action restrictions (subset of parent)
- Enable/disable status
This is the first step toward implementing issue #7744
(IAM Service Account Support).
* iam: add service account response types
Add IAM API response types for service account operations:
- ServiceAccountInfo struct for marshaling account details
- CreateServiceAccountResponse
- DeleteServiceAccountResponse
- ListServiceAccountsResponse
- GetServiceAccountResponse
- UpdateServiceAccountResponse
Also add type aliases in iamapi package for backwards compatibility.
Part of issue #7744 (IAM Service Account Support).
* iam: implement service account API handlers
Add CRUD operations for service accounts:
- CreateServiceAccount: Creates service account with ABIA key prefix
- DeleteServiceAccount: Removes service account and parent linkage
- ListServiceAccounts: Lists all or filtered by parent user
- GetServiceAccount: Retrieves service account details
- UpdateServiceAccount: Modifies status, description, expiration
Service accounts inherit parent user's actions by default and
support optional expiration timestamps.
Part of issue #7744 (IAM Service Account Support).
* sts: add AssumeRoleWithWebIdentity HTTP endpoint
Add STS API HTTP endpoint for AWS SDK compatibility:
- Create s3api_sts.go with HTTP handlers matching AWS STS spec
- Support AssumeRoleWithWebIdentity action with JWT token
- Return XML response with temporary credentials (AccessKeyId,
SecretAccessKey, SessionToken) matching AWS format
- Register STS route at POST /?Action=AssumeRoleWithWebIdentity
This enables AWS SDKs (boto3, AWS CLI, etc.) to obtain temporary
S3 credentials using OIDC/JWT tokens.
Part of issue #7744 (IAM Service Account Support).
* test: add service account and STS integration tests
Add integration tests for new IAM features:
s3_service_account_test.go:
- TestServiceAccountLifecycle: Create, Get, List, Update, Delete
- TestServiceAccountValidation: Error handling for missing params
s3_sts_test.go:
- TestAssumeRoleWithWebIdentityValidation: Parameter validation
- TestAssumeRoleWithWebIdentityWithMockJWT: JWT token handling
Tests skip gracefully when SeaweedFS is not running or when IAM
features are not configured.
Part of issue #7744 (IAM Service Account Support).
* iam: address code review comments
- Add constants for service account ID and key lengths
- Use strconv.ParseInt instead of fmt.Sscanf for better error handling
- Allow clearing descriptions by checking key existence in url.Values
- Replace magic numbers (12, 20, 40) with named constants
Addresses review comments from gemini-code-assist[bot]
* test: add proper error handling in service account tests
Use require.NoError(t, err) for io.ReadAll and xml.Unmarshal
to prevent silent failures and ensure test reliability.
Addresses review comment from gemini-code-assist[bot]
* test: add proper error handling in STS tests
Use require.NoError(t, err) for io.ReadAll and xml.Unmarshal
to prevent silent failures and ensure test reliability.
Repeated this fix throughout the file.
Addresses review comment from gemini-code-assist[bot] in PR #7901.
* iam: address additional code review comments
- Specific error code mapping for STS service errors
- Distinguish between Sender and Receiver error types in STS responses
- Add nil checks for credentials in List/GetServiceAccount
- Validate expiration date is in the future
- Improve integration test error messages (include response body)
- Add credential verification step in service account tests
Addresses remaining review comments from gemini-code-assist[bot] across multiple files.
* iam: fix shared slice reference in service account creation
Copy parent's actions to create an independent slice for the service
account instead of sharing the underlying array. This prevents
unexpected mutations when the parent's actions are modified later.
Addresses review comment from coderabbitai[bot] in PR #7901.
* iam: remove duplicate unused constant
Removed redundant iamServiceAccountKeyPrefix as ServiceAccountKeyPrefix
is already defined and used.
Addresses remaining cleanup task.
* sts: document limitation of string-based error mapping
Added TODO comment explaining that the current string-based error
mapping approach is fragile and should be replaced with typed errors
from the STS service in a future refactoring.
This addresses the architectural concern raised in code review while
deferring the actual implementation to a separate PR to avoid scope
creep in the current service account feature addition.
* iam: fix remaining review issues
- Add future-date validation for expiration in UpdateServiceAccount
- Reorder tests so credential verification happens before deletion
- Fix compilation error by using correct JWT generation methods
Addresses final review comments from coderabbitai[bot].
* iam: fix service account access key length
The access key IDs were incorrectly generated with 24 characters
instead of the AWS-standard 20 characters. This was caused by
generating 20 random characters and then prepending the 4-character
ABIA prefix.
Fixed by subtracting the prefix length from AccessKeyLength, so the
final key is: ABIA (4 chars) + random (16 chars) = 20 chars total.
This ensures compatibility with S3 clients that validate key length.
* test: add comprehensive service account security tests
Added comprehensive integration tests for service account functionality:
- TestServiceAccountS3Access: Verify SA credentials work for S3 operations
- TestServiceAccountExpiration: Test expiration date validation and enforcement
- TestServiceAccountInheritedPermissions: Verify parent-child relationship
- TestServiceAccountAccessKeyFormat: Validate AWS-compatible key format (ABIA prefix, 20 char length)
These tests ensure SeaweedFS service accounts are compatible with AWS
conventions and provide robust security coverage.
* iam: remove unused UserAccessKeyPrefix constant
Code cleanup to remove unused constants.
* iam: remove unused iamCommonResponse type alias
Code cleanup to remove unused type aliases.
* iam: restore and use UserAccessKeyPrefix constant
Restored UserAccessKeyPrefix constant and updated s3api tests to use it
instead of hardcoded strings for better maintainability and consistency.
* test: improve error handling in service account security tests
Added explicit error checking for io.ReadAll and xml.Unmarshal in
TestServiceAccountExpiration to ensure failures are reported correctly and
cleanup is performed only when appropriate. Also added logging for failed
responses.
* test: use t.Cleanup for reliable resource cleanup
Replaced defer with t.Cleanup to ensure service account cleanup runs even
when require.NoError fails. Also switched from manual error checking to
require.NoError for more idiomatic testify usage.
* iam: add CreatedBy field and optimize identity lookups
- Added createdBy parameter to CreateServiceAccount to track who created each service account
- Extract creator identity from request context using GetIdentityNameFromContext
- Populate created_by field in ServiceAccount protobuf
- Added findIdentityByName helper function to optimize identity lookups
- Replaced nested loops with O(n) helper function calls in CreateServiceAccount and DeleteServiceAccount
This addresses code review feedback for better auditing and performance.
* iam: prevent user deletion when service accounts exist
Following AWS IAM behavior, prevent deletion of users that have active
service accounts. This ensures explicit cleanup and prevents orphaned
service account resources with invalid ParentUser references.
Users must delete all associated service accounts before deleting the
parent user, providing safer resource management.
* sts: enhance TODO with typed error implementation guidance
Updated TODO comment with detailed implementation approach for replacing
string-based error matching with typed errors using errors.Is(). This
provides a clear roadmap for a follow-up PR to improve error handling
robustness and maintainability.
* iam: add operational limits for service account creation
Added AWS IAM-compatible safeguards to prevent resource exhaustion:
- Maximum 100 service accounts per user (LimitExceededException)
- Maximum 1000 character description length (InvalidInputException)
These limits prevent accidental or malicious resource exhaustion while
not impacting legitimate use cases.
* iam: add missing operational limit constants
Added MaxServiceAccountsPerUser and MaxDescriptionLength constants that
were referenced in the previous commit but not defined.
* iam: enforce service account expiration during authentication
CRITICAL SECURITY FIX: Expired service account credentials were not being
rejected during authentication, allowing continued access after expiration.
Changes:
- Added Expiration field to Credential struct
- Populate expiration when loading service accounts from configuration
- Check expiration in all authentication paths (V2 and V4 signatures)
- Return ErrExpiredToken for expired credentials
This ensures expired service accounts are properly rejected at authentication
time, matching AWS IAM behavior and preventing unauthorized access.
* iam: fix error code for expired service account credentials
Use ErrAccessDenied instead of non-existent ErrExpiredToken for expired
service account credentials. This provides appropriate access denial for
expired credentials while maintaining AWS-compatible error responses.
* iam: fix remaining ErrExpiredToken references
Replace all remaining instances of non-existent ErrExpiredToken with
ErrAccessDenied for expired service account credentials.
* iam: apply AWS-standard key format to user access keys
Updated CreateAccessKey to generate AWS-standard 20-character access keys
with AKIA prefix for regular users, matching the format used for service
accounts. This ensures consistency across all access key types and full
AWS compatibility.
- Access keys: AKIA + 16 random chars = 20 total (was 21 chars, no prefix)
- Secret keys: 40 random chars (was 42, now matches AWS standard)
- Uses AccessKeyLength and UserAccessKeyPrefix constants
* sts: replace fragile string-based error matching with typed errors
Implemented robust error handling using typed errors and errors.Is() instead
of fragile strings.Contains() matching. This decouples the HTTP layer from
service implementation details and prevents errors from being miscategorized
if error messages change.
Changes:
- Added typed error variables to weed/iam/sts/constants.go:
* ErrTypedTokenExpired
* ErrTypedInvalidToken
* ErrTypedInvalidIssuer
* ErrTypedInvalidAudience
* ErrTypedMissingClaims
- Updated STS service to wrap provider authentication errors with typed errors
- Replaced strings.Contains() with errors.Is() in HTTP layer for error checking
- Removed TODO comment as the improvement is now implemented
This makes error handling more maintainable and reliable.
* sts: eliminate all string-based error matching with provider-level typed errors
Completed the typed error implementation by adding provider-level typed errors
and updating provider implementations to return them. This eliminates ALL
fragile string matching throughout the entire error handling stack.
Changes:
- Added typed error definitions to weed/iam/providers/errors.go:
* ErrProviderTokenExpired
* ErrProviderInvalidToken
* ErrProviderInvalidIssuer
* ErrProviderInvalidAudience
* ErrProviderMissingClaims
- Updated OIDC provider to wrap JWT validation errors with typed provider errors
- Replaced strings.Contains() with errors.Is() in STS service for error mapping
- Complete error chain: Provider -> STS -> HTTP layer, all using errors.Is()
This provides:
- Reliable error classification independent of error message content
- Type-safe error checking throughout the stack
- No order-dependent string matching
- Maintainable error handling that won't break with message changes
* oidc: use jwt.ErrTokenExpired instead of string matching
Replaced the last remaining string-based error check with the JWT library's
exported typed error. This makes the error detection independent of error
message content and more robust against library updates.
Changed from:
strings.Contains(errMsg, "expired")
To:
errors.Is(err, jwt.ErrTokenExpired)
This completes the elimination of ALL string-based error matching throughout
the entire authentication stack.
* iam: add description length validation to UpdateServiceAccount
Fixed inconsistency where UpdateServiceAccount didn't validate description
length against MaxDescriptionLength, allowing operational limits to be
bypassed during updates.
Now validates that updated descriptions don't exceed 1000 characters,
matching the validation in CreateServiceAccount.
* iam: refactor expiration check into helper method
Extracted duplicated credential expiration check logic into a helper method
to reduce code duplication and improve maintainability.
Added Credential.isCredentialExpired() method and replaced 5 instances of
inline expiration checks across auth_signature_v2.go and auth_signature_v4.go.
* iam: address critical Copilot security and consistency feedback
Fixed three critical issues identified by Copilot code review:
1. SECURITY: Prevent loading disabled service account credentials
- Added check to skip disabled service accounts during credential loading
- Disabled accounts can no longer authenticate
2. Add DurationSeconds validation for STS AssumeRoleWithWebIdentity
- Enforce AWS-compatible range: 900-43200 seconds (15 min - 12 hours)
- Returns proper error for out-of-range values
3. Fix expiration update consistency in UpdateServiceAccount
- Added key existence check like Description field
- Allows explicit clearing of expiration by setting to empty string
- Distinguishes between "not updating" and "clearing expiration"
* sts: remove unused durationSecondsStr variable
Fixed build error from unused variable after refactoring duration parsing.
* iam: address remaining Copilot feedback and remove dead code
Completed remaining Copilot code review items:
1. Remove unused getPermission() method (dead code)
- Method was defined but never called anywhere
2. Improve slice modification safety in DeleteServiceAccount
- Replaced append-with-slice-operations with filter pattern
- Avoids potential issues from mutating slice during iteration
3. Fix route registration order
- Moved STS route registration BEFORE IAM route
- Prevents IAM route from intercepting STS requests
- More specific route (with query parameter) now registered first
* iam: improve expiration validation and test cleanup robustness
Addressed additional Copilot feedback:
1. Make expiration validation more explicit
- Added explicit check for negative values
- Added comment clarifying that 0 is allowed to clear expiration
- Improves code readability and intent
2. Fix test cleanup order in s3_service_account_test.go
- Track created service accounts in a slice
- Delete all service accounts before deleting parent user
- Prevents DeleteConflictException during cleanup
- More robust cleanup even if test fails mid-execution
Note: s3_service_account_security_test.go already had correct cleanup
order due to LIFO defer execution.
* test: remove redundant variable assignments
Removed duplicate assignments of createdSAId, createdAccessKeyId, and
createdSecretAccessKey on lines 148-150 that were already assigned on
lines 132-134.
This document describes the binary layout of the Needle structure as used in SeaweedFS storage, for all supported versions (v1, v2, v3).
A Needle represents a file or data blob stored in a volume file. The layout determines how the Needle is serialized to disk for efficient storage and retrieval.
Common Field Sizes
Field
Size (bytes)
Cookie
4
NeedleId
8
Size
4
DataSize
4
Flags
1
NameSize
1
MimeSize
1
LastModified
5
Ttl
2
PairsSize
2
Checksum
4
Timestamp
8
Needle Layouts by Version
Version 1
Offset
Field
Size (bytes)
Description
0
Cookie
4
Random number to mitigate brute force lookups
4
Id
8
Needle ID
12
Size
4
Length of Data
16
Data
N
File data (N = Size)
16+N
Checksum
4
CRC32 of Data
20+N
Padding
0-7
To align to 8 bytes
Version 2
Offset
Field
Size (bytes)
Description
0
Cookie
4
Random number
4
Id
8
Needle ID
12
Size
4
Total size of the following fields
16
DataSize
4
Length of Data (N)
20
Data
N
File data
20+N
Flags
1
Bit flags
21+N
NameSize
1 (opt)
Optional, if present
22+N
Name
M (opt)
Optional, if present (M = NameSize)
...
MimeSize
1 (opt)
Optional, if present
...
Mime
K (opt)
Optional, if present (K = MimeSize)
...
LastModified
5 (opt)
Optional, if present
...
Ttl
2 (opt)
Optional, if present
...
PairsSize
2 (opt)
Optional, if present
...
Pairs
P (opt)
Optional, if present (P = PairsSize)
...
Checksum
4
CRC32
...
Padding
0-7
To align to 8 bytes
Version 3
Offset
Field
Size (bytes)
Description
0
Cookie
4
Random number
4
Id
8
Needle ID
12
Size
4
Total size of the following fields
16
DataSize
4
Length of Data (N)
20
Data
N
File data
20+N
Flags
1
Bit flags
21+N
NameSize
1 (opt)
Optional, if present
22+N
Name
M (opt)
Optional, if present (M = NameSize)
...
MimeSize
1 (opt)
Optional, if present
...
Mime
K (opt)
Optional, if present (K = MimeSize)
...
LastModified
5 (opt)
Optional, if present
...
Ttl
2 (opt)
Optional, if present
...
PairsSize
2 (opt)
Optional, if present
...
Pairs
P (opt)
Optional, if present (P = PairsSize)
...
Checksum
4
CRC32
...
Timestamp
8
Append time in nanoseconds
...
Padding
0-7
To align to 8 bytes
Offsets marked with ... depend on the presence and size of previous optional fields.
Fields marked (opt) are optional and only present if the corresponding size or flag is non-zero.
N = DataSize, M = NameSize, K = MimeSize, P = PairsSize.
Field Explanations
Cookie: 4 bytes, random value for security.
Id: 8 bytes, unique identifier for the Needle.
Size: 4 bytes, total size of the Needle data section (not including header, checksum, timestamp, or padding).
Checksum: 4 bytes, CRC32 checksum of the Needle data.
Timestamp: 8 bytes, append time (only in v3).
Padding: 0-7 bytes, to align the total Needle size to 8 bytes.
Version Comparison Table
Field
v1
v2
v3
Cookie
✔
✔
✔
Id
✔
✔
✔
Size
✔
✔
✔
DataSize
✔
✔
Data
✔
✔
✔
Flags
✔
✔
NameSize/Name
✔
✔
MimeSize/Mime
✔
✔
LastModified
✔
✔
Ttl
✔
✔
PairsSize/Pairs
✔
✔
Checksum
✔
✔
✔
Timestamp
✔
Padding
✔
✔
✔
Flags Field Details
The Flags field (present in v2 and v3) is a bitmask that encodes several boolean properties of the Needle. Each bit has a specific meaning:
Bit Value
Name
Meaning
0x01
FlagIsCompressed
Data is compressed (isCompressed)
0x02
FlagHasName
Name field is present (NameSize/Name)
0x04
FlagHasMime
Mime field is present (MimeSize/Mime)
0x08
FlagHasLastModifiedDate
LastModified field is present
0x10
FlagHasTtl
Ttl field is present
0x20
FlagHasPairs
Pairs field is present (PairsSize/Pairs)
0x80
FlagIsChunkManifest
Data is a chunk manifest (for large files)
If a flag is set, the corresponding field(s) will appear in the Needle layout at the appropriate position.
The Flags field is always present in v2 and v3, immediately after the Data field.
Optional Fields
Fields marked as optional in the layout tables are only present if the corresponding flag in the Flags field is set (except for Name/Mime/Pairs, which also depend on their size fields being non-zero).
The order of optional fields is fixed and matches the order of their flags.
Special Notes
isCompressed: If set, the Data field is compressed (typically using gzip). This is indicated by the lowest bit (0x01) in the Flags byte.
isChunkManifest: If set, the Data field contains a manifest describing chunks of a large file, not raw file data.
All multi-byte fields are stored in big-endian order.
Padding is always added at the end to align the total Needle size to 8 bytes.
N = DataSize, M = NameSize, K = MimeSize, P = PairsSize in the layout tables above.
For more details, see the implementation in the corresponding Go files in this directory.
Chris Lu
ae9a943ef6