@nakafa/aksara-contracts 0.27.0

package/dist/release/rollback/digest.d.ts

@@ -0,0 +1,126 @@
+import { Effect, Schema, Stream } from "effect";
+import { type ReleaseId } from "#contracts/ids";
+import { type RollbackSnapshotEntry } from "#contracts/release/rollback/spec";
+import type { ContentReleaseManifest } from "#contracts/release/spec";
+declare const RollbackSnapshotHashError_base: Schema.Class<RollbackSnapshotHashError, Schema.TaggedStruct<"RollbackSnapshotHashError", {
+    readonly releaseId: Schema.brand<Schema.String, "@NakafaAI/AksaraReleaseId">;
+}>, import("effect/Cause").YieldableError>;
+/** SHA-256 computation failed before rollback-state integrity was established. */
+export declare class RollbackSnapshotHashError extends RollbackSnapshotHashError_base {
+}
+declare const RollbackSnapshotCountMismatchError_base: Schema.Class<RollbackSnapshotCountMismatchError, Schema.TaggedStruct<"RollbackSnapshotCountMismatchError", {
+    readonly actualCount: Schema.Finite;
+    readonly expectedCount: Schema.Finite;
+    readonly releaseId: Schema.brand<Schema.String, "@NakafaAI/AksaraReleaseId">;
+}>, import("effect/Cause").YieldableError>;
+/** A replayed rollback snapshot has a different signed entry count. */
+export declare class RollbackSnapshotCountMismatchError extends RollbackSnapshotCountMismatchError_base {
+}
+declare const RollbackSnapshotDigestMismatchError_base: Schema.Class<RollbackSnapshotDigestMismatchError, Schema.TaggedStruct<"RollbackSnapshotDigestMismatchError", {
+    readonly actualDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    readonly expectedDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    readonly releaseId: Schema.brand<Schema.String, "@NakafaAI/AksaraReleaseId">;
+}>, import("effect/Cause").YieldableError>;
+/** A replayed rollback snapshot does not match its signed digest. */
+export declare class RollbackSnapshotDigestMismatchError extends RollbackSnapshotDigestMismatchError_base {
+}
+/** Keeps mutable Node hash state private behind the incremental digest seam. */
+declare class RollbackSnapshotDigestState {
+    #private;
+    count: number;
+    /** Initializes one domain-separated rollback snapshot hash. */
+    constructor();
+    /** Adds one canonical prior state to the snapshot digest. */
+    update(entry: RollbackSnapshotEntry): void;
+    /** Consumes the hash and returns its branded immutable identity. */
+    digest(): string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+}
+/** Creates a fresh domain-separated digest state for one rollback snapshot. */
+export declare function createRollbackSnapshotDigest(releaseId: ReleaseId): Effect.Effect<RollbackSnapshotDigestState, RollbackSnapshotHashError, never>;
+/** Adds one canonical prior state to an incremental rollback digest. */
+export declare function updateRollbackSnapshotDigest(releaseId: ReleaseId, state: RollbackSnapshotDigestState, entry: RollbackSnapshotEntry): Effect.Effect<RollbackSnapshotDigestState, RollbackSnapshotHashError, never>;
+/** Finalizes one rollback snapshot digest with a typed hash failure. */
+export declare function finalizeRollbackSnapshotDigest(releaseId: ReleaseId, state: RollbackSnapshotDigestState): Effect.Effect<string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">, RollbackSnapshotHashError, never>;
+/** Digests one rollback snapshot stream without retaining prior state bodies. */
+export declare const digestRollbackSnapshot: <E, R>(releaseId: string & import("effect/Brand").Brand<"@NakafaAI/AksaraReleaseId">, entries: Stream.Stream<{
+    readonly index: number;
+    readonly releaseId: string & import("effect/Brand").Brand<"@NakafaAI/AksaraReleaseId">;
+    readonly snapshot: {
+        readonly artifactLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraArtifactLocale">;
+        readonly contentKey: string & import("effect/Brand").Brand<"@NakafaAI/AksaraContentKey">;
+        readonly family: "article" | "material" | "page" | "question";
+        readonly state: "absent";
+    } | {
+        readonly head: {
+            readonly artifactHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly artifactLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraArtifactLocale">;
+            readonly compilerConfigHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly contentKey: string & import("effect/Brand").Brand<"@NakafaAI/AksaraContentKey">;
+            readonly delivery: "authenticated" | "entitled" | "public";
+            readonly projectionHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly publicPath?: (string & import("effect/Brand").Brand<"@NakafaAI/AksaraPublicPath">) | undefined;
+            readonly rendererDomain: "ai-ds" | "biology" | "chemistry" | "mathematics" | "physics" | "politics" | "site" | "snbt-general" | "snbt-math" | "snbt-plain" | "snbt-quant" | "tka-math";
+            readonly sourceHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly sourcePath: string & import("effect/Brand").Brand<"@NakafaAI/AksaraCorpusSourcePath">;
+            readonly family: "article";
+        };
+        readonly state: "article";
+    } | {
+        readonly head: {
+            readonly artifactHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly artifactLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraArtifactLocale">;
+            readonly compilerConfigHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly contentKey: string & import("effect/Brand").Brand<"@NakafaAI/AksaraContentKey">;
+            readonly delivery: "authenticated" | "entitled" | "public";
+            readonly projectionHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly publicPath?: (string & import("effect/Brand").Brand<"@NakafaAI/AksaraPublicPath">) | undefined;
+            readonly rendererDomain: "ai-ds" | "biology" | "chemistry" | "mathematics" | "physics" | "politics" | "site" | "snbt-general" | "snbt-math" | "snbt-plain" | "snbt-quant" | "tka-math";
+            readonly sourceHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly sourcePath: string & import("effect/Brand").Brand<"@NakafaAI/AksaraCorpusSourcePath">;
+            readonly family: "material";
+        };
+        readonly state: "material";
+    } | {
+        readonly head: {
+            readonly artifactHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly artifactLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraArtifactLocale">;
+            readonly compilerConfigHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly contentKey: string & import("effect/Brand").Brand<"@NakafaAI/AksaraContentKey">;
+            readonly delivery: "authenticated" | "entitled" | "public";
+            readonly projectionHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly publicPath?: (string & import("effect/Brand").Brand<"@NakafaAI/AksaraPublicPath">) | undefined;
+            readonly rendererDomain: "ai-ds" | "biology" | "chemistry" | "mathematics" | "physics" | "politics" | "site" | "snbt-general" | "snbt-math" | "snbt-plain" | "snbt-quant" | "tka-math";
+            readonly sourceHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly sourcePath: string & import("effect/Brand").Brand<"@NakafaAI/AksaraCorpusSourcePath">;
+            readonly family: "page";
+        };
+        readonly state: "page";
+    } | {
+        readonly head: {
+            readonly artifactHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly artifactLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraArtifactLocale">;
+            readonly compilerConfigHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly contentKey: string & import("effect/Brand").Brand<"@NakafaAI/AksaraContentKey">;
+            readonly delivery: "authenticated" | "entitled" | "public";
+            readonly projectionHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly publicPath?: (string & import("effect/Brand").Brand<"@NakafaAI/AksaraPublicPath">) | undefined;
+            readonly rendererDomain: "ai-ds" | "biology" | "chemistry" | "mathematics" | "physics" | "politics" | "site" | "snbt-general" | "snbt-math" | "snbt-plain" | "snbt-quant" | "tka-math";
+            readonly sourceHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            readonly sourcePath: string & import("effect/Brand").Brand<"@NakafaAI/AksaraCorpusSourcePath">;
+            readonly family: "question";
+        };
+        readonly state: "question";
+    };
+}, E, R>) => Effect.Effect<{
+    count: number;
+    digest: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+}, E | RollbackSnapshotHashError, R>;
+/** Authenticates a replayed prior-state stream against its signed release. */
+export declare const verifyRollbackSnapshot: <E, R>(input: {
+    readonly entries: Stream.Stream<RollbackSnapshotEntry, E, R>;
+    readonly manifest: ContentReleaseManifest;
+}) => Effect.Effect<{
+    count: number;
+    digest: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+}, E | RollbackSnapshotCountMismatchError | RollbackSnapshotDigestMismatchError | RollbackSnapshotHashError, R>;
+export {};

