@octaviaflow/oflow

The format core for .oflow — OctaviaFlow's portable workflow artifact. Standalone, dependency-isolated, private (intended to live in a private Bitbucket repo). No app or business logic — only build / parse / sign / verify / encrypt / decrypt + the manifest schema.

Status: v0 scaffold. The cryptographic design below is implemented but must get an independent security review before any production / marketplace use. Don't ship secrets through it until reviewed.

What .oflow is

A .oflow file is NOT a readable zip. It is a fully-encrypted, signed binary container. Opened with a generic tool (unzip, an archive utility, a hex editor) you see only a tiny cleartext header and an opaque ciphertext blob — the workflow graph, the manifest, and any embedded credentials/keys are all inside the encrypted payload. Only a holder of the correct key (via this library) can decrypt it.

On-disk layout

┌─────────────────────────────────────────────────────────────┐
│ magic        "OFLOW1"            (6 bytes, ASCII)             │
│ headerLen    uint32 LE                                        │
│ header       JSON (cleartext, NO secrets — only the params    │
│              needed to attempt decryption + the signer pubkey)│
│ ciphertext   AES-256-GCM( gzip(bundle), dek, nonce, aad=hdr ) │  ← opaque
│ signature    Ed25519( magic ‖ header ‖ ciphertext )  (64 B)  │  ← provenance
└─────────────────────────────────────────────────────────────┘

bundle (only visible AFTER decryption) is:

{
  "manifest": { /* name, version, author, kind, createdAt, integrity… */ },
  "flow":     { /* the workflow graph */ },
  "secrets":  { /* credentials / keys — the sensitive part */ },
  "assets":   { "path/to/file": "<base64>" }   // optional
}

Cryptography

| Concern | Primitive | Library | |----------------|--------------------------------------------|--------------------| | Confidentiality| AES-256-GCM (AEAD; header bound as AAD) | @noble/ciphers | | Data key (DEK) | random 32 bytes per file | @noble/hashes | | Provenance | Ed25519 detached signature | @noble/curves | | Key wrap | pluggable — see below | @noble/curves |

The 32-byte DEK encrypts the payload. The DEK itself is wrapped by one of:

• x25519 (recipient keys, recommended). An ephemeral X25519 key + ECDH → HKDF-SHA256 → KEK, one wrapped DEK per recipient public key. Encrypt to specific orgs/users; revocable per recipient; no shared secret ships.
• passphrase. KEK = scrypt(passphrase, salt). Simplest sharing — distribute the passphrase out-of-band. Security = the passphrase.
• kms (interface). DEK wrapped by an external KMS key. Strongest "only our infra can read it" — the unwrap key never leaves the KMS. Provided as a KeyProvider interface to implement against your KMS; not bundled here.

The honest security note (read this)

"Only our library can read it" is delivered by (a) the encrypted opaque container (generic tools can't read or unzip it) and (b) key management — the file decrypts only with the recipient key / passphrase / KMS key. A symmetric key embedded in this distributed library would be extractable and is therefore not used as the security boundary. Treat the format as public; treat the keys as the secret.

API (v0)

import {
  createOflow, openOflow,
  generateSigningKeyPair, generateRecipientKeyPair,
} from '@octaviaflow/oflow';

// keys (do this once; store private keys securely / in your vault)
const signer    = generateSigningKeyPair();    // Ed25519 — provenance
const recipient = generateRecipientKeyPair();  // X25519  — who may decrypt

// build
const bytes = await createOflow(
  { manifest, flow, secrets, assets },
  { sign: signer.privateKey,
    keyWrap: { type: 'x25519', recipients: [recipient.publicKey] } },
);
await Bun.write('my-flow.oflow', bytes);

// open
const result = await openOflow(bytes, {
  unwrap: { type: 'x25519', privateKey: recipient.privateKey },
  trustedSigners: [signer.publicKey],   // reject unknown signers
});
// → { manifest, flow, secrets, assets, signerPublicKey, signatureValid }

Unsigned / wrong-signer / tampered / undecryptable files throw — never silently trusted.

CLI

oflow pack   <bundle.json> -o out.oflow  [--passphrase ... | --recipient <pubkey>] --sign <privkey>
oflow open   <in.oflow>     [--passphrase ... | --recipient-key <privkey>] [--trust <pubkey>]
oflow inspect <in.oflow>            # prints the cleartext header ONLY (no decryption)
oflow keygen  (sign|recipient)

Layout

src/
  crypto.ts    AEAD, Ed25519 sign/verify, DEK key-wrap (x25519 + passphrase), KeyProvider iface
  manifest.ts  manifest schema + validation
  format.ts    the .oflow envelope: pack / unpack (magic, header, ciphertext, signature)
  index.ts     public API (createOflow / openOflow / keygen)
  cli.ts       pack / open / inspect / keygen