@ai-matrx/vault 0.0.0 → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1186 @@
+import * as react from 'react';
+import { KnobClient } from '@ai-matrx/data/knobs';
+import * as account from '@ai-matrx/api/account';
+import { Api } from '@ai-matrx/api';
+
+/**
+ * The Vault as the screens see it. Hosts map the wire shape into this once, in their VaultPort
+ * (`createApiVaultPort` does it for every host that talks to the server). Plaintext never lives
+ * here: an encrypted field carries a masked hint, and a revealed value is held only by
+ * `useTransientSecret` in the row showing it.
+ */
+/** Who may see a field's value. Mirrors the server contract: sealed has no human path, ever. */
+type FieldHandling = "visible" | "revealable" | "sealed";
+type FieldKind = "text" | "secret" | "url" | "multiline";
+interface VaultField {
+    id: string;
+    /** Stable key inside the item (`username`, `password`). */
+    key: string;
+    label: string;
+    kind: FieldKind;
+    handling: FieldHandling;
+    editable: boolean;
+    envKey: string | null;
+    injectIntoSandbox: boolean;
+    /** Plain words about this field (`fields/` edits it). */
+    description: string;
+    /** Off = kept, but not used by anything. Inactive fields stay on the item so they can be turned back on. */
+    active: boolean;
+}
+/** A plaintext custom field (the server's `non_secret_fields`): label + value, never encrypted. */
+interface VaultCustomField {
+    key: string;
+    label: string;
+    value: string;
+}
+interface VaultOwner {
+    kind: "me" | "organization" | "shared";
+    label: string;
+    organizationId: string | null;
+}
+interface VaultItemCapabilities {
+    canUse: boolean;
+    canEdit: boolean;
+    canReveal: boolean;
+    canManage: boolean;
+}
+interface VaultAuthenticator {
+    digits: number;
+    period: number;
+    enabled: boolean;
+}
+interface VaultAttachment {
+    id: string;
+    label: string;
+    /** What the file is for ("Signs App Store requests"); "" when none. */
+    description: string;
+    fileName: string;
+    mediaType: string;
+    sizeBytes: number;
+    handling: FieldHandling;
+    createdAt: string;
+    updatedAt: string;
+}
+/** How the browser decides an item matches a page. */
+type UriMatchMode = "host" | "domain" | "exact" | "never";
+interface VaultItem {
+    id: string;
+    name: string;
+    description: string;
+    definitionKey: string;
+    definitionLabel: string;
+    owner: VaultOwner;
+    tags: string[];
+    loginUrls: string[];
+    notes: string;
+    fields: VaultField[];
+    custom: VaultCustomField[];
+    authenticator: VaultAuthenticator | null;
+    capabilities: VaultItemCapabilities;
+    attachments: VaultAttachment[];
+    uriMatchMode: UriMatchMode;
+    browserFillEnabled: boolean;
+    /** `all_members` / `restricted` for an organization item. */
+    accessMode: string | null;
+    /** The person who owns the item (`user_id`). For the person's own items this is them. */
+    ownerUserId: string | null;
+    /** Set when the item is in the trash: what restoring it needs. */
+    deletion: {
+        deletionId: string | null;
+        deletedAt: string | null;
+    } | null;
+    updatedAt: string;
+    createdAt: string;
+}
+interface VaultOrganizationRef {
+    id: string;
+    name: string;
+}
+type VaultSort = "name" | "website" | "updated" | "created";
+/** Which vault to look in. `all` is everything the person can see, shared with them included. */
+type VaultSelection = "all" | "mine" | "shared" | (string & {});
+interface VaultLocation {
+    vault: VaultSelection;
+    /** `all`, `favorites`, `authenticator`, `trash`, `category:<id>`, `type:<definitionKey>` or `tag:<tag>`. */
+    view: string;
+    q: string;
+    sort: VaultSort;
+    /** The open item; null = none. */
+    itemId: string | null;
+    mode: "view" | "edit" | "new";
+    /** New-item flow: the chosen definition, and the URL pasted at the start (kept across steps). */
+    kind: string | null;
+    url: string;
+    /** A panel open over the workspace: `share`, `history`, `activity`, `files`, `move`, `import`, … */
+    panel: string | null;
+}
+declare const DEFAULT_LOCATION: VaultLocation;
+/** Reads a location from query params. The item id is the host's to place (a path or a param). */
+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;
+/** 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 sortItems(items: readonly VaultItem[], sort: VaultSort): VaultItem[];
+interface NewSecretField {
+    key: string;
+    label: string;
+    value: string;
+}
+interface ItemDraft {
+    name: string;
+    description: string;
+    tags: string[];
+    loginUrls: string[];
+    notes: string;
+    /** New values for encrypted fields the definition declares, by field key. Absent = unchanged. */
+    values: Record<string, string>;
+    /** Encrypted custom fields added in this edit. */
+    secrets: NewSecretField[];
+    /** The plaintext custom fields, complete. */
+    custom: VaultCustomField[];
+    /** Ids of encrypted fields to delete. */
+    removed: string[];
+    /** A seed or otpauth address to enrol as the item's one-time password; empty = leave alone. */
+    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;
+    revision: number;
+    recordedAt: string;
+    /** False when the server kept the change but not its value (it can be neither shown nor restored). */
+    available: boolean;
+}
+/** One page of an item's history, newest first. */
+interface HistoryPage {
+    entries: HistoryEntry[];
+    /** The chain head. A restore names it so a change made meanwhile is refused, never overwritten. */
+    historyRevision: number;
+    /** False when nothing on this item can be restored at all. */
+    restoreAvailable: boolean;
+    /** When capture began; earlier values were never recorded. */
+    captureStartedAt: string | null;
+    /** Pass to `history` for the next (older) page; null = no more. */
+    nextBefore: number | null;
+    /** Entries the server left out (unreadable), so the timeline is incomplete. */
+    omitted: number;
+    incomplete: boolean;
+}
+/** One audit row: what happened, who did it, when. Never a value. */
+interface AuditEntry {
+    id: string;
+    action: string;
+    /** Null when the platform itself acted (automation, a scheduled job). */
+    actorId: string | null;
+    /** The encrypted field the event is about, when it is about one. */
+    fieldId: string | null;
+    metadata: Record<string, unknown>;
+    at: string;
+}
+/** New or changed file details. `description: null` clears it. */
+interface FileDetails {
+    label?: string;
+    description?: string | null;
+    fileName?: string;
+    handling?: FieldHandling;
+}
+/** What happened to an item: password history, the audit trail, and its protected files. */
+interface ActivityPort {
+    /** Personal items only (the server refuses others). `before` = `nextBefore` of the previous page. */
+    history(item: VaultItem, before?: number | null): Promise<HistoryPage>;
+    /** Audited; needs a recent sign-in. */
+    revealHistory(item: VaultItem, fieldId: string, revision: number): Promise<string>;
+    /** Makes an earlier value current again. Rejects with `HistoryChangedError` when the history moved. */
+    restoreHistory(item: VaultItem, fieldId: string, revision: number, expectedHistoryRevision: number): Promise<VaultItem>;
+    /** Newest first. The server has no cursor, only a limit (1–500). */
+    audit(item: VaultItem, limit: number): Promise<AuditEntry[]>;
+    /** Each returns the item as the server now has it. */
+    addFile(item: VaultItem, file: File, details: {
+        label: string;
+        description: string | null;
+        handling: FieldHandling;
+    }): Promise<VaultItem>;
+    updateFile(item: VaultItem, attachmentId: string, details: FileDetails): Promise<VaultItem>;
+    replaceFile(item: VaultItem, attachmentId: string, file: File): Promise<VaultItem>;
+    deleteFile(item: VaultItem, attachmentId: string): Promise<VaultItem>;
+    /** The decrypted bytes. Audited; sealed files are always refused. */
+    downloadFile(item: VaultItem, attachment: VaultAttachment): Promise<Uint8Array>;
+}
+
+/**
+ * CONFIRM IT'S YOU. The server shows or exports a secret only after a sign-in from the last few
+ * minutes (`recent_auth_required`). Every host signs people in with Supabase, so the one way to
+ * produce a fresh sign-in lives here, over the host's own auth client — whichever way the person
+ * signs in: Google (or any connected provider), a password, or a code sent to their email.
+ */
+/** How a person can prove it is them again. Ordered by what the account actually uses. */
+type IdentityMethod = "provider" | "password" | "email_code" | "dev";
+interface IdentityAccount {
+    email: string | null;
+    /** Connected sign-in providers on the account (`google`, `github`, …), never `email`. */
+    providers: readonly string[];
+    hasPassword: boolean;
+}
+interface VaultIdentity {
+    account(): Promise<IdentityAccount>;
+    /** Leaves the page for the provider and comes back to the same address (the URL carries everything). */
+    withProvider(provider: string): Promise<void>;
+    withPassword(password: string): Promise<void>;
+    sendEmailCode(): Promise<void>;
+    withEmailCode(code: string): Promise<void>;
+    /** A host-only path with no human step (the playground's dev server). */
+    dev?: () => Promise<void>;
+}
+/** The slice of supabase-js `auth` this needs, so the package never depends on supabase-js itself. */
+interface SupabaseAuthLike {
+    getUser(): Promise<{
+        data: {
+            user: {
+                id: string;
+                email?: string | null;
+                identities?: {
+                    provider: string;
+                }[] | null;
+                app_metadata?: {
+                    providers?: string[];
+                };
+            } | null;
+        };
+        error: unknown;
+    }>;
+    signInWithPassword(c: {
+        email: string;
+        password: string;
+    }): Promise<{
+        data: {
+            user: {
+                id: string;
+            } | null;
+        };
+        error: {
+            message: string;
+        } | null;
+    }>;
+    signInWithOtp(c: {
+        email: string;
+        options?: {
+            shouldCreateUser?: boolean;
+        };
+    }): Promise<{
+        error: {
+            message: string;
+        } | null;
+    }>;
+    verifyOtp(c: {
+        email: string;
+        token: string;
+        type: "email";
+    }): Promise<{
+        data: {
+            user: {
+                id: string;
+            } | null;
+        };
+        error: {
+            message: string;
+        } | null;
+    }>;
+    signInWithOAuth(c: {
+        provider: never;
+        options?: {
+            redirectTo?: string;
+        };
+    }): Promise<{
+        error: {
+            message: string;
+        } | null;
+    }>;
+}
+/** THE identity confirmation for every host: give it the host's `supabase.auth`. */
+declare function createSupabaseIdentity(auth: SupabaseAuthLike, options?: {
+    redirectTo?: () => string;
+    dev?: () => Promise<void>;
+}): VaultIdentity;
+/** True when the server refused because the sign-in is not recent enough. */
+declare function needsRecentSignIn(e: unknown): boolean;
+
+/** One account's one-time password as the server reports it. Metadata only: never a seed. */
+interface AuthenticatorEntry {
+    itemId: string;
+    /** The login's name (the server has no separate authenticator name). */
+    name: string;
+    issuer: string | null;
+    /** The account the codes are for, from the setup address (`me@x.com`). */
+    account: string | null;
+    digits: number;
+    period: number;
+    algorithm: string;
+    enabled: boolean;
+    loginUrls: string[];
+}
+/**
+ * A two-factor method that is NOT an app code, recorded on the login as the plaintext custom field
+ * `mfa_method` so agents know to hand control back at the verification step.
+ */
+type MfaMethod = "sms" | "push_or_other";
+type ItemRef = Pick<VaultItem, "id" | "owner">;
+/**
+ * One-time passwords: every code, enrol by key / otpauth address / QR image, enable, disable,
+ * rename, remove, and the recorded non-app method. Every call may reject; enrol and remove may
+ * reject with "sign in again" — wrap them in `useConfirmed()`.
+ */
+interface AuthenticatorPort {
+    /** Every account the signed-in person holds a one-time password for. */
+    list(): Promise<AuthenticatorEntry[]>;
+    /** null when the item has none. */
+    get(item: ItemRef): Promise<AuthenticatorEntry | null>;
+    /** The current code and how long it lives. */
+    code(item: ItemRef & Pick<VaultItem, "authenticator">): Promise<TotpReading>;
+    /** A base32 setup key or a full `otpauth://totp/…` address. Needs a recent sign-in. */
+    enrol(item: ItemRef, input: string): Promise<AuthenticatorEntry>;
+    /** A QR image the server decodes in-request and drops. For hosts that cannot decode locally. */
+    enrolQrImage(item: ItemRef, image: Blob, fileName?: string): Promise<AuthenticatorEntry>;
+    /** On/off. Takes effect on the next code. */
+    setEnabled(item: ItemRef, enabled: boolean): Promise<AuthenticatorEntry>;
+    /** Deletes the seed. Two-factor stays on at the site; the phone app and backup codes still work. */
+    remove(item: ItemRef): Promise<void>;
+    /** Renames the login the code belongs to. */
+    rename(item: ItemRef, name: string): Promise<VaultItem>;
+    /** Records (or clears, with null) a non-app two-factor method on the login. */
+    setMfaMethod(item: ItemRef & Pick<VaultItem, "custom">, method: MfaMethod | null): Promise<VaultItem>;
+}
+
+/** One field a credential type declares. */
+interface DefinitionField {
+    key: string;
+    label: string;
+    kind: FieldKind;
+    handling: FieldHandling;
+    /** `metadata` fields are plaintext columns of the item; `encrypted` ones are secrets. */
+    storage: "metadata" | "encrypted";
+    required: boolean;
+}
+/** A credential type from the platform catalog (e.g. "GitHub personal access token"). */
+interface VaultDefinition {
+    key: string;
+    label: string;
+    family: string;
+    providerKey: string | null;
+    description: string;
+    fields: readonly DefinitionField[];
+    sortOrder: number;
+}
+/** Catalog rows -> definitions. A preset's own fields replace its base's; with none it inherits them. */
+declare function parseDefinitions(entries: readonly {
+    key: string;
+    payload: Record<string, unknown>;
+    sort_order?: number;
+}[]): VaultDefinition[];
+/** What a pasted address tells us: a name, the address itself, and the best-fitting type. */
+interface UrlGuess {
+    name: string;
+    url: string;
+    definitionKey: string | null;
+    /** True when the address belongs to a provider the catalog knows. */
+    recognised: boolean;
+    /** That provider's own types (its tokens, its apps), offered beside the login. */
+    alternatives: readonly string[];
+}
+declare function inferFromUrl(raw: string, definitions: readonly VaultDefinition[]): UrlGuess | null;
+/**
+ * THE CATEGORIES people browse by (1Password's left list), instead of the catalog's 130 raw types.
+ * Every type lands in exactly one, by its key and family; the raw type still shows on each item.
+ */
+declare const CATEGORIES: readonly [{
+    readonly id: "logins";
+    readonly label: "Logins";
+}, {
+    readonly id: "passkeys";
+    readonly label: "Passkeys";
+}, {
+    readonly id: "api";
+    readonly label: "API keys & tokens";
+}, {
+    readonly id: "oauth";
+    readonly label: "Apps & OAuth";
+}, {
+    readonly id: "infra";
+    readonly label: "Servers & databases";
+}, {
+    readonly id: "env";
+    readonly label: "Environment values";
+}, {
+    readonly id: "files";
+    readonly label: "Files & certificates";
+}, {
+    readonly id: "other";
+    readonly label: "Other";
+}];
+type CategoryId = (typeof CATEGORIES)[number]["id"];
+declare function categoryOf(key: string, family: string): CategoryId;
+
+/**
+ * BROWSERS THAT CAN FILL (access ladder T-30). Every AI Matrx extension install (or the macOS
+ * password app) that may fill a saved password has its own key, registered the first time it fills
+ * with a step-up: the person's password, or a passkey approval of that key from an aimatrx.com page.
+ * The server audits every registration, approval, fill and turn-off; turned-off devices stay listed.
+ */
+/** What is asking to fill: the browser extension, or the macOS password app. */
+type FillDeviceKind = "browser" | "mac";
+/** One browser (or Mac) that may fill saved passwords. Never carries key material. */
+interface FillDevice {
+    id: string;
+    label: string;
+    /** The extension origin that registered it (`chrome-extension://…`), when known. */
+    origin: string | null;
+    addedAt: string | null;
+    lastUsedAt: string | null;
+    /** Set once it was turned off. A turned-off device stays in the list. */
+    revokedAt: string | null;
+    revokeReason: string | null;
+    keyThumbprint: string;
+}
+/** How this person can confirm it is them to turn filling on. */
+interface FillStepUpMethods {
+    password: boolean;
+    passkey: boolean;
+}
+/** One key to approve: what the extension (or Mac app) put in the approval link. */
+interface FillApprovalRequest {
+    /** SHA-256 JWK thumbprint, 64 lowercase hex characters. */
+    keyThumbprint: string;
+    label: string | null;
+    kind: FillDeviceKind;
+}
+/** The extension's own registration of its public key (the password step-up path). */
+interface FillDeviceRegistration {
+    publicKeyJwk: Record<string, string>;
+    label: string;
+    origin: string | null;
+    /** The person's password as the step-up; omit when a fresh passkey approval of this key exists. */
+    password: string | null;
+}
+/**
+ * The passkey half (ONE WebAuthn stack: the auth server's passkeys, relying party `rpId`). Present
+ * only when the host supplied its auth client; `available()` says whether a ceremony can run on
+ * this page at all (passkeys belong to one domain).
+ */
+interface FillPasskeys {
+    rpId: string;
+    available(): boolean;
+    /** Runs one passkey ceremony and approves the key. The approval is single-use and expires in minutes. */
+    approve(request: FillApprovalRequest): Promise<{
+        expiresAt: string;
+    }>;
+    /** Adds a passkey to the signed-in account (the auth server's own ceremony). */
+    add(): Promise<void>;
+}
+interface DevicesPort {
+    /** Newest first, turned-off ones included. */
+    list(): Promise<FillDevice[]>;
+    /** Turns filling off for one device; returns it as the server now has it. */
+    revoke(deviceId: string): Promise<FillDevice>;
+    stepUpMethods(): Promise<FillStepUpMethods>;
+    /** For the extension host: register its key with a step-up. */
+    register(registration: FillDeviceRegistration): Promise<FillDevice>;
+    passkeys?: FillPasskeys;
+}
+/**
+ * The slice of supabase-js `auth` the passkey half needs, so the package never depends on
+ * supabase-js itself. Hosts pass their own `supabase.auth`.
+ */
+interface PasskeyAuthLike {
+    passkey: {
+        startAuthentication(): Promise<{
+            data: {
+                challenge_id: string;
+                options: unknown;
+            } | null;
+            error: unknown;
+        }>;
+    };
+    registerPasskey(): Promise<{
+        error: {
+            message?: string;
+        } | null;
+    }>;
+}
+
+/**
+ * WHAT THE BROWSER EXTENSION DOES FOR THE VAULT — types only.
+ *
+ * The package never touches a web page, a frame or a tab. Everything that does (reading the tab,
+ * finding the focused login field, filling it, catching a submitted login, this browser's own fill
+ * key) is the extension's work, offered here as host abilities. A missing ability hides its screen;
+ * none shows a dead control.
+ *
+ * Words are the package's: every outcome is a code, and the package says it (`page-logic.ts`). The
+ * one exception is `message` on a server refusal the package cannot word for itself.
+ *
+ * Live state comes two ways:
+ *   - `page` is a SNAPSHOT: the host passes a new object when the tab, its matches or its focused
+ *     field change (the host re-renders the workspace).
+ *   - `capture` and `fillSetup` are STORES (`get` + `subscribe`): service-worker messages arrive at
+ *     any time and only their card redraws.
+ */
+/** A small external store: `get` returns the same object until it changes (useSyncExternalStore). */
+interface HostStore<T> {
+    get(): T;
+    subscribe(onChange: () => void): () => void;
+}
+/** Why the server's match read failed. */
+type PageMatchError = "sign_in_required" | "forbidden" | "fill_setup_required" | "server_error";
+/** The server's "which logins may fill this page" read. */
+type PageMatchState = {
+    status: "loading";
+} | {
+    status: "ready";
+} | {
+    status: "error";
+    reason: PageMatchError;
+    retry: () => void;
+};
+/**
+ * Why Fill cannot run on this page right now. Absent = it can.
+ * - `restricted`: a browser page, or not https (filling never targets it)
+ * - `unavailable`: the extension cannot reach the page right now
+ * - `no_field`: no login box is focused yet ("click the username box, then Fill")
+ * - `matching_off`: saved-login matching is off in the extension's settings
+ * - `checking`: the extension is still looking at the page
+ */
+type PageBlock = "restricted" | "unavailable" | "no_field" | "matching_off" | "checking";
+/** What a Fill did. */
+type FillOutcome = "filled" | "partial" | "no_field" | "unavailable" | "not_started";
+/** What "Sign in for me" did (the agent's own credential_login on this tab). */
+type SignInOutcome = "signed_in" | "needs_code" | "challenge" | "rejected" | "several" | "no_match" | "unsafe" | "signed_out" | "unsupported" | "unknown";
+/**
+ * The tab the side panel sits beside. A SUPERSET of today's `VaultHostCapabilities.page`
+ * (`url` + `matchingItemIds`), so `ItemList`'s "This page" keeps working unchanged.
+ */
+interface ExtensionPage {
+    /** The tab's address ("" when no tab). */
+    url: string;
+    /** The logins the SERVER says may fill this page, best first. */
+    matchingItemIds: readonly string[];
+    /** The match read itself. Absent = settled (`ready`). */
+    matchState?: PageMatchState;
+    /**
+     * Of `matchingItemIds`, the ones a Fill would put into the focused field right now (the focused
+     * frame's own offer). Absent = every match.
+     */
+    fillableItemIds?: readonly string[];
+    /** Why Fill cannot run here. Absent = it can. */
+    blocked?: PageBlock;
+    /** "Sign in for me": fill AND submit, top frame only. Absent = not offered here. */
+    signIn?: (itemId: string) => Promise<SignInOutcome>;
+    /** Read the page and its matches again. */
+    refresh?: () => void;
+}
+/** Proposed replacement for `VaultHostCapabilities.fill` (today `Promise<void>`): it says what happened. */
+type ExtensionFill = (itemId: string) => Promise<FillOutcome>;
+/** A login the person just submitted on a page. Metadata only: the password stays in the host. */
+interface CapturePrompt {
+    id: string;
+    /** The site, as people read it (`github.com`). */
+    host: string;
+    /** The username the page showed (not secret), so the person knows which account. */
+    username: string | null;
+    /** Saved logins for this site the server approved as update targets. */
+    existing: readonly {
+        itemId: string;
+        name: string;
+    }[];
+    /** The host could not keep the login in trusted memory: it can only be saved by hand. */
+    unavailable?: boolean;
+}
+type CaptureDecision = {
+    action: "save";
+} | {
+    action: "update";
+    itemId: string;
+} | {
+    action: "dismiss";
+} | {
+    action: "never";
+};
+type CaptureResult = "saved" | "updated" | "dismissed" | "never" | "expired" | "sign_in_required" | "error";
+interface CaptureHost extends HostStore<CapturePrompt | null> {
+    /** The host writes the password to the vault itself; the package only sends the choice. */
+    decide(promptId: string, decision: CaptureDecision): Promise<CaptureResult>;
+}
+interface FillSetupState {
+    /** `on`/`signed_out`/`loading` draw nothing; `off` draws the card. */
+    status: "loading" | "on" | "off" | "signed_out";
+    /** How this person can confirm it's them. null = not read yet (password is offered meanwhile). */
+    methods: {
+        password: boolean;
+        passkey: boolean;
+    } | null;
+    /** The web page that approves this browser with a passkey, and the code it shows. null = not ready. */
+    passkey: {
+        url: string;
+        code: string;
+    } | null;
+    /** The person went to approve with a passkey (outlives a remount of the card). */
+    awaitingPasskey: boolean;
+}
+type FillSetupResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "sign_in_required" | "not_approved" | "failed";
+    message?: string;
+};
+interface FillSetupHost extends HostStore<FillSetupState> {
+    /** The password travels once, straight from the box to the host; the package keeps no copy. */
+    turnOnWithPassword(password: string): Promise<FillSetupResult>;
+    /** Opens the passkey approval page (the host's own outbound door) and marks `awaitingPasskey`. */
+    openPasskey(): void;
+    /** Claims a passkey approval made on the web page. */
+    finishPasskey(): Promise<FillSetupResult>;
+}
+/** One set of new-password boxes on the page (one form in one frame). */
+interface NewPasswordTarget {
+    id: string;
+    /** Where the boxes are (`https://github.com`). */
+    origin: string;
+    /** How many boxes it fills (a password and its confirmation = 2). */
+    fieldCount: number;
+    /** true when the boxes are in the page itself, not an embedded frame. */
+    topFrame: boolean;
+}
+type NewPasswordFind = {
+    status: "ready";
+    targets: readonly NewPasswordTarget[];
+} | {
+    status: "none" | "stale" | "unavailable" | "unsafe";
+};
+type NewPasswordFillOutcome = "filled" | "partial" | "stale" | "unavailable" | "refused";
+interface NewPasswordFieldsHost {
+    /** Finds new-password boxes on the page. */
+    find(): Promise<NewPasswordFind>;
+    /** Puts `value` into one target's boxes. The other targets are dropped by the host. */
+    use(targetId: string, value: string): Promise<NewPasswordFillOutcome>;
+}
+
+/** A metadata-only change to one field. The value never travels here. Absent = unchanged. */
+interface FieldSettingsPatch {
+    /** Sealing is permanent: the server refuses any change away from `sealed`. */
+    handling?: FieldHandling;
+    /** null removes the env key. */
+    envKey?: string | null;
+    injectIntoSandbox?: boolean;
+    editable?: boolean;
+    /** "" clears it. */
+    description?: string;
+    active?: boolean;
+}
+/** Item-level settings that are not part of editing the item's content. Absent = unchanged. */
+interface ItemSettingsPatch {
+    uriMatchMode?: UriMatchMode;
+    browserFillEnabled?: boolean;
+    /** The complete list of websites (used to add a promoted address). */
+    loginUrls?: string[];
+}
+interface NewFieldInput {
+    key: string;
+    value: string;
+    handling: FieldHandling;
+    envKey?: string | null;
+    injectIntoSandbox?: boolean;
+    description?: string;
+}
+/** The server's advisory look at a website. It never decides whether an item may be saved. */
+interface DestinationResult {
+    normalizedUrl: string;
+    state: "reachable" | "not_found" | "responded" | "unreachable" | "invalid";
+    httpStatus: number | null;
+}
+/**
+ * Per-field and per-item settings: handling, sealing, env key, sandbox, description, active,
+ * values for recovery codes, website matching and browser fill. Every write answers with the item
+ * as the server now has it, so the screen never guesses.
+ */
+interface FieldsPort {
+    updateField(item: VaultItem, fieldId: string, patch: FieldSettingsPatch): Promise<VaultItem>;
+    /** Replaces one field's value (recovery codes after "Mark used", a replaced set). */
+    setValue(item: VaultItem, fieldId: string, value: string): Promise<VaultItem>;
+    addField(item: VaultItem, input: NewFieldInput): Promise<VaultItem>;
+    removeField(item: VaultItem, fieldId: string): Promise<VaultItem>;
+    /** Replaces several values at once, by field key, as one change (the server's rotate). */
+    rotate(item: VaultItem, values: Record<string, string>): Promise<VaultItem>;
+    updateItem(item: VaultItem, patch: ItemSettingsPatch): Promise<VaultItem>;
+    /** `item` decides the organization the check runs under; omit for the signed-in context. */
+    checkDestination(url: string, item?: VaultItem): Promise<DestinationResult>;
+}
+
+/** What the server will take from a passkey exchange file. */
+interface NativeImportLimits {
+    maxFileBytes: number;
+    maxItems: number;
+}
+
+/**
+ * The desktop shell's passkey-file importer, as the web layer sees it. Only the desktop shell can
+ * open the file chooser, parse the exchange file and hold the keys; it talks to the server itself
+ * (`account.importPasskey`). The panel only ever receives counts and titles — never a value.
+ */
+type NativeImportRequest = {
+    action: "begin_file_import";
+    organization_id: string;
+} | {
+    action: "recover";
+} | {
+    action: "status" | "cancel";
+    operation_id: string;
+} | {
+    action: "preview";
+    operation_id: string;
+    offset: number;
+} | {
+    action: "choose_scope";
+    operation_id: string;
+    organization_id: string;
+} | {
+    action: "confirm";
+    operation_id: string;
+    preview_digest: string;
+};
+type NativeImportPhase = "authorizing" | "preview" | "awaiting_confirmation" | "importing" | "partial" | "completed" | "cancelled" | "failed" | "unavailable";
+type NativeImportDisposition = "eligible" | "unsupported" | "committed" | "failed" | "uncertain" | "not_attempted";
+interface NativeImportStatus {
+    operation_id: string;
+    phase: NativeImportPhase;
+    total: number;
+    committed: number;
+    already_present: number;
+    unsupported: number;
+    failed: number;
+    uncertain: number;
+    not_attempted: number;
+    message: string;
+}
+interface NativeImportPreview {
+    operation_id: string;
+    preview_digest: string;
+    offset: number;
+    total: number;
+    slots: {
+        slot_id: string;
+        title: string | null;
+        disposition: NativeImportDisposition;
+        reason: string | null;
+    }[];
+}
+/** What the desktop shell supplies (Tauri `native_vault_file_import`). */
+interface NativeImportBridge {
+    request(request: NativeImportRequest): Promise<NativeImportStatus | NativeImportPreview>;
+    /** Fires when the signed-in account or organization changes under a running import. Returns the unsubscribe. */
+    subscribe?(listener: () => void): () => void;
+}
+
+/**
+ * THE organization settings the vault obeys (`vault.generator.*`, `vault.import.*`): every limit is
+ * a knob an organization sets, never a number in this package. Hosts build it once over their own
+ * Supabase client; one round trip, then lookups.
+ */
+type VaultKnobs = () => Promise<Readonly<Record<string, unknown>>>;
+declare function createVaultKnobs(client: KnobClient, address: {
+    organizationId: string;
+    userId: string;
+}): VaultKnobs;
+
+/** Bringing items in and taking them out: imports, login CSV export, encrypted backup and restore. */
+
+/** The formats the server writes a login CSV in. */
+type LoginCsvProfile = account.VaultLoginCsvPreviewRequest["profile"];
+type LoginCsvPreview = account.VaultLoginCsvPreviewResponse;
+type BackupPreview = account.VaultBackupDownloadPreview;
+type RestorePreview = account.VaultBackupRestorePreview;
+type RestoreResult$1 = account.VaultBackupRestoreResult;
+/** What the server created for one imported record. */
+interface CreatedItem {
+    id: string;
+    name: string;
+}
+interface IoPort {
+    /** One imported record. The key makes a retry safe: the server answers a repeat with the first result. */
+    createImported(body: account.VaultItemCreateRequest, organizationId: string | null, idempotencyKey: string): Promise<CreatedItem>;
+    /** `KEY=value` text: one item per key; an existing key is updated in place. */
+    importEnv(envText: string, organizationId: string | null, injectIntoSandbox: boolean): Promise<CreatedItem[]>;
+    previewLoginCsv(profile: LoginCsvProfile, itemIds: readonly string[]): Promise<LoginCsvPreview>;
+    /** The CSV text. `revision` ties it to the preview the person just read. */
+    downloadLoginCsv(profile: LoginCsvProfile, itemIds: readonly string[], revision: string): Promise<string>;
+    previewBackup(itemIds: readonly string[]): Promise<BackupPreview>;
+    /** The encrypted backup file's bytes. */
+    downloadBackup(args: {
+        itemIds: readonly string[];
+        revision: string;
+        passphrase: string;
+        acceptOmissions: boolean;
+    }): Promise<Uint8Array<ArrayBuffer>>;
+    previewRestore(envelopeBase64: string, passphrase: string): Promise<RestorePreview>;
+    restoreBackup(args: {
+        envelopeBase64: string;
+        passphrase: string;
+        preview: RestorePreview;
+        restoreRunId: string;
+        acceptOmissions: boolean;
+    }): Promise<RestoreResult$1>;
+}
+
+/** What a restore brought back. The item returns disabled: sharing and automatic use stay off. */
+interface RestoreResult {
+    item: VaultItem;
+    restoredFields: number;
+    restoredAttachments: number;
+    restoredPasskeys: number;
+    alreadyRestored: boolean;
+}
+/** Why a trashed item can't be brought back automatically. */
+type RecoveryRefusal = "recovery_tracking_unavailable" | "recovery_manifest_unsupported" | "protected_component_requires_native_recovery" | "linked_component_requires_native_recovery" | "native_recovery_unavailable" | "native_components_missing" | "native_components_conflict" | "native_manifest_invalid";
+/** What a restore would bring back. Counts only — the server never returns a value here. */
+type RecoveryPreview = {
+    supported: true;
+    deletionId: string;
+    fields: number;
+    attachments: number;
+    passkeys: 0 | 1;
+    priorWasDisabled: boolean;
+} | {
+    supported: false;
+    deletionId: string | null;
+    reason: RecoveryRefusal;
+    priorWasDisabled: boolean | null;
+};
+/** Favorites: the person's own star, across every host. */
+interface FavoritesPort {
+    list(): Promise<string[]>;
+    set(itemId: string, on: boolean): Promise<void>;
+}
+/** Recently opened: newest first. */
+interface RecentsPort {
+    list(): Promise<string[]>;
+    record(itemId: string): Promise<void>;
+}
+/**
+ * The per-person state door (`platform.user_entity_state` through the public `ues_*` functions):
+ * anything with a supabase-js style `rpc`. The server API has no endpoint for it (see FEATURE.md),
+ * so the HOST supplies it; without it `favorites` and `recents` are absent and their controls hide.
+ */
+interface VaultUserStateDoor {
+    rpc(fn: string, args?: Record<string, unknown>): PromiseLike<{
+        data?: unknown;
+        error?: {
+            message?: string;
+        } | null;
+    }>;
+}
+/** List-level state: trash and restore, favorites, recently opened. */
+interface ListsPort {
+    /** Brings a trashed item back (disabled). `deletionId` is the one the preview named; without it the port asks again. May reject with a recent-sign-in refusal. */
+    restore(item: VaultItem, deletionId?: string): Promise<RestoreResult>;
+    /** What a restore would bring back, before anything changes. Absent when the host gives no state door. */
+    preview?(item: VaultItem): Promise<RecoveryPreview>;
+    favorites?: FavoritesPort;
+    recents?: RecentsPort;
+    /** Everything of the vault's in Trash. The server's vault list leaves deleted items out, so this is the only way to see them. */
+    trash?: {
+        list(): Promise<VaultItem[]>;
+    };
+}
+
+/**
+ * What a person or an organization vault may do with a shared item — the server's two grant
+ * levels (`can_use`, `can_manage`). "use": sign in with it (and its agents), see the visible
+ * fields, never show the password. "edit": also show and change values. Only the owner (or an
+ * organization admin for an organization item) shares, moves or deletes — no grant gives that.
+ */
+type ShareLevel = "use" | "edit";
+/** One entry on an item's access list: a person, or an organization vault it is shared into. */
+interface ShareGrant {
+    id: string;
+    kind: "person" | "organization";
+    /** The person's email, or the organization's name. */
+    label: string;
+    userId: string | null;
+    organizationId: string | null;
+    level: ShareLevel;
+    createdAt: string;
+}
+/** A member's own access to an organization's vault. `null` follows the organization default. */
+type MemberVaultAccess = "none" | "use" | "editor";
+type EffectiveVaultAccess = MemberVaultAccess | "admin";
+interface MemberAccessRow {
+    userId: string;
+    email: string;
+    role: string;
+    access: MemberVaultAccess | null;
+    effective: EffectiveVaultAccess;
+}
+interface MemberAccessList {
+    organizationId: string;
+    defaultAccess: MemberVaultAccess;
+    members: MemberAccessRow[];
+}
+/** Where an item can move or be copied to: a person's own vault (null) or one of their organizations. */
+type VaultDestination = string | null;
+interface MoveOutcome {
+    /** The item as the server has it now, in its new vault. */
+    item: VaultItem;
+    /** Field keys the server retired instead of moving (the one-time-password seed). */
+    notMoved: string[];
+}
+interface GiveOutcome {
+    recipientEmail: string;
+    notMoved: string[];
+}
+interface AssignInput {
+    recipientEmail: string;
+    definition: VaultDefinition;
+    draft: ItemDraft;
+    /** The server generates this field's value and never returns it (the creator never sees it). */
+    generateFieldKey: string | null;
+}
+interface AssignOutcome {
+    id: string;
+    name: string;
+    recipientEmail: string;
+    generated: boolean;
+}
+/** A protected field the server would let this sender include in a secure link. */
+interface SecureLinkField {
+    key: string;
+    label: string;
+    available: boolean;
+    /** Why it cannot go (sealed, no reveal right…), in the server's words. */
+    reason: string | null;
+}
+/** What a secure link for this item could carry and how long its two halves live (organization knob). */
+interface SecureLinkOptions {
+    fields: SecureLinkField[];
+    linkMinutes: number;
+    codeMinutes: number;
+}
+type SecureChannel = "email" | "sms";
+interface SecureLinkInput {
+    email: string;
+    /** Their mobile, for the code. Without it the link and the code both go by email. */
+    phone: string | null;
+    name: string | null;
+    fieldKeys: readonly string[];
+    /** Which channel carries the link when both are given; the code takes the other. */
+    linkBy: SecureChannel | null;
+    note: string | null;
+}
+/** The server's receipt. Never the link and never a value: the link goes only to the recipient. */
+interface SecureLinkReceipt {
+    id: string;
+    linkBy: SecureChannel;
+    codeBy: SecureChannel;
+    sameChannel: boolean;
+    expiresAt: string;
+    fieldKeys: string[];
+    sentence: string;
+}
+type SecureLinkStatus = "pending" | "viewed" | "revoked" | "expired" | "undeliverable" | "locked";
+/** One link this person sent for this item (their own rows only). */
+interface SentSecureLink {
+    id: string;
+    name: string | null;
+    email: string | null;
+    phone: string | null;
+    linkBy: string;
+    codeBy: string;
+    fieldKeys: string[];
+    status: SecureLinkStatus | string;
+    createdAt: string;
+    expiresAt: string;
+    viewedAt: string | null;
+}
+/** Who can use an item: grants, organization access, member access, move, give ownership, assign, copy. */
+interface SharingPort {
+    /** The item's current access list. Needs manage; load it before any change so nobody is dropped unseen. */
+    grants(item: VaultItem): Promise<ShareGrant[]>;
+    /** Share with ONE person by their exact email (the account must exist). Nobody else changes. */
+    addPerson(item: VaultItem, email: string, level: ShareLevel): Promise<ShareGrant>;
+    /** Share a personal item into one of the owner's organizations. It then lives in both vaults. */
+    addOrganization(item: VaultItem, organizationId: string, level: ShareLevel): Promise<ShareGrant>;
+    setLevel(item: VaultItem, grant: ShareGrant, level: ShareLevel): Promise<ShareGrant>;
+    revoke(item: VaultItem, grant: ShareGrant): Promise<void>;
+    /**
+     * An organization item's mode: every member (at their own vault access) or only the people listed.
+     * `all_members` clears every person on the list (server rule); `restricted` keeps `people`.
+     */
+    setAccessMode(item: VaultItem, mode: "all_members" | "restricted", people: readonly ShareGrant[]): Promise<VaultItem>;
+    /** Every member's access to an organization's vault. Owners and admins only. */
+    memberAccess(organizationId: string): Promise<MemberAccessList>;
+    setMemberAccess(organizationId: string, userId: string, access: MemberVaultAccess | null): Promise<EffectiveVaultAccess>;
+    /** Move between the person's own vault and their organizations' vaults. Values are not copied. */
+    move(item: VaultItem, to: VaultDestination): Promise<MoveOutcome>;
+    /** Hand the item to another person. The sender loses all access; every share is removed. */
+    giveOwnership(item: VaultItem, email: string): Promise<GiveOutcome>;
+    /** An independent copy whose values can diverge. Needs edit on the item. */
+    copy(item: VaultItem, to: VaultDestination): Promise<VaultItem>;
+    /** Create a NEW item already owned by someone else (the new-item flow's "For someone else"). */
+    assign(input: AssignInput): Promise<AssignOutcome>;
+    /** Send by secure link: which protected fields may go, and the link's lifetimes. */
+    secureLinkOptions(item: VaultItem): Promise<SecureLinkOptions>;
+    /** Seals the chosen fields and sends the link to the recipient. May reject with a recent-sign-in refusal. */
+    sendSecureLink(item: VaultItem, input: SecureLinkInput): Promise<SecureLinkReceipt>;
+    /** Turns a pending link off at once; what it carried is deleted. Returns the server's sentence. */
+    revokeSecureLink(item: VaultItem, deliveryId: string): Promise<string>;
+    /** The links this person sent for the item. Present only when the host passes its database door. */
+    sentSecureLinks?: (item: VaultItem) => Promise<SentSecureLink[]>;
+    /** The texting-consented mobile on file for an existing user with this email, else null. Same door. */
+    phoneOnFile?: (email: string) => Promise<string | null>;
+}
+
+/** A one-time-password reading: the code and where it sits in its period. */
+interface TotpReading {
+    code: string;
+    periodSeconds: number;
+    remainingSeconds: number;
+}
+/** A save that landed. `notice` is set when part of it did not (e.g. the one-time password was refused). */
+interface SaveResult {
+    item: VaultItem;
+    notice: string | null;
+}
+interface VaultSnapshot {
+    /** Parts that could not be read this time (an organization, shared items, one-time codes). */
+    unavailable: readonly string[];
+    items: readonly VaultItem[];
+    /** Items in the trash (deleted, still recoverable). Never mixed into `items`. */
+    deleted: readonly VaultItem[];
+    organizations: readonly VaultOrganizationRef[];
+    definitions: readonly VaultDefinition[];
+}
+/**
+ * The data seam. `createApiVaultPort` (this package) implements it over `@ai-matrx/api` for every
+ * host — web app, extension, desktop — so there is ONE client. Every method may reject; the screens
+ * show the failure and never swallow it. Each feature area owns its own slice (`authenticator`,
+ * `sharing`, …) in its own folder.
+ */
+interface VaultPort {
+    load(): Promise<VaultSnapshot>;
+    /** The one path to a plaintext value. Audited by the server; handling `sealed` always refuses. */
+    reveal(item: VaultItem, fieldKey: string): Promise<string>;
+    /** `organizationId` null = the person's own vault. */
+    create(definition: VaultDefinition, organizationId: string | null, draft: ItemDraft): Promise<SaveResult>;
+    /** Applies the draft's changes; returns the item as the server now has it. */
+    save(item: VaultItem, definition: VaultDefinition | null, draft: ItemDraft): Promise<SaveResult>;
+    remove(item: VaultItem): Promise<void>;
+    /** The item as the server has it now. */
+    get(item: VaultItem): Promise<VaultItem>;
+    authenticator: AuthenticatorPort;
+    sharing: SharingPort;
+    activity: ActivityPort;
+    io: IoPort;
+    fields: FieldsPort;
+    lists: ListsPort;
+    devices: DevicesPort;
+    /** Desktop passkey import: the server's limits (and proof the organization may import). */
+    native: {
+        limits(organizationId: string): Promise<NativeImportLimits>;
+    };
+}
+/**
+ * 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).
+ */
+interface VaultHostCapabilities {
+    identity?: VaultIdentity;
+    /** The organization's vault settings (`createVaultKnobs`): generator and import limits. Without it neither is offered. */
+    knobs?: VaultKnobs;
+    /** Extension: the tab beside the panel, its matches and state (`extension/host.ts`). */
+    page?: ExtensionPage;
+    fill?: ExtensionFill;
+    /** Extension: the save-this-login prompt after a sign-in. */
+    capture?: CaptureHost;
+    /** Extension: whether filling is turned on in this browser, and turning it on. */
+    fillSetup?: FillSetupHost;
+    /** Extension: new-password boxes on the page, for the generator's "Fill page". */
+    newPasswordFields?: NewPasswordFieldsHost;
+    /** Desktop: the native passkey importer (file chooser, parsing and keys stay native). */
+    nativeImport?: NativeImportBridge;
+    openUrl?: (url: string) => void;
+    nativeProvider?: {
+        status: "ready" | "needs_setup" | "unavailable";
+        openSetup: () => void;
+    };
+}
+
+type VaultLayout = "auto" | "full" | "split" | "stack";
+interface VaultAppProps {
+    port: VaultPort;
+    host?: VaultHostCapabilities;
+    /** `auto` picks by the room the workspace is given: a side panel stacks, a window shows three panes. */
+    layout?: VaultLayout;
+    /**
+     * Everything the address carries: vault, view, search, sort, the open item, edit/new, the new-item
+     * address, the open panel. Controlled when given (the host writes it to the URL); the workspace
+     * keeps its own copy when not. `push` = a step the Back button should undo; `replace` = typing.
+     */
+    location?: VaultLocation;
+    onLocationChange?: (next: VaultLocation, how: "push" | "replace") => void;
+    /** The host's own toasts; without it the vault shows its own short notices. */
+    notify?: Notify;
+}
+/** 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;
+
+interface SharingPortOptions {
+    /**
+     * The host's database door on the `platform` schema (`supabase.schema("platform")`). It is the only
+     * way to read the links a person sent (`secure_delivery_sent`, their own rows) and the recipient's
+     * texting-consented mobile (`secure_delivery_recipient_phone`); the API has no route for either.
+     * Without it the "Sent" list and the mobile pre-fill are absent; sending and turning off still work.
+     */
+    platformDoor?: VaultUserStateDoor;
+}
+
+/**
+ * THE vault client for every host: a VaultPort over the generated `@ai-matrx/api`. The web app, the
+ * extension and the desktop app hand it their own `Api` (their own sign-in and organization) and get
+ * identical behaviour; none of them keeps a hand-written vault client.
+ */
+
+interface ApiVaultPortOptions {
+    /** Overrides the organizations the vault lists (default: the signed-in person's own). */
+    organizations?: readonly VaultOrganizationRef[];
+    /** The host's per-person state door (its supabase client): turns on Favorites and Recently opened. */
+    userState?: VaultUserStateDoor;
+    /** The host's `supabase.schema("platform")`: turns on "Sent links" and the recipient's mobile in Send. */
+    platformDoor?: SharingPortOptions["platformDoor"];
+    /** The host's `supabase.auth`: turns on approving a browser with a passkey. */
+    passkeys?: PasskeyAuthLike;
+}
+declare function createApiVaultPort(api: Api, options?: ApiVaultPortOptions): VaultPort;
+
+/** Reads the organization's ceilings. Raw knob values are fine: they are validated here. */
+type GeneratorLimitsSource = () => Promise<{
+    maxPasswordLength?: unknown;
+    maxPassphraseWords?: unknown;
+} | null>;
+/**
+ * An icon button beside a secret field that opens the generator. "Use" hands the value back and
+ * closes it; closing without using drops the value.
+ */
+declare function GenerateButton({ onUse, label, limits, disabled }: {
+    onUse: (value: string) => void;
+    label?: string;
+    limits?: GeneratorLimitsSource;
+    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 };