@coordination-network/credential 0.0.1

package/src/revocation.ts

@@ -0,0 +1,81 @@
+import { Identity } from "@semaphore-protocol/identity"
+import { bytesToHex, randomBytes } from "@noble/hashes/utils"
+import { EddsaPublicKey, EddsaSignature, StatusClaim } from "./types"
+
+/**
+ * Device-side revocation material (spec 08). r is 32 random bytes, generated
+ * on the device, never leaving it. Everything below takes r as Uint8Array,
+ * never as a hex string: the two encodings derive different commitments
+ * (Semaphore hashes the raw input), and the regression test holds that line.
+ */
+
+function assertSecret(r: Uint8Array): void {
+    if (r.length !== 32) {
+        throw new Error("revocation secret must be 32 bytes")
+    }
+}
+
+function nonceToBigint(nonce: Uint8Array): bigint {
+    if (nonce.length === 0) {
+        throw new Error("nonce must not be empty")
+    }
+    return BigInt(`0x${bytesToHex(nonce)}`)
+}
+
+/** Generates a fresh 32-byte revocation secret r. Device-side only. */
+export function generateRevocationSecret(): Uint8Array {
+    return randomBytes(32)
+}
+
+/** commitment = new Identity(r).commitment (Semaphore V4). */
+export function deriveRevocationCommitment(r: Uint8Array): bigint {
+    assertSecret(r)
+    return new Identity(r).commitment
+}
+
+/**
+ * Signs the issuer's challenge nonce with the Baby Jubjub EdDSA key behind
+ * r, proving the device owns the commitment it asks the issuer to embed.
+ */
+export function signCommitmentOwnership(
+    r: Uint8Array,
+    nonce: Uint8Array
+): { publicKey: EddsaPublicKey; signature: EddsaSignature } {
+    assertSecret(r)
+    const identity = new Identity(r)
+    const signature = identity.signMessage(nonceToBigint(nonce))
+    return {
+        publicKey: [identity.publicKey[0], identity.publicKey[1]],
+        signature: { R8: [signature.R8[0], signature.R8[1]], S: signature.S }
+    }
+}
+
+/**
+ * Issuer-side check: verifies the EdDSA signature over the nonce, recomputes
+ * the commitment from the public key, and compares it to the claimed one.
+ */
+export function verifyCommitmentOwnership(params: {
+    commitment: bigint
+    publicKey: EddsaPublicKey
+    signature: EddsaSignature
+    nonce: Uint8Array
+}): boolean {
+    try {
+        if (!Identity.verifySignature(nonceToBigint(params.nonce), params.signature, params.publicKey)) {
+            return false
+        }
+        return Identity.generateCommitment(params.publicKey) === params.commitment
+    } catch {
+        return false
+    }
+}
+
+/** Builds the status.cn_zk_revocation claim for the signed body (spec 07). */
+export function buildStatusClaim(commitment: bigint, revocationRegistry: string): StatusClaim {
+    return {
+        cn_zk_revocation: {
+            revocationRegistry,
+            revocationCommitment: commitment.toString(10)
+        }
+    }
+}

package/src/signer.ts

@@ -0,0 +1,21 @@
+import { Jwk } from "./types"
+
+/**
+ * Issuer signing key, KMS-shaped. sign receives the JWS signing input in
+ * message mode (the service applies SHA-256 itself, never a precomputed
+ * digest) and returns the raw 64-byte r||s signature.
+ */
+export interface Signer {
+    getPublicKeyJwk(): Promise<Jwk>
+    sign(message: Uint8Array): Promise<Uint8Array>
+}
+
+/**
+ * Holder P-256 device key: the secure element in the app, a software key in
+ * tests. Same contract as Signer; a separate type because the two keys must
+ * never be interchangeable in signatures.
+ */
+export interface DeviceSigner extends Signer {
+    /** Signs an already-computed 32-byte digest, without hashing it again. */
+    signDigest(digest: Uint8Array): Promise<Uint8Array>
+}

package/src/types.ts

