@aithos/sdk 0.1.0-alpha.6 → 0.1.0-alpha.60

package/dist/src/assets.js

@@ -0,0 +1,534 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * `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 { generateAMK, wrapAMKForRecipient, unwrapAMK, encryptAssetBytes, decryptAssetBytes, plaintextSha256Hex, } from "@aithos/assets-crypto";
+import { x25519 } from "@noble/curves/ed25519.js";
+import { sha512 } from "@noble/hashes/sha2.js";
+import { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
+import { signOwnerEnvelope } from "./internal/envelope.js";
+/* -------------------------------------------------------------------------- */
+/*  Public factory                                                            */
+/* -------------------------------------------------------------------------- */
+export function createAssetsClient(args) {
+    return new AssetsClient(args);
+}
+/* -------------------------------------------------------------------------- */
+/*  AssetsClient implementation                                               */
+/* -------------------------------------------------------------------------- */
+export class AssetsClient {
+    #pdsUrl;
+    #did;
+    #seed;
+    #verificationMethod;
+    #fetch;
+    #resolver;
+    /** Cache: URN → AMK (recovered on first fetch, reused thereafter). */
+    #amkCache = new Map();
+    constructor(args) {
+        this.#pdsUrl = (args.pdsUrl ?? DEFAULT_SDK_ENDPOINTS.assets).replace(/\/$/, "");
+        this.#did = args.did;
+        this.#seed = args.sphereSeed;
+        this.#verificationMethod = args.verificationMethod;
+        this.#fetch = args.fetch ?? globalThis.fetch.bind(globalThis);
+        this.#resolver = args.recipientResolver ?? defaultSelfResolver(args);
+    }
+    /* ------------------------------------------------------------------ */
+    /*  upload                                                             */
+    /* ------------------------------------------------------------------ */
+    async upload(input) {
+        const regime = resolveRegime(input);
+        const sha = plaintextSha256Hex(input.bytes);
+        // For private regime, generate AMK + wraps eagerly so the
+        // init_upload call already carries the envelope (the server
+        // records it as part of the pending-upload metadata).
+        let amk;
+        let amkEnvelope;
+        let recipientSet;
+        if (regime === "private") {
+            recipientSet = await this.#resolver.resolve({
+                subjectDid: this.#did,
+                context: input.attachTo,
+            });
+            if (recipientSet.recipients.length === 0) {
+                throw new Error("sdk.assets.upload: private regime requires at least one recipient — check RecipientResolver");
+            }
+            amk = generateAMK();
+            // The bytes encryption nonce is computed inside encryptAssetBytes;
+            // the wrap list will be filled below once we know the final URN
+            // (it's bound into the AAD via assetUrn).
+            // We pre-compose a placeholder envelope to satisfy server
+            // validation, then re-emit with the real URN at init+complete.
+            amkEnvelope = {
+                alg: "xchacha20poly1305-ietf",
+                nonce: "",
+                wraps: [],
+            };
+        }
+        // init_upload
+        const initResp = (await this.#callWrite("aithos.assets.init_upload", {
+            subject_did: this.#did,
+            media_type: input.mediaType,
+            size_bytes: input.bytes.length,
+            sha256_of_plaintext: sha,
+            ...(input.attachTo ? { attached_context: serializeContext(input.attachTo) } : {}),
+            regime,
+            ...(input.forwardSecrecy ? { forward_secrecy: input.forwardSecrecy } : {}),
+            ...(amkEnvelope ? { amk_envelope: amkEnvelope } : {}),
+        }));
+        if (initResp.result === "dedup_hit") {
+            // Asset already exists — return existing URN; no PUT needed.
+            const asset = initResp.asset;
+            if (!asset) {
+                throw new Error("sdk.assets.upload: dedup_hit response is missing the asset metadata");
+            }
+            return {
+                urn: initResp.urn,
+                assetId: initResp.asset_id,
+                mediaType: asset.media_type,
+                sizeBytes: asset.size_bytes,
+                sha256OfPlaintext: asset.sha256_of_plaintext,
+                encrypted: asset.encrypted,
+                url: !asset.encrypted ? composePublicUrl(asset) : undefined,
+                dedupHit: true,
+            };
+        }
+        const finalUrn = initResp.urn;
+        // Build the real wraps using the final URN.
+        let blob;
+        let nonceB64;
+        let finalWraps = [];
+        if (regime === "private") {
+            finalWraps = recipientSet.recipients.map((r) => wrapAMKForRecipient({
+                amk: amk,
+                recipientPublicKey: r.x25519PublicKey,
+                recipientDidUrl: r.didUrl,
+                assetUrn: finalUrn,
+            }));
+            const enc = encryptAssetBytes({
+                amk: amk,
+                assetUrn: finalUrn,
+                plaintext: input.bytes,
+            });
+            blob = enc.blob;
+            nonceB64 = enc.nonce_b64;
+        }
+        else {
+            blob = input.bytes;
+        }
+        // PUT bytes to S3. TS lib.dom typings expect BodyInit; a plain
+        // Uint8Array is accepted at runtime by all modern fetch
+        // implementations (browser, Node 18+, undici), but the lib.dom
+        // signature requires a cast to a BodyInit-compatible view.
+        const putResp = await this.#fetch(initResp.upload_url, {
+            method: "PUT",
+            headers: {
+                "content-type": regime === "private" ? "application/octet-stream" : input.mediaType,
+            },
+            body: blob,
+        });
+        if (!putResp.ok) {
+            throw new Error(`sdk.assets.upload: S3 PUT failed with status ${putResp.status}`);
+        }
+        // complete_upload (with real AMK envelope for private uploads)
+        const completePayload = {
+            upload_session: initResp.upload_session,
+            observed_sha256_of_plaintext: sha,
+        };
+        if (regime === "private") {
+            // The server stores the amk_envelope from init_upload — for v0.1
+            // we don't have a separate "update_envelope_on_complete" hook,
+            // so we recompose it here client-side and call authorize_grantee-
+            // style updates if we need to push real wraps. The simpler v0.1
+            // workaround: include the envelope in init_upload from the start
+            // by precomputing the URN client-side — but the URN is allocated
+            // by the server. For now we ship the envelope on complete via a
+            // backwards-compatible extension field, and the backend stores
+            // it on the asset doc.
+            completePayload.amk_envelope = {
+                alg: "xchacha20poly1305-ietf",
+                nonce: nonceB64,
+                wraps: finalWraps,
+            };
+        }
+        const completeResp = (await this.#callWrite("aithos.assets.complete_upload", completePayload));
+        // Cache the AMK locally for the lifetime of this session.
+        if (amk) {
+            this.#amkCache.set(finalUrn, amk);
+        }
+        return {
+            urn: completeResp.urn,
+            assetId: initResp.asset_id,
+            mediaType: input.mediaType,
+            sizeBytes: input.bytes.length,
+            sha256OfPlaintext: sha,
+            encrypted: regime === "private",
+            url: regime === "public"
+                ? composePublicUrl(completeResp.asset)
+                : undefined,
+            dedupHit: false,
+        };
+    }
+    /* ------------------------------------------------------------------ */
+    /*  uploadWithThumbnails                                               */
+    /* ------------------------------------------------------------------ */
+    /**
+     * 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).
+     */
+    async uploadWithThumbnails(input) {
+        const primary = await this.upload(input);
+        const thumbnails = await Promise.all(input.sizes.map(async (size) => {
+            const scaledBytes = await input.downscale(input.bytes, size);
+            const thumb = await this.upload({
+                ...input,
+                bytes: scaledBytes,
+                // Thumbnails inherit the primary's attachTo so they live in
+                // the same recipient set.
+            });
+            return { size, result: thumb };
+        }));
+        return { primary, thumbnails };
+    }
+    /* ------------------------------------------------------------------ */
+    /*  fetch                                                              */
+    /* ------------------------------------------------------------------ */
+    async fetch(urn) {
+        const resp = (await this.#callRead("aithos.assets.get_asset", {
+            urn,
+        }));
+        const asset = resp.asset;
+        const r = await this.#fetch(resp.fetch_url);
+        if (!r.ok) {
+            throw new Error(`sdk.assets.fetch: byte fetch failed with status ${r.status}`);
+        }
+        const blob = new Uint8Array(await r.arrayBuffer());
+        let bytes;
+        if (asset.encrypted) {
+            const amk = this.#amkCache.get(urn) ??
+                this.#unwrapAmkForSelf(urn, asset.amk_envelope);
+            this.#amkCache.set(urn, amk);
+            bytes = decryptAssetBytes({
+                amk,
+                assetUrn: urn,
+                blob,
+                expectedSha256Hex: asset.sha256_of_plaintext,
+            });
+        }
+        else {
+            bytes = blob;
+            // SHA verification still applies for public assets.
+            if (plaintextSha256Hex(bytes) !== asset.sha256_of_plaintext) {
+                throw new Error("sdk.assets.fetch: plaintext SHA-256 mismatch on public asset");
+            }
+        }
+        return {
+            urn,
+            mediaType: asset.media_type,
+            sizeBytes: asset.size_bytes,
+            bytes,
+            sha256OfPlaintext: asset.sha256_of_plaintext,
+        };
+    }
+    /* ------------------------------------------------------------------ */
+    /*  head                                                               */
+    /* ------------------------------------------------------------------ */
+    async head(urn) {
+        const r = (await this.#callRead("aithos.assets.head_asset", {
+            urn,
+        }));
+        return r.asset;
+    }
+    /* ------------------------------------------------------------------ */
+    /*  list                                                               */
+    /* ------------------------------------------------------------------ */
+    async list(opts = {}) {
+        const params = {
+            subject_did: this.#did,
+        };
+        if (opts.limit !== undefined)
+            params.limit = opts.limit;
+        if (opts.cursor)
+            params.cursor = opts.cursor;
+        if (opts.order)
+            params.order = opts.order;
+        if (opts.includeOrphaned)
+            params.include_orphaned = true;
+        if (opts.includeTombstoned)
+            params.include_tombstoned = true;
+        if (opts.filter) {
+            const f = {};
+            if (opts.filter.mediaTypePrefix)
+                f.media_type_prefix = opts.filter.mediaTypePrefix;
+            if (opts.filter.sizeBytes)
+                f.size_bytes = opts.filter.sizeBytes;
+            if (opts.filter.createdAfter)
+                f.created_after = opts.filter.createdAfter;
+            if (opts.filter.createdBefore)
+                f.created_before = opts.filter.createdBefore;
+            params.filter = f;
+        }
+        const r = (await this.#callRead("aithos.assets.list_assets", params));
+        return {
+            items: r.items.map((it) => ({
+                urn: it.urn,
+                assetId: it.asset_id,
+                mediaType: it.media_type,
+                sizeBytes: it.size_bytes,
+                sha256OfPlaintext: it.sha256_of_plaintext,
+                encrypted: it.encrypted,
+                state: it.state,
+                referenceCount: it.reference_count,
+                createdAt: it.created_at,
+                modifiedAt: it.modified_at,
+            })),
+            ...(r.next_cursor ? { nextCursor: r.next_cursor } : {}),
+        };
+    }
+    /* ------------------------------------------------------------------ */
+    /*  ref / unref / listReferences                                       */
+    /* ------------------------------------------------------------------ */
+    async ref(urn, reference) {
+        const r = (await this.#callWrite("aithos.assets.ref_asset", {
+            urn,
+            reference,
+        }));
+        return { referenceCount: r.reference_count, gammaRef: r.gamma_ref };
+    }
+    async unref(urn, reference) {
+        const r = (await this.#callWrite("aithos.assets.unref_asset", {
+            urn,
+            reference,
+        }));
+        return { referenceCount: r.reference_count, gammaRef: r.gamma_ref };
+    }
+    async listReferences(urn) {
+        const r = (await this.#callRead("aithos.assets.list_references", {
+            urn,
+        }));
+        return r.items;
+    }
+    /* ------------------------------------------------------------------ */
+    /*  delete                                                             */
+    /* ------------------------------------------------------------------ */
+    async delete(urn) {
+        const r = (await this.#callWrite("aithos.assets.delete_asset", {
+            urn,
+        }));
+        this.#amkCache.delete(urn);
+        return { tombstonedAt: r.tombstoned_at, gammaRef: r.gamma_ref };
+    }
+    /* ------------------------------------------------------------------ */
+    /*  reset cache                                                        */
+    /* ------------------------------------------------------------------ */
+    /** Zero in-memory AMK cache. Useful at user logout. */
+    reset() {
+        for (const k of this.#amkCache.values())
+            k.fill(0);
+        this.#amkCache.clear();
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Internals — envelope dispatch                                      */
+    /* ------------------------------------------------------------------ */
+    async #callRead(method, params) {
+        return this.#dispatch("/mcp/primitives/read", method, params);
+    }
+    async #callWrite(method, params) {
+        return this.#dispatch("/mcp/primitives/write", method, params);
+    }
+    async #dispatch(path, method, params) {
+        const aud = `${this.#pdsUrl}${path}`;
+        const envelope = await this.#signEnvelope({ aud, method, params });
+        const body = {
+            jsonrpc: "2.0",
+            id: makeUlidLite(),
+            method,
+            params: { ...params, _envelope: envelope },
+        };
+        const r = await this.#fetch(aud, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        const json = (await r.json());
+        if (json.error) {
+            const err = new Error(json.error.message);
+            err.code = json.error.code;
+            err.data = json.error.data;
+            throw err;
+        }
+        return json.result ?? {};
+    }
+    async #signEnvelope(args) {
+        return signOwnerEnvelope({
+            iss: this.#did,
+            aud: args.aud,
+            method: args.method,
+            params: args.params,
+            verificationMethod: this.#verificationMethod,
+            signer: {
+                sign: async (msg) => {
+                    // We delegate to @noble/ed25519 directly to avoid pulling the
+                    // SDK's Signer abstraction surface into this module. The
+                    // dependency is already present transitively via assets-crypto.
+                    const { signAsync } = await import("@noble/ed25519");
+                    return signAsync(msg, this.#seed);
+                },
+            },
+        });
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Internals — AMK unwrap for self                                    */
+    /* ------------------------------------------------------------------ */
+    #unwrapAmkForSelf(urn, envelope) {
+        const ourPub = ed25519SeedToX25519PublicKey(this.#seed);
+        void ourPub;
+        const ourPriv = ed25519SeedToX25519PrivateKey(this.#seed);
+        // Try every wrap that names a recipient under our DID. The DID
+        // URL fragment is unconstrained — `#kex`, `#circle-kex`, `#self-kex`
+        // are all candidates. We attempt each wrap whose `recipient`
+        // starts with our DID; AAD binding makes wrong attempts fail
+        // cleanly.
+        const ours = envelope.wraps.filter((w) => w.recipient.startsWith(this.#did));
+        for (const wrap of ours) {
+            try {
+                return unwrapAMK({
+                    wrap,
+                    recipientPrivateKey: ourPriv,
+                    assetUrn: urn,
+                });
+            }
+            catch {
+                // Wrong fragment / wrong key — try the next wrap.
+            }
+        }
+        throw new Error(`sdk.assets.fetch: no AMK wrap for ${this.#did} found in asset ${urn}`);
+    }
+}
+/* -------------------------------------------------------------------------- */
+/*  Default RecipientResolver — self-only                                     */
+/* -------------------------------------------------------------------------- */
+function defaultSelfResolver(args) {
+    return {
+        async resolve(input) {
+            // For the default self-only resolver we always wrap to the
+            // subject's own X25519 sphere key. Other recipients (grantees)
+            // can be added explicitly later via authorize_grantee in v0.2.
+            const pub = ed25519SeedToX25519PublicKey(args.sphereSeed);
+            const didUrl = recipientDidUrlForContext(input.subjectDid, input.context);
+            return {
+                recipients: [{ didUrl, x25519PublicKey: pub }],
+            };
+        },
+    };
+}
+/** Pick a DID URL fragment matching the attaching zone. */
+function recipientDidUrlForContext(subjectDid, context) {
+    if (context?.ethos?.zone === "circle")
+        return `${subjectDid}#circle-kex`;
+    if (context?.ethos?.zone === "self")
+        return `${subjectDid}#self-kex`;
+    if (context?.data)
+        return `${subjectDid}#data-kex`;
+    return `${subjectDid}#kex`;
+}
+function resolveRegime(input) {
+    if (input.regime === "public")
+        return "public";
+    if (input.regime === "private")
+        return "private";
+    if (input.attachTo?.ethos?.zone === "public")
+        return "public";
+    return "private";
+}
+function serializeContext(ctx) {
+    if (ctx.ethos) {
+        return {
+            kind: "ethos",
+            zone: ctx.ethos.zone,
+            ...(ctx.ethos.sectionId ? { section_id: ctx.ethos.sectionId } : {}),
+        };
+    }
+    if (ctx.data) {
+        return {
+            kind: "data",
+            collection_urn: ctx.data.collectionUrn,
+            ...(ctx.data.recordId ? { record_id: ctx.data.recordId } : {}),
+        };
+    }
+    return {};
+}
+function composePublicUrl(asset) {
+    return asset.public_url;
+}
+/**
+ * Derive a 32-byte X25519 private key from an Ed25519 seed via
+ * SHA-512 truncation + clamping. Same construction libsodium uses for
+ * `crypto_sign_ed25519_sk_to_curve25519`.
+ */
+function ed25519SeedToX25519PrivateKey(seed) {
+    if (seed.length !== 32)
+        throw new Error("Ed25519 seed must be 32 bytes");
+    const h = sha512(seed);
+    const sk = new Uint8Array(h.slice(0, 32));
+    // Clamp per X25519 spec
+    sk[0] = sk[0] & 248;
+    sk[31] = sk[31] & 127;
+    sk[31] = sk[31] | 64;
+    return sk;
+}
+function ed25519SeedToX25519PublicKey(seed) {
+    const sk = ed25519SeedToX25519PrivateKey(seed);
+    try {
+        return x25519.getPublicKey(sk);
+    }
+    finally {
+        sk.fill(0);
+    }
+}
+function makeUlidLite() {
+    // Lightweight monotonic-ish id for JSON-RPC `id` field — not
+    // crypto-grade. Production code uses ulid().
+    return (Date.now().toString(36) +
+        Math.random().toString(36).substring(2, 10));
+}
+//# sourceMappingURL=assets.js.map