@metalabel/dfos-client 0.29.0

package/dist/types-ByxTj1u-.d.ts

@@ -0,0 +1,324 @@
+import { VerifiedIdentity, VerifiedContentChain } from '@metalabel/dfos-protocol/chain';
+import { VerifiedDFOSCredential, Attenuation } from '@metalabel/dfos-protocol/credentials';
+import { PeerClient } from '@metalabel/dfos-web-relay/peer-client';
+
+/**
+ * The two axes v1 genuinely cannot check:
+ * - `revocation` — non-revocation is never provable (a relay can only attest to
+ *   what it has seen, and can withhold), so a credential's unrevoked status is
+ *   honest absence-of-evidence, not proof.
+ * - `tip` — tip freshness is never PROVEN in v1 (head proofs are v2 /
+ *   `tipProven`). The axis is carried whenever the answer's freshness rests on
+ *   a cached head: either the cache alone (all relays unreachable) or relays'
+ *   empty-delta claim against it (a relay that never saw the cached head reports
+ *   the same empty page as one that is genuinely caught up).
+ */
+type UnverifiableAxis = 'revocation' | 'tip';
+/** Trust is DATA. `ok` = the value verified; `unverifiable` lists honest gaps. */
+interface Trust {
+    ok: boolean;
+    unverifiable?: UnverifiableAxis[];
+}
+/** One relay's answer to a fan-out. `digest` is a content digest for quorum. */
+interface RelayResponse {
+    url: string;
+    ok: boolean;
+    digest: string;
+}
+/** Where an answer came from and whether relays agreed. Stays thin. */
+interface Provenance {
+    answeredBy: string;
+    responses: RelayResponse[];
+    agreed: boolean;
+    fromCache: boolean;
+}
+/** A proven value wrapped in trust + provenance. */
+interface Resolved<T> {
+    value: T;
+    trust: Trust;
+    provenance: Provenance;
+}
+/** No-throw verification outcome. `ok` routes the decision; `error` explains a no. */
+interface VerifyResult<T> {
+    ok: boolean;
+    value?: T;
+    error?: string;
+    unverifiable?: UnverifiableAxis[];
+}
+interface ResolvedContent {
+    chain: VerifiedContentChain;
+    /** The creator identity — resolved as a side effect of key resolution. */
+    creator: VerifiedIdentity;
+    /** The current document blob, when fetched. */
+    document?: DocumentBlob;
+}
+interface ResolvedCredential {
+    credential: VerifiedDFOSCredential;
+    /** The issuer identity, verified. */
+    issuer: VerifiedIdentity;
+    /** Revocation status per the effective revocation checker (see Trust.unverifiable). */
+    revoked: boolean;
+}
+interface DocumentBlob {
+    bytes: Uint8Array;
+    documentCID: string;
+    mediaType?: string;
+    /** The parsed document if it was JSON — the on-wire form relays store. */
+    decoded?: unknown;
+    /** Whether the fetched bytes re-derive to `documentCID` (content-address check). */
+    integrity: boolean;
+}
+/** Discriminated result of the paste-a-string dispatcher. */
+type Resolution = ({
+    kind: 'identity';
+} & Resolved<VerifiedIdentity>) | ({
+    kind: 'content';
+} & Resolved<ResolvedContent>) | ({
+    kind: 'credential';
+} & Resolved<ResolvedCredential>);
+/**
+ * Check whether a credential has been revoked. Default: `() => false` (honest).
+ *
+ * `asOfUnix` is the protocol's revocation as-of basis (see the protocol's
+ * `RevocationChecker`): supplied when folding committed history, so a credential
+ * revoked AFTER an operation was signed does not invalidate it; omitted for live
+ * "is it revoked right now" checks. Omitted **or `<= 0`** means timeless — `0` is
+ * the Go twin's in-band sentinel, so "as of epoch 0" is not expressible there and
+ * must not be expressible here either.
+ */
+type RevChecker = (issuerDID: string, credentialCID: string, asOfUnix?: number) => Promise<boolean>;
+/**
+ * The bound protocol-lib callbacks — spread straight into `verifyContentChain`,
+ * `verifyDFOSCredential`, or any DFOS verifier. This is the trunk product.
+ */
+interface Callbacks {
+    resolveKey: (kid: string) => Promise<Uint8Array>;
+    resolveIdentity: (did: string) => Promise<VerifiedIdentity | undefined>;
+    isRevoked: RevChecker;
+}
+/**
+ * A minimal async key/value cache. Values are JSON-serializable records the
+ * client owns; consumers never construct them. `memoryStore()` is the default;
+ * `indexedDbStore()` (behind `./store`) is the only heavy, browser-only adapter.
+ */
+interface Store {
+    get(key: string): Promise<unknown | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+}
+/** A raw JWS operation from a relay log — cid + token, unverified until folded. */
+interface LogOp {
+    cid: string;
+    jwsToken: string;
+    /**
+     * Relay-asserted operation kind — present on global-log entries, absent on
+     * chain logs. A ROUTING HINT for indexers/browsers, never a verification
+     * input: folds re-derive everything from the JWS itself.
+     */
+    kind?: string;
+    /**
+     * Relay-asserted chain identifier (DID / contentId / targetCID by kind).
+     * Same hint-only status as `kind`.
+     */
+    chainId?: string;
+}
+/** Options for a global-log page read. */
+interface GlobalLogOptions extends CallOptions {
+    /** Page size, 1–1000 (relay-enforced cap). Default 100. */
+    limit?: number;
+}
+/** A page of the global operation log — a seam, not a sync engine (v1). */
+interface GlobalLogPage {
+    entries: LogOp[];
+    next: string | null;
+    provenance: Provenance;
+}
+/** A global-log page, or a relay-local resume position rejected with HTTP 400. */
+type GlobalLogResult = GlobalLogPage | 'invalid-cursor';
+/** Parsed `/.well-known/dfos-relay` body, passed through untouched. */
+interface RelayHealth {
+    url: string;
+    ok: boolean;
+    did?: string;
+    capabilities?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * The relay's capability flags this client cares about, MERGED across the relay
+ * set (true when any relay advertises it). `index` gates whether a browser can
+ * populate from `/index/v0` instead of replaying the full log.
+ */
+interface IndexCapabilities {
+    index: boolean;
+}
+/**
+ * Time-ordered enumeration selector for the `/identities` and `/content` index
+ * routes: newest chains first (`genesisAt.desc`) or most recently active first
+ * (`headAt.desc`). Absent this param the route enumerates in its lexical default.
+ * In ordered mode `after`/`next` are OPAQUE cursor tokens — pass `next` back
+ * verbatim, never parse or construct one.
+ */
+type IndexOrder = 'genesisAt.desc' | 'headAt.desc';
+/** Recency ordering for operation-derived index rows. */
+type IndexRecencyOrder = 'createdAt.desc' | 'ingestedAt.desc';
+/**
+ * The `profile/v1 → name` well-known projection on an identity row. ATTRIBUTION
+ * TIER by construction: the `anchor` is controller-signed (strong), but `name`
+ * is whatever the anchored document says — verify by fetching + re-hashing the
+ * bytes to the committed documentCID. Fields are null on the relay's circuit
+ * breakers (unheld bytes, wrong/missing schema, non-string name).
+ */
+interface IndexIdentityProfile {
+    anchor: string;
+    publicRead: boolean;
+    docSchema: string | null;
+    name: string | null;
+}
+/** One row of the identity index. Mirrors GET /index/v0/identities, nullability included. */
+interface IndexIdentityRow {
+    did: string;
+    headCID: string;
+    opCount: number;
+    genesisAt: string;
+    headAt: string;
+    isDeleted: boolean;
+    profile: IndexIdentityProfile | null;
+}
+/** A page of the identity index. `next` is a `did` cursor (null on the last page). */
+interface IndexIdentitiesPage {
+    identities: IndexIdentityRow[];
+    next: string | null;
+}
+/** One row of the content index. Mirrors GET /index/v0/content, nullability included. */
+interface IndexContentRow {
+    contentId: string;
+    genesisCID: string;
+    headCID: string;
+    creatorDID: string;
+    isDeleted: boolean;
+    opCount: number;
+    genesisAt: string;
+    headAt: string;
+    currentDocumentCID: string | null;
+    publicRead: boolean;
+    docSchema: string | null;
+    title: string | null;
+}
+/** A page of the content index. `next` is a `contentId` cursor (null on the last page). */
+interface IndexContentPage {
+    content: IndexContentRow[];
+    next: string | null;
+}
+/** One row of the countersignatures-by-witness index. Carries the full self-proving JWS. */
+interface IndexCountersignatureRow {
+    cid: string;
+    targetCID: string;
+    relation: string | null;
+    jwsToken: string;
+}
+/** A page of the countersignatures-by-witness index. `next` is a `cid` cursor. */
+interface IndexCountersignaturesPage {
+    witness: string;
+    countersignatures: IndexCountersignatureRow[];
+    next: string | null;
+}
+/** One row of the public-credentials index. Carries the full self-proving JWS. */
+interface IndexCredentialRow {
+    cid: string;
+    issuerDID: string;
+    aud: '*';
+    att: Attenuation[];
+    exp: number;
+    jwsToken: string;
+}
+/** A page of the public-credentials index. `next` is a `cid` cursor. */
+interface IndexCredentialsPage {
+    credentials: IndexCredentialRow[];
+    next: string | null;
+}
+/** Per-call overrides. */
+interface CallOptions {
+    /** Override the client's relay set for this call. */
+    relays?: string[];
+    /** Bypass the cache and re-fetch from genesis. */
+    fresh?: boolean;
+}
+interface ClientConfig {
+    /** Ordered, untrusted relay URLs. IMMUTABLE — a relay switch is a new client. */
+    relays: string[];
+    /** Cache backend. Default `memoryStore()`. */
+    store?: Store;
+    /** Distinct-digest agreement threshold. Default 1 (first-wins). */
+    quorum?: number;
+    /** Revocation checker. Default `() => false` (honest — status is unverifiable). */
+    isRevoked?: RevChecker;
+    /** Injected fetch for blob/health/revocation calls. Default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /**
+     * Per-request timeout in ms (default 10000). A hung relay must fail so
+     * failover can move on — applied to every HTTP request the client makes,
+     * including the default peer-client transport.
+     */
+    timeoutMs?: number;
+    /** Clock injection (unix ms). Default `Date.now`. */
+    now?: () => number;
+    /** Injected log transport. Default `createHttpPeerClient({ fetch })`. */
+    peerClient?: PeerClient;
+}
+interface Client {
+    /** The bound protocol-lib callbacks — spread into any verifier. */
+    callbacks(options?: CallOptions): Callbacks;
+    /** Paste-a-string dispatcher → a typed, trust-wrapped resolution. */
+    resolve(ref: string, options?: CallOptions): Promise<Resolution>;
+    identity(did: string, options?: CallOptions): Promise<Resolved<VerifiedIdentity>>;
+    content(contentId: string, options?: CallOptions): Promise<Resolved<ResolvedContent>>;
+    credential(jws: string, options?: CallOptions): Promise<Resolved<ResolvedCredential>>;
+    document(contentId: string, options?: CallOptions): Promise<Resolved<DocumentBlob>>;
+    /** No-throw, self-routing "is this legit". */
+    verify(jws: string, options?: CallOptions): Promise<VerifyResult<unknown>>;
+    /** Raw floor. */
+    log(kind: 'identity' | 'content', id: string, options?: CallOptions): Promise<Resolved<LogOp[]>>;
+    globalLog(after?: string, options?: GlobalLogOptions): Promise<GlobalLogResult>;
+    health(options?: CallOptions): Promise<RelayHealth[]>;
+    /**
+     * Index (v0) — non-authoritative discovery hints. Rows are CLAIMS, not proofs:
+     * verify one by fetching its chain (`identity`/`content`/`log`) and folding.
+     * Gate on `capabilities().index` before preferring these over full-log sync.
+     */
+    capabilities(options?: CallOptions): Promise<IndexCapabilities>;
+    indexIdentities(params?: {
+        did?: string;
+        hasPublicProfile?: boolean;
+        nameContains?: string;
+        order?: IndexOrder;
+        after?: string;
+        limit?: number;
+    }, options?: CallOptions): Promise<IndexIdentitiesPage>;
+    indexContent(params?: {
+        contentId?: string;
+        creator?: string;
+        signer?: string;
+        docSchema?: string;
+        documentCID?: string;
+        publicRead?: boolean;
+        isDeleted?: boolean;
+        titleContains?: string;
+        order?: IndexOrder;
+        after?: string;
+        limit?: number;
+    }, options?: CallOptions): Promise<IndexContentPage>;
+    indexCountersignatures(witness: string, params?: {
+        relation?: string;
+        order?: IndexRecencyOrder;
+        after?: string;
+        limit?: number;
+    }, options?: CallOptions): Promise<IndexCountersignaturesPage>;
+    indexCredentials(params?: {
+        issuer?: string;
+        resource?: string;
+        action?: string;
+        after?: string;
+        limit?: number;
+    }, options?: CallOptions): Promise<IndexCredentialsPage>;
+}
+
+export type { ClientConfig as C, DocumentBlob as D, GlobalLogOptions as G, IndexCapabilities as I, LogOp as L, Provenance as P, RevChecker as R, Store as S, Trust as T, UnverifiableAxis as U, VerifyResult as V, Client as a, Callbacks as b, CallOptions as c, GlobalLogPage as d, GlobalLogResult as e, IndexContentPage as f, IndexContentRow as g, IndexCountersignatureRow as h, IndexCountersignaturesPage as i, IndexCredentialRow as j, IndexCredentialsPage as k, IndexIdentitiesPage as l, IndexIdentityProfile as m, IndexIdentityRow as n, IndexOrder as o, IndexRecencyOrder as p, RelayHealth as q, RelayResponse as r, Resolution as s, Resolved as t, ResolvedContent as u, ResolvedCredential as v };

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@metalabel/dfos-client",
+  "version": "0.29.0",
+  "type": "module",
+  "description": "DFOS Client — read-only resolve + verify orchestration over untrusted relays. Fetch, resolve, verify-orchestration, cache; all crypto truth comes from @metalabel/dfos-protocol",
+  "license": "MIT",
+  "author": "Metalabel <hello@metalabel.com> (https://metalabel.com)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/metalabel/dfos.git",
+    "directory": "packages/dfos-client"
+  },
+  "homepage": "https://protocol.dfos.com",
+  "keywords": [
+    "dfos",
+    "client",
+    "did",
+    "verifiable",
+    "resolve",
+    "siwd",
+    "ed25519",
+    "jws",
+    "metalabel"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./siwd": "./src/siwd.ts",
+    "./store": "./src/store/index.ts"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "import": "./dist/index.js",
+        "types": "./dist/index.d.ts"
+      },
+      "./siwd": {
+        "import": "./dist/siwd.js",
+        "types": "./dist/siwd.d.ts"
+      },
+      "./store": {
+        "import": "./dist/store/index.js",
+        "types": "./dist/store/index.d.ts"
+      }
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm build"
+  },
+  "peerDependencies": {
+    "@metalabel/dfos-protocol": "^0.29.0",
+    "@metalabel/dfos-web-relay": "^0.29.0"
+  },
+  "devDependencies": {
+    "@metalabel/dfos-protocol": "workspace:*",
+    "@metalabel/dfos-web-relay": "workspace:*",
+    "@types/node": "^24.10.4",
+    "tsup": "^8.5.1",
+    "vitest": "^4.1.8"
+  }
+}