@ai-ecoverse/slicc-vault 1.11.0 → 1.12.1

package/README.md

@@ -112,7 +112,8 @@ Otherwise the vault keeps the policy it last accepted for that file, so the rule
 - **Session rules** (§3.19) add `protocol` and `port` (an integer from 1 to 65535), and are used only by `sessionMaterialize`, never by `forward`; a rule without `protocol` is used only by `forward`:
   - `protocol = "http1"`: `header`, `methods` and `paths` as above; the position is the header. A `position` is a warning.
   - `protocol = "smtp"`, with `position = "auth-plain"` or `"auth-login"`, or `protocol = "pg"`, with `position = "password-cleartext"` or `"scram-sha-256"` (each allowed only where a rule names it): no `header`, `methods` or `paths` (a warning otherwise). Its `header` reads `''`.
-  - `port` or `position` without `protocol`, another `protocol`, or a missing or wrong `port` or `position` is a warning, and the rule is dropped.
+  - **Trust anchors** (§3.19.6), on any session rule: `anchors` (base64 DER certificates, each starting with a SEQUENCE and at most 8 KB), `pins` (base64 SHA-256 of a public key, 32 bytes) and `roots` (`true` or `false`), at most 8 anchors and 8 pins. A rule with anchors or pins accepts only sessions the kernel verified against them, never the public roots, unless it says `roots = true`; a rule without them accepts the public roots, and `roots = false` there is a warning. The vault checks only their format: the kernel checks that an anchor is a CA (CA:true and keyCertSign) and the chain. Like every rule, they come only from the attested root-owned file, so only an approved `sudo` write sets them: no program, agent or page op can.
+  - `port`, `position`, `anchors`, `pins` or `roots` without `protocol`, another `protocol`, or a missing or wrong `port`, `position`, `anchors`, `pins` or `roots` is a warning, and the rule is dropped.
 - 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.
 
