@nakafa/aksara-contracts 0.27.0

package/dist/runtime/verify.js

@@ -0,0 +1,123 @@
+import { Effect } from "effect";
+import { verifySignedContentArtifact } from "#contracts/artifact/verify";
+import { hashContentProjection } from "#contracts/projection/hash";
+import { verifyContentReleaseBundle } from "#contracts/release/verify";
+import { verifyContentRendererCompatibility } from "#contracts/renderer/compatibility";
+import { validateLiveRendererManifestHash } from "#contracts/renderer/manifest";
+import { ContentRuntimeMismatchError } from "#contracts/runtime/error";
+import { decodePublicContentRuntimeRequest, decodePublicContentRuntimeResponse, } from "#contracts/runtime/spec";
+/** Checks one article path preserves its pair-grouped physical source identity. */
+function hasArticleSourcePath(projection, sourcePath) {
+    const prefix = `packages/corpus/articles/${projection.category}/`;
+    const suffix = `/${projection.artifactLocale}.mdx`;
+    if (!(sourcePath.startsWith(prefix) && sourcePath.endsWith(suffix))) {
+        return false;
+    }
+    const sourceRoot = sourcePath.slice(prefix.length, -suffix.length);
+    const segments = sourceRoot.split("/");
+    return segments.length === 2 && segments.join("-") === projection.articleSlug;
+}
+/** Checks one page path matches its signed source-owned provenance. */
+function hasPageSourcePath(projection, sourcePath) {
+    return sourcePath === projection.sourcePath;
+}
+/** Checks one public path exactly matches its projected content family. */
+function hasProjectionSourcePath(projection, sourcePath) {
+    if (projection.kind === "article") {
+        return hasArticleSourcePath(projection, sourcePath);
+    }
+    if (projection.kind === "public-page") {
+        return hasPageSourcePath(projection, sourcePath);
+    }
+    return (sourcePath ===
+        `packages/corpus/${projection.contentKey}/${projection.artifactLocale}.mdx`);
+}
+/** Verifies one active public artifact belongs to its exact route request. */
+const verifyPublicIdentity = Effect.fn("AksaraContracts.verifyPublicIdentity")(function* (request, response) {
+    if (response.projection.appLocale !== request.appLocale) {
+        return yield* new ContentRuntimeMismatchError({ reason: "locale" });
+    }
+    if (response.projection.publicPath !== request.publicPath) {
+        return yield* new ContentRuntimeMismatchError({ reason: "publicPath" });
+    }
+    if (!hasProjectionSourcePath(response.projection, response.sourcePath)) {
+        return yield* new ContentRuntimeMismatchError({ reason: "sourcePath" });
+    }
+    if (response.projectionHash !== hashContentProjection(response.projection)) {
+        return yield* new ContentRuntimeMismatchError({
+            reason: "projectionHash",
+        });
+    }
+});
+/** Binds public content to the exact authenticated active release. */
+const verifyPublicRelease = Effect.fn("AksaraContracts.verifyPublicRelease")(function* (response, bundle) {
+    if (response.activeReleaseId !== bundle.release.manifest.releaseId) {
+        return yield* new ContentRuntimeMismatchError({
+            reason: "activeReleaseId",
+        });
+    }
+    if (response.activeManifestHash !== bundle.release.manifestHash) {
+        return yield* new ContentRuntimeMismatchError({
+            reason: "activeManifestHash",
+        });
+    }
+});
+/** Authenticates one public response and applies its explicit use policy. */
+const verifyPublicRuntimeExchange = Effect.fn("AksaraContracts.verifyPublicRuntimeExchange")(function* (input) {
+    const request = yield* decodePublicContentRuntimeRequest(input.request);
+    const response = yield* decodePublicContentRuntimeResponse(input.response);
+    if (response.kind !== "found") {
+        return response;
+    }
+    yield* verifyPublicIdentity(request, response);
+    const bundle = yield* verifyContentReleaseBundle({
+        release: response.release,
+        rendererManifest: response.rendererManifest,
+    });
+    yield* verifyPublicRelease(response, bundle);
+    const artifact = yield* verifySignedContentArtifact({
+        artifact: response.artifact,
+        rendererContractVersion: bundle.release.manifest.rendererContractVersion,
+        rendererManifest: bundle.rendererManifest,
+    });
+    if (input.policy.kind === "evidence") {
+        return response;
+    }
+    const liveRenderer = yield* validateLiveRendererManifestHash(input.policy.rendererManifest);
+    if (liveRenderer.hash !== bundle.rendererManifest.hash) {
+        yield* verifyContentRendererCompatibility({
+            payload: artifact.payload,
+            rendererContractVersion: bundle.release.manifest.rendererContractVersion,
+            rendererManifest: liveRenderer,
+        });
+    }
+    return response;
+});
+/**
+ * Authenticates independently signed runtime evidence for one exact request.
+ *
+ * This capability does not claim that a non-rendering consumer can execute the
+ * artifact with a live renderer.
+ */
+export const verifyContentRuntimeEvidenceExchange = Effect.fn("AksaraContracts.verifyContentRuntimeEvidenceExchange")(function* (input) {
+    return yield* verifyPublicRuntimeExchange({
+        ...input,
+        policy: { kind: "evidence" },
+    });
+});
+/**
+ * Verifies independently signed runtime values selected for one exact request.
+ *
+ * Active catalog membership is trusted authenticated target state as recorded
+ * in ADR 0002, not an artifact property inferred from the release digest.
+ */
+export const verifyContentRuntimeExchange = Effect.fn("AksaraContracts.verifyContentRuntimeExchange")(function* (input) {
+    return yield* verifyPublicRuntimeExchange({
+        policy: {
+            kind: "execution",
+            rendererManifest: input.rendererManifest,
+        },
+        request: input.request,
+        response: input.response,
+    });
+});

