@totemsdk/identity 0.1.0 → 0.1.1

package/src/claims.ts

@@ -1,108 +0,0 @@
-/**
- * Claim creation helpers.
- *
- * Claim IDs are deterministic: SHA3-256 of claim fields + canonical payload hash.
- */
-
-import { sha3_256 } from '@noble/hashes/sha3.js';
-import { canonicalJson, toHex } from './canonical.js';
-import type { IdentityClaim, IdentityClaimType } from './types.js';
-
-function computeClaimId(
-  type: IdentityClaimType,
-  issuer: string,
-  subject: string,
-  object: string,
-  issuedAt: number,
-  payload: Record<string, unknown>,
-): string {
-  const canonical = canonicalJson({ type, issuer, subject, object, issuedAt, payload });
-  const hash = sha3_256(new TextEncoder().encode(canonical));
-  return toHex(hash);
-}
-
-export function createIdentityClaim(opts: {
-  type: IdentityClaimType;
-  issuer: string;
-  subject: string;
-  object: string;
-  payload: Record<string, unknown>;
-  issuedAt?: number;
-  expiresAt?: number;
-}): IdentityClaim {
-  const { type, issuer, subject, object, payload, expiresAt } = opts;
-  const issuedAt = opts.issuedAt ?? Date.now();
-  const id = computeClaimId(type, issuer, subject, object, issuedAt, payload);
-  return {
-    id,
-    type,
-    issuer,
-    subject,
-    object,
-    issuedAt,
-    ...(expiresAt !== undefined ? { expiresAt } : {}),
-    payload,
-  };
-}
-
-export function createDelegationClaim(opts: {
-  issuer: string;
-  subject: string;
-  delegatedAddress: string;
-  scopes: string[];
-  issuedAt?: number;
-  expiresAt?: number;
-}): IdentityClaim {
-  const { issuer, subject, delegatedAddress, scopes, expiresAt } = opts;
-  return createIdentityClaim({
-    type: 'delegates_to',
-    issuer,
-    subject,
-    object: delegatedAddress,
-    payload: { scopes },
-    issuedAt: opts.issuedAt,
-    expiresAt,
-  });
-}
-
-export function createPaymentRecipientClaim(opts: {
-  issuer: string;
-  subject: string;
-  address: string;
-  label?: string;
-  issuedAt?: number;
-  expiresAt?: number;
-}): IdentityClaim {
-  const { issuer, subject, address, label, expiresAt } = opts;
-  const payload: Record<string, unknown> = {};
-  if (label !== undefined) payload.label = label;
-  return createIdentityClaim({
-    type: 'payment_recipient',
-    issuer,
-    subject,
-    object: address,
-    payload,
-    issuedAt: opts.issuedAt,
-    expiresAt,
-  });
-}
-
-export function createServiceEndpointClaim(opts: {
-  issuer: string;
-  subject: string;
-  endpointType: string;
-  uri: string;
-  issuedAt?: number;
-  expiresAt?: number;
-}): IdentityClaim {
-  const { issuer, subject, endpointType, uri, expiresAt } = opts;
-  return createIdentityClaim({
-    type: 'service_endpoint',
-    issuer,
-    subject,
-    object: uri,
-    payload: { endpointType },
-    issuedAt: opts.issuedAt,
-    expiresAt,
-  });
-}

package/src/constants.ts

@@ -1 +0,0 @@
-export const IDENTITY_VERSION = 1 as const;

package/src/document.ts

@@ -1,35 +0,0 @@
-/**
- * Identity document creation and ID computation.
- *
- * computeIdentityId: deterministic SHA3-256 of "totem-identity" + kind + rootAddress.
- * Version is NOT part of the ID hash — schema version upgrades must not change the identity ID.
- */
-
-import { sha3_256 } from '@noble/hashes/sha3.js';
-import { IDENTITY_VERSION } from './constants.js';
-import { toHex } from './canonical.js';
-import type { IdentityKind, TotemIdentityDocument } from './types.js';
-
-export function computeIdentityId(kind: IdentityKind, rootAddress: string): string {
-  const input = `totem-identity\0${kind}\0${rootAddress}`;
-  const hash = sha3_256(new TextEncoder().encode(input));
-  return `totem:id:${kind}:${toHex(hash)}`;
-}
-
-export function createIdentityDocument(opts: {
-  kind: IdentityKind;
-  rootAddress: string;
-  controllerAddress: string;
-  metadata?: Record<string, unknown>;
-}): TotemIdentityDocument {
-  const { kind, rootAddress, controllerAddress, metadata } = opts;
-  return {
-    id: computeIdentityId(kind, rootAddress),
-    kind,
-    version: IDENTITY_VERSION,
-    rootAddress,
-    controllerAddress,
-    createdAt: Date.now(),
-    ...(metadata !== undefined ? { metadata } : {}),
-  };
-}

