Skip to main content
Builtins catalog / nika:hash

Data

Tool family from the canonical registry.

invoke

Call this builtin through the invoke verb.

​
Read this contract

This reference preserves the specification at the revision linked below. Source examples are fragments: their surrounding tasks, inputs and permissions are not supplied here. Consult engine status and nika catalog --tools --json for the installed implementation; a registry declaration is not a runtime qualification.

​
Usage and behavior

> Reference-engine availability at 6ac427c5e62dc450d1d2393e3eec169e9566f6a3: > digest calls accept content, algo and encoding. The op argument, > including explicit op: hash, and the sign/verify forms below are > spec-ahead of this engine pin. Their normative contract is retained; > these examples do not announce implementation availability.
illustration
Content hashing · default blake3 (fastest modern cryptographic hash · parallel · secure) · or sha256/sha512. md5/sha1 NOT supported (cryptographically broken · NIKA-BUILTIN-HASH-001 validation_error on an unsupported algo). encoding: hex (default) | base64. Use cases · cache keys · content addressing · provenance. content: accepts a string or a structured value (an object/array is hashed as compact JSON — do not pre-pipe | tojson). Digest arguments (op omitted or op: hash). content MUST be present and non-null. Strings are hashed verbatim; every other non-null JSON value (object, array, number or boolean) is hashed as compact JSON. An empty string, 0, false, an empty object or array, and null members inside an object or array are valid content. algo and encoding use their defaults only when absent. When present, each MUST be a string in its listed closed set; null, another JSON type, an empty string or an unsupported value is a validation error (NIKA-BUILTIN-HASH-001). Statically known invalid literals MUST be refused before execution. A valid substitution expression whose result is not yet known is checked after resolution; it does not exempt other, independently decidable arguments from validation. op: · hash (default) · sign · verify (normative · v0.1 surface). The engine already signs and verifies Ed25519 — the run seal is one Ed25519 signature over the journal, minted by nika key init and checked by the evidence verifier. The language could not reach any of it. A capability that ships and stays unreachable from the file is not a shipped capability, so op: exposes it through the builtin that already owns the digest. sign returns the signature string; verify returns a boolean and never throws on a bad signature (a false verdict is data, not an error — a workflow branches on it with when:). A malformed key, an unknown op:, or a missing per-op required arg is NIKA-BUILTIN-HASH-001 (validation_error). The key rides secrets: — that is a hard rule, not a convention. A private key reached from the ambient environment or an implicit on-disk keyring would make nika:hash read state its declaration does not name, which is exactly the pure-compute-that-is-not-pure defect the permits boundary exists to refuse. Declaring the key under secrets: keeps it inside the three-authority family, keeps it masked in logs, and keeps its reach governed by egress: like any other secret. What this closes, and what it does NOT (bounded honestly). It closes Ed25519 signing and verification — detached signatures over content the workflow already holds: release manifests, provenance attestations, inter-workflow handoffs, checkpoint verification. It does not close RS256/JWT: that is RSA with a different key format, a different padding scheme and a token envelope, none of which this surface has. A GitHub App credential exchange is RS256 and stays out of reach — do not read this section as authenticating anything that mints a JWT. capability_classification for the builtin moves from pure_internal to secret-reading under op: sign; the classification row in canon/builtins.yaml follows when the engine wires the op (today the engine’s ARGS gate declares content · algo · encoding only, so op: is spec-ahead-of-engine and this file says so rather than implying a green that does not exist).

Arguments

Pass the values required by the tool contract.

Permissions

Understand authority before granting effects.

Errors and recovery

Read diagnostics and choose a recovery policy.

Workflow templates

Put the fragment inside a complete workflow.

​
Contract provenance

Read the pinned specification · Canonical registry. Tool identity: nika:hash. Specification revision: f8c5df2127c7. The Lab language identity is language:tool:hash; the registry view is ecosystem:tool/nika:hash. They refer to this contract without merging their graph identities.