@openentity/sdk 0.2.0 → 0.4.1

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export interface KeyPair {
 }
 export declare function keyPairFromJwk(privateJwk: JsonWebKey): Promise<KeyPair>;
 export declare function generateKeyPair(): Promise<KeyPair>;
-/** Deterministic key pair from a 32-byte seed. For test vectors only. */
+/** Deterministic key pair from a 32-byte seed: test vectors, and `Identity` (sdk/ts/src/node.ts), which keeps the seed. */
 export declare function keyPairFromSeed(seed32: Uint8Array): Promise<KeyPair>;
 export declare function didKeyFromPublicKey(pk: Uint8Array): string;
 export declare function publicKeyFromDidKey(did: string): Uint8Array;
@@ -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,203 @@ 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[];
+    }[];
+};
+type IssuerOpts = {
+    issuer?: string;
+    keyId?: string;
+    now?: Date;
+};
+/** A signed Attestation (spec 8.2). `ttlSeconds` defaults to 90 days and is capped at one year. */
+export declare function signAttestation(kp: KeyPair, o: IssuerOpts & {
+    subject: string;
+    claimType: string;
+    claim: object;
+    evidence?: object;
+    confidence?: number;
+    ttlSeconds?: number;
+}): Promise<{
+    spec: string;
+    type: string;
+    issuer: string;
+    subject: string;
+    claim_type: string;
+    claim: object;
+    evidence?: object | undefined;
+    confidence?: number | undefined;
+    created: string;
+    expires: string;
+} & {
+    proof: Proof;
+}>;
+/** A signed Revocation naming the attestation (the object, or its SHA-256 hex) (spec 8.4). */
+export declare function signRevocation(kp: KeyPair, attested: object | string, o?: IssuerOpts & {
+    reason?: string;
+}): Promise<{
+    spec: string;
+    type: string;
+    issuer: string;
+    attestation_sha256: string;
+    reason?: string | undefined;
+    created: string;
+} & {
+    proof: Proof;
+}>;
+/** The body of `https://<domain>/.well-known/did.json` for a did:web issuer. */
+export declare function buildDidDocument(did: string, publicKey: Uint8Array, keyId?: string): {
+    "@context": string[];
+    id: string;
+    verificationMethod: {
+        id: string;
+        type: string;
+        controller: string;
+        publicKeyMultibase: string;
+    }[];
+    assertionMethod: string[];
+    authentication: string[];
+};
+/** The unsigned body of `https://<domain>/.well-known/openentity.json`: the domain alias proof (spec 3.4) and, under
+ * `extensions["openentity:observer"]`, an observer's methodology (spec 8.4). */
+export declare function buildOpenEntityJson(did: string, publicKey: Uint8Array, o: {
+    name: string;
+    description: string;
+    keyId?: string;
+    operator?: object;
+    extensions?: object;
+}): {
+    spec: string;
+    eid: string;
+    name: string;
+    description: string;
+    keys: {
+        id: string;
+        type: string;
+        publicKeyMultibase: string;
+    }[];
+    operator: object;
+    extensions?: object | undefined;
+};
+/** The registry's allowlist for the unsigned `client` label on POST /v1/adopt. */
+export declare const CLIENTS: readonly ["adk", "goose", "langchain", "ui-tars", "cli", "other"];
+export type Client = (typeof CLIENTS)[number];
+/** Adopt `kp` on a registry: document, Declaration and the seq-1 declaration entry (spec 5.2, 6.2, 7.3). `client` is not signed. */
+export declare function adopt(kp: KeyPair, o: {
+    name: string;
+    description?: string;
+    registry?: string;
+    client?: Client;
+}): Promise<{
+    response: any;
+    did: string;
+    document: object & {
+        proof: Proof;
+    };
+    declaration: object & {
+        proof: Proof;
+    };
+    recordEntry: {
+        spec: string;
+        type: string;
+        eid: string;
+        seq: number;
+        prev: null;
+        kind: string;
+        at: string;
+        payload: {
+            declaration_version: string;
+            sha256: string;
+        };
+    } & {
+        proof: Proof;
+    };
+    recordPushed: boolean;
+}>;
+export interface TrustReport {
+    eid: string;
+    /** false: a read failed or a signature did not verify. Treat the entity as untrusted. */
+    ok: boolean;
+    error?: string;
+    level?: string;
+    withdrawn: boolean;
+    /** issuer DID to its newest live tier (0 to 4) */
+    trustTier: Record<string, number>;
+    /** claim of the newest live custom:securemyagent:security_posture */
+    securityPosture: Record<string, any> | null;
+    /** live custom:clawgrc:violation */
+    violations: {
+        issuer: string;
+        severity: string;
+        policy: string;
+        observed_at: string;
+        sha256: string;
+    }[];
+    /** verified revocations of the accepted attestations */
+    revocations: {
+        sha256: string;
+        claim_type: string;
+        issuer: string;
+        reason?: string;
+        at: string;
+    }[];
+}
+type FetchJson = (url: string) => Promise<any>;
+export declare const clearTrustCache: () => void;
+/** did:web through /.well-known/did.json (or <path>/did.json); everything else offline. */
+export declare function didWebResolver(fetchJson?: FetchJson): Resolver;
+/**
+ * One TrustReport from `GET /v1/entities/{eid}` and `/attestations` only. Every attestation and revocation from the accepted
+ * issuers is verified locally against the issuer's key; any failure returns an untrusted report. Cached for 5 minutes.
+ */
+export declare function trust(eid: string, o?: {
+    registry?: string;
+    now?: Date;
+    fetchJson?: FetchJson;
+    resolver?: Resolver;
+}): Promise<TrustReport>;
 export {};