@git-stunts/git-cas 1.6.0 → 1.6.2

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.2] — OIDC publishing + JSR docs coverage (2026-02-07)
+
+### Added
+- JSDoc comments on all exported TypeScript interfaces (`CryptoPort`, `CodecPort`, `GitPersistencePort`, `CasServiceOptions`, `EncryptionMeta`, `ManifestData`, `ContentAddressableStoreOptions`) to reach 100% JSR symbol documentation coverage.
+
+### Fixed
+- npm publish workflow now uses OIDC trusted publishing (no stored token). Upgrades npm to >=11.5.1 at publish time since pnpm does not yet support OIDC natively.
+
+## [1.6.1] — JSR quality fixes (2026-02-07)
+
+### Added
+- TypeScript declaration files (`.d.ts`) for all three entrypoints and shared value objects, resolving JSR "slow types" scoring penalty.
+- `@ts-self-types` directives in `index.js`, `CasService.js`, and `ManifestSchema.js`.
+- `@fileoverview` module doc to `CasService.js` (required by JSR for module docs scoring).
+
+### Fixed
+- JSR package name corrected to `@git-stunts/git-cas`.
+- JSR publication now excludes tests, docs, CI configs, and other non-distribution files via `jsr.json` exclude list.
+- `index.d.ts` added to `package.json` files array for npm distribution.
+
 ## [1.6.0] — M4 Compass + M5 Sonar + M6 Cartographer (2026-02-06)
 
 ### Added

package/index.d.ts

@@ -0,0 +1,155 @@
+/**
+ * @module
+ * Content Addressable Store — Managed blob storage in Git.
+ */
+
+import Manifest from "./src/domain/value-objects/Manifest.js";
+import type { EncryptionMeta, ManifestData } from "./src/domain/value-objects/Manifest.js";
+import Chunk from "./src/domain/value-objects/Chunk.js";
+import CasService from "./src/domain/services/CasService.js";
+import type {
+  CryptoPort,
+  CodecPort,
+  GitPersistencePort,
+  CasServiceOptions,
+} from "./src/domain/services/CasService.js";
+
+export { CasService, Manifest, Chunk };
+export type { EncryptionMeta, ManifestData, CryptoPort, CodecPort, GitPersistencePort, CasServiceOptions };
+
+/** Abstract port for cryptographic operations. */
+export declare class CryptoPortBase {
+  sha256(buf: Buffer): string | Promise<string>;
+  randomBytes(n: number): Buffer;
+  encryptBuffer(
+    buffer: Buffer,
+    key: Buffer,
+  ): { buf: Buffer; meta: EncryptionMeta } | Promise<{ buf: Buffer; meta: EncryptionMeta }>;
+  decryptBuffer(buffer: Buffer, key: Buffer, meta: EncryptionMeta): Buffer | Promise<Buffer>;
+  createEncryptionStream(key: Buffer): {
+    encrypt: (source: AsyncIterable<Buffer>) => AsyncIterable<Buffer>;
+    finalize: () => EncryptionMeta;
+  };
+}
+
+/** Abstract port for persisting data to Git's object database. */
+export declare class GitPersistencePortBase {
+  writeBlob(content: Buffer | string): Promise<string>;
+  writeTree(entries: string[]): Promise<string>;
+  readBlob(oid: string): Promise<Buffer>;
+  readTree(
+    treeOid: string,
+  ): Promise<Array<{ mode: string; type: string; oid: string; name: string }>>;
+}
+
+/** Git-backed implementation of the persistence port. */
+export declare class GitPersistenceAdapter extends GitPersistencePortBase {
+  constructor(options: { plumbing: unknown; policy?: unknown });
+}
+
+/** Node.js crypto implementation of CryptoPort. */
+export declare class NodeCryptoAdapter extends CryptoPortBase {
+  constructor();
+}
+
+/** Abstract codec interface for manifest serialization. */
+export declare class CodecPortBase {
+  encode(data: object): Buffer | string;
+  decode(buffer: Buffer | string): object;
+  get extension(): string;
+}
+
+/** JSON codec for manifest serialization. */
+export declare class JsonCodec extends CodecPortBase {
+  constructor();
+}
+
+/** CBOR codec for manifest serialization. */
+export declare class CborCodec extends CodecPortBase {
+  constructor();
+}
+
+/** Constructor options for {@link ContentAddressableStore}. */
+export interface ContentAddressableStoreOptions {
+  plumbing: unknown;
+  chunkSize?: number;
+  codec?: CodecPort;
+  crypto?: CryptoPort;
+  policy?: unknown;
+}
+
+/**
+ * High-level facade for the Content Addressable Store library.
+ *
+ * Wraps CasService with lazy initialization, runtime-adaptive crypto
+ * selection, and convenience helpers for file I/O.
+ */
+export default class ContentAddressableStore {
+  constructor(options: ContentAddressableStoreOptions);
+
+  get chunkSize(): number;
+
+  getService(): Promise<CasService>;
+
+  static createJson(options: {
+    plumbing: unknown;
+    chunkSize?: number;
+    policy?: unknown;
+  }): ContentAddressableStore;
+
+  static createCbor(options: {
+    plumbing: unknown;
+    chunkSize?: number;
+    policy?: unknown;
+  }): ContentAddressableStore;
+
+  encrypt(options: {
+    buffer: Buffer;
+    key: Buffer;
+  }): Promise<{ buf: Buffer; meta: EncryptionMeta }>;
+
+  decrypt(options: {
+    buffer: Buffer;
+    key: Buffer;
+    meta: EncryptionMeta;
+  }): Promise<Buffer>;
+
+  storeFile(options: {
+    filePath: string;
+    slug: string;
+    filename?: string;
+    encryptionKey?: Buffer;
+  }): Promise<Manifest>;
+
+  store(options: {
+    source: AsyncIterable<Buffer>;
+    slug: string;
+    filename: string;
+    encryptionKey?: Buffer;
+  }): Promise<Manifest>;
+
+  restoreFile(options: {
+    manifest: Manifest;
+    encryptionKey?: Buffer;
+    outputPath: string;
+  }): Promise<{ bytesWritten: number }>;
+
+  restore(options: {
+    manifest: Manifest;
+    encryptionKey?: Buffer;
+  }): Promise<{ buffer: Buffer; bytesWritten: number }>;
+
+  createTree(options: { manifest: Manifest }): Promise<string>;
+
+  verifyIntegrity(manifest: Manifest): Promise<boolean>;
+
+  readManifest(options: { treeOid: string }): Promise<Manifest>;
+
+  deleteAsset(options: {
+    treeOid: string;
+  }): Promise<{ slug: string; chunksOrphaned: number }>;
+
+  findOrphanedChunks(options: {
+    treeOids: string[];
+  }): Promise<{ referenced: Set<string>; total: number }>;
+}

