[medium] SDK packaging blocks browser consumers: CJS-only barrel pulls Veil + WASM into every import

[nandal]

Two requests from building a browser client against @bytesbrains/maktub-sdk@0.1.0-dev.4. The first shapes how everything else gets consumed, so it's worth deciding before the second.

1. Packaging: a browser consumer cannot import the crypto without the Veil/WASM barrel

The package is CommonJS-only — main: dist/index.js, with no module field, no exports map, and no "type": "module". The barrel entry pulls everything unconditionally:

dist/index.js:122        require("./veil/veil.js")
dist/veil/veil.js:62     require("./wasm/warden_wasm.js")

So

import { deriveReadingKeyFromPrfOutput } from "@bytesbrains/maktub-sdk";

evaluates the Veil module and its WASM glue as a side effect of importing one HKDF function. Rollup/esbuild can't reliably tree-shake CommonJS, so it ends up in the bundle.

Why this matters more than bundle size

A browser client that derives reading keys wants the tightest possible CSP on that origin, because the derived key is long-lived and its published half is write-once — one injected script that reads it decrypts everything that user has ever received, unrotatably. script-src 'self' with no 'unsafe-eval' and no 'wasm-unsafe-eval' is achievable for a static bundle.

WebAssembly instantiation requires wasm-unsafe-eval. So if the WASM actually instantiates on import, a consumer either weakens the policy protecting the key-derivation origin, or can't use the SDK's crypto at all.

I've confirmed the glue is required at module-evaluation time; whether the .wasm binary itself instantiates eagerly or lazily depends on warden_wasm.js and I haven't measured that. Either way the structural problem stands: there is currently no way to ask for the crypto alone.

Request

An ESM build alongside CJS, and an exports subpath map, so consumers can import narrowly:

{
  "type": "module",
  "exports": {
    ".":        { "types": "./dist/index.d.ts",        "import": "./dist/index.js",        "require": "./dist/index.cjs" },
    "./crypto": { "types": "./dist/crypto/index.d.ts", "import": "./dist/crypto/index.js", "require": "./dist/crypto/index.cjs" },
    "./veil":   { "types": "./dist/veil/veil.d.ts",    "import": "./dist/veil/veil.js",    "require": "./dist/veil/veil.cjs" }
  }
}

@bytesbrains/maktub-sdk/crypto would then give derivation and ECIES with no Veil, no WASM, and no CSP implications. A "sideEffects": false flag would help bundlers further.

If a full dual build is too much for now, even an ESM build with the Veil re-export moved off the root barrel would solve the immediate problem.

2. Four pieces of smart-wallet client logic that don't exist in the SDK yet

Also missing, and each is a place where two language ports must agree byte-for-byte or a user lands on the wrong wallet / the chain rejects the signature:

Piece	Consequence of divergence
Counterfactual address derivation — CREATE2 over the ERC-1167 creation code with the implementation spliced in	A wrong address is an account that cannot be found, and a reading key published against it is stranded
P-256 public-key recovery from an ECDSA signature (SEC 1 §4.1.6)	Used to identify which credential signed an assertion; a mismatch in the candidate set breaks credential-based account discovery
WebAuthn codecs — DER signature parse, attestation-object CBOR parse, clientDataJSON type/challenge byte offsets	Feeds all of the above, plus the on-chain signature payload
PackedUserOperation encoding + the ERC-4337 v0.7 EntryPoint hash	Byte-exact or the operation is rejected

These already exist in the Dart client and are pinned there by ground-truth vectors. Porting them independently into each new client is exactly the divergence risk that vectors/reading-key.json exists to prevent for the reading key — and the same argument that made shipping that fixture inside the package worthwhile.

Housing them here, with cross-language vectors alongside the existing ones, means every port is checked against one artifact rather than trusted to reimplement four byte-exact constructions correctly.

Happy to contribute these if the direction is agreeable — in which case the packaging question above decides what the module boundaries should look like, so it's worth settling first.

[wrokin]

🤖 wrokin triage

The SDK is CommonJS-only with a barrel import that forces all consumers to load Veil and WASM, breaking browser CSP policies and preventing tree-shaking. Missing smart-wallet client logic pieces require byte-exact reimplementations across ports.

Suggested priority: medium
Labels applied: enhancement, security, help wanted
Possible duplicate: no

_{Model: deepseek/deepseek-v4-pro · your key, your model (BYOK)}

[nandal]

Part 1 is done and published — @bytesbrains/maktub-sdk@0.1.0-dev.5 is on npm, latest and dev both point at it. Landed in #40.

Your diagnosis held, and the part you flagged as unmeasured resolved the bad way. src/veil/wasm/warden_wasm.js is the nodejs wasm-bindgen target and instantiates at module-evaluation time:

