@coordination-network/credential 0.0.1 → 0.0.2

package/src/decode.ts

@@ -1,25 +0,0 @@
-import { decodeSdJwtSync, getClaimsSync } from "@sd-jwt/decode"
-import { sdJwtHasher } from "./crypto"
-import { validateClaims } from "./profile"
-import { ApprovalCredentialClaims } from "./types"
-
-/**
- * Decodes a compact SD-JWT and reconstructs the full claim set from its
- * disclosures WITHOUT verifying the signature — for callers that already
- * trust the token, such as the issuer reading back a token it just signed.
- * Untrusted tokens go through verifyCredential/verifyPresentation instead.
- */
-export function decodeSdJwtCredentialClaims(token: string): ApprovalCredentialClaims {
-    let reconstructed: unknown
-    try {
-        const decoded = decodeSdJwtSync(token, sdJwtHasher)
-        reconstructed = getClaimsSync(decoded.jwt.payload, decoded.disclosures, sdJwtHasher)
-    } catch {
-        throw new Error("token is not a decodable SD-JWT")
-    }
-    const checked = validateClaims(reconstructed)
-    if (!checked.ok) {
-        throw new Error(checked.message)
-    }
-    return checked.claims
-}

package/src/issue.ts

@@ -1,83 +0,0 @@
-import { SDJwtVcInstance, SdJwtVcPayload } from "@sd-jwt/sd-jwt-vc"
-import { DisclosureFrame } from "@sd-jwt/types"
-import { InvalidBindingInputError, verifyCredentialBinding } from "@coordination-network/identity"
-import { createSdJwtSigner, jwkToPublicKeyBytes, randomUuid, sdJwtHasher, sdJwtSaltGenerator } from "./crypto"
-import { IssuanceError } from "./errors"
-import { buildPayload, DISCLOSURE_FRAME } from "./profile"
-import { ApprovalResolver } from "./resolver"
-import { verifyCommitmentOwnership } from "./revocation"
-import { Signer } from "./signer"
-import { Hex32, SdJwtIssueParams } from "./types"
-
-/**
- * Issues the delegated user approval credential (spec 07, issuance flow).
- * Throws IssuanceError, without signing anything, if the issuer isn't
- * approved or any challenge signature fails.
- */
-export async function issueSdJwtCredential(
-    params: SdJwtIssueParams,
-    signer: Signer,
-    approval: ApprovalResolver
-): Promise<string> {
-    if (!(await approval.isApprovedNetworkMember(params.issuerNetworkId))) {
-        throw new IssuanceError(
-            "ISSUER_NOT_APPROVED",
-            `issuer ${params.issuerNetworkId} is not an approved network member`
-        )
-    }
-    if (!(params.validFrom < params.validUntil)) {
-        throw new IssuanceError("INVALID_PARAMS", "validFrom must be before validUntil")
-    }
-
-    let binding: ReturnType<typeof verifyCredentialBinding>
-    try {
-        binding = verifyCredentialBinding({
-            nonce: params.nonce,
-            accountPublicKey: params.accountPublicKey,
-            confirmationKey: jwkToPublicKeyBytes(params.confirmationKey),
-            accountSignature: params.accountPopSignature,
-            deviceSignature: params.devicePopSignature
-        })
-    } catch (error) {
-        if (error instanceof InvalidBindingInputError) {
-            throw new IssuanceError("INVALID_PARAMS", `malformed binding input: ${error.message}`)
-        }
-        throw error
-    }
-
-    if (binding.networkId !== params.subjectNetworkId.toLowerCase()) {
-        throw new IssuanceError("SUBJECT_MISMATCH", "subjectNetworkId does not match the account public key")
-    }
-    if (!binding.valid) {
-        throw new IssuanceError("BINDING_INVALID", "credential binding failed")
-    }
-
-    const ownershipOk = verifyCommitmentOwnership({
-        commitment: params.revocation.commitment,
-        publicKey: params.revocation.publicKey,
-        signature: params.revocation.ownershipSignature,
-        nonce: params.nonce
-    })
-    if (!ownershipOk) {
-        throw new IssuanceError("COMMITMENT_OWNERSHIP_INVALID", "revocation commitment ownership proof failed")
-    }
-
-    const payload = buildPayload(
-        { ...params, subjectNetworkId: binding.networkId as Hex32 },
-        `urn:uuid:${randomUuid()}`
-    )
-    const sdjwt = new SDJwtVcInstance({
-        signer: createSdJwtSigner(signer),
-        signAlg: "ES256",
-        hasher: sdJwtHasher,
-        hashAlg: "sha-256",
-        saltGenerator: sdJwtSaltGenerator
-    })
-    // Cast: the library types `status` as its own status-list reference, but
-    // our custom cn_zk_revocation member is deliberate (spec 07) and the
-    // status-list fetcher only triggers on status.status_list.
-    return sdjwt.issue(
-        { ...payload } as unknown as SdJwtVcPayload,
-        DISCLOSURE_FRAME as unknown as DisclosureFrame<SdJwtVcPayload>
-    )
-}

package/src/present.ts

