Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion INTEGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,18 @@ blob = encrypt(kr, ctx, b"ada@example.com")
assert decrypt(kr, ctx, blob) == b"ada@example.com"
```

`api/eg_crypto` is the Python package. `crates/encryptoglyph` is the Rust source of truth. Both check `testvectors/envelope.json`.
`api/eg_crypto` is the Python package. `crates/encryptoglyph` is the Rust source of truth. `@godesk/encryptoglyph` (`sdk/js`) is the Node.js 24 package. All three check `testvectors/envelope.json`.

```js
import { Keyring, encrypt, decrypt } from "@godesk/encryptoglyph";

const kr = new Keyring(kid, key);
const ctx = { tenant: "acme", purpose: "field", table: "customers", recordId: "42", field: "email" };
const blob = encrypt(kr, ctx, "ada@example.com");
if (Buffer.from(decrypt(kr, ctx, blob)).toString() !== "ada@example.com") throw new Error("round trip");
```

Install with `npm install ./sdk/js`, `npm install ./sdk/js/godesk-encryptoglyph-0.2.0.tgz`, or `npm install github:GoDeskio/Encryptoglyph#<ref>`. No `wasm-pack` step.

## Sidecar

Expand Down
44 changes: 29 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Encryptoglyph is an open-source encryption-at-rest library and self-hosted servi
| --- | --- |
| Rust envelope, HKDF, Argon2id, key rotation | Implemented and tested |
| Python module, wire-compatible with Rust | Implemented and tested |
| TypeScript wrapper over the WASM build | Source in `bindings/ts`; `wasm-pack` output is not committed |
| Node.js package `@godesk/encryptoglyph` | `sdk/js` and `bindings/ts`. Pure JS, Node >= 24, no `wasm-pack` step |
| `eg-api` container | `/healthz`, the `/v1` sidecar, and the console. Swagger, ReDoc, and `/openapi.json` are not served |
| OpenBao, Postgres 16, restic rest-server | Images and config in `deploy/docker-compose.yml`. The console reports them as not connected |
| Console | `console/`, served by the API. See [INTEGRATION.md](INTEGRATION.md) |
Expand All @@ -47,7 +47,7 @@ flowchart TB
subgraph crypto [shared XChaCha20-Poly1305 envelope]
rust[Rust crate]
python[Python eg_crypto]
ts[TypeScript WASM]
ts[Node.js envelope]
end
operator --> traefik
traefik --> console
Expand All @@ -62,7 +62,7 @@ flowchart TB

The lines from `eg-api` to OpenBao, Postgres, and rest-server are placement in the compose file, not live calls from the health handler.

![Architecture diagram: Traefik on proxy-net in front of the MSP console and API; OpenBao, Postgres, and restic rest-server on an internal network; Rust, Python, and TypeScript sharing one envelope](docs/img/architecture.svg)
![Architecture diagram: Traefik on proxy-net in front of the MSP console and API; OpenBao, Postgres, and restic rest-server on an internal network; Rust, Python, and Node.js sharing one envelope](docs/img/architecture.svg)

The SVG is the same layout: [docs/img/architecture.svg](docs/img/architecture.svg).

Expand Down Expand Up @@ -189,37 +189,51 @@ python -m pip install -r requirements-dev.txt
pytest
```

### TypeScript
### Node.js

`bindings/ts` is a thin wrapper around the WASM build of the Rust crate. Crypto stays in Rust. Build the package with wasm-pack, then compile the wrapper:
`@godesk/encryptoglyph` is plain ECMAScript in `sdk/js` (and the same envelope file in `bindings/ts`). It runs on Node.js 24 or newer and does not run `wasm-pack`. XChaCha20-Poly1305 uses HChaCha20 plus Node's ChaCha20-Poly1305. HKDF-SHA256 and Argon2id use `node:crypto`. The package decrypts `testvectors/envelope.json`.

From a checkout:

```bash
npm install ./sdk/js
node --test sdk/js/test/vectors.test.js
```

The Rust `wasm` feature still builds for `wasm32-unknown-unknown`. `fpe` and `blahaj` stay in the crate's main dependency table, and the wasm32 graph enables `getrandom` `js` plus `getrandom` 0.4 `wasm_js`. `bindings/ts` can still pack that feature when a browser build is needed:

```bash
cd bindings/ts
npm run build:wasm
npm run build
# Node services use the CommonJS package instead of the bundler target:
npm run build:wasm:node
node vector-test.cjs pkg-node
```

```ts
import { Keyring } from "@godesk/encryptoglyph";
Git installs use the repository root `package.json`, which points at the same files:

```bash
npm install github:GoDeskio/Encryptoglyph#<ref>
```

A packed tarball is `sdk/js/godesk-encryptoglyph-0.2.0.tgz`.

```js
import { Keyring, encrypt, decrypt } from "@godesk/encryptoglyph";

const key = crypto.getRandomValues(new Uint8Array(32));
const kr = new Keyring("k1", key);
const blob = kr.encrypt(
{ tenant: "acme", purpose: "field", table: "customers", recordId: "42", field: "email" },
new TextEncoder().encode("ada@example.com"),
);
const ctx = { tenant: "acme", purpose: "field", table: "customers", recordId: "42", field: "email" };
const blob = encrypt(kr, ctx, "ada@example.com");
const plain = decrypt(kr, ctx, blob);
```

The package is `private` and is not published to npm from this repository. `bindings/ts/pkg` is gitignored.
The browser sidecar client remains `sdk/js/encryptoglyph.js`. It calls `/v1` and does not seal locally. The envelope module is for Node, where `node:crypto` provides the primitives.

## Security model