package/dist/signature/spec.d.ts

@@ -0,0 +1,53 @@
+import { Context, type Effect, Schema } from "effect";
+import { type SigningKeyId } from "#contracts/ids";
+/** Authenticated object whose Ed25519 signature is being checked. */
+export declare const ContentSignatureSubjectSchema: Schema.Literals<readonly ["artifact", "release", "tryout-runtime-bundle"]>;
+export type ContentSignatureSubject = typeof ContentSignatureSubjectSchema.Type;
+declare const SigningKeyNotFoundError_base: Schema.Class<SigningKeyNotFoundError, Schema.TaggedStruct<"SigningKeyNotFoundError", {
+    readonly keyId: Schema.brand<Schema.String, "@NakafaAI/AksaraSigningKeyId">;
+}>, import("effect/Cause").YieldableError>;
+/** No trusted public key exists for the requested key identifier. */
+export declare class SigningKeyNotFoundError extends SigningKeyNotFoundError_base {
+}
+declare const SigningKeyResolutionError_base: Schema.Class<SigningKeyResolutionError, Schema.TaggedStruct<"SigningKeyResolutionError", {
+    readonly keyId: Schema.brand<Schema.String, "@NakafaAI/AksaraSigningKeyId">;
+}>, import("effect/Cause").YieldableError>;
+/** The trusted key source could not resolve the requested public key. */
+export declare class SigningKeyResolutionError extends SigningKeyResolutionError_base {
+}
+declare const PublicKeyParseError_base: Schema.Class<PublicKeyParseError, Schema.TaggedStruct<"PublicKeyParseError", {
+    readonly keyId: Schema.brand<Schema.String, "@NakafaAI/AksaraSigningKeyId">;
+    readonly subject: Schema.Literals<readonly ["artifact", "release", "tryout-runtime-bundle"]>;
+}>, import("effect/Cause").YieldableError>;
+/** A resolved public key could not be parsed without exposing its contents. */
+export declare class PublicKeyParseError extends PublicKeyParseError_base {
+}
+declare const PublicKeyTypeError_base: Schema.Class<PublicKeyTypeError, Schema.TaggedStruct<"PublicKeyTypeError", {
+    readonly keyId: Schema.brand<Schema.String, "@NakafaAI/AksaraSigningKeyId">;
+    readonly subject: Schema.Literals<readonly ["artifact", "release", "tryout-runtime-bundle"]>;
+}>, import("effect/Cause").YieldableError>;
+/** A resolved public key is not an Ed25519 verification key. */
+export declare class PublicKeyTypeError extends PublicKeyTypeError_base {
+}
+declare const SignatureCheckError_base: Schema.Class<SignatureCheckError, Schema.TaggedStruct<"SignatureCheckError", {
+    readonly keyId: Schema.brand<Schema.String, "@NakafaAI/AksaraSigningKeyId">;
+    readonly subject: Schema.Literals<readonly ["artifact", "release", "tryout-runtime-bundle"]>;
+}>, import("effect/Cause").YieldableError>;
+/** Web Crypto could not complete an Ed25519 verification operation. */
+export declare class SignatureCheckError extends SignatureCheckError_base {
+}
+declare const SignatureInvalidError_base: Schema.Class<SignatureInvalidError, Schema.TaggedStruct<"SignatureInvalidError", {
+    readonly keyId: Schema.brand<Schema.String, "@NakafaAI/AksaraSigningKeyId">;
+    readonly subject: Schema.Literals<readonly ["artifact", "release", "tryout-runtime-bundle"]>;
+}>, import("effect/Cause").YieldableError>;
+/** The signature does not authenticate the supplied canonical bytes. */
+export declare class SignatureInvalidError extends SignatureInvalidError_base {
+}
+declare const ContentVerificationKeyResolver_base: Context.ServiceClass<ContentVerificationKeyResolver, "AksaraContentVerificationKeyResolver", {
+    /** Resolves a reviewed public key without exposing key material in errors. */
+    readonly resolve: (keyId: SigningKeyId) => Effect.Effect<string, SigningKeyNotFoundError | SigningKeyResolutionError>;
+}>;
+/** Server-side trust seam for resolving reviewed Ed25519 public keys. */
+export declare class ContentVerificationKeyResolver extends ContentVerificationKeyResolver_base {
+}
+export {};

