thingy-crypto-node 0.0.2 → 0.1.0

package/README.md

@@ -1,55 +1,100 @@
 # thingy-crypto-node 
 
 # Background
-Thingy Nodes usually have an assymetric keypair - this way all authentication works between the nodes in the thingy-ecosystem.
+Thingy Nodes usually have an asymmetric keypair - this way all authentication works between the nodes in the thingy-ecosystem.
 The thingy-crypto-node is the keeper of the keypair of this node - implementing all basic crypto functionality for this specific keypair.
 
+It is a convenience layer over [secret-manager-crypto-utils](https://www.npmjs.com/package/secret-manager-crypto-utils) - see there for the cryptographic details and security notes.
+
 # Usage
-Current Functionality
----------------------
-```coffescript
+```js
 import { ThingyCryptoNode } from "thingy-crypto-node"
 
-options = {
-    secretKeyHex: "..." # required
-    publicKeyHex: "..." # required
-    context: "..." # optional
-}
-cryptoNode = new ThingyCryptoNode(options)
+const cryptoNode = new ThingyCryptoNode({
+    secretKeyHex: "...", // required
+    publicKeyHex: "...", // required
+    context: "..."       // optional, default "standard ThingyCryptoNode"
+})
+```
 
+## Signing and Verifying
+```js
+const signatureHex = await cryptoNode.sign(content) // content: string
 
-## Signing and Verifiying
-content = STRING
-signatureHex = await cryptoNode.sign(content)
-signatureHex = STRINGHEX
+const err = await cryptoNode.sigCheck(signatureHex, content)
+if (err) throw new Error(err) // "Invalid signature!" or "Malformed input!"
+// valid from here
+```
+**`sigCheck` resolves `undefined` when the signature is valid** and an error string when it is not. It never throws.
+So the check is `if (err)` - and a forgotten `await` fails closed, because a Promise is truthy.
 
-true = await cryptoNode.verify(signatureHex, content)
+`sigCheck` checks signatures of this node's own key.
 
 ## Encrypting and Decrypting
-content = STRING
-secretsObject = await cryptoNode.encrypt(content)
-secretsObject = { referencePointHex, encryptedContentHex }
-secretsObject = { STRINGHEX, STRINGHEX }
-
-content = await cryptoNode.decrypt(secretsObject)
-
-## DiffieHellman For shared secret with specific foreign node
-id = STRINGHEX64
-salt = STRING
-timestamp = NUMBER
-sharedSecretHex = await cryptoNode.diffieHellmanFor(id, salt, timestamp)
-sharedSecretHex = STRINGHEX128
-
+Encrypts for this node's own key - e.g. for storing secrets only this node can read.
+```js
+const secretsObject = await cryptoNode.encrypt(content) // { referencePointHex, encryptedContentHex }
+const content = await cryptoNode.decrypt(secretsObject)
+```
+`decrypt` rejects with `Error("Decryption failed!")` on a wrong key or changed data.
+
+## Diffie-Hellman shared secret with a specific foreign node
+```js
+const sharedSecretHex = await cryptoNode.diffieHellmanFor(id, salt, timestamp)
+// id: the other node's publicKeyHex
+// salt: string, timestamp: number
+// sharedSecretHex: 128 hex chars (64 bytes)
+```
+Both nodes get the same secret when they use the same `salt`, `timestamp` and `context`.
+
+# Breaking Updates
+
+`0.0.x` -> `0.1.y`
+------------------
+Updated to secret-manager-crypto-utils 0.4 - new encryption format and new shared secrets.
+
+| 0.0.x | 0.1.x | What changed |
+|---|---|---|
+| `sign` | `sign` | nothing - same signatures |
+| `verify` → `true` when valid | `sigCheck` → `undefined` when valid | **removed, inverted meaning** - see below |
+| `encrypt` | `encrypt` | new format, 0.0.x cannot decrypt it |
+| `decrypt` | `decrypt` | reads the new format only |
+| `diffieHellmanFor` | `diffieHellmanFor` | different secret than 0.0.x |
+
+- `verify` is removed on purpose, so every old call fails loudly with `TypeError: cryptoNode.verify is not a function` - instead of silently accepting invalid signatures. Mind the inverted meaning:
+  ```js
+  // before
+  if (!(await cryptoNode.verify(sig, content))) return reject()
+  // now
+  if (await cryptoNode.sigCheck(sig, content)) return reject()
+  ```
+- Signatures are compatible both ways: 0.0.x nodes verify signatures of 0.1.x nodes and vice versa.
+
+## Legacy functions
+**Only for compatibility with data and nodes of 0.0.x. Never use them in new code. They will be removed in a future version.**
+
+| Function | 1:1 like 0.0.x | Use for |
+|---|---|---|
+| `verifyLegacy(sig, content)` | `verify` → `true` when valid (malformed input → `false` instead of throwing) | a quick fix until you switch to `sigCheck` |
+| `decryptLegacy(secretsObject)` | `decrypt` | reading data encrypted with 0.0.x -> encrypting it in new format is recommended |
+| `diffieHellmanForLegacy(id, salt, timestamp)` | `diffieHellmanFor` | nodes that still run 0.0.x shared secrets |
+
+Migrating encrypted data:
+```js
+let content
+try { content = await cryptoNode.decrypt(secretsObject) }
+catch { content = await cryptoNode.decryptLegacy(secretsObject) }
+secretsObject = await cryptoNode.encrypt(content) // store this one
 ```
 
----
-
-# Further steps
-
-- Add more features when the requirement pops up.
-
-
-All sorts of inputs are welcome, thanks!
+Talking to a node that still runs 0.0.x:
+```js
+const sharedSecretHex = peerIsLegacy
+    ? await cryptoNode.diffieHellmanForLegacy(id, salt, timestamp)
+    : await cryptoNode.diffieHellmanFor(id, salt, timestamp)
+```
+There is no way to detect a legacy node from the secret itself: you have to know which version the other node runs.
+Anything that was keyed with an old shared secret has to be re-derived.
 
 ---
 

package/index.js

@@ -1,44 +1,30 @@
-// Generated by CoffeeScript 2.7.0
-//###########################################################
-var defaultContext;
+import * as secUtl from "secret-manager-crypto-utils"
+import * as legacy from "secret-manager-crypto-utils/legacy"
 
-import * as secUtl from "secret-manager-crypto-utils";
+const defaultContext = "standard ThingyCryptoNode"
 
-//###########################################################
-defaultContext = "standard ThingyCryptoNode";
-
-//###########################################################
-export var ThingyCryptoNode = class ThingyCryptoNode {
-  constructor(o) {
-    this.key = o.secretKeyHex;
-    this.id = o.publicKeyHex;
-    this.ctx = o.context;
-    if (this.ctx == null) {
-      this.ctx = defaultContext;
+export class ThingyCryptoNode {
+    constructor(o) {
+        this.key = o.secretKeyHex
+        this.id = o.publicKeyHex
+        this.ctx = o.context ?? defaultContext
     }
-  }
-
-  //#######################################################
-  async sign(content) {
-    return (await secUtl.createSignatureHex(content, this.key));
-  }
-
-  async verify(sig, content) {
-    return (await secUtl.verifyHex(sig, this.id, content));
-  }
 
-  async encrypt(content) {
-    return (await secUtl.asymmetricEncryptHex(content, this.id));
-  }
-
-  async decrypt(secretsObj) {
-    return (await secUtl.asymmetricDecryptHex(secretsObj, this.key));
-  }
+    sign(content) { return secUtl.createSignature(content, this.key) }
+    // undefined when valid, an error string otherwise - never throws
+    sigCheck(sig, content) { return secUtl.verifySignature(sig, this.id, content) }
+    encrypt(content) { return secUtl.asymmetricEncrypt(content, this.id) }
+    decrypt(secretsObj) { return secUtl.asymmetricDecrypt(secretsObj, this.key) }
+    diffieHellmanFor(id, salt, timestamp) {
+        return secUtl.diffieHellmanSecretHash(this.key, id, contextFor(salt, this.ctx, timestamp))
+    }
 
-  async diffieHellmanFor(id, salt, timestamp) {
-    var context;
-    context = `${salt}:${this.ctx}_${timestamp}`;
-    return (await secUtl.diffieHellmanSecretHashHex(this.key, id, context));
-  }
+    // Legacy: 1:1 with thingy-crypto-node 0.0.x - only for compatibility, will be removed
+    async verifyLegacy(sig, content) { return !(await this.sigCheck(sig, content)) }
+    decryptLegacy(secretsObj) { return legacy.asymmetricDecryptV0_3_1(secretsObj, this.key) }
+    diffieHellmanForLegacy(id, salt, timestamp) {
+        return legacy.diffieHellmanSecretHashV0_3_1(this.key, id, contextFor(salt, this.ctx, timestamp))
+    }
+}
 
-};
+const contextFor = (salt, ctx, timestamp) => `${salt}:${ctx}_${timestamp}`

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "thingy-crypto-node",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "The thingy-crypto-node is the keeper of an ed25519 keypair, implementing all basic crypto functionality for this specific keypair",
   "main": "index.js",
+  "files": [
+    "index.js"
+  ],
   "keywords": [
     "thingy",
     "crypto",
@@ -13,7 +16,7 @@
     "diffie-hellman"
   ],
   "author": "Lenard Frommelt lenard@frommelt.dev",
-  "license": "CC0",
+  "license": "CC0-1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/JhonnyJason/thingy-crypto-node.git"
@@ -23,9 +26,12 @@
   },
   "homepage": "https://github.com/JhonnyJason/thingy-crypto-node-output#readme",
   "dependencies": {
-    "secret-manager-crypto-utils": "^0.3.1"
+    "secret-manager-crypto-utils": "^0.4.0"
   },
   "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   }

package/LICENSE

@@ -1,121 +0,0 @@
-Creative Commons Legal Code
-
-CC0 1.0 Universal
-
-    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
-    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
-    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
-    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
-    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
-    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
-    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
-    HEREUNDER.
-
-Statement of Purpose
-
-The laws of most jurisdictions throughout the world automatically confer
-exclusive Copyright and Related Rights (defined below) upon the creator
-and subsequent owner(s) (each and all, an "owner") of an original work of
-authorship and/or a database (each, a "Work").
-
-Certain owners wish to permanently relinquish those rights to a Work for
-the purpose of contributing to a commons of creative, cultural and
-scientific works ("Commons") that the public can reliably and without fear
-of later claims of infringement build upon, modify, incorporate in other
-works, reuse and redistribute as freely as possible in any form whatsoever
-and for any purposes, including without limitation commercial purposes.
-These owners may contribute to the Commons to promote the ideal of a free
-culture and the further production of creative, cultural and scientific
-works, or to gain reputation or greater distribution for their Work in
-part through the use and efforts of others.
-
-For these and/or other purposes and motivations, and without any
-expectation of additional consideration or compensation, the person
-associating CC0 with a Work (the "Affirmer"), to the extent that he or she
-is an owner of Copyright and Related Rights in the Work, voluntarily
-elects to apply CC0 to the Work and publicly distribute the Work under its
-terms, with knowledge of his or her Copyright and Related Rights in the
-Work and the meaning and intended legal effect of CC0 on those rights.
-
-1. Copyright and Related Rights. A Work made available under CC0 may be
-protected by copyright and related or neighboring rights ("Copyright and
-Related Rights"). Copyright and Related Rights include, but are not
-limited to, the following:
-
-  i. the right to reproduce, adapt, distribute, perform, display,
-     communicate, and translate a Work;
- ii. moral rights retained by the original author(s) and/or performer(s);
-iii. publicity and privacy rights pertaining to a person's image or
-     likeness depicted in a Work;
- iv. rights protecting against unfair competition in regards to a Work,
-     subject to the limitations in paragraph 4(a), below;
-  v. rights protecting the extraction, dissemination, use and reuse of data
-     in a Work;
- vi. database rights (such as those arising under Directive 96/9/EC of the
-     European Parliament and of the Council of 11 March 1996 on the legal
-     protection of databases, and under any national implementation
-     thereof, including any amended or successor version of such
-     directive); and
-vii. other similar, equivalent or corresponding rights throughout the
-     world based on applicable law or treaty, and any national
-     implementations thereof.
-
-2. Waiver. To the greatest extent permitted by, but not in contravention
-of, applicable law, Affirmer hereby overtly, fully, permanently,
-irrevocably and unconditionally waives, abandons, and surrenders all of
-Affirmer's Copyright and Related Rights and associated claims and causes
-of action, whether now known or unknown (including existing as well as
-future claims and causes of action), in the Work (i) in all territories
-worldwide, (ii) for the maximum duration provided by applicable law or
-treaty (including future time extensions), (iii) in any current or future
-medium and for any number of copies, and (iv) for any purpose whatsoever,
-including without limitation commercial, advertising or promotional
-purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
-member of the public at large and to the detriment of Affirmer's heirs and
-successors, fully intending that such Waiver shall not be subject to
-revocation, rescission, cancellation, termination, or any other legal or
-equitable action to disrupt the quiet enjoyment of the Work by the public
-as contemplated by Affirmer's express Statement of Purpose.
-
-3. Public License Fallback. Should any part of the Waiver for any reason
-be judged legally invalid or ineffective under applicable law, then the
-Waiver shall be preserved to the maximum extent permitted taking into
-account Affirmer's express Statement of Purpose. In addition, to the
-extent the Waiver is so judged Affirmer hereby grants to each affected
-person a royalty-free, non transferable, non sublicensable, non exclusive,
-irrevocable and unconditional license to exercise Affirmer's Copyright and
-Related Rights in the Work (i) in all territories worldwide, (ii) for the
-maximum duration provided by applicable law or treaty (including future
-time extensions), (iii) in any current or future medium and for any number
-of copies, and (iv) for any purpose whatsoever, including without
-limitation commercial, advertising or promotional purposes (the
-"License"). The License shall be deemed effective as of the date CC0 was
-applied by Affirmer to the Work. Should any part of the License for any
-reason be judged legally invalid or ineffective under applicable law, such
-partial invalidity or ineffectiveness shall not invalidate the remainder
-of the License, and in such case Affirmer hereby affirms that he or she
-will not (i) exercise any of his or her remaining Copyright and Related
-Rights in the Work or (ii) assert any associated claims and causes of
-action with respect to the Work, in either case contrary to Affirmer's
-express Statement of Purpose.
-
-4. Limitations and Disclaimers.
-
- a. No trademark or patent rights held by Affirmer are waived, abandoned,
-    surrendered, licensed or otherwise affected by this document.
- b. Affirmer offers the Work as-is and makes no representations or
-    warranties of any kind concerning the Work, express, implied,
-    statutory or otherwise, including without limitation warranties of
-    title, merchantability, fitness for a particular purpose, non
-    infringement, or the absence of latent or other defects, accuracy, or
-    the present or absence of errors, whether or not discoverable, all to
-    the greatest extent permissible under applicable law.
- c. Affirmer disclaims responsibility for clearing rights of other persons
-    that may apply to the Work or any use thereof, including without
-    limitation any person's Copyright and Related Rights in the Work.
-    Further, Affirmer disclaims responsibility for obtaining any necessary
-    consents, permissions or other rights required for any use of the
-    Work.
- d. Affirmer understands and acknowledges that Creative Commons is not a
-    party to this document and has no duty or obligation with respect to
-    this CC0 or use of the Work.