@teikyo/blob 0.0.0-stage → 0.1.0

package/lib/plugin.js

@@ -0,0 +1,190 @@
+import { createBlobService, DEFAULT_LIMITS } from '@hozon/blob';
+import { BLOB_STORE as BLOB_STORE_DEFINITION, blobStoreDefinition } from '@hozon/store-blob';
+import { pluginName } from '@sozai/http-server';
+import { ACCESS_GRANTS, ACCESS_REVOCATION } from '@teikyo/access';
+import { HOZON_DB } from '@teikyo/hozon';
+import { getAuthInfo, OAUTH_RESOURCE } from '@teikyo/oauth';
+import { grantsAuthorizer } from './auth/grants.js';
+import { oauthAuthenticator } from './auth/oauth.js';
+import { tokenAuthenticator } from './auth/token.js';
+import { createReadCapabilityMinter } from './capability.js';
+import { transportFromHono } from './context.js';
+import { createBlobHandlers, DEFAULT_BASE_PATH, DEFAULT_MAX_UPLOAD_SIZE, DEFAULT_UPLOAD_TIMEOUT_MS } from './handlers/index.js';
+import { resolveBasePath } from './handlers/router.js';
+import { assertUploadLimits } from './limits.js';
+import { createReadinessCheck } from './readiness.js';
+export const DEFAULT_STAGING_MAX_AGE_MS = 86400000;
+export const BLOB_STORE = pluginName()('blob:store');
+function isPositiveInteger(value) {
+    return Number.isSafeInteger(value) && value > 0;
+}
+/**
+ * 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 function blobPlugin(params) {
+    const { oauth, revocation = false } = params;
+    const defaultAuthenticator = params.authenticator == null && oauth == null;
+    if (oauth != null && params.authenticator != null) {
+        throw new Error('oauth cannot be combined with a custom authenticator');
+    }
+    if (defaultAuthenticator && (params.audience == null || params.audience === '')) {
+        throw new Error('audience is required by the default token authenticator');
+    }
+    if (revocation && !defaultAuthenticator) {
+        throw new Error('revocation requires the default token authenticator');
+    }
+    if (params.signer != null && !defaultAuthenticator) {
+        // Minted capabilities are only accepted as proofs by the default token authenticator.
+        throw new Error('signer requires the default token authenticator');
+    }
+    const basePath = resolveBasePath(params.basePath ?? DEFAULT_BASE_PATH);
+    if (basePath === '') {
+        throw new Error('basePath must not be the root path');
+    }
+    const maxUploadSize = params.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE;
+    const uploadTimeoutMs = params.uploadTimeoutMs ?? DEFAULT_UPLOAD_TIMEOUT_MS;
+    assertUploadLimits({
+        maxUploadSize,
+        uploadTimeoutMs,
+        maxBlobSize: params.limits?.maxBlobSize ?? DEFAULT_LIMITS.maxBlobSize
+    });
+    const stagingMaxAgeMs = params.stagingMaxAgeMs ?? DEFAULT_STAGING_MAX_AGE_MS;
+    if (!isPositiveInteger(stagingMaxAgeMs) || stagingMaxAgeMs <= uploadTimeoutMs) {
+        throw new Error('stagingMaxAgeMs must be an integer above uploadTimeoutMs');
+    }
+    const dependsOn = [
+        HOZON_DB
+    ];
+    if (params.authorizer == null) dependsOn.push(ACCESS_GRANTS);
+    if (revocation) dependsOn.push(ACCESS_REVOCATION);
+    if (oauth != null) dependsOn.push(OAUTH_RESOURCE);
+    return {
+        name: BLOB_STORE,
+        dependsOn,
+        async setup (ctx) {
+            const db = ctx.use(HOZON_DB);
+            db.register(blobStoreDefinition);
+            // Run migrations now so a schema failure aborts startup.
+            await db.getStore(BLOB_STORE_DEFINITION);
+            const service = createBlobService({
+                db,
+                backend: params.backend,
+                codec: params.codec,
+                chunkSize: params.chunkSize,
+                lock: params.lock,
+                limits: params.limits
+            });
+            try {
+                const { removed, failed } = await service.pruneStaging(new Date(Date.now() - stagingMaxAgeMs));
+                if (removed > 0 || failed > 0) {
+                    ctx.logger.info('pruned blob staging: {removed} removed, {failed} failed', {
+                        removed,
+                        failed
+                    });
+                }
+            } catch (error) {
+                ctx.logger.error('blob staging prune failed', {
+                    error
+                });
+            }
+            let authenticator;
+            let checkDelegation;
+            if (oauth != null) {
+                authenticator = oauthAuthenticator();
+            } else if (params.authenticator != null) {
+                // No checkDelegation: it trusts `principal.token`, so it only vouches for principals
+                // produced by the token authenticator. Delegated principals from here fail closed.
+                authenticator = params.authenticator;
+            } else {
+                const token = tokenAuthenticator({
+                    audience: params.audience,
+                    revocation: revocation ? ctx.use(ACCESS_REVOCATION).verifyToken : undefined,
+                    verifyOptions: params.verifyOptions
+                });
+                authenticator = token;
+                checkDelegation = token.checkDelegation;
+            }
+            let authorizer;
+            if (params.authorizer == null) {
+                authorizer = grantsAuthorizer({
+                    grants: ctx.use(ACCESS_GRANTS),
+                    checkDelegation,
+                    scopes: oauth?.scopes
+                });
+            } else if (checkDelegation != null) {
+                // `delegatedFrom` is an unverified claim until checkDelegation accepts the proof, so a
+                // custom authorizer only sees delegated principals whose proof covers the request.
+                const custom = params.authorizer;
+                const verifyDelegation = checkDelegation;
+                authorizer = async (input)=>{
+                    const { principal, action, blobID } = input;
+                    if (principal?.delegatedFrom != null && await verifyDelegation({
+                        principal,
+                        action,
+                        blobID
+                    }) !== true) {
+                        return false;
+                    }
+                    return await custom(input);
+                };
+            } else {
+                authorizer = params.authorizer;
+            }
+            const handlers = createBlobHandlers({
+                service,
+                authenticator,
+                authorizer,
+                basePath,
+                maxUploadSize,
+                uploadTimeoutMs,
+                secureTransport: params.secureTransport,
+                logger: ctx.logger
+            });
+            // The handler enforces maxUploadSize while streaming and its own upload deadline.
+            ctx.limits(basePath, {
+                bodyBytes: false,
+                timeoutMs: false
+            });
+            if (oauth != null) {
+                ctx.middleware(ctx.use(OAUTH_RESOURCE).requireBearer(), basePath);
+            }
+            const handle = (c)=>{
+                const context = {
+                    transport: transportFromHono(c)
+                };
+                if (oauth != null) {
+                    const info = getAuthInfo(c);
+                    const principal = {
+                        subject: info.subject,
+                        scopes: [
+                            ...info.scopes
+                        ]
+                    };
+                    context.principal = principal;
+                }
+                return handlers(c.req.raw, context);
+            };
+            ctx.route('all', basePath, handle);
+            ctx.route('all', `${basePath}/*`, handle);
+            ctx.addReadinessCheck(createReadinessCheck({
+                probe: ()=>service.list({
+                        limit: 1
+                    }),
+                logger: ctx.logger
+            }));
+            const api = {
+                service,
+                handlers
+            };
+            if (params.signer != null) {
+                api.mintReadCapability = createReadCapabilityMinter({
+                    signer: params.signer,
+                    serviceAudience: params.audience,
+                    canonicalize: (id)=>service.codec.canonicalize(id)
+                });
+            }
+            return api;
+        }
+    };
+}

package/lib/range.d.ts

@@ -0,0 +1,11 @@
+/** Inclusive byte range, matching HTTP `Range` / `Content-Range` semantics. */
+export type ParsedRange = {
+    start: number;
+    end: number;
+};
+/**
+ * Parse a single-range HTTP `Range` header against a known content length.
+ * Returns `null` when the header is absent or not a `bytes` range (ignored, serve the whole body),
+ * a range when satisfiable, or `'unsatisfiable'` for malformed, multi-range or out-of-bounds ranges.
+ */
+export declare function parseRange(header: string | null, length: number): ParsedRange | null | 'unsatisfiable';