package/dist/signature/spec.js

@@ -0,0 +1,29 @@
+import { Context, Schema } from "effect";
+import { SigningKeyIdSchema } from "#contracts/ids";
+/** Authenticated object whose Ed25519 signature is being checked. */
+export const ContentSignatureSubjectSchema = Schema.Literals([
+    "artifact",
+    "release",
+    "tryout-runtime-bundle",
+]);
+/** No trusted public key exists for the requested key identifier. */
+export class SigningKeyNotFoundError extends Schema.TaggedError()("SigningKeyNotFoundError", { keyId: SigningKeyIdSchema }) {
+}
+/** The trusted key source could not resolve the requested public key. */
+export class SigningKeyResolutionError extends Schema.TaggedError()("SigningKeyResolutionError", { keyId: SigningKeyIdSchema }) {
+}
+/** A resolved public key could not be parsed without exposing its contents. */
+export class PublicKeyParseError extends Schema.TaggedError()("PublicKeyParseError", { keyId: SigningKeyIdSchema, subject: ContentSignatureSubjectSchema }) {
+}
+/** A resolved public key is not an Ed25519 verification key. */
+export class PublicKeyTypeError extends Schema.TaggedError()("PublicKeyTypeError", { keyId: SigningKeyIdSchema, subject: ContentSignatureSubjectSchema }) {
+}
+/** Web Crypto could not complete an Ed25519 verification operation. */
+export class SignatureCheckError extends Schema.TaggedError()("SignatureCheckError", { keyId: SigningKeyIdSchema, subject: ContentSignatureSubjectSchema }) {
+}
+/** The signature does not authenticate the supplied canonical bytes. */
+export class SignatureInvalidError extends Schema.TaggedError()("SignatureInvalidError", { keyId: SigningKeyIdSchema, subject: ContentSignatureSubjectSchema }) {
+}
+/** Server-side trust seam for resolving reviewed Ed25519 public keys. */
+export class ContentVerificationKeyResolver extends Context.Service()("AksaraContentVerificationKeyResolver") {
+}

package/dist/signature/trusted.d.ts

@@ -0,0 +1,19 @@
+import { Effect, Schema } from "effect";
+import { SigningKeyNotFoundError, SigningKeyResolutionError } from "#contracts/signature/spec";
+/** One code-reviewed Ed25519 public key retained for release verification. */
+export declare const TrustedKeySchema: Schema.Struct<{
+    readonly keyId: Schema.brand<Schema.String, "@NakafaAI/AksaraSigningKeyId">;
+    readonly publicKeyPem: Schema.NonEmptyString;
+}>;
+export type TrustedKey = typeof TrustedKeySchema.Type;
+/** Only this reviewed identity may sign newly published content. */
+export declare const ACTIVE_SIGNING_KEY_ID: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSigningKeyId">;
+/** Production keys retained while signed content may still reference them. */
+export declare const TRUSTED_CONTENT_KEYS: readonly Readonly<{
+    readonly keyId: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSigningKeyId">;
+    readonly publicKeyPem: string;
+}>[];
+/** Builds an immutable exact-ID resolver from code-owned retained entries. */
+export declare function makeTrustedKeyResolver(entries: readonly TrustedKey[]): {
+    readonly resolve: (keyId: import("#contracts/ids").SigningKeyId) => Effect.Effect<string, SigningKeyNotFoundError | SigningKeyResolutionError>;
+};

package/dist/signature/trusted.js

