@ai-matrx/vault 0.1.5 → 0.1.7

package/dist/index.d.cts

@@ -122,7 +122,7 @@ 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;
 /** An item's website as people read it: `github.com` (no scheme, no `www.`), or "" when it has none. */
-declare function siteOf(item: Pick<VaultItem, "loginUrls">): string;
+declare function loginSiteOf(item: Pick<VaultItem, "loginUrls">): string;
 declare function sortItems(items: readonly VaultItem[], sort: VaultSort): VaultItem[];
 interface NewSecretField {
     key: string;
@@ -147,9 +147,6 @@ interface ItemDraft {
     authenticator: string;
 }
 
-type NoticeKind = "success" | "error" | "info";
-type Notify = (message: string, kind?: NoticeKind) => void;
-
 /** One recorded earlier value of a secret field. Value-free: the value comes only from `revealHistory`. */
 interface HistoryEntry {
     fieldId: string;
@@ -1096,7 +1093,8 @@ interface VaultPort {
  * What only some hosts can do. A missing capability hides its control; it never shows a dead one.
  * - Every host with a signed-in person supplies `identity` (confirm it's you before a secret shows).
  * - The browser extension supplies `page` (the tab's address, the logins that match it) and `fill`.
- * - The desktop app supplies `nativeProvider` (the system credential provider's state).
+ * - The desktop app supplies `nativeProvider` (the system credential provider's state), and its own
+ *   `lock`, `clipboard` custody and `revealSeconds`.
  */
 interface VaultHostCapabilities {
     identity?: VaultIdentity;
@@ -1114,12 +1112,71 @@ interface VaultHostCapabilities {
     /** Desktop: the native passkey importer (file chooser, parsing and keys stay native). */
     nativeImport?: NativeImportBridge;
     openUrl?: (url: string) => void;
+    /** A lock the host holds (`lock.ts`): while locked the vault shows Unlock and refuses every port call. */
+    lock?: VaultLock;
+    /** The host's clipboard: every copy goes through it; a secret is the host's to clear (`lock.ts`). */
+    clipboard?: VaultClipboard;
+    /** How long a shown value stays shown, in seconds (an organization knob the host reads); default 20. */
+    revealSeconds?: number;
     nativeProvider?: {
         status: "ready" | "needs_setup" | "unavailable";
         openSetup: () => void;
     };
 }
 
+/**
+ * A HOST-HELD LOCK. Some hosts lock the vault themselves (the desktop app: Touch ID, starts locked,
+ * locks after idle, on sleep and on screen lock). The host owns the lock and enforces it on its own
+ * side; the vault shows a locked screen with Unlock, and while locked refuses every port call — a
+ * value never reaches a screen while the host says locked. Without `lock` nothing changes.
+ */
+interface VaultLock {
+    /** Locked right now. */
+    locked(): boolean;
+    /** Told on every change; returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** Ask the host to unlock (Touch ID, a click…). Rejects with a sentence a person can act on. */
+    unlock(): Promise<void>;
+    /** Lock now. When given, the vault offers "Lock". */
+    lock?: () => void | Promise<void>;
+    /** The unlock button's words ("Unlock with Touch ID"); default "Unlock". */
+    unlockLabel?: string;
+}
+/**
+ * HOST CLIPBOARD CUSTODY. When given, every copy in the vault goes through the host. `secret` asks
+ * the host to take custody: clear it after a while if it is still there, and on lock or quit.
+ */
+interface VaultClipboard {
+    copy(text: string, how: {
+        secret: boolean;
+    }): Promise<void>;
+}
+declare const LOCKED_MESSAGE = "The vault is locked. Unlock it first.";
+declare class VaultLockedError extends Error {
+    readonly code = "vault_locked";
+    constructor();
+}
+/**
+ * The port with every method (areas included) refused while `locked()` says so. The check runs at
+ * call time, so a screen still mounted when the lock lands cannot read a value.
+ */
+declare function guardPort(port: VaultPort, locked: () => boolean): VaultPort;
+
+type NoticeKind = "success" | "error" | "info";
+type Notify = (message: string, kind?: NoticeKind) => void;
+interface CopyOptions {
+    /** A secret (a password, a code, a key): the host's clipboard takes custody. Default true. */
+    secret?: boolean;
+}
+/**
+ * Writes `text` and says so (or says why not). Through the host's clipboard when it has one (custody:
+ * the host clears a secret later), else the browser's. Pure over its inputs, so it is tested alone.
+ */
+declare function copyValue(text: string, label: string, options: CopyOptions, deps: {
+    clipboard?: VaultClipboard | undefined;
+    notify: Notify;
+}): Promise<boolean>;
+
 type VaultLayout = "auto" | "full" | "split" | "stack";
 interface VaultAppProps {
     port: VaultPort;
@@ -1183,4 +1240,4 @@ declare function GenerateButton({ onUse, label, limits, disabled }: {
     disabled?: boolean;
 }): react.JSX.Element | null;
 
-export { type ApiVaultPortOptions, CATEGORIES, type CategoryId, DEFAULT_LOCATION, type DefinitionField, type FieldHandling, type FieldKind, GenerateButton, type IdentityAccount, type IdentityMethod, type ItemDraft, type NoticeKind, type Notify, type SaveResult, type SupabaseAuthLike, type TotpReading, type UriMatchMode, type UrlGuess, VaultApp, type VaultAppProps, type VaultAttachment, type VaultAuthenticator, type VaultCustomField, type VaultDefinition, type VaultField, type VaultHostCapabilities, type VaultIdentity, type VaultItem, type VaultItemCapabilities, type VaultKnobs, type VaultLayout, type VaultLocation, type VaultOrganizationRef, type VaultOwner, type VaultPort, type VaultSelection, type VaultSnapshot, type VaultSort, type VaultUserStateDoor, categoryOf, createApiVaultPort, createSupabaseIdentity, createVaultKnobs, inferFromUrl, locationFromParams, locationToParams, matchesQuery, needsRecentSignIn, parseDefinitions, siteOf, sortItems };
+export { type ApiVaultPortOptions, CATEGORIES, type CategoryId, type CopyOptions, DEFAULT_LOCATION, type DefinitionField, type FieldHandling, type FieldKind, GenerateButton, type IdentityAccount, type IdentityMethod, type ItemDraft, LOCKED_MESSAGE, type NoticeKind, type Notify, type SaveResult, type SupabaseAuthLike, 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, locationFromParams, locationToParams, loginSiteOf, matchesQuery, needsRecentSignIn, parseDefinitions, sortItems };

package/dist/index.d.ts

@@ -122,7 +122,7 @@ 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;
 /** An item's website as people read it: `github.com` (no scheme, no `www.`), or "" when it has none. */
-declare function siteOf(item: Pick<VaultItem, "loginUrls">): string;
+declare function loginSiteOf(item: Pick<VaultItem, "loginUrls">): string;
 declare function sortItems(items: readonly VaultItem[], sort: VaultSort): VaultItem[];
 interface NewSecretField {
     key: string;
@@ -147,9 +147,6 @@ interface ItemDraft {
     authenticator: string;
 }
 
-type NoticeKind = "success" | "error" | "info";
-type Notify = (message: string, kind?: NoticeKind) => void;
-
 /** One recorded earlier value of a secret field. Value-free: the value comes only from `revealHistory`. */
 interface HistoryEntry {
     fieldId: string;
@@ -1096,7 +1093,8 @@ interface VaultPort {
  * What only some hosts can do. A missing capability hides its control; it never shows a dead one.
  * - Every host with a signed-in person supplies `identity` (confirm it's you before a secret shows).
  * - The browser extension supplies `page` (the tab's address, the logins that match it) and `fill`.
- * - The desktop app supplies `nativeProvider` (the system credential provider's state).
+ * - The desktop app supplies `nativeProvider` (the system credential provider's state), and its own
+ *   `lock`, `clipboard` custody and `revealSeconds`.
  */
 interface VaultHostCapabilities {
     identity?: VaultIdentity;
@@ -1114,12 +1112,71 @@ interface VaultHostCapabilities {
     /** Desktop: the native passkey importer (file chooser, parsing and keys stay native). */
     nativeImport?: NativeImportBridge;
     openUrl?: (url: string) => void;
+    /** A lock the host holds (`lock.ts`): while locked the vault shows Unlock and refuses every port call. */
+    lock?: VaultLock;
+    /** The host's clipboard: every copy goes through it; a secret is the host's to clear (`lock.ts`). */
+    clipboard?: VaultClipboard;
+    /** How long a shown value stays shown, in seconds (an organization knob the host reads); default 20. */
+    revealSeconds?: number;
     nativeProvider?: {
         status: "ready" | "needs_setup" | "unavailable";
         openSetup: () => void;
     };
 }
 
+/**
+ * A HOST-HELD LOCK. Some hosts lock the vault themselves (the desktop app: Touch ID, starts locked,
+ * locks after idle, on sleep and on screen lock). The host owns the lock and enforces it on its own
+ * side; the vault shows a locked screen with Unlock, and while locked refuses every port call — a
+ * value never reaches a screen while the host says locked. Without `lock` nothing changes.
+ */
+interface VaultLock {
+    /** Locked right now. */
+    locked(): boolean;
+    /** Told on every change; returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** Ask the host to unlock (Touch ID, a click…). Rejects with a sentence a person can act on. */
+    unlock(): Promise<void>;
+    /** Lock now. When given, the vault offers "Lock". */
+    lock?: () => void | Promise<void>;
+    /** The unlock button's words ("Unlock with Touch ID"); default "Unlock". */
+    unlockLabel?: string;
+}
+/**
+ * HOST CLIPBOARD CUSTODY. When given, every copy in the vault goes through the host. `secret` asks
+ * the host to take custody: clear it after a while if it is still there, and on lock or quit.
+ */
+interface VaultClipboard {
+    copy(text: string, how: {
+        secret: boolean;
+    }): Promise<void>;
+}
+declare const LOCKED_MESSAGE = "The vault is locked. Unlock it first.";
+declare class VaultLockedError extends Error {
+    readonly code = "vault_locked";
+    constructor();
+}
+/**
+ * The port with every method (areas included) refused while `locked()` says so. The check runs at
+ * call time, so a screen still mounted when the lock lands cannot read a value.
+ */
+declare function guardPort(port: VaultPort, locked: () => boolean): VaultPort;
+
+type NoticeKind = "success" | "error" | "info";
+type Notify = (message: string, kind?: NoticeKind) => void;
+interface CopyOptions {
+    /** A secret (a password, a code, a key): the host's clipboard takes custody. Default true. */
+    secret?: boolean;
+}
+/**
+ * Writes `text` and says so (or says why not). Through the host's clipboard when it has one (custody:
+ * the host clears a secret later), else the browser's. Pure over its inputs, so it is tested alone.
+ */
+declare function copyValue(text: string, label: string, options: CopyOptions, deps: {
+    clipboard?: VaultClipboard | undefined;
+    notify: Notify;
+}): Promise<boolean>;
+
 type VaultLayout = "auto" | "full" | "split" | "stack";
 interface VaultAppProps {
     port: VaultPort;
@@ -1183,4 +1240,4 @@ declare function GenerateButton({ onUse, label, limits, disabled }: {
     disabled?: boolean;
 }): react.JSX.Element | null;
 
-export { type ApiVaultPortOptions, CATEGORIES, type CategoryId, DEFAULT_LOCATION, type DefinitionField, type FieldHandling, type FieldKind, GenerateButton, type IdentityAccount, type IdentityMethod, type ItemDraft, type NoticeKind, type Notify, type SaveResult, type SupabaseAuthLike, type TotpReading, type UriMatchMode, type UrlGuess, VaultApp, type VaultAppProps, type VaultAttachment, type VaultAuthenticator, type VaultCustomField, type VaultDefinition, type VaultField, type VaultHostCapabilities, type VaultIdentity, type VaultItem, type VaultItemCapabilities, type VaultKnobs, type VaultLayout, type VaultLocation, type VaultOrganizationRef, type VaultOwner, type VaultPort, type VaultSelection, type VaultSnapshot, type VaultSort, type VaultUserStateDoor, categoryOf, createApiVaultPort, createSupabaseIdentity, createVaultKnobs, inferFromUrl, locationFromParams, locationToParams, matchesQuery, needsRecentSignIn, parseDefinitions, siteOf, sortItems };
+export { type ApiVaultPortOptions, CATEGORIES, type CategoryId, type CopyOptions, DEFAULT_LOCATION, type DefinitionField, type FieldHandling, type FieldKind, GenerateButton, type IdentityAccount, type IdentityMethod, type ItemDraft, LOCKED_MESSAGE, type NoticeKind, type Notify, type SaveResult, type SupabaseAuthLike, 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, locationFromParams, locationToParams, loginSiteOf, matchesQuery, needsRecentSignIn, parseDefinitions, sortItems };