@ai-ecoverse/slicc-vault 0.0.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,191 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright
+      owner or by an individual or Legal Entity authorized to submit on
+      behalf of the copyright owner. For the purposes of this definition,
+      "submitted" means any form of electronic, verbal, or written
+      communication sent to the Licensor or its representatives, including
+      but not limited to communication on electronic mailing lists, source
+      code control systems, and issue tracking systems that are managed by,
+      or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or otherwise designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 ai-ecoverse
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,9 +1,224 @@
-# @ai-ecoverse/slicc-vault
+# slicc-vault
 
-🐣 This package name has been claimed with [fledgling](https://github.com/dmno-dev/fledgling), and a real release will land here soon.
+The separate-origin vault at `vault.sliccy.ai`. It holds the sealed secrets, OAuth tokens, and model and MCP credentials of SLICC seven, so that no value ever reaches the model provider. The design is `secrets-tokens-design.md` (revision 4) in slicc-agent-plan. This README is the spec of what is built.
 
-This is a placeholder — there is nothing to install yet.
+- **Built:** the key store, records, origin namespacing, auto-unlock with an optional passkey or passphrase lock, the embedding API with its `page` and `agent` roles, the page's `put`, `seal`, `remove`, `restore`, `cancel` and `lock`, the scrub state, the lock button and its popup, and the vault side of the `/dev/sealed` ops `seal`, `placeholder`, `list`, `test`, `request`, `status`, `cancel` and `materialize`.
+- **Not built yet:** policy (every record is `inert`, and `test` always refuses), `forward` and the scrubber, exec, `import` and `export`, and the agent's ops. They answer as described below.
 
----
+## Documents and hosting
 
-Want to claim a name of your own? Run `npx fledgling add <name> --new --yes` — it reserves the name on npm and can set up token-less (OIDC trusted) publishing for when you are ready.
+The build (`npm run build`) writes a flat static tree to `dist/site/`:
+
+| file | what it is |
+|---|---|
+| `index.html`, `frame.js` | the core frame. bios embeds it as a hidden iframe and talks to it over a `MessagePort` |
+| `button.html`, `button.js` | the lock button. A popup can only open from a click inside a vault document, so bios and spectrum embed this wherever the lock is offered |
+| `popup.html`, `popup.js` | the vault window, a top-level `vault.sliccy.ai` document, used only for the passkey or passphrase lock |
+| `vault.css`, `fonts/` | Spectrum 2 from the CSS-only `@spectrum-css` packages, and Adobe Clean |
+| `config.json` | `{ version, embedders }`. `embedders` is the fallback list, `["https://seven.sliccy.ai"]` |
+
+There is no third-party JavaScript: the bundles hold only this repo's code. The sliccy-ai Worker serves the tree from the network on every load, never from OPFS, with:
+- `Content-Security-Policy` with `script-src 'self'`, no inline scripts or styles, and `frame-ancestors` listing the seven origins;
+- `Cross-Origin-Embedder-Policy: require-corp`, `Cross-Origin-Resource-Policy: same-site`, `Cross-Origin-Opener-Policy: same-origin`;
+- `Origin-Agent-Cluster: ?1`, `nosniff`, `Referrer-Policy: no-referrer`, `no-cache` with an ETag.
+
+`GET /embedders.json` is answered by the Worker, not by this tree. It returns `{ "embedders": [...] }`, the same sources as `frame-ancestors`. The vault reads it at start, falls back to `config.json` when it's missing or malformed, and accepts only those origins. An embedder source is `http(s)://host`, optionally with `:port` or `:*`, matched exactly.
+
+`main` is served at `vault.sliccy.ai`, and every other branch at `vault-<label>.sliccy.ai`. seven embeds only `vault.sliccy.ai`.
+
+## Storage and keys
+
+Everything lives in the vault origin's IndexedDB, database `slicc-vault`, version 1:
+
+| store | key | holds |
+|---|---|---|
+| `meta` | `"keys"` | the key state below |
+| `records` | `[ns, kind, name]`, unique index on `placeholder` | records |
+| `requests` | `id` | requests that wait for a human |
+| `audit` | `seq` (auto-increment) | the audit log, per namespace |
+| `intents` | `nonce` | hand-offs from a button to the popup, valid for 10 minutes |
+
+**The data key** is one AES-GCM 256 key. Each record's value is encrypted under it with a fresh 12-byte IV and the additional data `slicc-vault/1 NUL ns NUL kind NUL name`, so a ciphertext can't be moved to another record.
+
+**The key state** is one of:
+- `auto` (the default): the data key is stored as a **non-extractable** `CryptoKey`. Every vault document loads it at start, so there's never a prompt.
+- `passkey`: the data key is stored only wrapped (AES-GCM) under a key-encryption key from **WebAuthn PRF**. The passkey's RP id is the vault's host, the PRF input is a random 32-byte salt, and the KEK is HKDF-SHA-256 over the PRF output with that salt and the info `slicc-vault/kek/1`.
+- `passphrase`: the same, with the KEK from PBKDF2-SHA-256, 600,000 iterations, over a random 16-byte salt.
+
+**Locking:**
+- While protected, a document starts locked and asks the other open vault documents (over the origin's `BroadcastChannel` `slicc-vault`) for the unwrapped key. Unlocking in the popup unwraps the key as non-extractable and hands it to every open vault document the same way.
+- `Lock now` drops the key from every document. Closing every vault document has the same effect.
+- **Protecting** makes a new data key, re-encrypts every record under it, and stores it wrapped, in one transaction. If a record changed meanwhile, protecting fails with `EAGAIN` and changes nothing. **Removing protection** stores the current key as non-extractable again.
+- Every data key has an id, stored with it. A seal checks that id in the same transaction that writes the record, so a value encrypted under a key that was replaced meanwhile is refused with `EAGAIN` rather than stored unreadable.
+- While locked, `seal` answers `EACCES` with a message starting `vault is locked`. Ops that need no value (`placeholder`, `list`, `status`, ...) still work.
+
+## Records
+
+```
+{ ns, kind: "secret" | "grant" | "model" | "mcp", name, placeholder, sealed: { iv, data },
+  source, createdAt, updatedAt, usedAt?, expiresAt?, refresh?, removedAt? }
+```
+
+- **`ns`** is the embedder's origin, below.
+- **`name`** matches `^[A-Za-z_][A-Za-z0-9_]*$`, at most 128 characters.
+- **A value** is at least 8 bytes of UTF-8, without CR, LF or NUL, and contains no placeholder. Anything shorter is refused with `EINVAL` "values shorter than 8 bytes can't be protected from the model", because the scrubber couldn't tell it apart from ordinary output.
+- **`placeholder`** is `fnox_proxy_` plus 24 lower-case hex characters from `crypto.getRandomValues`, unique across the whole vault and stable for the record's life. All placeholders have the same length, so none contains another.
+- **`source`** is `settings` (entered in spectrum), `process`, `jerk:<provider>@<device>`, `oauth:<provider>` or `import:<kind>`.
+- **`state`** is computed, never stored: `removed` when `removedAt` is set, `active` when the accepted policy has a rule naming the record, otherwise `inert`. With no policy yet, every record is `inert`.
+- **Removing** sets `removedAt`. A removed record keeps its placeholder, can be restored with `restore`, and is deleted for good 30 days later. Sealing a removed name brings it back with a new value and the same placeholder.
+- **Times** are epoch milliseconds everywhere.
+
+## Backup reminder
+
+`status.exportedAt` is the time of the namespace's last successful `export`, or `null` if it never exported. `status.backupReminder` is `due` once the namespace holds a `secret` record and has never exported, `dismissed` after `dismissBackupReminder`, and `null` otherwise (no secrets yet, or exported). `export` arrives with VAULT-1e; until then `exportedAt` stays `null`.
+
+## Scrub state
+
+`scrub { needed, version, ready }` tells bios and the agent whether output must pass the vault's scrubber before it reaches the model. It's per namespace:
+- `needed` is false only when the namespace holds no plaintext at all: no record of any kind or state, removed ones included until they're purged.
+- `version` counts every change to the namespace's set of values: each seal, rotation, removal, restore and purge.
+- `ready` is false only when values exist but this vault frame never held the data key since it loaded, which is a reload with the lock on, before unlock. Locking again later doesn't clear it, because the compiled scrubber stays in memory for the frame's life.
+
+It's in `status`, in `placeholders` replies and in every `placeholders` push. After `put` and `seal`, the push with the new pair goes out **before** the reply.
+
+## Namespaces
+
+Every record, request, audit entry and scrub version belongs to the origin that embeds the vault. The core frame takes it from the `event.origin` of the hello, and the button from `location.ancestorOrigins[0]` (or the first message's origin when the browser hides ancestors). A branch preview of bios therefore gets its own empty vault and never sees seven's records. The popup shows the namespace of the button that opened it. The lock itself is one per vault.
+
+## The embedding API (core frame)
+
+The embedder (bios) loads `https://vault.sliccy.ai/` in an iframe and, after `load`, posts a hello carrying a port:
+
+```js
+iframe.contentWindow.postMessage({ type: 'slicc-vault', v: 1, op: 'hello', role: 'page' }, 'https://vault.sliccy.ai', [port2]);
+```
+
+- The frame answers only when the message comes from its own parent window, from an allowed origin, matching `location.ancestorOrigins[0]` when the browser exposes it. Anything else gets no answer at all.
+- On `port2` it answers `{ v: 1, op: 'welcome', role, status }`, or `{ v: 1, op: 'refused', error }` for another protocol version or an unknown role.
+- Everything after that goes over the port. The namespace and the role are fixed by the hello. Requests are `{ v: 1, id, op, ...fields }`; replies are `{ v: 1, id, op, ...fields }` or `{ v: 1, id, error: { code, message } }`. Each port is answered in order (FIFO).
+- **Roles:** `page` (the default) is bios and spectrum. bios may hand spectrum a page port of its own, or relay; the messages are the same. `agent` is the port bios hands the agent worker: it may use only `redact`, `redactStream`, `push`, `end`, `drop`, `model`, `mcp`, `endpoints`, `records`, `grant` and `refresh` (all `ENOTSUP` in this version), and anything else is `EACCES`. The agent port gets no events.
+
+| op (page role) | fields | reply |
+|---|---|---|
+| `sealed` | `req` (the `/dev/sealed` request object, or its JSON text), `stamp` (`{ pid, ppid, uid, gid, tag }` from the kernel) | `{ reply }`, the §3.7 reply, below |
+| `status` | — | `{ status: { version, protocol, origin, locked, lock, scrub, waiting, exportedAt, backupReminder } }` |
+| `placeholders` | — | `{ placeholders, scrub }`: every placeholder of a record that isn't removed, active and inert, sorted |
+| `list` | — | `{ list: { secrets, refused, audit, auditMore, exits } }` for Settings › Secrets |
+| `audit` | `before?` (a `seq`), `limit?` (1–1000, default 100) | `{ audit, more, next? }`, newest first; pass `next` as `before` for the next page |
+| `put` | `name`, `value`, `request?` | `{ name, placeholder, state }`. A value typed in Settings, with source `settings`; on an existing name it's a rotation that keeps the placeholder. With `request`, it answers that value request, which must still be pending and ask for `name` (else `EINVAL`, and nothing is stored), so its `/dev/sealed` `status` becomes `done` |
+| `seal` | `name`, `value`, `source`, `kind?` (default `secret`), `expiresAt?`, `refresh?` | `{ name, placeholder, state }`. bios's, for J1 leases and sign-in tokens |
+| `remove`, `restore` | `name`, `kind?` (default `secret`) | `{ name, placeholder, state }`. A record removed more than 30 days ago can't be restored (`ENOENT`) |
+| `cancel` | `request` | `{ state }`; the request's `/dev/sealed` `status` becomes `cancelled` |
+| `lock` | — | `{}`; drops the key everywhere when the lock is on |
+| `dismissBackupReminder` | — | `{ backupReminder }`; the reminder becomes `dismissed` for this namespace |
+| `import`, `export`, anything else | | `ENOTSUP` |
+
+`put` and `seal` need the vault unlocked. They answer `EACCES` with a message starting `vault is locked` otherwise.
+
+**Events** on page ports:
+- `{ v: 1, event: 'status', status }` whenever requests, records, the scrub state or the lock change;
+- `{ v: 1, event: 'placeholders', placeholders, scrub }` whenever either changes;
+- `{ v: 1, event: 'changed', parts }`, with `parts` among `secrets`, `audit` and `exits`, so a view knows what to reload.
+
+**Errors** use errno names: `EINVAL`, `ENOENT`, `EACCES`, `EEXIST`, `EAGAIN`, `ETIMEDOUT`, `ENOTCONN`, and `ENOTSUP` for ops this version doesn't have.
+
+## `/dev/sealed`, the vault side
+
+bios relays each kernel request unchanged as the `sealed` op, with the kernel's stamp. The vault validates and answers `{ v: 1, ...fields }` or `{ v: 1, error: { code, message } }`. A request over 64 KiB, one that isn't a single JSON object, one with `v` other than 1, and an unknown `op` are `EINVAL`, as is a missing or malformed stamp.
+
+| op | fields | reply |
+|---|---|---|
+| `seal` | `name`, `value` | `{ placeholder, state }`. A new name creates a `process` record. An existing one is rotated and keeps its placeholder, but only when its value came from a process; a value from Settings, jerk, OAuth or an import is replaced only by uid 0, and anyone else gets `EEXIST` |
+| `placeholder` | `name` | `{ placeholder, state }`, including `removed`; `ENOENT` when there's no record |
+| `list` | — | `{ secrets: [{ name, placeholder, state, exec, rules, expiresAt? }] }`, records of kind `secret` that aren't removed |
+| `test` | `name`, `url`, `method?`, `header?` | `{ verdict, reason }`. Without policy it's always `refuse`; `ENOENT` for an unknown name |
+| `request` | `kind: "value"`, `name`, `prompt?` (≤ 200 characters) | `{ state: "pending", id }` |
+| `request` | `kind: "oauth"`, `provider`, `oauth` (an object) | the same |
+| `request` | `kind: "jerk-seal"`, `provider` | the same |
+| `status` | `id` | `{ state }`, with `placeholder` and `record` once a value request is `done` |
+| `cancel` | `id` | `{ state }`: `cancelled`, or the state it had already reached |
+| `materialize` | `names`, `path`, `argv`, `cwd` | checked, then always `EACCES` in this version |
+
+- **Requests** expire 300 s after they're made. Each uid has at most one pending request per namespace; a second one is `EAGAIN`. `status` and `cancel` see only the caller's own requests (uid 0 sees all), and others get `ENOENT`.
+- A value request shows up in `status.waiting` and is answered by the page's `put` with its `request` id, or ended by `cancel`. `oauth` and `jerk-seal` requests can only be cancelled in this version.
+
+## The button (`button.html`)
+
+A popup needs a click inside a vault document, so the way into the lock popup is this button. The embedder loads `https://vault.sliccy.ai/button.html` in an iframe and, after `load`, posts:
+
+```js
+frame.contentWindow.postMessage({ type: 'slicc-vault', v: 1, op: 'button', button: config }, 'https://vault.sliccy.ai');
+```
+
+**`config`** (`ButtonConfig` in the types):
+
+| field | values | default |
+|---|---|---|
+| `intent` | `{ kind: 'unlock' }`, `{ kind: 'protect' }`, or `"auto"` | `"auto"` |
+| `label` | text instead of the default label | per intent |
+| `size` | `s`, `m`, `l` (24, 32 and 40 px high) | `m` |
+| `variant` | `accent`, `primary`, `secondary` | `secondary` |
+| `treatment` | `fill`, `outline` | `fill` |
+| `quiet`, `disabled` | booleans | `false` |
+| `scale` | `medium`, `large` | `medium` |
+| `theme` | `light`, `dark` | the system's colour scheme |
+| `dir`, `lang` | `ltr`/`rtl`, a language tag | `ltr`, `en` |
+
+- **Sending `op: 'button'` again updates the same button in place.** The frame doesn't reload, and only the fields given apply on top of the defaults.
+- `{ op: 'focus' }` moves keyboard focus into the button.
+- `unlock` is labelled `Unlock vault`, and `protect` (set up or remove the lock) `Vault lock`. `"auto"` shows `Unlock vault` while the vault is locked, and otherwise no button at all (size 0×0).
+- The background is transparent, and the button sits inside a 2 px inset so its focus ring isn't clipped. Pass `theme` to match the page: Chrome paints an iframe opaque when its colour scheme differs from the embedder's, so the frame takes the scheme of `theme`, and the browser default without it.
+
+**Events** to the embedder, all `{ type: 'slicc-vault', v: 1, event, ... }`:
+- `ready`, once;
+- `size { width, height, inset }`, on every change, so the embedder sizes the iframe to it;
+- `label { label }`, on every change, for the iframe's `title`;
+- `focus { direction: 'next' | 'previous' }`, when Tab or Shift+Tab leaves the button;
+- `popup { intent, state }`, with `state` `opened`, `done`, `cancelled`, `closed` (the window closed without an answer) or `blocked` (the browser blocked the window).
+
+## The popup (`popup.html`)
+
+The button writes its intent to `intents` under a random 128-bit nonce and opens `/popup.html#<nonce>` in a 460×680 window. The popup claims that intent and shows the namespace it was opened for. Without a valid nonce it shows only "Nothing to do here". It asks the browser to make the vault's storage persistent.
+
+| intent | what the popup does |
+|---|---|
+| `unlock` | unlocks with the passkey or passphrase, then closes |
+| `protect` | while unlocked: **Protect with a passkey** (WebAuthn PRF), **Protect with a passphrase**, or, once protected, **Lock now** and **Remove protection** |
+
+- A locked vault asks to be unlocked first, whatever the intent.
+- A wrong passphrase or passkey says so ("That passphrase doesn't unlock this vault."), and a wrong passphrase is cleared from the field.
+- A new passphrase needs at least 12 characters, typed twice. The popup says what's missing as you type, and **Protect** stays disabled until both fields pass.
+- **Remove protection** asks first: "Remove protection? The vault will unlock by itself on this device." 
+
+## Types for bios and spectrum
+
+The npm package `@ai-ecoverse/slicc-vault` holds only TypeScript types, built from `src/contract.ts`: the port API (`Hello`, `Greeting`, `Request`, `Reply`, `VaultEvent`, `Role`), the button (`ButtonConfig`, `ButtonMessage`, `ButtonEvent`), the popup (`PopupIntent`, `PopupState`), the page's results (`SealResult`, `ImportResult`), and the data Settings shows (`SecretView`, `VaultStatus`, `ScrubState`, `PendingRequest`, `AuditEntry`, `ExitPolicyView`, `VaultList`). `Availability` (`connecting`, `waiting`, `locked`, `ready`) is for bios to tell spectrum "waiting for the vault" and "unlock the vault to continue". They mean:
+
+- **`EpochMs`**: milliseconds since the epoch. **`DeviceId`**: the same id bios uses for linked devices and trays, in `sourceDevice`, `device:<id>` exits and `ExitPolicyView.devices[].device`.
+- **`Rule`**: `domain` is an exact lower-case host; `header` a lower-case header name; **empty `methods` or `paths` mean any**.
+- **`exec`**: `false` means the value is never revealed to a program; `any`, `argv` (with `execArgv`, the allowed argv prefixes) and `shell` are the `[exec]` modes under which `fnox exec` may hand it to a program.
+- **`exits`** is present only when `/etc/slicc/secrets-policy.toml` restricts that secret; absent means every exit (`page`, `proxy`, `tailscale`, `device:<id>`).
+- **`kind`**: `secret` (a credential programs use through rules), **`grant`** (a sign-in's refresh token, never injected; show it as "Sign-in"), `model` (a model provider key), `mcp` (an MCP server credential). `provider` and `account` name the service and the signed-in account where one is known.
+- **`AuditEntry`**: `forward` is a use of a value in a request, with the exit that carried it; **`materialize` is shown as "Revealed to a program"**; `seal`, `remove`, `restore` and `policy` (with its `changes`) record changes. Every entry has a `seq` for paging.
+- **`VaultList.refused`** lists rules the vault dropped because they name a model or MCP endpoint.
+- **`PendingRequest.prompt`** is untrusted, agent-written text of at most 200 characters.
+- **`ExitPolicyView`** is read-only: the secrets `/etc/slicc/secrets-policy.toml` restricts to certain exits.
+
+## Develop
+
+```sh
+npm install
+npm run build      # dist/site and dist/types
+npm run lint
+npm test           # Chromium integration tests
+npm start          # vault on http://vault.sliccy.localhost:8790, a test embedder on seven.sliccy.localhost
+```
+
+- **Integration tests** (`test/integration/`) run the built vault on a local server that sends the production headers, at `http://vault.sliccy.localhost:<port>`, with test embedders on `seven.`, `preview.` and `evil.sliccy.localhost`. Chromium treats `*.sliccy.localhost` as one site and as a secure context, so the embedded frame gets the same first-party storage it gets under `sliccy.ai`. They use slicc-shared-web's CDP harness, plus a second CDP session for popups and the virtual WebAuthn authenticator.
+- **Unit tests** stay in the gitignored `test/unit/` (`npm run test:unit`), and the pre-commit hook requires them to cover every changed line of `src/`.
+- The Biome, TypeScript, lefthook and Renovate configuration comes from [slicc-shared-web](https://github.com/ai-ecoverse/slicc-shared-web). There are no comments in any file.
+
+## Release and deploy
+
+- **Releases:** semantic-release on `main` tags a version from the conventional commits. It publishes the types package when the repository variable `NPM_PUBLISH` is `true`.
+- **Deploy:** after semantic-release, the release job builds with the new version and publishes `dist/site/` to `vault.sliccy.ai` from the `production` environment. Every push to another branch publishes it to `vault-<label>.sliccy.ai`. Both use GitHub's OIDC token against sliccy-ai's `/api/publish` route (`edge/publish.mjs`), with no stored secret.

package/dist/types/contract.d.ts

@@ -0,0 +1,377 @@
+export type Protocol = 1;
+export type MessageType = 'slicc-vault';
+export type EpochMs = number;
+export type DeviceId = string;
+export type RecordKind = 'secret' | 'grant' | 'model' | 'mcp';
+export type RecordState = 'active' | 'inert' | 'removed';
+export type RecordSource = 'settings' | 'process' | `jerk:${string}@${DeviceId}` | `oauth:${string}` | `import:${string}`;
+export type LockMode = 'auto' | 'passkey' | 'passphrase';
+export type RequestKind = 'value' | 'oauth' | 'jerk-seal';
+export type RequestState = 'pending' | 'done' | 'cancelled' | 'expired';
+export type ErrorCode = 'EINVAL' | 'ENOENT' | 'EACCES' | 'EEXIST' | 'EAGAIN' | 'ETIMEDOUT' | 'ENOTCONN' | 'ENOTSUP';
+export type ExitName = 'page' | 'proxy' | 'tailscale' | `device:${DeviceId}`;
+export type ExecMode = false | 'any' | 'argv' | 'shell';
+export type Role = 'page' | 'agent';
+export interface Stamp {
+    pid: number;
+    ppid: number;
+    uid: number;
+    gid: number;
+    tag: string | null;
+}
+export interface VaultError {
+    code: ErrorCode;
+    message: string;
+}
+export interface Rule {
+    domain: string;
+    header: string;
+    methods: string[];
+    paths: string[];
+}
+export interface RefusedRule {
+    secret: string;
+    rule: Rule;
+    reason: string;
+}
+export interface SecretView {
+    name: string;
+    kind: RecordKind;
+    placeholder: string;
+    state: RecordState;
+    source: RecordSource;
+    sourceDevice: DeviceId | null;
+    provider?: string;
+    account?: string;
+    domains: string[];
+    rules: Rule[];
+    exits?: ExitName[];
+    exec: ExecMode;
+    execArgv?: string[][];
+    createdAt: EpochMs;
+    usedAt?: EpochMs;
+    expiresAt?: EpochMs;
+    removedAt?: EpochMs;
+}
+export interface PendingRequest {
+    id: string;
+    kind: RequestKind;
+    name?: string;
+    provider?: string;
+    prompt?: string;
+    uid: number;
+    tag: string | null;
+    createdAt: EpochMs;
+    expiresAt: EpochMs;
+}
+export interface ScrubState {
+    needed: boolean;
+    version: number;
+    ready: boolean;
+}
+export interface VaultStatus {
+    version: string;
+    protocol: Protocol;
+    origin: string;
+    locked: boolean;
+    lock: LockMode;
+    scrub: ScrubState;
+    waiting: PendingRequest[];
+    exportedAt: EpochMs | null;
+    backupReminder: BackupReminder;
+}
+export type BackupReminder = 'due' | 'dismissed' | null;
+export type Availability = 'connecting' | 'waiting' | 'locked' | 'ready';
+export type PolicyFile = '/etc/fnox/config.toml' | '/etc/slicc/secrets-policy.toml';
+export type PolicyChange = {
+    kind: 'rule';
+    secret: string;
+    rule: Rule;
+    change: 'added' | 'removed';
+} | {
+    kind: 'exec';
+    secret: string;
+    from: ExecMode;
+    to: ExecMode;
+} | {
+    kind: 'exits';
+    secret: string;
+    from: ExitName[] | null;
+    to: ExitName[] | null;
+} | {
+    kind: 'limits';
+    field: string;
+    from: number;
+    to: number;
+};
+interface AuditBase {
+    seq: number;
+    id: string;
+    at: EpochMs;
+    name: string;
+    uid: number | null;
+    tag: string | null;
+}
+export interface ForwardEntry extends AuditBase {
+    type: 'forward';
+    domain: string;
+    method: string;
+    path: string;
+    rule: Rule;
+    exit: ExitName;
+}
+export interface RevealEntry extends AuditBase {
+    type: 'materialize';
+    exec: ExecMode;
+    path: string;
+    argv: string;
+    argvSha256: string;
+    cwd: string;
+    pid: number;
+    ppid: number;
+    ticket: string;
+    consumed: boolean;
+}
+export interface SealEntry extends AuditBase {
+    type: 'seal';
+    source: RecordSource;
+    rotated: boolean;
+}
+export interface RemoveEntry extends AuditBase {
+    type: 'remove' | 'restore';
+}
+export interface PolicyEntry {
+    type: 'policy';
+    seq: number;
+    id: string;
+    at: EpochMs;
+    file: PolicyFile;
+    sha256: string;
+    accepted: boolean;
+    changes: PolicyChange[];
+    warning?: string;
+}
+export type AuditEntry = ForwardEntry | RevealEntry | SealEntry | RemoveEntry | PolicyEntry;
+export interface AuditPage {
+    audit: AuditEntry[];
+    more: boolean;
+    next?: number;
+}
+export interface ExitPolicyView {
+    file: '/etc/slicc/secrets-policy.toml';
+    sha256: string | null;
+    restricted: {
+        name: string;
+        exits: ExitName[];
+    }[];
+}
+export interface VaultList {
+    secrets: SecretView[];
+    refused: RefusedRule[];
+    audit: AuditEntry[];
+    auditMore: boolean;
+    exits: ExitPolicyView;
+}
+export interface SealResult {
+    name: string;
+    placeholder: string;
+    state: RecordState;
+}
+export type ImportKind = 'bundle' | 'keepass' | 'six';
+export interface ImportCandidate {
+    name: string;
+    exists: boolean;
+    suggestedRules?: string;
+}
+export type ImportResult = {
+    stage: 'pick';
+    candidates: ImportCandidate[];
+} | {
+    stage: 'done';
+    imported: SealResult[];
+    skipped: string[];
+};
+export type PopupIntent = {
+    kind: 'unlock';
+} | {
+    kind: 'protect';
+};
+export type PopupState = 'opened' | 'done' | 'cancelled' | 'closed' | 'blocked';
+export interface ButtonConfig {
+    intent: PopupIntent | 'auto';
+    label?: string;
+    size?: 's' | 'm' | 'l';
+    variant?: 'accent' | 'primary' | 'secondary';
+    treatment?: 'fill' | 'outline';
+    quiet?: boolean;
+    scale?: 'medium' | 'large';
+    theme?: 'light' | 'dark';
+    dir?: 'ltr' | 'rtl';
+    lang?: string;
+    disabled?: boolean;
+}
+export type SealedRequest = {
+    v: Protocol;
+    op: string;
+} & Record<string, unknown>;
+export type SealedReply = {
+    v: Protocol;
+} & Record<string, unknown>;
+export type Op = {
+    op: 'sealed';
+    req: SealedRequest;
+    stamp: Stamp;
+} | {
+    op: 'status';
+} | {
+    op: 'placeholders';
+} | {
+    op: 'list';
+} | {
+    op: 'audit';
+    before?: number;
+    limit?: number;
+} | {
+    op: 'put';
+    name: string;
+    value: string;
+    request?: string;
+} | {
+    op: 'cancel';
+    request: string;
+} | {
+    op: 'remove';
+    name: string;
+    kind?: RecordKind;
+} | {
+    op: 'restore';
+    name: string;
+    kind?: RecordKind;
+} | {
+    op: 'seal';
+    name: string;
+    value: string;
+    source: RecordSource;
+    kind?: RecordKind;
+    expiresAt?: EpochMs;
+    refresh?: string;
+} | {
+    op: 'import';
+    kind: ImportKind;
+    bytes: Uint8Array;
+    password?: string;
+    pick?: string[];
+} | {
+    op: 'export';
+    passphrase: string;
+} | {
+    op: 'lock';
+} | {
+    op: 'dismissBackupReminder';
+};
+export type OpReply = {
+    op: 'sealed';
+    reply: SealedReply;
+} | {
+    op: 'status';
+    status: VaultStatus;
+} | {
+    op: 'placeholders';
+    placeholders: string[];
+    scrub: ScrubState;
+} | {
+    op: 'list';
+    list: VaultList;
+} | ({
+    op: 'audit';
+} & AuditPage) | ({
+    op: 'put' | 'seal' | 'remove' | 'restore';
+} & SealResult) | {
+    op: 'cancel';
+    state: RequestState;
+} | ({
+    op: 'import';
+} & ImportResult) | {
+    op: 'export';
+    bundle: Uint8Array;
+} | {
+    op: 'lock';
+} | {
+    op: 'dismissBackupReminder';
+    backupReminder: BackupReminder;
+};
+export type Request = Op & {
+    v: Protocol;
+    id: number;
+};
+export type Reply = (OpReply & {
+    v: Protocol;
+    id: number;
+}) | {
+    v: Protocol;
+    id: number;
+    error: VaultError;
+};
+export type ChangedPart = 'secrets' | 'audit' | 'exits';
+export type VaultEvent = {
+    v: Protocol;
+    event: 'status';
+    status: VaultStatus;
+} | {
+    v: Protocol;
+    event: 'placeholders';
+    placeholders: string[];
+    scrub: ScrubState;
+} | {
+    v: Protocol;
+    event: 'changed';
+    parts: ChangedPart[];
+};
+export interface Hello {
+    type: MessageType;
+    v: Protocol;
+    op: 'hello';
+    role?: Role;
+}
+export type Greeting = {
+    v: Protocol;
+    op: 'welcome';
+    role: Role;
+    status: VaultStatus;
+} | {
+    v: Protocol;
+    op: 'refused';
+    error: VaultError;
+};
+export type ButtonMessage = {
+    type: MessageType;
+    v: Protocol;
+    op: 'button';
+    button: ButtonConfig;
+} | {
+    type: MessageType;
+    v: Protocol;
+    op: 'focus';
+};
+export type ButtonEvent = {
+    type: MessageType;
+    v: Protocol;
+} & ({
+    event: 'ready';
+} | {
+    event: 'size';
+    width: number;
+    height: number;
+    inset: number;
+} | {
+    event: 'label';
+    label: string;
+} | {
+    event: 'focus';
+    direction: 'next' | 'previous';
+} | {
+    event: 'popup';
+    intent: PopupIntent;
+    state: PopupState;
+});
+export {};

package/package.json

@@ -1,4 +1,64 @@
 {
   "name": "@ai-ecoverse/slicc-vault",
-  "version": "0.0.0"
+  "version": "1.1.0",
+  "description": "The separate-origin vault at vault.sliccy.ai: sealed secrets, OAuth tokens, and model and MCP credentials for SLICC seven, used only by its injector",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ai-ecoverse/slicc-vault.git"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "fledgling": {
+    "provider": "github",
+    "workflow": "release.yml",
+    "repo": "ai-ecoverse/slicc-vault",
+    "publish": true
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/contract.d.ts"
+    }
+  },
+  "types": "./dist/types/contract.d.ts",
+  "files": [
+    "dist/types"
+  ],
+  "scripts": {
+    "prepare": "[ ! -e .git ] || lefthook install",
+    "build": "node build.mjs && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "start": "npm run build && node test/integration/serve.mjs",
+    "pretest": "npm run build && playwright-core install --no-shell chromium",
+    "test": "node --test --test-timeout=300000 --test-global-setup=node_modules/@ai-ecoverse/slicc-shared-web/harness/global.mjs 'test/integration/*.test.mjs'",
+    "test:unit": "NODE_NO_WARNINGS=1 mcr -c node_modules/@ai-ecoverse/slicc-shared-web/mcr.config.mjs node --import fake-indexeddb/auto --test --test-force-exit 'test/unit/**/*.test.mjs'",
+    "typecheck": "tsc",
+    "lint": "slicc-lint",
+    "format": "biome check --write .",
+    "trust": "npx fledgling sync -y --skip-publish",
+    "trust:dry": "npx fledgling sync --dry-run -y --skip-publish",
+    "release": "semantic-release"
+  },
+  "devDependencies": {
+    "@ai-ecoverse/slicc-shared-web": "1.13.1",
+    "@biomejs/biome": "2.5.15",
+    "@happy-dom/global-registrator": "20.14.5",
+    "@spectrum-css/button": "14.2.0",
+    "@spectrum-css/textfield": "8.2.0",
+    "@spectrum-css/tokens": "16.0.2",
+    "esbuild": "0.28.2",
+    "fake-indexeddb": "6.2.5",
+    "happy-dom": "20.14.5",
+    "lefthook": "2.1.17",
+    "monocart-coverage-reports": "2.13.0",
+    "playwright-core": "1.63.0",
+    "semantic-release": "25.0.9",
+    "typescript": "7.0.2"
+  }
 }