@@ -0,0 +1,32 @@
+import { Effect, Schema } from "effect";
+import { SigningKeyIdSchema } from "#contracts/ids";
+import { ContentVerificationKeyResolver, SigningKeyNotFoundError, SigningKeyResolutionError, } from "#contracts/signature/spec";
+/** One code-reviewed Ed25519 public key retained for release verification. */
+export const TrustedKeySchema = Schema.Struct({
+    keyId: SigningKeyIdSchema,
+    publicKeyPem: Schema.NonEmptyString,
+});
+const ACTIVE_CONTENT_KEY = Object.freeze(TrustedKeySchema.make({
+    keyId: SigningKeyIdSchema.make("content-2026-07-23"),
+    publicKeyPem: "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEADaLoLeK2jGt3Jav3xpfXU5BNWYOo086miCmkV8FCmsE=\n-----END PUBLIC KEY-----\n",
+}));
+/** Only this reviewed identity may sign newly published content. */
+export const ACTIVE_SIGNING_KEY_ID = ACTIVE_CONTENT_KEY.keyId;
+/** Production keys retained while signed content may still reference them. */
+export const TRUSTED_CONTENT_KEYS = Object.freeze([ACTIVE_CONTENT_KEY]);
+/** Builds an immutable exact-ID resolver from code-owned retained entries. */
+export function makeTrustedKeyResolver(entries) {
+    const retained = entries.map((entry) => ({ ...entry }));
+    return ContentVerificationKeyResolver.of({
+        resolve: (keyId) => {
+            const [match, ...duplicates] = retained.filter((entry) => entry.keyId === keyId);
+            if (match === undefined) {
+                return Effect.fail(new SigningKeyNotFoundError({ keyId }));
+            }
+            if (duplicates.length > 0) {
+                return Effect.fail(new SigningKeyResolutionError({ keyId }));
+            }
+            return Effect.succeed(match.publicKeyPem);
+        },
+    });
+}

package/dist/signature/verify.d.ts

@@ -0,0 +1,10 @@
+import { Effect } from "effect";
+import type { Ed25519Signature, SigningKeyId } from "#contracts/ids";
+import { type ContentSignatureSubject, ContentVerificationKeyResolver, PublicKeyParseError, PublicKeyTypeError, SignatureCheckError, SignatureInvalidError } from "#contracts/signature/spec";
+/** Resolves trust and verifies domain-separated canonical bytes with Ed25519. */
+export declare const verifyEd25519Signature: (input: {
+    readonly keyId: SigningKeyId;
+    readonly message: string;
+    readonly signature: Ed25519Signature;
+    readonly subject: ContentSignatureSubject;
+}) => Effect.Effect<undefined, PublicKeyParseError | PublicKeyTypeError | SignatureCheckError | SignatureInvalidError | import("#contracts/signature/spec").SigningKeyNotFoundError | import("#contracts/signature/spec").SigningKeyResolutionError, ContentVerificationKeyResolver>;

package/dist/signature/verify.js