package/src/guards.ts

@@ -1,75 +0,0 @@
-/**
- * Type guards for identity types.
- */
-
-import type {
-  TotemIdentityDocument,
-  IdentityClaim,
-  SignedIdentityClaim,
-  RotationClaim,
-  RevocationClaim,
-} from './types.js';
-
-export function isTotemIdentityDocument(value: unknown): value is TotemIdentityDocument {
-  if (!value || typeof value !== 'object') return false;
-  const v = value as Record<string, unknown>;
-  return (
-    typeof v.id === 'string' &&
-    typeof v.kind === 'string' &&
-    typeof v.version === 'number' &&
-    typeof v.rootAddress === 'string' &&
-    typeof v.controllerAddress === 'string' &&
-    typeof v.createdAt === 'number'
-  );
-}
-
-export function isIdentityClaim(value: unknown): value is IdentityClaim {
-  if (!value || typeof value !== 'object') return false;
-  const v = value as Record<string, unknown>;
-  return (
-    typeof v.id === 'string' &&
-    typeof v.type === 'string' &&
-    typeof v.issuer === 'string' &&
-    typeof v.subject === 'string' &&
-    typeof v.object === 'string' &&
-    typeof v.issuedAt === 'number' &&
-    typeof v.payload === 'object' &&
-    v.payload !== null
-  );
-}
-
-export function isSignedIdentityClaim(value: unknown): value is SignedIdentityClaim {
-  if (!value || typeof value !== 'object') return false;
-  const v = value as Record<string, unknown>;
-  if (!isIdentityClaim(v.claim)) return false;
-  if (!v.proof || typeof v.proof !== 'object') return false;
-  const p = v.proof as Record<string, unknown>;
-  return (
-    typeof p.address === 'string' &&
-    typeof p.publicKey === 'string' &&
-    typeof p.signature === 'string'
-  );
-}
-
-export function isRotationClaim(value: unknown): value is RotationClaim {
-  if (!value || typeof value !== 'object') return false;
-  const v = value as Record<string, unknown>;
-  return (
-    typeof v.claimId === 'string' &&
-    typeof v.issuer === 'string' &&
-    typeof v.subject === 'string' &&
-    typeof v.newAddress === 'string' &&
-    typeof v.issuedAt === 'number'
-  );
-}
-
-export function isRevocationClaim(value: unknown): value is RevocationClaim {
-  if (!value || typeof value !== 'object') return false;
-  const v = value as Record<string, unknown>;
-  return (
-    typeof v.claimId === 'string' &&
-    typeof v.issuer === 'string' &&
-    typeof v.subject === 'string' &&
-    typeof v.issuedAt === 'number'
-  );
-}

package/src/index.ts