package/lib/range.js

@@ -0,0 +1,30 @@
+/** Inclusive byte range, matching HTTP `Range` / `Content-Range` semantics. */ /**
+ * Parse a single-range HTTP `Range` header against a known content length.
+ * Returns `null` when the header is absent or not a `bytes` range (ignored, serve the whole body),
+ * a range when satisfiable, or `'unsatisfiable'` for malformed, multi-range or out-of-bounds ranges.
+ */ export function parseRange(header, length) {
+    if (header == null) return null;
+    const value = header.trim();
+    if (!/^bytes\s*=/i.test(value)) return null;
+    const match = /^bytes\s*=\s*(\d*)-(\d*)$/i.exec(value);
+    if (match == null) return 'unsatisfiable';
+    const [, startText, endText] = match;
+    if (length <= 0 || startText === '' && endText === '') return 'unsatisfiable';
+    // Suffix form `bytes=-N`: the final N bytes.
+    if (startText === '') {
+        const suffix = Number(endText);
+        if (suffix === 0) return 'unsatisfiable';
+        return {
+            start: Math.max(0, length - suffix),
+            end: length - 1
+        };
+    }
+    const start = Number(startText);
+    if (!Number.isSafeInteger(start) || start >= length) return 'unsatisfiable';
+    const end = endText === '' ? length - 1 : Math.min(Number(endText), length - 1);
+    if (end < start) return 'unsatisfiable';
+    return {
+        start,
+        end
+    };
+}

