@rare-id/platform-kit-web 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import { RareApiClient } from '@rare-id/platform-kit-client';
+import { IdentityLevel, RarePlatformEventItem, KeyResolver } from '@rare-id/platform-kit-core';
+
+type IdentityMode = "public" | "full";
+type EffectiveLevel = "L0" | "L1" | "L2";
+interface AuthChallenge {
+    nonce: string;
+    aud: string;
+    issuedAt: number;
+    expiresAt: number;
+}
+interface PlatformSession {
+    sessionToken: string;
+    agentId: string;
+    sessionPubkey: string;
+    identityMode: IdentityMode;
+    rawLevel: IdentityLevel;
+    effectiveLevel: EffectiveLevel;
+    displayName: string;
+    aud: string;
+    createdAt: number;
+    expiresAt: number;
+}
+interface AuthCompleteInput {
+    nonce: string;
+    agentId: string;
+    sessionPubkey: string;
+    delegationToken: string;
+    signatureBySession: string;
+    publicIdentityAttestation?: string;
+    fullIdentityAttestation?: string;
+}
+interface AuthCompleteResult {
+    session_token: string;
+    agent_id: string;
+    level: EffectiveLevel;
+    raw_level: IdentityLevel;
+    identity_mode: IdentityMode;
+    display_name: string;
+    session_pubkey: string;
+}
+interface VerifyActionInput {
+    sessionToken: string;
+    action: string;
+    actionPayload: Record<string, unknown>;
+    nonce: string;
+    issuedAt: number;
+    expiresAt: number;
+    signatureBySession: string;
+}
+interface VerifiedActionContext {
+    session: PlatformSession;
+    action: string;
+    actionPayload: Record<string, unknown>;
+}
+interface IngestEventsInput {
+    eventToken?: string;
+    platformId?: string;
+    kid?: string;
+    privateKeyPem?: string;
+    jti?: string;
+    events?: RarePlatformEventItem[];
+    issuedAt?: number;
+    expiresAt?: number;
+}
+interface IngestEventsResult {
+    eventToken: string;
+    response: Record<string, unknown>;
+}
+interface ChallengeStore {
+    set(challenge: AuthChallenge): Promise<void>;
+    consume(nonce: string): Promise<AuthChallenge | null>;
+}
+interface ReplayStore {
+    has(key: string): Promise<boolean>;
+    put(key: string, expiresAt: number): Promise<void>;
+}
+interface SessionStore {
+    save(session: PlatformSession): Promise<void>;
+    get(sessionToken: string): Promise<PlatformSession | null>;
+}
+interface RarePlatformKit {
+    issueChallenge(aud?: string): Promise<AuthChallenge>;
+    completeAuth(input: AuthCompleteInput): Promise<AuthCompleteResult>;
+    verifyAction(input: VerifyActionInput): Promise<VerifiedActionContext>;
+    ingestNegativeEvents(input: IngestEventsInput): Promise<IngestEventsResult>;
+}
+interface RarePlatformKitConfig {
+    aud: string;
+    challengeStore: ChallengeStore;
+    replayStore: ReplayStore;
+    sessionStore: SessionStore;
+    rareApiClient?: RareApiClient;
+    keyResolver?: KeyResolver;
+    initialJwks?: {
+        issuer?: string;
+        keys?: Array<Record<string, unknown>>;
+    };
+    rareSignerPublicKeyB64?: string;
+    challengeTtlSeconds?: number;
+    sessionTtlSeconds?: number;
+    maxSignedTtlSeconds?: number;
+    clockSkewSeconds?: number;
+}
+declare function createRarePlatformKit(config: RarePlatformKitConfig): RarePlatformKit;
+declare class InMemoryChallengeStore implements ChallengeStore {
+    private readonly challenges;
+    set(challenge: AuthChallenge): Promise<void>;
+    consume(nonce: string): Promise<AuthChallenge | null>;
+}
+declare class InMemoryReplayStore implements ReplayStore {
+    private readonly seen;
+    has(key: string): Promise<boolean>;
+    put(key: string, expiresAt: number): Promise<void>;
+    private cleanup;
+}
+declare class InMemorySessionStore implements SessionStore {
+    private readonly sessions;
+    save(session: PlatformSession): Promise<void>;
+    get(sessionToken: string): Promise<PlatformSession | null>;
+}
+
+export { type AuthChallenge, type AuthCompleteInput, type AuthCompleteResult, type ChallengeStore, type EffectiveLevel, type IdentityMode, InMemoryChallengeStore, InMemoryReplayStore, InMemorySessionStore, type IngestEventsInput, type IngestEventsResult, type PlatformSession, type RarePlatformKit, type RarePlatformKitConfig, type ReplayStore, type SessionStore, type VerifiedActionContext, type VerifyActionInput, createRarePlatformKit };

package/dist/index.js

