@warpgogol/werkstatt-shared 0.2.0

package/src/passport/schema.ts

@@ -0,0 +1,198 @@
+/******************************************************************************* 
+<MODULE_CONTRACT> 
+<purpose>Defines JSON schemas for passport-related data structures, ensuring data integrity and validation.</purpose> 
+ 
+ 
+<non-goals> 
+  <item>Do not handle data persistence or retrieval logic.</item> 
+  <item>Do not perform runtime data transformations outside of validation.</item> 
+  <item>Do not manage application state or side effects.</item> 
+</non-goals> 
+</MODULE_CONTRACT> 
+ 
+<CHANGE_SUMMARY>
+  <item>Tidied by compass.changesummary.tidy; see git history for prior entries.</item>
+</CHANGE_SUMMARY> 
+*******************************************************************************/
+
+/**
+ * @warpgogol/werkstatt-shared/passport — Passport JSON schema (schemaVersion 1.0)
+ *
+ * DNA-31 / RFC-0028
+ *
+ * This is the authoritative schema for dist/.well-known/cosmic-passport.json.
+ * Additive changes bump schemaVersion minor; breaking changes require a
+ * superseding RFC.
+ */
+
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Sub-schemas
+// ---------------------------------------------------------------------------
+
+const PlanetPinSchema = z.object({
+  cosmicPlanet: z.string().min(1),
+  pin: z.string().min(1),
+  semanticId: z.string().optional(),
+});
+
+const StarCompositionSchema = z.object({
+  route: z.string().min(1),
+  cosmicStar: z.string().min(1),
+  planets: z.array(PlanetPinSchema).default([]),
+});
+
+const CompositionSchema = z.object({
+  /**
+   * SHA-256 hash of the canonical system.yaml content at build time.
+   * Format: "sha256:<hex>"
+   */
+  systemHash: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+  constellation: z.string().min(1),
+  biome: z.string().min(1),
+  stars: z.array(StarCompositionSchema).default([]),
+});
+
+const VCProofSchema = z.object({
+  type: z.literal("Ed25519Signature2020"),
+  created: z.string(),
+  verificationMethod: z.string(),
+  proofPurpose: z.literal("assertionMethod"),
+  /** Multibase-encoded Ed25519 signature */
+  proofValue: z.string(),
+});
+
+const VerifiableCredentialSchema = z.object({
+  "@context": z.array(z.string()),
+  type: z.array(z.string()),
+  issuer: z.string(),
+  issuanceDate: z.string(),
+  credentialSubject: z.object({
+    id: z.string(),
+    systemHash: z.string(),
+    commitSha: z.string(),
+  }),
+  proof: VCProofSchema,
+});
+
+const ProvenanceSchema = z.object({
+  commitSha: z.string().min(1),
+  commitAt: z.string(),
+  builtAt: z.string(),
+  buildDurationMs: z.number().int().nonnegative(),
+  builder: z.string().min(1),
+  keyVersion: z.string().min(1),
+  verifiableCredential: VerifiableCredentialSchema,
+});
+
+const NebulaPillarSchema = z.object({
+  score: z.number().min(0).max(100),
+  weight: z.number().min(0).max(1),
+});
+
+const ScoresSchema = z.object({
+  nebula: z.number().int().min(0).max(100),
+  pillars: z.object({
+    performance: NebulaPillarSchema,
+    accessibility: NebulaPillarSchema,
+    contentHealth: NebulaPillarSchema,
+    architecturalCompliance: NebulaPillarSchema,
+  }),
+});
+
+const LinksSchema = z.object({
+  starMapSvg: z.string(),
+  publicKey: z.string(),
+  dnaReport: z.string(),
+});
+
+// ---------------------------------------------------------------------------
+// Root schema
+// ---------------------------------------------------------------------------
+
+export const PassportSchema = z.object({
+  schemaVersion: z.literal("1.0"),
+  appId: z.string().min(1),
+  issuedAt: z.string(),
+  composition: CompositionSchema,
+  provenance: ProvenanceSchema,
+  scores: ScoresSchema,
+  links: LinksSchema,
+});
+
+// ---------------------------------------------------------------------------
+// Public key file schema (/.well-known/cosmic-passport-key.json)
+// ---------------------------------------------------------------------------
+
+export const PassportPublicKeyEntrySchema = z.object({
+  version: z.string().min(1),
+  active: z.boolean(),
+  type: z.literal("Ed25519VerificationKey2020"),
+  /** Multibase-encoded (base58btc, prefix "z") Ed25519 public key */
+  publicKeyMultibase: z.string().regex(/^z[1-9A-HJ-NP-Za-km-z]+$/),
+  createdAt: z.string(),
+});
+
+export const PassportPublicKeyFileSchema = z.object({
+  schemaVersion: z.literal("1.0"),
+  appId: z.string().min(1),
+  keys: z.array(PassportPublicKeyEntrySchema).min(1),
+});
+
+// ---------------------------------------------------------------------------
+// Identity credentials (RFC-0558)
+// ---------------------------------------------------------------------------
+
+export const SiteOwnershipCredentialSubjectSchema = z.object({
+  id: z.string().min(1),
+  siteId: z.string().min(1),
+  role: z.literal("owner"),
+});
+
+export const ActorDelegationCredentialSubjectSchema = z.object({
+  id: z.string().min(1),
+  siteId: z.string().min(1),
+  delegatedBy: z.string().min(1),
+  expiresAt: z.string().datetime(),
+  scopes: z.array(z.string().min(1)),
+});
+
+export const WerkstattCredentialSchema = z.object({
+  credentialId: z.string().min(1),
+  type: z.enum(["SiteOwnershipCredential", "ActorDelegationCredential"]),
+  subject: z.union([SiteOwnershipCredentialSubjectSchema, ActorDelegationCredentialSubjectSchema]),
+  proof: VCProofSchema,
+  issuedAt: z.string().datetime(),
+  issuer: z.string().min(1),
+});
+
+export const WerkstattIdentityConfigSchema = z.object({
+  schemaVersion: z.literal("1.0"),
+  operatorName: z.string().min(1),
+  operatorKeyPair: z.object({
+    publicKeyMultibase: z.string().regex(/^z[1-9A-HJ-NP-Za-km-z]+$/),
+    keyVersion: z.string().min(1),
+    algId: z.literal("Ed25519Signature2020"),
+  }),
+  authMode: z.enum(["permissive", "enforced"]),
+  domain: z.string().min(1),
+  issuedCredentials: z.array(WerkstattCredentialSchema),
+  revokedCredentialIds: z.array(z.string().min(1)),
+});
+
+// ---------------------------------------------------------------------------
+// TypeScript types
+// ---------------------------------------------------------------------------
+
+export type PassportJson = z.infer<typeof PassportSchema>;
+export type PassportPublicKeyFile = z.infer<typeof PassportPublicKeyFileSchema>;
+export type PassportPublicKeyEntry = z.infer<typeof PassportPublicKeyEntrySchema>;
+export type VCProof = z.infer<typeof VCProofSchema>;
+export type VerifiableCredential = z.infer<typeof VerifiableCredentialSchema>;
+export type SiteOwnershipCredentialSubject = z.infer<typeof SiteOwnershipCredentialSubjectSchema>;
+export type ActorDelegationCredentialSubject = z.infer<
+  typeof ActorDelegationCredentialSubjectSchema
+>;
+export type WerkstattCredential = z.infer<typeof WerkstattCredentialSchema>;
+export type WerkstattIdentityConfig = z.infer<typeof WerkstattIdentityConfigSchema>;

