@teikyo/blob 0.0.0-stage → 0.1.0

package/lib/handlers/index.js

@@ -0,0 +1,153 @@
+import { getLogger } from '@sozai/log';
+import { errorResponse, toErrorResponse } from '../errors.js';
+import { assertUploadLimits } from '../limits.js';
+import { cancelBody } from './body.js';
+import { deleteBlob, listBlobs, pinBlob, unpinBlob } from './manage.js';
+import { getBlob, getBlobManifest, getBlobMeta } from './read.js';
+import { decodeSegment, matchRoute, methodNotAllowed, relativeSegments, resolveBasePath } from './router.js';
+import { uploadBlob } from './write.js';
+export const DEFAULT_BASE_PATH = '/blobs';
+export const DEFAULT_MAX_UPLOAD_SIZE = 104857600;
+export const DEFAULT_UPLOAD_TIMEOUT_MS = 600000;
+const routes = [
+    {
+        method: 'GET',
+        pattern: [
+            ':id'
+        ],
+        handler: getBlob
+    },
+    {
+        method: 'HEAD',
+        pattern: [
+            ':id'
+        ],
+        handler: getBlob
+    },
+    {
+        method: 'GET',
+        pattern: [
+            ':id',
+            'meta'
+        ],
+        handler: getBlobMeta
+    },
+    {
+        method: 'HEAD',
+        pattern: [
+            ':id',
+            'meta'
+        ],
+        handler: getBlobMeta
+    },
+    {
+        method: 'GET',
+        pattern: [
+            ':id',
+            'manifest'
+        ],
+        handler: getBlobManifest
+    },
+    {
+        method: 'HEAD',
+        pattern: [
+            ':id',
+            'manifest'
+        ],
+        handler: getBlobManifest
+    },
+    {
+        method: 'POST',
+        pattern: [],
+        handler: uploadBlob
+    },
+    {
+        method: 'GET',
+        pattern: [],
+        handler: listBlobs
+    },
+    {
+        method: 'HEAD',
+        pattern: [],
+        handler: listBlobs
+    },
+    {
+        method: 'PUT',
+        pattern: [
+            ':id'
+        ],
+        handler: uploadBlob
+    },
+    {
+        method: 'DELETE',
+        pattern: [
+            ':id'
+        ],
+        handler: deleteBlob
+    },
+    {
+        method: 'PUT',
+        pattern: [
+            ':id',
+            'pin'
+        ],
+        handler: pinBlob
+    },
+    {
+        method: 'DELETE',
+        pattern: [
+            ':id',
+            'pin'
+        ],
+        handler: unpinBlob
+    }
+];
+export function createBlobHandlers(params) {
+    const maxUploadSize = params.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE;
+    const uploadTimeoutMs = params.uploadTimeoutMs ?? DEFAULT_UPLOAD_TIMEOUT_MS;
+    assertUploadLimits({
+        maxUploadSize,
+        uploadTimeoutMs,
+        maxBlobSize: params.service.limits.maxBlobSize
+    });
+    const resolved = {
+        ...params,
+        basePath: resolveBasePath(params.basePath ?? DEFAULT_BASE_PATH),
+        maxUploadSize,
+        uploadTimeoutMs,
+        secureTransport: params.secureTransport ?? true,
+        logger: params.logger ?? getLogger([
+            'teikyo',
+            'blob'
+        ])
+    };
+    return async (request, context = {})=>{
+        // Set once a route handler owns the request; every earlier exit releases the body.
+        let dispatched = false;
+        try {
+            const segments = relativeSegments(new URL(request.url).pathname, resolved.basePath);
+            if (segments == null) return errorResponse(404, 'NOT_FOUND');
+            const match = matchRoute(routes, segments, request.method);
+            if (match.type === 'not-found') return errorResponse(404, 'NOT_FOUND');
+            if (match.type === 'method-not-allowed') return methodNotAllowed(match.allow);
+            let blobID;
+            if (match.encodedID != null) {
+                const decoded = decodeSegment(match.encodedID);
+                if (decoded == null) return errorResponse(400, 'INVALID_ID');
+                // Throws InvalidBlobIDError (400) for malformed IDs.
+                blobID = resolved.service.codec.canonicalize(decoded);
+            }
+            dispatched = true;
+            return await match.handler({
+                params: resolved,
+                request,
+                context,
+                blobID
+            });
+        } catch (error) {
+            return toErrorResponse(error, resolved.logger);
+        } finally{
+            if (!dispatched) await cancelBody(request);
+        }
+    };
+}

