@nakafa/aksara-contracts 0.27.0

package/dist/preview/artifact.d.ts

@@ -0,0 +1,198 @@
+import { Schema } from "effect";
+export declare const LOCAL_PREVIEW_ARTIFACT_PREFIX = "/v1/artifacts/";
+/** Builds the one content-addressed path owned by the preview protocol. */
+export declare function localPreviewArtifactPath(artifactHash: string): string;
+/** One signed artifact reference and its exact current renderer projection. */
+export declare const PreviewArtifactSchema: Schema.Struct<{
+    readonly artifactHash: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    readonly artifactPath: Schema.Trimmed;
+    readonly projection: Schema.Union<readonly [Schema.Struct<{
+        readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+        readonly articleRouteSlug: Schema.brand<Schema.String, "@NakafaAI/AksaraArticleRouteSlug">;
+        readonly articleSlug: Schema.brand<Schema.String, "@NakafaAI/AksaraArticleSlug">;
+        readonly artifactLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraArtifactLocale">;
+        readonly category: Schema.brand<Schema.String, "@NakafaAI/AksaraArticleCategory">;
+        readonly categoryRouteSlug: Schema.brand<Schema.String, "@NakafaAI/AksaraArticleRouteSlug">;
+        readonly contentKey: Schema.brand<Schema.String, "@NakafaAI/AksaraContentKey">;
+        readonly graph: Schema.Struct<{
+            readonly alignmentId: Schema.String;
+            readonly assetId: Schema.String;
+            readonly conceptId: Schema.String;
+            readonly learningObjectId: Schema.String;
+            readonly lensId: Schema.String;
+        }>;
+        readonly publicPath: Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">;
+        readonly categoryTitle: Schema.Trimmed;
+        readonly kind: Schema.Literal<"article">;
+        readonly metadata: Schema.Struct<{
+            readonly dateModified: Schema.optionalKey<Schema.String>;
+            readonly datePublished: Schema.String;
+            readonly authors: Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+            }>>;
+            readonly description: Schema.optional<Schema.String>;
+            readonly title: Schema.String;
+        }>;
+        readonly official: Schema.Boolean;
+        readonly parentPath: Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">;
+        readonly references: Schema.$Array<Schema.Struct<{
+            readonly authors: Schema.String;
+            readonly citation: Schema.optional<Schema.String>;
+            readonly details: Schema.optional<Schema.String>;
+            readonly publication: Schema.optional<Schema.String>;
+            readonly title: Schema.String;
+            readonly url: Schema.optional<Schema.String>;
+            readonly year: Schema.Finite;
+        }>>;
+        readonly sitemap: Schema.Literal<true>;
+    }>, Schema.Struct<{
+        readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+        readonly artifactLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraArtifactLocale">;
+        readonly contentKey: Schema.brand<Schema.String, "@NakafaAI/AksaraContentKey">;
+        readonly graph: Schema.Struct<{
+            readonly alignmentId: Schema.String;
+            readonly assetId: Schema.String;
+            readonly conceptId: Schema.String;
+            readonly learningObjectId: Schema.String;
+            readonly lensId: Schema.String;
+        }>;
+        readonly materialKey: Schema.brand<Schema.String, "@NakafaAI/AksaraMaterialKey">;
+        readonly order: Schema.Finite;
+        readonly publicPath: Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">;
+        readonly sectionKey: Schema.brand<Schema.String, "@NakafaAI/AksaraMaterialSection">;
+        readonly kind: Schema.Literal<"subject-lesson">;
+        readonly metadata: Schema.Struct<{
+            readonly dateModified: Schema.optionalKey<Schema.String>;
+            readonly datePublished: Schema.String;
+            readonly authors: Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+            }>>;
+            readonly description: Schema.optional<Schema.String>;
+            readonly subject: Schema.optional<Schema.String>;
+            readonly title: Schema.String;
+        }>;
+        readonly parentPath: Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">;
+        readonly sitemap: Schema.Literal<true>;
+        readonly topicTitle: Schema.String;
+    }>, Schema.Struct<{
+        readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+        readonly artifactLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraArtifactLocale">;
+        readonly contentKey: Schema.brand<Schema.String, "@NakafaAI/AksaraContentKey">;
+        readonly pageKey: Schema.brand<Schema.String, "@NakafaAI/AksaraPageKey">;
+        readonly publicPath: Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">;
+        readonly kind: Schema.Literal<"public-page">;
+        readonly metadata: Schema.Struct<{
+            readonly dateModified: Schema.optionalKey<Schema.String>;
+            readonly datePublished: Schema.String;
+            readonly description: Schema.Trimmed;
+            readonly title: Schema.Trimmed;
+        }>;
+        readonly sitemap: Schema.Literal<true>;
+        readonly sourcePath: Schema.brand<Schema.String, "@NakafaAI/AksaraCorpusSourcePath">;
+    }>, Schema.Union<readonly [Schema.Struct<{
+        readonly artifactLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraArtifactLocale">;
+        readonly contentKey: Schema.brand<Schema.String, "@NakafaAI/AksaraContentKey">;
+        readonly peerContentKey: Schema.brand<Schema.String, "@NakafaAI/AksaraContentKey">;
+        readonly questionKey: Schema.brand<Schema.String, "@NakafaAI/AksaraQuestionKey">;
+        readonly questionNumber: Schema.Finite;
+        readonly setKey: Schema.brand<Schema.String, "@NakafaAI/AksaraQuestionSetKey">;
+        readonly bodyKind: Schema.Literal<"question">;
+        readonly blueprint: Schema.optionalKey<Schema.Struct<{
+            readonly cognitiveLevel: Schema.String;
+            readonly contentDomain: Schema.String;
+            readonly topic: Schema.String;
+        }>>;
+        readonly kind: Schema.Literal<"question-body">;
+        readonly metadata: Schema.Struct<{
+            readonly dateModified: Schema.optionalKey<Schema.String>;
+            readonly datePublished: Schema.String;
+            readonly authors: Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+            }>>;
+            readonly title: Schema.String;
+        }>;
+        readonly stimulusKey: Schema.optionalKey<Schema.String>;
+        readonly response: Schema.Union<readonly [Schema.Struct<{
+            readonly categories: Schema.$Array<Schema.Struct<{
+                readonly categoryKey: Schema.String;
+                readonly label: Schema.NonEmptyArray<Schema.Union<readonly [Schema.Struct<{
+                    readonly display: Schema.Literals<readonly ["block", "inline"]>;
+                    readonly kind: Schema.Literal<"math">;
+                    readonly math: Schema.String;
+                }>, Schema.Struct<{
+                    readonly kind: Schema.Literal<"text">;
+                    readonly text: Schema.String;
+                }>]>>;
+                readonly order: Schema.Int;
+            }>>;
+            readonly kind: Schema.Literal<"category">;
+            readonly statements: Schema.$Array<Schema.Struct<{
+                readonly correctCategoryKey: Schema.String;
+                readonly label: Schema.NonEmptyArray<Schema.Union<readonly [Schema.Struct<{
+                    readonly display: Schema.Literals<readonly ["block", "inline"]>;
+                    readonly kind: Schema.Literal<"math">;
+                    readonly math: Schema.String;
+                }>, Schema.Struct<{
+                    readonly kind: Schema.Literal<"text">;
+                    readonly text: Schema.String;
+                }>]>>;
+                readonly order: Schema.Int;
+                readonly statementKey: Schema.String;
+            }>>;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"multiple-choice">;
+            readonly options: Schema.$Array<Schema.Struct<{
+                readonly isCorrect: Schema.Boolean;
+                readonly label: Schema.NonEmptyArray<Schema.Union<readonly [Schema.Struct<{
+                    readonly display: Schema.Literals<readonly ["block", "inline"]>;
+                    readonly kind: Schema.Literal<"math">;
+                    readonly math: Schema.String;
+                }>, Schema.Struct<{
+                    readonly kind: Schema.Literal<"text">;
+                    readonly text: Schema.String;
+                }>]>>;
+                readonly optionKey: Schema.String;
+                readonly order: Schema.Int;
+            }>>;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"single-choice">;
+            readonly options: Schema.$Array<Schema.Struct<{
+                readonly isCorrect: Schema.Boolean;
+                readonly label: Schema.NonEmptyArray<Schema.Union<readonly [Schema.Struct<{
+                    readonly display: Schema.Literals<readonly ["block", "inline"]>;
+                    readonly kind: Schema.Literal<"math">;
+                    readonly math: Schema.String;
+                }>, Schema.Struct<{
+                    readonly kind: Schema.Literal<"text">;
+                    readonly text: Schema.String;
+                }>]>>;
+                readonly optionKey: Schema.String;
+                readonly order: Schema.Int;
+            }>>;
+        }>]>;
+    }>, Schema.Struct<{
+        readonly artifactLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraArtifactLocale">;
+        readonly contentKey: Schema.brand<Schema.String, "@NakafaAI/AksaraContentKey">;
+        readonly peerContentKey: Schema.brand<Schema.String, "@NakafaAI/AksaraContentKey">;
+        readonly questionKey: Schema.brand<Schema.String, "@NakafaAI/AksaraQuestionKey">;
+        readonly questionNumber: Schema.Finite;
+        readonly setKey: Schema.brand<Schema.String, "@NakafaAI/AksaraQuestionSetKey">;
+        readonly bodyKind: Schema.Literal<"answer">;
+        readonly blueprint: Schema.optionalKey<Schema.Struct<{
+            readonly cognitiveLevel: Schema.String;
+            readonly contentDomain: Schema.String;
+            readonly topic: Schema.String;
+        }>>;
+        readonly kind: Schema.Literal<"question-body">;
+        readonly metadata: Schema.Struct<{
+            readonly dateModified: Schema.optionalKey<Schema.String>;
+            readonly datePublished: Schema.String;
+            readonly authors: Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+            }>>;
+            readonly title: Schema.String;
+        }>;
+        readonly stimulusKey: Schema.optionalKey<Schema.String>;
+    }>]>]>;
+}>;
+export type PreviewArtifact = typeof PreviewArtifactSchema.Type;