@@ -1,55 +0,0 @@
-/**
- * @module @totemsdk/identity
- *
- * Canonical identity and claims layer for Totem Edge.
- * Pure package — no network, no DHT, no blockchain submission.
- */
-
-export { IDENTITY_VERSION } from './constants.js';
-
-export type {
-  IdentityKind,
-  IdentityStatus,
-  TotemIdentityDocument,
-  IdentityClaim,
-  IdentityClaimType,
-  SignedIdentityClaim,
-  IdentityVerifyResult,
-  IdentityProofVerifier,
-  IdentityGraph,
-  ResolvedIdentity,
-  IdentityResolutionResult,
-  DelegationClaim,
-  PaymentRecipientClaim,
-  ServiceEndpointClaim,
-  RotationClaim,
-  RevocationClaim,
-  ManifestIdentityBinding,
-} from './types.js';
-
-export { computeIdentityId, createIdentityDocument } from './document.js';
-
-export {
-  createIdentityClaim,
-  createDelegationClaim,
-  createPaymentRecipientClaim,
-  createServiceEndpointClaim,
-} from './claims.js';
-
-export { signIdentityClaim } from './signing.js';
-export { verifyIdentityClaim } from './verify.js';
-
-export { rotateIdentity } from './rotation.js';
-export { revokeIdentity } from './revocation.js';
-
-export { resolveIdentityGraph } from './resolver.js';
-
-export { bindManifestToIdentity, verifyManifestIdentity } from './manifest-binding.js';
-
-export {
-  isTotemIdentityDocument,
-  isIdentityClaim,
-  isSignedIdentityClaim,
-  isRotationClaim,
-  isRevocationClaim,
-} from './guards.js';

package/src/manifest-binding.ts

@@ -1,163 +0,0 @@
-/**
- * Manifest identity binding.
- *
- * bindManifestToIdentity: verify a signed manifest against an identity graph.
- * verifyManifestIdentity: core verification logic.
- *
- * Security model for valid signer addresses:
- *   A manifest signer is authorized if the signing address is one of:
- *   1. The identity's rootAddress
- *   2. The identity's controllerAddress
- *   3. An address in authorizedAddresses (delegates with "manifest:sign" or "*" scope)
- *   4. An address in result.provenAddresses returned by the root-identity proof verifier
- *
- * Note: controlledAddresses (delegates with any scope) are NOT included in the
- * manifest-signing valid set. Only explicitly scoped manifest signers may bind.
- *
- * Verification order:
- *   1. verifyManifest (manifest signature must be valid)
- *   2. resolveIdentityGraph (traverse graph)
- *   3. Optional root-identity proof verifier hooks
- *   4. Address membership check
- *   5. Identity status check (revoked = invalid)
- */
-
-import { verifyManifest, computeManifestId } from '@totemsdk/manifest';
-import type { SignedManifest } from '@totemsdk/manifest';
-import { resolveIdentityGraph } from './resolver.js';
-import type {
-  IdentityGraph,
-  ManifestIdentityBinding,
-  IdentityProofVerifier,
-} from './types.js';
-
-export async function verifyManifestIdentity(
-  signedManifest: SignedManifest<any>,
-  identityGraph: IdentityGraph,
-  options?: {
-    proofVerifiers?: Record<string, IdentityProofVerifier>;
-  },
-): Promise<ManifestIdentityBinding> {
-  const proofVerifiers = options?.proofVerifiers ?? {};
-  const manifestId = computeManifestId(signedManifest.manifest);
-
-  // Step 1: verify manifest signature first — fail fast on invalid manifest
-  const manifestVerifyResult = verifyManifest(signedManifest);
-  if (!manifestVerifyResult.valid) {
-    return {
-      valid: false,
-      reason: `manifest signature invalid: ${manifestVerifyResult.reason ?? 'unknown'}`,
-      manifestId,
-      identityId: identityGraph.document.id,
-      signerAddress: signedManifest.authorAddress,
-      resolvedStatus: 'active',
-    };
-  }
-
-  // Step 2: resolve identity graph (includes claim signature verification)
-  const resolution = resolveIdentityGraph(identityGraph);
-  if (!resolution.resolved) {
-    return {
-      valid: false,
-      reason: 'identity graph could not be resolved',
-      manifestId,
-      identityId: identityGraph.document.id,
-      signerAddress: signedManifest.authorAddress,
-      resolvedStatus: 'active',
-    };
-  }
-
-  const resolved = resolution.resolved;
-
-  // Step 3: collect additional proven addresses from proof verifiers
-  const provenAddresses: string[] = [];
-
-  // Check manifest-level rootIdentityProof
-  if (signedManifest.rootIdentityProof && proofVerifiers['root-identity']) {
-    try {
-      const verifyResult = await proofVerifiers['root-identity'].verify(
-        signedManifest.rootIdentityProof,
-      );
-      if (verifyResult.valid && verifyResult.provenAddresses) {
-        provenAddresses.push(...verifyResult.provenAddresses);
-      }
-    } catch {
-      // silently ignore verifier errors
-    }
-  }
-
-  // Check claim-level rootIdentityProof fields
-  if (proofVerifiers['root-identity']) {
-    for (const sc of identityGraph.claims) {
-      if (sc.rootIdentityProof) {
-        try {
-          const verifyResult = await proofVerifiers['root-identity'].verify(
-            sc.rootIdentityProof,
-          );
-          if (verifyResult.valid && verifyResult.provenAddresses) {
-            provenAddresses.push(...verifyResult.provenAddresses);
-          }
-        } catch {
-          // silently ignore verifier errors
-        }
-      }
-    }
-  }
-
-  // Step 4: check address validity
-  // Valid signers (per spec):
-  //   1. rootAddress
-  //   2. controllerAddress
-  //   3. controlledAddresses — all delegated addresses (any scope)
-  //   4. authorizedAddresses — subset with "manifest:sign" or "*" scope (already subset of above)
-  //   5. provenAddresses — from root-identity proof verifiers
-  const signerAddress = signedManifest.authorAddress;
-  const validAddresses = new Set<string>([
-    resolved.rootAddress,
-    resolved.controllerAddress,
-    ...resolved.controlledAddresses,
-    ...resolved.authorizedAddresses,
-    ...provenAddresses,
-  ]);
-
-  if (!validAddresses.has(signerAddress)) {
-    return {
-      valid: false,
-      reason: `signer address '${signerAddress}' is not authorized to sign manifests for identity '${identityGraph.document.id}'`,
-      manifestId,
-      identityId: identityGraph.document.id,
-      signerAddress,
-      resolvedStatus: resolved.status,
-    };
-  }
-
-  // Step 5: check identity status — revoked identities cannot bind
-  if (resolved.status === 'revoked') {
-    return {
-      valid: false,
-      reason: 'identity has been revoked',
-      manifestId,
-      identityId: identityGraph.document.id,
-      signerAddress,
-      resolvedStatus: resolved.status,
-    };
-  }
-
-  return {
-    valid: true,
-    manifestId,
-    identityId: identityGraph.document.id,
-    signerAddress,
-    resolvedStatus: resolved.status,
-  };
-}
-
-export async function bindManifestToIdentity(
-  signedManifest: SignedManifest<any>,
-  identityGraph: IdentityGraph,
-  options?: {
-    proofVerifiers?: Record<string, IdentityProofVerifier>;
-  },
-): Promise<ManifestIdentityBinding> {
-  return verifyManifestIdentity(signedManifest, identityGraph, options);
-}

