@forgezero/vault 0.1.22 → 0.1.23

package/README.md

@@ -41,6 +41,7 @@ These are supported consumer entry points, not every internal module shipped for
 | @forgezero/vault/env | Envless: fill `process.env` from the vault at boot, refusing to run during a build. | portable | [Reference + usage](#forgezero-vault-env) |
 | @forgezero/vault/frameworks | SvelteKit and Next.js wiring, attached at the one place that runs once, on the server, before any request. | portable | [Reference + usage](#forgezero-vault-frameworks) |
 | @forgezero/vault/providers | Adapters that make Vault a provider-configuration and credential source without coupling the providers package to ForgeZero. | portable | [Reference + usage](#forgezero-vault-providers) |
+| @forgezero/vault/runtime | Explicit, separately granted password, envelope-encryption, signing, chain-address and SSH-certificate operations whose private material never leaves the unlocked Vault runtime. | portable | [Reference + usage](#forgezero-vault-runtime) |
 
 ## Commands
 
@@ -231,6 +232,63 @@ const repositories = await git.call('listRepositories', { installationId: '42' }
 if (!repositories.ok) throw repositories.error;
 ```
 
+<a id="forgezero-vault-runtime"></a>
+## @forgezero/vault/runtime
+
+Explicit, separately granted password, envelope-encryption, signing, chain-address and SSH-certificate operations whose private material never leaves the unlocked Vault runtime. 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 {
+  VaultRuntime,
+} from '@forgezero/vault/runtime';
+```
+
+## @forgezero/vault/runtime — Encrypt with a non-exportable, versioned DEK
+
+Runtime operations require explicit external API-key grants. The returned envelope carries the immutable key version, so data remains decryptable after rotation; the DEK itself is never returned.
+
+```text
+import {
+  createVault,
+} from '@forgezero/vault';
+
+const vault = createVault({ project: 'payments', environment: 'production' });
+const dek = await vault.runtime.create({
+  kind: 'data-encryption-key',
+  algorithm: 'aes-256-gcm',
+  label: 'customer database envelope'
+});
+
+const plaintext = new TextEncoder().encode('sensitive row');
+const encrypted = await vault.runtime.encrypt(dek.runtimeKey, plaintext, 'customers:42');
+await vault.runtime.rotate(dek.runtimeKey);
+
+// encrypted.keyVersion selects the old immutable version after rotation.
+const opened = await vault.runtime.decrypt(dek.runtimeKey, encrypted, 'customers:42');
+```
+
+## @forgezero/vault/runtime — Derive an address and sign without exporting its key
+
+Ethereum and Solana are the initial reviewed chain profiles. ForgeZero derives the documented path and signs canonical bytes or a 32-byte digest; transaction serialization remains the chain SDK’s responsibility.
+
+```text
+import {
+  createVault,
+} from '@forgezero/vault';
+
+const vault = createVault({ project: 'treasury', environment: 'production' });
+const signer = await vault.runtime.create({
+  kind: 'chain-key',
+  algorithm: 'ethereum-secp256k1',
+  label: 'settlement signer',
+  chain: { chain: 'ethereum', network: 'sepolia', account: 0, change: 0, index: 0 }
+});
+
+console.log(signer.address, signer.path, signer.publicKey);
+declare const transactionDigest: Uint8Array; // exactly 32 bytes
+const signed = await vault.runtime.sign(signer.runtimeKey, transactionDigest);
+```
+
 ## Three paths, and why they stay explicit
 
 Platform API logic already holds the requested realm master seed, so it opens the scoped envelope directly through an injected internal backend — no HTTP call, API key or local replica. A tenant on managed compute uses the local agent and its memory-only project scope. A tenant elsewhere signs HTTPS with an API-key seed. These share vault semantics and never silently fall through from a stronger posture to a weaker one.

package/dist/index.d.ts

@@ -28,6 +28,9 @@
  * returns the shape structurally, because a dependency edge in either direction
  * would make each package need the other.
  */
+import { VaultRuntime, type RuntimeRequest } from './runtime';
+export { VaultRuntime } from './runtime';
+export type { CreateRuntimeKeyOptions, RuntimeKeyInfo, SshCertificateOptions } from './runtime';
 export declare class VaultError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
@@ -127,6 +130,16 @@ export interface VaultOptions {
     fetch?: typeof globalThis.fetch;
     signer?: Signer;
     agentTransport?: AgentTransport;
+    /**
+     * Separately authorized Vault-runtime transport for managed workloads.
+     *
+     * The ordinary Agent socket is deliberately read-only. A supervisor may
+     * inject a request function backed by a distinct systemd credential or a
+     * future capability-scoped runtime socket. The function receives paths
+     * relative to this project's runtime API and must enforce the exact machine
+     * grants itself. It is never inferred from Agent access.
+     */
+    runtimeRequest?: RuntimeRequest;
     credential?: Credential;
     discovery?: DiscoveryEnvironment;
 }
@@ -147,6 +160,7 @@ export declare const DEFAULT_API_URL = "https://api.forgezero.net";
 export declare const DEFAULT_REQUEST_TIMEOUT_MS = 15000;
 export declare class ForgeZero {
     readonly credential: Credential;
+    readonly runtime: VaultRuntime;
     private readonly apiUrl;
     private readonly doFetch;
     private readonly signer?;
@@ -282,4 +296,4 @@ export declare function systemdCredentials(options?: SystemdCredentialOptions):
     readonly name: 'systemd';
     get(reference: string, field: string): Promise<string>;
 };
-export declare const VERSION = "0.1.22";
+export declare const VERSION = "0.1.23";

package/dist/index.js

@@ -1,3 +1,124 @@
+// src/runtime.ts
+import {
+  fromBase64Url,
+  toBase64Url
+} from "@forgezero/runtime/vault-runtime";
+
+class VaultRuntimeClientError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "VaultRuntimeClientError";
+  }
+}
+var json = (value) => ({ method: "POST", body: JSON.stringify(value) });
+
+class VaultRuntime {
+  request;
+  transport;
+  constructor(request, transport) {
+    this.request = request;
+    this.transport = transport;
+  }
+  available() {
+    if (this.transport === "managed-read-only") {
+      throw new VaultRuntimeClientError("MANAGED_RUNTIME_DELEGATION_REQUIRED", "Vault runtime operations require a separately granted external API key; the managed Agent replica is read-only.");
+    }
+  }
+  async create(options) {
+    this.available();
+    return this.request("/keys", json(options));
+  }
+  async rotate(runtimeKey) {
+    this.available();
+    return this.request(`/${encodeURIComponent(runtimeKey)}/rotate`, json({}));
+  }
+  async info(runtimeKey, version) {
+    this.available();
+    const query = version === undefined ? "" : `?version=${version}`;
+    return this.request(`/${encodeURIComponent(runtimeKey)}/public${query}`);
+  }
+  async password(runtimeKey, version) {
+    this.available();
+    return this.request(`/${encodeURIComponent(runtimeKey)}/secret`, json({ version }));
+  }
+  async encrypt(runtimeKey, plaintext, aad) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "encrypt",
+      plaintext: toBase64Url(plaintext),
+      aad
+    }));
+    return { keyVersion: result.version, ciphertext: result.ciphertext };
+  }
+  async decrypt(runtimeKey, encrypted, aad) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "decrypt",
+      ciphertext: encrypted.ciphertext,
+      aad,
+      version: encrypted.keyVersion
+    }));
+    return fromBase64Url(result.plaintext);
+  }
+  async wrap(runtimeKey, plaintextKey) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "wrap",
+      plaintextKey: toBase64Url(plaintextKey)
+    }));
+    return { keyVersion: result.version, wrapped: result.wrapped };
+  }
+  async unwrap(runtimeKey, wrapped) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "unwrap",
+      wrapped: wrapped.wrapped,
+      version: wrapped.keyVersion
+    }));
+    return fromBase64Url(result.plaintextKey);
+  }
+  async sign(runtimeKey, message) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({ operation: "sign", message: toBase64Url(message) }));
+    return { keyVersion: result.version, signature: fromBase64Url(result.signature) };
+  }
+  async verify(runtimeKey, message, signed) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({
+      operation: "verify",
+      message: toBase64Url(message),
+      signature: toBase64Url(signed.signature),
+      version: signed.keyVersion
+    }));
+    return result.valid;
+  }
+  async signJwt(runtimeKey, claims) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({ operation: "jwt-sign", claims }));
+    return { keyVersion: result.version, token: result.token };
+  }
+  async verifyJwt(runtimeKey, signed, options = {}) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({
+      operation: "jwt-verify",
+      token: signed.token,
+      version: signed.keyVersion,
+      ...options
+    }));
+    return result.claims;
+  }
+  async issueSshCertificate(runtimeKey, options) {
+    this.available();
+    return this.request(`/${encodeURIComponent(runtimeKey)}/ssh/certificates`, json({
+      ...options,
+      publicKey: toBase64Url(options.publicKey),
+      serial: options.serial?.toString()
+    }));
+  }
+}
+
 // src/index.ts
 import {
   deriveKeysFromSeed,
@@ -7,7 +128,6 @@ import {
   RESPONSE_KEY_HEADER,
   signRequest
 } from "@forgezero/runtime/identity";
-
 class VaultError extends Error {
   code;
   constructor(code, message) {
@@ -136,6 +256,7 @@ function apiOrigin(value) {
 
 class ForgeZero {
   credential;
+  runtime;
   apiUrl;
   doFetch;
   signer;
@@ -156,6 +277,8 @@ class ForgeZero {
     }
     this.project = options.project ?? "default";
     this.environment = options.environment ?? "production";
+    const runtimeRequest = options.runtimeRequest ?? ((path, init) => this.request(`/v1/vault/${this.scope()}/runtime${path}`, init));
+    this.runtime = new VaultRuntime(runtimeRequest, this.credential.mode === "external" ? "external" : options.runtimeRequest ? "managed-delegated" : "managed-read-only");
   }
   scope() {
     return `${encodeURIComponent(this.project)}/${encodeURIComponent(this.environment)}`;
@@ -382,7 +505,7 @@ function systemdCredentials(options = {}) {
     }
   };
 }
-var VERSION = "0.1.22";
+var VERSION = "0.1.23";
 export {
   vaultCredentials,
   systemdCredentials,
@@ -391,6 +514,7 @@ export {
   discover,
   directCredentials,
   createVault,
+  VaultRuntime,
   VaultError,
   VERSION,
   ForgeZero,

package/dist/providers.js

@@ -1,3 +1,124 @@
+// src/runtime.ts
+import {
+  fromBase64Url,
+  toBase64Url
+} from "@forgezero/runtime/vault-runtime";
+
+class VaultRuntimeClientError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "VaultRuntimeClientError";
+  }
+}
+var json = (value) => ({ method: "POST", body: JSON.stringify(value) });
+
+class VaultRuntime {
+  request;
+  transport;
+  constructor(request, transport) {
+    this.request = request;
+    this.transport = transport;
+  }
+  available() {
+    if (this.transport === "managed-read-only") {
+      throw new VaultRuntimeClientError("MANAGED_RUNTIME_DELEGATION_REQUIRED", "Vault runtime operations require a separately granted external API key; the managed Agent replica is read-only.");
+    }
+  }
+  async create(options) {
+    this.available();
+    return this.request("/keys", json(options));
+  }
+  async rotate(runtimeKey) {
+    this.available();
+    return this.request(`/${encodeURIComponent(runtimeKey)}/rotate`, json({}));
+  }
+  async info(runtimeKey, version) {
+    this.available();
+    const query = version === undefined ? "" : `?version=${version}`;
+    return this.request(`/${encodeURIComponent(runtimeKey)}/public${query}`);
+  }
+  async password(runtimeKey, version) {
+    this.available();
+    return this.request(`/${encodeURIComponent(runtimeKey)}/secret`, json({ version }));
+  }
+  async encrypt(runtimeKey, plaintext, aad) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "encrypt",
+      plaintext: toBase64Url(plaintext),
+      aad
+    }));
+    return { keyVersion: result.version, ciphertext: result.ciphertext };
+  }
+  async decrypt(runtimeKey, encrypted, aad) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "decrypt",
+      ciphertext: encrypted.ciphertext,
+      aad,
+      version: encrypted.keyVersion
+    }));
+    return fromBase64Url(result.plaintext);
+  }
+  async wrap(runtimeKey, plaintextKey) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "wrap",
+      plaintextKey: toBase64Url(plaintextKey)
+    }));
+    return { keyVersion: result.version, wrapped: result.wrapped };
+  }
+  async unwrap(runtimeKey, wrapped) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "unwrap",
+      wrapped: wrapped.wrapped,
+      version: wrapped.keyVersion
+    }));
+    return fromBase64Url(result.plaintextKey);
+  }
+  async sign(runtimeKey, message) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({ operation: "sign", message: toBase64Url(message) }));
+    return { keyVersion: result.version, signature: fromBase64Url(result.signature) };
+  }
+  async verify(runtimeKey, message, signed) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({
+      operation: "verify",
+      message: toBase64Url(message),
+      signature: toBase64Url(signed.signature),
+      version: signed.keyVersion
+    }));
+    return result.valid;
+  }
+  async signJwt(runtimeKey, claims) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({ operation: "jwt-sign", claims }));
+    return { keyVersion: result.version, token: result.token };
+  }
+  async verifyJwt(runtimeKey, signed, options = {}) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({
+      operation: "jwt-verify",
+      token: signed.token,
+      version: signed.keyVersion,
+      ...options
+    }));
+    return result.claims;
+  }
+  async issueSshCertificate(runtimeKey, options) {
+    this.available();
+    return this.request(`/${encodeURIComponent(runtimeKey)}/ssh/certificates`, json({
+      ...options,
+      publicKey: toBase64Url(options.publicKey),
+      serial: options.serial?.toString()
+    }));
+  }
+}
+
 // src/index.ts
 import {
   deriveKeysFromSeed,
@@ -7,7 +128,6 @@ import {
   RESPONSE_KEY_HEADER,
   signRequest
 } from "@forgezero/runtime/identity";
-
 class VaultError extends Error {
   code;
   constructor(code, message) {
@@ -136,6 +256,7 @@ function apiOrigin(value) {
 
 class ForgeZero {
   credential;
+  runtime;
   apiUrl;
   doFetch;
   signer;
@@ -156,6 +277,8 @@ class ForgeZero {
     }
     this.project = options.project ?? "default";
     this.environment = options.environment ?? "production";
+    const runtimeRequest = options.runtimeRequest ?? ((path, init) => this.request(`/v1/vault/${this.scope()}/runtime${path}`, init));
+    this.runtime = new VaultRuntime(runtimeRequest, this.credential.mode === "external" ? "external" : options.runtimeRequest ? "managed-delegated" : "managed-read-only");
   }
   scope() {
     return `${encodeURIComponent(this.project)}/${encodeURIComponent(this.environment)}`;
@@ -382,7 +505,7 @@ function systemdCredentials(options = {}) {
     }
   };
 }
-var VERSION = "0.1.22";
+var VERSION = "0.1.23";
 
 // src/providers.ts
 var MISSING = new Set(["ENTRY_NOT_FOUND", "VERSION_NOT_FOUND"]);

package/dist/runtime.d.ts

@@ -0,0 +1,97 @@
+import { type RuntimeCiphertext, type RuntimeWrappedKey, type VaultRuntimeAlgorithm, type VaultRuntimeCreateDescriptor, type VaultRuntimeDescriptor, type VaultRuntimeKind } from '@forgezero/runtime/vault-runtime';
+export type RuntimeRequest = <T>(path: string, init?: RequestInit) => Promise<T>;
+export interface RuntimeKeyInfo {
+    runtimeKey: string;
+    version: number;
+    kind: VaultRuntimeKind;
+    algorithm: VaultRuntimeAlgorithm;
+    label: string;
+    publicKey?: string;
+    address?: string;
+    path?: string;
+    chain?: string;
+    network?: string;
+    sshPublicKey?: string;
+}
+export type CreateRuntimeKeyOptions = VaultRuntimeCreateDescriptor;
+export interface SshCertificateOptions {
+    publicKey: Uint8Array;
+    type?: 1 | 2;
+    keyId: string;
+    principals: readonly string[];
+    validAfterSec: number;
+    validBeforeSec: number;
+    serial?: bigint;
+}
+export interface VersionedRuntimeCiphertext {
+    keyVersion: number;
+    ciphertext: RuntimeCiphertext;
+}
+export interface VersionedRuntimeWrappedKey {
+    keyVersion: number;
+    wrapped: RuntimeWrappedKey;
+}
+export interface VersionedRuntimeSignature {
+    keyVersion: number;
+    signature: Uint8Array;
+}
+export declare class VaultRuntimeClientError extends Error {
+    readonly code: 'MANAGED_RUNTIME_DELEGATION_REQUIRED';
+    constructor(code: 'MANAGED_RUNTIME_DELEGATION_REQUIRED', message: string);
+}
+/**
+ * How runtime operations reach the control plane.
+ *
+ * Managed secret replication remains read-only by default. A managed workload
+ * may use cryptographic runtime operations only when its supervisor injects a
+ * separate, capability-scoped request function. Keeping that delegation
+ * explicit prevents membership of the local Vault-reader group from silently
+ * granting signing, decryption or certificate authority.
+ */
+export type VaultRuntimeTransport = 'external' | 'managed-read-only' | 'managed-delegated';
+/**
+ * Explicit non-exporting cryptographic capabilities.
+ *
+ * This object is separate from ordinary Vault reads. Each method maps to a
+ * distinct API-key grant, so an application allowed to read a database URL is
+ * not silently able to sign transactions or decrypt application data.
+ */
+export declare class VaultRuntime {
+    private readonly request;
+    private readonly transport;
+    constructor(request: RuntimeRequest, transport: VaultRuntimeTransport);
+    private available;
+    create(options: CreateRuntimeKeyOptions): Promise<RuntimeKeyInfo & {
+        created: boolean;
+    }>;
+    rotate(runtimeKey: string): Promise<RuntimeKeyInfo>;
+    info(runtimeKey: string, version?: number): Promise<RuntimeKeyInfo>;
+    password(runtimeKey: string, version?: number): Promise<{
+        password: string;
+        version: number;
+    }>;
+    encrypt(runtimeKey: string, plaintext: Uint8Array, aad: string): Promise<VersionedRuntimeCiphertext>;
+    decrypt(runtimeKey: string, encrypted: VersionedRuntimeCiphertext, aad: string): Promise<Uint8Array>;
+    wrap(runtimeKey: string, plaintextKey: Uint8Array): Promise<VersionedRuntimeWrappedKey>;
+    unwrap(runtimeKey: string, wrapped: VersionedRuntimeWrappedKey): Promise<Uint8Array>;
+    sign(runtimeKey: string, message: Uint8Array): Promise<VersionedRuntimeSignature>;
+    verify(runtimeKey: string, message: Uint8Array, signed: VersionedRuntimeSignature): Promise<boolean>;
+    signJwt(runtimeKey: string, claims: Record<string, unknown>): Promise<{
+        keyVersion: number;
+        token: string;
+    }>;
+    verifyJwt(runtimeKey: string, signed: {
+        keyVersion: number;
+        token: string;
+    }, options?: {
+        issuer?: string;
+        audience?: string;
+    }): Promise<Record<string, unknown>>;
+    issueSshCertificate(runtimeKey: string, options: SshCertificateOptions): Promise<{
+        version: number;
+        certificate: string;
+        caPublicKey: string;
+        subjectPublicKey: string;
+    }>;
+}
+export type { VaultRuntimeDescriptor };

package/dist/runtime.js

@@ -0,0 +1,124 @@
+// src/runtime.ts
+import {
+  fromBase64Url,
+  toBase64Url
+} from "@forgezero/runtime/vault-runtime";
+
+class VaultRuntimeClientError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "VaultRuntimeClientError";
+  }
+}
+var json = (value) => ({ method: "POST", body: JSON.stringify(value) });
+
+class VaultRuntime {
+  request;
+  transport;
+  constructor(request, transport) {
+    this.request = request;
+    this.transport = transport;
+  }
+  available() {
+    if (this.transport === "managed-read-only") {
+      throw new VaultRuntimeClientError("MANAGED_RUNTIME_DELEGATION_REQUIRED", "Vault runtime operations require a separately granted external API key; the managed Agent replica is read-only.");
+    }
+  }
+  async create(options) {
+    this.available();
+    return this.request("/keys", json(options));
+  }
+  async rotate(runtimeKey) {
+    this.available();
+    return this.request(`/${encodeURIComponent(runtimeKey)}/rotate`, json({}));
+  }
+  async info(runtimeKey, version) {
+    this.available();
+    const query = version === undefined ? "" : `?version=${version}`;
+    return this.request(`/${encodeURIComponent(runtimeKey)}/public${query}`);
+  }
+  async password(runtimeKey, version) {
+    this.available();
+    return this.request(`/${encodeURIComponent(runtimeKey)}/secret`, json({ version }));
+  }
+  async encrypt(runtimeKey, plaintext, aad) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "encrypt",
+      plaintext: toBase64Url(plaintext),
+      aad
+    }));
+    return { keyVersion: result.version, ciphertext: result.ciphertext };
+  }
+  async decrypt(runtimeKey, encrypted, aad) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "decrypt",
+      ciphertext: encrypted.ciphertext,
+      aad,
+      version: encrypted.keyVersion
+    }));
+    return fromBase64Url(result.plaintext);
+  }
+  async wrap(runtimeKey, plaintextKey) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "wrap",
+      plaintextKey: toBase64Url(plaintextKey)
+    }));
+    return { keyVersion: result.version, wrapped: result.wrapped };
+  }
+  async unwrap(runtimeKey, wrapped) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "unwrap",
+      wrapped: wrapped.wrapped,
+      version: wrapped.keyVersion
+    }));
+    return fromBase64Url(result.plaintextKey);
+  }
+  async sign(runtimeKey, message) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({ operation: "sign", message: toBase64Url(message) }));
+    return { keyVersion: result.version, signature: fromBase64Url(result.signature) };
+  }
+  async verify(runtimeKey, message, signed) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({
+      operation: "verify",
+      message: toBase64Url(message),
+      signature: toBase64Url(signed.signature),
+      version: signed.keyVersion
+    }));
+    return result.valid;
+  }
+  async signJwt(runtimeKey, claims) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({ operation: "jwt-sign", claims }));
+    return { keyVersion: result.version, token: result.token };
+  }
+  async verifyJwt(runtimeKey, signed, options = {}) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({
+      operation: "jwt-verify",
+      token: signed.token,
+      version: signed.keyVersion,
+      ...options
+    }));
+    return result.claims;
+  }
+  async issueSshCertificate(runtimeKey, options) {
+    this.available();
+    return this.request(`/${encodeURIComponent(runtimeKey)}/ssh/certificates`, json({
+      ...options,
+      publicKey: toBase64Url(options.publicKey),
+      serial: options.serial?.toString()
+    }));
+  }
+}
+export {
+  VaultRuntimeClientError,
+  VaultRuntime
+};

