Osy#betaRun it on Osyrin: osyrin.com

Reference / Function

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

Crypto.SealToHost(publicKey, host, kind, name, fromField: "token") → string (fcs1 text)

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.

preview1 example compiled by CIfunctioncryptoencryptionsecurity

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
publicKeythe host's P-256 public key, as base64 SPKI (or PEM)
host, kind, namewhat 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 answerthe sealed text, fcs1.…

Signature#

string sealedText = Crypto.SealToHost(hostKey, "ft-mini", "github", "GH_TOKEN", fromField: "token");

Description#

A page that hands a host a token#

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#

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.<eph>.<nonce>.<ciphertext>          each part base64url, no padding
partwhat it is
ephthe SPKI of a fresh ephemeral P-256 key — a new one for every seal
keyHKDF-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
nonce12 random bytes
ciphertextAES-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#

Related

Crypto.Encrypt and Crypto.Decrypt

Encrypt and decrypt values under your app's key, which the platform mints, protects, and rotates for you. There is no…

Setting a secret from a page — the value goes from the browser to each zone

An application's secret is sealed in each zone that runs it, under a short-lived grant the control plane signs. From a…

component

The one archetype for all UI: a bounded reactive unit — typed props, reactive members (fields, `live`…