@@ -0,0 +1,116 @@
+/** Credential and issuance types. */
+
+/** A 32-byte value as a 0x-prefixed hex string (e.g. a networkId). */
+export type Hex32 = `0x${string}`
+
+/** An EC public key in JWK form (RFC 7517). This profile uses P-256 only. */
+export interface Jwk {
+    kty: "EC"
+    crv: "P-256"
+    x: string
+    y: string
+}
+
+export interface ApprovalScope {
+    /** Programme the approval covers. */
+    programme: string
+    /** ISO 3166-1 alpha-3 country code. */
+    country: string
+}
+
+/** Baby Jubjub EdDSA public key, shaped as Semaphore V4 exposes it. */
+export type EddsaPublicKey = [bigint, bigint]
+
+/** Baby Jubjub EdDSA signature, shaped as Semaphore V4 exposes it. */
+export interface EddsaSignature {
+    R8: [bigint, bigint]
+    S: bigint
+}
+
+/**
+ * The custom status member inside the signed body (spec 07). The commitment
+ * is issuer-attested and visible to WS1 verifiers by design.
+ */
+export interface StatusClaim {
+    cn_zk_revocation: {
+        /** urn:cn:contract: URN of the on-chain revocation registry. */
+        revocationRegistry: string
+        revocationCommitment: string
+    }
+}
+
+/** The reconstructed claim set of a verified credential. */
+export interface ApprovalCredentialClaims {
+    vct: string
+    iss: string
+    sub: string
+    jti: string
+    nbf: number
+    exp: number
+    cnf: { jwk: Jwk }
+    status: StatusClaim
+    approvalScope: ApprovalScope
+}
+
+export interface IssuanceRequest {
+    issuerNetworkId: Hex32
+    subjectNetworkId: Hex32
+    approvalScope: ApprovalScope
+    validFrom: number
+    validUntil: number
+    confirmationKey: Jwk
+    accountPublicKey: Uint8Array
+    nonce: Uint8Array
+    devicePopSignature: Uint8Array
+    accountPopSignature: Uint8Array
+    revocation: {
+        commitment: bigint
+        publicKey: EddsaPublicKey
+        ownershipSignature: EddsaSignature
+    }
+}
+
+export interface SdJwtIssueParams extends IssuanceRequest {
+    revocationRegistry: string
+}
+
+export interface ZkCredentialIssueParams extends IssuanceRequest {
+    identityPublicKey: EddsaPublicKey
+}
+
+export interface ZkCredentialBody {
+    programmeHash: bigint
+    countryCode: number
+    notBefore: number
+    expiresAt: number
+    deviceKeyCommitment: bigint
+    holderKeyCommitment: bigint
+    revocationCommitment: bigint
+}
+
+export interface ZkCredential {
+    body: ZkCredentialBody
+    issuerPublicKey: EddsaPublicKey
+    signature: EddsaSignature
+}
+
+export interface SerializedZkCredential {
+    body: {
+        programmeHash: string
+        countryCode: number
+        notBefore: number
+        expiresAt: number
+        deviceKeyCommitment: string
+        holderKeyCommitment: string
+        revocationCommitment: string
+    }
+    issuerPublicKey: [string, string]
+    signature: { R8: [string, string]; S: string }
+}
+
+export type VerifyErrorCode =
+    "MALFORMED" | "ISSUER_NOT_APPROVED" | "KEY_NOT_FOUND" | "PROOF_INVALID" | "EXPIRED" | "NOT_YET_VALID" | "REVOKED"
+
+/** Checks run in spec order (07, verification flow) and the first failure wins. */
+export type VerifyResult =
+    { ok: true; claims: ApprovalCredentialClaims } | { ok: false; code: VerifyErrorCode; message: string }

package/src/verify.ts