package/lib/handlers/manage.d.ts

@@ -0,0 +1,5 @@
+import type { RouteHandler } from './types.js';
+export declare const deleteBlob: RouteHandler;
+export declare const pinBlob: RouteHandler;
+export declare const unpinBlob: RouteHandler;
+export declare const listBlobs: RouteHandler;

package/lib/handlers/manage.js

@@ -0,0 +1,81 @@
+import { InvalidCursorError } from '@hozon/store-blob';
+import { errorResponse } from '../errors.js';
+import { authorize } from './guard.js';
+const DEFAULT_LIST_LIMIT = 100;
+const MAX_LIST_LIMIT = 1000;
+const noContent = ()=>new Response(null, {
+        status: 204
+    });
+export const deleteBlob = async (input)=>{
+    const { params, request, context, blobID } = input;
+    if (blobID == null) return errorResponse(404, 'NOT_FOUND');
+    await authorize({
+        guard: params,
+        request,
+        context,
+        action: 'delete',
+        blobID
+    });
+    const deleted = await params.service.delete(blobID);
+    return deleted ? noContent() : errorResponse(404, 'NOT_FOUND');
+};
+function setPinned(pinned) {
+    return async (input)=>{
+        const { params, request, context, blobID } = input;
+        if (blobID == null) return errorResponse(404, 'NOT_FOUND');
+        await authorize({
+            guard: params,
+            request,
+            context,
+            action: 'pin',
+            blobID
+        });
+        // Throws BlobNotFoundError (404) for an unknown blob.
+        await params.service.setPinned(blobID, pinned);
+        return noContent();
+    };
+}
+export const pinBlob = setPinned(true);
+export const unpinBlob = setPinned(false);
+export const listBlobs = async (input)=>{
+    const { params, request, context } = input;
+    await authorize({
+        guard: params,
+        request,
+        context,
+        action: 'list'
+    });
+    const query = new URL(request.url).searchParams;
+    const rawLimit = query.get('limit');
+    let limit = DEFAULT_LIST_LIMIT;
+    if (rawLimit != null) {
+        if (!/^\d+$/.test(rawLimit)) return errorResponse(400, 'INVALID_LIMIT');
+        limit = Number(rawLimit);
+        if (limit < 1 || limit > MAX_LIST_LIMIT) return errorResponse(400, 'INVALID_LIMIT');
+    }
+    const cursor = query.get('cursor') ?? undefined;
+    let page;
+    try {
+        page = await params.service.list({
+            limit,
+            cursor
+        });
+    } catch (error) {
+        // hozon throws InvalidCursorError for a malformed cursor.
+        if (cursor != null && error instanceof InvalidCursorError) {
+            return errorResponse(400, 'INVALID_CURSOR');
+        }
+        throw error;
+    }
+    const { entries, nextCursor } = page;
+    const body = request.method === 'HEAD' ? null : JSON.stringify({
+        entries,
+        nextCursor
+    });
+    return new Response(body, {
+        status: 200,
+        headers: {
+            'Content-Type': 'application/json'
+        }
+    });
+};

package/lib/handlers/read.d.ts

@@ -0,0 +1,4 @@
+import type { RouteHandler } from './types.js';
+export declare const getBlob: RouteHandler;
+export declare const getBlobMeta: RouteHandler;
+export declare const getBlobManifest: RouteHandler;

package/lib/handlers/read.js

