@teikyo/blob 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Le Cam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,205 @@
-# Temporary Holding Version
+# @teikyo/blob
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Blob storage HTTP plugin with access control, for `@sozai/http-server`. It provides the `blob:store` plugin (exported as `BLOB_STORE`), built on `@hozon/blob` (content-addressed storage with ranged reads and peer transfer) and the `hozon:db` plugin from `@teikyo/hozon`.
+
+## Install
+
+```sh
+pnpm add @teikyo/blob @sozai/http-server hono
+```
+
+## Setup
+
+```ts
+import { FSBlobBackend } from '@hozon/blob-node-fs'
+import { createServer } from '@sozai/http-server'
+import { accessGrantsPlugin, accessRevocationPlugin } from '@teikyo/access'
+import { blobPlugin } from '@teikyo/blob'
+import { hozonDBPlugin } from '@teikyo/hozon'
+
+const server = await createServer({
+  plugins: [
+    hozonDBPlugin({ db: './app.db' }),
+    accessGrantsPlugin(),
+    accessRevocationPlugin(),
+    blobPlugin({
+      backend: new FSBlobBackend('./blobs'),
+      audience: 'did:key:z6Mk...', // this service's identifier
+      signer: serverIdentity, // optional: enables mintReadCapability
+      revocation: true, // optional: check tokens through access:revocation
+    }),
+  ],
+})
+```
+
+`dependsOn` follows the configuration: `hozon:db` always, `access:grants` unless a custom `authorizer` is given, `access:revocation` with `revocation: true`, `oauth:resource` with `oauth`.
+
+| Option | Description |
+| --- | --- |
+| `backend` | Required `BlobBackend` (for example `FSBlobBackend`). |
+| `codec`, `chunkSize`, `lock`, `limits` | Passed to the `@hozon/blob` service. |
+| `basePath` | Mount path, `/blobs` by default. The root path is rejected. Each segment is limited to `A-Za-z0-9._~-`; empty, `.` and `..` segments are rejected. |
+| `maxUploadSize` | Upload limit in bytes, 100 MiB by default. A positive integer, at most the service `maxBlobSize`. |
+| `uploadTimeoutMs` | Upload deadline, 10 minutes by default. |
+| `stagingMaxAgeMs` | Staging older than this is pruned at startup, 24 hours by default. Must exceed `uploadTimeoutMs`. |
+| `audience` | This service's identifier. Required by the default token authenticator. |
+| `verifyOptions` | kokuin verifier options (DID resolver, allowed signature methods, custom `verifiers`) for invocation tokens and their delegation proofs. |
+| `revocation` | Check invocation tokens and their proofs through `access:revocation`. Default authenticator only. |
+| `authenticator`, `authorizer` | Replace the defaults. With the default token authenticator, a custom `authorizer` sees delegated principals only once their proof is verified. |
+| `oauth` | `{ scopes? }`: OAuth mode, see below. Not allowed with `authenticator`. |
+| `signer` | Server identity. Enables `mintReadCapability`. Default token authenticator only: not allowed with `oauth` or `authenticator`. |
+| `secureTransport` | Transport gate for read routes, `true` by default. |
+
+The plugin API (`ctx.use(BLOB_STORE)`) exposes `service` (the `@hozon/blob` service, including the peer transfer methods), `handlers` (the framework-free request handler) and, with a `signer`, `mintReadCapability`.
+
+## Default authentication flow
+
+Callers send a kokuin **invocation token**: `Authorization: Bearer <token>`, signed by the caller with `aud` equal to the plugin `audience`, plus `exp` and `jti`.
+
+```ts
+const token = await identity.signToken({
+  aud: 'did:key:z6Mk...', // the plugin `audience`
+  exp: Math.floor(Date.now() / 1000) + 60,
+  jti: crypto.randomUUID(),
+})
+const res = await fetch('https://blobs.example.com/blobs', {
+  method: 'POST',
+  headers: { Authorization: `Bearer ${stringifyToken(token)}`, 'Content-Type': 'image/png' },
+  body: bytes,
+})
+// 201 { "id": "...", "contentLength": 1234, "contentType": "image/png" }
+```
+
+The caller (`iss`) must hold a matching grant in `access:grants`, for example `blob/*` or `blob/read/*`. A direct invocation must not carry `act`, `res` or proof claims, and a server-minted capability is never accepted on its own.
+
+Invocation tokens are bearer credentials: anyone holding one can replay it until its `exp`. The `jti` is for revocation, not replay protection, so keep `exp` short (seconds to a minute) and send tokens over TLS only.
+
+**Delegation.** An invocation with `sub` different from `iss` and a `cap` proof chain acts with the grants of `sub`, provided the verified capability covers the action and resource. Use `mintReadCapability({ blobID, audience, ttlSeconds = 300 })` (needs `signer`; the server identity must hold a `blob/read/*` grant) to give another identity audience-bound read access to one blob. The grantee presents it as proof inside its own invocation (`sub` = server identity, `cap` = the minted capability). `audience` must differ from both the server identity and the service `audience`. Capabilities are revocable by `jti` through `access:revocation`.
+
+Caveats:
+
+- Delegation (`checkDelegation`) is wired only with the default token authenticator. Delegated principals produced by a custom authenticator fail closed with the default authorizer; a custom authorizer receives them as-is, unverified.
+- `BlobPrincipal.delegatedFrom` is a caller-supplied claim (the invocation `sub`), only verified by `checkDelegation`. With the default token authenticator the plugin enforces it for any authorizer: a custom `authorizer` only sees delegated principals whose proof covers the requested action and blob. Embedders using `createBlobHandlers` directly with `tokenAuthenticator` must call its `checkDelegation` in their authorizer before trusting `delegatedFrom`.
+
+## OAuth mode
+
+`blobPlugin({ backend, oauth: {} })` authenticates through `oauth:resource` (`@teikyo/oauth`) instead of kokuin tokens; `audience` is not required. The plugin mounts `requireBearer()` ahead of the blob routes. The default authorizer requires the scope for the action (`blob:<action>` by default, overridable with `oauth.scopes`, for example `{ read: 'files:read' }`) and then the usual grant check for the token subject, so a read-scoped token cannot delete even when its subject holds a delete grant. `revocation` is not available in this mode.
+
+## Resource mapping
+
+One mapping is shared by grants and capabilities. `<id>` is always the canonical blob ID.
+
+| Action | Grant resource | Capability `act` | Capability `res` |
+| --- | --- | --- | --- |
+| read (data, meta, manifest) | `blob/read/<id>` | `blob/read` | `blob/<id>` |
+| write with expected ID | `blob/write/<id>` | `blob/write` | `blob/<id>` |
+| write without ID | `blob/write` | `blob/write` | `blob/*` |
+| delete | `blob/delete/<id>` | `blob/delete` | `blob/<id>` |
+| pin / unpin | `blob/pin/<id>` | `blob/pin` | `blob/<id>` |
+| list | `blob/list` | `blob/list` | `blob/*` |
+
+Grant `blob/read/*` covers reading all blobs and `blob/*` covers every blob action. `list` is a global privilege returning metadata for all blobs.
+
+## Routes
+
+Relative to `basePath`.
+
+| Route | Action | Behavior |
+| --- | --- | --- |
+| `POST /` | write | Raw body, `Content-Type` stored as MIME. 201 new, 200 existing, body `{ id, contentLength, contentType }`. |
+| `PUT /:id` | write | Upload with expected ID. 422 on ID or MIME mismatch. |
+| `GET /:id`, `HEAD /:id` | read | Single `Range` (suffix and open forms), 200/206, 416 with `Content-Range: bytes */N`. `ETag: "<id>"`, immutable `Cache-Control`, `If-None-Match` gives 304. |
+| `GET /:id/meta` | read | `contentLength`, `contentType`, `state`, `pinned`, `createdAt`, `encrypted`, `keyID`. |
+| `GET /:id/manifest` | read | `{ contentLength, chunkSize, chunks }` with base64url chunk digests, local blobs only. Used for peer transfer. |
+| `GET /?limit&cursor`, `HEAD /?limit&cursor` | list | `{ entries, nextCursor }`, `limit` 1-1000 (default 100), `nextCursor` `null` on the last page. Each entry is `{ blobID, contentLength, contentType, state, pinned, createdAt, encrypted, keyID, chunkSize }`, as stored by `@hozon/store-blob` (`createdAt` in epoch milliseconds). |
+| `DELETE /:id` | delete | 204. |
+| `PUT /:id/pin`, `DELETE /:id/pin` | pin | 204. |
+
+Requests are processed in this order: canonicalize the ID (400), transport gate (read, meta and manifest only), authenticate, authorize, then existence and body. Unauthorized callers get 401 (anonymous) or 403 (authenticated), never 404, so they cannot probe for IDs.
+
+Served blobs carry `X-Content-Type-Options: nosniff` and `Content-Security-Policy: sandbox`, because user content is served from the API origin.
+
+Errors are JSON `{ "error": "<CODE>" }`:
+
+| Status | Codes | When |
+| --- | --- | --- |
+| 400 | `INVALID_ID`, `INVALID_CONTENT_TYPE`, `INVALID_CONTENT_LENGTH`, `INVALID_LIMIT`, `INVALID_CURSOR` | Malformed ID, `Content-Type`, `Content-Length` or list query. |
+| 401 | `UNAUTHENTICATED` | Missing or invalid credentials when anonymous access is denied; `WWW-Authenticate: Bearer`. |
+| 403 | `FORBIDDEN`, `INSECURE_TRANSPORT` | An authenticated principal is denied (including revoked tokens), or the transport gate refuses. |
+| 404 | `NOT_FOUND` | Unknown blob, not local, or unknown route. |
+| 405 | `METHOD_NOT_ALLOWED` | Known route, other method; `Allow` header lists the methods. |
+| 408 | `UPLOAD_TIMEOUT` | Upload deadline exceeded. |
+| 413 | `TOO_LARGE` | Upload exceeds the size limit. |
+| 416 | `RANGE_NOT_SATISFIABLE` | Unsatisfiable or multi-range `Range`. |
+| 422 | `ID_MISMATCH`, `CONTENT_TYPE_MISMATCH` | Expected ID or MIME mismatch. |
+| 503 | `UNAVAILABLE` | Backend or store failure, lock timeout; details are logged, never returned. |
+
+A client disconnect during an upload produces no response; its internal `499 CLIENT_CLOSED` is for logs only.
+
+## Transport gate
+
+Read, meta and manifest routes require TLS on the accepted connection, or loopback on both ends. `secureTransport: false` disables the check, and a `(request, context) => boolean` predicate supports deployments behind a TLS-terminating proxy. Proxy headers are never consulted by the default gate. A missing transport context fails closed with 403 `INSECURE_TRANSPORT`.
+
+## Limits
+
+- `maxUploadSize` (default 100 MiB) is checked against `Content-Length` upfront and enforced while streaming (413).
+- `uploadTimeoutMs` (default 10 minutes) aborts the upload, publishes nothing and responds 408. A client disconnect also aborts and cleans up staging.
+- The plugin disables sozai's generic body limit and timeout on `basePath` (`ctx.limits(basePath, { bodyBytes: false, timeoutMs: false })`) because the handler enforces both itself. Downloads have no deadline.
+- The plugin registers a readiness check that lists one entry. It logs an error when the check starts failing and an info line when it recovers, not on every failed probe.
+- There is no automatic GC. Blobs are removed only by an authorized `DELETE`; stale staging is pruned at startup.
+
+## Embedding in another application
+
+`createBlobHandlers` is framework-free: it takes a `Request` and a trusted `BlobRequestContext` (never derived from request headers) and returns a `Response`. Combined with a custom codec and authorizer it integrates blobs into an application with its own access model, for example allowing reads by document reference:
+
+```ts
+import { createBlobService } from '@hozon/blob'
+import { createBlobHandlers } from '@teikyo/blob'
+
+const service = createBlobService({ db, backend, codec: mimeEmbeddingCodec })
+const handle = createBlobHandlers({
+  service,
+  authenticator: async (request) => myAppPrincipal(request),
+  // Deny `list`: v1 has no per-blob filtered listing.
+  authorizer: async ({ action, blobID, principal }) =>
+    action === 'list' ? false : await myAppCanAccess(principal, action, blobID),
+})
+
+const response = await handle(request, {
+  transport: { secure: true, localAddress, remoteAddress },
+})
+```
+
+When the embedded authenticator is `tokenAuthenticator`, the authorizer must check delegated principals itself, since `delegatedFrom` is unverified until then:
+
+```ts
+const tokens = tokenAuthenticator({ audience })
+const handle = createBlobHandlers({
+  service,
+  authenticator: tokens,
+  authorizer: async ({ action, blobID, principal }) => {
+    if (principal == null) return false
+    if (principal.delegatedFrom != null && !(await tokens.checkDelegation({ principal, action, blobID }))) {
+      return false
+    }
+    return await myAppCanAccess(principal, action, blobID)
+  },
+})
+```
+
+With a codec that embeds the content type in the ID, `PUT /:id` without a `Content-Type` stores the embedded type. The same handler is available from the plugin as `api.handlers`.
+
+## Exports
+
+- Plugin: `blobPlugin`, `BLOB_STORE`, `BlobPluginParams`, `BlobPluginAPI`, `DEFAULT_STAGING_MAX_AGE_MS`.
+- Handlers: `createBlobHandlers`, `BlobHandler`, `BlobHandlersParams`, `DEFAULT_BASE_PATH`, `DEFAULT_MAX_UPLOAD_SIZE`, `DEFAULT_UPLOAD_TIMEOUT_MS`; range parsing `parseRange(header, length)` and `ParsedRange`.
+- Authentication and authorization: `tokenAuthenticator`, `TokenAuthenticator`, `TokenAuthenticatorParams`, `CheckDelegation`, `CheckDelegationParams`, `oauthAuthenticator`, `requiredScope(action, scopes?)`, `grantsAuthorizer`, `GrantsAuthorizerParams`.
+- Read capabilities: `createReadCapabilityMinter`, `ReadCapabilityMinterParams`, `MintReadCapability`, `MintReadCapabilityParams`, `DEFAULT_READ_CAPABILITY_TTL_SECONDS`.
+- Request context and auth types: `BlobAction`, `BlobPrincipal`, `TokenPayload`, `TransportInfo`, `BlobRequestContext`, `BlobAuthenticator`, `BlobAuthorizer`.
+- Transport: `transportFromHono(c)`, `isTransportAllowed(option, request, context)`, `SecureTransportOption`.
+- Resource mapping: `grantResource(action, blobID?)` and `capabilityPermission(action, blobID?)`.
+- Errors mapped to JSON responses: `errorResponse`, `toErrorResponse`, `BlobAuthenticationError` (401), `BlobAccessDeniedError` (403), `BlobInsecureTransportError` (403).
+
+## License
+
+MIT

