# Crypto.SealToHost — seal a page input to a host's public key

> Seals what a person types into an UNBOUND password input to a host's P-256 public key, in the browser, and answers the sealed text (fcs1) that only that host's private key opens — and only as the host, kind and name it was sealed for. The value is never an Osy# value: the input is read by the verb, emptied afterwards, and the plaintext never reaches the server — not in a request, a continuation, or a trace.

<!-- id: function-crypto-seal-to-host · area: function · stability: preview · html: https://osysharp.com/reference/function/crypto-seal-to-host/ -->

## Summary        {#summary}
`Crypto.SealToHost` lets a page take a credential — an API token, a password — and hand it to **one host** without
the server in between ever holding it. The browser seals it to the host's public key; the server only ever sees the
sealed text, which it can store or pass on but cannot open.

| | what it is |
|---|---|
| `publicKey` | the host's P-256 public key, as base64 SPKI (or PEM) |
| `host`, `kind`, `name` | what the sealed text is FOR — it opens only as these three, so it cannot be replayed as another credential |
| `fromField:` | the **name** of a password input on the page, which must have **no** `value:` binding |
| the answer | the sealed text, `fcs1.…` |

## Signature      {#signature}
```osy syntax
string sealedText = Crypto.SealToHost(hostKey, "ft-mini", "github", "GH_TOKEN", fromField: "token");
```

## Description    {#description}

### A page that hands a host a token   {#example}
```osy title="seal in the browser, store the sealed text" test app=function-crypto-seal-to-host
string HostKey() {
  return "";   // the host's published P-256 public key, base64 SPKI
}

void Store(string sealedText) {
  Log.Information("stored a sealed credential of {Length} characters", sealedText.Length);
}

[Route("/credential")]
[AllowAnonymous]
component Credential() {
  action Save() {
    string sealedText = Crypto.SealToHost(HostKey(), "ft-mini", "github", "GH_TOKEN", fromField: "token");
    Store(sealedText);
  }

  render {
    Input(type: "password", name: "token");   // NO `value:` — the verb reads it, seals it, and empties it
    Button("Save", onPress: Save);
  }
}
```

### Why the value is a field NAME and not an argument   {#why}
When an action awaits a server function — `Store` above — the page hands the server a **continuation**: the action's
locals, so the server can resume it. A trace records the same locals. If the value were an argument, a local or a
bound component field, it would ride that continuation to the server. Naming the input keeps the plaintext in the
input until it is sealed, and nowhere after.

So the verb **refuses a bound input** (`Input(value: draft, …)`) with a message saying why — a binding has already
copied every keystroke into component state — and the compiler refuses a value handed to it directly:
`Crypto.SealToHost(key, "h", "k", "n", "ghp_…")` does not compile. The input is emptied once it has been read, whether
the seal succeeded or not.

A page that is wrong — no input by that name, two of them, a bound one, an empty one, a key that is not a P-256
public key, a `host`, `kind` or `name` that is empty or contains `|` — throws an `InvalidOperationException`, and
nothing is sealed.

### The format   {#fcs1}
```text
fcs1.<eph>.<nonce>.<ciphertext>          each part base64url, no padding
```

| part | what it is |
|---|---|
| `eph` | the SPKI of a fresh ephemeral P-256 key — a new one for every seal |
| key | HKDF-SHA256 over the ECDH shared secret (the x-coordinate) of `eph` and the host's key; salt = `eph`'s SPKI bytes, info = `factory-credential-v1`, 32 bytes |
| `nonce` | 12 random bytes |
| `ciphertext` | AES-256-GCM of the UTF-8 value under that key and nonce, with the 16-byte tag appended, and the additional data below |

The additional data is the UTF-8 of `fcs1|host|kind|name` — which is why none of the three may contain `|`.

The host opens it with its private key: ECDH with `eph`, the same HKDF, and AES-GCM with the same additional data. In
.NET that is `ECDiffieHellman.DeriveRawSecretAgreement`, `HKDF.DeriveKey` and `AesGcm.Decrypt`. Opened as any other
host, kind or name, the tag does not verify and nothing is returned. Sealing the same value twice gives different text.

## See also   {#see-also}
- [Crypto.Encrypt and Crypto.Decrypt](https://osysharp.com/reference/function/crypto-encrypt/) — encryption under your own app's key, on the server
- [Setting a secret from a page — the value goes from the browser to each zone](https://osysharp.com/reference/zones/setting-a-secret-from-a-page/) — the same input-by-name rule, for a zone's secret
- [component](https://osysharp.com/reference/ui/component/) — actions, and where a client verb is called from
