@kybernesis/vault 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# @kybernesis/vault
+
+The person's logins, cards and addresses, usable by their agent without ever
+being read by it.
+
+Items live in the Kybernesis control plane, added from KYBER Studio
+(Settings → Vault, or a Chrome password CSV import). The summary half — label,
+site, username, a card's brand and last four — is what an agent may list. The
+secret half is sealed, and leaves the control plane through exactly one door: a
+materialize call that carries the agent's credential AND the person's verified
+principal, for one item, audited. The only caller of that door is
+`fill_from_vault`, which types the value into the page open on the agent's own
+computer (`@kybernesis/computer`'s DevTools fill) and returns which selectors
+were filled. The value is never a tool result, so it is never in a transcript.
+
+```ts title="agent/tools/list_vault.ts"
+import { listVaultTool } from "@kybernesis/vault";
+export default listVaultTool();
+```
+
+```ts title="agent/tools/fill_from_vault.ts"
+import { fillFromVaultTool } from "@kybernesis/vault";
+export default fillFromVaultTool();
+```
+
+## Who the vault belongs to
+
+`personFromContext` is default-deny: only a turn whose verified principal came
+from the control plane (`authenticator: "kybernesis"`, a `user`) has a vault.
+Studio turns and linked chat senders qualify; schedules, eve's local-dev
+principal and a channel's default principal do not, and get an empty list.
+
+## Guards
+
+- A **login** only fills on the site it was saved for (same registrable host or
+  a subdomain of it). A password typed into a look-alike is the whole phishing
+  problem, so the tool refuses rather than asking.
+- A **card** requires the person's approval on every fill (eve `user-approval`).
+- Every materialization writes an `audit_log` row naming the agent and the item.
+
+## Env
+
+`KYBERNESIS_ISSUER` (the control plane) and `KYBERNESIS_AGENT_CREDENTIAL` (this
+agent's credential) — the same two every enterprise-governed agent already has.

package/dist/client.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The agent's view of a person's vault, through the control plane.
+ *
+ * Two calls. `listItems` returns what the agent may know: a label, a site, a
+ * username, a card's brand and last four. `materialize` returns one item's
+ * secret, and exists for exactly one caller — the fill tool, which types it into
+ * a page and returns nothing. Both name the person from the turn's VERIFIED
+ * principal, never from the model: a vault is someone's, and an unattended turn
+ * (a schedule, an unlinked chat sender) has no one.
+ */
+export type VaultKind = "login" | "card" | "address" | "contact";
+export interface VaultSummary {
+    readonly id: string;
+    readonly kind: VaultKind;
+    readonly label: string;
+    readonly origin: string | null;
+    readonly summary: Readonly<Record<string, unknown>>;
+    readonly updatedAt: string;
+}
+export interface MaterializedItem extends VaultSummary {
+    readonly secret: Readonly<Record<string, unknown>>;
+}
+export interface VaultClientOptions {
+    /** The control plane. Defaults to KYBERNESIS_ISSUER, then agent.kybernesis.ai. */
+    readonly issuer?: string;
+    /** This agent's credential. Defaults to KYBERNESIS_AGENT_CREDENTIAL. */
+    readonly credential?: string;
+    readonly fetchImpl?: typeof fetch;
+}
+/** The shape of eve's tool context this package reads. Kept structural so the package has no opinion about the rest. */
+export interface PrincipalContext {
+    readonly session?: {
+        readonly auth?: {
+            readonly current?: {
+                readonly principalId?: string;
+                readonly authenticator?: string;
+                readonly principalType?: string;
+            } | null;
+        };
+    };
+}
+/**
+ * The person this turn is for, or null. Default-deny: only a principal the
+ * control plane itself authenticated (Studio, a linked chat sender) counts.
+ * eve's own local-dev and channel-default principals are not people the vault
+ * knows, so they get nothing.
+ */
+export declare function personFromContext(ctx: PrincipalContext): string | null;
+export declare const NO_PERSON = "This conversation has no signed-in person, so there is no vault to use. Ask them to continue from KYBER Studio or a linked channel.";
+export declare function listItems(options: VaultClientOptions, user: string, origin?: string): Promise<VaultSummary[]>;
+export declare function materialize(options: VaultClientOptions, user: string, id: string): Promise<MaterializedItem>;
+/** `accounts.example.com` and `example.com` are the same site for a stored login; `example.com.evil.net` is not. */
+export declare function sameSite(stored: string | null, pageUrl: string): boolean;
+/**
+ * Every value a form field may be filled with, by field name. Summary and
+ * secret flatten together; a card also gets `expiration` (MM/YY) and
+ * `expiration_long` (MM/YYYY), and a zero-padded `exp_month`.
+ */
+export declare function valuesOf(item: MaterializedItem): Record<string, string>;

package/dist/client.js

@@ -0,0 +1,96 @@
+const DEFAULT_ISSUER = "https://agent.kybernesis.ai";
+function base(options) {
+    return (options.issuer ?? process.env.KYBERNESIS_ISSUER ?? DEFAULT_ISSUER).replace(/\/$/, "");
+}
+function credentialOf(options) {
+    const credential = options.credential ?? process.env.KYBERNESIS_AGENT_CREDENTIAL;
+    if (!credential)
+        throw new Error("This agent has no control-plane credential, so it cannot reach anyone's vault.");
+    return credential;
+}
+/**
+ * The person this turn is for, or null. Default-deny: only a principal the
+ * control plane itself authenticated (Studio, a linked chat sender) counts.
+ * eve's own local-dev and channel-default principals are not people the vault
+ * knows, so they get nothing.
+ */
+export function personFromContext(ctx) {
+    const current = ctx.session?.auth?.current;
+    if (!current?.principalId)
+        return null;
+    if (current.authenticator !== "kybernesis")
+        return null;
+    if (current.principalType && current.principalType !== "user")
+        return null;
+    return current.principalId;
+}
+export const NO_PERSON = "This conversation has no signed-in person, so there is no vault to use. Ask them to continue from KYBER Studio or a linked channel.";
+async function post(options, path, body) {
+    const f = options.fetchImpl ?? fetch;
+    const res = await f(`${base(options)}${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${credentialOf(options)}` },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(20_000),
+    });
+    if (res.status === 401)
+        throw new Error("The control plane did not accept this agent's credential.");
+    if (res.status === 404)
+        throw new Error("That vault item does not exist (or is not this person's).");
+    if (!res.ok)
+        throw new Error(`The vault call failed (HTTP ${res.status}).`);
+    return (await res.json());
+}
+export async function listItems(options, user, origin) {
+    const body = await post(options, "/api/vault/items", { user, ...(origin ? { origin } : {}) });
+    return body.items ?? [];
+}
+export async function materialize(options, user, id) {
+    const body = await post(options, "/api/vault/materialize", { user, id });
+    return body.item;
+}
+/** `accounts.example.com` and `example.com` are the same site for a stored login; `example.com.evil.net` is not. */
+export function sameSite(stored, pageUrl) {
+    if (!stored)
+        return false;
+    try {
+        const a = new URL(stored).hostname.replace(/^www\./, "").toLowerCase();
+        const b = new URL(pageUrl).hostname.replace(/^www\./, "").toLowerCase();
+        return a === b || a.endsWith(`.${b}`) || b.endsWith(`.${a}`);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Every value a form field may be filled with, by field name. Summary and
+ * secret flatten together; a card also gets `expiration` (MM/YY) and
+ * `expiration_long` (MM/YYYY), and a zero-padded `exp_month`.
+ */
+export function valuesOf(item) {
+    const out = {};
+    for (const source of [item.summary, item.secret]) {
+        for (const [key, value] of Object.entries(source)) {
+            if (value === null || value === undefined)
+                continue;
+            out[key] = String(value);
+        }
+    }
+    if (item.kind === "card") {
+        const mm = out.expMonth ? out.expMonth.padStart(2, "0") : undefined;
+        const yyyy = out.expYear;
+        if (mm)
+            out.exp_month = mm;
+        if (yyyy) {
+            out.exp_year = yyyy;
+            out.exp_year_short = yyyy.slice(-2);
+            if (mm) {
+                out.expiration = `${mm}/${yyyy.slice(-2)}`;
+                out.expiration_long = `${mm}/${yyyy}`;
+            }
+        }
+        if (out.cardholder)
+            out.name = out.cardholder;
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { listVaultTool, fillFromVaultTool } from "./tools.js";
+export { VAULT_INSTRUCTIONS } from "./instructions.js";
+export { listItems, materialize, personFromContext, sameSite, valuesOf, NO_PERSON, type MaterializedItem, type PrincipalContext, type VaultClientOptions, type VaultKind, type VaultSummary, } from "./client.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { listVaultTool, fillFromVaultTool } from "./tools.js";
+export { VAULT_INSTRUCTIONS } from "./instructions.js";
+export { listItems, materialize, personFromContext, sameSite, valuesOf, NO_PERSON, } from "./client.js";

package/dist/instructions.d.ts

@@ -0,0 +1 @@
+export declare const VAULT_INSTRUCTIONS = "## The person's vault\n\nThe person can save logins, cards and addresses in KYBER Studio (Settings \u2192 Vault). You can use them on your own computer without ever seeing them:\n\n- `list_vault` with the page URL tells you what applies: labels, usernames, a card's brand and last four. That is all you get.\n- `fill_from_vault` types an item into the form you are looking at. You give the item id and the CSS selector of each field; the values go straight into the page. Then take a screenshot and check before submitting.\n\nRules: a login only fills on the site it was saved for; if the tool refuses, say so rather than retyping anything by hand. A card asks the person for approval every time. If a site asks for a code or a second factor, stop and tell the person what is on the screen \u2014 they can take over your screen. Never ask the person to paste a password into chat; point them to the vault instead.\n";

package/dist/instructions.js

@@ -0,0 +1,9 @@
+export const VAULT_INSTRUCTIONS = `## The person's vault
+
+The person can save logins, cards and addresses in KYBER Studio (Settings → Vault). You can use them on your own computer without ever seeing them:
+
+- \`list_vault\` with the page URL tells you what applies: labels, usernames, a card's brand and last four. That is all you get.
+- \`fill_from_vault\` types an item into the form you are looking at. You give the item id and the CSS selector of each field; the values go straight into the page. Then take a screenshot and check before submitting.
+
+Rules: a login only fills on the site it was saved for; if the tool refuses, say so rather than retyping anything by hand. A card asks the person for approval every time. If a site asks for a code or a second factor, stop and tell the person what is on the screen — they can take over your screen. Never ask the person to paste a password into chat; point them to the vault instead.
+`;

package/dist/tools.d.ts

@@ -0,0 +1,77 @@
+import { type VaultClientOptions } from "./client.js";
+/** What the person has that could apply here. Labels and handles only. */
+export declare function listVaultTool(options?: VaultClientOptions): import("eve/tools").ToolDefinition<{
+    page_url?: string | undefined;
+}, {
+    items: {
+        id: string;
+        kind: import("./client.js").VaultKind;
+        label: string;
+        site: string | null;
+    }[];
+    note: string;
+}> & {
+    execute(input: {
+        page_url?: string | undefined;
+    }, ctx: import("eve/tools").ToolContext): Promise<{
+        items: {
+            id: string;
+            kind: import("./client.js").VaultKind;
+            label: string;
+            site: string | null;
+        }[];
+        note: string;
+    }>;
+};
+/**
+ * Type a vault item into the page open on the agent's computer. The secret
+ * goes control plane → page; the model sees which selectors were filled.
+ *
+ * Guards: a login only fills on the site it was saved for (a password typed
+ * into a look-alike is the whole phishing problem), and a card asks the
+ * person first — logging in is what they saved the login for, spending is a
+ * decision each time.
+ */
+export declare function fillFromVaultTool(options?: VaultClientOptions): import("eve/tools").ToolDefinition<{
+    item_id: string;
+    page_url: string;
+    fields: {
+        field: string;
+        selector: string;
+        frameUrl?: string | undefined;
+    }[];
+    submit?: boolean | undefined;
+}, {
+    note: string;
+    unknown_fields?: string[] | undefined;
+    ok: boolean;
+    item: {
+        id: string;
+        kind: import("./client.js").VaultKind;
+        label: string;
+    };
+    filled: readonly string[];
+    missing: readonly string[];
+}> & {
+    execute(input: {
+        item_id: string;
+        page_url: string;
+        fields: {
+            field: string;
+            selector: string;
+            frameUrl?: string | undefined;
+        }[];
+        submit?: boolean | undefined;
+    }, ctx: import("eve/tools").ToolContext): Promise<{
+        note: string;
+        unknown_fields?: string[] | undefined;
+        ok: boolean;
+        item: {
+            id: string;
+            kind: import("./client.js").VaultKind;
+            label: string;
+        };
+        filled: readonly string[];
+        missing: readonly string[];
+    }>;
+};

package/dist/tools.js

@@ -0,0 +1,102 @@
+import { fillOnComputer } from "@kybernesis/computer";
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { NO_PERSON, listItems, materialize, personFromContext, sameSite, valuesOf, } from "./client.js";
+/** What the person has that could apply here. Labels and handles only. */
+export function listVaultTool(options = {}) {
+    return defineTool({
+        description: "List the signed-in person's saved logins, cards and addresses that apply to a site: labels, usernames, card brand and last four. Never the secrets. Give the page URL you are on so logins are filtered to that site.",
+        inputSchema: z.object({
+            page_url: z.string().url().optional().describe("The page open in your browser; logins are filtered to its site."),
+        }),
+        async execute(input, ctx) {
+            const user = personFromContext(ctx);
+            if (!user)
+                return { items: [], note: NO_PERSON };
+            const items = await listItems(options, user, input.page_url);
+            return {
+                items: items.map((i) => ({ id: i.id, kind: i.kind, label: i.label, site: i.origin, ...i.summary })),
+                note: items.length ? "Use fill_from_vault with an item id and the selectors of the fields you can see." : "Nothing saved for this site. The person can add it in KYBER Studio under Settings → Vault.",
+            };
+        },
+    });
+}
+const fieldSchema = z.object({
+    field: z
+        .string()
+        .min(1)
+        .max(40)
+        .describe("Which value: username, password, number, cvc, expiration (MM/YY), expiration_long (MM/YYYY), exp_month, exp_year, name/cardholder, or an address/contact key like line1, city, postal_code, email, phone."),
+    selector: z.string().min(1).max(500).describe("CSS selector of that input on the page."),
+    frameUrl: z.string().url().optional().describe("If the input is inside an iframe, that frame's URL prefix."),
+});
+/**
+ * Type a vault item into the page open on the agent's computer. The secret
+ * goes control plane → page; the model sees which selectors were filled.
+ *
+ * Guards: a login only fills on the site it was saved for (a password typed
+ * into a look-alike is the whole phishing problem), and a card asks the
+ * person first — logging in is what they saved the login for, spending is a
+ * decision each time.
+ */
+export function fillFromVaultTool(options = {}) {
+    return defineTool({
+        description: "Type a saved login, card or address from the person's vault into the form open in your own browser. Give the item id (from list_vault), the page URL as shown, and the CSS selector for each field you can see. The values never come back to you; the result says which selectors were filled. A login only fills on its own site. Take a screenshot afterwards before submitting.",
+        inputSchema: z.object({
+            item_id: z.string().min(1).max(200),
+            page_url: z.string().url(),
+            fields: z.array(fieldSchema).min(1).max(12),
+            submit: z.boolean().optional().describe("Press the form's submit after filling. Default false: look first."),
+        }),
+        approval: async (ctx) => {
+            // Spending needs a yes each time; signing in is what the person saved the
+            // login for. If anything about the question fails, ask.
+            try {
+                const user = personFromContext(ctx);
+                const id = ctx.toolInput?.item_id;
+                if (!user || !id)
+                    return "user-approval";
+                const items = await listItems(options, user);
+                const item = items.find((i) => i.id === id);
+                if (!item)
+                    return "user-approval";
+                return item.kind === "card" ? "user-approval" : "not-applicable";
+            }
+            catch {
+                return "user-approval";
+            }
+        },
+        async execute(input, ctx) {
+            const user = personFromContext(ctx);
+            if (!user)
+                throw new Error(NO_PERSON);
+            const item = await materialize(options, user, input.item_id);
+            if (item.kind === "login" && !sameSite(item.origin, input.page_url)) {
+                throw new Error(`That login was saved for ${item.origin}, and this page is ${new URL(input.page_url).origin}. It will not be typed into a different site. If this really is the same service, tell the person; they can save a login for this site.`);
+            }
+            const values = valuesOf(item);
+            const fields = [];
+            const unknown = [];
+            for (const f of input.fields) {
+                const value = values[f.field];
+                if (value === undefined) {
+                    unknown.push(f.field);
+                    continue;
+                }
+                fields.push({ selector: f.selector, value, ...(f.frameUrl ? { frameUrl: f.frameUrl } : {}) });
+            }
+            if (!fields.length)
+                throw new Error(`None of those field names exist on this ${item.kind}: ${unknown.join(", ")}. Available: ${Object.keys(values).join(", ")}.`);
+            const sandbox = await ctx.getSandbox();
+            const result = await fillOnComputer(sandbox, { pageOrigin: new URL(input.page_url).origin, fields, submit: input.submit ?? false });
+            return {
+                ok: result.ok,
+                item: { id: item.id, kind: item.kind, label: item.label },
+                filled: result.filled,
+                missing: result.missing,
+                ...(unknown.length ? { unknown_fields: unknown } : {}),
+                note: result.ok ? "Filled. Take a screenshot and check before you submit." : "Some selectors were not found on the page; look again and correct them.",
+            };
+        },
+    });
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kybernesis/vault",
+  "version": "0.1.0",
+  "description": "The person's password and card vault, usable by their eve agent on its own computer: the agent sees labels and handles, the control plane holds the secrets, and a fill tool types them into the page so they are never in the transcript.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KybernesisAI/platform.git",
+    "directory": "packages/vault"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "node ../../scripts/prepublish.mjs",
+    "test": "node --test \"test/**/*.test.mjs\""
+  },
+  "peerDependencies": {
+    "@kybernesis/computer": ">=0.2.0 <0.3.0",
+    "eve": ">=0.68.0 <0.69.0",
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "@kybernesis/computer": "*",
+    "eve": "0.68.0",
+    "zod": "^4.0.0",
+    "typescript": "^5.9.0",
+    "@types/node": "^24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}