@chance722/dsh-inbox 0.1.0

package/lib/types/host/vault/vault.d.ts

@@ -0,0 +1,269 @@
+/**
+ * The vault facade: one open domain plus the operations the tools and the panel
+ * need. Callers never touch the storage backend directly.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Category, CategorySource, Kind, Source } from '../../shared/vocabulary.js';
+import { type ItemQuery } from './query.js';
+/** A capture that needs the key while the vault is locked. */
+export declare class VaultLockedError extends Error {
+    constructor();
+}
+import { type Attachment, type Item, type VaultGlobal } from './spec.js';
+/** Everything a caller supplies when filing something new. */
+export interface NewItem {
+    kind: Kind;
+    category: Category;
+    /** Defaults to `rule`: the vault files by rule unless told otherwise. */
+    categorySource?: CategorySource;
+    source: Source;
+    title?: string;
+    /** A headline fetched from the link's own page; see `link-title.ts`. */
+    linkTitle?: string;
+    /** A short code explaining a missed headline fetch (see `link-title.ts`). */
+    linkTitleError?: string;
+    text?: string;
+    /** A sealed credential body, from `sealSecret` (never both with `text`). */
+    secret?: string;
+    /** The keyed digest that matches a re-paste of the same credential. */
+    secretDigest?: string;
+    url?: string;
+    platform?: string;
+    note?: string;
+    tags?: readonly string[];
+    attachmentIds?: readonly string[];
+}
+/** Fields a later edit may replace. Classification and the note are the point. */
+export interface ItemPatch {
+    category?: Category;
+    /** Set to `user` when the person editing is the one choosing the category. */
+    categorySource?: CategorySource;
+    watchLater?: boolean;
+    title?: string;
+    linkTitle?: string;
+    /** A short code explaining a missed headline fetch; empty string clears it. */
+    linkTitleError?: string;
+    note?: string;
+    platform?: string;
+    tags?: readonly string[];
+    attachmentIds?: readonly string[];
+}
+/** Where the vault's key state stands, for the panel to show and the tools to check. */
+export interface VaultLockState {
+    /** A master password exists, so credentials can be sealed at all. */
+    configured: boolean;
+    /** The key is in memory: credentials can be read and written. */
+    unlocked: boolean;
+}
+export declare class Vault {
+    private readonly ctx;
+    private readonly domain;
+    /** Absolute path of the domain's unit directory, for diagnostics. */
+    readonly unit: string;
+    private closed;
+    /**
+     * The derived key, **memory only**.
+     *
+     * Nothing on disk can be used to read a credential: the master password is
+     * never stored, the key is never stored, and a restart therefore locks the
+     * vault again. That is the trade the red line asks for ("主密码永不上传"),
+     * and it is why the panel has an explicit unlock.
+     */
+    private key?;
+    private constructor();
+    /**
+     * Open the vault's domain over whatever backend the composition routed it to.
+     *
+     * @param ctx - host context carrying the storage domain facility.
+     * @param unit - unit location, recorded for diagnostics only.
+     * @returns the open vault.
+     */
+    static open(ctx: Context, unit?: string): Promise<Vault>;
+    /**
+     * Bring records written by version 1/2 into the version-3 shape: strip the
+     * `待看` tag, because the flag now says the same thing.
+     *
+     * The old read/unread pair is **not** converted, on purpose. 待看 is the
+     * user's own mark, and back-filling it would have flagged twelve records on
+     * their behalf at first launch.
+     *
+     * (A note for whoever reads this next: you cannot even see the old `status`
+     * from here. The domain validates on read and zod drops unknown keys, so by
+     * the time a record reaches this loop the field is gone — measured, after the
+     * first version of this migration silently converted nothing and the rail
+     * read 「待看 0」.)
+     */
+    private migrateOnce;
+    private get items();
+    private get attachments();
+    /** Where the key state stands; what the panel shows and the tools consult. */
+    get lockState(): VaultLockState;
+    /**
+     * Set (or replace) the master password, and seal everything that needs it.
+     *
+     * Replacing it is allowed on purpose: a user who wrote the password down
+     * badly, or wants a stronger one, must be able to fix that. Records sealed
+     * with the *old* password are re-sealed with the new key, which is why the
+     * old password has to be supplied again in the panel.
+     *
+     * @param password - the new master password, never stored anywhere.
+     * @returns how many records were sealed in the process.
+     */
+    setMasterPassword(password: string): Promise<number>;
+    /**
+     * Derive the key from the stored salt and check it against the verifier.
+     *
+     * @param password - what the user typed.
+     * @returns true when the vault is now unlocked.
+     */
+    unlock(password: string): Promise<boolean>;
+    /** Drop the key. Credentials stay on disk, unreadable until the next unlock. */
+    lock(): void;
+    /**
+     * Seal one credential body for storage.
+     *
+     * @param plaintext - the credential as the user pasted it.
+     * @returns the envelope to store, and the keyed digest used for de-duplication.
+     */
+    sealSecret(plaintext: string): {
+        secret: string;
+        secretDigest: string;
+    };
+    /**
+     * The plaintext behind a credential, when it can be read.
+     *
+     * @param item - the record.
+     * @returns the plaintext, or undefined while locked.
+     */
+    secretText(item: Item): string | undefined;
+    /**
+     * The keyed digest a re-paste is matched against (see `spec.ts`).
+     *
+     * @param plaintext - the credential as pasted.
+     * @returns a hex digest, stable for one vault and useless without its key.
+     */
+    digestOf(plaintext: string): string;
+    /**
+     * Move credentials that are still sitting in `text` into the sealed field.
+     *
+     * Version-5 vaults kept a credential's body in plain text — that is what this
+     * whole change is about — so the first unlock rewrites them. A record that is
+     * not a `secret` is left alone, even if it looks like one: the category is the
+     * user's own statement about what a record is.
+     *
+     * @returns how many records were sealed.
+     */
+    private sealLegacySecrets;
+    /**
+     * Re-seal everything that was sealed with the previous key.
+     *
+     * @param previous - the key in use until a moment ago, if there was one.
+     * @returns how many records were re-sealed.
+     */
+    private resealSecrets;
+    /** Total records held, including soft-deleted ones. */
+    get size(): number;
+    /**
+     * File a new item.
+     *
+     * @param input - the caller-owned fields; id and timestamps are assigned here.
+     * @returns the stored record.
+     */
+    create(input: NewItem): Promise<Item>;
+    /** Read one live or soft-deleted record. */
+    get(id: string): Item | undefined;
+    /** Records sitting in the recycle bin, newest first. */
+    getBin(): Item[];
+    /**
+     * List records matching a query, newest first.
+     *
+     * @param query - filters and paging.
+     * @returns matching records.
+     */
+    list(query?: ItemQuery): Item[];
+    /**
+     * Replace editable fields. The atomic read-modify-write keeps concurrent
+     * edits from interleaving on the domain's write chain.
+     *
+     * @param id - record key.
+     * @param patch - fields to replace.
+     * @returns the stored record.
+     */
+    patch(id: string, patch: ItemPatch): Promise<Item>;
+    /** Flag or unflag a record for later. */
+    setWatchLater(id: string, on?: boolean): Promise<Item>;
+    /**
+     * Strip one tag from every record that carries it.
+     *
+     * A tag is not an entity here — it is a word on a record — so "delete this
+     * tag" can only mean "take this word off everything". Returns how many
+     * records changed, so the panel can say so instead of guessing.
+     *
+     * @param tag - the exact tag to remove.
+     * @returns the number of records that carried it.
+     */
+    removeTag(tag: string): Promise<number>;
+    /**
+     * Soft delete: the record stops appearing in lists but keeps its bytes, so the
+     * recycle bin (and restoring) needs no second table.
+     */
+    softDelete(id: string): Promise<Item>;
+    /** Undo a soft delete. */
+    restore(id: string): Promise<Item>;
+    /**
+     * Delete one record for good, together with its attachment rows.
+     *
+     * The bytes behind an attachment live in dsh's own store, which never deletes
+     * automatically — emptying the recycle bin drops our references, not their
+     * objects. A row another record still references is left alone.
+     *
+     * @param id - record key.
+     * @returns whether the record existed.
+     */
+    remove(id: string): Promise<boolean>;
+    /**
+     * Record an attachment's metadata. The bytes stay in the store named by
+     * `storeId`; this row is our own index over them, keyed by a generated id
+     * because store ids are not path-safe.
+     */
+    addAttachment(input: Omit<Attachment, 'id' | 'createdAt'> & {
+        createdAt?: string;
+    }): Promise<Attachment>;
+    /** Read one attachment record. */
+    getAttachment(id: string): Attachment | undefined;
+    /** Find our index row for a store-side attachment id, if we have one. */
+    findAttachmentByStoreId(storeId: string): Attachment | undefined;
+    /** Current sync state; M6 writes it. */
+    get global(): VaultGlobal;
+    /** Replace the global slot. */
+    setGlobal(value: VaultGlobal): Promise<void>;
+    /** Record today's model-fallback spend. */
+    setModelSpend(spend: NonNullable<VaultGlobal['model']>, last?: string): Promise<void>;
+    /** Record where the last WebDAV pull got to. */
+    setSync(sync: VaultGlobal['sync']): Promise<void>;
+    /**
+     * Write a record exactly as another device had it.
+     *
+     * The merge's only write, and deliberately not `create`: an imported record
+     * keeps the id other devices already know, the `createdAt` it was made with and
+     * the `updatedAt` the conflict was settled on. Re-stamping any of them would
+     * make the next pull decide the other way and bounce the record back and forth.
+     *
+     * @param item - the record, already validated by the merge's own parse.
+     * @returns the stored record.
+     */
+    import(item: Item): Promise<Item>;
+    /**
+     * The same for one attachment's row.
+     *
+     * `storeId` is the *local* store's id for the bytes the merge just admitted;
+     * everything else — our row id in particular — travels with the object so the
+     * record's `attachmentIds` still point at something.
+     *
+     * @param record - the row, with a local `storeId`.
+     * @returns the stored row.
+     */
+    importAttachment(record: Attachment): Promise<Attachment>;
+    /** Release the domain handle. Idempotent. */
+    close(): Promise<void>;
+}

