> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nika.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# nika:hash

> Usage, declared contract and source links for this Nika builtin.

[Builtins catalog](https://docs.nika.sh/reference/builtins.md) / `nika:hash`

> [card] Data
>
> Tool family from the canonical registry.

> [card] [invoke](https://docs.nika.sh/reference/language/words/invoke.md)
>
> 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](https://docs.nika.sh/reference/status.md) 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.

```yaml illustration theme={"system"}
with: { report: "${{ tasks.X.output }}" }
invoke: { tool: "nika:hash", args: { algo: blake3, content: "${{ with.report }}", encoding: hex } }

# Normative op forms · spec-ahead at the engine pin named above
invoke: { tool: "nika:hash", args: { op: sign,   content: "${{ with.manifest }}", key: "${{ secrets.release_key }}" } }
invoke: { tool: "nika:hash", args: { op: verify, content: "${{ with.manifest }}", public_key: "${{ const.release_pub }}", signature: "${{ with.sig }}" } }
```

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.

| Arg | Ops | Notes |
| - | - | - |
| `content` | all | required · the bytes under the operation |
| `algo` | `hash` | `blake3` (default) · `sha256` · `sha512` |
| `encoding` | `hash` · `sign` | `hex` (default) · `base64` — the output encoding |
| `key` | `sign` | required · the Ed25519 private key · **MUST be a `${{ secrets.X }}` reference** |
| `public_key` | `verify` | required · the Ed25519 public key (a `const:`/`inputs:` value — a public key is not a secret) |
| `signature` | `verify` | required · the signature to check, in `encoding:` |

`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).

***

## Related concepts

> [card] [Arguments](https://docs.nika.sh/reference/language/words/args.md)
>
> Pass the values required by the tool contract.

> [card] [Permissions](https://docs.nika.sh/concepts/security.md)
>
> Understand authority before granting effects.

> [card] [Errors and recovery](https://docs.nika.sh/reference/error-codes.md)
>
> Read diagnostics and choose a recovery policy.

> [card] [Workflow templates](https://docs.nika.sh/guides/templates.md)
>
> Put the fragment inside a complete workflow.

## Contract provenance

[Read the pinned specification](https://github.com/supernovae-st/nika-spec/blob/5cd95cd25c0ff453be266794a03666e5e3f2d7a8/stdlib/builtins-v0.1.md#L408) · [Canonical registry](https://github.com/supernovae-st/nika-spec/blob/5cd95cd25c0ff453be266794a03666e5e3f2d7a8/canon/builtins.yaml).

Tool identity: `nika:hash`. Specification revision: `5cd95cd25c0f`.

> [card] [Documentation](https://docs.nika.sh/introduction.md)
>
> Guides, reference contracts and working examples.

> [card] [Language spec](https://github.com/supernovae-st/nika-spec)
>
> the nine-key envelope, Apache-2.0. The contract these docs explain.

> [card] [Engine source](https://github.com/supernovae-st/nika)
>
> Rust, AGPL-3.0-or-later. Every commit public.

> [card] [TypeScript SDK](https://docs.nika.sh/sdk/overview.md)
>
> Use one typed lifecycle locally or against authenticated nika serve HTTP.

> [card] [Editor extension](https://marketplace.visualstudio.com/items?itemName=supernovae.nika)
>
> The editor extension, frozen at 0.120 and not qualified with 0.124: use `nika lsp` and the JSON Schema.

> [card] [Homebrew tap](https://github.com/supernovae-st/homebrew-tap)
>
> `brew install supernovae-st/tap/nika` for the latest tagged CLI release.

> [card] [SuperNovae](https://supernovae.studio)
>
> The Paris studio crafting Nika. 🦋


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.