Skip to content
← Public packages

@kody/dropbox

Reusable Dropbox OAuth helpers for account, metadata, search, file transfer, sharing, and generic API requests.

FollowFork

Files

content-hash.ts

107 lines · 3.6 KB · TypeScript
/**
 * Compute a Dropbox `content_hash` so callers can verify an upload.
 * Dropbox splits the file into 4 MiB blocks, takes the SHA-256 of each block,
 * concatenates those digests, and takes the SHA-256 of the result (hex).
 *
 * @example
 * import { dropboxContentHash } from 'kody:@kody/dropbox/content-hash'
 * const hash = await dropboxContentHash(bytes)
 * // compare with metadata.content_hash from get-metadata or a finished upload
 */

import { decodeBase64 } from './base64.ts'
import { requireRecord, requireString } from './types.ts'

/** Block size Dropbox uses for `content_hash` (4 MiB). */
export const DROPBOX_CONTENT_HASH_BLOCK_BYTES = 4 * 1024 * 1024

async function sha256(bytes: Uint8Array): Promise<Uint8Array> {
	const digest = await crypto.subtle.digest('SHA-256', bytes as BufferSource)
	return new Uint8Array(digest)
}

function toHex(bytes: Uint8Array): string {
	let hex = ''
	for (const byte of bytes) hex += byte.toString(16).padStart(2, '0')
	return hex
}

export type DropboxContentHasher = {
	/** Feed the next bytes of the file, in order. */
	update(bytes: Uint8Array): Promise<void>
	/** Finish and return the hex `content_hash`. The hasher cannot be reused. */
	digest(): Promise<string>
	/** Total bytes fed so far. */
	readonly byteLength: number
}

/**
 * Incremental Dropbox content hasher for data that arrives in pieces (for
 * example one upload chunk at a time). Feed bytes in file order.
 */
export function createDropboxContentHasher(): DropboxContentHasher {
	const blockDigests: Uint8Array[] = []
	let pending = new Uint8Array(0)
	let total = 0
	let finished = false

	return {
		get byteLength() {
			return total
		},
		async update(bytes: Uint8Array) {
			if (finished) throw new Error('content hasher already finished.')
			total += bytes.byteLength
			let input = bytes
			if (pending.byteLength > 0) {
				const merged = new Uint8Array(pending.byteLength + input.byteLength)
				merged.set(pending, 0)
				merged.set(input, pending.byteLength)
				input = merged
			}
			let offset = 0
			while (input.byteLength - offset >= DROPBOX_CONTENT_HASH_BLOCK_BYTES) {
				blockDigests.push(
					await sha256(input.subarray(offset, offset + DROPBOX_CONTENT_HASH_BLOCK_BYTES)),
				)
				offset += DROPBOX_CONTENT_HASH_BLOCK_BYTES
			}
			pending = input.slice(offset)
		},
		async digest() {
			if (finished) throw new Error('content hasher already finished.')
			finished = true
			if (pending.byteLength > 0) blockDigests.push(await sha256(pending))
			const joined = new Uint8Array(blockDigests.length * 32)
			blockDigests.forEach((digest, index) => joined.set(digest, index * 32))
			return toHex(await sha256(joined))
		},
	}
}

/** Dropbox `content_hash` (hex) of the given bytes. */
export async function dropboxContentHash(bytes: Uint8Array): Promise<string> {
	const hasher = createDropboxContentHasher()
	await hasher.update(bytes)
	return hasher.digest()
}

/**
 * Compute the Dropbox `content_hash` of `bytesBase64` (pass it in execute
 * params). Read-only; never calls Dropbox.
 *
 * @example
 * import contentHash from 'kody:@kody/dropbox/content-hash'
 * const { contentHash: hash, byteLength } = await contentHash({ bytesBase64: params.bytesBase64 })
 */
export default async function contentHashEntrypoint(
	params: { bytesBase64?: string } & Record<string, unknown> = {},
) {
	const input = requireRecord(params, 'content-hash')
	const bytes = decodeBase64(requireString(input.bytesBase64, 'bytesBase64', { allowEmpty: true }))
	return {
		contentHash: await dropboxContentHash(bytes),
		byteLength: bytes.byteLength,
		blockBytes: DROPBOX_CONTENT_HASH_BLOCK_BYTES,
	}
}