package/lib/auth/grants.d.ts

@@ -0,0 +1,16 @@
+import type { AccessGrants } from '@teikyo/access';
+import type { BlobAction, BlobAuthorizer } from '../types.js';
+import type { CheckDelegation } from './token.js';
+export type GrantsAuthorizerParams = {
+    grants: Pick<AccessGrants, 'allows'>;
+    /** Required for delegated principals; without it they are always denied. */
+    checkDelegation?: CheckDelegation;
+    /** Action to OAuth scope mapping, defaults to `blob:<action>`. Only applies to OAuth principals. */
+    scopes?: Partial<Record<BlobAction, string>>;
+};
+/**
+ * Default authorizer. Denies by default: anonymous, then OAuth scope (when the principal has
+ * `scopes`), then the grant for `subject` (or `delegatedFrom`), then the delegation proof.
+ * Errors from `grants.allows` propagate.
+ */
+export declare function grantsAuthorizer(params: GrantsAuthorizerParams): BlobAuthorizer;

package/lib/auth/grants.js

@@ -0,0 +1,26 @@
+import { grantResource } from '../resources.js';
+import { requiredScope } from './oauth.js';
+/**
+ * Default authorizer. Denies by default: anonymous, then OAuth scope (when the principal has
+ * `scopes`), then the grant for `subject` (or `delegatedFrom`), then the delegation proof.
+ * Errors from `grants.allows` propagate.
+ */ export function grantsAuthorizer(params) {
+    const { grants, checkDelegation, scopes } = params;
+    return async ({ action, blobID, principal })=>{
+        if (principal == null) return false;
+        if (principal.scopes !== undefined && !principal.scopes.includes(requiredScope(action, scopes))) {
+            return false;
+        }
+        const resource = grantResource(action, blobID);
+        if (principal.delegatedFrom == null) {
+            return await grants.allows(principal.subject, resource);
+        }
+        if (!await grants.allows(principal.delegatedFrom, resource)) return false;
+        if (checkDelegation == null) return false;
+        return await checkDelegation({
+            principal,
+            action,
+            blobID
+        }) === true;
+    };
+}

