@sixb/core 0.1.16 → 0.1.18

package/src/blob-storage/download-urls.ts

@@ -0,0 +1,138 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto"
+import type { FileDownloadGrantRecord, FileDownloadGrantStorage, Storage } from "../storage"
+import { BlobStorageError } from "./errors"
+import type { BlobStorage, FileRef } from "./types"
+import { isFileRef } from "./validation"
+
+/**
+ * Download URLs let a third party that cannot hold a Sixb session — a social network fetching
+ * media to publish, for instance — read one file for a bounded time.
+ *
+ * Each URL carries a random token. Storage keeps only its SHA-256, with the file, the expiry, and
+ * the execution that issued it. The API looks the token up on every request, so any process
+ * sharing the storage can issue a URL, and a URL can be revoked before it expires.
+ *
+ * The API serves the bytes itself rather than redirecting to the blob provider: fetchers such as
+ * TikTok refuse redirects and accept only hosts whose ownership the developer verified.
+ */
+
+/** Path prefix of the public route that serves download URLs. */
+export const FILE_DOWNLOAD_ROUTE_PREFIX = "/api/files/downloads/"
+
+const DEFAULT_EXPIRY_MS = 60 * 60 * 1000
+// SQLite compares ISO timestamps as text, which orders them correctly only for four-digit years.
+const LATEST_EXPIRY_MS = Date.UTC(9999, 11, 31, 23, 59, 59, 999)
+/** 32 random bytes in base64url. */
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/
+
+export interface CreateFileDownloadUrlOptions {
+  /** How long the URL stays valid. Defaults to one hour. */
+  readonly expiresInMs?: number
+}
+
+export interface FileDownloadUrl {
+  /** Pass to `blobs.revokeDownloadUrl()` to stop the URL before it expires. */
+  readonly id: string
+  readonly url: string
+  readonly expiresAt: Date
+}
+
+/** What issuing and revoking need from the execution that asks. */
+export interface FileDownloadUrlContext {
+  readonly projectId: string
+  readonly storage: Storage
+  readonly blobStorage: BlobStorage
+  readonly executionId: string
+  readonly apiPublicOrigin: string | undefined
+}
+
+export async function createFileDownloadUrl(
+  context: FileDownloadUrlContext,
+  file: FileRef,
+  options: CreateFileDownloadUrlOptions = {}
+): Promise<FileDownloadUrl> {
+  if (!isFileRef(file)) {
+    throw new Error("[Sixb] blobs.createDownloadUrl() requires a valid file reference.")
+  }
+  const createdAt = new Date()
+  const expiresAt = expiryFrom(createdAt, options.expiresInMs ?? DEFAULT_EXPIRY_MS)
+  const grants = requireGrantStorage(context.storage)
+  if (context.apiPublicOrigin === undefined) {
+    throw new Error(
+      "[Sixb] blobs.createDownloadUrl() needs the API's public origin. Set SIXB_API_PUBLIC_ORIGIN for the API and every worker."
+    )
+  }
+  // Fail here, not when a third party fetches the URL minutes later and gets a bare 404.
+  const stat = await context.blobStorage.stat(file.blobId)
+  if (!stat || stat.digest !== file.digest || stat.sizeBytes !== file.sizeBytes) {
+    throw new BlobStorageError(`[Sixb] No stored blob matches file '${file.blobId}'.`)
+  }
+
+  const token = randomBytes(32).toString("base64url")
+  const { logicalPath: _logicalPath, ...served } = file
+  const grant: FileDownloadGrantRecord = {
+    id: `filedownload_${randomUUID()}`,
+    projectId: context.projectId,
+    tokenHash: hashToken(token),
+    file: served,
+    executionId: context.executionId,
+    createdAt,
+    expiresAt,
+  }
+  await grants.create(grant)
+
+  return {
+    id: grant.id,
+    url: new URL(`${FILE_DOWNLOAD_ROUTE_PREFIX}${token}`, context.apiPublicOrigin).toString(),
+    expiresAt: grant.expiresAt,
+  }
+}
+
+export async function revokeFileDownloadUrl(
+  context: FileDownloadUrlContext,
+  id: string
+): Promise<void> {
+  const revoked = await requireGrantStorage(context.storage).revoke({
+    projectId: context.projectId,
+    id,
+    revokedAt: new Date(),
+  })
+  if (!revoked) {
+    throw new Error(`[Sixb] Download URL '${id}' does not exist.`)
+  }
+}
+
+/** The file a token serves, or `null` when the token is unknown, expired, or revoked. */
+export async function resolveFileDownload(
+  host: { readonly id: string; readonly storage: Storage },
+  token: string
+): Promise<FileRef | null> {
+  const grants = host.storage.fileDownloadGrants
+  if (!grants || !TOKEN_PATTERN.test(token)) return null
+
+  const grant = await grants.findByTokenHash({ projectId: host.id, tokenHash: hashToken(token) })
+  if (!grant || grant.revokedAt || grant.expiresAt.getTime() <= Date.now()) return null
+  return grant.file
+}
+
+function hashToken(token: string): string {
+  return createHash("sha256").update(token).digest("hex")
+}
+
+function requireGrantStorage(storage: Storage): FileDownloadGrantStorage {
+  if (!storage.fileDownloadGrants) {
+    throw new Error("[Sixb] Download URLs require storage.fileDownloadGrants.")
+  }
+  return storage.fileDownloadGrants
+}
+
+function expiryFrom(createdAt: Date, expiresInMs: number): Date {
+  if (!Number.isSafeInteger(expiresInMs) || expiresInMs <= 0) {
+    throw new Error("[Sixb] expiresInMs must be a positive integer.")
+  }
+  const expiresAt = createdAt.getTime() + expiresInMs
+  if (expiresAt > LATEST_EXPIRY_MS) {
+    throw new Error("[Sixb] expiresInMs must end before the year 10000.")
+  }
+  return new Date(expiresAt)
+}

