@ai-matrx/vault 0.1.10 → 0.1.12

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import * as react from 'react';
+import { ReactNode } from 'react';
 import { Look } from '@ai-matrx/design-system';
 import { KnobClient } from '@ai-matrx/data/knobs';
 import * as account from '@ai-matrx/api/account';
@@ -122,8 +123,26 @@ declare function locationFromParams(params: URLSearchParams, itemId?: string | n
 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
+ * one "One-time password" row, never as loose fields — and always kept when the item is saved.
+ */
+/**
+ * A vault item a host keeps for itself, never shown in any list (the desktop app's Touch ID key:
+ * its one-time-password factor's secret, so each of the person's computers can read it). Marked by
+ * this tag; the person's own vault holds it like any other item, encrypted by the server.
+ */
+declare const HIDDEN_ITEM_TAG = "matrx:hidden";
+declare const isHiddenItem: (item: {
+    tags?: readonly string[] | null;
+}) => boolean;
 /** An item's website as people read it: `github.com` (no scheme, no `www.`), or "" when it has none. */
 declare function loginSiteOf(item: Pick<VaultItem, "loginUrls">): string;
+/**
+ * The site a host belongs to, its registrable domain: `accounts.google.com` → `google.com`,
+ * `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[];
 interface NewSecretField {
     key: string;
@@ -240,6 +259,12 @@ interface VaultIdentity {
     withEmailCode(code: string): Promise<void>;
     /** A host-only path with no human step (the playground's dev server). */
     dev?: () => Promise<void>;
+    /**
+     * Run once when the page loads. After a provider confirmation left the page and came back, it
+     * checks the SAME person is signed in. A different account is signed out of this device and the
+     * sentence to show is returned; otherwise null.
+     */
+    checkReturn?: () => Promise<string | null>;
 }
 /** The slice of supabase-js `auth` this needs, so the package never depends on supabase-js itself. */
 interface SupabaseAuthLike {
@@ -305,12 +330,38 @@ interface SupabaseAuthLike {
             message: string;
         } | null;
     }>;
+    /** Used only when the host gives no `onDifferentPerson`: ends THIS device's session, never others. */
+    signOut?(o: {
+        scope: "local";
+    }): Promise<{
+        error: unknown;
+    }>;
 }