@@ -0,0 +1,296 @@
+// src/index.ts
+import {
+  buildActionPayload,
+  buildAuthChallengePayload,
+  generateNonce,
+  nowTs,
+  parseRareJwks,
+  signPlatformEventToken,
+  verifyDelegationToken,
+  verifyDetached,
+  verifyIdentityAttestation
+} from "@rare-id/platform-kit-core";
+function createRarePlatformKit(config) {
+  const challengeTtlSeconds = config.challengeTtlSeconds ?? 120;
+  const sessionTtlSeconds = config.sessionTtlSeconds ?? 3600;
+  const maxSignedTtlSeconds = config.maxSignedTtlSeconds ?? 300;
+  const clockSkewSeconds = config.clockSkewSeconds ?? 30;
+  const keyCache = config.initialJwks ? parseRareJwks(config.initialJwks) : {};
+  const resolveIdentityKey = async (kid) => {
+    if (config.keyResolver) {
+      return config.keyResolver(kid);
+    }
+    const existing = keyCache[kid];
+    if (existing) {
+      return existing;
+    }
+    if (!config.rareApiClient) {
+      return null;
+    }
+    const jwks = await config.rareApiClient.getJwks();
+    Object.assign(keyCache, parseRareJwks(jwks));
+    return keyCache[kid] ?? null;
+  };
+  return {
+    async issueChallenge(aud) {
+      const now = nowTs();
+      const challenge = {
+        nonce: generateNonce(18),
+        aud: aud ?? config.aud,
+        issuedAt: now,
+        expiresAt: now + challengeTtlSeconds
+      };
+      await config.challengeStore.set(challenge);
+      return challenge;
+    },
+    async completeAuth(input) {
+      const challenge = await config.challengeStore.consume(input.nonce);
+      if (!challenge) {
+        throw new Error("unknown challenge nonce");
+      }
+      const now = nowTs();
+      if (challenge.expiresAt < now - clockSkewSeconds) {
+        throw new Error("challenge expired");
+      }
+      const authPayload = buildAuthChallengePayload({
+        aud: challenge.aud,
+        nonce: challenge.nonce,
+        issuedAt: challenge.issuedAt,
+        expiresAt: challenge.expiresAt
+      });
+      if (!verifyDetached(
+        authPayload,
+        input.signatureBySession,
+        input.sessionPubkey
+      )) {
+        throw new Error("invalid session challenge signature");
+      }
+      const delegation = await verifyDelegationToken(input.delegationToken, {
+        expectedAud: config.aud,
+        requiredScope: "login",
+        rareSignerPublicKeyB64: config.rareSignerPublicKeyB64,
+        currentTs: now,
+        clockSkewSeconds
+      });
+      const delegationPayload = delegation.payload;
+      const delegatedSessionPubkey = delegationPayload.session_pubkey;
+      if (delegatedSessionPubkey !== input.sessionPubkey) {
+        throw new Error("session pubkey mismatch");
+      }
+      let identityMode = null;
+      let identityPayload = null;
+      if (input.fullIdentityAttestation) {
+        try {
+          const fullVerified = await verifyIdentityAttestation(
+            input.fullIdentityAttestation,
+            {
+              keyResolver: resolveIdentityKey,
+              expectedAud: config.aud,
+              currentTs: now,
+              clockSkewSeconds
+            }
+          );
+          identityMode = "full";
+          identityPayload = fullVerified.payload;
+        } catch {
+        }
+      }
+      if (!identityPayload && input.publicIdentityAttestation) {
+        const publicVerified = await verifyIdentityAttestation(
+          input.publicIdentityAttestation,
+          {
+            keyResolver: resolveIdentityKey,
+            currentTs: now,
+            clockSkewSeconds
+          }
+        );
+        identityMode = "public";
+        identityPayload = publicVerified.payload;
+      }
+      if (!identityPayload || !identityMode) {
+        throw new Error("missing identity attestation");
+      }
+      const delegatedAgent = delegationPayload.agent_id;
+      const identitySub = identityPayload.sub;
+      if (input.agentId !== delegatedAgent || input.agentId !== identitySub) {
+        throw new Error("agent identity triad mismatch");
+      }
+      const jti = delegationPayload.jti;
+      const exp = delegationPayload.exp;
+      if (typeof jti !== "string" || typeof exp !== "number") {
+        throw new Error("delegation replay fields missing");
+      }
+      const delegationReplayKey = `delegation:${jti}`;
+      if (await config.replayStore.has(delegationReplayKey)) {
+        throw new Error("delegation token replay detected");
+      }
+      await config.replayStore.put(delegationReplayKey, exp);
+      const rawLevel = identityPayload.lvl;
+      if (rawLevel !== "L0" && rawLevel !== "L1" && rawLevel !== "L2") {
+        throw new Error("unsupported identity level");
+      }
+      const effectiveLevel = identityMode === "public" && rawLevel === "L2" ? "L1" : rawLevel;
+      let displayName = "unknown";
+      const claims = identityPayload.claims;
+      if (claims && typeof claims === "object") {
+        const profile = claims.profile;
+        if (profile && typeof profile === "object") {
+          const maybeName = profile.name;
+          if (typeof maybeName === "string" && maybeName.trim()) {
+            displayName = maybeName;
+          }
+        }
+      }
+      const sessionToken = generateNonce(24);
+      const session = {
+        sessionToken,
+        agentId: input.agentId,
+        sessionPubkey: input.sessionPubkey,
+        identityMode,
+        rawLevel,
+        effectiveLevel,
+        displayName,
+        aud: config.aud,
+        createdAt: now,
+        expiresAt: now + sessionTtlSeconds
+      };
+      await config.sessionStore.save(session);
+      return {
+        session_token: session.sessionToken,
+        agent_id: session.agentId,
+        level: session.effectiveLevel,
+        raw_level: session.rawLevel,
+        identity_mode: session.identityMode,
+        display_name: session.displayName,
+        session_pubkey: session.sessionPubkey
+      };
+    },
+    async verifyAction(input) {
+      const session = await config.sessionStore.get(input.sessionToken);
+      if (!session) {
+        throw new Error("invalid session token");
+      }
+      const now = nowTs();
+      if (session.expiresAt < now) {
+        throw new Error("session expired");
+      }
+      if (input.issuedAt > now + clockSkewSeconds) {
+        throw new Error("action issued_at too far in future");
+      }
+      if (input.expiresAt < now - clockSkewSeconds) {
+        throw new Error("action expired");
+      }
+      if (input.expiresAt <= input.issuedAt) {
+        throw new Error("action expires_at must be greater than issued_at");
+      }
+      if (input.expiresAt - input.issuedAt > maxSignedTtlSeconds) {
+        throw new Error(
+          `action ttl exceeds max ${maxSignedTtlSeconds} seconds`
+        );
+      }
+      const replayKey = `action:${session.sessionToken}:${input.nonce}`;
+      if (await config.replayStore.has(replayKey)) {
+        throw new Error("action nonce already consumed");
+      }
+      await config.replayStore.put(replayKey, input.expiresAt);
+      const signingInput = buildActionPayload({
+        aud: config.aud,
+        sessionToken: session.sessionToken,
+        action: input.action,
+        actionPayload: input.actionPayload,
+        nonce: input.nonce,
+        issuedAt: input.issuedAt,
+        expiresAt: input.expiresAt
+      });
+      if (!verifyDetached(
+        signingInput,
+        input.signatureBySession,
+        session.sessionPubkey
+      )) {
+        throw new Error("invalid action signature");
+      }
+      return {
+        session,
+        action: input.action,
+        actionPayload: input.actionPayload
+      };
+    },
+    async ingestNegativeEvents(input) {
+      if (!config.rareApiClient) {
+        throw new Error("rareApiClient is required for event ingest");
+      }
+      let eventToken = input.eventToken;
+      if (!eventToken) {
+        if (!input.platformId || !input.kid || !input.privateKeyPem || !input.jti || !input.events) {
+          throw new Error("missing event signing input");
+        }
+        eventToken = await signPlatformEventToken({
+          platformId: input.platformId,
+          kid: input.kid,
+          privateKeyPem: input.privateKeyPem,
+          jti: input.jti,
+          events: input.events,
+          issuedAt: input.issuedAt,
+          expiresAt: input.expiresAt
+        });
+      }
+      const response = await config.rareApiClient.ingestPlatformEvents(eventToken);
+      return { eventToken, response };
+    }
+  };
+}
+var InMemoryChallengeStore = class {
+  challenges = /* @__PURE__ */ new Map();
+  async set(challenge) {
+    this.challenges.set(challenge.nonce, challenge);
+  }
+  async consume(nonce) {
+    const challenge = this.challenges.get(nonce) ?? null;
+    if (challenge) {
+      this.challenges.delete(nonce);
+    }
+    return challenge;
+  }
+};
+var InMemoryReplayStore = class {
+  seen = /* @__PURE__ */ new Map();
+  async has(key) {
+    this.cleanup();
+    return this.seen.has(key);
+  }
+  async put(key, expiresAt) {
+    this.seen.set(key, expiresAt);
+    this.cleanup();
+  }
+  cleanup() {
+    const now = nowTs();
+    for (const [key, expiresAt] of this.seen.entries()) {
+      if (expiresAt < now) {
+        this.seen.delete(key);
+      }
+    }
+  }
+};
+var InMemorySessionStore = class {
+  sessions = /* @__PURE__ */ new Map();
+  async save(session) {
+    this.sessions.set(session.sessionToken, session);
+  }
+  async get(sessionToken) {
+    const session = this.sessions.get(sessionToken) ?? null;
+    if (!session) {
+      return null;
+    }
+    if (session.expiresAt < nowTs()) {
+      this.sessions.delete(sessionToken);
+      return null;
+    }
+    return session;
+  }
+};
+export {
+  InMemoryChallengeStore,
+  InMemoryReplayStore,
+  InMemorySessionStore,
+  createRarePlatformKit
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@rare-id/platform-kit-web",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xsidfan/Rare.git",
+    "directory": "rare-platform-kit-ts/packages/platform-kit-web"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "dependencies": {
+    "@rare-id/platform-kit-client": "0.1.0",
+    "@rare-id/platform-kit-core": "0.1.0"
+  },
+  "devDependencies": {
+    "jose": "^6.0.8",
+    "tweetnacl": "^1.0.3"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "test": "vitest run",
+    "lint": "biome check src test",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}