@ai-ecoverse/slicc-vault 1.6.0 → 1.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 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, the attested policy (rules, `[exec]`, `[exits]`, `[limits]`), the injector and `forward` with the response scrub (S1), the agent's `redact`, `redactStream` and `endpoints` (S3), the model and MCP refusal, exec tickets (`materialize` and `materializeConsume`), `import` (backups, KeePass, six's `secrets.env`) and `export`, and the vault side of the `/dev/sealed` ops `seal`, `placeholder`, `list`, `test`, `request`, `status`, `cancel` and `materialize`.
+- **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]`), the injector and `forward` with the response scrub (S1), the agent's `redact`, `redactStream` and `endpoints` (S3), the model and MCP refusal, exec tickets (`materialize` and `materializeConsume`), `import` (backups, KeePass, six's `secrets.env`) and `export`, sign-in tokens with their grants and refresh through `egress`, and the vault side of the `/dev/sealed` ops `seal`, `placeholder`, `list`, `test`, `request`, `status`, `cancel` and `materialize`.
 - **Not built yet:** the agent's `model`, `mcp`, `records`, `grant` and `refresh`. They answer as described below.
 - **The vault has no network stack.** It never fetches anything but its own `config.json` and `embedders.json`: bios sends every request the vault prepares.
 
@@ -153,14 +153,14 @@ Every record, request, audit entry and scrub version belongs to the origin that
 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]);
+iframe.contentWindow.postMessage({ type: 'slicc-vault', v: 1, op: 'hello', role: 'page', sudoGid }, '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`, `idle`, `end`, `drop`, `endpoints`, `model`, `mcp`, `records`, `grant` and `refresh` (the last five `ENOTSUP` in this version), and anything else is `EACCES`. The agent port gets no events. Its ops are below (The agent's ops).
-- **Values:** only `forward` (inside the head it returns, where an accepted rule allows it) and `materializeConsume` (for an `[exec]` grant) put a value into the page. No other op, event or reply carries one, and nothing on the agent port ever does.
+- **Values:** only `forward` (inside the head it returns, where an accepted rule allows it), `materializeConsume` (for an `[exec]` grant) and `egress` (a refresh request) put a value into the page. No other op, event or reply carries one, and nothing on the agent port ever does.
 
 | op (page role) | fields | reply |
 |---|---|---|
@@ -170,7 +170,9 @@ iframe.contentWindow.postMessage({ type: 'slicc-vault', v: 1, op: 'hello', role:
 | `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 |
+| `seal` | `name`, `value`, `source`, `kind?` (default `secret`), `expiresAt?`, `refresh?`, `oauth?`, `request?`, `jerk?` | `{ name, placeholder, state }`. bios's, for J1 leases and sign-in tokens, below (Tokens and refresh) |
+| `answer` | `request`, `state` (`progress` or `done`), `progress?` (≤ 200), `exit?`, `user?`, `scopes?`, `message?` (≤ 500), `rows?`, `placeholder?` | `{ state }`. The answer to a `jerk` or `unseal` request (or a sign-in that failed: for `oauth` and `jerk-seal`, `done` needs a nonzero `exit`, since only `seal` completes them); fields merge into the request, and `status` returns them. `rows` (for `jop: "list"`) are `{ provider, name?, env, device?, signedIn?, user?, scopes? }`, with any other field dropped, so no token can pass. For a `jop: "status"` answered `done` with `exit` 0, the vault adds the placeholder of the provider's own `oauth:<provider>` or `jerk:<provider>@…` record; a `placeholder` given by bios must be one of those records of the provider |
+| `refresh` | `name` | `{ state: 'refreshed', expiresAt? }` or `{ state: 'requested' }`, below |
 | `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 |
@@ -187,7 +189,9 @@ iframe.contentWindow.postMessage({ type: 'slicc-vault', v: 1, op: 'hello', role:
 **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.
+- `{ v: 1, event: 'changed', parts }`, with `parts` among `secrets`, `audit` and `exits`, so a view knows what to reload;
+- `{ v: 1, event: 'refresh', name, source, expiresAt }`, when a J1 lease is due (below);
+- `{ v: 1, event: 'egress', request }`, with a `MessagePort`, when the vault needs bios to send a request it built (below).
 
 **Errors** use errno names: `EINVAL`, `ENOENT`, `EACCES`, `EEXIST`, `EAGAIN`, `ETIMEDOUT`, `ENOTCONN`, and `ENOTSUP` for ops this version doesn't have.
 
@@ -204,12 +208,28 @@ bios relays each kernel request unchanged as the `sealed` op, with the kernel's
 | `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` |
+| `request` | `kind: "jerk"`, `jop` (`list`, `status`, `create`), `provider?` (needed but for `list`), `scope?`, `params?` (an object) | the same, or `{ state: 'done', id, exit: 2, message }` for a J2 refusal |
+| `request` | `kind: "unseal"`, `provider` | the same, or the J2 refusal |
+| `status` | `id` | `{ state }`, with `placeholder` and `record` once the request is `done`, `jerk` for a sign-in or lease that reported it, and the latest `answer` fields (`progress`, `exit`, `user`, `scopes`, `message`, `rows`, `placeholder`) |
 | `cancel` | `id` | `{ state }`: `cancelled`, or the state it had already reached |
 | `materialize` | `names` (or `shellGrants: true`), `path`, `argv`, `cwd`, `interpreter?` | `{ ticket, expiresAt, real: { NAME: true \| false } }`, below (Exec) |
 
-- **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.
+- **Requests** expire 300 s after they're made. Each uid has at most one pending request per namespace that waits for a human (`value`, `oauth`, `jerk-seal`, and `jerk` with `jop: "create"`); a second one is `EAGAIN`. `status` and `cancel` see only the caller's own requests (uid 0 sees all), and others get `ENOENT`. Only requests that wait for a human show in `status.waiting`.
+- A value request is answered by the page's `put` with its `request` id. A sign-in or lease (`oauth`, `jerk-seal`) is answered by `seal` with `request` (Tokens and refresh). Every other kind is answered by the page's `answer`. `cancel` ends any of them and pushes `{ v: 1, event: 'cancelled', request, kind }` to the page, which passes it on to J1 where it can.
+- **J-8's jerk requests** (§3.7.1): the vault only keeps their state; bios learns of them from the relay and answers. `jop: "create"` and `unseal` are for root and cones only (J2): the kernel stamp must have `users: 'enforce'`, and either uid 0 or the `sudo` group among its `groups`. bios names that group's gid as `sudoGid` in its hello; a page hello without it clears the namespace's gid. A stamp without `groups`, a vault without `sudoGid`, or any other mode refuses: the request is `done` with `exit: 2` at once, before bios sees anything. The tag is kept for audit and display only.
+
+## Tokens and refresh
+
+The vault has no network stack, so sign-ins run in seven's page (route (b), §3.11) and the vault keeps only the results.
+- **A sign-in's tokens:** bios runs the sign-in, does the code exchange, and hands the results to `seal`, keeping no copy:
+  - the refresh token as `{ kind: 'grant', name, value, source: 'oauth:<provider>', oauth: { tokenUrl, clientId, scope?, resource? } }`. A grant is never injected and never exported; `tokenUrl` must be `https:`;
+  - the access token as `{ name, value, source: 'oauth:<provider>', expiresAt, refresh: '<grant name>' }`. A grant name needs an `oauth:` source and `jerk-seal` a `jerk:` one (`EINVAL`), and a refresh uses the grant only when its source is the token's own (else the grant is missing).
+  - With `request` (only for a `secret`; the id of a pending `oauth` request for the same provider as `oauth:<provider>`, or a `jerk-seal` request for the provider of `jerk:<provider>@…`) and `jerk` (`{ exit, user?, scopes?, expires_at? }`), `seal` also answers that request, in the same transaction that stores the record (a request that ended meanwhile refuses with `EINVAL`, and nothing is stored): its `/dev/sealed` `status` becomes `done`, with `jerk`, the record's `placeholder` and `record` state.
+- **A J1 lease:** `{ name, value, source: 'jerk:<provider>@<device>', expiresAt, refresh: 'jerk-seal' }`.
+- **When a token is due** (5 minutes before `expiresAt`): the core frame checks once a minute, for every connected namespace, and `refresh { name }` asks for it at once. Vault frames of the same storage (several tabs) take a Web Lock per refresh source, so one grant is sent to its IdP by one frame at a time; a frame that finds the token changed while it waited (refreshed or sealed again) sends nothing and answers with the stored token's `{ state: 'refreshed', expiresAt? }`.
+  - A `jerk-seal` token is announced once per `expiresAt` (kept in IndexedDB, so across frames), and again every 10 minutes while it stays unsealed, in case no live page heard it, with the `refresh` event, and bios runs J1 `seal` again (`{ state: 'requested' }`).
+  - An OAuth token is refreshed in the vault: it builds `POST tokenUrl` with `grant_type=refresh_token`, the refresh token, `client_id` and any `scope` and `resource` (form-encoded), and sends it through bios with the `egress` event. bios sends the request through its exits and posts `{ status, headers, body }` (or `{ error }`) on the event's port within 30 s. The event goes to the page port of the namespace that connected last. A port that doesn't answer in time (`ETIMEDOUT`), closed or not, keeps its ops and events but gets no more `egress`, and the next refresh goes to the page port before it. The vault reads `access_token`, `expires_in` and any new `refresh_token`, checks them as values, and rotates the records in one transaction with the `refresh` audit entry (their placeholders stay; if the token or its grant was changed, removed or restored during the round trip, nothing is written and it answers `EAGAIN`). An `expires_in` of 0 makes the token due at once, and one that isn't a non-negative finite number is `EACCES: refresh failed: the IdP returned an invalid expires_in` (likewise a `refresh_token` that is present but not a string, and a `token_type` other than `Bearer`); a response carrying `error` fails even with a token; a response without `expires_in` leaves the new token without an expiry, so it isn't refreshed again until a new one is sealed. It answers `{ state: 'refreshed', expiresAt? }`, without `expiresAt` when the token has none. A failed refresh is `EACCES: refresh failed: <the IdP's error code>`, scrubbed. Without a connected page it's `ENOTCONN`.
+- `egress` carries the refresh token to the page, in transit only; the response goes back to the vault, never to the kernel.
 
 ## Import and export
 
@@ -232,7 +252,7 @@ Spectrum's Settings › Secrets reads the file and the password, and bios hands
 
 | `kind` | `password` | what becomes a candidate |
 |---|---|---|
-| `bundle` | the export passphrase | each record, with its kind, source (`import:bundle` when it isn't a valid source), expiry and **placeholder**, so the policy files still match. A placeholder used by another record of the namespace, or by another embedder of this vault, is refused, as is a name whose record here has another placeholder |
+| `bundle` | the export passphrase | each record, with its kind, source (`import:bundle` when it isn't a valid source), expiry and **placeholder**, so the policy files still match. A placeholder used by another record of the namespace, or by another embedder of this vault, is refused ("this app already has this secret under another name", "another app that uses this vault already has this secret; use it there, or add it here by hand"), as is a name whose record here has another placeholder ("this app already has a different secret with this name") |
 | `keepass` | the master password (KDBX 3 or 4, as kdbxweb reads them; Argon2 through hash-wasm) | each entry with a password, named after its title (upper-cased, other characters as `_`, a leading digit prefixed with `_`; a name already taken by an earlier entry gets `_2`, `_3`, …), source `import:keepass` |
 | `six` | — | each `NAME=value` line of six's `secrets.env` (`export` and quotes allowed), source `import:six`. `NAME_DOMAINS` becomes `suggestedRules`: a `[[proxy.rules]]` stanza per exact domain, for the human to add with `sudo`, and a note for each wildcard, which isn't carried over |
 

package/dist/types/contract.d.ts

@@ -6,7 +6,7 @@ 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 RequestKind = 'value' | 'oauth' | 'jerk-seal' | 'jerk' | 'unseal';
 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}`;
@@ -18,6 +18,8 @@ export interface Stamp {
     uid: number;
     gid: number;
     tag: string | null;
+    users?: string;
+    groups?: number[];
 }
 export interface VaultError {
     code: ErrorCode;
@@ -162,7 +164,11 @@ export interface PolicyEntry {
     changes: PolicyChange[];
     warning?: string;
 }
-export type AuditEntry = ForwardEntry | McpEntry | RevealEntry | SealEntry | RemoveEntry | PolicyEntry;
+export type AuditEntry = ForwardEntry | McpEntry | RevealEntry | SealEntry | RemoveEntry | RefreshEntry | PolicyEntry;
+export interface RefreshEntry extends AuditBase {
+    type: 'refresh';
+    grant: string;
+}
 export interface RequestHead {
     method: string;
     url: string;
@@ -352,7 +358,17 @@ export type Op = {
     kind?: RecordKind;
     expiresAt?: EpochMs;
     refresh?: string;
+    oauth?: OAuthConfig;
+    request?: string;
+    jerk?: JerkResult;
 } | {
+    op: 'refresh';
+    name: string;
+} | ({
+    op: 'answer';
+    request: string;
+    state: 'progress' | 'done';
+} & RequestAnswer) | {
     op: 'import';
     kind: ImportKind;
     bytes: Uint8Array;
@@ -468,7 +484,14 @@ export type OpReply = {
     backupReminder: BackupReminder;
 } | ({
     op: 'policy';
-} & PolicyResult) | ({
+} & PolicyResult) | {
+    op: 'refresh';
+    state: 'refreshed' | 'requested';
+    expiresAt?: EpochMs;
+} | {
+    op: 'answer';
+    state: RequestState;
+} | ({
     op: 'forward';
 } & ForwardResult) | {
     op: 'materializeConsume';
@@ -501,12 +524,71 @@ export type VaultEvent = {
     v: Protocol;
     event: 'changed';
     parts: ChangedPart[];
+} | {
+    v: Protocol;
+    event: 'refresh';
+    name: string;
+    source: RecordSource;
+    expiresAt: EpochMs;
+} | {
+    v: Protocol;
+    event: 'egress';
+    request: EgressRequest;
+} | {
+    v: Protocol;
+    event: 'cancelled';
+    request: string;
+    kind: RequestKind;
+};
+export interface JerkRow {
+    provider: string;
+    name?: string;
+    env: string[];
+    device?: string;
+    signedIn?: boolean;
+    user?: string;
+    scopes?: string[];
+}
+export interface RequestAnswer {
+    progress?: string;
+    exit?: number;
+    user?: string;
+    scopes?: string[];
+    message?: string;
+    rows?: JerkRow[];
+    placeholder?: string;
+}
+export interface EgressRequest {
+    method: string;
+    url: string;
+    headers: [string, string][];
+    body: string;
+}
+export type EgressAnswer = {
+    status: number;
+    headers: [string, string][];
+    body: Uint8Array | string;
+} | {
+    error: string;
 };
+export interface OAuthConfig {
+    tokenUrl: string;
+    clientId: string;
+    scope?: string;
+    resource?: string;
+}
+export interface JerkResult {
+    exit: number;
+    user?: string;
+    scopes?: string[];
+    expires_at?: string;
+}
 export interface Hello {
     type: MessageType;
     v: Protocol;
     op: 'hello';
     role?: Role;
+    sudoGid?: number;
 }
 export type Greeting = {
     v: Protocol;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-vault",
-  "version": "1.6.0",
+  "version": "1.7.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",