@peerbit/blocks-interface 2.1.7 → 2.2.0

package/README.md

@@ -13,3 +13,23 @@ consumer boundary, after the bytes are authenticated.
 DAG-CBOR block can still allocate its decoded object graph, so callers handling
 attacker-selected CIDs should prefer `verifyBlockBytes` unless they explicitly
 need the logical value and enforce suitable resource bounds.
+
+## Reclamation capability
+
+`Blocks.localReclamation` is an operational capability, not caller-declared
+metadata. A service may report `enforcedReclamation: "scoped-references-v1"`
+through the additive `observedLocalStoreSafety` property only when that
+capability exists; callers must additionally require a `ready` health result.
+The existing `localStoreSafety` property and `BlockStoreSafety` declaration
+type remain restricted to `enforcedReclamation: "none"` for source
+compatibility. `DeclaredBlockStoreSafety` is an explicit alias, while
+`ObservedBlockStoreSafety` includes the service-minted enforced variant.
+Custom-store configuration therefore cannot assert an enforcement mechanism it
+does not implement. Peerbit's enforced metadata value is private to the
+built-in wrapper and is derived from that wrapper's actual capability; neither
+the opt-in flag nor caller metadata can mint it.
+
+Each `openScope` key is exactly 32 bytes and is defensively copied. Scope
+handles belong to one service lifecycle. Managed retain/release operations are
+single-block, bounded, idempotent, local-only, and isolated from raw `put`/`rm`
+blocks.

package/dist/src/index.d.ts

@@ -17,7 +17,116 @@ export type CrashSafeBlockDurability = {
     readonly crashSafe: true;
     barrier(): MaybePromise<void>;
 };
