@venn-lang/crypto 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# @venn-lang/crypto
+
+> The `crypto` namespace: digests, HMACs, base64, PBKDF2 password hashing and JSON Web Tokens.
+
+Auth flows need to mint a token, check a signature, or prove that a stored password is not the
+password. This package gives thirteen verbs for that. All of them run over the `CryptoEngine`
+port, whose real implementation is the platform's WebCrypto, so the package stays
+`platform: neutral` and needs no native module.
+
+## Install
+
+The package is part of the stdlib the `venn` CLI loads, so nothing to install. Reach it from a
+flow with a `use` line:
+
+```ruby
+use "venn/crypto"
+```
+
+The plugin requires no host capability: cryptography here is computation, not I/O.
+
+## Usage
+
+```ruby
+module demo.session
+
+use "venn/assert"
+use "venn/crypto"
+
+flow "A session token round-trips" {
+  const secret = "s3cret"
+
+  step "the password is stored hashed, never in the clear" {
+    const stored = crypto.password.hash "correct horse" { iterations: 1000 }
+    expect stored contains "pbkdf2$sha256$1000$"
+
+    let ok = crypto.password.verify "correct horse" { hash: stored }
+    expect ok == true
+
+    let wrong = crypto.password.verify "wrong horse" { hash: stored }
+    expect wrong == false
+  }
+
+  step "the token verifies, and its claims read back" {
+    const token = crypto.jwt.sign { payload: { sub: "alice" }, secret: secret }
+
+    let ok = crypto.jwt.verify token { secret: secret }
+    expect ok == true
+
+    const decoded = crypto.jwt.decode token
+    expect decoded.header.alg == "HS256"
+    expect decoded.payload.sub == "alice"
+  }
+}
+```
+
+## Verbs
+
+| Verb | Options | Gives back |
+| --- | --- | --- |
+| `crypto.hash data` | `algorithm` (`sha1`, `sha256`, `sha384`, `sha512`; default `sha256`) | The digest, lowercase hex. |
+| `crypto.hmac data` | `key` (required), `algorithm` | The keyed digest, lowercase hex. |
+| `crypto.randomBytes` | `size` (default 16) | Random bytes, hex-encoded. |
+| `crypto.uuid` | none | A random v4 UUID. |
+| `crypto.base64.encode text` | none | Base64. |
+| `crypto.base64.decode text` | none | The original string. |
+| `crypto.base64url.encode text` | none | Base64url, the flavour JWT uses. |
+| `crypto.base64url.decode text` | none | The original string. |
+| `crypto.jwt.sign` | `payload` (required), `secret` (required), `algorithm` (`HS256`, `HS384`, `HS512`; default `HS256`) | The signed token. |
+| `crypto.jwt.verify token` | `secret` (required) | `true` when the signature matches. |
+| `crypto.jwt.decode token` | none | `crypto.Jwt`: `header`, `payload`, `signature`, `signingInput`. |
+| `crypto.password.hash password` | `iterations` (default 100000), `algorithm` (`sha256` or `sha512`) | The encoded hash. |
+| `crypto.password.verify password` | `hash` (required) | `true` when the password produced that hash. |
+
+`crypto.jwt.sign` reads everything from options, so nothing goes in argument position. The rest
+take their subject positionally.
+
+### Passwords
+
+`crypto.password.hash` uses PBKDF2, not bcrypt: WebCrypto offers PBKDF2, which keeps this package
+free of a native dependency. The result is self-describing, so verifying needs nothing but the
+string itself:
+
+```
+pbkdf2$sha256$100000$<salt>$<derived>
+```
+
+A fresh 16-byte salt is drawn per call, so hashing the same password twice gives two different
+strings and both verify. Comparison is constant-time.
+
+### Tokens
+
+`crypto.jwt.decode` splits and decodes a token **without verifying it**. Reading a token's claims
+and trusting them are two different acts, and `crypto.jwt.verify` is the second one. A token that
+is not base64url-encoded JSON raises `VN7003`. Verification recomputes the HMAC over the token's
+own `signingInput` and compares in constant time, so a payload edited after signing fails.
+
+## The CryptoEngine port
+
+`venn.port.crypto-engine`, contract version 1, requires no capability, four methods: `digest`,
+`hmac`, `derive`, `randomBytes`. Everything returns lowercase hex, which is the one shape the
+verbs convert from.
+
+| Implementation | Behaviour |
+| --- | --- |
+| `createWebCryptoEngine()` | The real one, backed by `crypto.subtle`. Available in Node 24 and in browsers. |
+| `createFakeCryptoEngine()` | Deterministic FNV-1a stand-in. Same input, same output, never secure; it exists so a flow's assertions replay. |
+
+Both run the same conformance suite. The stdlib binds the **real** engine by default, even though
+it binds fakes for everything else: hashing is pure computation, not a side effect, so there is
+nothing to isolate a test from.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `cryptoPlugin` | The `PluginDefinition` for the `crypto` namespace. |
+| `CryptoEnginePort` | The port descriptor. |
+| `CryptoEngine`, `DeriveArgs`, `HashAlgorithm` | The interface an engine satisfies, its `derive` arguments, and the four digests. |
+| `createWebCryptoEngine`, `createFakeCryptoEngine` | The two implementations. |
+| `decodeJwt(token)`, `DecodedJwt` | The splitter behind `crypto.jwt.decode`, usable directly. |
+| `toBytes`, `fromBytes` | String to `Uint8Array` and back, UTF-8. |
+| `toHex`, `fromHex` | Bytes to lowercase hex and back. |
+| `toBase64`, `fromBase64` | Bytes to base64 and back. |
+| `toBase64Url`, `fromBase64Url` | The same, with `+/` as `-_` and no padding. |
+| `equals(left, right)` | Constant-time string comparison, so a verification cannot be timed. |
+
+The plugin publishes one named type, `crypto.Jwt`. Every other verb answers with a string or a
+boolean, which the signature says inline.
+
+## See also
+
+- [`@venn-lang/data`](../std-data) for the passwords and identities to hash.
+- [`@venn-lang/auth`](../std-auth) for building the headers a token goes into.
+- [`@venn-lang/contracts`](../contracts) for `Port`, `Host` and capability negotiation.

