Documentation

What are Secrets?#

Secrets are encrypted API keys, tokens, or sensitive data stored on-chain. They are automatically decrypted and injected as environment variables when your WASM code executes. The keystore service running in TEE handles all encryption/decryption operations.

Creating Secrets#

Use the Secrets page to create encrypted secrets. Specify repository, branch (optional), and profile name. Secrets are encrypted client-side before being stored on-chain.

Secrets Binding Types#

Secrets can be bound to different identifiers depending on your use case:

Locking a secret to one build#

Every rule above answers who may read a secret. This one answers what may read it, and it exists because those are different questions.

When you hand a credential to a project, you are trusting its code — and that code can change under you. A new version is published and your key goes to it, without you being asked. The author need not be hostile for this to matter: a dependency moves, a build script changes, somebody force-pushes. One build only removes that trust from the arrangement. The secret opens for one exact binary, identified by the SHA-256 of the bytes that run, and a rebuild is refused. The check is made inside the attested enclave that holds the key, against the measurement the attested worker reports for the code it is about to execute — so nothing the calling code says about itself enters into it.

Your key does not become unusable at the next release. The lock and the value are stored apart: Access moves the lock to a new build without re-entering anything, so a PROTECTED_ key generated in the enclave keeps its value across every release you approve. The decision moves from the author's publish button to yours.

The hash does not drift on its own. A project built from GitHub compiles to the same bytes every time it is built from the same commit, so a lock you set stays good until someone publishes new code — which is exactly the event it exists to catch. For that to hold, a project built from source has to commit its Cargo.lock: without one its dependency versions are chosen afresh at build time, and the bytes can change with no change to your code.

Lending a secret to an agent#

A secret you store stays yours. Handing it to an agent does not copy it anywhere: the row keeps your account as its owner and your profile as its name, and the agent merely names it in a call through secrets_ref. Take the grant away and it has nothing — there was never a second copy to take back.

A grant names any NEAR account: a person, an ordinary named account, or a custody wallet. A wallet's account is the implicit one that pays for its calls, which is why it looks like 64 hex characters; the Access form offers your own wallets by name so you need not hunt for it.

An expiry is not a revocation. The expiry is for a grant you already know the end of — a lease, a trial, a day of work — and it lapses without you doing anything. Revoking is for changing your mind sooner: remove the account and the next call is refused. The secrets page lists every account your secrets are handed to, with a one-click revoke, so a grant that outlived its agent is found rather than remembered.

The rules compose, and this is the tightest useful shape: And[Whitelist[agent], ValidUntil(tomorrow), WasmHash(build)] — one agent, one day, one build. The agent is admitted only while all three hold.

Access Control#

Control who can decrypt your secrets using flexible access conditions:

• AllowAll: anyone who names the secret can run the project with it — right for an app's own credential named in its manifest, not for a personal one
• Whitelist: specific NEAR accounts only — the default for a new personal secret under a project is your own account
• NEAR Balance: accounts with a minimum NEAR balance
• FT/NFT Balance: token holders only
• Account Pattern: regex over the account id, anchored to the whole id
• Until a date: admits only before an instant (UTC); with a whitelist under AND it is a grant that lapses on its own
• One build only: admits only a run of one exact build — the SHA-256 of the WebAssembly bytes, shown as Executed binary in an execution's details. With a whitelist under AND it is your secret that a rebuild cannot open; Access moves it to the next build without re-storing, so a generated PROTECTED_ key keeps its value across the releases you approve
• Logic: AND / OR / NOT combinations of the above

Access on a secret card changes the condition without touching the value: grant an agent by its wallet account (the 64-character account that pays for its calls — your own custody wallets are offered by name), with an expiry for a leased agent, and revoke by removing it. The secrets page also lists every account your secrets are handed to, with a one-click revoke, so a grant that has outlived its agent is found rather than remembered. The agent names the secret in its call with secrets_ref.

The author's secret — for any project#

Everything above is a secret a caller names in a call. A project can also carry one of its author's own — an upstream API key, an SMTP password — decrypted into every run without the caller naming anything. Any WASI project, not only a connector: the artefact declares it in its outlayer.manifest section:

{ "author_secrets": { "profile": "prod" } }

Then store that profile on the Secrets page under the accessor Project of this project (the form says so beside the profile field). The row's owner is the publishing account unless the manifest names another owner — a team account may hold the credential while a developer account publishes.

Its access condition is who may run the project at all: the keystore judges it against the real caller before anything executes, so AllowAll makes a public app, a whitelist or a DAO role makes an app for a circle, and a caller outside it is refused before the code runs. A declared profile nobody has stored refuses every run, with a message that says what to store. A caller's own secret (named with secrets_ref) sits beside the author's; a name defined on both sides refuses that call, and a name the caller brings that the author never stored is added as the caller's — store every name your code reads.

Secrets left FOR an agent#

Everything above is a secret you own. This is the other direction: a credential stored under an agent's account, so a connector it calls can use your API token without the agent ever holding it.

The agent cannot store it itself. Its custody wallet has no NEAR to pay for the write, and the key that authorises one never leaves the TEE — so the coordinator prepares the call and a person sends and pays for it. The value is encrypted in the browser before it goes anywhere: neither the page nor the coordinator sees it.

Store one on the Secrets page, in the “for an agent” form. A link may propose which secret to create and deliberately cannot carry its value or the agent's key — both would end up in browser history, referrers and proxy logs:

