-
Notifications
You must be signed in to change notification settings - Fork 0
/
typedef.js
159 lines (127 loc) · 5.88 KB
/
typedef.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
"use strict";
// Typedefs are not exported without `export` keyword present.
export {}
/**
General Notes See the Go implementation (Cyphrme/Coze) for full Coze
documentation.
Alg is a declarative abstraction for cryptographic functions for Coze. For more
on Alg, see the main Coze README, and the Go implementation, `alg.go`:
https://github.com/Cyphrme/Coze#readme
`can` is defined as type string[] and not type object. Some canon related
functions may permit a canon as type object and those functions should
explicitly document that usage. For those functions, if Can is object, only the
first level keys should be used and nested keys should be ignored.
In Coze, the message is always a "pay". "pay" is then hashed and the resulting
digest is signed.
*/
/**
@typedef {string} B64 b64ut (RFC 4648 base64 url truncated)
@typedef {B64} Dig A digest encoded as b64ut.
@typedef {string} Alg Algorithm in use, e.g. "ES256".
@typedef {number} Iat "Issued at" Unix time, e.g. 1623132000.
@typedef {Dig} Tmb Thumbprint, e.g. "cLj8vsYtMBwYkzoFVZHBZo6SNL8wSdCIjCKAwXNuhOk"
@typedef {string} Typ Type, e.g. "cyphr.me/msg"
@typedef {B64} Sig A cryptographic signature, e.g. "Jl8Kt4nznAf0LGgO5yn_9HkGdY3ulvjg-NyRGzlmJzhncbTkFFn9jrwIwGoRAQYhjc88wmwFNH5u_rO56USo_w"
@typedef {string} Kid Non-programmatic key identifier, e.g. "Zami's Majuscule Key."
@typedef {string[]} Can Canon, e.g. ["alg","iat","msg","tmb","typ"].
@typedef {Dig} Cad "Canonical digest" of `pay`, e.g. "Ie3xL77AsiCcb4r0pbnZJqMcfSBqg5Lk0npNJyJ9BC4"
@typedef {Dig} Czd "Coze digest" of `coze`, e.g. "TnRe4DRuGJlw280u3pGhMDOIYM7ii7J8_PhNuSScsIU"
@typedef {string} Msg A not-hashed, non-digest, "raw" message, e.g. `{"msg":"Coze Rocks","alg":"ES256","iat":1623132000,"tmb":"cLj8vsYtMBwYkzoFVZHBZo6SNL8wSdCIjCKAwXNuhOk","typ":"cyphr.me/msg"}`
@typedef {Key} SK Private Coze key, an object containing private component `d`.
@typedef {Key} PK Public Coze key, an object containing `x` and not containing `d`.
@typedef {string} Gen Gen is the genus for an Alg (Level 1), e.g. "SHA2", "ECDSA".
@typedef {string} Fam Fam is the family for an Alg (Level 2), e.g. "SHA", "EC".
@typedef {string} Hsh Hsh is a hashing algorithm that results in a digest, e.g. "SHA-256".
@typedef {string} Crv Crv is the (elliptic) curve used for Alg, e.g. "P-256".
@typedef {string} Use Use is the use for Alg, e.g. "sig", "enc", "dig".
*/
/**
* Metadata object. [pay, key, iat, can, cad, czd, tmb, sig]
@typedef {object} Meta
@property {Alg} alg
@property {Iat} [iat]
@property {B64} [tmb]
@property {string} [typ]
@property {Can} can
@property {Cad} cad
@property {Sig} [sig]
@property {Czd} [czd]
*/
/**
Coze is a signed coze object. See Go implementation docs (Cyphrme/Coze).
- pay: The `pay`. See docs on Pay for more.
- sig: The B64 signature.
- cad: Canonical digest of `pay`. E.g. LSgWE4vEfyxJZUTFaRaB2JdEclORdZcm4UVH9D8vVto
- can: The canon of pay. E.g. ["alg", "iat", "msg", "tmb", "typ"]
- czd: "Coze digest" over `{"cad":...,"sig":...}`.
- key: Coze Key used to sign `coze`.
@typedef {object} Coze
@property {Pay} pay
@property {Sig} sig
@property {Cad} [cad]
@property {Can} [can]
@property {Czd} [czd]
@property {Key} [key]
*/
/**
Pay contains the standard `Coze.Pay` fields. See Go implementation docs (Cyphrme/Coze).
- alg: Algorithm. E.g. "ES256".
- iat: Unix time of signing. E.g. 1623132000.
- tmb: Signing thumbprint E.g. cLj8vsYtMBwYkzoFVZHBZo6SNL8wSdCIjCKAwXNuhOk
- typ: Type. E.g. "cyphr.me/msg/create".
@typedef {object} Pay
@property {Alg} alg
@property {Iat} iat
@property {Tmb} tmb
@property {Typ} typ
*/
/**
Key holds a cryptographic key, with the minimum required fields for the
given `alg`. See Go implementation docs (Cyphrme/Coze).
*
-alg: Cryptographic signing or encryption algorithm - e.g. "ES256"
-kid: Human readable, non programmatic, key identifier - e.g. "Test Key"
-iat: Unix time key was created. e.g. 1624472390
-tmb: Key thumbprint e.g. "cLj8vsYtMBwYkzoFVZHBZo6SNL8wSdCIjCKAwXNuhOk"
-d: ECDSA private "d" component in b64ut. Required for ECDSA private Coze keys.
e.g. "bNstg4_H3m3SlROufwRSEgibLrBuRq9114OvdapcpVA"
-x: ECDSA public "x" component in b64ut. Required for ECDSA public Coze keys.
e.g. "2nTOaFVm2QLxmUO_SjgyscVHBtvHEfo2rq65MvgNRjORojq39Haq9rXNxvXxwba_Xj0F5vZibJR3isBdOWbo5g"
@typedef {object} Key
@property {Alg} alg
@property {Kid} kid
@property {Iat} iat
@property {B64} tmb
@property {B64} [d]
@property {B64} [x]
*/
/**
Params holds all relevant values for an `alg`. If values are not applicable
for a particular `alg`, values may be populated with the zero value, e.g.
for the hash alg "SHA-256" Curve's value is "" and XSize is 0.
-Name: Alg string Name.
-Genus: Genus E.g. "SHA2", "ECDSA".
-Family: Family E.g. "SHA", "EC".
-Hash: Hash is the hashing algorithm. E.g. "SHA-256".
-HashSize: Size in bytes of the digest. E.g. 32 for "SHA-256".
-SigSize: Size in bytes of the signature. E.g. 64 for "ES256".
-XSize: Size in bytes of `x`. E.g. "64" for ES256
-DSize: Size in bytes of `d`. E.g. "32" for ES256
-Curve: Curve is the elliptic curve. E.g. "P-256".
-Use: Algorithm use. E.g. "sig".
@typedef {object} Params
@property {string} Name
@property {Gen} Genus
@property {Fam} Family
@property {Use} Use
@property {Dig} Hash
@property {number} HashSize
@property {number} HashSizeB64
@property {number} XSize
@property {number} XSizeB64
@property {number} DSize
@property {number} DSizeB64
@property {Crv} Curve
@property {number} SigSize
@property {number} SigSizeB64
*/