package/index.js

@@ -1,3 +1,4 @@
+/* @ts-self-types="./index.d.ts" */
 /**
  * @fileoverview Content Addressable Store - Managed blob storage in Git.
  */

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@git-stunts/git-cas",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "Content-addressed storage backed by Git's object database, with optional encryption and pluggable codecs",
   "type": "module",
   "main": "index.js",
   "bin": {
-    "git-cas": "./bin/git-cas.js"
+    "git-cas": "bin/git-cas.js"
   },
   "exports": {
     ".": "./index.js",
@@ -14,6 +14,7 @@
   },
   "files": [
     "index.js",
+    "index.d.ts",
     "bin/",
     "src/",
     "README.md",
@@ -78,4 +79,4 @@
     "prettier": "^3.4.2",
     "vitest": "^2.1.8"
   }
-}
+}

package/src/domain/schemas/ManifestSchema.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @module
+ * Zod schemas for validating CAS manifest and chunk data.
+ */
+
+import { z } from "zod";
+
+/** Validates a single chunk entry within a manifest. */
+export declare const ChunkSchema: z.ZodObject<{
+  index: z.ZodNumber;
+  size: z.ZodNumber;
+  digest: z.ZodString;
+  blob: z.ZodString;
+}>;
+
+/** Validates the encryption metadata attached to an encrypted manifest. */
+export declare const EncryptionSchema: z.ZodObject<{
+  algorithm: z.ZodString;
+  nonce: z.ZodString;
+  tag: z.ZodString;
+  encrypted: z.ZodDefault<z.ZodBoolean>;
+}>;
+
+/** Validates a complete file manifest. */
+export declare const ManifestSchema: z.ZodObject<{
+  slug: z.ZodString;
+  filename: z.ZodString;
+  size: z.ZodNumber;
+  chunks: z.ZodArray<typeof ChunkSchema>;
+  encryption: z.ZodOptional<typeof EncryptionSchema>;
+}>;

package/src/domain/schemas/ManifestSchema.js

@@ -1,3 +1,4 @@
+/* @ts-self-types="./ManifestSchema.d.ts" */
 /**
  * @fileoverview Zod schemas for validating CAS manifest and chunk data.
  */