-/** THE identity confirmation for every host: give it the host's `supabase.auth`. */
-declare function createSupabaseIdentity(auth: SupabaseAuthLike, options?: {
+/** Where the person confirming is remembered while the page is away at the provider. */
+interface ReturnStore {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface SupabaseIdentityOptions {
+    /** The host's accepted OAuth return address carrying this page. */
     redirectTo?: () => string;
     dev?: () => Promise<void>;
-}): VaultIdentity;
+    /**
+     * A provider confirmation came back signed in as someone else. The host ends that session on THIS
+     * device only (its own device-scoped sign-out) and tells the person; `message` says what happened.
+     * Without it the package signs out locally through `auth.signOut({ scope: "local" })`.
+     */
+    onDifferentPerson?: (message: string) => Promise<void> | void;
+    /** Default: the tab's `sessionStorage`. */
+    store?: ReturnStore;
+    /** Default `Date.now`. */
+    now?: () => number;
+}
+/** The key the expected person is kept under across the provider's redirect. */
+declare const CONFIRM_RETURN_KEY = "matrx-vault:confirming-as";
+/** THE identity confirmation for every host: give it the host's `supabase.auth`. */
+declare function createSupabaseIdentity(auth: SupabaseAuthLike, options?: SupabaseIdentityOptions): VaultIdentity;
 /** True when the server refused because the sign-in is not recent enough. */
 declare function needsRecentSignIn(e: unknown): boolean;
 
@@ -1118,6 +1169,8 @@ interface VaultHostCapabilities {
     /** Desktop: the native passkey importer (file chooser, parsing and keys stay native). */
     nativeImport?: NativeImportBridge;
     openUrl?: (url: 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. */
     lock?: VaultLock;
     /** The host's clipboard: every copy goes through it; a secret is the host's to clear (`lock.ts`). */
@@ -1236,6 +1289,20 @@ interface ApiVaultPortOptions {
 }
 declare function createApiVaultPort(api: Api, options?: ApiVaultPortOptions): VaultPort;
 
+/**
+ * Wrap any call that shows, copies or exports a secret. When the server answers "sign in again",
+ * the person confirms it is them (Google, password, or an emailed code) and the call runs again —
+ * they never see a dead "Authentication required" in the row.
+ */
+type Confirmed = <T>(run: () => Promise<T>) => Promise<T>;
+declare function useConfirmed(): Confirmed;
+declare function IdentityGate({ identity, children }: {
+    identity: VaultIdentity | undefined;
+    children: ReactNode;
+}): react.JSX.Element;
+/** True for the rejection a cancelled confirmation produces (callers stay quiet about it). */
+declare const wasCancelled: (e: unknown) => boolean;
+
 /** Reads the organization's ceilings. Raw knob values are fine: they are validated here. */
 type GeneratorLimitsSource = () => Promise<{
     maxPasswordLength?: unknown;
@@ -1252,4 +1319,4 @@ declare function GenerateButton({ onUse, label, limits, disabled }: {
     disabled?: boolean;
 }): react.JSX.Element | null;
 
-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 };
+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 };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as react from 'react';
+import { ReactNode } from 'react';
 import { Look } from '@ai-matrx/design-system';
 import { KnobClient } from '@ai-matrx/data/knobs';
 import * as account from '@ai-matrx/api/account';
@@ -122,8 +123,26 @@ declare function locationFromParams(params: URLSearchParams, itemId?: string | n
 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
+ * one "One-time password" row, never as loose fields — and always kept when the item is saved.
+ */
+/**
+ * A vault item a host keeps for itself, never shown in any list (the desktop app's Touch ID key:
+ * its one-time-password factor's secret, so each of the person's computers can read it). Marked by
+ * this tag; the person's own vault holds it like any other item, encrypted by the server.
+ */
+declare const HIDDEN_ITEM_TAG = "matrx:hidden";
+declare const isHiddenItem: (item: {
+    tags?: readonly string[] | null;
+}) => boolean;
 /** An item's website as people read it: `github.com` (no scheme, no `www.`), or "" when it has none. */
 declare function loginSiteOf(item: Pick<VaultItem, "loginUrls">): string;
+/**
+ * The site a host belongs to, its registrable domain: `accounts.google.com` → `google.com`,
+ * `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[];
 interface NewSecretField {
     key: string;
@@ -240,6 +259,12 @@ interface VaultIdentity {
     withEmailCode(code: string): Promise<void>;
     /** A host-only path with no human step (the playground's dev server). */
     dev?: () => Promise<void>;
+    /**
+     * Run once when the page loads. After a provider confirmation left the page and came back, it
+     * checks the SAME person is signed in. A different account is signed out of this device and the
+     * sentence to show is returned; otherwise null.
+     */
+    checkReturn?: () => Promise<string | null>;
 }
 /** The slice of supabase-js `auth` this needs, so the package never depends on supabase-js itself. */
 interface SupabaseAuthLike {
@@ -305,12 +330,38 @@ interface SupabaseAuthLike {
             message: string;
         } | null;
     }>;
+    /** Used only when the host gives no `onDifferentPerson`: ends THIS device's session, never others. */
+    signOut?(o: {
+        scope: "local";
+    }): Promise<{
+        error: unknown;
+    }>;
 }
-/** THE identity confirmation for every host: give it the host's `supabase.auth`. */
-declare function createSupabaseIdentity(auth: SupabaseAuthLike, options?: {
+/** Where the person confirming is remembered while the page is away at the provider. */
+interface ReturnStore {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface SupabaseIdentityOptions {
+    /** The host's accepted OAuth return address carrying this page. */
     redirectTo?: () => string;
     dev?: () => Promise<void>;
-}): VaultIdentity;
+    /**
+     * A provider confirmation came back signed in as someone else. The host ends that session on THIS
+     * device only (its own device-scoped sign-out) and tells the person; `message` says what happened.
+     * Without it the package signs out locally through `auth.signOut({ scope: "local" })`.
+     */
+    onDifferentPerson?: (message: string) => Promise<void> | void;
+    /** Default: the tab's `sessionStorage`. */
+    store?: ReturnStore;
+    /** Default `Date.now`. */
+    now?: () => number;
+}
+/** The key the expected person is kept under across the provider's redirect. */
+declare const CONFIRM_RETURN_KEY = "matrx-vault:confirming-as";
+/** THE identity confirmation for every host: give it the host's `supabase.auth`. */
+declare function createSupabaseIdentity(auth: SupabaseAuthLike, options?: SupabaseIdentityOptions): VaultIdentity;
 /** True when the server refused because the sign-in is not recent enough. */
 declare function needsRecentSignIn(e: unknown): boolean;
 
@@ -1118,6 +1169,8 @@ interface VaultHostCapabilities {
     /** Desktop: the native passkey importer (file chooser, parsing and keys stay native). */
     nativeImport?: NativeImportBridge;
     openUrl?: (url: 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. */
     lock?: VaultLock;
     /** The host's clipboard: every copy goes through it; a secret is the host's to clear (`lock.ts`). */
@@ -1236,6 +1289,20 @@ interface ApiVaultPortOptions {
 }
 declare function createApiVaultPort(api: Api, options?: ApiVaultPortOptions): VaultPort;
 
+/**
+ * Wrap any call that shows, copies or exports a secret. When the server answers "sign in again",
+ * the person confirms it is them (Google, password, or an emailed code) and the call runs again —
+ * they never see a dead "Authentication required" in the row.
+ */
+type Confirmed = <T>(run: () => Promise<T>) => Promise<T>;
+declare function useConfirmed(): Confirmed;
+declare function IdentityGate({ identity, children }: {
+    identity: VaultIdentity | undefined;
+    children: ReactNode;
+}): react.JSX.Element;
+/** True for the rejection a cancelled confirmation produces (callers stay quiet about it). */
+declare const wasCancelled: (e: unknown) => boolean;
+
 /** Reads the organization's ceilings. Raw knob values are fine: they are validated here. */
 type GeneratorLimitsSource = () => Promise<{
     maxPasswordLength?: unknown;
@@ -1252,4 +1319,4 @@ declare function GenerateButton({ onUse, label, limits, disabled }: {
     disabled?: boolean;
 }): react.JSX.Element | null;
 
-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 };
+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 };