Storacha Delegation Base64 Encoding Issue

[frrist]

Summary

Delegations created by storacha delegation create contain JWT tokens with standard base64 encoding instead of base64url encoding, causing parsing failures when loading delegations in @storacha/client.

Environment

• storacha CLI version: 1.6.32
• @storacha/client version: 1.8.20
• @web3-storage/access version: 20.3.0
• Node.js version: 20.19.1
• Platform: macOS

Steps to Reproduce

1. Create a delegation using the CLI:

storacha delegation create did:key:z6MkjBecPeTeaPzAjQ99ifWFLFGupUrthtKFapz7kct73qyo \
--can 'space/*' --can 'store/*' --can 'upload/*' \
--output delegation.car

2. Attempt to load the delegation in Node.js:

import * as ed25519 from '@ucanto/principal/ed25519'
import { create } from '@storacha/client'
import { StoreMemory } from '@storacha/client/stores/memory'
import { bytesToDelegations } from '@web3-storage/access/encoding'
import { readFileSync } from 'fs'

const agentKey = 'MgCYUSoC2FrOX4WaDPQxJxZJ2u6g0JvoIAo1KzQr6yWiUsu0BTMJ+dmC3SKMS6/iDQrjqhQoFmPNKnSi/ETIqeFoDzmM='
const spaceDid = 'did:key:z6MkjBecPeTeaPzAjQ99ifWFLFGupUrthtKFapz7kct73qyo'

const principal = ed25519.parse(agentKey)
const store = new StoreMemory()
const client = await create({ principal, store })

const bytes = readFileSync('delegation.car')
const delegations = bytesToDelegations(bytes)

await client.addProof(delegations[0]) // FAILS HERE
await client.setCurrentSpace(spaceDid)

Expected Behavior

The delegation should load successfully and authorize the agent to access the space.

Actual Behavior

Error occurs when calling client.addProof():

SyntaxError: Non-base64url character
at decode (file:///node_modules/multiformats/dist/src/bases/base.js:137:19)
at Codec.decode [as baseDecode] (file:///node_modules/multiformats/dist/src/bases/base.js:202:20)
at parseHeader (file:///node_modules/@ipld/dag-ucan/src/parser.js:36:51)
at parse (file:///node_modules/@ipld/dag-ucan/src/parser.js:23:24)
at Module.decode (file:///node_modules/@ipld/dag-ucan/src/codec/jwt.js:36:27)

Root Cause

The JWT tokens embedded in the CAR file use standard base64 encoding (with + and / characters) instead of base64url encoding (with - and _ characters) as required by the JWT/UCAN specification (RFC 4648 §5).

The @ipld/dag-ucan parser explicitly imports and uses base64url from multiformats:

import { base64url } from "multiformats/bases/base64"

But the JWT tokens in the delegation CAR file contain standard base64 characters, causing the parser to reject them.

Verification

The delegation CAR file starts with correct CBOR/CAR format (0x3a 0xa2), but the embedded UCAN tokens have encoding mismatches.

Impact

• Cannot programmatically load delegations in Lambda functions or server environments
• Blocks automation of space authorization workflows
• Prevents using delegations for service-to-service authentication

Workaround

None found. The storacha space add command also requires a valid delegation proof file.

Additional Context

This issue occurs consistently across multiple delegation creation attempts. The same error appears whether using:

• storacha delegation create --base64
• storacha delegation create --output file.car
• Different capability combinations

Request

Please investigate the delegation creation process in the storacha CLI to ensure JWT tokens are encoded using base64url (RFC 4648 §5) instead of standard base64.

---

Date: 2025-11-29
Reporter: BlockFact Team
Contact: egbert@blockfact.io

[NiKrause]

hi!

try:
1: Go to: https://bafybeid2ygpsn7762snsrhdq5ahwmrtym7gfxrbj76mzrj4fwxsz6rksn4.ipfs.dweb.link/ (or run https://github.com/NiKrause/ucan-upload-wall/tree/worker-keystore-encrypted-archive )
2. Authenticate with your Passkey to get a DID!
3. Then create a delegation: storacha delegation create did:key:z6MkpAgXxUPUayDYmduh3FQ4Mzutpkt1mD27C11NRJzQqWpj --base64
4. Go back to the Upload Wall and go to second tab and import the base64 delegation -
5. Go back to Upload Files: click "reload" or upload a file to your space
6. Checkout code base e.g. ucan-delegation.ts

Or try something like:

  const proof = await Proof.parse(credentials.proof);
  const space = await client.addSpace(proof);
  await client.setCurrentSpace(space.did());

P.S. in my case I import also the multibase-base64 format maybe you just need to convert it?

Let me know if it helps.
If not please provide a example project, so I could have a look!