package/dist/preview/artifact.js

@@ -0,0 +1,20 @@
+import { Schema } from "effect";
+import { Sha256HashSchema } from "#contracts/ids";
+import { CurrentContentProjectionSchema } from "#contracts/projection/spec";
+export const LOCAL_PREVIEW_ARTIFACT_PREFIX = "/v1/artifacts/";
+/** Builds the one content-addressed path owned by the preview protocol. */
+export function localPreviewArtifactPath(artifactHash) {
+    return `${LOCAL_PREVIEW_ARTIFACT_PREFIX}${encodeURIComponent(artifactHash)}`;
+}
+/** Ensures one artifact endpoint is addressed only by its signed hash. */
+function hasCoherentArtifactPath(input) {
+    return input.artifactPath === localPreviewArtifactPath(input.artifactHash);
+}
+/** One signed artifact reference and its exact current renderer projection. */
+export const PreviewArtifactSchema = Schema.Struct({
+    artifactHash: Sha256HashSchema,
+    artifactPath: Schema.Trimmed.check(Schema.isNonEmpty()),
+    projection: CurrentContentProjectionSchema,
+}).pipe(Schema.check(Schema.makeFilter(hasCoherentArtifactPath, {
+    message: "Expected the artifact path to match its signed hash.",
+})));