@@ -0,0 +1,118 @@
+import { fromUTF, toB64U } from '@sozai/codec';
+import { errorResponse } from '../errors.js';
+import { parseRange } from '../range.js';
+import { authorize } from './guard.js';
+const CACHE_CONTROL = 'private, max-age=31536000, immutable';
+// Stored user content is served on the API origin: forbid sniffing and sandbox any rendering.
+const CONTENT_SECURITY_HEADERS = {
+    'X-Content-Type-Options': 'nosniff',
+    'Content-Security-Policy': 'sandbox'
+};
+/** Whether `If-None-Match` matches the (strong) ETag for `blobID`; weak and listed tags count. */ function matchesIfNoneMatch(header, blobID) {
+    if (header == null) return false;
+    return header.split(',').some((part)=>{
+        const tag = part.trim();
+        if (tag === '*') return true;
+        const strong = tag.startsWith('W/') ? tag.slice(2) : tag;
+        return strong === `"${blobID}"`;
+    });
+}
+function jsonResponse(body, isHead) {
+    const text = JSON.stringify(body);
+    return new Response(isHead ? null : text, {
+        status: 200,
+        headers: {
+            'Content-Type': 'application/json',
+            'Content-Length': String(fromUTF(text).byteLength)
+        }
+    });
+}
+function notFound() {
+    return errorResponse(404, 'NOT_FOUND');
+}
+/** Authorized entry (any state), or a ready 404 response for an unknown blob. */ async function readEntry(input) {
+    const { params, request, context, blobID } = input;
+    if (blobID == null) return notFound();
+    await authorize({
+        guard: params,
+        request,
+        context,
+        action: 'read',
+        blobID
+    });
+    return await params.service.get(blobID) ?? notFound();
+}
+export const getBlob = async (input)=>{
+    const { params, request, blobID } = input;
+    const entry = await readEntry(input);
+    if (entry instanceof Response) return entry;
+    // Plain GET of a non-local blob is 404.
+    if (entry.state !== 'local' || blobID == null) return notFound();
+    const etag = `"${blobID}"`;
+    if (matchesIfNoneMatch(request.headers.get('If-None-Match'), blobID)) {
+        return new Response(null, {
+            status: 304,
+            headers: {
+                ETag: etag,
+                'Cache-Control': CACHE_CONTROL,
+                ...CONTENT_SECURITY_HEADERS
+            }
+        });
+    }
+    const length = entry.contentLength;
+    const headers = new Headers({
+        'Content-Type': entry.contentType || 'application/octet-stream',
+        'Accept-Ranges': 'bytes',
+        ETag: etag,
+        'Cache-Control': CACHE_CONTROL,
+        ...CONTENT_SECURITY_HEADERS
+    });
+    const range = parseRange(request.headers.get('Range'), length);
+    if (range === 'unsatisfiable') {
+        return errorResponse(416, 'RANGE_NOT_SATISFIABLE', {
+            'Content-Range': `bytes */${length}`
+        });
+    }
+    const isHead = request.method === 'HEAD';
+    let status = 200;
+    let contentLength = length;
+    if (range != null) {
+        status = 206;
+        contentLength = range.end - range.start + 1;
+        headers.set('Content-Range', `bytes ${range.start}-${range.end}/${length}`);
+    }
+    headers.set('Content-Length', String(contentLength));
+    if (isHead || contentLength === 0) return new Response(null, {
+        status,
+        headers
+    });
+    const body = await params.service.createReadStream(blobID, range ?? undefined);
+    return new Response(body, {
+        status,
+        headers
+    });
+};
+export const getBlobMeta = async (input)=>{
+    const entry = await readEntry(input);
+    if (entry instanceof Response) return entry;
+    return jsonResponse({
+        contentLength: entry.contentLength,
+        contentType: entry.contentType,
+        state: entry.state,
+        pinned: entry.pinned,
+        createdAt: entry.createdAt,
+        encrypted: entry.encrypted,
+        keyID: entry.keyID
+    }, input.request.method === 'HEAD');
+};
+export const getBlobManifest = async (input)=>{
+    const entry = await readEntry(input);
+    if (entry instanceof Response) return entry;
+    if (entry.state !== 'local' || input.blobID == null) return notFound();
+    const digests = await input.params.service.getChunkDigests(input.blobID);
+    return jsonResponse({
+        contentLength: entry.contentLength,
+        chunkSize: entry.chunkSize,
+        chunks: digests.map((digest)=>toB64U(digest))
+    }, input.request.method === 'HEAD');
+};