https://app.outlayer.ai/secrets?project=connectors.outlayer.near/near-email&name=SENDGRID_KEY

It is filed against a scope — a project id or a WASM hash — and read only by code running under it. Cost is ~0.1 NEAR, the excess refunded.

Asking for it at call time

Nothing is fetched unless the call asks. Most calls need no secret, and a lookup that always ran would add a keystore round trip to every one of them:

curl -s -X POST -H "Content-Type: application/json" \
  -H "X-Payment-Key: $PAYMENT_KEY" \
  -H "x-use-owner-secret: true" \
  -d '{"input":{"operation":"send"}}' \
  "https://api.outlayer.ai/call/connectors.outlayer.near/near-email"

The address it is read from is the agent's own account — the primary key of its payment key's row, not anything the caller can choose. That is what makes it unforgeable: only the agent's wk_ can make that wallet sign.

Using Secrets in Code#

Access secrets in your WASM code using standard environment variable functions. In Rust:std::env::var("API_KEY")

Storage Costs#

Secrets storage costs are proportional to data size plus indexing overhead (~64 bytes). Storage fees are refunded when you delete secrets.

Security Model#

Secrets are encrypted in your browser using ECIES: an ephemeral X25519 ECDH exchange against the keystore's public key, HKDF-SHA256 to derive the symmetric key, and ChaCha20-Poly1305 AEAD for the payload. The matching private key exists only inside the TEE, so not even the browser that encrypted a secret can decrypt it again — the public key published by the keystore can encrypt and nothing else.

Decryption happens in TEE workers with attestation verification, so plaintext exists only inside the enclave. Ciphertext is stored on-chain and is useless without the enclave-held key. Each encryption uses a fresh ephemeral keypair and nonce, so encrypting the same value twice produces different ciphertext, and the AEAD tag makes tampering detectable rather than silently decrypting to garbage.

Confidential Key Derivation (CKD)#

┌──────────┐
│ Keystore │
│   TEE    │
│          │
│• Generate│
│  keypair │
│• TDX     │
│ measures │
└────┬─────┘
     │
     │ 1. Submit
     │ attestation
     ▼
┌──────────┐
│   DAO    │
│ Contract │
│          │
│• Verify  │
│  attest. │
│• Create  │
│ proposal │
└────┬─────┘
     │
     │ 2. Send
     │ proposal
     ▼
┌──────────┐
│   DAO    │
│ Members  │
│          │
│• Review  │
│ measures │
│• Vote    │
│  (>50%)  │
└────┬─────┘
     │
     │ 3. Approve
     ▼
┌──────────┐
│         │
│APPROVED  │
│          │
│Functional│
│key added │
│ to DAO   │
└──────────┘

┌──────────┐
│ Keystore │
│   TEE    │
│          │
│ Has     │
│  func key│
│• Needs   │
│  CKD     │
└────┬─────┘
     │
     │ 1. Request
     │ CKD with
     │ func key
     ▼
┌──────────┐
│   DAO    │
│ Contract │
│(Gateway) │
│          │
│Only func │
│key can   │
│call      │
└────┬─────┘
     │
     │ 2. Forward
     │ request_key()
     ▼
┌──────────┐
│   MPC    │
│ Contract │
│          │
│v1.signer-│
│   prod   │
│          │
│Coordinate│
│derivation│
└────┬─────┘
     │
     │ 3. Distribute
     │ to nodes
     ▼
┌──────────┐
│   MPC    │
│  Nodes   │
│          │
│  ● ● ●   │
│   ● ●    │
│  ● ● ●   │
│          │
│ Compute  │
│BLS12-381 │
└────┬─────┘
     │
     │ 4. Return
     │ encrypted
     │ derivation key
     ▼
┌──────────┐
│ Keystore │
│ receives │
│encrypted │
│   key    │
│          │
│ Only TEE │
│   can    │
│ decrypt  │
└──────────┘

DAO Governance & Keystore Authorization#

Keystore Authorization Flow

1. On-Chain TEE Verification: Keystore submits Intel TDX attestation directly to DAO contract. The contract cryptographically verifies the Intel certificate and TEE measurements (MRTD + RTMR0-3) on-chain. This ensures submissions can only come from genuine TEE with verified binary.
2. Automated Validation: DAO contract automatically rejects any submission that:
   • Doesn't have valid Intel signature
   • Comes from unverified measurements (MRTD + RTMR0-3)
   • Attempts to bypass TEE requirements
3. DAO Voting: Only after passing on-chain TEE verification, DAO members vote to authorize keystore based on operator reputation, stake, and network capacity needs
4. MPC Key Request: Once approved, keystore requests derivation key from MPC Network using CKD protocol with its unique keystore_id
5. Derivation Key Receipt: Keystore receives encrypted derivation key, decrypts it in TEE, and can now decrypt user secrets while keeping all keys inside the enclave

// TEE app generates key pair
let (a, A) = generate_elgamal_keypair();

// Include A in attestation report_data
let attestation = get_tdx_attestation(A);

// Call developer contract
developer_contract.get_key(attestation, A);

// Developer contract validates and calls MPC
mpc_contract.gen_app_private_key(A);

// Receive encrypted secret (Y, C)
// Decrypt: sig = C - a·Y
// Derive: secret = HKDF(sig)

CKD & MPC FAQ#