@sneekin/sdk 0.3.2 → 1.1.0

package/dist/verify/index.cjs

@@ -0,0 +1,471 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/verify/index.ts
+var verify_exports = {};
+__export(verify_exports, {
+  SneekApiError: () => SneekApiError,
+  SneekClient: () => SneekClient,
+  SneekVerifyHandler: () => SneekVerifyHandler,
+  deriveKeys: () => deriveKeys
+});
+module.exports = __toCommonJS(verify_exports);
+
+// src/core/client.ts
+var SneekApiError = class extends Error {
+  constructor(status, type, title, detail) {
+    super(`${title}${detail ? `: ${detail}` : ""} [${status}]`);
+    this.status = status;
+    this.type = type;
+    this.title = title;
+    this.detail = detail;
+    this.name = "SneekApiError";
+  }
+  status;
+  type;
+  title;
+  detail;
+};
+var SneekClient = class {
+  apiUrl;
+  apiKey;
+  fetchImpl;
+  maxRetries;
+  retryBaseMs;
+  constructor(options) {
+    if (!options.apiUrl) throw new Error("apiUrl is required");
+    if (!options.apiKey) throw new Error("apiKey is required");
+    this.apiUrl = options.apiUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.fetchImpl = options.fetch ?? fetch;
+    this.maxRetries = options.maxRetries ?? 2;
+    this.retryBaseMs = options.retryBaseMs ?? 200;
+  }
+  async request(method, path, body, extraHeaders) {
+    const raw = body === void 0 ? void 0 : JSON.stringify(body);
+    let attempt = 0;
+    let lastError;
+    for (; ; ) {
+      try {
+        const response = await this.fetchImpl(`${this.apiUrl}${path}`, {
+          method,
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${this.apiKey}`,
+            ...extraHeaders ?? {}
+          },
+          body: raw
+        });
+        const text = await response.text();
+        const parsed = text ? parseJson(text) : void 0;
+        if (!response.ok) {
+          const problem = asProblem(parsed);
+          const error = new SneekApiError(
+            response.status,
+            problem.type ?? "about:blank",
+            problem.title ?? response.statusText,
+            problem.detail
+          );
+          if (response.status >= 500 && attempt < this.maxRetries) {
+            lastError = error;
+            await this.backoff(attempt++);
+            continue;
+          }
+          throw error;
+        }
+        return parsed;
+      } catch (error) {
+        if (error instanceof SneekApiError) throw error;
+        if (attempt < this.maxRetries) {
+          lastError = error;
+          await this.backoff(attempt++);
+          continue;
+        }
+        throw lastError ?? error;
+      }
+    }
+  }
+  backoff(attempt) {
+    return new Promise((resolve) => setTimeout(resolve, this.retryBaseMs * 2 ** attempt));
+  }
+};
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function asProblem(value) {
+  if (typeof value !== "object" || value === null) return {};
+  const problem = value;
+  return {
+    type: typeof problem.type === "string" ? problem.type : void 0,
+    title: typeof problem.title === "string" ? problem.title : void 0,
+    detail: typeof problem.detail === "string" ? problem.detail : void 0
+  };
+}
+
+// src/core/derive-keys.ts
+var import_node_crypto = require("crypto");
+var KEY_LABELS = {
+  qrSigningKey: "sneek-qr-v1",
+  webhookSigningKey: "sneek-webhook-v1",
+  proofKey: "sneek-proof-v1"
+};
+function deriveKeys(apiKey) {
+  if (typeof apiKey !== "string" || apiKey.length === 0) {
+    throw new TypeError("apiKey must be a nonempty string");
+  }
+  const inputKeyMaterial = Buffer.from(apiKey, "utf8");
+  const derive = (label) => Buffer.from(
+    (0, import_node_crypto.hkdfSync)("sha256", inputKeyMaterial, Buffer.alloc(0), label, 32)
+  );
+  return {
+    qrSigningKey: derive(KEY_LABELS.qrSigningKey),
+    webhookSigningKey: derive(KEY_LABELS.webhookSigningKey),
+    proofKey: derive(KEY_LABELS.proofKey)
+  };
+}
+
+// src/verify/handler.ts
+var import_node_crypto2 = require("crypto");
+var import_jose = require("jose");
+
+// src/verify/auth-schema.ts
+var import_zod = require("zod");
+var BrowserProof = import_zod.z.string().min(1).max(4096);
+var VerificationId = import_zod.z.string().uuid();
+var QrReference = import_zod.z.string().regex(/^[0-9a-f]{64}$/);
+var ConfigActionSchema = import_zod.z.object({ action: import_zod.z.literal("config") }).strict();
+var RequestActionSchema = import_zod.z.object({
+  action: import_zod.z.literal("request"),
+  identifier: import_zod.z.string().min(3).max(254)
+}).strict();
+var SwitchActionSchema = import_zod.z.object({
+  action: import_zod.z.literal("switch"),
+  requestId: VerificationId,
+  channel: import_zod.z.enum(["sms", "whatsapp", "email", "push"]),
+  proof: BrowserProof
+}).strict();
+var VerifyCodeActionSchema = import_zod.z.object({
+  action: import_zod.z.literal("verify"),
+  requestId: VerificationId,
+  code: import_zod.z.string().min(4).max(12).optional(),
+  proof: BrowserProof
+}).strict();
+var VerifyQrActionSchema = import_zod.z.object({
+  action: import_zod.z.literal("verify"),
+  requestId: VerificationId,
+  ref: QrReference,
+  bindingProof: BrowserProof
+}).strict();
+var CreateQrActionSchema = import_zod.z.object({ action: import_zod.z.literal("create") }).strict();
+var QrStatusActionSchema = import_zod.z.object({
+  action: import_zod.z.literal("status"),
+  ref: QrReference,
+  bindingProof: BrowserProof
+}).strict();
+var QrWebhookEventSchema = import_zod.z.object({
+  type: import_zod.z.literal("qr.approved"),
+  applicationId: import_zod.z.string().uuid(),
+  ref: QrReference,
+  requestId: VerificationId
+}).strict();
+var SneekVerifyActionSchema = import_zod.z.union([
+  ConfigActionSchema,
+  RequestActionSchema,
+  SwitchActionSchema,
+  VerifyCodeActionSchema,
+  VerifyQrActionSchema,
+  CreateQrActionSchema,
+  QrStatusActionSchema
+]);
+
+// src/verify/handler.ts
+var SneekVerifyHandler = class {
+  client;
+  allowedOrigins;
+  keys;
+  approvalStore;
+  onVerified;
+  jwksByIssuer = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.client = new SneekClient({
+      apiUrl: options.apiUrl,
+      apiKey: options.apiKey,
+      fetch: options.fetch
+    });
+    this.allowedOrigins = new Set(options.allowedOrigins.map((origin) => new URL(origin).origin));
+    this.keys = deriveKeys(options.apiKey);
+    this.approvalStore = options.approvalStore;
+    this.onVerified = options.onVerified;
+  }
+  async handle(request) {
+    const origin = this.getAllowedOrigin(request);
+    if (request.method !== "POST" || !origin) {
+      return jsonResponse({ error: "Forbidden" }, 403);
+    }
+    let body;
+    try {
+      body = await request.json();
+    } catch {
+      return jsonResponse({ error: "Invalid JSON body" }, 400);
+    }
+    const action = SneekVerifyActionSchema.safeParse(body);
+    if (!action.success) return jsonResponse({ error: "Invalid auth action" }, 400);
+    switch (action.data.action) {
+      case "config":
+        return this.config(origin);
+      case "request":
+        return this.startVerification(action.data.identifier, origin);
+      case "switch":
+        return this.switchVerification(action.data, origin);
+      case "verify":
+        return this.verify(action.data, origin);
+      case "create":
+        return this.createQr(origin);
+      case "status":
+        return this.qrStatus(action.data.ref, action.data.bindingProof, origin);
+    }
+  }
+  async handleWebhook(request) {
+    if (request.method !== "POST") return jsonResponse({ error: "Invalid webhook" }, 405);
+    const contentLength = Number(request.headers.get("content-length") ?? 0);
+    if (contentLength > 16384) return jsonResponse({ error: "Invalid webhook" }, 413);
+    const signature = request.headers.get("sneek-signature") ?? "";
+    const match = /^t=(\d{1,12}),v1=([A-Za-z0-9_-]{43})$/.exec(signature);
+    if (!match) return jsonResponse({ error: "Invalid webhook signature" }, 401);
+    const timestamp = Number(match[1]);
+    const now = Math.floor(Date.now() / 1e3);
+    if (!Number.isSafeInteger(timestamp) || Math.abs(now - timestamp) > 300) {
+      return jsonResponse({ error: "Expired webhook signature" }, 401);
+    }
+    let body;
+    try {
+      const text = await request.text();
+      if (Buffer.byteLength(text, "utf8") > 16384) return jsonResponse({ error: "Invalid webhook" }, 413);
+      body = JSON.parse(text);
+    } catch {
+      return jsonResponse({ error: "Invalid webhook body" }, 400);
+    }
+    const event = QrWebhookEventSchema.safeParse(body);
+    if (!event.success || !this.isValidWebhookSignature(timestamp, event.data, match[2])) {
+      return jsonResponse({ error: "Invalid webhook signature" }, 401);
+    }
+    const session = await this.approvalStore.readQrSession(event.data.ref);
+    if (!session || session.applicationId !== event.data.applicationId || session.expiresAt <= Date.now()) {
+      return jsonResponse({ error: "Unknown or expired QR approval" }, 401);
+    }
+    const recorded = await this.approvalStore.recordQrApproval(event.data, Date.now());
+    if (recorded === "missing") return jsonResponse({ error: "Unknown or expired QR approval" }, 401);
+    return new Response(null, { status: 204 });
+  }
+  getAllowedOrigin(request) {
+    const origin = request.headers.get("origin");
+    if (!origin || origin === "null") return null;
+    try {
+      const parsed = new URL(origin);
+      return parsed.origin === origin && this.allowedOrigins.has(parsed.origin) && new URL(request.url).origin === parsed.origin ? parsed.origin : null;
+    } catch {
+      return null;
+    }
+  }
+  async config(origin) {
+    const partner = await this.client.request("GET", "/api/verify/qr/partner-config");
+    const enabled = partner.origins.includes(origin);
+    return jsonResponse({
+      origin,
+      enabled,
+      ...enabled ? { applicationId: partner.applicationId } : {}
+    }, 200);
+  }
+  async startVerification(identifier, origin) {
+    const result = await this.client.request("POST", "/api/verify", { identifier });
+    return this.startResponse(result, origin);
+  }
+  async switchVerification(action, origin) {
+    if (!this.isValidProof(action.proof, action.requestId, origin)) {
+      return jsonResponse({ error: "Invalid or expired browser proof" }, 403);
+    }
+    const result = await this.client.request(
+      "POST",
+      `/api/verify/${action.requestId}/switch`,
+      { channel: action.channel }
+    );
+    return this.startResponse(result, origin);
+  }
+  async verify(action, origin) {
+    if ("proof" in action) {
+      if (!this.isValidProof(action.proof, action.requestId, origin)) {
+        return jsonResponse({ error: "Invalid or expired browser proof" }, 403);
+      }
+    } else {
+      const session = await this.qrSession(action.ref, action.bindingProof, origin);
+      if (!session || session.requestId !== action.requestId) {
+        return jsonResponse({ error: "QR approval is not bound to this browser" }, 403);
+      }
+    }
+    const body = "proof" in action && action.code !== void 0 ? { code: action.code } : {};
+    const result = await this.client.request(
+      "POST",
+      `/api/verify/${action.requestId}/check`,
+      body
+    );
+    if (result.status !== "verified") {
+      return jsonResponse({ error: "This verification requires additional account setup" }, 403);
+    }
+    const partner = await this.client.request("GET", "/api/verify/qr/partner-config");
+    let payload;
+    try {
+      const jwks = this.jwksByIssuer.get(partner.issuer) ?? (0, import_jose.createRemoteJWKSet)(new URL("/oauth/jwks", partner.issuer));
+      this.jwksByIssuer.set(partner.issuer, jwks);
+      ({ payload } = await (0, import_jose.jwtVerify)(result.idToken, jwks, {
+        issuer: partner.issuer,
+        audience: partner.clientId
+      }));
+    } catch {
+      return jsonResponse({ error: "Sneek verification token is invalid" }, 502);
+    }
+    const claims = this.verifiedClaims(payload, action.requestId);
+    if (!claims) return jsonResponse({ error: "Sneek verification token is invalid" }, 502);
+    if (!await this.approvalStore.claimJti(claims.jti, claims.expiresAt * 1e3)) {
+      return jsonResponse({ error: "Sneek verification token was already used" }, 401);
+    }
+    const verified = {
+      identifier: claims.identifier,
+      kind: claims.kind,
+      method: claims.method,
+      verifiedAt: new Date(claims.verifiedAt * 1e3).toISOString(),
+      requestId: action.requestId
+    };
+    await this.onVerified(verified);
+    return jsonResponse({ status: "verified", ...verified }, 200);
+  }
+  verifiedClaims(payload, requestId) {
+    const requestClaim = payload.verification_request_id;
+    const issuedAt = payload.auth_time ?? payload.iat;
+    const methods = payload.amr;
+    const email = payload.email;
+    const mobile = payload.phone_number;
+    const hasEmail = typeof email === "string" && payload.email_verified === true;
+    const hasMobile = typeof mobile === "string" && payload.phone_number_verified === true;
+    if (payload.sub !== requestId || requestClaim !== requestId || typeof payload.exp !== "number" || typeof issuedAt !== "number" || typeof payload.jti !== "string" || !payload.jti || !Array.isArray(methods) || methods.length === 0 || methods.some((method) => typeof method !== "string" || !method) || hasEmail === hasMobile) return null;
+    return {
+      identifier: hasEmail ? email : mobile,
+      kind: hasEmail ? "email" : "mobile",
+      method: methods.join(" "),
+      verifiedAt: issuedAt,
+      expiresAt: payload.exp,
+      jti: payload.jti
+    };
+  }
+  startResponse(result, origin) {
+    const expiresAt = Date.parse(result.expiresAt);
+    if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) {
+      return jsonResponse({ error: "Verification response is invalid or expired" }, 502);
+    }
+    return jsonResponse({
+      requestId: result.id,
+      channel: result.channel,
+      maskedIdentifier: result.maskedIdentifier,
+      expiresAt: result.expiresAt,
+      ...result.instruction ? { instruction: result.instruction } : {},
+      ...result.alternatives ? { alternatives: result.alternatives } : {},
+      ...result.challengeNumber ? { challengeNumber: result.challengeNumber } : {},
+      proof: this.createProof(result.id, origin, expiresAt)
+    }, 200);
+  }
+  createProof(requestId, origin, expiresAt) {
+    const payload = Buffer.from(JSON.stringify({
+      requestId,
+      origin,
+      expiresAt,
+      nonce: (0, import_node_crypto2.randomBytes)(16).toString("base64url")
+    })).toString("base64url");
+    const signature = (0, import_node_crypto2.createHmac)("sha256", this.keys.proofKey).update(payload).digest("base64url");
+    return `${payload}.${signature}`;
+  }
+  isValidProof(proof, requestId, origin) {
+    const [payload, signature, ...extra] = proof.split(".");
+    if (!payload || !signature || extra.length > 0) return false;
+    const expected = (0, import_node_crypto2.createHmac)("sha256", this.keys.proofKey).update(payload).digest();
+    const actual = Buffer.from(signature, "base64url");
+    if (actual.length !== expected.length || !(0, import_node_crypto2.timingSafeEqual)(expected, actual)) return false;
+    try {
+      const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+      return decoded.requestId === requestId && decoded.origin === origin && typeof decoded.expiresAt === "number" && decoded.expiresAt > Date.now() && typeof decoded.nonce === "string";
+    } catch {
+      return false;
+    }
+  }
+  async createQr(origin) {
+    const partner = await this.partnerConfig();
+    if (!partner.origins.includes(origin)) return jsonResponse({ error: "Origin is not registered for QR verification" }, 403);
+    const nonce = (0, import_node_crypto2.randomBytes)(32).toString("hex");
+    const ref = (0, import_node_crypto2.createHash)("sha256").update(nonce).digest("hex");
+    const issuedAt = Math.floor(Date.now() / 1e3);
+    const expiresAt = (issuedAt + partner.qrTtlSeconds) * 1e3;
+    const bindingProof = (0, import_node_crypto2.randomBytes)(32).toString("base64url");
+    const signature = (0, import_node_crypto2.createHmac)("sha256", this.keys.qrSigningKey).update(["sneek-qr-v1", partner.applicationId, nonce, origin, String(issuedAt)].join("\n")).digest().subarray(0, 16).toString("base64url");
+    await this.approvalStore.createQrSession({
+      ref,
+      applicationId: partner.applicationId,
+      origin,
+      bindingProofHash: this.hash(bindingProof),
+      expiresAt
+    });
+    return jsonResponse({ ref, nonce, issuedAt, expiresAt, signature, bindingProof }, 200);
+  }
+  async qrStatus(ref, bindingProof, origin) {
+    const session = await this.qrSession(ref, bindingProof, origin);
+    if (!session) return jsonResponse({ error: "QR approval is not bound to this browser" }, 403);
+    if (!session.requestId) return jsonResponse({ status: "pending" }, 200);
+    return jsonResponse({ status: "approved", requestId: session.requestId }, 200);
+  }
+  async qrSession(ref, bindingProof, origin) {
+    const session = await this.approvalStore.readQrSession(ref);
+    if (!session || session.origin !== origin || session.expiresAt <= Date.now()) return null;
+    const expected = Buffer.from(session.bindingProofHash, "hex");
+    const actual = Buffer.from(this.hash(bindingProof), "hex");
+    if (expected.length !== actual.length || !(0, import_node_crypto2.timingSafeEqual)(expected, actual)) return null;
+    return session;
+  }
+  async partnerConfig() {
+    return this.client.request("GET", "/api/verify/qr/partner-config");
+  }
+  isValidWebhookSignature(timestamp, event, signature) {
+    const expected = (0, import_node_crypto2.createHmac)("sha256", this.keys.webhookSigningKey).update(["sneek-webhook-v1", String(timestamp), event.type, event.applicationId, event.ref, event.requestId].join("\n")).digest();
+    const actual = Buffer.from(signature, "base64url");
+    return actual.length === expected.length && (0, import_node_crypto2.timingSafeEqual)(expected, actual);
+  }
+  hash(value) {
+    return (0, import_node_crypto2.createHash)("sha256").update(value).digest("hex");
+  }
+};
+function jsonResponse(body, status) {
+  return Response.json(body, { status });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SneekApiError,
+  SneekClient,
+  SneekVerifyHandler,
+  deriveKeys
+});

package/dist/verify/index.d.ts

@@ -0,0 +1,3 @@
+export * from '../core/index.js';
+export * from './approval-store.js';
+export * from './handler.js';