Documentation
¶
Overview ¶
Package runtimeaws provides fail-closed AWS runtime hardening helpers for Go Lambdas.
The package deliberately uses narrow STS interfaces and AppTheory's object-store contract rather than raw service clients. AssumeFirst eagerly assumes one role and proves its account identity before returning an ephemeral credentials provider. VerifyVersionedArtifact accepts only a version-pinned object whose returned version and archive-derived aggregate digest match the caller's pins.
Index ¶
Constants ¶
const ( // MaxVersionedArtifactBytes is the hard ceiling for one fetched release archive. MaxVersionedArtifactBytes int64 = 32 << 20 // MaxVersionedArtifactEntries is the hard ceiling for archive members. MaxVersionedArtifactEntries = 512 )
Variables ¶
var ( // ErrExpectedAccountNotConfigured means no non-empty expected account ID was provided. ErrExpectedAccountNotConfigured = errors.New("apptheory runtime aws: expected account is not configured") // ErrAssumeRoleFailed means STS did not return usable ephemeral credentials. ErrAssumeRoleFailed = errors.New("apptheory runtime aws: assume role failed") ErrCallerIdentityUnavailable = errors.New("apptheory runtime aws: caller identity is unavailable") // ErrAccountMismatch means the caller account ID did not equal the configured account ID. ErrAccountMismatch = errors.New("apptheory runtime aws: caller account does not match expected account") )
var ( // ErrArtifactInvalidRequest means bucket, key, or digest input was invalid. ErrArtifactInvalidRequest = errors.New("apptheory runtime aws: invalid versioned artifact request") // ErrArtifactVersionRequired means no non-empty S3 VersionId was pinned. ErrArtifactVersionRequired = errors.New("apptheory runtime aws: artifact version is required") ErrArtifactUnavailable = errors.New("apptheory runtime aws: versioned artifact is unavailable") // ErrArtifactVersionMismatch means S3 returned a different VersionId than requested. ErrArtifactVersionMismatch = errors.New("apptheory runtime aws: returned artifact version does not match requested version") // ErrArtifactArchiveInvalid means the object was not a bounded, regular-file tar archive. ErrArtifactArchiveInvalid = errors.New("apptheory runtime aws: versioned artifact archive is invalid") // ErrArtifactDigestMismatch means the archive-derived digest did not equal the pinned digest. ErrArtifactDigestMismatch = errors.New("apptheory runtime aws: versioned artifact digest does not match expected digest") )
Functions ¶
This section is empty.
Types ¶
type AccountAssertion ¶
type AccountAssertion struct {
State AccountAssertionState
ExpectedAccountID string
ActualAccountID string
}
AccountAssertion records the expected and observed account identity with an explicit state.
func AssertAccount ¶
func AssertAccount(ctx context.Context, client CallerIdentityAPI, expectedAccountID string) (AccountAssertion, error)
AssertAccount resolves the caller through STS and requires an exact account-ID match.
type AccountAssertionState ¶
type AccountAssertionState string
AccountAssertionState is the explicit outcome of an AWS account assertion.
const ( // AccountAssertionNotConfigured means the expected account ID was empty. AccountAssertionNotConfigured AccountAssertionState = "not_configured" // AccountAssertionAssumeFailed means STS could not establish assumed authority. AccountAssertionAssumeFailed AccountAssertionState = "assume_failed" AccountAssertionUnavailable AccountAssertionState = "unavailable" // AccountAssertionMismatch means caller identity was available but named another account. AccountAssertionMismatch AccountAssertionState = "mismatch" // AccountAssertionVerified means caller identity exactly matched the expected account. AccountAssertionVerified AccountAssertionState = "verified" )
type ArtifactEntry ¶
type ArtifactEntry struct {
Path string
// Mode is the normalized permission-relevant mode value used by attestation.
Mode int64
// contains filtered or unexported fields
}
ArtifactEntry is one regular-file member of a verified release archive. Content is available only through Bytes so callers cannot mutate the verified copy.
func (ArtifactEntry) Bytes ¶
func (e ArtifactEntry) Bytes() []byte
Bytes returns a defensive copy of the entry content.
func (ArtifactEntry) SHA256 ¶
func (e ArtifactEntry) SHA256() string
SHA256 returns the lower-case hexadecimal SHA-256 of the entry content.
type ArtifactVerificationState ¶
type ArtifactVerificationState string
ArtifactVerificationState is the explicit outcome of versioned-artifact verification.
const ( // ArtifactVerificationInvalidRequest means bucket, key, or digest input was invalid. ArtifactVerificationInvalidRequest ArtifactVerificationState = "invalid_request" // ArtifactVerificationVersionRequired means the request omitted its S3 VersionId pin. ArtifactVerificationVersionRequired ArtifactVerificationState = "version_required" ArtifactVerificationUnavailable ArtifactVerificationState = "unavailable" // ArtifactVerificationVersionMismatch means returned VersionId differed from the request. ArtifactVerificationVersionMismatch ArtifactVerificationState = "version_mismatch" // ArtifactVerificationArchiveInvalid means the fetched bytes were not a safe bounded tar. ArtifactVerificationArchiveInvalid ArtifactVerificationState = "archive_invalid" // ArtifactVerificationDigestMismatch means the archive-derived digest differed from the pin. ArtifactVerificationDigestMismatch ArtifactVerificationState = "digest_mismatch" // ArtifactVerificationVerified means all three F6 checks succeeded. ArtifactVerificationVerified ArtifactVerificationState = "verified" )
type AssumeFirstResult ¶
type AssumeFirstResult struct {
Assertion AccountAssertion
Credentials awssdk.CredentialsProvider
}
AssumeFirstResult carries verified account evidence and, only when verified, the ephemeral assumed credentials provider.
func AssumeFirst ¶
func AssumeFirst( ctx context.Context, assumer AssumeRoleAPI, identityFactory CallerIdentityFactory, request AssumeRoleRequest, ) (AssumeFirstResult, error)
AssumeFirst eagerly assumes a role, resolves caller identity using the assumed credentials, and returns authority only after the expected account is verified.
type AssumeRoleAPI ¶
type AssumeRoleAPI interface {
AssumeRole(context.Context, *sts.AssumeRoleInput, ...func(*sts.Options)) (*sts.AssumeRoleOutput, error)
}
AssumeRoleAPI is the narrow STS operation required by AssumeFirst.
type AssumeRoleRequest ¶
type AssumeRoleRequest struct {
RoleARN string
RoleSessionName string
ExternalID string
ExpectedAccountID string
}
AssumeRoleRequest is the bounded role-assumption contract used by AssumeFirst.
type CallerIdentityAPI ¶
type CallerIdentityAPI interface {
GetCallerIdentity(context.Context, *sts.GetCallerIdentityInput, ...func(*sts.Options)) (*sts.GetCallerIdentityOutput, error)
}
CallerIdentityAPI is the narrow STS operation required by AssertAccount.
type CallerIdentityFactory ¶
type CallerIdentityFactory func(awssdk.CredentialsProvider) CallerIdentityAPI
CallerIdentityFactory creates an STS identity client bound to assumed credentials.
Implementations should copy their base aws.Config, replace only Credentials with the supplied provider, and create an STS client from that copy.
type VersionedArtifact ¶
type VersionedArtifact struct {
State ArtifactVerificationState
RequestedVersionID string
ReturnedVersionID string
ExpectedDigest string
ActualDigest string
// contains filtered or unexported fields
}
VersionedArtifact records verification evidence and retains bytes only on success.
func VerifyVersionedArtifact ¶
func VerifyVersionedArtifact( ctx context.Context, store objectstore.Store, request VersionedArtifactRequest, ) (VersionedArtifact, error)
VerifyVersionedArtifact performs the F6 triple without fallback: it requests an exact VersionId, requires S3 to echo that VersionId, then re-hashes every regular archive member and compares the derived aggregate digest.
func (VersionedArtifact) ArchiveBytes ¶
func (a VersionedArtifact) ArchiveBytes() []byte
ArchiveBytes returns a defensive copy of the fetched tar retained after successful member verification. The aggregate digest attests parsed member paths, permission modes, and content bytes (and therefore content sizes), not every tar header or padding byte. Use Entries and ArtifactEntry.Bytes when consuming fully content-digest-attested member bytes.
func (VersionedArtifact) Entries ¶
func (a VersionedArtifact) Entries() []ArtifactEntry
Entries returns defensive copies of all verified regular-file members.
Source Files