package/lib/readiness.d.ts

@@ -0,0 +1,7 @@
+import type { Logger } from '@sozai/log';
+export type ReadinessCheckParams = {
+    probe: () => Promise<unknown>;
+    logger: Logger;
+};
+/** Readiness check that logs on state transitions only, so a persistent outage logs once. */
+export declare function createReadinessCheck(params: ReadinessCheckParams): () => Promise<boolean>;

package/lib/readiness.js

@@ -0,0 +1,17 @@
+/** Readiness check that logs on state transitions only, so a persistent outage logs once. */ export function createReadinessCheck(params) {
+    const { probe, logger } = params;
+    let healthy = true;
+    return async ()=>{
+        try {
+            await probe();
+            if (!healthy) logger.info('blob store readiness check recovered');
+            healthy = true;
+        } catch (error) {
+            if (healthy) logger.error('blob store readiness check failed', {
+                error
+            });
+            healthy = false;
+        }
+        return healthy;
+    };
+}

package/lib/resources.d.ts

@@ -0,0 +1,8 @@
+import type { BlobAction } from './types.js';
+/** Grant resource string; `blobID` must be the canonical ID. */
+export declare function grantResource(action: BlobAction, blobID?: string): string;
+/** Capability permission (`act` and `res`); `blobID` must be the canonical ID. */
+export declare function capabilityPermission(action: BlobAction, blobID?: string): {
+    act: string;
+    res: string;
+};

package/lib/resources.js

@@ -0,0 +1,9 @@
+/** Grant resource string; `blobID` must be the canonical ID. */ export function grantResource(action, blobID) {
+    return blobID == null ? `blob/${action}` : `blob/${action}/${blobID}`;
+}
+/** Capability permission (`act` and `res`); `blobID` must be the canonical ID. */ export function capabilityPermission(action, blobID) {
+    return {
+        act: `blob/${action}`,
+        res: blobID == null ? 'blob/*' : `blob/${blobID}`
+    };
+}

package/lib/transport.d.ts

@@ -0,0 +1,4 @@
+import type { BlobRequestContext } from './types.js';
+export type SecureTransportOption = boolean | ((request: Request, context: BlobRequestContext) => boolean);
+/** Whether the request's transport satisfies the `secureTransport` option. Fails closed. */
+export declare function isTransportAllowed(option: SecureTransportOption, request: Request, context: BlobRequestContext): boolean;