package/dist/preview/auth.d.ts

@@ -0,0 +1,71 @@
+import { Effect, Schema } from "effect";
+import type { Sha256HashSchema } from "#contracts/ids";
+/** Stable wire format for one authenticated local renderer response. */
+export declare const PREVIEW_RENDERER_AUTH_FORMAT = "aksara-renderer-auth-v1";
+/** Fresh parent-generated challenge bound to one renderer request. */
+export declare const PreviewRendererNonceSchema: Schema.String;
+export type PreviewRendererNonce = typeof PreviewRendererNonceSchema.Type;
+/** Process-local HMAC key available only to the spawned Nakafa child. */
+export declare const PreviewRendererSecretSchema: Schema.String;
+export type PreviewRendererSecret = typeof PreviewRendererSecretSchema.Type;
+/** HMAC-SHA256 proof returned by the exact spawned Nakafa child. */
+export declare const PreviewRendererProofSchema: Schema.String;
+export type PreviewRendererProof = typeof PreviewRendererProofSchema.Type;
+/** Authenticated response returned only by the local renderer endpoint. */
+export declare const PreviewRendererResponseSchema: Schema.Struct<{
+    readonly format: Schema.Literal<"aksara-renderer-auth-v1">;
+    readonly manifest: Schema.Struct<{
+        readonly base: Schema.Struct<{
+            authoringComponents: Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+                readonly version: Schema.Finite;
+            }>>;
+            supportedComponents: Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+                readonly version: Schema.Finite;
+            }>>;
+        }>;
+        readonly domains: Schema.$Array<Schema.Struct<{
+            readonly authoringComponents: Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+                readonly version: Schema.Finite;
+            }>>;
+            readonly name: Schema.Literals<readonly ["ai-ds", "biology", "chemistry", "mathematics", "physics", "politics", "site", "snbt-general", "snbt-math", "snbt-plain", "snbt-quant", "tka-math"]>;
+            readonly supportedComponents: Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+                readonly version: Schema.Finite;
+            }>>;
+        }>>;
+        readonly format: Schema.Literal<"nakafa-mdx-renderer-v1">;
+        readonly hash: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+        readonly publishedDomains: Schema.$Array<Schema.Literals<readonly ["ai-ds", "biology", "chemistry", "mathematics", "physics", "politics", "site", "snbt-general", "snbt-math", "snbt-plain", "snbt-quant", "tka-math"]>>;
+        readonly rendererContractVersion: Schema.Literal<"1.0.0">;
+    }>;
+    readonly proof: Schema.String;
+}>;
+export type PreviewRendererResponse = typeof PreviewRendererResponseSchema.Type;
+declare const PreviewRendererAuthError_base: Schema.Class<PreviewRendererAuthError, Schema.TaggedStruct<"PreviewRendererAuthError", {
+    readonly reason: Schema.Literals<readonly ["compute", "invalid"]>;
+}>, import("effect/Cause").YieldableError>;
+/** Renderer authentication could not be computed or did not match. */
+export declare class PreviewRendererAuthError extends PreviewRendererAuthError_base {
+}
+/** Canonicalizes one challenge and exact validated renderer identity. */
+export declare function canonicalizePreviewRendererAuth(input: {
+    readonly manifestHash: typeof Sha256HashSchema.Type;
+    readonly nonce: PreviewRendererNonce;
+}): string;
+/** Computes one renderer response proof from a process-local secret. */
+export declare const computePreviewRendererProof: (input: {
+    readonly manifestHash: typeof Sha256HashSchema.Type;
+    readonly nonce: PreviewRendererNonce;
+    readonly secret: PreviewRendererSecret;
+}) => Effect.Effect<string, PreviewRendererAuthError, never>;
+/** Verifies one proof without exposing timing-sensitive string comparison. */
+export declare const verifyPreviewRendererProof: (input: {
+    readonly manifestHash: typeof Sha256HashSchema.Type;
+    readonly nonce: PreviewRendererNonce;
+    readonly proof: PreviewRendererProof;
+    readonly secret: PreviewRendererSecret;
+}) => Effect.Effect<undefined, PreviewRendererAuthError, never>;
+export {};