package/lib/types/host/webdav/client.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The smallest WebDAV surface the inbox needs: list one folder, read one file.
+ *
+ * No dependency and no XML library: a `PROPFIND` answer is read with two small
+ * expressions over the response blocks, because the alternative (a full parser)
+ * buys nothing for the two fields we actually use.
+ *
+ * `fetch` is injected so the whole thing is testable without a server, and the
+ * caller never sees bytes it did not ask for.
+ */
+/** Basic-auth credentials, when the server is not anonymous. */
+export interface WebdavAuth {
+    username: string;
+    password: string;
+}
+/** One file found in a remote folder. */
+export interface RemoteFile {
+    /** Absolute path on the server, as the `href` reported it. */
+    path: string;
+    /** `getlastmodified`, when the server sent one. */
+    lastModified?: string;
+    /** `getcontenttype`, when the server sent one. */
+    contentType?: string;
+}
+/** The subset of `fetch` this module uses, so tests can stand in for it. */
+export interface FetchResponseLike {
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    headers?: {
+        get(name: string): string | null;
+    };
+}
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<FetchResponseLike>;
+/** Everything the client needs besides the URL. */
+export interface WebdavDeps {
+    fetch: FetchLike;
+    auth?: WebdavAuth;
+    /** What to send as `User-Agent`; empty falls back to the plugin's own. */
+    userAgent?: string;
+}
+/** Basic auth header, or nothing for an anonymous server. */
+export declare function authHeaders(auth?: WebdavAuth): Record<string, string>;
+/**
+ * The identity this request presents.
+ *
+ * Same header, same reason as the S3 side: 数据胶囊 answers a request that
+ * does not claim to be the application its access key is bound to with
+ * `403 Client type mismatch.`, and nothing in the status code hints at it.
+ *
+ * @param deps - the client's dependencies.
+ * @returns the header to send.
+ */
+export declare function userAgentHeaders(deps: WebdavDeps): Record<string, string>;
+/** One joined URL that keeps the base path the user configured. */
+export declare function joinUrl(base: string, part: string): string;
+/**
+ * Write one file.
+ *
+ * WebDAV needs none of the S3 ceremony — a `PUT` with the bytes and the auth
+ * header is the whole protocol — which is exactly why the push path can share
+ * one interface with the S3 client (`remote/write.ts`).
+ *
+ * @param baseUrl - the configured base.
+ * @param path - the file's path under it.
+ * @param bytes - what to store.
+ * @param deps - fetch, credentials and the identity to present.
+ * @param contentType - what the bytes are.
+ */
+export declare function writeFile(baseUrl: string, path: string, bytes: Uint8Array, deps: WebdavDeps, contentType?: string): Promise<void>;
+/**
+ * Remove one file.
+ *
+ * A 404 counts as success: the object the caller wanted gone is gone. Anything
+ * else 4xx/5xx is reported with the server's own words, because a read-only
+ * share is a real answer and "删除失败" alone would hide it.
+ *
+ * @param baseUrl - the configured base.
+ * @param path - the file's path under it.
+ * @param deps - fetch, credentials and the identity to present.
+ */
+export declare function deleteFile(baseUrl: string, path: string, deps: WebdavDeps): Promise<void>;
+/**
+ * Read one `PROPFIND` answer into files, skipping the folder entries themselves.
+ *
+ * @param xml - the response body.
+ * @param directory - the requested folder, so its own entry can be dropped.
+ * @returns the files the server listed.
+ */
+export declare function parseListing(xml: string, directory: string): RemoteFile[];
+/** List the files directly inside one folder. */
+export declare function listFolder(baseUrl: string, directory: string, deps: WebdavDeps): Promise<RemoteFile[]>;
+/** Fetch one file's bytes, with its content type when the server offers one. */
+export declare function readFile(path: string, deps: WebdavDeps, absoluteUrl?: string): Promise<{
+    bytes: Uint8Array;
+    contentType: string;
+}>;