package/src/resolver.ts

@@ -1,171 +0,0 @@
-/**
- * Local-only identity graph resolver.
- *
- * Resolves an IdentityGraph into a ResolvedIdentity by:
- * - Verifying each claim's signature before accepting it
- * - Enforcing claim authority (only root, controller, or delegated addresses may issue)
- * - Detecting rotation/revocation
- * - Collecting payment recipients, service endpoints, delegations
- *
- * Security: every SignedIdentityClaim is passed through verifyIdentityClaim before
- * its issuer or content is trusted. Unsigned or tampered claims are silently dropped.
- *
- * Claim authority rules (after signature verification):
- *   A claim is only accepted if its issuer is:
- *     1. The subject's rootAddress
- *     2. The subject's controllerAddress
- *     3. An address holding an active + signature-verified delegates_to claim from the subject
- *   Claims from unauthorized issuers are silently dropped.
- */
-
-import { verifyIdentityClaim } from './verify.js';
-import type {
-  IdentityGraph,
-  IdentityResolutionResult,
-  ResolvedIdentity,
-  IdentityStatus,
-  DelegationClaim,
-  PaymentRecipientClaim,
-  ServiceEndpointClaim,
-  SignedIdentityClaim,
-} from './types.js';
-
-function isExpired(claim: { expiresAt?: number }): boolean {
-  if (claim.expiresAt === undefined) return false;
-  return Date.now() > claim.expiresAt;
-}
-
-export function resolveIdentityGraph(graph: IdentityGraph): IdentityResolutionResult {
-  const { document, claims } = graph;
-  const { rootAddress, controllerAddress } = document;
-
-  // Step 1: signature-verify all claims upfront and collect the valid ones.
-  // A claim is ONLY trusted when:
-  //   (a) the WOTS signature is valid over the canonical claim bytes, AND
-  //   (b) the cryptographic signer address (proof.address, bound to proof.publicKey via key
-  //       derivation) exactly matches claim.issuer.
-  // This prevents issuer-field spoofing: an attacker cannot set claim.issuer to a privileged
-  // address (root, controller, delegate) if they signed with their own key.
-  const verifiedClaims = claims.filter((sc) => {
-    const result = verifyIdentityClaim(sc);
-    return result.valid && result.signerAddress === sc.claim.issuer;
-  });
-
-  // Step 2: collect delegation claims issued by root or controller only (first-level authority).
-  const rootDelegations = verifiedClaims.filter(
-    (sc) =>
-      sc.claim.type === 'delegates_to' &&
-      sc.claim.subject === document.id &&
-      (sc.claim.issuer === rootAddress || sc.claim.issuer === controllerAddress) &&
-      !isExpired(sc.claim),
-  );
-  const firstLevelDelegates = new Set<string>(rootDelegations.map((sc) => sc.claim.object));
-
-  // Full authorized issuer set
-  const allAuthorized = new Set<string>([rootAddress, controllerAddress, ...firstLevelDelegates]);
-
-  // Helper: claim is authorized if its issuer is in the authorized set and targets this identity
-  function isAuthorized(sc: SignedIdentityClaim): boolean {
-    return allAuthorized.has(sc.claim.issuer) && sc.claim.subject === document.id;
-  }
-
-  // Detect revocation
-  const revocationClaims = verifiedClaims.filter(
-    (sc) => sc.claim.type === 'revokes' && isAuthorized(sc),
-  );
-  const isRevoked = revocationClaims.length > 0;
-  const revokedAt = isRevoked
-    ? Math.min(...revocationClaims.map((sc) => sc.claim.issuedAt))
-    : undefined;
-
-  // Detect rotation
-  const rotationClaims = verifiedClaims.filter(
-    (sc) => sc.claim.type === 'rotates_to' && isAuthorized(sc) && !isExpired(sc.claim),
-  );
-  const rotationTarget = rotationClaims.length > 0 ? rotationClaims[0].claim.object : undefined;
-
-  let status: IdentityStatus = 'active';
-  if (isRevoked) status = 'revoked';
-  else if (rotationTarget !== undefined) status = 'rotated';
-
-  // Collect all delegation claims from authorized issuers
-  const allDelegationSignedClaims = verifiedClaims.filter(
-    (sc) =>
-      sc.claim.type === 'delegates_to' &&
-      sc.claim.subject === document.id &&
-      allAuthorized.has(sc.claim.issuer) &&
-      !isExpired(sc.claim),
-  );
-
-  const delegates: DelegationClaim[] = allDelegationSignedClaims.map((sc) => ({
-    claimId: sc.claim.id,
-    issuer: sc.claim.issuer,
-    subject: sc.claim.subject,
-    delegatedAddress: sc.claim.object,
-    scopes: Array.isArray(sc.claim.payload.scopes) ? (sc.claim.payload.scopes as string[]) : [],
-    issuedAt: sc.claim.issuedAt,
-    expiresAt: sc.claim.expiresAt,
-  }));
-
-  // controlledAddresses: all delegated addresses (any scope) — for informational use
-  const controlledAddresses: string[] = [...new Set(delegates.map((d) => d.delegatedAddress))];
-
-  // authorizedAddresses: only delegates with manifest:sign or * scope
-  const authorizedAddresses: string[] = [
-    ...new Set(
-      delegates
-        .filter((d) => d.scopes.includes('*') || d.scopes.includes('manifest:sign'))
-        .map((d) => d.delegatedAddress),
-    ),
-  ];
-
-  // Payment recipients
-  const paymentRecipients: PaymentRecipientClaim[] = verifiedClaims
-    .filter(
-      (sc) =>
-        sc.claim.type === 'payment_recipient' &&
-        isAuthorized(sc) &&
-        !isExpired(sc.claim),
-    )
-    .map((sc) => ({
-      claimId: sc.claim.id,
-      issuer: sc.claim.issuer,
-      address: sc.claim.object,
-      label: typeof sc.claim.payload.label === 'string' ? sc.claim.payload.label : undefined,
-      issuedAt: sc.claim.issuedAt,
-      expiresAt: sc.claim.expiresAt,
-    }));
-
-  // Service endpoints
-  const serviceEndpoints: ServiceEndpointClaim[] = verifiedClaims
-    .filter(
-      (sc) =>
-        sc.claim.type === 'service_endpoint' &&
-        isAuthorized(sc) &&
-        !isExpired(sc.claim),
-    )
-    .map((sc) => ({
-      claimId: sc.claim.id,
-      issuer: sc.claim.issuer,
-      endpointType: typeof sc.claim.payload.endpointType === 'string' ? sc.claim.payload.endpointType : 'unknown',
-      uri: sc.claim.object,
-      issuedAt: sc.claim.issuedAt,
-      expiresAt: sc.claim.expiresAt,
-    }));
-
-  const resolved: ResolvedIdentity = {
-    document,
-    status,
-    rootAddress,
-    controllerAddress,
-    controlledAddresses,
-    authorizedAddresses,
-    delegates,
-    paymentRecipients,
-    serviceEndpoints,
-    rotationTarget,
-    revokedAt,
-  };
-
-  return { resolved, errors: [] };
-}