package/src/passport/sign.ts

@@ -0,0 +1,225 @@
+/* <MODULE_CONTRACT>
+<purpose>Facilitates Ed25519 key generation, signing, and verification for verifiable credentials.</purpose>
+<non-goals>
+  <item>Do not handle raw key storage or management.</item>
+  <item>Do not perform network operations or external API calls.</item>
+  <item>Do not parse or validate credential content beyond signing/verification.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Tidied by compass.changesummary.tidy; see git history for prior entries.</item>
+</CHANGE_SUMMARY> */
+
+/**
+ * @warpgogol/werkstatt-shared/passport — Ed25519 VC signing helpers
+ *
+ * DNA-34 / RFC-0028
+ *
+ * Uses the Web Crypto API (available in Node.js 16+ and all modern browsers).
+ * No private keys are ever written to disk by this module.
+ *
+ * SECURITY CONTRACT:
+ * - Private keys arrive exclusively as environment variable `PASSPORT_SIGNING_KEY`
+ *   (hex-encoded, 32 bytes) or as a runtime parameter in key-rotate.ts.
+ * - This module never logs, writes, or returns private key material.
+ */
+
+import * as ed from "@noble/ed25519";
+import bs58 from "bs58";
+import type { VCProof, VerifiableCredential } from "./schema.ts";
+
+// ---------------------------------------------------------------------------
+// Multibase base58btc encoding (prefix "z")
+// ---------------------------------------------------------------------------
+
+/** Encode bytes as multibase base58btc (prefix "z"). */
+export function toMultibase(bytes: Uint8Array): string {
+  return "z" + bs58.encode(bytes);
+}
+
+/** Decode multibase base58btc string (prefix "z") to bytes. */
+export function fromMultibase(multibase: string): Uint8Array {
+  if (!multibase.startsWith("z")) {
+    throw new Error(
+      `Unsupported multibase prefix "${multibase[0]}". Only "z" (base58btc) is supported.`,
+    );
+  }
+  return bs58.decode(multibase.slice(1));
+}
+
+// ---------------------------------------------------------------------------
+// The canonical credential subject digest
+// ---------------------------------------------------------------------------
+
+/** The data signed in the VC proof — composition hash + commit SHA. */
+export interface CredentialSubjectDigest {
+  systemHash: string;
+  commitSha: string;
+  issuedAt: string;
+  appId: string;
+}
+
+/**
+ * Produce the canonical UTF-8 bytes that are signed/verified.
+ * DETERMINISM: identical inputs → identical bytes.
+ */
+export function credentialBytes(subject: CredentialSubjectDigest): Uint8Array {
+  // Stable JSON: sorted keys, no whitespace
+  const canonical = JSON.stringify({
+    appId: subject.appId,
+    commitSha: subject.commitSha,
+    issuedAt: subject.issuedAt,
+    systemHash: subject.systemHash,
+  });
+  return new TextEncoder().encode(canonical);
+}
+
+// ---------------------------------------------------------------------------
+// Key generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a new Ed25519 keypair.
+ * @returns { privateKeyHex, publicKeyBytes, publicKeyMultibase }
+ *
+ * The private key is returned as a hex string for one-time copy into a
+ * GitHub Actions secret. It is NEVER written to disk by this function.
+ */
+export async function generateKeypair(): Promise<{
+  privateKeyHex: string;
+  publicKeyBytes: Uint8Array;
+  publicKeyMultibase: string;
+}> {
+  const privateKeyBytes = ed.utils.randomSecretKey();
+  const publicKeyBytes = await ed.getPublicKeyAsync(privateKeyBytes);
+  return {
+    privateKeyHex: Buffer.from(privateKeyBytes).toString("hex"),
+    publicKeyBytes,
+    publicKeyMultibase: toMultibase(publicKeyBytes),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Signing
+// ---------------------------------------------------------------------------
+
+/**
+ * Sign the credential subject and produce a W3C VC proof.
+ *
+ * @param subject       — canonical credential subject fields
+ * @param privateKeyHex — 32-byte Ed25519 private key as hex (from env secret)
+ * @param verificationMethod — DID key reference (e.g. "did:web:example.org#key-v1")
+ */
+// @ai-invariant: signCredential uses @noble/ed25519. Private keys arrive
+// exclusively as hex env vars — never logged, written to disk, or returned.
+// The signed output is a W3C VC with Ed25519Signature2020 proof.
+
+export async function signCredential(
+  subject: CredentialSubjectDigest,
+  privateKeyHex: string,
+  verificationMethod: string,
+): Promise<VCProof> {
+  const privateKeyBytes = new Uint8Array(Buffer.from(privateKeyHex, "hex"));
+  const message = credentialBytes(subject);
+  const signatureBytes = await ed.signAsync(message, privateKeyBytes);
+
+  return {
+    type: "Ed25519Signature2020",
+    created: subject.issuedAt,
+    verificationMethod,
+    proofPurpose: "assertionMethod",
+    proofValue: toMultibase(signatureBytes),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Verification
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify a VC proof against the published public key.
+ *
+ * @param subject           — credential subject fields from passport.json
+ * @param proof             — proof object from passport.json
+ * @param publicKeyMultibase — multibase public key from cosmic-passport-key.json
+ * @returns true if signature is valid
+ */
+export async function verifyCredential(
+  subject: CredentialSubjectDigest,
+  proof: VCProof,
+  publicKeyMultibase: string,
+): Promise<boolean> {
+  try {
+    const publicKeyBytes = fromMultibase(publicKeyMultibase);
+    const signatureBytes = fromMultibase(proof.proofValue);
+    const message = credentialBytes(subject);
+    return await ed.verifyAsync(signatureBytes, message, publicKeyBytes);
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Raw detached signing (RFC-0135 amend provenance trail)
+// ---------------------------------------------------------------------------
+
+/**
+ * Sign arbitrary bytes with an Ed25519 private key, returning a multibase
+ * base58btc detached signature. Reused by the amend provenance trail
+ * (RFC-0135) so provenance records carry the same signing facility as the
+ * Cosmic Passport (RFC-0028).
+ *
+ * @param privateKeyHex — 32-byte Ed25519 private key as hex (from env secret)
+ * @param message       — canonical bytes to sign
+ */
+export async function signBytes(privateKeyHex: string, message: Uint8Array): Promise<string> {
+  const privateKeyBytes = new Uint8Array(Buffer.from(privateKeyHex, "hex"));
+  const signatureBytes = await ed.signAsync(message, privateKeyBytes);
+  return toMultibase(signatureBytes);
+}
+
+/**
+ * Verify a multibase detached signature produced by {@link signBytes} against
+ * a multibase public key. Returns false on any decode/verify failure.
+ */
+export async function verifyBytes(
+  publicKeyMultibase: string,
+  message: Uint8Array,
+  signatureMultibase: string,
+): Promise<boolean> {
+  try {
+    const publicKeyBytes = fromMultibase(publicKeyMultibase);
+    const signatureBytes = fromMultibase(signatureMultibase);
+    return await ed.verifyAsync(signatureBytes, message, publicKeyBytes);
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Assemble full VC
+// ---------------------------------------------------------------------------
+
+export function assembleVerifiableCredential(
+  appId: string,
+  domain: string,
+  subject: CredentialSubjectDigest,
+  proof: VCProof,
+  keyVersion: string,
+): VerifiableCredential {
+  return {
+    "@context": ["https://www.w3.org/2018/credentials/v1"],
+    type: ["VerifiableCredential", "CosmicPassportCredential"],
+    issuer: `did:web:${domain}`,
+    issuanceDate: subject.issuedAt,
+    credentialSubject: {
+      id: `urn:warpgogol:app:${appId}`,
+      systemHash: subject.systemHash,
+      commitSha: subject.commitSha,
+    },
+    proof: {
+      ...proof,
+      verificationMethod: `did:web:${domain}#key-${keyVersion}`,
+    },
+  };
+}

package/src/passport/tests/schema.pbt.test.ts

@@ -0,0 +1,93 @@
+import { test, expect } from "vitest";
+import fc from "fast-check";
+import { PassportSchema } from "../schema.ts";
+
+const validHash = "sha256:" + "a".repeat(64);
+
+const arbValidPassport = fc.record({
+  schemaVersion: fc.constant("1.0"),
+  appId: fc.string({ minLength: 1, maxLength: 20 }),
+  issuedAt: fc.string({ minLength: 1, maxLength: 30 }),
+  composition: fc.record({
+    systemHash: fc.constant(validHash),
+    constellation: fc.string({ minLength: 1, maxLength: 20 }),
+    biome: fc.string({ minLength: 1, maxLength: 20 }),
+    stars: fc.constant([]),
+  }),
+  provenance: fc.record({
+    commitSha: fc.string({ minLength: 1, maxLength: 40 }),
+    commitAt: fc.string({ minLength: 1, maxLength: 30 }),
+    builtAt: fc.string({ minLength: 1, maxLength: 30 }),
+    buildDurationMs: fc.integer({ min: 0, max: 999999 }),
+    builder: fc.string({ minLength: 1, maxLength: 20 }),
+    keyVersion: fc.string({ minLength: 1, maxLength: 10 }),
+    verifiableCredential: fc.record({
+      "@context": fc.constant(["https://www.w3.org/2018/credentials/v1"]),
+      type: fc.constant(["VerifiableCredential"]),
+      issuer: fc.string({ minLength: 1, maxLength: 50 }),
+      issuanceDate: fc.string({ minLength: 1, maxLength: 30 }),
+      credentialSubject: fc.record({
+        id: fc.string({ minLength: 1, maxLength: 50 }),
+        systemHash: fc.constant(validHash),
+        commitSha: fc.string({ minLength: 1, maxLength: 40 }),
+      }),
+      proof: fc.record({
+        type: fc.constant("Ed25519Signature2020"),
+        created: fc.string({ minLength: 1, maxLength: 30 }),
+        verificationMethod: fc.string({ minLength: 1, maxLength: 50 }),
+        proofPurpose: fc.constant("assertionMethod"),
+        proofValue: fc.string({ minLength: 1, maxLength: 100 }),
+      }),
+    }),
+  }),
+  scores: fc.record({
+    nebula: fc.integer({ min: 0, max: 100 }),
+    pillars: fc.record({
+      performance: fc.record({
+        score: fc.float({ min: 0, max: 100, noNaN: true }),
+        weight: fc.float({ min: 0, max: 1, noNaN: true }),
+      }),
+      accessibility: fc.record({
+        score: fc.float({ min: 0, max: 100, noNaN: true }),
+        weight: fc.float({ min: 0, max: 1, noNaN: true }),
+      }),
+      contentHealth: fc.record({
+        score: fc.float({ min: 0, max: 100, noNaN: true }),
+        weight: fc.float({ min: 0, max: 1, noNaN: true }),
+      }),
+      architecturalCompliance: fc.record({
+        score: fc.float({ min: 0, max: 100, noNaN: true }),
+        weight: fc.float({ min: 0, max: 1, noNaN: true }),
+      }),
+    }),
+  }),
+  links: fc.record({
+    starMapSvg: fc.string({ minLength: 1, maxLength: 50 }),
+    publicKey: fc.string({ minLength: 1, maxLength: 50 }),
+    dnaReport: fc.string({ minLength: 1, maxLength: 50 }),
+  }),
+});
+
+test("PBT: valid passport always passes schema validation", () => {
+  fc.assert(
+    fc.property(arbValidPassport, (passport) => {
+      expect(PassportSchema.safeParse(passport).success).toBe(true);
+    }),
+  );
+});
+
+test("PBT: nebula score outside [0,100] always fails", () => {
+  fc.assert(
+    fc.property(
+      arbValidPassport,
+      fc.integer({ min: -500, max: 500 }).filter((n) => n < 0 || n > 100),
+      (passport, badNebula) => {
+        const result = PassportSchema.safeParse({
+          ...passport,
+          scores: { ...passport.scores, nebula: badNebula },
+        });
+        expect(result.success).toBe(false);
+      },
+    ),
+  );
+});