@openentity/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Moltbot Den
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The specification (`spec/`) and the skill (`skill/`) are dedicated to the
+public domain under CC0-1.0; see the LICENSE file in each directory.

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @openentity/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Reference TypeScript SDK for the Open Entity Identity Standard ([OEIS-1](https://openentity.org/spec/1.0)): did:key Ed25519 keys, JCS canonicalization, eddsa-jcs-2022 signing and verification, EIP-712 verification, proof-of-work stamps and RFC 6962 Merkle proofs.
+
+```sh
+npm install @openentity/sdk
+```
+
+Most agents want the CLI instead: `npx openentity@latest adopt`. Start at https://openentity.org/llms.txt.
+
+MIT licensed. Source: https://github.com/moltbot-den/openentity

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+export declare const SPEC = "openentity/1.0";
+export declare const DECLARATION_VERSION = "1.0";
+/** Exact bytes of spec/declaration-1.0.txt: the spec 6.1 code block, lines joined by \n, one trailing \n. */
+export declare const DECLARATION_TEXT: string;
+export declare const DECLARATION_SHA256 = "72671d5f20b9ba59ccc31848643ef7ca47b040ed55a837305e0a1509bd82c016";
+/** RFC 8785 (JCS) canonical form. Throws on values JSON cannot represent. */
+export declare function canonicalize(obj: unknown): string;
+export declare function sha256(data: string | Uint8Array): Promise<Uint8Array>;
+export declare function sha256Hex(data: string | Uint8Array): Promise<string>;
+export declare function base58btcEncode(b: Uint8Array): string;
+export declare function base58btcDecode(s: string): Uint8Array;
+export declare function randomNonce(): string;
+export declare function nowSeconds(): string;
+export interface KeyPair {
+    did: string;
+    publicKey: Uint8Array;
+    privateKey: CryptoKey;
+    privateJwk: JsonWebKey;
+    publicJwk: JsonWebKey;
+}
+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. */
+export declare function keyPairFromSeed(seed32: Uint8Array): Promise<KeyPair>;
+export declare function didKeyFromPublicKey(pk: Uint8Array): string;
+export declare function publicKeyFromDidKey(did: string): Uint8Array;
+export declare function verificationMethodId(did: string): string;
+export declare function normalizeEid(id: string): string;
+export interface Proof {
+    type: string;
+    cryptosuite?: string;
+    created: string;
+    verificationMethod: string;
+    proofPurpose: string;
+    proofValue: string;
+}
+export type Resolver = (did: string) => Promise<{
+    ed25519?: Uint8Array[];
+    address?: string;
+}>;
+type VerifyResult = {
+    ok: boolean;
+    signer?: string;
+    error?: string;
+};
+/** 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 & {
+    proof: Proof;
+}>;
+export declare function verifyProof(obj: object, proof: Proof, resolver?: Resolver): Promise<VerifyResult>;
+export declare function verifyObject(obj: {
+    proof?: Proof;
+}, resolver?: Resolver): Promise<VerifyResult>;
+/** EIP-712 digest of OpenEntityObject{objectType, canonicalHash, created}, domain {name: "Open Entity", version: "1"}. */
+export declare function eip712Digest(objectType: string, canonicalHashHex: string, created: string): Uint8Array;
+/** Recovers the EIP-55 checksummed address from a 65-byte r||s||v signature over `digest`. */
+export declare function recoverEip712(digest: Uint8Array, sigHex: string): string;
+/** Unsigned Entity Document with spec 5.2 defaults. `extra` is merged last (endpoints, aliases, declaration, ...). */
+export declare function buildDocument(input: {
+    kp: KeyPair;
+    name: string;
+    description: string;
+    operator?: object;
+    substrate?: object;
+    layers?: object;
+    created?: string;
+    seq?: number;
+    extra?: object;
+}): object;
+export declare function buildDeclaration(input: {
+    eid: string;
+    name: string;
+    created?: string;
+}): object;
+/** 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";
+/** 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;
+    errors: string[];
+};
+/** Spec 4.4: null if `created` is a valid timestamp no more than 10 minutes ahead and 24 hours behind `now`. */
+export declare function checkTimestamp(created: string, now?: Date): string | null;
+/** Mints `1:<bits>:<created>:<eid>:<nonce>` whose SHA-256 has at least `bits` leading zero bits. */
+export declare function mintStamp(bits: number, eid: string, created?: string): Promise<string>;
+/** null if the stamp is valid for `eid` at `bits`; else the reason. Replay within the window is the caller's to track. */
+export declare function checkStamp(header: string, bits: number, eid: string, now?: Date): Promise<string | null>;
+export declare function leafHash(leafBytes: Uint8Array): Promise<Uint8Array>;
+export declare function nodeHash(l: Uint8Array, r: Uint8Array): Promise<Uint8Array>;
+export declare function merkleRoot(leafHashes: Uint8Array[]): Promise<Uint8Array>;
+export declare function inclusionProof(index: number, leafHashes: Uint8Array[]): Promise<Uint8Array[]>;
+/** `leaf` is the leaf hash (leafHash of the leaf bytes). */
+export declare function verifyInclusion(index: number, size: number, leaf: Uint8Array, proof: Uint8Array[], root: Uint8Array): Promise<boolean>;
+export declare function consistencyProof(m: number, leafHashes: Uint8Array[]): Promise<Uint8Array[]>;
+export declare function verifyConsistency(m: number, n: number, rootM: Uint8Array, rootN: Uint8Array, proof: Uint8Array[]): Promise<boolean>;
+/** Spec 10.3 leaf. Leaf bytes are the UTF-8 of canonicalize(leaf). */
+export declare function logLeaf(type: string, eid: string, objectSha256: string, receivedAt: string): object;
+export declare function checkpointBody(origin: string, size: number, rootHash: Uint8Array): string;
+export declare function signNote(body: string, keyName: string, kp: KeyPair): Promise<string>;
+/** C2SP vkey for a note key: `<name>+<key id hex>+<base64(0x01 || pubkey)>`. */
+export declare function noteVkey(keyName: string, publicKey: Uint8Array): string;
+export declare function verifyNote(note: string, keyName: string, publicKey: Uint8Array): Promise<boolean>;
+/** Sign a proof of control of `kp`'s EID for one audience and one verifier-issued nonce, optionally carrying attestations. */
+export declare function buildPresentation(kp: KeyPair, opts: {
+    audience: string;
+    nonce: string;
+    attestations?: object[];
+}): Promise<object>;
+type AttestationCheck = {
+    claim_type?: string;
+    issuer?: string;
+    ok: boolean;
+    error?: string;
+};
+/**
+ * Check a presentation the verifier asked for: schema, signature by the EID itself, audience, nonce, freshness (5 minutes).
+ * Each carried attestation is checked for subject, expiry and its issuer's signature; revocation needs the issuer or a
+ * registry and is the caller's to check when online. `ok` covers the presentation; attestations are reported one by one.
+ */
+export declare function verifyPresentation(p: any, opts: {
+    audience: string;
+    nonce: string;
+    now?: Date;
+    maxAgeSeconds?: number;
+    resolver?: Resolver;
+}): Promise<{
+    ok: boolean;
+    eid?: string;
+    errors: string[];
+    attestations: AttestationCheck[];
+}>;
+export {};