- **Authenticated encryption.** Version 2 is XChaCha20-Poly1305-IETF. The header (magic, version, algorithm, key id, nonce) is part of the additional data, together with the canonical record context. Flipping the version or moving the blob between records fails authentication.
- **Key separation.** A root key never encrypts plaintext directly. HKDF-SHA256 derives a data key from the root key, the purpose, the tenant, and the algorithm. Password root keys use Argon2id with a 16-byte salt.
- **Rotation.** A `Keyring` encrypts with the current key id and can decrypt older ids. `rewrap` writes a fresh version-2 blob. The current key cannot be retired.
- **Rotation.** A `Keyring` encrypts with the current key id and can decrypt older ids. `rewrap` writes a fresh version-3 blob. The current key cannot be retired.
- **Uniform failures.** Decrypt errors do not distinguish a bad tag from a malformed header.
- **No backdoor in the library.** There is no escrow or override key in the Rust or Python code. Custody of root keys is an OpenBao operation. This console keeps session keys in process memory and says so.
- **Network.** Compose does not publish host ports. OpenBao's own UI is disabled. Postgres passwords come from the gitignored env file.
Expand Down
18 changes: 18 additions & 0 deletions bindings/ts/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# bindings/ts

TypeScript source for `@godesk/encryptoglyph`. The runtime is `js/envelope.js`, a byte-for-byte copy of `sdk/js/envelope.js`. Installing this directory does not run `wasm-pack` or `tsc`.

Node.js 24 or newer:

```bash
npm install ./bindings/ts
node --experimental-strip-types -e "import { Keyring } from '@godesk/encryptoglyph'"
```

From git:

```bash
npm install github:GoDeskio/Encryptoglyph#<ref>:bindings/ts
```

The repository-root package and `sdk/js` publish the same name and the same envelope. Use whichever path your installer accepts. Konektor (Node) should depend on the root package or `sdk/js`.
103 changes: 103 additions & 0 deletions bindings/ts/index.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
export const VERSION_LEGACY: 1;
export const VERSION_V2: 2;
export const VERSION_V3: 3;
export const ALG_AES256GCM: 1;
export const ALG_XCHACHA20POLY1305: 2;
export const ALG_XCHACHA20POLY1305_COMMIT: 3;
export const KEY_LEN: 32;
export const ARGON2_TIME: 3;
export const ARGON2_MEMORY_KIB: 262144;
export const ARGON2_PARALLELISM: 1;

export class DecryptError extends Error {}
export class DowngradeError extends DecryptError {}

export type Bytes = Uint8Array;

export interface RecordContextInit {
tenant: string;
purpose: string;
table: string;
recordId?: string;
record_id?: string;
field?: string;
schemaVersion?: number;
schema_version?: number;
}

export class RecordContext {
constructor(
tenant: string,
purpose: string,
table: string,
recordId: string,
field?: string,
schemaVersion?: number,
);
tenant: string;
purpose: string;
table: string;
recordId: string;
field: string;
schemaVersion: number;
aad(): Uint8Array;
}

export class Keyring {
constructor(kid: string, key: Bytes);
constructor(keys: Record<string, Bytes>, current: string);
static generateKey(): Uint8Array;
readonly current: string;
add(kid: string, key: Bytes, makeCurrent?: boolean): void;
retire(kid: string): void;
has(kid: string): boolean;
derive(kid: string, purpose: string, tenant: string, alg: number): Uint8Array;
encrypt(ctx: RecordContext | RecordContextInit | unknown[], plaintext: Bytes | string): Uint8Array;
decrypt(ctx: RecordContext | RecordContextInit | unknown[], blob: Bytes, minVersion?: number): Uint8Array;
rewrap(ctx: RecordContext | RecordContextInit | unknown[], blob: Bytes): Uint8Array;
needsRewrap(blob: Bytes): boolean;
}

export interface ParsedHeader {
version: number;
alg: number;
kid: string;
nonce: Uint8Array;
header: Uint8Array;
body: Uint8Array;
}

export function parseHeader(blob: Bytes): ParsedHeader;
export function encrypt(keyring: Keyring, ctx: RecordContext | RecordContextInit | unknown[], plaintext: Bytes | string): Uint8Array;
export function encryptWithNonce(
keyring: Keyring,
ctx: RecordContext | RecordContextInit | unknown[],
plaintext: Bytes | string,
nonce: Bytes,
): Uint8Array;
export function encryptV2(keyring: Keyring, ctx: RecordContext | RecordContextInit | unknown[], plaintext: Bytes | string): Uint8Array;
export function encryptLegacyV1(
keyring: Keyring,
ctx: RecordContext | RecordContextInit | unknown[],
plaintext: Bytes | string,
): Uint8Array;
export function decrypt(
keyring: Keyring,
ctx: RecordContext | RecordContextInit | unknown[],
blob: Bytes,
minVersion?: number,
): Uint8Array;
export function needsRewrap(keyring: Keyring, blob: Bytes): boolean;
export function rewrap(keyring: Keyring, ctx: RecordContext | RecordContextInit | unknown[], blob: Bytes): Uint8Array;
export function blindIndex(key: Bytes, tenant: string, field: string, value: string, length?: number): Uint8Array;
export function verifyBlindIndex(key: Bytes, tenant: string, field: string, value: string, expected: Bytes): boolean;
export function fingerprint(key: Bytes): string;
export function deriveRootKeyFromPassword(password: string | Bytes, salt: Bytes): Uint8Array;
export function deriveRootKeyWithParams(
password: string | Bytes,
salt: Bytes,
params?: { time?: number; memoryKiB?: number; parallelism?: number },
): Uint8Array;
export function hchacha20(key: Bytes, nonce16: Bytes): Uint8Array;
export function asContext(ctx: RecordContext | RecordContextInit | unknown[]): RecordContext;
export function normalizeBlindIndex(value: string): string;
Loading
Loading