@ai-ecoverse/slicc-vault 1.0.0 → 1.2.0

package/README.md

@@ -2,8 +2,8 @@
 
 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.
 
-- **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.
+- **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, the attested policy (rules, `[exec]`, `[exits]`, `[limits]`), and the vault side of the `/dev/sealed` ops `seal`, `placeholder`, `list`, `test`, `request`, `status`, `cancel` and `materialize`.
+- **Not built yet:** `forward` and the scrubber (`test` always refuses), exec, `import` and `export`, and the agent's ops. They answer as described below.
 
 ## Documents and hosting
 
@@ -64,10 +64,76 @@ Everything lives in the vault origin's IndexedDB, database `slicc-vault`, versio
 - **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`.
+- **`state`** is computed, never stored: `removed` when `removedAt` is set, `active` when the accepted policy has a rule for the record (below), otherwise `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`.
+
+## Policy
+
+The rules come only from two root-owned kernel files. bios reads them with the kernel's page-only `kernel.attest(path)` (KS-7), at boot and whenever either file changes, and passes the results through unchanged:
+
+```js
+port.postMessage({ v: 1, id, op: 'policy', files: [await kernel.attest('/etc/fnox/config.toml'), await kernel.attest('/etc/slicc/secrets-policy.toml')] });
+```
+
+**An attestation** is exactly `{ path, bytes, uid, gid, mode, ino, mtimeMs, sha256, users, onRootFs, parents }`, nothing more or less:
+
+| field | format |
+|---|---|
+| `path` | the canonical absolute path the kernel read (it refuses symlinks and mount points) |
+| `bytes` | the file's bytes, a `Uint8Array`, read in the same step as the stats |
+| `uid`, `gid`, `mode` | integers; `mode` includes the type bits (`0o100644`) |
+| `ino`, `mtimeMs` | numbers |
+| `sha256` | 64 lower-case hex characters |
+| `users` | the kernel's users mode: `off`, `report` or `enforce` |
+| `onRootFs` | true only on the root file system, under no mount |
+| `parents` | every directory from `/` down to the file's, each exactly `{ path, uid, gid, mode }` |
+
+The vault trusts a file only when:
+- `path` is `/etc/fnox/config.toml` or `/etc/slicc/secrets-policy.toml`, and the object has exactly the fields above in those formats;
+- the SHA-256 the vault computes over `bytes` equals `sha256` (the field alone is never trusted);
+- `uid` is 0, and `mode` is a regular file with `mode & 0o022` of 0;
+- `parents` lists exactly the directories above `path`, in order from `/`, each with uid 0, a directory type and `mode & 0o022` of 0;
+- `onRootFs` is true, and `users` is `enforce`;
+- `bytes` is UTF-8 and parses.
+
+Otherwise the vault keeps the policy it last accepted for that file, so the rules it would have changed stay as they were (new ones stay inert), and warns, e.g. `rules not trusted: /etc/fnox/config.toml: kernel users must be enforce`. The reply is `{ accepted, files: [{ path, sha256, accepted, warnings }], rules: [{ secret, domain, header, methods, paths }], warnings }`, with `rules` the rules now in effect. `status.policy` repeats `files` from the last `policy` call, so Settings can show why rules aren't trusted.
+
+**The KS-7 conformance fixtures** are `test/integration/fixtures/attest/*.json`: `{ description, trusted, reason?, attestation }`, with `bytes` as base64, written by `make.mjs` next to them. `good-*` must be trusted, and every `bad-*` must be refused with a warning containing `reason`. The vault's own tests run them through the `policy` op, and the kernel's tests can check that `kernel.attest` produces the good shape.
+
+**`/etc/fnox/config.toml`**, the injection policy, read the way fnox reads it:
+- `[secrets]`: entries whose `provider` (or the file's `default_provider`) is `seven`, and whose `value` is a placeholder.
+- `[[proxy.rules]]`: `secret` (a seven entry of `[secrets]`), `domain` (one exact host, lower-cased), `header` (lower-cased, default `authorization`), `methods` (upper-cased; empty means any) and `paths` (each starting with `/`; empty means any). A rule that breaks any of this is dropped with a warning; the rest of the file still counts.
+- A record of kind `secret` is `active` when the file's `[secrets]` entry of its name holds the record's own placeholder and at least one rule names it. A placeholder from another vault or an old record doesn't activate anything.
+- Nothing else in the file counts: no imports, profiles or other providers.
+
+**`/etc/slicc/secrets-policy.toml`**, read by the vault only:
+
+```toml
+[exec]
+NPM_TOKEN = true
+GITHUB_TOKEN = { argv = [["/usr/bin/gh", "release", "upload"]] }
+OPENAI_API_KEY = { shell = true }
+
+[exits]
+NPM_TOKEN = ["page", "device:lars-air"]
+
+[limits]
+materialize_per_minute = 10
+materialize_per_day = 200
+shell_per_day = 5000
+```
+
+- `[exec]`: `false` is an explicit off, `true` is `exec: 'any'`, exactly `{ argv = [[…]] }` is `'argv'` (each prefix an absolute program path), and exactly `{ shell = true }` is `'shell'`. Anything else, a table with other or extra keys included, is a warning, and `exec` stays `false`. VAULT-1d acts on them.
+- `[exits]` is **optional**: a secret without a line may use every exit; a line restricts it to the exits listed (`page`, `proxy`, `tailscale`, `device:<name>`). Unknown names are dropped from the line with a warning, which leaves the line narrower, never wider.
+- `[limits]` overrides the defaults above with positive integers.
+
+Accepted policy is kept per namespace in IndexedDB, and loaded when an embedder says hello. Each file is audited once per SHA-256 and verdict (the vault remembers the last 64 per file) as a `policy` entry, with `accepted`, any `warning`, and its `changes` against the previously accepted file: rules `added` or `removed`, `exec` modes, `exits` lines and `limits`. Any change to the accepted policy, or a new audit entry, pushes `changed` with `secrets`, `exits` and `audit`, and other vault documents of the namespace reload the policy. Each `policy` call reads, merges and writes the stored policy in one transaction, so two pages can't undo each other's update.
+
 ## 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:
@@ -97,7 +163,7 @@ iframe.contentWindow.postMessage({ type: 'slicc-vault', v: 1, op: 'hello', role:
 | 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 } }` |
+| `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 |
@@ -106,6 +172,8 @@ iframe.contentWindow.postMessage({ type: 'slicc-vault', v: 1, op: 'hello', role:
 | `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 |
+| `policy` | `files` | the attested policy files, below (Policy) |
 | `import`, `export`, anything else | | `ENOTSUP` |
 
 `put` and `seal` need the vault unlocked. They answer `EACCES` with a message starting `vault is locked` otherwise.
@@ -125,7 +193,7 @@ bios relays each kernel request unchanged as the `sealed` op, with the kernel's
 |---|---|---|
 | `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 |
+| `list` | — | `{ secrets: [{ name, placeholder, state, exec, rules, expiresAt? }] }`, records of kind `secret` that aren't removed, with their rules and `[exec]` mode |
 | `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 |
@@ -195,7 +263,7 @@ The npm package `@ai-ecoverse/slicc-vault` holds only TypeScript types, built fr
 - **`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.
+- **`VaultList.refused`** lists rules the vault dropped because they name a model or MCP endpoint (empty until VAULT-1b).
 - **`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.
 

package/dist/types/contract.d.ts

@@ -77,7 +77,11 @@ export interface VaultStatus {
     lock: LockMode;
     scrub: ScrubState;
     waiting: PendingRequest[];
+    exportedAt: EpochMs | null;
+    backupReminder: BackupReminder;
+    policy: PolicyFileState[];
 }
+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 = {
@@ -162,6 +166,38 @@ export interface ExitPolicyView {
         exits: ExitName[];
     }[];
 }
+export interface Attestation {
+    path: string;
+    bytes: Uint8Array;
+    uid: number;
+    gid: number;
+    mode: number;
+    ino: number;
+    mtimeMs: EpochMs;
+    sha256: string;
+    users: string;
+    onRootFs: boolean;
+    parents: {
+        path: string;
+        uid: number;
+        gid: number;
+        mode: number;
+    }[];
+}
+export interface PolicyFileState {
+    path: string;
+    sha256: string | null;
+    accepted: boolean;
+    warnings: string[];
+}
+export interface PolicyResult {
+    accepted: boolean;
+    files: PolicyFileState[];
+    rules: (Rule & {
+        secret: string;
+    })[];
+    warnings: string[];
+}
 export interface VaultList {
     secrets: SecretView[];
     refused: RefusedRule[];
@@ -263,6 +299,11 @@ export type Op = {
     passphrase: string;
 } | {
     op: 'lock';
+} | {
+    op: 'dismissBackupReminder';
+} | {
+    op: 'policy';
+    files: Attestation[];
 };
 export type OpReply = {
     op: 'sealed';
@@ -291,7 +332,12 @@ export type OpReply = {
     bundle: Uint8Array;
 } | {
     op: 'lock';
-};
+} | {
+    op: 'dismissBackupReminder';
+    backupReminder: BackupReminder;
+} | ({
+    op: 'policy';
+} & PolicyResult);
 export type Request = Op & {
     v: Protocol;
     id: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-vault",
-  "version": "1.0.0",
+  "version": "1.2.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",
@@ -46,7 +46,7 @@
     "release": "semantic-release"
   },
   "devDependencies": {
-    "@ai-ecoverse/slicc-shared-web": "1.13.0",
+    "@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",