package/src/blob-storage/execution.ts

@@ -1,6 +1,14 @@
 import { assertProviderAccess } from "../authorization"
 import type { ExecutionContext } from "../execution"
 import type { SixbRuntimeContext } from "../runtime/types"
+import {
+  type CreateFileDownloadUrlOptions,
+  createFileDownloadUrl,
+  type FileDownloadUrl,
+  type FileDownloadUrlContext,
+  revokeFileDownloadUrl,
+} from "./download-urls"
+import { canonicalMediaType } from "./media-type"
 import type {
   AbortBlobUploadInput,
   BlobByteRange,
@@ -21,6 +29,13 @@ export interface BlobsRuntime {
   put(input: PutBlobInput): Promise<FileRef>
   open(blobId: string): Promise<ReadableStream<Uint8Array>>
   stat(blobId: string): Promise<BlobInfo | null>
+  /**
+   * A URL anyone can use to read this file until it expires or is revoked, for services that
+   * fetch media themselves. Requires the API's public origin (`SIXB_API_PUBLIC_ORIGIN`).
+   */
+  createDownloadUrl(file: FileRef, options?: CreateFileDownloadUrlOptions): Promise<FileDownloadUrl>
+  /** Stop a URL from `createDownloadUrl()` before it expires. */
+  revokeDownloadUrl(id: string): Promise<void>
   openRange?(blobId: string, range: BlobByteRange): Promise<ReadableStream<Uint8Array>>
   createUpload?(input: CreateBlobUploadInput): Promise<BlobUploadSession>
   signUploadPart?(input: SignBlobUploadPartInput): Promise<SignedBlobUploadPart>
@@ -31,12 +46,22 @@ export interface BlobsRuntime {
 export function createBlobsRuntime(
   runtime: SixbRuntimeContext,
   execution: ExecutionContext,
-  blobStorage: BlobStorage
+  blobStorage: BlobStorage,
+  apiPublicOrigin: () => string | undefined
 ): BlobsRuntime {
   const assertAccess = () => assertProviderAccess(runtime, execution, "blobs.access")
+  // Read the origin per call: the server or CLI may record it after this SDK was bound.
+  const downloadUrlContext = (): FileDownloadUrlContext => ({
+    projectId: runtime.projectId,
+    storage: runtime.storage,
+    blobStorage,
+    executionId: execution.id,
+    apiPublicOrigin: apiPublicOrigin(),
+  })
   const executionBlobs: BlobsRuntime = {
     put: (input) => {
       assertAccess()
+      assertMediaType("put", input.mediaType)
       return blobStorage.put(input)
     },
     open: (blobId) => {
@@ -47,6 +72,14 @@ export function createBlobsRuntime(
       assertAccess()
       return blobStorage.stat(blobId)
     },
+    createDownloadUrl: async (file, options) => {
+      assertAccess()
+      return createFileDownloadUrl(downloadUrlContext(), file, options)
+    },
+    revokeDownloadUrl: async (id) => {
+      assertAccess()
+      return revokeFileDownloadUrl(downloadUrlContext(), id)
+    },
   }
 
   if (supportsRangeRead(blobStorage)) {
@@ -58,6 +91,7 @@ export function createBlobsRuntime(
   if (supportsDirectUpload(blobStorage)) {
     executionBlobs.createUpload = (input) => {
       assertAccess()
+      assertMediaType("createUpload", input.mediaType)
       return blobStorage.createUpload(input)
     }
     executionBlobs.signUploadPart = (input) => {
@@ -66,6 +100,7 @@ export function createBlobsRuntime(
     }
     executionBlobs.completeUpload = (input) => {
       assertAccess()
+      assertMediaType("completeUpload", input.mediaType)
       return blobStorage.completeUpload(input)
     }
     executionBlobs.abortUpload = (input) => {
@@ -76,3 +111,11 @@ export function createBlobsRuntime(
 
   return Object.freeze(executionBlobs)
 }
+
+function assertMediaType(method: string, mediaType: string | undefined): void {
+  if (mediaType !== undefined && canonicalMediaType(mediaType) === null) {
+    throw new Error(
+      `[Sixb] blobs.${method}() mediaType must be one media type, such as "application/pdf". Received ${JSON.stringify(mediaType)}.`
+    )
+  }
+}

package/src/blob-storage/file-content.ts

@@ -0,0 +1,106 @@
+import type { BlobInfo, BlobStorage, FileRef, OpenedFileRef } from "./types"
+import { isFileRef } from "./validation"
+
+/**
+ * A file is served only through the record that references it: the caller reads that record with
+ * its own authority, resolves the FileRef inside it, then checks the FileRef against the stored
+ * blob. File content routes and the SDK's `file().open()` share these steps.
+ */
+
+/** The FileRef at a JSON Pointer in an authorized record, or null when none is there. */
+export function resolveFileRefAtPath(root: unknown, path: string): FileRef | null {
+  const value = resolveJsonPointer(root, path)
+  return isFileRef(value) ? value : null
+}
+
+/** The stored blob a FileRef names, or null when it is absent or no longer matches it. */
+export async function statFileRef(
+  blobStorage: Pick<BlobStorage, "stat">,
+  fileRef: FileRef
+): Promise<BlobInfo | null> {
+  const stat = await blobStorage.stat(fileRef.blobId)
+  return stat &&
+    stat.blobId === fileRef.blobId &&
+    stat.digest === fileRef.digest &&
+    stat.sizeBytes === fileRef.sizeBytes
+    ? stat
+    : null
+}
+
+/**
+ * Open a FileRef resolved from an authorized record, or return null when its blob is gone. The
+ * blob itself is opened on the body's first read, so a body nobody reads holds nothing.
+ */
+export async function openFileRef(
+  blobStorage: Pick<BlobStorage, "stat" | "open">,
+  fileRef: FileRef
+): Promise<OpenedFileRef | null> {
+  const stat = await statFileRef(blobStorage, fileRef)
+  if (!stat) return null
+  return { fileRef, body: openOnFirstRead(blobStorage, fileRef.blobId) }
+}
+
+function openOnFirstRead(
+  blobStorage: Pick<BlobStorage, "open">,
+  blobId: string
+): ReadableStream<Uint8Array> {
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined
+  return new ReadableStream<Uint8Array>(
+    {
+      async pull(controller) {
+        reader ??= (await blobStorage.open(blobId)).getReader()
+        const { done, value } = await reader.read()
+        if (done) controller.close()
+        else controller.enqueue(value)
+      },
+      async cancel(reason) {
+        await reader?.cancel(reason)
+      },
+    },
+    // No read-ahead: the first pull waits for the first read.
+    { highWaterMark: 0 }
+  )
+}
+
+/** Escape one segment of a JSON Pointer. */
+export function jsonPointerSegment(segment: string | number): string {
+  return String(segment).replaceAll("~", "~0").replaceAll("/", "~1")
+}
+
+function resolveJsonPointer(root: unknown, pointer: string): unknown {
+  if (pointer === "") {
+    return root
+  }
+
+  if (!pointer.startsWith("/")) {
+    return undefined
+  }
+
+  let current = root
+  for (const rawSegment of pointer.slice(1).split("/")) {
+    const segment = decodeJsonPointerSegment(rawSegment)
+    if (Array.isArray(current)) {
+      const index = Number.parseInt(segment, 10)
+      if (!Number.isInteger(index) || index < 0 || index.toString() !== segment) {
+        return undefined
+      }
+      if (!Object.hasOwn(current, segment)) {
+        return undefined
+      }
+      current = current[index]
+      continue
+    }
+
+    if (typeof current !== "object" || current === null || !Object.hasOwn(current, segment)) {
+      return undefined
+    }
+
+    current = (current as Record<string, unknown>)[segment]
+  }
+
+  return current
+}
+
+function decodeJsonPointerSegment(segment: string): string {
+  return segment.replaceAll("~1", "/").replaceAll("~0", "~")
+}

package/src/blob-storage/index.ts

@@ -21,6 +21,7 @@ export type {
   DirectPutBlobUploadSession,
   DirectUploadBlobStorage,
   MultipartBlobUploadSession,
+  OpenedFileRef,
   PutBlobInput,
   RangeReadableBlobStorage,
   SignBlobUploadPartInput,

package/src/blob-storage/internal.ts

@@ -0,0 +1,8 @@
+export { FILE_DOWNLOAD_ROUTE_PREFIX, resolveFileDownload } from "./download-urls"
+export {
+  jsonPointerSegment,
+  openFileRef,
+  resolveFileRefAtPath,
+  statFileRef,
+} from "./file-content"
+export { canonicalMediaType } from "./media-type"

package/src/blob-storage/media-type.ts

@@ -0,0 +1,29 @@
+// One media type as RFC 9110 defines it: `type/subtype`, each a token, then optional
+// `;name=value` parameters whose value is a token or a quoted string. Stricter than the RFC where
+// leniency only invites a second reading: no surrounding whitespace, no empty parameters, no
+// escapes, and no comma anywhere. Browsers read a comma-separated value as a list of types and
+// use the last valid one, so a value with a comma can mean something other than its first type.
+const TOKEN = "[!#$%&'*+.^_`|~0-9A-Za-z-]+"
+const QUOTED_STRING = '"[\\t\\x20\\x21\\x23-\\x2b\\x2d-\\x5b\\x5d-\\x7e]*"'
+const PARAMETER = `[\\t ]*;[\\t ]*(${TOKEN})=(${TOKEN}|${QUOTED_STRING})`
+const MEDIA_TYPE_PATTERN = new RegExp(`^(${TOKEN})/(${TOKEN})((?:${PARAMETER})*)$`)
+const PARAMETER_PATTERN = new RegExp(PARAMETER, "g")
+
+/**
+ * The canonical form of a single well-formed media type, or `null` for anything else.
+ *
+ * Type, subtype, and parameter names are case-insensitive, so they are lowercased; parameter
+ * values keep their case. `"Text/Plain; Charset=UTF-8"` becomes `"text/plain;charset=UTF-8"`.
+ */
+export function canonicalMediaType(value: unknown): string | null {
+  if (typeof value !== "string") return null
+  const match = MEDIA_TYPE_PATTERN.exec(value)
+  if (!match) return null
+
+  const [, type, subtype, parameters] = match
+  let canonical = `${type.toLowerCase()}/${subtype.toLowerCase()}`
+  for (const [, name, parameterValue] of parameters.matchAll(PARAMETER_PATTERN)) {
+    canonical += `;${name.toLowerCase()}=${parameterValue}`
+  }
+  return canonical
+}

package/src/blob-storage/types.ts

@@ -7,7 +7,9 @@ export type BlobDigest = `sha256:${string}`
  * `blobId` is always `blob_<sha256 hex>` derived from `digest`. `fileName`,
  * `mediaType`, and `logicalPath` are caller-supplied per-reference metadata (not
  * part of blob identity) and are untrusted — consumers must sanitize them before
- * using them for paths, headers, or rendering.
+ * using them for paths, headers, or rendering. A caller storing a reference must give a
+ * single media type such as `image/png` (`isValidFileRef`); references stored earlier may
+ * hold anything, so file routes re-parse it before serving.
  */
 export interface FileRef {
   readonly blobId: string
@@ -20,6 +22,16 @@ export interface FileRef {
 
 export type BlobBody = ArrayBuffer | Uint8Array | Blob | ReadableStream<Uint8Array>
 
+/** A FileRef opened through the record that references it. */
+export interface OpenedFileRef {
+  readonly fileRef: FileRef
+  /**
+   * The file's bytes. The stored blob is opened on the first read: read the body to its end or
+   * cancel it, and a body never read holds nothing.
+   */
+  readonly body: ReadableStream<Uint8Array>
+}
+
 export interface PutBlobInput {
   readonly body: BlobBody
   /** Reject the write when the consumed byte count differs from this value. */

package/src/blob-storage/validation.ts

@@ -1,5 +1,6 @@
 import { isPlainRecord } from "../json"
 import { blobIdFromDigest } from "./derive"
+import { canonicalMediaType } from "./media-type"
 import type {
   BlobDigest,
   BlobStorage,
@@ -30,6 +31,18 @@ export function isFileRef(value: unknown): value is FileRef {
   )
 }
 
+/**
+ * `isFileRef`, plus a `mediaType` that, when present, is exactly one media type. Paths that store
+ * a reference a caller hands them use this. Reads keep `isFileRef`, so references stored before
+ * the rule still load; file routes re-parse the type before serving it.
+ */
+export function isValidFileRef(value: unknown): value is FileRef {
+  return (
+    isFileRef(value) &&
+    (value.mediaType === undefined || canonicalMediaType(value.mediaType) !== null)
+  )
+}
+
 export function supportsDirectUpload(
   storage: BlobStorage
 ): storage is BlobStorage & DirectUploadBlobStorage {