feat: implement toJSON methods (#72)

* chore: add toJSON to DID module

* feat: add to/from JSON to signatures

* chore: add toJSON method

* fix: test coverage

src/crypto.ts

@@ -1,4 +1,11 @@
-import type { ByteView, MulticodecCode } from "./ucan.js"
+import type {
+  ByteView,
+  MulticodecCode,
+  ToJSON,
+  ToString,
+  JSONUnknown,
+  UCAN,
+} from "./ucan.js"
 
 /**
  * Multicodec code corresponding to the byteprefix of the [VarSig]. It is
@@ -51,6 +58,13 @@ export interface Signature<T = unknown, Alg extends SigAlg = SigAlg>
   raw: Uint8Array
 }
 
+export type SignatureJSON<T extends Signature = Signature> = ToJSON<
+  T,
+  {
+    "/": { bytes: ToString<T> }
+  }
+>
+
 /**
  * Just like {@link Verifier}, except definitely async.
  */

src/did.js

@@ -86,7 +86,7 @@ export const decode = bytes => {
     case RSA:
     case P384:
     case P521:
-      return /** @type {UCAN.PrincipalView<ID>} */ (
+      return /** @type {UCAN.PrincipalView<any>} */ (
         new DIDKey(buffer, byteOffset, byteLength)
       )
     case DID_CORE:
@@ -118,6 +118,10 @@ class DID extends Uint8Array {
     const bytes = new Uint8Array(this.buffer, this.byteOffset + METHOD_OFFSET)
     return /** @type {ID} */ (`did:${UTF8.decode(bytes)}`)
   }
+
+  toJSON() {
+    return this.did()
+  }
 }
 
 /**

src/signature.js

@@ -1,6 +1,6 @@
 import * as UCAN from "./ucan.js"
 import { varint } from "multiformats"
-import { base64url } from "multiformats/bases/base64"
+import { base64url, base64 } from "multiformats/bases/base64"
 import * as UTF8 from "./utf8.js"
 
 export const NON_STANDARD = 0xd000
@@ -105,6 +105,10 @@ class Signature extends Uint8Array {
     Object.defineProperties(this, { raw: { value } })
     return value
   }
+
+  toJSON() {
+    return toJSON(this)
+  }
 }
 
 /**
@@ -255,3 +259,20 @@ export const parse = (signature, base) =>
   /** @type {UCAN.Signature<T, A>} */ (
     decode((base || base64url).decode(signature))
   )
+
+/**
+ * @template {UCAN.Signature} Signature
+ * @param {Signature} signature
+ * @returns {UCAN.SignatureJSON<Signature>}
+ */
+export const toJSON = signature => ({
+  "/": { bytes: base64.baseEncode(signature) },
+})
+
+/**
+ * @template {UCAN.Signature} Signature
+ * @param {UCAN.SignatureJSON<Signature>} json
+ * @returns {Signature}
+ */
+export const fromJSON = json =>
+  /** @type {Signature} */ (decode(base64.baseDecode(json["/"].bytes)))

src/ucan.ts

@@ -168,6 +168,22 @@ export interface Model<C extends Capabilities = Capabilities>
   s: Crypto.Signature<string>
 }
 
+export type UCANJSON<T extends UCAN = UCAN> = ToJSON<
+  T,
+  {
+    v: Version
+    iss: DID
+    aud: DID
+    s: Crypto.SignatureJSON
+    att: ToJSON<T["att"]>
+    prf: { "/": ToString<Link> }[]
+    exp: UTCUnixTimestamp
+    fct?: ToJSON<T["fct"]>
+    nnc?: Nonce
+    nbf?: UTCUnixTimestamp
+  }
+>
+
 export interface FromJWT<C extends Capabilities = Capabilities>
   extends Model<C> {
   jwt: JWT<C>
@@ -310,6 +326,34 @@ export type ToString<In, Out extends string = string> = Encoded<In, Out>
  */
 export type ToJSONString<In, Out extends string = string> = Encoded<In, Out>
 
+export type JSONScalar = null | boolean | number | string
+export type JSONObject = {
+  [key: string]: JSONUnknown | Phantom<unknown>
+}
+export type JSONUnknown = JSONScalar | JSONObject | JSONUnknown[]
+
+/**
+ * JSON representation
+ */
+export type ToJSON<In, Out extends JSONUnknown = IntoJSON<In>> = Encoded<
+  In,
+  Out
+>
+
+export type IntoJSON<T> = T extends JSONScalar
+  ? T
+  : T extends { toJSON(): infer U }
+  ? IntoJSON<U>
+  : T extends Array<infer U>
+  ? IntoJSON<U>[]
+  : T extends JSONObject
+  ? IntoJSONObject<T>
+  : never
+
+export type IntoJSONObject<T extends JSONObject> = {
+  [K in keyof T]: IntoJSON<T[K]>
+}
+
 /**
  * [Multicodec code] usually used to tag [multiformat].
  *

src/view.js

@@ -1,5 +1,12 @@
 import * as UCAN from "./ucan.js"
 import * as DID from "./did.js"
+import { encode as encodeJSON } from "@ipld/dag-json"
+import { decode as decodeUTF8 } from "./utf8.js"
+
+/**
+ * @param {unknown} data
+ */
+const toJSON = data => JSON.parse(decodeUTF8(encodeJSON(data)))
 
 /**
  * @template {UCAN.Capabilities} C
@@ -108,4 +115,26 @@ export class View {
   get prf() {
     return this.model.prf
   }
+
+  /**
+   * @returns {UCAN.ToJSON<UCAN.UCAN<C>, UCAN.UCANJSON<this>>}
+   */
+  toJSON() {
+    const { v, iss, aud, s, att, prf, exp, fct, nnc, nbf } = this.model
+
+    return {
+      iss,
+      aud,
+      v,
+      s,
+      exp,
+      ...toJSON({
+        att,
+        prf,
+        ...(fct.length > 0 && { fct }),
+      }),
+      ...(nnc != null && { nnc }),
+      ...(nbf && { nbf }),
+    }
+  }
 }

test/did.spec.js

@@ -26,4 +26,8 @@ describe("DID", () => {
   it("DID.encode <-> DID.decode", () => {
     assert.equal(DID.decode(DID.encode(alice)).did(), alice.did())
   })
+
+  it("JSON.stringify", () => {
+    assert.deepEqual(JSON.stringify(DID.parse(alice.did())), `"${alice.did()}"`)
+  })
 })

test/lib.spec.js

@@ -4,12 +4,13 @@ import { assert } from "chai"
 import { alice, bob, mallory, JWT_UCAN, JWT_UCAN_SIG } from "./fixtures.js"
 import * as TSUCAN from "./ts-ucan.cjs"
 import * as CBOR from "../src/codec/cbor.js"
+import * as Link from "multiformats/link"
 import { encode as encodeCBOR } from "@ipld/dag-cbor"
 import * as RAW from "multiformats/codecs/raw"
 import * as UTF8 from "../src/utf8.js"
 import * as DID from "../src/did.js"
 import { identity } from "multiformats/hashes/identity"
-import { base64url } from "multiformats/bases/base64"
+import { base64, base64url } from "multiformats/bases/base64"
 import {
   decodeAuthority,
   createRSAIssuer,
@@ -1065,8 +1066,6 @@ describe("encode <-> decode", () => {
 
     const { iss, aud, s, nnc, ...body } = model
 
-    console.log(body)
-
     const bytes = encodeCBOR({
       ...body,
       iss: DID.encode(iss),
@@ -1420,3 +1419,98 @@ describe("verify", () => {
     )
   })
 })
+
+describe("JSON.stringify", () => {
+  it("basic", async () => {
+    const expiration = UCAN.now()
+
+    const ucan = await UCAN.issue({
+      issuer: alice,
+      audience: bob,
+      capabilities: [
+        {
+          can: "store/put",
+          with: alice.did(),
+        },
+      ],
+      expiration,
+    })
+
+    assert.deepEqual(JSON.parse(JSON.stringify(ucan)), {
+      iss: alice.did(),
+      aud: bob.did(),
+      v: UCAN.VERSION,
+      s: { "/": { bytes: base64.baseEncode(ucan.signature) } },
+      exp: expiration,
+      att: [
+        {
+          can: "store/put",
+          with: alice.did(),
+        },
+      ],
+      prf: [],
+    })
+  })
+
+  it("proof-chain", async () => {
+    const nbf = UCAN.now()
+    const expiration = nbf + 100
+    const link = Link.parse(
+      "bafybeifpzwjvqgnael34taig2dqbp7snfhodyeh4yrmoqvvp2sks23n2hu"
+    )
+    /** @type {Link.Link<any, number, number, 1>} */
+    const proof = Link.parse(
+      "bafybeiduj5jlxuw6gfkqjivtn5vdin3ydqgshxiqplgrtyqscwisfi4iky"
+    )
+    const none = Link.parse("bafkqaaa")
+    const bytes = UTF8.encode("hello world")
+
+    const ucan = await UCAN.issue({
+      issuer: alice,
+      audience: bob,
+      capabilities: [
+        {
+          can: "store/put",
+          with: alice.did(),
+          nb: { link, bytes },
+        },
+      ],
+      notBefore: nbf,
+      nonce: "something",
+      expiration,
+      proofs: [proof],
+      facts: [{ none }, { bytes }],
+    })
+
+    assert.deepEqual(JSON.parse(JSON.stringify(ucan)), {
+      iss: alice.did(),
+      aud: bob.did(),
+      v: UCAN.VERSION,
+      s: { "/": { bytes: base64.baseEncode(ucan.signature) } },
+      exp: expiration,
+      nbf,
+      nnc: "something",
+      att: [
+        {
+          can: "store/put",
+          with: alice.did(),
+          nb: {
+            link: { "/": link.toString() },
+            bytes: { "/": { bytes: base64.baseEncode(bytes) } },
+          },
+        },
+      ],
+      prf: [
+        {
+          "/": proof.toString(),
+        },
+      ],
+      fct: [
+        { none: { "/": none.toString() } },
+        {
+          bytes: { "/": { bytes: base64.baseEncode(bytes) } },
+        },
+      ],
+    })
+  })
+})

test/signature.spec.js

@@ -6,7 +6,7 @@ import { alice, bob, mallory, JWT_UCAN, JWT_UCAN_SIG } from "./fixtures.js"
 import * as Signature from "../src/signature.js"
 import { varint } from "multiformats"
 import * as UTF8 from "../src/utf8.js"
-import { base64url } from "multiformats/bases/base64"
+import { base64url, base64 } from "multiformats/bases/base64"
 
 describe("Signature", () => {
   const dataset = [
@@ -69,13 +69,18 @@ describe("Signature", () => {
       assert.deepEqual(sig.code, code)
       assert.deepEqual(sig.algorithm, algorithm)
       assert.deepEqual(sig.raw, raw)
+      assert.deepEqual(
+        JSON.stringify(sig),
+        JSON.stringify({ "/": { bytes: base64.baseEncode(sig) } })
+      )
     })
 
     it(`roundtrip ${title}`, () => {
       const raw = UTF8.encode(`parse<->format ${title}`)
       const sig = Signature.createNamed(algorithm, raw)
 
       assert.deepEqual(sig, Signature.parse(Signature.format(sig)))
+      assert.deepEqual(sig, Signature.fromJSON(Signature.toJSON(sig)))
     })
   }