package/src/revocation.ts

@@ -1,25 +0,0 @@
-/**
- * Identity revocation — produces a RevocationClaim.
- */
-
-import { createIdentityClaim } from './claims.js';
-import type { IdentityClaim } from './types.js';
-
-export function revokeIdentity(opts: {
-  issuer: string;
-  subject: string;
-  reason?: string;
-  issuedAt?: number;
-}): IdentityClaim {
-  const { issuer, subject, reason } = opts;
-  const payload: Record<string, unknown> = {};
-  if (reason !== undefined) payload.reason = reason;
-  return createIdentityClaim({
-    type: 'revokes',
-    issuer,
-    subject,
-    object: subject,
-    payload,
-    issuedAt: opts.issuedAt,
-  });
-}

package/src/rotation.ts

@@ -1,23 +0,0 @@
-/**
- * Identity rotation — produces a RotationClaim.
- */
-
-import { createIdentityClaim } from './claims.js';
-import type { IdentityClaim } from './types.js';
-
-export function rotateIdentity(opts: {
-  issuer: string;
-  subject: string;
-  newAddress: string;
-  issuedAt?: number;
-}): IdentityClaim {
-  const { issuer, subject, newAddress } = opts;
-  return createIdentityClaim({
-    type: 'rotates_to',
-    issuer,
-    subject,
-    object: newAddress,
-    payload: {},
-    issuedAt: opts.issuedAt,
-  });
-}

