fix(changeset): the protect-ffi 0.31.0 adoption is a patch, not a major

[coderdan]

The release PR (#859) currently proposes 2.0.0 for stash, @cipherstash/stack, @cipherstash/wizard and the three adapters. That comes from a single changeset (olive-pugs-invite.md) marked major, and the reasoning behind that mark is wrong.

What the changeset claimed

That a base64-encoded clientKey "worked on 1.x" and stops working after adopting protect-ffi 0.31.0, so upgrading breaks callers.

What is actually true

Hex has always been the documented and only supported encoding for config.clientKey / CS_CLIENT_KEY. It is what stash env emits, what the variable table in skills/stash-auth has always shown, and what every example uses. Nothing in the JavaScript stack has ever produced or accepted a base64 key.

Base64 is the on-disk encoding the Rust stash-profile crate uses for ~/.cipherstash/secretkey.json — handled entirely outside this SDK. The decoder underneath (SecretKey::from_hex) happened to fall back to standard padded base64, so a key pasted out of that file worked by accident.

Removing an undocumented decoder tolerance is not a breaking change to this package's contract, and it should not drag five other packages in the fixed group to 2.0.0.

Changes

• .changeset/olive-pugs-invite.md: major → patch, and the prose reframed — the narrowing is described as the removal of an unsupported spelling, with the troubleshooting hint kept (if construction starts failing, the key is not hex).
• .changeset/lucky-cows-repeat.md and skills/stash-auth/SKILL.md: the same "older versions also accepted base64, so a key copied out of that file worked" framing corrected. The skill still tells you the symptom and the fix — it just no longer implies a supported input was withdrawn.

The DynamoDB error-code narrowing in that changeset is unchanged and still described; it is a fix, not a breaking change.

Result

info Packages to be bumped at minor
 - stash 1.1.0
 - @cipherstash/stack 1.1.0
 - @cipherstash/stack-drizzle 1.1.0
 - @cipherstash/stack-prisma 1.1.0
 - @cipherstash/stack-supabase 1.1.0
 - @cipherstash/wizard 1.1.0
---
info Running release would release NO packages as a major

The 1.1.0 comes from the pre-existing minors (getSchemas(), the Lovable handoff target, eql migration --supabase), which are unaffected.

Merging this updates #859 in place.

Summary by CodeRabbit

• Documentation

  • Clarified that explicitly supplied client keys must use hex encoding.
  • Documented that base64-encoded keys are rejected during client construction and explained how to resolve the error.
  • Clarified the difference between explicit client keys and profile-store keys, which continue using base64 encoding.
  • Added guidance for native profile fallback and explicit configuration requirements in WASM environments.

• Release

  • Updated the @cipherstash/stack release classification to a patch release.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7829ee1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes changesets to release 11 packages

Name	Type
stash	Patch
@cipherstash/stack	Patch
@cipherstash/basic-example	Patch
@cipherstash/e2e	Patch
@cipherstash/bench	Patch
@cipherstash/stack-drizzle	Patch
@cipherstash/stack-prisma	Patch
@cipherstash/stack-supabase	Patch
@cipherstash/test-kit	Patch
@cipherstash/prisma-example	Patch
@cipherstash/wizard	Patch

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR updates authentication documentation to require hex-encoded explicit client keys, rejects base64 values during client construction, preserves base64 for profile-store keys, and changes the package release level from major to patch.

Changes

Client key encoding

Layer / File(s)	Summary
Release notes and encoding contract .changeset/olive-pugs-invite.md, .changeset/lucky-cows-repeat.md	The changeset now uses a patch release and documents hex encoding for explicit clientKey values. It states that non-hex values fail during client construction and that profile-store keys remain base64.
Authentication skill guidance skills/stash-auth/SKILL.md	The CS_CLIENT_KEY guidance now requires hex encoding and rejects base64 values copied from the profile store.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• cipherstash/stack#647: Both PRs modify Changesets release metadata for @cipherstash/stack.
• cipherstash/stack#834: This PR refines the stash-auth key-encoding guidance introduced there.
• cipherstash/stack#860: This PR refines the same CS_CLIENT_KEY and clientKey encoding documentation.

Suggested reviewers: tobyhede

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the primary change: correcting the protect-ffi 0.31.0 release classification from major to patch.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/changeset-not-a-major

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.changeset/olive-pugs-invite.md:
- Around line 7-15: Update the changeset text around the clientKey encoding
history to clarify that base64 was never intentionally supported or produced by
the JavaScript stack, but was accepted incidentally through the decoder’s
fallback; preserve the distinction between documented hex support and accidental
compatibility with copied profile keys.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fcfc912a-a36f-48f5-9bf0-ffeb6b25dc39

📥 Commits

Reviewing files that changed from the base of the PR and between 7785643 and 7829ee1.

📒 Files selected for processing (3)

• .changeset/lucky-cows-repeat.md
• .changeset/olive-pugs-invite.md
• skills/stash-auth/SKILL.md

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Correct the historical acceptance claim.

Line 14 says that the JavaScript stack never accepted a base64 key. The preceding text says that the decoder fallback accepted standard padded base64, and .changeset/lucky-cows-repeat.md says that copied profile keys happened to work. State that base64 was never intentionally supported or produced, but was accepted incidentally.

Proposed wording

-and nothing in the JavaScript stack ever produced or accepted a base64 key.
+and the JavaScript stack never intentionally produced or documented base64; the decoder nevertheless accepted it incidentally.

The PR objective states that base64 worked incidentally through decoder fallback.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	**`clientKey` is hex, and a decoder tolerance that accepted other spellings is
	gone.** Hex has always been the documented and only supported encoding for
	`config.clientKey` / `CS_CLIENT_KEY` — it is what `stash env` emits and what
	the docs and skills have always shown. The decoder underneath happened to fall
	back to standard padded base64, which is the encoding the Rust
	`stash-profile` crate uses for `~/.cipherstash/secretkey.json` on disk; that
	fallback was never part of this package's contract, and nothing in the
	JavaScript stack ever produced or accepted a base64 key. It is now rejected at
	client construction with `invalid clientKey: expected a hex-encoded key`.
	**`clientKey` is hex, and a decoder tolerance that accepted other spellings is
	gone.** Hex has always been the documented and only supported encoding for
	`config.clientKey` / `CS_CLIENT_KEY` — it is what `stash env` emits and what
	the docs and skills have always shown. The decoder underneath happened to fall
	back to standard padded base64, which is the encoding the Rust
	`stash-profile` crate uses for `~/.cipherstash/secretkey.json` on disk; that
	fallback was never part of this package's contract, and the JavaScript stack
	never intentionally produced or documented base64; the decoder nevertheless
	accepted it incidentally. It is now rejected at client construction with
	`invalid clientKey: expected a hex-encoded key`.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.changeset/olive-pugs-invite.md around lines 7 - 15, Update the changeset
text around the clientKey encoding history to clarify that base64 was never
intentionally supported or produced by the JavaScript stack, but was accepted
incidentally through the decoder’s fallback; preserve the distinction between
documented hex support and accidental compatibility with copied profile keys.