package/lib/handlers/router.d.ts

@@ -0,0 +1,31 @@
+import type { RouteHandler } from './types.js';
+export type Route = {
+    method: string;
+    /** Segments after `basePath`; `':id'` captures the blob ID. */
+    pattern: ReadonlyArray<string>;
+    handler: RouteHandler;
+};
+export type RouteMatch = {
+    type: 'matched';
+    handler: RouteHandler;
+    encodedID?: string;
+} | {
+    type: 'method-not-allowed';
+    allow: Array<string>;
+} | {
+    type: 'not-found';
+};
+/** Normalizes `basePath` to a leading slash with no trailing slash (`/` becomes empty). */
+export declare function normalizeBasePath(basePath: string): string;
+/**
+ * Normalizes `basePath` and checks that every segment is plain: unreserved URL characters only,
+ * not empty, `.` or `..`. The root path normalizes to an empty string and is returned as-is.
+ */
+export declare function resolveBasePath(basePath: string): string;
+/** Raw (still percent-encoded) segments after `basePath`, or null when outside it. */
+export declare function relativeSegments(pathname: string, basePath: string): Array<string> | null;
+/** Decodes a path segment exactly once; null when malformed or when the result contains `/`. */
+export declare function decodeSegment(segment: string): string | null;
+/** Matches raw path segments and the method against `routes`; the `:id` segment stays encoded. */
+export declare function matchRoute(routes: ReadonlyArray<Route>, segments: Array<string>, method: string): RouteMatch;
+export declare function methodNotAllowed(allow: Array<string>): Response;

package/lib/handlers/router.js

