{"_id":"@dolr-ai/identity","name":"@dolr-ai/identity","dist-tags":{"latest":"0.1.4"},"versions":{"0.1.4":{"name":"@dolr-ai/identity","version":"0.1.4","description":"TypeScript implementation of yral-identity for authenticating with Dolr off-chain services","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","test":"jest","lint":"eslint 'src/**/*.ts'","prepare":"npm run build","example":"ts-node examples/usage.ts"},"keywords":["yral","identity","authentication","internet-computer","icp","dfinity"],"author":"","license":"MIT","devDependencies":{"@types/jest":"^29.5.4","@types/node":"^20.5.9","@typescript-eslint/eslint-plugin":"^6.6.0","@typescript-eslint/parser":"^6.6.0","eslint":"^8.48.0","jest":"^29.6.4","ts-jest":"^29.1.1","ts-node":"^10.9.2","typescript":"^5.2.2"},"dependencies":{"@dfinity/agent":"^2.3.0","@dfinity/candid":"^2.3.0","@dfinity/identity":"^2.3.0","@dfinity/principal":"^2.3.0"},"_id":"@dolr-ai/identity@0.1.4","gitHead":"eddd73b4cadcd3b201b0d7d67d3269e0a1a29d0c","_nodeVersion":"22.15.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-IHrfJ7aXj1n8jUcgYRCu0araLR7CZb517DVoclH/rAORbdrt+43VHSkf0GgGOyE35J6W/WBAVJnVusxqYma4Fg==","shasum":"de6c08f586882e7349617eb0f310efeaff6b275b","tarball":"https://registry.npmjs.org/@dolr-ai/identity/-/identity-0.1.4.tgz","fileCount":12,"unpackedSize":48531,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIB4nX4BkVq3JgtITFIVhfDOVxECSrs1U3V1mBjwT61duAiEA6XfWfI9Y/qzZXN+AvwmC8gInbWq5ae6YzlzBNDi9NBE="}]},"_npmUser":{"name":"hrsh-dolr","email":"harsh@gobazzinga.io"},"directories":{},"maintainers":[{"name":"hrsh-dolr","email":"harsh@gobazzinga.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/identity_0.1.4_1746086182929_0.839351669563488"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-01T07:56:22.816Z","0.1.4":"2025-05-01T07:56:23.131Z","modified":"2025-05-01T07:56:23.377Z"},"maintainers":[{"name":"hrsh-dolr","email":"harsh@gobazzinga.io"}],"description":"TypeScript implementation of yral-identity for authenticating with Dolr off-chain services","keywords":["yral","identity","authentication","internet-computer","icp","dfinity"],"license":"MIT","readme":"# yral-identity-ts\n\nA TypeScript implementation of the yral-identity library for authenticating with Yral off-chain services. This library provides a compatible way to sign messages with Internet Computer identities and produce signatures that are compatible with the Rust-based yral-identity library.\n\n## Usage\n\n### Basic Usage\n\n```typescript\nimport { Ed25519KeyIdentity } from \"@dfinity/identity\";\nimport { Principal } from \"@dfinity/principal\";\nimport { IDL } from \"@dfinity/candid\";\nimport { Message, signMessage } from \"yral-identity-ts\";\n\n// Create or load an identity\nconst identity = Ed25519KeyIdentity.generate();\n\n// Create a message\nconst canisterId = Principal.fromText(\"rrkah-fqaaa-aaaaa-aaaaq-cai\");\nconst message = new Message()\n  .withCanisterId(canisterId)\n  .withMethodName(\"greet\")\n  .withArgs([IDL.Text], [\"Hello, World!\"])\n  .withIngressMaxAge(300_000);\n\n// Sign the message\nconst signature = await signMessage(identity, message);\n\n// Convert to JSON for sending to the service\nconst signatureJson = signature.serializeJSON();\n```\n\n### Using Delegations\n\nThe library supports delegations, which allow one identity to act on behalf of another:\n\n```typescript\nimport {\n  DelegationChain,\n  DelegationIdentity,\n  Ed25519KeyIdentity,\n} from \"@dfinity/identity\";\nimport { Principal } from \"@dfinity/principal\";\nimport { Message, signMessage } from \"yral-identity-ts\";\nimport { IDL } from \"@dfinity/candid\";\n\n// Create identities\nconst identity = Ed25519KeyIdentity.generate();\nconst delegationIdentity = Ed25519KeyIdentity.generate();\n\n// Create delegation chain\nconst delegation = await DelegationChain.create(\n  identity,\n  delegationIdentity.getPublicKey(),\n);\n\n// Create delegation identity\nconst delegatedIdentity = DelegationIdentity.fromDelegation(\n  delegationIdentity,\n  delegation,\n);\n\n// Create and sign a message with the delegated identity\nconst message = new Message()\n  .withCanisterId(Principal.fromText(\"rrkah-fqaaa-aaaaa-aaaaq-cai\"))\n  .withMethodName(\"greet\")\n  .withArgs([IDL.Text], [\"Hello, World!\"])\n  .withIngressMaxAge(300_000);\n\nconst signature = await signMessage(delegatedIdentity, message);\n\n// This signature with delegations can now be serialized\nconst signatureJson = signature.serializeJSON();\n```\n\n## Comprehensive Tests\n\nThe library includes tests that verify:\n\n1. Basic functionality with Ed25519KeyIdentity\n2. JSON serialization compatibility with the Rust implementation\n3. Proper Candid encoding of arguments\n4. Delegation support and serialization\n\nRun the tests with:\n\n```bash\nnpm test\n```\n\n## API Reference\n\n### YralIdentityError\n\nError class for yral-identity-ts operations.\n\n```typescript\nclass YralIdentityError extends Error {\n  static SenderNotFound: YralIdentityError;\n  static Signing(e: Error): YralIdentityError;\n  static ArgumentEncoding(e: Error): YralIdentityError;\n}\n```\n\n### Message\n\nThe `Message` class represents a message that can be signed and sent to a canister.\n\n#### Constructor\n\n```typescript\nconstructor(\n  canisterId: Principal = Principal.anonymous(),\n  methodName: string = '',\n  args: Uint8Array = new Uint8Array(),\n  sender: Principal = Principal.anonymous(),\n  ingressExpiry: number = 120_000,\n  nonce?: Uint8Array\n)\n```\n\n#### Properties\n\n- `canisterId: Principal` - The ID of the canister that will receive the message\n- `methodName: string` - The name of the method to call\n- `args: Uint8Array` - The encoded Candid arguments\n- `sender: Principal` - The Principal of the message sender\n- `ingressExpiry: Expiry` - When the message expires\n- `nonce?: Uint8Array` - Optional nonce for replay protection\n- `ingressMaxAgeMs: number` - The maximum age of the message in milliseconds\n\n#### Methods\n\n- `withCanisterId(canisterId: Principal): Message` - Sets the canister ID\n- `withMethodName(methodName: string): Message` - Sets the method name\n- `withArgs(argTypes: IDL.Type[], args: unknown[]): Message` - Sets and encodes the arguments as Candid\n- `withIngressMaxAge(maxAgeMs: number): Message` - Sets how long the message is valid\n- `withNonce(nonce: Uint8Array): Message` - Sets a nonce for the message\n- `toCallRequest(): CallRequest` - Converts to a CallRequest for signing\n\n### Delegation Interface\n\n```typescript\ninterface Delegation {\n  pubkey: Uint8Array; // Public key of the delegatee\n  expiration_ns: bigint; // Expiration in nanoseconds since epoch\n  targets?: Principal[]; // Optional target canisters for the delegation\n}\n```\n\n### SignedDelegation Interface\n\n```typescript\ninterface SignedDelegation {\n  delegation: Delegation; // The delegation details\n  signature: Uint8Array; // Signature from the delegator\n}\n```\n\n### Signature\n\nThe `Signature` class represents a signature that can be sent to a service for authentication.\n\n#### Constructor\n\n```typescript\nconstructor(\n  sig?: Uint8Array,\n  publicKey?: Uint8Array,\n  ingressExpiry: Expiry = new Expiry(120_000),\n  sender: Principal = Principal.anonymous(),\n  delegations?: SignedDelegation[]\n)\n```\n\n#### Properties\n\n- `sig?: Uint8Array` - The signature bytes\n- `public_key?: Uint8Array` - The public key bytes of the signer\n- `ingress_expiry: Expiry` - When the signature expires\n- `delegations?: SignedDelegation[]` - Optional delegations for delegation signing\n- `sender: Principal` - The Principal of the signer\n\n#### Methods\n\n- `static fromAgentSignature(signature: AgentSignature, ingressExpiry: Expiry, sender: Principal): Signature` - Converts from agent signature format\n- `serializeJSON(): string` - Converts the signature to a JSON string suitable for interoperability with Rust services\n\n### signMessage Function\n\n```typescript\nasync function signMessage(\n  identity: DelegationIdentity | SignIdentity,\n  message: Message,\n): Promise<Signature>;\n```\n\nSigns a message using the provided identity. This function:\n\n1. Sets the sender in the message to the identity's principal\n2. Creates a CallRequest from the message\n3. Calculates the request ID\n4. Signs the request ID using the provided identity\n5. Extracts the signature and public key\n6. Creates and returns a Signature object\n\n## JSON Serialization\n\nThe `Signature` class includes a `serializeJSON()` method that ensures proper serialization of all properties including `Uint8Array` objects, which are converted to standard arrays. This is crucial for compatibility with the Rust implementation.\n\nWhen using the `serializeJSON()` method on a `Signature` instance, the result will be properly formatted for use with yral-identity Rust services:\n\n```json\n{\n  \"sig\": [1, 2, 3, ...],\n  \"public_key\": [4, 5, 6, ...],\n  \"ingress_expiry\": {\n    \"secs\": 120,\n    \"nanos\": 0\n  },\n  \"delegations\": [\n    {\n      \"delegation\": {\n        \"pubkey\": [7, 8, 9, ...],\n        \"expiration_ns\": 3600000000000,\n        \"targets\": [\"aaaaa-aa\"]\n      },\n      \"signature\": [10, 11, 12, ...]\n    }\n  ],\n  \"sender\": \"rrkah-fqaaa-aaaaa-aaaaq-cai\"\n}\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-7e6f7c0ed22c8f5ca9430c38c7d1c3dc"}