# Nuncio Secrets

Canonical URL: https://nuncio.one/docs/components/secrets
Markdown URL: https://nuncio.one/docs/components/secrets.md
Summary: Secrets stores user-owned details so agents can discover suitable fields and request authorized values for the intended task.
Description: Nuncio Secrets is user-data storage designed specifically for personal AI agents and user-approved data use.

## Canonical Answer

Secrets stores user-owned details so agents can discover suitable fields and request authorized values for the intended task. Nuncio Secrets is user-data storage designed specifically for personal AI agents and user-approved data use. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context.

![How Nuncio Secrets is organised: identities, items, fields](https://nuncio.one/docs-assets/images/components-memory-model.svg)

## Key Points

- Secure data storage designed for personal AI agents, not a prompt memory system.
- Items group related fields and can identify the person or organization they belong to.
- Users can manage data directly, while agents can request or save approved data during work.
- Metadata discovery is value-free; an approved release may return task values to the host.

## Agent Secrets Storage

Nuncio Secrets is the user-data layer for personal AI agents. It stores reusable facts and secrets in a user-bound model, so an agent can ask for the right data at the right moment without asking the user to paste passwords, identity details, card values, or addresses into chat. Users can create and edit records from the UI. Agents can request records during a checkout, ask the user for missing data, and save approved values for future sessions.

## Items, Subjects, And Fields

The current storage model is intentionally small: the user owns each secret, an item groups related fields, and optional subject links record who or what the item is about. A subject link can distinguish the user, a spouse, another traveler, or an organization when that context was explicitly saved. This supports requests such as “buy tickets for me and my wife” without claiming a separate identity graph or inferring relationships that the user did not provide.

```ts
type SecretsItem = {
  id: string;
  owner_user_id: string;
  display_label: string;
  status: 'active' | 'pending' | 'revoked' | 'deleted';
  subject_links: Array<{ subject_ref: string; role?: string }>;
  scope: Array<Record<string, unknown>>;
  fields: SecretsField[];
  availability: Record<string, unknown>;
};
```

## Entries

An entry is a reusable secret: login, identity document, payment method, wallet, address-like identity data, or another saved record. A user can have several entries with overlapping fields. If a checkout needs a delivery address and several address entries match, Nuncio should ask a choice request instead of guessing. The selected entry becomes the source for that session, and the user can save new entries when an agent discovers missing information along the way.

```ts
type SecretsField = {
  name: string;
  label: string;
  hint?: string | null;
  value_type?: 'date' | 'phone_number' | 'person_name' | 'country';
  is_secret: boolean;
};
```

## Fields

A field is a key-value pair with a label, type, requirement flag, sensitivity, and optional semantic tags. Fields can appear in several entries: date of birth can exist on a basic identity entry, a passport entry, and a driver license entry. Nuncio Secrets keeps this flexible by separating schema definitions from values and by enforcing a sensitivity floor for hard-secret keys such as passwords, card numbers, CVV, document numbers, private keys, seed phrases, and dates of birth.

Field property | Meaning | Example
--- | --- | ---
key | Stable machine key used by agents and form matching. | date_of_birth
label | Human-readable label shown to the user. | Date of birth
type | Value type used by editors and validation. | text, secret, date, email, url
sensitivity | Whether the field is marked secret. | secret flag
semantic_tags | Hints for secure matching and Secrets fill. | document_number, password

## Choice Requests

When more than one entry can satisfy a request, Nuncio Secrets should hand the decision to the user. For example, a user may have a home address, an office address, and a hotel address; the agent should not infer which one to use for the current checkout. A choice request can show the safe labels and summaries, let the user pick the right entry, and optionally collect a note that helps the agent continue.

- Use choice requests when multiple identities, addresses, documents, or payment-related entries match.
- Show safe summaries rather than raw values.
- Persist the selected entry only when the user explicitly chooses to save or reuse it.

## Agent Access

Agents use the current connected Secrets tools rather than direct database access. Start with value-free metadata and template discovery, select the exact fields and revisions, and follow any returned consent or secure collection request. Continue the same request after its recorded decision; Save and Use once have separate persistence outcomes.

## Authorized Task Values

Discover saved metadata first, then resolve exact selected fields and current revisions through the connected Secrets workflow. An approved response may return values to the host for this task. This does not provide model or transcript isolation.

- Use authorized values only for the intended form, person and role.
- Keep credentials out of public replies, helper files, logs and exported evidence.
- Use supported targeted native browser input for the current rendered controls.
- Data-use consent does not authorize form submission or a purchase.

## Security And Storage

Nuncio Secrets is user-bound and permissioned through Nuncio. Secrets records keep open metadata separate from protected values, and they can point to provider-backed records such as provider-issued payment cards instead of copying them. Identity data that comes from the KYC flow stays provider-sourced: Nuncio references the verification result rather than storing every verified field itself. Authorized requests may return values to the host; keep their use tied to the intended task and current permissions.

- Open fields can support matching and user-visible summaries.
- Protected fields are redacted from ordinary list and get responses.
- Provider-backed records can store references instead of copying provider-owned secrets.
- Revoked secrets remain unavailable to agents until re-enabled by the user.

## Extensible Schemas

The model is intentionally flexible. Today the registry includes login, identity, identity document, provider-backed payment card, and wallet schemas. New entries can add fields and semantic tags without changing how agents request data. This lets Nuncio Secrets act as a secure store for ordinary checkout data now and expand toward richer personal and organizational identity graphs over time.

```ts
type SecretsField = {
  key: string;
  label: string;
  type: 'text' | 'secret' | 'date' | 'number' | 'email' | 'url';
  required: boolean;
  secret: boolean;
  semantic_tags?: string[];
};
```

## Save During Workflows

Nuncio Secrets can be populated before a session from UI, or during a session when the user supplies missing data. Session-time writes should be explicit so the user understands what identity, entry, and fields will be reusable later.

- Reusable Secrets facts can be convenient, but sensitive values belong in secrets.
- Provider-backed card items are synced from provider state rather than manually edited.
- Artifacts should not be logged, stored in prompts, or reused after the protected step.

## Related

- Manage Secrets: https://nuncio.one/docs/guides/manage-secrets
- Nuncio Secrets fill: https://nuncio.one/docs/components/secrets-fill
- Entities: https://nuncio.one/docs/reference/entities