package/lib/types/host/webdav/config.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Where the WebDAV settings live, and why they live there.
+ *
+ * URL, folder and username are *configuration*: they belong in dsh's settings
+ * service, so a deployment can ship defaults and a user can change them from a
+ * configuration surface. The password is a *secret*: it goes through the
+ * credentials service, which keeps values out of configuration files entirely.
+ *
+ * Both services are optional. Without them the plugin keeps working from its own
+ * composed values — a headless profile has no settings provider and must not
+ * break — and the panel simply says what is missing.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { WebdavSettings, WebdavStatus } from '../../shared/panel-wire.js';
+import type { Vault } from '../vault/vault.js';
+export type { WebdavSettings, WebdavStatus } from '../../shared/panel-wire.js';
+/** Namespace this plugin owns in the settings service. */
+export declare const SETTINGS_NAMESPACE = "dsh-inbox-webdav";
+/** The credential key holding the password. */
+export declare const PASSWORD_KEY = "DSH_INBOX_WEBDAV_PASSWORD";
+/** The credential key holding the S3 secret access key. */
+export declare const S3_SECRET_KEY = "DSH_INBOX_S3_SECRET";
+/** The composed defaults, so a fresh install has a sane shape. */
+export declare const DEFAULT_SETTINGS: WebdavSettings;
+/** The namespace's schema: every field optional, so a partial user layer is valid. */
+export declare const WebdavSettingsSchema: z<Schemastery.ObjectS<{
+    protocol: z<"webdav" | "s3", "webdav" | "s3">;
+    baseUrl: z<string, string>;
+    directory: z<string, string>;
+    username: z<string, string>;
+    endpoint: z<string, string>;
+    bucket: z<string, string>;
+    region: z<string, string>;
+    signatureVersion: z<string, string>;
+    accessKeyId: z<string, string>;
+    userAgent: z<string, string>;
+    webdavUserAgent: z<string, string>;
+}>, Schemastery.ObjectT<{
+    protocol: z<"webdav" | "s3", "webdav" | "s3">;
+    baseUrl: z<string, string>;
+    directory: z<string, string>;
+    username: z<string, string>;
+    endpoint: z<string, string>;
+    bucket: z<string, string>;
+    region: z<string, string>;
+    signatureVersion: z<string, string>;
+    accessKeyId: z<string, string>;
+    userAgent: z<string, string>;
+    webdavUserAgent: z<string, string>;
+}>>;
+/** Resolve the current settings, falling back to the composed defaults. */
+export declare function readSettings(ctx: Context): WebdavSettings;
+/**
+ * Declare the namespace once, at plugin load.
+ *
+ * Registering lazily on the first save looked harmless and was not: before that
+ * first save, `get()` answers undefined for an unregistered namespace, so the
+ * panel loaded *defaults* instead of the stored overrides — and the next save
+ * wrote those defaults back over the user's real values. Declaring up front is
+ * the whole point of a settings namespace.
+ *
+ * @param ctx - host context.
+ * @param base - composed defaults for this deployment.
+ */
+export declare function installWebdavSettings(ctx: Context, base?: WebdavSettings): void;
+/** Read the password, or undefined when none is stored. */
+export declare function readPassword(ctx: Context): Promise<string | undefined>;
+/** Read the S3 secret access key, or undefined when none is stored. */
+export declare function readS3Secret(ctx: Context): Promise<string | undefined>;
+/** Everything the panel needs, without ever handing out the password. */
+export declare function describeWebdav(ctx: Context): Promise<WebdavStatus>;
+/** What a save may change. An absent password leaves the stored one alone. */
+export interface WebdavPatch {
+    protocol?: string;
+    baseUrl?: string;
+    directory?: string;
+    username?: string;
+    /** Empty string clears the stored password; undefined leaves it. */
+    password?: string;
+    endpoint?: string;
+    bucket?: string;
+    region?: string;
+    signatureVersion?: string;
+    accessKeyId?: string;
+    /** Empty string clears the stored S3 secret; undefined leaves it. */
+    accessKeySecret?: string;
+    /**
+     * The `User-Agent` to send for this patch's protocol; empty string means the
+     * plugin's own identity. Lands in the protocol's own slot.
+     */
+    userAgent?: string;
+}
+/**
+ * The client identity configured for whichever protocol is active.
+ *
+ * Two slots, one answer: the identity is bound to the credential, and each
+ * protocol carries its own credential.
+ *
+ * @param settings - the resolved settings.
+ * @returns the `User-Agent` to send, empty when the user configured nothing.
+ */
+export declare function activeUserAgent(settings: WebdavSettings): string;
+/**
+ * Accept what people actually type: a bare host is the normal case, and the
+ * scheme is the part they should not have to remember. An explicit `http://`
+ * survives, because a self-hosted endpoint on a LAN is a real setup.
+ *
+ * @param value - whatever was typed.
+ * @returns the URL to store.
+ */
+export declare function normalizeUrl(value: string): string;
+/**
+ * Persist a configuration change.
+ *
+ * The password never lands in settings: it is written (or cleared) through the
+ * credentials service, and a composition without one refuses the write instead
+ * of quietly storing a secret somewhere else.
+ *
+ * @param ctx - host context.
+ * @param vault - the open vault, used for the "settings unavailable" fallback.
+ * @param base - composed defaults for the settings base layer.
+ * @param patch - what to change.
+ * @returns whether the write went through, and why not when it did not.
+ */
+export declare function saveWebdav(ctx: Context, vault: Vault | undefined, base: WebdavSettings, patch: WebdavPatch): Promise<{
+    ok: boolean;
+    reason?: string;
+}>;