package/dist/release/rollback/digest.js

@@ -0,0 +1,92 @@
+import { createHash } from "node:crypto";
+import { Effect, Schema, Stream } from "effect";
+import { ReleaseIdSchema, Sha256HashSchema, } from "#contracts/ids";
+import { canonicalizeRollbackSnapshotEntry, } from "#contracts/release/rollback/spec";
+const ROLLBACK_SNAPSHOT_DIGEST_DOMAIN = "nakafa.aksara.rollback-snapshot";
+/** SHA-256 computation failed before rollback-state integrity was established. */
+export class RollbackSnapshotHashError extends Schema.TaggedError()("RollbackSnapshotHashError", { releaseId: ReleaseIdSchema }) {
+}
+/** A replayed rollback snapshot has a different signed entry count. */
+export class RollbackSnapshotCountMismatchError extends Schema.TaggedError()("RollbackSnapshotCountMismatchError", {
+    actualCount: Schema.Finite.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThanOrEqualTo(0))),
+    expectedCount: Schema.Finite.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThanOrEqualTo(0))),
+    releaseId: ReleaseIdSchema,
+}) {
+}
+/** A replayed rollback snapshot does not match its signed digest. */
+export class RollbackSnapshotDigestMismatchError extends Schema.TaggedError()("RollbackSnapshotDigestMismatchError", {
+    actualDigest: Sha256HashSchema,
+    expectedDigest: Sha256HashSchema,
+    releaseId: ReleaseIdSchema,
+}) {
+}
+/** Keeps mutable Node hash state private behind the incremental digest seam. */
+class RollbackSnapshotDigestState {
+    #hash = createHash("sha256");
+    count = 0;
+    /** Initializes one domain-separated rollback snapshot hash. */
+    constructor() {
+        this.#hash.update(ROLLBACK_SNAPSHOT_DIGEST_DOMAIN);
+        this.#hash.update("\n");
+    }
+    /** Adds one canonical prior state to the snapshot digest. */
+    update(entry) {
+        this.#hash.update(canonicalizeRollbackSnapshotEntry(entry));
+        this.#hash.update("\n");
+        this.count += 1;
+    }
+    /** Consumes the hash and returns its branded immutable identity. */
+    digest() {
+        return Sha256HashSchema.make(`sha256:${this.#hash.digest("hex")}`);
+    }
+}
+/** Creates a fresh domain-separated digest state for one rollback snapshot. */
+export function createRollbackSnapshotDigest(releaseId) {
+    return Effect.try({
+        catch: () => new RollbackSnapshotHashError({ releaseId }),
+        try: () => new RollbackSnapshotDigestState(),
+    });
+}
+/** Adds one canonical prior state to an incremental rollback digest. */
+export function updateRollbackSnapshotDigest(releaseId, state, entry) {
+    return Effect.try({
+        catch: () => new RollbackSnapshotHashError({ releaseId }),
+        try: () => {
+            state.update(entry);
+            return state;
+        },
+    });
+}
+/** Finalizes one rollback snapshot digest with a typed hash failure. */
+export function finalizeRollbackSnapshotDigest(releaseId, state) {
+    return Effect.try({
+        catch: () => new RollbackSnapshotHashError({ releaseId }),
+        try: () => state.digest(),
+    });
+}
+/** Digests one rollback snapshot stream without retaining prior state bodies. */
+export const digestRollbackSnapshot = Effect.fn("AksaraContracts.digestRollbackSnapshot")(function* (releaseId, entries) {
+    const initial = yield* createRollbackSnapshotDigest(releaseId);
+    const state = yield* entries.pipe(Stream.runFoldEffect(() => initial, (current, entry) => updateRollbackSnapshotDigest(releaseId, current, entry)));
+    const digest = yield* finalizeRollbackSnapshotDigest(releaseId, state);
+    return { count: state.count, digest };
+});
+/** Authenticates a replayed prior-state stream against its signed release. */
+export const verifyRollbackSnapshot = Effect.fn("AksaraContracts.verifyRollbackSnapshot")(function* (input) {
+    const summary = yield* digestRollbackSnapshot(input.manifest.releaseId, input.entries);
+    if (summary.count !== input.manifest.rollbackCount) {
+        return yield* new RollbackSnapshotCountMismatchError({
+            actualCount: summary.count,
+            expectedCount: input.manifest.rollbackCount,
+            releaseId: input.manifest.releaseId,
+        });
+    }
+    if (summary.digest !== input.manifest.rollbackDigest) {
+        return yield* new RollbackSnapshotDigestMismatchError({
+            actualDigest: summary.digest,
+            expectedDigest: input.manifest.rollbackDigest,
+            releaseId: input.manifest.releaseId,
+        });
+    }
+    return summary;
+});