@@ -0,0 +1,118 @@
+import { SDJwtVcInstance } from "@sd-jwt/sd-jwt-vc"
+import { base64urlToBytes, createSdJwtVerifier, sdJwtHasher } from "./crypto"
+import { urnToNetworkId, validateClaims } from "./profile"
+import { Resolver } from "./resolver"
+import { ApprovalCredentialClaims, Hex32, Jwk, VerifyErrorCode, VerifyResult } from "./types"
+
+export interface VerifyOptions {
+    /** Verification time, unix seconds. Defaults to now. */
+    currentDate?: number
+}
+
+const fail = (code: VerifyErrorCode, message: string): VerifyResult => ({ ok: false, code, message })
+
+/**
+ * The shared verification pipeline (spec 07, verification flow), check order
+ * first-failure-wins: decode/structure -> issuer approved -> key fetch ->
+ * signature and disclosure digests -> claims shape -> validity window ->
+ * revocation. A disclosure whose digest matches nothing is silently dropped
+ * by the library (phase 1 spike), so it surfaces in the claims-shape step as
+ * a missing approvalScope member and fails MALFORMED.
+ *
+ * The library's own nbf/exp check runs against a clamped timestamp so the
+ * window verdict (EXPIRED vs NOT_YET_VALID) always comes from our check,
+ * after the signature has been verified.
+ */
+async function runPipeline(
+    token: string,
+    resolver: Resolver,
+    now: number,
+    verifyWithLibrary: (issuerJwk: Jwk, clampedNow: number) => Promise<Record<string, unknown>>
+): Promise<{ result: VerifyResult; issuerId?: Hex32 }> {
+    let payload: Record<string, unknown>
+    try {
+        const jwt = token.split("~")[0]
+        const segments = jwt.split(".")
+        if (segments.length !== 3) {
+            return { result: fail("MALFORMED", "not a compact SD-JWT") }
+        }
+        payload = JSON.parse(new TextDecoder().decode(base64urlToBytes(segments[1])))
+        if (typeof payload !== "object" || payload === null) {
+            return { result: fail("MALFORMED", "JWS payload is not an object") }
+        }
+    } catch {
+        return { result: fail("MALFORMED", "token could not be decoded") }
+    }
+
+    const issuerId = typeof payload.iss === "string" ? urnToNetworkId(payload.iss) : null
+    if (issuerId === null) {
+        return { result: fail("MALFORMED", "iss missing or not a urn:cn:network URN") }
+    }
+    if (!(await resolver.isApprovedNetworkMember(issuerId))) {
+        return {
+            result: fail("ISSUER_NOT_APPROVED", `issuer ${payload.iss} is not an approved network member`),
+            issuerId
+        }
+    }
+    const issuerJwk = await resolver.getCredentialPublicKey(issuerId)
+    if (issuerJwk === null) {
+        return { result: fail("KEY_NOT_FOUND", `no credential public key published for ${payload.iss}`), issuerId }
+    }
+
+    // Clamp the library's clock inside the token's window; our own check below decides the verdict.
+    let clampedNow = now
+    if (typeof payload.exp === "number" && clampedNow > payload.exp) clampedNow = payload.exp
+    if (typeof payload.nbf === "number" && clampedNow < payload.nbf) clampedNow = payload.nbf
+
+    let reconstructed: Record<string, unknown>
+    try {
+        reconstructed = await verifyWithLibrary(issuerJwk, clampedNow)
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        if (message.includes("not yet valid")) return { result: fail("NOT_YET_VALID", message), issuerId }
+        if (message.includes("expired")) return { result: fail("EXPIRED", message), issuerId }
+        return { result: fail("PROOF_INVALID", message), issuerId }
+    }
+
+    const checked = validateClaims(reconstructed)
+    if (!checked.ok) {
+        return { result: fail("MALFORMED", checked.message), issuerId }
+    }
+    const claims: ApprovalCredentialClaims = checked.claims
+
+    if (now < claims.nbf) {
+        return { result: fail("NOT_YET_VALID", "credential is not yet within its validity window"), issuerId }
+    }
+    if (now > claims.exp) {
+        return { result: fail("EXPIRED", "credential validity window has passed"), issuerId }
+    }
+    if (await resolver.isRevoked(BigInt(claims.status.cn_zk_revocation.revocationCommitment))) {
+        return { result: fail("REVOKED", "credential commitment is in the revocation registry"), issuerId }
+    }
+    return { result: { ok: true, claims }, issuerId }
+}
+
+/**
+ * Verifies a compact SD-JWT credential with all its disclosures — the
+ * holder's verify-on-receipt and any check that does not involve a live
+ * presentation. Key binding is not checked here; that is verifyPresentation.
+ */
+export async function verifySdJwtCredential(
+    token: string,
+    resolver: Resolver,
+    options?: VerifyOptions
+): Promise<VerifyResult> {
+    const now = options?.currentDate ?? Math.floor(Date.now() / 1000)
+    const { result } = await runPipeline(token, resolver, now, async (issuerJwk, clampedNow) => {
+        const sdjwt = new SDJwtVcInstance({
+            verifier: createSdJwtVerifier(issuerJwk),
+            hasher: sdJwtHasher,
+            hashAlg: "sha-256"
+        })
+        const { payload } = await sdjwt.verify(token, { currentDate: clampedNow })
+        return payload
+    })
+    return result
+}
+
+export { runPipeline }

