@rare-id/platform-kit-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+type IdentityLevel = "L0" | "L1" | "L2";
+interface VerifiedTokenResult {
+    header: Record<string, unknown>;
+    payload: Record<string, unknown>;
+}
+interface RareJwks {
+    issuer?: string;
+    keys?: Array<Record<string, unknown>>;
+}
+interface RareJwk {
+    kid: string;
+    kty: "OKP";
+    crv: "Ed25519";
+    x: string;
+}
+type KeyResolver = (kid: string) => Promise<RareJwk | null> | RareJwk | null;
+declare function parseRareJwks(jwks: RareJwks): Record<string, RareJwk>;
+interface VerifyIdentityOptions {
+    keyResolver: KeyResolver;
+    expectedAud?: string;
+    currentTs?: number;
+    clockSkewSeconds?: number;
+}
+declare function verifyIdentityAttestation(token: string, options: VerifyIdentityOptions): Promise<VerifiedTokenResult>;
+interface VerifyDelegationOptions {
+    expectedAud: string;
+    requiredScope: string;
+    rareSignerPublicKeyB64?: string;
+    currentTs?: number;
+    clockSkewSeconds?: number;
+}
+declare function verifyDelegationToken(token: string, options: VerifyDelegationOptions): Promise<VerifiedTokenResult>;
+declare function buildAuthChallengePayload(input: {
+    aud: string;
+    nonce: string;
+    issuedAt: number;
+    expiresAt: number;
+}): string;
+declare function buildActionPayload(input: {
+    aud: string;
+    sessionToken: string;
+    action: string;
+    actionPayload: Record<string, unknown>;
+    nonce: string;
+    issuedAt: number;
+    expiresAt: number;
+}): string;
+declare function stableJson(value: unknown): string;
+declare function verifyDetached(input: string, signatureB64Url: string, publicKeyB64Url: string): boolean;
+interface RarePlatformEventItem {
+    event_id: string;
+    agent_id: string;
+    category: "spam" | "fraud" | "abuse" | "policy_violation";
+    severity: number;
+    outcome: string;
+    occurred_at: number;
+    evidence_hash?: string;
+}
+interface SignPlatformEventTokenInput {
+    platformId: string;
+    kid: string;
+    privateKeyPem: string;
+    jti: string;
+    events: RarePlatformEventItem[];
+    issuedAt?: number;
+    expiresAt?: number;
+}
+declare function signPlatformEventToken(input: SignPlatformEventTokenInput): Promise<string>;
+declare function nowTs(): number;
+declare function generateNonce(size?: number): string;
+declare function decodeBase64Url(value: string): Uint8Array;
+
+export { type IdentityLevel, type KeyResolver, type RareJwk, type RareJwks, type RarePlatformEventItem, type SignPlatformEventTokenInput, type VerifiedTokenResult, type VerifyDelegationOptions, type VerifyIdentityOptions, buildActionPayload, buildAuthChallengePayload, decodeBase64Url, generateNonce, nowTs, parseRareJwks, signPlatformEventToken, stableJson, verifyDelegationToken, verifyDetached, verifyIdentityAttestation };

package/dist/index.js