package/lib/auth/oauth.d.ts

@@ -0,0 +1,5 @@
+import type { BlobAction, BlobAuthenticator } from '../types.js';
+/** Authenticator for OAuth mode: the principal is set on the context by adapter middleware. */
+export declare function oauthAuthenticator(): BlobAuthenticator;
+/** OAuth scope required for an action: the mapped scope, defaulting to `blob:<action>`. */
+export declare function requiredScope(action: BlobAction, scopes?: Partial<Record<BlobAction, string>>): string;

package/lib/auth/oauth.js

@@ -0,0 +1,6 @@
+/** Authenticator for OAuth mode: the principal is set on the context by adapter middleware. */ export function oauthAuthenticator() {
+    return async (_request, context)=>context.principal ?? null;
+}
+/** OAuth scope required for an action: the mapped scope, defaulting to `blob:<action>`. */ export function requiredScope(action, scopes) {
+    return scopes?.[action] ?? `blob:${action}`;
+}

package/lib/auth/token.d.ts

@@ -0,0 +1,23 @@
+import { type SignedToken, type VerifyTokenOptions } from '@kokuin/token';
+import type { BlobAction, BlobAuthenticator, BlobPrincipal } from '../types.js';
+export type TokenAuthenticatorParams = {
+    /** This service's identifier; invocation tokens must carry it as `aud`. */
+    audience: string;
+    /** Revocation hook, run on the invocation and on each delegation proof. */
+    revocation?: (token: SignedToken, raw: string) => Promise<void>;
+    verifyOptions?: Pick<VerifyTokenOptions, 'resolver' | 'cache' | 'methods' | 'verifiers'>;
+};
+export type CheckDelegationParams = {
+    principal: BlobPrincipal;
+    action: BlobAction;
+    blobID?: string;
+};
+export type CheckDelegation = (params: CheckDelegationParams) => Promise<boolean>;
+export type TokenAuthenticator = BlobAuthenticator & {
+    /**
+     * Whether the principal's verified delegation proof covers `action` on `blobID`. The principal
+     * must come from this authenticator; mismatched subject/delegatedFrom yield false.
+     */
+    checkDelegation: CheckDelegation;
+};
+export declare function tokenAuthenticator(params: TokenAuthenticatorParams): TokenAuthenticator;

