@aithos/sdk 0.1.0-alpha.4 → 0.1.0-alpha.41

package/dist/src/assets.d.ts

@@ -0,0 +1,207 @@
+/**
+ * `sdk.assets` — high-level API for the Aithos assets sub-protocol PDS.
+ *
+ * Stores binary content (images, PDFs, audio, video) owned by a
+ * subject, encrypted client-side under per-asset AMKs (Asset Master
+ * Keys), accessible to authorized apps via signed mandates (v0.2).
+ *
+ *     const assets = sdk.assets;
+ *     const avatar = await assets.upload({
+ *       bytes: pngBuffer,
+ *       mediaType: "image/png",
+ *       attachTo: { ethos: { zone: "public", sectionId: "sec_identity" } },
+ *     });
+ *     // avatar.url is a stable CloudFront URL (public asset)
+ *
+ *     const cv = await assets.upload({
+ *       bytes: pdfBuffer,
+ *       mediaType: "application/pdf",
+ *       attachTo: { ethos: { zone: "circle", sectionId: "sec_career_docs" } },
+ *     });
+ *     // cv is private: stored encrypted, fetched via short-lived presigned URL.
+ *
+ *     const bytes = await assets.fetch(cv.urn);
+ *     // decrypted plaintext returned to the caller
+ *
+ * The module wires:
+ *   - AMK generation + wrap (via @aithos/assets-crypto)
+ *   - Bytes encryption with the canonical nonce-prefix on-disk layout
+ *   - RecipientResolver (v0.2-ethos: maps {zone} → recipient set)
+ *   - Direct S3 PUT against the presigned URL returned by init_upload
+ *   - In-memory AMK cache (per asset URN) for sub-second re-fetches
+ *   - Signed envelope JSON-RPC dispatch to /mcp/primitives/{read,write}
+ *
+ * Spec ref: spec/assets/ in the aithos-protocol repo.
+ */
+import { type AssetMetadata, type AssetReference } from "@aithos/assets-crypto";
+export interface CreateAssetsClientArgs {
+    /** Base URL of the deployed assets PDS. */
+    readonly pdsUrl: string;
+    /** Subject DID. */
+    readonly did: string;
+    /** Ed25519 sphere seed (32 bytes). */
+    readonly sphereSeed: Uint8Array;
+    /** Verification method URL within the DID document (e.g. `<did>#<multibase>` for did:key). */
+    readonly verificationMethod: string;
+    /** Optional fetch implementation. Defaults to globalThis.fetch. */
+    readonly fetch?: typeof fetch;
+    /**
+     * Optional override for the recipient resolver. By default the SDK
+     * uses a "self-only" resolver that maps every private upload to the
+     * subject's own X25519 sphere key. Apps that already orchestrate
+     * grantees explicitly may pass a custom resolver.
+     */
+    readonly recipientResolver?: RecipientResolver;
+}
+export interface AttachedContext {
+    readonly ethos?: {
+        readonly zone: "public" | "circle" | "self";
+        readonly sectionId?: string;
+    };
+    readonly data?: {
+        readonly collectionUrn: string;
+        readonly recordId?: string;
+        readonly field?: string;
+    };
+}
+export interface AssetUploadInput {
+    readonly bytes: Uint8Array;
+    readonly mediaType: string;
+    readonly attachTo?: AttachedContext;
+    /**
+     * OPTIONAL — force a regime. Defaults to "auto":
+     *   - ethos.zone === "public" → public
+     *   - anything else → private
+     */
+    readonly regime?: "auto" | "public" | "private";
+    /** OPTIONAL — strict forward secrecy at AMK rotation time. */
+    readonly forwardSecrecy?: "best_effort" | "strict";
+}
+export interface AssetUploadResult {
+    readonly urn: string;
+    readonly assetId: string;
+    readonly mediaType: string;
+    readonly sizeBytes: number;
+    readonly sha256OfPlaintext: string;
+    readonly encrypted: boolean;
+    /**
+     * Stable URL for public assets (CloudFront-served). Absent for
+     * private assets — fetch them via {@link AssetsClient.fetch}.
+     */
+    readonly url?: string;
+    /** Whether this URN was returned by intra-subject dedup (existing asset). */
+    readonly dedupHit: boolean;
+}
+export interface AssetFetchResult {
+    readonly urn: string;
+    readonly mediaType: string;
+    readonly sizeBytes: number;
+    readonly bytes: Uint8Array;
+    readonly sha256OfPlaintext: string;
+}
+export interface AssetBrief {
+    readonly urn: string;
+    readonly assetId: string;
+    readonly mediaType: string;
+    readonly sizeBytes: number;
+    readonly sha256OfPlaintext: string;
+    readonly encrypted: boolean;
+    readonly state: "ACTIVE" | "ORPHANED" | "TOMBSTONED";
+    readonly referenceCount: number;
+    readonly createdAt: string;
+    readonly modifiedAt: string;
+}
+export interface ListAssetsOpts {
+    readonly filter?: {
+        readonly mediaTypePrefix?: string;
+        readonly sizeBytes?: {
+            gte?: number;
+            lte?: number;
+        };
+        readonly createdAfter?: string;
+        readonly createdBefore?: string;
+    };
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly order?: "newest" | "oldest";
+    readonly includeOrphaned?: boolean;
+    readonly includeTombstoned?: boolean;
+}
+export interface ThumbnailUploadInput extends AssetUploadInput {
+    /** Long-edge sizes to produce (e.g. [64, 256]). */
+    readonly sizes: readonly number[];
+    /**
+     * Downscaler. The SDK does NOT bundle an image library; callers pass
+     * a function that takes the original bytes and a target size and
+     * returns downscaled bytes. Typical implementations: `pica` in the
+     * browser, `sharp` in Node.
+     */
+    readonly downscale: (bytes: Uint8Array, targetLongEdge: number) => Promise<Uint8Array>;
+}
+export interface ThumbnailUploadResult {
+    readonly primary: AssetUploadResult;
+    readonly thumbnails: readonly {
+        size: number;
+        result: AssetUploadResult;
+    }[];
+}
+/**
+ * Maps an attaching context to the set of recipients whose wraps the
+ * AMK must carry. The v0.1 default returns the subject's own X25519
+ * sphere key derived from the SDK's seed.
+ *
+ * v0.2 will introduce an Ethos-aware resolver that inspects the
+ * current manifest's `zones.<z>.cipher.wraps[]` (or, in v0.3, the
+ * per-section wraps) to mirror grantees on attached assets.
+ */
+export interface RecipientResolver {
+    resolve(input: {
+        subjectDid: string;
+        context: AttachedContext | undefined;
+    }): Promise<RecipientSet>;
+}
+export interface RecipientSet {
+    readonly recipients: ReadonlyArray<{
+        readonly didUrl: string;
+        readonly x25519PublicKey: Uint8Array;
+    }>;
+}
+export declare function createAssetsClient(args: CreateAssetsClientArgs): AssetsClient;
+export declare class AssetsClient {
+    #private;
+    constructor(args: CreateAssetsClientArgs);
+    upload(input: AssetUploadInput): Promise<AssetUploadResult>;
+    /**
+     * Upload a primary asset plus one or more thumbnails (downscaled
+     * client-side). Convenience method for the Deep avatar use case and
+     * any UI that displays the same asset at multiple resolutions.
+     *
+     * The thumbnails are attached to the same context as the primary
+     * and uploaded in parallel. They carry the {@link AssetReference}
+     * role `"thumbnail"` when referenced from a section (see
+     * spec/assets/03-asset-descriptors.md §3.2.3).
+     */
+    uploadWithThumbnails(input: ThumbnailUploadInput): Promise<ThumbnailUploadResult>;
+    fetch(urn: string): Promise<AssetFetchResult>;
+    head(urn: string): Promise<AssetMetadata>;
+    list(opts?: ListAssetsOpts): Promise<{
+        items: AssetBrief[];
+        nextCursor?: string;
+    }>;
+    ref(urn: string, reference: AssetReference): Promise<{
+        referenceCount: number;
+        gammaRef: string;
+    }>;
+    unref(urn: string, reference: AssetReference): Promise<{
+        referenceCount: number;
+        gammaRef: string;
+    }>;
+    listReferences(urn: string): Promise<AssetReference[]>;
+    delete(urn: string): Promise<{
+        tombstonedAt: string;
+        gammaRef: string;
+    }>;
+    /** Zero in-memory AMK cache. Useful at user logout. */
+    reset(): void;
+}
+//# sourceMappingURL=assets.d.ts.map