@@ -0,0 +1,252 @@
+// src/index.ts
+import { createHash, randomBytes } from "crypto";
+import {
+  SignJWT,
+  decodeJwt,
+  decodeProtectedHeader,
+  importJWK,
+  importPKCS8,
+  jwtVerify
+} from "jose";
+import nacl from "tweetnacl";
+function parseRareJwks(jwks) {
+  if (!Array.isArray(jwks.keys)) {
+    throw new Error("invalid JWKS payload");
+  }
+  const resolved = {};
+  for (const item of jwks.keys) {
+    if (!item || typeof item !== "object") {
+      continue;
+    }
+    const kid = item.kid;
+    const kty = item.kty;
+    const crv = item.crv;
+    const x = item.x;
+    if (typeof kid !== "string" || typeof x !== "string") {
+      continue;
+    }
+    if (kty !== "OKP" || crv !== "Ed25519") {
+      continue;
+    }
+    resolved[kid] = { kid, kty, crv, x };
+  }
+  return resolved;
+}
+async function verifyIdentityAttestation(token, options) {
+  const header = decodeProtectedHeader(token);
+  const typ = header.typ;
+  if (typ !== "rare.identity.public+jws" && typ !== "rare.identity.full+jws") {
+    throw new Error("invalid identity token typ");
+  }
+  const kid = header.kid;
+  if (typeof kid !== "string") {
+    throw new Error("missing key id");
+  }
+  const resolved = await options.keyResolver(kid);
+  if (!resolved) {
+    throw new Error("unknown identity key id");
+  }
+  const key = await importJWK(
+    {
+      kty: "OKP",
+      crv: "Ed25519",
+      x: resolved.x
+    },
+    "EdDSA"
+  );
+  const verified = await jwtVerify(token, key, {
+    algorithms: ["EdDSA"],
+    clockTolerance: options.clockSkewSeconds ?? 30
+  });
+  const payload = verified.payload;
+  if (payload.typ !== "rare.identity") {
+    throw new Error("invalid identity payload typ");
+  }
+  if (payload.ver !== 1) {
+    throw new Error("unsupported identity payload version");
+  }
+  if (payload.iss !== "rare") {
+    throw new Error("invalid identity issuer");
+  }
+  if (typ === "rare.identity.full+jws") {
+    if (!options.expectedAud) {
+      throw new Error("expected_aud required for full identity token");
+    }
+    if (payload.aud !== options.expectedAud) {
+      throw new Error("identity full token aud mismatch");
+    }
+  } else if (Object.prototype.hasOwnProperty.call(payload, "aud")) {
+    throw new Error("public identity token must not contain aud");
+  }
+  const level = payload.lvl;
+  if (level !== "L0" && level !== "L1" && level !== "L2") {
+    throw new Error("invalid identity level");
+  }
+  const now = options.currentTs ?? nowTs();
+  const iat = payload.iat;
+  const exp = payload.exp;
+  if (typeof iat !== "number" || typeof exp !== "number") {
+    throw new Error("identity timestamps must be integers");
+  }
+  const skew = options.clockSkewSeconds ?? 30;
+  if (iat - skew > now) {
+    throw new Error("identity token not yet valid");
+  }
+  if (exp + skew < now) {
+    throw new Error("identity token expired");
+  }
+  return { header, payload };
+}
+async function verifyDelegationToken(token, options) {
+  const header = decodeProtectedHeader(token);
+  if (header.typ !== "rare.delegation+jws") {
+    throw new Error("invalid delegation token typ");
+  }
+  const payload = decodeJwt(token);
+  if (payload.typ !== "rare.delegation") {
+    throw new Error("invalid delegation payload typ");
+  }
+  if (payload.ver !== 1) {
+    throw new Error("unsupported delegation payload version");
+  }
+  const agentId = payload.agent_id;
+  if (typeof agentId !== "string") {
+    throw new Error("delegation agent_id missing");
+  }
+  let key;
+  if (payload.iss === "rare-signer") {
+    if (payload.act !== "delegated_by_rare") {
+      throw new Error("rare signer delegation missing act");
+    }
+    if (!options.rareSignerPublicKeyB64) {
+      throw new Error("rare signer key unavailable");
+    }
+    key = await importJWK(
+      { kty: "OKP", crv: "Ed25519", x: options.rareSignerPublicKeyB64 },
+      "EdDSA"
+    );
+  } else if (payload.iss === "agent") {
+    if (payload.act !== "delegated_by_agent") {
+      throw new Error("agent delegation missing act");
+    }
+    key = await importJWK({ kty: "OKP", crv: "Ed25519", x: agentId }, "EdDSA");
+  } else {
+    throw new Error("unsupported delegation issuer");
+  }
+  const verified = await jwtVerify(token, key, {
+    algorithms: ["EdDSA"],
+    clockTolerance: options.clockSkewSeconds ?? 30
+  });
+  const verifiedPayload = verified.payload;
+  if (verifiedPayload.aud !== options.expectedAud) {
+    throw new Error("delegation aud mismatch");
+  }
+  const scope = verifiedPayload.scope;
+  if (!Array.isArray(scope) || !scope.includes(options.requiredScope)) {
+    throw new Error("delegation scope missing required action");
+  }
+  if (typeof verifiedPayload.session_pubkey !== "string") {
+    throw new Error("delegation missing session_pubkey");
+  }
+  const now = options.currentTs ?? nowTs();
+  const iat = verifiedPayload.iat;
+  const exp = verifiedPayload.exp;
+  const jti = verifiedPayload.jti;
+  if (typeof iat !== "number" || typeof exp !== "number") {
+    throw new Error("delegation timestamps must be integers");
+  }
+  if (typeof jti !== "string" || jti.trim().length === 0) {
+    throw new Error("delegation jti missing");
+  }
+  const skew = options.clockSkewSeconds ?? 30;
+  if (iat - skew > now) {
+    throw new Error("delegation token not yet valid");
+  }
+  if (exp + skew < now) {
+    throw new Error("delegation token expired");
+  }
+  return {
+    header,
+    payload: verifiedPayload
+  };
+}
+function buildAuthChallengePayload(input) {
+  return `rare-auth-v1:${input.aud}:${input.nonce}:${input.issuedAt}:${input.expiresAt}`;
+}
+function buildActionPayload(input) {
+  const bodyHash = sha256Hex(stableJson(input.actionPayload));
+  return `rare-act-v1:${input.aud}:${input.sessionToken}:${input.action}:${bodyHash}:${input.nonce}:${input.issuedAt}:${input.expiresAt}`;
+}
+function stableJson(value) {
+  return JSON.stringify(sortJson(value));
+}
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortJson(item));
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value).sort(
+      ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+    );
+    const output = {};
+    for (const [k, v] of entries) {
+      output[k] = sortJson(v);
+    }
+    return output;
+  }
+  return value;
+}
+function sha256Hex(input) {
+  const bytes = new TextEncoder().encode(input);
+  return createHash("sha256").update(bytes).digest("hex");
+}
+function verifyDetached(input, signatureB64Url, publicKeyB64Url) {
+  const message = new TextEncoder().encode(input);
+  const signature = decodeBase64Url(signatureB64Url);
+  const publicKey = decodeBase64Url(publicKeyB64Url);
+  return nacl.sign.detached.verify(message, signature, publicKey);
+}
+async function signPlatformEventToken(input) {
+  const issuedAt = input.issuedAt ?? nowTs();
+  const expiresAt = input.expiresAt ?? issuedAt + 300;
+  const key = await importPKCS8(input.privateKeyPem, "EdDSA");
+  const payload = {
+    typ: "rare.platform-event",
+    ver: 1,
+    iss: input.platformId,
+    aud: "rare.identity-library",
+    iat: issuedAt,
+    exp: expiresAt,
+    jti: input.jti,
+    events: input.events
+  };
+  return new SignJWT(payload).setProtectedHeader({
+    alg: "EdDSA",
+    typ: "rare.platform-event+jws",
+    kid: input.kid
+  }).sign(key);
+}
+function nowTs() {
+  return Math.floor(Date.now() / 1e3);
+}
+function generateNonce(size = 18) {
+  return randomBytes(size).toString("base64url");
+}
+function decodeBase64Url(value) {
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = normalized.length % 4 === 0 ? "" : "=".repeat(4 - normalized.length % 4);
+  return new Uint8Array(Buffer.from(normalized + pad, "base64"));
+}
+export {
+  buildActionPayload,
+  buildAuthChallengePayload,
+  decodeBase64Url,
+  generateNonce,
+  nowTs,
+  parseRareJwks,
+  signPlatformEventToken,
+  stableJson,
+  verifyDelegationToken,
+  verifyDetached,
+  verifyIdentityAttestation
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@rare-id/platform-kit-core",
+  "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-core"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "dependencies": {
+    "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"
+  }
+}