package/lib/auth/token.js

@@ -0,0 +1,88 @@
+import { checkCapability } from '@kokuin/capability';
+import { verifyToken } from '@kokuin/token';
+import { sameDID } from '../did.js';
+import { BlobAccessDeniedError, BlobAuthenticationError } from '../errors.js';
+import { capabilityPermission } from '../resources.js';
+const BEARER = /^Bearer[ \t]+(\S+)[ \t]*$/i;
+export function tokenAuthenticator(params) {
+    const { audience, revocation, verifyOptions = {} } = params;
+    const { resolver, cache, methods, verifiers } = verifyOptions;
+    const authenticate = async (request)=>{
+        const header = request.headers.get('Authorization');
+        if (header == null) return null;
+        const match = BEARER.exec(header);
+        if (match == null) throw new BlobAuthenticationError();
+        const raw = match[1] ?? '';
+        let verified;
+        try {
+            verified = await verifyToken(raw, {
+                resolver,
+                cache,
+                methods,
+                verifiers
+            });
+        } catch (cause) {
+            throw new BlobAuthenticationError('Invalid token', {
+                cause
+            });
+        }
+        const payload = verified.payload;
+        if (typeof payload.iss !== 'string') throw new BlobAuthenticationError();
+        if (typeof payload.aud !== 'string' || !sameDID(payload.aud, audience)) {
+            throw new BlobAuthenticationError('Invalid audience');
+        }
+        if (typeof payload.exp !== 'number') throw new BlobAuthenticationError('Missing expiry');
+        if (typeof payload.jti !== 'string' || payload.jti === '') {
+            throw new BlobAuthenticationError('Missing jti');
+        }
+        const delegated = payload.sub != null && !sameDID(payload.sub, payload.iss);
+        if (delegated) {
+            if (typeof payload.sub !== 'string' || payload.cap == null) {
+                throw new BlobAuthenticationError('Missing proof');
+            }
+            if (payload.act != null || payload.res != null) {
+                throw new BlobAuthenticationError('Capability presented as invocation');
+            }
+        } else if (payload.act != null || payload.res != null || payload.cap != null) {
+            // Capability-shaped: a capability is only valid as proof inside an invocation.
+            throw new BlobAuthenticationError('Capability presented as invocation');
+        }
+        if (revocation != null) {
+            // Any throw from the hook (revoked or lookup failure) maps to 403 BlobAccessDeniedError.
+            try {
+                await revocation(verified, raw);
+            } catch (cause) {
+                throw new BlobAccessDeniedError('Token revoked', {
+                    cause
+                });
+            }
+        }
+        return delegated ? {
+            subject: payload.iss,
+            delegatedFrom: payload.sub,
+            token: payload
+        } : {
+            subject: payload.iss
+        };
+    };
+    const checkDelegation = async ({ principal, action, blobID })=>{
+        const { token, delegatedFrom } = principal;
+        if (token == null || delegatedFrom == null || typeof token.sub !== 'string') return false;
+        if (!sameDID(delegatedFrom, token.sub) || !sameDID(principal.subject, token.iss)) return false;
+        try {
+            await checkCapability(capabilityPermission(action, blobID), token, {
+                verifyToken: revocation,
+                resolver,
+                cache,
+                methods,
+                verifiers
+            });
+            return true;
+        } catch  {
+            return false;
+        }
+    };
+    return Object.assign(authenticate, {
+        checkDelegation
+    });
+}

