@misofm/sdk 0.3.0 → 0.5.0

package/dist/read/works.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"works.d.ts","sourceRoot":"","sources":["../../src/read/works.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,OAAO,EACb,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9C,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7C;AAWD,gFAAgF;AAChF,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,gBAAgB,EACxB,UAAU,EAAE,cAAc,EAC1B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,wBAAwB,CAAC,CAmDnC;AAED,MAAM,WAAW,OAAO;IACtB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IACnD,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IAC/C,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC5C;AAED,mEAAmE;AACnE,wBAAsB,aAAa,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAO/F;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,gBAAgB,EACzB,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAwCjC"}
+{"version":3,"file":"works.d.ts","sourceRoot":"","sources":["../../src/read/works.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,OAAO,EAEb,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9C,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7C;AAYD,mEAAmE;AACnE,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,gBAAgB,EACxB,UAAU,EAAE,cAAc,EAC1B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,wBAAwB,CAAC,CA8FnC;AAED,MAAM,WAAW,OAAO;IACtB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IACnD,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IAC/C,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC5C;AA+BD,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,OAAO,GACZ,OAAO,CAuCT;AAED,yEAAyE;AACzE,wBAAsB,aAAa,CACjC,MAAM,EAAE,iBAAiB,EACzB,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,SAAS,CAAC,CA2CpB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,gBAAgB,EACzB,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA+CjC"}

package/dist/read/works.js

@@ -1,67 +1,172 @@
 // Copyright (c) Miso Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
-import { extractTypeParams2, getCompositionsByIds, getRecordingsByIds, getReleasesByIds, } from "@misonetwork/sdk";
-/** Resolve work share types without relying on unpublished protocol helpers. */
+import { normalizeSuiAddress } from "@mysten/sui/utils";
+import { contracts, extractTypeParams2, getCompositionsByIds, } from "@misonetwork/sdk";
+/** Resolve all work share types in one aliased GraphQL request. */
 export async function getWorkAddressesByShareTypes(client, shareTypes, misoPackageId) {
     const compositions = [...new Set(shareTypes.compositions)];
-    const recordingSet = new Set(shareTypes.recordings);
+    const recordings = new Set(shareTypes.recordings);
     const out = { compositions: {}, recordings: {} };
-    const compositionEntries = await Promise.all(compositions.map(async (shareType) => {
-        const type = `${misoPackageId}::composition::Composition<${shareType}>`;
-        const result = await client.query({
-            query: `query WorkByType($type: String!) {
-          objects(filter: { type: $type }) {
-            nodes { address asMoveObject { contents { type { repr } } } }
-          }
-        }`,
-            variables: { type },
-        });
-        if (result.errors?.length)
-            throw new Error(result.errors[0].message);
-        return [shareType, result.data?.objects?.nodes[0]?.address];
-    }));
-    for (const [shareType, address] of compositionEntries) {
+    if (compositions.length === 0 && recordings.size === 0)
+        return out;
+    const declarations = [];
+    const selections = [];
+    const variables = {};
+    compositions.forEach((shareType, index) => {
+        const variable = `compositionType${index}`;
+        declarations.push(`$${variable}: String!`);
+        selections.push(`composition${index}: objects(first: 1, filter: { type: $${variable} }) { nodes { address } }`);
+        variables[variable] =
+            `${misoPackageId}::composition::Composition<${shareType}>`;
+    });
+    if (recordings.size > 0) {
+        declarations.push("$recordingType: String!");
+        selections.push(`recordings: objects(first: 50, filter: { type: $recordingType }) {
+      pageInfo { hasNextPage endCursor }
+      nodes { address asMoveObject { contents { type { repr } } } }
+    }`);
+        variables.recordingType = `${misoPackageId}::recording::Recording`;
+    }
+    const result = await client.query({
+        query: `query WorkAddressesByShareTypes(${declarations.join(", ")}) {
+      ${selections.join("\n")}
+    }`,
+        variables,
+    });
+    if (result.errors?.length) {
+        throw new AggregateError(result.errors.map((error) => new Error(error.message)), "Work type discovery failed");
+    }
+    compositions.forEach((shareType, index) => {
+        const address = result.data?.[`composition${index}`]?.nodes[0]?.address;
         if (address)
             out.compositions[shareType] = address;
-    }
-    if (recordingSet.size > 0) {
-        const type = `${misoPackageId}::recording::Recording`;
-        const result = await client.query({
-            query: `query RecordingsByType($type: String!) {
-        objects(filter: { type: $type }) {
-          nodes { address asMoveObject { contents { type { repr } } } }
-        }
-      }`,
-            variables: { type },
-        });
-        if (result.errors?.length)
-            throw new Error(result.errors[0].message);
-        for (const node of result.data?.objects?.nodes ?? []) {
-            const repr = node.asMoveObject?.contents?.type.repr;
+    });
+    const readRecordingPage = (page) => {
+        for (const node of page?.nodes ?? []) {
+            const repr = node.asMoveObject?.contents?.type?.repr;
             if (!repr)
                 continue;
-            let recordingShareType;
             try {
-                [recordingShareType] = extractTypeParams2(repr);
+                const [shareType] = extractTypeParams2(repr);
+                if (recordings.has(shareType))
+                    out.recordings[shareType] = node.address;
             }
             catch {
-                recordingShareType = /<(.+)>$/.exec(repr)?.[1]?.trim();
-            }
-            if (recordingShareType && recordingSet.has(recordingShareType)) {
-                out.recordings[recordingShareType] = node.address;
+                // Ignore objects whose deployed type does not match the Recording ABI.
             }
         }
+    };
+    let page = result.data?.recordings;
+    readRecordingPage(page);
+    while (page?.pageInfo?.hasNextPage &&
+        page.pageInfo.endCursor &&
+        Object.keys(out.recordings).length < recordings.size) {
+        const next = await client.query({
+            query: `query RecordingWorkAddresses($recordingType: String!, $cursor: String!) {
+        recordings: objects(first: 50, after: $cursor, filter: { type: $recordingType }) {
+          pageInfo { hasNextPage endCursor }
+          nodes { address asMoveObject { contents { type { repr } } } }
+        }
+      }`,
+            variables: {
+                recordingType: variables.recordingType,
+                cursor: page.pageInfo.endCursor,
+            },
+        });
+        if (next.errors?.length) {
+            throw new AggregateError(next.errors.map((error) => new Error(error.message)), "Recording type discovery failed");
+        }
+        page = next.data?.recordings;
+        readRecordingPage(page);
     }
     return out;
 }
-/** Fetch each work kind through the authoritative protocol SDK. */
+function workState(value) {
+    return value?.$kind === "Published"
+        ? { type: "Published", timestampMs: Number(value.Published) }
+        : { type: "Initialized" };
+}
+function parseComposition(id, content) {
+    const value = contracts.composition.Composition.parse(content);
+    return {
+        id,
+        state: workState(value.state),
+        title: String(value.title),
+        royaltyRate: {
+            value: Number(Array.isArray(value.royalty_rate)
+                ? value.royalty_rate[0]
+                : value.royalty_rate),
+        },
+    };
+}
+function parseRecording(id, content) {
+    const value = contracts.recording.Recording.parse(content);
+    return { id, state: workState(value.state) };
+}
+export function parseReleaseObject(id, content, json) {
+    const deployed = json;
+    if (deployed?.discs) {
+        const tracks = deployed.discs.flatMap((disc) => disc.tracks ?? []);
+        const publishedAt = deployed.state?.["@variant"] === "Published" ? deployed.state.pos0 : null;
+        return {
+            id,
+            state: publishedAt == null
+                ? { type: "Initialized" }
+                : { type: "Published", timestampMs: Number(publishedAt) },
+            title: String(deployed.title ?? ""),
+            tracks: tracks.map((track) => ({
+                state: (track.state?.["@variant"] ?? "Unassigned"),
+                recordingId: String(track.recording_id),
+                splitBps: { value: Number(track.split_bps?.pos0 ?? track.split_bps) },
+            })),
+        };
+    }
+    const value = contracts.release.Release.parse(content);
+    return {
+        id,
+        state: workState(value.state),
+        title: String(value.title),
+        tracks: (value.tracks ?? []).map((track) => ({
+            state: (track.state?.$kind ?? "Unassigned"),
+            recordingId: String(track.recording_id),
+            splitBps: {
+                value: Number(Array.isArray(track.split_bps) ? track.split_bps[0] : track.split_bps),
+            },
+        })),
+    };
+}
+/** Fetch and parse heterogeneous works through one Core bulk request. */
 export async function getWorksByIds(client, ids) {
-    const [compositions, recordings, releases] = await Promise.all([
-        getCompositionsByIds(client, [...ids.compositions]),
-        getRecordingsByIds(client, [...ids.recordings]),
-        getReleasesByIds(client, [...ids.releases]),
-    ]);
-    return { compositions, recordings, releases };
+    const kinds = new Map();
+    for (const [kind, objectIds] of Object.entries(ids)) {
+        for (const objectId of objectIds) {
+            const normalized = normalizeSuiAddress(objectId);
+            const previous = kinds.get(normalized);
+            if (previous && previous !== kind) {
+                throw new Error(`Work ${normalized} was requested as both ${previous} and ${kind}`);
+            }
+            kinds.set(normalized, kind);
+        }
+    }
+    const out = { compositions: {}, recordings: {}, releases: {} };
+    if (kinds.size === 0)
+        return out;
+    const { objects } = await client.core.getObjects({
+        objectIds: [...kinds.keys()],
+        include: { content: true, json: true },
+    });
+    for (const object of objects) {
+        if (object instanceof Error || !object.content)
+            continue;
+        const kind = kinds.get(normalizeSuiAddress(object.objectId));
+        if (kind === "compositions")
+            out.compositions[object.objectId] = parseComposition(object.objectId, object.content);
+        else if (kind === "recordings")
+            out.recordings[object.objectId] = parseRecording(object.objectId, object.content);
+        else if (kind === "releases")
+            out.releases[object.objectId] = parseReleaseObject(object.objectId, object.content, object.json);
+    }
+    return out;
 }
 /**
  * Resolve display titles for both deployed recording layouts. Older recordings
@@ -71,7 +176,10 @@ export async function getRecordingTitles(client, graphql, recordingIds, misoPack
     const ids = [...new Set(recordingIds)];
     if (ids.length === 0)
         return {};
-    const { objects } = await client.core.getObjects({ objectIds: ids, include: { json: true } });
+    const { objects } = await client.core.getObjects({
+        objectIds: ids,
+        include: { json: true },
+    });
     const titles = {};
     const compositionShareByRecording = {};
     for (const object of objects) {
@@ -97,7 +205,9 @@ export async function getRecordingTitles(client, graphql, recordingIds, misoPack
     const compositions = await getCompositionsByIds(client, Object.values(addresses.compositions).filter((id) => !!id));
     for (const [recordingId, shareType] of Object.entries(compositionShareByRecording)) {
         const compositionId = addresses.compositions[shareType];
-        const title = compositionId ? compositions[compositionId]?.title : undefined;
+        const title = compositionId
+            ? compositions[compositionId]?.title
+            : undefined;
         if (title)
             titles[recordingId] = title;
     }

package/dist/read/works.js.map

@@ -1 +1 @@
-{"version":3,"file":"works.js","sourceRoot":"","sources":["../../src/read/works.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"works.js","sourceRoot":"","sources":["../../src/read/works.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misofm/sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Complete client SDK for the Miso platform on Sui \u2014 high-level reads, pressings, listings, records, and work publishing.",
   "license": "Apache-2.0",
   "repository": {
@@ -80,6 +80,10 @@
       "types": "./dist/read/types.d.ts",
       "default": "./dist/read/types.js"
     },
+    "./auth": {
+      "types": "./dist/auth.d.ts",
+      "default": "./dist/auth.js"
+    },
     "./drop": {
       "types": "./dist/drop.d.ts",
       "default": "./dist/drop.js"

package/src/auth.ts

@@ -0,0 +1,275 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { isValidSuiAddress, normalizeSuiAddress } from "@mysten/sui/utils";
+
+export type AuthNetwork = "testnet" | "mainnet";
+
+export interface ApiAuthorizationFields {
+  method: string;
+  path: string;
+  address: string;
+  network: AuthNetwork;
+  issuedAt: string;
+}
+
+export interface AuthorizationChallenge extends ApiAuthorizationFields {
+  payload: string;
+  expiresAt: string;
+}
+
+export interface PersonalMessageSigner {
+  signPersonalMessage(message: Uint8Array): Promise<{ signature: string; bytes?: string }>;
+}
+
+export const AUTHORIZATION_MAX_AGE_MS = 5 * 60 * 1_000;
+export const AUTHORIZATION_FUTURE_SKEW_MS = 60 * 1_000;
+
+export const MISO_AUTH_HEADERS = {
+  address: "X-Sui-Address",
+  signature: "X-Sui-Signature",
+  issuedAt: "X-Sui-Issued-At",
+} as const;
+
+export type MisoAuthErrorCode =
+  | "invalid_target"
+  | "challenge_rejected"
+  | "invalid_challenge"
+  | "signing_failed";
+
+export class MisoAuthError extends Error {
+  readonly code: MisoAuthErrorCode;
+  readonly status?: number;
+
+  constructor(code: MisoAuthErrorCode, message: string, options: { status?: number; cause?: unknown } = {}) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "MisoAuthError";
+    this.code = code;
+    this.status = options.status;
+  }
+}
+
+/** The byte-exact Sui personal message required for an authenticated API mutation. */
+export function buildApiAuthorizationPayload(fields: ApiAuthorizationFields): string {
+  return [
+    "miso.fm API authorization v1",
+    "",
+    `Method: ${fields.method.toUpperCase()}`,
+    `Path: ${fields.path}`,
+    `Address: ${fields.address}`,
+    `Network: ${fields.network}`,
+    `Issued At: ${fields.issuedAt}`,
+  ].join("\n");
+}
+
+export function isValidAuthorizationTarget(method: string, path: string): boolean {
+  return (
+    ["POST", "PUT", "PATCH", "DELETE"].includes(method.toUpperCase()) &&
+    path.startsWith("/platform/") &&
+    path.length <= 2_048 &&
+    !/[\r\n?#]/.test(path)
+  );
+}
+
+/** Accept only fresh timestamps in one canonical spelling. */
+export function parseFreshAuthorizationIssuedAt(input: unknown, nowMs: number = Date.now()): string | null {
+  if (typeof input !== "string") return null;
+  const issuedAtMs = Date.parse(input);
+  if (!Number.isFinite(issuedAtMs)) return null;
+  if (
+    issuedAtMs > nowMs + AUTHORIZATION_FUTURE_SKEW_MS ||
+    nowMs - issuedAtMs > AUTHORIZATION_MAX_AGE_MS
+  ) {
+    return null;
+  }
+  const canonical = new Date(issuedAtMs).toISOString();
+  return input === canonical ? canonical : null;
+}
+
+function target(method: string, path: string): { method: string; path: string } {
+  const normalized = { method: method.toUpperCase(), path };
+  if (!isValidAuthorizationTarget(normalized.method, normalized.path)) {
+    throw new MisoAuthError("invalid_target", "Authenticated requests require a mutation under /platform/.");
+  }
+  return normalized;
+}
+
+function parseChallenge(
+  input: unknown,
+  expected: { method: string; path: string; address: string; network?: AuthNetwork; nowMs?: number },
+): AuthorizationChallenge {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    throw new MisoAuthError("invalid_challenge", "The API returned an invalid authorization challenge.");
+  }
+  const body = input as Partial<Record<keyof AuthorizationChallenge, unknown>>;
+  if (
+    typeof body.payload !== "string" ||
+    typeof body.method !== "string" ||
+    typeof body.path !== "string" ||
+    typeof body.address !== "string" ||
+    typeof body.network !== "string" ||
+    typeof body.issuedAt !== "string" ||
+    typeof body.expiresAt !== "string" ||
+    !isValidSuiAddress(body.address) ||
+    (body.network !== "testnet" && body.network !== "mainnet")
+  ) {
+    throw new MisoAuthError("invalid_challenge", "The API returned an invalid authorization challenge.");
+  }
+
+  const nowMs = expected.nowMs ?? Date.now();
+  const issuedAt = parseFreshAuthorizationIssuedAt(body.issuedAt, nowMs);
+  const expiresAtMs = Date.parse(body.expiresAt);
+  const canonicalAddress = normalizeSuiAddress(body.address);
+  const expectedAddress = normalizeSuiAddress(expected.address);
+  const challenge: AuthorizationChallenge = {
+    payload: body.payload,
+    method: body.method,
+    path: body.path,
+    address: canonicalAddress,
+    network: body.network,
+    issuedAt: body.issuedAt,
+    expiresAt: body.expiresAt,
+  };
+  const canonicalExpiresAt = Number.isFinite(expiresAtMs) ? new Date(expiresAtMs).toISOString() : "";
+
+  if (
+    !issuedAt ||
+    body.method !== expected.method ||
+    body.path !== expected.path ||
+    canonicalAddress !== expectedAddress ||
+    (expected.network !== undefined && body.network !== expected.network) ||
+    body.expiresAt !== canonicalExpiresAt ||
+    expiresAtMs <= nowMs ||
+    expiresAtMs > Date.parse(issuedAt) + AUTHORIZATION_MAX_AGE_MS ||
+    body.payload !== buildApiAuthorizationPayload(challenge)
+  ) {
+    throw new MisoAuthError("invalid_challenge", "The authorization challenge did not match this request.");
+  }
+  return challenge;
+}
+
+async function responseMessage(response: Response): Promise<string> {
+  const body = await response.clone().json().catch(() => null) as {
+    error?: { message?: unknown } | string;
+    message?: unknown;
+  } | null;
+  if (typeof body?.error === "object" && typeof body.error.message === "string") return body.error.message;
+  if (typeof body?.error === "string") return body.error;
+  if (typeof body?.message === "string") return body.message;
+  return `Authorization challenge failed (${response.status}).`;
+}
+
+export interface RequestAuthorizationChallengeOptions {
+  apiUrl: string | URL;
+  token: string;
+  address: string;
+  method: string;
+  path: string;
+  network?: AuthNetwork;
+  challengeUrl?: string | URL;
+  fetch?: typeof globalThis.fetch;
+  nowMs?: number;
+}
+
+/** Ask Miso to verify the Enoki account and issue the exact message to sign. */
+export async function requestAuthorizationChallenge(
+  options: RequestAuthorizationChallengeOptions,
+): Promise<AuthorizationChallenge> {
+  const expected = target(options.method, options.path);
+  if (!options.token || !isValidSuiAddress(options.address)) {
+    throw new MisoAuthError("challenge_rejected", "A valid Enoki token and Sui address are required.");
+  }
+  const apiUrl = new URL(options.apiUrl);
+  const challengeUrl = options.challengeUrl === undefined
+    ? new URL("/platform/auth/challenge", apiUrl.origin)
+    : new URL(options.challengeUrl, apiUrl);
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const response = await fetcher(challengeUrl, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${options.token}`,
+      [MISO_AUTH_HEADERS.address]: normalizeSuiAddress(options.address),
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(expected),
+  });
+  if (!response.ok) {
+    throw new MisoAuthError("challenge_rejected", await responseMessage(response), { status: response.status });
+  }
+  const body = await response.json().catch(() => null);
+  return parseChallenge(body, {
+    ...expected,
+    address: options.address,
+    network: options.network,
+    nowMs: options.nowMs,
+  });
+}
+
+export interface CreateAuthorizationHeadersOptions extends RequestAuthorizationChallengeOptions {
+  signer: PersonalMessageSigner;
+}
+
+/** Verify the challenge locally, sign it as a Sui personal message, and produce API headers. */
+export async function createAuthorizationHeaders(
+  options: CreateAuthorizationHeadersOptions,
+): Promise<{ challenge: AuthorizationChallenge; headers: Headers }> {
+  const challenge = await requestAuthorizationChallenge(options);
+  let signature: string;
+  try {
+    const signed = await options.signer.signPersonalMessage(new TextEncoder().encode(challenge.payload));
+    signature = signed.signature;
+  } catch (cause) {
+    throw new MisoAuthError("signing_failed", "The authorization request was not signed.", { cause });
+  }
+  if (!signature) {
+    throw new MisoAuthError("signing_failed", "The signer returned an empty authorization signature.");
+  }
+  return {
+    challenge,
+    headers: new Headers({
+      Authorization: `Bearer ${options.token}`,
+      [MISO_AUTH_HEADERS.address]: challenge.address,
+      [MISO_AUTH_HEADERS.signature]: signature,
+      [MISO_AUTH_HEADERS.issuedAt]: challenge.issuedAt,
+    }),
+  };
+}
+
+export interface AuthenticatedFetchOptions extends RequestInit {
+  auth: {
+    token: string;
+    address: string;
+    signer: PersonalMessageSigner;
+    network?: AuthNetwork;
+  };
+  challengeUrl?: string | URL;
+  fetch?: typeof globalThis.fetch;
+}
+
+/** Perform a protected Miso API mutation with a fresh Enoki-verified Sui signature. */
+export async function authenticatedFetch(
+  input: string | URL,
+  options: AuthenticatedFetchOptions,
+): Promise<Response> {
+  const { auth, challengeUrl, fetch: fetchOption, ...init } = options;
+  const url = new URL(input);
+  const method = (init.method ?? "").toUpperCase();
+  if (url.search || url.hash) {
+    throw new MisoAuthError("invalid_target", "Authenticated request URLs cannot include a query or fragment.");
+  }
+  const fetcher = fetchOption ?? globalThis.fetch;
+  const authorization = await createAuthorizationHeaders({
+    apiUrl: url,
+    challengeUrl,
+    fetch: fetcher,
+    token: auth.token,
+    address: auth.address,
+    signer: auth.signer,
+    network: auth.network,
+    method,
+    path: url.pathname,
+  });
+  const headers = new Headers(init.headers);
+  authorization.headers.forEach((value, name) => headers.set(name, value));
+  return fetcher(url, { ...init, method, headers });
+}