@forgezero/runtime 0.1.17 → 0.1.18

package/README.md

@@ -7,7 +7,7 @@
 
 # Platform runtime
 
-The machinery behind a request handler — jobs, queues, an outbox, a hash-chained audit trail, mail, backups, schema validation and exact money. 30 public modules, each imported on its own.
+The machinery behind a request handler — jobs, queues, an outbox, a hash-chained audit trail, mail, backups, schema validation and exact money. 31 public modules, each imported on its own.
 
 ## Package overview
 
@@ -53,6 +53,7 @@ These are supported consumer entry points, not every internal module shipped for
 | @forgezero/runtime/ssh-cert | OpenSSH certificates, so access expires instead of having to be hunted down. Takes a signing FUNCTION rather than a secret key, which is what lets the CA live in a vault that never hands it out. | portable | [Reference + usage](#forgezero-runtime-ssh-cert) |
 | @forgezero/runtime/slip10 | SLIP-0010 derivation for ed25519, hardened-only — BIP-32 does not work on this curve and produces halves that do not correspond. | portable | [Reference + usage](#forgezero-runtime-slip10) |
 | @forgezero/runtime/identity | Hybrid Ed25519 + ML-DSA-65 request signing. One canonical string, so the compute agent that signs inside a guest and the API that verifies cannot drift — which two implementations of it certainly would. | portable | [Reference + usage](#forgezero-runtime-identity) |
+| @forgezero/runtime/vault-runtime | Provider-neutral algorithms for non-exportable Vault runtime records: passwords, DEK/KEK operations, HMAC/JWS, Ed25519/secp256k1 and Ethereum/Solana address encoding. | portable | [Reference + usage](#forgezero-runtime-vault-runtime) |
 | @forgezero/runtime/schema | Validate against JSON Schema, restrict what a caller may declare, and describe a schema as a form. | portable | [Reference + usage](#forgezero-runtime-schema) |
 | @forgezero/runtime/schema/typebox | The TypeBox validator behind that interface. | portable | [Reference + usage](#forgezero-runtime-schema-typebox) |
 | @forgezero/runtime/finance/discounts | Promotions as arithmetic over integer minor units. They never stack — one winner — and a percentage rounds down, because rounding a discount up gives away a unit of currency per invoice forever. | portable | [Reference + usage](#forgezero-runtime-finance-discounts) |
@@ -509,6 +510,29 @@ import {
 export const selectedCapability = CLOCK_SKEW_SECONDS;
 ```
 
+<a id="forgezero-runtime-vault-runtime"></a>
+## @forgezero/runtime/vault-runtime
+
+Provider-neutral algorithms for non-exportable Vault runtime records: passwords, DEK/KEK operations, HMAC/JWS, Ed25519/secp256k1 and Ethereum/Solana address encoding. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
+
+```text
+import {
+  DEFAULT_PASSWORD_ALPHABET,
+} from '@forgezero/runtime/vault-runtime';
+```
+
+## @forgezero/runtime/vault-runtime — Use this entry point
+
+This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.
+
+```text
+import {
+  DEFAULT_PASSWORD_ALPHABET,
+} from '@forgezero/runtime/vault-runtime';
+
+export const selectedCapability = DEFAULT_PASSWORD_ALPHABET;
+```
+
 <a id="forgezero-runtime-schema"></a>
 ## @forgezero/runtime/schema
 

package/dist/jobs.d.ts

@@ -58,7 +58,12 @@ export interface Lease {
     until: number;
 }
 export interface JobLock {
-    acquire(key: string, ttlMs: number): Promise<Lease | undefined>;
+    /**
+     * Acquire the job. A scheduled occurrence is a durable once-only token: after
+     * the holder releases its lease, another replica still cannot execute that
+     * same due slot. Manual runs omit it and remain deliberately repeatable.
+     */
+    acquire(key: string, ttlMs: number, occurrence?: string): Promise<Lease | undefined>;
     /** Extend a lease held by this fence. False means it was lost. */
     renew(key: string, fence: number, ttlMs: number): Promise<boolean>;
     release(key: string, fence: number): Promise<void>;
@@ -72,7 +77,7 @@ export declare function memoryLock(clock?: Clock): JobLock;
  * the same lease to two processes under exactly the load that makes it matter.
  */
 export interface LockStore {
-    claim(key: string, until: number, now: number): Promise<Lease | undefined>;
+    claim(key: string, until: number, now: number, occurrence?: string): Promise<Lease | undefined>;
     extend(key: string, fence: number, until: number): Promise<boolean>;
     clear(key: string, fence: number): Promise<void>;
 }

package/dist/jobs.js

@@ -379,15 +379,20 @@ function nextWallClockAt(schedule, afterMs) {
 }
 function memoryLock(clock = systemClock) {
   const held = new Map;
+  const claimedOccurrences = new Map;
   let fences = 0;
   return {
-    async acquire(key, ttlMs) {
+    async acquire(key, ttlMs, occurrence) {
+      if (occurrence !== undefined && claimedOccurrences.get(key) === occurrence)
+        return;
       const current = held.get(key);
       if (current && current.until > clock.now())
         return;
       fences += 1;
       const lease = { fence: fences, until: clock.now() + ttlMs };
       held.set(key, lease);
+      if (occurrence !== undefined)
+        claimedOccurrences.set(key, occurrence);
       return lease;
     },
     async renew(key, fence, ttlMs) {
@@ -405,7 +410,7 @@ function memoryLock(clock = systemClock) {
 }
 function storeLock(store, clock = systemClock) {
   return {
-    acquire: (key, ttlMs) => store.claim(key, clock.now() + ttlMs, clock.now()),
+    acquire: (key, ttlMs, occurrence) => store.claim(key, clock.now() + ttlMs, clock.now(), occurrence),
     renew: (key, fence, ttlMs) => store.extend(key, fence, clock.now() + ttlMs),
     release: (key, fence) => store.clear(key, fence)
   };
@@ -465,10 +470,10 @@ function createScheduler(options) {
   let paused = false;
   let running = false;
   const outstanding = new Map;
-  const submit = async (job) => {
+  const submit = async (job, occurrence) => {
     outstanding.set(job.key, (outstanding.get(job.key) ?? 0) + 1);
     try {
-      await work.run(job.key, execute, job).result;
+      await work.run(job.key, execute, job, occurrence).result;
     } finally {
       const left = (outstanding.get(job.key) ?? 1) - 1;
       if (left === 0)
@@ -477,14 +482,14 @@ function createScheduler(options) {
         outstanding.set(job.key, left);
     }
   };
-  async function execute(job) {
+  async function execute(job, occurrence) {
     const report = reports.get(job.key);
     const leaseMs = job.leaseMs ?? (job.every ? everyMs(job.every) * 4 : 60000);
     let lease;
     let leaseHeld = true;
     let renewTimer;
     if (!job.unlocked) {
-      lease = await lock.acquire(job.key, leaseMs);
+      lease = await lock.acquire(job.key, leaseMs, occurrence);
       if (!lease) {
         report.skippedLocked += 1;
         return;
@@ -553,8 +558,11 @@ function createScheduler(options) {
     }
   }
   function nextDelay(job) {
-    if (job.every !== undefined)
-      return everyMs(job.every);
+    if (job.every !== undefined) {
+      const interval = everyMs(job.every);
+      const now = clock.now();
+      return Math.max(0, (Math.floor(now / interval) + 1) * interval - now);
+    }
     if (job.schedule)
       return Math.max(0, nextWallClockAt(job.schedule, clock.now()) - clock.now());
     return;
@@ -563,7 +571,8 @@ function createScheduler(options) {
     const next = delayMs ?? nextDelay(job);
     if (!running || next === undefined)
       return;
-    reports.get(job.key).nextRunAtMs = clock.now() + next;
+    const dueAt = clock.now() + next;
+    reports.get(job.key).nextRunAtMs = dueAt;
     timers.set(job.key, setTimeout(() => {
       timers.delete(job.key);
       if (!running || paused)
@@ -574,12 +583,14 @@ function createScheduler(options) {
           reports.get(job.key).skippedOverlap += 1;
           return;
         }
-        submit(job).catch(() => {
+        const occurrence2 = job.every === undefined ? `wall:${dueAt}` : `interval:${Math.floor(clock.now() / everyMs(job.every))}`;
+        submit(job, occurrence2).catch(() => {
           return;
         });
         return;
       }
-      submit(job).then(() => schedule(job), () => {
+      const occurrence = job.every === undefined ? `wall:${dueAt}` : `interval:${Math.floor(clock.now() / everyMs(job.every))}`;
+      submit(job, occurrence).then(() => schedule(job), () => {
         return;
       });
     }, next));

package/dist/vault-runtime.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Provider-neutral Vault runtime primitives.
+ *
+ * This module never derives from a realm seed and never stores a key. The API
+ * owns those two security boundaries and lends this module one short-lived key
+ * for one operation. Keeping the algorithms here makes their byte formats
+ * independently testable without making `@forgezero/vault.get()` a signer.
+ */
+export declare const VAULT_RUNTIME_KINDS: readonly ["random-password", "data-encryption-key", "key-encryption-key", "hmac-key", "jwt-hmac-key", "ed25519-key", "secp256k1-key", "ssh-ca-key", "chain-key"];
+export type VaultRuntimeKind = typeof VAULT_RUNTIME_KINDS[number];
+export declare const VAULT_RUNTIME_ALGORITHM_IDS: readonly ["password-v1", "aes-256-gcm", "aes-256-kw", "hmac-sha256", "hmac-sha512", "jws-hs256", "ed25519", "secp256k1", "ssh-ed25519-ca", "ethereum-secp256k1", "solana-ed25519"];
+export type VaultRuntimeAlgorithm = typeof VAULT_RUNTIME_ALGORITHM_IDS[number];
+export type VaultRuntimeOperation = 'generate-password' | 'encrypt' | 'decrypt' | 'wrap' | 'unwrap' | 'sign' | 'verify' | 'sign-jwt' | 'verify-jwt' | 'issue-ssh-certificate' | 'derive-public-key' | 'derive-address';
+export interface VaultRuntimeAlgorithmDefinition {
+    kind: VaultRuntimeKind;
+    algorithm: VaultRuntimeAlgorithm;
+    operations: readonly VaultRuntimeOperation[];
+    /** Private material is never a supported output. */
+    exports: 'password-only' | 'public-only' | 'none';
+    standard: string;
+}
+/**
+ * Typed algorithm truth shared by the API, package documentation and future UI.
+ * Adding another chain or credential generator requires a reviewed definition;
+ * callers cannot invent an algorithm string and reach an unreviewed primitive.
+ */
+export declare const VAULT_RUNTIME_ALGORITHMS: readonly [{
+    readonly kind: "random-password";
+    readonly algorithm: "password-v1";
+    readonly operations: readonly ["generate-password"];
+    readonly exports: "password-only";
+    readonly standard: "ForgeZero password-v1";
+}, {
+    readonly kind: "data-encryption-key";
+    readonly algorithm: "aes-256-gcm";
+    readonly operations: readonly ["encrypt", "decrypt"];
+    readonly exports: "none";
+    readonly standard: "NIST SP 800-38D";
+}, {
+    readonly kind: "key-encryption-key";
+    readonly algorithm: "aes-256-kw";
+    readonly operations: readonly ["wrap", "unwrap"];
+    readonly exports: "none";
+    readonly standard: "NIST SP 800-38F";
+}, {
+    readonly kind: "hmac-key";
+    readonly algorithm: "hmac-sha256";
+    readonly operations: readonly ["sign", "verify"];
+    readonly exports: "none";
+    readonly standard: "RFC 2104 / SHA-256";
+}, {
+    readonly kind: "hmac-key";
+    readonly algorithm: "hmac-sha512";
+    readonly operations: readonly ["sign", "verify"];
+    readonly exports: "none";
+    readonly standard: "RFC 2104 / SHA-512";
+}, {
+    readonly kind: "jwt-hmac-key";
+    readonly algorithm: "jws-hs256";
+    readonly operations: readonly ["sign-jwt", "verify-jwt"];
+    readonly exports: "none";
+    readonly standard: "RFC 7515 / RFC 7518";
+}, {
+    readonly kind: "ed25519-key";
+    readonly algorithm: "ed25519";
+    readonly operations: readonly ["derive-public-key", "sign", "verify"];
+    readonly exports: "public-only";
+    readonly standard: "RFC 8032";
+}, {
+    readonly kind: "secp256k1-key";
+    readonly algorithm: "secp256k1";
+    readonly operations: readonly ["derive-public-key", "sign", "verify"];
+    readonly exports: "public-only";
+    readonly standard: "SEC 2 secp256k1";
+}, {
+    readonly kind: "ssh-ca-key";
+    readonly algorithm: "ssh-ed25519-ca";
+    readonly operations: readonly ["derive-public-key", "issue-ssh-certificate"];
+    readonly exports: "public-only";
+    readonly standard: "OpenSSH PROTOCOL.certkeys";
+}, {
+    readonly kind: "chain-key";
+    readonly algorithm: "ethereum-secp256k1";
+    readonly operations: readonly ["derive-public-key", "derive-address", "sign", "verify"];
+    readonly exports: "public-only";
+    readonly standard: "BIP-32/BIP-44/SLIP-44/EIP-55";
+}, {
+    readonly kind: "chain-key";
+    readonly algorithm: "solana-ed25519";
+    readonly operations: readonly ["derive-public-key", "derive-address", "sign", "verify"];
+    readonly exports: "public-only";
+    readonly standard: "SLIP-10/BIP-44/SLIP-44";
+}];
+export declare const VAULT_RUNTIME_CHAINS: readonly [{
+    readonly chain: "ethereum";
+    readonly coinType: 60;
+    readonly curve: "secp256k1";
+    readonly path: "m/44'/60'/account'/change/index";
+}, {
+    readonly chain: "solana";
+    readonly coinType: 501;
+    readonly curve: "ed25519";
+    readonly path: "m/44'/501'/account'/change'/index'";
+}];
+export interface PasswordPolicy {
+    length: number;
+    alphabet?: string;
+}
+export interface EthereumDerivation {
+    chain: 'ethereum';
+    network?: 'mainnet' | 'sepolia' | string;
+    account?: number;
+    change?: number;
+    index?: number;
+}
+export interface SolanaDerivation {
+    chain: 'solana';
+    network?: 'mainnet-beta' | 'devnet' | 'testnet' | string;
+    account?: number;
+    change?: number;
+    index?: number;
+}
+export type ChainDerivation = EthereumDerivation | SolanaDerivation;
+type RuntimeDefinition = typeof VAULT_RUNTIME_ALGORITHMS[number];
+/**
+ * A correlated creation contract: an algorithm cannot be paired with the wrong
+ * key kind, password keys require a policy, and chain keys require a reviewed
+ * chain derivation. The API repeats these checks at its trust boundary.
+ */
+export type VaultRuntimeCreateDescriptor = RuntimeDefinition extends infer Definition ? Definition extends {
+    kind: infer Kind extends VaultRuntimeKind;
+    algorithm: infer Algorithm extends VaultRuntimeAlgorithm;
+} ? {
+    kind: Kind;
+    algorithm: Algorithm;
+    label: string;
+} & (Kind extends 'random-password' ? {
+    password: PasswordPolicy;
+    chain?: never;
+} : Kind extends 'chain-key' ? {
+    chain: ChainDerivation;
+    password?: never;
+} : {
+    password?: never;
+    chain?: never;
+}) : never : never;
+export interface VaultRuntimeDescriptor {
+    format: 1;
+    kind: VaultRuntimeKind;
+    algorithm: VaultRuntimeAlgorithm;
+    label: string;
+    createdAtTs: number;
+    password?: PasswordPolicy;
+    chain?: ChainDerivation;
+}
+export interface RuntimeCiphertext {
+    algorithm: 'aes-256-gcm';
+    nonce: string;
+    ciphertext: string;
+}
+export interface RuntimeWrappedKey {
+    algorithm: 'aes-256-kw';
+    ciphertext: string;
+}
+export declare const DEFAULT_PASSWORD_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz23456789!@#$%^&*()-_=+";
+export declare function validatePasswordPolicy(policy: PasswordPolicy): void;
+export declare const toBase64Url: (bytes: Uint8Array) => string;
+export declare const fromBase64Url: (value: string) => Uint8Array;
+export declare function passwordFromBytes(entropy: Uint8Array, policy: PasswordPolicy): string;
+export declare function encryptWithDek(key: Uint8Array, plaintext: Uint8Array, aad: string): RuntimeCiphertext;
+export declare function decryptWithDek(key: Uint8Array, box: RuntimeCiphertext, aad: string): Uint8Array;
+export declare function wrapWithKek(key: Uint8Array, plaintextKey: Uint8Array): RuntimeWrappedKey;
+export declare function unwrapWithKek(key: Uint8Array, wrapped: RuntimeWrappedKey): Uint8Array;
+export declare function hmacSign(algorithm: 'hmac-sha256' | 'hmac-sha512', key: Uint8Array, message: Uint8Array): Uint8Array;
+export declare function hmacVerify(algorithm: 'hmac-sha256' | 'hmac-sha512', key: Uint8Array, message: Uint8Array, signature: Uint8Array): boolean;
+export declare function signCompactJws(key: Uint8Array, claims: Record<string, unknown>): string;
+export declare function verifyCompactJws(key: Uint8Array, token: string, options?: {
+    nowSec?: number;
+    issuer?: string;
+    audience?: string;
+}): Record<string, unknown>;
+export declare const ed25519PublicKey: (secret: Uint8Array) => Uint8Array;
+export declare const ed25519Sign: (secret: Uint8Array, message: Uint8Array) => Uint8Array;
+export declare const ed25519Verify: (publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array) => boolean;
+export declare const secp256k1PublicKey: (secret: Uint8Array, compressed?: boolean) => Uint8Array;
+export declare const secp256k1SignDigest: (secret: Uint8Array, digest: Uint8Array) => Uint8Array;
+export declare const secp256k1VerifyDigest: (publicKey: Uint8Array, digest: Uint8Array, signature: Uint8Array) => boolean;
+export declare function chainPath(chain: ChainDerivation): string;
+export declare function ethereumAddress(uncompressedPublicKey: Uint8Array): string;
+export declare const solanaAddress: (publicKey: Uint8Array) => string;
+export {};

package/dist/vault-runtime.js

@@ -0,0 +1,272 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/vault-runtime.ts
+import { aeskw, gcm } from "@noble/ciphers/aes.js";
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import { hmac } from "@noble/hashes/hmac.js";
+import { keccak_256 } from "@noble/hashes/sha3.js";
+import { sha256, sha512 } from "@noble/hashes/sha2.js";
+import { base58 } from "@scure/base";
+var VAULT_RUNTIME_KINDS = [
+  "random-password",
+  "data-encryption-key",
+  "key-encryption-key",
+  "hmac-key",
+  "jwt-hmac-key",
+  "ed25519-key",
+  "secp256k1-key",
+  "ssh-ca-key",
+  "chain-key"
+];
+var VAULT_RUNTIME_ALGORITHM_IDS = [
+  "password-v1",
+  "aes-256-gcm",
+  "aes-256-kw",
+  "hmac-sha256",
+  "hmac-sha512",
+  "jws-hs256",
+  "ed25519",
+  "secp256k1",
+  "ssh-ed25519-ca",
+  "ethereum-secp256k1",
+  "solana-ed25519"
+];
+var VAULT_RUNTIME_ALGORITHMS = [
+  { kind: "random-password", algorithm: "password-v1", operations: ["generate-password"], exports: "password-only", standard: "ForgeZero password-v1" },
+  { kind: "data-encryption-key", algorithm: "aes-256-gcm", operations: ["encrypt", "decrypt"], exports: "none", standard: "NIST SP 800-38D" },
+  { kind: "key-encryption-key", algorithm: "aes-256-kw", operations: ["wrap", "unwrap"], exports: "none", standard: "NIST SP 800-38F" },
+  { kind: "hmac-key", algorithm: "hmac-sha256", operations: ["sign", "verify"], exports: "none", standard: "RFC 2104 / SHA-256" },
+  { kind: "hmac-key", algorithm: "hmac-sha512", operations: ["sign", "verify"], exports: "none", standard: "RFC 2104 / SHA-512" },
+  { kind: "jwt-hmac-key", algorithm: "jws-hs256", operations: ["sign-jwt", "verify-jwt"], exports: "none", standard: "RFC 7515 / RFC 7518" },
+  { kind: "ed25519-key", algorithm: "ed25519", operations: ["derive-public-key", "sign", "verify"], exports: "public-only", standard: "RFC 8032" },
+  { kind: "secp256k1-key", algorithm: "secp256k1", operations: ["derive-public-key", "sign", "verify"], exports: "public-only", standard: "SEC 2 secp256k1" },
+  { kind: "ssh-ca-key", algorithm: "ssh-ed25519-ca", operations: ["derive-public-key", "issue-ssh-certificate"], exports: "public-only", standard: "OpenSSH PROTOCOL.certkeys" },
+  { kind: "chain-key", algorithm: "ethereum-secp256k1", operations: ["derive-public-key", "derive-address", "sign", "verify"], exports: "public-only", standard: "BIP-32/BIP-44/SLIP-44/EIP-55" },
+  { kind: "chain-key", algorithm: "solana-ed25519", operations: ["derive-public-key", "derive-address", "sign", "verify"], exports: "public-only", standard: "SLIP-10/BIP-44/SLIP-44" }
+];
+var VAULT_RUNTIME_CHAINS = [
+  { chain: "ethereum", coinType: 60, curve: "secp256k1", path: "m/44'/60'/account'/change/index" },
+  { chain: "solana", coinType: 501, curve: "ed25519", path: "m/44'/501'/account'/change'/index'" }
+];
+var DEFAULT_PASSWORD_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz23456789!@#$%^&*()-_=+";
+function validatePasswordPolicy(policy) {
+  const alphabet = policy.alphabet ?? DEFAULT_PASSWORD_ALPHABET;
+  if (!Number.isInteger(policy.length) || policy.length < 16 || policy.length > 256) {
+    throw new Error("vault-runtime: password length must be in 16..256");
+  }
+  if (alphabet.length < 16 || alphabet.length > 128 || new Set(alphabet).size !== alphabet.length) {
+    throw new Error("vault-runtime: password alphabet must contain 16..128 unique characters");
+  }
+}
+var toBase64Url = (bytes) => {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+};
+var fromBase64Url = (value) => {
+  if (!/^[A-Za-z0-9_-]*$/.test(value))
+    throw new Error("vault-runtime: invalid base64url");
+  const padded = value.replaceAll("-", "+").replaceAll("_", "/") + "=".repeat((4 - value.length % 4) % 4);
+  let binary;
+  try {
+    binary = atob(padded);
+  } catch {
+    throw new Error("vault-runtime: invalid base64url");
+  }
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+};
+var utf8 = (value) => new TextEncoder().encode(value);
+function passwordFromBytes(entropy, policy) {
+  const alphabet = policy.alphabet ?? DEFAULT_PASSWORD_ALPHABET;
+  validatePasswordPolicy(policy);
+  const limit = 256 - 256 % alphabet.length;
+  let output = "";
+  for (const byte of entropy) {
+    if (byte >= limit)
+      continue;
+    output += alphabet[byte % alphabet.length];
+    if (output.length === policy.length)
+      return output;
+  }
+  throw new Error("vault-runtime: insufficient unbiased password entropy");
+}
+function encryptWithDek(key, plaintext, aad) {
+  if (key.length !== 32)
+    throw new Error("vault-runtime: DEK must be 32 bytes");
+  if (!aad)
+    throw new Error("vault-runtime: authenticated data is required");
+  const nonce = crypto.getRandomValues(new Uint8Array(12));
+  const ciphertext = gcm(key, nonce, utf8(aad)).encrypt(plaintext);
+  return { algorithm: "aes-256-gcm", nonce: toBase64Url(nonce), ciphertext: toBase64Url(ciphertext) };
+}
+function decryptWithDek(key, box, aad) {
+  if (key.length !== 32)
+    throw new Error("vault-runtime: DEK must be 32 bytes");
+  if (!aad || box.algorithm !== "aes-256-gcm")
+    throw new Error("vault-runtime: invalid ciphertext");
+  return gcm(key, fromBase64Url(box.nonce), utf8(aad)).decrypt(fromBase64Url(box.ciphertext));
+}
+function wrapWithKek(key, plaintextKey) {
+  if (key.length !== 32)
+    throw new Error("vault-runtime: KEK must be 32 bytes");
+  if (plaintextKey.length < 16 || plaintextKey.length % 8 !== 0) {
+    throw new Error("vault-runtime: wrapped key must be a non-empty multiple of 8 bytes, at least 16 bytes");
+  }
+  return { algorithm: "aes-256-kw", ciphertext: toBase64Url(aeskw(key).encrypt(plaintextKey)) };
+}
+function unwrapWithKek(key, wrapped) {
+  if (key.length !== 32 || wrapped.algorithm !== "aes-256-kw") {
+    throw new Error("vault-runtime: invalid wrapped key");
+  }
+  return aeskw(key).decrypt(fromBase64Url(wrapped.ciphertext));
+}
+function hmacSign(algorithm, key, message) {
+  return hmac(algorithm === "hmac-sha256" ? sha256 : sha512, key, message);
+}
+function hmacVerify(algorithm, key, message, signature) {
+  const actual = hmacSign(algorithm, key, message);
+  if (actual.length !== signature.length)
+    return false;
+  let difference = 0;
+  for (let index = 0;index < actual.length; index += 1)
+    difference |= actual[index] ^ signature[index];
+  return difference === 0;
+}
+function signCompactJws(key, claims) {
+  if (!claims || Array.isArray(claims) || Object.getPrototypeOf(claims) !== Object.prototype) {
+    throw new Error("vault-runtime: JWT claims must be a plain object");
+  }
+  const header = toBase64Url(utf8(JSON.stringify({ alg: "HS256", typ: "JWT" })));
+  let serialized;
+  try {
+    serialized = JSON.stringify(claims);
+  } catch {
+    throw new Error("vault-runtime: JWT claims must be JSON serializable");
+  }
+  const payload = toBase64Url(utf8(serialized));
+  const input = `${header}.${payload}`;
+  return `${input}.${toBase64Url(hmac(sha256, key, utf8(input)))}`;
+}
+function verifyCompactJws(key, token, options = {}) {
+  const parts = token.split(".");
+  if (parts.length !== 3)
+    throw new Error("vault-runtime: malformed compact JWS");
+  const [headerPart, payloadPart, signaturePart] = parts;
+  let header;
+  try {
+    header = JSON.parse(new TextDecoder().decode(fromBase64Url(headerPart)));
+  } catch {
+    throw new Error("vault-runtime: malformed compact JWS");
+  }
+  if (!header || Array.isArray(header) || typeof header !== "object") {
+    throw new Error("vault-runtime: malformed compact JWS");
+  }
+  const headerRecord = header;
+  if (headerRecord.alg !== "HS256" || headerRecord.typ !== "JWT")
+    throw new Error("vault-runtime: unsupported JWS header");
+  if (!hmacVerify("hmac-sha256", key, utf8(`${headerPart}.${payloadPart}`), fromBase64Url(signaturePart))) {
+    throw new Error("vault-runtime: invalid JWS signature");
+  }
+  let parsedClaims;
+  try {
+    parsedClaims = JSON.parse(new TextDecoder().decode(fromBase64Url(payloadPart)));
+  } catch {
+    throw new Error("vault-runtime: malformed JWT claims");
+  }
+  if (!parsedClaims || Array.isArray(parsedClaims) || typeof parsedClaims !== "object") {
+    throw new Error("vault-runtime: JWT claims must be an object");
+  }
+  const claims = parsedClaims;
+  const now = options.nowSec ?? Math.floor(Date.now() / 1000);
+  if (claims.exp !== undefined && typeof claims.exp !== "number")
+    throw new Error("vault-runtime: JWT exp must be a NumericDate");
+  if (claims.nbf !== undefined && typeof claims.nbf !== "number")
+    throw new Error("vault-runtime: JWT nbf must be a NumericDate");
+  if (typeof claims.exp === "number" && now >= claims.exp)
+    throw new Error("vault-runtime: JWT expired");
+  if (typeof claims.nbf === "number" && now < claims.nbf)
+    throw new Error("vault-runtime: JWT not active");
+  if (options.issuer !== undefined && claims.iss !== options.issuer)
+    throw new Error("vault-runtime: JWT issuer mismatch");
+  if (options.audience !== undefined) {
+    const audiences = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+    if (audiences.some((audience) => typeof audience !== "string"))
+      throw new Error("vault-runtime: JWT aud must contain strings");
+    if (!audiences.includes(options.audience))
+      throw new Error("vault-runtime: JWT audience mismatch");
+  }
+  return claims;
+}
+var ed25519PublicKey = (secret) => ed25519.getPublicKey(secret);
+var ed25519Sign = (secret, message) => ed25519.sign(message, secret);
+var ed25519Verify = (publicKey, message, signature) => ed25519.verify(signature, message, publicKey);
+var secp256k1PublicKey = (secret, compressed = true) => secp256k1.getPublicKey(secret, compressed);
+var secp256k1SignDigest = (secret, digest) => {
+  if (digest.length !== 32)
+    throw new Error("vault-runtime: secp256k1 requires a 32-byte digest");
+  return secp256k1.sign(digest, secret, { prehash: false, format: "recovered" });
+};
+var secp256k1VerifyDigest = (publicKey, digest, signature) => digest.length === 32 && secp256k1.verify(signature, digest, publicKey, { prehash: false, format: "recovered" });
+function chainPath(chain) {
+  const bound = (value, label, fallback) => {
+    const result = value ?? fallback;
+    if (!Number.isInteger(result) || result < 0 || result >= 2147483648) {
+      throw new Error(`vault-runtime: ${label} must be in 0..2147483647`);
+    }
+    return result;
+  };
+  const account = bound(chain.account, "account", 0);
+  const change = bound(chain.change, "change", 0);
+  const index = bound(chain.index, "index", 0);
+  return chain.chain === "ethereum" ? `m/44'/60'/${account}'/${change}/${index}` : `m/44'/501'/${account}'/${change}'/${index}'`;
+}
+function ethereumAddress(uncompressedPublicKey) {
+  if (uncompressedPublicKey.length !== 65 || uncompressedPublicKey[0] !== 4) {
+    throw new Error("vault-runtime: Ethereum requires an uncompressed secp256k1 public key");
+  }
+  const lower = Array.from(keccak_256(uncompressedPublicKey.slice(1)).slice(-20), (byte) => byte.toString(16).padStart(2, "0")).join("");
+  const checksum = Array.from(keccak_256(utf8(lower)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+  let address = "0x";
+  for (let index = 0;index < lower.length; index += 1) {
+    const character = lower[index];
+    address += Number.parseInt(checksum[index], 16) >= 8 ? character.toUpperCase() : character;
+  }
+  return address;
+}
+var solanaAddress = (publicKey) => base58.encode(publicKey);
+export {
+  wrapWithKek,
+  verifyCompactJws,
+  validatePasswordPolicy,
+  unwrapWithKek,
+  toBase64Url,
+  solanaAddress,
+  signCompactJws,
+  secp256k1VerifyDigest,
+  secp256k1SignDigest,
+  secp256k1PublicKey,
+  passwordFromBytes,
+  hmacVerify,
+  hmacSign,
+  fromBase64Url,
+  ethereumAddress,
+  encryptWithDek,
+  ed25519Verify,
+  ed25519Sign,
+  ed25519PublicKey,
+  decryptWithDek,
+  chainPath,
+  VAULT_RUNTIME_KINDS,
+  VAULT_RUNTIME_CHAINS,
+  VAULT_RUNTIME_ALGORITHM_IDS,
+  VAULT_RUNTIME_ALGORITHMS,
+  DEFAULT_PASSWORD_ALPHABET
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/runtime",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -59,6 +59,10 @@
       "types": "./dist/identity.d.ts",
       "default": "./dist/identity.js"
     },
+    "./vault-runtime": {
+      "types": "./dist/vault-runtime.d.ts",
+      "default": "./dist/vault-runtime.js"
+    },
     "./passkey-hybrid": {
       "types": "./dist/passkey-hybrid.d.ts",
       "default": "./dist/passkey-hybrid.js"
@@ -134,13 +138,14 @@
     "prepublishOnly": "bun ../tools/package-task.ts prepublish runtime"
   },
   "dependencies": {
-    "@forgezero/access": "^0.1.12"
+    "@forgezero/access": "^0.1.13"
   },
   "peerDependencies": {
     "@noble/ciphers": "^2.2.0",
     "@noble/curves": "^2.2.0",
     "@noble/post-quantum": "^0.6.1",
     "@noble/hashes": "^2.2.0",
+    "@scure/base": "^2.2.0",
     "@sinclair/typebox": "^0.34.0",
     "@scure/bip39": "^2.2.0"
   },
@@ -162,6 +167,9 @@
     },
     "@scure/bip39": {
       "optional": true
+    },
+    "@scure/base": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -170,9 +178,12 @@
     "@sinclair/typebox": "^0.34.0",
     "@noble/curves": "^2.2.0",
     "@noble/post-quantum": "^0.6.1",
+    "@noble/ciphers": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
+    "@scure/base": "^2.2.0",
     "@scure/bip39": "^2.2.0"
   },
-  "description": "The machinery a service needs behind its request handlers: jobs, keyed queues, a transactional outbox, a hash-chained audit trail, templated mail, encrypted backups and schema validation.",
+  "description": "Server-neutral runtime primitives for jobs, queues, outbox, audit, Vault cryptography, finance, identity, recovery and deployment automation.",
   "keywords": [
     "jobs",
     "scheduler",
@@ -186,7 +197,10 @@
     "validation",
     "calendar",
     "billing-period",
-    "working-days"
+    "working-days",
+    "vault-runtime",
+    "envelope-encryption",
+    "signing"
   ],
   "license": "MIT",
   "homepage": "https://www.forgezero.net/docs/runtime",