package/lib/capability.d.ts

@@ -0,0 +1,19 @@
+import { type SigningIdentity } from '@kokuin/token';
+export declare const DEFAULT_READ_CAPABILITY_TTL_SECONDS = 300;
+export type ReadCapabilityMinterParams = {
+    /** Server identity; issuer and subject of minted capabilities. */
+    signer: SigningIdentity;
+    /** This service's identifier; never a valid capability audience. */
+    serviceAudience?: string;
+    /** Maps a blob ID to its canonical form. */
+    canonicalize: (id: string) => string;
+};
+export type MintReadCapabilityParams = {
+    blobID: string;
+    /** Grantee DID. */
+    audience: string;
+    /** Integer in 1-86400, default 300. */
+    ttlSeconds?: number;
+};
+export type MintReadCapability = (params: MintReadCapabilityParams) => Promise<string>;
+export declare function createReadCapabilityMinter(params: ReadCapabilityMinterParams): MintReadCapability;

package/lib/capability.js

@@ -0,0 +1,25 @@
+import { createCapability } from '@kokuin/capability';
+import { stringifyToken } from '@kokuin/token';
+import { sameDID } from './did.js';
+import { capabilityPermission } from './resources.js';
+export const DEFAULT_READ_CAPABILITY_TTL_SECONDS = 300;
+const MAX_TTL_SECONDS = 86400;
+export function createReadCapabilityMinter(params) {
+    const { signer, serviceAudience, canonicalize } = params;
+    return async ({ blobID, audience, ttlSeconds = DEFAULT_READ_CAPABILITY_TTL_SECONDS })=>{
+        if (sameDID(audience, signer.id) || serviceAudience != null && sameDID(audience, serviceAudience)) {
+            throw new Error('Invalid audience');
+        }
+        if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > MAX_TTL_SECONDS) {
+            throw new Error('Invalid ttlSeconds');
+        }
+        const token = await createCapability(signer, {
+            sub: signer.id,
+            aud: audience,
+            exp: Math.floor(Date.now() / 1000) + ttlSeconds,
+            jti: crypto.randomUUID(),
+            ...capabilityPermission('read', canonicalize(blobID))
+        });
+        return stringifyToken(token);
+    };
+}