@@ -1,101 +0,0 @@
-import { SDJwtVcInstance } from "@sd-jwt/sd-jwt-vc"
-import { JwtPayload, PresentationFrame } from "@sd-jwt/types"
-import { createSdJwtSigner, createSdJwtVerifier, sdJwtHasher, sdJwtSaltGenerator } from "./crypto"
-import { Resolver } from "./resolver"
-import { DeviceSigner } from "./signer"
-import { Jwk, VerifyResult } from "./types"
-import { runPipeline } from "./verify"
-
-export interface PresentOptions {
-    /** Verifier URN, pinned as the KB-JWT audience. */
-    audience: string
-    /** Verifier-issued nonce, echoed in the KB-JWT. */
-    nonce: string
-    /** Which approvalScope members to disclose. Both when omitted. */
-    disclose?: ("programme" | "country")[]
-}
-
-export interface VerifyPresentationOptions {
-    /** The verifier's own URN; the KB-JWT audience must match it. */
-    audience: string
-    /** The nonce this verifier handed out; must be fresh and match. */
-    nonce: string
-    /** Verification time, unix seconds. Defaults to now. */
-    currentDate?: number
-}
-
-/**
- * Builds a presentation from a stored credential: the JWS, the selected
- * disclosures, and a KB-JWT signed by the device key binding the verifier's
- * audience, the nonce and the sd_hash of the exact presented token (spec 07,
- * verification flow step 7).
- */
-export async function presentSdJwtCredential(
-    token: string,
-    deviceSigner: DeviceSigner,
-    options: PresentOptions
-): Promise<string> {
-    const disclose = options.disclose ?? ["programme", "country"]
-    const frame = { approvalScope: Object.fromEntries(disclose.map((member) => [member, true])) }
-    const sdjwt = new SDJwtVcInstance({
-        hasher: sdJwtHasher,
-        hashAlg: "sha-256",
-        saltGenerator: sdJwtSaltGenerator,
-        kbSigner: createSdJwtSigner(deviceSigner),
-        kbSignAlg: "ES256"
-    })
-    return sdjwt.present(token, frame as unknown as PresentationFrame<Record<string, unknown>>, {
-        kb: {
-            payload: {
-                aud: options.audience,
-                nonce: options.nonce,
-                iat: Math.floor(Date.now() / 1000)
-            }
-        }
-    })
-}
-
-/**
- * Verifies a presentation: the full verifyCredential pipeline, plus the
- * KB-JWT under the credential's cnf.jwk with nonce, sd_hash (both checked by
- * the library) and audience (checked here) pinned.
- */
-export async function verifySdJwtPresentation(
-    presentation: string,
-    resolver: Resolver,
-    options: VerifyPresentationOptions
-): Promise<VerifyResult> {
-    const now = options.currentDate ?? Math.floor(Date.now() / 1000)
-    let audience: string | undefined
-
-    const { result } = await runPipeline(presentation, resolver, now, async (issuerJwk: Jwk, clampedNow: number) => {
-        const sdjwt = new SDJwtVcInstance({
-            verifier: createSdJwtVerifier(issuerJwk),
-            hasher: sdJwtHasher,
-            hashAlg: "sha-256",
-            kbVerifier: (data: string, signature: string, payload: JwtPayload) => {
-                const cnfJwk = (payload as { cnf?: { jwk?: Jwk } }).cnf?.jwk
-                if (!cnfJwk) return false
-                try {
-                    return createSdJwtVerifier(cnfJwk)(data, signature)
-                } catch {
-                    return false
-                }
-            }
-        })
-        const { payload, kb } = await sdjwt.verify(presentation, {
-            currentDate: clampedNow,
-            keyBindingNonce: options.nonce
-        })
-        audience = kb?.payload.aud
-        return payload
-    })
-
-    if (!result.ok) {
-        return result
-    }
-    if (audience !== options.audience) {
-        return { ok: false, code: "PROOF_INVALID", message: "KB-JWT audience does not match this verifier" }
-    }
-    return result
-}

package/src/profile.ts

