fix: s/prepare/toGeneral

README.md

@@ -59,10 +59,17 @@ const signer = ES256KSigner(privkey)
 const payloadBlock = await encodePayload(payload)
 // sign the CID as a JWS using our signer
 const jws = await createJWS(toJWSPayload(payloadBlock), signer)
-// convert our JWS to a DagJWS for IPLD encoidng
-const dagJWS = dagJose.prepare(jws)
+
+// createJWS gives us a compact string form JWS, DAG-JOSE will accept both the
+// compact and general (object) form but a round-trip decode will always
+// result in the general form. If we want need `jws` to be isometric regardless
+// of whether it has been round-tripped through DAG-JOSE or straight out of
+// `createJWS()` we can call `toGeneral()` to ensure it is always in the
+// general form.
+// jws = dagJose.toGeneral(jws)
+
 // encode as a DagJWS IPLD block
-const jwsBlock = await Block.encode({ value: dagJWS, codec: dagJose, hasher: sha256 })
+const jwsBlock = await Block.encode({ value: jws, codec: dagJose, hasher: sha256 })
 
 // we now have two blocks, a signed envelope and a payload
 // DagJWS envelope:

example-signing-ipld.mjs

@@ -24,10 +24,17 @@ async function storeSigned (payload, privkey, store) {
   const payloadBlock = await encodePayload(payload)
   // sign the CID as a JWS using our signer
   const jws = await createJWS(toJWSPayload(payloadBlock), signer)
-  // convert our JWS to a DagJWS for IPLD encoidng
-  const dagJWS = dagJose.prepare(jws)
+
+  // createJWS gives us a compact string form JWS, DAG-JOSE will accept both the
+  // compact and general (object) form but a round-trip decode will always
+  // result in the general form. If we want need `jws` to be isometric regardless
+  // of whether it has been round-tripped through DAG-JOSE or straight out of
+  // `createJWS()` we can call `toGeneral()` to ensure it is always in the
+  // general form.
+  // jws = dagJose.toGeneral(jws)
+
   // encode as a DagJWS IPLD block
-  const jwsBlock = await Block.encode({ value: dagJWS, codec: dagJose, hasher: sha256 })
+  const jwsBlock = await Block.encode({ value: jws, codec: dagJose, hasher: sha256 })
 
   // we now have two blocks, a signed envelope and a payload
   // DagJWS envelope:

src/index.ts

@@ -59,7 +59,15 @@ function isDagJWE(jose: DagJWS | DagJWE | EncodedJWS | EncodedJWE): jose is DagJ
   )
 }
 
-export function prepare(jose: DagJWS | DagJWE | string): DagJWS | DagJWE {
+/**
+ * Create a properly formed DagJWS or DagJWE object, from either a DagJWS, or
+ * DagJWE or the compact string form of either.
+ * Applying this function on an already valid DagJWS or DagJWE object will be
+ * idempotent. So this function can be used to either verify the proper object
+ * form, or expand a compact string form and ensure you have the same form
+ * of object that you would receive if you performed a round-trip encode/decode.
+ */
+export function toGeneral(jose: DagJWS | DagJWE | string): DagJWS | DagJWE {
   if (typeof jose === 'string') {
     const split = jose.split('.')
     if (split.length === 3) {
@@ -77,7 +85,7 @@ export function prepare(jose: DagJWS | DagJWE | string): DagJWS | DagJWE {
 
 export function encode(obj: DagJWS | DagJWE | string): ByteView<EncodedJWS | EncodedJWE> {
   if (typeof obj === 'string') {
-    obj = prepare(obj)
+    obj = toGeneral(obj)
   }
   let encodedJose
   if (isDagJWS(obj)) {

src/utils.ts

@@ -1,7 +1,7 @@
 import { base64url } from 'multiformats/bases/base64'
 
 export function toBase64url(b: Uint8Array): string {
-  return base64url.encode(b).slice(1)
+  return base64url.encode(b).slice(1) // remove multibase prefix
 }
 
 export function fromBase64url(s: string): Uint8Array {