@ai-matrx/vault 0.1.14 → 0.1.16

package/dist/index.d.cts

@@ -100,7 +100,8 @@ interface VaultOrganizationRef {
     id: string;
     name: string;
 }
-type VaultSort = "name" | "website" | "updated" | "created";
+/** `name` A–Z, `name-desc` Z–A, `viewed` = most recently opened first (needs the host's Recently opened door). */
+type VaultSort = "name" | "name-desc" | "website" | "updated" | "created" | "viewed";
 /** Which vault to look in. `all` is everything the person can see, shared with them included. */
 type VaultSelection = "all" | "mine" | "shared" | (string & {});
 interface VaultLocation {
@@ -123,7 +124,6 @@ declare const DEFAULT_LOCATION: VaultLocation;
 declare function locationFromParams(params: URLSearchParams, itemId?: string | null): VaultLocation;
 /** Writes everything that is not a default (and not the item id, which the host places). */
 declare function locationToParams(loc: VaultLocation): URLSearchParams;
-/** The one search every list shares: name, type, tags, URLs, then plaintext custom fields. */
 declare function matchesQuery(item: VaultItem, query: string): boolean;
 /**
  * The authenticator's own storage on an item (the seed, digits, period, issuer…): shown only as the
@@ -145,11 +145,26 @@ declare function loginSiteOf(item: Pick<VaultItem, "loginUrls">): string;
  * `shop.example.co.uk` → `example.co.uk`. An address or a one-label host is returned as it is.
  */
 declare function siteDomainOf(host: string): string;
-declare function sortItems(items: readonly VaultItem[], sort: VaultSort): VaultItem[];
+/**
+ * `recents` is the person's Recently opened ids, newest first: `viewed` puts those first in that
+ * order, then everything never opened by name. Without it `viewed` sorts by name.
+ */
+declare function sortItems(items: readonly VaultItem[], sort: VaultSort, recents?: readonly string[] | null): VaultItem[];
 interface NewSecretField {
     key: string;
     label: string;
     value: string;
+    /** The name sandboxes and workflows find it by (`GITHUB_TOKEN`); absent = none. */
+    envKey?: string;
+    /** Who may see it; absent = `revealable` (shown after "Confirm it's you"). */
+    handling?: FieldHandling;
+    /** Sandboxes get it as an env variable (needs `envKey`). */
+    injectIntoSandbox?: boolean;
+}
+/** How the browser treats a NEW item, chosen before its first save (afterwards: item settings). */
+interface DraftBrowserSettings {
+    uriMatchMode: UriMatchMode;
+    browserFillEnabled: boolean;
 }
 interface ItemDraft {
     name: string;
@@ -167,6 +182,8 @@ interface ItemDraft {
     removed: string[];
     /** A seed or otpauth address to enrol as the item's one-time password; empty = leave alone. */
     authenticator: string;
+    /** New item only: website matching and browser fill chosen before the first save; absent = the defaults. */
+    browser?: DraftBrowserSettings;
 }
 
 /** One recorded earlier value of a secret field. Value-free: the value comes only from `revealHistory`. */
@@ -1173,6 +1190,10 @@ interface VaultHostCapabilities {
     /** Desktop: the native passkey importer (file chooser, parsing and keys stay native). */
     nativeImport?: NativeImportBridge;
     openUrl?: (url: string) => void;
+    /** The browser extension: opens the full vault on the website. Without it there is no "Open on the web". */
+    openWebVault?: () => void;
+    /** Opens one item in a new browser tab (the web app: `/vault/<id>`). Without it there is no "Open in new tab". */
+    openItemInNewTab?: (itemId: string) => void;
     /** The host's own sign-in, offered when the session has ended (the web app: its login page, back here after). */
     signIn?: () => void;
     /** A lock the host holds (`lock.ts`): while locked the vault shows Unlock and refuses every port call. */
@@ -1240,6 +1261,40 @@ declare function copyValue(text: string, label: string, options: CopyOptions, de
     notify: Notify;
 }): Promise<boolean>;
 
+/**
+ * What an agent may know about the vault: its NON-SECRET shape, never a value.
+ *
+ * A host that offers agents on the vault (the web app's right-click menu and its Agents menu, surface
+ * `matrx-user/vault`) builds their context here, so every host says the same thing and none can leak
+ * more. `VaultItem` carries no plaintext (a revealed value lives only in the row that showed it), but
+ * a person can type a secret into a free-text box, so notes, descriptions and custom-field VALUES are
+ * left out on purpose: names, type, provider, websites' hosts, status, tags and field KEYS only.
+ */
+
+/** Everything the person can see, as `VaultApp`'s `onInventory` reports it. */
+interface VaultInventory {
+    items: readonly VaultItem[];
+    definitions: readonly VaultDefinition[];
+}
+/** The surface values `matrx-user/vault` declares (count, names, providers) plus the menu's content. */
+interface VaultAgentScope {
+    content: string;
+    credential_count: number;
+    credential_labels: string[];
+    credential_providers: string[];
+}
+/** The provider an item is for (`github`, `openai`), from its type; null for generic types. */
+declare function providerOf(item: VaultItem, definitions: readonly VaultDefinition[]): string | null;
+/** One item, as lines an agent may read. Never a value: field KEYS only. */
+declare function vaultItemFacts(item: VaultItem, definitions: readonly VaultDefinition[]): string[];
+/**
+ * The vault scope for an agent: the right-clicked item's facts when there is one, else the whole
+ * inventory by name and type; plus the three values the surface always carries.
+ */
+declare function vaultInventoryScope(inventory: VaultInventory, clicked?: VaultItem | null): VaultAgentScope;
+/** The item a right-click landed on: every list row carries `data-item="<id>"`. */
+declare function itemIdAt(target: Element | null | undefined): string | null;
+
 type VaultLayout = "auto" | "full" | "split" | "stack";
 interface VaultAppProps {
     port: VaultPort;
@@ -1261,6 +1316,11 @@ interface VaultAppProps {
      * Apple's text styles, AppKit controls and grouped boxes, sheets for panels, light and dark).
      */
     look?: Look;
+    /**
+     * Every item the person can see, each time the list changes: the host builds its agent context
+     * from it (`vaultInventoryScope`), never from secrets — items carry none.
+     */
+    onInventory?: (inventory: VaultInventory) => void;
 }
 /** THE VAULT WORKSPACE: one component for the web app, the extension side panel and the desktop app. */
 declare function VaultApp(props: VaultAppProps): react.JSX.Element;
@@ -1323,4 +1383,4 @@ declare function GenerateButton({ onUse, label, limits, disabled }: {
     disabled?: boolean;
 }): react.JSX.Element | null;
 
-export { type ApiVaultPortOptions, CATEGORIES, CONFIRM_RETURN_KEY, type CategoryId, type Confirmed, type CopyOptions, DEFAULT_LOCATION, type DefinitionField, type FieldHandling, type FieldKind, GenerateButton, HIDDEN_ITEM_TAG, type IdentityAccount, IdentityGate, type IdentityMethod, type ItemDraft, LOCKED_MESSAGE, type NoticeKind, type Notify, type ReturnStore, type SaveResult, type SupabaseAuthLike, type SupabaseIdentityOptions, type TotpReading, type UriMatchMode, type UrlGuess, VaultApp, type VaultAppProps, type VaultAttachment, type VaultAuthenticator, type VaultClipboard, type VaultCustomField, type VaultDefinition, type VaultField, type VaultHostCapabilities, type VaultIdentity, type VaultItem, type VaultItemCapabilities, type VaultKnobs, type VaultLayout, type VaultLocation, type VaultLock, VaultLockedError, type VaultOrganizationRef, type VaultOwner, type VaultPort, type VaultSelection, type VaultSnapshot, type VaultSort, type VaultUserStateDoor, categoryOf, copyValue, createApiVaultPort, createSupabaseIdentity, createVaultKnobs, guardPort, inferFromUrl, isHiddenItem, locationFromParams, locationToParams, loginSiteOf, matchesQuery, needsRecentSignIn, parseDefinitions, siteDomainOf, sortItems, useConfirmed, wasCancelled };
+export { type ApiVaultPortOptions, CATEGORIES, CONFIRM_RETURN_KEY, type CategoryId, type Confirmed, type CopyOptions, DEFAULT_LOCATION, type DefinitionField, type FieldHandling, type FieldKind, GenerateButton, HIDDEN_ITEM_TAG, type IdentityAccount, IdentityGate, type IdentityMethod, type ItemDraft, LOCKED_MESSAGE, type NoticeKind, type Notify, type ReturnStore, type SaveResult, type SupabaseAuthLike, type SupabaseIdentityOptions, type TotpReading, type UriMatchMode, type UrlGuess, type VaultAgentScope, VaultApp, type VaultAppProps, type VaultAttachment, type VaultAuthenticator, type VaultClipboard, type VaultCustomField, type VaultDefinition, type VaultField, type VaultHostCapabilities, type VaultIdentity, type VaultInventory, type VaultItem, type VaultItemCapabilities, type VaultKnobs, type VaultLayout, type VaultLocation, type VaultLock, VaultLockedError, type VaultOrganizationRef, type VaultOwner, type VaultPort, type VaultSelection, type VaultSnapshot, type VaultSort, type VaultUserStateDoor, categoryOf, copyValue, createApiVaultPort, createSupabaseIdentity, createVaultKnobs, guardPort, inferFromUrl, isHiddenItem, itemIdAt, locationFromParams, locationToParams, loginSiteOf, matchesQuery, needsRecentSignIn, parseDefinitions, providerOf, siteDomainOf, sortItems, useConfirmed, vaultInventoryScope, vaultItemFacts, wasCancelled };

package/dist/index.d.ts

@@ -100,7 +100,8 @@ interface VaultOrganizationRef {
     id: string;
     name: string;
 }
-type VaultSort = "name" | "website" | "updated" | "created";
+/** `name` A–Z, `name-desc` Z–A, `viewed` = most recently opened first (needs the host's Recently opened door). */
+type VaultSort = "name" | "name-desc" | "website" | "updated" | "created" | "viewed";
 /** Which vault to look in. `all` is everything the person can see, shared with them included. */
 type VaultSelection = "all" | "mine" | "shared" | (string & {});
 interface VaultLocation {
@@ -123,7 +124,6 @@ declare const DEFAULT_LOCATION: VaultLocation;
 declare function locationFromParams(params: URLSearchParams, itemId?: string | null): VaultLocation;
 /** Writes everything that is not a default (and not the item id, which the host places). */
 declare function locationToParams(loc: VaultLocation): URLSearchParams;
-/** The one search every list shares: name, type, tags, URLs, then plaintext custom fields. */
 declare function matchesQuery(item: VaultItem, query: string): boolean;
 /**
  * The authenticator's own storage on an item (the seed, digits, period, issuer…): shown only as the
@@ -145,11 +145,26 @@ declare function loginSiteOf(item: Pick<VaultItem, "loginUrls">): string;
  * `shop.example.co.uk` → `example.co.uk`. An address or a one-label host is returned as it is.
  */
 declare function siteDomainOf(host: string): string;
-declare function sortItems(items: readonly VaultItem[], sort: VaultSort): VaultItem[];
+/**
+ * `recents` is the person's Recently opened ids, newest first: `viewed` puts those first in that
+ * order, then everything never opened by name. Without it `viewed` sorts by name.
+ */
+declare function sortItems(items: readonly VaultItem[], sort: VaultSort, recents?: readonly string[] | null): VaultItem[];
 interface NewSecretField {
     key: string;
     label: string;
     value: string;
+    /** The name sandboxes and workflows find it by (`GITHUB_TOKEN`); absent = none. */
+    envKey?: string;
+    /** Who may see it; absent = `revealable` (shown after "Confirm it's you"). */
+    handling?: FieldHandling;
+    /** Sandboxes get it as an env variable (needs `envKey`). */
+    injectIntoSandbox?: boolean;
+}
+/** How the browser treats a NEW item, chosen before its first save (afterwards: item settings). */
+interface DraftBrowserSettings {
+    uriMatchMode: UriMatchMode;
+    browserFillEnabled: boolean;
 }
 interface ItemDraft {
     name: string;
@@ -167,6 +182,8 @@ interface ItemDraft {
     removed: string[];
     /** A seed or otpauth address to enrol as the item's one-time password; empty = leave alone. */
     authenticator: string;
+    /** New item only: website matching and browser fill chosen before the first save; absent = the defaults. */
+    browser?: DraftBrowserSettings;
 }
 
 /** One recorded earlier value of a secret field. Value-free: the value comes only from `revealHistory`. */
@@ -1173,6 +1190,10 @@ interface VaultHostCapabilities {
     /** Desktop: the native passkey importer (file chooser, parsing and keys stay native). */
     nativeImport?: NativeImportBridge;
     openUrl?: (url: string) => void;
+    /** The browser extension: opens the full vault on the website. Without it there is no "Open on the web". */
+    openWebVault?: () => void;
+    /** Opens one item in a new browser tab (the web app: `/vault/<id>`). Without it there is no "Open in new tab". */
+    openItemInNewTab?: (itemId: string) => void;
     /** The host's own sign-in, offered when the session has ended (the web app: its login page, back here after). */
     signIn?: () => void;
     /** A lock the host holds (`lock.ts`): while locked the vault shows Unlock and refuses every port call. */
@@ -1240,6 +1261,40 @@ declare function copyValue(text: string, label: string, options: CopyOptions, de
     notify: Notify;
 }): Promise<boolean>;
 
+/**
+ * What an agent may know about the vault: its NON-SECRET shape, never a value.
+ *
+ * A host that offers agents on the vault (the web app's right-click menu and its Agents menu, surface
+ * `matrx-user/vault`) builds their context here, so every host says the same thing and none can leak
+ * more. `VaultItem` carries no plaintext (a revealed value lives only in the row that showed it), but
+ * a person can type a secret into a free-text box, so notes, descriptions and custom-field VALUES are
+ * left out on purpose: names, type, provider, websites' hosts, status, tags and field KEYS only.
+ */
+
+/** Everything the person can see, as `VaultApp`'s `onInventory` reports it. */
+interface VaultInventory {
+    items: readonly VaultItem[];
+    definitions: readonly VaultDefinition[];
+}
+/** The surface values `matrx-user/vault` declares (count, names, providers) plus the menu's content. */
+interface VaultAgentScope {
+    content: string;
+    credential_count: number;
+    credential_labels: string[];
+    credential_providers: string[];
+}
+/** The provider an item is for (`github`, `openai`), from its type; null for generic types. */
+declare function providerOf(item: VaultItem, definitions: readonly VaultDefinition[]): string | null;
+/** One item, as lines an agent may read. Never a value: field KEYS only. */
+declare function vaultItemFacts(item: VaultItem, definitions: readonly VaultDefinition[]): string[];
+/**
+ * The vault scope for an agent: the right-clicked item's facts when there is one, else the whole
+ * inventory by name and type; plus the three values the surface always carries.
+ */
+declare function vaultInventoryScope(inventory: VaultInventory, clicked?: VaultItem | null): VaultAgentScope;
+/** The item a right-click landed on: every list row carries `data-item="<id>"`. */
+declare function itemIdAt(target: Element | null | undefined): string | null;
+
 type VaultLayout = "auto" | "full" | "split" | "stack";
 interface VaultAppProps {
     port: VaultPort;
@@ -1261,6 +1316,11 @@ interface VaultAppProps {
      * Apple's text styles, AppKit controls and grouped boxes, sheets for panels, light and dark).
      */
     look?: Look;
+    /**
+     * Every item the person can see, each time the list changes: the host builds its agent context
+     * from it (`vaultInventoryScope`), never from secrets — items carry none.
+     */
+    onInventory?: (inventory: VaultInventory) => void;
 }
 /** THE VAULT WORKSPACE: one component for the web app, the extension side panel and the desktop app. */
 declare function VaultApp(props: VaultAppProps): react.JSX.Element;
@@ -1323,4 +1383,4 @@ declare function GenerateButton({ onUse, label, limits, disabled }: {
     disabled?: boolean;
 }): react.JSX.Element | null;
 
-export { type ApiVaultPortOptions, CATEGORIES, CONFIRM_RETURN_KEY, type CategoryId, type Confirmed, type CopyOptions, DEFAULT_LOCATION, type DefinitionField, type FieldHandling, type FieldKind, GenerateButton, HIDDEN_ITEM_TAG, type IdentityAccount, IdentityGate, type IdentityMethod, type ItemDraft, LOCKED_MESSAGE, type NoticeKind, type Notify, type ReturnStore, type SaveResult, type SupabaseAuthLike, type SupabaseIdentityOptions, type TotpReading, type UriMatchMode, type UrlGuess, VaultApp, type VaultAppProps, type VaultAttachment, type VaultAuthenticator, type VaultClipboard, type VaultCustomField, type VaultDefinition, type VaultField, type VaultHostCapabilities, type VaultIdentity, type VaultItem, type VaultItemCapabilities, type VaultKnobs, type VaultLayout, type VaultLocation, type VaultLock, VaultLockedError, type VaultOrganizationRef, type VaultOwner, type VaultPort, type VaultSelection, type VaultSnapshot, type VaultSort, type VaultUserStateDoor, categoryOf, copyValue, createApiVaultPort, createSupabaseIdentity, createVaultKnobs, guardPort, inferFromUrl, isHiddenItem, locationFromParams, locationToParams, loginSiteOf, matchesQuery, needsRecentSignIn, parseDefinitions, siteDomainOf, sortItems, useConfirmed, wasCancelled };
+export { type ApiVaultPortOptions, CATEGORIES, CONFIRM_RETURN_KEY, type CategoryId, type Confirmed, type CopyOptions, DEFAULT_LOCATION, type DefinitionField, type FieldHandling, type FieldKind, GenerateButton, HIDDEN_ITEM_TAG, type IdentityAccount, IdentityGate, type IdentityMethod, type ItemDraft, LOCKED_MESSAGE, type NoticeKind, type Notify, type ReturnStore, type SaveResult, type SupabaseAuthLike, type SupabaseIdentityOptions, type TotpReading, type UriMatchMode, type UrlGuess, type VaultAgentScope, VaultApp, type VaultAppProps, type VaultAttachment, type VaultAuthenticator, type VaultClipboard, type VaultCustomField, type VaultDefinition, type VaultField, type VaultHostCapabilities, type VaultIdentity, type VaultInventory, type VaultItem, type VaultItemCapabilities, type VaultKnobs, type VaultLayout, type VaultLocation, type VaultLock, VaultLockedError, type VaultOrganizationRef, type VaultOwner, type VaultPort, type VaultSelection, type VaultSnapshot, type VaultSort, type VaultUserStateDoor, categoryOf, copyValue, createApiVaultPort, createSupabaseIdentity, createVaultKnobs, guardPort, inferFromUrl, isHiddenItem, itemIdAt, locationFromParams, locationToParams, loginSiteOf, matchesQuery, needsRecentSignIn, parseDefinitions, providerOf, siteDomainOf, sortItems, useConfirmed, vaultInventoryScope, vaultItemFacts, wasCancelled };