package/src/witness.ts

@@ -0,0 +1,69 @@
+import type { CompiledCircuit } from "@noir-lang/noir_js"
+import { ZkPresentationInputs } from "./presentation-inputs"
+
+type CircuitAbi = CompiledCircuit["abi"]
+type AbiType = CircuitAbi["parameters"][number]["type"]
+
+const DECIMAL_RE = /^(0|[1-9][0-9]*)$/
+
+function scalarWitness(value: unknown, path: string): string {
+    if (typeof value !== "string" || !DECIMAL_RE.test(value)) {
+        throw new Error(`zkPresentationInputsToWitness: ${path} must be a canonical decimal string`)
+    }
+    return value
+}
+
+function booleanWitness(value: unknown, path: string): string {
+    if (typeof value !== "boolean") {
+        throw new Error(`zkPresentationInputsToWitness: ${path} must be a boolean`)
+    }
+    return value ? "1" : "0"
+}
+
+/** Depth-first ABI walk (spec: field/integer -> decimal string, boolean -> "1"/"0", array/struct recurse). */
+function emit(type: AbiType, value: unknown, path: string, witness: string[]): void {
+    switch (type.kind) {
+        case "field":
+        case "integer":
+            witness.push(scalarWitness(value, path))
+            return
+        case "boolean":
+            witness.push(booleanWitness(value, path))
+            return
+        case "array":
+            if (!Array.isArray(value) || value.length !== type.length) {
+                throw new Error(`zkPresentationInputsToWitness: ${path} must be an array of length ${type.length}`)
+            }
+            value.forEach((element, index) => emit(type.type, element, `${path}[${index}]`, witness))
+            return
+        case "struct": {
+            if (typeof value !== "object" || value === null || Array.isArray(value)) {
+                throw new Error(`zkPresentationInputsToWitness: ${path} must be an object`)
+            }
+            const fields = value as Record<string, unknown>
+            type.fields.forEach((field) => emit(field.type, fields[field.name], `${path}.${field.name}`, witness))
+            return
+        }
+        default:
+            throw new Error(`zkPresentationInputsToWitness: ${path} has unsupported ABI type "${type.kind}"`)
+    }
+}
+
+/**
+ * Flattens {@link ZkPresentationInputs} into the ordered `string[]` witness a
+ * native Noir prover consumes, walking the compiled circuit's ABI (public and
+ * private parameters, in declaration order) rather than the JS object's own
+ * key order — a struct field reorder in the circuit changes the ABI and so
+ * changes this output, instead of silently desyncing from it.
+ */
+export function zkPresentationInputsToWitness(abi: CircuitAbi, inputs: ZkPresentationInputs): string[] {
+    const record: Record<string, unknown> = { ...inputs }
+    const witness: string[] = []
+    for (const parameter of abi.parameters) {
+        if (!(parameter.name in record)) {
+            throw new Error(`zkPresentationInputsToWitness: unknown ABI parameter "${parameter.name}"`)
+        }
+        emit(parameter.type, record[parameter.name], parameter.name, witness)
+    }
+    return witness
+}