package/lib/context.d.ts

@@ -0,0 +1,8 @@
+import type { Context } from 'hono';
+import type { TransportInfo } from './types.js';
+/**
+ * Transport info of the connection the Node server accepted, read from the socket behind
+ * `c.env.incoming` (`@hono/node-server`). Never consults request headers. `undefined` when the
+ * request has no Node socket (e.g. `app.request()`), which the default transport gate rejects.
+ */
+export declare function transportFromHono(c: Context): TransportInfo | undefined;

package/lib/context.js

@@ -0,0 +1,16 @@
+/**
+ * Transport info of the connection the Node server accepted, read from the socket behind
+ * `c.env.incoming` (`@hono/node-server`). Never consults request headers. `undefined` when the
+ * request has no Node socket (e.g. `app.request()`), which the default transport gate rejects.
+ */ export function transportFromHono(c) {
+    const env = c.env;
+    const socket = env?.incoming?.socket;
+    if (socket == null) return undefined;
+    const { encrypted, localAddress, remoteAddress } = socket;
+    if (typeof localAddress !== 'string' || typeof remoteAddress !== 'string') return undefined;
+    return {
+        secure: encrypted === true,
+        localAddress,
+        remoteAddress
+    };
+}

package/lib/did.d.ts

@@ -0,0 +1,2 @@
+/** Compare two DIDs after normalization, falling back to string equality for non-DIDs. */
+export declare function sameDID(a: string, b: string): boolean;