@@ -1,133 +0,0 @@
-import { ApprovalCredentialClaims, ApprovalScope, Hex32, Jwk, SdJwtIssueParams, StatusClaim } from "./types"
-import { buildStatusClaim } from "./revocation"
-
-/**
- * The claims profile of the delegated user approval credential (spec 07):
- * payload construction, the disclosure frame, and the shape validator that
- * backs the MALFORMED verdict.
- */
-
-export const APPROVAL_CREDENTIAL_VCT = "urn:cn:credential:approval:v1"
-
-/** Only the two approvalScope members are disclosable; everything else is plain. */
-export const DISCLOSURE_FRAME = {
-    approvalScope: { _sd: ["programme", "country"] }
-} as const
-
-const NETWORK_ID_RE = /^0x[0-9a-f]{64}$/
-const NETWORK_URN_RE = /^urn:cn:network:[0-9a-f]{64}$/
-const CONTRACT_URN_RE = /^urn:cn:contract:.+$/
-const UUID_URN_RE = /^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
-
-export function networkIdToUrn(id: Hex32): string {
-    const normalized = id.toLowerCase() as Hex32
-    if (!NETWORK_ID_RE.test(normalized)) {
-        throw new Error("networkId must be a 0x-prefixed 32-byte hex string")
-    }
-    return `urn:cn:network:${normalized.slice(2)}`
-}
-
-export function urnToNetworkId(urn: string): Hex32 | null {
-    return NETWORK_URN_RE.test(urn) ? (`0x${urn.slice("urn:cn:network:".length)}` as Hex32) : null
-}
-
-/** Assembles the full signed payload; the disclosure frame is applied at issue time. */
-export function buildPayload(params: SdJwtIssueParams, jti: string): ApprovalCredentialClaims {
-    return {
-        vct: APPROVAL_CREDENTIAL_VCT,
-        iss: networkIdToUrn(params.issuerNetworkId),
-        sub: networkIdToUrn(params.subjectNetworkId),
-        jti,
-        nbf: params.validFrom,
-        exp: params.validUntil,
-        cnf: { jwk: params.confirmationKey },
-        status: buildStatusClaim(params.revocation.commitment, params.revocationRegistry),
-        approvalScope: { ...params.approvalScope }
-    }
-}
-
-type ClaimsCheck = { ok: true; claims: ApprovalCredentialClaims } | { ok: false; message: string }
-
-const ALLOWED_TOP_LEVEL = new Set(["vct", "iss", "sub", "jti", "nbf", "exp", "cnf", "status", "approvalScope"])
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-    return typeof value === "object" && value !== null && !Array.isArray(value)
-}
-
-function isJwk(value: unknown): value is Jwk {
-    if (!isRecord(value)) return false
-    const keys = Object.keys(value)
-    return (
-        keys.length === 4 &&
-        value.kty === "EC" &&
-        value.crv === "P-256" &&
-        typeof value.x === "string" &&
-        typeof value.y === "string"
-    )
-}
-
-function isStatusClaim(value: unknown): value is StatusClaim {
-    if (!isRecord(value) || Object.keys(value).length !== 1) return false
-    const entry = value.cn_zk_revocation
-    if (!isRecord(entry) || Object.keys(entry).length !== 2) return false
-    return (
-        typeof entry.revocationRegistry === "string" &&
-        CONTRACT_URN_RE.test(entry.revocationRegistry) &&
-        typeof entry.revocationCommitment === "string" &&
-        /^[0-9]+$/.test(entry.revocationCommitment)
-    )
-}
-
-function isApprovalScope(value: unknown): value is ApprovalScope {
-    if (!isRecord(value)) return false
-    const keys = Object.keys(value)
-    return (
-        keys.length === 2 &&
-        typeof value.programme === "string" &&
-        value.programme.length > 0 &&
-        typeof value.country === "string" &&
-        /^[A-Z]{3}$/.test(value.country)
-    )
-}
-
-/**
- * Validates the reconstructed payload of a verified token against the
- * profile. Strict on both sides: a missing required claim and an unknown
- * plain claim both fail (spec 07; a tampered disclosure surfaces here as a
- * missing approvalScope member).
- */
-export function validateClaims(payload: unknown): ClaimsCheck {
-    if (!isRecord(payload)) {
-        return { ok: false, message: "payload is not an object" }
-    }
-    for (const key of Object.keys(payload)) {
-        if (!ALLOWED_TOP_LEVEL.has(key)) {
-            return { ok: false, message: `unknown claim: ${key}` }
-        }
-    }
-    if (payload.vct !== APPROVAL_CREDENTIAL_VCT) {
-        return { ok: false, message: "vct missing or not the approval credential type" }
-    }
-    if (typeof payload.iss !== "string" || urnToNetworkId(payload.iss) === null) {
-        return { ok: false, message: "iss missing or not a urn:cn:network URN" }
-    }
-    if (typeof payload.sub !== "string" || urnToNetworkId(payload.sub) === null) {
-        return { ok: false, message: "sub missing or not a urn:cn:network URN" }
-    }
-    if (typeof payload.jti !== "string" || !UUID_URN_RE.test(payload.jti)) {
-        return { ok: false, message: "jti missing or not a urn:uuid URN" }
-    }
-    if (typeof payload.nbf !== "number" || typeof payload.exp !== "number") {
-        return { ok: false, message: "nbf/exp missing or not NumericDate values" }
-    }
-    if (!isRecord(payload.cnf) || Object.keys(payload.cnf).length !== 1 || !isJwk(payload.cnf.jwk)) {
-        return { ok: false, message: "cnf.jwk missing or not a P-256 JWK" }
-    }
-    if (!isStatusClaim(payload.status)) {
-        return { ok: false, message: "status.cn_zk_revocation missing or malformed" }
-    }
-    if (!isApprovalScope(payload.approvalScope)) {
-        return { ok: false, message: "approvalScope missing programme/country" }
-    }
-    return { ok: true, claims: payload as unknown as ApprovalCredentialClaims }
-}

package/src/verify.ts

@@ -1,118 +0,0 @@
-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 }