+/**
+ * Scope across which local references to a content-addressed block may alias.
+ *
+ * `block-service` is the scope of Peerbit's built-in stores: the backing
+ * namespace belongs to one blocks service, but every program using that
+ * service shares it. `caller-exclusive` is an explicit assertion that the
+ * declaring caller controls the entire physical namespace and every reference
+ * in it. `shared` means references may exist outside this block service;
+ * `unknown` makes no reliable scope assertion. Neither persistence nor a
+ * backend class implies any scope.
+ */
+export type BlockStoreReferenceDomain = "block-service" | "caller-exclusive" | "shared" | "unknown";
+/**
+ * Immutable facts needed before a caller considers physical block deletion.
+ *
+ * `enforcedReclamation: "none"` means the store exposes no reference-safe
+ * lease, fencing, atomic delete-if-unreferenced, or isolated-namespace
+ * primitive. A raw `rm` is therefore safe only for an authority that controls
+ * the complete reference domain. This field is deliberately separate from
+ * `persisted()`.
+ */
+export type BlockStoreSafety = Readonly<{
+    referenceDomain: BlockStoreReferenceDomain;
+    enforcedReclamation: "none";
+}>;
+/** Explicit alias for APIs that accept caller-declared safety facts. */
+export type DeclaredBlockStoreSafety = BlockStoreSafety;
+/**
+ * Observed service safety. The enforced variant is valid only together with a
+ * matching, ready `Blocks.localReclamation` capability; metadata alone never
+ * grants deletion authority.
+ */
+export type ObservedBlockStoreSafety = BlockStoreSafety | Readonly<{
+    referenceDomain: "block-service";
+    enforcedReclamation: "scoped-references-v1";
+}>;
+export type ScopedBlockReclamationLimits = Readonly<{
+    maxBlockBytes: number;
+    maxCidBytes: number;
+    scopeKeyBytes: number;
+    maxReferencesPerBlock: number;
+    maxPendingOperations: number;
+    maxPendingBytes: number;
+}>;
+export type ScopedBlockReclamationFaultCode = "ambiguous-mutation" | "corrupt-state" | "storage-failure";
+export type ScopedBlockReclamationHealth = Readonly<{
+    status: "opening" | "ready" | "closed";
+}> | Readonly<{
+    status: "faulted";
+    reason: ScopedBlockReclamationFaultCode;
+}>;
+export type ScopedBlockReleaseResult = "not-retained" | "retained" | "reclaimed";
+/**
+ * One durable ownership scope inside a block-service managed namespace.
+ *
+ * A scope key is local authority, not a network identity. Callers must use a
+ * stable, collision-resistant value under their control; this mechanism does
+ * not isolate mutually hostile code that can invoke `openScope` with another
+ * caller's key. `retain` copies and CID-verifies bytes before publishing the
+ * reference. `release` can delete only managed bytes after the last durable
+ * scope reference is gone. Calls are idempotent and deliberately single-block
+ * so each unit of work is bounded.
+ */
+export interface ScopedBlockReclamationScopeV1 {
+    put(bytes: Uint8Array): MaybePromise<string>;
+    retain(cid: string, bytes: Uint8Array): MaybePromise<string>;
+    release(cid: string): MaybePromise<ScopedBlockReleaseResult>;
+}
+/**
+ * Opt-in, local-only reference enforcement for a block-service-owned managed
+ * namespace. It never adopts or deletes blocks written through the legacy/raw
+ * `Blocks.put`/`Blocks.rm` namespace.
+ */
+export interface ScopedBlockReclamationV1 {
+    readonly kind: "scoped-references-v1";
+    readonly limits: ScopedBlockReclamationLimits;
+    health(): ScopedBlockReclamationHealth;
+    openScope(scopeKey: Uint8Array): ScopedBlockReclamationScopeV1;
+}
+export declare const UNKNOWN_BLOCK_STORE_SAFETY: BlockStoreSafety;
+export declare const BLOCK_SERVICE_BLOCK_STORE_SAFETY: BlockStoreSafety;
+/**
+ * Validate, defensively copy, and freeze block-store safety metadata.
+ *
+ * The input is intentionally `unknown`: declarations can cross JavaScript and
+ * configuration boundaries where TypeScript's static shape is unavailable.
+ */
+export declare const normalizeBlockStoreSafety: (value: unknown) => BlockStoreSafety;
 export interface Blocks extends WaitForPeer {
+    /**
+     * Legacy caller-declared safety metadata for this service's local physical
+     * block namespace. Its type and values remain restricted to
+     * `enforcedReclamation: "none"`.
+     */
+    readonly localStoreSafety?: BlockStoreSafety;
+    /**
+     * Optional service-observed safety metadata. Absence is equivalent to
+     * `localStoreSafety` (or {@link UNKNOWN_BLOCK_STORE_SAFETY} when both are
+     * absent), so older and custom implementations fail closed.
+     *
+     * The enforced variant is descriptive only; callers must also require the
+     * matching, ready `localReclamation` capability.
+     */
+    readonly observedLocalStoreSafety?: ObservedBlockStoreSafety;
+    /**
+     * Present only when this exact service owns and enforces a separate managed
+     * namespace. Callers must require `health().status === "ready"`; metadata
+     * alone is not authority to delete.
+     */
+    readonly localReclamation?: ScopedBlockReclamationV1;
     put(data: Uint8Array | {
         block: Block<any, any, any, any>;
         cid: string;

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/src/index.js

@@ -1,4 +1,41 @@
 import {} from "@peerbit/stream-interface";
 import {} from "multiformats/block";
+export const UNKNOWN_BLOCK_STORE_SAFETY = Object.freeze({
+    referenceDomain: "unknown",
+    enforcedReclamation: "none",
+});
+export const BLOCK_SERVICE_BLOCK_STORE_SAFETY = Object.freeze({
+    referenceDomain: "block-service",
+    enforcedReclamation: "none",
+});
+/**
+ * Validate, defensively copy, and freeze block-store safety metadata.
+ *
+ * The input is intentionally `unknown`: declarations can cross JavaScript and
+ * configuration boundaries where TypeScript's static shape is unavailable.
+ */
+export const normalizeBlockStoreSafety = (value) => {
+    if (value === undefined)
+        return UNKNOWN_BLOCK_STORE_SAFETY;
+    if (value === null || typeof value !== "object") {
+        throw new TypeError("Invalid block-store safety metadata");
+    }
+    const referenceDomain = value
+        .referenceDomain;
+    const enforcedReclamation = value
+        .enforcedReclamation;
+    if (referenceDomain !== "block-service" &&
+        referenceDomain !== "caller-exclusive" &&
+        referenceDomain !== "shared" &&
+        referenceDomain !== "unknown") {
+        throw new TypeError("Invalid block-store reference domain");
+    }
+    // Enforced reclamation is an operational capability, not a caller assertion.
+    // DirectBlock mints its scoped capability only for its own supported store.
+    if (enforcedReclamation !== "none") {
+        throw new TypeError("Unsupported block-store reclamation capability");
+    }
+    return Object.freeze({ referenceDomain, enforcedReclamation });
+};
 export { cidifyString, stringifyCid, createBlock, getBlockValue, calculateRawCid, checkDecodeBlock, verifyBlockBytes, codecCodes, defaultHasher, codecMap, } from "./block.js";
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAc,MAAM,oBAAoB,CAAC;AAgEhD,OAAO,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,QAAQ,GACR,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAc,MAAM,oBAAoB,CAAC;AA4HhD,MAAM,CAAC,MAAM,0BAA0B,GAAqB,MAAM,CAAC,MAAM,CAAC;IACzE,eAAe,EAAE,SAAS;IAC1B,mBAAmB,EAAE,MAAM;CAC3B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,gCAAgC,GAAqB,MAAM,CAAC,MAAM,CAC9E;IACC,eAAe,EAAE,eAAe;IAChC,mBAAmB,EAAE,MAAM;CAC3B,CACD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACxC,KAAc,EACK,EAAE;IACrB,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,0BAA0B,CAAC;IAC3D,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACjD,MAAM,IAAI,SAAS,CAAC,qCAAqC,CAAC,CAAC;IAC5D,CAAC;IACD,MAAM,eAAe,GAAI,KAAuC;SAC9D,eAAe,CAAC;IAClB,MAAM,mBAAmB,GAAI,KAA2C;SACtE,mBAAmB,CAAC;IACtB,IACC,eAAe,KAAK,eAAe;QACnC,eAAe,KAAK,kBAAkB;QACtC,eAAe,KAAK,QAAQ;QAC5B,eAAe,KAAK,SAAS,EAC5B,CAAC;QACF,MAAM,IAAI,SAAS,CAAC,sCAAsC,CAAC,CAAC;IAC7D,CAAC;IACD,6EAA6E;IAC7E,4EAA4E;IAC5E,IAAI,mBAAmB,KAAK,MAAM,EAAE,CAAC;QACpC,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,mBAAmB,EAAE,CAAC,CAAC;AAChE,CAAC,CAAC;AAgEF,OAAO,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,QAAQ,GACR,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peerbit/blocks-interface",
-  "version": "2.1.7",
+  "version": "2.2.0",
   "description": "Block store streaming",
   "type": "module",
   "sideEffects": false,

package/src/index.ts

@@ -22,7 +22,174 @@ export type CrashSafeBlockDurability = {
 	barrier(): MaybePromise<void>;
 };
 
+/**
+ * Scope across which local references to a content-addressed block may alias.
+ *
+ * `block-service` is the scope of Peerbit's built-in stores: the backing
+ * namespace belongs to one blocks service, but every program using that
+ * service shares it. `caller-exclusive` is an explicit assertion that the
+ * declaring caller controls the entire physical namespace and every reference
+ * in it. `shared` means references may exist outside this block service;
+ * `unknown` makes no reliable scope assertion. Neither persistence nor a
+ * backend class implies any scope.
+ */
+export type BlockStoreReferenceDomain =
+	| "block-service"
+	| "caller-exclusive"
+	| "shared"
+	| "unknown";
+
+/**
+ * Immutable facts needed before a caller considers physical block deletion.
+ *
+ * `enforcedReclamation: "none"` means the store exposes no reference-safe
+ * lease, fencing, atomic delete-if-unreferenced, or isolated-namespace
+ * primitive. A raw `rm` is therefore safe only for an authority that controls
+ * the complete reference domain. This field is deliberately separate from
+ * `persisted()`.
+ */
+export type BlockStoreSafety = Readonly<{
+	referenceDomain: BlockStoreReferenceDomain;
+	enforcedReclamation: "none";
+}>;
+
+/** Explicit alias for APIs that accept caller-declared safety facts. */
+export type DeclaredBlockStoreSafety = BlockStoreSafety;
+
+/**
+ * Observed service safety. The enforced variant is valid only together with a
+ * matching, ready `Blocks.localReclamation` capability; metadata alone never
+ * grants deletion authority.
+ */
+export type ObservedBlockStoreSafety =
+	| BlockStoreSafety
+	| Readonly<{
+			referenceDomain: "block-service";
+			enforcedReclamation: "scoped-references-v1";
+	  }>;
+
+export type ScopedBlockReclamationLimits = Readonly<{
+	maxBlockBytes: number;
+	maxCidBytes: number;
+	scopeKeyBytes: number;
+	maxReferencesPerBlock: number;
+	maxPendingOperations: number;
+	maxPendingBytes: number;
+}>;
+
+export type ScopedBlockReclamationFaultCode =
+	| "ambiguous-mutation"
+	| "corrupt-state"
+	| "storage-failure";
+
+export type ScopedBlockReclamationHealth =
+	| Readonly<{ status: "opening" | "ready" | "closed" }>
+	| Readonly<{
+			status: "faulted";
+			reason: ScopedBlockReclamationFaultCode;
+	  }>;
+
+export type ScopedBlockReleaseResult =
+	| "not-retained"
+	| "retained"
+	| "reclaimed";
+
+/**
+ * One durable ownership scope inside a block-service managed namespace.
+ *
+ * A scope key is local authority, not a network identity. Callers must use a
+ * stable, collision-resistant value under their control; this mechanism does
+ * not isolate mutually hostile code that can invoke `openScope` with another
+ * caller's key. `retain` copies and CID-verifies bytes before publishing the
+ * reference. `release` can delete only managed bytes after the last durable
+ * scope reference is gone. Calls are idempotent and deliberately single-block
+ * so each unit of work is bounded.
+ */
+export interface ScopedBlockReclamationScopeV1 {
+	put(bytes: Uint8Array): MaybePromise<string>;
+	retain(cid: string, bytes: Uint8Array): MaybePromise<string>;
+	release(cid: string): MaybePromise<ScopedBlockReleaseResult>;
+}
+
+/**
+ * Opt-in, local-only reference enforcement for a block-service-owned managed
+ * namespace. It never adopts or deletes blocks written through the legacy/raw
+ * `Blocks.put`/`Blocks.rm` namespace.
+ */
+export interface ScopedBlockReclamationV1 {
+	readonly kind: "scoped-references-v1";
+	readonly limits: ScopedBlockReclamationLimits;
+	health(): ScopedBlockReclamationHealth;
+	openScope(scopeKey: Uint8Array): ScopedBlockReclamationScopeV1;
+}
+
+export const UNKNOWN_BLOCK_STORE_SAFETY: BlockStoreSafety = Object.freeze({
+	referenceDomain: "unknown",
+	enforcedReclamation: "none",
+});
+
+export const BLOCK_SERVICE_BLOCK_STORE_SAFETY: BlockStoreSafety = Object.freeze(
+	{
+		referenceDomain: "block-service",
+		enforcedReclamation: "none",
+	},
+);
+
+/**
+ * Validate, defensively copy, and freeze block-store safety metadata.
+ *
+ * The input is intentionally `unknown`: declarations can cross JavaScript and
+ * configuration boundaries where TypeScript's static shape is unavailable.
+ */
+export const normalizeBlockStoreSafety = (
+	value: unknown,
+): BlockStoreSafety => {
+	if (value === undefined) return UNKNOWN_BLOCK_STORE_SAFETY;
+	if (value === null || typeof value !== "object") {
+		throw new TypeError("Invalid block-store safety metadata");
+	}
+	const referenceDomain = (value as { referenceDomain?: unknown })
+		.referenceDomain;
+	const enforcedReclamation = (value as { enforcedReclamation?: unknown })
+		.enforcedReclamation;
+	if (
+		referenceDomain !== "block-service" &&
+		referenceDomain !== "caller-exclusive" &&
+		referenceDomain !== "shared" &&
+		referenceDomain !== "unknown"
+	) {
+		throw new TypeError("Invalid block-store reference domain");
+	}
+	// Enforced reclamation is an operational capability, not a caller assertion.
+	// DirectBlock mints its scoped capability only for its own supported store.
+	if (enforcedReclamation !== "none") {
+		throw new TypeError("Unsupported block-store reclamation capability");
+	}
+	return Object.freeze({ referenceDomain, enforcedReclamation });
+};
+
 export interface Blocks extends WaitForPeer {
+	/**
+	 * Legacy caller-declared safety metadata for this service's local physical
+	 * block namespace. Its type and values remain restricted to
+	 * `enforcedReclamation: "none"`.
+	 */
+	readonly localStoreSafety?: BlockStoreSafety;
+	/**
+	 * Optional service-observed safety metadata. Absence is equivalent to
+	 * `localStoreSafety` (or {@link UNKNOWN_BLOCK_STORE_SAFETY} when both are
+	 * absent), so older and custom implementations fail closed.
+	 *
+	 * The enforced variant is descriptive only; callers must also require the
+	 * matching, ready `localReclamation` capability.
+	 */
+	readonly observedLocalStoreSafety?: ObservedBlockStoreSafety;
+	/**
+	 * Present only when this exact service owns and enforces a separate managed
+	 * namespace. Callers must require `health().status === "ready"`; metadata
+	 * alone is not authority to delete.
+	 */
+	readonly localReclamation?: ScopedBlockReclamationV1;
 	put(
 		data: Uint8Array | { block: Block<any, any, any, any>; cid: string },
 	): MaybePromise<string>;