package/lib/did.js

@@ -0,0 +1,8 @@
+import { normalizeDID } from '@kokuin/token';
+/** Compare two DIDs after normalization, falling back to string equality for non-DIDs. */ export function sameDID(a, b) {
+    try {
+        return normalizeDID(a) === normalizeDID(b);
+    } catch  {
+        return a === b;
+    }
+}

package/lib/errors.d.ts

@@ -0,0 +1,12 @@
+import type { Logger } from '@sozai/log';
+export declare class BlobAuthenticationError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class BlobAccessDeniedError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class BlobInsecureTransportError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare function errorResponse(status: number, code: string, headers?: HeadersInit): Response;
+export declare function toErrorResponse(error: unknown, logger: Logger): Response;

package/lib/errors.js

@@ -0,0 +1,53 @@
+import { BlobIDMismatchError, BlobLockTimeoutError, BlobNotFoundError, BlobTooLargeError, ContentTypeMismatchError, InvalidBlobIDError, InvalidRangeError } from '@hozon/blob';
+export class BlobAuthenticationError extends Error {
+    constructor(message = 'Authentication failed', options){
+        super(message, options);
+        this.name = 'BlobAuthenticationError';
+    }
+}
+export class BlobAccessDeniedError extends Error {
+    constructor(message = 'Access denied', options){
+        super(message, options);
+        this.name = 'BlobAccessDeniedError';
+    }
+}
+export class BlobInsecureTransportError extends Error {
+    constructor(message = 'Insecure transport', options){
+        super(message, options);
+        this.name = 'BlobInsecureTransportError';
+    }
+}
+export function errorResponse(status, code, headers) {
+    const responseHeaders = new Headers(headers);
+    responseHeaders.set('Content-Type', 'application/json');
+    return new Response(JSON.stringify({
+        error: code
+    }), {
+        status,
+        headers: responseHeaders
+    });
+}
+export function toErrorResponse(error, logger) {
+    if (error instanceof InvalidBlobIDError) return errorResponse(400, 'INVALID_ID');
+    if (error instanceof InvalidRangeError) return errorResponse(416, 'RANGE_NOT_SATISFIABLE');
+    if (error instanceof BlobNotFoundError) return errorResponse(404, 'NOT_FOUND');
+    if (error instanceof BlobTooLargeError) return errorResponse(413, 'TOO_LARGE');
+    if (error instanceof BlobIDMismatchError) return errorResponse(422, 'ID_MISMATCH');
+    if (error instanceof ContentTypeMismatchError) {
+        return errorResponse(422, 'CONTENT_TYPE_MISMATCH');
+    }
+    if (error instanceof BlobAuthenticationError) {
+        return errorResponse(401, 'UNAUTHENTICATED', {
+            'WWW-Authenticate': 'Bearer'
+        });
+    }
+    if (error instanceof BlobInsecureTransportError) {
+        return errorResponse(403, 'INSECURE_TRANSPORT');
+    }
+    if (error instanceof BlobAccessDeniedError) return errorResponse(403, 'FORBIDDEN');
+    // BlobLockTimeoutError and anything unknown: masked from the client, logged.
+    logger.error(error instanceof BlobLockTimeoutError ? 'Blob lock acquire timed out: {error}' : 'Blob request failed: {error}', {
+        error
+    });
+    return errorResponse(503, 'UNAVAILABLE');
+}

