[alanshaw]

A delete or a retention write that asks to bypass governance retention, with x-amz-bypass-governance-retention: true, needs s3:BypassGovernanceRetention in S3. Hilt had no such permission, so the header carried no decision here. This is the Hilt half of governance bypass; the gateway half stays as it is.

What changes

s3:BypassGovernanceRetention joins the vocabulary as a policy action, added by fil-forge/libforge#88 and now on libforge main, which this pins, and as a service-key permission. It maps to no Forge commands of its own, since the delete or retention write it rides on carries them.

The header is priced like the other header-added permissions: on DeleteObject, DeleteObjectVersion, DeleteObjects and PutObjectRetention, read on its first value case-insensitively as the gateway reads it, and only when the signature covers it. A service key must hold the permission and a principal's effective set must grant it.

What does not change

Ingot's gateway layer decides the bypass itself against the bucket's lock state, and today refuses it whatever the key holds, since it looks for the grant in a bucket policy document Ingot does not serve internally. So the permission has no effect on the wire yet: a request carrying the header is refused by Hilt without the permission, and by the gateway with it. The gateway hook that would honour Hilt's answer is the parked other half.

Behaviour changes to know about

• A request carrying the bypass header from a key or principal without the permission is now refused by Hilt as not permitted, where before it reached the gateway and was refused there. The outcome is the same; the refusing side moves.
• A bypass header the signature does not cover is refused as UnsignedHeader, like the lock headers.
• Keys issued with explicit permission lists, and policies that list actions, can now name s3:BypassGovernanceRetention.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

The narrow change follows existing authorization mechanisms, includes targeted regression coverage, and has no identified blocking issues.

No open issues 🎉

What changed in this PR

Adds Hilt-side authorization for governance-retention bypass requests using s3:BypassGovernanceRetention. Gateway enforcement remains unchanged, so this does not yet enable bypass on the wire.

Changes:

• Adds the permission to service-key vocabulary and pins libforge’s policy-action support.
• Requires the permission and a signed bypass header on applicable delete and retention operations.
• Adds classification and authorization tests for service keys and principal-bound keys.

File	Description
pkg/​s3perm/​s3perm.go	Registers the bypass permission without additional Forge commands.
pkg/​s3perm/​s3perm_test.go	Updates the expected policy-action count.
pkg/​rpc/​service/​auth/​operation.go	Adds bypass-header permission requirements.
pkg/​rpc/​service/​auth/​operation_test.go	Covers applicable operations and header-value handling.
pkg/​rpc/​service/​auth/​auth_test.go	Tests permission checks and unsigned-header rejection.
pkg/​bucketpolicy/​bucketpolicy_test.go	Includes bypass in object-resource action coverage.
go.sum	Updates libforge dependency checksums.
go.mod	Pins libforge with the new policy action.
AGENTS.md	Documents bypass-header authorization.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The localized change reuses existing authorization checks, includes focused regression coverage, and has no identified blocking issues.

No open issues 🎉

_{Review effort: Balanced}