package/dist/preview/auth.js

@@ -0,0 +1,49 @@
+import { Buffer } from "node:buffer";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { Effect, Schema } from "effect";
+import { RendererManifestEnvelopeSchema } from "#contracts/renderer/contract";
+const BASE64URL_SHA256_PATTERN = /^[A-Za-z0-9_-]{43}$/u;
+/** Stable wire format for one authenticated local renderer response. */
+export const PREVIEW_RENDERER_AUTH_FORMAT = "aksara-renderer-auth-v1";
+/** Fresh parent-generated challenge bound to one renderer request. */
+export const PreviewRendererNonceSchema = Schema.String.pipe(Schema.check(Schema.isPattern(BASE64URL_SHA256_PATTERN)));
+/** Process-local HMAC key available only to the spawned Nakafa child. */
+export const PreviewRendererSecretSchema = Schema.String.pipe(Schema.check(Schema.isPattern(BASE64URL_SHA256_PATTERN)));
+/** HMAC-SHA256 proof returned by the exact spawned Nakafa child. */
+export const PreviewRendererProofSchema = Schema.String.pipe(Schema.check(Schema.isPattern(BASE64URL_SHA256_PATTERN)));
+/** Authenticated response returned only by the local renderer endpoint. */
+export const PreviewRendererResponseSchema = Schema.Struct({
+    format: Schema.Literal(PREVIEW_RENDERER_AUTH_FORMAT),
+    manifest: RendererManifestEnvelopeSchema,
+    proof: PreviewRendererProofSchema,
+});
+/** Renderer authentication could not be computed or did not match. */
+export class PreviewRendererAuthError extends Schema.TaggedError()("PreviewRendererAuthError", { reason: Schema.Literals(["compute", "invalid"]) }) {
+}
+/** Canonicalizes one challenge and exact validated renderer identity. */
+export function canonicalizePreviewRendererAuth(input) {
+    return JSON.stringify([
+        PREVIEW_RENDERER_AUTH_FORMAT,
+        input.nonce,
+        input.manifestHash,
+    ]);
+}
+/** Computes one renderer response proof from a process-local secret. */
+export const computePreviewRendererProof = Effect.fn("AksaraContracts.computePreviewRendererProof")(function* (input) {
+    return yield* Effect.try({
+        catch: () => new PreviewRendererAuthError({ reason: "compute" }),
+        try: () => PreviewRendererProofSchema.make(createHmac("sha256", Buffer.from(input.secret, "base64url"))
+            .update(canonicalizePreviewRendererAuth(input))
+            .digest("base64url")),
+    });
+});
+/** Verifies one proof without exposing timing-sensitive string comparison. */
+export const verifyPreviewRendererProof = Effect.fn("AksaraContracts.verifyPreviewRendererProof")(function* (input) {
+    const expected = yield* computePreviewRendererProof(input);
+    const actualBytes = Buffer.from(input.proof, "base64url");
+    const expectedBytes = Buffer.from(expected, "base64url");
+    if (timingSafeEqual(actualBytes, expectedBytes)) {
+        return;
+    }
+    return yield* new PreviewRendererAuthError({ reason: "invalid" });
+});