std/host-op

Import from @norbital-ai/std/host-op

std/host-op (§7.1 "Operations"): the one signed-host-operation scheme for hosts and their operator CLIs. A MAC (HMAC-SHA256, base64url) over the newline-joined v1 · scope · host · op · ts · nonce · sha256(body), carried in the bolt-op-* headers. A request older or newer than five minutes, one for another scope, host or operation, a bad MAC and a replayed nonce are refused before the body is read as an operation. Nonces are durable: the host's NonceStore.

NonceStore interface

interface NonceStore<E = never> {
    claim(nonce: string, at: number): Effect.Effect<boolean, E>;
}

Where a host keeps the nonces it has accepted. claim succeeds with true the first time a nonce is offered and false after, across restarts; at (epoch ms) lets the store prune nonces older than OP_WINDOW_MS.

Members

Name	Type	Description
claim	(nonce: string, at: number) => Effect.Effect<boolean, E>

Source: packages/std/src/host-op.ts:23

OP_HEADERS const

const OP_HEADERS: { readonly op: "bolt-op-name"; readonly ts: "bolt-op-ts"; readonly nonce: "bolt-op-nonce"; readonly mac: "bolt-op-mac"; }

The request headers a signed operation travels in: its name, timestamp (epoch ms), nonce and MAC.

Members

Name	Type	Description
op	"bolt-op-name"
ts	"bolt-op-ts"
nonce	"bolt-op-nonce"
mac	"bolt-op-mac"

Source: packages/std/src/host-op.ts:9

OP_WINDOW_MS const

const OP_WINDOW_MS: number

How far a signature's timestamp may be from the verifier's clock, either way.

Source: packages/std/src/host-op.ts:16

OpKey type

type OpKey = {
    readonly secret: string | Uint8Array;
    readonly scope: string;
};

The secret and the scope it signs for: a workspace handle (bolt-server) or a platform deployment environment.

Members

Name	Type	Description
secret	string | Uint8Array
scope	string

Source: packages/std/src/host-op.ts:18

OpRefused class

class OpRefused extends OpRefused_base {
}

Why a signed operation was refused: no or malformed signature, outside the window, a bad MAC, or a replayed nonce.

Members

Name	Type	Description
reason	Schema.Literals<readonly ["unsigned", "stale", "badSignature", "replayed"]>

Source: packages/std/src/host-op.ts:28

signOp function

function signOp(key: OpKey, host: string, op: string, body: string | Uint8Array, now: number, nonce?: string): { readonly [header: string]: string; }

The headers one operation carries to host (the Host the verifier sees in the request URL).

Parameters

Name	Type	Description
key	OpKey	secret: string | Uint8Array scope: string
host	string
op	string
body	string | Uint8Array
now	number
nonce?	string

Source: packages/std/src/host-op.ts:50

verifyOp function

function verifyOp<E>(key: OpKey, request: Request, body: string | Uint8Array, nonces: NonceStore<E>): Effect.Effect<string, OpRefused | E>

The operation name of an authentic, fresh, first-seen request; else OpRefused (the nonce is claimed last).

Parameters

Name	Type	Description
key	OpKey	secret: string | Uint8Array scope: string
request	Request
body	string | Uint8Array
nonces	NonceStore<E>	claim: (nonce: string, at: number) => Effect.Effect<boolean, E, never>

Source: packages/std/src/host-op.ts:68