package/lib/transport.js

@@ -0,0 +1,15 @@
+function isLoopback(address) {
+    const addr = address.toLowerCase();
+    if (addr === '::1') return true;
+    const v4 = addr.startsWith('::ffff:') ? addr.slice(7) : addr;
+    // Exactly four decimal octets, 0-255, no leading zeros, first octet 127.
+    const octets = v4.split('.');
+    return octets.length === 4 && octets[0] === '127' && octets.every((octet)=>/^(0|[1-9]\d{0,2})$/.test(octet) && Number(octet) <= 255);
+}
+/** Whether the request's transport satisfies the `secureTransport` option. Fails closed. */ export function isTransportAllowed(option, request, context) {
+    if (typeof option === 'function') return option(request, context);
+    if (!option) return true;
+    const transport = context.transport;
+    if (transport == null) return false;
+    return transport.secure === true || isLoopback(transport.localAddress) && isLoopback(transport.remoteAddress);
+}

package/lib/types.d.ts

@@ -0,0 +1,34 @@
+import type { SignedPayload } from '@kokuin/token';
+export type TokenPayload = SignedPayload;
+export type BlobAction = 'read' | 'write' | 'delete' | 'pin' | 'list';
+export type TransportInfo = {
+    /** TLS on the connection the server accepted. */
+    secure: boolean;
+    localAddress: string;
+    remoteAddress: string;
+};
+export type BlobPrincipal = {
+    subject: string;
+    /**
+     * Identity the caller claims to act for. A caller-supplied claim, only verified by
+     * `checkDelegation`: the plugin enforces it for any authorizer when the default token
+     * authenticator is used. Embedders calling `createBlobHandlers` with `tokenAuthenticator`
+     * directly must call `checkDelegation` in their authorizer.
+     */
+    delegatedFrom?: string;
+    token?: TokenPayload;
+    scopes?: Array<string>;
+};
+export type BlobRequestContext = {
+    transport?: TransportInfo;
+    /** Principal already verified by adapter middleware (e.g. OAuth), if any. */
+    principal?: BlobPrincipal;
+};
+export type BlobAuthenticator = (request: Request, context: BlobRequestContext) => Promise<BlobPrincipal | null>;
+export type BlobAuthorizer = (input: {
+    action: BlobAction;
+    blobID?: string;
+    principal: BlobPrincipal | null;
+    request: Request;
+    context: BlobRequestContext;
+}) => Promise<boolean>;

package/lib/types.js

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

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@teikyo/blob",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Blob storage HTTP plugin with access control",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TairuFramework/teikyo.git",
+    "directory": "packages/blob"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/*"
+  ],
+  "dependencies": {
+    "@hozon/blob": "^0.1.1",
+    "@hozon/store-blob": "^0.2.2",
+    "@kokuin/capability": "^0.5.1",
+    "@kokuin/token": "^0.6.1",
+    "@sozai/codec": "^0.4.3",
+    "@sozai/http-server": "^0.2.0",
+    "@sozai/log": "^0.4.0",
+    "@teikyo/access": "^0.2.0",
+    "@teikyo/hozon": "^0.2.0",
+    "@teikyo/oauth": "^0.1.0"
+  },
+  "devDependencies": {
+    "@hozon/blob-backend": "^0.2.0",
+    "@hozon/blob-id": "^0.1.1",
+    "@hozon/db": "^0.3.0",
+    "@hozon/provider": "^0.1.2",
+    "@noble/curves": "^2.4.0",
+    "@types/node": "^26.6.5",
+    "del-cli": "^8.0.1",
+    "hono": "^4.13.13",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "hono": "^4.13.13"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del-cli lib",
+    "build:js": "del-cli \"lib/**/*.js\" && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del-cli \"lib/**/*.d.ts\" \"lib/**/*.d.ts.map\" && tsc --emitDeclarationOnly --skipLibCheck",
+    "build:types:ci": "tsc --emitDeclarationOnly --skipLibCheck --declarationMap false",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
 }