const wasmBytes = require('fs').readFileSync(wasmPath);
const wasmModule = new WebAssembly.Module(wasmBytes);
let wasmInstance = new WebAssembly.Instance(wasmModule, __wbg_get_imports());

So it was eager — and because fs.readFileSync doesn't exist in a browser, the root barrel didn't merely cost you a CSP directive there, it couldn't load at all.

What shipped

Import	Contains	Pulls in
@bytesbrains/maktub-sdk	client, contracts, crypto, types, errors	ethers
@bytesbrains/maktub-sdk/crypto	derivation, ECIES, hybrid envelope	@noble/* only
@bytesbrains/maktub-sdk/veil	Veil (preview)	WebAssembly; Node only

Dual ESM+CJS, exports map, sideEffects declared. So this now does what you asked for:

import { deriveReadingKeyFromPrfOutput } from "@bytesbrains/maktub-sdk/crypto";

no Veil, no WASM, no wasm-unsafe-eval on the origin deriving reading keys.

Three notes on the implementation:

• src/veil is excluded from the ESM tsconfig, so the wasm-free property is structural rather than a convention a future re-export could quietly undo.
• @noble/curves and @noble/hashes are now declared dependencies. They were phantom deps — imported directly in six files under src/crypto/, in dependencies in none, resolving only because ethers hoisted them. Without that fix the new /crypto subpath would have failed to resolve under pnpm's strict layout or Yarn PnP, which would have defeated the point. Same versions ethers already pins, so nothing moved.
• npm run verify:packaging runs inside npm run build, so CI and the publish workflow both enforce it. It traps the WebAssembly constructors before importing /crypto, which covers the transitive graph rather than what a grep can see. sdk-publish.yml additionally checks every exports target is actually present in the tarball.

Verified by installing from the registry into a clean project — root and /crypto in both ESM and CJS, /veil still working, a crypto round-trip, and the deep data paths from dev.4 (/vectors/reading-key.json, /deployments/base-sepolia.json) still resolving under the new exports map. A browser bundle of /crypto via Vite is 88.7 kB with zero references to wasm, veil, or ethers.

Breaking: Veil moved off the package root to /veil (named exports unchanged), and deep paths into dist/ are no longer reachable. Migration note is in the changelog.

Part 2 is not done

Closing this issue, so to be explicit about what that leaves: the four smart-wallet pieces are not implemented. They should be tracked separately rather than treated as covered here.

For whoever picks it up — they do belong in this repo. The contracts they derive against are here (contracts/v3/wallet/: ERC-1167 Clones.cloneDeterministic, OZ WebAuthn/P256, 4337 v0.7 PackedUserOperation), deployments/base-sepolia.json already carries the factory and implementation, and vectors/ is the established home for byte-exact cross-language fixtures. The SDK has no wallet surface at all today, so it would be net-new rather than a move.

Two things want deciding first:

1. Whether the wallet layer belongs in the SDK or is app-layer, under "simplicity in the protocol, complexity in the app."
2. If it lands, it should be its own ./wallet subpath — which the packaging work here now makes cheap to add.

Thanks for the report; the CSP framing was the right way to argue it, and it's preserved in the code comments rather than only in the PR.

[nandal]

Correcting my comment above. I wrote "they do belong in this repo" about the part-2 pieces. That's stronger than I can defend, and it points in the wrong direction for three of the four.

The distinction I blurred: shipping vectors is not the same as shipping an implementation.

The argument in this issue for housing the four pieces here is that they must agree byte-for-byte across ports, like vectors/reading-key.json. That argument justifies publishing vectors. It doesn't justify the SDK growing a wallet layer. The precedent already set here is that vectors/ holds the byte-for-byte contract and each language port implements against it — which is exactly the stated goal, "every port is checked against one artifact rather than trusted to reimplement four byte-exact constructions correctly."

The test that sorts them: does the protocol break if this is wrong, or does one app break?

• A reading key derived wrong → letters unreadable forever, unrotatably. Protocol fault. That is why derivation is in the SDK.
• A userOp encoded wrong → that app's transaction reverts and the user retries. App fault.

By that test:

Piece
PackedUserOperation + ERC-4337 v0.7 EntryPoint hash	Not Maktub-specific in any way. viem and permissionless already implement it; housing it here means maintaining a mini-4337 library indefinitely.
WebAuthn codecs (DER, attestation CBOR, clientDataJSON)	The topology in CLAUDE.md already assigns passkeys to maktub_passkey. Duplicating them here contradicts that map.
P-256 public-key recovery	Generic crypto in service of credential discovery — app UX.
Counterfactual address derivation	The strongest case of the four, and still weaker than I implied. See below.

Two things I checked that weakened the last one:

1. RecipientRegistryV2.sol contains no reference to wallets, CREATE2, or derivation. The reading-key-to-derived-address binding is a client convention, not a contract invariant. So it is not protocol-critical in the way the 0.1.0-dev.4 changelog's framing suggests.
2. MaktubSmartWalletFactory.predictAddress(ownerX, ownerY, salt) is already a public view function on the deployed factory. A client that can make an RPC call can ask the chain rather than reimplement ERC-1167 CREATE2. Offline derivation is an optimisation, not a requirement.

Revised recommendation: publish vectors/smart-wallet.json covering all four constructions, and implement none of them in the SDK. One PR rather than four, no epic, and the SDK stays the protocol surface — consistent with "simplicity in the protocol, complexity in the app."

None of this affects part 1, which is shipped in 0.1.0-dev.5 and unaffected.

[nandal]

Proposed approach for part 2 — for the maktub-app team to sanity-check

New context since the comments above: maktub-app is Flutter for mobile and React for web, and part 2 was requested so both clients could share this logic. That changes the analysis, and I think it argues for a different shape than the issue proposed. Posting it here so whoever is working on maktub-app can say whether it actually meets their requirements.

The problem with "shared code"

Flutter is Dart. React is TypeScript. They cannot share code.

A TypeScript SDK does nothing for the Flutter client. So putting the four pieces in @bytesbrains/maktub-sdk would not produce shared code — it would produce a second implementation in TS alongside the Dart one, which this issue already notes exists ("These already exist in the Dart client and are pinned there by ground-truth vectors").

Two implementations are unavoidable. That's not a failure of the plan; it's the language boundary.

What can actually be shared

The only thing Dart and TypeScript can share is the contract between them — byte-exact inputs and expected outputs.

That's vectors, and it's the precedent this repo already set. vectors/reading-key.json exists for exactly this reason, and the issue's own argument invokes it. Vectors aren't a weaker substitute for shared code here; they're the only form of sharing that crosses the language boundary at all.

Where the TypeScript implementation should live

The Dart side already answered this. The Dart implementation is not inside a protocol SDK — it's maktub_passkey, a separate package on pub.dev, per the topology in CLAUDE.md.

The symmetric answer for the web client is a separate npm package mirroring it, not a @bytesbrains/maktub-sdk/wallet subpath.

Three reasons beyond symmetry:

1. The protocol SDK is about the protocol. Maktub does not care how you authenticate. A passkey wallet is a login method; an EOA works identically.
2. The wallet contracts are scheduled to leave this repo. Per the fork notice in MaktubSmartWallet.sol, they split out to a public base-passkey-wallet repo at mainnet. A separate passkey package can travel with them. A subpath of the protocol SDK would be stranded.
3. It keeps the SDK's public API stable. @bytesbrains/maktub-sdk/wallet would be a permanent published surface over contracts with a documented move date.

Proposed shape

What	Where	Status
vectors/smart-wallet.json — the cross-language contract	this repo	to build
Dart implementation	maktub_passkey	exists
TypeScript implementation	new npm package, mirroring the Dart one	to build
Protocol SDK	@bytesbrains/maktub-sdk	unchanged

The four constructions themselves are unchanged from the issue — counterfactual address derivation, P-256 recovery, WebAuthn codecs, PackedUserOperation + EntryPoint hash. Only their address changes.

Two notes for whoever builds the clients

Relying-party ID is account-critical, not a UX detail. ownerX/ownerY are the passkey public key, and the wallet address is CREATE2 over keccak256(ownerX ‖ ownerY ‖ salt). Different passkey → different key → different wallet. If the Flutter app and the React app don't share one RP ID, a user registers on web, opens mobile, and gets a second wallet — with their letters on the one they can't reach. That needs Apple associated domains (apple-app-site-association) and Android Digital Asset Links (assetlinks.json) resolving to the same RP ID the web app uses. It's configuration, not code, but it's the same class of fault this issue raised about stranded reading keys.

Getting that right shrinks the work. Piece 2 (P-256 recovery) exists to answer "which credential signed this?" when a user may have several. With one synced passkey across web and mobile, most users have exactly one credential and that question largely goes away.

What would change this recommendation

Genuinely open to being wrong. Concretely, it would change if:

• The web client needs something from the protocol SDK that the passkey package can't reach without a circular dependency.
• There's a reason two published packages is materially worse for the app than one — install friction, version-pinning pain across the Dart/TS pair, or similar.
• The wallet split-out at mainnet is no longer the plan, which removes reason 2 above.

If any of those hold, say so and the subpath argument gets a lot stronger.

[nandal]

Client-side perspective, since you asked for the sanity-check. Part 1 is confirmed working in a real consumer. On part 2 I agree with three of the four rows and think the TypeScript one rests on a premise that doesn't hold.

Part 1 — verified, and it does more than asked

Installed 0.1.0-dev.5 into a browser client and measured:

• @bytesbrains/maktub-sdk/crypto — derivation works, vectors pass, zero references to wasm, veil, or ethers in the emitted bundle. script-src 'self' with no wasm-unsafe-eval holds.
• The root barrel is also safe now. I imported deriveReadingKeyFromPrfOutput from . rather than /crypto expecting to catch the mistake — Veil still didn't reach the bundle. Rollup drops the unreached graph because of the narrow sideEffects declaration.
• ABIs are reachable without ethers. import { RECIPIENT_REGISTRY_ABI } from "@bytesbrains/maktub-sdk" adds 0.48 kB and pulls no ethers at all. I was about to ask for an /abis subpath; measured first, and it isn't needed.

So the sideEffects work is doing more than the subpath alone would. Worth knowing, because it means a consumer who imports from the root by mistake gets a working bundle rather than a white page.

And the eager-instantiation question resolved the bad way, as you found: the nodejs wasm-bindgen target calling fs.readFileSync at module-evaluation means the old barrel wouldn't have merely cost a CSP directive in a browser — it couldn't have loaded at all.

Agreed: vectors are the only thing that crosses the language boundary

The framing that two implementations are unavoidable and only the contract between them can be shared is right, and it's a better articulation than the one in my original issue. And the SDK staying unchanged is right.

The TypeScript row rests on a premise that isn't accurate

The Dart implementation is not inside a protocol SDK — it's maktub_passkey, a separate package on pub.dev

It isn't. All four constructions live in the app repo, not the plugin:

p256_recovery.dart          P-256 recovery
webauthn_codec.dart         DER, attestation CBOR, clientData offsets
smart_wallet_address.dart   CREATE2 + ERC-1167
user_operation.dart         PackedUserOperation + v0.7 EntryPoint hash

maktub_passkey is imported in exactly one file, and only for the platform ceremonies — ASAuthorization and CredentialManager. It owns platform integration; it holds none of the byte-exact constructions.

So the symmetric answer isn't "a package mirroring the Dart package." The Dart side already answered this question, and its answer was app code. Mirroring it means app code on the web side too.

Against the criteria you listed

You named install friction and version-pinning pain as something that would change the recommendation. Concretely, from this quarter: adopting the smart-wallet addresses needed a publish and a pin bump before the client could use them; so did this packaging fix. Both were the right call for protocol-level artifacts. But a second release train for code with one consumer puts a publish cycle in front of every codec fix, and there is nothing on the other side of it — no second consumer exists.

Extraction later, when one does, is cheap. Extraction now is speculative structure with a standing tax.

Reason 2 is your strongest — if the wallet contracts split to base-passkey-wallet at mainnet, code deriving against them wants to travel with them. I'd take that as an argument for extract at that point, not start as a package. The Dart side faces the identical pressure and hasn't extracted either; whatever is right for both is probably right for both at the same moment.

One correction on your second client note

Piece 2 (P-256 recovery) exists to answer "which credential signed this?" … With one synced passkey, most users have exactly one credential and that question largely goes away.

Recovery isn't answering which credential — it's answering what the public key is at all. A WebAuthn assertion never returns the credential's public key; only registration does. So on a browser with no stored state there is no other way to obtain ownerX/ownerY, and without those there is no address to look anything up by. There's no on-chain credentialId → owner index either.

It's structurally required for address-free sign-in regardless of how many credentials a user has. Worth knowing before it gets deprioritised in the vectors file.

The RP-ID warning — already handled, and thank you for stating it

It's the apex, it's a single constant in each client, and I removed the last defaulted override parameters from both ports this week precisely because the one value an override could realistically carry is the dangerous one: a subdomain RP ID is reachable, and it produces a different PRF output, a different reading key, and an account whose letters never open — with no error to explain it.

On the vectors' priority

Lower than my original issue implied, and your protocol-fault/app-fault test is why. All four constructions fail closed: wrong recovery → no account found; wrong codec → sign-in fails; wrong userOp encoding → a revert and a retry. None can orphan letters the way a wrong reading key can.

Also, MaktubSmartWalletFactory.predictAddress being a public view function removes the one case with an untidy failure — a client that can reach an RPC can ask the chain instead of deriving offline, which can't go stale against a redeploy either. We'll do that.

So the fixture is a quality and velocity aid rather than a safety requirement. Worth building; nothing waits on it.

Net: nothing further needed from this repo. Part 1 unblocked the client work completely.