package/src/zk-proof.ts

@@ -0,0 +1,198 @@
+import type { BackendOptions, ProofData, UltraHonkBackendOptions } from "@aztec/bb.js"
+import type { CompiledCircuit } from "@noir-lang/noir_js"
+import type { InputMap } from "@noir-lang/noir_js"
+import { countryCode, programmeHash, stringToField } from "./credential-message"
+import { challengeToField, ZkPresentationInputs } from "./presentation-inputs"
+
+const PUBLIC_INPUT_NAMES = [
+    "current_time",
+    "challenge",
+    "audience",
+    "required_programme_hash",
+    "required_country_code"
+] as const
+
+type PublicInputName = (typeof PUBLIC_INPUT_NAMES)[number]
+
+export type ZkCredentialCircuit = CompiledCircuit
+export type ZkPresentationProof = ProofData
+
+export interface ExpectedZkPresentation {
+    currentTime: number
+    challenge: Uint8Array
+    audience: string
+    programme: string
+    country: string
+}
+
+export type ZkPresentationVerifyResult =
+    | { ok: true; approvedIssuerRoot: bigint; revocationRoot: bigint }
+    | { ok: false; code: "PUBLIC_INPUT_MISMATCH"; publicInput?: PublicInputName }
+    | { ok: false; code: "PROOF_INVALID" }
+
+export interface ZkProofSystemOptions {
+    backend?: BackendOptions
+    proof?: UltraHonkBackendOptions
+}
+
+interface NoirExecutor {
+    execute(inputs: InputMap): Promise<{ witness: Uint8Array; returnValue: unknown }>
+}
+
+interface ProofBackend {
+    generateProof(witness: Uint8Array, options?: UltraHonkBackendOptions): Promise<ProofData>
+    verifyProof(proof: ProofData, options?: UltraHonkBackendOptions): Promise<boolean>
+}
+
+interface DisposableBackend {
+    destroy(): Promise<void>
+}
+
+const publicParameterNames = (circuit: CompiledCircuit): string[] =>
+    circuit.abi.parameters.filter((parameter) => parameter.visibility === "public").map((parameter) => parameter.name)
+
+export const assertZkCredentialCircuitAbi = (circuit: CompiledCircuit): void => {
+    const actual = publicParameterNames(circuit)
+    if (
+        actual.length !== PUBLIC_INPUT_NAMES.length ||
+        actual.some((name, index) => name !== PUBLIC_INPUT_NAMES[index])
+    ) {
+        throw new Error(`unexpected credential circuit public inputs: ${actual.join(", ")}`)
+    }
+
+    const returnType = circuit.abi.return_type
+    if (
+        returnType === null ||
+        returnType.visibility !== "public" ||
+        returnType.abi_type.kind !== "tuple" ||
+        returnType.abi_type.fields.length !== 2 ||
+        returnType.abi_type.fields.some((field) => field.kind !== "field")
+    ) {
+        throw new Error("credential circuit must return the proven issuer and revocation roots as public Fields")
+    }
+}
+
+const expectedPublicInputs = (expected: ExpectedZkPresentation): bigint[] => {
+    if (!Number.isSafeInteger(expected.currentTime) || expected.currentTime < 0) {
+        throw new Error("currentTime must be a non-negative safe integer")
+    }
+
+    return [
+        BigInt(expected.currentTime),
+        challengeToField(expected.challenge),
+        stringToField(expected.audience),
+        programmeHash(expected.programme),
+        BigInt(countryCode(expected.country))
+    ]
+}
+
+const proofPublicValues = (proof: ZkPresentationProof): bigint[] | null => {
+    if (proof.publicInputs.length !== PUBLIC_INPUT_NAMES.length + 2) return null
+    try {
+        return proof.publicInputs.map(BigInt)
+    } catch {
+        return null
+    }
+}
+
+const publicInputMismatch = (
+    proof: ZkPresentationProof,
+    expected: ExpectedZkPresentation
+): PublicInputName | undefined | null => {
+    const values = proofPublicValues(proof)
+    if (values === null) return null
+    const actual = values.slice(0, PUBLIC_INPUT_NAMES.length)
+    const wanted = expectedPublicInputs(expected)
+    const mismatch = actual.findIndex((value, index) => value !== wanted[index])
+    return mismatch < 0 ? undefined : PUBLIC_INPUT_NAMES[mismatch]
+}
+
+export class ZkCredentialProofSystem {
+    private constructor(
+        private readonly noir: NoirExecutor,
+        private readonly backend: ProofBackend,
+        private readonly api: DisposableBackend,
+        private readonly proofOptions?: UltraHonkBackendOptions
+    ) {}
+
+    static async create(
+        circuit: CompiledCircuit,
+        options: ZkProofSystemOptions = {}
+    ): Promise<ZkCredentialProofSystem> {
+        assertZkCredentialCircuitAbi(circuit)
+        const [{ Noir }, { Barretenberg, UltraHonkBackend }] = await Promise.all([
+            import("@noir-lang/noir_js"),
+            import("@aztec/bb.js")
+        ])
+        const api = await Barretenberg.new(options.backend)
+        return new ZkCredentialProofSystem(
+            new Noir(circuit),
+            new UltraHonkBackend(circuit.bytecode, api),
+            api,
+            options.proof
+        )
+    }
+
+    async generateProof(inputs: ZkPresentationInputs): Promise<ZkPresentationProof> {
+        const { witness } = await this.noir.execute(inputs as unknown as InputMap)
+        const proof = await this.backend.generateProof(witness, this.proofOptions)
+        return { proof: proof.proof, publicInputs: [...proof.publicInputs] }
+    }
+
+    async verifyProof(
+        proof: ZkPresentationProof,
+        expected: ExpectedZkPresentation
+    ): Promise<ZkPresentationVerifyResult> {
+        const mismatch = publicInputMismatch(proof, expected)
+        if (mismatch === null) return { ok: false, code: "PUBLIC_INPUT_MISMATCH" }
+        if (mismatch !== undefined) return { ok: false, code: "PUBLIC_INPUT_MISMATCH", publicInput: mismatch }
+        if (!(proof.proof instanceof Uint8Array) || proof.proof.length === 0 || proof.proof.length % 32 !== 0) {
+            return { ok: false, code: "PROOF_INVALID" }
+        }
+
+        try {
+            if (!(await this.backend.verifyProof(proof, this.proofOptions))) {
+                return { ok: false, code: "PROOF_INVALID" }
+            }
+            const publicValues = proofPublicValues(proof)!
+            return {
+                ok: true,
+                approvedIssuerRoot: publicValues[PUBLIC_INPUT_NAMES.length],
+                revocationRoot: publicValues[PUBLIC_INPUT_NAMES.length + 1]
+            }
+        } catch {
+            return { ok: false, code: "PROOF_INVALID" }
+        }
+    }
+
+    async destroy(): Promise<void> {
+        await this.api.destroy()
+    }
+}
+
+export async function generateZkPresentationProof(
+    circuit: CompiledCircuit,
+    inputs: ZkPresentationInputs,
+    options: ZkProofSystemOptions = {}
+): Promise<ZkPresentationProof> {
+    const proofSystem = await ZkCredentialProofSystem.create(circuit, options)
+    try {
+        return await proofSystem.generateProof(inputs)
+    } finally {
+        await proofSystem.destroy()
+    }
+}
+
+export async function verifyZkPresentationProof(
+    circuit: CompiledCircuit,
+    proof: ZkPresentationProof,
+    expected: ExpectedZkPresentation,
+    options: ZkProofSystemOptions = {}
+): Promise<ZkPresentationVerifyResult> {
+    const proofSystem = await ZkCredentialProofSystem.create(circuit, options)
+    try {
+        return await proofSystem.verifyProof(proof, expected)
+    } finally {
+        await proofSystem.destroy()
+    }
+}