package/src/signing.ts

@@ -1,38 +0,0 @@
-/**
- * Claim signing using WOTS primitives from @totemsdk/core.
- */
-
-import { sha3_256 } from '@noble/hashes/sha3.js';
-import {
-  wotsSign,
-  wotsKeypairFromSeed,
-  wotsAddressFromKeypair,
-  bytesToHex,
-} from '@totemsdk/core';
-import { canonicalJson } from './canonical.js';
-import type { IdentityClaim, SignedIdentityClaim } from './types.js';
-
-export function claimDigest(claim: IdentityClaim): Uint8Array {
-  const canonical = canonicalJson(claim);
-  return sha3_256(new TextEncoder().encode(canonical));
-}
-
-export async function signIdentityClaim(
-  claim: IdentityClaim,
-  seed: Uint8Array,
-  keyIndex: number,
-): Promise<SignedIdentityClaim> {
-  const digest = claimDigest(claim);
-  const sigBytes = wotsSign(seed, keyIndex, digest);
-  const kp = wotsKeypairFromSeed(seed, keyIndex);
-  const address = wotsAddressFromKeypair(kp);
-
-  return {
-    claim,
-    proof: {
-      address,
-      publicKey: bytesToHex(kp.pk),
-      signature: bytesToHex(sigBytes),
-    },
-  };
-}