package/dist/index.d.ts

@@ -0,0 +1,131 @@
+import { Port } from "@venn-lang/contracts";
+import { PluginDefinition } from "@venn-lang/sdk";
+//#region src/bytes/bytes.d.ts
+/** Bytes backed by a plain `ArrayBuffer`, the only shape WebCrypto accepts. */
+type Bytes = Uint8Array<ArrayBuffer>;
+/** UTF-8 encode a string. */
+declare function toBytes(text: string): Bytes;
+/** UTF-8 decode bytes back to a string. Invalid sequences become the replacement character. */
+declare function fromBytes(bytes: Uint8Array): string;
+/** Lowercase hex, two characters per byte. */
+declare function toHex(bytes: Uint8Array): string;
+/** Read a hex string back into bytes. A trailing odd character is dropped. */
+declare function fromHex(hex: string): Bytes;
+/** Standard base64, padded. */
+declare function toBase64(bytes: Uint8Array): string;
+/**
+ * Read standard base64 back into bytes.
+ *
+ * @throws DOMException when the text is not valid base64.
+ */
+declare function fromBase64(text: string): Bytes;
+/** Base64url, the flavour JWT uses: `+/` become `-_` and padding is dropped. */
+declare function toBase64Url(bytes: Uint8Array): string;
+/**
+ * Read base64url back into bytes, restoring the padding first.
+ *
+ * @throws DOMException when the text is not valid base64url.
+ */
+declare function fromBase64Url(text: string): Bytes;
+/**
+ * Compare two strings in time that does not depend on where they differ.
+ *
+ * Use this for every signature and digest check: `===` returns early on the
+ * first mismatched byte, which leaks the correct prefix to a patient attacker.
+ */
+declare function equals(left: string, right: string): boolean;
+//#endregion
+//#region src/port/crypto-engine.types.d.ts
+/** The digests every engine supports. */
+type HashAlgorithm = "sha1" | "sha256" | "sha384" | "sha512";
+/** Arguments for {@link CryptoEngine.derive}: a password plus its PBKDF2 cost parameters. */
+interface DeriveArgs {
+  password: string;
+  salt: string;
+  iterations: number;
+  algorithm: HashAlgorithm;
+}
+/**
+ * The primitives every `crypto` verb is built from.
+ *
+ * Each method answers in lowercase hex. That single shape is what the actions
+ * convert from, so an engine that returned bytes would break every caller.
+ */
+interface CryptoEngine {
+  digest(args: {
+    algorithm: HashAlgorithm;
+    data: string;
+  }): Promise<string>;
+  hmac(args: {
+    algorithm: HashAlgorithm;
+    key: string;
+    data: string;
+  }): Promise<string>;
+  derive(args: DeriveArgs): Promise<string>;
+  randomBytes(size: number): string;
+}
+//#endregion
+//#region src/port/crypto-engine.port.d.ts
+/**
+ * The port every `crypto` verb reaches its primitives through.
+ *
+ * Bound by the host to `createWebCryptoEngine` or `createFakeCryptoEngine`.
+ * Requires no capability, because WebCrypto is present on every target.
+ */
+declare const CryptoEnginePort: Port<CryptoEngine>;
+//#endregion
+//#region src/engines/fake-engine.d.ts
+/**
+ * A deterministic stand-in for tests: same input, same output, no platform crypto.
+ *
+ * Not secure and not meant to be. It exists so assertions over a digest, an HMAC
+ * or a random token stay reproducible from run to run.
+ */
+declare function createFakeCryptoEngine(): CryptoEngine;
+//#endregion
+//#region src/engines/web-crypto-engine.d.ts
+/**
+ * The real engine, backed by the platform's global WebCrypto.
+ *
+ * WebCrypto exists in Node 24 and in browsers alike, so nothing here imports
+ * `node:crypto` and the package stays platform-neutral.
+ */
+declare function createWebCryptoEngine(): CryptoEngine;
+//#endregion
+//#region src/jwt/jwt.types.d.ts
+/** A JWT taken apart, verified or not. */
+interface DecodedJwt {
+  header: Record<string, unknown>;
+  payload: Record<string, unknown>;
+  /** The third section, still base64url. Empty when the token carries none. */
+  signature: string;
+  /** `header.payload`, exactly the bytes the signature covers. */
+  signingInput: string;
+}
+//#endregion
+//#region src/jwt/decode.d.ts
+/**
+ * Split a token and decode its header and payload, without verifying anything.
+ *
+ * Reading a token's claims and trusting them are separate acts. This is the
+ * first; `crypto.jwt.verify` is the second.
+ *
+ * @param token A compact JWS, `header.payload.signature`.
+ * @returns The decoded sections plus the `signingInput` a signature covers.
+ * @throws VennError `VN7003` when the token has fewer than two sections, or when
+ * a section is not base64url-encoded JSON.
+ */
+declare function decodeJwt(token: string): DecodedJwt;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `crypto` plugin: digests, encodings, password hashing and JSON Web Tokens.
+ *
+ * Every primitive comes from `CryptoEnginePort`, so a host can swap WebCrypto for
+ * the deterministic fake and keep assertions reproducible. No capability is
+ * required: WebCrypto is present in Node and in the browser alike.
+ */
+declare const cryptoPlugin: PluginDefinition;
+//#endregion
+export { type CryptoEngine, CryptoEnginePort, type DecodedJwt, type DeriveArgs, type HashAlgorithm, createFakeCryptoEngine, createWebCryptoEngine, cryptoPlugin, decodeJwt, equals, fromBase64, fromBase64Url, fromBytes, fromHex, toBase64, toBase64Url, toBytes, toHex };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/bytes/bytes.ts","../src/port/crypto-engine.types.ts","../src/port/crypto-engine.port.ts","../src/engines/fake-engine.ts","../src/engines/web-crypto-engine.ts","../src/jwt/jwt.types.ts","../src/jwt/decode.ts","../src/plugin.ts"],"mappings":";;;;KAIY,QAAQ,WAAW;;iBAGf,QAAQ,eAAe;;iBAKvB,UAAU,OAAO;;iBAKjB,MAAM,OAAO;;iBAKb,QAAQ,cAAc;;iBAMtB,SAAS,OAAO;;;;;;iBAShB,WAAW,eAAe;;iBAK1B,YAAY,OAAO;;;;;;iBASnB,cAAc,eAAe;;;;;;;iBAW7B,OAAO,cAAc;;;;KC7DzB;;UAGK;EACf;EACA;EACA;EACA,WAAW;;;;;;;;UASI;EACf,OAAO;IAAQ,WAAW;IAAe;MAAiB;EAC1D,KAAK;IAAQ,WAAW;IAAe;IAAa;MAAiB;EACrE,OAAO,MAAM,aAAa;EAC1B,YAAY;;;;;;;;;;cCZD,kBAAkB,KAAK;;;;;;;;;iBCDpB,0BAA0B;;;;;;;;;iBCQ1B,yBAAyB;;;;UCfxB;EACf,QAAQ;EACR,SAAS;;EAET;;EAEA;;;;;;;;;;;;;;;iBCQc,UAAU,gBAAgB;;;;;;;;;;cCJ7B,cAAc"}