package/lib/types/host/webdav/probe.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The WebDAV self-test: one request that answers "is this channel usable".
+ *
+ * The S3 side needs a matrix because a gateway can refuse four different things
+ * with the same status code. WebDAV does not: a `PROPFIND` on the configured
+ * folder either works (the server answers a listing or a 404 for the path) or it
+ * does not, and the status says which. So this is deliberately one row — the
+ * panel turns it into one sentence.
+ *
+ * Read-only by construction: `PROPFIND` with no body, and nothing else.
+ */
+import type { ProbeRow } from '../../shared/panel-wire.js';
+import { type WebdavDeps } from './client.js';
+/**
+ * Ask the configured folder for its listing.
+ *
+ * @param deps - fetch, credentials and the identity to present.
+ * @param baseUrl - the remote base URL from the settings.
+ * @param directory - the folder inside it, as configured.
+ * @returns one row: what was asked, and what came back.
+ */
+export declare function probeWebdav(deps: WebdavDeps, baseUrl: string, directory: string): Promise<ProbeRow[]>;

package/lib/types/host/webdav/run.d.ts

@@ -0,0 +1,34 @@
+/**
+ * One pull, wired for real: reads the configuration, resolves the password, and
+ * hands the whole thing to the ingest.
+ *
+ * Both callers (startup and the panel's button) go through here, so what the
+ * button does and what a restart does cannot drift apart.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+import type { S3FetchLike } from '../s3/client.js';
+import type { Vault } from '../vault/vault.js';
+import { type PullResult } from '../remote/pull.js';
+import type { FetchLike } from './client.js';
+/** The global fetch, adapted to the client's injected-fetch shape. */
+export declare const webdavFetch: FetchLike;
+/**
+ * The same adapter for the S3 client.
+ *
+ * The body has to be forwarded here, and it *was not* until a real bucket
+ * showed it: every PUT left with an empty payload, the gateway accepted them
+ * all, and the cloud drive filled up with 0-byte objects while the push happily
+ * reported success. A fake fetch in a unit test cannot catch that — it is this
+ * one-line omission that the *adapter* had, not the client.
+ */
+export declare const s3Fetch: S3FetchLike;
+/**
+ * Pull once.
+ *
+ * @param ctx - host context carrying settings and credentials.
+ * @param vault - the open vault.
+ * @param attachments - the store that owns pulled bytes.
+ * @returns the pull's outcome; never throws.
+ */
+export declare function runPull(ctx: Context, vault: Vault, attachments: AttachmentStore | undefined): Promise<PullResult>;

package/lib/types/shared/constants.d.ts

@@ -0,0 +1,23 @@
+/** Stable ids shared by the host half and the browser half. */
+/** npm package name; also the client bundle id the loader registers. */
+export declare const PACKAGE_NAME = "@chance722/dsh-inbox";
+/** Sidebar panel id: addresses both the `sidebar.panellist` row and the `main` key. */
+export declare const PANEL_ID = "inbox";
+/**
+ * The version the plugin reports, substituted from `package.json` at build time.
+ *
+ * The status tool used to print an internal milestone marker instead (`M6c`),
+ * which told the user nothing — and the assistant relays that string verbatim,
+ * so it was also the first thing they saw when they asked what the vault held.
+ * `typeof` keeps a build that forgot the substitution from throwing.
+ */
+export declare const VERSION: string;
+/**
+ * What the plugin calls itself in `User-Agent` when the user configured nothing.
+ *
+ * Some object-storage gateways (中科院数据胶囊 among them) bind an access key to
+ * an application and reject any caller that does not claim to be that
+ * application, which is why this is a visible setting rather than a constant
+ * buried in a client.
+ */
+export declare const DEFAULT_USER_AGENT = "dsh-inbox";