feat: support signed urls

Author: rdunk

package.json

@@ -9,6 +9,12 @@
       "import": "./lib/index.js",
       "default": "./lib/index.js"
     },
+    "./signed": {
+      "source": "./src/signed/index.ts",
+      "import": "./lib/signed/index.js",
+      "require": "./lib/signed/index.cjs",
+      "default": "./lib/signed/index.js"
+    },
     "./package.json": "./package.json"
   },
   "main": "./lib/index.js",
@@ -79,5 +85,9 @@
     "content",
     "image-url"
   ],
+  "dependencies": {
+    "@noble/ed25519": "^3.0.0",
+    "@noble/hashes": "^2.0.0"
+  },
   "packageManager": "[email protected]"
 }

pnpm-lock.yaml

@@ -29,7 +29,10 @@ function isSanityClientLike(
   return client && 'clientConfig' in client ? typeof client.clientConfig === 'object' : false
 }
 
-function rewriteSpecName(key: string) {
+/**
+ * @internal
+ */
+export function rewriteSpecName(key: string) {
   const specs = SPEC_NAME_TO_URL_NAME_MAPPINGS
   for (const entry of specs) {
     const [specName, param] = entry
@@ -42,42 +45,57 @@ function rewriteSpecName(key: string) {
 }
 
 /**
- * @public
+ * @internal
  */
-export function urlBuilder(
-  options?: SanityClientLike | SanityProjectDetails | SanityModernClientLike
-) {
-  // Did we get a modernish client?
-  if (isSanityModernClientLike(options)) {
+export function createBuilder<C extends typeof ImageUrlBuilder>(
+  Builder: C,
+  _options?: SanityClientLike | SanityProjectDetails | SanityModernClientLike
+): InstanceType<C> {
+  let options: ConstructorParameters<C>[1] = {}
+
+  if (isSanityModernClientLike(_options)) {
     // Inherit config from client
-    const {apiHost: apiUrl, projectId, dataset} = options.config()
+    const {apiHost: apiUrl, projectId, dataset} = _options.config()
     const apiHost = apiUrl || 'https://api.sanity.io'
-    return new ImageUrlBuilder(null, {
+    options = {
       baseUrl: apiHost.replace(/^https:\/\/api\./, 'https://cdn.'),
       projectId,
       dataset,
-    })
+    }
   }
 
   // Did we get a SanityClient?
-  if (isSanityClientLike(options)) {
+  else if (isSanityClientLike(_options)) {
     // Inherit config from client
-    const {apiHost: apiUrl, projectId, dataset} = options.clientConfig
+    const {apiHost: apiUrl, projectId, dataset} = _options.clientConfig
     const apiHost = apiUrl || 'https://api.sanity.io'
-    return new ImageUrlBuilder(null, {
+    options = {
       baseUrl: apiHost.replace(/^https:\/\/api\./, 'https://cdn.'),
       projectId,
       dataset,
-    })
+    }
   }
 
   // Or just accept the options as given
-  return new ImageUrlBuilder(null, options || {})
+  else {
+    options = _options || {}
+  }
+
+  return new Builder(null, options) as InstanceType<C>
 }
 
 /**
  * @internal
  */
+export function urlBuilder(
+  options?: SanityClientLike | SanityProjectDetails | SanityModernClientLike
+) {
+  return createBuilder(ImageUrlBuilder, options)
+}
+
+/**
+ * @public
+ */
 export class ImageUrlBuilder {
   public options: ImageUrlBuilderOptions
 
@@ -87,7 +105,7 @@ export class ImageUrlBuilder {
       : {...(options || {})} // Copy options
   }
 
-  withOptions(options: Partial<ImageUrlBuilderOptionsWithAliases>) {
+  protected constructNewOptions(options: Partial<ImageUrlBuilderOptionsWithAliases>) {
     const baseUrl = options.baseUrl || this.options.baseUrl
 
     const newOptions: {[key: string]: any} = {baseUrl}
@@ -97,8 +115,12 @@ export class ImageUrlBuilder {
         newOptions[specKey] = options[key]
       }
     }
+    return {baseUrl, ...newOptions}
+  }
 
-    return new ImageUrlBuilder(this, {baseUrl, ...newOptions})
+  withOptions(options: Partial<ImageUrlBuilderOptionsWithAliases>): this {
+    const newOptions = this.constructNewOptions(options)
+    return new ImageUrlBuilder(this, newOptions) as this
   }
 
   // The image to be represented. Accepts a Sanity 'image'-document, 'asset'-document or

src/builder.ts

@@ -0,0 +1,29 @@
+export {urlBuilder} from './signed-builder'
+
+export type {
+  AutoMode,
+  CropMode,
+  CropSpec,
+  FitMode,
+  HotspotSpec,
+  ImageFormat,
+  ImageUrlBuilderOptions,
+  ImageUrlBuilderOptionsWithAliases,
+  ImageUrlBuilderOptionsWithAsset,
+  Orientation,
+  SanityAsset,
+  SanityClientLike,
+  SanityImageCrop,
+  SanityImageDimensions,
+  SanityImageFitResult,
+  SanityImageHotspot,
+  SanityImageObject,
+  SanityImageRect,
+  SanityImageSource,
+  SanityImageWithAssetStub,
+  SanityModernClientLike,
+  SanityProjectDetails,
+  SanityReference,
+} from '../types'
+
+export type {ImageUrlSigningOptions, ImageUrlSignedBuilderOptions} from './types'

src/signed/index.ts

@@ -0,0 +1,64 @@
+import {createBuilder, ImageUrlBuilder, rewriteSpecName} from '../builder'
+import {signedUrlForImage} from './signedUrlForImage'
+import type {ImageUrlSignedBuilderOptions, ImageUrlSigningOptions} from './types'
+import type {
+  ImageUrlBuilderOptions,
+  ImageUrlBuilderOptionsWithAliases,
+  SanityClientLike,
+  SanityModernClientLike,
+  SanityProjectDetails,
+} from '../types'
+
+function assertValidSignedOptions(
+  opts: Partial<ImageUrlSigningOptions>
+): asserts opts is ImageUrlSigningOptions {
+  if (typeof opts.keyId !== 'string') {
+    throw new Error('Cannot call `signedUrl()` without `keyId`')
+  }
+
+  if (typeof opts.privateKey !== 'string') {
+    throw new Error('Cannot call `signedUrl()` without `privateKey`')
+  }
+}
+
+/**
+ * @public
+ */
+export class ImageSignedUrlBuilder extends ImageUrlBuilder {
+  public declare options: ImageUrlBuilderOptions & Partial<ImageUrlSigningOptions>
+
+  constructor(parent: ImageSignedUrlBuilder | null, options: ImageUrlSignedBuilderOptions) {
+    super(parent, options)
+  }
+
+  override withOptions(
+    options: Partial<ImageUrlBuilderOptionsWithAliases & ImageUrlSigningOptions>
+  ): this {
+    const newOptions = this.constructNewOptions(options)
+    return new ImageSignedUrlBuilder(this, {...newOptions}) as this
+  }
+
+  expiry(expiry: string | Date) {
+    return this.withOptions({expiry})
+  }
+
+  signingKey(keyId: string, privateKey: string) {
+    return this.withOptions({keyId, privateKey})
+  }
+
+  signedUrl() {
+    const {expiry, keyId, privateKey, ...rest} = this.options
+    const signedOptions = {expiry, keyId, privateKey}
+    assertValidSignedOptions(signedOptions)
+    return signedUrlForImage(rest, signedOptions)
+  }
+}
+
+/**
+ * @public
+ */
+export function urlBuilder(
+  options?: SanityClientLike | SanityProjectDetails | SanityModernClientLike
+) {
+  return createBuilder(ImageSignedUrlBuilder, options)
+}

src/signed/signed-builder.ts

@@ -0,0 +1,85 @@
+import type {ImageUrlBuilderOptions} from '../types'
+import type {ImageUrlSigningOptions} from './types'
+import {etc, hashes, sign} from '@noble/ed25519'
+import {sha512} from '@noble/hashes/sha2.js'
+import {urlForImage} from '../urlForImage'
+
+hashes.sha512 = sha512
+
+// Swap alphabet, keep '=' padding
+function normalizeBase64Url(base64: string): string {
+  return base64.replace(/\+/g, '-').replace(/\//g, '_')
+}
+
+// Go's base64.URLEncoding uses a URL-safe alphabet WITH '=' padding. To match,
+// we need only URL-safe chars, to allow between 0 to 2 '=' at the end, and
+// ensure length is a multiple of 4
+function toBase64UrlWithPadding(bytes: Uint8Array): string {
+  let b64: string
+
+  if (typeof Buffer !== 'undefined') {
+    // Node: Uint8Array → Buffer → base64
+    b64 = Buffer.from(bytes).toString('base64')
+  } else {
+    // Browser: Uint8Array → binary string → btoa
+    // @todo Do we want to allow signing in the browser?
+    const bin = String.fromCharCode(...bytes)
+    b64 = btoa(bin)
+  }
+  // Ensure padding, although likely unnecessary as an Ed25519 signature is
+  // always 64 bytes / 88 chars when encoded in b64
+  if (b64.length % 4) b64 += '='.repeat(4 - (b64.length % 4))
+
+  return normalizeBase64Url(b64)
+}
+
+function normalizeExpiry(expiry: string | Date | undefined): string | undefined {
+  if (!expiry) {
+    return undefined
+  }
+
+  let date: Date
+  if (expiry instanceof Date) {
+    date = expiry
+  } else {
+    date = new Date(expiry)
+    if (isNaN(date.getTime())) {
+      throw new Error('Invalid expiry date format')
+    }
+  }
+
+  const now = new Date()
+  if (date.getTime() < now.getTime()) {
+    throw new Error('Expiry date must be in the future')
+  }
+
+  // Format as 'YYYY-MM-DDTHH:mm:ssZ' (strip milliseconds)
+  return date.toISOString().replace(/\.\d{3}Z$/, 'Z')
+}
+
+export function signedUrlForImage(
+  options: ImageUrlBuilderOptions,
+  signingOptions: ImageUrlSigningOptions
+): string {
+  const {expiry, keyId, privateKey} = signingOptions
+  // Get the base URL without any signing specific parameters
+  const baseUrl = urlForImage(options)
+  // Support expiry as Date or string
+  const expiryString = normalizeExpiry(expiry)
+  // Append keyid and expiry (if present), in that order
+  const sep = baseUrl.includes('?') ? '&' : '?'
+  const query = [`keyid=${keyId}`, expiryString && `expiry=${expiryString}`]
+    .filter(Boolean)
+    .join('&')
+  const urlToSign = `${baseUrl}${sep}${query}`
+  // Encode the URL as bytes
+  const urlBytes = new TextEncoder().encode(urlToSign)
+  // Encode the private key as bytes
+  const privateKeyBytes = etc.hexToBytes(privateKey)
+  // Get the signed URL as bytes
+  const signatureBytes = sign(urlBytes, privateKeyBytes)
+  // Convert the signature to a URL-safe base64 string
+  const signatureBase64 = toBase64UrlWithPadding(signatureBytes)
+  // Construct and return the full signed URL
+  return `${urlToSign}&signature=${signatureBase64}`
+}

src/signed/signedUrlForImage.ts

@@ -0,0 +1,15 @@
+import type {ImageUrlBuilderOptions} from '../types'
+
+/**
+ * @public
+ */
+export interface ImageUrlSigningOptions {
+  keyId: string
+  privateKey: string
+  expiry?: string | Date
+}
+
+/**
+ * @public
+ */
+export type ImageUrlSignedBuilderOptions = ImageUrlBuilderOptions & Partial<ImageUrlSigningOptions>