package/dist/schema.js

@@ -1,3 +1,124 @@
+// src/runtime.ts
+import {
+  fromBase64Url,
+  toBase64Url
+} from "@forgezero/runtime/vault-runtime";
+
+class VaultRuntimeClientError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "VaultRuntimeClientError";
+  }
+}
+var json = (value) => ({ method: "POST", body: JSON.stringify(value) });
+
+class VaultRuntime {
+  request;
+  transport;
+  constructor(request, transport) {
+    this.request = request;
+    this.transport = transport;
+  }
+  available() {
+    if (this.transport === "managed-read-only") {
+      throw new VaultRuntimeClientError("MANAGED_RUNTIME_DELEGATION_REQUIRED", "Vault runtime operations require a separately granted external API key; the managed Agent replica is read-only.");
+    }
+  }
+  async create(options) {
+    this.available();
+    return this.request("/keys", json(options));
+  }
+  async rotate(runtimeKey) {
+    this.available();
+    return this.request(`/${encodeURIComponent(runtimeKey)}/rotate`, json({}));
+  }
+  async info(runtimeKey, version) {
+    this.available();
+    const query = version === undefined ? "" : `?version=${version}`;
+    return this.request(`/${encodeURIComponent(runtimeKey)}/public${query}`);
+  }
+  async password(runtimeKey, version) {
+    this.available();
+    return this.request(`/${encodeURIComponent(runtimeKey)}/secret`, json({ version }));
+  }
+  async encrypt(runtimeKey, plaintext, aad) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "encrypt",
+      plaintext: toBase64Url(plaintext),
+      aad
+    }));
+    return { keyVersion: result.version, ciphertext: result.ciphertext };
+  }
+  async decrypt(runtimeKey, encrypted, aad) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "decrypt",
+      ciphertext: encrypted.ciphertext,
+      aad,
+      version: encrypted.keyVersion
+    }));
+    return fromBase64Url(result.plaintext);
+  }
+  async wrap(runtimeKey, plaintextKey) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "wrap",
+      plaintextKey: toBase64Url(plaintextKey)
+    }));
+    return { keyVersion: result.version, wrapped: result.wrapped };
+  }
+  async unwrap(runtimeKey, wrapped) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/crypt`, json({
+      operation: "unwrap",
+      wrapped: wrapped.wrapped,
+      version: wrapped.keyVersion
+    }));
+    return fromBase64Url(result.plaintextKey);
+  }
+  async sign(runtimeKey, message) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({ operation: "sign", message: toBase64Url(message) }));
+    return { keyVersion: result.version, signature: fromBase64Url(result.signature) };
+  }
+  async verify(runtimeKey, message, signed) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({
+      operation: "verify",
+      message: toBase64Url(message),
+      signature: toBase64Url(signed.signature),
+      version: signed.keyVersion
+    }));
+    return result.valid;
+  }
+  async signJwt(runtimeKey, claims) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({ operation: "jwt-sign", claims }));
+    return { keyVersion: result.version, token: result.token };
+  }
+  async verifyJwt(runtimeKey, signed, options = {}) {
+    this.available();
+    const result = await this.request(`/${encodeURIComponent(runtimeKey)}/sign`, json({
+      operation: "jwt-verify",
+      token: signed.token,
+      version: signed.keyVersion,
+      ...options
+    }));
+    return result.claims;
+  }
+  async issueSshCertificate(runtimeKey, options) {
+    this.available();
+    return this.request(`/${encodeURIComponent(runtimeKey)}/ssh/certificates`, json({
+      ...options,
+      publicKey: toBase64Url(options.publicKey),
+      serial: options.serial?.toString()
+    }));
+  }
+}
+
 // src/index.ts
 import {
   deriveKeysFromSeed,
@@ -7,7 +128,6 @@ import {
   RESPONSE_KEY_HEADER,
   signRequest
 } from "@forgezero/runtime/identity";
-
 class VaultError extends Error {
   code;
   constructor(code, message) {
@@ -136,6 +256,7 @@ function apiOrigin(value) {
 
 class ForgeZero {
   credential;
+  runtime;
   apiUrl;
   doFetch;
   signer;
@@ -156,6 +277,8 @@ class ForgeZero {
     }
     this.project = options.project ?? "default";
     this.environment = options.environment ?? "production";
+    const runtimeRequest = options.runtimeRequest ?? ((path, init) => this.request(`/v1/vault/${this.scope()}/runtime${path}`, init));
+    this.runtime = new VaultRuntime(runtimeRequest, this.credential.mode === "external" ? "external" : options.runtimeRequest ? "managed-delegated" : "managed-read-only");
   }
   scope() {
     return `${encodeURIComponent(this.project)}/${encodeURIComponent(this.environment)}`;
@@ -382,7 +505,7 @@ function systemdCredentials(options = {}) {
     }
   };
 }
-var VERSION = "0.1.22";
+var VERSION = "0.1.23";
 
 // src/schema.ts
 function managedSchemas(vault, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/vault",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -30,6 +30,10 @@
     "./providers": {
       "types": "./dist/providers.d.ts",
       "default": "./dist/providers.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
     }
   },
   "scripts": {
@@ -42,7 +46,7 @@
     "@types/bun": "latest"
   },
   "dependencies": {
-    "@forgezero/runtime": "^0.1.17"
+    "@forgezero/runtime": "^0.1.18"
   },
   "peerDependencies": {
     "@noble/curves": "^2.2.0",