Document vault passkeys and credential field add/remove

docs.json

@@ -181,6 +181,7 @@
                     "pages": [
                       "vaults/overview",
                       "vaults/credentials",
+                      "vaults/passkeys",
                       "vaults/existing-credential-vault",
                       "vaults/fill",
                       "vaults/1password"

vaults/credentials.mdx

@@ -3,7 +3,7 @@ title: "Credential Items"
 description: "Collect and update encrypted credentials, then use them in a vault-attached browser session"
 ---
 
-use a `credential` item for usernames, passwords, totp generators, and other non-payment credentials. it belongs directly to a [vault](/vaults/overview); you don't need a wallet or an external credential provider. credential items power the [Fill from Vault](/auth/fill-from-vault) path under Auth.
+use a `credential` item for usernames, passwords, totp generators, [passkeys](/vaults/passkeys), and other non-payment credentials. it belongs directly to a [vault](/vaults/overview); you don't need a wallet or an external credential provider. credential items power the [Fill from Vault](/auth/fill-from-vault) path under Auth.
 
 <Warning>
   use `wallet` and `card` items for credit card numbers, security codes, and expiration dates. don't store, collect, or fill payment-card data through credential items.
@@ -96,20 +96,20 @@ set `provider: "kernel"` for **KERNEL-hosted collection**: the user enters value
 | --- | --- |
 | `name` | required stable machine key for item state, value updates, and browser fill |
 | `label` | optional human-readable form text; falls back to `name` when omitted |
-| `type` | `text`, `email`, `password`, or `totp` |
+| `type` | `text`, `email`, `password`, `totp`, or `passkey` |
 | `required` | defaults to `true`; all required fields must have values for the item to become ready |
 | `sensitive` | defaults to `true`; leave it `true` for write-only values, or set it `false` only when your backend or collection form needs to read and prefill the value |
 | `value` | optional initial value from trusted code; omit it to leave the field unset |
 
-password and totp fields must be sensitive. usernames and email addresses can also remain sensitive; `fill` works either way. fields marked `sensitive: false` return their stored values in item responses.
+password, totp, and passkey fields must be sensitive. usernames and email addresses can also remain sensitive; `fill` works either way. fields marked `sensitive: false` return their stored values in item responses.
 
 Vault `totp` fields currently generate SHA1, six-digit codes every 30 seconds. The TOTP settings you can configure on a Managed Auth credential don't change this. For vault fill, those settings apply only when you [fill from Managed Auth](/auth/fill-from-managed-auth), where `fill` generates codes with that credential's algorithm, digit count, and period. For a non-default algorithm, digit count, or period, don't use a vault `totp` field for fill until that API supports those settings.
 
 `fields` is an ordered array. define fields in the same top-to-bottom order as the website; collection forms preserve it exactly. `name` remains authoritative for `state.fields`, updates, and `fill`. `label` only changes display text and is returned as non-secret metadata. labels must be nonempty, trimmed, single-line display text of at most 128 utf-8 bytes.
 
 an item accepts 1–32 named fields. field names must start with an ascii letter, contain only ascii letters, numbers, and underscores, and be at most 64 characters. `email` values must be bare valid addresses such as `user@example.com`; use `text` for usernames that aren't valid email addresses. initial values must be nonempty strings and fit within 16 kib of utf-8 data each; `null` and empty strings aren't accepted on creation.
 
-field names, labels, types, required flags, and sensitivity are immutable. repeating the same creation request retrieves the current item without overwriting later edits. use an update for value changes; use a new item key for a different field definition.
+repeating the same creation request retrieves the current item without overwriting later edits. use an update for value changes, and [add or remove fields](#add-or-remove-fields) to change the field list.
 
 ### Copy values from an existing vault
 
@@ -256,7 +256,7 @@ poll the item with a bounded wait until its status is `ready`. readiness means r
 
 invoke the advertised `collect` operation to reopen collection for a ready item. this doesn't clear its values. record its `version` before opening the form, then retrieve without `wait` to observe edits: `wait` waits for readiness, not changes to an already-ready item. a version change can also come from an api update, so it doesn't identify a particular form submission.
 
-the form includes text, email, and password fields in declaration order, not totp. it renders `label` when present and falls back to `name`. non-sensitive values can be prefilled; stored secrets aren't revealed. required visible inputs must be populated on submission.
+the form includes text, email, and password fields in declaration order, not totp or passkey fields. it renders `label` when present and falls back to `name`. non-sensitive values can be prefilled; stored secrets aren't revealed. required visible inputs must be populated on submission.
 
 ## Use a credential with WebMCP
 
@@ -319,16 +319,85 @@ this replaces the password without returning either value. public updates can in
 
 a successful update increments the version and invalidates outstanding hosted collection sessions. on a `409` conflict, reload and reconcile with the user rather than automatically resubmitting stale edits.
 
+## Add or remove fields
+
+an existing field's name, label, type, required flag, and sensitivity can't be edited. to change the field list, send `add_fields` or `remove_fields` in an update with the latest `version`:
+
+- `add_fields` appends field definitions, with the same defaults as creation. it takes definitions only; set a new field's value in `fields` in the same update.
+- `remove_fields` deletes the named fields and their values. an unknown name returns `400`, and at least one field must remain.
+- removals apply before additions, so removing a field and adding one with the same name in one update replaces its definition and deletes the old value.
+- an item still holds at most 32 fields, and names must be unique. a required totp or passkey field needs its value in the same update, because a collection form can't supply it.
+
+<CodeGroup>
+
+```typescript TypeScript
+const current = await kernel.vaults.items.retrieve(item.key, { id_or_name: vault.id });
+if (current.type !== "credential" || current.id !== item.id) {
+  throw new Error("credential item was replaced");
+}
+const updated = await kernel.vaults.items.update(item.key, {
+  id_or_name: vault.id,
+  type: "credential",
+  version: current.version,
+  expected_item_id: item.id,
+  spec: {
+    add_fields: [
+      {
+        name: "account_number",
+        label: "Account number",
+        type: "text",
+        required: true,
+        sensitive: false,
+      },
+    ],
+    fields: { account_number: { value: "4417-2231" } },
+  },
+});
+```
+
+```python Python
+current = kernel.vaults.items.retrieve(item.key, id_or_name=vault.id)
+if current.type != "credential" or current.id != item.id:
+    raise RuntimeError("credential item was replaced")
+updated = kernel.vaults.items.update(
+    item.key,
+    id_or_name=vault.id,
+    type="credential",
+    version=current.version,
+    expected_item_id=item.id,
+    spec={
+        "add_fields": [
+            {
+                "name": "account_number",
+                "label": "Account number",
+                "type": "text",
+                "required": True,
+                "sensitive": False,
+            }
+        ],
+        "fields": {"account_number": {"value": "4417-2231"}},
+    },
+)
+```
+
+</CodeGroup>
+
+adding a required field without a value returns the item to `pending_collection` when the field is form-supported, so the user can supply it.
+
 ## Use totp
 
 supply a base32 generator seed through trusted backend code, using `value` at creation or an authenticated update. a required totp field needs its seed at creation; the collection form can't supply it. an optional totp field can receive its seed later.
 
 KERNEL generates a fresh six-digit code immediately before filling, using hmac-sha1 and a 30-second period. neither the seed nor a generated code is returned by item reads. the seed never enters the browser; the generated code does. custom algorithms, periods, and digit counts aren't supported.
 
+## Use passkeys
+
+a `passkey` field holds a passkey that a vault-attached browser can register on a website or sign in with. KERNEL signs on its servers, so the private key never enters the browser. passkeys aren't filled; use the `register_passkey`, `arm_passkey`, and `disarm_passkey` operations instead. see [passkeys](/vaults/passkeys).
+
 ## Build your own collection surface
 
 your authenticated backend can retrieve safe item state and submit value updates using the ordinary item api. authenticate your own users, authorize their access to the vault and immutable item id, and apply the version precondition. keep broad KERNEL api credentials out of the frontend.
 
-render every form-supported field in declaration order, display `label` with a `name` fallback, keep controls and updates keyed by `name`, omit totp, prefill only non-sensitive values, and don't log submitted values. for an unchanged form, use your own completion callback rather than an empty update. KERNEL doesn't store or authenticate your custom collection url.
+render every form-supported field in declaration order, display `label` with a `name` fallback, keep controls and updates keyed by `name`, omit totp and passkey fields, prefill only non-sensitive values, and don't log submitted values. for an unchanged form, use your own completion callback rather than an empty update. KERNEL doesn't store or authenticate your custom collection url.
 
 continue with [fill browser fields](/vaults/fill) or the [browser agent cookbook](/browsers/use-vault-credentials-in-browser-agent).

vaults/overview.mdx

@@ -13,6 +13,8 @@ payments. sensitive values aren't returned by the vault api.
 
 use KERNEL's [`fill` api](/vaults/fill) to safely inject stored values from supported items into browser fields without passing the values through your application's injection code or model context. your controller supplies references and selectors; KERNEL writes the values and returns outcomes, not the values. invoke `fill` when the item advertises it in `available_operations`.
 
+credential items can also hold [passkeys](/vaults/passkeys). an attached browser registers and signs in with them while KERNEL signs on its servers, so the private key never enters the browser.
+
 for authentication workflows where your application or agent controls
 navigation and submission, start with [Fill from Vault](/auth/fill-from-vault).