@zanii/vc 0.1.0

package/LICENSE

@@ -0,0 +1,159 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed
+      to in writing, Licensor provides the Work (and each Contributor
+      provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES
+      OR CONDITIONS OF ANY KIND, either express or implied, including,
+      without limitation, any warranties or conditions of TITLE,
+      NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Zanii
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,54 @@
+# @zanii/vc
+
+The **W3C Verifiable Credentials 2.0 bridge** — and it is not cosmetic. Zanii already
+signs with did:key + Ed25519 over JCS, which is *exactly* the W3C Data Integrity
+cryptosuite **`eddsa-jcs-2022`**. So `toVC` emits spec-conformant VCs with genuine
+`DataIntegrityProof`s that a standards wallet can verify with no Zanii code at all —
+and `verifyVC` verifies any did:key `eddsa-jcs-2022` VC from anyone.
+
+```sh
+npm install @zanii/vc @zanii/core @zanii/credentials @zanii/cv
+```
+
+```ts
+import { toVC, cvToVC, signVC, verifyVC } from '@zanii/vc';
+
+// a university exports a Zanii diploma credential as a W3C VC (same issuer key):
+const vc = toVC(zaniiCredential, issuerPrivateKey, { created: now });
+// → { "@context": ["https://www.w3.org/ns/credentials/v2"],
+//     type: ["VerifiableCredential", "ZaniiCredential"],
+//     issuer: "did:key:z6Mk…", validFrom, validUntil,
+//     credentialSubject: { id: holderDid, scope, claim, issuerDomain },
+//     proof: { type: "DataIntegrityProof", cryptosuite: "eddsa-jcs-2022", proofValue: "z…" } }
+
+// an agent exports its CV as a self-issued VC:
+const cvVc = cvToVC(signedCv, agentPrivateKey, { created: now });
+
+// verify anyone's did:key eddsa-jcs-2022 VC:
+const r = verifyVC(vc, { at: now });   // window checked only when `at` is passed
+r.ok; r.issuer;
+
+// or sign your own custom VC types with the generic engine:
+signVC({ '@context': [...], type: ['VerifiableCredential'], issuer, credentialSubject }, keypair, { created });
+```
+
+Python: `from zanii.vc import to_vc, cv_to_vc, verify_vc, ...` — **byte-identical**:
+the same credential + key + timestamp produces the exact same VC (proofValue included)
+in both languages, locked by parity vectors.
+
+## Guardrails
+
+- `toVC`/`cvToVC` **verify the Zanii artifact first** — a forged credential or altered
+  CV is refused, so the bridge can never launder a broken artifact into a
+  valid-looking VC.
+- `verifyVC` is deterministic: the validity window is checked only against an explicit
+  `at`, never a hidden "now".
+
+## The limit, stated up front
+
+This bridges the **format, not the trust model.** A VC produced here proves what the
+Zanii artifact proved — no more. Revocation with its explicit freshness window, the
+domain-bound issuer root-of-trust, and ledger-backed history remain Zanii-side checks
+(`@zanii/credentials`, `@zanii/kya`); W3C StatusList is deliberately not implemented —
+mapping it would claim a liveness this bridge cannot provide. And `verifyVC` checks
+the proof, not the issuer's institutional identity — say what it does, never more.

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import type { Credential } from '@zanii/credentials';
+import { type AgentCV } from '@zanii/cv';
+export declare const VC_CONTEXT = "https://www.w3.org/ns/credentials/v2";
+export declare const CRYPTOSUITE = "eddsa-jcs-2022";
+export interface DataIntegrityProof {
+    type: 'DataIntegrityProof';
+    cryptosuite: typeof CRYPTOSUITE;
+    created: string;
+    /** `did:key:z6Mk…#z6Mk…` — the did:key with its multikey fragment. */
+    verificationMethod: string;
+    proofPurpose: 'assertionMethod';
+    /** Multibase base58btc (`z…`) of the Ed25519 signature. */
+    proofValue: string;
+}
+export interface VerifiableCredential {
+    '@context': string[];
+    type: string[];
+    issuer: string;
+    validFrom?: string;
+    validUntil?: string;
+    credentialSubject: Record<string, unknown>;
+    proof?: DataIntegrityProof;
+    [k: string]: unknown;
+}
+/** The verification method a did:key controls: the DID plus its own multikey fragment. */
+export declare function verificationMethodOf(did: string): string;
+/**
+ * Sign any VC-shaped document with a did:key per `eddsa-jcs-2022`. The generic proof
+ * engine — the mappers below use it, and you can too for custom VC types.
+ */
+export declare function signVC(unsecured: Omit<VerifiableCredential, 'proof'>, signer: {
+    did: string;
+    privateKey: Uint8Array;
+}, opts: {
+    created: string;
+}): VerifiableCredential;
+export interface VCCheck {
+    ok: boolean;
+    reasons: string[];
+    /** The issuer DID whose key produced the proof (when it verified). */
+    issuer: string | null;
+}
+/**
+ * Verify a did:key `eddsa-jcs-2022` VC — any issuer, not just Zanii's. Checks the
+ * DataIntegrityProof and that the verification method belongs to the stated issuer.
+ * Pass `at` to also check the `validFrom`/`validUntil` window (deliberately not
+ * defaulted to "now" — verification stays deterministic).
+ */
+export declare function verifyVC(vc: VerifiableCredential | undefined, opts?: {
+    at?: string;
+}): VCCheck;
+/**
+ * Export a `@zanii/credentials` credential as a W3C VC, re-issued by the SAME issuer
+ * key. The Zanii signature is verified first — an invalid credential is refused, so
+ * the bridge can never launder a forged artifact into a valid-looking VC. (Revocation
+ * and issuer-domain resolution are deliberately NOT checked here — acceptance-time
+ * checks belong to the verifier via `@zanii/credentials`; the bridge only re-encodes.)
+ */
+export declare function toVC(credential: Credential, issuerPrivateKey: Uint8Array, opts: {
+    created: string;
+}): VerifiableCredential;
+/** Export an AgentCV as a self-issued VC — the agent attests its own assembled view. */
+export declare function cvToVC(cv: AgentCV, agentPrivateKey: Uint8Array, opts: {
+    created: string;
+}): VerifiableCredential;
+/** Decode helper for tests/interop: raw signature bytes from a multibase proofValue. */
+export declare function proofSignatureBytes(proofValue: string): Uint8Array;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,eAAO,MAAM,UAAU,yCAAyC,CAAC;AACjE,eAAO,MAAM,WAAW,mBAAmB,CAAC;AAE5C,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,WAAW,EAAE,OAAO,WAAW,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,iBAAiB,CAAC;IAChC,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAExD;AAgBD;;;GAGG;AACH,wBAAgB,MAAM,CACpB,SAAS,EAAE,IAAI,CAAC,oBAAoB,EAAE,OAAO,CAAC,EAC9C,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,EAC/C,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GACxB,oBAAoB,CAuBtB;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sEAAsE;IACtE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,oBAAoB,GAAG,SAAS,EAAE,IAAI,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CA+ClG;AAeD;;;;;;GAMG;AACH,wBAAgB,IAAI,CAClB,UAAU,EAAE,UAAU,EACtB,gBAAgB,EAAE,UAAU,EAC5B,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GACxB,oBAAoB,CAwBtB;AAED,wFAAwF;AACxF,wBAAgB,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,oBAAoB,CAuBhH;AAED,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAGlE"}

package/dist/index.js

@@ -0,0 +1,217 @@
+/**
+ * @zanii/vc — the W3C Verifiable Credentials 2.0 bridge.
+ *
+ * Governments, universities, and wallets increasingly speak the W3C VC data model.
+ * Zanii doesn't need a new trust stack to meet them: Zanii already signs with
+ * **did:key + Ed25519 over JCS**, which is *exactly* the W3C Data Integrity
+ * cryptosuite **`eddsa-jcs-2022`**. So this bridge is not cosmetic — `toVC` emits
+ * spec-conformant VCs with genuine `DataIntegrityProof`s a standards wallet can
+ * verify, and `verifyVC` verifies any did:key `eddsa-jcs-2022` VC from anyone.
+ *
+ * Two mappers over one proof engine:
+ * - `toVC(credential, issuerKey)` — a `@zanii/credentials` credential (diploma,
+ *   licence), re-issued as a VC **by the same issuer key** (the Zanii signature is
+ *   verified first; an invalid credential is refused).
+ * - `cvToVC(cv, agentKey)` — an AgentCV as a self-issued VC (the agent attests its
+ *   own assembled view, exactly like `signCV`).
+ *
+ * ## The limit, stated up front
+ *
+ * This bridges the **format, not the trust model.** A VC produced here proves what
+ * the Zanii artifact proved — no more. Revocation with an explicit freshness window,
+ * the domain-bound issuer root-of-trust, and ledger-backed history remain Zanii-side
+ * checks (`@zanii/credentials` `verifyCredential`, `resolveIssuer`); W3C-native
+ * status mechanisms (StatusList) are deliberately not implemented — mapping them
+ * would claim a liveness this bridge cannot provide. And `verifyVC` checks the
+ * proof and (optionally) the validity window — it does NOT resolve issuers or check
+ * revocation; say what it does, never more.
+ */
+import { ed25519 } from '@noble/curves/ed25519';
+import { sha256 } from '@noble/hashes/sha256';
+import { hexToBytes } from '@noble/hashes/utils';
+import { base58 } from '@scure/base';
+import { canonicalBytes, publicKeyFromDid } from '@zanii/core';
+import { verifyCV } from '@zanii/cv';
+export const VC_CONTEXT = 'https://www.w3.org/ns/credentials/v2';
+export const CRYPTOSUITE = 'eddsa-jcs-2022';
+/** The verification method a did:key controls: the DID plus its own multikey fragment. */
+export function verificationMethodOf(did) {
+    return `${did}#${did.slice('did:key:'.length)}`;
+}
+/**
+ * `eddsa-jcs-2022` hash step: sha256(JCS(proof options)) || sha256(JCS(document
+ * without proof)) — 64 bytes, which the Ed25519 key signs.
+ */
+function hashData(doc, proofOptions) {
+    const { proof: _omit, ...unsecured } = doc;
+    const configHash = sha256(canonicalBytes(proofOptions));
+    const docHash = sha256(canonicalBytes(unsecured));
+    const out = new Uint8Array(64);
+    out.set(configHash, 0);
+    out.set(docHash, 32);
+    return out;
+}
+/**
+ * Sign any VC-shaped document with a did:key per `eddsa-jcs-2022`. The generic proof
+ * engine — the mappers below use it, and you can too for custom VC types.
+ */
+export function signVC(unsecured, signer, opts) {
+    if (!Array.isArray(unsecured['@context']) || unsecured['@context'][0] !== VC_CONTEXT) {
+        throw new Error(`@context must start with ${VC_CONTEXT}`);
+    }
+    if (Number.isNaN(Date.parse(opts.created)))
+        throw new Error('created must be an ISO timestamp');
+    const proofOptions = {
+        '@context': unsecured['@context'],
+        type: 'DataIntegrityProof',
+        cryptosuite: CRYPTOSUITE,
+        created: opts.created,
+        verificationMethod: verificationMethodOf(signer.did),
+        proofPurpose: 'assertionMethod',
+    };
+    const sig = ed25519.sign(hashData(unsecured, proofOptions), signer.privateKey);
+    const proof = {
+        type: 'DataIntegrityProof',
+        cryptosuite: CRYPTOSUITE,
+        created: opts.created,
+        verificationMethod: proofOptions['verificationMethod'],
+        proofPurpose: 'assertionMethod',
+        proofValue: `z${base58.encode(sig)}`,
+    };
+    return { ...unsecured, proof };
+}
+/**
+ * Verify a did:key `eddsa-jcs-2022` VC — any issuer, not just Zanii's. Checks the
+ * DataIntegrityProof and that the verification method belongs to the stated issuer.
+ * Pass `at` to also check the `validFrom`/`validUntil` window (deliberately not
+ * defaulted to "now" — verification stays deterministic).
+ */
+export function verifyVC(vc, opts = {}) {
+    const reasons = [];
+    const v = vc ?? {};
+    if (!Array.isArray(v['@context']) || v['@context'][0] !== VC_CONTEXT)
+        reasons.push(`@context must start with ${VC_CONTEXT}`);
+    if (!Array.isArray(v.type) || !v.type.includes('VerifiableCredential'))
+        reasons.push('type must include VerifiableCredential');
+    if (typeof v.issuer !== 'string' || !v.issuer.startsWith('did:key:'))
+        reasons.push('issuer must be a did:key (this bridge verifies did:key VCs only)');
+    const p = v.proof;
+    if (!p || p.type !== 'DataIntegrityProof' || p.cryptosuite !== CRYPTOSUITE) {
+        reasons.push(`proof must be a DataIntegrityProof with cryptosuite ${CRYPTOSUITE}`);
+    }
+    if (reasons.length > 0)
+        return { ok: false, reasons, issuer: null };
+    const proof = p;
+    if (proof.verificationMethod !== verificationMethodOf(v.issuer)) {
+        reasons.push('verificationMethod does not belong to the stated issuer');
+    }
+    const pub = publicKeyFromDid(v.issuer);
+    if (!pub)
+        reasons.push('issuer did:key does not decode to an Ed25519 key');
+    let sig = null;
+    if (typeof proof.proofValue === 'string' && proof.proofValue.startsWith('z')) {
+        try {
+            sig = base58.decode(proof.proofValue.slice(1));
+        }
+        catch {
+            sig = null;
+        }
+    }
+    if (!sig)
+        reasons.push('proofValue is not multibase base58btc');
+    if (reasons.length === 0 && pub && sig) {
+        const { proofValue: _omit, ...proofOptions } = proof;
+        const data = hashData(v, { '@context': v['@context'], ...proofOptions });
+        let valid = false;
+        try {
+            valid = ed25519.verify(sig, data, pub);
+        }
+        catch {
+            valid = false;
+        }
+        if (!valid)
+            reasons.push('proof does not verify — the VC was altered or signed by another key');
+    }
+    if (opts.at !== undefined && reasons.length === 0) {
+        const at = Date.parse(opts.at);
+        if (Number.isNaN(at))
+            reasons.push('at must be an ISO timestamp');
+        else {
+            if (typeof v.validFrom === 'string' && at < Date.parse(v.validFrom))
+                reasons.push(`not yet valid at ${opts.at}`);
+            if (typeof v.validUntil === 'string' && at > Date.parse(v.validUntil))
+                reasons.push(`expired at ${opts.at}`);
+        }
+    }
+    return { ok: reasons.length === 0, reasons, issuer: reasons.length === 0 ? v.issuer : null };
+}
+/** The Zanii credential signature convention: `ed25519:<hex>` over the JCS bytes minus `sig`. */
+function zaniiSigValid(obj, signerDid) {
+    const pub = publicKeyFromDid(signerDid);
+    const hex = typeof obj.sig === 'string' && obj.sig.startsWith('ed25519:') ? obj.sig.slice(8) : '';
+    if (!pub || !/^[0-9a-f]{128}$/.test(hex))
+        return false;
+    const { sig: _omit, ...unsigned } = obj;
+    try {
+        return ed25519.verify(hexToBytes(hex), canonicalBytes(unsigned), pub);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Export a `@zanii/credentials` credential as a W3C VC, re-issued by the SAME issuer
+ * key. The Zanii signature is verified first — an invalid credential is refused, so
+ * the bridge can never launder a forged artifact into a valid-looking VC. (Revocation
+ * and issuer-domain resolution are deliberately NOT checked here — acceptance-time
+ * checks belong to the verifier via `@zanii/credentials`; the bridge only re-encodes.)
+ */
+export function toVC(credential, issuerPrivateKey, opts) {
+    if (credential?.v !== 1 || credential.type !== 'credential' || !credential.issuer || !credential.holder) {
+        throw new Error('refusing to bridge: not a Zanii credential (v1)');
+    }
+    if (!zaniiSigValid(credential, credential.issuer)) {
+        throw new Error('refusing to bridge an invalid credential: bad issuer signature');
+    }
+    return signVC({
+        '@context': [VC_CONTEXT],
+        type: ['VerifiableCredential', 'ZaniiCredential'],
+        issuer: credential.issuer,
+        validFrom: credential.issued_at,
+        validUntil: credential.exp,
+        credentialSubject: {
+            id: credential.holder,
+            scope: credential.scope,
+            claim: credential.claim,
+            issuerDomain: credential.issuer_domain,
+        },
+    }, { did: credential.issuer, privateKey: issuerPrivateKey }, opts);
+}
+/** Export an AgentCV as a self-issued VC — the agent attests its own assembled view. */
+export function cvToVC(cv, agentPrivateKey, opts) {
+    const check = verifyCV(cv);
+    if (!check.ok || check.signed === false) {
+        throw new Error(`refusing to bridge an invalid CV: ${[...check.reasons].join('; ') || 'bad signature'}`);
+    }
+    return signVC({
+        '@context': [VC_CONTEXT],
+        type: ['VerifiableCredential', 'ZaniiAgentCV'],
+        issuer: cv.did,
+        validFrom: cv.generated_at,
+        credentialSubject: {
+            id: cv.did,
+            summary: cv.summary,
+            work: cv.work,
+            authority: cv.authority,
+            benchmarks: cv.benchmarks,
+            skills: cv.skills,
+        },
+    }, { did: cv.did, privateKey: agentPrivateKey }, opts);
+}
+/** Decode helper for tests/interop: raw signature bytes from a multibase proofValue. */
+export function proofSignatureBytes(proofValue) {
+    if (!proofValue.startsWith('z'))
+        throw new Error('not multibase base58btc');
+    return base58.decode(proofValue.slice(1));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,QAAQ,EAAgB,MAAM,WAAW,CAAC;AAEnD,MAAM,CAAC,MAAM,UAAU,GAAG,sCAAsC,CAAC;AACjE,MAAM,CAAC,MAAM,WAAW,GAAG,gBAAgB,CAAC;AAwB5C,0FAA0F;AAC1F,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,OAAO,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,SAAS,QAAQ,CAAC,GAA4B,EAAE,YAAqC;IACnF,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,SAAS,EAAE,GAAG,GAAG,CAAC;IAC3C,MAAM,UAAU,GAAG,MAAM,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IAC/B,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IACvB,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACrB,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CACpB,SAA8C,EAC9C,MAA+C,EAC/C,IAAyB;IAEzB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,IAAI,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC;QACrF,MAAM,IAAI,KAAK,CAAC,4BAA4B,UAAU,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAChG,MAAM,YAAY,GAA4B;QAC5C,UAAU,EAAE,SAAS,CAAC,UAAU,CAAC;QACjC,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EAAE,WAAW;QACxB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,kBAAkB,EAAE,oBAAoB,CAAC,MAAM,CAAC,GAAG,CAAC;QACpD,YAAY,EAAE,iBAAiB;KAChC,CAAC;IACF,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAoC,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC1G,MAAM,KAAK,GAAuB;QAChC,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EAAE,WAAW;QACxB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,kBAAkB,EAAE,YAAY,CAAC,oBAAoB,CAAW;QAChE,YAAY,EAAE,iBAAiB;QAC/B,UAAU,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;KACrC,CAAC;IACF,OAAO,EAAE,GAAG,SAAS,EAAE,KAAK,EAA0B,CAAC;AACzD,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,EAAoC,EAAE,OAAwB,EAAE;IACvF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,CAAC,GAAG,EAAE,IAAK,EAA2B,CAAC;IAC7C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,UAAU;QAAE,OAAO,CAAC,IAAI,CAAC,4BAA4B,UAAU,EAAE,CAAC,CAAC;IAC7H,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,sBAAsB,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;IAC/H,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,kEAAkE,CAAC,CAAC;IACvJ,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;IAClB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,oBAAoB,IAAI,CAAC,CAAC,WAAW,KAAK,WAAW,EAAE,CAAC;QAC3E,OAAO,CAAC,IAAI,CAAC,uDAAuD,WAAW,EAAE,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAEpE,MAAM,KAAK,GAAG,CAAuB,CAAC;IACtC,IAAI,KAAK,CAAC,kBAAkB,KAAK,oBAAoB,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,yDAAyD,CAAC,CAAC;IAC1E,CAAC;IACD,MAAM,GAAG,GAAG,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,CAAC,GAAG;QAAE,OAAO,CAAC,IAAI,CAAC,kDAAkD,CAAC,CAAC;IAC3E,IAAI,GAAG,GAAsB,IAAI,CAAC;IAClC,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7E,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,GAAG,GAAG,IAAI,CAAC;QACb,CAAC;IACH,CAAC;IACD,IAAI,CAAC,GAAG;QAAE,OAAO,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;IAChE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC;QACvC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,YAAY,EAAE,GAAG,KAAK,CAAC;QACrD,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAuC,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,EAAE,GAAG,YAAY,EAAE,CAAC,CAAC;QAC/G,IAAI,KAAK,GAAG,KAAK,CAAC;QAClB,IAAI,CAAC;YACH,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,KAAK,GAAG,KAAK,CAAC;QAChB,CAAC;QACD,IAAI,CAAC,KAAK;YAAE,OAAO,CAAC,IAAI,CAAC,qEAAqE,CAAC,CAAC;IAClG,CAAC;IACD,IAAI,IAAI,CAAC,EAAE,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/B,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;aAC7D,CAAC;YACJ,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,oBAAoB,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;YACjH,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/G,CAAC;IACH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AAC/F,CAAC;AAED,iGAAiG;AACjG,SAAS,aAAa,CAAC,GAA+C,EAAE,SAAiB;IACvF,MAAM,GAAG,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClG,IAAI,CAAC,GAAG,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACvD,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,QAAQ,EAAE,GAAG,GAAG,CAAC;IACxC,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,IAAI,CAClB,UAAsB,EACtB,gBAA4B,EAC5B,IAAyB;IAEzB,IAAI,UAAU,EAAE,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,IAAI,KAAK,YAAY,IAAI,CAAC,UAAU,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC;QACxG,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,UAAmE,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3G,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,MAAM,CACX;QACE,UAAU,EAAE,CAAC,UAAU,CAAC;QACxB,IAAI,EAAE,CAAC,sBAAsB,EAAE,iBAAiB,CAAC;QACjD,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,SAAS,EAAE,UAAU,CAAC,SAAS;QAC/B,UAAU,EAAE,UAAU,CAAC,GAAG;QAC1B,iBAAiB,EAAE;YACjB,EAAE,EAAE,UAAU,CAAC,MAAM;YACrB,KAAK,EAAE,UAAU,CAAC,KAAK;YACvB,KAAK,EAAE,UAAU,CAAC,KAAK;YACvB,YAAY,EAAE,UAAU,CAAC,aAAa;SACvC;KACF,EACD,EAAE,GAAG,EAAE,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,gBAAgB,EAAE,EACxD,IAAI,CACL,CAAC;AACJ,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,MAAM,CAAC,EAAW,EAAE,eAA2B,EAAE,IAAyB;IACxF,MAAM,KAAK,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC3B,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,eAAe,EAAE,CAAC,CAAC;IAC3G,CAAC;IACD,OAAO,MAAM,CACX;QACE,UAAU,EAAE,CAAC,UAAU,CAAC;QACxB,IAAI,EAAE,CAAC,sBAAsB,EAAE,cAAc,CAAC;QAC9C,MAAM,EAAE,EAAE,CAAC,GAAG;QACd,SAAS,EAAE,EAAE,CAAC,YAAY;QAC1B,iBAAiB,EAAE;YACjB,EAAE,EAAE,EAAE,CAAC,GAAG;YACV,OAAO,EAAE,EAAE,CAAC,OAA6C;YACzD,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,SAAS,EAAE,EAAE,CAAC,SAAS;YACvB,UAAU,EAAE,EAAE,CAAC,UAAU;YACzB,MAAM,EAAE,EAAE,CAAC,MAAM;SAClB;KACF,EACD,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,eAAe,EAAE,EAC5C,IAAI,CACL,CAAC;AACJ,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC5E,OAAO,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5C,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@zanii/vc",
+  "version": "0.1.0",
+  "description": "W3C Verifiable Credentials 2.0 bridge - export Zanii credentials and AgentCVs as spec-conformant VCs with genuine eddsa-jcs-2022 DataIntegrityProofs (Zanii already speaks did:key + Ed25519 + JCS, which IS that cryptosuite), and verify any did:key eddsa-jcs-2022 VC from anyone. Bridges the format, not the trust model: revocation freshness and domain binding remain Zanii-side checks.",
+  "license": "Apache-2.0",
+  "homepage": "https://ledger.zanii.agency",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.8.1",
+    "@noble/hashes": "^1.7.1",
+    "@scure/base": "^1.2.1",
+    "@zanii/core": "0.4.0",
+    "@zanii/cv": "0.1.0",
+    "@zanii/credentials": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,256 @@
+/**
+ * @zanii/vc — the W3C Verifiable Credentials 2.0 bridge.
+ *
+ * Governments, universities, and wallets increasingly speak the W3C VC data model.
+ * Zanii doesn't need a new trust stack to meet them: Zanii already signs with
+ * **did:key + Ed25519 over JCS**, which is *exactly* the W3C Data Integrity
+ * cryptosuite **`eddsa-jcs-2022`**. So this bridge is not cosmetic — `toVC` emits
+ * spec-conformant VCs with genuine `DataIntegrityProof`s a standards wallet can
+ * verify, and `verifyVC` verifies any did:key `eddsa-jcs-2022` VC from anyone.
+ *
+ * Two mappers over one proof engine:
+ * - `toVC(credential, issuerKey)` — a `@zanii/credentials` credential (diploma,
+ *   licence), re-issued as a VC **by the same issuer key** (the Zanii signature is
+ *   verified first; an invalid credential is refused).
+ * - `cvToVC(cv, agentKey)` — an AgentCV as a self-issued VC (the agent attests its
+ *   own assembled view, exactly like `signCV`).
+ *
+ * ## The limit, stated up front
+ *
+ * This bridges the **format, not the trust model.** A VC produced here proves what
+ * the Zanii artifact proved — no more. Revocation with an explicit freshness window,
+ * the domain-bound issuer root-of-trust, and ledger-backed history remain Zanii-side
+ * checks (`@zanii/credentials` `verifyCredential`, `resolveIssuer`); W3C-native
+ * status mechanisms (StatusList) are deliberately not implemented — mapping them
+ * would claim a liveness this bridge cannot provide. And `verifyVC` checks the
+ * proof and (optionally) the validity window — it does NOT resolve issuers or check
+ * revocation; say what it does, never more.
+ */
+import { ed25519 } from '@noble/curves/ed25519';
+import { sha256 } from '@noble/hashes/sha256';
+import { hexToBytes } from '@noble/hashes/utils';
+import { base58 } from '@scure/base';
+import { canonicalBytes, publicKeyFromDid } from '@zanii/core';
+import type { Credential } from '@zanii/credentials';
+import { verifyCV, type AgentCV } from '@zanii/cv';
+
+export const VC_CONTEXT = 'https://www.w3.org/ns/credentials/v2';
+export const CRYPTOSUITE = 'eddsa-jcs-2022';
+
+export interface DataIntegrityProof {
+  type: 'DataIntegrityProof';
+  cryptosuite: typeof CRYPTOSUITE;
+  created: string;
+  /** `did:key:z6Mk…#z6Mk…` — the did:key with its multikey fragment. */
+  verificationMethod: string;
+  proofPurpose: 'assertionMethod';
+  /** Multibase base58btc (`z…`) of the Ed25519 signature. */
+  proofValue: string;
+}
+
+export interface VerifiableCredential {
+  '@context': string[];
+  type: string[];
+  issuer: string;
+  validFrom?: string;
+  validUntil?: string;
+  credentialSubject: Record<string, unknown>;
+  proof?: DataIntegrityProof;
+  [k: string]: unknown;
+}
+
+/** The verification method a did:key controls: the DID plus its own multikey fragment. */
+export function verificationMethodOf(did: string): string {
+  return `${did}#${did.slice('did:key:'.length)}`;
+}
+
+/**
+ * `eddsa-jcs-2022` hash step: sha256(JCS(proof options)) || sha256(JCS(document
+ * without proof)) — 64 bytes, which the Ed25519 key signs.
+ */
+function hashData(doc: Record<string, unknown>, proofOptions: Record<string, unknown>): Uint8Array {
+  const { proof: _omit, ...unsecured } = doc;
+  const configHash = sha256(canonicalBytes(proofOptions));
+  const docHash = sha256(canonicalBytes(unsecured));
+  const out = new Uint8Array(64);
+  out.set(configHash, 0);
+  out.set(docHash, 32);
+  return out;
+}
+
+/**
+ * Sign any VC-shaped document with a did:key per `eddsa-jcs-2022`. The generic proof
+ * engine — the mappers below use it, and you can too for custom VC types.
+ */
+export function signVC(
+  unsecured: Omit<VerifiableCredential, 'proof'>,
+  signer: { did: string; privateKey: Uint8Array },
+  opts: { created: string },
+): VerifiableCredential {
+  if (!Array.isArray(unsecured['@context']) || unsecured['@context'][0] !== VC_CONTEXT) {
+    throw new Error(`@context must start with ${VC_CONTEXT}`);
+  }
+  if (Number.isNaN(Date.parse(opts.created))) throw new Error('created must be an ISO timestamp');
+  const proofOptions: Record<string, unknown> = {
+    '@context': unsecured['@context'],
+    type: 'DataIntegrityProof',
+    cryptosuite: CRYPTOSUITE,
+    created: opts.created,
+    verificationMethod: verificationMethodOf(signer.did),
+    proofPurpose: 'assertionMethod',
+  };
+  const sig = ed25519.sign(hashData(unsecured as Record<string, unknown>, proofOptions), signer.privateKey);
+  const proof: DataIntegrityProof = {
+    type: 'DataIntegrityProof',
+    cryptosuite: CRYPTOSUITE,
+    created: opts.created,
+    verificationMethod: proofOptions['verificationMethod'] as string,
+    proofPurpose: 'assertionMethod',
+    proofValue: `z${base58.encode(sig)}`,
+  };
+  return { ...unsecured, proof } as VerifiableCredential;
+}
+
+export interface VCCheck {
+  ok: boolean;
+  reasons: string[];
+  /** The issuer DID whose key produced the proof (when it verified). */
+  issuer: string | null;
+}
+
+/**
+ * Verify a did:key `eddsa-jcs-2022` VC — any issuer, not just Zanii's. Checks the
+ * DataIntegrityProof and that the verification method belongs to the stated issuer.
+ * Pass `at` to also check the `validFrom`/`validUntil` window (deliberately not
+ * defaulted to "now" — verification stays deterministic).
+ */
+export function verifyVC(vc: VerifiableCredential | undefined, opts: { at?: string } = {}): VCCheck {
+  const reasons: string[] = [];
+  const v = vc ?? ({} as VerifiableCredential);
+  if (!Array.isArray(v['@context']) || v['@context'][0] !== VC_CONTEXT) reasons.push(`@context must start with ${VC_CONTEXT}`);
+  if (!Array.isArray(v.type) || !v.type.includes('VerifiableCredential')) reasons.push('type must include VerifiableCredential');
+  if (typeof v.issuer !== 'string' || !v.issuer.startsWith('did:key:')) reasons.push('issuer must be a did:key (this bridge verifies did:key VCs only)');
+  const p = v.proof;
+  if (!p || p.type !== 'DataIntegrityProof' || p.cryptosuite !== CRYPTOSUITE) {
+    reasons.push(`proof must be a DataIntegrityProof with cryptosuite ${CRYPTOSUITE}`);
+  }
+  if (reasons.length > 0) return { ok: false, reasons, issuer: null };
+
+  const proof = p as DataIntegrityProof;
+  if (proof.verificationMethod !== verificationMethodOf(v.issuer)) {
+    reasons.push('verificationMethod does not belong to the stated issuer');
+  }
+  const pub = publicKeyFromDid(v.issuer);
+  if (!pub) reasons.push('issuer did:key does not decode to an Ed25519 key');
+  let sig: Uint8Array | null = null;
+  if (typeof proof.proofValue === 'string' && proof.proofValue.startsWith('z')) {
+    try {
+      sig = base58.decode(proof.proofValue.slice(1));
+    } catch {
+      sig = null;
+    }
+  }
+  if (!sig) reasons.push('proofValue is not multibase base58btc');
+  if (reasons.length === 0 && pub && sig) {
+    const { proofValue: _omit, ...proofOptions } = proof;
+    const data = hashData(v as unknown as Record<string, unknown>, { '@context': v['@context'], ...proofOptions });
+    let valid = false;
+    try {
+      valid = ed25519.verify(sig, data, pub);
+    } catch {
+      valid = false;
+    }
+    if (!valid) reasons.push('proof does not verify — the VC was altered or signed by another key');
+  }
+  if (opts.at !== undefined && reasons.length === 0) {
+    const at = Date.parse(opts.at);
+    if (Number.isNaN(at)) reasons.push('at must be an ISO timestamp');
+    else {
+      if (typeof v.validFrom === 'string' && at < Date.parse(v.validFrom)) reasons.push(`not yet valid at ${opts.at}`);
+      if (typeof v.validUntil === 'string' && at > Date.parse(v.validUntil)) reasons.push(`expired at ${opts.at}`);
+    }
+  }
+  return { ok: reasons.length === 0, reasons, issuer: reasons.length === 0 ? v.issuer : null };
+}
+
+/** The Zanii credential signature convention: `ed25519:<hex>` over the JCS bytes minus `sig`. */
+function zaniiSigValid(obj: Record<string, unknown> & { sig?: string }, signerDid: string): boolean {
+  const pub = publicKeyFromDid(signerDid);
+  const hex = typeof obj.sig === 'string' && obj.sig.startsWith('ed25519:') ? obj.sig.slice(8) : '';
+  if (!pub || !/^[0-9a-f]{128}$/.test(hex)) return false;
+  const { sig: _omit, ...unsigned } = obj;
+  try {
+    return ed25519.verify(hexToBytes(hex), canonicalBytes(unsigned), pub);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Export a `@zanii/credentials` credential as a W3C VC, re-issued by the SAME issuer
+ * key. The Zanii signature is verified first — an invalid credential is refused, so
+ * the bridge can never launder a forged artifact into a valid-looking VC. (Revocation
+ * and issuer-domain resolution are deliberately NOT checked here — acceptance-time
+ * checks belong to the verifier via `@zanii/credentials`; the bridge only re-encodes.)
+ */
+export function toVC(
+  credential: Credential,
+  issuerPrivateKey: Uint8Array,
+  opts: { created: string },
+): VerifiableCredential {
+  if (credential?.v !== 1 || credential.type !== 'credential' || !credential.issuer || !credential.holder) {
+    throw new Error('refusing to bridge: not a Zanii credential (v1)');
+  }
+  if (!zaniiSigValid(credential as unknown as Record<string, unknown> & { sig?: string }, credential.issuer)) {
+    throw new Error('refusing to bridge an invalid credential: bad issuer signature');
+  }
+  return signVC(
+    {
+      '@context': [VC_CONTEXT],
+      type: ['VerifiableCredential', 'ZaniiCredential'],
+      issuer: credential.issuer,
+      validFrom: credential.issued_at,
+      validUntil: credential.exp,
+      credentialSubject: {
+        id: credential.holder,
+        scope: credential.scope,
+        claim: credential.claim,
+        issuerDomain: credential.issuer_domain,
+      },
+    },
+    { did: credential.issuer, privateKey: issuerPrivateKey },
+    opts,
+  );
+}
+
+/** Export an AgentCV as a self-issued VC — the agent attests its own assembled view. */
+export function cvToVC(cv: AgentCV, agentPrivateKey: Uint8Array, opts: { created: string }): VerifiableCredential {
+  const check = verifyCV(cv);
+  if (!check.ok || check.signed === false) {
+    throw new Error(`refusing to bridge an invalid CV: ${[...check.reasons].join('; ') || 'bad signature'}`);
+  }
+  return signVC(
+    {
+      '@context': [VC_CONTEXT],
+      type: ['VerifiableCredential', 'ZaniiAgentCV'],
+      issuer: cv.did,
+      validFrom: cv.generated_at,
+      credentialSubject: {
+        id: cv.did,
+        summary: cv.summary as unknown as Record<string, unknown>,
+        work: cv.work,
+        authority: cv.authority,
+        benchmarks: cv.benchmarks,
+        skills: cv.skills,
+      },
+    },
+    { did: cv.did, privateKey: agentPrivateKey },
+    opts,
+  );
+}
+
+/** Decode helper for tests/interop: raw signature bytes from a multibase proofValue. */
+export function proofSignatureBytes(proofValue: string): Uint8Array {
+  if (!proofValue.startsWith('z')) throw new Error('not multibase base58btc');
+  return base58.decode(proofValue.slice(1));
+}