@@ -0,0 +1,82 @@
+import { Effect } from "effect";
+import { ContentVerificationKeyResolver, PublicKeyParseError, PublicKeyTypeError, SignatureCheckError, SignatureInvalidError, } from "#contracts/signature/spec";
+const PUBLIC_KEY_HEADER = "-----BEGIN PUBLIC KEY-----\n";
+const PUBLIC_KEY_FOOTER = "-----END PUBLIC KEY-----";
+const ED25519_SPKI_PREFIX = "302a300506032b6570032100";
+const PUBLIC_KEY_BASE64_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/u;
+/** Decodes canonical base64 text without a Node Buffer dependency. */
+function decodeBase64(value) {
+    const decoded = atob(value);
+    return Uint8Array.from(decoded, (character) => character.charCodeAt(0));
+}
+/** Encodes bytes as lowercase hexadecimal for one exact key-type check. */
+function encodeHex(value) {
+    let hex = "";
+    for (const byte of value) {
+        hex += byte.toString(16).padStart(2, "0");
+    }
+    return hex;
+}
+/** Reads the reviewed SPKI bytes from one exact public-key PEM. */
+function decodePublicKeyPem(keyId, publicKeyPem, subject) {
+    const normalizedPublicKeyPem = publicKeyPem.replaceAll("\r\n", "\n");
+    if (!(normalizedPublicKeyPem.startsWith(PUBLIC_KEY_HEADER) &&
+        normalizedPublicKeyPem.trimEnd().endsWith(PUBLIC_KEY_FOOTER))) {
+        return Effect.fail(new PublicKeyParseError({ keyId, subject }));
+    }
+    return Effect.try({
+        catch: () => new PublicKeyParseError({ keyId, subject }),
+        try: () => {
+            const body = normalizedPublicKeyPem
+                .slice(PUBLIC_KEY_HEADER.length)
+                .replace(PUBLIC_KEY_FOOTER, "")
+                .replaceAll("\n", "")
+                .trim();
+            if (!PUBLIC_KEY_BASE64_PATTERN.test(body) || body.length % 4 !== 0) {
+                throw new TypeError("Invalid public-key base64");
+            }
+            return decodeBase64(body);
+        },
+    });
+}
+/** Imports one exact Ed25519 SPKI key through Web Crypto. */
+function importEd25519PublicKey(keyId, publicKeyPem, subject) {
+    return Effect.gen(function* () {
+        const bytes = yield* decodePublicKeyPem(keyId, publicKeyPem, subject);
+        if (bytes.byteLength !== 44 ||
+            !encodeHex(bytes.slice(0, 12)).startsWith(ED25519_SPKI_PREFIX)) {
+            return yield* new PublicKeyTypeError({ keyId, subject });
+        }
+        return yield* Effect.tryPromise({
+            catch: () => new PublicKeyParseError({ keyId, subject }),
+            try: () => crypto.subtle.importKey("spki", bytes, { name: "Ed25519" }, false, [
+                "verify",
+            ]),
+        });
+    });
+}
+/** Decodes one unpadded base64url Ed25519 signature. */
+function decodeSignature(signature) {
+    const base64 = signature.replaceAll("-", "+").replaceAll("_", "/");
+    return decodeBase64(base64.padEnd(Math.ceil(base64.length / 4) * 4, "="));
+}
+/** Resolves trust and verifies domain-separated canonical bytes with Ed25519. */
+export const verifyEd25519Signature = Effect.fn("AksaraContracts.verifyEd25519Signature")(function* (input) {
+    const resolver = yield* ContentVerificationKeyResolver;
+    const publicKeyPem = yield* resolver.resolve(input.keyId);
+    const publicKey = yield* importEd25519PublicKey(input.keyId, publicKeyPem, input.subject);
+    const valid = yield* Effect.tryPromise({
+        catch: () => new SignatureCheckError({
+            keyId: input.keyId,
+            subject: input.subject,
+        }),
+        try: () => crypto.subtle.verify("Ed25519", publicKey, decodeSignature(input.signature), new TextEncoder().encode(input.message)),
+    });
+    if (valid) {
+        return;
+    }
+    return yield* new SignatureInvalidError({
+        keyId: input.keyId,
+        subject: input.subject,
+    });
+});

package/dist/text/order.d.ts

@@ -0,0 +1,2 @@
+/** Compares strings by stable JavaScript UTF-16 code-unit order. */
+export declare function compareCodeUnits(left: string, right: string): -1 | 0 | 1;

package/dist/text/order.js

@@ -0,0 +1,10 @@
+/** Compares strings by stable JavaScript UTF-16 code-unit order. */
+export function compareCodeUnits(left, right) {
+    if (left < right) {
+        return -1;
+    }
+    if (left > right) {
+        return 1;
+    }
+    return 0;
+}

package/dist/text/syntax.d.ts

@@ -0,0 +1,6 @@
+/** Checks one lowercase kebab-case segment without owning its domain meaning. */
+export declare function isLowerKebab(value: string): boolean;
+/** Checks one slash-separated path of lowercase kebab-case segments. */
+export declare function isLowerKebabPath(value: string): boolean;
+/** Checks one whitespace-free absolute HTTPS source URL. */
+export declare function isHttpsUrl(value: string): boolean;

package/dist/text/syntax.js

@@ -0,0 +1,15 @@
+const LOWER_KEBAB_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const LOWER_KEBAB_PATH_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*$/u;
+const HTTPS_URL_PATTERN = /^https:\/\/\S+$/u;
+/** Checks one lowercase kebab-case segment without owning its domain meaning. */
+export function isLowerKebab(value) {
+    return LOWER_KEBAB_PATTERN.test(value);
+}
+/** Checks one slash-separated path of lowercase kebab-case segments. */
+export function isLowerKebabPath(value) {
+    return LOWER_KEBAB_PATH_PATTERN.test(value);
+}
+/** Checks one whitespace-free absolute HTTPS source URL. */
+export function isHttpsUrl(value) {
+    return HTTPS_URL_PATTERN.test(value);
+}