@@ -184,7 +185,8 @@ iframe.contentWindow.postMessage({ type: 'slicc-vault', v: 1, op: 'hello', role:
 | `policy` | `files` | the attested policy files, below (Policy) |
 | `forward` | `head`, `body?`, `owner`, `exit`, `rawTraits`, with a `MessagePort` transferred alongside | the injected head, below (Forward) |
 | `materializeConsume` | `ticket`, `stamp`, `path`, `resolved`, `argv`, `cwd`, `interpreters`, `trusted` | the values for the child's environment, below (Exec) |
-| `sessionMaterialize` | `stamp`, `session`, `host`, `port`, `protocol`, `position`, `verified`, `handshakeAt`, `exit`, then `placeholders` (and `head` for http1) at every position but `scram-sha-256`, which takes `scram` and no `placeholders` | `{ values }` for a kernel-verified TLS session, below (Sessions) |
+| `sessionMaterialize` | `stamp`, `session`, `host`, `port`, `protocol`, `position`, `verified`, `handshakeAt`, `exit`, `verifiedBy?`, `anchor?`, then `placeholders` (and `head` for http1) at every position but `scram-sha-256`, which takes `scram` and no `placeholders` | `{ values }` for a kernel-verified TLS session, below (Sessions) |
+| `sessionAnchors` | `stamp`, `session`, `host`, `port`, `protocol`, `exit` | `{ anchors, pins }`, below (Sessions) |
 | `import` | `kind`, `bytes`, `password?`, `pick?` | below (Import and export) |
 | `export` | `passphrase` | `{ bundle, count }`, below |
 | anything else | | `ENOTSUP` |
@@ -329,6 +331,7 @@ The fields are the kernel's session attestation:
 - `host`: the name the kernel verified the leaf against, compared lower-cased without one trailing dot; `port`; `protocol` (`http1`, `smtp` or `pg`).
 - `position`: `header:<name>` (lower-cased) for http1, else `auth-plain`, `auth-login`, `password-cleartext` or `scram-sha-256` (below).
 - `verified`: the kernel's own verdict on the chain and the name; `handshakeAt`: when the handshake finished (epoch ms).
+- `verifiedBy`: `roots` (the default; the kernel's bundled public roots) or `anchored` (a rule's anchors or pins, below), with `anchor`: base64 of the SHA-256 of the whole DER of the anchor that verified the chain, as `sessionAnchors` gave it, or the pin itself. `anchor` with `roots`, or a missing or malformed one with `anchored`, is `EINVAL`.
 - `exit`: the exit the session leaves by (`page`, `proxy`, `tailscale` or `device:<id>`, with the device's `DeviceId`).
 - `placeholders` (every position but `scram-sha-256`, which takes `scram` instead, below): 1 to 16 placeholders, every one found at the position, in one request. `head` (http1 only, required there): `{ method, path }`, the request line's method and target.
 - A malformed field is `EINVAL`, and so is a `protocol` other than these or a `position` that isn't one of its protocol's; neither burns the session.
@@ -342,7 +345,9 @@ Once the fields check out, the vault burns the session in IndexedDB, in one tran
 
 Each placeholder then gets its value only when it is a `secret` record's, holding the placeholder `[secrets]` names, neither removed nor expired, with a session rule of that secret whose `protocol`, `domain`, `port` and position are the session's (and, for http1, whose `methods` and `paths` allow `head`), and whose `[exits]` line, if any, lists `exit`. A session can carry several secrets this way, each by its own rule. Just before answering, the records, the accepted policy and the registered endpoints are read again, at a fresh clock, in the transaction that audits the values. A value whose record was removed, expired or rotated meanwhile, or whose rule or `[exits]` line no longer allows it, is withheld. A session past its deadline by then, or an http1 URL now under a registered endpoint, refuses the whole request. That transaction is the point of release: if the vault locked before it, it writes nothing and refuses (`vault is locked`).
 
-It answers `{ values: { [placeholder]: value } }` for those, and leaves the others out, so the kernel sends them as written. When none gets a value, it's `EACCES` with the first placeholder's reason: "NAME isn't a secret", "a placeholder of no record of this vault", "NAME's placeholder isn't the one /etc/fnox/config.toml names", "NAME was removed", "NAME expired", "no session rule in /etc/fnox/config.toml lets NAME be used", "no session rule lets NAME at PROTOCOL POSITION on HOST:PORT" (with " for METHOD PATH" for http1), "NAME isn't allowed on EXIT", or "the secret or its rule changed meanwhile". Each value handed out adds a `session` audit entry `{ name, session, domain, port, protocol, position, rule, exit, uid, tag }`, `rule` being the number of the rule that allowed it, and sets the record's `usedAt`. It never includes the value. Stored values never hold CR, LF or NUL (Records), so a value can't break out of its position.
+It answers `{ values: { [placeholder]: value } }` for those, and leaves the others out, so the kernel sends them as written. When none gets a value, it's `EACCES` with the first placeholder's reason: "NAME isn't a secret", "a placeholder of no record of this vault", "NAME's placeholder isn't the one /etc/fnox/config.toml names", "NAME was removed", "NAME expired", "no session rule in /etc/fnox/config.toml lets NAME be used", "no session rule lets NAME at PROTOCOL POSITION on HOST:PORT" (with " for METHOD PATH" for http1), "NAME isn't allowed on EXIT", or "the secret or its rule changed meanwhile". Each value handed out adds a `session` audit entry `{ name, session, domain, port, protocol, position, rule, verifiedBy, anchor?, exit, uid, tag }`, `rule` being the number of the rule that allowed it and `verifiedBy` and `anchor` how the kernel trusted the session (`anchor` only when `anchored`: the anchor's DER SHA-256 or the pin, never a value; entries written before 1.12.1 have neither, which means unknown, never `roots`), and sets the record's `usedAt`. It never includes the value. Stored values never hold CR, LF or NUL (Records), so a value can't break out of its position.
+
+**`sessionAnchors`** (§3.19.6) is value-free: when the kernel's bundled roots fail a session only on trust (the leaf names the host and the chain is otherwise valid), it asks with `{ stamp, session, host, port, protocol, exit }` (checked as above; `users` must be `enforce`), and the vault answers `{ anchors, pins }`: every anchor and pin of the session rules for that `protocol`, `domain` and `port` whose secret's `[exits]` line, if any, lists `exit`, without duplicates, or empty lists. It burns nothing and needs no unlocked vault. The kernel then verifies the chain against those anchors only (never the program's `ca`), and asks `sessionMaterialize` with `verifiedBy: 'anchored'` and the `anchor` it used. A placeholder gets its value only by a rule that trusts the session: a rule with anchors or pins needs an `anchored` session whose `anchor` is one of that rule's own ("the anchor that verified the session isn't one of NAME's session rule" otherwise), or `roots = true` for a `roots` session ("NAME's session rule accepts only its anchors and pins, not public roots"); a rule without them takes a `roots` session only. So one rule's anchor never opens another rule's secret, and a pinned host can't fall back to a public CA.
 
 **pg SCRAM-SHA-256** (`position: 'scram-sha-256'`, §3.19.5). The program's pg client computes its `ClientProof` from the password it holds, a placeholder, so the kernel can't see which one it used; the vault finds it from the proof. The request carries `scram: { clientFirstBare, serverFirst, clientFinalBare, proof }` and no `placeholders` (`EINVAL` otherwise, and `scram` at any other position is `EINVAL` too):
 - `clientFirstBare` is `n=<user>,r=<client nonce>` and `serverFirst` is `r=<nonce>,s=<salt>,i=<iterations>`, with no extensions; the server's nonce must extend the client's, and `i` must be 1 to 100000.
@@ -452,13 +457,13 @@ The button writes its intent to `intents` under a random 128-bit nonce and opens
 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 stable id of a linked device's link certificate, the same id bios uses for linked devices and trays, in `sourceDevice`, `device:<id>` exits (and `[exits]` lines) and `ExitPolicyView.devices[].device`; never a display name.
-- **`Rule`**: `domain` is an exact lower-case host; `header` a lower-case header name; **empty `methods` or `paths` mean any**. A rule with `protocol` (`http1`, `smtp`, `pg`) is a session rule, with its `port` and, for smtp and pg, its `position`; show it as "PROTOCOL on host:port".
+- **`Rule`**: `domain` is an exact lower-case host; `header` a lower-case header name; **empty `methods` or `paths` mean any**. A rule with `protocol` (`http1`, `smtp`, `pg`) is a session rule, with its `port` and, for smtp and pg, its `position`; show it as "PROTOCOL on host:port". `anchors`, `pins` and `roots` are its trust anchors (Policy).
 - **`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>`).
 - **Bindings in `list`:** read under one scrub version (retried, then `EAGAIN`), `provider`, `server` and `settings` are scrubbed over every value (a setting whose name holds one is dropped), and left out while the vault is locked before its first unlock.
 - **`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; a `model` record always has its `provider`, an `mcp` record may have its `server`, and either may carry non-secret `settings`.
 - **Who did it:** `uid` and `tag` are the kernel stamp for entries a program or the agent caused (`/dev/sealed` seals, `forward`, `mcp`, `materialize`, `session`). Every entry from a page-role op (`put`, `seal`, `remove`, `restore`, `import`, `policy`) and from the vault itself (`refresh`) has `uid: null, tag: null`, older entries included. Spectrum shows page ops as "by you", `refresh` as "automatically", and `policy` entries with no "by …".
-- **`AuditEntry`**: `forward` is a use of a value in a request, with the exit that carried it; `mcp` a kernel program's call to a registered MCP server; `session` a value handed to the kernel for a verified TLS session (show it as "Sent over PROTOCOL to host"); **`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.
+- **`AuditEntry`**: `forward` is a use of a value in a request, with the exit that carried it; `mcp` a kernel program's call to a registered MCP server; `session` a value handed to the kernel for a verified TLS session (show it as "Sent over PROTOCOL to host", with "trusted by public roots" or "trusted by its pinned anchor" from `verifiedBy`, and nothing when an older entry has no `verifiedBy`); **`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.
 - **`SessionTarget`**: a `sessionMaterialize` request's protocol, position and what goes with it: `placeholders` (and `head` for http1) for every position but `scram-sha-256`, which takes `scram` (a `ScramExchange`) and no `placeholders`.
 - **`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.

package/dist/types/contract.d.ts

@@ -69,6 +69,9 @@ export interface Rule {
     protocol?: SessionProtocol;
     position?: SessionPosition;
     port?: number;
+    anchors?: string[];
+    pins?: string[];
+    roots?: boolean;
 }
 export interface RefusedRule {
     secret: string;
@@ -172,6 +175,8 @@ export interface SessionEntry extends AuditBase {
     protocol: SessionProtocol;
     position: string;
     rule: number;
+    verifiedBy?: 'roots' | 'anchored';
+    anchor?: string;
     exit: ExitName;
 }
 export interface McpEntry extends AuditBase {
@@ -492,7 +497,21 @@ export type Op = {
     verified: boolean;
     handshakeAt: EpochMs;
     exit: ExitName;
-} & SessionTarget);
+} & SessionTarget & ({
+    verifiedBy?: 'roots';
+    anchor?: never;
+} | {
+    verifiedBy: 'anchored';
+    anchor: string;
+})) | {
+    op: 'sessionAnchors';
+    stamp: Stamp;
+    session: string;
+    host: string;
+    port: number;
+    protocol: SessionProtocol;
+    exit: ExitName;
+};
 export type AgentOp = {
     op: 'redact';
     texts: (string | Uint8Array)[];
@@ -634,6 +653,10 @@ export type OpReply = {
 } | {
     op: 'sessionMaterialize';
     values: Record<string, string>;
+} | {
+    op: 'sessionAnchors';
+    anchors: string[];
+    pins: string[];
 };
 export type Request = Op & {
     v: Protocol;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-vault",
-  "version": "1.11.0",
+  "version": "1.12.1",
   "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",
@@ -47,7 +47,7 @@
   },
   "devDependencies": {
     "@ai-ecoverse/jerk-oauth": "1.0.0",
-    "@ai-ecoverse/slicc-kernel": "1.125.12",
+    "@ai-ecoverse/slicc-kernel": "1.126.0",
     "@ai-ecoverse/slicc-scrub": "1.0.0",
     "@ai-ecoverse/slicc-shared-web": "1.24.2",
     "@ai-ecoverse/wasm-bash": "5.3.0-20",