package/src/domain/services/CasService.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @module
+ * Domain service for Content Addressable Storage operations.
+ */
+
+import { EventEmitter } from "node:events";
+import Manifest from "../value-objects/Manifest.js";
+import type { EncryptionMeta } from "../value-objects/Manifest.js";
+
+/** Port interface for cryptographic operations (hashing, encryption, random bytes). */
+export interface CryptoPort {
+  sha256(buf: Buffer): string | Promise<string>;
+  randomBytes(n: number): Buffer;
+  encryptBuffer(
+    buffer: Buffer,
+    key: Buffer,
+  ): { buf: Buffer; meta: EncryptionMeta } | Promise<{ buf: Buffer; meta: EncryptionMeta }>;
+  decryptBuffer(buffer: Buffer, key: Buffer, meta: EncryptionMeta): Buffer | Promise<Buffer>;
+  createEncryptionStream(key: Buffer): {
+    encrypt: (source: AsyncIterable<Buffer>) => AsyncIterable<Buffer>;
+    finalize: () => EncryptionMeta;
+  };
+}
+
+/** Port interface for encoding and decoding manifest data. */
+export interface CodecPort {
+  encode(data: object): Buffer | string;
+  decode(buffer: Buffer | string): object;
+  get extension(): string;
+}
+
+/** Port interface for persisting data to Git's object database. */
+export interface GitPersistencePort {
+  writeBlob(content: Buffer | string): Promise<string>;
+  writeTree(entries: string[]): Promise<string>;
+  readBlob(oid: string): Promise<Buffer>;
+  readTree(
+    treeOid: string,
+  ): Promise<Array<{ mode: string; type: string; oid: string; name: string }>>;
+}
+
+/** Constructor options for {@link CasService}. */
+export interface CasServiceOptions {
+  persistence: GitPersistencePort;
+  codec: CodecPort;
+  crypto: CryptoPort;
+  chunkSize?: number;
+}
+
+/**
+ * Domain service for Content Addressable Storage operations.
+ *
+ * Provides chunking, encryption, and integrity verification for storing
+ * arbitrary data in Git's object database.
+ */
+export default class CasService extends EventEmitter {
+  readonly persistence: GitPersistencePort;
+  readonly codec: CodecPort;
+  readonly crypto: CryptoPort;
+  readonly chunkSize: number;
+
+  constructor(options: CasServiceOptions);
+
+  encrypt(options: {
+    buffer: Buffer;
+    key: Buffer;
+  }): Promise<{ buf: Buffer; meta: EncryptionMeta }>;
+
+  decrypt(options: {
+    buffer: Buffer;
+    key: Buffer;
+    meta: EncryptionMeta;
+  }): Promise<Buffer>;
+
+  store(options: {
+    source: AsyncIterable<Buffer>;
+    slug: string;
+    filename: string;
+    encryptionKey?: Buffer;
+  }): Promise<Manifest>;
+
+  createTree(options: { manifest: Manifest }): Promise<string>;
+
+  restore(options: {
+    manifest: Manifest;
+    encryptionKey?: Buffer;
+  }): Promise<{ buffer: Buffer; bytesWritten: number }>;
+
+  readManifest(options: { treeOid: string }): Promise<Manifest>;
+
+  deleteAsset(options: {
+    treeOid: string;
+  }): Promise<{ slug: string; chunksOrphaned: number }>;
+
+  findOrphanedChunks(options: {
+    treeOids: string[];
+  }): Promise<{ referenced: Set<string>; total: number }>;
+
+  verifyIntegrity(manifest: Manifest): Promise<boolean>;
+}

package/src/domain/services/CasService.js

@@ -1,3 +1,8 @@
+/* @ts-self-types="./CasService.d.ts" */
+/**
+ * @fileoverview Domain service for Content Addressable Storage operations.
+ * @module
+ */
 import { EventEmitter } from 'node:events';
 import Manifest from '../value-objects/Manifest.js';
 import CasError from '../errors/CasError.js';

package/src/domain/value-objects/Chunk.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Immutable value object representing a single content chunk.
+ */
+export default class Chunk {
+  readonly index: number;
+  readonly size: number;
+  readonly digest: string;
+  readonly blob: string;
+
+  constructor(data: {
+    index: number;
+    size: number;
+    digest: string;
+    blob: string;
+  });
+}

package/src/domain/value-objects/Manifest.d.ts

@@ -0,0 +1,33 @@
+import Chunk from "./Chunk.js";
+
+/** AES-256-GCM encryption metadata attached to an encrypted manifest. */
+export interface EncryptionMeta {
+  algorithm: string;
+  nonce: string;
+  tag: string;
+  encrypted: boolean;
+}
+
+/** Raw manifest data accepted by the {@link Manifest} constructor. */
+export interface ManifestData {
+  slug: string;
+  filename: string;
+  size: number;
+  chunks: Array<{ index: number; size: number; digest: string; blob: string }>;
+  encryption?: EncryptionMeta;
+}
+
+/**
+ * Immutable value object representing a file manifest.
+ */
+export default class Manifest {
+  readonly slug: string;
+  readonly filename: string;
+  readonly size: number;
+  readonly chunks: readonly Chunk[];
+  readonly encryption?: EncryptionMeta;
+
+  constructor(data: ManifestData);
+
+  toJSON(): ManifestData;
+}