https://github.com/cyphrme/cozejs
Coze Javascript - cryptographic JSON messaging specification
https://github.com/cyphrme/cozejs
auth authentication coze cryptography cyphrme json jwt login
Last synced: 5 days ago
JSON representation
Coze Javascript - cryptographic JSON messaging specification
- Host: GitHub
- URL: https://github.com/cyphrme/cozejs
- Owner: Cyphrme
- License: bsd-3-clause
- Created: 2022-04-22T16:53:04.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2025-11-14T22:44:53.000Z (3 months ago)
- Last Synced: 2026-01-15T17:00:38.878Z (23 days ago)
- Topics: auth, authentication, coze, cryptography, cyphrme, json, jwt, login
- Language: JavaScript
- Homepage: https://cyphr.me/coze
- Size: 749 KB
- Stars: 5
- Watchers: 3
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
For Coze, please see the README in the [Main Coze Project.](https://github.com/Cyphrme/Coze)
For your project use `coze.min.js`.
# Developing Coze JS
## How to Build
##### Install esbuild
If using Go, esbuild can be installed with the following.
```
go install github.com/evanw/esbuild/cmd/esbuild@v0.15.8
```
[Alternatively, see esbuild's installation instructions.][1]
Also, [Coze JS npm](https://www.npmjs.com/package/coze).
##### Create the Coze distribution file.
(See [join.js](join.js) for more instructions.)
```
esbuild join.js --bundle --format=esm --minify --outfile=coze.min.js
cp coze.min.js verifier/coze.min.js
```
## Simple Coze Verifier
The simple verifier is self-contained in `/verifier`.
- [Cyphr.me hosted Power Coze Verifier](https://cyphr.me/coze)
- [Cyphr.me hosted Simple Coze Verifier](https://cyphr.me/coze_verifier_simple/coze.html)
- [Github.com hosted Simple Coze Verifier](https://cyphrme.github.io/CozeJS/verifier/coze.html)
To run the simple verifier locally, especially useful for local development, use
the Go server.
```sh
cd verifier
go run server.go
```
And then go to https://localhost:8082/coze.html in your browser.
## Testing
Coze uses BrowserTestJS
for running unit tests in the browser. The test can run as a [Github
page.](https://cyphrme.github.io/CozeJS/verifier/browsertest/browsertest.html)
For local development, use the Go server.
```sh
cd verifier/browsertest
go run server.go
```
Then go to `https://localhost:8082`.
# Coze Javascript Gotchas
- ⚠️ **Constant Time** ⚠️- Javascript is not constant time. Until there's something available
with constant time guarantees, like [constant time
WASM](https://cseweb.ucsd.edu/~dstefan/pubs/renner:2018:ct-wasm.pdf), this
library will be vulnerable to timing attacks as this problem is inherent to Javascript.
- ⚠️ **Duplicates** ⚠️- Duplicate detection is unavailable for Javascript objects
as Javascript objects always have unique fields with last-value-wins. (This of
course does not apply to strings or any serialized UTF-8 form). . The
solution Coze JS uses is that String/UTF-8/serialized form must be checked for
duplicates by calling function `CheckDuplicate`. This is slow and
unfortunate, but for security reasons required as different versions of
Javascript have different behaviors.
In ES5, duplicates should fail in strict mode, which is the correct behavior
for a JSON parser. ES6 experienced regression, and objects in ES6
terrifyingly permit duplicate fields with last-value-wins.
This is the wrong design decision for a plethora of reasons and the correct
behavior is error-on-duplicate, but there's nothing we can do about that on
our side without implementing our own primitives. As currently designed, no
JSON parsing is done within of Coze JS, and so Coze JS inherits the
last-value-wins behaviour from Javascript, thus the Coze JS provided function
`CheckDuplicate` must be called for correct behavior. See notes on
`test_Duplicate`.
See also https://github.com/json5/json5-spec/issues/38#issuecomment-1224158640
and https://262.ecma-international.org/5.1/#sec-C > It is a SyntaxError if
strict mode code contains an ObjectLiteral with more > than one definition of
any data property (11.1.5).
- **ES224 is not supported**. Even though [FIPS
186](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf) defines
curves P-224, the [W3C recommendation omits
it](https://www.w3.org/TR/WebCryptoAPI/#dfn-EcKeyGenParams) and thus is not
implemented in Javascript. The Javascript version of Coze will probably only
support ES256, ES384, and ES512.
- The W3C Web Cryptography API recommendation also omits Ed25519, so an external
package that implements the Ed25519 primitive is used. The upcoming update
[FIPS 186-5 section 7.8](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5-draft.pdf)
specifies Ed25519 support. Hopefully this will motivate Javascript to include
Ed25519. Also, [Paul has implemented Ed25519ph](
https://github.com/paulmillr/noble-ed25519/issues/63).
- TODO use Paul's curves library. Currently ESM builds are "broken", and we'll
wait for it to be polished. (The imports are using Typescript `@` imports and
not resolving to ESM files.)
Also, we'll preserve the current style somewhere so that we have a
SubtleCrypto backend that can be used.
- Javascript's `SubtleCrypto.sign(algorithm, key, data)` always hashes a message
before signing while Go's ECDSA expects a digest to sign. This means that in
Javascript messages must be passed for signing, while in Go only a digest is
needed.
----------------------------------------------------------------------
# Attribution, Trademark Notice, and License
Coze and CozeJS are released under The 3-Clause BSD License.
"Cyphr.me" is a trademark of Cypherpunk, LLC. The Cyphr.me logo is all rights
reserved Cypherpunk, LLC and may not be used without permission.
Coze is an open source project. Use at your own risk.
[1]:https://esbuild.github.io/getting-started/#build-from-source