package/lib/handlers/body.d.ts

@@ -0,0 +1,2 @@
+/** Releases a request body the handler will not read. */
+export declare function cancelBody(request: Request): Promise<void>;

package/lib/handlers/body.js

@@ -0,0 +1,3 @@
+/** Releases a request body the handler will not read. */ export async function cancelBody(request) {
+    await request.body?.cancel().catch(()=>{});
+}

package/lib/handlers/guard.d.ts

@@ -0,0 +1,17 @@
+import type { BlobAction, BlobPrincipal, BlobRequestContext } from '../types.js';
+import type { ResolvedBlobHandlersParams } from './types.js';
+export type GuardParams = Pick<ResolvedBlobHandlersParams, 'authenticator' | 'authorizer' | 'secureTransport'>;
+export type AuthorizeParams = {
+    guard: GuardParams;
+    request: Request;
+    context: BlobRequestContext;
+    action: BlobAction;
+    blobID?: string;
+};
+/**
+ * Request order after ID canonicalization: transport gate (read only) -> authenticate -> authorize.
+ * Throws `BlobInsecureTransportError` (transport gate), `BlobAuthenticationError` (invalid
+ * credentials from the authenticator, or a denied anonymous caller) or `BlobAccessDeniedError`
+ * (denied principal). Errors thrown by the predicate, authenticator or authorizer propagate.
+ */
+export declare function authorize(params: AuthorizeParams): Promise<BlobPrincipal | null>;

package/lib/handlers/guard.js

@@ -0,0 +1,27 @@
+import { BlobAccessDeniedError, BlobAuthenticationError, BlobInsecureTransportError } from '../errors.js';
+import { isTransportAllowed } from '../transport.js';
+/**
+ * Request order after ID canonicalization: transport gate (read only) -> authenticate -> authorize.
+ * Throws `BlobInsecureTransportError` (transport gate), `BlobAuthenticationError` (invalid
+ * credentials from the authenticator, or a denied anonymous caller) or `BlobAccessDeniedError`
+ * (denied principal). Errors thrown by the predicate, authenticator or authorizer propagate.
+ */ export async function authorize(params) {
+    const { guard, request, context, action, blobID } = params;
+    if (action === 'read' && !isTransportAllowed(guard.secureTransport, request, context)) {
+        throw new BlobInsecureTransportError();
+    }
+    const principal = await guard.authenticator(request, context);
+    const allowed = await guard.authorizer({
+        action,
+        blobID,
+        principal,
+        request,
+        context
+    });
+    if (!allowed) {
+        // Anonymous callers are asked to authenticate (401); known principals are refused (403).
+        if (principal == null) throw new BlobAuthenticationError('Authentication required');
+        throw new BlobAccessDeniedError();
+    }
+    return principal;
+}

package/lib/handlers/index.d.ts

@@ -0,0 +1,6 @@
+import type { BlobHandler, BlobHandlersParams } from './types.js';
+export type { BlobHandler, BlobHandlersParams } from './types.js';
+export declare const DEFAULT_BASE_PATH = "/blobs";
+export declare const DEFAULT_MAX_UPLOAD_SIZE = 104857600;
+export declare const DEFAULT_UPLOAD_TIMEOUT_MS = 600000;
+export declare function createBlobHandlers(params: BlobHandlersParams): BlobHandler;