Skip to content

fix(base64): use standard RFC 4648 alphabet on the text path (#87)#283

Merged
fredbi merged 1 commit into
go-openapi:masterfrom
fredbi:fix/base64-encoding-consistency
Jul 12, 2026
Merged

fix(base64): use standard RFC 4648 alphabet on the text path (#87)#283
fredbi merged 1 commit into
go-openapi:masterfrom
fredbi:fix/base64-encoding-consistency

Conversation

@fredbi

@fredbi fredbi commented Jul 12, 2026

Copy link
Copy Markdown
Member

strfmt.Base64 maps to OpenAPI format: byte, which OAI v2 defines as unqualified "base64 encoded characters".

Per RFC 4648, unqualified "base64" is the standard alphabet (section 4, +/); base64url (section 5, -_) is a separately named encoding the RFC says must not be called "base64".

Eight of the nine Base64 serialization paths already used StdEncoding (String, MarshalJSON/UnmarshalJSON, Scan/Value, MarshalBSON/UnmarshalBSON).

The lone outlier was the encoding.TextMarshaler/TextUnmarshaler pair, which used URLEncoding since PR #57.

The result: the same Base64 value serialized to a query parameter (text) versus a JSON body encoded differently whenever the payload hit alphabet index 62/63, breaking opaque tokens that cross boundaries.

Route every path through a single seam, base64Encoding = base64.StdEncoding, so the whole type now uses standard base64 and there is exactly one place to introduce a URL-safe variant later (see the type-parameterization work). The misleading "URLEncoding alphabet" godoc is corrected.

Behavioral change (patch-level spec-conformance fix): the text path now emits and accepts standard base64. base64url text that previously round-tripped via UnmarshalText will now be rejected. In practice this was rarely hit because consumers marshal via JSON even for parameters.

Change type

Please select: 🆕 New feature or enhancement|🔧 Bug fix'|📃 Documentation update

Short description

Fixes

Full description

Checklist

  • I have signed all my commits with my name and email (see DCO. This does not require a PGP-signed commit
  • I have rebased and squashed my work, so only one commit remains
  • I have added tests to cover my changes.
  • I have properly enriched go doc comments in code.
  • I have properly documented any breaking change.

…api#87)

strfmt.Base64 maps to OpenAPI `format: byte`, which OAI v2 defines as unqualified
"base64 encoded characters".

Per RFC 4648, unqualified "base64" is the standard alphabet (section 4, `+/`);
base64url (section 5, `-_`) is a separately named encoding the RFC says must not be called "base64".

Eight of the nine Base64 serialization paths already used StdEncoding (String,
MarshalJSON/UnmarshalJSON, Scan/Value, MarshalBSON/UnmarshalBSON).

The lone outlier was the encoding.TextMarshaler/TextUnmarshaler pair, which used URLEncoding since PR go-openapi#57.

The result: the same Base64 value serialized to a query parameter (text) versus a JSON body encoded differently
whenever the payload hit alphabet index 62/63, breaking opaque tokens that cross boundaries.

Route every path through a single seam, `base64Encoding = base64.StdEncoding`,
so the whole type now uses standard base64 and there is exactly one place to
introduce a URL-safe variant later (see the type-parameterization work). The
misleading "URLEncoding alphabet" godoc is corrected.

Behavioral change (patch-level spec-conformance fix): the text path now emits
and accepts standard base64. base64url text that previously round-tripped via
UnmarshalText will now be rejected. In practice this was rarely hit because
consumers marshal via JSON even for parameters.

* fixes go-openapi#87

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
@codecov

codecov Bot commented Jul 12, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.81%. Comparing base (7f8ff38) to head (a7a118b).
✅ All tests successful. No failed tests found.

Additional details and impacted files
@@           Coverage Diff           @@
##           master     #283   +/-   ##
=======================================
  Coverage   87.81%   87.81%           
=======================================
  Files          18       18           
  Lines        2471     2471           
=======================================
  Hits         2170     2170           
  Misses        208      208           
  Partials       93       93           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

@fredbi
fredbi merged commit 4de561f into go-openapi:master Jul 12, 2026
28 checks passed
@fredbi
fredbi deleted the fix/base64-encoding-consistency branch July 12, 2026 18:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Base64 type states that it represents URL encoded string but in JSON, it uses standard base64 encoding

1 participant