@@ -0,0 +1,55 @@
+import { errorResponse } from '../errors.js';
+/** Normalizes `basePath` to a leading slash with no trailing slash (`/` becomes empty). */ export function normalizeBasePath(basePath) {
+    const trimmed = basePath.replace(/\/+$/, '');
+    return trimmed === '' || trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+const PLAIN_SEGMENT = /^[A-Za-z0-9._~-]+$/;
+/**
+ * Normalizes `basePath` and checks that every segment is plain: unreserved URL characters only,
+ * not empty, `.` or `..`. The root path normalizes to an empty string and is returned as-is.
+ */ export function resolveBasePath(basePath) {
+    const normalized = normalizeBasePath(basePath);
+    if (normalized === '') return normalized;
+    const valid = normalized.slice(1).split('/').every((segment)=>PLAIN_SEGMENT.test(segment) && segment !== '.' && segment !== '..');
+    if (!valid) throw new Error('basePath must be "/" or plain path segments');
+    return normalized;
+}
+/** Raw (still percent-encoded) segments after `basePath`, or null when outside it. */ export function relativeSegments(pathname, basePath) {
+    if (pathname === basePath) return [];
+    if (!pathname.startsWith(`${basePath}/`)) return null;
+    return pathname.slice(basePath.length + 1).split('/');
+}
+/** Decodes a path segment exactly once; null when malformed or when the result contains `/`. */ export function decodeSegment(segment) {
+    try {
+        const decoded = decodeURIComponent(segment);
+        return decoded.includes('/') ? null : decoded;
+    } catch  {
+        return null;
+    }
+}
+/** Matches raw path segments and the method against `routes`; the `:id` segment stays encoded. */ export function matchRoute(routes, segments, method) {
+    const candidates = routes.filter((route)=>route.pattern.length === segments.length && route.pattern.every((part, index)=>part === ':id' ? segments[index] !== '' : part === segments[index]));
+    if (candidates.length === 0) return {
+        type: 'not-found'
+    };
+    const route = candidates.find((candidate)=>candidate.method === method);
+    if (route == null) {
+        return {
+            type: 'method-not-allowed',
+            allow: [
+                ...new Set(candidates.map((c)=>c.method))
+            ]
+        };
+    }
+    const idIndex = route.pattern.indexOf(':id');
+    return {
+        type: 'matched',
+        handler: route.handler,
+        encodedID: idIndex === -1 ? undefined : segments[idIndex]
+    };
+}
+export function methodNotAllowed(allow) {
+    return errorResponse(405, 'METHOD_NOT_ALLOWED', {
+        Allow: allow.join(', ')
+    });
+}

package/lib/handlers/types.d.ts

@@ -0,0 +1,36 @@
+import type { BlobService } from '@hozon/blob';
+import type { Logger } from '@sozai/log';
+import type { SecureTransportOption } from '../transport.js';
+import type { BlobAuthenticator, BlobAuthorizer, BlobRequestContext } from '../types.js';
+export type BlobHandlersParams = {
+    service: BlobService;
+    authenticator: BlobAuthenticator;
+    authorizer: BlobAuthorizer;
+    /** Default `/blobs`. */
+    basePath?: string;
+    /** Default 100 MiB. */
+    maxUploadSize?: number;
+    /** Default 10 minutes. */
+    uploadTimeoutMs?: number;
+    /** Default `true`. */
+    secureTransport?: SecureTransportOption;
+    logger?: Logger;
+};
+/** Params with defaults applied. */
+export type ResolvedBlobHandlersParams = BlobHandlersParams & {
+    basePath: string;
+    maxUploadSize: number;
+    uploadTimeoutMs: number;
+    secureTransport: SecureTransportOption;
+    logger: Logger;
+};
+export type RouteInput = {
+    params: ResolvedBlobHandlersParams;
+    request: Request;
+    context: BlobRequestContext;
+    /** Canonical blob ID when the route pattern has an `:id` segment. */
+    blobID?: string;
+};
+/** Request handler returned by `createBlobHandlers`. */
+export type BlobHandler = (request: Request, context?: BlobRequestContext) => Promise<Response>;
+export type RouteHandler = (input: RouteInput) => Promise<Response>;

package/lib/handlers/types.js

@@ -0,0 +1 @@
+export { };

package/lib/handlers/write.d.ts

@@ -0,0 +1,3 @@
+import type { RouteHandler } from './types.js';
+/** Shared by `POST /` (no blobID) and `PUT /:id` (expected ID). */
+export declare const uploadBlob: RouteHandler;

package/lib/handlers/write.js

@@ -0,0 +1,78 @@
+import { BlobWriteAbortedError } from '@hozon/blob';
+import { errorResponse } from '../errors.js';
+import { cancelBody } from './body.js';
+import { authorize } from './guard.js';
+const MAX_CONTENT_TYPE_LENGTH = 255;
+/** Parses `Content-Length` into a non-negative integer, `null` when absent, `'invalid'` otherwise. */ function parseContentLength(header) {
+    if (header == null) return null;
+    if (!/^\d+$/.test(header)) return 'invalid';
+    const value = Number(header);
+    return Number.isSafeInteger(value) ? value : 'invalid';
+}
+/** Shared by `POST /` (no blobID) and `PUT /:id` (expected ID). */ export const uploadBlob = async (input)=>{
+    const state = {
+        handedOff: false
+    };
+    try {
+        return await upload(input, state);
+    } finally{
+        // Every early return or throw before the service owns the body releases it.
+        if (!state.handedOff) await cancelBody(input.request);
+    }
+};
+async function upload(input, state) {
+    const { params, request, context, blobID } = input;
+    await authorize({
+        guard: params,
+        request,
+        context,
+        action: 'write',
+        blobID
+    });
+    const contentType = request.headers.get('Content-Type');
+    if (contentType != null && contentType.length > MAX_CONTENT_TYPE_LENGTH) {
+        return errorResponse(400, 'INVALID_CONTENT_TYPE');
+    }
+    const contentLength = parseContentLength(request.headers.get('Content-Length'));
+    if (contentLength === 'invalid') return errorResponse(400, 'INVALID_CONTENT_LENGTH');
+    // Checked before touching the body so an oversized upload is never read.
+    if (contentLength != null && contentLength > params.maxUploadSize) {
+        return errorResponse(413, 'TOO_LARGE');
+    }
+    const timeoutSignal = AbortSignal.timeout(params.uploadTimeoutMs);
+    const signal = AbortSignal.any([
+        request.signal,
+        timeoutSignal
+    ]);
+    const body = request.body ?? new ReadableStream({
+        start: (c)=>c.close()
+    });
+    state.handedOff = true;
+    try {
+        const { entry, created } = await params.service.write({
+            stream: body,
+            maxSize: params.maxUploadSize,
+            signal,
+            contentType: contentType ?? undefined,
+            expectedID: blobID
+        });
+        return new Response(JSON.stringify({
+            id: entry.blobID,
+            contentLength: entry.contentLength,
+            contentType: entry.contentType
+        }), {
+            status: created ? 201 : 200,
+            headers: {
+                'Content-Type': 'application/json'
+            }
+        });
+    } catch (error) {
+        if (error instanceof BlobWriteAbortedError || signal.aborted) {
+            // Benign race: a non-abort error coinciding with the timeout reports 408.
+            // A disconnected client never receives this 499; it only completes the handler contract.
+            if (request.signal.aborted) return errorResponse(499, 'CLIENT_CLOSED');
+            if (timeoutSignal.aborted) return errorResponse(408, 'UPLOAD_TIMEOUT');
+        }
+        throw error;
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,12 @@
+export { type GrantsAuthorizerParams, grantsAuthorizer } from './auth/grants.js';
+export { oauthAuthenticator, requiredScope } from './auth/oauth.js';
+export { type CheckDelegation, type CheckDelegationParams, type TokenAuthenticator, type TokenAuthenticatorParams, tokenAuthenticator, } from './auth/token.js';
+export { createReadCapabilityMinter, DEFAULT_READ_CAPABILITY_TTL_SECONDS, type MintReadCapability, type MintReadCapabilityParams, type ReadCapabilityMinterParams, } from './capability.js';
+export { transportFromHono } from './context.js';
+export { BlobAccessDeniedError, BlobAuthenticationError, BlobInsecureTransportError, errorResponse, toErrorResponse, } from './errors.js';
+export { type BlobHandler, type BlobHandlersParams, createBlobHandlers, DEFAULT_BASE_PATH, DEFAULT_MAX_UPLOAD_SIZE, DEFAULT_UPLOAD_TIMEOUT_MS, } from './handlers/index.js';
+export { BLOB_STORE, type BlobPluginAPI, type BlobPluginParams, blobPlugin, DEFAULT_STAGING_MAX_AGE_MS, } from './plugin.js';
+export { type ParsedRange, parseRange } from './range.js';
+export { capabilityPermission, grantResource } from './resources.js';
+export { isTransportAllowed, type SecureTransportOption } from './transport.js';
+export type { BlobAction, BlobAuthenticator, BlobAuthorizer, BlobPrincipal, BlobRequestContext, TokenPayload, TransportInfo, } from './types.js';

package/lib/index.js

@@ -0,0 +1,11 @@
+export { grantsAuthorizer } from './auth/grants.js';
+export { oauthAuthenticator, requiredScope } from './auth/oauth.js';
+export { tokenAuthenticator } from './auth/token.js';
+export { createReadCapabilityMinter, DEFAULT_READ_CAPABILITY_TTL_SECONDS } from './capability.js';
+export { transportFromHono } from './context.js';
+export { BlobAccessDeniedError, BlobAuthenticationError, BlobInsecureTransportError, errorResponse, toErrorResponse } from './errors.js';
+export { createBlobHandlers, DEFAULT_BASE_PATH, DEFAULT_MAX_UPLOAD_SIZE, DEFAULT_UPLOAD_TIMEOUT_MS } from './handlers/index.js';
+export { BLOB_STORE, blobPlugin, DEFAULT_STAGING_MAX_AGE_MS } from './plugin.js';
+export { parseRange } from './range.js';
+export { capabilityPermission, grantResource } from './resources.js';
+export { isTransportAllowed } from './transport.js';

package/lib/limits.d.ts

@@ -0,0 +1,6 @@
+/** Throws unless `maxUploadSize` is in 1..`maxBlobSize` and `uploadTimeoutMs` a valid timeout. */
+export declare function assertUploadLimits(params: {
+    maxUploadSize: number;
+    uploadTimeoutMs: number;
+    maxBlobSize: number;
+}): void;

package/lib/limits.js

@@ -0,0 +1,11 @@
+// setTimeout/AbortSignal.timeout limit (2^32 - 1).
+const MAX_TIMEOUT_MS = 4294967295;
+/** Throws unless `maxUploadSize` is in 1..`maxBlobSize` and `uploadTimeoutMs` a valid timeout. */ export function assertUploadLimits(params) {
+    const { maxUploadSize, uploadTimeoutMs, maxBlobSize } = params;
+    if (!Number.isSafeInteger(maxUploadSize) || maxUploadSize <= 0 || maxUploadSize > maxBlobSize) {
+        throw new Error('Invalid maxUploadSize');
+    }
+    if (!Number.isSafeInteger(uploadTimeoutMs) || uploadTimeoutMs <= 0 || uploadTimeoutMs > MAX_TIMEOUT_MS) {
+        throw new Error('Invalid uploadTimeoutMs');
+    }
+}

package/lib/plugin.d.ts

@@ -0,0 +1,51 @@
+import { type BlobService, type BlobServiceParams } from '@hozon/blob';
+import type { SigningIdentity } from '@kokuin/token';
+import { type AnyPluginName, type HTTPPlugin } from '@sozai/http-server';
+import { type TokenAuthenticatorParams } from './auth/token.js';
+import { type MintReadCapability } from './capability.js';
+import { type BlobHandler } from './handlers/index.js';
+import type { SecureTransportOption } from './transport.js';
+import type { BlobAction, BlobAuthenticator, BlobAuthorizer } from './types.js';
+export declare const DEFAULT_STAGING_MAX_AGE_MS = 86400000;
+export type BlobPluginParams = Pick<BlobServiceParams, 'backend' | 'codec' | 'chunkSize' | 'lock' | 'limits'> & {
+    /** Default `/blobs`; the root path is rejected. */
+    basePath?: string;
+    /** Default 100 MiB; a positive integer at most the service `maxBlobSize`. */
+    maxUploadSize?: number;
+    /** Default 10 minutes. */
+    uploadTimeoutMs?: number;
+    /** Replaces the default kokuin token authenticator. Not allowed with `oauth`. */
+    authenticator?: BlobAuthenticator;
+    /**
+     * Replaces the default grants authorizer, removing the `access:grants` dependency. With the
+     * default token authenticator, delegated principals reach it only after `checkDelegation`.
+     */
+    authorizer?: BlobAuthorizer;
+    /** This service's identifier, required by the default token authenticator. */
+    audience?: string;
+    verifyOptions?: TokenAuthenticatorParams['verifyOptions'];
+    /** Check invocation tokens and their proofs through `access:revocation` (default authenticator only). */
+    revocation?: boolean;
+    /** OAuth mode through `oauth:resource`, with per-action scopes defaulting to `blob:<action>`. */
+    oauth?: {
+        scopes?: Partial<Record<BlobAction, string>>;
+    };
+    /** Server identity; enables `mintReadCapability`. Default token authenticator only. */
+    signer?: SigningIdentity;
+    /** Default `true`. */
+    secureTransport?: SecureTransportOption;
+    /** Staging older than this is pruned at startup. Default 24 hours, above `uploadTimeoutMs`. */
+    stagingMaxAgeMs?: number;
+};
+export type BlobPluginAPI = {
+    service: BlobService;
+    handlers: BlobHandler;
+    mintReadCapability?: MintReadCapability;
+};
+export declare const BLOB_STORE: import("@sozai/http-server").PluginName<"blob:store", BlobPluginAPI>;
+/**
+ * Serve blob storage on `basePath`. Authenticates with kokuin invocation tokens by default (or
+ * OAuth bearer tokens with `oauth`) and authorizes through `access:grants` unless a custom
+ * `authorizer` is given.
+ */
+export declare function blobPlugin(params: BlobPluginParams): HTTPPlugin<'blob:store', BlobPluginAPI, Array<AnyPluginName>>;