@openentity/sdk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -45,8 +45,9 @@ type VerifyResult = {
 };
 /** eddsa-jcs-2022 hashData: sha256(JCS(proof config)) || sha256(JCS(document)). */
 export declare function hashData(obj: object, config: Omit<Proof, "proofValue">): Uint8Array;
-export declare function signProof(obj: object, kp: KeyPair, created?: string): Promise<Proof>;
-export declare function signObject<T extends object>(obj: T, kp: KeyPair, created?: string): Promise<T & {
+/** `verificationMethod` defaults to the did:key of `kp`; a did:web signer passes its own method id (for example `did:web:x#key-1`). */
+export declare function signProof(obj: object, kp: KeyPair, created?: string, verificationMethod?: string): Promise<Proof>;
+export declare function signObject<T extends object>(obj: T, kp: KeyPair, created?: string, verificationMethod?: string): Promise<T & {
     proof: Proof;
 }>;
 export declare function verifyProof(obj: object, proof: Proof, resolver?: Resolver): Promise<VerifyResult>;
@@ -74,9 +75,36 @@ export declare function buildDeclaration(input: {
     name: string;
     created?: string;
 }): object;
+/** The successor's unsigned seq 1 Entity Document: `prev` re-keyed, aliases dropped (their proofs name the old EID), `continuity.previous` set. */
+export declare function successorDocument(prev: Record<string, any>, next: KeyPair, created?: string): Record<string, any>;
+/** A Continuity Link signed by both keys (spec 9.2) plus the successor's document signed by the successor: the body of `POST /v1/continuity`. */
+export declare function buildRotation(previous: KeyPair, successor: KeyPair, document: Record<string, any>, o?: {
+    basis?: "rotation" | "migration";
+    created?: string;
+    nonce?: string;
+}): Promise<{
+    link: Record<string, any>;
+    document: Record<string, any>;
+}>;
+/**
+ * Rotate `previous` to a new key in one call: fetch the current document, build and sign the link, mint the stamp for the
+ * successor and submit. Nothing is persisted: on success the caller saves `successor` (its `privateJwk`) and only then retires
+ * the old key. Throws on any non-2xx answer.
+ */
+export declare function rotate(o: {
+    previous: KeyPair;
+    registry?: string;
+    successor?: KeyPair;
+    basis?: "rotation" | "migration";
+}): Promise<{
+    successor: KeyPair;
+    link: Record<string, any>;
+    document: Record<string, any>;
+    response: any;
+}>;
 /** sha256 hex of the canonical entry INCLUDING its proof: the next entry's `prev` (spec 7.4). */
 export declare function recordEntryHash(entry: object): Promise<string>;
-type ObjectType = "EntityDocument" | "Declaration" | "Withdrawal" | "RecordEntry" | "Attestation" | "Revocation" | "ContinuityLink" | "Dispute" | "Presentation" | "LogLeaf";
+type ObjectType = "EntityDocument" | "Declaration" | "Withdrawal" | "Redaction" | "RecordEntry" | "Attestation" | "Revocation" | "ContinuityLink" | "Dispute" | "Presentation" | "LogLeaf";
 /** Schema check (spec Appendix A) plus size caps: 16 KB for a RecordEntry (7.4), 64 KB for anything else (5.2). */
 export declare function validate(type: ObjectType, obj: unknown): {
     ok: boolean;
@@ -132,4 +160,52 @@ export declare function verifyPresentation(p: any, opts: {
     errors: string[];
     attestations: AttestationCheck[];
 }>;
+export declare const A2A_EXTENSION_URI = "https://openentity.org/spec/1.0";
+/** The AgentExtension entry that carries an EID in an A2A Agent Card's `capabilities.extensions`. */
+export declare function a2aExtension(eid: string, documentUrl: string): {
+    uri: string;
+    description: string;
+    required: boolean;
+    params: {
+        eid: string;
+        document: string;
+    };
+};
+/** A full A2A AgentCard for an Entity Document: each capability slug becomes a skill. `url` is the agent's A2A endpoint. */
+export declare function agentCard(doc: {
+    eid: string;
+    name: string;
+    description: string;
+    capabilities?: string[];
+}, opts: {
+    url: string;
+    documentUrl: string;
+    version?: string;
+}): {
+    name: string;
+    description: string;
+    url: string;
+    version: string;
+    capabilities: {
+        streaming: boolean;
+        pushNotifications: boolean;
+        extensions: {
+            uri: string;
+            description: string;
+            required: boolean;
+            params: {
+                eid: string;
+                document: string;
+            };
+        }[];
+    };
+    defaultInputModes: string[];
+    defaultOutputModes: string[];
+    skills: {
+        id: string;
+        name: string;
+        description: string;
+        tags: string[];
+    }[];
+};
 export {};

package/dist/index.js

@@ -939,6 +939,46 @@ var openentity_1_0_default = {
         }
       ]
     },
+    Redaction: {
+      type: "object",
+      required: [
+        "spec",
+        "type",
+        "eid",
+        "seq",
+        "entry_sha256",
+        "created",
+        "nonce",
+        "proof"
+      ],
+      properties: {
+        spec: {
+          $ref: "#/$defs/spec"
+        },
+        type: {
+          const: "Redaction"
+        },
+        eid: {
+          $ref: "#/$defs/did"
+        },
+        seq: {
+          type: "integer",
+          minimum: 1
+        },
+        entry_sha256: {
+          $ref: "#/$defs/hex64"
+        },
+        created: {
+          $ref: "#/$defs/timestamp"
+        },
+        nonce: {
+          $ref: "#/$defs/nonce"
+        },
+        proof: {
+          $ref: "#/$defs/proof"
+        }
+      }
+    },
     Attestation: {
       type: "object",
       required: [
@@ -1355,19 +1395,19 @@ function unsecured(obj) {
 function hashData(obj, config) {
   return concat(sha256Sync(canonicalize(config)), sha256Sync(canonicalize(unsecured(obj))));
 }
-async function signProof(obj, kp, created = nowSeconds()) {
+async function signProof(obj, kp, created = nowSeconds(), verificationMethod = verificationMethodId(kp.did)) {
   const config = {
     type: "DataIntegrityProof",
     cryptosuite: "eddsa-jcs-2022",
     created,
-    verificationMethod: verificationMethodId(kp.did),
+    verificationMethod,
     proofPurpose: "assertionMethod"
   };
   const sig = new Uint8Array(await crypto.subtle.sign({ name: "Ed25519" }, kp.privateKey, hashData(obj, config)));
   return { ...config, proofValue: "z" + base58btcEncode(sig) };
 }
-async function signObject(obj, kp, created) {
-  return { ...obj, proof: await signProof(obj, kp, created) };
+async function signObject(obj, kp, created, verificationMethod) {
+  return { ...obj, proof: await signProof(obj, kp, created, verificationMethod) };
 }
 async function verifyProof(obj, proof, resolver = defaultResolver) {
   try {
@@ -1462,6 +1502,43 @@ function buildDeclaration(input) {
     nonce: randomNonce()
   };
 }
+function successorDocument(prev, next, created = nowSeconds()) {
+  const { proof: _p, aliases: _a, ...d } = structuredClone(prev);
+  return {
+    ...d,
+    eid: next.did,
+    keys: [{ id: verificationMethodId(next.did), type: "Multikey", publicKeyMultibase: next.did.slice("did:key:".length) }],
+    created,
+    updated: created,
+    seq: 1,
+    continuity: { ...d.continuity, previous: prev.eid }
+  };
+}
+async function buildRotation(previous, successor, document, o = {}) {
+  const created = o.created ?? nowSeconds();
+  const body = { spec: SPEC, type: "ContinuityLink", previous: previous.did, successor: successor.did, basis: o.basis ?? "rotation", created, nonce: o.nonce ?? randomNonce() };
+  const link = { ...body, proofs: [await signProof(body, previous, created), await signProof(body, successor, created)] };
+  return { link, document: await signObject(document, successor, created) };
+}
+async function rotate(o) {
+  const registry = (o.registry ?? "https://openentity.org").replace(/\/+$/, "");
+  const call = async (path2, init) => {
+    const r = await fetch(registry + path2, init);
+    const text = await r.text();
+    if (!r.ok) throw new Error(`registry ${r.status} for ${path2}: ${text.slice(0, 200)}`);
+    return JSON.parse(text);
+  };
+  const next = o.successor ?? await generateKeyPair();
+  const prevDoc = await call(`/v1/entities/${o.previous.did}/document`);
+  const { link, document } = await buildRotation(o.previous, next, successorDocument(prevDoc, next), { basis: o.basis });
+  const { stamp_bits } = await call("/v1/spec");
+  const response = await call("/v1/continuity", {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-oe-stamp": await mintStamp(stamp_bits, next.did) },
+    body: JSON.stringify({ link, document })
+  });
+  return { successor: next, link, document, response };
+}
 async function recordEntryHash(entry) {
   return sha256Hex(canonicalize(entry));
 }
@@ -1680,16 +1757,39 @@ async function verifyPresentation(p, opts) {
   }
   return { ok: errors.length === 0, eid, errors, attestations };
 }
+var A2A_EXTENSION_URI = "https://openentity.org/spec/1.0";
+function a2aExtension(eid, documentUrl) {
+  return { uri: A2A_EXTENSION_URI, description: "Open Entity identity (OEIS-1) of this agent", required: false, params: { eid, document: documentUrl } };
+}
+function agentCard(doc, opts) {
+  return {
+    name: doc.name,
+    description: doc.description,
+    url: opts.url,
+    version: opts.version ?? "1.0.0",
+    capabilities: { streaming: false, pushNotifications: false, extensions: [a2aExtension(doc.eid, opts.documentUrl)] },
+    defaultInputModes: ["text/plain"],
+    defaultOutputModes: ["text/plain"],
+    skills: (doc.capabilities ?? []).map((slug) => {
+      const [ns, name] = slug.includes(":") ? slug.split(":", 2) : [void 0, slug];
+      return { id: slug, name: name.replace(/[-.]/g, " "), description: `Self-declared capability: ${slug}`, tags: ns ? [ns, name] : [name] };
+    })
+  };
+}
 export {
+  A2A_EXTENSION_URI,
   DECLARATION_SHA256,
   DECLARATION_TEXT,
   DECLARATION_VERSION,
   SPEC,
+  a2aExtension,
+  agentCard,
   base58btcDecode,
   base58btcEncode,
   buildDeclaration,
   buildDocument,
   buildPresentation,
+  buildRotation,
   canonicalize,
   checkStamp,
   checkTimestamp,
@@ -1714,11 +1814,13 @@ export {
   randomNonce,
   recordEntryHash,
   recoverEip712,
+  rotate,
   sha256,
   sha256Hex,
   signNote,
   signObject,
   signProof,
+  successorDocument,
   validate,
   verificationMethodId,
   verifyConsistency,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openentity/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Reference TypeScript SDK for the Open Entity Identity Standard (OEIS-1)",
   "license": "MIT",
   "type": "module",